Polly-B-Gone World XML Format

Polly-B-Gone uses an XML file to define the game world. The file is called world.xml and you'll find it inside the app bundle:

Polly-B-Gone.app/Contents/Resources/world.xml

You can edit this file to define change textures, lighting, and music. You can even design new objects, puzzles, rooms and entire levels!

This document assumes that you are familiar with the basic structure of XML. If you've edited a webpage before, then you know HTML which is similiar. However, XML is more formal and less forgiving, so don't forget to quote attributes and close your tags. In fact, in the initial release of Polly-B-Gone, there's no error detection whatsoever; if there is any problem with XML file, the application will crash on startup and output an error to the console. I realize this is frustrating and if people are interested in designing their own levels then I will improve the error handling!

I highly recommend you make a backup copy of the original world.xml file before making any edits. This way you can easily diff your changes and revert to a working version. (Or better yet, use SVN.)

The world in Polly-B-Gone is structured as a directed graph of rooms, defined by multiple instances of the room element. Typically, rooms are arranged in a linear fashion, starting with the easiest puzzles and progressing to more difficult ones. However, there's no reason to restrict yourself to a linear layout; you can structure arbitrary connections using portals and origins defined below.

The world element also defines the materials which will be used to control each object's appearance, for example the textures and diffuse colors used in the OpenGL lighting model. The associated material can also affect the physical properties of an object, like friction. You can also define the lights used in different rooms.

Child Element	Meaning
material	Defines visual properties of room objects: textures, diffuse lighting, specular lighting, etc. Also defines some physical properties like how slippery the surface is.
lighting	Defines the location of lights in the room, as well as each light's properties per the OpenGL lighting model. Up to eight static lights can be specified per room.
room	Defines a "room" in the game world: a collection of room objects that Polly can drive around in, connected with other rooms through portals.

Within each room, you need to define one or more room objects, which are 3D primitives like boxes and cylinders that Polly can drive on. Let's start by looking at a simple example:

<room name="hello-world" lighting="default">
  <camera-min x="-10" y="4" z="-5"/>
  <camera-max x="10" y="10" z="10"/>

  <origin name="start">
    <position x="0" y=".1" z="3"/>
    <velocity x="1" y="0" z="0"/>
  </origin>

  <block material="concrete">
    <min x="-10" y="-100" z="-10"/>
    <max x="10" y="0" z="10"/>
  </block>
</room>

Here we have a simple room, named "hello-world", that has only a single object: it's a square, flat 10x10 block made of concrete. Polly-B-Gone uses the standard XYZ axes, so the ground is the XZ plane, with the X-axis pointing to the right and the Z-axis pointing out of the screen.

The block extends to y="-100", which means that it's actually a very tall column that we're driving on. This technique is typically used so that the column appears infinitely-tall: the bottom will fade into the black fog below using OpenGL's fog model.

Attribute	Meaning
name	A unique name for the room, used to identify the room in conjunction with a portal and an origin.
lighting	The name of the associated lighting model.
music	The path to the file containing the background music for the room; optional. You can use MIDI (.mid), MP3 (.mp3) or Ogg Vorbis (.ogg), but SDL_mixer music support for MIDI and MP3 seems buggy; Ogg is strongly recommended.

Child Element	Meaning
camera-min	The minimum bounds of the camera position; a vector.
camera-max	The maximum bounds of the camera position; a vector.
origin	An entrance to the room, in terms of position and initial velocity.
portal	An exit from room, defined as an axis-aligned block, connected to an origin in another room (or potentially the same room).
block	An axis-aligned or oriented box. You can also use this element to describe other hexahedrons, such as parallelepipeds, provided the sides are quadrilateral.
wall	A quadrilateral or triangle, with optional texture coordinates.
tube	A cylinder with closed end caps.
ball	A sphere.
ramp	A five-sided polyhedron (two triangle sides and three quadrilateral sides).
escalator	An axis-aligned block with a surface velocity and associated moving texture.
switch	An axis-aligned block that enables any associated transformations (translations or rotations) when the player touches the switch.
seesaw	An axis-aligned block modeled as a three-particle system along the X-axis that swings back and forth depending on the player's position.
fan	A cylinder containing rotating fan blades. (This could also be implemented manually using normal blocks, tubes, balls and rotations.)
translation	A dynamic linear translation that is applied to any contained objects.
rotation	A dynamic rotation that is applied to any contained objects.
constant-force	An invisible axis-aligned block that applies a constant force to the player when the player is inside the block.

The camera follows Polly as she drives around the room. A fixed offset from the player's location is used: <0, 4, 6>. The offset is in world coordinates, rather than player coordinates, meaning that the camera does not rotate as the player turns. Although this may take a little getting used to when driving Polly (similar to driving a remote-control car), the big advantage as a level designer is that you can design the room so the camera doesn't get obstructed by room objects. For example, you can place tall objects in the back, with shorter objects in the front.

