An OPTION statement changes the way Axbasic executes a script. OPTION can be followed by several different keywords, a few of which you've seen already. We'll list all of them here.
Before executing a script, Axbasic checks for any OPTION statements. An OPTION statement applies to the whole script, even if it actually occurs right at the end of the script. However, there is no good reason not to put all your OPTIONs right at the top, because that is where human readers are expecting to find them.
You'll see these messages when Axbasic starts and finishes executing a script:
AXBASIC: Executing 'test'
AXBASIC: Execution of 'test' complete
You can hide these messages by using OPTION SILENT.
Any error or debug messages will still be displayed. The only way to turn them off is to fix your script.
Every statement must start with a keyword, so if you want to set a variable's value, you must do it using a LET statement.
LET a$ = "hello"
Typing LET is rather a lot of work, though, and in any case most programmers are used to writing a simple a$ = "hello". When you specify OPTION NOLET, Axbasic will let you miss out LETs altogether.
OPTION NOLET
a$ = "hello"
LET is always optional in Axbasic scripts with line numbers (see Section 18).
As you know, keywords like PAUSE won't work unless the script is run as a task. You can avoid any unexpected surprises by telling Axbasic that the script must only be run as a task.
OPTION NEEDTASK
PRINT "Hello..."
PAUSE 3
PRINT "...world!"
END
From time to time, Axbasic undergoes small changes and improvements. If you're making use of some exciting new feature, you can tell Axbasic not to run the script on an older version of Axmud.
The current version of Axbasic, at the time of writing, is 1.002:
! Don't run on older versions of Axmud
OPTION REQUIRE 1.002
The earliest version of Axbasic was 1.0, so using this line is the same as omitting OPTION REQUIRE altogether:
! Run on all versions of Axmud
OPTION REQUIRE 1.0
By the way, the Version () function returns the current Axbasic version.
PRINT Version ()
It's just too easy to mis-type a variable like string$, in which case your script won't work as intended. Mistakes of this kind are notoriously difficult to diagnose.
The solution is to use OPTION TYPO, which tells Axbasic that all variables will be declared (in a GLOBAL or LOCAL statement) before they are used.
OPTION TYPO
GLOBAL name$, address$, phone_number
Now, if you type the following line (in which address$ has been misspelled), you'll get an error with a line number. Because you know exactly where the problem is, it won't take long to spot the typo.
PRINT adress$
OPTION TYPO is strongly recommended for all of your Axbasic scripts.
Client commands are normally typed in Axmud's main window, but any part of the code can execute a client command. (Internally, this is known as a pseudo command.)
In Axbasic, we use a CLIENT statement.
CLIENT "starttask compass"
Nearly every client command displays a confirmation (success) message in the main window. If there's a problem, an error message is displayed there instead. We can change what happens as a result of the CLIENT statement in any of the following ways.
OPTION PSEUDO "show_all"
This shows all system messages generated by the client command, as if the user had typed it themselves.
OPTION PSEUDO "hide_complete"
This shows any error messages in the main window, but not the confirmation message. (This is the default behaviour if no OPTION PSEUDO statement is used.)
OPTION PSEUDO "hide_system"
This hides any error messages, as well as any confirmation message.
OPTION PSEUDO "win_error"
This displays a confirmation message in the main window, but any error messages appear in a dialogue (popup) window.
OPTION PSEUDO "win_only"
This displays both confirmation and error messages in a dialogue (popup) window.
OPTION REDIRECT
Axbasic scripts can create their own task window. A WRITEWIN statement display text in that task window. However, if the task window isn't open, nothing is displayed.
OPTION REDIRECT redirects text into the main window, if the task window has been closed for some reason.
OPTION PERSIST
Interfaces can be created with an ADDTRIG, ADDALIAS, ADDMACRO, ADDTIMER or ADDHOOK statement. Normally, those interfaces are destroyed as soon as the script stops running, but OPTION PERSIST prevents that destruction.
OPTION ANGLE DEGREES
Axbasic's trignometric functions like Sin () and Cos () expect angles measured in radians. If you'd prefer them to expect angles measured in degrees, you can use OPTION ANGLE DEGREES.
OPTION ANGLE RADIANS
This statement is useful for clarifying to any humans reading your code that you'll be using radians, not degrees.
An Axbasic script can be run using a client command. ;runscript runs the test.bas script, and ;runscript wumpus runs the wumpus.bas script.
When you try to run a script, Axbasic looks for a file in the default directory (folder), as we described in Section 2.
You can find the location of this directory using the ;listdirectory command. On a Linux system, the output will look something like this:
List of Axbasic directories
0 /home/myname/axmud-data/data/scripts
Client ';listdirectory' : Directory list displayed (found 1 directory)
You can add more directories to that list, if you want to. If the right file isn't found in the first directory, Axbasic will look in the second, then in the third (and so on).
To add a directory to the list, use the ;adddirectory command.
;addirectory
If you already know the full directory path, you can specify it. (We enclose the path inside diamond brackets, just in case it contains space characters.)
;addirectory <home/myname/mydir>
The ;listdirectory command gives each directory a number; you'll need that number if you want to remove a directory from the list.
;deletedirectory 2
An alternative approach is to specify the full file path every time you run the script.
;runscript -p <home/myname/mydir/myscript.bas>
When you run a script as a task, the ;runscripttask command provides a number of options, two of which might be useful to you.
Firstly, an Axbasic script runs from beginning to end. A script that runs on a continuous loop would run indefinitely, meaning that Axmud itself would appear to freeze.
In previous Sections you learned to use PAUSE statements. When the script pauses, control is returned to Axmud for a short time. In this way, both Axmud and Axbasic can run code (almost) simultaneously.
In fact, the Script task pauses automatically every 100 steps (which is roughly equivalent to 100 Axbasic statements). This prevents Axmud from freezing up if you've forgotten to add PAUSE statements to your script. You can change this setting, if you like.
! Execute 1000 statements before each pause
;runscripttask wumpus -m 1000
If you use the number 0, the Script task will only pause when it executes a PAUSE (or SLEEP) statement.
! Execute infinite statements before each pause
;runscripttask wumpus -m 0
Secondly, Axbasic can display output in either the main window or in a task window. A task window can be opened with the OPENWIN statement, but that's not much help if you're trying to run a BASIC programme written in the 1960s.
This is how to force the Script task to open a window and to display all of its output there:
;runscripttask wumpus -w
The switches can be combined and used in any order (but the script name must come first):
;runscripttask wumpus -m 200 -w
;runscripttask wumpus -w -m 200
There are two more client commands to mention. ;editscript opens the script in a text editor, and ;checkscript checks the script for syntax errors, but doesn't actually run it.
;editscript wumpus
;checkscript wumpus
In both cases, if you don't specify a script, the test.bas script it used.