excalibur DocumentationRelease

Erik Onarheim, Josh Edeen, Kamran Ayub

Aug 12, 2017

User Documentation

1 Installing Excalibur.js 31.1 Getting Excalibur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Unstable Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 Example Project Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Referencing Excalibur Standalone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.5 Referencing Excalibur via Triple-Slash Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.6 Referencing Excalibur as a Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Getting Started 72.1 Download and Install Excalibur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Build Your Game Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.3 Hello Excalibur: Building Breakout! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3 Features 13

4 Installation 154.1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.2 API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.3 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.4 Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.5 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.6 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5 Indices and tables 17

i

ii

excalibur Documentation, Release

Excalibur is a simple, free game engine written in TypeScript for making 2D games in HTML5 canvas. Our goalwith Excalibur is to make it incredibly simple to create and write 2D HTML/JS games aimed at folks new to gamedevelopment all the way up to more experienced game developers. We take care of all the boilerplate engine code,cross-platform targeting, and more so you don’t have to. Use as much or as little as you need!

Excalibur is an open source project licensed under the 2-clause BSD license (this means you can use it in commercialprojects!). It’s free and always will be. We welcome any feedback or contributions! If you make something withExcalbur, please let us know so we can feature you in our online gallery.

User Documentation 1

excalibur Documentation, Release

2 User Documentation

CHAPTER 1

Installing Excalibur.js

Getting Excalibur

There are several ways you can download Excalibur.

npm (Best for TypeScript projects):

npm install excalibur

Nuget:

Install-Package Excalibur

Yeoman Generator

You can use the Excalibur Yeoman generator to spin up a blank, ready-to-go Excalibur game:

# Install Yeoman globallynpm install -g yo# Install the Excalibur generator globallynpm install -g @excaliburjs/generator-excalibur# Create the folder you want your game to be inmkdir my-game# Go into the foldercd my-game# Run the excalibur generatoryo @excaliburjs/excalibur

The Yeoman generator will automatically create the appropriate package.json and bower.json files and install theneeded dependencies for your project.

Raw Script Files

You can also download the raw Javascript files from the Excalibur Distribution repository.

3

excalibur Documentation, Release

Note: Remember, Excalibur is a client-side library and cannot be used in a server-side Node.js project.

Unstable Builds

If you want to live on the edge and get unstable builds, you can add the Excalibur Appveyor Nuget feed to your project,see unstable.

Example Project Templates

The excaliburjs organization on GitHub has several example projects:

• TypeScript, Angular2 & SystemJS

• TypeScript & Webpack

• TypeScript & Browserify

• Universal Windows Platform (UWP)

• Apache Cordova

• Xamarin Forms

• Electron

These examples allow you to simply clone and start building your game!

Referencing Excalibur Standalone

Just include the excalibur.min.js file on your page and you’ll be set.

<!DOCTYPE html><html lang="en">

<head></head><body>

<script src="excalibur.min.js"></script></body>

</html>

Referencing Excalibur via Triple-Slash Reference

For a simple TypeScript-based game, using triple-slash references works great. It requires no extra module system orloaders.

/// <reference path="node_modules/excalibur/dist/excalibur.d.ts" />

var game = new ex.Engine({ ... });

4 Chapter 1. Installing Excalibur.js

excalibur Documentation, Release

Make sure the path is relative to the current TS file. You only need to include the reference on your “entrypoint” file.Then simply include excalibur.min.js as mentioned above in your HTML page.

You can also reference Excalibur through the tsconfig.json.

{"compilerOptions": {

"target": "es5","outFile": "game.js","types": ["excalibur"]

}}

Referencing Excalibur as a Module

Excalibur is built using the AMD module system. The standalone files excalibur.js or excalibur.min.jsuse the UMD module syntax at runtime to support CommonJS (Node-like), AMD, and a global browser fallback. It isauto-loaded into the ex global namespace. These are the recommended files to use for production deployments.

You can optionally use excalibur.amd.js and excalibur.amd.d.ts to load Excalibur using an AMD-compatible loader (such as jspm). Note that this method is harder to reference via TypeScript.

To get started, first install Excalibur through npm (TypeScript typings are best supported in npm):

npm install excalibur -D

In a TypeScript project, you can reference Excalibur with the ES6 import style syntax:

// Excalibur is loaded into the ex global namespaceimport * as ex from 'excalibur'

At runtime, you should still include excalibur.min.js standalone. In a module loader system, such as SystemJS,you must mark excalibur as an external module.

An example SystemJS configuration:

