kaplay(gopt?: KAPLAYOpt)
Initialize KAPLAY context. The starting point of all KAPLAY games.
// Start KAPLAY with default options (will create a fullscreen canvas under <body>)
kaplay()
// Init with some options
kaplay({
width: 320,
height: 240,
font: "sans-serif",
canvas: document.querySelector("#mycanvas"),
background: [ 0, 0, 255, ],
})
// All KAPLAY functions are imported to global after calling kaplay()
add()
onUpdate()
onKeyPress()
vec2()
// If you want to prevent KAPLAY from importing all functions to global and use a context handle for all KAPLAY functions
const k = kaplay({ global: false })
k.add(...)
k.onUpdate(...)
k.onKeyPress(...)
k.vec2(...)
groupStart
End everything.
sincev2000.0
groupStart
KAPLAYOpt<TPlugin, TButtonDef>:
KAPLAY configurations.
groupStart
Width of game.
Height of game.
Pixel scale / size.
If stretch canvas to container when width and height is specified
When stretching if keep aspect ratio and leave black bars on remaining spaces.
If register debug buttons (default true)
Key that toggles debug mode
font?: string
Default font (defaults to "monospace").
Device pixel scale (defaults to 1, high pixel density will hurt performance).
sincev3000.0
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?: RGBValue | RGBAValue | 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.
Default texture filter.
How many log messages can there be on one screen (default 8).
How many seconds log messages stay on screen (default 4).
sincev3000.1
Size of the spatial hash grid for collision detection (default 64).
sincev3000.0
If translate touch events as mouse clicks (default true).
If KAPLAY should render a default loading screen when assets are not fully ready (default true).
sincev3000.0
If pause audio when tab is not active (default false).
sincev3000.0
gamepads?: Record<string, GamepadDef>
Custom gamepad definitions (see gamepad.json for reference of the format).
sincev3000.0
Defined buttons for input binding.
sincev30010
Limit framerate to an amount per second.
sincev3000.0
If focus on the canvas on start (default true).
sincev3001.0
If import all KAPLAY functions to global (default true).
List of plugins to import.
burp?: boolean
Enter burp mode.
Make component's id ("sprite" for sprite() comp) be added as tags.
That means .is() will return true for components with that id.
defaulttrue
experimentalThis feature is in experimental phase, it will be fully released in v4000.0
Padding used when adding sprites to texture atlas.
default0
experimentalThis feature is in experimental phase, it will be fully released in v4000.0
loadRoot(path?: string): string
Sets the root for all subsequent resource urls.
This is useful when you want to load assets from a different domain, or setup
a base path for all assets.
parampath- The root path.
loadRoot("https://myassets.com/");
loadSprite("bean", "sprites/bean.png"); // will resolve to "https://myassets.com/sprites/bean.png"
loadRoot("./"); // useful for Itch.io
groupAssets
loadSprite(name: string | null, src: LoadSpriteSrc | LoadSpriteSrc[], opt?: LoadSpriteOpt): Asset<SpriteData>
Load a sprite into asset manager, with name and resource url and optional config.
paramname- The asset name.
paramsrc- The resource url.
paramopt- The optional config.
// due to browser policies you'll need a static file server to load local files
loadSprite("bean", "bean.png");
loadSprite("apple", "https://play.kaplayjs.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,
},
},
});
returnsThe asset data.
sincev2000.0
groupAssets
loadSpriteAtlas(src: LoadSpriteSrc, data: SpriteAtlasData): Asset<Record>
Load sprites from a sprite atlas.
paramsrc- The image resource url.
paramdata- The sprite atlas data.
// 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");
returnsThe asset data.
sincev2000.0
groupAssets
loadSpriteAtlas(src: LoadSpriteSrc, url: string): Asset<Record>
Load sprites from a sprite atlas with URL.
paramsrc- The image resource url.
paramurl- The json resource 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")
returnsThe asset data.
sincev2000.0
groupAssets
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).
paramname- The asset name.
paramimgSrc- The image resource url.
loadAseprite("car", "sprites/car.png", "sprites/car.json")
returnsThe asset data.
sincev2000.0
groupAssets
loadPedit(name: string | null, src: string): Asset<SpriteData>
paramname- The asset name.
paramsrc- The resource url.
Load .pedit file.
deprecatedThe format is not supported anymore.
returnsThe asset data.
sincev2000.0
groupAssets
loadBean(name?: string): Asset<SpriteData>
Load default sprite "bean".
paramname- The optional name for bean.
loadBean();
// use it right away
add([
sprite("bean"),
]);
returnsThe asset data.
sincev2000.0
groupAssets
loadJSON(name: string | null, url: string): Asset<any>
Load custom JSON data from url.
paramname- The asset name.
paramurl- The resource url.
returnsThe asset data.
sincev3000.0
groupAssets
loadSound(name: string | null, src: string | ArrayBuffer | AudioBuffer): Asset<SoundData>
Load a sound into asset manager, with name and resource url.
Supported formats: mp3, ogg, wav.
paramname- The asset name.
paramsrc- The resource url.
loadSound("shoot", "/sounds/horse.ogg");
loadSound("shoot", "/sounds/squeeze.mp3");
loadSound("shoot", "/sounds/shoot.wav");
returnsThe asset data.
sincev2000.0
groupAssets
loadMusic(name: string | null, url: string): void
Like loadSound(), but the audio is streamed and won't block loading. Use this for big audio files like background music.
paramname- The asset name.
paramurl- The resource url.
loadMusic("shoot", "/music/bossfight.mp3");
returnsThe asset data.
sincev3001.0
groupAssets
loadFont(name: string, src: string | BinaryData, opt?: LoadFontOpt): Asset<FontData>
Load a font (any format supported by the browser, e.g. ttf, otf, woff).
paramname- The asset name.
// load a font from a .ttf file
loadFont("frogblock", "fonts/frogblock.ttf");
returnsThe asset data.
sincev3000.0
groupAssets
loadBitmapFont(name: string | null, src: string, gridW: number, gridH: number, opt?: LoadBitmapFontOpt): Asset<BitmapFontData>
Load a bitmap font into asset manager, with name and resource url and information on the layout of the bitmap.
paramname- The asset name.
paramsrc- The resource url.
paramgridW- The width of each character on the bitmap.
paramgridH- The height of each character on the bitmap.
paramopt- The options for the bitmap font.
// 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: "☺☻♥♦♣♠" });
returnsThe asset data.
sincev3000.0
groupAssets
loadShader(name: string | null, vert?: string | null, frag?: string | null): Asset<ShaderData>
Load a shader with vertex and fragment code.
paramname- The asset name.
paramvert- The vertex shader code. Null if not needed.
paramfrag- The fragment shader code. Null if not needed.
// default shaders and custom shader format
loadShader("outline",
`vec4 vert(vec2 pos, vec2 uv, vec4 color) {
// predefined functions to get the default value by KAPLAY
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)
returnsThe asset data.
sincev2000.0
groupAssets
loadShaderURL(name: string | null, vert?: string | null, frag?: string | null): Asset<ShaderData>
Load a shader with vertex and fragment code file url.
paramname- The name of the asset.
paramvert- The vertex shader code. Null if not needed.
paramfrag- The fragment shader code. Null if not needed.
// load only a fragment shader from URL
loadShaderURL("outline", null, "/shaders/outline.glsl")
retunrsThe asset data.
sincev3000.0
groupAssets
load<T>(l: Promise): Asset<T>
Add a new loader to wait for before starting the game.
paraml- The loader to wait for.
load(new Promise((resolve, reject) => {
// anything you want to do that stalls the game in loading state
resolve("ok")
}))
returnsThe asset data.
sincev3000.0
groupAssets
Get the global asset loading progress (0.0 - 1.0).
returnsThe loading progress.
sincev3000.0
groupAssets
getSprite(name: string): Asset | null
Get SpriteData from name.
paramname- The asset name.
returnsThe asset data.
sincev3000.0
groupAssets
getSound(name: string): Asset | null
Get SoundData from name.
paramname- The asset name.
returnsThe asset data.
sincev3000.0
groupAssets
getFont(name: string): Asset | null
Get FontData from name.
paramname- The asset name.
returnsThe asset data.
sincev3000.0
groupAssets
getBitmapFont(name: string): Asset | null
Get BitmapFontData from name.
paramname- The asset name.
returnsThe asset data.
sincev3000.0
groupAssets
getShader(name: string): Asset | null
Get ShaderData from name.
paramname- The asset name.
returnsThe asset data.
sincev3000.0
groupAssets
getAsset(name: string): Asset | null
Get custom data from name.
paramname- The asset name.
returnsThe asset data.
sincev3000.0
groupAssets
An asset is a resource that is loaded asynchronously.
loaded<D>(data: D): Asset<D>
data: D | null
error: Error | null
onLoad(action: (data: D)=>void): this
onError(action: (err: Error)=>void): this
onFinish(action: ()=>void): this
then(action: (data: D)=>void): Asset<D>
catch(action: (err: Error)=>void): Asset<D>
finally(action: ()=>void): Asset<D>
tex: Texture
anims: SpriteAnims
slice9: NineSlice | null
sincev3001.0
from(src: LoadSpriteSrc, opt?: LoadSpriteOpt): Promise<SpriteData>
fromImage(data: ImageSource, opt?: LoadSpriteOpt): SpriteData
fromURL(url: string, opt?: LoadSpriteOpt): Promise<SpriteData>
buf: AudioBuffer
fromArrayBuffer(buf: ArrayBuffer): Promise<SoundData>
fromURL(url: string): Promise<SoundData>
add<T>(comps?: CompList | GameObj): GameObj<T>
Assemble a game object from a list of components, and add it to the game,
paramcomps- List of components to add to the game object, or a game object made with
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);
});
returnsThe added game object that contains all properties and methods each component offers.
groupGame Obj
make<T>(comps?: CompList): GameObj<T>
Create a game object like add(), but not adding to the scene.
paramcomps- List of components to add to the game object.
const label = make([
rect(100, 20),
]);
// Add a new text to the label
label.add([
text("Hello, world!"),
]);
// Add game object to the scene
// Now it will render
add(label);
returnsThe created game object that contains all properties and methods each component offers.
sincev3000.1
groupGame Obj
readd(obj: GameObj): GameObj
Remove and re-add the game obj, without triggering add / destroy events.
paramobj- The game object to re-add.
// 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);
});
returnsThe re-added game object.
sincev3001.0
groupGame Obj
get(tag: Tag | Tag[], opts?: GetOpt): GameObj[]
Get a list of all game objs with certain tag.
paramtag- The tag to search for. Use "*" to get all objects.
paramopts- Additional options.
// 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 });
returnsA list of game objects that have the tag.
sincev2000.0
groupGame Obj
query(opt: QueryOpt): GameObj[]
Get a list of game objects in an advanced way.
paramopt- The query options.
const bean = k.add(["friend", "bean"]);
const bean2 = k.add(["friend", "bean"]);
const bag = k.add(["friend", "bag"]);
// get bean
query({
include: "bean",
}) // will return [bean, bean2];
// get all friends excluding bean
query({
include: "friend",
exclude: "bean",
}); // will return [bag]
groupGame Obj
destroy(obj: GameObj): void
Remove the game obj.
paramobj- The game object to remove.
// every time bean collides with anything with tag "fruit", remove it
bean.onCollide("fruit", (fruit) => {
destroy(fruit);
});
groupGame Obj
Remove all game objs with certain tag.
paramtag- The tag to search for.
// destroy all objects with tag "bomb" when you click one
onClick("bomb", () => {
destroyAll("bomb");
});
groupGame Obj
Base interface of all game objects.
sincev2000.0
groupGame Obj
add<T>(comps?: CompList | GameObj): GameObj<T>
Add a child.
paramcomps- The components to add.
returnsThe added game object.
sincev3000.0
readd<T>(obj: GameObj): GameObj<T>
Remove and re-add the game obj, without triggering add / destroy events.
paramobj- The game object to re-add.
returnsThe re-added game object.
sincev3000.0
remove(obj: GameObj): void
Remove a child.
paramobj- The game object to remove.
sincev3000.0
Remove all children with a certain tag.
paramtag- The tag to remove.
sincev3000.0
Remove all children.
sincev3000.0
get(tag: Tag | Tag[], opts?: GetOpt): GameObj[]
Get a list of all game objs with certain tag.
paramtag- The tag to get.
sincev3000.0
query(opt: QueryOpt): GameObj[]
Get a list of all game objs with certain properties.
paramopt- The properties to get.
sincev3001.0
readonlyGet all children game objects.
sincev3000.0
tags: string[]
readonlyGet the tags of a game object. For update it, use `tag()` and `untag()`.
sincev3001.0
Update this game object and all children game objects.
sincev3001.0
Update this game object and all children game objects.
sincev3000.0
Draw this game object and all children game objects.
sincev3000.0
Draw debug info in inspect mode
sincev3000.0
use(comp: Comp | Tag): void
Add a component.
const obj = add([
sprite("bean"),
]);
// Add opacity
obj.use(opacity(0.5));
sincev2000.0
unuse(comp: Tag): void
Remove a component with its id (the component name)
paramcomp- The component id to remove. It means the name, if sprite, then it's "sprite".
// Remove sprite component
obj.unuse("sprite");
sincev2000.0
has(compId: string | string[], op?: "and" | "or"): boolean
Check if game object has a certain component.
paramcompId- The component id(s) to check.
paramop- The operator to use when searching for multiple components. Default is "and".
// Check if game object has sprite component
if(obj.has("sprite")) {
debug.log("has sprite component");
}
// Check if game object has tags
obj.has(["tag1", "tag2"]); // AND, it has both tags
obj.has(["tag1", "tag2"], "or"); // OR, it has either tag1 or tag2
returnstrue if has the component(s), false otherwise.
sincev3001.0.5
experimentalThis feature is in experimental phase, it will be fully released in v4000.0
tag(tag: Tag | Tag[]): void
Add a tag(s) to the game obj.
paramtag- The tag(s) to add.
// add enemy tag
obj.tag("enemy");
// add multiple tags
obj.tag(["enemy", "boss"]);
sincev3001.0.5
experimentalThis feature is in experimental phase, it will be fully released in v4000.0
untag(tag: Tag | Tag[]): void
Remove a tag(s) from the game obj.
paramtag- The tag(s) to remove.
// remove enemy tag
obj.untag("enemy");
// remove multiple tags
obj.untag(["enemy", "boss"]);
sincev3001.0.5
experimentalThis feature is in experimental phase, it will be fully released in v4000.0
is(tag: Tag | Tag[], op?: "and" | "or"): boolean
If there's certain tag(s) on the game obj.
paramtag- The tag(s) for checking.
paramop- The operator to use when searching for multiple tags. Default is "and".
sincev3001.0.5
experimentalThis feature is in experimental phase, it will be fully released in v4000.0
on(event: GameObjEventNames | string & {}, action: (args: any)=>void): KEventController
Register an event.
paramevent- The event name.
paramaction- The action to run when event is triggered.
returnsThe event controller.
sincev2000.0
trigger(event: string, args: any): void
Trigger an event.
paramevent- The event name.
parmargs - The arguments to pass to the event action.
sincev2000.0
Remove the game obj from scene.
sincev2000.0
c(id: string): Comp | null
Get state for a specific comp.
paramid- The component id.
sincev2000.0
inspect(): GameObjInspect
Gather debug info of all comps.
sincev2000.0
onAdd(action: ()=>void): KEventController
Register an event that runs when the game obj is added to the scene.
returnsThe event controller.
sincev2000.0
onUpdate(action: ()=>void): KEventController
Register an event that runs every frame as long as the game obj exists.
returnsThe event controller.
sincev2000.1
onFixedUpdate(action: ()=>void): KEventController
Register an event that runs every frame as long as the game obj exists.
returnsThe event controller.
sincev2000.1
onDraw(action: ()=>void): KEventController
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).
returnsThe event controller.
sincev2000.1
onDestroy(action: ()=>void): KEventController
Register an event that runs when the game obj is destroyed.
returnsThe event controller.
sincev2000.1
onUse(action: (id: string)=>void): KEventController
Register an event that runs when a component is used.
returnsThe event controller.
sincev3001.0
onUnuse(action: (id: string)=>void): KEventController
Register an event that runs when a component is unused.
returnsThe event controller.
sincev3001.0
onTag(action: (tag: string)=>void): KEventController
Register an event that runs when a tag is added.
returnsThe event controller.
sincev3001.10
experimental
onUntag(action: (tag: string)=>void): KEventController
Register an event that runs when a tag is removed.
returnsThe event controller.
sincev3001.10
experimental
If game obj is attached to the scene graph.
returnstrue if attached, false otherwise.
sincev2000.0
Check if is an ancestor (recursive parent) of another game object
returnstrue if is ancestor, false otherwise.
sincev3000.0
Calculated transform matrix of a game object.
sincev3000.0
If draw the game obj (run "draw" event or not).
sincev2000.0
If update the game obj (run "update" event or not).
sincev2000.0
id: GameObjID | null
A unique number ID for each game object.
sincev2000.0
canvas: FrameBuffer | null
The canvas to draw this game object on
sincev3001.0
onKeyDown: KAPLAYCtx["onKeyDown"]
onKeyPress: KAPLAYCtx["onKeyPress"]
onKeyRelease: KAPLAYCtx["onKeyRelease"]
onCharInput: KAPLAYCtx["onCharInput"]
onMouseDown: KAPLAYCtx["onMouseDown"]
onMousePress: KAPLAYCtx["onMousePress"]
onMouseRelease: KAPLAYCtx["onMouseRelease"]
onMouseMove: KAPLAYCtx["onMouseMove"]
onTouchStart: KAPLAYCtx["onTouchStart"]
onTouchMove: KAPLAYCtx["onTouchMove"]
onTouchEnd: KAPLAYCtx["onTouchEnd"]
onScroll: KAPLAYCtx["onScroll"]
onGamepadStick: KAPLAYCtx["onGamepadStick"]
onButtonDown: KAPLAYCtx["onButtonDown"]
onButtonPress: KAPLAYCtx["onButtonPress"]
GameObj<T>: GameObjRaw & MergeComps
The basic unit of object in KAPLAY. The player, a butterfly, a tree, or even a piece of text.
groupGame Obj
groupGame Obj
pos(x: number, y: number): PosComp
Set the position of a Game Object.
paramx- The x position to set.
paramy- The y position to set.
// This game object will draw a "bean" sprite at (100, 200)
add([
pos(100, 200),
sprite("bean"),
]);
returnsThe position comp.
sincev2000.0
groupComponents
pos(xy: number): PosComp
pos(p: Vec2): PosComp
pos(): PosComp
scale(x: number, y: number): ScaleComp
Set the scale of a Game Object.
paramx- The x scale to set.
paramy- The y scale to set.
// 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);
returnsThe scale comp.
sincev2000.0
groupComponents
scale(xy: number): ScaleComp
scale(s: Vec2): ScaleComp
scale(): ScaleComp
rotate(a?: number): RotateComp
Rotates a Game Object (in degrees).
parama- The angle to rotate by. Defaults to 0.
let bean = add([
sprite("bean"),
rotate(),
])
// bean will be upside down!
bean.angle = 180
returnsThe rotate comp.
sincev2000.0
groupComponents
color(r: number, g: number, b: number): ColorComp
Sets the color of a Game Object (rgb 0-255).
paramr- The red value to set.
paramg- The green value to set.
paramb- The blue value to set.
// blue frog
add([
sprite("bean"),
color(0, 0, 255),
]);
returnsThe color comp.
sincev2000.0
groupComponents
color(c: Color): ColorComp
color(rgb:
[
number, number, number
]
): ColorComp
color(c: string): ColorComp
color(): ColorComp
opacity(o?: number): OpacityComp
Sets the opacity of a Game Object (0.0 - 1.0).
paramo- The opacity value to set.
const bean = add([
sprite("bean"),
opacity(0.5) // Make bean 50% transparent
])
// Make bean invisible
bean.opacity = 0
// Make bean fully visible
bean.opacity = 1
returnsThe opacity comp.
sincev2000.0
groupComponents
sprite(spr: string | SpriteData | Asset, opt?: SpriteCompOpt): SpriteComp
Attach and render a sprite to a Game Object.
paramspr- The sprite to render.
paramopt- Options for the sprite component. See
// 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
returnsThe sprite comp.
sincev2000.0
groupComponents
text(txt?: string, opt?: TextCompOpt): TextComp
Attach and render a text to a Game Object.
paramtxt- The text to display.
paramopt- Options for the text component. See
// 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
}),
])
returnsThe text comp.
sincev2000.0
groupComponents
polygon(pts: Vec2[], opt?: PolygonCompOpt): PolygonComp
Attach and render a polygon to a Game Object.
parampts- The points to render the polygon.
paramopt- Options for the polygon component. See
// 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(),
])
returnsThe polygon comp.
sincev3001.0
groupComponents
rect(w: number, h: number, opt?: RectCompOpt): RectComp
Attach and render a rectangle to a Game Object.
paramw- The width of the rectangle.
paramh- The height of the rectangle.
paramopt- Options for the rectangle component. See
const obstacle = add([
pos(80, 120),
rect(20, 40),
outline(4),
area(),
])
returnsThe rectangle component.
groupComponents
circle(radius: number, opt?: CircleCompOpt): CircleComp
Attach and render a circle to a Game Object.
paramradius- The radius of the circle.
paramopt- Options for the circle component. See
add([
pos(80, 120),
circle(16),
])
returnsThe circle comp.
sincev2000.0
groupComponents
uvquad(w: number, h: number): UVQuadComp
Attach and render a UV quad to a Game Object.
paramw- The width of the quad.
paramh- The height of the quad.
add([
uvquad(width(), height()),
shader("spiral"),
])
returnsThe UV quad comp.
sincev2000.0
groupComponents
area(opt?: AreaCompOpt): AreaComp
Attach a collider area from shape and enables collision detection in a Game Object.
paramopt- Options for the area component. See
// 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
}
})
returnsThe area comp.
sincev2000.0
groupComponents
anchor(o: Anchor | Vec2): AnchorComp
Anchor point for render (default "topleft").
paramo- The anchor point to set.
// set anchor to "center" so it'll rotate from center
add([
rect(40, 10),
rotate(45),
anchor("center"),
])
returnsThe anchor comp.
sincev2000.0
groupComponents
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.
paramz- The z value to set.
const bean = add([
sprite("bean"),
pos(100, 100),
z(10), // Bean has a z value of 10
])
// Mark has a z value of 20, so he will always be drawn on top of bean
const mark = add([
sprite("mark"),
pos(100, 100),
z(20),
])
bean.z = 30 // Bean now has a higher z value, so it will be drawn on top of mark
returnsThe z comp.
sincev2000.0
groupComponents
outline(width?: number, color?: Color, opacity?: number, join?: LineJoin, miterLimit?: number, cap?: LineCap): OutlineComp
Give an object an outline. Doesn't support sprite or text components.
paramwidth- The width of the outline.
paramcolor- The color of the outline.
paramopacity- The opacity of the outline.
paramjoin- -The line join style.
parammiterLimit- The miter limit ratio.
paramcap-The line cap style.
// Add an outline to a rectangle
add([
rect(40, 40),
outline(4),
]);
returnsThe outline comp.
sincev2000.0
groupComponents
particles(popt: ParticlesOpt, eopt: EmitterOpt): ParticlesComp
Attach a particle emitter to a Game Object.
parampopt- The options for the particles.
parameopt- The options for the emitter.
// beansplosion
// create the emitter
const emitter = add([
pos(center()),
particles({
max: 100,
speed: [75, 100],
lifeTime: [0.75,1.0],
angle: [0, 360],
opacities: [1.0, 0.0],
texture: getSprite("bean").tex, // texture of a sprite
quads: getSprite("bean").frames, // frames of a sprite
}, {
direction: 0,
spread: 360,
}),
])
onUpdate(() => {
emitter.emit(1)
})
returnsThe particles comp.
sincev3001.0
groupComponents
body(opt?: BodyCompOpt): BodyComp
Physical body that responds to gravity. Requires "area" and "pos" comp. This also makes the object "solid".
paramopt- Options for the body component. See
// 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!")
})
returnsThe body comp.
sincev2000.0
groupComponents
surfaceEffector(opt: SurfaceEffectorCompOpt): SurfaceEffectorComp
Applies a force on a colliding object in order to make it move along the collision tangent vector.
Good for conveyor belts.
paramopt- Options for the surface effector component. See
loadSprite("belt", "/sprites/jumpy.png")
// conveyor belt
add([
pos(center()),
sprite("belt"),
rotate(90),
area(),
body({ isStatic: true }),
surfaceEffector({
speed: 50,
})
])
returnsThe surface effector comp.
sincev3001.0
groupComponents
areaEffector(opt: AreaEffectorCompOpt): AreaEffectorComp
Applies a force on a colliding object.
Good to apply anti-gravity, wind or water flow.
paramopt- Options for the area effector component. See
returnsThe area effector comp.
sincev3001.0
groupComponents
pointEffector(opt: PointEffectorCompOpt): PointEffectorComp
Applies a force on a colliding object directed towards this object's origin.
Good to apply magnetic attraction or repulsion.
paramopt- Options for the point effector component. See
returnsThe point effector comp.
sincev3001.0
groupComponents
platformEffector(opt?: PlatformEffectorCompOpt): PlatformEffectorComp
The platform effector makes it easier to implement one way platforms
or walls. This effector is typically used with a static body, and it
will only be solid depending on the direction the object is traveling from.
paramopt- Options for the platform effector component. See
returnsThe platform effector comp.
sincev3001.0
groupComponents
buoyancyEffector(opt: BuoyancyEffectorCompOpt): BuoyancyEffectorComp
Applies an upwards force (force against gravity) to colliding objects depending on the fluid density and submerged area.
Good to apply constant thrust.
paramopt- Options for the buoyancy effector component. See
returnsThe buoyancy effector comp.
sincev3001.0
groupComponents
constantForce(opt: ConstantForceCompOpt): ConstantForceComp
Applies a constant force to the object.
Good to apply constant thrust.
paramopt- Options for the constant force component. See
returnsThe constant force comp.
sincev3001.0
groupComponents
doubleJump(numJumps?: number): DoubleJumpComp
Enables double jump.
paramnumJumps- The number of jumps allowed. Defaults to 1.
requires
returnsThe double jump comp.
sincev3000.0
groupComponents
move(dir: number | Vec2, speed: number): EmptyComp
Move towards a direction infinitely, and destroys when it leaves game view.
paramdir- The direction to move towards.
paramspeed- The speed to move at.
requires
// enemy throwing feces at player
const projectile = add([
sprite("feces"),
pos(enemy.pos),
area(),
move(player.pos.angle(enemy.pos), 1200),
offscreen({ destroy: true }),
])
returnsThe move comp.
sincev2000.0
groupComponents
offscreen(opt?: OffScreenCompOpt): OffScreenComp
Control the behavior of object when it goes out of view.
paramopt- Options for the offscreen component. See
add([
pos(player.pos),
sprite("bullet"),
offscreen({ destroy: true }),
"projectile",
]);
returnsThe offscreen comp.
sincev2000.2
groupComponents
follow(obj: GameObj | null, offset?: Vec2): FollowComp
Follow another game obj's position.
paramobj- The game obj to follow.
paramoffset- The offset to follow at.
const bean = add(...)
add([
sprite("bag"),
pos(),
follow(bean) // Follow bean's position
]);
// Using offset
const target = add(...)
const mark = add([
sprite("mark"),
pos(),
follow(target, vec2(32, 32)) // Follow target's position with an offset
])
mark.follow.offset = vec2(64, 64) // Change the offset
returnsThe follow comp.
sincev2000.0
groupComponents
shader(id: string, uniform?: Uniform | ()=>Uniform): ShaderComp
Custom shader.
paramid- The shader id.
paramuniform- The uniform to pass to the shader.
returnsThe shader comp.
sincev2000.0
groupComponents
textInput(hasFocus?: boolean, maxInputLength?: number): TextInputComp
Get input from the user and store it in the nodes text property, displaying it with the text component and allowing other functions to access it.
paramhasFocus- Whether the text input should have focus.
parammaxInputLength- The maximum length of the input.
const obj = add([
text(""),
textInput(),
])
obj.hasFocus = false
debug.log(obj.text) // oh no i cant see my new text since it was disabled
returnsThe text input comp.
sincev3001.0
groupComponents
timer(maxLoopsPerFrame?: number): TimerComp
Enable timer related functions like wait(), loop(), tween() on the game object.
parammaxLoopsPerFrame- The maximum number of loops per frame.
const obj = add([
timer(),
])
obj.wait(2, () => { ... })
obj.loop(0.5, () => { ... })
obj.tween(obj.pos, mousePos(), 0.5, (p) => obj.pos = p, easings.easeOutElastic)
returnsThe timer comp.
sincev2000.0
groupComponents
fixed(): FixedComp
Make a game obj unaffected by camera or parent object transforms, and render at last.
Useful for UI elements.
// this will be be fixed on top left and not affected by camera
const score = add([
text(0),
pos(12, 12),
fixed(),
])
returnsThe fixed comp.
sincev2000.0
groupComponents
stay(scenesToStay?: string[]): StayComp
Don't get destroyed on scene switch. Only works in objects attached to root.
paramscenesToStay- The scenes to stay in. By default it stays in all scenes.
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)
})
returnsThe stay comp.
sincev2000.0
groupComponents
health(hp: number, maxHP?: number): HealthComp
Handles health related logic and events.
paramhp- The initial health points.
parammaxHP- The maximum health points.
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")
})
returnsThe health comp.
sincev2000.0
groupComponents
lifespan(time: number, options?: LifespanCompOpt): EmptyComp
Destroy the game obj after certain amount of time
paramtime- The time to live.
paramoptions- Options for the lifespan component. See
// spawn an explosion, destroy after 1.5 seconds (time + fade)
add([
sprite("explosion", { anim: "burst", }),
lifespan(1, {
fade: 0.5 // it start fading 0.5 second after time
}),
]);
returnsThe lifespan comp.
sincev2000.0
groupComponents
named(name: string): NamedComp
Names an game obj.
paramname- The name to set.
returnsThe named comp.
sincev3001.0
groupComponents
state(initialState: string, stateList?: string[]): StateComp
Finite state machine.
paraminitialState- The initial state.
paramstateList- The list of states.
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")
}
})
returnsThe state comp.
sincev2000.1
groupComponents
state(initialState: string, stateList: string[], transitions: Record): StateComp
state() with pre-defined transitions.
paraminitialState- The initial state.
paramstateList- The list of states.
paramtransitions- The transitions between states.
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)
})
returnsThe state comp.
sincev2000.2
groupComponents
fadeIn(time: number): Comp
deprecatedsince v3001.0
requires
returnsAn empty comp.
sincev3000.0
groupComponents
mask(maskType?: Mask): MaskComp
Mask all children object render.
parammaskType- The type of mask to use.
returnsThe mask comp.
sincev3001.0
groupComponents
drawon(canvas: FrameBuffer): Comp
Specifies the FrameBuffer the object should be drawn on.
paramcanvas- The FrameBuffer to draw on.
// Draw on another canvas
let canvas = makeCanvas(width(), height());
let beanOnCanvas = add([
sprite("bean"),
drawon(canvas.fb),
]);
returnsThe drawon comp.
sincev3000.0
groupComponents
tile(opt?: TileCompOpt): TileComp
A tile on a tile map.
paramopt- Options for the tile component. See
returnsThe tile comp.
sincev3000.0
groupComponents
agent(opt?: AgentCompOpt): AgentComp
An agent which can finds it way on a tilemap.
paramopt- Options for the agent component. See
returnsThe agent comp.
sincev3000.0
groupComponents
animate(opt?: AnimateCompOpt): AnimateComp
A component to animate properties.
paramopt- Options for the animate component. See
let movingBean = add([
sprite("bean"),
pos(50, 150),
anchor("center"),
animate(),
]);
// Moving right to left using ping-pong
movingBean.animate("pos", [vec2(50, 150), vec2(150, 150)], {
duration: 2,
direction: "ping-pong",
});
returnsThe animate comp.
sincev3001.0
groupComponents
serializeAnimation(obj: GameObj, name: string): Animation
Serializes the animation to plain objects
paramobj- The game obj to serialize.
returnsThe serialized animation.
sincev3001.0
groupComponents
sentry(candidates: SentryCandidates, opt?: SentryCompOpt): SentryComp
A sentry which reacts to objects coming into view.
returnsThe sentry comp.
sincev3001.0
groupComponents
patrol(opts: PatrolCompOpt): PatrolComp
A patrol which can follow waypoints to a goal.
paramopts- Options for the patrol component. See
const bean = add([
sprite("bean"),
pos(40, 30),
patrol({
waypoints: [
vec2(100, 100),
vec2(120, 170),
vec2(50, 50),
vec2(300, 100),
],
}),
]);
bean.onPatrolFinished(gb => {
// Note that the position doesn't exactly match the last waypoint,
// this is an approximation.
debug.log(`Bean reached the end of the patrol at ${gb.pos.x}, ${gb.pos.y}`);
});
returnsThe patrol comp.
sincev3001.0
groupComponents
pathfinder(opts: PathfinderCompOpt): PathfinderComp
A navigator pathfinder which can calculate waypoints to a goal.
sincev3001.0
groupComponents
groupComponents
id?: Tag
Component ID (if left out won't be treated as a comp).
What other comps this comp depends on.
add?(): void
Event that runs when host game obj is added to scene.
Event that runs at a fixed frame rate.
Event that runs every frame.
draw?(): void
Event that runs every frame after update.
Event that runs when obj is removed from scene.
inspect?(): string | null
Debug info for inspect mode.
Draw debug info in inspect mode
sincev3000.0
The circle component.
groupComponent Types
draw: Comp["draw"]
Radius of circle.
Render area of the circle.
sincev3000.0
Options for the circle component.
groupComponent Types
fill?: boolean
If fill the circle (useful if you only want to render outline with
outline component).
The color component.
groupComponent Types
The mask component.
groupComponent Types
The opacity component.
groupComponent Types
Opacity of the current object.
fadeIn(time?: number, easeFunc?: EaseFunc): TweenController
Fade in at the start.
fadeOut(time?: number, easeFunc?: EaseFunc): TweenController
Fade out at the start.
The outline component.
groupComponent Types
Options for the particles's component
groupComponent Types
The particles component.
groupComponent Types
emit(n: number): void
onEnd(cb: ()=>void): void
The polygon component.
sincev3001.0
groupComponent Types
draw: Comp["draw"]
pts: Vec2[]
Points in the polygon.
radius?: number | number[]
The radius of each corner.
The color of each vertex.
uv?: Vec2[]
The uv of each vertex.
sincev3001.0
tex?: Texture
The texture used when uv coordinates are present.
sincev3001.0
PolygonCompOpt: Omit<DrawPolygonOpt, "pts">
Options for the polygon component.
groupComponent Types
The rect component.
groupComponent Types
draw: Comp["draw"]
Width of rectangle.
Height of rectangle.
radius?: number |
[
number, number, number, number
]
The radius of each corner.
sincev3000.0
Options for the rect component.
groupComponent Types
radius?: number |
[
number, number, number, number
]
Radius of the rectangle corners.
fill?: boolean
If fill the rectangle (useful if you only want to render outline with outline() component).
The shader component.
groupComponent Types
Uniform values to pass to the shader.
The shader ID.
The sprite component.
groupComponent Types
draw: Comp["draw"]
Name of the sprite.
Width for sprite.
Height for sprite.
Current frame in the entire spritesheet.
Current frame in relative to the animation that is currently playing.
The rectangular area of the texture to render.
play(anim: string, options?: SpriteAnimPlayOpt): void
Play a piece of anim.
Stop current anim.
Get total number of frames.
getCurAnim(): SpriteCurAnim | null
Get the current animation data.
sincev3001.0
curAnim(): string | undefined
Get current anim name.
deprecatedUse `getCurAnim().name` instead.
hasAnim(name: string): boolean
Check if object's sprite has an animation.
getAnim(name: string): SpriteAnim | null
Get an animation.
Speed multiplier for all animations (for the actual fps for an anim use .play("anim", { speed: 10 })).
Flip texture horizontally.
Flip texture vertically.
onAnimStart(action: (anim: string)=>void): KEventController
Register an event that runs when an animation is played.
onAnimEnd(action: (anim: string)=>void): KEventController
Register an event that runs when an animation is ended.
sincev3000.0
Options for the sprite component.
groupComponent Types
If the sprite is loaded with multiple frames, or sliced, use the frame option to specify which frame to draw.
If provided width and height, don't stretch but instead render tiled.
Stretch sprite to a certain width.
Stretch sprite to a certain height.
anim?: string
Play an animation on start.
Speed multiplier for all animations (for the actual fps for an anim use .play("anim", { speed: 10 })).
Flip texture horizontally.
Flip texture vertically.
The rectangular sub-area of the texture to render, default to full texture `quad(0, 0, 1, 1)`.
fill?: boolean
If fill the sprite (useful if you only want to render outline with outline() component).
The text component.
groupComponent Types
draw: Comp["draw"]
The text to render.
The text after formatting.
The text size.
font: string | BitmapFontData
The font to use.
Width of text.
Height of text.
align: TextAlign
Text alignment ("left", "center" or "right", default "left").
sincev3000.0
The gap between each line.
sincev2000.2
The gap between each character.
sincev2000.2
textTransform: CharTransform | CharTransformFunc
Transform the pos, scale, rotation or color for each character based on the index or char.
sincev2000.1
textStyles: Record<string, CharTransform | CharTransformFunc>
Stylesheet for styled chunks, in the syntax of "this is a [style]text[/style] word".
sincev2000.2
sincev3000.0
Options for the text component.
groupComponent Types
size?: number
Height of text.
font?: string | BitmapFontData
The font to use.
Wrap text to a certain width.
align?: TextAlign
Text alignment ("left", "center" or "right", default "left").
sincev3000.0
The gap between each line.
sincev2000.2
The gap between each character.
sincev2000.2
transform?: CharTransform | CharTransformFunc
Transform the pos, scale, rotation or color for each character based on the index or char.
sincev2000.1
styles?: Record<string, CharTransform | CharTransformFunc>
Stylesheet for styled chunks, in the syntax of "this is a [style]text[/style] word".
sincev2000.2
If true, any (whitespace) indent on the first line of the paragraph
will be copied to all of the lines for those parts that text-wrap.
The uvquad component.
groupComponent Types
draw: Comp["draw"]
Width of rect.
Height of height.
sincev3000.0
The agent component.
groupComponent Types
getPath(): Vec2[] | null
setTarget(target: Vec2): void
onTargetReached(cb: ()=>void): KEventController
Options for the agent component.
groupComponent Types
The fixed component.
groupComponent Types
If the obj is unaffected by camera
The pos component.
groupComponent Types
Object's current world position.
move(xVel: number, yVel: number): void
Move how many pixels per second. If object is 'solid', it won't move into other 'solid' objects.
move(vel: Vec2): void
moveBy(dx: number, dy: number): void
Move how many pixels, without multiplying dt, but still checking for 'solid'.
moveBy(d: Vec2): void
moveTo(dest: Vec2, speed?: number): void
Move to a spot with a speed (pixels per second), teleports if speed is not given.
moveTo(x: number, y: number, speed?: number): void
screenPos(newPos?: Vec2): Vec2 | null
Get / Set the position of the object on the screen.
sincev2000.0
worldPos(newPos?: Vec2): Vec2 | null
Get / Set the position of the object relative to the root.
sincev2000.0
toScreen(this: GameObj, p: Vec2): Vec2
Transform a local point (relative to this) to a screen point (relative to the camera)
toWorld(this: GameObj, p: Vec2): Vec2
Transform a local point (relative to this) to a world point (relative to the root)
sincev3001.0
fromScreen(this: GameObj, p: Vec2): Vec2
Transform a screen point (relative to the camera) to a local point (relative to this)
sincev3001.0
fromWorld(this: GameObj, p: Vec2): Vec2
Transform a world point (relative to the root) to a local point (relative to this)
sincev3001.0
toOther(this: GameObj, other: GameObj, p: Vec2): Vec2
Transform a point relative to this to a point relative to other
sincev3001.0
fromOther(this: GameObj, other: GameObj, p: Vec2): Vec2
Transform a point relative to other to a point relative to this
sincev3001.0
The sentry component.
groupComponent Types
onObjectsSpotted(cb: (objects: GameObj[])=>void): KEventController
Attaches an event handler which is called when objects of interest are spotted.
paramcbThe event handler called when objects are spotted.
isWithinFieldOfView(obj: GameObj, direction?: Vec2, fieldOfView?: number): boolean
Returns true if the object is within the field of view.
paramobjThe object to test.
paramdirectionThe direction to look at.
paramfieldOfViewThe field of view in degrees.
Returns true if there is a line of sight to the object.
paramobjThe object to test.
Options for the sentry component.
groupComponent Types
The tile component.
groupComponent Types
The tile position inside the level.
If the tile is an obstacle in pathfinding.
How much a tile is cost to traverse in pathfinding (default 0).
If the tile has hard edges that cannot pass in pathfinding.
Position offset when setting `tilePos`.
getLevel(): GameObj<LevelComp>
tileMove(dir: Vec2): void
TileCompOpt: If the tile is an obstacle in pathfinding.
cost?: number
How much a tile is cost to traverse in pathfinding (default 0).
If the tile has hard edges that cannot pass in pathfinding.
Position offset when setting `tilePos`.
Options for the tile component.
groupComponent Types
The health component.
groupComponent Types
hurt(n?: number): void
Decrease HP by n (defaults to 1).
heal(n?: number): void
Increase HP by n (defaults to 1).
hp(): number
Current health points.
setHP(hp: number): void
Set current health points.
maxHP(): number | null
Max amount of HP.
setMaxHP(hp: number): void
Set max amount of HP.
onHurt(action: (amount?: number)=>void): KEventController
Register an event that runs when hurt() is called upon the object.
sincev2000.1
onHeal(action: (amount?: number)=>void): KEventController
Register an event that runs when heal() is called upon the object.
sincev2000.1
onDeath(action: ()=>void): KEventController
Register an event that runs when object's HP is equal or below 0.
sincev2000.1
The lifespan component.
groupComponent Types
fade?: number
Fade out duration (default 0 which is no fade out).
The named component.
groupComponent Types
The state component.
groupComponent Types
Current state.
enterState(state: string, args: any): void
Enter a state, trigger onStateEnd for previous state and onStateEnter for the new State state.
onStateTransition(from: string, to: string, action: ()=>void): KEventController
Register event that runs once when a specific state transition happens. Accepts arguments passed from `enterState(name, ...args)`.
sincev2000.2
onStateEnter(state: string, action: (args: any)=>void): KEventController
Register event that runs once when enters a specific state. Accepts arguments passed from `enterState(name, ...args)`.
onStateEnd(state: string, action: ()=>void): KEventController
Register an event that runs once when leaves a specific state.
onStateUpdate(state: string, action: ()=>void): KEventController
Register an event that runs every frame when in a specific state.
onStateDraw(state: string, action: ()=>void): KEventController
Register an event that runs every frame when in a specific state.
The stay component.
groupComponent Types
stay: boolean
If the obj should not be destroyed on scene switch.
Array of scenes that the obj will stay on.
The textInput component.
groupComponent Types
Enable the text input array from being modified by user input.
The "real" text that the user typed, without any escaping.
The timer component.
groupComponent Types
The maximum number of loops per frame allowed,
to keep loops with sub-frame intervals from freezing the game.
wait(time: number, action?: ()=>void): TimerController
Run the callback after n seconds.
loop(time: number, action: ()=>void, maxLoops?: number, waitFirst?: boolean): TimerController
Run the callback every n seconds.
If waitFirst is false (the default), the function will
be called once on the very next frame, and then loop like normal.
sincev3000.0
tween<V>(from: V, to: V, duration: number, setValue: (value: V)=>void, easeFunc?: (t: number)=>number): TweenController
Tweeeeen! Note that this doesn't specifically mean tweening on this object's property, this just registers the timer on this object, so the tween will cancel with the object gets destroyed, or paused when obj.paused is true.
sincev3000.0
The area component.
groupComponent Types
area: shape: Shape | null
If we use a custom shape over render shape.
Area scale.
Area offset.
cursor: Cursor | null
Cursor on hover.
Collider area info.
If this object should ignore collisions against certain other objects.
sincev3000.0
If was just clicked on last frame.
If is being hovered on.
checkCollision(other: GameObj): Collision | null
Check collision with another game obj.
sincev3000.0
Get all collisions currently happening.
sincev3000.0
If is currently colliding with another game obj.
If is currently overlapping with another game obj (like isColliding, but will return false if the objects are just touching edges).
onClick(f: ()=>void, btn?: MouseButton): KEventController
Register an event runs when clicked.
sincev2000.1
onHover(action: ()=>void): KEventController
Register an event runs once when hovered.
sincev3000.0
onHoverUpdate(action: ()=>void): KEventController
Register an event runs every frame when hovered.
sincev3000.0
onHoverEnd(action: ()=>void): KEventController
Register an event runs once when unhovered.
sincev3000.0
onCollide(tag: Tag, f: (obj: GameObj, col?: Collision)=>void): KEventController
Register an event runs once when collide with another game obj with certain tag.
sincev2001.0
onCollide(f: (obj: GameObj, col?: Collision)=>void): KEventController
Register an event runs once when collide with another game obj.
sincev2000.1
onCollideUpdate(tag: Tag, f: (obj: GameObj, col?: Collision)=>KEventController): KEventController
Register an event runs every frame when collide with another game obj with certain tag.
sincev3000.0
onCollideUpdate(f: (obj: GameObj, col?: Collision)=>void): KEventController
Register an event runs every frame when collide with another game obj.
sincev3000.0
onCollideEnd(tag: Tag, f: (obj: GameObj)=>void): KEventController
Register an event runs once when stopped colliding with another game obj with certain tag.
sincev3000.0
onCollideEnd(f: (obj: GameObj)=>void): void
Register an event runs once when stopped colliding with another game obj.
sincev3000.0
hasPoint(p: Vec2): boolean
If has a certain point inside collider.
Push out from another solid game obj if currently overlapping.
Get the geometry data for the collider in local coordinate space.
sincev3000.0
Get the geometry data for the collider in world coordinate space.
Get the geometry data for the collider in screen coordinate space.
Options for the area component.
groupComponent Types
The shape of the area (currently only Rect and Polygon is supported).
add([
sprite("butterfly"),
pos(100, 200),
// a triangle shape!
area({ shape: new Polygon([vec2(0), vec2(100), vec2(-100, 100)]) }),
])
scale?: number | Vec2
Area scale.
Area offset.
Cursor on hover.
If this object should ignore collisions against certain other objects.
sincev3000.0
The body component.
groupComponent Types
Object current velocity.
sincev3001.0
How much velocity decays (velocity *= (1 - drag) every frame).
sincev3001.0
If object is static, it won't move, all non static objects won't move past it, and all
calls to addForce(), applyImpulse(), or jump() on this body will do absolutely nothing.
Initial speed in pixels per second for jump().
Gravity multiplier.
Mass of the body, decides how much a non-static body should move when resolves with another non-static body. (default 1).
sincev3000.0
If object should move with moving platform (default true).
sincev3000.0
Current platform landing on.
If currently landing on a platform.
sincev2000.1
If currently falling.
sincev2000.1
If currently rising.
sincev3000.0
Applies an impulse
paramimpulseThe impulse vector, applied directly
addForce(force: Vec2): void
Applies a force
paramforceThe force vector, applied after scaled by the inverse mass
jump(force?: number): void
Upward thrust.
onPhysicsResolve(action: (col: Collision)=>void): KEventController
Register an event that runs when a collision is resolved.
sincev3000.0
onBeforePhysicsResolve(action: (col: Collision)=>void): KEventController
Register an event that runs before a collision would be resolved.
sincev3000.0
onGround(action: ()=>void): KEventController
Register an event that runs when the object is grounded.
sincev2000.1
onFall(action: ()=>void): KEventController
Register an event that runs when the object starts falling.
sincev2000.1
onFallOff(action: ()=>void): KEventController
Register an event that runs when the object falls off platform.
sincev3000.0
onHeadbutt(action: ()=>void): KEventController
Register an event that runs when the object bumps into something on the head.
sincev2000.1
onLand(action: (obj: GameObj)=>void): KEventController
Register an event that runs when an object lands on this object.
sincev3001.0
onHeadbutted(action: (obj: GameObj)=>void): KEventController
Register an event that runs when the object is bumped by another object head.
Options for the body component.
groupComponent Types
drag?: number
How much velocity decays (velocity *= (1 - drag) every frame).
sincev3001.0
Initial speed in pixels per second for jump().
Maximum velocity when falling.
Gravity multiplier.
If object is static, it won't move, all non static objects won't move past it, and all
calls to addForce(), applyImpulse(), or jump() on this body will do absolutely nothing.
sincev3000.0
If object should move with moving platform (default true).
sincev3000.0
mass?: number
Mass of the body, decides how much a non-static body should move when resolves with another non-static body. (default 1).
sincev3000.0
The doubleJump component.
groupComponent Types
Number of jumps allowed.
doubleJump(force?: number): void
Performs double jump (the initial jump only happens if player is grounded).
onDoubleJump(action: ()=>void): KEventController
Register an event that runs when the object performs the second jump when double jumping.
The anchor component.
groupComponent Types
anchor: Anchor | Vec2
Anchor point for render.
The follow component.
groupComponent Types
follow: obj: GameObj
The object to follow.
The offset to follow the object by.
The layer component.
groupComponent Types
Get the index of the current layer the object is assigned to.
returnsThe index of the layer the object is assigned to, or `null` if the layer does not exist.
layer(): string | null
Get the name of the current layer the object is assigned to.
returnsThe name of the layer the object is assigned to.
layer(name: string):
Set the name of the layer the object should be assigned to.
The offscreen component.
groupComponent Types
The minimum distance that the object must be off the screen by to be considered "offscreen".
If it is undefined, it means that the object will be considered to be offscreen when its bounding rectangle
(defined by width and height) is not intersecting with the screen rectangle.
If object is currently out of view.
onExitScreen(action: ()=>void): KEventController
Register an event that runs when object goes out of view.
onEnterScreen(action: ()=>void): KEventController
Register an event that runs when object enters view.
Options for offscreen component.
groupComponent Types
hide?: boolean
If hide object when out of view.
If pause object when out of view.
If unpause object when back in view.
If destroy object when out of view.
The distance when out of view is triggered (default 200).
sincev3000.0
The rotate component.
groupComponent Types
Angle in degrees.
rotateBy(angle: number): void
Rotate in degrees.
rotateTo(s: number): void
Rotate to a degree (like directly assign to .angle)
sincev3000.0
The scale component.
groupComponent Types
The current scale of the object
returnsThe current scale of the object as a
scaleTo(s: number): void
Set the scale of the object to a number
scaleTo(s: Vec2): void
Set the scale of the object to a Vec2
scaleTo(sx: number, sy: number): void
Set the scale of the object to a number for x and y
scaleBy(s: number): void
Scale the object by a number
scaleBy(s: Vec2): void
Scale the object by a Vec2
scaleBy(sx: number, sy: number): void
Scale the object by a number for x and y
The z component.
groupComponent Types
z: number
Defines the z-index of this game obj
MergeComps<T>: Omit<MergeObj, TypeOperator>
A type to merge the components of a game object, omitting the default component properties.
groupComponent Types
CompList<T>: Array<T | Tag>
A component list.
groupComponent Types
A component without own properties.
groupComponent Types
A level component.
groupComponent Types
spawn(sym: string, p: Vec2): GameObj | null
Spawn a tile from a symbol defined previously.
spawn(sym: string, x: number, y: number): GameObj | null
spawn<T>(obj: CompList, p: Vec2): GameObj | null
Spawn a tile from a component list.
returnsThe spawned game object, or null if the obj hasn't components.
spawn<T>(sym: CompList, x: number, y: number): GameObj | null
Total width of level in pixels.
Total height of level in pixels.
getAt(tilePos: Vec2): GameObj[]
Get all game objects that's currently inside a given tile.
raycast(origin: Vec2, direction: Vec2): RaycastResult
Raycast all game objects on the given path.
tile2Pos(tilePos: Vec2): Vec2
Convert tile position to pixel position.
tile2Pos(x: number, y: number): Vec2
pos2Tile(pos: Vec2): Vec2
Convert pixel position to tile position.
pos2Tile(x: number, y: number): Vec2
getTilePath(from: Vec2, to: Vec2, opts?: PathFindOpt): Vec2[] | null
Find the path to navigate from one tile to another tile.
returnsA list of traverse points in tile positions.
getPath(from: Vec2, to: Vec2, opts?: PathFindOpt): Vec2[] | null
Find the path to navigate from one tile to another tile.
returnsA list of traverse points in pixel positions.
Gets the name of the current scene. Returns null if no scene is active.
sincev3001.0
groupScene
scene(name: SceneName, def: SceneDef): void
Define a scene.
paramname- The scene name.
paramdef- The scene definition.
// define a scene
scene("game", () => {
// ...
});
// get options
scene("game", (opts) => {
debug.log(opts.level);
});
groupScene
go(name: SceneName, args: any): void
Go to a scene, passing all rest args to scene callback.
paramname- The scene name.
paramargs- The rest args to pass to the scene callback.
// go to "game" scene
go("game");
// go with options
go("game", { level: 1 });
sincev2000.0
groupScene
layers(layers: string[], defaultLayer: string): void
paramlayers- The layer names.
paramdefaultLayer- The default layer name.
deprecatedUse
setLayers(["bg", "obj", "ui"], "obj")
// no layer specified, will be added to "obj"
add([
sprite("bean"),
]);
// add to "bg" layer
add([
sprite("bg"),
layer("bg"),
]);
sincev3001.0
groupScene
onGamepadConnect(action: (gamepad: KGamepad)=>void): void
Register an event that runs when a gamepad is connected.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3000.0
groupInput
onGamepadDisconnect(action: (gamepad: KGamepad)=>void): void
Register an event that runs when a gamepad is disconnected.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3000.0
groupInput
onClick(tag: Tag, action: (a: GameObj)=>void): KEventController
Register an event that runs when game objs with certain tags are clicked (required to have the area() component).
paramtag- The tag to listen for.
paramaction- The function to run when the event is triggered.
// click on any "chest" to open
onClick("chest", (chest) => chest.open())
returnsThe event controller.
sincev2000.1
groupInput
onClick(action: ()=>void): KEventController
Register an event that runs when users clicks.
paramaction- The function to run when the event is triggered.
// click on anywhere to go to "game" scene
onClick(() => go("game"));
returnsThe event controller.
sincev2000.1
groupEvents
onKeyDown(key: Key | Key[], action: (key: Key)=>void): KEventController
Register an event that runs every frame when a key is held down.
paramkey- The key(s) to listen for.
paramaction- The function to run when the event is triggered.
// move left by SPEED pixels per frame every frame when left arrow key is being held down
onKeyDown("left", () => {
bean.move(-SPEED, 0)
});
returnsThe event controller.
sincev2000.1
groupInput
onKeyDown(action: (key: Key)=>void): KEventController
Register an event that runs every frame when any key is held down.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev2000.1
groupInput
onKeyPress(key: Key | Key[], action: (key: Key)=>void): KEventController
Register an event that runs when user presses certain keys.
paramkey- The key(s) to listen for.
paramaction- The function to run when the event is triggered.
// .jump() once when "space" is just being pressed
onKeyPress("space", () => {
bean.jump();
});
onKeyPress(["up", "space"], () => {
bean.jump();
});
returnsThe event controller.
sincev2000.1
groupInput
onKeyPress(action: (key: Key)=>void): KEventController
Register an event that runs when user presses any key.
paramaction- The function to run when the event is triggered.
// Call restart() when player presses any key
onKeyPress((key) => {
debug.log(`key pressed ${key}`);
restart();
});
returnsThe event controller.
sincev3001.0
groupInput
onKeyPressRepeat(k: Key | Key[], action: (k: Key)=>void): KEventController
Register an event that runs when user presses certain keys (also fires repeatedly when the keys are being held down).
paramk- The key(s) to listen for.
paramaction- The function to run when the event is triggered.
// delete last character when "backspace" is being pressed and held
onKeyPressRepeat("backspace", () => {
input.text = input.text.substring(0, input.text.length - 1);
});
returnsThe event controller.
sincev3000.1
groupInput
onKeyPressRepeat(action: (k: Key)=>void): KEventController
onKeyRelease(k: Key | Key[], action: (k: Key)=>void): KEventController
Register an event that runs when user release certain keys.
paramk- The key(s) to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev2000.1
groupInput
onKeyRelease(action: (k: Key)=>void): KEventController
onCharInput(action: (ch: string)=>void): KEventController
Register an event that runs when user inputs text.
paramaction- The function to run when the event is triggered.
// type into input
onCharInput((ch) => {
input.text += ch
})
returnsThe event controller.
sincev2000.1
groupInput
onMouseDown(btn: MouseButton | MouseButton[], action: (m: MouseButton)=>void): KEventController
Register an event that runs every frame when certain mouse buttons are being held down.
parambtn- The button(s) to listen for.
returnsThe event controller.
sincev3001.0
groupInput
onMouseDown(action: (m: MouseButton)=>void): KEventController
onMousePress(action: (m: MouseButton)=>void): KEventController
Register an event that runs when user clicks mouse.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3001.0
groupInput
onMousePress(btn: MouseButton | MouseButton[], action: (m: MouseButton)=>void): KEventController
onMouseRelease(action: (m: MouseButton)=>void): KEventController
Register an event that runs when user releases mouse.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3001.0
groupInput
onMouseRelease(btn: MouseButton | MouseButton[], action: (m: MouseButton)=>void): KEventController
onMouseMove(action: (pos: Vec2, delta: Vec2)=>void): KEventController
Register an event that runs whenever user move the mouse.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev2000.1
groupInput
onTouchStart(action: (pos: Vec2, t: Touch)=>void): KEventController
Register an event that runs when a touch starts.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev2000.1
groupInput
onTouchMove(action: (pos: Vec2, t: Touch)=>void): KEventController
Register an event that runs whenever touch moves.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev2000.1
groupInput
onTouchEnd(action: (pos: Vec2, t: Touch)=>void): KEventController
Register an event that runs when a touch ends.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev2000.1
groupInput
onScroll(action: (delta: Vec2)=>void): KEventController
Register an event that runs when mouse wheel scrolled.
paramaction- The function to run when the event is triggered.
// Zoom camera on scroll
onScroll((delta) => {
const zoom = delta.y / 500;
camScale(camScale().add(zoom));
});
returnsThe event controller.
sincev3000.0
groupInput
onGamepadButtonDown(btn: KGamepadButton | KGamepadButton[], action: (btn: KGamepadButton, gamepad: KGamepad)=>void): KEventController
Register an event that runs every frame when certain gamepad buttons are held down.
parambtn- The button(s) to listen for.
paramaction- The function to run when the event is triggered.
returnThe event controller.
sincev3001.0
groupInput
onGamepadButtonDown(action: (btn: KGamepadButton, gamepad: KGamepad)=>void): KEventController
Register an event that runs every frame when any gamepad buttons are held down.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3001.0
groupInput
onGamepadButtonPress(btn: KGamepadButton | KGamepadButton[], action: (btn: KGamepadButton, gamepad: KGamepad)=>void): KEventController
Register an event that runs when user presses certain gamepad button.
parambtn- The button(s) to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3001.0
groupInput
onGamepadButtonPress(action: (btn: KGamepadButton, gamepad: KGamepad)=>void): KEventController
Register an event that runs when user presses any gamepad button.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3001.0
groupInput
onGamepadButtonRelease(btn: KGamepadButton | KGamepadButton[], action: (btn: KGamepadButton, gamepad: KGamepad)=>void): KEventController
Register an event that runs when user releases certain gamepad button
parambtn- The button(s) to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3001.0
groupInput
onGamepadButtonRelease(action: (btn: KGamepadButton, gamepad: KGamepad)=>void): KEventController
Register an event that runs when user releases any gamepad button.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3000.0
groupInput
onGamepadStick(stick: GamepadStick, action: (value: Vec2, gameepad: KGamepad)=>void): KEventController
Register an event that runs when the gamepad axis exists.
paramstick- The stick to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3000.0
groupInput
onButtonPress(btn: TButton | TButton[], action: (btn: TButton)=>void): KEventController
Register an event that runs when user press a defined button
(like "jump") on any input (keyboard, gamepad).
parambtn- The button(s) to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3001.0
groupInput
onButtonRelease(btn: TButton | TButton[], action: (btn: TButton)=>void): KEventController
Register an event that runs when user release a defined button
(like "jump") on any input (keyboard, gamepad).
parambtn- The button(s) to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3001.0
groupInput
onButtonRelease(action: (btn: TButton)=>void): KEventController
onButtonDown(btn: TButton | TButton[], action: (btn: TButton)=>void): KEventController
Register an event that runs when user press a defined button
(like "jump") on any input (keyboard, gamepad).
parambtn- The button(s) to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3001.0
groupInput
onButtonDown(action: (btn: TButton)=>void): KEventController
Is currently on a touch screen device.
returnstrue if on a touch screen device.
sincev3000.0
groupInput
Get current mouse position (without camera transform).
returnsThe current mouse position.
sincev2000.0
groupInput
How much mouse moved last frame.
returnsThe delta mouse position.
sincev2000.0
groupInput
isKeyDown(k?: Key | Key[]): boolean
If any or certain key(s) are currently down.
paramk- The key(s) to check.
// Any key down
let lastKeyTime = time()
let triedToWakeUp = false
onUpdate(() => {
if (isKeyDown()) {
lastKeyTime = time()
triedToWakeUp = false
return
}
if (triedToWakeUp || time() - lastKeyTime < 5) return
debug.log("Wake up!")
triedToWakeUp = true
})
// Certain key down
// equivalent to the calling bean.move() in an onKeyDown("left")
onUpdate(() => {
if (isKeyDown("left")) {
bean.move(-SPEED, 0)
}
})
// Certain keys down
let isMoving = false
onUpdate(() => {
isMoving = isKeyDown(["left", "right"])
})
sincev2000.0
groupInput
isKeyPressed(k?: Key | Key[]): boolean
If any or certain key(s) are just pressed last frame.
paramk- The key(s) to check.
onUpdate(() => {
if (!isKeyPressed()) return // early return as no key was pressed
if (isKeyPressed("space")) debug.log("Pressed the jump key")
if (isKeyPressed(["left", "right"])) debug.log("Pressed any of the move keys")
})
sincev2000.0
groupInput
If any or certain key(s) are just pressed last frame (also fires repeatedly when the keys are being held down).
paramk- The key(s) to check.
let heldKeys = new Set()
onUpdate(() => {
if (isKeyPressedRepeat("space")) {
pressedOrHeld(["space"], 'the jump key')
} else if (isKeyPressedRepeat(["left", "right"])) {
pressedOrHeld(["left", "right"], 'any of the move keys')
} else if (isKeyPressedRepeat()) {
pressedOrHeld(["any"], 'any key')
}
})
onKeyRelease((key) => wait(0.1, () => {
heldKeys.delete(key)
heldKeys.delete("any")
}))
// log message if pressed only or held as well
function pressedOrHeld(keys, string) {
debug.log(`Pressed${keys.some(key => heldKeys.has(key)) ? ' and held' : ''} ${string}`)
keys.forEach((key) => {
if (key == "any" || isKeyDown(key)) heldKeys.add(key)
})
}
sincev2000.0
groupInput
If any or certain key(s) are just released last frame.
paramk- The key(s) to check.
onUpdate(() => {
if (!isKeyReleased()) return // early return as no key was released
if (isKeyReleased("space")) debug.log("Released the jump key")
if (isKeyReleased(["left", "right"])) debug.log("Released any of the move keys")
})
sincev2000.0
groupInput
isMouseDown(btn?: MouseButton | MouseButton[]): boolean
If mouse buttons are currently down.
parambtn- The button(s) to check.
sincev2000.0
groupInput
isMousePressed(btn?: MouseButton | MouseButton[]): boolean
If mouse buttons are just clicked last frame
parambtn- The button(s) to check.
sincev2000.0
groupInput
isMouseReleased(btn?: MouseButton | MouseButton[]): boolean
If mouse buttons are just released last frame.
parambtn- The button(s) to check.
sincev2000.0
groupInput
If mouse moved last frame.
sincev2000.1
groupInput
isGamepadButtonPressed(btn?: KGamepadButton | KGamepadButton[]): boolean
If certain gamepad buttons are just pressed last frame
parambtn- The button(s) to check.
sincev3000.0
groupInput
isGamepadButtonDown(btn?: KGamepadButton | KGamepadButton): boolean
If certain gamepad buttons are currently held down.
parambtn- The button(s) to check.
sincev3000.0
groupInput
isGamepadButtonReleased(btn?: KGamepadButton | KGamepadButton[]): boolean
If certain gamepad buttons are just released last frame.
parambtn- The button(s) to check.
sincev3000.0
groupInput
isButtonPressed(btn?: TButton | TButton[]): boolean
If any or certain bound button(s) are just pressed last frame on any input (keyboard, gamepad).
parambtn- The button(s) to check.
onUpdate(() => {
if (!isButtonPressed()) return // early return as no button was pressed
if (isButtonPressed("jump")) debug.log("Player jumped")
if (isButtonPressed(["left", "right"])) debug.log("Player moved")
})
sincev3001.0
groupInput
isButtonDown(btn?: TButton | TButton[]): boolean
If any or certain bound button(s) are currently held down on any input (keyboard, gamepad).
parambtn- The button(s) to check.
onUpdate(() => {
if (!isButtonDown()) return // early return as no button is held down
if (isButtonDown("jump")) debug.log("Player is jumping")
if (isButtonDown(["left", "right"])) debug.log("Player is moving")
})
sincev3001.0
groupInput
isButtonReleased(btn?: TButton | TButton[]): boolean
If any or certain bound button(s) are just released last frame on any input (keyboard, gamepad).
parambtn- The button(s) to check.
onUpdate(() => {
if (!isButtonReleased()) return // early return as no button was released
if (isButtonReleased("jump")) debug.log("Player stopped jumping")
if (isButtonReleased(["left", "right"])) debug.log("Player stopped moving")
})
sincev3001.0
groupInput
getButton(btn: TypeOperator): ButtonBinding
Get a input binding from a button name.
parambtn- The button to get binding for.
sincev3001.0
groupInput
setButton(btn: string, def: ButtonBinding): void
Set a input binding for a button name.
parambtn- The button to set binding for.
sincev3001.0
groupInput
Press a button virtually.
parambtn- The button to press.
// press "jump" button
pressButton("jump"); // triggers onButtonPress, starts onButtonDown
releaseButton("jump"); // triggers onButtonRelease, stops onButtonDown
sincev3001.0
groupInput
Release a button virtually.
parambtn- The button to release.
// press "jump" button
pressButton("jump"); // triggers onButtonPress, starts onButtonDown
releaseButton("jump"); // triggers onButtonRelease, stops onButtonDown
sincev3001.0
groupInput
Get stick axis values from a gamepad.
paramstick- The stick to get values from.
returnsThe stick axis Vec2.
sincev3001.0
groupInput
Get the latest input device type that triggered the input event.
returnsThe last input device type, or null if no input event has been triggered.
sincev3001.0
groupInput
List of characters inputted since last frame.
returnnsAn array of characters inputted.
sincev3000.0
groupInput
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" | string & {}
A key.
groupInput
MouseButton: "left" | "right" | "middle" | "back" | "forward"
A mouse button.
groupInput
KGamepadButton: "north" | "east" | "south" | "west" | "ltrigger" | "rtrigger" | "lshoulder" | "rshoulder" | "select" | "start" | "lstick" | "rstick" | "dpad-up" | "dpad-right" | "dpad-down" | "dpad-left" | "home" | "capture"
A gamepad button.
groupInput
A gamepad stick.
groupInput
A controller for all events in KAPLAY.
// Create a new event
const logHi = onUpdate(() => {
debug.log("hi");
});
// Pause the event
logHi.paused = true;
// Cancel the event
logHi.cancel();
groupEvents
If the event is paused
Cancel the event
join(events: KEventController[]): KEventController
replace(oldEv: KEventController, newEv: KEventController): KEventController
Game Object events with their arguments.
If looking for use it with `obj.on()`, ignore first parameter (Game Obj)
groupEvents
trigger(event: string, tag: string, args: any): void
Trigger an event on all game objs with certain tag.
paramevent- The tag to trigger to.
paramtag- Arguments to pass to the `on()` functions
trigger("shoot", "target", 140);
on("shoot", "target", (obj, score) => {
obj.destroy();
debug.log(140); // every bomb was 140 score points!
});
sincev3001.0.6
groupEvents
experimentalThis feature is in experimental phase, it will be fully released in v3001.1.0
on<Ev>(event: Ev, tag: Tag, action: (obj: GameObj, args: TupleWithoutFirst)=>void): KEventController
Register an event on all game objs with certain tag.
paramevent- The tag to listen for.
paramtag- The function to run when the event is triggered.
// a custom event defined by body() comp
// every time an obj with tag "bomb" hits the floor, destroy it and addKaboom()
on("ground", "bomb", (bomb) => {
destroy(bomb)
addKaboom(bomb.pos)
})
// a custom event can be defined manually
// by passing an event name, a tag, and a callback function
// if you want any tag, use a tag of "*"
on("talk", "npc", (npc, message) => {
npc.add([
text(message),
pos(0, -50),
lifespan(2),
opacity(),
])
});
onKeyPress("space", () => {
// the trigger method on game objs can be used to trigger a custom event
npc.trigger("talk", "Hello, KAPLAY!");
});
returnsThe event controller.
sincev2000.0
groupEvents
onFixedUpdate(action: ()=>void): KEventController
Register an event that runs at a fixed framerate.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3001.0
groupEvents
onFixedUpdate(tag: Tag, action: (obj: GameObj)=>void): KEventController
onUpdate(tag: Tag, action: (obj: GameObj)=>void): KEventController
Register an event that runs every frame (~60 times per second) for all game objs with certain tag.
paramtag- The tag to listen for.
paramaction- The function to run when the event is triggered.
// 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)
}
})
returnsThe event controller.
sincev2000.1
groupEvents
onUpdate(action: ()=>void): KEventController
Register an event that runs every frame (~60 times per second).
paramaction- The function to run when the event is triggered.
// This will run every frame
onUpdate(() => {
debug.log("ohhi")
})
returnsThe event controller.
sincev2000.1
groupEvents
onDraw(tag: Tag, action: (obj: GameObj)=>void): KEventController
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).
paramtag- The tag to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev2000.1
groupEvents
onDraw(action: ()=>void): KEventController
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).
onDraw(() => {
drawLine({
p1: vec2(0),
p2: mousePos(),
color: rgb(0, 0, 255),
})
})
returnsThe event controller.
sincev2000.1
groupEvents
onAdd(tag: Tag, action: (obj: GameObj)=>void): KEventController
Register an event that runs when a game obj with certain tag is created.
paramtag- The tag to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev2000.0
groupEvents
onAdd(action: (obj: GameObj)=>void): KEventController
Register an event that runs when a game obj is created.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev2000.0
groupEvents
onDestroy(tag: Tag, action: (obj: GameObj)=>void): KEventController
Register an event that runs when a game obj with certain tag is destroyed.
paramtag- The tag to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev2000.0
groupEvents
onDestroy(action: (obj: GameObj)=>void): KEventController
Register an event that runs when a game obj is destroyed.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
groupEvents
onUse(action: (obj: GameObj, id: string)=>void): KEventController
Register an event that runs when an object starts using a component.
paramaction- The function that runs when an object starts using component.
paramunknown- The id of the component that was added.
returnsThe event controller.
sincev3001.10
groupEvents
onUnuse(action: (obj: GameObj, id: string)=>void): KEventController
Register an event that runs when an object stops using a component.
paramaction- The function that runs when an object stops using a component.
paramunknown- The id of the component that was removed.d
returnsThe event controller.
sincev3001.10
groupEvents
onTag(action: (obj: GameObj, tag: string)=>void): KEventController
Register an event that runs when an object gains a tag.
paramaction- The function that runs when an object gains a tag.
paramunknown- The tag which was added.
returnsThe event controller.
sincev3001.10
groupEvents
onUntag(action: (obj: GameObj, tag: string)=>void): KEventController
Register an event that runs when an object loses a tag.
paramaction- The function that runs when an object loses a tag.
paramunknown- The tag which was removed.
returnsThe event controller.
sincev3001.10
groupEvents
onLoad(action: ()=>void): void
Register an event that runs when all assets finished loading.
paramaction- The function to run when the event is triggered.
const bean = add([
sprite("bean"),
])
// certain assets related data are only available when the game finishes loading
onLoad(() => {
debug.log(bean.width)
})
returnsThe event controller.
sincev2000.1
groupEvents
onLoadError(action: (name: string, failedAsset: Asset)=>void): KEventController | undefined
Register an event that runs once for each asset that failed to load,
after all others have completed.
paramactionThe function to run when the event is triggered.
// this will not load
loadSprite("bobo", "notavalidURL");
// process the error
// you decide whether to ignore it, or throw an error and halt the game
onLoadError((name, asset) => {
debug.error(`${name} failed to load: ${asset.error}`);
})
returnsThe event controller.
sincev3001.0
groupEvents
onLoading(action: (progress: number)=>void): void
Register an event that runs every frame when assets are initially loading. Can be used to draw a custom loading screen.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3000.0
groupEvents
onError(action: (err: Error)=>void): void
Register a custom error handler. Can be used to draw a custom error screen.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3000.0
groupEvents
onResize(action: ()=>void): void
Register an event that runs when the canvas resizes.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3000.0
groupEvents
onCleanup(action: ()=>void): void
Cleanup function to run when quit() is called.
paramaction- The function to run when the event is triggered.
sincev3000.0
groupEvents
onCollide(t1: Tag, t2: Tag, action: (a: GameObj, b: GameObj, col?: Collision)=>void): KEventController
Register an event that runs once when 2 game objs with certain tags collides (required to have area() component).
paramt1- The tag of the first game obj.
paramt2- The tag of the second game obj.
paramaction- The function to run when the event is triggered.
onCollide("sun", "earth", () => {
addExplosion()
})
returnsThe event controller.
sincev2000.1
groupEvents
onCollideUpdate(t1: Tag, t2: Tag, action: (a: GameObj, b: GameObj, col?: Collision)=>void): KEventController
Register an event that runs every frame when 2 game objs with certain tags collides (required to have area() component).
paramt1- The tag of the first game obj.
paramt2- The tag of the second game obj.
paramaction- The function to run when the event is triggered.
onCollideUpdate("sun", "earth", () => {
debug.log("okay this is so hot");
})l
returnsThe event controller.
sincev3000.0
groupEvents
onHover(tag: Tag, action: (a: GameObj)=>void): KEventController
Register an event that runs once when game objs with certain tags are hovered (required to have area() component).
paramtag- The tag to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3000.0
groupEvents
onHoverUpdate(tag: Tag, action: (a: GameObj)=>void): KEventController
Register an event that runs every frame when game objs with certain tags are hovered (required to have area() component).
paramtag- The tag to listen for.
paramaction- The function to run when the event is triggered.
// Rotate bean 90 degrees per second when hovered
onHoverUpdate("bean", (bean) => {
bean.angle += dt() * 90
});
returnsThe event controller.
sincev3000.0
groupEvents
onHoverEnd(tag: Tag, action: (a: GameObj)=>void): KEventController
Register an event that runs once when game objs with certain tags are unhovered (required to have area() component).
paramtag- The tag to listen for.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3000.0
groupEvents
onHide(action: ()=>void): KEventController
Register an event that runs when tab is hidden.
returnsThe event controller.
sincev3001.0
groupEvents
onShow(action: ()=>void): KEventController
Register an event that runs when tab is shown.
returnsThe event controller.
sincev3001.0
groupEvents
onSceneLeave(action: (newScene?: string)=>void): KEventController
Register an event that runs when current scene ends.
paramaction- The function to run when the event is triggered.
returnsThe event controller.
sincev3000.0
groupEvents
add(action: (args: Args)=>unknown): KEventController
addOnce(action: (args: Args | PromiseLike[])=>void): KEventController
next(): Promise<Args>
trigger(args: Args): void
registers: Partial<MappedType>
on<Name>(name: Name, action: (args: EventMap[Name])=>void): KEventController
onOnce<Name>(name: Name, action: (args: EventMap[Name])=>void): KEventController
next<Name>(name: Name): Promise<unknown>
trigger<Name>(name: Name, args: EventMap[Name]): void
remove<Name>(name: Name): void
numListeners<Name>(name: Name): number
A controller for all events in KAPLAY.
// Create a new event
const logHi = onUpdate(() => {
debug.log("hi");
});
// Pause the event
logHi.paused = true;
// Cancel the event
logHi.cancel();
groupEvents
If the event is paused
Cancel the event
join(events: KEventController[]): KEventController
replace(oldEv: KEventController, newEv: KEventController): KEventController
Cancels the event by returning the cancel symbol.
onKeyPress((key) => {
if (key === "q") return cancel();
});
returnsThe cancel event symbol.
sincev3001.0.5
groupEvents
experimentalThis feature is in experimental phase, it will be fully released in v4000.0
Get the width of game.
returnsThe width of the game.
sincev2000.0
groupInfo
Get the root of all objects.
returnsThe root object.
sincev2000.0
groupInfo
Get the height of game.
returnsThe height of the game.
sincev2000.0
groupInfo
Get the center point of view.
// add bean to the center of the screen
add([
sprite("bean"),
pos(center()),
// ...
])
returnsThe center point of the view.
sincev2000.0
groupInfo
dt(): number
Get the delta time since last frame.
// rotate bean 100 deg per second
bean.onUpdate(() => {
bean.angle += 100 * dt()
})
sincev2000.0
groupInfo
Get the fixed delta time since last frame.
sincev3000.0
groupInfo
Get the rest delta time since last frame.
sincev3000.0
groupInfo
time(): number
Get the total time since beginning.
sincev3001
groupInfo
If the game canvas is currently focused.
returnstrue if focused.
sincev2000.1
groupInfo
Set background color.
sincev3000.0
groupInfo
setBackground(color: Color, alpha: number): void
setBackground(r: number, g: number, b: number): void
setBackground(r: number, g: number, b: number, alpha: number): void
Get background color.
returnsThe background color.
sincev3000.0
groupInfo
Get connected gamepads.
returnsAn array of connected gamepads.
sincev3000.0
groupInfo
setCursor(style: Cursor): void
Set cursor style.
paramstyle- The cursor style.
// Change between cursor styles
// Reset cursor to default at start of every frame
onUpdate(() => setCursor("default"));
button.onHover((c) => {
// change cursor to pointer when hovering over button
setCursor("pointer")
})
// Hide the only cursor at start (useful for fakeMouse)
setCursor("none");
sincev2000.0
groupInfo
Get current cursor style.
returnsThe current cursor style.
sincev2000.0
groupInfo
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.
sincev2000.0
groupInfo
Get if cursor is currently locked.
returnstrue if locked, false otherwise.
sincev2000.0
groupInfo
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());
});
sincev2000.0
groupInfo
If currently in fullscreen mode.
returnstrue if fullscreen, false otherwise.
sincev2000.0
groupInfo
canvas: HTMLCanvasElement
The canvas DOM KAPLAY is currently using.
sincev2000.0
groupInfo
Current KAPLAY library version.
sincev3000.0
groupInfo
wait(n: number, action?: ()=>void): TimerController
Run the function after n seconds.
paramn- The time to wait in seconds.
paramaction- The function to run.
// 3 seconds until explosion! Runnn!
wait(3, () => {
explode()
})
// wait() returns a PromiseLike that can be used with await
await wait(1)
returnsA timer controller.
sincev2000.0
groupTimer
loop(t: number, action: ()=>void, maxLoops?: number, waitFirst?: boolean): TimerController
Run the function every n seconds.
paramt- The time to wait in seconds.
paramaction- The function to run.
parammaxLoops- The maximum number of loops to run. If not provided, it will run forever.
paramwaitFirst- Whether to wait for the first loop to start.
// spawn a butterfly at random position every 1 second
loop(1, () => {
add([
sprite("butterfly"),
pos(rand(vec2(width(), height()))),
area(),
"friend",
])
})
returnsA timer controller.
sincev2000.0
groupTimer
TimerController: If the event handler is paused.
Cancel the event handler.
onEnd(action: ()=>void): void
Register an event when finished.
then(action: ()=>void): TimerController
groupTimer
TweenController: TimerController & Finish the tween now and cancel.
Event controller for tween.
groupTimer
0-255 RGBA color.
groupMath
r: number
Red (0-255.
g: number
Green (0-255).
b: number
Blue (0-255).
fromArray(arr: number[]): Color
fromHex(hex: string | number): Color
Create color from hex string or literal.
Color.fromHex(0xfcef8d)
Color.fromHex("#5ba675")
Color.fromHex("d46eb3")
sincev3000.0
fromHSL(h: number, s: number, l: number): Color
RED: Color
lighten(a: number): Color
Lighten the color (adds RGB by n).
darken(a: number): Color
Darkens the color (subtracts RGB by n).
mult(other: Color): Color
lerp(dest: Color, t: number): Color
Linear interpolate to a destination color.
sincev3000.0
toHSL():
[
number, number, number
]
Convert color into HSL format.
sincev3001.0
eq(other: Color): boolean
Return the hex string of color.
sincev3000.0
toArray(): Array<number>
Return the color converted to an array.
sincev3001.0
Vec2Args:
[
number, number
]
|
[
number
]
|
[
Vec2
]
|
[
number | Vec2
]
|
[
]
Possible arguments for a Vec2.
groupMath
A 2D vector.
groupMath
x: number
The x coordinate
y: number
The y coordinate
fromAngle(deg: number): Vec2
Create a new Vec2 from an angle in degrees
Create a new Vec2 from an array
An empty vector. (0, 0)
A vector with both components of 1. (1, 1)
A vector signaling to the left. (-1, 0)
A vector signaling to the right. (1, 0)
UP: Vec2
A vector signaling up. (0, -1)
A vector signaling down. (0, 1)
Clone the vector
add(args: Vec2Args): Vec2
Returns the addition with another vector.
sub(args: Vec2Args): Vec2
Returns the subtraction with another vector.
scale(args: Vec2Args): Vec2
Scale by another vector. or a single number
dist(args: Vec2Args): number
Get distance between another vector
sdist(args: Vec2Args): number
Get squared distance between another vector
sdist(v: Vec2, other: Vec2): number
Calculates the squared distance between the vectors
paramvThe vector
paramotherThe other vector
returnsThe distance between the vectors
len(): number
Get length of the vector
sincev3000.0
slen(): number
Get squared length of the vector
sincev3000.0
Get the unit vector (length of 1).
Get the perpendicular vector.
reflect(normal: Vec2): Vec2
Get the reflection of a vector with a normal.
sincev3000.0
project(on: Vec2): Vec2
Get the projection of a vector onto another vector.
sincev3000.0
reject(on: Vec2): Vec2
Get the rejection of a vector onto another vector.
sincev3000.0
dot(p2: Vec2): number
Get the dot product with another vector.
dot(v: Vec2, other: Vec2): number
Get the dot product between 2 vectors.
sincev3000.0
cross(p2: Vec2): number
Get the cross product with another vector.
sincev3000.0
cross(v: Vec2, other: Vec2): number
Get the cross product between 2 vectors.
sincev3000.0
angle(args: Vec2Args): number
Get the angle of the vector in degrees.
Get the angle between this vector and another vector.
sincev3000.0
lerp(dest: Vec2, t: number): Vec2
Linear interpolate to a destination vector (for positions).
slerp(dest: Vec2, t: number): Vec2
Spherical linear interpolate to a destination vector (for rotations).
sincev3000.0
If the vector (x, y) is zero.
sincev3000.0
toFixed(n: number): Vec2
To n precision floating point.
Multiply by a Mat4.
sincev3000.0
eq(other: Vec2): boolean
See if one vector is equal to another.
sincev3000.0
Converts the vector to a Rect with the vector as the origin.
sincev3000.0.
toArray(): Array<number>
Converts the vector to an array.
sincev3001.0
groupMath
x: number
y: number
w: number
h: number
scale(other: Quad): Quad
pos(): Vec2
eq(other: Quad): boolean
groupMath
m: number[]
scale(s: Vec2): Mat4
scale(p: Vec2): this
rotateX(a: number): Mat4
rotateY(a: number): Mat4
rotateZ(a: number): Mat4
rotate(a: number): Mat4
mult(other: Mat4): Mat4
groupMath
gen(): number
genNumber(a: number, b: number): number
genVec2(a: Vec2, b: Vec2): Vec2
genColor(a: Color, b: Color): Color
genAny<T>(args:
[
]
|
[
T
]
|
[
T, T
]
): T
ShapeType: Point | Circle | Line | Rect | Polygon | Ellipse
groupMath
groupMath
groupMath
groupMath
p1: Vec2
p2: Vec2
area(): number
collides(shape: ShapeType | Vec2): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
groupMath
fromPoints(p1: Vec2, p2: Vec2): Rect
points():
[
Vec2, Vec2, Vec2, Vec2
]
area(): number
collides(shape: ShapeType | Vec2): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
groupMath
transform(tr: Mat4): Ellipse
area(): number
collides(shape: ShapeType | Vec2): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
groupMath
fromMat2(tr: Mat2): Ellipse
transform(tr: Mat4): Ellipse
area(): number
clone(): Ellipse
collides(shape: ShapeType): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
groupMath
pts: Vec2[]
area(): number
clone(): Polygon
collides(shape: ShapeType | Vec2): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
cut(a: Vec2, b: Vec2):
[
Polygon | null, Polygon | null
]
UniformValue: number | Vec2 | Color | Mat4 | number[] | Vec2[] | Color[]
groupMath
UniformKey: Exclude<string, "u_tex">
groupMath
Uniform: Record<UniformKey, UniformValue>
groupMath
raycast(origin: Vec2, direction: Vec2, exclude?: string[]): RaycastResult
Create a raycast.
sincev3001.0
groupMath
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))
returnsThe vector.
sincev2000.0
groupMath
vec2(p: Vec2): Vec2
vec2(xy: number): Vec2
rgb(r: number, g: number, b: number): Color
Create a color from RGB values (0 - 255).
paramr- The red value.
paramg- The green value.
paramb- The blue value.
// update the color of the sky to light blue
sky.color = rgb(0, 128, 255)
returnsThe color.
sincev2000.0
groupMath
rgb(hex: string): Color
Create a color from hex string.
paramhex- The hex string.
sky.color = rgb("#ef6360")
returnsThe color.
sincev2000.0
groupMath
rgb(): Color
Same as rgb(255, 255, 255).
groupMath
hsl2rgb(hue: number, saturation: number, lightness: number): Color
Convert HSL color (all values in 0.0 - 1.0 range) to RGB color.
paramhue- The hue value.
paramsaturation- The saturation value.
paramlightness- The lightness value.
// animate rainbow color
onUpdate("rainbow", (obj) => {
obj.color = hsl2rgb(wave(0, 1, time()), 0.6, 0.6);
});
returnsThe color.
sincev2000.1
groupMath
quad(x: number, y: number, w: number, h: number): Quad
Rectangle area (0.0 - 1.0).
paramx- The x position of the rectangle.
paramy- The y position of the rectangle.
paramw- The width of the rectangle.
paramh- The height of the rectangle.
returnsA Quad object.
sincev3001.0
groupMath
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)
}
})
groupMath
lerp<V>(from: V, to: V, t: number): V
Linear interpolation.
groupMath
tween<V>(from: V, to: V, duration: number, setValue: (value: V)=>void, easeFunc?: (t: number)=>number): TweenController
Tweeeeeeeening!
sincev3000.0
// tween bean to mouse position
tween(bean.pos, mousePos(), 1, (p) => bean.pos = p, easings.easeOutBounce)
groupMath
easings: Record<EaseFuncs, EaseFunc>
A collection of easing functions for tweening.
sincev3000.0
groupMath
easingSteps(steps: number, position: StepPosition): number
Steps easing. Eases in discontinious steps.
sincev3001.0
groupMath
Linear easing with keyframes
sincev3001.0
groupMath
Bezier easing. Both control points need x to be within 0 and 1.
sincev3001.0
groupMath
map(v: number, l1: number, h1: number, l2: number, h2: number): number
Map a value from one range to another range.
If the value overshoots, the source range, the result values will also do.
For clamping check mapc
paramvThe value the function will depend on.
paraml1The minimum value of the source range.
paramh1The minimum result value.
paraml2The maximum value of the source range.
paramh2The maximum result value.
onUpdate(() => {
// Redness will be 0 when the mouse is at the left edge and 255 when the mouse is at the right edge
const redness = map(mousePos().x, 0, width(), 0, 255)
setBackground(rgb(redness, 0, 0))
})
returnsThe result value based on the source value.
sincev2000.0
groupMath
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.
paramvThe value the function will depend on.
paraml1The minimum value of the source range.
paramh1The minimum result value.
paraml2The maximum value of the source range.
paramh2The maximum result value.
onUpdate(() => {
// This variable will be 0 when the mouse is at the left edge and 255 when the mouse is at the right edge
const redness = mapc(mousePos().x, 0, width(), 0, 255)
setBackground(rgb(redness, 0, 0))
})
returnsThe clamped result value based on the source value.
sincev2000.0
groupMath
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)
})
groupMath
deg2rad(deg: number): number
Convert degrees to radians.
groupMath
rad2deg(rad: number): number
Convert radians to degrees.
groupMath
clamp(n: number, min: number, max: number): number
Return a value clamped to an inclusive range of min and max.
groupMath
evaluateQuadratic(pt1: Vec2, pt2: Vec2, pt3: Vec2, t: number): Vec2
Evaluate the quadratic Bezier at the given t
groupMath
Evaluate the first derivative of a quadratic bezier at the given t
sincev3001.0
groupMath
Evaluate the second derivative of a quadratic bezier at the given t
sincev3001.0
groupMath
evaluateBezier(pt1: Vec2, pt2: Vec2, pt3: Vec2, pt4: Vec2, t: number): Vec2
Evaluate the cubic Bezier at the given t
sincev3001.0
groupMath
evaluateBezierFirstDerivative(pt1: Vec2, pt2: Vec2, pt3: Vec2, pt4: Vec2, t: number): Vec2
Evaluate the first derivative of a cubic Bezier at the given t
groupMath
evaluateBezierSecondDerivative(pt1: Vec2, pt2: Vec2, pt3: Vec2, pt4: Vec2, t: number): Vec2
Evaluate the second derivative of a cubic bezier at the given t
sincev3001.0
groupMath
evaluateCatmullRom(pt1: Vec2, pt2: Vec2, pt3: Vec2, pt4: Vec2, t: number): Vec2
Evaluate the Catmull-Rom spline at the given t
sincev3001.0
groupMath
Evaluate the first derivative of a Catmull-Rom spline at the given t
sincev3001.0
groupMath
curveLengthApproximation(curve: (t: number)=>Vec2, entries: number, detail: number): number
Returns a function.
entries is the amount of entries in the LUT.
detail is the sampling granularity of each segment recorded in the LUT.
This new function either returns the length for a given t, or t for a given length, depending on the inverse parameter.
sincev3001.0
groupMath
normalizedCurve(curve: (t: number)=>Vec2): Vec2
Returns a new curve which is normalized. This new curve has constant speed
curve is any curve in t (non-constant between 0 and 1)
returns a curve in s (constant between 0 and 1)
sincev3001.0
groupMath
testLinePoint(l: Line, pt: Vec2): boolean
Check if a line and a point intersect.
paraml- The line.
parampt- The point.
returnstrue if the line and point intersects.
sincev2000.0
groupMath
testLineLine(l1: Line, l2: Line): Vec2 | null
Check if 2 lines intersects, if yes returns the intersection point.
paraml1- The first line.
paraml2- The second line.
returnThe intersection point, or null if the lines are parallel.
sincev2000.0
groupMath
testLineCircle(l: Line, c: Circle): boolean
Check if a line and a circle intersect.
paraml- The line.
paramc- The circle.
returnstrue if the line and circle intersects.
sincev2000.0
groupMath
testRectRect(r1: Rect, r2: Rect): boolean
Check if 2 rectangle overlaps.
paramr1- The first rectangle.
paramr2- The second rectangle.
returnstrue if the rectangles overlap.
sincev2000.0
groupMath
testRectLine(r: Rect, l: Line): boolean
Check if a line and a rectangle overlaps.
paramr- The line.
paraml- The rectangle.
returnstrue if the line and rectangle overlaps.
sincev2000.0
groupMath
testRectPoint(r: Rect, pt: Vec2): boolean
Check if a point is inside a rectangle.
paramr- The rectangle.
parampt- The point.
returnstrue if the point is inside the rectangle.
sincev2000.0
groupMath
Check if a circle and polygon intersect linewise.
paramc- The circle.
paramp- The polygon.
returnstrue if the circle and polygon intersect linewise.
sincev2000.0
groupMath
isConvex(pts: Vec2[]): boolean
groupMath
triangulate(pts: Vec2[]): Vec2[][]
sincev3001.0
groupMath
addPolygon(vertices: Vec2[]): NavPolygon
addRect(pos: Vec2, size: Vec2): NavPolygon
getCost(a: number, b: number): number
getHeuristic(indexA: number, indexB: number): number
getPath(start: number, goal: number): number[]
getWaypointPath(start: Vec2, goal: Vec2, opt: any): Vec2[]
pt: Vec2
area(): number
collides(shape: ShapeType): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
groupMath
p1: Vec2
p2: Vec2
area(): number
collides(shape: ShapeType | Vec2): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
groupMath
fromPoints(p1: Vec2, p2: Vec2): Rect
points():
[
Vec2, Vec2, Vec2, Vec2
]
area(): number
collides(shape: ShapeType | Vec2): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
groupMath
transform(tr: Mat4): Ellipse
area(): number
collides(shape: ShapeType | Vec2): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
groupMath
fromMat2(tr: Mat2): Ellipse
transform(tr: Mat4): Ellipse
area(): number
clone(): Ellipse
collides(shape: ShapeType): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
groupMath
pts: Vec2[]
area(): number
clone(): Polygon
collides(shape: ShapeType | Vec2): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
cut(a: Vec2, b: Vec2):
[
Polygon | null, Polygon | null
]
A 2D vector.
groupMath
x: number
The x coordinate
y: number
The y coordinate
fromAngle(deg: number): Vec2
Create a new Vec2 from an angle in degrees
Create a new Vec2 from an array
An empty vector. (0, 0)
A vector with both components of 1. (1, 1)
A vector signaling to the left. (-1, 0)
A vector signaling to the right. (1, 0)
UP: Vec2
A vector signaling up. (0, -1)
A vector signaling down. (0, 1)
Clone the vector
add(args: Vec2Args): Vec2
Returns the addition with another vector.
sub(args: Vec2Args): Vec2
Returns the subtraction with another vector.
scale(args: Vec2Args): Vec2
Scale by another vector. or a single number
dist(args: Vec2Args): number
Get distance between another vector
sdist(args: Vec2Args): number
Get squared distance between another vector
sdist(v: Vec2, other: Vec2): number
Calculates the squared distance between the vectors
paramvThe vector
paramotherThe other vector
returnsThe distance between the vectors
len(): number
Get length of the vector
sincev3000.0
slen(): number
Get squared length of the vector
sincev3000.0
Get the unit vector (length of 1).
Get the perpendicular vector.
reflect(normal: Vec2): Vec2
Get the reflection of a vector with a normal.
sincev3000.0
project(on: Vec2): Vec2
Get the projection of a vector onto another vector.
sincev3000.0
reject(on: Vec2): Vec2
Get the rejection of a vector onto another vector.
sincev3000.0
dot(p2: Vec2): number
Get the dot product with another vector.
dot(v: Vec2, other: Vec2): number
Get the dot product between 2 vectors.
sincev3000.0
cross(p2: Vec2): number
Get the cross product with another vector.
sincev3000.0
cross(v: Vec2, other: Vec2): number
Get the cross product between 2 vectors.
sincev3000.0
angle(args: Vec2Args): number
Get the angle of the vector in degrees.
Get the angle between this vector and another vector.
sincev3000.0
lerp(dest: Vec2, t: number): Vec2
Linear interpolate to a destination vector (for positions).
slerp(dest: Vec2, t: number): Vec2
Spherical linear interpolate to a destination vector (for rotations).
sincev3000.0
If the vector (x, y) is zero.
sincev3000.0
toFixed(n: number): Vec2
To n precision floating point.
Multiply by a Mat4.
sincev3000.0
eq(other: Vec2): boolean
See if one vector is equal to another.
sincev3000.0
Converts the vector to a Rect with the vector as the origin.
sincev3000.0.
toArray(): Array<number>
Converts the vector to an array.
sincev3001.0
0-255 RGBA color.
groupMath
r: number
Red (0-255.
g: number
Green (0-255).
b: number
Blue (0-255).
fromArray(arr: number[]): Color
fromHex(hex: string | number): Color
Create color from hex string or literal.
Color.fromHex(0xfcef8d)
Color.fromHex("#5ba675")
Color.fromHex("d46eb3")
sincev3000.0
fromHSL(h: number, s: number, l: number): Color
RED: Color
lighten(a: number): Color
Lighten the color (adds RGB by n).
darken(a: number): Color
Darkens the color (subtracts RGB by n).
mult(other: Color): Color
lerp(dest: Color, t: number): Color
Linear interpolate to a destination color.
sincev3000.0
toHSL():
[
number, number, number
]
Convert color into HSL format.
sincev3001.0
eq(other: Color): boolean
Return the hex string of color.
sincev3000.0
toArray(): Array<number>
Return the color converted to an array.
sincev3001.0
groupMath
m: number[]
scale(s: Vec2): Mat4
scale(p: Vec2): this
rotateX(a: number): Mat4
rotateY(a: number): Mat4
rotateZ(a: number): Mat4
rotate(a: number): Mat4
mult(other: Mat4): Mat4
groupMath
x: number
y: number
w: number
h: number
scale(other: Quad): Quad
pos(): Vec2
eq(other: Quad): boolean
groupMath
gen(): number
genNumber(a: number, b: number): number
genVec2(a: Vec2, b: Vec2): Vec2
genColor(a: Color, b: Color): Color
genAny<T>(args:
[
]
|
[
T
]
|
[
T, T
]
): T
LerpValue: number | Vec2 | Color
groupMath
RNGValue: number | Vec2 | Color
groupMath
Collision resolution data.
groupMath
The first game object in the collision.
The second game object in the collision.
The contact normal.
The length of the displacement.
The displacement source game object have to make to avoid the collision.
If the collision is resolved.
Prevent collision resolution if not yet resolved.
sincev3000.0
If the 2 objects have any overlap, or they're just touching edges.
sincev3000.0
Get a new collision with reversed source and target relationship.
isTop(): boolean
If the collision happened (roughly) on the top side.
If the collision happened (roughly) on the bottom side.
If the collision happened (roughly) on the left side.
If the collision happened (roughly) on the right side.
Edge: "left" | "right" | "top" | "bottom"
groupMath
EaseFuncs: "linear" | "easeInSine" | "easeOutSine" | "easeInOutSine" | "easeInQuad" | "easeOutQuad" | "easeInOutQuad" | "easeInCubic" | "easeOutCubic" | "easeInOutCubic" | "easeInQuart" | "easeOutQuart" | "easeInOutQuart" | "easeInQuint" | "easeOutQuint" | "easeInOutQuint" | "easeInExpo" | "easeOutExpo" | "easeInOutExpo" | "easeInCirc" | "easeOutCirc" | "easeInOutCirc" | "easeInBack" | "easeOutBack" | "easeInOutBack" | "easeInElastic" | "easeOutElastic" | "easeInOutElastic" | "easeInBounce" | "easeOutBounce" | "easeInOutBounce"
The list of easing functions available.
groupMath
EaseFunc(t: number): number
A function that takes a time value and returns a new time value.
groupMath
GfxCtx: ReturnType<initGfx>
ctx: GfxCtx
src: null | ImageSource
glTex: WebGLTexture
fromImage(ctx: GfxCtx, img: ImageSource, opt?: TextureOpt): Texture
update(img: ImageSource, x?: number, y?: number): void
Frees up texture memory. Call this once the texture is no longer being used to avoid memory leaks.
ctx: GfxCtx
glVBuf: WebGLBuffer
glIBuf: WebGLBuffer
curTex: Texture | null
push(primitive: GLenum, verts: number[], indices: number[], shader: Shader, tex?: Texture | null, uniform?: Uniform): void
ctx: GfxCtx
glVBuf: WebGLBuffer
glIBuf: WebGLBuffer
draw(primitive?: GLenum): void
RGBValue:
[
number, number, number
]
RGBAValue:
[
number, number, number, number
]
ColorArgs:
[
Color
]
|
[
Color, number
]
| RGBValue | RGBAValue |
[
string
]
|
[
number[]
]
|
[
]
a: number
b: number
c: number
d: number
mul(other: Mat2): Mat2
transform(point: Vec2): Vec2
eigenvectors(e1: number, e2: number): number[][]
det(): number
rotation(radians: number): Mat2
scale(x: number, y: number): Mat2
pt: Vec2
area(): number
collides(shape: ShapeType): boolean
contains(point: Vec2): boolean
raycast(origin: Vec2, direction: Vec2): RaycastResult
StepPosition: "jump-start" | "jump-end" | "jump-none" | "jump-both"
DrawCurveOpt: RenderProps & The amount of line segments to draw.
The width of the line.
DrawBezierOpt: DrawCurveOpt & The first point.
The the first control point.
The the second control point.
The second point.
DrawCircleOpt: Omit & Radius of the circle.
Starting angle.
fill?: boolean
If fill the shape with color (set this to false if you only want an outline).
gradient?:
[
Color, Color
]
Use gradient instead of solid color.
sincev3000.0
Multiplier for circle vertices resolution (default 1)
anchor?: Anchor | Vec2
The anchor point, or the pivot point. Default to "topleft".
How the circle should look like.
tex: Texture
map: Record<string, Quad>
outline: Outline | null
CharTransformFunc(idx: number, ch: string): CharTransform
A function that returns a character transform config. Useful if you're generating dynamic styles.
Formatted text with info on how and where to render each character.
One formated character.
ch: string
tex: Texture
DrawLineOpt: Omit & p1: Vec2
Starting point of the line.
p2: Vec2
Ending point of the line.
The width, or thickness of the line,
How the line should look like.
LineJoin: "none" | "round" | "bevel" | "miter"
LineCap: "butt" | "round" | "square"
DrawLinesOpt: Omit & pts: Vec2[]
The points that should be connected with a line.
The width, or thickness of the lines,
radius?: number | number[]
The radius of each corner.
join?: LineJoin
Line join style (default "none").
cap?: LineCap
Line cap style (default "none").
Maximum miter length, anything longer becomes bevel.
How the lines should look like.
DrawRectOpt: RenderProps & Width of the rectangle.
Height of the rectangle.
gradient?:
[
Color, Color
]
Use gradient instead of solid color.
sincev3000.0
If the gradient should be horizontal.
sincev3000.0
fill?: boolean
If fill the shape with color (set this to false if you only want an outline).
radius?: number | number[]
The radius of each corner.
anchor?: Anchor | Vec2
The anchor point, or the pivot point. Default to "topleft".
How the rectangle should look like.
getCost(node: number, neighbor: number): number
getHeuristic(node: number, goal: number): number
getPath(from: number, to: number): number[]
getWaypointPath(from: Vec2, to: Vec2, opt: any): Vec2[]
A grid is a graph consisting of connected grid cells
getCost(a: number, b: number): number
getHeuristic(a: number, b: number): number
getPath(start: number, goal: number): number[]
getWaypointPath(start: Vec2, goal: Vec2): Vec2[]
a: Vec2
b: Vec2
polygon: WeakRef<NavPolygon>
isLeft(x: number, y: number): number
id(): number
edges(edges: NavEdge[]):
edges(): NavEdge[]
contains(p: Vec2): boolean
addPolygon(vertices: Vec2[]): NavPolygon
addRect(pos: Vec2, size: Vec2): NavPolygon
getCost(a: number, b: number): number
getHeuristic(indexA: number, indexB: number): number
getPath(start: number, goal: number): number[]
getWaypointPath(start: Vec2, goal: Vec2, opt: any): Vec2[]
DrawSpriteOpt: RenderProps & sprite: string | SpriteData | Asset
The sprite name in the asset manager, or the raw sprite data.
If the sprite is loaded with multiple frames, or sliced, use the frame option to specify which frame to draw.
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 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.
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.
If flip the texture horizontally.
If flip the texture vertically.
The sub-area to render from the texture, by default it'll render the whole `quad(0, 0, 1, 1)`
anchor?: Anchor | Vec2
The anchor point, or the pivot point. Default to "topleft".
pos?: Vec2
The position
How the sprite should look like.
DrawTriangleOpt: RenderProps & p1: Vec2
First point of triangle.
p2: Vec2
Second point of triangle.
p3: Vec2
Third point of triangle.
fill?: boolean
If fill the shape with color (set this to false if you only want an outline).
The radius of each corner.
How the triangle should look like.
AppGfxCtx: ReturnType<initAppGfx>
addSingle(img: ImageSource):
[
Texture, Quad, number
]
add(img: ImageSource):
[
Texture, Quad, number
]
buf: AudioBuffer
fromArrayBuffer(buf: ArrayBuffer): Promise<SoundData>
fromURL(url: string): Promise<SoundData>
SpriteAnim: number | from?: number
The starting frame.
to?: number
The end frame.
loop?: boolean
If this anim should be played in loop.
When looping should it move back instead of go to start frame again.
This anim's speed in frames per second.
List of frames for the animation.
If this property exists, **from, to, and pingpong will be ignored**.
Frame-based animation configuration.
SpriteAnims: Record<string, SpriteAnim>
A dict of name <-> animation.
Sprite loading configuration.
If the defined area contains multiple sprites, how many frames are in the area horizontally.
If the defined area contains multiple sprites, how many frames are in the area vertically.
9 slice sprite for proportional scaling.
sincev3000.0
Individual frames.
sincev3000.0
anims?: SpriteAnims
Animation configuration.
If the sprite is a single image.
NineSlice: The width of the 9-slice's left column.
The width of the 9-slice's right column.
top: number
The height of the 9-slice's top row.
The height of the 9-slice's bottom row.
tex: Texture
anims: SpriteAnims
slice9: NineSlice | null
sincev3001.0
from(src: LoadSpriteSrc, opt?: LoadSpriteOpt): Promise<SpriteData>
fromImage(data: ImageSource, opt?: LoadSpriteOpt): SpriteData
fromURL(url: string, opt?: LoadSpriteOpt): Promise<SpriteData>
An asset is a resource that is loaded asynchronously.
loaded<D>(data: D): Asset<D>
data: D | null
error: Error | null
onLoad(action: (data: D)=>void): this
onError(action: (err: Error)=>void): this
onFinish(action: ()=>void): this
then(action: (data: D)=>void): Asset<D>
catch(action: (err: Error)=>void): Asset<D>
finally(action: ()=>void): Asset<D>
assets: Map<string, Asset>
add(name: string | null, loader: Promise): Asset<D>
addLoaded(name: string | null, data: D): Asset<D>
get(handle: string): Asset | undefined
AssetsCtx: ReturnType<initAssets>
AsepriteData: frames: Array< frame: x: number
y: number
w: number
h: number
>
meta: size: w: number
h: number
frameTags: Array< to: number
direction: "forward" | "reverse" | "pingpong"
>
anims: SpriteAnims
SpriteAtlasData: Record<string, SpriteAtlasEntry>
SpriteAtlasEntry: LoadSpriteOpt & x: number
X position of the top left corner.
y: number
Y position of the top left corner.
Sprite area width.
Sprite area height.
A sprite in a sprite atlas.
AudioCtx: ReturnType<initAudio>
push(v: T): number
pushd(v: T): void
add(action: (args: Args)=>unknown): KEventController
addOnce(action: (args: Args | PromiseLike[])=>void): KEventController
next(): Promise<Args>
trigger(args: Args): void
registers: Partial<MappedType>
on<Name>(name: Name, action: (args: EventMap[Name])=>void): KEventController
onOnce<Name>(name: Name, action: (args: EventMap[Name])=>void): KEventController
next<Name>(name: Name): Promise<unknown>
trigger<Name>(name: Name, args: EventMap[Name]): void
remove<Name>(name: Name): void
numListeners<Name>(name: Name): number
_compareFn(a: T, b: T): boolean
insert(item: T): void
Insert an item into the binary heap
Remove the smallest item from the binary heap in case of a min heap
or the greatest item from the binary heap in case of a max heap
Remove all items
moveUp(pos: number): void
moveDown(pos: number): void
swap(index1: number, index2: number): void
Returns the amount of items
Audio play configurations.
If audio should start out paused.
sincev3000.0
loop?: boolean
If audio should be played again from start when its ended.
Volume of audio. 1.0 means full volume, 0.5 means half volume.
Playback speed. 1.0 means normal playback speed, 2.0 means twice as fast.
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.
pan?: number
The stereo pan of the sound.
-1.0 means fully from the left channel, 0.0 means centered, 1.0 means fully right.
Defaults to 0.0.
play(time?: number): void
Start playing audio.
sincev3000.0
seek(time: number): void
Seek time.
sincev3000.0
Stop the sound.
sincev3001.0
If the sound is paused.
sincev2000.1
Playback speed of the sound. 1.0 means normal playback speed, 2.0 means twice as fast.
Detune the sound. Every 100 means a semitone.
// tune down a semitone
music.detune = -100
// tune up an octave
music.detune = 1200
Volume of the sound. 1.0 means full volume, 0.5 means half volume.
pan?: number
The stereo pan of the sound.
-1.0 means fully from the left channel, 0.0 means centered, 1.0 means fully right.
Defaults to 0.0.
loop: boolean
If the audio should start again when it ends.
time(): number
The current playing time (not accurate if speed is changed).
The total duration.
onEnd(action: ()=>void): KEventController
Register an event that runs when audio ends.
sincev3000.0
then(action: ()=>void): KEventController
Options for the particles's component
navigate(origin: Vec2, target: Vec2, navigationOpt: any): Vec2[] | undefined
graph: Graph | undefined
navigateTo(target: Vec2): Vec2[] | undefined
graph: Graph | undefined
waypoints: Vec2[] | undefined
onPatrolFinished(cb: (objects: GameObj[])=>void): KEventController
Attaches an event handler which is called when using "stop" and the end of the path is reached.
paramcbThe event handler called when the patrol finishes.
TimeDirection: "forward" | "reverse" | "ping-pong"
Interpolation: "none" | "linear" | "slerp" | "spline"
Duration of the animation in seconds
Loops, Default is undefined aka infinite
Behavior when reaching the end of the animation. Default is forward.
Easing function. Default is linear time.
Interpolation function. Default is linear interpolation.
Timestamps in percent for the given keys, if omitted, keys are equally spaced.
Easings for the given keys, if omitted, easing is used.
Changes the angle so it follows the motion, requires the rotate component
The animation is added to the base values of pos, angle, scale and opacity instead of replacing them
animate<T>(name: string, keys: T[], opts: AnimateOpt): void
Animates a property on this object.
paramnameName of the property to animate.
paramkeysKeys determining the value at a certain point in time.
paramoptsOptions.
unanimate(name: string): void
Removes the animation from the given property.
paramnameName of the property to remove the animation from.
Removes the animations from all properties
Attaches an event handler which is called when all the animation channels have finished.
paramcbThe event handler called when the animation finishes.
Attaches an event handler which is called when an animation channels has finished.
paramcbThe event handler called when an animation channel finishes.
base: BaseValues
Base values for relative animation
animation: Pauses playing
seek(time: number): void
Move the animation to a specific point in time
Returns the duration of the animation
Serializes the options of this object to plain Javascript types
AnimationChannel: keys: AnimationChannelKeys
& AnimationOptions
ForceMode: "constant" | "inverseLinear" | "inverseSquared"
applyBuoyancy(body: GameObj, submergedArea: Polygon): void
applyDrag(body: GameObj, submergedArea: Polygon): void
App events with their arguments
The name of a scene.
SceneDef(args: any): void
Game: ReturnType<initGame>
Sensitive KAPLAY data
_k: KAPLAYInternal
Internal data that should not be accessed directly.
readonly
groupMisc
addKaboom(pos: Vec2, opt?: BoomOpt): GameObj
Add an explosion effect.
parampos- The position of the explosion.
paramopt- The options for the explosion.
onMousePress(() => {
addKaboom(mousePos());
});
returnsThe explosion object.
sincev2000.0
groupMisc
Tag: string
Defined<T>: ConditionalType
Expand<T>: ConditionalType
MergeObj<T>: Expand<UnionToIntersection>
MergePlugins<T>: MergeObj<ReturnType>
PluginList<T>: Array<T | KAPLAYPlugin>
GamepadDef: buttons: Record<string, KGamepadButton>
sticks: Partial<Record>
A gamepad definition.
KGamepad: The order of the gamepad in the gamepad list.
isPressed(b: KGamepadButton): boolean
If certain button is pressed.
isDown(b: KGamepadButton): boolean
If certain button is held down.
isReleased(b: KGamepadButton): boolean
If certain button is released.
getStick(stick: GamepadStick): Vec2
Get the value of a stick.
A KAPLAY gamepad
Inspect info for a game object.
Sprite animation configuration when playing.
loop?: boolean
If this anim should be played in loop.
When looping should it move back instead of go to start frame again.
This anim's speed in frames per second.
Runs when this animation ends.
outline?: number | Outline
size?: number
The size to load the font in (default 64).
sincev3001.0
ImageSource: Exclude<TexImageSource, VideoFrame>
uv: Vec2
TexFilter: "nearest" | "linear"
Texture scaling filter. "nearest" is mainly for sharp pixelated scaling, "linear" means linear interpolation.
TexWrap: "repeat" | "clampToEdge"
Common render properties.
pos?: Vec2
scale?: Vec2 | number
shader?: string | ShaderData | Asset | null
uniform?: Uniform | null
DrawUVQuadOpt: RenderProps & Width of the UV quad.
Height of the UV quad.
If flip the texture horizontally.
If flip the texture vertically.
tex?: Texture
The texture to sample for this quad.
The texture sampling area.
anchor?: Anchor | Vec2
The anchor point, or the pivot point. Default to "topleft".
DrawEllipseOpt: RenderProps & The horizontal radius.
The vertical radius.
Starting angle.
fill?: boolean
If fill the shape with color (set this to false if you only want an outline).
gradient?:
[
Color, Color
]
Use gradient instead of solid color.
sincev3000.0
Multiplier for circle vertices resolution (default 1)
anchor?: Anchor | Vec2
The anchor point, or the pivot point. Default to "topleft".
How the ellipse should look like.
DrawPolygonOpt: RenderProps & pts: Vec2[]
The points that make up the polygon
fill?: boolean
If fill the shape with color (set this to false if you only want an outline).
Manual triangulation.
The center point of transformation in relation to the position.
radius?: number | number[]
The radius of each corner.
The color of each vertex.
sincev3000.0
uv?: Vec2[]
The uv of each vertex.
sincev3001.0
tex?: Texture
The texture if uv are supplied.
sincev3001.0
Triangulate concave polygons.
sincev3001.0
How the polygon should look like.
The width, or thickness of the line.
The color of the line.
Opacity (overrides fill opacity).
sincev3001.0
join?: LineJoin
Line join.
sincev3000.0
Miter limit. If the length of the miter divided by the line width exceeds this limit, the style is converted to a bevel.
sincev3001.0
cap?: LineCap
Line cap.
sincev3001.0
Mask: "intersect" | "subtract"
loop: boolean
The current index relative to the start of the
associated `frames` array for this animation.
This may be greater than the number of frames
in the sprite.
press(btn: T): void
buttonState: ButtonState<KGamepadButton>
stickState: Map<GamepadStick, Vec2>
fps: number
tick(dt: number): void
App: ReturnType<initApp>
AppState: ReturnType<initAppState>
initAssets(ggl: GfxCtx, spriteAtlasPadding: number): sprites: AssetBucket<SpriteData>
fonts: AssetBucket<FontData>
sounds: AssetBucket<SoundData>
shaders: AssetBucket<Shader>
custom: AssetBucket<any>
music: Record<string, string>
initApp(opt: canvas: HTMLCanvasElement
gamepads?: Record<string, GamepadDef>
): dt(): number
time(): number
run(fixedUpdate: ()=>void, update: (processInput: ()=>void, resetInput: ()=>void)=>void): void
canvas: HTMLCanvasElement
fps(): number
isKeyDown(k?: Key | Key[]): boolean
isKeyPressed(k?: Key | Key[]): boolean
isMouseDown(m?: MouseButton): boolean
isGamepadButtonPressed(btn?: KGamepadButton | KGamepadButton[]): boolean
isGamepadButtonDown(btn?: KGamepadButton | KGamepadButton[]): boolean
isGamepadButtonReleased(btn?: KGamepadButton | KGamepadButton[]): boolean
isButtonPressed(btn?: string | string[]): boolean
isButtonDown(btn?: string | string[]): boolean
isButtonReleased(btn?: string | string[]): boolean
setButton(btn: string, binding: ButtonBinding): void
getButton(btn: string): ButtonBinding
onResize(action: ()=>void): KEventController
onKeyDown: (action: (key: Key)=>void)=>KEventController & (key: Key | Key[], action: (key: Key)=>void)=>KEventController
onKeyPress: (action: (key: Key)=>void)=>KEventController & (key: Key | Key[], action: (key: Key)=>void)=>KEventController
onKeyPressRepeat: (action: (key: Key)=>void)=>KEventController & (key: Key | Key[], action: (key: Key)=>void)=>KEventController
onKeyRelease: (action: (key: Key)=>void)=>KEventController & (key: Key | Key[], action: (key: Key)=>void)=>KEventController
onMouseDown: (action: (m: MouseButton)=>void)=>KEventController & (mouse: MouseButton | MouseButton[], action: (m: MouseButton)=>void)=>KEventController
onMousePress: (action: (m: MouseButton)=>void)=>KEventController & (mouse: MouseButton | MouseButton[], action: (m: MouseButton)=>void)=>KEventController
onMouseRelease: (action: (m: MouseButton)=>void)=>KEventController & (mouse: MouseButton | MouseButton[], action: (m: MouseButton)=>void)=>KEventController
onMouseMove(f: (pos: Vec2, dpos: Vec2)=>void): KEventController
onCharInput(action: (ch: string)=>void): KEventController
onTouchStart(f: (pos: Vec2, t: Touch)=>void): KEventController
onTouchMove(f: (pos: Vec2, t: Touch)=>void): KEventController
onTouchEnd(f: (pos: Vec2, t: Touch)=>void): KEventController
onScroll(action: (delta: Vec2)=>void): KEventController
onHide(action: ()=>void): KEventController
onShow(action: ()=>void): KEventController
onGamepadButtonDown: (action: (btn: KGamepadButton, gamepad: KGamepad)=>void)=>KEventController & (btn: KGamepadButton, action: (btn: KGamepadButton, gamepad: KGamepad)=>void)=>KEventController
onGamepadButtonPress: (action: (btn: KGamepadButton, gamepad: KGamepad)=>void)=>KEventController & (btn: KGamepadButton | KGamepadButton[], action: (btn: KGamepadButton, gamepad: KGamepad)=>void)=>KEventController
onGamepadButtonRelease: (action: (btn: KGamepadButton, gamepad: KGamepad)=>void)=>KEventController & (btn: KGamepadButton | KGamepadButton[], action: (btn: KGamepadButton, gamepad: KGamepad)=>void)=>KEventController
onGamepadStick(stick: GamepadStick, action: (value: Vec2, gp: KGamepad)=>void): KEventController
onGamepadConnect(action: (gamepad: KGamepad)=>void): void
onGamepadDisconnect(action: (gamepad: KGamepad)=>void): void
onButtonPress: (action: (btn: string)=>void)=>KEventController & (btn: string | string, action: (btn: string)=>void)=>KEventController
onButtonDown: (action: (btn: string)=>void)=>KEventController & (btn: string | string, action: (btn: string)=>void)=>KEventController
onButtonRelease: (action: (btn: string)=>void)=>KEventController & (btn: string | string, action: (btn: string)=>void)=>KEventController
events: KEventHandler<AppEventMap>
ButtonBinding: gamepad?: KGamepadButton | KGamepadButton[]
mouse?: MouseButton | MouseButton[]
A button binding.
groupButton Bindings
ButtonsDef: Record<string, ButtonBinding>
A buttons definition for an action (jump, walk-left, run).
groupButton Bindings
A button binding device
groupButton Bindings
groupGFX
ctx: GfxCtx
tex: Texture
draw(action: ()=>void): void
groupGFX
ctx: GfxCtx
send(uniform: Uniform): void
DrawTextOpt: RenderProps & The text to render.
font?: string | FontData | Asset | BitmapFontData | Asset
The name of font to use.
size?: number
The size of text (the height of each character).
align?: TextAlign
Text alignment (default "left")
sincev3000.0
The maximum width. Will wrap word around if exceed.
The gap between each line (only available for bitmap fonts).
sincev2000.2
The gap between each character (only available for bitmap fonts).
sincev2000.2
anchor?: Anchor | Vec2
The anchor 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 (only available for bitmap fonts).
sincev2000.1
styles?: Record<string, CharTransform | CharTransformFunc>
Stylesheet for styled chunks, in the syntax of "this is a [stylename]styled[/stylename] word" (only available for bitmap fonts).
sincev2000.2
If true, any (whitespace) indent on the first line of the paragraph
will be copied to all of the lines for those parts that text-wrap.
How the text should look like.
groupDraw
TextAlign: "center" | "left" | "right"
How the text should be aligned.
groupDraw
drawSprite(opt: DrawSpriteOpt): void
Draw a sprite.
paramopt- The draw sprite options.
drawSprite({
sprite: "bean",
pos: vec2(100, 200),
frame: 3,
});
sincev2000.0
groupDraw
drawText(opt: DrawTextOpt): void
Draw a piece of text.
paramopt- The draw text options.
drawText({
text: "oh hi",
size: 48,
font: "sans-serif",
width: 120,
pos: vec2(100, 200),
color: rgb(0, 0, 255),
});
sincev2000.0
groupDraw
drawRect(opt: DrawRectOpt): void
Draw a rectangle.
paramopt- The draw rect options.
drawRect({
width: 120,
height: 240,
pos: vec2(20, 20),
color: YELLOW,
outline: { color: BLACK, width: 4 },
});
sincev2000.0
groupDraw
drawLine(opt: DrawLineOpt): void
Draw a line.
paramopt- The draw line options.
drawLine({
p1: vec2(0),
p2: mousePos(),
width: 4,
color: rgb(0, 0, 255),
});
sincev3000.0
groupDraw
drawLines(opt: DrawLinesOpt): void
Draw lines.
paramopt- The draw lines options.
drawLines({
pts: [ vec2(0), vec2(0, height()), mousePos() ],
width: 4,
pos: vec2(100, 200),
color: rgb(0, 0, 255),
});
sincev3000.0
groupDraw
drawCurve(curve: (t: number)=>Vec2, opt: DrawCurveOpt): void
Draw a curve.
drawCurve(t => evaluateBezier(a, b, c, d, t)
{
width: 2,
color: rgb(0, 0, 255),
});
sincev3001.0
groupDraw
drawBezier(opt: DrawBezierOpt): void
Draw a cubic Bezier curve.
paramopt- The draw cubic bezier options.
drawBezier({
pt1: vec2(100, 100),
pt2: vec2(200, 100),
pt3: vec2(200, 200),
pt4: vec2(100, 200),
width: 2,
color: GREEN
});
sincev3001.0
groupDraw
drawTriangle(opt: DrawTriangleOpt): void
Draw a triangle.
paramopt- The draw triangle options.
drawTriangle({
p1: vec2(0),
p2: vec2(0, height()),
p3: mousePos(),
pos: vec2(100, 200),
color: rgb(0, 0, 255),
});
sincev3001.0
groupDraw
drawCircle(opt: DrawCircleOpt): void
Draw a circle.
paramopt- The draw circle options.
drawCircle({
pos: vec2(100, 200),
radius: 120,
color: rgb(255, 255, 0),
});
sincev2000.0
groupDraw
drawEllipse(opt: DrawEllipseOpt): void
Draw an ellipse.
paramopt- The draw ellipse options.
drawEllipse({
pos: vec2(100, 200),
radiusX: 120,
radiusY: 120,
color: rgb(255, 255, 0),
});
sincev3000.0
groupDraw
drawPolygon(opt: DrawPolygonOpt): void
Draw a convex polygon from a list of vertices.
paramopt- The draw polygon options.
drawPolygon({
pts: [
vec2(-12),
vec2(0, 16),
vec2(12, 4),
vec2(0, -2),
vec2(-8),
],
pos: vec2(100, 200),
color: rgb(0, 0, 255),
});
sincev3000.0
groupDraw
drawUVQuad(opt: DrawUVQuadOpt): void
Draw a rectangle with UV data.
paramopt- The draw rect with UV options.
sincev2000.0
groupDraw
Draw a piece of formatted text from formatText().
paramtext- The formatted text object.
// text background
const txt = formatText({
text: "oh hi",
});
drawRect({
width: txt.width,
height: txt.height,
});
drawFormattedText(txt);
sincev2000.2
groupDraw
drawMasked(content: ()=>void, mask: ()=>void): void
Whatever drawn in content will only be drawn if it's also drawn in mask (mask will not be rendered).
sincev3000.0
groupDraw
drawSubtracted(content: ()=>void, mask: ()=>void): void
Subtract whatever drawn in content by whatever drawn in mask (mask will not be rendered).
sincev3000.0
groupDraw
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();
sincev2000.0
groupDraw
Pop the topmost transform matrix from the transform stack.
sincev2000.0
groupDraw
pushTranslate(x: number, y: number): void
Translate all subsequent draws.
pushTranslate(100, 100)
// this will be drawn at (120, 120)
drawText({
text: "oh hi",
pos: vec2(20, 20),
})
sincev2000.0
groupDraw
pushTranslate(args: Vec2Args |
[
undefined
]
): void
pushScale(x: number, y: number): void
Scale all subsequent draws.
sincev2000.0
groupDraw
pushScale(s: Vec2 | number): void
pushScale(args: Vec2Args |
[
undefined
]
|
[
undefined, undefined
]
): void
pushRotate(angle?: number): void
Rotate all subsequent draws.
sincev2000.0
groupDraw
Apply a transform matrix, ignore all prior transforms.
sincev3000.0
groupDraw
usePostEffect(name: string, uniform?: Uniform | ()=>Uniform): void
Apply a post process effect from a shader name.
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")
sincev3000.0
groupDraw
formatText(options: DrawTextOpt): FormattedText
Format a piece of text without drawing (for getting dimensions, etc).
// text background
const txt = formatText({
text: "oh hi",
});
drawRect({
width: txt.width,
height: txt.height,
});
drawFormattedText(txt);
returnsThe formatted text object.
sincev2000.2
groupDraw
makeCanvas(w: number, h: number): Canvas
Create a canvas to draw stuff offscreen.
returnsThe canvas object.
sincev3001.0
groupDraw
Cursor: string | "auto" | "default" | "none" | "context-menu" | "help" | "pointer" | "progress" | "wait" | "cell" | "crosshair" | "text" | "vertical-text" | "alias" | "copy" | "move" | "no-drop" | "not-allowed" | "grab" | "grabbing" | "all-scroll" | "col-resize" | "row-resize" | "n-resize" | "e-resize" | "s-resize" | "w-resize" | "ne-resize" | "nw-resize" | "se-resize" | "sw-resize" | "ew-resize" | "ns-resize" | "nesw-resize" | "nwse-resize" | "zoom-int" | "zoom-out"
groupDraw
Anchor: "topleft" | "top" | "topright" | "left" | "center" | "right" | "botleft" | "bot" | "botright"
groupDraw
Shape: Rect | Line | Point | Circle | Ellipse | Polygon
groupDraw
Describes how to transform each character.
groupOptions
pos?: Vec2
Offset to apply to the position of the text character.
Shifts the character's position by the specified 2D vector.
scale?: Vec2 | number
Scale transformation to apply to the text character's current scale.
When a number, it is scaled uniformly.
Given a 2D vector, it is scaled independently along the X and Y axis.
Increases the amount of degrees to rotate the text character.
Color transformation applied to the text character.
Multiplies the current color with this color.
Opacity multiplication applied to the text character.
For example, an opacity of 0.4 with 2 set in the transformation, the resulting opacity will be 0.8 (0.4 × 2).
If true, the styles applied by this specific entry transform
will override, rather than compose with, the default styles given in and by other
components' styles.
groupOptions
Animation speed.
Scale.
comps?: CompList<any>
Additional components.
sincev3000.0
groupOptions
Width of each block.
Height of each block.
pos?: Vec2
Position of the first block.
Definition of each tile.
wildcardTile?(sym: string, pos: Vec2): CompList | null | undefined
Called when encountered a symbol not defined in "tiles".
GetOpt: Recursively get all children and their descendants.
Live update the returned list every time object is added / removed.
only?: "tags" | "comps"
Get only by tags or components.
groupOptions
QueryOpt: include?: string | string[]
All objects which include all or any of these tags, depending on includeOp.
Selects the operator to use. Defaults to and.
exclude?: string | string[]
All objects which do not have all or any of these tags, depending on excludeOp.
Selects the operator to use. Defaults to and.
All objects which are near or far to the position of this, depending on distanceOp.
Selects the operator to use. Defaults to near.
All objects visible from this standpoint.
hierarchy?: "children" | "siblings" | "ancestors" | "descendants"
All objects in the given group. Defaults to children.
groupOptions
groupOptions
layer(name: string): LayerComp
Determines the layer for objects. Object will be drawn on top if the layer index is higher.
paramname- The layer name to set.
// Define layers
layers(["background", "game", "foreground"], "game")
const bean = add([
sprite("bean"),
pos(100, 100),
layer("background"),
])
// Mark is in a higher layer, so he will be drawn on top of bean
const mark = add([
sprite("mark"),
pos(100, 100),
layer("game"),
])
bean.layer("foreground") // Bean is now in the foreground layer and will be drawn on top of mark
returnsThe layer comp.
sincev3001.0
groupLayer
onCollideEnd(t1: Tag, t2: Tag, action: (a: GameObj, b: GameObj, col?: Collision)=>void): KEventController
Register an event that runs once frame when 2 game objs with certain tags stops colliding (required to have area() component).
paramt1- The tag of the first game obj.
paramt2- The tag of the second game obj.
paramaction- The function to run when the event is triggered.
onCollideEnd("bean", "earth", () => {
debug.log("destroying world in 3... 2... 1...")
});
returnsThe event controller.
sincev3000.0
groupPhysics
Set gravity.
paramg- The gravity to set.
sincev2000.0
groupPhysics
Get gravity.
sincev3001.0
groupPhysics
Set gravity direction.
sincev3001.0
groupPhysics
Get gravity direction.
returnsThe gravity direction.
sincev3001.0
groupPhysics
Set camera position.
parampos- The position to set the camera to.
// move camera to (100, 100)
setCamPos(100, 100);
setCamPos(vec2(100, 100));
setCamPos(100); // x and y are the same
sincev3001.10
groupCamera
setCamPos(x: number, y: number): void
Get camera position.
returnsThe current camera position.
sincev3001.10
groupCamera
Set camera scale.
paramscale- The scale to set the camera to.
// set camera scale to (2, 2)
setCamScale(2, 2);
setCamScale(vec2(2, 2));
setCamScale(2); // x and y are the same
sincev3001.10
groupCamera
setCamScale(x: number, y: number): void
Get camera scale.
returnsThe current camera scale.
sincev3001.10
groupCamera
setCamRot(angle: number): void
Set camera rotation.
paramangle- The angle to rotate the camera.
// rotate camera 90 degrees
setCamRot(90);
sincev3001.10
groupCamera
Get camera rotation.
returnsThe current camera rotation.
sincev3001.10
groupCamera
Get camera transform.
returnsThe current camera transform.
sincev3001.10
groupCamera
shake(intensity?: number): void
Camera shake.
paramintensity- The intensity of the shake. Default to 12.
// shake intensively when bean collides with a "bomb"
bean.onCollide("bomb", () => {
shake(120)
})
sincev3000.0
groupCamera
flash(flashColor: Color, fadeOutTime: number): TimerController
Camera flash.
paramflashColor- The color of the flash.
paramfadeOutTime- The time it takes for the flash to fade out.
onClick(() => {
// flashed
flash(WHITE, 0.5);
});
returnsA timer controller.
sincev3001.0
groupCamera
camPos(pos: Vec2): Vec2
parampos- The position to set the camera to.
deprecatedUse
// camera follows player
player.onUpdate(() => {
camPos(player.pos)
})
returnsThe current camera position.
sincev2000.0
groupCamera
camPos(x: number, y: number): Vec2
deprecated
camPos(xy: number): Vec2
deprecated
deprecated
camScale(scale: Vec2): Vec2
paramscale- The scale to set the camera to.
deprecatedUse
returnsThe current camera scale.
sincev2000.0
groupCamera
camScale(x: number, y: number): Vec2
deprecated
camScale(xy: number): Vec2
deprecated
deprecated
camRot(angle?: number): number
paramangle- The angle to rotate the camera.
deprecatedUse
returnsThe current camera rotation.
sincev2000.0
groupCamera
camFlash(flashColor: Color, fadeOutTime: number): TimerController
paramflashColor- The color of the flash.
paramfadeOutTime- The time it takes for the flash to fade out.
deprecateduse
returnsA timer controller.
sincev3001.0
groupCamera
deprecateduse
groupCamera
Transform a point from world position (relative to the root) to screen position (relative to the screen).
paramp- The point to transform.
sincev3001.0
groupCamera
toWorld(p: Vec2): Vec2
Transform a point from screen position (relative to the screen) to world position (relative to the root).
paramp- The point to transform.
sincev3001.0
groupCamera
play(src: string | SoundData | Asset | MusicData | Asset, options?: AudioPlayOpt): AudioPlay
Play a piece of audio.
// 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
returnsA control handle.
sincev2000.0
groupAudio
burp(options?: AudioPlayOpt): AudioPlay
Yep. Plays a burp sound.
returnsA control handle.
sincev2000.0
groupAudio
Set the global volume.
paramv- The volume to set.
setVolume(0.5)
sincev3001.10
groupAudio
Get the global volume.
returnsThe current volume.
sincev3001.10
groupAudio
volume(v?: number): number
deprecatedUse
// makes everything quieter
volume(0.5)
returnsThe new volume or the current volume.
sincev2000.0
groupAudio
Get the underlying browser AudioContext.
sincev2000.0
groupAudio
rand<T>(a?: T, b?: T): T
Get a random value between the given bound.
parama- The lower bound. If not upper bound, this is the upper bound and the lower bound is 0.
paramb- The upper bound.
// a random number between 0 - 8
rand(8)
// a random point on screen
rand(vec2(width(), height()))
// a random color
rand(rgb(255, 255, 255))
// a random number between 50 - 100
rand(50, 100);
// a random point on screen with x between 20 - 100 and y between 20 - 100
rand(vec2(20), vec2(100));
// spawn something on the right side of the screen but with random y value within screen height
add([
pos(width(), rand(0, height())),
]);
sincev2000.0
groupRandom
randi(a?: number, b?: number): number
rand() but floored to integer. If not arguments, returns 0 or 1.
parama- The lower bound. If not upper bound, this is the upper bound.
paramb- The upper bound.
randi(); // returns either 0 or 1
randi(10); // returns a random integer between 0 and 9
randi(10, 20); // returns a random integer between 10 and 19
returnsA random integer between 0 and 1.
sincev2000.0
groupRandom
randSeed(seed?: number): number
Get / set the random number generator seed.
paramseed- The seed to set.
randSeed(Date.now())
returnsThe new seed.
sincev2000.0
groupRandom
choose<T>(lst: T[]): T
Choose a random item from a list.
paramlst- The list to choose from.
// decide the best fruit randomly
const bestFruit = choose(["apple", "banana", "pear", "watermelon"]);
returnsA random item from the list.
sincev3001.0
groupRandom
chooseMultiple<T>(lst: T[], count: number): T[]
Choose multiple random items from a list.
paramlst- The list to choose from.
paramcount- The number of items to choose.
returnsAn array of random items from the list.
sincev3001.0
groupRandom
shuffle<T>(lst: T[]): T[]
Shuffle an array.
paramlst- The list to shuffle.
returnsA shuffled array.
sincev3001.0
groupRandom
setLayers(layers: string[], defaultLayer: string): void
Define the layer names. Should be called before any objects are made.
paramlayers- The layer names.
paramdefaultLayer- The default layer name.
layers(["bg", "obj", "ui"], "obj")
// no layer specified, will be added to "obj"
add([
sprite("bean"),
]);
// add to "bg" layer
add([
sprite("bg"),
layer("bg"),
]);
sincev3001.10
groupLayers
getLayers(): string[] | null
Get the layer names.
returnsThe layer names or null if not set.
sincev3001.10
groupLayers
experimentalThis feature is in experimental phase, it will be fully released in v4000.0
Get the default layer name.
returnsThe default layer name or null if not set.
sincev3001.0.5
groupLayers
experimentalThis feature is in experimental phase, it will be fully released in v4000.0
addLevel(map: string[], opt: LevelOpt): GameObj<PosComp | LevelComp>
Construct a level based on symbols.
parammap- The map data.
paramopt- The level options.
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(),
body({ isStatic: true }),
],
"$": () => [
sprite("coin"),
area(),
pos(0, -9),
],
"^": () => [
sprite("spike"),
area(),
"danger",
],
}
})
returnsA game obj with the level.
sincev2000.0
groupLevel
getData<T>(key: string, def?: T): T | null
Get data from local storage, if not present can set to a default value.
paramkey- The key to get data from.
paramdef- The default value to set if not found.
returnsThe data or null if not found.
sincev2000.0
groupData
setData(key: string, data: any): void
Set data from local storage.
paramkey- The key to set data to.
paramdata- The data to set.
sincev2000.0
groupData
Take a screenshot and get the data url of the image.
returnsThe dataURL of the image.
sincev2000.0
groupData
download(filename: string, dataurl: string): void
Trigger a file download from a url.
sincev3000.0
groupData
downloadText(filename: string, text: string): void
Trigger a text file download.
sincev3000.0
groupData
downloadJSON(filename: string, data: any): void
Trigger a json download from a .
sincev3000.0
groupData
downloadBlob(filename: string, blob: Blob): void
Trigger a file download from a blob.
sincev3000.0
groupData
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.
returnsA control handle.
sincev2000.1
groupData
Screen recording control handle.
groupData
Pause the recording.
Resume the recording.
stop(): Promise<Blob>
Stop the recording and get the video data as mp4 Blob.
sincev3000.0
download(filename?: string): void
Stop the recording and downloads the file as mp4. Trying to resume later will lead to error.
The Debug interface for debugging stuff.
// pause the whole game
debug.paused = true
// enter inspect mode
debug.inspect = true
returnsThe debug interface.
sincev2000.0
groupDebug
groupDebug
Pause the whole game.
Draw bounding boxes of all objects with `area()` component, hover to inspect their states.
Global time scale.
Show the debug log or not.
fps(): number
Current frames per second.
Total number of frames elapsed.
sincev3000.0
Number of draw calls made last frame.
Step to the next frame. Useful with pausing.
Clear the debug log.
log(msg: any): void
Log some text to on screen debug log.
error(msg: any): void
Log an error message to on screen debug log.
The recording handle if currently in recording mode.
sincev2000.1
Get total number of objects.
sincev3001.0
plug<T>(plugin: KAPLAYPlugin): KAPLAYCtx & T
Import a plugin.
paramplugin- The plugin to import.
returnsThe updated context with the plugin.
sincev2000.0
groupPlugins
KAPLAYPlugin<T>(k: KAPLAYCtx): T | (args: any)=>(k: KAPLAYCtx)=>T
A plugin for KAPLAY.
// a plugin that adds a new function to KAPLAY
const myPlugin = (k) => ({
myFunc: () => {
k.debug.log("hello from my plugin")
}
})
// use the plugin
kaplay({
plugins: [ myPlugin ]
})
// now you can use the new function
myFunc()
groupPlugins
All chars in ASCII.
sincev2000.0
groupConstants
Left directional vector vec2(-1, 0).
sincev2000.0
groupConstants
Right directional vector vec2(1, 0).
sincev2000.0
groupConstants
UP: Vec2
Up directional vector vec2(0, -1).
sincev2000.0
groupConstants
Down directional vector vec2(0, 1).
sincev2000.0
groupConstants
RED: Color
Red color.
sincev2000.0
groupConstants
Green color.
sincev2000.0
groupConstants
Blue color.
sincev2000.0
groupConstants
Yellow color.
sincev2000.0
groupConstants
Cyan color.
sincev2000.0
groupConstants
Cyan color.
sincev2000.0
groupConstants
White color.
sincev2000.0
groupConstants
Black color.
sincev2000.0
groupConstants
Home 
Discord 
GitHub 
Changelog 
KAPLAYGROUND 
Donate to KAPLAY 
Guides 
API Docs 
Blog