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

Objects

An object is anything drawn, moved or touched. name is required; class is optional (a kind that rules and conditions match); from= takes a piece of the kit.

<object name="ball" class="ball">
  <sprite><circle><radius>8</radius></circle></sprite>
  <position><x><centered /></x><y>100</y></position>
  <velocity><x>3</x><y>2</y></velocity>
  <collisions>
    <collision edge="vertical"><bounce /></collision>
  </collisions>
</object>

Parts of an object

What is left out is nothing: no velocity stands still, no <collisions> touches nothing. Every part but the position is optional. In this order:

Part What it does
<sprite> what it looks like: one shape. Several named sprites are looks or animation frames
<animation> which sprites show, in what order, for how long
<position> where it starts, <x> and <y> from the top left. <centered>value</centered> puts its middle there instead (empty: the window’s middle). Required unless it has no sprite
<velocity> pixels a frame, <x> and <y>; a half left out is 0
<acceleration> added to the velocity every frame: gravity is a <y>. <stop /> takes it away, a reset gives it back
<heading> degrees clockwise from straight up. Lets <turn>, <thrust>, <swing> work, and turns the picture
<pivot> the point the picture turns about (turning about a pivot); the position is then where that point sits
<drag> 0 up to 1: the share of its speed lost each frame
<friction> 0 or more: how much a still surface holds it back, and what brings it to rest
<mass> above 0: how hard it is to knock. None: a knock does not move it
<surface> this is ground: a <drag> and <grip> that a gripping thing over it takes (surfaces)
<pull object="sun">strength</pull> that much more speed toward the nearest of that name each frame; several add up
<seek object="ship">degrees</seek> a homing missile: its way turns toward the nearest of that name, at most that much a frame, keeping its speed
<light>, <dark> how far it lights; drawn only when lit (light and dark)
<altitude>, <shadow object> height off the ground; kept under another (height and shadows)
<facing> up, down, left, right, without turning the picture: follows its last move; a <fire> leaves that way
<poses>, <mirror>, <grip> looks picked by how it moves, flipped pictures, how its speed follows the keys (poses)
<maze map="maze"> walks that map’s tiles (walking a map)
<active> false: starts out of play (not drawn, touching nothing, not counted) until a <reveal>, <release> or <fire>
<drawn> false: in play but never drawn: an exit, a trigger zone
<most> how many copies may be out at once
<collisions> how and what it touches (collisions). Written, it is on unless <enabled>false</enabled>; <collisions /> alone is something others touch
<actions> named <action>s that a key or a rule runs
<variables> its own numbers, read anywhere as name.variable
<timers> what it does every so often, or once after a while (timers)

A group’s member, a map’s piece and a kit piece have the same parts (the schema’s objectParts), so they cannot drift apart.

Numbers only

An object with no <sprite> only holds numbers: never drawn, no position, and it must have <variables> or <timers>. Keep score, lives and clock on one that no state draws (Pitfall’s status), so resetting the player does not touch them.

<object name="status">
  <variables>
    <variable name="score">0</variable>
    <variable name="lives">3</variable>
  </variables>
</object>

An object with class="projectile" starts out of play, waiting to be fired.

Groups

A <group> is several objects written once. It gives what its members share, then lists them; whatever a member leaves out it takes from its group.

<group name="logrow3" class="logs">
  <sprite><rectangle><width>3 * cell</width><height>body</height><color>color.brown</color></rectangle></sprite>
  <position><y>3 * cell</y></position>                 <!-- the row, once -->
  <velocity><x>-1</x></velocity>
  <collisions><collision edge="horizontal"><wrap /></collision></collisions>
  <member><position><x>20</x></position></member>      <!-- where each starts -->
  <member><position><x>272</x></position></member>
  <member name="last"><position><x>524</x></position></member>
</group>

Groups inside a group

A group can hold groups instead of members; an inner group takes from the one around it the same way. Frogger writes <wrap /> once for all ten lanes:

<group name="lanes">
  <rows>1</rows>
  <collisions><collision edge="horizontal"><wrap /></collision></collisions>
  <group name="river" class="logs">
    <sprite><bitmap> ... </bitmap></sprite>
    <group name="logrow2">
      <columns>3</columns>
      <padding><x>(window.right + 180) / 3 - 180</x></padding>
      <position><x>20</x><y>2 * cell + 6</y></position>
      <velocity><x>1.4</x></velocity>
    </group>
    <group name="logrow4"> ... </group>
  </group>
  <group name="traffic" class="hazard"> ... </group>
</group>

Columns and rows

Instead of members, a group can lay out a block: <columns> and <rows> make a cell per place, <padding> is the gap. Its <position> is the top left of the first cell.

<group name="bricks" class="bricks">
  <columns>14</columns>
  <rows>8</rows>
  <padding><x>4</x><y>4</y></padding>
  <sprite><rectangle><width>brick</width><height>12</height><color>color.red</color></rectangle></sprite>
  <position><x>margin</x><y>top</y></position>
  <row><number>3</number><number>4</number><sprite><rectangle><color>color.orange</color></rectangle></sprite></row>
  <row number="5"><sprite><rectangle><color>color.green</color></rectangle></sprite></row>
  <cell row="1" column="7" name="boss"> ... </cell>
</group>
Tag Picks Can change
<row number="2"> one row; several by a <number> each; every other by <odd /> or <even /> sprites, animation, velocity, padding (<y> the gap above, <x> between its cells), variables
<column number="..."> columns, the same way the same; its <x> padding is the gap to its left
<cell row column name> one cell, which it may name sprites, animation, velocity, variables

The kit and from=

The <kit> holds objects, groups and maps written once, called pieces. A piece is never in play itself: it comes into play where an <objects> takes it, or as copies a spawn makes.

<kit>
  <object name="paddle" class="paddle"> ... </object>
  <object name="bomb" class="bomb"> ... <most>6</most> </object>   <!-- only ever spawned -->
</kit>
<objects>
  <object name="paddle1" from="paddle"><position><x>10</x></position></object>
  <object name="paddle2" from="paddle"><position><x>780</x></position></object>
</objects>

The one change rule

A take, a state from= another and a scene from= another all change what they start from the same way:

What is written Does
attributes (class) replace
a <sprite> or <animation> replaces the one of that name, whole, or is added
an <x> or <y> of position, velocity, acceleration or padding replaces that half
a <variable>, <action>, <timer> replaces the one of that name, or is added (an unnamed timer is added)
<collision> rules are added after
<solid>s; <member>s, <row>s, <column>s, <cell>s replace all of them
an inner group or map piece of the same name is changed the same way, or added
anything else replaces that tag

These stop the load: a from= naming no piece, taking a name the list already has, a map from= an object (or the reverse), two pieces of one name, a piece from= a later one, a dotted name (rocks.2; name the member instead).

All of this is worked out on the XML before any object is read (load/merge.cpp), and the same in XSLT for a generated program (merge.xsl).

Spawn and despawn

Objects can be made and taken away while the game runs, and a copy is the same as an object the file wrote.

<action name="fire">
  <fire object="shot" />                 <!-- a new copy of the kit's shot -->
  <play sound="zap" />                   <!-- only if one left -->
</action>
...
<object name="shot" class="shot">        <!-- in the kit -->
  <sprite> ... </sprite>
  <velocity><y>-8</y></velocity>
  <most>3</most>
  <collisions>
    <collision edge="all"><despawn /></collision>
    <collision class="rock"><despawn /></collision>
  </collisions>
</object>

A group of <active>false</active> members is still a pool that <fire>, <release> and <reveal> take from; it suits things that come back where they were (Frostbite’s igloo blocks).