babylon-box3d 0.6.1 → 0.8.0

package/wasm/box3d_shim.c

@@ -50,6 +50,54 @@ BX_EXPORT int bx_GetVersion( void )
 	return v.major * 10000 + v.minor * 100 + v.revision;
 }
 
+// World positions cross the boundary in doubles. Entry points take them as doubles, and those that give one back
+// write it to s_scratchF64 (or a double buffer beside their float records) as well as to the float scratch. A build with
+// BOX3D_DOUBLE_PRECISION keeps them exact far from the origin; the default build holds floats, so there the doubles
+// are its floats widened, and the floats are what they always were.
+#define BX_SCRATCH_F64_SIZE 16
+static double s_scratchF64[BX_SCRATCH_F64_SIZE];
+
+BX_EXPORT double* bx_ScratchF64( void )
+{
+	return s_scratchF64;
+}
+
+/// 1 when this module was built with BOX3D_DOUBLE_PRECISION, so world positions are held in doubles.
+BX_EXPORT int bx_IsDoublePrecision( void )
+{
+	return b3IsDoublePrecision() ? 1 : 0;
+}
+
+typedef struct bxDoubleBuffer
+{
+	double* data;
+	int count;
+	int capacity;
+} bxDoubleBuffer;
+
+static void bxDoubleBuffer_Reserve( bxDoubleBuffer* buf, int count )
+{
+	if ( count <= buf->capacity )
+	{
+		return;
+	}
+	int capacity = buf->capacity == 0 ? 256 : buf->capacity;
+	while ( capacity < count )
+	{
+		capacity *= 2;
+	}
+	buf->data = (double*)realloc( buf->data, (size_t)capacity * sizeof( double ) );
+	buf->capacity = capacity;
+}
+
+/// A world position from three doubles: exact in a double precision build, rounded to float in the default one, as a
+/// float argument always was.
+static b3Pos bxPos( double x, double y, double z )
+{
+	b3Pos p = { x, y, z };
+	return p;
+}
+
 typedef struct bxFloatBuffer
 {
 	float* data;
@@ -106,8 +154,19 @@ typedef struct bxBody
 	bxHelper* helpers;
 	int helperCount;
 	int helperCapacity;
+	// The body's feature key: each of its shapes gets (featureKey << BX_FEATURE_INDEX_BITS) | its index in the body as
+	// Box3D's b3ShapeDef::featureKey, which orders new contacts, continuous collision and cast ties. 0 until it is set.
+	uint64_t featureKey;
+	// A clip plane (wasm/patches/0006): contact points on its positive side, where n.p + d > 0 like Babylon's clip
+	// planes, or within twice the linear slop of it, are dropped from this body's contacts with shapes whose category
+	// bits meet clipMask. Off while clipEnabled is 0.
+	int clipEnabled;
+	double clipPlane[4];
+	uint64_t clipMask;
 } bxBody;
 
+#define BX_FEATURE_INDEX_BITS 20
+
 static void bxReleaseBodyShapes( bxBody* body, int destroyShapes );
 
 static bxBody* s_bodies;
@@ -154,6 +213,10 @@ typedef struct bxShapeDesc
 	int groupIndex;
 	float rollingResistance;
 	int isSensor;
+	// Box3D's b3ShapeDef::invokeContactCreation, on by default: a static shape made with it starts in the broad phase's
+	// move buffer and looks for its own pairs on the next step. Off, it waits to be found by a moving shape. A container
+	// that has it off turns it off for every shape made from its children.
+	int invokeContactCreation;
 	bxChild* children;
 	int childCount;
 	int childCapacity;
@@ -546,6 +609,129 @@ static void bxResetTasks( void )
 // World
 // ---------------------------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------------------------
