melonJS
    Preparing search index...

    Interface BodyDefinitionInit

    A body definition as authored, before the engine resolves it.

    This is what Renderable#bodyDef takes. It is a BodyDefinition whose shapes may additionally name a collision shape file, which is resolved into real shapes when the renderable is added to a container — so every adapter receives the same BodyDefinition, and one definition works unchanged on the builtin, matter and planck backends alike.

    // preload the file the shape editor exported, like any other JSON
    { name: "shapes", type: "json", src: "data/physics/shapes.json" }

    // then name it, and the body inside it to use
    new Sprite(x, y, {
        image: "hotdog",
        bodyDef: { type: "dynamic", shapes: "shapes", id: "hotdog" },
    });

    // material values the file carries are applied unless the definition
    // states otherwise, so this body bounces at 0.9 whatever the file says
    { type: "dynamic", shapes: "shapes", id: "hotdog", restitution: 0.9 }

    // authored shapes still work, and the two can be mixed
    { type: "static", shapes: [new Rect(0, 0, 32, 32)] }
    interface BodyDefinitionInit {
        collisionMask?: number;
        collisionType?: number;
        density?: number;
        fixedRotation?: boolean;
        friction?: number;
        frictionAir?: number | { x: number; y: number };
        gravityScale?: number;
        id?: string;
        isSensor?: boolean;
        maxVelocity?: { x: number; y: number };
        restitution?: number;
        shapes: string | BodyShape[] | ShapeEntry[];
        type: BodyType;
        userData?: unknown;
    }

    Hierarchy

    Index
    collisionMask? collisionType? density? fixedRotation? friction? frictionAir? gravityScale? id? isSensor? maxVelocity? restitution? shapes type userData?
    collisionMask?: number

    Bit mask of collision types this body can collide with. Defaults to collision.types.ALL_OBJECT.

    collisionType?: number

    Bit flag identifying this body's collision type. See collision.types. Adapters translate to their native filter system (Matter collisionFilter.category, Box2D categoryBits).

    density?: number

    mass per unit area; defaults are adapter-specific

    fixedRotation?: boolean

    Disable rotation simulation, so the body keeps whatever angle it has.

    Defaults to whatever the underlying engine defaults to, which for both matter and planck is false: a rigid body turns when something turns it. Pass true for anything that must stay upright, such as a platformer actor that should never tip over.

    The builtin adapter ignores this field, since its rotation is visual only and its collision shapes never turn either way.

    false

    // a character that stays upright whatever it walks into
    this.bodyDef = { type: "dynamic", shapes: [...], fixedRotation: true };
    friction?: number

    Surface coefficient of friction during contact. Matter's body.friction — 0 = frictionless (objects slide past each other), 1 = high stick. Determines how much tangential velocity is transferred between contacting bodies. Combined with body rotation, this is what produces "throw" between colliding circles and "english" off a wall. Distinct from frictionAir (per-step drag with no contact required). Builtin SAT adapter ignores this.

    frictionAir?: number | { x: number; y: number }

    Per-step velocity damping (Matter's frictionAir). Bleeds velocity off every frame regardless of contact, creating terminal velocity. Number applies uniformly; {x, y} damps each axis independently (melonJS-specific — Matter only supports scalar and will average).

    It damps ROTATION as well as translation on the matter and planck adapters, so it is also what stops a body spinning once something has set it turning. Left at 0, a spin never decays. The builtin adapter maps it onto its per-axis body.friction damping vector instead, and has no rotation to damp.

    gravityScale?: number

    Per-body gravity multiplier. 0 disables gravity for this body; negative inverts it. Matches Matter's body.gravityScale.

    id?: string

    Which body to read out of the file, when shapes names one. A collision shape file usually holds a map of body name to fixtures, and this is the name the shapes were authored under.

    Not needed for a single-body export, where the file IS one body's fixture list with no map above it; there is nothing for an id to name, and the whole file is used.

    isSensor?: boolean

    the body generates collision events but no physical response

    maxVelocity?: { x: number; y: number }

    Hard cap on velocity magnitude per axis. melonJS extension — Matter has no direct equivalent and uses frictionAir-induced terminal velocity instead; MatterAdapter implements this by clamping velocity in an afterUpdate hook.

    restitution?: number

    Bounciness (coefficient of restitution): 0 = inelastic (stops on contact), 1 = perfectly elastic (rebound speed equals impact speed). Typically in [0, 1]. Values > 1 produce a super-elastic ("energy-gain") rebound — physically unrealistic but useful for arcade effects like pinball flippers, slingshot boosters, or trampoline pads. The value is not clamped at the interface level; how an adapter handles out-of-range values is adapter-specific.

    shapes: string | BodyShape[] | ShapeEntry[]

    The body's collision shapes, as any of:

    • real shapes, the usual case
    • the name a collision shape file was preloaded under, paired with BodyDefinitionInit.id
    • the exported fixtures themselves, for a file read by hand

    Shapes are OWNED by the body they are given to, and a rotating body mutates them in place, so never share one array between two bodies. Naming the file instead sidesteps this: every body resolved from it mints its own shapes.

    type: BodyType

    simulation kind

    userData?: unknown

    arbitrary user data attached to the body

    Settings
    Member Visibility

    On This Page
    Properties