System.config({paths: {// paths serve as alias'npm:': 'node_modules/'

},// map tells the System loader where to look for thingsmap: {// our app is within the app folderapp: 'app',// excalibur in an npm module'excalibur': 'npm:excalibur/dist/excalibur.js'

},// packages tells the System loader how to load when no filename and/or no extensionpackages: {app: {

main: './main.js',defaultExtension: 'js'

}});

1.6. Referencing Excalibur as a Module 5

excalibur Documentation, Release

6 Chapter 1. Installing Excalibur.js

CHAPTER 2

Getting Started

Download and Install Excalibur

Review the Installing Excalibur.js for instructions.

Build Your Game Script

Create a script in your project, here I’ve named it game.js. Excalibur games are built off of the ex.Enginecontainer. It is important to start the engine once you are done building your game.

Note: ProTip™ Call game.start() right away so you don’t forget

// game.js

// Create an instance of the engine.// I'm specifying that the game be 800 pixels wide by 600 pixels tall.// If no dimensions are specified the game will be fullscreen.var game = new ex.Engine({

width: 800,height: 600

});// todo build awesome game here

// Start the engine to begin the game.game.start();

Include your game script after the excalibur script.

<html><head></head>

7

excalibur Documentation, Release

<body><!-- Include your script at the end of the body tag --><script src="excalibur-version.js"></script><script src="game.js"></script>

</body></html>...

Open a browser and view the blank blue screen of goodness.

Hello Excalibur: Building Breakout!

That’s cool, but let’s make something more interesting on the screen.

To do this Excalibur uses a primitive called an Actor, and places actors into a Scene. Think of actors like you wouldthe actors in a play. Actors are the primary way to draw things to the screen.

Note: ProTip™ Actors must be added to a scene to be drawn or updated! game.add(actor) Will add an actor tothe current scene.

Note: Important! Actors have a default anchor of (0.5, 0.5) which means their position is centered (not top-left) bydefault.

// game.js

// Create an instance of the engine.var game = new ex.Engine({

width: 800,height: 600

});

// Create an actor with x position of 150px,// y position of 40px from the bottom of the screen,// width of 200px, height and a height of 20pxvar paddle = new ex.Actor(150, game.getDrawHeight() - 40, 200, 20);

// Let's give it some color with one of the predefined// color constantspaddle.color = ex.Color.Chartreuse;

// Make sure the paddle can partipate in collisions, by default excalibur actors do→˓not collidepaddle.collisionType = ex.CollisionType.Fixed;

// `game.add` is the same as calling// `game.currentScene.add`game.add(paddle);

// Start the engine to begin the game.game.start();

8 Chapter 2. Getting Started

excalibur Documentation, Release

Open up your favorite browser and you should see something like this:

That’s neat, but this game is way more fun if things move around. Let’s make the paddle follow the mouse around inthe x direction.

// Add a mouse move listenergame.input.pointers.primary.on('move', function (evt) {

paddle.pos.x = evt.x;});

What’s breakout without the ball? To make the ball bounce, Excalibur comes prebuilt with an “elastic” collision typethat does naive elastic collisions, which is sufficient for breakout.

// Create a ballvar ball = new ex.Actor(100, 300, 20, 20);

// Set the colorball.color = ex.Color.Red;

// Set the velocity in pixels per secondball.vel.setTo(100, 100);

// Set the collision Type to elasticball.collisionType = ex.CollisionType.Elastic;

// Add the ball to the current scene

2.3. Hello Excalibur: Building Breakout! 9

excalibur Documentation, Release

game.add(ball);

The ball will now bounce off of the paddle, but does not bounce with the side of the screen. To fix that, let’s takeadvantage of the update event.

// Wire up to the update eventball.on('update', function () {

// If the ball collides with the left side// of the screen reverse the x velocityif (this.pos.x < (this.getWidth() / 2)) {

this.vel.x *= -1;}

// If the ball collides with the right side// of the screen reverse the x velocityif (this.pos.x + (this.getWidth() / 2) > game.getDrawWidth()) {

this.vel.x *= -1;}

// If the ball collides with the top// of the screen reverse the y velocityif (this.pos.y < (this.getHeight() / 2)) {

this.vel.y *= -1;}

});

Don’t like square balls? Neither do we. You can create your own custom drawing function like so:

// Draw is passed a rendering context and a delta in milliseconds since the last frameball.draw = function (ctx, delta) {

// Optionally call original 'base' method// ex.Actor.prototype.draw.call(this, ctx, delta)

