babylon-box3d 0.1.0 → 0.2.0

package/{src → wasm}/box3d_shim.c

@@ -92,10 +92,15 @@ typedef struct bxBody
 	b3BodyId id;
 	int world;
 	int alive;
+	// begin/end touch events and hit events on this body's shapes (Babylon's COLLISION_STARTED/FINISHED and CONTINUED)
 	int contactEvents;
+	int hitEvents;
 	int shapeDesc;
 	b3ShapeId* shapes;
+	// the description each shape came from, and the description owning its geometry: the same, except for a mesh in a
+	// container, where a transformed copy of the mesh is baked for this body (see bxInstantiate)
 	int* shapeDescs;
+	int* geomDescs;
 	int shapeCount;
 	int shapeCapacity;
 	bxHelper* helpers;
@@ -103,6 +108,8 @@ typedef struct bxBody
 	int helperCapacity;
 } bxBody;
 
+static void bxReleaseBodyShapes( bxBody* body, int destroyShapes );
+
 static bxBody* s_bodies;
 static int s_bodyCount;
 static int s_bodyCapacity;
@@ -162,6 +169,8 @@ typedef struct bxJoint
 {
 	b3JointId id;
 	int alive;
+	// spherical motor target as a relative angular velocity in joint frame A, converted to world space every step
+	b3Vec3 motorVelocity;
 } bxJoint;
 
 static bxJoint* s_joints;
@@ -210,10 +219,23 @@ static int bxAllocJoint( void )
 	return bxAllocSlot( (void**)&s_joints, sizeof( bxJoint ), &s_jointCount, &s_jointCapacity, &s_freeJoints, &s_freeJointCount );
 }
 
