b3dPhysicsEntityPick

Physics-based entity forward raycast (raycasts in entity's forward direction based on rotation). Takes entity (entity handle to cast from), range (maximum distance to check), layerMask (0=all layers, reserved for future). Returns entity handle if hit (0 if no hit). Calculates forward direction from entity pitch/yaw, raycasts from entity position, calls b3dPhysicsLinePick with calculated ray. Use for AI line-of-sight, sensor detection, forward collision checks, or entity-based targeting.

This function performs entity-based physics raycast. Entity picking: raycasts in entity's forward direction (based on entity rotation, automatic direction calculation), ray origin = entity position (entity.position.x/y/z, center of entity), ray direction = entity forward (calculated from pitch and yaw, normalized forward vector), ray length = range (user-specified max distance, units). Forward direction calculation: forward from pitch/yaw (forwardX = sin(yaw) * cos(pitch), forwardY = -sin(pitch), forwardZ = cos(yaw) * cos(pitch)), ignores roll (roll doesn't affect forward direction, only up vector), unit vector (forward direction normalized, magnitude = 1.0), scaled by range (direction * range = endpoint offset). Use cases: (1) AI line-of-sight (NPC vision checks, enemy detection), (2) Sensor raycast (trigger when entity detects object ahead), (3) Forward collision (check obstacles in front of entity), (4) Targeting system (entity aims at target, raycast confirms hit), (5) Proximity detection (entity detects nearby objects forward). Common patterns: AI vision visible = b3dPhysicsEntityPick(npcEntity, 50, 0) check 50 units ahead, sensor detection obstacle = b3dPhysicsEntityPick(car, 10, 0) check 10 units for collision, targeting confirmed = b3dPhysicsEntityPick(turret, 100, 0) confirm target in sights. Typical usage: call every frame for AI (continuous vision checks, detect player or threats), call for sensor triggers (proximity sensors, collision avoidance), combine with entity rotation (entity aims, raycast confirms hit).

