KAPLAY

https://kaplayjs.com/docs
Admin
KAPLAY is a JavaScript game development library that provides a component-based architecture for...
Tokens:144,981
Snippets:1,419
Trust Score:7.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install and run http-server

Source: https://kaplayjs.com/docs/guides/install

Installs the global http-server utility and starts it to serve static files.

```bash
npm install --global http-server
```

```bash
http-server # Serve your files!
```

--------------------------------

### Repository Setup Commands

Source: https://kaplayjs.com/docs/guides/contributor-guide-on-guides

Commands to clone the repository, initialize submodules, and start the development server.

```bash
git clone https://github.com/kaplayjs/kaplay-site.git
git submodule init
git submodule update
pnpm ci
pnpm dev
```

--------------------------------

### Start KAPLAY Development Server

Source: https://kaplayjs.com/docs/guides/how-to-make-a-multiplayer-game-with-colyseus-and-kaplay

Commands to install dependencies and launch the KAPLAY client server.

```bash
cd client
npm install
npm start
```

--------------------------------

### Start Colyseus Development Server

Source: https://kaplayjs.com/docs/guides/how-to-make-a-multiplayer-game-with-colyseus-and-kaplay

Commands to install dependencies and launch the Colyseus server.

```bash
cd server
npm install
npm start
```

--------------------------------

### Custom Node.js installation

Source: https://kaplayjs.com/docs/guides/install

Installs KAPLAY and esbuild for manual bundling.

```bash
npm install kaplay
```

```bash
npm install esbuild
```

--------------------------------

### Start Development Server for Network Access

Source: https://kaplayjs.com/docs/guides/how-to-make-a-multiplayer-game-with-colyseus-and-kaplay

Commands to start the client development server with host exposure enabled for local network testing.

```bash
cd client
# Linux
npm run start -- --host
# Windows
npm run start -- -- --host
```

--------------------------------

### Start development server

Source: https://kaplayjs.com/docs/guides/install

Navigates to the project directory and launches the local development server.

```bash
cd myGame && npm run dev
```

--------------------------------

### onTouchStart

Source: https://kaplayjs.com/docs/api/reference

Registers an event that runs when a touch starts.

```APIDOC
## onTouchStart(action: (pos: Vec2, t: Touch) => void): KEventController

### Description
Register an event that runs when a touch starts.

### Parameters
- **action** (function) - Required - The function to run when the event is triggered.

### Returns
- **KEventController** - The event controller.
```

--------------------------------

### Clone the starter repository

Source: https://kaplayjs.com/docs/guides/how-to-make-a-multiplayer-game-with-colyseus-and-kaplay

Use this command to clone the official KAPLAY and Colyseus quickstart repository.

```bash
git clone https://github.com/colyseus/kaplay.git kaplay-colyseus
```

--------------------------------

### Install KAPLAY package

Source: https://kaplayjs.com/docs/guides/migration-kaplay

Use npm to install the KAPLAY package in your project.

```bash
npm install kaplay@3001
```

--------------------------------

### Install Experimental KAPLAY

Source: https://kaplayjs.com/docs/guides/ai

Command to install the latest development version of KAPLAY from GitHub.

```bash
npm i github:kaplayjs/kaplay
```

--------------------------------

### play(time?: number): void

Source: https://kaplayjs.com/docs/api/AudioPlay

Starts playing the audio. An optional time parameter can be provided to start playback from a specific point.

```APIDOC
## play(time?: number): void

### Description
Starts playing the audio. An optional time parameter can be provided to start playback from a specific point.

### Parameters
- **time** (number) - Optional - The time in seconds to start playback from.
```

--------------------------------

### run

Source: https://kaplayjs.com/docs/api/reference

Starts the game loop with provided update functions.

```APIDOC
## run

### Description
Starts the game loop, executing the provided fixedUpdate and update functions.

### Signature
run(fixedUpdate: () => void, update: (processInput: () => void, resetInput: () => void) => void) => void
```

--------------------------------

### Initialize KAPLAY context

Source: https://kaplayjs.com/docs/api/kaplay

Demonstrates starting the engine with default settings, custom options, and using a non-global context handle.

```javascript
// Start KAPLAY with default options (will create a fullscreen canvas under <body>)
kaplay()

// Init with some options
kaplay({
    width: 320,
    height: 240,
    font: "sans-serif",
    canvas: document.querySelector("#mycanvas"),
    background: [ 0, 0, 255, ],
})

// All KAPLAY functions are imported to global after calling kaplay()
add()
onUpdate()
onKeyPress()
vec2()

// If you want to prevent KAPLAY from importing all functions to global and use a context handle for all KAPLAY functions
const k = kaplay({ global: false })

k.add(...)
k.onUpdate(...)
k.onKeyPress(...)
k.vec2(...)
```

--------------------------------

### onTouchStart(action: (pos: Vec2, t: Touch) => void): KEventController

Source: https://kaplayjs.com/docs/api/ctx/onTouchStart

Registers an event that runs when a touch starts.

```APIDOC
## onTouchStart

### Description
Registers an event listener that executes a provided callback function when a touch interaction starts on the device.

### Signature
`onTouchStart(action: (pos: Vec2, t: Touch) => void): KEventController`

### Parameters
- **action** (function) - Required - The function to run when the event is triggered. It receives the position (Vec2) and the touch object (Touch) as arguments.

### Returns
- **KEventController** - The event controller used to manage or cancel the event listener.

### Since
v2000.1
```

--------------------------------

### Rendered Code component example

Source: https://kaplayjs.com/docs/guides/contributor-guide-on-guides

Example of how the Code component appears when rendered.

```javascript
// Code to be rendered
```

--------------------------------

### Loading sound assets

Source: https://kaplayjs.com/docs/api/ctx/loadSound

Examples of loading different audio file formats into the asset manager.

