Kaboom.js

Start

kaboom()

Game Obj

Timer

Audio

Scene

Level

Data

Debug

NOTE: Kaboom.js is no longer maintained. See GitHub for more.Kaboom.js is a Javascript game programming library that helps you make games fast and fun.

// start the game
kaboom()

// define gravity
setGravity(2400)

// load a default sprite
loadBean()

// add character to screen, from a list of components
const player = add([
    sprite("bean"),  // renders as a sprite
    pos(120, 80),    // position in world
    area(),          // has a collider
    body(),          // responds to physics and gravity
])

// jump when player presses "space" key
onKeyPress("space", () => {
    // .jump() is provided by the body() component
    player.jump()
})

Play with it yourself or check out the examples in the Playground!

Start

kaboom(options?: KaboomOpt<T>)

Initialize kaboom context. The starting point of all kaboom games.

// Start kaboom with default options (will create a fullscreen canvas under <body>)
kaboom()

// Init with some options (check out #KaboomOpt for full options list)
kaboom({
    width: 320,
    height: 240,
    font: "sans-serif",
    canvas: document.querySelector("#mycanvas"),
    background: [ 0, 0, 255, ],
})

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

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

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

Game Obj

add(comps?: CompList<T> | GameObj<T>) => GameObj<T>

Assemble a game object from a list of components, and add it to the game

returns

The added game object that contains all properties and methods each component offers.

const player = add([
    // List of components, each offers a set of functionalities
    sprite("mark"),
    pos(100, 200),
    area(),
    body(),
    health(8),
    // Plain strings are tags, a quicker way to let us define behaviors for a group
    "player",
    "friendly",
    // Components are just plain objects, you can pass an object literal as a component.
    {
        dir: LEFT,
        dead: false,
        speed: 240,
    },
])

// .jump is provided by body()
player.jump()

// .moveTo is provided by pos()
player.moveTo(300, 200)

// .onUpdate() is on every game object, it registers an event that runs every frame
player.onUpdate(() => {
    // .move() is provided by pos()
    player.move(player.dir.scale(player.speed))
})

// .onCollide is provided by area()
player.onCollide("tree", () => {
    destroy(player)
})

make(comps?: CompList<T>) => GameObj<T>

Create a game object like add(), but not adding to the scene.

since

v3000.1

const label = make([
    text("oh hi"),
])

add([
    rect(label.width, label.height),
    color(0, 0, 255),
    children(label),
])

readd(obj: GameObj)

Remove and re-add the game obj, without triggering add / destroy events.

// Common way to use this is to have one sprite overlap another sprite, and use readd() to have the bottom sprite on top of the other.

// Create two sprites.
const greenBean = add([
sprite("bean"),
pos(200,140),
color(255, 255, 255),
     * area(),
])

// This bean will overlap the green bean.
const purpleBean = add([
sprite("bean"),
pos(230,140),
color(255, 0, 255),
 area(),
])

// Example 1: simply call readd() on the target you want on top.
readd(greenBean)   

// Example 2: using onClick() or other functions with readd().
// If you comment out the first example, and use this readd() with a function like onClick(), you
can keep switching which sprite is above the other ( click on edge of face ).

purpleBean.onClick(() => {
        readd(greenBean)
})
       
greenBean.onClick(() => {
        readd(purpleBean)
})

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

Get a list of all game objs with certain tag.

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

destroy(obj: GameObj)

Remove the game obj.

// every time bean collides with anything with tag "fruit", remove it
bean.onCollide("fruit", (fruit) => {
    destroy(fruit)
})

destroyAll(tag: Tag)

Remove all game objs with certain tag.

// destroy all objects with tag "bomb" when you click one
onClick("bomb", () => {
    destroyAll("bomb")
})

Components

pos(x: number, y: number) => PosComp

Position

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

pos(xy: number) => PosComp

pos(p: Vec2) => PosComp

pos() => PosComp

scale(x: number, y: number) => ScaleComp

Scale.

scale(xy: number) => ScaleComp

scale(s: Vec2) => ScaleComp

scale() => ScaleComp

Scale the game obj.

// scale uniformly with one value 
add([
    sprite("bean"),
       scale(3),
])
// scale with x & y values. In this case, scales more horizontally.
add([
    sprite("bean"),
       scale(3, 1),
])
 // scale with vec2(x,y).
bean.scale = vec2(2,4)

rotate(a: number) => RotateComp

Rotation (in degrees).

color(r: number, g: number, b: number) => ColorComp

Sets color (rgb 0-255).

// blue frog
add([
    sprite("bean"),
    color(0, 0, 255)
])

color(c: Color) => ColorComp

color(rgb: unknown) => ColorComp

color(c: string) => ColorComp

color() => ColorComp

opacity(o?: number) => OpacityComp

Sets opacity (0.0 - 1.0).

sprite(spr: string | SpriteData, options?: SpriteCompOpt) => SpriteComp

Render as a sprite.

// 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

text(txt: string, options?: TextCompOpt) => TextComp

Render as text.

// 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
    }),
])

polygon(pts: Vec2[], opt?: PolygonCompOpt) => PolygonComp

Render as a polygon.

since

v3000.2

// Make a square the hard way
add([
    pos(80, 120),
    polygon([vec2(0,0), vec2(50,0), vec2(50,50), vec2(0,50)]),
    outline(4),
    area(),
])

rect(w: number, h: number, opt?: RectCompOpt) => RectComp

Render as a rectangle.

// i don't know, could be an obstacle or something
add([
    pos(80, 120),
    rect(20, 40),
    outline(4),
    area(),
])

circle(radius: number) => CircleComp

Render as a circle.

add([
    pos(80, 120),
    circle(16),
])

uvquad(w: number, h: number) => UVQuadComp

Render as a UV quad.

add([
    uvquad(width(), height()),
    shader("spiral"),
])

area() => AreaComp

Generates collider area from shape and enables collision detection.

// Automatically generate area information from the shape of render
const player = add([
    sprite("bean"),
    area(),
])

// Die if player collides with another game obj with tag "tree"
player.onCollide("tree", () => {
    destroy(player)
    go("lose")
})

// Check for collision manually every frame instead of registering an event
player.onUpdate(() => {
    if (player.isColliding(bomb)) {
        score += 1
    }
})

area(options: AreaCompOpt) => AreaComp

Define collider area and enables collision detection.

add([
    sprite("flower"),
    // Scale to 0.6 of the generated area
    area({ scale: 0.6 }),
    // If we want the area scale to be calculated from the center
    anchor("center"),
])

add([
    sprite("bean"),
    // Define area with custom shape
    area({ shape: new Polygon([vec2(0), vec2(100), vec2(-100, 100)]) }),
])

anchor(o: Anchor | Vec2) => AnchorComp

Anchor point for render (default "topleft").

