Tunable ccd (#1093)

- Added `b2BodyDef::safetyFactor` to allow continuous collision to
engage at lower speeds.
- Contact recycling is now disabled on fast bodies.
- Implements #1040

Author: erincatto

include/box2d/box2d.h

@@ -566,6 +566,12 @@ B2_API void b2Body_SetSleepThreshold( b2BodyId bodyId, float sleepThreshold );
 /// Get the sleep threshold, usually in meters per second.
 B2_API float b2Body_GetSleepThreshold( b2BodyId bodyId );
 
+/// Set the continuous collision safety factor. Smaller is safer but can lead to hitching. Recommended range [0.01, 0.5]. Non-dimensional.
+B2_API void b2Body_SetSafetyFactor( b2BodyId bodyId, float safetyFactor );
+
+/// Get the continuous collision safety factor. Non-dimensional.
+B2_API float b2Body_GetSafetyFactor( b2BodyId bodyId );
+
 /// Returns true if this body is enabled
 B2_API bool b2Body_IsEnabled( b2BodyId bodyId );
 

include/box2d/types.h

@@ -237,6 +237,13 @@ typedef struct b2BodyDef
 	/// Sleep speed threshold, default is 0.05 meters per second
 	float sleepThreshold;
 
+	/// Continuous collision safety factor. The solver only uses continuous collision if there is a
+	/// risk of tunneling. If the body is moving fast enough to risk tunneling then it is considered a "fast body".
+	/// This improves performance and prevents movement hitches. If a body moving N meter risks tunneling, then the
+	/// body will be considered fast if it moves more than a safetyFactor times N meters over one full time step.
+	/// Non-dimensional. Recommended range [0.01, 0.5]. Default is 0.5 for high performance with low tunneling risk.
+	float safetyFactor;
+
 	/// Optional body name for debugging. Up to B2_NAME_LENGTH characters
 	const char* name;
 

samples/dynamic_mover.cpp

@@ -174,7 +174,7 @@ bool DynamicMover::Jump()
 	}
 
 	float surfaceVelocity = 0.0f;
-	if (b2Body_IsValid(m_castResult.bodyId))
+	if ( b2Body_IsValid( m_castResult.bodyId ) )
 	{
 		b2Vec2 v = b2Body_GetWorldPointVelocity( m_castResult.bodyId, m_castResult.point );
 		surfaceVelocity = v.y;
@@ -243,15 +243,15 @@ void DynamicMover::Update( float timeStep, float throttle )
 		m_onGround = m_jumping == false;
 
 		// Is the ground too steep to walk?
-		m_walkable = m_castResult.normal.y > m_minGroundNormalY;
+		m_walkable = m_castResult.normal.y >= m_minGroundNormalY;
 	}
 	else
 	{
 		m_onGround = false;
 		m_walkable = false;
 	}
 
-		m_velocity = b2Body_GetLinearVelocity( m_moverId );
+	m_velocity = b2Body_GetLinearVelocity( m_moverId );
 
 	// Friction
 	if ( m_onGround )

samples/sample_character.cpp

@@ -756,7 +756,8 @@ class DynamicMoverSample : public Sample
 		DrawScreenTextLine( "pogo: impulse %.3f, velocity %.3f", m_mover.m_pogoImpulse, m_mover.m_pogoVelocity );
 		DrawScreenTextLine( "pogo: length = %.2f/%.2f", m_mover.m_pogoLength, m_mover.m_pogoRestLength );
 		DrawScreenTextLine( "on ground: %d", (int)m_mover.m_onGround );
-		DrawScreenTextLine( "walkable: %d", (int)m_mover.m_walkable );
+		float normalY = m_mover.m_castResult.hit ? m_mover.m_castResult.normal.y : 0.0f;
+		DrawScreenTextLine( "walkable: %d, normal y: %.3f/%.3f", (int)m_mover.m_walkable, normalY, m_mover.m_minGroundNormalY );
 		DrawScreenTextLine( "jumping/ticks: %d/%d", (int)m_mover.m_jumping, m_mover.m_jumpTicks );
 
 		if ( m_lockCamera )

samples/sample_continuous.cpp

@@ -1756,3 +1756,121 @@ class Wedge : public Sample
 };
 
 static int sampleWedge = RegisterSample( "Continuous", "Wedge", Wedge::Create );