```javascript
loadSound("shoot", "/sounds/horse.ogg");
loadSound("shoot", "/sounds/squeeze.mp3");
loadSound("shoot", "/sounds/shoot.wav");
```

--------------------------------

### Guide Frontmatter Template

Source: https://kaplayjs.com/docs/guides/contributor-guide-on-guides

The standard YAML frontmatter required for all guide MDX files.

```yaml
---
title: Creating Guides # The title, it appears in the sidebar
description: You shouldn't see this # Description for metadata
version: "4000" # Don't use it unless the guide is only for v4000
url: contributor-guide-on-guides # The url
order: "misc-4" # The order string, just follow the others in the same category
hidden: true # Hide it
noads: true # Disable ads (used in Contributors pages)
---
```

--------------------------------

### Initialize and Run a Full KAPLAY Game

Source: https://kaplayjs.com/docs/guides/creating_your_first_game

This example covers the entire lifecycle of a basic game, from initialization and asset loading to scene definitions and input handling.

```javascript
import kaplay from "kaplay";
import "kaplay/global"; // comment if you want to use the k. prefix

const FLOOR_HEIGHT = 48;
const JUMP_FORCE = 800;
const SPEED = 480;

// initialize context
kaplay();

// load assets
loadSprite("bean", "sprites/bean.png");

scene("game", () => {
    // define gravity
    setGravity(1600);

    // add a game object to screen
    const player = add([
        // list of components
        sprite("bean"),
        pos(80, 40),
        area(),
        body(),
    ]);

    // floor
    add([
        rect(width(), FLOOR_HEIGHT),
        outline(4),
        pos(0, height()),
        anchor("botleft"),
        area(),
        body({ isStatic: true }),
        color(127, 200, 255),
    ]);

    function jump() {
        if (player.isGrounded()) {
            player.jump(JUMP_FORCE);
        }
    }

    // jump when user press space
    onKeyPress("space", jump);
    onMousePress(jump);

    function spawnTree() {
        // add tree obj
        add([
            rect(48, rand(32, 96)),
            area(),
            body({isStatic: true}),
            outline(4),
            pos(width(), height() - FLOOR_HEIGHT),
            anchor("botleft"),
            color(255, 180, 255),
            move(LEFT, SPEED),
            "tree",
        ]);
        // wait a random amount of time to spawn next tree
        wait(rand(0.5, 1.5), spawnTree);
    }

    // start spawning trees
    spawnTree();

    // lose if player collides with any game obj with tag "tree"
    player.onCollide("tree", () => {
        // go to "lose" scene and pass the score
        go("lose", score);
        burp();
        addKaboom(player.pos);
    });

    // keep track of score
    let score = 0;

    const scoreLabel = add([text(score), pos(24, 24)]);

    // increment score every frame
    onUpdate(() => {
        score++;
        scoreLabel.text = score;
    });
});

scene("lose", (score) => {
    add([text("Game Over"), pos(center()), anchor("center")]);

    // display score
    add([
        text(score),
        pos(width() / 2, height() / 2 + 80),
        scale(2),
        anchor("center"),
    ]);

    // go back to game when space is pressed
    onKeyPress("space", () => go("game"));
    onMousePress(() => go("game"));
});

go("game");
```

--------------------------------

### Custom fragment shader examples

Source: https://kaplayjs.com/docs/guides/shaders

Examples of modifying pixel colors using texture data and base colors.

```glsl
vec4 frag(vec2 pos, vec2 uv, vec4 color, sampler2D tex) {
  return vec4(color.rgb, texture2D(tex, uv).a);
}
```

```glsl
vec4 frag(vec2 pos, vec2 uv, vec4 color, sampler2D tex) {
  vec4 tcolor = texture2D(tex, uv);
  float gray = dot(tcolor.rgb, vec3(0.299, 0.587, 0.114));
  return vec4(color.rgb * gray, tcolor.a);
}
```

--------------------------------

### Load a fragment shader from a URL

Source: https://kaplayjs.com/docs/api/ctx/loadShaderURL

Example showing how to load only a fragment shader by passing null for the vertex shader parameter.

```javascript
// load only a fragment shader from URL
loadShaderURL("outline", null, "/shaders/outline.glsl")
```

--------------------------------

### Install KAPLAY Crew package

Source: https://kaplayjs.com/docs/guides/crew

Use npm to install the required package for the KAPLAY Crew plugin.

```bash
npm i @kaplayjs/crew
```

--------------------------------

### Using the text component

Source: https://kaplayjs.com/docs/api/ctx/text

Examples showing how to initialize a text component for a score counter and how to apply styling options like size and wrapping.

```javascript
// a simple score counter
const score = add([
    text("Score: 0"),
    pos(24, 24),
    { value: 0 },
])

player.onCollide("coin", () => {
    score.value += 1
    score.text = "Score:" + score.value
})

// with options
add([
    pos(24, 24),
    text("ohhi", {
        size: 48, // 48 pixels tall
        width: 320, // it'll wrap to next line when width exceeds this value
        font: "sans-serif", // specify any font you loaded or browser built-in
    }),
])
```

--------------------------------

### Initialize KAPLAY in JS/TS

Source: https://kaplayjs.com/docs/guides/install

Basic import and initialization for a custom Node.js setup.

```javascript
import kaplay from "kaplay";

kaplay();
```

--------------------------------

### load

Source: https://kaplayjs.com/docs/api/reference

Adds a new loader to wait for before starting the game.

```APIDOC
## load(l)

### Description
Add a new loader to wait for before starting the game.

### Parameters
- **l** (Promise<T>) - Required - The loader to wait for.

### Returns
- **Asset<T>** - The asset data.
```

--------------------------------

### record

Source: https://kaplayjs.com/docs/api/reference

Starts recording the canvas into a video.

