KAPLAY.js — A JavaScript & TypeScript Game Library

KAPLAY is the fun-first 2D game library designed for JavaScript and TypeScript. It’s built to feel like you’re making a game while you’re actually building one. The aim is simple: make development fast, expressive, and approachable without sacrificing power. Whether you’re just starting out or you’re a seasoned developer, KAPLAY offers a streamlined experience that keeps you in the flow.

What makes KAPLAY special is not just its features, but its philosophy. It’s crafted to be fast and responsive, with a focus on giving you something tangible to play as you code. To accelerate learning and experimentation, KAPLAY ships with its own web-based editor — the KAPLAYGROUND — so you can try code instantly and learn from more than 90 examples. This hands-on approach helps you iterate quickly, test ideas on the fly, and see immediate results in a friendly, game-like environment.

---

Quick Overview: A Glimpse at the Basics

KAPLAY embraces a clear, expressive syntax that makes game development feel natural. Here’s a quick snapshot to illustrate how you might kick off a game, load assets, and add a sprite to the scene:

// 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
]);

The core idea is to compose game objects from simple, powerful components. You don’t have to write sprawling boilerplate. Instead, you assemble behavior and appearance by combining modular pieces. For example, you can construct a player object from components that handle geometry, position, physics, health, and data fields:

// Add a Game Obj to the scene from a list of components
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 with physics
  health(8),               // it has 8 health points
  // Additional data on the object:
  // Give it tags for easier group behaviors
  "friendly",
  // Fields for associated data
  { dir: vec2(-1, 0), dead: false, speed: 240 },
]);

This block of code exemplifies the “blocky imperative” style that makes KAPLAY approachable. Rather than chasing a long inheritance chain or wrestling with abstractions, you wire up capabilities by list-building components. The result is a readable, maintainable description of what the entity does and how it behaves.

Blocky imperative syntax lets you describe nuanced behavior directly in code blocks:

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

// 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);
});

This style makes behaviors feel tangible and immediate. You can read the flow almost as a narrative: when the player collides with enemies, lose health; if the player falls below the floor, destroy it; all enemies drift left; pressing a key moves the player upward. It’s direct, expressive, and conducive to experimentation.

---

Getting Started: Installation and Setup

KAPLAY caters to a range of workflows, from quick experiments to full project pipelines. You have a couple of primary pathways to begin.

Using create-kaplay — The Fast Lane

If you want to be up and running in minutes, the fastest route is to scaffold a new project with create-kaplay:

npx create-kaplay my-game

After the scaffold completes, open the project in your browser:

• Navigate to http://localhost:5173
• Edit the file src/game.js to start experimenting with your game ideas

This approach gives you a ready-made development environment with sensible defaults and a working project structure so you can focus on gameplay and logic from day one.

Install with a Package Manager

If you prefer to integrate KAPLAY into an existing project or you’re building a custom toolchain, you can install the library from npm or a package manager:

• npm:

  npm install kaplay

• yarn:

  yarn add kaplay

• pnpm:

  pnpm add kaplay

• bun:

  bun add kaplay

Note: To use KAPLAY effectively, you’ll need a bundler such as Vite or ESBuild. These tooling options help you compile, optimize, and serve your project efficiently. If you’re setting up a custom environment, consult the ESBuild setup guide referenced by KAPLAY’s docs.

Use in Browser — CDN Option

For quick experiments or learning sessions without a local build, KAPLAY can be included in a web page via a CDN. This lets you try snippets directly in a browser. The CDN route is described in the documentation and is ideal for quick demos or sharing small examples with others.

---

TypeScript Support: Global Types and Safe Typing

TypeScript users enjoy strong typing and editor intelligence, which helps catch mistakes early and speeds up development. KAPLAY ships with global types and a path to more explicit type usage, making it comfortable to work with in both learning and production contexts.

Global Types (Convenient for Quick Prototyping)

If you’re using the create-kaplay setup or you installed KAPLAY via a package manager and you want global types available globally, you can load them with:

import "kaplay/global";
vec2(10, 10); // typed!

This approach lets you write vector-like code directly in your TypeScript files without importing types explicitly in every module.

Configuring TypeScript for Global Types

If you’d rather rely on TypeScript’s config-based approach, you can include the types in your tsconfig.json, ensuring that global types are available project-wide:

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

A Note on Global Namespace

There’s a helpful caveat to keep in mind. If you are publishing a game (and not just testing or learning), you may prefer to avoid relying on global namespaces. The KAPLAY documentation discusses this consideration and provides guidance on optimization and scope control. If you eventually want stronger module boundaries, you can import KAPLAY types directly instead of using global types.

Importing KAPLAY Types Directly

For those who prefer module-like usage over globals, KAPLAY also supports importing types directly:

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

With this approach, you can extend or adapt KAPLAY’s typed interfaces without polluting the global namespace, maintaining a clean module boundary while retaining full TypeScript benefits.

---

Resources to Learn, Build, and Connect

KAPLAY’s ecosystem is designed to be approachable and well-documented. The resources are organized to help you learn, experiment, and connect with the community.