+// Clip planes (wasm/patches/0006)
+// ---------------------------------------------------------------------------------------------
+
+// Called from Box3D's workers during a step: only reads.
+static const bxBody* bxClipBody( b3ShapeId shapeId, b3ShapeId otherId )
+{
+	int slot = (int)(intptr_t)b3Body_GetUserData( b3Shape_GetBody( shapeId ) );
+	const bxBody* body = s_bodies + slot;
+	if ( slot <= 0 || slot >= s_bodyCount || body->clipEnabled == 0 )
+	{
+		return NULL;
+	}
+	return ( b3Shape_GetFilter( otherId ).categoryBits & body->clipMask ) != 0 ? body : NULL;
+}
+
+static int bxIsClipped( const bxBody* body, b3Pos point )
+{
+	if ( body == NULL )
+	{
+		return 0;
+	}
+	// A surface lying in the plane, such as the wall a portal is on, is clipped too: points within twice the linear
+	// slop in front of the plane count as past it, which covers a resting contact's point between the surfaces and the
+	// 5 mm skin mesh and height field contacts carry.
+	const double* n = body->clipPlane;
+	return n[0] * point.x + n[1] * point.y + n[2] * point.z + n[3] > -2.0 * B3_LINEAR_SLOP;
+}
+
+// Drops the points either body's clip plane clips; Box3D drops the manifolds left empty.
+static int bxClipManifolds( b3ShapeId shapeIdA, b3ShapeId shapeIdB, b3Pos originA, b3Manifold* manifolds, int manifoldCount,
+							void* context )
+{
+	(void)context;
+	const bxBody* a = bxClipBody( shapeIdA, shapeIdB );
+	const bxBody* b = bxClipBody( shapeIdB, shapeIdA );
+	if ( a == NULL && b == NULL )
+	{
+		return manifoldCount;
+	}
+	for ( int i = 0; i < manifoldCount; ++i )
+	{
+		b3Manifold* manifold = manifolds + i;
+		int kept = 0;
+		for ( int j = 0; j < manifold->pointCount; ++j )
+		{
+			// A speculative point is made while the surfaces are still apart, by up to the distance the body covers in
+			// the step against a mesh, and it lies midway between them (convex shapes) or on shape B (meshes and height
+			// fields). Either way it can sit in front of the plane while the surface it would push on lies in it, and a
+			// body falling into a portal would stop dead on the surface the portal is on. So each body also tests the
+			// point moved one separation toward the other shape, along the normal, which points from A to B: on or past
+			// that shape's surface.
+			const b3ManifoldPoint* mp = manifold->points + j;
+			b3Pos point = b3OffsetPos( originA, mp->anchorA );
+			b3Vec3 gap = b3MulSV( mp->separation, manifold->normal );
+			int clipped = bxIsClipped( a, point ) || bxIsClipped( a, b3OffsetPos( point, gap ) ) || bxIsClipped( b, point ) ||
+						  bxIsClipped( b, b3OffsetPos( point, b3Neg( gap ) ) );
+			if ( clipped == 0 )
+			{
+				manifold->points[kept] = manifold->points[j];
+				kept += 1;
+			}
+		}
+		manifold->pointCount = kept;
+	}
+	return manifoldCount;
+}
+
+// Continuous collision has only its time of impact point.
+static bool bxClipPreSolve( b3ShapeId shapeIdA, b3ShapeId shapeIdB, b3Pos point, b3Vec3 normal, void* context )
+{
+	(void)normal;
+	(void)context;
+	return bxIsClipped( bxClipBody( shapeIdA, shapeIdB ), point ) == 0 && bxIsClipped( bxClipBody( shapeIdB, shapeIdA ), point ) == 0;
+}
+
+/// Clips the body's contacts with a plane, see bxBody::clipPlane; enabled 0 removes it. The plane is normalized, so
+/// its normal need not be unit length. Wakes the body so its contacts are made again.
+BX_EXPORT void bx_Body_SetClipPlane( int slot, int enabled, double nx, double ny, double nz, double d, unsigned int mask )
+{
+	bxBody* body = bxGetBody( slot );
+	if ( body == NULL || b3Body_IsValid( body->id ) == false )
+	{
+		return;
+	}
+	double length = sqrt( nx * nx + ny * ny + nz * nz );
+	body->clipEnabled = enabled != 0 && length > 0.0;
+	length = length > 0.0 ? length : 1.0;
+	body->clipPlane[0] = nx / length;
+	body->clipPlane[1] = ny / length;
+	body->clipPlane[2] = nz / length;
+	body->clipPlane[3] = d / length;
+	body->clipMask = (uint64_t)mask;
+	for ( int i = 0; i < body->shapeCount; ++i )
+	{
+		if ( b3Shape_IsValid( body->shapes[i] ) )
+		{
+			b3Shape_EnablePreSolveEvents( body->shapes[i], body->clipEnabled != 0 );
+		}
+	}
+	if ( b3Body_GetType( body->id ) != b3_staticBody )
+	{
+		b3Body_SetAwake( body->id, true );
+	}
+}
+
+/// scratchF64: [enabled, nx, ny, nz, d, mask]
+BX_EXPORT void bx_Body_GetClipPlane( int slot )
+{
+	memset( s_scratchF64, 0, 6 * sizeof( double ) );
+	bxBody* body = bxGetBody( slot );
+	if ( body == NULL || b3Body_IsValid( body->id ) == false )
+	{
+		return;
+	}
+	s_scratchF64[0] = body->clipEnabled;
+	for ( int i = 0; i < 4; ++i )
+	{
+		s_scratchF64[1 + i] = body->clipPlane[i];
+	}
+	s_scratchF64[5] = (double)( body->clipMask & 0xffffffffu );
+}
+
 BX_EXPORT int bx_GetMaxWorkers( void )
 {
 	return BX_MAX_WORKERS;
@@ -582,6 +768,9 @@ BX_EXPORT int bx_CreateWorld( float gx, float gy, float gz, int workerCount )
 			}
 #endif
 			s_worlds[i] = b3CreateWorld( &def );
+			// both only run for shapes with pre-solve events, which only clip planes turn on
+			b3World_SetManifoldCallback( s_worlds[i], bxClipManifolds, NULL );
+			b3World_SetPreSolveCallback( s_worlds[i], bxClipPreSolve, NULL );
 			return i + 1;
 		}
 	}
@@ -685,7 +874,7 @@ BX_EXPORT void bx_World_SetContactTuning( int w, float hertz, float dampingRatio
 	}
 }
 
-BX_EXPORT void bx_World_Explode( int w, float px, float py, float pz, float radius, float falloff, float impulsePerArea )
+BX_EXPORT void bx_World_Explode( int w, double px, double py, double pz, float radius, float falloff, float impulsePerArea )
 {
 	b3WorldId worldId = bxGetWorld( w );
 	if ( B3_IS_NULL( worldId ) )
@@ -693,7 +882,7 @@ BX_EXPORT void bx_World_Explode( int w, float px, float py, float pz, float radi
 		return;
 	}
 	b3ExplosionDef def = b3DefaultExplosionDef();
-	def.position = bxVec3( px, py, pz );
+	def.position = bxPos( px, py, pz );
 	def.radius = radius;
 	def.falloff = falloff;
 	def.impulsePerArea = impulsePerArea;
@@ -714,6 +903,13 @@ BX_EXPORT int bx_World_GetJointEventCount( int w )
 	return B3_IS_NON_NULL( worldId ) ? b3World_GetJointEvents( worldId ).count : 0;
 }
 