// set anchor to "center" so it'll rotate from center
add([
    rect(40, 10),
    rotate(45),
    anchor("center"),
])

z(z: number) => ZComp

Determines the draw order for objects on the same layer. Object will be drawn on top if z value is bigger.

outline(width?: number, color?: Color) => OutlineComp

Give obj an outline.

body(options?: BodyCompOpt) => BodyComp

Physical body that responds to gravity. Requires "area" and "pos" comp. This also makes the object "solid".

// bean jumpy
const bean = add([
    sprite("bean"),
    // body() requires "pos" and "area" component
    pos(),
    area(),
    body(),
])

// when bean is grounded, press space to jump
// check out #BodyComp for more methods
onKeyPress("space", () => {
    if (bean.isGrounded()) {
        bean.jump()
    }
})

// run something when bean falls and hits a ground
bean.onGround(() => {
    debug.log("oh no!")
})

doubleJump(numJumps?: number) => DoubleJumpComp

Enables double jump. Requires "body" component.

since

v3000.0

move(direction: number | Vec2, speed: number) => EmptyComp

Move towards a direction infinitely, and destroys when it leaves game view. Requires "pos" component.

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

offscreen(opt?: OffScreenCompOpt) => OffScreenComp

Control the behavior of object when it goes out of view.

since

v2000.2

add([
    pos(player.pos),
    sprite("bullet"),
    offscreen({ destroy: true }),
    "projectile",
])

follow(obj: GameObj | null, offset?: Vec2) => FollowComp

Follow another game obj's position.

shader(id: string, uniform?: Uniform | (() => Uniform)) => ShaderComp

Custom shader.

timer() => TimerComp

Enable timer related functions like wait(), loop(), tween() on the game object.

const obj = add([
    timer(),
])

obj.wait(2, () => { ... })
obj.loop(0.5, () => { ... })
obj.tween(obj.pos, mousePos(), 0.5, (p) => obj.pos = p, easings.easeOutElastic)

fixed() => FixedComp

Make object unaffected by camera or parent object transforms, and render at last.

// this will be be fixed on top left and not affected by camera
const score = add([
    text(0),
    pos(12, 12),
    fixed(),
])

stay(scenesToStay?: string[]) => StayComp

Don't get destroyed on scene switch.

player.onCollide("bomb", () => {
    // spawn an explosion and switch scene, but don't destroy the explosion game obj on scene switch
    add([
        sprite("explosion", { anim: "burst", }),
        stay(),
        lifespan(1),
    ])
    go("lose", score)
})

health(hp: number, maxHP?: number) => HealthComp

Handles health related logic and events.

const player = add([
    health(3),
])

player.onCollide("bad", (bad) => {
    player.hurt(1)
    bad.hurt(1)
})

player.onCollide("apple", () => {
    player.heal(1)
})

player.on("hurt", () => {
    play("ouch")
})

// triggers when hp reaches 0
player.on("death", () => {
    destroy(player)
    go("lose")
})

lifespan(time: number, options?: LifespanCompOpt) => EmptyComp

Destroy the game obj after certain amount of time

// spawn an explosion, destroy after 1 seconds, start fading away after 0.5 second
add([
    sprite("explosion", { anim: "burst", }),
    lifespan(1, { fade: 0.5 }),
])

state(initialState: string, stateList?: string[]) => StateComp

Finite state machine.

since

v2000.1

const enemy = add([
    pos(80, 100),
    sprite("robot"),
    state("idle", ["idle", "attack", "move"]),
])

// this callback will run once when enters "attack" state
enemy.onStateEnter("attack", () => {
    // enter "idle" state when the attack animation ends
    enemy.play("attackAnim", {
        // any additional arguments will be passed into the onStateEnter() callback
        onEnd: () => enemy.enterState("idle", rand(1, 3)),
    })
    checkHit(enemy, player)
})

// this will run once when enters "idle" state
enemy.onStateEnter("idle", (time) => {
    enemy.play("idleAnim")
    wait(time, () => enemy.enterState("move"))
})

// this will run every frame when current state is "move"
enemy.onStateUpdate("move", () => {
    enemy.follow(player)
    if (enemy.pos.dist(player.pos) < 16) {
        enemy.enterState("attack")
    }
})

state(initialState: string, stateList: string[], transitions: Record<string, string | string[]>) => StateComp

state() with pre-defined transitions.

since

v2000.2

const enemy = add([
    pos(80, 100),
    sprite("robot"),
    state("idle", ["idle", "attack", "move"], {
        "idle": "attack",
        "attack": "move",
        "move": [ "idle", "attack" ],
    }),
])

// this callback will only run once when enter "attack" state from "idle"
enemy.onStateTransition("idle", "attack", () => {
    checkHit(enemy, player)
})

fadeIn(time: number) => Comp

Fade object in.

since

v3000.0

mask(maskType?: Mask) => MaskComp

Mask all children object render.

since

v3000.2

drawon(canvas: FrameBuffer) => Comp

tile(opt: TileCompOpt) => TileComp

A tile on a tile map.

since

v3000.0

agent(opt?: AgentCompOpt) => AgentComp

An agent which can finds it way on a tilemap.

since

v3000.0

Events

on(event: string, tag: Tag, action: (obj: GameObj, args: ...) => void) => EventController

// 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 a name and a callback function
on("talk", (message, posX, posY) => {
    add([
     text(message), 
     pos(posX, posY - 100)
    ])
})
onKeyPress("space", () => {
   // the trigger method on game objs can be used to trigger a custom event
   npc.trigger("talk", "Hello World!", npc.pos.x, npc.pos.y)
})

onUpdate(tag: Tag, action: (obj: GameObj) => void) => EventController

since

v2000.1

// move every "tree" 120 pixels per second to the left, destroy it when it leaves screen
// there'll be nothing to run if there's no "tree" obj in the scene
onUpdate("tree", (tree) => {
    tree.move(-120, 0)
    if (tree.pos.x < 0) {
        destroy(tree)
    }
})

onUpdate(action: () => void) => EventController

since

v2000.1

// This will run every frame
onUpdate(() => {
    debug.log("ohhi")
})

onDraw(tag: Tag, action: (obj: GameObj) => void) => EventController

Register an event that runs every frame (~60 times per second) for all game objs with certain tag (this is the same as onUpdate but all draw events are run after update events, drawXXX() functions only work in this phase).

since

v2000.1

onDraw(action: () => void) => EventController

Register an event that runs every frame (~60 times per second) (this is the same as onUpdate but all draw events are run after update events, drawXXX() functions only work in this phase).

since

v2000.1

onDraw(() => {
    drawLine({
        p1: vec2(0),
        p2: mousePos(),
        color: rgb(0, 0, 255),
    })
})

onAdd(tag: Tag, action: (obj: GameObj) => void) => EventController

onAdd(action: (obj: GameObj) => void) => EventController