+/// Slot lookups that failed on a non zero slot. Every entry point returns quietly when it does not recognize a slot,
+/// which is the right thing during teardown but hides the two ways this can go wrong for real: a body used after it
+/// was destroyed, and a box3d.js loader paired with a box3d.wasm from a different build, where the exports line up
+/// with the wrong functions. The plugin reads this and says so once.
+static int s_rejectedSlots;
+
+/// Rejected slot lookups since the module was created. Slot 0 means "none" and is not counted.
+BX_EXPORT int bx_GetRejectedSlotCount( void )
+{
+	return s_rejectedSlots;
+}
+
 static bxBody* bxGetBody( int slot )
 {
 	if ( slot <= 0 || slot >= s_bodyCount || s_bodies[slot].alive == 0 )
 	{
+		s_rejectedSlots += slot > 0 ? 1 : 0;
 		return NULL;
 	}
 	return s_bodies + slot;
@@ -223,6 +245,7 @@ static bxShapeDesc* bxGetDesc( int slot )
 {
 	if ( slot <= 0 || slot >= s_descCount || s_descs[slot].alive == 0 )
 	{
+		s_rejectedSlots += slot > 0 ? 1 : 0;
 		return NULL;
 	}
 	return s_descs + slot;
@@ -246,9 +269,12 @@ static b3WorldId bxGetWorld( int slot )
 {
 	if ( slot <= 0 || slot > BX_MAX_WORLDS )
 	{
+		s_rejectedSlots += slot > 0 ? 1 : 0;
 		return b3_nullWorldId;
 	}
-	return s_worlds[slot - 1];
+	b3WorldId world = s_worlds[slot - 1];
+	s_rejectedSlots += B3_IS_NULL( world ) ? 1 : 0;
+	return world;
 }
 
 static int bxBodySlotFromId( b3BodyId bodyId )
@@ -374,8 +400,12 @@ BX_EXPORT void bx_DestroyWorld( int w )
 	{
 		if ( s_bodies[i].alive && s_bodies[i].world == w )
 		{
+			// the world is gone, so the shapes are too, but their geometry still has to be released: mesh and height
+			// field descriptions are reference counted and a mesh baked for this body is owned by it
+			bxReleaseBodyShapes( s_bodies + i, 0 );
 			free( s_bodies[i].shapes );
 			free( s_bodies[i].shapeDescs );
+			free( s_bodies[i].geomDescs );
 			free( s_bodies[i].helpers );
 			memset( s_bodies + i, 0, sizeof( bxBody ) );
 			s_freeBodies[s_freeBodyCount++] = i;
@@ -466,6 +496,14 @@ BX_EXPORT int bx_World_GetAwakeBodyCount( int w )
 	return B3_IS_NON_NULL( worldId ) ? b3World_GetAwakeBodyCount( worldId ) : 0;
 }
 
+/// Number of joint force/torque threshold events from the last step. The plugin does not consume them; with the
+/// default thresholds (FLT_MAX) this stays 0.
+BX_EXPORT int bx_World_GetJointEventCount( int w )
+{
+	b3WorldId worldId = bxGetWorld( w );
+	return B3_IS_NON_NULL( worldId ) ? b3World_GetJointEvents( worldId ).count : 0;
+}
+
 /// scratch: [bodyCount, shapeCount, contactCount, jointCount, islandCount, stepMs, collideMs, solveMs]
 BX_EXPORT void bx_World_GetStats( int w )
 {
@@ -551,7 +589,46 @@ BX_EXPORT int bx_World_GetMoveEvents( int w )
 	return count;
 }
 
-/// Each record: [kind (0 begin, 1 end, 2 hit), shapeDescA, shapeDescB, bodyA, bodyB, px, py, pz, nx, ny, nz, approachSpeed]
+/// Writes the contact point, normal (from shape A to shape B) and the total normal impulse of a begin touch event,
+/// taken from the contact's first manifold. Havok reports these on collision started events too.
+static void bxWriteBeginTouchData( float* out, b3ContactId contactId, b3ShapeId shapeIdA )
+{
+	memset( out, 0, 7 * sizeof( float ) );
+	if ( b3Contact_IsValid( contactId ) == false )
+	{
+		return;
+	}
+	b3ContactData data = b3Contact_GetData( contactId );
+	if ( data.manifoldCount <= 0 || data.manifolds[0].pointCount <= 0 )
+	{
+		return;
+	}
+	const b3Manifold* manifold = data.manifolds + 0;
+	// manifold anchors are relative to the center of mass of the contact's body A, which may be the event's shape B
+	int flipped = B3_ID_EQUALS( data.shapeIdA, shapeIdA ) == false;
+	b3Pos center = b3Body_GetWorldCenter( b3Shape_GetBody( data.shapeIdA ) );
+	b3Vec3 anchor = b3Vec3_zero;
+	float impulse = 0.0f;
+	for ( int i = 0; i < manifold->pointCount; ++i )
+	{
+		anchor = b3Add( anchor, manifold->points[i].anchorA );
+		impulse += manifold->points[i].totalNormalImpulse;
+	}
+	anchor = b3MulSV( 1.0f / (float)manifold->pointCount, anchor );
+	b3Pos point = b3OffsetPos( center, anchor );
+	b3Vec3 normal = flipped ? b3Neg( manifold->normal ) : manifold->normal;
+	out[0] = point.x;
+	out[1] = point.y;
+	out[2] = point.z;
+	out[3] = normal.x;
+	out[4] = normal.y;
+	out[5] = normal.z;
+	out[6] = impulse;
+}
+
+/// Each record: [kind (0 begin, 1 end, 2 hit), shapeDescA, shapeDescB, bodyA, bodyB, px, py, pz, nx, ny, nz, value]
+/// Begin events carry the contact point, normal and the total normal impulse of the step, hit events the point, normal
+/// and approach speed, end events nothing.
 BX_EXPORT int bx_World_GetContactEvents( int w )
 {
 	b3WorldId worldId = bxGetWorld( w );
@@ -580,7 +657,7 @@ BX_EXPORT int bx_World_GetContactEvents( int w )
 		out[2] = (float)bxDescSlotFromShape( e->shapeIdB );
 		out[3] = (float)bodyA;
 		out[4] = (float)bodyB;
-		memset( out + 5, 0, 7 * sizeof( float ) );
+		bxWriteBeginTouchData( out + 5, e->contactId, e->shapeIdA );
 		out += BX_CONTACT_EVENT_STRIDE;
 		count += 1;
 	}
@@ -722,6 +799,9 @@ static void bxDestroyHelpers( bxBody* body )
 	body->helperCount = 0;
 }
 
+static void bxDescRelease( int slot );
+BX_EXPORT void bx_ShapeDesc_Destroy( int slot );
+
 static void bxReleaseBodyShapes( bxBody* body, int destroyShapes )
 {
 	if ( destroyShapes )
@@ -730,15 +810,17 @@ static void bxReleaseBodyShapes( bxBody* body, int destroyShapes )
 	}
 	for ( int i = 0; i < body->shapeCount; ++i )
 	{
-		bxShapeDesc* desc = bxGetDesc( body->shapeDescs[i] );
-		if ( desc != NULL && ( desc->kind == bx_meshDesc || desc->kind == bx_heightFieldDesc ) )
-		{
-			desc->refCount -= 1;
-		}
 		if ( destroyShapes && b3Shape_IsValid( body->shapes[i] ) )
 		{
 			b3DestroyShape( body->shapes[i], false );
 		}
+		int geomSlot = body->geomDescs[i];
+		if ( geomSlot != body->shapeDescs[i] )
+		{
+			// a mesh baked for this body alone, nothing else refers to it
+			bx_ShapeDesc_Destroy( geomSlot );
+		}
+		bxDescRelease( geomSlot );
 	}
 	body->shapeCount = 0;
 }
@@ -750,15 +832,16 @@ BX_EXPORT void bx_DestroyBody( int slot )
 	{
 		return;
 	}
-	// b3DestroyBody destroys attached shapes and joints
+	// b3DestroyBody destroys attached shapes and joints; free the geometry only once no shape can refer to it
 	bxDestroyHelpers( body );
-	bxReleaseBodyShapes( body, 0 );
 	if ( b3Body_IsValid( body->id ) )
 	{
 		b3DestroyBody( body->id );
 	}
+	bxReleaseBodyShapes( body, 0 );
 	free( body->shapes );
 	free( body->shapeDescs );
+	free( body->geomDescs );
 	free( body->helpers );
 	memset( body, 0, sizeof( bxBody ) );
 	s_freeBodies[s_freeBodyCount++] = slot;
@@ -966,7 +1049,67 @@ BX_EXPORT void bx_Body_GetAABB( int slot )
 	bxWriteVec3( 3, aabb.upperBound );
 }
 
