Application Manual
Get started quickly!
Here is a video tutorial to get you quicky up and running. It shows how to create a project, how to add a new body, and how to define its collision shape. The video quality is not awesome at all (sorry about that), so don’t look at it to appreciate the user experience of the application but only to learn the basic commands.
There is two kind of shapes that can be created: polygons and circles. To create a polygon shape, all you have to do is to enable the creation mode, and to click anywhere on the screen. Each click will add a point to the polygon, and when you want to close it, just click on the first point. To create a circle shape, you need to hold CTRL or C key, and then click once to define the center of the shape, and a second time to define its radius.
Several keyboard shortcuts exist to make your life easier:
- TAB to switch between creation, edition and test modes,
- BACKSPACE to delete the selected points,
- ENTER to insert new points between the selected ones,
- ESC to cancel the creation of a shape before you close it.
The tool supports an auto-trace feature that may help you in many occasions with a little practice. Auto-trace algorithms are generally far less precise than your hand, but with a few refinement steps, you can create complex shapes very quickly.
Auto-trace feature is only available when there is no existing shape previously defined, and if an image is associated to your body. It works on the alpha channel of the image, and takes 4 parameters. Hull tolerance defines how precisely you want the contour of your image to be followed (a higher value means a lower precision). Alpha tolerance ranges between 0 and 255 and defines the alpha limit between a solid pixel and an empty pixel. When activated, multi-part detection will try to trace multiple shapes, and hole detection will try to detect a hole in an image. The success of the two last option is not guaranteed.
In Physics Body Editor, you define a body for each image, and this body is made of multiple fixtures. A fixture is basically a shape (polygon or circle) associated to some parameters, like its density and its friction. A body is located in the world with a single point, called the reference point. Its fixtures are placed around this reference point. Note that this reference point has nothing to do with its mass center. Indeed, the rotation point of your body is its mass center. The reference point has no impact on the physics simulation. It is just a convenience point to get the position of your body relatively to this reference point. That’s it for the theory of physics engines.
By default, the reference point of a body is at the bottom left corner of its associated image. This means that when you will position the body in your game world, its fixtures will all be at the right of the location. You can move this reference point in Physics Body Editor in edition mode: it is the red cross with a circle.
Note: the following code snippets are extracted from the loader-libgdx-demo project. They are written in Java, and target the LibGDX game framework. However, they should be easy to understand, and easy to port to any other language.
There are two important things when you want to use your project file in your game: (1) attaching the fixtures to your bodies, and (2) drawing the associated image at the right place. In physics engines, bodies are models: they are not related to how you will render them on screen at all. See my tutorial about the separation between models and render to understand.
First step is easy, the provided loader does everything for you. Note that at line 7, the position correspond the the world position of the body reference point. Here we set it at world coordinates (0,0).
private void createBottle() {
// 0. Create a loader for the file saved from the editor.
BodyEditorLoader loader = new BodyEditorLoader(Gdx.files.internal("data/test.json"));
// 1. Create a BodyDef, as usual.
BodyDef bd = new BodyDef();
bd.position.set(0, 0);
bd.type = BodyType.DynamicBody;
// 2. Create a FixtureDef, as usual.
FixtureDef fd = new FixtureDef();
fd.density = 1;
fd.friction = 0.5f;
fd.restitution = 0.3f;
// 3. Create a Body, as usual.
bottleModel = world.createBody(bd);
// 4. Create the body fixture automatically by using the loader.
loader.attachFixture(bottleModel, "test01", fd, BOTTLE_WIDTH);
}Now that we have our model entirely built, we need to draw the corresponding image at its location. LibGDX draws images with a reference to their bottom left corner. Therefore, if you left the reference point at the bottom left corner of your body, you can directly place the image at the location of the reference point (returned by Box2d engine with the getPosition() method).Else, if you changed the reference point location, you need to take it into account to draw the image.
Therefore, you need to store the reference point somewhere for later use:
bottleModelOrigin = loader.getOrigin("test01", BOTTLE_WIDTH).cpy();Finally, in your render method, you can draw the image at the reference point location, offset by its local coordinates relatively to the image bottom left corner:
public void render() {
Vector2 bottlePos = bottleModel.getPosition().sub(bottleModelOrigin);
bottleSprite.setPosition(bottlePos.x, bottlePos.y);
bottleSprite.setOrigin(bottleModelOrigin.x, bottleModelOrigin.y);
bottleSprite.setRotation(bottleModel.getAngle() * MathUtils.radiansToDegrees);
...
}That’s all, you should now be up and running!
