Godot Genre Stealth

NEVER Do (Expert Anti-Patterns)

Detection & Awareness

• NEVER use binary "Seen/Not Seen" detection; strictly use a Gradual Detection Meter (0-100%) that builds based on distance, light level, and speed.
• NEVER use standard RayCast3D nodes for massive amounts of vision checks; strictly use PhysicsDirectSpaceState3D.intersect_ray() to query the PhysicsServer instantly and nodelessly.
• NEVER allow AI to see through solid geometry; strictly use raycasts between AI eyes and player sample points (Head/Torso/Feet).
• NEVER use a single sample point for visibility; strictly sample at least 3 points (Head, Torso, Feet) to prevent detection bugs when partially in cover.
• NEVER use static "Guard Paths"; strictly implement Dynamic Investigating where guards leave their route to check on suspicious sounds/activities.
• NEVER trigger "Detection" immediately upon line-of-sight; strictly use a Detection Meter with a decay rate to provide a "forgiveness window" for the player to recover.
• NEVER assume a random navmesh point is safe; strictly verify cover points by Raycasting toward the Threat to ensure geometry successfully breaks the line of sight.
• NEVER forget to pass the guard's own RID into the raycast exclude array; if omitted, the ray will hit the guard's own body, causing false blocking.
• NEVER run complex AI detection for off-screen guards; strictly use VisibleOnScreenNotifier3D to pause heavy logic for distant enemies.

Systemic & World Logic

• NEVER use a simple distance_to() check for hearing; strictly calculate sound travel along the Navigation Path to determine if a wall blocks noise.
• NEVER make combat as viable as stealth; strictly ensure "going loud" triggers intense reinforcements or high-lethality states to preserve the stealth loop.
• NEVER hide the "Why" of detection; strictly provide immediate feedback via UI icons (?, !) or audio barks ("What was that?").
• NEVER ignore the return value of intersect_ray(); strictly check is_empty() first to prevent runtime crashes.
• NEVER assume a raycast won't hit the guard itself; strictly exclude the guard's RID from Query Parameters.

Optimization & Performance

• NEVER tightly couple AI to player scripts; strictly use duck-typing (e.g., if body.has_method("get_detected")) so guards can spot decoys or dead bodies without brittle dependencies.
• NEVER maintain hardcoded arrays to trigger base-wide alarms; strictly add guards to a "guards" group and use get_tree().call_group() for dynamic notification.
• NEVER use standard Strings for AI state; strictly use StringName (&"alert") for O(1) pointer-level comparisons in high-frequency loops.
• NEVER bake massive NavigationMeshes synchronously; strictly use use_async_iterations to prevent main thread stalls during runtime bakes.
• NEVER rely on Node.find_child() during gameplay; strictly use Groups or exported references for O(1) player tracking.
• NEVER leave CollisionShapes enabled on incapacitated bodies; strictly disable them or move them to a "corpse" layer to prevent pathing interference.

---

🛠 Expert Components (scripts/)

MANDATORY reads before implementing the matching system:

1. stealth_patterns.gd — space-state LoS, cone DOT, hearing helpers
2. stealth_ai_controller.gd — multi-sample rays + RID exclude + path-length hearing
3. stealth_vision_cone.gd / vision_cone_3d.gd — cone authorship

Original Expert Patterns

• stealth_patterns.gd - Nodeless LoS, cone tests, AI_Audible bus, async investigate.
• stealth_ai_controller.gd - Alert meter AI using PhysicsDirectSpaceState (not RayCast3D nodes).

Modular Components

• stealth_vision_cone.gd - 2D/logic cone helpers.
• vision_cone_3d.gd - 3D cone debug / query helpers.
• visibility_manager.gd - Player exposure / light gem aggregation.
• light_detector.gd - Light probe / overlap exposure.
• sound_occlusion_manager.gd - Occlusion / bus routing for AI hearing.

---

Core Loop

1. Hide / move → 2. Vision & light exposure → 3. Sound propagation → 4. Alert escalation → 5. Investigate / escape

Decision Trees

Perception

When to load modules

Do not paste long vision/alert/ability tutorials into the skill body — keep decision trees here and implement from scripts.

Skill Chain

Common Pitfalls