# functions

name: NoteColour
prototype: short NoteColour;
summary: Chooses which custom colour will be used for world notes.
return_value: This is a property. You can use it to find the current note colour.
type_of_object: Property
doc_name: colours
lua_example: Note (GetNoteColour ()) SetNoteColour (15) -- use custom colour 15
description:
You can get or set this to change the colour (number) that the *next* world.note will be displayed in. The valid range is 0 to 16, where 0 is "no change", 1 is custom colour 1, through to 16 for custom colour 16.

If notes are currently being displayed in RGB mode (using NoteColourFore or NoteColourBack) then getting the NoteColour will return -1.

If notes are currently being displayed in RGB mode (using NoteColourFore or NoteColourBack) then setting the NoteColour will switch back to palette mode (the default).

It may be easier to use ColourNote to display notes in a different colour (in a single function) rather than changing the note colour and then doing a Note.

vb_example:
world.notecolour = 15  ' set note colour to use custom colour 15
world.note "This will be in custom colour 15"
world.note world.notecolour  ' display current note colour

java_example:
world.notecolour = 15;  // set note colour to use custom colour 15
world.note("This will be in custom colour 15");
world.note(world.notecolour);  // display current note colour

perl_example:
$world->{notecolour} = 15;  # set note colour to use custom colour 15
$world->note("This will be in custom colour 15");
$world->note($world->{notecolour});  # display current note colour

see_also:
Note NoteColourFore NoteColourBack Tell NoteColourName NoteColourRGB ColourNote ColourTell NoteStyle

python_example:
world.notecolour = 15  # set note colour to use custom colour 15
world.note("This will be in custom colour 15")
world.note(world.notecolour)  # display current note colour

lua_notes:
Lua implements this as two functions:

GetNoteColour - gets the note colour
SetNoteColour - sets the note colour


name: LogNotes
prototype: short LogNotes;
summary: The property of whether notes are logged to the log file
description: Set to 1 to log notes to the log file, 0 to not log
return_value: This is a property. You can use it to find whether notes are currently logged.
type_of_object: Property
see_also: LogInput LogOutput
doc_name: logging
vb_example:
world.lognotes = 1   ' log notes
world.lognotes = 0   ' don't log notes
world.note world.lognotes  ' display whether notes are logged

java_example:
world.lognotes = 1;   // log notes
world.lognotes = 0;   // don't log notes
world.note(world.lognotes);  // display whether notes are logged

perl_example:
$world->{lognotes} = 1;   # log notes
$world->{lognotes} = 0;   # don't log notes
$world->note($world->{lognotes});  # display whether notes are logged

python_example:
world.lognotes = 1   # log notes
world.lognotes = 0   # don't log notes
world.note(world.lognotes)  # display whether notes are logged

lua_example:
SetLogNotes (true)   -- log notes
SetLogNotes (false)   -- don't log notes
Note(GetLogNotes ())  -- display whether notes are logged

lua_notes:
Lua implements this as two functions:

GetLogNotes - gets whether notes are logged
SetLogNotes - sets whether notes are logged

The argument is optional, and defaults to true.


name: LogInput
prototype: short LogInput;
summary: The property of whether commands are logged to the log file
description: Set to 1 to log commands to the log file, 0 to not log
return_value: This is a property. You can use it to find whether commands (your input) are currently logged.
type_of_object: Property
see_also: LogNotes LogOutput EchoInput
doc_name: logging
vb_example:
world.loginput = 1   ' log input
world.loginput = 0   ' don't log input
world.note world.loginput  ' display whether input is logged

java_example:
world.loginput = 1;   // log input
world.loginput = 0;   // don't log input
world.note(world.loginput);  // display whether input is logged

perl_example:
$world->{loginput} = 1;   # log input
$world->{loginput} = 0;   # don't log input
$world->note($world->{loginput});  # display whether input is logged

python_example:
world.loginput = 1   # log input
world.loginput = 0   # don't log input
world.note(world.loginput)  # display whether input is logged

lua_example:
SetLogInput (true)   -- log input
SetLogInput (false)   -- don't log input
Note(GetLogInput ())  -- display whether input is logged

lua_notes:
Lua implements this as two functions:

GetLogInput- gets whether input is logged
SetLogInput- sets whether input is logged

The argument is optional, and defaults to true.


name: Trace
prototype: boolean Trace;
summary: Trace mode property
return_value: This is a property. You can use it to find whether trace mode is on.
type_of_object: Property
see_also: TraceOut
doc_name: utils
description:
Set to 1 to turn trace mode on, 0 to turn it off.

When trace mode is on debug messages appear in the output window. These occur when:

1. A trigger matches
2. A timer fires
3. An alias matches
4. A script executes
5. A script calls TraceOut.

vb_example:
world.trace = 1   ' turn trace on
world.trace = 0   ' turn trace off
world.note world.trace  ' display whether trace is on

java_example:
world.trace = 1;   // turn trace on
world.trace = 0;   // turn trace off
world.Note(world.Trace);  // display whether trace is on

perl_example:
$world->{trace} = 1;   # trace mode on
$world->{trace} = 0;   # trace mode off
$world->note($world->{trace});  # display whether trace is on

python_example:
world.trace = 1   # turn trace on
world.trace = 0   # turn trace off
world.Note(world.Trace)  # display whether trace is on

lua_example:
SetTrace (true)   -- turn trace on
SetTrace (false)   -- turn trace off
Note(GetTrace ())  -- display whether trace is on

lua_notes:
Lua implements this as two functions:

GetTrace - gets whether tracing occurs
SetTrace - sets whether tracing occurs

The argument is optional, and defaults to true.


name: GetLineCount
prototype: long GetLineCount();
summary: Gets count of lines received
vb_example: world.note world.GetLineCount
java_example: world.note(world.GetLineCount());
perl_example: $world->note($world->GetLineCount());
return_value: The number of lines received by this world.
type_of_object: Method
see_also: GetReceivedBytes GetSentBytes GetLinesInBufferCount
python_example: world.note(world.GetLineCount)
doc_name: info
lua_example: Note(GetLineCount())
description:
This returns the number of lines received by this world. However, see GetLinesInBufferCount for the number of lines currently in the output buffer, which might be different.


name: IsConnected
prototype: boolean IsConnected();
summary: Tests to see if the world is connected to the MUD server
vb_example: world.note world.IsConnected
java_example: world.note(world.IsConnected());
perl_example: $world->note($world->IsConnected());
type_of_object: Method
see_also: Connect Disconnect GetConnectDuration GetInfo
python_example: world.note(world.IsConnected)
doc_name: info
lua_example: Note(IsConnected())
description:
This returns TRUE if the world is currently connected.

See GetInfo (227) for more details about the exact connection status.

There are actually a number of connection "phases" because connection is not synchronous. That is, connecting takes time.

If you are using a proxy server, with a username/password, there are 8 phases as described below. Not all phases are necessarily done, for example if the MUD address is already a "dotted decimal" number then a MUD name lookup is not required.

They are:

0=not connected (and not attempting to connect)
1=MUD name lookup (converting MUD name to an IP address)
2=Proxy server name lookup (converting proxy server name to an IP address)
3=connecting to MUD (establishing TCP/IP connection to the MUD)
4=connecting to proxy server (establishing TCP/IP connection to the proxy server)
5=proxy server phase 1 (sent SOCKS authentication method, awaiting confirmation)
6=proxy server phase 2 (sent SOCKS username/password, awaiting confirmation)
7=proxy server phase 3 (sent SOCKS connect details, awaiting confirmation
)
8=connected to MUD (fully connected)

Strictly speaking, IsConnected returns true if the connection phase is 8 (connected to MUD) and false for any other phase.

return_value:
TRUE if world connected
FALSE if not connected

Note: TRUE is a non-zero value, FALSE is the value 0.


name: Note
prototype: void Note(BSTR Message);
summary: Sends a note to the output window
vb_example: world.note "This monster is worth avoiding!"
java_example: world.note("This monster is worth avoiding!");
perl_example: $world->note("This monster is worth avoiding!");
return_value: Nothing.
type_of_object: Method
python_example: world.note("This monster is worth avoiding!")
doc_name: note
lua_example: Note ("This monster is worth avoiding!")
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
This makes a note in the output window. It is not transmitted to the world. It is useful for making comments to yourself. The note is automatically terminated by a newline, so each world.Note will appear on a separate line.

The note appears in the current NoteColour (a custom colour), or in the RGB colours selected by NoteColourFore and NoteColourBack.

You can also choose colours with NoteColourRGB and NoteColourName.

If you want to change colours in the middle of a note, use Tell instead.

To make changes to the text style (eg. bold, underline) see NoteStyle.

see_also:
Send NoteColour NoteColourFore NoteColourBack Tell NoteColourRGB NoteColourName ColourNote ColourTell NoteStyle NoteHr


name: Send
prototype: long Send(BSTR Message);
summary: Sends a message to the MUD
vb_example: world.send "go north"
java_example: world.Send("go north");
perl_example: $world->Send("go north");
type_of_object: Method
see_also: Note LogSend SendPush Execute SendImmediate Queue SendNoEcho SendPkt SendSpecial
python_example: world.Send("go north")
doc_name: send
lua_example: Send ("go north")
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
This sends the specified text to the world. It is similar to typing it into the command window. However aliases, speedwalks, scripting prefixes, command-stacking etc. are not evaluated. 

If you want to exactly emulate typing into the command window use world.Execute instead.

Use Send to send things to the MUD without further evaluation. Use Execute to allow other aliases to process what you sent.

A newline character is appended to the text you supply, as MUD commands normally are terminated with a newline.

The text may include imbedded newlines. 

If the text has a trailing newline it is removed. In other words, text with a trailing newline will not end up with two newlines when sent to the MUD.

The command is not saved in the command history buffer (use SendPush if you want to save it).

return_value:
eWorldClosed : The world is closed
eItemInUse : Cannot be called from within OnPluginSent script callback
eOK: Sent OK


name: Sound
prototype: long Sound(BSTR SoundFileName);
summary: Plays a sound
vb_example: Sound "ding.wav"
java_example: Sound("ding.wav");
perl_example: $world->Sound("ding.wav");
type_of_object: Method
see_also: PlaySound StopSound GetSoundStatus
python_example: world.Sound("ding.wav")
doc_name: utils
lua_example: Sound ("ding.wav")
description:
This plays the specified sound file, allowing you to add sound-effects to your world.

Also see PlaySound which lets you play multiple sound files at once.

The sound file should have the properties:

* "Wave" file (ie. ending in .wav)
* Audio sample size: 16 bit
* Channels: 2
* Audio sample rate: 22 kHz
* Audio format: PCM

You can use programs like Audacity (which is free) to convert sound files from one format to another.

http://audacity.sourceforge.net/

return_value:
eNoNameSpecified: no sound file name given
eCannotPlaySound: cannot play that file
eOK: completed OK


name: DeleteTrigger
prototype: long DeleteTrigger(BSTR TriggerName);
summary: Deletes a trigger
vb_example: world.DeleteTrigger "my_trigger"
java_example: world.DeleteTrigger("my_trigger");
perl_example: $world->DeleteTrigger("my_trigger");
type_of_object: Method
python_example: world.DeleteTrigger("my_trigger")
doc_name: triggers
lua_example: DeleteTrigger("my_trigger")
description:
Deletes the named trigger from the list of triggers.

WARNING - if the trigger is executing a script it cannot be deleted. For example, a trigger cannot delete itself.

If you need to delete a trigger from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableTrigger to disable it first.

return_value:
eInvalidObjectLabel: The trigger name is not valid
eTriggerNotFound: The named trigger does not exist
eItemInUse: The trigger is currently executing a script
eOK: deleted OK

see_also:
AddTrigger EnableTrigger GetTrigger GetTriggerList IsTrigger GetTriggerInfo DeleteTriggerGroup DoAfterSpecial


name: AddTrigger
summary: Adds a trigger
vb_example: world.addtrigger "monster", "* attacks", "flee", 1, 14, 0, "", ""
java_example: world.AddTrigger("monster", "* attacks", "flee", 1, 14, 0, "", "");
perl_example: $world->AddTrigger("monster", "* attacks", "flee", 1, 14, 0, "", "");
type_of_object: Method
python_example: world.AddTrigger("monster", "* attacks", "flee", 1, 14, 0, "", "")
doc_name: triggers
prototype:
long AddTrigger(BSTR TriggerName, BSTR MatchText, BSTR ResponseText, long Flags, short Colour, short Wildcard, BSTR SoundFileName, BSTR ScriptName);

description:
Adds a trigger to the list of triggers. If you want to specify the sequence number of the trigger, or where the response text is to be sent to, use AddTriggerEx.

For AddTrigger they default to:
  Sequence: 100
  Send to:  world

Name: name of this trigger - may be empty (see rules for names below)
Match_text: what to match on
Response_text: what to send back to the world
Flags: various flags, see list below
Colour: what colour to draw triggered text, see list below
Wildcard: Copy which wildcard to the clipboard (0 = none), otherwise 1 to 10.
SoundFileName: Which sound file to play
ScriptName: Which script subroutine to execute

Flags

The flags can be one or more of the constants below. For example, to omit from log and omit from output, the flags would be 6. Preferably use the constant declarations in your script file, and "OR" them together. E.g. 

VBscript: eOmitFromLog or eOmitFromOutput
JScript: eOmitFromLog | eOmitFromOutput

VBscript:

const eEnabled = 1  ' enable trigger
const eOmitFromLog = 2  ' omit from log file
const eOmitFromOutput = 4  ' omit trigger from output
const eKeepEvaluating = 8  ' keep evaluating
const eIgnoreCase = 16  ' ignore case when matching
const eTriggerRegularExpression = 32  ' trigger uses regular expression
const eExpandVariables = 512  '  expand variables like @direction
const eReplace = 1024  ' replace existing trigger of same name
const eTemporary = 16384 ' temporary - do not save to world file
const eTriggerOneShot = 32768 ' one shot - delete after firing

JScript:

var eEnabled = 1;  //  enable trigger
var eOmitFromLog = 2; // omit from log file
var eOmitFromOutput = 4;  // omit trigger from output
var eKeepEvaluating = 8;  //  keep evaluating
var eIgnoreCase = 16;  //  ignore case when matching
var eTriggerRegularExpression = 32;  //  trigger uses regular expression
var eExpandVariables = 512;  // expand variables like @direction
var eReplace = 1024;  // replace existing trigger of same name
var eTemporary = 16384; // temporary - do not save to world file
var eTriggerOneShot = 32768; // one shot - delete after firing

PerlScript constants:

my $eEnabled = 1;  #  enable trigger
my $eOmitFromLog = 2; # omit from log file
my $eOmitFromOutput = 4;  # omit trigger from output
my $eKeepEvaluating = 8;  #  keep evaluating
my $eIgnoreCase = 16;  #  ignore case when matching
my $eTriggerRegularExpression = 32;  #  trigger uses regular expression
my $eExpandVariables = 512;  # expand variables like @direction
my $eReplace = 1024;  # replace existing trigger of same name
my $eTemporary = 16384;  # temporary - do not save to world file
my $eTriggerOneShot = 32768; # one shot - delete after firing

Colours

VBscript:

const NOCHANGE = -1
const custom1 = 0
const custom2 = 1
const custom3 = 2 
const custom4 = 3
const custom5 = 4
const custom6 = 5
const custom7 = 6
const custom8 = 7
const custom9 = 8
const custom10 = 9
const custom11 = 10
const custom12 = 11
const custom13 = 12
const custom14 = 13
const custom15 = 14
const custom16 = 15

JScript:

var NOCHANGE = -1;
var custom1 = 0;
var custom2 = 1;
var custom3 = 2; 
var custom4 = 3;
var custom5 = 4;
var custom6 = 5;
var custom7 = 6;
var custom8 = 7;
var custom9 = 8;
var custom10 = 9;
var custom11 = 10;
var custom12 = 11;
var custom13 = 12;
var custom14 = 13;
var custom15 = 14;
var custom16 = 15;

PerlScript:

my $NOCHANGE = -1;
my $custom1 = 0;
my $custom2 = 1;
my $custom3 = 2; 
my $custom4 = 3;
my $custom5 = 4;
my $custom6 = 5;
my $custom7 = 6;
my $custom8 = 7;
my $custom9 = 8;
my $custom10 = 9;
my $custom11 = 10;
my $custom12 = 11;
my $custom13 = 12;
my $custom14 = 13;
my $custom15 = 14;
my $custom16 = 15;


* 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 (_)

return_value:
eInvalidObjectLabel: The trigger name is not valid
eTriggerAlreadyExists: A trigger of that name already exists
eTriggerCannotBeEmpty: The "match_text" cannot be empty
eScriptNameNotLocated: The script name cannot be located in the script file
eBadRegularExpression: The regular expression could not be evaluated
eOK: added OK

see_also:
AddTriggerEx DeleteTrigger EnableTrigger GetTrigger GetTriggerList IsTrigger GetTriggerInfo EnableGroup EnableTriggerGroup DeleteGroup DeleteTriggerGroup SetTriggerOption GetTriggerOption ImportXML

lua_example:
AddTrigger("monster", "* attacks", "flee", trigger_flag.Enabled , custom_colour.Custom15, 0, "", "")

lua_notes:
The script name is optional.

The trigger flags are built into the "trigger_flag" table, as follows:

Enabled = 1
OmitFromLog = 2
OmitFromOutput = 4
KeepEvaluating = 8
IgnoreCase = 16
RegularExpression = 32
ExpandVariables = 512
Replace = 1024
Temporary = 16384
LowercaseWildcard = 2048
OneShot = 32768

The colour names for custom colours are built into the "custom_colour" table, as follows:

NoChange = -1
Custom1 = 0
Custom2 = 1
Custom3 = 2
Custom4 = 3
Custom5 = 4
Custom6 = 5
Custom7 = 6
Custom8 = 7
Custom9 = 8
Custom10 = 9
Custom11 = 10
Custom12 = 11
Custom13 = 12
Custom14 = 13
Custom15 = 14
Custom16 = 15
CustomOther = 16


name: EnableTrigger
prototype: long EnableTrigger(BSTR TriggerName, BOOL Enabled);
summary: Enables or disables a trigger
type_of_object: Method
see_also: AddTrigger DeleteTrigger GetTrigger GetTriggerList IsTrigger GetTriggerInfo
doc_name: triggers
lua_notes: The enabled flag is optional, and defaults to true.
description:
Enables or disables the named trigger.  An enabled trigger is "active", otherwise it is ignored when processing incoming text from the MUD.

vb_example:
world.EnableTrigger "monster", TRUE  ' enable trigger
world.EnableTrigger "monster", FALSE  ' disable trigger

java_example:
world.EnableTrigger("monster", true);  # enable trigger
world.EnableTrigger("monster", false);  # disable trigger

return_value:
eInvalidObjectLabel: The trigger name is not valid
eTriggerNotFound: The named trigger does not exist
eOK: completed OK

python_example:
world.EnableTrigger("monster", True)  # enable trigger
world.EnableTrigger("monster", False)  # disable trigger

lua_example:
EnableTrigger("monster", true)  -- enable trigger
EnableTrigger("monster", false)  -- disable trigger


name: GetTrigger
summary: Gets details about a named trigger
java_example: // Use GetTriggerInfo when using Jscript
perl_example: # Use GetTriggerInfo when using PerlScript
type_of_object: Method
see_also: AddTrigger DeleteTrigger EnableTrigger GetTriggerList IsTrigger GetTriggerInfo
python_example: # Use GetTriggerInfo when using Python
doc_name: triggers
prototype:
long GetTrigger(BSTR TriggerName, VARIANT* MatchText, VARIANT* ResponseText, VARIANT* Flags, VARIANT* Colour, VARIANT* Wildcard, VARIANT* SoundFileName, VARIANT* ScriptName);

description:
Gets details about the specified trigger.

For a detailed description about the meanings of the fields, see AddTrigger.

This function does not appear to work when using Jscript or PerlScript, so if you are using those languages you should see GetTriggerInfo instead. See below for how it works with Lua.

vb_example:
dim trname
dim trmatch
dim trresponse
dim trflags
dim trcolour
dim trwildcard
dim trsoundfilename
dim trscriptname
dim iStatus

iStatus = world.gettrigger (trname, trmatch, trresponse,_
      trflags, trcolour, trwildcard, trsoundfilename, trscriptname)

return_value:
eInvalidObjectLabel: The trigger name is not valid
eTriggerNotFound: The named trigger does not exist
eOK: completed OK

lua_example:
local status

local match
local response
local flags
local colour
local wildcard
local soundfilename
local scriptname

status, match, response, flags, colour, wildcard, soundfilename, scriptname = 
 GetTrigger ("mytrigger")

print (match, response, flags, colour, wildcard, soundfilename, scriptname)

lua_notes:
Lua does not let you call by reference, however it can return multiple results.

Thus GetTrigger is implemented to return the various fields as a multiple-return result, 
as shown in the example above.


name: IsTrigger
prototype: long IsTrigger(BSTR TriggerName);
summary: Tests to see if a trigger exists
description: Used to test if a trigger exists. Note that this function returns 0 if the trigger *exists*.
vb_example: world.note world.IsTrigger ("myTrigger")
java_example: world.note(world.IsTrigger("myTrigger"));
perl_example: $world->note($world->IsTrigger("myTrigger"));
type_of_object: Method
see_also: AddTrigger DeleteTrigger EnableTrigger GetTrigger GetTriggerList GetTriggerInfo
python_example: world.note(world.IsTrigger("myTrigger"))
doc_name: triggers
lua_example: Note(IsTrigger("myTrigger"))
return_value:
eInvalidObjectLabel: The trigger name is not valid
eTriggerNotFound: The named trigger does not exist
eOK: completed OK  (ie. The trigger exists)


name: GetTriggerList
prototype: VARIANT GetTriggerList();
summary: Gets the list of triggers
perl_example: foreach $item (Win32::OLE::in ($world->GetTriggerList)) { $world->note($item); }
type_of_object: Method
see_also: AddTrigger DeleteTrigger EnableTrigger GetTrigger IsTrigger GetTriggerInfo GetPluginTriggerList
python_example: triggerlist = world.GetTriggerList if (triggerlist ): for t in triggerlist : world.Note (t)
doc_name: triggers
lua_notes: Lua returns nil where applicable instead of an "empty variant".
description:
Returns an array of all the named triggers currently defined. You can then use GetTrigger or GetTriggerInfo to find out more details about each one.

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

If you want to find the list of triggers in another plugin, or the global MUSHclient triggers, use "GetPluginTriggerList".

Note - from version 3.30 onwards GetTriggerList returns all triggers, even unlabelled ones. The unlabelled triggers will have assigned an "internal" label (like "*trigger42") that can be used in GetTriggerInfo, and similar routines.

vb_example:
dim trList

trList = world.GetTriggerList

If Not IsEmpty (trList) then

  For Each t In trList 
    world.Note t 
  Next

End If

java_example:
triggerlist = new VBArray(world.GetTriggerList()).toArray();

if (triggerlist)  // if not empty
 for (i = 0; i < triggerlist.length; i++)
   world.note(triggerlist [i]);

return_value:
If there are no triggers (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the triggers. Use "ubound" to find the number of triggers in the list. You can then use "GetTrigger" to find details about each trigger. See the example for how to do this. You can paste this example into an "Immediate" window (CTRL+I) to test it.

lua_example:
tl = GetTriggerList()
if tl then
  for k, v in ipairs (tl) do 
    Note (v) 
  end  -- for
end -- if we have any triggers


name: GetVariable
prototype: VARIANT GetVariable(BSTR VariableName);
summary: Gets the contents of a variable
type_of_object: Method
see_also: SetVariable GetVariableList GetPluginVariable GetPluginVariableList GetEntity
doc_name: variables
lua_notes: Lua returns nil where applicable instead of an "empty variant" or "null variant".
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.

vb_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

java_example:
var MyName;

MyName = world.GetVariable("MyName");

if (MyName == null)
  world.note("MyName is not defined");
else
  world.note(MyName);

perl_example:
$MyName = $world->GetVariable("MyName");

if (!defined ($MyName)) 
  {
  $world->note ("MyName is not defined");
  }
else 
  {
  $world->note ($MyName);
  }

return_value:
The contents of the specified variable.
An EMPTY variant, if the variable does not exist.
A NULL variant if the variable name is invalid.

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


name: SetVariable
prototype: long SetVariable(BSTR VariableName, BSTR Contents);
summary: Sets the value of a variable
vb_example: world.SetVariable "MyName", "Nick Gammon"
java_example: world.SetVariable("MyName", "Nick Gammon");
perl_example: $world->SetVariable("MyName", "Nick Gammon");
return_value: eInvalidObjectLabel: The variable name is not valid eOK: The variable contents were set
type_of_object: Method
see_also: GetVariable GetVariableList
python_example: world.SetVariable("MyName", "Nick Gammon")
doc_name: variables
lua_example: SetVariable ("MyName", "Nick Gammon")
description:
Sets the contents of a variable. If the named variable already exists the contents are replaced. If the variable doesn't exist it is created. Variables are contained in the "world" configuration, and saved when the world is saved. You can use variables to "remember" data from one session of MUSHclient to the next.

* 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 (_)


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.


name: GetVariableList
prototype: VARIANT GetVariableList();
summary: Gets the list of variables
description: Returns an array of all the variables currently defined.
type_of_object: Method
see_also: GetVariable SetVariable
doc_name: variables
vb_example:
dim varList

varList = world.GetVariableList

If Not IsEmpty (varList) Then
  
  For Each v In varList 
    world.note v & " = " &  world.GetVariable (v)
  Next

End If

java_example:
variablelist = new VBArray(world.GetVariableList()).toArray();

if (variablelist)  // if not empty
 for (i = 0; i < variablelist.length; i++)
   world.note(variablelist [i] + " = " + 
       world.GetVariable(variablelist [i]));

perl_example:
foreach $item (Win32::OLE::in ($world->GetVariableList))
 {
 ($key, $value) = ($item, $world->GetVariable ($item));
 $world->note($key . " = " . $value) if (defined ($key));
 }

return_value:
If there are no variables then the return value is empty. Use "IsEmpty" to test for this possibility.
Otherwise, it returns a variant array containing the names of all the variables. Use "lbound" and "ubound" to find the bounds of the array of variables (ie. the number of variables in the list). You can then use "GetVariable" to find the contents of each variable.

python_example:
variablelist = world.GetVariableList
if (variablelist ):
  for v in variablelist : world.Note (v + " = " +
                  world.GetVariable(v))

lua_example:
-- show all variables and their values

for k, v in pairs (GetVariableList()) do 
  Note (k, " = ", v) 
end

lua_notes:
Under Lua this function returns a table of all variables and their values, 
keyed by the variable name.

Thus you can directly access variables from the table, like this:

-- show value for variable "victim" ...

print (GetVariableList ().victim)


name: GetInfo
prototype: VARIANT GetInfo(long InfoType);
summary: Gets information about the current world
perl_example: # # Display world IP address # $world->note ($world->GetInfo (1));
type_of_object: Method
see_also: GetTriggerInfo GetAliasInfo GetTimerInfo Debug
doc_name: info
description:
Gets details about the current world. You can use:

Debug ("info")

... to list the descriptions corresponding to each one (and their current values), inside MUSHclient.

You can obtain various "types" of information about the world by specifying an "InfoType". The possible InfoTypes are: 

(strings - configuration)

  1 - Server name (IP address) 
  2 - World name
  3 - Character name
  4 - Send to world - file preamble
  5 - Send to world - file postamble
  6 - Send to world - line preamble 
  7 - Send to world - line postamble 
  8 - World notes
  9 - Sound on new activity
 10 - Scripts editor
 11 - Log file preamble
 12 - Log file postamble
 13 - Log file line preamble - player input
 14 - Log file line preamble - notes
 15 - Log file line preamble - MUD output
 16 - Log file line postamble - player input
 17 - Log file line postamble - notes
 18 - Log file line postamble - MUD output
 19 - Speed Walk Filler 
 20 - Output window font name
 21 - Speed walk prefix
 22 - Text sent on connecting
 23 - Input font name
 24 - Paste to world - file preamble
 25 - Paste to world - file postamble
 26 - Paste to world - line preamble 
 27 - Paste to world - line postamble 
 28 - Scripting language
 29 - Script function for world open
 30 - Script function for world close
 31 - Script function for world connect
 32 - Script function for world disconnect
 31 - Script function for world get focus
 32 - Script function for world lose focus
 35 - Script file name
 36 - Scripting prefix
 37 - Auto-say string
 38 - Auto-say override
 39 - Tab-completion defaults
 40 - Auto-log file name
 41 - Recall window - line preamble
 42 - Terminal ID (telnet negotiation)
 43 - Mapping failure message
 44 - Script function for MXP starting up     
 45 - Script function for MXP closing down    
 46 - Script function for MXP error           
 47 - Script function for MXP tag open        
 48 - Script function for MXP tag close       
 49 - Script function for MXP variable set    
 50 - Sound to play for beeps

(strings - calculated at runtime)
 
 51 - Current log file name
 52 - Last "immediate" script expression
 53 - Current status line message
 54 - World file pathname
 55 - World title
 56 - MUSHclient application path name
 57 - World files default path (directory)
 58 - Log files default path (directory)
 59 - Script files default path (directory)
 60 - Plugin files default path (directory)
 61 - World TCP/IP address (as string, after DNS lookup, eg. 10.0.0.16)
 62 - Proxy server TCP/IP address (as string, after DNS lookup, eg. 10.0.0.22)
 63 - Host name (name of this PC)
 64 - Current directory
 65 - Script function for world save
 66 - MUSHclient application directory
 67 - World file directory
 68 - MUSHclient startup (initial) directory
 69 - Translation file
 70 - Locale
 71 - Font used for fixed-pitch dialogs
 72 - MUSHclient version (eg. "4.11")
 73 - MUSHclient compilation date/time (eg. "Jul 25 2007 14:21:10")
 74 - Default sounds file directory (presently GetInfo (66) + "sounds/")
 75 - Last telnet subnegotiation string received
 76 - Special font pathname
 77 - Windows version debug string (eg. "Service Pack 2")
 78 - Foreground image name
 79 - Background image name
 80 - libpng version (eg. "1.2.31")
 81 - libpng header (eg. " libpng version 1.2.31 - August 21, 2008")
 82 - Preferences database pathname
 83 - SQLite3 database version
 84 - File-browsing directory
 85 - Plugins state file directory
 86 - Word under mouse on mouse menu click
 87 - Last command sent to the MUD


(booleans - calculated at runtime)
 
101 - 'No Echo' flag
102 - Debug incoming packets
103 - Decompressing
104 - MXP active
105 - Pueblo active
106 - Disconnected flag (true if not connected)
107 - Currently-connecting flag
108 - OK-to-disconnect flag
109 - Trace flag
110 - Script file changed
111 - 'World file is modified' flag
112 - Automapper active flag
113 - 'World is active' flag
114 - 'Output window paused' flag
115 - Localization active
116 / 117 - removed
118 - Variables have changed
119 - Script engine is active
120 - Scoll bar is (wanted to be) visible for output window
121 - High-resolution timer is available
122 - Is the SQLite3 library thread-safe?
123 - Are we currently processing a "Simulate" function call?
124 - Is the current line from the MUD being omitted from output?

(numbers (longs) - calculated at runtime)

201 - Total lines received
202 - Lines received but not yet seen (new lines)
203 - Total lines sent
204 - Packets received
205 - Packets sent
206 - Total uncompressed bytes received
207 - Total compresssed bytes received
208 - MCCP protocol in use (0=none, 1 - or 2)
209 - MXP error count
210 - MXP tags received
211 - MXP entities received
212 - Output font height
213 - Output font width
214 - Input font height
215 - Input font width
216 - Total bytes received
217 - Total bytes sent
218 - Count of variables
219 - Count of triggers
220 - Count of timers
221 - Count of aliases
222 - Count of queued commands
223 - Count of mapper items
224 - Count of lines in output window
225 - Count of custom MXP elements
226 - Count of custom MXP entities
227 - Connect phase:
   (0=not connected, 1=MUD name lookup, 2=Proxy server name lookup,
   3=connecting to MUD, 4=connecting to proxy server, 5=proxy server phase 1,
   6=proxy server phase 2, 7=proxy server phase 3, 8=connected  to MUD)
228 - World TCP/IP address (after DNS lookup, as a number)
229 - Proxy server TCP/IP address (after DNS lookup, as a number)
230 - Script execution depth
231 - Log file size (0 if no log file open)
232 - High-performance counter output (in seconds) (double)
233 - Time spent executing trigger matching (double)
234 - Time spent executing alias matching (double)
    -  note: see GetScriptTime function for the time taken to execute scripts
235 - Number of world windows open
236 - First column of the selection in the command window (1-relative)
    - if no selection, the column to the right of the cursor.
    - If the cursor is at the start of the window, it will return 1.
237 - Last column of the selection in the command window (1-relative)
    - if no selection, returns 0.
    - For example, if "abcd" is in the command window and "bc" is selected then
    -   GetInfo (236) will return 2 and GetInfo (237) will return 3.
238 - Current "show state" for the first world window of this world.
    Hide           =  0      
    Shownormal     =  1      
    Normal         =  1      
    Showminimized  =  2      
    Showmaximized  =  3      
    Maximize       =  3      
    Shownoactivate =  4      
    Show           =  5      
    Minimize       =  6      
    Showminnoactive=  7      
    Showna         =  8      
    Restore        =  9      
    Showdefault    = 10     

239 - The "source" of the current scripted action.

It is intended for scripters who want to know if a particular script is running because of user (player) action, or some sort of automated response. Effectively this can be used to determine if the player is AFK or not.

The returned value will be a number in the range 0 to 10, with these meanings:

  UnknownActionSource = 0 --> no particular reason, could be plugin saving
  UserTyping = 1 --> user typed something in the command area and pressed <Enter>
  UserMacro = 2 --> user typed a macro (eg. F2)
  UserKeypad = 3 --> user used the numeric keypad
  UserAccelerator = 4 --> user used an accelerator key
  UserMenuAction = 5 --> item chosen from pop-up menu
  TriggerFired = 6 --> trigger fired
  TimerFired = 7 --> timer fired
  InputFromServer = 8 --> input arrived (eg. packet received)
  WorldAction = 9 --> some sort of world action (eg. world open, connect, got focus)
  LuaSandbox = 10 --> executing Lua sandbox

Effectively, if GetInfo (239) returns a number in the range 1 to 5 inclusive, then the script is running in response to direct player input. Other numbers would indicate automated processing like a trigger or timer firing, input from the MUD, a plugin callback being called, and so on.

There is no entry in the list above for an alias being called, because aliases can be triggered by user input, "send to script (Execute function)", macros and so on. Thus, the number above would indicate the "real" reason an alias was called.

240 - The average width, in pixels, of a character in the output window, in the current output font. This figure is used when calculating how many characters would fit in the current width of the output window.

241 - The height, in pixels, of a character in the output window, in the current output font.

242 - Count of lines that had bad UTF-8 sequences in them, and were thus not considered for trigger evaluation (long)

243 - Font size of fixed pitch font
244 - Count of number of triggers that were evaluated (long)
245 - Count of number of triggers that matched (long)
246 - Count of number of aliases that were evaluated (long)
247 - Count of number of aliases that matched (long)
248 - Count of number of timers that fired (long)

249 - Main frame window height (long)
250 - Main frame window width (long)
251 - Main toolbar window height (long)
252 - Main toolbar window width (long)
253 - Game toolbar window height (long)
254 - Game toolbar window width (long)
255 - Activity toolbar window height (long)
256 - Activity toolbar window width (long)
257 - Info bar window height (long)
258 - Info bar window width (long)
259 - Status bar window height (long)
260 - Status bar window width (long)
261 - World window non-client height (long)
262 - World window non-client width (long)
263 - World window client height (long)
264 - World window client width (long)
265 - Windows major version  (long)  -- see below
266 - Windows minor version (long)  
267 - Windows build number (long)
268 - Windows platform ID (long)
269 - Foreground image mode
270 - Background image mode
271 - Background colour
272 - Text rectangle - left  (see TextRectangle function)
273 - Text rectangle - top
274 - Text rectangle - right
275 - Text rectangle - bottom
276 - Text rectangle - border offset
277 - Text rectangle - border width
278 - Text rectangle - outside colour
279 - Text rectangle - outside style
280 - Output window client height
281 - Output window client width
282 - Text rectangle - border colour
283 - Mouse position - X (relative to world output window)
284 - Mouse position - Y 
285 - Is output window available? (true or false)
286 - Triggers matched this session (long)
287 - Aliases matched this session (long)
288 - Timers fired this session  (long)
289 - Last line number that was terminated by an IAC/GA or IAC/EOR (long)  
290 - Actual text rectangle - left  (see below)
291 - Actual text rectangle - top
292 - Actual text rectangle - right
293 - Actual text rectangle - bottom
294 - Status of keyboard modifiers / mouse click, as follows:

      (values are in hexadecimal)

      0x00001 - shift key down (left or right)    
      0x00002 - control key down (left or right) 
      0x00004 - Alt key down (left or right)

      0x00008 - left shift key down     
      0x00010 - right shift key down     

      0x00020 - left control key down  
      0x00040 - right control key down

      0x00080 - left Alt key down  
      0x00100 - right Alt key down

      0x00200 - Caps Lock key down (right now)    
      0x00400 - Num Lock key down (right now)
      0x00800 - Scroll Lock key down (right now)

      0x02000 - Caps Lock key toggled (active)  
      0x04000 - Num Lock key  toggled (active)
      0x08000 - Scroll Lock key  toggled (active)

      0x10000 - Left mouse button down  
      0x20000 - Right mouse button down
      0x40000 - Middle mouse button down

More than one of these can be active at once so you should use a bitwise "and"
operation to check each bit (eg. bit.band in Lua).

295 - Number of times output window was redrawn
296 - Current vertical position of scroll bar in first output window (long)
297 - Resolution (frequency) of the high-resolution timer
298 - SQLite3 version number (eg. 3007002 for version 3.7.2.)
299 - ANSI code-page number (see below)
300 - OEM code-page number (see below)

(dates - calculated at runtime)

301 - Time connected
302 - Time log file was last flushed to disk
303 - When script file was last modified
304 - The current date/time
305 - When client started executing
306 - When this world was created/opened

(more numbers)

310 - Newlines received from the MUD (lines terminated by a newline)



You can deduce the operating system as follows by using GetInfo (265) through to GetInfo (268):

If platform ID == 0 (Win32s) then:
  you should not get this, MUSHclient doesn't run under Win32s
  
If platform ID == 1 (Windows 95-style versions) then:

If major == 4 and minor == 0 then: Windows 95
If major == 4 and minor == 10 then: Windows 98 (or 98SE)
If major == 4 and minor == 90 then: Windows ME

If platform ID == 2 (Windows NT versions) then:

If major == 3 then: Windows NT 3.51
If major == 4 then: Windows NT 4
If major == 5 and minor == 0 then: Windows 2000
If major == 5 and minor == 1 then: Windows XP
If major == 5 and minor == 2 then: Windows Server 2003
If major == 6 and minor == 0 then: Windows Vista, or Windows Server Longhorn
If major == 6 and minor == 1 then: Windows 7
If major == 6 and minor == 2 then: Windows 8
If major == 6 and minor == 3 then: Windows 8.1
If major == 10 and minor == 0 then: Windows 10


(The symbol "==" means "is equal to").

----

The "actual text rectangle" (selectors 290 to 293) give the offset of the text rectangle inside the main output window, taking into account the TextRectangle function (if used). However unlike selectors 273 to 276 these will always be the correct pixel offsets. For example, if TextRectangle has never been called, then 273 to 276 will all be zero, whereas 290 to 293 will have the coordinates of the text rectangle. Also if negative offsets are used for the bottom or right sides, then these are "normalized" into actual offsets for selectors 290 to 293. Thus you can use 290 to 293 for finding exactly where the text is on the screen (these figures may change if the window is resized).

----

ANSI code page numbers:

874 Thai 
932 Japan 
936 Chinese (PRC, Singapore) 
949 Korean 
950 Chinese (Taiwan Region; Hong Kong SAR, PRC)  
1200 Unicode (BMP of ISO 10646) 
1250 Windows 3.1 Eastern European  
1251 Windows 3.1 Cyrillic 
1252 Windows 3.1 Latin 1 (US, Western Europe) 
1253 Windows 3.1 Greek 
1254 Windows 3.1 Turkish 
1255 Hebrew 
1256 Arabic 
1257 Baltic 

OEM code page numbers:

437 MS-DOS United States 
708 Arabic (ASMO 708) 
709 Arabic (ASMO 449+, BCON V4) 
710 Arabic (Transparent Arabic) 
720 Arabic (Transparent ASMO) 
737 Greek (formerly 437G) 
775 Baltic 
850 MS-DOS Multilingual (Latin I) 
852 MS-DOS Slavic (Latin II) 
855 IBM Cyrillic (primarily Russian) 
857 IBM Turkish 
860 MS-DOS Portuguese 
861 MS-DOS Icelandic 
862 Hebrew 
863 MS-DOS Canadian-French 
864 Arabic 
865 MS-DOS Nordic 
866 MS-DOS Russian (former USSR) 
869 IBM Modern Greek 
874 Thai 
932 Japan 
936 Chinese (PRC, Singapore) 
949 Korean 
950 Chinese (Taiwan Region; Hong Kong SAR, PRC)  
1361 Korean (Johab)

vb_example:
'
'  List the lot
'

dim i, info

for i = 1 to 320
  info = world.GetInfo (i)
  if not isnull (info) then
   world.note i & " = " & info
  end if
next

'
' Find world IP address
'

Note GetInfo (1)

java_example:
//
//  display all information
//

for (i = 1; i <= 320; i++)
  {
  info = world.GetInfo (i);
  if (info)
    world.Note (i + " = " + info);
  }

return_value:
The specified information about the world, as described above. 
An EMPTY variant, if a date is undefined. 
A NULL variant if the InfoType is not a valid type.

python_example:
#
#  display all information
#

for i in range (320):
  info = world.GetInfo (i)
  if (info):
    world.Note (str(i) + " = " + str(info))

lua_example:
--
--  display all information
--

for i = 1, 320 do
  info = GetInfo(i)
  if info then
    Note (i, " = ", info)
  end
end


name: Save
prototype: boolean Save(BSTR Name);
summary: Saves world configuration.
vb_example: world.Save "" ' Saves under current name world.Save "my_new_name.mcl" ' Saves under new name
java_example: world.Save(""); // Saves under current name
perl_example: $world->Save(""); # Saves under current name
return_value: eOK: saved OK any other value: not saved Under Lua: false: saved OK true: did not save OK
type_of_object: Method
python_example: world.Save("") # Saves under current name
description:
Saves the current world, under the specified filename. Supply a blank file name to save under the current name.

Also, all plugins are forced to save their current state.

Under Lua (only) you can do a "save as" which saves under a new name, but preserves the original name, see below.

lua_example:
Save("")   -- Saves under current name

Save ("my_new_name.mcl")  -- Save under a new name - which is used for future saves

Save ("my_backup.mcl", true)  -- Save a copy under a different name, original name is unchanged

lua_notes:
The filename is optional, if not supplied the file is saved under its current name, if any.

You can supply a second boolean argument. If true, MUSHclient does a "save as", which means the file is saved under the given name, however the original name is preserved for future save. If you do a "save as" the file name is not optional.

Note under Lua the return codes are a bit misleading:

false: saved OK
true: did not save OK


name: Connect
prototype: long Connect();
summary: Connects the world to the MUD server
vb_example: world.connect
java_example: world.connect();
perl_example: $world->connect;
return_value: eWorldOpen: world is already open eOK: initiated connection
type_of_object: Method
see_also: IsConnected Disconnect ResetIP
python_example: world.connect
lua_example: Connect()
description:
This connects the current world. Note that since connecting is "asynchronous" you are not actually connected when this command completes. A return value of eOK simply means that the connection process has successfully started.

You can use IsConnected to see if the world is currently connected.


name: DeleteAlias
prototype: long DeleteAlias(BSTR AliasName);
summary: Deletes an alias
vb_example: world.DeleteAlias "my_alias"
java_example: world.DeleteAlias("my_alias");
perl_example: $world->DeleteAlias("my_alias");
type_of_object: Method
see_also: AddAlias EnableAlias GetAlias GetAliasList IsAlias GetAliasInfo DeleteAliasGroup DoAfterSpecial
python_example: world.DeleteAlias("my_alias")
doc_name: aliases
lua_example: DeleteAlias("my_alias")
description:
Deletes the named alias from the list of aliases.

WARNING - if the alias is executing a script it cannot be deleted. For example, an alias cannot delete itself.

If you need to delete an alias from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableGroup to disable it first.

return_value:
eInvalidObjectLabel: The alias name is not valid
eAliasNotFound: The named alias does not exist
eItemInUse: Cannot delete trigger/alias/timer because it is executing a script
eOK: deleted OK


name: EnableAlias
prototype: long EnableAlias(BSTR AliasName, BOOL Enabled);
summary: Enables or disables an alias
vb_example: world.EnableAlias "teleport", TRUE
java_example: world.EnableAlias("teleport", true);
perl_example: $world->EnableAlias("teleport", true);
type_of_object: Method
see_also: AddAlias DeleteAlias GetAlias GetAliasList IsAlias GetAliasInfo
python_example: world.EnableAlias("teleport", True)
doc_name: aliases
lua_example: EnableAlias ("teleport", true)
lua_notes: The enabled flag is optional, and defaults to true.
description:
Enables or disables the named alias. An enabled alias is "active", otherwise it is ignored when processing commands you type.

return_value:
eInvalidObjectLabel: The alias name is not valid
eAliasNotFound: The named alias does not exist
eOK: completed OK


name: GetAlias
summary: Gets details about an alias
java_example: // Use GetAliasInfo when using Jscript
perl_example: # Use GetAliasInfo when using PerlScript
type_of_object: Method
see_also: AddAlias DeleteAlias EnableAlias GetAliasList IsAlias GetAliasInfo
python_example: # Use GetAliasInfo when using Python
doc_name: aliases
prototype:
long GetAlias(BSTR AliasName, VARIANT* MatchText, VARIANT* ResponseText, VARIANT* Parameter, VARIANT* Flags, VARIANT* ScriptName);

description:
Gets details about the specified alias name.

See AddAlias for a description of the meanings of the fields.

This function does not appear to work when using Jscript or PerlScript, so if you are using those languages you should see GetAliasInfo instead. See below for how it works with Lua.

vb_example:
dim alname
dim almatch
dim alresponse
dim alparameter
dim alflags
dim alscriptname
dim iStatus

iStatus = world.getalias (alname, almatch, alresponse, _
              alparameter, alflags, alscriptname)

return_value:
eInvalidObjectLabel: The alias name is not valid
eAliasNotFound: The named alias does not exist
eOK: completed OK

lua_example:
local iStatus
local almatch
local alresponse
local alflags
local alscriptname


iStatus, almatch, alresponse, alflags, alscriptname  =
   GetAlias ("myalias")

print (iStatus, almatch, alresponse, alflags, alscriptname)

lua_notes:
Lua does not let you call by reference, however it can return multiple results.

Thus GetAlias is implemented to return the various fields as a multiple-return result, as shown in the example above.

The field Parameter is deprecated and thus not returned.


name: GetAliasList
prototype: VARIANT GetAliasList();
summary: Gets the list of aliases
perl_example: foreach $item (Win32::OLE::in ($world->GetAliasList)) { $world->note($item); }
type_of_object: Method
see_also: AddAlias DeleteAlias EnableAlias GetAlias IsAlias GetAliasInfo
python_example: aliaslist = world.GetAliasList if (aliaslist ): for a in aliaslist : world.Note (a)
doc_name: aliases
lua_notes: Lua returns nil where applicable instead of an "empty variant".
description:
Returns an array of all the named aliases currently defined. You can then use GetAlias or GetAliasInfo for more details about each one.

Note - from version 3.40 onwards GetAliasList returns all aliases, even unlabelled ones. The unlabelled aliases will have assigned an "internal" label (like "*alias42") that can be used in GetAliasInfo, and similar routines.

vb_example:
dim alList

alList = world.GetAliasList

If Not IsEmpty (alList) then

  For Each name In alList 
    world.Note name
  Next

End If

java_example:
aliaslist = new VBArray(world.GetAliasList()).toArray();

if (aliaslist)  // if not empty
 for (i = 0; i < aliaslist.length; i++)
   world.note(aliaslist [i]);

return_value:
If there are no aliases (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the aliases. Use "ubound" to find the number of aliases in the list. You can then use "GetAlias" to find details about each alias.

lua_example:
al = GetAliasList()
if al then
  for k, v in ipairs (al) do 
    Note (v) 
  end  -- for
end -- if we have any aliases


name: IsAlias
prototype: long IsAlias(BSTR AliasName);
summary: Tests to see if an alias exists
description: Used to test if an alias exists. Note that this function returns 0 if the alias *exists*.
vb_example: world.note world.IsAlias ("myalias")
java_example: world.note(world.IsAlias("myalias"));
perl_example: $world->note($world->IsAlias("myalias"));
type_of_object: Method
see_also: AddAlias DeleteAlias EnableAlias GetAlias GetAliasList GetAliasInfo
python_example: world.note(world.IsAlias("myalias"))
doc_name: aliases
lua_example: Note(IsAlias("myalias"))
return_value:
eInvalidObjectLabel: The alias name is not valid
eAliasNotFound: The named alias does not exist
eOK: completed OK - ie. The alias exists.


name: CloseLog
prototype: long CloseLog();
summary: Closes the log file
vb_example: world.closelog
java_example: world.closelog();
perl_example: $world->closelog;
return_value: eOK: closed OK eLogFileNotOpen: log file was not open
type_of_object: Method
see_also: OpenLog IsLogOpen WriteLog FlushLog
python_example: world.closelog
doc_name: logging
lua_example: CloseLog()
description:
This closes the currently open log file.

If you have a log file postamble declared this is written to the log file (note that this is inconsistent with what OpenLog does).


name: OpenLog
prototype: long OpenLog(BSTR LogFileName, BOOL Append);
summary: Opens a log file.
vb_example: world.openlog "mylog.txt", false
java_example: world.openlog("mylog.txt", false);
perl_example: $world->openlog("mylog.txt", false);
type_of_object: Method
see_also: CloseLog WriteLog IsLogOpen FlushLog
python_example: world.openlog("mylog.txt", False)
doc_name: logging
lua_example: OpenLog ("mylog.txt", false)
lua_notes: The Append flag is optional, and defaults to false.
description:
This opens a log file of the name "LogFileName", with optional appending to an existing file of the same name. No previous output lines are written (as may happen when you use the ‘open log’ dialog box), nor is a log-file preamble written. If you want to write those things to the script file, you must do them yourself (see WriteLog).

If an empty filename is supplied (that is, "") then the filename specified in the Logging configuration will be used, which lets you use substitutions in the name of the file (eg. the date).

return_value:
eOK: opened OK
eCouldNotOpenLogFile: unable to open the log file
eLogFileAlreadyOpen: log file was already open


name: WriteLog
prototype: long WriteLog(BSTR Message);
summary: Writes to the log file
vb_example: world.writelog "--- Message for the log file ---"
java_example: world.WriteLog("--- Message for the log file ---");
perl_example: $world->WriteLog("--- Message for the log file ---");
type_of_object: Method
see_also: OpenLog CloseLog IsLogOpen LogSend FlushLog
python_example: world.WriteLog("--- Message for the log file ---")
doc_name: logging
lua_example: WriteLog("--- Message for the log file ---")
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
This writes a message to the log file.

A "newline" is appended to the line if there is not already one there.

You can also use "LogSend" to send a message to the MUD, and log it, in a single function.

The data in the log file may not appear immediately if you view it in another application. To force the data to disk use the FlushLog function.

return_value:
eOK: written OK
eLogFileBadWrite: unable to write to the log file
eLogFileNotOpen: log file was not open


name: EnableTimer
prototype: long EnableTimer(BSTR TimerName, BOOL Enabled);
summary: Enables or disables an timer
vb_example: world.EnableTimer "heartbeat", TRUE
java_example: world.EnableTimer("heartbeat", true);
perl_example: $world->EnableTimer("heartbeat", true);
type_of_object: Method
see_also: ResetTimer ResetTimers DeleteTimer GetTimerList GetTimerList IsTimer GetTimer GetTimerInfo
python_example: world.EnableTimer("heartbeat", True)
doc_name: timers
lua_example: EnableTimer("heartbeat", true)
lua_notes: The enabled flag is optional, and defaults to true.
description:
Enables or disables the named timer.  An enabled timer is "active", otherwise it is ignored when processing periodic events.

return_value:
eInvalidObjectLabel: The timer name is not valid
eTimerNotFound: The named timer does not exist
eOK: completed OK


name: AddAlias
prototype: long AddAlias(BSTR AliasName, BSTR MatchText, BSTR ResponseText, long Flags, BSTR ScriptName);
summary: Adds an alias
vb_example: world.addalias "food_alias", "eat", "eat food", eEnabled, ""
java_example: world.AddAlias("food_alias", "eat", "eat food", eEnabled, "");
perl_example: $world->AddAlias("food_alias", "eat", "eat food", $eEnabled, "");
type_of_object: Method
python_example: world.AddAlias("food_alias", "eat", "eat food", eEnabled, "")
doc_name: aliases
lua_example: AddAlias("food_alias", "eat", "eat food", alias_flag.Enabled, "")
description:
Adds a alias to the list of aliases.

Name: name of this alias - may be empty (see rules for names below)
Match_text: what to match on
Response_text: what to send to the world
Flags: various flags, see list below
ScriptName: Which script subroutine to execute

Flags

The flags can be one or more of the constants below. For example, to enable the alias, and ignore the case of what was typed, the flags would be 33. Preferably use the constant declarations in your script file, and "OR" them together. E.g. 

VBscript: eEnabled or eIgnoreAliasCase
JScript:  eEnabled | eIgnoreAliasCase

VBscript constants:

const eEnabled = 1  ' enable alias
const eKeepEvaluating = 8 ' keep evaluating 
const eIgnoreAliasCase = 32  ' ignore case when matching
const eOmitFromLogFile = 64  ' omit this alias from the log file
const eAliasRegularExpression = 128 ' alias is regular expressions
const eExpandVariables = 512  ' expand variables like @direction
const eReplace = 1024  ' replace existing alias of same name
const eAliasSpeedWalk = 2048  ' interpret send string as a speed walk string
const eAliasQueue = 4096  ' queue this alias for sending at the speedwalking delay interval
const eAliasMenu = 8192  ' this alias appears on the alias menu
const eTemporary = 16384 ' temporary - do not save to world file

JScript constants:

var eEnabled = 1;   // same as for AddTrigger
var eKeepEvaluating = 8; // keep evaluating 
var eIgnoreAliasCase = 32; //  ignore case when matching
var eOmitFromLogFile = 64; // omit this alias from the log file
var eAliasRegularExpression = 128; // alias is regular expressions
var eExpandVariables = 512;  // expand variables like @direction
var eReplace = 1024;  //  replace existing alias of same name
var eAliasSpeedWalk = 2048;  // interpret send string as a speed walk string
var eAliasQueue = 4096;  // queue this alias for sending at the speedwalking delay interval
var eAliasMenu = 8192; //  this alias appears on the alias menu
var eTemporary = 16384; // temporary - do not save to world file


PerlScript constants:

my $eEnabled = 1;   # same as for AddTrigger
my $eKeepEvaluating = 8; # keep evaluating 

my $eIgnoreAliasCase = 32; #  ignore case when matching
my $eOmitFromLogFile = 64; # omit this alias from the log file
my $eAliasRegularExpression = 128; # alias is regular expressions
my $eExpandVariables = 512;  # expand variables like @direction
my $eReplace = 1024;  #  replace existing alias of same name
my $eAliasSpeedWalk = 2048; # interpret send string as a speed walk string 
my $eAliasQueue = 4096;  # queue this alias for sending at the speedwalking delay interval
my $eAliasMenu = 8192; #  this alias appears on the alias menu
my $eTemporary = 16384;  # temporary - do not save to world file


* 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 (_)

return_value:
eInvalidObjectLabel: The alias name is not valid
eAliasAlreadyExists: A alias of that name already exists
eAliasCannotBeEmpty: The "match_text" cannot be empty
eScriptNameNotLocated: The script name cannot be located in the script file
eBadRegularExpression: The regular expression could not be evaluated
eOK: added OK

see_also:
DeleteAlias EnableAlias GetAlias GetAliasList IsAlias GetAliasInfo EnableGroup EnableAliasGroup DeleteGroup DeleteAliasGroup SetAliasOption GetAliasOption ImportXML

lua_notes:
The script name is optional.

The alias flags are built into the "alias_flag" table, as follows:

Enabled = 1
KeepEvaluating = 8 
IgnoreAliasCase = 32
OmitFromLogFile = 64
RegularExpression = 128
ExpandVariables = 512
Replace = 1024
AliasSpeedWalk = 2048
AliasQueue = 4096
AliasMenu = 8192
Temporary = 16384


name: DeleteVariable
prototype: long DeleteVariable(BSTR VariableName);
summary: Deletes a variable
description: Deletes the named variable.
vb_example: world.DeleteVariable "myvariable"
java_example: world.DeleteVariable("myvariable");
perl_example: $world->DeleteVariable("myvariable");
type_of_object: Method
see_also: GetVariable GetVariableList SetVariable
python_example: world.DeleteVariable("myvariable")
doc_name: variables
lua_example: DeleteVariable("myvariable")
return_value:
eInvalidObjectLabel: The alias name is not valid
eVariableNotFound: The variable does not exist
eOK: deleted OK


name: ResetTimers
prototype: void ResetTimers();
summary: Resets all timers
vb_example: world.ResetTimers
java_example: world.ResetTimers();
perl_example: $world->ResetTimers();
return_value: Nothing.
type_of_object: Method
see_also: EnableTimer ResetTimer GetTimer GetTimerInfo GetTimerList AddTimer DeleteTimer IsTimer
python_example: world.ResetTimers
doc_name: timers
lua_example: ResetTimers()
description:
Resets all timers for the world. There is no return value.

This function will reset all periodic timers to fire from the appropriate interval from when the "ResetTimers" was done.

WARNING - timers that are not enabled will not be reset. Use EnableTimer first to make sure that timers are enabled, before resetting them, if necessary.


name: SetStatus
prototype: void SetStatus(BSTR Message);
summary: Sets the status line text
vb_example: world.setstatus "Current HP = " & Cstr (world.getvariable ("hp"))
java_example: world.SetStatus("Current HP = " + world.GetVariable("hp"));
perl_example: $world->SetStatus("Current HP = " . $world->GetVariable("hp"));
return_value: Nothing.
type_of_object: Method
see_also: Note Send SetCommand SetTitle
python_example: world.SetStatus("Current HP = " + world.GetVariable("hp"))
doc_name: utils
lua_example: SetStatus ("Current HP = ", GetVariable("hp"))
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
This sets the status line (at the bottom of the screen) to the nominated text. It is useful for keeping track of things. The status line is separately maintained for each world.


name: SetCommand
prototype: long SetCommand(BSTR Message);
summary: Sends text to the command window
vb_example: world.SetCommand "think Here is another command"
java_example: world.SetCommand("think Here is another command");
perl_example: $world->SetCommand("think Here is another command");
return_value: eCommandNotEmpty : Command area was not empty eOK: Set OK
type_of_object: Method
see_also: Send Note PasteCommand SetCommandSelection
python_example: world.SetCommand("think Here is another command")
doc_name: send
lua_example: SetCommand ("think Here is another command")
description:
This lets you send text to the command window. It will only act if the command window is currently empty (to avoid wiping out something you are typing).

Because of this you cannot test "setcommand" by typing it into the command window, because by definition, the command window will not be empty (it will have the "setcommand" in it). You must do it from a script, or an immediate window.


name: SetNotes
prototype: void SetNotes(BSTR Message);
summary: Sets the notes for the world.
vb_example: world.setnotes world.getnotes & vbcrlf _ & "This is a new line of notes"
java_example: world.setnotes(world.getnotes() + "\r\nThis is a new line of notes");
perl_example: $world->setnotes($world->getnotes() . "\r\nThis is a new line of notes");
return_value: Nothing.
type_of_object: Method
see_also: GetNotes
python_example: world.setnotes(world.getnotes + "\r\nThis is a new line of notes")
doc_name: note
lua_example: SetNotes (GetNotes () .. "\r\nThis is a new line of notes")
description:
This sets the notes for the current world.

Use the built-in constant "vbcrlf" to add a new line to the notes.

Use GetNotes if you want to get the existing notes (perhaps to append to them, as in the example).


name: NormalColour
prototype: long NormalColour(short WhichColour); void NormalColour(short WhichColour, long nNewValue);
summary: Gets/sets the RGB colour for one of the 8 ANSI normal colours
perl_example: $world->Note($world->normalcolour(3)); $world->redraw # redraw screen
return_value: This is a property. You can use it to find the current normal colour.
type_of_object: Property
see_also: BoldColour Redraw
doc_name: colours
lua_example: Note (GetNormalColour (2)) SetNormalColour (2, 254) Redraw() -- redraw screen
description:
You can use this property to get or set the RGB colours used for the 8 ANSI normal colours. You must specify *which* colour you want to get/set, in the range 1 to 8, as follows:

black = 1
red     = 2
green   = 3
yellow  = 4
blue    = 5
magenta = 6
cyan    = 7
white   = 8


If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description 
-------------------------------
vbBlack    &h00     Black 
vbRed      &hFF     Red 
vbGreen    &hFF00   Green 
vbYellow   &hFFFF   Yellow 
vbBlue     &hFF0000 Blue 
vbMagenta  &hFF00FF Magenta 
vbCyan     &hFFFF00 Cyan 
vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

You should be cautious doing frequent colour changes, because what happens is that you are changing the *palette* colour. What this means in practice is that if you change (say) the white colour (colour 8) then when new text appears on the screen it will be drawn in the new colour, however existing text will stay the old colour *until* it is redrawn (eg. is covered by a dialog box). This may lead to patchy bits of different colour on the screen.

You can have different colours on the screen (at the same time) by using the 16 custom colours, but only 16 different colours can be visible at once.

You can force a redraw of the whole world's window(s) by using the "Redraw" method.

See also BoldColour.

vb_example:
world.note world.normalcolour (3)  
world.normalcolour (3) = vbGreen  
world.normalcolour (8) = &h303030 
world.redraw   ' redraw screen

java_example:
world.note(world.normalcolour(3)); 
world.normalcolour (3) = 0xFF00;   
world.normalcolour (8) = 0x303030;  
world.redraw();  // redraw screen

python_example:
world.note(world.normalcolour(3)) 
world.normalcolour (3) = 0xFF00   
world.normalcolour (8) = 0x303030  
world.redraw  # redraw screen

lua_notes:
Lua implements this as two functions:

GetNormalColour - gets the normal colour
SetNormalColour - sets the normal colour


name: BoldColour
prototype: long BoldColour(short WhichColour); void BoldColour(short WhichColour, long nNewValue);
summary: Gets/sets the RGB colour for one of the 8 ANSI bold colours
vb_example: world.note world.boldcolour (2) world.boldcolour (2) = vbRed world.redraw ' redraw screen
java_example: world.Note(world.boldcolour(2)); world.boldcolour(2) = 0xFF; world.redraw(); // redraw screen
perl_example: $world->Note($world->boldcolour(2));
return_value: This is a property. You can use it to find the current bold colour.
type_of_object: Property
see_also: NormalColour Redraw
python_example: world.Note(world.boldcolour(2))
doc_name: colours
lua_example: Note (GetBoldColour (2)) SetBoldColour (2, 254) Redraw() -- redraw screen
description:
You can use this property to get or set the RGB colours used for the 8 ANSI bold colours. You must specify *which* colour you want to get/set, in the range 1 to 8, as follows:

black = 1
red     = 2
green   = 3
yellow  = 4
blue    = 5
magenta = 6
cyan    = 7
white   = 8


If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description 
-------------------------------
vbBlack    &h00     Black 
vbRed      &hFF     Red 
vbGreen    &hFF00   Green 
vbYellow   &hFFFF   Yellow 
vbBlue     &hFF0000 Blue 
vbMagenta  &hFF00FF Magenta 
vbCyan     &hFFFF00 Cyan 
vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

You should be cautious doing frequent colour changes, because what happens is that you are changing the *palette* colour. What this means in practice is that if you change (say) the white colour (colour 8) then when new text appears on the screen it will be drawn in the new colour, however existing text will stay the old colour *until* it is redrawn (eg. is covered by a dialog box). This may lead to patchy bits of different colour on the screen.

You can have different colours on the screen (at the same time) by using the 16 custom colours, but only 16 different colours can be visible at once.

You can force a redraw of the whole world's window(s) by using the "Redraw" method.

See also NormalColour.

lua_notes:
Lua implements this as two functions:

GetBoldColour - gets the bold colour
SetBoldColour - sets the bold colour


name: CustomColourText
prototype: long CustomColourText(short WhichColour); void CustomColourText(short WhichColour, long nNewValue);
summary: Sets the RGB value for the text of a custom colour
vb_example: world.note world.customcolourtext (10) world.customcolourtext (14) = vbBlue
java_example: world.Note(world.customcolourtext(10)); world.customcolourtext(14) = 0xFF0000;
perl_example: $world->Note($world->customcolourtext(10));
return_value: This is a property. You can use it to find the current custom text colour.
type_of_object: Property
see_also: CustomColourBackground NormalColour BoldColour SetCustomColourName GetCustomColourName
python_example: world.Note(world.customcolourtext(10)) world.customcolourtext(14) = 0xFF0000
doc_name: colours
lua_example: Note(GetCustomColourText (10)) SetCustomColourText (14, ColourNameToRGB ("brown"))
description:
You can use this property to get or set the RGB colours used for the text (foreground) of the 16 custom colours. You must specify *which* colour you want to get/set, in the range 1 to 16.

If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description 
-------------------------------
vbBlack    &h00     Black 
vbRed      &hFF     Red 
vbGreen    &hFF00   Green 
vbYellow   &hFFFF   Yellow 
vbBlue     &hFF0000 Blue 
vbMagenta  &hFF00FF Magenta 
vbCyan     &hFFFF00 Cyan 
vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

You should be cautious doing frequent colour changes, because what happens is that you are changing the *palette* colour. What this means in practice is that if you change (say) the white colour (colour 8) then when new text appears on the screen it will be drawn in the new colour, however existing text will stay the old colour *until* it is redrawn (eg. is covered by a dialog box). This may lead to patchy bits of different colour on the screen.

You can have different colours on the screen (at the same time) by using the 16 custom colours, but only 16 different colours can be visible at once.

You can force a redraw of the whole world's window(s) by using the "Redraw" method.

See also NormalColour, BoldColour and CustomColourBackground.

lua_notes:
Lua implements this as two functions:

GetCustomColourText - gets the custom colour text
SetCustomColourText - sets the custom colour text


name: CustomColourBackground
summary: Sets the RGB value for the background of a custom colour
vb_example: world.note world.customcolourbackground (10) world.customcolourbackground (14) = vbBlack
java_example: world.Note(world.customcolourbackground(10)); world.customcolourbackground(14) = 0;
perl_example: $world->Note($world->customcolourbackground(10));
return_value: This is a property. You can use it to find the current custom background colour.
type_of_object: Property
see_also: CustomColourText NormalColour BoldColour SetCustomColourName GetCustomColourName
python_example: world.Note(world.customcolourbackground(10)) world.customcolourbackground(14) = 0
doc_name: colours
lua_example: Note (GetCustomColourBackground (10)) SetCustomColourBackground (14, 0)
prototype:
long CustomColourBackground(short WhichColour);
void CustomColourBackground(short WhichColour, long nNewValue);

description:
You can use this property to get or set the RGB colours used for the background of the 16 custom colours. You must specify *which* colour you want to get/set, in the range 1 to 16.

If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description 
-------------------------------
vbBlack    &h00     Black 
vbRed      &hFF     Red 
vbGreen    &hFF00   Green 
vbYellow   &hFFFF   Yellow 
vbBlue     &hFF0000 Blue 
vbMagenta  &hFF00FF Magenta 
vbCyan     &hFFFF00 Cyan 
vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

You should be cautious doing frequent colour changes, because what happens is that you are changing the *palette* colour. What this means in practice is that if you change (say) the white colour (colour 8) then when new text appears on the screen it will be drawn in the new colour, however existing text will stay the old colour *until* it is redrawn (eg. is covered by a dialog box). This may lead to patchy bits of different colour on the screen.

You can have different colours on the screen (at the same time) by using the 16 custom colours, but only 16 different colours can be visible at once.

You can force a redraw of the whole world's window(s) by using the "Redraw" method.

See also NormalColour, BoldColour and CustomColourText.

lua_notes:
Lua implements this as two functions:

GetCustomColourBackground - gets the custom colour background
SetCustomColourBackground - sets the custom colour background


name: Redraw
prototype: void Redraw();
summary: Schedules a redraw for all windows for this world
vb_example: Redraw
java_example: Redraw();
perl_example: $world->Redraw();
return_value: Nothing.
type_of_object: Method
see_also: NormalColour BoldColour NoteColour CustomColourBackground CustomColourText Repaint
python_example: Redraw
lua_example: Redraw ()
description:
Schedules a redraw of all windows for this world. Use this after changing colours, or changing miniwindows.

Note that the main window is not actually redrawn at this point, however it is scheduled for redraw next time through the main event loop.


name: ResetTimer
prototype: long ResetTimer(BSTR TimerName);
summary: Resets a named timer
vb_example: world.ResetTimer "mytimer"
java_example: world.ResetTimer("mytimer");
perl_example: $world->ResetTimer("mytimer");
type_of_object: Method
see_also: EnableTimer ResetTimers GetTimer GetTimerInfo GetTimerList AddTimer DeleteTimer
python_example: world.ResetTimer("mytimer")
doc_name: timers
lua_example: ResetTimer("mytimer")
description:
Resets the named timer.

Also see ResetTimers to reset all timers.

WARNING - timers that are not enabled will not be reset. Use EnableTimer first to make sure the timer is enabled, before resetting it, if necessary.

return_value:
eInvalidObjectLabel: The timer name is not valid
eTimerNotFound: The timer does not exist
eOK: reset OK


name: SetOutputFont
prototype: void SetOutputFont(BSTR FontName, short PointSize);
summary: Sets the font for the output window.
vb_example: world.SetOutputFont "Lucida Console", 9
java_example: world.SetOutputFont("Lucida Console", 9);
perl_example: $world->SetOutputFont("Lucida Console", 9);
return_value: Nothing.
type_of_object: Method
see_also: SetInputFont
python_example: world.SetOutputFont("Lucida Console", 9)
doc_name: options
lua_example: SetOutputFont ("Lucida Console", 9)
description:
Use this to change the output font. The *entire* window font changes, you cannot change individual lines or words.

Also see SetInputFont.


name: SetInputFont
prototype: void SetInputFont(BSTR FontName, short PointSize, short Weight, boolean Italic);
summary: Sets the font for the input window
vb_example: world.SetInputFont "Lucida Console", 15, 400, 0
java_example: world.SetInputFont("Lucida Console", 15, 400, 0);
perl_example: $world->SetInputFont("Lucida Console", 15, 400, 0);
return_value: Nothing.
type_of_object: Method
see_also: SetOutputFont
python_example: world.SetInputFont("Lucida Console", 15, 400, 0)
doc_name: options
lua_example: SetInputFont("Lucida Console", 15, 400, 0)
lua_notes: The Italic flag is optional, and defaults to false.
description:
Use this to change the command window font. The *entire* window font changes, you cannot change individual lines or words.

Also see SetOutputFont.

The weight can be one of:

 (Don't Care) 0 
 Thin 100 
 Extralight 200 
 Light 300 
 Normal 400 
 Medium 500 
 Semibold 600 
 Bold 700 
 Extrabold 800 
 Heavy 900 

 Italic can be true or false.


name: SendToNotepad
prototype: boolean SendToNotepad(BSTR Title, BSTR Contents);
summary: Creates a notepad and sends text to it
vb_example: world.SendToNotepad "Nick's window", "Hello, world" & _ vbcrlf & "another line"
java_example: world.SendToNotepad("Nick's window", "Hello, world\r\nanother line")
perl_example: $world->SendToNotepad("Nick's window", "Hello, world\r\nanother line");
return_value: 0: Window not created. 1: Window created OK
type_of_object: Method
python_example: world.SendToNotepad("Nick's window", "Hello, world\r\nanother line")
doc_name: notepad
lua_example: SendToNotepad ("Nick's window", "Hello, world\r\nanother line")
lua_notes: You can supply multiple arguments after the notepad name, which are concatenated together.
description:
Creates a notepad window with the nominated title and contents.

The contents are copied "as is" without a trailing newline. If you want a newline you will need to add it yourself. The built-in constant "vbcrlf" can be used for this purpose in Visual Basic.

see_also:
GetNotepadLength GetNotepadText AppendToNotepad ActivateNotepad ReplaceNotepad CloseNotepad SaveNotepad GetNotepadList NotepadReadOnly


name: AppendToNotepad
prototype: boolean AppendToNotepad(BSTR Title, BSTR Contents);
summary: Appends text to a notepad window
vb_example: world.AppendToNotepad "Nick's window", "More stuff" + vbcrlf
java_example: world.AppendToNotepad("Nick's window", "More stuff\r\n");
perl_example: $world->AppendToNotepad("Nick's window", "More stuff\r\n");
return_value: 0: Could not do it. 1: Appended OK
type_of_object: Method
python_example: world.AppendToNotepad("Nick's window", "More stuff\r\n")
doc_name: notepad
lua_example: AppendToNotepad("Nick's window", "More stuff\r\n", "another line")
lua_notes: You can supply multiple arguments after the notepad name, which are concatenated together.
description:
Appends the text to a notepad window of the given title. If no such window exists, it is created.

The function "AppendToNotepad" does not activate (bring to the front) the notepad window. However the function "ActivateNotepad" can be used to do that.

You can use world.activate to activate the world itself (eg. you might want to do that after creating a notepad window).

You might use GetNotepadLength to check if there is likely to be room in the notepad for the new text.

see_also:
GetNotepadLength GetNotepadText SendToNotepad ActivateNotepad Activate ReplaceNotepad CloseNotepad SaveNotepad GetNotepadList


name: ActivateNotepad
prototype: boolean ActivateNotepad(BSTR Title);
summary: Activates a notepad window
description: Activates (makes the active window) the notepad window of the given title.
vb_example: world.ActivateNotepad "Nick's window"
java_example: world.ActivateNotepad("Nick's window");
perl_example: $world->ActivateNotepad("Nick's window");
return_value: 0: Could not do it. 1: Activated OK
type_of_object: Method
python_example: world.ActivateNotepad("Nick's window")
doc_name: notepad
lua_example: ActivateNotepad("Nick's window")
see_also:
GetNotepadLength GetNotepadText Activate SendToNotepad ReplaceNotepad AppendToNotepad CloseNotepad SaveNotepad ActivateClient GetNotepadList NotepadReadOnly


name: Activate
prototype: void Activate();
summary: Activates the world window
vb_example: world.activate
java_example: world.activate();
perl_example: $world->activate;
return_value: Nothing.
type_of_object: Method
see_also: ActivateNotepad ReplaceNotepad AppendToNotepad SendToNotepad Open ActivateClient
python_example: world.activate
lua_example: Activate()
description:
Activates the main (first) window for this world. If you have multiple windows open then the first one created will be activated.


name: GetWorld
prototype: IDispatch* GetWorld(BSTR WorldName);
summary: Gets an object reference to the named world
type_of_object: Method
see_also: GetWorldList Open GetWorldById
doc_name: world
description:
Returns an object which can be used to refer to another world.

You should be very cautious about storing the object reference of the world in a global variable, because if the world is closed then that reference becomes invalid, which will very likely lead to an access violation (program crash). You are better off using "world.getworld (name)" every time you need to get a reference to the world, and checking if it "is nothing" as in the example.

You could use a small variation on the examples above to write your own "send to all worlds" or something similar.

If more than one world has the same name, only the first one matching that name will be returned. If this is likely, use GetWorldIDList to get a list of unique IDs (identifiers) and then use GetWorldById instead of GetWorld.

vb_example:
' --------------------------------------------------
' Example showing sending a message to another world
' --------------------------------------------------

sub SendToWorld (name, message)
dim otherworld

  set otherworld = world.getworld (name)

  if otherworld is nothing then
    world.note "World " + name + " is not open"
    exit sub
  end if

  otherworld.send message

end sub

java_example:
// --------------------------------------------------
// Example showing sending a message to another world
// --------------------------------------------------

function SendToWorld (name, message)
{
 var otherworld

   otherworld = world.getworld (name);

  if (otherworld == null)
    {
    world.note("World " + name + " is not open");
    return;
    }

  otherworld.send(message);

}

SendToWorld ("MyOtherWorld", "say Hi there");

perl_example:
# --------------------------------------------------
# Example showing sending a message to another world
# --------------------------------------------------

sub SendToWorld {
 my ($name, $message) = @_;

 my $otherworld;

 $otherworld = $world->getworld ($name);

  if (!defined ($otherworld))
    {
    $world->note("World " . $name . " is not open");
    return;
    }

  $otherworld->send($message);

}

SendToWorld ("MyOtherWorld", "say Hi there");

return_value:
An object reference to the named world, if it was found.
Otherwise NULL.

In Vbscript use the test "is nothing" to see if the reference is to a valid world.
In JavaScript use the test "== null" to see if the reference is to a valid world.
In PerlScript use the test "defined ()" to see if the reference is to a valid world.
In Python use the test "if (ref)" to see if the reference is to a valid world.
In Lua use the test "if ref == nil" to see if the reference is to a valid world.

python_example:
# --------------------------------------------------
# Example showing sending a message all worlds
# --------------------------------------------------

def SendToAllWorlds (message):
  worldlist = world.GetWorldList
  if (worldlist):
    for w in worldlist : world.GetWorld (w).Send (message)

SendToAllWorlds ("say Hi there")

lua_example:
-- --------------------------------------------------
-- Example showing sending a message to another world
-- --------------------------------------------------

function SendToWorld (name, message)

local otherworld

  otherworld = GetWorld (name)

  if otherworld == nil then
    Note ("World " .. name .. " is not open")
    return
  end

  Send (otherworld, message)

  -- alternative syntax:   otherworld:Send (message)

end -- of SendToWorld

SendToWorld ("MyOtherWorld", "say Hi there")

lua_notes:
Since Lua does not use the COM (Component Object Model) interface getting world 
variables works differently than for other languages.

The function GetWorld returns a "userdata" item which contains the address of the other world.

You can pass this as the first argument to any MUSHclient function and that 
function will then be applied to the target world.

eg.

otherworld = GetWorld ('pennmush')

Send (otherworld, "sigh")  --> send "sigh" to 'pennmush' world


An alternative syntax is to put the world name first, followed by a colon (not a dot), 
like this:

otherworld:Send ("sigh")  --> send "sigh" to 'pennmush' world

Every function call that is passed a different world name is automatically checked to see
if the world is still open, so it is safe to use the world variable some time after
obtaining it (although an error will be raised if you do so).

You can protect function calls using pcall, so you might do this to see if the
world is still valid:

-- try to call WorldName for world 'otherworld'

ok = pcall (WorldName, otherworld)

if ok then
  Note "otherworld is OK"
else
  Note "otherword has closed"
end


name: GetWorldList
prototype: VARIANT GetWorldList();
summary: Gets the list of open worlds - returning their world names
vb_example: for each name in world.GetWorldList world.note name next
perl_example: foreach $item (Win32::OLE::in ($world->GetWorldList)) { $world->note($item); }
type_of_object: Method
see_also: GetWorld GetWorldIdList GetWorldById
python_example: worldlist = world.GetworldList if (worldlist ): for w in worldlist : world.Note (w)
doc_name: world
lua_example: for k, v in pairs (GetWorldList()) do Note (v) end
lua_notes: See the description for GetWorld for more discussion about using "world" variables in Lua.
description:
Returns a variant array which is a list of all open worlds.

If more than one world has the same name you may get duplicates - to be able to refer to each world uniquely, use GetWorldIdList.

java_example:
worldlist = new VBArray(world.GetworldList()).toArray();

if (worldlist)  // if not empty
 for (i = 0; i < worldlist.length; i++)
   world.note(worldlist [i]);

return_value:
If there are no worlds then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the worlds. Use "ubound" to find the number of worlds in the list. You can then use "GetWorld" to return a reference to that world.


name: FixupHTML
prototype: BSTR FixupHTML(BSTR StringToConvert);
summary: Fixes up text for writing as HTML
vb_example: world.note world.FixupHTML ("I will go <north> here")
java_example: world.note(world.FixupHTML("I will go <north> here"));
perl_example: $world->note($world->FixupHTML("I will go <north> here"));
type_of_object: Method
python_example: world.note(world.FixupHTML("I will go <north> here"))
doc_name: utils
lua_example: Note(FixupHTML("I will go <north> here"))
description:
This translates text so that it can be logged as HTML.

It will translate "<", ">" and "&" to the HTML equivalents (eg. &lt; ), otherwise a line like this: "go <north>" would not log correctly as HTML.

This is intended for use in scripts that are used to log to the log file, where you are writing out a log file in HTML.

return_value:
The supplied string with the following characters replaced with the HTML "escaped" equivalents:

<   &lt;
>   &gt;
&   &amp;
"   &quot;


name: LogOutput
prototype: short LogOutput;
summary: The property of whether MUD output is logged to the log file
description: Set to 1 to log output to the log file, 0 to not log
return_value: This is a property. You can use it to find whether MUD output is currently logged.
type_of_object: Property
see_also: LogInput LogNotes
doc_name: logging
vb_example:
world.logoutput = 1   ' log output
world.logoutput = 0   ' don't log output
world.note world.logoutput  ' display whether output is logged

java_example:
world.logoutput = 1;   // log output
world.logoutput = 0;   // don't log output
world.note(world.logoutput);  // display whether output is logged

perl_example:
$world->{logoutput} = 1;   # log output
$world->{logoutput} = 0;   # don't log output
$world->note($world->{logoutput});  # display whether output is logged

python_example:
world.logoutput = 1   # log output
world.logoutput = 0   # don't log output
world.note(world.logoutput)  # display whether output is logged

lua_example:
SetLogOutput (true)   -- log output
SetLogOutput (false)   -- don't log output
Note(GetLogOutput ())  -- display whether output is logged

lua_notes:
Lua implements this as two functions:

GetLogOutput - gets whether output is logged
SetLogOutput - sets whether output is logged

The argument is optional, and defaults to true.


name: Replace
prototype: BSTR Replace(BSTR Source, BSTR SearchFor, BSTR ReplaceWith, boolean Multiple);
summary: Replaces one substring with another
vb_example: world.Note world.Replace ("go north, go east", "go", "walk", true)
java_example: world.Note(world.Replace("go north, go east", "go", "walk", true));
perl_example: $world->Note($world->Replace("go north, go east", "go", "walk", true));
return_value: The source string with one or more occurences of "SearchFor" replaced by "ReplaceWith".
type_of_object: Method
see_also: FixupHTML FixupEscapeSequences Trim
python_example: world.Note(world.Replace("go north, go east", "go", "walk", True))
doc_name: utils
lua_example: Note(Replace("go north, go east", "go", "walk", true))
lua_notes: The Multiple flag is optional, and defaults to true.
description:
This is a utility function for doing a "find and replace" inside a string.

It is intended to simplify writing scripts that need to replace things.

If "Multiple" is true then all occurences are replaced, otherwise only the first one is replaced.


name: FixupEscapeSequences
prototype: BSTR FixupEscapeSequences(BSTR Source);
summary: Converts "escape sequences" like \t to their equivalent codes.
vb_example: world.send world.FixupEscapeSequences ("go north \n go west")
return_value: The source string with any escape sequences (as described above) replaced by the equivalent code.
type_of_object: Method
see_also: FixupHTML Replace Trim
python_example: world.Send(world.FixupEscapeSequences(mystring))
doc_name: utils
description:
This provides a script interface to the internal routine used by MUSHclient to convert special "escape" sequences into the ASCII equivalents.

The following sequences are recognised:

 \a Bell (alert)
 \b Backspace
 \f Formfeed
 \n New line
 \r Carriage return
 \t Horizontal tab
 \v Vertical tab
 \' Single quotation mark
 \" Double quotation mark
 \\ Backslash
 \? Literal question mark
 \xhh ASCII character in hexadecimal notation

java_example:
world.Send(world.FixupEscapeSequences(mystring));

// In JScript a quoted sequence like "\n" will already 
// be interpreted by the JScript interpreter

perl_example:
$world->Send($world->FixupEscapeSequences($mystring));

// In PerlScript a quoted sequence like "\n" will already
// be interpreted by the PerlScript interpreter

lua_example:
Send(FixupEscapeSequences(mystring))

-- In Lua a quoted sequence like "\n" will already 
-- be interpreted by the Lua interpreter


name: Trim
prototype: BSTR Trim(BSTR Source);
summary: Trims leading and trailing spaces from a string
vb_example: world.note "*" & world.trim (" mystring ") & "*"
java_example: world.Note("*" + world.Trim(" mystring ") + "*");
perl_example: $world->Note("*" . $world->Trim(" mystring ") . "*");
return_value: The source string with any leading or trailing spaces removed.
type_of_object: Method
see_also: FixupHTML Replace FixupEscapeSequences
python_example: world.Note("*" + world.Trim(" mystring ") + "*")
doc_name: utils
lua_example: Note("*" .. Trim(" mystring ") .. "*")
description:
This is supplied as a convenient way of removing leading and trailing spaces from a supplied string.


name: ReplaceNotepad
prototype: boolean ReplaceNotepad(BSTR Title, BSTR Contents);
summary: Replaces text in a notepad window
vb_example: world.ReplaceNotepad "Nick's window", "New contents" + vbcrlf
java_example: world.ReplaceNotepad("Nick's window", "New contents\r\n");
perl_example: $world->ReplaceNotepad("Nick's window", "New contents\r\n");
return_value: 0: Could not do it. 1: Replaced OK
type_of_object: Method
python_example: world.ReplaceNotepad("Nick's window", "New contents\r\n")
doc_name: notepad
lua_example: ReplaceNotepad("Nick's window", "New contents\r\n")
lua_notes: You can supply multiple arguments after the notepad name, which are concatenated together.
description:
Replaces  the text in a notepad window of the given title. If no such window exists, it is created.

The function "ReplaceNotepad" does not activate (bring to the front) the notepad window. However the function "ActivateNotepad" can be used to do that.

You can use world.activate to activate the world itself (eg. you might want to do that after creating a notepad window).

see_also:
GetNotepadLength GetNotepadText SendToNotepad ActivateNotepad Activate AppendToNotepad CloseNotepad SaveNotepad GetNotepadList NotepadReadOnly


name: GetTriggerInfo
prototype: VARIANT GetTriggerInfo(BSTR TriggerName, short InfoType);
summary: Gets details about a named trigger
vb_example: world.note world.gettriggerinfo ("monster", 2)
java_example: /world.note(world.gettriggerinfo ("monster", 2));
perl_example: /$world->note ($world->gettriggerinfo ("monster", 2));
type_of_object: Method
python_example: world.note(world.gettriggerinfo ("monster", 2))
doc_name: triggers
lua_example: Note (GetTriggerInfo ("monster", 2))
description:
Gets details about the specified trigger.

You can obtain one of 38 "types" of information about the trigger by specifying an "InfoType". The possible InfoTypes are:

 1: What to match on (string)
 2: What to send (string)
 3: Sound to play (string)
 4: Script procedure name (string)
 5: Omit from log (boolean)
 6: Omit from output (boolean)
 7: Keep evaluating (boolean)
 8: Enabled (boolean)
 9: Regular expression (boolean)
10: Ignore case (boolean)
11: Repeat on same line (boolean)
12: Play sound if inactive (boolean)
13: Expand variables (boolean)
14: Which wildcard to send to clipboard (short)
15: Send to - see below (short)
16: Sequence (short)
17: Match on (colour/style) (short)
18: Change to style (short)
19: Change to colour (short)
20: Invocation count (long)
21: Times matched (long)
22: Date/time trigger last matched (date)
23: 'temporary' flag (boolean)
24: Trigger was included from an include file (boolean)
25: Make wildcards lower case flag (boolean)
26: Group name (string)
27: Variable name (string)
28: User option value (long)
29: Other colour foreground colour value (long)
30: Other colour backgroundground colour value (long)
31: Number of matches to regular expression (most recent match) (long)
32: The string we matched against (last trigger text matched against) (string)
33: Executing-script flag (boolean)
34: Script is valid flag (boolean)
35: Error number from PCRE when evaluating last match (long), zero if none
36: 'one shot' flag (boolean)
37: Time taken (in seconds) to test triggers (including un-matched ones) (double)
38: Number of attempts to match this trigger (long)



101: Wildcard %1 from last time it matched
102: Wildcard %2 from last time it matched
103: Wildcard %3 from last time it matched
104: Wildcard %4 from last time it matched
105: Wildcard %5 from last time it matched
106: Wildcard %6 from last time it matched
107: Wildcard %7 from last time it matched
108: Wildcard %8 from last time it matched
109: Wildcard %9 from last time it matched
110: Wildcard %0 from last time it matched

Other wildcards can be extracted by using GetTriggerWildcard.

The word in brackets indicates the "type" of data returned.
  String: a character string (eg. "north")
  Boolean: TRUE or FALSE
  Short: a 16-bit number
  Long: a 32-bit number

The field "send to" indicates where the trigger response (item 2) gets sent:

 0: World     
 1: Command window
 2: Output window
 3: Status line
 4: Notepad (new)
 5: Notepad (append)
 6: Log File   
 7: Notepad (replace)
 8: Command queue
 9: Send To Variable
10: Execute (re-parse as command)
11: Speedwalk (send text is speedwalk, queue it)
12: Script (send to script engine)
13: Immediate (send to world in front of speedwalk queue)
14: Script - after omit (send to script engine, after omitting matching line from output)

The field "invocation count" is a count of how many times the script routine was called.
The field "times matched" is a count of how many times the trigger matched. These two would normally be the same, unless scripting was disabled, or there was an error in the script file.

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

For a detailed description about the meanings of the fields, see AddTrigger.

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

If you want to information about a trigger in another plugin, or the global MUSHclient triggers, use "GetPluginTriggInfo".

return_value:
The specified information about the trigger, as described above.
An EMPTY variant, if the trigger does not exist.
A NULL variant if the trigger name is invalid.
A NULL variant if the InfoType is not a valid type.

see_also:
AddTrigger DeleteTrigger EnableTrigger GetTriggerList IsTrigger GetTrigger GetInfo GetPluginTriggerInfo SetTriggerOption GetTriggerOption GetTriggerWildcard

lua_notes:
Lua returns nil where applicable instead of an "empty variant" or "null variant".

The "SendTo" field can be looked up using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0
sendto.command = 1
sendto.output = 2
sendto.status = 3
sendto.notepad = 4
sendto.notepadappend = 5
sendto.logfile = 6
sendto.notepadreplace = 7
sendto.commandqueue = 8
sendto.variable = 9
sendto.execute = 10
sendto.speedwalk = 11
sendto.script = 12
sendto.immediate = 13
sendto.scriptafteromit = 14


name: GetAliasInfo
prototype: VARIANT GetAliasInfo(BSTR AliasName, short InfoType);
summary: Gets details about an alias
vb_example: world.note world.GetAliasInfo ("my_alias", 2)
java_example: /world.note(world.GetAliasInfo ("my_alias", 2));
perl_example: /$world->note ($world->GetAliasInfo ("my_alias", 2));
type_of_object: Method
python_example: world.note(world.GetAliasInfo ("my_alias", 2))
doc_name: aliases
lua_example: Note (GetAliasInfo("my_alias", 2))
description:
Gets details about the specified alias name.

You can obtain one of 31 "types" of information about the alias by specifying an "InfoType". The possible InfoTypes are:

 1: What to match on (string)
 2: What to send (string)
 3: Script procedure name (string)
 4: Omit from log (boolean)
 5: Omit from output (boolean)
 6: Enabled (boolean)
 7: Regular expression  (boolean)
 8: Ignore case (boolean)
 9: Expand variables (boolean)
10: Invocation count (long)
11: Times matched (long)
12: Menu (boolean)
13: Date/time alias last matched (date)
14: 'temporary' flag (boolean)
15: Alias was included from an include file (boolean)
16: Group name (string)
17: Variable name to set (string)
18: Send-to location (long)
19: 'keep-evaluating' flag (boolean)
20: Sequence number (long)
21: 'echo alias' flag (boolean)
22: 'omit from command history' flag (boolean)
23: User option value (long)
24: Number of matches to regular expression (most recent match) (long)
25: The string we matched against (last alias text matched against) (string)
26: Executing-script flag (boolean)
27: Script is valid flag (boolean)
28: Error number from PCRE when evaluating last match (long), zero if none
29: 'one shot' flag (boolean)
30: Time taken (in seconds) to test aliases (including un-matched ones) (double)
31: Number of attempts to match this alias (long)

101: Wildcard %1 from last time it matched
102: Wildcard %2 from last time it matched
103: Wildcard %3 from last time it matched
104: Wildcard %4 from last time it matched
105: Wildcard %5 from last time it matched
106: Wildcard %6 from last time it matched
107: Wildcard %7 from last time it matched
108: Wildcard %8 from last time it matched
109: Wildcard %9 from last time it matched
110: Wildcard %0 from last time it matched

Other wildcards can be extracted by using GetAliasWildcard.

The word in brackets indicates the "type" of data returned.
  String: a character string (eg. "north")
  Boolean: TRUE or FALSE
  Long: a 32-bit number

The field "invocation count" is a count of how many times the script routine was called.
The field "times matched" is a count of how many times the alias matched. These two would normally be the same, unless scripting was disabled, or there was an error in the script file.

The meanings of the "send-to" field are:

 0: World     
 1: Command window
 2: Output window
 3: Status line
 4: Notepad (new)
 5: Notepad (append)
 6: Log File   
 7: Notepad (replace)
 8: Command queue
 9: Send To Variable
10: Execute (re-parse as command)
11: Speedwalk (send text is speedwalk, queue it)
12: Script (send to script engine)
13: Immediate (send to world in front of speedwalk queue)
14: Script - after omit 

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

See AddAlias for a description of the meanings of the fields.

return_value:
The specified information about the alias, as described above.
An EMPTY variant, if the alias does not exist.
A NULL variant if the alias name is invalid.
A NULL variant if the InfoType is not a valid type.

see_also:
AddAlias DeleteAlias EnableAlias GetAliasList IsAlias GetAlias GetInfo SetAliasOption GetAliasOption GetAliasWildcard

lua_notes:
Lua returns nil where applicable instead of an "empty variant" or "null variant".

The "SendTo" field can be looked up using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0
sendto.command = 1
sendto.output = 2
sendto.status = 3
sendto.notepad = 4
sendto.notepadappend = 5
sendto.logfile = 6
sendto.notepadreplace = 7
sendto.commandqueue = 8
sendto.variable = 9
sendto.execute = 10
sendto.speedwalk = 11
sendto.script = 12
sendto.immediate = 13
sendto.scriptafteromit = 14


name: EvaluateSpeedwalk
prototype: BSTR EvaluateSpeedwalk(BSTR SpeedWalkString)
summary: Evaluates a speed walk string
vb_example: world.note world.EvaluateSpeedwalk ("4n3esuwdLW")
java_example: world.note(world.EvaluateSpeedwalk ("4n3esuwdLW"));
perl_example: $world->note($world->EvaluateSpeedwalk ("4n3esuwdLW"));
type_of_object: Method
see_also: ReverseSpeedwalk Queue Send
python_example: world.note(world.EvaluateSpeedwalk ("4n3esuwdLW"))
doc_name: speed_walking
lua_example: Note(EvaluateSpeedwalk ("4n3esuwdLW"))
description:
Converts a supplied string based on the rules for "speed walking".

For example:

#4n3esuwdLW

This would move you: 4 times North, 3 times East, South, Up, West, Down and then "lock west"

Actions

Actions recognised are: C:close; O:open; L:lock; K:unlock (or nothing for no special action, just walk in that direction)

Directions

The directions recognised are: N:north, S:south, E:east, W:west, U:up, D:down.

Filler

You can also enter "F" for a speed walk "filler". This is for MUDs that reject multiple identical commands. For example, if you need to walk West 30 times, but your MUD disconnects you after 20 identical commands, enter:

#15w f 15w

The exact text that is sent by the "filler" is customisable from the "Input" world configuration screen. A suggested filler command would be something harmless, like LOOK.

Multipliers

You may also enter a one or two-digit multiplier in the range 1 to 99. The multiplier affects the *next* direction entered, e.g. "5s" means go South 5 times.

Spaces are accepted in the speed walk string, and ignored.

Non-standard directions

You can supply non-standard directions (eg. NE for NorthEast) by putting them in brackets.

For example:

5N 4W (ne) (say open sesame) 5U 4(se)

You can also supply the "reverse" direction after a "/" character, in case you want to reverse the speedwalk direction later.

For example:

5N 4W (ne/sw) (say open sesame/kick door) 5U 4(se/nw)

When speedwalking, only the characters before the slash are evaluated.

return_value:
The supplied string, converted from speed walk characters to directions, with a "newline" between each direction.
If there is an error in the speed walk string then the first character of the returned string will be an asterisk ("*"), and the rest will be an English error message.


name: ReverseSpeedwalk
prototype: BSTR ReverseSpeedwalk(BSTR SpeedWalkString)
summary: Reverses a speed walk string
vb_example: world.note world.ReverseSpeedwalk ("4n3esuwdLW(ne/sw)")
java_example: world.note(world.ReverseSpeedwalk ("4n3esuwdLW(ne/sw)"));
perl_example: $world->note($world->ReverseSpeedwalk ("4n3esuwdLW(ne/sw)"));
type_of_object: Method
see_also: EvaluateSpeedwalk RemoveBacktracks
python_example: world.note(world.ReverseSpeedwalk ("4n3esuwdLW(ne/sw)"))
doc_name: speed_walking
lua_example: Note(ReverseSpeedwalk ("4n3esuwdLW(ne/sw)"))
description:
Reverses a supplied string based on the rules for "speed walking". See EvaluateSpeedwalk for a detailed description of those rules.

For example:

4n 3e s u w d LW

When reversed, this would become:

LE U E D N 3W 4S 

If you supply a "special string" in parentheses, then the order of the words in parentheses is reversed. This lets you do special actions (eg. NE for NorthEast), and supply the reverse direction.

For example:

4n (se/nw)(in/out)

This would become:

(out/in) (nw/se) 4S

return_value:
The supplied string, with the speedwalk directions reversed as described above.
If there is an error in the speed walk string then the first character of the returned string will be an asterisk ("*"), and the rest will be an English error message.


name: AddTimer
summary: Adds a timer
vb_example: world.addtimer "my_timer", 0, 0, 1, "go north", 5, ""
java_example: world.addtimer("my_timer", 0, 0, 1, "go north", 5, "");
perl_example: $world->addtimer("my_timer", 0, 0, 1, "go north", 5, "");
type_of_object: Method
python_example: world.addtimer("my_timer", 0, 0, 1, "go north", 5, "")
doc_name: timers
prototype:
long AddTimer(BSTR TimerName, short Hour, short Minute, double Second, BSTR ResponseText, long Flags, BSTR ScriptName);

description:
Adds a timer to the list of timers. 

Timers can be used to cause something to happen periodically, either every x seconds, or at a certain time of day.

Periodical timers (which fire after a certain time has elapsed) are intended for periodical events (eg. save your world file every hour, drink a potion every minute, check your health every 10 seconds).

Timers that fire at a certain time of day are intended to do things like start a new log file at midnight, warn you if when it is time to go to work, that sort of thing. :)

You can make a "one-shot" timer that does something once, and then deletes itself. This is useful for making a single thing happen in the future (eg. in 5 minutes) rather than happening every 5 minutes.

You can use "DoAfter", "DoAfterNote", "DoAfterSpeedWalk" or "DoAfterSpecial" for a simplified way of adding timers.

TimerName: name of this timer - may be empty (see rules for names below)
Hour: The hour to fire  (0 - 23)
Minute: The minute to fire (0 - 59)
Second: The second to fire (0 - 59.9999)
Response_text: what to send to the world
Flags: various flags, see list below
ScriptName: Which script subroutine to execute

Time Interval

From version 3.61 onwards of MUSHclient the seconds part of the time may include fractions (ie. it is a floating-point number). This lets you set up sub-second timers (eg. 0.5 seconds, 1.2 seconds).

To enable this you need to go to Global Configuration -> Timers and set the Timer Interval in seconds to zero.

The maximum granularity of the timers is currently 0.1 seconds.

Flags

The flags can be one or more of the constants below. For example, to enable the timer, and make it a one-shot, the flags would be 5. Preferably use the constant declarations in your script file, and "OR" them together. E.g. 

VBscript: eEnabled or eOneShot
JScript:  eEnabled | eOneShot
Lua:  timer_flag.Enabled + timer_flag.OneShot


VBscript constants:

const eEnabled = 1   ' is timer enabled?
const eAtTime = 2  ' if not set, time is "every"
const eOneShot = 4  ' if set, timer only fires once
const eTimerSpeedWalk = 8 ' timer does a speed walk when it fires
const eTimerNote = 16 ' timer does a world.note when it fires
const eActiveWhenClosed = 32 ' timer fires even when world is disconnected
const eReplace = 1024  ' replace existing timer of same name
const eTemporary = 16384 ' temporary - do not save to world file


JScript constants:

var eEnabled = 1;   // is timer enabled?
var eAtTime = 2;  // if not set, time is "every"
var eOneShot = 4;   // if set, timer only fires once
var eTimerSpeedWalk = 8; // timer does a speed walk when it fires
var eTimerNote = 16;  // timer does a world.note when it fires
var eActiveWhenClosed = 32;  // timer fires even when world is disconnected
var eReplace = 1024;  // replace existing timer of same name
var eTemporary = 16384; // temporary - do not save to world file


PerlScript constants:

my $eEnabled = 1;   # is timer enabled?
my $eAtTime = 2;   # if not set, time is "every"
my $eOneShot = 4;   # if set, timer only fires once
my $eTimerSpeedWalk = 8; # timer does a speed walk when it fires
my $eTimerNote = 16; # timer does a world.note when it fires
my $eActiveWhenClosed = 32;  # timer fires even when world is disconnected
my $eReplace = 1024;  #  replace existing timer of same name
my $eTemporary = 16384;  # temporary - do not save to world file

Lua constants (in the timer_flag table):

timer_flag.Enabled = 1
timer_flag.AtTime = 2
timer_flag.OneShot = 4
timer_flag.TimerSpeedWalk = 8
timer_flag.TimerNote = 16
timer_flag.ActiveWhenClosed = 32
timer_flag.Replace = 1024
timer_flag.Temporary = 16384

* 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 (_)

return_value:
eInvalidObjectLabel: The timer name is not valid
eTimerAlreadyExists: A timer of that name already exists
eScriptNameNotLocated: The script name cannot be located in the script file
eTimeInvalid: The time is invalid (eg. hour not in range 0 to 23).
eOK: added OK

see_also:
DeleteTimer EnableTimer GetTimerList IsTimer ResetTimer ResetTimers GetTimer GetTimerInfo DoAfter DoAfterSpeedWalk DoAfterNote EnableGroup EnableTimerGroup DeleteGroup  SetTimerOption GetTimerOption DoAfter DoAfterNote DoAfterSpecial ImportXML

lua_example:
AddTimer ("my_timer", 0, 0, 1.5, "go north", 
          timer_flag.Enabled + timer_flag.OneShot, "")

lua_notes:
The script name is optional.

The timer flags are built into the "timer_flag" table, as follows:

Enabled = 1
AtTime = 2
OneShot = 4
TimerSpeedWalk = 8
TimerNote = 16
ActiveWhenClosed = 32
Replace = 1024
Temporary = 16384


name: DeleteTimer
prototype: long DeleteTimer(BSTR TimerName);
summary: Deletes a timer
vb_example: world.DeleteTimer "mytimer"
java_example: world.DeleteTimer("mytimer");
perl_example: $world->DeleteTimer("mytimer");
type_of_object: Method
python_example: world.DeleteTimer("mytimer")
doc_name: timers
lua_example: DeleteTimer("mytimer")
description:
Deletes the named timer from the list of timers.

WARNING - if the timer is executing a script it cannot be deleted. For example, a timer cannot delete itself.

If you need to delete a timer from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableTimer to disable it first.

return_value:
eInvalidObjectLabel: The timer name is not valid
eTimerNotFound: The named timer does not exist
eItemInUse: Cannot delete trigger/alias/timer because it is executing a script
eOK: deleted OK

see_also:
AddTimer EnableTimer GetTimerList IsTimer ResetTimer ResetTimers GetTimer GetTimerInfo DeleteTimerGroup DoAfterSpecial


name: IsTimer
prototype: long IsTimer(BSTR TimerName);
summary: Tests to see if a timer exists
description: Used to test if a timer exists. Note that this function returns 0 if the timer *exists*.
vb_example: world.note world.IsTimer ("mytimer")
java_example: world.note(world.IsTimer("mytimer"));
perl_example: $world->note($world->IsTimer("mytimer"));
type_of_object: Method
see_also: AddTimer EnableTimer GetTimerList DeleteTimer ResetTimer ResetTimers GetTimer GetTimerInfo
python_example: world.note(world.IsTimer("mytimer"))
doc_name: timers
lua_example: Note(IsTimer("mytimer"))
return_value:
eInvalidObjectLabel: The timer name is not valid
eTimerNotFound: The named timer does not exist
eOK: completed OK - ie. The timer exists.


name: GetTimerList
prototype: VARIANT GetTimerList();
summary: Gets the list of timers
perl_example: foreach $item (Win32::OLE::in ($world->GetTimerList)) { $world->note($item); }
type_of_object: Method
see_also: AddTimer EnableTimer IsTimer DeleteTimer ResetTimer ResetTimers GetTimer GetTimerInfo
python_example: timerlist = world.GetTimerList if (timerlist): for t in timerlist : world.Note (t)
doc_name: timers
lua_notes: Lua returns nil where applicable instead of an "empty variant".
description:
Returns an array of all the named timers currently defined. You can then use GetTimer or GetTimerInfo for more details about each one.

Note - from version 3.40 onwards GetTimerList returns all timers, even unlabelled ones. The unlabelled timers will have assigned an "internal" label (like "*timer42") that can be used in GetTimerInfo, and similar routines.

vb_example:
dim timerList

timerList = world.GetTimerList

If Not IsEmpty (timerList) then

   For Each t In timerList
     world.Note t 
   next

End If

java_example:
timerlist = new VBArray(world.GetTimerList()).toArray();

if (timerlist)  // if not empty
 for (i = 0; i < timerlist.length; i++)
   world.note(timerlist [i]);

return_value:
If there are no timers (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the timers. Use "ubound" to find the number of timers in the list.

lua_example:
tl = GetTimerList ()
if tl then
  for k, v in ipairs (tl) do 
    Note (v) 
  end  -- for
end -- if we have any timers


name: GetTimer
summary: Gets details about a timer
java_example: // Use GetTimerInfo when using Jscript
perl_example: # Use GetTimerInfo when using PerlScript
type_of_object: Method
see_also: AddTimer EnableTimer IsTimer DeleteTimer ResetTimer ResetTimers GetTimerInfo GetTimerList
python_example: # Use GetTimerInfo when using Python
doc_name: timers
prototype:
long GetTimer(BSTR TimerName, VARIANT* Hour, VARIANT* Minute, VARIANT* Second, VARIANT* ResponseText, VARIANT* Flags, VARIANT* ScriptName);

description:
Gets details about the specified timer name.

See AddTimer for a description of the meanings of the fields.

This function does not appear to work when using Jscript or PerlScript, so if you are using those languages you should see GetTimerInfo instead. See below for how it works with Lua.

vb_example:
dim timername
dim timerhour
dim timerminute
dim timersecond
dim timerresponse
dim timerflags
dim timerscriptname
dim iStatus

iStatus = world.gettimer (timername, timerhour, timerminute, _
            timersecond, timerresponse, _
            timerflags, timerscriptname)

return_value:
eInvalidObjectLabel: The timer name is not valid
eTimerNotFound: The named timer does not exist
eOK: completed OK

lua_example:
local status

local hour
local minute
local second
local response
local flags
local scriptname

status, hour, minute, second, response, flags, scriptname = 
  GetTimer ("my_timer")

print (hour, minute, second, response, flags, scriptname)

lua_notes:
Lua does not let you call by reference, however it can return multiple results.

Thus GetTimer is implemented to return the various fields as a multiple-return result, 
as shown in the example above.


name: GetTimerInfo
prototype: VARIANT GetTimerInfo(BSTR TimerName, short InfoType);
summary: Gets details about a timer
vb_example: world.note world.GetTimerInfo ("my_timer", 2)
java_example: world.note(world.GetTimerInfo ("my_timer", 2));
perl_example: $world->note ($world->GetTimerInfo ("my_timer", 2));
type_of_object: Method
python_example: world.note(world.GetTimerInfo ("my_timer", 2))
doc_name: timers
lua_example: Note(GetTimerInfo ("my_timer", 2))
description:
Gets details about the specified timer name.

You can obtain one of 26 "types" of information about the timer by specifying an "InfoType". The possible InfoTypes are:

 1: The hour (short)
 2: The minute (short)
 3: The second (short)
 4: What to send (string)
 5: Script procedure name (string)
 6: Enabled (boolean)
 7: One shot timer (boolean)
 8: "At" timer (if false, timer fires "every" hour/minute/second)  (boolean)
 9: Invocation count (long)
10: Times matched (long)
11: Date/time timer last fired (or was reset) (date)
12: Date/time timer will fire next (date)
13: Number of seconds until timer will fire next or zero if it is due to fire immediately (this might happen if the timer is due to fire but is disabled). (double)
14: 'temporary' flag (boolean)
15: 'speed walk' flag (boolean)
16: 'note' flag (boolean)
17: 'active when disconnected' flag (boolean)
18: Timer was included from an include file (boolean)
19: Group name (string)
20: Send-to location (long)
21: User option value (long)
22: Timer label (string)
23: 'Omit from output' flag (boolean)
24: 'Omit from log file' flag (boolean)
25: 'Executing-script' flag (boolean)
26: Script is valid flag (boolean)

The word in brackets indicates the "type" of data returned.
  String: a character string (eg. "north")
  Boolean: TRUE or FALSE
  Long: a 32-bit number

The field "invocation count" is a count of how many times the script routine was called.
The field "times matched" is a count of how many times the timer matched. These two would normally be the same, unless scripting was disabled, or there was an error in the script file.

The meanings of the "send-to" field are:

 0: World     
 1: Command window
 2: Output window
 3: Status line
 4: Notepad (new)
 5: Notepad (append)
 6: Log File   
 7: Notepad (replace)
 8: Command queue
 9: Send To Variable
10: Execute (re-parse as command)
11: Speedwalk (send text is speedwalk, queue it)
12: Script (send to script engine)
13: Immediate (send to world in front of speedwalk queue)
14: Script - after omit 

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

See AddTimer for a description of the meanings of the fields.

return_value:
The specified information about the timer, as described above.
An EMPTY variant, if the timer does not exist.
A NULL variant if the timer name is invalid.
A NULL variant if the InfoType is not a valid type.

see_also:
AddTimer EnableTimer IsTimer DeleteTimer ResetTimer ResetTimers GetTimer GetTimerList GetInfo SetTimerOption GetTimerOption

lua_notes:
Lua returns nil where applicable instead of an "empty variant" or "null variant".

The "SendTo" field can be looked up using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0
sendto.command = 1
sendto.output = 2
sendto.status = 3
sendto.notepad = 4
sendto.notepadappend = 5
sendto.logfile = 6
sendto.notepadreplace = 7
sendto.commandqueue = 8
sendto.variable = 9
sendto.execute = 10
sendto.speedwalk = 11
sendto.script = 12
sendto.immediate = 13
sendto.scriptafteromit = 14


name: GetUniqueNumber
prototype: long GetUniqueNumber();
summary: Returns a unique number
vb_example: world.note world.GetUniqueNumber
java_example: world.note (world.GetUniqueNumber());
perl_example: $world->note ($world->GetUniqueNumber());
return_value: A unique number in the range 0 to 2147483647 as described above.
type_of_object: Method
see_also: GetUniqueID CreateGUID
python_example: world.note (world.GetUniqueNumber)
doc_name: utils
lua_example: Note (GetUniqueNumber())
description:
Returns a unique number in the range 0 to 2,147,483,647.

This number will be unique for this session of MUSHclient, across all worlds. You might use it to generate unique labels for one-shot timers, or other similar purposes.

Note that the number will eventually "wrap around" and thus, if you generate a lot of them (ie. 2,147,483,647 of them), they will no longer be unique.

Also note that this number generator is used internally in MUSHclient, and thus the numbers generated will not necessarily be in sequence.

Important - this number is reset for each new MUSHclient session, so these numbers are only unique per session, not indefinitely.


name: Queue
prototype: long Queue(BSTR Message, boolean Echo);
summary: Queues a command for sending at the "speed walk" rate.
vb_example: world.queue world.evaluatespeedwalk ("4n"), true
java_example: world.queue(world.evaluatespeedwalk("4n"), true);
perl_example: $world->queue($world->evaluatespeedwalk("4n"), true);
type_of_object: Method
see_also: Send Note DiscardQueue SpeedWalkDelay EvaluateSpeedwalk GetQueue SendImmediate
python_example: world.queue(world.evaluatespeedwalk("4n"), True)
lua_example: Queue (EvaluateSpeedwalk("4n"), true)
lua_notes: The echo flag is optional, and defaults to true.
description:
Queues the supplied command for sending to the MUD at the designated "speed walk" rate. This is for sending commands slowly, because quick sending might be inappropriate.

If the speed walk delay (SpeedWalkDelay property) is zero, then using Queue is exactly the same as using Send.

If Echo is true then the commands are echoed to the output window (as they are sent, not as they are queued).

If the speed walk delay is not zero, then the supplied message is appended to the end of the command queue. The command is split up at line breaks (whenever a carriage-return/linefeed combination is found), and each line is sent, separated by a delay of SpeedWalkDelay milliseconds.

Periodically (every SpeedWalkDelay milliseconds) the command at the top of the command queue is retrieved and sent to the MUD, and echoed in the output window if required.

If you want to bypass the queue (eg. to say something) then use SendImmediate.

return_value:
eWorldClosed : The world is closed
eItemInUse : Cannot be called from within OnPluginSent script callback
eOK: Queued OK


name: DiscardQueue
prototype: long DiscardQueue();
summary: Discards the speed walk queue
vb_example: world.discardqueue
java_example: world.discardqueue();
perl_example: $world->discardqueue();
return_value: The number of commands discarded (might be zero).
type_of_object: Method
see_also: Queue SpeedWalkDelay GetQueue
python_example: world.discardqueue
lua_example: DiscardQueue()
description:
Discards any commands queued up, to be sent at the speedwalk delay interval.

The return value is the number of commands discarded.


name: SpeedWalkDelay
prototype: short SpeedWalkDelay;
summary: The number of milliseconds delay between speed walk commands
vb_example: world.note world.SpeedWalkDelay ' display delay world.SpeedWalkDelay = 5000 ' make delay 5 seconds
type_of_object: Property
see_also: Queue DiscardQueue SpeedWalkDelay
python_example: world.note(world.SpeedWalkDelay) # display delay world.SpeedWalkDelay = 5000 # make delay 5 seconds
doc_name: speed_walking
lua_example: Note (GetSpeedWalkDelay ()) -- display delay SetSpeedWalkDelay (5000) -- make delay 5 seconds
description:
This property is used to retrieve, or set, the number of milliseconds which elapses between sending speed walk commands (or commands sent with the Queue method).

The interval is in milliseconds. There are 1000 milliseconds to the second.

The valid range for the speed walk delay is 0 to 30000 milliseconds (0 to 30 seconds).

If the interval is zero, then commands are not queued, but are sent immediately, as fast as possible.

Setting the interval to zero, when it was previously some other value, flushes any outstanding commands from the queue, so they are sent immediately.

java_example:
world.note(world.SpeedWalkDelay); // display delay
world.SpeedWalkDelay = 5000; // make delay 5 seconds

perl_example:
$world->note ($world->{SpeedWalkDelay});  # display delay
$world->{SpeedWalkDelay} = 5000;  # make delay 5 seconds

return_value:
This is a property. You can review or change the number of milliseconds between sending speedwalk commands.

lua_notes:
Lua implements this as two functions:

GetSpeedWalkDelay - gets the speedwalk delay
SetSpeedWalkDelay - sets the speedwalk delay


name: ReadNamesFile
prototype: long ReadNamesFile(BSTR FileName);
summary: Loads in a file for generating character names
vb_example: world.readnamesfile "mynames.nam"
java_example: world.readnamesfile("mynames.nam");
perl_example: $world->readnamesfile("mynames.nam");
type_of_object: Method
see_also: GenerateName
python_example: world.readnamesfile("mynames.nam")
doc_name: utils
lua_example: ReadNamesFile ("mynames.nam")
description:
This is used to load in a file of character names for the random name generator.

The names file should be loaded before calling GenerateName.

The file should contain lines with "[start]", "[middle]", "[end]" and "[stop]" in it (see below for example). Using the example file below, a generated name might be Wicorebwyn  (Wic - ore - bwyn). By setting up different files you can generate names with a different "feel" to them. 

Example names file:

[start]
A
Ab
Ac
Ad
W
Wic
[middle]
a
ae
ore
u
y

[end]
a
and
b
bwyn
baen
bard
[stop]

return_value:
eNoNameSpecified: File name cannot be blank
eCouldNotOpenFile: Could not open file, or file was not a valid names file
eOK: Processed file OK


name: GenerateName
prototype: VARIANT GenerateName();
summary: Generates a random character name
vb_example: ' generate 20 names for i = 1 to 20 world.note world.generatename next
java_example: // generate 20 names for (i = 0; i < 20; i++) world.note(world.generatename ());
perl_example: # generate 20 names for ($i = 0; $i < 20; $i++) { $world->note($world->generatename ()); }
type_of_object: Method
see_also: ReadNamesFile
python_example: # generate 20 names for i in range (20): world.note(world.generatename )
doc_name: utils
lua_example: -- generate 20 names for i = 1, 20 do Note(GenerateName()) end
description:
Generates a random character name based on the names in the names file previously loaded with ReadNamesFile.

return_value:
If a names file has not been loaded, the return value is a NULL variant.
Otherwise, the return value is the generated name.


name: Mapping
prototype: boolean Mapping;
summary: A flag to indicate whether we are mapping the world
description: This property controls whether automatic mapping takes place as you walk around.
vb_example: world.note world.Mapping
java_example: world.note(world.Mapping);
perl_example: $world->note ($world->{Mapping});
type_of_object: Property
python_example: world.note(world.Mapping)
doc_name: mapper
lua_example: Note(GetMapping ()) SetMapping (false)
return_value:
TRUE if mapping is enabled
FALSE if mapping is NOT enabled

Note: TRUE is a non-zero value, FALSE is the value 0.

see_also:
RemoveMapReverses AddToMapper GetMappingCount GetMappingItem GetMappingString DeleteLastMapItem DeleteAllMapItems

lua_notes:
Lua implements this as two functions:

GetMapping - gets whether mapping occurs
SetMapping - sets whether mapping occurs

The argument is optional, and defaults to true.


name: RemoveMapReverses
prototype: boolean RemoveMapReverses;
summary: A flag to indicate whether we backtracks are removed during mapping
description: This property controls whether backtracks are removed from the auto-mapper as you walk around.
vb_example: world.note world.RemoveMapReverses
java_example: world.note(world.RemoveMapReverses);
perl_example: $world->note ($world->{RemoveMapReverses});
type_of_object: Property
python_example: world.note(world.RemoveMapReverses)
doc_name: mapper
lua_example: Note(GetRemoveMapReverses ())
return_value:
TRUE if backtracks are removed
FALSE if backtracks are NOT removed

Note: TRUE is a non-zero value, FALSE is the value 0.

see_also:
Mapping AddToMapper GetMappingCount GetMappingItem GetMappingString DeleteLastMapItem DeleteAllMapItems

lua_notes:
Lua implements this as two functions:

GetRemoveMapReverses - gets the 'remove map reverses' flag
SetRemoveMapReverses - sets the 'remove map reverses' flag


name: AddToMapper
prototype: long AddToMapper(BSTR Direction, BSTR Reverse);
summary: Adds a mapping direction to the auto-map sequence
vb_example: world.AddToMapper "north", "south" world.AddToMapper "enter", "leave"
java_example: world.AddToMapper("north", "south"); world.AddToMapper("enter", "leave");
perl_example: $world->AddToMapper("north", "south"); $world->AddToMapper("enter", "leave");
type_of_object: Method
python_example: world.AddToMapper("north", "south") world.AddToMapper("enter", "leave")
doc_name: mapper
lua_example: AddToMapper("north", "south") AddToMapper("enter", "leave")
lua_notes: The reverse direction is optional.
description:
Adds a new direction to the auto-map sequence. You specify both the forward direction, and the reverse direction (the one taken when going backwards).

For example if you are going North, then the reverse direction is (usually) South.

Note, mapping does *not* need to be enabled to use this method. This lets you use triggers or aliases to build up a map direction, rather than MUSHclient's automatic mapping.

return_value:
eBadMapItem: direction (or reverse direction) may not contain "{", "}", "(", ")", "/" or ""
eBadMapItem: forward and reverse direction cannot both be empty
eOK: added OK

see_also:
Mapping RemoveMapReverses GetMappingCount GetMappingItem GetMappingString DeleteLastMapItem DeleteAllMapItems AddMapperComment


name: GetMappingCount
prototype: long GetMappingCount();
summary: Gets a count of the number of items in the auto-map sequence
description: Returns the number of items in the auto-map sequence. May be zero if no items are present.
vb_example: world.note world.GetMappingCount
java_example: world.note(world.GetMappingCount);
perl_example: $world->note ($world->GetMappingCount);
return_value: The number of items in the auto-map sequence. Will be zero if it is empty.
type_of_object: Method
python_example: world.note(world.GetMappingCount)
doc_name: mapper
lua_example: Note (GetMappingCount ())
see_also:
Mapping RemoveMapReverses AddToMapper GetMappingItem GetMappingString DeleteLastMapItem DeleteAllMapItems


name: GetMappingItem
prototype: VARIANT GetMappingItem(long Item);
summary: Gets one item from the auto-map sequence
vb_example: world.note world.GetMappingItem (0)
java_example: world.note(world.GetMappingItem(0));
perl_example: $world->note($world->GetMappingItem(0));
type_of_object: Method
python_example: world.note(world.GetMappingItem(0))
doc_name: mapper
lua_example: Note(GetMappingItem(0))
lua_notes: Lua returns nil where applicable instead of an "empty variant" or "null variant".
description:
Returns one item from the auto-map sequence. You supply the item number that you want. 

It should be in the range zero to the value returned by GetMappingCount, minus 1. If not, a NULL variant will be returned.

The item number is zero relative, so that if you have two items in the map sequence, they will be:

0: first item
1: second item

The returned value is a single string, with the forwards and reverse direction separated by a slash. For example:

north/south

return_value:
If the item number is less than zero, or greater than, or equal to, the number returned by GetMappingCount, then a NULL variant will be returned.

Otherwise, the contents of the appropriate map item will be returned. The forwards and reverse direction will be separated by the "/" character.

see_also:
Mapping RemoveMapReverses AddToMapper GetMappingCount GetMappingString DeleteLastMapItem DeleteAllMapItems


name: GetMappingString
prototype: VARIANT GetMappingString();
summary: Returns the speedwalk string generated by the auto-mapper.
vb_example: world.note world.GetMappingString
java_example: world.note(world.GetMappingString());
perl_example: $world->note($world->GetMappingString());
type_of_object: Method
python_example: world.note(world.GetMappingString)
doc_name: mapper
lua_example: Note(GetMappingString())
description:
Returns the speedwalk string generated by the auto-mapper. This is a string that can be sent to EvaluateSpeedWalk to convert it into appropriate commands for sending to the MUD.

For example: 

4s 2(ne/sw) e (ne/sw) 2n

If you want to get the reverse direction , send the supplied string to ReverseSpeedwalk.

return_value:
The speedwalk string generated by the auto-mapper. It might be an empty string if there are no items in the auto-map sequence.

see_also:
Mapping RemoveMapReverses AddToMapper GetMappingCount GetMappingString DeleteLastMapItem DeleteAllMapItems EvaluateSpeedwalk ReverseSpeedwalk


name: DeleteLastMapItem
prototype: long DeleteLastMapItem();
summary: Deletes the most recently-added item from the auto-mapper sequence.
vb_example: world.DeleteLastMapItem
java_example: world.DeleteLastMapItem();
perl_example: $world->DeleteLastMapItem();
return_value: eNoMapItems: Map sequence was empty, nothing was deleted. eOK: Deleted last entry
type_of_object: Method
python_example: world.DeleteLastMapItem
doc_name: mapper
lua_example: DeleteLastMapItem()
description:
Deletes the most recently-added item from the auto-mapper sequence. You might use this in a trigger to remove a direction that you were not able to go.

see_also:
Mapping RemoveMapReverses AddToMapper GetMappingCount GetMappingString GetMappingString DeleteAllMapItems


name: DeleteAllMapItems
prototype: long DeleteAllMapItems();
summary: Deletes the all items from the auto-mapper sequence.
vb_example: world.DeleteAllMapItems
java_example: world.DeleteAllMapItems();
perl_example: $world->DeleteAllMapItems();
return_value: eNoMapItems: Map sequence was empty, nothing was deleted. eOK: Deleted all items
type_of_object: Method
python_example: world.DeleteAllMapItems
doc_name: mapper
lua_example: DeleteAllMapItems()
description:
Deletes all items from the auto-mapper sequence.

You can use this to start a new auto-map sequence.

see_also:
Mapping RemoveMapReverses AddToMapper GetMappingCount GetMappingString GetMappingString DeleteLastMapItem


name: GetSentBytes
prototype: long GetSentBytes();
summary: Returns the number of bytes sent to the world
vb_example: world.note world.GetSentBytes
java_example: world.note(world.GetSentBytes());
perl_example: $world->note($world->GetSentBytes());
return_value: The number of bytes sent to the MUD.
type_of_object: Method
see_also: GetReceivedBytes GetLineCount GetConnectDuration GetScriptTime
python_example: world.note(world.GetSentBytes)
doc_name: info
lua_example: Note(GetSentBytes())
lua_notes: Lua will always return the correct number as the Lua data type is double, not long.
description:
Returns a count of the number of bytes actually sent to the world. (This will exclude commands that are queued up that haven't yet been sent).

The maximum number that can be returned by this function is a 31-bit number (ie. 0 to 2,147,483,647 bytes). This does not apply to Lua which returns the numbers as a "double" type (floating point).

If more bytes than that have been sent the number will "wrap around" and become negative for a while.


name: GetReceivedBytes
prototype: long GetReceivedBytes();
summary: Returns the number of bytes received from the world
vb_example: world.note world.GetReceivedBytes
java_example: world.note(world.GetReceivedBytes());
perl_example: $world->note($world->GetReceivedBytes());
return_value: The number of bytes received from the MUD.
type_of_object: Method
see_also: GetSentBytes GetLineCount GetConnectDuration GetScriptTime
python_example: world.note(world.GetReceivedBytes)
doc_name: info
lua_example: Note(GetReceivedBytes())
lua_notes: Lua will always return the correct number as the Lua data type is double, not long.
description:
Returns a count of the number of bytes received from the world.

The maximum number that can be returned by this function is a 31-bit number (ie. 0 to 2,147,483,647 bytes). This does not apply to Lua which returns the numbers as a "double" type (floating point).

If more bytes than that have been received the number will "wrap around" and become negative for a while.


name: GetConnectDuration
prototype: long GetConnectDuration();
summary: Returns the number of seconds this world has been connected.
vb_example: world.note world.GetConnectDuration
java_example: world.note(world.GetConnectDuration());
perl_example: $world->note($world->GetConnectDuration());
return_value: The number of seconds this world has been connected.
type_of_object: Method
see_also: GetSentBytes GetLineCount GetReceivedBytes IsConnected GetScriptTime
python_example: world.note(world.GetConnectDuration)
doc_name: info
lua_example: Note(GetConnectDuration())
description:
Returns the number of seconds the world has been connected, or zero if the world is not currently connected.


name: GetScriptTime
prototype: double GetScriptTime();
summary: Returns the amount of time spent in script routines
vb_example: world.note world.getscripttime
java_example: world.note(world.getscripttime());
perl_example: $world->note($world->getscripttime());
type_of_object: Method
see_also: GetSentBytes GetLineCount GetReceivedBytes GetConnectDuration
python_example: world.note(world.getscripttime)
doc_name: utils
lua_example: Note(GetScriptTime())
description:
Returns the amount of time spent, in seconds compiling and executing scripts. This is a "double" type, which means that it can contain fractions of a second.

The current command (or script) is excluded from the time, as timing is done when the script routine finishes. Thus, if you type one of the examples below, and *then* check it against the figure shown in the MUSHclient scripting configuration page, they will disagree. However, if you check the time *first* and then run the example, then the times should agree to within 0.000001 seconds. The reason for that discrepancy is that the figure shown in the scripting configuration page is rounded to the 6th decimal place (ie. to the nearest microsecond).

return_value:
The number of seconds, as a "double" spent executing scripts. The current script routine will not be counted, as it has not completed execution yet. Scripts which have errors are not counted in the time.


name: DeleteCommandHistory
prototype: void DeleteCommandHistory();
summary: Deletes command history list.
vb_example: world.DeleteCommandHistory
java_example: world.DeleteCommandHistory();
perl_example: $world->DeleteCommandHistory();
return_value: Nothing.
type_of_object: Method
see_also: DeleteOutput
python_example: world.DeleteCommandHistory
lua_example: DeleteCommandHistory()
description:
Deletes any commands in the command history list for all windows. If you have multiple windows open to this world all comand histories will be deleted.  There is no confirmation dialog.


name: EchoInput
prototype: boolean EchoInput;
summary: A flag to indicate whether we are echoing command input to the output window
description: This property controls whether command input is echoed to the output window.
vb_example: world.note world.EchoInput world.EchoInput = vbTrue world.EchoInput = vbFalse;
java_example: world.note(world.EchoInput); world.EchoInput = true; world.EchoInput = false;
perl_example: $world->note ($world->{EchoInput}); $world->{EchoInput} = false; $world->{EchoInput} = true;
type_of_object: Property
see_also: LogInput
python_example: world.note(world.EchoInput) world.EchoInput = True world.EchoInput = False
doc_name: info
lua_example: Note (GetEchoInput ()) SetEchoInput (true) SetEchoInput (false)
return_value:
TRUE if echoing is enabled
FALSE if echoing is NOT enabled

Note: TRUE is a non-zero value, FALSE is the value 0.

lua_notes:
Lua implements this as two functions:

GetEchoInput - gets the echo input flag
SetEchoInput - sets the echo input flag

When setting the flag the flag is optional and defaults to true.


name: DeleteOutput
prototype: void DeleteOutput();
summary: Clears all output from the output window.
vb_example: world.DeleteOutput
java_example: world.DeleteOutput();
perl_example: $world->DeleteOutput();
return_value: Nothing.
type_of_object: Method
see_also: DeleteCommandHistory DeleteLines
python_example: world.DeleteOutput
lua_example: DeleteOutput()
description:
Clears all output from the output window. There is no confirmation dialog.

To delete part of the output buffer only, see DeleteLines.


name: Tell
prototype: void Tell(BSTR Message);
summary: Sends a message to the output window - not terminated by a newline
vb_example: world.tell "This monster is worth avoiding!"
java_example: world.tell("This monster is worth avoiding!");
perl_example: $world->tell("This monster is worth avoiding!");
return_value: Nothing.
type_of_object: Method
python_example: world.tell("This monster is worth avoiding!")
doc_name: note
lua_example: Tell ("This monster is worth avoiding!")
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
This makes a note in the output window. It is not transmitted to the world. It is useful for making comments to yourself. The note is NOT automatically terminated by a newline, so you can use Tell multiple times on one line (eg. to change colour in mid-line).

The note appears in the current NoteColour (a custom colour), or in the RGB colours selected by NoteColourFore and NoteColourBack.

You can also choose colours with NoteColourRGB and NoteColourName.

A new line will automatically be started by output from the MUD, or a command that you type being echoed to the output window. You can send a new line yourself by sending vbCRLF (in Visual Basic) or \n in Jscript or Perlscript.

To make changes to the text style (eg. bold, underline) see NoteStyle.

see_also:
Send NoteColour NoteColourFore NoteColourBack Note NoteColourRGB NoteColourName ColourNote ColourTell NoteStyle NoteHr NoteStyle


name: NoteColourFore
prototype: long NoteColourFore;
summary: Chooses which RGB colour will be used for world notes - text colour
return_value: This is a property. You can use it to find the current note text colour.
type_of_object: Property
see_also: NoteColour NoteColourBack Tell Note NoteColourRGB NoteColourName ColourNote ColourTell
doc_name: colours
description:
You can use this to set the foreground (text) colour used in world.note and world.tell. The colour is specified in RGB (Red, Green, Blue). Red is in the low-order byte, Green in the middle-order byte, and Blue in the higher-order byte. (ie. 0x00BBGGRR).

If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description 
-------------------------------
vbBlack    &h00     Black 
vbRed      &hFF     Red 
vbGreen    &hFF00   Green 
vbYellow   &hFFFF   Yellow 
vbBlue     &hFF0000 Blue 
vbMagenta  &hFF00FF Magenta 
vbCyan     &hFFFF00 Cyan 
vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

vb_example:
world.notecolourfore = vbRed  ' set note colour to red
world.note "This will be in red"
world.note world.notecolourfore  ' display current note colour

java_example:
world.notecolourfore = 0xFF;  // set note colour to use red
world.note("This will be in red");
world.note(world.notecolourfore);  // display current note colour

perl_example:
$world->{notecolourfore} = 0xFF;  # set note colour to use red
$world->note("This will be in red");
$world->note($world->{notecolourfore});  # display current note colour

python_example:
world.notecolourfore = 0xFF  # set note colour to use red
world.note("This will be in red")
world.note(world.notecolourfore)  # display current note colour

lua_example:
SetNoteColourFore (255)  -- set note colour to use red foreground
Note ("This will be in red")
Note(GetNoteColourFore ())  -- display current note background colour

lua_notes:
Lua implements this as two functions:

GetNoteColourFore - gets the note colour foreground
SetNoteColourFore - sets the note colour foreground


name: NoteColourBack
prototype: long NoteColourBack;
summary: Chooses which RGB colour will be used for world notes - background colour
return_value: This is a property. You can use it to find the current note background colour.
type_of_object: Property
see_also: NoteColour NoteColourFore Tell Note NoteColourRGB NoteColourName ColourNote ColourTell
doc_name: colours
description:
You can use this to set the background colour used in world.note and world.tell. The colour is specified in RGB (Red, Green, Blue). Red is in the low-order byte, Green in the middle-order byte, and Blue in the higher-order byte. (ie. 0x00BBGGRR).

If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description 
-------------------------------
vbBlack    &h00     Black 
vbRed      &hFF     Red 
vbGreen    &hFF00   Green 
vbYellow   &hFFFF   Yellow 
vbBlue     &hFF0000 Blue 
vbMagenta  &hFF00FF Magenta 
vbCyan     &hFFFF00 Cyan 
vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

vb_example:
world.notecolourback = vbRed  ' set note background colour to red
world.note "This will be on a red background"
world.note world.notecolourback  ' display current note background colour

java_example:
world.notecolourback = 0xFF;  // set note colour to use red background
world.note("This will be on a red background");
world.note(world.notecolourback);  // display current note background colour

perl_example:
$world->{notecolourback} = 0xFF;  # set note colour to use red background
$world->note("This will be on a red background");
$world->note($world->{notecolourback});  # display current note background colour

python_example:
world.notecolourback = 0xFF  # set note colour to use red background
world.note("This will be on a red background")
world.note(world.notecolourback)  # display current note background colour

lua_example:
SetNoteColourBack (255)  -- set note colour to use red background
Note ("This will be on a red background")
Note(GetNoteColourBack ())  -- display current note background colour

lua_notes:
Lua implements this as two functions:

GetNoteColourBack - gets the note colour background
SetNoteColourBack - sets the note colour background


name: NoteColourRGB
prototype: void NoteColourRGB(long Foreground, long Background);
summary: Chooses which RGB colour will be used for world notes - text and background
return_value: Nothing.
type_of_object: Method
see_also: NoteColourFore NoteColourBack Tell Note NoteColour NoteColourName ColourNote ColourTell
doc_name: colours
description:
You can use this to set the foreground (text) and background colours used in world.note and world.tell. The colour is specified in RGB (Red, Green, Blue). Red is in the low-order byte, Green in the middle-order byte, and Blue in the higher-order byte. (ie. 0x00BBGGRR).

You must specify an RGB values. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description 
-------------------------------
vbBlack    &h00     Black 
vbRed      &hFF     Red 
vbGreen    &hFF00   Green 
vbYellow   &hFFFF   Yellow 
vbBlue     &hFF0000 Blue 
vbMagenta  &hFF00FF Magenta 
vbCyan     &hFFFF00 Cyan 
vbWhite    &hFFFFFF White

In JScript and PerlScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

To calculate this mathematically this would be:

colour = red + (green * 256) + (blue * 65536)

vb_example:
world.notecolourRGB vbRed, vbGreen  ' set note colour to red on green
world.note "This will be in red on green"

java_example:
world.notecolourRGB (0xFF, 0xFF00);  // set note colour to use red on green
world.note("This will be in red on green");

perl_example:
$world->NoteColourRGB (0xFF, 0xFF00);  # set note colour to use red on green
$world->note("This will be in red on green");

python_example:
world.notecolourRGB (0xFF, 0xFF00)  # set note colour to use red on green
world.note("This will be in red on green")

lua_example:
NoteColourRGB (255, 256 * 255)  -- set note colour to use red on green
Note("This will be in red on green")


name: NoteColourName
prototype: void NoteColourName(BSTR Foreground, BSTR Background);
summary: Chooses which RGB colour name will be used for world notes - text and background
return_value: Nothing.
type_of_object: Method
see_also: NoteColourFore NoteColourBack Tell Note NoteColour NoteColourRGB ColourNote ColourTell
doc_name: colours
description:
You can use this to set the foreground (text) and background colours used in world.note and world.tell. The colour is specified as a colour name, eg. "red", "green", "beige", "cyan" and so on.

The names are not case-sensitive.

You can also use HTML colour codes, eg. "#7FFF00", in this case the colours are in the order #rrggbb (rr = red, gg = green, bb = blue).

If a particular colour is invalid or not found, then that colour will be unchanged. Thus you can use this function to change the foreground colour only, the background colour only, or both.

Eg.

world.notecolourname "red", ""  ' foreground only
world.notecolourname "", "blue"  ' background only
world.notecolourname "green", "cyan"  ' both

You can use MUSHclient's "colour picker" to choose a suitable name. Use the Edit menu -> Colour Picker to do this, or press Ctrl+Alt+P.

vb_example:
world.notecolourname "red", "green"  ' set note colour to red on green
world.note "This will be in red on green"

java_example:
world.notecolourname ("red", "green");  // set note colour to use red on green
world.note("This will be in red on green");

perl_example:
$world->NoteColourname ("red", "green");  # set note colour to use red on green
$world->note("This will be in red on green");

python_example:
world.notecolourname ("red", "green")  # set note colour to use red on green
world.note("This will be in red on green")

lua_example:
NoteColourName ("red", "green")  -- set note colour to use red on green
Note("This will be in red on green")


name: Version
prototype: BSTR Version();
summary: Gets the MUSHclient version string.
vb_example: world.note world.Version
java_example: world.Note(world.Version());
perl_example: $world->Note($world->Version());
return_value: MUSHclient version string.
type_of_object: Method
python_example: world.Note(world.Version)
doc_name: info
lua_example: Note(Version())
description:
This returns the MUSHclient version string. This is usually a "number" like "3.10" but might have letters appended if it is a beta or test version (eg. "3.10.2" or "3.10p22").


name: Reset
prototype: void Reset();
summary: Resets all outstanding MXP/Pueblo tags
vb_example: world.reset
java_example: world.Reset();
perl_example: $world->Reset();
return_value: Nothing.
type_of_object: Method
python_example: world.Reset
lua_example: Reset()
description:
This closes any outstanding MXP/Pueblo tags, and resets the output window colours to ANSI white on black. It also cancels underline, highlight, and inverse.


name: GetOptionList
prototype: VARIANT GetOptionList();
summary: Gets the list of world options
type_of_object: Method
see_also: GetOption SetOption GetAlphaOption SetAlphaOption GetAlphaOptionList GetGlobalOptionList
python_example: for opt in world.GetOptionList: world.Note (opt)
doc_name: options
lua_example: for k, v in pairs (GetOptionList()) do Note (v, " = ", GetOption (v)) end
description:
Returns a variant array which is a list of all options that you can get with GetOption or set with SetOption.

The examples show extracting all option names, and their values.

The option names should be reasonably self-explanatory.

vb_example:
For Each opt In world.GetOptionList
    world.note opt + " = " + cstr (world.GetOption ( opt ))
Next

java_example:
optionlist = new VBArray(world.GetOptionList()).toArray();

 for (i = 0; i < optionlist .length; i++)
   world.note(optionlist [i] + " = " + world.GetOption (optionlist [i] ));

perl_example:
foreach $item (Win32::OLE::in ($world->GetOptionList))
 {
 $world->note($item . " = " . $world->GetOption($item));
 }

return_value:
It returns a variant array containing the names of all the options. Use "ubound" to find the number of options in the list. You can then use "GetOption" to return the value for that particular option, or "SetOption" to set that option value.


name: GetOption
prototype: long GetOption(BSTR OptionName);
summary: Gets value of a named world option
vb_example: world.note world.getoption ("show_italic")
java_example: /world.note(world.getoption ("show_italic"));
perl_example: /$world->note ($world->getoption ("show_italic"));
return_value: The value of the requested option, or -1 if the option does not exist.
type_of_object: Method
see_also: GetOptionList SetOption GetAlphaOption GetLoadedValue GetDefaultValue GetCurrentValue
python_example: world.note(world.getoption ("show_italic"))
doc_name: options
lua_example: Note (GetOption ("show_italic"))
description:
Gets value of a world option. Many options are booleans (true or false). The number zero represents false (option not set) and the number one represents true (option set).

You can use GetOptionList to get a list of the names of all possible options.


name: SetOption
prototype: long SetOption(BSTR OptionName, long Value);
summary: Sets value of a named world option
vb_example: world.setoption "show_italic", 1
java_example: world.setoption ("show_italic", 1);
perl_example: $world->setoption ("show_italic", 1);
type_of_object: Method
see_also: GetOptionList GetOption GetAlphaOptionList GetAlphaOption SetAlphaOption
python_example: world.setoption ("show_italic", 1)
doc_name: options
lua_example: SetOption ("show_italic", 1)
lua_notes: You can use true, false or nil for boolean options.
description:
Sets value of a world option. Many options are booleans (true or false).

For boolean options the supplied value may be:

1 for true
0 for false

Also if you are using Lua you can supply simply true or false.

You can use GetOptionList to get a list of the names of all possible options.

Use SetAlphaOption to set alphanumeric options.

return_value:
eUnknownOption - option name not recognised
eOptionOutOfRange - option value out of range
ePluginCannotSetOption: The option is marked as non-settable (in a plugin or not)
eOK - set OK


name: Open
prototype: IDispatch* Open(BSTR FileName);
summary: Opens a named document
type_of_object: Method
see_also: GetWorldList GetWorld Activate OpenBrowser
doc_name: world
lua_example: openedOK = world.Open ("smaug.mcl") -- true or false
description:
Returns an object which can be used to refer to the new document (except in Lua, see below).

You should be very cautious about storing the object reference of the world in a global variable, because if the world is closed then that reference becomes invalid, which will very likely lead to an access violation (program crash). You are better off using "world.getworld (name)" every time you need to get a reference to the world, and checking if it "is nothing" as in the example.

Better still, use "world.GetWorldById (id)" which uses each world's unique ID, in case you have multiple worlds of the same name.

You can use Open to open either a MUSHclient world (ie. a MCL file) or a text file (ie. a TXT file).

If the named document is already open then "open" does *not* open another copy, rather it activates that document (brings it to the front).

vb_example:
dim otherworld

  set otherworld = world.open  ("smaug.mcl")

  if not (otherworld is nothing) then
    otherworld.send "say hello everyone" 
  end if

java_example:
var otherworld

   otherworld = world.Open ("smaug.mcl");

  if (otherworld != null)
   otherworld.send("say hi there everyone");

perl_example:
my $otherworld;

 $otherworld = $world->Open ("smaug.mcl");

  if (!defined ($otherworld))
    { 
   $otherworld->send("say hi there everyone");
    }

return_value:
For Lua, it returns true if the file was opened OK, and false if not.

For other languages:

An object reference to the named world, if it was found.
Otherwise NULL.

In Vbscript use the test "is nothing" to see if the reference is to a valid world.
In JavaScript use the test "== null" to see if the reference is to a valid world.
In PerlScript use the test "defined ()" to see if the reference is to a valid world.

python_example:
var otherworld

   otherworld = world.Open ("smaug.mcl")

  if (otherworld != null)
   otherworld.send("say hi there everyone")

lua_notes:
Lua is not implemented using the COM model, and thus opening a file and getting an object reference is not possible.

As of version 4.08 however, it will attempt to open the file in the same way as other languages, and return true if it succeeded, and false otherwise.

If you want a "world" userdata to refer to after opening a world, you would need to use GetWorld or GetWorldById to get a reference to the newly-opened world.


name: GetLineInfo
prototype: VARIANT GetLineInfo(long LineNumber, short InfoType);
summary: Gets details about a specified line in the output window
type_of_object: Method
doc_name: info
description:
Returns details about any line in the output buffer (window).

The line number can be from 1 (the first line) to the number of lines in the output window. You can use "world.GetLinesInBufferCount" to find how many lines are currently in the output window. This number is different from the sequential number of the line since the world opened. For example, if your buffer size is 5000 lines, and you have received 8000 lines, then the last line will be line around 5000 in the buffer but "actual line number" (selector 10 below) will return 8000.

Note that when the buffer fills up lines are discarded in batches of 100, so the last line will probably not be 5000, even if your buffer size is 5000 and you have been connected for a while. It is likely to be in the range 4900 to 4999.

Also, the last line may be blank (empty) as MUSHclient creates a new, empty, line as soon as a newline is received for the previous line from the MUD.

You can obtain one of 12 "types" of information about the line by specifying an "InfoType". The possible InfoTypes are:

 1: text of line (string)                                   
 2: length of text (short)                                 
 3: true if newline, false if not  (boolean)                 
 4: true if world.note  (boolean)                            
 5: true if player input (boolean)                           
 6: true if line logged  (boolean)                           
 7: true if bookmarked  (boolean)                            
 8: true if MXP horizontal rule (<hr>)  (boolean)                
 9: date/time line arrived  (date)                        
10: actual line number (not line number in buffer)  (long)
11: count of style runs  (long)     
12: ticks - exact value from the high-performance timer (double)     
13: elapsed time in seconds from when the world was started (opened) (high precision)                 

The text of the line is the actual text you see on the screen.

If "newline" is true then this line is the end of a paragraph (ie. had a newline at the end of it). You can reassemble paragraphs by concatenating lines as found, and then adding a newline (carriage-return, linefeed) whenever "newline" is true. MUSHclient automatically preserves the space at the end of each line, so it is unnecessary to add another of your own. If "indent paragraphs" option is set in MUSHclient the space will be at the start of the next line, rather than the end of the previous line.

If "world.note" is true this is a "note" line, not MUD output.

If "player input" is true, then this line is an echoed command, not MUD output.

The count of styles runs can be used in conjunction with GetStyleInfo to further break up individual lines into style runs (eg. colour changes, bold, underline, etc.).

The "ticks" value is obtained by querying the "high performance timer" provided by Windows. This gives a time interval to a high degree of precision, however it is not related to the time-of-day in any meaningful way. The intention here is that you can use it to find the precise time difference between various lines as they arrive from the MUD.

vb_example:
dim line, total_lines

total_lines = world.GetLinesInBufferCount

'
'  Example showing the last 10 lines in the output buffer
'   Shown is text of line, date/time received, count of style runs
'

for line = total_lines - 10 to total_lines

  world.note "Line " & line & " = " & world.GetLineInfo (line, 1)
  world.tell "Received " & world.GetLineInfo (line, 9)
  world.note " - Style runs = " & world.GetLineInfo (line, 11)

next

java_example:
var line, total_lines;

total_lines = world.GetLinesInBufferCount ();

//
//  Example showing the last 10 lines in the output buffer
//   Shown is text of line, date/time received, count of style runs
//

for (line = total_lines - 10; line <= total_lines; line++)
  {
  world.note ("Line " + line + " = " + world.GetLineInfo (line, 1));
  world.tell ("Received " + world.GetLineInfo (line, 9));
  world.note (" - Style runs = " + world.GetLineInfo (line, 11));
  }

perl_example:
my $line, $total_lines;

$total_lines = $world->GetLinesInBufferCount ();

#
#  Example showing the last 10 lines in the output buffer
#   Shown is text of line, date/time received, count of style runs
#

for ($line = $total_lines - 10; $line <= $total_lines; $line++)
  {
  $world->note ("Line " . $line . " = " . $world->GetLineInfo ($line, 1));
  $world->tell ("Received " . $world->GetLineInfo ($line, 9));
  $world->note (" - Style runs = " . $world->GetLineInfo ($line, 11));
  }

return_value:
The specified information about the line, as described above.
An EMPTY variant, if the line does not exist.
A NULL variant if the InfoType is not a valid type.

see_also:
GetLinesInBufferCount GetStyleInfo GetSelectionStartLine GetSelectionEndLine GetSelectionStartColumn GetSelectionEndColumn GetInfo

python_example:
total_lines = world.GetLinesInBufferCount 

#
#  Example showing the last 10 lines in the output buffer
#   Shown is text of line, date/time received, count of style runs
#

for line in range (total_lines - 10, total_lines):
  world.note ("Line " + str(line) + " = " + world.GetLineInfo (line, 1))
  world.tell ("Received " + str (world.GetLineInfo (line, 9)))
  world.note (" - Style runs = " + str (world.GetLineInfo (line, 11)))

lua_example:
local line, total_lines

total_lines = GetLinesInBufferCount ()

--
--  Example showing the last 10 lines in the output buffer
--   Shown is text of line, date/time received, count of style runs
--

for line = total_lines - 10, total_lines do
  Note ("Line ", line, " = ", GetLineInfo (line, 1))
  Tell ("Received ", GetLineInfo (line, 9))
  Note (" - Style runs = ", GetLineInfo (line, 11))
  end


-- Lua extension - returns all information in a table:

for line = total_lines - 10, total_lines do
  table.foreach (GetLineInfo (line), print)  
end

lua_notes:
The InfoType is optional, and defaults to zero.

As an extension, if the InfoType is omitted or zero, then all types of information
for the nominated line are returned in a table, keyed by type:

 text:     text of line (string)                                   
 length:   length of text (number)                                 
 newline:  true if newline, false if not  (boolean)                 
 note:     true if world.note  (boolean)                            
 user:     true if player input (boolean)                           
 log:      true if line logged  (boolean)                           
 bookmark: true if bookmarked  (boolean)                            
 hr:       true if MXP horizontal rule (<hr>)  (boolean)                
 time:     date/time line arrived  (date - number)                        
 timestr:  date/time line arrived  (date - string)
 line:     actual line number (not line number in buffer)  (number)
 styles:   count of style runs  (number)  
 ticks:    exact value from the high-performance timer 
(number)                          
 elapsed:  exact elapsed time (number) since world started (opened)

Thus, to print the text of line 5 you might do this:

  print (GetLineInfo (5).text)

If the line does not exist, or the InfoType is invalid, Lua will return nil.


name: GetLinesInBufferCount
prototype: long GetLinesInBufferCount();
summary: Returns the number of lines in the output window
vb_example: world.note world.GetLinesInBufferCount
java_example: world.note(world.GetLinesInBufferCount());
perl_example: $world->note($world->GetLinesInBufferCount());
return_value: The number of lines in the output buffer (output window) of this world.
type_of_object: Method
see_also: GetLineCount GetLineInfo
python_example: world.note(world.GetLinesInBufferCount)
doc_name: info
lua_example: Note(GetLinesInBufferCount())
description:
This returns the number of lines in the output buffer (window) of this world.

It will differ from GetLineCount once the number of lines received exceeds the size of the buffer (as early ones will be discarded).


name: GetStyleInfo
prototype: VARIANT GetStyleInfo(long LineNumber, long StyleNumber, short InfoType);
summary: Gets details about a specified style run for a specified line in the output window
vb_example: ' find foreground colour in RGB of style 2 on line 100 world.note world.GetStyleInfo (100, 2, 14)
type_of_object: Method
doc_name: info
description:
Returns details about any style run for any line in the output buffer (window). 

The line number can be from 1 (the first line) to the number of lines in the output window. You can use "world.GetLinesInBufferCount" to find how many lines are currently in the output window. 

The style number can be from 1 (the first style on the line) to the number of styles in that line. You can use "world.GetLineInfo(LineNumber, 11)" to find the number of styles in each line.

You can obtain one of 15 "types" of information about the style by specifying an "InfoType". The possible InfoTypes are: 

 1: text of style  (string)                                             
 2: length of style run  (short)                                       
 3: starting column of style  (short)                                  
 4: action type - 0=none, 1=send to mud, 2=hyperlink, 3=prompt  (short)
 5: action   (eg. what to send)  (string)  
 6: hint     (what to show)      (string)                               
 7: variable (variable to set)   (string)                               
 8: true if bold           (boolean)                                     
 9: true if underlined     (boolean)                                     
10: true if blinking       (boolean)                                     
11: true if inverse        (boolean)                                     
12: true if changed by trigger from original    (boolean)                 
13: true if start of a tag (action is tag name) (boolean)                
14: foreground (text) colour in RGB   (long)                          
15: background colour in RGB          (long)

You could use this function to "reassemble" lines with ANSI codes or other markup, by putting appropriate codes around each style run. For instance, if the "bold" flag was set, you might use <b> ... </b> .                          

The "action type", "action", "hint" and "variable" fields are used by MXP. See the MXP write-ups on the MUSHclient forum for more detail about what they are used for.

The colour codes are in RGB - you could use NormalColour or BoldColour to work out which ANSI colour they corresponded to (note, they might not correspond to any ANSI colour if MXP, or world.note has been used to output non-standard colours).

java_example:
// find foreground colour in RGB of style 2 on line 100

world.note (world.GetStyleInfo (100, 2, 14));

perl_example:
# find foreground colour in RGB of style 2 on line 100

$world->note ($world->GetStyleInfo (100, 2, 14));

return_value:
The specified information about the style run, as described above. 
An EMPTY variant, if the line or style does not exist. 
A NULL variant if the InfoType is not a valid type.

see_also:
GetLineInfo GetLinesInBufferCount NormalColour BoldColour GetSelectionStartLine GetSelectionEndLine GetSelectionStartColumn GetSelectionEndColumn GetInfo

python_example:
# find foreground colour in RGB of style 2 on line 100

world.note (world.GetStyleInfo (100, 2, 14))

lua_example:
-- find foreground colour in RGB of style 2 on line 100

Note (GetStyleInfo (100, 2, 14))

-- display the text for style 2 on line 71

Note (GetStyleInfo (71) [2].text)

-- Same thing, done differently:

Note (GetStyleInfo (71, 2).text)

lua_notes:
Lua returns nil where applicable instead of an "empty variant" or "null variant".

As an extension, you can supply zero for the StyleNumber and/or the InfoType.

If the StyleNumber is zero, then a table of all styles will be returned 
(keyed numerically starting at one).

If the InfoType is omitted or zero, then all types of information
for the nominated style are returned in a table, keyed by type:

 text:       text of style (string)                                   
 length:     length of style run (number) 
 column:     starting column of style run (number) 
 actiontype: action type - 0=none, 1=send to mud, 2=hyperlink, 3=prompt
 action:     action (eg. what to send) (string) 
 hint:       hint (what to show) (string) 
 variable:   variable (variable to set) (string) 
 bold:       true if bold (boolean) 
 ul:         true if underlined (boolean) 
 blink:      true if blinking (boolean) 
 inverse:    true if inverse (boolean) 
 changed:    true if changed by trigger from original (boolean) 
 starttag:   true if start of a tag (action is tag name) (boolean) 
 textcolour: foreground (text) colour in RGB (number) 
 backcolour: background colour in RGB (number)

This lets you readily re-assemble data from a particular line with only one
function call. Then just process the returned table.

If you omit (or set to zero) both the StyleNumber and InfoType then the 
returned result will be a table of tables. The outer table will have one entry 
per style, the inner table will have one entry per InfoType.

Example:

t = GetStyleInfo (71)     -- get all styles, all types for line 71
for k, v in pairs (t) do 
  Note ("style run = ", k)  -- this is one style
  for a, b in pairs (v) do  -- display all info types for style
    Note (" item = ", a, " value = ", b)
  end  
end


name: GetSelectionStartLine
prototype: long GetSelectionStartLine();
summary: Returns the starting line of the selection in the output window
vb_example: world.note world.GetSelectionStartLine
java_example: world.note (world.GetSelectionStartLine ());
perl_example: $world->note ($world->GetSelectionStartLine ());
return_value: The number of the first line in the selection, or zero if no selection.
type_of_object: Method
see_also: GetLinesInBufferCount GetLineInfo GetSelectionEndLine GetSelectionStartColumn GetSelectionEndColumn
python_example: world.note (world.GetSelectionStartLine )
doc_name: info
lua_example: Note (GetSelectionStartLine ())
description:
Returns a number in the range 1 to the number of lines in the output window, which is the first "selected" line.

If no selection, returns zero.


name: GetSelectionEndLine
prototype: long GetSelectionEndLine();
summary: Returns the last line of the selection in the output window
vb_example: world.note world.GetSelectionEndLine
java_example: world.note (world.GetSelectionEndLine ());
perl_example: $world->note ($world->GetSelectionEndLine ());
return_value: The number of the last line in the selection, or zero if no selection.
type_of_object: Method
python_example: world.note (world.GetSelectionEndLine )
doc_name: info
lua_example: Note (GetSelectionEndLine ())
description:
Returns a number in the range 1 to the number of lines in the output window, which is the last "selected" line. 

If no selection, returns zero.

see_also:
GetLineInfo GetLinesInBufferCount GetSelectionStartLine GetSelectionStartColumn GetSelectionEndColumn


name: GetSelectionStartColumn
prototype: long GetSelectionStartColumn();
summary: Returns the starting column of the selection in the output window
vb_example: world.note world.GetSelectionStartColumn
java_example: world.note (world.GetSelectionStartColumn ());
perl_example: $world->note ($world->GetSelectionStartColumn ());
return_value: The number of the first column in the selection, or zero if no selection. The first column is 1.
type_of_object: Method
python_example: world.note (world.GetSelectionStartColumn )
doc_name: info
lua_example: Note (GetSelectionStartColumn ())
description:
Returns the first column of the selected text in the output window (starting at 1).

If no selection, returns zero.

If you want to the current selection in the *command* window, use GetInfo(236) (first character) and GetInfo(237) (last character) instead.

see_also:
GetLineInfo GetStyleInfo GetLinesInBufferCount GetSelectionEndLine GetSelectionEndLine GetSelectionEndColumn


name: GetSelectionEndColumn
prototype: long GetSelectionEndColumn();
summary: Returns the endling column of the selection in the output window
vb_example: world.note world.GetSelectionEndColumn
java_example: world.note (world.GetSelectionEndColumn ());
perl_example: $world->note ($world->GetSelectionEndColumn ());
return_value: The number of the last column in the selection, or zero if no selection. The first column is 1.
type_of_object: Method
python_example: world.note (world.GetSelectionEndColumn )
doc_name: info
lua_example: Note (GetSelectionEndColumn ())
description:
Returns the last column of the selected text in the output window (starting at 1). 

If no selection, returns zero.


If you want to the current selection in the *command* window, use GetInfo(236) (first character) and GetInfo(237) (last character) instead.

see_also:
GetLineInfo GetStyleInfo GetLinesInBufferCount GetSelectionStartLine GetSelectionEndLine GetSelectionStartColumn


name: GetCommandList
prototype: VARIANT GetCommandList(long Count);
summary: Returns some or all commands from the command history
type_of_object: Method
see_also: GetCommand PushCommand SelectCommand SetCommand
description:
This returns a variant array of the nominated number of most recent commands (in the command history window). 

You can get all available commands by requesting a count of zero. (You can get the most recently saved command by requesting a count of 1). 

If you request more than the available number, then the number of items in the array may be less than that requested.

You can get the current command (not yet in the command history list) by using world.GetCommand.

vb_example:
dim commandList
dim iCount

'
' Get last 10 commands
'
  commandList = world.GetCommandList (10)

  If Not IsEmpty (commandList) Then
    For Each command In commandList  
      world.Note command 
    Next
  End If

'
' ------------------------
'

'
' Get most recent command
'

  world.note world.getcommandlist (1) (0)

java_example:
//
// Get last 10 commands
//
  
  commandList = new VBArray(world.GetCommandList (10)).toArray();

  if (commandList) 
    for (i = 0; i < commandList.length; i++)
        world.note (commandList [i]);

perl_example:
#
#  Get last 10 commands
#

foreach $item (Win32::OLE::in ($world->GetCommandList (10)))
 {
 $world->note($item);
 }

return_value:
If there are no commands in the history list then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the specified number of commands (counting from the most recent). Use "ubound" to find the number of commands in the list.

python_example:
#
# Get last 10 commands
#

commandList = world.GetCommandList (10)
if (commandList ):
  for c in commandList : world.Note (c)

lua_example:
--
-- Get last 10 commands
--

for k, v in ipairs (GetCommandList (10)) do 
  print (k, v)   --> command number, what the command was
end


name: PushCommand
prototype: BSTR PushCommand();
summary: Pushes the current command into the command history list
vb_example: world.PushCommand
java_example: world.PushCommand ();
perl_example: $world->PushCommand ();
return_value: The original contents of the command window.
type_of_object: Method
see_also: SetCommand GetCommand GetCommandList SelectCommand
python_example: world.PushCommand
lua_example: PushCommand ()
description:
Pushes the current contents of the command window into the command history list, and then blanks the current command.

You could use this prior to doing SetCommand, as SetCommand will not work with a command in the command window.

This function returns the text of the command that was in the command window, in case you want to restore it later.

If more than one window is open for this world, it uses the first window in the window list.


name: SelectCommand
prototype: void SelectCommand();
summary: Selects (highlights) the current command in the command window
vb_example: world.SelectCommand
java_example: world.SelectCommand ();
perl_example: $world->SelectCommand ();
return_value: Nothing.
type_of_object: Method
see_also: SetCommand GetCommand GetCommandList PushCommand
python_example: world.SelectCommand
lua_example: SelectCommand ()
description:
Selects the command in the command window. 

The intention here is to be used by scripts that place text in the command window. By selecting it, the player can discard the selected command by simply starting to type.

If more than one window is open for this world, it uses the first window in the window list.


name: GetCommand
prototype: BSTR GetCommand();
summary: Gets the current command in the command window
vb_example: world.Note world.GetCommand
java_example: world.Note (world.GetCommand ());
perl_example: $world->Note ($world->GetCommand ());
return_value: The contents of the command window.
type_of_object: Method
see_also: SetCommand SelectCommand GetCommandList PushCommand
python_example: world.Note (world.GetCommand )
lua_example: Note (GetCommand ())
description:
Returns the current contents of the command window, without changing it.

If more than one window is open for this world, it uses the first window in the window list.


name: DoAfter
prototype: long DoAfter(double Seconds, BSTR SendText);
summary: Adds a one-shot, temporary timer - simplified interface
vb_example: world.DoAfter 10, "eat food" world.DoAfter 20.5, "get bottle bag" world.DoAfter 21, "drink water"
return_value: eTimeInvalid: The time is invalid (seconds not in range 0.1 to 86,399). eOK: added OK
type_of_object: Method
see_also: AddTimer DoAfterSpeedWalk DoAfterNote DoAfterSpecial
doc_name: timers
lua_example: DoAfter (10, "eat food") DoAfter (20.5, "get bottle bag") DoAfter (21, "drink water")
description:
This routine adds an unlabelled, temporary, one-shot timer, set to go off after the designated number of seconds. The first argument (seconds) must evaluate to a time between 0.1 second, and 23 hours 59 minutes 59 seconds (that is, 0.1 to  86,399).

From version 3.61 onwards of MUSHclient the interval may include fractions (ie. it is a floating-point number). This lets you set up sub-second intervals (eg. 0.5 seconds, 1.2 seconds).

To enable this you need to go to Global Configuration -> Timers and set the 'Timer Interval' in seconds to zero.

The maximum granularity of the timers is currently 0.1 seconds. In other words, regardless of what you specify, the timers are only checked every 10th of a second.

You can also use DoAfterSpeedWalk - this is the same as DoAfter, except the command is interpreted as a speedwalk sequence.

You can also use DoAfterNote - this is the same as DoAfter, except the text is sent to the output window, not the MUD.

The purpose of this is simplify the frequent case of simply wanting to do something in a few seconds, rather than using AddTimer.

WARNING - as DoAfter is implemented by using temporary MUSHclient timers, it will not work if timers are disabled. If DoAfter is not working for you (however the function call is returning zero) then ensure that timers are enabled in the Timers configuration dialog.

java_example:
world.DoAfter (10, "eat food");
world.DoAfter (20.5, "get bottle bag");
world.DoAfter (21, "drink water");

perl_example:
$world->DoAfter (10, "eat food");
$world->DoAfter (20.5, "get bottle bag");
$world->DoAfter (21, "drink water");

python_example:
world.DoAfter (10, "eat food")
world.DoAfter (20.5, "get bottle bag")
world.DoAfter (21, "drink water")


name: DoAfterSpeedWalk
prototype: long DoAfterSpeedWalk(long Seconds, BSTR SendText)
summary: Adds a one-shot, temporary speedwalk timer - simplified interface
vb_example: world.DoAfterSpeedWalk 10, "5e 4s w"
java_example: world.DoAfterSpeedWalk (10, "5e 4s w");
perl_example: $world->DoAfterSpeedWalk (10, "5e 4s w");
return_value: eTimeInvalid: The time is invalid (seconds not in range 0.1 to 86,399). eOK: added OK
type_of_object: Method
see_also: AddTimer DoAfter DoAfterNote DoAfterSpecial
python_example: world.DoAfterSpeedWalk (10, "5e 4s w")
doc_name: timers
lua_example: DoAfterSpeedWalk (10, "5e 4s w")
description:
This routine adds an unlabelled, temporary, one-shot speedwalk timer, set to go off after the designated number of seconds. The first argument (seconds) must evaluate to a time between 0.1 second, and 23 hours 59 minutes 59 seconds (that is, 0.1 to 86,399). 

From version 3.61 onwards of MUSHclient the interval may include fractions (ie. it is a floating-point number). This lets you set up sub-second intervals (eg. 0.5 seconds, 1.2 seconds).

To enable this you need to go to Global Configuration -> Timers and set the 'Timer Interval' in seconds to zero.

The maximum granularity of the timers is currently 0.1 seconds. In other words, regardless of what you specify, the timers are only checked every 10th of a second.

You can also use DoAfter if you do not wish to speed walk, or DoAfterNote if you want to send a note to the output window.

The purpose of this is simplify the frequent case of simply wanting to do something in a few seconds, rather than using AddTimer.


WARNING - as DoAfterSpeedWalk is implemented by using temporary MUSHclient timers, it will not work if timers are disabled. If DoAfterSpeedWalk is not working for you (however the function call is returning zero) then ensure that timers are enabled in the Timers configuration dialog.


name: AddTriggerEx
summary: Adds a trigger - extended arguments
vb_example: world.AddTriggerEx "", "* attacks", "You are under attack!", 1, 14, 0, "", "", 2, 50
java_example: world.AddTriggerEx ("", "* attacks", "You are under attack!", 1, 14, 0, "", "", 2, 50);
perl_example: $world->AddTriggerEx ("", "* attacks", "You are under attack!", 1, 14, 0, "", "", 2, 50);
type_of_object: Method
python_example: world.AddTriggerEx ("", "* attacks", "You are under attack!", 1, 14, 0, "", "", 2, 50)
doc_name: triggers
prototype:
long AddTriggerEx(BSTR TriggerName, BSTR MatchText, BSTR ResponseText, long Flags, short Colour, short Wildcard, BSTR SoundFileName, BSTR ScriptName, short SendTo, short Sequence);

description:
Adds a trigger to the list of triggers. If you are prepared to accept the default values for Sequence and "Send To" you can use AddTrigger instead.

For AddTrigger they default to: 
Sequence: 100 
Send to: world 

Name: name of this trigger - may be empty  (see rules for names below)
Match_text: what to match on 
Response_text: what to send back to the world 
Flags: various flags, see list below 
Colour: what colour to draw triggered text, see list below 
Wildcard: Copy which wildcard to the clipboard (0 = none), otherwise 1 to 10. 
SoundFileName: Which sound file to play 
ScriptName: Which script subroutine to execute 
Sequence: Sequence number of trigger (lower is evaluated earlier). Must be in range 0 to 10,000
Send To: Where to send the trigger text to ...

0: World 
1: Command window
2: Output window
3: Status line
4: Notepad (new)
5: Notepad (append)
6: Log File 
7: Notepad (replace)
8: Command queue
9: Send To Variable
10: Execute (re-parse as command)
11: Speedwalk (send text is speedwalk, queue it)
12: Script (send to script engine)
13: Immediate (send to world in front of speedwalk queue)
14: Script - after omit (send to script engine, after lines have been omitted)


Flags 

The flags can be one or more of the constants below. For example, to omit from log and omit from output, the flags would be 6. Preferably use the constant declarations in your script file, and "OR" them together. E.g. 

VBscript: eOmitFromLog or eOmitFromOutput 
JScript: eOmitFromLog | eOmitFromOutput 

VBscript: 

const eEnabled = 1 ' enable trigger 
const eOmitFromLog = 2 ' omit from log file 
const eOmitFromOutput = 4 ' omit trigger from output 
const eKeepEvaluating = 8 ' keep evaluating 
const eIgnoreCase = 16 ' ignore case when matching 
const eTriggerRegularExpression = 32 ' trigger uses regular expression 
const eExpandVariables = 512 ' expand variables like @direction 
const eReplace = 1024 ' replace existing trigger of same name 
const eTemporary = 16384 ' temporary - do not save to world file 

JScript: 

var eEnabled = 1; // enable trigger 
var eOmitFromLog = 2; // omit from log file 
var eOmitFromOutput = 4; // omit trigger from output 
var eKeepEvaluating = 8; // keep evaluating 
var eIgnoreCase = 16; // ignore case when matching 
var eTriggerRegularExpression = 32; // trigger uses regular expression 
var eExpandVariables = 512; // expand variables like @direction 
var eReplace = 1024; // replace existing trigger of same name 
var eTemporary = 16384; // temporary - do not save to world file 

PerlScript constants: 

$eEnabled = 1; # enable trigger 
$eOmitFromLog = 2; # omit from log file 
$eOmitFromOutput = 4; # omit trigger from output 
$eKeepEvaluating = 8; # keep evaluating 
$eIgnoreCase = 16; # ignore case when matching 
$eTriggerRegularExpression = 32; # trigger uses regular expression 
$eExpandVariables = 512; # expand variables like @direction 
$eReplace = 1024; # replace existing trigger of same name 
$eTemporary = 16384; # temporary - do not save to world file 


Colours 

VBscript: 

const NOCHANGE = -1 
const custom1 = 0 
const custom2 = 1 
const custom3 = 2 
const custom4 = 3 
const custom5 = 4 
const custom6 = 5 
const custom7 = 6 
const custom8 = 7 
const custom9 = 8 
const custom10 = 9 
const custom11 = 10 
const custom12 = 11 
const custom13 = 12 
const custom14 = 13 
const custom15 = 14 
const custom16 = 15 

JScript: 

var NOCHANGE = -1; 
var custom1 = 0; 
var custom2 = 1; 
var custom3 = 2; 
var custom4 = 3; 
var custom5 = 4; 
var custom6 = 5; 
var custom7 = 6; 
var custom8 = 7; 
var custom9 = 8; 
var custom10 = 9; 
var custom11 = 10; 
var custom12 = 11; 
var custom13 = 12; 
var custom14 = 13; 
var custom15 = 14; 
var custom16 = 15; 

PerlScript: 

$NOCHANGE = -1; 
$custom1 = 0; 
$custom2 = 1; 
$custom3 = 2; 
$custom4 = 3; 
$custom5 = 4; 
$custom6 = 5; 
$custom7 = 6; 
$custom8 = 7; 
$custom9 = 8; 
$custom10 = 9; 
$custom11 = 10; 
$custom12 = 11; 
$custom13 = 12; 
$custom14 = 13; 
$custom15 = 14; 
$custom16 = 15;

* 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 (_)

return_value:
eInvalidObjectLabel: The trigger name is not valid 
eTriggerAlreadyExists: A trigger of that name already exists 
eTriggerCannotBeEmpty: The "match_text" cannot be empty 
eScriptNameNotLocated: The script name cannot be located in the script file 
eBadRegularExpression: The regular expression could not be evaluated
eTriggerSequenceOutOfRange: Sequence is not in range 0 to 10000
eTriggerSendToInvalid: Send to field is not in range 0 to 9 
eOK: added OK

see_also:
AddTrigger DeleteTrigger EnableTrigger GetTrigger GetTriggerList IsTrigger GetTriggerInfo SetTriggerOption GetTriggerOption ImportXML

lua_example:
AddTriggerEx ("", "* attacks", "You are under attack!", trigger_flag.Enabled, custom_colour.Custom15, 0, "", "", 2, 50)

lua_notes:
The trigger sequence is optional and defaults to 100.

The trigger flags are built into the "trigger_flag" table, as follows:

trigger_flag.Enabled = 1
trigger_flag.OmitFromLog = 2
trigger_flag.OmitFromOutput = 4
trigger_flag.KeepEvaluating = 8
trigger_flag.IgnoreCase = 16
trigger_flag.RegularExpression = 32
trigger_flag.ExpandVariables = 512
trigger_flag.Replace = 1024
trigger_flag.Temporary = 16384
trigger_flag.LowercaseWildcard = 2048


The colour names for custom colours are built into the "custom_colour" table, as follows:

custom_colour.NoChange = -1
custom_colour.Custom1 = 0
custom_colour.Custom2 = 1
custom_colour.Custom3 = 2
custom_colour.Custom4 = 3
custom_colour.Custom5 = 4
custom_colour.Custom6 = 5
custom_colour.Custom7 = 6
custom_colour.Custom8 = 7
custom_colour.Custom9 = 8
custom_colour.Custom10 = 9
custom_colour.Custom11 = 10
custom_colour.Custom12 = 11
custom_colour.Custom13 = 12
custom_colour.Custom14 = 13
custom_colour.Custom15 = 14
custom_colour.Custom16 = 15
custom_colour.CustomOther = 16

The "SendTo" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0
sendto.command = 1
sendto.output = 2
sendto.status = 3
sendto.notepad = 4
sendto.notepadappend = 5
sendto.logfile = 6
sendto.notepadreplace = 7
sendto.commandqueue = 8
sendto.variable = 9
sendto.execute = 10
sendto.speedwalk = 11
sendto.script = 12
sendto.immediate = 13
sendto.scriptafteromit = 14


name: GetQueue
prototype: VARIANT GetQueue();
summary: Returns a variant array which is a list of queued commands
perl_example: foreach $item (Win32::OLE::in ($world->GetQueue ())) { $world->note($item); }
type_of_object: Method
see_also: DiscardQueue Queue SpeedWalkDelay
python_example: commandList = world.GetQueue if (commandList): for c in commandList : world.Note (c)
doc_name: info
lua_example: for k, v in pairs (GetQueue()) do Note (v) end
description:
Returns an array of the currently queued commands (speedwalks etc.).

You might use this if you needed to do something urgently. Retrieve the queue into an array, discard the queue, and then requeue it.

vb_example:
dim speedwalkQueue

  speedwalkQueue = world.GetQueue

  If Not IsEmpty (speedwalkQueue) Then
    For Each sw In speedwalkQueue 
       world.note sw
    Next

  End If

java_example:
commandList = new VBArray(world.GetQueue()).toArray();

 if (commandList) 
   for (i = 0; i < commandList.length; i++)
       world.note (commandList [i]);

return_value:
If there are no commands in the queue then the return value is empty. Use "IsEmpty" to test for this possibility. 

Otherwise, it returns a variant array containing all queued commands. Use "ubound" to find the number of commands in the list.


name: Debug
prototype: VARIANT Debug(BSTR Command);
summary: Displays debugging information about the world
vb_example: /world.Debug "colours"
java_example: /world.Debug ("colours");
perl_example: /$world->Debug ("colours");
type_of_object: Method
see_also: Simulate
python_example: world.Debug ("colours")
doc_name: info
lua_example: Debug ("colours")
description:
You can use this to quickly list things of interest about the world.

You can currently get the following information:

"actions" - things like hyperlinks that do something

"aliases" - list of world aliases

"alpha_options" - the world's alpha (string) options, and their values

"ansi" - lists the ANSI colours defined in the ANSI configuration tab (with swatches) 

"arrays" - list of world arrays (see ArrayCreate)

"colours" - known colour names, (with swatches) and RGB codes etc.

"colours256" - list of extended ANSI colours (with swatches)

"commands" - lists command history

"custom_colours - lists the 16 custom colours along with their names (with swatches) 

"entities" - lists known MXP entities with what the translate to

"global_options" - list of global options and their values

"included_options" - list of options set by included files

"info" - lists all GetInfo items and associated values

"internal_commands" - lists commands that can be done with DoCommand

"options" - the world's numeric options, and their values

"option_info" - list of alpha/numeric options and their ranges

"plugins" - lists information for each plugin (aliases, triggers, etc.)

"server_elements" - lists MXP elements defined by the MUD server

"server_entities" - lists MXP entities defined by the MUD server

"summary" - summarizes triggers, aliases, world info, plugins, miniwindows

"triggers" - list of world triggers

"variables" - list of world variables


eg. /world.Debug "aliases"

To find the list without referring to this web page, just type:

/world.Debug ""

return_value:
Returns a variant, however it is not used at present. The debug information is displayed in the world window.


name: DeleteTemporaryTimers
prototype: long DeleteTemporaryTimers();
summary: Deletes all temporary timers
vb_example: world.DeleteTemporaryTimers
java_example: world.DeleteTemporaryTimers ();
perl_example: $world->DeleteTemporaryTimers ();
return_value: Returns a count of the number of timers deleted.
type_of_object: Method
see_also: AddTimer DoAfter DoAfterSpeedWalk DoAfterNote DeleteTemporaryAliases DeleteTemporaryTriggers
python_example: world.DeleteTemporaryTimers
doc_name: timers
lua_example: DeleteTemporaryTimers ()
description:
Deletes all timers marked as "temporary". 

The intention here is to provide a quick way of restoring the world to how it would be after loading (since temporary timers are not loaded from the world file).

You might also use this if a runaway script created too many temporary timers with "DoAfter" or similar.


name: DoAfterNote
prototype: long DoAfterNote(long Seconds, BSTR NoteText);
summary: Adds a one-shot, temporary note timer - simplified interface
vb_example: world.DoAfterNote 60, "Spell has worn off!"
java_example: world.DoAfterNote (60, "Spell has worn off!");
perl_example: $world->DoAfterNote (60, "Spell has worn off!");
return_value: eTimeInvalid: The time is invalid (seconds not in range 0.1 to 86,399). eOK: added OK
type_of_object: Method
see_also: AddTimer DoAfter DoAfterSpeedWalk DoAfterSpecial
python_example: world.DoAfterNote (60, "Spell has worn off!")
doc_name: note
lua_example: DoAfterNote (60, "Spell has worn off!")
description:
This routine adds an unlabelled, temporary, one-shot note timer, set to go off after the designated number of seconds. The first argument (seconds) must evaluate to a time between 0.1 second, and 23 hours 59 minutes 59 seconds (that is, 0.1 to 86,399). 

From version 3.61 onwards of MUSHclient the interval may include fractions (ie. it is a floating-point number). This lets you set up sub-second intervals (eg. 0.5 seconds, 1.2 seconds).

To enable this you need to go to Global Configuration -> Timers and set the 'Timer Interval' in seconds to zero.

The maximum granularity of the timers is currently 0.1 seconds. In other words, regardless of what you specify, the timers are only checked every 10th of a second.

When the time elapses the text will be "noted" - that is, displayed in the output window, not sent to the MUD.

You can also use DoAfter if you wish to send to the world. 

The purpose of this is simplify the frequent case of simply wanting to do something in a few seconds, rather than using AddTimer.


WARNING - as DoAfterNote is implemented by using temporary MUSHclient timers, it will not work if timers are disabled. If DoAfterNote is not working for you (however the function call is returning zero) then ensure that timers are enabled in the Timers configuration dialog.


name: DeleteTemporaryAliases
prototype: long DeleteTemporaryAliases();
summary: Deletes all temporary aliases
vb_example: world.DeleteTemporaryAliases
java_example: world.DeleteTemporaryAliases ();
perl_example: $world->DeleteTemporaryAliases ();
return_value: Returns a count of the number of aliases deleted.
type_of_object: Method
see_also: DeleteTemporaryTimers DeleteTemporaryTriggers AddAlias
python_example: world.DeleteTemporaryAliases
doc_name: aliases
lua_example: DeleteTemporaryAliases ()
description:
Deletes all aliases marked as "temporary". 

The intention here is to provide a quick way of restoring the world to how it would be after loading (since temporary aliases are not loaded from the world file).


name: DeleteTemporaryTriggers
prototype: long DeleteTemporaryTriggers();
summary: Deletes all temporary triggers
vb_example: world.DeleteTemporaryTriggers
java_example: world.DeleteTemporaryTriggers ();
perl_example: $world->DeleteTemporaryTriggers ();
return_value: Returns a count of the number of triggers deleted.
type_of_object: Method
see_also: DeleteTemporaryTimers DeleteTemporaryAliases AddTrigger
python_example: world.DeleteTemporaryTriggers
doc_name: triggers
lua_example: DeleteTemporaryTriggers ()
description:
Deletes all triggers marked as "temporary". 

The intention here is to provide a quick way of restoring the world to how it would be after loading (since temporary triggers are not loaded from the world file).


name: GetAlphaOption
prototype: VARIANT GetAlphaOption(BSTR OptionName);
summary: Gets the value of an alphanumeric configuration option
vb_example: world.note world.getalphaoption ("player")
java_example: /world.note(world.getalphaoption ("player"));
perl_example: /$world->note ($world->getalphaoption ("player"));
return_value: The value of the requested option, or an "empty" variant if the option does not exist.
type_of_object: Method
see_also: SetAlphaOption GetAlphaOptionList GetOption SetOption GetOptionList GetInfo
python_example: world.note(world.getalphaoption ("player"))
doc_name: options
lua_example: Note (GetAlphaOption("player"))
description:
Gets the value of an alphanumeric world option (text option), such as player name, MUD name etc.

You can use GetAlphaOptionList to get a list of the names of all possible options.


name: GetAlphaOptionList
prototype: VARIANT GetAlphaOptionList();
summary: Gets the list of world alphanumeric options
type_of_object: Method
see_also: GetAlphaOption SetAlphaOption GetOption SetOption GetOptionList GetInfo
python_example: for opt in world.GetAlphaOptionList: world.Note (opt)
doc_name: options
lua_example: for k, v in pairs (GetAlphaOptionList ()) do Note (v) end
description:
Returns a variant array which is a list of all options that you can get with GetAlphaOption or set with SetAlphaOption. 

The examples show extracting all option names, and their values. 

The option names should be reasonably self-explanatory.

vb_example:
For Each opt In world.GetAlphaOptionList
   world.note opt + " = " + cstr (world.GetAlphaOption ( opt ))
Next

java_example:
optionlist = new VBArray(world.GetAlphaOptionList()).toArray();

for (i = 0; i < optionlist .length; i++)
  world.note(optionlist [i] + " = " + world.GetAlphaOption (optionlist [i] ));

perl_example:
foreach $item (Win32::OLE::in ($world->GetAlphaOptionList))
  {
  $world->note($item . " = " . $world->GetAlphaOption($item));
  }

return_value:
It returns a variant array containing the names of all the options. Use "ubound" to find the number of options in the list. You can then use "GetAlphaOption" to return the value for that particular option, or "SetAlphaOption" to set that option value.


name: SetAlphaOption
prototype: long SetAlphaOption(BSTR OptionName, BSTR Value);
summary: Sets value of a named world alphanumeric option
vb_example: world.setalphaoption "player", "Gandalf"
java_example: world.setalphaoption ("player", "Gandalf");
perl_example: $world->setalphaoption ("player", "Gandalf");
return_value: eUnknownOption - option name not recognised eOK - set OK
type_of_object: Method
see_also: GetAlphaOptionList GetAlphaOption GetOptionList GetOption SetOption GetInfo
python_example: world.setalphaoption ("player", "Gandalf")
doc_name: options
lua_example: SetAlphaOption ("player", "Gandalf")
description:
Sets the value of a world alphanumeric (string) option.

You can use GetAlphaOptionList to get a list of the names of all possible options.

Use SetOption to set numeric and boolean options.


name: ColourNameToRGB
prototype: long ColourNameToRGB(BSTR Name);
summary: Converts a named colour to a RGB colour code.
vb_example: world.note world.colourNameToRGB ("brown")
java_example: world.note (world.colourNameToRGB ("brown"));
perl_example: $world->note ($world->colourNameToRGB ("brown"));
type_of_object: Method
python_example: world.note (world.colourNameToRGB ("brown"))
doc_name: colours
lua_example: Note (ColourNameToRGB ("brown"))
description:
Converts a named colour (eg. "brown") to an RGB colour code (eg. 2763429).

The colours can either be named (eg. "red", "blue", "green", "brown") or supplied as HTML colour codes (eg. "#010203"). For HTML colours, the leading "#" is required.

The list of colour names recognised can be found by using MUSHclient's "colour picker" (Ctrl+Alt+P), or by using the function:

world.Debug "colours"

return_value:
The RGB code of the converted colour, or -1 if the colour name is not recognised. Note that -1 cannot be an RGB colour (-1 is the hex sequence 0xFFFFFFFF, whereas the "highest" colour (white) is hex 0x00FFFFFF).

see_also:
RGBColourToName CustomColourBackground BoldColour CustomColourText Debug NormalColour NoteColourBack NoteColourFore NoteColourName NoteColourRGB MapColour PickColour


name: DeleteGroup
prototype: long DeleteGroup(BSTR GroupName);
summary: Deletes a group of triggers, aliases and timers
vb_example: world.DeleteGroup "groupname"
java_example: world.DeleteGroup ("groupname");
perl_example: $world->DeleteGroup ("groupname");
return_value: A count of the number of items deleted.
type_of_object: Method
python_example: world.DeleteGroup ("groupname")
doc_name: group
lua_example: DeleteGroup ("groupname")
description:
Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To delete an entire group of triggers, aliases and timers do this: 

  world.DeleteGroup "groupname"

For debugging purposes the function returns a count of the number of members deleted. eg.

  dim mycount
  mycount = world.DeleteGroup ("groupname")

If you are using plugins only the members of the current plugin (if any) are deleted. If the call is made outside a plugin only the members of the group that are not in a plugin are deleted.

see_also:
EnableGroup EnableTriggerGroup EnableAliasGroup EnableTimerGroup GetAliasInfo GetTriggerInfo GetTimerInfo DeleteTriggerGroup DeleteAliasGroup DeleteTimerGroup


name: RGBColourToName
prototype: BSTR RGBColourToName(long Colour);
summary: Converts an RGB colour code to its equivalent name
vb_example: world.note world.RGBColourToName (255)
java_example: world.note (world.RGBColourToName (255));
perl_example: $world->note ($world->RGBColourToName (255));
return_value: The colour name (eg. "red", "blue"), or an RGB code (eg. "#FFE4E1).
type_of_object: Method
python_example: world.note (world.RGBColourToName (255))
doc_name: colours
lua_example: Note (RGBColourToName (255))
description:
Converts an RGB colour code (eg. 255) to its HTML name (eg. "red").

If the name is not in the list of names recognised by MUSHclient, the colour is represented as a hex HTML colour (eg. "#010203").

The list of colour names recognised can be found by using MUSHclient's "colour picker" (Ctrl+Alt+P), or by using the function: 

world.Debug "colours"

see_also:
ColourNameToRGB CustomColourBackground BoldColour CustomColourText Debug NormalColour NoteColourBack NoteColourFore NoteColourName NoteColourRGB MapColour PickColour


name: Base64Decode
prototype: VARIANT Base64Decode(BSTR Text);
summary: Takes a base-64 encoded string and decodes it.
vb_example: world.note world.Base64Decode ("TmljayBHYW1tb24=")
java_example: world.note (world.Base64Decode ("TmljayBHYW1tb24="));
perl_example: $world->note ($world->Base64Decode ("TmljayBHYW1tb24="));
type_of_object: Method
see_also: Base64Encode
python_example: world.note (world.Base64Decode ("TmljayBHYW1tb24="))
doc_name: utils
description:
Takes a base-64 encoded string (eg. "TmljayBHYW1tb24=") and decodes it. The string may contain space characters (including carriage-return/newline) which will be removed.

The string to be decoded must contain valid base-64 characters, and must be a multiple of 4 characters long (once spaces are removed), or a NULL variant will be returned.

The valid base-64 characters are:

'A','B','C','D','E','F','G','H','I','J','K','L','M','N','O','P',
'Q','R','S','T','U','V','W','X','Y','Z','a','b','c','d','e','f',
'g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','v',
'w','x','y','z','0','1','2','3','4','5','6','7','8','9','+','/'

Also, '=' is used as a padding character if the original text to be encoded was not exactly a multiple of 3 characters long.

Because of the way strings are stored this will not work with strings which have nulls in them (hex 00), however see below for a work-around for Lua.

return_value:
The decoded string, or a NULL variant if the input string was not a multiple of 4 characters in length, once spaces were removed, or did not contain the valid base-64 characters listed above.

Note that due to the way strings are represented internally, it is not possible for the decoded string to contain the NULL character (hex 0x00) and be returned correctly.

lua_example:
Note (Base64Decode ("TmljayBHYW1tb24="))

-- or, as described in the notes:

Note (utils.base64decode ("TmljayBHYW1tb24="))

lua_notes:
In MUSHclient version 3.57 onwards you can also use 

decoded_string = utils.base64decode (s)

This works the same as described above, however it will correctly handle strings with the null (hex 00) character in them.

This function works a bit differently if it encounters "bad" data:

* Characters not in the set shown above are silently ignored

* If the source string is not a multiple of four characters, the string is still processed, however up to the last 3 bytes will not be returned.


name: Base64Encode
prototype: VARIANT Base64Encode(BSTR Text, BOOL MultiLine);
summary: Encodes a string using base-64 encoding.
vb_example: world.note world.base64encode ("swordfish", 0)
java_example: world.note (world.base64encode ("swordfish", 0));
perl_example: $world->note ($world->base64encode ("swordfish", 0));
return_value: The encoded string.
type_of_object: Method
see_also: Base64Decode
python_example: world.note (world.base64encode ("swordfish", 0))
doc_name: utils
lua_example: Note (Base64Encode ("swordfish", 0))
description:
Encodes a string (like "swordfish") returning it as base-64 characters (eg. "c3dvcmRmaXNo").

Each 3 characters of input become 4 characters of output. This can be used:

a) as a primitive form of encryption (or 'information hiding')
b) to send non-printable characters as a text stream

Note that due to the way strings are represented internally, it is not possible for the encoded string to contain the NULL character (hex 0x00) and be returned correctly, however see below for a work-around for Lua.

If "multiline" is true, then the returned string will have a carriage-return/linefeed after every 76 characters, otherwise it will be one long text stream.

lua_notes:
The multi-line flag is optional, and defaults to false.

---

In MUSHclient version 3.57 onwards you can also use 

encoded_string = utils.base64encode (s, [, linebreaks] )

This works the same as described above, however it will correctly handle strings with the null (hex 00) character in them.


name: GetUniqueID
prototype: BSTR GetUniqueID();
summary: Creates a unique ID for general use, or for making Plugin IDs
vb_example: world.Note world.GetUniqueID
java_example: world.Note (world.GetUniqueID ());
perl_example: $world->Note ($world->GetUniqueID ());
return_value: A 24-character unique identifier.
type_of_object: Method
see_also: GetUniqueNumber CreateGUID Hash
python_example: world.Note (world.GetUniqueID )
doc_name: utils
lua_example: Note (GetUniqueID ())
description:
This uses CreateGUID to get a unique number, and then hashes it, retaining 24 characters (96 bits) of the hash. This generates a nice, unique identifier, like this: "0a96ce42d8e0ede554d3b9ab".

The advantage of using this over CreateGUID is that by hashing the number your network card MAC address is concealed. Conceivably some users might not want their MAC address to be revealed. The number generated here will be used by plugins to uniquely identify themselves.

You could also use it for variable, trigger, timer, alias names, when generated by a script, to ensure uniqueness over multiple sessions. You could also use it as a handy "password generator", as the number sequences are hardly going to be predicable.

Contrast this to "GetUniqueNumber" which only returns a unique number for this session of MUSHclient. Thus, the numbers (from "GetUniqueNumber") will not be unique over multiple sessions.

See also the new script function world.CreateGUID.

Also, using random number generation for unique identifiers has a chance of returning the same number, depending on a) the seed given to the generator; and b) the way the generator must eventually recyle and regenerate the same sequence.


name: GetPluginVariable
prototype: VARIANT GetPluginVariable(BSTR PluginID, BSTR VariableName);
summary: Gets the contents of a variable belonging to a plugin
type_of_object: Method
see_also: SetVariable GetVariableList GetVariable GetPluginVariableList
doc_name: plugins
lua_notes: Lua returns nil where applicable instead of an "empty variant" or "null variant".
description:
Gets the contents of the named variable for the nominated plugin. Each plugin has a unique ID - specify that ID to identify the plugin in question.

If the named variable does not exist, EMPTY is returned. 

If the name given is invalid, NULL is returned. 

If the nominated plugin does not exist, NULL is returned.

(Use "IsEmpty" and "IsNull" to test for these possibilities).

If you want to find the value of a variable in the current plugin, use "GetVariable".

If you are writing a plugin and want to find a "global" MUSHclient variable value, use an empty plugin ID, eg.

  world.Note world.GetPluginVariable ("", "target")

vb_example:
dim MyName

MyName = world.GetPluginVariable ("a42fbf74f394d8129df956ae", "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

java_example:
var MyName;

MyName = world.GetPluginVariable ("a42fbf74f394d8129df956ae", "MyName");

if (MyName == null)
  world.note("MyName is not defined");
else
  world.note(MyName);

perl_example:
$MyName = $world->GetPluginVariable ("a42fbf74f394d8129df956ae", "MyName");

if (!defined ($MyName)) 
  {
  $world->note ("MyName is not defined");
  }
else 
  {
  $world->note ($MyName);
  }

return_value:
The contents of the specified variable for the specified plugin.
An EMPTY variant, if the variable does not exist.
A NULL variant if the variable name is invalid, or the plugin is not installed.

python_example:
MyName = world.GetPluginVariable ("a42fbf74f394d8129df956ae", "MyName")

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

lua_example:
MyName = GetPluginVariable ("a42fbf74f394d8129df956ae", "MyName")

if MyName == nil then
  Note("MyName is not defined")
else
  Note(MyName)
end


name: GetPluginID
prototype: BSTR GetPluginID();
summary: Returns the 24-character ID of the current plugin
vb_example: world.Note world.GetPluginID
java_example: world.Note (world.GetPluginID ());
perl_example: $world->Note ($world->GetPluginID ());
return_value: The 24-character plugin ID of the current plugin, or an empty string if no plugin is running.
type_of_object: Method
see_also: GetPluginInfo GetPluginName GetWorldID
python_example: world.Note (world.GetPluginID )
doc_name: plugins
lua_example: Note (GetPluginID ())
description:
Returns the unique ID (identifier) of the currently-executing plugin. This will let the plugin find things out about itself (using GetPluginInfo). If no plugin is executing an empty string will be returned.

To find the unique ID of your current world (rather than plugin) use GetWorldID.


name: GetPluginList
prototype: VARIANT GetPluginList();
summary: Gets a list of installed plugins.
description: Returns an array of the unique IDs of all the plugins currently installed.
type_of_object: Method
doc_name: plugins
lua_example: for k, v in pairs (GetPluginList()) do Note (v, " = ", GetPluginInfo(v, 1)) end
vb_example:
dim pluginList 

pluginList = world.GetPluginList

If Not IsEmpty (pluginList) Then
                  
  For Each p In pluginList 
     world.note p & " = " &  world.GetPluginInfo (p, 1)
  Next

End If

java_example:
pluginlist = new VBArray(world.GetPluginList()).toArray();

if (pluginlist)  // if not empty
  for (i = 0; i < pluginlist.length; i++)
      world.note(pluginlist [i] + " = " + 
                 world.GetPluginInfo(pluginlist [i], 1));

perl_example:
foreach $item (Win32::OLE::in ($world->GetPluginList))
   {
   ($key, $value) = ($item, $world->GetPluginInfo ($item, 1));
   $world->note($key . " = " . $value) if (defined ($key));
   }

return_value:
If there are no plugins then the return value is empty. Use "IsEmpty" to test for this possibility. 

Otherwise, it returns a variant array containing the unique IDs of all the plugins. Use "lbound" and "ubound" to find the bounds of the array of plugins (ie. the number of plugins in the list). You can then use "GetPluginInfo" to find information about each plugin.

see_also:
GetPluginInfo IsPluginInstalled GetPluginVariableList GetPluginTriggerList GetPluginAliasList GetPluginTimerList CallPlugin PluginSupports EnablePlugin

python_example:
pluginlist = world.GetPluginList
if (pluginlist):
  for p in pluginlist: world.Note (p + " = " +
                  world.GetPluginInfo(p, 1))


name: GetPluginName
prototype: BSTR GetPluginName();
summary: Returns the name of the current plugin
vb_example: world.Note world.GetPluginName
java_example: world.Note (world.GetPluginName ());
perl_example: $world->Note ($world->GetPluginName ());
return_value: The name of the current plugin, or an empty string if no plugin is running.
type_of_object: Method
see_also: GetPluginInfo GetPluginID
python_example: world.Note (world.GetPluginName )
doc_name: plugins
lua_example: Note (GetPluginName ())
description:
Returns the name of the currently-executing plugin. If no plugin is executing an empty string will be returned.


name: GetPluginTriggerInfo
prototype: VARIANT GetPluginTriggerInfo(BSTR PluginID, BSTR TriggerName, short InfoType);
summary: Gets details about a named trigger for a specified plugin
vb_example: world.note world.GetPluginTriggerInfo ("c8efc9f9e1edd118c6f2dbf5", "monster", 2)
java_example: /world.note(world.GetPluginTriggerInfo ("c8efc9f9e1edd118c6f2dbf5", "monster", 2));
perl_example: /$world->note ($world->GetPluginTriggerInfo ("c8efc9f9e1edd118c6f2dbf5", "monster", 2));
type_of_object: Method
see_also: AddTrigger DeleteTrigger GetTriggerList GetTriggerInfo GetPluginTriggerList
python_example: world.note(world.GetPluginTriggerInfo ("c8efc9f9e1edd118c6f2dbf5", "monster", 2))
doc_name: triggers
lua_example: Note (GetPluginTriggerInfo ("c8efc9f9e1edd118c6f2dbf5", "monster", 2))
lua_notes: Lua returns nil where applicable instead of an "empty variant" or "null variant".
description:
Gets details about the specified trigger for the specified plugin.

You can obtain various "types" of information about the trigger by specifying an "InfoType". The possible InfoTypes are described under GetTriggerInfo.

If the named trigger does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the InfoType given is out of range, NULL is returned. If the plugin does not exist, NULL is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

If you want to find the value of a trigger in the current plugin, use "GetTriggerInfo".

If you are writing a plugin and want to find "global" MUSHclient trigger values, use an empty plugin ID, eg.

  world.Note world.GetPluginTriggerInfo ("", "my_trigger", 1)

return_value:
The specified information about the trigger, as described above.
An EMPTY variant, if the trigger does not exist.
A NULL variant if the trigger name is invalid.
A NULL variant if the InfoType is not a valid type.
A NULL variant if the plugin is not installed.


name: GetPluginAliasInfo
prototype: VARIANT GetPluginAliasInfo(BSTR PluginID, BSTR AliasName, short InfoType);
summary: Gets details about a named alias for a specified plugin
vb_example: world.note world.GetPluginAliasInfo ("c8efc9f9e1edd118c6f2dbf5", "my_alias", 2)
java_example: world.note(world.GetPluginAliasInfo ("c8efc9f9e1edd118c6f2dbf5", "my_alias", 2));
perl_example: /$world->note ($world->GetPluginAliasInfo ("c8efc9f9e1edd118c6f2dbf5", "my_alias", 2));
type_of_object: Method
see_also: AddAlias DeleteAlias GetAliasList GetAliasInfo GetPluginAliasList
python_example: world.note(world.GetPluginAliasInfo ("c8efc9f9e1edd118c6f2dbf5", "my_alias", 2))
doc_name: aliases
lua_example: Note (GetPluginAliasInfo ("c8efc9f9e1edd118c6f2dbf5", "my_alias", 2))
lua_notes: Lua returns nil where applicable instead of an "empty variant" or "null variant".
description:
Gets details about the specified alias for the specified plugin.

You can obtain various "types" of information about the alias by specifying an "InfoType". The possible InfoTypes are described under GetAliasInfo.

If the named alias does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the InfoType given is out of range, NULL is returned. If the plugin does not exist, NULL is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

If you want to find the value of a alias in the current plugin, use "GetAliasInfo".

If you are writing a plugin and want to find "global" MUSHclient alias values, use an empty plugin ID, eg.

  world.Note world.GetPluginAliasInfo ("", "my_alias", 1)

return_value:
The specified information about the alias, as described above.
An EMPTY variant, if the alias does not exist.
A NULL variant if the alias name is invalid.
A NULL variant if the InfoType is not a valid type.
A NULL variant if the plugin is not installed.


name: GetPluginTimerInfo
prototype: VARIANT GetPluginTimerInfo(BSTR PluginID, BSTR TimerName, short InfoType);
summary: Gets details about a named timer for a specified plugin
vb_example: world.note world.GetPluginTimerInfo ("c8efc9f9e1edd118c6f2dbf5", "my_timer", 2)
java_example: world.note(world.GetPluginTimerInfo ("c8efc9f9e1edd118c6f2dbf5", "my_timer", 2));
perl_example: $world->note ($world->GetPluginTimerInfo ("c8efc9f9e1edd118c6f2dbf5", "my_timer", 2));
type_of_object: Method
see_also: AddTimer DeleteTimer GetTimerList GetTimerInfo GetPluginTimerList
python_example: world.note(world.GetPluginTimerInfo ("c8efc9f9e1edd118c6f2dbf5", "my_timer", 2))
doc_name: plugins
lua_example: Note(GetPluginTimerInfo ("c8efc9f9e1edd118c6f2dbf5", "my_timer", 2))
lua_notes: Lua returns nil where applicable instead of an "empty variant" or "null variant".
description:
Gets details about the specified timer for the specified plugin.

You can obtain various "types" of information about the timer by specifying an "InfoType". The possible InfoTypes are described under GetTimerInfo.

If the named timer does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the InfoType given is out of range, NULL is returned. If the plugin does not exist, NULL is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

If you want to find the value of a timer in the current plugin, use "GetTimerInfo".

If you are writing a plugin and want to find "global" MUSHclient timer values, use an empty plugin ID, eg.

  world.Note world.GetPlugintimerInfo ("", "my_timer", 1)

return_value:
The specified information about the timer, as described above.
An EMPTY variant, if the timer does not exist.
A NULL variant if the timer name is invalid.
A NULL variant if the InfoType is not a valid type.
A NULL variant if the plugin is not installed.


name: GetPluginTriggerList
prototype: VARIANT GetPluginTriggerList(BSTR PluginID);
summary: Gets the list of triggers in a specified plugin
type_of_object: Method
doc_name: triggers
lua_example: for k, v in pairs (GetPluginTriggerList ("982581e59ab42844527eec80")) do Note (v) end
description:
Returns an array of all the named triggers currently defined for the nominated plugin. You can then use GetPluginTriggerInfo to find out more details about each one.

If you want to find the list of triggers in the current plugin, use "GetTriggerList".

If you are writing a plugin and want to find the "global" MUSHclient trigger list, use an empty plugin ID, eg.

 trList = world.GetPluginTriggerList ("")

vb_example:
dim trList

trList = world.GetPluginTriggerList ("982581e59ab42844527eec80")

If Not IsEmpty (trList) Then
  for each t in trList
    world.note t
  next
End If

java_example:
triggerlist = new VBArray(world.GetPluginTriggerList("982581e59ab42844527eec80")).toArray();

if (triggerlist)  // if not empty
 for (i = 0; i < triggerlist.length; i++)
   world.note(triggerlist [i]);

perl_example:
foreach $item (Win32::OLE::in ($world->GetPluginTriggerList ("982581e59ab42844527eec80")))
 {
 $world->note($item);
 }

return_value:
If there are no triggers (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

If the nominated plugin does not exist, then the return value is NULL. Use "IsNull" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the triggers in the specified plugin. Use "ubound" to find the number of triggers in the list. You can then use "GetPluginTrigger" to find details about each trigger.

see_also:
AddTrigger DeleteTrigger EnableTrigger GetTrigger IsTrigger GetTriggerInfo GetTriggerList GetPluginTriggerInfo

python_example:
triggerlist = world.GetPluginTriggerList("982581e59ab42844527eec80")
if (triggerlist ):
  for t in triggerlist : world.Note (t)


name: GetPluginAliasList
prototype: VARIANT GetPluginAliasList(BSTR PluginID);
summary: Gets the list of aliases in a specified plugin
type_of_object: Method
see_also: AddAlias DeleteAlias EnableAlias GetAlias IsAlias GetAliasInfo GetAliasList GetPluginAliasInfo
doc_name: aliases
lua_example: for k, v in pairs (GetPluginAliasList ("982581e59ab42844527eec80")) do Note (v) end
description:
Returns an array of all the named aliases currently defined for the nominated plugin. You can then use GetPluginAliasInfo to find out more details about each one.

If you want to find the list of aliases in the current plugin, use "GetAliasList".

If you are writing a plugin and want to find the "global" MUSHclient alias list, use an empty plugin ID, eg.

 alList = world.GetPluginAliasList ("")

vb_example:
dim alList

alList = world.GetPluginAliasList ("982581e59ab42844527eec80")

If Not IsEmpty (alList) Then
  for each a in alList
    world.note a
  next
End If

java_example:
aliaslist = new VBArray(world.GetPluginAliasList("982581e59ab42844527eec80")).toArray();

if (aliaslist)  // if not empty
 for (i = 0; i < aliaslist.length; i++)
   world.note(aliaslist [i]);

perl_example:
foreach $item (Win32::OLE::in ($world->GetPluginAliasList ("982581e59ab42844527eec80")))
 {
 $world->note($item);
 }

return_value:
If there are no aliases (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

If the nominated plugin does not exist, then the return value is NULL. Use "IsNull" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the aliases in the specified plugin. Use "ubound" to find the number of aliases in the list. You can then use "GetPluginAliasInfo" to find details about each alias.

python_example:
aliaslist = world.GetPluginAliasList ("982581e59ab42844527eec80")
if (aliaslist):
  for a in aliaslist : world.Note (a)


name: GetPluginTimerList
prototype: VARIANT GetPluginTimerList(BSTR PluginID);
summary: Gets the list of timers in a specified plugin
type_of_object: Method
see_also: AddTimer DeleteTimer EnableTimer GetTimer IsTimer GetTimerInfo GetTimerList GetPluginTimerInfo
doc_name: plugins
lua_example: for k, v in pairs (GetPluginTimerList ("982581e59ab42844527eec80")) do Note (v) end
description:
Returns an array of all the named timers currently defined for the nominated plugin. You can then use GetPluginTimerInfo to find out more details about each one.

If you want to find the list of timers in the current plugin, use "GetTimerList".

If you are writing a plugin and want to find the "global" MUSHclient timer list, use an empty plugin ID, eg.

 tList = world.GetPluginTimerList ("")

vb_example:
dim tList

tList = world.GetPluginTimerList ("982581e59ab42844527eec80")

If Not IsEmpty (tList) Then
  for each t in tList
    world.note t
  next
End If

java_example:
timerlist = new VBArray(world.GetPluginTimerList("982581e59ab42844527eec80")).toArray();

if (timerlist)  // if not empty
 for (i = 0; i < timerlist.length; i++)
   world.note(timerlist [i]);

perl_example:
foreach $item (Win32::OLE::in ($world->GetPluginTimerList ("982581e59ab42844527eec80")))
 {
 $world->note($item);
 }

return_value:
If there are no timers (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

If the nominated plugin does not exist, then the return value is NULL. Use "IsNull" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the timers in the specified plugin. Use "ubound" to find the number of timers in the list. You can then use "GetPluginTimerInfo" to find details about each timer.

python_example:
timerlist = world.GetPluginTimerList("982581e59ab42844527eec80")
if (timerlist):
  for t in timerlist : world.Note (t)


name: GetPluginVariableList
prototype: VARIANT GetPluginVariableList(BSTR PluginID);
summary: Gets the list of variables in a specified plugin
type_of_object: Method
see_also: GetVariable GetVariableList GetPluginVariableList
doc_name: plugins
description:
Returns an array of all the variables currently defined for the nominated plugin. You can then use GetPluginVariable to get the value for each one.

If you want to find the list of variables in the current plugin, use "GetVariableList".

If you are writing a plugin and want to find the "global" MUSHclient variable list, use an empty plugin ID, eg.

 vList = world.GetPluginVariableList ("")

vb_example:
dim varList

varList = world.GetPluginVariableList ("982581e59ab42844527eec80")

If Not IsEmpty (varList) Then

  For Each v In varList 
    world.note v & " = " &  world.GetPluginVariable ("982581e59ab42844527eec80", v)
  Next

End If

java_example:
varList = new VBArray(world.GetPluginVariableList("982581e59ab42844527eec80")).toArray();

if (varList)  // if not empty
 for (i = 0; i < varList.length; i++)
   world.note(varList [i] + " = " + 
         world.GetPluginVariable("982581e59ab42844527eec80", varList [i]));

perl_example:
foreach $item (Win32::OLE::in ($world->GetPluginVariableList ("982581e59ab42844527eec80")))
 {
 ($key, $value) = ($item, $world->GetPluginVariable ("982581e59ab42844527eec80", $item));
 $world->note($key . " = " . $value) if (defined ($key));
 }

return_value:
If there are no variables then the return value is empty. Use "IsEmpty" to test for this possibility.

If the nominated plugin does not exist, then the return value is NULL. Use "IsNull" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the variables in the specified plugin. Use "ubound" to find the number of variables in the list. You can then use "GetPluginVariable" to find details about each variable.

python_example:
variablelist = world.GetPluginVariableList("982581e59ab42844527eec80")
if (variablelist ):
  for v in variablelist : world.Note (v + " = " +
                  world.GetPluginVariable("982581e59ab42844527eec80", v))

lua_example:
-- show all variables and their values

for k, v in pairs (GetPluginVariableList("982581e59ab42844527eec80")) do 
  Note (k, " = ", v) 
end

lua_notes:
Under Lua this function returns a table of all variables and their values, 
keyed by the variable name.

Thus you can directly access variables from the table, like this:

-- show value for variable "victim" in plugin ID "982581e59ab42844527eec80" ...

print (GetPluginVariableList("982581e59ab42844527eec80").victim)


name: Info
prototype: void Info(BSTR Message);
summary: Adds text to the "info" tool bar
vb_example: world.Info "You are now connected"
java_example: world.Info ("You are now connected");
perl_example: $world->Info ("You are now connected");
return_value: Nothing.
type_of_object: Method
see_also: ShowInfoBar InfoFont InfoClear InfoColour InfoBackground SetStatus
python_example: world.Info ("You are now connected")
doc_name: infobar
lua_example: Info ("You are now connected")
description:
This adds the specified text to the info bar.

The bar is not cleared first, use InfoClear if you want to start a fresh lot of text.

If you want to change the colour, font or style of the text, use InfoFont and/or InfoColour before displaying the text.

The info bar may contain mixed colours, fonts and styles. 

The info bar is shared between all worlds. Switching worlds will not change its contents.

lua_notes:
You can supply multiple arguments, which are concatenated together.

eg.

Info ("You see ", themob, " here")


name: LoadPlugin
prototype: long LoadPlugin(BSTR FileName);
summary: Loads a plugin from disk
vb_example: LoadPlugin "c:/mushclient/plugins/plugin_list.xml"
java_example: LoadPlugin ("c:/mushclient/plugins/plugin_list.xml");
perl_example: $world->LoadPlugin ("c:/mushclient/plugins/plugin_list.xml");
type_of_object: Method
see_also: IsPluginInstalled GetPluginList GetPluginInfo ReloadPlugin
python_example: world.LoadPlugin ("c:/mushclient/plugins/plugin_list.xml")
doc_name: plugins
lua_example: LoadPlugin ("c:/mushclient/plugins/plugin_list.xml")
description:
Loads a plugin file from disk. This is intended to let plugins load other plugins if desired. For example, you could make a "scan plugin directory" plugin, that loads all plugins found in a particular directory.

You might use "IsPluginInstalled" to see if a particular plugin is already installed.

If the plugin cannot be loaded an error window will open describing the problem with the plugin (eg. XML parsing error).

However if the problem is simply that the plugin file cannot be found, then no window will open.

You can use ReloadPlugin to reinstall a plugin once it is loaded, if you have changed it.

return_value:
ePluginFileNotFound: Plugin file not found
eProblemsLoadingPlugin: Parsing or other problem in plugin file - see error window
eOK: Loaded OK


name: IsPluginInstalled
prototype: boolean IsPluginInstalled(BSTR PluginID);
summary: Checks to see if a particular plugin is installed
vb_example: world.note world.IsPluginInstalled ("982581e59ab42844527eec80")
java_example: world.note (world.IsPluginInstalled ("982581e59ab42844527eec80"));
perl_example: $world->note ($world->IsPluginInstalled ("982581e59ab42844527eec80"));
return_value: True if the plugin has been installed. False if not installed.
type_of_object: Method
see_also: LoadPlugin CallPlugin PluginSupports EnablePlugin GetPluginInfo
python_example: world.note (world.IsPluginInstalled ("982581e59ab42844527eec80"))
doc_name: plugins
lua_example: Note (IsPluginInstalled ("982581e59ab42844527eec80"))
description:
Use IsPluginInstalled to find if a particular plugin (identified by its unique Plugin ID) has been installed into this session of MUSHclient.


name: SaveState
prototype: long SaveState();
summary: Saves the state of the current plugin
vb_example: world.SaveState
java_example: world.SaveState ();
perl_example: $world->SaveState ();
type_of_object: Method
see_also: GetPluginInfo CallPlugin PluginSupports EnablePlugin
python_example: world.SaveState
doc_name: plugins
lua_example: SaveState ()
description:
This causes the current plugin to save its state (ie. its variables) to its "state" file. You might call this in a timer every couple of minutes to ensure that variables are saved in the event of a program or computer crash.

If a plugin has: 

  save_state="y"

in its plugin configuration (header), then its state is saved automatically as described below.

Plugins automatically save their state when they are closed (ie. when they are uninstalled, or when the world closes), and when the world file is saved. However if the world does not close for days then you may want to arrange for the plugin to save its state more often, particularly if the variables that the plugin is using are valuable.

The plugins by default save their state to a directory called "state" which is a subdirectory of the nominated "world plugins directory". If no such directory exists, then the plugin cannot save its state. The "save state" directory can be found by doing GetInfo (85).

There is a state file for each world/plugin combination.

The file name will look like this:

a282eaabbecd18a56aa07f84-c8efc9f9e1edd118c6f2dbf5-state.xml

This is:

(world ID)-(plugin ID)-state.xml

Each world should have a unique ID, and each plugin should have a unique ID, thus each world's plugin's state should have a unique file name.

Plugins are also forced to save their state when the main world file is saved (ie. world.Save is called, or you save the world file from the File menu).

If the plugin has an OnPluginSaveState function this is called before the state is saved - this lets the plugin serialize its script variables - that is, convert from script internal variables to MUSHclient variables.

If a plugin is not executing (that is, if this is called from outside a plugin execution) then no state can be saved and an error code is returned.

Prior to version 4.56 a plugin could not save its state by calling this function unless save_state was set as "y" in the plugin header.

return_value:
eNotAPlugin: Script is not currently executing inside a plugin.
ePluginCouldNotSaveState: The plugin could not save its state (eg. no "state" directory, disk full, not permitted)
eOK: Plugin saved its state OK.

lua_notes:
See the forum thread http://www.gammon.com.au/forum/?id=4960 for suggestions about how to serialize Lua tables into a variable. This has example OnPluginSaveState functions.


name: GetPluginInfo
prototype: VARIANT GetPluginInfo(BSTR PluginID, short InfoType);
summary: Gets details about a specified plugin
vb_example: world.note world.GetPluginInfo (world.GetPluginID, 8)
java_example: world.note (world.GetPluginInfo (world.GetPluginID, 8));
perl_example: $world->note ($world->GetPluginInfo ($world->GetPluginID, 8));
type_of_object: Method
see_also: GetPluginList GetPluginID GetPluginName IsPluginInstalled EnablePlugin LoadPlugin
python_example: world.note (world.GetPluginInfo (world.GetPluginID, 8))
doc_name: plugins
lua_example: Note (GetPluginInfo (GetPluginID (), 8))
description:
Gets details about the specified plugin, identified by its unique ID.

You can obtain various "types" of information about the plugin by specifying an "InfoType". 

If the InfoType given is out of range, NULL is returned. If the plugin does not exist, NULL is returned. (Use "IsNull" to test for this possibility).

You can obtain one of 25 "types" of information about the plugin by specifying an "InfoType". The possible InfoTypes are:

 1: Name (string)
 2: Author (string)
 3: Description (long description) (string)
 4: Script contents (string)
 5: Script language (ie. vbscript, perlscript, jscript) (string)
 6: Plugin file name (string)
 7: Unique ID (string)
 8: Purpose (short description) (string)
 9: Number of triggers (long)
10: Number of aliases (long)
11: Number of timers (long)
12: Number of variables (long)
13: Date written (date)
14: Date modified (date)
15: Save state flag (boolean)
16: Scripting enabled? (boolean)
17: Enabled? (boolean)
18: Required MUSHclient version (double)
19: Version of plugin (double)
20: Directory that plugin resides in (string)
21: Evaluation order of plugin (long)
22: Date/time plugin installed (date)
23: During a CallPlugin call, the ID of the calling plugin (if any) (string)
24: Time spent on scripting in this plugin (seconds, double)
25: Plugin sequence number (short)

The evaluation order starts at 1, and increases by 1 for each plugin in the list of plugins (disabled or not).

return_value:
The specified information about the plugin, as described above.
A NULL variant if the InfoType is not a valid type.
A NULL variant if the plugin is not installed.


name: CallPlugin
prototype: long CallPlugin(BSTR PluginID, BSTR Routine, BSTR Argument);
summary: Calls a routine in a plugin
vb_example: world.CallPlugin "80cc18937a2aca27079567f0", "LogIt", "Data to be logged"
java_example: world.CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged");
perl_example: $world->CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged");
type_of_object: Method
see_also: PluginSupports GetPluginID GetPluginList GetPluginInfo LoadPlugin IsPluginInstalled BroadcastPlugin
python_example: world.CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged")
doc_name: plugins
lua_example: CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged")
description:
Calls a nominated routine in a nominated plugin, supplying a string argument.

The intention here is to allow plugins to interact with each other, to a certain extent.

For instance, you might write a plugin that logs text to a log file (or miniwindow), and want to share it between other plugins. Hence you might log a message like this:

  world.CallPlugin "80cc18937a2aca27079567f0", "LogIt", "Data to be logged"

The above example would locate plugin with the ID 80cc18937a2aca27079567f0 (if installed) and then call the routine "LogIt" in that plugin, with the argument "Data to be logged". In this example, the LogIt routine would look like this:

function LogIt (sText)
  WriteLog (sText)
end -- function LogIt


You should exercise caution when using this technique. It will be annoying for plugin users if plugins become overly dependent on each other, particularly if they cannot find the one that is required.

Also, be careful you do not set up circular dependencies (eg. A needs B, and B needs A).

You can use "PluginSupports" to see if a particular routine is implemented in a plugin. For example:

if PluginSupports ("80cc18937a2aca27079567f0", "LogIt") ~= error_code.eOK then
  Note "Required 'LogIt' routine is not available"
end -- if


If you want to send a message to all installed plugins you might consider using BroadcastPlugin instead.

New in version 4.55: Lua scripts can call Lua plugins using CallPlugin, but pass multiple arguments (not just a single string). Also they can receive returned data. See below for more details.

return_value:
eNoSuchPlugin: Plugin not installed
ePluginDisabled: Plugin is disabled
eNoSuchRoutine: Specified routine cannot be found in that plugin
eErrorCallingPluginRoutine: Error when calling function (runtime error) OR - the function returned an unsupported data type (Lua only)
eBadParameter: An argument was an invalid type (Lua only)
eOK: Called OK

lua_notes:
Functions can be nested inside tables. So for example you could call function "foo.bar".


New in version 4.55 onwards:

You can pass multiple arguments which must be one of: nil, boolean, number or string.

The called function can return zero or more values which must also be one of the above types.

For example:

rc, a, b, c, d = CallPlugin ("80cc18937a2aca27079567f0", "show_message", "red", "green", "message", 42)

On an error the second value returned ('a' in the example) will be a string indicating the reason for the error.

On an execution error (eErrorCallingPluginRoutine) there will also be a third return value ('b' in the example) which is the error message generated at runtime.

See: 

http://www.gammon.com.au/forum/?id=10453


name: PluginSupports
prototype: long PluginSupports(BSTR PluginID, BSTR Routine);
summary: Checks if a plugin supports a particular routine
type_of_object: Method
see_also: CallPlugin GetPluginID GetPluginList GetPluginInfo LoadPlugin IsPluginInstalled
doc_name: plugins
description:
Checks to see if a specified plugin exists, and supports a specified routine.

For example:

If world.PluginSupports ("80cc18937a2aca27079567f0", "LogIt") <> eOK then
  world.Note "Required 'LogIt' routine is not available"
End If

vb_example:
If world.PluginSupports ("80cc18937a2aca27079567f0", "LogIt") <> eOK then
  world.Note "Required 'LogIt' routine is not available"
End If

java_example:
If (world.PluginSupports ("80cc18937a2aca27079567f0", "LogIt") != eOK)
  {
  world.Note ("Required 'LogIt' routine is not available");
  }

perl_example:
if ($world->PluginSupports ("80cc18937a2aca27079567f0", "LogIt") != eOK)   
 {
 $world->Note ("Required 'LogIt' routine is not available");
 }

return_value:
eNoSuchPlugin: Plugin not installed
eNoSuchRoutine: Specified routine cannot be found in that plugin
eOK: Called OK

python_example:
if world.PluginSupports ("80cc18937a2aca27079567f0", "LogIt") != 0:
  world.Note ("Required 'LogIt' routine is not available")

lua_example:
if PluginSupports ("80cc18937a2aca27079567f0", "LogIt") ~= error_code.eOK then
  Note ("Required 'LogIt' routine is not available")
end


name: EnablePlugin
prototype: long EnablePlugin(BSTR PluginID, BOOL Enabled);
summary: Enables or disables the specified plugin
vb_example: world.EnablePlugin "982581e59ab42844527eec80", vbTrue
java_example: world.EnablePlugin ("982581e59ab42844527eec80", true);
perl_example: $world->EnablePlugin ("982581e59ab42844527eec80", 1);
return_value: eNoSuchPlugin: That plugin ID is not installed eOK: enabled/disabled OK
type_of_object: Method
see_also: GetPluginID GetPluginList GetPluginInfo CallPlugin
python_example: world.EnablePlugin ("982581e59ab42844527eec80", True)
doc_name: plugins
lua_example: EnablePlugin ("982581e59ab42844527eec80", true)
lua_notes: The enabled flag is optional, and defaults to true.
description:
Enables or disables the named plugin. An enabled plugin is "active", otherwise its triggers, timers and aliases are ignored.

You can use GetPluginInfo to see if the plugin is currently enabled.

If the plugin's "enabled" state changes (ie. from enabled to disabled, or disabled to enabled) then the appropriate routine in the plugin is called, if found ...

OnPluginEnable or OnPluginDisable

For example, you might have these routines in your plugin ...

sub OnPluginEnable 
  world.Note world.GetPluginName & " has just been enabled."
end sub

sub OnPluginDisable 
  world.Note world.GetPluginName & " has just been disabled."
end sub


name: GetLoadedValue
prototype: VARIANT GetLoadedValue(BSTR OptionName);
summary: Gets value of a named world option, as loaded from the world file
vb_example: world.note world.GetLoadedValue ("port") world.note world.GetLoadedValue ("player")
java_example: world.note (world.GetLoadedValue ("port")); world.note (world.GetLoadedValue ("player"));
perl_example: $world->note ($world->GetLoadedValue ("port")); $world->note ($world->GetLoadedValue ("player"));
type_of_object: Method
see_also: GetOption GetOptionList SetOption GetDefaultValue GetCurrentValue
python_example: world.note (world.GetLoadedValue ("port")) world.note (world.GetLoadedValue ("player"))
doc_name: options
lua_example: Note (GetLoadedValue ("port")) Note (GetLoadedValue ("player"))
description:
Gets the value of a MUSHclient <world> option, as at the moment after the world was loaded from disk.

You can use GetOptionList, and GetAlphaOptionList, to get a list of the names of all possible options.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

return_value:
The value of the requested option, or a NULL variant if the option does not exist, or is not permitted to be read.


name: GetDefaultValue
prototype: VARIANT GetDefaultValue(BSTR OptionName);
summary: Gets the default value of a named world option
vb_example: world.note world.GetDefaultValue ("port") world.note world.GetDefaultValue("player")
java_example: world.note (world.GetDefaultValue ("port")); world.note (world.GetDefaultValue ("player"));
perl_example: $world->note ($world->GetDefaultValue ("port")); $world->note ($world->GetDefaultValue ("player"));
type_of_object: Method
see_also: GetOption GetOptionList SetOption GetLoadedValue GetCurrentValue
python_example: world.note (world.GetDefaultValue ("port")) world.note (world.GetDefaultValue ("player"))
doc_name: options
lua_example: Note (GetDefaultValue ("port")) Note (GetDefaultValue ("player"))
description:
Gets the default value of a MUSHclient <world> option, as it would be directly after creating a new world.

You can use GetOptionList, and GetAlphaOptionList, to get a list of the names of all possible options.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

return_value:
The value of the requested option, or a NULL variant if the option does not exist, or is not permitted to be read.


name: GetCurrentValue
prototype: VARIANT GetCurrentValue(BSTR OptionName);
summary: Gets the current value of a named world option
vb_example: world.note world.GetCurrentValue ("port") world.note world.GetCurrentValue ("player")
java_example: world.note (world.GetCurrentValue ("port")); world.note (world.GetCurrentValue ("player"));
perl_example: $world->note ($world->GetCurrentValue ("port")); $world->note ($world->GetCurrentValue ("player"));
type_of_object: Method
see_also: GetOption GetOptionList SetOption GetLoadedValue GetDefaultValue
python_example: world.note (world.GetCurrentValue ("port")) world.note (world.GetCurrentValue ("player"))
doc_name: options
lua_example: Note (GetCurrentValue ("port")) Note (GetCurrentValue ("player"))
description:
Gets the current value of a MUSHclient <world> option, that is, the value it currently has.

You can use GetOptionList, and GetAlphaOptionList, to get a list of the names of all possible options.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

return_value:
The value of the requested option, or a NULL variant if the option does not exist, or is not permitted to be read.


name: CreateGUID
prototype: BSTR CreateGUID();
summary: Creates a GUID - Global Unique Identifier
vb_example: world.Note world.CreateGUID
java_example: world.Note (world.CreateGUID ());
perl_example: $world->Note ($world->CreateGUID ());
return_value: A 36-character GUID.
type_of_object: Method
see_also: GetUniqueNumber GetUniqueID
python_example: world.Note (world.CreateGUID )
doc_name: utils
lua_example: Note (CreateGUID ())
description:
This generates a unique GUID (Global Unique Identifier). This is guaranteed to be unique throughout the world, and at any time (ie. completely and utterly unique) provided you have a network card in your PC, as part of the GUID is the MAC address of the network card, which are manufactured to be unique world-wide. If you do not have a network card, there is a small possibility that GUIDs generated by two PCs (both without network cards) might be the same.

The GUID will look like this: 6B29FC40-CA47-1067-B31D-00DD010662DA

The purpose of this is to give you a way of having a unique identifier (eg. for a variable). If you were to use it for that purpose you would have to add a letter to the front, as variables must start with a letter, not a number, and change hyphens to underscores. eg.

   dim uniqueid
    uniqueid = "X" & world.replace (world.createguid, "-", "_", true)

These numbers may seem cumbersome, but at least if you use them you are guaranteed of a unique identifier. The last 12 characters are the hardware MAC address of your network card (in the example above, "00DD010662DA"), so if you wanted an identifier that was unique for your PC, but not necessarily around the world, you could trim off the last 13 characters (eg. "6B29FC40-CA47-1067-B31D" would be unique on this PC). eg.

   dim uniqueid
    uniqueid = "X" & left (world.replace (world.createguid, "-", "_", true), 23)

  (eg. X989B3DD0_7125_11D6_BBB7)

To save a bit more space you could even get rid of the hyphens altogether. eg.

   dim uniqueid
    uniqueid = "X" & left (world.replace (world.createguid, "-", "", true), 20)

   (eg. X989B3DCD712511D6BBB7)

In this case the identifier is only 21 characters (including the "X") and will be unique on this PC.

Contrast this to "GetUniqueNumber" which only returns a unique number for this session of MUSHclient. Thus, the numbers (from "GetUniqueNumber") will not be unique over multiple sessions.

See also the new script function world.GetUniqueID.

Also, using random number generation for unique identifiers has a chance of returning the same number, depending on a) the seed given to the generator; and b) the way the generator must eventually recyle and regenerate the same sequence.


name: ColourTell
prototype: void ColourTell(BSTR TextColour, BSTR BackgroundColour, BSTR Text);
summary: Sends a message to the output window in specified colours - not terminated by a newline
vb_example: world.ColourTell "red", "blue", "Hello " world.ColourTell "white", "green", "there"
java_example: world.ColourTell ("red", "blue", "Hello "); world.ColourTell ("white", "green", "there");
perl_example: $world->ColourTell ("red", "blue", "Hello "); $world->ColourTell ("white", "green", "there");
return_value: Nothing.
type_of_object: Method
python_example: world.ColourTell ("red", "blue", "Hello ") world.ColourTell ("white", "green", "there")
doc_name: colours
lua_example: ColourTell ("red", "blue", "Hello there ", "white", "green", "everyone")
description:
This lets you do a "tell" in a specified colour. It is not transmitted to the world. It is useful for making comments to yourself. The note is NOT automatically terminated by a newline, so you can use ColourTell multiple times on one line (eg. to change colour in mid-line). The note colour is saved and restored, so that the world note colour is unchanged after using this function (however the new colour is used for the tell itself).

eg.

  world.ColourTell "red", "blue", "Hello there"

The colour is specified by colour name - you can use the MUSHclient colour picker to see all possible colour names, or type: world.Debug "colours". You can also specify colours in HTML format, like this:

  world.ColourTell "#FAEBD7", "#FFB6C1", "Hi there"

If you leave a colour name blank, it is unchanged. Thus you could do this to get red text on the existing background:

  world.ColourTell "red", "", "Hello there"
  

A new line will automatically be started by output from the MUD, or a command that you type being echoed to the output window. You can send a new line yourself by sending vbCRLF (in Visual Basic) or n in Jscript or Perlscript.


To make changes to the text style (eg. bold, underline) see NoteStyle.

see_also:
Send NoteColour NoteColourFore NoteColourBack Note NoteColourRGB NoteColourName ColourNote Tell NoteStyle

lua_notes:
You can supply any number of arguments, however they must be in groups of three:

* foreground colour
* background colour
* text

The example above shows how you might send two lots of text coloured different ways.


name: ColourNote
prototype: void ColourNote(BSTR TextColour, BSTR BackgroundColour, BSTR Text);
summary: Sends a message to the output window in specified colours
vb_example: world.ColourNote "red", "blue", "Hello there"
java_example: world.ColourNote ("red", "blue", "Hello there");
perl_example: $world->ColourNote ("red", "blue", "Hello there");
return_value: Nothing.
type_of_object: Method
python_example: world.ColourNote ("red", "blue", "Hello there")
doc_name: colours
lua_example: ColourNote ("red", "blue", "Hello there ", "white", "green", "everyone")
description:
This lets you do a "note" in a specified colour. It is not transmitted to the world. It is useful for making comments to yourself. The note colour is saved and restored, so that the world note colour is unchanged after using this function (however the new colour is used for the tell itself).

eg.

  world.ColourNote "red", "blue", "Hello there"

The colour is specified by colour name - you can use the MUSHclient colour picker to see all possible colour names, or type: world.Debug "colours". You can also specify colours in HTML format, like this:

  world.ColourNote "#FAEBD7", "#FFB6C1", "Hi there"

If you leave a colour name blank, it is unchanged. Thus you could do this to get red text on the existing background:

  world.ColourNote "red", "", "Hello there"
  

A new line will automatically be started by output from the MUD, or a command that you type being echoed to the output window. You can send a new line yourself by sending vbCRLF (in Visual Basic) or n in Jscript or Perlscript.


To make changes to the text style (eg. bold, underline) see NoteStyle.

see_also:
Send NoteColour NoteColourFore NoteColourBack NoteColourRGB NoteColourName ColourTell Note Tell AnsiNote ChatNote NoteStyle

lua_notes:
You can supply any number of arguments, however they must be in groups of three:

* foreground colour
* background colour
* text

The example above shows how you might send two lots of text coloured different ways.

The newline is only appended to the end of the note, not between individual items.


name: Hash
prototype: BSTR Hash(BSTR Text);
summary: Produces a hash (checksum) of a specified piece of text
vb_example: world.note world.hash ("This Mud is running on the Dawn Codebase")
java_example: world.note (world.hash ("This Mud is running on the Dawn Codebase"));
perl_example: $world->note ($world->hash ("This Mud is running on the Dawn Codebase"));
return_value: A 40-character hexadecimal string which is the hash of the supplied text.
type_of_object: Method
see_also: GetUniqueID
python_example: world.note (world.hash ("This Mud is running on the Dawn Codebase"))
doc_name: utils
lua_example: Note (Hash("This Mud is running on the Dawn Codebase"))
description:
This produces a 160-bit hash of the supplied text, returned as a 40-character hex string (40 X 4 bits = 160 bits). eg.

  world.note world.hash ("This Mud is running on the Dawn Codebase")

  c6a948fc8e81baa172a15aa534409b7654861a33

You might use this to store a hash of a long string (eg. a script file) to see if it has changed rather than storing the text itself.

There is no limit to the length of the string that can be hashed.

Because of the way strings are stored this will not work with strings which have nulls in them (hex 00), however see below for a work-around for Lua.

lua_notes:
In MUSHclient version 3.57 onwards you can also use 

hashed_string = utils.hash (s)

This works the same as described above, however it will correctly handle strings with the null (hex 00) character in them.


name: LogSend
prototype: long LogSend(BSTR Message);
summary: Sends a message to the MUD and logs it
vb_example: world.logsend "go north"
java_example: world.LogSend("go north");
perl_example: $world->LogSend("go north");
type_of_object: Method
see_also: Note Send FlushLog WriteLog
python_example: world.LogSend("go north")
doc_name: logging
lua_example: LogSend [[ go north eat food drink water ]]
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
This sends the specified text to the world. It is like typing it into the command window.

The message text is also logged to the current log file, if one is open.

The data in the log file may not appear immediately if you view it in another application. To force the data to disk use the FlushLog function.

return_value:
eWorldClosed : The world is closed
eItemInUse : Cannot be called from within OnPluginSent script callback
eOK: Sent OK


name: AddMapperComment
prototype: long AddMapperComment(BSTR Comment);
summary: Adds a comment to the auto-map sequence
vb_example: world.AddMapperComment "Main Square"
java_example: world.AddMapperComment ("Main Square");
perl_example: $world->AddMapperComment("Main Square");
return_value: eBadMapItem: comment may not contain "{", "}", "(", ")", "/" or "\" eOK: added OK
type_of_object: Method
python_example: world.AddMapperComment ("Main Square")
doc_name: mapper
lua_example: AddMapperComment ("Main Square")
description:
Adds a comment to the auto-map sequence. This lets you put comments into the map sequence (eg. the name of the current room).

Note, mapping does *not* need to be enabled to use this method. This lets you use triggers or aliases to build up a map direction, rather than MUSHclient's automatic mapping.

see_also:
Mapping RemoveMapReverses GetMappingCount GetMappingItem GetMappingString DeleteLastMapItem DeleteAllMapItems AddToMapper


name: SendPush
prototype: long SendPush(BSTR Message);
summary: Sends a message to the MUD and saves it in the command history buffer
vb_example: world.SendPush "go north"
java_example: world.SendPush("go north");
perl_example: $world->SendPush("go north");
type_of_object: Method
see_also: Note LogSend Send SendSpecial
python_example: world.SendPush("go north")
doc_name: send
lua_example: SendPush ("go north")
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
This sends the specified text to the world. It is like typing it into the command window.

A newline character is appended to the text you supply, as MUD commands normally are terminated with a newline.

The text may include imbedded newlines. 

If the text has a trailing newline it is removed. In other words, text with a trailing newline will not end up with two newlines when sent to the MUD.

The command is saved in the command history buffer (use Send if you do NOT want to save it).

return_value:
eWorldClosed : The world is closed
eItemInUse : Cannot be called from within OnPluginSent script callback
eOK: Sent OK


name: EnableGroup
prototype: long EnableGroup(BSTR GroupName, BOOL Enabled);
summary: Enables/disables a group of triggers, aliases and timers
return_value: A count of the number of items in that group.
type_of_object: Method
doc_name: group
lua_notes: The enabled flag is optional, and defaults to true.
description:
Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To enable an entire group of triggers, aliases and timers do this: 

  world.EnableGroup "groupname", 1

To disable the entire group:

  world.EnableGroup "groupname", 0

For debugging purposes the function returns a count of the number of members in the group (not the number enabled, as some may already be enabled). eg.

  dim mycount
  mycount = world.EnableGroup ("groupname", 1)

If you are using plugins only the members of the current plugin (if any) are affected. If the call is made outside a plugin only the members of the group that are not in a plugin are affected.

vb_example:
world.EnableGroup "groupname", 1  ' enable the group
world.EnableGroup "groupname", 0  ' disable the group

java_example:
world.EnableGroup ("groupname", 1);  // enable the group
world.EnableGroup ("groupname", 0);  // disable the group

perl_example:
$world->EnableGroup ("groupname", 1);  # enable the group
$world->EnableGroup ("groupname", 0);  # disable the group

see_also:
EnableTriggerGroup EnableAliasGroup EnableTimerGroup GetAliasInfo GetTriggerInfo GetTimerInfo DeleteGroup DeleteTriggerGroup DeleteTImerGroup DeleteAliasGroup

python_example:
world.EnableGroup ("groupname", 1)  # enable the group
world.EnableGroup ("groupname", 0)  # disable the group

lua_example:
EnableGroup ("groupname", true)  -- enable the group
EnableGroup ("groupname", false)  -- disable the group


name: EnableTriggerGroup
prototype: long EnableTriggerGroup(BSTR GroupName, BOOL Enabled);
summary: Enables/disables a group of triggers
return_value: A count of the number of items in that group.
type_of_object: Method
see_also: EnableGroup EnableAliasGroup EnableTimerGroup GetTriggerInfo DeleteGroup DeleteTriggerGroup
doc_name: triggers
lua_notes: The enabled flag is optional, and defaults to true.
description:
Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To enable an entire group of triggers do this: 

  world.EnableTriggerGroup "groupname", 1

To disable the entire group:

  world.EnableTriggerGroup "groupname", 0

For debugging purposes the function returns a count of the number of members in the group (not the number enabled, as some may already be enabled). eg.

  dim mycount
  mycount = world.EnableTriggerGroup ("groupname", 1)

If you are using plugins only the members of the current plugin (if any) are affected. If the call is made outside a plugin only the members of the group that are not in a plugin are affected.

vb_example:
world.EnableTriggerGroup "groupname", 1  ' enable the group
world.EnableTriggerGroup "groupname", 0  ' disable the group

java_example:
world.EnableTriggerGroup ("groupname", 1);  // enable the group
world.EnableTriggerGroup ("groupname", 0);  // disable the group

perl_example:
$world->EnableTriggerGroup ("groupname", 1);  # enable the group
$world->EnableTriggerGroup ("groupname", 0);  # disable the group

python_example:
world.EnableTriggerGroup ("groupname", 1)  # enable the group
world.EnableTriggerGroup ("groupname", 0)  # disable the group

lua_example:
EnableTriggerGroup ("groupname", true)  -- enable the group
EnableTriggerGroup ("groupname", false)  -- disable the group


name: EnableAliasGroup
prototype: long EnableAliasGroup(BSTR GroupName, BOOL Enabled);
summary: Enables/disables a group of aliases
return_value: A count of the number of items in that group.
type_of_object: Method
see_also: EnableGroup EnableTriggerGroup EnableTimerGroup GetAliasInfo DeleteGroup DeleteAliasGroup
doc_name: aliases
lua_notes: The enabled flag is optional, and defaults to true.
description:
Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To enable an entire group of aliases do this: 

  world.EnableAliasGroup "groupname", 1

To disable the entire group:

  world.EnableAliasGroup "groupname", 0

For debugging purposes the function returns a count of the number of members in the group (not the number enabled, as some may already be enabled). eg.

  dim mycount
  mycount = world.EnableAliasGroup ("groupname", 1)

If you are using plugins only the members of the current plugin (if any) are affected. If the call is made outside a plugin only the members of the group that are not in a plugin are affected.

vb_example:
world.EnableAliasGroup "groupname", 1  ' enable the group
world.EnableAliasGroup "groupname", 0  ' disable the group

java_example:
world.EnableAliasGroup ("groupname", 1);  // enable the group
world.EnableAliasGroup ("groupname", 0);  // disable the group

perl_example:
$world->EnableAliasGroup ("groupname", 1);  # enable the group
$world->EnableAliasGroup ("groupname", 0);  # disable the group

python_example:
world.EnableAliasGroup ("groupname", 1)  # enable the group
world.EnableAliasGroup ("groupname", 0)  # disable the group

lua_example:
EnableAliasGroup ("groupname", true)  -- enable the group
EnableAliasGroup ("groupname", false)  -- disable the group


name: InfoFont
prototype: void InfoFont(BSTR FontName, short Size, short Style);
summary: Changes the font, font size and style for text on the info bar
vb_example: world.InfoFont "FixedSys", 12, 5 world.Info "You are now connected"
java_example: world.InfoFont ("FixedSys", 12, 5); world.Info ("You are now connected");
perl_example: $world->InfoFont ("FixedSys", 12, 5); $world->Info ("You are now connected");
return_value: Nothing.
type_of_object: Method
see_also: ShowInfoBar Info InfoClear InfoColour InfoBackground SetStatus
python_example: world.InfoFont ("FixedSys", 12, 5) world.Info ("You are now connected")
doc_name: infobar
lua_example: InfoFont ("FixedSys", 12, 5) Info ("You are now connected")
description:
Changes the font, font size, and style of the next piece of text to be displayed on the info bar.

If the font name is empty, then the font is unchanged.

If the font size is zero, then the font size is unchanged. The font size is in points.

The style should be a combination of the numbers below (zero is just plain text). For instance, bold and italic would be 3.

Style bits:

    1 = bold
    2 = italic
    4 = underline
    8 = strikeout

eg. To display the next text in 12 point, FixedSys, bold, underline font:

world.InfoFont "FixedSys", 12, 5


name: EnableTimerGroup
prototype: long EnableTimerGroup(BSTR GroupName, BOOL Enabled);
summary: Enables/disables a group of timers
return_value: A count of the number of items in that group.
type_of_object: Method
see_also: EnableGroup EnableTriggerGroup EnableAliasGroup GetTimerInfo DeleteGroup DeleteTimerGroup
doc_name: timers
lua_notes: The enabled flag is optional, and defaults to true.
description:
Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To enable an entire group of timers do this: 

  world.EnableTimerGroup "groupname", 1

To disable the entire group:

  world.EnableTimerGroup "groupname", 0

For debugging purposes the function returns a count of the number of members in the group (not the number enabled, as some may already be enabled). eg.

  dim mycount
  mycount = world.EnableTimerGroup ("groupname", 1)

If you are using plugins only the members of the current plugin (if any) are affected. If the call is made outside a plugin only the members of the group that are not in a plugin are affected.

vb_example:
world.EnableTimerGroup "groupname", 1  ' enable the group
world.EnableTimerGroup "groupname", 0  ' disable the group

java_example:
world.EnableTimerGroup ("groupname", 1);  // enable the group
world.EnableTimerGroup ("groupname", 0);  // disable the group

perl_example:
$world->EnableTimerGroup ("groupname", 1);  # enable the group
$world->EnableTimerGroup ("groupname", 0);  # disable the group

python_example:
world.EnableTimerGroup ("groupname", 1)  # enable the group
world.EnableTimerGroup ("groupname", 0)  # disable the group

lua_example:
EnableTimerGroup ("groupname", true)  -- enable the group
EnableTimerGroup ("groupname", false)  -- disable the group


name: DeleteTriggerGroup
prototype: long DeleteTriggerGroup(BSTR GroupName);
summary: Deletes a group of triggers
vb_example: world.DeleteTriggerGroup "groupname"
java_example: world.DeleteTriggerGroup ("groupname");
perl_example: $world->DeleteTriggerGroup ("groupname");
return_value: A count of the number of items deleted.
type_of_object: Method
python_example: world.DeleteTriggerGroup ("groupname")
doc_name: triggers
lua_example: DeleteTriggerGroup ("groupname")
description:
Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To delete an entire group of triggers do this: 

  world.DeleteTriggerGroup "groupname"

For debugging purposes the function returns a count of the number of members deleted. eg.

  dim mycount
  mycount = world.DeleteTriggerGroup ("groupname")

If you are using plugins only the members of the current plugin (if any) are deleted. If the call is made outside a plugin only the members of the group that are not in a plugin are deleted.

WARNING - if the trigger is executing a script it cannot be deleted. For example, a trigger cannot delete itself.

If you need to delete a trigger from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableTriggerGroup to disable it first.

Since DeleteTriggerGroup deletes multiple triggers, any found to be "in use" (that is, executing a script) will not be deleted.

see_also:
DeleteTrigger EnableGroup EnableTriggerGroup EnableAliasGroup EnableTimerGroup GetAliasInfo GetTriggerInfo GetTimerInfo DeleteGroup DeleteAliasGroup DeleteTimerGroup DoAfterSpecial


name: DeleteAliasGroup
prototype: long DeleteAliasGroup(BSTR GroupName);
summary: Deletes a group of aliases
vb_example: world.DeleteAliasGroup "groupname"
java_example: world.DeleteAliasGroup ("groupname");
perl_example: $world->DeleteAliasGroup ("groupname");
return_value: A count of the number of items deleted.
type_of_object: Method
python_example: world.DeleteAliasGroup ("groupname")
doc_name: aliases
lua_example: DeleteAliasGroup ("groupname")
description:
Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To delete an entire group of aliases do this: 

  world.DeleteAliasGroup "groupname"

For debugging purposes the function returns a count of the number of members deleted. eg.

  dim mycount
  mycount = world.DeleteAliasGroup ("groupname")

If you are using plugins only the members of the current plugin (if any) are deleted. If the call is made outside a plugin only the members of the group that are not in a plugin are deleted.

WARNING - if the alias is executing a script it cannot be deleted. For example, an alias cannot delete itself.

If you need to delete an alias from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableAliasGroup to disable it first.

Since DeleteAliasGroup deletes multiple aliases, any found to be "in use" (that is, executing a script) will not be deleted.

see_also:
DeleteAlias EnableGroup EnableTriggerGroup EnableAliasGroup EnableTimerGroup GetAliasInfo GetTriggerInfo GetTimerInfo DeleteGroup DeleteTriggerGroup DeleteTimerGroup DoAfterSpecial


name: DeleteTimerGroup
prototype: long DeleteTimerGroup(BSTR GroupName);
summary: Deletes a group of timers
vb_example: world.DeleteTimerGroup "groupname"
java_example: world.DeleteTimerGroup ("groupname");
perl_example: $world->DeleteTimerGroup ("groupname");
return_value: A count of the number of items deleted.
type_of_object: Method
python_example: world.DeleteTimerGroup ("groupname")
doc_name: timers
lua_example: DeleteTimerGroup ("groupname")
description:
Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To delete an entire group of timers do this: 

  world.DeleteTimerGroup "groupname"

For debugging purposes the function returns a count of the number of members deleted. eg.

  dim mycount
  mycount = world.DeleteTimerGroup ("groupname")

If you are using plugins only the members of the current plugin (if any) are deleted. If the call is made outside a plugin only the members of the group that are not in a plugin are deleted.

WARNING - if the timer is executing a script it cannot be deleted. For example, a timer cannot delete itself.

If you need to delete a timer from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableTimerGroup to disable it first.

Since DeleteTimerGroup deletes multiple timers, any found to be "in use" (that is, executing a script) will not be deleted.

see_also:
DeleteTimer EnableGroup EnableTriggerGroup EnableAliasGroup EnableTimerGroup GetAliasInfo GetTriggerInfo GetTimerInfo DeleteGroup DeleteAliasGroup DeleteTriggerGroup


name: InfoClear
prototype: void InfoClear();
summary: Clears all text from the info bar
vb_example: world.InfoClear
java_example: world.InfoClear ();
perl_example: $world->InfoClear ();
return_value: Nothing.
type_of_object: Method
see_also: ShowInfoBar Info InfoFont InfoColour InfoBackground SetStatus
python_example: world.InfoClear
doc_name: infobar
lua_example: InfoClear ()
description:
Clears the info bar, ready to start adding new text to it.

The font and colour are restored to the defaults as well.


name: InfoColour
prototype: void InfoColour(BSTR Name);
summary: Sets the colour of the foreground (text color) for the info bar
vb_example: world.InfoColour "red"
java_example: world.InfoColour ("red");
perl_example: $world->InfoColour ("red");
return_value: Nothing.
type_of_object: Method
see_also: ShowInfoBar Info InfoFont InfoClear InfoBackground SetStatus
python_example: world.InfoColour ("red")
doc_name: infobar
lua_example: InfoColour ("red")
description:
Sets the text colour for subsequent text written to the info bar with world.Info.

The colours can either be named (eg. "red", "blue", "green", "brown") or supplied as HTML colour codes (eg. "#010203"). For HTML colours, the leading "#" is required.

The list of colour names recognised can be found by using MUSHclient's "colour picker" (Ctrl+Alt+P), or by using the function:

world.Debug "colours"


name: InfoBackground
prototype: void InfoBackground(BSTR Name);
summary: Sets the background colour for the info bar
vb_example: world.InfoBackground "red"
java_example: world.InfoBackground ("red");
perl_example: $world->InfoBackground ("red");
return_value: Nothing.
type_of_object: Method
see_also: ShowInfoBar Info InfoFont InfoClear InfoColour SetStatus
python_example: world.InfoBackground ("red")
doc_name: infobar
lua_example: InfoBackground ("red")
description:
Sets the backkground colour for the info bar. Because of the way the info bar is implemented (as a RichEdit control) the entire background colour is changed. You cannot change the background for individual parts of the bar.

The colours can either be named (eg. "red", "blue", "green", "brown") or supplied as HTML colour codes (eg. "#010203"). For HTML colours, the leading "#" is required.

The list of colour names recognised can be found by using MUSHclient's "colour picker" (Ctrl+Alt+P), or by using the function:

world.Debug "colours"


name: GetTriggerOption
prototype: VARIANT GetTriggerOption(BSTR TriggerName, BSTR OptionName);
summary: Gets the value of a named trigger option
vb_example: Note world.GetTriggerOption ("mytrigger", "match")
java_example: Note (world.GetTriggerOption ("mytrigger", "match"));
perl_example: $world->Note ($world->GetTriggerOption ("mytrigger", "match"));
return_value: As described above.
type_of_object: Method
see_also: AddTrigger AddTriggerEx GetTriggerInfo SetTriggerOption GetPluginTriggerOption
python_example: Note (world.GetTriggerOption ("mytrigger", "match"))
doc_name: triggers
lua_example: Note (GetTriggerOption ("mytrigger", "match"))
lua_notes: Lua returns nil where applicable instead of an "empty variant" or "null variant".
description:
Gets the current value of a trigger option.

You must specify the name of an existing trigger, and a trigger option from the list below. These are the same names as used in the XML world files for trigger options.

Note that you can neither get or set the "name" field. It is listed below for completeness in viewing triggers copied to the clipboard or in world files and plugins. You already know the name when getting the trigger option (it is TriggerName), and this function is provided to modify existing triggers, not rename them. To change the name of a trigger use ExportXML, modify the XML, and then ImportXML.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named trigger does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

For a detailed description about the meanings of the fields, see AddTrigger.

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

To find options for other plugins, use GetPluginTriggerOption.

The various option names are:

"clipboard_arg":             0 - 10 - which wildcard to copy to the clipboard
"colour_change_type":        0=both, 1=foreground, 2=background
"custom_colour":             0=no change, 1 - 16, 17=other
"enabled":                   y/n - trigger is enabled
"expand_variables":          y/n - expand variables (like @target)
"group":                     (string - group name)
"ignore_case":               y/n - caseless matching
"inverse":                   y/n - only match if inverse, however see match_inverse
"italic":                    y/n - only match if italic, however see match_italic
"keep_evaluating":           y/n - evaluate next trigger in sequence
"lines_to_match":            0 - 200 - how many lines to match for multi-line triggers
"lowercase_wildcard":        y/n - make matching wildcards lower-case
"match":                     (string - what to match)
"match_style":      (see below) - what style and colour combination to match on
"multi_line":                y/n - multi-line trigger
"name":                      (string - name/label of trigger)
"new_style":       (style(s) to change to: (bold (1) / underline (2) / italic (4) ) )
"omit_from_log":             y/n - omit matching line from log file
"omit_from_output":          y/n - omit matching line from output window
"one_shot":                  y/n - trigger is deleted after firing
"other_back_colour":         (string - name of colour to change to)
"other_text_colour":         (string - name of colour to change to)
"regexp":                    y/n - regular expression
"repeat":                    y/n - repeatedly evaluate on same line
"script":                    (string - name of function to call)
"send":                      (multi-line string - what to send)
"send_to":                   0 - 14 - "send to" location (see below)
"sequence":                  0 - 10000 - sequence in which to check - lower first
"sound":                     (string - sound file name to play)
"sound_if_inactive":         y/n - play sound even if world inactive
"user":                      -2147483647 to 2147483647 - user-defined number
"variable":                  (string - name of variable to send to)

Options that match on colour, bold, inverse or underline are tested against the first matching character.

Boolean options (shown as y/n) are returned as 0 for false (n) or 1 for true (y).

Send-to locations

"0"    - send to MUD                  
"1"    - put in command window        
"2"    - display in output window     
"3"    - put in status line           
"4"    - new notepad                  
"5"    - append to notepad            
"6"    - put in log file              
"7"    - replace notepad              
"8"    - queue it                     
"9"    - set a variable               
"10"    - re-parse as command          
"11"    - send to MUD as speedwalk     
"12"    - send to script engine        
"13"    - send without queuing
"14"    - send to script engine - after omitting from output



Trigger match_style field will be as follows (in hex nibbles):

  TBFS    

  T = what style to test
  B = background colour
  F = foreground colour
  S = what style bits are wanted

Style bits:

NORMAL     0x0000   // normal text
HILITE     0x0001   // bold
UNDERLINE  0x0002   // underline
BLINK      0x0004   // italic (sent to client as blink)
INVERSE    0x0008   // need to invert it


MATCH_TEXT      0x0080  // match on text colour?
MATCH_BACK      0x0800  // match on background colour?
MATCH_HILITE    0x1000  // match on bold bit?
MATCH_UNDERLINE 0x2000  // match on underline?
MATCH_BLINK     0x4000  // match on blink?
MATCH_INVERSE   0x8000  // match on inverse?

Colours:

BLACK = 0
RED = 1
GREEN = 2 
YELLOW = 3 
BLUE = 4 
MAGENTA = 5 
CYAN = 6 
WHITE = 7


See the forum posting at http://www.gammon.com.au/forum/?id=4873 for more details about match_style.


name: SetTriggerOption
prototype: long SetTriggerOption(BSTR TriggerName, BSTR OptionName, BSTR Value);
summary: Sets the value of a named trigger option
vb_example: world.SetTriggerOption "mytrigger", "match", "north"
java_example: world.SetTriggerOption ("mytrigger", "match", "north");
perl_example: $world->SetTriggerOption ("mytrigger", "match", "north");
type_of_object: Method
see_also: AddTrigger GetTriggerInfo GetTriggerOption
python_example: world.SetTriggerOption ("mytrigger", "match", "north")
doc_name: triggers
lua_example: SetTriggerOption ("mytrigger", "match", "north")
description:
Sets the current value of a trigger option.

You must specify the name of an existing trigger, and a trigger option from the list given for GetTriggerOption. These are the same names as used in the XML world files for trigger options.

Note that you can neither get or set the "name" field. It is listed below for completeness in viewing triggers copied to the clipboard or in world files and plugins. You already know the name when getting the trigger option (it is TriggerName), and this function is provided to modify existing triggers, not rename them. To change the name of a trigger use ExportXML, modify the XML, and then ImportXML.

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

For numeric options (such as "sequence") the supplied string will be converted to a number. It is an error if the string does not consist of digits (0 to 9). For the "user" option an optional leading sign is accepted.

For boolean options (such as "enabled") the supplied string may be:

"y", "Y", or "1" for true
"n", "N", or "0" for false

Also if you are using Lua you can supply simply true or false.

The various option names are:

"clipboard_arg":             0 - 10 - which wildcard to copy to the clipboard
"colour_change_type":        0=both, 1=foreground, 2=background
"custom_colour":             0=no change, 1 - 16, 17=other
"enabled":                   y/n - trigger is enabled
"expand_variables":          y/n - expand variables (like @target)
"group":                     (string - group name)
"ignore_case":               y/n - caseless matching
"inverse":                   y/n - only match if inverse, however see match_inverse
"italic":                    y/n - only match if italic, however see match_italic
"keep_evaluating":           y/n - evaluate next trigger in sequence
"lines_to_match":            0 - 200 - how many lines to match for multi-line triggers
"lowercase_wildcard":        y/n - make matching wildcards lower-case
"match":                     (string - what to match)
"match_style":      (see below) - what style and colour combination to match on
"multi_line":                y/n - multi-line trigger
"name":                      (string - name/label of trigger)
"new_style":       (style(s) to change to: (bold (1) / underline (2) / italic (4) ) )
"omit_from_log":             y/n - omit matching line from log file
"omit_from_output":          y/n - omit matching line from output window
"one_shot":                  y/n - trigger is deleted after firing
"other_back_colour":         (string - name of colour to change to)
"other_text_colour":         (string - name of colour to change to)
"regexp":                    y/n - regular expression
"repeat":                    y/n - repeatedly evaluate on same line
"script":                    (string - name of function to call)
"send":                      (multi-line string - what to send)
"send_to":                   0 - 14 - "send to" location (see below)
"sequence":                  0 - 10000 - sequence in which to check - lower first
"sound":                     (string - sound file name to play)
"sound_if_inactive":         y/n - play sound even if world inactive
"user":                      -2147483647 to 2147483647 - user-defined number
"variable":                  (string - name of variable to send to)


Options that match on colour, bold, inverse or underline are tested against the first matching character.


Send-to locations

"0"    - send to MUD                  
"1"    - put in command window        
"2"    - display in output window     
"3"    - put in status line           
"4"    - new notepad                  
"5"    - append to notepad            
"6"    - put in log file              
"7"    - replace notepad              
"8"    - queue it                     
"9"    - set a variable               
"10"    - re-parse as command          
"11"    - send to MUD as speedwalk     
"12"    - send to script engine        
"13"    - send without queuing
"14"    - send to script engine - after omitting from output   


Trigger match_style field will be as follows (in hex nibbles):

TBFS 

T = what style to test
B = background colour
F = foreground colour
S = what style bits are wanted

Style bits:

NORMAL 0x0000 // normal text
HILITE 0x0001 // bold
UNDERLINE 0x0002 // underline
BLINK 0x0004 // italic (sent to client as blink)
INVERSE 0x0008 // need to invert it


MATCH_TEXT 0x0080 // match on text colour?
MATCH_BACK 0x0800 // match on background colour?
MATCH_HILITE 0x1000 // match on bold bit?
MATCH_UNDERLINE 0x2000 // match on underline?
MATCH_BLINK 0x4000 // match on blink?
MATCH_INVERSE 0x8000 // match on inverse?

Colours:

BLACK = 0
RED = 1
GREEN = 2 
YELLOW = 3 
BLUE = 4 
MAGENTA = 5 
CYAN = 6 
WHITE = 7


See the forum posting at http://www.gammon.com.au/forum/?id=4873 for more details about match_style.

An easier way of settting trigger options, particularly ones relating to matching style and colours, could be to use ImportXML.

See the forum posting at http://www.gammon.com.au/forum/?id=7123 for more details about ImportXML, and the "addxml" module supplied for Lua scripting.

return_value:
eInvalidObjectLabel: The trigger name is not valid
eTriggerCannotBeEmpty: The "match_text" cannot be empty
eScriptNameNotLocated: The script name cannot be located in the script file
eBadRegularExpression: The regular expression could not be evaluated
ePluginCannotSetOption: The option is marked as non-settable (in a plugin or not)
eOK: set OK

lua_notes:
The "send_to" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0
sendto.command = 1
sendto.output = 2
sendto.status = 3
sendto.notepad = 4
sendto.notepadappend = 5
sendto.logfile = 6
sendto.notepadreplace = 7
sendto.commandqueue = 8
sendto.variable = 9
sendto.execute = 10
sendto.speedwalk = 11
sendto.script = 12
sendto.immediate = 13
sendto.scriptafteromit = 14


You can use true, false or nil for boolean options.


name: GetAliasOption
prototype: VARIANT GetAliasOption(BSTR AliasName, BSTR OptionName);
summary: Gets the value of a named alias option
vb_example: Note GetAliasOption ("myalias", "match")
java_example: Note (GetAliasOption ("myalias", "match"));
perl_example: $world->Note ($world->GetAliasOption ("myalias", "match"));
return_value: As described above.
type_of_object: Method
see_also: AddAlias GetAliasInfo SetAliasOption GetPluginAliasOption
python_example: world.Note (world.GetAliasOption ("myalias", "match"))
doc_name: aliases
lua_example: Note (GetAliasOption ("myalias", "match"))
description:
Gets the current value of an alias option.

You must specify the name of an existing alias, and an alias option from the list below. These are the same names as used in the XML world files for alias options.

Note that you can neither get or set the "name" field. It is listed below for completeness in viewing aliases copied to the clipboard or in world files and plugins. You already know the name when getting the alias option (it is AliasName), and this function is provided to modify existing aliases, not rename them. To change the name of an alias use ExportXML, modify the XML, and then ImportXML.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named alias does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

For a detailed description about the meanings of the fields, see AddAlias.

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

To find options for other plugins use GetPluginAliasOption.

The various option names are:

"echo_alias":               y/n - echo alias itself to output window
"enabled":                  y/n - alias is enabled
"expand_variables":         y/n - expand variables (like @target)
"group":                    (string - group name)
"ignore_case":              y/n - caseless matching
"keep_evaluating":          y/n - evaluate next alias in sequence
"match":                    (string - what to match)
"menu":                     y/n - add alias to menu that appears if you LH click
"name":                     (string - name/label of alias)
"omit_from_command_history":   y/n - omit alias from the command history
"omit_from_log":            y/n - omit alias from log file
"omit_from_output":         y/n - omit sent text from the output window
"one_shot":                 y/n - alias is deleted after firing
"regexp":                   y/n - regular expression
"script":                   (string - name of function to call)
"send":                     (multi-line string - what to send)
"send_to":                  0 - 13 - "send to" location (see below)
"sequence":                 0 - 10000 - sequence number in which to check - lower first
"user":                     -2147483647 to 2147483647 - user-defined number
"variable":                 (string - name of variable to send to)

Boolean options (shown as y/n) are returned as 0 for false (n) or 1 for true (y).

Send-to locations

"0"    - send to MUD                  
"1"    - put in command window        
"2"    - display in output window     
"3"    - put in status line           
"4"    - new notepad                  
"5"    - append to notepad            
"6"    - put in log file              
"7"    - replace notepad              
"8"    - queue it                     
"9"    - set a variable               
"10"    - re-parse as command          
"11"    - send to MUD as speedwalk     
"12"    - send to script engine        
"13"    - send without queuing
"14"    - send to script engine - after omitting from output

lua_notes:
Lua returns nil where applicable instead of an "empty variant" or "null variant".


The "SendTo" field can be looked up using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0
sendto.command = 1
sendto.output = 2
sendto.status = 3
sendto.notepad = 4
sendto.notepadappend = 5
sendto.logfile = 6
sendto.notepadreplace = 7
sendto.commandqueue = 8
sendto.variable = 9
sendto.execute = 10
sendto.speedwalk = 11
sendto.script = 12
sendto.immediate = 13
sendto.scriptafteromit = 14


name: SetAliasOption
prototype: long SetAliasOption(BSTR AliasName, BSTR OptionName, BSTR Value);
summary: Sets the value of a named alias option
vb_example: world.SetAliasOption "myalias", "match", "north"
java_example: world.SetAliasOption ("myalias", "match", "north");
perl_example: $world->SetAliasOption ("myalias", "match", "north");
type_of_object: Method
see_also: AddAlias GetAliasInfo GetAliasOption
python_example: world.SetAliasOption ("myalias", "match", "north")
doc_name: aliases
lua_example: SetAliasOption ("myalias", "match", "north")
description:
Sets the current value of an alias option.

You must specify the name of an existing alias, and an alias option from the list given for GetAliasOption. These are the same names as used in the XML world files for alias options.

Note that you can neither get or set the "name" field. It is listed below for completeness in viewing aliases copied to the clipboard or in world files and plugins. You already know the name when getting the alias option (it is AliasName), and this function is provided to modify existing aliases, not rename them. To change the name of an alias use ExportXML, modify the XML, and then ImportXML.

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

For numeric options (such as "sequence") the supplied string will be converted to a number. It is an error if the string does not consist of digits (0 to 9). For the "user" option an optional leading sign is accepted.

For boolean options (such as "enabled") the supplied string may be:

"y", "Y", or "1" for true
"n", "N", or "0" for false

Also if you are using Lua you can supply simply true or false.


The various option names are:

"echo_alias":               y/n - echo alias itself to output window
"enabled":                  y/n - alias is enabled
"expand_variables":         y/n - expand variables (like @target)
"group":                    (string - group name)
"ignore_case":              y/n - caseless matching
"keep_evaluating":          y/n - evaluate next alias in sequence
"match":                    (string - what to match)
"menu":                     y/n - add alias to menu that appears if you LH click
"name":                     (string - name/label of alias)
"omit_from_command_history":   y/n - omit alias from the command history
"omit_from_log":            y/n - omit alias from log file
"omit_from_output":         y/n - omit sent text from the output window
"one_shot":                 y/n - alias is deleted after firing
"regexp":                   y/n - regular expression
"script":                   (string - name of function to call)
"send":                     (multi-line string - what to send)
"send_to":                  0 - 13 - "send to" location (see below)
"sequence":                 0 - 10000 - sequence number in which to check - lower first
"user":                     -2147483647 to 2147483647 - user-defined number
"variable":                 (string - name of variable to send to)

Send-to locations

"0"    - send to MUD                  
"1"    - put in command window        
"2"    - display in output window     
"3"    - put in status line           
"4"    - new notepad                  
"5"    - append to notepad            
"6"    - put in log file              
"7"    - replace notepad              
"8"    - queue it                     
"9"    - set a variable               
"10"    - re-parse as command          
"11"    - send to MUD as speedwalk     
"12"    - send to script engine        
"13"    - send without queuing
"14"    - send to script engine - after omitting from output

return_value:
eInvalidObjectLabel: The alias name is not valid
eAliasCannotBeEmpty: The "match_text" cannot be empty
eScriptNameNotLocated: The script name cannot be located in the script file
eBadRegularExpression: The regular expression could not be evaluated
ePluginCannotSetOption: The option is marked as non-settable (in a plugin or not)
eOK: set OK

lua_notes:
The "send_to" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0
sendto.command = 1
sendto.output = 2
sendto.status = 3
sendto.notepad = 4
sendto.notepadappend = 5
sendto.logfile = 6
sendto.notepadreplace = 7
sendto.commandqueue = 8
sendto.variable = 9
sendto.execute = 10
sendto.speedwalk = 11
sendto.script = 12
sendto.immediate = 13
sendto.scriptafteromit = 14


You can use true, false or nil for boolean options.


name: GetTimerOption
prototype: VARIANT GetTimerOption(BSTR TimerName, BSTR OptionName);
summary: Gets the value of a named timer option
vb_example: Note world.GetTimerOption ("mytimer", "group")
java_example: Note (world.GetTimerOption ("mytimer", "group"));
perl_example: $world->Note ($world->GetTimerOption ("mytimer", "group"));
return_value: As described above.
type_of_object: Method
see_also: AddTimer GetTimerInfo SetTimerOption GetPluginTimerOption
python_example: world.Note (world.GetTimerOption ("mytimer", "group"))
doc_name: timers
lua_example: Note (GetTimerOption ("mytimer", "group"))
lua_notes: Lua returns nil where applicable instead of an "empty variant" or "null variant".
description:
Gets the current value of a timer option.

You must specify the name of an existing timer, and a timer option from the list below. These are the same names as used in the XML world files for timer options.

Note that you can neither get nor set the "name" field. It is listed below for completeness in viewing timers copied to the clipboard or in world files and plugins. You already know the name when getting the timer option (it is TimerName), and this function is provided to modify existing timers, not rename them. To change the name of a timer use ExportXML, modify the XML, and then ImportXML.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named timer does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

For a detailed description about the meanings of the fields, see AddTimer.

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

To find options for timers in other plugins, use GetPluginTimerOption.

The various option names are:

"active_closed":            y/n - timer is active when world closed
"at_time":                  y/n - y=fire *at* time of day, otherwise every interval
"enabled":                  y/n - timer is enabled
"group":                    (string - group name)
"hour":                     hour to fire at (or every hour)
"minute":                   minute to fire at (or every minute)
"name":                     (string - name/label of alias)
"offset_hour":              offset hour - fire at time *plus* this
"offset_minute":            offset minute - fire at time *plus* this
"offset_second":            offset second - fire at time *plus* this
"omit_from_log":            y/n - omit timer from log file
"omit_from_output":         y/n - omit timer output from log file
"one_shot":                 y/n - delete after firing
"script":                   (string - name of function to call)
"second":                   hour to fire at (or every second)
"send":                     (multi-line string - what to send)     
"send_to":                  0 - 13 - "send to" location (see below)
"user":                      -2147483647 to 2147483647 - user-defined number
"variable":                 (string - name of variable to send to)

Boolean options (shown as y/n) are returned as 0 for false (n) or 1 for true (y).

Send-to locations

"0"    - send to MUD                  
"1"    - put in command window        
"2"    - display in output window     
"3"    - put in status line           
"4"    - new notepad                  
"5"    - append to notepad            
"6"    - put in log file              
"7"    - replace notepad              
"8"    - queue it                     
"9"    - set a variable               
"10"    - re-parse as command          
"11"    - send to MUD as speedwalk     
"12"    - send to script engine        
"13"    - send without queuing
"14"    - send to script engine - after omitting from output


name: SetTimerOption
prototype: long SetTimerOption(BSTR TimerName, BSTR OptionName, BSTR Value);
summary: Sets the value of a named timer option
vb_example: world.SetTimerOption "mytimer", "minute", "5"
java_example: world.SetTimerOption ("mytimer", "minute", "5");
perl_example: $world->SetTimerOption ("mytimer", "minute", "5");
type_of_object: Method
see_also: AddTimer GetTimerInfo GetTimerOption
python_example: world.SetTimerOption ("mytimer", "minute", "5")
doc_name: timers
lua_example: SetTimerOption ("mytimer", "minute", "5")
description:
Sets the current value of a timer option.

You must specify the name of an existing timer, and a timer option from the list given for GetTimerOption. These are the same names as used in the XML world files for timer options.

For a detailed description about the meanings of the fields, see AddTimer.

Note that you can neither get nor set the "name" field. It is listed below for completeness in viewing timers copied to the clipboard or in world files and plugins. You already know the name when getting the timer option (it is TimerName), and this function is provided to modify existing timers, not rename them. To change the name of a timer use ExportXML, modify the XML, and then ImportXML.

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

For numeric options (such as "hour") the supplied string will be converted to a number. It is an error if the string does not consist of digits (0 to 9). For the "user" option an optional leading sign is accepted.

For boolean options (such as "enabled") the supplied string may be:

"y", "Y", or "1" for true
"n", "N", or "0" for false

Also if you are using Lua you can supply simply true or false.

The "offset" options are the time offset within the interval. In other words, if the interval is an hour, but the offset is 45 minutes, then the timer fires 15 minutes into the hour (it still fires every hour, but 45 minutes is subtracted from the fire time). This lets you stagger timer fire times. 

The various option names are:

"active_closed":            y/n - timer is active when world closed
"at_time":                  y/n - y=fire *at* time of day, otherwise every interval
"enabled":                  y/n - timer is enabled
"group":                    (string - group name)
"hour":                     hour to fire at (or every hour)
"minute":                   minute to fire at (or every minute)
"name":                     (string - name/label of alias)
"offset_hour":              offset hour - fire at time *plus* this
"offset_minute":            offset minute - fire at time *plus* this
"offset_second":            offset second - fire at time *plus* this
"omit_from_log":            y/n - omit timer from log file
"omit_from_output":         y/n - omit timer output from log file
"one_shot":                 y/n - delete after firing
"script":                   (string - name of function to call)
"second":                   second to fire at (or every second)
"send":                     (multi-line string - what to send)     
"send_to":                  0 - 13 - "send to" location (see below)
"user":                      -2147483647 to 2147483647 - user-defined number
"variable":                 (string - name of variable to send to)

Send-to locations

"0"    - send to MUD                  
"1"    - put in command window        
"2"    - display in output window     
"3"    - put in status line           
"4"    - new notepad                  
"5"    - append to notepad            
"6"    - put in log file              
"7"    - replace notepad              
"8"    - queue it                     
"9"    - set a variable               
"10"    - re-parse as command          
"11"    - send to MUD as speedwalk     
"12"    - send to script engine        
"13"    - send without queuing
"14"    - send to script engine - after omitting from output

return_value:
eInvalidObjectLabel: The timer name is not valid
eTimeInvalid: Time is out of range (hours not 0 to 23, minutes/seconds not 0-59)
eScriptNameNotLocated: The script name cannot be located in the script file
eBadRegularExpression: The regular expression could not be evaluated
ePluginCannotSetOption: The option is marked as non-settable (in a plugin or not)
eOK: set OK

lua_notes:
The "send_to" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0
sendto.command = 1
sendto.output = 2
sendto.status = 3
sendto.notepad = 4
sendto.notepadappend = 5
sendto.logfile = 6
sendto.notepadreplace = 7
sendto.commandqueue = 8
sendto.variable = 9
sendto.execute = 10
sendto.speedwalk = 11
sendto.script = 12
sendto.immediate = 13
sendto.scriptafteromit = 14

You can use true, false or nil for boolean options.


name: SaveNotepad
prototype: long SaveNotepad(BSTR Title, BSTR FileName, BOOL ReplaceExisting);
summary: Saves a notepad window to disk
vb_example: world.SaveNotepad "my_notepad", "c:/mushclient/notepad.txt", 0
java_example: world.SaveNotepad ("my_notepad", "c:/mushclient/notepad.txt", 0);
perl_example: $world->SaveNotepad ("my_notepad", "c:/mushclient/notepad.txt", 0);
return_value: 1 = saved OK 0 = not saved
type_of_object: Method
python_example: world.SaveNotepad ("my_notepad", "c:/mushclient/notepad.txt", 0)
doc_name: notepad
lua_example: SaveNotepad ("my_notepad", "c:/mushclient/notepad.txt", 0)
lua_notes: The ReplaceExisting flag is optional, and defaults to false.
description:
This saves an existing notepad window to disk.

Title - title of the notepad (used in functions like AppendToNotepad)

FileName - name to save to disk as.
  
If the file name is empty (ie. "") then it will be saved under its existing file name, if any, or you will be prompted for the name to save it as.

ReplaceExisting:

If true - the specified file name becomes the "default" file name for the file. In other words, if you subsequently save from the GUI interface it will automatically use that file.

If false - saves the file under the name you specify, however the "default" file name is unchanged.


WARNING - if a file of the same name exists on disk it will be overwritten, regardless of the ReplaceExisting flag value.

SECOND WARNING - versions 4.13 and earlier of MUSHclient returned 0 on a good save and 1 on a bad save. From version 4.14 onwards it returns 0 on a bad save and 1 on a good save.

see_also:
GetNotepadLength GetNotepadText AppendToNotepad SendToNotepad ActivateNotepad ReplaceNotepad CloseNotepad NotepadSaveMethod GetNotepadList


name: CloseNotepad
prototype: long CloseNotepad(BSTR Title, BOOL QuerySave);
summary: Closes a notepad window
vb_example: world.CloseNotepad "my_notepad", 0
java_example: world.CloseNotepad ("my_notepad", 0);
perl_example: $world->CloseNotepad ("my_notepad", 0);
return_value: 1 = closed OK 0 = not closed
type_of_object: Method
see_also: AppendToNotepad SendToNotepad ActivateNotepad ReplaceNotepad SaveNotepad GetNotepadList
python_example: world.CloseNotepad ("my_notepad", 0)
doc_name: notepad
lua_example: CloseNotepad ("my_notepad", 0)
lua_notes: The QuerySave argument is optional, and defaults to false.
description:
This closes a notepad window.

Title - title of the notepad (used in functions like AppendToNotepad)

QuerySave - whether to query to save changes, if the contents of the window have changed.


name: GetEntity
prototype: BSTR GetEntity(BSTR Name);
summary: Retrieves the value of an MXP server-defined entity
vb_example: world.Note world.GetEntity ("foo")
java_example: world.Note (world.GetEntity ("foo"));
perl_example: $world->Note (world.GetEntity ("foo"));
return_value: The contents of the specified entity, or an empty string if no such entity is found.
type_of_object: Method
see_also: GetVariable SetEntity GetXMLEntity
python_example: world.Note (world.GetEntity ("foo"))
doc_name: info
lua_example: Note (GetEntity ("foo"))
description:
Returns the value of an entity defined by the MUD server using MXP.

eg.

If the server sent:

  <!ENTITY foo "bar">

Then if you did this:

  world.Note world.GetEntity ("foo")

You would see "bar" displayed.

To get standard (automatically defined) entities use GetXMLEntity.


name: Execute
prototype: long Execute(BSTR Command);
summary: Executes a command as if you had typed it into the command window
perl_example: $world->Execute ("north"); # normal command $world->Execute ("4s 3e"); # speed walk
return_value: eOK: Executed OK eWorldClosed: World is closed eCommandsNestedTooDeeply: Commands nested too deeply
type_of_object: Method
see_also: Send
description:
The Execute function lets you execute arbitrary commands as if they were typed into the command window.

The command will be parsed exactly the same as the command window parser, depending on currently-set options (eg. speedwalking, command stacking, scripting etc.).

The only difference is that the command will:

* Not be placed in the command history (as you didn't actually type it in)
* Not unpause the output window if it is paused

There is a possibility that you might accidentally nest calls to execute, for example if an alias called itself, so MUSHclient limits nested calls to the Execute function to 20 levels of nesting.

Note that the Execute function ignores the auto-say setting. Thus you can still use Execute to do things, even if the player has turned on auto-say for a quick chat. However if you are planning to do script commands you will need to be sure that the scripting prefix has not changed.

If you are planning to execute a script using Execute you should probably find the current script prefix (using world.GetOption) rather than relying it on being the same all the time.

vb_example:
world.Execute "north"  ' normal command
world.Execute "#4s 3e"  ' speed walk
world.Execute "/world.Debug ""colours "" "  ' execute a script

java_example:
world.Execute ("north");  // normal command
world.Execute ("4s 3e");  // speed walk
world.Execute ("/world.Debug ("colours ") ");  // execute a script

python_example:
world.Execute ("north")  # normal command
world.Execute ("4s 3e")  # speed walk
world.Execute ("world.Debug ("colours ") ")  # execute a script

lua_example:
Execute ("north")  -- normal command
Execute ("4s 3e")  -- speed walk
Execute ("/Debug ('colours') ")  -- execute a script


name: DoAfterSpecial
prototype: long DoAfterSpecial(long Seconds, BSTR SendText, short SendTo);
summary: Adds a one-shot, temporary, timer to carry out some special action
type_of_object: Method
see_also: DoAfter DoAfterNote DoAfterSpeedWalk AddTimer
doc_name: timers
description:
This routine adds an unlabelled, temporary, one-shot timer, set to go off after 
the designated number of seconds. 

The timer sends its "SendText" text to the designated location when it fires.

The first argument (seconds) must evaluate to a time between 0.1 second, 
and 23 hours 59 minutes 59 seconds (that is, 0.1 to 86,399). 

From version 3.61 onwards of MUSHclient the interval may include fractions (ie. it is a floating-point number). This lets you set up sub-second intervals (eg. 0.5 seconds, 1.2 seconds).

To enable this you need to go to Global Configuration -> Timers and set the 'Timer Interval' in seconds to zero.

The maximum granularity of the timers is currently 0.1 seconds. In other words, regardless of what you specify, the timers are only checked every 10th of a second.

The purpose of this is simplify the frequent case of simply wanting to do 
something in a few seconds, rather than using AddTimer.

This lets you do things that involve simple scripting at some future time, 
without having to go to a lot of trouble writing script routines.

The "SendTo" argument specifies where the text is to be sent to when the 
time elapsed. It can be one of:

0: World 
1: Command window
2: Output window
3: Status line
4: Notepad (new)
5: Notepad (append)
6: Log File 
7: Notepad (replace)
8: Command queue
9: Send To Variable
10: Execute (re-parse as command)
11: Speedwalk (send text is speedwalk, queue it)
12: Script (send to script engine)
13: Immediate (send to world in front of speedwalk queue)
14: Script - after omit (send to script engine, after lines have been omitted)

The case "set variable" is not very useful because there is no way of specifying which variable, 
however instead you could use "send to script" (12) and do a "setvariable". eg.

world.DoAfterSpecial 5, "SetVariable ""target"", ""kobold"" ", 12

This example uses double-quotes for the variable name and variable value, because they are quotes 
within quotes (an argument to SetVariable inside the argument to DoAfterSpecial).

Also, case "Script - after omit" is really intended for use in triggers, and will have the same behaviour as "Script" if used elsewhere.

WARNING - as DoAfterSpecial is implemented by using temporary MUSHclient timers, it will not work if timers are disabled. If DoAfterSpecial is not working for you (however the function call is returning zero) then ensure that timers are enabled in the Timers configuration dialog.

vb_example:
world.DoAfterSpecial 5, "EnableTriggerGroup ""mygroup"", 1", 12

In the above example the last argument (12) means send the 
command to the script engine after 5 seconds. 

The argument to EnableTriggerGroup has double quotes, 
because it is quotes within quotes.


world.DoAfterSpecial 10, "4s 3w", 11

In the above example the last argument (11) means send the command 
to the speed walk parser after 10 seconds.

java_example:
world.DoAfterSpecial (5, "EnableTriggerGroup ("mygroup", 1);", 12);

In the above example the last argument (12) means send the 
command to the script engine after 5 seconds. 

The argument to EnableTriggerGroup has escaped quotes, 
because it is quotes within quotes.


world.DoAfterSpecial (10, "4s 3w", 11);

perl_example:
$world->DoAfterSpecial (5, 'EnableTriggerGroup ("mygroup", 1);', 12);

In the above example the last argument (12) means send the 
command to the script engine after 5 seconds. 

We use single quotes for the argument to DoAfterSpecial, 
so we can use double quotes for the argument to EnableTriggerGroup.


$world->DoAfterSpecial (10, "4s 3w", 11);

return_value:
eTimeInvalid: The time is invalid (seconds not in range 0.1 to 86,399). 
eOptionOutOfRange: The "SendTo" argument is not in the range 0 to 12.
eOK: added OK

python_example:
world.DoAfterSpecial (5, "EnableTriggerGroup ("mygroup", 1)", 12)

In the above example the last argument (12) means send the 
command to the script engine after 5 seconds. 

The argument to EnableTriggerGroup has escaped quotes, 
because it is quotes within quotes.


world.DoAfterSpecial (10, "4s 3w", 11)

lua_example:
DoAfterSpecial (5, 'EnableTriggerGroup ("mygroup", 1)', sendto.script)

--[[
In the above example the last argument (sendto.script) means send the 
command to the script engine after 5 seconds. 

The argument to EnableTriggerGroup has the alternative quotes, 
because it is quotes within quotes.
--]]


DoAfterSpecial (10, "4s 3w", sendto.speedwalk)

lua_notes:
The "SendTo" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0
sendto.command = 1
sendto.output = 2
sendto.status = 3
sendto.notepad = 4
sendto.notepadappend = 5
sendto.logfile = 6
sendto.notepadreplace = 7
sendto.commandqueue = 8
sendto.variable = 9
sendto.execute = 10
sendto.speedwalk = 11
sendto.script = 12
sendto.immediate = 13
sendto.scriptafteromit = 14


name: ANSI
prototype: BSTR ANSI(short Code);
summary: Generates an ANSI colour sequence
vb_example: ANSINote "This is normal" & ANSI (33) & " and this is yellow"
java_example: ANSINote ("This is normal" + ANSI (33) + " and this is yellow");
perl_example: ANSINote ("This is normal" . ANSI (33) . " and this is yellow");
return_value: A string consisting of: ESC "[" Code "m"
type_of_object: Method
see_also: AnsiNote StripANSI ChatNote ChatMessage
python_example: world.ANSINote ("This is normal", world.ANSI (33, 47), " and this is yellow")
doc_name: colours
lua_example: AnsiNote ("This is normal ", ANSI (33, 47), "and this is yellow on white")
description:
This generates an ANSI colour sequence, like this:

ESC [ code m

The code number is supplied as an argument.

This is intended to be used with the ANSINote function - which lets you write to the output window with ANSI formatting, or to send to other clients via the chat system.

Useful numbers to use would be:

Miscellaneous

 0: reset
 1: bold
 3: blink (is rendered as italic)
 4: underline
 7: inverse

22: cancel bold
23: cancel blink
24: cancel underline
27: cancel inverse

Foreground (text) colour

30: Black  
31: Red    
32: Green  
33: Yellow 
34: Blue   
35: Magenta
36: Cyan   
37: White  

Background colour

40: Black  
41: Red    
42: Green  
43: Yellow 
44: Blue   
45: Magenta
46: Cyan   
47: White

// 256 colour ANSI foreground
38;5;n  where n is 0 to 255

// 256 colour ANSI background
48;5;n  where n is 0 to 255


Suggestion - you could conceivably replace colours in incoming chat messages by doing a world.Replace using ANSI, providing the incoming ANSI codes conform exactly to the rendering used here.

For example:

  mymessage = world.Replace (incoming_message, ANSI (36), ANSI (37))

This would hopefully replace the code for Cyan with the code for White.

lua_notes:
You can supply multiple arguments, as in the above example. 
Each one will generate its own ANSI code, so you can easily do multiple changes 

(eg. foreground, background, bold) in a single call to ANSI.

If you supply multiple arguments they will be placed into the same ANSI sequence, like this:

ANSI (33, 47) --> ESC[33;47m


name: AnsiNote
prototype: void AnsiNote(BSTR Text);
summary: Make a note in the output window from text with ANSI colour codes imbedded
return_value: Nothing.
type_of_object: Method
see_also: ANSI StripANSI ChatNote Note ColourNote NoteStyle
doc_name: note
lua_example: AnsiNote (ANSI (32, 1, 43), "This is bold green text on a yellow background")
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
Sends "Text" to the output window, changing colour, bold, underline etc. if it gets ANSI sequences in the text. ANSI sequences are things like ESC [ 30 m. You can use the ANSI function to set them up.

AnsiNote saves the current world note colour, and restores it afterwards, so that any colour changes do not persist to subsequent note lines.

The ANSI sequences defined in the ANSI function will be recognised.

WARNING: Bold italic, and underlined styles will only be visible if the appropriate configurations are enabled in the world Appearance: Output configuration. Otherwise they will be ignored (the same as for text arriving from the MUD).

vb_example:
AnsiNote ANSI (32) & ANSI (1) & ANSI (43) & _
          "This is bold green text on a yellow background"

java_example:
AnsiNote (ANSI (32) + ANSI (1) + ANSI (43) + 
         "This is bold green text on a yellow background");

perl_example:
AnsiNote (ANSI (32) . ANSI (1) . ANSI (43) . 
         "This is bold green text on a yellow background");

python_example:
world.AnsiNote (world.ANSI (32) + world.ANSI (1) + world.ANSI (43) + 
"This is bold green text on a yellow background")


name: ChatAcceptCalls
prototype: long ChatAcceptCalls(short Port);
summary: Accepts incoming chat calls
vb_example: ChatAcceptCalls 0 ' use the default port ChatAcceptCalls 4051 ' use port 4051
java_example: ChatAcceptCalls (0); // use the default port ChatAcceptCalls (4051); // use port 4051
perl_example: ChatAcceptCalls (0); # use the default port ChatAcceptCalls (4051); # use port 4051
type_of_object: Method
see_also: ChatCall ChatDisconnect ChatDisconnectAll ChatStopAcceptingCalls
python_example: world.ChatAcceptCalls (0) # use the default port world.ChatAcceptCalls (4051) # use port 4051
doc_name: chat
lua_example: ChatAcceptCalls (0) -- use the default port ChatAcceptCalls (4051) -- use port 4051
lua_notes: The Port argument is optional. If omitted it defaults to 4050.
description:
Starts accepting incoming chat calls.

The port number specifies which port to listen for the calls on. If zero, the default chat port is used. If non-zero, this will change the default chat port.

This will fail if MUSHclient is already accepting calls.

It will also fail if another program or another world (eg. another MUSHclient window) is already listening for calls on the specified port. Thus, if you are accepting calls in different worlds simultaneously, each one must use a different port.

The default port for chats is 4050.

return_value:
eChatAlreadyListening: We are already accepting calls.
eCannotCreateChatSocket: We cannot do that, probably the port is in use.
eOK: Now accepting calls.


name: ChatCall
prototype: long ChatCall(BSTR Server, long Port);
summary: Calls a chat server (makes an outgoing call) using the MudMaster chat protocol
type_of_object: Method
see_also: ChatAcceptCalls ChatDisconnect ChatDisconnectAll ChatStopAcceptingCalls ChatCallzChat
doc_name: chat
lua_notes: The Port argument is optional. If omitted it defaults to 4050.
description:
Attempts to establish a chat call to another client. If you know the other client is using zChat you may wish to use ChatCallzChat instead which uses the zChat protocol.

You specify the TCP/IP address and the port number. If the port number is zero the default chat port of 4050 is used.

Because of the asynchronous nature of TCP/IP a "good" status from this call does not necessarily mean you will establish a chat session, it just means it has succeeded in starting the process.

In order to establish a chat session, MUSHclient must:

1. Look up the name using the Domain Name Server (DNS) unless a dotted-decimal name was given - this may take a few seconds.
2. Connect to the chat server - this may take a few more seconds
3. Attempt to negotiate a chat session by sending "CHAT:" to the chat server
4. Await a response - this may take a while if the player at the other end is deciding whether to accept the connection or not.
5. Finally, if all goes well, the chat session is established.

To know if the session was really established you need to use the plugin callback routine "OnPluginChatNewUser" - this notifies you when a new user is established.

vb_example:
ChatCall "123.45.67.89", 0     ' call on default port
ChatCall "123.45.67.89", 4060  ' call on port 4060
ChatCall "myfriend.hisdomain.com", 0    ' call on default port using name

java_example:
ChatCall ("123.45.67.89", 0);     // call on default port
ChatCall ("123.45.67.89", 4060);  // call on port 4060
ChatCall ("myfriend.hisdomain.com", 0);    // call on default port using name

perl_example:
ChatCall ("123.45.67.89", 0);     # call on default port
ChatCall ("123.45.67.89", 4060);  # call on port 4060
ChatCall ("myfriend.hisdomain.com", 0);    # call on default port using name

return_value:
eCannotCreateChatSocket: Cannot start call - perhaps all sockets are in use?
eCannotLookupDomainName: Cannot start looking up domain name
eOK: Call process started OK

python_example:
world.ChatCall ("123.45.67.89", 0)     # call on default port
world.ChatCall ("123.45.67.89", 4060)  # call on port 4060
world.ChatCall ("myfriend.hisdomain.com", 0)    # call on default port using name

lua_example:
ChatCall ("123.45.67.89")     -- call on default port
ChatCall ("123.45.67.89", 4060)  -- call on port 4060
ChatCall ("myfriend.hisdomain.com")    -- call on default port using name


name: ChatDisconnect
prototype: long ChatDisconnect(long ID);
summary: Disconnects a current chat call
vb_example: ChatDisconnect 5 ' disconnect chat user 5 ChatDisconnect ChatGetID ("nick") ' disconnect nick
return_value: eChatIDNotFound: That chat ID was not found eOK: Disconnected OK
type_of_object: Method
see_also: ChatAcceptCalls ChatCall ChatDisconnectAll ChatStopAcceptingCalls GetChatList ChatGetID
doc_name: chat
description:
Disconnects an existing chat call. 

The call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world. 

You can use GetChatList to find a list of chat IDs that is current. 

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

If a file transfer is in progress it is aborted. 

The plugin callback routine "OnPluginChatUserDisconnect" will be called for this user.

java_example:
ChatDisconnect (5);  // disconnect chat user 5
ChatDisconnect (ChatGetID ("nick"));  // disconnect nick

perl_example:
ChatDisconnect (5);  #/ disconnect chat user 5
ChatDisconnect (ChatGetID ("nick"));  # disconnect nick

python_example:
world.ChatDisconnect (5)  # disconnect chat user 5
world.ChatDisconnect (world.ChatGetID ("nick"))  # disconnect nick

lua_example:
ChatDisconnect (5)  -- disconnect chat user 5
ChatDisconnect (ChatGetID ("nick"))  -- disconnect nick


name: ChatDisconnectAll
prototype: long ChatDisconnectAll();
summary: Disconnects all current chat calls
vb_example: ChatDisconnectAll
java_example: ChatDisconnectAll ();
perl_example: ChatDisconnectAll ();
return_value: A count of the number of calls disconnected.
type_of_object: Method
see_also: ChatAcceptCalls ChatCall ChatDisconnect ChatStopAcceptingCalls GetChatList
python_example: world.ChatDisconnectAll
doc_name: chat
lua_example: ChatDisconnectAll ()
description:
Disconnects all existing chat calls. 

If any file transfers are in progress they wil be aborted. 

The plugin callback routine "OnPluginChatUserDisconnect" will be called for each user.

If you want to know which calls are currently connected, use GetChatList.


name: ChatEverybody
prototype: long ChatEverybody(BSTR Message, BOOL Emote);
summary: Sends a chat message to every connected chat user
vb_example: ChatEverybody "hi there", 0 ' say it ChatEverybody "laughs", 1 ' emote it
java_example: ChatEverybody ("hi there", 0); // say it ChatEverybody ("laughs", 1); // emote it
perl_example: ChatEverybody ("hi there", 0); # say it ChatEverybody ("laughs", 1); # emote it
return_value: eNoChatConnections: No connections (that are not being ignored) eOK: Sent to at least one person
type_of_object: Method
see_also: ChatPasteEverybody ChatPersonal ChatGroup ChatID GetChatList ChatGetID
python_example: world.ChatEverybody ("hi there", 0) # say it world.ChatEverybody ("laughs", 1) # emote it
doc_name: chat
lua_example: ChatEverybody ("hi there", 0) -- say it ChatEverybody ("laughs", 1) -- emote it
lua_notes: The Emote argument is optional and defaults to false.
description:
This sends a "say" or "emote" to all connected chat users, excepting the ones you are ignoring, if any.

If the "emote" parameter is zero (false) then you will "say" the message, otherwise you will emote it.

If you "say" the message, it will appear like this on other people's clients:

Nick chats to everybody, 'hi there'

If you "emote" the message, it will appear like this on other people's clients:

Nick laughs


name: ChatPersonal
prototype: long ChatPersonal(BSTR Who, BSTR Message, BOOL Emote);
summary: Sends a chat message to a particular person
vb_example: ChatPersonal "Nick", "hi there", 0 ' say it ChatPersonal "Nick", "laughs", 1 ' emote it
java_example: ChatPersonal ("nick", "hi there", 0); // say it ChatPersonal ("nick", "laughs", 1); // emote it
perl_example: ChatPersonal ("nick", "hi there", 0); # say it ChatPersonal ("nick", "laughs", 1); # emote it
return_value: eChatPersonNotFound: No person of that name connected eOK: Sent to at least one person
type_of_object: Method
see_also: ChatPasteEverybody ChatEverybody ChatGroup ChatID GetChatList ChatGetID
doc_name: chat
lua_example: ChatPersonal ("nick", "hi there") -- say it ChatPersonal ("nick", "laughs", true) -- emote it
lua_notes: The Emote argument is optional and defaults to false.
description:
This sends a "say" or "emote" to the person(s) of that name.

If more than one person has the specified name, all will get the message. If this is a problem, use ChatID to send a message to a specific user by number rather than name.

If the "emote" parameter is zero (false) then you will "say" the message, otherwise you will emote it.

If you "say" the message, it will appear like this on that person's client:

Nick chats to you, 'hi there'

If you "emote" the message, it will appear like this on that person's client:

To you, Nick laughs

The different message (compared to ChatEverybody or ChatGroup) is so you can tell the message was addressed to you personally.

The message will be sent even if you have set the "ignore" flag on that person, as presumably you want to override it, if you are addressing a message to them directly.

python_example:
world.ChatPersonal ("nick", "hi there", 0)  # say it
world.ChatPersonal ("nick", "laughs", 1)  # emote it


name: ChatID
prototype: long ChatID(long ID, BSTR Message, BOOL Emote);
summary: Sends a chat message to a particular chat session
vb_example: ChatID 5, "hi there", 0 ' say it ChatID 5, "laughs", 1 ' emote it
java_example: ChatID (5, "hi there", 0); // say it ChatID (5, "laughs", 1); // emote it
perl_example: ChatID (5, "hi there", 0); # say it ChatID (5, "laughs", 1); # emote it
return_value: eChatIDNotFound: No person of that ID is connected eOK: Sent to at least one person
type_of_object: Method
see_also: ChatPasteEverybody ChatEverybody ChatGroup ChatPersonal GetChatList ChatGetID
python_example: world.ChatID (5, "hi there", 0) # say it world.ChatID (5, "laughs", 1) # emote it
doc_name: chat
lua_example: ChatID (5, "hi there") -- say it ChatID (5, "laughs", true) -- emote it
lua_notes: The Emote argument is optional and defaults to false.
description:
This sends a "say" or "emote" to the with that Chat ID.

Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world. 

You can use GetChatList to find a list of chat IDs that is current.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

If the "emote" parameter is zero (false) then you will "say" the message, otherwise you will emote it.

If you "say" the message, it will appear like this on that person's client:

Nick chats to you, 'hi there'

If you "emote" the message, it will appear like this on that person's client:

To you, Nick laughs

The different message (compared to ChatEverybody or ChatGroup) is so you can tell the message was addressed to you personally.

The message will be sent even if you have set the "ignore" flag on that person, as presumably you want to override it, if you are addressing a message to them directly.


name: ChatGroup
prototype: long ChatGroup(BSTR Group, BSTR Message, BOOL Emote);
summary: Sends a chat message to every connected chat user in the specified group
vb_example: ChatGroup "friends", "hi there", 0 ' say it ChatGroup "friends", "laughs", 1 ' emote it
java_example: ChatGroup ("friends", "hi there", 0); // say it ChatGroup ("friends", "laughs", 1); // emote it
perl_example: ChatGroup ("friends", "hi there", 0); # say it ChatGroup ("friends", "laughs", 1); # emote it
type_of_object: Method
see_also: ChatPasteEverybody ChatPersonal ChatEverybody ChatID GetChatList ChatGetID SetChatOption
doc_name: chat
lua_example: ChatGroup ("friends", "hi there") -- say it ChatGroup ("friends", "laughs", true) -- emote it
lua_notes: The Emote argument is optional and defaults to false.
description:
This sends a "say" or "emote" to all connected chat users in the specified group, excepting the ones you are ignoring, if any.

If the "emote" parameter is zero (false) then you will "say" the message, otherwise you will emote it.

If you "say" the message, it will appear like this on other people's clients:

Nick chats to the group, 'hi'

If you "emote" the message, it will appear like this on other people's clients:

To the group, Nick laughs

To put a particular chat user into a group, use SetChatOption, like this:

world.SetChatOption 5, "group", "friends" ' put user 5 into group friends

return_value:
eBadParameter: No group name specified
eNoChatConnections: No connections in that group (that are not being ignored)
eOK: Sent to at least one person

python_example:
world.ChatGroup ("friends", "hi there", 0)  # say it
world.ChatGroup ("friends", "laughs", 1)  # emote it


name: ChatPasteText
prototype: long ChatPasteText(long ID);
summary: Pastes the clipboard contents to that person
vb_example: ChatPasteText 5 ' paste to user 5 ChatPasteText ChatGetID ("nick") ' paste to Nick
java_example: ChatPasteText (5); // paste to user 5 ChatPasteText (ChatGetID ("nick")); // paste to Nick
perl_example: ChatPasteText (5); # paste to user 5 ChatPasteText (ChatGetID ("nick")); # paste to Nick
return_value: eChatIDNotFound: No call with that chat ID eClipboardEmpty: No text on the clipboard eOK: Sent OK
type_of_object: Method
see_also: ChatPasteEverybody ChatEverybody ChatGroup ChatID GetChatList ChatGetID ChatPersonal
doc_name: chat
lua_example: ChatPasteText (5) -- paste to user 5 ChatPasteText (ChatGetID ("nick")) -- paste to Nick
description:
This pastes the clipboard contents to the person with that chat ID.

The clipboard must contain text - if it does the entire contents will be pasted to that person (as a personal chat message, so it will work with other clients), and echoed on your output window as well.

You could use that to exchange aliases, triggers, messages from the screen, and so on.

Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world. 

You can use GetChatList to find a list of chat IDs that is current.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

python_example:
world.ChatPasteText (5)   # paste to user 5
world.ChatPasteText (world.ChatGetID ("nick"))  # paste to Nick


name: ChatPasteEverybody
prototype: long ChatPasteEverybody();
summary: Pastes the clipboard contents to every connected person
vb_example: ChatPasteEverybody
java_example: ChatPasteEverybody ();
perl_example: ChatPasteEverybody ();
return_value: eNoChatConnections: No chat connetions found eClipboardEmpty: No text on the clipboard eOK: Sent OK
type_of_object: Method
see_also: ChatPasteText ChatEverybody ChatGroup ChatID GetChatList ChatGetID ChatPersonal
python_example: world.ChatPasteEverybody
doc_name: chat
lua_example: ChatPasteEverybody ()
description:
This pastes the clipboard contents to everybody (who you are not ignoring).

The clipboard must contain text - if it does the entire contents will be pasted to that everybody (as an "everybody" chat message, so it will work with other clients), and echoed on your output window as well.

You could use that to exchange aliases, triggers, messages from the screen, and so on.


name: ChatGetID
prototype: long ChatGetID(BSTR Who);
summary: Looks up what chat ID (identifier) corresponds to a particular chat name
vb_example: ChatID ChatGetID ("nick"), "hi there", 0
java_example: ChatID (ChatGetID ("nick"), "hi there", 0);
perl_example: ChatID (ChatGetID ("nick"), "hi there", 0);
return_value: The chat ID corresponding to that name, or zero if none is found.
type_of_object: Method
python_example: world.ChatID (world.ChatGetID ("nick"), "hi there", 0)
doc_name: chat
lua_example: ChatID (ChatGetID ("nick"), "hi there", 0)
description:
Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world. 

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

If more than one person has that name the first one (earliest connection) is returned.

If no person has that name zero is returned.

A message is sent to the output window, so you can use ChatGetID in scripts and have them automatically notify you if that person cannot be found.

see_also:
ChatMessage ChatNameChange ChatPeekConnections ChatPing ChatRequestConnections ChatSendFile ChatStopFileTransfer GetChatInfo GetChatOption SetChatOption


name: ChatMessage
prototype: long ChatMessage(long ID, short Message, BSTR Text);
summary: Sends a message to a chat user (raw format)
return_value: eChatIDNotFound: That chat ID is not connected eOK: Sent OK
type_of_object: Method
see_also: ChatEverybody ChatPasteEverybody ChatPersonal ChatGroup ChatID GetChatList ChatGetID ChatPersonal
doc_name: chat
lua_notes: The message is optional and defaults to the empty string.
description:
This sends a "raw" chat message to the particular chat user identified by the chat ID.

You would not normally use this, as this is a low-level routine which is used by other script functions (such as ChatPersonal).

However you could use it to do custom chat messages (eg. use message number 200) which the receiving client could pick up in a plugin callback routine.

For an example of doing that, see:

http://www.gammon.com.au/mushclient/chat.htm#EXAMPLE

Another possible use would be to send chat messages with custom colours, or custom formatting (eg. different colours).

The "Message" argument is the chat message number, which is used at the start of the chat message. These numbers are currently defined:

   1    Name_change				  
   2    Request_connections 
   3    Connection_list	 		
   4    Text_everybody			
   5    Text_personal			  
   6    Text_group				  
   7    Message					    
   8    Do_not_disturb			
   9    Send_action				  
  10    Send_alias				  
  11    Send_macro				  
  12    Send_variable				
  13    Send_event			    
  14    Send_gag				    
  15    Send_highlight			
  16    Send_list				    
  17    Send_array				  
  18    Send_baritem			  
  19    Version					    
  20    File_start				  
  21    File_deny				    
  22    File_block_request	
  23    File_block			    
  24    File_end				    
  25    File_cancel				  
  26    Ping_request				
  27    Ping_response				
  28    Peek_connections		
  29    Peek_list			    	
  30    Snoop					      
  31    Snoop_data		
 105    Send_command		  

The "Text" argument is the text of the message to be sent. It can be empty. See the chat specifications for more details about what should be in the text field. You do *not* need to put the message number at the start of the text field, nor do you need to put the message terminator (hex FF) at the end of the text field. MUSHclient does that for you automatically.


Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world. 

You can use GetChatList to find a list of chat IDs that is current.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

vb_example:
ChatMessage ChatGetID ("fred"), 30, ""  ' start snooping Fred
'
'  do a custom coloured "chat to everybody" (using bold magenta)
'
' (The chat is only sent to connection Bruce, however)
'

ChatMessage ChatGetID ("bruce"), 4, _
             vbCrLf & ANSI (35) & ANSI (1) & _
             "<CHAT> The chat system is great!" & _
             vbCrLf

java_example:
ChatMessage (ChatGetID ("fred"), 30, "");  // start snooping Fred
//
//  do a custom coloured "chat to everybody" (using bold magenta)
//
// (The chat is only sent to connection Bruce, however)

ChatMessage (ChatGetID ("bruce"), 4, 
             "\n" + ANSI (35) + ANSI (1) + 
             "<CHAT> The chat system is great!\n");

perl_example:
ChatMessage (ChatGetID ("fred"), 30, "");  # start snooping Fred
#
#  do a custom coloured "chat to everybody" (using bold magenta)
#
# (The chat is only sent to connection Bruce, however)

ChatMessage (ChatGetID ("bruce"), 4, 
             "\n" . ANSI (35) . ANSI (1) . 
             "<CHAT> The chat system is great!\n");

python_example:
world.ChatMessage (world.ChatGetID ("fred"), 30, "")  # start snooping Fred
#
#  do a custom coloured "chat to everybody" (using bold magenta)
#
# (The chat is only sent to connection Bruce, however)

world.ChatMessage (world.ChatGetID ("bruce"), 4, 
             "n" + world.ANSI (35) + world.ANSI (1) + 
             "<CHAT> The chat system is great!n")

lua_example:
ChatMessage (ChatGetID ("fred"), 30)  -- start snooping Fred
--
--  do a custom coloured "chat to everybody" (using bold magenta)
--
-- (The chat is only sent to connection Bruce, however)

ChatMessage (ChatGetID ("bruce"), 4, 
             "n" .. ANSI (35) .. ANSI (1) .. 
             "<CHAT> The chat system is great!n")


name: ChatNameChange
prototype: long ChatNameChange(BSTR NewName);
summary: Changes your chat name
vb_example: ChatNameChange "Krenath"
java_example: ChatNameChange ("Krenath");
perl_example: ChatNameChange ("Krenath");
return_value: eBadParameter: No name supplied eOK: Name changed
type_of_object: Method
see_also: GetChatInfo GetChatOption SetChatOption
python_example: world.ChatNameChange ("Krenath")
doc_name: chat
lua_example: ChatNameChange ("Krenath")
description:
This changes your chat name - the name other people see when connecting to you, or when you connect to them. A message is sent to all directly connected users notifying them of the name change, so their clients should show the new name immediately.


name: ChatNote
prototype: void ChatNote(short NoteType, BSTR Message);
summary: Does a note using ANSI codes for the chat system
vb_example: ChatNote 3, "<CHAT> My plugin is now installed"
java_example: ChatNote (3, "<CHAT> My plugin is now installed");
perl_example: ChatNote (3, "<CHAT> My plugin is now installed");
return_value: Nothing.
type_of_object: Method
see_also: AnsiNote ColourNote Note SetOption GetOption ANSI
python_example: world.ChatNote (3, "<CHAT> My plugin is now installed")
doc_name: chat
lua_example: ChatNote (3, "<CHAT> My plugin is now installed")
lua_notes: The message is optional and defaults to the empty string.
description:
This is used internally by the chat system to put notes on the screen in the current chat colour.

First, it calls the plugin callback routine "OnPluginChatDisplay" for each installed plugin, and passes the NoteType and Message to it. This gives the plugin a chance to do its own thing with the message (for instance, display it in a notepad window).

If any plugin returns False (0) then ChatNote exits without doing anything else (including calling other plugins later down the list).

However if all plugins return true (or don't have a "OnPluginChatDisplay" handler) then ChatNote then does the following:

1. Save the current note colour.
2. Change the note colour to the "chat_foreground_colour" and "chat_background_colour" from the world preferences. If they are both the same, it takes the default chat colour of red on black.
3. Removes a leading newline, if any.
4. Removes a trailing newline, if any.
5. If the world preferences option "ignore_chat_colours" is set, the ANSI codes are stripped from the message.
6. The message is displayed (using AnsiNote).
7. The saved note colour is restored.


The NoteType argument is used to identify "types" of chats to the plugin callback routine. These types are currently defined:

   0 Connection attempt    
   1 Session start, end          
   2 Name Change        
   3 Message           
   4 Incoming Personal  
   5 Incoming Everybody 
   6 Incoming roup     
   7 Outgoing Personal  
   8 Outgoing Everybody 
   9 Outgoing Group     
  10 Peek List          
  11 Connection List    
  12 Ping              
  13 Information       
  14 File              
  15 Snoop Data         
  16 Command

You could use those to send some types of messages (eg. connection attempts) to the main world window, but other types to a notepad window.


name: ChatPeekConnections
prototype: long ChatPeekConnections(long ID);
summary: Sends a "peek connections" message to the specified chat user
vb_example: ChatPeekConnections ChatGetID ("nick")
java_example: ChatPeekConnections (ChatGetID ("nick"));
perl_example: ChatPeekConnections (ChatGetID ("nick"));
return_value: eChatIDNotFound: That chat ID is not currently connected. eOK: Peek message sent.
type_of_object: Method
see_also: ChatMessage ChatRequestConnections
python_example: world.ChatPeekConnections (world.ChatGetID ("nick"))
doc_name: chat
lua_example: ChatPeekConnections (ChatGetID ("nick"))
description:
Requests the specified chat user to send a list of its public connections. This is the same as doing this:

ChatMessage ID, 28, ""

The chat user who receives that will (should) respond with a list of their current chat connections that they have (excluding the connection to you), so you can see who else they are chatting with.

If you want to connect to those users automatically, use ChatRequestConnections.


name: ChatRequestConnections
prototype: long ChatRequestConnections(long ID);
summary: Sends a "request connections" message to the specified chat user
vb_example: ChatRequestConnectionsChatGetID ("nick")
java_example: ChatRequestConnections(ChatGetID ("nick"));
perl_example: ChatRequestConnections(ChatGetID ("nick"));
return_value: eChatIDNotFound: That chat ID is not currently connected. eOK: Request connections message sent.
type_of_object: Method
see_also: ChatMessage ChatPeekConnections
python_example: world.ChatRequestConnections(world.ChatGetID ("nick"))
doc_name: chat
lua_example: ChatRequestConnections(ChatGetID ("nick"))
description:
Requests the specified chat user to send a list of its public connections. This is the same as doing this:

ChatMessage ID, 2, ""

The chat user who receives that will (should) respond with a list of their current chat connections that they have (excluding the connection to you. MUSHclient will then try to connect to them directly (so that you can chat with them without having to go through the other person, for example, in case they disconnect).

If you want to see who those users are first, use ChatPeekConnections.


name: ChatPing
prototype: long ChatPing(long ID);
summary: Sends a ping message to the specified chat user
vb_example: ChatPing ChatGetID ("john")
java_example: ChatPing (ChatGetID ("john"));
perl_example: ChatPing (ChatGetID ("john"));
return_value: eChatIDNotFound: The chat ID was not connected. eOK: Ping message sent.
type_of_object: Method
see_also: ChatGetID ChatMessage
python_example: world.ChatPing (world.ChatGetID ("john"))
doc_name: chat
lua_example: ChatPing (ChatGetID ("john"))
description:
This sends a "ping request" chat message (26) (not an ICMP message) to the specified chat user. They should response by echoing the message back with a "ping response" message type (27).

MUSHclient makes a note of the time the ping message was sent, so that when the ping response arrives, it can work out how long the ping took for the round trip.


name: ChatSendFile
prototype: long ChatSendFile(long ID, BSTR FileName);
summary: Starts sending a file to the specified chat user
vb_example: ChatSendFile ChatGetID ("fred"), "" ' send a file that you choose
java_example: ChatSendFile (ChatGetID ("fred"), ""); // send a file that you choose
perl_example: ChatSendFile (ChatGetID ("fred"), ""); # send a file that you choose
type_of_object: Method
see_also: ChatStopFileTransfer GetChatInfo GetChatOption SetChatOption ChatGetID
python_example: world.ChatSendFile (world.ChatGetID ("fred"), "") # send a file that you choose
doc_name: chat
lua_example: ChatSendFile (ChatGetID ("fred")) -- send a file that you choose
lua_notes: The file name is optional. If omitted you will be prompted for one.
description:
This starts the process of sending a file to the specified chat ID. 

If the file name is empty, then you will be prompted with a "choose file" dialog box, so you can pick the file with the normal Window file browser.

If the file name is not empty, then MUSHclient will attempt to send that file.

The recipient of the file must have allowed file sending, or you will get an error message.

You cannot send more than one file at a time - you will get an error if you attempt to send a file whilst sending, or receiving, another one (to that user).

You can use GetChatInfo to see if a file transfer is in progres. 

You can use SetChatOption to set the "can_send_files" flag.

Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world. 

You can use GetChatList to find a list of chat IDs that is current.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

Note that an "OK" response merely means that we have sent a request to the other user to accept the file. There is no guarantee that s/he will want it.

return_value:
eChatIDNotFound: That chat ID is not connected
eAlreadyTransferringFile: Already transferring a file
eFileNotFound: That file not found, or user cancelled file picker dialog box
eOK: File transfer initiated


name: ChatStopFileTransfer
prototype: long ChatStopFileTransfer(long ID);
summary: Stops a file transfer in progress to that chat user
vb_example: ChatStopFileTransfer ChatGetID ("peter")
java_example: ChatStopFileTransfer (ChatGetID ("peter"));
perl_example: ChatStopFileTransfer (ChatGetID ("peter"));
type_of_object: Method
see_also: ChatGetID ChatSendFile GetChatInfo
python_example: world.ChatStopFileTransfer (world.ChatGetID ("peter"))
doc_name: chat
lua_example: ChatStopFileTransfer (ChatGetID ("peter"))
description:
If a file transfer is in progress (send or receive) it is aborted, and the user at the other end notified, if possible.

You can use GetChatInfo to see if a file transfer is in progress.

Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world. 

You can use GetChatList to find a list of chat IDs that is current.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

return_value:
eChatIDNotFound: That chat ID is not connected.
eNotTransferringFile: We are not transferring a file.
eOK: File transfer aborted.


name: ChatStopAcceptingCalls
prototype: void ChatStopAcceptingCalls();
summary: Stops this world from accepting chat calls
vb_example: ChatStopAcceptingCalls
java_example: ChatStopAcceptingCalls ();
perl_example: ChatStopAcceptingCalls ();
return_value: Nothing.
type_of_object: Method
see_also: ChatDisconnect ChatDisconnectAll ChatAcceptCalls GetChatList
python_example: world.ChatStopAcceptingCalls
doc_name: chat
lua_example: ChatStopAcceptingCalls ()
description:
Stops the world from accepting incoming chat calls. Existing calls are not affected. What this does is close the "listening" socket, so that the client no longer "hears" incoming calls.

Use ChatDisconnect or ChatDisconnectAll to disconnect existing calls.


name: GetChatInfo
prototype: VARIANT GetChatInfo(long ChatID, short InfoType);
summary: Get information about a chat connection
vb_example: Note "Version: " & GetChatInfo (id, 4)
java_example: Note ("Version: " + GetChatInfo (id, 4));
perl_example: Note ("Version: " . GetChatInfo (id, 4));
type_of_object: Method
see_also: GetChatOption SetChatOption ChatGetID
python_example: world.Note ("Version: " + str (world.GetChatInfo (id, 4)))
doc_name: chat
lua_example: Note ("Version: " .. GetChatInfo (id, 4))
description:
Gets details about the specified chat session.

You can obtain one of 41 "types" of information about the chat session by specifying an "InfoType". The possible InfoTypes are:

  1: Server name              
  2: User (ie. their chat name)
  3: Group name
  4: Client version             
  5: Call IP (address to call to get them)            
  6: Address (address they actually are)            
  7: Port    (incoming port)
  8: Call port (port to call them on)
  9: Status             
 10: Type   (0 = MudMaster protocol)             
 11: ID     (internal chat ID)             
 12: Incoming (true = they called us, false = we called them)            
 13: Can snoop flag           
 14: Snooping flag                      
 15: They are snooping us flag                     
 16: Send commands flag                  
 17: Private flag           
 18: Can send files flag                 
 19: Ignore them flag            
 20: Recent ping time         
 21: Started at time     
 22: Last message in time      
 23: Last message out time
 24: Started file transfer time        
 25: We are transferring a file flag           
 26: File transfer is a send (false = receive)
 27: File name being transferred           
 28: Full file path (on our disk)      
 29: File size bytes      
 30: File blocks          
 31: Blocks already transferred      
 32: Block size 
 33: Incoming personal count  
 34: Incoming all count         
 35: Incoming group count       
 36: Outgoing personal count    
 37: Outgoing all count         
 38: Outgoing group count       
 39: Messages count             
 40: File xfer bytes in count   
 41: File xfer bytes out count
 42: zChat stamp ID
 43: Email address (from zChat)
 44: PGP key (from zChat) - not used by MUSHclient
 45: Status number (from zChat)
 46: User option value (long)

return_value:
The specified information about the chat session, as described above.
A NULL variant if the chat session does not exist.
An EMPTY variant if the InfoType is not a valid type.


name: GetChatList
prototype: VARIANT GetChatList();
summary: Gets the list of chat sessions
type_of_object: Method
doc_name: chat
lua_example: for k, v in pairs (GetChatList ()) do Note (v) end
description:
Returns an array of all the chat sessions which are currently connected. You can then use various "chat" routines to do something with that list.

vb_example:
dim chatList

chatList = GetChatList

If Not IsEmpty (chatList) then

  For Each c In chatList
    Note c & " = " & GetChatInfo (c, 2)
  Next

End If

java_example:
chatList = new VBArray(GetChatList()).toArray();

if (chatList)  // if not empty
 for (i = 0; i < chatList.length; i++)
   world.note(chatList [i] + " = " + GetChatInfo (chatList [i], 2));

perl_example:
foreach $item (Win32::OLE::in ($world->GetChatList))
 {
 Note($item . " = " . GetChatInfo ($item, 2));
 }

return_value:
If there are no chat sessions then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the IDs of all the chat sessions. Use "ubound" to find the number of chat sessions in the list. You can then use "GetChatInfo" to find details about each session. See the example for how to do this. You can paste this example into an "Immediate" window (CTRL+I) to test it.

see_also:
ChatDisconnect ChatEverybody ChatPasteEverybody ChatPersonal ChatGroup ChatID ChatPersonal ChatMessage ChatPeekConnections ChatPing ChatRequestConnections ChatSendFile ChatStopFileTransfer GetChatInfo GetChatOption SetChatOption

python_example:
chatList = world.GetChatList
if (chatList ):
  for c in chatList : world.Note (str (c) + " = " + 
              world.GetChatInfo (c, 2))


name: GetChatOption
prototype: VARIANT GetChatOption(long ID, BSTR OptionName);
summary: Gets the value of a chat session option
vb_example: Note GetChatOption (ChatGetID ("nick"), "group")
java_example: Note (GetChatOption (ChatGetID ("nick"), "group"));
perl_example: Note (GetChatOption (ChatGetID ("nick"), "group"));
return_value: As described above.
type_of_object: Method
see_also: GetChatInfo GetChatOption SetChatOption ChatGetID GetChatList
python_example: world.Note (world.GetChatOption (world.ChatGetID ("nick"), "group"))
doc_name: chat
lua_example: Note (GetChatOption (ChatGetID ("nick"), "group"))
description:
Gets the current value of a chat session option.

You must specify the identifier of a current chat session, and a chat option from the list below. 

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the chat session does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

OPTION NAMES

"address" - TCP/IP address of remote user (address to call them)
"can_send_commands" - can that user send us commands?
"can_send_files" - can that user send us files?
"can_snoop" - can that user snoop on our session?
"group" - their group name
"ignore" - ignore them?
"private" - private session?
"served" - incoming call?
"server" - TCP/IP address of remote user
"user" - user value (for scripting, is not used by MUSHclient)
"username" - their chat name
"version" - what version client they are using


name: SetChatOption
prototype: long SetChatOption(long ID, BSTR OptionName, BSTR Value);
summary: Sets the value of a chat session option
vb_example: SetChatOption ChatGetID ("nick"), "group", "friends"
java_example: SetChatOption (ChatGetID ("nick"), "group", "friends");
perl_example: SetChatOption (ChatGetID ("nick"), "group", "friends");
type_of_object: Method
see_also: GetChatInfo GetChatOption GetChatOption ChatGetID GetChatList
python_example: world.SetChatOption (world.ChatGetID ("nick"), "group", "friends")
doc_name: chat
lua_example: SetChatOption (ChatGetID ("nick"), "group", "friends")
lua_notes: You can use true or false for boolean options, as these are converted to 1 or 0.
description:
Sets the current value of a chat session option.

You must specify the identifier of a current chat session, and a chat option from the list described for the routine GetChatOption. 

For numeric options (such as the flags) the supplied string will be converted to a number. It is an error if the string does not consist of digits (0 to 9). 

For boolean options (such as "ignore") the supplied string may be:

"y", "Y", or "1" for true
"n", "N", or "0" for false

Also if you are using Lua you can supply simply true or false.


Note that because chat sessions are transitory the option is not remembered in the world file or anywhere else for future sessions. Thus, any options must be set on a per-session basis.

See the supplied Chat.xml plugin for an example of how you can do that automatically as a new session is started.

return_value:
eChatIDNotFound: That chat ID is not a current chat session.
eOptionOutOfRange: The numeric option is out of range.
ePluginCannotSetOption: The option is marked as non-settable (in a plugin or not)
eUnknownOption: Option name is not known.
eOK: Set the option OK.


name: StripANSI
prototype: BSTR StripANSI(BSTR Message);
summary: Strips ANSI colour sequences from a string
vb_example: Note StripANSI (incoming_message)
java_example: Note (StripANSI (incoming_message));
perl_example: Note (StripANSI (incoming_message));
return_value: The supplied string with ANSI colour sequences removed.
type_of_object: Method
see_also: ANSI ChatMessage Note
python_example: world.Note (StripANSI (world.incoming_message))
doc_name: utils
lua_example: Note (StripANSI (incoming_message))
description:
This removes ANSI colour sequences from a string.

The intention of this routine is to be used with incoming chat messages (which may have ANSI colour codes in them), if you want to display them in a plain colour, or reformat using your own colours.


name: GetWorldIdList
prototype: VARIANT GetWorldIdList();
summary: Gets the list of open worlds - returning their world IDs
vb_example: for each id in world.GetWorldIdList world.note id next
perl_example: foreach $item (Win32::OLE::in ($world->GetWorldIdList)) { Note ($item); }
type_of_object: Method
see_also: GetWorldById GetWorldList
python_example: worldlist = world.GetworldIdList if (worldlist ): for w in worldlist : world.Note (w)
doc_name: world
lua_notes: See the description for GetWorld for more discussion about using "world" variables in Lua.
description:
Returns a variant array which is a list of the identifiers (IDs) of all open worlds.

This is safer than using GetWorldList because multiple worlds might have the same name.

java_example:
worldlist = new VBArray(world.GetworldIdList()).toArray();

if (worldlist)  // if not empty
 for (i = 0; i < worldlist.length; i++)
   Note (worldlist [i]);

return_value:
If there are no worlds then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the Ids of all the worlds. Use "ubound" to find the number of worlds in the list. You can then use "GetWorldById" to return a reference to that world.

lua_example:
-- --------------------------------------------------
-- Example showing sending a message all worlds
-- --------------------------------------------------

function SendToAllWorlds (message)

  for k, v in pairs (GetWorldIdList ()) do 
    GetWorldById (v):Send (message)
  end
end

SendToAllWorlds ("say Hi there")


name: GetWorldById
prototype: IDispatch* GetWorldById(BSTR WorldID);
summary: Gets an object reference to the world given its unique ID
type_of_object: Method
see_also: GetWorldIdList Open GetWorld
doc_name: world
lua_notes: See the description for GetWorld for more discussion about using "world" variables in Lua.
description:
Returns an object which can be used to refer to another world.

You should be very cautious about storing the object reference of the world in a global variable, because if the world is closed then that reference becomes invalid, which will very likely lead to an access violation (program crash). You are better off using "world.getworldbyid (id)" every time you need to get a reference to the world, and checking if it "is nothing" as in the example.

This does not apply to Lua which checks the world object every time it is used.

You could use a small variation on the examples above to write your own "send to all worlds" or something similar.

vb_example:
' --------------------------------------------------
' Example showing sending a message to all worlds
' --------------------------------------------------

sub SendToAllWorlds (message)

dim otherworld

for each id in GetWorldIdList
  set otherworld = GetWorldById (id)
  otherworld.Send message
  set otherworld = nothing
next

end sub

SendToAllWorlds "sigh"

java_example:
// --------------------------------------------------
// Example showing sending a message all worlds
// --------------------------------------------------

function SendToAllWorlds (message)
{
 worldlist = new VBArray(GetWorldIdList()).toArray();

 if (worldlist)  // if not empty
  for (i = 0; i < worldlist.length; i++)
    GetWorldByID (worldlist [i]).Send (message);

}

SendToAllWorlds ("say Hi there");

perl_example:
# --------------------------------------------------
# Example showing sending a message to another world
# --------------------------------------------------

sub SendToAllWorlds {
 my ($message) = @_;

 my $otherworld;

 foreach $item (Win32::OLE::in ($world->GetWorldIdList))
 {
 GetWorldById ($item)->Send ($message);
 }

}

SendToAllWorlds ("say Hi there");

return_value:
An object reference to the named world, if it was found.
Otherwise NULL.

In Vbscript use the test "is nothing" to see if the reference is to a valid world.
In JavaScript use the test "== null" to see if the reference is to a valid world.
In PerlScript use the test "defined ()" to see if the reference is to a valid world.
In Lua use the test "if ref == nil" to see if the reference is to a valid world.

python_example:
# --------------------------------------------------
# Example showing sending a message all worlds
# --------------------------------------------------

def SendToAllWorlds (message):
  worldlist = world.GetWorldIdList
  if (worldlist):
    for w in worldlist : world.GetWorldByID (w).Send (message)

SendToAllWorlds ("say Hi there")

lua_example:
-- --------------------------------------------------
-- Example showing sending a message all worlds
-- --------------------------------------------------

function SendToAllWorlds (message)

  for k, v in pairs (GetWorldIdList ()) do 
    GetWorldById (v):Send (message)
  end
end

SendToAllWorlds ("say Hi there")


name: GetHostAddress
prototype: VARIANT GetHostAddress(BSTR HostName);
summary: Returns a list of IP addresses that correspond to a host name on the Internet
vb_example: For Each ip In GetHostAddress ("www.netscape.com") Note ip Next
perl_example: foreach $item (Win32::OLE::in ($world->GetHostAddress ("www.netscape.com"))) { Note ($item); }
type_of_object: Method
see_also: GetHostName
doc_name: info
lua_example: for k, v in pairs (GetHostAddress ("www.netscape.com")) do Note (v) end
description:
Returns a variant array which is a list of all the TCP/IP addresses which correspond to a given IP address, using DNS (Domain Name Server).

Warning - because this function has to connect to a DNS server and await a response it may take some time to execute, perhaps 20 seconds or more.

It should not be used in a script where speed is the essence, or which is executed frequently. If you need to know the answer multiple times you should "cache" the result for future use.

The intended purpose is to relate an address in the chat system (eg. during the connection phase) to a domain name.

The reason an array is returned is because a single name might have multiple hosts (eg. Microsoft, Netscape) so a list of all of them is returned.

java_example:
iplist = new VBArray(world.GetHostAddress ("www.netscape.com")).toArray();

if (iplist)  // if not empty
 for (i = 0; i < iplist.length; i++)
   Note (iplist [i]);

return_value:
If there were no addresses returned then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the IP addresses for this domain name. Use "ubound" to find the number of addresses in the list.

python_example:
iplist = world.GetHostAddress ("www.netscape.com")
if (iplist ):
  for ip in iplist : world.Note (ip)


name: GetHostName
prototype: BSTR GetHostName(BSTR IPaddress);
summary: Returns the host name that corresponds to an IP address on the Internet
vb_example: Note GetHostName ("66.36.226.56")
java_example: Note (GetHostName ("66.36.226.56"));
perl_example: Note (GetHostName ("66.36.226.56"));
return_value: Name corresponding to the supplied IP address, or an empty string if it could not be determined.
type_of_object: Method
see_also: GetHostAddress
python_example: world.Note (world.GetHostName ("66.36.226.56"))
doc_name: info
lua_example: Note (GetHostName ("66.36.226.56"))
description:
This returns the name of the host which has a specified IP address, using DNS (Domain Name Server).

Warning - because this function has to connect to a DNS server and await a response it may take some time to execute, perhaps 20 seconds or more.

It should not be used in a script where speed is the essence, or which is executed frequently. If you need to know the answer multiple times you should "cache" the result for future use.

The address should be supplied as a "dotted decimal" string, like "66.36.226.56".


name: GetClipboard
prototype: BSTR GetClipboard();
summary: Gets the clipboard contents
vb_example: Note GetClipboard
java_example: Note (GetClipboard ());
perl_example: Note (GetClipboard ());
return_value: The clipboard contents, of an empty string if the clipboard does not contain text.
type_of_object: Method
see_also: SetClipboard
python_example: world.Note (world.GetClipboard)
doc_name: utils
lua_example: Note (GetClipboard ())
description:
Returns the clipboard contents, if the clipboard contains straight text. If there is no text on the clipboard, it returns the empty string.


name: ImportXML
prototype: long ImportXML(BSTR XML);
summary: Imports configuration data in XML format
type_of_object: Method
see_also: SetOption SetAlphaOption AddTrigger AddAlias AddTimer ExportXML
doc_name: utils
lua_notes: A useful trick in Lua is to use multiple-line constants, as illustrated above.
description:
This duplicates the functionality in the File menu -> Import -> Clipboard.

It allows you to import one or more triggers, aliases, macros, timers, variables, colours, numeric keypad configuration items.

The two things you cannot import here are general world configuration (use SetOption and SetAlphaOption for that), and plugins.

The XML text should start with one of the following, or -1 will be returned:

<?xml
<!--
<!DOCTYPE
<muclient
<world
<triggers
<aliases
<timers
<macros
<variables
<colours
<keypad
<printing
<comment
<include
<plugin
<script


In other words, to import a trigger you should start with <triggers>. You can import more than one type of thing, eg. 

<triggers> ... </triggers> <aliases> ... </aliases>


The syntax is exactly the same as used in the world file, or if you copy a trigger/alias/timers/variable to the clipboard from the world configuration screens.

If there is a parsing error (eg. bad XML format, like unterminated element, or unknown option for an item) then a text window will open with the error description shown. Also, the function will return -2.

If there is no parsing error then the function will return the number of items imported, which might be zero if the syntax was OK, but nothing was actually added, eg. "<triggers></triggers>" would parse OK but not add anything.

If you copy triggers etc. from the world configuration then you will need to "double" the quotes (or escape them appropriately) as you will probably have quotes within quotes. See the examples below for more details.

Note that duplicate items are replaced by ImportXML - so if you already have a trigger / alias / timer of the same name, it will be replaced.

vb_example:
ImportXML _
  "<timers>" & _
  "<timer name=""mylabel"" script=""timerscript"" enabled=""y"" hour=""16"" at_time=""y"" >" & _
  "</timer>" &_
  "</timers>"

java_example:
ImportXML (
  "<timers>" +
  "<timer name="mylabel" script="timerscript" enabled="y" hour="16" at_time="y" >" +
  "</timer>" +
  "</timers>");

perl_example:
ImportXML (
  "<timers>" .
  "<timer name="mylabel" script="timerscript" enabled="y" hour="16" at_time="y" >" .
  "</timer>" .
  "</timers>");

return_value:
-1 : not XML format - failed initial check
-2 : error parsing XML - see error window
0 or more: count of items imported

python_example:
world.ImportXML (
  "<timers>" +
  "<timer name="mylabel" script="timerscript" enabled="y" hour="16" at_time="y" >" +
  "</timer>" +
  "</timers>")

lua_example:
ImportXML
[[
<timers>
  <timer name="mytimer" 
         enabled="y" 
         minute="10" 
         group="battle" >
  <send>sigh</send>
  </timer>
</timers>
]]


name: GetInternalCommandsList
prototype: VARIANT GetInternalCommandsList();
summary: Returns a list of the internal MUSHclient command names
vb_example: For Each command In GetInternalCommandsList world.Note command Next
perl_example: foreach $item (Win32::OLE::in ($world->GetInternalCommandsList())) { $world->note($item); }
type_of_object: Method
see_also: DoCommand
python_example: for c in world.GetInternalCommandsList : world.Note (c)
doc_name: info
lua_example: for k, v in pairs (GetInternalCommandsList ()) do Note (v) end
description:
This returns a variant array of the internal MUSHclient command names. You can use any name in this list in the DoCommand function. You can also use:

/world.Debug "internal_commands" 

to see the list shown in the output window.

java_example:
commandList = new VBArray(world.GetInternalCommandsList ()).toArray();
  for (i = 0; i < commandList.length; i++)
      Note (commandList [i]);

return_value:
It returns a variant array containing the names of the internal MUSHclient commands. Use "ubound" to find the number of commands in the list.


name: DoCommand
prototype: long DoCommand(BSTR Command);
summary: Queues a MUSHclient menu command
vb_example: DoCommand "WindowsSocketInformation" DoCommand "FullScreenMode"
java_example: DoCommand ("WindowsSocketInformation"); DoCommand ("FullScreenMode");
perl_example: DoCommand ("WindowsSocketInformation"); DoCommand ("FullScreenMode");
type_of_object: Method
see_also: GetInternalCommandsList
python_example: world.DoCommand ("WindowsSocketInformation") world.DoCommand ("FullScreenMode")
lua_example: DoCommand ("WindowsSocketInformation") DoCommand ("FullScreenMode")
description:
Queues an internal MUSHclient command, as if you had selected it from the menu or typed the corresponding keyboard accelerator. This lets you script things that are available from menus but might not be provided for directly in the scripting language (eg. connect to worlds in startup list). 

The command is actually entered in the Windows message queue using the PostMessage operating-system call. What this means is that the command you specify is not done immediately, but will be actioned next time through the main "message loop".

The reason for this is that some commands (eg. world.DoCommand "close", or world.DoCommand "ExitClient") would crash the client because the program (or window) would close while the script was still executing. Similarly any command that opened a dialog box would mean that the script would be paused until the dialog box was closed.

That means that this sort of thing will *not* work:

world.DoCommand "copy"
mystring = world.GetClipboard

This is because the copy command is deferred until later, whereas the GetClipboard is executed immediately (as it is an inbuilt script command).

The intention of DoCommand is that you can bind aliases to internal commands, or automate some actions, but not to directly execute MUSHclient actions while a script is running. For instance, you might make an alias:

Alias: #chats
Send:  DoCommand "chatsessions"
Send to: Script

To find the current list of commands you can use:

/world.Debug "internal_commands"

Also see world.GetInternalCommandsList to get the list in a script.

The current list is (as at version 3.73):

ASCIIart, About, ActivateInputArea, ActivityList, ActivityToolbar, 
ActivityViewCloseWorld, ActivityViewSaveWorld, ActivityViewSaveWorldAs, AltA, 
AltB, AltDownArrow, AltJ, AltK, AltL, AltM, AltN, AltO, AltP, AltQ, AltR, 
AltS, AltT, AltU, AltUpArrow, AltV, AltX, AltY, AltZ, AlwaysOnTop, 
ArrangeIcons, AutoConnect, AutoSay, Base64Decode, Base64Encode, 
BookmarkSelection, BugReports, CascadeWindows, ChatSessions, 
ClearCommandHistory, ClearOutput, Close, CloseAllNotepadWindows, ColourPicker, 
CommandEnd, CommandHistory, CommandHome, CompleteFunction, ConfigureAliases, 
ConfigureAutosay, ConfigureChat, ConfigureColours, ConfigureCommands, 
ConfigureCustomColours, ConfigureKeypad, ConfigureLogging, ConfigureMacros, 
ConfigureMudaddress, ConfigureMxpPueblo, ConfigureNameAndPassword, 
ConfigureNotes, ConfigureOutput, ConfigurePasteToWorld, ConfigurePrinting, 
ConfigureScripting, ConfigureSendFile, ConfigureTimers, ConfigureTriggers, 
ConfigureVariables, Connect, ConnectToAllOpenWorlds, 
ConnectToWorldsInStartupList, Connect_Or_Reconnect, ContextHelp, 
ConvertHTMLspecial, Copy, CopyAsHTML, CtrlKeypad0, CtrlKeypad1, CtrlKeypad2, 
CtrlKeypad3, CtrlKeypad4, CtrlKeypad5, CtrlKeypad6, CtrlKeypad7, CtrlKeypad8, 
CtrlKeypad9, CtrlKeypadDash, CtrlKeypadDot, CtrlKeypadPlus, CtrlKeypadSlash, 
CtrlKeypadStar, CtrlN, CtrlP, CtrlZ, Cut, DebugIncomingPackets, 
DebugWorldInput, DiscardQueuedCommands, Disconnect, DoMapperComment, 
DoMapperSpecial, DosToMac, DosToUnix, East, EditScriptFile, End, Examine, 
ExitClient, Find, FindAgain, FindNextNotepad, FindNotepad, FlipToNotepad, 
Forum, FreezeOutput, FullScreenMode, FunctionList, FunctionsWebPage, 
GenerateCharacterName, GenerateUniqueID, GettingStarted, GlobalPreferences, 
GlobalReplace, GoToBookmark, GoToLine, GoToMatchingBrace, GoToNotepadLine, 
GoToURL, Help, HelpContents, HelpIndex, HighlightWord, Immediate, Import, 
Info, InfoBar, InputGlobalChange, InsertDateTime, Keypad0, Keypad1, Keypad2, 
Keypad3, Keypad4, Keypad5, Keypad6, Keypad7, Keypad8, Keypad9, KeypadDash, 
KeypadDot, KeypadPlus, KeypadSlash, KeypadStar, KeysEscape, KeysTab, LineDown, 
LineUp, LogSession, Look, LowerCase, MacToDos, MacroCtrlF1, MacroCtrlF10, 
MacroCtrlF11, MacroCtrlF12, MacroCtrlF2, MacroCtrlF3, MacroCtrlF5, MacroCtrlF
6, MacroCtrlF7, MacroCtrlF8, MacroCtrlF9, MacroF1, MacroF10, MacroF11, MacroF
12, MacroF2, MacroF3, MacroF4, MacroF5, MacroF6, MacroF7, MacroF8, MacroF9, 
MacroShiftF1, MacroShiftF10, MacroShiftF11, MacroShiftF12, MacroShiftF2, 
MacroShiftF3, MacroShiftF4, MacroShiftF5, MacroShiftF6, MacroShiftF7, 
MacroShiftF8, MacroShiftF9, MakeMultiLineTrigger, Mapper, Maximize, MinimiseProgram, 
Minimize, MudLists, New, NewWindow, NextCommand, NextPane, NoCommandEcho, 
North, NotesWorkArea, Open, OpenWorldsInStartupList, PageDown, Pageup, Paste, 
PasteFile, PasteToMush, PluginWizard, Plugins, Preferences, PreviousCommand, 
Print, PrintNotepad, PrintPreview, PrintSetup, QuickConnect, Quit, 
QuoteForumCodes, QuoteLines, RecallText, ReconnectOnDisconnect, 
RefreshRecalledData, Register, ReloadDefaults, ReloadNamesFile, 
ReloadScriptFile, RemoveBlanks, RepeatLastCommand, RepeatLastWord, 
ReplaceNotepad, ResetAllTimers, ResetToolbars, Restore, Save, SaveAs, SaveSelection, 
SelectAll, SelectMatchingBrace, SendMailTo, SendToAllWorlds, 
SendToCommandWindow, SendToScript, SendToWorld, South, SpellCheck, Start, 
StopSoundPlaying, Take, TextAttributes, TileWindows, TileWindowsVertically, 
TipOfTheDay, Trace, UnconvertHTMLspecial, Undo, UnixToDos, Up, UpperCase, 
UsingHelp, ViewStatusbar, ViewToolbar, ViewWorldToolbar, WebPage, West, 
Whisper, WindowsSocketInformation, WordCount, World1, World10, World2, World3, 
World4, World5, World6, World7, World8, World9, WrapLines, WrapOutput

return_value:
eNoSuchCommand: That command name was not recognised
eOK: Did the command (or attempted to do it)

Note that even if eOK (0) is returned, the command will not necessarily successfully execute. For example, DoCommand "WordCount" would not do anything if a "world" window was active, rather than a notepad window.


name: ChatCallzChat
prototype: long ChatCallzChat(BSTR Server, long Port);
summary: Calls a zChat chat server (makes an outgoing call)
type_of_object: Method
see_also: ChatAcceptCalls ChatDisconnect ChatDisconnectAll ChatStopAcceptingCalls ChatCall
doc_name: chat
lua_notes: The Port argument is optional. If omitted it defaults to 4050.
description:
Attempts to establish a chat call to another client using the zChat protocol. 

Use ChatCall to call using the MudMaster chat protocol.

You specify the TCP/IP address and the port number. If the port number is zero the default chat port of 4050 is used.

Because of the asynchronous nature of TCP/IP a "good" status from this call does not necessarily mean you will establish a chat session, it just means it has succeeded in starting the process.

In order to establish a chat session, MUSHclient must:

1. Look up the name using the Domain Name Server (DNS) unless a dotted-decimal name was given - this may take a few seconds.
2. Connect to the chat server - this may take a few more seconds
3. Attempt to negotiate a chat session by sending "ZCHAT:" to the chat server
4. Await a response - this may take a while if the player at the other end is deciding whether to accept the connection or not.
5. Finally, if all goes well, the chat session is established.

To know if the session was really established you need to use the plugin callback routine "OnPluginChatNewUser" - this notifies you when a new user is established.

vb_example:
ChatCallzChat "123.45.67.89", 0     ' call on default port
ChatCallzChat "123.45.67.89", 4060  ' call on port 4060
ChatCallzChat "myfriend.hisdomain.com", 0    ' call on default port using name

java_example:
ChatCallzChat ("123.45.67.89", 0);     // call on default port
ChatCallzChat ("123.45.67.89", 4060);  // call on port 4060
ChatCallzChat ("myfriend.hisdomain.com", 0);    // call on default port using name

perl_example:
ChatCallzChat ("123.45.67.89", 0);     # call on default port
ChatCallzChat ("123.45.67.89", 4060);  # call on port 4060
ChatCallzChat ("myfriend.hisdomain.com", 0);    # call on default port using name

return_value:
eCannotCreateChatSocket: Cannot start call - perhaps all sockets are in use?
eCannotLookupDomainName: Cannot start looking up domain name
eOK: Call process started OK

python_example:
world.ChatCallzChat ("123.45.67.89", 0)     # call on default port
world.ChatCallzChat ("123.45.67.89", 4060)  # call on port 4060
world.ChatCallzChat ("myfriend.hisdomain.com", 0)    # call on default port using name

lua_example:
ChatCallzChat ("123.45.67.89")     -- call on default port
ChatCallzChat ("123.45.67.89", 4060)  -- call on port 4060
ChatCallzChat ("myfriend.hisdomain.com")    -- call on default port using name


name: GetNotepadLength
prototype: long GetNotepadLength(BSTR Title);
summary: Gets the length of the text in a notepad window
vb_example: world.Note world.GetNotepadLength ("mynotes")
java_example: world.Note (world.GetNotepadLength ("mynotes"));
perl_example: Note (GetNotepadLength ("mynotes"));
type_of_object: Method
python_example: world.Note (str (world.GetNotepadLength ("mynotes")));
doc_name: notepad
lua_example: Note (GetNotepadLength ("mynotes"))
description:
Find the length of the text in the specified notepad window.

If a notepad of that name does not exist a length of zero is returned.

return_value:
The length of the text in the specified notepad, in characters.

If that notepad does not exist, zero is returned.

see_also:
SendToNotepad ActivateNotepad Activate AppendToNotepad CloseNotepad SaveNotepad ReplaceNotepad GetNotepadText GetNotepadList


name: GetNotepadText
prototype: BSTR GetNotepadText(BSTR Title);
summary: Gets the text from a notepad window
vb_example: world.Note world.GetNotepadText("mynotes")
java_example: world.Note (world.GetNotepadText ("mynotes"));
perl_example: Note (GetNotepadText ("mynotes"));
type_of_object: Method
python_example: world.Note (world.GetNotepadText ("mynotes"))
doc_name: notepad
lua_example: Note (GetNotepadText ("mynotes"))
description:
Returns the text from the specified notepad window.

If a notepad of that name does not exist an empty string is returned.

return_value:
The text from the specified notepad window.

If that notepad does not exist, an empty string is returned.

see_also:
SendToNotepad ActivateNotepad Activate AppendToNotepad CloseNotepad SaveNotepad ReplaceNotepad GetNotepadLength GetNotepadList


name: SendImmediate
prototype: long SendImmediate(BSTR Message);
summary: Sends a message to the MUD immediately, bypassing the speedwalk queue
vb_example: world.SendImmediate "go north"
java_example: world.SendImmediate("go north");
perl_example: $world->SendImmediate("go north");
type_of_object: Method
see_also: Note LogSend SendPush Execute Send Queue SendSpecial
python_example: world.SendImmediate("go north")
doc_name: send
lua_example: SendImmediate ("go north")
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
This sends the specified text to the world. It is like typing it into the command window. If there is a queue of commands in the speedwalk queue, this command "jumps the queue" - that is, it gets sent immediately.

The intention here is to use it for commands (like "say", "tell") that are not dependent on a speedwalk sequence finishing.

The command is not saved in the command history buffer nor is it logged.


name: AdjustColour
prototype: long AdjustColour(long Colour, short Method);
summary: Adjust an RGB colour
vb_example: mycolour = world.AdjustColour (ColourNameToRGB ("red"), 1) ' get inverse of red
java_example: mycolour = AdjustColour (ColourNameToRGB ("red"), 1); // get inverse of red
perl_example: mycolour = AdjustColour (ColourNameToRGB ("red"), 1); # get inverse of red
return_value: The RGB code of the adjusted colour. If the method is out of range the original colour is returned.
type_of_object: Method
see_also: ColourNameToRGB NoteColourRGB RGBColourToName PickColour
python_example: mycolour = world.AdjustColour (world.ColourNameToRGB ("red"), 1) # get inverse of red
doc_name: colours
lua_example: mycolour = AdjustColour (ColourNameToRGB ("red"), 1) -- get inverse of red
description:
This lets you play with colours in a script. You pass to it a colour and an adjustment method. The methods are:

1: invert
2: lighter
3: darker
4: less colour
5: more colour

This lets you do in a script what can be done on the ANSI colour page - fiddle with colour values.


name: SendNoEcho
prototype: long SendNoEcho(BSTR Message);
summary: Sends a message to the MUD without echoing in the output window
vb_example: world.SendNoEcho "go north"
java_example: world.SendNoEcho("go north");
perl_example: $world->SendNoEcho("go north");
type_of_object: Method
see_also: Note LogSend SendPush Execute SendImmediate Queue Send SendSpecial
python_example: world.SendNoEcho ("go north")
doc_name: send
lua_example: SendNoEcho("go north")
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
This sends the specified text to the world. It is like typing it into the command window. The command is not echoed in the output window.

A newline character is appended to the text you supply, as MUD commands normally are terminated with a newline.

The text may include imbedded newlines. 

If the text has a trailing newline it is removed. In other words, text with a trailing newline will not end up with two newlines when sent to the MUD.

The command is not saved in the command history buffer (use SendPush if you want to save it).


name: ExportXML
prototype: BSTR ExportXML(short Type, BSTR Name);
summary: Exports a world item in XML format
vb_example: world.Note world.ExportXML (0, "mytrigger")
java_example: world.Note (world.ExportXML (0, "mytrigger"));
perl_example: Note (ExportXML (0, "mytrigger"));
type_of_object: Method
see_also: ImportXML
python_example: world.Note (world.ExportXML (0, "mytrigger"));
doc_name: utils
lua_example: Note (ExportXML (0, "mytrigger"))
description:
This lets you export one trigger, timer, alias, macro, keypad item or variable in XML format. This is symmetrical with the ImportXML function - a trigger exported with ExportXML will be syntactically correct for importing with ImportXML. However, it may not actually import if, say, there is a clash where two triggers both have the same label. 

This would let you send triggers etc. from one world to another in an automated way, or from one client to another if you built some chat scripting around these functions.

The various types of things are numbered:

0 = trigger
1 = alias
2 = timer
3 = macro
4 = variable
5 = keypad

return_value:
The XML text of the nominated item. If the "type" is not valid, or the item cannot be found, then the return value is the empty string.


name: Hyperlink
prototype: void Hyperlink(BSTR Action, BSTR Text, BSTR Hint, BSTR TextColour, BSTR BackColour, BOOL URL);
summary: Creates a hyperlink in the output window
vb_example: world.Hyperlink "#chats", "Chat sessions", "Active chat sessions", "blue", "green", 0
java_example: Hyperlink ("#chats", "Chat sessions", "Active chat sessions", "blue", "green", 0);
perl_example: Hyperlink ("#chats", "Chat sessions", "Active chat sessions", "blue", "green", 0);
return_value: Nothing.
type_of_object: Method
see_also: Note ColourNote ColourTell CallPlugin
python_example: world.Hyperlink ("#chats", "Chat sessions", "Active chat sessions", "blue", "green", 0)
doc_name: note
lua_example: Hyperlink ("#chats", "Chat sessions", "Active chat sessions", "blue", "green", 0)
description:
This lets you add a hyperlink to your output window (like a world.ColourTell). Because it is like a ColourTell you can precede or follow it by other text (by using ColourTell). Also, as it is like a ColourTell you should eventually wrap up the line with a Note or similar to "end the line".

You can specify:

* An action (what is done) - this is what gets sent. If URL is true it is sent to your web browser, otherwise it is sent to "Execute", that is the MUSHclient command processor.

  eg.  "north", "http://www.gammon.com.au/"

* Link text (what the player sees, underlined)

  eg. "go north", "Gammon Solutions web site"

* A hint (what appears if the mouse hovers over the hyperlink).

  If empty, defaults to the action.

  eg. "click to go north" 

* A foreground colour

  The text colour. If empty, defaults to the note text colour.
  eg. "blue"

* A background colour. If empty, defaults to the note background colour.

  eg. "black"

* Whether it is a URL or not - if not, the action is executed like a command, otherwise it is sent to your web browser.
  
  If false, the action gets sent to the MUSHclient command parser, so it can be a simple command (eg. "eat food"), an alias (eg. "#chats"), a script (eg. '/world.note "hello" '), or a speedwalk.

  If true, the action must start with "http://", "https://", or "mailto:" and if so, it is sent to the web browser.

From version 3.42 you can also call a script in a plugin from a Hyperlink:

The hyperlink "action" text has a special case, that if it is in this format:

!!pluginID:sub(arg)

... then the sub "sub" in the plugin with that ID will be called, passing the argument "arg" (as a string).

For example:

world.Hyperlink "!!01245a24e83abd8552058478:nicktest(sigh)", "My test", "Click for my test", "yellow", "green", 0

In the example above we have:

Plugin ID = 01245a24e83abd8552058478
Sub to call = nicktest
Argument = sigh

Inside that plugin you might have a sub like this:

Sub nicktest (arg)
  Note arg
End Sub

Note that the brackets are required, so you would need: "sub()" if you wanted to pass no particular argument to the sub.

The argument will be passed as a string, so you don't need to quote it. It doesn't particularly matter if the argument contains brackets, as the processing of the argument simply starts at the first bracket, discards the last bracket, and sends everything inbetween (even if they are brackets).

For example:

world.Hyperlink "!!01245a24e83abd8552058478:nicktest(You say (hello))", "My test", "Click for my test", "yellow", "green", 0

The plugin is called using world.CallPlugin - see its description for more details.

Normally if you were using this inside a plugin, the plugin would find its own plugin ID, and then use that to generate the appropriate hyperlinks. eg. Inside a plugin you might do this:

world.Hyperlink "!!" & world.GetPluginID & ":mysub(North)", "Go North", "Click to go north", "yellow", "green", 0

... elsewhere in the plugin ...

Sub mysub (arg)
  Send arg
End Sub

------------------

WARNING!

Do not use the Hyperlink function in a script called by "sendto:script" from a trigger, if that trigger omits from output. The mechanism for preserving the "noted" output does not preserve hyperlinks. Use "sendto:script (after omit") instead.

lua_notes:
Lua has a 7th optional argument: NoUnderline.

If true, the hyperlink is not underlined. It defaults to false.


name: NoteStyle
prototype: void NoteStyle(short Style);
summary: Sets the style for notes
vb_example: NoteStyle 5 ' bold italic Note "hello"
java_example: NoteStyle (5); // bold italic Note ("hello");
perl_example: NoteStyle (5) # bold italic Note ("hello")
return_value: Nothing.
type_of_object: Method
see_also: GetNoteStyle Note Tell ColourNote ColourTell AnsiNote
python_example: NoteStyle (5) # bold italic Note ("hello")
doc_name: note
lua_example: NoteStyle (5) -- bold italic Note ("hello")
description:
This sets the text style for world.note and similar functions.

The styles are 1 bit each, which can be added or OR'ed together.

The style bits are:

  1 = bold
  2 = underline
  4 = blink (italic)
  8 = inverse
 32 = strike-through

Therefore:

NoteStyle (0) resets to normal style.

NoteStyle (1) would be bold.

NoteStyle (3) would be bold and underlined.


Styles are reset to normal when a newline is processed, so if you want to have bold/italic etc. over multiple lines you would need to do the NoteStyle at the start of each line.

You can also use AnsiNote to output styled text.

WARNING: Bold italic, and underlined styles will only be visible if the appropriate configurations are enabled in the world Appearance: Output configuration. Otherwise they will be ignored (the same as for text arriving from the MUD).


name: GetNoteStyle
prototype: short GetNoteStyle();
summary: Gets the style for notes
vb_example: Note GetNoteStyle
java_example: Note (GetNoteStyle ());
perl_example: Note (GetNoteStyle ());
return_value: The style currently in force for notes.
type_of_object: Method
see_also: NoteStyle Note Tell ColourNote ColourTell AnsiNote
python_example: Note (GetNoteStyle ())
doc_name: note
lua_example: Note (GetNoteStyle ())
description:
This gets the text style for world.note and similar functions.

The styles are 1 bit each, which can be added or OR'ed together.

The style bits are:

  1 = bold
  2 = underline
  4 = blink (italic)
  8 = inverse
 32 = strike-through