-/// scratch: [mass, cx, cy, cz, ixx, iyy, izz]
+/// Mass data the body's shapes would give it, whatever its type. Box3D keeps mass 0 on static and kinematic bodies,
+/// while Havok reports the shape mass for every body, so the plugin uses this for its mass property getters.
+/// scratch: [mass, cx, cy, cz, ixx, iyy, izz, ixy, ixz, iyz]
+BX_EXPORT void bx_Body_ComputeShapeMassData( int slot )
+{
+	memset( s_scratch, 0, 10 * sizeof( float ) );
+	bxBody* body = bxGetBody( slot );
+	if ( body == NULL || b3Body_IsValid( body->id ) == false )
+	{
+		return;
+	}
+	float mass = 0.0f;
+	b3Vec3 center = b3Vec3_zero;
+	for ( int i = 0; i < body->shapeCount; ++i )
+	{
+		if ( b3Shape_IsValid( body->shapes[i] ) == false )
+		{
+			continue;
+		}
+		b3MassData md = b3Shape_ComputeMassData( body->shapes[i] );
+		mass += md.mass;
+		center = b3MulAdd( center, md.mass, md.center );
+	}
+	if ( mass <= 0.0f )
+	{
+		return;
+	}
+	center = b3MulSV( 1.0f / mass, center );
+	// parallel axis theorem: shift each shape's inertia to the combined center of mass
+	b3Matrix3 inertia = b3Mat3_zero;
+	for ( int i = 0; i < body->shapeCount; ++i )
+	{
+		if ( b3Shape_IsValid( body->shapes[i] ) == false )
+		{
+			continue;
+		}
+		b3MassData md = b3Shape_ComputeMassData( body->shapes[i] );
+		b3Vec3 d = b3Sub( md.center, center );
+		float dd = b3Dot( d, d );
+		inertia = b3AddMM( inertia, md.inertia );
+		inertia.cx.x += md.mass * ( dd - d.x * d.x );
+		inertia.cy.y += md.mass * ( dd - d.y * d.y );
+		inertia.cz.z += md.mass * ( dd - d.z * d.z );
+		inertia.cy.x -= md.mass * d.x * d.y;
+		inertia.cx.y -= md.mass * d.x * d.y;
+		inertia.cz.x -= md.mass * d.x * d.z;
+		inertia.cx.z -= md.mass * d.x * d.z;
+		inertia.cz.y -= md.mass * d.y * d.z;
+		inertia.cy.z -= md.mass * d.y * d.z;
+	}
+	s_scratch[0] = mass;
+	bxWriteVec3( 1, center );
+	s_scratch[4] = inertia.cx.x;
+	s_scratch[5] = inertia.cy.y;
+	s_scratch[6] = inertia.cz.z;
+	s_scratch[7] = inertia.cy.x;
+	s_scratch[8] = inertia.cz.x;
+	s_scratch[9] = inertia.cz.y;
+}
+
+/// scratch: [mass, cx, cy, cz, ixx, iyy, izz, ixy, ixz, iyz], the inertia tensor about the center of mass
 BX_EXPORT void bx_Body_GetMassData( int slot )
 {
 	BX_BODY( slot );
@@ -976,21 +1119,43 @@ BX_EXPORT void bx_Body_GetMassData( int slot )
 	s_scratch[4] = md.inertia.cx.x;
 	s_scratch[5] = md.inertia.cy.y;
 	s_scratch[6] = md.inertia.cz.z;
+	s_scratch[7] = md.inertia.cy.x;
+	s_scratch[8] = md.inertia.cz.x;
+	s_scratch[9] = md.inertia.cz.y;
 }
 
-BX_EXPORT void bx_Body_SetMassData( int slot, float mass, float cx, float cy, float cz, float ixx, float iyy, float izz )
+/// Full symmetric inertia tensor, needed for Babylon mass properties with an inertia orientation.
+BX_EXPORT void bx_Body_SetMassDataFull( int slot, float mass, float cx, float cy, float cz, float ixx, float iyy, float izz,
+										float ixy, float ixz, float iyz )
 {
 	BX_BODY( slot );
 	b3MassData md;
 	md.mass = mass;
 	md.center = bxVec3( cx, cy, cz );
-	md.inertia = b3Mat3_zero;
-	md.inertia.cx.x = ixx;
-	md.inertia.cy.y = iyy;
-	md.inertia.cz.z = izz;
+	md.inertia.cx = bxVec3( ixx, ixy, ixz );
+	md.inertia.cy = bxVec3( ixy, iyy, iyz );
+	md.inertia.cz = bxVec3( ixz, iyz, izz );
 	b3Body_SetMassData( body->id, md );
 }
 
+BX_EXPORT void bx_Body_SetMassData( int slot, float mass, float cx, float cy, float cz, float ixx, float iyy, float izz )
+{
+	bx_Body_SetMassDataFull( slot, mass, cx, cy, cz, ixx, iyy, izz, 0.0f, 0.0f, 0.0f );
+}
+
+/// scratch: [lx, ly, lz, ax, ay, az], 1 where the motion is locked
+BX_EXPORT void bx_Body_GetMotionLocks( int slot )
+{
+	BX_BODY( slot );
+	b3MotionLocks locks = b3Body_GetMotionLocks( body->id );
+	s_scratch[0] = locks.linearX ? 1.0f : 0.0f;
+	s_scratch[1] = locks.linearY ? 1.0f : 0.0f;
+	s_scratch[2] = locks.linearZ ? 1.0f : 0.0f;
+	s_scratch[3] = locks.angularX ? 1.0f : 0.0f;
+	s_scratch[4] = locks.angularY ? 1.0f : 0.0f;
+	s_scratch[5] = locks.angularZ ? 1.0f : 0.0f;
+}
+
 BX_EXPORT void bx_Body_ApplyMassFromShapes( int slot )
 {
 	BX_BODY( slot );
@@ -1003,20 +1168,34 @@ BX_EXPORT int bx_Body_GetShapeCount( int slot )
 	return body->shapeCount;
 }
 
