# Gamelib

## Models

### `Color`

A type of string.

Represents HTML colors. This includes [named colors](https://developer.mozilla.org/en-US/docs/Web/CSS/named-color) 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:

```ts
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](https://developer.mozilla.org/en-US/docs/Web/API/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 */

### `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:

```ts

let playerX = 0;

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

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

### `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:

```ts

let playerX = 0;

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

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

## Functions

### `lib.println(msg: string) -> void`

Print a message the debug console.

Example:

```ts
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:

```ts
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:

```ts
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:

```ts
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:

```ts
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:

```ts
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:

```ts

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

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