Coordinate System
Defines positions, directions, rotations, and units used by the public API.
JoltPhysics uses a right-handed Z-up public coordinate system. The current native mapping is intentionally an identity mapping, so public X, Y, and Z cross the Jolt bridge without an axis swap.
Axes#
| Axis | Meaning |
|---|---|
| X | Left / right |
| Y | Forward / backward |
| Z | Up / down; positive Z is up |
// Ten units above the origin.
var body = jolt_box_create_dynamic(0, 0, 10, 1, 1, 1);
// Upward world-space impulse.
body.add_impulse(0, 0, 5);Coordinate spaces#
| Value | Space |
|---|---|
| Body position and transform | World space |
| Linear and angular velocity | World space |
| Forces and impulses | World space |
| add_force_local / add_impulse_local point | Body-local point; the vector remains world-space |
| Compound child transform | Local to the compound |
| Contact position and normal | World space |
| Raycast endpoints and results | World space |
Units#
The engine does not impose a named distance unit, but consistent real-world scale produces the best results. The recommended convention is meters for distance, kilograms for mass, and seconds for time. The default gravity -9.81 on Z therefore represents approximately Earth gravity when one world unit is one meter.
Angles and rotations#
- The canonical rotation is a normalized quaternion {x,y,z,w}.
- Functions explicitly named Euler use degrees.
- Euler conversion composes q = qZ × qY × qX: public X, then Y, then Z.
- Angular velocity is radians per second, not degrees per second.
- World-space surface normals and direction vectors use the same right-handed axes.
Dimensions#
High-level primitive creators use full public dimensions. For example, jolt_box_create_dynamic(x,y,z,width,depth,height) accepts the complete size, while the low-level native Box API works with half extents. Capsule and Cylinder creators document their own full-height rules.
Example mapping from a 2D room#
// Example policy only: room X -> physics X,
// inverted room Y -> physics Z, fixed depth -> physics Y.
var physics_x = x * scale;
var physics_y = 0;
var physics_z = -y * scale;The correct mapping depends on your camera and game. Keep conversion in one helper instead of mixing screen-space and physics-space values throughout gameplay code.