b3dPhysicsLinePick

Physics-based line raycast (origin+direction, faster than mesh picking, only detects physics bodies). Takes x,y,z (ray origin world position), dx,dy,dz (ray direction vector, length = max distance), layerMask (0=all layers, layer filtering reserved for future). Returns entity handle if hit (0 if no hit). Uses Jolt spatial acceleration for fast broad-phase, stores hit details in g_lastPickResult (access via b3dPickedX/Y/Z/NX/NY/NZ/Time). Use for fast physics queries, line-of-sight checks, hitscan weapons, or collision detection.

This function performs physics raycast. Physics-based raycasting: uses Jolt physics spatial acceleration (broad-phase BVH tree, narrow-phase shape queries), much faster than mesh-based picking (b3dLinePick/CameraPick/EntityPick iterate triangles, slower), only detects physics bodies (entities with b3dCreatePhysicsBody, ignores non-physics meshes), returns closest hit along ray (nearest intersection, ignores further hits). Ray parameters: origin (x,y,z) start point in world space, direction (dx,dy,dz) ray direction vector (magnitude = max distance, not normalized), ray length calculated from direction magnitude (length = sqrt(dx^2 + dy^2 + dz^2)), zero-length ray returns 0 (dx=dy=dz=0 invalid, no raycast). Layer mask: layerMask 0 = all layers (default, tests all physics bodies), layer filtering future feature (currently unused, reserved for collision layers), all bodies tested regardless of mask (filtering not yet implemented). Use cases: (1) Hitscan weapons (instant-hit bullets, laser beams), (2) Line-of-sight checks (AI vision, enemy detection), (3) Trigger detection (activate when ray hits target), (4) Fast collision queries (alternative to overlap tests), (5) Targeting systems (crosshair hit detection, aim assist). Common patterns: forward raycast ray = b3dPhysicsLinePick(x, y, z, forwardX * 100, forwardY * 100, forwardZ * 100, 0) 100 units forward, downward raycast ground = b3dPhysicsLinePick(x, y, z, 0, -10, 0, 0) 10 units down for ground check, weapon fire hit = b3dPhysicsLinePick(gunX, gunY, gunZ, aimDx * 1000, aimDy * 1000, aimDz * 1000, 0) long-range shot. Typical usage: call for gameplay queries (weapon fire, line-of-sight, targeting), call every frame for continuous checks (ground detection, aim tracking), combine with b3dPickedX/Y/Z for hit position.

Raycast algorithm: Jolt CastRay narrow-phase query (spatial acceleration structure, fast broad-phase culling), ClosestHitCollector (captures nearest hit, ignores further hits), RayCastResult stores hit fraction (distance along ray 0.0-1.0, 0.0=origin 1.0=endpoint), maps BodyID to entity handle (reverse lookup in g_entityToBody, finds entity from physics body). Ray direction: dx,dy,dz is direction vector (not unit vector, magnitude matters), ray length = vector magnitude (distance = sqrt(dx^2 + dy^2 + dz^2)), normalized internally (direction / length creates unit vector for Jolt), endpoint = origin + direction (ray travels from origin to origin + (dx,dy,dz)). Hit detection: tests all physics bodies (static and dynamic bodies, kinematic characters excluded), broad-phase filter (DefaultBroadPhaseLayerFilter tests layer compatibility), narrow-phase shape query (exact intersection test against body shapes), returns closest hit (minimum fraction along ray, nearest intersection). Hit details stored: g_lastPickResult shared with mesh picking (same result structure, compatible queries), position = origin + direction * fraction (world space hit point, exact intersection), normal = -rayDirection (approximate normal pointing back toward ray, reverse of ray direction), time = length * fraction (distance from origin to hit, world units), entity handle (physics body entity, mapped from BodyID). Zero-length ray: dx=dy=dz=0 returns 0 (invalid ray, no direction), length < 0.001 returns 0 (nearly zero, avoid precision issues), typical minimum 0.01 units (very short but valid ray).

