# filogcs/crawl architecture

> Architecture diagram of the GitHub repository filogcs/crawl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/filogcs/crawl
- Repository: https://github.com/filogcs/crawl

## Overview

Below are detailed instructions tailored to this project:

##### Main Components
- Game Engine Core: This is the central simulation loop—a collection of modules responsible for game logic. Components include dungeon generation (with vaults, level design, procedural layout generation), combat resolution, and the simulation of monsters, players, and in-game events. Source files in crawl-ref/source (e.g., dungeon.cc, monster.cc, etc.) implement these core features.
- Data and Configuration: The game is highly data-driven. The “dat” directories (with YAML and .des files under crawl-ref/source/dat and its subfolders) contain definitions for monsters, species, vaults, items, and descriptions. This component serves as the content repository.
- Rendering/User Interface:
 Tiles/Graphical UI: Utilizes SDL and related libraries (e.g., SDLMain, glwrapper, rltiles) for rendering tiles and graphical interfaces.
 ASCII/Console Mode: The classic text-based output mode.
 Android Frontend: A dedicated Android project exists under crawl-ref/source/android-project that provides a mobile UI.
 Webtiles Interface: Located in crawl-ref/source/webserver, this provides a browser-based interface to play the game online.
- Scripting and Extensibility: Lua scripts (found in various crawl-ref/source/dat/dlua and other Lua modules) offer in-game functionality such as macros and additional behaviors.
- Build and Deployment Infrastructure: There are build scripts (e.g., Makefiles, Gradle for Android, and MSVC project files) and GitHub workflows that support building across multiple environments. There is also integration for Debian packaging and codecov reporting.
- Development Support and Testing: The repository includes test suites (catch2-tests) and extensive documentation under the crawl-ref/docs folder for developers and contributors.

##### Relationships and Interactions
- The core game engine interacts with the data/content repository by loading and parsing specifications for levels, monsters, weapons, etc.
- The Engine then communicates with its various UI layers:
- In a graphical build, the SDL/tiles module receives rendering calls from the engine.
- In a console build, ASCII output is produced.
- The Android project is essentially a wrapper that calls into the game engine (or builds a version of it) for mobile platforms.
- The webtiles server acts as both a network interface and UI layer, forwarding user input (via HTTP/WebSocket) to the game engine, then formatting and delivering output.
- Scripting (Lua) is integrated into the engine to provide dynamic behaviors, which allows advanced users and modders to extend or alter game logic.
- Build, Continuous Integration, and packaging tools ensure quality and portability across OS-es (Windows, Linux, OSX, Android).

##### Architectural Patterns and Design Principles
- Separation of concerns is fundamental: rendering layers, engine logic, and data definitions are isolated.
- Modular design allows for different frontends (tiles, ASCII, Android, web) to plug into the same core simulation.
- Data-driven design keeps game content (levels, monsters, items) separate from code.
- The architecture supports extensibility via scripting and an open data specification approach.

##### Components Specific to a Full-Stack Game
- Since this is a full-stack game with multiple interfaces, pinpoint the clear separation between the game simulation and the presentation layers.
- Notes on how the engine accesses external libraries (e.g., SDL, SQLite, PCRE, libpng) to manage rendering, data storage, and regular expression matching for commands.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Engine Layer
    subgraph "Engine Layer"
        Data_And_Config["Data & Configuration\n(monsters, vaults, items)"] 
        Core_Game_Engine["Core Game Engine\n(dungeon generation, combat, simulation)"]
        Scripting_Engine["Scripting Engine\n(Lua Integration)"]
    end

    %% UI Layer
    subgraph "User Interface"
        Tiles_UI["Tiles/Graphical UI\n(SDL/Tiles)"]
        ASCII_UI["ASCII/Console UI"]
        Android_UI["Android Frontend"]
        Webtiles_UI["Webtiles Interface\n(Browser based)"]
    end

    %% Infrastructure
    subgraph "Infrastructure"
        subgraph "Build & Deployment"
            Build_Makefile["Makefile"]
            Build_MSVC["MSVC Projects"]
            Build_CI["CI/CD Workflows"]
        end
        subgraph "Development Support & Testing"
            Testing_Catch2["Catch2 Tests"]
            Docs["Documentation"]
        end
    end

    %% Relationships in Engine Layer
    Data_And_Config -->|"loads"| Core_Game_Engine
    Scripting_Engine <-->|"integrates"| Core_Game_Engine

    %% Communication from Engine to UI
    Core_Game_Engine -->|"renders"| Tiles_UI
    Core_Game_Engine -->|"renders"| ASCII_UI
    Core_Game_Engine -->|"renders"| Android_UI
    Core_Game_Engine <-->|"communicates"| Webtiles_UI

    %% User input flow from UI to Engine
    Tiles_UI -->|"input"| Core_Game_Engine
    ASCII_UI -->|"input"| Core_Game_Engine
    Android_UI -->|"input"| Core_Game_Engine

    %% Infrastructure support to Core Engine (dashed lines)
    Build_Makefile ---|"builds"| Core_Game_Engine
    Build_MSVC ---|"builds"| Core_Game_Engine
    Build_CI ---|"builds"| Core_Game_Engine
    Testing_Catch2 ---|"tests"| Core_Game_Engine
    Docs ---|"guides"| Core_Game_Engine

    %% Infrastructure support to UI (dashed lines)
    Build_Makefile ---|"builds"| Tiles_UI
    Build_MSVC ---|"builds"| Android_UI
    Build_CI ---|"builds"| Webtiles_UI
    Testing_Catch2 ---|"tests"| Tiles_UI
    Docs ---|"guides"| Docs

    %% Click Events
    click Core_Game_Engine "https://github.com/filogcs/crawl/tree/master/crawl-ref/source"
    click Data_And_Config "https://github.com/filogcs/crawl/tree/master/crawl-ref/source/dat"
    click Scripting_Engine "https://github.com/filogcs/crawl/tree/master/crawl-ref/source/dat/dlua"
    click Tiles_UI "https://github.com/filogcs/crawl/tree/master/crawl-ref/rltiles"
    click Android_UI "https://github.com/filogcs/crawl/tree/master/crawl-ref/android-project"
    click Webtiles_UI "https://github.com/filogcs/crawl/tree/master/crawl-ref/webserver"
    click Build_Makefile "https://github.com/filogcs/crawl/tree/master/crawl-ref/source/Makefile"
    click Build_MSVC "https://github.com/filogcs/crawl/tree/master/crawl-ref/source/MSVC"
    click Build_CI "https://github.com/filogcs/crawl/tree/master/.github/workflows"
    click Testing_Catch2 "https://github.com/filogcs/crawl/tree/master/crawl-ref/catch2-tests"
    click Docs "https://github.com/filogcs/crawl/tree/master/crawl-ref/docs"

    %% Styles
    class Core_Game_Engine core
    class Data_And_Config data
    class Scripting_Engine script
    class Tiles_UI ui
    class Android_UI ui
    class Webtiles_UI ui
    class ASCII_UI ui
    class Build_Makefile build
    class Build_MSVC build
    class Build_CI build
    class Testing_Catch2 test
    class Docs test
```
