Variables (Also see Lists, Notes on Variable Assignment.)

Function names shown in green are actually macros. See User-Defined Functions.

@asn[$name,@n]
Assigns value @n to local variable with specified name, and returns new value.
Example: @asn["x",12] is the same as @x=12 or $name="x"; @asn[$name,12].

$asn[$name,$s]
Assigns $s to specified local variable, and returns new value.

@gasn[$name,@n]
Assign value @n to global variable with specified $name, and returns new value
Example: @gasn["x",12] is the same as @@x=12 or $name="x"; @gasn[$name,12].

$gasn[$name,$s]
Assigns $s to specified global variable, and returns new value.

@var[$name]
Returns the value of local numeric variable with specified name, if present; otherwise returns the value of global variable with specified name. If variable isn't found, an error occurs.

$var[$name]
Returns the value of local variable with specified name, if present; otherwise returns the value of global variable with specified name.

@v_[$name]
Returns the value of local numeric variable with specified name, if present; otherwise returns the value of global variable with specified name. If variable isn't found, a 0 is returned.

$v_[$name]
Returns the value of local string variable with specified name, if present; otherwise returns the value of global variable with specified name. If variable isn't found, an empty string is returned.

@gvar[$name]
Returns the value of global variable with specified name, if present; otherwise causes an error message.

$gvar[$name]
Returns the value of global variable with specified name, if present; otherwise causes an error message.

@isvar[$varname]
Returns true if numeric variable with specified name exists.

@isstrvar[$varname]
Returns true if string variable with specified name exists

@isvar_[$varname]
Returns true if local numeric variable with specified name exists.

@isstrvar_[$varname]
Returns true if local string variable with specified name exists

@isgvar[$varname]
Returns true if global numeric variable with specified name exists.

@isstrgvar[$varname]
Returns true if global string variable with specified name exists

@varcount
Returns the count of all global variables .

@varncount[$prefix]
Returns a count of all variables whose name starts with the specified prefix. The prefix should include the "$" or "@". For example, @varncount["@"] returns a count of all numeric variables. Note that @varncount["$Stuff:"] is equivalent to @itemcount["Stuff"] and @varncount["@Stuff:"] is equivalent to @itemcount_["Stuff"]
Returns the count of global variables with specified prefix; if $prefix is an empty string, then the count of all variables is returned. Use prefix "@" for a count of all numeric global variables or "$" for a count of all string global variables.

$var_[@index]
Returns the value of the variable with the specified index. Note this means the actual index, base 0, in the "heap" of all global variables, not the number suffix added to variable names in lists. If the variable is numeric, the string equivalent is returned.

$varname_[@index]
Returns the name (including the "$" or "@") of the variable with the specified index. Note this means the actual index, base 0, in the "heap" of all global variables, not the number suffix added to variable names in lists.

$pick[$prompt,$prefix]
Displays a list of all variables with the specified prefix, prompting the user to make a selection, and returns the value of the user's choice from that list.

$pickv[$prompt,$prefix]
Displays a list of all variables with the specified prefix, prompting the user to make a selection, and returns the name of the variable chosen from that list.
 

User-created variable lists ("VLists")
In Magsbot 4.1, users can create their own variable lists to store data. Don't confuse user-created variable lists with the lists that you create and manipulate using the various list commands and functions like ENLIST, SETITEM, @litem, etc.  Rather, user-created variable lists are similar to the global variable list (viewed by pressing Ctrl-F3) or local variable lists that are created automatically within custom buttons or behavior table rows, except that user-created variable lists are maintained separately and can be used for whatever purpose you might wish.  Generally they are intended to be used like structs in C, to conveniently group a number of variables together in one item.

To create a variable list, simply call the @vlist function, which will return a handle to an empty list. You can then use the handle with the STORE and STORE_ commands to add or update items to the list (similarly to how the ASN and ASNS commands work with the local variable list, or how the GLOBAL and GLOBALSTR commands work with the global variable list), and use @lvar, $lvar and other such functions (listed below) to retrieve the data. Free the list using the FREEVLIST command.

