godot-genre-roguelike

NEVER Do (Expert Anti-Patterns)

Generation & RNG

• NEVER make runs dependent on pure RNG; strictly provide mitigation (rerolls, shops, pity timers) to ensure every run is winnable.
• NEVER use unseeded RNG for world generation; strictly initialize isolated RandomNumberGenerator with a predictable seed for daily runs/debugging.
• NEVER rely on @GlobalScope.randi() for critical logic; strictly use local RNG instances to prevent global state pollution.
• NEVER use Array.pick_random() for critical content drops; strictly use a Shuffle Bag to prevent statistically unfair streaks.
• NEVER generate massive dungeons on the main thread; strictly use WorkerThreadPool.addtask() or addgroup_task() to distribute generation across cores and prevent frame freezes.
• NEVER interact with the SceneTree from a background thread; strictly generate dungeon data in a thread-safe Array/PackedByteArray before parsing on the main thread.

Data & State

• NEVER allow Save Scumming; strictly delete mid-run save files immediately upon loading to enforce permadeath.
• NEVER allow the player to see the "Edge of the World"; strictly use Fog of War or limited vision cones to maintain the mystery of the unknown.
• NEVER evaluate complex "Director" heuristics every frame; strictly use Frame-Slicing (Engine.getprocessframes()) to run heavy pacing logic only once every 60-120 frames for CPU efficiency.
• NEVER move rooms individually by pixel values during procedural generation; strictly use Marker2D Connection Points in pre-authored scenes to calculate exact offsets for seamless room stitching.
• NEVER allow Run State to leak into Meta State; strictly use separate singletons or Resources for RunManager and MetaManager.
• NEVER scale meta-progression to be overpowered (+100% damage); strictly keep upgrades subtle (+5-15%) to maintain skill-based play.
• NEVER forget to call duplicate(true) on base stat Resources; failing to deep-duplicate causes all entities to share a single health instance.
• NEVER save run states to .tscn files; strictly serialize to JSON or binary in user:// to prevent bloat.
• NEVER rely on the SceneTree as the source of truth for grid logic; strictly maintain grid data in a separate Dictionary or Array.

Grid & Performance

• NEVER forget to handle Navigation re-baking; strictly rebake NavigationRegion2D AFTER procedural tiles are placed.
• NEVER use AStar2D for tile grids; strictly use AStarGrid2D with jumping_enabled = true (Jump Point Search) for O(1) queries and high-performance pathing across open areas.
• NEVER forget to call update() on AStarGrid2D after modifying states; strictly ensures pathfinding queries aren't stale.
• NEVER use floats (Vector2) for discrete grid coordinates; strictly use Vector2i to prevent precision drift.
• NEVER use Manhattan heuristics for 8-way movement; strictly use HEURISTICCHEBYSHEV or HEURISTICOCTILE.
• NEVER iterate over every cell coordinate (0 to W,H) in GDScript; strictly use getusedcells() for optimized tile access.
• NEVER clear procedural levels using free(); strictly use queue_free() to avoid mid-frame segmentation faults.
• NEVER broadcast mass state changes to a grid immediately; strictly use calldeferred() or callgroup_flags to avoid frame spikes during turn transitions.
• NEVER use heavy TileMapLayer nodes for high-resolution Fog of War; strictly use a GPU Shader Mask via ColorRect and an ImageTexture updated via RenderingServer.texture2dupdate().

🛠 Expert Components (scripts/)

MANDATORY before implementing generation, seed sharing, or meta unlocks — read these first (do not reinvent from inline samples):
- [dungeongeneratorwalker.gd](scripts/dungeongeneratorwalker.gd) — Drunkard's Walk with local RandomNumberGenerator (rng.randi() % n, never Array.pick_random()).
- [seededrngresource.gd](scripts/seededrngresource.gd) — seed persistence for shareable / daily runs.
- [metaprogressionmanager.gd](scripts/metaprogressionmanager.gd) — permanent unlock currency + save boundaries vs run state.

Do NOT Load the full scripts/ folder for a single task. Open only the script that matches the phase below.

Original Expert Patterns

• [metaprogressionmanager.gd](scripts/metaprogressionmanager.gd) - Foundational meta-progression logic with secure data persistence and currency unlocks.
• [roguelikepatterns.gd](scripts/roguelikepatterns.gd) - 10 Essential Roguelike Expert Snippets (AStar, BSP, WorkerThreadPool, ShuffleBag, etc.).

Modular Components