// Custom draw codectx.fillStyle = this.color.toString();ctx.beginPath();ctx.arc(this.pos.x, this.pos.y, 10, 0, Math.PI * 2);ctx.closePath();ctx.fill();

}

Note: ProTip™ Overriding a method like this will remove any built-in Excalibur functionality. If you would like tocall the original draw for example ex.Actor.prototype.draw.call(this, ctx, delta)

Breakout needs some bricks to break. To do this we calculate our brick layout and add them to the current scene.

// Build Bricks

// Padding between bricksvar padding = 20; // pxvar xoffset = 65; // x-offsetvar yoffset = 20; // y-offsetvar columns = 5;var rows = 3;

var brickColor = [ex.Color.Violet, ex.Color.Orange, ex.Color.Yellow];

10 Chapter 2. Getting Started

excalibur Documentation, Release

// Individual brick width with padding factored invar brickWidth = game.getDrawWidth() / columns - padding - padding/columns; // pxvar brickHeight = 30; // pxvar bricks = [];for (var j = 0; j < rows; j++) {

for (var i = 0; i < columns; i++) {bricks.push(new ex.Actor(xoffset + i * (brickWidth + padding) + padding,

→˓yoffset + j * (brickHeight + padding) + padding, brickWidth, brickHeight,→˓brickColor[j % brickColor.length]));

}}

bricks.forEach(function (brick) {// Make sure that bricks can participate in collisionsbrick.collisionType = ex.CollisionType.Active;

// Add the brick to the current scene to be drawngame.add(brick);

});

When the ball collides with bricks, we want to remove them from the scene.

// On collision remove the brickball.on('collision', function (ev) {

if (bricks.indexOf(ev.other) > -1) {// kill removes an actor from the current scene// therefore it will no longer be drawn or updatedev.other.kill();

}});

Finally, if the ball leaves the screen, the player loses!

ball.on('exitviewport', function(){alert('You lose!');

});

2.3. Hello Excalibur: Building Breakout! 11

excalibur Documentation, Release

Congratulations! You have just created your first game in Excalibur! Please review the documentation for moreexamples and an API Reference.

12 Chapter 2. Getting Started

CHAPTER 3

Features

We are still pre-1.0 but Excalibur has many powerful features built-in already that make it simple to build and designyour games:

• Built with TypeScript first

• Fully-documented API

• Works in all major browsers (Chrome, Firefox, IE11) and most mobile browsers (Android Chrome, AppleSafari)

• HTML Canvas-based rendering engine

• Full Web Audio support and fallback HTML5 audio support

• Full HTML5 Gamepad API support

• Full keyboard, mouse, and touch support using a unified Pointers API

• Support for basic collisions

• Support for rigid body physics system <https://excaliburjs.com/docs/api/edge/classes/_physics_.physics.html>‘_

• Cross-platform support using Electron or Apache Cordova

• Simple update/draw pattern to keep logic and drawing separated

• Simple Actor model with Scenes, Actions API, cameras, and more

• Preloader API supporting resources like images, sounds, video, and generic resources

• Basic primitives like sprites, spritesheets, animations, and textures

• Sprite effects, particle emitters and post processor support

• Support for tile-based maps (with Tiled support)

• Logging API for debugging

• Promises-based async API

• Math API with Vectors, Rays, Lines, Projections, and more

13

excalibur Documentation, Release

• and much more!

14 Chapter 3. Features

CHAPTER 4

Installation

Follow our Installing Excalibur.js guide.

Getting Started

Follow our Getting Started guide.

API Documentation

The master branch API documentation is always available and up-to-date on our Edge documentation site.

Otherwise, see the TOC on the left to find the stable API documentation.

Support

Ask us anything in the Excalibur.js mailing list. If you find a bug, report it on the GitHub issues page.

Samples

Compiled examples can be found in the Excalibur Samples.

Contributing

Please view the Contributing guidelines. If you spot a bug, have a question, or want to contribute, please open aGitHub issue!

15

excalibur Documentation, Release

License

Excalibur is open source and operates under the 2 clause BSD license:

Copyright (c) 2014, Erik Onarheim All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted providedthat the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and thefollowing disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions andthe following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THEIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PUR-POSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBU-TORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, ORCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUB-STITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUP-TION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANYWAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OFSUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of the authors andshould not be interpreted as representing official policies, either expressed or implied, of the FreeBSDProject.

16 Chapter 4. Installation

CHAPTER 5

Indices and tables

• genindex

• modindex

• search

17