gamelib docs

docs/gamelib.md

@@ -0,0 +1,228 @@
+# 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);
+});
+```

docs/index.html

@@ -6,6 +6,6 @@
         <title>Karlkoder Docs</title>
     </head>
     <body>
-        <h1>Chatgpt</h1>
+        <h1>Docs</h1>
     </body>
 </html>