onDestroy(tag: Tag, action: (obj: GameObj) => void) => EventController

onDestroy(action: (obj: GameObj) => void) => EventController

onLoad(action: () => void)

since

v2000.1

const bean = add([
    sprite("bean"),
])

// certain assets related data are only available when the game finishes loading
onLoad(() => {
    debug.log(bean.width)
})

onLoading(action: (progress: number) => void)

since

v3000.0

onError(action: (err: Error) => void)

since

v3000.0

onResize(action: () => void)

since

v3000.0

onCleanup(action: () => void)

Cleanup function to run when quit() is called.

since

v3000.0

onGamepadConnect(action: (gamepad: KGamePad) => void)

since

v3000.0

onGamepadDisconnect(action: (gamepad: KGamePad) => void)

since

v3000.0

onCollide(t1: Tag, t2: Tag, action: (a: GameObj, b: GameObj, col?: Collision) => void) => EventController

since

v2000.1

onCollide("sun", "earth", () => {
    addExplosion()
})

onCollideUpdate(t1: Tag, t2: Tag, action: (a: GameObj, b: GameObj, col?: Collision) => void) => EventController

since

v3000.0

onCollideUpdate("sun", "earth", () => {
    runWorldEndTimer()
})

onCollideEnd(t1: Tag, t2: Tag, action: (a: GameObj, b: GameObj, col?: Collision) => void) => EventController

Register an event that runs once frame when 2 game objs with certain tags stops colliding (required to have area() component).

since

v3000.0

onCollideEnd("bean", "earth", () => {
    worldEnd()
})

onClick(tag: Tag, action: (a: GameObj) => void) => EventController

since

v2000.1

// click on any "chest" to open
onClick("chest", (chest) => chest.open())

onClick(action: () => void) => EventController

since

v2000.1

// click on anywhere to go to "game" scene
onClick(() => go("game"))

onHover(tag: Tag, action: (a: GameObj) => void) => EventController

since

v3000.0

onHoverUpdate(tag: Tag, onHover: (a: GameObj) => void) => EventController

Register an event that runs every frame when game objs with certain tags are hovered (required to have area() component).

since

v3000.0

onHoverEnd(tag: Tag, action: (a: GameObj) => void) => EventController

since

v3000.0

onKeyDown(key: Key, action: (key: Key) => void) => EventController

since

v2000.1

// move left by SPEED pixels per frame every frame when left arrow key is being held down
onKeyDown("left", () => {
    bean.move(-SPEED, 0)
})

onKeyDown(action: (key: Key) => void) => EventController

since

v2000.1

onKeyPress(key: Key, action: (key: Key) => void) => EventController

since

v2000.1

// .jump() once when "space" is just being pressed
onKeyPress("space", () => {
    bean.jump()
})

onKeyPress(action: (key: Key) => void) => EventController

since

v2000.1

// Call restart() when player presses any key
onKeyPress(() => {
    restart()
})

onKeyPressRepeat(k: Key, action: (k: Key) => void) => EventController

since

v2000.1

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

onKeyPressRepeat(action: (k: Key) => void) => EventController

onKeyRelease(k: Key, action: (k: Key) => void) => EventController

since

v2000.1

onKeyRelease(action: (k: Key) => void) => EventController

onCharInput(action: (ch: string) => void) => EventController

since

v2000.1

// type into input
onCharInput((ch) => {
    input.text += ch
})

onMouseDown(action: (m: MouseButton) => void) => EventController

since

v2000.1

onMouseDown(button: MouseButton, action: (m: MouseButton) => void) => EventController

onMousePress(action: (m: MouseButton) => void) => EventController

since

v2000.1

onMousePress(button: MouseButton, action: (m: MouseButton) => void) => EventController

onMouseRelease(action: (m: MouseButton) => void) => EventController

since

v2000.1

onMouseRelease(button: MouseButton, action: (m: MouseButton) => void) => EventController

onMouseMove(action: (pos: Vec2, delta: Vec2) => void) => EventController

since

v2000.1

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

since

v2000.1

onTouchMove(action: (pos: Vec2, t: Touch) => void) => EventController

since

v2000.1

onTouchEnd(action: (pos: Vec2, t: Touch) => void) => EventController

since

v2000.1

onScroll(action: (delta: Vec2) => void) => EventController

since

v3000.0

onHide(action: () => void) => EventController

since

v3000.2

onShow(action: () => void) => EventController

since

v3000.2

onGamepadButtonDown(btn: GamepadButton, action: (btn: GamepadButton) => void) => EventController

since

v3000.0

onGamepadButtonDown(action: (btn: GamepadButton) => GamepadButton) => EventController

since

v3000.0

onGamepadButtonPress(btn: GamepadButton, action: (btn: GamepadButton) => void) => EventController

since

v3000.0

onGamepadButtonPress(action: (btn: GamepadButton) => GamepadButton) => EventController

since

v3000.0

onGamepadButtonRelease(btn: GamepadButton, action: (btn: GamepadButton) => void) => EventController

since

v3000.0

onGamepadButtonRelease(action: (btn: GamepadButton) => void) => EventController

since

v3000.0

onGamepadStick(stick: GamepadStick, action: (value: Vec2) => void) => EventController

since

v3000.0

onSceneLeave(action: (newScene?: string) => void) => EventController

since

v3000.0

Assets

loadRoot(path?: string) => string

Sets the root for all subsequent resource urls.

loadRoot("https://myassets.com/")
loadSprite("bean", "sprites/bean.png") // will resolve to "https://myassets.com/sprites/bean.png"

loadSprite(name: string | null, src: LoadSpriteSrc | LoadSpriteSrc[], options?: LoadSpriteOpt) => Asset<SpriteData>

Load a sprite into asset manager, with name and resource url and optional config.

// due to browser policies you'll need a static file server to load local files
loadSprite("bean", "bean.png")
loadSprite("apple", "https://kaboomjs.com/sprites/apple.png")

// slice a spritesheet and add anims manually
loadSprite("bean", "bean.png", {
    sliceX: 4,
    sliceY: 1,
    anims: {
        run: {
            from: 0,
            to: 3,
        },
        jump: {
            from: 3,
            to: 3,
        },
    },
})

loadSpriteAtlas(src: LoadSpriteSrc, data: SpriteAtlasData) => Asset<Record<string, SpriteData>>

Load sprites from a sprite atlas.

// See #SpriteAtlasData type for format spec
loadSpriteAtlas("sprites/dungeon.png", {
    "hero": {
        x: 128,
        y: 68,
        width: 144,
        height: 28,
        sliceX: 9,
        anims: {
            idle: { from: 0, to: 3 },
            run: { from: 4, to: 7 },
            hit: 8,
        },
    },
})

const player = add([
    sprite("hero"),
])

player.play("run")

loadSpriteAtlas(src: LoadSpriteSrc, url: string) => Asset<Record<string, SpriteData>>

Load sprites from a sprite atlas with URL.

// Load from json file, see #SpriteAtlasData type for format spec
loadSpriteAtlas("sprites/dungeon.png", "sprites/dungeon.json")

const player = add([
    sprite("hero"),
])

player.play("run")

loadAseprite(name: string | null, imgSrc: LoadSpriteSrc, jsonSrc: string | AsepriteData) => Asset<SpriteData>

Load a sprite with aseprite spritesheet json (should use "array" in the export options).

loadAseprite("car", "sprites/car.png", "sprites/car.json")

loadPedit(name: string | null, src: string) => Asset<SpriteData>

loadBean(name?: string) => Asset<SpriteData>

Load default sprite "bean".

loadBean()

// use it right away
add([
    sprite("bean"),
])

loadJSON(name: string | null, url: string) => Asset<any>

Load custom JSON data from url.

since

v3000.0

loadSound(name: string | null, src: string | ArrayBuffer) => Asset<SoundData>

Load a sound into asset manager, with name and resource url.

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

loadMusic(name: string | null, url: string)

Like loadSound(), but the audio is streamed and won't block loading. Use this for big audio files like background music.

loadMusic("shoot", "/music/bossfight.mp3")

loadFont(name: string, src: string | BinaryData, opt?: LoadFontOpt) => Asset<FontData>

Load a font (any format supported by the browser, e.g. ttf, otf, woff).

since

v3000.0

// load a font from a .ttf file
loadFont("frogblock", "fonts/frogblock.ttf")

loadBitmapFont(name: string | null, src: string, gridWidth: number, gridHeight: number, options?: LoadBitmapFontOpt) => Asset<BitmapFontData>

Load a bitmap font into asset manager, with name and resource url and infomation on the layout of the bitmap.

since

v3000.0

// 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: "☺☻♥♦♣♠" })

loadShader(name: string | null, vert?: string, frag?: string) => Asset<ShaderData>

Load a shader with vertex and fragment code.

// default shaders and custom shader format
loadShader("outline",
`vec4 vert(vec2 pos, vec2 uv, vec4 color) {
    // predefined functions to get the default value by kaboom
    return def_vert();
}`,
`vec4 frag(vec2 pos, vec2 uv, vec4 color, sampler2D tex) {
    // turn everything blue-ish
    return def_frag() * vec4(0, 0, 1, 1);
}`, false)

loadShaderURL(name: string | null, vert?: string, frag?: string) => Asset<ShaderData>

Load a shader with vertex and fragment code file url.

since

v3000.0

// load only a fragment shader from URL
loadShader("outline", null, "/shaders/outline.glsl", true)

load(l: Promise<T>) => Asset<T>

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

load(new Promise((resolve, reject) => {
    // anything you want to do that stalls the game in loading state
    resolve("ok")
}))

loadProgress() => number

Get the global asset loading progress (0.0 - 1.0).

since

v3000.0

getSprite(name: string) => Asset<SpriteData> | void

Get SpriteData from name.

since

v3000.0

getSound(name: string) => Asset<SoundData> | void

Get SoundData from name.

since

v3000.0

getFont(name: string) => Asset<FontData> | void

Get FontData from name.

since

v3000.0

getBitmapFont(name: string) => Asset<BitmapFontData> | void

Get BitmapFontData from name.

since

v3000.0

getShader(name: string) => Asset<ShaderData> | void

Get ShaderData from name.

since

v3000.0

getAsset(name: string) => Asset<any> | void

Get custom data from name.

since

v3000.0

type

Asset

loaded: boolean

loaded(data: D) => Asset<D>

data: D | null

error: Error | null

onLoad(action: (data: D) => void) => Asset<D>

onError(action: (err: Error) => void) => Asset<D>

onFinish(action: () => void) => Asset<D>

then(action: (data: D) => void) => Asset<D>

catch(action: (err: Error) => void) => Asset<D>

finally(action: () => void) => Asset<D>

type

SpriteData

tex: Texture

frames: Quad[]

anims: SpriteAnims

width: number

since

v3000.2

height: number

since

v3000.2

slice9: NineSlice | null

from(src: LoadSpriteSrc, opt?: LoadSpriteOpt) => Promise<SpriteData>

fromImage(data: ImageSource, opt?: LoadSpriteOpt) => SpriteData

fromURL(url: string, opt?: LoadSpriteOpt) => Promise<SpriteData>

type

SoundData

buf: AudioBuffer

fromArrayBuffer(buf: ArrayBuffer) => Promise<SoundData>

fromURL(url: string) => Promise<SoundData>

Info

width() => number

Get the width of game.

height() => number

Get the height of game.

center() => Vec2

Get the center point of view.

// add bean to the center of the screen
add([
    sprite("bean"),
    pos(center()),
    // ...
])

dt() => number

Get the delta time since last frame.

// rotate bean 100 deg per second
bean.onUpdate(() => {
    bean.angle += 100 * dt()
})

time() => number

Get the total time since beginning.

isFocused() => boolean

If the game canvas is currently focused.

since

v2000.1

isTouchscreen() => boolean

Is currently on a touch screen device.

since

v3000.0

mousePos() => Vec2

Get current mouse position (without camera transform).

mouseDeltaPos() => Vec2

How much mouse moved last frame.

isKeyDown(k?: Key) => boolean

If certain key is currently down.

since

v2000.1

// equivalent to the calling bean.move() in an onKeyDown("left")
onUpdate(() => {
    if (isKeyDown("left")) {
        bean.move(-SPEED, 0)
    }
})

isKeyPressed(k?: Key) => boolean

If certain key is just pressed last frame.

since

v2000.1

isKeyPressedRepeat(k?: Key) => boolean

If certain key is just pressed last frame (also fires repeatedly when the key is being held down).

since

v2000.1

isKeyReleased(k?: Key) => boolean

If certain key is just released last frame.

since

v2000.1

isMouseDown(button?: MouseButton) => boolean

If a mouse button is currently down.

since

v2000.1

isMousePressed(button?: MouseButton) => boolean

If a mouse button is just clicked last frame.

since

v2000.1

isMouseReleased(button?: MouseButton) => boolean

If a mouse button is just released last frame.

since

v2000.1

isMouseMoved() => boolean

If mouse moved last frame.

since

v2000.1

isGamepadButtonPressed(btn?: GamepadButton) => boolean

If a gamepad button is just pressed last frame

since

v3000.0

isGamepadButtonDown(btn?: GamepadButton) => boolean

If a gamepad button is currently held down.

since

v3000.0

isGamepadButtonReleased(btn?: GamepadButton) => boolean

If a gamepad button is just released last frame.

since

v3000.0

getGamepadStick(stick: GamepadStick) => Vec2