+
+// This shows how adjusting the CCD safety factor can engage continuous collision at
+// lower speeds to avoid the slight overlap that happens with discrete collision detection.
+// The best way to run this sample is:
+// 1. press pause (P)
+// 2. restart (R) or press the Drop button
+// 3. then single step (O)
+// Then look at the metrics and overlap. The color of the shape gets darker when it is using
+// continuous collision detection.
+class SafetyFactor : public Sample
+{
+public:
+	explicit SafetyFactor( SampleContext* context )
+		: Sample( context )
+	{
+		if ( m_context->restart == false )
+		{
+			m_context->camera.center = { 0.0f, 3.0f };
+			m_context->camera.zoom = 6.0f;
+		}
+
+		{
+			b2BodyDef bodyDef = b2DefaultBodyDef();
+			bodyDef.position = { 0.0f, -1.0f };
+			b2BodyId groundId = b2CreateBody( m_worldId, &bodyDef );
+
+			b2ShapeDef shapeDef = b2DefaultShapeDef();
+			b2Polygon box = b2MakeBox( 20.0f, 1.0f );
+			b2CreatePolygonShape( groundId, &shapeDef, &box );
+		}
+
+		m_bodyId = b2_nullBodyId;
+		m_extent = 0.5f;
+		m_height = 0.3f;
+		m_safetyFactor = 0.1f;
+		m_overlap = 0.0f;
+
+		Launch();
+	}
+
+	void Launch()
+	{
+		if ( B2_IS_NON_NULL( m_bodyId ) )
+		{
+			b2DestroyBody( m_bodyId );
+		}
+
+		b2BodyDef bodyDef = b2DefaultBodyDef();
+		bodyDef.type = b2_dynamicBody;
+		bodyDef.position = { 0.0f, m_height + m_extent };
+		bodyDef.safetyFactor = m_safetyFactor;
+		m_bodyId = b2CreateBody( m_worldId, &bodyDef );
+
+		b2ShapeDef shapeDef = b2DefaultShapeDef();
+		b2Polygon box = b2MakeSquare( m_extent );
+		b2CreatePolygonShape( m_bodyId, &shapeDef, &box );
+
+		m_overlap = 0.0f;
+	}
+
+	void Step() override
+	{
+		Sample::Step();
+
+		if ( m_didStep )
+		{
+			// Contacts are computed at the beginning of the step, so the manifold holds the initial separation.
+			b2ContactData data;
+			int count = b2Body_GetContactData( m_bodyId, &data, 1 );
+			if ( count == 1 )
+			{
+				for ( int j = 0; j < data.manifold.pointCount; ++j )
+				{
+					m_overlap = b2MaxFloat( m_overlap, -data.manifold.points[j].separation );
+				}
+			}
+		}
+
+		DrawLine( m_draw, b2ToPos( b2Vec2{ -3.0f, -m_overlap } ), b2ToPos( b2Vec2{ 3.0f, -m_overlap } ), b2_colorRed );
+
+		float timeStep = m_context->hertz > 0.0f ? 1.0f / m_context->hertz : 0.0f;
+		float motion = timeStep * b2Length( b2Body_GetLinearVelocity( m_bodyId ) );
+
+		DrawScreenTextLine( "actual movement = %.3f m", motion );
+		DrawScreenTextLine( "fast movement = %.3f m", m_safetyFactor * m_extent );
+		DrawScreenTextLine( "overlap = %.4f m", m_overlap );
+	}
+
+	bool DrawControls() override
+	{
+		bool changed = false;
+
+		ImGui::PushItemWidth( 10.0f * ImGui::GetFontSize() );
+		changed |= ImGui::SliderFloat( "Height", &m_height, 0.0f, 2.0f, "%.2f" );
+		changed |= ImGui::SliderFloat( "Safety", &m_safetyFactor, 0.0f, 1.0f, "%.2f" );
+		ImGui::PopItemWidth();
+
+		if ( ImGui::Button( "Drop" ) || changed )
+		{
+			Launch();
+		}
+
+		return true;
+	}
+
+	static Sample* Create( SampleContext* context )
+	{
+		return new SafetyFactor( context );
+	}
+
+	b2BodyId m_bodyId;
+	float m_extent;
+	float m_height;
+	float m_safetyFactor;
+	float m_overlap;
+};
+
+static int sampleSafetyFactor = RegisterSample( "Continuous", "Safety Factor", SafetyFactor::Create );