+/// The most the world's step stack has held at once, in bytes. Box3D grows the stack to 1.5 times this and keeps it.
+BX_EXPORT int bx_World_GetStackUsed( int w )
+{
+	b3WorldId worldId = bxGetWorld( w );
+	return B3_IS_NON_NULL( worldId ) ? b3World_GetCounters( worldId ).stackUsed : 0;
+}
+
 /// scratch: [bodyCount, shapeCount, contactCount, jointCount, islandCount, stepMs, collideMs, solveMs]
 BX_EXPORT void bx_World_GetStats( int w )
 {
@@ -985,7 +1181,7 @@ BX_EXPORT int bx_World_GetSensorEvents( int w )
 // ---------------------------------------------------------------------------------------------
 
 /// type: 0 static, 1 kinematic, 2 dynamic
-BX_EXPORT int bx_CreateBody( int w, int type, float px, float py, float pz, float qx, float qy, float qz, float qw, int isAwake )
+BX_EXPORT int bx_CreateBody( int w, int type, double px, double py, double pz, float qx, float qy, float qz, float qw, int isAwake )
 {
 	b3WorldId worldId = bxGetWorld( w );
 	if ( B3_IS_NULL( worldId ) )
@@ -996,7 +1192,7 @@ BX_EXPORT int bx_CreateBody( int w, int type, float px, float py, float pz, floa
 	bxBody* body = s_bodies + slot;
 	b3BodyDef def = b3DefaultBodyDef();
 	def.type = (b3BodyType)type;
-	def.position = bxVec3( px, py, pz );
+	def.position = bxPos( px, py, pz );
 	def.rotation = bxQuat( qx, qy, qz, qw );
 	def.isAwake = isAwake != 0;
 	def.userData = (void*)(intptr_t)slot;
@@ -1092,37 +1288,47 @@ BX_EXPORT int bx_Body_GetType( int slot )
 	return (int)b3Body_GetType( body->id );
 }
 
-BX_EXPORT void bx_Body_SetTransform( int slot, float px, float py, float pz, float qx, float qy, float qz, float qw )
+BX_EXPORT void bx_Body_SetTransform( int slot, double px, double py, double pz, float qx, float qy, float qz, float qw )
 {
 	BX_BODY( slot );
-	b3Body_SetTransform( body->id, bxVec3( px, py, pz ), bxQuat( qx, qy, qz, qw ) );
+	b3Body_SetTransform( body->id, bxPos( px, py, pz ), bxQuat( qx, qy, qz, qw ) );
 	if ( body->helperCount > 0 )
 	{
-		b3Transform xf = bxTransform( px, py, pz, qx, qy, qz, qw );
+		b3WorldTransform xf;
+		xf.p = bxPos( px, py, pz );
+		xf.q = bxTransform( 0.0f, 0.0f, 0.0f, qx, qy, qz, qw ).q;
 		for ( int i = 0; i < body->helperCount; ++i )
 		{
 			if ( b3Body_IsValid( body->helpers[i].id ) )
 			{
-				b3Transform h = b3MulTransforms( xf, body->helpers[i].local );
+				b3WorldTransform h = b3MulWorldTransforms( xf, body->helpers[i].local );
 				b3Body_SetTransform( body->helpers[i].id, h.p, h.q );
 			}
 		}
 	}
 }
 
-/// scratch: [px, py, pz, qx, qy, qz, qw]
+/// scratch: [px, py, pz, qx, qy, qz, qw]; scratchF64: [px, py, pz], the position as the build holds it
 BX_EXPORT void bx_Body_GetTransform( int slot )
 {
 	BX_BODY( slot );
 	b3WorldTransform xf = b3Body_GetTransform( body->id );
-	bxWriteVec3( 0, xf.p );
+	s_scratch[0] = (float)xf.p.x;
+	s_scratch[1] = (float)xf.p.y;
+	s_scratch[2] = (float)xf.p.z;
 	bxWriteQuat( 3, xf.q );
+	s_scratchF64[0] = xf.p.x;
+	s_scratchF64[1] = xf.p.y;
+	s_scratchF64[2] = xf.p.z;
 }
 
-BX_EXPORT void bx_Body_SetTargetTransform( int slot, float px, float py, float pz, float qx, float qy, float qz, float qw, float dt )
+BX_EXPORT void bx_Body_SetTargetTransform( int slot, double px, double py, double pz, float qx, float qy, float qz, float qw,
+										   float dt )
 {
 	BX_BODY( slot );
-	b3WorldTransform xf = bxTransform( px, py, pz, qx, qy, qz, qw );
+	b3WorldTransform xf;
+	xf.p = bxPos( px, py, pz );
+	xf.q = bxTransform( 0.0f, 0.0f, 0.0f, qx, qy, qz, qw ).q;
 	b3Body_SetTargetTransform( body->id, xf, dt, true );
 }
 
@@ -1186,10 +1392,10 @@ BX_EXPORT float bx_Body_GetGravityScale( int slot )
 	return b3Body_GetGravityScale( body->id );
 }
 
-BX_EXPORT void bx_Body_ApplyForce( int slot, float fx, float fy, float fz, float px, float py, float pz )
+BX_EXPORT void bx_Body_ApplyForce( int slot, float fx, float fy, float fz, double px, double py, double pz )
 {
 	BX_BODY( slot );
-	b3Body_ApplyForce( body->id, bxVec3( fx, fy, fz ), bxVec3( px, py, pz ), true );
+	b3Body_ApplyForce( body->id, bxVec3( fx, fy, fz ), bxPos( px, py, pz ), true );
 }
 
 BX_EXPORT void bx_Body_ApplyForceToCenter( int slot, float fx, float fy, float fz )
@@ -1204,10 +1410,10 @@ BX_EXPORT void bx_Body_ApplyTorque( int slot, float x, float y, float z )
 	b3Body_ApplyTorque( body->id, bxVec3( x, y, z ), true );
 }
 
