Installation Guide

Getting Excalibur

There are several ways you can get Excalibur: as standalone packages, using a script generator, or as raw script files you can download.

npm Package

Best for JavaScript/TypeScript projects

If you’re using Node.js or intend to use Excalibur in a primarily JavaScript project, you can install it via npm.

With Node installed, run the following on the command-line:

npm install excalibur

This will add excalibur to your package.json as a project dependency and will create a folder structure like:

/node_modules
    /excalibur
        /dist
            excalibur.js
            excalibur.min.js
            excalibur.d.ts
            ...other files

See below for how to reference these files in your project after Excalibur is installed.

View the excalibur package on npm.

Nuget Package

Best for .NET projects

If you intend to use Excalibur in a primarily .NET-based project (like Xamarin, Windows 10, etc.), you can use Nuget.

With the .NET SDK installed, run the following on the command-line:

Install-Package Excalibur

Nuget will automatically place the Excalibur files in the Content/Scripts folder of your project:

/Content
    /Scripts
        excalibur.js
        excalibur.min.js
        excalibur.d.ts
        ...other files

See below for how to reference these files in your project after Excalibur is installed.

View the Excalibur package on Nuget.

Yeoman Generator

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

# Install Yeoman globally
npm install -g yo
# Install the Excalibur generator globally
npm install -g @excaliburjs/generator-excalibur
# Create the folder you want your game to be in
mkdir my-game
# Go into the folder
cd my-game
# Run the excalibur generator
yo @excaliburjs/excalibur

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

Raw Script Files via CDN or Download

Excalibur is available via unpkg CDN, with the latest version at the following URL:

https://unpkg.com/[email protected]/dist/excalibur.js

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

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

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 Builds.

Example Project Templates

The excaliburjs organization on GitHub has several example projects:

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>

If you used npm to install Excalibur, you can use the node_modules/excalibur/dist/excalibur.min.js path above in the HTML. We recommend webpack for more sophisticated projects.

Referencing Excalibur via Triple-Slash Reference

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

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

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

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"]
  }
}

Module Loaders and Bundlers

Excalibur is built using webpack and ES2015 modules. The standalone files excalibur.js or excalibur.min.js support bundlers, module loaders, and browsers. In the browser, Excalibur is attached to the window.ex global namespace. These are the recommended files to use for production deployments.

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 namespace
import * as ex from 'excalibur'

In a module loader system, such as Webpack, it will automatically bundle Excalibur. See the webpack example repo

To support tree-shaking, you should use named imports:

import { Actor } from 'excalibur'

Excalibur doesn't do the best optimization to support tree-shaking--likely you'll end up importing everything.