Installation Guide

Getting Excalibur

There are several ways you can get Excalibur: as standalone packages from npm or nuget, as raw script files you can download, or by using one of our pre-made template repos.

Excalibur is a client-side library and cannot be used in a server-side Node.js, however it can be downloaded with npm.

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
        /build
            /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.

If you used npm to install Excalibur, you can use the node_modules/excalibur/build/dist/excalibur.min.js path above in the HTML. We recommend parcel for quick projects or webpack for more sophisticated projects. Read more about builds and bundlers

Script Reference or Download

Best for quick prototypes or small projects

If you are using Excalibur in a script tag, unpkg provides a quick way to include published npm packages as scripts.

It is recommended you pin your version of excalibur to specific version like [email protected], however you can get the latest https://unpkg.com/[email protected]

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <script src="https://unpkg.com/[email protected]"></script>
    <script src="./my-game.js"></script>
  </body>
</html>

You can also download the compiled script from Excalibur repository.

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <script src="excalibur.min.js"></script>
    <script src="./my-game.js"></script>
  </body>
</html>

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.

Unstable Builds

If you want to live on the edge and get the latest unreleased and possibly unstable builds, you can download -alpha npm packages.

The latest documetnation for the Unstable Builds.

Example Project Templates & Samples

The excaliburjs organization on GitHub has several example projects:

GitHub Templates

GitHub Samples

Older GitHub Templates

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

TypeScript

We recommend using TypeScript for the best experience using Excalibur, but it will work just as well using plain JavaScript.

No Bundler or Loader via Triple-Slash Reference

If you are using a standalone script for Excalibur, you may want to use triple-slash references. It requires no extra module system or loaders!

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

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

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