Hitscan weapon example: player fires weapon (instant-hit bullet, no projectile travel time), raycast from gun (hit = b3dPhysicsLinePick(gunX, gunY, gunZ, aimDx * 1000, aimDy * 1000, aimDz * 1000, 0) 1000 units max), check hit (If hit > 0 Then damage entity, apply bullet impact), instant hit detection (no projectile physics, immediate feedback). Line-of-sight example: AI checks if player visible (vision cone check first, then raycast), raycast to player (visible = b3dPhysicsLinePick(aiX, aiY, aiZ, dx, dy, dz, 0) where direction = player - AI), check hit entity (If visible = playerHandle Then see player, Else obstruction blocks view), occlusion detection (walls block sight, line-of-sight fails). Ground detection example: check ground below character (raycast downward from character position), raycast down (ground = b3dPhysicsLinePick(charX, charY, charZ, 0, -10, 0, 0) 10 units down), check hit (If ground > 0 Then grounded = True, groundY = b3dPickedY()), continuous ground tracking (call every frame for accurate ground state). Targeting system example: crosshair points at target (screen-to-world ray from camera), player aims (crosshair on screen), raycast forward (target = b3dPhysicsLinePick(camX, camY, camZ, forwardDx * 500, forwardDy * 500, forwardDz * 500, 0)), display target info (If target > 0 Then show target name, distance = b3dPickedTime()), aim assist or UI feedback. Trigger activation example: ray detects object in range (trigger when ray hits specific entity), raycast forward (detected = b3dPhysicsLinePick(sensorX, sensorY, sensorZ, rangeDx, rangeDy, rangeDz, 0)), check detected entity (If detected = triggerTarget Then activate event), proximity sensor or switch.

