Voxatron Designer User Manual

version 0.2.10 // by zep

(c) 2011-2014 Lexaloffle Games LLP

guydiggingapothole.gif This manual is a work in progress! warningskullandcrossbones.gif

Check the BBS for more information: http://www.lexaloffle.com/bbs

Feel free to post questions there about how anything works until the manual is more complete.

Welcome to Voxatron Designer! This manual describes how to create new content for the Voxatron Engine including levels, custom monsters, weapons, music, sound, and to make entirely new games that utilise the Voxatron's volumetric display format.

1.0  Basic Concepts

1.1  Cartridges

A voxatron cartridge (or 'cart') contains one playable game or level, similar to a real-world console cartride. Each cartridge is saved as a single .vxc.png file can be shared with other users.

1.2  Object Definitions and Resource Tree

An object in Voxatron is anything that might appear in the game world including actors, pickups, rooms, music, sound and scripts. Object definitions are organised in a tree referred to as the 'Resource Tree'.

1.3  Props and Animations

The most basic type of object, a prop is a single static voxel model. Animations are a folder of props that are placed in sequence, along with a few paramters such as how fast the animation should be played.

1.4  Rooms and Object Instances

Voxatron is a room-orientated game and engine; only one room is shown or simulated at one time. A room is constructed by arranging object instances at various times and locations, along with rules dictated when each object should appear.

1.5  Actors

Objects that can move around and interact with each other are called actors. The most common actors are monsters, players and pickups.

1.6  Objects IDs and States

Every object definition and object instance has a global id that is unique to the whole cartridge. This allows objects to be referred to across rooms in order to, for example, open a door in another room when a level is pulled. [move

If an object spawns one or more actors, the actor(s) inherit that id. This allows triggers to refer to the state of the actors by using the OBJ_ID selector.]

2.0  Designer Interface Overview

2.1  Navigator

All of the items contained in a cart can be accessed via the resource navigator at the bottom right. While it is in focus, a thin pink rectangle is drawn inside the boundary. This indicates that some operations (undo, copy, paste) apply to the resource tree. The right-most tab of the resource tree is read-only and allows internal system items to be accessed.

2.2  Object Editor

The central section of the designer displays the object currently being edited. To give it focus, press space.

2.3  Undo

Undo / Redo with Ctrl+Z and CTRL+Y. Some undo operations are unlimited (e.g. editing a prop), but some are limited by the context (you can undo resource tree changes once the navigator loses focus).

2.4  Disk

Any portion of the resources tree can be saved to disk. A cartridge is saved by simply saving the whole tree. These files have the extension .vxc.png ("Voxatron Cartridge"). Separate objects or parial sections of the resource trees are saved as .vob.png ("Voxatron Object Bank").

2.5  Editing options

3.0  Controls

3.1  Camera control

Hold 'Alt' or 'C' to use the camera tool.

Click and drag to rotate the view.

Click the second mouse button and drag to adjust viewing distance.

Hold 'Ctrl' or 'X' to pan.

3.2  Resource Navigator control

Always present at the bottom right of the screen is the navigator. This allows you to browse and manage resources like models and actors. There are five tabs; the model and objects tabs are for objects that belong to the level, and the last two (actors/items) are fixed internal objects that can not be edited.

To open a folder

double-click (or select and click the open button)

To edit an item

control-click (or select and click the edit button)

To set the cursor position in a tab

click between objects

To select an item

click on it

To select multiple

hold shift

To move selected items

click and drag, either to a cursor position

(insert) or to another item (drop at that absolute position)

To move selected items between folders


Check the descriptions on the navigator buttons to see which operations are possible. If an operation can not be performed (e.g. loading an item into a read-only folder) it will be greyed out.

Special objects such as animations are actually just folders. To see the contents of the object (e.g. animation frames), just double click

on it as you would a folder. To edit the properties of the animation, click the edit button OR click on the object's button in the crumb navigation (animation show up as orange)

Navigator operatios (move, cut, delete etc.) can be undone and redone as usual, but the undo stack is cleared when the navigator loses focus. To check if something can be undone, look at the UNDO/REDO buttons at the top right. If they apply to a navigator operation, the icon changes to include a little grid of squares to indicate this).

