Custom Body Data

Associates project-owned gameplay information with every managed physics body.

Every high-level JoltBody exposes a public data variable containing an ordinary GML struct. It is intended for names, item properties, health, categories, inventories and other gameplay metadata that should travel with the body wrapper without becoming part of the native physics state.

Basic usage#

body.data
options.data

Creation contract#

Supported body creation paths#

• Dynamic, Static and Kinematic primitive constructors accept options.data.
• Bodies created from reusable JoltShape resources accept the same option.
• Compound builder create, create_static and create_kinematic paths preserve custom data.
• Each body created without explicit data gets a distinct container; editing one default struct cannot affect another body.

Reference and mutation semantics#

• The supplied struct follows normal current GameMaker reference/value semantics. The extension does not deep-clone it.
• Nested structs and arrays remain usable and mutable through body.data.
• When the same struct is retained elsewhere, changes made through either reference are visible through the other according to normal GML semantics.
• The extension does not validate individual fields because their schema belongs entirely to the game project.

Where the data remains available#

body.data and user_data#

Lifecycle and ownership#

• Destroying a body invalidates its physics handle but does not erase data from an old wrapper that GML still references.
• A new body that reuses a native slot receives a new wrapper and new empty data; metadata never leaks from the destroyed body.
• body.data does not change mass, collision, sensor state, velocity, sleeping or resource lifetime.
• Save/load, JSON conversion, networking and persistence are project responsibilities and are not provided by this feature.

Example#

var bottle = jolt_box_create_dynamic(0, 0, 3, 0.5, 0.5, 1, {
    mass: 1,
    data: {
        name: "Bottle",
        price: 20,
        health: 10,
        type: "item",
        inventory: ["Gold", "Potion"]
    }
});

show_debug_message(bottle.data.name);
bottle.data.health -= 5;
array_push(bottle.data.inventory, "Sword");

Verified operation contracts#

These contracts distinguish units, return values, errors and lifetime according to the current implementation. Check results: false, 0 and undefined can mean different things for different methods.