Installation

The most easy way to get started with KAPLAY is to use the CLI tool, which will generate a project for you:

$ npx create-kaplay mygame
$ cd mygame
$ npm run dev

This will create your game in the mygame folder, and start a development server for you to preview your game. If you edit src/main.js and refresh the page, you will see your changes.

To see all options, run:

$ create-kaplay --help

Using a CDN

If you prefer to use KAPLAY without any bundlers, you can use a CDN to include it directly in your HTML file, or import it with ECMAScript modules.

<script type="module">
    // import kaplay
    import kaplay from "https://unpkg.com/kaplay@3001/dist/kaplay.mjs";
    // start kaplay
    kaplay();
</script>

You can also just include it with a <script> tag.

<script src="https://unpkg.com/kaplay@3001/dist/kaplay.js"></script>

<script>
    kaplay();
</script>

Setup your own Node.js environment

With Node.js and npm it’s easier have some other packages and use version control, also it’s easier to get typescript autocomplete support, but it requires a bit more setup. (This is the way of create-kaplay)

$ npm install kaplay

You’ll need to use a bundler to use Kaboom with NPM. There’s a lot of options like:

esbuild,
webpack,
parcel,
vitejs,

This is a short example of how to use Kaboom with “esbuild”.

Once you have esbuild installed, and you have this in a .js or .ts file:

import kaplay from "kaplay";

kaplay();

just run

$ esbuild game.js --bundle > build.js

and it’ll find the KAPLAY package and include it in the built build.js, include build.js in your HTML and you’re good to go. Feel free to automate this process.

Loading Assets

You might have encountered errors when trying to loadSprite() from local file system, that is because browser won’t allow loading local files with JavaScript. To get around that you’ll need to use a static file that serves the files through HTTP. There’re a lot of programs that helps you to do that.

$ python3 -m http.server if you have python3 installed
$ python -m SimpleHTTPServer if you have python2 installed
$ serve if you have serve installed
$ caddy file-server if you have caddy installed
$ static-here if you have static-here installed
$ ruby -run -ehttpd . -p8000 if you have ruby installed
$ php -S localhost:8000 if you have php installed

Let’s say you have a folder structure like this:

.
├── sprites
│   ├── froggy.png
│   └── cloud.png
├── sounds
│   └── horse.mp3
└── index.html

and you have the static file server running on port 8000, just go to http://localhost:8000/index.html, and you should be able to load stuff from relative paths like

loadSprite("froggy", "sprites/froggy.png");
loadSound("horse", "sounds/horse.mp3");

To learn more check out this MDN doc.

Why KAPLAY?

Basic Concepts