-BX_EXPORT void bx_Body_ApplyLinearImpulse( int slot, float ix, float iy, float iz, float px, float py, float pz )
+BX_EXPORT void bx_Body_ApplyLinearImpulse( int slot, float ix, float iy, float iz, double px, double py, double pz )
 {
 	BX_BODY( slot );
-	b3Body_ApplyLinearImpulse( body->id, bxVec3( ix, iy, iz ), bxVec3( px, py, pz ), true );
+	b3Body_ApplyLinearImpulse( body->id, bxVec3( ix, iy, iz ), bxPos( px, py, pz ), true );
 }
 
 BX_EXPORT void bx_Body_ApplyLinearImpulseToCenter( int slot, float ix, float iy, float iz )
@@ -1301,6 +1507,15 @@ BX_EXPORT float* bx_BodyContactsPtr( void )
 	return s_bodyContacts.data;
 }
 
+// Each record's points as [x, y, z] doubles, room for four to a record, beside the float records
+#define BX_BODY_CONTACT_POINTS_STRIDE ( 3 * B3_MAX_MANIFOLD_POINTS )
+static bxDoubleBuffer s_bodyContactPoints;
+
+BX_EXPORT double* bx_BodyContactPointsF64Ptr( void )
+{
+	return s_bodyContactPoints.data;
+}
+
 /// The index of shapeId among the body's shapes, or -1.
 static int bxShapeIndex( const bxBody* body, b3ShapeId shapeId )
 {
@@ -1373,8 +1588,10 @@ BX_EXPORT int bx_Body_GetContacts( int slot )
 	}
 	bxFloatBuffer_Reserve( &s_bodyContacts, manifoldTotal * BX_BODY_CONTACT_STRIDE );
 
+	bxDoubleBuffer_Reserve( &s_bodyContactPoints, manifoldTotal * BX_BODY_CONTACT_POINTS_STRIDE );
 	b3Pos center = b3Body_GetWorldCenter( body->id );
 	float* out = s_bodyContacts.data;
+	double* outPoints = s_bodyContactPoints.data;
 	int count = 0;
 	for ( int i = 0; i < contactCount; ++i )
 	{
@@ -1394,6 +1611,7 @@ BX_EXPORT int bx_Body_GetContacts( int slot )
 		{
 			const b3Manifold* manifold = data->manifolds + m;
 			memset( out, 0, BX_BODY_CONTACT_STRIDE * sizeof( float ) );
+			memset( outPoints, 0, BX_BODY_CONTACT_POINTS_STRIDE * sizeof( double ) );
 			out[0] = (float)selfIndex;
 			out[1] = (float)( other != NULL ? otherSlot : 0 );
 			out[2] = (float)otherIndex;
@@ -1414,6 +1632,9 @@ BX_EXPORT int bx_Body_GetContacts( int slot )
 				po[0] = (float)point.x;
 				po[1] = (float)point.y;
 				po[2] = (float)point.z;
+				outPoints[3 * p + 0] = point.x;
+				outPoints[3 * p + 1] = point.y;
+				outPoints[3 * p + 2] = point.z;
 				po[3] = mp->separation;
 				po[4] = mp->normalImpulse;
 				po[5] = mp->totalNormalImpulse;
@@ -1422,6 +1643,7 @@ BX_EXPORT int bx_Body_GetContacts( int slot )
 				po[8] = (float)bxContactMaterial( other, otherIndex, mp->triangleIndex );
 			}
 			out += BX_BODY_CONTACT_STRIDE;
+			outPoints += BX_BODY_CONTACT_POINTS_STRIDE;
 			count += 1;
 		}
 	}
@@ -1570,6 +1792,40 @@ BX_EXPORT int bx_Body_GetShapeCount( int slot )
 	return body->shapeCount;
 }
 
