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](scripts/stealth_patterns.gd) — space-state LoS, cone DOT, hearing helpers

> 2. [stealth_ai_controller.gd](scripts/stealth_ai_controller.gd) — multi-sample rays + RID exclude + path-length hearing

> 3. [stealth_vision_cone.gd](scripts/stealth_vision_cone.gd) / [vision_cone_3d.gd](scripts/vision_cone_3d.gd) — cone authorship

Original Expert Patterns

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

Modular Components

• [stealth_vision_cone.gd](scripts/stealth_vision_cone.gd) - 2D/logic cone helpers.
• [vision_cone_3d.gd](scripts/vision_cone_3d.gd) - 3D cone debug / query helpers.
• [visibility_manager.gd](scripts/visibility_manager.gd) - Player exposure / light gem aggregation.
• [light_detector.gd](scripts/light_detector.gd) - Light probe / overlap exposure.
• [sound_occlusion_manager.gd](scripts/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

| Need | Action |

|------|--------|

| LoS + exclude self/player RIDs | MANDATORY [stealth_ai_controller.gd](scripts/stealth_ai_controller.gd) + [stealth_patterns.gd](scripts/stealth_patterns.gd) |

| Light-scaled detection | [visibility_manager.gd](scripts/visibility_manager.gd) / [light_detector.gd](scripts/light_detector.gd) |

| Hearing through geometry | Path-length via NavigationServer (controller) + [sound_occlusion_manager.gd](scripts/sound_occlusion_manager.gd) |

When to load modules

| Task | Load |

|------|------|

| Guard AI spine | patterns + ai_controller |

| Author cones | vision_cone scripts |

| Player light gem | visibility + light_detector |

| Loud world props | sound_occlusion_manager |

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

Skill Chain

| Phase | Skills | Purpose |

|-------|--------|---------|

| 1. Physics | godot-raycasting-queries | Space-state LoS |

| 2. Nav | godot-navigation-pathfinding | Investigate / path hearing |

| 3. AI | godot-state-machine-advanced | IDLE→ALERT FSM |

| 4. Audio | godot-audio-systems | AI_Audible buses |

| 5. Balance | godot-monte-carlo-balancer | Detection thresholds |

Common Pitfalls

| Pitfall | Solution |

|---------|----------|

| RayCast3D per guard | Multi-sample intersect_ray + RID exclude |

| distance_to hearing | Navigation path length |

| Off-screen CPU | VisibleOnScreenNotifier suspend |

Deep recipes (on demand)

| Topic | Reference / script |

|-------|-------------------|

| Design pillars | [design-principles.md](references/design-principles.md) |

| Vision / sound / light | [ai-detection-system.md](references/ai-detection-system.md) + [stealth_ai_controller.gd](scripts/stealth_ai_controller.gd) |

| Alert FSM & UI feedback | [alert-states.md](references/alert-states.md) + [visibility_manager.gd](scripts/visibility_manager.gd) |

| Player tools (lean, gadgets) | [player-abilities.md](references/player-abilities.md) |

| Cover & encounter layout | [level-design.md](references/level-design.md) |

| UI communication | [ui-communication.md](references/ui-communication.md) |

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Ray-casting — Node casts vs PhysicsDirectSpaceState3D.intersect_ray() for many AI LoS checks without RayCast3D spam.
• Physics introduction — collision layers/masks that filter vision rays, hearing spheres, and corpse layers.
• PhysicsDirectSpaceState3D — nodeless intersect_ray / intersect_shape contracts for composite vision and cover verification.
• PhysicsRayQueryParameters3D — mask, exclude RIDs, and collide flags so guards never self-block LoS queries.
• Lights and shadows — Omni/Spot energy and shadows that drive light-gem exposure and shadow-layer hiding.
• Audio buses — dedicated AI-audible buses so loud footsteps/impacts route into hearing systems.
• Navigation introduction (3D) — regions, agents, and async bake for patrols and investigate paths.
• Using navigation paths — path length as wall-aware sound travel instead of raw distance_to().
• NavigationServer3D — map_get_path, random cover points, and avoidance masks for investigating guards.
• Groups — guards / player / lights groups and call_group for base-wide alarms without hardcoded arrays.
• VisibleOnScreenNotifier3D — pause heavy detection when off-screen so distant AI do not burn the physics budget.
• Screen-reading shaders — hint_screen_texture vision-cone feedback overlays (not Godot 3 SCREEN_TEXTURE).

Related Skills

Prerequisites

• godot-project-foundations — scene tree, groups, and import/project setup before wiring guards, lights, and player sample points.
• godot-physics-3d — CharacterBody3D, layers/masks, and collision shapes that vision rays and hearing volumes must hit honestly.
• godot-raycasting-queries — PhysicsServer query parameters, RID excludes, and multi-sample LoS recipes this genre depends on every frame.

Complements

• godot-navigation-pathfinding — NavigationAgent patrols, investigate targets, and path-length hearing that respects walls.
• godot-ai-navigation — FOV sensors and perception stacks that feed suspicion/alert state machines.
• godot-audio-systems — 3D streams and bus layouts for AI-audible noise without coupling to player SFX buses.
• godot-3d-lighting — light energy, shadows, and probe setups that make light-level detection fair and readable.
• godot-state-machine-advanced — StringName IDLE/SUSPICIOUS/ALERTED/COMBAT machines instead of ad-hoc string compares.
• godot-signal-architecture — alert_state_changed and detection-meter signals that keep UI, barks, and AI decoupled.
• godot-shaders-basics — screen-space cone tint and outline feedback so players always see why they were spotted.
• godot-camera-systems — lean/peek and frustum-driven VisibleOnScreenNotifier suspend for off-screen guard budgets.
• godot-monte-carlo-balancer — simulate detection rates, FOV ranges, hearing falloff, and forgiveness windows before shipping difficulty.

Downstream / consumers

• godot-genre-horror — stalker cones, hiding spots, and suspicion meters that reuse sensory AI patterns.
• godot-combat-system — lethal escalation and takedown windows once ALERTED/COMBAT breaks the stealth loop.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.