Mirage WorldBuilder syntax

From Tekkotsu Wiki

Jump to: navigation, search



The Worldbuilder takes an input file with extension .ian and produces an output file with extension .mirage. It should be on your search path, so to invoke it, just type:

WorldBuilder path-to-my-file.ian

User-created world files typically live in ~/project/worlds. The WordlBuilder itself can be found in /usr/local/Tekkotsu/tools/mirage/worldbuilder.

Each line of a .ian file is a separate directive. The most basic directive creates a shape; its syntax is:

shape_name attribute1=value1 attribute2=value2 ...


cube material=Wood location=[0,0,25] scale=[50,50,50] mass=5

Comments begin with # and can appear anywhere on a line.


The built-in shape primitives are cube, sphere, cylinder, and plane. Shape attributes are shown below:

Attribute Meaning
material=nameName of a material defined in some material file in /usr/local/Tekkotsu/tools/mirage/media or ~/.mirage. AprilTags are a special type of material and the syntax changes to material="AprilTag/tag16h5/tagnumber" (including the quotes).
location=[x,y,z]     Location of the center of the object, in millimeters.
scale=[x,y,z] Scale of the object in millimeters.
(or rotx or roty)
Orientation/rotation around the centroid of the object using the three components of a unit quaternion, or an angle in radians. See the Quaternions section below.
pointat=[x,y,z]Overrides orientation to point the z axis at the specified point.
visible=Boolean Visibility of the object to the robot, true for enabled and false for disabled.
collision=Boolean Defaults to true. If false, the robot can pass through the object without colliding.
mass=Float Mass of the object in Kilograms. Objects in the environment without mass or mass 0 are static.
centerofmass=[x,y,z] Center of mass of the object, in millimeters.
kinematics=name Special kinematics can be set by providing a kinematic filename or .kin file.
group=name Register the object in a group. When a group is instantiated (via the copy command), the object will be instantiated relative to its group.
attachto==name Attach this shape to a previously defined shape. Note: nested/chained attachment is not currently supported, so you can only attach shapes that don't themselves have attachments.

Model attributes: The following advanced attributes allow you to use an Ogre mesh file for rendering the object in Mirage.

Model Attribute Meaning
model=filename Name of an Ogre mesh file
moffset=[x,y,z] Offset of the model relative to parent coordinate frame
mrotation=[x,y,z] Rotation of the model relative to the parent coordinate frame, expressed as a unit quaternion
mscale=[x,y,z] Scale of the model (defaults to the regular scale attribute)

Collision model attributes: When specifying a complex model such as an Ogre mesh file, it may be beneficial to specify a simpler collision model to speed up the physics calculations.

Collision Model Attribute Meaning
cmodel=shape Collision model to use (cube, sphere, cylinder, plane)
cmoffset=[x,y,z] Offset of the collision model relative to parent coordinate frame
cmrotation=[x,y,z] Rotation of the collision model relative to the parent coordinate frame, expressed as a unit quaternion
cmscale=[x,y,z] Scale of the collision model (defaults to the regular scale attribute)

Defining New Shapes

The syntax for defining new shapes is:

define new_shape parent_shape attribute1=value1 attribute2=value2 ...

The parent shape can either be one of the built-in shape primitives or a previously defined shape. In the example below, woodencube is defined as a refinement of the cube primitive, then bigwoodencube is defined as a refinement of woodencube, Then we make an instance of bigwoodencube at a specific location. Note that the z coordinate (50) is half the object height; this assures that the cube will be resting on and not embedded in the floor.

define woodencube cube material=Wood
define bigwoodencube woodencube scale=[100,100,100]

bigwoodencube location=[0,300,50]

Variables and Expressions

Variables can be declared in order to facilitate calculations and make the code neater and malleable. The syntax used to declare variables is:

set variable_name = expression


set wallLength = 1000
set wallMass = 5000
set wallHeight = wallLength/2

The print command can be used to print a string or the value of an expression:

print "The surface area of the wall is:"
print wallLength * wallHeight

After variables are declared and assigned, they can be directly used in attributes (coordinates or values). Example:

define Wall cube scale=[500,wallLength,wallHeight] mass=wallMass

The WorldBuilder language also offers full support for complex mathematical expressions:

Mathematical Expression Syntax
Arithmetic operators +, -, *, /, %, ^
Relational operators ==, <, >
Trigonometric functions sin(value), cos(value), tan(value)
Square root and absolute value sqrt(value), abs(value)
Degrees to radians deg2rad(value)

Note: pi is predefined as a mathematical constant before the parsing begins. Also, parentheses can be used to prioritize order in computations.

These mathematical expressions can be combined with variables to compute more complex and useful values.


set wallAngle = deg2rad(90)
set wallOrient = cos((pi/2 - wallAngle/2)/2)
Wall location=[400,200,wallHeight/2] orientation=rotz(wallOrient+pi/18)

Other types of expressions:

Expression Syntax
Vector [x,y,z]
String "string_variable", string_variable
Boolean "true", "t", "yes", "1"