-BX_EXPORT void bx_Body_EnableContactEvents( int slot, int flag )
+/// Begin/end touch events and hit events are enabled separately so a body only pays for the events it asked for.
+BX_EXPORT void bx_Body_SetEventFlags( int slot, int contactEvents, int hitEvents )
 {
 	BX_BODY( slot );
-	body->contactEvents = flag != 0;
+	body->contactEvents = contactEvents != 0;
+	body->hitEvents = hitEvents != 0;
 	for ( int i = 0; i < body->shapeCount; ++i )
 	{
 		if ( b3Shape_IsValid( body->shapes[i] ) )
 		{
-			b3Shape_EnableContactEvents( body->shapes[i], flag != 0 );
-			b3Shape_EnableHitEvents( body->shapes[i], flag != 0 );
+			b3Shape_EnableContactEvents( body->shapes[i], body->contactEvents != 0 );
+			b3Shape_EnableHitEvents( body->shapes[i], body->hitEvents != 0 );
 		}
 	}
 }
 
+/// Bit 1: begin/end touch events, bit 2: hit events.
+BX_EXPORT int bx_Body_GetEventFlags( int slot )
+{
+	BX_BODY_RET( slot, 0 );
+	return ( body->contactEvents ? 1 : 0 ) | ( body->hitEvents ? 2 : 0 );
+}
+
+BX_EXPORT void bx_Body_EnableContactEvents( int slot, int flag )
+{
+	bx_Body_SetEventFlags( slot, flag, flag );
+}
+
 // ---------------------------------------------------------------------------------------------
 // Shape descriptions
 // ---------------------------------------------------------------------------------------------
@@ -1133,8 +1312,10 @@ BX_EXPORT int bx_ShapeDesc_CreateMesh( const float* vertices, int vertexCount, c
 }
 
 /// heights: countX * countZ floats indexed [z * countX + x]
-BX_EXPORT int bx_ShapeDesc_CreateHeightField( const float* heights, int countX, int countZ, float sx, float sy, float sz,
-											  int clockwise, float ox, float oy, float oz )
+/// materials: (countX - 1) * (countZ - 1) cell material indices indexed [z * (countX - 1) + x], or NULL for every cell 0.
+/// A cell of B3_HEIGHT_FIELD_HOLE (255) is a hole: nothing collides with it and rays pass through. Box3D copies them.
+BX_EXPORT int bx_ShapeDesc_CreateHeightField( const float* heights, const unsigned char* materials, int countX, int countZ,
+											  float sx, float sy, float sz, int clockwise, float ox, float oy, float oz )
 {
 	float minHeight = heights[0];
 	float maxHeight = heights[0];
@@ -1155,6 +1336,7 @@ BX_EXPORT int bx_ShapeDesc_CreateHeightField( const float* heights, int countX,
 	}
 	b3HeightFieldDef def = { 0 };
 	def.heights = (float*)heights;
+	def.materialIndices = (uint8_t*)materials;
 	def.countX = countX;
 	def.countZ = countZ;
 	def.scale = bxVec3( sx, sy, sz );
@@ -1473,28 +1655,106 @@ static void bxDescRelease( int slot )
 // Shape instantiation on bodies
 // ---------------------------------------------------------------------------------------------
 
-static void bxBodyPushShape( bxBody* body, b3ShapeId shapeId, int descSlot )
+// Counts every box3d shape the shim has created. Rebuilding a shape description on its bodies is the expensive path,
+// so this makes it observable (bx_GetShapeBuildCount).
+static int s_shapeBuildCount;
+
+BX_EXPORT int bx_GetShapeBuildCount( void )
+{
+	return s_shapeBuildCount;
+}
+
+/// Live shape descriptions, including the mesh copies baked for container children. Used to spot leaks.
+BX_EXPORT int bx_GetShapeDescCount( void )
+{
+	int count = 0;
+	for ( int i = 1; i < s_descCount; ++i )
+	{
+		if ( s_descs[i].alive != 0 || s_descs[i].refCount > 0 )
+		{
+			count += 1;
+		}
+	}
+	return count;
+}
+
+/// descSlot is the description the shape belongs to, geomSlot the one owning the geometry it was built from (the same,
+/// unless a transformed mesh copy was baked for this body).
+static void bxBodyPushShape( bxBody* body, b3ShapeId shapeId, int descSlot, int geomSlot )
 {
 	if ( B3_IS_NULL( shapeId ) )
 	{
 		return;
 	}
+	s_shapeBuildCount += 1;
 	if ( body->shapeCount >= body->shapeCapacity )
 	{
 		int capacity = body->shapeCapacity == 0 ? 4 : body->shapeCapacity * 2;
 		body->shapes = (b3ShapeId*)realloc( body->shapes, (size_t)capacity * sizeof( b3ShapeId ) );
 		body->shapeDescs = (int*)realloc( body->shapeDescs, (size_t)capacity * sizeof( int ) );
+		body->geomDescs = (int*)realloc( body->geomDescs, (size_t)capacity * sizeof( int ) );
 		body->shapeCapacity = capacity;
 	}
 	b3Shape_SetUserData( shapeId, (void*)(intptr_t)descSlot );
 	body->shapes[body->shapeCount] = shapeId;
 	body->shapeDescs[body->shapeCount] = descSlot;
+	body->geomDescs[body->shapeCount] = geomSlot;
 	body->shapeCount += 1;
-	bxShapeDesc* desc = bxGetDesc( descSlot );
-	if ( desc != NULL && ( desc->kind == bx_meshDesc || desc->kind == bx_heightFieldDesc ) )
+	bxShapeDesc* geom = bxGetDesc( geomSlot );
+	if ( geom != NULL && ( geom->kind == bx_meshDesc || geom->kind == bx_heightFieldDesc ) )
+	{
+		geom->refCount += 1;
+	}
+}
+
+/// Box3D mesh shapes have no local transform, so a mesh inside a container is baked into a private transformed copy of
+/// the mesh data. Returns a new description owning that copy, or 0.
+static int bxBakeTransformedMesh( const bxShapeDesc* source, b3Transform xf, b3Vec3 scale )
+{
+	const b3Vec3* vertices = b3GetMeshVertices( source->mesh );
+	const b3MeshTriangle* triangles = b3GetMeshTriangles( source->mesh );
+	int vertexCount = source->mesh->vertexCount;
+	int triangleCount = source->mesh->triangleCount;
+	if ( vertices == NULL || triangles == NULL || vertexCount < 3 || triangleCount < 1 )
+	{
+		return 0;
+	}
+	b3Vec3* baked = (b3Vec3*)malloc( (size_t)vertexCount * sizeof( b3Vec3 ) );
+	int32_t* indices = (int32_t*)malloc( (size_t)triangleCount * 3 * sizeof( int32_t ) );
+	if ( baked == NULL || indices == NULL )
+	{
+		free( baked );
+		free( indices );
+		return 0;
+	}
+	for ( int i = 0; i < vertexCount; ++i )
+	{
+		baked[i] = b3Add( xf.p, b3RotateVector( xf.q, bxMulScale( vertices[i], scale ) ) );
+	}
+	// a mirroring scale flips the winding, so swap two indices to keep the triangles facing outwards
+	int mirrored = scale.x * scale.y * scale.z < 0.0f;
+	for ( int i = 0; i < triangleCount; ++i )
 	{
-		desc->refCount += 1;
+		indices[3 * i + 0] = triangles[i].index1;
+		indices[3 * i + 1] = mirrored ? triangles[i].index3 : triangles[i].index2;
+		indices[3 * i + 2] = mirrored ? triangles[i].index2 : triangles[i].index3;
 	}
+	b3MeshDef def = { 0 };
+	def.vertices = baked;
+	def.vertexCount = vertexCount;
+	def.indices = indices;
+	def.triangleCount = triangleCount;
+	def.identifyEdges = true;
+	b3MeshData* mesh = b3CreateMesh( &def, NULL, 0 );
+	free( baked );
+	free( indices );
+	if ( mesh == NULL )
+	{
+		return 0;
+	}
+	int slot = bxNewDesc( bx_meshDesc );
+	s_descs[slot].mesh = mesh;
+	return slot;
 }
 
 static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 scale, int depth )
