Expert blueprint for roguelikes including procedural generation (Walker method, BSP rooms), permadeath with meta-progression (unlock persistence), run state vs meta state separation, seeded RNG (shareable runs), loot/relic systems (hook-based modifiers), and difficulty scaling (floor-based progression). Use for dungeon crawlers, action roguelikes, or roguelites. Trigger keywords: roguelike, procedural_generation, permadeath, meta_progression, seeded_RNG, relic_system, run_state.
15k tokens
context cost
the whole folder, loaded on every use
23
files
ships runnable scripts
0
copies elsewhere
how many repositories repackaged it
451
stars on the repo
on the repository, not the skill itself
Install
one command, takes just this skill from the repository
NEVER assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.
Genre: Roguelike
Expert blueprint for roguelikes balancing challenge, progression, and replayability.
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 localRandomNumberGenerator (rng.randi() % n, never Array.pick_random()).
Fog / LOS: fog_of_war_masker.gd, fov_raycast_calculator.gd.
Director pacing: frame-slice with Engine.get_process_frames() % N (see NEVER); keep heuristics out of every-frame _process work.
Common Pitfalls
RNG Dependency: Don't make runs entirely dependent on luck. Good roguelikes allow skill to mitigate bad RNG.
Meta-progression Imbalance: If meta-upgrades are too strong, the game becomes a "grind to win" rather than "learn to win".
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.
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. 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 — set_cell / get_used_cells 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.