Get stick axis values from a gamepad.

since

v3000.2

charInputted() => string[]

List of characters inputted since last frame.

since

v3000.0

shake(intensity: number)

Camera shake.

// shake intensively when bean collides with a "bomb"
bean.onCollide("bomb", () => {
    shake(120)
})

camPos(pos: Vec2) => Vec2

Get / set camera position.

// camera follows player
player.onUpdate(() => {
    camPos(player.pos)
})

camPos(x: number, y: number) => Vec2

camPos() => Vec2

camScale(scale: Vec2) => Vec2

Get / set camera scale.

camScale(x: number, y: number) => Vec2

camScale() => Vec2

camRot(angle?: number) => number

Get / set camera rotation.

toScreen(p: Vec2) => Vec2

Transform a point from world position to screen position.

toWorld(p: Vec2) => Vec2

Transform a point from screen position to world position.

setGravity(g: number)

Set gravity.

getGravity() => number

Get gravity.

setBackground(color: Color, alpha?: number)

Set background color.

setBackground(r: number, g: number, b: number, alpha?: number)

getBackground() => Color

Get background color.

getGamepads() => KGamePad[]

Get connected gamepads.

since

v3000.0

setCursor(style: Cursor)

Set cursor style (check Cursor type for possible values). Cursor will be reset to "default" every frame so use this in an per-frame action.

since

v3000.0

button.onHover((c) => {
    setCursor("pointer")
})

getCursor() => Cursor

Get current cursor style.

since

v3000.0 ```

setCursorLocked(locked: boolean)

Lock / unlock cursor. Note that you cannot lock cursor within 1 second after user unlocking the cursor with the default unlock gesture (typically the esc key) due to browser policy.

since

v3000.0

isCursorLocked() => boolean

Get if cursor is currently locked.

since

v3000.0 ```

setFullscreen(f?: boolean)

Enter / exit fullscreen mode. (note: mouse position is not working in fullscreen mode at the moment)

// toggle fullscreen mode on "f"
onKeyPress("f", (c) => {
    setFullscreen(!isFullscreen())
})

isFullscreen() => boolean

If currently in fullscreen mode.

Timer

wait(n: number, action?: () => void) => TimerController

Run the callback after n seconds.

// 3 seconds until explosion! Runnn!
wait(3, () => {
    explode()
})

// wait() returns a PromiseLike that can be used with await
await wait(1)

loop(t: number, action: () => void) => EventController

Run the callback every n seconds.

// spawn a butterfly at random position every 1 second
loop(1, () => {
    add([
        sprite("butterfly"),
        pos(rand(vec2(width(), height()))),
        area(),
        "friend",
    ])
})

Audio

play(src: string | SoundData | Asset<SoundData> | MusicData | Asset<MusicData>, options?: AudioPlayOpt) => AudioPlay

Play a piece of audio.

returns

A control handle.

// 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

burp(options?: AudioPlayOpt) => AudioPlay

Yep.

volume(v?: number) => number

Sets global volume.

// makes everything quieter
volume(0.5)

audioCtx: AudioContext

Get the underlying browser AudioContext.

Math

rand() => number

Get a random number between 0 - 1.

rand(n: T) => T

Get a random value between 0 and the given value.

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

rand(a: T, b: T) => T

Get a random value between the given bound.

rand(50, 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())),
])

randi(n: number) => number

rand() but floored to integer.

randi(10) // returns 0 to 9

randi(a: number, b: number) => number

rand() but floored to integer.

randi(0, 3) // returns 0, 1, or 2

randi() => number

rand() but floored to integer.

randi() // returns either 0 or 1

randSeed(seed?: number) => number

Get / set the random number generator seed.

randSeed(Date.now())

vec2(x: number, y: number) => Vec2

Create a 2d vector.

// { x: 0, y: 0 }
vec2()

// { x: 10, y: 10 }
vec2(10)

// { x: 100, y: 80 }
vec2(100, 80)

// move to 150 degrees direction with by length 10
player.pos = pos.add(Vec2.fromAngle(150).scale(10))

vec2(p: Vec2) => Vec2

vec2(xy: number) => Vec2

vec2() => Vec2

rgb(r: number, g: number, b: number) => Color

Create a color from RGB values (0 - 255).

// update the color of the sky to light blue
sky.color = rgb(0, 128, 255)

rgb(hex: string) => Color

Create a color from hex string.

since

v3000.2

sky.color = rgb("#ef6360")

rgb() => Color

Same as rgb(255, 255, 255).

hsl2rgb(hue: number, saturation: number, lightness: number) => Color

Convert HSL color (all values in 0.0 - 1.0 range) to RGB color.

since

v2000.1

// animate rainbow color
onUpdate("rainbow", (obj) => {
    obj.color = hsl2rgb(wave(0, 1, time()), 0.6, 0.6)
})

quad(x: number, y: number, w: number, h: number) => Quad

Rectangle area (0.0 - 1.0).

choose(lst: T[]) => T

Choose a random item from a list.

// decide the best fruit randomly
const bestFruit = choose(["apple", "banana", "pear", "watermelon"])

chance(p: number) => boolean

rand(1) <= p

// every frame all objs with tag "unlucky" have 50% chance die
onUpdate("unlucky", (o) => {
    if (chance(0.5)) {
        destroy(o)
    }
})

lerp(from: V, to: V, t: number) => V

Linear interpolation.

tween(from: V, to: V, duration: number, setValue: (value: V) => void, easeFunc?: (t: number) => number) => TweenController

Tweeeeeeeening!

since

v3000.0

// tween bean to mouse position
tween(bean.pos, mousePos(), 1, (p) => bean.pos = p, easings.easeOutBounce)

// tween() returns a then-able that can be used with await
await tween(bean.opacity, 1, 0.5, (val) => bean.opacity = val, easings.easeOutQuad)

easings: Record<EaseFuncs, EaseFunc>

A collection of easing functions for tweening.

since

v3000.0

map(v: number, l1: number, h1: number, l2: number, h2: number) => number

Map a value from one range to another range.

mapc(v: number, l1: number, h1: number, l2: number, h2: number) => number

Map a value from one range to another range, and clamp to the dest range.

wave(lo: number, hi: number, t: number, func?: (x: number) => number) => number

Interpolate between 2 values (Optionally takes a custom periodic function, which default to Math.sin).

// bounce color between 2 values as time goes on
onUpdate("colorful", (c) => {
    c.color.r = wave(0, 255, time())
    c.color.g = wave(0, 255, time() + 1)
    c.color.b = wave(0, 255, time() + 2)
})

deg2rad(deg: number) => number

Convert degrees to radians.

rad2deg(rad: number) => number

Convert radians to degrees.

clamp(n: number, min: number, max: number) => number

Return a value clamped to an inclusive range of min and max.