Quaternions are four-dimensional complex numbers that can be used to express rotations in 3D. Mirage represents these rotations using vectors. They can be used as arguments to the orientation= keyword. Here is a tutorial on quaterion rotations.

Quaternion Syntax
Vector form[x, y, z]
To rotate about the Z axis by an angle theta, use [0, 0, sin(theta/2)].
Axis-aligned rotationrotx(angle), roty(angle), rotz(angle)
angle is in radians

For a detailed example of using expressions to define a world, see the VeeTags Maze world.


The copy command copies a group of shapes, making a new set of instances. You cannot copy a shape class, only the instances that are members of the group, so the shape class must be instantiated at least once to establish a non-empty group.

copy groupname offset flags

The offset parameter is a vector [dx,dy,dz]. The flags are optional.

Flag Meaning
flipxFlip the copies about the x axis
flipyFlip the copies about the y axis
keepgroupAdd the copies to this group, increasing the group size. Note: if the object is a member of multiple groups, it will always be added to the other groups; the keepgroup flag only controls whether it is added to the group being copied.

Light Sources

Light sources can be defined using the WorldBuilder. The syntax for defining a new light source is:

light attribute1=value1 attribute2=value2 ...

The light attributes that can be modified are:

Attribute Meaning
location=[x,y,z] Location of the light source.
orientation=quaternion Light orientation using components of a quaternion (see the Quaternion section above).
pointat=[x,y,z]Overrides orientation to point the z axis at the specified point.
color=RRGGBB_hex_string Color of the light can be set using a hexadecimal string value for R (red), G (green), and B (blue).


light location=[-100,3000,2000] color=0000ff

Environment Parameters


Change the background of the Mirage world. The default background is solid black. Syntax:

background attr1=value1 ...
Background Attribute Meaning
material=name Name of a material defined in some material file in /usr/local/Tekkotsu/tools/mirage/media or ~/.mirage.
model=name Model used for the skybox. Obtions are Dome, Plane, Box and None.
color=#RRGGBB_hex_string Color can be set using a hexadecimal string value from 0 to f for R (red), G (green), and B (blue).
tiling=expression Tiling can be set depending on the material that is chosen for the background.
distance=expression Distance of the background can be modified with this attribute.
curvature=expression Curvature of the background can be modified with this attribute.


Controls the rendering of shadows in the simulated world. Syntax:

shadows attr1=value1 ...
Shadow Attribute Meaning
enabled=boolean Enable or disable shadow rendering.
color=#RRGGBB_hex_string Color can be set using a hexadecimal string value from 0 to f for R (red), G (green), and B (blue).
modulative=boolean One of the control methods used to render shadows. It can be enabled or disabled.
stencil=boolean One of the control methods used to render shadows. It can be enabled or disabled.


Physics Attribute Meaning
erp=expression Error Resolution Proportion (ERP) adjusts the granularity used to solve physics constraint problems. Larger values can reduce the workload for these problems, but may cause jitter or instability.
gravity=expression Sets gravity to a different value relative to the default value (-9.8m/s^2).
massscale=expression Sets the mass scale to a different value relative to the default.
solveriterations=expression Controls the maximum number of iterations the constraint solver may take. Increasing this may allow more problems to be solved, such as in joint strain situations.
spacescale=expression Defines the distance scale used when solving constraint problems.
stepsperframe=expression Allows each graphics update (new frame) to be subdivided into further physics solving steps.


Observer Attribute Meaning
location=[x,y,z] Adjusts the initial location of the observer.
orientation=[x,y,z] Observer's orientation can be changed using components of a quaternion.
pointat=[x,y,z] Overrides orientation to point the z axis at the specified point.

Other environment parameters

These parameters are global values for the Mirage environment, so they occur on their own line as keywords by themselves.

  • ambient=#RRGGBB_hex_string: Ambient color can be set using a hexadecimal string value from 0 to f for R (red), G (green), and B (blue).
  • inertia=expression: Changes the default inertia.
  • mass=expression: Changes the default mass.
  • render=expression: Inertia parameters for the rendering.
  • timescale=expression: Inertia parameters for the timescale.

Logo Turtle Mode

Logo turtle mode allows you to draw shapes using relative motion commands such as forward and turn. This is useful for drawing complex walls or corridors.

Logo Mode Command Meaning
penheight numberSet the height of the line the pen will draw.
penwidth numberSet the width of the line the pen will draw.
penshape shapeSet the shape the pen will draw with; default is cube. The width and height are controlled by the penwidth and penheight commands; the length is controlled by the forward command.
pencolor materialSet the color (material) the pen will draw in.
pendownTurn on drawing mode.
penupTurn off drawing mode; motion commands will still take effect.
forward numberMove the pen forward by this amount, drawing a shape if the pen is down.
up numberMove the pen up by this amount.
turn degreesTurn by this many degrees (positive is counterclockwise).
moveto [x,y,z]Set the pen position.
heading degreeesSet the direction the pen is facing.