Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

kaplay

kaplayjs5kMIT3001.0.19TypeScript support: included

KAPLAY is a JavaScript & TypeScript game library that helps you make games fast and fun! (formerly known as Kaboom.js)

game development, javascript, typescript, game engine, 2d games, physics engine, webgl, canvas, game library, kaplay, kaboom, kaboomjs, kaboom.js

readme

🎮 KAPLAY.js — A JavaScript & TypeScript Game Library

KAPLAY is the fun-first, 2D game library for JavaScript and TypeScript. It’s made to feel like a game while you're making games. Simple. Fast. Powerful.

✨ Whether you’re a beginner or an experienced dev, KAPLAY comes with its own web-based editor — the KAPLAYGROUND — so you can try code instantly, and learn with more than 90 examples!

🎲 Quick Overview

// Start a game
kaplay({
    background: "#6d80fa",
});

// Load an image
loadSprite("bean", "https://play.kaplayjs.com/bean.png");

// Add a sprite to the scene
add([
    sprite("bean"), // it renders as a sprite
]);

Game objects are composed from simple, powerful components:

// Add a Game Obj to the scene from a list of component
const player = add([
    rect(40, 40), // it renders as a rectangle
    pos(100, 200), // it has a position (coordinates)
    area(), // it has a collider
    body(), // it is a physical body which will respond to physics
    health(8), // it has 8 health points
    // Give it tags for easier group behaviors
    "friendly",
    // Give plain objects fields for associated data
    {
        dir: vec2(-1, 0),
        dead: false,
        speed: 240,
    },
]);

Blocky imperative syntax for describing behaviors

// .onCollide() comes from "area" component
player.onCollide("enemy", () => {
    // .hurt() comes from "health" component
    player.hurt(1);
});

// check fall death
player.onUpdate(() => {
    if (player.pos.y >= height()) {
        destroy(player);
    }
});

// All objects with tag "enemy" will move to the left
onUpdate("enemy", (enemy) => {
    enemy.move(-400, 0);
});

// move up 100 pixels per second every frame when "w" key is held down
onKeyDown("w", () => {
    player.move(0, 100);
});

🖥️ Installation

🚀 Using create-kaplay

The fastest way to get started:

npx create-kaplay my-game

Then open http://localhost:5173 and edit src/game.js.

📦 Install with package manager

npm install kaplay
yarn add kaplay
pnpm add kaplay
bun add kaplay

You will need a bundler like Vite or ESBuild to use KAPLAY in your project. Learn how to setup ESbuild here.

🌐 Use in Browser

Include via CDN:

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

📜 TypeScript Global Types

If you're using TypeScript, you used create-kaplay or installed with a package manager and you want global types, you can load them using the following directive:

import "kaplay/global";

vec2(10, 10); // typed!

But it's recommended to use tsconfig.json to include the types:

{
  "compilerOptions": {
    "types": ["./node_modules/kaplay/dist/declaration/global.d.ts"]
  }
}

If you are publishing a game (and not testing/learning) maybe you don't want to use globals, see why.

You can also use all KAPLAY source types importing them:

import type { TextCompOpt } from "kaplay"
import type * as KA from "kaplay" // if you prefer a namespace-like import

interface MyTextCompOpt extends KA.TextCompOpt {
  fallback: string;
}

📚 Resources

📖 Docs

📺 Tutorials

💬 Community

🎮 Games

Collections of games made with KAPLAY, selected by KAPLAY:

🙌 Credits

KAPLAY is an open-source project, maintained by the KAPLAY Team and core contributors and with the support of many other amazing contributors.

🏆 Recognitions

changelog