Lich:Software/Scripting reference

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

cast

cast(908)

cast(908,"wraith")

• Returns: a string based on outcome of casting the given spell. Outcomes would be the cast roundtime, spell hindrance, not enough mana, and likely others
• Description: Will check that you have enough mana for desired spell, and if so cast the spell. If no target given it will selfcast buffs or open cast if utility/attack. Will automatically change stance based on spell being cast. Will return a string that can be matched to determine if the spell was successfully cast, blocked due to spell hinrance, or if you did not have enough mana.

pause

pause 1

pause '2s'

pause '3m'

pause '2h'

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.

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.

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

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

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

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

unique_waitfor

unique_waitfor "continue"

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

wait_while

wait_while { percenthealth != 100 }

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

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

wait_until

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

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.

toggle_upstream

toggle_upstream

• Returns: updated value of the "upstream" flag (true/false)
• Description: See above.

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

undo_before_dying

undo_before_dying

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

abort!

• Returns: never returns
• 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

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.

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.

Settings.load

Settings.load

Settings["SettingName"]

Settings.save

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.

toggle_unique

toggle_unique

• 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

no_kill_all

• 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 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 'no_pause_all' setting (true or 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.

hide_me

hide_me

• Returns: updated value of the 'hidden' setting (true or 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.

silence_me

silence_me

• Returns: updated value of the 'silenced' setting (true or 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).

toggle_echo

toggle_echo

• 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

checkpoison

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

checkdisease

checkdisease

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

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

unique_get

unique_get

• 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

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.

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

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

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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.

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.

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.

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

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

dothis

dothis "action here", "string 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, "string to match for success"

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

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.

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.

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

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.

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.

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.

start_wizard_script

start_wizard_script "test", [ "command line variable(s)", "etc" ]

• 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. Note: This command no longer exists in the latest versions of lich

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.

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

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.

running?

running? "test"

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

variable

variable[1]

• Returns: an array, possibly empty
• 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

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

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

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.

Wounds.torso

Wounds.torso

Wounds.neck

Wounds.lhand

(etc)

• Returns: an integer
• 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

Scars.nerves

Scars.lleg

(etc)

• Returns: an integer
• Description: Identical to the Wounds.(bodypart) commands seen above, but for scars instead of wounds.

Spell

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

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.

GameObj arrays

There's a number of arrays 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.

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

• Description: 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)

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.

See Also

• The Lich

References

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