Lich:Software/Scripting reference: Difference between revisions

The official GemStone IV encyclopedia.
< Lich:Software
Jump to navigation Jump to search
 
(76 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{3rd-party}}
== put ==
== variable ==
<div {{log}}>
<div {{log}}>
variable[1]
put "look"
</div>
<div {{log}}>
Script.current.vars[0]
</div>
<div {{log}}>
Script.current.vars[1]
</div>
</div>
*'''Returns:''' the string that was sent
*'''Description:''' Identical to Wizard.


*'''Returns:''' an array, possibly empty
== fput ==
*'''Synonyms:''' Script.current.vars, script.vars
*'''Description:''' An array containing the command line variables the user entered when starting the script. Index position 0 contains all the variables passed to it in a single string. Index positions 1 thru n correlate to space separated list of the values passed to the script. The third example above showing proper syntax for recalling the first variable passed to the script. While variable and script.vars still work, the current best practice is to use Script.current.vars to match appropriate Lich API usage.

== echo ==
<div {{log}}>
<div {{log}}>
echo
fput "stance defensive"
</div>
</div>
<div {{log}}>
<div {{log}}>
echo "Hi there!"
fput "stance defensive", "are now in a defensive stance", "can't do that while dead", "etc"
</div>
</div>
<div {{log}}>
*'''Returns:''' the string that was accepted as meaning the action succeeded (see below)
echo "Line one", "Line two", "endlessly"
*'''Synonyms:''' forceput
</div>
*'''Description:''' It's named 'forceput' because originally it was intended to be used only infrequently, but as it's turned out there are very few times when 'put' is preferable. This command will continue to 'put' whatever string you give it, until it receives a line from the game that it doesn't recognize as one of the common "command rejected" responses (for example, "You can't do that while entangled in a web", "...wait x seconds" (RT), "Wait x seconds." (cast RT), "Sorry, you may only type ahead x lines", "You'll have to stand up first" (stands and reattempts), etc). If stunned, it will wait until you're no longer stunned to reattempt; if in RT (hard or soft), will wait 'x' seconds before reattempting. If you need to stand, it will do so and retry immediately. If it causes a type ahead error, it will pause for 1 second and then reattempt. This has a very high rate of success, but it is definitely not infallible -- it only checks the next line received from the game, and there's no guarantee the next line from the game has anything at all to do with what the 'fput' command just sent. Because of this it can often fail to realize the command wasn't really successful, particularly if the user is doing a lot of things at once. If given more than one string, the first string is taken as the command to send to the game, and all other strings are used as what to accept as meaning the action succeeded. BE CAREFUL with this behavior! It can very infrequently be extremely useful, but if not used cautiously, it can easily cause a script to mistakenly repeat an action many times in *very* rapid succession (which with CoL signs for instance can very easily kill you in less than a second flat).
*'''Returns:''' a string
*'''Description:''' Displays '[script_name: the string it was given]' in the game window; if given multiple strings it echoes each string on its own line. If it's given no arguments, it simply prints a blank line without the '[script_name: ]' business.

== respond ==
<div {{log}}>
respond
</div>
<div {{log}}>
respond "I'm a string to display"
</div>
<div {{log}}>
respond "Line one", "Line two", "so on and so on"
</div>
*'''Returns:''' integer
*'''Description:''' Just like the 'echo' command, but does not display the script name. Since it's possible for Lich to be running two dozen scripts at the same time, it can get a little hard to know which script is saying what unless they use the 'echo' command and not the 'respond' command. Still, 'echo' can be a bit ugly for printing tables and whatnot, so use this instead if desired. The return value is how many characters the last string displayed contained.


== pause ==
== pause ==
<div {{log}}>
<div {{log}}>
pause 1
pause
</div>
<div {{log}}>
pause 3
</div>
</div>
<div {{log}}>
<div {{log}}>
Line 26: Line 53:
<div {{log}}>
<div {{log}}>
pause '3m'
pause '3m'
</div>
<div {{log}}>
pause '2h'
</div>
</div>
<div {{log}}>
<div {{log}}>
Line 36: Line 60:
*'''Description:''' If given no arguments, pauses for one second. If given an integer, pauses for that many seconds. If given a string (as in the examples above), extracts the number to pause for from the string and pauses for that many seconds/hours/days (yeah, well, I was bored, so why not make it do days too). Return value is the number of seconds it paused for.
*'''Description:''' If given no arguments, pauses for one second. If given an integer, pauses for that many seconds. If given a string (as in the examples above), extracts the number to pause for from the string and pauses for that many seconds/hours/days (yeah, well, I was bored, so why not make it do days too). Return value is the number of seconds it paused for.



== echo ==
== Output ==

Sending output to the game as though typed by the player.

=== put ===
<div {{log}}>
<div {{log}}>
put "look"
echo
</div>
</div>
*'''Returns:''' the string that was sent
*'''Description:''' Identical to Wizard.

=== fput ===
<div {{log}}>
<div {{log}}>
fput "stance defensive"
echo "Hi there!"
</div>
</div>
<div {{log}}>
<div {{log}}>
fput "stance defensive", "are now in a defensive stance", "can't do that while dead", "etc"
echo "Line one", "Line two", "endlessly"
</div>
*'''Returns:''' the string that was accepted as meaning the action succeeded (see below)
*'''Synonyms:''' forceput
*'''Description:''' It's named 'forceput' because originally it was intended to be used only infrequently, but as it's turned out there are very few times when 'put' is preferable. This command will continue to 'put' whatever string you give it, until it receives a line from the game that it doesn't recognize as one of the common "command rejected" responses (for example, "You can't do that while entangled in a web", "...wait x seconds" (RT), "Wait x seconds." (cast RT), "Sorry, you may only type ahead x lines", "You'll have to stand up first" (stands and reattempts), etc). If stunned, it will wait until you're no longer stunned to reattempt; if in RT (hard or soft), will wait 'x' seconds before reattempting. If you need to stand, it will do so and retry immediately. If it causes a type ahead error, it will pause for 1 second and then reattempt. This has a very high rate of success, but it is definitely not infallible -- it only checks the next line received from the game, and there's no guarantee the next line from the game has anything at all to do with what the 'fput' command just sent. Because of this it can often fail to realize the command wasn't really successful, particularly if the user is doing a lot of things at once. If given more than one string, the first string is taken as the command to send to the game, and all other strings are used as what to accept as meaning the action succeeded. BE CAREFUL with this behavior! It can very infrequently be extremely useful, but if not used cautiously, it can easily cause a script to mistakenly repeat an action many times in *very* rapid succession (which with CoL signs for instance can very easily kill you in less than a second flat).

=== multifput ===
<div {{log}}>
multifput "stance offensive", "incant 910", "stance defensive"
</div>
*'''Returns:''' a string (return value of the last 'fput' executed)
*'''Description:''' Takes multiple strings and executes an 'fput' command for every one sequentially.

=== dothis ===
<div {{log}}>
dothis "action here", /regex to match for success/
</div>
*'''Returns:''' a success string, or false
*'''Description:''' Similar to fput, but will continue to try the action until a success string is matched

=== dothistimeout ===
<div {{log}}>
dothistimeout "action here", time, /regex to match for success/
</div>
*'''Returns:''' a success string, or nil
*'''Description:''' Same as 'dothis', but if a success isn't seen in the given amount of time, returns a value of 'nil' and the script will move on.