evaluateBezier(pt1: Vec2, pt2: Vec2, pt3: Vec2, pt4: Vec2, t: number) => Vec2

Evaluate the Bezier at the given t

testLinePoint(l: Line, pt: Vec2) => boolean

Check if a line and a point intersect.

testLineLine(l1: Line, l2: Line) => Vec2 | null

Check if 2 lines intersects, if yes returns the intersection point.

testLineCircle(l: Line, circle: Circle) => boolean

Check if a line and a circle intersect.

testRectRect(r1: Rect, r2: Rect) => boolean

Check if 2 rectangle overlaps.

testRectLine(r: Rect, l: Line) => boolean

Check if a line and a rectangle overlaps.

testRectPoint(r: Rect, pt: Point) => boolean

Check if a point is inside a rectangle.

testCirclePolygon(c: Circle, p: Polygon) => boolean

Check if a circle and polygon intersect linewise.

type

Line

p1: Vec2

p2: Vec2

transform(m: Mat4) => Line

bbox() => Rect

area() => number

clone() => Line

collides(shape: ShapeType) => boolean

contains(point: Vec2) => boolean

raycast(origin: Vec2, direction: Vec2) => RaycastResult

type

Rect

pos: Vec2

width: number

height: number

fromPoints(p1: Vec2, p2: Vec2) => Rect

center() => Vec2

points() => unknown

transform(m: Mat4) => Polygon

bbox() => Rect

area() => number

clone() => Rect

distToPoint(p: Vec2) => number

sdistToPoint(p: Vec2) => number

collides(shape: ShapeType) => boolean

contains(point: Vec2) => boolean

raycast(origin: Vec2, direction: Vec2) => RaycastResult

type

Circle

center: Vec2

radius: number

transform(m: Mat4) => Ellipse

bbox() => Rect

area() => number

clone() => Circle

collides(shape: ShapeType) => boolean

contains(point: Vec2) => boolean

raycast(origin: Vec2, direction: Vec2) => RaycastResult

type

Ellipse

center: Vec2

radiusX: number

radiusY: number

transform(m: Mat4) => Ellipse

bbox() => Rect

area() => number

clone() => Ellipse

collides(shape: ShapeType) => boolean

contains(point: Vec2) => boolean

raycast(origin: Vec2, direction: Vec2) => RaycastResult

type

Polygon

pts: Vec2[]

transform(m: Mat4) => Polygon

bbox() => Rect

area() => number

clone() => Polygon

collides(shape: ShapeType) => boolean

contains(point: Vec2) => boolean

raycast(origin: Vec2, direction: Vec2) => RaycastResult

type

Vec2

x: number

y: number

LEFT: Vec2

RIGHT: Vec2

UP: Vec2

DOWN: Vec2

fromAngle(deg: number) => Vec2

clone() => Vec2

add(p: Vec2) => Vec2

Returns the addition with another vector.

add(x: number, y: number) => Vec2

sub(p: Vec2) => Vec2

Returns the subtraction with another vector.

sub(x: number, y: number) => Vec2

scale(p: Vec2) => Vec2

Scale by another vector, or a single number.

scale(s: number) => Vec2

scale(sx: number, sy: number) => Vec2

dot(p: Vec2) => number

Get the dot product with another vector.

cross(p2: Vec2) => number

Get the cross product with another vector.

since

v3000.0

dist(p: Vec2) => number

Get distance between another vector.

sdist(p: Vec2) => number

Get squared distance between another vector.

since

v3000.0

len() => number

slen() => number

Get squared length of a vector.

since

v3000.0

unit() => Vec2

Get the unit vector (length of 1).

normal() => Vec2

Get the perpendicular vector.

reflect(normal: Vec2) => Vec2

Get the reflection of a vector with a normal.

since

v3000.0

project(on: Vec2) => Vec2

Get the projection of a vector onto another vector.

since

v3000.0

reject(on: Vec2) => Vec2

Get the rejection of a vector onto another vector.

since

v3000.0

angle(p: Vec2) => number

Get the angle of the vector from p towards this.

angleBetween(args: ...) => number

Get the angle between this vector and another vector.

since

v3000.0

lerp(p: Vec2, t: number) => Vec2

Linear interpolate to a destination vector (for positions).

slerp(p: Vec2, t: number) => Vec2

Spherical linear interpolate to a destination vector (for rotations).

since

v3000.0

isZero() => boolean

If both x and y is 0.

since

v3000.0

toFixed(n: number) => Vec2

To n precision floating point.

transform(n: Mat4) => Vec2

Multiply by a Mat4.

since

v3000.0

bbox() => Rect

eq(p: Vec2) => boolean

type

Color

0-255 RGBA color.

r: number

Red (0-255).

g: number

Green (0-255).

b: number

Blue (0-255).

fromArray(arr: number[]) => Color

fromHSL(h: number, s: number, l: number) => Color

fromHex(hex: number | string) => Color

Create color from hex string or literal.

since

v3000.0

Color.fromHex(0xfcef8d)
Color.fromHex("#5ba675")
Color.fromHex("d46eb3")

RED: Color

GREEN: Color

BLUE: Color

YELLOW: Color

MAGENTA: Color

CYAN: Color

WHITE: Color

BLACK: Color

clone() => Color

lighten(n: number) => Color

Lighten the color (adds RGB by n).

darken(n: number) => Color

Darkens the color (subtracts RGB by n).

invert() => Color

mult(other: Color) => Color

lerp(dest: Color, t: number) => Color

Linear interpolate to a destination color.

since

v3000.0

eq(c: Color) => boolean

toHSL() => unknown

Convert color into HSL format.

since

v3000.2

toHex() => string

Return the hex string of color.

since

v3000.0

type

Mat4

m: number[]

translate(p: Vec2) => Mat4

scale(s: Vec2) => Mat4

rotateX(a: number) => Mat4

rotateY(a: number) => Mat4

rotateZ(a: number) => Mat4

clone() => Mat4

mult(other: Mat4) => Mat4

multVec2(p: Vec2) => Vec2

rotate(a: number) => Mat4

getTranslation() => Vec2

getScale() => Vec2

getRotation() => number

getSkew() => Vec2

invert() => Mat4

type

Quad

x: number

y: number

w: number

h: number

scale(q: Quad) => Quad

pos() => Vec2

clone() => Quad

eq(q: Quad) => boolean

type

RNG

seed: number

gen() => number

genNumber(a: number, b: number) => number

genVec2(a: Vec2, b?: Vec2) => Vec2

genColor(a: Color, b: Color) => Color

genAny(args: ...) => T

Scene

scene(id: SceneName, def: SceneDef)

Define a scene.

go(id: SceneName, args: ...)

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

Level

addLevel(map: string[], options: LevelOpt) => GameObj

Construct a level based on symbols.

