box3dplugin

3D rigid bodies, joints, sensors and queries by Box3D (WebAssembly).

#Putting it in a scene

The scene's sim lists the box3d kind from #plugins/box3d/box3d.sim.ts, and the scene has one { "is": "box3d" } actor, the world row. Every kind named in world.box3d.kinds is a body, every kind named in world.box3d.joints is a joint, and so is every kind that a plugin named in its kinds mods makes. A child scene inherits world.box3d from the manager scene. Any field a setting leaves out is Box3D's own default, and names that Box3D has keep Box3D's spelling, so its manual reads straight onto the scene file.

"world": {
  "box3d": {
    "gravity": [0, -9.8, 0],
    "subStepCount": 4,
    "static": [
      { "pos": [0, -0.5, 0], "rot": [0, 0, 0, 1], "shapes": [{ "box": [50, 0.5, 50], "baseMaterial": { "friction": 0.8 } }] }
    ],
    "kinds": {
      "crate": {
        "shapes": [{ "box": [0.5, 0.5, 0.5], "density": 1, "baseMaterial": { "friction": 0.6, "restitution": 0.1 }, "enableContactEvents": true }]
      }
    },
    "joints": {
      "hinge": { "type": "revolute", "enableLimit": true, "lowerAngle": -0.5, "upperAngle": 0.5 }
    },
    "mods": { "ground": "terrain3d" },
    "chunk": { "count": 33, "cell": 4 }
  }
},
"prefabs": {
  "box3d": {},
  "crate": { "pos": [0, 5, 0], "rot": [0, 0, 0, 1], "vel": [0, 0, 0], "spin": [0, 0, 0], "awake": true }
}

A point is [x, y, z] and a rotation is a quaternion [x, y, z, w].

#Properties

Read from world.box3d. The world settings are read when the world is made, a kind's entry when each of its bodies or joints is made.

World

Body entries

A kind's entry in .kinds. Where a body is and how it moves are on its row.

Shapes

One geometry from the list below, plus any of these fields beside it.

Geometries

A hull holds at most 128 vertices and 255 half edges, so a cylinder or a cone of more than about 40 sides is refused. A box, hull, cylinder, cone or rock may also carry pos, rot and scale: it is placed, turned and stretched on its body.

Joint entries

A kind's entry in .joints. A joint row names the two bodies it joins.

#The rows

The rows are all the state a seat is sent and a rule reads and writes, so two runs of the same presses land on the same bytes. Each step, rows are pushed into Box3D, the world is stepped, and every body's and joint's row is written back. The world is made on the first step and kept for as long as the row lives.

The world row

The box3d row may carry any numeric or switch setting of the world above, subStepCount and gravity included but not capacity, static, kinds, joints, chunk or mods. The row's value is then the world's, pushed on each step it differs from the one pushed last.

A body row

A joint row

#Methods

Acts

On the box3d row. A rule calls them with w.call.

explode( x, y, z, radius, falloff, impulsePerArea, maskBits? )

Blows the world apart on the next step. Each shape within radius of the point gets an impulse for every unit of its area, less toward the edge by falloff. Only shapes whose category maskBits names are pushed, and every shape is if it is left out.

Rules

From #plugins/box3d/box3d.sim.ts. The queries ask the world as the last step left it, so the box3d row must have stepped once. They answer in row ids, with a static body as -(i + 1) and a ground chunk as 0. filter is { categoryBits?, maskBits? }.

castRayClosest( w, origin, translation, filter? ) : RayHit | undefined

The first thing a ray from origin along translation meets. A RayHit is { id, point, normal, fraction }, with fraction the share of translation travelled.

castRay( w, origin, translation, filter? ) : RayHit[]

Everything a ray meets, nearest first, one hit per shape.

castShape( w, origin, points, radius, translation, filter? ) : RayHit[]

Everything a convex shape meets as it is swept along translation, nearest first. The shape is the hull of the flat [x, y, z, …] list points about origin, rounded by radius.

overlapShape( w, origin, points, radius, filter? ) : number[]

The ids of the bodies that a convex shape at origin overlaps, sorted, each once.

overlapAABB( w, aabb, filter? ) : number[]