A history of edited items can be navigated using Alt-Left and Alt-Right, similar to a web browser.

3.3  Keyboard shortcuts

3.3.1  Common

P Play the current room

Shift-P Play, and show the timeline

Ctrl-S Save

Ctrl-L Load

Ctrl-Z Undo

Ctrl-Y Redo

Cursors Move selected object/voxels *

A,Z Move objects up & down *

[ ] Move objects in time *

Shift-R Rotate selected objects

r Rotate the cursor object

d Delete selected

Tab Hide/Show the menus on the right

Escape ~ Toggle console

Ctrl-C Copy

Ctrl-V Paste

Ctrl-A Select All

Ctrl-I Invert Section

Enter Select None

+ Edit previous/next item *

m drag to move selected objects *

g Set selection to group

shift-G Turn selected objects into a group

h Hide selected objects

H Unhide all


  * Hold shift to move faster


3.3.2  Object Editor

f Flip X

Shift-F Flip Y

r Rotate around Z

Shift-R Rotate around X

3.3.3  Room Editor

f Bring selected objects to the front

Shift-F Push selected objects to the back

3.4  Console

Press escape or ~ to hide/show the console.

4.0  Room Editor

4.1  Placing objects

An object has a position in space and a time.

To create an object instance, click on the ground or in the timeline.

4.2  Tools

Place objects

The currently selected object is placed with the center of the bottom at your cursor. You

also use shift for this, to indicate that the object should be placed

at the voxel under your cursor, rather than on top or to the side of it.

Press r to rotate the object you're about to place.

Pick up object

Selects the object under your cursor


Stamps a copy of whatever objects you last copied (Control-C)

The shift key modifier works the same way.


select objects (see below)


change which part of the room is viewed (the display only shows a 128x128x48 area)

When an object is selected, it shows up on the right in an object properties

box. If multiple object objects are selected, only one of them is shown

but changes can effect all of them at once using the "edit all" toggle button.

4.3  Selections

While using the selection tool, draw a loop to select everything inside it (or click to select whatever is at that point).

To add to a selection, hold control.

To remove from a selection, hold shift.

To select all, Control-A

To invert selection, Control-I

To select none, Enter, or click outside

Selected object/voxels can be

Deleted: backspace, or d

Moved: use the cursor keys, or A & Z for up and down

Moved fast: hold shift to move 8x speed

For room objects, press [ and ] to move in time or R to rotate.

4.4  Object Instance Properties

4.4.1  Position


appear at that particular point in the room


appear close to a player


appear far away from a player


appear at a random point in the room

4.4.2  Time

