godot-genre-horror

NEVER Do (Expert Anti-Patterns)

Atmosphere & Tension

• NEVER maintain 100% tension at all times; strictly use a Sawtooth Pacing model (buildup → peak/scare → dedicated relief period) to prevent player "numbing" and exhaustion.
• NEVER rely on jump-scares as the primary source of horror; focus on atmosphere, spatial audio cues, and the anticipation of a threat to build genuine dread.
• NEVER make environments pitch black to the point of frustrating navigation; darkness should obscure threats (details), not the floor. Use rim lighting or a limited-battery flashlight.
• NEVER grant the player unlimited resources; survival horror relies on Scarcity. Limited battery, rare ammo, and slow animations are mandatory to force stressful decision-making.

AI & Senses

• NEVER allow AI to detect the player instantly; implement a Suspicion Meter or a 1-3s reaction window before the AI enters full aggression to avoid "unfair cheating" feel.
• NEVER use predictable AI paths; an enemy on a perfect loop is a puzzle, not a predator. Use the Director to periodically "hint" a new destination near the player.
• NEVER use Area3D overlap signals for instant, frame-perfect Line-of-Sight (LoS) checks; use nodeless raycasting via PhysicsDirectSpaceState3D.intersect_ray() for fixed-physics sync.
• NEVER calculate complex AI vision or pathfinding for monsters far outside the camera's frustum; use VisibleOnScreenNotifier3D to disable processing logic.
• NEVER leave navigation avoidance layers unconfigured on chasing monsters; explicitly assign avoidance masks to prevent visual "stacking" in tight corridors.

Technical & Scarcity

• NEVER use the visual SceneTree (like GridContainer children) as the source of truth for inventory; strictly maintain a typed memory structure like Dictionary[StringName, Resource].
• NEVER rely on instantiating standard Nodes to store base item stats/definitions; use custom Resource scripts to reduce memory overhead and allow direct Inspector editing.
• NEVER forget to call duplicate(true) on an item's Resource when adding to inventory; if items have mutable states (ammo/durability), you will overwrite the global resource otherwise.
• NEVER parse massive JSON save files synchronously; strictly offload heavy parsing to the WorkerThreadPool to prevent auto-save freezes.
• NEVER use standard strings for hot-path IDs (states, item types); strictly use StringName (&"chasing") for pointer-speed comparisons.
• NEVER evaluate exact floating-point equality (sanity == 0.0); strictly use is_equal_approx() or threshold checks for deterministic triggers.
• NEVER write screen-reading shaders expecting Godot 3 SCREEN_TEXTURE; strictly use sampler2D with hint_screen_texture.
• NEVER instantiate detailed monster meshes or lights without culling; strictly configure visibility_range for automatic HLOD efficiency.
• NEVER rely on AnimationPlayer for random flickering; use Tween for programmatic, clean energy manipulation.
• NEVER load heavy scare scenes or 4K textures synchronously via load(); strictly use ResourceLoader.load_threaded_request() to prevent frame stalls.
• NEVER scale CollisionShape3D non-uniformly; strictly adjust internal shape resource parameters (radius, height) to prevent erratic physics.
• NEVER perform synchronous, heavy file I/O in a Safe Room; strictly use Thread and Mutex to handle background saving without stalling the main game thread.
• NEVER check for hiding spot types by casting; strictly use Object metadata (set_meta) for performant, decoupled AI queries.

---

🛠 Expert Components (scripts/)

Original Expert Patterns (MANDATORY at architecture steps)

• director_pacing.gd - Invisible orchestrator managing the "Sawtooth" tension wave and relief periods. MANDATORY before wiring any pacing/Director.
• predator_stalking_ai.gd - Dual-brain stalker (Director hints + honest senses) with view-cone avoidance. MANDATORY before implementing predator AI.

Modular Components

• monster_los_check.gd - Physics-synced raycasting for high-performance visibility checks.
• flashlight_flicker.gd - Procedural light interference for atmospheric tension.
• inventory_data_storage.gd - Typed data structure for sparse resource management.
• async_scare_loader.gd - Threaded resource loading for hitch-free jump-scares.
• spatial_noise_emitter.gd - Shape-based sound sensing for sensory AI.
• item_state_duplicator.gd - Deep duplication for managing unique weapon/item states.
• fog_claus_intensifier.gd - Volumetric fog manipulation for dread buildup.
• offscreen_logic_suspender.gd - Culling logic for AI processing outside camera view.
• sanity_shader_manager.gd - Instance-uniform driven distortion effects.
• sanity_manager.gd - Stress/sanity value pipeline feeding shake and audio buses.
• optimized_horror_state_machine.gd - High-speed predator behavior logic.

---

Core Loop

1. Explore: Player navigates a threatening environment.
2. Sense: Player hears/sees signs of danger.
3. React: Player hides, runs, or fights (disempowered combat).
4. Survive: Player reaches safety or solves a puzzle.
5. Relief: Brief moment of calm before tension builds again.

Skill Chain

Phase	Skills	Purpose
1. Atmosphere	godot-3d-lighting, godot-audio-systems	Volumetric fog, dynamic shadows, spatial audio
2. AI	godot-state-machine-advanced, godot-navigation-pathfinding, godot-raycasting-queries	Hunter AI, honest LoS/sound
3. Player	godot-camera-systems, godot-genre-stealth, godot-physics-3d	Lean/shake, hiding, CharacterBody3D movement
4. Scarcity	godot-inventory-system	Limited battery, ammo, health
5. Logic / saves	this skill's Director scripts + godot-save-load-systems	Sawtooth pacing + threaded safe-room saves

