Surreal Roguelike

Engine Vision & Core Pillars

Procedural Everything, With Context

The engine emphasizes procedural generation beyond maps—creating terrain, dungeons, cities, quests, and lore that all reference a shared world state. A multi-century history simulation (documented as ~250 years) provides causal grounding for ruins, conflicts, artifacts, faction relationships, and emergent quest lines.

Three-Realm World Model

Gameplay spans three distinct interconnected realms: • Earth (mortal): classic biome and dungeon exploration • Heaven (divine): celestial environments, unique creatures, and mechanics • Hell (infernal): high-risk traversal, hostile ecosystems, and corruption themes

Realm travel occurs via procedural portals tied to sacred/profane geography, enabling long-form runs with shifting rulesets and content density.

Gameplay Systems

Tactical Turn-Based Combat

Combat is built around an energy-based turn economy and supports: • 15 damage types spanning physical, elemental, supernatural, and special categories • Status effects suchs as poison, bleed, burn, freeze, stun, and blind • A flexible ability model (attack/heal/buff/debuff/summon/teleport/etc.) with target modes, costs, and cooldowns • A configurable FOV/line-of-sight system supporting stealth, positioning, and ranged play

The design supports high readability (traditional roguelike clarity) while enabling modern build expression and counterplay through effects and resistances.

Deep Progression & Build Craft

Progression supports long-run identity and replay variety: • Attributes, classes, skills/perks, and level-based unlock pacing • Extensive equipment coverage (17 slots, including “cybernetic/implant” expansion) • Multiple weapon and armor archetypes with rarity tiers from Common through Mythic and Cursed

This creates a wide combinatorial space for “builds” while keeping the combat loop deterministic and tactical.

Procedural Narrative & Faction Dynamics

Surreal Roguelike treats story as a system rather than authored content: • Procedural quests derived from world state and faction relationships • NPCs with generated histories and contextual dialogue • Reputation-driven behavior changes, pricing shifts, access gating, and quest availability

The result is a roguelike structure where “what happened in this world” shapes what the player is asked to do—without relying on static templates.

Rendering, UI, and Presentation

Terminal Aesthetic with a Modern GPU Pipeline

The engine uses a character-grid UI buffer (configurable, e.g., 80×50) as the primary presentation abstraction: • Game logic writes characters + foreground/background colors to a grid buffer • A Metal-backed renderer converts cells to pixels via atlas lookup and shader processing • Optional post effects (bloom/vignette/scanlines/atmospherics) preserve the terminal feel while adding modern polish

This approach keeps the classic readability of roguelikes while leveraging GPU throughput for smooth animations, camera behavior, and effects.

UI Framework & State Stack

A dedicated UI framework supports a widget hierarchy, modal overlays, and focus/hit-testing, integrated with a stack-based game state model (gameplay/menu/dialogue/inventory/etc.). This keeps gameplay, UI, and navigation flows cleanly separated while still rendering through a unified grid pipeline.

Internal Architecture

ECS + Event-Driven Systems

The engine is built around: • Entity Component System (ECS) for data-oriented gameplay modeling • A type-safe event bus for decoupled communication between systems • A centralized engine facade coordinating init/shutdown, fixed-timestep loop, and subsystem orchestration

This architecture supports extensibility—new abilities, creatures, biomes, items, UI widgets, and narrative systems can be added without destabilizing core loops.

Tooling, Testing, and Maturity

Surreal Roguelike ships with “real-engine” development ergonomics: • Makefile + CMake build flows (including test builds) • GoogleTest unit and integration testing, with coverage workflows and explicit thresholds • Documentation structured like a product: systems, controls, configuration, architecture, and extension guides • Optional integration with Weaviate for advanced retrieval/knowledge workflows (where applicable)