PhysicsEditor Documentation

Overview

PhysicsEditor is a GUI tool to create collision shapes within seconds! Without specifying any additional options PhysicsEditor already creates very good results, but you also have enough options available to adjust things to your needs.

Supported operating systems:

MacOS

MacOS 10.7 (Lion) and above.

Windows

Windows XP, Vista, 7, 8, 8.1 and 10, 32bit and 64bit

Linux (Ubuntu)

Ubuntu 13.10 (Saucy Salamander) and above.

Creating your first collision shape

Creating your first collision shape is really simple:

1. Select the framework for your project.
2. Drag and drop an image to the shapes panel on the left.
3. Click on the magic wand icon to Auto-Trace your shape.
4. Set physics parameters.
5. Press Publish.

PhysicsEditor shows physics parameter settings depending on your framework. The settings and details are described in this documentation.

In case you can't find your favorite framework in the list, contact me or simply create your own custom exporter. With the built-in template system you can create all kinds of text files.

User Interface

The user interface consists of 3 main elements:

1. The Shapes list on the left
2. The Shape editor in the center
3. The Parameter editor on the right

Tool Bar

New project
Create a new project for your framework.

Open project
Open an existing .pes file.

Save project
Save the current project to disk. Creates a .pes file.

Publish
Writes all shapes using the framework settings and physics parameters.

Publish as...
Writes all shapes using the framework settings and physics parameters. Also allows you to specify where the files are written.

Add sprites
Add new sprites to the shape list.
You can also add sprites by dropping them into the shape list.

Shapes List

The shapes list contains all shapes that are currently known to PhysicsEditor.

You can add shapes simply by dragging and dropping them onto the list. Or alternatively click Add Sprites in the menu bar or below the shapes list.

Plus you can Open an existing .pes file in the menu bar.

You can clone a shape with its collision shape by clicking Clone selected shape below the shapes list.

Shapes can be renamed by double-clicking.

Shape Editor

The Shape Editor is the main area for editing your shapes.

Points can be dragged with the mouse.

To add points double-click near a line.

To remove a single point double-click the point.

With the Zoom Panel below the Shape Editor you can adjust the scaling factor of your Shape Preview.

On the left you have the scaling factor (default is 100), you can type in this field to change the zoom factor. You can also click on the arrows upward or downwards to change the zoom level in predefined steps.

Right next to it the "-"magnifying glass decreases zoom level in predefined steps.

Use the slider to zoom in or out continuously.

The "+"magnifying glass increases zoom level in predefined steps.

The golden "Zoom to pixel" magnifying glass resets the zoom factor to 100.

Automated Shape-Tracer

The Automated Shape-Tracer is one of the most powerful elements of PhysicsEditor. It automatically traces shape outlines!

Click on a point within the shape to start a trace. This is only needed if your shape consists of several non connected parts.

The most important setting is the Tolerance. This value tells the tracer how exactly the polygon should match the shape. It directly influences the number of vertices the polygon will have.

For example, setting the Tolerance to 20 will result in a 5-vertex polygon that no longer fits the shape; setting it to 1 creates a perfectly-matching polygon with 39 vertices. A Tolerance value of 5 gives us an acceptable match with about 15 vertices. That’s fine!

Not enough vertexes

Too many vertexes

Good trace

There are two Trace modes:

Natural

Try this for rounded objects with different angles or pointy edges.

Straight

Try this for objects with straight lines and angles.

Sometimes both modes deliver nearly identical results but sometimes have more or less vertexes.

The Alpha threshold value can be used to only add parts of the image which are more solid.

Another influence for the result is the starting point for the trace. Depending on the point you click in the shape might give slightly different results.

If you add more images to one shape in the main window, you can browse through the Animation phases with the slider.

The Frame mode decides how animation phases are handled:

Single frame

traces the current animation frame.

All frames - intersection

traces all frames, using only the parts that are available in all frames.

All frames - union

traces all frames, using any parts that are available in at least one frame.

Press OK to accept the polygon.

Parameter Editor

You can undock the Parameter Editor by clicking the small gray button on the left or by just dragging it out of position. Re-dock it by double-clicking or dragging it onto PhysicsEditors's or right window border.

The parameter editor strongly depends on the exporter you selected. The interface changes with the capabilities of the framework targeted. Therefore it is not possible to document all the many various options here.

In our PhysicsEditor tutorials section you can find tutorials for every framework supported, check them out to find out more about the specific parameters for your framework.

Common Physics Parameters

Collision shapes need physics parameters. They define how a body is moved by the physics engine.

Mass/Density

The Mass or Density value tells the physics engine how heavy an object is. This has effect on collisions between objects. It does not have any effect on how fast the bodies fall.

Friction

The Friction value comes in play when one object slides on another. Low friction lets the object slide a longer distance, higher values make the object stop faster.

Restitution/Elasticity/Bounce

Restitution, Elasticity or Bounce values are used when objects collide. They get repelled depending on the strength of this value. A basketball for example will usually have a high value here whereas a block of steel will have a low value.

Collision Parameters

Additionally collision parameters can be set directly from PhysicsEditor.

IsSensor

This value tells the physics engine that the shape is only used to create inform your main program about the collision but the shape itself does not collide with other objects.

Type

This is the collision type. Use this value to set up dedicated collision handlers using cpSpaceAddCollisionHandler. You might want to change this by modifying the exporter.

Group

Shapes in the same non-zero group do not generate collisions. Useful when creating an object out of many shapes that you don’t want to self collide.

Layers

Shapes only collide if they are in the same bit-planes. By default, a shape occupies all bit-planes. You can set names for simple reference in the left column under Bit's name. To add a shape to a specific layer set the checkmark in the right column under Layers.

PhysicsEditor Exporter Customization

PhysicsEditor already comes with a whole bunch of data formats allowing you to export to many game engines right out of the box - including Cocos2D, Corona SDK, Nape, Moai, Gideros, JSON, Flash/AS3 and many others. But sometimes this is not enough.

Maybe you need some extra properties you can assign to a shape or simply need a complete new format to match your needs.

The simple solution for you is to create your own custom format.

Basic structure of an exporter

An exporter consists of 2 files:

• exporter.xml - the description of the exporter itself
• template - 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.

For full details on how to create your own custom data format for your game engine read the corresponding blogpost: Customize PhysicsEditor Exporter.