Difference between revisions of "Manual:Mudlet Object Functions"

Revision as of 04:51, 5 June 2017

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>

clearCmdLine

clearCmdLine(): Clears the input line of any text that's been entered.

Example

<lua> -- don't be evil with this! clearCmdLine() </lua>

createStopWatch

createStopWatch(): This function creates a stopwatch, a high resolution time measurement tool. Stopwatches can be started, stopped, reset and asked how much time has passed since the stop watch has been started.

Returns: The ID of a stopwatch.

Example: In a global script you can 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().

Note: it's best to re-use stopwatch IDs if you can - Mudlet at the moment does not delete them, so creating more and more would use more memory.

disableAlias

disableAlias(name): Disables/deactivates the alias by its name. If several aliases have this name, they'll all be disabled.; See also: enableAlias()

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): Disables key a key (macro) or a key group. When you disable a key group, all keys within the group will be implicitly disabled as well.

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.

disableTrigger

disableTrigger(name): Disables a permanent (one in the trigger editor) or a temporary trigger.

enableAlias

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

enableKey

enableKey(name): Enables a key (macro) or a group of keys (and thus all keys within it that aren't explicitly deactivated).

Parameters

name:

The name of the group that identifies the key.

<lua> -- you could use this to disable one key set for the numpad and activate another disableKey("fighting keys") enableKey("walking keys") </lua>

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> -- enable the timer called 'my timer' that you created in Mudlets timers section enableTimer("my timer") </lua>

<lua> -- or disable & enable a tempTimer you've made timerID = tempTimer(10, echo("hi!"))

-- it won't go off now disableTimer(timerID) -- it will continue going off again enableTimer(timerID) </lua>

enableTrigger

enableTrigger(name): Enables or activates a trigger that was previously disabled.

Parameters

name:

Expects the trigger ID that was returned by tempTrigger or by any other temp*Trigger variants, or the name of the trigger in case of a GUI trigger.

<lua> -- enable the trigger called 'my trigger' that you created in Mudlets triggers section enableTrigger("my trigger") </lua>

<lua> -- or disable & enable a tempTrigger you've made triggerID = tempTrigger("some text that will match in a line", echo("hi!"))

-- it won't go off now when a line with matching text comes by disableTrigger(triggerID)

-- and now it will continue going off again enableTrigger(triggerID) </lua>

exists

exists(name, type): Tells you how many things of the given type exist.

Parameters

name:

The name or the id returned by the temp* function to identify the item.

type:

The type can be 'alias', 'trigger', 'timer' or as of Mudlet 3.2, 'keybind'.

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>

Especially helpful when working with permTimer:

<lua> if not exists("My animation timer", "timer") then

 vdragtimer = permTimer("My animation timer", "", .016, onVDragTimer) -- 60fps timer!

end

enableTimer("My animation timer") </lua>

getButtonState

getButtonState(): This function can be used within checkbox button scripts (2-state buttons) to determine the current state of the checkbox.

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>

getCmdLine

getCmdLine(): Returns the current content of the main input line.

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.; Returns the number of active things - and 0 if none are active. Beware that all numbers are true in Lua, including zero.

Parameters

name:

The name or the id returned by temp* function to identify the item.

type:

The type can be 'alias', 'trigger', 'timer', or as Mudlet 3.2, 'keybind'.

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>

killKey

killKey(name): Deletes a keybinding with the given name. If several keybindings have this name, they'll all be deleted.

Parameters

name:

The name or the id returned by tempKey to identify the key.

Note: Available in Mudlet 3.2+

<lua> -- make a temp key local keyid = tempKey(mudlet.key.F8, echo("hi!"))

-- delete the said temp key killKey(keyid) </lua>

killTimer

killTimer(id): Deletes a tempTimer.

Note: Non-temporary timers that you have set up in the GUI OR by using permTimer cannot be deleted with this function. Use disableTimer() and enableTimer() to turn them on or off.

Parameters

id: the ID returned by tempTimer.

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.

Example

<lua> -- create the timer and remember the timer ID timerID = tempTimer(10, echo("hello!"))

-- delete the timer if killTimer(timerID) then echo("deleted the timer") else echo("timer is already deleted") end </lua>

killTrigger

killTrigger(id): Deletes a tempTrigger, or a trigger made with one of the temp<type>Trigger() functions.

Note: When used in out of trigger contexts, the triggers are disabled and deleted upon the next line received from the game - so if you are testing trigger deletion within an alias, the 'statistics' window will be reporting trigger counts that are disabled and pending removal, and thus are no cause for concern.

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

name of the timer.

parent

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

seconds

a floating point number specifying a delay in seconds after which the timer will do the lua code (stored as the timer's "script") you give it as a string.

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

Returns

a unique id number for that timer.

Example

<lua> -- create a timer in the "first timer group" group permTimer("my timer", "first timer group", 4.5, send ("my timer that's in my first timer group fired!")) -- create a timer that's not in any group; just at the top permTimer("my timer", "", 4.5, send ("my timer that's in my first timer group fired!"))

-- enable timer - they start off disabled until you're ready enableTimer("my timer") </lua>

Note: The timer is NOT active after creation, it will need to be enabled by a call to enableTimer() before it starts.

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.

permKey

permKey(name, parent, modifier, key code, lua code): Creates a persistent key that stays after Mudlet is restarted and shows up in the Script Editor.

Parameters

name

name of the key.

parent

name of the timer group you want the timer to go in or "" for the top level.

modifier

(optional) modifier to use - can be one (or more, if they are added together) of the numeric values now stored in the mudlet.keymodifier table: mudlet.keymodifier.Control, mudlet.keymodifier.Alt, mudlet.keymodifier.Shift, mudlet.keymodifier.Meta, mudlet.keymodifier.Keypad, mudlet.keymodifier.GroupSwitch or instead the default no option value of mudlet.keymodifier.None can be used; it is assumed if the argument is omitted.

key code

actual key to use - can be one of the numeric values now stored in the mudlet.keymodifier table, e.g.: mudlet.key.Escape, mudlet.key.Tab, mudlet.key.F1, mudlet.key.A, and so on. The list is too long to list out in full so it is available here.

lua code'

code you would like the key to run.

Returns

a unique id number for that key.

Note: Available in Mudlet 3.2+

Example

<lua> -- create a key at the top level for F8 permKey("my key", "", nil, mudlet.key.F8, echo("hey this thing actually works!\n"))

-- or Ctrl+F8 lua permKey("my key", "", mudlet.keymodifier.Control, mudlet.key.F8, echo("hey this thing actually works!\n")) </lua>

Note: Mudlet by design allows duplicate names - so calling permKey with the same name will keep creating new keys. You can check if a key already exists with the exists() function. The key will be created even if the lua code does not compile correctly - but this will be apparent as it will be seen in the Editor.

printCmdLine

printCmdLine(text)

Replaces the current text in the input line, and sets it to the given text.

<lua> printCmdLine("say I'd like to buy ") </lua>

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 in this profile 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: handles nil and boolean arguments since Mudlet 3.0.

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.

Where the number of arguments that your event may receive is not fixed you can use ... as the last argument in the function declaration to handle any number of arguments. For example:

<lua> -- try this function out with "lua myscripthandler(1,2,3,4)" function myscripthandler(a, b, ...)

 print("Arguments a and b are: ", a,b)
 -- save the rest of the arguments into a table
 local otherarguments = {...}
 print("Rest of the arguments are:")
 display(otherarguments)

 -- access specific otherarguments:
 print("First and second otherarguments are: ", otherarguments[1], otherarguments[2])

end </lua>

raiseGlobalEvent

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

Like raiseEvent() this raises the event "event_name", but this event is sent to all other opened profiles instead. The profiles receive the event in circular alphabetical order (if profile "C" raised this event and we have profiles "A", "C", and "E", the order is "E" -> "A", but if "E" raised the event the order would be "A" -> "C"); execution control is handed to the receiving profiles so that means that long running events may lock up the profile that raised the event.

The sending profile's name is automatically appended as the last argument to the event.

Example

<lua> -- from profile called "My MUD" this raises an event "my event" with additional arguments 1, 2, 3, "My MUD" to all profiles except the original one raiseGlobalEvent("my event", 1, 2, 3) </lua>

Note: Available since Mudlet 3.1.0.

Tip: you might want to add the profile name to your plain raiseEvent() arguments. This'll help you tell which profile your event came from similar to raiseGlobalEvent().

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 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. Stopwatches can be stopped and re-started any number of times.

Parameters

watchID: The stopwatch ID you get with createStopWatch().

Examples

<lua> -- this is a common pattern for re-using stopwatches and starting them: watch = watch or createStopWatch() startStopWatch(watch) </lua>

stopStopWatch

stopStopWatch( watchID ): Stops the stop watch and returns the elapsed time in milliseconds in form of 0.001. You can also retrieve the current time without stopping the stopwatch with getStopWatchTime().; Returns time as a number.

Parameters

watchID: The stopwatch ID you get with createStopWatch().

Examples

<lua> -- this is a common pattern for re-using stopwatches and starting them: watch = watch or createStopWatch() startStopWatch(watch)

-- do some long-running code here ...

print("The code took: "..stopStopWatch(watch).."s to run.") </lua>

Note: The current implementation is broken in that it is NOT possible to stop a stopwatch - it behaves the same as the getStopWatchTime() command.

tempAlias

aliasID = tempAlias(regex, code to do): Creates a temporary alias - temporary in the sense that it won't be saved when Mudlet restarts (unless you re-create it). The alias will go off as many times as it matches, it is not a one-shot alias. The function returns an ID for subsequent enableAlias(), disableAlias() and killAlias() calls.

Parameters

regex: Alias pattern in regex.
code to do: The code to do when the alias fires - wrap it in [[ ]].

Examples

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

-- you can also delete the alias later with: killAlias(myaliasID) </lua>

tempBeginOfLineTrigger

tempBeginOfLineTrigger(part of line, code to do): Creates a trigger that will go off whenever the part of line it's provided with matches the line right from the start (doesn't matter what the line ends with). This trigger isn't temporary in the sense that it'll go off only once (it'll go off as often as it matches), but rather it won't be saved when Mudlet is closed. The function returns the trigger ID for subsequent enableTrigger(), disableTrigger() and killTrigger() calls. The trigger will go off multiple times until you disable or destroy it.

Parameters

part of line: Start of the line that you'd like to match.
code to do: The code to do when the trigger fires - wrap it in [[ ]].

Examples

<lua> mytriggerID = tempBeginOfLineTrigger("Hello", echo("We matched!"))

--[[ now this trigger will match on any of these lines: Hello Hello! Hello, Bob!

but not on: Oh, Hello Oh, Hello! ]] </lua>

tempButton

tempButton(group name, button text, orientation): Creates a temporary button.

Parameters

group name: The toolbar to place the button into.
button text: The text to place on the button.
orientation: a number, 0 - horizontal orientation for the button, or 1 - vertical orientation for the button.

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. The function returns the trigger ID for subsequent enableTrigger(), disableTrigger() and killTrigger() calls. The trigger will go off multiple times until you disable or destroy it.

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>

tempComplexRegexTrigger

tempComplexRegexTrigger('name', regex, code to execute, multiline, foreground color, bg color, filter, match all, highlight foreground color, highlight background color, play sound file, fire length, line delta): Allows you to create a temporary trigger in Mudlet, using any of the UI-available options.; Returns the trigger name, that you can use killTrigger() later on with.

For the multiline and so on options, use a 0 if you don't want those options. Otherwise enter the value you want to use.

For color, you need to provide both fg and bg together.

For making multiline triggers, use the same trigger name an options, providing the new pattern to add:

<lua> tempComplexRegexTrigger("testTrigger", "first pattern", echo("it went"), 1, 0, 0....) tempComplexRegexTrigger("testTrigger", "second pattern", echo("it went"), 1, 0, 0....) </lua>

That will make 1 trigger with both regex patterns. Note only one script will ever be used (the last one set).

tempExactMatchTrigger

tempExactMatchTrigger(exact line, code to do): Creates a trigger that will go off whenever the line from the game matches the provided line exactly (ends the same, starts the same, and looks the same). You don't need to use any of the regex symbols here (^ and $). This trigger isn't temporary in the sense that it'll go off only once (it'll go off as often as it matches), but rather it won't be saved when Mudlet is closed. The function returns the trigger ID for subsequent enableTrigger(), disableTrigger() and killTrigger() calls. The trigger will go off multiple times until you disable or destroy it.

Parameters

exact line: Exact line you'd like to match.
code to do: The code to do when the trigger fires - wrap it in [[ ]].

Examples

<lua> mytriggerID = tempExactMatchTrigger("You have recovered balance on all limbs.", echo("We matched!")) </lua>

tempKey

tempKey(modifier, key code, lua code): Creates a keybinding. This keybinding isn't temporary in the sense that it'll go off only once (it'll go off as often as you use it), but rather it won't be saved when Mudlet is closed.

modifier

(optional) modifier to use - can be one (or more if they are added together) of the numeric values stored in the mudlet.keymodifier table: mudlet.keymodifier.Control, mudlet.keymodifier.Alt, mudlet.keymodifier.Shift, mudlet.keymodifier.Meta, mudlet.keymodifier.Keypad, or mudlet.keymodifier.GroupSwitch or the default value of mudlet.keymodifier.None which is used if the argument is omitted.

key code

actual key to use - can be one of the numeric values stored in the mudlet.key table, e.g. mudlet.key.Escape, mudlet.key.Tab, mudlet.key.F1, mudlet.key.A, and so on. The list is a bit long to list out in full so it is available here.

lua code'

code you'd like the key to run - wrap it in [[ ]].

Returns

a unique id number for that key.

Examples

<lua> local keyID = tempKey(mudlet.key.F8, echo("hi"))

local anotherKeyID = tempKey(mudlet.keymodifier.Control, mudlet.key.F8, echo("hello"))

-- delete it if you don't like it anymore killKey(keyID) </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 - the trigger does not require any patterns to match on. The function returns the trigger ID for subsequent enableTrigger(), disableTrigger() and killTrigger() calls. The trigger will go off multiple times until you disable, destroy it or it runs out.

Returns trigger ID as a string.

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. The trigger will go off multiple times until you disable or destroy it.

Parameters

regex: The regular expression that lines will be matched on.
code to do: The code to do when the timer is up - wrap it in [[ ]].

Examples

<lua> -- create a non-duplicate trigger that matches on any line and calls a function html5log = html5log or {} if html5log.trig then killTrigger(html5log.trig) end html5log.trig = tempRegexTrigger("^", "html5log.recordline()") </lua>

tempTimer

tempTimer(time, code to do): Creates a temporary one-shot timer and returns the timer ID, which you can use with enableTimer(), disableTimer() and killTimer() functions. You can use 2.3 seconds or 0.45 etc. After it has fired, the timer will be deactivated and destroyed, so it will only go off once. See here for a more detailed introduction to tempTimer.

Parameters

time: The time in seconds for which to set the timer for - you can use decimals here for precision. The timer will go off x given seconds after you make it.
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.

Note: 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. The trigger will go off multiple times until you disable or destroy it.

Parameters

substring: The substring to look for - this means a part of the line. If your provided text matches anywhere within the line from the game, the trigger will go off.
code to do: The code to do when the timer is up - wrap it in [[ ]].

Example: <lua> -- this example will highlight the contents of the "target" variable. -- It will also delete the previous trigger it made when you call it again, so you're only ever highlighting one name if id then killTrigger(id) end id = tempTrigger(target, selectString(" .. target .. ", 1) fg("gold") resetFormat()) </lua>

<lua> -- a simpler trigger to replace "hi" with "bye" whenever you see it tempTrigger("hi", selectString("hi", 1) replace("bye")) </lua>

@@ Line 505: / Line 505: @@
 <lua>
 -- create a key at the top level for F8
-permKey("my key", "", nil, mudlet.key.F8 [[echo("hey this thing actually works!\n")]])
+permKey("my key", "", nil, mudlet.key.F8, [[echo("hey this thing actually works!\n")]])
 -- or Ctrl+F8

Difference between revisions of "Manual:Mudlet Object Functions"

Revision as of 04:51, 5 June 2017

Mudlet Object Functions

appendCmdLine

clearCmdLine

createStopWatch

disableAlias

disableKey

disableTimer

disableTrigger

enableAlias

enableKey

enableTimer

enableTrigger

exists

getButtonState

getCmdLine

invokeFileDialog

isActive

isPrompt

killAlias

killKey

killTimer

killTrigger

permAlias

permGroup

permRegexTrigger

permSubstringTrigger

permTimer

permKey

printCmdLine

raiseEvent

raiseGlobalEvent

resetStopWatch

setConsoleBufferSize

setTriggerStayOpen

startStopWatch

stopStopWatch

tempAlias

tempBeginOfLineTrigger

tempButton

tempColorTrigger

tempComplexRegexTrigger

tempExactMatchTrigger

tempKey

tempLineTrigger

tempRegexTrigger

tempTimer

tempTrigger

Navigation menu

Search