Lich scripting reference

The Lich scripting engine allows you to automate many of your routine tasks through scripts. Lich scripts are written in Ruby, so you have some powerful Ruby features available, such as GTK bindings to create GUIs.

If you are more comfortable with Wrayth and Wizard scripts, Lich can run most of them unaltered, but since Lich is running them, you can have any number of them running simultaneously. Lich is highly compatible with Wrayth/Wizard scripts, so you can use your existing scripts and scripting experience when writing Lich scripts.

Running a Script

By preceding your script name with the prefix character, which defaults to a semicolon ; character, you can run a script. For example, if you created a script named sell-loot then issuing the command ;sell-loot would run the sell-loot script.

Passing Variables to Scripts

You can also supply arguments to the script by adding the arguments after the script name. A script can act on these arguments or use them to modify the behavior.

;sell-loot gems

This will run the sell-loot script with variable[1] set to "gems".

;sell-loot gems skins

This will run the sell-loot script with variable[1] set to "gems" and variable[2] set to "skins". Sometimes you want to use spaces in your arguments, so you can use quotes:

;sell-loot "a fancy gem" skins

This will set variable[1] to "a fancy gem" and variable[2] to "skins".

Stopping a Script

A script ends when it reaches the last command or encounters the exit command. A script can be killed with the ;kill command.

Labels and the Goto Command

A label is a spot in the code where a command can branch to with certain commands. They are given unique names followed by a colon. For example:

loop:
move n
goto "loop"

This script contains one label named loop. As written, this script will continually move north until it is killed by the user e.g. via ;kill. Because of the goto loop, it will never end on its own.

A script label can be any string of characters, so long as it does not have a space. Each label must be unique in a script. You cannot have two labels with the same name. For the purposes of matching labels, case is ignored. Therefore "Bob" is the same as "bob" is the same as "BOB" etc.

There is a special catch-all label labelError. If a script command tries to branch to a label that is not found, the script will abort with an error unless there is a labelError: label. If the label exists, it will branch this catch-all label.

Label names can be constructed from variables in commands such as goto. For example:

goto "label" + variable[1]

label1:
echo "The first variable was 1"
exit

label2:
echo "The first variable was 2"
exit

label3:
echo "The first variable was 3"
exit

Commands that work in DR

Wrayth-like commands

put

put "look"

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

bput

bput "get box", 'you pick up', 'get what?'

• Returns: the string that was accepted as meaning the action succeeded (see below)
• Synonyms: blocking put
• Description: Part of the common helper functions for actions in scripts. It's named 'blocking put' is designed to be a more robust version of fput in situations where you know the desired response from the game. Unlike fput which will resend the same command repeatedly until it sees the desired message first from the game, bput only sends a given command one time (unless round time or type ahead errors occur) and then waits for the desired response. if the desired response isn't seen bput will eventually time out and echo debugging information. The command (fput "forage grass", 'Roundtime') would never work because the game sends a response line "You search around..." before "Roundtime" is encountered. Similarly a command that can only succeed once can cause fput to hang. In this case, you have to deal with the failure case and just spam the command until failure in a noisy room with fput (fput "get box", 'you pick up', 'get what?'). To get around all of this you can use bput to ensure that the command is matching (ex. bput "get box", 'you pick up', 'get what?'). It puts in the command and then waits until a successful match.

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.

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.

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 "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 capitalization, the goto command starts acting as though its case sensitive).

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.

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

Waits, matches, and such

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

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.

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

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. A script that uses this command will need to be trusted because it makes use of eval.

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

Upstream

toggle_upstream

toggle_upstream

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

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

Check commands

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.

checkstamina

checkstamina 50
 checkstamina

• Returns: true/false or an integer
• Description: Only in Wrayth (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.

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.

checkmana/checkhealth/checkspirit

checkmana 50

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

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.

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

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.

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.

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.

checkpoison

checkpoison

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

checkdisease

checkdisease

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

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

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.

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.

Commands for the script itself

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.

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 effected by the user typing ;kill all. A script with this set to on must be killed specifically (by typing ;kill [script], or just ;kill). There is no way to prevent a script from being killed when targeted by the user.

silence_me

silence_me

• Returns: new 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.

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 independently). Useful for some scripts who have no need to eat up resources being fed game data (such as dict.lic).

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" code blocks that have been used for the script. 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).

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 clearcommand for more on that).

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

unique_waitfor

unique_waitfor "continue"

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

Commands for other scripts

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.

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

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.

running?

running? "test"

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

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.

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

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.

Commands that don't work in DR

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

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

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).
• Infomon won't run in DR

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 corresponding 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).
• Will only return nil

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.
• Returns an empty string in DR.

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.