Voxatron Designer User Manual

Version 0.3.5b

Author: zep

www.voxatron.com


:: Contents

1.0  What is Voxatron?

2.0  Concepts

2.1  Voxel

2.2  Cartridges

2.3  Object Definitions and Resource Tree

2.4  Props and Animations

2.5  Actors

2.6  Rooms and Object Instances

2.7  Object IDs

3.0  Designer Overview

3.1  Object Editor

3.2  Navigator

3.3  Undo

3.4  Disk Operations

3.5  Running a Cartridge

4.0  Controls

4.1  Camera Control

4.2  Resource Navigator Control

4.3  Keyboard shortcuts

4.4  Number Fields

5.0  Room Editor

5.1  Placing objects

5.2  Tools

5.3  Selections

5.4  Object Instance Properties

5.5  Groups

5.6  Prop Properties

5.7  Room Properties

6.0  Prop Editor

6.1  Tools

6.2  Indicating Voxel Position

6.3  Voxel Properties

7.0  Custom Objects

7.1  Animation

7.2  Actor

7.3  Monsters

7.4  Pickups

7.5  Inventory Items

7.6  Players

7.7  Bullets

7.8  Emitter

7.9  Door

8.0  Actor Component Control

8.1  Modifiers

8.2  Property Value Functions

8.3  Activation Controller

9.0  Game Saving

9.1  Saving Methods

10.0  Microscripting

10.1  Statements

10.2  Selectors

10.3  Events

11.0  Lua Scripting API

Voxatron Designer User Manual
1.0  What is Voxatron?

Voxatron is a fantasy console for making and playing volumetric games and other computer programs. It has an unusual display format: a 128x128x64 block of tiny holographic cubes that can light up in patterns to form scenery, characters, text and any other visible elements. The display can be visualised as an animated diorama placed on a table and viewed from any angle. Such displays already exist in the real world but are still very rare, so Voxatron also provides a simulated volumetric display that can be viewed on standard 2D monitors.


2.0  Concepts


2.1  Voxel

A voxel is the 3D version of a pixel. Anything that can be said about a pixel in 2D can be said about a voxel in 3D. For example, to the extent that pixels can be thought of as little coloured squares that make up a larger image, voxels can be thought of as little coloured cubes. They are more precisely described as points without any geometric properties beyond their position in a regular grid, but Voxatron's default renderer displays them as cubes.


2.2  Cartridges

A Voxatron cartridge typically contains one playable game similar to a real-world console cartridge. Each cartridge is stored as a standard png image file that can be shared with other users.


2.3  Object Definitions and Resource Tree

Anything that might appear in the game world is an object. Objects include actors, pickups, rooms, music, sound and scripts. Object definitions are stored in a browsable tree (similar to a file system) referred to as the 'Resource Tree'.


2.4  Props and Animations

Props are the most basic type of object and consist of a single voxel model. An animation is a collection of frames (each one a prop) stored in a single folder along with additional properties such as how fast the animation should be played.


2.5  Actors

Objects that can move around in the game world and interact with each other are called actors. The most common actors are monsters, players and pickups. Like animations, they are also represented as a folder of components including animations, emitters -- you can double click on an actor in the resource navigator to see what's inside.


2.6  Rooms and Object Instances

A room is a collection of props (typically arranged into scenery), actors and other object instances, each with their own XYZ position along with rules about when they should appear. Voxatron is a room-orientated engine; only one room is shown or simulated at one time.


2.7  Object IDs

Every object definition and every object instance each have a global integer id that is unique to the whole cartridge. This allows objects to refer to each other across rooms. For example, a door in one room might open when a switch in another room has been flipped, and would check this using the switch's instance id.

It is important to understand the difference between definition ids and instance id. They are two separate indexing schemes:

- The definition id picks out a single object definition in the resource tree.

- The instance id picks out a single instance of the object in the game world.

