An engine for describing games built around Xerces, exprtk, and SFML.
Each row is one design topic: the options that were considered (a few words each), which one was chosen (if any), and a link to the full write-up. The current, working behavior of the engine is described in ../readme.md. These files record why, and what is still an idea.
Verbs are sometimes written as bounce() or hop.up(distance) for short in these notes; in a game file they are always tags (../readme.md).
Status key: Built = in the code today. Decided = chosen, not built. Leaning = a direction stated but not final. Open = undecided. Idea = floated, not adopted.
| # | Topic | Options considered | Chosen / status | Write-up |
|---|---|---|---|---|
| 01 | Vision and scope | purely declarative / embedded scripting / declarative + triggers | Declarative + condition triggers. Built (basic) |
01 |
| 02 | File format | XML+XSD / academic text VGDL / YAML / JSON; one file vs rules + level file | XML with XSD, one file. Built | 02 |
| 03 | Expression syntax | function-call strings / one element per call / structure for real trees / functions to elements, arithmetic stays | Functions became elements and value tags (<random>); arithmetic stays text. Built |
03 |
| 04 | Arithmetic and XSLT code generation | paste strings / XSLT parses / parse to AST-as-XML then XSLT / remove arithmetic from XML | None yet; AST-as-XML suggested, author prefers no extra tooling. Open | 04 |
| 05 | Variables and evaluation order | declaration order / two-pass symbol collection; topological sort vs lazy | Two-pass up-front registration. Built (chained references: lazy suggested) | 05 |
| 06 | Names and classes | HTML-style name + class; compound selectors; class inheritance; unique instance names |
name + class with filters, and unique names for grid cells (aliens.3.2). Built; the rest Idea |
06 |
| 07 | Object variables and references | polling / listeners / copies / raw pointers; float vs Value variant |
Polling by named reference, float variables. Built; Value variant and handle references Decided. An object’s own size in expressions (title.width, title.height, by object name, to center a text). Built; alignment attributes Idea |
07 |
| 08 | Entity storage, handles, type identity | vector by value / unique_ptr / indices / {index, generation} handle / deque; enum vs data types |
Generational handles, data-driven types. Decided, not built (code uses a vector and name search) | 08 |
| 09 | States and screens | state = screen; flat list / stack; file-prefix naming | Stack of states with shows, inputs, conditions. Built; per-state object behavior (a static object on the menu, moving in play) Open | 09 |
| 10 | Input and named actions | keys bound directly / key to named action to behavior; held keys across state changes: latched to the press / live held keys / cancel on change | Three-layer indirection; held-key combining; live held keys: a state change releases what the old state was driving and resumes the new state’s continuous bindings for keys still down; one-shot verbs (fire, hop) are never resumed. Built |
10 |
| 11 | Collision detection and response | tangled / split detect, dispatch, execute; edge-only vs swept | Split into detector, typed commands, executor; swept object-against-object collision, per-cell grid objects; more verbs in object rules, riding (carry), rule exceptions (unless). Built (rough spots listed) |
11 |
| 12 | Collision escalation | per-type-pair rules / class hierarchy / TCG-style verbs and phases | Verb protocol idea from Mario model. Idea | 12 |
| 13 | Verb vocabulary | small closed set now; static vs dynamic jump; AI targeting modes | Grow only when a game needs it: dec, hop, wrap, carry added for Frogger. Set Built; arcing jump and AI Decided in outline, not built |
13 |
| 14 | Conditions and win conditions | if / trigger; state-level vs object-level; >= only vs richer |
State-level condition: variable threshold (atleast, or atmost from above), or remaining (none left). Built, minimal |
14 |
| 15 | Backend abstraction | concrete node vs interface; pointers vs values; read-only vs mutable; strong vs weak XSD | Interfaces + factories: 4 XML and 3 window backends, Strong/Weak validation. Built | 15 |
| 16 | Code layout and pipeline | layered directories / flat files; parse-validate-evaluate-generate | Pipeline concept kept, tree flattened; no generate step. Built (partial) |
16 |
| 17 | Reference Pong in C++ | tunables, generic helpers, swept vs simple collision | Kept as the yardstick; its swept collision idea is now in the engine (11). Prototype | 17 |
| 18 | Build system | CMake per directory / one root file + modules; find vs FetchContent | One root file, modules in scripts/cmake/. Built |
18 |
| 19 | The VGDL landscape | GDL, RBG, Ludii, PuzzleScript, Griddly, GVGAI | Reference only | 19 |
| 20 | Ideas parking lot | machine-readable state export; growth components; more | Idea | 20 |
| 21 | Frogger and the vocabulary it added | how to say lives, one-step hops, looping lanes, riding, and “unless on a log” | dec/atmost, hop, wrap, carry, unless, more verbs in object rules, named colors. Built |
21 |
| 22 | Motion models | position-driven / constant velocity / accelerated; kinematic vs dynamic and other labels; animation-locked vs free control | Kinematic and dynamic as public words; movement-feel options. Idea | 22 |
| 23 | Jump and air control | jump types (static, dynamic) / jump model plus a per-axis air-control ladder / movement as capabilities | Air-control ladder and capability form refine 13. Idea | 23 |
| 24 | Paths and formations | lookup table / parametric curve / Bezier / command sequence; formation slots | Support all four behind one interface. Idea | 24 |
| 25 | Targets and capability profiles | one target / several targets with limits and degradation reports; null and software backends; tables resolved at load | Long-term direction. Idea | 25 |
| 26 | Scrolling and screen regions | camera / world / region scroll; map layers; tile triggers; route branching | Undecided. Idea | 26 |
| 27 | Object composition and shape | opt-in parts; position and velocity vs at and moving; response block forms; shapes as reusable outlines | Opt-in parts favored. Idea | 27 |
| 28 | Game ideas and test games | Pong variants, mocking difficulty, unwinnable starts, combat styles, packing, balance math | Candidates only. Idea | 28 |
| 29 | Groups | one group per lane with members overriding what differs / group position as an origin / nested groups inheriting / <grid> with per-row velocity / reusable templates |
One group per lane, a member takes what it leaves out from its group; read as one object per member, and Frogger and Space Race are written with it (about 30% smaller). Built | 29 |
| 30 | Kaboom | a fixed set of falling pieces that cycle / pieces spawned while the game runs / a dropper object that releases them; speeds drawn once at load / drawn again on every reset; one miss acts on all bombs via a condition on a tally | A fixed set that cycles, speeds and heights drawn once with <random> inside a <group>, a state per wave, a tally variable that a condition turns into the explosion. Built (no new verbs); the bomber dropping bombs, spawning and re-drawing on reset Idea |
30 |
| 31 | Freeway | timed rounds / first to N crossings; knocked back a lane / sent to the start; lives or none | First to N crossings, sent to the start, no lives; two players share one road. Built (no new verbs); a clock Idea | 31 |
| 32 | Depth Charge | ammunition that counts every shot / counts only misses; several charges in flight / one | Count only misses with dec in the charge’s floor rule, one charge at a time. Built (no new verbs) |
32 |
| 33 | Astrosmash | rocks that split or drift / a fixed set that cycles; a miss that costs nothing / costs a life | A fixed set that cycles and fall in straight columns, a miss costs a life. Built (no new verbs); splitting needs spawning, Idea | 33 |
| 34 | Lunar Lander | a picture from lines / a box with parts; pixel testing for all / opt-in; gravity per object / a world setting | <line> sprites, <type>pixel</type> behind the box sweep, <acceleration>, held <accelerate> with burn, <stop />, <slower>/<faster>. Built |
34 |
| 35 | Library and front ends | engine as one program / a library with front ends; static / shared linking; one GUI project now / later | A library with two programs, XGECLI and XGEGUI (first a stub, now the Qt application of 38); static by default, shared behind XGE_BUILD_SHARED. Built |
35 |
| 36 | Built-in font | no font file means no text / text from a font stored in the program; a TTF in the executable / a small bitmap table | An 8x8 bitmap font in builtin_font.cpp, drawn through Bitmap. Built |
36 |
| 37 | Command line | positional game only / options with attached or spaced values / --name=value; defaults / required backends |
-g, -w, -x (and long forms), bare game kept, --game pong spaced only. Built |
37 |
| 38 | Qt front end | embed an SFML/SDL2 window in Qt / draw the picture ourselves with a Qt backend; a tree of the data / a form per object; edit the running game / a copy | A Window backend that draws with QPainter into a Qt widget, a tree of the XML structure with an editor on each changeable value, the engine run from a timer so it can be paused and stepped. Built; other video libraries are shown by 39 and 40 |
38 |
| 39 | OpenGL backend and Options | embed raylib/GLFW by reparenting / draw them to a back buffer; GLFW with a loader / plain OpenGL 1.1; options on restart / swap the window live | A GLFW OpenGLWindow in plain OpenGL 1.1, Engine::replaceWindow, and an Options dialog (video, XML parser) that pauses the game while it is open. The embedding it first used (WindowTarget, back buffers, context juggling) was removed by 40. Built |
39 |
| 40 | One window or two in XGEGUI | embed every video library in the main window / Qt’s own surface only in one window, and a second window of the library’s own for the rest | One window draws with the Qt renderer; a View option, or picking a video library (after a question that can be turned off, kept in xgegui.ini), moves the game to a window of its own that the library opens as it does in XGECLI. All the embedding code was removed, and the game view is an ordinary widget so Qt uses no OpenGL. Built |
40 |
| 41 | Asteroids | rotate at draw time / pre-rotated pictures at load; spawn while running / pools of hidden objects and a release verb | <heading>, <turn>, <thrust>, <drag>, <hidden>, <release>, <fire> from a pool along the heading. Built |
41 |
| 42 | Bitmap sprites and animation | ASCII rows / an image file / more lines; one text block / <row> elements; a palette / one colour per sprite; a clock per object / a global one |
<bitmap> rows (* filled, . clear) with an optional <scale>, named <sprite>s, an <animation> of <frame>s on an interval in seconds, and <fire> centred on the shooter. Built |
42 |
New to the project: readme, then 01, 02, 03, 09, 10, 11. Working on the language: 03, 04, 12, 13, 14, 21, 22, 23, 24, 29. Working on the C++: 07, 08, 15, 16, 25.
Compiled by Claude (Sonnet 5.5) on 2026-09-29 from the author’s exported conversation history (see ../agents/sources.md) and checked against the source on the claude branch. A second batch (docs 22 to 28, plus new sections headed second batch in earlier docs) came from a second export on 2026-09-30.