XMLGameEngine

XMLGameEngine is a VGDL (video game description language) and an engine for running games completely contained within an XML file.

View the Project on GitHub beefviper/XMLGameEngine

AGENTS.md

XMLGameEngine is a video game description language in XML plus a C++ engine that runs it. A game is one .xml file (games/descriptions/), checked against games/xgedef.xsd; behavior comes from a closed vocabulary of verb tags, never from code in the file.

Read in this order

  1. docs/readme.md: the guide to the docs, a short tour and an index of every word.
  2. docs/reference/: how the engine works today, a page per topic (format, objects, collisions, commands, states, the engine, limitations). The authority on behaviour.
  3. docs/designs/00-designs.md: index of one small file per topic: why, options rejected, ideas, backlog. Open only the one for your area.
  4. docs/agents/notes.md: gotchas.

The root readme.md is the short public overview.

Layout

Path What
xge/lib/ xgelib, the engine, a folder per part (game/, play/, load/, xml/, window/, audio/, picture/, engine/), each header beside its source, included as "game/game.h". Throws, never exit()s
xge/cli/, xge/gui/ xgecli; xgegui (Qt 6, built only when Qt is found)
xge/tests/ Catch2 (xgetest), one test_<topic>.cpp per area; games are played frame by frame
games/xgedef.xsd the schema, the definition of the language; games name it ../xgedef.xsd
games/descriptions/, games/assets/ the games; their media
games/generators/ the XSLT stylesheets xgecli --generate runs, a folder per target
scripts/cmake/, scripts/shell/ CMake modules; shell/linux/ prerequisite installers, shell/windows/games-run-all.bat [config] runs games-generate-all.bat (every game into output/<config>/generated/<game>/), games-build-all.bat (each with MSVC at /W4) and games-test-all.bat (builds and runs xgetest-generated)

The programs make games/ their working directory (engine/folder.h), so asset paths in a game file (assets/paddle.jpg) and the tests’ paths (descriptions/pong.xml) are relative to it.

Flow: load/xml (parse, validate; load/merge works out the <kit> and every from= on the XML first) → game/scenes (layOutScenes: states’ and scenes’ objects named by path) → load/expr (evaluate; load/calc works out the arithmetic in text) → Object/State → Game with play/frame (one frame) + Engine (loop, windows, sound). Backends sit behind XmlDocument, Window and Audio factories.

Build and test

cmake -B build -DBUILD_TESTING=ON
cmake --build build --parallel
output/Debug/xgetest            # Catch2 filters work, e.g. "[kaboom]"
cd build && ctest -j16          # each case its own run, side by side
cmake --build build --target xgetest-generated && output/Debug/xgetest-generated   # generated games, separate
output/Debug/xgecli frogger     # -w window, -x xml, -a audio libraries

A plain build has one backend of each kind (SFML 3, Xerces); -DXGE_WITH_<NAME>=ON adds one, -DXGE_ALL_BACKENDS=ON all, and BUILD_TESTING implies all. Backend code is compiled behind XGE_WITH_<NAME>, so build with no options as well as with tests when you touch the factories, cli.cpp or session_options.cpp. FORCE_LOCAL_<NAME> forces a fetched dependency. Outputs land in output/<Config>.

Conventions