How can I create a custom physics data for my game?
An exporter consists of 2 files:
- exporter.xml - the description of the exporter itself
- template.txt - a template file containing the file layout
The exporters shipped with PhysicsEditor are located inside the application's folder in a folder called exporters.
To add your own exporter you can simply point PhysicsEditor's preferences to a location where you want to keep your custom exporters.

exporter.xml
Let's first have a look at the exporter.xml. This file describes the basic information about the exporter itself.
The exporter.xml is - as the name already says - an xml file.
It has 4 main blocks:
- Global exporter settings - settings for the exporter itself
- Global parameters - settings for all bodies - e.g. gravity
- Body parameters - settings for one body - e.g. body name, type, ...
- Fixture parameters - settings for a single fixture - e.g. bounce rate of the head
Global exporter parameters
Element | Type | Info |
---|---|---|
<name> |
string | Identifier for the exporter, must be unique. Otherwise the lastest exporter found for that name will overwrite the others. |
<displayName> |
string | This is how the exporter's name is displayed in the combo box in the GUI |
<description> |
string | Some information about the exporter |
<version> |
string | Exporter version - should be build from digits separated with dots - e.g. 1.0 or 1.0.1 |
<yAxisDirection> |
up / down |
Direction of the yAxis |
<physicsEngine> |
box2d / chipmunk / generic |
Name of the physics engine used. This currently set the polygon orientation. |
<template> |
string | Name of the template file - relative to the exporter.xml |
<fileExtension> |
string | File extension used when exporting the data file |
Anchor Points

AnchorPoints can be used as the center of a sprite - e.g. for rotation or move operations.
When setting the origin
to anchorPoint
it is also possible to center.
Additional global parameters are anchor points:
Element | Type | Info |
---|---|---|
<enabled> |
yes / no |
Display and use anchor points for this exporter |
<relX> |
float | Relative position of the anchor points x position |
<relY> |
float | Relative position of the anchor points y position |
Origin
Origin - the 0/0 location of the sprite. This might be set to a fixed position or to the anchor point.
Element | Type | Info |
---|---|---|
<type> |
fixed / anchorPoint |
Fixed sets a fixed relative position to the sprite's size, anchorPoint uses the AnchorPoint as sprite's center |
<relX> |
float | Relative position of the origin x position |
<relY> |
float | Relative position of the origin y position |
Parameter blocks
There are 3 parameter blocks which can be used to define properties and values on file base, per body and per fixture.
Element | Type | Info |
---|---|---|
<global> |
list of <parameter> |
The global parameters used for the complete file - e.g. gravity |
<body> |
list of <parameter> |
Parameters used for an individual body |
<fixture> |
list of <parameter> |
Parameters used on an individual fixture. Might be multiple sub-fixtures in case the fixture is decomposed into convex parts. |
Parameter definitions
In each of the elements <global>, <body> and <fixture> 0 or more parameters can be defined.
Values for all parameters
These elements must be present for all parameters and define their appearance in the GUI.
Element | Type | Info |
---|---|---|
<name> |
string | Name of the value (used in the template) |
<displayName> |
string | Human readable name of the value (used in the user interface) |
<description> |
string | Description of the element used in the tooltip when hovering over the element for some time |
<shortDescription> |
string | Short description of the element used in the status bar when hovering over the element |
<type> |
bool , string ,float , int , uint16 , bitfield |
Type of the parameter - which adds additional fields |
<bitfield> |
yes , no |
Connects a value to an existing bit field |
bool
Element | Type | Info |
---|---|---|
<type> |
bool |
Defines a bool input field / Checkbox |
<default> |
false / true |
The default value |

<parameter>
<name>isSensor</name>
<displayName>Is Sensor</displayName>
<description>The object only detects collisions without colliding</description>
<shortDescription>Turns the fixture into a sensor</shortDescription>
<type>bool</type>
<default>false</default>
</parameter>
string
Element | Type | Info |
---|---|---|
<type> |
string | Defines a string input field |
<default> |
string | The default value which is used if nothing else is entered |

<parameter>
<name>fixture_id</name>
<displayName>Identifier</displayName>
<description>Identify a fixture during collision detection</description>
<shortDescription>Identifier for the fixture</shortDescription>
<type><code>string</code></type>
<default>fixture123</default>
</parameter>
float
Element | Type | Info |
---|---|---|
<type> |
float | Defines a float input field |
<default> |
float | The default value |
<min> |
float | Minimum value |
<max> |
float | Maximum value |

<parameter>
<name>density</name>
<displayName>Density</displayName>
<description>
Density of the fixture, results in the mass if multiplied with the fixture's area
</description>
<shortDescription>Density of the fixture</shortDescription>
<type>float</type>
<min>-1000</min>
<max>1000</max>
<default>2.0</default>
</parameter>
int / uint16
Element | Type | Info |
---|---|---|
<type> |
int |
Defines a int input field |
<default> |
int | The default value |

