Kaboom

// start the game
kaboom()

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

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: "sinko",
    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

Game Object is the basic unit of entity in a kaboom world. Everything is a game object, the player, a butterfly, a tree, or even a piece of text.

This section contains functions to add, remove, and access game objects. To actually make them do stuff, check out the Components section.

add(comps: CompList<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),
    doubleJump(),
    // 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)
})

get(tag?: Tag | Tag[]) => 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")

// without args returns all current objs in the game
const allObjs = get()

every(tag: Tag | Tag[], action: (obj: GameObj) => T)

Run callback on every game obj with certain tag.

// Destroy all game obj with tag "fruit"
every("fruit", destroy)

every(action: (obj: GameObj) => T)

Run callback on every game obj.

every((obj) => {})

revery(tag: Tag | Tag[], action: (obj: GameObj) => T)

Run callback on every game obj with certain tag in reverse order.

revery(action: (obj: GameObj) => T)

Run callback on every game obj in reverse order.

readd(obj: GameObj) => GameObj

Remove and re-add the game obj.

// mainly useful when you want to make something to draw on top
readd(froggy)

destroy(obj: GameObj)

Remove the game obj.

// every time froggy collides with anything with tag "fruit", remove it
froggy.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

Kaboom uses a flexible component system which values composition over inheritence. Each game object is composed from a list of components, each component gives the game object certain capabilities.

Use add() to assemble the components together into a Game Object and add them to the world.

const player = add([
    sprite("froggy"),
    pos(100, 200),
    area(),
    body(),
])

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

// .moveTo() is provided by pos() component
player.moveTo(120, 80)

// .onCollide() is provided by the area() component
player.onCollide("enemy", (enemy) => {
    destroy(enemy)
    addExplosion()
})

To see what methods and properties a component offers, click on the type that the component function returns, e.g. PosComp, which will open a panel showing all the properties and methods it'd give the game object.

To learn more about how components work or how to make your own component, check out the component demo.

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

Position

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

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

rotate(a: number) => RotateComp

Rotation (in degrees). (This doesn't work with the area() collider yet)

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

Sets color (rgb 0-255).

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

color(c: Color) => 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("froggy"),
])

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

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

// manually setting a frame
froggy.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: "sink", // there're 4 built-in fonts: "apl386", "apl386o", "sink", and "sinko"
    }),
])

rect(w: number, h: number) => 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("froggy"),
    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
    origin("center"),
])

add([
    sprite("froggy"),
    // Define custom area with width and height
    area({ width: 20, height: 40. }),
])

origin(o: Origin | Vec2) => OriginComp

Origin point for render (default "topleft").

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

layer(l: string) => LayerComp

Which layer this object belongs to.

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

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

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

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

solid() => SolidComp

Make other objects cannot move pass. Requires "area" comp.

add([
    sprite("rock"),
    pos(30, 120),
    area(),
    solid(),
])

// only do collision checking when a block is close to player for performance
onUpdate("block", (b) => {
    b.solid = b.pos.dist(player.pos) <= 64
})

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

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

// enemy throwing feces at player
const projectile = add([
    sprite("feces"),
    pos(enemy.pos),
    area(),
    move(player.pos.angle(enemy.pos), 1200),
    cleanup(),
])

outview(opt?: OutviewCompOpt) => OutviewComp

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

since

v2000.2

add([
    pos(1200, 80),
    outview({ hide: true, pause: true }),
])

cleanup(opt?: CleanupCompOpt) => CleanupComp

destroy() the object if it goes out of screen. Optionally specify the amount of time it has to be off-screen before removal.

// destroy when it leaves screen
const bullet = add([
    pos(80, 80),
    move(LEFT, 960),
    cleanup(),
])

cleanup(delay?: number) => CleanupComp

deprecated

v2000.2 Use cleanup() with optional CleanupCompOpt instead of single time argument.

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

Follow another game obj's position.

shader(id: string) => ShaderComp

Custom shader.

timer(n?: number, action?: () => void) => TimerComp

Run certain action after some time.

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() => 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) => 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) => LifespanComp

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

Events

Kaboom uses events extensively for a flat and declarative code style.

For example, it's most common for a game to have something run every frame which can be achieved by adding an onUpdate() event

// Make something always move to the right
onUpdate(() => {
    banana.move(320, 0)
})

Events are also used for input handlers.

onKeyPress("space", () => {
    player.jump()
})

Every function with the on prefix is an event register function that takes a callback function as the last argument, and should return a function that cancels the event listener.

Note that you should never nest one event handler function inside another or it might cause severe performance punishment.

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

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

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

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) => EventCanceller

since

v2000.1

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

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

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) => EventCanceller

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

onLoad(action: () => void)

since

v2000.1

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

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

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

since

v2000.1

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

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

since

v2000.1

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

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

since

v2000.1

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

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

since

v2000.1

onKeyDown(k: Key | Key[], action: () => void) => EventCanceller

since

v2000.1

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

onKeyPress(k: Key | Key[], action: () => void) => EventCanceller

since

v2000.1

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

onKeyPress(action: () => void) => EventCanceller