```APIDOC
## record(frameRate?: number): Recording

### Description
Start recording the canvas into a video. If framerate is not specified, a new frame will be captured each time the canvas changes.

### Returns
- **Recording** - A control handle.
```

--------------------------------

### Event Listener Patterns

Source: https://kaplayjs.com/docs/guides/events

Examples of different ways to register listeners for global, object, and custom events.

```javascript
// a global event
onUpdate(() => {});
// an object event
obj.onUpdate(() => {});
// a custom event
obj.on("hi", () => {});
```

--------------------------------

### Loading a Bitmap Font

Source: https://kaplayjs.com/docs/api/ctx/loadBitmapFont

Examples showing how to load a standard bitmap font and one with a custom character set.

```javascript
// load a bitmap font called "04b03", with bitmap "fonts/04b03.png"
// each character on bitmap has a size of (6, 8), and contains default ASCII_CHARS
loadBitmapFont("04b03", "fonts/04b03.png", 6, 8);

// load a font with custom characters
loadBitmapFont("myfont", "myfont.png", 6, 8, { chars: "☺☻♥♦♣♠" });
```

--------------------------------

### Defining and using layers

Source: https://kaplayjs.com/docs/api/ctx/layers

Example showing how to define layers and assign objects to them. Objects without a specified layer are added to the default layer.

```javascript
setLayers(["bg", "obj", "ui"], "obj")

// no layer specified, will be added to "obj"
add([
     sprite("bean"),
]);

// add to "bg" layer
add([
    sprite("bg"),
    layer("bg"),
]);
```

--------------------------------

### Registering Events with on

Source: https://kaplayjs.com/docs/api/ctx/on

Examples showing how to use on to handle custom events and object interactions, including triggering events via game objects.

```javascript
// a custom event defined by body() comp
// every time an obj with tag "bomb" hits the floor, destroy it and addKaboom()
on("ground", "bomb", (bomb) => {
    destroy(bomb)
    addKaboom(bomb.pos)
})

// a custom event can be defined manually
// by passing an event name, a tag, and a callback function
// if you want any tag, use a tag of "*"
on("talk", "npc", (npc, message) => {
    npc.add([
        text(message),
        pos(0, -50),
        lifespan(2),
        opacity(),
    ])
});

onKeyPress("space", () => {
    // the trigger method on game objs can be used to trigger a custom event
    npc.trigger("talk", "Hello, KAPLAY!");
});
```

--------------------------------

### onAnimStart(action: (anim: string) => void): KEventController

Source: https://kaplayjs.com/docs/api/SpriteComp

Registers a callback for when an animation starts.

```APIDOC
## onAnimStart(action: (anim: string) => void): KEventController

### Description
Registers an event listener that triggers when an animation begins playing.

### Parameters
- **action** (function) - Required - The callback function to execute.
```

--------------------------------

### Generate random integers with randi

Source: https://kaplayjs.com/docs/api/ctx/randi

Examples showing how to use randi with no arguments, a single upper bound, or a range.

```javascript
randi(); // returns either 0 or 1
randi(10); // returns a random integer between 0 and 9
randi(10, 20); // returns a random integer between 10 and 19
```

--------------------------------

### Using the move component

Source: https://kaplayjs.com/docs/api/ctx/move

This example demonstrates adding the move component to a projectile object, requiring the pos component to function.

```javascript
// enemy throwing feces at player
const projectile = add([
    sprite("feces"),
    pos(enemy.pos),
    area(),
    move(player.pos.angle(enemy.pos), 1200),
    offscreen({ destroy: true }),
])
```

--------------------------------

### Identify Network Address

Source: https://kaplayjs.com/docs/guides/how-to-make-a-multiplayer-game-with-colyseus-and-kaplay

Example output showing the network address to access the game from other devices.

```text
-> Network: http://192.168.1.2:5173/
```

--------------------------------

### onHover(action)

Source: https://kaplayjs.com/docs/api/AreaComp

Registers an event listener for hover start.

```APIDOC
## onHover(action)

### Description
Register an event that runs once when the object is hovered.

### Parameters
- **action** (Function) - The callback function.
```

--------------------------------

### Example Asset Path

Source: https://kaplayjs.com/docs/guides/publishing

A standard asset loading call using an absolute path, which may require adjustment for web hosting.

```javascript
loadSprite("bean", "/sprites/bean.png");
```

--------------------------------

### Attach a particle emitter to a Game Object

Source: https://kaplayjs.com/docs/api/ctx/particles

This example demonstrates how to initialize a particle emitter using the particles component and trigger emission within an onUpdate loop.

```javascript
// beansplosion

// create the emitter
const emitter = add([
    pos(center()),
    particles({
        max: 100,
        speed: [75, 100],
        lifeTime: [0.75,1.0],
        angle: [0, 360],
        opacities: [1.0, 0.0],
        texture: getSprite("bean").tex,   // texture of a sprite
        quads: getSprite("bean").frames,  // frames of a sprite
    }, {
        direction: 0,
        spread: 360,
    }),
])

onUpdate(() => {
    emitter.emit(1)
})
```

--------------------------------

### Initialize a KAPLAY Game

Source: https://kaplayjs.com/docs/guides/starting

Use the kaplay() function to start the game engine. It can be called with default settings or a configuration object to customize the canvas, dimensions, and background.

```javascript
// Start with default options
kaplay();

// Start with options
kaplay({
    width: 200,
    height: 200,
    background: "#d46eb3",
    scale: 2,
    canvas: document.getElementById("canvas"),
});
```

--------------------------------

### Apply a post-processing shader effect

Source: https://kaplayjs.com/docs/api/ctx/usePostEffect

This example demonstrates how to define a custom shader using loadShader and then apply it as a post-processing effect with usePostEffect.

```javascript
loadShader("invert", null, `
vec4 frag(vec2 pos, vec2 uv, vec4 color, sampler2D tex) {
    vec4 c = def_frag();
    return vec4(1.0 - c.r, 1.0 - c.g, 1.0 - c.b, c.a);
}
`)

usePostEffect("invert")
```

