b3dCountCollisions

Returns number of collisions for entity this frame (new contacts only, cleared each frame). Takes entity (entity handle with physics body). Returns collision count (0 if no collisions, >0 if collided). Queries g_entityCollisions map for entity, returns vector size (number of CollisionData entries). Use to check if entity collided, iterate collision details, or react to multiple impacts.

This function counts collisions for entity. Collision detection: Jolt ContactListener captures contacts (OnContactAdded callback when bodies first touch), records CollisionData for each contact (position, normal, impulse, other entity), stores in g_entityCollisions map (entityHandle -> vector of collisions), thread-safe access (mutex-protected, physics runs on multiple threads). Frame-based collision: collisions cleared each frame (g_entityCollisions.clear() at start of UpdatePhysicsSystem), only new contacts counted (OnContactAdded fires, OnContactPersisted ignored), persisting contacts not re-counted (continuous contact = no new collision after first frame), query this frame only (check collisions immediately, don't cache across frames). Collision data structure: CollisionData stores (otherEntityHandle, position Vec3, normal Vec3, impulse float), bidirectional recording (both entities record collision, entity A sees B, entity B sees A), normal flipped for second entity (collision normal points away from surface for each entity). Use cases: (1) Impact detection (check if entity hit something, trigger effects), (2) Damage calculation (iterate collisions, apply damage per hit), (3) Collision response (change state, play sounds, spawn particles), (4) Multiple impacts (handle multiple simultaneous collisions, explosions or clusters), (5) Collision filtering (check collision count, decide response based on number). Common patterns: check collision If b3dCountCollisions(entity) > 0 Then collided this frame, iterate collisions For i = 0 To b3dCountCollisions(entity) - 1: process each collision, count-based response If count > 3 Then major impact, special handling. Typical usage: call every frame to check collisions (real-time collision detection), iterate collision details for response (use count to loop through collisions), combine with other collision queries (b3dCollisionEntity, b3dCollisionImpulse).

Return value: 0 if no collisions (entity not in g_entityCollisions, or empty collision vector), positive integer (number of collisions this frame, 1-N range), typical 0-5 collisions (most entities collide with 1-2 objects, clusters or explosions may have more). Entity requirement: entity must have physics body (b3dCreatePhysicsBody called, body exists in Jolt system), non-physics entities always return 0 (no physics body = no collisions detected), entity must be active (body must be active and collidable). Zero collisions: entity not in map (no collisions ever, or previous frame cleared), entity has empty vector (collisions cleared, entity present but no new contacts), check returns 0 (no collisions this frame, safe to skip collision handling). Thread-safe access: mutex lock (std::lock_guard protects g_entityCollisions access), safe to call during physics update (ContactListener adds collisions on physics threads, query thread-safe), no race conditions (mutex ensures consistent reads and writes).

Collision iteration pattern: get count (count = b3dCountCollisions(entity)), loop through collisions (For i = 0 To count - 1), query details (otherEntity = b3dCollisionEntity(entity, i), pos = b3dCollisionX/Y/Z(entity, i)), process each collision (apply damage, spawn effects, play sounds). Impact detection example: check if player hit something (count = b3dCountCollisions(player)), react to collision (If count > 0 Then player hit, trigger impact feedback), single or multiple (handle first collision or iterate all, depends on gameplay). Damage calculation example: iterate all collisions (For i = 0 To b3dCountCollisions(entity) - 1), get impulse (impulse = b3dCollisionImpulse(entity, i)), calculate damage (damage = impulse * damageMultiplier), apply total damage (sum damage from all collisions, apply to entity health). Multiple impact handling: cluster collisions (explosions, multiple debris hits at once), count collisions (count = b3dCountCollisions(entity)), threshold response (If count > 3 Then major impact, spawn particles, play heavy sound), scale effects (more collisions = bigger effect). Collision filtering: check specific entity (For i = 0 To count - 1, check b3dCollisionEntity(entity, i)), find target collision (If collision entity = targetHandle Then found specific collision), selective response (only process certain collision types, ignore others).

Frame lifecycle: frame start (g_entityCollisions.clear() removes all previous collisions), physics update (Jolt updates, ContactListener fires OnContactAdded for new contacts), collision recording (ContactListener stores CollisionData in g_entityCollisions for both entities), query collisions (user code calls b3dCountCollisions, b3dCollisionX/Y/Z, etc.), next frame start (clear collisions, repeat cycle). New contacts only: OnContactAdded fires once (when bodies first touch, initial contact), OnContactPersisted ignored (continuous contact, bodies still touching but not new), new frame new detection (if bodies separate and re-collide, new contact again), one-frame lifetime (collision data exists for single frame, cleared next frame). Persisting contacts: bodies continuously touching (standing on ground, pressed against wall), not re-counted each frame (OnContactPersisted doesn't add new collision), detected only on first contact (initial touch generates collision, continuous contact silent), separate and re-collide (if bodies separate and touch again, new collision recorded). Bidirectional recording: both entities see collision (entityA records collision with entityB, entityB records collision with entityA), symmetric data (same position, same impulse, flipped normal), independent queries (query either entity, get collision from their perspective). Normal direction: normal points away from surface (normal direction relative to querying entity), entityA normal points out of surface toward A (positive direction from collision surface), entityB normal flipped (negative of entityA normal, points toward B), use for response (apply force along normal, bounce or slide direction).

Index range: valid indices 0 to count-1 (zero-based array indexing), negative index returns 0 (b3dCollisionX/Y/Z/etc. clamp to 0), index >= count returns 0 (out of bounds, default value), typical loop (For i = 0 To b3dCountCollisions(entity) - 1). Collision data queries: b3dCollisionX/Y/Z (world position of collision, contact point), b3dCollisionNX/NY/NZ (surface normal at collision, direction for response), b3dCollisionEntity (other entity handle, what was hit), b3dCollisionImpulse (impact magnitude, force of collision), all use same index (index 0 = first collision, index 1 = second, etc.). Entity not found: entity handle invalid (entity doesn't exist, or no physics body), function returns 0 (graceful failure, empty collision count), check entity first (ensure entity exists and has physics body before querying). No physics body: entity without physics body (decorative mesh, light, camera), never has collisions (no entry in Jolt physics system, ContactListener never fires), always returns 0 (no physics = no collisions detected). Multiple simultaneous collisions: entity collides with multiple objects (car hits multiple debris pieces, explosion affects multiple objects), each collision separate entry (one CollisionData per contact, independent details), count = number of contacts (count 5 = hit 5 different objects or 5 different contact points).

Performance: O(1) lookup (unordered_map find operation, constant time), mutex lock cost (minimal overhead, fast lock/unlock), typical <0.001ms (very fast, safe to call every frame for many entities), hundreds of entities (check collisions for 100+ entities per frame, negligible cost). ContactListener overhead: runs on physics threads (Jolt internal threading, parallel collision detection), mutex-protected writes (thread-safe collision recording, minimal contention), adds to g_entityCollisions (vector push_back, fast O(1) amortized). Collision clearing: clears all collisions (g_entityCollisions.clear() removes all entries), happens once per frame (at start of UpdatePhysicsSystem, before Jolt update), fresh slate (each frame starts with empty collision map, no lingering old collisions). Memory usage: g_entityCollisions map (entityHandle -> vector<CollisionData>), each CollisionData 44 bytes (int + Vec3*2 + float = 4 + 12*2 + 4 + padding), typical memory (10 entities * 2 collisions each * 44 bytes = ~1KB, negligible), cleared each frame (memory freed, no accumulation). Use with b3dEntityCollided: b3dCountCollisions checks if any collision (count > 0 means something hit), b3dEntityCollided checks specific entity (did entityA collide with entityB, boolean query), count for iteration (loop through all collisions, process each), b3dEntityCollided for specific (check if specific entity pair collided, single check).

Typical usage patterns: impact feedback (If b3dCountCollisions(player) > 0 Then play impact sound, camera shake), damage from collisions (For each collision, calculate damage based on impulse, apply to health), spawn particles (For each collision, spawn particles at collision position, use collision normal for direction), collision sounds (play sound at collision position, pitch/volume based on impulse), state changes (If collided Then change entity state, trigger animations or behaviors). Edge cases: entity collides with itself (shouldn't happen, Jolt filters self-collisions, but if compound bodies check), entity destroyed during frame (handle may become invalid, check entity exists before processing collisions), very high collision counts (explosions or dense clusters may generate many collisions, clamp or limit processing). Validation: returns 0 if entity not in map (no collisions recorded, or entity invalid), returns vector size if found (collision count, 0-N range), no error checking (assumes entity handle reasonable, graceful failure for invalid handles). Related: b3dCollisionX/Y/Z get collision position (world space contact point, index 0 to count-1), b3dCollisionNX/NY/NZ get collision normal (surface normal, direction away from surface), b3dCollisionEntity get other entity (what was hit, entity handle), b3dCollisionImpulse get impact force (collision strength, damage calculation), b3dEntityCollided check specific pair (did entityA collide with entityB, boolean).