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

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.