--------------------------------

### View CLI help

Source: https://kaplayjs.com/docs/guides/install

Displays all available options for the create-kaplay package.

```bash
npx create-kaplay --help
```

--------------------------------

### Implementing Touch Input Handlers

Source: https://kaplayjs.com/docs/guides/how-to-make-a-multiplayer-game-with-colyseus-and-kaplay

Register touch start and move events to simulate player movement using device pixel ratio scaling.

```typescript
k.onTouchStart(pos => touchPos = pos);
k.onTouchMove((pos) => {
    move(pos, pos.sub(touchPos).scale(window.devicePixelRatio), false);
    touchPos = pos;
});
```

--------------------------------

### initAudio()

Source: https://kaplayjs.com/docs/api/initAudio

Initializes the audio system and returns the audio context, master gain node, and default burp sound data.

```APIDOC
## initAudio()

### Description
Initializes the audio system. Returns an object containing the AudioContext, the master GainNode, and the default burp SoundData.

### Signature
`initAudio(): { ctx: AudioContext, masterNode: GainNode, burpSnd: SoundData }`

### Returns
- **ctx** (AudioContext) - The initialized Web Audio API context.
- **masterNode** (GainNode) - The master gain node for audio control.
- **burpSnd** (SoundData) - The default burp sound asset.
```

--------------------------------

### Check key states with isKeyDown

Source: https://kaplayjs.com/docs/api/ctx/isKeyDown

Examples showing how to detect if any key is pressed, a specific key is held, or if one of several keys is active.

```javascript
// Any key down

let lastKeyTime = time()
let triedToWakeUp = false

onUpdate(() => {
    if (isKeyDown()) {
        lastKeyTime = time()
        triedToWakeUp = false
        return
    }

    if (triedToWakeUp || time() - lastKeyTime < 5) return

    debug.log("Wake up!")
    triedToWakeUp = true
})

// Certain key down
// equivalent to the calling bean.move() in an onKeyDown("left")

onUpdate(() => {
    if (isKeyDown("left")) {
        bean.move(-SPEED, 0)
    }
})

// Certain keys down

let isMoving = false

onUpdate(() => {
    isMoving = isKeyDown(["left", "right"])
})
```

--------------------------------

### Initialize KAPLAY project

Source: https://kaplayjs.com/docs/guides/install

Generates a new project with the recommended structure using the KAPLAY CLI.

```bash
npx create-kaplay myGame
```

--------------------------------

### Building the Client for Production

Source: https://kaplayjs.com/docs/guides/how-to-make-a-multiplayer-game-with-colyseus-and-kaplay

Commands to build the client application for production deployment on different operating systems.

```bash
cd client
# Linux
npm run build
# Windows
npx vite build
```

--------------------------------

### Registering a key repeat event

Source: https://kaplayjs.com/docs/api/ctx/onKeyPressRepeat

This example demonstrates how to trigger an action repeatedly when the 'backspace' key is held down, specifically for text input deletion.

```javascript
// delete last character when "backspace" is being pressed and held
onKeyPressRepeat("backspace", () => {
    input.text = input.text.substring(0, input.text.length - 1);
});
```

--------------------------------

### getLayers

Source: https://kaplayjs.com/docs/api/reference

Get the layer names.

```APIDOC
## getLayers(): string[] | null

### Description
Get the layer names.

### Returns
- (string[] | null) The layer names or null if not set.
```

--------------------------------

### Generating random values with rand

Source: https://kaplayjs.com/docs/api/ctx/rand

Examples showing how to generate random numbers, vectors, and colors, as well as how to use rand within game object components.

```javascript
// a random number between 0 - 8
rand(8)

// a random point on screen
rand(vec2(width(), height()))

// a random color
rand(rgb(255, 255, 255))

// a random number between 50 - 100
rand(50, 100);

// a random point on screen with x between 20 - 100 and y between 20 - 100
rand(vec2(20), vec2(100));

// spawn something on the right side of the screen but with random y value within screen height
add([
    pos(width(), rand(0, height())),
]);
```

--------------------------------

### initApp(opt)

Source: https://kaplayjs.com/docs/api/initApp

Initializes the application with the provided configuration options and returns the application state and timing utilities.

```APIDOC
## initApp(opt)

### Description
Initializes the application environment, including canvas setup and input configuration.

### Parameters
- **opt** (Object) - Required
  - **canvas** (HTMLCanvasElement) - Required: The canvas element to render to.
  - **touchToMouse** (boolean) - Optional: Whether to map touch events to mouse events.
  - **gamepads** (Record<string, GamepadDef>) - Optional: Configuration for gamepads.
  - **pixelDensity** (number) - Optional: The pixel density for the canvas.
  - **maxFPS** (number) - Optional: The maximum frames per second.
  - **buttons** (ButtonsDef) - Optional: Button definitions.

### Returns
- **state** (Object) - The internal state object containing canvas, input states, timing data, and event handlers.
- **dt** (Function) - Returns the delta time.
- **fixedDt** (Function) - Returns the fixed delta time.
```

--------------------------------

### go(name: SceneName, args: any): void

Source: https://kaplayjs.com/docs/api/ctx/go

Transitions the game to the specified scene. Any additional arguments provided are passed directly to the scene's callback function.

```APIDOC
## go(name, args)

### Description
Go to a scene, passing all rest args to the scene callback.

### Parameters
- **name** (SceneName) - Required - The scene name.
- **args** (any) - Optional - The rest args to pass to the scene callback.

### Usage Example
```javascript
// go to "game" scene
go("game");

// go with options
go("game", { level: 1 });
```
```

--------------------------------

### camPos

Source: https://kaplayjs.com/docs/api/reference

Gets or sets the camera position (Deprecated).

