Manual:Mudlet Object Functions

Mudlet Object Functions

appendCmdLine

appendCmdLine()

Appends text to the main input line.

Example

<lua> -- adds the text "55 backpacks" to whatever is currently in the input line appendCmdLine("55 backpacks")

-- makes a link, that when clicked, will add "55 backpacks" to the input line echoLink("press me", "appendCmdLine'55 backpack'", "Press me!") </lua>

createStopWatch

createStopWatch()

This function creates a stop watch. It is high resolution time measurement tool. Stop watches can be started, stopped, reset and asked how much time has passed since the stop watch has been started.

Returns: The ID of a high resolution clock with milliseconds to measure time more accurately.

Example

In a global script you create all stop watches that you need in your system and store the respective stopWatch-IDs in global variables:

<lua> fightStopWatch = createStopWatch(); -- you store the watchID in a global variable to access it from anywhere </lua>

Then you can start the stop watch in some trigger/alias/script with:

<lua> startStopWatch( fightStopWatch ); </lua>

To stop the watch and measure its time in e.g. a trigger script you can write:

<lua> fightTime = stopStopWatch( fightStopWatch ) echo( "The fight lasted for " .. fightTime .. " seconds." ) resetStopWatch( fightStopWatch ); </lua>

You can also measure the elapsed time without having to stop the stop watch with getStopWatchTime

disableAlias

disableAlias(name)

Disables/deactivates the alias by it’s name. If several aliases have this name, they’ll all be disabled.

Parameters

• name:

The name of the alias. Passed as a string.

Examples

<lua> --Disables the alias called 'my alias' disableAlias("my alias") </lua>

disableKey

disableKey(name)

Disable key or key group "name" (hot keys or action keys).

Parameters

• name:

The name or the id returned by tempTimer to identify the key or group name that you want to disable.

Examples

Need example use

disableTimer

disableTimer(name)

Disables a timer from running it’s script when it fires - so the timer cycles will still be happening, just no action on them. If you’d like to permanently delete it, use killTrigger instead.

Parameters

• name:

Expects the timer ID that was returned by tempTimer on creation of the timer or the name of the timer in case of a GUI timer.

Example

<lua> --Disables the timer called 'my timer' disableTimer("my timer") </lua>

disableTrigger

disableTrigger(name)

Disables a trigger that was previously enabled.

Parameters

• name:

Expects the trigger ID that was returned by tempTrigger on creation of the timer or the name of the timer in case of a GUI trigger.

Example

<lua> -- Disables the trigger called 'my trigger' disableTrigger("my trigger") </lua>

enableAlias

enableAlias(name)

Enables/activates the alias by it’s name. If several aliases have this name, they’ll all be enabled.

Parameters

• name:

Expects the alias ID that was returned by tempTrigger on creation of the alias or the name of the alias in case of a GUI alias.

Example

<lua> --Enables the alias called 'my alias' enableAlias("my alias") </lua>

enableKey

enableKey(name)

Enable key or key group "name" (hot keys or action keys).

Parameters

• name:

The name or the id returned by tempTimer to identify the key or group name that you want to enable.

enableTimer

enableTimer(name)

Enables or activates a timer that was previously disabled.

Parameters

• name:

Expects the timer ID that was returned by tempTimer on creation of the timer or the name of the timer in case of a GUI timer.

<lua> --Enables the timer called 'my timer' enableTimer("my timer") </lua>

enableTrigger

enableTrigger(name)

Enables a Trigger. see enableTimer for more details.

<lua> enableTrigger("my trigger") </lua>

exists

exists(name, type)

Tells you how many things of the given type exist.

Parameters

• name:

The name or the id returned by tempTimer to identify the item.

• type:

The type can be 'alias', 'trigger', or 'timer'.

Example

<lua> echo("I have " .. exists("my trigger", "trigger") .. " triggers called 'my trigger'!") </lua>

You can also use this alias to avoid creating duplicate things, for example:

<lua> -- this code doesn't check if an alias already exists and will keep creating new aliases permAlias("Attack", "General", "^aa$", send ("kick rat"))

-- while this code will make sure that such an alias doesn't exist first -- we do == 0 instead of 'not exists' because 0 is considered true in Lua if exists("Attack", "alias") == 0 then

   permAlias("Attack", "General", "^aa$", send ("kick rat"))

end </lua>

getButtonState

getButtonState()

This function can only be used inside a toggle button script

Returns 2 if button is checked, and 1 if it's not.

Example

<lua> checked = getButtonState(); if checked == 1 then

   hideExits()

else

   showExits()

end; </lua>

invokeFileDialog

