Quickstart
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 by the current version of PhysicsEditor:
- macOS 10.14 and newer, including macOS 12
- Windows 8 and newer, including Windows 11
- Ubuntu 20 and newer
Older versions also support OS versions back to macOS 10.7 (Lion), Windows XP and Ubuntu 13.10 (Saucy Salamander) but might not contain all features of the current release.
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
Toolbar
- 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.
- Add sprite
- Add new sprites to the shape list. You can also add sprites by dropping them into the shape list.
- Remove sprite
- Remove a sprite and sprite settings from the shape list
- Clone sprite
- Duplicate a sprite and its physics settings.
- Publish
- Writes all shapes using the framework settings and physics parameters.
- Tutorials
- Open the PhysicsEditor tutorials page.
- Feedback
- Send feedback to us.
Shapes Editor
The Shape Editor is the main area for editing your shapes.
- Double-click near a line to insert a point
- Double-click a point to remove it
- Points can be dragged with the mouse.
- Add circle
- Add a circle fixture to the body.
- Add polygon
- Add a polygon fixture to the body.
- Shape tracer
- Automatically create a polygon from the sprite's transparency.
- Copy fixture
- Copy a fixture with its physics parameters.
- Paste fixture
- Paste a fixture with its physics parameters and add it to the body.
- Delete fixture
- Remove a fixture from the body.
- Flip horizontally
- Flip selected fixture horizontally.
- Flip vertically
- Flip selected fixture vertically.
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!
Tracer settings: Too many vertices (left), good, not enough vertices (right).
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.
Please refer to your frameworkʻs reference manual for more information or look at the examples shipped with PhysicsEditor. 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.