sfja/karlkoder-playground
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improve docs rendering

Browse Source
This commit is contained in:
Theis Pieter Hollebeek 2025-10-13 17:10:00 +02:00
parent 7c544ddc17
commit 06bf686f8c
5 changed files with 66 additions and 289 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/src/gamelib/index.md
View File

@ -1,7 +1,5 @@
# Gamelib # Gamelib
## Contents
<table-of-contents></table-of-contents> <table-of-contents></table-of-contents>
## Models ## Models
@ -78,7 +76,7 @@ The name used for `deltaT` can be anything, it functions as any other function p
For example: For example:
``` ```js
loopFunction is called at 12:00.24 - deltaT is 0 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:00.75 - deltaT is .51
loopFunction is called at 12:01.52 - deltaT is .77 loopFunction is called at 12:01.52 - deltaT is .77

256
docs/src/gamelib/other.md
View File

@ -1,259 +1,7 @@
# Gamelib # Gamelib
## Contents
<table-of-contents></table-of-contents> <table-of-contents></table-of-contents>
## Models ## What is this?
### `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:
```
"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`](#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:
```
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 using it as a variable
lib.startGameFunction(loopFunction);
```
## Lib
### `println`
`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`
`lib.startGameLoop(loopFunction: LoopFunc) -> void`
Registers a gameloop function, that is called on every tick.
See also: [`Models.LoopFunc`](#Models-LoopFunc)
### `isPressed`
`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`
`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`
`lib.onRelease(key: Key, handlerFunction: KeyEventFunc) -> void`
The opposite of [`lib.onPress`](#Lib-onPress)
### `rgb`
`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`
`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();
});
```
### `drawSprite`
`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");
});
```
### `drawRect`
`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);
});
```
Example of having two .md files in the same directory

2
docs/src/index.md
View File

@ -1,5 +1,7 @@
# Docs # Docs
<table-of-contents></table-of-contents>
## Gamelib ## Gamelib
[Link to Gamelib docs](gamelib) [Link to Gamelib docs](gamelib)

24
docs/static/headers.js vendored
View File

@ -12,9 +12,6 @@ function renderTableOfContents() {
const ancestors = []; const ancestors = [];
for (const header of headers) { for (const header of headers) {
if (header.textContent === "Contents") {
continue;
}
const depth = parseInt(header.tagName.slice(1)) - 1; const depth = parseInt(header.tagName.slice(1)) - 1;
while (ancestors.length >= depth) { while (ancestors.length >= depth) {
ancestors.pop(); ancestors.pop();
@ -40,15 +37,20 @@ function renderTableOfContents() {
ancestors.push(ul); ancestors.push(ul);
} }
root.replaceChildren(list); const title = document.createElement("h2");
title.textContent = "Table of contents";
root.replaceChildren(title, list);
} }
function groupHeadersInDiv(headerTag) { function groupHeadersInDiv(headerTag, index = 0) {
const firstElement = document.querySelector(headerTag); const elements = document.querySelectorAll(headerTag);
if (firstElement === null) { const firstElement = elements[index];
if (!firstElement) {
return; return;
} }
let container = document.createElement("div"); let container = document.createElement("div");
console.log(firstElement);
firstElement.replaceWith(container); firstElement.replaceWith(container);
container.append(firstElement); container.append(firstElement);
@ -60,9 +62,13 @@ function groupHeadersInDiv(headerTag) {
if (sib.nodeName === headerTag.toUpperCase()) { if (sib.nodeName === headerTag.toUpperCase()) {
container = document.createElement("div"); container = document.createElement("div");
sib.replaceWith(container); sib.replaceWith(container);
index++;
} }
container.append(sib); container.append(sib);
} }
if (index < elements.length) {
groupHeadersInDiv(headerTag, index + 1);
}
} }
function slugify(elements) { function slugify(elements) {
@ -90,4 +96,6 @@ function attachIdToHeaders() {
attachIdToHeaders(); attachIdToHeaders();
renderTableOfContents(); renderTableOfContents();
groupHeadersInDiv("h2"); for (let i = 2; i <= 6; ++i) {
groupHeadersInDiv(`h${i}`);
}

69
docs/static/style.css vendored
View File

@ -28,22 +28,14 @@ body {
padding: 1rem; padding: 1rem;
max-width: 1000px; max-width: 1000px;
margin: 0 auto; margin: 0 auto;
line-height: 1.5;
} }
h1 { h1, h2, h3, h4, h5, h6 {
font-size: 2.5rem; line-height: 1;
} code {
font-size: inherit;
h2 { }
font-size: 2rem;
}
h3 {
font-size: 1rem;
}
h4 {
font-size: 0.5rem;
} }
a { a {
@ -68,16 +60,21 @@ h1, h2, h3, h4, h5, h6 {
isolation: isolate; isolation: isolate;
position: relative; position: relative;
max-width: max-content; max-width: max-content;
background: var(--clr-bg-1);
border-radius: 0 0.5rem 0.5rem 0;
padding: 0.5em;
&::before { &::before {
content: ""; content: "";
position: absolute; position: absolute;
top: -0.25em; width: 3em;
bottom: -0.25em; top: 0;
right: -1em; bottom: 0;
left: -10rem; left: -3em;
z-index: -1; z-index: -1;
border-radius: 0.5rem; background: linear-gradient(to left, var(--clr-bg-1), transparent);
background: linear-gradient(to left, var(--clr-bg-1) 75%, transparent); border-radius: 0.5rem 0 0 0.5rem;
} }
} }
@ -87,8 +84,32 @@ h2 {
z-index: 10; z-index: 10;
} }
table-of-contents > ul { table-of-contents h2 {
list-style: none; position: initial;
padding-left: 0; }
font-size: 1.25rem;
table-of-contents {
background: var(--clr-bg-1);
border-radius: 0.5rem;
padding: 1.5rem;
display: block;
max-width: max-content;
}
table-of-contents ul:first-of-type {
font-size: 1.1em;
padding-left: 1.5rem;
margin: 0;
}
table-of-contents li: {
margin-bottom: 0.25em;
}
table-of-contents h2 {
padding-inline: 0;
margin: 0;
&::before {
all: initial;
}
} }