Do-NOT-Load (by fantasy)

Fantasy focus	Load	Do NOT load
Atmosphere / fog / flashlight only	fog_claus_intensifier.gd, flashlight_flicker.gd	Predator AI, LoS, noise, state machine
Stalker / dual-brain AI	director_pacing.gd, predator_stalking_ai.gd, monster_los_check.gd, spatial_noise_emitter.gd	Sanity shaders, inventory duplicator, scare loader
Sanity / stress FX	sanity_manager.gd, sanity_shader_manager.gd	Inventory scarcity scripts, async scare loader
Scarcity / inventory truth	inventory_data_storage.gd, item_state_duplicator.gd	Fog intensifier, sanity shaders
Hitch-free scare assets	async_scare_loader.gd	Full Director + sanity stack

Architecture Overview

1. The Director System (Macro AI)

Controls pacing so players never stay at 100% tension.

MANDATORY read: director_pacing.gd — do not paste a one-off tension enum. Wire Director events to near-player investigation targets, never instant on-player teleports during quiet phases.

2. Sensory Perception (Micro AI)

Honest monster senses (vision + sound) that the Director may only hint, never hard-cheat.

MANDATORY reads: predator_stalking_ai.gd for dual-brain orchestration; monster_los_check.gd + spatial_noise_emitter.gd for LoS/sound. Prefer PhysicsDirectSpaceState3D.intersect_ray() over Area overlap for vision.

3. Sanity / Stress System

Distorting the world based on fear.

Load sanity_manager.gd + sanity_shader_manager.gd for value → shake/bus/shader pipelines. Keep thresholds on is_equal_approx / bands, never sanity == 0.0.

Key Mechanics Implementation

Pacing (The Sawtooth Wave)

Horror needs peaks and valleys.

1. Safety: Save room.
2. Unease: Strange noise, lights flicker.
3. Dread: Monster is known to be close.
4. Terror: Chase sequence / Combat.
5. Relief: Escape to Safety.

The "Dual Brain" AI

• Director (All-knowing): Cheats to keep the alien relevant (teleports it closer if far away, guides it to player's general area).
• Alien (Senses only): Honest AI. Must actually see/hear the player to attack.

3. Hiding-Spot Metadata System

Use set_meta / groups — MANDATORY: predator_stalking_ai.gd + peer godot-genre-stealth. Do not paste hiding-spot tutorials inline.

4. Adaptive Audio (Stress Muffling)

Bus LPF / volume from fear — MANDATORY: sanity_manager.gd + peer godot-audio-systems.

5. Safe-Room Multithreaded Save

Threaded checkpoint I/O — MANDATORY: peer godot-save-load-systems (Thread/Mutex / WorkerThreadPool). Never sync FileAccess on the main thread in a safe room.

Expert knowledge (on demand)

LLM-ignorance rule: If a general agent would not know it before reading, load the reference — never delete expert deltas.

• expert-horror-patterns.md — restored baseline pedagogy (architecture, WHY, implementation depth)

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

• Volumetric fog and fog volumes — density/albedo and light-dependent scattering for dread atmosphere.
• Environment and post-processing — WorldEnvironment tonemap, glow, and fog modes that carry horror looks.
• Lights and shadows — SpotLight3D flashlight cones, soft shadows, and bias for dark interiors.
• Audio buses — LowPass/Reverb bus effects for stress muffling and spatial dread.
• Ray-casting — PhysicsDirectSpaceState intersect_ray for honest monster LoS (not Area overlap).
• Navigation introduction (3D) — predator chase paths and avoidance masks in tight corridors.
• Background loading — ResourceLoader threaded requests so jump-scare assets never hitch.
• Screen-reading shaders — hint_screen_texture sanity distortion (not Godot 3 SCREEN_TEXTURE).
• Visibility ranges — GeometryInstance3D HLOD/culling for expensive monster meshes and lights.
• Saving games — FileAccess patterns for safe-room checkpoints without inventing a format.
• Using threads — Thread/Mutex and WorkerThreadPool for background saves and heavy parse work.
• Resources — Resource definitions and duplicate(true) so mutable item state never aliases globals.

Related Skills

Prerequisites

• godot-project-foundations — scene tree, autoloads, and import basics before Director/WorldEnvironment wiring.
• godot-3d-lighting — volumetric fog, SpotLight3D flashlights, and shadow budgets that define horror atmosphere.
• godot-audio-systems — buses, spatial emitters, and effect stacks the sanity/stress systems modulate.

Complements

• godot-navigation-pathfinding — NavigationAgent chase/search paths and avoidance so predators do not stack in corridors.
• godot-state-machine-advanced — StringName-driven patrol/chase/search machines for predator micro-AI.
• godot-raycasting-queries — physics-synced LoS and shape queries for sensory perception without Area cheating.
• godot-shaders-basics — instance uniforms and screen-reading distortion for sanity FX.
• godot-inventory-system — typed Resource inventory and scarcity (battery/ammo) separate from visual UI trees.
• godot-camera-systems — shake, lean, and frustum-driven offscreen AI suspend via VisibleOnScreenNotifier3D.
• godot-tweening — procedural flashlight flicker and fog density ramps without AnimationPlayer spam.
• godot-monte-carlo-balancer — simulate Director sawtooth peaks/relief and scarcity budgets before shipping.
• godot-genre-stealth — suspicion meters, hiding spots, and view-cone stalker patterns that share sensory AI.

Downstream / consumers

• godot-genre-survival — scarcity loops and safe-room checkpoints that reuse horror resource pressure.
• godot-save-load-systems — threaded/async save pipelines for safe rooms without main-thread freezes.

Master

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