Ray vs mesh picking: physics raycast (b3dPhysicsLinePick) tests physics bodies only (b3dCreatePhysicsBody entities, ignores non-physics meshes), mesh raycast (b3dLinePick) tests mesh triangles (all meshes regardless of physics, slower but more accurate), physics faster (Jolt spatial acceleration, broad-phase culling very efficient), mesh more accurate (exact triangle intersection, per-vertex precision). When to use physics: fast queries (performance critical, frequent raycasts), physics-only detection (only care about physics bodies, ignore decorative meshes), gameplay mechanics (weapons, line-of-sight, triggers use physics), typical use (most gameplay systems use physics raycasts). When to use mesh: precise picking (mouse picking UI, precise object selection), non-physics objects (decorative meshes, static geometry without physics), triangle-level precision (need exact triangle hit, surface index data), editor tools (selection, manipulation, precise queries). Physics body requirement: entity must have physics body (b3dCreatePhysicsBody called, body exists in Jolt system), non-physics entities ignored (decorative meshes, lights, cameras not detected), static or dynamic (both static and dynamic bodies detected, kinematic not tested). Body mapping: maps BodyID to entity handle (reverse lookup in g_entityToBody map), finds entity from physics body (for each pair, check if BodyID matches hit body), returns 0 if not found (shouldn't happen, indicates orphaned body), entity handle returned (same handle from b3dLoadEntity/b3dCreateEntity).

Hit position access: b3dPickedX/Y/Z() returns world position (exact intersection point, calculated from fraction), position = origin + direction * (length * fraction) (scales direction by distance ratio, adds to origin), accurate to float precision (typical +/-0.0001 units). Hit normal access: b3dPickedNX/NY/NZ() returns approximate normal (points back toward ray origin, -rayDirection), simplified normal (true normal requires shape query at hit point, expensive), sufficient for most use cases (visual effects, reflection direction, impact orientation), for precise normal (query shape at hit point separately, more accurate but slower). Hit distance access: b3dPickedTime() returns distance from origin (world units, length * fraction), time = length * fraction (fraction 0.0-1.0 scaled by ray length), typical use (display distance to target, range checks, falloff calculations). Hit details persistence: g_lastPickResult overwritten by next pick call (any pick function resets result, not persistent), read immediately after raycast (If hit Then x = b3dPickedX(), don't delay), shared with mesh picking (b3dLinePick/CameraPick/EntityPick use same result structure). No hit behavior: returns 0 if no hit (ray doesn't intersect any physics body, clear line), g_lastPickResult reset (empty result, default values), b3dPickedX/Y/Z return 0.0 (default position, invalid), check return value (If hit = 0 Then no hit, skip b3dPicked calls).

Direction normalization: direction normalized internally (rayDirection = direction / length, unit vector), user provides direction vector (dx,dy,dz, magnitude = max distance), endpoint = origin + (dx,dy,dz) (ray travels exactly to specified endpoint), length matters (long vector = long ray, short vector = short ray). Max distance: ray length = direction magnitude (distance = sqrt(dx^2 + dy^2 + dz^2)), longer direction = further ray (1000 units forward = long-range ray), shorter direction = closer ray (10 units forward = short-range ray), typical ranges (10-100 for ground checks, 100-1000 for weapons, 1000+ for long-range). Ray endpoint: endpoint = origin + direction (absolute endpoint position, ray stops here), ray tests from origin to endpoint (all bodies along line segment), doesn't extend beyond endpoint (capped at direction length). Jolt spatial acceleration: broad-phase BVH (bounding volume hierarchy, fast spatial queries), culls non-intersecting bodies (tests AABB first, skips distant bodies), narrow-phase shape query (precise intersection test, only for broad-phase candidates), very fast (thousands of raycasts per frame, typical cost <0.01ms per raycast). Comparison with overlap: raycast tests line segment (infinite thin line, no volume), overlap tests volume (sphere, box, capsule), raycast faster (simpler query, line vs volume), overlap detects area (multiple bodies, all within volume), use raycast for line queries (weapons, line-of-sight), use overlap for area queries (explosions, triggers).

BodyID mapping: g_entityToBody maps entity to BodyID (forward lookup, entity -> physics body), reverse lookup for raycast hit (iterate map, find entity where BodyID matches hit), O(N) reverse lookup (linear search through map, typically fast <100 entities), cached in future (could optimize with reverse map, currently acceptable performance). Collector pattern: ClosestHitCollector (custom collector, captures nearest hit), AddHit callback (called for each hit, updates if closer), mFraction comparison (hit.mFraction < closest.mFraction, stores minimum), returns single closest hit (ignores all further hits, only nearest matters). RayCastSettings: default settings (no special flags, standard raycast), could customize (backface culling, filter by type, currently unused), future extensions (layer filtering, ignore flags, custom filters). Broadphase and object filters: DefaultBroadPhaseLayerFilter (tests layer compatibility, currently all layers), DefaultObjectLayerFilter (tests object layer, currently MOVING layer), BodyFilter and ShapeFilter empty (no custom filtering, test all bodies), future layer system (collision layers, filter by mask). Performance: O(log N) broad-phase (BVH tree traversal, spatial acceleration), O(M) narrow-phase (M = broad-phase candidates, shape tests), typical <0.01ms per raycast (very fast, thousands per frame possible), much faster than mesh picking (mesh O(N triangles), physics O(log N bodies)).

Validation: returns 0 if no physics system (g_physicsSystem null, physics not initialized), returns 0 if zero-length ray (dx=dy=dz=0 or length < 0.001, invalid), returns 0 if no hit (ray doesn't intersect any body, miss), silent failure (no error messages, graceful failure). Related: b3dPhysicsCameraPick raycasts from camera through screen point (unprojection, camera-based picking), b3dPhysicsEntityPick raycasts forward from entity (entity-based, forward direction), b3dLinePick mesh-based line raycast (triangle intersection, slower), b3dPickedX/Y/Z/NX/NY/NZ/Time access hit details (result queries, shared across pick functions).