# 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