```APIDOC
## camPos(pos?: Vec2 | number | x, y?: number)

### Description
Get / set camera position. Note: This function is deprecated. Use setCamPos and getCamPos instead.

### Parameters
- **pos** (Vec2) - Optional - The position to set the camera to.

### Returns
- **Vec2** - The current camera position.

### Since
v2000.0
```

--------------------------------

### initApp

Source: https://kaplayjs.com/docs/api/reference

Initializes the application with the provided configuration options, returning the application state object.

```APIDOC
## initApp(opt)

### Description
Initializes the KAPLAY application environment. This function sets up the canvas, input handling, and game loop state.

### Parameters
- **opt** (Object) - Required
  - **canvas** (HTMLCanvasElement) - Required: The target canvas element.
  - **touchToMouse** (boolean) - Optional: Whether to map touch events to mouse events.
  - **gamepads** (Record<string, GamepadDef>) - Optional: Configuration for gamepads.
  - **pixelDensity** (number) - Optional: The pixel density for the canvas.
  - **maxFPS** (number) - Optional: The maximum frames per second.
  - **buttons** (ButtonsDef) - Optional: Custom button definitions.
```

--------------------------------

### onFall

Source: https://kaplayjs.com/docs/api/BodyComp

Registers an event that runs when the object starts falling.

```APIDOC
## onFall(action: () => void): KEventController

### Description
Register an event that runs when the object starts falling.

### Parameters
- **action** (function) - Required - The callback function to execute when the object begins to fall.
```

--------------------------------

### initAudio

Source: https://kaplayjs.com/docs/api/reference

Initializes the audio context and master audio nodes for the game.

```APIDOC
## initAudio()

### Description
Initializes the Web Audio API context and sets up the master gain node for audio playback.
```

--------------------------------

### Create objects using prefabs

Source: https://kaplayjs.com/docs/guides/migration-4000

Demonstrates creating and adding objects using the prefab system.

```javascript
const enemy1 = add([sprite("alien"), pos(100)]); // (100, 100)

const enemyPrefab = createPrefab("enemy", enemy);

const enemy2 = addPrefab("enemy", [pos(400, 200)]); // (400, 200)
```

--------------------------------

### camScale

Source: https://kaplayjs.com/docs/api/ctx/camScale

Get or set the camera scale. This function is deprecated.

```APIDOC
## camScale

### Description
Get or set the camera scale. This function is deprecated, use setCamScale and getCamScale instead.

### Signatures
- camScale(scale: Vec2): Vec2
- camScale(x: number, y: number): Vec2
- camScale(xy: number): Vec2
- camScale(): Vec2

### Parameters
- **scale** (Vec2) - Optional - The scale to set the camera to.
- **x** (number) - Optional - The x component of the scale.
- **y** (number) - Optional - The y component of the scale.
- **xy** (number) - Optional - The uniform scale value.

### Returns
- **Vec2** - The current camera scale.
```

--------------------------------

### initAppState(opt)

Source: https://kaplayjs.com/docs/api/initAppState

Initializes the application state with the provided configuration options.

```APIDOC
## initAppState(opt)

### Description
Initializes the application state for a KAPLAY game. This function sets up the canvas, input handling, and internal timing mechanisms.

### Parameters
- **opt** (Object) - Required
  - **canvas** (HTMLCanvasElement) - Required - The canvas element to render the game.
  - **touchToMouse** (boolean) - Optional - Whether to map touch events to mouse events.
  - **gamepads** (Record<string, GamepadDef>) - Optional - Configuration for gamepads.
  - **pixelDensity** (number) - Optional - The pixel density for the canvas.
  - **maxFPS** (number) - Optional - The maximum frames per second.
  - **buttons** (ButtonsDef) - Optional - Custom button definitions.

### Returns
- **Object** - The initialized application state containing properties like `canvas`, `buttons`, `mousePos`, `keyState`, `gamepads`, and various timing and event handlers.
```

--------------------------------

### worldPos

Source: https://kaplayjs.com/docs/api/PosComp

Gets or sets the position of the object relative to the root.

```APIDOC
## worldPos

### Description
Get / Set the position of the object relative to the root.

### Signature
`worldPos(newPos?: Vec2): Vec2 | null`
```

--------------------------------

### screenPos

Source: https://kaplayjs.com/docs/api/PosComp

Gets or sets the position of the object relative to the screen.

```APIDOC
## screenPos

### Description
Get / Set the position of the object on the screen.

### Signature
`screenPos(newPos?: Vec2): Vec2 | null`
```

--------------------------------

### time

Source: https://kaplayjs.com/docs/api/reference

Returns the total time elapsed since the game started.

```APIDOC
## time()

### Description
Get the total time since beginning.

### Returns
- **number** - The total time.
```

--------------------------------

### layer() (get)

Source: https://kaplayjs.com/docs/api/LayerComp

Retrieves the name of the current layer the object is assigned to.

```APIDOC
## layer()

### Description
Get the name of the current layer the object is assigned to.

### Returns
- **string | null** - The name of the layer the object is assigned to.
```

--------------------------------

### Define Puck Constants

Source: https://kaplayjs.com/docs/guides/how-to-make-a-multiplayer-game-with-colyseus-and-kaplay

Set the size and starting position for the puck object.

```typescript
const size = 48;
const startPos = () => (k.center().sub(0, 6));
```

--------------------------------

### Operations Section Template

Source: https://kaplayjs.com/docs/guides/contributor-guide-on-guides

Standardized format for 'How to' collection sections within a guide.

```markdown
## [Title of Guide] Operations 

### How to [thing]

You can do [thing] with [thing they can use]
```

--------------------------------

### Create base HTML file

Source: https://kaplayjs.com/docs/guides/install

Initial structure for a KAPLAY project without using a bundler.

```html
<html>
  <head>
    <title>My Game</title>
  </head>
  <body></body>
</html>
```

