Zion

A light-weight, un-opinionated game engine/library based on HTML5 Canvas game development.

Built along the course CSC 481/591 Game Engine Development, @NC State, 2017.

Table of Contents

• Zion
• Get Started
• Features
  • Game Flow
  • Base Classes
  • Basic Rendering
  • Physics
  • Particle Systems
  • I/O
  • Network
  • AI
• Gallery Page
• Contribution
• Acknowledgement

Get Started

npm install --save zion-engine

import zion from 'zion-engine';

Features

Game Flow

To build a game, whatever platform it's based on, we can think of the whole game as a (infinite) state machine. The flow is all about updating state and rendering the canvas in a constant interval (game loop).

The more you decouple between the state updating logic and the game rendering, the easier your game is to maintain and scale.

import zion from 'zion';

const { Game } = zion.createComponents();
// in your entry file you'll have the main class extend the base class `Game`

class MyGame extends Game {
  constructor() {
    this.gameloop = this.gameloop.bind(this);
  }

  update() {

  }

  render() {

  }

  init() {
    // run update and render consecutively, in a constant interval
    const timer = setInterval(this.gameLoop, TIME_INTERVAL);
  }
}

Base Classes

To conform to the Object-Oriented Paradigm, a few base classes are provided for extension.

const { Sprite } = zion.createComponents();

class SnakeSegment extends Sprite {
  // ...
}

• Game The game entry class. We suggest you extend it in your main game file.
• Sprite The basic build block which are integrated into a larger scene.
• SpriteSheet A bitmap image class that contains several smaller graphics in a tiled grid arrangement. Used in animations.
• Particle and ParticleSystem See Particle Systems.
• Obstacle An extendable collision-detection system. See Physics.

Basic Rendering

Zion provides a few rendering utilities on top of the native canvas API, like clearCanvas(), coordinateConversion(), insertText(), etc, which save you from diving too deep into the fuss.

Specifically, for image rendering, Zion uses the canvas-image-cache, which enhances the performance in a way that image instances will not be recreated from scratch for each rendering after being loaded at first.

const cu = zion.createCanvasUtils();

cu.clearCanvas(canvas, context);

The basic APIs below:

• clearCanvas(canvas, context)
• coordinateConversion(canvas, x, y) : get the coordination with respect to the canvas boundaries
• getBoundaries({ x, y }, size)
• generateRandomPosition(canvas, middle = false, spriteSize)
• createImageCache(): create the canvas-image-cache utility
• drawRotate(context, { img, x, y, degrees }): draw rotate sprites
• insertText(context, options = {}): insert text into canvas

Physics

Zion provides a basic physics engine for sprite-sprite collisions called Obstacle. Unlike traditional bounding-box based systems, the engine sub-divides each obstacle into a pre-set number of low, medium, or high boundary levels. This implementation eliminiates the need for entire sprite collision checks as the system can more finely detect intersections at specific sprite edges.

Obstacles can be managed in groups or individually, depending on your game's structure:

// Create a new obstacle. The last parameter specifies the divisionType for creating the different
// boundary levels (0 - 2: Low, Medium, High).
let obstacle = new Obstacle(src, {width: 16, height: 16}, {x: 0, y: 0}, 0);

Collision between obstacles and sprites is not strictly enforced. You may choose to apply collision through calling the getCollision() method from any obstacle. In this manner, obstacles and sprites that should not have collision are ignored.

let car = new Sprite('car.png', size, position);

/**
 * objOffset specifies how close the sprite being examined should be allowed to come within 
 * the obstacle's range. boundsOffset extends the base distance at which it collides with
 * the obstacle.
 */
if(obstacle.getCollision(car, objOffset, boundsOffset)) {
  // do something
}

Zion provides additional support for debugging collision:

• getDetails() Returns a string representation of this Obstacle's properties (size, position, divisionType, boundaries)
• drawBoundariesDebug() Draws red squares indicating the on-screen location of an Obstacle's boundaries (use in your draw() function).

Particle Systems

Zion supports an extendable particle system for grouped-sprite management. For visual effects, Zion provides two functions for easy object creation: createUniformParticles() and createRandomizedParticles(). The former allows simple creation of uniform particle sets, providing an efficient solution for multiple like-objects. The latter allows for randomized particle set creation, suitable for varied graphical effects and unevenly distributed objects (e.g. varying sprite sizes, speeds, etc.). All particles extend our Obstacle Physics System, requiring no additional collision detection.

You can create a new Particle System by supplying a Particle's desired properties:

 // Create two new ParticleSystems: one uniform, one random
 let boulders = new ParticleSystem();
 let fire = new ParticleSystem();

 // Supply properties for the uniform system
 boulders.createUniformParticles(src, size, position, speed, numParticles, divisionType);

 // Specify options and create random particles
 let properties = {
     src: 'fire.png',
     size: {width: 10, height: 10},
     maxHorizontal: 30,
     maxVertical: 40,
     speed: 5,
     divisionType: 0
 };
 fire.createRandomizedParticles(options);

I/O

Keyboard Handler

Zion uses KeyBus as its keyboard handling component. It supports basic keyboard event, and wraps up a hash-based simultaneous multikey handler functionality(Why?).

Basic Usage:

import KeyBus from 'keybus'

const kb = new KeyBus(document)

let enterKeydownHandler = kb.down(13, () => console.log('Enter keydown!'))

// to remove the keydown event handler for a specific key and event
enterKeydownHandler.remove()

Multikey handler:

const canvas = document.getElementById('my-canvas')
const kb = new KeyBus(canvas)

kb.simulDown(38, () => console.log('up'))
kb.simulDown(39, () => console.log('right'))

function game_loop() {
  // the only thing you need to do is to call this method in every game loop,
  // the keybus will automatically check if anykey is pressed and run the according handlers (could be more than one)
  kb.executeMultiKeyHandlers();
}

Audio Manager

Zion provides a wrapper for managing audio assets. The AudioManager class allows you to create, load, and play game audio. This class can be easily extended to support more advanced game features: