ray-query-3d-picking-contract

name: ray-query-3d-picking-contract description: Specialized Tier 3 contract for deterministic 3D picking/LOS ray queries using Camera3D projection methods and PhysicsDirectSpaceState3D intersect_ray semantics. tier: tertiary godot_version: 4.6+ doc_anchors: - godot-docs/tutorials/physics/ray-casting.rst - godot-docs/classes/class_camera3d.rst - godot-docs/classes/class_physicsrayqueryparameters3d.rst - godot-docs/classes/class_physicsdirectspacestate3d.rst tags: - picking - raycast - physics depends_on: - godot-skills/godot-secondary/domain-gameplay-simulation/SKILL.md

3D Ray-Query Picking Contract

Use When

• Implementing mouse/controller picking on 3D boards.
• Building LOS/cover ray checks with deterministic filters.

Outcomes

• Ray origin/direction construction is consistent for all picking sources.
• Query filters and timing boundaries are explicit and deterministic.
• Hit-to-domain conversion remains stable for gameplay logic.

Required Rules

• Build rays from Camera3D.project_ray_origin() plus project_ray_normal().
• Run world-space ray queries through get_world_3d().direct_space_state.intersect_ray(...).
• Use PhysicsRayQueryParameters3D with explicit collision mask and exclusions.
• Avoid querying physics space from unsafe timing; schedule queries on physics-safe cadence.
• Define deterministic tie-break/ordering when multiple checks feed gameplay decisions.

Workflow

1. Define input source and camera projection strategy.
2. Build ray query parameters with explicit mask/exclusion policy.
3. Execute queries in physics-safe cadence and capture hit results.
4. Convert hits to domain coordinates with deterministic tie-breaks.
5. Emit debug traces for query/hit conversion boundaries.

Validation

• Repeated identical camera/input states produce identical pick targets.
• Collision mask and exclusion changes are covered by targeted tests.
• Hit conversion diagnostics explain target selection and rejection.

Failure Modes

• Ray construction differs across input paths and yields inconsistent picks.
• Query timing violates physics constraints and causes intermittent misses.
• Multiple hit candidates resolve without explicit ordering policy.

Local Doc Anchors

• godot-docs/tutorials/physics/ray-casting.rst
• godot-docs/classes/class_camera3d.rst
• godot-docs/classes/class_physicsrayqueryparameters3d.rst
• godot-docs/classes/class_physicsdirectspacestate3d.rst