Example of using a user-created variable list.

@@mylist=@vlist;  Create the list and assign the handle to a global variable for later use.

 store @mylist MyStrVariable="This will be stored in a variable within the list!";    Store a string variable in the list.

store_ @mylist MyNumVariable=1234;  Store a numeric variable in the list.

...

$x=$lv_[@mylist,MyStrVariable];  Retrieve a string variable from the list.

@x=@lv_[@mylist,MynumVariable];  Retrieve a numeric variable from the list.

report $fmt["mylist contained MyNumVariable=%s and MyStrVariable=%s",@x,$x];

FREEVLIST @mylist; When you're done with the list, free it.

@vlist
Creates a new variable list and returns a handle to it.

@lasn[@list,$varname,@value]
Assigns a numeric variable to a user-created variable list.  Also see the STORE_ command.

$lasn[@list,$varname,$value]
Assigns a string variable to a user-created variable list.  Also see the STORE command.

@lvar[@list,$varname]
Returns a numeric value from a user-created variable list. An error occurs if either the list or the variable doesn't exist.

@lv_[@list,$varname]
Returns a numeric value from a user-created variable list. Returns 0 if either the list or the variable doesn't exist.

$lvar[@list,$varname]
Returns a string value from a user-created variable list.  An error occurs if either the list or the variable doesn't exist.

$lv_[@list,$varname]
Returns a string value from a user-created variable list. Returns an empty string if either the list or the variable doesn't exist.

@lvindex[@list,$value]
Returns the index in a vlist of a string variable according to its value, or -1 if not found.

@lvindex_[@list,@value]
Returns the index in a vlist of a numeric variable according to its value, or -1 if not found.

@vlistcount
Returns the number of user-created variable lists in memory.

@vlist_[@i]
Returns the handle for a vlist by index. Use @vlistcount to find the number of vlists in memory.

$vlistname[@list]
Returns the name that was assigned to the vlist using the VLISTNAME command.

$lv_[@list,$varname]
Returns a string value from a user-created variable list.  Returns an empty string ""  if either the list or the variable doesn't exist.

$lvar_[@list,@index]
Returns the value of a numeric or string variable from a user-created variable list, in string form, by index (not item number...user-created variable lists don't have item numbers).  An error occurs if either the list or the variable doesn't exist. Similar to  $var_.

$lvarname_[@list,@index]
Returns the name (including the "$" or "@") of the variable with the specified index. Note this means the actual index, base 0, in the vlist, not the number suffix added to variable names in global lists.

@isvlist[@list]
Returns 1 if the user-created variable list exists or 0 if it doesn't.

@islvar[@list,$vname]
Returns 1 if the user-created variable list and variable exist or 0 if either doesn't.

@isstrlvar[@list,$vname]
Returns 1 if the user-created variable list and variable exist or 0 if either doesn't.

@lvarcount
Returns the count of all variables in a user-created variable list..

@lvarncount[$prefix]
Returns a count of all variables in a user-created variable list, whose name starts with the specified prefix. (See @varncount.)

<>$vlpick[@vlist,$prompt]
$vlpicks[@vlist,$prompt,$delim]
$vlpickv[@vlist,$prompt]
$vlpickvs[@vlist,$prompt,$delim]
These are similar to $pick and $pickv, except these are used with vlists instead of global lists. Each displays a vlist and allows the user to select an item or items from the list.  $vlpick returns the value of the selected variable; $vlpicks returns the values of several selected variables separated by the specified delimiter; $vlpickv returns the name of the selected variable; $vlpickvs returns the names of several selected variables separated by the specified delimiter.<>
<>
$objdatafromvlist[@objtype,@vlist]
@objdatafromvlist[@objtype,@vlist]
@vlistfromobjdata[@objtype,$objdata]
@vlistfromobjdata_[@objtype,@objdata]
Used for creating special objects (zones, particle emitters, movers and cameras). See here.

Also see VList-related commands here.

 Back to Functions