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

States and scenes

A state is a mode of the game (title, playing, paused, game over). A state played in several places holds them as scenes. Conditions are tests checked every frame.

States

The first state in the file is where the game starts. name is required; from copies an earlier state. Children, in this order:

Element What it does
<objects> the state’s own objects, in play whenever it is current, in every scene of it
<scenes> the places it is played in, one current at a time (scenes)
<shows> <show object="best" /> runs another’s object as its own; <show set="end" /> a shared set; <show state="playing" /> draws that state’s objects still underneath
<music sound> a looping sound plays while it is current (restarting after a pause); one that does not loop plays as it begins
<inputs> the keys (input). Needed unless the state is from= another
<conditions> tests checked every frame (conditions)
<computer> a player the game plays itself (computer players)
<timers> timers that count while it is current
<state name="paused">
  <objects>
    <object name="paused"> ... </object>     <!-- the PAUSED text -->
  </objects>
  <shows>
    <show state="playing" />                 <!-- the game, still, under it -->
  </shows>
  <inputs>
    <input button="space"><pop /></input>
  </inputs>
</state>

A state from another

<state name="gameover" from="youwin"> is a copy of an earlier state with what it writes over it, by the one change rule. Its objects are named by the new state (gameover.message). Its <input>s replace the copied ones of the same key, conditions and timers those of the same name=, music the copied. A state with scenes cannot be copied yet.

<state name="gameover" from="youwin">
  <objects>
    <object name="message">
      <sprite><text style="banner"><content>GAME OVER</content></text></sprite>
    </object>
  </objects>
</state>

Scenes

One scene is current, and only its objects are in play, beside the state’s own.

<state name="playing">
  <objects>
    <object name="hero"> ... </object>              <!-- in every scene -->
  </objects>
  <scenes>
    <scene name="room1">
      <ways><way name="out" scene="room2" /></ways>
      <variables><variable name="pace">2</variable></variables>
      <objects>
        <object name="topwall" />                   <!-- the kit's, as it is -->
        <group name="robots"><velocity><x>pace</x></velocity></group>   <!-- the kit's, changed -->
        <object name="exit"> ... </object>          <!-- its own -->
      </objects>
      <conditions> ... </conditions>
      <timers> ... </timers>
    </scene>
    <scene name="room2" from="room1">               <!-- room1, but its pace and way -->
      <ways><way name="out" scene="room1" /></ways>
      <variables><variable name="pace">3</variable></variables>
    </scene>
  </scenes>
</state>

Shared sets

At the top of <states>, named sets hold what several states share; a set can take an earlier set.

Conditions

<condition object="frog" variable="lives">
  <atmost>0</atmost>
  <push state="gameover" />
</condition>

A condition is checked every frame while its state (or scene) is current. It holds when an object matching class= and/or object= passes its test, and then runs its commands. The first condition that holds runs, and no more that frame, so order matters. A name= lets a scene’s from= replace it.

Test Holds when the number is
<atleast>N</atleast> N or more
<atmost>N</atmost> N or less (lives counting down)
<above>N</above>, <below>N</below>, <equal>N</equal> more than, less than, equal to N
<remaining>N</remaining> no more than N of the matched objects are in play (class="aliens" with 0: all shot)
<condition>
  <all>
    <condition object="dragon" distance="hero"><below>160</below></condition>
    <condition object="dragon" variable="awake"><equal>0</equal></condition>
  </all>
  <inc variable="dragon.awake" />
  <become object="dragon" sprite="awake" />
</condition>

Keeps

A new game puts every object back as it started; the objects in <keeps> keep their variables, place and looks.

<keeps>
  <keep object="best" />
</keeps>
...
<condition object="ship" variable="score">
  <above>best.score</above>
  <copy variable="ship.score" into="best.score" />
</condition>

On disk. The programs write each kept object’s variables and look to saves/<game>.xml in the games folder when a new game starts and when they close, and read it at load. A game that keeps nothing writes nothing; tests write nothing unless asked. Delete the file to start again.

A table of the best

A group whose members are the places, best first, and <rank variable="entry.score" into="table" />: the entry takes the first place whose score is below its own, all its variables going in, and the rest move down. A tie goes below. Whether a score makes it is a condition, <above>table.5.score</above>.

<group name="table">
  <sprite><text><letter>table.first</letter><letter>table.second</letter><letter>table.third</letter><number>table.score</number></text></sprite>
  ...
</group>
...
<input button="space"><rank variable="entry.score" into="table" /><reset /></input>

Taking turns

Players take turns as the arcade machines did: each plays a game of their own, and the machine swaps them.

<input button="num2">
  <push state="playing" />
  <turns>
    <player state="player1" />
    <player state="player2" />
  </turns>
</input>

Attract mode

A game’s <demo>, after <states>, is a recorded game: the random seed, how many frames, and each key pressed and released on its frame.

<demo>
  <seed>20261016</seed>
  <frames>1200</frames>
  <press button="space">30</press>
  <release button="space">34</release>
  ...
</demo>

<demo /> plays it as a new game from the seed, so it plays out exactly as recorded. A key pressed, or the recording running out, ends it with a new game, kept things as they were (a demo never sets the best). xgecli <game> --record writes one into the file, keeping its line endings.

Computer players

A state’s <computer> is a player the game plays itself, pressing the state’s keys as a person would: conditions whose commands are <hold button>s. Every condition is tested every frame; the keys of those that hold are held, the rest let go.

<computer>
  <condition object="cpu" variable="x"><below>ball.x</below><hold button="l" /></condition>
  <condition object="cpu" variable="x"><above>ball.x</above><hold button="j" /></condition>
</computer>

A condition can be gated on a mode (an <all> with a players variable the title sets), so one state serves one player and two. Pong’s two levels are both plain conditions.

Thinking

For a board game, a condition may hold a <think> instead of <hold>s:

<computer>
  <condition>
    <all>
      <condition object="match" variable="players"><equal>1</equal></condition>
      <condition object="cursor" variable="turn"><equal>2</equal></condition>
    </all>
    <think class="white" object="cursor" button="f12">
      <depth>4</depth>
      <worth sprite="king">3</worth>
    </think>
  </condition>
</computer>

A <hold> or <think> anywhere else, or any other command in a <computer>, stops the load.