• [dungeongeneratorwalker.gd](scripts/dungeongeneratorwalker.gd) - Drunkard's Walk algorithm for carving procedural rooms and caves.
• [fovraycastcalculator.gd](scripts/fovraycastcalculator.gd) - High-performance LOS checking using physics server queries.
• [seededrngresource.gd](scripts/seededrngresource.gd) - RNG state persistence for deterministic and shareable replayability.
• [turnmanagerdecoupled.gd](scripts/turnmanagerdecoupled.gd) - Signal-driven turn coordination for decoupled entity logic.
• [astargridhandler.gd](scripts/astargridhandler.gd) - Specialised AStarGrid2D wrapper for optimized roguelike pathfinding.
• [weightedloottable.gd](scripts/weightedloottable.gd) - Native-optimized weighted random item drops with drop-rate controls.
• [jsonstateserializer.gd](scripts/jsonstateserializer.gd) - Persistent serialization for procedural entity data and run states.
• [fogofwarmasker.gd](scripts/fogofwarmasker.gd) - TileMapLayer-based visibility masking and discovery system.
• [metaprogressionresource.gd](scripts/metaprogressionresource.gd) - Data separation for permanent game unlocks and skill trees.
• [movecommandobject.gd](scripts/movecommandobject.gd) - Command pattern implementation for reversible turn-based actions.
• [dungeongenerator.gd](scripts/dungeongenerator.gd) - High-level procedural orchestrator for room-and-hallway layout generation.
• [runmanager.gd](scripts/runmanager.gd) - Autoload run seed/floor/inventory lifecycle (startrun / endrun).
• [directorai.gd](scripts/directorai.gd) - Pacing manager — spawn intensity from player power + time-in-run.
• [roomassembler.gd](scripts/roomassembler.gd) - Marker-based procedural room stitching from prefab scenes.
• [synergymanager.gd](scripts/synergymanager.gd) - Relic tag synergy detection and stacked modifier application.
• [examplerelicvampirism.gd](scripts/examplerelicvampirism.gd) - Sample Relic Resource hook (ondamagedealt).

Core Loop

1. Preparation: Select character, equip meta-upgrades (see metaprogressionresource.gd).
2. The Run: complete procedural levels (dungeongeneratorwalker.gd), acquire temporary power-ups.
3. The Challenge: Survive increasingly difficult encounters using A* pathfinding (astargridhandler.gd).
4. Death/Victory: Run ends, resources calculated.
5. Meta-Progression: Spend resources on permanent unlocks (metaprogressionresource.gd).
6. Repeat: Start a new run with new capabilities.

Skill Chain

Architecture Overview

Roguelikes require a strict separation between Run State (temporary) and Meta State (persistent).

• Run lifespan / seed: Own an AutoLoad that resets on death; seed via MANDATORY [seededrngresource.gd](scripts/seededrngresource.gd). Never leak run HP/gold into meta saves.
• Meta unlocks: MANDATORY [metaprogressionmanager.gd](scripts/metaprogressionmanager.gd) + [metaprogressionresource.gd](scripts/metaprogressionresource.gd) — subtle permanent bonuses only (+5–15%).
• Serialize: Prefer [jsonstateserializer.gd](scripts/jsonstateserializer.gd) / user:// JSON-binary; never treat .tscn as a run save.

Key Mechanics (route to scripts/)

Procedural Dungeon Generation

• Drunkard's Walk: MANDATORY [dungeongeneratorwalker.gd](scripts/dungeongeneratorwalker.gd) — pass a local seeded RandomNumberGenerator; directions via rng.randi() % directions.size() (never Array.pick_random()).
• Critical drops / fairness: Use Shuffle Bag patterns in [roguelikepatterns.gd](scripts/roguelikepatterns.gd) or weights in [weightedloottable.gd](scripts/weightedloottable.gd).
• BSP / room orchestrator: [dungeongenerator.gd](scripts/dungeongenerator.gd); deeper WFC/noise → peer godot-procedural-generation.
• Pathing after gen: [astargridhandler.gd](scripts/astargridhandler.gd) — call update() after solid-cell edits; rebake NavigationRegion2D if using nav meshes.

Relics, turns, fog, pacing

