Register forum user name Search FAQ

MUSHclient scripting

Description of MUSHclient world function: world.GetVariable

Name GetVariable
Type Method
Summary Gets the contents of a variable
Prototype VARIANT GetVariable(BSTR VariableName);

View list of data type meanings
Description

Gets the contents of the named variable. If the named variable does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

If GetVariable is called from within a plugin, the variables for the current plugin are used, not the "global" MUSHclient variables.

If you want to find the value of a variable in another plugin, or the global MUSHclient variables, use "GetPluginVariable".


-----

RULES FOR NAMES

Names of triggers, aliases, timers and variables must follow these rules:

a. Start with a letter (A-Z)
b. Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)


-----

SAVING AND LOADING

Please note that the following characters will not be handled correctly:

* The byte value hex 00 (otherwise known as 0x00 or null). This is used as a string terminator in MUSHclient, and attempts to imbed 0x00 values into variables will result in the variable being terminated at the 0x00 position.


* Carriage-return (hex 0D or 0x0D) and line-feeds (hex 0A or 0x0A). You can use these internally however you like, however when they are read from a plugin state file, or a MUSHclient world file, carriage returns are dropped, and line-feeds are converted to the sequence 0x0D 0x0A (carriage-return followed by linefeed). This is not normally a problem - because line breaks are usually stored as carriage-return/linefeed, and the reading process effectively will read them back in as that. However individual carriage-returns or linefeeds will not be read back in correctly.


If you are planning to use variables to store "binary" data - that is, data that can have all 256 possible character values, you are advised to convert them to base-64 encoded strings (using Base64Encode) when saving them, and conver them back (using Base64Decode) when loading them. Also be aware that only the Lua version of the base 64 encoding (utils.base64encode and utils.base64decode) will correctly handle the 0x00 value.

-----

RETRIEVING NUMBERS

Variables are stored as strings, so GetVariable returns a string, not a number. If the variable is supposed to be storing a numeric quantity (a count of mobs, hit points, or experience, for example) then you will probably need to convert it back to a number if it is going to be correctly processed inside a script. For example:

Lua: x = tonumber (GetVariable ("x"))
JScript: x = parseInt (GetVariable ("x"))
Python: x = int (GetVariable ("x"))
VBscript: x = CInt (GetVariable ("x"))

These examples retrieve the variable "x" and use the "convert to number" function of the script language to convert it back into a script numeric variable.
VBscript example 
dim MyName

MyName = world.GetVariable ("MyName")

if isempty (MyName) then
  world.note "My name is not defined"
end if

if isnull (MyName) then
  world.note "Invalid variable name"
end if

world.note MyName
Jscript example 
var MyName;

MyName = world.GetVariable("MyName");

if (MyName == null)
  world.note("MyName is not defined");
else
  world.note(MyName);
PerlScript example 
$MyName = $world->GetVariable("MyName");

if (!defined ($MyName)) 
  {
  $world->note ("MyName is not defined");
  }
else 
  {
  $world->note ($MyName);
  }
Python example 
MyName = world.GetVariable("MyName")

if not MyName:
  world.note("MyName is not defined")
else:
  world.note(MyName)
Lua example 
local MyName

MyName = GetVariable("MyName")

if MyName == nil then
  Note ("MyName is not defined")
else
  Note (MyName)
end
Lua notes 
Lua returns nil where applicable instead of an "empty variant" or "null variant".
Returns The contents of the specified variable.
An EMPTY variant, if the variable does not exist.
A NULL variant if the variable name is invalid.

See also ...

Function Description
GetEntity Retrieves the value of an MXP server-defined entity
GetPluginVariable Gets the contents of a variable belonging to a plugin
GetPluginVariableList Gets the list of variables in a specified plugin
GetVariableList Gets the list of variables
SetVariable Sets the value of a variable

Search for script function

Enter a word or phrase in the box below to narrow the list down to those that match.

The function name, prototype, summary, and description are searched.

Search for:   

Leave blank to show all functions.

Return codes

Many functions return a "code" which indicates the success or otherwise of the function.

You can view a list of the return codes

Function prototypes

The "prototype" part of each function description lists exactly how the function is called (what arguments, if any, to pass to it).

You can view a list of the data types used in function prototypes

View all functions

[Back]

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.

Home