<parameter>
<name>filter_groupIndex</name>
<displayName>Group</displayName>
<description>
Collision group - objects which have collision enabled need to be in the same collision group
</description>
<shortDescription>The collision group</shortDescription>
<type>int</type>
<default>0</default>
</parameter>
BitField
The bit field is a more complicated structure and might get a better XML representation some day.
It works quite simple for now. First you need to define a bitfield parameter which holds the other values.
The values themselves get an additional field <bitfield>yes</bitfield>
which connects them to the bit field.
Make sure to match the size of the values to the <size>
value in the bitfield definition.
Element | Type | Info |
---|---|---|
<type> |
bitfield |
Defines a bitfield input |
<size> |
int | The number of bits usually 16 or 32 |

<parameter>
<name>filter_bitfield</name>
<type>bitfield</type>
<size>16</size>
</parameter>
<parameter>
<name>filter_categoryBits</name>
<displayName>Cat.</displayName>
<description>Collision category</description>
<shortDescription>Collision category</shortDescription>
<type>uint16</type>
<default>1</default>
<bitfield>yes</bitfield>
</parameter>
<parameter>
<name>filter_maskBits</name>
<displayName>Mask</displayName>
<description>Collision mask</description>
<shortDescription>Collision mask</shortDescription>
<type>uint16</type>
<default>65535</default>
<bitfield>yes</bitfield>
</parameter>
Data structure
Top level objects
Value | Description |
---|---|
global
|
Contains all generic parameters defined in <global>
|
bodies
|
Contains all bodies as body objects
|
Body
A body
object holds all the bodies defined in PhysicsEditor.
Here's a table of the built in values.
Values defined in the <body>
section of the exporter.xml are added to the object.
Value | Description |
---|---|
anchorPointRel.x
|
Anchorpoint's x coordinate relative to the sprite's size.
|
anchorPointRel.y
|
Anchorpoint's y coordinate relative to the sprite's size.
|
anchorPointAbs.x
|
Anchorpoint's x coordinate in pixels.
|
anchorPointAbs.y
|
Anchorpoint's y coordinate in pixels.
|
body.size.width
|
The body's width in pixels. Same as sprite width. |
body.size.height
|
The body's height in pixels. Same as sprite width. |
body.fixtures
|
List of body's fixture objects.
|
Fixture
A fixture
object holds all the fixtures defined in a body.
Here's a table of the built in values.
Values defined in the <fixture>
section of the exporter.xml are added to the object.
Value | Description |
---|---|
type
|
Type of the fixture POLYGON or CIRCLE
|
isCircle
|
Convenience function to check if the fixture is a circle |
Circle-Fixture
These additional values are available inside circle fixtures.
Value | Description |
---|---|
fixture.radius
|
The radius of the shape in pixels |
fixture.center.x
|
Circle's center coordinate, x value |
fixture.center.y
|
Circle's center coordinate, y value |
Polygon-Fixture
These additional values are available inside polygon fixtures.
Value | Description |
---|---|
fixture.hull
|
All points as a single polygon object - may be concave.
Order of the points depends on the physics engine set in the exporter.xml
|
fixture.polygons
|
List of convex polygon objects after convex decomposition.
|
Polygon
A polygon is a list of point
objects:
Value | Description |
---|---|
x
|
x coordinate of a vertex in pixels |
y
|
y coordinate of a vertex in pixels |
The Template
I am using the GrantLee template system, which is close to Django templates. The basics are available from the GrantLee documentation.
A good starting point is the plain text exporter which is part of PhysicsEditor's distribution - since it contains all variables and features.
Referencing values
You can access 2 types of values
- Build in values
- Values that are added through parameters in exporter.xml
Values are surrounded by {{
and }}
Sub values are separated by .
.
You might use |
after the value itself to use filters for changing the value itself.
Please have a look a the GrantLee documentation for more details about that.
Template | Output | Remark |
---|---|---|
gravity={{global.gravity}};
|
gravity=9.800000;
|
This uses the gravity property from the global object and insers it into the template. (Gravity is a custom property.)
|
gravity={{global.gravity|floatformat:3}};
|
gravity=9.800;
|
Same as above with shortening the float value to 3 digits. |
Control structures
Control-Structure: if
{% if condition %} ... {% else %} ... {% endif %}
Control-Structure: for
{% for object in objectList %} ... {% endfor %}
Mixed example
This example prints a list of coordinates, separating each block with a ,
but not adding a comma before the first element of the list:
{% for point in fixture.hull %}
{% if not forloop.first %}, {% endif %}({{point.x}}, {{point.y}})
{% endfor %}