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

The game file

The shape of a game file, how numbers and names are written, and the game-wide parts: window, variables, styles, colours.

Layout

One <game> root, its children in this order (the schema enforces it):

<game xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="../xgedef.xsd">
  <window name="Pong"> ... </window>   <!-- size, scale, background, frame rate -->
  <variables> ... </variables>         <!-- numbers the whole game uses -->
  <sounds> ... </sounds>               <!-- optional: notes and music -->
  <paths> ... </paths>                 <!-- optional: routes objects fly -->
  <styles> ... </styles>               <!-- optional: named text and bitmap looks -->
  <kit> ... </kit>                     <!-- optional: pieces written once, taken below -->
  <objects> ... </objects>             <!-- optional: what every state shares -->
  <keeps> ... </keeps>                 <!-- optional: what a new game passes over -->
  <states> ... </states>               <!-- title, playing, paused, game over ... -->
  <demo> ... </demo>                   <!-- optional: a recorded game -->
</game>

The format’s one rule

An attribute names or picks something; everything else is element content.

<inc variable="paddle1.score" />                          <!-- names -->
<collision edge="left"> ... </collision>                  <!-- picks -->
<radius>10</radius>                                       <!-- a number: content -->
<chase object="hero">2</chase>                            <!-- a verb's one number: content -->
<jump direction="up">rowgap<seconds>leap</seconds></jump> <!-- more numbers: named tags -->

Values

Every number in a game (a position, a speed, a size, a threshold) is a value, written one of three ways. A value holds text or one tag, never both.

Form Example
arithmetic as text window.width.center - title.width / 2
<random> <random><min>-7</min><max>7</max></random>
<formula> the same arithmetic as tags (below)

When a value is worked out

Once, at load, except:

A <random> is drawn at load and again whenever its object comes back into play: a reset (of it, its scene or the game), a <reveal>, <release> or <fire>, or a new copy. So each Pong serve is new. A game-level <random> is drawn once; entering a scene draws nothing.

Names a value can use

Name Value
window.top, window.left 0
window.bottom, window.right the window’s height, its width
window.width.center, window.height.center half the width, half the height
a game <variable> its value (worked out in the order written)
object.variable that object’s variable, wherever the object is written
object.width, object.height its size (its sprite’s footprint); meant for <position>
object.timer a named object timer’s time left
object.x, .y, .velocity.x, .velocity.y, .heading, .altitude, .rise, .light, .blink live numbers: its top left, how it goes, its height, light, blinking
self. before any of these in an object’s own rules, actions and timers, the object running it
touch.x, .y, .along, .depth, .normal.x, .normal.y in a rule about another object: the point, where along the object’s side (0 to 1), how deep, the way out of the other

An object’s own <variable> named like a size or live number (width, x) wins over it.

Values read when used

A command whose numbers name something that changes is worked out each time it runs:

<inc variable="player.score">self.worth</inc>                     <!-- the worth of the fish just landed -->
<set variable="shark.velocity.x">shark.velocity.x * 1.1</set>     <!-- speed the shark up -->
<above>gun2.score</above>                                         <!-- a test following gun 2's score -->

Every other value is fixed at load, and one that is not a command’s (a position, a size) naming a live number stops the load, since nothing is anywhere yet.

Arithmetic as tags

A <formula> is one operation whose operands are elements, each a name, a number, a <random> or another operation. Precedence is the nesting, so nothing is parsed. Plain sums stay text; what text cannot say is a formula.

<x>
  <formula>
    <subtract>
      <minuend>window.width.center</minuend>
      <subtrahend><divide><dividend>title.width</dividend><divisor>2</divisor></divide></subtrahend>
    </subtract>
  </formula>
</x>
Operation Operands Gives
<add> <augend>, <addend>s sum
<subtract> <minuend>, <subtrahend>s difference
<multiply> <multiplicand>, <multiplier>s product
<divide> <dividend>, <divisor>s quotient
<remainder> <dividend>, one <divisor> what is left, from 0 up to the divisor (-1 of 4 is 3)
<smallest>, <largest> two or more <value>s the smallest, the largest
<absolute>, <negate>, <sign> one <value> without its sign; turned over; -1, 0 or 1
<floor>, <ceiling>, <round> one <value> down, up, nearest (a half away from 0)
<sine>, <cosine> one <value> of an angle in degrees
<clamp> <value>, <atleast>, <atmost> the value kept between the two
<compare> <value>, then one of <above>, <below>, <atleast>, <atmost>, <equal> 1 if it passes, else 0

Names

Names are dotted, and every dot means “inside”:

Name Is
ball.radius the ball’s variable radius
logrow3.2, aliens.3.2, maze.dots.17 a group’s member, a cell (column 3, row 2), a map’s piece
playing.hero the state playing’s own object
playing.room2.robots.3 a member of a scene’s group
playing.room2.pace a scene’s variable
shot.1 a copy made while the game runs

Window

<window name="Pong"> (the title), then in this order:

Element Default Meaning
<width>, <height> required the game’s size in pixels, plain whole numbers
<scale> 1 each game pixel drawn this many window pixels across. Mario Bros. is 256 by 224 at <scale>3</scale>. The mouse is read back in game pixels
<background> color.black a colour
<fullscreen> false  
<framerate> 60 frames a second, up to 255. It is how often the whole engine runs, keys and timers too, so a slow game keeps 60 and steps on a timer

Variables

<variables>
  <variable name="margin">30</variable>
  <variable name="paddle">margin * 4</variable>
  <variable name="start"><random><min>1</min><max>3</max></random></variable>
</variables>

Game-level variables are named constants, worked out in the order written. Declaring one twice keeps the later. Numbers that change belong to objects (paddle1.score); an object with no picture can hold them (numbers only).

Styles

A style is a named look taken by <text style="..."> or <bitmap style="...">. What a text or bitmap gives itself wins.

<styles>
  <style name="banner"><size>64</size><color>color.red</color><font>assets/pressstart2p.ttf</font></style>
  <style name="mario">
    <scale>3</scale>
    <color>color.red</color>              <!-- the * pixels -->
    <color char="b">color.blue</color>    <!-- each b pixel -->
  </style>
</styles>
Part For Meaning
<size> text a value, worked out with the game’s names
<scale> bitmap pixels per character
<color>, <color char="x"> text takes the plain one; a bitmap all colours
<font> text a font file under the games folder. Default assets/tuffy.ttf; assets/pressstart2p.ttf is 8 by 8 at size 8 (use multiples of 8), under the SIL OFL in pressstart2p-ofl.txt

A style= naming no style, or a text left with no size, stops the load. The games name styles by role: banner, prompt, help, keys, hud.

Palette swap

<become style="angry" /> puts another style’s colours on an object’s bitmaps.

Mario Bros.’ pests are drawn once per kind; one that gets up by itself does <become style="angry" />, and one angry style recolours every kind.

Colours

Every colour is written color.<name>: black, white, red, green, blue, yellow, magenta, cyan, and the muted grey, darkgrey, lightgrey, brown, orange, purple, darkblue, darkgreen, forestgreen, gold, peach (picture/color.cpp). Any other name stops the load.