@@ -1517,8 +1777,9 @@ static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 sc
 	// Visitors must opt in to be seen by sensors. Babylon triggers see everything.
 	def.enableSensorEvents = true;
 	def.enableContactEvents = body->contactEvents != 0;
-	def.enableHitEvents = body->contactEvents != 0;
-	def.updateBodyMass = true;
+	def.enableHitEvents = body->hitEvents != 0;
+	// the caller applies the mass once after instantiating every shape of the description
+	def.updateBodyMass = false;
 
 	switch ( desc->kind )
 	{
@@ -1527,7 +1788,7 @@ static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 sc
 			b3Sphere s = desc->sphere;
 			s.center = b3Add( xf.p, b3RotateVector( xf.q, bxMulScale( s.center, scale ) ) );
 			s.radius *= bxMaxAbsScale( scale );
-			bxBodyPushShape( body, b3CreateSphereShape( body->id, &def, &s ), descSlot );
+			bxBodyPushShape( body, b3CreateSphereShape( body->id, &def, &s ), descSlot, descSlot );
 			break;
 		}
 		case bx_capsuleDesc:
@@ -1536,26 +1797,47 @@ static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 sc
 			c.center1 = b3Add( xf.p, b3RotateVector( xf.q, bxMulScale( c.center1, scale ) ) );
 			c.center2 = b3Add( xf.p, b3RotateVector( xf.q, bxMulScale( c.center2, scale ) ) );
 			c.radius *= bxMaxAbsScale( scale );