addLevel([
    "                          $",
    "                          $",
    "           $$         =   $",
    "  %      ====         =   $",
    "                      =    ",
    "       ^^      = >    =   &",
    "===========================",
], {
    // define the size of tile block
    tileWidth: 32,
    tileHeight: 32,
    // define what each symbol means, by a function returning a component list (what will be passed to add())
    tiles: {
        "=": () => [
            sprite("floor"),
            area(),
            solid(),
        ],
        "$": () => [
            sprite("coin"),
            area(),
            pos(0, -9),
        ],
        "^": () => [
            sprite("spike"),
            area(),
            "danger",
        ],
    }
})

Data

getData(key: string, def?: T) => T

Get data from local storage, if not present can set to a default value.

setData(key: string, data: any)

Set data from local storage.

Draw

drawSprite(options: DrawSpriteOpt)

Draw a sprite.

drawSprite({
    sprite: "bean",
    pos: vec2(100, 200),
    frame: 3,
})

drawText(options: DrawTextOpt)

Draw a piece of text.

drawText({
    text: "oh hi",
    size: 48,
    font: "sans-serif",
    width: 120,
    pos: vec2(100, 200),
    color: rgb(0, 0, 255),
})

drawRect(options: DrawRectOpt)

Draw a rectangle.

drawRect({
    width: 120,
    height: 240,
    pos: vec2(20, 20),
    color: YELLOW,
    outline: { color: BLACK, width: 4 },
})

drawLine(options: DrawLineOpt)

Draw a line.

drawLine({
    p1: vec2(0),
    p2: mousePos(),
    width: 4,
    color: rgb(0, 0, 255),
})

drawLines(options: DrawLinesOpt)

Draw lines.

drawLines({
    pts: [ vec2(0), vec2(0, height()), mousePos() ],
    width: 4,
    pos: vec2(100, 200),
    color: rgb(0, 0, 255),
})

drawCurve(curve: (t: number) => Vec2, opt: DrawCurveOpt)

Draw a curve.

drawCurve(t => evaluateBezier(a, b, c, d, t)
 {
    width: 2,
    color: rgb(0, 0, 255),
})

drawBezier(opt: DrawBezierOpt)

Draw a cubic Bezier curve.

drawBezier({
     pt1: vec2(100, 100),
     pt2: vec2(200, 100),
     pt3: vec2(200, 200),
     pt4: vec2(100, 200),
     width: 2,
     color: GREEN
})

drawTriangle(options: DrawTriangleOpt)

Draw a triangle.

drawTriangle({
    p1: vec2(0),
    p2: vec2(0, height()),
    p3: mousePos(),
    pos: vec2(100, 200),
    color: rgb(0, 0, 255),
})

drawCircle(options: DrawCircleOpt)

Draw a circle.

drawCircle({
    pos: vec2(100, 200),
    radius: 120,
    color: rgb(255, 255, 0),
})

drawEllipse(options: DrawEllipseOpt)

Draw an ellipse.

drawEllipse({
    pos: vec2(100, 200),
    radiusX: 120,
    radiusY: 120,
    color: rgb(255, 255, 0),
})

drawPolygon(options: DrawPolygonOpt)

Draw a convex polygon from a list of vertices.

drawPolygon({
    pts: [
        vec2(-12),
        vec2(0, 16),
        vec2(12, 4),
        vec2(0, -2),
        vec2(-8),
    ],
    pos: vec2(100, 200),
    color: rgb(0, 0, 255),
})

drawUVQuad(options: DrawUVQuadOpt)

Draw a rectangle with UV data.

drawFormattedText(text: FormattedText)

Draw a piece of formatted text from formatText().

since

v2000.2

// text background
const txt = formatText({
    text: "oh hi",
})

drawRect({
    width: txt.width,
    height: txt.height,
})

drawFormattedText(txt)

drawMasked(content: () => void, mask: () => void)

Whatever drawn in content will only be drawn if it's also drawn in mask (mask will not be rendered).

since

v3000.0

drawSubtracted(content: () => void, mask: () => void)

Subtract whatever drawn in content by whatever drawn in mask (mask will not be rendered).

since

v3000.0

pushTransform()

Push current transform matrix to the transform stack.

pushTransform()

// these transforms will affect every render until popTransform()
pushTranslate(120, 200)
pushRotate(time() * 120)
pushScale(6)

drawSprite("bean")
drawCircle(vec2(0), 120)

// restore the transformation stack to when last pushed
popTransform()

popTransform()

Pop the topmost transform matrix from the transform stack.

pushTranslate(x: number, y: number)

Translate all subsequent draws.

pushTranslate(100, 100)

// this will be drawn at (120, 120)
drawText({
    text: "oh hi",
    pos: vec2(20, 20),
})

pushTranslate(p: Vec2)

pushScale(x: number, y: number)

Scale all subsequent draws.

pushScale(s: number)

pushScale(s: Vec2)

pushRotate(angle: number)

Rotate all subsequent draws.

pushMatrix(mat: Mat4)

Apply a transform matrix, ignore all prior transforms.

since

v3000.0

usePostEffect(name: string, uniform?: Uniform | (() => Uniform))

Apply a post process effect from a shader name.

since

v3000.0

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")

formatText(options: DrawTextOpt) => FormattedText

Format a piece of text without drawing (for getting dimensions, etc).

since

v2000.2

// text background
const txt = formatText({
    text: "oh hi",
})

drawRect({
    width: txt.width,
    height: txt.height,
})

drawFormattedText(txt)

makeCanvas(w: number, h: number) => Canvas

Create a canvas to draw stuff offscreen.

since

v3000.2

Debug

debug: Debug

// pause the whole game
debug.paused = true

// enter inspect mode
debug.inspect = true

Misc

plug(plugin: KaboomPlugin<T>) => unknown

Import a plugin.

screenshot() => string

Take a screenshot and get the dataurl of the image.

returns

The dataURL of the image.

download(filename: string, dataurl: string)

Trigger a file download from a url.

since

v3000.0

downloadText(filename: string, text: string)

Trigger a text file download.

since

v3000.0

downloadJSON(filename: string, data: any)

Trigger a json download from a .

since

v3000.0

downloadBlob(filename: string, blob: Blob)

Trigger a file download from a blob.

since

v3000.0

record(frameRate?: number) => Recording

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

returns

A control handle.

since

v2000.1

addKaboom(pos: Vec2, opt?: BoomOpt) => GameObj

Add an explosion

ASCII_CHARS: string

All chars in ASCII.

LEFT: Vec2

Left directional vector vec2(-1, 0).

RIGHT: Vec2

Right directional vector vec2(1, 0).

UP: Vec2

Up directional vector vec2(0, -1).

DOWN: Vec2

Down directional vector vec2(0, 1).

RED: Color

GREEN: Color

BLUE: Color

YELLOW: Color

MAGENTA: Color

CYAN: Color

WHITE: Color