=== move ===
<div {{log}}>
move 'northwest'
</div>
*'''Returns:''' true or false
*'''Description:''' Same as the Wizard 'move' command, but it will usually compensate for things like type ahead errors, RT, currently stunned, etc.; will also stand and re-attempt the movement if it's detected to be necessary. Returns 'true' if the move was executed properly, 'false' if it wasn't able to be performed (which is very rare due to the move command's error compensation measures).

=== multimove ===
<div {{log}}>
multimove 'nw', 'ne', 'go hole', 'climb stairs'
</div>
*'''Returns:''' true or false
*'''Description:''' Takes multiple directions to move in and executes the 'move' command for each one. Returns the value of the last 'move' command executed (true or false).


== Input ==

This is core line-by-line handling of full lines of input sent by the game to the player. For more complex filtering and handling, see "match" and "wait" sections.

=== get ===
<div {{log}}>
get
</div>
</div>
*'''Returns:''' a string
*'''Returns:''' a string
*'''Description:''' Displays '[script_name: the string it was given]' in the game window; if given multiple strings it echoes each string on its own line. If it's given no arguments, it simply prints a blank line without the '[script_name: ]' business.
*'''Description:''' Fetches the next un-checked line of game data (while a script is running, it is given every game line, and these lines are available for a script to check/use at its leisure).


== respond ==
=== regetall ===
<div {{log}}>
<div {{log}}>
regetall "Shaelun"
respond
</div>
</div>
*'''Returns:''' an array of strings, or nil
*'''Description:''' Takes a string and returns an array of all game lines (since login) that match as having contained the given string (absolutely every single line since you logged in, Lich remembers them all). If a script is set as receiving the status data that doesn't show in the game window, those lines are also matched for; if the script is only being fed normal game data, that's the only history this command checks. If no matching lines were found, returns 'nil' (which is false in a logical comparison). As well as returning the matches, it also adds them to the script's game data stack so that subsequent 'get' commands will fetch them in order. The string to match for is actually optional, and if omitted, all lines are considered 'matching'.

=== reget ===
<div {{log}}>
<div {{log}}>
reget 3
respond "I'm a string to display"
</div>
</div>
<div {{log}}>
<div {{log}}>
reget 5, "Shaelun"
respond "Line one", "Line two", "so on and so on"
</div>
</div>
*'''Returns:''' integer
*'''Returns:''' an array of strings, or nil
*'''Description:''' Similar to 'regetall' in behavior, but it only checks the current RAM cache (every 2 minutes, Lich's 'memory' of game data is emptied out of RAM and stored in a temporary file on the hard disk so that the program doesn't take up more resources than is necessary -- these files are deleted when the program closes); it also takes an optional integer, which represents how many game lines back to check ('reget 5' would scan the last 5 lines from the game that are still in RAM). If the integer is omitted, will scan the entire existing RAM buffer (again, cleared every 2 minutes).
*'''Description:''' Just like the 'echo' command, but does not display the script name. Since it's possible for Lich to be running two dozen scripts at the same time, it can get a little hard to know which script is saying what unless they use the 'echo' command and not the 'respond' command. Still, 'echo' can be a bit ugly for printing tables and whatnot, so use this instead if desired. The return value is how many characters the last string displayed contained.


== goto ==
=== clear ===
<div {{log}}>
<div {{log}}>
clear
goto "MainLabel"
</div>
</div>
*'''Returns:''' (has no return value, the current execution stack is discarded and the jump never returns)
*'''Returns:''' an array of strings (possible for the return array to be empty, but unlikely)
*'''Description:''' Empties ALL unchecked input to the script from ALL queues (normal game stack, unique script stack and upstream stack); the return value is whatever was in the game data stack before it was cleared (which could be nothing, in which case the return is an empty array).
*'''Description:''' Identical to standard Wizard/SF scripts; the label to jump to has to be in quotes, and its case insensitive. The label declaration itself (the LABEL: line) MUST NOT be in quotes: only the name of the label when you use the goto command. If a label called "main" and a label called "Main" (with a capital) both exist, then using GOTO to jump to the "main" label would jump there -- however, if you tried to jump to the "Main" label, it would jump to the capital-letter one instead (basically if there are two labels with the same name but different capitalizations, the goto command starts acting as though its case sensitive).


== Wait ==


== wait ==
=== wait ===
<div {{log}}>
<div {{log}}>
wait
wait
Line 76: Line 164:
*'''Description:''' Identical to Wizard; waits until a line from the game is seen. Returns the line (in actuality this command simply clears the game stack and executes a 'get').
*'''Description:''' Identical to Wizard; waits until a line from the game is seen. Returns the line (in actuality this command simply clears the game stack and executes a 'get').


== waitrt ==
=== waitrt ===
<div {{log}}>
<div {{log}}>
waitrt
waitrt
Line 83: Line 171:
*'''Description:''' Pauses for however many seconds you're currently in roundtime for. Return value is how many seconds paused. Waits until you're in roundtime if you aren't at the time this command is used, and therefore can hang endlessly.
*'''Description:''' Pauses for however many seconds you're currently in roundtime for. Return value is how many seconds paused. Waits until you're in roundtime if you aren't at the time this command is used, and therefore can hang endlessly.


== waitrt? ==
=== waitrt? ===
<div {{log}}>
<div {{log}}>
waitrt?
waitrt?
Line 89: Line 177:
*'''Returns:''' an integer (Fixnum class)
*'''Returns:''' an integer (Fixnum class)
*'''Description:''' Identical to 'waitrt', but does not wait until you're in roundtime and as such will not hang (but will not wait for any roundtime if the game hasn't sent that you're in roundtime yet).
*'''Description:''' Identical to 'waitrt', but does not wait until you're in roundtime and as such will not hang (but will not wait for any roundtime if the game hasn't sent that you're in roundtime yet).
*'''Note:''' Zero is a value, and ALL values in Ruby are evaluated to true, EXCEPT for FALSE and NIL. This means that !waitrt? will not do do a proper true/false check like it might in other languages.


== waitcastrt ==
=== waitcastrt ===
<div {{log}}>
<div {{log}}>
waitcastrt
waitcastrt
Line 97: Line 186:
*'''Description:''' Pauses for however many seconds you're currently in RT for. Return value is how many seconds paused. Waits until you're in RT if you aren't at the time this command is used, and therefore can hang endlessly.
*'''Description:''' Pauses for however many seconds you're currently in RT for. Return value is how many seconds paused. Waits until you're in RT if you aren't at the time this command is used, and therefore can hang endlessly.


== waitcastrt? ==
=== waitcastrt? ===
<div {{log}}>
<div {{log}}>
waitcastrt?
waitcastrt?
Line 103: Line 192:
*'''Returns:''' an integer (Fixnum class)
*'''Returns:''' an integer (Fixnum class)
*'''Description:''' Identical to 'waitcastrt', but does not wait until you're in cast roundtime and as such will not hang (but will not wait for any cast roundtime if the game hasn't sent that you're in cast roundtime yet).
*'''Description:''' Identical to 'waitcastrt', but does not wait until you're in cast roundtime and as such will not hang (but will not wait for any cast roundtime if the game hasn't sent that you're in cast roundtime yet).
*'''Note:''' Zero is a value, and ALL values in Ruby are evaluated to true, EXCEPT for FALSE and NIL. This means that !waitcastrt? will not do do a proper true/false check like it might in other languages.


== waitfor ==
=== waitfor ===
<div {{log}}>
<div {{log}}>
waitfor " just arrived.", "More lines to waitfor if you desire", "endlessly"
waitfor " just arrived.", "More lines to waitfor if you desire", "endlessly"
Line 111: Line 201:
*'''Description:''' Waits until a line from the game includes the string you gave it as an argument. The return value is the complete string from the game (in the example used here, if Shaelun entered the room, the command would return "Shaelun just arrived."). 'waitfor' is case insensitive (capital letters are considered matches even if the string it was given didn't have a capital letter there).
*'''Description:''' Waits until a line from the game includes the string you gave it as an argument. The return value is the complete string from the game (in the example used here, if Shaelun entered the room, the command would return "Shaelun just arrived."). 'waitfor' is case insensitive (capital letters are considered matches even if the string it was given didn't have a capital letter there).


== unique_waitfor ==
=== wait_while ===
<div {{log}}>
unique_waitfor "continue"
</div>
*'''Returns:''' a string
*'''Description:''' Same as 'waitfor' but acts on the 'unique' queue.

== wait_while ==
<div {{log}}>
<div {{log}}>
wait_while { percenthealth != 100 }
wait_while { percenthealth != 100 }
</div>
</div>
<div {{log}}>
<div {{log}}>
wait_while "You do not have full health: waiting until you do." { percenthealth != 100 }
wait_while("You do not have full health: waiting until you do.") { percenthealth != 100 }
</div>
</div>
*'''Returns:''' true/false
*'''Returns:''' true/false
*'''Synonyms:''' all the variants of `Wounds.(bodypart)' are the same for `Scars.(bodypart)'
*'''Description:''' The script will wait while the given code block has a logical value of 'true', and will only continue on to the next line when/if the code block has a value of 'false'. If given the optional string to announce to the user, it will only display that string if it's going to be sitting there waiting for something -- if the command will not be waiting at all, it doesn't display the string to the user. Note that there's no limit to how long/complicated the code block can be; it was designed for very short logical comparisons like the example above, but need not be used that way.
*'''Description:''' The script will wait while the given code block has a logical value of 'true', and will only continue on to the next line when/if the code block has a value of 'false'. If given the optional string to announce to the user, it will only display that string if it's going to be sitting there waiting for something -- if the command will not be waiting at all, it doesn't display the string to the user. Note that there's no limit to how long/complicated the code block can be; it was designed for very short logical comparisons like the example above, but need not be used that way.


== wait_until ==
=== wait_until ===
<div {{log}}>
<div {{log}}>
wait_until { checkmana(50) }
wait_until("Waiting until 50 mana or more!") { checkmana(50) }
</div>
</div>
*'''Returns:''' true/false
*'''Returns:''' true/false
*'''Description:''' Identical in all ways to 'wait_while', but does the opposite (waits UNTIL the given code block is true, not WHILE it's true). Also takes the optional string if desired.
*'''Description:''' Identical in all ways to 'wait_while', but does the opposite (waits UNTIL the given code block is true, not WHILE it's true). Also takes the optional string if desired.


== upstream_get ==
== Match ==
<div {{log}}>
upstream_get
</div>
*'''Returns:''' a string
*'''Description:''' Same thing as "get" except it fetches the last line the user sent to the game. A script has to ask Lich to give it this information by first using the "toggle_upstream" command.


Wizard-style "match" commands
== toggle_upstream ==

=== matchtimeout ===
<div {{log}}>
<div {{log}}>
matchtimeout 5, "string to watch for", "another", "endlessly"
toggle_upstream
</div>
</div>
*'''Returns:''' updated value of the "upstream" flag (true/false)
*'''Returns:''' a string, or false
*'''Description:''' Same as 'waitfor', but if a match isn't seen in the given amount of time, returns a value of 'false' and the script will move on.
*'''Description:''' See above.


== upstream_waitfor ==
=== matchwait ===
<div {{log}}>
<div {{log}}>
upstream_waitfor "climb stairs"
</div>
</div>
*'''Returns:''' a string
*'''Returns:''' a string
*'''Description:''' If used without any arguments, 100% identical to Wizard 'matchwait' commands. You can optionally give it arguments, in which case it acts identically to 'waitfor' in all ways except one: matches are case sensitive (for instance, matchwait "shaelun" will not match if the word "Shaelun" is seen from the game).
*'''Description:''' Identical to "waitfor" but only checks the upstream commands (the commands sent to the game by the user).


== undo_before_dying ==
=== match ===
<div {{log}}>
<div {{log}}>
match 'label', 'line to watch for'
undo_before_dying
</div>
</div>
*'''Returns:''' nothing useful
*'''Description:''' Clears any "before_dying" code blocks that have been used. If none have been used, does nothing (see the 'before_dying' command).

== abort! ==
<div {{log}}>
<div {{log}}>
match "gameline", "gameline", "some other gameline", "so on and so forth"
abort!
</div>
</div>
*'''Returns:''' never returns
*'''Returns:''' a string
*'''Description:''' If given exactly two arguments, identical to the Wizard 'match' command. If given *any* other number of arguments, it's a case sensitive version of 'waitfor' but instead of returning the entire matching game line, it returns only the portion of the string you asked it to watch for.
*'''Description:''' Immediately kills the script, bypassing any 'before_dying' blocks that have been registered. Probably won't ever be of use, but it's a way to make the calling script go away as fast as possible (note that it isn't any faster than the 'exit' command is, it just makes sure that nothing except stopping the script happens).


== watchhealth ==
=== matchfind ===
<div {{log}}>
<div {{log}}>
matchfind "A ? attacks you!", "A ? swings a ? at you!"
watchhealth(50) { echo "Uh, your health is below 50..." }
</div>
</div>
<div {{log}}>
<div {{log}}>
person, weapon = matchfind "? swings a ? at you!"
watchhealth(50, proc_object)
</div>
</div>
*'''Returns:''' nothing useful
*'''Returns:''' a string or an array
*'''Description:''' Same as 'waitfor', but returns only the portion of the line where the question mark(s) are. If given multiple question marks, returns an array containing the portions of the string (in order). Note that if you assign multiple variables to equal a single array, the array's elements are used in order and assigned to each variable (if there are fewer elements in the array than there are variables being assigned, variables receive a value of 'nil', and if there are more elements in the array than there are variables being assigned, the last variable is assigned an array with the remaining values). This is why the above usage example works (person, weapon =).
*'''Description:''' Returns immediately so that the calling script continues to run as normal, and while it does, monitors your health. If it falls below the number you give it, executes the block you passed to it. Only does this once -- if you want it to repeat as the script executes (be careful, chances are your health will still be below 50 after the block executes once) then pass watchhealth a proc object that includes a line registering itself over again (as in, a proc that includes a 'watchhealth(#, self)' thingie). If your health never falls below the number you give it, then nothing happens; once the script ends, it stops watching.


== checkoutside ==
=== matchfindword ===
<div {{log}}>
<div {{log}}>
weapon = matchfindword "Shaelun swings a ? at you!"
checkoutside
</div>
</div>
*'''Returns:''' a string (single word)
<div {{log}}>
*'''Description:''' Identical to 'matchfind', but only looks for a single word where the question marks are. Note that a line won't match if more than one word is where the question mark is (in the above example, if the weapon were a "broadsword" it would match, but if it were a "sonic hammer of kai" there would be no match).
outside?
</div>
*'''Returns:''' true/false
*'''Synonyms:''' outside?
*'''Description:''' Really simple, just returns true if you're outside, false if you aren't. Probably only of use to rangers writing their own spellup scripts or something, but either way: it's available if you have a use for it.


== Settings.load ==
=== matchfindexact ===
<div {{log}}>
<div {{log}}>
matchfindexact "? just arrived."
Settings.load
</div>
</div>
*'''Returns:''' a string
<div {{log}}>
*'''Description:''' Version of matchfind meant for use in special cases; matchfind is very forgiving and will return and match anything (case insensitively) -- matchfindexact is very strict. It is case sensitive and cares about things like spaces, word boundaries (partial pieces of a word will not match, only whole words), the case of the string it's looking for, etc.. Use it if you need to use matchfind and want to make sure only a very specific line matches.
Settings["SettingName"]
</div>
<div {{log}}>
Settings.save
</div>
<div {{log}}>
Settings.clear
</div>
*'''Returns:''' either a hash representing your settings, or 'nil' if no settings for the script exist
*'''Description:''' Note that Settings.clear will erase all settings, but it will NOT save that on its own. Issue a Settings.save command after the Settings.clear if you want that script's settings reset permanently.


== toggle_unique ==
<div {{log}}>
toggle_unique
</div>
*'''Returns:''' updated value of the 'unique' setting (true or false)
*'''Description:''' When a script is set as being 'unique', it does not receive normal game data; instead it only receives what the user sends to it by typing ;send to (script) (message). This is of use if a script wants to only act on a user's input or has no use for game data (it provides a method for scripts to make sure game data doesn't accidentally get recognized as a user's input, and also serves to prevent scripts from slowly eating away at system resources because the script never checks or clears its data buffer -- see the 'clear' command for more on that).


== no_kill_all ==
== Room ==

=== checkarea ===
<div {{log}}>
<div {{log}}>
checkarea
no_kill_all
</div>
</div>
*'''Returns:''' updated value of the 'no_kill_all' setting (true or false)
*'''Description:''' Toggles on/off the 'no kill all' setting: when this setting is on (defaults to off), a script will not be effected by the user typing ;kill all. A script with this set to on must be killed specifically (by typing ;kill [script], or just ;kill). There is no way to prevent a script from being killed when targetted by the user.

== silence_me ==
<div {{log}}>
<div {{log}}>
checkarea "illistim"
silence_me
</div>
</div>
*'''Returns:''' new value of the 'silenced' setting (true or false)
*'''Returns:''' a string, or true or false
*'''Description:''' By itself returns the geographical area of your current room, or if given a string to check for, returns true or false based on whether your current area matches the string or not.
*'''Description:''' Toggles on/off the 'silenced' setting. A script with this on will not have commands it sends to the game echoed to your game window. A script run in SAFE mode cannot change this setting (attempting to do so will generate a warning and otherwise have no effect).


== toggle_echo ==
=== checkroom ===
<div {{log}}>
<div {{log}}>
checkroom
toggle_echo
</div>
</div>
*'''Returns:''' new value of the 'suppress echo' setting (true or false)
*'''Description:''' Toggles on/off the 'suppress echo' setting. A script with this on will not execute any 'echo' commands, but will silently ignore them instead; it's designed more for people who don't want clutter in their game window but still want to make use of an existing script. Commands sent to the game are still echoed to the game window.

== checkpoison ==
<div {{log}}>
<div {{log}}>
checkroom "table"
checkpoison
</div>
</div>
*'''Returns:''' true/false
*'''Returns:''' true or false, or a string
*'''Description:''' See checkdisease.
*'''Description:''' Identical to checkarea, but uses the room title instead of the geographical area.


== checkdisease ==
=== checkpaths ===
<div {{log}}>
<div {{log}}>
checkpaths
checkdisease
</div>
</div>
*'''Returns:''' true/false
*'''Description:''' See checkpoison.

== get ==
<div {{log}}>
<div {{log}}>
checkpaths 'nw'
get
</div>
</div>
*'''Returns:''' a string
*'''Returns:''' an array of strings, or true/false
*'''Description:''' Fetches the next un-checked line of game data (while a script is running, it is given every game line, and these lines are available for a script to check/use at its leisure).
*'''Description:''' Returns an array consisting of the current 'Obvious exits:' directions if given no argument, or true/false based on whether all arguments given are currently available as exits or not.


== unique_get ==
=== checkoutside ===
<div {{log}}>
<div {{log}}>
checkoutside
unique_get
</div>
</div>
*'''Returns:''' a string
*'''Description:''' Fetches a line from the unique stack, as opposed to the game data stack (see 'toggle_unique' for more about what the 'unique' stack refers to).

== send_to_script ==
<div {{log}}>
<div {{log}}>
outside?
send_to_script 'scriptname', 'message to send'
</div>
</div>
*'''Returns:''' true or false
*'''Returns:''' true/false
*'''Synonyms:''' outside?
*'''Description:''' The target script will be sent a string exactly as though it came from the game. Returns true if successful, false if the script wasn't found to be active.
*'''Description:''' Really simple, just returns true if you're outside, false if you aren't. Probably only of use to rangers writing their own spellup scripts or something, but either way: it's available if you have a use for it.


== unique_send_to_script ==
=== checknpcs ===
<div {{log}}>
<div {{log}}>
if checknpcs
unique_send_to_script 'scriptname', 'message to send'
fput "attack"
end
</div>
</div>
*'''Returns:''' true or false
*'''Description:''' Same as 'send_to_script', but the script will receive the string sent in its 'unique' stack instead of its 'game data' stack (see 'toggle_unique' for more info).

== move ==
<div {{log}}>
<div {{log}}>
if checknpcs "big monster of doom", "small monster of doom"
move 'northwest'
put "Oh noes!"
end
</div>
</div>
*'''Returns:''' true or false
*'''Description:''' Same as the Wizard 'move' command, but it will usually compensate for things like type ahead errors, RT, currently stunned, etc.; will also stand and re-attempt the movement if it's detected to be necessary. Returns 'true' if the move was executed properly, 'false' if it wasn't able to be performed (which is very rare due to the move command's error compensation measures).

== multimove ==
<div {{log}}>
<div {{log}}>
for npc in checknpcs
multimove 'nw', 'ne', 'go hole', 'climb stairs'
put "greet #{npc}"
end
</div>
</div>
*'''Returns:''' true or false
*'''Returns:''' an array of strings, a string, or nil
*'''Description:''' If checknpcs is used without giving it npcs to check for, it returns an array of strings coresponding to the noun of each npc in the room, or nil if there are no npcs (does not return an empty array, so you can use "if checknpcs"). If chekcnpcs is given npcs to look for, it returns a string of the first matching npc it finds, or nil if none matched (any string evaluates to true, only nil and false evaluate to false in an if statement).
*'''Description:''' Takes multiple directions to move in and executes the 'move' command for each one. Returns the value of the last 'move' command executed (true or false).


== fetchloot ==
=== checkpcs ===
<div {{log}}>
<div {{log}}>
checkpcs
fetchloot
</div>
</div>
*'''Returns:''' a string
*'''Description:''' Performs a 'look' and takes/puts away all items on the ground that aren't listed in your 'excludeloot:' setting. Return value is the last line from the game.

== Lich.fetchloot ==
<div {{log}}>
<div {{log}}>
checkpcs "shaelun"
Lich.fetchloot
</div>
</div>
*'''Returns:''' a string
*'''Returns:''' array of strings, or true/false
*'''Description:''' Identical to 'fetchloot' in all ways except only the items listed in your 'treasure:' setting are fetched.
*'''Description:''' Identical to 'checknpcs', but with the players currently present.


== checkloot ==
=== checkloot ===
<div {{log}}>
<div {{log}}>
checkloot
checkloot
Line 313: Line 349:
*'''Description:''' Returns an array consisting of the items currently in the room.
*'''Description:''' Returns an array consisting of the items currently in the room.



== take ==
== Familiars ==

=== checkfamarea/checkfamroom ===
<div {{log}}>
<div {{log}}>
checkfamarea
take "box", "coffer", "ruby", "etc"
</div>
</div>
<div {{log}}>
*'''Returns:''' a string (the last line the 'fput' command saw)
checkfamarea "illistim"
*'''Description:''' Picks up every item listed and puts each one in turn into your 'lootsack:' setting by issuing the commands with fput.
</div>
*'''Returns:''' a string, or true/false
*'''Description:''' Identical to checkarea/checkroom, but check your familiar's current location instead of yours (only in Wizard and only if you have a familiar).


== checkpaths ==
=== checkfampcs ===
<div {{log}}>
<div {{log}}>
checkfampcs "shaelun"
checkpaths
</div>
</div>
<div {{log}}>
<div {{log}}>
checkfampcs
checkpaths 'nw'
</div>
</div>
*'''Returns:''' an array of strings, or true/false
*'''Returns:''' array of strings, or true/false
*'''Synonyms:''' checkfamnpcs
*'''Description:''' Returns an array consisting of the current 'Obvious exits:' directions if given no argument, or true/false based on whether all arguments given are currently available as exits or not.
*'''Description:''' Identical to the above two, but tracks for your familiar's room instead. Not available in SF as of v3.06.



== walk ==
== Character ==

=== checkpoison ===
<div {{log}}>
<div {{log}}>
checkpoison
walk
</div>
</div>
*'''Returns:''' true or false
*'''Returns:''' true/false
*'''Description:''' See checkdisease.
*'''Description:''' Moves in a random cardinal direction (what's seen in the 'Obvious exits:' line), storing the direction moved, and returning 'true' if there is a critter in the room or 'false' if there aren't any NPCs in the room. The stored direction will not be among the random directions chosen the next time the 'walk' command is used (unless it hits a dead-end, then it will backtrack the way it came).


== run ==
=== checkdisease ===
<div {{log}}>
<div {{log}}>
checkdisease
run if not health(50)
</div>
</div>
*'''Returns:''' true or false
*'''Returns:''' true/false
*'''Description:''' See checkpoison.
*'''Description:''' Will execute a 'walk' command repeatedly until it enters a room with no critters, at which point it returns and the script will pick up execution on the next line (does not continue to run away).


== checkfried ==
=== checkfried ===
<div {{log}}>
<div {{log}}>
checkfried
checkfried
Line 351: Line 397:
*'''Description:''' Returns true if you're fried, false if not.
*'''Description:''' Returns true if you're fried, false if not.


== checkmind ==
=== checkmind ===
<div {{log}}>
<div {{log}}>
checkmind
checkmind
Line 361: Line 407:
*'''Description:''' By itself returns a string representing the level of exp in your head ('clear as a bell', 'fried', 'muddled', etc). If given an integer, returns true or false if you have the corresponding level of exp in your head, with 0 being 'clear as a bell', 1 being 'fresh and clear', etc.
*'''Description:''' By itself returns a string representing the level of exp in your head ('clear as a bell', 'fried', 'muddled', etc). If given an integer, returns true or false if you have the corresponding level of exp in your head, with 0 being 'clear as a bell', 1 being 'fresh and clear', etc.


== check_mind ==
=== check_mind ===
<div {{log}}>
<div {{log}}>
check_mind
check_mind
Line 371: Line 417:
*'''Description:''' By itself returns a string representing the level of exp in your head ('clear as a bell', 'fried', 'muddled', etc). If given an integer, returns true or false if you have the corresponding percentage of exp in your head.
*'''Description:''' By itself returns a string representing the level of exp in your head ('clear as a bell', 'fried', 'muddled', etc). If given an integer, returns true or false if you have the corresponding percentage of exp in your head.


== percentmind ==
=== percentmind ===
<div {{log}}>
<div {{log}}>
percentmind
percentmind
Line 381: Line 427:
*'''Description:''' By itself returns an integer ranging from 0-100 representing the percentage of exp in your head. If given an integer, returns true or false if you have at least that percentage of experience. Both saturated and fried show up as 100 percent - a user interested in distinguishing between the two can add a checksaturated or saturated? qualifier to their percentmind check.
*'''Description:''' By itself returns an integer ranging from 0-100 representing the percentage of exp in your head. If given an integer, returns true or false if you have at least that percentage of experience. Both saturated and fried show up as 100 percent - a user interested in distinguishing between the two can add a checksaturated or saturated? qualifier to their percentmind check.


== checkarea ==
=== checkright/checkleft ===
<div {{log}}>
<div {{log}}>
checkright
checkarea
</div>
</div>
<div {{log}}>
<div {{log}}>
checkleft "broadsword"
checkarea "illistim"
</div>
*'''Returns:''' a string, or true or false
*'''Description:''' By itself returns the geographical area of your current room, or if given a string to check for, returns true or false based on whether your current area matches the string or not.

== checkroom ==
<div {{log}}>
checkroom
</div>
<div {{log}}>
checkroom "table"
</div>
</div>
*'''Returns:''' true or false, or a string
*'''Returns:''' true or false, or a string
*'''Synonyms:''' righthand?/lefthand?
*'''Description:''' Identical to checkarea, but uses the room title instead of the geographical area.
*'''Description:''' Give them a string and will return true/false if it matches what you're holding, or the last word in the item name if used by itself. If your hands are currently empty, it will return 'nil' (identical to 'false' in a logical comparison) regardless of whether it was given an argument or not. This behavior can be useful to make absolutely certain a 'take' command succeeded, for instance.


=== checkstance ===
== checkfamarea/checkfamroom ==
<div {{log}}>
<div {{log}}>
checkstance
checkfamarea
</div>
</div>
<div {{log}}>
<div {{log}}>
checkstance "offensive"
checkfamarea "illistim"
</div>
</div>
*'''Returns:''' a string, or true/false
*'''Description:''' Identical to checkarea/checkroom, but check your familiar's current location instead of yours (only in Wizard and only if you have a familiar).

== checkright/checkleft ==
<div {{log}}>
<div {{log}}>
checkstance 0
checkright
</div>
<div {{log}}>
checkleft "broadsword"
</div>
</div>
*'''Returns:''' true or false, or a string
*'''Returns:''' true or false, or a string
*'''Synonyms:''' righthand?/lefthand?
*'''Synonyms:''' stance
*'''Description:''' With no arguments, returns the string representing your current stance. With a numerical or string argument, returns a boolean flag indicating if the current stance matches the given string. For string based comparisons, this will correctly test against the stance values possible if using [[Combat Mastery]] or [[[[Warrior_Tricks#Stance_Perfection|Stance Perfection]]]], while integer based arguments will perform a precise comparison.
*'''Description:''' Give them a string and will return true/false if it matches what you're holding, or the last word in the item name if used by itself. If your hands are currently empty, it will return 'nil' (identical to 'false' in a logical comparison) regardless of whether it was given an argument or not. This behavior can be useful to make absolutely certain a 'take' command succeeded, for instance.


== check(thing) ==
=== check(thing) ===
<div {{log}}>
<div {{log}}>
checkstanding
checkstanding
Line 436: Line 466:
*'''Description:''' Most are true if you are (checkstunned for example), false if you aren't; they all follow the same basic behavior as the above-documented 'check' commands.
*'''Description:''' Most are true if you are (checkstunned for example), false if you aren't; they all follow the same basic behavior as the above-documented 'check' commands.


== checkname ==
=== checkname ===
<div {{log}}>
<div {{log}}>
checkname
checkname
Line 446: Line 476:
*'''Description:''' True/false if given a string and the names match, or just returns the character name if given no arguments.
*'''Description:''' True/false if given a string and the names match, or just returns the character name if given no arguments.


== checknpcs ==
=== checkstamina ===
<div {{log}}>
<div {{log}}>
checkstamina 50
if checknpcs
fput "attack"
end
</div>
</div>
<div {{log}}>
<div {{log}}>
checkstamina
if checknpcs "big monster of doom", "small monster of doom"
put "Oh noes!"
end
</div>
</div>
*'''Returns:''' true/false or an integer
*'''Description:''' Only in StormFront (there is no auto-updated stamina tag in Wizard). Given no arguments, returns your current stamina. Given a number, returns true/false based on whether you have at least or more than that number.

=== checkrt / checkcastrt ===
<div {{log}}>
<div {{log}}>
checkrt
for npc in checknpcs
put "greet #{npc}"
end
</div>
</div>
<div {{log}}>
*'''Returns:''' an array of strings, a string, or nil
checkcastrt
*'''Description:''' If checknpcs is used without giving it npcs to check for, it returns an array of strings coresponding to the noun of each npc in the room, or nil if there are no npcs (does not return an empty array, so you can use "if checknpcs"). If chekcnpcs is given npcs to look for, it returns a string of the first matching npc it finds, or nil if none matched (any string evaluates to true, only nil and false evaluate to false in an if statement).
</div>
*'''Returns:''' value of roundtime
*'''Description:''' Returns a value of how much roundtime left. Useful for IF statements.


=== checkmana/checkhealth/checkspirit ===
== checkpcs ==
<div {{log}}>
<div {{log}}>
checkmana 50
checkpcs
</div>
</div>
*'''Returns:''' identical as above
*'''Synonyms:''' health, health?, mana, mana?, spirit, spirit?
*'''Description:''' Identical to checkstamina.

=== maxhealth/maxstamina/maxmana/maxspirit ===
<div {{log}}>
<div {{log}}>
fput "eat my acantha leaf" while (checkhealth < maxhealth)
checkpcs "shaelun"
</div>
</div>
*'''Returns:''' array of strings, or true/false
*'''Returns:''' integer
*'''Description:''' Identical to 'checknpcs', but with the players currently present.
*'''Description:''' Returns your maximum health/spirit/stamina/mana as an integer (class Fixnum). Takes no arguments.


=== percenthealth/percentmana/percentspirit/percentstamina ===
== checkfampcs ==
<div {{log}}>
<div {{log}}>
fput "eat my acantha leaf" while (percenthealth < 90)
checkfampcs "shaelun"
</div>
</div>
*'''Returns:''' integer
*'''Description:''' Returns an integer (0-100) representing the percentage of your current health/mana/whatever in relation to your max.

=== checkspell ===
<div {{log}}>
<div {{log}}>
checkspell "elemental defense i"
checkfampcs
</div>
</div>
*'''Returns:''' array of strings, or true/false
*'''Returns:''' true/false
*'''Synonyms:''' checkfamnpcs
*'''Synonyms:''' active?
*'''Description:''' Identical to the above two, but tracks for your familiar's room instead. Not available in SF as of v3.06.
*'''Description:''' Returns true if the spell you give it is active, false if it isn't (only available if you use the infomon script, since that's what keeps track of this).


== checkstamina ==
=== Wounds ===
<div {{log}}>
<div {{log}}>
Wounds.torso
checkstamina 50
</div>
</div>
<div {{log}}>
<div {{log}}>
Wounds.neck
checkstamina
</div>
</div>
<div {{log}}>
*'''Returns:''' true/false or an integer
Wounds.lhand
*'''Description:''' Only in StormFront (there is no auto-updated stamina tag in Wizard). Given no arguments, returns your current stamina. Given a number, returns true/false based on whether you have at least or more than that number.
</div>
*'''Returns:''' an integer
*'''Variations:''' Wounds.head; Wounds.neck; Wounds.abs; Wounds.lhand; Wounds.rhand; Wounds.larm; Wounds.rarm; Wounds.chest; Wounds.back; Wounds.rleg; Wounds.lleg; Wounds.nerves
*'''Description:''' Returns the current wound rank (numerically). If I had 'deep gashes and serious bleeding' on my chest, Wounds.chest would return the integer 3. If I had no wound there, it would return 0.


=== Scars ===
== checkmana/checkhealth/checkspirit ==
<div {{log}}>
<div {{log}}>
Scars.abs
checkmana 50
</div>
</div>
<div {{log}}>
*'''Returns:''' identical as above
Scars.nerves
*'''Synonyms:''' health, health?, mana, mana?, spirit, spirit?
</div>
*'''Description:''' Identical to checkstamina.
<div {{log}}>
Scars.rleg
</div>
*'''Returns:''' an integer
*'''Description:''' Identical to Wounds above, but for scars instead of wounds.



== clear ==
== Lich toggles ==

=== # QUIET ===
<div {{log}}>
<div {{log}}>
&#35; QUIET
clear
</div>
</div>
*'''Returns:''' n/a
*'''Returns:''' an array of strings (possible for the return array to be empty, but unlikely)
*'''Description:''' This is a special directive that must be a Ruby comment placed as above in the first line of the Lich script. Lich will ordinarily bookend the lifetime of a script with <code>--- Lich: (scriptname) active.</code> and <code>--- Lich: (scriptname) has exited.</code> This option omits those lines, allowing a script to start and exit silently.
*'''Description:''' Empties ALL unchecked input to the script from ALL queues (normal game stack, unique script stack and upstream stack); the return value is whatever was in the game data stack before it was cleared (which could be nothing, in which case the return is an empty array).

=== hide_me ===
<div {{log}}>
hide_me
</div>
*'''Returns:''' updated value of the setting (true/false)
*'''Description:''' Toggles on/off the 'hidden' setting. When this setting is on (defaults to off), a script will not be listed when the user types ;list. It will still show up under ;list all. There is no way to prevent a script from being being displayed in ;list all.


== i_stand_alone ==
=== i_stand_alone ===
<div {{log}}>
<div {{log}}>
i_stand_alone
i_stand_alone
Line 518: Line 577:
*'''Description:''' Toggles on/off. Removes a script from ALL data feeds; a script using this will receive no game lines and no unique data whatsoever (unless they toggle it back off). If Lich can more or less ignore that a script exists and not bother with keeping its data stacks up-to-the-second with game data and anything else it's requested, then a script has virtually no overhead whatsoever (meaning any resources it requires come only from what it does independantly). Useful for some scripts who have no need to eat up resources being fed game data (such as dict.lic).
*'''Description:''' Toggles on/off. Removes a script from ALL data feeds; a script using this will receive no game lines and no unique data whatsoever (unless they toggle it back off). If Lich can more or less ignore that a script exists and not bother with keeping its data stacks up-to-the-second with game data and anything else it's requested, then a script has virtually no overhead whatsoever (meaning any resources it requires come only from what it does independantly). Useful for some scripts who have no need to eat up resources being fed game data (such as dict.lic).


== matchtimeout ==
=== no_kill_all ===
<div {{log}}>
<div {{log}}>
no_kill_all
matchtimeout 5, "string to watch for", "another", "endlessly"
</div>
</div>
*'''Returns:''' a string, or false
*'''Returns:''' updated value of the setting (true/false)
*'''Description:''' Toggles on/off the 'no kill all' setting: when this setting is on (defaults to off), a script will not be affected by the user typing ;kill all. A script with this set to on must be killed specifically (by typing ;kill [script], or just ;kill). There is no way to prevent a script from being killed when targeted by the user.
*'''Description:''' Same as 'waitfor', but if a match isn't seen in the given amount of time, returns a value of 'false' and the script will move on.


== matchwait ==
=== no_pause_all ===
<div {{log}}>
<div {{log}}>
no_pause_all
</div>
</div>
*'''Returns:''' a string
*'''Returns:''' updated value of the setting (true/false)
*'''Description:''' Toggles on/off the 'no pause all' setting: when this setting is on (defaults to off), a script will not be affected by the user typing ;pause all. A script with this set to on must be killed specifically (by typing ;pause [script], or just ;pause). There is no way to prevent a script from being paused when targeted by the user.
*'''Description:''' If used without any arguments, 100% identical to Wizard 'matchwait' commands. You can optionally give it arguments, in which case it acts identically to 'waitfor' in all ways except one: matches are case sensitive (for instance, matchwait "shaelun" will not match if the word "Shaelun" is seen from the game).


== match ==
=== silence_me ===
<div {{log}}>
<div {{log}}>
silence_me
match 'label', 'line to watch for'
</div>
</div>
*'''Returns:''' updated value of the setting (true/false)
*'''Description:''' Toggles on/off the 'silenced' setting. A script with this on will not have commands it sends to the game echoed to your game window. A script run in SAFE mode cannot change this setting (attempting to do so will generate a warning and otherwise have no effect).

===status_tags===
<div {{log}}>
<div {{log}}>
status_tags
match "gameline", "gameline", "some other gameline", "so on and so forth"
</div>
</div>
*'''Returns:''' a string
*'''Returns:''' ?
*'''Description:'''Tells Lich to send this script XML tags rather than stripping them, or, if already doing so, tells Lich to go back to stripping the XML. If called with the argument "on" or "off", switches to that setting and echoes that it has done so.
*'''Description:''' If given exactly two arguments, identical to the Wizard 'match' command. If given *any* other number of arguments, it's a case sensitive version of 'waitfor' but instead of returning the entire matching game line, it returns only the portion of the string you asked it to watch for.


== matchfind ==
=== toggle_echo ===
<div {{log}}>
<div {{log}}>
toggle_echo
matchfind "A ? attacks you!", "A ? swings a ? at you!"
</div>
</div>
*'''Returns:''' updated value of the setting (true/false)
*'''Description:''' Toggles on/off the 'suppress echo' setting. A script with this on will not execute any 'echo' commands, but will silently ignore them instead; it's designed more for people who don't want clutter in their game window but still want to make use of an existing script. Commands sent to the game are still echoed to the game window.

=== toggle_unique ===
<div {{log}}>
<div {{log}}>
toggle_unique
person, weapon = matchfind "? swings a ? at you!"
</div>
</div>
*'''Returns:''' a string or an array
*'''Returns:''' updated value of the setting (true/false)
*'''Description:''' When a script is set as being 'unique', it does not receive normal game data; instead it only receives what the user sends to it by typing ;send to (script) (message). This is of use if a script wants to only act on a user's input or has no use for game data (it provides a method for scripts to make sure game data doesn't accidentally get recognized as a user's input, and also serves to prevent scripts from slowly eating away at system resources because the script never checks or clears its data buffer -- see the 'clear' command for more on that).
*'''Description:''' Same as 'waitfor', but returns only the portion of the line where the question mark(s) are. If given multiple question marks, returns an array containing the portions of the string (in order). Note that if you assign multiple variables to equal a single array, the array's elements are used in order and assigned to each variable (if there are fewer elements in the array than there are variables being assigned, variables receive a value of 'nil', and if there are more elements in the array than there are variables being assigned, the last variable is assigned an array with the remaining values). This is why the above usage example works (person, weapon =).


== matchfindword ==
=== toggle_upstream ===
<div {{log}}>
<div {{log}}>
toggle_upstream
weapon = matchfindword "Shaelun swings a ? at you!"
</div>
</div>
*'''Returns:''' a string (single word)
*'''Returns:''' updated value of the setting (true/false)
*'''Description:''' This must be enabled to allow the script to intercept what you send to the game. See the separate upstream section for more detail.
*'''Description:''' Identical to 'matchfind', but only looks for a single word where the question marks are. Note that a line won't match if more than one word is where the question mark is (in the above example, if the weapon were a "broadsword" it would match, but if it were a "sonic hammer of kai" there would be no match).


== matchfindexact ==
== Lich::Util ==
=== issue_command() ===
<div {{log}}>
<div {{log}}>
Lich::Util.issue_command(command, start_pattern, end_pattern = /<prompt/, include_end: true, timeout: 5, silent: nil, usexml: true, quiet: false)
matchfindexact "? just arrived."

Lich::Util.issue_command('tattoo menu', /List of flash tattoos available \(Page \d+\):/
</div>
</div>
*'''Returns:''' a string
*'''Returns:''' returns result as an array of strings.
*'''Description:''' Will attempt to issue the command(string) given and capture the returning output from the begging start_pattern(regex) until the end_pattern(regex) is seen or the timeout(int) is reached. include_end(booleen) will indicate whether the last line of the end_pattern is included in the array. silent(boolean) will determine if the command is sent silently or echo'd to the frontend. usexml determines whether the start/end pattern is matching against the xml feed or plain txt feed. quiet flag determines whether the output is squelched or shown to the front end. The only required values needed are command and start_pattern. Everything else has default values that can be used or changed.
*'''Description:''' Version of matchfind meant for use in special cases; matchfind is very forgiving and will return and match anything (case insensitively) -- matchfindexact is very strict. It is case sensitive and cares about things like spaces, word boundaries (partial pieces of a word will not match, only whole words), the case of the string it's looking for, etc.. Use it if you need to use matchfind and want to make sure only a very specific line matches.


== send_scripts ==
=== quiet_command_xml() ===
<div {{log}}>
<div {{log}}>
Lich::Util.quiet_command_xml(command, start_pattern, end_pattern = /<prompt/, include_end = true, timeout = 5, silent = true)
send_scripts "To the running scripts, this line looks identical to one that came from the game"

Lich::Util.quiet_command_xml("tattoo menu", /List of flash tattoos available \(Page \d+\):/)
</div>
</div>
*'''Returns:''' true/false
*'''Returns:''' returns result as an array of strings.
*'''Description:''' Will attempt to issue the command(string) given and capture XML buffer lines once the start_pattern(regex) is seen till the end_pattern(regex) is seen or the timeout(int) is reached. include_end(booleen) will indicate whether the last line of the end_pattern is included in the array. silent(boolean) will determine if the command is sent silently or echo'd to the frontend. end_pattern, include_end, timeout, and silent do not need to be included unless changing the default values.
*'''Description:''' Same as 'send_to_script', but sends a line to all scripts instead of just one.


== regetall ==
=== quiet_command() ===
<div {{log}}>
<div {{log}}>
Lich::Util.quiet_command(command, start_pattern, end_pattern, include_end = true, timeout = 5, silent = true)
regetall "Shaelun"

Lich::Util.quiet_command("tattoo menu", /List of flash tattoos available \(Page \d+\):/, end_pattern = /Type TATTOO MENU again in the next minute to display the next group of flash tattoos\./)
</div>
</div>
*'''Returns:''' an array of strings, or nil
*'''Returns:''' returns result as an array of strings.
*'''Description:''' Will attempt to issue the command(string) given and capture buffer lines once the start_pattern(regex) is seen till the end_pattern(regex) is seen or the timeout(int) is reached. include_end(booleen) will indicate whether the last line of the end_pattern is included in the array. silent(boolean) will determine if the command is sent silently or echo'd to the frontend. include_end, timeout, and silent do not need to be included unless changing the default values.
*'''Description:''' Takes a string and returns an array of all game lines (since login) that match as having contained the given string (absolutely every single line since you logged in, Lich remembers them all). If a script is set as receiving the status data that doesn't show in the game window, those lines are also matched for; if the script is only being fed normal game data, that's the only history this command checks. If no matching lines were found, returns 'nil' (which is false in a logical comparison). As well as returning the matches, it also adds them to the script's game data stack so that subsequent 'get' commands will fetch them in order. The string to match for is actually optional, and if omitted, all lines are considered 'matching'.


== reget ==
=== silver_count() ===
<div {{log}}>
<div {{log}}>
Lich::Util.silver_count(timeout = 3)
reget 3

Lich::Util.silver_count
</div>
</div>
*'''Returns:''' an integer of how much silver you have
*'''Description:''' useful to know the amount of silver one has on themselves.

== Lich::Messaging ==

=== monsterbold ===
<div {{log}}>
<div {{log}}>
Lich::Messaging.monsterbold(msg)
reget 5, "Shaelun"

Lich::Messaging.monsterbold("This text I want to monsterbold")
</div>
</div>
*'''Returns:''' an array of strings, or nil
*'''Returns:''' an encoded string with proper monsterbold tags depending on FrontEnd used
*'''Description:''' Will take the string given and return it with monsterbold before/after and xml_encode the msg.
*'''Description:''' Similar to 'regetall' in behavior, but it only checks the current RAM cache (every 2 minutes, Lich's 'memory' of game data is emptied out of RAM and stored in a temporary file on the hard disk so that the program doesn't take up more resources than is necessary -- these files are deleted when the program closes); it also takes an optional integer, which represents how many game lines back to check ('reget 5' would scan the last 5 lines from the game that are still in RAM). If the integer is omitted, will scan the entire existing RAM buffer (again, cleared every 2 minutes).


== multifput ==
=== msg_format ===
<div {{log}}>
<div {{log}}>
Lich::Messaging.msg_format(type, msg)
multifput "stance offensive", "incant 910", "stance defensive"

Lich::Messaging.msg_format("info", "Let's make this text pretty!")
</div>
</div>
*'''Returns:''' a string (return value of the last 'fput' executed)
*'''Returns:''' an encoded string with start and end tags to change the color in the FrontEnd
*'''Description:''' Takes multiple strings and executes an 'fput' command for every one sequentially.
*'''Description:''' Returns the string given with color coding based on the type chosen. Current options are as follows:
** error, yellow, bold, monster, creature
** warn, orange, gold, thought
** info, teal, whisper
** green, speech, debug, light green


== kill_script ==
=== msg ===
<div {{log}}>
<div {{log}}>
Lich::Messaging.msg(type, msg)
kill_script "test"

Lich::Messaging.msg("info", "Let's make this text pretty!")
</div>
*'''Description:''' sends the string given to the client encoded for the type given.

=== stream_window ===
<div {{log}}>
Lich::Messaging.stream_window(msg, window)

Lich::Messaging.stream_window("Let's send this to a different window!", "familiar")
</div>
*'''Description:''' send the string to the various stream window. Currently supports the familiar, speech, thoughts and loot window.

=== xml_encode ===
<div {{log}}>
Lich::Messaging.xml_encode(msg)

Lich::Messaging.xml("Let's encode some text!")
</div>
*'''Returns:''' an xml encoded text

=== mono ===
<div {{log}}>
Lich::Messaging.mono(msg)

Lich::Messaging.mono("Let's mono some code!")
</div>
*'''Returns:''' force mono formatted string to be displayed properly using XML output class of mono

== Settings ==

Settings are specific to the script itself. For example, a setting with the name "bank" in fetch_turnips.lic have no effect on the "bank" setting in buy_cheese.lic.

=== Settings.load ===
<div {{log}}>
Settings.load
</div>

=== Settings["SettingName"] ===
<div {{log}}>
Settings["SettingName"]
</div>

=== Settings.save ===
<div {{log}}>
Settings.save
</div>

=== Settings.clear ===
<div {{log}}>
Settings.clear
</div>
*'''Returns:''' either a hash representing your settings, or 'nil' if no settings for the script exist
*'''Description:''' Note that Settings.clear will erase all settings, but it will NOT save that on its own. Issue a Settings.save command after the Settings.clear if you want that script's settings reset permanently.


== Upstream ==

=== upstream_get ===
<div {{log}}>
upstream_get
</div>
*'''Returns:''' a string
*'''Description:''' Same thing as "get" except it fetches the last line the user sent to the game. A script has to ask Lich to give it this information by first using the "toggle_upstream" command.

=== upstream_get? ===
<div {{log}}>
upstream_get?
</div>
*'''Returns:''' a string
*'''Description:''' Attempts to get the last line the user sent to the game, but does not wait for a line to be sent. A script has to ask Lich to give it this information by first using the "toggle_upstream" command.

=== upstream_waitfor ===
<div {{log}}>
upstream_waitfor "climb stairs"
</div>
*'''Returns:''' a string
*'''Description:''' Identical to "waitfor" but only checks the upstream commands (the commands sent to the game by the user).


== Interscript communication ==

=== running? ===
<div {{log}}>
running? "test"
</div>
</div>
*'''Returns:''' true/false
*'''Returns:''' true/false
*'''Description:''' Takes a string and returns true/false if the given script is active or not.
*'''Synonyms:''' kill_scripts, stop_script, stop_scripts

*'''Description:''' Simulates the user having entered ;kill test in the game entry box and hitting enter; takes multiple scripts to kill. If the script is not running, returns false; if the script was found to be active and was killed, returns true.
=== send_to_script ===
<div {{log}}>
send_to_script 'scriptname', 'message to send'
</div>
*'''Returns:''' true or false
*'''Description:''' The target script will be sent a string exactly as though it came from the game. Returns true if successful, false if the script wasn't found to be active.

=== send_scripts ===
<div {{log}}>
send_scripts "To the running scripts, this line looks identical to one that came from the game"
</div>
*'''Returns:''' true/false
*'''Description:''' Same as 'send_to_script', but sends a line to all scripts instead of just one.


== start_script ==
=== start_script ===
<div {{log}}>
<div {{log}}>
start_script "test"
start_script "test"
Line 614: Line 803:
*'''Description:''' Simulates the user having entered ;test in the game entry box. Returns 'true' if the script was successfully started, 'false' if for any reason it couldn't be found/started. The optional second argument (which must be an array, as seen in the above example) can be used to simulate arguments to the script (the above example would simulate the user typing: ;heal shaelun adhara).
*'''Description:''' Simulates the user having entered ;test in the game entry box. Returns 'true' if the script was successfully started, 'false' if for any reason it couldn't be found/started. The optional second argument (which must be an array, as seen in the above example) can be used to simulate arguments to the script (the above example would simulate the user typing: ;heal shaelun adhara).


== start_scripts ==
=== start_scripts ===
<div {{log}}>
<div {{log}}>
start_scripts "test"
start_scripts "test"
Line 624: Line 813:
*'''Description:''' Executes a "start_script" command for every argument given. Note that you cannot give a script arguments when using this command.
*'''Description:''' Executes a "start_script" command for every argument given. Note that you cannot give a script arguments when using this command.


== start_wizard_script ==
=== pause_script ===
<div {{log}}>
start_wizard_script "test", [ "command line variable(s)", "etc" ]
</div>
*'''Returns:''' true if successful, false if the script can't be found or run
*'''Description:''' Same as 'start_script', but starts Wizard/SF script files.

== maxhealth/maxstamina/maxmana/maxspirit ==
<div {{log}}>
fput "eat my acantha leaf" while (checkhealth < maxhealth)
</div>
*'''Returns:''' integer
*'''Description:''' Returns your maximum health/spirit/stamina/mana as an integer (class Fixnum). Takes no arguments.

== pause_script ==
<div {{log}}>
<div {{log}}>
pause_script
pause_script
Line 648: Line 823:
*'''Description:''' If given no arguments, pauses the script using the command. If given a string, pauses the script who's name matches that string; if the script is not currently active, returns 'false' ('true' if the script was paused successfully).
*'''Description:''' If given no arguments, pauses the script using the command. If given a string, pauses the script who's name matches that string; if the script is not currently active, returns 'false' ('true' if the script was paused successfully).


== unpause_script ==
=== unpause_script ===
<div {{log}}>
<div {{log}}>
unpause_script "test"
unpause_script "test"
Line 655: Line 830:
*'''Description:''' Unpauses the script you give it. Note that because of the way the 'script is paused' state is handled, it's conceivable for a script that was paused to actually still be executing commands internally for a brief time -- a script isn't actually "stopped dead in its tracks" until it attempts to interact with the game in some way (by fetching game data, sending game data, or by attempting a command that requires the script to be identified). Since most commands identify a script (including this one), this command cannot unpause the script itself: when it attempts to unpause itself, it will be identified as being paused and will be halted where it is until it's unpaused by another script or the user (or killed). When it is, it will be allowed to continue, and will then try to unpause itself (pointlessly, since it was just unpaused...).
*'''Description:''' Unpauses the script you give it. Note that because of the way the 'script is paused' state is handled, it's conceivable for a script that was paused to actually still be executing commands internally for a brief time -- a script isn't actually "stopped dead in its tracks" until it attempts to interact with the game in some way (by fetching game data, sending game data, or by attempting a command that requires the script to be identified). Since most commands identify a script (including this one), this command cannot unpause the script itself: when it attempts to unpause itself, it will be identified as being paused and will be halted where it is until it's unpaused by another script or the user (or killed). When it is, it will be allowed to continue, and will then try to unpause itself (pointlessly, since it was just unpaused...).


=== kill_script ===
== percenthealth/percentmana/percentspirit/percentstamina ==
<div {{log}}>
<div {{log}}>
kill_script "test"
fput "eat my acantha leaf" while (percenthealth < 90)
</div>
</div>
*'''Returns:''' integer
*'''Returns:''' true/false
*'''Synonyms:''' kill_scripts, stop_script, stop_scripts
*'''Description:''' Returns an integer (0-100) representing the percentage of your current health/mana/whatever in relation to your max.
*'''Description:''' Simulates the user having entered ;kill test in the game entry box and hitting enter; takes multiple scripts to kill. If the script is not running, returns false; if the script was found to be active and was killed, returns true.


== Unique ==

See [[Lich_scripting_reference#toggle_unique|toggle_unique]] for more about the 'unique' stack.


== running? ==
=== unique_get ===
<div {{log}}>
<div {{log}}>
unique_get
running? "test"
</div>
</div>
*'''Returns:''' true/false
*'''Returns:''' a string
*'''Description:''' Takes a string and returns true/false if the given script is active or not.
*'''Description:''' Fetches a line from the unique stack, as opposed to the game data stack ().


== variable ==
=== unique_send_to_script ===
<div {{log}}>
<div {{log}}>
unique_send_to_script 'scriptname', 'message to send'
variable[1]
</div>
</div>
*'''Returns:''' an array, possibly empty
*'''Returns:''' true or false
*'''Description:''' Same as 'send_to_script', but the script will receive the string sent in its 'unique' stack instead of its 'game data' stack (see [[Lich_scripting_reference#toggle_unique|toggle_unique]] for more info).
*'''Synonyms:''' script.vars
*'''Description:''' It's an array containing the command line variables the user entered when starting the script (begins at variable[1], unlike standard arrays; as is the behavior of Wizard, variable[0] is the entire line the user entered).


== checkspell ==
=== unique_waitfor ===
<div {{log}}>
<div {{log}}>
unique_waitfor "continue"
checkspell "elemental defense i"
</div>
</div>
*'''Returns:''' true/false
*'''Returns:''' a string
*'''Description:''' Same as 'waitfor' but acts on the 'unique' queue.
*'''Synonyms:''' active?

*'''Description:''' Returns true if the spell you give it is active, false if it isn't (only available if you use the infomon script, since that's what keeps track of this).

== Exit handling ==

=== exit ===
<div {{log}}>
exit
</div>
*'''Returns:''' does not return
*'''Description:''' Ends the script.


== die_with_me ==
=== die_with_me ===
<div {{log}}>
<div {{log}}>
die_with_me "test", "calcredux", "etc"
die_with_me "test", "calcredux", "etc"
</div>
</div>
*'''Returns:''' true
*'''Returns:''' true
*'''Description:''' If the given scripts are active at the time the script using this command ends (exits itself, finishes, gets killed by the user, or dies in error) they'll all be killed automatically (produces no notification to avoid clutter, but the scripts are indeed stopped). The given scripts need not be running (or technically even exist) at the time this command is used -- it only updates the setting, and that setting isn't actually acted upon until the script is killed.
*'''Description:''' If the given scripts are active at the time the script using this command ends ("exit", finishes, gets killed by the user, or dies in error) they'll all be killed automatically (produces no notification to avoid clutter, but the scripts are indeed stopped). The given scripts need not be running (or technically even exist) at the time this command is used -- it only updates the setting, and that setting isn't actually acted upon until the script is killed.


== before_dying ==
=== before_dying ===
<div {{log}}>
<div {{log}}>
before_dying { echo "Oh God, why have you killed me dear user...?!" }
before_dying { echo "Oh God, why have you killed me dear user...?!" }
Line 702: Line 891:
*'''Description:''' Performs the given actions right before the script exits. Note nothing is done at the time this command is used (it simply sets what should be done just before the script is killed). The block given to this command is actually wrapped up into a proc object (an object of the 'Procedure' class), and scheduled to be run when the script is killed/exits (if multiple procs exist, they are executed sequentially in the order they were declared). Because of this, the same 'binding' principles that apply to other proc objects apply here (in a nutshell, if a variable didn't exist when you declared the 'before_dying' stuff, then you can't use it in the 'before_dying' code; if it did exist at the time though, you *can* use it, even if it doesn't really exist in the script when it dies). Also note that if the command(s) take more than 0.5 seconds to complete, they're forcibly aborted and the script is killed regardless (this is to prevent a possibly bad situation where a script makes a mistake in the 'before_dying' command and is refusing to stop executing due to errors). Note that if a script is set as executing in SAFE mode, all the restrictions that normally apply will also apply in the 'before_dying' code block (this cannot circumvent that, nor can anything else for that matter).
*'''Description:''' Performs the given actions right before the script exits. Note nothing is done at the time this command is used (it simply sets what should be done just before the script is killed). The block given to this command is actually wrapped up into a proc object (an object of the 'Procedure' class), and scheduled to be run when the script is killed/exits (if multiple procs exist, they are executed sequentially in the order they were declared). Because of this, the same 'binding' principles that apply to other proc objects apply here (in a nutshell, if a variable didn't exist when you declared the 'before_dying' stuff, then you can't use it in the 'before_dying' code; if it did exist at the time though, you *can* use it, even if it doesn't really exist in the script when it dies). Also note that if the command(s) take more than 0.5 seconds to complete, they're forcibly aborted and the script is killed regardless (this is to prevent a possibly bad situation where a script makes a mistake in the 'before_dying' command and is refusing to stop executing due to errors). Note that if a script is set as executing in SAFE mode, all the restrictions that normally apply will also apply in the 'before_dying' code block (this cannot circumvent that, nor can anything else for that matter).


== undo_before_dying ==
=== undo_before_dying ===
<div {{log}}>
<div {{log}}>
undo_before_dying
undo_before_dying
Line 709: Line 898:
*'''Description:''' Clears any 'before_dying' commands that have been used for the script.
*'''Description:''' Clears any 'before_dying' commands that have been used for the script.


== Wounds.torso ==
=== abort! ===
<div {{log}}>
<div {{log}}>
abort!
Wounds.torso
</div>
</div>
*'''Returns:''' does not return
*'''Description:''' Immediately kills the script, bypassing any 'before_dying' blocks that have been registered. Probably won't ever be of use, but it's a way to make the calling script go away as fast as possible (note that it isn't any faster than the 'exit' command is, it just makes sure that nothing except stopping the script happens).


== Spell ==

The Spell class combines spell information from spell-list.xml and character information from infomon to greatly simplify basic spell handling.

=== Spell[number].cast() ===
<div {{log}}>
<div {{log}}>
Spell[503].cast
Wounds.neck
Spell[503].cast('Tilmen')
</div>
</div>
*'''Returns:''' returns result as string ( ie cast roundtime, hinderance, etc. )
*'''Description:''' Attempt to cast spell given using info from spell-list.xml

=== Spell[number].affordable? ===
<div {{log}}>
<div {{log}}>
Spell[503].affordable?
Wounds.lhand
</div>
</div>
*'''Returns:''' returns true or false
*'''Description:''' Useful for knowing if you have enough mana for spell

=== Spell[number].active? ===
<div {{log}}>
<div {{log}}>
Spell[503].active?
(etc)
</div>
</div>
*'''Returns:''' an integer
*'''Returns:''' returns true or false if spell is active
*'''Description:''' Will return true if the spell is currently active on yourself, false if it is not.
*'''Synonyms:''' Wounds.head; Wounds.neck; Wounds.abs; Wounds.lhand; Wounds.rhand; Wounds.larm; Wounds.rarm; Wounds.chest; Wounds.back; Wounds.rleg; Wounds.lleg; Wounds.nerves
*'''Description:''' Returns the current wound rank (numerically). If I had 'deep gashes and serious bleeding' on my chest, Wounds.chest would return the integer 3. If I had no wound there, it would return 0.


== Scars.torso ==
=== Spell[number].timeleft ===
<div {{log}}>
<div {{log}}>
Spell[503].timeleft
Scars.nerves
</div>
</div>
*'''Returns:''' returns number
*'''Description:''' Returns amount of time left as value

=== Spell[number].force_cast() ===
<div {{log}}>
<div {{log}}>
Spell[503].force_cast
Scars.lleg
Spell[503].force_cast('Tilmen')
</div>
</div>
*'''Returns:''' returns result as string ( ie cast roundtime, hinderance, etc. )
*'''Description:''' Attempt to force cast spell

=== Spell[number].force_channel() ===
<div {{log}}>
<div {{log}}>
Spell[503].force_channel
(etc)
Spell[503].force_channel('Tilmen')
</div>
</div>
*'''Returns:''' an integer
*'''Returns:''' returns result as string ( ie cast roundtime, hinderance, etc. )
*'''Description:''' Identical to the Wounds.(bodypart) commands seen above, but for scars instead of wounds.
*'''Description:''' Attempt to force channel spell


=== Spell[number].force_evoke() ===
== GameObj ==
*'''Description:''' The GameObj class tracks various objects in the same room as you, and makes their game id, name, noun, status, and contents available to you.
<div {{log}}>
<div {{log}}>
Spell[503].force_evoke
GameObj.inv
Spell[503].force_evoke('Tilmen')
</div>
</div>
*'''Returns:''' an array of objects of the GameObj class representing the things you are wearing.
*'''Returns:''' returns result as string ( ie cast roundtime, hinderance, etc. )
*'''Description:''' Attempt to force evoke spell

=== Spell[number].force_incant() ===
<div {{log}}>
<div {{log}}>
Spell[503].force_incant
GameObj.pcs
</div>
</div>
*'''Returns:''' returns result as string ( ie cast roundtime, hinderance, etc. )
*'''Returns:''' an array of objects of the GameObj class representing the other players in the room, or nil if there are none.
*'''Description:''' Attempt to force incant spell

== Effect ==

=== active? ===
<div {{log}}>
<div {{log}}>
Effects::Spells.active?("Call Familiar")
GameObj.npcs

Effects::Spells.active?(920)

Effects::Cooldowns.active?("Mana Leech")

Effects::Buffs.active?("Rapid Fire")

Effects::Debuffs.active?("Silenced")
</div>
</div>
*'''Returns:''' true or false
*'''Returns:''' an array of objects of the GameObj class representing the npcs in the room, or nil if there are none.
*'''Description:''' Used to detect whether the given effect is currently active. Spells can be referenced by number or name, unless the spell does not have a number, then must be referenced by name. Name can only be used when FLAG ShowSpellName is set to ON.

=== time_left ===
<div {{log}}>
<div {{log}}>
Effects::Spells.time_left("Call Familiar")
GameObj.loot

Effects::Spells.time_left(920)

Effects::Cooldowns.time_left("Mana Leech")

Effects::Buffs.time_left("Rapid Fire")

Effects::Debuffs.time_left("Silenced")
</div>
</div>
*'''Returns:''' time left in minutes as a floating number
*'''Returns:''' an array of objects of the GameObj class representing the loot in the room, or nil if there is none. For the purposes of this function, loot is anything that Simu hasn't tagged with monster bold. Any exits or anything that shows up in the "You also see" line will be included.
*'''Description:''' Used to determine how much time is left on a given effect.

== Weapon ==
=== known? ===
<div {{log}}>
<div {{log}}>
Weapon.known?(name)
GameObj.room_desc

Weapon.known?("Charge")
</div>
</div>
*'''Returns:''' true or false
*'''Returns:''' an array of objects of the GameObj class representing any links found in the room description, or nil if there are none.
*'''Description:''' Used to detect whether the weapon skill given is known to the character.

=== affordable? ===
<div {{log}}>
<div {{log}}>
Weapon.affordable?(name)
GameObj.right_hand<br>

GameObj.left_hand<br>
Weapon.affordable?("Charge")
</div>
</div>
*'''Returns:''' true or false
*'''Returns:''' an object of the GameObj class representing whatever is in your hand. Currently, if there is nothing in your hand, it still returns a GameObj where the name is "Empty".
*'''Description:''' Used to detect whether the weapon skill given is affordable for the character.

=== available? ===
<div {{log}}>
<div {{log}}>
Weapon.available?(name)
GameObj.fam_pcs<br>

GameObj.fam_npcs<br>
Weapon.available?("Charge")
GameObj.fam_loot<br>
GameObj.fam_room_desc
</div>
</div>
*'''Returns:''' true or false
*'''Description:''' Checks whether the weapon skill is known, currently affordable, and that no known current cooldown or Overexerted debuff would block it's use.

== CMan ==
=== known? ===
<div {{log}}>
CMan.known?(name)

CMan.known?("Garrote")
</div>
*'''Returns:''' true or false
*'''Description:''' Used to detect whether the cman skill given is known to the character.

=== affordable? ===
<div {{log}}>
CMan.affordable?(name)

CMan.affordable?("Garrote")
</div>
*'''Returns:''' true or false
*'''Description:''' Used to detect whether the cman skill given is affordable for the character.

=== available? ===
<div {{log}}>
CMan.available?(name)

CMan.available?("Garrote")
</div>
*'''Returns:''' true or false
*'''Description:''' Checks whether the cman skill is known, currently affordable, and that no known current cooldown or Overexerted debuff would block it's use.

== Shield ==

=== known? ===
<div {{log}}>
Shield.known?(name)

Shield.known?("Shield Charge")
</div>
*'''Returns:''' true or false
*'''Description:''' Used to detect whether the shield skill given is known to the character.

=== affordable? ===
<div {{log}}>
Shield.affordable?(name)

Shield.affordable?("Shield Charge")
</div>
*'''Returns:''' true or false
*'''Description:''' Used to detect whether the shield skill given is affordable for the character.

=== available? ===
<div {{log}}>
Shield.available?(name)

Shield.available?("Shield Charge")
</div>
*'''Returns:''' true or false
*'''Description:''' Checks whether the shield skill is known, currently affordable, and that no known current cooldown or Overexerted debuff would block it's use.

=== use ===
<div {{log}}>
Shield.use(name, target = "")

Shield.use("Shield Charge", "Wyrom")
Shield.use("Shield Charge", 9000)
</div>
*'''Description:''' Attempts to use the shield skill given on target specified. Target can be a GameObj, integer, or string. If no target given, will issue command with no target, relying on game-engine targeting.

== Armor ==
=== known? ===
<div {{log}}>
Armor.known?(name)

Armor.known?("Armor Blessing")
</div>
*'''Returns:''' true or false
*'''Description:''' Used to detect whether the armor skill given is known to the character.

== Feat ==
=== known? ===
<div {{log}}>
Feat.known?(name)

Feat.known?("Absorb Magic")
</div>
*'''Returns:''' true or false
*'''Description:''' Used to detect whether the feat skill given is known to the character.

=== affordable? ===
<div {{log}}>
Feat.affordable?(name)

Feat.affordable?("Absorb Magic")
</div>
*'''Returns:''' true or false
*'''Description:''' Used to detect whether the feat skill given is affordable for the character.

=== available? ===
<div {{log}}>
Feat.available?(name)

Feat.available?("Absorb Magic")
</div>
*'''Returns:''' true or false
*'''Description:''' Checks whether the feat skill is known, currently affordable, and that no known current cooldown or Overexerted debuff would block it's use.

== GameObj ==

The GameObj class tracks various objects in the same room as you, and makes their game id, name, noun, status, and contents available to you.

=== GameObj arrays ===

Several arrays are exposed by GameObj. They include:

==== GameObj.inv ====

*'''Returns:''' an array of objects of the GameObj class representing the things you are wearing.

==== GameObj.pcs ====

*'''Returns:''' an array of objects of the GameObj class representing the other players in the room, or nil if there are none.

==== GameObj.npcs ====

*'''Returns:''' an array of objects of the GameObj class representing the npcs in the room, or nil if there are none.

==== GameObj.loot ====

*'''Returns:''' an array of objects of the GameObj class representing the loot in the room, or nil if there is none. For the purposes of this function, loot is anything that Simu hasn't tagged with monster bold. Any exits or anything that shows up in the "You also see" line will be included.

==== GameObj.room_desc ====

*'''Returns:''' an array of objects of the GameObj class representing any links found in the room description, or nil if there are none.

==== GameObj.dead ====

*'''Returns:''' an array of objects of the GameObj class representing the dead '''npcs''' in the room, or nil if there are none.

==== GameObj.fam_pcs, GameObj.fam_npcs, GameObj.fam_loot, GameObj.fam_room_desc ====

*'''Returns:''' an array of objects of the GameObj class. Similar to the ones above, except for your familiar's room, and these don't stay up-to-date without having your familiar look at the room.
*'''Returns:''' an array of objects of the GameObj class. Similar to the ones above, except for your familiar's room, and these don't stay up-to-date without having your familiar look at the room.

==== GameObj.targets ====

*'''Returns:''' an array of objects of the GameObj class representing the hostile npcs in the room, the mobs, the monsters, whatever you want to call them.

==== GameObj.target ====

*'''Returns:''' an object of the GameObj class representing the current target you have selected, if any.

=== Finding game objects with GameObj ===

Now that you've got an object or array of objects, here's what to do with them:
Now that you've got an object or array of objects, here's what to do with them:

<div {{log}}>
<div {{log}}>
target = GameObj.npcs.find { |npc| npc.status.nil? }<br>
target = GameObj.npcs.find { |npc| npc.status.nil? }<br>
Line 780: Line 1,188:
end
end
</div>
</div>

*'''Description:''' This example shows (in an over-simplified way) the most common use of the GameObj class. First, "GameObj.npcs" gives an array of all the npcs in the room. Then, ".find" searches each item in that array. For each item in the array, the code inside the brackets following "GameObj.npcs.find" is run, and "npc" represents the item it's currently looking at. The code inside the brackets acts like an if statement, and as soon as it is true, "target" is assigned the npc object.<br>
*'''Description:''' This example shows (in an over-simplified way) the most common use of the GameObj class. First, "GameObj.npcs" gives an array of all the npcs in the room. Then, ".find" searches each item in that array. For each item in the array, the code inside the brackets following "GameObj.npcs.find" is run, and "npc" represents the item it's currently looking at. The code inside the brackets acts like an if statement, and as soon as it is true, "target" is assigned the npc object.
The "status" method applies to npcs and pcs (using it on others won't give an error, but it will always return nil). The status is basically whatever shows up after "that appears", "that is", or "who is". So, if you also see a kobold that appears stunned, its status will be "stunned". In the example, we're looking for an npc with a nil status, because that represents an npc that's standing and not stunned, dead, prone, etc. The game never shows "You also see a kobold that is standing."<br>

The "status" method applies to npcs and pcs (using it on others won't give an error, but it will always return nil). The status is basically whatever shows up after "that appears", "that is", or "who is". So, if you also see a kobold that appears stunned, its status will be "stunned". In the example, we're looking for an npc with a nil status, because that represents an npc that's standing and not stunned, dead, prone, etc. The game never shows "You also see a kobold that is standing."

Now suppose there's twenty kobolds in the room, and only the fifteenth one is standing. How can you be sure you attack the standing one? This is where the kobold's id comes in handy. Simu assigns an id to almost everything in the game. Stormfront uses these ids when you click on links. For the most part, these ids can be used just like nouns. "attack ##{target.id}" will attack the npc you found earlier, even if other npcs are walking in and out of the room. The double pound sign is not a typo.
Now suppose there's twenty kobolds in the room, and only the fifteenth one is standing. How can you be sure you attack the standing one? This is where the kobold's id comes in handy. Simu assigns an id to almost everything in the game. Stormfront uses these ids when you click on links. For the most part, these ids can be used just like nouns. "attack ##{target.id}" will attack the npc you found earlier, even if other npcs are walking in and out of the room. The double pound sign is not a typo.

=== Other GameObj methods ===

==== GameObj.containers ====

*'''Returns:''' a Hash of ids (as Strings) mapping to arrays of objects of the GameObj class. Each id represents an accessible container '''that GameObj is aware of''' with the given id. The id maps to an array of objects of the GameObj class representing that container's contents.

For a container to be added to the Hash, GameObj must first be made aware of its contents by some sort of interaction with the container, looking in it, opening it, and more. (Someone who knows the specific cases, please add detail!)

==== GameObj.right_hand, GameObj.left_hand ====

*'''Returns:''' an object of the GameObj class representing whatever is in your hand. Currently, if there is nothing in your hand, it still returns a GameObj where the name is "Empty".

==== Useful and hopefully self-explanatory methods to use once you have the right GameObj object====

<div {{log}}>
<div {{log}}>
.id<br>
.id<br>
Line 791: Line 1,217:
</div>
</div>



==status_tags==
== Script ==

The Script class deals with and runs scripts.

=== Script.start ===
*'''Description:''' Starts the specified script. Arguments for that script should be passed as a single string. A hash can also be passed with other script options (:quiet, :force, and you can also use :name and :args instead of passing one/two strings).

=== Script.run ===
*'''Description:''' Starts the specified script and waits while it runs. Arguments for that script should be passed as a single string. A hash can also be passed with other script options (:quiet, :force, and you can also use :name and :args instead of passing one/two strings).

=== Script.list, Script.running, Script.hidden ===
*'''Returns:''' An array of Script objects for every running/visible/invisible script.
*'''Note:''' This is not the same as ;list. The Script class does not have a defined to_s method.

=== Script.running? ===
*'''Description:''' Checks whether a script is running (paused or not)
*'''Returns:''' true or false

=== Script.pause ===
*'''Description:''' Pauses a script
*'''Returns:''' true if the script was paused successfully, false otherwise (script not running or already paused)

=== Script.unpause ===
*'''Description:''' Unpauses a script
*'''Returns:''' true if the script was unpaused successfully, false otherwise (script not running or was not paused)

=== Script.paused? ===
*'''Returns:''' true if a script is running and paused, false otherwise

=== Script.exists? ===
*'''Returns:''' true if a script with the given name is in the user's script directory, false otherwise. extension is optional.

=== Script.log ===
Appends to the script's .log file in the lich/log directory.

=== Script.db ===
Gets you a sqlite3 database for your script, of type SQLite3::Database (http://www.rubydoc.info/github/luislavena/sqlite3-ruby/SQLite3/Database)

=== Script.version ===
<div {{log}}>
<div {{log}}>
Script.version("infomon")
status_tags
</div>
</div>
*'''Returns:''' Ruby Gem version
*'''Description:''' Takes a string(script) and returns the current version in header of script as a Ruby Gem version


<div {{log}}>
*'''Returns:''' ?
Script.version("infomon", "1.18.0")
*'''Description:'''Tells Lich to send this script XML tags rather than stripping them, or, if already doing so, tells Lich to go back to stripping the XML. If called with the argument "on" or "off", switches to that setting and echoes that it has done so.
</div>
*'''Returns:''' true/false
*'''Description:''' Takes a string(script) and minimum required version


== Global variables ==
==See Also==

=== $PROGRAM_NAME ===
Ruby's global variable capturing current script -- in this case, the path to Lich.

=== $frontend ===
Frontend detected by Lich.

=== $login_time ===
Local time the current Lich session started.

== Lich Constants ==

=== LICH_DIR ===
Path of the current Lich directory.

=== SCRIPT_DIR ===
Path to directory Lich is using to for scripts.

=== DATA_DIR ===
Path to the directory Lich is using for data.

=== LOG_DIR ===
Path to the directory Lich is using for logs.

=== LICH_VERSION ===
Lich version.

== Builtin Lich shortcuts ==

These automatically perform multiple checks or commands.

=== take ===
<div {{log}}>
take "box", "coffer", "ruby", "etc"
</div>
*'''Returns:''' a string (the last line the 'fput' command saw)
*'''Description:''' Picks up every item listed and puts each one in turn into your 'lootsack:' setting by issuing the commands with fput.

=== fetchloot ===
<div {{log}}>
fetchloot
</div>
*'''Returns:''' a string
*'''Description:''' Performs a 'look' and takes/puts away all items on the ground that aren't listed in your 'excludeloot:' setting. Return value is the last line from the game.
*'''See also:''' GS now natively includes the command LOOT ROOM with a similar effect.

=== Lich.fetchloot ===
<div {{log}}>
Lich.fetchloot
</div>
*'''Returns:''' a string
*'''Description:''' Identical to 'fetchloot' in all ways except only the items listed in your 'treasure:' setting are fetched.

=== walk ===
<div {{log}}>
walk
</div>
*'''Returns:''' true or false
*'''Description:''' Moves in a random cardinal direction (what's seen in the 'Obvious exits:' line), storing the direction moved, and returning 'true' if there is a critter in the room or 'false' if there aren't any NPCs in the room. The stored direction will not be among the random directions chosen the next time the 'walk' command is used (unless it hits a dead-end, then it will backtrack the way it came).

=== run ===
<div {{log}}>
run if not health(50)
</div>
*'''Returns:''' true or false
*'''Description:''' Will execute a 'walk' command repeatedly until it enters a room with no critters, at which point it returns and the script will pick up execution on the next line (does not continue to run away).
*'''See also:''' wander.lic is a popular and sophisticated auto-moving creature-finding script.

=== watchhealth ===
<div {{log}}>
watchhealth(50) { echo "Uh, your health is below 50..." }
</div>
<div {{log}}>
watchhealth(50, proc_object)
</div>
*'''Returns:''' nothing useful
*'''Description:''' Returns immediately so that the calling script continues to run as normal, and while it does, monitors your health. If it falls below the number you give it, executes the block you passed to it. Only does this once -- if you want it to repeat as the script executes (be careful, chances are your health will still be below 50 after the block executes once) then pass watchhealth a proc object that includes a line registering itself over again (as in, a proc that includes a 'watchhealth(#, self)' thingie). If your health never falls below the number you give it, then nothing happens; once the script ends, it stops watching.

== goto ==
<div {{log}}>
goto "MainLabel"
</div>
*'''Returns:''' (has no return value, the current execution stack is discarded and the jump never returns)
*'''Description:''' Identical to standard Wizard/SF scripts; the label to jump to has to be in quotes, and it is (kinda sorta) case insensitive. The label declaration itself (the LABEL: line) MUST NOT be in quotes: only the name of the label when you use the goto command. If there are two labels with the same name but different capitalizations, the goto command will attempt to be case sensitive.


== See also ==
*[[The Lich]]
*[[The Lich]]



==References==
== References ==
*The initial content of this article was copied from the scripting documentation posted by Tillmen which formerly resided at http://lichproject.com/
*The initial content of this article was copied from the scripting documentation posted by Tillmen which formerly resided at http://lichproject.com/


Latest revision as of 07:58, 27 September 2024

Lich:Software/Scripting reference is a third party script and is not maintained by Simutronics. Simutronics is not responsible for the accuracy of the information presented on this page, nor is it liable for issues stemming from the use of the application on players' personal devices.

variable

variable[1]

Script.current.vars[0]

Script.current.vars[1]

  • Returns: an array, possibly empty
  • Synonyms: Script.current.vars, script.vars
  • Description: An array containing the command line variables the user entered when starting the script. Index position 0 contains all the variables passed to it in a single string. Index positions 1 thru n correlate to space separated list of the values passed to the script. The third example above showing proper syntax for recalling the first variable passed to the script. While variable and script.vars still work, the current best practice is to use Script.current.vars to match appropriate Lich API usage.

echo

echo

echo "Hi there!"

echo "Line one", "Line two", "endlessly"

  • Returns: a string
  • Description: Displays '[script_name: the string it was given]' in the game window; if given multiple strings it echoes each string on its own line. If it's given no arguments, it simply prints a blank line without the '[script_name: ]' business.

respond

respond

respond "I'm a string to display"

respond "Line one", "Line two", "so on and so on"

  • Returns: integer
  • Description: Just like the 'echo' command, but does not display the script name. Since it's possible for Lich to be running two dozen scripts at the same time, it can get a little hard to know which script is saying what unless they use the 'echo' command and not the 'respond' command. Still, 'echo' can be a bit ugly for printing tables and whatnot, so use this instead if desired. The return value is how many characters the last string displayed contained.

pause

pause

pause 3

pause '2s'

pause '3m'

pause '1d'

  • Returns: an integer
  • Description: If given no arguments, pauses for one second. If given an integer, pauses for that many seconds. If given a string (as in the examples above), extracts the number to pause for from the string and pauses for that many seconds/hours/days (yeah, well, I was bored, so why not make it do days too). Return value is the number of seconds it paused for.


Output

Sending output to the game as though typed by the player.

put

put "look"

  • Returns: the string that was sent
  • Description: Identical to Wizard.

fput

fput "stance defensive"

fput "stance defensive", "are now in a defensive stance", "can't do that while dead", "etc"

  • Returns: the string that was accepted as meaning the action succeeded (see below)
  • Synonyms: forceput
  • Description: It's named 'forceput' because originally it was intended to be used only infrequently, but as it's turned out there are very few times when 'put' is preferable. This command will continue to 'put' whatever string you give it, until it receives a line from the game that it doesn't recognize as one of the common "command rejected" responses (for example, "You can't do that while entangled in a web", "...wait x seconds" (RT), "Wait x seconds." (cast RT), "Sorry, you may only type ahead x lines", "You'll have to stand up first" (stands and reattempts), etc). If stunned, it will wait until you're no longer stunned to reattempt; if in RT (hard or soft), will wait 'x' seconds before reattempting. If you need to stand, it will do so and retry immediately. If it causes a type ahead error, it will pause for 1 second and then reattempt. This has a very high rate of success, but it is definitely not infallible -- it only checks the next line received from the game, and there's no guarantee the next line from the game has anything at all to do with what the 'fput' command just sent. Because of this it can often fail to realize the command wasn't really successful, particularly if the user is doing a lot of things at once. If given more than one string, the first string is taken as the command to send to the game, and all other strings are used as what to accept as meaning the action succeeded. BE CAREFUL with this behavior! It can very infrequently be extremely useful, but if not used cautiously, it can easily cause a script to mistakenly repeat an action many times in *very* rapid succession (which with CoL signs for instance can very easily kill you in less than a second flat).

multifput

multifput "stance offensive", "incant 910", "stance defensive"

  • Returns: a string (return value of the last 'fput' executed)
  • Description: Takes multiple strings and executes an 'fput' command for every one sequentially.

dothis

dothis "action here", /regex to match for success/

  • Returns: a success string, or false
  • Description: Similar to fput, but will continue to try the action until a success string is matched

dothistimeout

dothistimeout "action here", time, /regex to match for success/

  • Returns: a success string, or nil
  • Description: Same as 'dothis', but if a success isn't seen in the given amount of time, returns a value of 'nil' and the script will move on.

move

move 'northwest'

  • Returns: true or false
  • Description: Same as the Wizard 'move' command, but it will usually compensate for things like type ahead errors, RT, currently stunned, etc.; will also stand and re-attempt the movement if it's detected to be necessary. Returns 'true' if the move was executed properly, 'false' if it wasn't able to be performed (which is very rare due to the move command's error compensation measures).

multimove

multimove 'nw', 'ne', 'go hole', 'climb stairs'

  • Returns: true or false
  • Description: Takes multiple directions to move in and executes the 'move' command for each one. Returns the value of the last 'move' command executed (true or false).


Input

This is core line-by-line handling of full lines of input sent by the game to the player. For more complex filtering and handling, see "match" and "wait" sections.

get

get

  • Returns: a string
  • Description: Fetches the next un-checked line of game data (while a script is running, it is given every game line, and these lines are available for a script to check/use at its leisure).

regetall

regetall "Shaelun"

  • Returns: an array of strings, or nil
  • Description: Takes a string and returns an array of all game lines (since login) that match as having contained the given string (absolutely every single line since you logged in, Lich remembers them all). If a script is set as receiving the status data that doesn't show in the game window, those lines are also matched for; if the script is only being fed normal game data, that's the only history this command checks. If no matching lines were found, returns 'nil' (which is false in a logical comparison). As well as returning the matches, it also adds them to the script's game data stack so that subsequent 'get' commands will fetch them in order. The string to match for is actually optional, and if omitted, all lines are considered 'matching'.

reget

reget 3

reget 5, "Shaelun"

  • Returns: an array of strings, or nil
  • Description: Similar to 'regetall' in behavior, but it only checks the current RAM cache (every 2 minutes, Lich's 'memory' of game data is emptied out of RAM and stored in a temporary file on the hard disk so that the program doesn't take up more resources than is necessary -- these files are deleted when the program closes); it also takes an optional integer, which represents how many game lines back to check ('reget 5' would scan the last 5 lines from the game that are still in RAM). If the integer is omitted, will scan the entire existing RAM buffer (again, cleared every 2 minutes).

clear

clear

  • Returns: an array of strings (possible for the return array to be empty, but unlikely)
  • Description: Empties ALL unchecked input to the script from ALL queues (normal game stack, unique script stack and upstream stack); the return value is whatever was in the game data stack before it was cleared (which could be nothing, in which case the return is an empty array).


Wait

wait

wait

  • Returns: a string
  • Description: Identical to Wizard; waits until a line from the game is seen. Returns the line (in actuality this command simply clears the game stack and executes a 'get').

waitrt

waitrt

  • Returns: an integer (Fixnum class)
  • Description: Pauses for however many seconds you're currently in roundtime for. Return value is how many seconds paused. Waits until you're in roundtime if you aren't at the time this command is used, and therefore can hang endlessly.

waitrt?

waitrt?

  • Returns: an integer (Fixnum class)
  • Description: Identical to 'waitrt', but does not wait until you're in roundtime and as such will not hang (but will not wait for any roundtime if the game hasn't sent that you're in roundtime yet).
  • Note: Zero is a value, and ALL values in Ruby are evaluated to true, EXCEPT for FALSE and NIL. This means that !waitrt? will not do do a proper true/false check like it might in other languages.

waitcastrt

waitcastrt

  • Returns: an integer (Fixnum class)
  • Description: Pauses for however many seconds you're currently in RT for. Return value is how many seconds paused. Waits until you're in RT if you aren't at the time this command is used, and therefore can hang endlessly.

waitcastrt?

waitcastrt?

  • Returns: an integer (Fixnum class)
  • Description: Identical to 'waitcastrt', but does not wait until you're in cast roundtime and as such will not hang (but will not wait for any cast roundtime if the game hasn't sent that you're in cast roundtime yet).
  • Note: Zero is a value, and ALL values in Ruby are evaluated to true, EXCEPT for FALSE and NIL. This means that !waitcastrt? will not do do a proper true/false check like it might in other languages.

waitfor

waitfor " just arrived.", "More lines to waitfor if you desire", "endlessly"

  • Returns: a string
  • Description: Waits until a line from the game includes the string you gave it as an argument. The return value is the complete string from the game (in the example used here, if Shaelun entered the room, the command would return "Shaelun just arrived."). 'waitfor' is case insensitive (capital letters are considered matches even if the string it was given didn't have a capital letter there).

wait_while

wait_while { percenthealth != 100 }

wait_while("You do not have full health: waiting until you do.") { percenthealth != 100 }

  • Returns: true/false
  • Description: The script will wait while the given code block has a logical value of 'true', and will only continue on to the next line when/if the code block has a value of 'false'. If given the optional string to announce to the user, it will only display that string if it's going to be sitting there waiting for something -- if the command will not be waiting at all, it doesn't display the string to the user. Note that there's no limit to how long/complicated the code block can be; it was designed for very short logical comparisons like the example above, but need not be used that way.

wait_until

wait_until("Waiting until 50 mana or more!") { checkmana(50) }

  • Returns: true/false
  • Description: Identical in all ways to 'wait_while', but does the opposite (waits UNTIL the given code block is true, not WHILE it's true). Also takes the optional string if desired.

Match

Wizard-style "match" commands

matchtimeout

matchtimeout 5, "string to watch for", "another", "endlessly"

  • Returns: a string, or false
  • Description: Same as 'waitfor', but if a match isn't seen in the given amount of time, returns a value of 'false' and the script will move on.

matchwait

  • Returns: a string
  • Description: If used without any arguments, 100% identical to Wizard 'matchwait' commands. You can optionally give it arguments, in which case it acts identically to 'waitfor' in all ways except one: matches are case sensitive (for instance, matchwait "shaelun" will not match if the word "Shaelun" is seen from the game).

match

match 'label', 'line to watch for'

match "gameline", "gameline", "some other gameline", "so on and so forth"

  • Returns: a string
  • Description: If given exactly two arguments, identical to the Wizard 'match' command. If given *any* other number of arguments, it's a case sensitive version of 'waitfor' but instead of returning the entire matching game line, it returns only the portion of the string you asked it to watch for.

matchfind

matchfind "A ? attacks you!", "A ? swings a ? at you!"

person, weapon = matchfind "? swings a ? at you!"

  • Returns: a string or an array
  • Description: Same as 'waitfor', but returns only the portion of the line where the question mark(s) are. If given multiple question marks, returns an array containing the portions of the string (in order). Note that if you assign multiple variables to equal a single array, the array's elements are used in order and assigned to each variable (if there are fewer elements in the array than there are variables being assigned, variables receive a value of 'nil', and if there are more elements in the array than there are variables being assigned, the last variable is assigned an array with the remaining values). This is why the above usage example works (person, weapon =).

matchfindword

weapon = matchfindword "Shaelun swings a ? at you!"

  • Returns: a string (single word)
  • Description: Identical to 'matchfind', but only looks for a single word where the question marks are. Note that a line won't match if more than one word is where the question mark is (in the above example, if the weapon were a "broadsword" it would match, but if it were a "sonic hammer of kai" there would be no match).

matchfindexact

matchfindexact "? just arrived."

  • Returns: a string
  • Description: Version of matchfind meant for use in special cases; matchfind is very forgiving and will return and match anything (case insensitively) -- matchfindexact is very strict. It is case sensitive and cares about things like spaces, word boundaries (partial pieces of a word will not match, only whole words), the case of the string it's looking for, etc.. Use it if you need to use matchfind and want to make sure only a very specific line matches.


Room

checkarea

checkarea

checkarea "illistim"

  • Returns: a string, or true or false
  • Description: By itself returns the geographical area of your current room, or if given a string to check for, returns true or false based on whether your current area matches the string or not.

checkroom

checkroom

checkroom "table"

  • Returns: true or false, or a string
  • Description: Identical to checkarea, but uses the room title instead of the geographical area.

checkpaths

checkpaths

checkpaths 'nw'

  • Returns: an array of strings, or true/false
  • Description: Returns an array consisting of the current 'Obvious exits:' directions if given no argument, or true/false based on whether all arguments given are currently available as exits or not.

checkoutside

checkoutside

outside?

  • Returns: true/false
  • Synonyms: outside?
  • Description: Really simple, just returns true if you're outside, false if you aren't. Probably only of use to rangers writing their own spellup scripts or something, but either way: it's available if you have a use for it.

checknpcs

if checknpcs fput "attack" end

if checknpcs "big monster of doom", "small monster of doom" put "Oh noes!" end

for npc in checknpcs put "greet #{npc}" end

  • Returns: an array of strings, a string, or nil
  • Description: If checknpcs is used without giving it npcs to check for, it returns an array of strings coresponding to the noun of each npc in the room, or nil if there are no npcs (does not return an empty array, so you can use "if checknpcs"). If chekcnpcs is given npcs to look for, it returns a string of the first matching npc it finds, or nil if none matched (any string evaluates to true, only nil and false evaluate to false in an if statement).

checkpcs

checkpcs

checkpcs "shaelun"

  • Returns: array of strings, or true/false
  • Description: Identical to 'checknpcs', but with the players currently present.

checkloot

checkloot

  • Returns: an array of strings (or an empty array if no items)
  • Description: Returns an array consisting of the items currently in the room.


Familiars

checkfamarea/checkfamroom

checkfamarea

checkfamarea "illistim"

  • Returns: a string, or true/false
  • Description: Identical to checkarea/checkroom, but check your familiar's current location instead of yours (only in Wizard and only if you have a familiar).

checkfampcs

checkfampcs "shaelun"

checkfampcs

  • Returns: array of strings, or true/false
  • Synonyms: checkfamnpcs
  • Description: Identical to the above two, but tracks for your familiar's room instead. Not available in SF as of v3.06.


Character

checkpoison

checkpoison

  • Returns: true/false
  • Description: See checkdisease.

checkdisease

checkdisease

  • Returns: true/false
  • Description: See checkpoison.

checkfried

checkfried

  • Returns: true or false
  • Description: Returns true if you're fried, false if not.

checkmind

checkmind

checkmind(2)

  • Returns: true or false, or a string
  • Description: By itself returns a string representing the level of exp in your head ('clear as a bell', 'fried', 'muddled', etc). If given an integer, returns true or false if you have the corresponding level of exp in your head, with 0 being 'clear as a bell', 1 being 'fresh and clear', etc.

check_mind

check_mind

check_mind(50)

  • Returns: true or false, or a string
  • Description: By itself returns a string representing the level of exp in your head ('clear as a bell', 'fried', 'muddled', etc). If given an integer, returns true or false if you have the corresponding percentage of exp in your head.

percentmind

percentmind

percentmind(80)

  • Returns: integer, or true or false
  • Description: By itself returns an integer ranging from 0-100 representing the percentage of exp in your head. If given an integer, returns true or false if you have at least that percentage of experience. Both saturated and fried show up as 100 percent - a user interested in distinguishing between the two can add a checksaturated or saturated? qualifier to their percentmind check.

checkright/checkleft

checkright

checkleft "broadsword"

  • Returns: true or false, or a string
  • Synonyms: righthand?/lefthand?
  • Description: Give them a string and will return true/false if it matches what you're holding, or the last word in the item name if used by itself. If your hands are currently empty, it will return 'nil' (identical to 'false' in a logical comparison) regardless of whether it was given an argument or not. This behavior can be useful to make absolutely certain a 'take' command succeeded, for instance.

checkstance

checkstance

checkstance "offensive"

checkstance 0

  • Returns: true or false, or a string
  • Synonyms: stance
  • Description: With no arguments, returns the string representing your current stance. With a numerical or string argument, returns a boolean flag indicating if the current stance matches the given string. For string based comparisons, this will correctly test against the stance values possible if using Combat Mastery or [[Stance Perfection]], while integer based arguments will perform a precise comparison.

check(thing)

checkstanding

checkspell "spirit defense"

checkdead

  • Returns: mostly true/false
  • Synonyms: checkstanding; checknotstanding; checksitting; checkprone; checkkneeling/kneeling?; checkprep/prepped?; checkmind; checkgrouped/checkjoined/joined?; checkwebbed/webbed?; checkstunned/stunned?; checkdead/dead?; checkhidden/checkhiding/hidden/hiding?; checkname/myname?; checkspell/checkactive/active?
  • Description: Most are true if you are (checkstunned for example), false if you aren't; they all follow the same basic behavior as the above-documented 'check' commands.

checkname

checkname

checkname "Shaelun"

  • Returns: string or true/false
  • Description: True/false if given a string and the names match, or just returns the character name if given no arguments.

checkstamina

checkstamina 50

checkstamina

  • Returns: true/false or an integer
  • Description: Only in StormFront (there is no auto-updated stamina tag in Wizard). Given no arguments, returns your current stamina. Given a number, returns true/false based on whether you have at least or more than that number.

checkrt / checkcastrt

checkrt

checkcastrt

  • Returns: value of roundtime
  • Description: Returns a value of how much roundtime left. Useful for IF statements.

checkmana/checkhealth/checkspirit

checkmana 50

  • Returns: identical as above
  • Synonyms: health, health?, mana, mana?, spirit, spirit?
  • Description: Identical to checkstamina.

maxhealth/maxstamina/maxmana/maxspirit

fput "eat my acantha leaf" while (checkhealth < maxhealth)

  • Returns: integer
  • Description: Returns your maximum health/spirit/stamina/mana as an integer (class Fixnum). Takes no arguments.

percenthealth/percentmana/percentspirit/percentstamina

fput "eat my acantha leaf" while (percenthealth < 90)

  • Returns: integer
  • Description: Returns an integer (0-100) representing the percentage of your current health/mana/whatever in relation to your max.

checkspell

checkspell "elemental defense i"

  • Returns: true/false
  • Synonyms: active?
  • Description: Returns true if the spell you give it is active, false if it isn't (only available if you use the infomon script, since that's what keeps track of this).

Wounds

Wounds.torso

Wounds.neck

Wounds.lhand

  • Returns: an integer
  • Variations: Wounds.head; Wounds.neck; Wounds.abs; Wounds.lhand; Wounds.rhand; Wounds.larm; Wounds.rarm; Wounds.chest; Wounds.back; Wounds.rleg; Wounds.lleg; Wounds.nerves
  • Description: Returns the current wound rank (numerically). If I had 'deep gashes and serious bleeding' on my chest, Wounds.chest would return the integer 3. If I had no wound there, it would return 0.

Scars

Scars.abs

Scars.nerves

Scars.rleg

  • Returns: an integer
  • Description: Identical to Wounds above, but for scars instead of wounds.


Lich toggles

# QUIET

# QUIET

  • Returns: n/a
  • Description: This is a special directive that must be a Ruby comment placed as above in the first line of the Lich script. Lich will ordinarily bookend the lifetime of a script with --- Lich: (scriptname) active. and --- Lich: (scriptname) has exited. This option omits those lines, allowing a script to start and exit silently.

hide_me

hide_me

  • Returns: updated value of the setting (true/false)
  • Description: Toggles on/off the 'hidden' setting. When this setting is on (defaults to off), a script will not be listed when the user types ;list. It will still show up under ;list all. There is no way to prevent a script from being being displayed in ;list all.

i_stand_alone

i_stand_alone

  • Returns: updated value of the setting (true/false)
  • Description: Toggles on/off. Removes a script from ALL data feeds; a script using this will receive no game lines and no unique data whatsoever (unless they toggle it back off). If Lich can more or less ignore that a script exists and not bother with keeping its data stacks up-to-the-second with game data and anything else it's requested, then a script has virtually no overhead whatsoever (meaning any resources it requires come only from what it does independantly). Useful for some scripts who have no need to eat up resources being fed game data (such as dict.lic).

no_kill_all

no_kill_all

  • Returns: updated value of the setting (true/false)
  • Description: Toggles on/off the 'no kill all' setting: when this setting is on (defaults to off), a script will not be affected by the user typing ;kill all. A script with this set to on must be killed specifically (by typing ;kill [script], or just ;kill). There is no way to prevent a script from being killed when targeted by the user.

no_pause_all

no_pause_all

  • Returns: updated value of the setting (true/false)
  • Description: Toggles on/off the 'no pause all' setting: when this setting is on (defaults to off), a script will not be affected by the user typing ;pause all. A script with this set to on must be killed specifically (by typing ;pause [script], or just ;pause). There is no way to prevent a script from being paused when targeted by the user.

silence_me

silence_me

  • Returns: updated value of the setting (true/false)
  • Description: Toggles on/off the 'silenced' setting. A script with this on will not have commands it sends to the game echoed to your game window. A script run in SAFE mode cannot change this setting (attempting to do so will generate a warning and otherwise have no effect).

status_tags

status_tags

  • Returns: ?
  • Description:Tells Lich to send this script XML tags rather than stripping them, or, if already doing so, tells Lich to go back to stripping the XML. If called with the argument "on" or "off", switches to that setting and echoes that it has done so.

toggle_echo

toggle_echo

  • Returns: updated value of the setting (true/false)
  • Description: Toggles on/off the 'suppress echo' setting. A script with this on will not execute any 'echo' commands, but will silently ignore them instead; it's designed more for people who don't want clutter in their game window but still want to make use of an existing script. Commands sent to the game are still echoed to the game window.

toggle_unique

toggle_unique

  • Returns: updated value of the setting (true/false)
  • Description: When a script is set as being 'unique', it does not receive normal game data; instead it only receives what the user sends to it by typing ;send to (script) (message). This is of use if a script wants to only act on a user's input or has no use for game data (it provides a method for scripts to make sure game data doesn't accidentally get recognized as a user's input, and also serves to prevent scripts from slowly eating away at system resources because the script never checks or clears its data buffer -- see the 'clear' command for more on that).

toggle_upstream

toggle_upstream

  • Returns: updated value of the setting (true/false)
  • Description: This must be enabled to allow the script to intercept what you send to the game. See the separate upstream section for more detail.

Lich::Util

issue_command()

Lich::Util.issue_command(command, start_pattern, end_pattern = /<prompt/, include_end: true, timeout: 5, silent: nil, usexml: true, quiet: false)

Lich::Util.issue_command('tattoo menu', /List of flash tattoos available \(Page \d+\):/

  • Returns: returns result as an array of strings.
  • Description: Will attempt to issue the command(string) given and capture the returning output from the begging start_pattern(regex) until the end_pattern(regex) is seen or the timeout(int) is reached. include_end(booleen) will indicate whether the last line of the end_pattern is included in the array. silent(boolean) will determine if the command is sent silently or echo'd to the frontend. usexml determines whether the start/end pattern is matching against the xml feed or plain txt feed. quiet flag determines whether the output is squelched or shown to the front end. The only required values needed are command and start_pattern. Everything else has default values that can be used or changed.

quiet_command_xml()

Lich::Util.quiet_command_xml(command, start_pattern, end_pattern = /<prompt/, include_end = true, timeout = 5, silent = true)

Lich::Util.quiet_command_xml("tattoo menu", /List of flash tattoos available \(Page \d+\):/)

  • Returns: returns result as an array of strings.
  • Description: Will attempt to issue the command(string) given and capture XML buffer lines once the start_pattern(regex) is seen till the end_pattern(regex) is seen or the timeout(int) is reached. include_end(booleen) will indicate whether the last line of the end_pattern is included in the array. silent(boolean) will determine if the command is sent silently or echo'd to the frontend. end_pattern, include_end, timeout, and silent do not need to be included unless changing the default values.

quiet_command()

Lich::Util.quiet_command(command, start_pattern, end_pattern, include_end = true, timeout = 5, silent = true)

Lich::Util.quiet_command("tattoo menu", /List of flash tattoos available \(Page \d+\):/, end_pattern = /Type TATTOO MENU again in the next minute to display the next group of flash tattoos\./)

  • Returns: returns result as an array of strings.
  • Description: Will attempt to issue the command(string) given and capture buffer lines once the start_pattern(regex) is seen till the end_pattern(regex) is seen or the timeout(int) is reached. include_end(booleen) will indicate whether the last line of the end_pattern is included in the array. silent(boolean) will determine if the command is sent silently or echo'd to the frontend. include_end, timeout, and silent do not need to be included unless changing the default values.

silver_count()

Lich::Util.silver_count(timeout = 3)

Lich::Util.silver_count

  • Returns: an integer of how much silver you have
  • Description: useful to know the amount of silver one has on themselves.

Lich::Messaging

monsterbold

Lich::Messaging.monsterbold(msg)

Lich::Messaging.monsterbold("This text I want to monsterbold")

  • Returns: an encoded string with proper monsterbold tags depending on FrontEnd used
  • Description: Will take the string given and return it with monsterbold before/after and xml_encode the msg.

msg_format

Lich::Messaging.msg_format(type, msg)

Lich::Messaging.msg_format("info", "Let's make this text pretty!")

  • Returns: an encoded string with start and end tags to change the color in the FrontEnd
  • Description: Returns the string given with color coding based on the type chosen. Current options are as follows:
    • error, yellow, bold, monster, creature
    • warn, orange, gold, thought
    • info, teal, whisper
    • green, speech, debug, light green

msg

Lich::Messaging.msg(type, msg)

Lich::Messaging.msg("info", "Let's make this text pretty!")

  • Description: sends the string given to the client encoded for the type given.

stream_window

Lich::Messaging.stream_window(msg, window)

Lich::Messaging.stream_window("Let's send this to a different window!", "familiar")

  • Description: send the string to the various stream window. Currently supports the familiar, speech, thoughts and loot window.

xml_encode

Lich::Messaging.xml_encode(msg)

Lich::Messaging.xml("Let's encode some text!")

  • Returns: an xml encoded text

mono

Lich::Messaging.mono(msg)

Lich::Messaging.mono("Let's mono some code!")

  • Returns: force mono formatted string to be displayed properly using XML output class of mono

Settings

Settings are specific to the script itself. For example, a setting with the name "bank" in fetch_turnips.lic have no effect on the "bank" setting in buy_cheese.lic.

Settings.load

Settings.load

Settings["SettingName"]

Settings["SettingName"]

Settings.save

Settings.save

Settings.clear

Settings.clear

  • Returns: either a hash representing your settings, or 'nil' if no settings for the script exist
  • Description: Note that Settings.clear will erase all settings, but it will NOT save that on its own. Issue a Settings.save command after the Settings.clear if you want that script's settings reset permanently.


Upstream

upstream_get

upstream_get

  • Returns: a string
  • Description: Same thing as "get" except it fetches the last line the user sent to the game. A script has to ask Lich to give it this information by first using the "toggle_upstream" command.

upstream_get?

upstream_get?

  • Returns: a string
  • Description: Attempts to get the last line the user sent to the game, but does not wait for a line to be sent. A script has to ask Lich to give it this information by first using the "toggle_upstream" command.

upstream_waitfor

upstream_waitfor "climb stairs"

  • Returns: a string
  • Description: Identical to "waitfor" but only checks the upstream commands (the commands sent to the game by the user).


Interscript communication

running?

running? "test"

  • Returns: true/false
  • Description: Takes a string and returns true/false if the given script is active or not.

send_to_script

send_to_script 'scriptname', 'message to send'

  • Returns: true or false
  • Description: The target script will be sent a string exactly as though it came from the game. Returns true if successful, false if the script wasn't found to be active.

send_scripts

send_scripts "To the running scripts, this line looks identical to one that came from the game"

  • Returns: true/false
  • Description: Same as 'send_to_script', but sends a line to all scripts instead of just one.

start_script

start_script "test"

start_script "heal", [ "shaelun", "adhara" ]

  • Returns: true/false
  • Description: Simulates the user having entered ;test in the game entry box. Returns 'true' if the script was successfully started, 'false' if for any reason it couldn't be found/started. The optional second argument (which must be an array, as seen in the above example) can be used to simulate arguments to the script (the above example would simulate the user typing: ;heal shaelun adhara).

start_scripts

start_scripts "test"

start_scripts "test", "calcredux", "etc"

  • Returns: true/false
  • Description: Executes a "start_script" command for every argument given. Note that you cannot give a script arguments when using this command.

pause_script

pause_script

pause_script "test"

  • Returns: true/false
  • Description: If given no arguments, pauses the script using the command. If given a string, pauses the script who's name matches that string; if the script is not currently active, returns 'false' ('true' if the script was paused successfully).

unpause_script

unpause_script "test"

  • Returns: true/false
  • Description: Unpauses the script you give it. Note that because of the way the 'script is paused' state is handled, it's conceivable for a script that was paused to actually still be executing commands internally for a brief time -- a script isn't actually "stopped dead in its tracks" until it attempts to interact with the game in some way (by fetching game data, sending game data, or by attempting a command that requires the script to be identified). Since most commands identify a script (including this one), this command cannot unpause the script itself: when it attempts to unpause itself, it will be identified as being paused and will be halted where it is until it's unpaused by another script or the user (or killed). When it is, it will be allowed to continue, and will then try to unpause itself (pointlessly, since it was just unpaused...).

kill_script

kill_script "test"

  • Returns: true/false
  • Synonyms: kill_scripts, stop_script, stop_scripts
  • Description: Simulates the user having entered ;kill test in the game entry box and hitting enter; takes multiple scripts to kill. If the script is not running, returns false; if the script was found to be active and was killed, returns true.


Unique

See toggle_unique for more about the 'unique' stack.

unique_get

unique_get

  • Returns: a string
  • Description: Fetches a line from the unique stack, as opposed to the game data stack ().

unique_send_to_script

unique_send_to_script 'scriptname', 'message to send'

  • Returns: true or false
  • Description: Same as 'send_to_script', but the script will receive the string sent in its 'unique' stack instead of its 'game data' stack (see toggle_unique for more info).

unique_waitfor

unique_waitfor "continue"

  • Returns: a string
  • Description: Same as 'waitfor' but acts on the 'unique' queue.


Exit handling

exit

exit

  • Returns: does not return
  • Description: Ends the script.

die_with_me

die_with_me "test", "calcredux", "etc"

  • Returns: true
  • Description: If the given scripts are active at the time the script using this command ends ("exit", finishes, gets killed by the user, or dies in error) they'll all be killed automatically (produces no notification to avoid clutter, but the scripts are indeed stopped). The given scripts need not be running (or technically even exist) at the time this command is used -- it only updates the setting, and that setting isn't actually acted upon until the script is killed.

before_dying

before_dying { echo "Oh God, why have you killed me dear user...?!" }

before_dying { Settings.save }

  • Returns: true
  • Description: Performs the given actions right before the script exits. Note nothing is done at the time this command is used (it simply sets what should be done just before the script is killed). The block given to this command is actually wrapped up into a proc object (an object of the 'Procedure' class), and scheduled to be run when the script is killed/exits (if multiple procs exist, they are executed sequentially in the order they were declared). Because of this, the same 'binding' principles that apply to other proc objects apply here (in a nutshell, if a variable didn't exist when you declared the 'before_dying' stuff, then you can't use it in the 'before_dying' code; if it did exist at the time though, you *can* use it, even if it doesn't really exist in the script when it dies). Also note that if the command(s) take more than 0.5 seconds to complete, they're forcibly aborted and the script is killed regardless (this is to prevent a possibly bad situation where a script makes a mistake in the 'before_dying' command and is refusing to stop executing due to errors). Note that if a script is set as executing in SAFE mode, all the restrictions that normally apply will also apply in the 'before_dying' code block (this cannot circumvent that, nor can anything else for that matter).

undo_before_dying

undo_before_dying

  • Returns: true
  • Description: Clears any 'before_dying' commands that have been used for the script.

abort!

abort!

  • Returns: does not return
  • Description: Immediately kills the script, bypassing any 'before_dying' blocks that have been registered. Probably won't ever be of use, but it's a way to make the calling script go away as fast as possible (note that it isn't any faster than the 'exit' command is, it just makes sure that nothing except stopping the script happens).


Spell

The Spell class combines spell information from spell-list.xml and character information from infomon to greatly simplify basic spell handling.

Spell[number].cast()

Spell[503].cast Spell[503].cast('Tilmen')

  • Returns: returns result as string ( ie cast roundtime, hinderance, etc. )
  • Description: Attempt to cast spell given using info from spell-list.xml

Spell[number].affordable?

Spell[503].affordable?

  • Returns: returns true or false
  • Description: Useful for knowing if you have enough mana for spell

Spell[number].active?

Spell[503].active?

  • Returns: returns true or false if spell is active
  • Description: Will return true if the spell is currently active on yourself, false if it is not.

Spell[number].timeleft

Spell[503].timeleft

  • Returns: returns number
  • Description: Returns amount of time left as value

Spell[number].force_cast()

Spell[503].force_cast Spell[503].force_cast('Tilmen')

  • Returns: returns result as string ( ie cast roundtime, hinderance, etc. )
  • Description: Attempt to force cast spell

Spell[number].force_channel()

Spell[503].force_channel Spell[503].force_channel('Tilmen')

  • Returns: returns result as string ( ie cast roundtime, hinderance, etc. )
  • Description: Attempt to force channel spell

Spell[number].force_evoke()

Spell[503].force_evoke Spell[503].force_evoke('Tilmen')

  • Returns: returns result as string ( ie cast roundtime, hinderance, etc. )
  • Description: Attempt to force evoke spell

Spell[number].force_incant()

Spell[503].force_incant

  • Returns: returns result as string ( ie cast roundtime, hinderance, etc. )
  • Description: Attempt to force incant spell

Effect

active?

Effects::Spells.active?("Call Familiar")

Effects::Spells.active?(920)

Effects::Cooldowns.active?("Mana Leech")

Effects::Buffs.active?("Rapid Fire")

Effects::Debuffs.active?("Silenced")

  • Returns: true or false
  • Description: Used to detect whether the given effect is currently active. Spells can be referenced by number or name, unless the spell does not have a number, then must be referenced by name. Name can only be used when FLAG ShowSpellName is set to ON.

time_left

Effects::Spells.time_left("Call Familiar")

Effects::Spells.time_left(920)

Effects::Cooldowns.time_left("Mana Leech")

Effects::Buffs.time_left("Rapid Fire")

Effects::Debuffs.time_left("Silenced")

  • Returns: time left in minutes as a floating number
  • Description: Used to determine how much time is left on a given effect.

Weapon

known?

Weapon.known?(name)

Weapon.known?("Charge")

  • Returns: true or false
  • Description: Used to detect whether the weapon skill given is known to the character.

affordable?

Weapon.affordable?(name)

Weapon.affordable?("Charge")

  • Returns: true or false
  • Description: Used to detect whether the weapon skill given is affordable for the character.

available?

Weapon.available?(name)

Weapon.available?("Charge")

  • Returns: true or false
  • Description: Checks whether the weapon skill is known, currently affordable, and that no known current cooldown or Overexerted debuff would block it's use.

CMan

known?

CMan.known?(name)

CMan.known?("Garrote")

  • Returns: true or false
  • Description: Used to detect whether the cman skill given is known to the character.

affordable?

CMan.affordable?(name)

CMan.affordable?("Garrote")

  • Returns: true or false
  • Description: Used to detect whether the cman skill given is affordable for the character.

available?

CMan.available?(name)

CMan.available?("Garrote")

  • Returns: true or false
  • Description: Checks whether the cman skill is known, currently affordable, and that no known current cooldown or Overexerted debuff would block it's use.

Shield

known?

Shield.known?(name)

Shield.known?("Shield Charge")

  • Returns: true or false
  • Description: Used to detect whether the shield skill given is known to the character.

affordable?

Shield.affordable?(name)

Shield.affordable?("Shield Charge")

  • Returns: true or false
  • Description: Used to detect whether the shield skill given is affordable for the character.

available?

Shield.available?(name)

Shield.available?("Shield Charge")

  • Returns: true or false
  • Description: Checks whether the shield skill is known, currently affordable, and that no known current cooldown or Overexerted debuff would block it's use.

use

Shield.use(name, target = "")

Shield.use("Shield Charge", "Wyrom") Shield.use("Shield Charge", 9000)

  • Description: Attempts to use the shield skill given on target specified. Target can be a GameObj, integer, or string. If no target given, will issue command with no target, relying on game-engine targeting.

Armor

known?

Armor.known?(name)

Armor.known?("Armor Blessing")

  • Returns: true or false
  • Description: Used to detect whether the armor skill given is known to the character.

Feat

known?

Feat.known?(name)

Feat.known?("Absorb Magic")

  • Returns: true or false
  • Description: Used to detect whether the feat skill given is known to the character.

affordable?

Feat.affordable?(name)

Feat.affordable?("Absorb Magic")

  • Returns: true or false
  • Description: Used to detect whether the feat skill given is affordable for the character.

available?

Feat.available?(name)

Feat.available?("Absorb Magic")

  • Returns: true or false
  • Description: Checks whether the feat skill is known, currently affordable, and that no known current cooldown or Overexerted debuff would block it's use.

GameObj

The GameObj class tracks various objects in the same room as you, and makes their game id, name, noun, status, and contents available to you.

GameObj arrays

Several arrays are exposed by GameObj. They include:

GameObj.inv

  • Returns: an array of objects of the GameObj class representing the things you are wearing.

GameObj.pcs

  • Returns: an array of objects of the GameObj class representing the other players in the room, or nil if there are none.

GameObj.npcs

  • Returns: an array of objects of the GameObj class representing the npcs in the room, or nil if there are none.

GameObj.loot

  • Returns: an array of objects of the GameObj class representing the loot in the room, or nil if there is none. For the purposes of this function, loot is anything that Simu hasn't tagged with monster bold. Any exits or anything that shows up in the "You also see" line will be included.

GameObj.room_desc

  • Returns: an array of objects of the GameObj class representing any links found in the room description, or nil if there are none.

GameObj.dead

  • Returns: an array of objects of the GameObj class representing the dead npcs in the room, or nil if there are none.

GameObj.fam_pcs, GameObj.fam_npcs, GameObj.fam_loot, GameObj.fam_room_desc

  • Returns: an array of objects of the GameObj class. Similar to the ones above, except for your familiar's room, and these don't stay up-to-date without having your familiar look at the room.

GameObj.targets

  • Returns: an array of objects of the GameObj class representing the hostile npcs in the room, the mobs, the monsters, whatever you want to call them.

GameObj.target

  • Returns: an object of the GameObj class representing the current target you have selected, if any.

Finding game objects with GameObj

Now that you've got an object or array of objects, here's what to do with them:

target = GameObj.npcs.find { |npc| npc.status.nil? }
if target
   fput "attack ##{target.id}"
end

  • Description: This example shows (in an over-simplified way) the most common use of the GameObj class. First, "GameObj.npcs" gives an array of all the npcs in the room. Then, ".find" searches each item in that array. For each item in the array, the code inside the brackets following "GameObj.npcs.find" is run, and "npc" represents the item it's currently looking at. The code inside the brackets acts like an if statement, and as soon as it is true, "target" is assigned the npc object.

The "status" method applies to npcs and pcs (using it on others won't give an error, but it will always return nil). The status is basically whatever shows up after "that appears", "that is", or "who is". So, if you also see a kobold that appears stunned, its status will be "stunned". In the example, we're looking for an npc with a nil status, because that represents an npc that's standing and not stunned, dead, prone, etc. The game never shows "You also see a kobold that is standing."

Now suppose there's twenty kobolds in the room, and only the fifteenth one is standing. How can you be sure you attack the standing one? This is where the kobold's id comes in handy. Simu assigns an id to almost everything in the game. Stormfront uses these ids when you click on links. For the most part, these ids can be used just like nouns. "attack ##{target.id}" will attack the npc you found earlier, even if other npcs are walking in and out of the room. The double pound sign is not a typo.

Other GameObj methods

GameObj.containers

  • Returns: a Hash of ids (as Strings) mapping to arrays of objects of the GameObj class. Each id represents an accessible container that GameObj is aware of with the given id. The id maps to an array of objects of the GameObj class representing that container's contents.

For a container to be added to the Hash, GameObj must first be made aware of its contents by some sort of interaction with the container, looking in it, opening it, and more. (Someone who knows the specific cases, please add detail!)

GameObj.right_hand, GameObj.left_hand

  • Returns: an object of the GameObj class representing whatever is in your hand. Currently, if there is nothing in your hand, it still returns a GameObj where the name is "Empty".

Useful and hopefully self-explanatory methods to use once you have the right GameObj object

.id
.name
.noun
.status
.contents


Script

The Script class deals with and runs scripts.

Script.start

  • Description: Starts the specified script. Arguments for that script should be passed as a single string. A hash can also be passed with other script options (:quiet, :force, and you can also use :name and :args instead of passing one/two strings).

Script.run

  • Description: Starts the specified script and waits while it runs. Arguments for that script should be passed as a single string. A hash can also be passed with other script options (:quiet, :force, and you can also use :name and :args instead of passing one/two strings).

Script.list, Script.running, Script.hidden

  • Returns: An array of Script objects for every running/visible/invisible script.
  • Note: This is not the same as ;list. The Script class does not have a defined to_s method.

Script.running?

  • Description: Checks whether a script is running (paused or not)
  • Returns: true or false

Script.pause

  • Description: Pauses a script
  • Returns: true if the script was paused successfully, false otherwise (script not running or already paused)

Script.unpause

  • Description: Unpauses a script
  • Returns: true if the script was unpaused successfully, false otherwise (script not running or was not paused)

Script.paused?

  • Returns: true if a script is running and paused, false otherwise

Script.exists?

  • Returns: true if a script with the given name is in the user's script directory, false otherwise. extension is optional.

Script.log

Appends to the script's .log file in the lich/log directory.

Script.db

Gets you a sqlite3 database for your script, of type SQLite3::Database (http://www.rubydoc.info/github/luislavena/sqlite3-ruby/SQLite3/Database)

Script.version

Script.version("infomon")

  • Returns: Ruby Gem version
  • Description: Takes a string(script) and returns the current version in header of script as a Ruby Gem version

Script.version("infomon", "1.18.0")

  • Returns: true/false
  • Description: Takes a string(script) and minimum required version

Global variables

$PROGRAM_NAME

Ruby's global variable capturing current script -- in this case, the path to Lich.

$frontend

Frontend detected by Lich.

$login_time

Local time the current Lich session started.

Lich Constants

LICH_DIR

Path of the current Lich directory.

SCRIPT_DIR

Path to directory Lich is using to for scripts.

DATA_DIR

Path to the directory Lich is using for data.

LOG_DIR

Path to the directory Lich is using for logs.

LICH_VERSION

Lich version.

Builtin Lich shortcuts

These automatically perform multiple checks or commands.

take

take "box", "coffer", "ruby", "etc"

  • Returns: a string (the last line the 'fput' command saw)
  • Description: Picks up every item listed and puts each one in turn into your 'lootsack:' setting by issuing the commands with fput.

fetchloot

fetchloot

  • Returns: a string
  • Description: Performs a 'look' and takes/puts away all items on the ground that aren't listed in your 'excludeloot:' setting. Return value is the last line from the game.
  • See also: GS now natively includes the command LOOT ROOM with a similar effect.

Lich.fetchloot

Lich.fetchloot

  • Returns: a string
  • Description: Identical to 'fetchloot' in all ways except only the items listed in your 'treasure:' setting are fetched.

walk

walk

  • Returns: true or false
  • Description: Moves in a random cardinal direction (what's seen in the 'Obvious exits:' line), storing the direction moved, and returning 'true' if there is a critter in the room or 'false' if there aren't any NPCs in the room. The stored direction will not be among the random directions chosen the next time the 'walk' command is used (unless it hits a dead-end, then it will backtrack the way it came).

run

run if not health(50)

  • Returns: true or false
  • Description: Will execute a 'walk' command repeatedly until it enters a room with no critters, at which point it returns and the script will pick up execution on the next line (does not continue to run away).
  • See also: wander.lic is a popular and sophisticated auto-moving creature-finding script.

watchhealth

watchhealth(50) { echo "Uh, your health is below 50..." }

watchhealth(50, proc_object)

  • Returns: nothing useful
  • Description: Returns immediately so that the calling script continues to run as normal, and while it does, monitors your health. If it falls below the number you give it, executes the block you passed to it. Only does this once -- if you want it to repeat as the script executes (be careful, chances are your health will still be below 50 after the block executes once) then pass watchhealth a proc object that includes a line registering itself over again (as in, a proc that includes a 'watchhealth(#, self)' thingie). If your health never falls below the number you give it, then nothing happens; once the script ends, it stops watching.

goto

goto "MainLabel"

  • Returns: (has no return value, the current execution stack is discarded and the jump never returns)
  • Description: Identical to standard Wizard/SF scripts; the label to jump to has to be in quotes, and it is (kinda sorta) case insensitive. The label declaration itself (the LABEL: line) MUST NOT be in quotes: only the name of the label when you use the goto command. If there are two labels with the same name but different capitalizations, the goto command will attempt to be case sensitive.


See also


References

  • The initial content of this article was copied from the scripting documentation posted by Tillmen which formerly resided at http://lichproject.com/
Retrieved from "https://gswiki.play.net/index.php?title=Lich:Software/Scripting_reference&oldid=225898"