+/// Gives the body a feature key, an integer from 1 to 2^44 - 1 passed as a double, and each of its shapes, now and when
+/// it is next shaped, the key (key << 20) | its index in the body. A moving shape's new contacts are made in the order
+/// of these keys, continuous collision sweeps in that order and a closest cast's tie goes to the lower key, so statics
+/// keyed by what they are (a cell, a piece) give the same contacts in the same order however and whenever they were
+/// made. Keys must differ between bodies a moving shape can reach. 0 takes the key off.
+BX_EXPORT void bx_Body_SetFeatureKey( int slot, double key )
+{
+	BX_BODY( slot );
+	uint64_t bodyKey = key >= 1.0 && key < 17592186044416.0 ? (uint64_t)key : 0;
+	body->featureKey = bodyKey;
+	for ( int i = 0; i < body->shapeCount; ++i )
+	{
+		if ( b3Shape_IsValid( body->shapes[i] ) )
+		{
+			b3Shape_SetFeatureKey( body->shapes[i], bodyKey == 0 ? 0 : ( bodyKey << BX_FEATURE_INDEX_BITS ) | (uint64_t)i );
+		}
+	}
+}
+
+BX_EXPORT double bx_Body_GetFeatureKey( int slot )
+{
+	BX_BODY_RET( slot, 0.0 );
+	return (double)body->featureKey;
+}
+
+static b3ShapeId bxBodyShape( int slot, int index );
+
+/// Shape `index`'s own feature key, as Box3D orders by it, passed as a double: exact up to 2^53.
+BX_EXPORT double bx_Body_GetShapeFeatureKey( int slot, int index )
+{
+	b3ShapeId shapeId = bxBodyShape( slot, index );
+	return B3_IS_NULL( shapeId ) ? 0.0 : (double)b3Shape_GetFeatureKey( shapeId );
+}
+
 /// 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 )
 {
@@ -1614,6 +1870,7 @@ static int bxNewDesc( int kind )
 	desc->categoryBits = B3_DEFAULT_CATEGORY_BITS;
 	desc->maskBits = B3_DEFAULT_MASK_BITS;
 	desc->meshScale = b3Vec3_one;
+	desc->invokeContactCreation = 1;
 	return slot;
 }
 
@@ -1762,6 +2019,146 @@ BX_EXPORT int bx_ShapeDesc_CreateHeightField( const float* heights, const unsign
 	return slot;
 }
 
+// Box3D's own allocator (core.c), which b3DestroyMesh and b3DestroyHeightField free with: an imported block must come
+// from it, with its alignment and its byte count.
+extern void* b3Alloc( size_t size );
+
+/// Where a mesh or height field description's data starts in this instance's memory, or 0 for any other description.
+/// Box3D keeps either as one block addressed by offsets from its start, with no pointer in it, so the block's bytes
+/// (bx_ShapeDesc_GetGeometryByteCount of them) can be copied out and made into a shape in another instance of the same
+/// build: a worker's instance with no world builds the geometry, and the simulation's instance only copies it in.
+BX_EXPORT const void* bx_ShapeDesc_GetGeometryBytes( int slot )
+{
+	bxShapeDesc* desc = bxGetDesc( slot );
+	if ( desc == NULL )
+	{
+		return NULL;
+	}
+	if ( desc->kind == bx_meshDesc )
+	{
+		return desc->mesh;
+	}
+	if ( desc->kind == bx_heightFieldDesc )
+	{
+		return desc->heightField;
+	}
+	return NULL;
+}
+
+/// The byte count of the block bx_ShapeDesc_GetGeometryBytes points at, or 0.
+BX_EXPORT int bx_ShapeDesc_GetGeometryByteCount( int slot )
+{
+	bxShapeDesc* desc = bxGetDesc( slot );
+	if ( desc == NULL )
+	{
+		return 0;
+	}
+	if ( desc->kind == bx_meshDesc && desc->mesh != NULL )
+	{
+		return desc->mesh->byteCount;
+	}
+	if ( desc->kind == bx_heightFieldDesc && desc->heightField != NULL )
+	{
+		return desc->heightField->byteCount;
+	}
+	return 0;
+}
+
+// Whether an array of count elements of size bytes at offset lies inside a block of byteCount bytes. An offset of 0
+// means the array is absent.
+static int bxInBlock( int32_t offset, int32_t count, int size, int byteCount )
+{
+	if ( offset == 0 )
+	{
+		return 1;
+	}
+	return offset > 0 && count >= 0 && (int64_t)offset + (int64_t)count * size <= byteCount;
+}
+
+/// A copy of bytes the caller has put in this instance's memory, in a block from Box3D's allocator, if they are a mesh
+/// (kind 3) or height field (kind 4) block of this build, whole and with every array inside it. NULL otherwise.
+static void* bxImportGeometry( const void* bytes, int byteCount, int kind )
+{
+	if ( bytes == NULL || byteCount < 16 )
+	{
+		return NULL;
+	}
+	if ( kind == bx_meshDesc )
+	{
+		if ( byteCount < (int)sizeof( b3MeshData ) )
+		{
+			return NULL;
+		}
+		b3MeshData header;
+		memcpy( &header, bytes, sizeof( header ) );
+		if ( header.version != B3_MESH_VERSION || header.byteCount != byteCount ||
+			 bxInBlock( header.nodeOffset, header.nodeCount, (int)sizeof( b3MeshNode ), byteCount ) == 0 ||
+			 bxInBlock( header.vertexOffset, header.vertexCount, (int)sizeof( b3Vec3 ), byteCount ) == 0 ||
+			 bxInBlock( header.triangleOffset, header.triangleCount, (int)sizeof( b3MeshTriangle ), byteCount ) == 0 ||
+			 bxInBlock( header.materialOffset, header.triangleCount, 1, byteCount ) == 0 ||
+			 bxInBlock( header.flagsOffset, header.triangleCount, 1, byteCount ) == 0 )
+		{
+			return NULL;
+		}
+	}
+	else
+	{
+		if ( byteCount < (int)sizeof( b3HeightFieldData ) )
+		{
+			return NULL;
+		}
+		b3HeightFieldData header;
+		memcpy( &header, bytes, sizeof( header ) );
+		int points = header.columnCount * header.rowCount;
+		int cells = ( header.columnCount - 1 ) * ( header.rowCount - 1 );
+		if ( header.version != B3_HEIGHT_FIELD_VERSION || header.byteCount != byteCount || header.columnCount < 2 ||
+			 header.rowCount < 2 || bxInBlock( header.heightsOffset, points, 2, byteCount ) == 0 ||
+			 bxInBlock( header.materialOffset, cells, 1, byteCount ) == 0 ||
+			 bxInBlock( header.flagsOffset, 2 * cells, 1, byteCount ) == 0 )
+		{
+			return NULL;
+		}
+	}
+	void* block = b3Alloc( (size_t)byteCount );
+	if ( block != NULL )
+	{
+		memcpy( block, bytes, (size_t)byteCount );
+	}
+	return block;
+}
+
+/// A mesh description from the bytes of a mesh block (bx_ShapeDesc_GetGeometryBytes, from this instance or another of
+/// the same build) that the caller has put at `bytes`: the block is copied as it is, and nothing in it needs fixing up.
+/// The scale is the description's, as bx_ShapeDesc_CreateMesh takes it. Returns 0 if the bytes are not such a block.
+BX_EXPORT int bx_ShapeDesc_CreateMeshFromBytes( const void* bytes, int byteCount, float sx, float sy, float sz )
+{
+	b3MeshData* mesh = (b3MeshData*)bxImportGeometry( bytes, byteCount, bx_meshDesc );
+	if ( mesh == NULL )
+	{
+		return 0;
+	}
+	int slot = bxNewDesc( bx_meshDesc );
+	s_descs[slot].mesh = mesh;
+	s_descs[slot].meshScale = bxVec3( sx, sy, sz );
+	return slot;
+}
+
+/// A height field description from the bytes of a height field block, as bx_ShapeDesc_CreateMeshFromBytes makes a mesh.
+/// The block carries its scale, quantization and winding; (ox, oy, oz) is the description's local offset, as
+/// bx_ShapeDesc_CreateHeightField takes it.
+BX_EXPORT int bx_ShapeDesc_CreateHeightFieldFromBytes( const void* bytes, int byteCount, float ox, float oy, float oz )
+{
+	b3HeightFieldData* hf = (b3HeightFieldData*)bxImportGeometry( bytes, byteCount, bx_heightFieldDesc );
+	if ( hf == NULL )
+	{
+		return 0;
+	}
+	int slot = bxNewDesc( bx_heightFieldDesc );
+	s_descs[slot].heightField = hf;
+	s_descs[slot].offset = bxVec3( ox, oy, oz );
+	return slot;
+}
+
 BX_EXPORT int bx_ShapeDesc_CreateContainer( void )
 {
 	return bxNewDesc( bx_containerDesc );
@@ -1905,6 +2302,27 @@ BX_EXPORT int bx_ShapeDesc_IsSensor( int slot )
 	return desc == NULL ? 0 : desc->isSensor;
 }
 