BLACK: Color

canvas: HTMLCanvasElement

The canvas DOM kaboom is currently using.

quit: () => void

End everything.

type

Event

add(action: (args: ...) => void) => EventController

addOnce(action: (args: ...) => void) => EventController

next() => Promise<Args>

trigger(args: ...)

numListeners() => number

clear()

type

EventHandler

on(name: Name, action: (args: ...) => void) => EventController

onOnce(name: Name, action: (args: ...) => void) => EventController

next(name: Name) => Promise<unknown>

trigger(name: Name, args: ...)

remove(name: Name)

clear()

numListeners(name: Name) => number

type

EventController

paused: boolean

If the event handler is paused.

cancel: () => void

Cancel the event handler.

join(events: EventController[]) => EventController

VERSION: string

Current Kaboom library version.

since

v3000.0

type

Tag

string

type

type

type

type

Expand<UnionToIntersection<Defined<T>>>

type

MergeComps

Omit<MergeObj<T>, unknown>

type

MergePlugins

MergeObj<ReturnType<T[number]>>

type

CompList

Array<T | Tag>

type

PluginList

Array<T | KaboomPlugin<any>>

type

Key

"f1" | "f2" | "f3" | "f4" | "f5" | "f6" | "f7" | "f8" | "f9" | "f10" | "f11" | "f12" | "`" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "0" | "-" | "=" | "q" | "w" | "e" | "r" | "t" | "y" | "u" | "i" | "o" | "p" | "[" | "]" | "\" | "a" | "s" | "d" | "f" | "g" | "h" | "j" | "k" | "l" | ";" | "'" | "z" | "x" | "c" | "v" | "b" | "n" | "m" | "," | "." | "/" | "escape" | "backspace" | "enter" | "tab" | "control" | "alt" | "meta" | "space" | " " | "left" | "right" | "up" | "down" | "shift"

type

MouseButton

"left" | "right" | "middle" | "back" | "forward"

type

GamepadButton

type

GamepadStick

"left" | "right"

type

GamepadDef

buttons: Record<string, GamepadButton>

sticks: Partial<Record<GamepadStick,

x: number

y: number

type

KGamePad

index: number

The order of the gamepad in the gamepad list.

isPressed(b: GamepadButton) => boolean

If certain button is pressed.

isDown(b: GamepadButton) => boolean

If certain button is held down.

isReleased(b: GamepadButton) => boolean

If certain button is released.

getStick(stick: GamepadStick) => Vec2

Get the value of a stick.

type

GameObjInspect

Record<Tag, string | null>

type

KaboomOpt

Kaboom configurations.

width?: number

Width of game.

height?: number

Height of game.

scale?: number

Pixel scale / size.

stretch?: boolean

If stretch canvas to container when width and height is specified

letterbox?: boolean

When stretching if keep aspect ratio and leave black bars on remaining spaces.

debug?: boolean

If register debug buttons (default true)

font?: string

Default font (defaults to "monospace").

pixelDensity?: number

Device pixel scale (defaults to window.devicePixelRatio, high pixel density will hurt performance).

since

v3000.0

crisp?: boolean

Disable antialias and enable sharp pixel display.

canvas?: HTMLCanvasElement

The canvas DOM element to use. If empty will create one.

root?: HTMLElement

The container DOM element to insert the canvas if created. Defaults to document.body.

background?: number[] | string

Background color. E.g. [ 0, 0, 255 ] for solid blue background, or [ 0, 0, 0, 0 ] for transparent background. Accepts RGB value array or string hex codes.

texFilter?: TexFilter

Default texture filter.

logMax?: number

How many log messages can there be on one screen (default 8).

logTime?: number

How many seconds log messages stay on screen (default 4).

since

v3000.1

hashGridSize?: number

Size of the spatial hash grid for collision detection (default 64).

since

v3000.0

touchToMouse?: boolean

If translate touch events as mouse clicks (default true).

loadingScreen?: boolean

If kaboom should render a default loading screen when assets are not fully ready (default true).

since

v3000.0

backgroundAudio?: boolean

If pause audio when tab is not active (default false).

since

v3000.0

gamepads?: Record<string, GamepadDef>

Custom gamepad definitions (see gamepad.json for reference of the format).

since

v3000.0

maxFPS?: number

Limit framerate to an amount per second.

since

v3000.0

focus?: boolean

If focus on the canvas on start (default true).

since

v3000.2

global?: boolean

If import all kaboom functions to global (default true).

plugins?: T

List of plugins to import.

burp?: boolean

Enter burp mode.

type

KaboomPlugin

(k: KaboomCtx) => T | ((args: ...) => (k: KaboomCtx) => T)

type

GameObjRaw

Base interface of all game objects.

add(comps?: CompList<T> | GameObj<T>) => GameObj<T>

Add a child.

since

v3000.0

readd(obj: GameObj<T>) => GameObj<T>

Remove and re-add the game obj, without triggering add / destroy events.

remove(obj: GameObj)

Remove a child.

since

v3000.0

removeAll(tag: Tag)

Remove all children with a certain tag.

since

v3000.0

removeAll()

Remove all children.

since

v3000.0

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

Get a list of all game objs with certain tag.

since

v3000.0

children: GameObj[]

Get all children game objects.

since

v3000.0

update()

Update this game object and all children game objects.

since

v3000.0

draw()

Draw this game object and all children game objects.

since

v3000.0

drawInspect: () => void

Draw debug info in inspect mode

since

v3000.0

clearEvents: () => void

is(tag: Tag | Tag[]) => boolean

If there's certain tag(s) on the game obj.

use(comp: Comp | Tag)

Add a component or tag.

unuse(comp: Tag)

Remove a tag or a component with its id.

on(event: string, action: (args: ...) => void) => EventController

trigger(event: string, args: ...)

Trigger an event.

destroy()

Remove the game obj from scene.

c(id: Tag) => Comp | unknown

Get state for a specific comp.

inspect() => GameObjInspect

Gather debug info of all comps.

onAdd(action: () => void) => EventController

onUpdate(action: () => void) => EventController

since

v2000.1

onDraw(action: () => void) => EventController

Register an event that runs every frame as long as the game obj exists (this is the same as `onUpdate()`, but all draw events are run after all update events).

since

v2000.1

onDestroy(action: () => void) => EventController

since

v2000.1

exists() => boolean

If game obj is attached to the scene graph.

isAncestorOf(obj: GameObj) => boolean

Check if is an ancestor (recursive parent) of another game object

since

v3000.0

transform: Mat4

Calculated transform matrix of a game object.

since

v3000.0

hidden: boolean

If draw the game obj (run "draw" event or not).

paused: boolean

If update the game obj (run "update" event or not).

id: GameObjID | null

A unique number ID for each game object.

canvas: FrameBuffer | null

The canvas to draw this game object on