How dron12261games/sft-eternity-engine-plus works
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 CMake · p_tick.cpp Simulation · d_files.cpp WAD FS · r_main.cpp Renderer
Components 28
Build & packaging
Build scripts, CI, and platform packaging support.
- CMake · Top-level build and packaging entry point.
CMakeLists.txt - GitHub CI · Automated build pipeline.
.github/workflows/build-eternity.yml - CMake extras · Platform, resource, and external-library build helpers.
cmake/ExternalLibraries.cmake
Core runtime
Engine startup, file loading, simulation, rendering, audio, and UI.
- Engine core · Main source tree for the Doom-engine fork.
source/d_main.cpp - Startup · Executable entry, IWAD/PWAD discovery, and file-system setup.
source/d_main.cpp - WAD FS · WAD/archive handling and file-view construction.
source/d_files.cpp - IWAD find · Discovers canonical game data and user content packs.
source/d_iwad.cpp - Game loop · Owns frame/tic coordination and gameplay progression.
source/g_game.cpp - Simulation · Map setup, thinkers, physics, sectors, portals, specials, and save-state integration.
source/p_tick.cpp - World defs · Actor, map, weapon, state, and EDF/UDMF integration layers.
source/e_edf.cpp - Renderer · Software/engine-side rendering pipeline and OpenGL-specific helpers.
source/r_main.cpp - GL backend · OpenGL initialization, projection, textures, and drawing helpers.
source/gl/gl_init.cpp - Audio · SFX, music metadata, reverb, and sequence playback orchestration.
source/s_sound.cpp - Platform HAL · OS-facing services for video, input, timing, directories, and startup glue.
source/hal/i_platform.h - SDL layer · Cross-platform runtime adapters for input, video, sound, music, and networking.
source/sdl/i_main.cpp - OS ports · Native platform implementations for Linux, macOS, and Win32.
source/Win32/i_w32main.cpp - UI shell · Menus, HUD, automap, intermission, finale, and textscreen widgets.
source/mn_menus.cpp - Persist & net · Savegames, demo logging, and networking synchronization paths.
source/p_saveg.cpp
Data & mods
Bundled game data, overlays, and resource definitions.
- Base data · Bundled EDF definitions, resource packs, and startup WAD overlays.
base/root.edf - User 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 · Embedded ACS virtual machine and support library.
acsvm/ACSVM/Script.cpp - libpng · PNG loading and writing for image/resource support.
libpng/png.c - zlib · Deflate/inflate support used by runtime and assets.
zlib/deflate.c - SPC audio · SNES SPC emulation used by the music pipeline.
snes_spc/SNES_SPC.cpp - ADLMIDI · Vendored MIDI playback backend.
adlmidi
Aux executables
Platform launchers, crash tools, and developer utilities.
- macOS launcher · Native macOS launcher application around the engine.
macosx/launcher/MainStart.m - Crash report · Windows crash-reporting utility.
eecrashreport/eecrashreport.cpp - Test WADs · Focused maps for portal and sector-behavior validation.
test/PortTest.wad
Connections 31
- 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.