Coordinates

Each voxel in a Microcosm world is located at a set of XYZ coordinates. Since Microcosm itself is written in Unity, it uses what’s referred to as a “left-handed” coordinate system. If you put your left thumb, index, and middle fingers into perpendicular “L” shapes with your middle finger pointing away from you and index finger pointing up, the fingers will be pointing in the positive X, Y, and Z directions.

These coordinates can be referenced in Lua using a table with three whole numbers. For example, {0, 0, 0} is the coordinate at the world origin (where the device is when the application first starts tracking). Here a few other sample coordinates to help you get oriented:

• {10, 0, 0}: 10 voxels to the right of the world origin (along the red X axis).
• {0, 10, 0}: 10 voxels above the world origin (along the green Y axis).
• {0, 0, 10}: 10 voxels in front of the world origin (along the blue Z axis, ”away” from the player when the application starts).
• {-10, 0, 10}: 10 voxels to the left and 10 voxels in front of the world origin.

Demonstration of the “left hand rule” for working with coordinates. The left thumb points in the direction of +X, index in the direction of +Y, and middle in the direction of +Z.

Anatomy of a voxel

Voxels are made up of a color and a layer. Colors look very similar to coordinates! They’re also a table, but this time of three whole numbers from 0 to 255. Unlike coordinates, colors can’t have negative values, or positive values greater than 255. The values of a color table represent its red, green, and blue components, respectively. For example, true red is {255, 0, 0}, true green {0, 255, 0}, and true blue {0, 0, 255}. There are many tools for finding these RGB color values, including one built right into Google.

A voxel’s layer changes how it’s rendered in the world. There are currently two options: Cosm.LayerType.Solid and Cosm.LayerType.Transparent. Here are a couple example voxels:

redVoxel = {
  color = {255, 0, 0},
  layer = Cosm.LayerType.Solid
}

-- When drawing transparent voxels, make sure to pass a fourth
-- `alpha` value in the color table. This is also 0-255, with 0
-- being fully transparent. 0 may be useful for things like
-- cursor hit detection in interactive scripts. 255 should not
-- be used for transparent voxels, and will cause rendering bugs.
transparentBlueVoxel = {
  color = {0, 0, 255, 200},
  layer = Cosm.LayerType.Transparent
}

Draw mode

The draw mode determines what actually happens when voxel drawing commands are run. These are mostly the same as the options available in the user interface, with one extra (Set).

Cosm.DrawMode.Create

Creates new voxels, but doesn’t overwrite existing voxels.

Cosm.DrawMode.Replace

Changes the color/layer of existing voxels, but doesn’t create new ones.

Cosm.DrawMode.Delete

Deletes existing voxels.

Cosm.DrawMode.Set

The Set draw mode is the only one that’s not available from the user interface. This mode works like a combination of all of the other modes depending on the context:

• Creates new voxels in empty space like Cosm.DrawMode.Create
• Changes the color/layer of existing voxels like Cosm.DrawMode.Replace