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.add_task() or add_group_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.get_process_frames()) 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 HEURISTIC_CHEBYSHEV or HEURISTIC_OCTILE.
• NEVER iterate over every cell coordinate (0 to W,H) in GDScript; strictly use get_used_cells() 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 call_deferred() or call_group_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.texture_2d_update().

🛠 Expert Components (scripts/)

MANDATORY before implementing generation, seed sharing, or meta unlocks — read these first (do not reinvent from inline samples):

• dungeon_generator_walker.gd — Drunkard's Walk with local RandomNumberGenerator (rng.randi() % n, never Array.pick_random()).
• seeded_rng_resource.gd — seed persistence for shareable / daily runs.
• meta_progression_manager.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

• meta_progression_manager.gd - Foundational meta-progression logic with secure data persistence and currency unlocks.
• roguelike_patterns.gd - 10 Essential Roguelike Expert Snippets (AStar, BSP, WorkerThreadPool, ShuffleBag, etc.).

Modular Components

• dungeon_generator_walker.gd - Drunkard's Walk algorithm for carving procedural rooms and caves.
• fov_raycast_calculator.gd - High-performance LOS checking using physics server queries.
• seeded_rng_resource.gd - RNG state persistence for deterministic and shareable replayability.
• turn_manager_decoupled.gd - Signal-driven turn coordination for decoupled entity logic.
• astar_grid_handler.gd - Specialised AStarGrid2D wrapper for optimized roguelike pathfinding.
• weighted_loot_table.gd - Native-optimized weighted random item drops with drop-rate controls.
• json_state_serializer.gd - Persistent serialization for procedural entity data and run states.
• fog_of_war_masker.gd - TileMapLayer-based visibility masking and discovery system.
• meta_progression_resource.gd - Data separation for permanent game unlocks and skill trees.
• move_command_object.gd - Command pattern implementation for reversible turn-based actions.
• dungeon_generator.gd - High-level procedural orchestrator for room-and-hallway layout generation.
• run_manager.gd - Autoload run seed/floor/inventory lifecycle (start_run / end_run).
• director_ai.gd - Pacing manager — spawn intensity from player power + time-in-run.
• room_assembler.gd - Marker-based procedural room stitching from prefab scenes.
• synergy_manager.gd - Relic tag synergy detection and stacked modifier application.
• example_relic_vampirism.gd - Sample Relic Resource hook (on_damage_dealt).

Core Loop

1. Preparation: Select character, equip meta-upgrades (see meta_progression_resource.gd).
2. The Run: complete procedural levels (dungeon_generator_walker.gd), acquire temporary power-ups.
3. The Challenge: Survive increasingly difficult encounters using A* pathfinding (astar_grid_handler.gd).
4. Death/Victory: Run ends, resources calculated.
5. Meta-Progression: Spend resources on permanent unlocks (meta_progression_resource.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 seeded_rng_resource.gd. Never leak run HP/gold into meta saves.
• Meta unlocks: MANDATORY meta_progression_manager.gd + meta_progression_resource.gd — subtle permanent bonuses only (+5–15%).
• Serialize: Prefer json_state_serializer.gd / user:// JSON-binary; never treat .tscn as a run save.

Key Mechanics (route to scripts/)

Procedural Dungeon Generation

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