Documentation

• KAPLAY Official Docs: https://kaplayjs.com/docs/
• KAPLAY Playground: https://play.kaplayjs.com

The official docs provide comprehensive guidance on API usage, concepts, and best practices. The playground is a rich, interactive space to try code, view examples, and understand how the library behaves in real time.

Tutorials

• KAPLAY Library Crash Course by JSLegend: A video introduction that covers core concepts and practical workflows.
• Learn JavaScript basics and KAPLAY to make games quickly: A resource for beginners that blends JavaScript fundamentals with hands-on KAPLAY examples.

Community and Support

• Discord Server: A place to chat with developers and other users
• GitHub Discussions: A space for questions, ideas, and troubleshooting
• Twitter/X: @kaplayjs for updates and community highlights
• BlueSky and Mastodon: Social channels for broader visibility and conversations

These channels provide a spectrum of engagement options—from quick questions to in-depth discussions about optimization, features, and future directions.

---

Games and Collections: Showcasing What You Can Build

KAPLAY has sparked a growing collection of games created with the library. These projects showcase what’s possible and offer inspiration for your own builds.

• Itch.io Collection: A curated set of games built with KAPLAY
• Newgrounds Playlist: A growing list of Kaplay-powered games

Exploring these collections gives you real-world examples of how to structure games, design levels, handle input, and implement gameplay loops with KAPLAY’s component-based approach.

---

Credits and Recognitions: A Community-Powered Project

KAPLAY is an open-source project maintained by the KAPLAY Team and core contributors, with support from many other amazing contributors. The project is a collaborative effort that blends thoughtful design with practical engineering to deliver a friendly yet capable game library.

Acknowledgments

• MulfoK’s color palette (mulfok32) inspires many sprite colors and art decisions used in KAPLAY examples.
• Pixabay provided the Burp sound used by the burp() function.
• Kenney’s assets underpin many example projects and demonstrations.
• Impact Sound Pack from Kenney (and other assets like the 1-Bit Platformer Pack) contributed to the audio landscape of sample games.
• APL386 font by abrudz and kitchen sink font by Polyducks contribute to the distinctive typography seen in examples and tutorials.
• The Dungeon Tileset II by 0x72 and other sprite assets from various contributors add to the library’s visual diversity.

This collaborative ecosystem ensures KAPLAY is not only a toolset but a community-driven platform for experimentation and learning.

---

Why KAPLAY: A Quick Recap

• Fun-first, fast, and powerful: KAPLAY emphasizes an enjoyable development experience without compromising capabilities.
• 2D game library for JavaScript and TypeScript: It embraces modern language features and a pragmatic approach to game design.
• Component-based architecture: Build games by composing simple, reusable components (rect, pos, area, body, health, tags, etc.) to create rich game objects.
• Imperative, readable workflows: Blocky, straightforward syntax makes behavior easy to follow and tweak, enabling quick iteration.
• Web-based editor and examples: KAPLAYGROUND accelerates learning with a visual, interactive coding environment and a large set of examples.
• Flexible installation: Use create-kaplay for rapid startup, or install via npm/yarn/pnpm/bun and integrate into existing projects.
• TypeScript-friendly: Global types or modular type imports provide flexible typing strategies, depending on your project needs.
• Rich resources and community: Documentation, tutorials, and community channels help you learn, share, and grow with other developers.

---

Getting the Most from Your KAPLAY Experience

• Start small: Use the quick overview examples to scaffold a basic scene, then incrementally add components to understand their behavior.
• Experiment with the editor: The KAPLAYGROUND environment is designed for hands-on learning. Try different components, tweak properties, and observe how changes shape gameplay.
• Embrace the community: Don’t hesitate to ask questions or share your progress in Discord, GitHub Discussions, or your preferred social channels. Learning from others speeds up your development and deepens understanding.
• Consider architecture early: If you’re building a larger game, think about how you’ll structure objects with tags and components, how you’ll handle updates, collisions, and physics, and how you’ll organize assets and code with TypeScript.

---

Final Thoughts

KAPLAY.js represents a thoughtful blend of accessibility and capability. It invites you to start building games quickly while giving you a robust toolkit to scale your ideas as they grow. The emphasis on "feel like a game while you’re making games" translates into a development experience that’s both enjoyable and productive. The combination of a friendly learning curve, a modular component system, a web-based editor, and an active community makes KAPLAY a compelling choice for both beginners looking to learn game development and veterans seeking a nimble, expressive library for 2D projects.

If you’re curious to dive in, the next steps are straightforward: try the create-kaplay generator for a quick start, or install the library in your preferred project workflow, explore the official docs and playground, and begin building your next interactive experience. The example snippets above are just a starting point; with KAPLAY, the playground becomes your workshop, and your ideas become tangible, playable prototypes in record time.

Remember to consult the official docs for the latest guidance, participate in the community for support and feedback, and celebrate your progress as you turn concepts into interactive, engaging games. The future of your 2D game ideas is just a few components away.

[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/kaplay-js-game-library?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)