+/// Whether a static shape made from this description looks for its own pairs on the next step (1, Box3D's default), or
+/// waits until a moving shape finds it (0). With 0 a static never enters the broad phase's move buffer, which saves the
+/// step the pair slots it would reserve for it (Box3D keeps its step stack at 1.5 times the largest it has needed), and
+/// a static made where a moving shape's fat bounds already reach it is paired only once that shape moves again, so a
+/// static made late pairs on the same step as one made at the start. Off on a container, it is off for every shape made
+/// from its children. Dynamic and kinematic shapes always look for pairs.
+BX_EXPORT void bx_ShapeDesc_SetInvokeContactCreation( int slot, int flag )
+{
+	bxShapeDesc* desc = bxGetDesc( slot );
+	if ( desc != NULL )
+	{
+		desc->invokeContactCreation = flag != 0;
+	}
+}
+
+BX_EXPORT int bx_ShapeDesc_GetInvokeContactCreation( int slot )
+{
+	bxShapeDesc* desc = bxGetDesc( slot );
+	return desc == NULL ? 0 : desc->invokeContactCreation;
+}
+
 static b3AABB bxDescAABB( bxShapeDesc* desc, b3Transform xf, b3Vec3 scale, int depth )
 {
 	b3AABB aabb = { b3Vec3_zero, b3Vec3_zero };
@@ -2108,6 +2526,10 @@ static void bxBodyPushShape( bxBody* body, b3ShapeId shapeId, int descSlot, int
 	body->shapeDescs[body->shapeCount] = descSlot;
 	body->geomDescs[body->shapeCount] = geomSlot;
 	body->shapeCount += 1;
+	if ( body->clipEnabled )
+	{
+		b3Shape_EnablePreSolveEvents( shapeId, true );
+	}
 	bxShapeDesc* geom = bxGetDesc( geomSlot );
 	if ( geom != NULL && ( geom->kind == bx_meshDesc || geom->kind == bx_heightFieldDesc ) )
 	{
@@ -2165,13 +2587,15 @@ static int bxBakeTransformedMesh( const bxShapeDesc* source, b3Transform xf, b3V
 	return slot;
 }
 
-static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 scale, int depth )
+/// invoke is 0 when a container above this description has contact creation off.
+static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 scale, int depth, int invoke )
 {
 	bxShapeDesc* desc = bxGetDesc( descSlot );
 	if ( desc == NULL || depth > 8 )
 	{
 		return;
 	}
+	invoke = invoke != 0 && desc->invokeContactCreation != 0;
 
 	b3ShapeDef def = b3DefaultShapeDef();
 	def.density = desc->density;
@@ -2188,6 +2612,10 @@ static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 sc
 	def.enableHitEvents = body->hitEvents != 0;
 	// the caller applies the mass once after instantiating every shape of the description
 	def.updateBodyMass = false;
+	def.invokeContactCreation = invoke != 0;
+	// the shape takes the next index on the body, whichever Box3D body it is made on; a body without a key leaves its
+	// shapes at zero, so they fall back to their ids as unkeyed shapes do
+	def.featureKey = body->featureKey == 0 ? 0 : ( body->featureKey << BX_FEATURE_INDEX_BITS ) | (uint64_t)body->shapeCount;
 
 	switch ( desc->kind )
 	{
@@ -2265,7 +2693,7 @@ static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 sc
 					body->helperCapacity = capacity;
 				}
 				b3WorldTransform bodyXf = b3Body_GetTransform( body->id );
-				b3Transform world = b3MulTransforms( bodyXf, local );
+				b3WorldTransform world = b3MulWorldTransforms( bodyXf, local );
 				b3BodyDef helperDef = b3DefaultBodyDef();
 				helperDef.type = b3_staticBody;
 				helperDef.position = world.p;
@@ -2291,7 +2719,8 @@ static void bxInstantiate( bxBody* body, int descSlot, b3Transform xf, b3Vec3 sc
 					break;
 				}
 				bxChild child = container->children[i];
-				bxInstantiate( body, child.desc, b3MulTransforms( xf, child.transform ), bxMulScale( scale, child.scale ), depth + 1 );
+				bxInstantiate( body, child.desc, b3MulTransforms( xf, child.transform ), bxMulScale( scale, child.scale ), depth + 1,
+							   invoke );
 			}
 			break;
 		}