--------------------------------

### go

Source: https://kaplayjs.com/docs/api/reference

Navigates to a specified scene, optionally passing arguments to the scene callback.

```APIDOC
## go

### Description
Go to a scene, passing all rest args to scene callback.

### Signature
`(name: SceneName, args: any): void`

### Parameters
- **name** (SceneName) - The scene name.
- **args** (any) - The rest args to pass to the scene callback.
```

--------------------------------

### Deploying the Colyseus Server

Source: https://kaplayjs.com/docs/guides/how-to-make-a-multiplayer-game-with-colyseus-and-kaplay

Commands to navigate to the server directory and initiate the deployment process using the Colyseus CLI.

```bash
cd server
npx @colyseus/cloud deploy
```

--------------------------------

### Initialize a new repository

Source: https://kaplayjs.com/docs/guides/how-to-make-a-multiplayer-game-with-colyseus-and-kaplay

Commands to remove the existing git history and initialize a new repository based on the operating system.

```bash
# Linux (Bash)
cd kaplay-colyseus; rm -rf .git; git init; git add .; git commit -m "Init commit"
```

```powershell
# Windows (PowerShell)
cd kaplay-colyseus; rm -r -Force .git; git init; git add .; git commit -m "Init commit"
```

```cmd
# Windows (CMD)
cd kaplay-colyseus && rmdir /s /q .git && git init && git add . && git commit -m "Init commit"
```

--------------------------------

### Retrieve all tags

Source: https://kaplayjs.com/docs/guides/tags

Access the tags property to get a read-only array of all tags assigned to an object.

```javascript
ghosty.tags; // read-only array with all tags.
// result: ["enemy"]
```

--------------------------------

### initAppGfx(gopt: KAPLAYOpt, ggl: GfxCtx)

Source: https://kaplayjs.com/docs/api/initAppGfx

Initializes the graphics environment for the application using the provided options and graphics context.

```APIDOC
## initAppGfx

### Signature
`initAppGfx(gopt: KAPLAYOpt, ggl: GfxCtx)`

### Description
Initializes the graphics context and returns an object containing the rendering state and utility methods for WebGL operations.

### Parameters
- **gopt** (KAPLAYOpt) - Required - Configuration options for the KAPLAY application.
- **ggl** (GfxCtx) - Required - The graphics context object.

### Returns
- **lastDrawCalls** (number)
- **ggl** (Object) - Contains WebGL context, texture filters, and lifecycle methods like `onDestroy` and `destroy`.
- **renderer** (BatchRenderer)
- **transform** (Mat4)
- **width** (number)
- **height** (number)

### Methods
- **pushTexture2D/popTexture2D** (item: WebGLTexture) - Manage texture stack.
- **pushArrayBuffer/popArrayBuffer** (item: WebGLBuffer) - Manage array buffer stack.
- **pushFramebuffer/popFramebuffer** (item: WebGLFramebuffer) - Manage framebuffer stack.
- **pushViewport/popViewport** (item: {x, y, w, h}) - Manage viewport stack.
- **setVertexFormat** (fmt: VertexFormat) - Sets the current vertex format.
```

--------------------------------

### Set Game Object Position

Source: https://kaplayjs.com/docs/api/ctx/pos

Example of using the pos component to place a sprite at specific coordinates.

```javascript
// This game object will draw a "bean" sprite at (100, 200)
add([
    pos(100, 200),
    sprite("bean"),
]);
```

--------------------------------

### Initialize and play a video component

Source: https://kaplayjs.com/docs/guides/video

Adds a video component to the game scene and triggers playback.

```javascript
const intro = add([
    pos(200, 100), // Where to place the video
    video("intro.mp4"),
]);

intro.play();
```

--------------------------------

### Query objects by tag

Source: https://kaplayjs.com/docs/guides/tags

Use the get method to retrieve all game objects that share a specific tag.

```javascript
obj.get("enemy"); // returns an array with all enemy game objects
```

--------------------------------

### initGame()

Source: https://kaplayjs.com/docs/api/initGame

Initializes the game engine and returns the game state object containing event handlers, scene information, and camera properties.

```APIDOC
## initGame()

### Description
Initializes the KAPLAY game environment. This function sets up the core engine, event listeners, and game state.

### Signature
`initGame(): { events: KEventHandler, objEvents: KEventHandler, root: GameObj, gravity: Vec2 | null, scenes: Record<SceneName, SceneDef>, currentScene: SceneName | null, layers: string[] | null, defaultLayerIndex: number, logs: Array, cam: Object }`

### Returns
- **events** (KEventHandler) - Object containing various event hooks for input, game objects, and engine lifecycle.
- **objEvents** (KEventHandler) - Event handler for game object specific events.
- **root** (GameObj) - The root game object containing the timer component.
- **gravity** (Vec2 | null) - Current gravity vector.
- **scenes** (Record) - Dictionary of defined game scenes.
- **currentScene** (SceneName | null) - The name of the currently active scene.
- **layers** (string[] | null) - List of defined layers.
- **cam** (Object) - Camera properties including position, scale, angle, shake, and transform matrix.
```

--------------------------------

### initGfx

Source: https://kaplayjs.com/docs/api/initGfx

Initializes the graphics context and returns an object containing methods to manipulate the WebGL state stack.

