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 |
Ctrl-C/Ctrl->X/Ctrl-V |
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 |
Stamp |
Stamps a copy of whatever objects you last copied (Control-C) |
The shift key modifier works the same way. |
Select |
select objects (see below) |
Pan |
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 |
XYZ |
appear at that particular point in the room |
CLOSE |
appear close to a player |
FAR |
appear far away from a player |
RANDOM |
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. |
Door: DESTINATION |
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. |
Type: LIQUID |
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 |
Duration |
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). |
Anchor |
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). |
Offset |
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. |
WIDTH, LENGTH and HEIGHT |
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). |
GRAVITY |
1.0 is roughly the same as the robot. |
LIFE |
Number of hitpoints. |
MORTALITY |
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. |
DENSITY |
Determines the monster's weight / floating level in water. * not yet implemented! Just leave at 1.0 |
POINTS |
Points scored when the monster is killed. * fixed in 0.2.8! |
TEAM |
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 X, Y, Z |
Lock the position (X,Y) or elevation (Z) of the monster. |
INTERACTION |
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 |
SPEED, JUMP HEIGHT |
1.0 is roughly the same as the robot. You probably want to turn speed down for most monsters. |
JUMP FREQ |
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. |
TURN SPEED |
How fast the monster can turn in rps; i.e. 1.0 means one full rotation in one second. |
MOVE STYLE |
How the monster turns and moves |
NONE |
Do nothing. |
WANDER |
Randomly wander around without reacting to the player's location. |
CHASE PLAYER |
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. |
PATROL |
Walk straight until hitting something, and then turn by the specified angle. Angles are in full rotations, so 0.5 means turn 180 degrees. |
EAT WALLS |
If the monster hits wall, bite a chunk out of it about once per second. |
ATOMIZE, LEAVE DEBRIS |
Explode into separate voxels on death, that optionally settle on the ground. |
SPREAD OUT |
Avoid walking too close to other monsters. If this is unchecked, monsters tend to bunch up into tight packs (like the demo pig) |
COUNTER AS MONSTER |
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. |
HURT PLAYER ON CONTACT |
Choose if the player is hurt when standing on top of and/or touches the side of a monster. |
FACING CONTROL |
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. |
NONE |
Remain facing the direction that the actor was placed |
FACE PLAYER |
Always turn to face the player |
FACE DIR |
Turn to match the heading |
TURN |
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 |
Note |
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. |
Gravity |
1.0 means the same as the robot. 0.0 means travel flat. |
Duration |
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 |
lock position on each axis. |
Multi-hit |
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 |
Single |
Emit a single item. |
Ring |
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). |
Spread |
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.1  WIDTH, HEIGHT, DEPTH |
7.6.2  DOOR TYPE |
Collectable |
Spawn Point |
Immediate |
7.6.3  EXIT DEPTH |
7.6.4  ENTRY DEPTH |
7.6.5  HIDE DEPTH |
7.6.6  FLAGS |
Open |
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. |
PLAYER |
The set of players. |
MONSTER |
All actors that have the 'COUNT AS MONSTER' flag set. |
ACTOR |
All players, monsters and pickups. |
OBJ_ID(n) |
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. |
DEF_ID(n) |
All actors that are instances of definition n. |
GROUP_ID(n) |
All actors that are in group n. |
SPECIAL:FRIEND (todo) |
All friends of this actor. (Those that have either a TEAM of 0, or the same team) |
SPECIAL:ENEMY |
picks out all actors that are not friends. |
SPECIAL:C1ITEM |
all actors that do not have reset_after_collect flag set. This is can be used to implement the legacy trigger 'NOITEM'. |
SPECIAL:D1ITEM |
all actors that do not have reset after_killed flag set. |
SPECIAL:CFLAG0 |
all actors that have custom flag 0 set. |
SPECIAL:CFLAG1 |
all actors that have custom flag 1 set. |
8.2.2  Activation Controller Selectors |
When activating actor compoments, the following additional selectors are available. |
HOST |
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. |
PARENT |
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. |
TIME |
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 |
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. |
Speed |
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. |
LIFE |
Actor life. |
TIME |
Actor's time since spawn. |
RANDOM(n) |
True every n world frames on average. A trigger set at random(240) will fire about once every 2 seconds on average. |
PERIODIC(n) |
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). |
DISTANCE |
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. |
VISIBLE |
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. |
LEGACY:SHOOT-L |
Host is shooting with left hand. |
LEGACY:SHOOT-R |
Host is shooting with right hand. |
LEGACY:SHOOT-ANY |
Host is shooting with either hand. |
LEGACY:HAVE GUN |
Host is holding a gun |
LEGACY:SWIPE |
Host is swinging a sword / handheld weapon. |
LEGACY:CLOSE |
Host is close to player (TRIG:CLOSE) |
9.0  To do |
tiny value functions |
inventory items |
newer monster properties |
team logic |
audio |
bbs useage |