# Gamelib
## Models
### `MouseButton`
A dictionary of mouse buttons, accessible with `lib.MouseButton`.
Members:
- `lib.MouseButton.Left`
- `lib.MouseButton.Right`
- `lib.MouseButton.Middle`
Example:
```ts
function mouseLeftClicked() {
/* do something */
}
lib.onClick(mouseLeftClicked, lib.MouseButton.Left);
```
### `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)`](#Lib-rgb) 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`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) property.
Example:
```javascript
"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`](#Lib-onMouseMove)
### `MouseButtonEventFunc`
A function with no parameters that is called whenever the appropriate
[`MouseButton`](#Models-MouseButton) is pressed / released.
Works both as a named and anonymous function.
Example:
```ts
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`](#Models-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;
}
/* 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:
```js
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;
}
/* 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`
```ts
lib.println(msg: string) -> void
```
Print a message the debug console.
Example:
```ts
lib.println("Hello world!");
lib.println("It is a thursday.");
```
```ini
[console]
Hello world!
It is a thursday.
```
### `startGameLoop`
```ts
lib.startGameLoop(loopFunction: LoopFunc) -> void
```
Registers a gameloop function, that is called on every tick.
See also: [`Models.LoopFunc`](#Models-LoopFunc)
### `width`
```ts
lib.width -> number;
```
Get canvas width in pixels.
### `height`
```ts
lib.width -> number;
```
Get canvas height in pixels.
### `isPressed`
```ts
lib.isPressed(key: Key) -> bool
```
Returns whether or not `key` is currently pressed.
See also: [`Models.Key`](#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;
}
});
```
### `onPress`
```ts
lib.onPress(key: Key, handlerFunction: KeyEventFunc) -> void
```
Calls `handlerFunction` whenever `key` is pressed.
See also: [`Models.Key`](#Models-Key), [`Models.KeyEventFunc`](#Models-KeyEventFunc)
Example:
```ts
let isJumping = false;
lib.onPress(" ", function () {
isJumping = true;
});
lib.onRelease(" ", function () {
isJumping = false;
});
```
### `onRelease`
```ts
lib.onRelease(key: Key, handlerFunction: KeyEventFunc) -> void
```
The opposite of [`lib.onPress`](#Lib-onPress)
### `rgb`
```ts
lib.rgb(red: number, green: number, blue: number) -> Color
```
Generates a correctly formatted [`Color`](#Models-Color) value based on `red`, `green` and `blue`
See also: [`Models.Color`](#Models-Color)
Example:
```ts
lib.drawRect(100, 0, 100, 100, lib.rgb(192, 127, 172));
```
### `clear`
```ts
lib.clear(color: Color) -> void
```
Paints the entire screen `color`.
See also: [`Models.Color`](#Models-Color)
Example:
```ts
function drawClouds() {
/* some lib.drawRect(..) or lib.drawSprite(..) */
}
lib.startGameLoop(function () {
lib.clear("blue");
drawClouds();
});
```
### `loadSprite`
```ts
lib.loadSprite(name: string, width: number, height: number) -> Promise
```
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:
```ts
const mySprite = await lib.loadSprite("sprite.png", 50, 50);
```
After loading, the sprite is ready to be drawn.
See also: [`lib.drawSprite()`](#Lib-drawSprite)
### `drawSprite`
```ts
lib.drawSprite(x: number, y: number, sprite: Sprite) -> void
```
Draws a loaded sprite at the specified coordinates.
Example:
```ts
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()`](#Lib-loadSprite)
### `drawSpriteRotated`
```ts
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`](#Lib-drawSprite)
### `drawRect`
```ts
lib.drawRect(x: number, y: number, width: number, height: number, color: Color) -> void
```
Fills a rect with [`Color`](#Models-Color).
See also: [`Models.Color`](#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);
});
```
### `drawLine`
```ts
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](#Models-Color).
See also: [`Models.Color`](#Models-Color)
### `drawPath`
```ts
lib.drawPath(path: [number, number][], color: Color) -> void
```
Fills an arbitrary polygon with [`Color`](#Models-Color).
Example:
```ts
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`](#Models-Color)
### `drawPathLine`
```ts
lib.drawPathLine(path: [number, number][], thickness: number, color: Color) -> void
```
Draws the outline of an arbitrary polygon.
See also: [`drawPath`](#Lib-drawPath), [`drawLine`](#Lib-drawLine)
### `onMouseMove`
```ts
lib.onMouseMove(handlerFunction: MouseMoveEventFunc) -> void
```
Calls `handlerFunction` whenever mouse is moved.
See also: [`Models.MouseMoveEventFunc`](#Models-MouseMoveEventFunc)
Example:
```ts
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);
```
```ts
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`
```ts
lib.isClicking(button: MouseButton) -> bool
```
Returns whether or not `key` is currently pressed.
See also: [`Models.MouseButton`](#Models-MouseButton)
Example:
```ts
let playerX = 0;
lib.startGameLoop(function (deltaT) {
if (lib.isPressed("a")) {
playerX -= 20 * deltaT;
}
if (lib.isPressed("d")) {
playerX -= 20 * deltaT;
}
});
```
### `onClick`
```ts
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-MouseButton),
[`Models.MouseButtonEventFunc`](#Models-MouseButtonEventFunc)
Example:
```ts
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`
```ts
lib.onClickRelease(
handlerFunction: MouseButtonEventFunc,
button: MouseButton = lib.MouseButton.Left
) -> void`
```
The opposite of [`lib.onClick`](#Lib-onClick)
### `MouseButton`
`lib.MouseButton.Left`, `lib.MouseButton.Right`, `lib.MouseButton.Middle`
A way to access [`Model.MouseButton`](#Model-MouseButton) values