Forward vector calculation: pitch rotation (rotates around X axis, tilts up/down), yaw rotation (rotates around Y axis, turns left/right), roll ignored (doesn't affect forward direction, only used for up vector), Euler to direction (standard pitch/yaw to forward vector, trigonometric conversion). Coordinate system: X axis east-west (positive X = east, negative X = west), Y axis up-down (positive Y = up, negative Y = down), Z axis north-south (positive Z = north, negative Z = south), left-handed Y-up (DirectX standard, Z forward default). Pitch angle: 0 degrees horizontal forward (level, no tilt), positive pitch up (entity tilted upward, forward vector points up), negative pitch down (entity tilted downward, forward vector points down), typical range -90 degrees to +90 degrees (straight down to straight up). Yaw angle: 0 degrees north/forward (+Z direction, default forward), 90 degrees east (+X direction, turned right), 180 degrees south (-Z direction, turned around), -90 degrees or 270 degrees west (-X direction, turned left). Range parameter: max raycast distance (units from entity position, ray length), longer range = further detection (100 units = long-range sensor), shorter range = close detection (5 units = proximity check), typical ranges (5-20 for collision avoidance, 20-100 for AI vision, 100+ for targeting).

AI line-of-sight example: NPC checks if player visible (every frame, continuous check), calculate direction to player (optional, pre-check distance and angle), raycast forward (visible = b3dPhysicsEntityPick(npc, visionRange, 0)), check hit entity (If visible = playerHandle Then see player, chase or attack), occlusion detection (wall blocks LOS, raycast hits wall first). Sensor raycast example: car has forward sensor (collision avoidance, autonomous driving), raycast ahead (obstacle = b3dPhysicsEntityPick(car, 10, 0) 10 units forward), check obstacle (If obstacle > 0 Then apply brakes, slow down or stop), dynamic collision avoidance (react to obstacles, steer or brake). Targeting system example: turret aims at target (rotation toward target, tracking), raycast forward (confirmed = b3dPhysicsEntityPick(turret, 100, 0)), check hit (If confirmed = targetHandle Then fire weapon, target in sights), confirms unobstructed shot (raycast hits target directly, no obstacles between). Proximity trigger example: entity detects objects ahead (trigger zone forward of entity), raycast forward (detected = b3dPhysicsEntityPick(triggerEntity, 5, 0) short-range), trigger event (If detected > 0 Then activate event, trigger response), directional trigger (only detects objects in forward direction, ignores behind). Forward collision check example: character moving forward (check obstacles before moving), raycast ahead (collision = b3dPhysicsEntityPick(character, moveSpeed * deltaTime + 1, 0)), prevent movement (If collision > 0 Then stop movement, collision avoidance), smooth movement (no clipping through walls, physics-based collision).

Entity validation: checks entity exists (g_entities.find(entityHandle), returns 0 if not found), doesn't check entity type (any entity type allowed, uses position and rotation), entity position (origin of raycast, center of entity), entity rotation (pitch and yaw define forward direction). Ray origin: entity position (entity.position.x/y/z, world space coordinates), ray starts at entity center (not offset, origin = entity position), typical use (entity eye position may differ, adjust origin if needed for character eyes). Ray direction: calculated forward vector (sin(yaw)*cos(pitch), -sin(pitch), cos(yaw)*cos(pitch)), unit direction (normalized forward, magnitude = 1.0), scaled by range (direction * range = endpoint offset, total ray length = range). Delegation to line pick: calls b3dPhysicsLinePick internally (originX/Y/Z = entity position, dx/dy/dz = forward * range), inherits line pick behavior (same hit detection, same result structure, same limitations), convenience wrapper (automates forward calculation, simpler interface for entity-based queries).

Range vs direction: range defines max distance (how far to check, units), direction always forward (based on entity rotation, automatic), endpoint = position + forward * range (absolute ray endpoint, where ray stops). Hit details: same as b3dPhysicsLinePick (g_lastPickResult stores position, normal, distance), b3dPickedX/Y/Z world position (intersection point, where ray hit), b3dPickedTime distance (units from entity, hit depth), access immediately (read after raycast, before next pick call). Shared result structure: g_lastPickResult shared (all physics pick functions use same result), overwritten by next pick (any pick function resets result, not persistent), read immediately (If hit Then hitPos = b3dPickedX(), don't delay). Performance: forward calculation (simple trigonometry, negligible cost <0.001ms), raycast cost (b3dPhysicsLinePick, fast ~0.01ms), total cost (acceptable for per-frame or multiple entities, hundreds per frame possible), typical use (AI vision every frame, sensors continuous).

Entity-based vs line-based: entity-based (automatic forward direction, convenient for entity queries), line-based (manual ray, explicit origin and direction, lower-level control), entity-based for gameplay (AI vision, sensors, entity interactions), line-based for custom rays (arbitrary directions, non-entity raycasts). Entity-based vs camera-based: entity-based (raycasts from entity forward, entity rotation), camera-based (raycasts from camera through screen point, screen coordinates), entity-based for AI (NPC vision, entity sensors), camera-based for player input (mouse picking, click interaction). Physics vs mesh picking: physics (b3dPhysicsEntityPick) tests physics bodies only (fast, Jolt acceleration), mesh (b3dEntityPick) tests mesh triangles (slower, more accurate, all meshes), physics for gameplay (interactive physics objects, collision queries), mesh for precise picking (decorative objects, exact triangle hit). Layer mask: layerMask 0 = all layers (default, tests all physics bodies), layer filtering future feature (currently unused, reserved), all bodies tested (regardless of mask, filtering not implemented). No hit behavior: returns 0 if no hit (ray doesn't intersect any physics body, clear forward path), g_lastPickResult reset (empty result, default values), check return value (If hit = 0 Then path clear, no obstacle ahead).

AI vision pattern: call every frame (continuous vision check, detect player or threats), raycast forward (visible = b3dPhysicsEntityPick(npc, visionRange, 0)), check hit entity (If visible = playerHandle Then chase, else patrol), field-of-view (combine with angle check, ensure target in FOV cone before raycast). Sensor continuous pattern: call every frame (real-time sensor, collision avoidance), raycast forward (obstacle = b3dPhysicsEntityPick(vehicle, safeDistance, 0)), react to obstacle (If obstacle > 0 Then brake or steer, avoid collision), dynamic response (adjust speed based on distance, smoother avoidance). Targeting confirmation pattern: rotate toward target (entity aims, pitch and yaw toward target), raycast forward (hit = b3dPhysicsEntityPick(turret, weaponRange, 0)), confirm hit (If hit = targetHandle Then fire, target unobstructed), prevents friendly fire (raycast may hit ally, don't fire if ally in way). Forward path check pattern: before moving (check obstacles ahead, collision avoidance), raycast forward (blocked = b3dPhysicsEntityPick(entity, moveDistance, 0)), proceed if clear (If blocked = 0 Then move forward, else stop or turn), smooth navigation (no clipping, physics-based movement).

Multiple entity raycasts: can call for many entities (hundreds of AI entities per frame, acceptable performance), each entity independent (separate raycast, separate results), read results immediately (store hit before next raycast, per-entity hit data). Invalid entity handling: returns 0 if entity not found (invalid handle, entity doesn't exist), silent failure (graceful, no error messages), user responsible (ensure entity exists, valid handle). Range zero or negative: zero range returns 0 (no distance, ray length = 0, invalid), negative range (direction reversed, raycast backward, unconventional), typical positive range (5-100 units, forward raycast). Rotation-only: uses pitch and yaw (rotation.x and rotation.y, standard rotation), ignores roll (rotation.z not used, doesn't affect forward direction), forward vector (calculated from pitch/yaw only, roll for up vector). Entity type agnostic: works with any entity type (mesh, camera, light, pivot, all have position and rotation), doesn't require physics body (entity itself doesn't need physics, raycast detects physics bodies), flexible usage (any entity can perform raycast, check for physics objects ahead).

Offset origin: ray starts at entity position (center of entity, no offset), custom origin (add offset manually, e.g., eye position = entity.Y + eyeHeight), character eyes (adjust Y offset for character eye level, more realistic vision), weapon muzzle (adjust position for gun barrel, accurate weapon raycast). Direction override: function uses entity forward (automatic, based on rotation), custom direction (use b3dPhysicsLinePick instead, manual direction control), aim offset (if entity rotation doesn't match desired direction, rotate entity first). Real-time usage: safe to call every frame (performance acceptable, hundreds per frame), typical AI (10-50 NPCs with vision checks, <1ms total), sensors and triggers (real-time collision avoidance, continuous detection). Related: b3dPhysicsLinePick performs line raycast (lower-level, manual ray, this function calls it), b3dPhysicsCameraPick raycasts from camera through screen (camera-based, mouse picking), b3dEntityPick mesh-based entity raycast (triangle intersection, slower, all meshes), b3dPickedX/Y/Z/NX/NY/NZ/Time access hit details (result queries, shared across pick functions).