Skip to content

How to load PhysicEditor Shapes into your project

Olivier Biot edited this page Nov 12, 2026 · 17 revisions

First create your physics data using the PhysicsEditor Tool:

featurecarousel_physiceditor

PhysicsEditor does not currently have a specific melonJS exporter, so use the Lime+Corona exporter which produces standard JSON output:

{
    "hotdog": [
        {
            "density": 2, "friction": 0, "bounce": 0,
            "shape": [6, 30, 11, 23, 100, 0, 104, 10, 92, 53, 57, 63, 32, 63, 8, 49]
        },
        {
            "density": 2, "friction": 0, "bounce": 0,
            "shape": [123, 24, 113, 39, 92, 53, 104, 10, 121, 15]
        }
    ]
}

Other exporter templates work too. The material fields above are custom parameters a template declares rather than fixed parts of the format, so real files differ, and melonJS reads the three layouts these produce: a bare fixture list like the one above, an object holding a fixtures list, and an object that is itself a single fixture. Circles are read as well as polygons, and a single-body export is used whole.

Load the shape definition

Add the JSON file to your resources like any other JSON asset:

{ name: "shapesdef", type: "json", src: "data/json/shapesdef.json" }

Apply the shapes to a body

Name the asset from a body definition, with id naming the body inside the file:

import { Sprite, loader } from "melonjs";

class Hotdog extends Sprite {
    constructor(x, y, settings) {
        super(x, y, settings);

        this.bodyDef = {
            type: "dynamic",
            shapes: "shapesdef",   // the name the JSON was preloaded under
            id: "hotdog",          // the body to read out of that file
        };
    }
}

The file is resolved into real collision shapes when the renderable is added to the world, before any physics adapter sees the definition. The same definition therefore works unchanged on the built-in solver and on the matter and planck adapters.

Since 20.7.0. Earlier versions use body.fromJSON(loader.getJSON("shapesdef"), "hotdog"), which reaches the built-in solver only; it still works but warns from 20.7.0 onward.

What comes across, and what does not

The density, friction and bounce the shapes were authored with are applied to the body, each honoured by whichever backends support it: the built-in solver has no contact friction, for example, exactly as it has none for a hand-written definition. The format carries these per fixture, but only one backend of three could honour that, so they reduce onto the body and a file whose fixtures disagree warns.

Anything you state on the definition yourself wins over the file:

// bounces at 0.9 whatever the file says
this.bodyDef = { type: "dynamic", shapes: "shapesdef", id: "hotdog", restitution: 0.9 };

The exporter's own collision filter block is deliberately not read, in any spelling. Its categoryBits and maskBits are numbers in the exporting tool's namespace rather than collision.types values, and a template writes its defaults for every fixture whether or not you set anything: importing them would silently tag your shapes as something they are not and stop them colliding. Set collisionType and collisionMask on the body definition instead.

If you want per-shape filtering from the editor, PhysicsEditor lets you define your own custom parameters. Name them collisionType and collisionMask and they are read per fixture, in melonJS's own namespace.

Notes

  • PhysicsEditor automatically decomposes concave shapes into convex polygons, so one authored outline may arrive as several shapes. Collision resolution handles this correctly; keep it in mind if you operate on the shapes by hand.
  • Shapes are owned by the body they are given to, and a rotating body mutates them in place. Naming the asset avoids the hazard entirely: every body resolved from the file mints its own shapes, so two sprites sharing one definition never share geometry.
  • Authored shapes and imported ones can sit in the same list.

See the Physics Shapes example for the same file and the same definition running on all three backends.

Clone this wiki locally