JSON format and collision shapes
JSON v1–v6, seven collision types, coordinate conversion and validation limits.
Checked against the current loader and exporter; plugin version 0.34.1.
Versions and identity#
The format is "joltphysics-authoring". Version 1 uses boxes[]; version 2 uses shapes[] and optional sockets[], sensors[], raycasts[], force_points[], explosion_points[] and points[]. Physical Controls use version 3 with a separate controls[] array; Render Surfaces use version 4 with surfaces[], and ragdolls use version 5 with ragdoll:{skeleton,parts}. The current loader supports versions 1–6. Box-only configurations without helpers or controls can export as v1. configuration_id and element IDs are persistent UUIDs, never runtime handles.
Helper Keys match [a-z][a-z0-9_]{0,63}, are unique within their category and configuration, and are independent of Display Name and Blender Object Name. Socket Keys are optional for legacy compatibility; newer helper categories require them. UUIDs must be globally unique across the document.
Collision geometry#
| API / field | Contract |
|---|---|
| box: size[3] | Full local XYZ dimensions. |
| sphere: radius | Positive radius. |
| capsule: radius, height | Local Z axis; full height including caps, height > 2 × radius. |
| cylinder: radius, height | Full height between bases, local Z axis. |
| tapered_capsule: top_radius, bottom_radius, height | Both radii positive; height > 2 × max(radii). Top is +Z. |
| tapered_cylinder: top_radius, bottom_radius, height | Both authoring radii positive; full height; Top is +Z. |
| convex_hull: points[N][3] | 4–256 local points with 3D volume. One convex hull; concave recesses are filled. |
At most 64 collision children share one asset. Files must contain 1–1,048,576 bytes. Values must remain valid after float32 conversion; degenerate hulls, shear, reflections and invalid dimensions are rejected. Helper-only assets can load, but cannot create a collision body without shapes. Convex vertices carry geometry only, without UVs, materials or triangle topology.
Coordinates#
The exporter mirrors X: F = diag(-1,1,1), position_json = F × position_blender, rotation_json = F × rotation_blender × F. Convex points include positive baked scale and the same mirror. JSON rotations are normalized XYZW. Do not mirror them again in GML. Helpers require unit scale; use their size/radius/length fields where available.
Body creation and migration#
jolt_asset_create_body(asset, motion, [options]);Use options.position = {x,y,z}; omitted position is zero and omitted rotation is identity. The earlier five/six-argument XYZ form currently remains as temporary compatibility. New examples should use the options form. Loading needs no world; body creation requires jolt_start(). Both revalidate mutable input. Failure returns undefined with jolt_get_error(); a failed build releases partial resources.
New related workflows#
Penetration Points / JSON v6#
Version 6 adds penetration_points[]. Ragdoll remains separate version 5. The exporter selects a version based on contained elements; not every file must be version 6. Loading does not automatically activate helpers.