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
RayCast3Dnodes for massive amounts of vision checks; strictly usePhysicsDirectSpaceState3D.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
VisibleOnScreenNotifier3Dto 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 checkis_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_iterationsto 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:
- stealth_patterns.gd — space-state LoS, cone DOT, hearing helpers
- stealth_ai_controller.gd — multi-sample rays + RID exclude + path-length hearing
- 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
- 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 + stealth_patterns.gd |
| Light-scaled detection | visibility_manager.gd / light_detector.gd |
| Hearing through geometry | Path-length via NavigationServer (controller) + 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 |
| Vision / sound / light | ai-detection-system.md + stealth_ai_controller.gd |
| Alert FSM & UI feedback | alert-states.md + visibility_manager.gd |
| Player tools (lean, gadgets) | player-abilities.md |
| Cover & encounter layout | level-design.md |
| UI communication | 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.