The ids of the bodies whose shapes' bounds overlap the box [minX, minY, minZ, maxX, maxY, maxZ], sorted, each once.

castMover( w, origin, mover, translation, filter? ) : number

For a character moved as a capsule { center1, center2, radius }: how far along translation, from 0 to 1, a capsule at origin moves before it meets something.

collideMover( w, origin, mover, filter? ) : (Plane & { id })[]

The planes of everything that a capsule at origin touches or is inside, each { id, normal, offset, point } with the id of the body it belongs to.

solvePlanes( targetDelta, planes ) : { delta, iterationCount }

The move nearest targetDelta that the planes allow. Each plane is { plane: { normal, offset }, pushLimit, push, clipVelocity }. It needs no world.

clipVector( vector, planes ) : Vec3

The velocity with the part of it that goes into the planes taken off. It needs no world.

contacts( w, row )

Every contact a body is in. Each is { a, b, with, manifolds }: the two bodies, the other body, and a list of manifolds, each with normal, twistImpulse, frictionImpulse, rollingImpulse and points.

massOf( w, row ) : { mass, center, inertia }

A body's mass, its centre of mass in its own frame, and its rotational inertia.

pointVelocity( w, row, point ) : Vec3

The velocity of a point of the world as it rides on the body.

boundsOf( w, row ) : [minX, minY, minZ, maxX, maxY, maxZ]

The bounds of a body's shapes.

counters( w )

What the world holds, as Box3D counts it, with awakeBodyCount, the number of bodies that are awake.

staticAt( world, point ) : boolean

Whether point [x, y, z] is inside one of the bodies of world.static, which is what to ask when a thing put somewhere might be in a wall. A point on a surface is not inside. It answers for a box, a sphere and a capsule; a box that carries pos, rot or scale, and every other shape, is not asked of.

outline( list, i, shape, from? ) : Vec3[][]

Shape shape of static body i of list as it lies in the world, as groups of points, for a view from above to draw. A sphere is its centre and the six points a radius off it along the axes, a capsule is its two spheres so, a box, hull, cylinder, cone or rock is its hull's vertices, each child of a compound is its own group, a mesh is one group for each triangle, and a height field is the eight corners of its bounds. from is a rule's w or a page's wire, needed for a mesh or height field read from an asset.

On the page

Through plugins.box3d.

follow( id, obj )

Makes obj, anything with position.fromArray and quaternion.fromArray as a three.js object has, follow the row with that id. After every frame the object takes the row's pos and rot. The rotation is made a unit turn again before it is drawn, because a page that runs ahead eases it as a blend of two turns. If obj has userData, userData.row is set to the id. How the body is drawn is up to the actor.

drop( id )

Stops following the row with that id.

b3

Box3D itself, exported from the sim file as b3, for its standalone geometry functions (b3ShapeDistance, b3ShapeCast, b3TimeOfImpact, b3Collide…), which need no world.

#Mods

Name them in world.box3d.mods, as { ground: "<plugin>", props: ["<plugin>", …], kinds: ["<plugin>", …] }. ground takes one plugin. props and kinds take a list, or one name, and every plugin in it is asked.

• terrain3d
  ground: ground(w, [i, j]) hands back chunk [i, j] of the ground as a static body.
• scatter3d
  props: props(w, [i, j]) hands back the fixed things that stand in chunk [i, j], each one's middle in the chunk's square, as a static body, or undefined where there are none. They are streamed with the ground.
• box3dvehicle
  kinds: the chassis, wheel and joint kinds of its cars.
• ragdoll3d
  kinds: the bone and bonejoint kinds of its ragdolls, in its physics mode.

kinds(w) hands back the kinds a plugin makes out of numbers of its own, { bodies: { kind: row => Body }, joints: { kind: row => Joint } }. Each entry is asked for when box3d makes that row's body or joint, so two rows of one kind may differ, as two wheels of one car with different sizes do. A kind that world.box3d.kinds or .joints lists takes that entry over a mod's, and of two plugins that make the same kind, the later in the list wins.

box3d gives one mod, to box3dvehicle: gravity(w), the gravity box3d's world steps with. It is the box3d row's gravity while the row carries one, else world.box3d.gravity, else Box3D's own default.

#In the guide