For example, there might be a single flower model in the resource tree (with it's own definition id), but then many instances of that flower placed in a room, where each instance has its own instance id.


3.0  Designer Overview


3.1  Object Editor

The central section of the designer interface displays the object currently being edited. At the top right you can find the name of the object and its definition id number. (The name can be anything you like, and does not need to be unique unless you are using it to pick out object definition by name in a Lua script.)


3.2  Navigator

Object definitions are accessed via the resource navigator at the bottom right. While it is in focus, a thin pink border is shown to indicate that some operations (undo, copy, paste) apply to the resource tree. The navigator is used both to select which object to edit, and also which object to place in a room.


3.3  Undo

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


3.4  Disk Operations

To save or load a cartridge, use the buttons at the very top right or CTRL-S to quick-save / CTRL-L to load. A complete cartridge is simply the whole resource tree saved as a single .png, but it is also possible to save any branch of the tree separately using 'Load Item' and 'Save Item' on the resource navigator tool bar. 'Load Item' can also import several other formats into the tree: .p8 PICO-8 cartridges, regular 2d .png files and .qb Qubicle Constructor scenes.


3.5  Running a Cartridge

Press the play button or press CTRL-R to run the cartridge from the most recently viewed room. You can then exit back to the editor from the in-game menu.


4.0  Controls


4.1  Camera Control

Hold 'Alt', 'C' or middle mouse button to use the camera tool.

Click and drag to rotate the view.

Click and drag the second mouse button (or use scroll wheel) to adjust viewing distance.

Hold 'Ctrl' or 'X' to pan.

If you get lost, use the camera reset button at the bottom left.


4.2  Resource Navigator Control

Always present at the bottom right of the screen is the navigator. This allows you to browse and organise object definitions as if they were files on a disk. There are five tabs; the room and objects tabs are for objects that belong to the cartridge, and the last one ('Internal') is for browsing built-in objects that can not be edited. The Metadata tab is for addition additional information about the cartridge [in development -- but you could try drawing a 60x32 label for later].

  • 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 while clicking or draging
  • 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: Copy (Ctrl-C) or cut (Ctrl-X) the item, move into the desired folder and then paste (Ctrl-V). Alternatively, drag the item or selected items into a folder as you would with a typical file browser.
  • 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 is grayed out.

    Compound objects such as animations are actually just folders. To see the contents of the object (e.g. animation frames), 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.

    Navigator operations (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. [experimental]


    4.3  Keyboard shortcuts


    4.3.1  Common

    P Play the current room

    Shift-P Play, and show the timeline and other debugging information

    Ctrl-S Save cartridge

    Ctrl-L Load cartridge

    Ctrl-Z Undo

    Ctrl-Y Redo

    Cursors Move selected object/voxels in X, Y*

    A,Z Move selected objects in Z (up and down) *

    [ ] Move selected 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-X Cut

    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 *

     

      * Hold shift to move faster

     


    4.3.2  Object Editor

    f Flip X

    Shift-F Flip Y

    r Rotate around Z

    Shift-R Rotate around X


    4.3.3  Room Editor

    f Bring selected objects to the front

    Shift-F Push selected objects to the back

    g Set selection to group

    shift-G Turn selected objects into a group

    h Hide selected objects

    H Unhide all


    4.4  Number Fields

    Numbers can be edited either by clicking once to type in the desired value, or by click and dragging up and down.


    5.0  Room Editor

    A new room can be created by opening the 'Rooms' tab in the navigator, and selecting 'New Room'. Use the Objects tabs to select which objects to place in the room as instances.


    5.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. In the first case, the currently selected time is used for that object (click at the bottom of the timeline to set the time).

    If a previous object is selected, the properties of that object will be used as defaults for the newly placed object. Press Enter to clear the current selection.


    5.2  Tools

    Room editing tools appear at the top center of Designer while viewing a room.

    Place objects

    The currently selected object is placed with the center of the bottom at your cursor. Hold LEFT SHIFT to indicate that the object should instead 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 definition under the 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 next section).

    Pan

    Change which part of the room is viewed (the display only shows a 128x128x64 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.


    5.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
  • Move: use the cursor keys, or A & Z for up and down
  • Move fast: hold shift to move 8x speed
  • For room objects, press [ and ] to move in time or Shift-R to rotate.


    5.4  Object Instance Properties

    Objects have a set of per-instance properties that can be edited in the selected object box on the right.

    To simultanrously edit properties of all selected objects rather than just one, use the 'Edit All Selected' toggle button at the top right of the object properties box.


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


    5.4.2  Time

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


    5.4.3  Trigger

    Specifies some condition that must be true for the object to spawn. Triggers are a single microscripting statement that can be true or false. An object spawns when the condition is true and the current time is greater or equal to the object's time. See the microscripting section for more details.


    5.4.4  Warp-in

    When this option is set, objects warp in from bottom to top instead of instantly appearing.


    5.4.5  Stop

    This causes the timeline time to pause when it reaches the flagged object, and continue only when the object has been spawned. Press shift-P to view the timeline while testing a room to see what it happening.


    5.4.6  Facing / Heading

    The small arrows sets an actor or prop's initial orientation. "Heading" refers to the direction an actor is initially moving and normally applies only to monsters.


    5.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 setting up 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.


    5.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, a message is shown to the player ("ROOM CLEARED"), and all goal objects are marked as non-eternal.

    Note that use of room goals are entirely optional but provided as a convenient mechanism for implementing game progress schemes.


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

    Script: P

    A parameter passed to the script.


    5.5  Groups

    Each object instance belongs to a group (and only one 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 to extend the selection to all objects in that group. 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.


    5.6  Prop Properties


    5.6.1  Indestructible

    When placed in the room, the prop's voxels are marked as indestructible. This means that they can hover in mid-air and will never be destroyed by bullets.


    5.7  Room Properties


    5.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!


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

    Type: SHAPE

    Room is an arbitrary shape defined by which voxels are non-zero at the ground level.

    Extend Walls

    Base types all have an 'extend walls' Z option. When this is checked, any walls present at the specified 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 visually make them tall.


    5.7.3  HUD Visible

    Toggle to indicate weather the HUD should be visible for that room.


    5.7.4  Time Skipping

    When this is on, the timeline will skip ahead to the next object if there are no active monsters. This is useful if you want to organise monster spawning into waves, but don't want the player to have to wait for the next wave to start.


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


    5.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 (O/P or d-pad by default).


    5.7.7  Atmospherics

    Turn on rain or snow.


    5.7.8  Elephant Mode and World Persistence

    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.


    6.0  Prop Editor

    Each prop is a single voxel model -- a 3 dimensional grid of colour values. Props can be placed directly in rooms as static scenery, and also collected into sequences to form animations. To create a new prop, select 'New Prop' from the 'New Item' menu in the navigator. You must be in one of the objects tabs as props can not be added to the Rooms tab.


    6.1  Tools


    6.1.1  Build

    Add voxels, or remove them with colour zero (marked with a 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

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


    6.2  Indicating Voxel Position

    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 draw over the voxel under the cursor, hold shift. Doing so produces bahviour similar to 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.3  Voxel Properties

    Some voxel colours have special properties. The shades of gray at the bottom right are indestructible and float indefiniately wherever they are in the world. e.g. for inside walls that should not be destroyed. You can alternatively set a whole prop to be indestructible with the per-prop 'Indestructible' checkbox.

    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 sculpting negative spaces out of the ground. [experimental -- not well supported by tools!]


    7.0  Custom Objects

    Compound objects such as actors are represented as special folders that contain any number of components along with a set of properties for that 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. The object definition's folder can be opened like a usual folder, by double clicking on it.

    To create a custom object, click 'New Object' and then select a type.


    7.1  Animation

    Animations can be either stand-alone objects (placed directly in a room -- e.g. a blade of grass), or used as an actor component (e.g. a monster's legs). All actors are drawn using only animations, so visible actors have at least one. Animations are usually a folder of props, where each prop is one frame.


    7.1.1  Animation Properties

    Duration

    Controls how many world ticks the animation is displayed for in world ticks. 120 == 1 second.

    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 positions are taken to be at the center of the collision box, in which case animations should also be centered (center center).

    Offset

    Further positioning relative 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). Z = 1 means down one voxel. 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 n voxels 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 and actor 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.1.2  Multi-Angle Animations

    A voxel model can only be drawn facing one of four anges (0, 90, 180 and 270 degrees). In cases where actors or bullets need to visually face more than 4 directions, it is possible to specify sets of frames to be drawn at different angles.

    Instead of creating a prop for each frame, using another animation indicates that the contents of that animation is the same frame drawn at multiple angles. The first prop in the sub-animation is at 0 degrees as usual, and then spread evently between 0 and 90 degrees after than. For example, 2 frames should show the animation drawn at 0 and 45 degrees, while 3 frames would indicate 0, 30 and 60 degrees and so on.


    7.2  Actor

    Actors include monsters, players and pickups. They can collide with each other and optionally stand on or push one another.


    7.2.1  Actor Properties

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

    WIDTH, LENGTH and HEIGHT

    In voxels. This defines the collision box and can be completely different from the animation size. Normally the size of the monster should roughly matches its appearance. It is best to give the width of the animation and the width of the monster the same parity (i.e. both odd or both even). Same for length.

    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

    Normally 1.0. Determines the actor's weight (weight = w * l * h * density). If you want an actor to be easily pushed around, try a lower value. If you want a bullets or small actors to push other actors around a lot, try something like 10.0.

    POINTS

    Points scored when the monster is killed.

    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. Internal monster definitions use team -1. Put monsters on different teams if you want them to hurt each other!

    LOCK X, Y, Z

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

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

    COUNT AS MONSTER (LEGACY)

    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.

    ATTACK

    Choose if the player (or any actor of another team) 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.4  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.4.1  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.4.2  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.5  Inventory Items

    Inventory items


    7.5.1  Properties

    Collect Group

    Collect Priority

    Weild Group

    Weild Priority

    Max Ammo

    Add Ammo

    Use Ammo

    Use Delay

    Weild Delay

    Flags

    Weild on Collect

    Deweild on 0 Ammo

    Auto-Reweild

    Reject Collection

    Use on Request

    Button


    7.6  Players

    Players are actors that can be controlled by human players and that can travel between rooms.

    The custom control scheme is intended to be only as flexible as required and no more, so that controls are generally standardized across cartridges. For example, it isn't possible to swap jump and shoot buttons at this level.

    Controls

    Move

    The player should move primarily in XY (most common) XZ, or be controlled like a car (turn and accelerate).

    Shoot

    Which buttons can be used to shoot. Facing buttons are taken to mean shoot when they are fully extended. i.e. it is possible to face in a particular direction without shooting e.g. when ASDW+mouse style input is used, the player can look around without shooting.

    Jump

    By default, player jumps when either A Button or either of the Triggers is pressed.

    Facing

    The facing buttons are used to control the direction the player is facing.

    Hoist / Throw

    Allow the player to hoist and throw hoistable/throwable actors. When X button is enabled for this as well as shoot, the shooting action is blocked when a hoist or throw is performed. In this case it is impossible for the player to shoot while carrying a throwable object on their head.

    Auto-Thrust

    The player should accelerate forward as if they were pushing the directional movement or acceleration button.

    Extra Controls

    Buttons can also be bound to the USE_ITEM event allowing inventory items to be triggered by any button.

    Debug Placement

    When playing from Designer, a special player spawning rule is used to allow testing arbitrary rooms without needing to start from the beginning each time. If there are no players in the room, and there is at least one door, the first player object found in the resource tree is placed at the first door found in the room.

    When playing from the starting room (the first room in the ROOMS folder), this rule is not applied so that the cartridge can be play-tested as if it were played from the BBS CARTS menu.


    7.7  Bullets

    Bullets are similar to actors but are more lightweight. They can collide with actors but not each other, and have fewer properties. Regular actors can normally be used in place of bullets, but if many (more than a few hundred) bullets are likely to be spawned at the same time, using the bullet type is recommended.


    7.7.1  Bullet Properties

    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 Sender

    When this is set, the bullet can collide with the actor that emitted it. It's normally best to leave this off at least for the start of a bullets life so that it doesn't immediately collide with the actor (unless that's what you want to do!)

    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, in which case the bullet will collide with any actor.

    Leave Hole In Ground

    When the bullet hits the ground, a small spherical crater is created. Control the size with crater_radius.

    Multi-hit

    If a bullet has multi-hit enabled, it does not necessarily die after colliding with an actor. Instead, the bullet is depleted by the ammount of attack damage it inflicted on the actor. If the actor dies and the bullet still has remaining attack damage, it will continue moving without changing velocity. For example, if a multi-hit bullet has attack damage 10 then it can cut through 20 life:0.5 actors before expiring.

    Lock

    Lock position on each axis.


    7.8  Emitter

    Emitters are used to spawn any kind of object into the game world. They can be stand-alone independent world objects or used as actor components to implement attacks or decorative effects.

    It is currently possible to emit monsters, pickups, animations, bullets and other emitters.

    Note that emitters that are used as actor components reset only when their activation controller resets.

    Source ID

    The thing you want to emit. If 0, the first item found in the emitter's folder will be emitted.

    Bursts

    How many bursts to emit. 0 for continuous.

    Burst Frequency

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

    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.

    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)

    Pattern

    The pattern describes what shape a single burst should be.

    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.8.1  Adding Random Noise

    If the burst shape should have some randomness to it, use something like "rand -0.2 0.2" in the dx, dy and dz fields.


    7.9  Door

    Doors are special actors that can transport player actors to other doors on contact. The destination door is specified in the door instance's properties. A 2-way door is actually 2 doors pointing at each other. Because it is a common pattern, a "LINK DOOR" button will sometimes pop up in the editor to link the selected door with the last selected door in another room, and vice versa.

    Note: earlier versions of Voxatron included doors that send players to rooms rather than doors. It is no longer possible to do this, and although legacy support is provided foor door-to-room doors, it is recommended to update them to modern door-to-door doors.


    7.9.1  Door Types

    Pocket

    The most common type of door: these are entered from the side and contain a pocket of special empty space that can extend beyond the visible side of the room. This creates an implied tunnel effect; there is a pause between a continuously moving player exiting one room and entering the next.

    The length of a door is taken to be how 'deep' the pocket goes. For example, a length of 20 means that the player will have to travel 20 voxels inside the door before being transported.

    Width and height specify the width and height of the pocket. They should normally roughly match the visual size of the door's opening. Check out the example doors in the default library for examples.

    Collectable

    Collectable doors behave like a regular pickup. They normaly point towards a spawn point door.

    Spawn Point

    Use to receive players from any type of door, but can never send players anywhere.

    Vertical Holes

    [Not implemented yet. Use collectable doors instead.]


    7.9.2  Flags

    Open

    Player can pass through to the destination door.

    Level Goal

    Set the cartridge to completed on entry.

    Orient Traveller

    Set the player to face the same direction as the door when entering.

    Scifi Warp

    (For pickups) do a rainbow warp effect on the player before being transported.

    Trundle

    Automatically push any players out. Useful for situations where you don't want to the player to lurk inside or door, or door entrances and exits directions do not match (e.g. North exit -> West entrance).


    8.0  Actor Component Control


    8.1  Modifiers

    A modifier is an actor definition that replaces part or all of the host actor's definition when it is active. For example, a boss might speed up and change movement behaviour when it is low on life. Or a door might be set to 'unlocked' after a key has been collected in another room.

    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 a boss monster is low on life in the above example, this might be to make the body change colour, or add visible damage.


    8.2  Property Value Functions

    Most values in object definitions are constant values. e.g. 0.2 or 45. For convenience, a few common functions are provided to give variable results based on the age of the actor or component. These can be typed into any actor property field in the form "func x y [z]".

    rand x y

    A random number between x and y

    srand x y

    A random number between x and y, but only randomized once on the actor's creation. E.g. if you want to give a monster a random speed for the lifetime of the monster.

    lerp x y z

    Linear interpolation between x and y over z seconds

    serp x y z

    Sigmoidal interpolation between x and y over z seconds

    sin/cos x y z

    x + sin(z) * y // z = 1.0 means PI*2 per second


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

    To debug an actor's activation controller state changes, play the cartidge in debug mode (shift-P) and use [ and ] to switch between actors.

    Activation controllers have the following properties:


    8.3.1  Trigger

    A single microscripting statement that triggers activation when true. A component can only be active when its parent is active.


    8.3.2  Duration

    How long the modifier remains active for in world ticks. 0 means forever. 1 means stay active while the trigger condition is true.


    8.3.3  Next

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


    8.3.4  Priority and Group

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


    8.3.5  Delay

    How long to wait before the modifier can be activated again.


    9.0  Game Saving

    Voxatron is able to store the state of the world to disk under the current player save game slot. The most recently saved state is restored when either the player dies, continues a saved game, or selects 'back to checkpoint' from the in-game menu.


    9.1  Saving Methods

    There are 2 ways to invoke a save: using room checkpoints or save point pickups (e.g. the floating disk item). Each method suits different styles of game progress but they can also be used in combination.


    9.1.1  Room Checkpoints

    In the room properties box, a checkpoint can be set using the little flag button. There are two types of checkpoints: Red means the world is saved each time the room is entered, and green means the world is saved just before the room is exited.


    9.1.2  Save Point Pickups

    Pickups have a special checkpoint flag ('save point') that indicates the world should be saved on collection. This method 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 can be set to eternal collectable (the little coin icon in object instance properties). See the default save point pickup in the Objects tabs (a little disk).


    10.0  Microscripting

    Microscripting in Voxatron provides basic control over things like when an actor should spawn in a room, or when an actor's jump animation should be active. There are two main parts: a "trigger" which can be true or false (e.g. "All of the apples in this room have been collected"), and an "activation controller". The activation controller is used to determine things like how long an animation should play for, and which animations can play at the same time.

    [It is possible to build reasonably complex objects using only microscripting events: e.g. a monster that changes behaviour and appearance when it can see a player. But it is also possible to mix with Lua scripting to do more specific things once a general event has been triggered.]


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


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

    Selectors only pick out objects in the same room, with the exception of OBJ_ID which can refer to objects in other rooms.


    10.2.1  SELF

    When activating actor components, SELF can be used to refer to the actor this component belongs to. For example, a player animation that is triggered by the player jumping might use self:state:in_air.


    10.2.2  ACTOR

    The set of actors of a particular type.


    10.2.3  OBJ_ID(n)

    Picks out all actors that have object instance id n. Normally there is only one of them, so use this to refer to a particular actor. Unlike other selectors, OBJ_ID(n) can be used to pick out objects in other rooms.


    10.2.4  DEF_ID(n)

    All actors that are instances of definition n.


    10.2.5  GROUP_ID(n)

    All actors that are in group n.


    10.3  Events

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


    10.3.1  Common Actor Events

    STATUS

    An actor's status is the point on its lifecycle. At first it is DORMANT, and then ACTIVE once spawned in the room. From there, it can either be killed (DIED) or in the case of pickups, COLLECTED. Pickups that disappear because of a time limit have a DIED status. [When more than one actor is spawned from the same object, the object has a state of DIED or COLLECTED only when all such spawned actors (that the same object id) have died or have been collected.]

    STATE

    IN AIR, STANDING, SWIMMING

    JUMPED, LANDED

    HURT (by anything)

    SHOT (by any bullet, even if not hurt)

    ATTACKED (hurt by colliding with an actor not on the same team)

    DEFENDED (if damage was averted by having a 'DEFEND' flag set)

    HOISTED THROWN

    ENTERING EXITING: the moment when entering or exiting a room

    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.

    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 perfectly 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 optionally [not implemented yet] 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.

    COMPONENT

    Check if a component is active or not.

    BUTTON

    For players

    LEGACY

    Some built-in events from old version of Voxatron

    SHOOT-L: Player is shooting with left hand.

    SHOOT-R: Player is shooting with right hand.

    LEGACY:SHOOT-ANY Player is shooting with either hand.

    LEGACY:HAVE GUN Player is holding a gun

    LEGACY:SWIPE Player is swinging a sword / handheld weapon.

    LEGACY:CLOSE Actor is close to player (used to be TRIG:CLOSE)


    11.0  Lua Scripting API

    (See the API reference manual)