invokeFileDialog(fileOrFolder, dialogTitle)

Opens a file chooser dialog, allowing the user to select a file or a folder visually. The function returns the selected path or "" if there was none chosen.

Parameters

• fileOrFolder: true for file selection, false for folder selection.
• dialogTitle: the code to do when the timer is up - wrap it in [[ ]], or provide a Lua function

Examples

<lua> function whereisit()

 local path = invokeFileDialog(false, "Where should we save the file? Select a folder and click Open")

 if path == "" then return nil else return path end

end </lua>

isActive

isActive(name, type)

You can use this function to check if something, or somethings, are active.

Parameters

• name:

The name or the id returned by tempTimer to identify the item.

• type:

The type can be 'alias', 'trigger', or 'timer'.

Example

<lua> echo("I have " .. isActive("my trigger", "trigger") .. " currently active trigger(s) called 'my trigger'!") </lua>

isPrompt

isPrompt()

Returns true or false depending on if the current line being processed is a prompt. This infallible feature is available for MUDs that supply GA events (to check if yours is one, look to bottom-right of the main window - if it doesn’t say <No GA>, then it supplies them).

Example use could be as a Lua function, making closing gates on a prompt real easy.

Example

<lua> -- make a trigger pattern with 'Lua function', and this will trigger on every prompt! return isPrompt() </lua>

killAlias

killAlias(name)

Deletes an alias with the given name. If several aliases have this name, they'll all be deleted.

Parameters

• name:

The name or the id returned by tempTimer to identify the alias.

<lua> --Deletes the alias called 'my alias' killAlias("my alias") </lua>

killTimer

killTimer(id)

Deletes a tempTimer.

Note: Non-temporary timers that you have set up in the GUI cannot be deleted with this function. Use disableTimer to turn them on or off.

Parameters

• id:

The ID returned by tempTimer to identify the item. ID is a string and not a number.

Returns true on success and false if the timer id doesn’t exist anymore (timer has already fired) or the timer is not a temp timer.

killTrigger

killTrigger(id)

Deletes a tempTrigger.

Parameters

• id:

The ID returned by tempTimer to identify the item. ID is a string and not a number.

Returns true on success and false if the trigger id doesn’t exist anymore (trigger has already fired) or the trigger is not a temp trigger.

permAlias

permAlias(name, parent, regex, lua code)

Creates a persistent alias that stays after Mudlet is restarted and shows up in the Script Editor.

Parameters

• name:

The name you’d like the alias to have.

• parent:

The name of the group, or another alias you want the trigger to go in - however if such a group/alias doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.

• regex:

The pattern that you’d like the alias to use.

• lua code:

The script the alias will do when it matches.

Example

<lua> -- creates an alias called "new alias" in a group called "my group" permAlias("new alias", "my group", "^test$", echo ("say it works! This alias will show up in the script editor too.")) </lua>

Note: Mudlet by design allows duplicate names - so calling permAlias with the same name will keep creating new aliases. You can check if an alias already exists with the exists function.

permGroup

permGroup(name, itemtype)

Creates a new group of a given type at the root level (not nested in any other groups). This group will persist through Mudlet restarts.

Parameters

• name:

The name of the new group you want to create.

• itemtype:

The name of the timer, trigger, or alias.

Note: Added to Mudlet in the 2.0 final release.

<lua> --create a new trigger group permGroup("Combat triggers", "trigger")

--create a new alias group only if one doesn't exist already if exists("Defensive aliases", "alias") == 0 then

 permGroup("Defensive aliases", "alias")

end </lua>

permRegexTrigger

permRegexTrigger(name, parent, pattern, lua code)

Creates a persistent trigger with a regex pattern that stays after Mudlet is restarted and shows up in the Script Editor.

Parameters

• name is the name you’d like the trigger to have.
• parent is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.
• pattern table is a table of patterns that you’d like the trigger to use - it can be one or many.
• lua code is the script the trigger will do when it matches.

Example