Indicates when the object should appear (providing the object's trigger is also satisfied).

4.4.3  Trigger

Specifies under what condition the object should appear. Triggers are a single microscripting statement that can be true or false. See the microscripting section for more details.

4.4.4  Warp-in

When this option is set, objects warp in from bottom to top, with a small random delay before appearing. This option is ignored for objects that appear at t=0, so if you'd like objects to warp in at the start of the room, set their t to slightly after 0.

4.4.5  Stop

This causes the timeline to pause when it reaches the flagged object, and continue only when the object is activated.

4.4.6  Facing / Heading

Sets an actor or prop's rotation. Heading refers to the direction an actor is initially moving and normally applies only to monsters.

Room objects have a set of properties that can be seen in the selected

object box on the right.

4.4.7  Eternal objects

If a pickup is flagged as eternal, it will reset after it is killed and/or collected

the next time that room is entered. Useful for things like save points that can be used

multiple times, or for rooms that should completely reset each time.

Skull toggle button

indicates an actor can die any number of times.

Coin toggle button

indicates a pickup can be collected any number of times.

4.4.8  Room Goal

Room Goal objects all need to be killed (monsters) or collected (pickups) for the room to be marked 'completed'. On completing a room, as message is shown to the player ("ROOM CLEARED"), and two things happen so that the room remains in its completed state

1. Elephant mode is switched on for that room (see an explanation of elephant mode in 'Room Properties')

2. All goal objects are marked as non-eternal.

Note that room goals are entirely optional, and are generally used for levels that allow the player to freely explore completed areas of the world.

4.4.9  Extra parameters

Room objects have some extra parameters that depend on their type.


Doors can be used to send a player from one room to another. Each door has a 'Destination' id that indicates where the player should be sent to. This is the room object id of a door in another room. If the id does not point towards an object that is a door, it is ignored.

Monster: HOW MANY

The number of monsters to spawn in a huddle. Each monster inherits the same object id.

Pickup: LIFE

How many seconds before disappearing (0 for no time limit)

4.5  Groups

Each room object belong to a group. To group objects, select them and press shift-G. To view the objects in a group, select one of the objects and press G. Groups can be referenced from object triggers to, for example, make something happen when all pickups in a group have been collected, or all monsters in a group have been killed.

4.6  Prop Properties

4.6.1  Indestructibe

When placed in the room, the prop's voxels are marked as indestructible.

4.7  Room Properties

4.7.1  Size

Maximum size is 256x256x64. If the room is more than 48 voxels high, be careful to not obscure the HUD too much with tall objects!

4.7.2  Base

Type: NONE

Empty space

Type: COL

Choose a colour to use an indestructible ground plane.

Type: VOID

No ground plane; similar to none but actors die if they fall into the void.


Room-wide liquid at a specified z level (default:56).

Extend Walls

Base types all have an 'extend walls' option. When this is checked, any walls present at the provided Z position create an invisible wall that extends to the top of the room. This can be useful for preventing the player or other actors from jumping over walls without having to visibly make them tall.

4.7.3  HUD style

Either display a standard arcade mode HUD or no HUD at all. (more HUD styles are in development)

4.7.4  Time Skipping

When this is on, the timeline will skip ahead to the next object if there are no active monsters.

4.7.5  Checkpoint

Red flag checkpoint

automatically save the game when entering the room.

Green flag checkpoint

automatically save the game when exiting the room.

4.7.6  Camera

Optionally set the camera position to a low or high angle.

After the camera has finished moving, the player is still free to manually adjust the cameras position using the camera controls (Q/E by default).

4.7.7  Atmospherics

Turn on rain or snow.

4.7.8  Elephant Mode

When elephant mode is on, the entire state of the room is recorded and then recalled when the player returns to the room. For example, any damage to the walls, spawned monsters and their positions, and any particles of snow will still be where you left them. When elephant mode is off, the room resets each time with one exception

any monsters killed will remain dead, and any pickups collected will remain collected. This exception can be switched off by using the per-object 'Eternal' option explained in Object Instance Properties.

5.0  Save Games

There are 2 ways to save the state of the world

using room checkpoints (set in room properties) or picking up a save point (e.g. the floating disk item). Each one suits a different style of saving structure, but they can also be used in combination. The player returns to the last save point after dying or by continuing a saved game from the cart menu.

5.0.1  Room Checkpoints

When the red checkpoint flag for a room is set, the world is saved each time the player enters that room. This is most useful for linear sections where the player must complete a series of rooms. When a green checkpoint flag is set, the world is saved just before exiting a room. This is useful in conjunction with room goals. If the player dies before completing a room they will be kicked back into the last room that had the green checkpoint flag set (normally the room they entered from).

5.0.2  Save Point Pickups

Pickups can have a special 'save point' flag set that indicates the world should be saved on collection. This type of save point suits worlds with sparse save points, where the player can decide at each point if they want to save or not. To allow the save point to be used multiple times, the object instance should be set to eternal collectable (the little coin icon in object instance properties).

5.1  Checkpoint Patterns

Some common ways to set up a saving scheme

5.1.1  Sparse Save Points

Create a pickup object that has SPECIAL:SAVE, and place anywhere in the level you would like the player to be able to save. Set each instance to ETERNAL_PICKUP the player should be able to save multiple times at the same point. There is an example save point pickup (the floating disk) in the default PICKUPS folder.

5.1.2  Linear Trail

If the level is a linear sequence of rooms, set all room checkpoints to red flags in order to restart any room. This is equivalent to early versions of Voxatron that had little world state persistence.

5.1.3  Room completion

A special mechanism is provided for levels that should be based on the task of clearing rooms in a non-linear order. Set all rooms to green checkpoints, tag all (or important) monsters and pickups as room goals, and set the triggers of all doors going forward to WORLD:ROOM_CLEARED.

5.1.4  Map

A central map or overworld area can be created by setting the map rooms to green flags, and not including any other save points. This means that when the player dies in a particular location they will be thrown back to the map and can choose to try again, or to enter another location.

6.0  Voxel Editor

A single voxel model in voxatron is called a 'Prop'. Props can be used to construct the basic architecture of rooms, and also combinted into sequences to form animations.

6.1  Tools

6.1.1  Build

Add voxels, or remove them with colour zero (with the white x)

6.1.2  Paint

Paint existing voxels (or remove with colour zero)

6.1.3  Dropper

Select the colour of a voxel (shortcut: right mouse button)

6.1.4  Stamp

Stampt a copy of what ever you last Control-C'ed

6.1.5  Box

Drag to get a filled box

6.1.6  Select

Select voxels (see below)

6.1.7  Fill

Fills a flat slice (hold shift), or extends whatever's under it.

For the build, stamp, box and fill tools, the voxel you're indicating is taken to be the one neighbouring the side under the cursor. So if

the cursor is on top of a voxel, whatever you draw will start there. If you want to indicate the voxel itself, hold shift. e.g. holding

shift with the build tool will cause it to act like the paint tool. Likewise, holding shift with the fill tool will fill a slice of solid

voxels rather than the empty space above/next to something.

6.2  Voxel Properties

Some voxel colours have special properties. The shades of gray at the bottom right are indestructible and float indefiniately whereever they are in the world. e.g. for inside walls that should not be destroyed.

The Magenta colour on the right of the palette is used to specify negative voxels. When negative voxels are drawn to the world, any

existing voxels are subtracted to leave empty space. This can be used for effects like opening doors or removing ground.

7.0  Custom Objects and Actors

Objects in Voxatron are represented as special folders that contain any number of components, along with a set of properties dependent on the type of object. For example, a monster folder might contain a walking animation, where the animation folder itself contains a sequence of frames (props) showing the monster's legs in different positions.

7.1  Animation

Animations can be either stand-alone objected (placed directly in a room), or used as an actor component. All actors are drawn using only animations, so most actors have at least one.

Animations should contain only one or more PROPs, interpreted as frames.

UPDATE: any frame that is also an animation is taken to be the same frame drawn at multiple angles. E.g. 2 frames = 0 degrees and 45 degrees.

7.1.1  Animation Properties


Controls how many world ticks the animation is dislayed for in world ticks. 120 == 1 second. Only relevant for looped / play once and hold animations.

Frame Length

Controls how many world ticks each frame is shown for in world ticks. Again in world ticks, so using 8 means that the animation is displayed at 15 frames per second (120 / 8).


The anchor controls where the animation is drawn with respect to its xyz coordinates in the world. Monsters' coordinates are taken to be bottom center, and so you normally want to also use this for monsters' animations. Bullets are taken to be at the center of the collision box, in which case animations should also be centered (center center).


Further positioning with respect to the anchor. These values are in the same coordinate space as the editor so if you draw a character facing the camera, then using X = 5 will shift the animation 5 voxels to the right (the character's left), and Y = 5 will shift it infront (towards the camera). Checking 'Rotate With Actor' will cause X & Y to be rotated according to the host actor's current facing angle.

Play Style

Controls how to advance through the frames. The only tricky one is 'Actor Movement'. This causes the frame to advance when the actor moves one voxel in any direction. So if you draw a walk cycle with feet that move one voxel at a time, they should roughly line up with the ground (avoiding a moonwalking effect).

Paint Mode

Paint Solid only draws voxels on existing world voxels; Paint Empty only draws voxels in empty space (never clobbering existing voxels).

Draw in Screen Space

Ignores the camera position (useful for titles, scrolly tricks)

The rest of the properties

Hitbox size, Gravity, Locking and Interaction are ignored for animations that are part of a monster. They are used for animations indpendently spawned into the world and have the same meaning as the corresponding monster properties. (i.e. they become physical objects similar to monsters).

7.2  Actors

7.2.1  Actor Properties

Some properties are shared between monsters, players, pickups and sometimes animations.


are in voxels. This defines the collision box and can be completely different from the animation size. Make sure the size of the monster roughly matches its appearance. It also helps to give the width of the animation and the width of the monster the same parity (i.e. both odd or both even).


1.0 is roughly the same as the robot.


Number of hitpoints.


Any damage inflicted on the monster is multiplied by this value. i.e. 1.0 means normal damage, 0.5 means 50% damage, and 0.0 means the monster is immortal.


Determines the monster's weight / floating level in water. * not yet implemented! Just leave at 1.0


Points scored when the monster is killed. * fixed in 0.2.8!


Which team the monster is on. Any bullets emitted from the monster will inherit this team value, determining which other actors it can hurt. 0 means no team and will hurt any other actor. The Robot has a default team number of -2.


Lock the position (X,Y) or elevation (Z) of the monster.


Usually you want to check the first 3, so that the object has collidable sides and can be stood on. Check hoistable & throwable if you want to be able to pick up an object (by pressing shoot infront of it) and throw it (by pressing shoot while carrying).

7.2.2  Monsters

In addition to common actor properties, a monster also has


1.0 is roughly the same as the robot. You probably want to turn speed down for most monsters.


How many frames on average between jumps. The world is calculated at 120 frames per second, so a value of 240 means jump about once every 2 seconds. 0 means never, 1 means constantly bouncing.


How fast the monster can turn in rps; i.e. 1.0 means one full rotation in one second.


How the monster turns and moves


Do nothing.


Randomly wander around without reacting to the player's location.


Turn towards the target (player) and accelerate towards them. The stop to turn parameter means that the monster will only accelerate when facing roughly in the desired direction. Leaving it unchecked results in a more loopy movement path. If X-Ray Vision is not checked, the monster will revert to a wandering behaviour after losing sight of the player for several seconds.


Walk straight until hitting something, and then turn by the specified angle. Angles are in full rotations, so 0.5 means turn 180 degrees.


If the monster hits wall, bite a chunk out of it about once per second.


Explode into separate voxels on death, that optionally settle on the ground.


Avoid walking too close to other monsters. If this is unchecked, monsters tend to bunch up into tight packs (like the demo pig)


Used in conjunction with the NOMON trigger. e.g. if you're making a crate that doesn't need to be killed in order to trigger a door, you would leave this unchecked.


Choose if the player is hurt when standing on top of and/or touches the side of a monster.


The direction in which the monster is accelerating (heading) and the direction that the monster is visibly rotated (facing) are two separate values. This means that you can have for example, a monster that patrols left and right, but is always facing the player.


Remain facing the direction that the actor was placed


Always turn to face the player


Turn to match the heading


Turn a given amount each frame

Facing Control's turn speed is given in rotations per second.

7.2.3  Pickups

Pickup definitions are similar to regular monsters. They can have the same behaviours as a monster.

The main difference is that when a pickup comes in contact with a player, it is collected.

7.2.4  Internal Pickups

Access to internal pickups is given by using the SPECIAL

attribute. These pickups act as if the player had collected one of the corresponding pickup type (health, sword, freeze, etc.)

7.2.5  Pickups and Teams

Like monsters, pickups have a team number. This can be used to determine which bullets are able to collide or hurt with the pickup, but also which players can collect it. Only players on the same team as a pickup may collect it. If the pickup's team is 0, any player can collect it. The Robot has a default team number of 1.

7.3  Player

Legacy player

7.4  Bullet

This will be an entirely self-contained object that could be spawned by other monsters or emitters, and could be stored anywhere in the navigator. But for convenience, it's nice to store it inside the monster's attack modifier.

The steps for creating a bullet are very similar to creating the initial monster. Navigate to the attack modifier's folder and create a new object (next to the attacking animation). Set type to bullet, open the bullet's folder, make an animation, and draw some frames. The result looks like this


leave the bullet's animation's anchor to the default of 'center center'. This means that you need to draw the bullet hovering in the center of each frame, rather than on the ground as with monsters. You can test that bullets animations line up with their collision hitboxes by checking to see where they leave holes in the walls. If the hole seems to be too high or too low, either the animation is not centered, or the anchor is wrong.

The properties of the animation are similar to before, except that I've used 'Loop' in stead of 'Actor Movement'. Because the animation is hosted by the bullet, the physical properties of the animation (size, gravity, interaction, locking) are ignored. [In future versions the interface will let you know about this automatically.]

Now to the bullet's definition

Width, Length and Height define the size of the bullet's hitbox. For small bullets I usually just leave this to 0,0,0 which means the point at the center of the bullet needs to be inside another actor's hitbox for it to collide.


1.0 means the same as the robot. 0.0 means travel flat.


How long the bullet should stay alive, or zero for forever. Try 480 (4 seconds) for a fast bullet. You should set some value less than 1200 for this to avoid slow bullets accumulating to a very large number, unless you're very certain the bullet will die at some point. If you're using a positive gravity value and no duration, make sure Collide With Ground is set.

Collide With/ Hurt Same Team

The team index is taken from the host actor that emitted it. A team value of 0 means no team, and never counts as the same team.


lock position on each axis.


bullet doesn't die until all damage is spend

monster can absorb extra damage if mortality is not 1.0

7.5  Emitter

Emitters are used to spawn any kind of object (including other emitters) into the world. They can be stand-alone independent world objects (in the way that animations can be), but can also be contained in monsters/modifiers to implement attacks.

It is currently possible to emit monsters, animations, bullets and other emitters. Don't try to emit the emitting emitter, because you will make Voxatron cry.

7.5.1  Source ID

The thing you want to emit. Find out the id by editing it in a different tab (will add an easier way in the future).

7.5.2  Bursts

How many bursts to emit. 0 for continuous.

7.5.3  Burst Frequency

How many world ticks inbetween each burst (by time), or how many voxels the host actor need to travel for one burst (by movement). The first burst is emitted at the moment the modifier is activated.

7.5.4  Spawn Position

Where to spawn relative to the emitter (or host actor's) position. Same meanings as animation offsets; Y = 10 will position the spawned object 10 voxels infront of the emitter/actor.

7.5.5  Velocity

Same again, but for velocity of the burst. This is added to any other velocities generated by the pattern (e.g. so you can have a ring that is expanding, but the whole ring is also moving)

7.5.6  Pattern


Emit a single item.


Emit a circle of items moving apart at speed of 'Magnitude', offset by Angle, and increasing the offset by DAngle each burst (to create spirals).


Emit an arc of items. Similar to ring, except spread controls how much of the ring to cover. 0.25 means a quarter-circle.

7.6  Door


7.6.2  DOOR TYPE



Spawn Point





7.6.6  FLAGS


Level Goal

Orient Traveller

Scifi Warp

7.7  Modifiers

A modifier is an actor definition that that replaces part or all of the host actor's definition when it is active. For example, a monster folder can contain another monster with the modifier option checked. The modifier can then override selected values. For example, a boss might speed up and change movement behaviour when its life is low.

Animations placed in a modifier's folder with an activation trigger of HOST:ACTIVE can be used to replace animations with the same activation group number. When the boss is low on life in the above example, this might be to make the body change colour, or add visible damage.

7.8  Property Values

Most values in object definitions are literal values. e.g. 0.2 or 45. If you instead want a random number within a certain range, use "RAND x y".

7.9  Activation Controller

Each actor component (animation, modifier, or emitter) has an activation controller that determines when the component should be activated or deactivated. For example, an animation of a player swimming should only replace the generic walking animation when that actor is swimming. In that case, the activation controller would need a trigger HOST:M-STATE:SWIMMING and for the animation to have the same group and priority than the walking animation.

Activation controllers have the following properties:

7.9.1  Duration

How long the modifier remains active for in world ticks. 0 means forever.

7.9.2  Next

Which modifier to activate when this one expires (0 for none)

7.9.3  Priority and Group

If group number is set, then only one modifier in each group can be active, selected by highest priority.

7.9.4  Delay

How long to wait before the modifier can be activated again (taken from time of expirey, not time of activation).

7.9.5  Audio Trigger

This audio is played when the activation controller is reset.

7.9.6  Reset on Activation

Reset the state of the activation controller when it is activated; i.e. the condition changes from not true to true.

7.9.7  Reset on Continue

Reset the state of the activation controller when it times out but is immediately reactivated because the condition remains true.

7.9.8  Trigger

A single microscripting statement that needs to be true for the component to be activated.

8.0  Microscripting

Microscripting in Voxatron provides basic control over custom actor behaviours and event triggering. At its core is the concept of a statement; a logical assertion that can be true or false. Statements in Voxatron are designed to express common situations in a Voxatron game state. For example:

"all monsters have died", or "a player is close to this actor".

These statements are used in sequence to build more complex logical machines (Microscripts), or as components of activation controllers and object instance triggers.

8.1  Statements

A statement has 2 main parts

a selector, an event. The selector picks out which objects to consider ("All monsters"), and the event part checks to see if something is true about each one ("has died").

Each statement can be either true or false, depending what's going on in the game world. The first part of the statement ("NO / ANY / ALL") specifies how many of the selected objects should pass the event test for the whole statement to be true.

8.2  Selectors

Each statement has a selector that picks out the actor or set of actors you want to talk about. For example, if you want to make something happen when all apples in a room are collected, the selector part of the statement will pick out the set of apples.

8.2.1  Common Selectors

The following selectors are available in any context.


The set of players.


All actors that have the 'COUNT AS MONSTER' flag set.


All players, monsters and pickups.


Picks out all actors that have object id n. Normally there is only one of them, so use this to refer to a particular actor. If the 'How Many' parameter is set to more than one when spawning a monster, all spawned monsters have the same object id.


All actors that are instances of definition n.


All actors that are in group n.


All friends of this actor. (Those that have either a TEAM of 0, or the same team)


picks out all actors that are not friends.


all actors that do not have reset_after_collect flag set. This is can be used to implement the legacy trigger 'NOITEM'.


all actors that do not have reset after_killed flag set.


all actors that have custom flag 0 set.


all actors that have custom flag 1 set.

8.2.2  Activation Controller Selectors

When activating actor compoments, the following additional selectors are available.


The host is the actor the current component belongs to. For example, a player animation that is triggered by the player jumping might use host.position.in_air.


This returns the parent activation controller. The attributes accessible (active, time) refer to the controller's state itself rather than the actor or parent component.

8.2.3  Object Trigger Selectors

When triggering objects in a room, TIME also appears in the selector menu. It doesn't function as a selector, but is here for convenience as it is very common.


The object will be triggered when time is greater that the object's time. Note that *all* object triggers also depend require this to be true.

8.3  Events

The events that can be tested for a particular actor depend on the type of actor.

8.3.1  Common Actor Events

S-State (Super State)

Actor has the specified super-state. DORMANT means the object is waiting to be activated. ACTIVE means the object is currently manifested as an actor. DIED and COLLECTED means that the actor has died or collected respecively. Pickups that disappear because of a time limit have the DIED superstate. When more than one actor is spawned from the same object, the object has a state DIED and COLLECTED only when all spawned actors have died or have been collected.

M-State (Momentary State)

Actor is currently simming, in the air, standing, has just been hurt etc.


Collide with another actor, on a specified side or set of sides. If the collide event is used in host, it means collide with anything.


Actor speed in voxels per world frame. As the world runs at 120 frames per second, a speed of 1.0 indicates the actor is moving at 120 voxels per second.


Actor life.


Actor's time since spawn.


True every n world frames on average. A trigger set at random(240) will fire about once every 2 seconds on average.


True every n world frames, starting from the actor's spawn time. A periodic event first occurs at time 0 when the actor is spawned (rather than at n frames).


The distance between two actors. The distance is taken to be the shortest straight line between the two actors, rather than the distance between their midpoints. So a distance of zero means that the two actors are touching, and a negative value means that they are overlapping.


There exists a visible line of sight between two actors. Vision is blocked by both map voxels and actors. The result of this call is cached and only updates at 4 times a second (every 30 frames) for efficiency.

Legacy applies to players. Normally used to trigger animations.


Host is shooting with left hand.


Host is shooting with right hand.


Host is shooting with either hand.


Host is holding a gun


Host is swinging a sword / handheld weapon.


Host is close to player (TRIG:CLOSE)

9.0  To do

tiny value functions

inventory items

newer monster properties

team logic


bbs useage