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

Commands

A command is a tag in a list: a collision rule, an action, a key’s <input>, a condition, a timer, or a path’s step. A list runs in the order written.

Where a command can go

Commands are sorted by what they need. Each place takes only the groups that mean something there; anything else is a schema error (and, read without the schema, a load error listing what can go there: ruleFor in load/check.cpp).

Group Commands Needs
changes inc, dec, set, copy, rank, play, silence, become, reveal, follow, shift, enter, reset, spawn, despawn object=, trigger nothing: they name what they change
flow push, pop, turns, pass, out, demo the game’s running order
self die, drop, move, release, reverse, stop, fire, despawn; on cells settle, slide, cycle, grow, split, pick, place an object running it
steering aim, chase, hunt, wander an object to steer
touch carry, deflect, hole, knock, land, ride another object touched
edge stick, wrap a screen edge
bounce bounce a screen edge or another object
controls accelerate, climb, go, hop, jump, leap, thrust, turn, track a key held or pressed
press hold, think a computer player
Place Takes
a <collision> with another object changes, self, steering, touch, bounce
a <collision edge> changes, self, edge, bounce
an object’s <action> changes, self, steering, controls
an object’s <timer>, a path’s <step> changes, self, steering
a state’s or scene’s <input>, <condition>, <timer> changes, flow
a <computer>’s <condition> press

A press that cannot be done

A verb that is refused ends its list: what is written after it is not done; what is before it has run. In a collision, only that rule’s rest is dropped; later rules still run.

<fire object="bullet" /><play sound="shoot" />   <!-- sounds only when a shot leaves -->

Refused are: a <fire> or <spawn> at its <most>; a <hop>, <jump> or hunt by hops in the air or landing outside the window; a <leap> off the ground; an <aim> with <lined> not lined up; a <pick>, <place> or <put> that is no move; a card <take> or <lay> the pile does not allow; a spawn into a taken cell. So write the verb first and its answers after.

An object out of play does nothing when its action is pressed or triggered; letting go still lets go.

Moving

Command Does
<move direction="up">step</move> in an action, held: step pixels a frame while the key is down (held keys). In a rule: shifts it once
<hop direction="up">distance</hop> once a press: a step made before collisions, judged where it lands; refused off the window. Diagonals up-left … down-right, by distance or <x> and <y>
<seconds>, <arc> in a <hop> or <jump> it takes that long through the air, touching nothing until it lands; <arc> lifts its altitude to that height half way
<jump direction="down">90<seconds>0.35</seconds></jump> a timed straight jump (0.3 s by default), refused off the screen
<leap>height</leap> a jump up under its own pull to about that height; only from the ground, fixed sideways until a <land />. Needs an acceleration down and a <land /> rule
<land /> in a rule: coming down onto the other’s top, it stands there. Any other side, or going up, does nothing (one-way platforms)
<climb direction="up" class="ladder">step</climb> held: at an object of that class, gets on, lines up and climbs; at an end steps off onto what it lands on, or holds there if nothing is. Stacked pieces are one ladder. Run by a rule or timer, it takes one ladder and lets go
<accelerate direction="up" burn="fuel">amount</accelerate> held: adds to the velocity every frame; burn takes 1 off its own variable each frame and stops at 0
<thrust burn="fuel">amount</thrust> held: the same along its <heading>
<turn direction="clockwise">degrees</turn> held: turns the heading that much a frame
<swing direction="counterclockwise"><degrees>60</degrees><seconds>0.1</seconds></swing> held: one eased, swept stroke, and back when let go (turning about a pivot)
<reverse /> the velocity turns round
<stop /> still for good (velocity 0, no pull, no held keys) until a reset
<track />, <track path="rail" /> run by a pointing control: goes where it points; with path=, that far along the path

Steering

Command Does
<chase object="hero">1.5<near>100</near></chase> heads straight for the nearest of that name at that speed, stopping within <near>. It acts once, so a timer repeats it
<aim object="man" /> its next <fire>s go straight at where that one was. <lined>8</lined>: only along one of eight ways, within 8 pixels, else refused
<follow path="dive" /> flies a path; object="aliens" sends every one, <stagger>0.15</stagger> apart; <nearest>2</nearest> only the two nearest
<shift object="aliens"><x>sway.way</x></shift> moves those objects, and the places they fly home to; a reset puts them back
<go direction="left">speed</go> a maze walker turns that way at the first tile it can; on cells, keeps stepping
<hunt object="pacman">2<ahead>4</ahead><with object="blinky" /><retreat object="corner">8</retreat></hunt> a maze walker, at every tile, takes the open way whose next tile is nearest a target: the quarry, <ahead> tiles in front of it, doubled away from a <with> partner, or a corner while within <retreat> tiles. Ties go up, left, down, right
<hunt object="qbert"><hop><x>32</x><y>48</y><seconds>0.3</seconds></hop></hunt> hunts by hops: of four hops, the one landing nearest the target
<wander>1.25</wander> a maze walker takes a random open way at every tile, never back