-			bxBodyPushShape( body, b3CreateCapsuleShape( body->id, &def, &c ), descSlot );
+			bxBodyPushShape( body, b3CreateCapsuleShape( body->id, &def, &c ), descSlot, descSlot );
 			break;
 		}
 		case bx_hullDesc:
 		{
 			if ( bxIsIdentity( xf, scale ) )
 			{
-				bxBodyPushShape( body, b3CreateHullShape( body->id, &def, desc->hull ), descSlot );
+				bxBodyPushShape( body, b3CreateHullShape( body->id, &def, desc->hull ), descSlot, descSlot );
 			}
 			else
 			{
-				bxBodyPushShape( body, b3CreateTransformedHullShape( body->id, &def, desc->hull, xf, scale ), descSlot );
+				bxBodyPushShape( body, b3CreateTransformedHullShape( body->id, &def, desc->hull, xf, scale ), descSlot, descSlot );
 			}
 			break;
 		}
 		case bx_meshDesc:
 		{
-			// Mesh shapes have no local transform in box3d. The plugin bakes any container offset
-			// into the vertices at creation time, so only the scale is applied here.
-			bxBodyPushShape( body, b3CreateMeshShape( body->id, &def, desc->mesh, bxMulScale( desc->meshScale, scale ) ), descSlot );
+			// Mesh shapes have no local transform in box3d, only a scale. A mesh that sits inside a container with an
+			// offset or a rotation gets a transformed copy of its data baked for this body.
+			b3Vec3 meshScale = bxMulScale( desc->meshScale, scale );
+			if ( bxIsIdentity( xf, b3Vec3_one ) )
+			{
+				bxBodyPushShape( body, b3CreateMeshShape( body->id, &def, desc->mesh, meshScale ), descSlot, descSlot );
+			}
+			else
+			{
+				int baked = bxBakeTransformedMesh( desc, xf, meshScale );
+				if ( baked != 0 )
+				{
+					b3ShapeId shapeId = b3CreateMeshShape( body->id, &def, s_descs[baked].mesh, b3Vec3_one );
+					if ( B3_IS_NON_NULL( shapeId ) )
+					{
+						bxBodyPushShape( body, shapeId, descSlot, baked );
+					}
+					else
+					{
+						// nothing recorded the baked copy, so free it here instead of leaking the slot and its mesh
+						bx_ShapeDesc_Destroy( baked );
+					}
+				}
+			}
 			break;
 		}
 		case bx_heightFieldDesc:
@@ -1564,7 +1846,7 @@ static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 sc
 			b3Transform local = b3MulTransforms( xf, offset );
 			if ( bxIsIdentity( local, b3Vec3_one ) )
 			{
-				bxBodyPushShape( body, b3CreateHeightFieldShape( body->id, &def, desc->heightField ), descSlot );
+				bxBodyPushShape( body, b3CreateHeightFieldShape( body->id, &def, desc->heightField ), descSlot, descSlot );
 			}
 			else
 			{
@@ -1585,15 +1867,22 @@ static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 sc
 				body->helpers[body->helperCount].id = helperId;
 				body->helpers[body->helperCount].local = local;
 				body->helperCount += 1;
-				bxBodyPushShape( body, b3CreateHeightFieldShape( helperId, &def, desc->heightField ), descSlot );
+				bxBodyPushShape( body, b3CreateHeightFieldShape( helperId, &def, desc->heightField ), descSlot, descSlot );
 			}
 			break;
 		}
 		case bx_containerDesc:
 		{
-			for ( int i = 0; i < desc->childCount; ++i )
+			// Instantiating a child can bake a mesh, which allocates a description and may move the description table,
+			// so `desc` must be re-fetched every iteration instead of being held across the recursion.
+			for ( int i = 0;; ++i )
 			{
-				bxChild child = desc->children[i];
+				bxShapeDesc* container = bxGetDesc( descSlot );
+				if ( container == NULL || i >= container->childCount )
+				{
+					break;
+				}
+				bxChild child = container->children[i];
 				bxInstantiate( body, child.desc, b3MulTransforms( xf, child.transform ), bxMulScale( scale, child.scale ), depth + 1 );
 			}
 			break;
@@ -1607,22 +1896,68 @@ static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 sc
 BX_EXPORT void bx_Body_SetShape( int slot, int descSlot )
 {
 	BX_BODY( slot );
-	bxDestroyHelpers( body );
+	bxReleaseBodyShapes( body, 1 );
+	body->shapeDesc = descSlot;
+	if ( descSlot != 0 )
+	{
+		bxInstantiate( body, descSlot, b3Transform_identity, b3Vec3_one, 0 );
+	}
+	b3Body_ApplyMassFromShapes( body->id );
+}
+
+/// Properties that can be changed on live shapes, see bx_Body_SyncShapeDesc.
+typedef enum bxSyncFlags
+{
+	bx_syncFilter = 1,
+	bx_syncMaterial = 2,
+	bx_syncDensity = 4,
+} bxSyncFlags;
+
+/// Applies changed description properties to the shapes this body already has, instead of rebuilding them. Rebuilding
+/// loses contacts and re-applies the mass, and Babylon games change filters on live jointed bodies often.
+BX_EXPORT void bx_Body_SyncShapeDesc( int slot, int descSlot, int what )
+{
+	BX_BODY( slot );
+	bxShapeDesc* desc = bxGetDesc( descSlot );
+	if ( desc == NULL )
+	{
+		return;
+	}
+	int massChanged = 0;
 	for ( int i = 0; i < body->shapeCount; ++i )
 	{
-		if ( b3Shape_IsValid( body->shapes[i] ) )
+		if ( body->shapeDescs[i] != descSlot || b3Shape_IsValid( body->shapes[i] ) == false )
 		{
-			b3DestroyShape( body->shapes[i], false );
+			continue;
+		}
+		b3ShapeId shapeId = body->shapes[i];
+		if ( what & bx_syncFilter )
+		{
+			b3Filter filter = b3Shape_GetFilter( shapeId );
+			filter.categoryBits = desc->categoryBits;
+			filter.maskBits = desc->maskBits;
+			filter.groupIndex = desc->groupIndex;
+			// true: contacts that the new filter forbids are dropped and new pairs are found on the next step
+			b3Shape_SetFilter( shapeId, filter, true );
+		}
+		if ( what & bx_syncMaterial )
+		{
+			b3SurfaceMaterial material = b3Shape_GetSurfaceMaterial( shapeId );
+			material.friction = desc->friction;
+			material.restitution = desc->restitution;
+			material.rollingResistance = desc->rollingResistance;
+			b3Shape_SetSurfaceMaterial( shapeId, material );
+		}
+		if ( what & bx_syncDensity )
+		{
+			b3Shape_SetDensity( shapeId, desc->density, false );
+			massChanged = 1;
 		}
-		bxDescRelease( body->shapeDescs[i] );
 	}
-	body->shapeCount = 0;
-	body->shapeDesc = descSlot;
-	if ( descSlot != 0 )
+	if ( massChanged )
 	{
-		bxInstantiate( body, descSlot, b3Transform_identity, b3Vec3_one, 0 );
+		b3Body_ApplyMassFromShapes( body->id );
 	}
-	b3Body_ApplyMassFromShapes( body->id );
 }
 
 BX_EXPORT int bx_Body_GetShapeDesc( int slot )
@@ -1777,6 +2112,19 @@ typedef enum bxJointType
 /// steeringHertz, steeringDamping, targetSteering, maxSteeringTorque, enableSteeringLimit, lowerSteering, upperSteering.
 /// Parallel joints read [hertz, dampingRatio, maxTorque] from scratch[14..].
 /// Returns the joint slot, 0 on failure.
+// Fills the shared part of a joint definition. The definition must come from its b3Default*JointDef function so every
+// field not set here keeps Box3D's default. In particular the force and torque thresholds default to FLT_MAX: a zeroed
+// definition sets them to 0, which makes Box3D compute reaction forces and emit a joint event for every awake joint
+// on every step.
+static void bxFillJointBase( b3JointDef* base, bxBody* bodyA, bxBody* bodyB, int collideConnected )
+{
+	base->bodyIdA = bodyA->id;
+	base->bodyIdB = bodyB->id;
+	base->localFrameA = bxTransform( s_scratch[0], s_scratch[1], s_scratch[2], s_scratch[3], s_scratch[4], s_scratch[5], s_scratch[6] );
+	base->localFrameB = bxTransform( s_scratch[7], s_scratch[8], s_scratch[9], s_scratch[10], s_scratch[11], s_scratch[12], s_scratch[13] );
+	base->collideConnected = collideConnected != 0;
+}
+
 BX_EXPORT int bx_CreateJoint( int w, int type, int bodyASlot, int bodyBSlot, int collideConnected, float param )
 {
 	b3WorldId worldId = bxGetWorld( w );
@@ -1787,68 +2135,41 @@ BX_EXPORT int bx_CreateJoint( int w, int type, int bodyASlot, int bodyBSlot, int
 		return 0;
 	}
 
-	b3JointDef base = { 0 };
-	base.bodyIdA = bodyA->id;
-	base.bodyIdB = bodyB->id;
-	base.localFrameA = bxTransform( s_scratch[0], s_scratch[1], s_scratch[2], s_scratch[3], s_scratch[4], s_scratch[5], s_scratch[6] );
-	base.localFrameB = bxTransform( s_scratch[7], s_scratch[8], s_scratch[9], s_scratch[10], s_scratch[11], s_scratch[12], s_scratch[13] );
-	base.collideConnected = collideConnected != 0;
-
 	b3JointId jointId = b3_nullJointId;
 	switch ( type )
 	{
 		case bx_weldJoint:
 		{
 			b3WeldJointDef def = b3DefaultWeldJointDef();
-			base.constraintHertz = def.base.constraintHertz;
-			base.constraintDampingRatio = def.base.constraintDampingRatio;
-			base.drawScale = def.base.drawScale;
-			base.internalValue = def.base.internalValue;
-			def.base = base;
+			bxFillJointBase( &def.base, bodyA, bodyB, collideConnected );
 			jointId = b3CreateWeldJoint( worldId, &def );
 			break;
 		}
 		case bx_sphericalJoint:
 		{
 			b3SphericalJointDef def = b3DefaultSphericalJointDef();
-			base.constraintHertz = def.base.constraintHertz;
-			base.constraintDampingRatio = def.base.constraintDampingRatio;
-			base.drawScale = def.base.drawScale;
-			base.internalValue = def.base.internalValue;
-			def.base = base;
+			bxFillJointBase( &def.base, bodyA, bodyB, collideConnected );
 			jointId = b3CreateSphericalJoint( worldId, &def );
 			break;
 		}
 		case bx_revoluteJoint:
 		{
 			b3RevoluteJointDef def = b3DefaultRevoluteJointDef();
-			base.constraintHertz = def.base.constraintHertz;
-			base.constraintDampingRatio = def.base.constraintDampingRatio;
-			base.drawScale = def.base.drawScale;
-			base.internalValue = def.base.internalValue;
-			def.base = base;
+			bxFillJointBase( &def.base, bodyA, bodyB, collideConnected );
 			jointId = b3CreateRevoluteJoint( worldId, &def );
 			break;
 		}
 		case bx_prismaticJoint:
 		{
 			b3PrismaticJointDef def = b3DefaultPrismaticJointDef();
-			base.constraintHertz = def.base.constraintHertz;
-			base.constraintDampingRatio = def.base.constraintDampingRatio;
-			base.drawScale = def.base.drawScale;
-			base.internalValue = def.base.internalValue;
-			def.base = base;
+			bxFillJointBase( &def.base, bodyA, bodyB, collideConnected );
 			jointId = b3CreatePrismaticJoint( worldId, &def );
 			break;
 		}
 		case bx_distanceJoint:
 		{
 			b3DistanceJointDef def = b3DefaultDistanceJointDef();
-			base.constraintHertz = def.base.constraintHertz;
-			base.constraintDampingRatio = def.base.constraintDampingRatio;
-			base.drawScale = def.base.drawScale;
-			base.internalValue = def.base.internalValue;
-			def.base = base;
+			bxFillJointBase( &def.base, bodyA, bodyB, collideConnected );
 			def.length = param;
 			def.enableLimit = true;
 			def.minLength = param;
@@ -1859,11 +2180,7 @@ BX_EXPORT int bx_CreateJoint( int w, int type, int bodyASlot, int bodyBSlot, int
 		case bx_wheelJoint:
 		{
 			b3WheelJointDef def = b3DefaultWheelJointDef();
-			base.constraintHertz = def.base.constraintHertz;
-			base.constraintDampingRatio = def.base.constraintDampingRatio;
-			base.drawScale = def.base.drawScale;
-			base.internalValue = def.base.internalValue;
-			def.base = base;
+			bxFillJointBase( &def.base, bodyA, bodyB, collideConnected );
 			const float* p = s_scratch + 14;
 			def.enableSuspensionSpring = p[0] != 0.0f;
 			def.suspensionHertz = p[1];
@@ -1888,11 +2205,7 @@ BX_EXPORT int bx_CreateJoint( int w, int type, int bodyASlot, int bodyBSlot, int
 		case bx_parallelJoint:
 		{
 			b3ParallelJointDef def = b3DefaultParallelJointDef();
-			base.constraintHertz = def.base.constraintHertz;
-			base.constraintDampingRatio = def.base.constraintDampingRatio;
-			base.drawScale = def.base.drawScale;
-			base.internalValue = def.base.internalValue;
-			def.base = base;
+			bxFillJointBase( &def.base, bodyA, bodyB, collideConnected );
 			def.hertz = s_scratch[14];
 			def.dampingRatio = s_scratch[15];
 			def.maxTorque = s_scratch[16];
@@ -1902,11 +2215,7 @@ BX_EXPORT int bx_CreateJoint( int w, int type, int bodyASlot, int bodyBSlot, int
 		case bx_filterJoint:
 		{
 			b3FilterJointDef def = b3DefaultFilterJointDef();
-			base.constraintHertz = def.base.constraintHertz;
-			base.constraintDampingRatio = def.base.constraintDampingRatio;
-			base.drawScale = def.base.drawScale;
-			base.internalValue = def.base.internalValue;
-			def.base = base;
+			bxFillJointBase( &def.base, bodyA, bodyB, collideConnected );
 			jointId = b3CreateFilterJoint( worldId, &def );
 			break;
 		}
@@ -2065,6 +2374,44 @@ BX_EXPORT void bx_Joint_EnableMotor( int slot, int flag )
 	}
 }
 
+/// Spherical joints take a relative angular velocity (angularVelocityB - angularVelocityA) in WORLD space. The target
+/// is stored in joint frame A here and converted, so the motor keeps meaning the same thing as body A turns. Call
+/// bx_Joint_UpdateMotorFrame once per step for joints with a non-zero target.
+BX_EXPORT void bx_Joint_UpdateMotorFrame( int slot )
+{
+	b3JointId id = bxGetJointId( slot );
+	if ( B3_IS_NULL( id ) || b3Joint_GetType( id ) != b3_sphericalJoint )
+	{
+		return;
+	}
+	b3Quat frameA = b3MulQuat( b3Body_GetRotation( b3Joint_GetBodyA( id ) ), b3Joint_GetLocalFrameA( id ).q );
+	b3SphericalJoint_SetMotorVelocity( id, b3RotateVector( frameA, s_joints[slot].motorVelocity ) );
+}
+
+/// Enables the spherical motor with a target relative angular velocity in joint frame A (x, y, z) and a torque limit.
+BX_EXPORT void bx_Joint_SetSphericalMotor( int slot, int enable, float x, float y, float z, float maxTorque )
+{
+	b3JointId id = bxGetJointId( slot );
+	if ( B3_IS_NULL( id ) || b3Joint_GetType( id ) != b3_sphericalJoint )
+	{
+		return;
+	}
+	s_joints[slot].motorVelocity = bxVec3( x, y, z );
+	b3SphericalJoint_EnableMotor( id, enable != 0 );
+	b3SphericalJoint_SetMaxMotorTorque( id, maxTorque );
+	bx_Joint_UpdateMotorFrame( slot );
+}
+
+/// Target rotation of a spherical joint's spring: frame B relative to frame A.
+BX_EXPORT void bx_Joint_SetSphericalTarget( int slot, float qx, float qy, float qz, float qw )
+{
+	b3JointId id = bxGetJointId( slot );
+	if ( B3_IS_NON_NULL( id ) && b3Joint_GetType( id ) == b3_sphericalJoint )
+	{
+		b3SphericalJoint_SetTargetRotation( id, bxQuat( qx, qy, qz, qw ) );
+	}
+}
+
 BX_EXPORT void bx_Joint_SetMotorSpeed( int slot, float speed )
 {
 	b3JointId id = bxGetJointId( slot );
@@ -2084,7 +2431,8 @@ BX_EXPORT void bx_Joint_SetMotorSpeed( int slot, float speed )
 			b3DistanceJoint_SetMotorSpeed( id, speed );
 			break;
 		case b3_sphericalJoint:
-			b3SphericalJoint_SetMotorVelocity( id, bxVec3( 0.0f, 0.0f, speed ) );
+			// twist about the joint's own axis (frame z), not a world axis
+			bx_Joint_SetSphericalMotor( slot, 1, 0.0f, 0.0f, speed, b3SphericalJoint_GetMaxMotorTorque( id ) );
 			break;
 		default:
 			break;