Lich:Software/Scripting reference

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.

References

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