Custom collision shapes allow you to use a shape other than a rectangle or circle to define how actors collide with each other. Custom collision shapes consist of one or more convex polygons, each consisting of 3-8 vertices.
To assign a custom collision shape to an actor, select the Physics->Collision Shape option “Custom”. You will be asked to select the file containing the collision data you want for your actor.
You will be given a dialog that lets you choose a file that defines the polygon and vertex data for the collision shape.
NOTE 1: after you import the data, the file will no longer be needed; the data will be imported into your game files.
NOTE 2: if you need to re-import the vertex data, select rectangle or circle as a collision shape, and then custom again.
The data file is in JSON format, with the following layout:
- array labeled “rigidBodies”, with each element being an object:
- each object contains an array labeled “polygons”
- each element in the array is an array of objects with the vertex data
- each vertex object contains an “x” and “y” floating point value
- the x and y values should be between 0 and 1 (inclusive), with 0 being the left/bottom of the actor’s image, and 1 being the right/top of the image
- (Note: technically, the x and y values can be smaller than 0 and larger than 1, but that means that collision with your actor will happen before the actor appears to collide on the screen. Only do this if you’re very sure about wanting that effect).
For example, an object containing 1 polygon consisting of 3 vertices at (0, 0), (1, 0), and (0.5, 1):
{
"rigidBodies": [
{
"polygons": [
[
{ "x": 0, "y": 0 },
{ "x": 1, "y": 0 },
{ "x": 0.5, "y": 1 }
]]}
]}
The vertex data can be created 3rd party tools. Currently we support Physics Body Editor, and PhysicsEditor.
Using Physics Body Editor
To use Physics Body Editor to create a collision shape data for to import in GameSalad Creator, run the program, and:
- Select “New project”. You will need one project for each actor that you want to create a collision shape file for. We suggest giving the project name the extension “.json”.
- Under the Rigid bodies tab, select “New”, and click “Create body from image”. Select the image you are using for your actor.
- IMPORTANT: Physics Body Editor will import a rectangular image so the long side has the rage of 0->1 and the short side has a range that is smaller than 1. However, GameSalad expects both sides to be in the rage of 0->1. If you will be using a rectangular image for your actor, create a separate square image to import into Physics Body Editor. We will correctly scale your collision data to match your rectangular image.
- You should see your image filling a box with the range of 0->1 on the x and y axes.
- Add vertices by clicking on your image with the left mouse button, and finish adding them by clicking on the first vertex created. The program will automatically determine the polygon data based on the vertices you have added.
- You can also have the program try to create vertices for you by clicking the “Auto-trace” button.
- You can edit vertices by clicking to the left of the “Creation” button on the left so that the “Edition” button pops out. Vertices can by moved around with the mouse, or deleted with the delete/backspace key.
- Save the data by clicking the save button.
Note 1: To optimize performance, create as few vertices as possible for your actor.
Note 2: “Dynamic Objects” functions in the tool are not used by GameSalad.
Note 3: Although more than one image/rigid body can be imported into the tool for a project, only the first object’s data will be imported into GameSalad Creator. You will need to create a separate project file for each actor you want collision data for.
Using PhysicsEditor
PhysicsEditor requires a plugin to save your data for GameSalad. Link: PhysicsEditorGameSaladExporter
- Extract the plugin zip file to a directory of your choice. Make sure the directory has nothing else in it except the “gamesalad” plugin directory.
- Run PhysicsEditor, open preferences, and set the “Custom exporter directory” to the folder “gamesalad” is in.
- Restart the program, and set the “Exporter” to “GameSalad”.
- Click the “Add sprites” button to load your actor’s image.
- Click on the “magic wand” icon to auto-trace your image.
- Clean up the collision shape by deleting/adjusting the vertex points.
- Click the “publish” button. Make sure the file to save to has the extension “.json”.