XMLGameEngine is a VGDL (video game description language) and an engine for running games completely contained within an XML file.
Gotchas that are easy to get wrong. How the engine works is the reference; why, and the backlog, is the design index. Rules and layout: AGENTS.md.
games/descriptions/, one test file per area in xge/tests/. New work lands on working ahead of master: check git branch -r and git log first.near, far, min, max, small, interface, ERROR. Never name anything one of them (-Dnear= -Dfar= on a syntax-only compile catches it).CmdLive, remade by Game::makeNow), a condition’s number (Condition::live).<random> is drawn again when its object comes back into play, not when a scene is entered.float. Anything that changes one goes through Game::setVariable, so bound texts and expressions see it.+ - * /, a sign and brackets (load/calc). A function call stops the load: write a <formula>. window.width is not a name (window.right is).liveParts (game/object.cpp); a new one is one row.operationShape (game/command.cpp), a case in evaluateOperation (load/expr.cpp) and the schema types. Each Answer has a late flag for values not final while loading; keep it.game_expr::compiled); a name is bound into calc only when first read. There is no second expression system.Moment (game/object.h), with start and before. A number a reset should put back goes in Moment and nowhere else. placed marks a reset or load between frames, whose place is not a move.from= are worked out on the XML first (load/merge.cpp), and the same in merge.xsl. Change one, change the other step for step: xgetest-generated compares the order of objects.layOutScenes flattens owned objects into data.objects named by path and writes every name out in full.isShown is visible and running in the top state; isStill is drawn under a <show state>; isAway is in a scene not current.Game::tryGetObject falls back to the end of one path, so tests may say getObject("ball"); carrying and owners hold full names.<reset object="x" /> resets every variable of x; a rule’s bare <reset /> only its own object. Never put <reset object="player" /> in someone else’s rule; keep score and lives on an object no state shows.<reset /> in an object’s timer only moves it back; it does not restart timers or variables.collisionData.others is the object-against-object rule list.Game::applyPaths runs after timers, before acceleration. Anything ending a path clears followPath.isAirborne()) is in no pair. A resting object stays touching its platform only because its pull moves it each frame, so <stop /> ends that.<land /> that runs first can hide a hazard met at the same moment (Pitfall’s jaws are written before the crocodiles).sprite= on a rule is the look as the touch happened, taken once.Object::spin; moveObjects turns it through the frame in advanceTo, and sweepTurning tests the pictures at each whole degree. The heading follows half a cosine over swingFrames. knock uses velocityAt(touch.point).knockedApart’s settle (four frames of pull) stops a resting ball hopping; <friction> (rub) may set Object::resting, which applyAcceleration wakes when the thing or a support moves.groundDrag/groundGrip from findGround; use those, not drag/grip.sprite=/unless= are an EdgeGuard; class= or object= on one is a load error.Game never touches audio: <play> queues a name.cellHolder finds nothing in, so a picker or marks on the board’s own map would block it: keep them on a map of their own.countMoves fills live moves; it is 0 while the piece is not shown.<put> turns a trapped piece by despawning it and spawning the putter’s template; copies sit in spawned until the frame ends, so live moves leaves out pieces put this frame.<think> copies every kind it reads (Kind) and never points into the game, since in a window it runs on its own thread (thinkInBackground). Tests have no loop, so they search in the frame. Random choice among equal moves is made on the game’s side.Engine::runAsPress judges each trigger’s from= by the look at the press. An axis <trigger from=> is honoured: give the look, or it runs in every look.cellHolder answers from a snapshot while a Game::CellsStill guard lives. Never move a piece on cells while one is held.RawCommand fields renamed for self in object.cpp, given scene values in scenes.cpp, generated in data.xsl and compared in test_generated_games.cpp. A new half goes in all of them.Game::spawned and join, and despawned ones go, in settleSpawns(), which calls rosterChanged() and drops every cache.playing.wave1.bomb.1).objects must be rebuilt in rosterChanged().ShapeKind::Line, built in buildPicture. Never draw or turn in a backend.<poses> starts as standing.<become object="group"> changes members out of play too.<stop /> takes the pull away until a reset, so it is no landing for something that can be knocked up again.<grip> below 1 brakes an object with no keys held: never give it to a thing that moves by velocity alone.<arc> is drawn through altitude; tests compare positions, not drawn spots.RawObject made in code (a deck’s cards) must have sprite equal to looks.front().drawOrder: 0 first in file order, then the rest sorted.<become> does not change an object’s size until the frame ends, so name.width later in the same list is the old look’s. Give looks placed by size the same size.Each rests on something that never changes while a game runs: FrameRules::partners and mazeGrid; tryGetObject’s answers and matching; game_expr::compiled; isShown, kept until stageChanged(). Anything new that changes the state stack, a scene or an object’s owner calls stageChanged().
xgetest "[.speed]" prints every game’s load and frame times to compare builds.
CommandExecutor::run. A new verb needs a line there, in ruleFor (load/check.cpp) and in the schema’s command groups. Use didYouMean and listOf in any name error.on="hold" and on="release" answer only a press made in the current state.Game without an Engine calls setCurrentState(0) and measureShapeSize, or nothing is shown and sizes are 0.settleSpawns() first. Never hold a reference to a copy across frames; look it up by name.games/, so a test names descriptions/<game>.xml and finds the schema with findSchema("descriptions/pong.xml", "../xgedef.xsd"). ctest runs from output/<config>/games, a plain run from the repository’s games/: check a new schema test both ways.scratchName(), so ctest -j never has two cases writing one file.circleOverlapsBox, add a test to test_collision_geometry.cpp.invaders_fixture.h is a frozen copy of the first Space Invaders.Engine::pump().pollEvents() must not call PollInputEvents(); Escape is not its exit key; a texture drawn into a render texture must live until EndTextureMode().SDL_Quit().XGE_WITH_<NAME>: build with no options as well as with tests when touching factories, cli.cpp or session_options.cpp.-DBUILD_SHARED_LIBS=ON links. A target named m collides with plutovg’s -lm.data.xsl is a second reader: a new tag or Raw* field needs the same there (and in the describer in test_generated_games.cpp), maybe a helper in game_parts.h.addCell, addMember): a Debug build gives each statement its own stack slots, and Breakout’s bricks once overflowed a 1 MB stack. Check under ulimit -s 1024.--; libxml2 refuses the stylesheet.engine.xml and assets.cmake; one that reads XML or chooses libraries stays out (keep game/game.cpp and engine/engine.cpp free of load/xml.h and the factories).Raw* change, cmake --build build --target xgetest-generated.QOpenGLWidget without a guard around every library call.GameSession swaps game or window checks its changing guard.QSpinBox borders (the arrows vanish).key_queue.cpp).This repository is public. Nothing personal from a chat export goes in it: no health, identity, contact or business details, no conversation titles, and no names beyond the beefviper handle in the code headers. Design files call the owner “the author”.