Quick Game Markup Language

QGML is a tool that allows you to structure your game with an HTML-like language and script it using JavaScript.

What it is

a quick way to prototype little web games

What it isn't

a fully-fledged game engine meant for polished games

Installation

$ npm i -g @qgml/cli

CLI Quick Start

Compilation

$ qgml --source myFile

Serve

$ qgml --source myFile --serve 8000

This will serve the compiled game at localhost:8000

note: serving also provides hot-reloading, so, if you modify the qgml file it should automatically reload and apply the changes in your web browser

note2: if you edit an asset (sprite or spritesheet) you have to run qgml again, it won't hot-reload it

For a full list of commands use

$ qgml --help

Quick Start

<qgml
	width = 300
	height = 300
>
	<world default>
		<actor
			id = "my-rect"
			state = ({
				position: { x: 20, y: 20 },
				size: { width: 50, height: 50 },
				color: 'blue'
			})
		/>
	</world>
</qgml>

pro tip: you can save qgml files as .html so that you get syntax highlighting in your favourite code editor!

Tags

QGML

<qgml></qgml>

Think of this as the root element; all other tags are children of it. It contains the configuration for the canvas

Props

| prop | data type | description | | ------------- | --------- | ------------------------------------------------------------ | | width | number | the width of the canvas (default: 300) | | height | number | the height of the canvas (default: 300) | | rootElementID | string | the id of the HTML element in your web page that the canvas should be appended to (default: 'qgml-game') | | debug | boolean | if this prop is present, the game will show the fps, frame-time, and number of actors in the top left |

World

<world></world>

Worlds are basically screens or scenes in your game; an example of worlds would be menu, level1, level2

Props

| props | data type | description | | ------- | --------- | ------------------------------------------------------------ | | id | string | the id of the world; this will be used in scripting to switch between worlds | | default | boolean | if this prop is present the world will be the one loaded as soon as the game starts. If your game has a menu screen, that one would be the default world |

Actor

<actor/>

An actor is anything that appears on the screen: the player, the ground, an object, etc

actor is a self closing tag because it cannot contain anything itself.

Props

| prop | data type | description | | -------- | --------- | ------------------------------------------------------------ | | id | string | the id of the player; this is useful if you want to do anything in script to this actor | | state | object | a state object | | sprite | string | the path relative to the qgml file to an image file | | animator | object | an animator object | | setup | function | a function that is called once when the world is loaded | | update | function | a function that is called every frame | | class | string | the class of the actor |

Animator

The animator overrides the sprite prop. This is used to add animations to certain actors

| property | data type | description | | ------------ | --------- | ----------------------- | | spritesheets | object | the spritesheets object |

Spritesheets

spritesheets: {
    idle: {
        frames: ['path/to/frame0', 'path/to/frame/1', etc],
        frameTime: 10
    },
    //or
    run: {
        strip: 'path/to/animation/strip.png',
        frames: 8,
        frameTime: 10
    },
    etc
}

frames - an array containing the relative paths to frames (images) or the number of frames in a strip

frameTime - the number of game ticks (frames) each animation frame should stay on screen [1 - change each frame (fastest), 10 - change every 10 frames, etc]

strip - the path to an animation strip

example of an animation strip (credit):

Example

<actor
	id = "player"
	state = ({...})
	animator = ({
		spritesheets: {
			idle: {
				strip: './assets/noBKG_KnightIdle_strip.png',
				frames: 15,
				frameTime: 10
			}
		}
	})
/>

[!] Note about setup and update

If the function you pass to setup or update uses classic notation (function () { ... }), the context within it (this) will be the actor itself; so, you will be able to write this.state.position which will return the actor's position, or this.animator which will return the actor's animator.

If the function you pass uses arrow notation (() => { ... }), the context (this) will be the QGML context.

TLDR: it is recommended that you use classic notation for functions passed to setup and update

example:

<actor
	update = (function () {
		console.log (this.state); // will log the actor's state
	})
/>

while

<actor
	update = (() => {
		console.log (this.state); // undefined
	})
/>

Group

<group>{children}</group>

Groups can be used to group together multiple Actors or Groups so that they can move all at once.

Props

| prop | data type | description | | ------ | --------- | ------------------------------------------------------------ | | id | string | just like the id of an actor, this can be used to access this group in a script | | state | object | a state object | | setup | function | a function that is called once when the world is loaded | | update | function | a function that is called every frame |

Modifying a group's position will move all of its children accordingly

<group id = "player">
	<actor id = "player-body"/>
	<group id = "nested" >
		<actor/>
	</group>
</group>

[!] Note about setup and update - everything said about applies

Var (Variables)

<var name = value />

Variables declared in a certain World are only accessible in that world, while variables declared outside of all worlds are considered global and can be accessed and modified from any world.

A single var tag can be used to declare multiple variables, for example

<var
	score = 0
	playerPosition = {
		x: 0,
		y: 0
	}
	playerName = "base name"
/>

Text

<text>text to display</text>

It is used to display text on the canvas

| prop | data type | description | | ----- | --------- | ------------------------------------------------------------ | | state | object | a state object | | font | string | the name of a web-safe font or the name of a font that you're already loading on your web page |

You can use placeholders inside of it to display the values of variables