since

v2000.1

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

onKeyPressRepeat(k: Key | Key[], action: () => void) => EventCanceller

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: () => void) => EventCanceller

onKeyRelease(k: Key | Key[], action: () => void) => EventCanceller

since

v2000.1

onKeyRelease(action: () => void) => EventCanceller

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

since

v2000.1

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

onMouseDown(action: (pos: Vec2) => void) => EventCanceller

since

v2000.1

onMouseDown(button: MouseButton, action: (pos: Vec2) => void) => EventCanceller

onMousePress(action: (pos: Vec2) => void) => EventCanceller

since

v2000.1

onMousePress(button: MouseButton, action: (pos: Vec2) => void) => EventCanceller

onMouseRelease(action: (pos: Vec2) => void) => EventCanceller

since

v2000.1

onMouseRelease(button: MouseButton, action: (pos: Vec2) => void) => EventCanceller

onMouseMove(action: (pos: Vec2) => void) => EventCanceller

since

v2000.1

onTouchStart(action: (id: TouchID, pos: Vec2) => void) => EventCanceller

since

v2000.1

onTouchMove(action: (id: TouchID, pos: Vec2) => void) => EventCanceller

since

v2000.1

onTouchEnd(action: (id: TouchID, pos: Vec2) => void) => EventCanceller

since

v2000.1

action: KaboomCtx["onUpdate"]

deprecated

v2000.1 Use onUpdate() instead

render: KaboomCtx["onDraw"]

deprecated

v2000.1 Use onDraw() instead

ready: KaboomCtx["onLoad"]

deprecated

v2000.1 Use onLoad() instead.

collides: KaboomCtx["onCollide"]

deprecated

v2000.1 Use onCollide() instead

clicks: KaboomCtx["onClick"]

deprecated

v2000.1 Use onClick() instead

hovers: KaboomCtx["onHover"]

deprecated

v2000.1 Use onHover() instead

keyDown: KaboomCtx["onKeyDown"]

deprecated

v2000.1 Use onKeyDown() instead.

keyPress: KaboomCtx["onKeyPress"]

deprecated

v2000.1 Use onKeyPress() instead.

keyPressRep: KaboomCtx["onKeyPressRepeat"]

deprecated

v2000.1 Use onKeyPressRepeat() instead.

keyRelease: KaboomCtx["onKeyRelease"]

deprecated

v2000.1 Use onKeyRelease() instead.

charInput: KaboomCtx["onCharInput"]

deprecated

v2000.1 Use onCharInput() instead.

mouseClick: KaboomCtx["onMousePress"]

deprecated

v2000.1 Use onClick() or onMousePress() instead.

mouseRelease: KaboomCtx["onMouseRelease"]

deprecated

v2000.1 Use onMouseRelease() instead.

mouseDown: KaboomCtx["onMouseDown"]

deprecated

v2000.1 Use onMouseDown() instead.

mouseMove: KaboomCtx["onMouseMove"]

deprecated

v2000.1 Use onMouseMove() instead.

touchStart: KaboomCtx["onTouchStart"]

deprecated

v2000.1 Use onTouchStart() instead.

touchMove: KaboomCtx["onTouchMove"]

deprecated

v2000.1 Use onTouchMove() instead.

touchEnd: KaboomCtx["onTouchEnd"]

deprecated

v2000.1 Use onTouchEnd() instead.

Assets

Every function with the load prefix is an async function that loads something into the asset manager, and should return a promise that resolves upon load complete.

loadRoot(path?: string) => string

Sets the root for all subsequent resource urls.

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

loadSprite(id: string | null, src: SpriteLoadSrc, options?: SpriteLoadOpt) => Promise<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("froggy", "froggy.png")
loadSprite("apple", "https://kaboomjs.com/sprites/apple.png")

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

loadSpriteAtlas(src: SpriteLoadSrc, data: SpriteAtlasData) => Promise<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: SpriteLoadSrc, url: string) => Promise<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: SpriteLoadSrc, jsonSrc: string) => Promise<SpriteData>

Load a sprite with aseprite spritesheet json.

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

loadPedit(name: string, src: string) => Promise<SpriteData>

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

Load default sprite "bean".

loadBean()

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

loadSound(id: string, src: string) => Promise<SoundData>

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

loadSound("shoot", "horse.ogg")
loadSound("shoot", "https://kaboomjs.com/sounds/scream6.mp3")

loadFont(id: string, src: string, gridWidth: number, gridHeight: number, options?: FontLoadOpt) => Promise<FontData>

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

// 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
loadFont("04b03", "fonts/04b03.png", 6, 8)

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

loadShader(name: string, vert?: string, frag?: string, isUrl?: boolean) => Promise<ShaderData>

Load a shader into asset manager with vertex and fragment code / file url.

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

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

load(l: Promise<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")
}))

Info

width() => number

Get the width of game.

height() => number

Get the height of game.

center() => Vec2

Get the center point of view.

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

dt() => number

Get the delta time since last frame.

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

time() => number

Get the total time since beginning.

isFocused() => boolean

If the game canvas is currently focused.