```APIDOC
## initGfx(gl, opts)

### Description
Initializes the graphics context. Returns an object with methods to push and pop various WebGL states.

### Parameters
- **gl** (WebGLRenderingContext) - Required - The WebGL rendering context.
- **opts** (Object) - Optional - Configuration options.
  - **texFilter** (TexFilter) - Optional - Texture filtering mode.

### Methods
- **onDestroy(action: () => unknown) => void** - Registers a callback for when the graphics context is destroyed.
- **destroy() => void** - Destroys the graphics context.
- **pushTexture2D(item: WebGLTexture) => void** - Pushes a texture to the stack.
- **popTexture2D() => void** - Pops a texture from the stack.
- **pushArrayBuffer(item: WebGLBuffer) => void** - Pushes an array buffer to the stack.
- **popArrayBuffer() => void** - Pops an array buffer from the stack.
- **pushElementArrayBuffer(item: WebGLBuffer) => void** - Pushes an element array buffer to the stack.
- **popElementArrayBuffer() => void** - Pops an element array buffer from the stack.
- **pushFramebuffer(item: WebGLFramebuffer) => void** - Pushes a framebuffer to the stack.
- **popFramebuffer() => void** - Pops a framebuffer from the stack.
- **pushRenderbuffer(item: WebGLRenderbuffer) => void** - Pushes a renderbuffer to the stack.
- **popRenderbuffer() => void** - Pops a renderbuffer from the stack.
- **pushViewport(item: {x: number, y: number, w: number, h: number}) => void** - Pushes a viewport configuration to the stack.
- **popViewport() => void** - Pops a viewport from the stack.
- **pushProgram(item: WebGLProgram) => void** - Pushes a shader program to the stack.
- **popProgram() => void** - Pops a shader program from the stack.
- **setVertexFormat(fmt: VertexFormat) => void** - Sets the current vertex format.
```

--------------------------------

### kaplay(gopt?: KAPLAYOpt): KAPLAYCtx

Source: https://kaplayjs.com/docs/api/kaplay

Initializes the KAPLAY context. This is the entry point for all KAPLAY games. It can either attach functions to the global scope or return a context handle for scoped access.

```APIDOC
## kaplay(gopt?: KAPLAYOpt)

### Description
Initializes the KAPLAY context. This function sets up the canvas and game environment. By default, it imports all KAPLAY functions into the global scope, but this can be disabled by setting the `global` option to `false`.

### Parameters
- **gopt** (KAPLAYOpt) - Optional - Configuration object for the engine (e.g., width, height, font, canvas, background, global).

### Returns
- **KAPLAYCtx** - The context object containing all engine methods.

### Example
```javascript
// Start with default options
kaplay();

// Start with custom options and scoped access
const k = kaplay({
    width: 320,
    height: 240,
    global: false
});

k.add(...);
```
```

--------------------------------

### Apply surfaceEffector to a game object

Source: https://kaplayjs.com/docs/api/ctx/surfaceEffector

This example demonstrates how to add a surfaceEffector to a static body to create a conveyor belt effect.

```javascript
loadSprite("belt", "/sprites/jumpy.png")

// conveyor belt
add([
    pos(center()),
    sprite("belt"),
    rotate(90),
    area(),
    body({ isStatic: true }),
    surfaceEffector({
        speed: 50,
    })
])
```

--------------------------------

### Using the sprite component

Source: https://kaplayjs.com/docs/api/ctx/sprite

Demonstrates basic sprite initialization, using options for animations, and controlling animation state or frames.

```javascript
// minimal setup
add([
    sprite("bean"),
])

// with options
const bean = add([
    sprite("bean", {
        // start with animation "idle"
        anim: "idle",
    }),
])

// play / stop an anim
bean.play("jump")
bean.stop()

// manually setting a frame
bean.frame = 3
```

--------------------------------

### Registering a collision end event

Source: https://kaplayjs.com/docs/api/ctx/onCollideEnd

This example demonstrates how to trigger an action when objects tagged 'bean' and 'earth' stop colliding.

```javascript
onCollideEnd("bean", "earth", () => {
    debug.log("destroying world in 3... 2... 1...")
});
```

--------------------------------

### Create and add a game object with make()

Source: https://kaplayjs.com/docs/api/ctx/make

Instantiate a game object with components, modify it, and then add it to the scene to enable rendering.

```javascript
const label = make([
    rect(100, 20),
]);

// Add a new text to the label
label.add([
    text("Hello, world!"),
]);

// Add game object to the scene
// Now it will render
add(label);
```

--------------------------------

### Create a basic particle emitter

Source: https://kaplayjs.com/docs/guides/particles

Initializes a particle emitter using ParticlesOpt and EmitterOpt to define particle behavior and emission patterns.

```javascript
let particleEmitter = add([
    pos(center()),
    particles(
        {
            max: 20,
            speed: [50, 50],
            lifeTime: [1, 2],
        },
        {
            direction: 0,
            spread: 45,
        },
    ),
]);
```

--------------------------------

### camRot(angle?: number): number

Source: https://kaplayjs.com/docs/api/ctx/camRot

Gets or sets the camera rotation. This function is deprecated; use setCamRot and getCamRot instead.

```APIDOC
## camRot(angle?: number): number

### Description
Get or set the camera rotation. This function is deprecated and users should use setCamRot and getCamRot instead.

### Parameters
- **angle** (number) - Optional - The angle to rotate the camera.

### Returns
- **number** - The current camera rotation.
```

--------------------------------

### Import KAPLAY via ES Modules

Source: https://kaplayjs.com/docs/guides/install

Connects a module script to the HTML and initializes KAPLAY.

```html
<body>
  <script type="module" src="./main.js"></script>
</body>
```

```javascript
// main.js
import kaplay from "https://unpkg.com/kaplay@3001.0.19/dist/kaplay.mjs";
kaplay();
```

--------------------------------

### Using the follow component

Source: https://kaplayjs.com/docs/api/ctx/follow

Demonstrates attaching the follow component to a game object to track a target, including setting and updating an offset.

```javascript
const bean = add(...)

add([
    sprite("bag"),
    pos(),
    follow(bean) // Follow bean's position
]);

// Using offset
const target = add(...)

const mark = add([
  sprite("mark"),
  pos(),
  follow(target, vec2(32, 32)) // Follow target's position with an offset
])

mark.follow.offset = vec2(64, 64) // Change the offset
```

