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 isequalapprox() or threshold checks for deterministic triggers.
• NEVER write screen-reading shaders expecting Godot 3 SCREENTEXTURE; strictly use sampler2D with hintscreen_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.loadthreadedrequest() 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)

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

Modular Components

• [monsterloscheck.gd](scripts/monsterloscheck.gd) - Physics-synced raycasting for high-performance visibility checks.
• [flashlightflicker.gd](scripts/flashlightflicker.gd) - Procedural light interference for atmospheric tension.
• [inventorydatastorage.gd](scripts/inventorydatastorage.gd) - Typed data structure for sparse resource management.
• [asyncscareloader.gd](scripts/asyncscareloader.gd) - Threaded resource loading for hitch-free jump-scares.
• [spatialnoiseemitter.gd](scripts/spatialnoiseemitter.gd) - Shape-based sound sensing for sensory AI.
• [itemstateduplicator.gd](scripts/itemstateduplicator.gd) - Deep duplication for managing unique weapon/item states.
• [fogclausintensifier.gd](scripts/fogclausintensifier.gd) - Volumetric fog manipulation for dread buildup.
• [offscreenlogicsuspender.gd](scripts/offscreenlogicsuspender.gd) - Culling logic for AI processing outside camera view.
• [sanityshadermanager.gd](scripts/sanityshadermanager.gd) - Instance-uniform driven distortion effects.
• [sanitymanager.gd](scripts/sanitymanager.gd) - Stress/sanity value pipeline feeding shake and audio buses.
• [optimizedhorrorstatemachine.gd](scripts/optimizedhorrorstatemachine.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

Do-NOT-Load (by fantasy)

Architecture Overview

1. The Director System (Macro AI)

Controls pacing so players never stay at 100% tension.

MANDATORY read: [directorpacing.gd](scripts/directorpacing.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: [predatorstalkingai.gd](scripts/predatorstalkingai.gd) for dual-brain orchestration; [monsterloscheck.gd](scripts/monsterloscheck.gd) + [spatialnoiseemitter.gd](scripts/spatialnoiseemitter.gd) for LoS/sound. Prefer PhysicsDirectSpaceState3D.intersect_ray() over Area overlap for vision.

3. Sanity / Stress System

Distorting the world based on fear.

Load [sanitymanager.gd](scripts/sanitymanager.gd) + [sanityshadermanager.gd](scripts/sanityshadermanager.gd) for value → shake/bus/shader pipelines. Keep thresholds on isequalapprox / 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 setmeta / groups — MANDATORY: [predatorstalkingai.gd](scripts/predatorstalking_ai.gd) + peer godot-genre-stealth. Do not paste hiding-spot tutorials inline.

4. Adaptive Audio (Stress Muffling)

Bus LPF / volume from fear — MANDATORY: [sanitymanager.gd](scripts/sanitymanager.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](references/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 — hintscreentexture sanity distortion (not Godot 3 SCREENTEXTURE).
• 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.