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

Gamelib

Models

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 (link) 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 */

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 using it as a variable
lib.startGameFunction(loopFunction);

Functions

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.

lib.startGameLoop(loopFunction: LoopFunc) -> void

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

See also: Models.LoopFunc

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

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

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

The opposite of lib.onPress

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

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

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

Draws a sprite imported in the sprite editor.

/* todo: link to sprite editor docs */

Example:

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

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