karlkoder-playground/docs/src/gamelib/index.md

Gamelib

Models

MouseButton

A dictionary of mouse buttons, accessible with lib.MouseButton.

Members:

• lib.MouseButton.Left
• lib.MouseButton.Right
• lib.MouseButton.Middle

Example:

function mouseLeftClicked() {
    /* do something */
}

lib.onClick(mouseLeftClicked, lib.MouseButton.Left);

Color

A type of string.

Represents HTML colors. This includes named colors such as blue, red, blanchedalmond, lavenderblush, and rgb/hex when used with proper format. You can use lib.rgb(r,g,b) to generate a properly formatted rgb color code.

Example:

lib.drawRect(0, 0, 100, 100, "blue");
lib.drawRect(100, 0, 100, 100, lib.rgb(192, 127, 172));

Key

A type of string.

Represents JavaScript's KeyboardEvent.key property.

Example:

"Enter": Enter was pressed.
"b": Lowercase 'b' was pressed.
"B": Uppercase 'B' was pressed (i.e. Shift + B)
" ": Spacebar was pressed.

/* todo: include a little html tool that listens to key events when focused and outputs what key was pressed */

MouseMoveEventFunc

A function with 4 parameters (mouseX, mouseY, mouseDeltaX, mouseDeltaY) that is called whenever the mouse moves.

Works both as a named and anonymous function.

Example:

See lib.onMouseMove

MouseButtonEventFunc

A function with no parameters that is called whenever the appropriate MouseButton is pressed / released.

Works both as a named and anonymous function.

Example:

let playerX = 0;

// anonymous function
lib.onClick(function () {
    playerX -= 20;
}, lib.MouseButton.Right);

// named function
function leftMouseWasPressed() {
    playerX += 20;
}
/* note the lack of () after leftMouseWasPressed -
   we are not calling the function, we are
   referring to it as a variable */
lib.onClick(leftMouseWasPressed, lib.MouseButton.Left);

KeyEventFunc

A function with no parameters that is called whenever the appropriate Key is pressed / released.

Works both as a named and anonymous function.

Example:

let playerX = 0;

// anonymous function
lib.onPress("a", function () {
    playerX -= 20;
});

// named function
function dWasPressed() {
    playerX += 20;
}
/* note the lack of () after dWasPressed -
   we are not calling the function, we are
   referring to it as a variable */
lib.onPress("a", dWasPressed);

LoopFunc

A function with a single parameters (deltaT) that is called whenever a game tick should run - usually about 1/60 times a second.

The deltaT parameter describes the time difference between the last tick and now, in seconds.

The name used for deltaT can be anything, it functions as any other function parameter. I.e. loopFunction(timeSinceLastCall), loopFunction(fooBar), etc.

For example:

loopFunction is called at 12:00.24 - deltaT is 0
loopFunction is called at 12:00.75 - deltaT is .51
loopFunction is called at 12:01.52 - deltaT is .77

Works both as a named and anonymous function.

Example:

let playerX = 0;

// anonymous function
lib.startGameLoop(function (deltaT) {
    playerX += 20 * deltaT;
});

// named function
function loopFunction(deltaTime) {
    playerX += 20 * deltaTime;
}
/* note the lack of () after loopFunction -
   we are not calling the function, we are
   referring to it as a variable */
lib.startGameFunction(loopFunction);

Lib

println

lib.println(msg: string) -> void

Print a message the debug console.

Example:

lib.println("Hello world!");
lib.println("It is a thursday.");

[console]
Hello world!
It is a thursday.

startGameLoop

lib.startGameLoop(loopFunction: LoopFunc) -> void

Registers a gameloop function, that is called on every tick.

See also: Models.LoopFunc

width

lib.width -> number;

Get canvas width in pixels.

height

lib.width -> number;

Get canvas height in pixels.

isPressed

lib.isPressed(key: Key) -> bool

Returns whether or not key is currently pressed.

See also: Models.Key

Example:

let playerX = 0;
lib.startGameLoop(function (deltaT) {
    if (lib.isPressed("a")) {
        playerX -= 20 * deltaT;
    }
    if (lib.isPressed("d")) {
        playerX -= 20 * deltaT;
    }
});

onPress

lib.onPress(key: Key, handlerFunction: KeyEventFunc) -> void

Calls handlerFunction whenever key is pressed.

See also: Models.Key, Models.KeyEventFunc

Example:

let isJumping = false;

lib.onPress(" ", function () {
    isJumping = true;
});

lib.onRelease(" ", function () {
    isJumping = false;
});

onRelease

lib.onRelease(key: Key, handlerFunction: KeyEventFunc) -> void

The opposite of lib.onPress

rgb

lib.rgb(red: number, green: number, blue: number) -> Color

Generates a correctly formatted Color value based on red, green and blue

See also: Models.Color

Example:

lib.drawRect(100, 0, 100, 100, lib.rgb(192, 127, 172));

clear

lib.clear(color: Color) -> void

Paints the entire screen color.

See also: Models.Color

Example:

function drawClouds() {
    /* some lib.drawRect(..) or lib.drawSprite(..) */
}

lib.startGameLoop(function () {
    lib.clear("blue");
    drawClouds();
});

loadSprite

lib.loadSprite(name: string, width: number, height: number) -> Promise<Sprite>

Loads a sprite from the asset editor with a specified width and height.

The name parameter is the file name as it is shown in the asset editor.

Setting the width and height to anything other than those of the original image will cause the sprite to be resized take up that size.

The loading is asynchronous, so you will have to add await for it to work.

Example:

const mySprite = await lib.loadSprite("sprite.png", 50, 50);

After loading, the sprite is ready to be drawn.

See also: lib.drawSprite()

drawSprite

lib.drawSprite(x: number, y: number, sprite: Sprite) -> void

Draws a loaded sprite at the specified coordinates.

Example:

const cloudSprite = await loadSprite("cloud.png", 20, 10);

lib.startGameLoop(function () {
    lib.clear("blue");
    lib.drawSprite(20, 30, cloudSprite);
});

Before drawing, the sprite must be loaded into a variable.

See also: lib.loadSprite()

drawSpriteRotated

lib.drawSpriteRotated(
    x: number,
    y: number,
    width: number,
    height: number,
    name: string,
    angle: number
) -> void

Same as drawSprite, but the sprite is rotated according to the angle parameter, specified in radians (meaning a full rotation is 2 * Math.PI.) The sprite is rotated around the center.

Note: Angles have a granularity/precision of 360 steps per rotation. This is because sprite images are cached internally on angle in addition to name, width and height.

See also: drawSprite

drawRect

lib.drawRect(x: number, y: number, width: number, height: number, color: Color) -> void

Fills a rect with Color.

See also: Models.Color

Example:

function drawCloud(x, y) {
    lib.drawRect(x, y, 20, 10, "white");
}

lib.startGameLoop(function () {
    lib.clear("blue");
    drawCloud(20, 30);
    drawCloud(50, 35);
});

drawLine

lib.drawLine(
    x0: number, y0: number,
    x1: number, y1: number,
    thickness: number,
    color: Color
) -> void

Draws a line from (x0, y0) to (x1, y1), with a thickness of thickness and a Color.

See also: Models.Color

drawPath

lib.drawPath(path: [number, number][], color: Color) -> void

Fills an arbitrary polygon with Color.

Example:

lib.drawPath([
    [0, 0],
    [10, 0],
    [10, 10],
    [0, 10],
], "blue");

Note: The path array must contain at minimum 1 element.

See also: Models.Color

drawPathLine

lib.drawPathLine(path: [number, number][], thickness: number, color: Color) -> void

Draws the outline of an arbitrary polygon.

See also: drawPath, drawLine

onMouseMove

lib.onMouseMove(handlerFunction: MouseMoveEventFunc) -> void

Calls handlerFunction whenever mouse is moved.

See also: Models.MouseMoveEventFunc

Example:

const player = {
    x: lib.width / 2,
    y: lib.height / 2,
    direction: { x: 0, y: 0 },
};

function mouseMoved(mouseX, mouseY) {
    const diffX = mouseX - player.x;
    const diffY = mouseY - player.y;
    const length = Math.sqrt(diffX ** 2 + diffY ** 2);
    player.direction = {
        x: (diffX / length),
        y: -(diffY / length),
    };
}

lib.onMouseMove(mouseMoved);

const player = {
    x: lib.width / 2,
    y: lib.height / 2,
};

function mouseMoved(_mouseX, _mouseY, deltaX, deltaY) {
    player.x += deltaX;
    player.y += deltaY;
}

lib.onMouseMove(mouseMoved);

isClicking

lib.isClicking(button: MouseButton) -> bool

Returns whether or not key is currently pressed.

See also: Models.MouseButton

Example:

let playerX = 0;
lib.startGameLoop(function (deltaT) {
    if (lib.isPressed("a")) {
        playerX -= 20 * deltaT;
    }
    if (lib.isPressed("d")) {
        playerX -= 20 * deltaT;
    }
});

onClick

lib.onClick(
    handlerFunction: MouseButtonEventFunc,
    button: MouseButton = lib.MouseButton.Left
) -> void

Calls handlerFunction whenever button is pressed.

button defaults to lib.MouseButton.Left if not provided.

See also: Models.MouseButton, Models.MouseButtonEventFunc

Example:

let isJumping = false;

/* here we take advantage of MouseButton.Left
   being the default argument, so we don't have
   to specify it. */
lib.onClickRelease(function () {
    isJumping = false;
});

/* here we decide to be explicit */
lib.onClick(function () {
    isJumping = true;
}, lib.MouseButton.Left);

onClickRelease

lib.onClickRelease(
    handlerFunction: MouseButtonEventFunc,
    button: MouseButton = lib.MouseButton.Left
) -> void`

The opposite of lib.onClick

MouseButton

lib.MouseButton.Left, lib.MouseButton.Right, lib.MouseButton.Middle

A way to access Model.MouseButton values