--------------------------------

### Setting and modifying object opacity

Source: https://kaplayjs.com/docs/api/ctx/opacity

Demonstrates how to initialize an object with opacity and update its visibility dynamically.

```javascript
const bean = add([
    sprite("bean"),
    opacity(0.5) // Make bean 50% transparent
])

// Make bean invisible
bean.opacity = 0

// Make bean fully visible
bean.opacity = 1
```

--------------------------------

### Set Camera Position

Source: https://kaplayjs.com/docs/api/ctx/setCamPos

Examples of moving the camera using different parameter formats including coordinates, vectors, and uniform values.

```javascript
// move camera to (100, 100)
setCamPos(100, 100);
setCamPos(vec2(100, 100));
setCamPos(100); // x and y are the same
```

--------------------------------

### state(initialState, stateList, transitions)

Source: https://kaplayjs.com/docs/api/ctx/state

Initializes a finite state machine with pre-defined allowed transitions between states.

```APIDOC
## state(initialState, stateList, transitions)

### Description
Creates a finite state machine component with explicit transition rules between states.

### Parameters
- **initialState** (string) - Required - The initial state of the object.
- **stateList** (string[]) - Required - The list of valid states.
- **transitions** (Record<string, string | string[]>) - Required - A mapping defining which states can transition to which other states.

### Returns
- **StateComp** - The state component instance.
```

--------------------------------

### Rotate object on hover

Source: https://kaplayjs.com/docs/api/ctx/onHoverUpdate

Example of rotating a game object with the tag 'bean' by 90 degrees per second while the pointer is hovering over it.

```javascript
// Rotate bean 90 degrees per second when hovered
onHoverUpdate("bean", (bean) => {
  bean.angle += dt() * 90
});
```

--------------------------------

### Destroying an object with lifespan

Source: https://kaplayjs.com/docs/api/ctx/lifespan

Spawns a sprite and configures it to be destroyed after 1 second, with a 0.5-second fade-out period starting after the initial time.

```javascript
// spawn an explosion, destroy after 1.5 seconds (time + fade)
add([
    sprite("explosion", { anim: "burst", }),
    lifespan(1, {
        fade: 0.5 // it start fading 0.5 second after time
    }),
]);
```

--------------------------------

### get(tag: Tag | Tag[], opts?: GetOpt): GameObj[]

Source: https://kaplayjs.com/docs/api/reference

Retrieves a list of all game objects associated with a specific tag or tags.

```APIDOC
## get(tag: Tag | Tag[], opts?: GetOpt): GameObj[]

### Description
Get a list of all game objects with a certain tag.

### Parameters
- **tag** (Tag | Tag[]) - Required - The tag to search for. Use "*" to get all objects.
- **opts** (GetOpt) - Optional - Additional options.

### Returns
- **GameObj[]** - A list of game objects that have the tag.
```

--------------------------------

### get(tag, opts)

Source: https://kaplayjs.com/docs/api/ctx/get

Retrieves a list of all game objects that match the specified tag or tags. Use '*' to retrieve all objects in the scene.

```APIDOC
## get(tag, opts)

### Description
Retrieves a list of all game objects that match the specified tag or tags. Use '*' to retrieve all objects in the scene.

### Signature
`get(tag: Tag | Tag[], opts?: GetOpt): GameObj[]`

### Parameters
- **tag** (Tag | Tag[]) - Required - The tag to search for. Use "*" to get all objects.
- **opts** (GetOpt) - Optional - Additional options for the search, such as recursive searching.

### Returns
- **GameObj[]** - A list of game objects that have the tag.

### Examples
```javascript
// get a list of all game objs with tag "bomb"
const allBombs = get("bomb");

// To get all objects use "*"
const allObjs = get("*");

// Recursively get all children and descendents
const allObjs = get("*", { recursive: true });
```
```

--------------------------------

### get(tag: Tag | Tag[], opts?: GetOpt): GameObj[]

Source: https://kaplayjs.com/docs/api/GameObjRaw

Retrieves a list of child game objects matching the specified tag(s).

```APIDOC
## get(tag: Tag | Tag[], opts?: GetOpt): GameObj[]

### Description
Get a list of all game objs with certain tag.

### Parameters
- **tag** (Tag | Tag[]) - Required - The tag or tags to filter by.
- **opts** (GetOpt) - Optional - Additional options for the query.

### Returns
- **GameObj[]** - A list of matching game objects.
```

--------------------------------

### Handle app events

Source: https://kaplayjs.com/docs/guides/events

Demonstrates specific key press listeners and asset loading completion events.

```javascript
// Only runs when the user presses "a"
onKeyPress("a", () => {
    debug.log("aaa");
});

// Only runs when assets finish loading
onLoad(() => {});
```

--------------------------------

### GetOpt

Source: https://kaplayjs.com/docs/api/GetOpt

Configuration options for game object retrieval methods.

```APIDOC
## GetOpt

### Description
Configuration object used to filter and control the behavior of game object retrieval operations.

### Parameters
- **recursive** (boolean) - Optional - If true, recursively get all children and their descendants.
- **liveUpdate** (boolean) - Optional - If true, live update the returned list every time an object is added or removed.
- **only** ("tags" | "comps") - Optional - Filter the results to include only objects matching specific tags or components.
```

--------------------------------

### Playing and controlling audio

Source: https://kaplayjs.com/docs/api/ctx/play

Demonstrates playing a one-off sound, a looping soundtrack with options, and using the returned handle to modify playback state.

```javascript
// play a one off sound
play("wooosh")

// play a looping soundtrack (check out AudioPlayOpt for more options)
const music = play("OverworldlyFoe", {
    volume: 0.8,
    loop: true
})

// using the handle to control (check out AudioPlay for more controls / info)
music.paused = true
music.speed = 1.2
```
Tokens:
Raw