Plugin

A plugin is represented as a JSON document that specifies all of its features, which are broken down below. A minimalist plugin document looks like this:

{
  "name": "my minimal plugin",
  "version": 1,
  "requires": "3.6.8",
  "code": "",
  "mxp":"",
  "triggers": [],
  "aliases": [],
  "timers": []
  "menus": {}
}

The name may be any string, but try to keep it unique. Version must be an integer or real number. Version is the minimum Sip/Siplet version. mxp is a document of MXP tags/entities that your plugin contributes. Code is your message handling javascript. The API is discussed in the last section.

The triggers field is an array of trigger objects, each of which looks like this:

{
	"name":"my trigger",
	"regex":false,
	"pattern":"mud output",
	"once":true,
	"action":"win.displayText('hi');"
}

The name of a plugin trigger is not terribly important, but is required. Regex is true if your pattern is a regular expression, and false if it is a simple string. Once is true if the trigger should be disabled after its initial match, or false to continue matching.

Action is one of: submitInput, displayText, playSound, setEntity, runScript, enableTrigger, disableTrigger, startTimer, clearTimer, displayAt, submitHidden, clearWindow, or sendPlugin. These, and the required argument(s) are summarized in the help for Actions. Remember that an argument string must be internally quoted, unless it is not a string, but one of the permitted variables.

The top level aliases field is an array of alias objects, each of which looks like this:

{
	"name":"my alias",
	"regex":false,
	"pattern":"/command",
	"replace":"replacement string",
	"action":"win.displayText('hi');"
}

The name, regex, pattern, action, and argument of a plugin alias is the same as described above for triggers, except that the action and argument may be empty. The replace field is the string that replaces the user input matched by the pattern.

The top level timers field is an array of timer objects, each of which looks like this:

{
	"name":"my timer",
	"delay":0,
	"option":"once"
	"trigger":true,
	"action":"win.displayText('hi');"
}

The name, action, and argument of a plugin timer is the same as described above for triggers. The option field must be one of 'once', 'multiple', or 'repeat'; see the help on Timers for more information on Options. The trigger field is true if a timer begins its delay immediately, or false if it must be externally triggered before counting down. Delay is the number of milliseconds (1000th of a second) that the timer delays for; for example, 5000 would be 5 seconds, and 60000 would be a minute.

The top level menus field is additions to the top level menu system. Each key is a top level menu (such as Windows, Global Options, or Help). Each menus key then is mapped to an array of specific menu entry json object like this:

"Top Menu": [{
	"n":"Option 1",
	"a":"win.displayText('hi');"
},{
	"n":"Option 2",
	"a":"win.displayText('ho');"
}]

The n entry is simply the drop-down option name, while a is an Action, which is the same as described above under Triggers. Optional arguments include v, which is a truthy variable expression that describes whether the option is visible, and e, which is a truthy variable expression describing whether the option may be clicked, or is grayed out.

Javascript Code

Plugin code has the same Scripts api available to it, but unlike normal scripts, plugin code is sandboxed to protect the user installing it, which means that the code will not have direct access to the ENTIRE mud client api or dom. Instead, it has limited access to the win.* and win.mapper.* methods as scripts in the Scripts help. For other outside events, it must receive information from a

window.onevent

function, and can post messages to the client using

window.send

. More detail on the types of events and the specifics of send messages is below, but first, here is some minimal plugin code:

window.onevent=function(event)
{ 
  console.log("plugin received event type " + event.type);
  var response = {
    command: 'displayText',
    data: '"i received ' + event.type + '"'
  };
  window.send(response); // send the same event back 
};
win.submitInput('LOOK');

The following are the events and event fields that might trigger the window.onevent function for a plugin. All events have a 'type' field, and always a 'data' field, in addition to other 'extra' fields.

Type	Extra	Description
connect		Connection made, with url
disconnect		Connection lost, with url
close		Plugins window closing
msdp		MSDP message with msdp js object data
gmcp	command	GMCP message with js object data
event		Un-typed event from trigger/alias/etc
variable	key	Result from fetchVariable with key,data
?	?	Typed event from trigger/alias/etc

If a plugin needs its own configuration, then you can take advantage of the fact that win.displayText(...) supports MXP tags, such as INPUT, regardless of whether MXP is actually turned on in the client. If you need storage, localStorage.getItem, setItem, and removeItem are also available. available.