PlaneHold

Planar physics: holds bodies to a plane (a plane lock for every body it covers), the way a side-on 2D or 2.5D physics game (a bridge builder, a platformer, a pinball table, a side-scrolling vehicle game) keeps everything in one plane of a 3D world. Each dynamic rigid body it covers moves along the plane and turns only about its normal, under collisions, joints, impulses and velocities set from code; each soft body it covers keeps its particles on the plane. A body is put on the plane when the hold takes it, and a body spawned later into what the hold covers is held from its first step.

Public fields:

• normal (default { 0, 0, 1 }, the XY plane of a side view) and point (default the origin): the plane, in world space.
• covers: "subtree" (default: this entity's body and every body under it; a piece torn off a soft body under it stays held), "group" (every body whose collision membership shares a bit with groups; a body with no CollisionGroup belongs to every group) or "world" (every body).
• groups (default 0xFFFFFFFF): the collision groups a "group" hold covers.
• free (default false): the hold covers its bodies with no plane, so a body or a subtree leaves a hold further out.

Disabling the component (.enabled = false, the flag every component carries) switches the hold off: the bodies it held move freely from the next step, and enabling it again holds them again.

The nearest hold wins: a subtree hold on the body or its nearest ancestor, then a group hold, then a world hold. A plane a SoftBody states for itself (plane) stands over every hold. Physics.planeHold(id) reads which plane holds a body and where that hold stands.

-- a side-view level: every body under it stays in the XY plane
level.component.add("PlaneHold", { normal = { 0, 0, 1 } })
-- every body in the world held to the plane x = 2
holder.component.add("PlaneHold", { covers = "world", normal = { 1, 0, 0 }, point = { 2, 0, 0 } })
-- one crate leaves the plane
crate.component.add("PlaneHold", { free = true })
-- build phase free, simulate phase held
level.component.get("PlaneHold").enabled = false