# dron12261games/sft-eternity-engine-plus architecture

> Architecture diagram of the GitHub repository dron12261games/sft-eternity-engine-plus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dron12261games/sft-eternity-engine-plus
- Repository: https://github.com/dron12261games/sft-eternity-engine-plus

## Overview

1. This repository is a Doom-engine source port, not a standalone game. The executable loads classic IWAD-style content plus this fork’s data packs from `base/` and `user/`, then runs the game loop on top of a custom engine derived from Eternity Engine.

2. The top-level build system is CMake, with extra packaging and platform support in `cmake/`. CI is driven by GitHub Actions. The repo also vendors third-party libraries and subprojects that materially affect runtime: `libpng` and `zlib` for asset/image compression, `acsvm` for ACS scripting, `snes_spc` for audio emulation, and `adlmidi` as a submodule for MIDI playback.

3. The core engine lives under `source/`. The central boundary is between platform-facing code and engine/game code. Platform backends are split by OS/driver layer in `source/hal/`, `source/sdl/`, `source/linux/`, `source/macos/`, and `source/Win32/`. These modules supply windowing, timing, input, sound, networking, directory access, and OS-specific startup glue.

4. Game startup and lifecycle are coordinated by `d_main.cpp`, `d_files.cpp`, `w_*` WAD loading, `d_iwad.cpp`, and `d_findiwads.cpp`. This layer discovers IWAD/PWAD content, builds the file system view, and then hands control to the rest of the engine. The `base/` and `user/` trees hold bundled EDF definitions, replacement resources, and game-specific content overlays.

5. The world simulation is in the classic Doom style but extended heavily. Major gameplay subsystems are split into modules for map setup, thinkers, physics, sectors, polyobjects, portals, specials, ACS/EDF hooks, and savegame support. Files like `p_*`, `ev_*`, `g_*`, `m_*`, `info.*`, `d_*`, and `e_*` divide the engine into gameplay rules, event dispatch, player state, and data-definition layers.

6. Rendering is a dedicated subsystem centered around `r_*` and `gl/*`. The software/engine-side renderer handles BSP traversal, planes, spans, textures, sprites, lighting, sky, portals, dynamic subsectors/segments, and interpolation. The `gl/` folder contains OpenGL-specific initialization and drawing helpers. This separation suggests a render pipeline that consumes world state and texture data from the game layer rather than owning simulation state itself.

7. Audio is also layered. `s_sound.cpp`, `s_formats.cpp`, `s_reverb.cpp`, `s_sndseq.cpp`, and `s_musinfo.cpp` manage sound effects, music metadata, reverb, and sequence playback. Platform adapters in `source/sdl/i_sdlmusic.cpp`, `source/sdl/i_sdlsound.cpp`, `source/Win32/i_winmusic.cpp`, plus the vendored MIDI/SPC libraries, form the backend that turns engine requests into actual audio output.

8. Scripting and modding are first-class architecture features. ACS support is split between the embedded VM in `acsvm/` and engine integration in `source/acs_*`. EDF support is handled by the `e_*.cpp` and `xl_*.cpp` families, which define the modding data model for actors, weapons, sounds, sprites, map metadata, and other game objects. The README’s new ACS functions are implemented by extending this scripting boundary rather than hardcoding gameplay.

9. Data-driven content is a major subsystem. The `base/*.edf` files define canonical gameplay defaults and per-game overrides for Doom, Heretic, Hexen, etc. Resource trees under `base/*/res/` contain graphics, sounds, sprites, gamepad mappings, translations, and startup assets. The engine appears designed to merge these definitions at startup, then let WAD content and scripts override them.

10. Save/load, demo, and networking boundaries are explicit. `p_saveg.cpp`, `mn_saveg.cpp`, `g_demolog.cpp`, `c_net.cpp`, `d_net.cpp`, and related headers indicate separate persistence and multiplayer synchronization paths. These systems sit beside the simulation layer rather than inside the renderer or UI, which is important for an architecture diagram.

11. User interface and frontend code are separate from core gameplay. Menus, HUD, automap, intermission, finale, cheat handling, and textscreen widgets live in `mn_*`, `hu_*`, `am_*`, `wi_*`, `f_*`, `in_lude.cpp`, and `source/textscreen/`. The UI reads from engine state and player state; it does not own the authoritative world model.

12. There are explicit platform-facing application shells beyond the main engine. `macosx/launcher/` builds a native macOS launcher app, and `eecrashreport/` is a Windows crash-reporting utility. These are ancillary executables around the engine, not part of the core simulation pipeline.

13. The repo includes a small set of test maps and WADs under `test/`, which likely exercise portals, conveyors, and sector behavior. This suggests the project is validating engine-specific mechanics rather than just rendering or asset loading.

