b3dDestroyConstraint

Destroys physics constraint (joint) and removes it from simulation. Takes constraintHandle (constraint handle returned from b3dCreatePointConstraint). Returns nothing (void function, no return value). Removes constraint from Jolt physics system, frees constraint memory, makes connected bodies independent again.

This function removes a constraint from the physics simulation, allowing previously connected bodies to move independently. After destruction, bodies are no longer forced to maintain their attachment points together and will separate under gravity/forces. Common uses: breaking chains (destroy link to separate chain segments), destructible structures (remove constraints when damage threshold reached), temporary connections (attach/detach objects dynamically), constraint release (free hanging object to let it fall). Does not destroy the bodies themselves (bodies continue to exist and simulate, just no longer connected).

Destruction process: (1) validates constraintHandle exists in g_constraints map (early return if not found), (2) retrieves Constraint* pointer from map, (3) calls g_physicsSystem->RemoveConstraint(constraint) to remove from Jolt simulation, (4) erases constraintHandle from g_constraints map (frees map entry), (5) Jolt handles constraint memory cleanup internally. Thread safety: RemoveConstraint is thread-safe (Jolt handles locking internally), safe to call during physics simulation, constraint removed at next physics step (not instant removal).

Typical usage patterns: Chain break: If weaponHit Then b3dDestroyConstraint(chainLink) makes chain segment fall. Timed release: If GetTimer() > releaseTime Then b3dDestroyConstraint(ropeConstraint) drops hanging object after delay. Damage threshold: health = health - damage, If health <= 0 Then b3dDestroyConstraint(jointConstraint) breaks joint when destroyed. Toggle attach/detach: If keyPressed Then If attached Then b3dDestroyConstraint(attachConstraint), attached = False Else attachConstraint = b3dCreatePointConstraint(...), attached = True. Cleanup on entity delete: b3dDestroyConstraint(entityConstraint), b3dFreeEntity(entity) removes constraint before removing entity.

Physics behavior after destruction: bodies immediately become independent (no longer constrained), bodies continue with current velocities (momentum preserved), gravity/forces apply normally (bodies fall/move freely), collisions still work (bodies can collide with each other or environment). Constraint forces removed instantly (bodies no longer pulled toward attachment points), any violation of constraint at destruction moment persists (bodies don't snap back to free state, just stop being forced together). Bodies may drift apart or collide depending on current velocities and forces.

Handle validation: silently returns if constraintHandle not found in map (safe to call with invalid handle, no error), does not validate bodies still exist (constraint removed even if bodies already destroyed), does not check g_physicsSystem initialized (assumes system exists if constraint exists). Common pattern: check if constraint exists before destroying: If constraintHandle <> 0 Then b3dDestroyConstraint(constraintHandle), constraintHandle = 0 prevents double-destroy.

Performance: O(1) map lookup and removal (instant), RemoveConstraint is O(N) where N = total constraints (Jolt iterates constraint list), typically very fast (<1ms even with hundreds of constraints), no physics step required (takes effect immediately). Best practice: destroy constraints when no longer needed to reduce solver overhead, batch destroy multiple constraints in same frame if possible, set constraintHandle = 0 after destroying to mark as invalid.

Memory management: constraint memory freed by Jolt internally (no manual cleanup needed), g_constraints map entry removed (handle becomes invalid), bodies not affected (continue to exist and simulate normally), constraint pointer becomes invalid (do not store or use after destroy). Jolt uses reference counting (constraint automatically deleted when no longer referenced).

Common mistakes: destroying constraint twice (use constraintHandle = 0 pattern to prevent), not checking if constraint exists before destroying (safe but inefficient), forgetting to destroy constraints when removing entities (creates memory leak if many create/destroy cycles), destroying constraint then trying to use handle later (handle becomes invalid after destroy). Invalid handle behavior: silently ignored (no crash or error), g_constraints.find() returns end() iterator, function returns early without doing anything.

Prerequisites: g_physicsSystem must be initialized (assumes constraint was created successfully), constraintHandle must be valid (from b3dCreatePointConstraint, non-zero). Safe to call if: bodies already destroyed (constraint removed anyway), constraint already removed (silently ignored), physics system shutting down (constraints auto-cleaned up). Not safe if: called from physics callback (may cause deadlock, destroy constraints outside callbacks).

Related functions: b3dCreatePointConstraint creates constraint (returns handle used here), b3dSetPhysicsBodyType can make body kinematic instead of destroying constraint (preserve connection but control manually), b3dApplyPhysicsImpulse can push bodies apart before destroying constraint (add separation force before release). Alternative to destroying: disable collision between bodies (keeps constraint but prevents collision response), make both bodies kinematic (manual control while preserving constraint), change body mass to near-zero (constraint still exists but very weak forces).

Advanced usage: Destructible chains (iterate all link constraints, destroy subset to break chain at specific point), ragdoll death (destroy all joint constraints when character dies, body parts fall freely), constraint pools (reuse constraint handles by destroying old and creating new, avoids handle exhaustion), conditional breaking (check constraint force/stress, destroy if exceeds threshold - requires custom constraint monitoring). Debugging: print "Constraint destroyed: " & constraintHandle before destroying (trace constraint lifetime), check bodies separate after destroy (verify constraint actually removed), count active constraints with g_constraints.size() (track constraint usage).

Use cases: (1) Breakable objects (vase shatters, constraints between shards destroyed), (2) Rope cutting (destroy middle constraint, rope splits in two), (3) Temporary grabbing (create constraint when grab, destroy when release), (4) Explosive force (apply impulse then destroy constraints for debris scattering), (5) Puzzle mechanics (destroy constraints to drop bridge sections). Performance note: destroying many constraints in one frame may cause frame spike (Jolt must rebuild solver data structures), stagger destruction over multiple frames if destroying hundreds of constraints.