In addition, you can place a limit on the places the camera can go using the camera-min and camera-max elements. These define an axis-aligned box, and the position of the camera is clamped to be within this box regardless of the location of the player. For example, when Polly falls into a chasm, using a minimum camera y-value of 4 makes the camera tilt down, rather than follow Polly down. Of course, you should feel free to play with this to try different effects.

See Vector.

See Vector.

The entrances to each room are defined by the origin element. A room may have multiple origins; in a linear arrangement, each room typically has two origins on either side. The origin simply defines the starting position of the player, and the player's starting velocity. Usually, you want the starting velocity to be non-zero to give a sense of rolling continuity from one room to the next. The velocity also implies which direction Polly is facing when she enters the room.

Attribute	Meaning
name	A name for the origin, used to identify the origin in conjunction with the parent room. For example, an origin named "start" in the room "hello-world" would be referenced as "hello-world.start" from a portal.

Child Element	Meaning
position	The player's initial position; a vector.
velocity	The player's initial velocity; a vector. Implies an orientation.

The exits from each room are defined by the portal element. A room may have multiple portals; in a linear arrangement, each room typically has two portals on either side. The portal is represented as an invisible axis-aligned box; when the player enters the box, they are instantly ported to the associated origin.

Portals are not currently subject to dynamic transformations, but that could be easily added in the future.

Attribute	Meaning
origin	The name of the target room and origin the player is ported to when they enter the portal. For example, an origin named "start" in the room "hello-world" would be referenced as "hello-world.start".

Child Element	Meaning
min	The minimum bounds of the portal; a vector.
max	The maximum bounds of the portal; a vector.

Room objects are three-dimensional primitives that are placed in the room. They serve as driving surfaces as well as obstacles Polly may need to get around in order to proceed to the next room. Most objects are static, though any object can have dynamic transformations applied to them. Some objects, like seesaws and fans, are inherently dynamic. More dynamic objects may be added in a future release.

A block is a solid box, either axis-aligned or oriented. It is not as basic as a wall, but is frequently more convenient to define solid objects.

Attribute	Meaning
material	The name of the associated material.
top-material	The name of the associated material for the top surface; optional. If not specified, the body material will be used.

Child Element	Meaning
min	The minimum bounds of the box; a vector. This field is used for axis-aligned boxes.
max	The maximum bounds of the box; a vector. This field is used for axis-aligned boxes.
c	The center point of the box; a vector. This field is used for oriented boxes.
x	The X-direction halfvector of the box; a vector. This field is used for oriented boxes.
y	The Y-direction halfvector of the box; a vector. This field is used for oriented boxes.
z	The Z-direction halfvector of the box; a vector. This field is used for oriented boxes.

A wall is either a quadrilateral or a triangle. The vertices must be coplanar. Unlike the other shapes, walls do not define a solid object, but they still collide with Polly. Walls are most useful because you can explicitly specify the texture coordinates.

Attribute	Meaning
material	The name of the associated material.

Child Element	Meaning
x0	The first vertex; a vector.
x1	The second vertex; a vector.
x2	The third vertex; a vector.
x3	The fourth vertex; a vector; optional. This field is only used for quadrilaterals.
tex-coords	The texture coordinates of each vertex; optional. If specified, this should contain child element vectors t0, t1, etc. that specify texture coordinates in X and Y (U and V).

A cylinder, expressed as a main axis and a radius. In addition, you should specify the Y-axis for the cylinder, orthogonal to the main axis, to orient the texture.

Attribute	Meaning
material	The name of the associated material.
cap-material	The name of the associated material for the end caps; optional. If not specified, the body material will be used.
radius	The radius of the cylinder.

Child Element	Meaning
x0	The first vertex of the main axis; a vector.
x1	The second vertex of the main axis; a vector.
y	The Y-axis (in shape space), orthogonal to the main axis; a vector.

A sphere, expressed as a center point and radius.

Attribute	Meaning
material	The name of the associated material.
radius	The radius of the sphere.

Child Element	Meaning
x	The center point of the sphere; a vector.

A five-sided polyhedron, expressed using four vertices that describe the top surface. The middle vertices (x1 and x2) must be the upper points of the ramp.

Attribute	Meaning
material	The name of the associated material.
top-material	The name of the associated material for the top surface; optional. If not specified, the body material will be used.

Child Element	Meaning
x0	The first, lower, vertex; a vector.
x1	The second, upper, vertex; a vector.
x2	The third, upper, vertex; a vector.
x3	The fourth, lower, vertex; a vector.

An axis-aligned block with a surface velocity.

Attribute	Meaning
material	The name of the associated material.
top-material	The name of the associated material for the top surface; optional. If not specified, the body material will be used.

Child Element	Meaning
min	The minimum bounds of the box; a vector.
max	The maximum bounds of the box; a vector.
v	The surface velocity vector; a vector. Typically this is along either the X- or Z-axis.

An axis-aligned block that, when touched by the player, enables any associated dynamic transformations. When a transformation is associated with a switch, the transformation is initially disabled.

Attribute	Meaning
material	The name of the associated material.
active-material	The name of the associated material when the switch is activated; optional. If not specified, the body material will be used. Unless you want the switch to be invisible to the player, it is recommended that you specify an active material to give the player feedback that the switch was triggered.