@@ -2308,7 +2737,7 @@ BX_EXPORT void bx_Body_SetShape( int slot, int descSlot )
 	body->shapeDesc = descSlot;
 	if ( descSlot != 0 )
 	{
-		bxInstantiate( body, descSlot, b3Transform_identity, b3Vec3_one, 0 );
+		bxInstantiate( body, descSlot, b3Transform_identity, b3Vec3_one, 0, 1 );
 	}
 	b3Body_ApplyMassFromShapes( body->id );
 }
@@ -3234,8 +3663,27 @@ typedef struct bxRayContext
 	int hitSensors;
 	int closestOnly;
 	int count;
+	// the closest hit so far, for ties
+	uint64_t bestKey;
+	int bestBody;
+	int bestIndex;
 } bxRayContext;
 
+/// Whether a hit on (key, body, index) wins a tie against the closest so far: the lower feature key, then the lower body
+/// slot and shape index, so a tie does not go to whichever shape the broad phase's tree happened to give first.
+static int bxHitPrecedes( uint64_t key, int body, int index, uint64_t bestKey, int bestBody, int bestIndex )
+{
+	if ( key != bestKey )
+	{
+		return key < bestKey;
+	}
+	if ( body != bestBody )
+	{
+		return body < bestBody;
+	}
+	return index < bestIndex;
+}
+
 static bxFloatBuffer s_rayHits;
 #define BX_RAY_HIT_STRIDE 11
 
@@ -3244,6 +3692,22 @@ BX_EXPORT float* bx_RayHitsPtr( void )
 	return s_rayHits.data;
 }
 
