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.
Expert blueprint for roguelikes balancing challenge, progression, and replayability.
RandomNumberGenerator with a predictable seed for daily runs/debugging.@GlobalScope.randi() for critical logic; strictly use local RNG instances to prevent global state pollution.Array.pick_random() for critical content drops; strictly use a Shuffle Bag to prevent statistically unfair streaks.WorkerThreadPool.add_task() or add_group_task() to distribute generation across cores and prevent frame freezes.RunManager and MetaManager.duplicate(true) on base stat Resources; failing to deep-duplicate causes all entities to share a single health instance..tscn files; strictly serialize to JSON or binary in user:// to prevent bloat.SceneTree as the source of truth for grid logic; strictly maintain grid data in a separate Dictionary or Array.NavigationRegion2D AFTER procedural tiles are placed.AStarGrid2D with jumping_enabled = true (Jump Point Search) for O(1) queries and high-performance pathing across open areas.update() on AStarGrid2D after modifying states; strictly ensures pathfinding queries aren't stale.Vector2) for discrete grid coordinates; strictly use Vector2i to prevent precision drift.HEURISTIC_CHEBYSHEV or HEURISTIC_OCTILE.get_used_cells() for optimized tile access.free(); strictly use queue_free() to avoid mid-frame segmentation faults.call_deferred() or call_group_flags to avoid frame spikes during turn transitions.ColorRect and an ImageTexture updated via RenderingServer.texture_2d_update().meta_progression_resource.gd).dungeon_generator_walker.gd), acquire temporary power-ups.astar_grid_handler.gd).meta_progression_resource.gd).| Phase | Skills | Purpose |
|---|---|---|
| 1. Architecture | state-machines, autoloads | Managing Run State vs Meta State |
| 2. World Gen | godot-procedural-generation, tilemap, noise | Creating unique levels every run |
| 3. Combat | godot-combat-system, enemy-ai | Fast-paced, high-stakes encounters |
| 4. Progression | loot-tables, godot-inventory-system | Managing run-specific items/relics |
| 5. Persistence | save-system, resources | Saving meta-progress between runs |
Roguelikes require a strict separation between Run State (temporary) and Meta State (persistent).
Handles the lifespan of a single run. Resets completely on death.
# run_manager.gd
extends Node
signal run_started
signal run_ended(victory: bool)
signal floor_changed(new_floor: int)
var current_seed: int
var current_floor: int = 1
var player_stats: Dictionary = {}
var inventory: Array[Resource] = []
var rng: RandomNumberGenerator
func start_run(seed_val: int = -1) -> void:
rng = RandomNumberGenerator.new()
if seed_val == -1:
rng.randomize()
current_seed = rng.seed
else:
current_seed = seed_val
rng.seed = current_seed
current_floor = 1
_reset_run_state()
run_started.emit()
func _reset_run_state() -> void:
player_stats = { "hp": 100, "gold": 0 }
inventory.clear()
func next_floor() -> void:
current_floor += 1
floor_changed.emit(current_floor)
func end_run(victory: bool) -> void:
run_ended.emit(victory)
# Trigger meta-progression save here
Stores permanent unlocks.
# meta_progression.gd
class_name MetaProgression
extends Resource
@export var total_runs: int = 0
@export var unlocked_weapons: Array[String] = ["sword_basic"]
@export var currency: int = 0
@export var skill_tree_nodes: Dictionary = {} # node_id: level
func save() -> void:
ResourceSaver.save(self, "user://meta_progression.tres")
static func load_or_create() -> MetaProgression:
if ResourceLoader.exists("user://meta_progression.tres"):
return ResourceLoader.load("user://meta_progression.tres")
return MetaProgression.new()
# dungeon_generator.gd
extends Node
@export var map_width: int = 50
@export var map_height: int = 50
@export var max_walkers: int = 5
@export var max_steps: int = 500
func generate_dungeon(tilemap: TileMapLayer, rng: RandomNumberGenerator) -> void:
tilemap.clear()
var walkers: Array[Vector2i] = [Vector2i(map_width/2, map_height/2)]
var floor_tiles: Array[Vector2i] = []
for step in max_steps:
var new_walkers: Array[Vector2i] = []
for walker in walkers:
floor_tiles.append(walker)
# 25% chance to destroy walker, 25% to spawn new one
if rng.randf() < 0.25 and walkers.size() > 1:
continue # Destroy
if rng.randf() < 0.25 and walkers.size() < max_walkers:
new_walkers.append(walker) # Spawn
# Move walker
var direction = [Vector2i.UP, Vector2i.DOWN, Vector2i.LEFT, Vector2i.RIGHT].pick_random()
new_walkers.append(walker + direction)
walkers = new_walkers
# Set tiles
for pos in floor_tiles:
tilemap.set_cell(pos, 0, Vector2i(0,0)) # Assuming source_id 0 is floor
# Post-process: Add walls, spawn points, etc.
Relics modify stats or add behavior.
# relic.gd
class_name Relic
extends Resource
@export var id: String
@export var name: String
@export var icon: Texture2D
@export_multiline var description: String
# Hook system for complex interactions
func on_pickup(player: Node) -> void:
pass
func on_damage_dealt(player: Node, target: Node, damage: int) -> int:
return damage # Return modified damage
func on_kill(player: Node, target: Node) -> void:
pass
# example_relic_vampirism.gd
extends Relic
func on_kill(player: Node, target: Node) -> void:
player.heal(5)
print("Vampirism triggered!")
RandomNumberGenerator with a seed. This allows players to share specific run layouts.ResourceSaver for meta-progression, but be careful with cyclical references in deeply nested resources.Room1.tscn, Room2.tscn) and instance them into the generated layout for handcrafted quality within procedural layouts.NavigationRegion2D at runtime after generating the dungeon layout if using 2D navigation.fire, projectile, companion) and check for tag combinations to create emergent power-ups.