<lua> -- Create a regex trigger that will match on the prompt to record your status permRegexTrigger("Prompt", "", {"^(\d+)h, (\d+)m"}, [[health = tonumber(matches[2]; mana = tonumber(matches[3])]] </lua> Note: Mudlet by design allows duplicate names - so calling permRegexTrigger with the same name will keep creating new triggers. You can check if a trigger already exists with the exists() function.

permSubstringTrigger

permSubstringTrigger( name, parent, pattern, lua code )

Creates a persistent trigger with a substring pattern that stays after Mudlet is restarted and shows up in the Script Editor.

Parameters

• name is the name you’d like the trigger to have.
• parent is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.
• pattern table is a table of patterns that you’d like the trigger to use - it can be one or many.
• lua code is the script the trigger will do when it matches.

Example

<lua> -- Create a trigger to highlight the word "pixie" for us permSubstringTrigger("Highlight stuff", "General", {"pixie"}, selectString(line, 1) bg("yellow") resetFormat())

-- Or another trigger to highlight several different things permSubstringTrigger("Highlight stuff", "General", {"pixie", "cat", "dog", "rabbit"}, selectString(line, 1) fg ("blue") bg("yellow") resetFormat()) </lua> Note: Mudlet by design allows duplicate names - so calling permSubstringTrigger with the same name will keep creating new triggers. You can check if a trigger already exists with the exists() function.

permTimer

permTimer(name, parent, seconds, lua code)

Creates a persistent timer that stays after Mudlet is restarted and shows up in the Script Editor.

Parameters

• name

Is the name of the timer.

• parent

Is the name of the timer group you want the timer to go in..

• seconds

Is a number specifying a delay after which the timer will do the lua code you give it as a string.

• lua code is the code with string you are doing this to.

Example

<lua> permTimer("my timer", "first timer group", 4.5, send ("my timer that's in my first timer group fired!")) </lua>

Note: Mudlet by design allows duplicate names - so calling permTimer with the same name will keep creating new timers. You can check if a timer already exists with the exists() function.

raiseEvent

raiseEvent(event_name, arg-1, … arg-n)

Raises the event event_name. The event system will call the main function (the one that is called exactly like the script name) of all such scripts that have registered event handlers. If an event is raised, but no event handler scripts have been registered with the event system, the event is ignored and nothing happens. This is convenient as you can raise events in your triggers, timers, scripts etc. without having to care if the actual event handling has been implemented yet - or more specifically how it is implemented. Your triggers raise an event to tell the system that they have detected a certain condition to be true or that a certain event has happened. How - and if - the system is going to respond to this event is up to the system and your trigger scripts don’t have to care about such details. For small systems it will be more convenient to use regular function calls instead of events, however, the more complicated your system will get, the more important events will become because they help reduce complexity very much.

The corresponding event handlers that listen to the events raised with raiseEvent() need to use the script name as function name and take the correct number of arguments.

Note: If you raise an event with 5 arguments but your event handlers functions only take 2,10 or 0 arguments, the functions will not be called.

Example

raiseEvent("fight") a correct event handler function would be: myScript( event_name ). In this example raiseEvent uses minimal arguments, name the event name. There can only be one event handler function per script, but a script can still handle multiple events as the first argument is always the event name. So you can call your own special handlers for individual events. The reason behind this is that you should rather use many individual scripts instead of one huge script that has all your function code etc. Scripts can be organized very well in trees and thus help reduce complexity on large systems.

resetStopWatch

resetStopWatch(watchID)

This function resets the time to 0:0:0.0, but does not start the stop watch. You can start it with startStopWatch → createStopWatch

setConsoleBufferSize

setConsoleBufferSize( consoleName, linesLimit, sizeOfBatchDeletion )

Sets the maximum number of lines can a buffer (main window or a miniconsole) can hold.

Parameters

• consoleName:

The name of the window

• linesLimit:

Sets the amount of lines the buffer should have.

Note: Mudlet performs extremely efficiently with even huge numbers, so your only limitation is your computers memory (RAM).

• sizeOfBatchDeletion:

Specifies how many lines should Mudlet delete at once when you go over the limit - it does it in bulk because it's efficient to do so.

Example

<lua> -- sets the main windows size to 5 million lines maximum - which is more than enough! setConsoleBufferSize("main", 5000000, 1000) </lua>

setTriggerStayOpen

setTriggerStayOpen(name, number)

Sets for how many more lines a trigger script should fire or a chain should stay open after the trigger has matched - so this allows you to extend or shorten the fire length of a trigger. The main use of this function is to close a chain when a certain condition has been met.

Parameters

• name: The name of the trigger which has a fire length set (and which opens the chain).
• number: 0 to close the chain, or a positive number to keep the chain open that much longer.

Examples

<lua> -- if you have a trigger that opens a chain (has some fire length) and you'd like it to be closed -- on the next prompt, you could make a trigger inside the chain with a Lua function pattern of: return isPrompt() -- and a script of: setTriggerStayOpen("Parent trigger name", 0) -- to close it on the prompt! </lua>

startStopWatch

startStopWatch( watchID )

Starts the stop watch. → createStopWatch()

stopStopWatch

stopStopWatch( watchID )

Stops the stop watch and returns the elapsed time in milliseconds in form of 0.001. → createStopWatch()

Returns time as a number

tempAlias

tempAlias(regex, code to do)

Creates a temporary alias - it'll won't be saved when Mudlet restarts and thus wiped.

Parameters

• regex: Alias pattern in regex.
• code to do::The code to do when the timer is up - wrap it in [[ ]], or provide a Lua function.

Examples

<lua> tempAlias("^hi$", send ("hi") echo ("we said hi!") </lua>

tempColorTrigger

tempColorTrigger(foregroundColor, backgroundColor, code)

Makes a color trigger that triggers on the specified foreground and background color. Both colors need to be supplied in form of these simplified ANSI 16 color mode codes.

Parameters

• foregroundColor: The foreground color you'd like to trigger on.
• backgroundColor: The background color you'd like to trigger on.
• code: The code you'd like the trigger to run, as a string.

Color codes

<lua> 0 = default text color 1 = light black 2 = dark black 3 = light red 4 = dark red 5 = light green 6 = dark green 7 = light yellow 8 = dark yellow 9 = light blue 10 = dark blue 11 = light magenta 12 = dark magenta 13 = light cyan 14 = dark cyan 15 = light white 16 = dark white </lua>

Examples

<lua> -- This script will re-highlight all text in blue foreground colors on a black background with a red foreground color on a blue background color until another color in the current line is being met. temporary color triggers do not offer match_all or filter options like the GUI color triggers because this is rarely necessary for scripting. A common usage for temporary color triggers is to schedule actions on the basis of forthcoming text colors in a particular context. tempColorTrigger(9,2,[[selectString(matches[1],1); fg("red"); bg("blue");]] ); </lua>

tempLineTrigger

tempLineTrigger( from, howMany, LuaCode )

Temporary trigger that will fire on n consecutive lines following the current line. This is useful to parse output that is known to arrive in a certain line margin or to delete unwanted output from the MUD.

Returns trigger ID, ID is a string and not a number.

Note: You can use this ID to enable/disable or kill this trigger later on.

Example

<lua> --Will fire 3 times with the line from the MUD. tempLineTrigger( 1, 3, )

--Will fire 20 lines after the current line and fire twice on 2 consecutive lines. tempLineTrigger( 20, 2, ) </lua>

tempRegexTrigger

tempRegexTrigger(regex, code to do)

Creates a temporary regex trigger that executes the code whenever it matches. The function returns the trigger ID for subsequent enableTrigger(), disableTrigger() and killTrigger() calls.

Returns trigger ID

Parameters

• regex: The regex to look for.
• code to do: The code to do when the timer is up - wrap it in [[ ]], or provide a Lua function.

Note: You can use this ID to enable/disable or kill this trigger later on. → tempTimer()

tempTimer

tempTimer(time, code to do)

Creates a temporary single shot timer and returns the timer ID for subsequent enableTimer(), disableTimer() and killTimer() calls. You can use 2.3 seconds or 0.45 etc. After it has fired, the timer will be deactivated and killed.

Parameters

• time: The time in seconds for which to set the timer for.
• code to do: The code to do when the timer is up - wrap it in [[ ]], or provide a Lua function.

Examples

<lua> -- wait half a second and then run the command tempTimer( 0.5, send("kill monster") )

-- or an another example - two ways to 'embed' variable in a code for later: local name = matches[2] tempTimer(2, send("hello, ..name..!")) -- or: tempTimer(2, function()

 send("hello, "..name)

end) </lua>

Note: Double Brackets, e.g: [[ ]] can be used to quote strings in Lua. The difference to the usual `" " quote syntax is that `[[ ]] also accepts the character ". Consequently, you don’t have to escape the " character in the above script. The other advantage is that it can be used as a multiline quote, so your script can span several lines. Also note that the Lua code that you provide as an argument is compiled from a string value when the timer fires. This means that if you want to pass any parameters by value e.g. you want to make a function call that uses the value of your variable myGold as a parameter you have to do things like this:

<lua> tempTimer( 3.8, echo("at the time of the tempTimer call I had .. myGold .. gold.") ) tempTimer also accepts functions (and thus closures) - which can be an easier way to embed variables and make the code for timers look less messy:

local variable = matches[2] tempTimer(3, function () send("hello, " .. variable) end) </lua>

tempTrigger

tempTrigger(substring, code to do)

Creates a temporary substring trigger that executes the code whenever it matches. The function returns the trigger ID for subsequent enableTrigger(), disableTrigger() and killTrigger() calls.

Parameters

• substring: The substring to look for.
• code to do: The code to do when the timer is up - wrap it in [[ ]], or provide a Lua function.