Child Element	Meaning
min	The minimum bounds of the box; a vector.
max	The maximum bounds of the box; a vector.
target	The target transformation of the switch, as specified by the name attribute. Multiple target transformations may be specified.

An axis-aligned block that responds to the players weight by swinging back and forth. Currently, seesaws must be aligned along the X-axis, but this is easy to fix in a future release.

Attribute	Meaning
material	The name of the associated material.
top-material	The name of the associated material for the top surface; optional. If not specified, the body material will be used.
mass	The mass of the seesaw; lighter seesaws will swing more wildly in response to the player's weight, while heavier seesaws will be more stable.

Child Element	Meaning
min	The minimum bounds of the box; a vector.
max	The maximum bounds of the box; a vector.

Attribute	Meaning
material	The name of the associated material.
radius	The radius of the fan blades.
speed	The rotational speed of the fan blades.

Child Element	Meaning
x	The center point of the fan; a vector.
v	The fan axis vector; a vector. In the future, this will be changed to x0 and x1 to specify the fan cylinder main axis.

Defines visual properties of an object, as well as some physical properties (friction).

Attribute	Meaning
name	The name of the material. Must be unique.
slip-angle	The angle at which the player loses friction; use 0 degrees for a frictionless surface, and 90 degrees for infinite lateral friction. This will likely change to a true coefficient of (coulomb) friction in a future release.

Child Element	Meaning
diffuse	The diffuse color; a color.
specular	The specular color; a color.
ambient	The ambient color; a color.
emission	The emission color; a color.
texture	The texture, as referenced by the path attribute. Textures may be PNGs, JPEGs, or any other image format supported by SDL_image. It is recommended that JPEGs are used for opaque textures, and PNGs for transparent textures. Texture dimensions should be powers of two; 512x512 is recommended. Mipmaps are built automatically.

Defines the lights in the scene. At the moment, all lights are static, but in a future release it might be nice to have dynamic lighting, either by applying dynamic transformations to light sources or doing something fancier.

Attribute	Meaning
name	The name of the lighting. Must be unique.

Child Element	Meaning
ambient	The global ambient lighting; a color.
light	A light. Up to eight lights may be specified.

Attribute	Meaning
spot-exponent	The spot exponent factor.
constant-attenuation	The constant attenuation factor.
linear-attenuation	The linear attenuation factor.
quadratic-attenuation	The quadratic attenuation factor.

Child Element	Meaning
diffuse	The diffuse light; a color.
specular	The specular light; a color.
ambient	The ambient light; a color.
position	The light position; a vector. In addition, you may specify the w coordinate of zero for a directional light.

Defines an animated linear translation.

Attribute	Meaning
name	The name of the translation. Only required if this translation needs to be enabled by a switch. The name must be unique.
speed	The speed of the translation. Speeds cannot be negative.
start	The start parameter, in [0, 1].
dampen	The dampening factor (in [0, 1]) of the translation. Use 0 for a "hard" reset, where the platform instantly changes direction. Keep in mind that this is likely to throw the player off the platform, so using a dampening factor near 1 will make the platform smoothly change directions. The dampening factor must be less than one. In the current implementation, using a non-zero dampening factor means any contained shapes to not fit exactly to the start and end position specified by the translation; they will go slightly outside the bounds. This will be fixed in a future release.
mode	The reset mode of the translation. The default is "reverse", which means the translation reverses directions when it reaches the end. Alternatively, you can use "one-way" if you want the translation to stop at the end (useful for extending bridges, for example) or "reset" if you want the translation to reset to the initial position instantaneously (used in the "barrelroll" room, for example).

Child Element	Meaning
x0	The start position; a vector.
x1	The end position; a vector.
*	Translations can contain any other room object, room force, or another transformation. In the simplest case, a translation might contain a single block to make a moving platform. But, by composing multiple translations and rotations, you can make interesting dynamic rooms.

Defines an animated rotation around an axis and origin.

Attribute	Meaning
name	The name of the rotation. Only required if this rotation needs to be enabled by a switch. The name must be unique.
speed	The speed of the rotation. Speeds can be negative.
angle	The start angle (in degrees).

Child Element	Meaning
origin	The rotation origin; a vector.
axis	The rotation axis; a vector.
*	Rotations can contain any other room object, room force, or another transformation. In the simplest case, a rotation might contain a single block to make a rotating platform. But, by composing multiple translations and rotations, you can make interesting dynamic rooms.

Defines an invisible axis-aligned box that applies a constant force to the player when the player is inside the box.

Child Element	Meaning
min	The minimum bounds of the box; a vector.
max	The maximum bounds of the box; a vector.
force	The force vector; a vector.

Attribute	Meaning
x	The X-coordinate of the vector.
y	The Y-coordinate of the vector.
z	The Z-coordinate of the vector.

Attribute	Meaning
r	The red component of the color.
g	The green component of the color.
b	The blue component of the color.
a	The alpha component of the color.