Skip to main content

Installation

First time here?

If this is your first time using Excalibur, we recommend you start with our Hello Excalibur tutorial where you can learn Excalibur in the browser.

Start From a Template​

If you want to get up and running quickly with a familiar toolchain, we have several templates and samples available on GitHub. These examples allow you to simply clone and start building your game! They are also a great way to learn how to integrate Excalibur into your existing toolchain.

Templates​

Samples​

Older Templates​

Starting from Scratch​

There are several ways you can start from scratch with Excalibur:

note

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​

note

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:

bash
npm install excalibur
bash
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
/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.

tip

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​

note

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 excalibur@0.24.5, however you can get the latest https://unpkg.com/excalibur@latest

html
<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <script src="https://unpkg.com/excalibur@0.24.5"></script>
    <script src="./my-game.js"></script>
  </body>
</html>
html
<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <script src="https://unpkg.com/excalibur@0.24.5"></script>
    <script src="./my-game.js"></script>
  </body>
</html>

You can also download the compiled script from Excalibur repository.

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

Nuget Package​

note

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:

bash
Install-Package Excalibur
bash
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
/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.

Using a CDN​

If you want to use Excalibur in a Deno environment, use a content delivery network like esm.sh or skypack.dev. They transform our NPM package into an ES Module. That may sound complicated, but it's really just one line of code:

typescript
// index.ts
import { Engine } from 'https://esm.sh/excalibur';
// and Tada!
const game = new Engine();
game.start();
typescript
// index.ts
import { Engine } from 'https://esm.sh/excalibur';
// and Tada!
const game = new Engine();
game.start();
tip

To see the full instructions on setting up Excalibur with Deno, check out our Deno guide.

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 documentation for the Unstable Builds.

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!

js
/// <reference path="node_modules/excalibur/build/dist/excalibur.d.ts" />
const game = new ex.Engine({ ... });
game.start();
js
/// <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.

json
{
  "compilerOptions": {
    "target": "es5",
    "outFile": "game.js",
    "types": ["excalibur"]
  }
}
json
{
  "compilerOptions": {
    "target": "es5",
    "outFile": "game.js",
    "types": ["excalibur"]
  }
}