+// Each hit's point as [x, y, z] doubles, beside its float record
+static bxDoubleBuffer s_rayHitPoints;
+
+BX_EXPORT double* bx_RayHitPointsF64Ptr( void )
+{
+	return s_rayHitPoints.data;
+}
+
+static void bxWriteHitPoint( int index, b3Pos point )
+{
+	bxDoubleBuffer_Reserve( &s_rayHitPoints, ( index + 1 ) * 3 );
+	s_rayHitPoints.data[3 * index + 0] = point.x;
+	s_rayHitPoints.data[3 * index + 1] = point.y;
+	s_rayHitPoints.data[3 * index + 2] = point.z;
+}
+
 static float bxRayCallback( b3ShapeId shapeId, b3Pos point, b3Vec3 normal, float fraction, uint64_t userMaterialId, int triangleIndex,
 							int childIndex, void* context )
 {
@@ -3259,6 +3723,26 @@ static float bxRayCallback( b3ShapeId shapeId, b3Pos point, b3Vec3 normal, float
 	{
 		return -1.0f;
 	}
+	int shapeIndex = bxShapeIndex( s_bodies + bodySlot, shapeId );
+	// The ray is clipped just past the closest hit, not at it, so a shape that ties with it is still reported, and the
+	// tie goes by feature key.
+	float clip = b3MinFloat( nextafterf( fraction, 2.0f ), 1.0f );
+	if ( ctx->closestOnly )
+	{
+		uint64_t key = b3Shape_GetFeatureKey( shapeId );
+		if ( ctx->count > 0 )
+		{
+			float best = s_rayHits.data[6];
+			if ( fraction > best ||
+				 ( fraction == best && bxHitPrecedes( key, bodySlot, shapeIndex, ctx->bestKey, ctx->bestBody, ctx->bestIndex ) == 0 ) )
+			{
+				return b3MinFloat( nextafterf( best, 2.0f ), 1.0f );
+			}
+		}
+		ctx->bestKey = key;
+		ctx->bestBody = bodySlot;
+		ctx->bestIndex = shapeIndex;
+	}
 	int index = ctx->closestOnly ? 0 : ctx->count;
 	bxFloatBuffer_Reserve( &s_rayHits, ( index + 1 ) * BX_RAY_HIT_STRIDE );
 	float* out = s_rayHits.data + index * BX_RAY_HIT_STRIDE;
@@ -3272,14 +3756,15 @@ static float bxRayCallback( b3ShapeId shapeId, b3Pos point, b3Vec3 normal, float
 	out[7] = (float)bodySlot;
 	out[8] = (float)bxDescSlotFromShape( shapeId );
 	out[9] = (float)triangleIndex;
-	out[10] = (float)bxShapeIndex( s_bodies + bodySlot, shapeId );
+	out[10] = (float)shapeIndex;
+	bxWriteHitPoint( index, point );
 	ctx->count = ctx->closestOnly ? 1 : ctx->count + 1;
-	return ctx->closestOnly ? fraction : 1.0f;
+	return ctx->closestOnly ? clip : 1.0f;
 }
 
 /// Casts a ray from origin along translation. Returns the number of hits written to bx_RayHitsPtr().
 /// Each hit: [px, py, pz, nx, ny, nz, fraction, bodySlot, shapeDesc, triangleIndex, shapeIndex]
-BX_EXPORT int bx_World_CastRay( int w, float ox, float oy, float oz, float dx, float dy, float dz, unsigned int categoryBits,
+BX_EXPORT int bx_World_CastRay( int w, double ox, double oy, double oz, float dx, float dy, float dz, unsigned int categoryBits,
 								unsigned int maskBits, int ignoreBody, int hitSensors, int closestOnly )
 {
 	b3WorldId worldId = bxGetWorld( w );
@@ -3287,21 +3772,14 @@ BX_EXPORT int bx_World_CastRay( int w, float ox, float oy, float oz, float dx, f
 	{
 		return 0;
 	}
-	bxRayContext ctx = { ignoreBody, hitSensors, closestOnly, 0 };
+	bxRayContext ctx = { ignoreBody, hitSensors, closestOnly, 0, 0, 0, 0 };
 	b3QueryFilter filter = b3DefaultQueryFilter();
 	filter.categoryBits = (uint64_t)categoryBits;
 	filter.maskBits = (uint64_t)maskBits;
-	b3World_CastRay( worldId, bxVec3( ox, oy, oz ), bxVec3( dx, dy, dz ), filter, bxRayCallback, &ctx );
+	b3World_CastRay( worldId, bxPos( ox, oy, oz ), bxVec3( dx, dy, dz ), filter, bxRayCallback, &ctx );
 	return ctx.count;
 }
 
-/// A world position from three doubles: exact in a double precision build, rounded to float in the default one.
-static b3Pos bxPos( double x, double y, double z )
-{
-	b3Pos p = { x, y, z };
-	return p;
-}
-
 typedef struct bxShapeCastContext
 {
 	int ignoreBody;
@@ -3309,6 +3787,10 @@ typedef struct bxShapeCastContext
 	int count;
 	float radius;
 	b3Vec3 translation;
+	// the closest hit so far, for ties
+	uint64_t bestKey;
+	int bestBody;
+	int bestIndex;
 } bxShapeCastContext;
 
 // Box3D's shape cast stops where the two cores are max(slop, radii - slop) apart, so that a body moved to the hit is
@@ -3354,12 +3836,20 @@ static float bxShapeCastCallback( b3ShapeId shapeId, b3Pos point, b3Vec3 normal,
 	touch = b3MaxFloat( touch, 0.0f );
 
 	int index = ctx->count;
+	int shapeIndex = bxShapeIndex( s_bodies + bodySlot, shapeId );
 	if ( ctx->closestOnly )
 	{
-		if ( ctx->count > 0 && s_rayHits.data[6] <= touch )
+		// a tie goes by feature key, not to whichever shape the tree gave first
+		uint64_t key = b3Shape_GetFeatureKey( shapeId );
+		if ( ctx->count > 0 &&
+			 ( s_rayHits.data[6] < touch ||
+			   ( s_rayHits.data[6] == touch && bxHitPrecedes( key, bodySlot, shapeIndex, ctx->bestKey, ctx->bestBody, ctx->bestIndex ) == 0 ) ) )
 		{
 			return 1.0f;
 		}
+		ctx->bestKey = key;
+		ctx->bestBody = bodySlot;
+		ctx->bestIndex = shapeIndex;
 		index = 0;
 	}
 	bxFloatBuffer_Reserve( &s_rayHits, ( index + 1 ) * BX_RAY_HIT_STRIDE );
@@ -3374,7 +3864,8 @@ static float bxShapeCastCallback( b3ShapeId shapeId, b3Pos point, b3Vec3 normal,
 	out[7] = (float)bodySlot;
 	out[8] = (float)bxDescSlotFromShape( shapeId );
 	out[9] = (float)triangleIndex;
-	out[10] = (float)bxShapeIndex( s_bodies + bodySlot, shapeId );
+	out[10] = (float)shapeIndex;
+	bxWriteHitPoint( index, point );
 	ctx->count = ctx->closestOnly ? 1 : ctx->count + 1;
 	return 1.0f;
 }
@@ -3391,7 +3882,7 @@ BX_EXPORT int bx_World_CastShape( int w, double ox, double oy, double oz, const
 	{
 		return 0;
 	}
-	bxShapeCastContext ctx = { ignoreBody, closestOnly, 0, radius, bxVec3( dx, dy, dz ) };
+	bxShapeCastContext ctx = { ignoreBody, closestOnly, 0, radius, bxVec3( dx, dy, dz ), 0, 0, 0 };
 	b3QueryFilter filter = b3DefaultQueryFilter();
 	filter.categoryBits = (uint64_t)categoryBits;
 	filter.maskBits = (uint64_t)maskBits;