Migrating from v2000 to v3000

• obj._id is renamed to obj.id

const obj = add([
    pos(300, 200),
    sprite("bean"),
    area(),
])

// before
console.log(obj._id)

// v3000
console.log(obj.id)

• origin() is renamed to anchor()

// before
add([
    sprite("bean"),
    origin("center"),
])

// v3000
add([
    sprite("bean"),
    anchor("center"),
])

• obj.onHover() in area() comp is renamed to obj.onHoverUpdate(), obj.onHover() now only runs once when obj is hovered

const obj = add([
    pos(300, 200),
    sprite("bean"),
    area(),
])

// before
obj.onHover(() => {
    console.log("this will print every frame when obj is hovered")
}, () => {
    console.log("this will print every frame when obj is not hovered")
})

// v3000
obj.onHover(() => {
    console.log("this will run once when obj is hovered")
})

obj.onHoverUpdate(() => {
    console.log("this will run every frame when obj is hovered")
})

obj.onHoverEnd(() => {
    console.log("this will run once when obj stopped being hovered")
})

• obj.pushOut() is renamed to obj.resolveCollision()

const player = add([
    sprite("bean"),
    pos(300, 200),
    area(),
])

// before
player.pushOut(rock)

// v3000
player.resolveCollision(rocker)

• solid() comp becomes an option in body({ isStatic: true })

// before
add([
    sprite("bean"),
    area(),
    body(),
    solid(),
])

// v3000
add([
    sprite("bean"),
    area(),
    body({ isStatic: true }),
])

• gravity now needs to be manually enabled, gravity() is renamed to setGravity() and getGravity()

// before, gravity will be enabled by body() component
add([
    pos(100, 100),
    sprite("bean"),
    area(),
    body(),
])

// v3000, use gravity() to manually enable gravity
setGravity(1600)

add([
    pos(100, 100),
    sprite("bean"),
    area(),
    body(),
])

• body.weight is renamed to body.gravityScale

// before
add([
    body({ weight: 2 }),
])

// before
add([
    body({ gravityScale: 2 }),
])

• body.doubleJump() is removed in favor of new doubleJump() component

const obj = add([
    pos(100, 100),
    sprite("bean"),
    area(),
    body(),
])

obj.doubleJump()

// after
const obj = add([
    pos(100, 100),
    sprite("bean"),
    area(),
    body(),
    doubleJump(),
])

obj.doubleJump()

• body.onFall() is renamed to body.onFallOff(), body.onFall() now runs when body is in the air and starts to fall

gravity(1600)

const obj = add([
    pos(100, 100),
    sprite("bean"),
    area(),
    body(),
])

// before
obj.onFall(() => {
    console.log("this will print when object falls off a platform")
})

// v3000
obj.onFallOff(() => {
    console.log("this will print when object falls off a platform")
})

obj.onFall(() => {
    console.log("this will print when object is in the air and starts falling")
})

• removed outview() in favor of offscreen(), which is less accurate but much faster

// before
add([
    sprite("flower"),
    outview({ hide: true }),
])

// v3000
add([
    sprite("flower"),
    // will hide itself when its position is 64 pixels offscreen
    offscreen({ hide: true, distance: 64 }),
])

• removed cleanup() in favor of offscreen({ destroy: true })

// before
add([
    pos(player.pos),
    sprite("bullet"),
    cleanup(),
])

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

• sprite.flipX and sprite.flipY becomes properties instead of functions

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

// before
bean.flipX(true)

// v3000
bean.flipX = true

• sprite.onAnimStart() and sprite.onAnimEnd() now triggers on any animation

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

// before
bean.onAnimStart("walk", () => {
    // do something
})

// before
bean.onAnimStart((anim) => {
    if (anim === "walk") {
        // do something
    }
})

• obj.scale now is always a Vec2

scale(2) // scale is vec2(2, 2)
obj.scale // vec2(2, 2)

• loadFont() now only loads .ttf, .otf, .woff etc fonts that browser support, use loadBitmapFont() to load bitmap fonts

// before
loadFont("unscii", "/examples/fonts/unscii_8x8.png", 8, 8)

// v3000
loadBitmapFont("unscii", "/examples/fonts/unscii_8x8.png", 8, 8)
loadFont("apl386", "/examples/fonts/apl386.ttf")

• removed builtin fonts apl386, apl386o, sink and sinko, using browser built-in monospace font as default font now

// v3000, manually load these fonts if you need them
loadFont("apl386", "/examples/fonts/apl386.ttf")
loadBitmapFont("sink", "/examples/fonts/sink_6x8.png")

// use outline option for "apl386o"
loadFont("apl386", "/examples/fonts/apl386.ttf", {
    outline: 3,
})

• changed vertex format from vec3 to vec2 (only applied in shaders)

// before
loadShader("test", null, `
vec4 frag(vec3 pos, vec2 uv, vec4 color, sampler2D tex) {
    return def_frag();
}
`)

// v3000
loadShader("test", null, `
vec4 frag(vec2 pos, vec2 uv, vec4 color, sampler2D tex) {
    return def_frag();
}
`)

• anchor (previously origin) no longer controls text alignment (only controls the anchor of the whole text area), use text({ align: "left" }) option for text alignment

// before
add([
    pos(center()),
    origin("center"),
    text("oh hi"),
])

// v3000
add([
    pos(center()),
    anchor("center"),
    text("oh hi", { align: "center" }),
])

• changed text styling syntax to bbcode

const textOpts = {
    styles: {
        "green": {
            color: rgb(128, 128, 255),
        },
        "wavy": (idx, ch) => ({
            color: hsl2rgb((time() * 0.2 + idx * 0.1) % 1, 0.7, 0.8),
            pos: vec2(0, wave(-4, 4, time() * 6 + idx * 0.5)),
        }),
    },
}

// before
add([
    text("[oh hi].green here's some [styled].wavy text", textOpts),
])

// v3000
add([
    text("[green]oh hi[/green] here's some [wavy]styled[/wavy] text", textOpts),
])

• changed all event handlers to return an EventController object, instead of a function to cancel

// before
const cancel = onUpdate(() => { /* ... */ })
cancel()

// v3000
const ev = onUpdate(() => { /* ... */ })
ev.paused = true
ev.cancel()

• changed the interface for addLevel()

// before
addLevel([
    "@  ^ $$",
    "=======",
], {
    width: 32,
    height: 32,
    "=": () => [
        sprite("grass"),
        area(),
        body({ isStatic: true }),
    ],
    "$": () => [
        sprite("coin"),
        area(),
        "coin",
    ],
    any: (symbol) => {
        if (symbol === "@") {
            return [ /* ... */ ]
        }
    },
})

// v3000
addLevel([
    "@  ^ $$",
    "=======",
], {
    tileWidth: 32,
    tileHeight: 32,
    tiles: {
        "=": () => [
            sprite("grass"),
            area(),
            body({ isStatic: true }),
        ],
        "$": () => [
            sprite("coin"),
            area(),
            "coin",
        ],
    },
    wildcardTile: (symbol) => {
        if (symbol === "@") {
            return [ /* ... */ ]
        }
    },
})