b3dCollisionTime

Returns collision time (0.0-1.0) for a specific collision event. Takes entity (entity handle), index (collision event index 0-based). Returns collision time as Double (0.0 = start of movement, 1.0 = end of movement, 0.0 on error). Reads from entity.collisions[index].time field.

This function retrieves time. Collision time: interpolation factor along movement ray (0.0 to 1.0 range), 0.0 = collision at start position (overlap at start), 1.0 = collision at end position (barely touching at destination), 0.5 = collision halfway through movement, represents when during the frame the collision occurred. Time calculation: swept collision detection traces entity movement from prevPosition to position, finds first intersection along ray, stores time value where intersection occurred, time = distance_to_collision / total_movement_distance. Use cases: (1) Temporal ordering (determine which collision happened first when multiple collisions occur), (2) Precise collision response (interpolate position to exact collision point), (3) Impact velocity calculation (compute velocity at collision time), (4) Multi-collision handling (process collisions in chronological order), (5) Animation synchronization (trigger effects at exact collision moment). Common patterns: earliest collision = find min(b3dCollisionTime(entity,i)) across all collisions, interpolate position = prevPos + (currPos - prevPos) * collisionTime, impact moment = if collisionTime < 0.1 then "hit at start", velocity at impact = movementVector * (1.0 - collisionTime). Typical usage: call after b3dEntityCollided returns collision count, iterate collision indices 0 to count-1, read time for each collision to determine sequence. Collision info array: entity.collisions stores all collisions from current frame, index parameter selects which collision (0 = first, 1 = second, etc.), array cleared at start of each frame before collision detection, populated during collision response in collideEntity(). Index validation: returns 0.0 if index < 0, returns 0.0 if index >= collision count, returns 0.0 if entity invalid, no error message for out-of-bounds (silent fail). Movement context: collision time only meaningful when entity moved during frame, if prevPosition == position then time is 0.0, swept collision detection used (continuous collision, not discrete), prevents tunneling through thin walls. Related collision queries: b3dCollisionX/Y/Z retrieves collision position (world coordinates where hit occurred), b3dCollisionNX/NY/NZ retrieves collision normal (surface direction at hit point), b3dCollisionEntity retrieves other entity handle (what was hit), b3dEntityCollided counts collisions of specific type (filtering by collision type). Example values: time=0.0 means entity started frame already overlapping obstacle, time=0.25 means collision 25% through movement, time=1.0 means collision at final position (barely touching). Collision ordering: lower time values = earlier collisions in movement sequence, process lowest time first for accurate response, helps with corner/edge cases where multiple surfaces hit. Performance: O(1) array access (no computation), negligible cost, just reading cached collision data from previous frame. Precision: double precision (64-bit float), accurate for fine-grained temporal analysis, sufficient for gameplay and physics needs. Default return: 0.0 on all error conditions (invalid entity, bad index, no movement), cannot distinguish error from legitimate 0.0 time, check b3dEntityCollided count first to validate index. Related: b3dEntityCollided counts collisions with type (determines valid index range), b3dCountCollisions gets total collision count (alternative to type-filtered count), b3dCollisions defines collision matrix (determines what collides).