Table of Contents
Writing Scripts
The script must be executable (e.g. chmod +x with an appropriate shebang). For some languages, it may be necessary to write a wrapper script to start the program. Additionally, on Windows systems where the shebang is not supported, the player must provide a means of running such a script. For example script python <path-to-script> if you are using python.
A Note on Newlines
All newline characters used in the scripting interface consist of the singular “\n” (decimal 10, hexadecimal 0x0a) character, aka Unix-style newlines. No other newline schemes are supported by the interface. A note to Windows users: Simple printline code or a .bat file echo command will not work.
Existing Format
Commands to client
Here is a list of command the script can send to client.
- watch <command type> - watch the given command from server-client protocol. <command type> specifies the commands we want to watch. Set to empty to get all commands.
- Besides what is already documented, watch also supports “tick”, “drawextinfo” (for most servers), and “drawinfo” (for very old servers)
- The “tick” argument will provide the script with “watch tick <integer>”, as a tick of the server's clock.
- “drawextinfo” provide the script with text printed in the Messages text area. The format is “watch drawextinfo <integer> <integer> <message>”. For some very old servers (none of them which are online at the time of writing), “drawextinfo” is not supported and you must fall back to “drawinfo”, which has the arguments “watch drawinfo <integer> <message>”.
- unwatch <command type> - unwatch the given command from server-client protocol. <command type> specifies the commands we want to watch. Set to empty to get all commands.
- request <data type> - Request a piece of information from client memory. Following is a table of <data type> allowed:
| Data Type | Comment |
|---|---|
| range | Return the type and name of the currently selected range attack |
| stat <type> | Return the specified stats |
| stat stats | Return Str,Con,Dex,Int,Wis,Pow,Cha |
| stat cmbt | Return wc,ac,dam,speed,weapon_sp |
| stat hp | Return hp,maxhp,sp,maxsp,grace,maxgrace,food |
| stat xp | Return level,xp,skill-1 level,skill-1 xp,… |
| stat resists | Return resistances |
| weight | Return maxweight, weight |
| flags | Return flags (fire, run) |
| items inv | Return a list of items in the inventory, one per line |
| items actv | Return a list of inventory items that are active, one per line |
| items on | Return a list of items under the player, one per line |
| items cont | Return a list of items in the open container, one per line |
| map pos | Return the players x,y within the current map |
| map near | Return the 3×3 grid of the map centered on the player |
| map all | Return all the known map information |
| map <x> <y> | Return the information about square x,y in the current map (relative to player position) |
| player | Return the player's tag and title |
| skills | Return a list of all skill names, one per line (see also stat xp) |
| spells | Return a list of known spells, one per line |
| stat paths | Return spell paths: attuned, repelled, denied |
Note: player, skills, spells, stat path were added between versions 1.11 and 1.50 of the GTK2 client.
Unfinished Business
The "request stat <type>" command
| Stat Type | Comment |
|---|---|
| flags | Return “request flags <firing> <running> <gtk-compat/obsolete?>” where values are integers 1 and 0 for true and false, respectively, and indicate whether or not a player is currently firing or running.  : Verify obsolesence |
* Request Commands *
VERIFIED Send: “request player” Returns: “request player <name> <title>” Note: <name> contains no spaces whereas <title> may contain several as the field ends at the newline.
VERIFIED Send: “request range” Depending on what your Range slot contains, this function may return data in several formats. * If nothing is equipped: “request range Range: nothing” * If an item was equipped automatically due to the invocation of a spell or prayer: “request range Skill: holy symbol” or “request range Skill: talisman” without the details of which holy symbol or talisman was equipped. * Bows/Crossbows: “request range Range: <rangedname> (<ammunition>)”, e.g. “elven bow (arrows)” * Spells: “request range Range: spell (<spell name>)”, e.g. “request range Range: spell (meteor swarm)” * Everything else: “request range Skill: <skillname>”, which is whatever you skill is required to use the weapon you equipped last; invoking a spell or prayer may automatically equip a talisman or a holy symbol and return that literally as a skill.
Send: “request weight” Returns: “request <maxweight> <carryingweight>” Note: Both values returned are integer grams.
The request stat * command
The “request stat <x>” is a command with several types and is documented seperately here:
VERIFIED Send: “request stat cmbt” Returns: “request stat cmbt <wc> <ac> <dam> <speed> <weaponspeed>” Note: All returned values are integers; wc and ac may be negative. To convert the speed values into fractional ones seen in the clients, divide them by 100000.
VERIFIED Send: “request stat hp” Returns “request stat hp <hp> <maxhp> <sp> <maxsp> <gr> <maxgr> <food>” Note: All returned values are integers. The sp and gr values may exceed the corresponding maxsp and maxgr values in certain situations (e.g. praying over an altar of your deity will eventually raise your gr to maxgr x 2 and may also raise your sp over maxsp depending on deity).
VERIFIED
Send: “request stat paths”
Returns: “request stat paths <attuned> <repelled> <denied>”
Note: All returned values are integers and are at present undefined. : Define
TODO: Verify Command: “request stat resists” Returns: “request stat resists <physical> <magic> <fire> <electricity> <cold> <confusion> <acid> <drain> <ghosthit> <poison> <slow> <paralyzation> <turn> <fear> <depletion> <death> <holy-word> <blindness>” All values are signed integers.
VERIFIED
Command: request stat stats
Returns: All your stats including all positive and negative effects due to equipment and spells. : Verify spells
Format: “request stat stats <str> <con> <dex> <int> <wis> <pow> <cha>”
All returned values are integers.
VERIFIED Command: request stat stats_applied Returns: request stat stats_race <str> <con> <dex> <int> <wis> <pow> <cha> Note: All values are integer zeroes. TODO: Sort out why command is borked.
VERIFIED Command: request stat stats_base Returns: request stat stats_base <str> <con> <dex> <int> <wis> <pow> <cha> Note: All values are integer zeroes. TODO: Sort out why command is borked.
VERIFIED Command: request stat stats_race Returns: request stat stats_race <str> <con> <dex> <int> <wis> <pow> <cha> Note: All returned values are integers and represent the base stats for your race.
* Multi-line output request commands *
VERIFIED Command: request items inv Returns: * Zero or more of “request item inv <tag> <count> <weight> <flags> <type> <title>” lines followed by “request items inv end”.
Return values:
<tag> - server-internal identifier for the item <count> - the number of items <weight> - the weight of the item(s) in grams (divide by 1000 to get kgs as displayed in the clients) <flags> - see below for valid flag values <type> - server-internal item type <title> - description of the item(s); encompasses the rest of the line
The flags value:
This is an integer using individual bits to designate whether or not a property applies to an item. For simplicity, decimal and hexadecimal values are given:
Open 0x04 Applied 0x08 Locked 0x10 Unpaid 0x20 Damned 0x40 Cursed 0x80 Magic 0x100
Command: request items actv This command is functionally equivalent to “request items inv” returning only items with the Applied flag set. The line prefix is “request items actv” however, and the termination string is “request items actv end”.
* Map Commands *
Commands: request map all
Repeats: request map all <x> <y> <darkness> <smooth1> <smooth2> <smooth3> <fog-of-war> heads <heads1> <heads2> <heads3> tails <tails1> <tails2> <tails3>
Values:
* x and y, integers: the coordinates of the tile; arbitrary (and may be negative), but relative to one another
* darkness, integer: the darkness of the tile; arbitrary byte value - : Verify
Note: Contrary to the command name, this command returns an arbitrary number of tiles surrounding you, not the entire map. The size of the map returned is server-specific.
* all smooth values: the character “y” or “n”
* fog-of-war, character: “y” or “n” indicating the presence of fog of war on the tile
* heads and tails values: server-specific types for the appearance of the tile
Quirks: heads and tails values will change with 1) tile animation and 2) the presence of a town portal on a tile
Commands: request map near Repeats: request map near <x> <y> <darkness> <smooth1> <smooth2> <smooth3> <fog-of-war> heads <heads1> <heads2> <heads3> tails <tails1> <tails2> <tails3> Terminates with: “request map near end” Note: The values returned are as “request map all” in every respect except that the tiles returned are of the spot on which you are standing and those immediately adjacent, nine in total.
Note: The title result terminates at newline and may include the number of that item you are carrying Note: All returned values are integers.
Send: request stat xp XXX Returns “request stat xp <level> <xp> <sp> <maxsp> <gr> <maxgr> <food>” Note: All returned values are integers.