<text state = { position: { x: 50, y: 100 } }>
	hello! your position is ${playerPosition.x} , ${playerPosition.y}
	and your score is ${score}
</text>

State Objects

| property | data type | description | applies to | | -------- | ---------------------------------------- | ---------------------- | ------------------ | | position | Object { x : Number, y : Number} | the initial position | actor, group, text | | size | Object { width: Number, height: Number } | the initial actor size | actor | | size | Number | the font size | text | | color | String | the fill color | actor, text | | stroke | Object { weight: Number, color: String } | the stroke / outline | actor, text | | style | String | the style of the text | text | | align | String | the text alignment | text |

color

any of the following formats are okay:

• "rgb(255, 125, 60)"
• "rgba(0, 25, 125, 0.5)"
• "rgba(0,0,0,0)"
• "red", "blue", "lightblue", etc.
• if color is omitted or set to false the rectangle will be transparent

style

• "normal"
• "bold"
• "italic"
• "bolditalic"

align

• "right"
• "center"
• "left"

Keymapper

<keymapper/>

The keymapper is used to bind functions to certain keyboard events. Keymappers are specific to the world they are declared inside.

Each prop has the following structure: <key or group of keys>|<event> = (<function>)

key:

• literal value of the key (w, a, s, d, etc)
• keycode of the key (32, 87, etc)
• one of the following special keys: backspace, delete, enter, return, tab, escape, shift, control, option, alt, up_arrow, down_arrow, left_arrow, right_arrow, space

group of keys

it's represented as [<key>,<key>,<key>,...]

event - for keys

• down - will fire every frame while the key is held down

• up - will fire every frame while the key is not held down

• pressed - will fire once when the key is pressed [DEFAULT]

• released - will fire once when the key is released

event - for groups of keys

• down - will fire every frame while all the keys are held down

• up - will fire every frame while none of the keys are held down

• pressed - will fire once after each key has been pressed at least once

• released - will fire once after every key has been released

example:

<keymapper
	a|down = (() => {
		console.log ('this will fire every frame while the A key is down');
	})
    
	space|pressed = (() => {
		console.log ('this will fire every time space is pressed');
	})
    
	16|released = (() => {
		console.log ('16 is the keycode for shift so this will fire everytime shift is released');
	})
    
	[q,e]|up = (() => {
		console.log ('this will fire every frame while Q and E are both up');
	})
/>

Script

<script></script>

Scripts are used to add JavaScript code that is executed either in setup (once, when the world is loaded) or in update (every frame)

Scripts are specific to the world they are declared in.

<script setup>
	console.log ('this is executed once when the world is loaded');
</script>

<script update>
	console.log ('this is executed every frame');
</script>

Actor-Template

<actor-template/>

Templates are used to spawn actors of the same type programmatically (from scripts and such).

An example of an actor template would be:

<actor-template
	id = "zombie"
	sprite = "./assets/zombie.png"
	update = (function () {
		// zombie behaviour            
	})
/>

Which you can then instantiate inside <script> tags or inside other actors' setup and update

spawn ('zombie', {
	position: {
		x: 10,
		y: 20
	}, size: {
		width: 40,
		height: 70
	}
});

You can check out the spawn function in the API section below.

Text-Template

<text-template>text</text-template>

Just like actor templates, text templates are used to spawn text objects programmatically.

API

Actors

getActor (id: String) - returns the actor with the specified ID

getActorsByClass (class: String) - returns an array of actors with the specified class

<Actor>.state - returns the state of the actor - this is read-only, the state is not meant to be modified

<Actor>.direction - returns the direction that actor is facing on both axis

<Actor>.getPosition () - returns the actor's position

<Actor>.direction.set (axis: String, value: String || Number)

• axis can be either 'horizontal' or 'vertical'
• value can be:
  • 'left' or -1 - for axis == 'horizontal'
  • 'right' or 1 - for axis == 'horizontal'
  • 'up' or 1 - for axis == 'vertical'
  • 'down' or -1 - for axis == 'vertical'

<Actor>.flip.horizontal () - flips the direction horizontally

<Actor>.flip.vertical () - flips the direction vertically

<Actor>.animator - returns the animator of an actor

overlaps (a1: Actor, a2: Actor) - returns true if the actors overlap

spawn (actorTemplateID: String, initialState: stateObject) - spawns a new actor from a specified actor-template, assigns its state to the initial state object, and assigns its class to the template id; it returns the new actor, or null if the specified template id does not exist.

Animator

<Animator>.set (animation: String) - sets the animator's animation to the specified one (ex: 'idle', 'run' - depending on how you declared the animator)

<Animator>.play (animation: String[, onAnimationDone: Function]) - plays the specified animation once, then calls the callback function if one is passed

Group

getGroup (id: String) - returns the group with the specified ID

<Group>.state - returns the state of the group - this is read-only, the state is not meant to be modified

<Group>.getPosition () - returns the position of the group

Entity

Entity = either Actor or Group

dist (x1: Number, y1: Number, x2: Number, y2: Number) - returns the distance between the points (x1, y1) and (x2, y2)

dist (e1: Entity, e2: Entity) - returns the distance between the two entities' positions

getPosition (e: Entity) - returns the entity's position