Touching

Command Does
<bounce />, <bounce>0.8</bounce> mirrors the velocity about the way the surface faces, keeping that share of its speed (above 1: a bumper). A box’s side or screen edge gives the plain flip; a pixel picture its drawn slope
<deflect>45</deflect> off another object at up to that angle, by where along the side it hit; speed kept (Pong)
<knock />, <knock>0.5</knock> the two meet as things with weight (knocks)
<stick /> stops only the velocity into the edge or side touched, so it slides along
<wrap /> once wholly off a screen edge, put back in from the opposite one
<through /> a refused cell step is made anyway; the two share the cell
<ride /> lent the other’s velocity this frame (a frog on a log)
<carry /> picks up what it touched and takes it along until a <drop />; one at a time
<drop /> puts down what it carries; on a picker or hand, puts back
<hole>4<rough>0.5</rough></hole> cuts a round hole in its own picture where it was struck; a reset mends it. Lines, polygons or a plain bitmap only

In and out of play

Command Does
<die /> out of play (not drawn, moved or touched) until a <reveal> or reset
<reset /> in an object’s place: back as it started. In a state’s place: a new game (every object back, copies gone, scenes started again, the stack down to the first state), except what is kept
<reset object="name" /> that object or group back as it started, every variable included, and its copies gone. So never reset the player from another’s rule: keep score on an object of its own
<reset scene="room1" />, <reset way="out" /> a scene back as it started
<enter scene="room2" />, <enter way="east" /> makes that scene current; the one left stays as it was
<reveal object="blocks">count</reveal> brings back the first count (default 1) out of play, where they started
<release object="debris">count</release> puts count into play at the middle of the object running it: copies of a kit piece, or from a pool
<fire object="shot" /> launches a copy (or pool member): along an aim; else from its facing side; else from its nose along a heading; else from its top with the shot’s own velocity
<spawn object="ball"> a new copy, placed and moving as its <position>, <velocity>, <acceleration> say, read as it runs: <x><centered>self.x + 5</centered></x>
<despawn />, <despawn object="bomb" /> takes it, or every copy of that name, out of the game (spawn and despawn)

Numbers

Command Does
<inc variable="ship.score" />, <inc variable="ship.score">self.worth</inc> adds 1, or the amount
<dec variable="frog.lives" /> takes 1, or the amount, off; may go below 0
<set variable="target">value</set> an object’s variable or a live number (x, y, velocity.x, velocity.y, heading, altitude, rise, light, blink). A group’s name sets every member
<copy variable="ship.score" into="best.score" /> the second takes the first’s number now
<count class="black" into="score.black" /> how many of that class are in play
<rank variable="entry.score" into="table" /> the entry takes its place in a table of the best

The variable must belong to an object; one no object has stops the load.

Look and sound

Command Does
<become sprite="blue" /> shows that look. object= changes that name or group (out of play too); from="normal" only those showing it; style="angry" a palette swap
<play sound="zap" /> a sound, played once the frame’s work is done; on a key a loop plays while held
<silence sound="thrust" /> stops that sound

Flow

Command Does
<push state="paused" /> puts that state over the current one
<pop /> back to the state below (never past the first)
<pop state="result" /> this state goes and that one takes its place
<trigger object="ship" action="fire" /> runs an object’s action as one press. On a group, each member. from="normal" only those showing that look (on a key, the look at the press). In an object’s own places object= may be left out
<turns>, <pass />, <out /> players taking turns
<demo /> plays the recorded <demo>
<hold button="l" /> a computer player holds that key

Actions that trigger one another in a circle stop the load.

Mistakes the loader catches

A game that would play wrong stops loading, saying where and, for a likely typo, what was meant. Names are checked once everything is built, so a name used before what it names is fine.

object 'ball' > <collisions> > <collision>: unknown command <explode>
there is no key named 'spcae' (did you mean 'space'?)