• Relic hooks / synergy tags: Resource subclasses + [weightedloottable.gd](scripts/weightedloottable.gd); inventory peer godot-inventory-system.
• Turns: [turnmanagerdecoupled.gd](scripts/turnmanagerdecoupled.gd) + [movecommandobject.gd](scripts/movecommandobject.gd).
• Fog / LOS: [fogofwarmasker.gd](scripts/fogofwarmasker.gd), [fovraycastcalculator.gd](scripts/fovraycastcalculator.gd).
• Director pacing: frame-slice with Engine.getprocessframes() % N (see NEVER); keep heuristics out of every-frame _process work.

Common Pitfalls

1. RNG Dependency: Don't make runs entirely dependent on luck. Good roguelikes allow skill to mitigate bad RNG.
2. Meta-progression Imbalance: If meta-upgrades are too strong, the game becomes a "grind to win" rather than "learn to win".
3. Lack of Variety: Procedural generation is only as good as the content it arranges. You need a lot of content (rooms, enemies, items) to keep it fresh.
4. Save Scumming: Players will try to quit to avoid death. Save the state only on floor transition or quit, and delete the save on load (optional, but standard for strict roguelikes).

Godot-Specific Tips

• Seeded Runs: Always initialize RandomNumberGenerator with a seed. This allows players to share specific run layouts.
• ResourceSaver: Use ResourceSaver for meta-progression, but be careful with cyclical references in deeply nested resources.
• Scenes as Rooms: Build your "rooms" as separate scenes (Room1.tscn, Room2.tscn) and instance them into the generated layout for handcrafted quality within procedural layouts.
• Navigation: Rebake NavigationRegion2D at runtime after generating the dungeon layout if using 2D navigation.

Advanced Techniques

• Synergy System: Tag items (fire, projectile, companion) and check for tag combinations to create emergent power-ups.
• Director AI: An invisible "Director" system that tracks player health/stress and adjusts spawn rates dynamically (like Left 4 Dead).

MANDATORY for depth beyond decision trees and script catalog: [roguelike-meta-systems-deep.md](references/roguelike-meta-systems-deep.md). Do NOT Load on first-pass wiring — use bundled scripts/ first.

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

• Using TileMaps — TileMapLayer cells, sources, and runtime placement for procedural floors/walls.
• TileMapLayer — setcell / getusedcells APIs used after walker/BSP generation and fog clears.
• AStarGrid2D — grid pathfinding with heuristics, diagonal modes, and update() after solid-cell edits.
• RandomNumberGenerator — seeded PCG32 for shareable runs; prefer local instances over global randi().
• WorkerThreadPool — offload heavy dungeon generation without freezing the main thread.
• Using multiple threads — when WorkerThreadPool/tasks are safe versus SceneTree ownership rules.
• Thread-safe APIs — generate data off-thread, then apply tiles/nodes on the main thread only.
• Saving games — user:// persistence patterns for meta unlocks and anti-scum mid-run deletes.
• Resources — Resource-backed meta/run data, duplicate(true), and save/load of .tres/custom resources.
• Singletons (AutoLoad) — isolate RunManager vs MetaManager so run death cannot wipe permanent progress.
• Ray-casting — PhysicsDirectSpaceState queries for FOV / line-of-sight without Area2D spam.
• FastNoiseLite — noise fields for cave-style maps before connectivity validation with AStarGrid2D.

Related Skills

Prerequisites

• godot-project-foundations — project layout, Autoloads, and Resource basics before run/meta split.
• godot-tilemap-mastery — TileMapLayer authorship and runtime cell edits that procedural generators write into.
• godot-resource-data-patterns — Resource duplication, typed data, and save-friendly schemas for relics/meta stats.
• godot-autoload-architecture — singleton boundaries so Run state resets cleanly without touching Meta state.

Complements

• godot-procedural-generation — deeper Walker/BSP/WFC generators that feed this genre's dungeon loop.
• godot-navigation-pathfinding — NavigationRegion rebake and agent pathing when not using pure AStarGrid2D.
• godot-combat-system — hit/hurt pipelines and turn-paced encounters inside generated floors.
• godot-inventory-system — run bags, relic slots, and item Resources consumed by loot tables.
• godot-save-load-systems — JSON/binary persistence, floor-transition saves, and permadeath delete-on-load.
• godot-signal-architecture — decoupled turn/floor/run signals without SceneTree as grid source of truth.
• godot-performance-optimization — thread pools, fog GPU masks, and frame-sliced director heuristics at scale.

Downstream / consumers

• godot-monte-carlo-balancer — simulate win% vs meta level, pity timers, and dead-item detection across seeded runs.
• godot-genre-action-rpg — action-RPG combat/progression layers that often consume roguelike run/meta patterns.

Master

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