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:
- Select the framework for your project.
- Drag and drop an image to the shapes panel on the left.
- Click on the magic wand icon to Auto-Trace your shape.
- Set physics parameters.
- 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:
- The Shapes list on the left
- The Shape editor in the center
- The Parameter editor on the right
Tool Bar
Create a new project for your framework.
Open an existing .pes file.
Save the current project to disk. Creates a .pes file.
Writes all shapes using the framework settings and physics parameters.
Writes all shapes using the framework settings and physics parameters. Also allows you to specify where the files are written.
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.
| Button | Action |
|---|---|
| Add circle | Press this button to add a circle to the shape. |
| Add polygon | Press this button to add a polygon to the shape. The shape can be dragged and points can be added to fit the shape of the image. |
| Automated Shape-Tracer | Press this button to start the Automated Shape-Tracer for automated detection of your shapes out-line. Automated Shape-Tracer and its options are described in detail in the following chapter. |
| Flip horizontally | Flips the shape horizontally. |
| Flip vertically | Flips the shape vertically. |
| x and y | Manually set the x and y coordinates for a single chosen point. |
| Delete polygon | Deletes the current polygon. |
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!
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.