DungeonCrawl

Reference

General

There are three main layers described below, and each element may have its own state values.

Dungeon

The dungeon is a collection of levels. It is at the top of the heirarchy, and is the root from where the levels sprout.

Level

The level is a collection of tiles, and is a member of a dungeon. The visible representation is only in two dimensions, but there are three dimensions used for denoting the position of a map tile (row and column for the 2d, and z_index for the layer or position on the stack). A player moves their avatar around the board only on tiles that are not blocking. A row/column coordinate without any tiles is treated as impassable, as are the edges outside the board itself.

Tile

The tile is a single element in a level, and is the leaf of the hierarchy. It makes up everything, from walls, floors, monsters, as well as player avatars. The player avatar map tile is similar to other map tiles. A map tile is simply an object with has coordinates (row, column, z_index), a character that is displayed (such as "M"), a foreground color, a background color, as well as state values and a script (state and script are optional). State values tell about the tile's state, such as if it is blocking, or pushable, as well as other information that might be used in its script (such as number of cycles left for a count down). The script controls more complicated behavior of the tile (further reference below).

Tile State Attributes and Values

There are several standard behaviors based on certain state values of a tile.

State Attribute	Standard Behavior
blocking	If this is false, the tile is not blocking. Another tile will not be prevented from moving on top of it. When true (or not present), it acts as a wall and stops another tile from moving onto it. Additionally it sends the "THUD" message to any tile attempting to move there.
low	If this is true, and the tile is also blocking, movement will still be restricted. However, when conditions such as fog exist, it will not block the players vision. Additionally, a tile that is "flying" will be able to pass over this tile.
flying	If this is true, this tile will be able to move over low and blocking tiles.
pushable	When true, the map tile may be shoved around by another map tile moving into its row column coordinates. The pushed map tile will attempt to move in the same direction that the pushing tile is moving (ie, tile A moves west to tile B's coordinates, tile B will attempt to also move west). However, if the pushed tile cannot move (such as another blocking tile is where it would be going), then it does not move, and blocks the other tile.
squishable	When true, the map tile may be "squished" which removes it. A map tile that is squishable, but not pushable will be removed when another tile moves into its row column coordinates. However, if it is pushable, it will move in the manner described for a pushable map tile if able; and if unable it will then be removed and the "squishing" tile will enter its coordinates.
destroyable	When true, this map tile will be removed if it receives the "SHOT" or "BOMBED" message.
teleporter	This indicates that the tile is a teleporter. For it to be active, the tile also needs "facing" set. When a player moves (or something is pushed) onto one of these tiles from the opposite direction it is facing, it may be teleported to a tile farther away but still in line. Candidate destinations include the tile past the teleporter, and tiles on the other side of other teleporters facing the activated transporter. If no candidates are available, it will not transport (pushables may be pushed out of the way on the teleport movement).
not_pushing	If set to true, this tile will not push tiles when moving. It will treat a pushable tile as non blocking (unless that tile actually has the blocking value true).
not_squishing	If set to true, this tile will not squish tiles when it is moving.
health	This is used to indicate how much health a tile has. When it reaches or drops below zero, the tile is removed (unless that tile is a player's tile). Where destroyable indicates a tile can be destroyed when shot, bombed or damaged, a tile with health could be shot, bombed or damaged many times before destroyed.
damage	This is how much will be subtracted from a tile's health when this tile sends it a "SHOT" or "BOMBED" message. Defaults to zero.
wait_cycles	How many cycles a script will wait until executing the next instruction after it executes an instruction that causes it to wait (ie, a movement instruction). Defaults to 5. Each cycle is approximately 50ms.
pullable	Indicates a tile is pullable. When true, the tile will follow when pulled (when false, it wont). If `linear`, then the tile may only be pulled the same direction the puller is moving. Pullable directions may be specified by any combination of the `nsew` characters. Finally, when this is set (at runtime) as a `map_tile_id`, then it may only be pulled by the tile with a matching id. This setting is treated as "pullable: true" for the first pull, and that objects "pullable" state value will be set to the first map tile id that pulls it. Defaults as false.
pulling	When this tile is pulled, it will attempt to pull another nearby tile. This defaults to false. When it is an integer, it will only pull the map tile with id matching this value. When `map_tile_id`, this value will be replaced with the id of the tile it pulls on a pull command or chain pull. If nothing is pulled, then pulling will be set to false. This helps to create double linked chains of map tiles that will only pull one specific tile, and will only be pulled by one specific tile.
points	When a destroyable tile (ie, one with health or simply `destroyable: true` as a state value) is destroyed the points to award to the player (tile) that did it. This is the tile that sent the shot/damaging message that resulted in the tile with points being destroyed. When this tile has an `owner`, specified by that state value, the points will go to that tiles score instead. Bullet and bomb explosion automatically will have the player that fired the bullet (or lit the bomb) as the owner.
owner	The ID of the tile that owns this one. Mainly used to determine whom to give points to when a tile is destroyed via standard behaviors.
light_source	For "dark" levels, indicates that this tile is a light source when true. Light is blocked by "blocking" tiles that are neither "low" nor not "blocking_light", and the light radiates outward from the source so shadows may be cast, similar to fog.
light_range	For "dark" levels and a light_source tile, indicates how far the light goes. Default range of a light_source is 6 when this state variable is not present.
blocking_light	When false, this tile will not block light or player vision even though "blocking" is true and movement may be prevented. By default a blocking tile will block light and vision.
Player Tile Specific
player	Indicates the tile is a player tile
score	The players score. Mainly used on the scoreboard. Score can be given via GIVE command, but also points will be added to the score when a player causes another tile to be destroyed via a bullet or blast from a bomb.
steps	How many steps (ie, movements) the player has taken this game.
deaths	How many times the player has died
duration	How many seconds the player had already spent in the dungeon. Used for calculating total duration for the score when a dungeon has saving enabled.
lives	How many lives a player has. -1 for infinite lives. Otherwise, triggers an end game event when it reaches zero, preventing the player from respawning.
gameover	Indicates that the players game has ended. This is set by the GAMEOVER command, or when the player runs out of lives.
already_touched	This is used internally when a player moves, and should not be explicitly set. It is set to false after a player has moved, and when it is true will cause the movement to not send touch events to all the tiles at the destination coordinates. This is due to internal implementation of a players movement that first sends the touch events, evaluates any programs for the destination tiles that respond to a touch command, (sets "already_touched" to true to not send the touch events again), moves the player tile to the destination if able, then resets "already_touched" back to false.
ammo	How much ammo the player has
health	The players HP; when it reaches zero the player dies and is replaced by a grave. Depending on the dungeon they may have the opportunity to respawn, although their stuff will be buried in the grave, including equippable items they did not start with.
gems	Number of gems a player has. They can be used in trading.
cash	Similar to gems, can be used for trading.
torches	How many torches the player has. These can be used to generate light that radiates from the players tile on dark levels. A torch will usually provide light for about 30 seconds.
torch_light	How long the torch will last, represented by a colored bar 6 units long. On the last unit, the light range is greatly diminished.
keys	These can be used to open colored doors that match the color of the key. Gone after one use, but sometimes the player may carry more than one of the same color key.
equipped	The item (represented as the item's "slug"ified name) the player currently has equipped, which may be used by holding shift and pressing a direction.
equiment	The items (represented by the item's "slug"ified names) the player currently has. By pressing e, a dialog will open allowing the user to equip anything from their equipment.

Level State Attributes and Values

There are several standard behaviors based on certain map state values. These will only impact the level (and not any other levels in the dungeon).

State Attribute	Standard Behavior
reset_player_when_damaged	Defaults as false. When this is set to true, if a player takes damage, their position will be changed to the coordinates they entered the map. This can be useful when creating a puzzle that has obstacles that can damage a player, and one wants to add extra challenge by requiring a player make it through the course without being hit or damaged by an obstacle (be it a monster, beam wall, etc).
reset_when_no_players	Resets the level when there are no players. This can be helpful for puzzels that can or need reset when a player fails to solve them.
pacifism	Defaults as false. When this is set to true, a player may not use a weapon item (ie, shift+direction will not spawn a bullet or activate the currently equipped weapon).
solo	Defaults as false. When false, the level is univeral and every player will use the same instance. When set to true, each player will have their own instance of this level and will not encounter other players.
visibility	This sets what the player can see of the level. By default, the top down view of the current level is seen entirely. When it is set to "fog", then the players vision is restricted to line of sight up to a certain number of tiles away. Blocking tiles can also cast a shadow unless the blocking tile is also "low".
fog_range	Optionally, when visibility is set to "fog", this sets the number of tiles away that a player can see. When not set, the player can see up to six tiles away.
fade_overlay	Controls the display of the fade overlay which can be useful to help a player find their avatar when changing levels. When set to "off", the fade overlay will not be used on that level. When set to "passages" (the default when the state value is not set) the fade overlay will not be shown when traveling to adjacent levels but will be shown when using a passage (which could place the player in a very different location on the next level). When set to "on", the fade overlay will always trigger.

Dungeon State Attributes and Values

There are several standard behaviors based on certain dungeon state values. These are general options for the entire dungeon.

State Attribute	Standard Behavior
no_scoring	When this is set to true, when an end game event occurs no score will be recorded for the player(s). Defaults to false.
saveable	When set to true, players will be able to save their progress when they quit. The dungeon instance will be persisted, even when there are no players remaining. Defaults to false.
starting_lives	The number of lives a player starts with. When a player dies, they lose a life. When their lives reach zero the game ends. Defaults to -1 (infinite lives), but can be set to a positive integer. Players can gain lives (ie, the GIVE command may increase the number of lives); their starting lives are set when they join the dungeon.
starting_equipment	What items a player starts in the dungeon with. This should be a space separated list of item slugs. The first item in the list will also be the default item equipped. When not explicitly set, defaults to "gun".

Scripting

A script can be defined which will control additional behavior of the map tile beyond the basic built in state values. A script begins running commands starting at the top, and working its way down. Certain commands, such as movement, will pause the script for a noticable amount of time (determined by the "wait_cycles"). When a map tile receives a message it can react to, the program will jump and start executing instructions from that point. A message will be reacted to if it is one of the standard behaviors, or if the map tile has a matching label in its script.

The script will continue to run until there are no more instructions it can run, or it encounters the END or TERMINATE instruction. For the former two, the script will be idle, and will no nothing further unless it receives a message to which it is able to respond. A script may recieve messages that will be queued in the order they were recieved. When running the script, when its status becomes `idle` or `waiting`, if there are messages, the top one will change the program counter and jump execution to that if that label exists and is active (also changing the status to `alive`), otherwise the next message will be handled. When there are no more messages for that program, and the program status is `idle` or `waiting`, then the next program will be run.

One instruction per line. Each line may have a prefix, denoting what that line is.

A script for an equippable item is similar to the script for a tile (which is described above). The main difference to keep in mind, is that when an equipped item is activated, its script will run and behave as if the player's (or whomever used the item's) tile is the context. Ie, any tile state attributes referenced will be those of the tile using the item (as the item itself does not have any state). Item scripts should be kept short, and will run starting from the first line each time the item is used. Additionally, the "DIE" command will remove, or unequip, the item. And any item that is "consumable" will also be unequipped after use.

Prefix	Type	Description	Examples
:	Label	When a map tile receives a message, this is where the program will start executing instructions at. There can be many of the same label, but the highest active label will be used. Labels can be activated and deactivated, but are initially active.	:open
@	State Value	This is for setting state values. "@", followed by the name of the state value, followed by an operator, followed by a value.	@open = false @HEALTH += 30
@@	Level value	Similar to the State Value, however this is for the entire level. There are a few special level values which are read only and return the boundary row/col: north_edge, west_edge, south_edge, east_edge. This can be useful for objects that need to know when they've reached the edge via a IF command.	@@ALARM = true #IF @col >= @@east_edge, something
&	Dungeon value	Similar to the State Value, however this is for the entire dungeon. This is useful for when one level sets a flag, and another level checks to see if it has been set.	&alarm = true #IF &countdown == 0, doorslocked
?<target>@	Other's State Value	Not to be confused with the Shorthand for try. This is for setting state values of another object. There may be occasions when the GIVE or TAKE commands are insufficient. The target can be a direction, "sender" (for the event sender if applicable) or the id of the target object. Additionally, {@state_val} can be used to determine the target from a state value of the current object (which should resolve to a direction or object id). Cannot target a player object. Additionally, if the target is invalid (ie, nonexistant, a player, etc), this will act as a noop. Its also important to note that this will not trigger any side effects (such as killing and removing an object from the board when its health reaches zero), unlike the TAKE command. Some of these are read only; such as ?random@[number] which cannot be assigned a different value.	?north@locked = true ?{@facing}@blocking = false ?12345@health += 10
/	Shorthand	Shorthand for the "GO" command. Slash followed by a n, s, e, or w (for north, south east or west). Shorthands can be chained together on the same line	/n/s/n/s
?	Shorthand	Shorthand for the "TRY" command. Question mark followed by a n, s, e, or w (for north, south east or west)	?n?s?n?s /n?e?e
#	Command	Run a command. Commands will sometimes have a list of parameters, or a list of keyword arguments (KWARGS). See the command reference further down.	#BECOME slug: breakable_wall, color: @color #SEND_MESSAGE north, touch
<no prefix>	Text	This will display a text message to the player that sent the last message (ie, a player tile touches a tile and said player sees a message). If there were none, nothing noticable happens. When there are several adjacent text commands, they may be displayed together in a text modal, instead of the side chat log. To include values interpolated at run time, wrap them in a ${ } in the line.	Hello player My color is ${ @color }, and name is ${ @name }
!<label>;<text>	Text Action	This will display a linked text message to the player. The display of the text will appear as a clickable link in a text modal. When clicked, the link will send the message given between the '!' and ';' to that object.	!buy_gems;Buy Gems !no;Answer "No"
~<conditional>, <number>	Text Conditional	This will display the following lines of text if the conditional is true, otherwise the number of lines specified after the comma will be ommitted. The conditional are similar to the conditional for the IF command.	~?sender@gems > 10, 1 ~not @waiting, 1

Script Commands

Some of the commands have shorthand equivalents. When available those may be used instead, at a slight cost to readability.

A successful move will change the tile's facing to the direction it moved.

Some parameters call for a direction.

north
south
east
west
up
down
left
right
idle - no direction. a movement command given idle as the direction will stay in the same place
player - direction towards a targeted player. If none are targeted, one will be selected randomly.

Variable prefixes

Parameters can be a literal value, and sometimes can be a variable. A variable will have a prefix, denoting its type.

Prefix	Description	Examples
@	state value for the tile	@open @facing
@@	state value for the level	@@flag_1
&	state value for the dungeon	&locks -= 1
?	Not to be confused with shorthand TRY (as mentioned in a section above). Another map tile or thing. `?sender` refers to the map tile that sent the last message. Additionally, `?@` can be used to refer to a state value for a tile in that direction the map tile/object that sent the last message. Some commands require a tile, and some commands require a value. An interpolated direction may come from the map tile's state value by using `?{@}@`. `?random@{upper bound}` may be used to get a random integer from between 1 and the upper bound. This can be useful for "random" chance in IF commands, to maybe go to a label only some of the time. `?any_player@is_facing` is special. `is_facing` is special in that it is a check for a target being directly in line (ie, when the object is facing west, the target must be west and on the same row, a row above or below will not return true). Instead of `any_player` a specific player map tile id may be used (`?{ @target_player_map_tile_id }@is_facing`) to only return true for a specific player (or other map tile).	?sender ?sender@health ?south@blocking ?{@facing}@blocking ?random@5 ?any_player@is_facing ?{ @target_player_map_tile_id }@is_facing
<prefix><variable>+<string>	An interpolated value can also be defined by a variable followed by a plus "+" and a string. This is useful for certain things, such as giving a color key based on the map tile's color, and using it to unlock a color door (based on the doors color).	@color+_key might be used for a GIVE command, and might be resolved as "red_key". Similarly, the door could have a TAKE command that uses "@color_+key" for the thing to take, and jump to a different label if the player did not have 1 (or more) stored as the "red_key" state value.

Scripting Commands

Command	Params	Description
BECOME	KWARGS	Transforms the object refernced by the id in some way. Changes can include character, color, background color. Additionally, if given a `slug`, the tile will be replaced with the matching tile template corresponding to the given slug. If the slug has a script, that script will replace the currently running one. If the slug has state, the state will be merged on top of the existing state key/values (a key not existing in the slug's state but existing for the tile won't be overwritten). Other changes given, such as name, character, color, background color, will override the values from the matching tile template. Other values not mentioned above will set state values.
#BECOME slug: breakable_wall #BECOME character: X, background_color: #000, color: #fab
CHANGE_STATE	list - 3	Changes the object's state element given in params. The params also specify what operation is being used, and the value to use in conjunction with the value from the state. When there is no state value; 0 is used as default. The shorthand for this command should be used instead.
@open = true @ammo += 10 @gems /= 2
CHANGE_LEVEL_INSTANCE_STATE	list - 3	Changes the level instance state_values element given in params. (Similar to change_state)
@@red_flag = false @@locks -= 1
CHANGE_DUNGEON_INSTANCE_STATE	list - 3	Changes the dungeon instance state_values element given in params. (Similar to change_state)
&red_flag = false &locks -= 1
CYCLE	list - 1	Sets the cycle speed of the object. The cycle speed is how quickly the object moves. It defaults to 5 (about one move every 5 ticks, where a tick is ~50ms currently). The lower the number the faster. Lowest it can be set is 1.
#CYCLE 3
DIE	none	Stops and removes the running script for the map tile.
#DIE
END	none	Changes the program state to idle. No further instructions will run, but the script will respond to messages (ie, a TOUCH event)
#END
EQUIP	list - 2, 3, or 4	Give a tile an equippable item. This will add the item slug to the tiles `equipment` list, but does not set it as `equipped`. If the item_slug is invalid, this command will do nothing. The third and fourth parameters are optional, but the fourth parameter requires the third. The first parameter is the item_slug, second parameter is whom to give the equipment. The third parameter is the max number of that equipment the tile may have, and the fourth is the label to jump to if the tile is at the max number.
#EQUIP gun, ?sender #EQUIP gun, ?sender #EQUIP bucket, ?sender, 3, MAX_BUCKET
FACING	list - 1	Changes the direction the object is facing. Valid directions include the cardinal directions, (north south east west up down left right) as well as rotations, and "player". Nothing done if the object has no facing if reverse, clockwise, or counterclockwise (the three rotations) are specified. player will cause the object to face the player it is targeting (a player will be picked to target if it is not already targeting one - state value at "target_player_map_tile_id").
#FACING player #FACING south #FACING counterclockwise
GAMEOVER	list - 0-3	This triggers the end of the game, and records scores when applicable. The three parameters are optional, the first being a boolean for victory (true) or loss (false). the second is the result the scores will be recorded as (ie, Win, Lose, etc, defaults as "Win") and is really a more wordy version of the first parameter but could be used to specify different win or lose conditions. The third is player(s) for which this command will end the game. Only three valid values `?sender`, a player map tile id, or `all`. Defaults to the event sender, which will end the game will be ended for only that player. When `all`, the game ends for all players in the dungeon.
#GAMEOVER #GAMEOVER true, Victory #GAMEOVER false, Loss, all
GIVE	list - 3, 4, or 5	Give a tile an amount of something. This modifies the state of that tile by adding the amount to whatever is at that key is at (creating it if not already present). First parameter is `what` (the state field, ie `ammo`), second the quantity (must be a positive number). Quantity may reference a state value for the giving tile. Third is the receiving tile of it. Fourth and fifth parameters are max amount the recieving tile may have (the command will give up to this amount if present). If receiving tile is already at max, then the fifth parameter is the label where the script will continue running from. Forth and fifth are optional, but the fifth parameter will require a valid fourth parameter. Valid tiles can be a direction - ie, north, south east, west; additionally the specail varialble `?sender` can be used to give to the program/player that sent the last event. For example, if a player touches a certain object, that object could give them gems.
#GIVE cash, 10, north #GIVE ammo, 6, ?sender #GIVE health, @heals, ?sender, ?sender@max_health, at_max_health
GO	list - 1	Move in the given direction. When the tile cannot move in that direction (ie, its blocked), it will retry until successful. The front slash "/" followed by a direction character (n, s, e, or w) or another character (i for idle, c to continue moving in the direction its facing, or p to move towards the targeted player) is this command's shorthand, and several shorthand commands may be on the same line.
#GO player /i/i/s/s/c /s
IF	list - 1 - 2	Conditionally jump to a label. If the expression evalutes to true, instructions will be executed starting next at the first active matching label (nothing happens if there is no matching active label). When no label is given, or an integer is given instead, if the expression is false, then the following N instruction(s) will be skipped over. This is useful for when you want to conditionally skip over the next N instruction(s). Several comparison operators are supported: == - both sides are equal != - both sides are not equal < - left is less than the right > - left is greater than the right <= - less than or equal >= - greater than or equal =~ - true when the right is included in the left (useful for seeing if a tile has a certain piece of equipment) !~ - true when the right is not included in the left
#IF @open, ALREADY_OPEN #IF ?sender@blocking, TOUCH #IF @timer > 0, CONTINUE #IF ?{@facing}@blocking, TOUCH #IF @north #IF @skiptext, 10 #IF ?sender@equipment =~ gun, ARMED
LOCK	none	Locks the object. This will prevent it from receiving and acting on any message/event until it is unlocked. The underlying state value `locked` can also be directly set via the state shorthand `@locked=true`.
#LOCK
PASSAGE	list - 1	Registers the coordinates the map tile/object is at as a passage exit which will be a candidate for the match_key. The passage exits are used by the TRANSPORT command (where the exit used may be specified by the match_key).
#PASSAGE up #PASSAGE @background_color
PULL	list - 1 or 2	Similar to the TRY command. The main difference is that the object will pull an adjacent map tile into its previous location if able. If the pulled tile has the state value `pulling` set then that tile may also pull an adjacent tile to where it was (this can be chained).
#PULL north #PULL south, true
PUSH	list - 1 or 2	Pushes a nearby (or above) tile in the given direction if that tile hash the `pushable` standard behavior. Tiles may be pushed up to the given `range` (default of 1) away. For example, a pushable tile immediately to the west would be pushed one more space to the west when `direction` is west and `range` is one. A tile in range will be pushed up to one space for each invocation of a push method.
#PUSH north #PUSH @facing, 3
PUT	KWARGS	Puts a new tile specified by the given "slug" in the given "direction". If no "direction" is given, then the new tile is placed on top of the tile associated with the running script. Alternatively, instead of putting a slug, an existing tile may be used instead, by using `clone` and the id of the tile to use as a base (or just a straight up clone). If there is a script on the cloned tile, the script will start from the top (and not where the script is currently executing on the original tile). Additionally, instead of a direction, "row" and "col" coordinates can be supplied to put the tile in a specific location. Direction can also be given to put the tile one square from the given coordinates in that direction. If both "row" and "col" are not given, then neither are used. If the specified location or direction is invalid/off the map, then nothing is done. The "shape" kwarg is for placing multiple tiles at once in a particular shape. Valid shapes include: "line", "cone", "circle", and "blob". When "shape" is given, "range" should also be given to indicate how far from the active tile the shape will go. "line" and "cone" need a "direction" as well. "cone" can also use "width", which determines how many tiles on either side of the center line the cone will go. "bypass_blocking" can be true, false, or "soft" ("soft" by default). When true, blocking tiles are ignored when drawing the shape. When false, blocking tiles will act as barriers when drawing the object (which is drawn in line of sight from the tile to the end of the range, except for "blob"). When "soft", it behaves similar to the false setting, except that blocking tiles which are also "soft" will be treated as open spaces where the shape may be drawn over. "include_origin" defaults to false (except for circle), and this kwarg indicates whether or not the origin (ie, the active object) will be included in the shape or not. Other kwargs can be given, such as name, character, color, background color, and will override the values from the matching tile template. Other values not mentioned above will set state values. Reference variables can be used instead of literals; however if they resolve to invalid values, then this command will do nothing.
#PUT slug: expanding_foam, direction: south, color: @color #PUT slug: wall, row: 1, col: 1
RANDOM	list - 2 or more	Sets the specified state variable to a random value from a list or range. The first parameter is the state variable, and the subsequent parameters can be a list of values to randomly choose from OR an integer range. An integer range may be specified by a low bound and a high bound with a hyphen in the middle (ie, 1-10). The range is inclusive, and a random integer within the bounds (inclusive) will be used. Both the list and the range have a uniform distribution.
#RANDOM hits, 5-10 #RANDOM direction, north, south, east, west
REPLACE	KWARGS	Replaces a map tile. Uses KWARGs, `target` and attributes prefixed with `target_` can be used to specify which tiles to replace. `target` can be the name of a tile, or a direction. The other `target_` attributes must also match along with the `target`. At least one attribute or slug KWARG should be used to specify what to replace the targeted tile with. If there are many tiles with that name, then all those tiles will be replaced. For a direction, only the top tile will be removed when there are more than one tiles there. If there are no tiles matching, nothing is done. Player tiles will not be replaced.
#REPLACE target_color: red, color: blue #REPLACE target: wall, target_color: green, slug: floor
REMOVE	KWARGS	Removes a map tile. Uses kwargs, the `target` KWARG in addition to other attribute targets may be used. Valid targets are a direction, or the name (case insensitive) of a tile. If there are many tiles with that name, then all those tiles will be removed. For a direction, only the top tile will be removed when there are more than one tiles there. If there are no tiles matching, nothing is done. Player tiles will not be removed.
#REMOVE target_color: green #REMOVE target: south #REMOVE target: locked door
RESTORE	list - 1	Restores a disabled ('zapped') label. This will allow it to be used when an event is sent to the object/program. Nothing is done if all labels that match the given one are active. Reactivates labels prioritizing the one closer to the end of the script.
#RESTORE touch #RESTORE thud
SEND	list - 1 to 3	Sends a message. A message can be sent to the current running program, or to another program. The first parameter is the message to send, and the second (optional) param is the target. The third (optional) param is the delay for the message. Default is zero (which sends the message immediately). A positive integer is the number of seconds to wait before triggering the message after the command is run. This is useful for when a player will not be hanging out in the level, and there are events that still need to happen after a period of time. Using the idle, ?i, movement could be used for a similar delay, however those idle commands will not run when the instance is idle and so it would make that even take longer to occur (provided the level is active at all). Both the label and the name are case insensitive. Valid targets include: self (this is used when no target explicitly given), all (all running scripts will be sent this message, including this one), others (all other running scripts will be sent this message), a direction, the name of a tile, or `global` (all running scripts will be send this message, including running scripts in different level instances). A direction takes priority over a tile name. The special varialble `?sender` can be used to send the message to the program that sent the event. `here` can be used to send the message to all the tiles at the same location as the message sender (including the message sender).
#SEND touch, ?sender #SEND close, all #SEND done #SEND grow, self, 60
SEQUENCE	list - 2 or more	Sets the specified state variable to the next value in the given sequence. The first parameter is the state variable, and the subsequent parameters are the sequence values. Starting with the first item in the list, each time this command runs it sets the state value to that item in the sequence. Ie, first time it runs, the state value is set to the first item in the sequence, the second time it is set to the second item in the sequence, etc. When the last item has been assigned, it starts back over at the first item
#SEQUENCE c, red, blue #SEQUENCE count, 9, 8, 6, 3, 1
SHIFT	list - 1	Rotates all the `pushable` tiles in the 8 adjacent squares about the object. Valid parameters are `clockwise` or `counterclockwise` to rotate in those respective directions. If a `pushable` tile is blocked by a blocking tile that cannot be pushed, that tile will not be moved.
#SHIFT clockwise #SHIFT counterclockwise
SHOOT	list - 1	Fires a bullet in the given direction. The bullet will spawn on the same tile as the object. The bullet will walk in given direction until it hits something, or something responds to the "SHOT" message.
#SHOOT north #SHOOT @facing
SOUND	list - 1 or 2	Play a sound effect. The first parameter is the slug of the sound to play. This will be heard by players in the level instance. The second optional parameter indicates who can hear it. May be set to ?sender, a specific player, "all" (to play for everyone; volume constant on the preceeding options), or "nearby" (to only play for players close to the source and the further, the quieter it will be. Default behavior is "nearby".
#SOUND beep #SOUND beep, all #SOUND beep, ?sender
TAKE	list - 3 or 4	Take from a tile an amount of something. This modifies the state of that tile by subtracting the amount from whatever is at that key is at (creating it if not already present). If there is not enough to take, nothing is taken and optionally a label can be given to jump script execution. First parameter is `what` (the state field, ie `ammo`), second the quantity (must be a positive number). Quantity may reference a state value for the giving tile. Third is the losing tile of it. Fourth, optional, is the label to have the program use if the target tile does not have enough to take. Valid tiles can be a direction - ie, north, south east, west; additionally the special varialble `?sender` can be used to give to the program/player that sent the last event. For example, if a player touches a certain object, that object could give them gems.
#TAKE gems, 1, north #TAKE cash, 10, ?sender, toopoor
TERMINATE	none	Ends the running script and removes it. The map tile will no longer have a running script, and will not respond to messages (other than standard behaviors). Useful when you want a map tile to stop doing things, but don't want the map tile removed outright.
#TERMINATE
TRANSPORT	list - 2 or 3	Transports a player map tile from one level to another level that is part of the same dungeon. First param is the who (which should resolve to a map tile id; but if its not a player's map tile this command will do nothing). Second param can either be a fixed level number, "up" or "down" (up or down will resolve to the level above or below the current one). If the level doesn't exist the nothing will be done. Third param is optional, and is used to specify what passage_exit will be used. For example, if the match key is "green", then only passage exits that also have that match key will be considered. When more than one match, one is randomly picked. Also, when there is no match key specified, a random passage_exit will be used. When no match key is specified, and there are no passage exits, then a random spawn coordinate will be used as a last option (for levels with no explicit spawn coordinates, any floor tile will count as a spawn coordinate).
#TRANSPORT ?sender, up, stairs_down #TRANSPORT @target_player, 1, blue
TRY	list - 1	Attempt to move in the given direction, if blocked the object doesn't move and moves on to the next command. The question mark "?" followed by a direction character (n, s, e, or w) or another character (i for idle, c to continue moving in the direction its facing, or p to move towards the targeted player) is this command's shorthand, and several shorthand commands may be on the same line.
#TRY west ?w?w?c ?i
UNEQUIP	list - 2, 3, or 4	Takes from a tile an equippable item. This will remove the item slug from the tiles in the `equipment` list, and clears `equipped` if the tile no longer has any of that slug in its `equipment` list. If the item_slug is invalid, this command will do nothing. The first parameter is the item_slug, second parameter is from whom to take the equipment. The third parameter is the label to jump to if the tile does not have this item.
#UNEQUIP stone, ?sender #UNEQUIP bucket, ?sender, NO_BUCKET
UNLOCK	none	Unlocks the object. This will allow it to receive and act on any message/event it may receive. The underlying state value `locked` can also be directly set via the state shorthand `@`.
#UNLOCK @locked = false
WALK	list - 1	Continue to move in the given direction until bumping into something. Similar to `TRY` but repeats until it cannot move in the given direction anymore. This can be used when the distance a tile should go is unknown, instead of chaining together multiple tries in a direction.
#WALK west #WALK player
ZAP	list - 1	Disables a label. This will prevent the label from being used to change the pc when the program/object recieves an event. Nothing is done if all labels that match the given one are inactive. Disables labels prioritizing the one closer to the top of the script.
#ZAP touch

System messages

Currently there are only a few messages that will be sent automatically when certain things happen. These message may also be send via the SEND command artifically.

Message	When Sent
THUD	Send to the map tile when it attempts to move but is blocked.
TOUCH	Sent when a moving map tile attempts or successfully moves to a map tile already at those coordinates.
OPEN	Sent by a player tile when a player hits the O key plus a direction.
CLOSE	Sent by a player tile when a player hits the C key plus a direction.