14. For an architecture diagram, the cleanest high-level flow is: OS/platform backend initializes -> file/iwad discovery -> EDF/WAD/resource loading -> game state setup -> main tick loop processes input, network, ACS, and simulation -> renderer and audio consume the updated state -> save/demo/UI subsystems observe or serialize that state. The main architectural boundary is between data-driven content plus scripting on one side, and the engine’s simulation/render/audio/platform layers on the other.

Main entry points: [`CMakeLists.txt`](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/CMakeLists.txt) (CMake), [`source/p_tick.cpp`](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/p_tick.cpp) (Simulation), [`source/d_files.cpp`](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/d_files.cpp) (WAD FS), [`source/r_main.cpp`](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/r_main.cpp) (Renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & packaging"]
  node_cmake["CMake<br/>build system<br/>[CMakeLists.txt]"]
  node_ci["GitHub CI<br/>workflow<br/>[build-eternity.yml]"]
  node_cmake_support["CMake extras<br/>packaging support"]
end

subgraph group_runtime["Core runtime"]
  node_engine_root["Engine core<br/>runtime tree<br/>[d_main.cpp]"]
  node_startup["Startup<br/>bootstrap<br/>[d_main.cpp]"]
  node_wadfs["WAD FS<br/>content loading<br/>[d_files.cpp]"]
  node_iwad_discovery["IWAD find<br/>content discovery<br/>[d_iwad.cpp]"]
  node_game_loop["Game loop<br/>tick orchestration<br/>[g_game.cpp]"]
  node_simulation["Simulation<br/>gameplay systems<br/>[p_tick.cpp]"]
  node_world_defs["World defs<br/>data model<br/>[e_edf.cpp]"]
  node_rendering["Renderer<br/>render pipeline<br/>[r_main.cpp]"]
  node_gl_backend["GL backend<br/>[gl_init.cpp]"]
  node_audio["Audio<br/>sound system<br/>[s_sound.cpp]"]
  node_platform["Platform HAL<br/>os backend<br/>[i_platform.h]"]
  node_sdl_backend["SDL layer<br/>platform adapter<br/>[i_main.cpp]"]
  node_os_specific["OS ports<br/>platform backend<br/>[i_w32main.cpp]"]
  node_ui["UI shell<br/>frontend<br/>[mn_menus.cpp]"]
  node_persistence["Persist & net<br/>state sync<br/>[p_saveg.cpp]"]
end

subgraph group_content["Data & mods"]
  node_content_base["Base data<br/>game content<br/>[root.edf]"]
  node_content_user["User overlays<br/>content overlays<br/>[delete.me]"]
end

subgraph group_deps["Vendored deps"]
  node_acsvm["ACS VM<br/>scripting runtime<br/>[Script.cpp]"]
  node_libpng["libpng<br/>image codec<br/>[png.c]"]
  node_zlib["zlib<br/>compression<br/>[deflate.c]"]
  node_snes_spc["SPC audio<br/>audio emulation<br/>[SNES_SPC.cpp]"]
  node_adlmidi["ADLMIDI<br/>midi submodule"]
end

subgraph group_tools["Aux executables"]
  node_launcher["macOS launcher<br/>app shell<br/>[MainStart.m]"]
  node_crashreport["Crash report<br/>utility app<br/>[eecrashreport.cpp]"]
  node_testmaps["Test WADs<br/>test content<br/>[PortTest.wad]"]
end

node_cmake -->|"uses"| node_cmake_support
node_ci -->|"builds"| node_cmake
node_cmake -->|"builds"| node_engine_root
node_cmake -->|"builds"| node_acsvm
node_cmake -->|"builds"| node_libpng
node_cmake -->|"builds"| node_zlib
node_cmake -->|"builds"| node_snes_spc
node_cmake -->|"includes"| node_adlmidi
node_startup -->|"calls"| node_iwad_discovery
node_startup -->|"initializes"| node_wadfs
node_wadfs -->|"loads"| node_content_base
node_wadfs -->|"overlays"| node_content_user
node_wadfs -->|"hands off"| node_game_loop
node_game_loop -->|"drives"| node_simulation
node_game_loop -->|"updates"| node_ui
node_simulation -->|"uses"| node_world_defs
node_simulation -->|"serializes"| node_persistence
node_simulation -->|"publishes"| node_rendering
node_simulation -->|"emits"| node_audio
node_rendering -->|"optionally uses"| node_gl_backend
node_rendering -->|"loads images"| node_libpng
node_rendering -->|"compresses"| node_zlib
node_audio -->|"uses"| node_snes_spc
node_audio -->|"uses"| node_adlmidi
node_audio -->|"adapts through"| node_sdl_backend
node_platform -->|"implements"| node_sdl_backend
node_platform -->|"specializes"| node_os_specific
node_sdl_backend -.->|"supports"| node_launcher
node_sdl_backend -.->|"supports"| node_crashreport
node_ui -->|"reads assets"| node_content_base
node_testmaps -.->|"exercise"| node_simulation

click node_cmake "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/CMakeLists.txt"
click node_ci "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/.github/workflows/build-eternity.yml"
click node_cmake_support "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/cmake/ExternalLibraries.cmake"
click node_engine_root "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/d_main.cpp"
click node_startup "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/d_main.cpp"
click node_wadfs "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/d_files.cpp"
click node_iwad_discovery "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/d_iwad.cpp"
click node_game_loop "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/g_game.cpp"
click node_simulation "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/p_tick.cpp"
click node_world_defs "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/e_edf.cpp"
click node_rendering "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/r_main.cpp"
click node_gl_backend "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/gl/gl_init.cpp"
click node_audio "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/s_sound.cpp"
click node_platform "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/hal/i_platform.h"
click node_sdl_backend "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/sdl/i_main.cpp"
click node_os_specific "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/Win32/i_w32main.cpp"
click node_ui "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/mn_menus.cpp"
click node_persistence "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/p_saveg.cpp"
click node_content_base "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/base/root.edf"
click node_content_user "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/user/doom/delete.me"
click node_acsvm "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/acsvm/ACSVM/Script.cpp"
click node_libpng "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/libpng/png.c"
click node_zlib "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/zlib/deflate.c"
click node_snes_spc "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/snes_spc/SNES_SPC.cpp"
click node_adlmidi "https://github.com/dron12261games/sft-eternity-engine-plus/tree/master/adlmidi"
click node_launcher "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/macosx/launcher/MainStart.m"
click node_crashreport "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/eecrashreport/eecrashreport.cpp"
click node_testmaps "https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/test/PortTest.wad"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmake,node_ci,node_cmake_support toneBlue
class node_engine_root,node_startup,node_wadfs,node_iwad_discovery,node_game_loop,node_simulation,node_world_defs,node_rendering,node_gl_backend,node_audio,node_platform,node_sdl_backend,node_os_specific,node_ui,node_persistence toneAmber
class node_content_base,node_content_user toneMint
class node_acsvm,node_libpng,node_zlib,node_snes_spc,node_adlmidi toneRose
class node_launcher,node_crashreport,node_testmaps toneIndigo
```

## Components

### Build & packaging

Build scripts, CI, and platform packaging support.

- [CMake](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/CMakeLists.txt): build system · Top-level build and packaging entry point. · `CMakeLists.txt`
- [GitHub CI](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/.github/workflows/build-eternity.yml): workflow · Automated build pipeline. · `.github/workflows/build-eternity.yml`
- [CMake extras](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/cmake/ExternalLibraries.cmake): packaging support · Platform, resource, and external-library build helpers. · `cmake/ExternalLibraries.cmake`

### Core runtime

Engine startup, file loading, simulation, rendering, audio, and UI.

- [Engine core](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/d_main.cpp): runtime tree · Main source tree for the Doom-engine fork. · `source/d_main.cpp`
- [Startup](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/d_main.cpp): bootstrap · Executable entry, IWAD/PWAD discovery, and file-system setup. · `source/d_main.cpp`
- [WAD FS](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/d_files.cpp): content loading · WAD/archive handling and file-view construction. · `source/d_files.cpp`
- [IWAD find](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/d_iwad.cpp): content discovery · Discovers canonical game data and user content packs. · `source/d_iwad.cpp`
- [Game loop](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/g_game.cpp): tick orchestration · Owns frame/tic coordination and gameplay progression. · `source/g_game.cpp`
- [Simulation](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/p_tick.cpp): gameplay systems · Map setup, thinkers, physics, sectors, portals, specials, and save-state integration. · `source/p_tick.cpp`
- [World defs](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/e_edf.cpp): data model · Actor, map, weapon, state, and EDF/UDMF integration layers. · `source/e_edf.cpp`
- [Renderer](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/r_main.cpp): render pipeline · Software/engine-side rendering pipeline and OpenGL-specific helpers. · `source/r_main.cpp`
- [GL backend](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/gl/gl_init.cpp): opengl backend · OpenGL initialization, projection, textures, and drawing helpers. · `source/gl/gl_init.cpp`
- [Audio](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/s_sound.cpp): sound system · SFX, music metadata, reverb, and sequence playback orchestration. · `source/s_sound.cpp`
- [Platform HAL](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/hal/i_platform.h): os backend · OS-facing services for video, input, timing, directories, and startup glue. · `source/hal/i_platform.h`
- [SDL layer](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/sdl/i_main.cpp): platform adapter · Cross-platform runtime adapters for input, video, sound, music, and networking. · `source/sdl/i_main.cpp`
- [OS ports](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/Win32/i_w32main.cpp): platform backend · Native platform implementations for Linux, macOS, and Win32. · `source/Win32/i_w32main.cpp`
- [UI shell](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/mn_menus.cpp): frontend · Menus, HUD, automap, intermission, finale, and textscreen widgets. · `source/mn_menus.cpp`
- [Persist & net](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/source/p_saveg.cpp): state sync · Savegames, demo logging, and networking synchronization paths. · `source/p_saveg.cpp`

### Data & mods

Bundled game data, overlays, and resource definitions.

- [Base data](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/base/root.edf): game content · Bundled EDF definitions, resource packs, and startup WAD overlays. · `base/root.edf`
- [User overlays](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/user/doom/delete.me): content overlays · User-facing override trees for fork-specific content packs. · `user/doom/delete.me`

### Vendored deps

Third-party libraries and embedded scripting/runtime dependencies.

- [ACS VM](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/acsvm/ACSVM/Script.cpp): scripting runtime · Embedded ACS virtual machine and support library. · `acsvm/ACSVM/Script.cpp`
- [libpng](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/libpng/png.c): image codec · PNG loading and writing for image/resource support. · `libpng/png.c`
- [zlib](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/zlib/deflate.c): compression · Deflate/inflate support used by runtime and assets. · `zlib/deflate.c`
- [SPC audio](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/snes_spc/SNES_SPC.cpp): audio emulation · SNES SPC emulation used by the music pipeline. · `snes_spc/SNES_SPC.cpp`
- [ADLMIDI](https://github.com/dron12261games/sft-eternity-engine-plus/tree/master/adlmidi): midi submodule · Vendored MIDI playback backend. · `adlmidi`

### Aux executables

Platform launchers, crash tools, and developer utilities.

- [macOS launcher](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/macosx/launcher/MainStart.m): app shell · Native macOS launcher application around the engine. · `macosx/launcher/MainStart.m`
- [Crash report](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/eecrashreport/eecrashreport.cpp): utility app · Windows crash-reporting utility. · `eecrashreport/eecrashreport.cpp`
- [Test WADs](https://github.com/dron12261games/sft-eternity-engine-plus/blob/master/test/PortTest.wad): test content · Focused maps for portal and sector-behavior validation. · `test/PortTest.wad`

## Connections

- CMake → CMake extras: uses · CMake delegates packaging and external dependency wiring to helper scripts.
- GitHub CI → CMake: builds · CI drives the repository through the main build configuration.
- CMake → Engine core: builds · Build system compiles the core engine sources.
- CMake → ACS VM: builds · ACS VM is compiled as a material runtime dependency.
- CMake → libpng: builds · libpng is bundled as a runtime library.
- CMake → zlib: builds · zlib is bundled as a runtime library.
- CMake → SPC audio: builds · SPC emulation library is compiled into the product.
- CMake → ADLMIDI: includes · ADLMIDI is pulled in as a MIDI backend submodule.
- Startup → IWAD find: calls · Startup discovers available IWADs and fork-specific packs.
- Startup → WAD FS: initializes · Startup hands content to the archive/file-system layer.
- WAD FS → Base data: loads · Base EDF and startup resources are mounted into the file view.
- WAD FS → User overlays: overlays · User content trees are merged as overlays.
- WAD FS → Game loop: hands off · After content discovery, control moves into the main game loop.
- Game loop → Simulation: drives · The frame/tic loop advances gameplay simulation.
- Game loop → UI shell: updates · Frontend code observes game and player state.
- Simulation → World defs: uses · Simulation consumes EDF/UDMF-driven gameplay definitions.
- Simulation → Persist & net: serializes · Save, demo, and network state are maintained alongside simulation.
- Simulation → Renderer: publishes · Renderer consumes the updated world state and geometry.
- Simulation → Audio: emits · Gameplay triggers sound and music events.
- Renderer → GL backend: optionally uses · OpenGL path provides a distinct drawing backend.
- Renderer → libpng: loads images · PNG assets are decoded for textures and resources.
- Renderer → zlib: compresses · Compression support backs archive and asset formats.
- Audio → SPC audio: uses · SPC emulation supports music playback.
- Audio → ADLMIDI: uses · MIDI output is delegated to the vendored backend.
- Audio → SDL layer: adapts through · SDL music and sound shims connect engine audio to the OS.
- Platform HAL → SDL layer: implements · SDL modules provide the common runtime backend.
- Platform HAL → OS ports: specializes · Linux, macOS, and Win32 supply platform-specific glue.
- SDL layer → macOS launcher: supports · macOS launcher is part of the SDL-oriented application surface.
- SDL layer → Crash report: supports · Windows utility sits beside the SDL-based runtime family.
- UI shell → Base data: reads assets · Menus, HUD, and frontend screens are data-driven from bundled resources.
- Test WADs → Simulation: exercise · Test WADs validate portals, conveyors, and sector behavior.