since

v2000.1

focus()

Focus on the game canvas.

deprecated

v2000.2

isTouch() => boolean

Is currently on a touch screen device.

mousePos() => Vec2

Get current mouse position (without camera transform).

mouseWorldPos() => Vec2

Get current mouse position (after camera transform).

deprecated

v2000.2 Use toWorld(mousePos()) instead.

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 froggy.move() in an onKeyDown("left")
onUpdate(() => {
    if (isKeyDown("left")) {
        froggy.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

shake(intensity: number)

Camera shake.

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

camPos(pos?: Vec2) => Vec2

Get / set camera position.

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

camScale(scale?: Vec2) => Vec2

Get / set camera scale.

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.

gravity(g: number) => number

Get / set gravity.

layers(list: string[], def?: string)

Define layers (the last one will be on top).

// defining 3 layers, "ui" will be drawn on top most, with default layer being "game"
layers([
    "bg",
    "game",
    "ui",
], "game")

// use layer() comp to define which layer an obj belongs to
add([
    text(score),
    layer("ui"),
    fixed(),
])

// without layer() comp it'll fall back to default layer, which is "game"
add([
    sprite("froggy"),
])

cursor(c?: Cursor) => Cursor

Get / set the cursor (css). Cursor will be reset to "default" every frame so use this in an per-frame action.

onHover("clickable", (c) => {
    cursor("pointer")
})

regCursor(c: string, draw: string | ((mpos: Vec2) => void))

Load a cursor from a sprite, or custom drawing function.

loadSprite("froggy", "sprites/froggy.png")

// use sprite as cursor
regCursor("default", "froggy")
regCursor("pointer", "apple")

fullscreen(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) => {
    fullscreen(!isFullscreen())
})

isFullscreen() => boolean

If currently in fullscreen mode.

keyIsDown: KaboomCtx["isKeyDown"]

deprecated

v2000.1 Use isKeyDown() instead.

keyIsPressed: KaboomCtx["isKeyPressed"]

deprecated

v2000.1 Use isKeyPressed() instead.

keyIsPressedRep: KaboomCtx["isKeyPressedRepeat"]

deprecated

v2000.1 Use isKeyPressedRepeat() instead.

keyIsReleased: KaboomCtx["isKeyReleased"]

deprecated

v2000.1 Use isKeyReleased() instead.

mouseIsDown: KaboomCtx["isMouseDown"]

deprecated

v2000.1 Use isMouseDown() instead.

mouseIsClicked: KaboomCtx["isMouseClicked"]

deprecated

v2000.1 Use isMouseClicked() instead.

mouseIsReleased: KaboomCtx["isMouseReleased"]

deprecated

v2000.1 Use isMouseReleased() instead.

mouseIsMoved: KaboomCtx["isMouseMoved"]

deprecated

v2000.1 Use isMouseMoved() instead.

focused() => boolean

deprecated

v2000.1 Use isFocused() instead.

Timer

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

Run the callback after n seconds.

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

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

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(id: string, 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.pause()
music.play()

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() => number

rand() but floored to integer.

randi(0, 3) // will give either 0, 1, or 2

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

RGB color (0 - 255).

// update the color of the sky to light blue
sky.color = rgb(0, 128, 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: number, to: number, t: number) => number

Linear interpolation.

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.

dir(deg: number) => Vec2

deprecated

v2000.2 Use Vec2.fromAngle instead.

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.

rng(seed: number) => RNG

Make a new random number generator.

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

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

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: Vec2) => boolean

Check if a point is inside a rectangle.

Scene

scene(id: SceneID, def: SceneDef)

Define a scene.

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

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

Level

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

Construct a level based on symbols.

addLevel([
    "                          $",
    "                          $",
    "           $$         =   $",
    "  %      ====         =   $",
    "                      =    ",
    "       ^^      = >    =   &",
    "===========================",
], {
    // define the size of each block
    width: 32,
    height: 32,
    // define what each symbol means, by a function returning a component list (what will be passed to add())
    "=": () => [
        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

Kaboom exposes all of the drawing interfaces it uses in the render components like sprite(), and you can use these drawing functions to build your own richer render components.

Also note that you have to put drawXXX() functions inside an onDraw() event or the draw() hook in component definitions which runs every frame (after the update events), or it'll be immediately cleared next frame and won't persist.

onDraw(() => {

    drawSprite({
        sprite: "froggy",
        pos: vec2(120, 160),
        angle: 90,
    })

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

})

There's also the option to use Kaboom purely as a rendering library. Check out the draw demo.

drawSprite(options: DrawSpriteOpt)

Draw a sprite.

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

drawText(options: DrawTextOpt)

Draw a piece of text.

drawText({
    text: "oh hi",
    size: 48,
    font: "sink",
    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),
})

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)

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("froggy")
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.

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)

Debug

By default kaboom starts in debug mode, which enables key bindings that calls out various debug utilities:

f1 to toggle inspect mode
f5 to take screenshot
f6 to toggle recording
f7 to slow down
f8 to pause / resume
f9 to speed up
f10 to skip frame

Some of these can be also controlled with stuff under the debug object.

If you want to turn debug mode off when releasing you game, set debug option to false in kaboom()

debug: Debug

// pause the whole game
debug.paused = true

// enter inspect mode
debug.inspect = true

Misc

plug(plugin: KaboomPlugin<T>)

Import a plugin.

screenshot() => string

Take a screenshot and get the dataurl of the image.

returns

The dataURL of the image.

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

ASCII_CHARS: string

All chars in ASCII.

CP437_CHARS: string

All chars in CP437.

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.

type

Tag

string

type

type

type

type

Expand<UnionToIntersection<Defined<T>>>

type

MergeComps

Omit<MergeObj<T>, unknown>

type

CompList

Array<T | Tag>

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" | "," | "." | "/" | "backspace" | "enter" | "tab" | "space" | " " | "left" | "right" | "up" | "down"

type

MouseButton

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

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. (note: not working properly at the moment.)

debug?: boolean

If register debug buttons (default true)

font?: string

Default font (defaults to "apl386o", with "apl386", "sink", "sinko" as other built-in options).

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[]

Background color. E.g. [ 0, 0, 255 ] for solid blue background.

inspectColor?: number[]

The color to draw collider boxes etc.

texFilter?: TexFilter

Default texture filter.

logMax?: number

How many log messages can there be on one screen.

touchToMouse?: boolean

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

global?: boolean

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

plugins?: KaboomPlugin<any>[]

List of plugins to import.

burp?: boolean

Enter burp mode.

type

KaboomPlugin

(k: KaboomCtx) => T

type

GameObjRaw

Base interface of all game objects.

_id: number | null

Internal GameObj ID.

hidden: boolean

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

paused: boolean

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

exists() => boolean

If game obj exists in scene.

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

Add a child.

since

v2000.2.0

readd(obj: GameObj) => GameObj

Remove and re-add the game obj.

since

v2000.2.0

remove(obj: GameObj)

Remove a child.

since

v2000.2.0

removeAll(tag: Tag)

Remove all children with a certain tag.

since

v2000.2.0

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

Get a list of all game objs with certain tag.

since

v2000.2.0

every(action: (obj: GameObj) => T)

Iterate through children.

since

v2000.2.0

every(tag: Tag | Tag[], action: (obj: GameObj) => T)

Iterate through children.

since

v2000.2.0

revery(action: (obj: GameObj) => T)

Iterate through children, in reverse.

since

v2000.2.0

revery(tag: Tag | Tag[], action: (obj: GameObj) => T)

Iterate through children, in reverse.

since

v2000.2.0

children: GameObj[]

Get all children game objects.

since

v2000.2.0

update()

Update this game object and all children game objects.

since

v2000.2.0

draw()

Draw this game object and all children game objects.

since

v2000.2.0

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(ev: string, action: () => void) => EventCanceller

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

Trigger an event.

destroy()

Remove the game obj from scene.

c(id: Tag) => Comp

Get state for a specific comp.

inspect() => GameObjInspect

Gather debug info of all comps.

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

since

v2000.1

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

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) => EventCanceller

since

v2000.1

action: GameObjRaw["onUpdate"]

deprecated

v2000.1 Use onUpdate() instead.

type

GameObj

GameObjRaw&MergeComps<T>

type

SceneID

string

type

SceneDef

(args: ...) => void

type

TouchID

number

type

EventCanceller

() => void

type

Recording

Screen recording control handle.

pause()

Pause the recording.

resume()

Resumes the recording.

download(filename?: string)

Stops the recording and downloads the file as mp4. Trying to resume later will lead to error.

type

SpriteAnim

number |

from: number

The starting frame.

to: number

The end frame.

loop?: boolean

If this anim should be played in loop.

pingpong?: boolean

When looping should it move back instead of go to start frame again.

speed?: number

This anim's speed in frames per second.

type

SpriteAnimPlayOpt

Sprite animation configuration when playing.

loop?: boolean

If this anim should be played in loop.

pingpong?: boolean

When looping should it move back instead of go to start frame again.

speed?: number

This anim's speed in frames per second.

onEnd?: () => void

Runs when this animation ends.

type

SpriteAnims

Record<string, SpriteAnim>

type

SpriteLoadOpt

Sprite loading configuration.

sliceX?: number

sliceY?: number

anims?: SpriteAnims

filter?: TexFilter

wrap?: TexWrap

type

SpriteAtlasData

Record<string, SpriteAtlasEntry>

type

SpriteAtlasEntry

A sprite in a sprite atlas.

x: number

X position of the top left corner.

y: number

Y position of the top left corner.

width: number

Sprite area width.

height: number

Sprite area height.

sliceX?: number

If the defined area contains multiple sprites, how many frames are in the area hozizontally.

sliceY?: number

If the defined area contains multiple sprites, how many frames are in the area vertically.

anims?: SpriteAnims

Animation configuration.

type

SpriteLoadSrc

string | GfxTexData

type

SpriteData

tex: GfxTexture

frames: Quad[]

anims: SpriteAnims

filter?: TexFilter

wrap?: TexWrap

type

FontLoadOpt

chars?: string

filter?: TexFilter

wrap?: TexWrap

type

SoundData

buf: AudioBuffer

type

FontData

GfxFont

type

ShaderData

GfxShader

type

AudioPlayOpt

Audio play configurations.

loop?: boolean

If audio should be played again from start when its ended.

volume?: number

Volume of audio. 1.0 means full volume, 0.5 means half volume.

speed?: number

Playback speed. 1.0 means normal playback speed, 2.0 means twice as fast.

detune?: number

Detune the sound. Every 100 means a semitone.

// play a random note in the octave
play("noteC", {
    detune: randi(0, 12) * 100,
})

seek?: number

The start time, in seconds.

type

AudioPlay

play(seek?: number)

Play the sound. Optionally pass in the time where it starts.

stop()

Stop the sound.

pause()

Pause the sound.

isPaused() => boolean

If the sound is paused.

since

v2000.1

isStopped() => boolean

If the sound is stopped or ended.

since

v2000.1

speed(s?: number) => number

Change the playback speed of the sound. 1.0 means normal playback speed, 2.0 means twice as fast.

detune(d?: number) => number

Detune the sound. Every 100 means a semitone.

// tune down a semitone
music.detune(-100)

// tune up an octave
music.detune(1200)

volume(v?: number) => number

Change the volume of the sound. 1.0 means full volume, 0.5 means half volume.

time() => number

The current playing time.

duration() => number

The total duration.

loop()

Set audio to play in loop.

unloop()

Set audio to not play in loop.

paused() => boolean

deprecated

v2000.1 Use isPaused() instead.

stopped() => boolean

deprecated

v2000.1 Use isStopped() instead.

type

GfxShader

bind()

unbind()

send(uniform: Uniform)

type

GfxTexture

width: number

height: number

bind()

unbind()

type

GfxTexData

HTMLImageElement | HTMLCanvasElement | ImageData | ImageBitmap

type

GfxFont

tex: GfxTexture

map: Record<string, Vec2>

qw: number

The quad width of each character.

qh: number

type

Vertex

pos: Vec3

uv: Vec2

color: Color

opacity: number

type

TexFilter

"nearest" | "linear"

type

TexWrap

"repeat" | "clampToEdge"

type

RenderProps

Common render properties.

pos?: Vec2

scale?: Vec2 | number

angle?: number

color?: Color

opacity?: number

fixed?: boolean

shader?: GfxShader

uniform?: Uniform

type

DrawSpriteOpt

RenderProps&

sprite: string | SpriteData

The sprite name in the asset manager, or the raw sprite data.

frame?: number

If the sprite is loaded with multiple frames, or sliced, use the frame option to specify which frame to draw.

width?: number

Width of sprite. If `height` is not specified it'll stretch with aspect ratio. If `tiled` is set to true it'll tiled to the specified width horizontally.

height?: number

Height of sprite. If `width` is not specified it'll stretch with aspect ratio. If `tiled` is set to true it'll tiled to the specified width vertically.

tiled?: boolean

When set to true, `width` and `height` will not scale the sprite but instead render multiple tiled copies of them until the specified width and height. Useful for background texture pattern etc.

flipX?: boolean

If flip the texture horizontally.

flipY?: boolean

If flip the texture vertically.

quad?: Quad

The sub-area to render from the texture, by default it'll render the whole `quad(0, 0, 1, 1)`

origin?: Origin | Vec2

The origin point, or the pivot point. Default to "topleft".

type

DrawUVQuadOpt

RenderProps&

width: number

Width of the UV quad.

height: number

Height of the UV quad.

flipX?: boolean

If flip the texture horizontally.

flipY?: boolean

If flip the texture vertically.

tex?: GfxTexture

The texture to sample for this quad.

quad?: Quad

The texture sampling area.

origin?: Origin | Vec2

The origin point, or the pivot point. Default to "topleft".

type

DrawRectOpt

RenderProps&

width: number

Width of the rectangle.

height: number

Height of the rectangle.

outline?: Outline

If draw an outline around the shape.

fill?: boolean

If fill the shape with color (set this to false if you only want an outline).

radius?: number

The radius of each corner.

origin?: Origin | Vec2

The origin point, or the pivot point. Default to "topleft".

type

DrawLineOpt

Omit<RenderProps, "angle" | "scale">&

p1: Vec2

Starting point of the line.

p2: Vec2

Ending point of the line.

width?: number

The width, or thickness of the line,

type

DrawLinesOpt

Omit<RenderProps, "angle" | "scale">&

pts: Vec2[]

The points that should be connected with a line.

width?: number

The width, or thickness of the lines,

radius?: number

The radius of each corner.

type

DrawTriangleOpt

RenderProps&

p1: Vec2

First point of triangle.

p2: Vec2

Second point of triangle.

p3: Vec2

Third point of triangle.

outline?: Outline

If draw an outline around the shape.

fill?: boolean

If fill the shape with color (set this to false if you only want an outline).

radius?: number

The radius of each corner.

type

DrawCircleOpt

Omit<RenderProps, "angle">&

radius: number

Radius of the circle.

start?: number

Starting angle.

outline?: Outline

If draw an outline around the shape.

fill?: boolean

If fill the shape with color (set this to false if you only want an outline).

resolution?: number

Multipliyer for the number of polygon segments.

origin?: Origin | Vec2

The origin point, or the pivot point. Default to "topleft".

type

DrawEllipseOpt

RenderProps&

radiusX: number

The horizontal radius.

radiusY: number

The vertical radius.

start?: number

Starting angle.

outline?: Outline

If draw an outline around the shape.

fill?: boolean

If fill the shape with color (set this to false if you only want an outline).

resolution?: number

Multipliyer for the number of polygon segments.

origin?: Origin | Vec2

The origin point, or the pivot point. Default to "topleft".

type

DrawPolygonOpt

RenderProps&

pts: Vec2[]

The points that make up the polygon

outline?: Outline

If draw an outline around the shape.

fill?: boolean

If fill the shape with color (set this to false if you only want an outline).

indices?: number[]

Manual triangulation.

offset?: Vec2

The center point of transformation in relation to the position.

radius?: number

The radius of each corner.

type

Outline

width?: number

The width, or thinkness of the line.

color?: Color

The color of the line.

type

DrawTextOpt

RenderProps&

text: string

The text to render.

font?: string | FontData

The name of font to use.

size?: number

The size of text (the height of each character).

width?: number

The maximum width. Will wrap around if exceed.

lineSpacing?: number

The gap between each line.

since

v2000.2

letterSpacing?: number

The gap between each character.

since

v2000.2

origin?: Origin | Vec2

The origin point, or the pivot point. Default to "topleft".

transform?: CharTransform | CharTransformFunc

Transform the pos, scale, rotation or color for each character based on the index or char.

since

v2000.1

styles?: Record<string, CharTransform | CharTransformFunc>

Stylesheet for styled chunks, in the syntax of "this is a [styled].stylename word".

since

v2000.2

type

FormattedText

Formatted text with info on how and where to render each character.

width: number

height: number

chars: FormattedChar[]

type

FormattedChar

One formated character.

tex: GfxTexture

quad: Quad

ch: string

pos: Vec2

scale: Vec2

angle: number

color: Color

fixed: boolean

opacity: number

uniform: Uniform

type

CharTransformFunc

(idx: number, ch: string) => CharTransform

type

CharTransform

Describes how to transform each character.

pos?: Vec2

scale?: Vec2 | number

angle?: number

color?: Color

opacity?: number

type

Cursor

type

Origin

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.

dist(p: Vec2) => number

Get distance between another vector.

len() => number

unit() => Vec2

Get the unit vector (length of 1).

normal() => Vec2

Get the perpendicular vector.

angle(p: Vec2) => number

Get the angle between another vector

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

Linear interpolate to a destination vector

toFixed(n: number) => Vec2

To n precision floating point.

eq(p: Vec2) => boolean

str() => string

deprecated

v2000.2 Use toString() instead.

type

Vec3

x: number

y: number

z: number

xy() => Vec2

type

Vec4

x: number

y: number

z: number

w: number

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

multVec4(p: Vec4) => Vec4

multVec3(p: Vec3) => Vec3

multVec2(p: Vec2) => Vec2

invert() => Mat4

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

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

eq(c: Color) => boolean

str() => string

deprecated

v2000.2 Use toString() instead.

type

Quad

x: number

y: number

w: number

h: number

scale(q: Quad) => Quad

clone() => Quad

eq(q: Quad) => boolean

type

RNGValue

number | Vec2 | Color

type

RNG

seed: number

gen() => number

gen(n: T) => T

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

type

Rect

p1: Vec2

p2: Vec2

type

Line

p1: Vec2

p2: Vec2

type

Circle

center: Vec2

radius: number

type

Polygon

type

Point

Vec2

type

Comp

id?: Tag

Component ID (if left out won't be treated as a comp).

require?: Tag[]

What other comps this comp depends on.

add?: () => void

Event that runs when host game obj is added to scene.

load?: () => void

Event that runs when host game obj is added to scene and game is loaded.

update?: () => void

Event that runs every frame.

draw?: () => void

Event that runs every frame.

destroy?: () => void

Event that runs when obj is removed from scene.

inspect?: () => string

Debug info for inspect mode.

type

GameObjID

number

type

PosComp

pos: Vec2

Object's current world position.

move(xVel: number, yVel: number)

Move how many pixels per second. If object is 'solid', it won't move into other 'solid' objects.

move(vel: Vec2)

moveBy(dx: number, dy: number)

Move how many pixels, without multiplying dt, but still checking for 'solid'.

moveBy(d: Vec2)

moveTo(dest: Vec2, speed?: number)

Move to a spot with a speed (pixels per second), teleports if speed is not given.

moveTo(x: number, y: number, speed?: number)

screenPos() => Vec2

Get position on screen after camera transform.

type

ScaleComp

scale: Vec2 | number

scaleTo(s: number)

scaleTo(s: Vec2)

scaleTo(sx: number, sy: number)

type

RotateComp

angle: number

Angle in degrees.

type

ColorComp

color: Color

type

OpacityComp

opacity: number

type

OriginComp

origin: Origin | Vec2

Origin point for render.

type

LayerComp

layer: string

Which layer this game obj belongs to.

type

ZComp

z: number

Defines the z-index of this game obj

type

FollowComp

follow:

obj: GameObj

offset: Vec2

type

MoveComp

type

OutviewCompOpt

hide?: boolean

If hide object when out of view.

pause?: boolean

If pause object when out of view.

destroy?: boolean

If destroy object when out of view.

offset?: number | Vec2

The screen bound offset.

delay?: number

If it needs to stay out of view for a period of time before proceed to action.

onExitView?: () => void

onEnterView?: () => void

type

OutviewComp

isOutOfView() => boolean

If object is currently out of view.

onExitView(action: () => void) => EventCanceller

onEnterView(action: () => void) => EventCanceller

type

CleanupCompOpt

offset?: number | Vec2

The screen bound offset.

delay?: number

If it needs to stay out of view for a period of time before proceed to destroy.

onCleanup?: () => void

type

CleanupComp

type

Collision

Collision resolution data.

target: GameObj

The game object that we collided into.

displacement: Vec2

The displacement it'll need to separate us from the target.

isTop() => boolean

If the collision happened (roughly) on the top side of us.

isBottom() => boolean

If the collision happened (roughly) on the bottom side of us.

isLeft() => boolean

If the collision happened (roughly) on the left side of us.

isRight() => boolean

If the collision happened (roughly) on the right side of us.

type

AreaCompOpt

shape?: Shape

The shape of the area.

offset?: Vec2

Position of area relative to position of the object.

width?: number

Width of area.

height?: number

Height of area.

scale?: number | Vec2

Area scale.

cursor?: Cursor

Cursor on hover.

type

AreaComp

area: AreaCompOpt

Collider area info.

isClicked() => boolean

If was just clicked on last frame.

isHovering() => boolean

If is being hovered on.

isColliding(o: GameObj) => boolean

If is currently colliding with another game obj.

isTouching(o: GameObj) => boolean

If is currently touching another game obj.

onClick(f: () => void)

since

v2000.1

onHover(onHover: () => void, onNotHover?: () => void)

since

v2000.1

onCollide(tag: Tag, f: (obj: GameObj, col?: Collision) => void)

since

v2000.1

hasPoint(p: Vec2) => boolean

If has a certain point inside collider.

pushOut(obj: GameObj)

Push out from another solid game obj if currently overlapping.

pushOutAll()

Push out from all other solid game objs if currently overlapping.

worldArea() => Area

Get the geometry data for the collider in world coordinate space.

screenArea() => Area

Get the geometry data for the collider in screen coordinate space.

collides: AreaComp["onCollide"]

deprecated

v2000.1 Use onCollide() instead.

clicks: AreaComp["onClick"]

deprecated

v2000.1 Use onClick() instead.

hovers: AreaComp["onHover"]

deprecated

v2000.1 Use onHover() instead.

type

SpriteCompOpt

frame?: number

If the sprite is loaded with multiple frames, or sliced, use the frame option to specify which frame to draw.

tiled?: boolean

If provided width and height, don't stretch but instead render tiled.

width?: number

Stretch sprite to a certain width.

height?: number

Stretch sprite to a certain height.

anim?: string

Play an animation on start.

animSpeed?: number

Animation speed scale multiplier.

flipX?: boolean

Flip texture horizontally.

flipY?: boolean

Flip texture vertically.

quad?: Quad

The rectangular sub-area of the texture to render, default to full texture `quad(0, 0, 1, 1)`.

type

SpriteComp

width: number

Width for sprite.

height: number

Height for sprite.

frame: number

Current frame.

quad: Quad

The rectangular area of the texture to render.

play(anim: string, options?: SpriteAnimPlayOpt)

Play a piece of anim.

stop()

Stop current anim.

numFrames() => number

Get total number of frames.

curAnim() => string

Get current anim name.

animSpeed: number

Frame animation speed scale multiplier.

flipX(b: boolean)

Flip texture horizontally.

flipY(b: boolean)

Flip texture vertically.

onAnimStart(name: string, action: () => void) => EventCanceller

onAnimEnd(name: string, action: () => void) => EventCanceller

type

TextComp

text: string

The text to render.

textSize: number

The text size.

font: string | FontData

The font to use.

width: number

Width of text.

height: number

Height of text.

lineSpacing: number

The gap between each line.

since

v2000.2

letterSpacing: number

The gap between each character.

since

v2000.2

transform: CharTransform | CharTransformFunc

Transform the pos, scale, rotation or color for each character based on the index or char.

since

v2000.1

styles: Record<string, CharTransform | CharTransformFunc>

Stylesheet for styled chunks, in the syntax of "this is a [styled].stylename word".

since

v2000.2

type

TextCompOpt

size?: number

Height of text.

font?: string | FontData

The font to use.

width?: number

Wrap text to a certain width.

lineSpacing?: number

The gap between each line.

since

v2000.2

letterSpacing?: number

The gap between each character.

since

v2000.2

transform?: CharTransform | CharTransformFunc

Transform the pos, scale, rotation or color for each character based on the index or char.

since

v2000.1

styles?: Record<string, CharTransform | CharTransformFunc>

Stylesheet for styled chunks, in the syntax of "this is a [styled].stylename word".

since

v2000.2

type

RectCompOpt

radius?: number

Radius of the rectangle corners.

type

RectComp

width: number

Width of rectangle.

height: number

Height of rectangle.

radius?: number

The radius of each corner.

type

CircleComp

radius: number

Radius of circle.

type

UVQuadComp

width: number

Width of rect.

height: number

Height of height.

type

Area

unknown | unknown | unknown | unknown | unknown

type

Shape

"rect" | "line" | "point" | "circle" | "polygon"

type

OutlineComp

outline: Outline

type

Debug

paused: boolean

Pause the whole game.

inspect: boolean

Draw bounding boxes of all objects with `area()` component, hover to inspect their states.

timeScale: number

Global time scale.

showLog: boolean

Show the debug log or not.

fps() => number

Current frames per second.

objCount() => number

Number of all existing game objects.

drawCalls() => number

Number of draw calls made last frame.

stepFrame()

Step to the next frame. Useful with pausing.

clearLog()

Clear the debug log.

log(msg: string)

Log some text to on screen debug log.

error(msg: string)

Log an error message to on screen debug log.

curRecording: Recording | null

The recording handle if currently in recording mode.

since

v2000.1

type

UniformValue

Vec2 | Vec3 | Color | Mat4

type

Uniform

Record<string, UniformValue>

type

ShaderComp

uniform: Uniform

shader: string

type

BodyComp

solid: boolean

If should collide with other solid objects.

jumpForce: number

Initial speed in pixels per second for jump().

weight: number

Gravity multiplier.

curPlatform() => GameObj | null

Current platform landing on.

isGrounded() => boolean

If currently landing on a platform.

since

v2000.1

isFalling() => boolean

If currently falling.

since

v2000.1

jump(force?: number)

Upward thrust.

doubleJump(f?: number)

Performs double jump (the initial jump only happens if player is grounded).

onGround(action: () => void) => EventCanceller

since

v2000.1

onFall(action: () => void) => EventCanceller

since

v2000.1

onHeadbutt(action: () => void) => EventCanceller

since

v2000.1

onDoubleJump(action: () => void) => EventCanceller

since

v2000.1

grounded() => boolean

deprecated

v2000.1 Use isGrounded() instead.

falling() => boolean

deprecated

v2000.1 Use isFalling() instead.

type

BodyCompOpt

jumpForce?: number

Initial speed in pixels per second for jump().

maxVel?: number

Maximum velocity when falling.

weight?: number

Gravity multiplier.

solid?: boolean

If should not move through other solid objects.

type

Timer

time: number

Time left.

action: () => void

The action to take when timer is up

finished: boolean

paused: boolean

tick(dt: number) => boolean

reset(time: number)

type

TimerComp

wait(n: number, action: () => void) => EventCanceller

Run the callback after n seconds.

type

SolidComp

solid: boolean

If should stop other solid objects from moving through.

type

FixedComp

fixed: boolean

If the obj is unaffected by camera

type

StayComp

stay: boolean

If the obj should not be destroyed on scene switch.

type

HealthComp

hurt(n?: number)

Decrease HP by n (defaults to 1).

heal(n?: number)

Increase HP by n (defaults to 1).

hp() => number

Current health points.

setHP(hp: number)

Set current health points.

onHurt(action: () => void) => EventCanceller

since

v2000.1

onHeal(action: () => void) => EventCanceller

since

v2000.1

onDeath(action: () => void) => EventCanceller

since

v2000.1

type

LifespanComp

type

LifespanCompOpt

fade?: number

Fade out duration (default 0 which is no fade out).

type

StateComp

state: string

Current state.

enterState: (state: string, args: ...) => void

Enter a state, trigger onStateLeave for previous state and onStateEnter for the new State state.

onStateTransition(from: string, to: string, action: () => void) => unknown

Register event that runs once when a specific state transition happens. Accepts arguments passed from `enterState(name, ...args)`.

since

v2000.2

onStateEnter: (state: string, action: (args: ...) => void) => void

onStateLeave: (state: string, action: () => void) => void

onStateUpdate: (state: string, action: () => void) => void

onStateDraw: (state: string, action: () => void) => void

type

LevelOpt

width: number

Width of each block.

height: number

Height of each block.

pos?: Vec2

Position of the first block.

any?: (s: string, pos: Vec2) => CompList<any> | unknown

Called when encountered an undefined symbol.

type

Level

getPos(p: Vec2) => Vec2

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

spawn(sym: string, p: Vec2) => GameObj

spawn(sym: string, x: number, y: number) => GameObj

width() => number

height() => number

gridWidth() => number

gridHeight() => number

offset() => Vec2

destroy() => unknown

type

Kaboom

destroy()

Remove kaboom.