572 lines
11 KiB
Markdown
572 lines
11 KiB
Markdown
# Gamelib
|
|
|
|
<table-of-contents></table-of-contents>
|
|
|
|
## 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<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:
|
|
|
|
```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
|