Manual:Mudlet Object Functions

From Mudlet
Revision as of 03:07, 11 August 2012 by Vadi (talk | contribs) (→‎killTimer: improvements)
Jump to navigation Jump to search

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 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.

Note 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.

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> -- 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 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 Note: Non-temporary timers that you have set up in the GUI cannot be deleted with this function. Use disableTimer() and enableTimer() to turn them on or off.

Parameters
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

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 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 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 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 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 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.

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 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.


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.

remember

remember("variable")
This function flags a variable to be saved by Mudlet's variable persistence system.
Parameters
  • variable
Variable that you are saving. Can be a table or regular variable. Name must be passed as a string.
Example

<lua>remember("table_Weapons") remember("var_EnemyHeight") </lua> Variables are automatically unpacked into the global namespace when the profile is loaded.
They are saved to "SavedVariables.lua" when the profile is closed or saved.

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 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

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>

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>

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>

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 or destroy it.
Returns trigger ID as a string.

Note 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.
  • 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 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 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>

Retrieved from "https://wiki.mudlet.org/index.php?title=Manual:Mudlet_Object_Functions&oldid=1753"