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

Do-NOT-Load (by fantasy)

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.