# ThicketScript documentation

Source: https://thicketscript.com/docs/

---

URL: https://thicketscript.com/docs/start/

# Getting started

<SiteArt src="/art/start-trail.svg" alt="Illustration: a stone path winding through the forest from a signpost toward a lit cottage" :width="1200" :height="360" eager />

ThicketScript is a language built from the ground up to make games. It reads like TypeScript, has its own type system, and runs on its own virtual machine. One program, `thicket`, runs your code, checks it, formats it, debugs it and builds it into a standalone program.

This section takes you from nothing to a program you can share:

1. **Install** `thicket` (this page).
2. [Your first script](./first-script): write a `.tks` file and run it.
3. [Your first window](./first-window): open a window and put a sprite in it.
4. [Checking your code](./check): find type errors before you run anything.
5. [Building a program](./build-executable): turn a project into a folder you can ship.

## Install

::: info Downloads are coming soon
The [download page](/download) is where `thicket` for Windows, macOS and Linux, plus the IDE plugin, will land.
:::

Installing is one program, `thicket`, on your `PATH`, with nothing else to install: the compiler, the virtual machine, the standard library, the 2D module and the language server all live inside it.

Once it is installed, this prints the version:

```sh
thicket version
```

And this lists every command:

```sh
thicket help
```

## The commands you will use most

| Command | What it does |
|---|---|
| `thicket new <name>` | Make a new project folder from a template. |
| `thicket run` | Run a script or a project. |
| `thicket check` | Type-check without running anything. |
| `thicket watch` | Run, and run again whenever a file changes. |
| `thicket fmt <file>` | Format a source file. |
| `thicket build` | Package a project as a standalone program. |
| `thicket debug` | Run with a debugger attached. |

`thicket help <command>` prints the full reference for any one of them.

## Editor support

`thicket lsp` is a built-in language server. The JetBrains plugin starts it for you and gives you autocomplete, type checking, go-to-definition and error highlighting as you type.

Next: [your first script](./first-script).

---

URL: https://thicketscript.com/docs/start/build-executable

# Building a program

```sh
thicket build
```

`thicket build` turns a project into a standalone program. The result runs on a machine with no `thicket`, no source code and no `thicket_packages/` folder.

## Try it

```sh
thicket new hello
cd hello
thicket build
./build/hello
```

```text
hello from thicket
```

## What you get

The output goes to `build/` inside the project, replaced on each build:

```text
build/
  hello                   the program (a prebuilt runtime)
  bundle.tbc              your compiled code and its frozen config
  package-receipt.json    a record of every file that was placed
```

The program file is a prebuilt runtime. `bundle.tbc` is your compiled bytecode. Keep them side by side.

- A **console app** gets the console runtime.
- A **window app** (a project with a `window` section) gets the window runtime, in a flat folder you can zip and share.

## Ship your assets

Only what the `assets` field lists ships with the program:

```json5
{
    entry: "app.tks",
    window: { title: "My Game" },
    assets: ["assets/**"],
}
```

Each file keeps the path it has in your project, so a path like `assets/player.png` means the same thing in `thicket run` and in the built program.

## Give your app an id

`thicket build` warns when `thicket.json` has no `id`. Without one, the app's save and cache folders are named after the project folder, so two projects in folders with the same name would share them. Set an id before you ship.

## Useful flags

| Flag | What it does |
|---|---|
| `--out <dir>` | Write somewhere other than `build/`. A folder that is not empty is refused unless you add `--force`. |
| `--release` | Drop the source map and function names. |
| `--strategy <name>` | Choose how the program is packaged. |
| `--list-strategies` | Show the strategies that fit this project. |

## Ship a fix without rebuilding everything

The runtime is not tied to one bundle. A `bundle.tbc` from a later build of the same project, made with the same `thicket` version, can be dropped over the old one and runs the new code. Changed assets have to be copied too.

Platforms, strategies and asset options are covered in [Building for each platform](/docs/build/).

---

URL: https://thicketscript.com/docs/start/check

# Checking your code

```sh
thicket check
```

`check` type-checks and compile-checks a program. Nothing runs and nothing is written. It prints `ok` when the program is clean. Otherwise it prints each diagnostic with its file, line, column and severity (`error`, `warning` or `hint`). It exits with code 1 when there is an error. Warnings and hints alone do not fail the check.

Like `run`, it takes a file, a project folder, or nothing (the nearest `thicket.json` above the current folder):

```sh
thicket check
thicket check app.tks
thicket check ./mygame
```

## What it catches

Save this as `oops.tks`:

```ts
let score: int = "ten";
```

```sh
thicket check oops.tks
```

```text
oops.tks(1,5): error: Cannot assign "ten" to int (variable 'score')
oops.tks(1,5): hint PF012: variable 'score' is declared but never used
```

The checker also reports:

- missing type annotations on variables and missing return types on functions (warning `PF071`),
- unused variables (a hint),
- calls with the wrong number or type of arguments,
- members that a class or interface does not declare,
- a class that says `implements` but leaves a member out,
- `await` in the wrong place, and other async mistakes,
- a `switch strict` that misses an enum member.

`check` also reports everything `run` would refuse at compile time, so a clean `check` means the program compiles.

## Window apps are checked too

You can check a window app on a machine with no display. `check` never opens a window, so it is a good fit for a build server or a pre-commit hook.

## In your editor

The JetBrains plugin runs the same checker through `thicket lsp` and underlines problems as you type.

## Formatting

```sh
thicket fmt app.tks
thicket fmt --check app.tks
```

`fmt` formats a file in place and keeps your comments. `--check` writes nothing and exits 1 when the file is not formatted.

## Silencing one line

When a warning is wrong for one line, suppress it on the line before. The code in brackets limits it to one diagnostic:

```ts
// @thicket-ignore-next-line [PF078]
const y: int = legacyRect.width;
```

Next: [building a program](./build-executable).

---

URL: https://thicketscript.com/docs/start/first-script

# Your first script

## One file

Save this as `hello.tks`:

```ts
const name: string = "world";
console.log("Hello, " + name + "!");
```

Run it:

```sh
thicket run hello.tks
```

```text
Hello, world!
```

A `.tks` file runs from top to bottom. You do not need a project file for a quick script.

Two things to notice already:

- **Every declaration has a type.** `const name: string`, not `const name`. The checker warns when a type is missing.
- **Every statement ends with a semicolon.**

## A little more

Template strings, typed arrays and loops all look the way you expect:

```ts
const name: string = "ThicketScript";
const version: int = 1;

console.log(`Hello from ${name} v${version}!`);

const items: Array<string> = ["fast startup", "typed numbers", "batteries included"];
for (const item of items) {
    console.log(`  - ${item}`);
}
```

```text
Hello from ThicketScript v1!
  - fast startup
  - typed numbers
  - batteries included
```

## A project

Real programs live in a project: a folder with a `thicket.json` (or `thicket.json5`) file. Make one with `thicket new`:

```sh
thicket new hello
cd hello
thicket run
```

`thicket new` writes three files:

```text
hello/
  .gitignore
  app.tks
  thicket.json5
```

The project file names the entry file:

```json5
{
  "entry": "app.tks"
}
```

And `app.tks` holds a class with a `static main()` method:

```ts
class ConsoleApp {
    static main(): void {
        console.log("hello from thicket");
    }
}
```

When the entry file declares a class with `static main()`, `thicket run` runs the file's top-level code first, then calls that `main`. A plain `function main()` at the top level is ordinary code and is never called for you.

`main` can also take the command-line arguments and return an exit code:

```ts
class App {
    static main(args: Array<string>): int {
        console.log("started with " + args.length + " arguments");
        return 0;
    }
}
```

Pass arguments after `--`:

```sh
thicket run -- --verbose --level=3
```

## Templates

`thicket new <name> <template>` picks a starting point:

| Template | What you get |
|---|---|
| `console` | A console app (the default). |
| `window` | A window app. |
| `willow` | A console app that uses the willow 2D module. |

## Run it again on every save

```sh
thicket watch
```

`watch` runs the program, then runs it again from scratch whenever a `.tks` file or `thicket.json` in the project changes.

Next: [your first window](./first-window).

---

URL: https://thicketscript.com/docs/start/first-window

# Your first window

A project becomes a **window app** when its `thicket.json` has a `window` section. Without one it is a console app.

## Make the project

```sh
thicket new mygame window
cd mygame
```

Open `thicket.json5` and give the window a title and a size. List the `willow` system, which is the 2D module, and turn on the `fs` permission so the game can load images from disk:

```json5
{
    entry: "app.tks",
    systems: ["willow"],
    window: { title: "My Game", width: 800, height: 600 },
    permissions: { fs: true },
}
```

`window: {}` also works and uses every default.

## Show a sprite

Put an image at `assets/player.png`, then replace `app.tks` with this:

```ts
import { Sprite } from "willow";

class Game {
    static main(): void {
        const player: Sprite = new Sprite("assets/player.png");
        player.setAnchor(0.5, 0.5);
        player.x = 400;
        player.y = 300;
        engine.root2d.add(player);

        const SPEED: float = 200;

        App.onFrame((dt: float): void => {
            if (Keyboard.isDown(Key.RIGHT)) {
                player.x += SPEED * dt;
            }
            if (Keyboard.isDown(Key.LEFT)) {
                player.x -= SPEED * dt;
            }
            if (Keyboard.isDown(Key.DOWN)) {
                player.y += SPEED * dt;
            }
            if (Keyboard.isDown(Key.UP)) {
                player.y -= SPEED * dt;
            }
            player.rotation += Math.PI * dt;
        });
    }
}
```

Run it:

```sh
thicket run
```

The window opens with the sprite in the middle, spinning half a turn per second. The arrow keys move it.

## What is going on

- **`new Sprite(path)`** loads the image and makes a display node that draws it.
- **`setAnchor(0.5, 0.5)`** puts the sprite's origin at its center, so `x` and `y` place the middle of the image and rotation turns it around its center.
- **`engine.root2d`** is the root of the 2D display tree. Anything you `add` to it is drawn every frame.
- **`App.onFrame`** runs your function once per drawn frame. `dt` is the time since the last frame, in seconds, so `SPEED * dt` moves the same distance per second at any frame rate.
- **`Keyboard`** and **`Key`** are global. You do not import them. `Keyboard.isDown` is true while a key is held. `Keyboard.isPressed` is true only on the frame the key goes down.
- **`rotation`** is in radians.

::: tip Avoid naming your class `App`
`App` is the built-in lifecycle class. A class of your own called `App` hides it, and `App.onFrame` stops working in that file. Name your entry class after your game instead.
:::

## Game logic on fixed ticks

`App.onFrame` runs once per drawn frame, so it runs more often on a faster screen. For game logic that should run at a steady rate, use `App.onTick`. Ticks run 60 times a second by default (`App.tps`). Draw-only work, like smoothing an animation, stays in `onFrame`.

Learn more about the 2D module in [willow](/docs/modules/willow).

Next: [checking your code](./check).

---

URL: https://thicketscript.com/docs/language/

# Language guide

ThicketScript will feel familiar if you know TypeScript. Classes, interfaces, generics, arrow functions, `async` and `await` all look the way you expect. Underneath it is its own language, with its own type system, a bytecode compiler and a virtual machine. A few things are deliberately different, and this guide points them out as it goes.

```ts
enum Team {
    Red,
    Blue,
}

class Player {
    constructor(public name: string, public team: Team, public hp: int = 100) {}

    isAlive(): boolean {
        return this.hp > 0;
    }
}

const players: Array<Player> = [
    new Player("Ada", Team.Red),
    new Player("Brin", Team.Blue, 0),
];

for (const p of players) {
    const status: string = p.isAlive() ? "alive" : "down";
    console.log(`${p.name}: ${status}`);
}
```

## The pages

| Page | What it covers |
|---|---|
| [Types](./types) | `int`, `uint`, `float`, `string`, `boolean`, unions, `null`, arrays, maps, `is` and `as`. |
| [Variables](./variables) | `let`, `const`, scope and assignment. |
| [Functions](./functions) | Declarations, arrow functions, default and rest parameters, closures. |
| [Classes](./classes) | Fields, constructors, inheritance, access modifiers, getters, abstract and final. |
| [Interfaces](./interfaces) | Shapes, `implements`, optional members. |
| [Enums](./enums) | Named constants, bitflags, `switch strict`. |
| [Generics](./generics) | Type parameters on functions, classes and interfaces. |
| [Control flow](./control-flow) | `if`, loops, ranges, `switch`, labels. |
| [Async, series and parallel](./async) | Promises, `await`, and the `series` and `parallel` blocks. |
| [Errors](./errors) | `throw`, `try`, typed `catch`, inline `try`, `defer`. |
| [Modules and imports](./modules) | `import`, `export`, system modules and path aliases. |
| [Coming from TypeScript](./coming-from-typescript) | What is left out, what is accepted and ignored, and what works differently. |

## The house style

Every sample on this site follows the same rules, and the checker nudges you toward them too:

- **Explicit types everywhere.** `let count: int = 0;`, not `let count = 0;`. Functions declare their return type, even `void`.
- **Semicolons** at the end of every statement.
- **`int`, `uint` and `float`, never `number`.** There is no `number` type.
- **`boolean`, never `bool`.**
- **`for (const x of items)`** to loop over a collection.
- **Parentheses** around every `if`, `for`, `while` and `switch` condition.

## Feature checklist at a glance

Everything on this list runs on the current `thicket`.

**Language**

- Classes, interfaces, generics, enums (numeric, string and bitflag) and `switch strict`.
- `struct` value types with methods and operator overloads.
- Packed numbers in struct fields: `int8`, `int16`, `int32`, `uint8`, `uint16`, `uint32`, `float32`.
- Integer overflow and out-of-range stores raise a `RangeError`.
- Ranges: `for (const i of 0..<3)` (or `in`) counts 0, 1, 2, and `0..<3` on its own is the array `[0, 1, 2]`.
- `defer` for cleanup on any scope exit, typed `catch`, and inline `try` expressions.
- `dump()` prints values with their variable names.

**Async and threads**

- `async` and `await` with Promises.
- `series` and `parallel`, as function modifiers or blocks.
- `async worker` functions: real threads, each in an isolated VM.
- `async mutex` functions with per-key locks.

**Standard library**

- 41 easing curves through `Ease.apply`, plus `Math.lerp`, `moveTowards`, `snap`, `wrap` and `smoothstep`.
- Seeded `Random`: the same seed gives the same rolls.
- Collection extras: `unique`, `compact`, `sum`, `avg` and `first` on arrays; `union` and `intersection` on `Set`.
- Reactive state: `Ref`, `computed` and `Signal` from the `reactivity` module.
- Databases: SQLite everywhere. Linux release builds add MySQL/MariaDB, Postgres and Redis. Packaged window builds carry SQLite only.

**Safety**

- A sandbox by default: file, network, crypto, database, shell, environment and audio access stay off until `thicket.json` grants them.
- A stack overflow is a catchable `RangeError`, not a crash.

**Tooling, all in `thicket`**

- `run`, `watch`, `check`, `fmt`, `debug`, `compile`, `build`, `new`, `tool`, `lsp` and `mcp`. `mcp` runs a Model Context Protocol server. Use `--project <dir>` when a client starts it outside the project folder.
- Debugging over the Debug Adapter Protocol for your IDE, or Chrome DevTools.

## Coming from TypeScript

The differences that trip people up most. The [Coming from TypeScript](./coming-from-typescript) page has the full list.

| TypeScript | ThicketScript |
|---|---|
| `number` | `int`, `uint` or `float` |
| `7 / 2` is `3.5` | `7 / 2` is `3` when both sides are `int` |
| `==` coerces | `==` and `===` are both strict |
| Structural typing | Nominal: a class must say `implements` to count as the interface |
| Integer overflow is silent | Integer overflow raises a `RangeError` |
| `Promise.all` | Also `parallel { ... }` |

---

URL: https://thicketscript.com/docs/language/async

# Async, series and parallel

Games wait on things all the time: files, network calls, a timer, an animation finishing. ThicketScript has the `async` and `await` you know from TypeScript, plus two blocks of its own, `series` and `parallel`, that say what you mean with less ceremony.

## async and await

```ts
async function loadLevel(name: string): Promise<string> {
    await sleep(10);
    return "level " + name;
}

const level: string = await loadLevel("1-1");
console.log(level);
```

- An `async` function always returns a `Promise<T>`. Write the return type that way.
- `await` waits for a promise and gives you its value.
- `await` works inside `async` functions and at the top level of the entry file.
- `sleep(ms)` is built in.

A rejected promise throws at the `await`, so `try` and `catch` work as you expect:

```ts
async function risky(): Promise<int> {
    throw new Error("network down");
}

try {
    const n: int = await risky();
    console.log(n);
} catch (err) {
    console.log("failed: " + err.message);
}
```

A promise that rejects with nobody listening is an **unhandled rejection**. `thicket run` reports it and exits with code 1.

## Promise helpers

`Promise.all`, `Promise.race`, `Promise.allSettled` and `Promise.any` work as in TypeScript, along with `.then`, `.catch` and `.finally`.

```ts
async function fetchScore(id: int): Promise<int> {
    await sleep(5);
    return id * 10;
}

const scores: Array<int> = await Promise.all([fetchScore(1), fetchScore(2)]);
console.log(scores.join(", "));
```

## Timers

```ts
const handle: int = setTimeout((): void => {
    console.log("too late");
}, 5000);
clearTimeout(handle);

setTimeout((): void => {
    console.log("fired");
}, 10);
```

`setInterval` and `clearInterval` repeat. In a window app, the [App lifecycle](/docs/start/first-window#game-logic-on-fixed-ticks) callbacks are usually the better tool for per-frame work.

## series: one after another

Inside a `series` block, every call that returns a promise is awaited for you. No `await` on each line:

```ts
async function step(name: string): Promise<string> {
    await sleep(5);
    return name + " done";
}

series {
    const a: string = step("load map");
    const b: string = step("spawn enemies");
    console.log(a);
    console.log(b);
}
```

Calls that are not async cost nothing extra. A call typed `Promise<int>` gives you an `int` directly.

`series` also works on a function or method, which makes the whole body implicitly awaited:

```ts
async function fade(name: string): Promise<void> {
    await sleep(5);
    console.log("faded " + name);
}

series function intro(): void {
    fade("logo");
    fade("title");
    console.log("intro finished");
}

await intro();
```

To start something without waiting for it, put `void` in front: `void playMusic("town.ogg");`.

## parallel: all at once

Every statement in a `parallel` block starts at the same time. The block ends when all of them have finished, like `Promise.all`:

```ts
async function loadAsset(name: string, ms: int): Promise<string> {
    await sleep(ms);
    return name;
}

parallel {
    let texture: string = loadAsset("tiles.png", 20);
    let music: string = loadAsset("theme.ogg", 10);
}
console.log(texture, music);
```

Variables declared with `let` in a `parallel` block can be read after it.

## Mixing them

Nest `parallel` inside `series` to load some things in order and others together:

```ts
async function load(name: string): Promise<string> {
    await sleep(5);
    return name;
}

series {
    const config: string = load("config");
    parallel {
        let tiles: string = load("tiles");
        let sounds: string = load("sounds");
    }
    console.log(config, tiles, sounds);
}
```

`series` and `parallel` also work on loops and `if`: `series for (const item of items) { ... }` handles one item at a time, and `parallel for (const item of items) { ... }` starts them all at once.

## The rules

- **No `await` inside `series` or `parallel`.** They do the waiting.
- **They are statements, not expressions.** `let x = parallel { ... }` is an error.
- **They need an async context**: an `async`, `series` or `parallel` function, or the top level of the entry file.
- **No `parallel` directly inside `parallel`.** Use one block.
- **No `return` out of a `parallel` statement.** Each statement runs as its own task.
- If a statement in a `parallel` block throws, the block waits for the others to finish, then throws the first error.

---

URL: https://thicketscript.com/docs/language/classes

# Classes

## A class

```ts
class Enemy {
    name: string;
    hp: int;

    constructor(name: string, hp: int) {
        this.name = name;
        this.hp = hp;
    }

    hit(damage: int): void {
        this.hp -= damage;
        if (this.hp < 0) {
            this.hp = 0;
        }
    }

    isDefeated(): boolean {
        return this.hp == 0;
    }
}

const slime: Enemy = new Enemy("Slime", 10);
slime.hit(4);
console.log(slime.name, slime.hp, slime.isDefeated());
```

Methods do not use the `function` keyword. Writing `function hit()` inside a class is a syntax error.

## Field defaults

When every field has a default and there is no constructor, one is made for you:

```ts
class Settings {
    volume: float = 0.8;
    fullscreen: boolean = false;
    language: string = "en";
}

const settings: Settings = new Settings();
console.log(settings.volume, settings.language);
```

## Constructor parameter properties

Put `public`, `private`, `protected` or `readonly` (alone or after an access modifier) on a constructor parameter to declare the field and assign it in one step:

```ts
class Point {
    constructor(public x: int, public y: int) {}
}

const p: Point = new Point(3, 4);
console.log(p.x, p.y);
```

## Access modifiers and readonly

| Modifier | Visible from |
|---|---|
| `public` | Everywhere (the default) |
| `protected` | The class and its subclasses |
| `private` | The class only |

`readonly` fields can only be set in the constructor. The checker enforces all of these.

```ts
class Wallet {
    readonly owner: string;
    private coins: int = 0;

    constructor(owner: string) {
        this.owner = owner;
    }

    add(amount: int): void {
        this.coins += amount;
    }

    get balance(): int {
        return this.coins;
    }
}

const w: Wallet = new Wallet("Ada");
w.add(25);
console.log(w.owner, w.balance);
```

## Getters and setters

`get` and `set` define properties that run code. They are read and written like fields:

```ts
class Temperature {
    private celsius: float = 0;

    get fahrenheit(): float {
        return this.celsius * 1.8 + 32;
    }

    set fahrenheit(value: float) {
        this.celsius = (value - 32) / 1.8;
    }
}

const t: Temperature = new Temperature();
t.fahrenheit = 212;
console.log(t.fahrenheit);
```

## Static members and constants

```ts
class Limits {
    static const MAX_PARTY: int = 4;
    static created: int = 0;

    static track(): void {
        Limits.created += 1;
    }
}

Limits.track();
console.log(Limits.MAX_PARTY, Limits.created);
```

`static const` is the preferred way to write a class constant. Statics are reached through the class name, not an instance. A subclass inherits its parent's statics.

## Inheritance

A class extends one parent. A subclass constructor must call `super()` before it touches `this`:

```ts
class Animal {
    constructor(public name: string) {}

    speak(): string {
        return this.name + " makes a sound";
    }
}

class Dog extends Animal {
    tricks: int;

    constructor(name: string, tricks: int) {
        super(name);
        this.tricks = tricks;
    }

    override speak(): string {
        return this.name + " barks";
    }
}

const rex: Animal = new Dog("Rex", 3);
console.log(rex.speak());
console.log(rex instanceof Dog);
```

`override` is optional, but the checker then makes sure the parent really has that method. `super.speak()` calls the parent's version.

## Abstract classes

An abstract class cannot be created directly. Subclasses must implement its abstract methods:

```ts
abstract class Shape {
    abstract area(): float;

    describe(): string {
        return "area " + this.area();
    }
}

class Circle extends Shape {
    constructor(public radius: float) {
        super();
    }

    area(): float {
        return Math.PI * this.radius * this.radius;
    }
}

const c: Circle = new Circle(2);
console.log(c.describe());
```

## Final

`final class` cannot be extended. A `final` method cannot be overridden.

```ts
final class Token {
    value: string = "";
}

class Base {
    final id(): string {
        return "base";
    }
}

console.log(new Token().value.length, new Base().id());
```

## Custom `toString`

A `toString()` method is used whenever the object becomes a string:

```ts
class Rgb {
    constructor(public r: int, public g: int, public b: int) {}

    toString(): string {
        return `rgb(${this.r}, ${this.g}, ${this.b})`;
    }
}

console.log(String(new Rgb(255, 128, 0)));
```

## Not supported

- `#private` fields. Use `private`.
- Static initializer blocks. Use static fields with initializers.
- Multiple inheritance. Use [interfaces](./interfaces) and composition.

---

URL: https://thicketscript.com/docs/language/coming-from-typescript

# Coming from TypeScript

ThicketScript shares TypeScript's syntax, but it is its own language, with its own type checker, compiler and VM.
There is no JavaScript underneath. Most of what you write in TypeScript works as it is. This page covers the rest:
what works differently, what is accepted and ignored, and what is left out.

## The differences that matter

### Numbers have real types

There is no `number`. Pick `int` (32-bit signed), `uint` (32-bit unsigned) or `float` (64-bit). Types are always
lowercase: `int`, `uint`, `float`, `string`, `boolean`.

`Int(x)`, `Float(x)` and their siblings are conversion functions, not types. `Int("42")` turns a string into an
`int`, and raises if it can't. Writing `Int` where a type goes is an error that points you to `int`.

```ts
const n: int = Int("42");
const f: float = Float("1.5");
console.log(n + 1, f * 2.0);
```

```text
43 3
```

### `int / int` truncates

Dividing two `int` values gives an `int`, rounded toward zero. A `float` operand, or a `float` target, makes it float
math.

```ts
const a: int = 7;
const b: int = 2;
console.log(a / b, -9 / 4);
const half: float = a / b;
console.log(half);
```

```text
3 -2
3.5
```

### Overflow raises an error

Integers never wrap and never quietly turn into floats. Going past the range raises a `RangeError`, so the bug
shows up on the line that caused it.

```ts
const big: int = 2147483647;
try {
    console.log(big + 1);
} catch (e) {
    console.log(e);
}
```

```text
RangeError: integer overflow
```

The same goes for packed struct fields: storing a computed 300 in a `uint8` raises instead of keeping 44, and a literal 300 there is a compile error.

### Equality is strict

`==` and `===` both compare without coercion. Comparing a string to a number is a checker error, because it can
never be true.

### Interfaces are nominal

A class counts as an interface only when it says `implements`. Matching the shape is not enough.

### Structs are values

`struct` is new. A struct is copied on assignment, carries methods and operators, and can use packed number fields.
See [Features](/features#structs-with-operators).

### Async has more words

`series` and `parallel` sit beside `async` and `await`. `async worker` runs a function on its own thread, and
`async mutex` runs one call at a time. See [Async, series and parallel](./async).

## Accepted and ignored

These type-level features parse without error. They have no runtime effect, and `thicket fmt` prints them as you
wrote them. You can paste TypeScript that uses them and keep going.

- Intersection types: `A & B`. The type is checked as `any`, so `x.a` and `x.b` work on an `A & B` value.
- Conditional types: `T extends U ? X : Y`. Checked as `any`.
- Mapped types: `{ [K in keyof T]: ... }`. Checked as `any`.
- Template literal types: `` `on${string}` ``. Checked as `string`.
- The `infer` keyword, inside a conditional type.
- `keyof` as a type operator. It is checked as `string`. `typeof x` in a type annotation is supported.
- Type predicates: a `x is string` return type. The function returns `boolean`, and the call does not narrow.
- Indexed access types: `T[K]`, such as the value of a mapped type, `{ [K in keyof T]: T[K] }`. Checked as `any`.
- Index signatures in a type literal: `{ [key: string]: int }`. Checked as `any`.
- Generic constraints: `T extends Something`. Not enforced: any argument is accepted.
- Type-only imports: `import type { X } from "./x"`. The `type` keyword is dropped and the name is imported, but,
  as in TypeScript, `X` is then usable only in type positions.
- Static initializer blocks: `static { ... }` inside a class. The block never runs; `thicket fmt` keeps it.
- Type arguments on calls: `first<string>(names)` and `new Box<int>(...)`.

Union types are not on this list. They are fully checked: a union with `null` needs `?.` or a guard before you use
it, and `typeof` and `is` narrow a union inside a branch. `abstract` is not on it either. Abstract classes and
methods are enforced.

### Non-null assertions are checked

ThicketScript supports TypeScript's postfix `!` with the same syntax and typing.
It narrows `T | null | undefined` to `T`:

```ts
function findTitle(id: int): string | null {
    return id == 1 ? "Intro" : null;
}

const title: string = findTitle(1)!;
console.log(title); // Intro
```

The deliberate difference is run-time behavior. TypeScript erases `!`, so a
wrong assertion carries the null forward until something else fails.
ThicketScript checks it: a nullish value raises a `TypeError` at the `!` that
names the expression. One more difference: `x! = v` is an error here (assign to
`x`), where TypeScript accepts it. Use `??` or an explicit guard when absence is
normal.

Two TypeScript features look ignorable and are not. Index signatures on an `interface` are discarded, so reading an
undeclared property is an error (`Property 'zzz' does not exist`): declare the properties, or use `Map<string, T>`.
Declaration merging does not happen: a second `interface A { ... }` is an error (`Duplicate declaration 'A'`), so
write one declaration.

### `Map.get` can be undefined

As in TypeScript, `map.get(key)` is typed `V | undefined`, and `has(key)` does not
narrow it. Use `!` when the key must exist, `??` when a missing key is normal, or
test the result against `undefined`:

```ts
const ages: Map<string, int> = new Map<string, int>();
ages.set("ada", 36);
const known: int = ages.get("ada")!;
const other: int = ages.get("bob") ?? 0;
```

The bracket read `ages["ada"]` is typed `int | undefined` too, like `get`; `ages["ada"] = 1` is checked against `int`.

## Left out

These are recognized and rejected with a clear error.

| Feature | What you get | Use instead |
|---|---|---|
| Decorators, `@sealed` | "Decorators are not supported" | Plain functions or base classes |
| BigInt, `10n` | "ThicketScript has no bigint/int64" | `int`, `uint` or `float` (exact to 2^53) |
| Private fields, `#x` | "Private fields are not supported" | The `private` modifier |
| `new Function()` | A runtime error | Function declarations or arrows |
| `eval()` | Not defined | Nothing: there is no runtime code generation |

These have no support at all:

- **Namespaces.** `namespace Foo { }` doesn't parse. `import * as ns from "./mod"` works.
- **Generators.** `function*` and `yield` don't parse.
- **`Symbol`.** Not defined.
- **The wrapping `Proxy` and `Reflect`.** `new Proxy(target, handler)` and `Reflect` are not defined. For wildcard
  property hooks, extend the built-in `Proxy` class instead.

## Different on purpose

- **`Date`** is ThicketScript's own struct, not the JavaScript class. There is no `new Date()`. `Date.now()` returns a
  `Date`, and `Date.nowMs()` gives epoch milliseconds.
- **No prototype chain, no `this` rebinding, no implicit coercion.** A method's `this` is its object.

## Why leave things out

ThicketScript keeps the practical core you use to write a game and drops what adds weight without helping game code.
The aim is a language a TypeScript developer can read on day one, running on a small, fast VM.

---

URL: https://thicketscript.com/docs/language/control-flow

# Control flow

Conditions always go in parentheses: `if (x > 0)`, never `if x > 0`.

## if and else

```ts
const hp: int = 12;

if (hp <= 0) {
    console.log("defeated");
} else if (hp < 20) {
    console.log("hurt");
} else {
    console.log("healthy");
}

const label: string = hp > 50 ? "strong" : "weak";
console.log(label);
```

## Looping over a collection: `for...of`

```ts
const party: Array<string> = ["Ada", "Brin", "Cass"];

for (const name of party) {
    console.log(name);
}
```

`for...of` is the loop to reach for. It works on arrays, maps, sets and strings.

::: tip One way to loop
The language also accepts a `foreach` keyword as an alias. Don't use it. The style guide allows only `for...of`, and every sample on this site follows it.
:::

## Counting loops

```ts
let total: int = 0;
for (let i: int = 1; i <= 10; i++) {
    total += i;
}
console.log(total);    // 55
```

Each iteration gets a fresh `i`, so closures made inside the loop each see their own value.

## Ranges

`a..b` includes both ends. `a..<b` leaves out the end. Loop over a range with `for...in` or `for...of`; both count the same values:

```ts
for (const i in 0..3) {
    console.log(i);    // 0, 1, 2, 3
}

for (const i in 0..<3) {
    console.log(i);    // 0, 1, 2
}
```

A range is also a value: an array of the same numbers, so you can store it, pass it or spread it.

```ts
const steps: int[] = 0..<3;            // [0, 1, 2]
const padded: int[] = [9, ...(1..2)];  // [9, 1, 2]
```

## Object keys

`for...in` over an object gives you its keys:

```ts
const stats: Object = { str: 5, dex: 7 };
for (const key in stats) {
    console.log(key);
}
```

## while and do...while

```ts
let n: int = 3;
while (n > 0) {
    console.log(n);
    n--;
}

let tries: int = 0;
do {
    tries++;
} while (tries < 3);
console.log(tries);
```

## switch

Each branch needs `case` and usually a `break`. Without `break`, a case falls through to the next one.

```ts
function weekday(day: int): string {
    switch (day) {
        case 0:
            return "Sunday";
        case 6:
            return "Saturday";
        default:
            return "a weekday";
    }
}

console.log(weekday(6));
```

For enums, `switch strict` checks that every member is covered, and `switch bitflag` matches flags. See [Enums](./enums).

## break, continue and labels

```ts
for (let i: int = 0; i < 10; i++) {
    if (i == 5) {
        break;
    }
    if (i % 2 == 0) {
        continue;
    }
    console.log(i);    // 1, 3
}

outer: for (let row: int = 0; row < 3; row++) {
    for (let col: int = 0; col < 3; col++) {
        if (row + col > 2) {
            break outer;
        }
    }
}
```

Labels can only go on loops.

## Running code on the way out: `defer`

`defer` runs a statement when the current scope ends, however it ends. See [Errors](./errors#defer).

---

URL: https://thicketscript.com/docs/language/enums

# Enums

## A basic enum

Members count up from 0:

```ts
enum State {
    Idle,
    Walking,
    Jumping,
}

const s: State = State.Walking;
console.log(s);    // 1
```

The type of a member is the enum, so declare the variable as `State`, not `int`.

## Explicit values

```ts
enum Direction {
    Up = "UP",
    Down = "DOWN",
}

enum Status {
    Unknown,
    Active = 10,
    Pending,
}

console.log(Direction.Up, Status.Pending);    // UP 11
```

After an explicit number, counting carries on from it.

## Bitflags

`enum bitflag` gives each member its own bit (1, 2, 4, 8 and so on), so you can combine them:

```ts
enum bitflag Permission {
    Read,
    Write,
    Execute,
}

const p: int = Permission.Read | Permission.Write;
console.log(p);    // 3
```

`switch bitflag` tests each case with a bitwise AND, so more than one case can run:

```ts
enum bitflag Perm {
    Read,
    Write,
    Execute,
}

const granted: int = Perm.Read | Perm.Write;

switch bitflag (granted) {
    case Perm.Read:
        console.log("can read");
        break;
    case Perm.Write:
        console.log("can write");
        break;
    case Perm.Execute:
        console.log("can execute");
        break;
}
```

In a `switch bitflag`, `break` moves on to the next case. `stop` leaves the whole switch.

## Exhaustive switches

`switch strict` makes the checker confirm that every member of the enum has a case. Add a member later and every `switch strict` that misses it becomes an error:

```ts
enum Suit {
    Hearts,
    Spades,
}

function suitName(suit: Suit): string {
    switch strict (suit) {
        case Suit.Hearts:
            return "hearts";
        case Suit.Spades:
            return "spades";
    }
    return "";
}

console.log(suitName(Suit.Spades));
```

## Doc comments

`/** */` comments on members show up in IDE hover and autocomplete:

```ts
enum HttpStatus {
    /** The request succeeded. */
    Ok = 200,
    /** Nothing at that path. */
    NotFound = 404,
}

console.log(HttpStatus.NotFound);
```

---

URL: https://thicketscript.com/docs/language/errors

# Errors

## Throwing and catching

```ts
function divide(a: float, b: float): float {
    if (b == 0) {
        throw new RangeError("division by zero");
    }
    return a / b;
}

try {
    console.log(divide(10, 0));
} catch (err) {
    console.log(err.name + ": " + err.message);
} finally {
    console.log("done");
}
```

`finally` runs whether the `try` succeeds or throws. You can use `try` with only `finally`.

## The error classes

`Error` is the base class. It has `message`, `name` and `stack`, a trace of where the error was created. The built-in subclasses are `TypeError`, `RangeError`, `ReferenceError`, `SyntaxError` and `AggregateError`.

You can make your own:

```ts
class SaveError extends Error {
    constructor(message: string, public slot: int) {
        super(message);
    }
}

try {
    throw new SaveError("disk full", 2);
} catch (err) {
    console.log(err.message);
}
```

## Typed catch clauses

Give the catch variable a type to catch only that kind of error. The first matching clause runs. An untyped clause catches everything, so put it last. If nothing matches, the error keeps going.

```ts
function parseLevel(text: string): int {
    if (text.length == 0) {
        throw new TypeError("empty level number");
    }
    return Int(text);
}

try {
    parseLevel("");
} catch (err: TypeError) {
    console.log("type error: " + err.message);
} catch (err: RangeError) {
    console.log("range error: " + err.message);
} catch (err) {
    console.log("something else");
}
```

## Inline try

`try` in front of an expression gives `null` when it throws. Pair it with `??` for a fallback:

```ts
const good: int | null = try Int("123");
const bad: int | null = try Int("abc");
const level: int = try Int("abc") ?? 1;
console.log(good, bad, level);
```

## defer

`defer` runs a statement when the current scope ends: normally, by `return`, or by an error. It is the tidy way to release something you opened:

```ts
function work(): void {
    console.log("open");
    defer console.log("close");
    console.log("working");
}

work();
```

Several `defer` statements run in reverse order, last one first.

## Errors in async code

When an `async` function throws, its promise rejects. Awaiting it throws the error at the `await`, so the same `try` and `catch` work. See [Async, series and parallel](./async).

---

URL: https://thicketscript.com/docs/language/functions

# Functions

## Declaring a function

Every parameter has a type and every function declares what it returns:

```ts
function add(a: int, b: int): int {
    return a + b;
}

function log(message: string): void {
    console.log("[game] " + message);
}

log("sum is " + add(2, 3));
```

Functions declared at the top level of a file can be called from anywhere in that file, even above the declaration.

## Arrow functions

```ts
const square: (x: float) => float = (x: float): float => x * x;

const clamp: (v: int, lo: int, hi: int) => int = (v: int, lo: int, hi: int): int => {
    if (v < lo) {
        return lo;
    }
    if (v > hi) {
        return hi;
    }
    return v;
};

console.log(square(3), clamp(12, 0, 10));
```

A function type is written `(x: float) => float`. You can also use the plain `Function` type when the exact signature does not matter.

When an arrow function is passed somewhere that already has a function type, its parameter types come from there:

```ts
const nums: Array<int> = [1, 2, 3, 4];
const evens: Array<int> = nums.filter((n: int): boolean => n % 2 == 0);
console.log(evens.join(","));
```

## Default parameters

```ts
function greet(name: string = "world"): string {
    return "Hello, " + name;
}

console.log(greet());
console.log(greet("Ada"));
```

## Rest parameters and spread

```ts
function sum(...nums: Array<int>): int {
    let total: int = 0;
    for (const n of nums) {
        total += n;
    }
    return total;
}

const values: Array<int> = [4, 5, 6];
console.log(sum(1, 2, 3));
console.log(sum(...values));
```

Every argument a rest parameter collects is checked against its element type.

## Closures

A function keeps access to the variables around it, even after the outer function returns:

```ts
function makeCounter(): () => int {
    let count: int = 0;
    return (): int => {
        count += 1;
        return count;
    };
}

const next: () => int = makeCounter();
console.log(next());    // 1
console.log(next());    // 2
```

## Functions are values

Pass them in, return them, store them:

```ts
function applyTwice(f: (n: int) => int, x: int): int {
    return f(f(x));
}

const double: (n: int) => int = (n: int): int => n * 2;
console.log(applyTwice(double, 3));    // 12
```

## Async functions

An `async` function returns a `Promise` and can use `await`. See [Async, series and parallel](./async).

---

URL: https://thicketscript.com/docs/language/generics

# Generics

Type parameters let one function or class work with many types while keeping them checked.

## Generic functions

```ts
function firstOr<T>(items: Array<T>, fallback: T): T {
    if (items.length == 0) {
        return fallback;
    }
    return items[0];
}

const n: int = firstOr([3, 4], 0);
const s: string = firstOr([], "none");
console.log(n, s);
```

The checker infers `T` from the arguments, then checks the result. `const s: string = firstOr([3, 4], 0);` would be an error, because `T` is `int` there.

You can also pass the type yourself: `firstOr<int>(scores, 0)`.

## Generic classes

```ts
class Stack<T> {
    private items: Array<T> = [];

    push(item: T): void {
        this.items.push(item);
    }

    pop(): T | null {
        if (this.items.length == 0) {
            return null;
        }
        return this.items.pop();
    }

    get size(): int {
        return this.items.length;
    }
}

const moves: Stack<string> = new Stack<string>();
moves.push("left");
moves.push("jump");
console.log(moves.pop(), moves.size);
```

## Write the type arguments in annotations

A type annotation must give every type argument. `let m: Map = ...` is an error. Write `Map<string, int>`, or `Map<any, any>` when you really mean any. A `new` expression can leave them out:

```ts
const scores: Map<string, int> = new Map();
scores.set("ada", 10);
console.log(scores.get("ada")); // get answers int | undefined; use ! or ?? to get an int
```

## Type arguments are checked

`Array<int>` and `Array<string>` are different types, and so are `Promise<int>` and `Promise<string>`. Arguments are covariant, as in TypeScript: an `Array<int>` can be used where an `Array<float>` is expected, but not the other way round.

```ts
const ints: Array<int> = [1, 2];
const floats: Array<float> = ints;
console.log(floats.length);
```

## At run time

Generics are erased. Every `Stack<T>` shares the same compiled code, and there is no type information for `T` at run time. All the checking happens before the program runs.

---

URL: https://thicketscript.com/docs/language/interfaces

# Interfaces

An interface describes the members something must have. It exists only for the checker and produces no code.

```ts
interface Damageable {
    hp: int;
    takeDamage(amount: int): void;
}

class Crate implements Damageable {
    hp: int = 3;

    takeDamage(amount: int): void {
        this.hp -= amount;
    }
}

function smash(target: Damageable): void {
    target.takeDamage(1);
}

const crate: Crate = new Crate();
smash(crate);
console.log(crate.hp);
```

## `implements` is checked

When a class says `implements`, the checker verifies that it really provides every member, with compatible types. A missing method is an error on the class name:

```ts
class Ghost implements Damageable {
    hp: int = 1;
}
// error: Class 'Ghost' incorrectly implements interface 'Damageable': missing member 'takeDamage'
```

Members inherited from a parent class count.

## Interfaces are nominal

This is the biggest difference from TypeScript. A class only counts as an interface when it says so. Having the same members is not enough:

```ts
class Barrel {
    hp: int = 5;
    takeDamage(amount: int): void {}
}

const d: Damageable = new Barrel();   // error: Cannot assign Barrel to Damageable
```

Add `implements Damageable` to `Barrel` and the assignment is fine.

## Optional and readonly members

```ts
interface ItemInfo {
    readonly id: string;
    label: string;
    description?: string;
}

class Potion implements ItemInfo {
    readonly id: string = "potion";
    label: string = "Potion";
}

function describe(item: ItemInfo): string {
    return item.label + ": " + (item.description ?? "no description");
}

console.log(describe(new Potion()));
```

- `?` means a class may leave the member out. Reading it gives `T | null`, so handle the `null` with `??`, `?.` or a check.
- `readonly` cannot be assigned through the interface.

## Extending an interface

An interface can extend one other interface:

```ts
interface Named {
    name: string;
}

interface Pet extends Named {
    owner: string;
}

class Cat implements Pet {
    name: string = "Mochi";
    owner: string = "Ada";
}

const n: Named = new Cat();
console.log(n.name);
```

A class can extend a parent and implement several interfaces: `class GuideDog extends Dog implements Pet, Trained`.

## Generic interfaces

```ts
interface Container<T> {
    get(): T;
    set(value: T): void;
}

class Slot implements Container<string> {
    private value: string = "";
    get(): string {
        return this.value;
    }
    set(value: string): void {
        this.value = value;
    }
}

const s: Slot = new Slot();
s.set("sword");
console.log(s.get());
```

## Methods cannot be swapped

A method declared as `go(): void;` is a contract, not a field you can reassign. If you need a replaceable callback, declare a property with a function type instead: `go: () => void;`.

---

URL: https://thicketscript.com/docs/language/modules

# Modules and imports

Every `.tks` file is a module. Share code between files with `export` and `import`, using the same syntax as TypeScript.

## Exporting

```ts
// src/combat/damage.tks
export const CRIT_MULTIPLIER: int = 2;

export function damage(base: int, crit: boolean): int {
    return crit ? base * CRIT_MULTIPLIER : base;
}

export default class Dice {
    static label(sides: int): string {
        return "d" + sides;
    }
}
```

## Importing

```ts
// src/main.tks
import Dice, { damage } from "./combat/damage";

console.log(damage(5, true));
console.log(Dice.label(20));
```

Relative paths start with `./` or `../`. The `.tks` extension is optional. A path that names a folder loads that folder's `index.tks`.

All the usual forms work:

```ts
import { damage, CRIT_MULTIPLIER } from "./combat/damage";   // named
import { damage as hit } from "./combat/damage";             // renamed
import Dice from "./combat/damage";                          // default
import * as combat from "./combat/damage";                   // namespace
import type { Enemy } from "./enemy";                        // types only
import "./setup";                                            // run for side effects
```

And on the export side, `export { a, b as c }`, `export { x } from "./other"` and `export * from "./other"` re-export from another module.

Each module runs once, the first time it is imported. Circular imports are allowed: classes and functions can refer to each other across the cycle.

## System modules

Some modules are built into `thicket`. You import them by name:

```ts
import { Files } from "fs";
import { Http } from "http";
import { Sprite } from "willow";
```

Each one exports a class you call directly, like `Files.readText(path)` or `Http.get(url)`.

| Kind | Names |
|---|---|
| Always available | `fs`, `env`, `events`, `reactivity` |
| Listed in `systems` | `audio`, `bitmap`, `compress`, `crypto`, `database`, `http`, `net`, `ws`, `shell` |
| Host modules | `willow` |

`fs` also carries the path helpers, such as `Files.join` and `Files.dirname`. There is no separate `path` module.

The everyday names, like `console`, `Math`, `JSON`, `print`, `sleep` and the error classes, need no import at all. The same goes for `System` (the platform, arguments, `System.exit`), and in a window app `engine`, `App`, `Keyboard`, `Mouse` and `Gamepad`.

## systems and permissions

A project's `thicket.json` can list the systems it uses:

```json5
{
    entry: "src/main.tks",
    systems: ["http", "willow"],
    permissions: { net: true, fs: true },
}
```

- **No `systems` key** means every system the host has.
- **A list is strict.** Importing a listable system that is not on the list is an error, with a hint to add it.
- **Permissions are separate.** A system says "include this code". A permission says "allow it at run time". The first call that needs a permission you have not granted throws a `PermissionError` naming the fix. The permissions are `fs`, `net`, `crypto`, `database`, `shell`, `env` and `audio`, all off by default. `async worker` functions need no permission: a worker is pure computation and gets no I/O modules. The checker rejects an imported I/O binding used in a worker.

## Path aliases

Long relative paths get old fast. `compiler.paths` in `thicket.json` defines shortcuts:

```json5
{
    entry: "src/main.tks",
    compiler: { paths: { "@combat/*": "src/combat/*" } },
}
```

```ts
import { CRIT_MULTIPLIER } from "@combat/damage";
console.log(CRIT_MULTIPLIER);
```

## Packages

Code from another folder, a git repository or a zip is a package. You import it by name, just like a system. See [Packages](/docs/packages/).

---

URL: https://thicketscript.com/docs/language/types

# Types

ThicketScript checks types before your program runs. The checker catches mistakes early, and the IDE uses the same information for autocomplete.

## The basic types

| Type | What it holds | Example |
|---|---|---|
| `int` | 32-bit signed integer | `let lives: int = 3;` |
| `uint` | 32-bit unsigned integer | `let color: uint = 0xFF8800FF;` |
| `float` | 64-bit floating point | `let speed: float = 2.5;` |
| `string` | Text | `let name: string = "Ada";` |
| `boolean` | `true` or `false` | `let ready: boolean = false;` |
| `void` | No value, for function returns | `function log(): void {}` |
| `null`, `undefined` | No value | `let target: Enemy \| null = null;` |
| `any` | Turns checking off for one value | Use sparingly. |

There is no `number` type and no `bool`. Pick `int`, `uint` or `float`, and write `boolean`.

## Integers are integers

Arithmetic on two `int` values stays an `int`. That includes division, which truncates toward zero:

```ts
const a: int = 7;
const b: int = 2;
console.log(a / b);      // 3
console.log(-9 / 4);     // -2

const half: float = a / b;
console.log(half);       // 3.5
```

A `float` target, like `half` above, makes the whole expression float math. A `float` operand does the same.

Integers never wrap silently. Going past the range raises a `RangeError`:

```ts
const big: int = 2147483647;
console.log(big + 1);    // RangeError: integer overflow
```

Values above `0x7FFFFFFF`, like most RGBA colors, need `uint`.

## Number literals

```ts
const hex: int = 0xFF;
const binary: int = 0b1010;
const octal: int = 0o77;
const ratio: float = 0.75;
console.log(hex, binary, octal, ratio);
```

## Strings

Strings use double quotes, single quotes or backticks. Backticks allow `${}` interpolation:

```ts
const name: string = "Ada";
const level: int = 4;
console.log(`${name} reached level ${level}`);
console.log(name + " has " + level + " gems");
console.log(name.toUpperCase(), name.length);
```

`"a" + 1` is `"a1"`, as in TypeScript.

## Unions and null

A union lets a value be one of several types. Adding `null` makes a value optional:

```ts
function greet(name: string | null): string {
    if (name != null) {
        return "Hello, " + name;
    }
    return "Hello, stranger";
}

console.log(greet("Ada"));
console.log(greet(null));
```

Inside the `if`, the checker knows `name` is a `string`. That is called narrowing. It works with `!= null`, truthiness checks, `is`, `instanceof` and early returns.

`x != null` catches both `null` and `undefined`, and narrows both away from `string | null | undefined`; `x == null` matches both. Strict `x !== null` removes only `null`, and `x !== undefined` only `undefined`. The `?.` and `??` operators work as in TypeScript:

```ts
class Weapon {
    damage: int = 5;
}

class Hero {
    weapon: Weapon | null = null;
}

const hero: Hero = new Hero();
const damage: int = hero.weapon?.damage ?? 1;
console.log(damage);    // 1
```

Use postfix `!` when a value must exist but a guard is impractical. It narrows
the expression from `T | null | undefined` to `T`:

```ts
function findTitle(id: int): string | null {
    return id == 1 ? "Intro" : null;
}

const title: string = findTitle(1)!;
console.log(title); // Intro
```

This differs from TypeScript: ThicketScript checks `!` at run time. A null or
undefined value raises a `TypeError` at the assertion, and the message names the
expression (`non-null assertion failed for 'findTitle()': value is null`).

## Equality is strict

`==` and `===` mean the same thing. Neither converts types. `0 == ""` is `false`. The one exception is `null == undefined`, which is `true`, so `x != null` is the usual null check.

## Truthiness

`null`, `undefined`, `false`, `0` and `""` are falsy. Everything else is truthy, including empty arrays and empty objects.

## Type aliases and literal types

```ts
type Direction = "up" | "down" | "left" | "right";
type EntityId = int;

let facing: Direction = "up";
const id: EntityId = 42;
console.log(facing, id);
```

Aliases exist only for the checker. They produce no code.

## Arrays, tuples, maps and sets

```ts
const scores: Array<int> = [10, 20, 30];
scores.push(40);
console.log(scores.length, scores[0]);

const doubled: Array<int> = scores.map((s: int): int => s * 2);
console.log(doubled.join(", "));

const pair: [string, int] = ["level", 3];
console.log(pair[0], pair[1]);

const hp: Map<string, int> = new Map<string, int>();
hp.set("slime", 12);
hp.set("bat", 6);
console.log(hp.get("slime"), hp.has("bat"), hp.size);

// get answers `int | undefined`: a missing key is undefined.
const slime: int = hp.get("slime")!;       // ! : the key must exist
const dragon: int = hp.get("dragon") ?? 0; // ?? : a missing key is normal
console.log(slime, dragon);

for (const [name, value] of hp) {
    console.log(name, value);
}

const seen: Set<string> = new Set<string>();
seen.add("cave");
console.log(seen.has("cave"));
```

An array's element type is enforced. Pushing a `string` into an `Array<int>` is an error.

Arrays come with extras beyond the JavaScript set, such as `first()`, `last()`, `isEmpty()`, `unique()`, `shuffle()`, `sum()` and `avg()`.

## Checking a type at run time: `is`

`is` tests a value and narrows it:

```ts
function describe(value: int | string): string {
    if (value is int) {
        return "a number: " + value;
    }
    return "some text: " + value;
}

console.log(describe(5));
console.log(describe("hi"));
```

`is` works with the basic types, the built-in object types (`Array`, `Map`, `Set` and others), your classes and structs.

## Converting and casting: `as`

Between basic types, `as` **converts**:

```ts
const text: string = 42 as string;       // "42"
const whole: int = 3.9 as int;           // 3, truncates toward zero
const parsed: int = "120" as int;        // 120
console.log(text, whole, parsed);
```

A string that is not a number converts to `NaN`. Check it with `isNaN()`. When you would rather get an error, use `Int(text)`, which throws, or `tryInt(text)`, which returns `null`.

Between classes, `as` **asserts**. If the value is not that class, it throws a `TypeError` instead of carrying on with the wrong object. Use `is` first when you are not sure.

## Structs

A `struct` is a value type with a fixed memory layout. Struct fields can use compact storage types such as `uint8`, `int16` and `float32`:

```ts
struct Pixel {
    r: uint8;
    g: uint8;
    b: uint8;
    a: uint8;
}

const p: Pixel = Pixel{ r: 255, g: 128, b: 0, a: 255 };
const red: uint = p.r;
console.log(red);
```

Reading a packed field gives you an ordinary `uint`, `int` or `float`. Writing checks the range. Storing a wider value without `as` is a warning (PF072), but when every input already fits the field, as in `Pixel{ r: (a.r + b.r) / 2, ... }` or `Vec{ x: a.x + b.x }` with `float32` fields, there is no warning. A literal that cannot fit, such as `r: 300`, is a compile error. The compact types are only for struct fields and similar storage: variables, parameters and class fields use `int`, `uint` and `float`.

When `dump()` renders a struct, a `float32` field uses the shortest decimal
that round-trips at single precision. A field read on its own is an ordinary
`float`, so format that value explicitly when it needs a fixed display width.

---

URL: https://thicketscript.com/docs/language/variables

# Variables

## `let` and `const`

```ts
let score: int = 0;
const MAX_SCORE: int = 9999;

score = score + 10;
score += 5;
console.log(score, MAX_SCORE);
```

- **`let`** declares a variable you can reassign.
- **`const`** declares one you cannot. It must have a value.

Both are block-scoped: a variable declared inside `{ }` is not visible outside it.

```ts
let x: int = 10;
{
    let inner: int = 20;
    console.log(x + inner);    // 30
}
console.log(x);                // 10
```

`var` still parses, but it is deprecated and the checker warns. Use `let` or `const`.

## Always write the type

```ts
let name: string = "Ada";
let speed: float = 1.5;
let alive: boolean = true;
let inventory: Array<string> = [];
console.log(name, speed, alive, inventory.length);
```

Leaving the type off (`let name = "Ada";`) earns warning `PF071`. Inference exists, but explicit types are the house style and keep the intent clear.

## Several at once

```ts
let a: int = 1, b: int = 2, c: int = 3;
console.log(a + b + c);
```

## Compound assignment

```ts
let n: int = 10;
n += 5;     // 15
n -= 3;     // 12
n *= 2;     // 24
n /= 4;     // 6, integer division
n %= 4;     // 2
n **= 3;    // 8
console.log(n);
```

Only a variable, a property (`a.b`, `a[i]`) or, for plain `=`, a destructuring pattern can be assigned to. `f() = 3` or `(n + 1) = 2` is a compile error.

Bitwise forms work too: `<<=`, `>>=`, `&=`, `|=` and `^=`.

## Destructuring

Pull values out of an array or a tuple in one line:

```ts
const [first, second]: Array<int> = [1, 2];
console.log(first, second);
```

## Shadowing

Declaring a variable with the same name as one in an outer scope is allowed, but the checker warns. Names that start with `_` are exempt.

## Constants are inlined

A `const` set to a literal number, string or boolean is replaced by its value wherever it is used, so it costs nothing at run time. The same goes for `static const` on a class.

---

URL: https://thicketscript.com/docs/modules/

# Modules

ThicketScript comes with the pieces a game needs. They sit in layers, and you pick the ones you want:

| Module | What it is | How you get it |
|---|---|---|
| [willow](./willow) | The 2D display tree: sprites, text, tweens, cameras, particles, tilemaps. | Built into `thicket`. List `willow` in `systems`. |
| [willowui](./willowui) | UI widgets built on willow: buttons, lists, text input, windows, themes. | A package, written in ThicketScript. |
| [gamekit](./gamekit) | Game structure: entities, components, scenes, saves. | A package, written in ThicketScript. |

Under all of them is the engine core: windows, input, audio and rendering. You never import it directly.

## Systems and packages

The difference matters only in `thicket.json`. In your code, every import looks the same.

- A **system** is built into the `thicket` program. You list it in `systems`.
- A **package** is ThicketScript source from a folder, a git repository or a zip. You list it in `packages`. See [Packages](/docs/packages/).

```json5
{
    entry: "app.tks",
    systems: ["willow", "bitmap"],
    packages: { willowui: "../willowui-tks" },
    window: { title: "My Game" },
}
```

Leave `systems` out and the project can use every system the host has.

---

URL: https://thicketscript.com/docs/modules/gamekit

# gamekit

<SiteArt src="/art/module-gamekit.svg" alt="Three scene cards linked by a path, an entity crate with component gears, and a glowing save crystal" :width="1200" :height="360" caption="Illustration" eager />

gamekit gives a game its structure: entities and components, a world that runs your systems in phases, scenes, input actions, assets, saves and test helpers. It is a **package** written entirely in ThicketScript, with no native code. It needs willow, and pairs with [willowui](./willowui) for window games.

::: tip The gamekit portal
gamekit has its own documentation: a getting-started walkthrough, one guide per concept, recipes and a full reference.

**[Open the gamekit docs](/gamekit/)**
:::

## Add it to a project

```json5
{
    entry: "app.tks",
    systems: ["willow", "bitmap"],
    packages: { gamekit: "../gamekit-tks" },
}
```

You list the `willow` and `bitmap` systems yourself, because a package's systems are never inherited. A console project works too: willow runs without a window.

## The families

| Family | What it holds |
|---|---|
| `core` | Entities, component keys, events, attributes, state machines, effects, conditions and actions, definitions and prefabs, assets, 2D helpers. |
| `ecs` | A world, component stores, queries, phase schedules and a world ticker. |
| `app` | Scenes, the scene stack and coordinator, focus, and input actions. |
| `save` | Codecs, versioned schemas, save slots and settings. |
| `audio` | A music director over the core audio system. |
| `willow` | Presentation bindings and a pointer bridge on willow. |
| `ui` | Scene windows and screen windows through willowui. |
| `testing` | Deterministic clocks, debug snapshots, scenarios and traces. |

Start with [Getting started](/gamekit/getting-started.html).

---

URL: https://thicketscript.com/docs/modules/willow

# willow

<SiteArt src="/art/module-willow.svg" alt="A 2D game scene: tile ground, willow trees, a floating platform with coins, a jumping sprite and a small display-tree diagram" :width="1200" :height="360" caption="Illustration" eager />

willow is the 2D module, built into `thicket`. It is a **display tree**, in the spirit of Flash and Starling: you build a tree of nodes (sprites, text, shapes, tilemaps, particles), set their position, scale, rotation and colour, and willow draws the whole tree every frame. List it under `systems` in `thicket.json` and import from `"willow"`.

::: tip The willow docs
willow has its own documentation section: a getting-started walkthrough, a guide per topic, recipes, and a reference page for every class.

**[Open the willow docs](/willow/)**
:::

- [Getting started](/willow/getting-started.html): a window, a sprite, moving it with the keyboard.
- [The scene graph](/willow/guide/scene-graph.html): the tree, the world and screen roots, layers.
- [Reference](/willow/reference/): every willow class.
- [willowui](./willowui) adds widgets on top of willow.

---

URL: https://thicketscript.com/docs/modules/willowui

# willowui

<SiteArt src="/art/module-willowui.svg" alt="A wooden UI window with a list, a slider, a checkbox, a toggle, a text field and buttons" :width="1200" :height="360" caption="Illustration" eager />

willowui is the UI toolkit: buttons, labels, text input, lists, trees, tables, windows, menus, themes, reactive data binding and an XML template system. It is written entirely in ThicketScript on top of [willow](./willow.html), and it comes as a **package**, not a built-in system.

**[Open the willowui documentation](/willowui/)**: getting started, layout, the XML template system in depth, and a reference for every widget.

## Add it to a project

```json5
{
    entry: "app.tks",
    systems: ["willow", "bitmap"],
    packages: { willowui: "../willowui-tks" },
    window: { title: "My UI", width: 800, height: 600 },
}
```

The key, `willowui`, is the name you import from: `import { Button, Screen, DEFAULT_STAGE } from "willowui";`.

## Authoring tools

willowui offers `themec` (compile a theme) and `xmluic` (compile an XML template to its binary form). A project that lists willowui runs them with `thicket tool themec` and `thicket tool xmluic`.

---

URL: https://thicketscript.com/docs/packages/

# Using packages

A package is ThicketScript source from somewhere else: another folder, a git repository or a zip. You list it under `packages` in `thicket.json` and import it by name. Packages are **source only**: nothing runs when one is fetched, and no package contains native code.

```json5
{
    entry: "app.tks",
    packages: {
        willowui: "../willowui-tks",                              // a folder next to this project
        shared: "https://github.com/example/shared-tks#v1.2.0",   // a git repo at a tag
        icons: "https://example.com/icons.zip",                   // a zip
        mathx: "mathx",                                           // thicket_packages/mathx/
        oldlib: false,                                            // switched off
    },
}
```

```ts
import { Button } from "willowui/src/core/button";
import { lerp } from "mathx/easing";
```

The key is the import name. `"name"` loads the package's entry file. `"name/sub/path"` loads another file inside it.

## One string per package

The shape of the string says where the package comes from:

| You write | It is |
|---|---|
| `./`, `../`, `/`, `~/` or a drive letter | A folder, used in place. |
| `https://`, `http://`, `ssh://` or `git@host:` | A git repository. Add `#tag`, `#branch` or `#commit` to pin it. |
| Anything ending in `.zip` | A zip archive, local or downloaded. |
| A plain name | A folder called `thicket_packages/<name>/`. |
| `false`, `null`, `""`, `"no"`, `"false"` or `"none"` | Switched off. |

## Where a plain name is found

The first folder that exists wins:

1. `thicket_packages/<name>/` next to your `thicket.json`.
2. `thicket_packages/<name>/` in each parent folder, up to the drive root. Handy for a workspace of projects that share packages.
3. Your per-user folder: `~/.local/share/thicket/thicket_packages/` on Linux, `~/Library/Application Support/thicket/thicket_packages/` on macOS, `%APPDATA%\thicket\thicket_packages\` on Windows.

There is no install command yet. To use a plain name, copy or link the folder into `thicket_packages/` yourself.

## One flat folder

Every package, including the packages your packages use, is resolved once, by name, for the whole program.

- Git and zip packages are fetched into your project's `thicket_packages/`, side by side, never nested.
- Two different sources for the same name anywhere in the program is an error that names both.
- Packages that list each other are fine.

## Git and zip packages

- Fetched once and reused. After the first fetch, runs and checks work offline.
- Fetched again only when the string changes, or when you delete the package's entry in `thicket.lock`.
- Git uses the `git` on your `PATH` with your own credentials.
- Zips are checked for unsafe entries before anything is written.
- `thicket check` fetches what is missing. The editor never fetches.

## thicket.lock

`thicket.lock` sits next to `thicket.json` and records what each string resolved to: the git commit, the zip's hash, or a folder and its content hash. **Commit it**, and gitignore `thicket_packages/`. The `.gitignore` that `thicket new` writes already does.

When something no longer matches the lock, the error names the package and the fix: delete that entry in `thicket.lock` to accept the change.

## You import only what you list

If a package you use depends on `dep`, you cannot import `dep` yourself until you add it to your own `packages`.

## You grant what packages need

A package's `permissions` and `systems` say what it needs. Only the project you run grants anything. If willowui needs `fs`, your project turns on `fs`. If it lists `willow`, your project lists `willow` too, or leaves `systems` out entirely. Every unmet need is reported at once:

```text
willowui needs fs; add it to permissions
```

## Names you cannot use

Package keys cannot be the name of a system or core module (`willow`, `fs`, `http` and so on), or `system`, `engine`, `thicket`, `thicketscript`, `tks` or `heartwood`. They cannot be empty, start with `.`, or contain `/`, `\`, `:` or spaces.

Next: [writing a package](./writing).

---

URL: https://thicketscript.com/docs/packages/writing

# Writing a package

A package is just a project whose `entry` gets imported instead of run. There is no special format and no `name` field: the project that uses it picks the import name.

## The layout

```text
mathx/
  thicket.json
  src/
    index.tks
    easing.tks
```

```json5
// mathx/thicket.json
{
    entry: "src/index.tks",
}
```

```ts
// mathx/src/index.tks
export function lerp(a: float, b: float, t: float): float {
    return a + (b - a) * t;
}

export function clamp01(t: float): float {
    if (t < 0) {
        return 0;
    }
    if (t > 1) {
        return 1;
    }
    return t;
}
```

Importing the package loads the entry's exports. It never calls `main`. A consumer reaches other files by path, relative to the package root: `import { easeIn } from "mathx/src/easing";`.

A package cannot import anything outside its own folder.

## Using it

```ts
// game/app.tks, with packages: { mathx: "../mathx" }
import { clamp01, lerp } from "mathx";

console.log(lerp(0, 10, clamp01(0.25)));
```

## Tests are a sub-project

Put the tests in a folder with its own `thicket.json` that lists the package by a relative path. They import it exactly as a real consumer would:

```json5
// mathx/tests/thicket.json
{ entry: "all.tks", packages: { mathx: ".." } }
```

There is no `thicket test` command yet. Run the tests with `thicket run`.

## Declare what you need

List what the package uses. These are requirements, not grants:

```json5
{
    entry: "src/index.tks",
    systems: ["willow"],
    permissions: { fs: true },
}
```

A project that uses your package has to list the same systems and turn on the same permissions. It gets a clear error naming the fix if it does not.

A package whose code uses `engine` makes its consumer a window app. Code that only needs the scene can read `Scene.main` instead, which is `null` in a console program and imposes no window.

## Reach your own files with `moduleDir`

A relative path given to `fs` resolves against the working directory, which is the game's folder, not yours. To load your own fonts, images or data, build the path from `moduleDir`, the folder the current source file lives in:

```ts
import { Files } from "fs";

export async function loadTheme(): Promise<string> {
    return await Files.readText(Files.join(moduleDir, "theme.json"));
}
```

`moduleDir` needs no import. It is right for a local folder, a package in `thicket_packages/` and a built program alike. Reading through it is an ordinary file read, so the package declares `fs` and the consuming project grants it.

In a built program, a consumer ships your files by listing them as `"<package>:<path>"` in its `assets`.

## Offer tools

A package can offer script tools to the projects that use it. Map a tool name to a script in `tools`:

```json5
{
    entry: "src/index.tks",
    tools: { themec: "tools/themec.tks" },
}
```

A project that lists the package runs it with `thicket tool themec`, and `thicket tool` lists every tool available.

## Share it

Publish the folder as a git repository and tag a version. Users add it with a URL pinned to that tag, like `"https://github.com/you/mathx-tks#v1.0.0"`. There is no package registry.

---

URL: https://thicketscript.com/docs/build/

# Building for each platform

`thicket build` packages a project as a standalone program: a prebuilt runtime, your compiled bytecode (`bundle.tbc`) and the assets you list. New to building? Start with [Building a program](/docs/start/build-executable).

```sh
thicket build [<project-dir>] [--out <dir>] [--strategy <name>] [--force] [--release]
```

## Console apps and window apps

What you get depends on the project:

- A project **without** a `window` section is a **console app**. It gets the smallest console runtime that has every system it lists.
- A project **with** a `window` section is a **window app**. It gets the window runtime: willow, the frame loop, input, audio and rendering, linked into one executable.

A console app can still list `willow`. It gets the console runtime plus willow, which runs the node tree, tweens and hit tests with no window, display or GPU. That is useful for servers and tools.

## Strategies

A strategy decides the shape of the output. With no `--strategy`, a console app uses `headless` (or `headless-willow` when it lists willow) and a window app uses `linux-portable` on Linux.

| Strategy | Platform | What it makes |
|---|---|---|
| `headless` | host | A console app: the console runtime beside `bundle.tbc`. |
| `headless-willow` | Linux | A console app that lists willow. |
| `linux-portable` | Linux | A window app as one flat folder with `assets/` beside it. |
| `linux-appdir` | Linux | A window app as an `.AppDir` with `AppRun`, a desktop entry and an icon. Needs `build.icon`. |
| `linux-appimage` | Linux | An AppDir wrapped as an `.AppImage`. Needs `appimagetool` on your `PATH`. |
| `windows-portable` | Windows | A Windows folder made from the `windows-x86_64` runtime. |
| `macos-app` | macOS | A macOS `.app` made from the `macos-arm64` runtime. Any `build.icon` must be an `.icns` file. |

`thicket build --list-strategies` shows the strategies that fit your project and whether each one is ready.

A strategy refuses a project it does not fit, before anything is written, and names the one that does.

## Building for another platform

`thicket` looks for each platform's runtime in a `runtimes/` folder beside itself: `linux-x86_64/`, `windows-x86_64/` and `macos-arm64/`. If a runtime folder is missing, build on that platform, or copy its runtime folder next to `thicket`. A build never relabels one platform's runtime as another's.

## What a built window app needs

The folder is self-contained except for the operating system. On Linux the program needs only the C library and the window-system and graphics libraries the desktop already has. Nothing is installed beside the folder. The player needs a desktop session and a working GPU driver, plus an audio device for sound.

## What each runtime includes

| | Console runtime | Window runtime |
|---|---|---|
| The language and standard library | yes | yes |
| `audio` | | yes |
| `database` | SQLite and server drivers | SQLite only |
| `http`, `net`, `ws` | yes | no |
| `shell`, `terminal`, package fetching | no | no |
| willow | with `headless-willow` | yes |

In a built window app, an uncaught error goes to `crash.log` beside the program and a native dialog.

## Assets

Only what `assets` in `thicket.json` lists ships. Entries are paths or globs (`*`, `**`, `?`, `{a,b}`) relative to the project, or `<package>:<path>` for a file inside a package. A glob that matches nothing is a build error.

```json5
assets: [
    "assets/**",
    "willowui:assets/fonts/go-{regular,bold}.ttf",
]
```

A plain list **embeds** the files inside `bundle.tbc`. The object form mixes three kinds:

| Kind | What happens |
|---|---|
| `embed` | Stored inside `bundle.tbc` and read only when opened. Read-only. |
| `pack` | Stored in one encrypted `app.pak` beside the program. A deterrent against casual browsing, not real secrecy: the key ships with the app. |
| `copy` | Copied beside the program as plain files. |

```json5
assets: {
    embed: ["assets/**"],
    copy: ["data/save.db"],
}
```

Your code reads every file the same way. A read looks in the embedded files first, then the pack, then the disk, at the same project-relative path. SQLite databases must be listed under `copy`, because the app writes to them.

## Version and icon

The `build` section of `thicket.json` holds `version`, `icon` and the per-platform settings under `linux`, `windows` and `macos`. On Windows, `build.windows.console: true` makes a console-subsystem program instead of a GUI one.

## Bytecode only

`thicket compile` is the smaller step. It writes a `.tbc` bundle and nothing else, which `thicket run app.tbc` can run.

```sh
thicket compile app.tks -o app.tbc
```

## Coming next

These are on the way. <small>Plans can change.</small>

- **Single-file programs**: the bundle appended to the runtime, so a game is one file.
- **Web builds**: a WebAssembly runtime that runs a bundle in the browser.

---

URL: https://thicketscript.com/docs/ai/

# Using ThicketScript with AI agents

AI coding agents write better ThicketScript when they can check their work against the real compiler. ThicketScript gives them two ways in:

- **`thicket mcp`**, a [Model Context Protocol](https://modelcontextprotocol.io) server built into the `thicket` program. It answers diagnostics, module APIs and symbol lookups for the exact version you have installed.
- **[`/llms.txt`](/llms.txt)** and **[`/llms-full.txt`](/llms-full.txt)**, plain-text copies of these docs for agents that read the web.

::: info Downloads are coming soon
Once you have `thicket`, everything on this page works with no extra install. There is no hosted server and no account.
:::

## Start the server

`thicket mcp` talks MCP over stdio: JSON-RPC 2.0, one JSON object per line. Stdout carries only protocol messages; warnings go to stderr. Your agent starts it for you, so you rarely run it by hand.

**Start it in your project directory.** On startup it loads the project's own types from `thicket.json` in the current directory, and workspace symbol search scans the `.tks` files under it. It skips `.git`, `build`, `node_modules` and `.tks-cache`, stops after 5,000 files, and never writes a cache into your source tree.

## Connect your agent

Any MCP client that can launch a stdio server needs only this:

```json
{ "command": "thicket", "args": ["mcp"] }
```

### Claude Code

Run this in your project directory:

```sh
claude mcp add thicket -- thicket mcp
```

### Cursor and other editors

Editors that read an `mcpServers` block (Cursor's `.cursor/mcp.json`, for example) take:

```json
{
  "mcpServers": {
    "thicket": {
      "command": "thicket",
      "args": ["mcp"]
    }
  }
}
```

If `thicket` is not on your `PATH`, use its full path as `command`.

## Tools

Paths can be absolute or relative to the directory the server started in. Line and column numbers are **1-based**, in both arguments and results, which print locations as `path:line:column`.

- **`get_diagnostics`** (optional `path`): Runs `thicket check` on the file, or on the project when `path` is left out, and returns its output and exit status.
- **`list_modules`** (no arguments): The built-in and host declaration modules, the same list as `thicket types list`.
- **`get_module_api`** (`module`): A module's full declaration file with its doc comments, the same as `thicket types print <module>`.
- **`get_symbol`** (`path`, `line`, `column`): Hover text for the symbol at that position, plus where it is defined.
- **`get_references`** (`path`, `line`, `column`): Every reference to the symbol at that position, including its declaration.
- **`get_document_symbols`** (`path`): The outline of one file: its classes, structs, functions, methods and so on, with positions.
- **`find_symbols`** (`query`): Symbols across the project whose names match `query`.

The answers come from the same language server that powers the IDE plugin, so an agent sees the same hovers, definitions and errors you do.

## A good loop for agents

1. Call `list_modules`, then `get_module_api` for the modules the task touches, before writing code against them.
2. Write the code.
3. Call `get_diagnostics` and fix what it reports. Repeat until it is clean.
4. Use `get_symbol` and `get_references` before renaming or changing a signature.

You can give your agent that loop in its instructions file (for example `CLAUDE.md` or `AGENTS.md`) along with a link to this page.

## llms.txt

[`https://thicketscript.com/llms.txt`](/llms.txt) follows the [llms.txt](https://llmstxt.org) format: a short summary of ThicketScript and a link to every docs page. [`https://thicketscript.com/llms-full.txt`](/llms-full.txt) is the full text of the docs in one file, for agents that want it all in context at once.

The [API reference](/docs/api/) is generated from the same declaration files `get_module_api` prints. For the version you have installed, prefer the MCP server; it is never out of date.

---

URL: https://thicketscript.com/docs/api/

# API reference

Every built-in class, function and module, generated from the declaration files that ship with ThicketScript. The same files power hover, completion and go-to-definition in the IDE plugin and in `thicket mcp`.

## Always available

In scope in every file. No import needed.

- [Global functions](./globals): Output, timers, parsers, type checks and the global constants.
- [console](./console): Leveled logging to stdout and stderr.
- [String](./string): The string type and its methods.
- [Number conversions](./numerics): Conversion functions and constants for numbers: `Int(x)`, `Float(x)`, `Int.MAX`, `Number.isInteger` and friends. The types themselves are lowercase: `int`, `uint`, `float`, and `int8` to `float32` for packed storage.
- [Number methods](./primitives): Methods you can call on a number value, such as `n.toFixed(2)`. The class names on this page are internal; you never write them in code.
- [Math](./math): Math functions and constants.
- [Random](./random): Seedable random number generators.
- [Array, Map and Set](./collections): The collection types: `Array`, `FixedArray`, `Map`, `Set` and the weak references.
- [Buffers and typed arrays](./buffer): `ByteArray`, `Buffer`, the typed arrays and their encodings.
- [Promise](./async): Async results for `async` / `await`.
- [Errors](./errors): The built-in error classes.
- [JSON](./json): Parse and stringify JSON.
- [Object](./object): `Object` helpers and `Proxy`.
- [RegExp](./regexp): Regular expressions.
- [URL](./url): Parse and build URLs and query strings.
- [App and System](./system): The app lifecycle (`App`), process and platform info (`System`), and autotest hooks.
- [Input constants](./input): `Key`, `GamepadButton`, `GamepadAxis` and `MouseCursor`.
- [InputMap](./inputmap): Named actions bound to keys, buttons and axes.
- [Color](./color): The `Color` value type: construct, convert and adjust colors.
- [Geometry](./geometry): The `Vec2`, `Point`, `Vec3`, `Size` and `Rect` value types.
- [Date and Duration](./date): Dates, times, time zones and durations.
- [Ease](./ease): Easing curves for animation and tweens.
- [Ticker](./ticker): Timers and sequences that advance with the app tick.
- [BitmapRect](./bitmaprect): The rectangle `Bitmap.contentBounds` returns.

## Modules

Import what you use, for example `import { Files } from "fs";`. Some modules also need a permission in `thicket.json`; each page says so where it applies.

- [audio](./audio): Sound playback, mixing, music, procedural sound effects and 3D spatial sound.
- [bitmap](./bitmap): Bitmaps: load, draw, composite and save images.
- [compress](./compress): zlib and gzip deflate and inflate, with streaming helpers.
- [crypto](./crypto): Hashing, HMAC, AES, PBKDF2, random bytes and UUIDs.
- [database](./database): Database connections: SQLite, MySQL, PostgreSQL, Redis and MongoDB.
- [env](./env): Environment variables.
- [events](./events): String-keyed event channels with `EventEmitter`.
- [fs](./fs): Files and directories.
- [http](./http): Asynchronous HTTP client and an HTTP server.
- [net](./net): TCP sockets.
- [reactivity](./reactivity): Signals, refs, computed values and reactive collections.
- [shell](./shell): Run child processes.
- [terminal](./terminal): Terminal input, output, cursor control and ANSI styling.
- [udp](./udp): UDP datagram sockets.
- [ws](./ws): WebSocket client and server.

---

URL: https://thicketscript.com/docs/api/async

# Promise

Async results for `async` / `await`.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Promise <Badge type="info" text="class" />

```ts
class Promise<T>
```

*Final: it cannot be subclassed.*

Async result of a deferred computation. State is one of pending,
fulfilled, or rejected; transitions are one-way. Handler chains run
via the microtask queue.

### Promise.then

```ts
then(onFulfilled?: Function, onRejected?: Function): Promise<any>
```

Attach fulfillment and rejection handlers. Returns a new promise
that resolves to the handler's return value (or rejects with a
thrown value). Either handler may be omitted to pass the
settlement through unchanged.

### Promise.catch

```ts
catch(onRejected?: Function): Promise<any>
```

Shorthand for `then(undefined, onRejected)`.

### Promise.finally

```ts
finally(onFinally?: Function): Promise<T>
```

Run `onFinally` after the promise settles, regardless of
outcome. The returned promise mirrors the receiver's state;
`onFinally` cannot observe or alter the resolution value.

### Promise.all

```ts
static all(iterable: Array<any>): Promise<Array<any>>
```

Resolve when every input settles fulfilled, or reject on the
first rejection. Inputs may be promises or plain values; plain
values are wrapped via `Promise.resolve`. Resolves with an array
of fulfilled values in input order.

### Promise.allSettled

```ts
static allSettled(iterable: Array<any>): Promise<Array<SettledResult>>
```

Resolve when every input settles, regardless of outcome.
Resolves with an array of `SettledResult` records in input
order.

### Promise.any

```ts
static any(iterable: Array<any>): Promise<any>
```

Resolve on the first input to fulfil, or reject when every
input has rejected. The aggregate rejection is reported as an
AggregateError-shaped string today; the typed
AggregateError class is registered separately.

### Promise.race

```ts
static race(iterable: Array<any>): Promise<any>
```

Resolve or reject as soon as any input settles, mirroring its
outcome. Subsequent settlements are ignored.

### Promise.reject

```ts
static reject(reason?: any): Promise<any>
```

Return a promise rejected with `reason`. Already-rejected
promises pass through unchanged.

### Promise.resolve

```ts
static resolve(value: Promise<any>): Promise<any>
static resolve<T>(value?: T): Promise<T>
```

Return a promise fulfilled with `value`. Already-fulfilled
promises pass through unchanged.

Two signatures, because the result's type argument is the
ARGUMENT's type and a promise argument is flattened rather than
nested. The promise overload is declared first so it wins for a
promise argument; `T` binds from anything else.

**Example**

```ts
const value: string = await Promise.resolve("ready");
console.log(value); // ready
```

## SettledResult <Badge type="info" text="class" />

```ts
class SettledResult
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Per-entry record produced by `Promise.allSettled`. `status` is
`"fulfilled"` or `"rejected"`. Fulfilled records carry `value`;
rejected records carry `reason`. The other field is absent.

```ts
readonly status: string
readonly value?: any
readonly reason?: any
```

---

*Generated from `lang/types/builtin_async.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/audio

# audio

Sound playback, mixing, music, procedural sound effects and 3D spatial sound.

::: tip Import
```ts
import { SfxPreset, Wave, Sfx, SoundGroup, ... } from "audio";
```

Needs the `"audio"` permission in `thicket.json`.
:::

## SoundPlayOptions <Badge type="info" text="class" />

```ts
class SoundPlayOptions
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Playback options for a SoundChannel.

### SoundPlayOptions.volume

```ts
volume?: float64
```

Volume; 0 is silent, 1 is normal.

### SoundPlayOptions.pitch

```ts
pitch?: float64
```

Speed multiplier; 1.0 is normal speed.

### SoundPlayOptions.pan

```ts
pan?: float64
```

Stereo pan; -1 is left, 0 is center, 1 is right.

### SoundPlayOptions.loop

```ts
loop?: boolean
```

Whether playback repeats when it reaches the end.

### SoundPlayOptions.group

```ts
group?: int
```

Sound group identifier; see `SoundGroup` constants.

## SoundChannel <Badge type="info" text="class" />

```ts
class SoundChannel
```

*Type only: the runtime hands you instances; you never construct it yourself.*

### SoundChannel.volume

```ts
volume: float64
```

Playback volume; 0 is silent, 1 is normal.

### SoundChannel.pitch

```ts
pitch: float64
```

Playback speed multiplier; 1.0 is normal speed.

### SoundChannel.pan

```ts
pan: float64
```

Stereo pan; -1 is left, 0 is center, 1 is right.

### SoundChannel.spatialized

```ts
spatialized: boolean
```

Whether this sound uses 3D spatial positioning.

### SoundChannel.position

```ts
position: Vec3 | float64
```

3D position in world space or 2D distance fallback.

### SoundChannel.velocity

```ts
velocity: Vec3
```

3D velocity in world space for Doppler effect.

### SoundChannel.minDistance

```ts
minDistance: float64
```

Closest distance for spatial attenuation falloff in world units.

### SoundChannel.maxDistance

```ts
maxDistance: float64
```

Farthest distance for spatial attenuation falloff in world units.

### SoundChannel.rolloff

```ts
rolloff: float64
```

Exponent for distance attenuation curve; typically 0.0–2.0.

### SoundChannel.attenuation

```ts
attenuation: int
```

Spatial attenuation model; see `Attenuation` constants.

### SoundChannel.position2D

```ts
position2D: float64
```

2D stereo pan when spatialized is false; -1 to 1.

### SoundChannel.isPlaying

```ts
readonly isPlaying: boolean
```

True if the sound is currently playing. Read-only.

### SoundChannel.playbackPosition

```ts
readonly playbackPosition: float64
```

The voice's live decoder cursor in seconds. Zero after it ends or is stolen.

### SoundChannel.stop

```ts
stop(): void
```

Stops playback immediately.

### SoundChannel.pause

```ts
pause(): void
```

Pauses playback; call `resume()` to continue.

### SoundChannel.resume

```ts
resume(): void
```

Resumes playback after `pause()`.

### SoundChannel.onComplete

```ts
onComplete(callback: () => void): void
```

Runs once on the main thread in the frame after natural playback completion.

## Sound <Badge type="info" text="class" />

```ts
class Sound
```

*Type only: the runtime hands you instances; you never construct it yourself.*

### Sound.duration

```ts
readonly duration: float64
```

The decoded source length in seconds.

### Sound.play

```ts
play(options?: SoundPlayOptions): SoundChannel
```

Begins playback and returns a SoundChannel for real-time control.

### Sound.unload

```ts
unload(): void
```

Frees decoded audio and invalidates all SoundChannels from this sound.

## MusicTrack <Badge type="info" text="class" />

```ts
class MusicTrack
```

*Type only: the runtime hands you instances; you never construct it yourself.*

A streamed music asset returned by Audio.loadMusic(path).

### MusicTrack.unload

```ts
unload(): void
```

Stops playback and frees resources.

## SfxPreset <Badge type="info" text="static class" />

```ts
static class SfxPreset
```

Named procedural sound-effect recipes.

```ts
static readonly COIN: int
static readonly LASER: int
static readonly EXPLOSION: int
static readonly POWERUP: int
static readonly HIT: int
static readonly JUMP: int
static readonly BLIP: int
static readonly RANDOM: int
```

## Wave <Badge type="info" text="static class" />

```ts
static class Wave
```

Oscillator wave shapes for Sfx.tone.

```ts
static readonly SINE: int
static readonly SQUARE: int
static readonly TRIANGLE: int
static readonly SAWTOOTH: int
static readonly NOISE: int
```

## Sfx <Badge type="info" text="static class" />

```ts
static class Sfx
```

Static procedural sound-effect synthesizer.

### Sfx.generate

```ts
static generate(preset: int, seed?: int): Sound
```

Generate a reusable Sound asset from a named preset and optional deterministic seed.

**Parameters**

- `preset`: A SfxPreset constant.
- `seed`: Optional deterministic seed; omitted or 0 for random variation.

**Returns:** A new Sound asset that can be played multiple times.

### Sfx.play

```ts
static play(preset: int, seed?: int): void
```

Play a preset immediately as a one-shot effect.

**Parameters**

- `preset`: A SfxPreset constant.
- `seed`: Optional deterministic seed; omitted or 0 for random variation.

### Sfx.tone

```ts
static tone(frequency: float64, durationMs: int, wave?: int): void
```

Play an oscillator tone for the given duration.

**Parameters**

- `frequency`: Frequency in Hz.
- `durationMs`: Duration in milliseconds.
- `wave`: Optional Wave constant; defaults to SINE.

## AudioListener <Badge type="info" text="class" />

```ts
class AudioListener
```

*Type only: the runtime hands you instances; you never construct it yourself.*

```ts
position: Vec3
direction: Vec3
```

## SoundGroup <Badge type="info" text="static class" />

```ts
static class SoundGroup
```

Top-level sound mix-group constants.

### SoundGroup.Music

```ts
static readonly Music: int
```

::: warning Deprecated
Use `MUSIC`.
:::

### SoundGroup.Voice

```ts
static readonly Voice: int
```

::: warning Deprecated
Use `VOICE`.
:::

### SoundGroup.Ambient

```ts
static readonly Ambient: int
```

::: warning Deprecated
Use `AMBIENT`.
:::

### Other members of SoundGroup

```ts
static readonly SFX: int
static readonly MUSIC: int
static readonly VOICE: int
static readonly AMBIENT: int
static readonly UI: int
```

## Attenuation <Badge type="info" text="static class" />

```ts
static class Attenuation
```

Top-level spatial attenuation constants.

### Attenuation.None

```ts
static readonly None: int
```

::: warning Deprecated
Use `NONE`.
:::

### Attenuation.InverseDistance

```ts
static readonly InverseDistance: int
```

::: warning Deprecated
Use `INVERSE`.
:::

### Attenuation.LinearDistance

```ts
static readonly LinearDistance: int
```

::: warning Deprecated
Use `LINEAR`.
:::

### Attenuation.ExponentialDistance

```ts
static readonly ExponentialDistance: int
```

::: warning Deprecated
Use `EXPONENTIAL`.
:::

### Other members of Attenuation

```ts
static readonly NONE: int
static readonly INVERSE: int
static readonly LINEAR: int
static readonly EXPONENTIAL: int
```

## Audio <Badge type="info" text="static class" />

```ts
static class Audio
```

### Audio.SoundGroup

```ts
static readonly SoundGroup: any
```

::: warning Deprecated
Use top-level `SoundGroup`.
:::

### Audio.AttenuationModel

```ts
static readonly AttenuationModel: any
```

::: warning Deprecated
Use top-level `Attenuation`.
:::

### Audio.loadSound

```ts
static loadSound(path: string, group?: int): Promise<Sound>
static loadSound(buffer: Buffer, group?: int): Promise<Sound>
```

Loads a sound asset from a project or bundled path.

**Parameters**

- `path`: Project or bundled asset path.
- `group`: Optional sound group; see `SoundGroup` constants.

**Returns:** Promise that resolves to a loaded Sound.

**Example**

```ts
import { Audio, Sound } from "audio";
const click: Sound = await Audio.loadSound("assets/click.wav");
Audio.play(click);
```

### Audio.play

```ts
static play(sound: Sound | int, options?: SoundPlayOptions | float64, pitch?: float64, loop?: boolean): SoundChannel | void
```

Begins playback of a sound or sound channel.

**Parameters**

- `sound`: Sound object or numeric handle.
- `options`: Optional SoundPlayOptions or volume (float64).
- `pitch`: Optional speed multiplier.
- `loop`: Optional boolean for looping playback.

**Returns:** SoundChannel if sound is a Sound object, void if a handle.

### Audio.unloadSound

```ts
static unloadSound(sound: Sound | int): void
```

Stops playback and frees resources for the given sound.

**Parameters**

- `sound`: Sound object or numeric handle.

### Audio.stop

```ts
static stop(sound: Sound | int): void
```

Stops playback of a sound or sound channel.

**Parameters**

- `sound`: Sound object or numeric handle.

### Audio.setSoundVolume

```ts
static setSoundVolume(sound: Sound | int, volume: float64): void
```

Sets the volume of a sound or sound channel.

**Parameters**

- `sound`: Sound object or numeric handle.
- `volume`: Volume; 0 is silent, 1 is normal.

### Audio.soundVolume

```ts
static soundVolume(sound: Sound | int): float64
```

Reads the current volume of a sound or sound channel.

**Parameters**

- `sound`: Sound object or numeric handle.

**Returns:** Current volume in range 0..1.

### Audio.setSoundPitch

```ts
static setSoundPitch(sound: Sound | int, pitch: float64): void
```

Sets the pitch (speed) of a sound or sound channel.

**Parameters**

- `sound`: Sound object or numeric handle.
- `pitch`: Speed multiplier; 1.0 is normal speed.

### Audio.soundPitch

```ts
static soundPitch(sound: Sound | int): float64
```

Reads the current pitch of a sound or sound channel.

**Parameters**

- `sound`: Sound object or numeric handle.

**Returns:** Current pitch multiplier.

### Audio.setSoundPan

```ts
static setSoundPan(sound: Sound | int, pan: float64): void
```

Sets the pan (left/right balance) of a sound or sound channel.

**Parameters**

- `sound`: Sound object or numeric handle.
- `pan`: Stereo pan; -1 is left, 0 is center, 1 is right.

### Audio.soundPan

```ts
static soundPan(sound: Sound | int): float64
```

Reads the current pan of a sound or sound channel.

**Parameters**

- `sound`: Sound object or numeric handle.

**Returns:** Current pan in range -1..1.

### Audio.playPanned

```ts
static playPanned(sound: Sound | int, pan: float64, volume?: float64, pitch?: float64, loop?: boolean): void
```

Plays a sound with a specific pan and volume.

**Parameters**

- `sound`: Sound object or numeric handle.
- `pan`: Stereo pan; -1 is left, 0 is center, 1 is right.
- `volume`: Optional volume; 0 is silent, 1 is normal.
- `pitch`: Optional speed multiplier.
- `loop`: Optional boolean for looping playback.

### Audio.loadMusic

```ts
static loadMusic(path: string): Promise<MusicTrack>
```

Streams a music asset from a project or bundled path.

**Parameters**

- `path`: Project or bundled asset path.

**Returns:** Promise that resolves to a loaded MusicTrack.

### Audio.unloadMusic

```ts
static unloadMusic(track: MusicTrack | int): void
```

Stops playback and frees resources for the given music track.

**Parameters**

- `track`: MusicTrack object or numeric handle.

### Audio.playMusicHandle

```ts
static playMusicHandle(track: MusicTrack, volume?: float64, loop?: boolean, startSeconds?: float64): void
static playMusicHandle(id: int, volume?: float64, loop?: boolean, startSeconds?: float64): void
```

Begins playback of a music track.

**Parameters**

- `track`: MusicTrack object to play.
- `volume`: Optional volume; 0 is silent, 1 is normal.
- `loop`: Optional boolean for looping playback.
- `startSeconds`: Optional start point in seconds (default 0), e.g. a saved `musicPosition()`.

**Example**

```ts
import { Audio, MusicTrack } from "audio";
const theme: MusicTrack = await Audio.loadMusic("assets/theme.ogg");
Audio.playMusicHandle(theme, 0.8, true);
```

### Audio.crossfadeTo

```ts
static crossfadeTo(track: MusicTrack, durationMs: int, volume?: float64, loop?: boolean): void
static crossfadeTo(id: int, durationMs: int, volume?: float64, loop?: boolean): void
```

Crossfades to a new music track over a specified duration.

**Parameters**

- `track`: MusicTrack object to crossfade to.
- `durationMs`: Crossfade duration in milliseconds.
- `volume`: Optional target volume; 0 is silent, 1 is normal.
- `loop`: Optional boolean for looping playback.

### Audio.stopMusic

```ts
static stopMusic(fadeMs?: int): void
```

Stops music playback with optional fade-out.

**Parameters**

- `fadeMs`: Optional fade-out duration in milliseconds.

### Audio.pauseMusic

```ts
static pauseMusic(): void
```

Pauses music playback.

### Audio.resumeMusic

```ts
static resumeMusic(): void
```

Resumes music playback after `pauseMusic()`.

### Audio.musicPlaying

```ts
static musicPlaying(): boolean
```

Returns true if music is currently playing.

### Audio.activeMusic

```ts
static activeMusic(): int
```

Returns the numeric handle of the currently playing track, or 0 if none.

### Audio.musicPosition

```ts
static musicPosition(): float64
```

Playback position of the active music track in seconds (playing or paused), or 0 if none.

### Audio.masterVolume

```ts
static masterVolume: float64
```

Master mixer gain, clamped to 0..1.

### Audio.sfxVolume

```ts
static sfxVolume: float64
```

Sound-effects mix-group gain, clamped to 0..1.

### Audio.musicVolume

```ts
static musicVolume: float64
```

Music mix-group gain, clamped to 0..1.

### Audio.listener

```ts
static readonly listener: AudioListener
```

The 3D listener's position and orientation for spatial audio. Read-only.

### Audio.setMasterVolume

```ts
static setMasterVolume(volume: float64): void
```

::: warning Deprecated
Assign masterVolume.
:::

### Audio.setSfxVolume

```ts
static setSfxVolume(volume: float64): void
```

::: warning Deprecated
Assign sfxVolume.
:::

### Audio.setMusicVolume

```ts
static setMusicVolume(volume: float64): void
```

::: warning Deprecated
Assign musicVolume.
:::

### Audio.setGroupVolume

```ts
static setGroupVolume(group: int, volume: float64): void
```

Sets the volume for a sound group.

**Parameters**

- `group`: A SoundGroup constant.
- `volume`: Volume; 0 is silent, 1 is normal.

### Audio.groupVolume

```ts
static groupVolume(group: int): float64
```

Reads the volume for a sound group.

**Parameters**

- `group`: A SoundGroup constant.

**Returns:** Current volume in range 0..1.

### Audio.setListenerPosition

```ts
static setListenerPosition(x: float64, y: float64, z: float64): void
```

Sets the 3D listener position for spatial audio.

**Parameters**

- `x`: World x coordinate.
- `y`: World y coordinate.
- `z`: World z coordinate.

### Audio.setListenerDirection

```ts
static setListenerDirection(fx: float64, fy: float64, fz: float64, ux?: float64, uy?: float64, uz?: float64): void
```

Sets the 3D listener orientation for spatial audio.

**Parameters**

- `fx`: Forward vector x component.
- `fy`: Forward vector y component.
- `fz`: Forward vector z component.
- `ux`: Optional up vector x; defaults to 0.
- `uy`: Optional up vector y; defaults to 1.
- `uz`: Optional up vector z; defaults to 0.

### Audio.listenerPosition

```ts
static listenerPosition(): Vec3
```

Reads the 3D listener position.

**Returns:** Current listener position as Vec3.

### Audio.setSoundPosition

```ts
static setSoundPosition(sound: Sound | int, x: float64, y: float64, z: float64): void
```

Sets the 3D world position of a sound.

**Parameters**

- `sound`: Sound object or numeric handle.
- `x`: World x coordinate.
- `y`: World y coordinate.
- `z`: World z coordinate.

### Audio.setSoundSpatialized

```ts
static setSoundSpatialized(sound: Sound | int, enabled: boolean): void
```

Enables or disables 3D spatial positioning for a sound.

**Parameters**

- `sound`: Sound object or numeric handle.
- `enabled`: True to use 3D positioning, false for 2D panning only.

### Audio.setSoundDistanceRange

```ts
static setSoundDistanceRange(sound: Sound | int, minDist: float64, maxDist: float64): void
```

Sets the distance range for spatial attenuation.

**Parameters**

- `sound`: Sound object or numeric handle.
- `minDist`: Minimum distance in world units; no attenuation closer than this.
- `maxDist`: Maximum distance in world units; silent beyond this.

### Audio.setSoundRolloff

```ts
static setSoundRolloff(sound: Sound | int, rolloff: float64): void
```

Sets the rolloff factor for distance attenuation.

**Parameters**

- `sound`: Sound object or numeric handle.
- `rolloff`: Rolloff exponent; typical range 0.0–2.0.

### Audio.soundRolloff

```ts
static soundRolloff(sound: Sound | int): float64
```

Reads the rolloff factor of a sound.

**Parameters**

- `sound`: Sound object or numeric handle.

**Returns:** Current rolloff exponent.

### Audio.setSoundDopplerFactor

```ts
static setSoundDopplerFactor(sound: Sound | int, factor: float64): void
```

Sets the Doppler effect factor for a sound.

**Parameters**

- `sound`: Sound object or numeric handle.
- `factor`: Doppler factor; 1.0 is realistic, 0.0 disables the effect.

### Audio.soundDopplerFactor

```ts
static soundDopplerFactor(sound: Sound | int): float64
```

Reads the Doppler effect factor of a sound.

**Parameters**

- `sound`: Sound object or numeric handle.

**Returns:** Current Doppler factor.

### Audio.setSoundVelocity

```ts
static setSoundVelocity(sound: Sound | int, x: float64, y: float64, z: float64): void
```

Sets the 3D velocity of a sound for Doppler effects.

**Parameters**

- `sound`: Sound object or numeric handle.
- `x`: Velocity x component.
- `y`: Velocity y component.
- `z`: Velocity z component.

### Audio.setSoundAttenuationModel

```ts
static setSoundAttenuationModel(sound: Sound | int, model: int): void
```

Sets the spatial attenuation model for a sound.

**Parameters**

- `sound`: Sound object or numeric handle.
- `model`: An Attenuation constant.

### Audio.soundAttenuationModel

```ts
static soundAttenuationModel(sound: Sound | int): int
```

Reads the spatial attenuation model of a sound.

**Parameters**

- `sound`: Sound object or numeric handle.

**Returns:** Current Attenuation constant.

### Audio.playSpatial

```ts
static playSpatial(sound: Sound | int, x: float64, y: float64, z: float64, minDist?: float64, maxDist?: float64, volume?: float64, pitch?: float64, loop?: boolean): void
```

Plays a sound at a 3D position with optional attenuation.

**Parameters**

- `sound`: Sound object or numeric handle.
- `x`: World x coordinate.
- `y`: World y coordinate.
- `z`: World z coordinate.
- `minDist`: Optional minimum distance for attenuation.
- `maxDist`: Optional maximum distance for attenuation.
- `volume`: Optional volume; 0 is silent, 1 is normal.
- `pitch`: Optional speed multiplier.
- `loop`: Optional boolean for looping playback.

## Music <Badge type="info" text="static class" />

```ts
static class Music
```

Global background-music playback. Audio's music methods remain aliases.

### Music.volume

```ts
static volume: float64
```

Music volume; 0 is silent, 1 is normal.

### Music.isPlaying

```ts
static readonly isPlaying: boolean
```

True if music is currently playing. Read-only.

### Music.current

```ts
static readonly current: int
```

Numeric handle of the currently playing track, or 0 if none. Read-only.

### Music.play

```ts
static play(track: int | MusicTrack): void
```

Begins playback of a music track.

**Parameters**

- `track`: MusicTrack object or numeric handle.

### Music.crossfade

```ts
static crossfade(track: int | MusicTrack, ms: int): void
```

Crossfades to a new music track over a specified duration.

**Parameters**

- `track`: MusicTrack object or numeric handle to crossfade to.
- `ms`: Crossfade duration in milliseconds.

### Music.pause

```ts
static pause(): void
```

Pauses music playback.

### Music.resume

```ts
static resume(): void
```

Resumes music playback after `pause()`.

### Music.stop

```ts
static stop(fadeMs?: int): void
```

Stops music playback with optional fade-out.

**Parameters**

- `fadeMs`: Optional fade-out duration in milliseconds.

## audio <Badge type="info" text="const" />

```ts
const audio: any
```

::: warning Deprecated
Use `Audio`.
:::

---

*Generated from `lang/types/audio.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/bitmap

# bitmap

Bitmaps: load, draw, composite and save images.

::: tip Import
```ts
import { BitmapFormat, BlendMode, ScaleFilter, LineCap, ... } from "bitmap";
```
:::

## BitmapFormat <Badge type="info" text="enum" />

```ts
enum BitmapFormat
```

Pixel format identifier for `Bitmap` allocation and conversion.

- `BitmapFormat.RGB8`: 24-bit RGB, no alpha. 3 bytes per pixel.
- `BitmapFormat.RGBA8`: 32-bit RGBA. 4 bytes per pixel. The default.
- `BitmapFormat.RGB16`: 48-bit RGB, no alpha. 6 bytes per pixel.
- `BitmapFormat.RGBA16`: 64-bit RGBA. 8 bytes per pixel.

## BlendMode <Badge type="info" text="enum" />

```ts
enum BlendMode
```

Compositing operator for `Bitmap.composite`, `DrawContext.setBlendMode`, and `Bitmap.drawScaled`.

- `BlendMode.REPLACE`: Direct overwrite. Source replaces destination unconditionally.
- `BlendMode.ALPHA`: Standard alpha compositing. Source alpha blends over destination.
- `BlendMode.ADDITIVE`: Add channels: dest + src. Saturates at 255.
- `BlendMode.MULTIPLY`: Multiply channels: dest * src / 255.
- `BlendMode.SCREEN`: Inverse multiply: 255 - ((255-dest) * (255-src) / 255).
- `BlendMode.OVERLAY`: Combination of multiply and screen depending on dest brightness.
- `BlendMode.DARKEN`: Per-channel `min(dest, src)`.
- `BlendMode.LIGHTEN`: Per-channel `max(dest, src)`.
- `BlendMode.COLOR_DODGE`: Brighten dest by src; high src values produce extreme highlights.
- `BlendMode.COLOR_BURN`: Darken dest by src; high src values produce deep shadows.
- `BlendMode.DIFFERENCE`: Absolute difference between channels.
- `BlendMode.EXCLUSION`: Like difference but lower contrast.

## ScaleFilter <Badge type="info" text="enum" />

```ts
enum ScaleFilter
```

Sampling filter for `Bitmap.resize` and `Bitmap.drawScaled`.

- `ScaleFilter.NEAREST`: Nearest-neighbour. Fastest, blocky output, preserves hard edges.
- `ScaleFilter.BILINEAR`: Bilinear interpolation. Smooth but soft. The default.
- `ScaleFilter.BICUBIC`: Bicubic interpolation. Sharpest of the smooth filters, slowest.

## LineCap <Badge type="info" text="enum" />

```ts
enum LineCap
```

Line-end style for `DrawContext.setLineCap`.

- `LineCap.BUTT`: Flat end at the line endpoint. The default.
- `LineCap.ROUND`: Semicircular cap extending past the endpoint by half the line width.
- `LineCap.SQUARE`: Square cap extending past the endpoint by half the line width.

## LineJoin <Badge type="info" text="enum" />

```ts
enum LineJoin
```

Line-join style for `DrawContext.setLineJoin`.

- `LineJoin.MITER`: Sharp mitered corner. The default.
- `LineJoin.ROUND`: Rounded corner with radius equal to half the line width.
- `LineJoin.BEVEL`: Beveled corner: a straight edge between the two segments.

## TextAlign <Badge type="info" text="enum" />

```ts
enum TextAlign
```

Horizontal text alignment for `DrawContext.setTextAlign`.

- `TextAlign.LEFT`: Anchor on the left edge of the text bounding box. The default.
- `TextAlign.CENTER`: Anchor on the horizontal center.
- `TextAlign.RIGHT`: Anchor on the right edge.

## TextBaseline <Badge type="info" text="enum" />

```ts
enum TextBaseline
```

Vertical text alignment for `DrawContext.setTextBaseline`.

- `TextBaseline.ALPHABETIC`: Anchor on the alphabetic baseline. The default.
- `TextBaseline.TOP`: Anchor on the top of the text bounding box.
- `TextBaseline.MIDDLE`: Anchor on the vertical center of the text bounding box.
- `TextBaseline.BOTTOM`: Anchor on the bottom of the text bounding box.

## ImageFormat <Badge type="info" text="enum" />

```ts
enum ImageFormat
```

File format for `Bitmap.encode`.

- `ImageFormat.PNG`: Portable Network Graphics. Lossless.
- `ImageFormat.JPEG`: JPEG. Lossy, no alpha channel.
- `ImageFormat.BMP`: Windows BMP. Lossless, uncompressed.
- `ImageFormat.TGA`: Truevision TGA. Lossless.
- `ImageFormat.WEBP`: WebP. Lossy or lossless, smaller than PNG/JPEG.

## TextMetrics <Badge type="info" text="class" />

```ts
class TextMetrics
```

Glyph metrics for a string under the active font, returned by `DrawContext.measureText`.

### TextMetrics.width

```ts
readonly width: float
```

Advance width: total horizontal space the text occupies.

### TextMetrics.height

```ts
readonly height: float
```

Total vertical extent (ascent + descent).

### TextMetrics.ascent

```ts
readonly ascent: float
```

Distance from the baseline to the highest glyph point.

### TextMetrics.descent

```ts
readonly descent: float
```

Distance from the baseline to the lowest glyph point.

### TextMetrics.leftBearing

```ts
readonly leftBearing: float
```

Horizontal padding to the left of the first glyph's ink.

### TextMetrics.rightBearing

```ts
readonly rightBearing: float
```

Horizontal padding to the right of the last glyph's ink.

## Bitmap <Badge type="info" text="class" />

```ts
class Bitmap
```

2D pixel buffer. Owns its memory; pixel data is freed when the
Bitmap is garbage-collected, or immediately when `dispose()` is
called.

Pixels are stored row-major, top-left origin. Colors are 32-bit
`Color` values (one packed `0xRRGGBBAA` uint32) — use the `Color` helpers to build
them.

**Example**

```ts
import { Bitmap } from "bitmap";
const bmp: Bitmap = new Bitmap(320, 240);
bmp.fill(Color.rgb(0, 0, 0));
bmp.fillRect(10, 10, 50, 50, Color.rgb(255, 0, 0));
```

### Bitmap.width

```ts
readonly width: int
```

Width in pixels. Read-only — set at construction.

### Bitmap.height

```ts
readonly height: int
```

Height in pixels. Read-only — set at construction.

### Bitmap.format

```ts
readonly format: string
```

Pixel format identifier. One of `BitmapFormat`'s string values.

### Bitmap.channels

```ts
readonly channels: int
```

Number of color channels in the active format (3 for RGB, 4 for RGBA).

### Bitmap.byteSize

```ts
readonly byteSize: int
```

Total size of the pixel buffer in bytes.

### new Bitmap()

```ts
constructor(width: int, height: int)
constructor(width: int, height: int, format: BitmapFormat)
```

Allocate a new bitmap of `width` x `height` pixels in `RGBA8`
format. Pixel contents are uninitialized — call `fill()` before
reading.

### Bitmap.dispose

```ts
dispose(): void
```

Free the pixel buffer immediately. Any further operation on
this bitmap signals an error. Idempotent — safe to call more
than once.

### Bitmap.getPixel

```ts
getPixel(x: int, y: int): Color
```

Read the pixel at `(x, y)` as a packed `0xRRGGBBAA` integer.
Out-of-bounds coordinates return zero rather than erroring.

### Bitmap.setPixel

```ts
setPixel(x: int, y: int, color: Color): void
```

Write `color` (packed `0xRRGGBBAA`) to the pixel at `(x, y)`.
Out-of-bounds coordinates are silently ignored.

### Bitmap.getPixelPacked

```ts
getPixelPacked(x: int, y: int): int
```

Read the pixel at `(x, y)` in the bitmap's native packed layout.
The exact byte order depends on `format`; intended for fast paths
that round-trip through `setPixelPacked` rather than mixing with
`Color` helpers.

### Bitmap.setPixelPacked

```ts
setPixelPacked(x: int, y: int, packed: int): void
```

Write `packed` (native layout) to the pixel at `(x, y)`. Pair
with `getPixelPacked` for format-preserving copies.

### Bitmap.fill

```ts
fill(color: Color): void
```

Fill every pixel with `color` (packed `0xRRGGBBAA`).

### Bitmap.fillRect

```ts
fillRect(x: int, y: int, w: int, h: int, color: Color): void
```

Fill the axis-aligned rectangle `(x, y, w, h)` with `color`.

### Bitmap.drawLine

```ts
drawLine(x0: int, y0: int, x1: int, y1: int, color: Color): void
```

Draw a 1-pixel line from `(x0, y0)` to `(x1, y1)` in `color`.

### Bitmap.drawRect

```ts
drawRect(x: int, y: int, w: int, h: int, color: Color): void
```

Draw the outline of the rectangle `(x, y, w, h)` in `color`.

### Bitmap.drawCircle

```ts
drawCircle(cx: int, cy: int, r: int, color: Color): void
```

Draw the outline of a circle centered at `(cx, cy)` with radius `r`.

### Bitmap.fillCircle

```ts
fillCircle(cx: int, cy: int, r: int, color: Color): void
```

Fill the circle centered at `(cx, cy)` with radius `r`.

### Bitmap.composite

```ts
composite(src: Bitmap, destX: int, destY: int, blendMode?: BlendMode): void
```

Composite `src` onto this bitmap with the top-left corner of
`src` at `(destX, destY)`. Defaults to `BlendMode.ALPHA`.

### Bitmap.blit

```ts
blit(src: Bitmap, destX: int, destY: int): void
```

Direct copy of `src` onto this bitmap with the top-left corner
at `(destX, destY)`. Faster than `composite` because it skips
blending — pixels are overwritten.

### Bitmap.drawScaled

```ts
drawScaled(src: Bitmap, destX: int, destY: int, destW: int, destH: int, filter: ScaleFilter, blendMode?: BlendMode): void
```

Scale `src` to `(destW, destH)` and composite at `(destX, destY)`.
`blendMode` defaults to `BlendMode.ALPHA`.

### Bitmap.blur

```ts
blur(radius?: int): void
```

Box blur with the given pixel `radius`. Defaults to `1`.

### Bitmap.gaussianBlur

```ts
gaussianBlur(sigma?: float): void
```

Gaussian blur with the given `sigma`. Defaults to `1.0`.

### Bitmap.sharpen

```ts
sharpen(amount?: float): void
```

Unsharp-mask sharpen by `amount` (1.0 = neutral). Defaults to `1.0`.

### Bitmap.grayscale

```ts
grayscale(): void
```

Convert all pixels to luma-weighted grayscale, in place.

### Bitmap.invert

```ts
invert(): void
```

Invert R, G, B channels, in place. Alpha is preserved.

### Bitmap.sepia

```ts
sepia(intensity?: float): void
```

Sepia tone, in place. `intensity` blends between original and
full sepia (0.0 = none, 1.0 = full). Defaults to `1.0`.

### Bitmap.adjustBrightness

```ts
adjustBrightness(delta: float): void
```

Add `delta` (-1.0 to 1.0) to every channel.

### Bitmap.adjustContrast

```ts
adjustContrast(factor: float): void
```

Multiply contrast around mid-gray by `factor` (1.0 = unchanged).

### Bitmap.adjustHue

```ts
adjustHue(degrees: float): void
```

Rotate hue by `degrees` (-360 to 360).

### Bitmap.adjustSaturation

```ts
adjustSaturation(factor: float): void
```

Multiply saturation by `factor` (0.0 = grayscale, 1.0 = unchanged).

### Bitmap.adjustOpacity

```ts
adjustOpacity(factor: float): void
```

Multiply alpha by `factor` (0.0 = transparent, 1.0 = unchanged).

### Bitmap.pixelate

```ts
pixelate(size?: int): void
```

Quantize into `size`-pixel blocks for a mosaic effect. Defaults to `4`.

### Bitmap.tint

```ts
tint(color: Color): void
```

Multiply every pixel by `color`. Preserves alpha.

### Bitmap.replaceColor

```ts
replaceColor(from: Color, to: Color, tolerance?: int): void
```

Replace every pixel within `tolerance` of `from` with `to`.
`tolerance` is in 0-255 distance per channel; `0` means exact
match.

### Bitmap.posterize

```ts
posterize(levels?: int): void
```

Posterize each channel to `levels` discrete values. Defaults to `4`.

### Bitmap.threshold

```ts
threshold(level?: float): void
```

Binarize: pixels with luma >= `level` (0.0 to 1.0) become white,
others black. Defaults to `0.5`.

### Bitmap.applyMask

```ts
applyMask(mask: Bitmap): void
```

Multiply this bitmap's alpha channel by `mask`'s luma, pixel by
pixel. `mask` must match this bitmap's dimensions.

### Bitmap.crop

```ts
crop(x: int, y: int, w: int, h: int): Bitmap
```

Return a new bitmap containing the rectangle `(x, y, w, h)`.

### Bitmap.resize

```ts
resize(w: int, h: int, filter?: ScaleFilter): Bitmap
```

Return a new bitmap resized to `(w, h)`. `filter` defaults to
`ScaleFilter.BILINEAR`.

### Bitmap.flipH

```ts
flipH(): Bitmap
```

Return a new bitmap mirrored horizontally.

### Bitmap.flipV

```ts
flipV(): Bitmap
```

Return a new bitmap mirrored vertically.

### Bitmap.rotate90

```ts
rotate90(): Bitmap
```

Return a new bitmap rotated 90° clockwise.

### Bitmap.rotate180

```ts
rotate180(): Bitmap
```

Return a new bitmap rotated 180°.

### Bitmap.rotate270

```ts
rotate270(): Bitmap
```

Return a new bitmap rotated 270° clockwise (90° counter-clockwise).

### Bitmap.rotate

```ts
rotate(degrees: float, bgColor?: Color): Bitmap
```

Return a new bitmap rotated by an arbitrary angle. The output is
sized to fit the rotated source; new corners are filled with
`bgColor` (default fully transparent).

### Bitmap.trim

```ts
trim(bg?: Color): Bitmap
```

Return a new bitmap with edges of color `bg` (default fully
transparent) trimmed away.

### Bitmap.pad

```ts
pad(top: int, right: int, bottom: int, left: int, fill?: Color): Bitmap
```

Return a new bitmap padded by the given margins, filling new
pixels with `fill` (default fully transparent).

### Bitmap.convert

```ts
convert(format: BitmapFormat): Bitmap
```

Return a new bitmap converted to `format`.

### Bitmap.equals

```ts
equals(other: Bitmap): boolean
```

True when `other` has identical dimensions, format, and pixels.

### Bitmap.diff

```ts
diff(other: Bitmap): Bitmap
```

Return a new bitmap whose pixels are the absolute difference
between this and `other`, channel-by-channel.

### Bitmap.clone

```ts
clone(): Bitmap
```

Return an independent copy of this bitmap.

### Bitmap.encode

```ts
encode(format: ImageFormat): Buffer
```

Encode the bitmap to a Buffer in the given file `format`.
Pair with `Files.writeFile` to save to disk.

### Bitmap.context

```ts
context(): DrawContext
```

Open a Canvas2D-style drawing context against this bitmap. The
returned `DrawContext` keeps this bitmap alive for as long as it
is referenced.

### Bitmap.scan

```ts
scan(fn?: Function): Array<[int, int, Color]>
```

Return every pixel as `[x, y, color]` tuples.

Bitmaps larger than 4 megapixels are rejected — use
`getRegion()` to slice subsets first.

**Parameters**

- `fn`: (NYI) When provided, will be called for each pixel as `fn(x: int, y: int, color: Color): void` and the array return becomes empty. Until the C++ wires the callback path, `fn` is ignored and the method behaves identically to the no-arg form. Future-proofed as optional so the callback shape can land without a breaking change.

### Bitmap.pixels

```ts
pixels(): Array<Color>
```

Return every pixel color as a flat `Array<Color>`, row-major.

Subject to the same 4-megapixel cap as `scan()`.

### Bitmap.region

```ts
region(x: int, y: int, w: int, h: int): Array<Color>
```

Return the colors of the pixels inside `(x, y, w, h)` as a flat
`Array<Color>`, row-major. Out-of-bounds portions are silently
dropped.

### Bitmap.edgeDetect

```ts
edgeDetect(): Bitmap
```

Return a new bitmap containing only edge pixels (Sobel-style).

### Bitmap.emboss

```ts
emboss(angle?: float, strength?: float): void
```

In-place emboss effect.

`angle` is the light direction in degrees (default `135`).
`strength` scales the effect (default `1.0`).

### Bitmap.getRegion

```ts
getRegion(x: int, y: int, w: int, h: int): Bitmap
```

Return a new bitmap containing the rectangle `(x, y, w, h)`.

### Bitmap.putRegion

```ts
putRegion(src: Bitmap, x: int, y: int): void
```

Paste `src` into this bitmap with its top-left at `(x, y)`. Direct copy, no blending.

### Bitmap.contentBounds

```ts
contentBounds(threshold?: int): BitmapRect
```

Return the smallest `BitmapRect` enclosing pixels above
`threshold` alpha (default `0`).

### Bitmap.fromBuffer

```ts
static fromBuffer(buffer: Buffer): Bitmap
```

Decode an image Buffer into a new Bitmap. Format is detected
from the buffer header (PNG, JPEG, BMP, TGA, WebP).

**Example**

```ts
import { Bitmap } from "bitmap";
import { Files } from "fs";
const png: any = await Files.readFile("sprite.png");
const image: Bitmap = Bitmap.fromBuffer(png);
console.log(image.width, image.height);
```

## DrawContext <Badge type="info" text="class" />

```ts
class DrawContext
```

Canvas2D-style drawing context bound to a Bitmap. Obtained via
`bmp.context()`. State is layered: `save()` pushes the current
style/clip/transform; `restore()` pops it.

Floating-point coordinates are accepted and rasterized with
antialiasing when enabled (`setAntialias(true)`, the default).

### DrawContext.save

```ts
save(): void
```

Push the current drawing state (style, clip, transform) onto the stack.

### DrawContext.restore

```ts
restore(): void
```

Pop the most recently saved drawing state.

### DrawContext.reset

```ts
reset(): void
```

Reset all drawing state to defaults and clear the state stack.

### DrawContext.setFillColor

```ts
setFillColor(color: Color): void
```

Set the fill color used by `fill*` methods. Packed `0xRRGGBBAA`.

### DrawContext.setStrokeColor

```ts
setStrokeColor(color: Color): void
```

Set the stroke color used by `stroke*` methods. Packed `0xRRGGBBAA`.

### DrawContext.setLineWidth

```ts
setLineWidth(width: float): void
```

Set the stroke line width in pixels.

### DrawContext.setLineCap

```ts
setLineCap(cap: LineCap): void
```

Set the line end style.

### DrawContext.setLineJoin

```ts
setLineJoin(join: LineJoin): void
```

Set the line join style.

### DrawContext.setGlobalAlpha

```ts
setGlobalAlpha(alpha: float): void
```

Multiply all subsequent draws by `alpha` (0.0 to 1.0).

### DrawContext.setBlendMode

```ts
setBlendMode(mode: BlendMode): void
```

Set the blend mode for subsequent draws.

### DrawContext.setAntialias

```ts
setAntialias(enabled: boolean): void
```

Toggle antialiasing for subsequent draws. Defaults to enabled.

### DrawContext.clearRect

```ts
clearRect(x: float, y: float, w: float, h: float): void
```

Clear `(x, y, w, h)` to fully transparent.

### DrawContext.fillRect

```ts
fillRect(x: float, y: float, w: float, h: float): void
```

Fill the rectangle `(x, y, w, h)` with the current fill color.

### DrawContext.strokeRect

```ts
strokeRect(x: float, y: float, w: float, h: float): void
```

Stroke the outline of the rectangle `(x, y, w, h)`.

### DrawContext.fillCircle

```ts
fillCircle(cx: float, cy: float, r: float): void
```

Fill the circle centered at `(cx, cy)` with radius `r`.

### DrawContext.strokeCircle

```ts
strokeCircle(cx: float, cy: float, r: float): void
```

Stroke the outline of the circle centered at `(cx, cy)` with radius `r`.

### DrawContext.drawLine

```ts
drawLine(x0: float, y0: float, x1: float, y1: float): void
```

Stroke a line from `(x0, y0)` to `(x1, y1)`.

### DrawContext.fillRoundRect

```ts
fillRoundRect(x: float, y: float, w: float, h: float, radius: float): void
```

Fill the rounded rectangle `(x, y, w, h)` with corner `radius`.

### DrawContext.strokeRoundRect

```ts
strokeRoundRect(x: float, y: float, w: float, h: float, radius: float): void
```

Stroke the rounded rectangle `(x, y, w, h)` with corner `radius`.

### DrawContext.fillEllipse

```ts
fillEllipse(cx: float, cy: float, rx: float, ry: float): void
```

Fill the ellipse centered at `(cx, cy)` with radii `(rx, ry)`.

### DrawContext.strokeEllipse

```ts
strokeEllipse(cx: float, cy: float, rx: float, ry: float): void
```

Stroke the outline of the ellipse centered at `(cx, cy)` with radii `(rx, ry)`.

### DrawContext.setFontFromSystem

```ts
setFontFromSystem(name: string, size: float): void
```

Load a font by system family name (e.g. `"Helvetica"`,
`"Arial"`) at the given pixel `size` and use it for subsequent
`fillText` / `strokeText` / `measureText`.

The font is cached per-context by name.

### DrawContext.setFontFromPath

```ts
setFontFromPath(path: string, size: float): void
```

Load a font from a `.ttf` / `.otf` file at `path`, at the given
pixel `size`. Cached per-context by path.

### DrawContext.setFontFromBuffer

```ts
setFontFromBuffer(buffer: Buffer, size: float): void
```

Load a font from an in-memory Buffer at the given pixel `size`.
The Buffer must remain valid for the lifetime of the context.

### DrawContext.setTextAlign

```ts
setTextAlign(align: TextAlign): void
```

Set horizontal alignment for `fillText` / `strokeText`.

### DrawContext.setTextBaseline

```ts
setTextBaseline(baseline: TextBaseline): void
```

Set vertical alignment.

### DrawContext.fillText

```ts
fillText(text: string, x: float, y: float): void
```

Fill `text` at `(x, y)` using the current font and fill color.

### DrawContext.strokeText

```ts
strokeText(text: string, x: float, y: float): void
```

Stroke the outline of `text` at `(x, y)` using the current font and stroke color.

### DrawContext.measureText

```ts
measureText(text: string): TextMetrics
```

Measure `text` with the current font, returning a `TextMetrics`.

### DrawContext.beginPath

```ts
beginPath(): void
```

Start a new path, discarding any pending sub-paths.

### DrawContext.closePath

```ts
closePath(): void
```

Close the current sub-path with a straight line to its starting point.

### DrawContext.moveTo

```ts
moveTo(x: float, y: float): void
```

Move the path cursor to `(x, y)` without drawing.

### DrawContext.lineTo

```ts
lineTo(x: float, y: float): void
```

Add a straight line from the current cursor to `(x, y)`.

### DrawContext.arc

```ts
arc(cx: float, cy: float, r: float, startAngle: float, endAngle: float, ccw?: boolean): void
```

Add a circular arc centered at `(cx, cy)` of radius `r`, from
`startAngle` to `endAngle` (radians). When `ccw` is `true` the
arc is drawn counter-clockwise.

### DrawContext.arcTo

```ts
arcTo(x1: float, y1: float, x2: float, y2: float, radius: float): void
```

Add an arc tangent to the line from the cursor to `(x1, y1)` and
the line from `(x1, y1)` to `(x2, y2)`, with the given `radius`.

### DrawContext.bezierTo

```ts
bezierTo(cp1x: float, cp1y: float, cp2x: float, cp2y: float, x: float, y: float): void
```

Add a cubic Bézier curve to `(x, y)` with control points `(cp1x, cp1y)` and `(cp2x, cp2y)`.

### DrawContext.quadraticTo

```ts
quadraticTo(cpx: float, cpy: float, x: float, y: float): void
```

Add a quadratic Bézier curve to `(x, y)` with control point `(cpx, cpy)`.

### DrawContext.rect

```ts
rect(x: float, y: float, w: float, h: float): void
```

Add a closed rectangle sub-path.

### DrawContext.fill

```ts
fill(): void
```

Fill the current path with the current fill color.

### DrawContext.stroke

```ts
stroke(): void
```

Stroke the current path with the current stroke color and line settings.

### DrawContext.clip

```ts
clip(): void
```

Restrict subsequent drawing to the current path.

### DrawContext.resetClip

```ts
resetClip(): void
```

Remove any active clip region.

### DrawContext.floodFill

```ts
floodFill(x: int, y: int, tolerance?: float): void
```

Fill connected pixels reachable from `(x, y)` whose color
matches the seed within `tolerance` (0.0 to 1.0, default `0`).

### DrawContext.isPointInPath

```ts
isPointInPath(x: float, y: float): boolean
```

True when `(x, y)` is inside the current path's filled region.

### DrawContext.isPointInStroke

```ts
isPointInStroke(x: float, y: float): boolean
```

True when `(x, y)` is inside the current path's stroked outline.

---

*Generated from `lang/types/bitmap.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/bitmaprect

# BitmapRect

The rectangle `Bitmap.contentBounds` returns.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## BitmapRect <Badge type="info" text="struct" />

```ts
struct BitmapRect
```

Axis-aligned bounding rectangle in whole pixels, returned by `Bitmap.contentBounds`.

### BitmapRect.x

```ts
x: int
```

Left edge in pixels.

### BitmapRect.y

```ts
y: int
```

Top edge in pixels.

### BitmapRect.w

```ts
w: int
```

Width in pixels.

### BitmapRect.h

```ts
h: int
```

Height in pixels.

### Other members of BitmapRect

```ts
operator eq(other: BitmapRect): boolean
toString(): string
```

---

*Generated from `lang/bitmaprect/index.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/buffer

# Buffers and typed arrays

`ByteArray`, `Buffer`, the typed arrays and their encodings.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## TextEncoding <Badge type="info" text="enum" />

```ts
enum TextEncoding
```

Text encoding accepted by `ByteArray.from(string, ...)`,
`toString`, `readString` and `writeString`. The runtime rejects
unknown encodings and non-string arguments at the call site.

- `TextEncoding.UTF8`: UTF-8. The default for both decode and encode.
- `TextEncoding.ASCII`: 7-bit ASCII; bytes above 127 decode to `?`.
- `TextEncoding.LATIN1`: ISO-8859-1; one byte per code point, no transformation.
- `TextEncoding.HEX`: Lowercase hexadecimal; two characters per byte.
- `TextEncoding.BASE64`: Standard base64.

## BufferEncoding <Badge type="info" text="enum" />

```ts
enum BufferEncoding
```

`Buffer`'s old name for `TextEncoding`; the same enum.

- `BufferEncoding.UTF8`: UTF-8. The default for both decode and encode.
- `BufferEncoding.ASCII`: 7-bit ASCII; bytes above 127 decode to `?`.
- `BufferEncoding.LATIN1`: ISO-8859-1; one byte per code point, no transformation.
- `BufferEncoding.HEX`: Lowercase hexadecimal; two characters per byte.
- `BufferEncoding.BASE64`: Standard base64.

## Endian <Badge type="info" text="enum" />

```ts
enum Endian
```

Byte order of a `ByteArray`'s multi-byte reads and writes.

- `Endian.LITTLE`: Least significant byte first. The default; matches the machines and the GPU.
- `Endian.BIG`: Most significant byte first.

## ByteArray <Badge type="info" text="class" />

```ts
class ByteArray
```

A growable sequence of bytes, held by reference: everything holding it
sees the same bytes. Streamed `read*`/`write*` move `position`;
`get*`/`set*` take a byte offset and leave it alone. A read past the end
and an offset out of range are `RangeError`s; a write past the end grows
the array.

### new ByteArray()

```ts
constructor(size?: int)
```

`size` zero bytes (default 0).

### ByteArray.length

```ts
length: int
```

Length in bytes. Setting it grows (zero-filled) or truncates.

### ByteArray.byteLength

```ts
readonly byteLength: int
```

`Buffer`'s spelling of `length`. Read-only.

### ByteArray.position

```ts
position: int
```

The cursor for the streamed `read*`/`write*` methods.

### ByteArray.bytesAvailable

```ts
readonly bytesAvailable: int
```

`length - position`.

### ByteArray.endian

```ts
endian: Endian
```

Byte order for multi-byte values. `Endian.LITTLE` by default.

### ByteArray.readInt8

```ts
readInt8(): int
```

Read a signed 8-bit integer at `position`; advances `position`. @returns The value.

### ByteArray.readUInt8

```ts
readUInt8(): uint
```

Read an unsigned 8-bit integer at `position`; advances `position`. @returns The value.

### ByteArray.readInt16

```ts
readInt16(): int
```

Read a signed 16-bit integer at `position` in the set byte order; advances `position`. @returns The value.

### ByteArray.readUInt16

```ts
readUInt16(): uint
```

Read an unsigned 16-bit integer at `position` in the set byte order; advances `position`. @returns The value.

### ByteArray.readInt32

```ts
readInt32(): int
```

Read a signed 32-bit integer at `position` in the set byte order; advances `position`. @returns The value.

### ByteArray.readUInt32

```ts
readUInt32(): uint
```

Read an unsigned 32-bit integer at `position` in the set byte order; advances `position`. @returns The value.

### ByteArray.readFloat32

```ts
readFloat32(): float
```

Read a 32-bit float at `position` in the set byte order; advances `position`. @returns The value.

### ByteArray.readFloat64

```ts
readFloat64(): float64
```

Read a 64-bit float at `position` in the set byte order; advances `position`. @returns The value.

### ByteArray.readBool

```ts
readBool(): boolean
```

Read a boolean (as a byte) at `position`; advances `position`. @returns True if the byte is nonzero.

### ByteArray.writeInt8

```ts
writeInt8(value: int): void
```

Write a signed 8-bit integer at `position`; advances `position`. @param value The value to write.

### ByteArray.writeUInt8

```ts
writeUInt8(value: uint): void
```

Write an unsigned 8-bit integer at `position`; advances `position`. @param value The value to write.

### ByteArray.writeInt16

```ts
writeInt16(value: int): void
```

Write a signed 16-bit integer at `position` in the set byte order; advances `position`. @param value The value to write.

### ByteArray.writeUInt16

```ts
writeUInt16(value: uint): void
```

Write an unsigned 16-bit integer at `position` in the set byte order; advances `position`. @param value The value to write.

### ByteArray.writeInt32

```ts
writeInt32(value: int): void
```

Write a signed 32-bit integer at `position` in the set byte order; advances `position`. @param value The value to write.

### ByteArray.writeUInt32

```ts
writeUInt32(value: float64): void
```

Write an unsigned 32-bit integer at `position` in the set byte order; advances `position`. @param value The value to write.

### ByteArray.writeFloat32

```ts
writeFloat32(value: float64): void
```

Write a 32-bit float at `position` in the set byte order; advances `position`. @param value The value to write.

### ByteArray.writeFloat64

```ts
writeFloat64(value: float64): void
```

Write a 64-bit float at `position` in the set byte order; advances `position`. @param value The value to write.

### ByteArray.writeBool

```ts
writeBool(value: boolean): void
```

Write a boolean at `position` as a single byte; advances `position`. @param value Nonzero values write as 1.

### ByteArray.getInt8

```ts
getInt8(offset: int): int
```

Read a signed 8-bit integer at `offset`; does not change `position`. @param offset Byte offset in the array. @returns The value.

### ByteArray.getUInt8

```ts
getUInt8(offset: int): uint
```

Read an unsigned 8-bit integer at `offset`; does not change `position`. @param offset Byte offset in the array. @returns The value.

### ByteArray.getInt16

```ts
getInt16(offset: int): int
```

Read a signed 16-bit integer at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @returns The value.

### ByteArray.getUInt16

```ts
getUInt16(offset: int): uint
```

Read an unsigned 16-bit integer at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @returns The value.

### ByteArray.getInt32

```ts
getInt32(offset: int): int
```

Read a signed 32-bit integer at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @returns The value.

### ByteArray.getUInt32

```ts
getUInt32(offset: int): uint
```

Read an unsigned 32-bit integer at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @returns The value.

### ByteArray.getFloat32

```ts
getFloat32(offset: int): float
```

Read a 32-bit float at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @returns The value.

### ByteArray.getFloat64

```ts
getFloat64(offset: int): float64
```

Read a 64-bit float at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @returns The value.

### ByteArray.getBool

```ts
getBool(offset: int): boolean
```

Read a boolean at `offset` as a single byte; does not change `position`. @param offset Byte offset in the array. @returns True if the byte is nonzero.

### ByteArray.setInt8

```ts
setInt8(offset: int, value: int): void
```

Write a signed 8-bit integer at `offset`; does not change `position`. @param offset Byte offset in the array. @param value The value to write.

### ByteArray.setUInt8

```ts
setUInt8(offset: int, value: uint): void
```

Write an unsigned 8-bit integer at `offset`; does not change `position`. @param offset Byte offset in the array. @param value The value to write.

### ByteArray.setInt16

```ts
setInt16(offset: int, value: int): void
```

Write a signed 16-bit integer at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @param value The value to write.

### ByteArray.setUInt16

```ts
setUInt16(offset: int, value: uint): void
```

Write an unsigned 16-bit integer at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @param value The value to write.

### ByteArray.setInt32

```ts
setInt32(offset: int, value: int): void
```

Write a signed 32-bit integer at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @param value The value to write.

### ByteArray.setUInt32

```ts
setUInt32(offset: int, value: float64): void
```

Write an unsigned 32-bit integer at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @param value The value to write.

### ByteArray.setFloat32

```ts
setFloat32(offset: int, value: float64): void
```

Write a 32-bit float at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @param value The value to write.

### ByteArray.setFloat64

```ts
setFloat64(offset: int, value: float64): void
```

Write a 64-bit float at `offset` in the set byte order; does not change `position`. @param offset Byte offset in the array. @param value The value to write.

### ByteArray.setBool

```ts
setBool(offset: int, value: boolean): void
```

Write a boolean at `offset` as a single byte; does not change `position`. @param offset Byte offset in the array. @param value Nonzero values write as 1.

### ByteArray.readBytes

```ts
readBytes(dest: ByteArray, offset?: int, length?: int): void
```

Copy `length` bytes from `position` into `dest` at `offset`
(default 0), growing `dest`; `length` 0 or omitted means all the
bytes available. Advances `position`.

### ByteArray.writeBytes

```ts
writeBytes(src: ByteArray, offset?: int, length?: int): void
```

Copy `length` bytes of `src` starting at `offset` (default 0) in at
`position`, growing this array; `length` 0 or omitted means the rest
of `src`. Advances `position`.

### ByteArray.readUTFBytes

```ts
readUTFBytes(length: int): string
```

Read `length` bytes as UTF-8 text.

### ByteArray.writeUTFBytes

```ts
writeUTFBytes(text: string): void
```

Write `text` as UTF-8 bytes.

### ByteArray.readString

```ts
readString(length: int, encoding?: TextEncoding): string
```

Read `length` bytes as text in `encoding` (default `TextEncoding.UTF8`).

### ByteArray.writeString

```ts
writeString(text: string, encoding?: TextEncoding): void
```

Write `text` encoded in `encoding` (default `TextEncoding.UTF8`).

### ByteArray.clear

```ts
clear(): void
```

Length 0 and position 0.

### ByteArray.slice

```ts
slice(start?: int, end?: int): ByteArray
```

Return a fresh array copying bytes in the half-open range
`[start, end)`. `end` defaults to `length`. Out-of-range
indices are clamped; an empty range yields an empty array.

### ByteArray.toString

```ts
toString(encoding?: TextEncoding): string
```

Decode the whole array to a string. `encoding` defaults to
`TextEncoding.UTF8`. Throws on unknown encodings or
non-string arguments.

### ByteArray.from

```ts
static from(data: any, encoding?: TextEncoding): ByteArray
```

Build an array from `data`. An `Array<int>` is treated as a byte
sequence (each element masked to 8 bits). A `ByteArray` is copied.
A typed array is copied element by element, each masked to 8 bits.
A numeric `FixedArray` copies its bytes, packed at native width, in
little-endian order.
A string is encoded using `encoding` (default `TextEncoding.UTF8`).
Throws if `encoding` is provided but is not a string. Other input
types yield an empty array.

**Example**

```ts
const bytes: ByteArray = ByteArray.from("hi");
const buf: Buffer = Buffer.from("hi");
console.log(bytes.length, buf.length); // 2 2
```

## Buffer <Badge type="info" text="class" />

```ts
class Buffer extends ByteArray
```

The old name of `ByteArray`: an alias of the same type, kept so
existing code compiles unchanged. `Buffer.alloc(n)`, `Buffer.from(...)`,
`byteLength` and `BufferEncoding` all work on it. Prefer `ByteArray`.

### Buffer.alloc

```ts
static alloc(size: int): ByteArray
```

`new ByteArray(size)`: a zero-filled array of `size` bytes.

## TypedArray <Badge type="info" text="class" />

```ts
class TypedArray
```

*Type only: the runtime hands you instances; you never construct it yourself.*

The type name for "any typed array".

All eight spellings use the fixed-array runtime representation.
`t is TypedArray` is true for every one. `t is Uint8Array` is true
exactly when the element type is `uint8`, and likewise for the other
seven spellings.

### TypedArray.length

```ts
readonly length: int
```

Number of elements in the view.

### TypedArray.byteLength

```ts
readonly byteLength: int
```

Total byte size of the view.

### TypedArray.set

```ts
set(source: any, offset?: int): void
```

Copy `source` (an array or another typed array) in starting at
`offset` (default 0), converting each element to this element type.
Throws RangeError when `source.length + offset` exceeds `length` or
`offset` is negative.

**Parameters**

- `source`: Array or typed array whose elements to copy.
- `offset`: Optional starting index in this array; defaults to 0.

## Int8Array <Badge type="info" text="class" />

```ts
class Int8Array extends TypedArray
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Old-grammar declaration for the `FixedArray<int8>` alias. `new Int8Array(x)` is compiler-lowered to `__fa_construct`; no runtime global exists.

### new Int8Array()

```ts
constructor()
constructor(length: int)
constructor(source: ByteArray)
constructor(source: TypedArray)
constructor(values: Array<int>)
```

Create an empty typed array.

### Int8Array.slice

```ts
slice(begin?: int, end?: int): Int8Array
```

A COPY of elements [begin, end) in new storage. Negative indices
count from the end; both clamp to the length.

**Parameters**

- `begin`: Optional starting index; defaults to 0.
- `end`: Optional ending index (exclusive); defaults to length.

**Returns:** A new Int8Array containing the copied elements.

## Uint8Array <Badge type="info" text="class" />

```ts
class Uint8Array extends TypedArray
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Old-grammar declaration for the `FixedArray<uint8>` alias. `new Uint8Array(x)` is compiler-lowered to `__fa_construct`; no runtime global exists.

### new Uint8Array()

```ts
constructor()
constructor(length: int)
constructor(source: ByteArray)
constructor(source: TypedArray)
constructor(values: Array<int>)
```

Create an empty typed array.

### Uint8Array.slice

```ts
slice(begin?: int, end?: int): Uint8Array
```

A COPY of elements [begin, end) in new storage. Negative indices
count from the end; both clamp to the length.

**Parameters**

- `begin`: Optional starting index; defaults to 0.
- `end`: Optional ending index (exclusive); defaults to length.

**Returns:** A new Uint8Array containing the copied elements.

## Int16Array <Badge type="info" text="class" />

```ts
class Int16Array extends TypedArray
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Old-grammar declaration for the `FixedArray<int16>` alias. `new Int16Array(x)` is compiler-lowered to `__fa_construct`; no runtime global exists.

### new Int16Array()

```ts
constructor()
constructor(length: int)
constructor(source: ByteArray)
constructor(source: TypedArray)
constructor(values: Array<int>)
```

Create an empty typed array.

### Int16Array.slice

```ts
slice(begin?: int, end?: int): Int16Array
```

A COPY of elements [begin, end) in new storage. Negative indices
count from the end; both clamp to the length.

**Parameters**

- `begin`: Optional starting index; defaults to 0.
- `end`: Optional ending index (exclusive); defaults to length.

**Returns:** A new Int16Array containing the copied elements.

## Uint16Array <Badge type="info" text="class" />

```ts
class Uint16Array extends TypedArray
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Old-grammar declaration for the `FixedArray<uint16>` alias. `new Uint16Array(x)` is compiler-lowered to `__fa_construct`; no runtime global exists.

### new Uint16Array()

```ts
constructor()
constructor(length: int)
constructor(source: ByteArray)
constructor(source: TypedArray)
constructor(values: Array<int>)
```

Create an empty typed array.

### Uint16Array.slice

```ts
slice(begin?: int, end?: int): Uint16Array
```

A COPY of elements [begin, end) in new storage. Negative indices
count from the end; both clamp to the length.

**Parameters**

- `begin`: Optional starting index; defaults to 0.
- `end`: Optional ending index (exclusive); defaults to length.

**Returns:** A new Uint16Array containing the copied elements.

## Int32Array <Badge type="info" text="class" />

```ts
class Int32Array extends TypedArray
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Old-grammar declaration for the `FixedArray<int32>` alias. `new Int32Array(x)` is compiler-lowered to `__fa_construct`; no runtime global exists.

### new Int32Array()

```ts
constructor()
constructor(length: int)
constructor(source: ByteArray)
constructor(source: TypedArray)
constructor(values: Array<int>)
```

Create an empty typed array.

### Int32Array.slice

```ts
slice(begin?: int, end?: int): Int32Array
```

A COPY of elements [begin, end) in new storage. Negative indices
count from the end; both clamp to the length.

**Parameters**

- `begin`: Optional starting index; defaults to 0.
- `end`: Optional ending index (exclusive); defaults to length.

**Returns:** A new Int32Array containing the copied elements.

## Uint32Array <Badge type="info" text="class" />

```ts
class Uint32Array extends TypedArray
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Old-grammar declaration for the `FixedArray<uint32>` alias. `new Uint32Array(x)` is compiler-lowered to `__fa_construct`; no runtime global exists.

### new Uint32Array()

```ts
constructor()
constructor(length: int)
constructor(source: ByteArray)
constructor(source: TypedArray)
constructor(values: Array<int>)
```

Create an empty typed array.

### Uint32Array.slice

```ts
slice(begin?: int, end?: int): Uint32Array
```

A COPY of elements [begin, end) in new storage. Negative indices
count from the end; both clamp to the length.

**Parameters**

- `begin`: Optional starting index; defaults to 0.
- `end`: Optional ending index (exclusive); defaults to length.

**Returns:** A new Uint32Array containing the copied elements.

## Float32Array <Badge type="info" text="class" />

```ts
class Float32Array extends TypedArray
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Old-grammar declaration for the `FixedArray<float32>` alias. `new Float32Array(x)` is compiler-lowered to `__fa_construct`; no runtime global exists.

### new Float32Array()

```ts
constructor()
constructor(length: int)
constructor(source: ByteArray)
constructor(source: TypedArray)
constructor(values: Array<float>)
```

Create an empty typed array.

### Float32Array.slice

```ts
slice(begin?: int, end?: int): Float32Array
```

A COPY of elements [begin, end) in new storage. Negative indices
count from the end; both clamp to the length.

**Parameters**

- `begin`: Optional starting index; defaults to 0.
- `end`: Optional ending index (exclusive); defaults to length.

**Returns:** A new Float32Array containing the copied elements.

## Float64Array <Badge type="info" text="class" />

```ts
class Float64Array extends TypedArray
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Old-grammar declaration for the `FixedArray<float64>` alias. `new Float64Array(x)` is compiler-lowered to `__fa_construct`; no runtime global exists.

### new Float64Array()

```ts
constructor()
constructor(length: int)
constructor(source: ByteArray)
constructor(source: TypedArray)
constructor(values: Array<float>)
```

Create an empty typed array.

### Float64Array.slice

```ts
slice(begin?: int, end?: int): Float64Array
```

A COPY of elements [begin, end) in new storage. Negative indices
count from the end; both clamp to the length.

**Parameters**

- `begin`: Optional starting index; defaults to 0.
- `end`: Optional ending index (exclusive); defaults to length.

**Returns:** A new Float64Array containing the copied elements.

---

*Generated from `lang/types/builtin_buffer.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/collections

# Array, Map and Set

The collection types: `Array`, `FixedArray`, `Map`, `Set` and the weak references.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Array <Badge type="info" text="class" />

```ts
class Array<T>
```

Indexed, mutable, ordered. The element type `T` is enforced: a
member call binds `T` to the receiver's element type, so
`a.push("nope")` on an `Array<int>` is a diagnostic and
`a.slice(0, 1)` answers `Array<int>`. Element reads answer `T`,
including indexed reads and the single-element methods below. Like an
out-of-range indexed read, an empty or out-of-range method result is
deliberately typed as `T` even though the runtime returns `undefined`
from `at` / `pop` / `shift` and `null` from `first` / `last` / `sample`.

### Array.length

```ts
readonly length: int
```

Number of elements.

### Array.size

```ts
readonly size: int
```

Alias of `length`. Present so `Array`, `Map`, and `Set` share the collection contract.

### new Array()

```ts
constructor()
constructor(length: int)
constructor(...items: Array<T>)
```

Empty array.

### Array.at

```ts
at(index: int): T
```

Element at `index`. Negative indices count from the end. Runtime result is `undefined` when out of range.

### Array.includes

```ts
includes(searchElement: T): boolean
```

True when `searchElement` is present (uses `===` semantics).

### Array.indexOf

```ts
indexOf(searchElement: T, fromIndex?: int): int
```

Index of the first match, or `-1`. `fromIndex` defaults to `0`.

### Array.lastIndexOf

```ts
lastIndexOf(searchElement: T): int
```

Index of the last match, or `-1`.

### Array.find

```ts
find(callback: Function): any
```

First element matching `callback`, or `undefined`. Callback shape: `(value: T, index: int, array: Array<T>): boolean`.

### Array.findIndex

```ts
findIndex(callback: Function): int
```

Index of the first match, or `-1`. Same callback shape as `find`.

### Array.some

```ts
some(callback: Function): boolean
```

True when at least one element passes `callback`.

### Array.every

```ts
every(callback: Function): boolean
```

True when every element passes `callback`.

### Array.push

```ts
push(...items: Array<T>): int
```

Append items, returns the new length.

**Example**

```ts
const items: int[] = [1, 2];
const length: int = items.push(3, 4);
console.log(length); // 4
```

### Array.pop

```ts
pop(): T
```

Remove and return the last element. Runtime result is `undefined` when empty.

### Array.shift

```ts
shift(): T
```

Remove and return the first element, shifting the rest down. Runtime result is `undefined` when empty.

### Array.unshift

```ts
unshift(...items: Array<T>): int
```

Prepend items, returns the new length.

### Array.fill

```ts
fill(value: T, start?: int, end?: int): Array<T>
```

Fill `[start, end)` with `value` in place. Defaults: `start=0`, `end=length`.

### Array.reverse

```ts
reverse(): Array<T>
```

Reverse in place and return the receiver.

### Array.sort

```ts
sort(compareFn?: Function): Array<T>
```

Sort in place. `compareFn(a, b)` returns negative / zero / positive; default is lexicographic.

### Array.splice

```ts
splice(start: int, deleteCount?: int, ...items: Array<T>): Array<T>
```

Remove `deleteCount` elements at `start`, insert `items` in their place, return the removed slice.

### Array.concat

```ts
concat(...items: Array<T | Array<T>>): Array<T>
```

Shallow copy with `items` and arrays-of-items appended. This matches
JavaScript and TypeScript: when `T` is an array, an array argument
is flattened one level at runtime even though the return is `Array<T>`.

### Array.join

```ts
join(separator?: string): string
```

Join elements with `separator` (default `","`).

### Array.slice

```ts
slice(start?: int, end?: int): Array<T>
```

Shallow copy of `[start, end)`. Negative indices count from the end.

### Array.flat

```ts
flat(): Array<any>
```

One level of nesting flattened. `[[1,2],[3]]` becomes `[1,2,3]`.

### Array.toString

```ts
toString(): string
```

Comma-joined string form.

### Array.forEach

```ts
forEach(callback: Function): void
```

Invoke `callback` for each element. Shape: `(value: T, index: int, array: Array<T>): void`.

### Array.map

```ts
map(callback: Function): Array<any>
```

New array of the results of `callback(value, index, array)`.

### Array.filter

```ts
filter(callback: Function): Array<T>
```

New array of the elements `callback` returned truthy for.

### Array.reduce

```ts
reduce(callback: Function, initialValue?: any): any
```

Fold with `callback(acc, value, index, array)`. `initialValue` seeds the accumulator.

### Array.entries

```ts
entries(): Array<[int, T]>
```

New array of `[index, value]` pairs.

### Array.keys

```ts
keys(): Array<int>
```

New array of indices `[0..length)`.

### Array.values

```ts
values(): Array<T>
```

Shallow copy of the values.

### Array.toArray

```ts
toArray(): Array<T>
```

Self — present so `Array`, `Map`, and `Set` share the collection contract.

### Array.compact

```ts
compact(): Array<T>
```

New array with `null` and `undefined` removed.

### Array.unique

```ts
unique(): Array<T>
```

New array with duplicates removed (uses `===` equality).

### Array.shuffle

```ts
shuffle(): Array<T>
```

New array with the elements in random order. Uses `std::rand()`.

### Array.first

```ts
first(): T
```

First element. Runtime result is `null` when empty.

### Array.last

```ts
last(): T
```

Last element. Runtime result is `null` when empty.

### Array.sample

```ts
sample(): T
```

Random element. Runtime result is `null` when empty. Uses `std::rand()`.

### Array.isEmpty

```ts
isEmpty(): boolean
```

True when `length === 0`.

### Array.sum

```ts
sum(): float
```

Sum of numeric elements. Non-numeric elements are skipped.

### Array.avg

```ts
avg(): float
```

Mean of numeric elements. `NaN` when empty.

## FixedArray <Badge type="info" text="class" />

```ts
class FixedArray<T>
```

`FixedArray<T>`: an array of a number, boolean, char or struct type whose
length is chosen when it is made and never changes. The length is not part
of the type: `new FixedArray<T>(n)` makes `n` zero elements, and a struct
field states its own, `name: FixedArray<char>(24)`.
Checks as an array of `T`; assignment to and from `Array<T>` converts
automatically (a copy), and an out-of-range index or element value raises
`RangeError`. `Uint8Array` ... `Float64Array` are aliases of `FixedArray<uint8>`
... `FixedArray<float64>` (one type, one runtime kind).
Construction and storage rules are in `docs/fixed-array.md`.

### new FixedArray()

```ts
constructor(length: int)
```

`n` zero elements; `RangeError` for a negative or non-integer `n`.

### FixedArray.length

```ts
readonly length: int
```

Number of elements: fixed when the array was made.

### FixedArray.byteLength

```ts
readonly byteLength: int
```

Total size of the elements in bytes.

### FixedArray.fill

```ts
fill(value: T): void
```

Set every element to `value`.

### FixedArray.slice

```ts
slice(begin?: int, end?: int): FixedArray<T>
```

A COPY of elements [begin, end) in new storage. Negative indices count
from the end; both clamp to the length.

### FixedArray.set

```ts
set(source: any, offset?: int): void
```

Copy `source` (an `Array` or another FixedArray) in starting at `offset`
(default 0). `RangeError` when it does not fit, or an element is out of range.

### FixedArray.indexOf

```ts
indexOf(value: T): int
```

Index of the first element equal to `value`, or -1.

### FixedArray.includes

```ts
includes(value: T): boolean
```

True when an element equals `value`.

### FixedArray.toArray

```ts
toArray(): Array<T>
```

A plain `Array<T>` copy of the elements. Packed element storage widens to its value type on read.

### FixedArray.toSet

```ts
toSet(): Set<T>
```

A `Set<T>` of the elements (duplicates collapse). Packed element storage widens to its value type on read.

### FixedArray.textLength

```ts
readonly textLength: int
```

Text rules, `FixedArray<char>` only: the text is the elements up to
the first zero. `length` stays the made length; `textLength` is the text's length.

### FixedArray.left

```ts
left(n: int): Array<T>
```

The first `n` characters, as a char array of the same type.

### FixedArray.right

```ts
right(n: int): Array<T>
```

The last `n` characters, as a char array of the same type.

### FixedArray.mid

```ts
mid(start: int, count: int): Array<T>
```

`count` characters from `start`, as a char array of the same type.

### FixedArray.startsWith

```ts
startsWith(prefix: any): boolean
```

True when the text begins with `prefix` (a string or char array).

### FixedArray.equalsIgnoreCase

```ts
equalsIgnoreCase(other: any): boolean
```

Equality ignoring ASCII case, against a string or char array.

### FixedArray.from

```ts
static from(source: any): Array<any>
```

The explicit spelling of the automatic `Array<T>` to `FixedArray<T>`
conversion. It builds the FixedArray the receiving slot declares, so
it is only valid where one does: `const a: FixedArray<int> = FixedArray.from(arr)`.
`source` may also be a `ByteArray`: its bytes are copied at the element's native
width, little-endian (a whole number of elements, else `RangeError`).

## Map <Badge type="info" text="class" />

```ts
class Map<K, V>
```

Ordered key-value store. Member calls enforce the receiver's `K` and
`V`. `length` is exposed as an alias of `size` for parity with the
rest of the collection family.

### Map.size

```ts
readonly size: int
```

Number of live entries.

### Map.length

```ts
readonly length: int
```

Alias of `size`.

### new Map()

```ts
constructor(entries?: any)
```

Empty map, or one filled from an iterable of `[key, value]` pairs (an `Array` of pairs or another `Map`).

### Map.clear

```ts
clear(): void
```

Remove every entry.

### Map.delete

```ts
delete(key: K): boolean
```

Remove `key`. Returns `true` when an entry was removed.

### Map.remove

```ts
remove(key: K): boolean
```

Alias of `delete`.

### Map.get

```ts
get(key: K): V | undefined
```

Value for `key`, or `undefined`.

**Example**

```ts
const ages: Map<string, int> = new Map<string, int>();
ages.set("ada", 36);
console.log(ages.get("ada")); // 36
```

### Map.has

```ts
has(key: K): boolean
```

True when `key` is present.

### Map.set

```ts
set(key: K, value: V): Map<K, V>
```

Set `key` to `value`. Returns the receiver.

**Example**

```ts
const ages: Map<string, int> = new Map<string, int>();
ages.set("ada", 36).set("alan", 41);
console.log(ages.size); // 2
```

### Map.add

```ts
add(key: K, value: V): Map<K, V>
```

Alias of `set`.

### Map.keys

```ts
keys(): Array<K>
```

Insertion-ordered keys.

### Map.values

```ts
values(): Array<V>
```

Insertion-ordered values.

### Map.entries

```ts
entries(): Array<[K, V]>
```

Insertion-ordered `[key, value]` pairs.

### Map.forEach

```ts
forEach(callback: Function): void
```

Invoke `callback` for each entry. Shape: `(value: V, key: K, map: Map<K, V>): void`.

### Map.toArray

```ts
toArray(): Array<V>
```

Insertion-ordered values. Mirrors the collection contract.

### Map.compact

```ts
compact(): Map<K, V>
```

New map with entries whose value is `null` or `undefined` removed.

### Map.first

```ts
first(): any
```

First inserted value, or `null` when empty.

### Map.last

```ts
last(): any
```

Last inserted value, or `null` when empty.

### Map.sample

```ts
sample(): any
```

Random value, or `null` when empty. Uses `std::rand()`.

### Map.isEmpty

```ts
isEmpty(): boolean
```

True when `size === 0`.

### Map.sum

```ts
sum(): float
```

Sum of numeric values. Non-numeric values are skipped.

### Map.avg

```ts
avg(): float
```

Mean of numeric values. `NaN` when empty.

## Set <Badge type="info" text="class" />

```ts
class Set<T>
```

Insertion-ordered, deduplicated value collection. Includes the
TKS-specific set algebra extensions (`union`, `intersection`,
`difference`, `isSubsetOf`) registered alongside the standard JS
surface.

### Set.size

```ts
readonly size: int
```

Number of live entries.

### Set.length

```ts
readonly length: int
```

Alias of `size`.

### new Set()

```ts
constructor(values?: any)
```

Empty set, or one filled from an iterable of values (an `Array` or another `Set`).

### Set.clear

```ts
clear(): void
```

Remove every value.

### Set.add

```ts
add(value: T): Set<T>
```

Insert `value`. Returns the receiver.

**Example**

```ts
const seen: Set<string> = new Set<string>();
seen.add("a").add("b").add("a");
console.log(seen.size); // 2
```

### Set.set

```ts
set(value: T): Set<T>
```

Alias of `add`.

### Set.delete

```ts
delete(value: T): boolean
```

Remove `value`. Returns `true` when a value was removed.

### Set.remove

```ts
remove(value: T): boolean
```

Alias of `delete`.

### Set.has

```ts
has(value: T): boolean
```

True when `value` is present.

### Set.forEach

```ts
forEach(callback: Function): void
```

Invoke `callback` for each value. Shape: `(value: T, value2: T, set: Set<T>): void`.

### Set.values

```ts
values(): Array<T>
```

Insertion-ordered values.

### Set.toArray

```ts
toArray(): Array<T>
```

Insertion-ordered values. Mirrors the collection contract.

### Set.compact

```ts
compact(): Set<T>
```

New set with `null` and `undefined` removed.

### Set.union

```ts
union(other: Set<T>): Set<T>
```

Values present in either set.

### Set.intersection

```ts
intersection(other: Set<T>): Set<T>
```

Values present in both sets.

### Set.difference

```ts
difference(other: Set<T>): Set<T>
```

Values present in this set but not in `other`.

### Set.isSubsetOf

```ts
isSubsetOf(other: Set<T>): boolean
```

True when every value in this set is also in `other`.

### Set.first

```ts
first(): any
```

First inserted value, or `null` when empty.

### Set.last

```ts
last(): any
```

Last inserted value, or `null` when empty.

### Set.sample

```ts
sample(): any
```

Random value, or `null` when empty. Uses `std::rand()`.

### Set.isEmpty

```ts
isEmpty(): boolean
```

True when `size === 0`.

### Set.sum

```ts
sum(): float
```

Sum of numeric values. Non-numeric values are skipped.

### Set.avg

```ts
avg(): float
```

Mean of numeric values. `NaN` when empty.

## WeakRef <Badge type="info" text="class" />

```ts
class WeakRef<T>
```

JavaScript-compatible weak reference to an object. Constructing the
reference and successfully dereferencing it keep the target alive until
the current job and its Promise microtasks finish.

### WeakRef.deref

```ts
deref(): T | undefined
```

Target while it remains alive, otherwise `undefined`.

### Other members of WeakRef

```ts
constructor(target: T)
```

## WeakMap <Badge type="info" text="class" />

```ts
class WeakMap<K, V>
```

### WeakMap.get

```ts
get(key: K): V | undefined
```

Value for `key`, or `undefined` when absent or already collected.

### WeakMap.set

```ts
set(key: K, value: V): WeakMap<K, V>
```

Set `key` to `value`. Returns the receiver.

### WeakMap.has

```ts
has(key: K): boolean
```

True when `key` is present.

### WeakMap.delete

```ts
delete(key: K): boolean
```

Remove `key`. Returns `true` when an entry was removed.

### Other members of WeakMap

```ts
constructor()
```

## WeakSet <Badge type="info" text="class" />

```ts
class WeakSet<T>
```

Weakly-referencing set. Members are held weakly; entries disappear
when collected. Not iterable and has no `size`, for the same reason
`WeakMap` has neither.

### WeakSet.add

```ts
add(value: T): WeakSet<T>
```

Add `value`. Returns the receiver.

### WeakSet.has

```ts
has(value: T): boolean
```

True when `value` is present.

### WeakSet.delete

```ts
delete(value: T): boolean
```

Remove `value`. Returns `true` when it was removed.

### Other members of WeakSet

```ts
constructor()
```

---

*Generated from `lang/types/builtin_collections.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/color

# Color

The `Color` value type: construct, convert and adjust colors.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Color <Badge type="info" text="struct" />

```ts
struct Color
```

### Color.fromUint

```ts
static fromUint(n: uint): Color
```

A packed 0xRRGGBBAA number.

### Color.fromArgb

```ts
static fromArgb(n: uint): Color
```

A packed 0xAARRGGBB number.

### Color.rgb

```ts
static rgb(r: int, g: int, b: int): Color
```

Red, green and blue bytes (0-255), fully opaque.

**Example**

```ts
const orange: Color = Color.rgb(255, 128, 0);
console.log(orange.r(), orange.g(), orange.b()); // 255 128 0
```

### Color.rgba

```ts
static rgba(r: int, g: int, b: int, a: int): Color
```

Red, green, blue and alpha bytes (0-255).

**Example**

```ts
const glass: Color = Color.rgba(255, 255, 255, 128);
console.log(glass.a()); // 128
```

### Color.rgbaf

```ts
static rgbaf(r: float, g: float, b: float, a: float = 1.0): Color
```

Red, green, blue and alpha as 0-1 floats.

### Color.hex

```ts
static hex(s: string): Color
```

A hex string such as "#ff8800"; throws when it is not one.

**Example**

```ts
const orange: Color = Color.hex("#ff8800");
console.log(orange.r(), orange.g(), orange.b()); // 255 136 0
```

### Color.hsl

```ts
static hsl(h: float, s: float, l: float): Color
```

Hue (degrees), saturation and lightness (0-1), fully opaque.

### Color.hsla

```ts
static hsla(h: float, s: float, l: float, a: float): Color
```

Hue, saturation, lightness and alpha (0-1).

### Color.hsv

```ts
static hsv(h: float, s: float, v: float, a: float = 1.0): Color
```

Hue (degrees), saturation and value (0-1).

### Other members of Color

```ts
value: uint32
static readonly WHITE: Color
static readonly BLACK: Color
static readonly TRANSPARENT: Color
static readonly RED: Color
static readonly GREEN: Color
static readonly BLUE: Color
static readonly YELLOW: Color
static readonly CYAN: Color
static readonly MAGENTA: Color
static readonly GRAY: Color
static readonly ORANGE: Color
static readonly PURPLE: Color
static tryHex(s: string): Color | null
r(): int
g(): int
b(): int
a(): int
rf(): float
gf(): float
bf(): float
af(): float
hue(): float
lightness(): float
saturation(): float
brightness(): float
luminance(): float
contrastRatio(other: Color): float
isDark(): boolean
isLight(): boolean
withR(v: int): Color
withG(v: int): Color
withB(v: int): Color
withA(v: int): Color
withAlpha(v: int): Color
fade(f: float): Color
hueShift(deg: float): Color
complement(): Color
saturate(amt: float): Color
desaturate(amt: float): Color
lighten(amt: float): Color
darken(amt: float): Color
brighten(f: float): Color
mix(other: Color, t: float): Color
lerp(other: Color, t: float): Color
tint(amt: float): Color
shade(amt: float): Color
invert(): Color
grayscale(): Color
premultiplied(): Color
toHex(): string
toHexRGB(): string
toCss(): string
toString(): string
toArgb(): uint
operator eq(other: Color): boolean
```

---

*Generated from `lang/color/index.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/compress

# compress

zlib and gzip deflate and inflate, with streaming helpers.

::: tip Import
```ts
import { Deflater, Inflater, Compress } from "compress";
```
:::

## Deflater <Badge type="info" text="class" />

```ts
class Deflater
```

Streaming deflate. Construct via `Compress.createDeflater(level?)`.
Feed input chunks with `feed`, drain compressed bytes with
`takeOutput`, and call `finish` once when the input is
exhausted. After `finish`, `takeOutput` may still be called
one or more times to drain the tail of the compressed stream.

### Deflater.feed

```ts
feed(data: Buffer | string): void
```

Append `data` to the input stream. Throws if the stream
was already finished. Strings are treated as raw bytes.

### Deflater.finish

```ts
finish(): void
```

Mark the input stream complete and flush any pending
compressed bytes into the output buffer. Throws if
already finished.

### Deflater.isFinished

```ts
isFinished(): boolean
```

True after `finish` has been called and every byte has
been drained via `takeOutput`. Until then, the deflater
is still in mid-stream.

### Deflater.takeOutput

```ts
takeOutput(): Buffer
```

Drain and return the compressed bytes accumulated so far.
The internal buffer is cleared. Returns an empty Buffer
when no output is currently available.

## Inflater <Badge type="info" text="class" />

```ts
class Inflater
```

Streaming inflate. Construct via `Compress.createInflater()`.
Feed compressed chunks with `feed`; drain decompressed bytes
with `takeOutput`. The stream finishes implicitly when the
compressed payload's terminator is reached — there is no
explicit `finish` call, mirroring how zlib's inflate state
machine works.

### Inflater.feed

```ts
feed(data: Buffer | string): void
```

Append `data` to the compressed input stream. Throws an
Error if the stream has already reached its end. Throws a
RangeError if the data is corrupt or the output limit is
exceeded. Strings are treated as raw bytes.

### Inflater.isFinished

```ts
isFinished(): boolean
```

True once the inflater has consumed the compressed
stream's terminator. Further `feed` calls will throw.

### Inflater.takeOutput

```ts
takeOutput(): Buffer
```

Drain and return the decompressed bytes accumulated so
far. The internal buffer is cleared. Returns an empty
Buffer when no output is currently available.

## Compress <Badge type="info" text="static class" />

```ts
static class Compress
```

One-shot zlib / gzip helpers plus factories for the streaming
variants. The class is `static`-only — there are no instances.
The level argument on the compressing helpers is clamped to
the zlib range `0..9` and defaults to `6`. The `maxOutput`
argument on the decompressing helpers caps the output size in
bytes; pass `0` or a negative value (or omit it) for
the default cap of 256 MiB.

### Compress.compress

```ts
static compress(data: Buffer | string, level?: int): Buffer
```

Deflate `data` using zlib framing. Returns the compressed
payload as a Buffer. `level` is clamped to `0..9` and
defaults to `6`.

**Example**

```ts
import { Compress } from "compress";
const packed: Buffer = Compress.compress("aaaaaaaaaaaaaaaaaaaaaaaa");
console.log(packed.length < 24); // true
```

### Compress.createDeflater

```ts
static createDeflater(level?: int): Deflater
```

Construct a streaming `Deflater`. `level` is clamped to
`0..9` and defaults to `6`.

### Compress.createInflater

```ts
static createInflater(maxOutput?: int): Inflater
```

Construct a streaming `Inflater`. `maxOutput` caps the
total decompressed output in bytes; omit, pass `0`, or
pass a negative value for the default cap of 256 MiB.
`feed` throws a RangeError when the cap is exceeded or
when the compressed data is corrupt.

### Compress.decompress

```ts
static decompress(data: Buffer | string, maxOutput?: int): Buffer
```

Inflate zlib-framed `data`. Returns the decompressed
payload as a Buffer. `maxOutput` caps the output in
bytes; omit, pass `0`, or pass a negative value for
the default cap of 256 MiB.

**Example**

```ts
import { Compress } from "compress";
const packed: Buffer = Compress.compress("hello hello hello");
console.log(Compress.decompress(packed).toString()); // hello hello hello
```

### Compress.gzipCompress

```ts
static gzipCompress(data: Buffer | string, level?: int): Buffer
```

Deflate `data` using gzip framing. Returns the compressed
payload as a Buffer. `level` is clamped to `0..9` and
defaults to `6`.

### Compress.gzipDecompress

```ts
static gzipDecompress(data: Buffer | string, maxOutput?: int): Buffer
```

Inflate gzip-framed `data`. Returns the decompressed
payload as a Buffer. `maxOutput` caps the output in
bytes; omit, pass `0`, or pass a negative value for
the default cap of 256 MiB.

---

*Generated from `lang/types/compress.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/console

# console

Leveled logging to stdout and stderr.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## console <Badge type="info" text="class" />

```ts
class console
```

### console.assert

```ts
static assert(condition: any, ...messages: any[]): void
```

Throw-style assertion. When `condition` is falsy, prints
`Assertion failed:` followed by the space-joined `messages`.
When truthy, the call is a no-op. Calling with zero arguments
is treated as a failed assertion with no message.

### console.error

```ts
static error(...args: any[]): void
```

Print one space-joined line prefixed with `ERROR:` to stdout
and capture it as an error-tagged output event.

### console.info

```ts
static info(...args: any[]): void
```

Print one space-joined line to stdout. Behaviourally identical
to `log` today; reserved for informational output that hosts
may route to a separate channel later.

### console.log

```ts
static log(...args: any[]): void
```

Print one space-joined line to stdout and capture it as an
output event. The standard diagnostic entry point.

### console.table

```ts
static table(...args: any[]): void
```

Print a tab-separated tabular dump of the argument. Arrays of
objects render as `(index)` plus one column per field of the
first element; maps render as `Key`/`Value` pairs; instances
render as `Property`/`Value`. Other inputs print their string
form. Calling with zero arguments prints `(empty)`.

### console.time

```ts
static time(label?: string): void
```

Start a named timer. Defaults to the label `"default"` when
omitted. Pair with `timeEnd` to print the elapsed milliseconds.

### console.timeEnd

```ts
static timeEnd(label?: string): void
```

Stop the named timer started by `time` and print
`<label>: <ms>ms` (three decimal places). Defaults to the
label `"default"`. Unknown labels are silently ignored.

### console.warn

```ts
static warn(...args: any[]): void
```

Print one space-joined line prefixed with `WARN:` to stdout
and capture it as a warning-tagged output event.

---

*Generated from `lang/types/builtin_console.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/crypto

# crypto

Hashing, HMAC, AES, PBKDF2, random bytes and UUIDs.

::: tip Import
```ts
import { Crypto } from "crypto";
```

Needs the `"crypto"` permission in `thicket.json`.
:::

## Crypto <Badge type="info" text="static class" />

```ts
static class Crypto
```

### Crypto.MD5

```ts
static readonly MD5: string
```

Algorithm constant for MD5 hashing ("md5"). Warning: MD5 is cryptographically broken; use SHA256/SHA512 for security-sensitive purposes.

### Crypto.SHA1

```ts
static readonly SHA1: string
```

Algorithm constant for SHA-1 hashing ("sha1"). Warning: SHA-1 is weak; use SHA256/SHA512 for security-sensitive purposes.

### Crypto.SHA256

```ts
static readonly SHA256: string
```

Algorithm constant for SHA-256 hashing ("sha256"). Recommended for most uses.

### Crypto.SHA512

```ts
static readonly SHA512: string
```

Algorithm constant for SHA-512 hashing ("sha512"). Recommended for security-sensitive uses.

### Crypto.decrypt

```ts
static decrypt(key: string, iv: string, ciphertext: string): string
```

Decrypt AES-256-CBC ciphertext.

**Parameters**

- `key`: 64 hex characters (32 bytes).
- `iv`: 32 hex characters (16 bytes).
- `ciphertext`: Hex string with length a non-zero multiple of 16 bytes.

**Returns:** The decrypted plaintext string.

### Crypto.encrypt

```ts
static encrypt(key: string, iv: string, plaintext: string | ByteArray): string
```

Encrypt plaintext using AES-256-CBC.

**Parameters**

- `key`: 64 hex characters (32 bytes).
- `iv`: 32 hex characters (16 bytes).
- `plaintext`: A string (encrypted as its UTF-8 bytes) or a ByteArray (whole content, `position` ignored).

**Returns:** The ciphertext as a hex string. Note: AES-CBC provides confidentiality only; always authenticate with HMAC.

### Crypto.hash

```ts
static hash(algorithm: string, data: string | ByteArray): string
```

Compute a hash digest.

**Parameters**

- `algorithm`: Hash algorithm: Crypto.MD5, Crypto.SHA1, Crypto.SHA256, or Crypto.SHA512.
- `data`: The data to hash: a string (hashed as its UTF-8 bytes) or a ByteArray (its whole content; `position` is ignored). Any other type throws TypeError.

**Returns:** The digest as a hex string.

### Crypto.hmac

```ts
static hmac(algorithm: string, key: string | ByteArray, data: string | ByteArray): string
```

Compute an HMAC.

**Parameters**

- `algorithm`: Hash algorithm: Crypto.SHA1, Crypto.SHA256, or Crypto.SHA512. Warning: SHA1-based HMAC is weak.
- `key`: The secret key: a string (UTF-8 bytes) or a ByteArray (whole content, `position` ignored).
- `data`: The data to authenticate: a string (UTF-8 bytes) or a ByteArray (whole content, `position` ignored).

**Returns:** The HMAC as a hex string.

### Crypto.pbkdf2

```ts
static pbkdf2(password: string | ByteArray, salt: any, iterations: int, keyLength: int, digest?: string): any
```

Derive a key from a password using PBKDF2.

**Parameters**

- `password`: A string (UTF-8 bytes) or a ByteArray (whole content, `position` ignored).
- `salt`: Random salt bytes.
- `iterations`: Number of iterations (higher is slower but more secure).
- `keyLength`: Desired output key length in bytes.
- `digest`: Optional hash algorithm: Crypto.SHA256 (default) or Crypto.SHA512.

**Returns:** A buffer containing the derived key bytes.

### Crypto.randomBytes

```ts
static randomBytes(n: int): string
```

Generate cryptographically secure random bytes.

**Parameters**

- `n`: Number of bytes to generate (max 1024).

**Returns:** A hex string (n * 2 characters).

### Crypto.randomUUID

```ts
static randomUUID(): string
```

Generate a UUID v4 string.

**Returns:** A UUID in standard 8-4-4-4-12 format (e.g., "550e8400-e29b-41d4-a716-446655440000").

---

*Generated from `lang/types/crypto.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/database

# database

Database connections: SQLite, MySQL, PostgreSQL, Redis and MongoDB.

::: tip Import
```ts
import { DbError, DbErrorCode, DbTls, DbExecResult, ... } from "database";
```

Needs the `"database"` permission in `thicket.json`.
:::

## DbError <Badge type="info" text="class" />

```ts
class DbError extends Error
```

A database operation or connection failure.

### DbError.code

```ts
readonly code: DbErrorCode
```

Broad, portable classification of the failure.

### DbError.driver

```ts
readonly driver: DatabaseDriver
```

Driver that reported the failure.

### DbError.serverCode

```ts
readonly serverCode: int | string | null
```

Driver/server-specific code when one is available; otherwise null.

## DbErrorCode <Badge type="info" text="enum" />

```ts
enum DbErrorCode
```

Portable database-error classifications.

- `DbErrorCode.DUPLICATE_KEY`
- `DbErrorCode.NETWORK`
- `DbErrorCode.TIMEOUT`
- `DbErrorCode.AUTH`
- `DbErrorCode.WRITE_CONCERN`
- `DbErrorCode.SERVER`
- `DbErrorCode.CONFIG`

## DbTls <Badge type="info" text="enum" />

```ts
enum DbTls
```

TLS policy for server database connections.

- `DbTls.OFF`: Plaintext; the default for localhost and Unix sockets.
- `DbTls.REQUIRE`: Encrypt the connection without validating the server certificate.
- `DbTls.VERIFY`: Encrypt and validate the certificate chain and hostname.

## DbExecResult <Badge type="info" text="class" />

```ts
class DbExecResult
```

### DbExecResult.insertId

```ts
insertId: int
```

The ID of a newly inserted row (driver-dependent).

### DbExecResult.rowsChanged

```ts
rowsChanged: int
```

The number of rows affected by an INSERT, UPDATE, or DELETE.

## DbCursor <Badge type="info" text="class" />

```ts
class DbCursor<T>
```

### DbCursor.fetch

```ts
fetch(n?: int): Promise<T[]>
```

Fetches up to n rows from the cursor.

**Parameters**

- `n`: Maximum number of rows to fetch; default fetches all remaining rows.

**Returns:** A Promise resolving to an array of rows.

### DbCursor.hasMore

```ts
hasMore: boolean
```

True if more rows are available.

### DbCursor.close

```ts
close(): Promise<void>
```

Closes the cursor and frees resources.

**Returns:** A Promise that resolves when the cursor is closed.

## ObjectId <Badge type="info" text="class" />

```ts
class ObjectId
```

BSON ObjectId. Construct one or parse its 24-character hex form.

### new ObjectId()

```ts
constructor()
```

Constructs a new ObjectId.

### ObjectId.parse

```ts
static parse(hex: string): ObjectId
```

Parses a 24-character hexadecimal string into an ObjectId.

**Parameters**

- `hex`: A 24-character hex string.

**Returns:** An ObjectId.

### ObjectId.toString

```ts
toString(): string
```

Converts the ObjectId to its 24-character hexadecimal string representation.

**Returns:** The hex string.

## MongoConnection <Badge type="info" text="class" />

```ts
class MongoConnection
```

### MongoConnection.collection

```ts
collection<T = any>(name: string): MongoCollection<T>
```

Gets or creates a collection by name.

**Parameters**

- `name`: The collection name.

**Returns:** A MongoCollection for the given name.

### MongoConnection.close

```ts
close(): Promise<void>
```

Closes the database connection.

**Returns:** A Promise that resolves when the connection is closed.

### MongoConnection.ping

```ts
ping(): Promise<boolean>
```

Tests the connection to the MongoDB server.

**Returns:** A Promise resolving to true if the connection is active.

## MongoCollection <Badge type="info" text="class" />

```ts
class MongoCollection<T>
```

### MongoCollection.insertOne

```ts
insertOne(document: T): Promise<ObjectId>
```

Inserts a single document.

**Parameters**

- `document`: The document to insert.

**Returns:** A Promise resolving to the inserted document's ObjectId.

### MongoCollection.insertMany

```ts
insertMany(documents: T[]): Promise<ObjectId[]>
```

Inserts multiple documents.

**Parameters**

- `documents`: An array of documents to insert.

**Returns:** A Promise resolving to an array of inserted ObjectIds.

### MongoCollection.findOne

```ts
findOne(filter?: any, options?: any): Promise<T | null>
```

Finds at most one document matching the filter.

**Parameters**

- `filter`: Optional filter query.
- `options`: Optional query options.

**Returns:** A Promise resolving to the found document or null.

### MongoCollection.find

```ts
find(filter?: any, options?: any): Promise<DbCursor<T>>
```

Finds all documents matching the filter.

**Parameters**

- `filter`: Optional filter query.
- `options`: Optional query options.

**Returns:** A Promise resolving to a DbCursor over the results.

### MongoCollection.updateOne

```ts
updateOne(filter: any, update: any): Promise<any>
```

Updates the first document matching the filter.

**Parameters**

- `filter`: The filter query.
- `update`: The update operation.

**Returns:** A Promise resolving to the update result.

### MongoCollection.updateMany

```ts
updateMany(filter: any, update: any): Promise<any>
```

Updates all documents matching the filter.

**Parameters**

- `filter`: The filter query.
- `update`: The update operation.

**Returns:** A Promise resolving to the update result.

### MongoCollection.replaceOne

```ts
replaceOne(filter: any, replacement: T): Promise<any>
```

Replaces the first document matching the filter.

**Parameters**

- `filter`: The filter query.
- `replacement`: The replacement document.

**Returns:** A Promise resolving to the replacement result.

### MongoCollection.deleteOne

```ts
deleteOne(filter: any): Promise<any>
```

Deletes the first document matching the filter.

**Parameters**

- `filter`: The filter query.

**Returns:** A Promise resolving to the deletion result.

### MongoCollection.deleteMany

```ts
deleteMany(filter: any): Promise<any>
```

Deletes all documents matching the filter.

**Parameters**

- `filter`: The filter query.

**Returns:** A Promise resolving to the deletion result.

### MongoCollection.countDocuments

```ts
countDocuments(filter?: any): Promise<int | float>
```

Counts documents matching the filter.

**Parameters**

- `filter`: Optional filter query.

**Returns:** A Promise resolving to the count.

### MongoCollection.createIndex

```ts
createIndex(keys: any, options?: any): Promise<string>
```

Creates an index on the collection.

**Parameters**

- `keys`: An object specifying the indexed fields.
- `options`: Optional index options.

**Returns:** A Promise resolving to the index name.

### MongoCollection.dropIndex

```ts
dropIndex(name: string): Promise<void>
```

Drops an index by name.

**Parameters**

- `name`: The name of the index to drop.

**Returns:** A Promise that resolves when the index is dropped.

### MongoCollection.aggregate

```ts
aggregate(pipeline: any[]): Promise<DbCursor<any>>
```

Executes an aggregation pipeline.

**Parameters**

- `pipeline`: An array of aggregation stages.

**Returns:** A Promise resolving to a DbCursor over the results.

## DbConnection <Badge type="info" text="class" />

```ts
class DbConnection
```

### DbConnection.begin

```ts
begin(): any
```

Begins a transaction.

**Returns:** A transaction object, or undefined if already in a transaction.

### DbConnection.close

```ts
close(): Promise<void>
```

Closes the database connection.

**Returns:** A Promise that resolves when the connection is closed.

### DbConnection.commit

```ts
commit(): any
```

Commits the active transaction.

**Returns:** A Promise that resolves when the transaction is committed.

### DbConnection.execute

```ts
execute(sql: string, params?: any): any
```

Executes a statement without returning rows.

**Parameters**

- `sql`: The SQL statement.
- `params`: Optional query parameters.

**Returns:** A Promise resolving to a DbExecResult.

### DbConnection.ping

```ts
ping(): any
```

Tests the connection to the database server.

**Returns:** A Promise resolving to true if the connection is active.

### DbConnection.query

```ts
query(sql: string, params?: any): any
```

Executes a query and returns all rows.

**Parameters**

- `sql`: The SQL query.
- `params`: Optional query parameters.

**Returns:** A Promise resolving to an array of rows.

### DbConnection.queryCursor

```ts
queryCursor(sql: string, params?: any): Promise<DbCursor<any>>
```

Executes a query and returns a cursor over the results.

**Parameters**

- `sql`: The SQL query.
- `params`: Optional query parameters.

**Returns:** A Promise resolving to a DbCursor.

### DbConnection.queryRow

```ts
queryRow(sql: string, params?: any): any
```

Executes a query and returns the first row.

**Parameters**

- `sql`: The SQL query.
- `params`: Optional query parameters.

**Returns:** A Promise resolving to the first row object, or null.

### DbConnection.queryScalar

```ts
queryScalar(sql: string, params?: any): any
```

Executes a query and returns a single scalar value.

**Parameters**

- `sql`: The SQL query.
- `params`: Optional query parameters.

**Returns:** A Promise resolving to the scalar value.

### DbConnection.rollback

```ts
rollback(): any
```

Rolls back the active transaction.

**Returns:** A Promise that resolves when the transaction is rolled back.

## RedisConnection <Badge type="info" text="class" />

```ts
class RedisConnection
```

### RedisConnection.close

```ts
close(): any
```

Closes the Redis connection.

**Returns:** A Promise that resolves when the connection is closed.

### RedisConnection.decr

```ts
decr(key: string): any
```

Decrements a numeric counter by 1.

**Parameters**

- `key`: The counter key.

**Returns:** A Promise resolving to the new value.

### RedisConnection.decrby

```ts
decrby(key: string, amount: int): any
```

Decrements a numeric counter by the given amount.

**Parameters**

- `key`: The counter key.
- `amount`: The decrement amount.

**Returns:** A Promise resolving to the new value.

### RedisConnection.del

```ts
del(...keys: string[]): any
```

Deletes one or more keys.

**Parameters**

- `keys`: The keys to delete.

**Returns:** A Promise resolving to the number of keys deleted.

### RedisConnection.exists

```ts
exists(key: string): any
```

Checks if a key exists.

**Parameters**

- `key`: The key to check.

**Returns:** A Promise resolving to 1 if the key exists, 0 otherwise.

### RedisConnection.expire

```ts
expire(key: string, seconds: int): any
```

Sets a key expiration timeout.

**Parameters**

- `key`: The key.
- `seconds`: Time to live in seconds.

**Returns:** A Promise resolving to 1 if the timeout was set.

### RedisConnection.get

```ts
get(key: string): any
```

Gets the value of a string key.

**Parameters**

- `key`: The key.

**Returns:** A Promise resolving to the string value, or null if not found.

### RedisConnection.hdel

```ts
hdel(key: string, field: string): any
```

Removes a field from a hash.

**Parameters**

- `key`: The hash key.
- `field`: The field name.

**Returns:** A Promise resolving to the number of fields removed.

### RedisConnection.hexists

```ts
hexists(key: string, field: string): any
```

Checks if a field exists in a hash.

**Parameters**

- `key`: The hash key.
- `field`: The field name.

**Returns:** A Promise resolving to 1 if the field exists, 0 otherwise.

### RedisConnection.hget

```ts
hget(key: string, field: string): any
```

Gets a field value from a hash.

**Parameters**

- `key`: The hash key.
- `field`: The field name.

**Returns:** A Promise resolving to the field value, or null if not found.

### RedisConnection.hgetall

```ts
hgetall(key: string): any
```

Gets all fields and values from a hash.

**Parameters**

- `key`: The hash key.

**Returns:** A Promise resolving to an object of field-value pairs.

### RedisConnection.hset

```ts
hset(key: string, field: string, value: string): any
```

Sets a field value in a hash.

**Parameters**

- `key`: The hash key.
- `field`: The field name.
- `value`: The field value.

**Returns:** A Promise resolving to the number of fields added.

### RedisConnection.incr

```ts
incr(key: string): any
```

Increments a numeric counter by 1.

**Parameters**

- `key`: The counter key.

**Returns:** A Promise resolving to the new value.

### RedisConnection.incrby

```ts
incrby(key: string, amount: int): any
```

Increments a numeric counter by the given amount.

**Parameters**

- `key`: The counter key.
- `amount`: The increment amount.

**Returns:** A Promise resolving to the new value.

### RedisConnection.llen

```ts
llen(key: string): any
```

Gets the length of a list.

**Parameters**

- `key`: The list key.

**Returns:** A Promise resolving to the list length.

### RedisConnection.lpop

```ts
lpop(key: string): any
```

Removes and returns the first element of a list.

**Parameters**

- `key`: The list key.

**Returns:** A Promise resolving to the removed value, or null if the list is empty.

### RedisConnection.lpush

```ts
lpush(key: string, value: string): any
```

Pushes a value to the front of a list.

**Parameters**

- `key`: The list key.
- `value`: The value to push.

**Returns:** A Promise resolving to the new list length.

### RedisConnection.lrange

```ts
lrange(key: string, start: int, stop: int): any
```

Gets a range of elements from a list.

**Parameters**

- `key`: The list key.
- `start`: The start index (inclusive).
- `stop`: The stop index (inclusive).

**Returns:** A Promise resolving to an array of list elements.

### RedisConnection.ping

```ts
ping(): any
```

Tests the connection to the Redis server.

**Returns:** A Promise resolving to "PONG" if the connection is active.

### RedisConnection.publish

```ts
publish(channel: string, message: string): any
```

Publishes a message to a channel.

**Parameters**

- `channel`: The channel name.
- `message`: The message text.

**Returns:** A Promise resolving to the number of subscribers that received the message.

### RedisConnection.rpop

```ts
rpop(key: string): any
```

Removes and returns the last element of a list.

**Parameters**

- `key`: The list key.

**Returns:** A Promise resolving to the removed value, or null if the list is empty.

### RedisConnection.rpush

```ts
rpush(key: string, value: string): any
```

Pushes a value to the back of a list.

**Parameters**

- `key`: The list key.
- `value`: The value to push.

**Returns:** A Promise resolving to the new list length.

### RedisConnection.sadd

```ts
sadd(key: string, ...members: string[]): any
```

Adds members to a set.

**Parameters**

- `key`: The set key.
- `members`: The members to add.

**Returns:** A Promise resolving to the number of members added.

### RedisConnection.scard

```ts
scard(key: string): any
```

Gets the cardinality (size) of a set.

**Parameters**

- `key`: The set key.

**Returns:** A Promise resolving to the set size.

### RedisConnection.set

```ts
set(key: string, value: string, opts?: any): any
```

Sets a string value with optional options.

**Parameters**

- `key`: The key.
- `value`: The string value.
- `opts`: Optional set options.

**Returns:** A Promise resolving to "OK" on success.

### RedisConnection.sismember

```ts
sismember(key: string, member: string): any
```

Checks if a member is in a set.

**Parameters**

- `key`: The set key.
- `member`: The member.

**Returns:** A Promise resolving to 1 if the member exists, 0 otherwise.

### RedisConnection.smembers

```ts
smembers(key: string): any
```

Gets all members of a set.

**Parameters**

- `key`: The set key.

**Returns:** A Promise resolving to an array of set members.

### RedisConnection.srem

```ts
srem(key: string, member: string): any
```

Removes a member from a set.

**Parameters**

- `key`: The set key.
- `member`: The member to remove.

**Returns:** A Promise resolving to the number of members removed.

### RedisConnection.subscribe

```ts
subscribe(channel: string, callback: any): any
```

Subscribes to a channel for messages.

**Parameters**

- `channel`: The channel name.
- `callback`: A function called with each message.

**Returns:** A subscription object that can be unsubscribed.

### RedisConnection.ttl

```ts
ttl(key: string): any
```

Gets the remaining time to live for a key in seconds.

**Parameters**

- `key`: The key.

**Returns:** A Promise resolving to the TTL, or -1 if the key has no expiration.

### RedisConnection.unsubscribe

```ts
unsubscribe(channel: string): any
```

Unsubscribes from a channel.

**Parameters**

- `channel`: The channel name.

**Returns:** A Promise that resolves when the unsubscription is complete.

## Database <Badge type="info" text="static class" />

```ts
static class Database
```

### Database.getConnection

```ts
static getConnection(name: string): any
```

Gets a registered database connection by name.

**Parameters**

- `name`: The connection name.

**Returns:** A MongoConnection, DbConnection, or RedisConnection depending on the driver.

### Database.registerConnection

```ts
static registerConnection(name: string, driver: DatabaseDriver, config: any): any
```

Registers a new database connection.

**Parameters**

- `name`: The connection name for later retrieval.
- `driver`: The database driver (SQLITE, MYSQL, POSTGRES, MONGO, REDIS).
- `config`: Driver-specific configuration object.

**Returns:** A Promise that resolves when the connection is established.

**Example**

```ts
import { Database, DatabaseDriver } from "database";
await Database.registerConnection("main", DatabaseDriver.SQLITE, { path: "app.db" });
const db: any = Database.getConnection("main");
```

## DatabaseDriver <Badge type="info" text="enum" />

```ts
enum DatabaseDriver
```

- `DatabaseDriver.SQLITE`
- `DatabaseDriver.MYSQL`: Included in Linux release builds.
- `DatabaseDriver.REDIS`
- `DatabaseDriver.POSTGRES`: Included in Linux release builds.
- `DatabaseDriver.MONGO`: Included only when TKS_ENABLE_DB and HEARTWOOD_ENABLE_MONGO are enabled; not included in release builds.

---

*Generated from `lang/types/database.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/date

# Date and Duration

Dates, times, time zones and durations.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Duration <Badge type="info" text="struct" />

```ts
struct Duration
```

### Duration.make

```ts
static make(t: float): Duration
```

Internal: the raw constructor (a struct literal must live inside its own struct).

### Duration.days

```ts
get days(): float
```

Whole days, floor (the part of `us` that is a multiple of a day).

### Duration.micros

```ts
get micros(): float
```

Microseconds into that day, 0..86,399,999,999.

### Duration.ofMicros

```ts
static ofMicros(n: float): Duration
```

A number of microseconds.

### Duration.ofMs

```ts
static ofMs(n: float): Duration
```

A number of milliseconds.

### Duration.ofSeconds

```ts
static ofSeconds(n: float): Duration
```

A number of seconds.

### Duration.ofMinutes

```ts
static ofMinutes(n: float): Duration
```

A number of minutes.

### Duration.ofHours

```ts
static ofHours(n: float): Duration
```

A number of hours.

### Duration.ofDays

```ts
static ofDays(n: float): Duration
```

A number of days.

### Duration.ofWeeks

```ts
static ofWeeks(n: float): Duration
```

A number of weeks.

### Duration.parse

```ts
static parse(s: string): Duration
```

A duration text such as "1h30m"; throws RangeError when it is not one.

### Other members of Duration

```ts
us: float
static x_mkDur(days: float, us: float): Duration
static x_durFromMicros(us: float): Duration
static x_parseDurationText(s0: string): Duration | null
static readonly zero: Duration
static tryParse(s: string): Duration | null
get totalMicros(): float
get totalMs(): float
get totalSeconds(): float
get totalMinutes(): float
get totalHours(): float
get totalDays(): float
get totalWeeks(): float
get isNegative(): boolean
get isZero(): boolean
absParts(): Array<float>
signOf(v: float): float
get dayPart(): float
get hourPart(): float
get minutePart(): float
get secondPart(): float
get msPart(): float
get usPart(): float
plus(o: Duration): Duration
minus(o: Duration): Duration
times(k: float): Duration
over(k: float): Duration
negated(): Duration
absolute(): Duration
adopt(o: Duration): Duration
add(o: Duration): Duration
subtract(o: Duration): Duration
multiply(k: float): Duration
divide(k: float): Duration
negate(): Duration
abs(): Duration
round(unit: string): Duration
truncate(unit: string): Duration
rounded(unit: string, mode: int): Duration
compare(o: Duration): int
equals(o: Duration): boolean
toString(): string
toJSON(): string
format(pattern: string): string
operator lt(o: Duration): boolean
operator lte(o: Duration): boolean
operator gt(o: Duration): boolean
operator gte(o: Duration): boolean
operator eq(o: Duration): boolean
```

## Date <Badge type="info" text="struct" />

```ts
struct Date
```

### Date.make

```ts
static make(t: float, off: int, zone: int): Date
```

Internal: the raw constructor (a struct literal must live inside its own struct).

### Date.epochDay

```ts
get epochDay(): float
```

Floor days since 1970-01-01 of the instant.

### Date.microsOfDay

```ts
get microsOfDay(): float
```

Microseconds into that UTC day, 0..86,399,999,999.

### Date.nowMs

```ts
static nowMs(): float
```

Epoch milliseconds as a number (the JS `Date.now()`); `Date.now()` is the Date.

**Example**

```ts
const started: float = Date.nowMs();
console.log(Date.nowMs() >= started); // true
```

### Date.now

```ts
static now(): Date
```

The current time, shown in the local zone.

**Example**

```ts
const stamp: Date = Date.now();
console.log(stamp.year >= 2026); // true
```

### Date.today

```ts
static today(): Date
```

Midnight at the start of today, in the local zone.

### Date.fromEpochMicros

```ts
static fromEpochMicros(us: float): Date
```

Epoch microseconds.

### Date.fromEpochMs

```ts
static fromEpochMs(ms: float): Date
```

Epoch milliseconds.

### Date.fromEpochSeconds

```ts
static fromEpochSeconds(s: float): Date
```

Epoch seconds.

### Date.from

```ts
static from(y: int, mo: int, d: int, h: int = 0, mi: int = 0, s: int = 0, ms: int = 0, zone: any = "local"): Date
```

Calendar fields, with an optional zone as the last argument.

### Date.utc

```ts
static utc(y: int, mo: int, d: int, h: int = 0, mi: int = 0, s: int = 0, ms: int = 0): Date
```

Calendar fields read as UTC.

### Date.parse

```ts
static parse(s: string): Date
```

A date string; throws RangeError when it is not a date.

### Date.parseFormat

```ts
static parseFormat(s: string, pattern: string, zone: any = "local"): Date
```

A string in a `format` pattern; throws RangeError on a mismatch.
 Fields the pattern lacks default to 1970-01-01 00:00:00 in `zone`.

### Date.epochMicrosExact

```ts
get epochMicrosExact(): float
```

Float alias for epoch microseconds. Exact to 1 us only within about +-285 years (2^53 us).

### Date.fromEpochMicrosExact

```ts
static fromEpochMicrosExact(t: float): Date
```

Float alias constructor. Exact to 1 us only within about +-285 years; RangeError outside the int64-us range.

### Date.isZoneResolved

```ts
get isZoneResolved(): boolean
```

False when the zone name came from a loaded value and the tz database does not know it.

### Date.addYears

```ts
addYears(n: float, mode: string = "clamp"): Date
```

`mode` "clamp" (default: Jan 31 + 1 month = Feb 28/29) or "overflow" (rolls: Mar 3).

### Date.modify

```ts
modify(relative: string): Date
```

Mutates by a relative phrase ("+1 week", "tomorrow", "next monday", "first day of next month", "noon", "2 days ago"); an unknown word throws.

### Date.nextTransition

```ts
nextTransition(): Date | null
```

The next / previous DST or offset change in this Date's zone (null for a fixed offset or a zone without changes).

### Date.toZone

```ts
toZone(zone: any): Date
```

Same instant, shown in another zone.

### Date.withZoneKeepLocal

```ts
withZoneKeepLocal(zone: any): Date
```

Same wall-clock reading in another zone (the instant changes).

### Date.diffIn

```ts
diffIn(o: Date, unit: string): int
```

Whole `unit`s from `o` to this, truncated toward zero (elapsed, not boundaries crossed).

### Date.diffBoundaries

```ts
diffBoundaries(o: Date, unit: string): int
```

Calendar boundaries of `unit` crossed between `o` and this (VB DateDiff).

### Other members of Date

```ts
utcUs: float
offMin: int16
zoneId: uint16
static x_mk(day: float, us: float, off: int, zone: int): Date
static x_calendarAddMonths(d: Date, months: float, overflow: boolean = false): Date
static x_addUnit(d: Date, n0: float, unit: string, overflow: boolean = false): Date
static x_epochSecOf(d: Date): float
static x_wallDayOf(d: Date): float
static x_wallUsOf(d: Date): float
static x_reoffset(day: float, us: float, zone: int, fixedOff: int): Date
static x_fromWall(wallDay: float, wallUs: float, fixedOff: int, zone: int): Date
static x_addDuration(d: Date, du: Duration): Date
static x_startOfUnit(d: Date, unit: string, weekStart: int): Date
static x_setWall(d: Date, y: float, mo: float, dd: float, h: float, mi: float, s: float, us: float): Date
static x_weekInfo(d: Date): Array<float>
static x_zoneNameOf(d: Date): string
static x_abbrOf(d: Date): string
static x_formatDate(d: Date, pattern: string): string
static x_isoText(d: Date, digits: int): string
static x_parseIso(s0: string): Date | null
static x_parseRfc(s0: string): Date | null
static x_addWeekdaysOf(d: Date, n: int): Date
static x_nextWeekdayOf(d: Date, dow: int): Date
static x_prevWeekdayOf(d: Date, dow: int): Date
static x_modify(d0: Date, text: string): Date
static x_parseFormat(s: string, pattern: string, zone: any): Date | null
static x_transition(d: Date, dir: int): Date | null
static x_parseAny(s: string): Date | null
static readonly ISO: string
static readonly RFC3339: string
static readonly RFC2822: string
static readonly HTTP: string
static readonly DATE: string
static readonly TIME: string
static readonly DATETIME: string
static readonly KITCHEN: string
static readonly LONG_DATE: string
static readonly SHORT_DATE: string
static readonly LONG_TIME: string
static readonly SHORT_TIME: string
static readonly GENERAL: string
static readonly epoch: Date
static nowMicros(): float
static tryParse(s: string): Date | null
static tryParseFormat(s: string, pattern: string, zone: any = "local"): Date | null
static since(d: Date): Duration
static until(d: Date): Duration
static isLeapYear(y: int): boolean
static monthLength(y: int, m: int): int
static dayName(n: int): string
static monthName(n: int): string
static compareDates(a: Date, b: Date): int
static min(a: Date, b: Date): Date
static max(a: Date, b: Date): Date
static zones(): Array<string>
static localZone(): string
static isValidZone(name: string): boolean
static offsetAt(zone: string, instant: Date): int
get epochMicros(): float
get epochMs(): float
get epochSeconds(): float
get year(): int
get month(): int
get day(): int
get hour(): int
get minute(): int
get second(): int
get ms(): int
get us(): int
get microsOfSecond(): int
get dayOfWeek(): int
get dayOfWeekSun(): int
get dayOfYear(): int
get weekOfYear(): int
get isoYear(): int
get quarter(): int
get daysInMonth(): int
get daysInYear(): int
get inLeapYear(): boolean
get offsetMinutes(): int
get offset(): string
get zone(): string
get zoneAbbr(): string
get isDST(): boolean
get isUTC(): boolean
get isWeekend(): boolean
get isToday(): boolean
toOffsetOf(o: Date): Date
adopt(o: Date): Date
copy(): Date
addQuarters(n: float, mode: string = "clamp"): Date
addMonths(n: float, mode: string = "clamp"): Date
addWeeks(n: float): Date
addDays(n: float): Date
addHours(n: float): Date
addMinutes(n: float): Date
addSeconds(n: float): Date
addMs(n: float): Date
addMicros(n: float): Date
addWeekdays(n: int): Date
plusRelative(relative: string): Date
prevTransition(): Date | null
add(du: Duration): Date
subtract(du: Duration): Date
addUnit(n: float, unit: string, mode: string = "clamp"): Date
plus(du: Duration): Date
minus(du: Duration): Date
plusUnit(n: float, unit: string, mode: string = "clamp"): Date
minusUnit(n: float, unit: string, mode: string = "clamp"): Date
setYear(y: int, mo: int = 0, d: int = 0): Date
setMonth(mo: int, d: int = 0): Date
setDay(d: int): Date
setDate(y: int, mo: int, d: int): Date
setHour(h: int, mi: int = -1, s: int = -1, ms: int = -1): Date
setMinute(mi: int, s: int = -1, ms: int = -1): Date
setSecond(s: int, ms: int = -1): Date
setMs(ms: int): Date
setMicros(us: int): Date
setTime(h: int, mi: int = 0, s: int = 0, ms: int = 0): Date
setEpochMs(ms: float): Date
setEpochMicros(us: float): Date
withYear(n: int): Date
withMonth(n: int): Date
withDay(n: int): Date
withHour(n: int): Date
withMinute(n: int): Date
withSecond(n: int): Date
withMs(n: int): Date
withMicros(n: int): Date
toUTC(): Date
toLocal(): Date
toOffset(off: any): Date
compare(o: Date): int
equals(o: Date): boolean
isBefore(o: Date): boolean
isAfter(o: Date): boolean
isBetween(a: Date, b: Date): boolean
isSame(o: Date, unit: string): boolean
diff(o: Date): Duration
diffMs(o: Date): float
diffMicros(o: Date): float
age(): Duration
startOf(unit: string, weekStart: int = 1): Date
endOf(unit: string, weekStart: int = 1): Date
round(unit: string): Date
firstDayOfMonth(): Date
lastDayOfMonth(): Date
nextWeekday(dow: int): Date
prevWeekday(dow: int): Date
nthWeekdayOfMonth(n: int, dow: int): Date
format(pattern: string, zone: any = null): string
toISO(digits: int = 3): string
toString(): string
toJSON(): string
toDateString(): string
toTimeString(): string
toUTCString(): string
toUnix(): float
operator lt(o: Date): boolean
operator lte(o: Date): boolean
operator gt(o: Date): boolean
operator gte(o: Date): boolean
operator eq(o: Date): boolean
```

---

*Generated from `lang/date/index.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/ease

# Ease

Easing curves for animation and tweens.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Ease <Badge type="info" text="class" />

```ts
class Ease
```

### Ease.LINEAR

```ts
static readonly LINEAR: int
```

No easing: constant velocity.

### Ease.IN_QUAD

```ts
static readonly IN_QUAD: int
```

Quadratic (t^2) ease-in: starts slow, accelerates.

### Ease.OUT_QUAD

```ts
static readonly OUT_QUAD: int
```

Quadratic (t^2) ease-out: starts fast, decelerates.

### Ease.IN_OUT_QUAD

```ts
static readonly IN_OUT_QUAD: int
```

Quadratic (t^2) ease-in-out: slow at both ends.

### Ease.OUT_IN_QUAD

```ts
static readonly OUT_IN_QUAD: int
```

Quadratic (t^2) composed out then in across the two halves.

### Ease.IN_CUBIC

```ts
static readonly IN_CUBIC: int
```

Cubic (t^3) ease-in: starts slow, accelerates.

### Ease.OUT_CUBIC

```ts
static readonly OUT_CUBIC: int
```

Cubic (t^3) ease-out: starts fast, decelerates.

### Ease.IN_OUT_CUBIC

```ts
static readonly IN_OUT_CUBIC: int
```

Cubic (t^3) ease-in-out: slow at both ends.

### Ease.OUT_IN_CUBIC

```ts
static readonly OUT_IN_CUBIC: int
```

Cubic (t^3) composed out then in across the two halves.

### Ease.IN_QUART

```ts
static readonly IN_QUART: int
```

Quartic (t^4) ease-in: starts slow, accelerates.

### Ease.OUT_QUART

```ts
static readonly OUT_QUART: int
```

Quartic (t^4) ease-out: starts fast, decelerates.

### Ease.IN_OUT_QUART

```ts
static readonly IN_OUT_QUART: int
```

Quartic (t^4) ease-in-out: slow at both ends.

### Ease.OUT_IN_QUART

```ts
static readonly OUT_IN_QUART: int
```

Quartic (t^4) composed out then in across the two halves.

### Ease.IN_QUINT

```ts
static readonly IN_QUINT: int
```

Quintic (t^5) ease-in: starts slow, accelerates.

### Ease.OUT_QUINT

```ts
static readonly OUT_QUINT: int
```

Quintic (t^5) ease-out: starts fast, decelerates.

### Ease.IN_OUT_QUINT

```ts
static readonly IN_OUT_QUINT: int
```

Quintic (t^5) ease-in-out: slow at both ends.

### Ease.OUT_IN_QUINT

```ts
static readonly OUT_IN_QUINT: int
```

Quintic (t^5) composed out then in across the two halves.

### Ease.IN_SINE

```ts
static readonly IN_SINE: int
```

Sinusoidal ease-in: starts slow, accelerates.

### Ease.OUT_SINE

```ts
static readonly OUT_SINE: int
```

Sinusoidal ease-out: starts fast, decelerates.

### Ease.IN_OUT_SINE

```ts
static readonly IN_OUT_SINE: int
```

Sinusoidal ease-in-out: slow at both ends.

### Ease.OUT_IN_SINE

```ts
static readonly OUT_IN_SINE: int
```

Sinusoidal composed out then in across the two halves.

### Ease.IN_EXPO

```ts
static readonly IN_EXPO: int
```

Exponential ease-in: starts slow, accelerates.

### Ease.OUT_EXPO

```ts
static readonly OUT_EXPO: int
```

Exponential ease-out: starts fast, decelerates.

### Ease.IN_OUT_EXPO

```ts
static readonly IN_OUT_EXPO: int
```

Exponential ease-in-out: slow at both ends.

### Ease.OUT_IN_EXPO

```ts
static readonly OUT_IN_EXPO: int
```

Exponential composed out then in across the two halves.

### Ease.IN_CIRC

```ts
static readonly IN_CIRC: int
```

Circular ease-in: starts slow, accelerates.

### Ease.OUT_CIRC

```ts
static readonly OUT_CIRC: int
```

Circular ease-out: starts fast, decelerates.

### Ease.IN_OUT_CIRC

```ts
static readonly IN_OUT_CIRC: int
```

Circular ease-in-out: slow at both ends.

### Ease.OUT_IN_CIRC

```ts
static readonly OUT_IN_CIRC: int
```

Circular composed out then in across the two halves.

### Ease.IN_BACK

```ts
static readonly IN_BACK: int
```

Overshooting back ease-in: starts slow, accelerates.

### Ease.OUT_BACK

```ts
static readonly OUT_BACK: int
```

Overshooting back ease-out: starts fast, decelerates.

### Ease.IN_OUT_BACK

```ts
static readonly IN_OUT_BACK: int
```

Overshooting back ease-in-out: slow at both ends.

### Ease.OUT_IN_BACK

```ts
static readonly OUT_IN_BACK: int
```

Overshooting back composed out then in across the two halves.

### Ease.IN_ELASTIC

```ts
static readonly IN_ELASTIC: int
```

Elastic ease-in: starts slow, accelerates.

### Ease.OUT_ELASTIC

```ts
static readonly OUT_ELASTIC: int
```

Elastic ease-out: starts fast, decelerates.

### Ease.IN_OUT_ELASTIC

```ts
static readonly IN_OUT_ELASTIC: int
```

Elastic ease-in-out: slow at both ends.

### Ease.OUT_IN_ELASTIC

```ts
static readonly OUT_IN_ELASTIC: int
```

Elastic composed out then in across the two halves.

### Ease.IN_BOUNCE

```ts
static readonly IN_BOUNCE: int
```

Bounce ease-in: starts slow, accelerates.

### Ease.OUT_BOUNCE

```ts
static readonly OUT_BOUNCE: int
```

Bounce ease-out: starts fast, decelerates.

### Ease.IN_OUT_BOUNCE

```ts
static readonly IN_OUT_BOUNCE: int
```

Bounce ease-in-out: slow at both ends.

### Ease.OUT_IN_BOUNCE

```ts
static readonly OUT_IN_BOUNCE: int
```

Bounce composed out then in across the two halves.

### Ease.apply

```ts
static apply(ease: int, t: float): float
```

The eased fraction of curve `ease` at `t`. `t` is clamped to 0..1, so `apply(c, 0)` is 0 and
`apply(c, 1)` is 1 for every curve; back and elastic overshoot in between. An unknown id is linear.

**Example**

```ts
console.log(Ease.apply(Ease.LINEAR, 0.5)); // 0.5
```

---

*Generated from `lang/ease/index.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/env

# env

Environment variables.

::: tip Import
```ts
import { Env } from "env";
```

Needs the `"env"` permission in `thicket.json`.
:::

## Env <Badge type="info" text="static class" />

```ts
static class Env
```

### Env.delete

```ts
static delete(name: string): void
```

Remove an environment variable.

**Parameters**

- `name`: The name of the variable to delete.

### Env.entries

```ts
static entries(): any
```

Get all environment variables as an array of [key, value] pairs.

**Returns:** An array of [name, value] tuples.

### Env.get

```ts
static get(name: string): any
```

Get an environment variable value.

**Parameters**

- `name`: The name of the variable.

**Returns:** The variable's value, or null if not set.

**Example**

```ts
import { Env } from "env";
const home: any = Env.get("HOME");
console.log(home != null); // true
```

### Env.has

```ts
static has(name: string): boolean
```

Check whether an environment variable is set.

**Parameters**

- `name`: The name of the variable.

**Returns:** true if the variable exists, false otherwise.

**Example**

```ts
import { Env } from "env";
if (Env.has("HOME")) {
    console.log("HOME is set");
}
```

### Env.keys

```ts
static keys(): any
```

Get all environment variable names.

**Returns:** An array of variable names.

### Env.set

```ts
static set(name: string, value: string): void
```

Set an environment variable.

**Parameters**

- `name`: The name of the variable.
- `value`: The value to set.

---

*Generated from `lang/types/env.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/errors

# Errors

The built-in error classes.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Error <Badge type="info" text="class" />

```ts
class Error
```

Base error class. Throwing any value works, but `Error` is the
conventional carrier for human-readable failures: it captures the
call stack at construction and renders cleanly in `console.error`.

`message` is the user-supplied description. `name` is `"Error"`
(overridden by each subclass). `stack` is a multi-line trace
captured at construction, prefixed with `name: message`.

### Error.message

```ts
message: string
```

Human-readable description passed to the constructor.

### Error.name

```ts
readonly name: string
```

Class name. `"Error"` for the base, overridden per subclass.

### Error.stack

```ts
readonly stack: string
```

Multi-line stack trace captured at construction time.

### new Error()

```ts
constructor(message?: string)
```

Construct an error with an optional message.

## TypeError <Badge type="info" text="class" />

```ts
class TypeError extends Error
```

Thrown when a value is not of the expected type. Idiomatic for
argument validation in user code; the runtime itself raises
`TypeError` for things like calling a non-callable or indexing a
non-collection.

```ts
constructor(message?: string)
```

## RangeError <Badge type="info" text="class" />

```ts
class RangeError extends Error
```

Thrown when a numeric or collection value is outside the legal
range. The runtime emits `RangeError` for integer overflow,
division by zero, out-of-range numeric conversions, and stdlib
helpers like `Random.nextInt(min, max)` when `min > max`.

```ts
constructor(message?: string)
```

## SyntaxError <Badge type="info" text="class" />

```ts
class SyntaxError extends Error
```

Thrown when a value cannot be parsed as valid syntax. Most often
surfaced by `JSON.parse` and other text-format readers. The
ThicketScript parser itself reports source-level syntax errors as
compiler diagnostics, not runtime exceptions.

```ts
constructor(message?: string)
```

## ReferenceError <Badge type="info" text="class" />

```ts
class ReferenceError extends Error
```

Thrown when a referenced binding does not exist. Raised by the VM
for unresolved global lookups; user code may throw it to flag a
missing key or handler by name.

```ts
constructor(message?: string)
```

## PermissionError <Badge type="info" text="class" />

```ts
class PermissionError extends Error
```

Thrown by a native system call when its required root-project
permission is absent. The message names the permission and explains
the `thicket.json` grant needed to enable it.

```ts
constructor(message?: string)
```

## AggregateError <Badge type="info" text="class" />

```ts
class AggregateError extends Error
```

Bundles multiple errors under one exception. Emitted by
`Promise.any` when every input rejects, and constructable directly
to report a batch of failures from parallel work.

`errors` holds the individual rejection reasons in input order;
`message` is the combined description; `name` is always
`"AggregateError"`.

### AggregateError.errors

```ts
readonly errors: Array<any>
```

Individual rejection reasons, in input order.

### new AggregateError()

```ts
constructor(errors: Array<any>, message?: string)
```

Construct from a list of reasons and an optional combined
message.

---

*Generated from `lang/types/builtin_errors.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/events

# events

String-keyed event channels with `EventEmitter`.

::: tip Import
```ts
import { EventEmitter } from "events";
```
:::

## EventEmitter <Badge type="info" text="class" />

```ts
class EventEmitter
```

### EventEmitter.emit

```ts
emit(event: string, ...args: any[]): boolean
```

Emit an event, calling all registered listeners with the provided arguments.

**Parameters**

- `event`: The event name.
- `args`: Arguments passed to each listener.

**Returns:** true if any listeners were called, false otherwise.

### EventEmitter.listenerCount

```ts
listenerCount(event: string): int
```

Get the number of listeners registered for an event.

**Parameters**

- `event`: The event name.

**Returns:** The count of both `on` and `once` listeners.

### EventEmitter.off

```ts
off(event: string, listener: Function): boolean
```

Remove one registration of `listener`. True when one was removed.

### EventEmitter.on

```ts
on(event: string, listener: Function): Function
```

Add a persistent listener. Returns a function that removes it.

### EventEmitter.once

```ts
once(event: string, listener: Function): Function
```

Add a listener that fires once. Returns a function that removes it.

### EventEmitter.removeAllListeners

```ts
removeAllListeners(event?: string): void
```

Remove all listeners for a specific event, or all listeners for all events.

**Parameters**

- `event`: Optional event name; if omitted, clears all events.

---

*Generated from `lang/types/events.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/fs

# fs

Files and directories.

::: tip Import
```ts
import { FileStat, Files } from "fs";
```

Needs the `"fs"` permission in `thicket.json`.
:::

## FileStat <Badge type="info" text="class" />

```ts
class FileStat
```

Metadata describing a filesystem entry, returned by `fs.stat`.

Times are milliseconds since the Unix epoch as `float64` so the
values survive a round-trip through `JSON.stringify` without
precision loss.

### FileStat.createdMs

```ts
createdMs: float64
```

Creation time in milliseconds since the Unix epoch.

### FileStat.isDirectory

```ts
isDirectory: boolean
```

True when the entry is a directory.

### FileStat.isFile

```ts
isFile: boolean
```

True when the entry is a regular file.

### FileStat.modifiedMs

```ts
modifiedMs: float64
```

Modification time in milliseconds since the Unix epoch.

### FileStat.size

```ts
size: uint
```

Size in bytes.

## Files <Badge type="info" text="static class" />

```ts
static class Files
```

Filesystem subsystem. Imported as `import { Files } from "fs"`.

Every async method returns `Promise<T>`; `await` it from an
`async function` or the top-level entry point. Errors come back as
rejected promises. The path-utility methods at the bottom of this
class are synchronous and require no permission.

### Files.sep

```ts
static readonly sep: string
```

The path separator on this platform.

Always `"/"` on macOS and Linux, `"\\"` on Windows.

### Files.delimiter

```ts
static readonly delimiter: string
```

The PATH environment variable delimiter on this platform.

`":"` on macOS and Linux, `";"` on Windows.

### Files.appendBytes

```ts
static appendBytes(path: string, data: any): any
```

Append raw bytes to `path`.

Creates the file if it does not exist.

### Files.appendFile

```ts
static appendFile(path: string, content: string): any
```

Append `content` to `path` as UTF-8.

Creates the file if it does not exist.

### Files.copy

```ts
static copy(src: string, dest: string): any
```

Copy `src` to `dest`, replacing `dest` if it exists.

`src` may be an embedded file (a plain path or `embed://`); its bytes
are written to `dest` on disk. `dest` can never be embedded.

Copies file contents; does not preserve extended attributes
or hard-link relationships.

### Files.exists

```ts
static exists(path: string): any
```

Resolve to `true` when `path` exists, `false` otherwise.

Does not distinguish files from directories — combine with
`isFile` / `isDirectory` when the kind matters.

### Files.isDirectory

```ts
static isDirectory(path: string): any
```

True when the entry is a directory.

### Files.isEmbedded

```ts
static isEmbedded(path: string): boolean
```

True when `path` is an embedded file or a folder inside the program's
embedded files. A plain path answers in a built program only; an
`embed://` path also answers in `thicket run`, from the project files
the `embed` entries of `assets` would ship. Synchronous.

### Files.isFile

```ts
static isFile(path: string): any
```

True when the entry is a regular file.

### Files.mkdir

```ts
static mkdir(path: string, recursive?: boolean): any
```

Create directory `path`.

When `recursive` is true, intermediate directories are
created as needed. Without it, missing parents cause an
error.

### Files.readDir

```ts
static readDir(path: string): any
```

Resolve to the entries of directory `path` as an array of
names.

Names are returned in implementation-defined order, except in a
built program where embedded files are merged in (they shadow a disk
entry of the same name, and implied folders appear): that listing is
sorted by name. `embed://<path>` lists the embedded files only. Use
`Files.join` to build full paths from the entries.

### Files.readFile

```ts
static readFile(path: string): any
```

Read the entire contents of `path` as raw bytes.

Resolves to a `Buffer`. Use `readText` when the file is known to
be UTF-8.

**Example**

```ts
import { Files } from "fs";
await Files.writeFile("data.bin", ByteArray.from("abc"));
const bytes: any = await Files.readFile("data.bin");
console.log(bytes.length); // 3
```

### Files.readText

```ts
static readText(path: string): any
```

Read the entire contents of `path` as UTF-8.

Throws if the file is missing, unreadable, or contains
invalid UTF-8.

Example:
```ts
const cfg = await Files.readText("config.json");
```

**Example**

```ts
import { Files } from "fs";
await Files.writeText("notes.txt", "hello");
console.log(await Files.readText("notes.txt")); // hello
```

### Files.remove

```ts
static remove(path: string, recursive?: boolean): any
```

Remove `path`.

For directories, pass `recursive: true` to remove the tree.
Without it, only empty directories can be removed.

### Files.rename

```ts
static rename(oldPath: string, newPath: string): any
```

Rename or move `oldPath` to `newPath`.

Both paths must reside on the same filesystem; cross-device
moves require copy + delete.

### Files.size

```ts
static size(path: string): any
```

Size in bytes.

### Files.stat

```ts
static stat(path: string): any
```

Resolve to a `FileStat` describing `path`.

Throws when `path` does not exist.

### Files.writeFile

```ts
static writeFile(path: string, data: any): any
```

Write raw bytes to `path`, replacing any existing file.

`data` is a `Buffer` or a string (written as its bytes). Like
`writeText` but does not assume UTF-8.

**Example**

```ts
import { Files } from "fs";
await Files.writeFile("data.bin", ByteArray.from("abc"));
```

### Files.writeText

```ts
static writeText(path: string, data: string): any
```

Write `data` to `path` as UTF-8, replacing any existing file.

Creates the file if it does not exist. Parent directories
must already exist; use `mkdir` first if needed.

### Files.basename

```ts
static basename(path: string, suffix?: string): string
```

Return the last segment of `path`.

When `suffix` is given and the segment ends with it, the suffix
is stripped from the result.

### Files.dirname

```ts
static dirname(path: string): string
```

Return the directory portion of `path`.

Returns `"."` when `path` has no directory component.

### Files.extname

```ts
static extname(path: string): string
```

Return the extension of `path`, including the leading dot.

Returns the empty string when there is no extension or the
file name begins with a dot (e.g. `.gitignore`).

### Files.formatPath

```ts
static formatPath(parts: any): string
```

Build a string from a parsed-path object produced by `parsePath`.

`base` takes precedence over `name + ext` when both are
provided, matching Node.js semantics.

### Files.isAbsolute

```ts
static isAbsolute(path: string): boolean
```

True when `path` is absolute on the host platform.

### Files.join

```ts
static join(...parts: string[]): string
```

Join all segments with the platform separator and normalize.

An absolute segment resets the accumulated path. Empty input
returns `"."`.

**Example**

```ts
import { Files } from "fs";
console.log(Files.join("assets", "img", "hero.png")); // assets/img/hero.png
```

### Files.normalize

```ts
static normalize(path: string): string
```

Collapse `.` and `..` segments and redundant separators.

Returns `"."` for the empty string.

### Files.parsePath

```ts
static parsePath(path: string): any
```

Split `path` into `{ root, dir, base, name, ext }`.

The shape mirrors Node.js's `path.parse`. Pass the result back
through `formatPath` to round-trip.

### Files.relative

```ts
static relative(from: string, to: string): string
```

Compute the relative path from `from` to `to`.

Both inputs are resolved against the current working directory
before the difference is computed.

### Files.resolve

```ts
static resolve(...parts: string[]): string
```

Resolve `parts` to an absolute path.

Segments are processed left to right; an absolute segment
discards everything before it. Relative results are anchored at
the current working directory.

---

*Generated from `lang/types/fs.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/geometry

# Geometry

The `Vec2`, `Point`, `Vec3`, `Size` and `Rect` value types.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Vec2 <Badge type="info" text="struct" />

```ts
struct Vec2
```

A 2D vector in game-defined units. An omitted field is 0.

### Vec2.copy

```ts
copy(): Vec2
```

A vector with the same components.

### Vec2.add

```ts
add(other: Vec2): Vec2
```

The component-wise sum.

### Vec2.subtract

```ts
subtract(other: Vec2): Vec2
```

The component-wise difference.

### Vec2.scaleBy

```ts
scaleBy(value: float): Vec2
```

This vector multiplied by a scalar.

### Other members of Vec2

```ts
x: float
y: float
operator add(other: Vec2): Vec2
operator sub(other: Vec2): Vec2
operator mul(value: float): Vec2
operator neg(): Vec2
operator eq(other: Vec2): boolean
toString(): string
```

## Point <Badge type="info" text="struct" />

```ts
struct Point
```

An integer position, such as a cursor in pixels. An omitted field is 0.

```ts
x: int
y: int
operator eq(other: Point): boolean
toString(): string
```

## Vec3 <Badge type="info" text="struct" />

```ts
struct Vec3
```

A 3D vector in game-defined units. An omitted field is 0.

### Vec3.copy

```ts
copy(): Vec3
```

A vector with the same components.

### Vec3.add

```ts
add(other: Vec3): Vec3
```

The component-wise sum.

### Vec3.subtract

```ts
subtract(other: Vec3): Vec3
```

The component-wise difference.

### Vec3.scaleBy

```ts
scaleBy(value: float): Vec3
```

This vector multiplied by a scalar.

### Other members of Vec3

```ts
x: float
y: float
z: float
operator add(other: Vec3): Vec3
operator sub(other: Vec3): Vec3
operator mul(value: float): Vec3
operator neg(): Vec3
operator eq(other: Vec3): boolean
toString(): string
```

## Size <Badge type="info" text="struct" />

```ts
struct Size
```

A width and a height. An omitted field is 0.

```ts
width: float
height: float
operator eq(other: Size): boolean
toString(): string
```

## Rect <Badge type="info" text="struct" />

```ts
struct Rect
```

An axis-aligned half-open rectangle: `x` and `y` are the top-left corner (inclusive),
and the right and bottom edges are exclusive. Spans `[x, x+width)` × `[y, y+height)`.
A literal is not checked, so a negative `width` or `height` is the caller's to avoid.

### Rect.right

```ts
get right(): float
```

Exclusive maximum x coordinate.

### Rect.bottom

```ts
get bottom(): float
```

Exclusive maximum y coordinate.

### Rect.center

```ts
get center(): Vec2
```

The midpoint of both extents.

### Rect.copy

```ts
copy(): Rect
```

A rectangle with identical edges.

### Rect.translated

```ts
translated(delta: Vec2): Rect
```

A copy offset by `delta`, with the same extents.

### Rect.contains

```ts
contains(point: Vec2): boolean
```

True for points inside the half-open rectangle: `[x, x+width)` × `[y, y+height)`.

### Rect.intersects

```ts
intersects(other: Rect): boolean
```

True when the rectangles overlap; touching edges or corners do not count.

### Rect.fromCenter

```ts
static fromCenter(center: Vec2, size: Vec2): Rect
```

A rectangle around a midpoint; throws when a size component is negative.

### Rect.union

```ts
static union(first: Rect, second: Rect): Rect
```

The smallest rectangle containing both inputs.

### Other members of Rect

```ts
x: float
y: float
width: float
height: float
operator eq(other: Rect): boolean
toString(): string
```

---

*Generated from `lang/geometry/index.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/globals

# Global functions

Output, timers, parsers, type checks and the global constants.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## print <Badge type="info" text="function" />

```ts
function print(...args: Array<any>): void
```

Write each argument to stdout on a single line, separated by spaces,
followed by a newline. Values are stringified the same way as
`console.log`. Unlike `console.log`, `print` has no level prefix and
no per-stream routing — it is the lowest-level write helper.

## dump <Badge type="info" text="function" />

```ts
function dump(...args: Array<any>): void
```

Debug-print each expression with its source text as a label. The
compiler rewrites `dump(x, y.z)` to `__dump_labeled("x", x, "y.z", y.z)`,
so the printed output reads `x = 1, y.z = 42`. Calling `dump`
indirectly (e.g. through a variable binding) skips the rewrite and
falls back to printing values without labels.

## setTimeout <Badge type="info" text="function" />

```ts
function setTimeout(handler: Function, delay?: int): int
```

Schedule `handler` to run once after at least `delay` milliseconds.
Omitted `delay` defaults to zero.
Returns a numeric timer id usable with `clearTimeout`. A negative
delay is clamped to zero. The runtime keeps the event loop alive
until the timer fires or is cleared.

## setInterval <Badge type="info" text="function" />

```ts
function setInterval(handler: Function, delay: int): int
```

Schedule `handler` to run repeatedly every `delay` milliseconds.
Returns a numeric timer id usable with `clearInterval`. Delays
below 1ms are clamped to 1ms. The first invocation occurs after
one full interval, not immediately.

## clearTimeout <Badge type="info" text="function" />

```ts
function clearTimeout(id: int): void
```

Cancel a pending `setTimeout`. Unknown ids are silently ignored.

## clearInterval <Badge type="info" text="function" />

```ts
function clearInterval(id: int): void
```

Cancel a recurring `setInterval`. Unknown ids are silently ignored.

## parseInt <Badge type="info" text="function" />

```ts
function parseInt(text: string): int
```

Parse a base-10 integer from `text`. Leading whitespace is skipped
and parsing stops at the first non-digit character. Returns 0 when
no digits are found.

## parseFloat <Badge type="info" text="function" />

```ts
function parseFloat(text: string): float64
```

Parse a floating-point number from `text`. Accepts decimal,
exponential, and `Infinity`/`NaN` forms. Returns `NaN` when no
numeric prefix is found.

## parseUint <Badge type="info" text="function" />

```ts
function parseUint(value: any, radix?: int): uint
```

Parse `value` as an unsigned 32-bit integer. Numeric inputs are
truncated; string inputs are read in `radix` (default 10). Throws
`RangeError` if the result is negative or exceeds `UINT32_MAX`.

## parseBool <Badge type="info" text="function" />

```ts
function parseBool(value: any): boolean | null
```

Parse the boolean a piece of text denotes. Strings are normalised with
`lower(trim(value))` and matched against the word list:
`true/yes/on/enable/enabled/success/1` are true,
`false/no/off/disable/disabled/failure/0` and the empty string are
false. A string outside the list returns `null` -- that is the only
thing `null` means here. Non-strings fall back to plain truthiness, so
`parseBool(0)` is false and `parseBool({})` is true.

This is NOT `Boolean()`. `Boolean(x)` asks whether there is a value,
so `Boolean("false")` is true. `parseBool(x)` asks what boolean the
text denotes, so `parseBool("false")` is false. Both are correct; they
answer different questions.

const debug: boolean = parseBool(Env.get("DEBUG")) ?? false;

## isNaN <Badge type="info" text="function" />

```ts
function isNaN(value: any): boolean
```

True if `value` is the IEEE-754 NaN sentinel.

## isFinite <Badge type="info" text="function" />

```ts
function isFinite(value: any): boolean
```

True if `value` is a finite number (not NaN, not ±Infinity).

## isNumber <Badge type="info" text="function" />

```ts
function isNumber(value: any): boolean
```

True if `value` is any numeric type (int, uint, or float).

## isString <Badge type="info" text="function" />

```ts
function isString(value: any): boolean
```

True if `value` is a string.

## isBoolean <Badge type="info" text="function" />

```ts
function isBoolean(value: any): boolean
```

True if `value` is a boolean.

## isInt <Badge type="info" text="function" />

```ts
function isInt(value: any): boolean
```

True if `value` is a 32-bit signed integer.

## isUint <Badge type="info" text="function" />

```ts
function isUint(value: any): boolean
```

True if `value` is a 32-bit unsigned integer.

## isNumeric <Badge type="info" text="function" />

```ts
function isNumeric(value: any): boolean
```

True if `value` is numeric.

## isNull <Badge type="info" text="function" />

```ts
function isNull(value: any): boolean
```

True if `value` is `null` or `undefined`.

## isArray <Badge type="info" text="function" />

```ts
function isArray(value: any): boolean
```

True if `value` is an array.

## isObject <Badge type="info" text="function" />

```ts
function isObject(value: any): boolean
```

True if `value` is a plain object instance. Excludes arrays, maps,
sets, and primitives.

## isMap <Badge type="info" text="function" />

```ts
function isMap(value: any): boolean
```

True if `value` is a `Map`.

## isSet <Badge type="info" text="function" />

```ts
function isSet(value: any): boolean
```

True if `value` is a `Set`.

## thisType <Badge type="info" text="function" />

```ts
function thisType(value: any): string
```

Return the runtime type tag of `value` as a lowercase string.
Possible values include `"int"`, `"uint"`, `"float"`, `"string"`,
`"boolean"`, `"array"`, `"object"`, `"map"`, `"set"`, `"function"`,
`"null"`, and `"undefined"`. More precise than the `typeof`
operator, which collapses numeric variants.

## declaredType <Badge type="info" text="function" />

```ts
function declaredType(value: any): string
```

Return the declared packed type of a direct struct field or FixedArray
element, otherwise the STATIC value type of the expression. For example,
an `int8` field reports `"int8"`, while a local holding its read reports
`"int"`. Folded to a string constant by the compiler: zero run-time cost,
and the argument is NOT evaluated. Compare `thisType`, which answers the
run-time type.

## toInt <Badge type="info" text="function" />

```ts
function toInt(value: any): int
```

Convert `value` to a 32-bit signed integer. Whole numeric strings
are accepted. Floats must be finite and integer-valued in range;
Values must fit. Throws `RangeError` on conversion failure. Use
`tryInt` for the non-throwing variant.

## toFloat64 <Badge type="info" text="function" />

```ts
function toFloat64(value: any): float64
```

Convert `value` to a 64-bit float. Numeric strings must contain one
complete number. Throws `RangeError` on conversion failure.

## tryFloat64 <Badge type="info" text="function" />

```ts
function tryFloat64(value: any): float64 | null
```

Like `toFloat64`, including numeric strings, but returns `null` on
failure instead of throwing.

## tryInt <Badge type="info" text="function" />

```ts
function tryInt(value: any): int | null
```

Like `toInt`, including whole numeric strings, but returns `null` on
failure instead of throwing. Useful for parsing untrusted input where
invalid values are expected.

## assert <Badge type="info" text="function" />

```ts
function assert(condition: any, message?: string): void
```

Halt execution if `condition` is falsy, raising an error with the
supplied message (or `"Assertion failed"` if none was given).
Intended for invariant checks; not stripped in release builds.

## exit <Badge type="info" text="function" />

```ts
function exit(code?: int): void
```

Request script termination with the given exit code (default 0).
Pending microtasks are drained before the process exits.
`System.exit()` is the canonical surface; this global is the
legacy shim and remains supported.

## sleep <Badge type="info" text="function" />

```ts
function sleep(ms: int): Promise<void>
```

Resolve after at least `ms` milliseconds, without blocking: other
tasks, timers and window frames keep running while an `await sleep(ms)`
is pending. `ms <= 0` resolves on the next timer turn, a fraction
truncates toward zero, and NaN or Infinity throw a RangeError. Under
`thicket run --autotest` the wait is measured in virtual frame time.
`wait` is the same function under a second name. A declaration of your
own named `sleep` shadows this one.

## wait <Badge type="info" text="function" />

```ts
function wait(ms: int): Promise<void>
```

Alias of `sleep`: `await wait(ms)` resolves after `ms` milliseconds.

## clone <Badge type="info" text="function" />

```ts
function clone(value: any): any
```

Return a deep copy of `value`. Strings, arrays, plain objects, maps,
and sets are recursively cloned; functions and class instances are
returned by reference. Throws on circular references.

## ts <Badge type="info" text="function" />

```ts
function ts(): float64
```

Wall-clock time in milliseconds since the Unix epoch.

## NaN <Badge type="info" text="const" />

```ts
const NaN: float64
```

IEEE-754 quiet NaN.

## Infinity <Badge type="info" text="const" />

```ts
const Infinity: float64
```

IEEE-754 positive infinity.

## globalThis <Badge type="info" text="const" />

```ts
const globalThis: any
```

The global object. Provides reflective access to every binding
defined at module scope. Untyped because the property set is
dynamic.

## undefined <Badge type="info" text="const" />

```ts
const undefined: any
```

The undefined value. Distinct from `null`.

## moduleDir <Badge type="info" text="const" />

```ts
const moduleDir: string
```

The absolute path of the folder this module's own source file lives
in, with no trailing slash. Each module sees its own: a package's
`widgets/button.tks` gets `.../widgets`, not the package root.
Computed when the module loads, so a moved program reports its new
folder. Reading a file through it needs the ordinary `fs` permission.

Example:
```ts
const theme = await Files.readText(Files.join(moduleDir, "theme.json"));
```

## Function <Badge type="info" text="class" />

```ts
class Function
```

*Final: it cannot be subclassed.*

`Function` global — the right-hand side of `f instanceof Function`,
which answers `true` for all four callable runtime types (a plain
function, a closure, a native function and a bound method) and
`false` for everything else.

`Function` is ALSO a type annotation (the wildcard callable, queue
081). That is a separate namespace: `let f: Function` and
`f instanceof Function` both work, and neither shadows the other.
`new Function()` still fails at runtime by design.

---

*Generated from `lang/types/builtin_globals.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/http

# http

Asynchronous HTTP client and an HTTP server.

::: tip Import
```ts
import { HttpMethod, HttpStatus, Http } from "http";
```

Needs the `"net"` permission in `thicket.json`.
:::

## HttpHeaders <Badge type="info" text="class" />

```ts
class HttpHeaders
```

*Type only: the runtime hands you instances; you never construct it yourself.*

HTTP response headers keyed by their field name.

### HttpHeaders.get

```ts
get(name: string): string?
```

Retrieves a header value by name; header names are case-insensitive.

**Parameters**

- `name`: The header field name.

**Returns:** The header value, or null if not found.

## HttpOptions <Badge type="info" text="class" />

```ts
class HttpOptions
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Options shared by Http's convenience methods. timeout is in seconds.

### HttpOptions.ca

```ts
ca?: string
```

PEM text or a PEM file for an additional private certificate authority.

### Other members of HttpOptions

```ts
headers?: HttpHeaders
body?: string
json?: Object
timeout?: float
```

## HttpRequestOptions <Badge type="info" text="class" />

```ts
class HttpRequestOptions extends HttpOptions
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Options for Http.request, including the required request URL.

```ts
url: string
method?: string
```

## HttpResponse <Badge type="info" text="class" />

```ts
class HttpResponse
```

*Type only: the runtime hands you instances; you never construct it yourself.*

A completed HTTP response. Transport and timeout failures reject instead.

### HttpResponse.text

```ts
text(): string
```

Reads the response body as a string.

**Returns:** The decoded response body.

### HttpResponse.json

```ts
json(): Object
```

Parses the response body as JSON.

**Returns:** A parsed JSON object, or undefined if parsing fails.

### HttpResponse.bytes

```ts
bytes(): Buffer
```

Reads the response body as bytes.

**Returns:** The response body as a Buffer.

### HttpResponse.text

```ts
static text(content: string, status?: int, headers?: HttpHeaders): HttpResponse
```

Constructs an HttpResponse with a string body.

**Parameters**

- `content`: The response body text.
- `status`: HTTP status code; default 200.
- `headers`: Optional HttpHeaders object.

**Returns:** An HttpResponse.

### HttpResponse.json

```ts
static json(content: Object, status?: int, headers?: HttpHeaders): HttpResponse
```

Constructs an HttpResponse with a JSON body.

**Parameters**

- `content`: The object to serialize as JSON.
- `status`: HTTP status code; default 200.
- `headers`: Optional HttpHeaders object.

**Returns:** An HttpResponse.

### HttpResponse.bytes

```ts
static bytes(content: Buffer, status?: int, headers?: HttpHeaders): HttpResponse
```

Constructs an HttpResponse with a binary body.

**Parameters**

- `content`: The response body bytes.
- `status`: HTTP status code; default 200.
- `headers`: Optional HttpHeaders object.

**Returns:** An HttpResponse.

### HttpResponse.redirect

```ts
static redirect(location: string, status?: int): HttpResponse
```

Constructs a redirect response.

**Parameters**

- `location`: The Location header value.
- `status`: HTTP status code; default 302.

**Returns:** An HttpResponse.

### Other members of HttpResponse

```ts
readonly status: int
readonly ok: boolean
readonly headers: HttpHeaders
readonly body: string
```

## HttpServerRequest <Badge type="info" text="class" />

```ts
class HttpServerRequest
```

*Type only: the runtime hands you instances; you never construct it yourself.*

A bounded, lazily decoded inbound server request.

### HttpServerRequest.params

```ts
readonly params: HttpParams
```

Percent-decoded values captured from :param route segments.

### HttpServerRequest.text

```ts
text(): string
```

Reads the request body as a string.

**Returns:** The decoded request body.

### HttpServerRequest.json

```ts
json(): Object
```

Parses the request body as JSON.

**Returns:** A parsed JSON object, or undefined if parsing fails.

### HttpServerRequest.bytes

```ts
bytes(): Buffer
```

Reads the request body as bytes.

**Returns:** The request body as a Buffer.

### Other members of HttpServerRequest

```ts
readonly method: string
readonly path: string
readonly query: string
readonly headers: HttpHeaders
```

## HttpParams <Badge type="info" text="class" />

```ts
class HttpParams
```

*Type only: the runtime hands you instances; you never construct it yourself.*

### HttpParams.get

```ts
get(name: string): string?
```

Retrieves a route parameter value by name.

**Parameters**

- `name`: The parameter name from a :param route segment.

**Returns:** The percent-decoded parameter value, or null if not found.

## HttpServer <Badge type="info" text="class" />

```ts
class HttpServer
```

*Type only: the runtime hands you instances; you never construct it yourself.*

### HttpServer.get

```ts
get(path: string, handler: (request: HttpServerRequest) => HttpResponse | Promise<HttpResponse>): void
```

Registers a handler for GET requests at the given path.

**Parameters**

- `path`: The URL path pattern, with :name for captured parameters.
- `handler`: A function that receives the request and returns a response or Promise.

### HttpServer.post

```ts
post(path: string, handler: (request: HttpServerRequest) => HttpResponse | Promise<HttpResponse>): void
```

Registers a handler for POST requests at the given path.

**Parameters**

- `path`: The URL path pattern, with :name for captured parameters.
- `handler`: A function that receives the request and returns a response or Promise.

### HttpServer.put

```ts
put(path: string, handler: (request: HttpServerRequest) => HttpResponse | Promise<HttpResponse>): void
```

Registers a handler for PUT requests at the given path.

**Parameters**

- `path`: The URL path pattern, with :name for captured parameters.
- `handler`: A function that receives the request and returns a response or Promise.

### HttpServer.delete

```ts
delete(path: string, handler: (request: HttpServerRequest) => HttpResponse | Promise<HttpResponse>): void
```

Registers a handler for DELETE requests at the given path.

**Parameters**

- `path`: The URL path pattern, with :name for captured parameters.
- `handler`: A function that receives the request and returns a response or Promise.

### HttpServer.serveStatic

```ts
serveStatic(urlPrefix: string, folder: string, index?: string): void
serveStatic(urlPrefix: string, assets: Object, index?: string): void
```

Mounts static files from a folder at the given URL prefix.

**Parameters**

- `urlPrefix`: The URL path prefix; e.g., "/static".
- `folder`: The filesystem folder path to serve.
- `index`: Optional index file name for directory requests; default none.

### HttpServer.onUpgrade

```ts
onUpgrade(handler: (request: HttpServerRequest, socket: WebSocket) => void): void
onUpgrade(path: string, handler: (request: HttpServerRequest, socket: WebSocket) => void): void
```

Registers a default WebSocket upgrade handler for all paths.

**Parameters**

- `handler`: A function that receives the request and WebSocket.

### HttpServer.close

```ts
close(): Promise<void>
```

Gracefully closes the server.

**Returns:** A Promise that resolves when the server is closed.

### Other members of HttpServer

```ts
readonly port: int
readonly connectionCount: int
```

## HttpServeOptions <Badge type="info" text="class" />

```ts
class HttpServeOptions
```

*Type only: the runtime hands you instances; you never construct it yourself.*

HTTP server limits and timeouts. Timeout values are seconds.

### HttpServeOptions.maxBodySize

```ts
maxBodySize?: int
```

Compatibility spelling retained from the original server proposal.

### Other members of HttpServeOptions

```ts
port: int
handler: (request: HttpServerRequest) => HttpResponse | Promise<HttpResponse>
host?: string
maxRequestLineBytes?: int
maxHeaderCount?: int
maxHeaderBytes?: int
maxBodyBytes?: int
headerTimeout?: float
bodyTimeout?: float
idleTimeout?: float
writeTimeout?: float
gracefulCloseTimeout?: float
maxConnections?: int
maxPendingWriteBytes?: int
maxStaticFileBytes?: int
maxPayload?: int
verifyOrigin?: Array<string> | ((origin: string, request: HttpServerRequest) => boolean)
```

## HttpMethod <Badge type="info" text="static class" />

```ts
static class HttpMethod
```

HTTP method name constants for request routing.

```ts
static readonly DELETE: string
static readonly GET: string
static readonly HEAD: string
static readonly OPTIONS: string
static readonly PATCH: string
static readonly POST: string
static readonly PUT: string
```

## HttpStatus <Badge type="info" text="static class" />

```ts
static class HttpStatus
```

Named status-code constants for HTTP response comparisons.

```ts
static readonly CONTINUE: int
static readonly OK: int
static readonly CREATED: int
static readonly NO_CONTENT: int
static readonly MOVED_PERMANENTLY: int
static readonly FOUND: int
static readonly NOT_MODIFIED: int
static readonly BAD_REQUEST: int
static readonly UNAUTHORIZED: int
static readonly FORBIDDEN: int
static readonly NOT_FOUND: int
static readonly REQUEST_TIMEOUT: int
static readonly PAYLOAD_TOO_LARGE: int
static readonly TOO_MANY_REQUESTS: int
static readonly REQUEST_HEADER_FIELDS_TOO_LARGE: int
static readonly UPGRADE_REQUIRED: int
static readonly INTERNAL_SERVER_ERROR: int
static readonly BAD_GATEWAY: int
static readonly SERVICE_UNAVAILABLE: int
```

## Http <Badge type="info" text="static class" />

```ts
static class Http
```

### Http.DEFAULT_MAX_REQUEST_LINE_BYTES

```ts
static readonly DEFAULT_MAX_REQUEST_LINE_BYTES: int
```

Default maximum HTTP request line size in bytes.

### Http.DEFAULT_MAX_HEADER_COUNT

```ts
static readonly DEFAULT_MAX_HEADER_COUNT: int
```

Default maximum number of HTTP headers per request.

### Http.DEFAULT_MAX_HEADER_BYTES

```ts
static readonly DEFAULT_MAX_HEADER_BYTES: int
```

Default maximum total header size in bytes.

### Http.DEFAULT_MAX_BODY_BYTES

```ts
static readonly DEFAULT_MAX_BODY_BYTES: int
```

Default maximum request body size in bytes.

### Http.DEFAULT_HEADER_TIMEOUT

```ts
static readonly DEFAULT_HEADER_TIMEOUT: float
```

Default header read timeout in seconds.

### Http.DEFAULT_BODY_TIMEOUT

```ts
static readonly DEFAULT_BODY_TIMEOUT: float
```

Default body read timeout in seconds.

### Http.DEFAULT_IDLE_TIMEOUT

```ts
static readonly DEFAULT_IDLE_TIMEOUT: float
```

Default idle connection timeout in seconds.

### Http.DEFAULT_WRITE_TIMEOUT

```ts
static readonly DEFAULT_WRITE_TIMEOUT: float
```

Default write timeout in seconds.

### Http.DEFAULT_GRACEFUL_CLOSE_TIMEOUT

```ts
static readonly DEFAULT_GRACEFUL_CLOSE_TIMEOUT: float
```

Default graceful close timeout in seconds.

### Http.DEFAULT_MAX_CONNECTIONS

```ts
static readonly DEFAULT_MAX_CONNECTIONS: int
```

Default maximum number of concurrent connections.

### Http.DEFAULT_MAX_PENDING_WRITE_BYTES

```ts
static readonly DEFAULT_MAX_PENDING_WRITE_BYTES: int
```

Default maximum pending write buffer size in bytes.

### Http.DEFAULT_MAX_STATIC_FILE_BYTES

```ts
static readonly DEFAULT_MAX_STATIC_FILE_BYTES: int
```

Default maximum static file size in bytes.

### Http.DELETE

```ts
static readonly DELETE: string
```

The HTTP DELETE method.

### Http.GET

```ts
static readonly GET: string
```

The HTTP GET method.

### Http.HEAD

```ts
static readonly HEAD: string
```

The HTTP HEAD method.

### Http.OPTIONS

```ts
static readonly OPTIONS: string
```

The HTTP OPTIONS method.

### Http.PATCH

```ts
static readonly PATCH: string
```

The HTTP PATCH method.

### Http.POST

```ts
static readonly POST: string
```

The HTTP POST method.

### Http.PUT

```ts
static readonly PUT: string
```

The HTTP PUT method.

### Http.delete

```ts
static delete(url: string, opts?: HttpOptions): Promise<HttpResponse>
```

Sends an HTTP DELETE request.

**Parameters**

- `url`: The request URL.
- `opts`: Optional request options (headers, timeout, etc.).

**Returns:** A Promise resolving to the HttpResponse.

### Http.get

```ts
static get(url: string, opts?: HttpOptions): Promise<HttpResponse>
```

Sends an HTTP GET request.

**Parameters**

- `url`: The request URL.
- `opts`: Optional request options (headers, timeout, etc.).

**Returns:** A Promise resolving to the HttpResponse.

### Http.head

```ts
static head(url: string, opts?: HttpOptions): Promise<HttpResponse>
```

Sends an HTTP HEAD request.

**Parameters**

- `url`: The request URL.
- `opts`: Optional request options (headers, timeout, etc.).

**Returns:** A Promise resolving to the HttpResponse.

### Http.options

```ts
static options(url: string, opts?: HttpOptions): Promise<HttpResponse>
```

Sends an HTTP OPTIONS request.

**Parameters**

- `url`: The request URL.
- `opts`: Optional request options (headers, timeout, etc.).

**Returns:** A Promise resolving to the HttpResponse.

### Http.patch

```ts
static patch(url: string, opts?: HttpOptions): Promise<HttpResponse>
```

Sends an HTTP PATCH request.

**Parameters**

- `url`: The request URL.
- `opts`: Optional request options (headers, timeout, etc.).

**Returns:** A Promise resolving to the HttpResponse.

### Http.post

```ts
static post(url: string, opts?: HttpOptions): Promise<HttpResponse>
```

Sends an HTTP POST request.

**Parameters**

- `url`: The request URL.
- `opts`: Optional request options (headers, timeout, etc.).

**Returns:** A Promise resolving to the HttpResponse.

### Http.put

```ts
static put(url: string, opts?: HttpOptions): Promise<HttpResponse>
```

Sends an HTTP PUT request.

**Parameters**

- `url`: The request URL.
- `opts`: Optional request options (headers, timeout, etc.).

**Returns:** A Promise resolving to the HttpResponse.

### Http.request

```ts
static request(opts: HttpRequestOptions): Promise<HttpResponse>
```

Sends a custom HTTP request.

**Parameters**

- `opts`: Request options, including url and optional method.

**Returns:** A Promise resolving to the HttpResponse.

### Http.serve

```ts
static serve(options: HttpServeOptions): Promise<HttpServer>
```

Starts an HTTP server.

**Parameters**

- `options`: Server options including port, handler, and limits.

**Returns:** A Promise resolving to the HttpServer.

---

*Generated from `lang/types/http.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/input

# Input constants

`Key`, `GamepadButton`, `GamepadAxis` and `MouseCursor`.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## MouseCursor <Badge type="info" text="static class" />

```ts
static class MouseCursor
```

*Final: it cannot be subclassed.*

Named cursor shapes accepted by Mouse.cursor and engine.cursor.set.

### MouseCursor.DEFAULT

```ts
static readonly DEFAULT: string
```

The default pointer.

### MouseCursor.ARROW

```ts
static readonly ARROW: string
```

The arrow pointer.

### MouseCursor.IBEAM

```ts
static readonly IBEAM: string
```

The text-insertion I-beam.

### MouseCursor.CROSSHAIR

```ts
static readonly CROSSHAIR: string
```

A crosshair.

### MouseCursor.POINTING_HAND

```ts
static readonly POINTING_HAND: string
```

The pointing hand used over links.

### MouseCursor.RESIZE_EW

```ts
static readonly RESIZE_EW: string
```

Horizontal resize (left-right).

### MouseCursor.RESIZE_NS

```ts
static readonly RESIZE_NS: string
```

Vertical resize (up-down).

### MouseCursor.RESIZE_NWSE

```ts
static readonly RESIZE_NWSE: string
```

Diagonal resize (top-left to bottom-right).

### MouseCursor.RESIZE_NESW

```ts
static readonly RESIZE_NESW: string
```

Diagonal resize (top-right to bottom-left).

### MouseCursor.RESIZE_ALL

```ts
static readonly RESIZE_ALL: string
```

Resize or move in every direction.

### MouseCursor.NOT_ALLOWED

```ts
static readonly NOT_ALLOWED: string
```

The not-allowed pointer.

## Key <Badge type="info" text="static class" />

```ts
static class Key
```

*Final: it cannot be subclassed.*

Keyboard constants named as in Heaps `hxd.Key`. Each is the physical key (scancode), so `Key.W` is the key in the W position of a QWERTY board on any layout.

### Key.BACKSPACE

```ts
static readonly BACKSPACE: int
```

Backspace.

### Key.TAB

```ts
static readonly TAB: int
```

Tab.

### Key.ENTER

```ts
static readonly ENTER: int
```

Enter / Return.

### Key.ESCAPE

```ts
static readonly ESCAPE: int
```

Escape.

### Key.SPACE

```ts
static readonly SPACE: int
```

The space bar.

### Key.PGUP

```ts
static readonly PGUP: int
```

Page Up.

### Key.PGDOWN

```ts
static readonly PGDOWN: int
```

Page Down.

### Key.END

```ts
static readonly END: int
```

End.

### Key.HOME

```ts
static readonly HOME: int
```

Home.

### Key.LEFT

```ts
static readonly LEFT: int
```

Left arrow.

### Key.UP

```ts
static readonly UP: int
```

Up arrow.

### Key.RIGHT

```ts
static readonly RIGHT: int
```

Right arrow.

### Key.DOWN

```ts
static readonly DOWN: int
```

Down arrow.

### Key.INSERT

```ts
static readonly INSERT: int
```

Insert.

### Key.DELETE

```ts
static readonly DELETE: int
```

Delete.

### Key.PRINT_SCREEN

```ts
static readonly PRINT_SCREEN: int
```

Print Screen.

### Key.QWERTY_EQUALS

```ts
static readonly QWERTY_EQUALS: int
```

The equals key (QWERTY layout position).

### Key.QWERTY_MINUS

```ts
static readonly QWERTY_MINUS: int
```

The minus key (QWERTY layout position).

### Key.QWERTY_TILDE

```ts
static readonly QWERTY_TILDE: int
```

The tilde key (QWERTY layout position).

### Key.QWERTY_BRACKET_LEFT

```ts
static readonly QWERTY_BRACKET_LEFT: int
```

The bracket left key (QWERTY layout position).

### Key.QWERTY_BRACKET_RIGHT

```ts
static readonly QWERTY_BRACKET_RIGHT: int
```

The bracket right key (QWERTY layout position).

### Key.QWERTY_SEMICOLON

```ts
static readonly QWERTY_SEMICOLON: int
```

The semicolon key (QWERTY layout position).

### Key.QWERTY_QUOTE

```ts
static readonly QWERTY_QUOTE: int
```

The quote key (QWERTY layout position).

### Key.QWERTY_BACKSLASH

```ts
static readonly QWERTY_BACKSLASH: int
```

The backslash key (QWERTY layout position).

### Key.QWERTY_COMMA

```ts
static readonly QWERTY_COMMA: int
```

The comma key (QWERTY layout position).

### Key.QWERTY_PERIOD

```ts
static readonly QWERTY_PERIOD: int
```

The period key (QWERTY layout position).

### Key.QWERTY_SLASH

```ts
static readonly QWERTY_SLASH: int
```

The slash key (QWERTY layout position).

### Key.INTL_BACKSLASH

```ts
static readonly INTL_BACKSLASH: int
```

The extra key next to left Shift on ISO keyboards.

### Key.LEFT_WINDOW_KEY

```ts
static readonly LEFT_WINDOW_KEY: int
```

Left Windows / Command key.

### Key.RIGHT_WINDOW_KEY

```ts
static readonly RIGHT_WINDOW_KEY: int
```

Right Windows / Command key.

### Key.CONTEXT_MENU

```ts
static readonly CONTEXT_MENU: int
```

The context-menu key.

### Key.AZERTY_DOLLAR

```ts
static readonly AZERTY_DOLLAR: int
```

The dollar key (AZERTY layout position).

### Key.AZERTY_EQUALS

```ts
static readonly AZERTY_EQUALS: int
```

The equals key (AZERTY layout position).

### Key.AZERTY_COMMA

```ts
static readonly AZERTY_COMMA: int
```

The comma key (AZERTY layout position).

### Key.AZERTY_SEMICOLON

```ts
static readonly AZERTY_SEMICOLON: int
```

The semicolon key (AZERTY layout position).

### Key.AZERTY_COLON

```ts
static readonly AZERTY_COLON: int
```

The colon key (AZERTY layout position).

### Key.AZERTY_MODULO

```ts
static readonly AZERTY_MODULO: int
```

The modulo key (AZERTY layout position).

### Key.AZERTY_PARENT_CLOSE

```ts
static readonly AZERTY_PARENT_CLOSE: int
```

The parent close key (AZERTY layout position).

### Key.AZERTY_MULTIPLY

```ts
static readonly AZERTY_MULTIPLY: int
```

The multiply key (AZERTY layout position).

### Key.AZERTY_POWER

```ts
static readonly AZERTY_POWER: int
```

The power key (AZERTY layout position).

### Key.AZERTY_SQUARED

```ts
static readonly AZERTY_SQUARED: int
```

The squared key (AZERTY layout position).

### Key.AZERTY_EXCLAM

```ts
static readonly AZERTY_EXCLAM: int
```

The exclam key (AZERTY layout position).

### Key.PAUSE_BREAK

```ts
static readonly PAUSE_BREAK: int
```

Pause / Break.

### Key.CAPS_LOCK

```ts
static readonly CAPS_LOCK: int
```

Caps Lock.

### Key.NUM_LOCK

```ts
static readonly NUM_LOCK: int
```

Num Lock.

### Key.SCROLL_LOCK

```ts
static readonly SCROLL_LOCK: int
```

Scroll Lock.

### Key.NUMBER_0

```ts
static readonly NUMBER_0: int
```

The 0 key on the main number row.

### Key.NUMBER_1

```ts
static readonly NUMBER_1: int
```

The 1 key on the main number row.

### Key.NUMBER_2

```ts
static readonly NUMBER_2: int
```

The 2 key on the main number row.

### Key.NUMBER_3

```ts
static readonly NUMBER_3: int
```

The 3 key on the main number row.

### Key.NUMBER_4

```ts
static readonly NUMBER_4: int
```

The 4 key on the main number row.

### Key.NUMBER_5

```ts
static readonly NUMBER_5: int
```

The 5 key on the main number row.

### Key.NUMBER_6

```ts
static readonly NUMBER_6: int
```

The 6 key on the main number row.

### Key.NUMBER_7

```ts
static readonly NUMBER_7: int
```

The 7 key on the main number row.

### Key.NUMBER_8

```ts
static readonly NUMBER_8: int
```

The 8 key on the main number row.

### Key.NUMBER_9

```ts
static readonly NUMBER_9: int
```

The 9 key on the main number row.

### Key.NUMPAD_0

```ts
static readonly NUMPAD_0: int
```

The 0 key on the numeric keypad.

### Key.NUMPAD_1

```ts
static readonly NUMPAD_1: int
```

The 1 key on the numeric keypad.

### Key.NUMPAD_2

```ts
static readonly NUMPAD_2: int
```

The 2 key on the numeric keypad.

### Key.NUMPAD_3

```ts
static readonly NUMPAD_3: int
```

The 3 key on the numeric keypad.

### Key.NUMPAD_4

```ts
static readonly NUMPAD_4: int
```

The 4 key on the numeric keypad.

### Key.NUMPAD_5

```ts
static readonly NUMPAD_5: int
```

The 5 key on the numeric keypad.

### Key.NUMPAD_6

```ts
static readonly NUMPAD_6: int
```

The 6 key on the numeric keypad.

### Key.NUMPAD_7

```ts
static readonly NUMPAD_7: int
```

The 7 key on the numeric keypad.

### Key.NUMPAD_8

```ts
static readonly NUMPAD_8: int
```

The 8 key on the numeric keypad.

### Key.NUMPAD_9

```ts
static readonly NUMPAD_9: int
```

The 9 key on the numeric keypad.

### Key.NUMPAD_MULT

```ts
static readonly NUMPAD_MULT: int
```

Numeric keypad multiply.

### Key.NUMPAD_ADD

```ts
static readonly NUMPAD_ADD: int
```

Numeric keypad add.

### Key.NUMPAD_ENTER

```ts
static readonly NUMPAD_ENTER: int
```

Numeric keypad Enter.

### Key.NUMPAD_SUB

```ts
static readonly NUMPAD_SUB: int
```

Numeric keypad subtract.

### Key.NUMPAD_DOT

```ts
static readonly NUMPAD_DOT: int
```

Numeric keypad decimal point.

### Key.NUMPAD_DIV

```ts
static readonly NUMPAD_DIV: int
```

Numeric keypad divide.

### Key.A

```ts
static readonly A: int
```

The A key (physical position).

### Key.B

```ts
static readonly B: int
```

The B key (physical position).

### Key.C

```ts
static readonly C: int
```

The C key (physical position).

### Key.D

```ts
static readonly D: int
```

The D key (physical position).

### Key.E

```ts
static readonly E: int
```

The E key (physical position).

### Key.F

```ts
static readonly F: int
```

The F key (physical position).

### Key.G

```ts
static readonly G: int
```

The G key (physical position).

### Key.H

```ts
static readonly H: int
```

The H key (physical position).

### Key.I

```ts
static readonly I: int
```

The I key (physical position).

### Key.J

```ts
static readonly J: int
```

The J key (physical position).

### Key.K

```ts
static readonly K: int
```

The K key (physical position).

### Key.L

```ts
static readonly L: int
```

The L key (physical position).

### Key.M

```ts
static readonly M: int
```

The M key (physical position).

### Key.N

```ts
static readonly N: int
```

The N key (physical position).

### Key.O

```ts
static readonly O: int
```

The O key (physical position).

### Key.P

```ts
static readonly P: int
```

The P key (physical position).

### Key.Q

```ts
static readonly Q: int
```

The Q key (physical position).

### Key.R

```ts
static readonly R: int
```

The R key (physical position).

### Key.S

```ts
static readonly S: int
```

The S key (physical position).

### Key.T

```ts
static readonly T: int
```

The T key (physical position).

### Key.U

```ts
static readonly U: int
```

The U key (physical position).

### Key.V

```ts
static readonly V: int
```

The V key (physical position).

### Key.W

```ts
static readonly W: int
```

The W key (physical position).

### Key.X

```ts
static readonly X: int
```

The X key (physical position).

### Key.Y

```ts
static readonly Y: int
```

The Y key (physical position).

### Key.Z

```ts
static readonly Z: int
```

The Z key (physical position).

### Key.F1

```ts
static readonly F1: int
```

The F1 function key.

### Key.F2

```ts
static readonly F2: int
```

The F2 function key.

### Key.F3

```ts
static readonly F3: int
```

The F3 function key.

### Key.F4

```ts
static readonly F4: int
```

The F4 function key.

### Key.F5

```ts
static readonly F5: int
```

The F5 function key.

### Key.F6

```ts
static readonly F6: int
```

The F6 function key.

### Key.F7

```ts
static readonly F7: int
```

The F7 function key.

### Key.F8

```ts
static readonly F8: int
```

The F8 function key.

### Key.F9

```ts
static readonly F9: int
```

The F9 function key.

### Key.F10

```ts
static readonly F10: int
```

The F10 function key.

### Key.F11

```ts
static readonly F11: int
```

The F11 function key.

### Key.F12

```ts
static readonly F12: int
```

The F12 function key.

### Key.F13

```ts
static readonly F13: int
```

The F13 function key.

### Key.F14

```ts
static readonly F14: int
```

The F14 function key.

### Key.F15

```ts
static readonly F15: int
```

The F15 function key.

### Key.F16

```ts
static readonly F16: int
```

The F16 function key.

### Key.F17

```ts
static readonly F17: int
```

The F17 function key.

### Key.F18

```ts
static readonly F18: int
```

The F18 function key.

### Key.F19

```ts
static readonly F19: int
```

The F19 function key.

### Key.F20

```ts
static readonly F20: int
```

The F20 function key.

### Key.F21

```ts
static readonly F21: int
```

The F21 function key.

### Key.F22

```ts
static readonly F22: int
```

The F22 function key.

### Key.F23

```ts
static readonly F23: int
```

The F23 function key.

### Key.F24

```ts
static readonly F24: int
```

The F24 function key.

### Key.SHIFT

```ts
static readonly SHIFT: int
```

Alias of `LSHIFT`.

### Key.CTRL

```ts
static readonly CTRL: int
```

Alias of `LCTRL`.

### Key.ALT

```ts
static readonly ALT: int
```

Alias of `LALT`.

### Key.LSHIFT

```ts
static readonly LSHIFT: int
```

Left Shift.

### Key.RSHIFT

```ts
static readonly RSHIFT: int
```

Right Shift.

### Key.LCTRL

```ts
static readonly LCTRL: int
```

Left Ctrl.

### Key.RCTRL

```ts
static readonly RCTRL: int
```

Right Ctrl.

### Key.LALT

```ts
static readonly LALT: int
```

Left Alt.

### Key.RALT

```ts
static readonly RALT: int
```

Right Alt.

### Key.name

```ts
static name(code: int): string
```

The Go-style name of a key ("LeftControl", "PageUp", "Space"), "" for anything that is not a Key constant. Saved bindings store this spelling.

### Key.fromName

```ts
static fromName(name: string): int
```

The Key constant for a Go-style ("LeftControl") or constant-style ("LCTRL") name; -1 when unknown.

## GamepadButton <Badge type="info" text="static class" />

```ts
static class GamepadButton
```

*Final: it cannot be subclassed.*

Gamepad button constants for `Gamepad.isDown`, `isPressed` and `isReleased`.

### GamepadButton.A

```ts
static readonly A: int
```

The A (bottom) face button.

### GamepadButton.B

```ts
static readonly B: int
```

The B (right) face button.

### GamepadButton.X

```ts
static readonly X: int
```

The X (left) face button.

### GamepadButton.Y

```ts
static readonly Y: int
```

The Y (top) face button.

### GamepadButton.LB

```ts
static readonly LB: int
```

Left shoulder button.

### GamepadButton.RB

```ts
static readonly RB: int
```

Right shoulder button.

### GamepadButton.LT

```ts
static readonly LT: int
```

Left trigger as a button.

### GamepadButton.RT

```ts
static readonly RT: int
```

Right trigger as a button.

### GamepadButton.LEFT_STICK

```ts
static readonly LEFT_STICK: int
```

Left stick click.

### GamepadButton.RIGHT_STICK

```ts
static readonly RIGHT_STICK: int
```

Right stick click.

### GamepadButton.DPAD_UP

```ts
static readonly DPAD_UP: int
```

D-pad up.

### GamepadButton.DPAD_DOWN

```ts
static readonly DPAD_DOWN: int
```

D-pad down.

### GamepadButton.DPAD_LEFT

```ts
static readonly DPAD_LEFT: int
```

D-pad left.

### GamepadButton.DPAD_RIGHT

```ts
static readonly DPAD_RIGHT: int
```

D-pad right.

### GamepadButton.START

```ts
static readonly START: int
```

Start button.

### GamepadButton.BACK

```ts
static readonly BACK: int
```

Back (select) button.

### GamepadButton.HOME

```ts
static readonly HOME: int
```

Home (guide) button.

## GamepadAxis <Badge type="info" text="static class" />

```ts
static class GamepadAxis
```

*Final: it cannot be subclassed.*

Gamepad axis constants for `Gamepad.axis` and `axisRaw`.

### GamepadAxis.LEFT_X

```ts
static readonly LEFT_X: int
```

Left stick horizontal axis.

### GamepadAxis.LEFT_Y

```ts
static readonly LEFT_Y: int
```

Left stick vertical axis.

### GamepadAxis.RIGHT_X

```ts
static readonly RIGHT_X: int
```

Right stick horizontal axis.

### GamepadAxis.RIGHT_Y

```ts
static readonly RIGHT_Y: int
```

Right stick vertical axis.

### GamepadAxis.LT

```ts
static readonly LT: int
```

Left trigger axis.

### GamepadAxis.RT

```ts
static readonly RT: int
```

Right trigger axis.

---

*Generated from `lang/types/builtin_input_constants.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/inputmap

# InputMap

Named actions bound to keys, buttons and axes.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## InputMap <Badge type="info" text="class" />

```ts
class InputMap
```

### InputMap.FORMAT_VERSION

```ts
static readonly FORMAT_VERSION: int
```

The version written by `save` and the only one `load` accepts.

### InputMap.MAX_SERIALIZED_BYTES

```ts
static readonly MAX_SERIALIZED_BYTES: int
```

`load` refuses documents larger than this many bytes.

### InputMap.MAX_ENTRIES

```ts
static readonly MAX_ENTRIES: int
```

`load` refuses documents with more bindings and axes than this.

### InputMap.MAX_JSON_DEPTH

```ts
static readonly MAX_JSON_DEPTH: int
```

`load` refuses documents nested deeper than this.

### InputMap.CAPTURE_AXIS_THRESHOLD

```ts
static readonly CAPTURE_AXIS_THRESHOLD: float
```

A stick must pass this magnitude, from below, for `captureNext` to take it.

### InputMap.CAPTURE_POLL_MS

```ts
static readonly CAPTURE_POLL_MS: int
```

How often a pending `captureNext` looks at the devices.

### InputMap.PAD_SLOTS

```ts
static readonly PAD_SLOTS: int
```

Gamepads are indexed 0 to 3; a pad binding is satisfied by any of them.

### InputMap.bind

```ts
static bind(action: actionid, inputs: Array<int>): void
```

Replaces the bindings of `action` with `inputs`. Values that are not input constants are dropped.

### InputMap.rebind

```ts
static rebind(action: actionid, input: int): void
```

Replaces the bindings of `action` with the one `input` (what `captureNext` resolves with).

### InputMap.unbind

```ts
static unbind(action: actionid): void
```

Removes the bindings and axis of `action`.

### InputMap.clear

```ts
static clear(): void
```

Removes every binding and axis.

### InputMap.axis

```ts
static axis(axisAction: actionid, negativeAction: actionid, positiveAction: actionid, padAxis?: int): void
```

Makes `axisAction` read `positiveAction - negativeAction` (clamped to -1..1); when `padAxis` is given,
the larger magnitude of that and the stick wins.

### InputMap.isDown

```ts
static isDown(action: actionid): boolean
```

Whether any input of `action` is held. False while text input is active.

### InputMap.isPressed

```ts
static isPressed(action: actionid): boolean
```

Whether `action` went down: once per edge on a tick, once per frame outside one.

### InputMap.isReleased

```ts
static isReleased(action: actionid): boolean
```

Whether `action` was let go: once per edge on a tick, once per frame outside one.

### InputMap.value

```ts
static value(action: actionid): float
```

-1..1 for an axis action, 0 or 1 for a digital one, the largest magnitude of a mixed list.

### InputMap.captureNext

```ts
static captureNext(): Promise<int>
```

Resolves with the next key, mouse button, pad button or stick (past the threshold) the player presses.
Rejects if text input starts or `cancelCapture` is called. A second call while one is pending returns
the same promise.

### InputMap.cancelCapture

```ts
static cancelCapture(): void
```

Rejects a pending `captureNext` (at its next poll).

### InputMap.save

```ts
static save(): string
```

Version 1 JSON with names (`Key.SPACE`), never numbers, so a saved file survives renumbering.

### InputMap.load

```ts
static load(json: string): Array<string>
```

Restores a saved document. Validates all of it before replacing anything, so a bad document leaves the
current map unchanged. Returns the names it did not recognise (from a newer engine).

### Other members of InputMap

```ts
static readonly KIND_NONE: int
static readonly KIND_KEY: int
static readonly KIND_MOUSE: int
static readonly KIND_PAD_BUTTON: int
static readonly KIND_PAD_AXIS: int
```

---

*Generated from `lang/inputmap/index.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/json

# JSON

Parse and stringify JSON.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## JsonMode <Badge type="info" text="enum" />

```ts
enum JsonMode
```

Dialect accepted by `JSON.parse(text, mode)`.

- `JsonMode.AUTO`: The default: standard JSON plus the lenient forms listed on `JSON.parse`.
- `JsonMode.STRICT`: RFC 8259 only. Comments, single quotes, unquoted keys, trailing commas and hex numbers throw `SyntaxError`.
- `JsonMode.JSON5`: The JSON5 spec (json5.org): AUTO's forms plus `Infinity`, `NaN`, a leading `+`, leading or trailing decimal points and string line continuation.

## JSON <Badge type="info" text="static class" />

```ts
static class JSON
```

*Final: it cannot be subclassed.*

JSON namespace. Static helpers for converting between TKS values
and JSON text. Pair with `Files.readText` and `Files.writeText` to load
and save data files on disk.

### JSON.parse

```ts
static parse(text: string, mode?: JsonMode): any
```

Parse `text` as JSON and return the resulting value.

Accepts strict JSON plus the following JSONC extensions: line
comments (two slashes through end of line), block comments
(slash-star to star-slash), single-quoted strings, trailing
commas in arrays and objects, and unquoted JSON5 identifier
keys such as `{ foo: 1 }`. Inside strings the escape sequences
`\n`, `\r`, `\t`, `\"`, `\'`, `\\`, and `\/` are recognised;
any other backslash escape passes through verbatim.

Returns `undefined` when `text` is empty, malformed, or not a
string. Numeric literals that round-trip through 64-bit
integer decode as `int`; every other number decodes as
`float`. JSON objects parse as plain instances. JSON arrays
parse as `Array<any>`.

`mode` picks the dialect (`JsonMode.AUTO` when omitted, which is
the behaviour described above). `JsonMode.STRICT` accepts RFC 8259
only; `JsonMode.JSON5` accepts the JSON5 spec. The second parameter
differs from JavaScript's `JSON.parse(text, reviver)`: there is no
reviver.

The compiler rewrites `JSON.parse<StructName>(text)` into a
second-argument call carrying the struct type ID, so user
code never passes that argument directly.

**Example**

```ts
const data: any = JSON.parse('{"name":"ada","id":7}');
console.log(data.name, data.id); // ada 7
```

### JSON.stringify

```ts
static stringify(value: any, replacer?: Function | Array<any> | null | undefined, space?: int | string): string
```

Serialize `value` to a JSON string.

`replacer` controls which properties are emitted. A function
is called as `(key: string, value: any): any` for every
property and may return a transformed value or `undefined` to
omit it. An array whitelists object keys: string entries are
matched verbatim and integer entries coerce to their decimal
string form. `null`, `undefined`, or any other value disables
replacement entirely.

`space` controls indentation. An integer is clamped to the
range `0..10` and emits that many spaces per nesting level. A
string is truncated to its first 10 characters and used
verbatim as the indent unit. A falsy or missing `space`
produces a compact, single-line result.

`NaN` and `Infinity` serialize as `null`, matching the JS
spec. `undefined` values, function values, and entries the
replacer drops are omitted from objects and serialized as
`null` inside arrays.

**Example**

```ts
const text: string = JSON.stringify({ name: "ada", id: 7 });
console.log(text); // {"name":"ada","id":7}
```

---

*Generated from `lang/types/builtin_json.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/math

# Math

Math functions and constants.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Math <Badge type="info" text="static class" />

```ts
static class Math
```

*Final: it cannot be subclassed.*

Static numeric utilities. Covers the JavaScript `Math` surface plus
ThicketScript additions for clamping, interpolation, easing, and
scalar mapping.

### Math.E

```ts
static readonly E: float64
```

Euler's number (e ≈ 2.71828).

### Math.LN10

```ts
static readonly LN10: float64
```

Natural log of 10.

### Math.LN2

```ts
static readonly LN2: float64
```

Natural log of 2.

### Math.LOG10E

```ts
static readonly LOG10E: float64
```

Base-10 log of e.

### Math.LOG2E

```ts
static readonly LOG2E: float64
```

Base-2 log of e.

### Math.PI

```ts
static readonly PI: float64
```

π — ratio of a circle's circumference to its diameter.

### Math.SQRT1_2

```ts
static readonly SQRT1_2: float64
```

1 / √2.

### Math.SQRT2

```ts
static readonly SQRT2: float64
```

√2.

### Math.TAU

```ts
static readonly TAU: float64
```

2π — full turn in radians.

### Math.abs

```ts
static abs(x: float64): float64
```

Absolute value of `x`.

### Math.floor

```ts
static floor(x: float64): int
```

Largest integer ≤ `x`.

**Example**

```ts
console.log(Math.floor(2.9)); // 2
console.log(Math.floor(-2.1)); // -3
```

### Math.ceil

```ts
static ceil(x: float64): int
```

Smallest integer ≥ `x`.

### Math.round

```ts
static round(x: float64): int
```

Round `x` to the nearest integer. Halves round away from zero.

**Example**

```ts
console.log(Math.round(2.5)); // 3
```

### Math.trunc

```ts
static trunc(x: float64): int
```

Integer part of `x` (truncate toward zero).

### Math.fract

```ts
static fract(x: float64): float64
```

Fractional part of `x`. Equivalent to `x - Math.trunc(x)`.

### Math.sign

```ts
static sign(x: float64): int
```

Sign of `x`: `1` if positive, `-1` if negative, `0` if zero or
NaN.

### Math.sqrt

```ts
static sqrt(x: float64): float64
```

Square root of `x`. NaN if `x < 0`.

**Example**

```ts
console.log(Math.sqrt(16)); // 4
```

### Math.cbrt

```ts
static cbrt(x: float64): float64
```

Cube root of `x`. Defined for negative inputs.

### Math.pow

```ts
static pow(base: float64, exp: float64): float64
```

`base` raised to `exp`.

### Math.exp

```ts
static exp(x: float64): float64
```

`e` raised to `x`.

### Math.log

```ts
static log(x: float64): float64
```

Natural logarithm of `x`. NaN if `x < 0`.

### Math.log2

```ts
static log2(x: float64): float64
```

Base-2 logarithm of `x`.

### Math.log10

```ts
static log10(x: float64): float64
```

Base-10 logarithm of `x`.

### Math.hypot

```ts
static hypot(...args: Array<float64>): float64
```

Euclidean norm of the arguments — `sqrt(a² + b² + …)`. Variadic;
with zero arguments returns 0.

### Math.sin

```ts
static sin(x: float64): float64
```

Sine of `x` (radians).

**Example**

```ts
console.log(Math.sin(0)); // 0
```

### Math.cos

```ts
static cos(x: float64): float64
```

Cosine of `x` (radians).

### Math.tan

```ts
static tan(x: float64): float64
```

Tangent of `x` (radians).

### Math.asin

```ts
static asin(x: float64): float64
```

Arc-sine of `x`. Result in `[-π/2, π/2]`.

### Math.acos

```ts
static acos(x: float64): float64
```

Arc-cosine of `x`. Result in `[0, π]`.

### Math.atan

```ts
static atan(x: float64): float64
```

Arc-tangent of `x`. Result in `(-π/2, π/2)`.

### Math.atan2

```ts
static atan2(y: float64, x: float64): float64
```

Two-argument arc-tangent. Returns the angle of the point
`(x, y)` in radians, in `(-π, π]`. Useful for converting
Cartesian to polar coordinates.

### Math.degToRad

```ts
static degToRad(deg: float64): float64
```

Convert degrees to radians.

**Example**

```ts
console.log(Math.degToRad(180) == Math.PI); // true
```

### Math.radToDeg

```ts
static radToDeg(rad: float64): float64
```

Convert radians to degrees.

**Example**

```ts
console.log(Math.radToDeg(Math.PI)); // 180
```

### Math.min

```ts
static min(...args: Array<float64>): float64
```

Smallest of the arguments. Variadic; returns `+Infinity` with no
arguments.

### Math.max

```ts
static max(...args: Array<float64>): float64
```

Largest of the arguments. Variadic; returns `-Infinity` with no
arguments.

### Math.random

```ts
static random(): float64
```

Uniform random float in `[0, 1)`. Backed by xoshiro256** seeded
from system entropy at VM startup. For reproducible sequences
use `new Random(seed)` instead.

**Example**

```ts
const roll: float64 = Math.random();
console.log(roll >= 0 && roll < 1); // true
```

### Math.approxEqual

```ts
static approxEqual(a: float64, b: float64, epsilon?: float64): boolean
```

True if `|a - b| ≤ epsilon`. `epsilon` defaults to a small value
appropriate for IEEE-754 doubles. Use this instead of `==` for
float comparisons.

**Example**

```ts
console.log(Math.approxEqual(0.1 + 0.2, 0.3)); // true
```

### Math.clamp

```ts
static clamp(x: float64, min: float64, max: float64): float64
```

Clamp `x` into `[min, max]`.

**Example**

```ts
console.log(Math.clamp(15, 0, 10)); // 10
```

### Math.lerp

```ts
static lerp(a: float64, b: float64, t: float64): float64
```

Linear interpolation. `t = 0` returns `a`, `t = 1` returns `b`.
`t` outside `[0, 1]` extrapolates.

**Example**

```ts
console.log(Math.lerp(10, 20, 0.25)); // 12.5
```

### Math.inverseLerp

```ts
static inverseLerp(a: float64, b: float64, value: float64): float64
```

Inverse of `lerp` — returns the `t` such that
`lerp(a, b, t) === value`. Returns 0 when `a === b`.

**Example**

```ts
console.log(Math.inverseLerp(10, 20, 15)); // 0.5
```

### Math.map

```ts
static map(value: float64, inMin: float64, inMax: float64, outMin: float64, outMax: float64): float64
```

Linearly remap `value` from `[inMin, inMax]` to
`[outMin, outMax]`. Equivalent to
`lerp(outMin, outMax, inverseLerp(inMin, inMax, value))`.

### Math.smoothstep

```ts
static smoothstep(edge0: float64, edge1: float64, x: float64): float64
```

Hermite smoothstep. Returns 0 below `edge0`, 1 above `edge1`,
and a smooth `3t² - 2t³` curve between. Derivative is zero at
both endpoints.

**Example**

```ts
console.log(Math.smoothstep(0, 1, 0.5)); // 0.5
```

### Math.wrap

```ts
static wrap(value: float64, lo: float64, hi: float64): float64
```

Wrap `value` into the half-open range `[lo, hi)`. Useful for
angle normalisation: `wrap(angle, 0, TAU)`.

**Example**

```ts
console.log(Math.wrap(370, 0, 360)); // 10
```

### Math.snap

```ts
static snap(value: float64, step: float64): float64
```

Snap `value` to the nearest multiple of `step`.

**Example**

```ts
console.log(Math.snap(13, 5)); // 15
```

### Math.moveTowards

```ts
static moveTowards(current: float64, target: float64, maxDelta: float64): float64
```

Move `current` toward `target` by at most `maxDelta`. Stops
exactly at `target` when within range. Frame-rate-friendly
substitute for raw subtraction.

**Example**

```ts
console.log(Math.moveTowards(0, 10, 3)); // 3
```

---

*Generated from `lang/types/builtin_math.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/net

# net

TCP sockets.

::: tip Import
```ts
import { TcpSocket, TcpServer, TcpFraming, Net, ... } from "net";
```

Needs the `"net"` permission in `thicket.json`.
:::

## TcpSocket <Badge type="info" text="class" />

```ts
class TcpSocket
```

A connected TCP socket for bidirectional communication.

### TcpSocket.remoteAddress

```ts
remoteAddress: string
```

Remote peer address (IP or hostname).

### TcpSocket.remotePort

```ts
remotePort: int
```

Remote peer port.

### TcpSocket.localPort

```ts
localPort: int
```

Local bound port.

### TcpSocket.write

```ts
write(data: string | ByteArray): boolean
```

Write `data` (string or ByteArray) to the socket. Returns true if the socket accepted the data, false if the write buffer is full and backpressure should be applied.

### TcpSocket.close

```ts
close(): void
```

Close the socket, terminating the connection.

### TcpSocket.onData

```ts
onData(fn: (data: string) => void): void
```

Register a callback invoked when text data arrives on the socket. @param fn Callback receiving the data string.

### TcpSocket.onBinary

```ts
onBinary(fn: (data: ByteArray) => void): void
```

Register a callback invoked when binary data arrives on the socket. @param fn Callback receiving the data as a ByteArray.

### TcpSocket.onClose

```ts
onClose(fn: () => void): void
```

Register a callback invoked when the socket closes. @param fn Callback with no arguments.

### TcpSocket.onError

```ts
onError(fn: (error: string) => void): void
```

Register a callback invoked on socket errors. @param fn Callback receiving an error message string.

### TcpSocket.setNoDelay

```ts
setNoDelay(enabled: boolean): void
```

Enable or disable Nagle's algorithm. Enabled by default; set to false for real-time data.

### TcpSocket.setKeepAlive

```ts
setKeepAlive(enabled: boolean, delaySeconds?: int): void
```

Enable or disable TCP keepalive. Enabled by default. @param enabled Whether keepalive is active. @param delaySeconds Time in seconds before the first keepalive probe (default 60).

### TcpSocket.onPacket

```ts
onPacket(fn: (packet: ByteArray) => void): void
```

Register a callback invoked when a framed packet arrives (if framing is enabled on this socket). @param fn Callback receiving the packet data as a ByteArray.

### TcpSocket.onDrain

```ts
onDrain(fn: () => void): void
```

Register a callback invoked when the write buffer drains (after backpressure clears). @param fn Callback with no arguments.

### TcpSocket.writePacket

```ts
writePacket(data: ByteArray): boolean
```

Write a framed packet to the socket if framing is enabled. Returns true if accepted, false if backpressured.

## TcpServer <Badge type="info" text="class" />

```ts
class TcpServer
```

A listening TCP server socket that accepts inbound client connections.

### TcpServer.address

```ts
address: string
```

Local address the server is bound to.

### TcpServer.port

```ts
port: int
```

Local port the server is listening on.

### TcpServer.onConnection

```ts
onConnection(fn: (socket: TcpSocket) => void): void
```

Register a callback invoked each time a client connects. @param fn Callback receiving the connected TcpSocket.

### TcpServer.close

```ts
close(options?: TcpCloseOptions): Promise<void>
```

Close the server, optionally forcibly terminating active connections. Returns a promise that resolves when all connections are closed or the timeout expires.

### TcpServer.connectionCount

```ts
connectionCount: int
```

Current number of active client connections.

### TcpServer.connections

```ts
connections: Array<TcpSocket>
```

Array of active client TcpSocket connections.

### TcpServer.broadcast

```ts
broadcast(data: string | ByteArray): boolean
```

Broadcast `data` (string or ByteArray) to all connected clients. Returns true if all accepts succeeded, false if any failed.

## TcpFraming <Badge type="info" text="class" />

```ts
class TcpFraming
```

Packet framing modes for TCP sockets.

### TcpFraming.RAW

```ts
static RAW: int
```

No framing; raw bytes.

### TcpFraming.LENGTH32

```ts
static LENGTH32: int
```

32-bit big-endian length prefix, then payload bytes.

### TcpFraming.LINE

```ts
static LINE: int
```

Line-delimited; packets end with `\n`.

## TcpListenOptions <Badge type="info" text="class" />

```ts
class TcpListenOptions
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Configuration options for `Tcp.listen()`.

### TcpListenOptions.host

```ts
host?: string
```

Local address to bind to (default "127.0.0.1").

### TcpListenOptions.framing

```ts
framing?: int
```

Packet framing mode: TcpFraming.RAW, LENGTH32, or LINE (default RAW).

### TcpListenOptions.maxConnections

```ts
maxConnections?: int
```

Maximum concurrent connections to accept (default unlimited).

### TcpListenOptions.idleTimeout

```ts
idleTimeout?: int
```

Close idle connections after this many milliseconds of inactivity (default no timeout).

## TcpCloseOptions <Badge type="info" text="class" />

```ts
class TcpCloseOptions
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Configuration options for `TcpServer.close()`.

### TcpCloseOptions.closeActive

```ts
closeActive?: boolean
```

If true, forcibly close all active connections; if false, gracefully drain them (default false).

### TcpCloseOptions.timeoutMs

```ts
timeoutMs?: int
```

Timeout in milliseconds to wait for graceful closure before forcing (default 30000).

## Net <Badge type="info" text="static class" />

```ts
static class Net
```

Compatibility alias for Tcp. Prefer Tcp in new code.

### Net.connect

```ts
static connect(host: string, port: int): any
```

Connect to a TCP server. Equivalent to `Tcp.connect`.

### Net.listen

```ts
static listen(port: int, hostOrOptions?: string | TcpListenOptions): any
```

Listen for inbound TCP connections. Equivalent to `Tcp.listen`.

## Tcp <Badge type="info" text="static class" />

```ts
static class Tcp
```

TCP socket client and server API.

### Tcp.connect

```ts
static connect(host: string, port: int): any
```

Connect to a TCP server at the given `host` and `port`. Returns a promise that resolves to a TcpSocket, or rejects on connection failure.

### Tcp.listen

```ts
static listen(port: int, options?: TcpListenOptions): any
```

Listen for inbound TCP connections on the given `port`. Returns a promise that resolves to a TcpServer, or rejects if the port cannot be bound.

---

*Generated from `lang/types/net.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/numerics

# Number conversions

Conversion functions and constants for numbers: `Int(x)`, `Float(x)`, `Int.MAX`, `Number.isInteger` and friends. The types themselves are lowercase: `int`, `uint`, `float`, and `int8` to `float32` for packed storage.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Number <Badge type="info" text="conversion" />

```ts
Number(value: any): float64
```

Coerce `value` to the most appropriate numeric form: an `int` when
the value fits in int32, a `uint` when it fits in uint32, otherwise
a `float64`. Strings parse as decimal numbers; non-numeric strings
yield `NaN`. Booleans become 0 or 1; objects are `NaN`.

Carries static helpers: `Number.isFinite`, `Number.isNaN`,
`Number.isInteger`, `Number.parseInt`, `Number.parseFloat`.

### Number.toFixed

```ts
toFixed(digits?: int): string
```

Instance surface shared by every numeric type (`Int8` through
`Float`): a method declared here works on all of them.

### Number.toString

```ts
toString(radix?: int): string
```

Format the number as a string; `radix` selects the base.

### Number.isFinite

```ts
static isFinite(value: any): boolean
```

`true` for an int, uint, or finite float; `false` for `NaN`, infinities, and non-numbers.

### Number.isNaN

```ts
static isNaN(value: any): boolean
```

`true` only for a float `NaN`; any non-number is `false`.

### Number.isInteger

```ts
static isInteger(value: any): boolean
```

`true` for an int or uint, or a finite float with no fraction; `false` otherwise.

**Example**

```ts
console.log(Number.isInteger(5)); // true
console.log(Number.isInteger(5.5)); // false
```

### Number.parseInt

```ts
static parseInt(value: string, radix?: int): int
```

Parse the leading integer of a string (decimal); `NaN` when it does not start with a number. A numeric argument truncates toward zero.

### Number.parseFloat

```ts
static parseFloat(value: string): float64
```

Parse a decimal number from the start of a string; `NaN` when it does not start with a number.

## Boolean <Badge type="info" text="class" />

```ts
class Boolean
```

*Final: it cannot be subclassed.*

Convert `value` to its truthiness. Strings, arrays, maps, and
objects are truthy; `0`, `NaN`, `""`, `null`, and `undefined` are
falsy.

### Boolean.callable

```ts
callable(value: any): boolean
```

Convert `value` to its truthiness; `Boolean(0)` is `false`.

### Boolean.valueOf

```ts
valueOf(): boolean
```

Return the boolean itself.

### Other members of Boolean

```ts
toString(): string
```

## Int <Badge type="info" text="conversion" />

```ts
Int(value: any, radix?: int): int
```

Convert `value` to a 32-bit signed integer. Floats truncate toward
zero; strings parse in `radix` (default auto-detect: `0x` hex,
`0b` binary, `0o` octal, otherwise decimal). Throws on
out-of-range or non-coercible input. Use `tryInt` for the
non-throwing variant.

### Int.MAX

```ts
static readonly MAX: int
```

Largest `Int` value.

### Int.MIN

```ts
static readonly MIN: int
```

Smallest `Int` value.

### Int.wrap

```ts
static wrap(value: float): int
```

Two's-complement wrap of `value` (fraction truncated toward zero) into `int`. Never raises for a finite number.

### Int.clamp

```ts
static clamp(value: float): int
```

Saturate `value` (fraction truncated toward zero) to the `int` range. Never raises for a finite number.

## Int8 <Badge type="info" text="conversion" />

```ts
Int8(value: any, radix?: int): int
```

Convert `value` to an 8-bit signed integer in `[-128, 127]`. Throws
`RangeError` if outside that range. `radix` applies to string
inputs.

### Int8.MAX

```ts
static readonly MAX: int
```

Largest `Int8` value.

### Int8.MIN

```ts
static readonly MIN: int
```

Smallest `Int8` value.

### Int8.wrap

```ts
static wrap(value: float): int
```

Two's-complement wrap of `value` (fraction truncated toward zero) into `int8`. Never raises for a finite number.

### Int8.clamp

```ts
static clamp(value: float): int
```

Saturate `value` (fraction truncated toward zero) to the `int8` range. Never raises for a finite number.

## Int16 <Badge type="info" text="conversion" />

```ts
Int16(value: any, radix?: int): int
```

Convert `value` to a 16-bit signed integer in `[-32768, 32767]`.

### Int16.MAX

```ts
static readonly MAX: int
```

Largest `Int16` value.

### Int16.MIN

```ts
static readonly MIN: int
```

Smallest `Int16` value.

### Int16.wrap

```ts
static wrap(value: float): int
```

Two's-complement wrap of `value` (fraction truncated toward zero) into `int16`. Never raises for a finite number.

### Int16.clamp

```ts
static clamp(value: float): int
```

Saturate `value` (fraction truncated toward zero) to the `int16` range. Never raises for a finite number.

## Int32 <Badge type="info" text="conversion" />

```ts
Int32(value: any, radix?: int): int
```

Convert `value` to a 32-bit signed integer (alias of the platform
int; same range as `Int`).

### Int32.MAX

```ts
static readonly MAX: int
```

Largest `Int32` value.

### Int32.MIN

```ts
static readonly MIN: int
```

Smallest `Int32` value.

### Int32.wrap

```ts
static wrap(value: float): int32
```

Two's-complement wrap of `value` (fraction truncated toward zero) into `int32`. Never raises for a finite number.

### Int32.clamp

```ts
static clamp(value: float): int32
```

Saturate `value` (fraction truncated toward zero) to the `int32` range. Never raises for a finite number.

## Float <Badge type="info" text="conversion" />

```ts
Float(value: any): float64
```

Convert `value` to a 64-bit float (alias of `Float64`). Strings
parse with `strtod`; non-coercible input throws.

### Float.MAX

```ts
static readonly MAX: float64
```

Largest `Float` value.

### Float.MIN_POSITIVE

```ts
static readonly MIN_POSITIVE: float64
```

Smallest positive normal `Float` value.

### Float.EPSILON

```ts
static readonly EPSILON: float64
```

Difference between 1 and the next larger `Float` value.

### Float.NaN

```ts
static readonly NaN: float64
```

Not-a-number value.

### Float.POSITIVE_INFINITY

```ts
static readonly POSITIVE_INFINITY: float64
```

Positive infinity.

### Float.NEGATIVE_INFINITY

```ts
static readonly NEGATIVE_INFINITY: float64
```

Negative infinity.

## Float64 <Badge type="info" text="conversion" />

```ts
Float64(value: any): float64
```

Convert `value` to a 64-bit float. Same as `Float`; the explicit
name is preferred when the bit width matters.

### Float64.MAX

```ts
static readonly MAX: float64
```

Largest `Float64` value.

### Float64.MIN_POSITIVE

```ts
static readonly MIN_POSITIVE: float64
```

Smallest positive normal `Float64` value.

### Float64.EPSILON

```ts
static readonly EPSILON: float64
```

Difference between 1 and the next larger `Float64` value.

### Float64.NaN

```ts
static readonly NaN: float64
```

Not-a-number value.

### Float64.POSITIVE_INFINITY

```ts
static readonly POSITIVE_INFINITY: float64
```

Positive infinity.

### Float64.NEGATIVE_INFINITY

```ts
static readonly NEGATIVE_INFINITY: float64
```

Negative infinity.

## Float32 <Badge type="info" text="conversion" />

```ts
Float32(value: any): float
```

Convert `value` to a 32-bit float. The result is rounded to float32
precision and returned as a float.

### Float32.MAX

```ts
static readonly MAX: float
```

Largest `Float32` value.

### Float32.MIN_POSITIVE

```ts
static readonly MIN_POSITIVE: float
```

Smallest positive normal `Float32` value.

### Float32.EPSILON

```ts
static readonly EPSILON: float
```

Difference between 1 and the next larger `Float32` value.

### Float32.NaN

```ts
static readonly NaN: float
```

Not-a-number value.

### Float32.POSITIVE_INFINITY

```ts
static readonly POSITIVE_INFINITY: float
```

Positive infinity.

### Float32.NEGATIVE_INFINITY

```ts
static readonly NEGATIVE_INFINITY: float
```

Negative infinity.

### Float32.round

```ts
static round(value: float): float
```

Round `value` to float32 precision. Overflow becomes `Infinity` or `-Infinity`; never raises.

## UInt <Badge type="info" text="conversion" />

```ts
UInt(value: any, radix?: int): uint
```

Convert `value` to a 32-bit unsigned integer (alias of `UInt32`).
Throws `RangeError` if negative or above `UINT32_MAX`.

### UInt.MAX

```ts
static readonly MAX: uint
```

Largest `UInt` value.

### UInt.MIN

```ts
static readonly MIN: uint
```

Smallest `UInt` value.

### UInt.wrap

```ts
static wrap(value: float): uint
```

Two's-complement wrap of `value` (fraction truncated toward zero) into `uint`. Never raises for a finite number.

### UInt.clamp

```ts
static clamp(value: float): uint
```

Saturate `value` (fraction truncated toward zero) to the `uint` range. Never raises for a finite number.

## UInt8 <Badge type="info" text="conversion" />

```ts
UInt8(value: any, radix?: int): uint
```

Convert `value` to an 8-bit unsigned integer in `[0, 255]`.

### UInt8.MAX

```ts
static readonly MAX: uint
```

Largest `UInt8` value.

### UInt8.MIN

```ts
static readonly MIN: uint
```

Smallest `UInt8` value.

### UInt8.wrap

```ts
static wrap(value: float): uint
```

Two's-complement wrap of `value` (fraction truncated toward zero) into `uint8`. Never raises for a finite number.

### UInt8.clamp

```ts
static clamp(value: float): uint
```

Saturate `value` (fraction truncated toward zero) to the `uint8` range. Never raises for a finite number.

## UInt16 <Badge type="info" text="conversion" />

```ts
UInt16(value: any, radix?: int): uint
```

Convert `value` to a 16-bit unsigned integer in `[0, 65535]`.

### UInt16.MAX

```ts
static readonly MAX: uint
```

Largest `UInt16` value.

### UInt16.MIN

```ts
static readonly MIN: uint
```

Smallest `UInt16` value.

### UInt16.wrap

```ts
static wrap(value: float): uint
```

Two's-complement wrap of `value` (fraction truncated toward zero) into `uint16`. Never raises for a finite number.

### UInt16.clamp

```ts
static clamp(value: float): uint
```

Saturate `value` (fraction truncated toward zero) to the `uint16` range. Never raises for a finite number.

## UInt32 <Badge type="info" text="conversion" />

```ts
UInt32(value: any, radix?: int): uint
```

Convert `value` to a 32-bit unsigned integer in `[0, 4294967295]`.

### UInt32.MAX

```ts
static readonly MAX: uint
```

Largest `UInt32` value.

### UInt32.MIN

```ts
static readonly MIN: uint
```

Smallest `UInt32` value.

### UInt32.wrap

```ts
static wrap(value: float): uint32
```

Two's-complement wrap of `value` (fraction truncated toward zero) into `uint32`. Never raises for a finite number.

### UInt32.clamp

```ts
static clamp(value: float): uint32
```

Saturate `value` (fraction truncated toward zero) to the `uint32` range. Never raises for a finite number.

---

*Generated from `lang/types/builtin_numerics.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/object

# Object

`Object` helpers and `Proxy`.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Object <Badge type="info" text="class" />

```ts
class Object
```

Object namespace. Static utilities for object reflection, property
inspection, and shallow copying.

### Object.keys

```ts
static keys(obj: any): Array<string>
```

Return an array of all own enumerable property names of `obj`.
Works on plain objects, class instances, and struct values.

### Object.values

```ts
static values(obj: any): Array<any>
```

Return an array of all own enumerable property values of `obj`.
Works on plain objects, class instances, and struct values.

### Object.entries

```ts
static entries(obj: any): Array<[string, any]>
```

Return an array of `[key, value]` pairs for all own enumerable
properties of `obj`. Works on plain objects, class instances,
and struct values.

### Object.fromEntries

```ts
static fromEntries(entries: Array<any>): any
```

Recreate an object from an array of key-value pairs.

### Object.assign

```ts
static assign(target: any, ...sources: Array<any>): any
```

Copy all own properties from one or more source objects into `target`.
Returns `target`.

### Object.freeze

```ts
static freeze(obj: any): any
```

Freeze `obj`, preventing all property additions, deletions,
and modifications. Returns `obj`.

### Object.seal

```ts
static seal(obj: any): any
```

Seal `obj`, preventing adding or removing properties, but allowing
modifications to existing property values. Returns `obj`.

### Object.isFrozen

```ts
static isFrozen(obj: any): boolean
```

Return `true` if `obj` is frozen, or if `obj` is a primitive.

### Object.isSealed

```ts
static isSealed(obj: any): boolean
```

Return `true` if `obj` is sealed or frozen, or if `obj` is a primitive.

### Object.hasOwn

```ts
static hasOwn(obj: any, prop: string): boolean
```

Return `true` if `obj` has `prop` as an own property.

## Proxy <Badge type="info" text="class" />

```ts
class Proxy
```

Base class for objects that answer undeclared names with code. Extend it
and override the hooks you need. A hook runs only when the name is not
declared on the class (declared fields, getters and methods resolve
normally and never reach a hook). On a value typed as a `Proxy`
subclass, an undeclared member is accepted and typed `any`.

### Proxy.getProperty

```ts
getProperty(name: string): any
```

Runs for `obj.name` / `obj[name]` when `name` is undeclared.

### Proxy.setProperty

```ts
setProperty(name: string, value: any): void
```

Runs for `obj.name = value` when `name` is undeclared.

### Proxy.callProperty

```ts
callProperty(name: string, ...args: Array<any>): any
```

Runs for `obj.name(...args)` when `name` is undeclared.

### Proxy.hasProperty

```ts
hasProperty(name: string): boolean
```

Runs for `name in obj` when `name` is undeclared.

### Proxy.deleteProperty

```ts
deleteProperty(name: string): boolean
```

Runs for `delete obj[name]` when `name` is undeclared.

### Other members of Proxy

```ts
constructor()
```

---

*Generated from `lang/types/builtin_object.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/primitives

# Number methods

Methods you can call on a number value, such as `n.toFixed(2)`. The class names on this page are internal; you never write them in code.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## NumericPrimitive <Badge type="info" text="class" />

```ts
class NumericPrimitive
```

The shared half of every numeric primitive's instance surface.
`valueOf` is not here because it returns the RECEIVER, so its type is
the receiver's own width; each subclass declares its own.

### NumericPrimitive.toFixed

```ts
toFixed(digits?: int): string
```

Fixed-point decimal rendering. `digits` is clamped to `[0, 100]`
and defaults to 0.

### NumericPrimitive.toString

```ts
toString(radix?: int): string
```

Decimal rendering, or base-`radix` when `radix` is given. `radix`
outside `[2, 36]` throws `RangeError`; a non-10 radix renders the
value truncated to an integer.

## IntPrimitive <Badge type="info" text="class" />

```ts
class IntPrimitive extends NumericPrimitive
```

Instance surface of the primitive `int`.

### IntPrimitive.valueOf

```ts
valueOf(): int
```

Return the receiver's value as an int.

## Int8Primitive <Badge type="info" text="class" />

```ts
class Int8Primitive extends NumericPrimitive
```

Instance surface of the primitive `int8`.

### Int8Primitive.valueOf

```ts
valueOf(): int
```

Return the receiver's value as an int.

## Int16Primitive <Badge type="info" text="class" />

```ts
class Int16Primitive extends NumericPrimitive
```

Instance surface of the primitive `int16`.

### Int16Primitive.valueOf

```ts
valueOf(): int
```

Return the receiver's value as an int.

## Int32Primitive <Badge type="info" text="class" />

```ts
class Int32Primitive extends NumericPrimitive
```

Instance surface of the primitive `int32`.

### Int32Primitive.valueOf

```ts
valueOf(): int32
```

Return the receiver's value as an int32.

## UintPrimitive <Badge type="info" text="class" />

```ts
class UintPrimitive extends NumericPrimitive
```

Instance surface of the primitive `uint`.

### UintPrimitive.valueOf

```ts
valueOf(): uint
```

Return the receiver's value as a uint.

## Uint8Primitive <Badge type="info" text="class" />

```ts
class Uint8Primitive extends NumericPrimitive
```

Instance surface of the primitive `uint8`.

### Uint8Primitive.valueOf

```ts
valueOf(): uint
```

Return the receiver's value as a uint.

## Uint16Primitive <Badge type="info" text="class" />

```ts
class Uint16Primitive extends NumericPrimitive
```

Instance surface of the primitive `uint16`.

### Uint16Primitive.valueOf

```ts
valueOf(): uint
```

Return the receiver's value as a uint.

## Uint32Primitive <Badge type="info" text="class" />

```ts
class Uint32Primitive extends NumericPrimitive
```

Instance surface of the primitive `uint32`.

### Uint32Primitive.valueOf

```ts
valueOf(): uint32
```

Return the receiver's value as a uint32.

## CharPrimitive <Badge type="info" text="class" />

```ts
class CharPrimitive
```

Instance surface of the primitive `char`: one ASCII character, held as
a one-character string. `c.code` is its character code.

### CharPrimitive.code

```ts
readonly code: int
```

The character code, 0 to 127.

### CharPrimitive.toString

```ts
toString(): string
```

Return the one-character string.

## Float32Primitive <Badge type="info" text="class" />

```ts
class Float32Primitive extends NumericPrimitive
```

Instance surface of the primitive `float32`.

### Float32Primitive.valueOf

```ts
valueOf(): float
```

Return the receiver's value as a float (float64).

## Float64Primitive <Badge type="info" text="class" />

```ts
class Float64Primitive extends NumericPrimitive
```

Instance surface of the primitive `float64`. `float` is a strict alias
of `float64`, so both spellings resolve here.

### Float64Primitive.valueOf

```ts
valueOf(): float64
```

Return the receiver's value as a float64.

---

*Generated from `lang/types/builtin_primitives.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/random

# Random

Seedable random number generators.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Random <Badge type="info" text="class" />

```ts
class Random
```

Seedable PRNG with deterministic output for a given seed. `fork(name)`
derives a child from the original seed and name, making sibling
branches order-independent.

### Random.seed

```ts
readonly seed: float64
```

The seed used to initialize this instance.

### new Random()

```ts
constructor(seed?: float64)
```

Create a new Random instance.

**Parameters**

- `seed`: Optional seed value (float64); if omitted, seeded from system clock.

### Random.fork

```ts
fork(): Random
fork(name: string): Random
```

Create a child Random instance derived from this instance's current state.

**Returns:** A new Random that advances this instance.

### Random.next

```ts
next(): float64
```

Return a pseudorandom float in [0.0, 1.0).

**Returns:** A float >= 0.0 and &lt; 1.0.

### Random.nextBool

```ts
nextBool(): boolean
```

Return a pseudorandom boolean with roughly 50% probability of true.

**Returns:** true or false.

### Random.nextFloat

```ts
nextFloat(min: float64, max: float64): float64
```

Return a pseudorandom float in [min, max).

**Parameters**

- `min`: Minimum (inclusive).
- `max`: Maximum (exclusive).

**Returns:** A float >= min and &lt; max.

### Random.nextInt

```ts
nextInt(min: int, max: int): int
```

Return a pseudorandom integer in [min, max].

**Parameters**

- `min`: Minimum (inclusive).
- `max`: Maximum (inclusive).

**Returns:** An integer >= min and &lt;= max.

### Random.pick

```ts
pick(array: Array<any>): any
```

Return a random element from an array.

**Parameters**

- `array`: The array to pick from.

**Returns:** An element chosen uniformly at random, or undefined if the array is empty.

### Random.shuffle

```ts
shuffle(array: Array<any>): Array<any>
```

Return a new array with elements randomly shuffled using Fisher-Yates.

**Parameters**

- `array`: The array to shuffle (not modified).

**Returns:** A new array with shuffled elements.

### Random.weighted

```ts
weighted(weights: Array<float64>): int
```

Return an index selected by weighted probability distribution.

**Parameters**

- `weights`: Array of non-negative weights; higher weight = higher probability.

**Returns:** An index (0 to weights.length - 1) selected by the weights.

---

*Generated from `lang/types/builtin_random.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/reactivity

# reactivity

Signals, refs, computed values and reactive collections.

::: tip Import
```ts
import { Signal, Ref, ReactiveArray, ReactiveRecord, ... } from "reactivity";
```
:::

## Signal <Badge type="info" text="class" />

```ts
class Signal<T>
```

Multicast event channel. Construct with `Signal()` (no `new`),
subscribe with `on` / `once`, fire with `emit`. Each listener
receives the emitted value as its single argument; `once`
listeners auto-unsubscribe after firing. `close` permanently
disables further `on` / `emit` calls.

### Signal.hasListeners

```ts
readonly hasListeners: boolean
```

True when at least one persistent or one-shot listener is attached.

### Signal.listenerCount

```ts
readonly listenerCount: uint
```

Total count of persistent and one-shot listeners.

### Signal.clear

```ts
clear(): void
```

Drop every listener. Does not close the signal.

### Signal.close

```ts
close(): void
```

Drop every listener and disable further `on` / `once` / `emit`.
Subsequent emits are silently ignored.

### Signal.emit

```ts
emit(value?: any): void
```

Invoke every listener with `value` as the single argument. When
omitted, listeners receive `undefined`.

### Signal.off

```ts
off(listener: any): void
```

Remove a previously attached persistent listener. No-op if
the listener was never attached.

### Signal.on

```ts
on(listener: any): Function
```

Attach a persistent listener. Returns a function that removes it.

### Signal.once

```ts
once(listener: any): Function
```

Attach a one-shot listener. Auto-removed after the next emit. Returns a function that removes it early.

## Ref <Badge type="info" text="class" />

```ts
class Ref<T>
```

Reactive value cell. Writes update `value` immediately, while listeners
run once at the next frame boundary. Multiple writes in one frame carry
the first old value and last new value to each listener.

### Ref.value

```ts
value: T
```

Tracked read and batched write access to the current value.

### Ref.dispose

```ts
dispose(): void
```

Permanently detach listeners and ignore later writes.

### Ref.freeze

```ts
freeze(): void
```

Suppress listener delivery until `unfreeze`.

### Ref.off

```ts
off(listener: any): void
```

Remove a persistent listener.

### Ref.on

```ts
on(listener: any): void
```

Register a batched `(newValue, oldValue)` listener.

### Ref.once

```ts
once(listener: any): void
```

Register a one-shot batched listener.

### Ref.peek

```ts
peek(): T
```

Read without dependency tracking.

### Ref.reset

```ts
reset(): void
```

Restore the constructor value through the normal batched setter.

### Ref.set

```ts
set(value: T): void
```

Update through the normal batched setter.

### Ref.silent

```ts
silent(value: T): void
```

Update without listeners or dependency invalidation.

### Ref.unfreeze

```ts
unfreeze(): void
```

Re-enable listener delivery.

## ReactiveArray <Badge type="info" text="class" />

```ts
class ReactiveArray<T>
```

Reactive ordered collection with Go willowui operation parity.

### ReactiveArray.at

```ts
at(index: int): T
```

Get the element at the given index, tracking access for reactivity.

### ReactiveArray.setAt

```ts
setAt(index: int, item: T): void
```

Replace the element at the given index and notify listeners.

### ReactiveArray.slice

```ts
slice(start: int, end?: int): Array<T>
```

Return a copy of the elements from start to end (end exclusive), without tracking.

### ReactiveArray.clone

```ts
clone(): ReactiveArray<T>
```

Return a new ReactiveArray with a copy of all items.

### ReactiveArray.version

```ts
version(): Ref<uint>
```

Return the version Ref: incremented on every change.

### ReactiveArray.lengthRef

```ts
lengthRef(): Ref<int>
```

Return the length Ref: tracks the current item count.

### ReactiveArray.push

```ts
push(...items: Array<T>): void
```

Append items to the end and notify listeners.

### ReactiveArray.pop

```ts
pop(): T
```

Remove and return the last item; no-op if the array is empty.

### ReactiveArray.unshift

```ts
unshift(...items: Array<T>): void
```

Insert items at the beginning and notify listeners.

### ReactiveArray.shift

```ts
shift(): T
```

Remove and return the first item; no-op if the array is empty.

### ReactiveArray.insert

```ts
insert(index: int, item: T): void
```

Insert an item at the given index, shifting others to the right.

### ReactiveArray.remove

```ts
remove(index: int): void
```

Remove the item at the given index.

### ReactiveArray.removeAt

```ts
removeAt(index: int): void
```

Remove the item at the given index (same as `remove`).

### ReactiveArray.splice

```ts
splice(start: int, deleteCount: int, ...items: Array<T>): void
```

Remove deleteCount items starting at start, optionally inserting new items.

### ReactiveArray.swap

```ts
swap(left: int, right: int): void
```

Swap the elements at left and right indices.

### ReactiveArray.move

```ts
move(sourceIndex: int, targetIndex: int): void
```

Move the item at sourceIndex to targetIndex.

### ReactiveArray.reverse

```ts
reverse(): void
```

Reverse the array in-place.

### ReactiveArray.sort

```ts
sort(compare: Function): void
```

Sort the array in-place using the compare function.

### ReactiveArray.shuffle

```ts
shuffle(): void
```

Randomly shuffle the array in-place.

### ReactiveArray.set

```ts
set(items: Array<T>): void
```

Replace all items with the given array.

### ReactiveArray.fill

```ts
fill(value: T, start: int, end: int): void
```

Fill elements from start to end (end exclusive) with the given value.

### ReactiveArray.truncate

```ts
truncate(length: int): void
```

Remove all items after the given length.

### ReactiveArray.clear

```ts
clear(): void
```

Remove all items.

### ReactiveArray.reserve

```ts
reserve(capacity: int): void
```

Reserve capacity (no-op).

### ReactiveArray.shrink

```ts
shrink(): void
```

Shrink the array to fit (creates a copy).

### ReactiveArray.batch

```ts
batch(fn: Function): void
```

Run the function with change notifications batched until it returns.

### ReactiveArray.find

```ts
find(fn: Function): any
```

Return the first item matching the predicate, or undefined.

### ReactiveArray.findIndex

```ts
findIndex(fn: Function): int
```

Return the index of the first item matching the predicate, or -1.

### ReactiveArray.some

```ts
some(fn: Function): boolean
```

Return true if any item matches the predicate.

### ReactiveArray.every

```ts
every(fn: Function): boolean
```

Return true if all items match the predicate.

### ReactiveArray.forEach

```ts
forEach(fn: Function): void
```

Call the function for each item with (index, item).

### ReactiveArray.filter

```ts
filter(fn: Function): ReactiveArray<T>
```

Return a new ReactiveArray with items matching the predicate.

### ReactiveArray.concat

```ts
concat(...others: Array<ReactiveArray<T>>): ReactiveArray<T>
```

Return a new ReactiveArray with items from this array and all others concatenated.

### ReactiveArray.onChange

```ts
onChange(fn: Function): Function
```

Subscribe to any change; returns a function that unsubscribes.

### ReactiveArray.onAdded

```ts
onAdded(fn: Function): Function
```

Subscribe to item additions; returns a function that unsubscribes.

### ReactiveArray.onRemoved

```ts
onRemoved(fn: Function): Function
```

Subscribe to item removals; returns a function that unsubscribes.

### ReactiveArray.onMoved

```ts
onMoved(fn: Function): Function
```

Subscribe to item moves; returns a function that unsubscribes.

### ReactiveArray.onReplaced

```ts
onReplaced(fn: Function): Function
```

Subscribe to bulk replacements; returns a function that unsubscribes.

### ReactiveArray.onItemChanged

```ts
onItemChanged(fn: Function): Function
```

Subscribe to item updates; returns a function that unsubscribes.

### Other members of ReactiveArray

```ts
readonly length: int
constructor()
constructor(items: Array<T>)
```

## ReactiveRecord <Badge type="info" text="class" />

```ts
class ReactiveRecord<V>
```

Reactive string-keyed collection with independently tracked values.

### ReactiveRecord.delete

```ts
delete(key: string): void
```

Remove a key and notify listeners.

### ReactiveRecord.get

```ts
get(key: string): V | undefined
```

Get the current value of a key, or undefined if not set.

### ReactiveRecord.has

```ts
has(key: string): boolean
```

Return true if the key exists.

### ReactiveRecord.keys

```ts
keys(): Array<string>
```

Return an array of all active keys.

### ReactiveRecord.onChange

```ts
onChange(fn: Function): Function
```

Subscribe to any change; returns a function that unsubscribes.

### ReactiveRecord.onFieldChange

```ts
onFieldChange(key: string, fn: Function): Function
```

Subscribe to changes of a specific key; returns a function that unsubscribes.

### ReactiveRecord.ref

```ts
ref(key: string): Ref<V>
```

Get the Ref for a key, creating one if needed.

### ReactiveRecord.set

```ts
set(key: string, value: V): void
```

Set the value of a key and notify listeners.

### ReactiveRecord.setMany

```ts
setMany(fields: Map<string, V>): void
```

Set multiple keys from a map.

### ReactiveRecord.toMap

```ts
toMap(): Map<string, V>
```

Return a copy of all keys and values as a Map.

### Other members of ReactiveRecord

```ts
constructor()
constructor(fields: Map<string, V>)
```

## Signal <Badge type="info" text="function" />

```ts
function Signal(...args: any[]): Signal<any>
```

Create a multicast event channel.

## Ref <Badge type="info" text="function" />

```ts
function Ref(...args: any[]): Ref<any>
```

Create a reactive value cell with an optional initial value.

## computed <Badge type="info" text="function" />

```ts
function computed(fn: Function): Ref<any>
```

Create a lazy derived value. Dependency invalidation is batched; the
callback re-evaluates only when a dirty value is read or observed.

## watchEffect <Badge type="info" text="function" />

```ts
function watchEffect(fn: Function): Function
```

Run `fn` immediately, auto-track every reactive read, then rerun it once
on the next frame when any current dependency changes. The returned
function stops the effect.

---

*Generated from `lang/types/reactivity.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/regexp

# RegExp

Regular expressions.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## RegExp <Badge type="info" text="class" />

```ts
class RegExp
```

`lastIndex` advances after `exec` when the `g` flag is set, matching
JS semantics.

### RegExp.dotAll

```ts
readonly dotAll: boolean
```

True if the `s` (dotAll) flag is set; . matches newlines.

### RegExp.flags

```ts
readonly flags: string
```

The flag string (e.g., "gi" for global and ignoreCase).

### RegExp.global

```ts
readonly global: boolean
```

True if the `g` (global) flag is set.

### RegExp.ignoreCase

```ts
readonly ignoreCase: boolean
```

True if the `i` (ignoreCase) flag is set.

### RegExp.multiline

```ts
readonly multiline: boolean
```

True if the `m` (multiline) flag is set; ^ and $ match line boundaries.

### RegExp.source

```ts
readonly source: string
```

The pattern string.

### RegExp.lastIndex

```ts
lastIndex: int
```

The index at which the next match search begins (for global regexes).
Advanced by `exec` and `test` when the `g` flag is set.

### new RegExp()

```ts
constructor(pattern: string, flags?: string)
```

Create a new regular expression.

**Parameters**

- `pattern`: The regex pattern string (e.g., "\\d+").
- `flags`: Optional flags: "i" (ignoreCase), "g" (global), "m" (multiline), "s" (dotAll).

**Throws:** SyntaxError if the pattern is invalid.

### RegExp.exec

```ts
exec(input: string): any
```

Execute a search for a match. Returns a match object with properties 0–N (full match and capture groups),
`index` (position in input), `input` (the original string), and `length` (1 + capture group count).
Returns null if no match.

**Parameters**

- `input`: The string to search in.

**Returns:** A match object or null.

### RegExp.test

```ts
test(input: string): boolean
```

Test whether the pattern matches the string.

**Parameters**

- `input`: The string to test.

**Returns:** true if a match was found, false otherwise.

### RegExp.toString

```ts
toString(): string
```

Return the regex as a string in `/pattern/flags` format.

**Returns:** The regex string representation.

---

*Generated from `lang/types/builtin_regexp.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/shell

# shell

Run child processes.

::: tip Import
```ts
import { ShellResult, ShellProcess, Shell } from "shell";
```

Needs the `"shell"` permission in `thicket.json`.
:::

## ShellResult <Badge type="info" text="class" />

```ts
class ShellResult
```

### ShellResult.exitCode

```ts
exitCode: int
```

Exit code of the child process.

### ShellResult.ok

```ts
ok: boolean
```

True if `exitCode` is 0.

### ShellResult.stderr

```ts
stderr: string
```

Standard error output from the child process.

### ShellResult.stdout

```ts
stdout: string
```

Standard output from the child process.

## ShellProcess <Badge type="info" text="class" />

```ts
class ShellProcess
```

### ShellProcess.kill

```ts
kill(signal?: string): void
```

Send a signal to the child process. `signal` defaults to `"SIGTERM"`;
recognized signals include `"SIGTERM"`, `"SIGKILL"`, `"SIGSTOP"`, `"SIGCONT"`, `"SIGINT"`.

**Parameters**

- `signal`: Signal name as a string; defaults to `"SIGTERM"`.

### ShellProcess.on

```ts
on(event: string, handler: any): void
```

Register an event handler. Recognized events: `"exit"` (passes exit code),
`"stdout"` (passes accumulated stdout data), `"stderr"` (passes accumulated stderr data).

**Parameters**

- `event`: Event name: `"exit"`, `"stdout"`, or `"stderr"`.
- `handler`: Callback; receives the event data (exit code as int, or data as string).

## Shell <Badge type="info" text="static class" />

```ts
static class Shell
```

### Shell.exec

```ts
static exec(cmd: string, opts?: any): any
```

Execute a command synchronously and return a Promise&lt;ShellResult>. The command string
is parsed (no shell expansion; supports single and double quotes and backslash escapes).
Options may include `cwd` (working directory) and `timeout` (milliseconds).

**Parameters**

- `cmd`: Command string to parse and execute.
- `opts`: Optional `{cwd?: string, timeout?: int}`.

**Returns:** Promise that resolves to a ShellResult when the process exits.

### Shell.spawn

```ts
static spawn(cmd: string): any
```

Spawn a child process and return a ShellProcess handle (Unix/Linux only).
The command string is parsed the same way as `exec`. Output is streamed to handlers
registered via `process.on("stdout"|"stderr"|"exit", ...)`.

**Parameters**

- `cmd`: Command string to parse and execute.

**Returns:** ShellProcess; use `.on()` to listen for output and exit.

---

*Generated from `lang/types/shell.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/string

# String

The string type and its methods.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## String <Badge type="info" text="class" />

```ts
class String
```

*Final: it cannot be subclassed.*

Instance surface for the primitive `string` type. Strings are
immutable: every method that "modifies" the string returns a new
value; the receiver is never mutated.

Pattern-accepting methods (`match`, `matchAll`, `replace`,
`replaceAll`, `search`, `split`) accept either a `string` (treated
as a literal substring) or a `RegExp`.

### String.length

```ts
readonly length: int
```

Length in bytes (not Unicode code points).

### String.toLowerCase

```ts
toLowerCase(): string
```

Lowercase every ASCII letter. Non-ASCII passes through unchanged.

### String.toUpperCase

```ts
toUpperCase(): string
```

Uppercase every ASCII letter. Non-ASCII passes through unchanged.

### String.toTitleCase

```ts
toTitleCase(): string
```

Capitalize the first character of every word. Words are
separated by space, hyphen, or underscore.

### String.toCamelCase

```ts
toCamelCase(): string
```

Convert space-, hyphen-, or underscore-separated words to
camelCase. The first word stays lowercase; subsequent words
have their first letter uppercased.

### String.toSnakeCase

```ts
toSnakeCase(): string
```

Convert to `snake_case`. Spaces and hyphens become
underscores; uppercase ASCII letters introduce an underscore
before being lowercased (except in runs of consecutive
uppercase letters).

### String.toKebabCase

```ts
toKebabCase(): string
```

Convert to `kebab-case`. Spaces and underscores become
hyphens; uppercase ASCII letters introduce a hyphen before
being lowercased (except in runs of consecutive uppercase
letters).

### String.endsWith

```ts
endsWith(searchString: string): boolean
```

True when the string ends with `searchString`.

### String.includes

```ts
includes(searchString: string): boolean
```

True when `searchString` appears anywhere in the string.

### String.indexOf

```ts
indexOf(searchString: string, fromIndex?: int): int
```

Return the index of the first occurrence of `searchString` at
or after `fromIndex` (default `0`), or `-1` if not found.

### String.lastIndexOf

```ts
lastIndexOf(searchString: string): int
```

Return the index of the last occurrence of `searchString`, or
`-1` if not found.

### String.match

```ts
match(regexp: any): any
```

Match against a `string` or `RegExp`. Returns `null` on no
match, or a match object (full match at key `0`, captured
groups at `1..n`, plus `index`, `input`, `length`). With a
global RegExp, returns an array of full-match strings instead.

### String.matchAll

```ts
matchAll(regexp: any): Array<any>
```

Match all occurrences of a `string` or `RegExp`. Returns an
array of match objects (same shape as `match`). Always
returns an array, never `null`.

### String.search

```ts
search(pattern: any): int
```

Return the index of the first match for a `string` or
`RegExp`, or `-1` if not found. Like `indexOf` but accepts
patterns.

### String.startsWith

```ts
startsWith(searchString: string): boolean
```

True when the string starts with `searchString`.

### String.at

```ts
at(index: int): string
```

Return the single character at `index`. Negative indices
count from the end. Returns the empty string if out of range.

### String.charAt

```ts
charAt(index: int): string
```

Return the single character at `index`. Returns the empty
string if out of range.

### String.charCodeAt

```ts
charCodeAt(index: int): int
```

Return the byte value at `index`, or `NaN` if out of range.

### String.slice

```ts
slice(start?: int, end?: int): string
```

Return the substring from `start` (default `0`) up to but not
including `end` (default end-of-string). Negative indices
count from the end.

### String.substring

```ts
substring(start: int, end?: int): string
```

Return the substring from `start` up to but not including
`end` (default end-of-string). Negative indices clamp to
`0`; if `start > end`, the arguments are swapped.

### String.left

```ts
left(n: int): string
```

Return the first `n` characters. If `n` is at least the length
of the string, the whole string. `n` of `0` gives `""`. A
negative `n` throws a `RangeError`.

### String.right

```ts
right(n: int): string
```

Return the last `n` characters. If `n` is at least the length
of the string, the whole string. `n` of `0` gives `""`. A
negative `n` throws a `RangeError`.

### String.mid

```ts
mid(start: int, n?: int): string
```

Return `n` characters starting at the 0-based index `start`, or
everything to the end when `n` is omitted. A `start` past the
end gives `""`. A negative `start` or `n` throws a `RangeError`.

### String.concat

```ts
concat(...strings: Array<string>): string
```

Return the receiver concatenated with each argument in order.

### String.padEnd

```ts
padEnd(targetLength: int, padString?: string): string
```

Pad the right end with `padString` (default `" "`) until the
total length reaches `targetLength`. Returns the receiver
unchanged if it is already long enough.

### String.padStart

```ts
padStart(targetLength: int, padString?: string): string
```

Pad the left end with `padString` (default `" "`) until the
total length reaches `targetLength`. Returns the receiver
unchanged if it is already long enough.

### String.repeat

```ts
repeat(count: int): string
```

Repeat the string `count` times. `count` must be non-negative.

### String.replace

```ts
replace(search: any, replacement: any): string
```

Replace the first match of `search` (a `string` or `RegExp`)
with `replacement`. `replacement` may be a string or a
function called with the match details.

### String.replaceAll

```ts
replaceAll(search: any, replacement: any): string
```

Replace every match of `search` (a `string` or `RegExp`) with
`replacement`. `replacement` may be a string or a function
called with each match's details.

### String.reverse

```ts
reverse(): string
```

Return the string with its bytes reversed.

### String.split

```ts
split(separator: any, limit?: int): Array<string>
```

Split the string on `separator` (a `string` or `RegExp`).
Returns an array of pieces, capped at `limit` when provided.

### String.toString

```ts
toString(): string
```

Return the receiver. Provided for symmetry with other types.

### String.trim

```ts
trim(): string
```

Strip leading and trailing whitespace.

### String.trimEnd

```ts
trimEnd(): string
```

Strip trailing whitespace.

### String.trimStart

```ts
trimStart(): string
```

Strip leading whitespace.

### String.truncate

```ts
truncate(maxLen: int, suffix?: string): string
```

Truncate to at most `maxLen` bytes, appending `suffix`
(default `"..."`) when truncation actually occurs. The total
length of the result, including suffix, will not exceed
`maxLen`.

### String.valueOf

```ts
valueOf(): string
```

Return the receiver (the string itself), like `toString()`.

### String.fromBase64

```ts
static fromBase64(encoded: string): string
```

Decode a base64 string into its raw byte string.

### String.fromHex

```ts
static fromHex(hex: string): string
```

Decode a hex string into its raw byte string.

### String.fromCharCode

```ts
static fromCharCode(...codes: Array<int>): string
```

Build a string from UTF-16 code units, like TypeScript. Each
argument is reduced to 16 bits. Strings are UTF-8, so units are
stored as UTF-8: a high plus low surrogate pair becomes one
code point, and a lone surrogate becomes U+FFFD.

**Example**

```ts
console.log(String.fromCharCode(72, 105)); // Hi
```

### String.toBase64

```ts
static toBase64(data: string): string
```

Encode a byte string as base64.

### String.toHex

```ts
static toHex(data: string): string
```

Encode a byte string as lowercase hex.

---

*Generated from `lang/types/builtin_string.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/system

# App and System

The app lifecycle (`App`), process and platform info (`System`), and autotest hooks.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## App <Badge type="info" text="static class" />

```ts
static class App
```

The application lifecycle surface shared by console and windowed
programs. `App.onFrame` is the canonical frame hook. Window projects
additionally provide the resize and focus lifecycle callbacks.

### App.onTick

```ts
static onTick(handler: any): Function
```

Registers a fixed-tick handler, called once per logic tick (`App.tps`
per second, catching up to `maxCatchUpTicks` ticks after a slow
frame). Returns the function that unsubscribes it. A console program
with a tick handler keeps running until `App.quit()`.

### App.ticker

```ts
static readonly ticker: Ticker
```

The app-lifetime `Ticker` (`App.ticker.every(1, fn)`, `await App.ticker.wait(2)`), advanced once per scaled
tick by the runtime, after `App.onTick` handlers. Created on first use. Reading it makes the program tick
(a console program with ticker entries runs until `App.quit()`).

### App.tps

```ts
static tps: float
```

Logic ticks per second (default 60; also `tps` in thicket.json). Set to `App.SYNC_WITH_FPS` for one tick per drawn frame.

### App.SYNC_WITH_FPS

```ts
static readonly SYNC_WITH_FPS: float
```

`App.tps` value that runs one tick per drawn frame.

### App.tickDelta

```ts
static readonly tickDelta: float
```

Seconds per tick: `1 / tps` (this frame's `dt` in `SYNC_WITH_FPS` mode).

### App.tick

```ts
static readonly tick: int
```

Ticks run since start; during a tick handler, the index of that tick.

### App.time

```ts
static readonly time: float
```

Scaled seconds since start, advanced per tick.

### App.realTime

```ts
static readonly realTime: float
```

Unscaled wall seconds since start.

### App.tickAlpha

```ts
static readonly tickAlpha: float
```

How far the current frame is between the last tick and the next, 0 to 1.

### App.actualTps

```ts
static readonly actualTps: float
```

Ticks per second measured over the last second.

### App.actualFps

```ts
static readonly actualFps: float
```

Frames per second measured over the last second.

### App.maxCatchUpTicks

```ts
static maxCatchUpTicks: int
```

Most ticks run per frame to catch up (default 8); the excess is dropped.

### App.droppedTicks

```ts
static readonly droppedTicks: int
```

Ticks dropped because a frame needed more than `maxCatchUpTicks`.

### App.maxFrameDelta

```ts
static maxFrameDelta: float
```

The longest `dt` the frame phase sees, in seconds (default 0.25).

### App.timeScale

```ts
static timeScale: float
```

Scales `App.time` (default 1).

### Other members of App

```ts
static onFrame(handler: any): Function
static onQuit(handler: any): Function
static onResize(handler: any): Function
static onFocus(handler: any): Function
static onBlur(handler: any): Function
static quit(code?: int): void
```

## Autotest <Badge type="info" text="static class" />

```ts
static class Autotest
```

Hooks for `thicket run --autotest` scripts. Present in every program;
outside `--autotest` nothing reads them.

### Autotest.probe

```ts
static probe(id: string, probe: () => boolean): void
```

Names a condition an autotest script can wait on:
`{ "action": "wait_until", "probe": "<id>", "max": 600 }` holds the
script until `probe` returns true, checking once per frame for at
most `max` frames (default 600), and fails the step if it never does.
Registering the same id again replaces the probe.

## System <Badge type="info" text="static class" />

```ts
static class System
```

Process-level introspection and lifecycle. `System` is pre-bound
in every scope (no import required) and is frozen at startup; its
fields cannot be reassigned from script. It is a native static
class at runtime.

### System.capabilities

```ts
readonly capabilities: SystemCapabilities
```

Frozen host capabilities. Native-module fields describe modules
embedded in this host, independent of project permissions.
`gamepad`, `fullscreen`, and `persistentStorage` describe the
current host's runtime ability; engine targets populate those
meaningfully, while the headless `tks` CLI reports `false`.

### System.debug

```ts
readonly debug: SystemDebug
```

Runtime stack-trace diagnostics.

### System.audio

```ts
readonly audio: any
```

::: warning Deprecated
Use the imported `Audio` static class.
:::

### System.DARWIN

```ts
readonly DARWIN: string
```

Platform constant: `"darwin"`. Compare against `System.platform()`.

### System.LINUX

```ts
readonly LINUX: string
```

Platform constant: `"linux"`. Compare against `System.platform()`.

### System.WIN32

```ts
readonly WIN32: string
```

Platform constant: `"win32"`. Compare against `System.platform()`.

### System.WEB

```ts
readonly WEB: string
```

Platform constant: `"web"`. Compare against `System.platform()`.

### System.args

```ts
readonly args: string[]
```

Command-line arguments passed to the script, in order. Does
not include the interpreter path or the script path itself.

### System.isPackaged

```ts
readonly isPackaged: boolean
```

`true` when the program runs from a `thicket build` output (any
strategy, release or not); `false` under `thicket run`. Set before
the script starts, so it is readable at the top of a file.

### System.cwd

```ts
cwd(): string
```

Current working directory of the host process. Returns
`undefined` if the underlying `getcwd` call fails.

### System.storageDir

```ts
storageDir(): string
```

The app's persistent folder, for saves and settings. Created on
first call. Needs no permission: an app always owns it, and `Files`
reads and writes inside it pass without `fs` in thicket.json.

The folder is keyed by the app id (`id` in thicket.json, else the
project folder's name). Linux `$XDG_DATA_HOME` or `~/.local/share/<id>`;
Windows `%APPDATA%\<id>`; macOS `~/Library/Application Support/<id>`.
Returns `""` when no home folder is known.

### System.cacheDir

```ts
cacheDir(): string
```

The app's cache folder, always safe to delete (compiled themes,
baked fonts). Created on first call. Needs no permission, like
`storageDir()`. Linux `$XDG_CACHE_HOME` or `~/.cache/<id>`; Windows
`%LOCALAPPDATA%\<id>\Cache`; macOS `~/Library/Caches/<id>`.
Returns `""` when no home folder is known.

### System.exit

```ts
exit(code?: int): void
```

Request process exit. Runs every registered `onQuit`
handler before the host exits; the request is honored at
the next safe point in the VM loop, so callers see the
function return normally.

**Example**

```ts
System.exit(0);
```

### System.frameDepth

```ts
frameDepth(): int
```

Current call-stack frame depth. Diagnostic.

### System.gc

```ts
gc(): int
```

Run a garbage-collection cycle and return the number of
objects freed.

### System.instructions

```ts
instructions(): float64
```

Total instructions executed by the VM since startup.
Returned as `float64` because the count routinely exceeds
the `int32` range.

### System.memUsage

```ts
memUsage(): int
```

Bytes currently allocated by the VM (sum of live object
sizes). Diagnostic.

### System.objectCount

```ts
objectCount(): int
```

Number of live VM objects. Diagnostic.

### System.onFrame

```ts
onFrame(handler: any): Function
```

Migration alias for `App.onFrame`, retained for compatibility and
scheduled for removal. Window hosts invoke it once per frame;
console programs invoke it once per event-loop turn, after the
preceding Promise microtasks.

### System.onQuit

```ts
onQuit(handler: any): void
```

Register a callback to run during shutdown — after natural
completion, `System.exit()`, or SIGINT/SIGTERM. Handlers
run in registration order and are guaranteed to run at
most once. Late registrations made while shutdown is
already in progress are silently ignored.

### System.platform

```ts
platform(): string
```

Host platform: `"darwin"`, `"linux"`, `"win32"`, `"web"`,
or `"unknown"` if the build was made on an unrecognized
target. Equal to one of `DARWIN`/`LINUX`/`WIN32`/`WEB` by
construction on supported platforms.

**Example**

```ts
const os: string = System.platform();
console.log(os == "linux" || os == "darwin" || os == "win32" || os == "web"); // true
```

### System.scriptPath

```ts
scriptPath(): string
```

Absolute path to the running script. Returns `undefined`
when the VM was embedded without a script path (e.g.
`tks repl`).

### System.stackDepth

```ts
stackDepth(): int
```

Current operand-stack depth. Diagnostic.

### System.time

```ts
time(): float64
```

Wall-clock time as milliseconds since the Unix epoch.

**Example**

```ts
const msSinceEpoch: float64 = System.time();
console.log(msSinceEpoch > 0); // true
```

### System.uptime

```ts
uptime(): float64
```

Milliseconds elapsed since process start, measured against
the steady clock. Suitable for interval timing; not tied
to wall-clock changes.

### System.version

```ts
version(): string
```

Runtime version string (e.g. `"0.1.0"`).

**Example**

```ts
console.log(System.version());
```

## SystemDebug <Badge type="info" text="class" />

```ts
class SystemDebug
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Diagnostic helpers exposed through `System.debug`.

### SystemDebug.traceback

```ts
traceback(): string
```

Return the current ThicketScript call stack as a string.

## SystemCapabilities <Badge type="info" text="class" />

```ts
class SystemCapabilities
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Frozen fields exposed by `System.capabilities`. All capability
fields are present on every target so guarded branches type-check;
their values report host availability, not permission grants.

### SystemCapabilities.audio

```ts
readonly audio: boolean
```

Native `audio` module is embedded in this host.

### SystemCapabilities.bitmap

```ts
readonly bitmap: boolean
```

Native `bitmap` module is embedded in this host.

### SystemCapabilities.compress

```ts
readonly compress: boolean
```

Native `compress` module is embedded in this host.

### SystemCapabilities.crypto

```ts
readonly crypto: boolean
```

Native `crypto` module is embedded in this host.

### SystemCapabilities.database

```ts
readonly database: boolean
```

Native `database` module is embedded in this host.

### SystemCapabilities.env

```ts
readonly env: boolean
```

Native `env` module is embedded in this host.

### SystemCapabilities.events

```ts
readonly events: boolean
```

Native `events` module is embedded in this host.

### SystemCapabilities.fs

```ts
readonly fs: boolean
```

Native `fs` module is embedded in this host.

### SystemCapabilities.http

```ts
readonly http: boolean
```

Native `http` module is embedded in this host.

### SystemCapabilities.net

```ts
readonly net: boolean
```

Native `net` module is embedded in this host.

### SystemCapabilities.reactivity

```ts
readonly reactivity: boolean
```

The `reactivity` script module is embedded in this host.

### SystemCapabilities.shell

```ts
readonly shell: boolean
```

Native `shell` module is embedded in this host.

### SystemCapabilities.terminal

```ts
readonly terminal: boolean
```

Native `terminal` module is embedded in this host.

### SystemCapabilities.udp

```ts
readonly udp: boolean
```

Native `udp` module is embedded in this host.

### SystemCapabilities.wsClient

```ts
readonly wsClient: boolean
```

This host supports outbound WebSocket connections.

### SystemCapabilities.wsServer

```ts
readonly wsServer: boolean
```

This host supports listening for inbound WebSocket connections.

### SystemCapabilities.ws

```ts
readonly ws: boolean
```

::: warning Deprecated
Use `wsClient` or `wsServer`; equivalent to `wsClient || wsServer`.
:::

### SystemCapabilities.engine

```ts
readonly engine: boolean
```

Engine component `engine` is linked into this host.

### SystemCapabilities.willow

```ts
readonly willow: boolean
```

Engine component `willow` is linked into this host.

### SystemCapabilities.gamepad

```ts
readonly gamepad: boolean
```

Current host can receive gamepad input; `tks` reports `false`.

### SystemCapabilities.fullscreen

```ts
readonly fullscreen: boolean
```

Current host can enter fullscreen; `tks` reports `false`.

### SystemCapabilities.persistentStorage

```ts
readonly persistentStorage: boolean
```

Current host offers persistent storage; `tks` reports `false`.

---

*Generated from `lang/types/system.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/terminal

# terminal

Terminal input, output, cursor control and ANSI styling.

::: tip Import
```ts
import { Terminal } from "terminal";
```
:::

## TerminalSize <Badge type="info" text="class" />

```ts
class TerminalSize
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Dimensions returned by `Terminal.size()`.

### TerminalSize.rows

```ts
readonly rows: int
```

Terminal height in rows.

### TerminalSize.cols

```ts
readonly cols: int
```

Terminal width in columns.

## TerminalKeyEvent <Badge type="info" text="class" />

```ts
class TerminalKeyEvent
```

*Type only: the runtime hands you instances; you never construct it yourself.*

A keypress returned by `Terminal.readKey()`.

### TerminalKeyEvent.key

```ts
readonly key: string
```

The key name, e.g. "a", "Enter", "Escape", "ArrowUp".

### TerminalKeyEvent.ctrl

```ts
readonly ctrl: boolean
```

Whether Ctrl is held.

### TerminalKeyEvent.alt

```ts
readonly alt: boolean
```

Whether Alt is held.

### TerminalKeyEvent.shift

```ts
readonly shift: boolean
```

Whether Shift is held.

## Terminal <Badge type="info" text="static class" />

```ts
static class Terminal
```

Terminal I/O, cursor control, clearing, styling, and raw mode.

### Terminal.readLine

```ts
static readLine(prompt: string, defaultValue?: string): Promise<string>
```

Read a line from stdin with the given `prompt`, optionally initialised to `defaultValue`. Returns a promise that resolves to the entered text.

### Terminal.readPassword

```ts
static readPassword(prompt: string): Promise<string>
```

Read a password from stdin with the given `prompt`, echoing asterisks instead of characters. Returns a promise that resolves to the entered password.

### Terminal.readKey

```ts
static readKey(): Promise<TerminalKeyEvent>
```

Read a single keypress including modifier state (Ctrl, Alt, Shift). Returns a promise that resolves to a `TerminalKeyEvent`.

### Terminal.write

```ts
static write(text: string): void
```

Write `text` to stdout without moving the cursor or writing a newline.

**Example**

```ts
import { Terminal } from "terminal";
Terminal.write("loading...");
```

### Terminal.rewriteLine

```ts
static rewriteLine(text: string): void
```

Overwrite the current line with `text`, moving the cursor to the start.

### Terminal.size

```ts
static size(): TerminalSize
```

Query the terminal dimensions. Returns `{rows, cols}`.

### Terminal.moveTo

```ts
static moveTo(row: int, col: int): void
```

Move the cursor to `(row, col)` (1-indexed).

### Terminal.moveUp

```ts
static moveUp(n?: int): void
```

Move the cursor up by `n` rows (default 1).

### Terminal.moveDown

```ts
static moveDown(n?: int): void
```

Move the cursor down by `n` rows (default 1).

### Terminal.moveLeft

```ts
static moveLeft(n?: int): void
```

Move the cursor left by `n` columns (default 1).

### Terminal.moveRight

```ts
static moveRight(n?: int): void
```

Move the cursor right by `n` columns (default 1).

### Terminal.moveToColumn

```ts
static moveToColumn(col: int): void
```

Move the cursor to column `col` on the current row (1-indexed).

### Terminal.clearLine

```ts
static clearLine(): void
```

Clear from the cursor to the end of the current line.

### Terminal.clearDown

```ts
static clearDown(): void
```

Clear from the cursor to the end of the screen.

### Terminal.clearScreen

```ts
static clearScreen(): void
```

Clear the entire screen and move cursor to top-left.

### Terminal.bold

```ts
static bold(text: string): string
```

Wrap `text` with ANSI bold formatting.

### Terminal.dim

```ts
static dim(text: string): string
```

Wrap `text` with ANSI dim formatting.

### Terminal.italic

```ts
static italic(text: string): string
```

Wrap `text` with ANSI italic formatting.

### Terminal.underline

```ts
static underline(text: string): string
```

Wrap `text` with ANSI underline formatting.

### Terminal.strikethrough

```ts
static strikethrough(text: string): string
```

Wrap `text` with ANSI strikethrough formatting.

### Terminal.red

```ts
static red(text: string): string
```

Wrap `text` with red foreground color.

### Terminal.green

```ts
static green(text: string): string
```

Wrap `text` with green foreground color.

### Terminal.yellow

```ts
static yellow(text: string): string
```

Wrap `text` with yellow foreground color.

### Terminal.blue

```ts
static blue(text: string): string
```

Wrap `text` with blue foreground color.

### Terminal.magenta

```ts
static magenta(text: string): string
```

Wrap `text` with magenta foreground color.

### Terminal.cyan

```ts
static cyan(text: string): string
```

Wrap `text` with cyan foreground color.

### Terminal.white

```ts
static white(text: string): string
```

Wrap `text` with white foreground color.

### Terminal.gray

```ts
static gray(text: string): string
```

Wrap `text` with gray (light black) foreground color.

### Terminal.rgb

```ts
static rgb(r: int, g: int, b: int, text: string): string
```

Wrap `text` with an RGB foreground color. @param r Red channel (0-255). @param g Green channel (0-255). @param b Blue channel (0-255). @param text The text to color. @returns The text wrapped with ANSI RGB color codes.

### Terminal.bgRed

```ts
static bgRed(text: string): string
```

Wrap `text` with red background color.

### Terminal.bgGreen

```ts
static bgGreen(text: string): string
```

Wrap `text` with green background color.

### Terminal.bgYellow

```ts
static bgYellow(text: string): string
```

Wrap `text` with yellow background color.

### Terminal.bgBlue

```ts
static bgBlue(text: string): string
```

Wrap `text` with blue background color.

### Terminal.bgMagenta

```ts
static bgMagenta(text: string): string
```

Wrap `text` with magenta background color.

### Terminal.bgCyan

```ts
static bgCyan(text: string): string
```

Wrap `text` with cyan background color.

### Terminal.bgWhite

```ts
static bgWhite(text: string): string
```

Wrap `text` with white background color.

### Terminal.bgGray

```ts
static bgGray(text: string): string
```

Wrap `text` with gray (light black) background color.

### Terminal.reset

```ts
static reset(): void
```

Reset all ANSI formatting (bold, dim, color, etc.) on stdout.

### Terminal.setRawMode

```ts
static setRawMode(enable: boolean): void
```

Enable or disable raw mode on stdin, allowing direct control of keyboard input including modifier keys.

### Terminal.isTTY

```ts
static readonly isTTY: boolean
```

True if stdin is a TTY (interactive terminal); false if redirected.

### Terminal.stdoutIsTTY

```ts
static readonly stdoutIsTTY: boolean
```

True if stdout is a TTY (interactive terminal); false if redirected.

### Terminal.colorDepth

```ts
static readonly colorDepth: int
```

The terminal's color depth: 1 (monochrome), 4 (16 colors), 8 (256 colors), or 24 (true color).

---

*Generated from `lang/types/terminal.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/ticker

# Ticker

Timers and sequences that advance with the app tick.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## Cancelled <Badge type="info" text="class" />

```ts
class Cancelled extends Error
```

The error a pending `await ticker.wait(...)` rejects with when its ticker or handle is disposed.

```ts
constructor(message: string = "Cancelled")
```

## TickerHandle <Badge type="info" text="class" />

```ts
class TickerHandle
```

One entry on a ticker: what `every`/`everyTicks` return. Also the record for one-shots and `waitUntil`.

### TickerHandle.name

```ts
get name(): string
```

The name given in `opts.name`, or "" .

### TickerHandle.remaining

```ts
get remaining(): int
```

Ticks until this entry next runs (`waitUntil`: -1; stopped: 0). Held value while paused.

### TickerHandle.dispose

```ts
dispose(): void
```

Stops this entry. A pending `await` on it rejects with `Cancelled`.

### Other members of TickerHandle

```ts
owner: any
kind: int
label: string
interval: int
phase: int
due: int
heapIndex: int
seq: int
maxRuns: int
runs: int
callback: any
predicate: any
resolveFn: any
rejectFn: any
isDead: boolean
isSuspended: boolean
heldRemaining: int
immediatePending: boolean
get paused(): boolean
set paused(value: boolean)
```

## TickerInfo <Badge type="info" text="class" />

```ts
class TickerInfo
```

What `Ticker.list()` returns for each live entry.

```ts
name: string
kind: string
interval: int
nextDue: int
runs: int
paused: boolean
```

## Ticker <Badge type="info" text="class" />

```ts
class Ticker
```

### Ticker.tick

```ts
tick: int
```

Ticks this ticker has run. The first `advance()` (at `timeScale` 1) is tick 1.

### Ticker.timeScale

```ts
timeScale: float
```

Scales how many ticks of work each `advance()` runs (0.5: every second call).

### Ticker.paused

```ts
paused: boolean
```

A paused ticker's `advance()` runs nothing, and its counters hold.

### new Ticker()

```ts
constructor(tps: float = 0.0)
```

`tps` is the tick rate seconds convert with. 0 (default) reads `App.tps`.

### Ticker.size

```ts
get size(): int
```

The number of live entries (handles not yet finished or disposed).

### Ticker.every

```ts
every(seconds: float, fn: any, opts: any = undefined): TickerHandle
```

Runs `fn` every `seconds` (rounded to whole ticks, at least 1). See `everyTicks` for `opts`.

### Ticker.everyTicks

```ts
everyTicks(n: int, fn: any, opts: any = undefined): TickerHandle
```

Runs `fn` every `n` ticks. `opts`: `name` (an existing name on this ticker is replaced), `count` (stop after that
many runs), `phase` (tick offset within the period), `spread: true` (stagger same-interval entries across the
period), `immediate` (also run on the next tick).

### Ticker.wait

```ts
wait(seconds: float, fn: any = undefined): Promise<void>
```

Runs `fn` once after `seconds`; `await ticker.wait(s)` waits. Cancelled by dispose (the promise rejects `Cancelled`).

### Ticker.waitTicks

```ts
waitTicks(n: int, fn: any = undefined): Promise<void>
```

Runs `fn` once after `n` ticks (at least 1); `await ticker.waitTicks(n)` waits.

### Ticker.waitUntil

```ts
waitUntil(predicate: any, fn: any = undefined): Promise<void>
```

Runs `fn` once, on the first tick `predicate()` is true (checked every tick); `await ticker.waitUntil(p)` waits.

### Ticker.advance

```ts
advance(): void
```

Runs one tick of work, or none, one, or several of them when `timeScale` is not 1.

### Ticker.fail

```ts
fail(h: TickerHandle, e: any): void
```

A callback threw: report it once and drop its entry.

### Ticker.list

```ts
list(): Array<TickerInfo>
```

The live entries (name, kind, interval, next due tick, run count), for debugging. Allocates; not for hot paths.

### Ticker.dispose

```ts
dispose(): void
```

Cancels everything: pending `await`s reject with `Cancelled`. The ticker runs nothing afterwards.

### Other members of Ticker

```ts
tpsValue: float
accumulator: float
buckets: Array<TickerBucket>
bucketByInterval: Map<int, TickerBucket>
spreadNext: Map<int, int>
named: Map<string, TickerHandle>
heap: Array<TickerHandle>
untils: Array<TickerHandle>
immediates: Array<TickerHandle>
held: Array<TickerHandle>
dirty: boolean
sequence: int
live: int
disposed: boolean
get tps(): float
ticksFor(seconds: float): int
settleLater(handle: TickerHandle): Promise<void>
claimName(handle: TickerHandle): void
runTick(): void
run(h: TickerHandle): void
remove(h: TickerHandle, cancel: boolean): void
unhold(h: TickerHandle): void
compact(): void
addToWheel(h: TickerHandle): void
remainingOf(h: TickerHandle): int
suspend(h: TickerHandle): void
resume(h: TickerHandle): void
heapLess(a: TickerHandle, b: TickerHandle): boolean
heapPush(h: TickerHandle): void
heapPop(): TickerHandle
heapRemoveAt(index: int): void
siftUp(start: int): void
siftDown(start: int): void
swap(a: int, b: int): void
```

---

*Generated from `lang/ticker/index.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/udp

# udp

UDP datagram sockets.

::: tip Import
```ts
import { Udp } from "udp";
```

Needs the `"net"` permission in `thicket.json`.
:::

## UdpSender <Badge type="info" text="class" />

```ts
class UdpSender
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Sender address supplied to UDP receive callbacks.

### UdpSender.host

```ts
readonly host: string
```

Host address (IP) of the sender.

### UdpSender.port

```ts
readonly port: int
```

Port number of the sender.

## UdpSocket <Badge type="info" text="class" />

```ts
class UdpSocket
```

*Type only: the runtime hands you instances; you never construct it yourself.*

A bound or unbound UDP socket.

### UdpSocket.sendTo

```ts
sendTo(host: string, port: int, data: string | ByteArray): void
```

Send a datagram to a remote address.

**Parameters**

- `host`: Destination host (IP address).
- `port`: Destination port (1–65535).
- `data`: Payload as string or ByteArray.

### UdpSocket.onData

```ts
onData(fn: (data: string, sender: UdpSender) => void): void
```

Register a callback to receive datagrams as strings.

**Parameters**

- `fn`: Callback receiving `(data: string, sender: UdpSender)`.

### UdpSocket.onBinary

```ts
onBinary(fn: (data: ByteArray, sender: UdpSender) => void): void
```

Register a callback to receive datagrams as ByteArray.

**Parameters**

- `fn`: Callback receiving `(data: ByteArray, sender: UdpSender)`.

### UdpSocket.port

```ts
readonly port: int
```

Local port this socket is bound to. Read-only.

### UdpSocket.broadcast

```ts
broadcast: boolean
```

Enable or disable broadcast mode.

### UdpSocket.close

```ts
close(): void
```

Close the socket and stop listening.

## Udp <Badge type="info" text="static class" />

```ts
static class Udp
```

UDP socket factories.

### Udp.bind

```ts
static bind(port: int, host?: string): UdpSocket
```

Create and bind a UDP socket to a local address.

**Parameters**

- `port`: Local port to bind to; 0 means the OS assigns an available port.
- `host`: Local host/interface to bind to; defaults to all interfaces.

**Returns:** A bound UdpSocket.

### Udp.create

```ts
static create(): UdpSocket
```

Create an unbound UDP socket for outbound-only use or later binding.

**Returns:** An unbound UdpSocket.

---

*Generated from `lang/types/udp.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/url

# URL

Parse and build URLs and query strings.

::: tip Always available
No import needed. These names are in scope in every file.
:::

## URLSearchParams <Badge type="info" text="class" />

```ts
class URLSearchParams
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Mutable, ordered query-string parameter list. Obtained from
`URL.searchParams`; mutating it rewrites the parent URL's
`search` component on the next read. Preserves insertion order
and allows repeated keys (use `append` to add duplicates,
`set` to collapse them).

### URLSearchParams.append

```ts
append(name: string, value: string): void
```

Append a `name`/`value` pair, even if `name` already exists.

### URLSearchParams.delete

```ts
delete(name: string): void
```

Remove every entry whose name equals `name`.

### URLSearchParams.entries

```ts
entries(): Array<Array<string>>
```

Return all entries as an array of `[name, value]` pairs in
insertion order.

### URLSearchParams.get

```ts
get(name: string): string | null
```

Return the first value associated with `name`, or `null` if
`name` is not present.

### URLSearchParams.has

```ts
has(name: string): boolean
```

True when at least one entry has the given `name`.

### URLSearchParams.keys

```ts
keys(): Array<string>
```

Return every entry name in insertion order.

### URLSearchParams.set

```ts
set(name: string, value: string): void
```

Replace every existing entry for `name` with a single
entry `(name, value)`. The first occurrence is updated in
place; subsequent duplicates are dropped. Appends a fresh
entry if `name` is not present.

### URLSearchParams.toString

```ts
toString(): string
```

Render as a percent-encoded query string (without the
leading `?`). Returns the empty string when no entries are
present.

### URLSearchParams.values

```ts
values(): Array<string>
```

Return every entry value in insertion order.

## URL <Badge type="info" text="class" />

```ts
class URL
```

Parsed URL with mutable components. Constructing throws
`TypeError` if `input` cannot be parsed. Writes to individual
components rebuild the dependent fields (e.g. assigning to
`protocol` updates `href` and `origin`). The `searchParams`
accessor returns a live `URLSearchParams` bound to this URL's
query string.

### URL.hash

```ts
hash: string
```

Fragment including the leading `#`, or empty when absent.

### URL.host

```ts
host: string
```

`hostname` plus `:port` when a non-default port is present.

### URL.hostname

```ts
hostname: string
```

Host without port.

### URL.href

```ts
href: string
```

Full URL, regenerated from the component fields.

### URL.origin

```ts
origin: string
```

`protocol` + `//` + `host` for hierarchical URLs. Read-only
in spirit: assigning has no defined effect.

### URL.pathname

```ts
pathname: string
```

Path component including the leading `/`.

### URL.port

```ts
port: string
```

Port as a string. Empty when the protocol's default port applies.

### URL.protocol

```ts
protocol: string
```

Scheme including the trailing `:` (e.g. `"https:"`).

### URL.search

```ts
search: string
```

Query string including the leading `?`, or empty when absent.

### URL.searchParams

```ts
searchParams: URLSearchParams
```

Live view of the query string as a `URLSearchParams`.
Mutations propagate back into `search` and `href`.

### new URL()

```ts
constructor(input: string)
```

Parse `input` as a URL. Throws `TypeError` if parsing fails
or `input` is not a string.

### URL.toString

```ts
toString(): string
```

Equivalent to reading `href`.

### URL.decode

```ts
static decode(value: string): string
```

Percent-decode a single value (the inverse of `encode`).

### URL.encode

```ts
static encode(value: string): string
```

Percent-encode a single value for use in a URL component.

---

*Generated from `lang/types/builtin_url.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/docs/api/ws

# ws

WebSocket client and server.

::: tip Import
```ts
import { WebSocket, WebSocketServer, WebSocketClose } from "ws";
```

Needs the `"net"` permission in `thicket.json`.
:::

## WebSocket <Badge type="info" text="class" />

```ts
class WebSocket
```

A connected WebSocket, returned by `WebSocket.connect` or a server callback.

### WebSocket.connected

```ts
connected: boolean
```

True while the connection is established; false after close or error.

### WebSocket.remoteAddress

```ts
readonly remoteAddress: string
```

Remote peer address (IP or hostname).

### WebSocket.remotePort

```ts
readonly remotePort: int
```

Remote peer port.

### WebSocket.url

```ts
readonly url: string
```

The URL passed to connect or received via static method.

### WebSocket.close

```ts
close(code?: int, reason?: string): void
```

Close the connection with an optional RFC 6455 close code and reason. @param code Close code (default WebSocketClose.NORMAL). @param reason Close reason text (default empty).

### WebSocket.onBinary

```ts
onBinary(fn: any): void
```

Register a callback invoked when binary data arrives. @param fn Callback receiving the data as a Buffer.

### WebSocket.onClose

```ts
onClose(fn: any): void
```

Register a callback invoked when the connection closes. @param fn Callback with no arguments.

### WebSocket.onError

```ts
onError(fn: any): void
```

Register a callback invoked on connection errors. @param fn Callback receiving an error message string.

### WebSocket.onMessage

```ts
onMessage(fn: any): void
```

Register a callback invoked when a text message arrives. @param fn Callback receiving the message as a string.

### WebSocket.onDrain

```ts
onDrain(fn: any): void
```

Register a callback invoked when write backpressure clears and the socket is writable again. @param fn Callback with no arguments.

### WebSocket.send

```ts
send(data: string): boolean
```

Send a text message. Returns true if accepted, false if the write buffer is full.

### WebSocket.sendBinary

```ts
sendBinary(data: Buffer): boolean
```

Send a binary message. Returns true if accepted, false if the write buffer is full.

### WebSocket.connect

```ts
static connect(url: string, options?: WebSocketConnectOptions): any
```

Connect to a WebSocket server at the given URL. Returns a promise that resolves to a WebSocket or rejects on connection failure.

**Example**

```ts
import { WebSocket } from "ws";
const socket: WebSocket = await WebSocket.connect("ws://localhost:8080");
socket.onMessage((message: string): void => { console.log(message); });
socket.send("hello");
```

## WebSocketServer <Badge type="info" text="class" />

```ts
class WebSocketServer
```

A native listening socket for inbound WebSocket connections. Browser/wasm targets cannot provide this.

### WebSocketServer.port

```ts
readonly port: int
```

Local port the server is listening on.

### WebSocketServer.connections

```ts
readonly connections: Array<WebSocket>
```

Array of accepted WebSocket connections.

### WebSocketServer.connectionCount

```ts
readonly connectionCount: int
```

Current number of connected clients.

### WebSocketServer.broadcast

```ts
broadcast(data: string): boolean
```

Broadcast a text message to all connected clients. Returns true if all accepts succeeded, false if any failed.

### WebSocketServer.close

```ts
close(): void
```

Close the server, stopping acceptance of new connections but leaving existing ones open until they close.

### WebSocketServer.onConnection

```ts
onConnection(fn: any): void
```

Register a callback invoked each time a client connects. @param fn Callback receiving the connected WebSocket.

### WebSocketServer.listen

```ts
static listen(port: int, host?: string | WebSocketListenOptions, options?: WebSocketListenOptions): any
```

Start a WebSocket listener on the given `port`. Returns a promise that resolves to a WebSocketServer or rejects if the port cannot be bound.

**Example**

```ts
import { WebSocketServer, WebSocket } from "ws";
const server: WebSocketServer = await WebSocketServer.listen(8080);
server.onConnection((peer: WebSocket): void => {
    peer.onMessage((message: string): void => { peer.send(message); });
});
```

## WebSocketListenOptions <Badge type="info" text="class" />

```ts
class WebSocketListenOptions
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Validation and resource limits for a listening WebSocket server.

### WebSocketListenOptions.host

```ts
host?: string
```

Local address to bind to (default "127.0.0.1").

### WebSocketListenOptions.tls

```ts
tls?: WebSocketTlsOptions
```

TLS certificate and key for a secure wss:// listener.

### WebSocketListenOptions.maxConnections

```ts
maxConnections?: int
```

Maximum concurrent connections to accept (default unlimited).

### WebSocketListenOptions.idleTimeout

```ts
idleTimeout?: float
```

Close idle connections after this many seconds of inactivity (default no timeout).

### WebSocketListenOptions.maxPendingWriteBytes

```ts
maxPendingWriteBytes?: int
```

Maximum bytes permitted in the send buffer per connection before backpressure is applied (default no limit).

### WebSocketListenOptions.supportedProtocols

```ts
supportedProtocols?: Array<string> | ((origin: string) => boolean)
```

List of supported WebSocket subprotocols (RFC 6455), or a function to validate the `Origin` header.

### WebSocketListenOptions.verifyOrigin

```ts
verifyOrigin?: Array<string> | ((origin: string) => boolean)
```

List of allowed origins for connections, or a function to validate dynamically.

## WebSocketTlsOptions <Badge type="info" text="class" />

```ts
class WebSocketTlsOptions
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Certificate files for a direct TLS WebSocket listener.

### WebSocketTlsOptions.cert

```ts
cert: string
```

Path to the PEM-encoded certificate file.

### WebSocketTlsOptions.key

```ts
key: string
```

Path to the PEM-encoded private key file.

## WebSocketConnectOptions <Badge type="info" text="class" />

```ts
class WebSocketConnectOptions
```

*Type only: the runtime hands you instances; you never construct it yourself.*

Extra trust anchor for a verified wss:// connection.

### WebSocketConnectOptions.ca

```ts
ca?: string
```

PEM-encoded CA certificate to trust for the wss:// connection (optional).

## WebSocketClose <Badge type="info" text="static class" />

```ts
static class WebSocketClose
```

RFC 6455 close codes for WebSocket.close().

### WebSocketClose.NORMAL

```ts
static readonly NORMAL: int
```

Normal closure; the connection successfully completed its purpose.

### WebSocketClose.GOING_AWAY

```ts
static readonly GOING_AWAY: int
```

The endpoint is going away, such as by a restart or shutdown.

### WebSocketClose.PROTOCOL_ERROR

```ts
static readonly PROTOCOL_ERROR: int
```

The endpoint received a malformed frame.

### WebSocketClose.UNSUPPORTED_DATA

```ts
static readonly UNSUPPORTED_DATA: int
```

The endpoint received an unsupported data type.

### WebSocketClose.ABNORMAL_CLOSURE

```ts
static readonly ABNORMAL_CLOSURE: int
```

The connection was closed abnormally without a close frame.

### WebSocketClose.INVALID_PAYLOAD

```ts
static readonly INVALID_PAYLOAD: int
```

The endpoint received a frame with invalid payload data.

### WebSocketClose.POLICY_VIOLATION

```ts
static readonly POLICY_VIOLATION: int
```

The endpoint received a message violating its policy.

### WebSocketClose.MESSAGE_TOO_BIG

```ts
static readonly MESSAGE_TOO_BIG: int
```

The endpoint received a message that is too large to process.

### WebSocketClose.INTERNAL_ERROR

```ts
static readonly INTERNAL_ERROR: int
```

The server encountered an unexpected condition and cannot continue.

---

*Generated from `lang/types/ws.d.tks` in the ThicketScript repository.*

---

URL: https://thicketscript.com/willow/

# willow

<SiteArt src="/img/portal-willow.webp" alt="Illustration: a glowing tree of floating sprites and panels in a twilight forest, like a living scene graph" :width="1536" :height="1024" banner eager />

willow is ThicketScript's 2D module. It is a **display tree**, in the spirit of Flash and Starling: you build a tree of nodes, set each one's position, scale, rotation and colour, and willow draws the whole tree every frame. You never issue draw calls yourself.

It is built into `thicket`. List it under `systems` in `thicket.json` and import what you need from `"willow"`.

## A minimal program

```json5
{
    entry: "app.tks",
    systems: ["willow"],
    window: { title: "Hello willow", width: 800, height: 600 },
}
```

```ts
import { Quad } from "willow";

class Hello {
    static main(): void {
        const box: Quad = new Quad(120, 120, Color.hex("#4FA3E0"));
        box.setAnchor(0.5, 0.5);
        box.x = 400;
        box.y = 300;
        engine.root2d.add(box);

        App.onFrame((dt: float): void => {
            box.rotation += Math.PI * dt;
        });
    }
}
```

A blue square spins in the middle of the window, half a turn per second.

- `new Quad(w, h, color)` makes a solid rectangle node.
- `engine.root2d` is the root of the 2D tree. A node is drawn once it is in the tree.
- `App.onFrame` runs once per drawn frame. `dt` is the frame time in seconds.

## How willow fits

A GPU renderer forgets everything between frames: each frame, every draw has to be issued again. willow keeps a **retained** tree on top of it. You describe what exists (a sprite here, a label there), and each frame willow walks the tree, works out where everything is, sorts it and turns it into as few GPU draws as it can.

```text
Your game      gameplay, content, rules
willow         the node tree, transforms, draw order, batching, hit testing
thicket        the window, the GPU, input, audio, the ThicketScript runtime
```

What willow is not:

- **Not a widget toolkit.** It has no buttons, lists or layout. For those, use [willowui](/willowui/), which is built on willow nodes.
- **Not a game framework.** It does not decide how you structure entities, levels or saves. It draws your tree and routes input to it; the rest is your code.

## Where to go next

<SiteGrid :cols="3">
  <SiteCard title="Getting started" label="Start" href="/willow/getting-started.html">A window, a sprite, and moving it with the keyboard.</SiteCard>
  <SiteCard title="The scene graph" label="Concept" href="/willow/guide/scene-graph.html">How the tree, the scene, the camera and layers fit together.</SiteCard>
  <SiteCard title="Nodes and transforms" label="Concept" href="/willow/guide/nodes-and-transforms.html">Position, pivot, scale, rotation, alpha, and converting between spaces.</SiteCard>
  <SiteCard title="Sprites and textures" label="Guide" href="/willow/guide/sprites-and-textures.html">Images, regions, atlases, sprite batches and frame animation.</SiteCard>
  <SiteCard title="Text and fonts" label="Guide" href="/willow/guide/text-and-fonts.html">Labels, TTF fonts, pixel fonts, effects and text input.</SiteCard>
  <SiteCard title="Input and hit testing" label="Guide" href="/willow/guide/input-and-hit-testing.html">Clicks, drags, wheel and pinch on nodes, plus keyboard and gamepad.</SiteCard>
  <SiteCard title="Recipes" label="How-to" href="/willow/recipes.html">Short answers to common tasks.</SiteCard>
  <SiteCard title="Common pitfalls" label="Gotchas" href="/willow/guide/gotchas.html">Radians, pivots, dispose, hit testing and the other usual surprises.</SiteCard>
  <SiteCard title="Performance" label="Guide" href="/willow/guide/performance.html">Batching, sprite batches, cached subtrees, tilemaps and culling.</SiteCard>
  <SiteCard title="Reference" label="API" href="/willow/reference/">Every willow class, generated from its type declarations.</SiteCard>
</SiteGrid>

## What is in willow

| Area | What you get | Guide |
|---|---|---|
| Tree | `Node`, the scene's world and screen roots, render layers, events | [The scene graph](./guide/scene-graph.md) |
| Images | `Sprite`, `SpriteBatch`, `Texture`, `TextureRegion`, `Atlas`, `AnimationPlayer` | [Sprites and textures](./guide/sprites-and-textures.md) |
| Text | `Text`, `Font` (bundles, TTF, pixel fonts), outline, glow and shadow | [Text and fonts](./guide/text-and-fonts.md) |
| Shapes | `Quad`, `Quad.line`, `Polygon`, `Mesh`, custom paint | [Shapes and meshes](./guide/shapes-and-meshes.md) |
| Motion | `TweenGroup`, node tickers, `Transition` between screens | [Tweens and transitions](./guide/tweens-and-transitions.md) |
| Time | `onUpdate`, `onTick`, pause, time scale, interpolation | [Lifecycle and time](./guide/lifecycle-and-time.md) |
| Interaction | Pointer handlers, hit shapes, drag, wheel, pinch, pointer capture | [Input and hit testing](./guide/input-and-hit-testing.md) |
| World | `Camera2D`, `TileLayer`, `TilemapViewport`, `NodeIndex` | [Camera and layers](./guide/camera-and-layers.md), [Tilemaps](./guide/tilemaps.md) |
| Effects | Particles, filters, masks, lighting, render textures | [Effects](./guide/effects.md) |
| Advanced | `Rope`, `DistortionGrid`, physics bodies | [Rope and distortion](./guide/rope-and-distortion.md), [Physics](./guide/physics.md) |

## Without a window

A console program can list `willow` too. The node tree, transforms, hit shapes, events, `NodeIndex`, physics and text measuring work with no window or GPU, which is useful for tools, servers and tests. Loading images needs a window. See [Running without a window](./guide/headless.md).

---

URL: https://thicketscript.com/willow/getting-started

# Getting started

This page builds a small program: a window, a background, a player sprite you move with the arrow keys, and a score label. It takes about ten minutes.

## 1. Make a window project

```sh
thicket new mygame window
cd mygame
```

Edit `thicket.json5`. List the `willow` system and turn on the `fs` permission so the game can load images from disk:

```json5
{
    entry: "app.tks",
    systems: ["willow"],
    window: { title: "My Game", width: 800, height: 600, bgColor: "#0E1E3C" },
    permissions: { fs: true },
}
```

A project with a `window` section is a window app. Without one it is a console app.

## 2. Put a sprite on screen

Put an image at `assets/player.png`. Replace `app.tks` with:

```ts
import { Sprite } from "willow";

class MyGame {
    static main(): void {
        const player: Sprite = new Sprite("assets/player.png");
        player.setAnchor(0.5, 0.5);
        player.x = 400;
        player.y = 300;
        engine.root2d.add(player);
    }
}
```

Run it with `thicket run`. The image sits in the middle of the window.

- `new Sprite(path)` loads the image and makes a node that draws it.
- `setAnchor(0.5, 0.5)` moves the sprite's origin to its center, so `x` and `y` place the middle of the image.
- `engine.root2d.add(player)` puts the sprite in the 2D tree. Nodes outside the tree are not drawn.

::: tip Don't name your class `App`
`App` is the built-in lifecycle class. A class of your own called `App` hides it in that file, and `App.onFrame` stops working. Name your entry class after your game.
:::

## 3. Move it with the keyboard

`App.onFrame` runs a function once per drawn frame. `Keyboard` and `Key` are global, so there is nothing to import.

```ts
import { Sprite } from "willow";

class MyGame {
    static main(): void {
        const player: Sprite = new Sprite("assets/player.png");
        player.setAnchor(0.5, 0.5);
        player.x = 400;
        player.y = 300;
        engine.root2d.add(player);

        const SPEED: float = 240;

        App.onFrame((dt: float): void => {
            if (Keyboard.isDown(Key.RIGHT)) {
                player.x += SPEED * dt;
            }
            if (Keyboard.isDown(Key.LEFT)) {
                player.x -= SPEED * dt;
            }
            if (Keyboard.isDown(Key.DOWN)) {
                player.y += SPEED * dt;
            }
            if (Keyboard.isDown(Key.UP)) {
                player.y -= SPEED * dt;
            }
        });
    }
}
```

`dt` is the time since the last frame, in seconds. Multiplying by it moves the player the same distance per second at any frame rate.

`Keyboard.isDown` is true while a key is held. `Keyboard.isPressed` is true only on the frame it goes down, which is what you want for a jump or a menu choice.

## 4. Add a background and a label

Nodes draw in tree order: a node added later draws on top. Add the background first, then the player, then the label.

```ts
import { Sprite, Quad, Text, Font } from "willow";

class MyGame {
    static main(): void {
        const ground: Quad = new Quad(800, 120, Color.hex("#2E5E3A"));
        ground.y = 480;
        engine.root2d.add(ground);

        const player: Sprite = new Sprite("assets/player.png");
        player.setAnchor(0.5, 1.0);
        player.x = 400;
        player.y = 480;
        engine.root2d.add(player);

        const label: Text = new Text("Coins: 0", Font.system());
        label.fontSize = 24;
        label.color = Color.WHITE;
        label.x = 16;
        label.y = 16;
        engine.root2d.add(label);

        let coins: int = 0;
        const SPEED: float = 240;

        App.onFrame((dt: float): void => {
            if (Keyboard.isDown(Key.RIGHT)) {
                player.x += SPEED * dt;
            }
            if (Keyboard.isDown(Key.LEFT)) {
                player.x -= SPEED * dt;
            }
            if (Keyboard.isPressed(Key.SPACE)) {
                coins += 1;
                label.text = "Coins: " + coins;
            }
        });
    }
}
```

- `Quad` is a solid rectangle. `Color.hex("#2E5E3A")` makes a colour from a hex string.
- `setAnchor(0.5, 1.0)` puts the origin at the bottom middle of the sprite, so `y` is where its feet stand.
- `Font.system()` is willow's bundled default font. Assigning `label.text` re-lays out the text on the next frame.

## 5. Game logic on fixed ticks

`App.onFrame` runs once per drawn frame, so it runs more often on a faster screen. For logic that should run at a steady rate, use `App.onTick`. Ticks run 60 times a second by default (`App.tps`).

```ts
import { Sprite } from "willow";

class MyGame {
    static main(): void {
        const player: Sprite = new Sprite("assets/player.png");
        player.setAnchor(0.5, 0.5);
        player.x = 400;
        player.y = 300;
        player.interpolate = true;
        engine.root2d.add(player);

        const STEP: float = 4;

        App.onTick((): void => {
            if (Keyboard.isDown(Key.RIGHT)) {
                player.x += STEP;
            }
            if (Keyboard.isDown(Key.LEFT)) {
                player.x -= STEP;
            }
        });
    }
}
```

`interpolate = true` makes willow draw the sprite between its last two tick positions, so it moves smoothly even when the screen refreshes faster than the tick rate. See [Lifecycle and time](./guide/lifecycle-and-time.md).

## Next

- [The scene graph](./guide/scene-graph.md) explains the tree, the world and screen roots, and layers.
- [Sprites and textures](./guide/sprites-and-textures.md) covers sharing textures, atlases and animation.
- [Input and hit testing](./guide/input-and-hit-testing.md) makes nodes clickable and draggable.
- [Recipes](./recipes.md) has short answers to common tasks.

---

URL: https://thicketscript.com/willow/guide/camera-and-layers

# Camera and layers

The scene has one 2D camera, `engine.camera` (also `Scene.main.camera`). It decides which part of the world root you see. Nodes under the screen root (`engine.screen2d`) ignore it.

At the start, world (0, 0) is the top-left of the window. The camera's `x` and `y` are the world point at the **center** of the view.

## Moving the camera

| Member | Does |
|---|---|
| `x`, `y`, `position` | The world point the view is centered on. |
| `zoom` | 1 is normal, above 1 zooms in, below 1 zooms out. |
| `rotation` | Rotation in radians. |
| `bounds` | A world `Rect` the view stays inside, or `null`. |
| `follow(node, { offset, lerp })` | Track a node every frame. Leave out `lerp` to snap; a small `lerp` such as 0.1 follows smoothly. |
| `unfollow()` | Stop following and stay put. |
| `scrollTo(point, seconds, ease?)` | Glide to a point. Returns a promise. |
| `scrollToTile(col, row, seconds, ease?, tileSize?)` | Glide to the center of a tile (32x32 by default). |
| `shake(trauma, decay?)` | Shake. `trauma` 0 to 1 adds up across hits; the shake grows with its square and fades by `decay` per second. |
| `screenToWorld(p)`, `worldToScreen(p)` | Convert points. |
| `visibleBounds()` | The world `Rect` currently on screen. |

```ts
import { Sprite, Quad, Text, Camera2D } from "willow";

class Follow {
    static main(): void {
        const level: Quad = new Quad(3200, 600, Color.hex("#24395C"));
        engine.root2d.add(level);

        const hero: Sprite = new Sprite("assets/hero.png");
        hero.setAnchor(0.5, 1.0);
        hero.setPosition(100, 500);
        engine.root2d.add(hero);

        const cam: Camera2D = engine.camera;
        cam.follow(hero, { offset: Vec2{ x: 0.0, y: -80.0 }, lerp: 0.1 });
        cam.bounds = Rect{ x: 0.0, y: 0.0, width: 3200.0, height: 600.0 };

        const hud: Text = new Text("Distance: 0");
        hud.setPosition(16, 16);
        engine.screen2d.add(hud);

        App.onFrame((dt: float): void => {
            if (Keyboard.isDown(Key.RIGHT)) {
                hero.x += 300 * dt;
            }
            if (Keyboard.isPressed(Key.X)) {
                cam.shake(0.4);
            }
            hud.text = "Distance: " + Math.round(hero.x);
        });
    }
}
```

The HUD text is under `engine.screen2d`, so it stays in the corner while the world scrolls.

`scrollTo` and `follow` interrupt each other: starting one rejects the promise of a scroll that was still running.

## Culling

`cam.cullEnabled = true` skips drawing any node whose world bounds are outside the view. It helps when a large world has many nodes off screen. Large tile grids have their own culling; see [Tilemaps](./tilemaps.md).

## Placing screen nodes over world points

A health bar over a unit should stay the same size when the camera zooms, so it belongs on the screen root. Each frame, put it where the unit is on screen:

```ts
import { Sprite, Quad } from "willow";

class Overhead {
    static main(): void {
        const unit: Sprite = new Sprite("assets/unit.png");
        unit.setPosition(600, 400);
        engine.root2d.add(unit);

        const bar: Quad = new Quad(40, 6, Color.hex("#4CD964"));
        engine.screen2d.add(bar);

        unit.onLateUpdate = (dt: float): void => {
            const p: Vec2 = unit.toScreen(0, -10);
            bar.setPosition(p.x, p.y);
        };
    }
}
```

`onLateUpdate` runs after the camera has moved for this frame.

## Layers

Render layers decide draw order across the whole tree; see [The scene graph](./scene-graph.md#draw-order). A common setup:

| Layer | Value | Holds |
|---|---|---|
| `LAYER_BACKGROUND` | 0 | Sky, parallax backdrops |
| `LAYER_DEFAULT` | 64 | The world |
| `LAYER_UI` | 192 | HUD and menus |
| `LAYER_OVERLAY` | 255 | Fades, debug overlays |

Read them from `engine.scene`.

## Finding nodes: NodeIndex

A `NodeIndex` finds nodes by name or tag, so you don't have to keep your own lists. The scene has one, `engine.scene.index`, and you can make your own with `new NodeIndex()`.

```ts
import { Node, NodeIndex } from "willow";

class Lookup {
    static main(): void {
        const index: NodeIndex = new NodeIndex();
        const bat: Node = new Node("bat-1");
        const slime: Node = new Node("slime-1");
        index.add(bat, "enemy", "flying");
        index.add(slime, "enemy");

        console.log("enemies: " + index.countByTag("enemy"));
        console.log("flying enemies: " + index.findByTags("enemy", "flying").length);
        console.log("bats: " + index.findAllByName("bat-%").length);

        slime.dispose();
        console.log("enemies after one is disposed: " + index.countByTag("enemy"));
    }
}
```

Output:

```text
enemies: 2
flying enemies: 1
bats: 1
enemies after one is disposed: 1
```

`%` in a pattern matches anything, as in SQL `LIKE`. A disposed node leaves the index on its own.

## Next

- [Tilemaps](./tilemaps.md)
- Reference: [Camera2D](../reference/camera.md), [NodeIndex](../reference/node-index.md), [Scene](../reference/scene.md)

---

URL: https://thicketscript.com/willow/guide/effects

# Effects

## Particles

A **`ParticleEmitter`** is a node that spawns and simulates a pool of particles. Set it up with an `EmitterConfig`.

```ts
import { ParticleEmitter, EmitterConfig, Range } from "willow";

class Sparks {
    static main(): void {
        const cfg: EmitterConfig = new EmitterConfig();
        cfg.maxParticles = 300;
        cfg.emitRate = 120;
        cfg.lifetime = new Range(0.4, 0.9);
        cfg.speed = new Range(80, 220);
        cfg.angle = new Range(-Math.PI * 0.75, -Math.PI * 0.25);
        cfg.gravityY = 400;
        cfg.startColor = Color.hex("#FFE08A");
        cfg.endColor = Color.hex("#FF4020");
        cfg.endAlpha = 0;
        cfg.endScale = 0.2;

        const sparks: ParticleEmitter = new ParticleEmitter("sparks", cfg);
        sparks.setPosition(400, 450);
        engine.root2d.add(sparks);
        sparks.start();

        App.onFrame((dt: float): void => {
            if (Keyboard.isPressed(Key.SPACE)) {
                sparks.burst(60);
            }
        });
    }
}
```

| Config field | Meaning | Default |
|---|---|---|
| `maxParticles` | Pool size. | 128 |
| `emitRate` | Particles per second while started. | 10 |
| `lifetime`, `speed`, `angle` | `Range`s for each new particle; angles in radians. | 1 s, 50 px/s, full circle |
| `gravityX`, `gravityY` | Constant acceleration. | 0 |
| `startScale` / `endScale` | Scale over a particle's life. | 1 / 1 |
| `startAlpha` / `endAlpha` | Alpha over a particle's life. | 1 / 0 |
| `startColor` / `endColor` | Tint over a particle's life. | white |
| `blendMode` | How particles blend. | `"add"` |
| `worldSpace` | Particles stay where they were born when the emitter moves (a trail). | `false` |

`start()` and `stop()` control continuous emission; `burst(n)` spawns at once; `reset()` clears everything. `seed` (or `setSeed`) makes the randomness repeatable.

## Blend modes

`node.blendMode` is one of `"normal"`, `"add"`, `"multiply"`, `"screen"`, `"erase"`, `"mask"`, `"below"` or `"none"`. `"add"` brightens and suits fire, magic and lasers.

## Filters

Filters change how a node and its children look once drawn. A node can have several; they apply in order.

```ts
import { Sprite, OutlineFilter, ColorMatrixFilter, BlurFilter } from "willow";

class Filtered {
    static main(): void {
        const selected: Sprite = new Sprite("assets/unit.png");
        selected.setPosition(200, 200);
        selected.addFilter(new OutlineFilter(2, Color.hex("#FFD24A")));
        engine.root2d.add(selected);

        const stone: Sprite = new Sprite("assets/unit.png");
        stone.setPosition(400, 200);
        stone.addFilter(new ColorMatrixFilter().setGrayscale());
        engine.root2d.add(stone);

        const far: Sprite = new Sprite("assets/hills.png");
        far.setPosition(0, 380);
        far.addFilter(new BlurFilter(4));
        engine.root2d.add(far);
    }
}
```

| Filter | Effect |
|---|---|
| `BlurFilter(radius)` | Blur. |
| `OutlineFilter(thickness, color)` | An outline several pixels thick. |
| `PixelPerfectOutlineFilter(color)` | A crisp one-pixel outline for pixel art. |
| `PixelPerfectInlineFilter(color)` | Recolours the one-pixel edge inside the shape. |
| `ColorMatrixFilter()` | Brightness, contrast, saturation, hue, grayscale, invert. The setters chain. |
| `PaletteFilter()` | Remaps colours by brightness to a 256-colour palette; animate `cycleOffset` for palette cycling. |
| `CustomShaderFilter(path)` / `CustomDrawShaderFilter(path)` | Your own prebuilt fragment shader. |

Manage the list with `addFilter`, `removeFilter`, `clearFilters`, `setFilters` or the `filters` array.

**Cost.** Filters marked as draw filters (`ColorMatrixFilter`, the pixel-perfect pair, `PaletteFilter`, `CustomDrawShaderFilter`) can apply while the sprite draws, without an offscreen pass, when the node is a single sprite with no mask or cache. The others (`BlurFilter`, `OutlineFilter`, `CustomShaderFilter`) draw the subtree to an offscreen texture first.

**Custom shaders** are bgfx fragment binaries built ahead of time with `shaderc`; there is no shader compiler at run time. willow loads `<path>.<backend>.bin` for the running renderer. The source image is sampler 0, and `setUniform(name, value)` sets named uniforms.

## Masks

`node.setMask(maskNode)` clips the node's subtree to the mask's shape. `clearMask()` removes it. The mask's own transform is ignored, and masks do not affect hit testing.

```ts
import { Sprite, Polygon } from "willow";

class Porthole {
    static main(): void {
        const view: Sprite = new Sprite("assets/ocean.png");
        view.setPosition(200, 100);
        engine.root2d.add(view);

        const circle: Polygon = Polygon.circle(120, Color.WHITE);
        view.setMask(circle);
    }
}
```

## Lighting

A **`LightLayer`** darkens everything drawn before it in the tree and cuts lights out of the darkness. Add your UI after it so the UI stays lit.

```ts
import { Sprite, LightLayer, Light, Text } from "willow";

class Cave {
    static main(): void {
        engine.root2d.add(new Sprite("assets/cave.png"));

        const hero: Sprite = new Sprite("assets/hero.png");
        hero.setPosition(300, 300);
        engine.root2d.add(hero);

        const dark: LightLayer = new LightLayer(0.85);
        engine.root2d.add(dark);

        const torch: Light = new Light(0, 0, 160, Color.hex("#FFD9A0"), 1.0);
        torch.attachTo(hero, 16, 16);
        dark.addLight(torch);

        const lamp: Light = new Light(600, 200, 90, Color.hex("#A0C8FF"), 0.8);
        dark.addLight(lamp);

        engine.root2d.add(new Text("Lit UI"));
    }
}
```

`ambientDarkness` (0 unlit to 1 black) and `ambient` (the colour of the dark) shape the mood. `addLight` returns an id for `removeLight` and `hasLight`. A light attached to a node follows it.

## Render textures

A **`RenderTexture`** is a canvas you draw images onto, then show as a sprite. Draws accumulate, which suits paint tools, decals and minimaps.

```ts
import { RenderTexture, Sprite, Texture } from "willow";

class Decals {
    static main(): void {
        const canvas: RenderTexture = new RenderTexture(800, 600);
        engine.root2d.add(canvas.createSpriteNode("decals"));

        const splat: Texture = Texture.load("assets/splat.png");
        App.onFrame((dt: float): void => {
            if (Mouse.isPressed(Mouse.LEFT)) {
                canvas.drawImage(splat, Mouse.x - 16, Mouse.y - 16);
            }
        });
    }
}
```

`drawImageTransformed` and `drawSpriteTransformed` take a `RenderTextureDrawOpts` with position, scale, rotation, pivot, colour, alpha and blend. `fill(color)` and `clear()` reset the canvas. Every sprite made with `createSpriteNode` shows the live canvas.

`ToTexture(node)` renders a subtree once into a new `RenderTexture`, for a snapshot or a thumbnail. Call it between frames (from `onUpdate`), and dispose the result when done.

## Next

- [Rope and distortion](./rope-and-distortion.md)
- Reference: [ParticleEmitter](../reference/particles.md), [Filters](../reference/filters.md), [LightLayer](../reference/lighting.md), [RenderTexture](../reference/render-texture.md)

---

URL: https://thicketscript.com/willow/guide/gotchas

# Common pitfalls

These are the things that trip people up most often in willow. Each one is short, says what happens, and says what to do instead.

## Rotation is in radians

`rotation`, `skewX`, `skewY` and `setRotation()` take radians, not degrees. `node.rotation = 90` turns the node about 14 full times, which looks like nothing much happened.

```ts
node.rotation = Math.PI / 2;          // a quarter turn, clockwise on screen
node.rotation = 45 * Math.PI / 180;   // from degrees
```

## The pivot is in pixels, the anchor is a fraction

`pivotX`, `pivotY` and `setPivot(x, y)` are in the node's **local pixels**. `setAnchor(nx, ny)` takes a **fraction** of the node's size and sets the pivot for you. Mixing them up is the usual reason a sprite spins around its corner.

```ts
import { Quad } from "willow";

class Pivots {
    static main(): void {
        const q: Quad = new Quad(100, 50, Color.WHITE);
        q.setAnchor(0.5, 0.5);
        console.log("anchor 0.5 -> pivot " + q.pivotX + ", " + q.pivotY);
        q.setPivot(0.5, 0.5);
        console.log("setPivot 0.5 -> pivot " + q.pivotX + ", " + q.pivotY);
    }
}
```

Output:

```text
anchor 0.5 -> pivot 50, 25
setPivot 0.5 -> pivot 0.5, 0.5
```

To centre a node, use `setAnchor(0.5, 0.5)` or `alignPivot()`. See [Nodes and transforms](./nodes-and-transforms.md#pivots-and-anchors).

## Alpha and tint multiply

A node's `alpha` multiplies with its parent's alpha, all the way up the tree. A sprite's `tint` is a separate multiplier on top, and its alpha counts too. So a sprite at `alpha = 1` can still be invisible if its parent is at 0, or if its tint has an alpha of 0. Use `alpha` to fade, and `tint` to colour.

A raw number used as a colour is always `0xRRGGBBAA`. A six-digit number such as `0xFF0000` has an alpha of 0. Write all eight digits, or use `Color.hex("#FF0000")`, which treats a six-digit string as opaque. See [Shapes and meshes](./shapes-and-meshes.md#polygons).

## `add()` moves a node

A node has one parent. Adding it somewhere else takes it out of the old parent first; it is not copied.

```ts
import { Node } from "willow";

class Moves {
    static main(): void {
        const a: Node = new Node("a");
        const b: Node = new Node("b");
        const coin: Node = new Node("coin");
        a.add(coin);
        b.add(coin);
        console.log("a has coin: " + a.contains(coin) + ", b has coin: " + b.contains(coin));
    }
}
```

Output:

```text
a has coin: false, b has coin: true
```

To show the same thing twice, make two nodes.

## `remove()` is reversible, `dispose()` is not

`remove()` detaches a node and keeps it, so you can add it back. `dispose()` frees it for good, **and every node below it**. Any later use of a disposed node, even reading `x`, raises `InvalidStateError`.

```ts
import { Node } from "willow";

class Gone {
    static main(): void {
        const enemy: Node = new Node("enemy");
        const healthBar: Node = new Node("healthBar");
        enemy.add(healthBar);
        enemy.dispose();
        try {
            console.log(healthBar.x);
        } catch (e) {
            console.log("" + e);
        }
    }
}
```

Output:

```text
InvalidStateError: Node.x: node has been disposed
```

Drop your own references to a node when you dispose it, and dispose the parent rather than each child. Disposing twice is safe.

## A node with no handler is not hit

A node takes pointer events only while it has a pointer handler assigned (`onClick`, `onPointerDown`, `onDrag` and the rest). A node without one is not hit tested at all, so the click goes to whatever is under it. `interactable` defaults to `true`; setting it to `false` takes a node out of hit testing while keeping its handlers, which is how you disable a button.

So if clicks on a panel's background reach the world behind it, give the panel a handler, even an empty one. See [Input and hit testing](./input-and-hit-testing.md).

## Masks clip drawing, not input

`setMask()` changes what is drawn. It does not change hit testing, so the hidden part of a masked node can still be clicked. If that matters, give the node a hit shape that matches the visible area with `setHitRect` or `setHitCircle`. See [Effects](./effects.md#masks).

## Hooks are single slots

`onUpdate`, `onTick`, `onClick` and the other handlers are fields. Assigning a second function replaces the first; it does not add to it. To run two things, call both from one function, or use named events with `on(name, handler)`, which keep a list. Assign `null` to detach a handler.

A lifecycle hook (`onUpdate`, `onTick` and the rest) that throws is reported once and then turned off, so a node that suddenly stops moving may have thrown on an earlier frame. Check the log.

## Names are labels, not keys

A node's `name` is for debugging and lookup. Nothing stops two nodes having the same name, and a `NodeIndex` keeps them all: `findByName` returns the first one registered, while `findAllByName` and `each` see every one. To find a group, tag the nodes and use `findByTag`. See [Camera and layers](./camera-and-layers.md#finding-nodes-nodeindex).

## The camera's position is the centre of the view

You do not need to set up a camera: with an untouched camera, world (0, 0) is the top-left of the window. When you do move it, `camera.x` and `camera.y` are the world point at the **centre** of the screen, not the top-left corner. `follow(node)` with no `lerp` snaps to the node; a small `lerp` such as 0.1 eases toward it. See [Camera and layers](./camera-and-layers.md).

## HUDs belong on the screen root

Anything under `engine.root2d` is drawn through the camera, so it scrolls and zooms with the world. Put menus, scores and health bars under `engine.screen2d` instead. See [The scene graph](./scene-graph.md#the-scene).

## Next

- [The scene graph](./scene-graph.md)
- [Recipes](../recipes.md)

---

URL: https://thicketscript.com/willow/guide/headless

# Running without a window

A console program (a `thicket.json` with no `window` section) can list `willow` too:

```json5
{
    entry: "app.tks",
    systems: ["willow"],
}
```

There is no scene, so `Scene.main` is `null` and nothing is drawn. The display tree itself still works. This is handy for unit tests of game logic, level tools and servers that share code with the game.

## What works

Every sample on these pages marked as run without a window was run that way to produce its output:

- Building trees: `new Node`, `add`, `remove`, `children`, `dispose`, names and `userData`.
- Transforms and conversions: `worldPosition`, `localToWorld`, `worldToLocal`, `distanceTo`, `setSize`.
- `Quad` nodes, hit shapes (`setHitCircle`, `hitShapeContains`) and `emit`/`on` events.
- `NodeIndex` lookups, including nodes leaving the index when disposed.
- Physics roots and bodies, stepped with `stepPhysics`.
- `Text` with `Font.system()`, and `text.measure()` and `font.measure()`.
- `TweenGroup` stepped by hand with `update(dt)`.

## What needs a window

Anything that makes or reads GPU pixels raises an error that names the problem, for example `AssetError: Texture.fromPixels: texture: renderer not initialised`. That includes:

- Loading or creating textures (`Texture.load`, `Texture.fromPixels`), and so sprites from images.
- Packing images into an atlas with `Atlas.add`.
- Render textures and `ToTexture`.
- Cached subtrees (`setCacheAsTree` has no effect).

To test code that uses these, keep the logic in plain classes and nodes, and give the window app the parts that load images.

```ts
import { Node, Quad } from "willow";

class LogicTest {
    static main(): void {
        const scene: Scene | null = Scene.main;
        console.log("scene present: " + (scene !== null));

        const board: Node = new Node("board");
        for (let i: int = 0; i < 3; i++) {
            const cell: Quad = new Quad(32, 32, Color.WHITE);
            cell.setPosition(i * 40, 0);
            board.add(cell);
        }
        board.x = 100;
        const last: Vec2 = board.children()[2].worldPosition();
        console.log("cells: " + board.children().length + ", last at x = " + last.x);
    }
}
```

Output:

```text
scene present: false
cells: 3, last at x = 180
```

---

URL: https://thicketscript.com/willow/guide/input-and-hit-testing

# Input and hit testing

There are two ways to read input:

- **Global state** for game controls: `Keyboard`, `Mouse`, `Gamepad`, `TouchInput` and `InputMap`. They are built in, with nothing to import.
- **Node handlers** for things you point at: buttons, cards, units. willow finds the node under the pointer and calls its handler.

## Global input

```ts
import { Sprite } from "willow";

class Controls {
    static main(): void {
        const ship: Sprite = new Sprite("assets/ship.png");
        ship.setAnchor(0.5, 0.5);
        ship.setPosition(400, 300);
        engine.root2d.add(ship);

        App.onFrame((dt: float): void => {
            let dx: float = Gamepad.axis(0, GamepadAxis.LEFT_X);
            if (Keyboard.isDown(Key.LEFT)) {
                dx = -1;
            }
            if (Keyboard.isDown(Key.RIGHT)) {
                dx = 1;
            }
            ship.x += dx * 300 * dt;

            if (Keyboard.isPressed(Key.SPACE) || Gamepad.isPressed(0, GamepadButton.A)) {
                console.log("fire");
            }
            if (Mouse.isPressed(Mouse.LEFT)) {
                console.log("clicked at " + Mouse.x + ", " + Mouse.y);
            }
        });
    }
}
```

`isDown` is true while held; `isPressed` and `isReleased` are true on the frame (or tick) the state changes. `Mouse.x` and `Mouse.y` are in screen pixels; convert them to the world with `engine.camera.screenToWorld`.

## Node handlers

Assign a handler and the node takes part in hit testing. A node with no pointer handler is never hit.

| Handler | Payload | Runs when |
|---|---|---|
| `onPointerDown` | `PointerEvent` | A button goes down over the node. |
| `onPointerUp` | `PointerEvent` | A button goes up over the node. |
| `onClick` | `PointerEvent` | Down and up both land on the node. |
| `onPointerMove` | `PointerEvent` | The pointer moves over the node. |
| `onPointerEnter` / `onPointerLeave` | `PointerEvent` | The pointer enters or leaves the node. These do not bubble. |
| `onDragStart`, `onDrag`, `onDragEnd` | `DragEvent` | A press moves past the drag dead zone, keeps moving, then lets go. |
| `onWheel` | `WheelEvent` | The wheel or trackpad scrolls over the node. |
| `onPinch` | `PinchContext` | A two-finger pinch or rotate. |

```ts
import { Quad, Text, PointerEvent, KeyModifiers } from "willow";

class ButtonDemo {
    static main(): void {
        const button: Quad = new Quad(160, 48, Color.hex("#3366CC"));
        button.setPosition(320, 276);
        engine.root2d.add(button);

        const label: Text = new Text("Start");
        label.setPosition(56, 12);
        button.add(label);

        button.onPointerEnter = (e: PointerEvent): void => {
            button.color = Color.hex("#4A7FE6");
        };
        button.onPointerLeave = (e: PointerEvent): void => {
            button.color = Color.hex("#3366CC");
        };
        button.onClick = (e: PointerEvent): void => {
            const shift: boolean = (e.modifiers & KeyModifiers.SHIFT) !== 0;
            console.log("start, shift held: " + shift + ", at " + e.x + ", " + e.y);
        };
    }
}
```

A `PointerEvent` carries the point in the node's local space (`x`, `y`), in the world (`worldX`, `worldY`) and on screen (`screenX`, `screenY`), plus `button` (0 left, 1 right, 2 middle), `modifiers` and `target`.

`interactable = false` takes a node out of hit testing while keeping its handlers, which is how you disable a button.

## Dragging

```ts
import { Sprite, DragEvent, Pointer } from "willow";

class DragCard {
    static main(): void {
        const card: Sprite = new Sprite("assets/card.png");
        card.setPosition(200, 200);
        engine.root2d.add(card);

        let startX: float = 0;
        let startY: float = 0;
        card.onDragStart = (e: DragEvent): void => {
            startX = card.x;
            startY = card.y;
            card.alpha = 0.8;
        };
        card.onDrag = (e: DragEvent): void => {
            card.x = startX + e.deltaX;
            card.y = startY + e.deltaY;
        };
        card.onDragEnd = (e: DragEvent): void => {
            card.alpha = 1;
        };

        Pointer.setDragDeadZone(6);
    }
}
```

`deltaX` and `deltaY` are the world distance since the drag began. The drag dead zone (`Pointer.setDragDeadZone(px)`) is how far a press must move before it counts as a drag rather than a click.

`Pointer.capture(node)` sends every pointer event to one node, wherever the pointer goes, until `Pointer.release()`. Use it for sliders and scroll bars.

## Hit shapes

By default the hit area is the node's bounding box. Give a node a tighter shape in its local space:

| Call | Hit area |
|---|---|
| `setHitRect(x, y, w, h)` | A rectangle. |
| `setHitCircle(cx, cy, r)` | A circle. |
| `setHitPolygon([x0, y0, ...])` | A convex polygon, at least three points. |
| `clearHitShape()` | Back to the bounding box. |

```ts
import { Quad } from "willow";

class HitShapes {
    static main(): void {
        const coin: Quad = new Quad(64, 64, Color.WHITE);
        coin.setHitCircle(32, 32, 30);
        console.log("center: " + coin.hitShapeContains(32, 32));
        console.log("corner: " + coin.hitShapeContains(2, 2));
        coin.clearHitShape();
        console.log("custom shape after clear: " + coin.hasHitShape());
    }
}
```

Output:

```text
center: true
corner: false
custom shape after clear: false
```

Masks do not change hit testing. A node clipped by a mask is still hit over its full shape.

## Clicks on empty space and keys as events

`engine.scene.onBackgroundClick(fn)` runs when a click misses every node, which is handy for deselecting. `engine.scene.onKeyDown(fn)` and `onKeyUp(fn)` deliver each key change as a `KeyEvent` with `keyCode` (a `Key` constant), `label`, `charCode`, `repeat` and the modifier flags, in the order they arrived.

## Next

- [Camera and layers](./camera-and-layers.md)
- Reference: [Pointer input](../reference/input.md), [Node](../reference/node.md)

---

URL: https://thicketscript.com/willow/guide/lifecycle-and-time

# Lifecycle and time

willow runs two clocks. **Frames** happen once per screen refresh. **Ticks** happen at a fixed rate, 60 per second by default (`App.tps`, or `tps` in `thicket.json`). Put game logic on ticks so it runs the same on every machine, and put purely visual work on frames.

## App-wide hooks

| Hook | Runs |
|---|---|
| `App.onTick(fn)` | Once per tick. After a slow frame, several ticks run to catch up (at most `App.maxCatchUpTicks`, default 8). |
| `App.onFrame(fn)` | Once per drawn frame, with `dt` in seconds. |
| `App.onResize(fn)` | When the window changes size. |
| `App.onFocus(fn)` / `App.onBlur(fn)` | When the window gains or loses focus. |
| `App.onQuit(fn)` | When the app is closing. |

Each returns a function that unsubscribes it. Useful readings: `App.tick` (ticks so far), `App.time` (scaled seconds), `App.realTime` (wall seconds), `App.actualFps`, `App.actualTps`.

## Node hooks

Any node can carry its own hooks. Assign a function; assign `null` to remove it.

| Hook | Runs |
|---|---|
| `onEnter()` | When the node is added to a parent. |
| `onExit()` | When it is removed from its parent. |
| `onReady()` | Once, on the first frame the node is in the tree. |
| `onTick()` | Once per tick, parents before children. |
| `onUpdate(dt)` | Every frame, after `onReady`. |
| `onLateUpdate(dt)` | Every frame, after every node's `onUpdate` and the tweens. Good for cameras and things that follow other things. |

```ts
import { Sprite } from "willow";

class Enemy {
    static spawn(x: float, y: float): Sprite {
        const e: Sprite = new Sprite("assets/slime.png");
        e.setAnchor(0.5, 1.0);
        e.setPosition(x, y);
        e.interpolate = true;

        let dir: float = 1;
        e.onReady = (): void => {
            console.log("slime ready at " + e.x);
        };
        e.onTick = (): void => {
            e.x += 2 * dir;
            if (e.x > x + 100 || e.x < x - 100) {
                dir = -dir;
                e.scaleX = dir;
            }
        };
        return e;
    }

    static main(): void {
        engine.root2d.add(Enemy.spawn(200, 400));
        engine.root2d.add(Enemy.spawn(500, 400));
    }
}
```

A hook that throws is reported once and then turned off, so one bad enemy does not flood the log.

## Interpolation

Move a node in `onTick` and it moves in steps of 1/60 second. On a 144 Hz screen that looks jerky. Set `interpolate = true` and willow draws `x`, `y`, `rotation`, `scaleX` and `scaleY` blended between the last two ticks. Your code still reads the real values.

After teleporting an interpolated node, call `resetInterpolation()`, or it visibly slides from the old spot for one tick.

## Pausing

`paused = true` on a node stops its subtree's `onTick`, `onUpdate`, `onLateUpdate`, ticker and tweens. Drawing continues, so the game freezes in place. `pauseMode` lets parts of a paused tree keep going:

| `PauseMode` | Behaviour |
|---|---|
| `INHERIT` | Follows its parent (default). |
| `ALWAYS` | Keeps running while an ancestor is paused: a pause menu inside the game tree. |
| `WHEN_PAUSED` | Runs only while an ancestor is paused. |
| `DISABLED` | Never runs. |

```ts
import { Node, Text, PauseMode } from "willow";

class PauseDemo {
    static main(): void {
        const game: Node = new Node("game");
        engine.root2d.add(game);

        const menu: Text = new Text("Paused");
        menu.visible = false;
        menu.pauseMode = PauseMode.WHEN_PAUSED;
        menu.onUpdate = (dt: float): void => {
            menu.alpha = 0.6 + 0.4 * Math.sin(App.realTime * 4);
        };
        game.add(menu);

        App.onFrame((dt: float): void => {
            if (Keyboard.isPressed(Key.ESCAPE)) {
                game.paused = !game.paused;
                menu.visible = game.paused;
            }
        });
    }
}
```

## Time scale

`node.timeScale` speeds up or slows down a subtree: 0.5 is half speed (slow motion), 2 is double. It scales `dt` for `onUpdate` and `onLateUpdate`, the number of `onTick` calls, and the node's ticker. `App.timeScale` does the same for the whole app. A node with `unscaled = true` ignores both, which suits UI that should not slow down with the game.

## Next

- [Input and hit testing](./input-and-hit-testing.md)
- Reference: [Node](../reference/node.md)

---

URL: https://thicketscript.com/willow/guide/nodes-and-transforms

# Nodes and transforms

Every node has a **local transform**: where it sits, how it is scaled and rotated, relative to its parent. willow multiplies the transforms down the tree to get each node's **world transform**. Only nodes whose transform (or an ancestor's) changed are recomputed, so a still subtree costs nothing per frame.

## Transform fields

| Field | Meaning | Default |
|---|---|---|
| `x`, `y` | Position in the parent's space, in pixels. | 0 |
| `scaleX`, `scaleY` | Scale factor. 1 is the authored size; negative flips. | 1 |
| `rotation` | Rotation in **radians**, clockwise on screen. | 0 |
| `skewX`, `skewY` | Skew in radians. | 0 |
| `pivotX`, `pivotY` | The point, in the node's own pixels, that `x`/`y` place and that rotation and scale turn around. | 0 (top-left) |
| `alpha` | Opacity 0 to 1. Multiplies with the parent's alpha. | 1 |
| `visible` | `false` hides the node and its whole subtree. | `true` |

Shortcuts set two fields at once: `setPosition(x, y)`, `setScale(s)` or `setScale(sx, sy)`, `setSkew(sx, sy)`, `setRotation(r)`, `setPivot(px, py)`.

## Pivots and anchors

By default a node's origin is its top-left corner, so it rotates around that corner. Move the pivot to make it spin in place:

| Call | Pivot |
|---|---|
| `setAnchor(0.5, 0.5)` | The center, as a fraction of the node's size. |
| `setAnchor(0.5, 1.0)` | Bottom middle: the feet of a character. |
| `setPivot(16, 32)` | An exact pixel inside the node. |
| `alignPivot()` | The center of the current content. |
| `alignPivot(Align.CENTER, Align.BOTTOM)` | Bottom middle of the current content. |

`alignPivot` reads the size once. If the content later changes size, call it again.

`setSize(w, h)` resizes a node by changing its scale: a 64x64 sprite given `setSize(128, 32)` gets `scaleX = 2` and `scaleY = 0.5`.

## Containers carry their children

```ts
import { Node, Quad } from "willow";

class Carry {
    static main(): void {
        const ship: Node = new Node("ship");
        ship.setPosition(100, 50);
        ship.setScale(2);

        const turret: Quad = new Quad(20, 20, Color.WHITE);
        turret.setPosition(10, 5);
        ship.add(turret);

        const p: Vec2 = turret.worldPosition();
        console.log("turret in the world: " + p.x + ", " + p.y);

        ship.x = 300;
        const q: Vec2 = turret.worldPosition();
        console.log("after moving the ship: " + q.x + ", " + q.y);
    }
}
```

Output:

```text
turret in the world: 120, 60
after moving the ship: 320, 60
```

The turret's own `x` and `y` never changed. Moving, scaling or rotating `ship` moves everything inside it.

## Converting between spaces

| Method | From | To |
|---|---|---|
| `node.localToWorld(p)` | The node's local space | World space |
| `node.worldToLocal(p)` | World space | The node's local space |
| `node.toScreen(x, y)` | The node's local space | Screen pixels (through the camera for world nodes) |
| `node.fromScreen(x, y)` | Screen pixels | The node's local space |
| `node.worldPosition()` | | The node's origin in world space |
| `node.worldBounds()` | | The node's bounding `Rect` in world space |
| `a.distanceTo(b)` | | World distance between two nodes, in pixels |
| `a.directionTo(b)` | | Unit `Vec2` from `a` toward `b` |

`localToWorld` and `worldToLocal` accept any `{ x, y }` value. Each call returns a new `Vec2`.

```ts
import { Node } from "willow";

class Spaces {
    static main(): void {
        const map: Node = new Node("map");
        map.setPosition(200, 100);
        map.setScale(0.5);

        const local: Vec2 = map.worldToLocal(Vec2{ x: 300.0, y: 150.0 });
        console.log("a click at (300, 150) is (" + local.x + ", " + local.y + ") on the map");

        const hero: Node = new Node("hero");
        const goal: Node = new Node("goal");
        hero.setPosition(0, 0);
        goal.setPosition(30, 40);
        console.log("distance: " + hero.distanceTo(goal));
    }
}
```

Output:

```text
a click at (300, 150) is (200, 100) on the map
distance: 50
```

## Names and user data

`name` is a free-form label, useful in logs and for lookups with a [`NodeIndex`](../reference/node-index.md). `userData` holds any value you want to attach to a node; willow never reads it.

## Next

- [Sprites and textures](./sprites-and-textures.md)
- [Node reference](../reference/node.md) lists every field and method.

---

URL: https://thicketscript.com/willow/guide/performance

# Performance

## How willow draws a frame

Each frame willow walks the tree and records a draw command per visible node. It then sorts the commands (render layer, then `zOrder`, then tree order) and merges neighbours that share a **batch key** into one GPU draw. The key is the render target, the shader, the blend mode and the texture page. Transforms are only recomputed for nodes that moved, or whose ancestor moved.

So the cheapest scene is one where many nodes in a row share a texture and a blend mode.

## What helps

| Do this | Because |
|---|---|
| **Put sprites that draw together on one texture page.** Use an `Atlas` or `TextureRegion.grid` on a shared sheet. | Neighbouring sprites from the same page merge into one draw. Alternating between two images breaks the batch every time. |
| **Keep blend modes grouped.** | A change of blend mode starts a new batch. Put all `"add"` effects on their own layer. |
| **Use `SpriteBatch` for thousands of simple sprites.** | Each element is a few numbers, not a node: no transform walk, no hit testing, no children. See [Sprites and textures](./sprites-and-textures.md#thousands-of-sprites-spritebatch). |
| **Use `TileLayer` for grids, under a `TilemapViewport` for big maps.** | One batch per layer, and only on-screen tiles are built. See [Tilemaps](./tilemaps.md). |
| **Cache still subtrees.** | See below. |
| **Turn on camera culling** (`engine.camera.cullEnabled = true`) for big worlds. | Nodes outside the view are skipped. |
| **Prefer draw filters.** `ColorMatrixFilter`, `PaletteFilter`, the pixel-perfect filters and `CustomDrawShaderFilter` on a single sprite apply during the normal draw. | `BlurFilter`, `OutlineFilter` and `CustomShaderFilter` render to an offscreen texture first. |
| **Dispose what you are done with.** | `dispose()` frees a node, texture or font now instead of waiting for the collector. |
| **Hide instead of rebuild.** `visible = false` skips a subtree. | Re-creating nodes and reloading textures every time a menu opens costs more than keeping them. |

## Cache a still subtree

`setCacheAsTree(true)` records a subtree's draw commands and replays them on later frames instead of walking it again. Moving the cached node, panning the camera and changing its alpha do not break the cache.

```ts
import { Node, Sprite, Texture, TextureRegion, CacheTreeMode } from "willow";

class Backdrop {
    static main(): void {
        const sheet: Texture = Texture.load("assets/props.png");
        const props: Array<TextureRegion> = TextureRegion.grid(sheet, 32, 32);

        const scenery: Node = new Node("scenery");
        for (let i: int = 0; i < 400; i++) {
            const s: Sprite = new Sprite(props[i % props.length]);
            s.setPosition((i * 53) % 1600, (i * 97) % 600);
            scenery.add(s);
        }
        engine.root2d.add(scenery);
        scenery.setCacheAsTree(true, CacheTreeMode.MANUAL);

        App.onFrame((dt: float): void => {
            if (Keyboard.isPressed(Key.R)) {
                const first: Node = scenery.children()[0];
                first.visible = !first.visible;
                scenery.invalidateCache();
            }
        });
    }
}
```

| Mode | When the cache rebuilds | Cost |
|---|---|---|
| `CacheTreeMode.MANUAL` (default) | Only when you call `invalidateCache()`. | Nothing extra per change. Best for big static scenery. |
| `CacheTreeMode.AUTO` | Whenever a field changes on the node or below it. | A small cost on every field write in the subtree. |

Cache subtrees that rarely change. A subtree that changes every frame gains nothing and pays for re-recording. Caching needs a real renderer; it does nothing without a window.

### Keep still and moving things apart

A cache belongs to one node and covers everything below it. One moving child is enough to make an `AUTO` cache re-record, or to make a `MANUAL` cache need an `invalidateCache()`. So split the tree by how things change, not only by what they are:

```text
level
├── scenery    setCacheAsTree(true)   tiles, props, background: never move
└── actors                            player, enemies, bullets: move every frame
```

The camera can pan over `scenery` and the cache still holds, because moving the cached node or the camera does not break it.

## Measure

`App.actualFps` and `App.actualTps` report the measured frame and tick rates over the last second, and `App.droppedTicks` counts ticks dropped after very slow frames. Watch them while you add content.

## Next

- [Running without a window](./headless.md)
- Reference: [CacheTreeMode](../reference/cache-tree.md), [SpriteBatch](../reference/sprite.md#spritebatch)

---

URL: https://thicketscript.com/willow/guide/physics

# Physics

willow can attach rigid bodies to nodes. A node with a body moves where the simulation puts it, so a falling crate is just a node you never move yourself.

## How it fits together

1. **A physics root.** Call `enablePhysics(config)` on a container node. Everything below it shares one isolated world. Physics roots cannot nest.
2. **Bodies.** Call `setBody(definition)` on a node under the root. The body starts at the node's current position and rotation.
3. **Stepping.** In a window app the scene steps every physics root once per logic tick. You can also step a root yourself with `stepPhysics(dt)`.

```ts
import { Node, PhysicsConfig, PhysicsBox, PhysicsDynamic, PhysicsStatic, PhysicsBody } from "willow";

class Drop {
    static main(): void {
        const world: Node = new Node("world");
        world.enablePhysics(new PhysicsConfig(Vec2{ x: 0.0, y: 900.0 }));

        const floor: Node = new Node("floor");
        floor.setPosition(200, 300);
        world.add(floor);
        floor.setBody(new PhysicsStatic(new PhysicsBox(400, 20)));

        const crate: Node = new Node("crate");
        crate.setPosition(200, 100);
        world.add(crate);
        crate.setBody(new PhysicsDynamic(new PhysicsBox(24, 24), 1, 0.5, 0.1));

        for (let i: int = 0; i < 120; i++) {
            world.stepPhysics(1 / 60);
        }
        console.log("crate rests at y = " + Math.round(crate.y));

        const body: PhysicsBody | null = crate.getBody();
        if (body !== null) {
            body.applyImpulse(Vec2{ x: 0.0, y: -300.0 });
            console.log("velocity after a kick: " + Math.round(body.velocity().y));
        }
    }
}
```

Output:

```text
crate rests at y = 278
velocity after a kick: -300
```

The floor's top is at 290 (300 minus half its 20 px height), and the crate's center rests half its 24 px height above that. Boxes are centered on the node's position.

This sample runs without a window, which makes physics easy to test. In a window app, add `world` to `engine.root2d`, give the nodes sprites, and leave the stepping to the scene.

## Bodies

| Definition | Moves by | Constructor |
|---|---|---|
| `PhysicsDynamic` | Forces, impulses, gravity and collisions. | `(shape, mass, friction?, elasticity?, moment?)` |
| `PhysicsStatic` | Never moves. Floors and walls. | `(shape, friction?, elasticity?)` |
| `PhysicsKinematic` | Your code, through velocity or position. Ignores forces and gravity. Moving platforms. | `(shape, friction?)` |

`elasticity` is bounciness from 0 to 1. A `moment` of 0 (the default) is worked out from the shape and mass.

## Shapes

| Shape | Constructor |
|---|---|
| `PhysicsCircle` | `(radius, offset?)` |
| `PhysicsBox` | `(width, height, cornerRadius?)`, centered on the node |
| `PhysicsSegment` | `(a, b, radius?)`, a line between two points |
| `PhysicsPolygon` | `(verts, cornerRadius?)`, the convex hull of the points |

## Driving a body

`getBody()` returns the live `PhysicsBody` (or `null`). It reads `position()`, `angle()`, `velocity()` and `angularVelocity()`, and changes them with `setPosition`, `setAngle`, `setVelocity`, `setAngularVelocity`, `applyImpulse` (an instant kick) and `applyForce` (a push until the next step).

`setBodyEnabled(false)` takes a body out of the simulation and keeps its state; `removeBody()` detaches it. `disablePhysics()` on the root removes every body below it.

## World settings

`PhysicsConfig(gravity?, iterations?, sleepTime?)`: gravity in pixels per second squared (positive y is down), solver iterations per step (0 means the default of 10), and how long a resting body waits before it sleeps (0 never sleeps).

## Next

- [Performance](./performance.md)
- Reference: [Physics](../reference/physics.md)

---

URL: https://thicketscript.com/willow/guide/rope-and-distortion

# Rope and distortion

## Rope

A **`Rope`** stretches a texture along a path as a ribbon: cables, tails, trails, lightning, banners. Give it points, or a curve to generate them from.

```ts
import { Rope, RopeConfig, RopeCurveMode, Texture } from "willow";

class Cable {
    static main(): void {
        const tex: Texture = Texture.load("assets/cable.png");

        const cfg: RopeConfig = {
            width: 8,
            curveMode: RopeCurveMode.CATENARY,
            start: Vec2{ x: 100.0, y: 100.0 },
            end: Vec2{ x: 600.0, y: 120.0 },
            sag: 80,
            segments: 32,
        };
        const cable: Rope = new Rope(tex, cfg);
        engine.root2d.add(cable);

        let t: float = 0;
        App.onFrame((dt: float): void => {
            t += dt;
            const c: RopeConfig = cable.config;
            c.sag = 80 + Math.sin(t * 2) * 20;
            cable.config = c;
            cable.update();
        });
    }
}
```

| Curve mode | Shape | Uses |
|---|---|---|
| `LINE` | Straight from `start` to `end`. | |
| `CATENARY` | A hanging cable. | `sag` |
| `QUAD_BEZIER` | A quadratic curve. | `control0` |
| `CUBIC_BEZIER` | A cubic curve. | `control0`, `control1` |
| `WAVE` | A sine wave along the line. | `amplitude`, `frequency`, `phase` |

Other options: `width`, `segments` (default 20), `joinMode` (`RopeJoinMode.MITER` or `BEVEL`) and `color`. For a free-form path, pass a flat `[x0, y0, x1, y1, ...]` array instead of a config, and change it later with `setPoints`. After changing `config`, call `update()` to rebuild the ribbon.

## DistortionGrid

A **`DistortionGrid`** draws a texture as a grid of `cols` by `rows` cells whose corners you can push around: ripples, jelly, flags, heat haze.

```ts
import { DistortionGrid, Texture } from "willow";

class Flag {
    static main(): void {
        const flag: DistortionGrid = new DistortionGrid(Texture.load("assets/flag.png"), 12, 6);
        flag.setPosition(250, 150);
        engine.root2d.add(flag);

        let t: float = 0;
        App.onFrame((dt: float): void => {
            t += dt;
            for (let col: int = 0; col <= flag.cols; col++) {
                for (let row: int = 0; row <= flag.rows; row++) {
                    const wave: float = Math.sin(t * 4 + col * 0.6) * col * 1.5;
                    flag.setVertex(col, row, 0, wave);
                }
            }
        });
    }
}
```

`setVertex(col, row, dx, dy)` offsets one grid corner from its rest position (`setPoint` is the same call). A grid of `cols` by `rows` cells has corners from 0 to `cols` and 0 to `rows`. `reset()` puts every corner back.

## Next

- [Physics](./physics.md)
- Reference: [Rope and DistortionGrid](../reference/rope.md)

---

URL: https://thicketscript.com/willow/guide/scene-graph

# The scene graph

willow keeps everything you see in one tree of **nodes**. Each node has a transform (position, scale, rotation, pivot, skew) and an alpha, and its children inherit them. Every frame willow walks the tree, works out each node's world transform, and draws it. You change node fields; willow does the drawing.

```text
Scene
├── root  (engine.root2d)        the world: drawn through the camera
│   ├── background   Quad
│   ├── level        Node
│   │   ├── tiles    TileLayer
│   │   └── player   Sprite
│   │       └── nameTag  Text      moves with the player
│   └── lights       LightLayer
└── screenRoot  (engine.screen2d)  the screen: no camera
    └── hud          Node
        └── score    Text
```

## Nodes and containers

`Node` is the base class of every display object. A plain `new Node("name")` draws nothing; it is a container you group other nodes under. Move the container and everything inside it moves too.

| Node type | Draws |
|---|---|
| `Node` | Nothing. A group. |
| `Sprite` | An image or part of one. |
| `SpriteBatch` | Thousands of simple sprites from one texture. |
| `Quad` | A solid rectangle (or a line, with `Quad.line`). |
| `Text` | A string in a font. |
| `Polygon`, `Mesh` | Filled shapes and raw triangles. |
| `TileLayer` | A grid of tiles. |
| `ParticleEmitter` | Pooled particles. |
| `LightLayer` | Darkness with lights cut out of it. |
| `Rope`, `DistortionGrid` | A ribbon along a path; a deformable textured grid. |

Every one of them extends `Node`, so they all have `x`, `y`, `add`, `onClick` and the rest.

## The scene

The window app has one **scene**. It owns two roots and a camera:

| What | Script name | Use it for |
|---|---|---|
| World root | `engine.root2d`, or `Scene.main.root` | The game world. Drawn through the camera, so it scrolls and zooms. |
| Screen root | `engine.screen2d`, or `Scene.main.screenRoot` | Menus and HUDs. Drawn after the world, in screen pixels, without the camera. |
| Camera | `engine.camera`, or `Scene.main.camera` | Which part of the world is on screen. See [Camera and layers](./camera-and-layers.md). |

Pointer input reaches the screen root first. If no visible, interactive node there takes the event, it falls through to the world.

`engine` is the window app's global. `Scene.main` is the same scene, typed `Scene | null` because a console program has no scene. Library code that should load in any program reads `Scene.main` and checks it for null:

```ts
import { Quad } from "willow";

class Hud {
    static main(): void {
        const scene: Scene | null = Scene.main;
        if (scene === null) {
            console.log("no scene: this program has no window");
            return;
        }
        const bar: Quad = new Quad(scene.width, 32, Color.hex("#00000080"));
        scene.screenRoot.add(bar);
        scene.backgroundColor = 0x0E1E3CFF;
    }
}
```

The scene also knows its size (`width`, `height`), the last frame time (`frameTime`), the time since it started (`elapsed`), and which node has keyboard focus (`focus`).

## Draw order

Three things decide what draws on top, in this order:

1. **`renderLayer`**, 0 to 255. A higher layer always draws over a lower one, wherever the node sits in the tree. A node with no layer of its own uses its nearest ancestor's, so set it once on a subtree's root. The scene has named values: `LAYER_BACKGROUND` (0), `LAYER_DEFAULT` (64), `LAYER_UI` (192) and `LAYER_OVERLAY` (255).
2. **`zOrder`** within the same parent. Higher draws on top.
3. **Tree order.** Among siblings with the same `zOrder`, a child added later draws on top. `addAt(child, index)` inserts at a position.

`globalOrder` breaks ties between nodes on the same render layer regardless of where they are in the tree.

```ts
import { Node, Quad } from "willow";

class Layers {
    static main(): void {
        const world: Node = new Node("world");
        const ui: Node = new Node("ui");
        engine.root2d.add(ui);
        engine.root2d.add(world);

        // ui was added first, but its layer puts it on top of the world.
        ui.renderLayer = engine.scene.LAYER_UI;
        world.renderLayer = engine.scene.LAYER_DEFAULT;

        ui.add(new Quad(200, 40, Color.WHITE));
        world.add(new Quad(800, 600, Color.hex("#224466")));
    }
}
```

## Adding, removing and disposing

| Call | Effect |
|---|---|
| `parent.add(child)` | Appends `child`. If it had a parent, it moves. |
| `parent.addAt(child, i)` | Inserts at index `i`. |
| `parent.removeChild(child)` / `child.remove()` | Detaches it. It still exists and can be added again. |
| `parent.removeAllChildren()` | Detaches every child. |
| `node.dispose()` | Frees the node now. Any later use raises `InvalidStateError`. |
| `parent.children()` | A snapshot array of direct children. |
| `parent.contains(child)` | True for a direct child. |

Removing a node is cheap and reversible. Dispose a node when you are done with it for good, for example an enemy that died; a disposed node leaves its parent's `children()` and its tweens stop.

## Events up the tree

Besides the typed handlers (`onClick` and friends, see [Input and hit testing](./input-and-hit-testing.md)), any node can emit a named event that bubbles up through its ancestors:

```ts
import { Node, Event } from "willow";

class Bubbling {
    static main(): void {
        const level: Node = new Node("level");
        const chest: Node = new Node("chest");
        level.add(chest);

        level.on("opened", (e: Event): void => {
            console.log(e.currentTarget.name + " heard " + e.type + " from " + e.target.name + ": " + e.data);
        });

        chest.emit("opened", "50 gold");
    }
}
```

Output:

```text
level heard opened from chest: 50 gold
```

A listener can call `e.stopPropagation()` to stop the event going further up. `off(name, handler)` and `offAll()` remove listeners.

## Next

- [Nodes and transforms](./nodes-and-transforms.md)
- [Lifecycle and time](./lifecycle-and-time.md) covers `onReady`, `onUpdate`, `onTick` and pausing a subtree.

---

URL: https://thicketscript.com/willow/guide/shapes-and-meshes

# Shapes and meshes

willow draws shapes without any image: rectangles, lines, polygons and raw triangle meshes. They are ordinary nodes, so they move, rotate, fade and take input like sprites.

## Rectangles and lines

```ts
import { Quad } from "willow";

class Bars {
    static main(): void {
        const back: Quad = new Quad(200, 20, Color.hex("#3A1010"));
        back.setPosition(20, 20);
        engine.root2d.add(back);

        const health: Quad = new Quad(200, 20, Color.hex("#E04040"));
        health.setPosition(20, 20);
        health.scaleX = 0.6;
        engine.root2d.add(health);

        const laser: Quad = Quad.line(100, 300, 500, 220, 3, Color.hex("#7CF2FF"));
        laser.blendMode = "add";
        engine.root2d.add(laser);
    }
}
```

- `new Quad(w, h, color)` is a solid rectangle. Change it with `color`, `width` and `height`.
- Scaling a bar with `scaleX` from its left edge is the easy way to draw a meter.
- `Quad.line(x1, y1, x2, y2, thickness, color)` makes a line as a thin rotated quad, with the position and rotation set for you.

## Polygons

`Polygon` fills a shape given as a flat list of points `[x0, y0, x1, y1, ...]`. Factories cover the common shapes:

| Factory | Shape |
|---|---|
| `new Polygon(points, color)` | Any simple polygon, at least three points. |
| `Polygon.regular(sides, radius, color)` | A regular polygon centered on the origin. |
| `Polygon.circle(radius, color)` | A circle (a 32-sided regular polygon). |
| `Polygon.star(points, outer, inner, color)` | A star. |
| `Polygon.triangle(x1, y1, x2, y2, x3, y3, color)` | A triangle. |
| `Polygon.textured(texture, points)` | A polygon filled with an image, mapped across its bounding box. |

```ts
import { Polygon } from "willow";

class Shapes {
    static main(): void {
        const sun: Polygon = Polygon.circle(40, Color.hex("#FFD24A"));
        sun.setPosition(120, 120);
        engine.root2d.add(sun);

        const star: Polygon = Polygon.star(5, 30, 12, Color.WHITE);
        star.setPosition(300, 120);
        engine.root2d.add(star);

        const hill: Polygon = new Polygon([0, 600, 0, 450, 200, 380, 450, 430, 800, 360, 800, 600], Color.hex("#2F6B3A"));
        engine.root2d.add(hill);

        App.onFrame((dt: float): void => {
            star.rotation += dt;
        });
    }
}
```

Polygon colours are full `Color` values with alpha. If you write a raw number, use all eight hex digits (`0xRRGGBBAA`): a six-digit number has an alpha of 0 and is invisible.

Replace a polygon's points with `setPoints(points, color?)`.

## Meshes

`Mesh` draws your own triangles. Vertices are flat, eight numbers each: `x, y, u, v, r, g, b, a` (colours 0 to 1). Indices list three vertices per triangle.

```ts
import { Mesh } from "willow";

class Gradient {
    static main(): void {
        const vertices: Array<float> = [
            0, 0, 0, 0, 1, 0, 0, 1,
            300, 0, 1, 0, 0, 1, 0, 1,
            300, 200, 1, 1, 0, 0, 1, 1,
            0, 200, 0, 1, 1, 1, 0, 1,
        ];
        const indices: Array<int> = [0, 1, 2, 0, 2, 3];
        const quad: Mesh = new Mesh(vertices, indices);
        quad.setPosition(250, 200);
        engine.root2d.add(quad);
    }
}
```

`tint` multiplies every vertex colour at draw time, so recolouring a mesh does not rebuild it. After editing vertices with `setVertices`, willow updates the bounds; call `invalidateBounds()` only if you changed them some other way.

## Custom paint

For full control, give a node a paint function with `setCustomPaint`. It runs each frame instead of the node's normal drawing and receives a `Painter`.

```ts
import { Node, Painter, TrianglesPaint } from "willow";

class Painted {
    static main(): void {
        const node: Node = new Node("painted");
        node.setPosition(400, 300);
        engine.root2d.add(node);

        node.setCustomPaint((painter: Painter): void => {
            const m: Array<float> = painter.worldTransform();
            const px: Array<float> = [0, -40, 40, 30, -40, 30];
            const verts: Array<float> = [];
            for (let i: int = 0; i < 3; i++) {
                const x: float = px[i * 2];
                const y: float = px[i * 2 + 1];
                verts.push(m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5], 0, 0, 1, 0.5, 0, 1);
            }
            painter.appendTriangles(new TrianglesPaint(verts, [0, 1, 2]));
        });
    }
}
```

- Painted vertices are in **world** space. `worldTransform()` returns `[a, b, c, d, tx, ty]`; a local point `(x, y)` maps to `(a*x + c*y + tx, b*x + d*y + ty)`. The camera is applied afterwards.
- `painter.paintDefault()` draws the node's normal content too, so you can add to a sprite rather than replace it.
- `painter.isBuildingCache()` is true while a [cached subtree](./performance.md#cache-a-still-subtree) is being recorded; skip animated extras then.
- The `Painter` is only valid during the call. Don't keep it.
- Pass `null` to `setCustomPaint` to remove the function.

## Next

- [Tweens and transitions](./tweens-and-transitions.md)
- Reference: [Quad](../reference/quad.md), [Polygon and Mesh](../reference/polygon-mesh.md), [Custom paint](../reference/custom-paint.md)

---

URL: https://thicketscript.com/willow/guide/sprites-and-textures

# Sprites and textures

A **`Texture`** is an image on the GPU. A **`TextureRegion`** is a rectangle inside a texture. A **`Sprite`** is a node that draws a texture or a region.

## Sprites

`Sprite` has three constructors:

| Constructor | Use it when |
|---|---|
| `new Sprite("assets/hero.png")` | One sprite uses the image. The sprite loads it. |
| `new Sprite(texture)` | Several sprites share one loaded texture. |
| `new Sprite(region)` | The sprite shows one frame or tile of a larger image. |

```ts
import { Sprite, Texture } from "willow";

class Coins {
    static main(): void {
        const coinTex: Texture = Texture.load("assets/coin.png");

        for (let i: int = 0; i < 5; i++) {
            const coin: Sprite = new Sprite(coinTex);
            coin.setAnchor(0.5, 0.5);
            coin.x = 100 + i * 80;
            coin.y = 200;
            engine.root2d.add(coin);
        }

        const ghost: Sprite = new Sprite(coinTex);
        ghost.x = 100;
        ghost.y = 300;
        ghost.tint = Color.hex("#80C0FF");
        ghost.alpha = 0.5;
        engine.root2d.add(ghost);
    }
}
```

`tint` multiplies the image's colours. `Color.WHITE` (the default) leaves it unchanged. `width` and `height` read the size of the region being drawn, before scale.

To change what a sprite shows, call `setTexture(texture)` or `setRegion(region)`.

Loading needs the `fs` permission in `thicket.json`. `Texture.load` caches by path, so loading the same file twice returns the same image; pass `{ cache: false }` to load a fresh copy.

## Textures from other sources

| Call | Makes a texture from |
|---|---|
| `Texture.load(path)` | A PNG or JPEG file. |
| `Texture.fromBuffer(buffer)` | PNG or JPEG bytes already in memory. |
| `Texture.fromPixels(w, h, rgba, updatable)` | Raw RGBA bytes, `w * h * 4` of them. Pass `updatable = true` to replace them later with `update(rgba)`. |

Call `dispose()` on a texture you no longer need to free the GPU memory.

## Regions and tilesets

`TextureRegion.fromRect(texture, x, y, w, h)` cuts out one rectangle. `TextureRegion.grid(texture, tileW, tileH)` slices a whole tileset into an array, row by row:

```ts
import { Sprite, Texture, TextureRegion } from "willow";

class Tiles {
    static main(): void {
        const sheet: Texture = Texture.load("assets/tileset.png");
        const tiles: Array<TextureRegion> = TextureRegion.grid(sheet, 32, 32);

        const grass: Sprite = new Sprite(tiles[0]);
        grass.x = 0;
        engine.root2d.add(grass);

        const water: Sprite = new Sprite(tiles[5]);
        water.x = 32;
        engine.root2d.add(water);

        const door: TextureRegion = TextureRegion.fromRect(sheet, 64, 96, 32, 64);
        const doorSprite: Sprite = new Sprite(door);
        doorSprite.x = 64;
        engine.root2d.add(doorSprite);
    }
}
```

`grid` takes an optional fourth argument `{ columns, count, margin, spacing }` for tilesets with gaps between cells.

## Atlases

An **`Atlas`** is a set of named regions on one texture page. Sprites that share a page can draw in one batch (see [Performance](./performance.md)).

| Factory | How the atlas is built |
|---|---|
| `Atlas.load(json, texture)` | From a TexturePacker-style JSON manifest and its page texture. |
| `Atlas.create(config?)` | Empty; pack images in one at a time with `add(name, w, h, rgba)`. |
| `Atlas.createBatch(config?)` | Empty; `stage` every image, then `pack()` once for a tighter fit. |

`PackerConfig` sets the page size (2048x2048 by default) and the padding between images (1 pixel).

```ts
import { Sprite, Texture, Atlas } from "willow";
import { Files } from "fs";

class Packed {
    static main(): void {
        const page: Texture = Texture.load("assets/sprites.png");
        const json: string = Files.readText("assets/sprites.json");
        const atlas: Atlas = Atlas.load(json, page);

        const hero: Sprite = new Sprite(atlas.region("hero_idle"));
        hero.x = 200;
        hero.y = 200;
        engine.root2d.add(hero);

        if (!atlas.has("hero_jump")) {
            console.log("hero_jump is missing from the atlas");
        }
    }
}
```

`region(name)` returns a small magenta placeholder for a missing name, so a typo shows up on screen instead of crashing. Check with `has(name)` when the name comes from data.

The `atlaspack` tool (`thicket tool atlaspack`) packs a folder of images into an atlas ahead of time.

## Thousands of sprites: SpriteBatch

A `Sprite` is a full node: it can have children, filters and input handlers. When you have thousands of things that only move, scale, rotate or tint (bullets, stars, debris), a **`SpriteBatch`** is much cheaper. Its elements are a few numbers each, not nodes, and they all share the batch's one texture.

```ts
import { SpriteBatch, Texture } from "willow";

class Starfield {
    static main(): void {
        const stars: SpriteBatch = new SpriteBatch(Texture.load("assets/star.png"));
        engine.root2d.add(stars);

        const handles: Array<float> = [];
        const speeds: Array<float> = [];
        for (let i: int = 0; i < 2000; i++) {
            handles.push(stars.addSprite(Math.random() * 800, Math.random() * 600));
            speeds.push(20 + Math.random() * 80);
        }

        App.onFrame((dt: float): void => {
            for (let i: int = 0; i < handles.length; i++) {
                const h: float = handles[i];
                const angle: float = App.time * 0.1 + i;
                stars.setSpritePosition(h, (i * 37) % 800, (App.time * speeds[i] + i * 13) % 600);
                stars.setSpriteRotation(h, angle);
            }
        });
    }
}
```

`addSprite` returns a handle. Pass it to `setSpritePosition`, `setSpriteScale`, `setSpriteRotation`, `setSpriteAlpha`, `setSpriteTint` and `setSpriteRegion`, or remove the element with `removeSprite(handle)`. A removed handle stays dead: it is rejected rather than pointing at another element. `setSpritePositions(flatArray)` moves every element in one call.

Elements rotate and scale around their top-left corner.

## Frame animation

An **`AnimationPlayer`** swaps a sprite's region over time. Give it named **`AnimationSequence`**s and play one by name:

```ts
import { Sprite, Texture, TextureRegion, AnimationPlayer, AnimationSequence } from "willow";

class Walker {
    static main(): void {
        const frames: Array<TextureRegion> = TextureRegion.grid(Texture.load("assets/hero.png"), 32, 32);

        const hero: Sprite = new Sprite(frames[0]);
        hero.setAnchor(0.5, 1.0);
        hero.x = 400;
        hero.y = 400;
        engine.root2d.add(hero);

        const anim: AnimationPlayer = new AnimationPlayer(hero);
        anim.addSequence(new AnimationSequence("idle", [frames[0], frames[1]], 2, true));
        anim.addSequence(new AnimationSequence("walk", [frames[2], frames[3], frames[4], frames[5]], 10, true));
        anim.play("idle");

        App.onFrame((dt: float): void => {
            if (Keyboard.isDown(Key.RIGHT)) {
                hero.x += 120 * dt;
                hero.scaleX = 1;
                anim.play("walk");
            } else if (Keyboard.isDown(Key.LEFT)) {
                hero.x -= 120 * dt;
                hero.scaleX = -1;
                anim.play("walk");
            } else {
                anim.play("idle");
            }
        });
    }
}
```

- `play(name)` does nothing if that sequence is already playing, so calling it every frame is fine.
- A player whose node is in the scene is advanced by the scene each frame. If you call `update(dt)` yourself, you take over and the scene stops advancing that player.
- `onComplete(fn)` runs when a non-looping sequence reaches its last frame.
- `scaleX = -1` mirrors the sprite. With the anchor at the center, it flips in place.

## Next

- [Text and fonts](./text-and-fonts.md)
- Reference: [Sprite](../reference/sprite.md), [Texture](../reference/texture.md), [Atlas](../reference/atlas.md), [AnimationPlayer](../reference/animation.md)

---

URL: https://thicketscript.com/willow/guide/text-and-fonts

# Text and fonts

A **`Text`** node draws a string. A **`Font`** is the typeface it uses. willow draws most fonts as signed distance fields (SDF), so text stays sharp at any size and scale.

## A label

```ts
import { Text, Font } from "willow";

class Title {
    static main(): void {
        const title: Text = new Text("Welcome", Font.system());
        title.fontSize = 48;
        title.color = Color.hex("#FFE9A8");
        title.align = "center";
        title.alignPivot();
        title.x = 400;
        title.y = 120;
        engine.root2d.add(title);
    }
}
```

`new Text(string)` without a font uses the default font. Assigning `text`, `font`, `fontSize` or `style` lays the text out again on the next frame.

## Text properties

| Property | Meaning | Default |
|---|---|---|
| `text` | The string. | |
| `font` | The `Font`. | willow's bundled font |
| `fontSize` | Size in pixels. | 16 |
| `color` | Fill colour, a `Color`. | white |
| `align` | `"left"`, `"center"` or `"right"`. | `"left"` |
| `wrapWidth` | Wrap lines to this width in pixels. 0 means no wrapping. | 0 |
| `lineHeight` | Line spacing multiplier. | 1 |
| `style` | `"regular"`, `"bold"`, `"italic"` or `"boldItalic"`. | `"regular"` |
| `sharpness` | SDF edge sharpness, 0 to 1. Higher narrows the soft edge. | 0 |
| `pixelSnap` | Puts the text on whole pixels when not rotated, which keeps small text crisp. Turn it off for slowly moving text so it glides. | `true` |
| `width`, `height` | Measured size, after the first layout. | |

`measure()` lays the text out right away and returns its `{ width, height }`, so you can size a panel before the first frame.

## Outline, glow and shadow

Each `Text` has an `effects` object. A width of 0 turns an effect off.

```ts
import { Text } from "willow";

class Damage {
    static main(): void {
        const hit: Text = new Text("-25");
        hit.fontSize = 36;
        hit.color = Color.hex("#FF5A4F");
        hit.effects.outlineWidth = 3;
        hit.effects.outlineColor = Color.BLACK;
        hit.effects.shadowOffsetX = 2;
        hit.effects.shadowOffsetY = 3;
        hit.effects.shadowColor = Color.hex("#00000099");
        hit.x = 300;
        hit.y = 200;
        engine.root2d.add(hit);
    }
}
```

`glowWidth` and `glowColor` add a soft glow.

## Fonts

| Factory | Loads |
|---|---|
| `Font.system()` | willow's bundled default font. |
| `Font.load(path)` | A `.fontbundle` file (baked ahead of time with `thicket tool fontgen`). |
| `Font.fromBuffer(buffer)` | A font bundle already in memory. |
| `Font.loadTTF(path, config?)` | A TTF or OTF file, baked once while it loads. |
| `Font.fromTTF(buffer, config?)` | TTF or OTF bytes in memory, baked once. |
| `Font.loadTTFCached(ttf, cacheDir, options?)` | A TTF or OTF, baked the first time and saved as a bundle in `cacheDir`; later runs load the saved bundle. |
| `Font.fromPixelFont(texture, cellW, cellH, chars)` | A bitmap font sheet of fixed-size cells, in row order. |

Baking never happens per frame. For a shipped game, bake fonts ahead of time with `fontgen` or let `loadTTFCached` keep the result.

```ts
import { Text, Font } from "willow";

class Fonts {
    static main(): void {
        const body: Font = Font.loadTTFCached("assets/fonts/Inter.ttf", ".cache/fonts", { sizes: [32], charset: "latin" });
        const pixel: Font = Font.fromPixelFont("assets/fonts/pixel.png", 8, 8, " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ");

        const a: Text = new Text("Smooth at any size", body);
        a.fontSize = 28;
        a.y = 40;
        engine.root2d.add(a);

        const b: Text = new Text("PIXEL FONT", pixel);
        b.fontSize = 16;
        b.y = 100;
        engine.root2d.add(b);
    }
}
```

`font.measure(text, size)` measures a string without making a node.

## Text input

A `Text` with `type = TextFieldType.INPUT` takes typing while it has focus. Give it focus with `engine.scene.focus = field`.

```ts
import { Text, TextFieldType, TextInputEvent } from "willow";

class NameEntry {
    static main(): void {
        const field: Text = new Text("");
        field.type = TextFieldType.INPUT;
        field.maxChars = 12;
        field.restrict = /[A-Za-z0-9 ]/;
        field.x = 100;
        field.y = 100;
        engine.root2d.add(field);
        engine.scene.focus = field;

        field.onTextInput((e: TextInputEvent): void => {
            if (e.text === "#") {
                e.preventDefault();
            }
        });
        field.onChange((): void => {
            console.log("name is now " + field.text);
        });
    }
}
```

- `maxChars` limits the length; `restrict` is a pattern each typed character must match.
- `onTextInput` runs before text is added and can cancel it with `preventDefault()`.
- `onChange` runs after typing or Backspace changes `text`.
- `onTextComposition` reports IME pre-edit text (for languages typed through an input method). It never changes `text`.

A plain input `Text` supports typing and Backspace at the end. For a caret, selection and clipboard, use willowui's `TextInput` or `TextArea`.

## Next

- [Shapes and meshes](./shapes-and-meshes.md)
- Reference: [Text](../reference/text.md), [Font](../reference/font.md)

---

URL: https://thicketscript.com/willow/guide/tilemaps

# Tilemaps

A **`TileLayer`** draws a whole grid of tiles as one batch. Use it instead of one `Sprite` per cell: a 200x200 map is 40,000 cells, and as sprites that is 40,000 nodes.

## A tile layer

```ts
import { Texture, TextureRegion, TileLayer } from "willow";

class TileDemo {
    static main(): void {
        const tiles: Texture = Texture.load("assets/tileset.png");
        const regions: Array<TextureRegion> = TextureRegion.grid(tiles, 16, 16);

        const COLS: int = 50;
        const ROWS: int = 38;
        const data: Array<int> = [];
        for (let row: int = 0; row < ROWS; row++) {
            for (let col: int = 0; col < COLS; col++) {
                const edge: boolean = row === 0 || col === 0 || row === ROWS - 1 || col === COLS - 1;
                data.push(edge ? 2 : 1);
            }
        }

        const ground: TileLayer = new TileLayer({
            tileWidth: 16, tileHeight: 16, columns: COLS, rows: ROWS,
            tileset: tiles, regions: regions, data: data,
        });
        engine.root2d.add(ground);

        ground.setTile(10, 10, TileLayer.encodeGid(3, true));
    }
}
```

**GIDs.** Each cell holds a number. 0 is empty; N draws `regions[N - 1]`. The top bits carry the horizontal, vertical and diagonal flip flags used by the Tiled editor. Use `TileLayer.encodeGid(index, flipH, flipV, flipD)` and `TileLayer.decodeGid(gid)` rather than packing bits yourself.

| Method | Does |
|---|---|
| `setTile(col, row, gid)` | Changes one cell. |
| `getTile(col, row)` | Reads one cell, with any tile animation applied. |
| `setData(array)` | Replaces the whole grid. The length must be `columns * rows`. |
| `setAnimation(gid, frames, fps)` | Animates every cell showing `gid` through a list of GIDs, like water or torches. |
| `query()` | A read-only `TileQuery` for collision and pathfinding. |

Out-of-range cells raise an error rather than being ignored.

## Culling big maps

A bare `TileLayer` draws its whole grid. Put it under a **`TilemapViewport`** and only the tiles inside the camera view (plus a margin) are drawn each frame, so a huge map stays cheap:

```ts
import { Texture, TextureRegion, TileLayer, TilemapViewport } from "willow";

class BigMap {
    static main(): void {
        const tiles: Texture = Texture.load("assets/tileset.png");
        const data: Array<int> = [];
        for (let i: int = 0; i < 512 * 512; i++) {
            data.push(1 + (i % 7));
        }

        const view: TilemapViewport = new TilemapViewport({ padding: 64 });
        engine.root2d.add(view);

        const ground: TileLayer = new TileLayer({
            tileWidth: 16, tileHeight: 16, columns: 512, rows: 512,
            tileset: tiles, regions: TextureRegion.grid(tiles, 16, 16), data: data,
        });
        view.add(ground);
    }
}
```

`padding` is the extra margin, in world pixels, drawn beyond the edge of the view.

## Querying tiles

```ts
import { Texture, TextureRegion, TileLayer, TileQuery, Sprite } from "willow";

class Walls {
    static main(): void {
        const tiles: Texture = Texture.load("assets/tileset.png");
        const data: Array<int> = [];
        for (let i: int = 0; i < 20 * 15; i++) {
            data.push(i % 20 === 0 ? 2 : 1);
        }
        const ground: TileLayer = new TileLayer({
            tileWidth: 32, tileHeight: 32, columns: 20, rows: 15,
            tileset: tiles, regions: TextureRegion.grid(tiles, 32, 32), data: data,
        });
        engine.root2d.add(ground);
        const map: TileQuery = ground.query();

        const hero: Sprite = new Sprite("assets/hero.png");
        hero.setPosition(100, 100);
        engine.root2d.add(hero);

        App.onFrame((dt: float): void => {
            let nx: float = hero.x;
            if (Keyboard.isDown(Key.LEFT)) {
                nx -= 150 * dt;
            }
            if (map.tileAtWorld(nx, hero.y) !== 2) {
                hero.x = nx;
            }
        });
    }
}
```

`TileQuery` also has `tileAt(col, row)`, `rawAt(col, row)` (ignoring animation), `worldToTile(x, y)` and `tileToWorld(col, row)`. Out-of-range reads return 0.

Pair a tilemap with the camera's `scrollToTile(col, row, seconds)` to move the view to a cell.

## Next

- [Effects](./effects.md)
- Reference: [TileLayer](../reference/tilemap.md)

---

URL: https://thicketscript.com/willow/guide/tweens-and-transitions

# Tweens and transitions

A **tween** moves a value from where it is to a target over a set time, along an easing curve. A **transition** blends one part of the scene into another, like a crossfade between two screens.

## Tweening a node

`TweenGroup` has one factory per field. Each takes a `TweenConfig` with the duration in seconds, an optional easing curve and an optional callback for the end.

```ts
import { Sprite, TweenGroup, TweenConfig } from "willow";

class Pickup {
    static main(): void {
        const gem: Sprite = new Sprite("assets/gem.png");
        gem.setAnchor(0.5, 0.5);
        gem.setPosition(400, 500);
        engine.root2d.add(gem);

        TweenGroup.position(gem, 400, 300, new TweenConfig(0.6, Ease.OUT_BACK));
        TweenGroup.scale(gem, 1.5, 1.5, new TweenConfig(0.6, Ease.OUT_CUBIC));
        TweenGroup.alpha(gem, 0, new TweenConfig(1.2, Ease.IN_QUAD, (): void => {
            gem.dispose();
        }));
    }
}
```

| Factory | Animates |
|---|---|
| `TweenGroup.position(node, x, y, cfg)` | `x` and `y` |
| `TweenGroup.scale(node, sx, sy, cfg)` | `scaleX` and `scaleY` |
| `TweenGroup.rotation(node, radians, cfg)` | `rotation` |
| `TweenGroup.alpha(node, alpha, cfg)` | `alpha` |
| `TweenGroup.color(node, color, cfg)` | `tint` on a sprite, `color` on a quad, text or polygon |
| `TweenGroup.value(from, to, cfg, onStep)` | A plain number, passed to `onStep(v)` each step |

Things to know:

- **Tweens run themselves.** willow advances every live tween once per frame. You don't call `update`. (`update(dt)` exists for stepping a tween by hand in tests, and it adds to the automatic step.)
- `cancel()` stops a tween where it is. `done` is true once it has finished.
- If the node is disposed, its tweens end quietly. The `onDone` callback does not run when a tween is cancelled or its node is disposed.
- A tween on a node inside a [paused](./lifecycle-and-time.md#pausing) subtree waits while the subtree is paused.
- `TweenGroup.activeCount()` counts unfinished tweens, which helps when looking for leaks.

The easing curve is a built-in `Ease` constant such as `Ease.LINEAR` (the default), `Ease.OUT_CUBIC` or `Ease.OUT_BACK`. You can also pass your own function `(t, b, c, d): float`, where `t` is the elapsed time, `b` the start value, `c` the change and `d` the duration.

## Tweening a number

```ts
import { Text, TweenGroup, TweenConfig } from "willow";

class Counter {
    static main(): void {
        const score: Text = new Text("0");
        score.fontSize = 40;
        engine.root2d.add(score);

        TweenGroup.value(0, 1500, new TweenConfig(1.0, Ease.OUT_QUAD), (v: float): void => {
            score.text = "" + Math.round(v);
        });
    }
}
```

## Waiting and timers

Each node has its own `ticker`, and the app has `App.ticker`. Use them to wait or to repeat without writing your own timer:

```ts
import { Quad } from "willow";

class Blink {
    static async main(): Promise<void> {
        const warning: Quad = new Quad(800, 40, Color.hex("#C0302A"));
        engine.root2d.add(warning);

        warning.ticker.every(0.25, (): void => {
            warning.visible = !warning.visible;
        });

        await warning.ticker.wait(3);
        warning.dispose();
    }
}
```

A node's ticker pauses and scales with the node. Disposing the node cancels its pending waits.

## Transitions between screens

`engine.scene.playTransition(transition, from, to)` blends one subtree into another. Both are normally children of the world root. The promise resolves when the transition ends; the scene never removes either node, so you retire `from` yourself.

```ts
import { Node, Quad, Text, Transition } from "willow";

class Screens {
    static async main(): Promise<void> {
        const title: Node = new Node("title");
        title.add(new Quad(800, 600, Color.hex("#1B2A4A")));
        title.add(new Text("Press Space"));
        engine.root2d.add(title);

        const level: Node = new Node("level");
        level.add(new Quad(800, 600, Color.hex("#2F6B3A")));

        const off: Function = engine.scene.onKeyDown(async (e: KeyEvent): Promise<void> => {
            if (e.keyCode === Key.SPACE) {
                off();
                engine.root2d.add(level);
                await engine.scene.playTransition(Transition.fade(0.5), title, level);
                title.dispose();
            }
        });
    }
}
```

- `Transition.fade(seconds)` is the built-in crossfade.
- Optional fourth and fifth arguments pass each side's screen-root subtree (its menu or dialog box) so it fades with that side, while other screen nodes stay on top.
- Only one transition plays at a time; a second `playTransition` rejects. `cancelTransition()` stops the current one, and its promise rejects with a `CancellationError`.

### Writing your own transition

Extend `Transition`, call `super(seconds)` and override `render`. willow has already drawn both sides into regions; you draw them onto the canvas.

```ts
import { Node, Transition, TextureRegion, TransitionCanvas } from "willow";

class LeftWipe extends Transition {
    constructor(seconds: float) {
        super(seconds);
    }

    render(progress: float, outgoing: TextureRegion, incoming: TextureRegion, canvas: TransitionCanvas): void {
        canvas.draw(outgoing, 0.0, 0.0);
        canvas.drawPart(incoming, 0.0, 0.0, progress * canvas.width, canvas.height, 0.0, 0.0);
    }
}

class WipeDemo {
    static async main(): Promise<void> {
        const a: Node = new Node("a");
        const b: Node = new Node("b");
        engine.root2d.add(a);
        engine.root2d.add(b);
        await engine.scene.playTransition(new LeftWipe(0.4), a, b);
        a.dispose();
    }
}
```

`progress` runs from 0 to 1. Anything you don't draw lets the scene show through, so draw `outgoing` first. The regions and the canvas are only valid during the call.

## Next

- [Lifecycle and time](./lifecycle-and-time.md)
- Reference: [TweenGroup](../reference/tween.md), [Transition](../reference/transition.md), [Scene](../reference/scene.md)

---

URL: https://thicketscript.com/willow/recipes

# Recipes

Short answers to common tasks. Each links to the guide with the details.

## Spin a sprite in place

Center its pivot, then turn it. Rotation is in radians.

```ts
import { Sprite } from "willow";

class Spin {
    static main(): void {
        const s: Sprite = new Sprite("assets/gear.png");
        s.setAnchor(0.5, 0.5);
        s.setPosition(400, 300);
        engine.root2d.add(s);
        s.onUpdate = (dt: float): void => {
            s.rotation += Math.PI * dt;
        };
    }
}
```

See [Nodes and transforms](./guide/nodes-and-transforms.md#pivots-and-anchors).

## Flash a sprite red when hit

```ts
import { Sprite, TweenGroup, TweenConfig } from "willow";

class Hit {
    static flash(s: Sprite): void {
        s.tint = Color.hex("#FF4040");
        TweenGroup.color(s, Color.WHITE, new TweenConfig(0.3, Ease.OUT_QUAD));
    }

    static main(): void {
        const s: Sprite = new Sprite("assets/hero.png");
        engine.root2d.add(s);
        App.onFrame((dt: float): void => {
            if (Keyboard.isPressed(Key.H)) {
                Hit.flash(s);
            }
        });
    }
}
```

See [Tweens and transitions](./guide/tweens-and-transitions.md).

## Keep the HUD still while the world scrolls

Add HUD nodes to `engine.screen2d`, not `engine.root2d`. See [Camera and layers](./guide/camera-and-layers.md).

## Find the world point under the mouse

```ts
import { Quad } from "willow";

class Pick {
    static main(): void {
        const marker: Quad = new Quad(8, 8, Color.hex("#FFD24A"));
        engine.root2d.add(marker);
        App.onFrame((dt: float): void => {
            if (Mouse.isPressed(Mouse.LEFT)) {
                const p: Vec2 = engine.camera.screenToWorld(Vec2{ x: Mouse.x, y: Mouse.y });
                marker.setPosition(p.x, p.y);
            }
        });
    }
}
```

## Make a button

Give a `Quad` or `Sprite` an `onClick`, and change its colour in `onPointerEnter` and `onPointerLeave`. See [Input and hit testing](./guide/input-and-hit-testing.md#node-handlers). For themed buttons, labels and layouts, use [willowui](../willowui/).

## Remove an enemy for good

Call `enemy.dispose()`. It leaves its parent, its tweens stop and it leaves any `NodeIndex`. Use `remove()` instead if you plan to add it back. See [The scene graph](./guide/scene-graph.md#adding-removing-and-disposing).

## Pause the game but not the pause menu

Set `paused = true` on the game's root node and `pauseMode = PauseMode.ALWAYS` (or `WHEN_PAUSED`) on the menu. See [Lifecycle and time](./guide/lifecycle-and-time.md#pausing).

## Crossfade to the next level

`await engine.scene.playTransition(Transition.fade(0.5), oldLevel, newLevel)`, then dispose `oldLevel`. See [Tweens and transitions](./guide/tweens-and-transitions.md#transitions-between-screens).

## Draw thousands of bullets

Use one `SpriteBatch` with the bullet texture and move elements by handle. See [Sprites and textures](./guide/sprites-and-textures.md#thousands-of-sprites-spritebatch).

## Find every node with a tag

`engine.scene.index` is the scene's `NodeIndex`. Register nodes with `index.add(node, "enemy")`, then `index.findByTag("enemy")`. See [Camera and layers](./guide/camera-and-layers.md#finding-nodes-nodeindex).

## Do something after a delay

`await node.ticker.wait(2)` or `node.ticker.every(0.5, fn)`. The timer pauses with the node and is cancelled if the node is disposed. See [Tweens and transitions](./guide/tweens-and-transitions.md#waiting-and-timers).

---

URL: https://thicketscript.com/willow/reference/animation

# AnimationPlayer

Frame-by-frame sprite animation.

```ts
import { AnimationSequence, AnimationPlayer } from "willow";
```

## AnimationSequence

```ts
class AnimationSequence
```

Defines a named sequence of texture frames for sprite animation. Plays through `frames` at `fps` frames per second, optionally looping.

### AnimationSequence: constructors

```ts
new AnimationSequence(config?: any)
new AnimationSequence(name: string, frames: Array<TextureRegion>, fps?: float, loop?: boolean)
```

### AnimationSequence: properties

| Member | Description |
|---|---|
| `name: string` | Name of this animation sequence (e.g. "idle", "walk", "jump"). |
| `frames: Array<TextureRegion>` | Array of texture regions representing each frame in order. |
| `fps: float` | Playback speed in frames per second (default 10.0). |
| `loop: boolean` | When true, wraps back to frame 0 after the last frame; otherwise stops at the final frame. |

## AnimationPlayer

```ts
class AnimationPlayer
```

Manages playback of multiple named animation sequences on a node or sprite. Advances frames over time and updates the bound node's texture region accordingly.

Stepping rule: a player whose node is in the scene (added under `Scene.main.root`) is stepped by the scene's frame, so it needs no `update(dt)` call. A script that calls `update(dt)` itself keeps driving the player: once it has, the scene leaves that player alone and it is never advanced twice in a frame. A player whose node is not in the scene is stepped only by your own `update(dt)` calls.

### AnimationPlayer: constructors

```ts
new AnimationPlayer(node?: Node)
```

### AnimationPlayer: properties

| Member | Description |
|---|---|
| `readonly current: string` | Name of the currently active sequence, or empty string if none. |
| `readonly frame: int` | Zero-based index of the current frame within the active sequence. |
| `readonly isPlaying: boolean` | True while an animation sequence is actively playing. |

### AnimationPlayer: methods

| Member | Description |
|---|---|
| `addSequence(seq: AnimationSequence): void` | Registers a named animation sequence with this player. |
| `play(name: string): void` | Starts playing the named sequence from frame 0. No-op if already playing it. |
| `playFrom(name: string, frame: int): void` | Starts playing the named sequence from a specific frame index. |
| `stop(): void` | Pauses or stops playback at the current frame. |
| `seek(frame: int): void` | Seeks to a specific frame index in the current sequence without changing playing state. |
| `update(dt: float): void` | Advances animation time by `dt` seconds and updates the target node's texture region. Calling this yourself takes over stepping this player from the scene (see the stepping rule on the class). |
| `onComplete(callback: Function): void` | Registers a callback invoked when a non-looping animation reaches its final frame. |

---

URL: https://thicketscript.com/willow/reference/atlas

# Atlas

Named regions packed onto texture pages.

```ts
import { Atlas, PackerConfig, AtlasEntry } from "willow";
```

## Atlas

```ts
class Atlas
```

A named collection of texture regions. Built one of three ways:

, `Atlas.load` / `Atlas.loadIntoScene` parse an existing TexturePacker JSON manifest against an already-loaded page `Texture`.
, `Atlas.create` packs images in dynamically, one at a time, via `add`.
, `Atlas.createBatch` stages images upfront via `stage`, then packs them all at once via `pack` for tighter results.

### Atlas: methods

| Member | Description |
|---|---|
| `has(name: string): boolean` | True if a region named `name` has been packed/parsed into this atlas. |
| `region(name: string): TextureRegion` | The region named `name`, or a 1x1 magenta placeholder if missing. Raises on a batch atlas that has not been packed yet. |
| `add(name: string, width: int, height: int, rgba: Buffer \| Uint8Array): TextureRegion` | Packs `width` * `height` * 4 RGBA bytes into the atlas under `name` and returns its region. Dynamic atlases only (from `Atlas.create`) and requires an initialized renderer. It is therefore unavailable in a headless console program. |
| `stage(name: string, width: int, height: int, rgba: Buffer \| Uint8Array): void` | Buffers `width` * `height` * 4 RGBA bytes under `name` for later packing via `pack`. Batch atlases only (from `Atlas.createBatch`, before `pack` has run), raises otherwise, including on a duplicate name. |
| `pack(): void` | Packs every staged image (MaxRects). Batch atlases only, and only once, a second call raises. |
| `regionCount(): int` | Number of named regions currently packed/parsed into this atlas. |
| `dispose(): void` | Releases the atlas's packer/page state. Idempotent, like every other `dispose()`. |

### Atlas: static methods

| Member | Description |
|---|---|
| `static load(jsonText: string, texture: Texture): Atlas` | Parses a TexturePacker JSON manifest against an existing page `texture`. |
| `static loadIntoScene(jsonText: string, texture: Texture): Atlas` |  |
| `static create(config?: PackerConfig): Atlas` | Creates an empty atlas for dynamic packing via `add`. |
| `static createBatch(config?: PackerConfig): Atlas` | Creates an empty atlas for batch packing via `stage`/`pack`. |

## PackerConfig

```ts
class PackerConfig
```

Page-size and padding configuration for a dynamically-packed atlas. All three fields are optional; unset fields default the same way `Atlas.create`/`Atlas.createBatch` do without a config at all: 2048x2048 pages, 1 pixel padding.

### PackerConfig: constructors

```ts
new PackerConfig(pageWidth?: int, pageHeight?: int, padding?: int)
```

### PackerConfig: properties

| Member | Description |
|---|---|
| `pageWidth: int` | Atlas page width in pixels. Defaults to 2048 when unset. |
| `pageHeight: int` | Atlas page height in pixels. Defaults to 2048 when unset. |
| `padding: int` | Pixel gap between packed images. Defaults to 1 when unset. |

## AtlasEntry

```ts
class AtlasEntry
```

One baked font-atlas page: a style/size tag plus the raw PNG and JSON bytes TexturePacker-style tooling exchanges for it.

### AtlasEntry: constructors

```ts
new AtlasEntry(style: string, bakeSize: float, png: Buffer, json: Buffer)
```

### AtlasEntry: properties

| Member | Description |
|---|---|
| `style: string` | Font style this atlas page was baked for ("regular" \| "bold" \| "italic" \| "boldItalic"). |
| `bakeSize: float` | SDF/bitmap bake size, in pixels, this page was baked at. |
| `png: Buffer` | Raw PNG bytes for the atlas page image. |
| `json: Buffer` | Raw JSON bytes for the atlas page's glyph manifest. |

---

URL: https://thicketscript.com/willow/reference/cache-tree

# CacheTreeMode

Constants for `Node.setCacheAsTree`.

```ts
import { CacheTreeMode } from "willow";
```

## CacheTreeMode

```ts
class CacheTreeMode
```

Cache tree invalidation mode. Controls when a cached subtree is invalidated.

### CacheTreeMode: static properties

| Member | Description |
|---|---|
| `static readonly MANUAL: int` | Cache invalidates only on explicit `invalidateCache()` call. Zero overhead on setters. Best for large static tilemaps. |
| `static readonly AUTO: int` | Cache invalidates automatically when any field is written on the cached node or its descendants. Small overhead per setter call (one pointer chase + bool write). |

---

URL: https://thicketscript.com/willow/reference/camera

# Camera2D

The 2D camera.

```ts
import { Camera2D, CameraFollow } from "willow";
```

## Camera2D

```ts
class Camera2D
```

The engine's single live 2D view into the scene: position, zoom, rotation and viewport. Reached via `engine.camera`. Points and rectangles are the core `Vec2` and `Rect` structs, and animation curves are core `Ease` ids.

### Camera2D: properties

| Member | Description |
|---|---|
| `position: Vec2` | World-space centre of the view. `x` and `y` are the same state. |
| `x: float` | World-space X the camera centers on. Same state as `position.x`. |
| `y: float` | World-space Y the camera centers on. Same state as `position.y`. |
| `zoom: float` | Scale factor: 1.0 is no zoom, greater than 1 zooms in, less than 1 zooms out. |
| `rotation: float` | Camera rotation in radians, clockwise. |
| `cullEnabled: boolean` | When true, a node whose world bounds miss the camera's visible area is skipped for rendering. |
| `readonly viewport: Rect` | The screen-space rectangle this camera renders into, in pixels. |
| `bounds: Rect \| null` | The world-space rectangle the camera keeps its view inside, or `null` for none. Setting it clamps the camera at once and on every frame after. Raises a `RangeError` when `width` or `height` is not positive. |

### Camera2D: methods

| Member | Description |
|---|---|
| `follow(node: Node, options?: CameraFollow): void` | Tracks `node` every frame, easing toward it. See `CameraFollow`. Interrupts any in-flight `scrollTo`/`scrollToTile`, rejecting its promise. |
| `unfollow(): void` | Stops following the current target node. The camera holds its last position. |
| `scrollTo(target: Vec2, seconds: float, ease?: int): Promise<void>` | Animates the camera centre to `target` over `seconds` (0 = instant), returning a promise that resolves when the motion completes (or at once, for an instant move). `ease` is a core `Ease` constant (default `Ease.LINEAR`); an unknown id rejects the promise with a `RangeError`. Interrupts any in-flight `follow`/scroll, rejecting the superseded promise. Raises a `RangeError` if `seconds` is negative. |
| `scrollToTile(col: int, row: int, seconds: float, ease?: int, tileSize?: Size): Promise<void>` | Same as `scrollTo`, targeting the centre of tile `(col, row)`. `tileSize` defaults to 32x32 (willow's tilemap default). |
| `shake(trauma: float, decay?: float): void` | Applies a one-shot trauma-based shake: `trauma` (0..1) adds to the camera's accumulated trauma, and shake magnitude scales with trauma squared, so repeated hits accumulate naturally. `decay`, when given, sets the per-second trauma decay rate (default 1.0) for this and future shakes. |
| `resetShake(): void` | Immediately cancels any active shake/trauma and resets shake state. |
| `screenToWorld(p: Vec2): Vec2` | Converts a screen-space point to world space, accounting for the camera's position, zoom and rotation. |
| `worldToScreen(p: Vec2): Vec2` | Converts a world-space point to screen space, the inverse of `screenToWorld`. |
| `visibleBounds(): Rect` | The world-space rectangle the camera can currently see. |

## CameraFollow

```ts
class CameraFollow
```

Options for `Camera2D.follow`. `offset` shifts the tracked point in world space (default `Vec2{}`); `lerp` is the per-frame interpolation factor, where an omitted `lerp` snaps to the target and a lower value follows smoothly. Pass an object literal: `{ offset: Vec2{ x: 0.0, y: -40.0 }, lerp: 0.1 }`.

### CameraFollow: properties

| Member | Description |
|---|---|
| `offset?: Vec2` | World-space shift of the tracked point (default `Vec2{}`). |
| `lerp?: float` | Per-frame interpolation factor; omit to snap to the target. |

---

URL: https://thicketscript.com/willow/reference/custom-paint

# Custom paint

Draw your own triangles for a node.

```ts
import { Painter, TrianglesPaint } from "willow";
```

## Painter

```ts
class Painter
```

The view onto the render pipeline passed to a node's custom-paint function. Only valid while the function runs: using a stored Painter later raises `InvalidStateError`.

### Painter: properties

| Member | Description |
|---|---|
| `readonly node: Node` | The node whose custom-paint function is running. |

### Painter: methods

| Member | Description |
|---|---|
| `worldTransform(): Array<float>` | The node's world transform as six numbers `[a, b, c, d, tx, ty]`. A point `(x, y)` maps to `(a * x + c * y + tx, b * x + d * y + ty)`. The camera is applied after painting. |
| `isBuildingCache(): boolean` | True when this paint pass is building a cached subtree (`CacheAsTree`): skip transient or animated content that should not be folded into the cache. |
| `paintDefault(): void` | Draws the node's normal content (sprite, mesh, text, particles) so custom geometry can be added alongside it. Containers draw nothing. |
| `appendTriangles(triangles: TrianglesPaint): void` | Draws one batch of triangles. Vertices are copied; the arrays may be reused after. |

## TrianglesPaint

```ts
class TrianglesPaint
```

One batch of textured triangles for `Painter.appendTriangles`. Vertex positions are in world space: write them through `Painter.worldTransform()`.

### TrianglesPaint: constructors

```ts
new TrianglesPaint(vertices: Float32Array | Array<float>, indices: Array<int>)
```

Creates a batch from flat vertex data (eight numbers per vertex: x, y, u, v, r, g, b, a, colour channels 0.0 to 1.0) and a triangle list (three vertex indices per triangle).

### TrianglesPaint: properties

| Member | Description |
|---|---|
| `vertices: Float32Array \| Array<float>` | Flat vertex data, eight numbers per vertex in order: x, y, u, v, r, g, b, a. |
| `indices: Array<int>` | Triangle list: three vertex indices per triangle. |
| `texture?: Texture \| TextureRegion` | Image sampled by the triangles; omit to draw vertex colours only. |
| `blendMode?: string` | Blend mode name such as "normal" or "add" (same names as `Node.blendMode`). |
| `renderLayer: int` | Render layer, 0 to 255. Defaults to 0. |
| `globalOrder: int` | Secondary draw-order key within the render layer. Defaults to 0. |

---

URL: https://thicketscript.com/willow/reference/filters

# Filters

Visual effects applied to a node's rendered output.

```ts
import { Filter, DrawFilter, BlurFilter, ColorMatrixFilter, OutlineFilter, PixelPerfectOutlineFilter, PixelPerfectInlineFilter, PaletteFilter, CustomShaderFilter, CustomDrawShaderFilter } from "willow";
```

## Filter

```ts
class Filter
```

Base class for visual effects applied to a node's rendered output.

### Filter: properties

| Member | Description |
|---|---|
| `readonly padding: int` | Extra padding pixels this filter needs around the node's bounds. Defaults to 0. |

## DrawFilter

```ts
class DrawFilter extends Filter
```

Extends [Filter](./filters.md#filter).

Base class for per-pixel filters that can be applied at draw time without an offscreen render target.

## BlurFilter

```ts
class BlurFilter extends Filter
```

Extends [Filter](./filters.md#filter).

Separable gaussian-approximating blur filter.

### BlurFilter: constructors

```ts
new BlurFilter(radius?: int)
```

Creates a new blur filter with the given radius (in pixels).

### BlurFilter: properties

| Member | Description |
|---|---|
| `radius: int` | Blur radius in pixels. Non-negative. |

### BlurFilter: static methods

| Member | Description |
|---|---|
| `static create(radius?: int): BlurFilter` | Creates a new blur filter with the given radius (in pixels). |

## ColorMatrixFilter

```ts
class ColorMatrixFilter extends DrawFilter
```

Extends [DrawFilter](./filters.md#drawfilter).

4x5 color matrix transformation filter.

### ColorMatrixFilter: constructors

```ts
new ColorMatrixFilter()
```

Creates a new color matrix filter initialized to the identity transform.

### ColorMatrixFilter: methods

| Member | Description |
|---|---|
| `setIdentity(): ColorMatrixFilter` | Resets the matrix to the identity transform. |
| `setGrayscale(): ColorMatrixFilter` | Sets full grayscale transformation (equivalent to setting saturation to 0). |
| `setInvert(): ColorMatrixFilter` | Inverts the RGB color channels. |
| `setBrightness(b: float): ColorMatrixFilter` | Adjusts brightness by offset in [-1.0, 1.0]. |
| `setContrast(c: float): ColorMatrixFilter` | Adjusts contrast: 1.0 is normal, 0.0 is gray, >1.0 is higher contrast. |
| `setSaturation(s: float): ColorMatrixFilter` | Adjusts saturation: 1.0 is normal, 0.0 is grayscale. |
| `setHueRotation(radians: float): ColorMatrixFilter` | Rotates hue by the given angle in radians. |

## OutlineFilter

```ts
class OutlineFilter extends Filter
```

Extends [Filter](./filters.md#filter).

Multi-pixel outline filter via offset sampling.

### OutlineFilter: constructors

```ts
new OutlineFilter(thickness: int, color: Color)
```

Creates a new outline filter with the given thickness and tint colour.

### OutlineFilter: properties

| Member | Description |
|---|---|
| `thickness: int` | Outline thickness in pixels. |
| `color: Color` | Outline tint colour. |

### OutlineFilter: static methods

| Member | Description |
|---|---|
| `static create(thickness: int, color: Color): OutlineFilter` | Creates a new outline filter with the given thickness and tint colour. |

## PixelPerfectOutlineFilter

```ts
class PixelPerfectOutlineFilter extends DrawFilter
```

Extends [DrawFilter](./filters.md#drawfilter).

1-pixel cardinal neighbor outline filter.

### PixelPerfectOutlineFilter: constructors

```ts
new PixelPerfectOutlineFilter(color: Color)
```

Creates a new pixel-perfect outline filter with the given tint colour.

### PixelPerfectOutlineFilter: properties

| Member | Description |
|---|---|
| `color: Color` | Outline tint colour. |

### PixelPerfectOutlineFilter: static methods

| Member | Description |
|---|---|
| `static create(color: Color): PixelPerfectOutlineFilter` | Creates a new pixel-perfect outline filter with the given tint colour. |

## PixelPerfectInlineFilter

```ts
class PixelPerfectInlineFilter extends DrawFilter
```

Extends [DrawFilter](./filters.md#drawfilter).

1-pixel edge recoloring filter for pixels bordering transparent areas.

### PixelPerfectInlineFilter: constructors

```ts
new PixelPerfectInlineFilter(color: Color)
```

Creates a new pixel-perfect inline filter with the given colour.

### PixelPerfectInlineFilter: properties

| Member | Description |
|---|---|
| `color: Color` | Inset border colour. |

### PixelPerfectInlineFilter: static methods

| Member | Description |
|---|---|
| `static create(color: Color): PixelPerfectInlineFilter` | Creates a new pixel-perfect inline filter with the given colour. |

## PaletteFilter

```ts
class PaletteFilter extends DrawFilter
```

Extends [DrawFilter](./filters.md#drawfilter).

Luminance-based palette remapping filter.

### PaletteFilter: constructors

```ts
new PaletteFilter()
```

Creates a new palette filter initialized with a grayscale palette.

### PaletteFilter: properties

| Member | Description |
|---|---|
| `cycleOffset: float` | Cycle offset for animated palette shifting. |

### PaletteFilter: methods

| Member | Description |
|---|---|
| `setPalette(colors: Color[]): void` | Sets the 256-entry palette colors. |

## CustomShaderFilter

```ts
class CustomShaderFilter extends Filter
```

Extends [Filter](./filters.md#filter).

Spatial filter driven by a user-provided prebuilt shader. The shader is a bgfx fragment binary built ahead of time with shaderc; there is no runtime shader compiler. The source image is sampler 0; named uniforms land in `u_params1`, sorted by name, each on a vec4 boundary.

### CustomShaderFilter: constructors

```ts
new CustomShaderFilter(shaderPath: string, padding?: int)
```

Loads `<shaderPath>.<backend>.bin` (spirv, glsl, essl, metal or dxbc, matching the running renderer) from the project assets. Raises an AssetError when the file is missing, is not a bgfx fragment shader, or was built for another backend.

### CustomShaderFilter: methods

| Member | Description |
|---|---|
| `setUniform(name: string, value: float \| float[]): CustomShaderFilter` | Sets a named uniform to a float or an array of floats; returns this filter. |

### CustomShaderFilter: static methods

| Member | Description |
|---|---|
| `static create(shaderPath: string, padding?: int): CustomShaderFilter` | Same as the constructor. |

## CustomDrawShaderFilter

```ts
class CustomDrawShaderFilter extends DrawFilter
```

Extends [DrawFilter](./filters.md#drawfilter).

Per-pixel filter driven by a user-provided prebuilt shader. Same shader format and uniform packing as `CustomShaderFilter`; the shader must not read neighbouring pixels.

### CustomDrawShaderFilter: constructors

```ts
new CustomDrawShaderFilter(shaderPath: string)
```

Loads `<shaderPath>.<backend>.bin` from the project assets. Raises an AssetError when the file is missing, is not a bgfx fragment shader, or was built for another backend.

### CustomDrawShaderFilter: methods

| Member | Description |
|---|---|
| `setUniform(name: string, value: float \| float[]): CustomDrawShaderFilter` | Sets a named uniform to a float or an array of floats; returns this filter. |

### CustomDrawShaderFilter: static methods

| Member | Description |
|---|---|
| `static create(shaderPath: string): CustomDrawShaderFilter` | Same as the constructor. |

---

URL: https://thicketscript.com/willow/reference/font

# Font

Fonts: bundles, TTF baking, pixel fonts and measuring.

```ts
import { Font, FontTtfConfig, FontBakeOptions, FontMeasureStyle, FontMeasureResult } from "willow";
```

## Font

```ts
class Font
```

Font handle backed by a willow::FontFamily. Constructed via the static factories (`Font.load`, `Font.system`, `Font.fromBuffer`). Direct `new Font(...)` raises a TypeError.

### Font: properties

| Member | Description |
|---|---|
| `readonly name: string` | Family name reported by the bundle. |

### Font: methods

| Member | Description |
|---|---|
| `dispose(): void` | Releases this font handle. Destroying the handle returned by `Font.system()` does NOT free willow's bundled default family. Only this wrapper retires. Idempotent and silent, like every other `dispose()`. The one method this class carries, `renderCount()`, raises `"InvalidStateError: Font.renderCount: font has been disposed"` afterwards. The `name` field also raises `InvalidStateError` once disposed. |
| `renderCount(): float` | Returns the cumulative number of glyph renders this font has performed. `float`, not `int`: the underlying counter never resets and would silently wrap an `int32` after roughly 2.1 billion glyphs. Counts glyphs actually emitted by the render pipeline (once per frame a Text node using this font is on-screen and not served from a CacheAsTree replay) — not distinct glyphs, and not frames where the node was cached. |
| `measure(text: string, size: float, style?: FontMeasureStyle): FontMeasureResult` | Measures text directly without creating a scene node. |
| `lineHeight(size: float, style?: FontMeasureStyle): float` | Returns willow's native line height for a display size and face style. |

### Font: static methods

| Member | Description |
|---|---|
| `static load(path: string): Font` | Loads a font bundle from `path` (resolved via the engine asset roots). |
| `static fromBuffer(buffer: Buffer): Font` | Loads a font bundle from an in-memory byte buffer. |
| `static fromPixelFont(texture: Texture \| string, cellWidth: int, cellHeight: int, chars: string): Font` | Wraps a pixel font spritesheet into a Font. `cellWidth` and `cellHeight` specify the fixed cell size in the texture. `chars` maps cells in row-major order to characters. |
| `static fromTTF(buffer: Buffer, config?: FontTtfConfig): Font` | Bakes a TTF/OTF buffer at load time. No baking occurs per frame. |
| `static loadTTF(path: string, config?: FontTtfConfig): Font` | Loads and bakes a project-root-confined TTF/OTF file at load time. |
| `static loadTTFCached(ttf: string \| Buffer, cacheDir: string, options?: FontBakeOptions): Font` | Synchronously loads a TTF/OTF (a project-root-confined path or a Buffer) through an on-disk bake cache. The first call bakes and writes `<cacheDir>/<key>.fontbundle` (atomically); later calls with the same font bytes and options load that file without baking. An empty or unwritable `cacheDir` bakes in memory. |
| `static cachedBakeCount(): float` | Number of bakes `Font.loadTTFCached` has performed in this process; cache hits do not count. |
| `static system(name?: string): Font` | Returns a handle to willow's bundled default font. The optional `name` argument is accepted for signature compatibility and ignored. |

## FontTtfConfig

```ts
class FontTtfConfig
```

Runtime TTF/OTF baking options. Baking happens once while loading.

### FontTtfConfig: properties

| Member | Description |
|---|---|
| `sizes?: Array<float>` | Point sizes to bake ahead of time. Unset uses the font family's default size set. |
| `sdfSpread?: float` | SDF spread in pixels for the baked distance field. Unset uses the baker's default. |
| `atlasWidth?: int` | Baked atlas page width in pixels. Unset uses the baker's default. |
| `atlasHeight?: int` | Baked atlas page height in pixels. Unset uses the baker's default. |
| `chars?: string` | Character set to bake glyphs for. Unset bakes the baker's default set. |

## FontBakeOptions

```ts
class FontBakeOptions
```

Options for `Font.loadTTFCached`; they map one to one onto the font baker's options and are part of the cache key.

### FontBakeOptions: properties

| Member | Description |
|---|---|
| `sizes?: Array<float>` | Em sizes in pixels to bake. Unset bakes 64 and 256. |
| `distanceRange?: float` | SDF distance range in pixels for every size. Unset or 0 uses size / 8. |
| `atlasWidth?: int` | Atlas page width in pixels. Unset bakes 1024. |
| `charset?: string` | Characters to bake: ascii, latin, full, U+hhhh-hhhh ranges joined by commas, or literal characters. Unset bakes ASCII. |
| `effectSize?: float` | Em size of the extra effects entry for outline, glow and shadow. Unset or 0 bakes none. |
| `effectRange?: float` | Distance range of the effects entry. Unset or 0 uses effectSize / 2. |

## FontMeasureStyle

```ts
class FontMeasureStyle
```

Optional face selection for direct font measurement.

### FontMeasureStyle: properties

| Member | Description |
|---|---|
| `bold?: boolean` | Measure using the bold face, when available. |
| `italic?: boolean` | Measure using the italic face, when available. |

## FontMeasureResult

```ts
class FontMeasureResult
```

Dimensions returned by direct font measurement.

### FontMeasureResult: properties

| Member | Description |
|---|---|
| `readonly width: float` | Measured width in pixels. |
| `readonly height: float` | Measured height in pixels. |

---

URL: https://thicketscript.com/willow/reference/

# Reference

Every class, enum and function willow gives your scripts, grouped by area. Generated from willow's own type declarations, so it matches what `thicket check` sees.

| Page | What is on it | Classes |
|---|---|---|
| [Node](./node.md) | The base of every display object: transform, children, lifecycle hooks, input handlers and events. | `Node`, `Event`, `Align`, `PauseMode` |
| [Scene](./scene.md) | The app's scene: its world root, screen root, camera, layers, keys and transitions. Module `willow-scene`, read without an import. | `Scene`, `KeyEvent` |
| [Sprite and SpriteBatch](./sprite.md) | Textured display objects. | `Sprite`, `SpriteBatch` |
| [Texture and TextureRegion](./texture.md) | Images on the GPU and rectangles inside them. | `Texture`, `TextureRegion` |
| [Atlas](./atlas.md) | Named regions packed onto texture pages. | `Atlas`, `PackerConfig`, `AtlasEntry` |
| [AnimationPlayer](./animation.md) | Frame-by-frame sprite animation. | `AnimationSequence`, `AnimationPlayer` |
| [Text](./text.md) | The text display object and its effects and input events. | `Text`, `TextEffects`, `TextFieldType`, `TextInputEvent`, `TextCompositionEvent` |
| [Font](./font.md) | Fonts: bundles, TTF baking, pixel fonts and measuring. | `Font`, `FontTtfConfig`, `FontBakeOptions`, `FontMeasureStyle`, `FontMeasureResult` |
| [Quad](./quad.md) | Solid-colour rectangles and lines. | `Quad` |
| [Polygon and Mesh](./polygon-mesh.md) | Filled shapes and raw triangle meshes. | `Polygon`, `Mesh` |
| [Custom paint](./custom-paint.md) | Draw your own triangles for a node. | `Painter`, `TrianglesPaint` |
| [Pointer input](./input.md) | Event payloads and pointer controls used by the node input handlers. | `PointerEvent`, `DragEvent`, `WheelEvent`, `PinchContext`, `KeyModifiers`, `Pointer` |
| [NodeIndex](./node-index.md) | Find nodes by name or tag. | `NodeIndex` |
| [Camera2D](./camera.md) | The 2D camera. | `Camera2D`, `CameraFollow` |
| [TileLayer](./tilemap.md) | Batched, culled tile grids. | `TileLayer`, `TilemapViewport`, `TileQuery`, `GidInfo` |
| [TweenGroup](./tween.md) | Animate node fields and plain numbers over time. | `TweenGroup`, `TweenConfig` |
| [Transition](./transition.md) | Effects played between two nodes by `Scene.playTransition`. | `Transition`, `TransitionCanvas` |
| [ParticleEmitter](./particles.md) | Pooled 2D particles. | `ParticleEmitter`, `EmitterConfig`, `Range` |
| [LightLayer](./lighting.md) | 2D lights over ambient darkness. | `LightLayer`, `Light` |
| [Filters](./filters.md) | Visual effects applied to a node's rendered output. | `Filter`, `DrawFilter`, `BlurFilter`, `ColorMatrixFilter`, `OutlineFilter`, `PixelPerfectOutlineFilter`, `PixelPerfectInlineFilter`, `PaletteFilter`, `CustomShaderFilter`, `CustomDrawShaderFilter` |
| [RenderTexture](./render-texture.md) | Offscreen canvases and subtree capture. | `RenderTexture`, `RenderTextureDrawOpts`, `ToTexture`, `FXAAConfig` |
| [Rope and DistortionGrid](./rope.md) | Ribbons along a path, and deformable grid meshes. | `Rope`, `RopeConfig`, `RopeJoinMode`, `RopeCurveMode`, `DistortionGrid` |
| [Physics](./physics.md) | Rigid bodies attached to nodes. | `PhysicsConfig`, `PhysicsBody`, `PhysicsBodyDef`, `PhysicsDynamic`, `PhysicsStatic`, `PhysicsKinematic`, `PhysicsShape`, `PhysicsCircle`, `PhysicsBox`, `PhysicsSegment`, `PhysicsPolygon`, `PhysicsBodyKind`, `PhysicsShapeKind` |
| [CacheTreeMode](./cache-tree.md) | Constants for `Node.setCacheAsTree`. | `CacheTreeMode` |

---

URL: https://thicketscript.com/willow/reference/input

# Pointer input

Event payloads and pointer controls used by the node input handlers.

```ts
import { PointerEvent, DragEvent, WheelEvent, PinchContext, KeyModifiers, Pointer } from "willow";
```

## PointerEvent

```ts
class PointerEvent
```

Payload handed to a node's pointer callbacks (`onPointerDown`, `onPointerUp`, `onClick`). `x`/`y` are in the node's local space; `worldX`/`worldY` are scene-world coordinates; `button` is the mouse button index (0 = left, 1 = right, 2 = middle); `modifiers` is a `KeyModifiers` bitmask of the keyboard modifier keys held during the event (e.g. `(e.modifiers & KeyModifiers.SHIFT) !== 0`); `target` is the Node the pointer hit.

### PointerEvent: properties

| Member | Description |
|---|---|
| `x: float` | Pointer X in the hit node's local space. |
| `y: float` | Pointer Y in the hit node's local space. |
| `worldX: float` | Pointer X in scene-world coordinates. |
| `worldY: float` | Pointer Y in scene-world coordinates. |
| `screenX: float` | Pointer X in logical screen pixels, before the camera. |
| `screenY: float` | Pointer Y in logical screen pixels, before the camera. |
| `button: int` | Mouse button index: 0 = left, 1 = right, 2 = middle. |
| `modifiers: int` | `KeyModifiers` bitmask of the keyboard modifier keys held during the event. |
| `target: Node` | The Node the pointer hit. |

## DragEvent

```ts
class DragEvent
```

Pointer drag payload. Coordinates and deltas mirror willow::DragContext. `modifiers` is a `KeyModifiers` bitmask of the keyboard modifier keys held during the drag.

### DragEvent: properties

| Member | Description |
|---|---|
| `x: float` | Pointer X in the target node's local space. |
| `y: float` | Pointer Y in the target node's local space. |
| `worldX: float` | Pointer X in scene-world coordinates. |
| `worldY: float` | Pointer Y in scene-world coordinates. |
| `startX: float` | World-space X where this drag began. |
| `startY: float` | World-space Y where this drag began. |
| `deltaX: float` | World-space X delta since the drag began. |
| `deltaY: float` | World-space Y delta since the drag began. |
| `screenDeltaX: float` | Screen-space X delta since the drag began. |
| `screenDeltaY: float` | Screen-space Y delta since the drag began. |
| `pointerId: int` | Platform pointer/touch id, for disambiguating multiple simultaneous drags. |
| `modifiers: int` | `KeyModifiers` bitmask of the keyboard modifier keys held during the drag. |
| `target: Node` | The Node this drag started on. |

## WheelEvent

```ts
class WheelEvent
```

Mouse wheel / trackpad scroll payload, handed to `Node.onWheel`.

### WheelEvent: properties

| Member | Description |
|---|---|
| `x: float` | Pointer X in the target node's local space. |
| `y: float` | Pointer Y in the target node's local space. |
| `worldX: float` | Pointer X in scene-world coordinates (after the camera). |
| `worldY: float` | Pointer Y in scene-world coordinates (after the camera). |
| `screenX: float` | Pointer X in logical screen pixels, before the camera. |
| `screenY: float` | Pointer Y in logical screen pixels, before the camera. |
| `deltaX: float` | Horizontal scroll for the frame. |
| `deltaY: float` | Vertical scroll for the frame. |
| `modifiers: int` | `KeyModifiers` bitmask of the keyboard modifier keys held during the scroll. |
| `target: Node` | The Node whose `onWheel` handled this event. |

## PinchContext

```ts
class PinchContext
```

Two-finger pinch/rotate gesture payload, handed to `Node.onPinch`. `centerX`/`centerY` are the midpoint between the two touch points in world coordinates. `scale`/`rotation` are CUMULATIVE since the gesture began, not a per-frame delta: `scale` is 1.0 and `rotation` is 0 at gesture start, and both track the pinch's total change since then. No `target` field, a pinch has no single hit node the way click/drag do.

### PinchContext: properties

| Member | Description |
|---|---|
| `centerX: float` | Midpoint X between the two touch points, in world coordinates. |
| `centerY: float` | Midpoint Y between the two touch points, in world coordinates. |
| `scale: float` | Cumulative scale factor since the gesture began. 1.0 at gesture start. |
| `rotation: float` | Cumulative rotation in radians since the gesture began. 0 at gesture start. |

## KeyModifiers

```ts
class KeyModifiers
```

Keyboard modifier-key bitmask constants. Carried on `PointerEvent.modifiers` / `DragEvent.modifiers`.

### KeyModifiers: static properties

| Member | Description |
|---|---|
| `static readonly SHIFT: int` | Shift key bit. |
| `static readonly CTRL: int` | Ctrl key bit. |
| `static readonly ALT: int` | Alt key bit. |
| `static readonly META: int` | Meta/Cmd/Windows key bit. |

## Pointer

```ts
class Pointer
```

Module-level pointer capture and drag-threshold controls.

### Pointer: static methods

| Member | Description |
|---|---|
| `static capture(node: Node, pointerId?: int): void` | Routes every subsequent pointer event for `pointerId` (default: the primary pointer) to `node` regardless of hit-testing, until `release` is called. Used to keep a drag on its originating node even after the pointer leaves its bounds. |
| `static release(pointerId?: int): void` | Releases a capture previously set by `capture`, restoring normal hit-testing. |
| `static setDragDeadZone(px: float): void` | Sets the minimum pointer movement, in pixels, before a press is treated as a drag rather than a click. |
| `static dragDeadZone(): float` | The current drag dead-zone in pixels. See `setDragDeadZone`. |

---

URL: https://thicketscript.com/willow/reference/lighting

# LightLayer

2D lights over ambient darkness.

```ts
import { LightLayer, Light } from "willow";
```

## LightLayer

```ts
class LightLayer extends Node
```

Extends [Node](./node.md#node).

2D lighting overlay layer using erase blending over ambient darkness. A LightLayer is a node: add it to the tree like any other (`stage.add(lights)`). What is drawn before it in the tree is darkened; what is added after it, such as a UI, stays unlit.

### LightLayer: constructors

```ts
new LightLayer(ambientDarkness?: float)
```

Constructs a new light layer with optional ambient darkness.

### LightLayer: properties

| Member | Description |
|---|---|
| `ambient: Color` | Ambient darkness tint color. Defaults to semi-transparent black. |
| `ambientDarkness: float` | Darkness strength in [0.0, 1.0]: 0.0 is unlit, 1.0 is full darkness. |
| `ambientAlpha: float` | Alias for ambientDarkness. |
| `readonly lightCount: int` | Number of active lights currently registered in the layer. |

### LightLayer: methods

| Member | Description |
|---|---|
| `setAmbient(ambient: Color): void` | Sets the ambient color the unlit scene is tinted toward. |
| `setAmbientDarkness(darkness: float): void` | Convenience setting pure-black ambient with the given darkness in [0, 1]. |
| `setAmbientAlpha(alpha: float): void` | Alias for setAmbientDarkness. |
| `addLight(light: Light): int` | Adds a light source to the layer and returns its assigned ID. |
| `removeLight(id: int): void` | Removes a light by its assigned ID or Light reference. |
| `hasLight(id: int): boolean` | Returns true if a light with the given ID is active in the layer. |
| `clearLights(): void` | Removes all light sources from the layer. |
| `update(): void` | Updates target-following light positions. |
| `redraw(): void` | Re-evaluates light transforms and updates the layer. |

### LightLayer: static methods

| Member | Description |
|---|---|
| `static create(ambientDarkness?: float): LightLayer` | Factory creating a light layer. |

## Light

```ts
class Light
```

Point or textured light source placed in a `LightLayer`.

### Light: constructors

```ts
new Light(x?: float, y?: float, radius?: float, color?: Color, intensity?: float)
```

Constructs a new light with optional parameters.

### Light: properties

| Member | Description |
|---|---|
| `x: float` | Light center position X in layer pixels. Defaults to 0.0. |
| `y: float` | Light center position Y in layer pixels. Defaults to 0.0. |
| `radius: float` | Light radius in pixels. Defaults to 100.0. |
| `rotation: float` | Rotation in radians for textured light sources. Defaults to 0.0. |
| `intensity: float` | Light intensity in [0.0, 1.0]. Defaults to 1.0. |
| `enabled: boolean` | Whether the light is enabled and contributes to the layer. Defaults to true. |
| `color: Color` | Tint color of the light source. Defaults to white. |
| `target?: Node` | Target node whose world position this light tracks. Null if untracked. |
| `offsetX: float` | Horizontal offset applied after tracking target position. Defaults to 0.0. |
| `offsetY: float` | Vertical offset applied after tracking target position. Defaults to 0.0. |

### Light: methods

| Member | Description |
|---|---|
| `attachTo(target: Node, offsetX?: float, offsetY?: float): void` | Tracks target node in world space with optional pixel offset. |
| `detach(): void` | Stops tracking target node, leaving the light at its current position. |

---

URL: https://thicketscript.com/willow/reference/node-index

# NodeIndex

Find nodes by name or tag.

```ts
import { NodeIndex } from "willow";
```

## NodeIndex

```ts
class NodeIndex
```

Opt-in registry for looking up nodes by name or tag. Supports SQL LIKE-style `%` wildcards, multi-tag intersection queries, and automatic cleanup when a node is disposed.

### NodeIndex: constructors

```ts
new NodeIndex()
```

### NodeIndex: methods

| Member | Description |
|---|---|
| `add(node: Node, ...tags: Array<string>): void` | Registers a node in the index, optionally with initial tags. |
| `remove(node: Node, ...tags: Array<string>): void` | Removes tags from a node; if no tags are provided, unregisters the node entirely. |
| `tag(node: Node, tag: string): void` | Adds a single tag to a node. |
| `untag(node: Node, tag: string): void` | Removes a single tag from a node. Safe to call if the node does not have this tag. |
| `findByName(pattern: string): Node \| null` | Returns the first registered node matching the name pattern (supports `%` wildcards), or null if not found. |
| `findAllByName(pattern: string): Array<Node>` | Returns all registered nodes matching the name pattern (supports `%` wildcards). |
| `findByTag(pattern: string): Array<Node>` | Returns all nodes matching the given tag pattern (supports `%` wildcards). |
| `findByTags(...tags: Array<string>): Array<Node>` | Returns all nodes that have every one of the given tags (AND query). |
| `countByTag(tag: string): int` | Returns the number of nodes with the given tag without allocating an array. |
| `each(fn: Function): void` | Iterates all registered nodes. Callback can return false to stop early. |
| `eachByTag(tag: string, fn: Function): void` | Iterates all nodes with the given tag. Callback can return false to stop early. |
| `clear(): void` | Removes all nodes and tags from the index. |
| `clearNode(node: Node): void` | Removes all entries (name and tags) for a specific node. |

---

URL: https://thicketscript.com/willow/reference/node

# Node

The base of every display object: transform, children, lifecycle hooks, input handlers and events.

```ts
import { Node, Event, Align, PauseMode } from "willow";
```

## Node

```ts
class Node
```

Scene-graph base. Every visual is a Node. Nodes carry position plus visibility, can own children, and can be removed from their parent or disposed. Lifecycle hooks (`onReady`, `onUpdate`, `onEnter`, `onExit`) are assignable callable slots.

### Node: constructors

```ts
new Node(name?: string)
```

Creates an invisible grouping node with no visual representation of its own. `name` is optional and purely for debugging/creation-site tooling. A plain `new Node()` is the building block every scene root and container is made from.

### Node: properties

| Member | Description |
|---|---|
| `filters: Filter[]` | List of visual filters applied to this node's rendered output. |
| `alpha: float` | Per-node opacity multiplier in 0.0..1.0. Composes with parent alpha. |
| `interactable: boolean` | Pointer-input enable switch. Defaults to `true`. Writing `false` takes the node out of hit-testing even while a pointer handler is assigned; writing `true` restores the handler-driven behaviour. It never makes a handler-less node hit-testable: a node still participates only while it has a pointer handler assigned. |
| `name: string` | Debug / lookup name. Seeded from the constructor argument (empty when omitted); assigning a non-string raises a `TypeError`. |
| `userData: any` | Free-form value the script attaches to this node. `undefined` until assigned. The runtime never reads it. |
| `blendMode: string` | Compositor blend mode. One of `"normal"` \| `"add"` \| `"multiply"` \| `"screen"` \| `"erase"` \| `"mask"` \| `"below"` \| `"none"`. `"add"` brightens (additive particle FX); `"mask"` clips against this node's alpha. An unknown string raises a typed VM error. Defaults to `"normal"`. |
| `globalOrder: int` | Secondary render-sort key (default 0). Breaks ties *within* the same `renderLayer`: among nodes on one layer, a higher `globalOrder` draws on top, independent of tree/insertion order. `renderLayer` still dominates it. A plain settable int. |
| `renderLayer: int` | Primary render-sort key in `[0, 255]`. A higher `renderLayer` draws on top of a lower one regardless of scene-tree position, the mechanism for UI-over-world or additive-FX-over-everything. Reserved conventional values live on `engine.scene` (`LAYER_BACKGROUND`, `LAYER_DEFAULT`, `LAYER_UI`, `LAYER_OVERLAY`). A value outside `[0, 255]` raises a typed VM error. Defaults to 0. A node with no layer of its own draws on its nearest ancestor's layer, so a subtree (including children added later) follows the layer set on its root. Reading returns that effective layer; writing makes the layer explicit for the node and its unset descendants; `clearRenderLayer()` goes back to inheriting. |
| `paused: boolean` | Stops this subtree's `onTick`, `onUpdate`, `onLateUpdate`, ticker and tweens while true. A detached node is not walked at all, so reattaching resumes it. Default `false`. |
| `pauseMode: PauseMode` | How this node treats a pause above it: a `PauseMode` constant. `INHERIT` (default) follows its parent, `ALWAYS` keeps running (a pause menu inside the paused tree), `WHEN_PAUSED` runs only while an ancestor is paused, `DISABLED` never runs. |
| `timeScale: float` | Scales this subtree's time (default 1): `onTick` runs `floor(accumulator)` times per app tick, `dt` for `onUpdate` and `onLateUpdate` is multiplied, and the node ticker follows the tick count. Must be >= 0. |
| `unscaled: boolean` | When true this subtree ignores `App.timeScale` and its ancestors' `timeScale`. Default `false`. |
| `interpolate: boolean` | When true the renderer draws `x`, `y`, `rotation`, `scaleX` and `scaleY` between their values at the last two ticks, using `App.tickAlpha`: move the node in `onTick` and it still looks smooth at a frame rate above `App.tps`. Only the drawing is blended; `x` and the other fields always read the logical value. Call `resetInterpolation()` after a teleport, or the node slides across the screen for one tick. Default `false`. |
| `readonly ticker: Ticker` | The node's own `Ticker`, made on first read. It ticks with the node, pauses and scales with it, and disposing the node rejects its pending waits with `Cancelled`. |
| `readonly parent: Node` | This node's parent in the scene graph. `undefined` while detached. |
| `pivotX: float` | Pivot x in local pixel space. The rotation/scale anchor. (0, 0) leaves rotation around the top-left. Centring (e.g. `setAnchor(0.5, 0.5)` or `setPivot(w/2, h/2)`) makes a node spin in place. |
| `pivotY: float` | Pivot y in local pixel space. See `pivotX`. |
| `rotation: float` | Local rotation in radians. |
| `scaleX: float` | Local x scale factor. 1.0 is the authored size. |
| `scaleY: float` | Local y scale factor. 1.0 is the authored size. |
| `skewX: float` | Local x skew in radians. |
| `skewY: float` | Local y skew in radians. |
| `visible: boolean` | Whether this node (and its subtree) renders. |
| `x: float` | Local x position in parent space. |
| `y: float` | Local y position in parent space. |
| `zOrder: int` | Render order within the parent. Higher draws on top. |

### Node: callbacks

| Member | Description |
|---|---|
| `onPointerMove: Function` | Fires for pointer movement over this node. |
| `onPointerEnter: Function` | Fires directly when the pointer enters this node. Enter and leave do not bubble. A transition fires leave on the old node before enter on the new node. |
| `onPointerLeave: Function` | Fires directly when the pointer leaves this node. |
| `onDragStart: Function` | Fires once movement crosses the configured drag dead zone. |
| `onDrag: Function` | Fires for movement after a drag has started. |
| `onDragEnd: Function` | Fires when an active drag ends. |
| `onPinch: Function` | Fires during a two-finger pinch/rotate gesture over this node. Registering this ALSO makes the node participate in hit-testing, same as `onPointerDown` et al. Called as `onPinch(e: PinchContext): void`. |
| `onWheel: Function` | Fires when the mouse wheel or trackpad scrolls while the pointer is over this node (or over a descendant with no `onWheel` of its own). Registering this makes the node participate in hit-testing. Called as `onWheel(e: WheelEvent): void`. |
| `onEnter: Function` | Fires when the node is added to a parent. Assign `null` to detach. Called as `onEnter(): void`. |
| `onExit: Function` | Fires when the node is removed from its parent. Assign `null` to detach. Called as `onExit(): void`. |
| `onReady: Function` | Fires once on the first frame this node is in the tree. Assign `null` to detach. Called as `onReady(): void`. |
| `onUpdate: Function` | Fires every frame after `onReady`. Assign `null` to detach. Called as `onUpdate(dt: float): void` where `dt` is the frame-time in seconds. |
| `onTick: Function` | Fires once per logic tick (`App.tps` per second), in the tick phase before the frame, parent before children. Visibility does not stop it; `paused` and a detached node do. Assign `null` to detach. A hook that throws is reported once and disabled. Called as `onTick(): void`. |
| `onLateUpdate: Function` | Fires every frame after the whole tree's `onUpdate` and the tweens (cameras and followers). Assign `null` to detach. Called as `onLateUpdate(dt: float): void`. |
| `onPointerDown: Function` | Fires when a pointer is pressed over this node. Assign `null` to detach. A node participates in hit-testing only while it has a pointer handler assigned. Called as `onPointerDown(e: PointerEvent): void`. |
| `onPointerUp: Function` | Fires when a pointer is released over this node. Assign `null` to detach. Called as `onPointerUp(e: PointerEvent): void`. |
| `onClick: Function` | Fires when a press and release both land on this node. Assign `null` to detach. Called as `onClick(e: PointerEvent): void`. |

### Node: methods

| Member | Description |
|---|---|
| `setMask(mask: Node \| null): void` | Clips this node's rendered subtree to `mask`. The mask's own transform is ignored by the renderer. Child transforms still apply. Masks do not affect hit testing. Passing null clears it. |
| `clearMask(): void` | Clears the subtree mask, if any. |
| `getMask(): Node \| null` | Returns the current subtree mask, or null when none is set. |
| `addFilter(filter: Filter): void` | Appends a filter to this node's filter chain. |
| `removeFilter(filter: Filter): void` | Removes a filter from this node's filter chain. |
| `clearFilters(): void` | Removes all filters from this node. |
| `getFilters(): Filter[]` | Returns this node's active filter chain. |
| `setFilters(filters: Filter[]): void` | Replaces this node's filter chain with the given array of filters. |
| `setCustomPaint(paint: ((painter: Painter) => void) \| null): void` | Installs a function that draws this node itself each frame, instead of its normal content. The function receives a `Painter`; call `painter.paintDefault()` to keep the normal content. Passing null removes it. |
| `enablePhysics(config: PhysicsConfig): void` | Turns this node into a physics root with its own isolated world. Nodes below it get bodies with `setBody`; the scene steps the world each logic tick. Raises if an ancestor or a descendant is already a physics root. |
| `disablePhysics(): void` | Tears this physics root down: every body below it is removed. |
| `isPhysicsRoot(): boolean` | True when this node is a physics root. |
| `setBody(definition: PhysicsBodyDef): void` | Attaches a body at this node's current position and rotation, replacing any existing body. Raises when no ancestor is a physics root or the definition is invalid. |
| `removeBody(): void` | Detaches this node's body; does nothing without one. |
| `getBody(): PhysicsBody \| null` | Returns this node's body, or null when it has none. |
| `setBodyEnabled(enabled: boolean): void` | Takes the body out of, or back into, the simulation, keeping its state. |
| `bodyEnabled(): boolean` | True when this node has a body that takes part in the simulation. |
| `stepPhysics(dt: float): void` | Advances the physics root enclosing this node by `dt` seconds and skips that root's next automatic step. Raises when no ancestor is a physics root. |
| `setCacheAsTree(enabled: boolean, mode?: int): void` | Enables or disables this node's subtree as a cached texture. In `CacheTreeMode.MANUAL` mode (default), call `invalidateCache()` when the subtree changes; in `CacheTreeMode.AUTO` mode, changes are detected automatically (slight overhead per change). Renders the whole subtree to an offscreen texture on the next frame and draws the texture thereafter until invalidated. Useful for reducing overdraw in complex, rarely-changing UI or tilesets. Requires a real renderer; has no effect in headless builds. |
| `invalidateCache(): void` | Invalidates the cache for this node's subtree, forcing a re-render on the next frame. Has no effect if cache-as-tree is not enabled. Called automatically in `CacheTreeMode.AUTO` on any setter; required manually in `CacheTreeMode.MANUAL` mode. |
| `isCacheEnabled(): boolean` | Returns true if this node's subtree is cached as a texture. |
| `resetInterpolation(): void` | Forgets the previous tick: the next draw shows the node exactly where it is now, with no slide from where it was. Call it after setting `x`/`y` to teleport a node that has `interpolate` on. |
| `dispose(): void` | Releases this node's native resources now rather than whenever the collector runs. Calling `dispose()` twice is a silent no-op. Every other method or field on a disposed node, on every subclass, raises a catchable `InvalidStateError` that names it, for example `"InvalidStateError: Node.x: node has been disposed"`. A disposed node also leaves its parent: `children()` no longer lists it and `parent.contains(deadChild)` answers `false`. `engine.root2d` cannot be disposed. |
| `add(child: Node): void` | Adds `child` to this node's child list and takes ownership. The scene graph holds a strong reference; `removeChild` drops it. |
| `addAt(child: Node, index: int): void` | Adds `child` at child index `index`, so it draws before the children already at or after that index. `index` runs `0..children().length`; re-adding an existing child of this node moves it, and its valid range is then `0..children().length, 1`. An out-of-range index raises a `RangeError`. |
| `children(): Array<Node>` | Returns a snapshot array of this node's direct children. |
| `contains(child: Node): boolean` | True if `child` is a direct child of this node. |
| `directionTo(other: Node): Vec2` | Returns the unit vector pointing from this node toward `other` in world space. Returns the zero vector if both nodes share a position. |
| `distanceTo(other: Node): float` | Euclidean distance between this node's world position and `other`'s, in pixels. |
| `localToWorld(p: any): Vec2` | Maps a point in this node's local space to world space. Returns a freshly-allocated `Vec2`. `p` accepts any `{ x, y }`-shaped value (a `Vec2` or a plain object literal), only the numeric `x`/`y` fields are read. |
| `toScreen(x: float, y: float): Vec2` | Maps a point in this node's local space to screen units (`engine.screen2d`'s space, the framebuffer in the units the camera viewport is given in). A node under the world root goes through the camera; a node under `engine.screen2d` does not. Place a screen2d node over a world point with it each frame (a ring over a unit), or anchor an overlay to a world node. Returns a freshly-allocated `Vec2`. |
| `fromScreen(x: float, y: float): Vec2` | The inverse of `toScreen`: maps a point in screen units to this node's local space, through the camera when the node is under the world root. Returns a freshly-allocated `Vec2`. |
| `remove(): void` | Removes this node from its current parent. No-op if already detached. |
| `removeAllChildren(): void` | Removes every direct child from this node in one call. |
| `removeChild(child: Node): void` | Drops the strong reference to `child` from this node. Inverse of `add`. No-op if `child` is not a direct child of this node. |
| `setAnchor(nx: float, ny: float): void` | Pivot setter taking normalised 0..1 coordinates relative to the node's source size. (0, 0) is top-left (default), (0.5, 0.5) is the centre. Centring the pivot is what makes a rotating node spin in place instead of swinging around its top-left corner. |
| `alignPivot(horizontal?: Align, vertical?: Align): void` | Moves the pivot to an edge or the centre of the node's current content, Starling's `alignPivot`: `alignPivot()` centres it, `alignPivot(Align.CENTER, Align.BOTTOM)` puts it at the bottom middle (feet of a character). Set once from the current size; a later resize does not move it. `horizontal` takes `Align.LEFT`, `CENTER` or `RIGHT`; `vertical` takes `Align.TOP`, `CENTER` or `BOTTOM`; any other value raises `RangeError`. |
| `clearRenderLayer(): void` | Drops this node's own `renderLayer` so it inherits its nearest ancestor's again. |
| `setHitRect(x: float, y: float, width: float, height: float): void` | Overrides this node's hit-test area with an axis-aligned rectangle in LOCAL coordinates, replacing whatever custom shape (if any) was set before. Without a custom shape, hit-testing uses the node's default bounding-box rect. |
| `setHitCircle(centerX: float, centerY: float, radius: float): void` | Overrides this node's hit-test area with a circle in LOCAL coordinates. See `setHitRect` for the default/override relationship. |
| `setHitPolygon(points: Float32Array \| Array<float>): void` | Overrides this node's hit-test area with a convex polygon in LOCAL coordinates, given as a flat `[x0, y0, x1, y1...]` array (at least 3 points). See `setHitRect` for the default/override relationship. |
| `clearHitShape(): void` | Clears a custom hit-test shape set by `setHitRect` / `setHitCircle` / `setHitPolygon`, reverting to the default bounding-box rect. |
| `hasHitShape(): boolean` | True while a custom hit-test shape set by `setHitRect` / `setHitCircle` / `setHitPolygon` is attached. |
| `hitShapeContains(x: float, y: float): boolean` | Whether the LOCAL-space point (`x`, `y`) is inside this node's custom hit-test shape. `false` when no custom shape is attached. |
| `setPivot(px: float, py: float): void` | Pivot setter in raw pixel coordinates. See `setAnchor` for the normalised form. |
| `setPosition(x: float, y: float): void` | Sets local position. Equivalent to writing `x` and `y` individually but in one call. |
| `setRotation(radians: float): void` | Sets local rotation in radians. Equivalent to writing `rotation`. |
| `setScale(sx: float, sy?: float): void` | Sets scale. One-arg form sets both axes to the same value. Two-arg form sets them independently. |
| `setSize(w: float, h: float): void` | Resize the node. For primitives (Quad, etc.) this scales relative to the authored base size. For sprites it derives a scaling factor from the texture dimensions. The cached `scaleX` / `scaleY` fields update to reflect the result. |
| `setSkew(sx: float, sy: float): void` | Sets local skew on both axes in radians. |
| `worldBounds(): Rect` | Returns this node's world-space bounds as a freshly-allocated `Rect`. The world transform is refreshed before reading, so a node moved earlier in the same frame returns its post-move bounds. |
| `worldPosition(): Vec2` | Returns this node's world-space position as a freshly-allocated `Vec2`. The world transform is refreshed before reading. |
| `worldToLocal(p: any): Vec2` | Maps a point in world space to this node's local space. Returns a freshly-allocated `Vec2`. `p` accepts any `{ x, y }`-shaped value (a `Vec2` or a plain object literal), only the numeric `x`/`y` fields are read. |
| `on(name: string, handler: Function): Function` | Registers `handler` for a custom event named `name`, the Starling/Pixi.js-style escape hatch, layered ON TOP of the typed setters above (`onClick`, etc.) rather than replacing them: a typed setter and a generic `on("click"...)` listener both fire for the same real click. Events emitted on a descendant bubble up through every ancestor's listeners for the same name (in registration order at each level), until either the tree root is reached or a listener calls `e.stopPropagation()`. Returns `handler` for chaining, same convention as `engine.onFrame`. |
| `off(name: string, handler: Function): boolean` | Removes a specific `handler` previously registered for `name` via `on`, matched by reference. Returns `true` if a listener was removed. |
| `offAll(name?: string): void` | Removes every listener registered via `on` for `name`. With no argument, removes every listener for every name on this node. |
| `emit(name: string, data?: any): void` | Dispatches `name` on this node, then bubbles to every ancestor, see `on`'s bubbling note. `data` (optional) is forwarded as `e.data` on the `Event` every listener receives. |
| `hasListener(name: string): boolean` | True if this node has at least one listener registered for `name` via `on`. |

## Event

```ts
class Event
```

Payload handed to a `Node.on`/`emit` listener. `type` is the event name; `target` is the node `emit` was originally called on (constant across the whole bubble); `currentTarget` is whichever node's listener is currently running (changes at each bubble level); `data` is whatever `emit`'s second argument was, or `undefined`. `stopPropagation()` halts the bubble walk before any further ancestor is reached.

### Event: properties

| Member | Description |
|---|---|
| `type: string` | The event name passed to `emit`. |
| `target: Node` | The node `emit` was originally called on. Constant across the whole bubble. |
| `currentTarget: Node` | Whichever node's listener is currently running. Changes at each bubble level. |
| `data: any` | Whatever `emit`'s second argument was, or `undefined`. |

### Event: methods

| Member | Description |
|---|---|
| `stopPropagation(): void` | Halts the bubble walk before any further ancestor's listeners run. |

## Align

```ts
enum Align
```

Edge or centre for `node.alignPivot`.

### Align: values

| Member | Description |
|---|---|
| `LEFT` | The left edge (horizontal). |
| `CENTER` | The centre (either axis). |
| `RIGHT` | The right edge (horizontal). |
| `TOP` | The top edge (vertical). |
| `BOTTOM` | The bottom edge (vertical). |

## PauseMode

```ts
enum PauseMode
```

How a node treats a pause above it (`node.pauseMode`); Godot's process modes.

### PauseMode: values

| Member | Description |
|---|---|
| `INHERIT` | Follows its parent (default). |
| `ALWAYS` | Keeps running while ancestors are paused: a pause menu or debug overlay inside the game tree. |
| `WHEN_PAUSED` | Runs only while an ancestor is paused. |
| `DISABLED` | Never runs. |

---

URL: https://thicketscript.com/willow/reference/particles

# ParticleEmitter

Pooled 2D particles.

```ts
import { ParticleEmitter, EmitterConfig, Range } from "willow";
```

## ParticleEmitter

```ts
class ParticleEmitter extends Node
```

Extends [Node](./node.md#node).

Particle emitter node managing a pool of simulated 2D particles.

### ParticleEmitter: constructors

```ts
new ParticleEmitter(name?: string, config?: EmitterConfig)
```

Constructs a new particle emitter node with optional name and config.

### ParticleEmitter: properties

| Member | Description |
|---|---|
| `config: EmitterConfig` | Emitter configuration controlling particle spawning and physics. |
| `readonly particleCount: int` | Current number of active particles alive in the simulation. |
| `readonly aliveCount: int` | Alias for particleCount. Current number of active alive particles. |
| `readonly active: boolean` | Whether the emitter is currently active and spawning particles. |
| `seed: int` | Deterministic RNG seed state for particle variations. |

### ParticleEmitter: methods

| Member | Description |
|---|---|
| `start(): void` | Begins emitting particles according to the emitter config rate. |
| `stop(): void` | Stops emitting new particles; live particles continue until death. |
| `reset(): void` | Stops emission and immediately clears all active particles. |
| `burst(count: int): void` | Spawns a burst of particles immediately. |
| `update(dt: float): void` | Advances particle simulation and quad rendering by dt seconds. |
| `setSeed(seed: int): void` | Sets the random seed for reproducible particle variation. |
| `bounds(): Rect` | Axis-aligned bounding box covering all currently alive particles. |

### ParticleEmitter: static methods

| Member | Description |
|---|---|
| `static create(name: string, config: EmitterConfig): ParticleEmitter` | Factory creating a new particle emitter node. |

## EmitterConfig

```ts
class EmitterConfig
```

Configuration options for particle emitter simulation and visuals.

### EmitterConfig: constructors

```ts
new EmitterConfig()
```

Constructs an EmitterConfig with default settings.

### EmitterConfig: properties

| Member | Description |
|---|---|
| `maxParticles: int` | Maximum pool size of concurrent particles. Defaults to 128. |
| `emitRate: float` | Emission rate in particles spawned per second. Defaults to 10.0. |
| `lifetime: Range` | Lifetime range of spawned particles in seconds. |
| `lifetimeMin: float` | Minimum particle lifetime in seconds. Defaults to 1.0. |
| `lifetimeMax: float` | Maximum particle lifetime in seconds. Defaults to 1.0. |
| `speed: Range` | Initial particle speed range in pixels per second. |
| `speedMin: float` | Minimum initial speed in pixels per second. Defaults to 50.0. |
| `speedMax: float` | Maximum initial speed in pixels per second. Defaults to 50.0. |
| `angle: Range` | Emission angle range in radians. Defaults to full circle [0, 2*PI]. |
| `angleMin: float` | Minimum emission angle in radians. Defaults to 0.0. |
| `angleMax: float` | Maximum emission angle in radians. Defaults to 2*PI. |
| `gravityX: float` | Constant horizontal acceleration applied to particles. Defaults to 0.0. |
| `gravityY: float` | Constant vertical acceleration applied to particles. Defaults to 0.0. |
| `startScale: float` | Scale factor at particle birth. Defaults to 1.0. |
| `endScale: float` | Scale factor at particle death. Defaults to 1.0. |
| `scaleStart: float` | Alias for startScale. Scale factor at particle birth. Defaults to 1.0. |
| `scaleEnd: float` | Alias for endScale. Scale factor at particle death. Defaults to 1.0. |
| `startAlpha: float` | Alpha multiplier at particle birth. Defaults to 1.0. |
| `endAlpha: float` | Alpha multiplier at particle death. Defaults to 0.0. |
| `alphaStart: float` | Alias for startAlpha. Alpha multiplier at particle birth. Defaults to 1.0. |
| `alphaEnd: float` | Alias for endAlpha. Alpha multiplier at particle death. Defaults to 0.0. |
| `startColor: Color` | Tint color at particle birth. Defaults to white. |
| `endColor: Color` | Tint color at particle death. Defaults to white. |
| `colorStart: Color` | Alias for startColor. Tint color at particle birth. |
| `colorEnd: Color` | Alias for endColor. Tint color at particle death. |
| `blendMode: string` | Compositor blend mode for particles. Defaults to "add". |
| `worldSpace: boolean` | When true, emitted particles remain in world space rather than following node. Defaults to false. |

## Range

```ts
class Range
```

A min/max range of numbers. `EmitterConfig` uses it for `lifetime`, `speed` and `angle`.

### Range: constructors

```ts
new Range(min: float, max: float)
```

### Range: properties

| Member | Description |
|---|---|
| `min: float` | Lower bound, inclusive. |
| `max: float` | Upper bound, inclusive. |

### Range: methods

| Member | Description |
|---|---|
| `random(): float` | A uniformly-distributed random value in `[min, max]`. Returns `min` when `min === max`. |

---

URL: https://thicketscript.com/willow/reference/physics

# Physics

Rigid bodies attached to nodes.

```ts
import { PhysicsConfig, PhysicsBody, PhysicsBodyDef, PhysicsDynamic, PhysicsStatic, PhysicsKinematic, PhysicsShape, PhysicsCircle, PhysicsBox, PhysicsSegment, PhysicsPolygon, PhysicsBodyKind, PhysicsShapeKind } from "willow";
```

## PhysicsConfig

```ts
class PhysicsConfig
```

Tunables for a physics world, passed to `Node.enablePhysics`.

### PhysicsConfig: constructors

```ts
new PhysicsConfig(gravity?: Vec2, iterations?: int, sleepTime?: float)
```

### PhysicsConfig: properties

| Member | Description |
|---|---|
| `gravity: Vec2` | Gravity in pixels per second squared; positive y points down the screen. |
| `iterations: int` | Solver iterations per step; 0 keeps the engine default (10). |
| `sleepTime: float` | Seconds a resting body waits before it sleeps; 0 never sleeps. |

## PhysicsBody

```ts
class PhysicsBody
```

The live body attached to a node, from `Node.getBody()`. Reading it after the node was disposed or its body removed raises `InvalidStateError`.

### PhysicsBody: properties

| Member | Description |
|---|---|
| `readonly kind: int` | Which body this is: one of the `PhysicsBodyKind` constants. |

### PhysicsBody: methods

| Member | Description |
|---|---|
| `enabled(): boolean` | True while the body takes part in the simulation (see `Node.setBodyEnabled`). |
| `position(): Vec2` | The body's position in its physics root's space. |
| `angle(): float` | The body's rotation in radians. |
| `velocity(): Vec2` | The body's linear velocity in pixels per second. |
| `angularVelocity(): float` | The body's angular velocity in radians per second. |
| `mass(): float` | The body's mass. |
| `moment(): float` | The body's moment of inertia. |
| `friction(): float` | The shape's friction coefficient. |
| `elasticity(): float` | The shape's elasticity. |
| `setPosition(position: Vec2): void` | Moves the body (and, on the next step, its node) to `position`. |
| `setAngle(radians: float): void` | Rotates the body to `radians`. |
| `setVelocity(velocity: Vec2): void` | Sets the linear velocity in pixels per second. |
| `setAngularVelocity(velocity: float): void` | Sets the angular velocity in radians per second. |
| `applyImpulse(impulse: Vec2): void` | Applies an instant impulse at the centre of gravity. |
| `applyForce(force: Vec2): void` | Applies a force at the centre of gravity until the next step. |

## PhysicsBodyDef

```ts
class PhysicsBodyDef
```

A body description passed to `Node.setBody`. Build one with `PhysicsDynamic`, `PhysicsStatic` or `PhysicsKinematic`.

### PhysicsBodyDef: properties

| Member | Description |
|---|---|
| `readonly kind: int` | Which body this is: one of the `PhysicsBodyKind` constants. |
| `shape: PhysicsShape` | The collider of the body. |
| `mass: float` | Mass; must be above 0 for a dynamic body. |
| `friction: float` | Surface friction coefficient. |
| `elasticity: float` | Bounciness, 0 (none) to 1 (perfectly elastic). |
| `moment: float` | Moment of inertia; 0 computes it from the shape and mass. |

## PhysicsDynamic

```ts
class PhysicsDynamic extends PhysicsBodyDef
```

Extends [PhysicsBodyDef](./physics.md#physicsbodydef).

A body driven by forces, impulses and collisions.

### PhysicsDynamic: constructors

```ts
new PhysicsDynamic(shape: PhysicsShape, mass: float, friction?: float, elasticity?: float, moment?: float)
```

## PhysicsStatic

```ts
class PhysicsStatic extends PhysicsBodyDef
```

Extends [PhysicsBodyDef](./physics.md#physicsbodydef).

An immovable body used for terrain and obstacles.

### PhysicsStatic: constructors

```ts
new PhysicsStatic(shape: PhysicsShape, friction?: float, elasticity?: float)
```

## PhysicsKinematic

```ts
class PhysicsKinematic extends PhysicsBodyDef
```

Extends [PhysicsBodyDef](./physics.md#physicsbodydef).

A body moved by script that ignores forces and gravity.

### PhysicsKinematic: constructors

```ts
new PhysicsKinematic(shape: PhysicsShape, friction?: float)
```

## PhysicsShape

```ts
class PhysicsShape
```

A collider descriptor. Build one with `PhysicsCircle`, `PhysicsBox`, `PhysicsSegment` or `PhysicsPolygon`.

### PhysicsShape: properties

| Member | Description |
|---|---|
| `readonly kind: int` | Which collider this is: one of the `PhysicsShapeKind` constants. |

## PhysicsCircle

```ts
class PhysicsCircle extends PhysicsShape
```

Extends [PhysicsShape](./physics.md#physicsshape).

A circular collider.

### PhysicsCircle: constructors

```ts
new PhysicsCircle(radius: float, offset?: Vec2)
```

### PhysicsCircle: properties

| Member | Description |
|---|---|
| `radius: float` | Circle radius in pixels. |
| `offset: Vec2` | Centre of the circle relative to the node's position. |

## PhysicsBox

```ts
class PhysicsBox extends PhysicsShape
```

Extends [PhysicsShape](./physics.md#physicsshape).

A rectangular collider centred on the node's position.

### PhysicsBox: constructors

```ts
new PhysicsBox(width: float, height: float, cornerRadius?: float)
```

### PhysicsBox: properties

| Member | Description |
|---|---|
| `width: float` | Box width in pixels. |
| `height: float` | Box height in pixels. |
| `cornerRadius: float` | Radius that rounds the corners; 0 keeps them square. |

## PhysicsSegment

```ts
class PhysicsSegment extends PhysicsShape
```

Extends [PhysicsShape](./physics.md#physicsshape).

A line-segment collider.

### PhysicsSegment: constructors

```ts
new PhysicsSegment(a: Vec2, b: Vec2, radius?: float)
```

### PhysicsSegment: properties

| Member | Description |
|---|---|
| `a: Vec2` | First endpoint relative to the node's position. |
| `b: Vec2` | Second endpoint relative to the node's position. |
| `radius: float` | Thickness radius around the segment; 0 is a hairline. |

## PhysicsPolygon

```ts
class PhysicsPolygon extends PhysicsShape
```

Extends [PhysicsShape](./physics.md#physicsshape).

A convex polygon collider.

### PhysicsPolygon: constructors

```ts
new PhysicsPolygon(verts: Array<Vec2>, cornerRadius?: float)
```

### PhysicsPolygon: properties

| Member | Description |
|---|---|
| `verts: Array<Vec2>` | Polygon points relative to the node's position; the convex hull is used. |
| `cornerRadius: float` | Radius that rounds the corners; 0 keeps them sharp. |

## PhysicsBodyKind

```ts
class PhysicsBodyKind
```

Which kind of body a physics definition describes.

### PhysicsBodyKind: static properties

| Member | Description |
|---|---|
| `static readonly DYNAMIC: int` | Driven by forces, impulses and collisions. |
| `static readonly STATIC: int` | Immovable terrain and obstacles. |
| `static readonly KINEMATIC: int` | Moved by script (a velocity or a position), ignoring forces and gravity. |

## PhysicsShapeKind

```ts
class PhysicsShapeKind
```

Which collider a physics shape describes.

### PhysicsShapeKind: static properties

| Member | Description |
|---|---|
| `static readonly CIRCLE: int` | A circle, optionally offset from the node's position. |
| `static readonly BOX: int` | A box centred on the node's position. |
| `static readonly SEGMENT: int` | A line segment with an optional thickness. |
| `static readonly POLYGON: int` | A convex polygon; the convex hull of the points is used. |

---

URL: https://thicketscript.com/willow/reference/polygon-mesh

# Polygon and Mesh

Filled shapes and raw triangle meshes.

```ts
import { Polygon, Mesh } from "willow";
```

## Polygon

```ts
class Polygon extends Node
```

Extends [Node](./node.md#node).

Filled polygon backed by one vertex-coloured mesh.

### Polygon: constructors

```ts
new Polygon(points: Float32Array | Array<float>, color: Color)
```

`points` is a flat `[x0, y0, x1, y1...]` array (at least 3 points).

### Polygon: properties

| Member | Description |
|---|---|
| `readonly color: Color` | Solid fill colour (0xRRGGBBAA, always 8 digits, a 6-digit literal is read as A=0x00, fully transparent). |

### Polygon: methods

| Member | Description |
|---|---|
| `setPoints(points: Float32Array \| Array<float>, color?: Color): void` | Replaces this polygon's vertices and, optionally, its colour. Same point/colour shape as the constructor. |
| `setColor(color: Color): void` | Equivalent to `polygon.color = color`. Solid fill colour. |

### Polygon: static methods

| Member | Description |
|---|---|
| `static regular(sides: int, radius: float, color: Color): Polygon` | Creates a solid-colour regular polygon with `sides` vertices centred at the polygon origin. |
| `static star(points: int, outerRadius: float, innerRadius: float, color: Color): Polygon` | Creates a solid-colour star polygon with `points` outer points, alternating `outerRadius`/`innerRadius`. |
| `static circle(radius: float, color: Color): Polygon` | Creates a solid-colour circle, approximated as a 32-segment regular polygon, Equivalent to `Polygon.regular(32, radius, color)`. |
| `static triangle(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float, color: Color): Polygon` | Creates a solid-colour triangle from three arbitrary points. A thin wrapper over the general `Polygon(points, color)` constructor for exactly 3 points. |
| `static textured(texture: Texture \| TextureRegion, points: Float32Array \| Array<float>): Polygon` | Creates a textured polygon mesh. Points form an arbitrary simple polygon triangulated via ear-clipping; texture coordinates are normalized from the polygon bounding box to the texture region. |

## Mesh

```ts
class Mesh extends Node
```

Extends [Node](./node.md#node).

Untextured mesh. Vertices use x, y, u, v, r, g, b, a stride order.

### Mesh: constructors

```ts
new Mesh(vertices: Float32Array | Array<float>, indices: Uint16Array | Array<int>)
```

`vertices` uses x, y, u, v, r, g, b, a stride order; `indices` are triangle-list vertex indices.

### Mesh: properties

| Member | Description |
|---|---|
| `tint: Color` | Colour tint, a `Color`, default `Color.WHITE`. It multiplies the vertex colours at draw time, so a colour change does not rebuild the vertex buffer. |

### Mesh: methods

| Member | Description |
|---|---|
| `setVertices(vertices: Float32Array \| Array<float>): void` | Replaces this mesh's vertex buffer. Same x, y, u, v, r, g, b, a stride order as the constructor. |
| `setIndices(indices: Uint16Array \| Array<int>): void` | Replaces this mesh's triangle-list index buffer. |
| `invalidateBounds(): void` | Forces this mesh's cached bounds to be recomputed on next use, after an out-of-band vertex edit. |

---

URL: https://thicketscript.com/willow/reference/quad

# Quad

Solid-colour rectangles and lines.

```ts
import { Quad } from "willow";
```

## Quad

```ts
class Quad extends Node
```

Extends [Node](./node.md#node).

Solid-colour quad (no texture). Useful for primitives and tests.

### Quad: constructors

```ts
new Quad(width: float, height: float)
new Quad(width: float, height: float, color: Color)
```

### Quad: properties

| Member | Description |
|---|---|
| `color: Color` | Equivalent to `quad.color = color`. Solid fill colour, a `Color`. |
| `height: float` | Quad height in pixels (authored base size). |
| `width: float` | Quad width in pixels (authored base size). |

### Quad: methods

| Member | Description |
|---|---|
| `setColor(color: Color): void` | Equivalent to `quad.color = color`. Solid fill colour. |

### Quad: static methods

| Member | Description |
|---|---|
| `static line(x1: float, y1: float, x2: float, y2: float, thickness: float, color: Color): Quad` | Creates a solid-colour line segment from `(x1, y1)` to `(x2, y2)` with the given `thickness`. |

---

URL: https://thicketscript.com/willow/reference/render-texture

# RenderTexture

Offscreen canvases and subtree capture.

```ts
import { RenderTexture, RenderTextureDrawOpts, ToTexture, FXAAConfig } from "willow";
```

## RenderTexture

```ts
class RenderTexture
```

Persistent offscreen canvas. Owns a GPU render target, not pooled, not recycled between frames, and provides immediate drawing methods. Draw a `Texture` or a `TextureRegion` onto it, then display the result via `createSpriteNode()`, which returns a `Sprite` whose pixels are this canvas's contents.

### RenderTexture: constructors

```ts
new RenderTexture(width: int, height: int)
```

### RenderTexture: properties

| Member | Description |
|---|---|
| `readonly width: int` | Canvas width in pixels, as constructed or last `resize()`d. |
| `readonly height: int` | Canvas height in pixels, as constructed or last `resize()`d. |

### RenderTexture: methods

| Member | Description |
|---|---|
| `drawImage(texture: Texture, x: float, y: float): void` | Draws all of `texture` onto this canvas at `(x, y)`, normal blend, no tint. |
| `drawImageTransformed(texture: Texture, opts: RenderTextureDrawOpts): void` | Draws all of `texture` onto this canvas with the full transform/tint/blend in `opts`. |
| `drawSprite(region: TextureRegion, x: float, y: float): void` | Draws `region` onto this canvas at `(x, y)`, normal blend, no tint. |
| `drawSpriteTransformed(region: TextureRegion, opts: RenderTextureDrawOpts): void` | Draws `region` onto this canvas with the full transform/tint/blend in `opts`. |
| `clear(): void` | Clears the canvas to fully transparent. |
| `fill(color: Color): void` | Fills the entire canvas with `color`. |
| `createSpriteNode(name: string): Sprite` | Creates a new `Sprite` node whose pixels are this canvas's current contents. The sprite is a live view, later draws onto this `RenderTexture` show up on every sprite created from it, since both reference the same GPU render target. |
| `resize(width: int, height: int): void` | Deallocates the old canvas and creates a new one at the given size. Existing sprite nodes follow the new render target with updated dimensions. |
| `dispose(): void` | Releases the GPU render target. Idempotent and silent, like every other `dispose()`. Existing sprite nodes created from this canvas are cleanly detached (rendered blank). |

## RenderTextureDrawOpts

```ts
class RenderTextureDrawOpts
```

Transform/tint options for `RenderTexture.drawImageTransformed` / `drawSpriteTransformed`. `color` is the built-in `Color`, like every other colour field in this file; `alpha` is an additional multiplier on top of it, matching the native struct.

### RenderTextureDrawOpts: constructors

```ts
new RenderTextureDrawOpts()
```

### RenderTextureDrawOpts: properties

| Member | Description |
|---|---|
| `x: float` | Draw position X in canvas pixels. Defaults to 0. |
| `y: float` | Draw position Y in canvas pixels. Defaults to 0. |
| `scaleX: float` | Horizontal scale factor. Defaults to 1.0. |
| `scaleY: float` | Vertical scale factor. Defaults to 1.0. |
| `rotation: float` | Rotation in radians. Defaults to 0. |
| `pivotX: float` | Rotation/scale pivot X in source pixel space. Defaults to 0. |
| `pivotY: float` | Rotation/scale pivot Y in source pixel space. Defaults to 0. |
| `color: Color` | Tint colour. Defaults to `Color.WHITE`. |
| `alpha: float` | Extra alpha multiplier on top of `color`'s own alpha byte. Defaults to 1.0. |
| `blend: string` | Compositor blend mode. Same string set as `Node.blendMode`: one of `"normal"` \| `"add"` \| `"multiply"` \| `"screen"` \| `"erase"` \| `"mask"` \| `"below"` \| `"none"`. Defaults to `"normal"`. |

## ToTexture

```ts
function ToTexture(node: Node, width?: int, height?: int): RenderTexture
```

Renders `node` and its descendants once into a new `RenderTexture`. The subtree is drawn in its own local space with the bounds origin at the canvas's top-left, so the result is the subtree cut out of the scene: show it with `createSpriteNode()`. Draws through `Scene.main`'s pipeline, so it raises `InvalidStateError` when no Willow scene is published. A one-shot capture, not part of the frame: call it between frames (from `onUpdate`, not from custom paint). The caller owns the canvas and disposes it. 
- `node`: The subtree root. 
- `width`: Canvas width in pixels; defaults to the subtree's bounds width. 
- `height`: Canvas height in pixels; defaults to the subtree's bounds height. 
- Returns: A new `RenderTexture` holding the subtree.

## FXAAConfig

```ts
class FXAAConfig
```

Settings for an FXAA (fast approximate antialiasing) pass. Only the settings value exists today: willow has no FXAA render pass yet, so creating one changes nothing on screen.

### FXAAConfig: constructors

```ts
new FXAAConfig(subpixQuality?: float, edgeThreshold?: float, edgeThresholdMin?: float)
```

### FXAAConfig: properties

| Member | Description |
|---|---|
| `subpixQuality: float` | Sub-pixel aliasing removal, 0.0 (off).. 1.0 (max). Default 0.75. |
| `edgeThreshold: float` | Minimum local contrast required to trigger AA. Lower catches more edges but blurs more. Default 0.166. |
| `edgeThresholdMin: float` | Skips AA on pixels below this darkness threshold, to avoid noise in shadows. Default 0.0312. |

### FXAAConfig: static methods

| Member | Description |
|---|---|
| `static default(): FXAAConfig` | FXAA 3.11 quality-15 defaults. Equivalent to `new FXAAConfig()`. |

---

URL: https://thicketscript.com/willow/reference/rope

# Rope and DistortionGrid

Ribbons along a path, and deformable grid meshes.

```ts
import { Rope, RopeConfig, RopeJoinMode, RopeCurveMode, DistortionGrid } from "willow";
```

## Rope

```ts
class Rope extends Node
```

Extends [Node](./node.md#node).

Generates a ribbon/rope mesh following a polyline path or procedural curve.

### Rope: constructors

```ts
new Rope(texture: Texture | TextureRegion, pointsOrConfig?: Float32Array | Array<float> | RopeConfig, config?: RopeConfig)
```

Creates a new Rope node with an optional path or curve configuration.

### Rope: properties

| Member | Description |
|---|---|
| `readonly node: Node` | Returns this rope's underlying scene node (returns `this`). |
| `config: RopeConfig` | Configuration for procedural curve generation. |

### Rope: methods

| Member | Description |
|---|---|
| `setPoints(points: Float32Array \| Array<float>): void` | Replaces the rope's polyline points. |
| `update(): void` | Recomputes the curve path from the rope's config and updates vertices. |

## RopeConfig

```ts
class RopeConfig
```

Configuration options for constructing and updating a Rope mesh.

### RopeConfig: properties

| Member | Description |
|---|---|
| `width?: float` | Width of the rope ribbon in pixels. |
| `joinMode?: int` | Corner join mode: RopeJoinMode.MITER (0) or RopeJoinMode.BEVEL (1). |
| `curveMode?: int` | Curve algorithm: one of RopeCurveMode constants (0..5). |
| `segments?: int` | Number of curve subdivisions (default 20). |
| `start?: Vec2` | Start point of the curve. |
| `end?: Vec2` | End point of the curve. |
| `sag?: float` | Sag offset in pixels for catenary curves. |
| `control0?: Vec2` | First control point for Bezier curves. |
| `control1?: Vec2` | Second control point for cubic Bezier curves. |
| `amplitude?: float` | Wave amplitude in pixels for wave curves. |
| `frequency?: float` | Wave frequency in cycles for wave curves. |
| `phase?: float` | Wave phase offset in radians for wave curves. |
| `color?: Color` | Vertex tint colour. |

## RopeJoinMode

```ts
class RopeJoinMode
```

Controls how segment corners join in a Rope mesh.

### RopeJoinMode: static properties

| Member | Description |
|---|---|
| `static readonly MITER: int` | Miter join: outer corner vertices are extended to meet. |
| `static readonly BEVEL: int` | Bevel join: outer corners are square without extension. |

## RopeCurveMode

```ts
class RopeCurveMode
```

Selects the curve algorithm used to compute rope segment vertices.

### RopeCurveMode: static properties

| Member | Description |
|---|---|
| `static readonly LINE: int` | Linear interpolation between start and end. |
| `static readonly CATENARY: int` | Catenary curve with sag. |
| `static readonly QUAD_BEZIER: int` | Quadratic Bezier curve using control0. |
| `static readonly CUBIC_BEZIER: int` | Cubic Bezier curve using control0 and control1. |
| `static readonly WAVE: int` | Sine wave along the segment between start and end. |
| `static readonly CUSTOM: int` | Custom curve callback. |

## DistortionGrid

```ts
class DistortionGrid extends Node
```

Extends [Node](./node.md#node).

Deformable grid mesh that can be deformed per-vertex from its rest position.

### DistortionGrid: constructors

```ts
new DistortionGrid(texture: Texture | TextureRegion, cols: int, rows: int)
```

Creates a grid mesh over `texture` with `cols` columns and `rows` rows.

### DistortionGrid: properties

| Member | Description |
|---|---|
| `readonly cols: int` | Number of grid cell columns. |
| `readonly rows: int` | Number of grid cell rows. |
| `readonly node: Node` | Returns this grid's underlying scene node (returns `this`). |

### DistortionGrid: methods

| Member | Description |
|---|---|
| `setVertex(col: int, row: int, dx: float, dy: float): void` | Offsets a single grid vertex at (col, row) by (dx, dy) from its rest position. |
| `setPoint(col: int, row: int, dx: float, dy: float): void` | Offsets a single grid vertex at (col, row) by (dx, dy) from its rest position. |
| `reset(): void` | Resets all grid vertices to their original rest positions. |

---

URL: https://thicketscript.com/willow/reference/scene

# Scene

The app's scene: its world root, screen root, camera, layers, keys and transitions. Module `willow-scene`, read without an import.

## Scene

```ts
class Scene
```

A scene: its root node, size, focus and key callbacks. Willow declares it, so a host that binds a `willow::Scene` (the `thicket` program, or a C++ application) gets the same script type.

### Scene: properties

| Member | Description |
|---|---|
| `readonly root: Node` | The scene's root node. |
| `readonly screenRoot: Node` | The scene's screen-space root (`engine.screen2d`): drawn after the world without the camera, in screen units (the framebuffer, in the units the camera viewport is given in), so a menu or HUD added here does not scroll or zoom. Input reaches it first; only a visible, interactive node takes an event, otherwise the event falls through to the world. Screen-sized things go here; world-sized ones (damage numbers, a name tag that zooms) stay under `root`. Use `node.toScreen(x, y)` to place a screen node over a world point. |
| `readonly camera: Camera2D \| null` | The scene's 2D camera (the same object as `engine.camera`), or null until a host binds one. World (0, 0) stays at the top-left of the window until the script moves the camera. |
| `readonly index: NodeIndex \| null` | The scene's tag index: every node that is added with `add(node...tags)` can be found by name or tag, and a node that is disposed leaves it. Null until a host binds the scene. |
| `readonly width: int` | Scene width in logical pixels. |
| `readonly height: int` | Scene height in logical pixels. |
| `backgroundColor: int` | Background colour as a packed colour int. It is the scene's clear colour; the window shows it. |
| `readonly frameTime: float` | Seconds the last frame took. |
| `readonly elapsed: float` | Seconds since the scene started. |
| `focus: Node \| null` | Focused node, or null. An INPUT Text starts IME text input. |
| `readonly LAYER_BACKGROUND: int` | Reserved `Node.renderLayer` convention for backdrop content that sits behind everything. Value: 0. See `Node.renderLayer`. |
| `readonly LAYER_DEFAULT: int` | Reserved `Node.renderLayer` convention for ordinary world/game content. Value: 64. Leaves room below for backdrops and above for UI. See `Node.renderLayer`. |
| `readonly LAYER_UI: int` | Reserved `Node.renderLayer` convention for UI/HUD drawn over the world. Value: 192. See `Node.renderLayer`. |
| `readonly LAYER_OVERLAY: int` | Reserved `Node.renderLayer` convention for topmost overlays (transitions, debug). Value: 255 (willow's max layer). See `Node.renderLayer`. |

### Scene: methods

| Member | Description |
|---|---|
| `add(child: Node): Node` | Adds a child to the scene root.  - `child`: The node to add.  - Returns: The added node. |
| `remove(child: Node): Node` | Removes a child from the scene root.  - `child`: The node to remove.  - Returns: The removed node. |
| `onKeyDown(cb: Function): Function` | Registers a callback for every key-down transition, in arrival order. It receives a `KeyEvent`.  - `cb`: The callback.  - Returns: A function that unregisters it. |
| `onKeyUp(cb: Function): Function` | Registers a callback for every key-up transition, in arrival order. It receives a `KeyEvent`.  - `cb`: The callback.  - Returns: A function that unregisters it. |
| `onBackgroundClick(cb: Function): Function` | Registers a callback invoked when a pointer click lands on the empty scene background (missed all nodes). The callback receives a `PointerEvent` carrying coordinates, button, and `modifiers` bitmask matching `KeyModifiers`. |
| `playTransition(transition: Transition, from: Node, to: Node, fromScreen?: Node, toScreen?: Node): Promise<void>` | Plays `transition` between two nodes of this scene: `from` leaves, `to` arrives. Both are normally children of `root`. While it plays the scene draws every other node as usual and the two subtrees only through the transition. Both are drawn the way the scene draws them (through the camera, with light layers, filters and masks), and the transition composites where `to` sorts: at its render layer, so a HUD on a higher layer such as `LAYER_UI` stays on top. The returned promise resolves once, when the transition ends. The scene never removes or disposes either node: `from` stays in the tree and alive until then, and the caller retires it after the promise resolves. A node disposed while the transition plays ends it. The promise rejects when a transition is already playing or the scene is not backed by a Willow scene.  - `transition`: The effect, for example `Transition.fade(0.3)`.  - `from`: The outgoing node.  - `to`: The incoming node.  - `fromScreen`: Optional: the outgoing side's subtree under `screenRoot` (its dialogue box, its menu). It is drawn without the camera over `from` and fades with it; screen nodes outside the pair (a toast, a debug HUD) stay on top, untouched.  - `toScreen`: Optional: the incoming side's subtree under `screenRoot`.  - Returns: A promise that resolves when the transition has ended. |
| `cancelTransition(): boolean` | Stops the transition that is playing, at once. Its `playTransition` promise REJECTS with a string starting `CancellationError` (it does not resolve: the transition never finished, and a caller that retires `from` after the promise must not do so on a cancel). The scene lets go of both nodes and touches neither: `from` stays in the tree and alive, `to` stays too, and the caller decides what to do with them. A new `playTransition` may start in the same call stack. Does nothing when no transition is playing.  - Returns: `true` when a transition was playing and is now cancelled, `false` when there was none. |

### Scene: static properties

| Member | Description |
|---|---|
| `static readonly main: Scene \| null` | The app's scene, the same object as `engine.scene`, or null until a host binds one (a console program, willow without a window, has none). Prefer this to `engine` in library code: a package that names `engine` needs a window app, one that reads `Scene.main` loads anywhere. |

## KeyEvent

```ts
class KeyEvent
```

Payload of `Scene.onKeyDown` / `onKeyUp`. `keyCode` equals the `Key.*` constant of the physical key; `label` is the printed character on the current layout and `charCode` its code point (0 for non-printing keys).

### KeyEvent: properties

| Member | Description |
|---|---|
| `readonly keyCode: int` | The `Key.*` constant of the physical key. |
| `readonly charCode: int` | Code point of the printed character; 0 for non-printing keys. |
| `readonly label: string` | The printed character on the current layout. |
| `readonly repeat: boolean` | True for an auto-repeat. |
| `readonly shiftKey: boolean` | True while Shift is held. |
| `readonly ctrlKey: boolean` | True while Ctrl is held. |
| `readonly altKey: boolean` | True while Alt is held. |
| `readonly metaKey: boolean` | True while Meta (Windows/Command) is held. |

---

URL: https://thicketscript.com/willow/reference/sprite

# Sprite and SpriteBatch

Textured display objects.

```ts
import { Sprite, SpriteBatch } from "willow";
```

## Sprite

```ts
class Sprite extends Node
```

Extends [Node](./node.md#node).

Textured sprite backed by a whole texture or a texture region.

### Sprite: constructors

```ts
new Sprite(path: string)
new Sprite(texture: Texture)
new Sprite(region: TextureRegion)
```

### Sprite: properties

| Member | Description |
|---|---|
| `readonly height: float` | Source-region height in pixels. |
| `readonly region: TextureRegion` | The rectangular source region currently drawn by this sprite. |
| `readonly texture: Texture` | Texture that backs the current region. |
| `tint: Color` | Multiplicative tint colour, a `Color`. White/opaque is `Color.WHITE`. |
| `readonly width: float` | Source-region width in pixels. |

### Sprite: methods

| Member | Description |
|---|---|
| `setRegion(region: TextureRegion): void` | Replaces the rectangular source region drawn by the sprite. |
| `setTexture(texture: Texture): void` | Replaces the sprite source with the texture's full image. |
| `setTint(color: Color): void` | Equivalent to `sprite.tint = color`. Multiplicative tint. |

## SpriteBatch

```ts
class SpriteBatch extends Node
```

Extends [Node](./node.md#node).

Many simple sprites drawn as one flat batch: use `SpriteBatch` instead of `Sprite` when you have thousands of sprites that only move, scale, rotate or tint. Each element is a few floats, not a scene-graph node, so a batch holds far more sprites at speed; elements cannot take children, filters or input. All elements share the batch's one texture. Element positions are in the batch's local space and rotate about their top-left corner.

An element is named by the handle `add` returns (a number). A handle stays valid until its element is removed; a stale handle is rejected, never silently pointed at a different element.

Element methods carry a `Sprite` suffix so they never shadow the batch node's own `Node` members (`add`, `remove`, `setPosition`...).

### SpriteBatch: constructors

```ts
new SpriteBatch(texture: Texture)
new SpriteBatch(region: TextureRegion)
```

A whole texture, or one region of it (elements default to that region).

### SpriteBatch: properties

| Member | Description |
|---|---|
| `readonly texture: Texture` | Texture that backs every element of this batch. |

### SpriteBatch: methods

| Member | Description |
|---|---|
| `addSprite(x: float, y: float, region?: TextureRegion): float` | Adds an element with its top-left at `(x, y)` and returns its handle. `region` picks a different region of the same texture. |
| `removeSprite(handle: float): boolean` | Removes an element. Returns false when the handle was already dead. |
| `hasSprite(handle: float): boolean` | True while `handle` names a live element. |
| `spriteCount(): int` | Number of live elements. |
| `clearSprites(): void` | Removes every element; all handles become dead. |
| `setSpritePosition(handle: float, x: float, y: float): void` | Moves one element (top-left, batch-local pixels). |
| `setSpriteScale(handle: float, scaleX: float, scaleY: float): void` | Scales one element about its top-left corner. |
| `setSpriteRotation(handle: float, radians: float): void` | Rotates one element about its top-left corner, in radians. |
| `setSpriteAlpha(handle: float, alpha: float): void` | Sets one element's opacity, 0 to 1. |
| `setSpriteTint(handle: float, color: Color): void` | Sets one element's tint, a `Color`. White/opaque is `Color.WHITE`. |
| `setSpriteRegion(handle: float, region: TextureRegion): void` | Points one element at another region of the batch's texture. |
| `setSpritePositions(positions: Float32Array \| Array<float>): void` | Moves many elements at once from a flat `[x0, y0, x1, y1...]` array. Pair `i` moves the element in slot `i` (the slot order `addSprite` handed out, with removed slots skipped); extra pairs are ignored. |

---

URL: https://thicketscript.com/willow/reference/text

# Text

The text display object and its effects and input events.

```ts
import { Text, TextEffects, TextFieldType, TextInputEvent, TextCompositionEvent } from "willow";
```

## Text

```ts
class Text extends Node
```

Extends [Node](./node.md#node).

Text-rendering primitive. `text` is live-settable.

### Text: constructors

```ts
new Text(text: string)
new Text(text: string, font: Font)
```

### Text: properties

| Member | Description |
|---|---|
| `align: string` | Horizontal text alignment. One of `"left"` \| `"center"` \| `"right"`. An unknown string raises a typed VM error. Defaults to `"left"`. |
| `color: Color` | Equivalent to `label.color = color`. Glyph fill colour, a `Color`. |
| `fontSize: float` | Glyph point size in pixels. Defaults to 16. Assigning re-flows on the next frame. |
| `wrapWidth: float` | Wrap width in pixels; text wraps to fit. 0 (default) disables wrapping. |
| `lineHeight: float` | Line-spacing multiplier (1 = single-spaced, default). Must be > 0. |
| `sharpness: float` | SDF edge sharpness, 0 (default) to 1 (sharpest); values outside are clamped. Higher values narrow the anti-aliased edge of the glyphs. |
| `pixelSnap: boolean` | Whole-pixel text, `true` (default): the first baseline and the x origin land on whole pixels when the text is not rotated or skewed, which keeps small text crisp. Set `false` on a label that moves slowly, so it glides instead of stepping a pixel at a time. |
| `style: string` | Font style: `"regular"` (default), `"bold"`, `"italic"`, or `"boldItalic"`. |
| `readonly effects: TextEffects` | Outline / glow / shadow parameters. See `TextEffects`. |
| `font: Font` | Bound font. Assigning triggers re-layout on the next frame. |
| `readonly height: float` | Measured text height in pixels, valid after the first layout pass. |
| `text: string` | The text content. Assigning triggers re-layout on the next frame. |
| `type: TextFieldType` | `DYNAMIC` (default) or `INPUT`. Only focused INPUT text can receive typing and end-entry Backspace. For caret, selection or clipboard editing, use willowui's TextInput or TextArea. |
| `maxChars: int` | Maximum Unicode characters accepted by typing. 0 (default) means unlimited. |
| `restrict: RegExp \| null` | Optional regex every typed character must match before `onTextInput` fires. |
| `readonly width: float` | Measured text width in pixels, valid after the first layout pass. |

### Text: methods

| Member | Description |
|---|---|
| `setColor(color: Color): void` | Equivalent to `label.color = color`. Glyph fill colour. |
| `setFont(font: Font): void` | Replaces the label's font. Triggers re-layout on the next frame. |
| `setText(text: string): void` | Equivalent to `label.text = text`. Triggers re-layout on the next frame. |
| `onTextInput(cb: (e: TextInputEvent) => void): Function` | Registers a cancelable pre-append text callback. Returns an unsubscribe function. |
| `onTextComposition(cb: (e: TextCompositionEvent) => void): Function` | Registers a callback for IME pre-edit updates. They never change `text`. |
| `onChange(cb: () => void): Function` | Registers a callback after focused typing or Backspace changes `text`. Returns an unsubscribe function. |
| `measure(): Size` | Computes the text layout (applying any pending property writes) without rendering and returns its `{ width, height }` in pixels. |

## TextEffects

```ts
class TextEffects
```

Outline / glow / drop-shadow parameters for a `Text`, reached via `label.effects`. All widths/offsets default to 0 (no effect drawn); colours are the built-in `Color`, like `Text.color`. Assigning any field takes effect on the next frame (or immediately before a `label.measure()` call).

### TextEffects: properties

| Member | Description |
|---|---|
| `outlineWidth: float` | Outline thickness in pixels. 0 disables the outline. |
| `outlineColor: Color` | Outline colour. |
| `glowWidth: float` | Glow radius in pixels. 0 disables the glow. |
| `glowColor: Color` | Glow colour. |
| `shadowOffsetX: float` | Drop-shadow horizontal offset in pixels. |
| `shadowOffsetY: float` | Drop-shadow vertical offset in pixels. |
| `shadowColor: Color` | Drop-shadow colour. |

## TextFieldType

```ts
enum TextFieldType
```

Input mode for a `Text` node. Dynamic text never receives IME input.

### TextFieldType: values

| Member | Description |
|---|---|
| `DYNAMIC` | Display-only text that does not accept focused typing. |
| `INPUT` | Editable text that receives IME and character input while focused. |

## TextInputEvent

```ts
class TextInputEvent
```

Cancelable event sent to a focused input `Text` before its content changes.

### TextInputEvent: properties

| Member | Description |
|---|---|
| `readonly text: string` | Accepted text proposed for insertion. |

### TextInputEvent: methods

| Member | Description |
|---|---|
| `preventDefault(): void` | Cancels insertion and suppresses the following change callback. |

## TextCompositionEvent

```ts
class TextCompositionEvent
```

A transient IME pre-edit update for a focused input `Text`.

### TextCompositionEvent: properties

| Member | Description |
|---|---|
| `readonly text: string` | Pre-edit text. Empty text with `cancelled` clears the composition. |
| `readonly selectionStart: int` | Selected segment start and length, measured in Unicode code points. |
| `readonly selectionLength: int` | Number of composed code points selected by the input method. |
| `readonly replacementStart: int` | Range in the widget selection which the eventual commit replaces. -1 means unspecified. |
| `readonly replacementLength: int` | Number of existing code points replaced by this composition. |
| `readonly cancelled: boolean` | True when the platform cancelled the active pre-edit. |

---

URL: https://thicketscript.com/willow/reference/texture

# Texture and TextureRegion

Images on the GPU and rectangles inside them.

```ts
import { Texture, TextureRegion } from "willow";
```

## Texture

```ts
class Texture
```

Texture handle backed by a GPU resource. Textures can be loaded from a path or encoded bytes, or created from RGBA pixels. Direct `new Texture(...)` raises a TypeError.

### Texture: properties

| Member | Description |
|---|---|
| `readonly height: int` | Texture height in pixels. |
| `readonly width: int` | Texture width in pixels. |

### Texture: methods

| Member | Description |
|---|---|
| `dispose(): void` | Releases the GPU resource. Idempotent and silent, like every other `dispose()`. |
| `update(rgba: Buffer \| Uint8Array): void` | Replaces all RGBA pixels of an updatable texture. |

### Texture: static methods

| Member | Description |
|---|---|
| `static load(path: string, opts?: any): Texture` | Loads a texture from `path` (resolved via the engine asset roots). Pass `{ cache: false }` to bypass the process-wide path cache. |
| `static fromBuffer(buffer: Buffer): Texture` | Loads a PNG or JPEG texture from encoded bytes. |
| `static fromPixels(width: int, height: int, rgba: Buffer \| Uint8Array, updatable?: boolean): Texture` | Creates a texture from width * height * 4 RGBA bytes. Requires an initialized renderer, so it is unavailable in a headless console program. Set `updatable` to true when the pixels will later be replaced. |

## TextureRegion

```ts
class TextureRegion
```

A rectangular sub-region of a texture with its source rectangle and pre-computed UVs. Direct `new TextureRegion(...)` raises a TypeError.

### TextureRegion: properties

| Member | Description |
|---|---|
| `readonly x: float` | Source x within the texture, in pixels. |
| `readonly y: float` | Source y within the texture, in pixels. |
| `readonly width: float` | Region width in pixels. |
| `readonly height: float` | Region height in pixels. |

### TextureRegion: static methods

| Member | Description |
|---|---|
| `static grid(tileset: Texture, tileWidth: int, tileHeight: int, opts?: any): Array<TextureRegion>` | Slices a regular grid tileset into an ordered `Array<TextureRegion>` (row-major, element 0 = the first cell = GID 1). `opts` accepts `{ columns?, count?, margin?, spacing? }`; `columns`/`count` are derived from the texture size when omitted. |
| `static fromRect(texture: Texture, x: float, y: float, width: float, height: float): TextureRegion` | Creates an axis-aligned pixel rectangle within `texture`. |

---

URL: https://thicketscript.com/willow/reference/tilemap

# TileLayer

Batched, culled tile grids.

```ts
import { TileLayer, TilemapViewport, TileQuery, GidInfo } from "willow";
```

## TileLayer

```ts
class TileLayer extends Node
```

Extends [Node](./node.md#node).

A batched, culled grid of tiles, the efficient way to build large 2D worlds (vs. one Sprite per cell). Backed by willow's tile renderer: one draw batch per layer, GID flip flags, animated tiles, and viewport culling. Construct with a config object:

```tks const tiles: Texture = Texture.load("tiles.png"); const regions: Array<TextureRegion> = TextureRegion.grid(tiles, 16, 16); const ground: TileLayer = new TileLayer({ tileWidth: 16, tileHeight: 16, columns: 64, rows: 64, tileset: tiles, regions: regions, data: world.groundData, }); ```

A GID of 0 is an empty cell; GID N maps to `regions[N, 1]`. The top three bits carry the horizontal / vertical / diagonal flip flags, use the `encodeGid` / `decodeGid` statics rather than packing bits by hand. Add a bare TileLayer to the scene to render its whole grid; add it under a `TilemapViewport` to cull to the camera-visible region.

### TileLayer: constructors

```ts
new TileLayer(config: any)
```

### TileLayer: properties

| Member | Description |
|---|---|
| `readonly columns: int` | Grid width in tiles. |
| `readonly rows: int` | Grid height in tiles. |
| `readonly tileWidth: float` | Tile width in pixels. |
| `readonly tileHeight: float` | Tile height in pixels. |

### TileLayer: methods

| Member | Description |
|---|---|
| `setTile(col: int, row: int, gid: int): void` | Sets the GID at `(col, row)`. Out-of-range coordinates or a negative GID raise a typed VM error. |
| `getTile(col: int, row: int): int` | Returns the GID at `(col, row)` (with any active animation frame applied). Out-of-range coordinates raise a typed VM error. |
| `setData(data: Array<int>): void` | Replaces the whole tile grid. `data.length` must equal `columns * rows`; otherwise a typed VM error is raised. |
| `setAnimation(gid: int, frames: Array<int>, fps: float): void` | Animates every cell whose base GID equals `gid`, cycling through `frames` (base GIDs) at `fps` frames per second. `fps` must be > 0. |
| `query(): TileQuery` | Returns a read-only `TileQuery` interface over this tile layer. |

### TileLayer: static methods

| Member | Description |
|---|---|
| `static encodeGid(index: int, flipH?: boolean, flipV?: boolean, flipD?: boolean): int` | Packs a tile `index` plus flip flags into a GID. Flags default to false. Inverse of `decodeGid`. |
| `static decodeGid(gid: int): GidInfo` | Unpacks a GID into its `{ index, flipH, flipV, flipD }`. |

## TilemapViewport

```ts
class TilemapViewport extends Node
```

Extends [Node](./node.md#node).

A container that clips its child `TileLayer`s to the camera-visible region each frame, only tiles inside the camera frustum (plus a `padding` margin) are meshed, so a huge map stays cheap. Culls against the engine camera; the optional `camera` config field is accepted for API symmetry. `new TilemapViewport({ padding: 96 })`.

### TilemapViewport: constructors

```ts
new TilemapViewport(config?: any)
```

### TilemapViewport: properties

| Member | Description |
|---|---|
| `padding: float` | Extra cull margin in world pixels beyond the camera frustum. |

## TileQuery

```ts
class TileQuery
```

Read-only view of tilemap data for collision, pathfinding or world queries. Exposes grid dimensions, tile sizes, coordinate conversions and tile ID queries.

### TileQuery: constructors

```ts
new TileQuery(layer: TileLayer)
```

### TileQuery: properties

| Member | Description |
|---|---|
| `readonly columns: int` | Grid width in columns. |
| `readonly rows: int` | Grid height in rows. |
| `readonly tileWidth: float` | Tile width in pixels. |
| `readonly tileHeight: float` | Tile height in pixels. |
| `readonly cols: int` | Grid width in columns. |
| `readonly tileW: float` | Tile width in pixels. |
| `readonly tileH: float` | Tile height in pixels. |

### TileQuery: methods

| Member | Description |
|---|---|
| `tileAt(col: int, row: int): int` | Returns the tile GID at `(col, row)` (with active animation), or 0 if out of bounds. |
| `rawAt(col: int, row: int): int` | Returns the raw (unanimated) tile GID at `(col, row)`, or 0 if out of bounds. |
| `worldToTile(worldX: float, worldY: float): any` | Converts world pixel coordinates to tile cell coordinates `{ col, row }`. |
| `tileToWorld(col: int, row: int): Vec2` | Converts tile coordinates `(col, row)` to world pixel coordinates `{ x, y }`. |
| `tileAtWorld(worldX: float, worldY: float): int` | Returns the tile GID at world coordinates `(worldX, worldY)`, or 0 if out of bounds. |

## GidInfo

```ts
class GidInfo
```

Decoded GID returned by `TileLayer.decodeGid`: the base tile `index` plus the three Tiled flip flags.

### GidInfo: properties

| Member | Description |
|---|---|
| `index: int` | Base tile index (flip bits stripped). |
| `flipH: boolean` | Horizontal-flip flag. |
| `flipV: boolean` | Vertical-flip flag. |
| `flipD: boolean` | Anti-diagonal-flip flag. |

---

URL: https://thicketscript.com/willow/reference/transition

# Transition

Effects played between two nodes by `Scene.playTransition`.

```ts
import { Transition, TransitionCanvas } from "willow";
```

## Transition

```ts
class Transition
```

An effect `Scene.playTransition` plays between two nodes. Willow's C++ `SceneManager` plays the same effects, so the two always look alike. Use `Transition.fade` for a crossfade, or write your own: a class that extends `Transition`, calls `super(seconds)` and overrides `render()`. `new Transition()` itself is not available. ``` class LeftWipe extends Transition { constructor(seconds: float) { super(seconds); } render(progress: float, outgoing: TextureRegion, incoming: TextureRegion, canvas: TransitionCanvas): void { canvas.draw(outgoing, 0.0, 0.0); canvas.drawPart(incoming, 0.0, 0.0, progress * canvas.width, canvas.height, 0.0, 0.0); } } ```

### Transition: constructors

```ts
new Transition(seconds: float)
```

Called by a subclass as `super(seconds)`. 
- `seconds`: How long the transition takes, 0 or more. 0 completes on the next frame.

### Transition: properties

| Member | Description |
|---|---|
| `readonly duration: float` | Length of the transition in seconds. |

### Transition: methods

| Member | Description |
|---|---|
| `render(progress: float, outgoing: TextureRegion, incoming: TextureRegion, canvas: TransitionCanvas): void` | The hook a subclass overrides to draw one frame. Willow has already drawn both screens, the way the scene draws them (camera, lights, filters and masks included), and calls this every frame while the transition plays. Draw the result with `canvas`: whatever is not drawn leaves the scene showing through, so a transition normally draws `outgoing` first and then the part of `incoming` that has arrived. Both regions and the canvas are valid only during this call, so do not store them. An exception thrown here is reported and that frame keeps whatever was drawn before it threw.  - `progress`: How far along the transition is, from 0 (just started) to 1 (finished).  - `outgoing`: The outgoing node, drawn as it looks now.  - `incoming`: The incoming node, drawn as it looks now.  - `canvas`: What to draw the effect with. |

### Transition: static methods

| Member | Description |
|---|---|
| `static fade(seconds: float): Transition` | A crossfade: the incoming node fades in over the outgoing one, a linear blend of the two.  - `seconds`: How long the fade takes, 0 or more. 0 completes on the next frame.  - Returns: The transition. |

## TransitionCanvas

```ts
class TransitionCanvas
```

What a `Transition` draws with, passed to its `render()`. Drawing goes straight onto the screen at the point where the transition sorts in the scene, in screen pixels (the top-left of the screen is (0, 0)). The canvas is only valid while `render()` runs: a stored canvas raises `InvalidStateError` when used later.

### TransitionCanvas: properties

| Member | Description |
|---|---|
| `readonly width: int` | Width of the area being transitioned, in pixels. Both source regions are this wide. |
| `readonly height: int` | Height of the area being transitioned, in pixels. Both source regions are this tall. |

### TransitionCanvas: methods

| Member | Description |
|---|---|
| `draw(region: TextureRegion, x: float, y: float, alpha?: float): void` | Draws `region` whole, with its top-left corner at `(x, y)`, at its own size.  - `region`: What to draw, normally `outgoing` or `incoming`.  - `x`: Screen X of the region's left edge.  - `y`: Screen Y of the region's top edge.  - `alpha`: Opacity from 0 to 1. Defaults to 1. |
| `drawPart(region: TextureRegion, srcX: float, srcY: float, width: float, height: float, x: float, y: float, alpha?: float): void` | Draws one rectangle of `region`, with its top-left corner at `(x, y)`, at its own size. A wipe draws a strip of the incoming screen that grows with the progress. A rectangle that runs past the region is cut to it.  - `region`: What to draw, normally `outgoing` or `incoming`.  - `srcX`: Left edge of the rectangle, in the region's own pixels.  - `srcY`: Top edge of the rectangle, in the region's own pixels.  - `width`: Width of the rectangle in pixels.  - `height`: Height of the rectangle in pixels.  - `x`: Screen X where the rectangle's left edge lands.  - `y`: Screen Y where the rectangle's top edge lands.  - `alpha`: Opacity from 0 to 1. Defaults to 1. |

---

URL: https://thicketscript.com/willow/reference/tween

# TweenGroup

Animate node fields and plain numbers over time.

```ts
import { TweenGroup, TweenConfig } from "willow";
```

## TweenGroup

```ts
class TweenGroup
```

An in-flight interpolation over up to 4 fields of a single Node, returned by the `TweenGroup.*` static factories below. A disposed target node ends the tween silently rather than raising. `TweenGroup.value` tweens a plain number with no node.

### TweenGroup: properties

| Member | Description |
|---|---|
| `readonly done: boolean` | True once every field has reached its end value, or the target was disposed. |

### TweenGroup: methods

| Member | Description |
|---|---|
| `update(dt: float): boolean` | Advances this tween by `dt` (same units as `TweenConfig.duration`) ON TOP of the automatic per-frame step, so a script that calls it every frame runs its tween at double speed. It exists for deterministic stepping in tests. Returns `true` once finished. A no-op returning `true` once already done or cancelled. |
| `cancel(): void` | Marks this tween for removal; the next `update` becomes a no-op finish. |

### TweenGroup: static methods

| Member | Description |
|---|---|
| `static activeCount(): int` | The number of tweens that are neither finished nor cancelled (leak checks). |
| `static value(from: float, to: float, cfg: TweenConfig, onStep: Function): TweenGroup` | Tweens a plain number from `from` to `to` with no node. `onStep(v)` runs on every step, and once with exactly `to` at the end, then `cfg.onDone` runs. Cancelling stops both. |
| `static position(node: Node, toX: float, toY: float, cfg: TweenConfig): TweenGroup` | Animates `node.x`/`node.y` to `(toX, toY)`. |
| `static alpha(node: Node, to: float, cfg: TweenConfig): TweenGroup` | Animates `node.alpha` to `to`. |
| `static color(node: Node, to: Color, cfg: TweenConfig): TweenGroup` | Animates a node's colour field (`tint` on Sprite; `color` on Quad/Text/Polygon) to `to`. Raises a TypeError if the node has neither field. |
| `static rotation(node: Node, to: float, cfg: TweenConfig): TweenGroup` | Animates `node.rotation` to `to` radians. |
| `static scale(node: Node, toSX: float, toSY: float, cfg: TweenConfig): TweenGroup` | Animates `node.scaleX`/`node.scaleY` to `(toSX, toSY)`. |

## TweenConfig

```ts
class TweenConfig
```

Duration + easing curve for a tween. `ease` is a core `Ease` constant or, for a custom curve, a function `(t, b, c, d): float` (`t` elapsed, `b` begin, `c` change, `d` duration). It defaults to `Ease.LINEAR` when omitted or `null`. `duration` is in the same units `TweenGroup.update`'s `dt` is stepped in (seconds by convention, matching `Node.onUpdate`'s `dt`).

### TweenConfig: constructors

```ts
new TweenConfig(duration: float, ease?: int | Function, onDone?: Function)
```

### TweenConfig: properties

| Member | Description |
|---|---|
| `duration: float` | Tween duration, in the same units `TweenGroup.update`'s `dt` is stepped in (seconds by convention). |
| `ease: int \| Function` | Easing curve: a core `Ease` constant or a custom `(t, b, c, d): float` function. Defaults to `Ease.LINEAR` when omitted or `null`. |

### TweenConfig: callbacks

| Member | Description |
|---|---|
| `onDone: Function` | Optional callback run once when the tween reaches its end. It does not run when the tween is cancelled or its target node is disposed. |

---

URL: https://thicketscript.com/willowui/

# willowui

<SiteArt src="/img/portal-willowui.webp" alt="Illustration: blank wooden and glass game menus, buttons and sliders drifting like lanterns among the trees at dusk" :width="1536" :height="1024" banner eager />

willowui is the UI toolkit for ThicketScript: buttons, labels, text input, lists, trees, tables, windows, menus, tooltips, toasts, color and date pickers, and more. It lays widgets out for you, styles them with themes, keeps them in step with your data through reactive refs, and can build a whole screen from an **XML template**.

It is written entirely in ThicketScript on top of [willow](/willow/), the 2D module, and it ships as a **package** that your project lists.

<SiteArt src="/art/module-willowui.svg" alt="A wooden UI window with a list, a slider, a checkbox, a toggle, a text field and buttons" :width="1200" :height="360" caption="Illustration" />

## A first screen

This is a complete window app: a label that counts and a button that adds one.

```ts
import { Button, DEFAULT_STAGE, Label, Ref, Screen } from "willowui";

const screen: Screen = new Screen();
const clicks: Ref<int> = new Ref<int>(0);
const text: Ref<string> = new Ref<string>("Clicks: 0");

const label: Label = new Label("count", "", "default", 24.0);
label.bindText(text);
label.setPosition(24.0, 24.0);
screen.add(label);

const button: Button = new Button("add", "Click me", "default", 16.0);
button.setSize(140.0, 40.0);
button.setPosition(24.0, 80.0);
button.setOnClick((): void => {
    clicks.set(clicks.peek() + 1);
    text.set("Clicks: " + clicks.peek());
});
screen.add(button);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => {
    DEFAULT_STAGE.update(dt);
});
```

The same screen as an XML template:

```xml
<Panel layout="vbox" spacing="12" padding="20">
    <Label bind:text="'Clicks: ' + clicks" fontSize="24" />
    <Button text="Click me" on:click="add" />
</Panel>
```

[XML templates](./xml/) shows the controller that supplies `clicks` and `add`.

## Where to go next

| If you want to | Read |
|---|---|
| Add willowui to a project and open a window | [Getting started](./getting-started.html) |
| Understand screens, the stage and components | [Concepts](./guide/concepts.html) |
| Arrange widgets in rows, columns, grids and anchors | [Layout](./guide/layout.html) |
| Build screens from XML | [XML templates](./xml/) |
| Look up a widget | [Widget catalogue](./widgets/) |
| Style with variants and themes | [Variants and inline themes](./xml/themes.html) |
| Get typed input back into your data | [Recipe: a form](./recipes/forms.html) |

## What is in the box

| Family | Widgets |
|---|---|
| [Core](./widgets/core.html) | Component, Panel, Label, Button, IconButton, Image, Tooltip, ScrollBar, ScrollPanel |
| [Display](./widgets/display.html) | Badge, ProgressBar, MeterBar, RichText, AnimatedImage, StatWeb, Toast, Spacer |
| [Interactive](./widgets/interactive.html) | Toggle, Checkbox, Radio, Slider, Select, OptionRotator, ToggleButtonBar, MenuBar, ContextMenu, Popover, ToolBar, DragHandle, TimePicker, CalendarSelector, KeybindInput, ImageCropper |
| [Text](./widgets/text.html) | TextInput, TextArea, MaskedInput, InputField, SearchBox, NumberStepper, Tag, TagBar, ColorPicker |
| [Containers](./widgets/containers.html) | Window, TabBar, List, TileList, TreeList, SortableList, SortableTreeList, TreeTable, Accordion, NavDrawer, AnchorLayout, TwoColumnLayout |
| [Composites](./widgets/composites.html) | DataTable, GradientEditor |

## Status

willowui is a port of an earlier Go library, and some files and comments in its source still say so. The pages here describe what the code does today; where a feature is partial, the page says so.

---

URL: https://thicketscript.com/willowui/getting-started

# Getting started

This page takes you from an empty project to a window with a label and a button. It assumes you have `thicket` installed and have read [Your first window](/docs/start/first-window.html).

## 1. Make a window project

```sh
thicket new myui window
cd myui
```

## 2. Add the package

willowui is a package, so your `thicket.json` lists it under `packages`. It draws with the `willow` system and builds some images with `bitmap`, so your project lists both systems too. A package never grants itself systems or permissions: your project does.

```json5
{
    entry: "app.tks",
    systems: ["willow", "bitmap"],
    packages: { willowui: "../willowui-tks" },
    window: { title: "My UI", width: 800, height: 600 },
}
```

The key, `willowui`, is the name you import from. The value is the path to the package folder.

If your app reads files (templates, themes, images from disk), add the `fs` system and `permissions: { fs: true }`.

## 3. Write the app

Replace `app.tks` with this:

```ts
import { Button, DEFAULT_STAGE, Label, Screen } from "willowui";

const screen: Screen = new Screen();

const hello: Label = new Label("hello", "Hello from willowui", "default", 20.0);
hello.setPosition(24.0, 24.0);
screen.add(hello);

const button: Button = new Button("greet", "Say hi", "default", 16.0);
button.setSize(120.0, 36.0);
button.setPosition(24.0, 70.0);
button.setOnClick((): void => {
    hello.setText("Hi!");
});
screen.add(button);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => {
    DEFAULT_STAGE.update(dt);
});
```

Run it:

```sh
thicket run
```

## What each part does

| Line | What it does |
|---|---|
| `new Screen()` | A screen holds one tree of widgets plus its own focus and input handling. |
| `new Label(name, text, font, size)` | Most widgets take a **name** first. Names let you find a widget later with `screen.findByName(name)`. `"default"` is the built-in font family. |
| `screen.add(widget)` | Puts the widget in the screen's root. |
| `DEFAULT_STAGE.setScene(engine.root2d)` | The stage draws its screens into willow's 2D scene. |
| `DEFAULT_STAGE.add(screen)` | Pushes the screen onto the stage and shows it. |
| `DEFAULT_STAGE.update(dt)` | Called once per frame. It runs input, focus, controllers and layout. Without it nothing responds. |

## Importing

Everything public is exported from the package root, so one import line covers most apps:

```ts
import { Button, Label, Panel, Screen, DEFAULT_STAGE, Ref, TemplateRegistry } from "willowui";
```

You can also import a single file by its path, which is what the examples in the willowui repository do:

```ts
import { Button } from "willowui/src/core/button";
```

## Next

- [Concepts](./guide/concepts.html): screens, the stage, controllers and components.
- [Layout](./guide/layout.html): stop positioning by hand.
- [XML templates](./xml/): describe the screen in markup instead of code.

---

URL: https://thicketscript.com/willowui/guide/concepts

# Concepts

willowui has four ideas. Learn them once and every widget behaves the same way.

## Components

Every widget is a **`Component`** (Button, Label and Window all extend it). A component has:

- a **name**, given in the constructor, used to find it later;
- a position and a size (`setPosition`, `setSize`, or `width` and `height` read back);
- **children**, added with `addChild`, which it can lay out for you (see [Layout](./layout.html));
- state flags: enabled, visible, hovered, pressed, focused;
- a **variant** that picks its look from the theme (primary, secondary, danger and so on);
- an underlying willow node (`component.node`) that holds the drawing.

A plain `Component` draws nothing. It is a box that holds and arranges children. A `Panel` is the same with a background, border and corner radius.

Components can also hold raw willow nodes that are not widgets, for example a `Sprite` or a `Quad`, with `addRawChild(node)`.

## Screens

A **`Screen`** is one page of UI: a root component, a focus manager and an input manager. You add widgets to it with `screen.add(widget)`, and you can look one up with `screen.findByName("save")`.

A screen has a lifecycle:

| Call | What happens |
|---|---|
| `show()` | Attaches the screen to the scene. The first time, calls the controller's `onCreate`. |
| `hide()` | Detaches it, keeping all its state. |
| `update(dt)` | One frame: overlays, focus and keyboard dispatch, the controller's `onUpdate`, then layout. |
| `dispose()` | Calls `onDispose`, stops every tracked binding and disposes the whole widget tree. The screen cannot be shown again. |

## Controllers

A **`Controller`** owns a screen's behaviour. It has three methods:

```ts
interface Controller {
    onCreate(screen: Screen): void;   // build the UI here
    onUpdate(dt: float): void;        // per-frame logic
    onDispose(): void;                // clean up
}
```

Attach one with `new Screen().withController(new MyController())`. A controller is optional: a screen without one uses a controller that does nothing.

A controller that also has `lookupRef(path)` and `callMethod(name)` is a **data provider** for XML templates. See [Bindings and events](../xml/bindings.html).

## The stage

The **stage** (`DEFAULT_STAGE`, a `StageManager`) is a stack of screens. You tell it where to draw once, then push screens onto it:

| Call | Use |
|---|---|
| `setScene(engine.root2d)` | Where screens attach. Call once at start-up. |
| `add(screen)` | Push and show a screen. |
| `replace(screen)` | Dispose the top screen and show the new one, for moving from a title screen to a game screen. |
| `remove(screen)` | Dispose one screen. |
| `top()` | The top screen, or null. |
| `update(dt)` | Update every visible screen. Call it from `App.onFrame`. |
| `dispose()` | Dispose everything, at shutdown. |

The usual frame loop is one line:

```ts
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

## Disposal

Widgets own native objects (nodes, textures, text), and ThicketScript frees them explicitly. Disposing a component disposes its children, its nodes and every binding it owns. Disposing a screen disposes everything on it. So:

- remove a widget for good with `widget.dispose()`;
- move between screens with `DEFAULT_STAGE.replace(next)`, which disposes the old one;
- a component can take ownership of any stop function with `component.own(stopFn)`, so the stop runs when the component goes.

## Overlays and managers

Some widgets float above everything: windows, menus, popovers, tooltips, toasts and the color picker. Each has a default manager (`DEFAULT_WINDOW_MANAGER`, `DEFAULT_MENU_POPUP_MANAGER`, `DEFAULT_POPOVER_MANAGER`, `DEFAULT_TOOLTIP_MANAGER`, `DEFAULT_TOAST_MANAGER`, `DEFAULT_COLOR_PICKER_MANAGER`) that keeps their stacking order and input in step. You usually only touch them to add a window or show a toast.

## Next

- [Layout](./layout.html)
- [Reactive state](./reactive-state.html): refs, computed values and binding widgets to data.
- [XML templates](../xml/)
- [Widget catalogue](../widgets/)

---

URL: https://thicketscript.com/willowui/guide/input-and-focus

# Input and focus

Mouse input goes to whatever is under the pointer. Keyboard input goes to the widget that has **focus**. willowui tracks focus for you, moves it with Tab and the arrow keys, and runs your key binds. All of that lives in one object, the **`FocusManager`**.

## The focus manager

Every `Screen` has a `focusManager`, which is `DEFAULT_FOCUS_MANAGER` unless you set another. `Screen.update` (called by `DEFAULT_STAGE.update`) runs it once per frame, so there is nothing to wire up.

| Member | Does |
|---|---|
| `focused` | The widget with focus, or `null`. |
| `setFocus(c)` | Gives focus to `c`. `setFocus(null)` or `clearFocus()` removes it. |
| `tabNext()`, `tabPrev()` | What Tab and Shift+Tab do. |
| `tabOrder` | The widgets that can take focus, in Tab order. |
| `bind(combo, fn)` | A global key bind. Returns a handle. |
| `bindScoped(comp, combo, fn)` | A key bind active only while `comp`, or something inside it, has focus. |
| `unbind(handle)` | Removes a global bind. |

Clicking a widget focuses it. Clicking empty space clears focus.

## Which widgets take focus

Interactive widgets (buttons, inputs, sliders, lists, and so on) call `enableFocusNavigation()` when they are made. That marks them focusable and adds them to the end of `tabOrder`. So **Tab order is creation order**. If you want a different order, create the widgets in that order.

A widget is skipped while it is disabled, hidden, or inside a disabled or hidden parent. Two flags take it out of one kind of navigation only:

| Flag | When false |
|---|---|
| `allowTab` | Tab and Shift+Tab skip it. |
| `allowSpatial` | The arrow keys skip it. |

Disposing a widget removes it from the tab order and drops its scoped binds.

This console program shows the rules without opening a window:

```ts
import { Button, Component, DEFAULT_FOCUS_MANAGER, FocusManager } from "willowui";

const fm: FocusManager = DEFAULT_FOCUS_MANAGER;
const play: Button = new Button("play", "Play", "default", 16.0);
const options: Button = new Button("options", "Options", "default", 16.0);
const quit: Button = new Button("quit", "Quit", "default", 16.0);
options.setEnabled(false);

function focusedName(): string {
    const f: Component | null = fm.focused;
    return f == null ? "nothing" : (f as Component).name;
}

console.log("in tab order: " + fm.tabOrder.length + ", first is " + play.name);
fm.tabNext();
console.log("Tab: " + focusedName());
fm.tabNext();
console.log("Tab: " + focusedName());
fm.tabPrev();
console.log("Shift+Tab: " + focusedName());
quit.allowTab = false;
fm.tabNext();
console.log("Tab: " + focusedName());
```

Output:

```text
in tab order: 3, first is play
Tab: play
Tab: quit
Shift+Tab: play
Tab: play
```

Options is disabled, so Tab goes from Play straight to Quit. Once Quit has `allowTab = false`, Play is the only stop left.

## Arrow keys: spatial navigation

When no widget claims an arrow key, the focus manager moves focus in that direction:

1. **Inside a VBox or HBox,** Up and Down (in a VBox) or Left and Right (in an HBox) go to the next eligible sibling. A menu laid out as a VBox works with no extra code.
2. **Otherwise,** it picks the nearest focusable widget on screen in that direction, scoring the gap between the two widgets plus how far off-line the other one is.

Some widgets use the arrows themselves: a slider changes its value, a list moves its selection. Those widgets set `interceptArrows`, and they get the key first.

## Key binds

A key bind runs a function when a key combination is pressed. Make the combination with `key(k, mods)`: `k` is a `Key` constant and `mods` is a mask of willow's `KeyModifiers` (`CTRL`, `SHIFT`, `ALT`), or `MOD_NONE`. The modifiers must match exactly. `CTRL` also matches the Command key.

The bind function returns a `boolean`. Return `true` to **consume** the key, so nothing later in the frame sees it.

```ts
import { Button, DEFAULT_FOCUS_MANAGER, DEFAULT_STAGE, Label, MOD_NONE, Panel, Screen, key } from "willowui";
import { KeyModifiers } from "willow";

const screen: Screen = new Screen();
const status: Label = new Label("status", "Ctrl+S saves. F1 works inside the panel.", "default", 14.0);
status.setPosition(20.0, 20.0);
screen.add(status);

const panel: Panel = new Panel("tools");
panel.setPosition(20.0, 60.0);
panel.setSize(220.0, 80.0);
screen.add(panel);
const help: Button = new Button("help", "Help", "default", 14.0);
help.setPosition(12.0, 12.0);
panel.addChild(help);

// Global: works whatever has focus.
const saveBind: int = DEFAULT_FOCUS_MANAGER.bind(key(Key.S, KeyModifiers.CTRL), (): boolean => {
    status.setText("Saved");
    return true;
});

// Scoped: only while the panel or a widget inside it has focus.
DEFAULT_FOCUS_MANAGER.bindScoped(panel, key(Key.F1, MOD_NONE), (): boolean => {
    status.setText("Help for the tools panel");
    return true;
});

// DEFAULT_FOCUS_MANAGER.unbind(saveBind) removes the global bind again.

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

## The order each frame

Each frame the focus manager handles keys in this order. Once a key is handled, later steps skip it.

1. A click outside every widget clears focus.
2. The focused widget takes the arrow keys it wants (`interceptArrows`).
3. Scoped binds whose widget is focused.
4. Global binds.
5. Tab and Shift+Tab.
6. Spatial navigation for the arrow keys nobody took.

So a scoped bind beats a global bind on the same key, and a global bind on an arrow key beats spatial navigation.

## UI keys and game keys

Game input, such as moving a character, reads the global input classes directly: `Keyboard.isDown(Key.RIGHT)`, `Gamepad`, `Mouse`. Those are ThicketScript built-ins, not part of willowui. Use focus and key binds for UI, and the input classes for play.

To let players rebind controls, use the `KeybindInput` widget. The [settings screen recipe](../recipes/settings.html) shows one.

## See also

- [Recipe: a main menu](../recipes/menus.html) uses spatial navigation in a VBox.
- [Widgets](../widgets/) lists which widgets take focus.

---

URL: https://thicketscript.com/willowui/guide/layout

# Layout

Any component can arrange its children. Set its `layout` and add children; willowui positions them on the next update. Leave `layout` at `LAYOUT_NONE` and you place children yourself with `setPosition`.

## The layout modes

| Mode | Constant | XML | What it does |
|---|---|---|---|
| None | `LAYOUT_NONE` | (default) | Children stay where you put them. |
| Vertical box | `LAYOUT_VBOX` | `layout="vbox"` | Children in a column, top to bottom. |
| Horizontal box | `LAYOUT_HBOX` | `layout="hbox"` | Children in a row, left to right. |
| Grid | `LAYOUT_GRID` | `layout="grid"` | Children in rows of `gridColumns` cells. |
| Flow | `LAYOUT_FLOW` | `layout="flow"` | A row that wraps onto the next line when it runs out of width, like words in a paragraph. |
| Anchor | `LAYOUT_ANCHOR` | `layout="anchor"` | Each child is pinned to a corner, an edge or the center, with pixel offsets. |

`newVBox(name)`, `newHBox(name)` and `newFlow(name)` make a plain component with that layout already set.

## A column of buttons

```ts
import { Button, DEFAULT_STAGE, LAYOUT_VBOX, Panel, Screen } from "willowui";

const screen: Screen = new Screen();

const menu: Panel = new Panel("menu");
menu.layout = LAYOUT_VBOX;
menu.spacing = 8.0;
menu.setPadding(16.0, 16.0, 16.0, 16.0);
menu.setPosition(40.0, 40.0);

for (const title of ["New game", "Continue", "Settings", "Quit"]) {
    const b: Button = new Button(title, title, "default", 16.0);
    b.setSize(200.0, 40.0);
    menu.addChild(b);
}
menu.sizeToContent();
screen.add(menu);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

`sizeToContent()` resizes the panel to fit its children. A template does this for you whenever a container has children but no size.

## Box settings

These fields live on every component. Set them on the container (spacing, padding, align, justify) or on a child (fill, grow, margin, size limits).

| Field | XML attribute | Applies to | Meaning |
|---|---|---|---|
| `spacing` | `spacing="8"` | container | Gap between children along the main axis. |
| `padding` | `padding="12"` | container | Space inside the edge. One value, `"vertical,horizontal"`, or `"top,right,bottom,left"`. On a Panel use `setPadding(top, right, bottom, left)` so the padding survives theme changes. |
| `align` | `align="center"` | container | Cross-axis alignment: `start`, `center`, `end`. |
| `justify` | `justify="end"` | container | Main-axis alignment: `start`, `center`, `end`, `space-between`. |
| `gridColumns` | `gridColumns="3"` | grid container | Number of columns. |
| `flowRowGap` | `flow-row-gap="6"` | flow container | Gap between wrapped rows. Falls back to `spacing` when zero. |
| `margin` | `margin="4"` | child | Space around the child. |
| `fill` | `fill="width"` | child | Stretch to the parent's content area: `width`, `height` or `both` (`FILL_WIDTH`, `FILL_HEIGHT`, `FILL_BOTH`). |
| `grow` | `grow="1"` | child of a vbox or hbox | Share of the space left after fixed-size children. Two children with `grow="1"` split it evenly; `grow="2"` takes twice as much. |
| `minWidth`, `minHeight`, `maxWidth`, `maxHeight` | same names | child | Size limits. A max of zero means no limit. |

The alignment constants are `ALIGN_START`, `ALIGN_CENTER`, `ALIGN_END` and `ALIGN_SPACE_BETWEEN`.

After changing a layout field in code, call `component.markLayoutDirty()` so the next update lays it out again. The XML setters do this for you.

## Anchors

An anchor layout pins each child to one of nine points of the parent: `ANCHOR_TOP_LEFT`, `ANCHOR_TOP_CENTER`, `ANCHOR_TOP_RIGHT`, `ANCHOR_MIDDLE_LEFT`, `ANCHOR_CENTER`, `ANCHOR_MIDDLE_RIGHT`, `ANCHOR_BOTTOM_LEFT`, `ANCHOR_BOTTOM_CENTER`, `ANCHOR_BOTTOM_RIGHT`. It suits game HUDs: health in one corner, a minimap in another.

```ts
import { ANCHOR_BOTTOM_RIGHT, ANCHOR_TOP_LEFT, Component, DEFAULT_STAGE, LAYOUT_ANCHOR, Label, Screen } from "willowui";

const screen: Screen = new Screen();
const hud: Component = new Component("hud");
hud.layout = LAYOUT_ANCHOR;
hud.setSize(800.0, 600.0);

const health: Label = new Label("health", "HP 100", "default", 18.0);
hud.addAnchoredChild(health, ANCHOR_TOP_LEFT, 12.0, 12.0);

const gold: Label = new Label("gold", "Gold 250", "default", 18.0);
hud.addAnchoredChild(gold, ANCHOR_BOTTOM_RIGHT, -12.0, -12.0);

screen.add(hud);
DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

`setAnchor(child, anchor, offsetX, offsetY)` moves a child that is already anchored. The `AnchorLayout` widget is the same idea with a background and border.

## Two columns of label and field

`TwoColumnLayout` lines up pairs: a label on the left, a control on the right. Add rows with `addRow(left, right)`. Its settings are `gap` (between the columns), `rowSpacing`, `leftWidth` or `columnRatio`, and `leftAlign` / `rightAlign`. It is the quickest way to build a settings form; see [Recipe: a form](../recipes/forms.html).

## Scrolling

Put content taller than the view in a `ScrollPanel`, give the panel its visible size with `setSize`, and tell it the content size with `setContentSize(w, h)`. It draws scroll bars and scrolls with the mouse wheel. `List`, `TreeList`, `TileList` and `DataTable` scroll on their own.

## Layout in XML

Every attribute above has the same name in XML. [Layout from XML](../xml/layout.html) shows each mode as a template.

---

URL: https://thicketscript.com/willowui/guide/reactive-state

# Reactive state

Without reactive state, every time the score changes you have to remember each label that shows it and call `setText` on it. With it, you keep the score in a **`Ref`** and bind the label to the ref once. When the ref changes, every widget bound to it updates.

The primitives come from ThicketScript's `reactivity` library. willowui re-exports them from its package root, next to a few helpers, so one import covers both.

## Refs

A `Ref<T>` holds one value.

| Member | Does |
|---|---|
| `new Ref<T>(initial)` | Makes a ref. |
| `ref.value` | Reads the value (and records it as a dependency inside `computed` or `watchEffect`). Assigning it writes. |
| `ref.set(v)` | Same as assigning `value`. |
| `ref.peek()` | Reads without recording a dependency. |
| `ref.on(fn)` | Calls `fn(newValue, oldValue)` after each change. |
| `ref.silent(v)` | Writes without notifying anyone. |
| `ref.reset()` | Goes back to the value it was made with. |

**Writes are immediate, notifications are batched.** After `hp.value = 50`, reading `hp.value` gives 50 at once. Listeners, effects and bound widgets run once, at the next frame boundary. Several writes in one frame reach each listener as one change, from the first old value to the last new one. Writing the value a ref already holds notifies nobody.

```ts
import { Ref, computed, watchEffect } from "reactivity";

class Health {
    static async main(): Promise<void> {
        const hp: Ref<float> = new Ref<float>(75.0);
        const maxHp: Ref<float> = new Ref<float>(100.0);
        const percent: Ref<any> = computed((): any => hp.value / maxHp.value * 100.0);

        const stop: Function = watchEffect((): void => {
            console.log("HP " + hp.value + " (" + percent.value + "%)");
        });
        hp.on((now: any, before: any): void => {
            console.log("changed " + before + " -> " + now);
        });

        hp.value = 60.0;
        hp.value = 50.0;
        console.log("read back at once: " + hp.value);

        await new Promise<void>((done: Function): void => { setTimeout((): void => { done(); }, 50); });
        stop();
    }
}
```

Output:

```text
HP 75 (75%)
read back at once: 50
HP 50 (50%)
changed 75 -> 50
```

The effect ran once when it was made and once more after the frame, not once per write. The listener saw one change, 75 to 50.

## Derived values: `computed`

`computed(fn)` makes a read-only ref whose value is `fn()`. It tracks every ref `fn` reads and works its value out again only when one of them has changed and someone reads it. Bind a widget to a computed exactly as you would to a ref.

## Effects: `watchEffect`

`watchEffect(fn)` runs `fn` now, records every ref it reads, and runs it again after any of them changes. It returns a **stop function**. Call it when you no longer need the effect, or the effect keeps running and keeps whatever it touches alive.

`watchValue(ref, fn)` from willowui watches one ref and calls `fn(oldValue, newValue)`: once at the start with the current value twice, then after each change. It returns a stop function too.

## Binding widgets

Most widgets have `bind*` methods that take a ref. The widget shows the ref's value now and follows it from then on.

| Method | Widgets |
|---|---|
| `bindText(Ref<string>)` | `Label`, `Button` |
| `bindValue(ref)` | `TextInput`, `TextArea`, `MaskedInput`, `SearchBox`, `InputField` (string); `Slider`, `NumberStepper`, `MeterBar` (float); `Checkbox`, `Toggle` (boolean); `OptionRotator`, `ColorPicker`, `GradientEditor`, `KeybindInput` |
| `bindSelected(Ref<int>)` | `List`, `TileList`, `SortableList`, `SortableTreeList`, `Select`, `Radio`, `TabBar`, `ToggleButtonBar`, `OptionRotator`, `ToolGroup`; `TreeList` takes a `Ref<TreeNode \| null>` |
| `bindItems(ReactiveArray)` | `List`, `TileList`, `DataTable` |
| `bindOptions(ReactiveArray)` | `Select`, `OptionRotator` |
| `bindEnabled(Ref<boolean>)`, `bindVisible(Ref<boolean>)` | Every component |

On an input widget, `bindValue` and `bindSelected` go **both ways**: what the user types, drags or picks is written into the ref, and code that sets the ref updates the widget. `bindText` goes one way, from the ref to the widget.

This settings panel has no `setText` and no change handlers. The readout follows the slider, and the Reset button is enabled only when something differs from the defaults:

```ts
import { BoundString, Button, Checkbox, Component, DEFAULT_STAGE, Label, Ref, Screen, Slider, bindFormatterf, computed, newVBox } from "willowui";

const volume: Ref<float> = new Ref<float>(0.8);
const muted: Ref<boolean> = new Ref<boolean>(false);

const screen: Screen = new Screen();
const column: Component = newVBox("settings");
column.spacing = 12.0;
column.setPosition(24.0, 24.0);
screen.add(column);

const slider: Slider = new Slider("volume");
slider.setRange(0.0, 1.0);
slider.setSize(240.0, 24.0);
slider.bindValue(volume);
column.addChild(slider);

const readout: Label = new Label("readout", "", "default", 16.0);
const text: BoundString = bindFormatterf(volume, "Volume: %.2f");
readout.bindText(text.ref);
readout.own(text.stop);
column.addChild(readout);

const mute: Checkbox = new Checkbox("mute", "Mute", "default", 16.0);
mute.bindValue(muted);
column.addChild(mute);

const reset: Button = new Button("reset", "Reset", "default", 16.0);
reset.setSize(120.0, 32.0);
reset.bindEnabled(computed((): any => volume.value != 0.8 || muted.value));
reset.setOnClick((): void => {
    volume.value = 0.8;
    muted.value = false;
});
column.addChild(reset);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

## Helpers

These return small functions, handy as click handlers:

| Helper | Returns or does |
|---|---|
| `increment(ref, n)` | A function that adds `n` to a number ref: `button.setOnClick(increment(clicks, 1))`. |
| `toggle(ref)` | A function that flips a boolean ref. |
| `setTo(ref, v)` | A function that sets the ref to `v`. |
| `update(ref, fn)` | Sets the ref to `fn(current)` now. |
| `bindFormatterf(ref, format)` | A `BoundString`: `.ref` is a string ref that follows `ref`, formatted with `%d`, `%s`, `%v`, `%f`, `%.Nf` or `%%`; `.stop` stops it following. |
| `bindFormatter(ref)` | The same with `%v`. |

## Lists and records

`ReactiveArray<T>` is an array that notifies on change: `push`, `insert`, `removeAt`, `move`, `swap`, `sort`, `set(items)` and the rest. Bind it to a `List`, `TileList` or `DataTable` with `bindItems`, and the widget adds, removes and moves rows as the array changes. Wrap many edits in `array.batch(fn)` to send one notification instead of one per edit. `onAdded`, `onRemoved`, `onMoved` and `onItemChanged` let your own code react to one kind of change.

`ReactiveRecord<V>` is a map of string keys that notifies on change, for form data and settings: `set(key, v)`, `get(key)`, `onFieldChange(key, fn)`, and `ref(key)` for a ref to one field that you can bind to a widget.

## Lifetime

A widget's own bindings stop when the widget is disposed. Anything else you start, a `watchEffect`, a `watchValue` or a `bindFormatterf`, keeps running until you stop it. Give the stop function to the component it belongs to with `component.own(stop)`, as the readout does above, and it stops when that component goes. A ref you never stop watching keeps its listeners, and the widgets they touch, alive.

XML templates use the same refs: a controller's `lookupRef` returns them, and `bind:` attributes bind to them. See [Bindings and events](../xml/bindings.html).

## Next

- [Layout](./layout.html)
- [A form](../recipes/forms.html) puts refs, inputs and a template together.

---

URL: https://thicketscript.com/willowui/guide/text-and-markup

# Text and markup

willowui has two widgets for text:

| Widget | Use it for |
|---|---|
| `Label` | One style per widget: a title, a value, a caption. Cheap, and the right default. |
| `RichText` | Mixed styles in one block: a bold word, a colored name, a link, an icon in a sentence, headings and bullet lists. |

For text the player types, see `TextInput`, `TextArea` and `RichTextEditor` on the [Text widgets](../widgets/text.html) page.

## Label

`new Label(name, text, family, size)` makes a label. `"default"` is the built-in font family.

| Method | Does |
|---|---|
| `setText(t)` | Changes the text. |
| `setFont(family)`, `setFontSize(size)` | Changes the font. |
| `setBold(b)`, `setItalic(b)` | Picks the bold or italic face of the family. |
| `setColor(c)` | Overrides the theme's text color. |
| `setAlign(a)` | `TEXT_ALIGN_LEFT`, `TEXT_ALIGN_CENTER` or `TEXT_ALIGN_RIGHT`. |
| `setWrapWidth(w)` | Wraps lines at `w` pixels. 0 means no wrapping. |
| `bindText(ref)` | Follows a `Ref<string>`. See [Reactive state](reactive-state.html). |

## RichText and setMarkup

`new RichText(name, family, size)` makes the widget. `setMarkup(text)` parses a small XML-like markup and replaces the content. An unknown tag throws, so a typo fails loudly instead of showing raw tags.

| Tag | Does |
|---|---|
| `<b>`, `<i>` | Bold, italic. |
| `<u>`, `<strike>` | Underline, strikethrough. |
| `<color value="#FFCC00">` | Text color. Takes the same color forms as themes: `#RRGGBB`, `#RRGGBBAA`, `rgb(...)`, `rgba(...)`, `white`, `black`, `transparent`. |
| `<size value="24">` | Font size in pixels. |
| `<outline thickness="2" color="#000000">` | A stroke behind the letters. Both attributes are optional (2 and black). |
| `<span color="..." size="..." font="bold">` | Several at once. `font` is `bold`, `italic`, `bolditalic` or `regular`. |
| `<link url="...">` | Underlined, clickable text. A click calls `onLinkClick` with the url. |
| `<icon=sheet.png:3/>` | Frame 3 of a horizontal sprite sheet of icons, inline with the text. |
| `<br/>` | Line break. |
| `<h1>`, `<h2>`, `<h3>` | A bold heading on its own line, scaled 2, 1.5 and 1.2 times the base size. `setHeadingScale(h1, h2, h3)` changes the scales. |
| `<ul>`, `<ol>`, `<li>` | Bullet and numbered lists, indented. |

`&amp;`, `&lt;`, `&gt;`, `&quot;` and `&apos;` write the characters `&`, `<`, `>`, `"` and `'`.

Other methods: `setWrapWidth(w)`, `setAlign(a)` (`RICH_ALIGN_LEFT`, `RICH_ALIGN_CENTER`, `RICH_ALIGN_RIGHT`, imported from `"willowui"`), `setColor(c)` and `setOutline(o)` for the defaults that tags override.

```ts
import { DEFAULT_STAGE, Label, RichText, Screen, TEXT_ALIGN_CENTER } from "willowui";

const screen: Screen = new Screen();

const title: Label = new Label("title", "Quest log", "default", 22.0);
title.setPosition(20.0, 16.0);
title.setWrapWidth(400.0);
title.setAlign(TEXT_ALIGN_CENTER);
screen.add(title);

const log: RichText = new RichText("log", "default", 16.0);
log.setPosition(20.0, 60.0);
log.setWrapWidth(400.0);
log.setMarkup(
    "<h2>The lost lantern</h2>" +
    "Find <color value=\"#FFCC00\">Mira</color> by the <b>old mill</b>.<br/>" +
    "<ul><li>Bring <i>rope</i></li><li>Avoid the <outline thickness=\"2\">bog</outline></li></ul>" +
    "<link url=\"map:mill\">Show on map</link>"
);
log.onLinkClick = (url: string): void => { title.setText("Opening " + url); };
screen.add(log);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

## What the markup turns into

`setMarkup` is built on `parseMarkup`, which is exported too. It turns markup into a list of `TextSpan`s, one per run of same-styled text. It needs no window, so it is a quick way to see what a string will do:

```ts
import { TextSpan, parseMarkup } from "willowui";

const spans: TextSpan[] = parseMarkup("Press <b>Space</b> to <color value=\"#FFCC00\">jump</color>", null, 16.0, [2.0, 1.5, 1.2]);
for (const s of spans) {
    console.log("[" + s.text + "] bold=" + s.bold + " colored=" + s.colorSet);
}
try {
    parseMarkup("a <blink>b</blink>", null, 16.0, [2.0, 1.5, 1.2]);
} catch (e) {
    console.log((e as Error).message);
}
```

Output:

```text
[Press ] bold=false colored=false
[Space] bold=true colored=false
[ to ] bold=false colored=false
[jump] bold=false colored=true
unknown markup tag <blink>
```

You can also build the spans yourself and pass them to `setSpans(spans)`, or append with `addSpan(text)` and `addTextSpan(span)`.

## RichText in XML

In a template, write the markup as the element's children. `markup="..."` and `bind:markup="..."` work too, and `on:linkClick` names the controller method for links.

```xml
<Panel layout="vbox" spacing="8" padding="16">
    <RichText fontSize="16" wrapWidth="360">
        <h2>Shop</h2>
        Gold: <color value="#FFD700">120</color>
        <ul><li>Potion</li><li>Ether</li></ul>
    </RichText>
</Panel>
```

Inline icons work the same way in a template: `<icon=sheet.png:3/>` inside `<RichText>` is passed to the markup parser as written.

## See also

- [Text widgets](../widgets/text.html): text input, text areas and the rich text editor.
- [Theming](theming.html): the `richText` and `label` theme entries set the default colors.

---

URL: https://thicketscript.com/willowui/guide/theming

# Theming

A **theme** decides how every widget looks: colors per state, borders, corner radius, padding, fonts, and images. You write it as JSON, load it once, and attach it to a widget. Every widget under that one picks it up.

## Where a theme applies

| Call | Effect |
|---|---|
| `component.setTheme(theme)` | That widget and everything under it use `theme`. `setTheme(null)` goes back to inheriting. |
| `setDefaultTheme(theme)` | The theme for any widget with no theme on itself or an ancestor. |
| `getDefaultTheme()` | The current default. willowui starts with its built-in default theme. |

A widget looks for a theme on itself, then its parent, then up the tree, then the default. So the usual pattern is one `screen.root.setTheme(theme)` per screen, plus an override on the odd panel that needs a different look.

## The theme file

```json
{
    "variants": ["card"],
    "colors": {
        "ink": "#EEEEEE",
        "surface": "#262629",
        "accent": "#59A6FF"
    },
    "components": {
        "_": { "borderWidth": 1, "cornerRadius": 4, "focusColor": { "focus": "$accent" } },
        "button": {
            "_": { "padding": { "top": 6, "right": 14, "bottom": 6, "left": 14 } },
            "primary": {
                "backgroundColor": { "default": "$surface", "hover": "#34343A", "disabled": "rgba(115, 115, 122, 0.6)" },
                "textColor": { "default": "$ink" }
            }
        },
        "panel": {
            "card": { "backgroundColor": { "default": "$surface" }, "cornerRadius": 8 }
        }
    }
}
```

The top-level keys:

| Key | What it holds |
|---|---|
| `colors` | Named colors. Use them anywhere as `"$name"`. |
| `variants` | Your own variant names (`card`, `muted`, ...). Each takes one of the custom slots. See [Variants and inline themes](../xml/themes.html). |
| `components` | One entry per widget kind (`button`, `label`, `panel`, `slider`, `list`, `window`, ...), then one entry per variant (`primary`, `secondary`, `accent`, `neutral`, `danger`, `success`, `warning`, `info`, or your own). |
| `nine-grids` | Images drawn as stretchable nine-slice backgrounds. See below. |
| `sprites` | Named rectangles cut from image files, for icons. |
| `fonts` | Font family per role. |

**`_` is the default layer.** `components._` applies to every widget that has a matching property. `components.button._` applies to every variant of the button. A variant's own value wins over both.

**Values per state.** Color and background properties take an object keyed by state: `default`, `hover`, `active`, `disabled`, `focus`, `focusHover`, `focusActive` and `focusDisabled`. Plain numbers such as `borderWidth` and `cornerRadius` take one value.

**Colors** are `#RRGGBB`, `#RRGGBBAA`, `rgb(...)`, `rgba(...)`, `white`, `black`, `transparent`, or a `$name` from `colors`. A background color can also be a gradient string starting with `gradient(`, `gradientH(` or `gradientV(`.

To see which widgets your theme leaves out, and which `$names` it uses but never defines, run the coverage report (see [themec](#compile-ahead-with-themec)).

## Load a theme

**`loadThemeAny(path)`** is the loader to use. It takes any of three things:

| `path` | What happens |
|---|---|
| a folder | Reads `theme.json` in it, plus the images it names. |
| a `.json` file | Reads that file, plus the images it names, relative to the file. |
| a compiled `.theme` file | Decodes it directly. This is what [themec](#compile-ahead-with-themec) writes. |

From source, the first load compiles the theme and writes the result to a cache in the app's cache folder. Later loads, in this run or the next, read the cache. The cache key covers the JSON and every image, so editing either recompiles by itself. The cache is always safe to delete.

`loadThemeAny` is async and reads files, so the project lists the `fs` system and grants the `fs` permission.

```ts
import { Button, DEFAULT_STAGE, Panel, Screen, Theme, VARIANT_DANGER, loadThemeAny } from "willowui";

const theme: Theme = await loadThemeAny(moduleDir + "/theme.json");

const screen: Screen = new Screen();
screen.root.setTheme(theme);

const box: Panel = new Panel("box");
box.setPosition(20.0, 20.0);
box.setSize(240.0, 120.0);
screen.add(box);

const save: Button = new Button("save", "Save", "default", 16.0);
save.setPosition(16.0, 16.0);
box.addChild(save);

const discard: Button = new Button("discard", "Discard", "default", 16.0);
discard.setVariant(VARIANT_DANGER);
discard.setPosition(16.0, 64.0);
box.addChild(discard);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

The matching `thicket.json`:

```json5
{
    entry: "app.tks",
    systems: ["willow", "bitmap", "fs"],
    permissions: { fs: true },
    packages: { willowui: "../willowui-tks" },
    window: { title: "Themed", width: 800, height: 600 },
}
```

### Themes with no images

**`loadTheme(jsonText)`** compiles a theme from a string, with no file access. Use it for themes that only set colors and sizes. Nine-slice images and sprites need `loadThemeAny`. **`validateTheme(theme, names)`** throws if the theme leaves any of the named widgets unconfigured, which is a cheap check to run at startup.

This runs in a console program, so you can try theme values without a window:

```ts
import { Theme, loadTheme, validateTheme, VARIANT_PRIMARY, VARIANT_DANGER, STATE_DEFAULT } from "willowui";

const JSON_TEXT: string = `{
    "colors": { "ink": "#EEEEEE", "red": "#CC3333", "redHover": "#EE4444" },
    "components": {
        "_": { "borderWidth": 1, "cornerRadius": 4 },
        "button": {
            "primary": { "textColor": { "default": "$ink" }, "cornerRadius": 6 },
            "danger": { "backgroundColor": { "default": "$red", "hover": "$redHover" } }
        }
    }
}`;

const theme: Theme = loadTheme(JSON_TEXT);
console.log("primary corner " + theme.button.group(VARIANT_PRIMARY).cornerRadius);
console.log("danger corner " + theme.button.group(VARIANT_DANGER).cornerRadius);
console.log("danger border " + theme.button.group(VARIANT_DANGER).borderWidth);
console.log("primary text " + theme.button.group(VARIANT_PRIMARY).textColor.resolve(STATE_DEFAULT).toHex());
try {
    validateTheme(theme, ["button", "slider"]);
} catch (e) {
    console.log((e as Error).message);
}
```

Output:

```text
primary corner 6
danger corner 4
danger border 1
primary text #EEEEEEFF
theme: missing configs: slider
```

The danger button has no `cornerRadius` of its own, so it gets 4 from `_`. The primary button sets 6, which wins.

## Nine-slice backgrounds

A nine-slice image keeps its corners at their real size and stretches only the edges and the middle. That is how one small rounded-rectangle PNG becomes a button of any width.

Declare the image under `nine-grids`, then use its name in a `backgroundGrid` property:

```json
{
    "components": {
        "button": {
            "primary": {
                "backgroundGrid": { "default": "button_up", "hover": "button_up", "active": "button_down" },
                "textColor": { "default": "#EEEEEE" }
            }
        }
    },
    "nine-grids": {
        "button_up": {
            "source": "buttons.png",
            "region": { "x": 0, "y": 0, "width": 48, "height": 48 },
            "innerRegion": { "x": 8, "y": 8, "width": 32, "height": 32 },
            "auto-slice": { "top": 8, "right": 8, "bottom": 8, "left": 8 }
        },
        "button_down": {
            "source": "buttons.png",
            "region": { "x": 48, "y": 0, "width": 48, "height": 48 },
            "innerRegion": "auto",
            "auto-slice": { "top": 8, "right": 8, "bottom": 8, "left": 8 }
        }
    }
}
```

| Field | Required | Meaning |
|---|---|---|
| `source` | yes | The image file, relative to the theme file. |
| `region` | no | The part of `source` to use, so several grids can share one sheet. Without it, the whole image is used. |
| `innerRegion` | yes | The content rectangle, or the string `"auto"` to derive it from `auto-slice`. |
| `auto-slice` | one of these two | The border widths: `top`, `right`, `bottom`, `left`. |
| `slices` | one of these two | The same, given as `topLeftCorner` and `bottomRightCorner` sizes (`width`, `height`). |

A grid must have exactly one of `auto-slice` and `slices`; the compiler rejects both or neither.

**Sprites** cut icons out of a sheet: `"sprites": { "close": { "src": "icons.png", "x": 0, "y": 0, "w": 16, "h": 16 } }`. `w` and `h` must not be zero.

## Compile ahead with themec

When you ship, compile each theme into one `.theme` file. It packs every image into one atlas, so the game loads one file and compiles nothing at startup. `loadThemeAny` reads it directly.

willowui provides the compiler as a tool. Run it from a project that lists the willowui package:

```sh
thicket tool themec themes/forest -o assets/forest.theme
thicket tool themec coverage themes/forest/theme.json
```

| Command | Does |
|---|---|
| `themec <theme-dir>` | Reads `<theme-dir>/theme.json` and the images it names, and writes `<theme-dir>.theme`. |
| `-o <file>` | Writes the compiled theme to `<file>` instead. |
| `--glyphs <png>` | Uses another default glyph sheet. |
| `themec coverage <theme.json or dir>` | Lists `$color` names that are used but not defined, and widgets the theme does not configure. |

Then load the compiled file the same way: `await loadThemeAny(moduleDir + "/assets/forest.theme")`.

## See also

- [Variants and inline themes](../xml/themes.html): `variant=` in XML, your own variant names, and the `<Theme>` element.
- [Concepts](concepts.html) for how widgets, screens and the stage fit together.

---

URL: https://thicketscript.com/willowui/recipes/dialogs

# Recipe: dialogs

A dialog is a `Window` that is **modal**: while it shows, an overlay covers the screen behind it and blocks clicks there. Build it once, hide it, and show it when you need an answer.

## A confirmation dialog

`setEnterResult("yes")` and `setEscResult("no")` make Enter and Escape close the window and pass that string to the function you give `setOnResult`. Your buttons call `fireResult(key, data)` to close it the same way, so every answer lands in one place.

```ts
import { Button, DEFAULT_STAGE, DEFAULT_WINDOW_MANAGER, LAYOUT_NONE, Label, Screen, VARIANT_DANGER, Window } from "willowui";

const W: float = 800.0;
const H: float = 600.0;
const screen: Screen = new Screen();

const status: Label = new Label("status", "", "default", 14.0);
status.setPosition(20.0, 60.0);
screen.add(status);

// Build the dialog once, hidden.
const dialog: Window = new Window("confirm-quit", "Quit the game?", "default", 16.0);
dialog.setModal(true);
dialog.setMovable(false);
dialog.setResizable(false);
dialog.setCloseable(false);
dialog.setSize(360.0, 160.0);
dialog.setPosition((W - 360.0) / 2.0, (H - 160.0) / 2.0);
dialog.body.setLayout(LAYOUT_NONE);
screen.add(dialog);
DEFAULT_WINDOW_MANAGER.add(dialog);
dialog.setVisible(false);

const message: Label = new Label("message", "Unsaved progress will be lost.", "default", 14.0);
message.setPosition(16.0, 16.0);
dialog.body.addChild(message);

const yes: Button = new Button("yes", "Quit", "default", 14.0);
yes.setVariant(VARIANT_DANGER);
yes.setSize(100.0, 34.0);
yes.setPosition(130.0, 70.0);
yes.setOnClick((): void => { dialog.fireResult("yes", null); });
dialog.body.addChild(yes);

const no: Button = new Button("no", "Stay", "default", 14.0);
no.setSize(100.0, 34.0);
no.setPosition(240.0, 70.0);
no.setOnClick((): void => { dialog.fireResult("no", null); });
dialog.body.addChild(no);

dialog.setEnterResult("yes");
dialog.setEscResult("no");
// fireResult hides the window, then calls this with the key and the data.
dialog.setOnResult((answer: string, data: any): void => {
    if (answer == "yes") { System.exit(0); }
    status.setText("Still here");
});

const quit: Button = new Button("quit", "Quit...", "default", 14.0);
quit.setPosition(20.0, 20.0);
quit.setOnClick((): void => {
    dialog.setVisible(true);
    DEFAULT_WINDOW_MANAGER.focus(dialog);
});
screen.add(quit);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

Notes:

- `DEFAULT_WINDOW_MANAGER.add(dialog)` is what makes the window stack, take focus and come to the front. Do it for every window.
- `setOnModalOverlayClick(fn)` runs when the player clicks the dimmed area; `setModalOverlayColor(c)` changes its color.
- `sizeToContent()` fits the window to what is in its body, instead of a fixed `setSize`.

## Small messages: toasts

For "Game saved" and other messages that need no answer, use a toast instead of a dialog: `showToast("Game saved", VARIANT_SUCCESS, [withDuration(2.0)])`. See [Display widgets](../widgets/display.html#toast).

## See also

- [Containers](../widgets/containers.html#windows) for the rest of the `Window` options.
- [Recipe: a form](forms.html) for collecting typed values in a window.

---

URL: https://thicketscript.com/willowui/recipes/forms

# Recipe: a form

Lay the form out in XML and bind each input to a ref. `bind:value`, `bind:selected` and `bind:checked` on a plain ref name are two way, so typed values land in your refs with no code. See [Bindings and events](../xml/bindings.html#two-way-bindings).

```ts
import { Component, Controller, DEFAULT_STAGE, Ref, Screen, TemplateRegistry } from "willowui";

const TEMPLATE: string = `
<Panel layout="vbox" spacing="10" padding="20">
    <Label text="New character" fontSize="20" />
    <TwoColumnLayout leftWidth="110" gap="12" rowSpacing="8">
        <Label text="Name" />
        <TextInput bind:value="name" width="220" placeholder="Hero" />
        <Label text="Class" />
        <Select options="Warrior,Mage,Rogue" size="220,32" bind:selected="classIndex" />
        <Label text="Hardcore" />
        <Checkbox text="One life only" bind:checked="hardcore" />
    </TwoColumnLayout>
    <Button text="Create" on:click="create" bind:enabled="name != ''" />
    <Label bind:text="status" />
</Panel>`;

const CLASSES: string[] = ["Warrior", "Mage", "Rogue"];

class NewCharacter implements Controller {
    name: Ref<string> = new Ref<string>("");
    classIndex: Ref<int> = new Ref<int>(0);
    hardcore: Ref<boolean> = new Ref<boolean>(false);
    status: Ref<string> = new Ref<string>("");

    onCreate(screen: Screen): void {
        const reg: TemplateRegistry = new TemplateRegistry();
        reg.registerXML("form", TEMPLATE);
        const root: Component = reg.instantiate("form", this, screen);
        screen.add(root);
    }
    onUpdate(dt: float): void {}
    onDispose(): void {}

    lookupRef(path: string): any {
        if (path == "name") { return this.name; }
        if (path == "classIndex") { return this.classIndex; }
        if (path == "hardcore") { return this.hardcore; }
        if (path == "status") { return this.status; }
        return null;
    }
    callMethod(method: string): boolean {
        if (method == "create") {
            const mode: string = this.hardcore.peek() ? " (hardcore)" : "";
            this.status.set("Created " + this.name.peek() + " the " + CLASSES[this.classIndex.peek()] + mode);
            return true;
        }
        return false;
    }
}

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(new Screen().withController(new NewCharacter()));
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

Notes:

- `bind:enabled="name != ''"` disables the button while the name is empty. Two strings compare as text (see [Expressions](../xml/expressions.html#comparisons)).
- Validation messages fit an `InputField` (`setValidationState`, `setValidationMessage`) instead of a bare `TextInput`.

---

URL: https://thicketscript.com/willowui/recipes/lists

# Recipe: lists

`List` shows rows of data in a scrolling column. It only makes views for the rows on screen and reuses them as you scroll, so a list of thousands of entries costs about the same as a list of twenty.

The easiest way to keep a list in step with your data is to put the data in a **`ReactiveArray<ListItem>`** and call `bindItems`. After that you never touch the list: push, remove or reorder the array and the rows follow, without losing the scroll position.

## A list you can add to and remove from

```ts
import { Button, Component, DEFAULT_STAGE, Label, List, ListItem, ReactiveArray, Ref, Screen } from "willowui";

class Quest {
    title: string;
    reward: int;
    constructor(title: string, reward: int) {
        this.title = title;
        this.reward = reward;
    }
}

const screen: Screen = new Screen();

const quests: ReactiveArray<ListItem> = new ReactiveArray<ListItem>();
quests.push(new ListItem(new Quest("Find the lantern", 50)));
quests.push(new ListItem(new Quest("Clear the cellar", 120)));
quests.push(new ListItem(new Quest("Deliver the letter", 20)));

const selected: Ref<int> = new Ref<int>(-1);

const list: List = new List("quests", 32.0);
list.setPosition(20.0, 20.0);
list.setSize(320.0, 300.0);
list.setSelectable(true);
// Each row: the data is the Quest inside the ListItem.
list.setRenderItem((index: int, data: any): Component => {
    const q: Quest = data as Quest;
    return new Label("row", q.title + "  (" + q.reward + " gold)", "default", 15.0);
});
list.bindItems(quests);
list.bindSelected(selected);
screen.add(list);

const detail: Label = new Label("detail", "Pick a quest", "default", 14.0);
detail.setPosition(360.0, 20.0);
screen.add(detail);
list.setOnChange((): void => {
    const item: any = list.selectedItem();
    if (item != null) { detail.setText("Reward: " + (item as Quest).reward + " gold"); }
});

const add: Button = new Button("add", "Add quest", "default", 14.0);
add.setPosition(20.0, 340.0);
add.setOnClick((): void => {
    quests.push(new ListItem(new Quest("New quest " + (quests.length + 1), 10)));
});
screen.add(add);

const remove: Button = new Button("remove", "Abandon", "default", 14.0);
remove.setPosition(160.0, 340.0);
remove.setOnClick((): void => {
    const i: int = selected.peek();
    if (i >= 0 && i < quests.length) {
        quests.removeAt(i);
        list.clearSelection();
    }
});
screen.add(remove);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

Notes:

- `setRenderItem` gets the row index and the `ListItem`'s data, and returns the row's widget. Without it, each row shows its data as text.
- `selectedItem()` returns that same data, or `null` when nothing is selected.
- With focus on the list, Up and Down move the selection. `selectNext()`, `selectPrevious()`, `selectFirst()` and `selectLast()` do the same from code, and scroll the row into view.
- `setItems([...])` replaces everything at once and scrolls back to the top. Use it for lists you rebuild rather than edit.

## A short list in XML

For a handful of rows, a template's `ui:for` is enough. Each row's `on:` handler can pass the row's item and `index` to your controller, so one method serves every row:

```xml
<Panel layout="vbox" spacing="4">
    <Button ui:for="quest in quests" bind:text="quest.title" on:click="abandon(quest, index)" />
</Panel>
```

Clicking a row calls `callMethod("abandon", [quest, index])`. `ui:for` builds a full widget per row and rebuilds them all when the array changes, so switch to a `List` for long lists. [Directives](../xml/directives.html#ui-for) has a complete controller, and [Bindings and events](../xml/bindings.html#on) covers handler arguments.

## Other list widgets

| Widget | Use it for |
|---|---|
| `TileList` | A grid of tiles, such as an inventory or a level select. Same `bindItems` and `setRenderItem`. |
| `SortableList` | A list the player reorders by dragging or with the keyboard. |
| `TreeList`, `SortableTreeList` | Nested items that open and close. |
| `DataTable`, `TreeTable` | Rows with columns, sortable by column. |

See [Containers](../widgets/containers.html) and [Composites](../widgets/composites.html). In XML, `<List>` takes `itemHeight`, `selected` and `size`; give it its rows from code with `bindItems`, after finding it with `screen.findByName` (see [Bindings and events](../xml/bindings.html)).

## See also

- [Reactive state](../guide/reactive-state.html) for `ReactiveArray` and `Ref`.

---

URL: https://thicketscript.com/willowui/recipes/menus

# Recipe: menus

Two kinds of menu come up in most games: a **main menu** (a column of big buttons) and, in tools and editors, a **menu bar** with dropdowns.

## A main menu

Put the buttons in a panel with a vertical layout. Because the parent is a VBox, the Up and Down arrows already move focus between the buttons (see [spatial navigation](../guide/input-and-focus.html#arrow-keys-spatial-navigation)). Focus the first button so the keyboard works from the first frame, and give Escape a global bind.

```ts
import { Button, DEFAULT_FOCUS_MANAGER, DEFAULT_STAGE, Insets, LAYOUT_VBOX, Label, MOD_NONE, Panel, Screen, key } from "willowui";

const screen: Screen = new Screen();

const menu: Panel = new Panel("main-menu");
menu.setLayout(LAYOUT_VBOX);
menu.setSpacing(10.0);
menu.padding = new Insets(20.0, 20.0, 20.0, 20.0);
menu.setPosition(280.0, 140.0);
menu.setSize(240.0, 260.0);
screen.add(menu);

const status: Label = new Label("status", "", "default", 14.0);
status.setPosition(280.0, 420.0);
screen.add(status);

function entry(name: string, text: string, action: Function): Button {
    const b: Button = new Button(name, text, "default", 18.0);
    b.setSize(200.0, 44.0);
    b.setOnClick((): void => { action(); });
    menu.addChild(b);
    return b;
}

const play: Button = entry("play", "Play", (): void => { status.setText("Starting..."); });
entry("continue", "Continue", (): void => { status.setText("Loading the last save"); }).setEnabled(false);
entry("settings", "Settings", (): void => { status.setText("Opening settings"); });
entry("quit", "Quit", (): void => { System.exit(0); });
menu.updateLayout();

DEFAULT_FOCUS_MANAGER.setFocus(play);
DEFAULT_FOCUS_MANAGER.bind(key(Key.ESCAPE, MOD_NONE), (): boolean => {
    status.setText("Press Quit to leave");
    return true;
});

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

Notes:

- The disabled Continue button is skipped by the arrows and by Tab, so there is no dead stop.
- The theme's `focusColor` draws the focus ring. See [Theming](../guide/theming.html).

## A menu bar

`MenuBar` takes a list of `MenuBarEntry(label, items)`. Each item is a `MenuItem(label, onSelect)`. An item can also be:

| Field | Effect |
|---|---|
| `disabled = true` | Shown greyed out; cannot be picked. |
| `separator = true` | A thin divider. The label and function are ignored. |
| `shortcut = "Ctrl+S"` | A hint drawn on the right. It is display only: bind the key yourself with `DEFAULT_FOCUS_MANAGER.bind`. |

```ts
import { DEFAULT_STAGE, Label, MenuBar, MenuBarEntry, MenuItem, Screen } from "willowui";

const screen: Screen = new Screen();
const status: Label = new Label("status", "Pick something from the menu", "default", 14.0);
status.setPosition(20.0, 60.0);
screen.add(status);

function item(label: string, shortcut: string): MenuItem {
    const m: MenuItem = new MenuItem(label, (): void => { status.setText("Picked " + label); });
    m.shortcut = shortcut;
    return m;
}
function separator(): MenuItem {
    const m: MenuItem = new MenuItem("", null);
    m.separator = true;
    return m;
}

const exportItem: MenuItem = item("Export", "");
exportItem.disabled = true;

const bar: MenuBar = new MenuBar("menu-bar", "default", 14.0);
bar.setSize(800.0, 32.0);
bar.setEntries([
    new MenuBarEntry("File", [item("New map", "Ctrl+N"), item("Open", "Ctrl+O"), separator(), exportItem]),
    new MenuBarEntry("Edit", [item("Undo", "Ctrl+Z"), item("Redo", "Ctrl+Y")]),
]);
screen.add(bar);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

Once a dropdown is open, the arrow keys move through it and Escape closes it. `setOnMenuOpen(fn)` gets the entry index; `setOnMenuClose(fn)` fires when it closes.

## A right-click menu

`ContextMenu(family, size)` is the same list as a popup at any point: `setItems([...])`, then `showAt(x, y)` from a click handler, and `hide()` to close it.

## See also

- [Input and focus](../guide/input-and-focus.html) for how the arrows and key binds work.
- [Recipe: dialogs](dialogs.html) for a "Quit the game?" confirmation.

---

URL: https://thicketscript.com/willowui/recipes/settings

# Recipe: a settings screen

A settings screen is a list of labelled controls, each tied to one setting. Keep each setting in a `Ref`, bind the control to it two ways with `bindValue` or `bindSelected`, and the rest of the game reads the refs. `TwoColumnLayout` lines the labels up on the left and the controls on the right.

```ts
import {
    DEFAULT_STAGE, KeyBinding, KeybindInput, Label, OptionRotator, Ref, Screen, Slider, Toggle, TwoColumnLayout,
} from "willowui";

class Settings {
    music: Ref<float> = new Ref<float>(0.8);
    effects: Ref<float> = new Ref<float>(1.0);
    fullscreen: Ref<boolean> = new Ref<boolean>(false);
    difficulty: Ref<int> = new Ref<int>(1);
    jumpKey: Ref<KeyBinding> = new Ref<KeyBinding>(KeyBinding.ofKey("Space"));
}

const settings: Settings = new Settings();
const screen: Screen = new Screen();

const title: Label = new Label("title", "Settings", "default", 22.0);
title.setPosition(40.0, 24.0);
screen.add(title);

const form: TwoColumnLayout = new TwoColumnLayout("settings");
form.setPosition(40.0, 70.0);
form.setSize(460.0, 260.0);
screen.add(form);

function label(text: string): Label {
    return new Label("label", text, "default", 15.0);
}

const music: Slider = new Slider("music");
music.setRange(0.0, 1.0);
music.setSize(220.0, 24.0);
music.bindValue(settings.music);
form.addRow(label("Music volume"), music);

const effects: Slider = new Slider("effects");
effects.setRange(0.0, 1.0);
effects.setSize(220.0, 24.0);
effects.bindValue(settings.effects);
form.addRow(label("Effects volume"), effects);

const fullscreen: Toggle = new Toggle("fullscreen");
fullscreen.bindValue(settings.fullscreen);
form.addRow(label("Fullscreen"), fullscreen);

const difficulty: OptionRotator = new OptionRotator("difficulty", ["Story", "Normal", "Hard"], "default", 15.0);
difficulty.setSize(220.0, 32.0);
difficulty.bindSelected(settings.difficulty);
form.addRow(label("Difficulty"), difficulty);

const jump: KeybindInput = new KeybindInput("jump", "default", 15.0);
jump.setSize(220.0, 32.0);
jump.bindValue(settings.jumpKey);
form.addRow(label("Jump"), jump);

// The rest of the game reacts to the refs, not to the widgets.
settings.music.on((now: any, before: any): void => {
    console.log("music volume is now " + now);
});

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

Notes:

- **Two-way binding.** Each `bindValue` or `bindSelected` call makes the widget show the ref's value and write the player's changes back into it. Setting a ref from code (loading saved settings, a "Reset to defaults" button) moves the widget too.
- **Key bindings.** A `KeybindInput` waits for the next key press when clicked and stores it as a `KeyBinding`. `setOnConflict(fn)` lets you reject a key that is already taken (return `false`). `setCombosEnabled(true)` accepts combinations such as Ctrl+S.
- **Choices.** `OptionRotator` steps through options with left and right arrows, which suits a gamepad. `Select` opens a dropdown and binds the same way with `bindSelected`.
- **Saving.** Read the refs with `peek()` when you save, and set them when you load. Nothing else needs to change.

## In XML

`bind:value`, `bind:checked`, `bind:selected` and `bind:rawValue` are two way when the expression is just the name of a ref, so a template can hold the whole settings screen: `<Slider bind:value="volume" />` moves with the ref and writes the player's drags back into it. [Recipe: a form](forms.html) shows it end to end.

## See also

- [Reactive state](../guide/reactive-state.html) for refs, `on` and `computed`.
- [Interactive widgets](../widgets/interactive.html) for every option of `Slider`, `Toggle`, `OptionRotator`, `Select` and `KeybindInput`.

---

URL: https://thicketscript.com/willowui/reference/composites

# Composites: API

This page is generated from the willowui source. It lists each public class with its constructor, its setter-style methods and its callback fields. The guide page for this family explains how to use them. Methods the generator skips (internal handlers, layout and draw steps) are still reachable but are not part of the everyday surface.

- [CellCoord](#cellcoord)
- [SortKey](#sortkey)
- [DataTableColumn](#datatablecolumn)
- [SelectionColumnState](#selectioncolumnstate)
- [DataTable](#datatable)
- [GradientEditor](#gradienteditor)

## CellCoord

Source: `src/widgets/composites/datatable.tks`.

```ts
new CellCoord(row: int, col: int)
```

## SortKey

Source: `src/widgets/composites/datatable.tks`.

```ts
new SortKey(colKey: string, dir: int)
```

## DataTableColumn

Source: `src/widgets/composites/datatable.tks`.

```ts
new DataTableColumn(key: string, header: string)
```

| Method | Returns | Notes |
|---|---|---|
| `isHidden()` | `boolean` |  |

## SelectionColumnState

Source: `src/widgets/composites/datatable.tks`.

Shared mutable state of a SelectionColumn, stored in DataTableColumn.internal so the table can wire itself in when the column is added.

```ts
new SelectionColumnState(visible: Ref<boolean>, multi: Ref<boolean>)
```

## DataTable

Source: `src/widgets/composites/datatable.tks`. Extends `Component`.

```ts
new DataTable(name: string, rowHeight: float)
```

Callback fields: `onSort`, `onMultiSort`, `onCellClick`, `onCellDoubleClick`, `onSelectionChanged`.

| Method | Returns | Notes |
|---|---|---|
| `addColumn(col: DataTableColumn)` | `void` |  |
| `setColumns(cols: DataTableColumn[])` | `void` | Replaces all columns. |
| `setItems(items: any[])` | `void` | Replaces the data and refreshes the display. |
| `bindItems(arr: ReactiveArray&lt;any&gt; \| null)` | `void` | Binds to a ReactiveArray: array changes are reflected on the next frame. Pass null to detach. |
| `setRowHeight(h: float)` | `void` |  |
| `setHeaderHeight(h: float)` | `void` |  |
| `setShowHeader(v: boolean)` | `void` |  |
| `setShowScrollBar(v: boolean)` | `void` |  |
| `setZebraStriping(v: boolean)` | `void` |  |
| `setShowColumnDividers(v: boolean)` | `void` |  |
| `setShowRowDividers(v: boolean)` | `void` |  |
| `setScrollMode(m: int)` | `void` |  |
| `setFont(family: string, size: float)` | `void` | The font family (registered name) and size for header text and default cell labels. Call before setItems / bindItems so cells pick it up. |
| `setSelectionMode(m: int)` | `void` |  |
| `setRowClickSelects(v: boolean)` | `void` |  |
| `setOnSortScroll(v: int)` | `void` |  |
| `setFilterFunc(fn: Function \| null)` | `void` | A function to filter visible rows; null clears it. The scroll position resets to the top. |
| `bindSearchFilter(ref: Ref&lt;string&gt;)` | `void` | The search text follows the ref; searchable columns with a searchValue are matched. |
| `bindSearchInput(ti: TextInput)` | `void` | Binds a TextInput's value to the search filter. |
| `setColumnFilter(colKey: string, values: string[])` | `void` | Only rows whose column searchValue is in `values` are shown. |
| `clearColumnFilter(colKey: string)` | `void` |  |
| `resetFiltersAndSort()` | `void` | Clears sort keys, filters, search and column filters, scrolls to top and rebuilds. |
| `setOnCellClick(fn: Function \| null)` | `void` |  |
| `setOnCellDoubleClick(fn: Function \| null)` | `void` |  |
| `setOnSelectionChanged(fn: Function \| null)` | `void` |  |
| `setOnSort(fn: Function \| null)` | `void` | When registered, the table does NOT sort internally: the caller owns sort logic. |
| `selectedIndexesCopy()` | `int[]` |  |
| `bindSelectedIndexes(getFn: Function \| null, setFn: Function \| null)` | `void` | Selection follows external getter / setter functions. |
| `setSelectedIndexes(indexes: int[])` | `void` | Replaces the selection from external code. |
| `clearSelection()` | `void` |  |
| `selectRow(index: int)` | `void` |  |
| `toggleRowSelection(index: int)` | `void` |  |
| `selectAll()` | `void` | Multi-selection mode only; no-op otherwise. |
| `isSelected(dataIdx: int)` | `boolean` |  |
| `scrollToRow(index: int)` | `void` | Scrolls so the given original-array index is visible. |
| `scrollToTop()` | `void` |  |
| `scrollToBottom()` | `void` |  |
| `bindScrollPos(ref: Ref&lt;float&gt; \| null)` | `void` | The scroll position follows the ref (Go never wrote back to it). |
| `setSortedColumn(key: string, dir: int)` | `void` | Sets a single sort column and direction; clears any multi-column sort. |
| `sortedColumnKey()` | `string` | The first sort column key and direction; "" and SORT_DIR_NONE when unsorted. |
| `sortedColumnDir()` | `int` |  |
| `setSortKeys(keys: SortKey[])` | `void` |  |
| `getSortKeys()` | `SortKey[]` |  |
| `setDefaultSort(key: string, dir: int)` | `void` | The default sort applied when sortKeys is empty (on setItems / bindItems). |
| `setOnMultiSort(fn: Function \| null)` | `void` |  |
| `rebuild()` | `void` | A full re-layout on the next frame (recreates all row slots). |
| `refresh()` | `void` | A slot rebuild on the next frame. |
| `setEmptyComponent(comp: Component \| null)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |
| `sortKeyIndex(colKey: string)` | `int` |  |
| `sortKeyDir(colKey: string)` | `int` |  |
| `hasSelectionColumn()` | `boolean` |  |
| `openColumnFilterPopover(col: DataTableColumn, colIndex: int)` | `void` | Opens a popover with a checkbox for each unique value in the column. |
| `closeFilterPopover()` | `void` | Closes the open filter popover, if any. |

## GradientEditor

Source: `src/widgets/composites/gradienteditor.tks`. Extends `Component`.

```ts
new GradientEditor(name: string, family: string, displaySize: float)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `setValue(g: Gradient)` | `void` | Sets the current gradient without firing onChange. |
| `getValue()` | `Gradient` | A copy of the current gradient. |
| `bindValue(ref: Ref&lt;Gradient&gt;)` | `void` | The editor writes back to the ref on every change; external writes update the editor. |
| `setOnChange(fn: Function \| null)` | `void` | Invoked on every edit (colour change or mode switch). |
| `setAllowedModes(modes: int[])` | `void` | Restricts which modes appear in the selector. If the current mode is not listed the editor switches to the first allowed mode. |
| `setShowModeSelector(show: boolean)` | `void` | Shows or hides the H \| V \| 4-corner selector row. |
| `setSize(w: float, h: float)` | `void` |  |

---

URL: https://thicketscript.com/willowui/reference/containers

# Containers: API

This page is generated from the willowui source. It lists each public class with its constructor, its setter-style methods and its callback fields. The guide page for this family explains how to use them. Methods the generator skips (internal handlers, layout and draw steps) are still reachable but are not part of the everyday surface.

- [AccordionSection](#accordionsection)
- [Accordion](#accordion)
- [AnchorLayout](#anchorlayout)
- [ListItem](#listitem)
- [List](#list)
- [NavDrawer](#navdrawer)
- [SortableList](#sortablelist)
- [SortableTreeItem](#sortabletreeitem)
- [SortableTreeList](#sortabletreelist)
- [TabBar](#tabbar)
- [TileList](#tilelist)
- [TreeNode](#treenode)
- [ReactiveTreeNode](#reactivetreenode)
- [TreeList](#treelist)
- [TableColumn](#tablecolumn)
- [TreeTableRow](#treetablerow)
- [TreeTable](#treetable)
- [TwoColumnLayout](#twocolumnlayout)
- [Window](#window)
- [WindowManager](#windowmanager)

## AccordionSection

Source: `src/widgets/containers/accordion.tks`.

A section to add (Go AccordionSection).

```ts
new AccordionSection(id: string, label: string, icon: TextureRegion | null, content: Component | null)
```

## Accordion

Source: `src/widgets/containers/accordion.tks`. Extends `Component`.

```ts
new Accordion(name: string)
```

Callback fields: `onToggle`.

| Method | Returns | Notes |
|---|---|---|
| `setFont(family: string, size: float)` | `void` | The font family and size for header labels; sections added before this have no label. |
| `addSection(section: AccordionSection)` | `Accordion` |  |
| `removeSection(id: string)` | `void` |  |
| `open(id: string)` | `void` |  |
| `close(id: string)` | `void` |  |
| `toggle(id: string)` | `void` |  |
| `setExpanded(id: string, v: boolean)` | `void` |  |
| `isExpanded(id: string)` | `boolean` |  |
| `setExclusive(v: boolean)` | `void` |  |
| `setAnimated(v: boolean)` | `void` |  |
| `setOnToggle(fn: Function \| null)` | `void` |  |
| `bindExpanded(ref: Ref&lt;string&gt;)` | `void` | Follow a Ref&lt;string&gt; holding the expanded section id ("" closes all). |
| `expandedID()` | `string` | The first expanded section id, or "". |
| `setSize(w: float, h: float)` | `void` |  |
| `applyThemeColors()` | `void` |  |

## AnchorLayout

Source: `src/widgets/containers/anchorlayout.tks`. Extends `Panel`.

```ts
new AnchorLayout(name: string)
```

## ListItem

Source: `src/widgets/containers/list.tks`.

Wraps arbitrary data for use in a List (Go ListItem).

```ts
new ListItem(data: any)
```

## List

Source: `src/widgets/containers/list.tks`. Extends `Component`.

```ts
new List(name: string, itemHeight: float)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `applyThemeColors()` | `void` |  |
| `setItems(items: ListItem[])` | `void` | Replace the data and refresh the visible items; scrolls back to the top. |
| `bindItems(arr: ReactiveArray&lt;ListItem&gt; \| null)` | `void` | Follow a ReactiveArray&lt;ListItem&gt;: every mutation resyncs the items and the pool without resetting the scroll position. Pass null to detach. |
| `setRenderItem(fn: Function \| null)` | `void` | The factory that creates the Component for an item: (index: int, data: any) =&gt; Component \| null. |
| `getSelected()` | `int` |  |
| `setSelected(idx: int)` | `void` |  |
| `bindSelected(ref: Ref&lt;int&gt;)` | `void` |  |
| `selectedRef()` | `Ref&lt;int&gt;` |  |
| `selectedItem()` | `any` | The data of the selected item, or null. |
| `clearSelection()` | `void` |  |
| `selectNext()` | `void` | Select the next item (the first when nothing is selected), scrolled into view. |
| `selectPrevious()` | `void` | Select the previous item (the last when nothing is selected). |
| `selectFirst()` | `void` |  |
| `selectLast()` | `void` |  |
| `scrollToSelection()` | `void` |  |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setSelectable(enabled: boolean)` | `void` | Enable the built-in highlight behind the selected item. |
| `isSelectable()` | `boolean` |  |
| `scrollToIndex(idx: int)` | `void` | Scroll so that item `idx` is visible. |
| `setSize(w: float, h: float)` | `void` |  |
| `setItemHeight(h: float)` | `void` | Change the row height and rebuild the visible rows (item 11472, bindable as bind:itemHeight). |

## NavDrawer

Source: `src/widgets/containers/navdrawer.tks`. Extends `Component`.

```ts
new NavDrawer(name: string)
```

Callback fields: `onOpen`, `onClose`.

| Method | Returns | Notes |
|---|---|---|
| `setContent(comp: Component \| null)` | `void` |  |
| `open()` | `void` | Slide the drawer into view. |
| `close()` | `void` | Slide the drawer out of view. |
| `toggle()` | `void` |  |
| `isOpen()` | `boolean` |  |
| `setPinned(v: boolean)` | `void` |  |
| `isPinned()` | `boolean` |  |
| `setDrawerAnchor(anchor: int)` | `void` |  |
| `setWidth(w: float)` | `void` |  |
| `setCloseOnBackdropClick(v: boolean)` | `void` |  |
| `setOnOpen(fn: Function \| null)` | `void` |  |
| `setOnClose(fn: Function \| null)` | `void` |  |
| `bindOpen(ref: Ref&lt;boolean&gt;)` | `void` | Bind the open state to a Ref: writes open or close the drawer, and user interaction writes the Ref. |
| `setSize(w: float, h: float)` | `void` | The overall container size (typically the full screen). |
| `setAnimationDuration(seconds: float)` | `void` |  |
| `applyThemeColors()` | `void` |  |

## SortableList

Source: `src/widgets/containers/sortablelist.tks`. Extends `Component`.

```ts
new SortableList(name: string, itemHeight: float)
```

Callback fields: `onChange`, `onReorder`, `onMoveDenied`.

| Method | Returns | Notes |
|---|---|---|
| `applyThemeColors()` | `void` |  |
| `setRenderItem(fn: Function \| null)` | `void` | The factory that creates the Component for an item: (index: int, data: any) =&gt; Component \| null. |
| `setUpdateItem(fn: Function \| null)` | `void` |  |
| `getSelected()` | `int` |  |
| `setSelected(idx: int)` | `void` |  |
| `selectedItem()` | `any` | The data of the selected item, or null. |
| `bindSelected(ref: Ref&lt;int&gt;)` | `void` |  |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setDragEnabled(v: boolean)` | `void` |  |
| `setKeyboardReorderEnabled(v: boolean)` | `void` |  |
| `setShowHandles(v: boolean)` | `void` |  |
| `setHandleSide(side: int)` | `void` |  |
| `setOnReorder(fn: Function \| null)` | `void` |  |
| `setOnMoveDenied(fn: Function \| null)` | `void` |  |
| `moveItem(src: int, dst: int)` | `void` | Move an item from one index to another; the selection follows the moved item and adjusts when an unselected item moves past it. |
| `moveSelectedUp()` | `void` |  |
| `moveSelectedDown()` | `void` |  |
| `scrollToIndex(idx: int)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |
| `rebuild()` | `void` | Clear and recreate every row component. |

## SortableTreeItem

Source: `src/widgets/containers/sortabletreelist.tks`.

A node in a sortable tree (Go SortableTreeItem). `depth` is computed from `parentId`.

```ts
new SortableTreeItem(id: string, parentId: string, label: string)
```

## SortableTreeList

Source: `src/widgets/containers/sortabletreelist.tks`. Extends `Component`.

```ts
new SortableTreeList(name: string, family: string, displaySize: float)
```

Callback fields: `onChange`, `onReorder`.

| Method | Returns | Notes |
|---|---|---|
| `applyThemeColors()` | `void` |  |
| `setItems(items: SortableTreeItem[])` | `void` |  |
| `getItems()` | `SortableTreeItem[]` | A copy of the current items. |
| `setAllowReparent(v: boolean)` | `void` |  |
| `setAllowCrossLevel(v: boolean)` | `void` |  |
| `setOnReorder(fn: Function \| null)` | `void` |  |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setExpanded(id: string, v: boolean)` | `void` |  |
| `isExpanded(id: string)` | `boolean` |  |
| `expandAll()` | `void` |  |
| `collapseAll()` | `void` |  |
| `getSelected()` | `int` |  |
| `setSelected(idx: int)` | `void` |  |
| `bindSelected(ref: Ref&lt;int&gt;)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |
| `moveSelectedUp()` | `void` |  |
| `moveSelectedDown()` | `void` |  |

## TabBar

Source: `src/widgets/containers/tabs.tks`. Extends `Component`.

```ts
new TabBar(name: string, family: string, displaySize: float)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `applyThemeColors()` | `void` |  |
| `addTab(label: string, content: Component \| null)` | `int` | Add a tab with a label and a content panel (may be null); returns the tab index. |
| `addTabPage(label: string, layout: int, spacing: float, padding: Insets)` | `Component` | A tab whose content is a new page sized to the tab body; returns the page (its index is tabCount() - 1). |
| `removeTab(index: int)` | `void` |  |
| `getSelected()` | `int` |  |
| `setSelected(idx: int)` | `void` |  |
| `bindSelected(ref: Ref&lt;int&gt;)` | `void` | Follow a Ref&lt;int&gt;; the current value applies now and later writes follow at the frame boundary. |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |
| `getOverflowMode()` | `int` |  |
| `scrollOffset()` | `float` | The scroll offset in pixels; always 0 in clip mode. |
| `setOverflowMode(mode: int)` | `void` |  |
| `scrollToTab(idx: int)` | `void` | Scroll so the tab at idx is fully visible. No-op in clip mode. |
| `scrollByOneTab(dir: int)` | `void` |  |

## TileList

Source: `src/widgets/containers/tilelist.tks`. Extends `Component`.

```ts
new TileList(name: string, tileW: float, tileH: float)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `applyThemeColors()` | `void` |  |
| `setItems(items: ListItem[])` | `void` | Replace the data and refresh. With setUpdateItem configured, pooled components are updated in place instead of disposed and recreated. |
| `setUpdateItem(fn: Function \| null)` | `void` |  |
| `bindItems(arr: ReactiveArray&lt;ListItem&gt; \| null)` | `void` | Follow a ReactiveArray&lt;ListItem&gt;; any change resyncs the pool and keeps the scroll position. |
| `setColumns(n: int)` | `void` |  |
| `setRenderItem(fn: Function \| null)` | `void` |  |
| `getSelected()` | `int` |  |
| `setSelected(idx: int)` | `void` |  |
| `bindSelected(ref: Ref&lt;int&gt;)` | `void` |  |
| `selectedRef()` | `Ref&lt;int&gt;` |  |
| `selectedItem()` | `any` |  |
| `clearSelection()` | `void` |  |
| `selectNext()` | `void` |  |
| `selectPrevious()` | `void` |  |
| `selectFirst()` | `void` |  |
| `selectLast()` | `void` |  |
| `scrollToIndex(idx: int)` | `void` | Scroll so the row holding tile `idx` is visible. |
| `scrollToSelection()` | `void` |  |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setSelectable(enabled: boolean)` | `void` |  |
| `isSelectable()` | `boolean` |  |
| `setSize(w: float, h: float)` | `void` |  |

## TreeNode

Source: `src/widgets/containers/treelist.tks`.

A node in a hierarchical tree (Go TreeNode).

```ts
new TreeNode(data: any, children: TreeNode[])
```

## ReactiveTreeNode

Source: `src/widgets/containers/treelist.tks`.

A tree node whose children are a reactive array (Go ReactiveTreeNode). Mutations anywhere in the subtree reach a TreeList bound with bindRoots.

```ts
new ReactiveTreeNode(data: any)
```

## TreeList

Source: `src/widgets/containers/treelist.tks`. Extends `Component`.

```ts
new TreeList(name: string, itemHeight: float)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `applyThemeColors()` | `void` |  |
| `setSelectable(enabled: boolean)` | `void` | Built-in selection: a click selects the row and a highlight bar is shown. |
| `isSelectable()` | `boolean` |  |
| `getSelected()` | `TreeNode \| null` |  |
| `selectedRef()` | `Ref&lt;TreeNode \| null&gt;` |  |
| `setSelected(node: TreeNode \| null)` | `void` |  |
| `clearSelection()` | `void` |  |
| `bindSelected(ref: Ref&lt;TreeNode \| null&gt;)` | `void` |  |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setLeafOnlySelection(enabled: boolean)` | `void` | Only leaves can be selected; parents stay clickable for expand and collapse. No effect while not selectable. |
| `setRoots(roots: TreeNode[])` | `void` |  |
| `bindRoots(arr: ReactiveArray&lt;ReactiveTreeNode&gt; \| null)` | `void` | Follow a ReactiveArray&lt;ReactiveTreeNode&gt;. A change anywhere in the subtree re-snapshots the tree without resetting the scroll position or the expansion state. Pass null to detach. |
| `setToggleIcons(expand: any \| null, collapse: any \| null)` | `void` | Custom glyphs for the toggle buttons built by newTreeToggle (null keeps the default). |
| `setRenderItem(fn: Function \| null)` | `void` |  |
| `setDefaultTextRenderer(family: string, displaySize: float, rowW: float, rowH: float)` | `void` | The standard row: depth indent, a toggle (or a spacer for leaves) and a label. Each node's data is a string. Clicking a parent row toggles it. |
| `expand(node: TreeNode \| null)` | `void` |  |
| `collapse(node: TreeNode \| null)` | `void` |  |
| `toggle(node: TreeNode)` | `void` |  |
| `expandAll()` | `void` |  |
| `collapseAll()` | `void` |  |
| `isExpanded(node: TreeNode)` | `boolean` |  |
| `moveSelection(delta: int)` | `boolean` | Move the selection `delta` rows (+1 down, -1 up); false when there is no such row. |
| `setSize(w: float, h: float)` | `void` |  |
| `toggleButton(name: string, node: TreeNode)` | `IconButton \| null` | A ready-made IconButton that expands or collapses `node` in `tl`; null for a leaf. The button uses the Custom1 variant and tints its glyph white by default and the theme text colour on hover or press, like the window close button. Glyph resolution: per-tree override, then the theme icon, then the chevrons. |

## TableColumn

Source: `src/widgets/containers/treetable.tks`.

A column of a TreeTable (Go TableColumn).

```ts
new TableColumn(key: string, label: string, width: float, sortable: boolean)
```

## TreeTableRow

Source: `src/widgets/containers/treetable.tks`.

A row of the hierarchy (Go TreeTableRow). `parentId` is set by the table when it flattens the nested `children`; "" is a root row.

```ts
new TreeTableRow(id: string, cells: Map<string, string>, children: TreeTableRow[])
```

## TreeTable

Source: `src/widgets/containers/treetable.tks`. Extends `Component`.

```ts
new TreeTable(name: string, family: string, displaySize: float)
```

Callback fields: `onRowClick`, `onRowExpand`.

| Method | Returns | Notes |
|---|---|---|
| `applyThemeColors()` | `void` |  |
| `setColumns(cols: TableColumn[])` | `void` |  |
| `getColumns()` | `TableColumn[]` | A copy of the current column definitions. |
| `setRows(rows: TreeTableRow[])` | `void` | Rows may be nested through `children`. |
| `getRows()` | `TreeTableRow[]` |  |
| `setSortColumn(key: string, dir: int)` | `void` |  |
| `expandAll()` | `void` |  |
| `collapseAll()` | `void` |  |
| `setExpanded(id: string, v: boolean)` | `void` |  |
| `isExpanded(id: string)` | `boolean` |  |
| `setOnRowClick(fn: Function \| null)` | `void` |  |
| `setOnRowExpand(fn: Function \| null)` | `void` |  |
| `getSelected()` | `int` |  |
| `setSelected(idx: int)` | `void` | Select by flat index. Does NOT fire onRowClick. |
| `setSize(w: float, h: float)` | `void` |  |

## TwoColumnLayout

Source: `src/widgets/containers/twocolumnlayout.tks`. Extends `Panel`.

```ts
new TwoColumnLayout(name: string)
```

| Method | Returns | Notes |
|---|---|---|
| `addRow(left: Component \| null, right: Component \| null)` | `void` | Add a row. With a null `right`, `left` spans both columns (clear:both). |
| `removeRow(left: Component \| null)` | `void` | Remove the row whose left (or spanning) child is `left`, detaching its components. |
| `sizeToContent()` | `void` | Resize to tightly wrap all rows; children must have their sizes set first. |

## Window

Source: `src/widgets/containers/window.tks`. Extends `Component`.

```ts
new Window(name: string, title: string, family: string, displaySize: float)
```

Callback fields: `onClose`, `onResult`.

| Method | Returns | Notes |
|---|---|---|
| `applyThemeColors()` | `void` |  |
| `setActive(active: boolean)` | `void` |  |
| `setTitle(t: string)` | `void` |  |
| `setSize(width: float, height: float)` | `void` |  |
| `setTitleBarHeight(h: float)` | `void` |  |
| `setMinSize(minW: float, minH: float)` | `void` |  |
| `setMinWidth(v: float)` | `void` |  |
| `setMinHeight(v: float)` | `void` |  |
| `sizeToContent()` | `void` | Fit the body to its content and size the window to match. |
| `setResizable(v: boolean)` | `void` |  |
| `setMovable(v: boolean)` | `void` |  |
| `isMovable()` | `boolean` |  |
| `setModal(v: boolean)` | `void` |  |
| `isModal()` | `boolean` |  |
| `setModalOverlayColor(c: Color)` | `void` |  |
| `setOnModalOverlayClick(fn: Function \| null)` | `void` |  |
| `setVisible(v: boolean)` | `void` |  |
| `setCloseIcon(img: any)` | `void` |  |
| `setCloseable(v: boolean)` | `void` |  |
| `setOnClose(fn: Function \| null)` | `void` |  |
| `setOnResult(fn: Function \| null)` | `void` |  |
| `setEscResult(key: string)` | `void` |  |
| `setEnterResult(key: string)` | `void` |  |
| `close()` | `void` |  |

## WindowManager

Source: `src/widgets/containers/window.tks`.

Stacks windows by z order and tracks the active (foremost) one (Go WindowManager), extended with independent layer ownership, suspension, and layer focus [H 2026-10-04].

| Method | Returns | Notes |
|---|---|---|
| `add(w: Window)` | `void` | Adds a window to this layer, transferring it from another layer if necessary. The normal visible state keeps Go's activate-on-add behaviour; a suspended layer records and hides the new window. |
| `remove(w: Window)` | `void` | Removes a window from this layer and clears its ownership and focus state. |
| `focus(w: Window)` | `void` | Gives this layer focus and activates `w`; the window must belong to this manager. |
| `isFocused()` | `boolean` | Reports whether this layer currently owns application focus. |
| `setOnFocusChanged(fn: Function \| null)` | `void` | Registers a callback invoked with the new boolean state when layer focus changes. |
| `resume()` | `void` | Restores exactly the per-window visibility recorded by suspend and later visibility requests. |
| `isSuspended()` | `boolean` | Reports whether this layer is currently hiding and suppressing its windows. |

---

URL: https://thicketscript.com/willowui/reference/core

# Core widgets: API

This page is generated from the willowui source. It lists each public class with its constructor, its setter-style methods and its callback fields. The guide page for this family explains how to use them. Methods the generator skips (internal handlers, layout and draw steps) are still reachable but are not part of the everyday surface.

- [Component](#component)
- [Panel](#panel)
- [Label](#label)
- [Button](#button)
- [IconButton](#iconbutton)
- [Image](#image)
- [Tooltip](#tooltip)
- [TooltipManager](#tooltipmanager)
- [ScrollBar](#scrollbar)
- [ScrollPanel](#scrollpanel)
- [Screen](#screen)
- [StageManager](#stagemanager)

## Component

Source: `src/core/component.tks`.

```ts
new Component(name: string)
```

Callback fields: `onFocusChange`, `onVisualStateChange`, `onActivate`, `onLayout`, `onThemeChange`, `onTooltipShow`, `onTooltipHide`.

| Method | Returns | Notes |
|---|---|---|
| `setOnActivate(fn: Function \| null)` | `void` |  |
| `setOnEvent(name: string, fn: Function)` | `void` | Register a named handler for template on:* bindings. |
| `setZIndex(z: int)` | `void` |  |
| `setUserData(v: any)` | `void` |  |
| `getUserData()` | `any` |  |
| `setInteractable(v: boolean)` | `void` |  |
| `isInteractable()` | `boolean` |  |
| `isDisposed()` | `boolean` |  |
| `isEnabled()` | `boolean` |  |
| `isVisible()` | `boolean` |  |
| `isHovered()` | `boolean` |  |
| `isPressed()` | `boolean` |  |
| `isFocused()` | `boolean` |  |
| `hasAncestor(a: Component)` | `boolean` | True when `a` is an ancestor of this component. |
| `setHitShape(s: Rect \| null)` | `void` | The pointer hit area, in local coordinates; null leaves the node's default bounds. |
| `addRawChild(n: Node \| null)` | `void` | Add a raw willow node (a Sprite, Text, ...) that is not a component. |
| `removeRawChild(n: Node \| null)` | `void` |  |
| `setPosition(px: float, py: float)` | `void` | Position in the parent's space; keeps the layout fields in step with the node. In a Window body a placed child leaves the flow and keeps this position, while its siblings keep flowing; other layout parents may override it. |
| `setSize(w: float, h: float)` | `void` | Size in pixels. Kept in width/height; the node is NOT resized (see the RULE above). An established hit shape follows. Panel overrides this to also fit its background and border. |
| `addToNode(parent: Node \| null)` | `void` | Add this component's node under `parent` and apply pending layout. |
| `addToScene(root: Node \| null)` | `void` | Add to the scene root (`engine.root2d`) and apply pending layout. |
| `setEnabled(v: boolean)` | `void` |  |
| `setVisible(v: boolean)` | `void` |  |
| `bindEnabled(ref: Ref&lt;boolean&gt;)` | `void` | Follow a Ref&lt;boolean&gt;; the previous binding is stopped first. |
| `bindVisible(ref: Ref&lt;boolean&gt;)` | `void` |  |
| `setCursorShape(shape: string)` | `void` |  |
| `setTooltip(tt: any)` | `void` |  |
| `setTooltipText(text: string, family: string, size: float)` | `void` | A one-label tooltip. Needs the tooltip provider that 7027's tooltip.tks registers. |
| `clearTooltip()` | `void` |  |
| `getTooltip()` | `any` |  |
| `setContextMenu(cm: Showable \| null)` | `void` |  |
| `clearContextMenu()` | `void` |  |
| `setOnTooltipShow(fn: Function \| null)` | `void` |  |
| `setOnTooltipHide(fn: Function \| null)` | `void` |  |
| `setFocused(v: boolean)` | `void` | Set the focus state directly; prefer FocusManager.setFocus for proper tracking. |
| `setHandleKey(fn: Function \| null)` | `void` |  |
| `addChild(child: Component \| null)` | `void` | Append a child. Both the component tree and the node tree are updated. |
| `removeChild(child: Component \| null)` | `void` |  |
| `setTheme(t: Theme \| null)` | `void` | Explicit theme; null reverts to parent inheritance. Propagates to descendants. |
| `setVariant(v: int)` | `void` |  |
| `enableFocusNavigation()` | `void` | The standard focus flags plus registration with the focus manager. |
| `hideBackground()` | `void` |  |
| `hideBorder()` | `void` |  |
| `hideFocusRing()` | `void` |  |
| `applyCornerRadius(r: float)` | `void` |  |
| `applyCornerRadiiPerCorner(tl: float, tr: float, br: float, bl: float)` | `void` |  |
| `applyBackground(bg: Background)` | `void` |  |
| `applyBorder(color: Color, width: float, bg: Background)` | `void` |  |
| `applyFocusRing(color: Color, width: float)` | `void` | Focus ring around the whole component; corner radius from the component. |
| `applyFocusRingSize(color: Color, width: float, w: float, h: float)` | `void` | Like applyFocusRing, for an interactive area smaller than the component (a checkbox box). |
| `hasBgSliceNodes()` | `boolean` |  |
| `isLayoutDirty()` | `boolean` |  |
| `isDrawDirty()` | `boolean` |  |
| `sizeToContent()` | `void` | Resize to tightly fit the children (VBox, HBox, Flow), then lay out. |
| `addAnchoredChild(child: Component \| null, anchor: int, offsetX: float, offsetY: float)` | `void` | Add a child pinned to `anchor` with pixel offsets; the layout must be LAYOUT_ANCHOR. |
| `setAnchor(child: Component \| null, anchor: int, offsetX: float, offsetY: float)` | `void` | Change the anchor and offsets of an existing direct child. |

## Panel

Source: `src/core/panel.tks`. Extends `Component`.

```ts
new Panel(name: string)
```

| Method | Returns | Notes |
|---|---|---|
| `applyThemeColors()` | `void` | Apply the effective theme's PanelGroup unless the aspect is overridden. |
| `setBackground(c: Color)` | `void` |  |
| `setCornerRadii(tl: float, tr: float, br: float, bl: float)` | `void` | Independent corner radii (TL, TR, BR, BL). |
| `setBorder(c: Color, width: float)` | `void` |  |
| `setPadding(top: float, right: float, bottom: float, left: float)` | `void` |  |
| `setLayout(mode: int)` | `void` |  |
| `setSpacing(s: float)` | `void` |  |
| `setAlignment(a: int)` | `void` |  |
| `setJustify(j: int)` | `void` |  |
| `setSize(w: float, h: float)` | `void` | Set the size and fit the background, border and hit shape. With a layout mode active, layout runs now so callers see final child positions. |

## Label

Source: `src/core/label.tks`. Extends `Component`.

```ts
new Label(name: string, text: string, family: string, displaySize: float)
```

| Method | Returns | Notes |
|---|---|---|
| `text()` | `string` |  |
| `setText(t: string)` | `void` |  |
| `setFont(family: string)` | `void` | Use another registered family at the current size. |
| `setBold(bold: boolean)` | `void` |  |
| `setItalic(italic: boolean)` | `void` |  |
| `setFontSize(size: float)` | `void` | Set the display size (0 restores the default) and re-measure. |
| `setColor(c: Color)` | `void` |  |
| `setAlign(a: int)` | `void` | TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER or TEXT_ALIGN_RIGHT. |
| `setSharpness(s: float)` | `void` | Go writes TextBlock.Sharpness; here it drives willow's Text.sharpness (item 7136). |
| `setWrapWidth(w: float)` | `void` | Maximum line width for wrapping; zero means no wrapping. |
| `bindText(ref: Ref&lt;string&gt;)` | `void` | Follow a Ref&lt;string&gt;: the label takes the ref's value now and at every later change. Any previous binding is stopped first. |

## Button

Source: `src/core/button.tks`. Extends `Component`.

```ts
new Button(name: string, text: string, family: string, displaySize: float)
```

| Method | Returns | Notes |
|---|---|---|
| `setText(t: string)` | `void` |  |
| `bindText(ref: Ref&lt;string&gt;)` | `void` | The label follows the ref; any previous binding is stopped first. |
| `setOnClick(fn: Function \| null)` | `void` |  |
| `setSize(w: float, h: float)` | `void` | Sets the size and disables auto-size. |
| `setAutoSize(v: boolean)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |
| `hasOnClickCallback()` | `boolean` |  |

## IconButton

Source: `src/core/button.tks`. Extends `Component`.

```ts
new IconButton(name: string)
```

| Method | Returns | Notes |
|---|---|---|
| `setIconKey(key: string)` | `void` | The icon from a sprite key in the effective theme's sprites map; an unknown key clears the icon. |
| `setIconImage(img: any)` | `void` | The icon from a Texture or a TextureRegion (a theme sprite holds either). |
| `setIconTexture(tex: Texture)` | `void` |  |
| `setIconRegion(region: TextureRegion)` | `void` |  |
| `setIconSize(w: float, h: float)` | `void` | Override the icon size; 0, 0 restores the theme size (square). |
| `setLabel(text: string, family: string, size: float)` | `void` |  |
| `setLabelPosition(pos: int)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |
| `setActive(v: boolean)` | `void` | The toggle-style active highlight. A bound ref follows the value. |
| `bindActive(ref: Ref&lt;boolean&gt;)` | `void` | Follow a Ref&lt;boolean&gt;. Clicking does not toggle the ref; that is the caller's job. |
| `setOnClick(fn: Function \| null)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |
| `isActive()` | `boolean` |  |

## Image

Source: `src/core/image.tks`. Extends `Component`.

```ts
new Image(name: string)
```

| Method | Returns | Notes |
|---|---|---|
| `setRegion(region: TextureRegion \| null)` | `void` | An atlas sprite; clears any Texture. |
| `setImage(tex: Texture \| null)` | `void` | A raw Texture; clears any region. null clears the image. |
| `clearImage()` | `void` | Leave the widget empty. |
| `setScaleMode(mode: int)` | `void` |  |
| `setTint(c: Color)` | `void` |  |
| `setAlpha(a: float)` | `void` | The alpha of the tint. |
| `setCornerRadius(r: float)` | `void` | -1 is a full pill (half the shorter side); 0 is sharp. |
| `setSize(w: float, h: float)` | `void` |  |
| `sizeToContent()` | `void` | Resize to the image's native pixel size; no effect without an image. |

## Tooltip

Source: `src/core/tooltip.tks`. Extends `Component`.

```ts
new Tooltip(name: string)
```

| Method | Returns | Notes |
|---|---|---|
| `applyThemeColors()` | `void` | Background, border and padding from the effective theme's TooltipGroup. |
| `setSize(w: float, h: float)` | `void` | Explicit dimensions, bypassing auto-size. |
| `setText(text: string, family: string, size: float)` | `void` | Replace all children with one Label showing `text`. |
| `setShowDelay(frames: int)` | `void` |  |
| `setHideDelay(frames: int)` | `void` |  |
| `setAnchor(a: int)` | `void` |  |
| `setOffset(x: float, y: float)` | `void` |  |
| `setFadeIn(seconds: float)` | `void` |  |
| `setFadeOut(seconds: float)` | `void` |  |
| `setClampToScreen(v: boolean)` | `void` |  |
| `setClampMargin(px: float)` | `void` |  |
| `show(x: float, y: float)` | `void` | Show at a screen position, bypassing the hover delay. Hide it with hide(). |
| `hide()` | `void` | Hide at once, bypassing hideDelay and the fade-out. |
| `isShowing()` | `boolean` |  |

## TooltipManager

Source: `src/core/tooltip.tks`.

Manages tooltip visibility for the scene. A ticker node under the scene root drives tick() once per frame. DEFAULT_TOOLTIP_MANAGER is the singleton every component uses.

| Method | Returns | Notes |
|---|---|---|
| `setScene(s: any)` | `void` | Called on every setScene: hide what is showing and make sure the nodes exist. |
| `showAtPosition(tt: Tooltip, px: float, py: float)` | `void` | Show at an explicit position, bypassing hover. Viewport-corner and follow-mouse anchors ignore (x, y) and compute their own. |
| `hideTooltip(tt: Tooltip)` | `void` |  |
| `hideImmediate(fireCallback: boolean)` | `void` | Hide with no fade. `fireCallback` false forgets the trigger first, so its hide callback does not run. |

## ScrollBar

Source: `src/core/scrollbar.tks`. Extends `Component`.

```ts
new ScrollBar(name: string)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `applyThemeColors()` | `void` |  |
| `applyThumbState()` | `void` |  |
| `setScrollPos(v: float)` | `void` | Clamp to [0, total - view], store, re-place the thumb and report a real change. |
| `setContentSize(total: float, view: float)` | `void` |  |
| `setOrientation(o: int)` | `void` |  |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setSize(w: float, h: float)` | `void` | The bar's dimensions. The node is not resized (RULE 7007); the track and border are, and the hit shape covers the whole bar. |
| `bindScrollPos(ref: Ref&lt;float&gt;)` | `void` | Follow a Ref&lt;float&gt;: apply its current value now and every later write (one frame after). |

## ScrollPanel

Source: `src/core/scrollpanel.tks`. Extends `Panel`.

```ts
new ScrollPanel(name: string)
```

| Method | Returns | Notes |
|---|---|---|
| `addContent(child: Component \| null)` | `void` | Add a component's node to the content node WITHOUT adopting it as a child (Go AddContent). |
| `setContentSize(w: float, h: float)` | `void` |  |
| `setScrollX(v: float)` | `void` |  |
| `setScrollY(v: float)` | `void` |  |
| `scrollTo(x: float, y: float)` | `void` |  |
| `getScrollX()` | `float` |  |
| `getScrollY()` | `float` |  |
| `showVScroll(show: boolean)` | `void` |  |
| `showHScroll(show: boolean)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |
| `setBorder(c: Color, width: float)` | `void` | A manual border colour and width; the bars and viewport re-fit inside it. (Go passes an empty solid Background so the border is drawn as edges.) |
| `addChild(child: Component \| null)` | `void` | Add a child component; its node goes inside the scrollable content container. |
| `removeChild(child: Component \| null)` | `void` | Detach a child from the content container (the node that holds it, not the panel node). |

## Screen

Source: `src/core/controller.tks`.

| Method | Returns | Notes |
|---|---|---|
| `add(e: Component)` | `void` |  |
| `addNode(n: Node)` | `void` |  |
| `remove(e: Component)` | `void` |  |
| `removeNode(n: Node)` | `void` |  |
| `isVisible()` | `boolean` |  |
| `show()` | `void` | Attach the root node to the scene and call onCreate on first show. |
| `hide()` | `void` | Detach the root node but keep all state. |
| `clearTemplateTree()` | `void` | Stop all tracked refs and remove every child of the root (hot reload). |
| `findByName(name: string)` | `Component \| null` | The component with this name in the tree, or null. |

## StageManager

Source: `src/core/controller.tks`.

A stack of screens.

| Method | Returns | Notes |
|---|---|---|
| `setScene(s: Node \| null)` | `void` | Set the scene root used to attach screens; screens without one adopt it. |
| `add(screen: Screen)` | `void` | Push and show. |
| `remove(screen: Screen)` | `void` | Dispose and remove a specific screen. |
| `closeAll()` | `void` |  |
| `size()` | `int` |  |

---

URL: https://thicketscript.com/willowui/reference/display

# Display widgets: API

This page is generated from the willowui source. It lists each public class with its constructor, its setter-style methods and its callback fields. The guide page for this family explains how to use them. Methods the generator skips (internal handlers, layout and draw steps) are still reachable but are not part of the everyday surface.

- [AnimatedImage](#animatedimage)
- [Badge](#badge)
- [MeterBar](#meterbar)
- [ProgressBar](#progressbar)
- [LineFragment](#linefragment)
- [LinkRect](#linkrect)
- [RichText](#richtext)
- [Spacer](#spacer)
- [StatAxis](#stataxis)
- [StatWeb](#statweb)
- [ToastEntry](#toastentry)
- [ToastManager](#toastmanager)

## AnimatedImage

Source: `src/widgets/display/animatedimage.tks`. Extends `Component`.

```ts
new AnimatedImage(name: string)
```

Callback fields: `onFrameChanged`, `onComplete`.

| Method | Returns | Notes |
|---|---|---|
| `setAtlas(tex: Texture \| null, fw: int, fh: int)` | `void` | Slice an atlas texture into frames of fw by fh, left to right then top to bottom. |
| `setFrames(frames: TextureRegion[])` | `void` | An explicit list of regions as frames. |
| `loadGif(g: GifData \| null)` | `void` | Frames and per-frame delays from a decoded GIF; loop count 0 loops forever, otherwise once. |
| `loadGifBytes(bytes: Buffer)` | `void` | Decode raw GIF file bytes (throws on a malformed file) and load them. |
| `setFPS(fps: float)` | `void` |  |
| `setPlayMode(mode: int)` | `void` |  |
| `play()` | `void` |  |
| `pause()` | `void` |  |
| `stop()` | `void` |  |
| `setFrame(n: int)` | `void` |  |
| `currentFrame()` | `int` |  |
| `isPlaying()` | `boolean` |  |
| `setScaleMode(mode: int)` | `void` |  |
| `setTint(c: Color)` | `void` |  |
| `setCornerRadius(r: float)` | `void` | -1 is a full pill. |
| `setSize(w: float, h: float)` | `void` |  |

## Badge

Source: `src/widgets/display/badge.tks`. Extends `Component`.

```ts
new Badge(name: string, family: string, displaySize: float)
```

| Method | Returns | Notes |
|---|---|---|
| `text()` | `string` |  |
| `setText(t: string)` | `void` |  |
| `setCount(n: int)` | `void` | The count as text, "N+" above maxCount (0 disables truncation). |
| `setMaxCount(n: int)` | `void` |  |
| `setDotMode(v: boolean)` | `void` |  |
| `setPadding(top: float, right: float, bottom: float, left: float)` | `void` | Override the theme padding with per-instance values. |
| `setSize(w: float, h: float)` | `void` | Override the auto-size dimensions. |
| `sizeToContent()` | `void` | Fit the badge to its content plus padding (dot mode: the theme dot size, default 8). |

## MeterBar

Source: `src/widgets/display/progressbar.tks`. Extends `Component`.

```ts
new MeterBar(name: string)
```

| Method | Returns | Notes |
|---|---|---|
| `value()` | `float` | The current normalized fill value (0 to 1), regardless of range. |
| `setRange(min: float, max: float)` | `void` |  |
| `setValue(v: float)` | `void` | Set the value in [min, max], mapped to 0..1 internally. |
| `setProgress(v: float)` | `void` | Set the normalized 0..1 fill directly, bypassing the range (used by bindValue). |
| `setSize(w: float, h: float)` | `void` |  |
| `setShowLabel(show: boolean, family: string, displaySize: float)` | `void` | Show or hide the percentage label overlay (created on first show). |
| `bindValue(ref: Ref&lt;float&gt;)` | `void` | Follow a Ref&lt;float&gt; (0..1 normalized): applied now and at every later write. |
| `setFillColor(c: Color)` | `void` |  |
| `clearFillColor()` | `void` |  |

## ProgressBar

Source: `src/widgets/display/progressbar.tks`. Extends `MeterBar`.

ProgressBar is an alias for MeterBar (Go type alias).

```ts
new ProgressBar(name: string)
```

## LineFragment

Source: `src/widgets/display/richtext.tks`.

A piece of text on a line, from a single span, with resolved styling and measured size.

```ts
new LineFragment(color: Color)
```

## LinkRect

Source: `src/widgets/display/richtext.tks`.

A clickable region mapped during render.

```ts
new LinkRect(rect: Rect, url: string)
```

## RichText

Source: `src/widgets/display/richtext.tks`. Extends `Component`.

```ts
new RichText(name: string, family: string, displaySize: float)
```

Callback fields: `onLinkClick`.

| Method | Returns | Notes |
|---|---|---|
| `setHeadingScale(h1: float, h2: float, h3: float)` | `void` |  |
| `addSpan(text: string)` | `RichText` |  |
| `addStyledSpan(text: string, family: string \| null, color: Color, outline: Outline \| null)` | `RichText` | A span with explicit styling; the colour is always set. `family` and `outline` null inherit. |
| `addTextSpan(span: TextSpan)` | `RichText` |  |
| `addBoldSpan(text: string, color: Color)` | `RichText` |  |
| `addItalicSpan(text: string, color: Color)` | `RichText` |  |
| `addBoldItalicSpan(text: string, color: Color)` | `RichText` |  |
| `clearSpans()` | `RichText` |  |
| `setSpans(spans: TextSpan[])` | `RichText` |  |
| `setWrapWidth(w: float)` | `void` |  |
| `setAlign(a: int)` | `void` |  |
| `setColor(c: Color)` | `void` |  |
| `setOutline(o: Outline \| null)` | `void` |  |
| `setMarkup(markup: string)` | `void` | Parse XML-like markup and replace all spans. Throws on an unknown tag. |

## Spacer

Source: `src/widgets/display/spacer.tks`. Extends `Component`.

```ts
new Spacer(name: string, w: float, h: float)
```

| Method | Returns | Notes |
|---|---|---|
| `setSize(w: float, h: float)` | `void` | Component.setSize also keeps an established hit shape in step; a spacer has none. |

## StatAxis

Source: `src/widgets/display/statweb.tks`.

```ts
new StatAxis(name: string, min: float, max: float, value: float)
```

## StatWeb

Source: `src/widgets/display/statweb.tks`. Extends `Component`.

```ts
new StatWeb(name: string, family: string, fontSize: float)
```

Callback fields: `onValueChanged`.

| Method | Returns | Notes |
|---|---|---|
| `setAxes(axes: StatAxis[])` | `void` | Define all spokes at once (at most eight; values are clamped into each axis's range). |
| `setValues(values: float[])` | `void` | Bulk-set values by index, parallel to the axes. |
| `values()` | `float[]` |  |
| `setValue(index: int, value: float)` | `void` |  |
| `value(index: int)` | `float` |  |
| `setFillEnabled(v: boolean)` | `void` | Show or hide the semi-transparent polygon fill. |
| `setEditable(v: boolean)` | `void` |  |
| `isEditable()` | `boolean` |  |
| `setSize(w: float, h: float)` | `void` |  |

## ToastEntry

Source: `src/widgets/display/toast.tks`.

```ts
new ToastEntry(root: Component, progressNode: Quad | null, progressMaxW: float, w: float, h: float, cfg: ToastOptions)
```

| Method | Returns | Notes |
|---|---|---|
| `cancelAnim()` | `void` |  |
| `cancelTimers()` | `void` | Drop the expiry and progress entries from the ticker. |

## ToastManager

Source: `src/widgets/display/toast.tks`.

| Method | Returns | Notes |
|---|---|---|
| `setFont(family: string, size: float)` | `void` | Font used to render messages; call once at startup. An empty family draws no message. |
| `setAnchor(corner: int)` | `void` |  |
| `setMaxStack(n: int)` | `void` | Maximum toasts visible at once (default 4, minimum 1); the oldest is dropped when full. |
| `setMargin(x: float, y: float)` | `void` | Pixel gap between the stack and the screen edge (default 16 by 16). |
| `show(message: string, variant: int, opts?: Function[])` | `void` | Show a toast; `opts` are option functions from withDuration and friends. |
| `dismissAll()` | `void` | Remove every toast immediately, running each onDismiss. |
| `setScene(s: any)` | `void` | Scene change: drop every entry and rebuild the overlay under the new root. |
| `dismissEntry(e: ToastEntry)` | `void` | Begin the dismiss animation (click-to-dismiss). |

---

URL: https://thicketscript.com/willowui/reference/interactive

# Interactive widgets: API

This page is generated from the willowui source. It lists each public class with its constructor, its setter-style methods and its callback fields. The guide page for this family explains how to use them. Methods the generator skips (internal handlers, layout and draw steps) are still reachable but are not part of the everyday surface.

- [CalendarDayCell](#calendardaycell)
- [CalendarSelector](#calendarselector)
- [Checkbox](#checkbox)
- [ContextMenu](#contextmenu)
- [DragHandle](#draghandle)
- [ImageCropper](#imagecropper)
- [KeybindInput](#keybindinput)
- [MenuBarEntry](#menubarentry)
- [MenuBarNode](#menubarnode)
- [MenuBar](#menubar)
- [MenuItem](#menuitem)
- [MenuPopup](#menupopup)
- [MenuPopupManager](#menupopupmanager)
- [OptionRotator](#optionrotator)
- [Popover](#popover)
- [PopoverManager](#popovermanager)
- [RadioButton](#radiobutton)
- [Radio](#radio)
- [SelectOption](#selectoption)
- [Select](#select)
- [Slider](#slider)
- [TimeValue](#timevalue)
- [TimeColumn](#timecolumn)
- [TimePicker](#timepicker)
- [Toggle](#toggle)
- [ToggleButtonBar](#togglebuttonbar)
- [ToolBar](#toolbar)
- [ToolGroup](#toolgroup)

## CalendarDayCell

Source: `src/widgets/interactive/calendarselector.tks`.

A single day cell in the grid.

```ts
new CalendarDayCell(container: Node, bg: Quad, label: Text)
```

## CalendarSelector

Source: `src/widgets/interactive/calendarselector.tks`. Extends `Component`.

```ts
new CalendarSelector(name: string, family: string, displaySize: float)
```

Callback fields: `onDateSelected`.

| Method | Returns | Notes |
|---|---|---|
| `setDate(t: Date)` | `void` | The selected date, and navigate to its month. Does not fire onDateSelected. |
| `setMinDate(t: Date)` | `void` |  |
| `setMaxDate(t: Date)` | `void` |  |
| `clearMinDate()` | `void` |  |
| `clearMaxDate()` | `void` |  |
| `setPopupMode(v: boolean)` | `void` | Switch between inline and popup display. |
| `isPopupMode()` | `boolean` |  |
| `openPopup()` | `void` | Open the popup calendar (popup mode only). |
| `closePopup()` | `void` | Close the popup calendar (popup mode only). |
| `setMonth(year: int, month: int)` | `void` | Navigate the view to a year and month (1-12). |
| `setOnDateSelected(fn: Function \| null)` | `void` |  |
| `bindDate(ref: Ref&lt;Date&gt;)` | `void` | The selected date follows the ref and user picks write to it. |
| `setSize(w: float, h: float)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |
| `isDateDisabled(t: Date)` | `boolean` |  |

## Checkbox

Source: `src/widgets/interactive/checkbox.tks`. Extends `Component`.

```ts
new Checkbox(name: string, text: string, family: string, displaySize: float)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `setChecked(v: boolean)` | `void` |  |
| `setText(text: string)` | `void` |  |
| `bindValue(ref: Ref&lt;boolean&gt;)` | `void` | The checkbox follows the ref (initial value applied now), and clicks write to it. |
| `setCheckIcon(img: TextureRegion)` | `void` | Replace the built-in check glyph with a custom image, shown at the box size. |
| `setEnabled(v: boolean)` | `void` |  |

## ContextMenu

Source: `src/widgets/interactive/contextmenu.tks`.

```ts
new ContextMenu(family: string, displaySize: float)
```

| Method | Returns | Notes |
|---|---|---|
| `setItems(items: MenuItem[])` | `void` | Replace the item list. |
| `setVariant(v: int)` | `void` |  |
| `showAt(x: float, y: float)` | `void` | Open the menu with its top-left at (x, y) in world/screen coordinates. |
| `hide()` | `void` | Close the menu if it is open. |

## DragHandle

Source: `src/widgets/interactive/draghandle.tks`. Extends `Component`.

```ts
new DragHandle(name: string)
```

Callback fields: `onDragStart`, `onDrag`, `onDragEnd`.

| Method | Returns | Notes |
|---|---|---|
| `setAxis(a: int)` | `void` |  |
| `setTarget(c: Component \| null)` | `void` |  |
| `clearTarget()` | `void` |  |
| `setGripStyle(s: int)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |

## ImageCropper

Source: `src/widgets/interactive/imagecropper.tks`. Extends `Component`.

```ts
new ImageCropper(name: string)
```

Callback fields: `onCropChanged`.

| Method | Returns | Notes |
|---|---|---|
| `setImage(img: Texture \| null)` | `void` | Set the source image (null clears it). The crop defaults to the whole image the first time. |
| `setCropRect(x: float, y: float, w: float, h: float)` | `void` | The crop rectangle in image-pixel coordinates. |
| `setAspectRatio(w: float, h: float)` | `void` | Constrain the crop to a fixed aspect ratio; 0, 0 is free. |
| `setMinSize(w: float, h: float)` | `void` |  |
| `setMaxSize(w: float, h: float)` | `void` |  |
| `setShowGrid(v: boolean)` | `void` | The rule-of-thirds grid overlay. |
| `setOnCropChanged(fn: Function \| null)` | `void` | Fired during handle drags with the new crop rectangle. |
| `setSize(w: float, h: float)` | `void` |  |
| `startDrag(handleIdx: int, gx: float, gy: float)` | `void` | Begin a drag of a handle (or -1 to move the whole rect) at the global pointer position. |

## KeybindInput

Source: `src/widgets/interactive/keybindinput.tks`. Extends `Component`.

```ts
new KeybindInput(name: string, family: string, displaySize: float)
```

Callback fields: `onBindingChanged`, `onConflict`.

| Method | Returns | Notes |
|---|---|---|
| `getBinding()` | `KeyBinding` |  |
| `setBinding(b: KeyBinding)` | `void` | Set the binding without entering listening mode or firing the callback. |
| `clearBinding()` | `void` |  |
| `setListening(v: boolean)` | `void` |  |
| `isListening()` | `boolean` |  |
| `setCombosEnabled(v: boolean)` | `void` |  |
| `setOnBindingChanged(fn: Function \| null)` | `void` |  |
| `setOnConflict(fn: Function \| null)` | `void` | Return false from the callback to reject a binding. |
| `bindValue(ref: Ref&lt;KeyBinding&gt;)` | `void` | The binding follows the ref and user captures write to it. |
| `setSize(w: float, h: float)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |

## MenuBarEntry

Source: `src/widgets/interactive/menubar.tks`.

One top-level menu in the bar.

```ts
new MenuBarEntry(label: string, items: MenuItem[])
```

## MenuBarNode

Source: `src/widgets/interactive/menubar.tks`.

Per-entry visual data.

```ts
new MenuBarNode(bg: Quad, label: Text, hit: Node, x: float, w: float)
```

## MenuBar

Source: `src/widgets/interactive/menubar.tks`. Extends `Component`.

```ts
new MenuBar(name: string, family: string, displaySize: float)
```

Callback fields: `onMenuOpen`, `onMenuClose`.

| Method | Returns | Notes |
|---|---|---|
| `setEntries(entries: MenuBarEntry[])` | `void` |  |
| `setEntry(index: int, entry: MenuBarEntry)` | `void` | Replace one entry; out of range is ignored. |
| `setSize(w: float, h: float)` | `void` |  |
| `setOnMenuOpen(fn: Function \| null)` | `void` |  |
| `setOnMenuClose(fn: Function \| null)` | `void` |  |
| `applyTheme()` | `void` |  |
| `rebuild()` | `void` |  |
| `hideOverlay()` | `void` | Remove the overlay and restore the normal entry node references. |
| `openMenu(index: int)` | `void` |  |
| `closeMenu()` | `void` | Close the open dropdown; the popup's onDismiss does the state cleanup. |

## MenuItem

Source: `src/widgets/interactive/menupopup.tks`.

A single entry in a MenuPopup.

```ts
new MenuItem(label: string, onSelect: Function | null)
```

Callback fields: `onSelect`.

## MenuPopup

Source: `src/widgets/interactive/menupopup.tks`.

```ts
new MenuPopup(family: string, displaySize: float)
```

Callback fields: `onDismiss`.

| Method | Returns | Notes |
|---|---|---|
| `setItems(items: MenuItem[])` | `void` |  |
| `setOnDismiss(fn: Function \| null)` | `void` |  |
| `setVariant(v: int)` | `void` |  |
| `scrollToHighlighted()` | `void` | Keep the highlighted item in view when navigating by keyboard in a scrollable popup. |

## MenuPopupManager

Source: `src/widgets/interactive/menupopup.tks`.

Manages the single active floating menu popup. Use DEFAULT_MENU_POPUP_MANAGER.

| Method | Returns | Notes |
|---|---|---|
| `setScene(s: any)` | `void` |  |
| `show(popup: MenuPopup, trigger: Component \| null)` | `void` | Display `popup` below (or above) the trigger component. |
| `showAt(popup: MenuPopup, x: float, y: float)` | `void` | Display `popup` with its top-left at (x, y). |
| `hide()` | `void` | Close the active popup without a selection. |
| `isOpen()` | `boolean` |  |
| `dismiss()` | `void` |  |
| `hideActive()` | `void` |  |
| `setHighlight(idx: int)` | `void` | Item pointer enter. |
| `clearHighlight(idx: int)` | `void` | Item pointer leave. |
| `selectItem(idx: int)` | `void` | Fire the item's onSelect and close the popup. |

## OptionRotator

Source: `src/widgets/interactive/optionrotator.tks`. Extends `Component`.

```ts
new OptionRotator(name: string, options: string[], family: string, displaySize: float)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `setOptions(opts: string[])` | `void` | Replaces the list; the index is clamped and onChange fires when that moves it. |
| `setSelected(i: int)` | `void` | The index is clamped; onChange fires only when the selection changes. |
| `setWrap(v: boolean)` | `void` |  |
| `setChevronIcons(left: TextureRegion \| null, right: TextureRegion \| null)` | `void` | Either icon may be null to keep the theme or built-in chevron for that side. |
| `bindOptions(arr: ReactiveArray&lt;string&gt; \| null)` | `void` | The options follow a ReactiveArray; the selection is clamped. Pass null to detach. |
| `bindSelected(ref: Ref&lt;int&gt;)` | `void` | The index follows the ref and user changes write to it. Replaces any previous binding. |
| `bindValue(ref: Ref&lt;string&gt;)` | `void` | The value string follows the ref; an unknown value resolves to index 0 (as in Go). |
| `value()` | `string` |  |
| `setSize(w: float, h: float)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |

## Popover

Source: `src/widgets/interactive/popover.tks`. Extends `Component`.

```ts
new Popover(name: string)
```

Callback fields: `onOpenCb`, `onCloseCb`.

| Method | Returns | Notes |
|---|---|---|
| `setPreferredSide(side: int)` | `void` |  |
| `setContentSize(w: float, h: float)` | `void` | The size of the content area (excluding the title bar). |
| `setTitle(text: string, family: string, size: float)` | `void` | An optional title in the header; `family` is a registered font family. |
| `setShowCloseButton(v: boolean)` | `void` |  |
| `setContent(comp: Component \| null)` | `void` |  |
| `setOnOpen(fn: Function \| null)` | `void` |  |
| `setOnClose(fn: Function \| null)` | `void` |  |
| `open(trigger: Component \| null)` | `void` | Open anchored to `trigger`, through DEFAULT_POPOVER_MANAGER; another open popover closes first. |
| `close()` | `void` |  |
| `isOpen()` | `boolean` |  |
| `setManager(m: any)` | `void` | Remember which manager opened it (PopoverManager.open). |

## PopoverManager

Source: `src/widgets/interactive/popover.tks`.

Manages the single active floating popover. Use DEFAULT_POPOVER_MANAGER.

| Method | Returns | Notes |
|---|---|---|
| `setScene(s: any)` | `void` | Called on every setScene. |
| `open(p: Popover, trigger: Component \| null)` | `void` | Display `p` anchored to `trigger` (null centres it); an open popover closes first. |
| `close(p: Popover)` | `void` | Close `p` if it is the active one. |
| `dismiss()` | `void` | The dismiss node was clicked. |
| `hideActive(fireCallback: boolean)` | `void` | Remove the active popover's node tree from the overlay. |

## RadioButton

Source: `src/widgets/interactive/radio.tks`. Extends `Component`.

One option within a Radio.

```ts
new RadioButton(group: RadioHost, groupName: string, index: int, text: string, family: string, displaySize: float)
```

| Method | Returns | Notes |
|---|---|---|
| `setSelected(sel: boolean)` | `void` |  |
| `applyThemeColors()` | `void` |  |

## Radio

Source: `src/widgets/interactive/radio.tks`. Extends `Component`.

```ts
new Radio(name: string)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `setColumns(n: int)` | `void` | Columns (default 1 = one vertical stack); triggers a layout update. |
| `setVerticalFirst(v: boolean)` | `void` | Fill order when columns &gt; 1: false fills left to right then wraps, true fills each column top down. |
| `addOption(text: string, family: string, displaySize: float)` | `RadioButton` |  |
| `setSelected(idx: int)` | `void` | Programmatic selection; does not fire onChange. |
| `bindSelected(ref: Ref&lt;int&gt;)` | `void` | The group follows the ref (initial value applied now); clicks write to it. |
| `selectIndex(idx: int)` | `void` |  |

## SelectOption

Source: `src/widgets/interactive/select.tks`.

A single choice in a Select.

```ts
new SelectOption(label: string, value: any)
```

## Select

Source: `src/widgets/interactive/select.tks`. Extends `Component`.

```ts
new Select(name: string, options: SelectOption[], family: string, displaySize: float)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `setOptions(options: SelectOption[])` | `void` | Replace the options; the selection resets to 0. |
| `bindOptions(arr: ReactiveArray&lt;SelectOption&gt; \| null)` | `void` | The options follow a ReactiveArray; the selection is clamped. Pass null to detach. |
| `bindSelected(ref: Ref&lt;int&gt;)` | `void` | The selection follows the ref and user choices write to it. Replaces any previous binding. |
| `setSelected(idx: int)` | `void` | Select the option at `idx`; out of range is ignored. |
| `selectedOption()` | `SelectOption` |  |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setSize(w: float, h: float)` | `void` | The explicit size of the trigger button. |
| `setEnabled(v: boolean)` | `void` |  |

## Slider

Source: `src/widgets/interactive/slider.tks`. Extends `Component`.

```ts
new Slider(name: string)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `setValue(v: float)` | `void` |  |
| `setRange(mn: float, mx: float)` | `void` |  |
| `setStep(s: float)` | `void` |  |
| `setOrientation(o: int)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |
| `bindValue(ref: Ref&lt;float&gt;)` | `void` | Follow the ref (initial value applied now); later writes one frame after. |
| `setEnabled(v: boolean)` | `void` |  |

## TimeValue

Source: `src/widgets/interactive/timepicker.tks`.

A time of day: hour (0-23), minute and second.

```ts
new TimeValue(hour: int, minute: int, second: int)
```

## TimeColumn

Source: `src/widgets/interactive/timepicker.tks`.

An up/down stepper column for one time field.

```ts
new TimeColumn(container: Node, upBtn: Button, downBtn: Button, label: Quad, labelText: Text)
```

| Method | Returns | Notes |
|---|---|---|
| `setEnabled(v: boolean)` | `void` |  |

## TimePicker

Source: `src/widgets/interactive/timepicker.tks`. Extends `Component`.

```ts
new TimePicker(name: string, family: string, displaySize: float)
```

Callback fields: `onTimeChanged`.

| Method | Returns | Notes |
|---|---|---|
| `setTime(h: int, m: int, s: int)` | `void` | Set the time; `h` is in the 24h range. |
| `setShowSeconds(v: boolean)` | `void` |  |
| `setFormat(format: int)` | `void` |  |
| `setOnTimeChanged(fn: Function \| null)` | `void` | Callback (hour24, minute, second) fired when any field changes by user interaction. |
| `bindTime(ref: Ref&lt;TimeValue&gt;)` | `void` | The time follows the ref and user steps write to it. |
| `setSize(w: float, h: float)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |
| `setDisplayHour(dispH: int)` | `void` | Convert a 12h display hour back to 24h and store it. |
| `toggleAmPm()` | `void` |  |

## Toggle

Source: `src/widgets/interactive/toggle.tks`. Extends `Component`.

```ts
new Toggle(name: string)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `setValue(v: boolean)` | `void` |  |
| `bindValue(ref: Ref&lt;boolean&gt;)` | `void` | Follow the ref (initial value applied now); clicks write to it. |
| `setEnabled(v: boolean)` | `void` |  |

## ToggleButtonBar

Source: `src/widgets/interactive/togglebuttonbar.tks`. Extends `Component`.

```ts
new ToggleButtonBar(name: string, family: string, displaySize: float)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `addButton(label: string)` | `void` |  |
| `removeButton(idx: int)` | `void` |  |
| `setSelected(idx: int)` | `void` | Out-of-range indices are ignored; onChange fires only when the index changes. |
| `bindButtons(arr: ReactiveArray&lt;string&gt; \| null)` | `void` | The button labels follow a ReactiveArray: the bar is rebuilt on each change, keeping the selection index where possible. Pass null to detach. |
| `bindSelected(ref: Ref&lt;int&gt;)` | `void` | The bar follows the ref (initial value applied now); selections write to it. |
| `setSize(w: float, h: float)` | `void` |  |

## ToolBar

Source: `src/widgets/interactive/toolbar.tks`. Extends `Component`.

```ts
new ToolBar(name: string)
```

| Method | Returns | Notes |
|---|---|---|
| `setOrientation(o: int)` | `void` |  |
| `addItem(comp: Component)` | `void` |  |
| `addSeparator()` | `void` |  |
| `addSpacer()` | `void` |  |
| `removeItem(nm: string)` | `void` | Removes the component item with this name (separators and spacers are not matched). |
| `clear()` | `void` |  |
| `setOverflowMode(mode: int)` | `void` |  |
| `setWrap(v: boolean)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |

## ToolGroup

Source: `src/widgets/interactive/toolgroup.tks`.

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `setAllowNone(v: boolean)` | `void` |  |
| `add(btn: IconButton)` | `void` |  |
| `setSelected(idx: int)` | `void` |  |
| `bindSelected(ref: Ref&lt;int&gt;)` | `void` | The group follows the ref (initial value applied now); selections write to it. |

---

URL: https://thicketscript.com/willowui/reference/text

# Text widgets: API

This page is generated from the willowui source. It lists each public class with its constructor, its setter-style methods and its callback fields. The guide page for this family explains how to use them. Methods the generator skips (internal handlers, layout and draw steps) are still reachable but are not part of the everyday surface.

- [ColorPicker](#colorpicker)
- [ColorPickerPopup](#colorpickerpopup)
- [ColorPickerManager](#colorpickermanager)
- [InputField](#inputfield)
- [MaskToken](#masktoken)
- [MaskedInput](#maskedinput)
- [NumberStepper](#numberstepper)
- [SearchBox](#searchbox)
- [Tag](#tag)
- [TagBar](#tagbar)
- [VisualLine](#visualline)
- [LineCol](#linecol)
- [TextArea](#textarea)
- [WordRange](#wordrange)
- [TextInput](#textinput)

## ColorPicker

Source: `src/widgets/text/colorpicker.tks`. Extends `Component`.

```ts
new ColorPicker(name: string, family: string, displaySize: float)
```

Callback fields: `onChange`, `onCommit`.

| Method | Returns | Notes |
|---|---|---|
| `setShowAlpha(show: boolean)` | `void` | Whether the alpha channel is editable in the popup. |
| `setDefaultMode(mode: int)` | `void` | The mode shown first when the popup opens. |
| `setValue(c: Color)` | `void` | Set the colour without opening the popup. |
| `bindValue(ref: Ref&lt;Color&gt;)` | `void` | The picker writes back to the ref; external writes update the picker. |
| `setOnChange(fn: Function \| null)` | `void` | Invoked whenever the colour changes (each drag step). |
| `setOnCommit(fn: Function \| null)` | `void` | Invoked when the popup closes with a committed value. |
| `open()` | `void` |  |
| `close()` | `void` |  |
| `cancel()` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |

## ColorPickerPopup

Source: `src/widgets/text/colorpicker.tks`.

```ts
new ColorPickerPopup(trigger: ColorPicker)
```

| Method | Returns | Notes |
|---|---|---|
| `setMode(mode: int)` | `void` |  |

## ColorPickerManager

Source: `src/widgets/text/colorpicker.tks`.

Manages the single active floating picker popup.

| Method | Returns | Notes |
|---|---|---|
| `show(trigger: ColorPicker)` | `void` | Open the popup for a trigger, below it and clamped to the window. |
| `commitAndClose()` | `void` |  |
| `cancelAndClose()` | `void` |  |
| `isOpen()` | `boolean` |  |

## InputField

Source: `src/widgets/text/inputfield.tks`. Extends `Component`.

```ts
new InputField(name: string, family: string, displaySize: float)
```

| Method | Returns | Notes |
|---|---|---|
| `setLabel(text: string)` | `void` |  |
| `setLabelPosition(pos: int)` | `void` |  |
| `setRequired(v: boolean)` | `void` |  |
| `setRequiredMarker(s: string)` | `void` | The character(s) appended to the label when required (default "*"). |
| `setValidationState(state: int)` | `void` |  |
| `setValidationMessage(msg: string)` | `void` |  |
| `clearValidation()` | `void` |  |
| `setValue(v: string)` | `void` |  |
| `getValue()` | `string` |  |
| `setPlaceholder(v: string)` | `void` |  |
| `bindValue(ref: Ref&lt;string&gt;)` | `void` |  |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setOnSubmit(fn: Function \| null)` | `void` |  |
| `setOnBlur(fn: Function \| null)` | `void` |  |
| `setMaxLength(n: int)` | `void` |  |
| `setReadOnly(v: boolean)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |
| `setSize(w: float, h: float)` | `void` | The input width and height; the label and message size themselves. |
| `setWidth(w: float)` | `void` | Width only; the height comes from the font size. |

## MaskToken

Source: `src/widgets/text/maskedinput.tks`.

```ts
new MaskToken(kind: int, literal: string)
```

## MaskedInput

Source: `src/widgets/text/maskedinput.tks`. Extends `Component`.

```ts
new MaskedInput(name: string, family: string, displaySize: float)
```

Callback fields: `onChange`, `onRawChange`, `onSubmit`, `onBlur`, `onComplete`, `onIncomplete`.

| Method | Returns | Notes |
|---|---|---|
| `setMask(mask: string)` | `void` | Parse and apply a new mask, resetting every slot. |
| `value()` | `string` | The formatted display string (filled slots and literals). |
| `setValue(v: string)` | `void` | Fill slots from a formatted string; characters that fit a slot are taken, others skipped. |
| `setRawValue(v: string)` | `void` |  |
| `setPlaceholder(p: string)` | `void` |  |
| `getPlaceholder()` | `string` |  |
| `setMaskPlaceholder(ch: string)` | `void` | The character shown for unfilled slots ("" = blank). Rebuilds the cells: widths derive from it. |
| `setMaxLength(n: int)` | `void` |  |
| `isComplete()` | `boolean` |  |
| `isEmpty()` | `boolean` |  |
| `clear()` | `void` |  |
| `selectAll()` | `void` |  |
| `hasSelection()` | `boolean` |  |
| `selectedText()` | `string` | The display text of the selected range, literals inside the range included. |
| `clearSelection()` | `void` |  |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setOnRawChange(fn: Function \| null)` | `void` |  |
| `setOnSubmit(fn: Function \| null)` | `void` |  |
| `setOnBlur(fn: Function \| null)` | `void` |  |
| `setOnComplete(fn: Function \| null)` | `void` | (raw: string, formatted: string) =&gt; void, when all slots become filled. |
| `setOnIncomplete(fn: Function \| null)` | `void` |  |
| `bindValue(ref: Ref&lt;string&gt;)` | `void` | Two-way: the ref follows every change, external changes refill the slots. |
| `bindRawValue(ref: Ref&lt;string&gt;)` | `void` |  |
| `setWidth(w: float)` | `void` | Width only: the height comes from the font and the theme padding. |
| `setSize(w: float, h: float)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |
| `setCursorFromCell(localX: float, shift: boolean)` | `void` | A click on a filled slot puts the cursor there; on an empty slot or outside every slot it snaps to the first empty slot. |
| `insertText(s: string)` | `void` | Distribute pasted characters into slots from the cursor; invalid ones are skipped. |
| `moveCursorLeft()` | `void` |  |
| `moveCursorLeftShift(shift: boolean)` | `void` |  |
| `moveCursorRight()` | `void` |  |
| `moveCursorRightShift(shift: boolean)` | `void` |  |
| `moveCursorHomeShift(shift: boolean)` | `void` |  |
| `moveCursorEndShift(shift: boolean)` | `void` |  |
| `setDebugSlots(v: boolean)` | `void` | A debug overlay outlining each slot cell. |
| `resetBlink()` | `void` |  |
| `getCursorPos()` | `int` |  |
| `setCursorPos(pos: int)` | `void` |  |
| `getSelStart()` | `int` |  |
| `getSelEnd()` | `int` |  |

## NumberStepper

Source: `src/widgets/text/numberstepper.tks`. Extends `Component`.

```ts
new NumberStepper(name: string, family: string, displaySize: float)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `setValue(v: float)` | `void` | Clamp to [min, max], update the text, fire onChange and the bound ref. |
| `setMin(v: float)` | `void` |  |
| `setMax(v: float)` | `void` |  |
| `setStep(v: float)` | `void` |  |
| `setPageStep(v: float)` | `void` |  |
| `setDecimals(n: int)` | `void` | Decimal places shown and accepted; negative is 0. Reformats the current value. |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `bindValue(ref: Ref&lt;float&gt;)` | `void` | Two-way sync with a Ref&lt;float&gt;: external writes set the value, stepper changes write the ref. |
| `setSize(w: float, h: float)` | `void` | The step buttons are square (height x height); the text field fills the rest. |
| `setEnabled(v: boolean)` | `void` |  |

## SearchBox

Source: `src/widgets/text/searchbox.tks`. Extends `Component`.

```ts
new SearchBox(name: string, family: string, displaySize: float)
```

Callback fields: `onChange`, `onSubmit`, `onBlur`, `onClear`, `onSearchStart`, `onSearchFinish`, `onSearchEmpty`.

| Method | Returns | Notes |
|---|---|---|
| `value()` | `string` |  |
| `setValue(v: string)` | `void` |  |
| `bindValue(ref: Ref&lt;string&gt;)` | `void` |  |
| `setPlaceholder(v: string)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |
| `setWidth(w: float)` | `void` | Width only; the height comes from the font and padding. |
| `setShowSearchIcon(v: boolean)` | `void` |  |
| `setShowClearButton(v: boolean)` | `void` |  |
| `clear()` | `void` | Empties the query, hides the clear button, clears results and fires onClear. |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setOnSubmit(fn: Function \| null)` | `void` |  |
| `setOnClear(fn: Function \| null)` | `void` |  |
| `setOnBlur(fn: Function \| null)` | `void` |  |
| `setDebounce(ms: float)` | `void` | Milliseconds; 0 searches on every change. |
| `cancelPendingSearch()` | `void` |  |
| `setMinQueryLength(n: int)` | `void` |  |
| `setSearchOnChange(v: boolean)` | `void` |  |
| `setSearchOnSubmit(v: boolean)` | `void` |  |
| `setOnSearchStart(fn: Function \| null)` | `void` |  |
| `setOnSearchFinish(fn: Function \| null)` | `void` |  |
| `setOnSearchEmpty(fn: Function \| null)` | `void` |  |
| `isSearching()` | `boolean` |  |
| `setSearchRunner(fn: Function \| null)` | `void` |  |
| `hasSelection()` | `boolean` |  |
| `selectAll()` | `void` |  |
| `insertText(s: string)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |
| `getPlaceholder()` | `string` |  |
| `getCursorPos()` | `int` |  |
| `clearVisible()` | `boolean` |  |

## Tag

Source: `src/widgets/text/tag.tks`. Extends `Component`.

```ts
new Tag(name: string, family: string, displaySize: float)
```

Callback fields: `onRemove`, `onToggle`.

| Method | Returns | Notes |
|---|---|---|
| `setText(text: string)` | `void` |  |
| `setRemovable(v: boolean)` | `void` | Show or hide the x affordance. |
| `setSelectable(v: boolean)` | `void` | Toggle-on-click behaviour. |
| `setSelected(v: boolean)` | `void` |  |
| `setOnRemove(fn: Function \| null)` | `void` |  |
| `setOnToggle(fn: Function \| null)` | `void` |  |
| `setPadding(top: float, right: float, bottom: float, left: float)` | `void` | Per-instance padding overriding the theme's. |
| `setSize(w: float, h: float)` | `void` |  |
| `sizeToContent()` | `void` | Size to the text plus padding (plus the x and its gap when removable), at least a circle. |

## TagBar

Source: `src/widgets/text/tagbar.tks`. Extends `Component`.

```ts
new TagBar(name: string, family: string, displaySize: float)
```

Callback fields: `onChange`, `onAddTag`, `onRemoveTag`.

| Method | Returns | Notes |
|---|---|---|
| `setTags(tags: string[])` | `void` | Replace the whole list. |
| `addTag(text: string)` | `void` |  |
| `removeTagAt(idx: int)` | `void` | Out-of-range indices are ignored. |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setOnAddTag(fn: Function \| null)` | `void` |  |
| `setOnRemoveTag(fn: Function \| null)` | `void` |  |
| `setPlaceholder(text: string)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |

## VisualLine

Source: `src/widgets/text/textarea.tks`.

One visual line: a rune range of the value, from a hard break or a word wrap (Go visualLine).

```ts
new VisualLine(runeStart: int, runeEnd: int)
```

## LineCol

Source: `src/widgets/text/textarea.tks`.

```ts
new LineCol(line: int, col: int)
```

## TextArea

Source: `src/widgets/text/textarea.tks`. Extends `Component`.

```ts
new TextArea(name: string, family: string, displaySize: float)
```

Callback fields: `onChange`.

| Method | Returns | Notes |
|---|---|---|
| `hasSelection()` | `boolean` |  |
| `selectedText()` | `string` |  |
| `selectAll()` | `void` |  |
| `clearSelection()` | `void` |  |
| `setValue(v: string)` | `void` |  |
| `setRows(n: int)` | `void` | Visible rows; the height follows (at least one). |
| `setMaxLength(n: int)` | `void` |  |
| `setCharFilter(fn: Function \| null)` | `void` | Newlines are always accepted regardless of the filter. |
| `setNumericOnly()` | `void` |  |
| `setAlphanumericOnly()` | `void` |  |
| `setAllowedChars(chars: string)` | `void` |  |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setSize(w: float, h: float)` | `void` |  |
| `bindValue(ref: Ref&lt;string&gt;)` | `void` | Follow a Ref&lt;string&gt; (the widget's own writes are not echoed back). |
| `insertText(text: string)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |
| `moveCursorLeft()` | `void` |  |
| `moveCursorLeftShift(shift: boolean)` | `void` |  |
| `moveCursorRight()` | `void` |  |
| `moveCursorRightShift(shift: boolean)` | `void` |  |
| `moveCursorWordLeftShift(shift: boolean)` | `void` |  |
| `moveCursorWordRightShift(shift: boolean)` | `void` |  |
| `moveCursorUp()` | `void` | The same x on the previous visual line (the start of the text on the first line). |
| `moveCursorUpShift(shift: boolean)` | `void` |  |
| `moveCursorDown()` | `void` | The same x on the next visual line (the end of the text on the last line). |
| `moveCursorDownShift(shift: boolean)` | `void` |  |
| `moveCursorHomeShift(shift: boolean)` | `void` |  |
| `moveCursorEndShift(shift: boolean)` | `void` |  |
| `moveCursorPageUpShift(shift: boolean)` | `void` |  |
| `moveCursorPageDownShift(shift: boolean)` | `void` |  |
| `selectWordAtCursor()` | `void` |  |
| `getVisualLines()` | `VisualLine[]` | The value split into visual lines: hard breaks (newline) and word wraps at the wrap width. |
| `setCursorFromClick(localX: float, localY: float, shift: boolean)` | `void` | Place the cursor at the character closest to local (x, y); shift extends from the anchor. |
| `resetBlink()` | `void` |  |
| `setComposition(text: string, selectionStart: int = 0, selectionLength: int = 0, replacementStart: int = -1, replacementLength: int = 0)` | `void` | Public for deterministic visual tests and host adapters. This never edits value. |

## WordRange

Source: `src/widgets/text/textinput.tks`.

```ts
new WordRange(lo: int, hi: int)
```

## TextInput

Source: `src/widgets/text/textinput.tks`. Extends `Component`.

```ts
new TextInput(name: string, family: string, displaySize: float)
```

Callback fields: `onChange`, `onSubmit`, `onBlur`.

| Method | Returns | Notes |
|---|---|---|
| `hasSelection()` | `boolean` |  |
| `selectedText()` | `string` |  |
| `selectAll()` | `void` |  |
| `clearSelection()` | `void` | Collapse the selection to the cursor. |
| `setValue(v: string)` | `void` |  |
| `setPlaceholder(p: string)` | `void` |  |
| `setMaxLength(n: int)` | `void` | Character limit (0 = none). |
| `setCharFilter(fn: Function \| null)` | `void` | Called for each typed or pasted character (one code point string): true accepts it. null clears. |
| `setNumericOnly()` | `void` |  |
| `setAlphanumericOnly()` | `void` |  |
| `setAllowedChars(chars: string)` | `void` |  |
| `setOnChange(fn: Function \| null)` | `void` |  |
| `setOnSubmit(fn: Function \| null)` | `void` |  |
| `setOnBlur(fn: Function \| null)` | `void` |  |
| `setKeyFilter(fn: Function \| null)` | `void` | Called before special-key handling; true skips the default handling of that key (Home, End). |
| `bindValue(ref: Ref&lt;string&gt;)` | `void` | Follow a Ref&lt;string&gt;: takes its value now and at every later external change. |
| `insertText(text: string)` | `void` | Insert at the cursor, replacing any selection. Newlines are stripped (single line). |
| `moveCursorLeft()` | `void` |  |
| `moveCursorLeftShift(shift: boolean)` | `void` |  |
| `moveCursorRight()` | `void` |  |
| `moveCursorRightShift(shift: boolean)` | `void` |  |
| `moveCursorWordLeftShift(shift: boolean)` | `void` |  |
| `moveCursorWordRightShift(shift: boolean)` | `void` |  |
| `moveCursorHomeShift(shift: boolean)` | `void` |  |
| `moveCursorEndShift(shift: boolean)` | `void` |  |
| `selectWordAtCursor()` | `void` | Select the word under the cursor. |
| `setPasswordMode(v: boolean)` | `void` |  |
| `isPasswordMode()` | `boolean` |  |
| `bindPasswordMode(ref: Ref&lt;boolean&gt;)` | `void` |  |
| `setWidth(w: float)` | `void` | Width only: the height comes from the font and theme padding. |
| `setSize(w: float, h: float)` | `void` |  |
| `setEnabled(v: boolean)` | `void` |  |
| `setCursorFromX(localX: float, shift: boolean)` | `void` | Place the cursor at the character closest to localX; shift extends from the anchor. |
| `resetBlink()` | `void` | Show the cursor immediately after a change and restart the blink timer. |
| `applyBorderColor(c: Color)` | `void` | Border colour override without touching other visuals (InputField validation state). |
| `setComposition(text: string, selectionStart: int = 0, selectionLength: int = 0, replacementStart: int = -1, replacementLength: int = 0)` | `void` | Public for deterministic visual tests and host adapters. This never edits value. |
| `getPlaceholder()` | `string` | Test-facing views (Go GetPlaceholder, SelRectVisible ...). |

---

URL: https://thicketscript.com/willowui/widgets/composites

# Composites

Larger widgets built from many smaller ones. Full method lists: [Composites API](../reference/composites.html).

## DataTable

`new DataTable(name, rowHeight)`. A table with a header, sortable and searchable columns, single or multi selection, a virtual scroll mode for large data sets, zebra striping and dividers.

| Area | Calls |
|---|---|
| Columns | `addColumn(new DataTableColumn(key, header))`, with `weight`, `fixedWidth`, `sortable`, `searchable`, `sortType` (`SORT_ALPHA`, `SORT_NUMERIC`, `SORT_CUSTOM`), `clipMode` (`CLIP_ELLIPSIS`, `CLIP_MASK`). Helpers: `labelColumn`, `meterColumn`, `selectionColumn`. |
| Data | `setItems(rows)` or `bindItems(reactiveArray)`. Each row is any value; a column's `key` names the field it shows. |
| Selection | `SELECTION_MODE_NONE`, `SELECTION_MODE_SINGLE`, `SELECTION_MODE_MULTI`; `bindSelectedIndexes(get, set)`; `setRowClickSelects`. |
| Search | `bindSearchFilter(Ref<string>)` or `bindSearchInput(textInput)`. |
| Scrolling | `SCROLL_MODE_VIRTUAL` (the default) or `SCROLL_MODE_STATIC`; `bindScrollPos`; after a sort, `ON_SORT_SCROLL_NONE`, `ON_SORT_SCROLL_TO_SELECTION` or `ON_SORT_SCROLL_TO_TOP`. |

In XML, `<DataTable>` takes the table settings as attributes and one `<Column>` child per column (see the [tag reference](../xml/tags.html#pseudo-elements)). Rows are always supplied in code.

## GradientEditor

`new GradientEditor(name, family, size)`. Edit a color gradient: add, move and recolor stops, and switch between horizontal, vertical and four-corner modes (`GRADIENT_MODE_H`, `GRADIENT_MODE_V`, `GRADIENT_MODE_FOUR_CORNER`). `bindValue(Ref<Gradient>)`, `setOnChange`, `setShowModeSelector`.

---

URL: https://thicketscript.com/willowui/widgets/containers

# Containers

Widgets that hold and organise other widgets or rows of data. Full method lists: [Containers API](../reference/containers.html). XML attributes and events: [tag reference](../xml/tags.html).

| Widget | What it is | Constructor |
|---|---|---|
| `Window` | A movable, optionally resizable and closeable window with a title bar and a `body`. Can be modal. | `new Window(name, title, family, size)` |
| `TabBar` | Tabs, each with its own page; `addTabPage(label, layout, spacing, padding)` returns the page. | `new TabBar(name, family, size)` |
| `List` | A scrolling list of `ListItem(data)` rows with selection; recycles row views, so it handles long lists. | `new List(name, itemHeight)` |
| `TileList` | A scrolling grid of tiles, for inventories and galleries. | `new TileList(name, tileW, tileH)` |
| `TreeList` | An expandable tree of `TreeNode`s. | `new TreeList(name, itemHeight)` |
| `SortableList` | A list the player reorders by dragging (or the keyboard). | `new SortableList(name, itemHeight)` |
| `SortableTreeList` | A tree the player reorders and reparents by dragging. | `new SortableTreeList(name, family, size)` |
| `TreeTable` | A tree with columns, sortable by column. | `new TreeTable(name, family, size)` |
| `Accordion` | Stacked sections that open and close; `exclusive` keeps one open at a time. | `new Accordion(name)` |
| `NavDrawer` | A panel that slides in from the left or right edge; `open()`, `close()`, `pinned`. | `new NavDrawer(name)` |
| `AnchorLayout` | An anchor-layout container with a background and border. | `new AnchorLayout(name)` |
| `TwoColumnLayout` | Label and control pairs in two aligned columns; `addRow(left, right)`. | `new TwoColumnLayout(name)` |

## Windows

Put content in `window.body`, add the window to the screen, then register it with `DEFAULT_WINDOW_MANAGER.add(window)` so clicking brings it to the front and focus moves with it. `setModal(true)` blocks the rest of the screen behind an overlay. `setEscResult("cancel")` and `setEnterResult("ok")` close the window on Escape or Enter and pass that string to `setOnResult(fn)`. Constants: `DEFAULT_WINDOW_WIDTH`, `DEFAULT_WINDOW_HEIGHT`, `WINDOW_TITLE_BAR_HEIGHT`.

## Lists

`setItems([...])` replaces the rows, `bindItems(reactiveArray)` follows a `ReactiveArray<ListItem>`, `bindSelected(Ref<int>)` follows and writes the selected index, `setOnChange(fn)` fires on selection. Rows draw `data` as text by default; the API page lists the hooks for custom row content.

## Example

```ts
import { DEFAULT_STAGE, DEFAULT_WINDOW_MANAGER, Label, List, ListItem, Ref, Screen, Window } from "willowui";

const screen: Screen = new Screen();

const win: Window = new Window("inventory", "Inventory", "default", 16.0);
win.setSize(300.0, 280.0);
win.setPosition(60.0, 60.0);
win.setResizable(true);

const picked: Ref<int> = new Ref<int>(0);
const list: List = new List("items", 28.0);
list.setSize(280.0, 180.0);
list.setItems([new ListItem("Potion"), new ListItem("Ether"), new ListItem("Lantern"), new ListItem("Rope")]);
list.bindSelected(picked);
win.body.addChild(list);

const status: Label = new Label("status", "Pick an item", "default", 14.0);
list.setOnChange((): void => { status.setText("Selected item " + (picked.peek() + 1)); });
win.body.addChild(status);

screen.add(win);
DEFAULT_WINDOW_MANAGER.add(win);
DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

---

URL: https://thicketscript.com/willowui/widgets/core

# Core widgets

The building blocks every screen uses. Full method lists: [Core API](../reference/core.html). XML attributes: [tag reference](../xml/tags.html).

| Widget | What it is | Constructor |
|---|---|---|
| `Component` | An invisible box that holds and lays out children. The base of every widget. | `new Component(name)` |
| `Panel` | A component with a background, border and corner radius. The usual container. | `new Panel(name)` |
| `Label` | A line (or wrapped block) of text. | `new Label(name, text, family, size)` |
| `Button` | A clickable button with text. | `new Button(name, text, family, size)` |
| `IconButton` | A button showing an icon from the theme's sprites. | `new IconButton(name)` |
| `Image` | A texture or theme sprite, with scale modes. | `new Image(name)` |
| `Tooltip` | Floating help shown on hover. | `new Tooltip(name)` |
| `ScrollBar` | A standalone scroll bar. | `new ScrollBar(name)` |
| `ScrollPanel` | A clipped viewport with scroll bars and wheel scrolling. | `new ScrollPanel(name)` |

## Panel

`setBackground(color)`, `setBorder(color, width)`, `setCornerRadii(tl, tr, br, bl)`, `setPadding(top, right, bottom, left)`. A panel with no explicit colors draws its theme entry for its variant.

## Label

`setText`, `bindText(ref)`, `setColor`, `setFontSize`, `setBold`, `setItalic`, `setAlign(...)` with `TEXT_ALIGN_LEFT`, `TEXT_ALIGN_CENTER` or `TEXT_ALIGN_RIGHT`, `setWrapWidth(px)` to wrap long text.

## Button and IconButton

`setOnClick(fn)`, `setText`, `bindText(ref)`, `setAutoSize(v)` to size to the text, `setSize`. `bindActive(ref)` shows a pressed-in state that follows a `Ref<boolean>`, for toggle-style buttons. `IconButton.setIconKey(key)` picks a sprite from the theme.

## Image

`setImage(texture)`, `setRegion(region)`, `setScaleMode(mode)` with `IMAGE_SCALE_STRETCH`, `IMAGE_SCALE_FIT`, `IMAGE_SCALE_FILL`, `IMAGE_SCALE_CENTER` or `IMAGE_SCALE_TILE`, `setCornerRadius`, `setAlpha`. An `Image` does not own a texture you give it: dispose the texture yourself.

In XML, `src="path"` takes bytes you registered with `registry.putAsset(path, bytes)`, and `atlas="key"` takes a theme sprite.

## Tooltip

Most of the time you do not make one: call `widget.setTooltipText("Saves the game", "default", 14.0)`. For rich content, build a `Tooltip`, fill it, and pass it to `widget.setTooltip(tt)`. Placement constants: `TOOLTIP_AUTO`, `TOOLTIP_ABOVE`, `TOOLTIP_BELOW`, `TOOLTIP_LEFT`, `TOOLTIP_RIGHT`, `TOOLTIP_FOLLOW_MOUSE`.

## ScrollPanel

Give it its visible size with `setSize`, add children, and set the scrollable size with `setContentSize(w, h)`. `setScrollX`, `setScrollY` scroll it from code.

## Example

```ts
import { Button, DEFAULT_STAGE, LAYOUT_VBOX, Label, Panel, Screen, TEXT_ALIGN_CENTER } from "willowui";

const screen: Screen = new Screen();
const card: Panel = new Panel("card");
card.layout = LAYOUT_VBOX;
card.spacing = 10.0;
card.setPadding(16.0, 16.0, 16.0, 16.0);
card.setBackground(Color.rgbaf(0.1, 0.11, 0.14, 1.0));
card.setCornerRadii(8.0, 8.0, 8.0, 8.0);
card.setPosition(40.0, 40.0);

const title: Label = new Label("title", "Quest complete", "default", 22.0);
title.setAlign(TEXT_ALIGN_CENTER);
card.addChild(title);

const body: Label = new Label("body", "You found the lost lantern. The keeper will want to hear about it.", "default", 15.0);
body.setWrapWidth(260.0);
card.addChild(body);

const ok: Button = new Button("ok", "Continue", "default", 16.0);
ok.setSize(120.0, 36.0);
ok.setTooltipText("Back to the map", "default", 14.0);
card.addChild(ok);
card.sizeToContent();
screen.add(card);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

---

URL: https://thicketscript.com/willowui/widgets/display

# Display widgets

Widgets that show information. Full method lists: [Display API](../reference/display.html). XML attributes: [tag reference](../xml/tags.html).

| Widget | What it is | Constructor |
|---|---|---|
| `Badge` | A small pill with a count or text, or a dot. | `new Badge(name, family, size)` |
| `ProgressBar` | A horizontal bar filled to a value, with an optional percentage label. | `new ProgressBar(name)` |
| `MeterBar` | A bar for a stat or resource, with a range. | `new MeterBar(name)` |
| `RichText` | Styled text from markup: bold, italic, colors, sizes, outlines, links, headings, lists. | `new RichText(name, family, size)` |
| `AnimatedImage` | Frames from an atlas strip, a list of regions or a GIF, played once, looped or ping-pong. | `new AnimatedImage(name)` |
| `StatWeb` | A radar chart of up to eight stats, optionally editable by dragging. | `new StatWeb(name, family, size)` |
| Toast | A short message that slides in and disappears. Shown through `showToast`. | (no constructor) |
| `Spacer` | Empty space of a fixed size, for layouts. | `new Spacer(name, w, h)` |

## Badge

`setCount(n)` (shows `N+` above `setMaxCount`), `setText`, `setDotMode(true)` for a plain dot. Its variant (`kind` in XML) picks the color.

## ProgressBar and MeterBar

`setRange(min, max)`, `setValue(v)`, `bindValue(ref)`. `ProgressBar.setShowLabel(true, family, size)` draws the percentage, `setFillColor(color)` overrides the theme.

## RichText

`setMarkup("Press <b>Space</b> to <color value=\"#ffcc00\">jump</color>")` parses the markup and throws on an unknown tag. `setWrapWidth`, `setAlign`, `setHeadingScale(h1, h2, h3)`. `onLinkClick` gets the URL of a clicked `<link>`. The markup tags (from `src/core/markup/markup.tks`) are: `b`, `i`, `u`, `strike`, `color value`, `size value`, `outline thickness color`, `span color size font`, `link url`, `icon value`, `br`, `h1` to `h3`, `ul`, `ol`, `li`. Inside an XML `<RichText>` element the same tags can be written as children, including the compact `<icon=sheet.png:3/>` form.

## AnimatedImage

`setAtlas(texture, frameW, frameH)`, `setFrames(regions)`, `loadGifBytes(bytes)`, `setFPS`, `setPlayMode(ANIM_PLAY_ONCE | ANIM_PLAY_LOOP | ANIM_PLAY_PING_PONG)`, `play()`.

## StatWeb

`setAxes([new StatAxis("STR", 0.0, 10.0, 7.0), ...])`, `setValue(index, value)`, `setEditable(true)` to let the player drag the points, `onValueChanged`.

## Toast

```ts
showToast("Game saved", VARIANT_SUCCESS, [withDuration(2.0)]);
```

Options: `withDuration`, `withDismissOnClick`, `withProgress`, `withOnDismiss`. `DEFAULT_TOAST_MANAGER` sets the corner (`TOAST_BOTTOM_RIGHT` and the other three).

## Example

```ts
import { Badge, DEFAULT_STAGE, LAYOUT_VBOX, Panel, ProgressBar, Ref, RichText, Screen } from "willowui";

const screen: Screen = new Screen();
const col: Panel = new Panel("col");
col.layout = LAYOUT_VBOX;
col.spacing = 12.0;
col.setPosition(40.0, 40.0);

const text: RichText = new RichText("intro", "default", 16.0);
text.setWrapWidth(320.0);
text.setMarkup("<b>Welcome back.</b> You have <color value=\"#ffcc00\">3 new quests</color>.");
col.addChild(text);

const xp: Ref<float> = new Ref<float>(40.0);
const bar: ProgressBar = new ProgressBar("xp");
bar.setSize(320.0, 18.0);
bar.setRange(0.0, 100.0);
bar.bindValue(xp);
col.addChild(bar);

const mail: Badge = new Badge("mail", "default", 13.0);
mail.setCount(3);
col.addChild(mail);
col.sizeToContent();
screen.add(col);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

---

URL: https://thicketscript.com/willowui/widgets/

# Widget catalogue

Each family has a guide page (what each widget is for, how to use it, an example) and a generated API page (every public constructor, method and callback, read from the source).

| Family | Guide | API |
|---|---|---|
| Core: Component, Panel, Label, Button, IconButton, Image, Tooltip, ScrollBar, ScrollPanel | [Core widgets](./core.html) | [API](../reference/core.html) |
| Display: Badge, ProgressBar, MeterBar, RichText, AnimatedImage, StatWeb, Toast, Spacer | [Display widgets](./display.html) | [API](../reference/display.html) |
| Interactive: Toggle, Checkbox, Radio, Slider, Select, OptionRotator, ToggleButtonBar, menus, Popover, ToolBar, DragHandle, pickers | [Interactive widgets](./interactive.html) | [API](../reference/interactive.html) |
| Text: TextInput, TextArea, MaskedInput, InputField, SearchBox, NumberStepper, Tag, TagBar, ColorPicker | [Text widgets](./text.html) | [API](../reference/text.html) |
| Containers: Window, TabBar, lists, trees, Accordion, NavDrawer, layouts | [Containers](./containers.html) | [API](../reference/containers.html) |
| Composites: DataTable, GradientEditor | [Composites](./composites.html) | [API](../reference/composites.html) |

## What every widget shares

All widgets extend `Component`, so these work everywhere:

| Method | Use |
|---|---|
| `setPosition(x, y)`, `setSize(w, h)` | Place and size it. In a Window body a placed child leaves the flow and its siblings keep flowing; other layout parents may override the position. |
| `setEnabled(v)`, `bindEnabled(ref)` | Disable it, or follow a `Ref<boolean>`. |
| `setVisible(v)`, `bindVisible(ref)` | Hide it, or follow a `Ref<boolean>`. |
| `setVariant(v)` | Pick a theme variant (`VARIANT_PRIMARY`, `VARIANT_DANGER` and so on). |
| `setTheme(theme)` | Give it (and its children) an explicit theme. |
| `setTooltipText(text, family, size)` | A one-line tooltip on hover. |
| `setContextMenu(menu)` | A right-click menu. |
| `setOnActivate(fn)` | Called when it, or a child, is clicked. |
| `dispose()` | Free it and everything it owns. |

Most constructors take a **name** first, then, for widgets that show text, a font family (`"default"`) and a size in pixels.

## Every widget in XML

Each widget's XML tag, with its attributes and events, is in the [tag reference](../xml/tags.html).

---

URL: https://thicketscript.com/willowui/widgets/interactive

# Interactive widgets

Controls the player clicks, drags or picks from. Full method lists: [Interactive API](../reference/interactive.html). XML attributes and events: [tag reference](../xml/tags.html).

Every value control has a two-way `bind...` method: the widget takes the ref's value, follows its changes, and writes the player's changes back into it.

| Widget | What it is | Constructor | Two-way binding |
|---|---|---|---|
| `Toggle` | An on/off switch. | `new Toggle(name)` | `bindValue(Ref<boolean>)` |
| `Checkbox` | A box with a label. | `new Checkbox(name, text, family, size)` | `bindValue(Ref<boolean>)` |
| `Radio` | A group of mutually exclusive options; `addOption(text, family, size)`. | `new Radio(name)` | `bindSelected(Ref<int>)` |
| `Slider` | Drag a thumb along a range; `setRange`, `setStep`, `setOrientation`. | `new Slider(name)` | `bindValue(Ref<float>)` |
| `Select` | A dropdown list of `SelectOption(label, value)`. | `new Select(name, options, family, size)` | `bindSelected(Ref<int>)`, `bindOptions(ReactiveArray)` |
| `OptionRotator` | Left and right arrows cycling through options, as in game settings. `setWrap`. | `new OptionRotator(name, options, family, size)` | `bindSelected(Ref<int>)`, `bindValue(Ref<string>)` |
| `ToggleButtonBar` | A segmented row of buttons, one selected; `addButton(label)`. | `new ToggleButtonBar(name, family, size)` | `bindSelected(Ref<int>)` |
| `MenuBar` | A desktop-style menu bar; `setEntries([new MenuBarEntry("File", items)])`. | `new MenuBar(name, family, size)` | |
| `ContextMenu` | A popup menu of `MenuItem`s; `setItems`, `showAt(x, y)`, or attach with `widget.setContextMenu(menu)` for right-click. | `new ContextMenu(family, size)` | |
| `Popover` | A floating panel anchored to a widget, with an optional title and close button; `open(trigger)`. | `new Popover(name)` | |
| `ToolBar` | A row or column of tool buttons and `ToolGroup`s, which clip, wrap or scroll when crowded. | `new ToolBar(name)` | `ToolGroup.bindSelected` |
| `DragHandle` | A grip you drag along an axis, for splitters and resizers. | `new DragHandle(name)` | |
| `TimePicker` | Hour, minute and optional second columns, 12 or 24 hour. | `new TimePicker(name, family, size)` | `bindTime(Ref<TimeValue>)` |
| `CalendarSelector` | A month grid for picking a date, inline or as a popup. | `new CalendarSelector(name, family, size)` | `bindDate(Ref<Date>)` |
| `KeybindInput` | Click, then press a key combination to capture it, for control remapping. | `new KeybindInput(name, family, size)` | `bindValue(Ref<KeyBinding>)` |
| `ImageCropper` | Drag a crop rectangle over an image. | `new ImageCropper(name)` | |

`MenuItem(label, onSelect)` has `disabled`, `separator` and `shortcut` (a display-only hint such as `"Ctrl+S"`) fields.

## Example

```ts
import { Checkbox, DEFAULT_STAGE, LAYOUT_VBOX, OptionRotator, Panel, Ref, Screen, Select, SelectOption, Slider, Toggle } from "willowui";

const screen: Screen = new Screen();
const form: Panel = new Panel("form");
form.layout = LAYOUT_VBOX;
form.spacing = 12.0;
form.setPosition(40.0, 40.0);

const music: Ref<boolean> = new Ref<boolean>(true);
const toggle: Toggle = new Toggle("music");
toggle.bindValue(music);
form.addChild(toggle);

const subtitles: Ref<boolean> = new Ref<boolean>(false);
const check: Checkbox = new Checkbox("subs", "Subtitles", "default", 15.0);
check.bindValue(subtitles);
form.addChild(check);

const volume: Ref<float> = new Ref<float>(70.0);
const slider: Slider = new Slider("volume");
slider.setSize(240.0, 24.0);
slider.setRange(0.0, 100.0);
slider.bindValue(volume);
form.addChild(slider);

const quality: Ref<int> = new Ref<int>(1);
const select: Select = new Select("quality", [
    new SelectOption("Low", "low"),
    new SelectOption("Medium", "medium"),
    new SelectOption("High", "high"),
], "default", 15.0);
select.setSize(200.0, 32.0);
select.bindSelected(quality);
form.addChild(select);

const difficulty: OptionRotator = new OptionRotator("difficulty", ["Easy", "Normal", "Hard"], "default", 15.0);
difficulty.setSize(220.0, 32.0);
form.addChild(difficulty);

form.sizeToContent();
screen.add(form);
DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

---

URL: https://thicketscript.com/willowui/widgets/text

# Text widgets

Widgets for typing and editing values. Full method lists: [Text API](../reference/text.html). XML attributes and events: [tag reference](../xml/tags.html).

| Widget | What it is | Constructor | Two-way binding |
|---|---|---|---|
| `TextInput` | A one-line text field with caret, selection, clipboard, placeholder, max length and password mode. | `new TextInput(name, family, size)` | `bindValue(Ref<string>)` |
| `TextArea` | A multi-line editor; `setRows(n)` sets its visible height. | `new TextArea(name, family, size)` | `bindValue(Ref<string>)` |
| `MaskedInput` | A field that follows a pattern, for dates, codes or phone numbers; `setMask`, `setMaskPlaceholder`. | `new MaskedInput(name, family, size)` | `bindValue`, `bindRawValue` |
| `InputField` | A TextInput with a label above or to the left, a required marker and a validation state and message. | `new InputField(name, family, size)` | `bindValue(Ref<string>)` |
| `SearchBox` | A field with a search icon, a clear button and a debounced change callback. | `new SearchBox(name, family, size)` | `bindValue(Ref<string>)` |
| `NumberStepper` | A number field with up and down buttons; `setMin`, `setMax`, `setStep`, `setPageStep`, `setDecimals`. | `new NumberStepper(name, family, size)` | `bindValue(Ref<float>)` |
| `Tag` | A chip with text, optionally removable or selectable. | `new Tag(name, family, size)` | |
| `TagBar` | A field that turns typed entries into tags; `addTag(text)`. | `new TagBar(name, family, size)` | |
| `ColorPicker` | A swatch that opens a picker with hex, RGB, HSV, HSL and float modes, and optional alpha. | `new ColorPicker(name, family, size)` | `bindValue(Ref<Color>)` |

Callbacks: text fields have `setOnChange`, `setOnSubmit` (Enter) and `setOnBlur`; SearchBox adds `setOnClear`; ColorPicker has `setOnChange` while dragging and `setOnCommit` when the choice is final; Tag has `setOnRemove` and `setOnToggle`.

InputField validation: `setValidationState(VALIDATION_ERROR)` (or `VALIDATION_WARNING`, `VALIDATION_SUCCESS`, `VALIDATION_NONE`) with `setValidationMessage("...")`. Label placement: `LABEL_ABOVE` or `LABEL_LEFT`.

## Example

```ts
import { DEFAULT_STAGE, LAYOUT_VBOX, Label, NumberStepper, Panel, Ref, Screen, TextInput, computed } from "willowui";

const screen: Screen = new Screen();
const form: Panel = new Panel("form");
form.layout = LAYOUT_VBOX;
form.spacing = 10.0;
form.setPosition(40.0, 40.0);

const heroName: Ref<string> = new Ref<string>("");
const nameField: TextInput = new TextInput("name", "default", 16.0);
nameField.setWidth(260.0);
nameField.setPlaceholder("Hero name");
nameField.bindValue(heroName);
form.addChild(nameField);

const level: Ref<float> = new Ref<float>(1.0);
const stepper: NumberStepper = new NumberStepper("level", "default", 16.0);
stepper.setMin(1.0);
stepper.setMax(99.0);
stepper.bindValue(level);
form.addChild(stepper);

const preview: Label = new Label("preview", "", "default", 16.0);
const summary: Ref<any> = computed((): any => (heroName.value == "" ? "Nameless" : heroName.value) + ", level " + level.value);
preview.bindText(summary as Ref<string>);
form.addChild(preview);

form.sizeToContent();
screen.add(form);
DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

---

URL: https://thicketscript.com/willowui/xml/binary

# Binary templates

A template can be compiled ahead of time to a small binary file, `.xmlui`. Loading it skips the XML parser and the expression parser at start-up, and a broken template is caught when you compile rather than when a player opens the screen.

## When to use it

| Use XML text when | Use binary when |
|---|---|
| You are still designing the screen | The screen is finished and ships with the game |
| You want [hot reload](./hot-reload.html) | Start-up time matters, or there are many templates |
| The template is generated at run time | You want compile errors at build time |

The two forms build identical widgets. Keep the `.xml` as the source and treat the `.xmlui` as a build output.

## Compile with xmluic

willowui offers the `xmluic` tool. From a project that lists willowui as a package:

```sh
thicket tool xmluic compile ui/settings.xml ui/settings.xmlui
```

`thicket tool xmluic ui/settings.xml ui/settings.xmlui` (without `compile`) does the same. A template error prints its line and column and the tool exits with a failure code.

The tool knows the built-in tags. For a template that uses [custom widgets](./custom-widgets.html), list them in a widget manifest, a JSON file that maps each tag to the module that defines it, and pass it with `--widgets`:

```sh
thicket tool xmluic compile --widgets ui/widgets.json ui/rating.xml ui/rating.xmlui
```

```json
{
  "StarRating": { "import": "./star_rating.tks", "attributes": { "maxStars": "int" } }
}
```

Each entry needs an `import` path. `attributes` is optional and maps an attribute name to a type name. A bare string (`"StarRating": "./star_rating.tks"`) is the short form, and the entries may also sit inside a top-level `"widgets"` object. The tool only reads the manifest to learn the tag names; it does not load your widget code. At run time, still call `registerWidget` before you load the `.xmlui`.

## Load it

```ts
import { Files } from "fs";
const bytes: Buffer = await Files.readFile(moduleDir + "/ui/settings.xmlui");
reg.registerBinary("settings", bytes);
const root: Component = reg.instantiate("settings", controller, screen);
```

`registerBinary` throws if the bytes are not a valid template (`template "settings": ...`).

## The format

For tools that want to read or write it. All numbers are little-endian.

| Part | Content |
|---|---|
| Magic | The four bytes `X`, `U`, `I`, `0x00`. |
| Version | `u16`, currently `1`. |
| Node | Component type and text (strings); a `u32` attribute count, each attribute as name, static value, expression and an is-event flag; a `u32` directive count, each as a type byte, expression and loop variable name; a `u32` child count and the child nodes, depth first; then the theme patch (a string, empty for none). |
| Strings | A `u32` byte length, then the UTF-8 bytes. |
| Expressions | Stored as their parsed tree, so no expression is parsed at load time. Literal numbers are stored as 64-bit floats. |

`encodeIR(node)` and `decodeIR(bytes)` are the public encoder and decoder, and `compileXML(text)` gives the `IRNode` tree to encode, so you can build your own pipeline step.

---

URL: https://thicketscript.com/willowui/xml/bindings

# Bindings and events

## The data provider

A template talks to one object, the **data provider**, through two methods:

```ts
interface DataProvider {
    lookupRef(path: string): any;      // answer a name used in an expression
    callMethod(name: string): boolean; // run an event handler; true when handled
}
```

An `on:` handler with arguments (below) calls `callMethod(name, args)` with a second, array argument, so a controller that takes arguments declares `callMethod(name: string, args?: any[]): boolean`. The one-argument form still works for handlers without arguments.

Pass it as the second argument of `instantiate`. Your screen's controller is the usual choice: give it both methods and pass `this`. An object that lacks either method is treated as no provider, so bindings show nothing and events do nothing.

## bind:

`bind:attr="expression"` evaluates the expression, applies the result through the attribute's setter, and does it again whenever a ref the expression read changes. Updates land at the next frame boundary.

```xml
<Panel layout="vbox" spacing="8">
    <Label bind:text="playerName" />
    <ProgressBar width="200" range="0,100" bind:value="health" />
    <Button text="Attack" bind:enabled="health > 0" />
    <Label bind:color="danger ? '#ff5555' : '#d4d4d4'" text="Status" />
</Panel>
```

Any settable attribute in the [tag reference](./tags.html) can be bound, including the common ones (`enabled`, `visible`, `width`, `variant`, `padding` and so on). A **static-only** attribute (one the widget reads when it is built, such as `Select options` or `List itemHeight`) ignores `bind:`.

For the controller this means: return a `Ref` (or `computed`) from `lookupRef` for anything that changes, and set the ref. A plain value works too, but the binding then never updates.

```ts
import { Component, Controller, DEFAULT_STAGE, Ref, Screen, TemplateRegistry, computed } from "willowui";

const TEMPLATE: string = `
<Panel layout="vbox" spacing="8" padding="16">
    <Label bind:text="summary" />
    <ProgressBar width="200" range="0,100" bind:value="health" />
    <Button text="Hit" on:click="hit" bind:enabled="health > 0" />
</Panel>`;

class Hud implements Controller {
    health: Ref<float> = new Ref<float>(100.0);
    summary: Ref<any> = new Ref<any>("");

    onCreate(screen: Screen): void {
        this.summary = computed((): any => "HP: " + this.health.value);
        const reg: TemplateRegistry = new TemplateRegistry();
        reg.registerXML("hud", TEMPLATE);
        const root: Component = reg.instantiate("hud", this, screen);
        screen.add(root);
    }
    onUpdate(dt: float): void {}
    onDispose(): void {}

    lookupRef(path: string): any {
        if (path == "health") { return this.health; }
        if (path == "summary") { return this.summary; }
        return null;
    }
    callMethod(name: string): boolean {
        if (name == "hit") {
            this.health.set(Math.max(0.0, this.health.peek() - 15.0));
            return true;
        }
        return false;
    }
}

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(new Screen().withController(new Hud()));
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

### Two-way bindings

`bind:value`, `bind:checked`, `bind:selected` and `bind:rawValue` write back. When the expression is just the name of a ref (a name `lookupRef` answers with a `Ref`, or a `ui:for` variable holding one), the template calls the widget's own `bindValue`, `bindSelected` or `bindRawValue` with that ref: the widget shows the ref's value, follows its changes, and writes the user's edits into it. `bind:checked` uses `bindValue`.

```xml
<Panel layout="vbox" spacing="8">
    <TextInput bind:value="name" width="220" />
    <Select options="Warrior,Mage,Rogue" bind:selected="classIndex" />
    <Checkbox text="Hardcore" bind:checked="hardcore" />
</Panel>
```

Any other expression (`count + 1`, `name ? name : 'Hero'`, a plain value) has no ref to write into, so it binds one way through the attribute's setter. The [forms recipe](../recipes/forms.html) shows a two-way form end to end.

## on:

`on:event="method"` calls `callMethod("method")` when the widget fires that event. The widget's new value is not passed along, so read it from your bound ref or from the widget.

`on:event="method(arg, ...)"` passes arguments. Each argument is an expression, evaluated when the event fires, in the same scope as `bind:`. Inside a `ui:for` row that includes the row's item and `index`, so each copy can say which row it is:

```xml
<Panel layout="vbox" spacing="4">
    <Button ui:for="item in inventory" bind:text="item.name" on:click="select(item, index)" />
    <Button text="Save" on:click="save" />
</Panel>
```

Clicking the second row calls `callMethod("select", [inventory[1], 1])`. The bare `on:click="save"` still calls `callMethod("save")`, and `save()` with empty parentheses passes an empty array.

| Event | Fired by |
|---|---|
| `click` | Button and IconButton when clicked. On any other tag, the component's activate callback, which a click on the component or any child bubbles up to. |
| `change` | Toggle, Checkbox, TextInput, MaskedInput, SearchBox, InputField, Slider, NumberStepper, TabBar, ToggleButtonBar, Select, OptionRotator, Radio, TimePicker, List, TileList, SortableList, SortableTreeList, ColorPicker, StatWeb, GradientEditor |
| `submit` | TextInput, MaskedInput, SearchBox, InputField (Enter) |
| `blur` | TextInput, MaskedInput, SearchBox, InputField (focus left) |
| `clear` | SearchBox (the clear button) |
| `select` | List, TileList, SortableList, SortableTreeList |
| `reorder` | SortableList, SortableTreeList |
| `close` | Window, NavDrawer, Popover |
| `open` | Popover |
| `commit` | ColorPicker |
| `remove` | Tag (its remove button) |
| `toggle` | Accordion (a section opened or closed), Tag (selected state) |
| `linkClick` | RichText (a `<link>` was clicked) |
| `crop` | ImageCropper |
| `capture` | KeybindInput (a new binding was captured) |

Any other event name, or a known name on a tag that does not fire it, is registered with `Component.setOnEvent(name, handler)`. A custom widget fires it with `this.fireEvent(name)`. See [Custom widgets](./custom-widgets.html).

Without a provider (`instantiateStatic`, or a controller missing `callMethod`), `on:` attributes do nothing.

## Lifetime

Each binding is an effect owned by its component, and also tracked by the screen you pass to `instantiate`. Disposing the component or the screen stops it. You never stop bindings by hand.

---

URL: https://thicketscript.com/willowui/xml/custom-widgets

# Custom widgets

`registerWidget` adds your own tag to one registry. The tag then works like a built-in one: it takes the common attributes, your own attributes (static or bound), and `on:` events your widget fires.

```ts
import { AttrSetter, Component, Controller, DEFAULT_STAGE, LAYOUT_HBOX, Label, Ref, Screen, TemplateRegistry } from "willowui";

// A row of stars. Clicking a star sets the rating and fires "change".
class StarRating extends Component {
    stars: Label[] = [];
    value: int = 0;

    constructor(name: string) {
        super(name);
        this.layout = LAYOUT_HBOX;
        this.spacing = 4.0;
        this.setMaxStars(5);
    }

    setMaxStars(n: int): void {
        for (const s of this.stars) { this.removeChild(s); s.dispose(); }
        this.stars = [];
        for (let i: int = 0; i < n; i++) {
            const star: Label = new Label(this.name + "-star-" + i, "*", "default", 24.0);
            const index: int = i + 1;
            star.setInteractable(true);
            star.setOnActivate((): void => { this.setValue(index); this.fireEvent("change"); });
            this.stars.push(star);
            this.addChild(star);
        }
        this.setValue(this.value);
    }

    setValue(v: int): void {
        this.value = v;
        for (let i: int = 0; i < this.stars.length; i++) {
            this.stars[i].setColor(i < v ? Color.rgbaf(1.0, 0.8, 0.2, 1.0) : Color.rgbaf(0.4, 0.4, 0.4, 1.0));
        }
    }
}

const TEMPLATE: string = `
<Panel layout="vbox" spacing="8" padding="16">
    <StarRating name="stars" maxStars="5" bind:value="rating" on:change="rated" />
    <Label bind:text="'Rating: ' + rating" />
</Panel>`;

class RatingScreen implements Controller {
    rating: Ref<int> = new Ref<int>(3);
    screen: Screen | null = null;

    onCreate(screen: Screen): void {
        this.screen = screen;
        const reg: TemplateRegistry = new TemplateRegistry();
        const setters: Map<string, AttrSetter> = new Map<string, AttrSetter>();
        setters.set("value", (c: Component, v: any): void => { (c as StarRating).setValue(v as int); });
        setters.set("maxStars", (c: Component, v: any): void => { (c as StarRating).setMaxStars(parseInt("" + v) as int); });
        reg.registerWidget("StarRating", (name: string): Component => new StarRating(name), setters);
        reg.registerXML("rating", TEMPLATE);
        screen.add(reg.instantiate("rating", this, screen));
    }
    onUpdate(dt: float): void {}
    onDispose(): void {}

    lookupRef(path: string): any {
        if (path == "rating") { return this.rating; }
        return null;
    }
    callMethod(name: string): boolean {
        if (name == "rated") {
            const w: StarRating = (this.screen as Screen).findByName("stars") as StarRating;
            this.rating.set(w.value);
            return true;
        }
        return false;
    }
}

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(new Screen().withController(new RatingScreen()));
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

## What registerWidget takes

| Argument | Meaning |
|---|---|
| `typeName` | The tag name. It must not be a built-in tag, or `registerWidget` throws. Register before `registerXML`, so the compiler knows the name. |
| `factory` | `(name: string) => Component`. Called once per element. `name` is the element's `name` attribute, or the tag name when there is none. |
| `setters` | Optional `Map<string, AttrSetter>`, where `AttrSetter` is `(c: Component, v: any) => void`. Each entry handles one attribute. They are merged over the common setters, so `width`, `layout`, `variant` and the rest keep working. |

A setter receives the attribute's value: a **string** for a static attribute (`maxStars="5"` gives `"5"`), or the evaluated value for a `bind:` (a number, a boolean, a string). Convert accordingly.

## Events

`on:anything` on a custom tag registers the handler with `setOnEvent(name, handler)`. Fire it from your widget with `this.fireEvent(name)`. `on:click` is wired to the component's activate callback, as on every tag.

## Compiling to .xmlui

`xmluic` learns your custom tags from a widget manifest passed with `--widgets`. See [Binary templates](./binary.html#compile-with-xmluic).

## Children

Child elements of a custom tag are instantiated and added with `addChild`, so a custom container works with no extra code. If your widget keeps its content in an inner component (as `Window` keeps a body), override `contentTarget()` to return it.

---

URL: https://thicketscript.com/willowui/xml/directives

# Directives

Directives are `ui:` attributes. They change the structure of what gets built rather than a single property.

| Directive | Status | What it does |
|---|---|---|
| `ui:show="expr"` | Works | Shows the element while the expression is truthy, hides it otherwise. Reactive. |
| `ui:if="expr"` | Works, as `ui:show` | Today it behaves exactly like `ui:show`: the element is always built, and only its visibility follows the expression. |
| `ui:for="item in list"` | Works | Builds one copy of the element for each item, and rebuilds the copies when the list changes. |
| `ui:else-if="expr"`, `ui:else` | Compile error | `ui:else is not supported yet; use ui:show with the negated condition` (and the same for `ui:else-if`). Use `ui:show` with the opposite condition. |
| `ui:key="expr"` | Compile error | `ui:key is not supported yet; ui:for rebuilds rows on change`. |
| `ui:ref`, anything else | Compile error | `unknown directive ui:...` (and `ui:ref` is rejected outright). |

## ui:show

```xml
<Panel layout="vbox" spacing="8">
    <Button text="Show details" on:click="toggleDetails" />
    <Panel ui:show="detailsOpen" layout="vbox" padding="8">
        <Label text="Here are the details." />
    </Panel>
    <Label text="Details are hidden." ui:show="!detailsOpen" />
</Panel>
```

A hidden element keeps its place in the tree and its state (a text field keeps what was typed). Whether a hidden child still takes space depends on the parent's layout, so test the look you want.

## ui:for

`ui:for="name in expression"` repeats the element. Inside it, `name` is the current item, `name.field` reads a field of it (a `Map` key, a `ReactiveRecord` field, or an object field), and `index` is the row's position, counting from 0.

```xml
<Panel layout="vbox" spacing="4">
    <Label text="Party" fontSize="18" />
    <Label ui:for="hero in party" bind:text="hero.name + ' (level ' + hero.level + ')'" />
</Panel>
```

The expression may give a plain array or a `ReactiveArray`. With a `ReactiveArray` (or a `Ref` holding an array), adding, removing or replacing items rebuilds the copies. The rebuild disposes every old copy and builds new ones, so widget state inside the copies (a half-typed field, a scroll position) does not survive a change to the list.

Copies are inserted where the element sits, so siblings before and after it keep their order, and several `ui:for` elements can share one parent.

```ts
import { Component, Controller, DEFAULT_STAGE, ReactiveArray, Screen, TemplateRegistry } from "willowui";

const TEMPLATE: string = `
<Panel layout="vbox" spacing="4" padding="16">
    <Button ui:for="task in tasks" bind:text="'Done: ' + task" on:click="finish(index)" />
    <Button text="Add task" on:click="addTask" />
</Panel>`;

class Tasks implements Controller {
    tasks: ReactiveArray<string> = new ReactiveArray<string>(["Write docs", "Check samples"]);

    onCreate(screen: Screen): void {
        const reg: TemplateRegistry = new TemplateRegistry();
        reg.registerXML("tasks", TEMPLATE);
        const root: Component = reg.instantiate("tasks", this, screen);
        screen.add(root);
    }
    onUpdate(dt: float): void {}
    onDispose(): void {}

    lookupRef(path: string): any {
        if (path == "tasks") { return this.tasks; }
        return null;
    }
    callMethod(name: string, args?: any[]): boolean {
        if (name == "addTask") {
            this.tasks.push("Task " + (this.tasks.length + 1));
            return true;
        }
        if (name == "finish" && args != null) {
            this.tasks.removeAt((args as any[])[0] as int);
            return true;
        }
        return false;
    }
}

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(new Screen().withController(new Tasks()));
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

For long lists (hundreds of rows), prefer a `List`, `TreeList` or `DataTable`, which recycle row views, over `ui:for`, which builds a full widget per item.

## Combining

An element may carry several directives and bindings at once:

```xml
<Panel layout="vbox">
    <Button ui:for="slot in slots" bind:text="slot.label" bind:enabled="slot.unlocked" on:click="useSlot(slot)" />
</Panel>
```

Each copy passes its own `slot` to `useSlot`, so the controller knows which one was clicked. See [handlers with arguments](./bindings.html#on).

---

URL: https://thicketscript.com/willowui/xml/expressions

# Expressions

`bind:` attributes, `ui:` directives and <code v-pre>{{ }}</code> interpolations hold an **expression**: a small language for reading your data and combining it. It is not ThicketScript. It has no calls, no assignment and no indexing, on purpose: logic lives in the controller, and the template only reads.

```xml
<Panel layout="vbox" spacing="8">
    <Label bind:text="name ? 'Hello, ' + name + '!' : 'Type your name'" />
    <Button text="Buy" bind:enabled="gold >= price" />
    <Panel ui:show="!loading &amp;&amp; items" />
</Panel>
```

## Values

| Kind | Written as |
|---|---|
| Number | `42`, `3.5` |
| String | `'single'` or `"double"` quotes. Inside an attribute that uses double quotes, use single. Escapes: `\n`, `\t`, `\\`, and a backslash before any other character keeps that character (`\'`). |
| Boolean | `true`, `false` |
| Nothing | `nil` |
| A name | `count`, `user.name`, `item.price` |

## Names

A name is looked up in this order:

1. **Loop variables** from an enclosing `ui:for`, innermost first. A dotted name whose first part is a loop variable walks into that value: map keys, a `ReactiveRecord`'s fields, or plain object fields.
2. **The controller**: `lookupRef(path)` is called with the whole name, dots included (`"user.name"`). Your controller decides what that means.

If the answer is a `Ref` (or a `computed`), its current value is used and the binding **subscribes** to it: when the ref changes, the expression runs again. That is the whole reactive story. Return refs from `lookupRef` for anything that changes.

A name nobody answers is `nil`.

## Operators

From lowest to highest precedence:

| Operators | Meaning |
|---|---|
| `c ? a : b` | Conditional. Right-associative. |
| `a \|\| b` | Or. Short-circuits. The result is `true` or `false`. |
| `a && b` | And. Short-circuits. In XML write `&amp;&amp;`. |
| `a == b`, `a != b` | Equality. Two strings compare as text, anything else as numbers. |
| `<`, `<=`, `>`, `>=` | Comparison, as numbers. In XML write `&lt;` for `<`. |
| `+`, `-` | Add and subtract. `+` joins strings if either side is a string. |
| `*`, `/`, `%` | Multiply, divide, remainder. Dividing by zero gives `0`. `%` works on whole parts. |
| `!a`, `-a` | Not, negate. |
| `( )` | Grouping. |

### Truthiness

`!`, `&&`, `||`, `? :` and `ui:show` treat these as false: `nil`, `false`, `0` and the empty string `""`. Everything else is true. So `ui:show="items"` hides a panel while `items` is `nil`, and `name ? ... : ...` tests for an empty string.

### Comparisons

When both sides of `==` or `!=` are strings, they compare as text: `name == 'Bob'` is true only for `Bob`, and `name != ''` is true for any name that is not empty. Otherwise both sides are converted to numbers first: booleans become `0` and `1`, numeric strings parse, and any other string becomes `0`. `<`, `<=`, `>` and `>=` always compare as numbers.

## Interpolation

Inside element text, <code v-pre>{{ }}</code> marks an expression:

```xml
<Label>Level {{level}}: {{hp}} / {{maxHp}} HP</Label>
```

The text becomes a concatenation of literal parts and expressions. An unclosed <code v-pre>{{</code> or a piece that does not parse is kept as literal text.

## Errors

A syntax error in `bind:`, `ui:if`, `ui:show`, `ui:for` or `ui:key` fails the compile with a `TemplateError` naming the attribute. A runtime problem (a missing name, a wrong type) never throws: the value becomes `nil`, `0` or `""`, and a binding whose evaluation fails simply skips that update.

## In code

The expression API is public, which is handy for tests or for your own widgets: `parseExpression(src)` returns an `ExprNode`, `evalExpression(node, new EvalContext(provider))` evaluates it against any `DataProvider`.

---

URL: https://thicketscript.com/willowui/xml/hot-reload

# Hot reload

`HotReloader` watches a template file on disk. When you save it, the screen's template tree is rebuilt from the new XML, keeping your controller and its refs, so the data on screen stays as it was. It can watch a theme JSON file too.

It is a development tool. Ship templates as text or [binary](./binary.html) and leave the reloader out of release builds.

## Use it

Your project needs the `fs` system and `permissions: { fs: true }`. `HotReloader` and `newHotReloader` come from the package root:

```ts
import { Files } from "fs";
import { Controller, DEFAULT_STAGE, HotReloader, Ref, Screen, TemplateRegistry, newHotReloader } from "willowui";

const XML_PATH: string = moduleDir + "/ui/main.xml";

class MainScreen implements Controller {
    title: Ref<string> = new Ref<string>("Edit ui/main.xml and save");
    reloader: HotReloader | null = null;

    onCreate(screen: Screen): void {
        const reg: TemplateRegistry = new TemplateRegistry();
        Files.readText(XML_PATH).then((xml: string): void => {
            reg.registerXML("main", xml);
            screen.add(reg.instantiate("main", this, screen));
            newHotReloader(reg, screen, this, "main", XML_PATH).then((hr: HotReloader): void => {
                this.reloader = hr;
            });
        });
    }
    onUpdate(dt: float): void {}
    onDispose(): void {
        const hr: HotReloader | null = this.reloader;
        if (hr != null) { (hr as HotReloader).stop(); }
    }

    lookupRef(path: string): any {
        if (path == "title") { return this.title; }
        return null;
    }
    callMethod(name: string): boolean { return false; }
}

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(new Screen().withController(new MainScreen()));
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

`newHotReloader(registry, screen, controller, templateName, xmlPath)` reads the file, then starts watching it.

## What a reload does

1. The file is polled every 50 ms (ThicketScript has no file-watch API). A change counts once the file's size and timestamps have been stable for 200 ms, so an editor's save-in-steps triggers one reload, not several.
2. If the bytes are the same as before, nothing happens.
3. The XML is recompiled. If it has an error, the error is reported and **the old tree stays on screen**, so a typo never blanks the screen.
4. The screen's template tree is cleared (its bindings stopped, its components disposed) and the new template is instantiated with the same controller.

Raw willow nodes added with `screen.addNode` survive a reload, because only components are cleared. Anything a controller built in code alongside the template is removed with the rest of the screen's components, so build such pieces inside the template, or re-add them.

## Themes

`await reloader.watchTheme(jsonPath)` also watches a theme JSON file. On a change it recompiles the theme and applies it to every top-level component of the screen. Images the theme names (atlas pages, nine-slices) are not re-read, only the JSON.

## Methods

| Method | Use |
|---|---|
| `stop()` | Stop watching. Call it in `onDispose`. |
| `reload()` | Reload the template now (returns a Promise). |
| `reloadTheme()` | Reload the theme now (returns a Promise). |
| `watchTheme(path)` | Start watching a theme file. |

---

URL: https://thicketscript.com/willowui/xml/

# XML templates

An XML template describes a tree of widgets in markup. willowui compiles it once, then builds live widgets from it as often as you like. Templates are a good fit for screens with many controls (forms, settings, inventories, editors), where code would be mostly `new`, `setSize` and `addChild`.

```xml
<Panel layout="vbox" spacing="12" padding="20">
    <Label bind:text="'Clicks: ' + clicks" fontSize="20" />
    <Button text="Click me" on:click="add" />
    <Label text="That is a lot of clicks." ui:show="clicks > 4" />
</Panel>
```

Every element is a widget. Plain attributes configure it. Three prefixes connect it to your code:

| Prefix | Example | Meaning |
|---|---|---|
| `bind:` | `bind:text="'Clicks: ' + clicks"` | Evaluate an [expression](./expressions.html) and keep the attribute in step with it. |
| `on:` | `on:click="add"`, `on:click="select(item)"` | Call a method on the controller when the widget fires the event, with optional arguments. |
| `ui:` | `ui:show="clicks > 4"` | A [directive](./directives.html): show, hide or repeat the element. |

## The pieces

| Piece | What it is |
|---|---|
| `TemplateRegistry` | Compiles templates, stores them by name and instantiates them. |
| The controller | Your object. Its `lookupRef(path)` answers names used in expressions, and its `callMethod(name, args?)` runs event handlers. |
| `instantiate(name, controller, screen)` | Builds the widget tree and returns its root component. |

## A complete app

```ts
import { Component, Controller, DEFAULT_STAGE, Ref, Screen, TemplateRegistry } from "willowui";

const TEMPLATE: string = `
<Panel layout="vbox" spacing="12" padding="20">
    <Label bind:text="'Clicks: ' + clicks" fontSize="20" />
    <Button text="Click me" on:click="add" />
    <Label text="That is a lot of clicks." ui:show="clicks > 4" />
</Panel>`;

class CounterScreen implements Controller {
    clicks: Ref<int> = new Ref<int>(0);

    onCreate(screen: Screen): void {
        const reg: TemplateRegistry = new TemplateRegistry();
        reg.registerXML("counter", TEMPLATE);
        const root: Component = reg.instantiate("counter", this, screen);
        root.setPosition(24.0, 24.0);
        screen.add(root);
    }
    onUpdate(dt: float): void {}
    onDispose(): void {}

    // Names used in bind: and ui: expressions.
    lookupRef(path: string): any {
        if (path == "clicks") { return this.clicks; }
        return null;
    }

    // Names used in on: attributes. Return true when the name was handled.
    callMethod(name: string): boolean {
        if (name == "add") {
            this.clicks.set(this.clicks.peek() + 1);
            return true;
        }
        return false;
    }
}

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(new Screen().withController(new CounterScreen()));
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

How it works:

1. `registerXML` parses and compiles the text. A mistake (an unknown tag, a bad expression) throws a `TemplateError` with the line and column.
2. `instantiate` builds the widgets. For each `bind:` it starts a reactive effect, so when `clicks` changes, the label text and the `ui:show` visibility update on the next frame.
3. Clicking the button calls `callMethod("add")`.

Because the screen is passed in, its bindings are stopped when the screen is disposed.

## Loading templates from files

Keep templates in `.xml` files and read them with the `fs` system (add `"fs"` to `systems` and `permissions: { fs: true }` to `thicket.json`):

```ts
import { Files } from "fs";
const templateXML: string = await Files.readText(moduleDir + "/template.xml");
```

To ship a template without parsing XML at start-up, compile it to the [binary form](./binary.html). To edit a template while the app runs, use [hot reload](./hot-reload.html).

## Registry settings

| Method | Use |
|---|---|
| `setFonts(fonts, defaultFamily)` | A map from the names used in `font="..."` to font families, and the default family. Pass `null` for no map. |
| `setFontSize(size)` | The default font size for text widgets (14 when not set). Each element can override it with `fontSize`. |
| `setTheme(theme)` | Register a compiled theme's custom variant names, so `variant="card"` resolves. |
| `setThemeJSON(json)` | Compile a theme from JSON text, register its variants, and keep the text so templates can patch it with an inline `<Theme>`. |
| `putAsset(path, bytes)` | Hand over image bytes for `Image src="..."` and `AnimatedImage gif="..."`. Setters cannot read files, so you load the bytes first. |
| `registerWidget(tag, factory, setters)` | Add your own tag. See [Custom widgets](./custom-widgets.html). |
| `registerBinary(name, bytes)` | Register a precompiled `.xmlui` template. |
| `instantiateStatic(name, screen)` | Instantiate with no controller. Bindings and events then do nothing. |
| `get(name)` | The compiled tree (`IRNode`), or null. |

`newTemplateRegistryWithFont(path, size)` makes a registry whose default font is the TTF or OTF file at `path`.

## In this section

- [Syntax and attributes](./syntax.html): the XML rules, value formats and the attributes every tag takes.
- [Expressions](./expressions.html): the small language inside `bind:` and `ui:`.
- [Bindings and events](./bindings.html): `bind:` and `on:` in depth.
- [Directives](./directives.html): `ui:show`, `ui:if`, `ui:for`.
- [Layout from XML](./layout.html)
- [Variants and inline themes](./themes.html)
- [Custom widgets](./custom-widgets.html)
- [Binary templates](./binary.html)
- [Hot reload](./hot-reload.html)
- [Tag reference](./tags.html): every tag with its attributes and events.

---

URL: https://thicketscript.com/willowui/xml/layout

# Layout from XML

Every layout field has an attribute of the same name (see [Layout](../guide/layout.html) for what each one means). This page shows the common shapes. The `xml-layout` example in the willowui repository has a tab for each.

## Stacks

```xml
<Panel layout="hbox" spacing="16" padding="12">
    <Panel layout="vbox" spacing="6" padding="10" background="#1a1c22" cornerRadius="6">
        <Button text="Top" size="160,36" />
        <Button text="Middle" size="160,36" variant="neutral" />
        <Button text="Bottom" size="160,36" />
    </Panel>
    <Panel layout="vbox" spacing="6" padding="10" size="180,200" justify="end" align="center">
        <Label text="Pushed to the bottom, centered" />
        <Button text="OK" size="80,30" />
    </Panel>
</Panel>
```

`justify` places children along the stack (`start`, `center`, `end`, `space-between`), `align` across it.

## Automatic size

A container with children and no size grows to fit them, padding included. Give only one of `width` or `height` and the other is fitted. Give `size` to fix both, for example to make `justify` meaningful.

## Grow

Inside a vbox or hbox, children with `grow` share the space the fixed children leave:

```xml
<Panel layout="hbox" size="600,40" spacing="8">
    <Button text="Fixed" size="100,40" />
    <Button text="Grows 1" grow="1" height="40" />
    <Button text="Grows 2" grow="2" height="40" />
</Panel>
```

## Grid

```xml
<Panel layout="grid" gridColumns="3" spacing="6" padding="10">
    <Button text="1" size="60,40" />
    <Button text="2" size="60,40" />
    <Button text="3" size="60,40" />
    <Button text="4" size="60,40" />
    <Button text="5" size="60,40" />
    <Button text="6" size="60,40" />
</Panel>
```

## Flow

Children run left to right and wrap when the next one does not fit the width:

```xml
<Panel layout="flow" width="300" spacing="6" flow-row-gap="6">
    <Tag text="fire" />
    <Tag text="ice" />
    <Tag text="lightning" />
    <Tag text="poison" />
    <Tag text="holy" />
</Panel>
```

## Anchors

```xml
<Panel name="hud" layout="anchor" size="700,420" padding="10">
    <Label anchor="top-left" text="HP 100" />
    <Label anchor="top-right" text="Gold 250" />
    <Label anchor="center" text="Paused" fontSize="32" />
    <Button anchor="bottom-right" offsetX="-8" offsetY="-8" text="Menu" />
</Panel>
```

Offsets are pixels from the anchor point.

## Two columns

`TwoColumnLayout` takes its children in pairs: left, right, left, right. An odd last child is added on its own.

```xml
<TwoColumnLayout leftWidth="120" gap="12" rowSpacing="8">
    <Label text="Name" />
    <TextInput width="200" placeholder="Hero" />
    <Label text="Class" />
    <Select options="Warrior,Mage,Rogue" size="200,32" />
    <Label text="Hardcore" />
    <Toggle />
</TwoColumnLayout>
```

`columnRatio` sizes the left column as a fraction instead of `leftWidth`. `leftAlign` and `rightAlign` align each column.

## Tabs

Each `<Tab>` inside a `<TabBar>` becomes a page. The tab's own layout attributes apply to its page, and its children go inside.

```xml
<TabBar size="500,300">
    <Tab label="General" layout="vbox" spacing="8" padding="12">
        <Checkbox text="Show tips" />
        <Checkbox text="Autosave" />
    </Tab>
    <Tab label="Audio" layout="vbox" spacing="8" padding="12">
        <Label text="Master volume" />
        <Slider width="240" range="0,100" />
    </Tab>
</TabBar>
```

## Windows

A `Window`'s children go into its body, which stacks them vertically.

```xml
<Window title="Inventory" size="320,240" resizable="true" closeable="true">
    <Label text="Three potions" />
    <Button text="Use one" on:click="usePotion" />
</Window>
```

Add the instantiated window to `DEFAULT_WINDOW_MANAGER` so it stacks and focuses with other windows. The [Containers](../widgets/containers.html) page shows a window built in code.

## Scrolling

`ScrollPanel` takes `size`, `background`, `scrollX` and `scrollY`. Its content size is set in code with `setContentSize(w, h)`, so name it and size it after `instantiate`.

---

URL: https://thicketscript.com/willowui/xml/syntax

# Syntax and attributes

## The document

A template is one root element with any number of children. The root is usually a `Panel` or another container.

```xml
<Panel layout="vbox" spacing="8">
        <Label text="Name" />
    <TextInput placeholder="Your name" width="240" />
</Panel>
```

The parser is small and forgiving:

| Rule | Detail |
|---|---|
| Tag names | Case-sensitive, and must be a [known tag](./tags.html) or one you registered. Anything else is a compile error. |
| Attribute quotes | Double or single quotes. An unquoted value runs to the next space or `>`. |
| Valueless attributes | `<Window modal>` means `modal="true"`. |
| Entities | `&amp;`, `&lt;`, `&gt;`, `&quot;`, `&apos;` and numeric references (`&#9733;`, `&#x2605;`). Unknown entities stay as written. |
| Skipped | Comments, processing instructions (`<?xml ...?>`) and `<!DOCTYPE>`-style directives. |
| CDATA | `<![CDATA[ ... ]]>` is plain text. |
| Closing tags | An end tag closes the innermost open element whatever its name. Write matching tags anyway: the next reader will thank you. |
| Prefixes | `bind:`, `on:` and `ui:` on attributes have meaning. A prefix on an element name is dropped. |

Escape `<` and `&` inside attribute values (`&lt;`, `&amp;`). That matters in expressions: write `count &lt; 10`, or flip it to `10 > count`.

## Text content

Text between the tags of an element becomes its `text`, and it may contain <code v-pre>{{expression}}</code> interpolations:

```xml
<Label>Hello, {{name}}! You have {{count}} new messages.</Label>
```

This is the same as `bind:text="'Hello, ' + name + '! You have ' + count + ' new messages.'"`. A piece that fails to parse stays as literal text. Text without <code v-pre>{{</code> is a plain value.

`RichText` is the exception: markup children such as `<b>` and `<color>` are kept as markup. The tags are listed on [Display widgets](../widgets/display.html#richtext).

## Attribute kinds

| Form | Example | When it is applied |
|---|---|---|
| Static | `text="Save"` | Once, when the widget is built. |
| Bound | `bind:text="title"` | Now, and again whenever a ref the expression reads changes. |
| Event | `on:click="save"`, `on:click="select(item)"` | Calls `callMethod("save")` when the widget fires it. With arguments, calls `callMethod("select", [item])`. |
| Directive | `ui:show="ready"` | Structural: visibility or repetition. |

Each tag has a fixed set of attributes it understands. An attribute it does not know is ignored without an error, so a typo shows up as "nothing happened". The [tag reference](./tags.html) lists them all.

## Value formats

| Kind | Format | Examples |
|---|---|---|
| Number | Decimal | `width="240"`, `spacing="8.5"` |
| Boolean | `true` or `1` is true, anything else is false | `modal="true"` |
| Color | `#RRGGBB` or `#RRGGBBAA`. Any other form is transparent black. | `color="#7ab3ff"`, `background="#00000080"` |
| Size | `width,height` | `size="200,32"` |
| Insets | `all`, `vertical,horizontal`, or `top,right,bottom,left` | `padding="12"`, `padding="8,16"`, `padding="4,8,4,8"` |
| Border | `color,width` | `border="#2e3340,1"` |
| Range | `min,max` | `range="0,100"` |
| List | Comma-separated, blanks dropped | `options="Easy,Normal,Hard"` |
| Alignment | `start`, `center`, `end`, `space-between` | `align="center"` |
| Anchor | `top-left`, `top-center`, `top-right`, `middle-left`, `center`, `middle-right`, `bottom-left`, `bottom-center`, `bottom-right` | `anchor="bottom-right"` |
| Variant | `primary`, `secondary`, `accent`, `neutral`, `danger`, `success`, `warning`, `info`, `custom1` to `custom40`, or a name your theme defines | `variant="danger"` |

## Common attributes

Every tag accepts these.

| Attribute | Meaning |
|---|---|
| `name` (or `id`) | The component's name. `screen.findByName("save")` finds it after `instantiate`. `name` wins if both are given. |
| `x`, `y` | An offset added on top of the position the layout gives. In a parent with no layout, this is the position. |
| `width`, `height` | Size in pixels. Many tags also take `size="w,h"`. |
| `minWidth`, `minHeight`, `maxWidth`, `maxHeight` | Size limits for layout. |
| `enabled` | `false` disables the widget. |
| `visible` | `false` hides it. |
| `layout` | `vbox`, `hbox`, `grid`, `flow`, `anchor`, or anything else for none. |
| `spacing` | Gap between children. |
| `gridColumns` | Columns for `layout="grid"`. |
| `flow-row-gap` | Gap between wrapped rows for `layout="flow"`. |
| `padding`, `margin` | Insets (see value formats). |
| `align`, `justify` | Cross-axis and main-axis alignment of children. |
| `fill` | `width`, `height` or `both`: stretch to the parent. |
| `grow` | Flex weight inside a vbox or hbox. |
| `zIndex` | Drawing order among siblings. |
| `variant` | The theme variant. |

In an anchor layout, children also take `anchor`, `offsetX` and `offsetY` (or `anchorOffsetX` and `anchorOffsetY`).

## Errors

`registerXML` throws a `TemplateError` whose message starts with `line:col:`, for example:

```text
template "settings": 4:9: unknown component type "Buton"
```

Other compile errors: a bad expression (`bind:text expression error: ...`), an unknown directive (`unknown directive ui:hide`), a malformed `ui:for`, and a `<Theme>` element that is empty or not valid JSON.

`instantiate` throws when a template name is not registered (`template "x" not found`). If a widget fails to build, the half-built tree is disposed before the error reaches you.

---

URL: https://thicketscript.com/willowui/xml/tags

# XML tag reference

The compiler accepts exactly these 57 tag names, plus any custom tag you register with `registerWidget`. Any other name is a compile error (`unknown component type`).

**Static** attributes are read once, when the widget is built (the factory reads them). **Settable** attributes go through a setter, so they work both as plain values and as `bind:` expressions. A static-only attribute given as `bind:` is ignored.

## Common attributes

Every tag takes these (plus `name`, or `id` as an alias, which names the component):

`x`, `y`, `enabled`, `visible`, `layout`, `spacing`, `gridColumns`, `flow-row-gap`, `variant`, `padding`, `margin`, `zIndex`, `align`, `justify`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight`, `fill`, `grow`, `width`, `height`.

See [Attributes and values](./syntax.html#common-attributes) for what each one does.

## Tags

| Tag | Static (build time) | Settable (also bindable) | Events (`on:`) |
|---|---|---|---|
| `Panel` |   | alignItems, background, border, cornerRadius, justifyContent, size | click |
| `Label` | font | align, bold, color, fontSize, italic, size, text, wrapWidth | click |
| `Button` | font, fontSize | autoSize, size, text | click |
| `IconButton` |   | icon, size | click |
| `Toggle` |   | value | change, click |
| `Checkbox` | font, fontSize | checked, text | change, click |
| `TextInput` | fontSize | maxLength, placeholder, size, value, width | change, submit, blur, click |
| `TextArea` | fontSize | maxLength, rows, size, value | click |
| `Slider` |   | orientation, range, size, step, value | change, click |
| `ScrollBar` |   | orientation, size, value | click |
| `ProgressBar` | showLabel | fillColor, range, size, value | click |
| `MeterBar` |   | range, size, value | click |
| `List` |   | itemHeight, selected, size | change, select, click |
| `TileList` | tileHeight, tileWidth | columns, selected, size | change, select, click |
| `TreeList` | itemHeight | leafOnlySelection, selectable, size | click |
| `TabBar` | fontSize | overflowMode, selected, size | change, click |
| `ScrollPanel` |   | background, scrollX, scrollY, size | click |
| `Window` | font, fontSize | closeable, enterResult, escResult, minHeight, minWidth, modal, movable, resizable, size, title | close, click |
| `RichText` | fontSize | align, color, headingScale, markup, wrapWidth | linkClick, click |
| `Radio` |   | columns, selected, verticalFirst | change, click |
| `Component` |   |   | click |
| `NumberStepper` | fontSize | decimals, max, min, pageStep, size, step, value | change, click |
| `ToggleButtonBar` | buttons, fontSize | selected, size | change, click |
| `AnchorLayout` |   | background, border, cornerRadius, size | click |
| `TwoColumnLayout` |   | background, border, columnRatio, gap, leftAlign, leftWidth, rightAlign, rowSpacing, size | click |
| `Tab` |   |   | click |
| `Spacer` |   | size | click |
| `Select` | fontSize | options, selected, size | change, click |
| `OptionRotator` | fontSize | options, selected, size, wrap | change, click |
| `RadioButton` |   |   | click |
| `DragHandle` |   | axis, gripStyle, max, min, size | click |
| `InputField` | fontSize | label, labelPosition, maxLength, placeholder, required, size, validationMessage, validationState, value, width | change, submit, blur, click |
| `SearchBox` | fontSize | debounceMs, minQueryLength, placeholder, showClearButton, showSearchIcon, size, value, width | change, submit, clear, blur, click |
| `Badge` | font, fontSize | count, dotMode, kind, maxCount, size, text | click |
| `StatWeb` | fontSize | editable, fillEnabled, size | change, click |
| `NavDrawer` |   | anchor, pinned, size, width | close, click |
| `ImageCropper` |   | showGrid, size | crop, click |
| `ColorPicker` | fontSize | color, defaultMode, showAlpha, size | change, commit, click |
| `ToolBar` |   | orientation, overflowMode, size, wrap | click |
| `SortableTreeList` | fontSize | allowCrossLevel, allowReparent, selected, size | change, select, reorder, click |
| `Image` |   | alpha, atlas, cornerRadius, scaleMode, size, src | click |
| `AnimatedImage` |   | atlas, cornerRadius, fps, gif, playMode, size | click |
| `CalendarSelector` | font, fontSize | date, popupMode, size | click |
| `TimePicker` | fontSize | format, showSeconds, size, time | change, click |
| `KeybindInput` | font, fontSize | size | capture, click |
| `MaskedInput` | fontSize | mask, maskPlaceholder, maxLength, placeholder, rawValue, size, value, width | change, submit, blur, click |
| `SortableList` | itemHeight | dragEnabled, handleSide, keyboardReorderEnabled, selected, showHandles, size | change, select, reorder, click |
| `Tag` | font, fontSize | kind, removable, selectable, selected, size, text | remove, toggle, click |
| `TagBar` | font, fontSize | placeholder, size | click |
| `Accordion` | fontSize | animated, exclusive, expanded, size | toggle, click |
| `DataTable` | headerHeight, onSortScroll, rowClickSelects, rowHeight, scrollMode, selectionMode, showColumnDividers, showHeader, showRowDividers, showScrollBar, zebraStriping |   | click |
| `Column` |   |   | click |
| `Section` |   |   | click |
| `Tooltip` |   | anchor, clampToScreen, fadeIn, fadeOut, hideDelay, showDelay, size, text | click |
| `Popover` | title | contentSize, preferredSide, showCloseButton, size | close, open, click |
| `GradientEditor` | fontSize | showModeSelector, size | change, click |
| `MenuBar` | fontSize | size | click |

`click` on a tag other than Button and IconButton is wired to the component's activate callback. Any other event name that the tag does not handle goes to `Component.setOnEvent(name, handler)`, so a custom widget can fire it.

## Pseudo-elements

- `<Column>`: Only inside `<DataTable>`: adds a column. Attributes: key, header, tooltip, weight, sortable, searchable, fixedWidth, sortType (numeric, custom), textAlign (center, right), clipMode (mask).
- `<RadioButton>`: Only inside `<Radio>`: adds one option. Attribute: label.
- `<Section>`: Only inside `<Accordion>`: adds a section whose children are stacked in a vbox panel. Attributes: id, label.
- `<Tab>`: Inside `<TabBar>`: adds a tab page. Attribute: label, plus any common attribute (layout, spacing, padding...) applied to the page. Its children go into the page.
- `<Theme>`: a JSON theme patch, not a component. See [Variants and inline themes](./themes.html).

## Configuring the rest in code

An attribute that is not in a tag's row has no effect in XML. Give the element a `name` and configure it in code after `instantiate` (for example list items, menu entries and table rows, which have no XML form).

---

URL: https://thicketscript.com/willowui/xml/themes

# Variants and inline themes

## variant=

Every widget draws in one **variant** of its theme entry. The built-in names are `primary` (the default), `secondary`, `accent`, `neutral`, `danger`, `success`, `warning` and `info`. There are also 56 numbered slots, `custom1` and up; XML accepts `custom1` to `custom40` by number.

```xml
<Panel layout="hbox" spacing="8">
    <Button text="Save" />
    <Button text="Cancel" variant="secondary" />
    <Button text="Delete" variant="danger" />
</Panel>
```

`Badge` and `Tag` also take `kind="..."`, which sets the same thing.

## Your own variant names

A theme can declare named variants, for example `card`, `muted` or `heading`. Each name is given one of the custom slots, and theme entries style it like any built-in variant.

```json
{
    "variants": ["card", "heading", "muted"],
    "colors": { "fg": "#D4D4D4", "fgMuted": "#9E9E9E", "surface1": "#1A1C22", "border": "#2E3340" },
    "components": {
        "label": {
            "heading": { "textColor": { "default": "$fg" } },
            "muted":   { "textColor": { "default": "$fgMuted" } }
        },
        "panel": {
            "card": {
                "backgroundColor": { "default": "$surface1" },
                "borderColor": { "default": "$border" },
                "cornerRadius": 8
            }
        }
    }
}
```

Give the compiled theme to the registry so the names resolve, then set it on the instantiated root so the widgets draw with it:

```ts
import { Component, DEFAULT_STAGE, Screen, TemplateRegistry, Theme, loadTheme } from "willowui";

const THEME_JSON: string = `{
    "variants": ["card", "muted"],
    "colors": { "fgMuted": "#9E9E9E", "surface1": "#1A1C22" },
    "components": {
        "label": { "muted": { "textColor": { "default": "$fgMuted" } } },
        "panel": { "card": { "backgroundColor": { "default": "$surface1" }, "cornerRadius": 8 } }
    }
}`;

const TEMPLATE: string = `
<Panel variant="card" layout="vbox" spacing="6" padding="12">
    <Label text="Profile" />
    <Label variant="muted" text="Last seen 3 minutes ago" />
</Panel>`;

const screen: Screen = new Screen();
const theme: Theme = loadTheme(THEME_JSON);
const reg: TemplateRegistry = new TemplateRegistry();
reg.setTheme(theme);
reg.registerXML("card", TEMPLATE);
const root: Component = reg.instantiate("card", null, screen);
root.setTheme(theme);
screen.add(root);

DEFAULT_STAGE.setScene(engine.root2d);
DEFAULT_STAGE.add(screen);
App.onFrame((dt: float): void => { DEFAULT_STAGE.update(dt); });
```

An unknown variant name falls back to `primary`. Variant names are not case-sensitive.

## Inline theme patches

A template can carry its own theme tweaks in a `<Theme>` element. Its text is a JSON **merge patch** (RFC 7396) applied to the registry's base theme: keys you give replace or extend the base, and a key set to `null` removes it.

```xml
<Panel layout="vbox" spacing="8" padding="12">
    <Theme>
        { "components": { "button": { "primary": { "backgroundColor": { "default": "#2a6a3a" } } } } }
    </Theme>
    <Label text="This screen has green buttons." />
    <Button text="Continue" />
</Panel>
```

Rules:

- The registry needs the base theme as JSON text: call `reg.setThemeJSON(json)` instead of `setTheme`. Without it, instantiating a patched template throws `inline <Theme> patches require SetThemeJSON on the registry`.
- Put `<Theme>` directly inside the **root** element. Only the root's patch is applied.
- The `<Theme>` text must be valid JSON, or the template does not compile.
- The merged theme is compiled when you instantiate and set on the returned root. Other templates from the same registry keep the base theme.

## Theme files

Theme files can also be compiled with `thicket tool themec <theme-dir> -o <file>.theme` and loaded with `loadThemeAny(path)` from `willowui`, which accepts a compiled `.theme`, a theme folder, or a single `.json` and caches the compile. The [Theming guide](../guide/theming.html) covers the theme file, nine-slice images and themec.

---

URL: https://thicketscript.com/gamekit/

# gamekit

<SiteArt src="/img/portal-gamekit.webp" alt="Illustration: a forest workshop bench at night with gears, a small clockwork figure and wooden game pieces" :width="1536" :height="1024" banner eager />

gamekit gives a game its structure: entities and components, a world that runs your systems in phases, scenes, input actions, assets, saves, and tools for testing all of it without a window. It is a **package** written entirely in ThicketScript, with no native code, and it sits on top of [willow](../willow/).

You build the game. gamekit supplies small parts that each do one job and that you wire together yourself. There is no `Game` base class to inherit from and nothing runs until you call it.

## A first taste

A world with one moving ball, stepped by the runtime's fixed tick:

```ts
import { ComponentKey, Entity, PhaseSchedule, World } from "gamekit";

class Position {
    x: float;
    y: float;
    constructor(x: float, y: float) {
        this.x = x;
        this.y = y;
    }
}

class Velocity {
    dx: float;
    dy: float;
    constructor(dx: float, dy: float) {
        this.dx = dx;
        this.dy = dy;
    }
}

const POSITION: ComponentKey<Position> = new ComponentKey<Position>("position");
const VELOCITY: ComponentKey<Velocity> = new ComponentKey<Velocity>("velocity");

const world: World = new World();
world.registerStore(POSITION);
world.registerStore(VELOCITY);

const ball: Entity = world.createEntity();
world.put(ball, POSITION, new Position(0.0, 0.0));
world.put(ball, VELOCITY, new Velocity(60.0, 30.0));

const schedule: PhaseSchedule = new PhaseSchedule();
schedule.addPhase("simulate", [], true);
schedule.addSystem("simulate", (w: World, dt: float, tick: int): void => {
    w.query2(POSITION, VELOCITY).each((entity: Entity, p: Position, v: Velocity): void => {
        p.x += v.dx * dt;
        p.y += v.dy * dt;
    });
});

App.tps = 10.0;
App.onTick((): void => {
    schedule.run(world, App.tickDelta, App.tick);
    const p: Position = world.getRequired(ball, POSITION);
    console.log("tick " + App.tick + ": ball at " + p.x + ", " + p.y);
    if (App.tick >= 4) {
        App.quit();
    }
});
```

```text
tick 0: ball at 6, 3
tick 1: ball at 12, 6
tick 2: ball at 18, 9
tick 3: ball at 24, 12
tick 4: ball at 30, 15
```

This is a console program: it needs no window, so it runs in a terminal and in tests. [Getting started](./getting-started.html) walks through it line by line and then puts it on screen.

## What is in the box

gamekit is split into **families**. Use one, some or all of them.

| Family | What it gives you | Guide |
|---|---|---|
| `core` | Entities and component keys, events and pipelines, attributes, state machines, effects, conditions, actions, interactions, definitions and prefabs, assets, gauges, weighted picks, 2D transforms and a spatial index. | [Entities](./guide/entities.html) |
| `ecs` | A `World` with one store per component, queries, deferred commands, phase schedules and a ticker that steps the world on the runtime tick. | [World and systems](./guide/world-and-systems.html) |
| `app` | Scenes, a scene stack and a scene coordinator, screen layers, focus, and input actions with routing, recording and replay. | [Scenes](./guide/scenes.html), [Input](./guide/input.html) |
| `save` | Codecs, versioned save schemas with migrations, save slots with backups and autosaves, and a settings store. | [Saves](./guide/saves.html) |
| `audio` | A music director that owns what is playing, on top of the core audio system. | [Utilities](./guide/utilities.html#music) |
| `willow` | Bindings that draw your game records as willow nodes, and a pointer and key bridge. | [Drawing with willow](./guide/willow-presentation.html) |
| `ui` | Scene windows and screen windows on [willowui](../willowui/). | [Windows](./guide/ui-windows.html) |
| `testing` | Deterministic clocks and schedulers, a fake asset loader, debug snapshots, scenarios and traces. | [Testing](./guide/testing-and-debug.html) |

## Add it to a project

```json5
{
    entry: "app.tks",
    systems: ["willow", "bitmap"],
    packages: { gamekit: "../gamekit-tks" },
}
```

`packages` points at the gamekit folder. You list the `willow` and `bitmap` systems yourself, because a package's systems are never inherited. gamekit brings willowui with it; list `willowui` yourself only when your own code imports it (see [Windows with willowui](./guide/ui-windows.html)). Add a `window` section when the game needs one; without it the program is a console app.

Most names come from the package root, `import { World } from "gamekit";`. The `willow`, `ui` and `testing` families import from their folders, for example `import { SimulationClock } from "gamekit/src/testing";`.

## Where to go next

<SiteGrid :cols="3">
<SiteCard title="Getting started" label="Start" href="./getting-started.html">

A minimal game with an entity and a system, first in a terminal, then in a window.

</SiteCard>
<SiteCard title="How gamekit is built" label="Concepts" href="./guide/mental-model.html">

The few ideas behind every family: explicit ownership, time you pass in, and parts you opt into.

</SiteCard>
<SiteCard title="Recipes" label="How-to" href="./recipes.html">

Short answers to common jobs: spawning, cooldowns, pausing, replays and saves.

</SiteCard>
<SiteCard title="Examples" label="Projects" href="./examples.html">

Five example projects that come with gamekit, from a card game to a console tactics match.

</SiteCard>
<SiteCard title="Reference" label="API" href="./reference/">

Every public class, interface and enum, by family, generated from the source.

</SiteCard>
<SiteCard title="willow" label="Below gamekit" href="../willow/">

The 2D engine gamekit draws with: nodes, quads, cameras and transitions.

</SiteCard>
</SiteGrid>

gamekit is at version `0.1.0-rc1`, a release candidate, so its API can still change before its first release.

---

URL: https://thicketscript.com/gamekit/examples

# Examples

gamekit comes with five example projects in its `examples/` folder. Each is a complete project: run it with `thicket run` from its folder.

| Example | Window | What it shows |
|---|---|---|
| `puzzle` | yes | A card-matching game with a willowui shell. `src/PuzzleShell.tks` holds the rules, `src/PuzzleShellApp.tks` the app. |
| `dungeon` | yes | A top-down dungeon crawler. `src/DungeonDemo.tks` holds the simulation, `src/DungeonWillowApp.tks` the app. |
| `scene-fade` | yes | A title scene replaced by a play scene with a willow fade, through `SceneStack`. |
| `window-layers` | yes | Scene windows, modal focus and screen windows with `SceneWindowLayer`. |
| `tactics` | no | A console tactics match that prints a transcript and exits. |

A project with a `window` section in its `thicket.json5` is a window app and stays open until the window closes. A console app exits when its work is done.

## The tactics match

`tactics` is the most complete use of gamekit in one place, and it runs in a terminal:

```sh
cd examples/tactics
thicket run play.tks
```

It uses definitions, entities with typed components and effects, world queries, conditions, transactional actions, interaction offers, attributes, state machines, a phase schedule with deferred commands, fixed stepping, seeded randomness, save schemas, input recording and replay, asset scopes and scenes. Its grid, teams, units and rules all live in the example, not in gamekit.

Its `commit` phase is the flush boundary that removes a defeated unit before the `outcome` phase checks who won. gamekit's tests run a full match, a save and resume in the middle, and a recorded-input replay across several seeds, and require the same final state and transcript from each.

## Rules without a window

The `puzzle` and `dungeon` rules classes need no window to run, and gamekit's tests drive them without opening the UI. Keeping rules in their own class, apart from the app class that draws them, is the pattern to copy.

---

URL: https://thicketscript.com/gamekit/getting-started

# Getting started

This page builds the smallest useful gamekit program: one entity, two components and one system, stepped by the runtime's fixed tick. Then it moves the same idea into a window with a scene, input and a drawn square.

You need `thicket` and a copy of the gamekit folder (`gamekit-tks`) with the willowui folder (`willowui-tks`) beside it. gamekit finds willowui through its own `packages`, so the two folders sit side by side.

## 1. Make a project

```text
mygame/
  thicket.json5
  app.tks
gamekit-tks/
willowui-tks/
```

`thicket.json5`:

```json5
{
    entry: "app.tks",
    systems: ["willow", "bitmap"],
    packages: { gamekit: "../gamekit-tks" },
}
```

There is no `window` section yet, so this is a console program. willow works without a window, which is what lets gamekit code run in a terminal and in headless tests.

## 2. Components are plain classes

```ts
import { ComponentKey, Entity, PhaseSchedule, World } from "gamekit";

class Position {
    x: float;
    y: float;
    constructor(x: float, y: float) {
        this.x = x;
        this.y = y;
    }
}

class Velocity {
    dx: float;
    dy: float;
    constructor(dx: float, dy: float) {
        this.dx = dx;
        this.dy = dy;
    }
}

const POSITION: ComponentKey<Position> = new ComponentKey<Position>("position");
const VELOCITY: ComponentKey<Velocity> = new ComponentKey<Velocity>("velocity");
```

A component is any class. It needs no base class. A `ComponentKey<T>` names a kind of component and carries its type, so reading a component back gives you a `Position`, not an `any`. The string label is for debugging only; two keys with the same label are still different keys.

## 3. A world holds the entities

```ts
const world: World = new World();
world.registerStore(POSITION);
world.registerStore(VELOCITY);

const ball: Entity = world.createEntity();
world.put(ball, POSITION, new Position(0.0, 0.0));
world.put(ball, VELOCITY, new Velocity(60.0, 30.0));
```

`registerStore` gives the world one store per key. `createEntity` makes an entity the world owns, and `put` files a component in that key's store, where queries can find it.

## 4. A system is a function

```ts
const schedule: PhaseSchedule = new PhaseSchedule();
schedule.addPhase("simulate", [], true);
schedule.addSystem("simulate", (w: World, dt: float, tick: int): void => {
    w.query2(POSITION, VELOCITY).each((entity: Entity, p: Position, v: Velocity): void => {
        p.x += v.dx * dt;
        p.y += v.dy * dt;
    });
});
```

A `PhaseSchedule` runs systems in named phases, in the order you add them. `addPhase(name, after, flushAfter)` takes the phases it must come after, and `flushAfter: true` applies any deferred entity changes when the phase ends. `query2` visits every entity that has both components.

## 5. Let the runtime tick it

```ts
App.tps = 10.0;
App.onTick((): void => {
    schedule.run(world, App.tickDelta, App.tick);
    const p: Position = world.getRequired(ball, POSITION);
    console.log("tick " + App.tick + ": ball at " + p.x + ", " + p.y);
    if (App.tick >= 4) {
        App.quit();
    }
});
```

`App.onTick` runs once per fixed logic tick, `App.tps` times a second, and a console program with a tick handler keeps running until `App.quit()`. Put the five snippets in `app.tks` in order and run it:

```sh
thicket run
```

```text
tick 0: ball at 6, 3
tick 1: ball at 12, 6
tick 2: ball at 18, 9
tick 3: ball at 24, 12
tick 4: ball at 30, 15
```

## 6. Put it in a window

A window game adds a `window` section:

```json5
{
    entry: "game.tks",
    systems: ["willow", "bitmap"],
    packages: { gamekit: "../gamekit-tks" },
    window: { title: "Drift", width: 640, height: 480 },
}
```

This version moves a square left and right with the arrow keys or A and D. It adds three gamekit parts:

- A **scene** (`AppScene`) that owns the world and a willow node. A `SceneStack` starts it.
- A **`WorldTicker`**, which steps the world on the scene node's tick. Pause or dispose the node and the world stops with it.
- An **`InputPolicy`**, which turns the core `InputMap` into an `ActionFrame` of named actions, and a **`WillowPresentationAdapter`**, which draws each `Body` as a willow `Quad` in the `present` phase.

```ts
import { Node, Quad } from "willow";
import { AppScene, ComponentKey, Entity, InputPolicy, PhaseSchedule, SceneStack, World, WorldTicker } from "gamekit";
import { WillowPresentationAdapter, WillowPresentationState } from "gamekit/src/willow";

enum Action { LEFT, RIGHT, MOVE_X }

class Body {
    x: float;
    y: float;
    speed: float = 0.0;
    constructor(x: float, y: float) {
        this.x = x;
        this.y = y;
    }
}

const BODY: ComponentKey<Body> = new ComponentKey<Body>("body");

class PlayScene extends AppScene {
    private world: World = new World();
    private schedule: PhaseSchedule = new PhaseSchedule();
    private input: InputPolicy = new InputPolicy();
    private adapter: WillowPresentationAdapter<Body>;
    private ticker: WorldTicker | null = null;
    private root: Node = new Node("play");

    constructor() {
        super("play");
        this.world.registerStore(BODY);
        InputMap.bind(Action.LEFT as int, [Key.LEFT, Key.A]);
        InputMap.bind(Action.RIGHT as int, [Key.RIGHT, Key.D]);
        InputMap.axis(Action.MOVE_X as int, Action.LEFT as int, Action.RIGHT as int);
        this.input.watch("move_x", Action.MOVE_X as int);

        // Presentation: one Quad per Body, synced in the present phase.
        this.adapter = new WillowPresentationAdapter<Body>(
            (body: Body): Node => new Quad(32.0, 32.0, Color{ value: 0x40C080FF }),
            (body: Body): WillowPresentationState => {
                const state: WillowPresentationState = new WillowPresentationState(this.root);
                state.x = body.x;
                state.y = body.y;
                return state;
            });

        this.schedule.addPhase("input", [], true);
        this.schedule.addPhase("simulate", ["input"], true);
        this.schedule.addPhase("present", ["simulate"]);
        this.schedule.addSystem("input", (w: World, dt: float, tick: int): void => {
            const axis: float = this.input.frame().axis("move_x");
            w.query(BODY).each((e: Entity, b: Body): void => { b.speed = axis * 200.0; });
        });
        this.schedule.addSystem("simulate", (w: World, dt: float, tick: int): void => {
            w.query(BODY).each((e: Entity, b: Body): void => { b.x += b.speed * dt; });
        });
        this.schedule.addSystem("present", (w: World, dt: float, tick: int): void => {
            this.adapter.present();
        });

        engine.root2d.add(this.root);
        this.attachNode(this.root);
    }

    override async enter(): Promise<void> {
        const player: Entity = this.world.createEntity();
        const body: Body = new Body(304.0, 224.0);
        this.world.put(player, BODY, body);
        this.adapter.bind(body);
        // The runtime's fixed tick steps the world while this scene's node runs.
        this.ticker = new WorldTicker(this.root, this.world, this.schedule, App.tickDelta);
    }

    override async exit(): Promise<void> {
        if (this.ticker != null) { this.ticker.dispose(); }
        this.adapter.dispose();
        this.world.dispose();
    }
}

const scenes: SceneStack = new SceneStack();
await scenes.start(new PlayScene());
```

The simulation never touches a willow node. Systems change `Body` records, and only the `present` phase copies them onto the screen. That split is what lets the same simulation run headless in a test.

## Next

- [How gamekit is built](./guide/mental-model.html): the ideas every family shares.
- [World, queries and systems](./guide/world-and-systems.html): stores, deferred commands and phase rules.
- [Scenes](./guide/scenes.html) and [Input actions](./guide/input.html): the two parts every game reaches for next.

---

URL: https://thicketscript.com/gamekit/guide/assets

# Assets

The asset tools load things in the right order, count who is using them, and release them when the scene that loaded them ends. They do not read files themselves: a **loader** you supply does that.

```ts
import { AssetHandle, AssetKey, AssetLoadPlan, AssetManager, AssetPlanResult, AssetScope, FakeAssetLoader } from "gamekit";

const CONFIG: AssetKey<string> = new AssetKey<string>("config");
const ATLAS: AssetKey<string> = new AssetKey<string>("atlas");

// A loader is any object with async load(key) and unload(key, asset).
// FakeAssetLoader is the in-memory one gamekit ships for tests and samples.
const loader: FakeAssetLoader = new FakeAssetLoader();
loader.set(CONFIG, "quality=high");
loader.set(ATLAS, "atlas pixels");
const assets: AssetManager = new AssetManager(loader);

async function main(): Promise<void> {
    const plan: AssetLoadPlan = new AssetLoadPlan();
    plan.add(CONFIG);
    plan.add(ATLAS, [CONFIG]);           // the atlas loads after the config
    const result: AssetPlanResult = await assets.loadPlan(plan);
    console.log("plan ok: " + result.isOk + ", loaded " + result.loadedCount);

    const scene: AssetScope = assets.createScope("level-1");
    const atlas: AssetHandle<string> = await scene.load(ATLAS);
    console.log("atlas: " + atlas.get() + ", refs " + assets.getRefCount(ATLAS));
    scene.dispose();                     // releases every handle the scope took
    console.log("refs after scope: " + assets.getRefCount(ATLAS));
}

await main();
```

```text
plan ok: true, loaded 2
atlas: atlas pixels, refs 2
refs after scope: 1
```

## The parts

| Part | What it is |
|---|---|
| `AssetKey<T>` | A typed name for one asset. |
| loader | Any object with `async load(key)` and `unload(key, asset)`. Pass a default one to `new AssetManager(loader)`, or set one per key with `registerLoader(key, loader)`. `FakeAssetLoader` is an in-memory loader for tests and samples. |
| `AssetManager` | Loads, caches and reference-counts assets. `getRefCount(key)`, `isLoaded(key)`, `replaceAsset(key, value)`, `shutdown()`. |
| `AssetHandle<T>` | One use of an asset. `get()` returns it; `release()` gives it back. |
| `AssetScope` | A group of handles with one owner. `load(key)`, `acquire(key)`, `get(key)`, `release(key)`, `releaseAll()`, `dispose()`. |
| `AssetLoadPlan` | A set of keys with dependencies, loaded in waves. |

## Load plans

`plan.add(key, dependencies?, options?)` adds an entry. `validate()` checks the plan and throws `CyclicDependency` before any loading if the dependencies loop. `manager.loadPlan(plan)` loads each wave after the one it depends on and returns an `AssetPlanResult`:

| Field | Meaning |
|---|---|
| `isOk`, `isCancelled` | Did it all load? Was it cancelled? |
| `loadedCount`, `failedCount` | Counts. |
| `getHandle(key)` | The handle for one key, or `null`. |
| `getFailure(key)`, `getFailureTrace(key)` | What went wrong for one key. |

`AssetPlanEntry` carries a `weight` for progress reporting and a `retries` count. Loads can be cancelled with an `AssetCancellationToken`.

## Scopes and scenes

Give each scene its own scope, and dispose it when the scene ends. With a [SceneCoordinator](./scenes.html#scenecoordinator), `registerAssetScope(scene, scope)` does that for you on exit.

Do not keep handles in globals. A handle used after its scope is disposed throws `StaleHandle`, which is how you find the leak. For assets every scene shares, use one long-lived scope owned by the app.

Reference: [AssetManager](../reference/core.html#assetmanager), [AssetScope](../reference/core.html#assetscope), [AssetHandle](../reference/core.html#assethandle), [AssetLoadPlan](../reference/core.html#assetloadplan), [AssetPlanResult](../reference/core.html#assetplanresult), [FakeAssetLoader](../reference/core.html#fakeassetloader).

---

URL: https://thicketscript.com/gamekit/guide/attributes-and-state-machines

# Attributes and state machines

Two small, separate tools that live together in `core`:

- An **`Attribute<T>`** is a value with modifiers, an optional clamp and listeners. Use it for stats such as speed, armour or max health.
- A **`StateMachine<TOwner>`** holds named states and only moves along the edges you permit. Use it for doors, AI moods, menus and animation states.

They do not know about each other. An attribute never starts a state machine, and a state machine owns no attributes.

```ts
import { Attribute, AttributeModifier, StateMachine, StateMachineState } from "gamekit";

// An attribute is a value with ordered modifiers and an optional clamp.
const speed: Attribute<float> = new Attribute<float>(100.0, (v: float): float => v < 0.0 ? 0.0 : v);
speed.addModifier(new AttributeModifier<float>("boots", 10, (v: float): float => v + 20.0));
speed.addModifier(new AttributeModifier<float>("slow", 20, (v: float): float => v * 0.5));
console.log("speed now " + speed.value);    // (100 + 20) * 0.5 = 60
speed.removeModifier("slow");

// A derived attribute recalculates from others.
const strength: Attribute<int> = new Attribute<int>(8);
const carry: Attribute<int> = new Attribute<int>(0);
carry.derive([strength], (values: any[]): int => (values[0] as int) * 5);
strength.setBase(10);
console.log("carry " + carry.value);

// A state machine only takes the edges you permit.
class Door {
    log: string[] = [];
    locked: boolean = true;
}
const door: Door = new Door();
const machine: StateMachine<Door> = new StateMachine<Door>(door);
machine.addState(new StateMachineState<Door>("closed", {
    enter: (owner: Door, context: any): void => { owner.log.push("closed"); },
}));
machine.addState(new StateMachineState<Door>("open", {
    enter: (owner: Door, context: any): void => { owner.log.push("open"); },
}));
machine.permit("closed", "open", (owner: Door, context: any): boolean => !owner.locked);
machine.permit("open", "closed");
machine.start("closed");
const whileLocked: boolean = machine.transition("open");   // the guard says no
door.locked = false;
const unlocked: boolean = machine.transition("open");
console.log(door.log.join(", ") + "; locked: " + whileLocked + ", unlocked: " + unlocked);
```

```text
speed now 60
carry 50
closed, open; locked: false, unlocked: true
```

## Attributes

| Call | What it does |
|---|---|
| `new Attribute<T>(base, clamp?)` | A value with a base. The clamp sees the fully modified value. |
| `addModifier(new AttributeModifier(id, order, apply))` | Adds a modifier. Lower `order` runs first; equal orders keep the order you added them. |
| `removeModifier(id)` | Removes one and returns whether it was there. |
| `setBase(value)` | Changes the base. |
| `derive(dependencies, calculate)` | Computes the base from other attributes. A cycle is rejected before it can take effect. |
| `clearDerived()` | Goes back to the stored base. |
| `subscribe(listener)` | Calls `listener(next, previous)` on change. Returns a subscription to dispose. |
| `value`, `inspect()` | The resolved value; a debug snapshot with counts and recalculations. |

Recalculation is synchronous and has no ticker or global registry behind it.

## State machines

| Call | What it does |
|---|---|
| `new StateMachine<TOwner>(owner, clock?, cap?)` | A machine for an owner. The clock is optional; `cap` bounds queued transition work (default 64). |
| `addState(new StateMachineState(name, { enter, exit, update }))` | Adds a state. Each callback is optional and receives the owner. |
| `permit(from, to, guard?)` | Allows an edge. The guard `(owner, context) => boolean` can refuse it. |
| `start(name, context?)` | Enters the first state. |
| `transition(to, context?)` | Moves along a permitted edge. Returns `false` when a guard refuses. Throws when the edge was never permitted. |
| `update(delta)` | Calls the current state's `update(owner, delta)`. Nothing updates on its own. |
| `transitionAfter(delay, to, context?)` | Schedules a transition. Needs a clock with `schedule`, such as `App.ticker` or a test `ClockScheduler`. |
| `dispose()` | Cancels timed work and exits the current state. |

A transition requested from inside a state callback is queued and runs after the current one, so callbacks never recurse. `inspect()` reports queued and scheduled work for debugging.

Reference: [Attribute](../reference/core.html#attribute), [AttributeModifier](../reference/core.html#attributemodifier), [StateMachine](../reference/core.html#statemachine), [StateMachineState](../reference/core.html#statemachinestate).

---

URL: https://thicketscript.com/gamekit/guide/conditions-and-actions

# Conditions, actions and interactions

Three tools for game rules that must be checked, applied safely and offered to the player:

- A **`Condition`** answers "is this allowed?" and says why not.
- An **`Action`** validates a request, stages its changes, and commits them all or none.
- An **interaction** offers actions the player could take on a target ("Open chest"), enabled or not.

## Conditions and actions

```ts
import { Action, ActionContext, ActionRequest, ActionResult, Condition, ConditionResult } from "gamekit";

class Wallet {
    gold: int = 30;
}

class Price {
    cost: int;
    constructor(cost: int) { this.cost = cost; }
}

// Conditions explain themselves when they fail.
const canAfford: Condition<ActionContext<Price>> = new Condition<ActionContext<Price>>(
    "can-afford", "not enough gold",
    (ctx: ActionContext<Price>): boolean => (ctx.actor as Wallet).gold >= ctx.payload.cost);

// An action validates, stages mutations, then commits them all or none.
const buy: Action<Price, any> = new Action<Price, any>("buy", "buys an item");
buy.addCondition(canAfford);
buy.validate((ctx: ActionContext<Price>): void => {
    const wallet: Wallet = ctx.actor as Wallet;
    const cost: int = ctx.payload.cost;
    ctx.stageMutation("pay",
        (): void => { wallet.gold -= cost; },
        (): void => { wallet.gold += cost; });
});

const wallet: Wallet = new Wallet();
const first: ActionResult<any> = buy.execute(new ActionRequest<Price>("buy", wallet, null, new Price(20)));
const second: ActionResult<any> = buy.execute(new ActionRequest<Price>("buy", wallet, null, new Price(20)));
console.log("first: " + first.status + ", second: " + second.status + " (" + (second.reason ?? "") + ")");
console.log("gold left: " + wallet.gold);

// Conditions compose.
const positive: Condition<int> = new Condition<int>("positive", "must be above zero", (n: int): boolean => n > 0);
const even: Condition<int> = new Condition<int>("even", "must be even", (n: int): boolean => n % 2 == 0);
const both: ConditionResult = Condition.all<int>([positive, even]).evaluate(3);
console.log("3 passes: " + both.passed + ", reason: " + both.reason);
```

```text
first: committed, second: denied (not enough gold)
gold left: 10
3 passes: false, reason: must be even
```

### Conditions

`new Condition<TContext>(id, description, evaluator)` wraps a predicate over a context you pass in; it never looks anything up globally. The evaluator may return a `boolean`, a `string` (a failure reason) or a `ConditionResult` (`passed`, `conditionId`, `reason`, `reasons`). When a plain `false` comes back, the description is the reason.

| Combinator | Behaviour |
|---|---|
| `Condition.all(list, shortCircuit = true)` | In order. Stops at the first failure, or with `false` collects every reason. |
| `Condition.any(list, shortCircuit = true)` | In order. Stops at the first pass; if all fail, collects the reasons. |
| `Condition.not(c, reason)` | Inverts, with an explicit reason. |
| `c.and(d)`, `c.or(d)`, `c.not()` | The same, written fluently. |

### Actions

An action runs a request through four steps:

1. **Request.** `new ActionRequest(actionId, actor, target, payload, metadata)` states what the caller wants.
2. **Validate.** Conditions (`addCondition`, `precondition`, `guard`) and stages (`validate(stage)`) run in the order you added them over an `ActionContext`. A stage may change the payload, stage changes with `stageMutation(id, apply, rollback)`, or call `deny(reason)`. A denial or a throw stops here with nothing applied.
3. **Commit.** The staged mutations run. If one throws, the ones already applied are rolled back in reverse order.
4. **Notify.** Events staged with `emitOnCommit(scope, key, event)` are emitted only after a successful commit, so listeners hear about facts, never about attempts.

`execute` returns an `ActionResult` with `status` (`ActionStatus`: committed, denied or failed), `ok`, `reason`, `error` and the applied mutations. `onCommit(fn)` adds commit-time work.

`ActionSequence` runs several actions in order. When one is denied or fails, the rest are skipped, and with `rollbackOnFailure` (the default) the committed ones are rolled back in reverse.

## Interactions

```ts
import { Action, ActionContext, ActionRequest, ActionResult, Condition, InteractionContext, InteractionDefinition, InteractionOffer, InteractionProvider, InteractionRegistry } from "gamekit";

class Player {
    keys: int = 0;
}
class Chest {
    open: boolean = false;
}

const openChest: Action<any, any> = new Action<any, any>("open-chest", "opens a chest");
openChest.validate((ctx: ActionContext<any>): void => {
    const chest: Chest = ctx.target as Chest;
    const player: Player = ctx.actor as Player;
    ctx.stageMutation("open",
        (): void => { chest.open = true; player.keys -= 1; },
        (): void => { chest.open = false; player.keys += 1; });
});

const chestDef: InteractionDefinition<string> = new InteractionDefinition<string>(
    "chest",
    openChest,
    (ctx: InteractionContext<Player, Chest, any>): ActionRequest<any> => new ActionRequest<any>("open-chest", ctx.actor, ctx.target),
    new Condition<any>("has-key", "you need a key", (ctx: any): boolean => (ctx.actor as Player).keys > 0),
    (ctx: InteractionContext<Player, Chest, any>, enabled: boolean, result: any): string => "Open chest");

const interactions: InteractionRegistry = new InteractionRegistry();
interactions.register(InteractionProvider.fromDefinition(chestDef));

const player: Player = new Player();
const chest: Chest = new Chest();
for (const offer of interactions.discover(player, chest)) {
    console.log(offer.metadata + " enabled: " + offer.enabled);
}
player.keys = 1;
const offers: InteractionOffer<any>[] = interactions.discover(player, chest);
const result: ActionResult<any> = offers[0].execute();
console.log("result " + result.status + ", chest open: " + chest.open);
```

```text
Open chest enabled: false
result committed, chest open: true
```

- An **`InteractionDefinition`** pairs an action with a request factory, an optional condition and an optional metadata factory. The metadata is yours: a prompt, a verb, an icon.
- An **`InteractionProvider`** discovers offers for an `InteractionContext(actor, target, environment)`. `InteractionProvider.fromDefinition` wraps a definition; `new InteractionProvider(id, discover)` takes your own discovery function.
- An **`InteractionRegistry`** gathers providers. `discover(actor, target, environment?)` returns `InteractionOffer`s. A disabled offer is still returned, with its `conditionResult`, so the game can show *why* it is greyed out. `offer.execute()` runs the action.

gamekit adds no prompts, ranges or verbs of its own. Two parts of a game can register unrelated interactions without knowing about each other.

Reference: [Condition](../reference/core.html#condition), [ConditionResult](../reference/core.html#conditionresult), [Action](../reference/core.html#action), [ActionContext](../reference/core.html#actioncontext), [ActionSequence](../reference/core.html#actionsequence), [InteractionRegistry](../reference/core.html#interactionregistry).

---

URL: https://thicketscript.com/gamekit/guide/definitions-and-prefabs

# Definitions and prefabs

A **definition** is template data: what a "soldier" or a "big slime" starts with. A `DefinitionRegistry` stores definitions, resolves inheritance, validates them, and hands the result to a factory you write. gamekit never constructs classes by name and never scans folders for content.

```ts
import { DefinitionRegistry, Prefab, ResolvedDefinition } from "gamekit";

class Unit {
    name: string;
    hp: int;
    attack: int;
    constructor(name: string, hp: int, attack: int) {
        this.name = name;
        this.hp = hp;
        this.attack = attack;
    }
}

const defs: DefinitionRegistry = new DefinitionRegistry();
defs.define("base_unit", { hp: 10, attack: 1 });
defs.define("soldier", { attack: 3 }, ["base_unit"]);
defs.define("veteran", { hp: 18 }, ["soldier"]);

const veteran: ResolvedDefinition = defs.resolve("veteran");
console.log("veteran: " + veteran.provenance.join(" -> "));

// You supply the factory. gamekit never constructs classes by name.
const makeUnit: Function = (def: ResolvedDefinition, context: any): Unit =>
    new Unit(def.id, def.data.hp as int, def.data.attack as int);
const prefab: Prefab = defs.createPrefab("veteran", makeUnit);
const unit: Unit = prefab.instantiate() as Unit;
console.log(unit.name + " hp " + unit.hp + " attack " + unit.attack);
```

```text
veteran: base_unit -> soldier -> veteran
veteran hp 18 attack 3
```

## Registering

| Call | What it does |
|---|---|
| `define(id, data, inherits?)` | Creates and registers a definition. |
| `register(definition)` | Registers a `new Definition(id, data, inherits)`. |
| `addValidator(fn)` | Adds a check that runs on resolve. A failure throws `InvalidDefinition`. |
| `resolve(id)`, `get(id)`, `getRequired(id)` | The merged `ResolvedDefinition` (`id`, `data`, `provenance`). `get` returns `null` when missing. |
| `instantiate(id, factory, context?)` | Resolves and calls `factory(definition, context)`. |
| `createPrefab(id, factory)` | A `Prefab` whose `instantiate(context?)` does the same each time. |

Data is deep-copied when registered and again when resolved, so changing a runtime object never changes the registry.

## Inheritance

`inherits` lists parents. They merge left to right, then the child's own data on top:

- Plain objects and `Map`s merge key by key.
- Numbers, strings, arrays and mismatched types are replaced by the child's value.
- `provenance` lists every definition that contributed, in order.

## Errors name the whole chain

| Error | When |
|---|---|
| `DuplicateRegistration` | An id is registered twice. |
| `MissingRegistration` | A parent does not exist. `provenance` shows the chain, such as `veteran -> soldier -> base_unit`. |
| `CyclicDefinition` | Inheritance loops. `cycle` shows the loop. |
| `InvalidDefinition` | A validator failed. Names the definition, the reason and its ancestry. |

## One definition, many kinds of object

The factory decides what to build. The same `"slime"` definition can become a live `Entity` with components in the world and a plain card in a bestiary screen. [The spawning recipe](../recipes.html#spawn-from-a-definition-during-a-phase) builds world entities from definitions inside a phase.

Reference: [DefinitionRegistry](../reference/core.html#definitionregistry), [ResolvedDefinition](../reference/core.html#resolveddefinition), [Prefab](../reference/core.html#prefab).

---

URL: https://thicketscript.com/gamekit/guide/effects

# Effects

An effect is a temporary, keyed value on an entity: poisoned, hasted, shielded, on fire. gamekit tracks its lifetime, its duration and what happens when a second one with the same key arrives. What the effect *does* is up to you; gamekit is not a rule engine.

```ts
import { EffectHandle, EffectKey, EffectOptions, EffectStacking, Entity } from "gamekit";
import { ClockScheduler } from "gamekit/src/testing";

class Poison {
    damage: int;
    constructor(damage: int) { this.damage = damage; }
    onActivate(owner: Entity, effect: any): void { console.log("poisoned for " + this.damage); }
    onExpire(owner: Entity, effect: any): void { console.log("poison wore off"); }
    onRemove(owner: Entity, effect: any, reason: string): void { console.log("removed: " + reason); }
}

const POISON: EffectKey<Poison> = new EffectKey<Poison>("poison");

// In a game the scheduler is a Ticker (App.ticker or a node's ticker).
// A ClockScheduler from testing advances only when you tell it to.
const clock: ClockScheduler = new ClockScheduler();
const hero: Entity = new Entity();
hero.activate();

const strongest: Function = EffectStacking.strongest((a: Poison, b: Poison): int => a.damage - b.damage);
hero.addEffect(POISON, new Poison(3), new EffectOptions<Poison>(strongest, null, 2.0, clock));
const weaker: EffectHandle<Poison> | null = hero.addEffect(POISON, new Poison(1), new EffectOptions<Poison>(strongest, null, 2.0, clock));
console.log("weaker accepted: " + (weaker != null));

clock.advance(2.5);
console.log("active poison: " + hero.getEffects(POISON).length);
```

```text
poisoned for 3
removed: rejected
weaker accepted: false
poison wore off
removed: expired
active poison: 0
```

## Adding effects

`entity.addEffect(key, value, options)` returns an `EffectHandle`, or `null` when the stacking policy rejects it. `entity.getEffects(key)` returns every current instance for a key.

`EffectOptions(policy, source, duration, scheduler)`:

| Option | Meaning |
|---|---|
| `policy` | What to do when the key already has an instance. Required in that case. |
| `source` | An optional owner, such as the entity that cast it. Disposing the source removes the effect. |
| `duration` | Optional length, counted on the scheduler. A duration without a scheduler is an error. |
| `scheduler` | Where time comes from. In a game, a core `Ticker` (`App.ticker` or a scene node's ticker), so `App.timeScale` stretches it and a paused node stops it. In tests, a `ClockScheduler` or a `PresentationClock`'s scheduler. |

## Stacking policies

`EffectStacking` has four ready policies:

| Policy | When a new instance arrives |
|---|---|
| `accumulate()` | Keep both. |
| `replace()` | Remove the old ones, keep the new one. |
| `strongest(compare)` | Keep whichever `compare` says is stronger. |
| `refreshDuration()` | Keep the existing one and restart its duration. |

A custom policy is a function that receives an `EffectStackingContext` and returns `context.accept()`, `reject()`, `replace()` or `refresh(effect)`.

## Hooks

An effect value may define `onAttach`, `onActivate`, `onSuspend`, `onExpire` and `onRemove`. Each receives the owner entity and the handle; `onRemove` also gets the reason (`EffectRemovalReason`). An effect can subscribe to `owner.events` in `onActivate` and release the subscription in `onRemove`.

Effects share one attachment order with components: activation goes forward, suspension goes in reverse. Every way an effect can end (removed, expired, its source disposed, its owner disposed) calls `onRemove` exactly once.

## The effect pipeline

Before the policy runs, `entity.effects.pipeline` (a [MutablePipeline](./events-and-pipelines.html)) sees each `EffectApplication`. A stage can change it, for example halving a duration for a resistant entity, or cancel it.

Reference: [EffectKey](../reference/core.html#effectkey), [EffectOptions](../reference/core.html#effectoptions), [EffectStacking](../reference/core.html#effectstacking), [EffectHandle](../reference/core.html#effecthandle), [EffectCollection](../reference/core.html#effectcollection).

---

URL: https://thicketscript.com/gamekit/guide/entities

# Entities and components

An `Entity` is a game object: something that has components, can sit in a hierarchy, and has a lifecycle. It has no position, no renderer node and no required base class for its components. You decide what an entity is by what you attach to it.

Use entities on their own for a small game or a hierarchy of objects (a room with furniture, a ship with turrets). Put them in a [World](./world-and-systems.html) when you want queries and systems over many of them.

## Components and keys

```ts
import { ComponentKey, Entity } from "gamekit";

class Health {
    current: int = 100;
}

const HEALTH: ComponentKey<Health> = new ComponentKey<Health>("health");

const hero: Entity = new Entity();
hero.addComponent(HEALTH, new Health());

const health: Health | null = hero.getComponent(HEALTH);
if (health != null) {
    health.current -= 25;
    console.log("hp " + health.current);
}
```

| Method | What it does |
|---|---|
| `addComponent(key, value)` | Attaches a component. Throws if the key is already present. |
| `replaceComponent(key, value)` | Swaps in a new value and returns the old one, or `null`. |
| `removeComponent(key)` | Removes and returns the value, or `null`. |
| `getComponent(key)` | Returns the value or `null`. Never throws for a missing key. |
| `getAncestorComponent(key)` | The nearest ancestor's value for the key, not counting this entity. |
| `getDescendantComponents(key)` | Every descendant's value for the key, parent before child. |

Components are visible the moment they are added. Adding, replacing or removing a component from inside one of the lifecycle hooks below throws.

## The lifecycle

An entity is in one of four states (`EntityState`): **detached**, **attached** (it has a parent), **active**, or **disposed**. A parentless entity becomes an active root when you call `activate()`. A child becomes active when it is attached to an active parent.

Components may define any of these optional hooks, and an `Entity` subclass may override them too:

| Hook | Called when | Order |
|---|---|---|
| `onAttach(owner)` | The entity joins a hierarchy. | Parent before child. |
| `onActivate(owner)` | The entity becomes active. | Parent before child. |
| `onDeactivate(owner)` | The entity stops being active. | Child before parent. |
| `onDetach(owner)` | The entity leaves its parent. | Child before parent. |
| `onDispose(owner)` | The entity is disposed. | Child before parent. |

The entity's own hook runs first, then its components in the order they were added (reverse order for deactivate and detach).

| Call | What happens |
|---|---|
| `attach(parent)` | `onAttach` on the entity and any detached descendants; if the parent is active, `onActivate` too. |
| `activate()` | `onActivate`, parent before child. On a parentless entity this makes it an active root. |
| `deactivate()` | `onDeactivate`, child before parent. Only valid on an active root. |
| `detach()` | Deactivates if active, then `onDetach`, then unlinks. The subtree stays intact. |
| `reparent(parent)` | Deactivate, detach, attach to the new parent, activate if that parent is active. |
| `dispose()` | Deactivate, detach, then `onDispose` for the whole subtree. Disposing twice does nothing. |

## Contexts and deferred teardown

This example uses a lifecycle hook, a context and a teardown queue:

```ts
import { ComponentKey, ContextKey, Entity, EntityState, EntityTeardownQueue } from "gamekit";

class Lamp {
    onAttach(owner: Entity): void { console.log("lamp attached"); }
    onActivate(owner: Entity): void { console.log("lamp on"); }
    onDeactivate(owner: Entity): void { console.log("lamp off"); }
    onDispose(owner: Entity): void { console.log("lamp disposed"); }
}

class Theme {
    name: string;
    constructor(name: string) { this.name = name; }
}

const LAMP: ComponentKey<Lamp> = new ComponentKey<Lamp>("lamp");
const THEME: ContextKey<Theme> = new ContextKey<Theme>("theme");

const room: Entity = new Entity();
room.setContext(THEME, new Theme("night"));
room.activate();                      // a parentless entity becomes an active root

const desk: Entity = new Entity();
desk.addComponent(LAMP, new Lamp());
desk.attach(room);                    // prints "lamp attached", then "lamp on"

const theme: Theme | null = desk.getContext(THEME);
if (theme != null) {
    console.log("desk sees theme " + theme.name);   // resolved from the nearest owner outward
}

const queue: EntityTeardownQueue = new EntityTeardownQueue();
desk.disposeDeferred(queue);          // still live until the queue flushes
console.log("desk state: " + desk.state);
queue.flush();                        // prints "lamp off", "lamp disposed"
console.log("disposed: " + (desk.state == EntityState.DISPOSED));
```

```text
lamp attached
lamp on
desk sees theme night
desk state: Active
lamp off
lamp disposed
disposed: true
```

- A **context** (`ContextKey<T>`) is a value an entity provides to its descendants. `getContext` looks from the entity outward to the nearest owner that set it. Setting or removing a context calls `onContextChanged(key)` on that entity and its descendants.
- An **`EntityTeardownQueue`** delays disposal to a moment you choose. `disposeDeferred(queue)` leaves the entity live until `queue.flush()`, which runs the normal `dispose()` sequence. Use it when an entity must not vanish in the middle of a loop that is still using it.

## Each entity has its own events and effects

`entity.events` is an [EventScope](./events-and-pipelines.html) that closes when the entity is disposed. `entity.effects` and `addEffect` hold [effects](./effects.html) whose lifecycle follows the entity.

## Identity

There are three different identities, and gamekit keeps them apart:

1. **Definition identity**, such as `"soldier"`: the template an entity was made from. See [Definitions and prefabs](./definitions-and-prefabs.html).
2. **Runtime identity**, an `EntityId` with an index and a generation, issued by a `World` while it owns the entity. A disposed entity's id stops resolving, and a reused index gets a new generation.
3. **Save identity**: a durable id your save code assigns. See [Saves](./saves.html).

Reference: [Entity](../reference/core.html#entity), [EntityState](../reference/core.html#entitystate), [ComponentKey](../reference/core.html#componentkey), [ContextKey](../reference/core.html#contextkey), [EntityTeardownQueue](../reference/core.html#entityteardownqueue).

---

URL: https://thicketscript.com/gamekit/guide/events-and-pipelines

# Events and pipelines

gamekit has two separate tools for "something happened" and "something is about to happen":

| | `EventScope` | `MutablePipeline` |
|---|---|---|
| Use it for | Telling listeners about a completed fact. | Letting rules change, answer or cancel a request. |
| Listeners can | Observe. | Modify the input, `produce(result)` or `cancel()`. |
| Keyed by | `EventKey<T>` | Nothing; one pipeline per kind of request. |
| Errors in a listener | Go to the scope's optional error sink; later listeners still run. | Propagate to the caller. |

```ts
import { EventKey, EventScope, EventSubscription, MutablePipeline, PipelineContext, PipelineResult } from "gamekit";

class Hit {
    amount: int;
    constructor(amount: int) { this.amount = amount; }
}

// An event scope delivers completed facts to listeners, keyed by EventKey.
const DAMAGED: EventKey<Hit> = new EventKey<Hit>("damaged");
const scope: EventScope = new EventScope();
const sub: EventSubscription = scope.subscribe(DAMAGED, (hit: Hit): void => {
    console.log("took " + hit.amount);
});
scope.emit(DAMAGED, new Hit(7));
sub.dispose();
scope.emit(DAMAGED, new Hit(9));   // nobody listening now

// A pipeline lets rules change a request before it happens.
const damage: MutablePipeline<Hit, int> = new MutablePipeline<Hit, int>();
damage.add((ctx: PipelineContext<Hit, int>): void => {
    ctx.input.amount = ctx.input.amount - 2;            // armour
});
damage.add((ctx: PipelineContext<Hit, int>): void => {
    if (ctx.input.amount <= 0) { ctx.cancel(); return; }
    ctx.produce(ctx.input.amount);
});
const strong: PipelineResult<int> = damage.run(new Hit(10));
const weak: PipelineResult<int> = damage.run(new Hit(1));
console.log("strong: " + (strong.result ?? 0) + ", weak cancelled: " + weak.cancelled);
```

```text
took 7
strong: 8, weak cancelled: true
```

## EventScope

- `subscribe(key, listener)` returns an `EventSubscription`; call `dispose()` on it to stop listening. Subscribing twice gives two separate subscriptions, run in the order they were made.
- `emit(key, event)` is synchronous. It takes a snapshot of listeners first: a listener removed during delivery still gets this event, and a listener added during delivery waits for the next one.
- Delivery is by key identity. The key's label is only for debugging.
- There is no automatic bubbling. `forward(target, key, event)` is the one way to pass an event to another scope.
- `close()` ends the scope; closed scopes ignore new subscriptions and emits. Every entity has one at `entity.events`, closed when the entity is disposed.

## MutablePipeline

- `add(stage)` returns a `PipelineSubscription` you can dispose.
- `run(input)` calls the stages in the order they were added, each with a `PipelineContext` holding `input`. A stage may change the input, call `produce(result)` or call `cancel()`, which stops later stages.
- `run` returns a `PipelineResult` with `cancelled` and `result`.
- Like events, a run snapshots its stages: changes made during a run apply to the next run.

Entity effects use a pipeline too: `entity.effects.pipeline` sees every effect before it is applied. See [Effects](./effects.html).

Reference: [EventScope](../reference/core.html#eventscope), [EventKey](../reference/core.html#eventkey), [MutablePipeline](../reference/core.html#mutablepipeline), [PipelineContext](../reference/core.html#pipelinecontext).

---

URL: https://thicketscript.com/gamekit/guide/input

# Input actions

Games should react to *actions* ("jump", "move_x"), not keys. In ThicketScript the core `InputMap` already binds keys and buttons to actions and handles rebinding and saving bindings. gamekit adds what a game needs on top:

- **`InputPolicy`** reads `InputMap` and gives you an `ActionFrame` of named actions each tick.
- **`InputRouter`** sends each action to the right **`InputContext`**, so a menu takes "confirm" while the game below keeps "move".
- **`InputRecorder`** and **`InputReplay`** record frames and play them back, for replays and tests.

## From InputMap to a frame

```ts
enum Action { JUMP, LEFT, RIGHT, MOVE_X }

InputMap.bind(Action.JUMP as int, [Key.SPACE, GamepadButton.A]);
InputMap.axis(Action.MOVE_X as int, Action.LEFT as int, Action.RIGHT as int, GamepadAxis.LEFT_X);

const policy: InputPolicy = new InputPolicy()
    .watch("jump", Action.JUMP as int)
    .watch("move_x", Action.MOVE_X as int);

App.onTick((): void => {
    const frame: ActionFrame = policy.frame();
    if (frame.pressed("jump")) { /* jump */ }
    const move: float = frame.axis("move_x");   // -1 to 1
});
```

`frame()` builds the frame from `InputMap.isDown`, `isPressed`, `isReleased` and `value`, so its edges follow `InputMap`'s rules: latched once per tick inside `App.onTick`, once per frame elsewhere. An axis action's pressed and released edges come from its two direction actions. A button's `axis` is `0` or `1`.

`InputPolicy.frame()` reads real devices, so it needs a window project. A headless test builds `ActionFrame`s directly, as below.

| `ActionFrame` method | Meaning |
|---|---|
| `held(action)` | Down this frame. |
| `pressed(action)` | Went down this frame. |
| `released(action)` | Went up this frame. |
| `repeated(action)` | Key repeat fired. |
| `axis(action)` | The value, `-1..1` for an axis. |

`policy.focusLost()` returns releases for every held action and clears the policy, for when the window loses focus. `policy.close()` cancels a pending `InputMap.captureNext()` when an options screen closes.

### Sharing keys with willowui

willowui uses some keys itself: a modal takes Escape, a focused control takes Enter. When a game uses willowui, name the keys UI may claim with the third argument of `watch`, and call `passThrough` once:

```ts
import { DEFAULT_INPUT_MANAGER } from "willowui/src/core/input";

policy.watch("back", Action.BACK as int, [Key.ESCAPE]).passThrough(DEFAULT_INPUT_MANAGER);
```

Then `frame()` reports no press or hold for an action whose key willowui used this frame, and drops that gesture's release too. Read the frame after willowui's per-frame update.

## Contexts and routing

```ts
import { ActionFrame, ActionState, InputContext, InputContextKind, InputRecorder, InputReplay, InputRouter, RoutedInput } from "gamekit";

// Contexts declare the actions they take. The newest context that declares an action gets it.
const play: InputContext = new InputContext("play", InputContextKind.SIMULATION, ["jump", "move_x"]);
const menu: InputContext = new InputContext("menu", InputContextKind.MODAL, ["confirm", "jump"]);
const router: InputRouter = new InputRouter();
router.push(play);
router.push(menu);

// A frame of action states: action, held, pressed, released, repeated, axis.
const frame: ActionFrame = new ActionFrame([
    new ActionState("jump", true, true, false, false, 1.0),
    new ActionState("move_x", true, false, false, false, -1.0),
]);
const routed: RoutedInput = router.route(frame);
console.log("menu jump: " + routed.forContext(menu).pressed("jump"));
console.log("play jump: " + routed.forContext(play).pressed("jump"));
console.log("play move_x: " + routed.forContext(play).axis("move_x"));

// Record frames, then replay them one per tick.
const recorder: InputRecorder = new InputRecorder();
recorder.record(frame);
recorder.record(new ActionFrame([]));
const replay: InputReplay = new InputReplay(recorder.recording());
while (!replay.finished) {
    const next: ActionFrame = replay.next();
    console.log("replayed frame with " + next.actions().length + " actions");
}
```

```text
menu jump: true
play jump: false
play move_x: -1
replayed frame with 2 actions
replayed frame with 0 actions
```

- `new InputContext(name, kind, actions)` declares which actions a context takes. `InputContextKind` is descriptive: `SIMULATION`, `SCREEN`, `MODAL`, `TEXT_ENTRY`, `DEBUG`.
- `router.push(context)` and `router.remove(context)` manage the stack. The newest context that declares an action receives it. A modal takes only what it declares; everything else still reaches the game below.
- A held action stays with the context that received its press until it is released. If that context is removed first, the next routed frame sends it a release, so nothing gets stuck down and no release leaks into the screen underneath.
- With a [SceneCoordinator](./scenes.html#scenecoordinator), `registerInputContext(scene, router, context)` pushes a scene's context only while that scene is on top.

## Record and replay

`InputRecorder.record(frame)` stores a copy of each frame; `recording()` returns an `InputRecording`. `InputReplay.next()` returns the next frame. It has no clock of its own: call it once per tick from whatever steps your simulation, and live and replayed runs stay comparable. See [the replay recipe](../recipes.html#replay-recorded-input).

## TickInput

Devices latch their edges once per drawn frame, so a game that ticks slower than it draws can miss a short tap. `TickInput` fixes that: feed it one policy frame per tick with `next(frame)`, and it reports `pressed` on the first tick an action is held, never twice for one hold. `axis(name, negative, positive)` declares a two-button axis whose tap that was pressed and released between ticks still counts as one tick of -1 or 1.

```ts
const ticks: TickInput = new TickInput().axis("move_x", "left", "right");
App.onTick((): void => { game.setInput(ticks.next(policy.frame())); });
```

## Pointer input on willow

The `willow` family's `WillowInputBridge` decides which game target gets a pointer event when several overlap. Register `WillowInputTarget`s with unique priorities; the winner is the only one that sees that pointer frame, and it keeps pointer capture even outside its area until release. A `WillowViewport` pairs a screen rectangle with a willow `Camera2D`, so a click lands on the world point that camera draws there, rotation included. `unregister` and `focusLost` cancel captures and report them through `drainCancelled`.

To let willowui have pointer input first, register the UI node as a target above the world target.

Reference: [InputPolicy](../reference/app.html#inputpolicy), [ActionFrame](../reference/app.html#actionframe), [InputRouter](../reference/app.html#inputrouter), [InputContext](../reference/app.html#inputcontext), [InputReplay](../reference/app.html#inputreplay), [TickInput](../reference/app.html#tickinput), [WillowInputBridge](../reference/willow.html#willowinputbridge).

---

URL: https://thicketscript.com/gamekit/guide/mental-model

# How gamekit is built

Every gamekit family follows the same few rules. Once you know them, the rest of the API is predictable.

## No central Game class

gamekit has no `Game` to subclass and no global registry. You create a `World`, a `SceneStack` or an `AssetManager` yourself and keep a reference to it. A small game can use `SceneStack` alone, or a `World` alone, or neither.

## Ownership is explicit

Each object has one owner, and the owner decides when it ends.

- A `World` owns the entities it creates or adopts. `world.disposeEntity(e)` ends one; `world.dispose()` ends them all.
- A `SceneStack` alone starts, covers, uncovers and ends scenes. A scene belongs to one stack at a time.
- An `AssetScope` owns the handles it loaded. Disposing the scope releases them.
- A `WillowPresentationAdapter` owns exactly the nodes its factory created, never your other nodes.

When something is released, it says so: a handle used after its scope is disposed throws `StaleHandle` instead of returning old data.

## Time is passed in

gamekit never reads the wall clock and never starts a timer of its own. Time arrives as an argument:

- Systems receive `dt` and the tick number from `PhaseSchedule.run`.
- `Gauge.advance(dt)` fills a gauge. `StateMachine.update(delta)` updates a state.
- Timed effects and `StateMachine.transitionAfter` need a scheduler you supply: in a game a core `Ticker` (`App.ticker` or a node's ticker), in a test a `ClockScheduler`.

So the same input gives the same result every run, and a test can run a minute of game time in a few milliseconds.

## Events are local, rules are pipelines

An `EventScope` delivers completed facts ("the door opened") to listeners. Each entity has its own scope (`entity.events`); nothing bubbles up a hierarchy on its own. When rules need to change something before it happens ("armour reduces this hit"), that is a `MutablePipeline`, a separate tool with stages that can modify, produce a result or cancel. See [Events and pipelines](./events-and-pipelines.html).

## Simulation and presentation stay apart

Simulation code works on your own records and components. Willow nodes are touched only at the presentation boundary, the `present()` call of a `WillowPresentationAdapter`, usually from a `present` phase. That keeps the simulation testable without a window.

## No genre built in

gamekit has no nouns like "unit", "spell" or "quest". Conditions, actions, effects, definitions and interactions carry your own data. The tactics example keeps its grid, teams and rules in the example, not in gamekit.

## Families and what they may use

gamekit checks its own layering in its tests. The rules, as written in `src/functions.tks`:

| Family | May import these gamekit families | External systems |
|---|---|---|
| `core` | none | willow, willowui |
| `ecs` | `core` | willow, willowui |
| `save` | none | `fs` (for `FsByteStorage`), willow, willowui |
| `app` | none | willow, willowui |
| `audio` | none | willow, willowui |
| `willow` | `core`, `ecs`, `app` | willow, willowui |
| `ui` | `core`, `app` | willow, willowui |
| `testing` | `core`, `ecs`, `save`, `app` | `fs`, willow, willowui |

The package root (`import ... from "gamekit"`) exports `core`, `ecs`, `app`, `save` and `audio`, plus a few `testing` debug classes. It never loads the `willow` or `ui` adapters; import those from `gamekit/src/willow` and `gamekit/src/ui` when you want them.

## When to skip gamekit

gamekit is for structure. For some jobs, willow or willowui directly is clearer:

- **Custom rendering.** Multi-pass effects or your own display containers: work with willow nodes and render targets directly.
- **Desktop-style tools.** Splitters, docking, trees and file dialogs: use willowui widgets directly rather than through scene windows.
- **One-screen prototypes.** A single screen with a tick loop needs no `SceneCoordinator` or save slots.

## Costs to know about

| Situation | What happens | What to do |
|---|---|---|
| Keeping an `AssetHandle` after its scope is disposed | `handle.get()` throws `StaleHandle`. | Tie handles to the scene that owns the scope. Do not keep them in globals. |
| Ticks take longer than the frame allows | The runtime runs at most `App.maxCatchUpTicks` ticks per frame and counts the rest in `App.droppedTicks`. | Watch `App.droppedTicks`; make the slow systems cheaper. |
| Input during a scene change | Input and the scene's clocks are held until the new scene is ready. | Nothing; `SceneCoordinator` does this for registered input and clocks. |
| An asset plan with a cycle | `AssetLoadPlan.validate()` throws `CyclicDependency` before any loading starts. | Make dependencies a tree; load shared files in an earlier wave. |
| Changing the world inside a phase | Direct structural changes throw while a phase runs. | Use the `defer...` methods; they apply at the next flush. |

---

URL: https://thicketscript.com/gamekit/guide/saves

# Saves and settings

The `save` family turns game state into versioned text and stores it safely. It has four layers:

| Layer | Job |
|---|---|
| `Codec<T>` | Turns a value into plain data and back. `Codecs` builds them. |
| `SaveSchema<T>` | Names the format and its current version, runs migrations, and checks versions on load. |
| `IByteStorage` | Where the bytes go: `MemoryByteStorage`, `FsByteStorage` (files), or your own. |
| `SaveSlotManager<T>`, `SettingsStore<T>` | Named save slots with backups and autosaves; one settings document. |

```ts
import { Codec, Codecs, MemoryByteStorage, MigrationStep, RecordField, SaveResult, SaveSchema, SaveSlotInfo, SaveSlotManager, SaveSlotMetadata } from "gamekit";

class Profile {
    name: string;
    level: int;
    gold: int;
    constructor(name: string, level: int, gold: int) {
        this.name = name;
        this.level = level;
        this.gold = gold;
    }
}

// A codec says how a value becomes plain data and back.
const profileCodec: Codec<Profile> = Codecs.record<Profile>(
    [
        new RecordField("name", Codecs.string()),
        new RecordField("level", Codecs.int()),
        new RecordField("gold", Codecs.int(), false, 0),   // optional, defaults to 0
    ],
    (f: any): Profile => new Profile(f.name as string, f.level as int, f.gold as int));

// A schema names the format and its version. Migrations upgrade older saves.
const schema: SaveSchema<Profile> = new SaveSchema<Profile>("profile", 2, profileCodec);
schema.addMigration(new MigrationStep(1, 2, (data: any): any => {
    data.gold = 0;   // version 1 had no gold
    return data;
}));

// MemoryByteStorage keeps bytes in memory. FsByteStorage writes files (needs the fs system).
const slots: SaveSlotManager<Profile> = new SaveSlotManager<Profile>(new MemoryByteStorage(), schema);

async function main(): Promise<void> {
    const meta: SaveSlotMetadata = new SaveSlotMetadata("slot1", "profile", 2, 0, 125.0, "Forest, level 3");
    const saved: SaveResult<SaveSlotMetadata> = await slots.saveSlot("slot1", new Profile("Robin", 3, 40), meta);
    console.log("saved: " + saved.isOk);

    const list: SaveResult<SaveSlotInfo[]> = await slots.listSlots();
    if (list.isOk) {
        for (const info of list.value as SaveSlotInfo[]) {
            console.log("slot " + info.slotId + ": " + (info.metadata as SaveSlotMetadata).title);
        }
    }

    const loaded: SaveResult<Profile> = await slots.loadSlot("slot1");
    if (loaded.isOk) {
        const p: Profile = loaded.value as Profile;
        console.log(p.name + " level " + p.level + " gold " + p.gold);
    } else {
        console.log("load failed: " + loaded.kind + " " + loaded.message);
    }
}

await main();
```

```text
saved: true
slot slot1: Forest, level 3
Robin level 3 gold 40
```

## Codecs

| Builder | Encodes |
|---|---|
| `Codecs.int()`, `float()`, `string()`, `boolean()`, `id()` | Single values. |
| `Codecs.optional(codec)` | A value or `null`. |
| `Codecs.array(codec)` | A list. |
| `Codecs.record(fields, factory, extractor?)` | An object, field by field. `new RecordField(name, codec, required = true, default = null)`. |
| `Codecs.taggedVariant(tagField, variants, tagOf)` | One of several shapes, chosen by a tag field. |
| `Codecs.reference(kind, idOf)` | A link to another object by id, resolved through a `ReferenceResolver`. |

A `CodecContext` sets what to do with unknown fields (`UnknownFieldPolicy.REJECT` or `PRESERVE`) and missing references (`ReferencePolicy.STRICT` or `ALLOW_NULL`).

## Schemas and migrations

`new SaveSchema<T>(schemaId, currentVersion, codec)`. `dump(value)` writes the current version; `load(text)` checks the schema id and version, then runs each `MigrationStep(from, to, migrate)` in turn from the saved version up to the current one, with optional validation before and after each step. A save from a newer version than the schema knows is refused as `INCOMPATIBLE`.

## Results, not exceptions

Load and save calls return a `SaveResult<T>`: check `isOk`, then read `value`. On failure, `kind` says why (`SaveResultKind`):

| Kind | Meaning |
|---|---|
| `OK` | It worked. |
| `UNAVAILABLE` | Nothing there, or the storage could not be reached. |
| `MALFORMED` | Not valid save data. |
| `INCOMPATIBLE` | A schema or version this game cannot read. |
| `CORRUPT` | The data is damaged. |

## Save slots

| Call | What it does |
|---|---|
| `saveSlot(id, data, metadata?)` | Writes a temp file, validates it, backs up the old save, then renames into place. Saves to the same slot run one after another. |
| `loadSlot(id)` | Loads the slot. If it is damaged, it falls back to the backup and restores the primary when that works. |
| `listSlots()` | Every slot, sorted by id, as `SaveSlotInfo` (metadata, whether a backup exists, whether it is corrupt). |
| `deleteSlot(id)` | Removes a slot. |
| `rotateAutosave(data, metadata?)` | Saves to the next slot in a ring of `maxAutosaves` (default 3). |
| `latestAutosave()` | The newest autosave's metadata. |

`SaveSlotMetadata(slotId, schemaId, version, timestamp, playTime, title, custom)` is what a load screen shows without loading the whole save. File names come from `SaveSlotManagerOptions` (extensions `.sav`, `.tmp`, `.bak`, autosave prefix `autosave_`). Long saves can be cancelled with a `SlotCancellationToken`.

## Settings

`new SettingsStore<T>(storage, filename, schema)` keeps one document, such as volume and key bindings, separate from game saves. `save`, `load`, `hasSettings` and `clear`, with the same temp, backup and recovery steps as slots.

## Saving to files

`FsByteStorage` writes under a folder you choose and needs the `fs` system in your project's `systems`. It is not in the package root; import it from the family folder:

```ts
import { FsByteStorage } from "gamekit/src/save";

const storage: FsByteStorage = new FsByteStorage("saves");
```

`FaultInjectingByteStorage` wraps another storage and fails on demand (a failed write, rename or read, a full disk, a partial write), for testing your error handling.

## Saving from a scene

With a [SceneCoordinator](./scenes.html#scenecoordinator), `registerSave(work)` registers save work that `save()` runs and that `quit()` drains before the last scene ends. The [restore recipe](../recipes.html#save-a-world-and-restore-it) saves a component and loads it into a fresh world.

Reference: [Codecs](../reference/save.html#codecs), [SaveSchema](../reference/save.html#saveschema), [SaveSlotManager](../reference/save.html#saveslotmanager), [SaveResult](../reference/save.html#saveresult), [SettingsStore](../reference/save.html#settingsstore), [FsByteStorage](../reference/save.html#fsbytestorage).

---

URL: https://thicketscript.com/gamekit/guide/scenes

# Scenes and the app lifecycle

A **scene** is one screen of your game: a title, a level, a pause menu. gamekit gives you three layers, and you can stop at any of them:

| Part | Use it for |
|---|---|
| `AppScene` | A base class with async `enter`, `exit`, `suspend` and `resume` hooks, focus, and an optional willow node. |
| `SceneStack` | Starting, pushing, popping and replacing scenes. The only thing that runs scene hooks. |
| `SceneCoordinator` | A `SceneStack` plus app states (boot, load, active, suspended, shutdown, failure), clocks, input, asset scopes and saves registered per scene. |

```ts
import { AppScene, AppState, SceneCoordinator } from "gamekit";

class TitleScene extends AppScene {
    constructor() {
        super("title");
    }
    override async enter(): Promise<void> {
        console.log("title: enter");
    }
    override async exit(): Promise<void> {
        console.log("title: exit");
    }
}

class PlayScene extends AppScene {
    constructor() {
        super("play");
    }
    override async enter(): Promise<void> {
        console.log("play: enter");
    }
    override async suspend(): Promise<void> {
        console.log("play: suspend");
    }
    override async resume(): Promise<void> {
        console.log("play: resume");
    }
}

class PauseScene extends AppScene {
    constructor() {
        super("pause");
    }
}

const app: SceneCoordinator = new SceneCoordinator((state: AppState): void => {
    console.log("app state: " + state);
});

async function main(): Promise<void> {
    await app.boot(new TitleScene());
    await app.replace(new PlayScene());   // title exits, play enters
    await app.push(new PauseScene());     // play is suspended underneath
    await app.pop();                      // play resumes
    console.log("top scene: " + (app.scenes.top as AppScene).name);
    await app.quit();
}

await main();
```

```text
app state: boot
app state: load
title: enter
app state: active
app state: load
title: exit
play: enter
app state: active
play: suspend
app state: active
play: resume
app state: active
top scene: play
app state: shutdown
```

## SceneStack

| Call | What it does |
|---|---|
| `start(scene)` | Enters the first scene. |
| `push(scene, options?)` | Suspends the top scene and enters a new one above it. |
| `pop(options?)` | Exits the top scene and resumes the one below. Popping an empty stack throws. |
| `replace(scene, options?)` | Exits the top scene and enters a new one in its place. |
| `suspend()`, `resume()`, `shutdown()` | Act on the whole stack. |
| `top`, `count`, `scenes()`, `transitioning` | What is there now. |
| `addObserver(observer)` | Watch changes; returns a registration to dispose. |

Each change returns `Promise<boolean>`. Scene hooks are async, so a change can be in flight; a newer change cancels the older one through its `SceneOperation`, and the older call resolves `false`. A cancelled scene is exited and never becomes the top. If a scene's `enter` throws, the stack exits it and goes back to the scene it had.

A scene belongs to one stack at a time. Only the ready top scene has input enabled (`isInputEnabled`).

## Scene nodes and screens

A scene can own a willow node: call `attachNode(node)` in its constructor. The stack then pauses that node when the scene is covered and disposes it when the scene exits, along with its tickers and tweens. That is how a [WorldTicker](./world-and-systems.html#stepping-the-world-worldticker) on the node stops when you push a pause menu.

`scene.screen` is a container for the scene's screen-sized UI, shown, hidden and paused with the scene. `ScreenLayers.scenes` holds every scene's screen, and `ScreenLayers.overlay` is one app-wide layer drawn above them, for things like a toast or an FPS counter.

## Transitions

`push`, `pop` and `replace` take an optional `{ transition: Transition }`, using willow's `Transition` (for example `Transition.fade(0.3)`):

```ts
import { Transition } from "willow";

await scenes.replace(new PlayScene(), { transition: Transition.fade(0.5) });
```

The transition plays between the leaving and arriving scene nodes. Input stays off for both scenes until it ends and the new scene is ready, and the old node is disposed only afterwards. Without the option, or when a scene has no node, the change happens at once. The `scene-fade` example shows this in a window.

## SceneCoordinator

`new SceneCoordinator(observer?)` wraps a stack (`coordinator.scenes`) and reports an `AppState` to the observer. `boot(scene)` starts it; `push`, `pop`, `replace`, `suspend`, `resume`, `save` and `quit` drive it.

Register things against a scene and the coordinator keeps them in step with it:

| Call | What it does |
|---|---|
| `registerClock(scene, clock)` | Pauses the clock (a core `Ticker` or a test clock) while the scene is not the ready top, and resumes it after entry or resume completes. |
| `registerInputContext(scene, router, context)` | Pushes the scene's [input context](./input.html) only while it is the ready top. |
| `registerAssetScope(scene, scope)` | Disposes the [asset scope](./assets.html) when the scene exits. |
| `registerSave(work)` | Runs this save work on `save()`, and drains it before `quit()` retires the last scene. |

Each returns an `AppRegistration`; disposing it is safe more than once. If entering a scene fails, the coordinator restores the previous scene's input, clocks and focus, and moves to `failure` with the original error in `coordinator.failure`.

## Focus

`AppScene` is a focus group (`IFocusGroup`): `activateFocus()`, `blur()`, `isFocused`, and `handleInput(input)` for keys the scene handles itself. With willowui windows on top, [SceneWindowLayer](./ui-windows.html) decides which group has focus.

Reference: [AppScene](../reference/app.html#appscene), [SceneStack](../reference/app.html#scenestack), [SceneCoordinator](../reference/app.html#scenecoordinator), [AppState](../reference/app.html#appstate), [ScreenLayers](../reference/app.html#screenlayers), [SceneOperation](../reference/app.html#sceneoperation).

---

URL: https://thicketscript.com/gamekit/guide/testing-and-debug

# Testing and debugging

Because gamekit never reads the wall clock and keeps simulation apart from drawing, most of a game can be tested in a console program. The `testing` family gives you the clocks and debug tools for it. Import them from `gamekit/src/testing`; importing other families adds no registry or per-frame callback.

```ts
import { ComponentKey, Entity, PhaseSchedule, World } from "gamekit";
import { DebugTools, SimulationClock } from "gamekit/src/testing";

class Counter {
    n: int = 0;
}
const COUNTER: ComponentKey<Counter> = new ComponentKey<Counter>("counter");

const world: World = new World();
world.registerStore(COUNTER);
const e: Entity = world.createEntity();
world.put(e, COUNTER, new Counter());

const schedule: PhaseSchedule = new PhaseSchedule();
schedule.addPhase("simulate", [], true);
schedule.addSystem("simulate", (w: World, dt: float, tick: int): void => {
    w.getRequired(e, COUNTER).n += 1;
});

// A SimulationClock runs fixed ticks from elapsed time you feed it. No window, no wall clock.
const clock: SimulationClock = new SimulationClock(0.1, 8, (dt: float, tick: int): void => {
    schedule.run(world, dt, tick);
});
const ran: int = clock.advance(0.35);    // three whole ticks, the rest carries over
console.log("ticks run: " + ran + ", counter " + world.getRequired(e, COUNTER).n);

// DebugTools turns state into stable data for asserts and failure messages.
const before: string = DebugTools.canonicalSnapshot({ hp: 10, name: "slime" });
const changed: any = DebugTools.diff({ hp: 10, name: "slime" }, { hp: 7, name: "slime" });
console.log(before);
console.log(JSON.stringify(changed));
```

```text
ticks run: 3, counter 3
{"hp":10,"name":"slime"}
{"changed":["hp"],"before":{"hp":10,"name":"slime"},"after":{"hp":7,"name":"slime"}}
```

## Clocks you advance

| Clock | Use it for |
|---|---|
| `SimulationClock(tickDuration, catchUpCap, tickWork)` | A fixed-step loop. `advance(elapsed)` runs whole ticks and carries the remainder; at most `catchUpCap` ticks per call. Also `step()`, `singleStep()`, `pause()`, `resume()`, `setTimeScale()`, `interpolation`. |
| `PresentationClock()` | Variable time for presentation-side work, with pause and time scale. |
| `ClockScheduler()` | Timed callbacks. `schedule(delay, fn)`, `scheduleEvery(period, fn)`, then `advance(elapsed)`. Pass it wherever gamekit asks for a scheduler, such as effect durations and `StateMachine.transitionAfter`. |
| `ScheduleOwner` | A generation token: work scheduled with an owner is retired when the owner is disposed or reused from a pool. |

In a game, the runtime's tick does this job (`App.onTick`, `App.ticker`, node tickers). These clocks stand in for it in tests.

## DebugTools

Static helpers that return detached data. They never advance a clock, read input, load an asset or touch storage.

| Call | Returns |
|---|---|
| `canonicalSnapshot(value)` | Sorted, stable JSON for a value. Good for comparing states. |
| `diff(before, after)` | The top-level keys that changed, with both sides. |
| `assertTranscript(actual, expected)` | Throws with a readable diff when two transcripts differ. |
| `inspectWorld`, `inspectQuery`, `inspectPhases`, `inspectClock`, `inspectInputRouter`, `inspectScenes`, `inspectEffects`, `inspectAssets`, `inspectSaves` | A description of what each object owns and in what order. |

## DebugScenario

`new DebugScenario(seed)` records your game's step inputs with `step(label, input)`. `run(initial, apply, assertFailure?)` replays them and returns either the transcript or the first failure, with the seed, the step, the input and before and after snapshots with a diff. `minimize(stillFails)` shrinks a failing scenario to the smallest set of steps that still fails.

## DebugTrace

`new DebugTrace(enabled = false, maxEntries = 128, redactor?, callback?)` is a bounded log. While disabled, `record` returns at once and keeps nothing. Your optional redactor decides what is safe to keep.

## Test fakes elsewhere

- `FakeAssetLoader` (core) loads from memory and can fail or delay on purpose.
- `MemoryByteStorage` and `FaultInjectingByteStorage` (save) keep saves in memory and fail on demand.
- An `IMusicBackend` fake stands in for audio in `MusicDirector` tests.

See also [the replay recipe](../recipes.html#replay-recorded-input).

Reference: [SimulationClock](../reference/testing.html#simulationclock), [ClockScheduler](../reference/testing.html#clockscheduler), [PresentationClock](../reference/testing.html#presentationclock), [DebugTools](../reference/testing.html#debugtools), [DebugScenario](../reference/testing.html#debugscenario), [DebugTrace](../reference/testing.html#debugtrace).

---

URL: https://thicketscript.com/gamekit/guide/ui-windows

# Windows with willowui

`SceneWindowLayer` (the `ui` family) connects a [SceneStack](./scenes.html) to [willowui](../../willowui/) windows. Each scene gets its own `WindowManager`, so its windows hide when another scene covers it and go away when it exits. A separate set of **screen windows** stays above every scene.

The layer only watches the stack. It never pushes, pops or creates scenes, and it leaves dragging, z-order, modal overlays and widget focus to willowui.

## Your project lists willowui too

gamekit brings willowui for its own use. As soon as your own code imports from `willowui`, list it in your `packages` as well, pointing at the **same folder** gamekit uses (two different sources for one package name is an error):

```json5
{
    entry: "ui.tks",
    systems: ["willow", "bitmap"],
    packages: {
        gamekit: "../gamekit-tks",
        willowui: "../willowui-tks",
    },
    window: { title: "Windows", width: 640, height: 480 },
}
```

## Scene windows and screen windows

```ts
import { Label } from "willowui/src/core/label";
import { Window, WindowManager } from "willowui/src/widgets/containers/window";
import { AppScene, SceneStack } from "gamekit";
import { SceneWindowLayer } from "gamekit/src/ui";

const scenes: SceneStack = new SceneStack();
const layers: SceneWindowLayer = new SceneWindowLayer(scenes, (): WindowManager => new WindowManager());

async function main(): Promise<void> {
    const play: AppScene = new AppScene("play");
    await scenes.start(play);

    // A scene window belongs to one scene: it hides when another scene covers it.
    const inventory: Window = new Window("inventory", "Inventory", "default", 18.0);
    inventory.setSize(240.0, 160.0);
    inventory.body.addChild(new Label("hint", "Hidden while paused.", "default", 14.0));
    engine.root2d.add(inventory.node);
    layers.openSceneWindow(play, inventory);

    // A screen window stays above every scene, across push, pop and replace.
    const chat: Window = new Window("chat", "Chat", "default", 18.0);
    chat.setSize(240.0, 120.0);
    engine.root2d.add(chat.node);
    layers.openScreenWindow(chat);

    await scenes.push(new AppScene("pause"));   // the inventory hides, chat stays
}

await main();
```

| Call | What it does |
|---|---|
| `new SceneWindowLayer(scenes, createManager?, keyboardHandler?, widgetFocus?)` | Watches a stack. `createManager` returns a fresh willowui `WindowManager` for each scene. |
| `openSceneWindow(scene, window)` | Adds a window to that scene's manager. Covering the scene suspends the manager; uncovering resumes it; exiting the scene removes the window. |
| `openScreenWindow(window)` | Adds a window to `screenWindows`, which stays across push, pop and replace. |
| `closeWindow(window)` | Removes a window from its manager without disposing it. You created it, so you dispose it. |
| `sceneWindows(scene)` | That scene's manager. |
| `dispose()` | Ends the layer with the same ownership rule. |

## Focus

One group has focus at a time. The layer checks, in order:

1. A visible modal among the screen windows.
2. A modal on the ready top scene.
3. The floating window clicked last.
4. The top scene itself.

Opening a modal focuses it. `clickWindow(window)` focuses a floating window; `clickScene()` blurs every window manager and gives focus back to the scene, so the scene's own arrow-key handling works again.

Keyboard input goes to the optional `keyboardHandler(window, input)` while a window has focus. Otherwise `dispatchKeyboard(input)` offers it to the top scene's `handleInput`. Pass a willowui `FocusManager` as `widgetFocus` and the focused window is handed to it, so tabbing between widgets stays inside willowui.

The `window-layers` example walks through all of this in a window.

Reference: [SceneWindowLayer](../reference/ui.html#scenewindowlayer), [FocusGroupResolver](../reference/app.html#focusgroupresolver).

---

URL: https://thicketscript.com/gamekit/guide/utilities

# Gauges, picks and spatial helpers

Small helpers that many games need. Each one is independent; use whichever you like.

```ts
import { Gauge, LinearSpatialIndex, Transform2D, WeightedPick } from "gamekit";

// Gauge: a value that fills with time you give it. Good for cooldowns and charge bars.
const dash: Gauge = new Gauge(1.0, 0.5);         // capacity 1, fills 0.5 per second
const ready: boolean = dash.advance(2.0);        // true when it reaches full
console.log("dash ready: " + ready);
dash.consume(1.0);

// WeightedPick: a weighted random choice from a seeded Random.
const loot: WeightedPick<string> = new WeightedPick<string>(new Random(42));
loot.add("coin", 80.0);
loot.add("gem", 19.0);
loot.add("crown", 1.0);
console.log("drop: " + loot.pick());

// Transform2D: plain position, rotation and scale data for simulation code.
const t: Transform2D = new Transform2D(Vec2{ x: 10.0, y: 20.0 });
t.rotation = 0.5;
console.log("at " + t.position.x + ", " + t.position.y);

// LinearSpatialIndex: find things by point, area or nearest.
const index: LinearSpatialIndex<string> = new LinearSpatialIndex<string>();
index.upsert("tree", Rect{ x: 0.0, y: 0.0, width: 10.0, height: 10.0 });
index.upsert("rock", Rect{ x: 50.0, y: 50.0, width: 5.0, height: 5.0 });
console.log("at (5, 5): " + index.point(Vec2{ x: 5.0, y: 5.0 }).join(", "));
console.log("nearest to (40, 40): " + (index.nearest(Vec2{ x: 40.0, y: 40.0 }) ?? "none"));
```

```text
dash ready: true
drop: coin
at 10, 20
at (5, 5): tree
nearest to (40, 40): rock
```

## Gauge

A value between 0 and `capacity` that fills at `rate` per unit of time you pass to `advance(dt)`. Use it for cooldowns, charge bars and stamina.

| Member | Meaning |
|---|---|
| `new Gauge(capacity, rate, start = 0)` | Throws `InvalidArgument` if capacity is not above zero or rate is negative. |
| `advance(dt)` | Fills and returns `true` when this call makes it full. Does nothing while `paused`. |
| `consume(amount)`, `fill()` | Spend some, or fill it at once. |
| `value`, `capacity`, `rate`, `paused` | Plain fields. |

Because time is passed in, a crossing happens on the same tick in every run. [The cooldown recipe](../recipes.html#a-cooldown-in-a-system) uses one in a system.

## WeightedPick

`new WeightedPick<T>(random)` picks items with probability proportional to their weight, from the seeded core `Random` you give it. `fork(name)` copies the entries onto a new picker that draws from `random.fork(name)`; later `add` calls on either one do not affect the other.

## Transform2D and the spatial index

- `Transform2D(position, rotation, scale)` is plain simulation data. It never touches a willow node; copy it onto the screen in your [presentation](./willow-presentation.html) code.
- `LinearSpatialIndex<T>` implements `ISpatialIndex<T>`: `upsert(value, rect)`, `remove`, `point`, `area`, `nearest(point, maxDistance?)` and `swept(rect, delta)`. It checks every entry, which is fine for small sets; implement `ISpatialIndex` for a grid or tree when you have many.

## Music

The `audio` family's `MusicDirector` owns what music is playing. `play(track)` changes it (and skips a change to the track already playing), `push(track)` plays one on top and `pop()` returns to the one below, with a crossfade of the length you choose. It talks to sound through an `IMusicBackend`, so tests can pass a fake. In a game, forward to the core `Audio` system:

```ts
import { Audio, MusicTrack } from "audio";
import { IMusicBackend, MusicDirector } from "gamekit";

// Forwards to the core Audio system.
class CoreMusic implements IMusicBackend {
    async loadMusic(trackId: string): Promise<any> { return await Audio.loadMusic(trackId); }
    playMusicHandle(handle: any, volume: float, loop: boolean): void { Audio.playMusicHandle(handle as MusicTrack, volume, loop); }
    crossfadeTo(handle: any, durationMs: int, volume: float, loop: boolean): void { Audio.crossfadeTo(handle as MusicTrack, durationMs, volume, loop); }
    unloadMusic(handle: any): void { Audio.unloadMusic(handle as MusicTrack); }
}

const music: MusicDirector = new MusicDirector(new CoreMusic(), 800);

async function main(): Promise<void> {
    await music.play("music/town.ogg");
    await music.push("music/battle.ogg");   // town is kept underneath
    await music.pop();                      // crossfades back to town
}

await main();
```

The project lists the `audio` system: `systems: ["willow", "bitmap", "audio"]`.

Reference: [Gauge](../reference/core.html#gauge), [WeightedPick](../reference/core.html#weightedpick), [Transform2D](../reference/core.html#transform2d), [LinearSpatialIndex](../reference/core.html#linearspatialindex), [MusicDirector](../reference/audio.html#musicdirector).

---

URL: https://thicketscript.com/gamekit/guide/willow-presentation

# Drawing with willow

The `willow` family connects your simulation to [willow](../../willow/) nodes without letting the two mix. Your systems change plain records. Once per tick, `adapter.present()` copies each record's state onto its node. Nothing else touches the nodes.

Import it from its folder; the package root never loads it:

```ts
import { WillowPresentationAdapter, WillowPresentationState } from "gamekit/src/willow";
```

## The adapter

`new WillowPresentationAdapter<T>(createNode, readState, syncNode?)` takes your functions:

| Function | Called with | Returns |
|---|---|---|
| `createNode(record)` | A record that has no node yet. | The willow `Node` to show it, for example a `Quad` or a sprite. |
| `readState(record)` | Each bound record, during `present()`. | A `WillowPresentationState`: parent, `x`, `y`, `rotation`, `scaleX`, `scaleY`, `pivotX`, `pivotY`, `skewX`, `skewY`, `alpha`, `visible`, `zOrder`. |
| `syncNode(record, node)` | Optional, after the state is copied. | Nothing. Update node content here, such as a label's text or a sprite frame. |

`adapter.bind(record)` returns a `WillowBinding<T>`. The node is created at the next `present()`. Call `present()` from a `present` phase so it runs after the simulation. [Getting started](../getting-started.html#_6-put-it-in-a-window) has a complete window example.

If your simulation uses `Transform2D` from `core`, have `readState` copy it into the state. Simulation data never holds a node.

## Bindings

| Call | What it does |
|---|---|
| `binding.ticket()` | Takes a ticket for async work (see below). |
| `binding.detach()` | Removes the node from the scene but keeps it, for moving to another parent. |
| `binding.pool()` | Takes the record and parent away but keeps the node for reuse. |
| `binding.reuse(record)` | Gives a pooled binding a new record. |
| `binding.replace(record)` | Disposes the old node; a new one is created at the next `present()`. |
| `binding.dispose()` | Disposes the node and ends the binding. |

## Async work and tickets

Each lifecycle change starts a new binding generation. Before async work (loading a texture, say), take a `WillowBindingTicket<T>`; when the work finishes, `ticket.apply(callback)` runs the callback only if the binding is still on the same generation and its node is alive. A detach, pool, reuse, replace or dispose in between makes the old ticket do nothing, so late work never lands on a recycled or disposed node.

## As a component

`WillowPresentation<T>` wraps a binding as a component. Add it to an entity under your own `ComponentKey` and it follows the entity: attach, detach, reparent and dispose are forwarded to the binding. The record's `readState` still chooses the scene parent, so the entity hierarchy and the willow hierarchy stay independent.

## Ownership

The adapter owns only the nodes `createNode` returned. Call `adapter.dispose()` before you dispose scene roots that contain them. It never disposes the parent you chose or any other node.

Reference: [WillowPresentationAdapter](../reference/willow.html#willowpresentationadapter), [WillowPresentationState](../reference/willow.html#willowpresentationstate), [WillowBinding](../reference/willow.html#willowbinding), [WillowBindingTicket](../reference/willow.html#willowbindingticket), [WillowPresentation](../reference/willow.html#willowpresentation).

---

URL: https://thicketscript.com/gamekit/guide/world-and-systems

# World, queries and systems

The `ecs` family is for games with many similar things: bullets, enemies, tiles, particles. A `World` owns entities and keeps one store per component key, so a query can visit every entity with a given set of components. Systems are plain functions that a `PhaseSchedule` runs in order.

## The World

```ts
const world: World = new World();
world.registerStore(POSITION);           // one store per key, before use
const e: Entity = world.createEntity();  // an active root the world owns
world.put(e, POSITION, new Position(0.0, 0.0));
```

| Method | What it does |
|---|---|
| `registerStore(key)` | Creates the store for a key. Registering a key twice throws. |
| `createEntity()` | Creates an entity, adopts it and activates it. |
| `adoptEntity(entity)` | Takes ownership of an entity you built yourself (or an `Entity` subclass). Returns its new `EntityId`. |
| `put(entity, key, value)` | Adds a component and files it in the key's store. |
| `get`, `getRequired`, `removeComponent` | Read or remove one entity's component. `getRequired` throws when it is missing. |
| `query(key)`, `query2(a, b)` | Queries over one or two keys. |
| `removeEntity(entity)` | Releases the entity without disposing it, so it can move to another world. |
| `disposeEntity(entity)` | Removes and disposes it. |
| `idOf(entity)`, `resolve(id)` | Map between entities and `EntityId`s. A stale id resolves to `null`. |
| `dispose()` | Disposes every entity and closes the world. |

`World` takes an optional `IComponentStoreFactory`. The default, `DenseStoreFactory`, makes a `DenseStore` per key; implement `IComponentStore` if a game needs a different layout.

## Queries

```ts
world.query(POSITION).each((e: Entity, p: Position): void => { /* ... */ });
world.query2(POSITION, VELOCITY).each((e: Entity, p: Position, v: Velocity): void => { /* ... */ });
```

`each` takes a snapshot of matching entities first, so the order is stable and the visit is safe. While a query or a phase is running, the world rejects direct structural changes.

## Deferred commands

Inside a phase, create, dispose and change entities through the `defer` methods. They queue the change, and `flush()` applies the batch:

| Deferred call | Applies at flush |
|---|---|
| `deferCreateEntity()` | Returns the entity at once; it joins the world at flush. |
| `deferDisposeEntity(entity)` | Disposes it. |
| `deferPutComponent(entity, key, value)` | Adds the component. |
| `deferRemoveComponent(entity, key)` | Removes the component. |

## Phase schedules

```ts
const schedule: PhaseSchedule = new PhaseSchedule();
schedule.addPhase("input", [], true);
schedule.addPhase("simulate", ["input"], false);
schedule.addPhase("present", ["simulate"], true);
schedule.addSystem("simulate", (w: World, dt: float, tick: int): void => { /* ... */ });
schedule.run(world, dt, tick);
```

- `addPhase(name, after, flushAfter)` adds a phase. `after` lists phases that must run first. Phases with no ordering between them run in the order you added them.
- `flushAfter: true` makes the phase a command boundary: its systems run, then `world.flush()` applies their deferred work. So an entity created in `simulate` is visible to the next phase in the same tick.
- Each system runs inside `World.runPhase`, which guards against direct structural changes.
- Duplicate names, unknown prerequisites and cycles throw before anything runs. The schedule cannot be changed while it is running. A system that throws stops that run, and the phase's commands stay unflushed.

`createConventionalSchedule()` returns a ready schedule with the phases `input`, `simulate`, `resolve`, `present` and `flush`, each with `flushAfter: true`. You are free to use any phases you like instead, or none.

If you need different timing, drive the world yourself:

```ts
world.runPhase((): void => { collectInput(world); });
world.flush();
world.runPhase((): void => { simulate(world); });
world.runPhase((): void => { present(world); });
world.flush();
```

## Spawning inside a phase

```ts
import { ComponentKey, DefinitionRegistry, Entity, PhaseSchedule, ResolvedDefinition, World } from "gamekit";

class Enemy {
    kind: string;
    hp: int;
    constructor(kind: string, hp: int) {
        this.kind = kind;
        this.hp = hp;
    }
}
const ENEMY: ComponentKey<Enemy> = new ComponentKey<Enemy>("enemy");

const defs: DefinitionRegistry = new DefinitionRegistry();
defs.define("slime", { hp: 3 });
defs.define("big_slime", { hp: 9 }, ["slime"]);

const world: World = new World();
world.registerStore(ENEMY);

const schedule: PhaseSchedule = new PhaseSchedule();
schedule.addPhase("spawn", [], true);        // flushAfter: deferred work lands at the end of the phase
schedule.addPhase("count", ["spawn"]);
schedule.addSystem("spawn", (w: World, dt: float, tick: int): void => {
    // Inside a phase the world rejects direct structural changes. Defer them instead.
    const e: Entity = w.deferCreateEntity();
    const enemy: Enemy = defs.instantiate("big_slime",
        (def: ResolvedDefinition, context: any): Enemy => new Enemy(def.id, def.data.hp as int)) as Enemy;
    w.deferPutComponent(e, ENEMY, enemy);
});
schedule.addSystem("count", (w: World, dt: float, tick: int): void => {
    let total: int = 0;
    w.query(ENEMY).each((e: Entity, enemy: Enemy): void => { total += enemy.hp; });
    console.log("tick " + tick + ": " + w.entityCount + " enemies, " + total + " hp");
});

for (let tick: int = 0; tick < 3; tick++) {
    schedule.run(world, 0.1, tick);
}
```

```text
tick 0: 1 enemies, 9 hp
tick 1: 2 enemies, 18 hp
tick 2: 3 enemies, 27 hp
```

## Stepping the world: WorldTicker

In a window game, let the runtime's fixed tick drive the schedule. `new WorldTicker(node, world, schedule, tickDelta)` sets the node's `onTick` to run `schedule.run(world, tickDelta, tickNumber)` once per tick. The runtime owns the tick rate (`App.tps`), the catch-up cap and `App.timeScale`.

Because a scene is a node, this ties the world to its scene: when `SceneStack` pushes a scene on top, it pauses the node below, so that world stops; when a scene is popped, its node is disposed. `ticker.dispose()` detaches the hook. [Getting started](../getting-started.html#_6-put-it-in-a-window) shows a full example.

In a console program, call `schedule.run` from `App.onTick` yourself. In a headless test, use a `SimulationClock` from the [testing family](./testing-and-debug.html).

Reference: [World](../reference/ecs.html#world), [PhaseSchedule](../reference/ecs.html#phaseschedule), [Query](../reference/ecs.html#query), [Query2](../reference/ecs.html#query2), [WorldTicker](../reference/ecs.html#worldticker), [createConventionalSchedule](../reference/ecs.html#createconventionalschedule).

---

URL: https://thicketscript.com/gamekit/recipes

# Recipes

Each recipe is a complete program. The console ones were run and their output is shown; the window ones were type-checked.

## Spawn from a definition during a phase

Inside a phase the world refuses direct structural changes, so a spawner defers them. The `spawn` phase has `flushAfter: true`, so new enemies are visible to `count` in the same tick.

```ts
import { ComponentKey, DefinitionRegistry, Entity, PhaseSchedule, ResolvedDefinition, World } from "gamekit";

class Enemy {
    kind: string;
    hp: int;
    constructor(kind: string, hp: int) {
        this.kind = kind;
        this.hp = hp;
    }
}
const ENEMY: ComponentKey<Enemy> = new ComponentKey<Enemy>("enemy");

const defs: DefinitionRegistry = new DefinitionRegistry();
defs.define("slime", { hp: 3 });
defs.define("big_slime", { hp: 9 }, ["slime"]);

const world: World = new World();
world.registerStore(ENEMY);

const schedule: PhaseSchedule = new PhaseSchedule();
schedule.addPhase("spawn", [], true);        // flushAfter: deferred work lands at the end of the phase
schedule.addPhase("count", ["spawn"]);
schedule.addSystem("spawn", (w: World, dt: float, tick: int): void => {
    // Inside a phase the world rejects direct structural changes. Defer them instead.
    const e: Entity = w.deferCreateEntity();
    const enemy: Enemy = defs.instantiate("big_slime",
        (def: ResolvedDefinition, context: any): Enemy => new Enemy(def.id, def.data.hp as int)) as Enemy;
    w.deferPutComponent(e, ENEMY, enemy);
});
schedule.addSystem("count", (w: World, dt: float, tick: int): void => {
    let total: int = 0;
    w.query(ENEMY).each((e: Entity, enemy: Enemy): void => { total += enemy.hp; });
    console.log("tick " + tick + ": " + w.entityCount + " enemies, " + total + " hp");
});

for (let tick: int = 0; tick < 3; tick++) {
    schedule.run(world, 0.1, tick);
}
```

```text
tick 0: 1 enemies, 9 hp
tick 1: 2 enemies, 18 hp
tick 2: 3 enemies, 27 hp
```

More: [World, queries and systems](./guide/world-and-systems.html), [Definitions and prefabs](./guide/definitions-and-prefabs.html).

## A cooldown in a system

A `Gauge` per turret fills with the tick's `dt`; the system fires when it reports full.

```ts
import { ComponentKey, Entity, Gauge, PhaseSchedule, World } from "gamekit";

class Turret {
    reload: Gauge = new Gauge(1.0, 2.0);   // full after 0.5 s of ticks
    shots: int = 0;
}
const TURRET: ComponentKey<Turret> = new ComponentKey<Turret>("turret");

const world: World = new World();
world.registerStore(TURRET);
world.put(world.createEntity(), TURRET, new Turret());

const schedule: PhaseSchedule = new PhaseSchedule();
schedule.addPhase("simulate", [], true);
schedule.addSystem("simulate", (w: World, dt: float, tick: int): void => {
    w.query(TURRET).each((e: Entity, t: Turret): void => {
        if (t.reload.advance(dt)) {
            t.reload.consume(1.0);
            t.shots += 1;
        }
    });
});

for (let tick: int = 0; tick < 30; tick++) {
    schedule.run(world, 0.1, tick);      // 3 seconds at 10 ticks per second
}
world.query(TURRET).each((e: Entity, t: Turret): void => {
    console.log("shots in 3 s: " + t.shots);
});
```

```text
shots in 3 s: 6
```

More: [Gauges, picks and spatial helpers](./guide/utilities.html).

## Pause the world with a pause scene

Pushing a scene pauses the node of the scene below. A `WorldTicker` on that node stops with it, and starts again when the pause scene is popped.

```ts
import { Node } from "willow";
import { AppScene, PhaseSchedule, SceneStack, World, WorldTicker } from "gamekit";

class PlayScene extends AppScene {
    world: World = new World();
    schedule: PhaseSchedule = new PhaseSchedule();
    ticker: WorldTicker;

    constructor() {
        super("play");
        const root: Node = new Node("play");
        engine.root2d.add(root);
        this.attachNode(root);
        this.schedule.addPhase("simulate", [], true);
        this.ticker = new WorldTicker(root, this.world, this.schedule, App.tickDelta);
    }
}

class PauseScene extends AppScene {
    constructor() {
        super("pause");
        const root: Node = new Node("pause");
        engine.root2d.add(root);
        this.attachNode(root);
    }
}

const scenes: SceneStack = new SceneStack();
const play: PlayScene = new PlayScene();
await scenes.start(play);

App.onFrame((dt: float): void => {
    if (!Keyboard.isPressed(Key.ESCAPE) || scenes.transitioning) { return; }
    if (scenes.top === play) {
        scenes.push(new PauseScene());   // pauses play's node, so its world stops ticking
    } else {
        scenes.pop();                    // play's node resumes, and so does its world
    }
});
```

More: [Scenes](./guide/scenes.html), [WorldTicker](./guide/world-and-systems.html#stepping-the-world-worldticker).

## Replay recorded input

Record each tick's `ActionFrame`, then feed the recording back through the same step function. The same frames give the same result.

```ts
import { ActionFrame, ActionState, InputRecorder, InputReplay } from "gamekit";
import { SimulationClock } from "gamekit/src/testing";

class Runner {
    x: float = 0.0;
}

// The same step function for live play and for replay.
function step(runner: Runner, frame: ActionFrame, dt: float): void {
    runner.x += frame.axis("move_x") * 100.0 * dt;
}

// 1. A "live" run records each tick's frame.
const recorder: InputRecorder = new InputRecorder();
const live: Runner = new Runner();
const liveClock: SimulationClock = new SimulationClock(0.1, 8, (dt: float, tick: int): void => {
    const axis: float = tick < 5 ? 1.0 : -0.5;
    const frame: ActionFrame = new ActionFrame([new ActionState("move_x", true, false, false, false, axis)]);
    recorder.record(frame);
    step(live, frame, dt);
});
liveClock.advance(1.0);

// 2. A replay feeds the recording back, one frame per tick.
const replay: InputReplay = new InputReplay(recorder.recording());
const again: Runner = new Runner();
const replayClock: SimulationClock = new SimulationClock(0.1, 8, (dt: float, tick: int): void => {
    if (!replay.finished) {
        step(again, replay.next(), dt);
    }
});
replayClock.advance(1.0);
console.log("live " + live.x + ", replay " + again.x + ", same: " + (live.x == again.x));
```

```text
live 35, replay 35, same: true
```

More: [Input actions](./guide/input.html), [Testing and debugging](./guide/testing-and-debug.html).

## Save a world and restore it

Save a component's data to a slot, then build a fresh world from it.

```ts
import { Codec, Codecs, ComponentKey, Entity, MemoryByteStorage, RecordField, SaveResult, SaveSchema, SaveSlotManager, SaveSlotMetadata, World } from "gamekit";

class Hero {
    level: int;
    gold: int;
    constructor(level: int, gold: int) {
        this.level = level;
        this.gold = gold;
    }
}
const HERO: ComponentKey<Hero> = new ComponentKey<Hero>("hero");

const heroCodec: Codec<Hero> = Codecs.record<Hero>(
    [new RecordField("level", Codecs.int()), new RecordField("gold", Codecs.int())],
    (f: any): Hero => new Hero(f.level as int, f.gold as int));
const slots: SaveSlotManager<Hero> = new SaveSlotManager<Hero>(
    new MemoryByteStorage(), new SaveSchema<Hero>("hero", 1, heroCodec));

async function main(): Promise<void> {
    // Play a little, then save the hero component.
    const world: World = new World();
    world.registerStore(HERO);
    const hero: Entity = world.createEntity();
    world.put(hero, HERO, new Hero(4, 120));
    await slots.saveSlot("main", world.getRequired(hero, HERO), new SaveSlotMetadata("main", "hero", 1));
    world.dispose();

    // Later: a fresh world, filled from the save.
    const loaded: SaveResult<Hero> = await slots.loadSlot("main");
    if (!loaded.isOk) {
        console.log("could not load: " + loaded.kind);
        return;
    }
    const fresh: World = new World();
    fresh.registerStore(HERO);
    fresh.put(fresh.createEntity(), HERO, loaded.value as Hero);
    fresh.query(HERO).each((e: Entity, h: Hero): void => {
        console.log("restored level " + h.level + " with " + h.gold + " gold");
    });
}

await main();
```

```text
restored level 4 with 120 gold
```

More: [Saves and settings](./guide/saves.html).

## A purchase that cannot half-happen

A condition refuses the purchase when gold is short; the staged mutation either commits or rolls back.

```ts
import { Action, ActionContext, ActionRequest, ActionResult, Condition, ConditionResult } from "gamekit";

class Wallet {
    gold: int = 30;
}

class Price {
    cost: int;
    constructor(cost: int) { this.cost = cost; }
}

// Conditions explain themselves when they fail.
const canAfford: Condition<ActionContext<Price>> = new Condition<ActionContext<Price>>(
    "can-afford", "not enough gold",
    (ctx: ActionContext<Price>): boolean => (ctx.actor as Wallet).gold >= ctx.payload.cost);

// An action validates, stages mutations, then commits them all or none.
const buy: Action<Price, any> = new Action<Price, any>("buy", "buys an item");
buy.addCondition(canAfford);
buy.validate((ctx: ActionContext<Price>): void => {
    const wallet: Wallet = ctx.actor as Wallet;
    const cost: int = ctx.payload.cost;
    ctx.stageMutation("pay",
        (): void => { wallet.gold -= cost; },
        (): void => { wallet.gold += cost; });
});

const wallet: Wallet = new Wallet();
const first: ActionResult<any> = buy.execute(new ActionRequest<Price>("buy", wallet, null, new Price(20)));
const second: ActionResult<any> = buy.execute(new ActionRequest<Price>("buy", wallet, null, new Price(20)));
console.log("first: " + first.status + ", second: " + second.status + " (" + (second.reason ?? "") + ")");
console.log("gold left: " + wallet.gold);

// Conditions compose.
const positive: Condition<int> = new Condition<int>("positive", "must be above zero", (n: int): boolean => n > 0);
const even: Condition<int> = new Condition<int>("even", "must be even", (n: int): boolean => n % 2 == 0);
const both: ConditionResult = Condition.all<int>([positive, even]).evaluate(3);
console.log("3 passes: " + both.passed + ", reason: " + both.reason);
```

```text
first: committed, second: denied (not enough gold)
gold left: 10
3 passes: false, reason: must be even
```

More: [Conditions, actions and interactions](./guide/conditions-and-actions.html).

---

URL: https://thicketscript.com/gamekit/reference/app

# app family

Scenes, the scene stack and coordinator, screen layers, focus groups, and input actions, routing and replay.

Every symbol on this page is exported from the package root: `import { Name } from "gamekit";`

22 symbols.

| Symbol | Summary |
|---|---|
| [`ActionFrame`](#actionframe) | *class*. Immutable-by-interface snapshot of named logical action states for one application frame. |
| [`ActionState`](#actionstate) | *class*. Complete logical state of one action for a single frame, including edges, repeat, and analog magnitude. |
| [`AppRegistration`](#appregistration) | *class*. Disposable token for one coordinator or scene-stack registration. |
| [`AppScene`](#appscene) | *class*. Base scene with asynchronous lifecycle hooks, focus state, and operation input gating. |
| [`AppState`](#appstate) | *enum*. Coarse coordinator phases reported to application observers. |
| [`FocusGroup`](#focusgroup) | *class*. Supplies the default focus bookkeeping for scenes and non-UI focus groups. |
| [`FocusGroupResolver`](#focusgroupresolver) | *class*. Resolves one focused application group from screen windows, scene windows, and the top scene. |
| [`IFocusGroup`](#ifocusgroup) | *interface*. Defines an application-level focus boundary shared by scenes and window layers. |
| [`InputContext`](#inputcontext) | *class*. Named routing layer that declares exactly which logical actions it can receive. |
| [`InputContextKind`](#inputcontextkind) | *enum*. Describes the game layer receiving routed actions; routing precedence still follows context stack order, not this label. |
| [`InputPolicy`](#inputpolicy) | *class*. Builds edge-aware logical action frames by asking the core `InputMap` about the actions in play. |
| [`InputRecorder`](#inputrecorder) | *class*. Accumulates detached action frames for deterministic replay. |
| [`InputRecording`](#inputrecording) | *class*. Immutable-by-interface sequence of copied logical action frames. |
| [`InputReplay`](#inputreplay) | *class*. Forward-only cursor over an isolated copy of an input recording. |
| [`InputRouter`](#inputrouter) | *class*. Routes logical actions through an explicit context stack while preserving press-to-release ownership. |
| [`InputSample`](#inputsample) | *class*. Normalized state of one physical control during a presentation frame. |
| [`RoutedInput`](#routedinput) | *class*. Per-context action-frame result produced by one `InputRouter.route` call. |
| [`SceneCoordinator`](#scenecoordinator) | *class*. Coordinates the application's sole scene stack with scene-scoped clocks, input contexts, assets, saves, and coarse state. |
| [`SceneOperation`](#sceneoperation) | *class*. Identifies one scene-stack mutation and lets newer work invalidate stale asynchronous completion. |
| [`SceneStack`](#scenestack) | *class*. Owns a game's asynchronous scene stack and keeps focus and input on only its ready top scene. |
| [`ScreenLayers`](#screenlayers) | *class*. The two GameKit containers on Willow's screen-space root (`engine.screen2d`, meta-thicket scenes.md problem 10). |
| [`TickInput`](#tickinput) | *class*. Turns one `InputPolicy` frame per simulation tick into a frame a fixed-step game can consume without losing taps. |

## ActionFrame

```ts
import { ActionFrame } from "gamekit";
class ActionFrame
```

Immutable-by-interface snapshot of named logical action states for one application frame. Missing actions read as inactive, and returned states are copies so recordings cannot be mutated indirectly.

**Members**

```ts
constructor(states: ActionState[] = [])
```
Copies action states into a new frame.

- `states`: Logical states to retain in their supplied order.

```ts
held(action: string): boolean
```
Tests whether an action is continuously active in this frame.

- `action`: Logical action name; unknown names are inactive.

```ts
pressed(action: string): boolean
```
Tests whether an action changed from inactive to active in this frame.

- `action`: Logical action name; unknown names are not pressed.

```ts
released(action: string): boolean
```
Tests whether an action changed from active to inactive in this frame.

- `action`: Logical action name; unknown names are not released.

```ts
repeated(action: string): boolean
```
Tests whether the physical source reported an explicit repeat for this action.

- `action`: Logical action name; unknown names are not repeated.

```ts
axis(action: string): float
```
Reads the strongest qualifying analog value selected for an action.

- `action`: Logical action name; unknown or digital-only names return zero.

```ts
actions(): ActionState[]
```
Returns detached state copies in action-map order.

```ts
copy(): ActionFrame
```
Clones the frame and every contained action state for independent retention.

## ActionState

```ts
import { ActionState } from "gamekit";
class ActionState
```

Complete logical state of one action for a single frame, including edges, repeat, and analog magnitude.

**Members**

```ts
action: string
```
Logical action name, independent of any device control.

```ts
held: boolean
```
Whether the action is active throughout this frame.

```ts
pressed: boolean
```
Whether this frame contains the inactive-to-active edge.

```ts
released: boolean
```
Whether this frame contains the active-to-inactive edge.

```ts
repeated: boolean
```
Whether an active source emitted an explicit repeat in this frame.

```ts
axis: float
```
Signed analog magnitude, or zero when no axis binding qualifies.

```ts
constructor(action: string, held: boolean, pressed: boolean, released: boolean, repeated: boolean, axis: float)
```
Captures one already-resolved action state without further normalization.

- `action`: Name associated with these resolved flags.
- `held`: Continuous active flag.
- `pressed`: Activation-edge flag.
- `released`: Deactivation-edge flag.
- `repeated`: Source repeat flag.
- `axis`: Signed analog magnitude.

```ts
copy(): ActionState
```
Returns an independent state object with the same scalar fields.

## AppRegistration

```ts
import { AppRegistration } from "gamekit";
class AppRegistration
```

Disposable token for one coordinator or scene-stack registration. Disposal is idempotent and prevents that registration from participating in later lifecycle work.

**Members**

```ts
constructor(disposeWork: Function)
```
Wraps the cleanup callback that will run at most once.

- `disposeWork`: Synchronous callback that detaches the registered item.

```ts
get active(): boolean
```
Is `true` until the first call to `dispose`.

```ts
dispose(): void
```
Detaches the registration once; later calls have no effect.

## AppScene

```ts
import { AppScene } from "gamekit";
class AppScene extends FocusGroup
```

Base scene with asynchronous lifecycle hooks, focus state, and operation input gating. A scene belongs to at most one SceneStack; its input remains disabled until it is the ready top scene. Its screen-sized UI goes in `screen`, a container on `engine.screen2d` shown, hidden and paused with the scene.

**Members**

```ts
name: string
```
Human-readable scene name used in ownership diagnostics.

```ts
constructor(name: string)
```
Creates a detached scene. @param name Non-empty diagnostic name. @throws Error when name is empty.

```ts
get isInputEnabled(): boolean
```
Reports whether the ready top scene may receive input.

```ts
get node(): any | null
```
The scene's node, or null when the scene has none or its node was disposed on exit. The stack pauses it while the scene is covered.

```ts
get screen(): Node
```
The scene's screen-space container for screen-sized UI (dialogue, menus, HUDs), drawn without the camera in screen units. It is mounted under `ScreenLayers.scenes` on `engine.screen2d` once the scene has a node or a stack takes it; the stack hides and pauses it while the scene is covered, passes it with the scene's node to transitions, and replaces it with a fresh empty container when the scene is released.

```ts
attachNode(node: any): void
```
Gives this scene the node that carries its tickers, tweens and `World` step. The owning SceneStack sets `paused` on it while the scene is covered and disposes it when the scene is released.

- `node`: A node with a writable `paused` flag and a `dispose()` method.
- Throws: Error when the node is null or the scene already has one.

```ts
async enter(operation?: SceneOperation): Promise<void>
```
Called while input is disabled before this scene becomes active. @param operation Current operation.

```ts
async exit(operation?: SceneOperation): Promise<void>
```
Called with input disabled before this scene is released. @param operation Current operation.

```ts
async suspend(operation?: SceneOperation): Promise<void>
```
Called with input disabled when another scene covers this scene. @param operation Current operation.

```ts
async resume(operation?: SceneOperation): Promise<void>
```
Called with input disabled before this scene becomes ready again. @param operation Current operation.

## AppState

```ts
import { AppState } from "gamekit";
enum AppState
```

Coarse coordinator phases reported to application observers. `FAILURE` retains the triggering error on `SceneCoordinator.failure`; `SHUTDOWN` begins before scenes exit.

| Member | Meaning |
|---|---|
| `BOOT = "boot"` | The coordinator has not begun scene entry. |
| `LOAD = "load"` | A scene is loading or entering. |
| `ACTIVE = "active"` | The top scene is ready to receive work. |
| `SUSPENDED = "suspended"` | The active scene is temporarily paused. |
| `SHUTDOWN = "shutdown"` | Shutdown has begun and scenes are exiting. |
| `FAILURE = "failure"` | A lifecycle operation failed. |

## FocusGroup

```ts
import { FocusGroup } from "gamekit";
class FocusGroup implements IFocusGroup
```

Supplies the default focus bookkeeping for scenes and non-UI focus groups. Extend it and override `handleInput` when a group accepts application input.

**Members**

```ts
activateFocus(): void
```
Gives this group application focus.

```ts
blur(): void
```
Removes application focus from this group.

```ts
get isFocused(): boolean
```
Reports whether this group owns application focus.

```ts
handleInput(input: any): boolean
```
Declines input by default so subclasses opt in explicitly.

- `input`: Caller-defined input value.
- Returns: False unless a subclass handles the value.

## FocusGroupResolver

```ts
import { FocusGroupResolver } from "gamekit";
class FocusGroupResolver
```

Resolves one focused application group from screen windows, scene windows, and the top scene. Resolution is screen modal, scene modal, last clicked group, then top scene, with no nested groups.

**Members**

```ts
constructor(scene: IFocusGroup)
```
Creates a resolver with the current top scene as its fallback group.

- `scene`: Top scene receiving focus when no window group wins.

```ts
setScene(scene: IFocusGroup): void
```
Changes the top-scene fallback and immediately resolves focus.

- `scene`: New top scene.

```ts
setSceneWindowGroup(group: IFocusGroup | null): void
```
Associates the top scene's window layer with this resolver. @param group Scene-owned window group, or null.

```ts
setScreenWindowGroup(group: IFocusGroup | null): void
```
Associates the persistent screen window layer with this resolver. @param group Screen-owned window group, or null.

```ts
setSceneModal(group: IFocusGroup, active: boolean): void
```
Records whether a scene-owned modal currently forces focus. @param group Scene window group. @param active Whether its top window is modal.

```ts
setScreenModal(group: IFocusGroup, active: boolean): void
```
Records whether a screen-owned modal currently forces focus. @param group Screen window group. @param active Whether its top window is modal.

```ts
clicked(group: IFocusGroup): void
```
Records the group most recently clicked and resolves focus.

- `group`: Scene or window group selected by pointer input.

```ts
resolve(): IFocusGroup
```
Applies the documented priority and returns the sole focused group.

- Returns: Screen modal, scene modal, last clicked group, or top scene.

## IFocusGroup

```ts
import { IFocusGroup } from "gamekit";
interface IFocusGroup
```

Defines an application-level focus boundary shared by scenes and window layers. WillowUI keeps widget focus inside a focused window; GameKit resolves only the owning group.

**Members**

```ts
activateFocus(): void
```
Gives keyboard input ownership to this group.

```ts
blur(): void
```
Releases keyboard input ownership from this group.

```ts
readonly isFocused: boolean
```
Reports whether this group currently owns application focus.

```ts
handleInput(input: any): boolean
```
Offers caller-defined input to the focused group.

- `input`: Input value chosen by the game or adapter.
- Returns: True when the group handled the value.

## InputContext

```ts
import { InputContext } from "gamekit";
class InputContext
```

Named routing layer that declares exactly which logical actions it can receive. When contexts overlap, `InputRouter` sends a newly held action to the most recently pushed declaring context.

**Members**

```ts
name: string
```
Non-empty diagnostic name for the routing layer.

```ts
kind: InputContextKind
```
Semantic layer label; it does not determine routing precedence.

```ts
constructor(name: string, kind: InputContextKind, actions: string[])
```
Copies the declared action set for one routing layer.

- `name`: Non-empty diagnostic name.
- `kind`: Simulation, screen, modal, text-entry, or debug label.
- `actions`: Logical action names this context accepts.
- Throws: Error if `name` is empty.

```ts
declares(action: string): boolean
```
Tests membership in the copied action declaration list.

- `action`: Logical action name to query.

```ts
actions(): string[]
```
Returns a detached copy of declared action names in original order.

## InputContextKind

```ts
import { InputContextKind } from "gamekit";
enum InputContextKind
```

Describes the game layer receiving routed actions; routing precedence still follows context stack order, not this label.

| Member | Meaning |
|---|---|
| `SIMULATION = "simulation"` | Input consumed by world or fixed-step simulation. |
| `SCREEN = "screen"` | Input for a full screen or scene. |
| `MODAL = "modal"` | Input for a blocking overlay. |
| `TEXT_ENTRY = "text-entry"` | Input for editable text. |
| `DEBUG = "debug"` | Input reserved for diagnostic controls. |

## InputPolicy

```ts
import { InputPolicy } from "gamekit";
class InputPolicy
```

Builds edge-aware logical action frames by asking the core `InputMap` about the actions in play. Bindings, rebinding and persistence live in `InputMap`; the policy only names the actions to watch, so a game binds `InputMap.bind(Action.JUMP, [Key.SPACE])` and watches `"jump"` here. Axis actions follow the `InputMap` rule: their pressed and released edges come from their two direction actions.

**Members**

```ts
watch(action: string, id: int, keys: int[] = []): InputPolicy
```
Adds one action to every frame this policy builds.

- `action`: Logical action name used by contexts, recordings and game code.
- `id`: The `InputMap` action id bound for it (an enum member converted with `as int`).
- `keys`: Keys bound to the action that WillowUI may claim for a widget. They matter only once `passThrough` is set; leave empty for pad-only actions.
- Returns: This policy, for chaining.
- Throws: Error if the name is empty or already watched.

```ts
passThrough(inputManager: InputManager | null): InputPolicy
```
Makes the policy see only the keys WillowUI left available: a watched key the UI consumed this frame (a modal taking Escape, a focused widget taking Enter) does not press or hold its action, so one key never acts in the UI and the game at once. Read the frame after WillowUI's per-frame update.

- `inputManager`: The WillowUI `InputManager` (its `isKeyAvailable` and `isKeyJustAvailable` are asked); GameKit requires willowui-tks. Null restores raw reads.
- Returns: This policy, for chaining.

```ts
frame(): ActionFrame
```
Reads `InputMap` for the current presentation frame, once per watched action.

- Returns: Logical states in watch order: held, edges, and the `InputMap` value (-1..1 for axes, 0 or 1 for buttons).

```ts
focusLost(): ActionFrame
```
Emits one release for every previously held action, then clears edge history.

- Returns: Release-only frame suitable for routing before focus changes.

```ts
close(): void
```
Rejects a pending `InputMap.captureNext()` so an options screen never leaves a capture running after it closes.

## InputRecorder

```ts
import { InputRecorder } from "gamekit";
class InputRecorder
```

Accumulates detached action frames for deterministic replay.

**Members**

```ts
record(frame: ActionFrame): void
```
Appends a deep frame copy so later mutation cannot alter the recording.

- `frame`: Resolved logical frame to retain.

```ts
recording(): InputRecording
```
Snapshots all frames recorded so far into an independent recording.

```ts
clear(): void
```
Removes retained frames without affecting recordings already produced.

## InputRecording

```ts
import { InputRecording } from "gamekit";
class InputRecording
```

Immutable-by-interface sequence of copied logical action frames.

**Members**

```ts
constructor(frames: ActionFrame[])
```
Deep-copies the supplied frame sequence.

- `frames`: Frames retained in replay order.

```ts
frames(): ActionFrame[]
```
Returns deep copies in replay order.

```ts
get frameCount(): int
```
Number of frames available to a new replay cursor.

## InputReplay

```ts
import { InputReplay } from "gamekit";
class InputReplay
```

Forward-only cursor over an isolated copy of an input recording.

**Members**

```ts
constructor(recording: InputRecording)
```
Copies all recorded frames and positions the cursor before the first one.

- `recording`: Source recording, which remains reusable by other cursors.

```ts
get frameCount(): int
```
Total frames in the replay, independent of cursor position.

```ts
get finished(): boolean
```
Is `true` after the cursor has consumed every frame.

```ts
next(): ActionFrame
```
Advances once and returns a detached copy of the frame at the old cursor.

- Throws: Error when no frames remain.

## InputRouter

```ts
import { InputRouter } from "gamekit";
class InputRouter
```

Routes logical actions through an explicit context stack while preserving press-to-release ownership. A held action stays captured by its original context even if higher contexts appear; removing that context queues one release.

**Members**

```ts
push(context: InputContext): void
```
Places a context at highest routing precedence.

- `context`: Context to add by identity.
- Throws: Error if the same context instance is already routed.

```ts
remove(context: InputContext): void
```
Removes a context and queues releases for actions it currently captures.

- `context`: Context identity to remove; an absent context is ignored.

```ts
route(frame: ActionFrame): RoutedInput
```
Delivers queued releases first, then routes held/released actions while maintaining captures.

- `frame`: Logical action frame to distribute.
- Returns: Per-context frames for all currently routed contexts plus any removed context owed a release.

## InputSample

```ts
import { InputSample } from "gamekit";
class InputSample
```

Normalized state of one physical control during a presentation frame. Platform bridges provide samples; action policy treats disconnected controls as inactive.

**Members**

```ts
device: string
```
Non-empty device namespace used for exact control matching.

```ts
control: string
```
Non-empty control name within the device namespace.

```ts
value: float
```
Signed analog magnitude; digital controls conventionally use zero or one.

```ts
connected: boolean
```
Whether the physical source remains connected and eligible to activate actions.

```ts
repeating: boolean
```
Whether the source emitted an explicit repeat edge this frame.

```ts
constructor(device: string, control: string, value: float, connected: boolean = true, repeating: boolean = false)
```
Captures one bridge-provided control reading.

- `device`: Device namespace.
- `control`: Control code.
- `value`: Signed magnitude interpreted against binding thresholds.
- `connected`: Set `false` for a hot-unplug sample.
- `repeating`: Set `true` only for an explicit platform repeat.
- Throws: Error if device or control is empty.

## RoutedInput

```ts
import { RoutedInput } from "gamekit";
class RoutedInput
```

Per-context action-frame result produced by one `InputRouter.route` call. Reads return copies, and an unknown context receives an empty frame without changing other contexts.

**Members**

```ts
forContext(context: InputContext): ActionFrame
```
Returns a detached frame for one context, creating an empty bucket if needed.

- `context`: Context identity whose delivered actions are requested.

```ts
add(context: InputContext, state: ActionState): void
```
Copies an action state into a context bucket, replacing the same action if already present.

- `context`: Destination context identity.
- `state`: Logical state to copy.

## SceneCoordinator

```ts
import { SceneCoordinator } from "gamekit";
class SceneCoordinator
```

Coordinates the application's sole scene stack with scene-scoped clocks, input contexts, assets, saves, and coarse state. Input and clocks turn off before a scene hook and return only after the new top scene is ready; assets retire on exit. Scene nodes have their own `ticker` (game-loop spec section 3); effects scheduled on a node's ticker respect the node's pause and timeScale state, so `registerClock` with the scene's node ticker integrates time scaling and pause directly.game-loop.md section 6.

**Members**

```ts
scenes: SceneStack
```
Sole scene-lifetime owner used by the coordinator and passive adapters.

```ts
constructor(observer: Function | null = null)
```
Creates a coordinator in `BOOT` with an empty scene stack.

- `observer`: Optional synchronous callback receiving every assigned `AppState` in order.

```ts
get state(): AppState
```
Reports the latest coarse lifecycle state published to the observer.

```ts
get failure(): Error | null
```
Returns the most recent caught lifecycle/save error, or `null` before any failure.

```ts
registerClock(scene: any, clock: any): AppRegistration
```
Associates a pausable clock with a scene, resuming it on activation and pausing it on suspension or exit.

- `scene`: Scene whose active lifetime controls the clock.
- `clock`: A core `Ticker` (paused through its `paused` flag), a scene node's `ticker` (which respects the node's pause and timeScale), or any object exposing synchronous `pause` and `resume` methods.
- Returns: Disposable association; disposal does not pause the clock.
- Throws: Error if `clock` is null.

```ts
registerInputContext(scene: any, router: any, context: any): AppRegistration
```
Pushes a context only while its scene is the ready top and removes it before every scene change.

- `scene`: Scene that owns the context lifetime.
- `router`: Object exposing `push(context)` and `remove(context)`.
- `context`: Neutral input context active only while its owner is the ready top scene.
- Returns: Disposable association that removes an already-active context.
- Throws: Error if the router or context is null.

```ts
registerAssetScope(scene: any, scope: any): AppRegistration
```
Associates a disposable asset scope with a scene so it is released after the scene exits.

- `scene`: Scene that owns the scope lifetime.
- `scope`: Object exposing synchronous `dispose`.
- Returns: Disposable association; early disposal detaches but does not dispose the scope.
- Throws: Error if `scope` is null.

```ts
registerSave(work: Function): AppRegistration
```
Appends asynchronous save work to the coordinator's ordered save pipeline.

- `work`: Zero-argument callback awaited during each save request.
- Returns: Disposable registration that excludes the callback from later save snapshots.
- Throws: Error if `work` is null.

```ts
async boot(scene: any): Promise<boolean>
```
Runs the one-time `BOOT -> LOAD -> ACTIVE` sequence and starts the first scene.

- `scene`: Initial detached scene.
- Returns: `true` when active; `false` after cancellation or a caught failure.
- Throws: Error if boot has already been attempted.

```ts
async replace(scene: any, options: { transition?: Transition } | null = null): Promise<boolean>
```
Publishes `LOAD`, replaces the top scene, then publishes `ACTIVE` on success.

- `scene`: Detached replacement scene.
- `options`: Optional `{ transition }` forwarded to `SceneStack.replace`.
- Returns: `true` on activation; `false` after cancellation or a caught failure.

```ts
async push(scene: any, options: { transition?: Transition } | null = null): Promise<boolean>
```
Suspends the current scene and activates a new top scene without publishing `LOAD`.

- `scene`: Detached scene to push.
- `options`: Optional `{ transition }` forwarded to `SceneStack.push`.
- Returns: `true` on activation; `false` after cancellation or a caught failure.

```ts
async pop(options: { transition?: Transition } | null = null): Promise<boolean>
```
Exits the top scene and resumes the scene beneath it.

- `options`: Optional `{ transition }` forwarded to `SceneStack.pop`.
- Returns: `true` after the boundary completes; `false` after cancellation or a caught failure.

```ts
async suspend(): Promise<boolean>
```
Suspends the current top and publishes `SUSPENDED` without releasing scene ownership.

- Returns: `true` after suspension; `false` after cancellation or a caught failure.

```ts
async resume(): Promise<boolean>
```
Resumes the current top and publishes `ACTIVE`.

- Returns: `true` after resumption; `false` after cancellation or a caught failure.

```ts
async save(): Promise<boolean>
```
Awaits a snapshot of registered save callbacks in registration order, coalescing concurrent callers onto one run.

- Returns: `true` when every callback completes; `false` after storing the first failure.

```ts
async quit(): Promise<boolean>
```
Coalesces quit requests, drains an in-flight save, publishes `SHUTDOWN`, and exits all scenes top-down.

- Returns: `true` after shutdown, or `false` when scene teardown fails and state becomes `FAILURE`.

## SceneOperation

```ts
import { SceneOperation } from "gamekit";
class SceneOperation
```

Identifies one scene-stack mutation and lets newer work invalidate stale asynchronous completion. IDs increase within one stack. Scene hooks may call `check` after awaits.

**Members**

```ts
kind: string
```
Stack operation such as `push`, `replace`, or `shutdown`.

```ts
id: int
```
Monotonic identifier assigned by the owning SceneStack.

```ts
constructor(kind: string, id: int)
```
Creates an active operation marker. @param kind Operation name. @param id Stack-local sequence number.

```ts
get cancelled(): boolean
```
Reports whether newer work cancelled this operation.

```ts
get cancelReason(): string
```
Explains cancellation, or is empty while active.

```ts
cancel(reason: string = "superseded"): void
```
Cancels this operation. @param reason Diagnostic reason used by `check`.

```ts
check(): void
```
Verifies that asynchronous scene work remains current. @throws Error when cancelled.

## SceneStack

```ts
import { SceneStack } from "gamekit";
class SceneStack
```

Owns a game's asynchronous scene stack and keeps focus and input on only its ready top scene. Push covers the prior scene, pop is back navigation, and replace keeps the same stack position.

**Members**

```ts
constructor(observer: any = null)
```
Creates an empty stack. @param observer Optional passive scene lifecycle observer.

```ts
get count(): int
```
Counts owned scenes, including covered scenes.

```ts
get top(): any | null
```
Returns the focused top scene, or null when empty.

```ts
scenes(): any[]
```
Returns a detached bottom-to-top scene snapshot.

```ts
get transitioning(): boolean
```
Reports whether a scene lifecycle hook is still completing.

```ts
addObserver(observer: any): AppRegistration
```
Adds a passive lifecycle observer without sharing stack ownership.

- `observer`: Object implementing the `_sceneChanging`, `_sceneActivated`, `_sceneSuspended`, `_sceneResumed`, and `_sceneExited` hooks it needs.
- Returns: Disposable observer registration.
- Throws: Error for null or duplicate observers.

```ts
async start(scene: any): Promise<boolean>
```
Enters the first scene with input gated until it is ready.

- `scene`: Detached scene to own.
- Returns: True after activation, or false when superseded.
- Throws: Error when non-empty or the scene is already owned.

```ts
async replace(scene: any, options: { transition?: Transition } | null = null): Promise<boolean>
```
Exits the top scene and enters a replacement without resuming a covered scene.

- `scene`: Detached replacement scene.
- `options`: Optional `{ transition }`: a Willow transition played between the two scene nodes; input stays gated and the leaving node alive until it ends.
- Returns: True after activation, or false when superseded.

```ts
async push(scene: any, options: { transition?: Transition } | null = null): Promise<boolean>
```
Suspends the current top and pushes a new scene above it.

- `scene`: Detached scene to push.
- `options`: Optional `{ transition }` played between the two scene nodes, as for `replace`.
- Returns: True after activation, or false when superseded.

```ts
async pop(options: { transition?: Transition } | null = null): Promise<boolean>
```
Pops the top scene and resumes the scene beneath it as back navigation.

- `options`: Optional `{ transition }` played from the popped scene node to the one beneath, as for `replace`.
- Returns: True after the boundary, or false when superseded.
- Throws: Error when the stack is empty.

```ts
async suspend(): Promise<boolean>
```
Suspends the top scene in place. @returns True after suspension, or false when superseded.

```ts
async resume(): Promise<boolean>
```
Resumes the top scene in place, enabling input only after its hook completes. @returns True after readiness.

```ts
async shutdown(): Promise<void>
```
Exits and releases every scene from top to bottom with input disabled.

## ScreenLayers

```ts
import { ScreenLayers } from "gamekit";
class ScreenLayers
```

The two GameKit containers on Willow's screen-space root (`engine.screen2d`, meta-thicket scenes.md problem 10). `scenes` holds one `AppScene.screen` per scene, in the order the scenes were mounted; `overlay` is drawn above all of them and is never part of a scene transition, so a toast or debug HUD added there stays on top. Scene screens draw on WillowUI's `RENDER_LAYER_UI` and the overlay on `RENDER_LAYER_OVERLAY`, so a plain quad (a fade, a gauge) sorts with the WillowUI windows beside it in tree order.

**Members**

```ts
static get scenes(): Node
```
The container under screen2d that holds each scene's screen container. Created on first read.

```ts
static get overlay(): Node
```
The app-global screen container drawn above every scene's UI; add screen-sized nodes that outlive scenes here.

```ts
static mount(): boolean
```
Adds both containers to `Scene.main.screenRoot` when a Willow scene is running and they are not there yet.

- Returns: True when both containers are on the running scene's screen root, false without a Willow scene.

## TickInput

```ts
import { TickInput } from "gamekit";
class TickInput
```

Turns one `InputPolicy` frame per simulation tick into a frame a fixed-step game can consume without losing taps. Devices latch their edges once per presentation frame, so a game that ticks slower than it draws (or reads mid-tick) can miss a short press. This helper reads true `pressed` on the first tick an action is held even when the device edge fell in a frame that ran no tick, and never twice for one hold; and a direction pair declared with `axis` that was pressed and already released still counts as one tick of that axis, so a sub-tick tap moves one step.

**Members**

```ts
axis(axis: string, negative: string, positive: string): TickInput
```
Declares a two-button axis whose sub-tick taps still count as one tick of -1 or 1.

- `axis`: Name of the axis action in the frame (its value is replaced only when the frame reports 0).
- `negative`: Name of the action pushing the axis to -1.
- `positive`: Name of the action pushing the axis to 1.
- Returns: This helper, for chaining.

```ts
next(frame: ActionFrame): ActionFrame
```
Normalises this tick's frame; call exactly once per tick.

- `frame`: The `InputPolicy` frame read this tick.
- Returns: The frame the simulation consumes: same actions, press-once-per-hold, tap-reliable axes.

---

URL: https://thicketscript.com/gamekit/reference/audio

# audio family

Music playback ownership with an injected backend.

Import these from `gamekit/src/audio` (a few are also re-exported by the package root, as noted on each).

2 symbols, 2 of them also in the package root.

| Symbol | Summary |
|---|---|
| [`IMusicBackend`](#imusicbackend) | *interface*. Small boundary around music playback so a game may adapt core `Audio` and tests may use a deterministic fake. |
| [`MusicDirector`](#musicdirector) | *class*. Owns the current music request, avoiding duplicate changes and restoring temporarily stacked tracks. |

## IMusicBackend

```ts
import { IMusicBackend } from "gamekit";
interface IMusicBackend
```

Small boundary around music playback so a game may adapt core `Audio` and tests may use a deterministic fake.

**Members**

```ts
loadMusic(trackId: string): Promise<any>
```
Loads one track and returns its opaque core audio handle.

- `trackId`: Project-relative track identifier accepted by the core audio backend.
- Returns: A promise for the loaded handle.

```ts
playMusicHandle(handle: any, volume: float, loop: boolean): void
```
Starts a loaded track without a transition.

- `handle`: Opaque handle returned by `loadMusic`.
- `volume`: Target gain, where 1 is normal volume.
- `loop`: Whether playback repeats after completion.

```ts
crossfadeTo(handle: any, durationMs: int, volume: float, loop: boolean): void
```
Transitions from the active track to a loaded track.

- `handle`: Opaque handle returned by `loadMusic`.
- `durationMs`: Transition duration in milliseconds.
- `volume`: Target gain, where 1 is normal volume.
- `loop`: Whether playback repeats after completion.

```ts
unloadMusic(handle: any): void
```
Cancels and releases a loaded track that is no longer current.

- `handle`: Opaque handle returned by `loadMusic`.

## MusicDirector

```ts
import { MusicDirector } from "gamekit";
class MusicDirector
```

Owns the current music request, avoiding duplicate changes and restoring temporarily stacked tracks. Supply an `IMusicBackend` implementation or a small adapter that forwards to core `Audio`; the checker does not currently accept `typeof Audio` directly as the interface. An outgoing handle remains retained for the full following transition and releases only on the next transition or `dispose`, so the mixer never fades from a freed track.

**Members**

```ts
constructor(backend: IMusicBackend, crossfadeMs: int = 500)
```
Creates a director over `backend` with a fixed crossfade length.

- `backend`: Music boundary, normally an adapter over core `Audio` or a test fake.
- `crossfadeMs`: Crossfade length in milliseconds.
- Default: 500

```ts
async play(trackId: string): Promise<void>
```
Makes `trackId` current. Repeating the current id makes no backend request. A replaced handle remains loaded throughout this transition and releases when a later transition begins or this director is disposed.

- `trackId`: Project-relative track identifier.
- Returns: A promise that resolves after the requested track is loaded and started or crossfaded.

```ts
async push(trackId: string): Promise<void>
```
Temporarily makes `trackId` current and remembers the prior track for `pop`.

- `trackId`: Project-relative track identifier.
- Returns: A promise that resolves after the requested track is loaded and started or crossfaded.

```ts
async pop(): Promise<void>
```
Brings back the most recently pushed track; does nothing when the temporary-track stack is empty.

- Returns: A promise that resolves after the prior track is loaded and crossfaded.

```ts
dispose(): void
```
Releases the current handle and the one retained for a completed fade, then clears all track requests. Call this when the director's owner is finished with music playback.

---

URL: https://thicketscript.com/gamekit/reference/core

# core family

Entities, keys, events and pipelines, attributes and state machines, effects, definitions and prefabs, conditions, actions and interactions, assets, 2D spatial types, gauges and weighted picks.

Every symbol on this page is exported from the package root: `import { Name } from "gamekit";`

80 symbols.

| Symbol | Summary |
|---|---|
| [`Action`](#action) | *class*. Executes validation, transactional mutations, rollback, and post-commit notifications in fixed order. |
| [`ActionContext`](#actioncontext) | *class*. Per-execution request view and staging area shared by action validation and commit callbacks. |
| [`ActionMutation`](#actionmutation) | *class*. Named reversible unit of commit work with explicit applied state. |
| [`ActionRequest`](#actionrequest) | *class*. Immutable-by-convention invocation data for a named Action. |
| [`ActionResult`](#actionresult) | *class*. Terminal action status with output, diagnostics, and mutation history available for compensation. |
| [`ActionSequence`](#actionsequence) | *class*. Executes action/request pairs in order and can compensate earlier commits after a later failure. |
| [`ActionSequenceResult`](#actionsequenceresult) | *class*. Terminal status and per-step results from an ActionSequence execution. |
| [`ActionSequenceStep`](#actionsequencestep) | *class*. Binds one Action to the request used when its sequence reaches that step. |
| [`ActionStatus`](#actionstatus) | *enum*. Defines the closed action status value set. |
| [`AssetCancellationToken`](#assetcancellationtoken) | *class*. Cooperative cancellation flag observed between entries of an AssetLoadPlan. |
| [`AssetFailure`](#assetfailure) | *class*. Captures one failed or dependency-blocked asset-plan entry. |
| [`AssetHandle`](#assethandle) | *class*. Retains one loaded asset until its owner releases the handle. |
| [`AssetKey`](#assetkey) | *class*. Identifies one typed asset independently of its diagnostic label. |
| [`AssetLoadPlan`](#assetloadplan) | *class*. Mutable dependency graph of asset keys with per-entry loader, weight, and retry policy. |
| [`AssetLoadProgress`](#assetloadprogress) | *class*. Mutable progress snapshot passed to an AssetManager plan callback after each outcome. |
| [`AssetManager`](#assetmanager) | *class*. Selects loaders, coalesces in-flight work, caches values, and unloads them after the final handle releases. |
| [`AssetPlanEntry`](#assetplanentry) | *class*. One asset-plan node with dependency identities and load policy. |
| [`AssetPlanResult`](#assetplanresult) | *class*. Aggregate handles, failures, counts, and cancellation state from one plan run. |
| [`AssetScope`](#assetscope) | *class*. Groups asset handles so a scene, screen, or other owner can release them together. |
| [`Attribute`](#attribute) | *class*. Lazily computes a value from a base or dependency set, then applies ordered modifiers and a final clamp. |
| [`AttributeInspection`](#attributeinspection) | *class*. Point-in-time diagnostic snapshot of an Attribute after refresh. |
| [`AttributeModifier`](#attributemodifier) | *class*. Named pure transformation applied to an Attribute at an explicit priority. |
| [`AttributeSubscription`](#attributesubscription) | *class*. Idempotent lifetime handle for one Attribute change observer. |
| [`cloneValue`](#clonevalue) | *function*. Deep-copies arrays, maps, and object properties while preserving primitive values. |
| [`ComponentKey`](#componentkey) | *class*. Identifies one component capability or ECS store independently of its label. |
| [`Condition`](#condition) | *class*. Normalizes boolean, string, or ConditionResult evaluators into composable diagnostic outcomes. |
| [`ConditionResult`](#conditionresult) | *class*. Normalized condition outcome with a primary explanation and optional aggregate reasons. |
| [`ContextKey`](#contextkey) | *class*. Identifies a typed hierarchical context value without relying on string lookup. |
| [`CyclicDefinition`](#cyclicdefinition) | *class*. Reports an inheritance cycle discovered while resolving definitions. |
| [`CyclicDependency`](#cyclicdependency) | *class*. Reports a directed dependency cycle, such as an asset load-plan loop. |
| [`Definition`](#definition) | *class*. Immutable source definition with copied data and ordered parent ids. |
| [`DefinitionError`](#definitionerror) | *class*. Adds definition identity and provenance to a registry resolution failure. |
| [`DefinitionRegistry`](#definitionregistry) | *class*. Resolves named definitions through ordered multiple inheritance and validator callbacks. |
| [`DuplicateRegistration`](#duplicateregistration) | *class*. Reports a second registration for an identity that must be unique. |
| [`EffectApplication`](#effectapplication) | *class*. Incoming typed effect payload and policy options passed through the application pipeline. |
| [`EffectCollection`](#effectcollection) | *class*. Owns effect handles, applies admission and stacking policy, and mirrors owner lifecycle callbacks. |
| [`EffectHandle`](#effecthandle) | *class*. Stable handle controlling one effect's lifecycle, timer, and source cleanup. |
| [`EffectKey`](#effectkey) | *class*. Identifies an effect kind and its typed payload across an entity's collection. |
| [`EffectOptions`](#effectoptions) | *class*. Optional collision, source-lifetime, and timed-expiration policy for an effect. |
| [`EffectRemovalReason`](#effectremovalreason) | *enum*. Defines the closed effect removal reason value set. |
| [`EffectStacking`](#effectstacking) | *class*. Factory for common collision policies consumed by EffectCollection. |
| [`EffectStackingContext`](#effectstackingcontext) | *class*. Collision-policy view of the incoming application and matching handles in insertion order. |
| [`EffectStackingResolution`](#effectstackingresolution) | *class*. Policy decision naming `accept`, `reject`, `replace`, or `refresh` plus an optional retained handle. |
| [`EffectState`](#effectstate) | *enum*. Defines the closed effect state value set. |
| [`Entity`](#entity) | *class*. Owns a game object's hierarchy, local facts, components, and effects. |
| [`EntityAllocator`](#entityallocator) | *class*. Issues compact generational entity ids and recycles released slots without reviving stale handles. |
| [`EntityId`](#entityid) | *class*. Names one lifetime of an allocator slot using an index-and-generation pair. |
| [`EntityState`](#entitystate) | *enum*. Defines the closed entity state value set. |
| [`EntityTeardownQueue`](#entityteardownqueue) | *class*. Deduplicates deferred Entity disposal until an explicit FIFO flush boundary. |
| [`EventKey`](#eventkey) | *class*. Identifies an event channel and statically carries the emitted payload type. |
| [`EventScope`](#eventscope) | *class*. Owns typed local event listeners and delivers snapshot notifications in subscription order. |
| [`EventSubscription`](#eventsubscription) | *class*. Idempotent handle controlling one listener's lifetime in an EventScope. |
| [`FakeAssetLoader`](#fakeassetloader) | *class*. Deterministic in-memory loader with configurable failures, delays, and call-order inspection. |
| [`GameKitError`](#gamekiterror) | *class*. Base error type for GameKit style guide and lifecycle violations. |
| [`Gauge`](#gauge) | *class*. Neutral rate-filled value for cooldowns, charge bars and any meter that fills with time. |
| [`InteractionContext`](#interactioncontext) | *class*. Typed actor, target, and environment tuple shared across interaction discovery. |
| [`InteractionDefinition`](#interactiondefinition) | *class*. Builds one executable offer from context, optional availability logic, and metadata. |
| [`InteractionOffer`](#interactionoffer) | *class*. Point-in-time executable interaction choice produced during discovery. |
| [`InteractionProvider`](#interactionprovider) | *class*. Named discovery callback that produces zero or more offers for one context. |
| [`InteractionRegistry`](#interactionregistry) | *class*. Aggregates providers in registration order without imposing ranking or deduplication. |
| [`InvalidArgument`](#invalidargument) | *class*. Reports a public API argument that violates an immediate precondition. |
| [`InvalidDefinition`](#invaliddefinition) | *class*. Reports definition data that cannot be validated or resolved. |
| [`ISpatialIndex`](#ispatialindex) | *interface*. Defines deterministic identity-based insertion and broad-phase 2D spatial queries. |
| [`KeyedRegistry`](#keyedregistry) | *class*. Associates heterogeneous values with exact typed-key identities in registration order. |
| [`LinearSpatialIndex`](#linearspatialindex) | *class*. Simple insertion-ordered spatial index that linearly scans copied bounds. |
| [`mergeData`](#mergedata) | *function*. Recursively overlays plain objects and maps, while other values replace the base. |
| [`MissingRegistration`](#missingregistration) | *class*. Reports a required typed-key, component, or definition registration that is absent. |
| [`MutablePipeline`](#mutablepipeline) | *class*. Runs mutable processing stages over one shared context snapshot in insertion order. |
| [`PipelineContext`](#pipelinecontext) | *class*. Mutable per-run input, cancellation flag, and optional output shared by pipeline stages. |
| [`PipelineResult`](#pipelineresult) | *class*. Immutable-by-convention snapshot of a completed pipeline's cancellation and output state. |
| [`PipelineSubscription`](#pipelinesubscription) | *class*. Idempotent lifetime handle for one stage in a MutablePipeline. |
| [`Prefab`](#prefab) | *class*. Reusable factory binding for one definition id in a specific registry. |
| [`ResolvedDefinition`](#resolveddefinition) | *class*. Fully merged definition data plus the ordered ids that contributed to it. |
| [`StaleHandle`](#stalehandle) | *class*. Reports mutation through an entity or effect handle whose lifetime has ended. |
| [`StateMachine`](#statemachine) | *class*. Runs explicit named-state callbacks with guarded, FIFO transitions and optional clock scheduling. |
| [`StateMachineInspection`](#statemachineinspection) | *class*. Point-in-time diagnostic counters and lifecycle flags for a StateMachine. |
| [`StateMachineState`](#statemachinestate) | *class*. Named state with optional owner callbacks for entry, exit, and fixed updates. |
| [`Transform2D`](#transform2d) | *class*. Mutable 2D position, rotation, and scale value with no scene-graph ownership. |
| [`TypedKey`](#typedkey) | *class*. Provides a process-unique, type-carrying identity for registries; labels are diagnostic only. |
| [`WeightedPick`](#weightedpick) | *class*. Weighted choice over an injected `Random`, the only source of chance, so a seed gives a fixed sequence. |

## Action

```ts
import { Action } from "gamekit";
class Action<TPayload, TData>
```

Executes validation, transactional mutations, rollback, and post-commit notifications in fixed order. Validation denial never mutates; commit failure rolls back applied mutations in reverse order.

**Members**

```ts
id: string
```
Stable identifier for this Action.

```ts
description: string
```
Human-readable explanation of this item.

```ts
constructor(id: string, description: string = "")
```
Creates a named action with no conditions, validation stages, or commit callback.

```ts
addCondition(condition: Condition<any>): Action<TPayload, TData>
```
Appends a precondition and returns this action for fluent configuration.

```ts
precondition(condition: Condition<any>): Action<TPayload, TData>
```
Fluent alias for appending a condition.

```ts
guard(condition: Condition<any>): Action<TPayload, TData>
```
Fluent alias for appending a condition.

```ts
validate(stage: Function): Action<TPayload, TData>
```
Appends a validation callback that may deny through context or throw failure.

```ts
onCommit(commitFn: Function): Action<TPayload, TData>
```
Replaces the callback that stages or applies commit work after validation.

```ts
execute(request: ActionRequest<TPayload>, targetScope: EventScope | null = null): ActionResult<TData>
```
Runs conditions and validators, commits staged mutations, then emits notifications. Notification failures are isolated after a successful commit.

## ActionContext

```ts
import { ActionContext } from "gamekit";
class ActionContext<TPayload>
```

Per-execution request view and staging area shared by action validation and commit callbacks.

**Members**

```ts
request: ActionRequest<TPayload>
```
Original request that owns this execution.

```ts
actor: any
```
Actor reference copied from the request for callback convenience.

```ts
target: any
```
Target reference copied from the request for callback convenience.

```ts
payload: TPayload
```
Typed payload copied from the request.

```ts
metadata: any
```
Auxiliary request metadata reference.

```ts
constructor(request: ActionRequest<TPayload>)
```
Copies request fields and starts with no denial, output, mutations, or notifications.

```ts
deny(reason: string): void
```
Marks validation denied and records the explanation returned to the caller.

```ts
get isDenied(): boolean
```
Whether any validation callback has denied execution.

```ts
get denialReason(): string
```
Latest explanation supplied to `deny`.

```ts
produce(data: any): void
```
Replaces the successful result payload.

```ts
get resultData(): any
```
Latest produced payload, or `null` when none was produced.

```ts
stageMutation(id: string, apply: Function, rollback: Function | null = null): ActionMutation
```
Creates and appends an unapplied mutation for commit-order execution.

```ts
addMutation(mutation: ActionMutation): void
```
Appends a prebuilt mutation to the commit sequence.

```ts
get stagedMutations(): ActionMutation[]
```
Ordered mutation list consumed by Action after the commit callback.

```ts
emitOnCommit(scope: EventScope, key: EventKey<any>, event: any): void
```
Queues an event fact for best-effort emission only after all mutations commit.

```ts
get stagedNotifications(): ActionNotificationEntry[]
```
Ordered post-commit notification list consumed by Action.

## ActionMutation

```ts
import { ActionMutation } from "gamekit";
class ActionMutation
```

Named reversible unit of commit work with explicit applied state.

**Members**

```ts
id: string
```
Stable identifier for this ActionMutation.

```ts
apply: Function
```
Callback invoked once during forward commit.

```ts
rollback: Function | null
```
Optional compensation callback invoked in reverse order.

```ts
applied: boolean = false
```
Whether forward work remains eligible for rollback.

```ts
constructor(id: string, apply: Function, rollback: Function | null = null)
```
Captures a non-empty diagnostic id and forward/optional compensation callbacks.

## ActionRequest

```ts
import { ActionRequest } from "gamekit";
class ActionRequest<TPayload>
```

Immutable-by-convention invocation data for a named Action.

**Members**

```ts
actionId: string
```
Non-empty action identity expected by dispatching game code.

```ts
actor: any
```
Game object initiating the action, or `null`.

```ts
target: any
```
Game object receiving the action, or `null`.

```ts
payload: TPayload
```
Typed action-specific input.

```ts
metadata: any
```
Optional auxiliary data not interpreted by GameKit.

```ts
constructor(actionId: string, actor: any = null, target: any = null, payload: TPayload = null, metadata: any = null)
```
Captures a non-empty action id and game-owned invocation values.

## ActionResult

```ts
import { ActionResult } from "gamekit";
class ActionResult<TData>
```

Terminal action status with output, diagnostics, and mutation history available for compensation.

**Members**

```ts
status: ActionStatus
```
Committed, denied-before-commit, or failed-during-validation/commit.

```ts
request: ActionRequest<any>
```
Original request associated with the execution.

```ts
data: TData | null
```
Produced success payload, or `null` for denial/failure or no output.

```ts
reason: string | null
```
Human-readable denial or failure explanation, when applicable.

```ts
error: Error | null
```
Caught validation or commit exception, never notification errors.

```ts
appliedMutations: ActionMutation[]
```
Forward mutations attempted before terminal completion.

```ts
constructor( status: ActionStatus, request: ActionRequest<any>, data: TData | null = null, reason: string | null = null, error: Error | null = null, appliedMutations: ActionMutation[] = [] )
```
Captures terminal execution state without copying request or mutation references.

```ts
get ok(): boolean
```
`true` only for a fully committed action.

```ts
get isCommitted(): boolean
```
Whether validation and every mutation completed successfully.

```ts
get isDenied(): boolean
```
Whether validation rejected execution before commit.

```ts
get isFailed(): boolean
```
Whether a validator or commit callback threw.

```ts
rollback(): void
```
Best-effort compensates still-applied mutations in reverse order; compensation errors are isolated.

## ActionSequence

```ts
import { ActionSequence } from "gamekit";
class ActionSequence
```

Executes action/request pairs in order and can compensate earlier commits after a later failure.

**Members**

```ts
constructor(rollbackOnFailure: boolean = true)
```
Configures whether a denied or failed step rolls back earlier committed steps.

```ts
add(action: Action<any, any>, request: ActionRequest<any>): ActionSequence
```
Appends an action and its request and returns this sequence for chaining.

```ts
execute(targetScope: EventScope | null = null): ActionSequenceResult
```
Stops on the first non-commit and optionally rolls back prior results in reverse order.

## ActionSequenceResult

```ts
import { ActionSequenceResult } from "gamekit";
class ActionSequenceResult
```

Terminal status and per-step results from an ActionSequence execution.

**Members**

```ts
status: ActionStatus
```
Overall status, inherited from the first unsuccessful step when present.

```ts
executedCount: int
```
Number of steps attempted, including the unsuccessful step.

```ts
results: ActionResult<any>[]
```
Ordered results for every attempted step.

```ts
rolledBack: boolean
```
Whether compensation of prior committed steps was requested.

```ts
failureReason: string | null
```
First denial or failure explanation, or `null` on complete commit.

```ts
constructor( status: ActionStatus, executedCount: int, results: ActionResult<any>[], rolledBack: boolean, failureReason: string | null = null )
```
Captures sequence outcome and ordered step history.

```ts
get ok(): boolean
```
`true` only when every step committed.

## ActionSequenceStep

```ts
import { ActionSequenceStep } from "gamekit";
class ActionSequenceStep
```

Binds one Action to the request used when its sequence reaches that step.

**Members**

```ts
action: Action<any, any>
```
Executable action reference.

```ts
request: ActionRequest<any>
```
Invocation passed to the action.

```ts
constructor(action: Action<any, any>, request: ActionRequest<any>)
```
Captures the action/request pair without executing it.

## ActionStatus

```ts
import { ActionStatus } from "gamekit";
enum ActionStatus
```

Defines the closed action status value set. Store and compare these values directly rather than introducing string aliases;

| Member | Meaning |
|---|---|
| `COMMITTED = "committed"` | The requested mutations completed. |
| `DENIED = "denied"` | Validation or a rule denied the request. |
| `FAILED = "failed"` | Execution started but did not complete successfully. |

## AssetCancellationToken

```ts
import { AssetCancellationToken } from "gamekit";
class AssetCancellationToken
```

Cooperative cancellation flag observed between entries of an AssetLoadPlan.

**Members**

```ts
isCancelled: boolean = false
```
Whether cancellation has been requested.

```ts
reason: string = ""
```
Latest game-supplied cancellation explanation.

```ts
cancel(reason: string = "cancelled"): void
```
Permanently marks the token cancelled and records the reason.

## AssetFailure

```ts
import { AssetFailure } from "gamekit";
class AssetFailure
```

Captures one failed or dependency-blocked asset-plan entry.

**Members**

```ts
key: AssetKey<any>
```
Asset whose load did not complete.

```ts
message: string
```
Final human-readable failure explanation.

```ts
error: any
```
Last thrown loader value, or `null` for dependency blocking.

```ts
attempts: int
```
Loader invocations made; zero means a dependency blocked loading.

```ts
trace: string[]
```
Per-attempt diagnostic lines in execution order.

```ts
constructor(key: AssetKey<any>, message: string, error: any = null, attempts: int = 1, trace: string[] = [])
```
Captures the terminal failure details for plan inspection.

## AssetHandle

```ts
import { AssetHandle } from "gamekit";
class AssetHandle<T>
```

Retains one loaded asset until its owner releases the handle.

**Members**

```ts
key: AssetKey<T>
```
Key of the asset retained by this handle.

```ts
isReleased: boolean = false
```
Whether this handle has already dropped its manager reference.

```ts
constructor(key: AssetKey<T>, manager: IAssetHandleManager<T>, scope: IAssetHandleScope | null = null)
```
Creates a handle managed by `AssetManager`; consumers normally receive one from `load` or `acquire`.

```ts
get scope(): IAssetHandleScope | null
```
Scope that will release this handle, or `null` for an independently managed handle.

```ts
get(): T
```
Reads the retained asset value while the handle remains live.

- Throws: StaleHandle When this handle has been released.

```ts
release(): void
```
Releases this handle's reference and detaches it from its scope. Repeated calls do nothing; the asset unloads when this is its final handle.

## AssetKey

```ts
import { AssetKey } from "gamekit";
class AssetKey<T> extends TypedKey<T>
```

Identifies one typed asset independently of its diagnostic label.

**Members**

```ts
constructor(label: string)
```
Allocates a fresh asset identity with the label shown in diagnostics.

## AssetLoadPlan

```ts
import { AssetLoadPlan } from "gamekit";
class AssetLoadPlan
```

Mutable dependency graph of asset keys with per-entry loader, weight, and retry policy.

**Members**

```ts
entries: Array<AssetPlanEntry> = []
```
Registration-ordered entries; adding an existing key replaces it in place.

```ts
add<T>( key: AssetKey<T>, dependencies: Array<AssetKey<any>> = [], options: any = null ): AssetLoadPlan
```
Adds or replaces an entry, normalizing weight and retry values in AssetPlanEntry.

```ts
has(key: AssetKey<any>): boolean
```
Tests membership by exact AssetKey identity.

```ts
getEntry(key: AssetKey<any>): AssetPlanEntry | null
```
Returns the entry for exact key identity, or `null` when absent.

```ts
validate(): void
```
Resolves dependency waves to detect cycles before any loader work begins.

```ts
getTopologicalWaves(): Array<Array<AssetPlanEntry>>
```
Groups entries into dependency-ready waves while preserving registration order within each wave. Dependencies outside the plan are assumed already satisfied.

## AssetLoadProgress

```ts
import { AssetLoadProgress } from "gamekit";
class AssetLoadProgress
```

Mutable progress snapshot passed to an AssetManager plan callback after each outcome.

**Members**

```ts
loadedCount: int = 0
```
Entries that acquired a handle successfully.

```ts
totalCount: int = 0
```
Total entries declared by the plan.

```ts
loadedWeight: int = 0
```
Sum of successful entry weights.

```ts
totalWeight: int = 0
```
Sum of all normalized entry weights.

```ts
ratio: float = 0.0
```
Successful weight divided by total weight, from zero through one.

```ts
lastKey: AssetKey<any> | null = null
```
Most recently loaded key, or `null` before the first success.

```ts
failedCount: int = 0
```
Entries failed or blocked by failed dependencies.

## AssetManager

```ts
import { AssetManager } from "gamekit";
class AssetManager implements IAssetHandleManager<any>, IAssetScopeManager
```

Selects loaders, coalesces in-flight work, caches values, and unloads them after the final handle releases. Create one manager for the asset domain that owns its loaders, then shut it down only after every scope has stopped requesting assets.

**Members**

```ts
isShutdown: boolean = false
```
Whether this manager has stopped accepting new work.

```ts
constructor(defaultLoader: any = null)
```
Starts an empty asset domain with an optional fallback loader.

```ts
registerLoader<T>(key: AssetKey<T>, loader: any): void
```
Associates a loader with exact key identity, replacing any earlier association.

```ts
setDefaultLoader(loader: any): void
```
Replaces the fallback selected when a key has no loader override.

```ts
createScope(name: string = ""): AssetScope
```
Creates a scope that can release every handle it acquires together.

- Throws: GameKitError When the manager has been shut down.

```ts
unregisterScope(scope: IAssetHandleScope): void
```
Stops retaining a disposed scope; removing an unknown scope is harmless.

```ts
isLoaded(key: AssetKey<any>): boolean
```
Tests whether a key has a completed cached record.

```ts
getRefCount(key: AssetKey<any>): int
```
Returns live handles retaining the key, or zero when unloaded.

```ts
getAssetValue<T>(key: AssetKey<T>): T
```
Returns a loaded asset without acquiring another handle.

- Throws: MissingRegistration When the key has no loaded record.

```ts
acquireHandle<T>(key: AssetKey<T>, scope: IAssetHandleScope | null = null): AssetHandle<T>
```
Acquires a retaining handle for an already loaded asset. The returned handle increments the reference count and is released directly or by its scope.

- Throws: GameKitError When the manager is shut down.
- Throws: MissingRegistration When the asset is not loaded.

```ts
releaseHandle(key: AssetKey<any>, handle: any): void
```
Drops one known handle reference and unloads the record when its count reaches zero.

```ts
replaceAsset<T>(key: AssetKey<T>, newAsset: T): void
```
Swaps a loaded value without invalidating handles, then best-effort unloads the old value.

```ts
async acquireOrLoad<T>(key: AssetKey<T>, scope: IAssetHandleScope | null = null, customLoader: any = null): Promise<AssetHandle<T>>
```
Returns a retaining handle, loading the key when no cached record exists. Concurrent requests for the same key await one shared load and each receive its own handle.

- Throws: GameKitError When the manager is shut down.
- Throws: MissingRegistration When no loader can be selected.

```ts
async load<T>(key: AssetKey<T>, options: any = null): Promise<AssetHandle<T>>
```
Acquires or loads one key using optional `{scope, loader}` overrides.

```ts
async loadPlan(plan: AssetLoadPlan, options: any = null): Promise<AssetPlanResult>
```
Loads a validated dependency plan wave by wave and records all outcomes. A failed dependency blocks dependants; `continueOnError` controls later independent work.

```ts
shutdown(): void
```
Stops new asset work, disposes active scopes, and unloads every cached record. In-flight promises are forgotten; do not use the manager after shutdown.

## AssetPlanEntry

```ts
import { AssetPlanEntry } from "gamekit";
class AssetPlanEntry
```

One asset-plan node with dependency identities and load policy.

**Members**

```ts
key: AssetKey<any>
```
Asset identity loaded by this node.

```ts
dependencies: Array<AssetKey<any>>
```
Keys that must succeed first when also present in the plan.

```ts
loader: any
```
Optional loader override; `null` uses key-specific or manager default selection.

```ts
weight: int
```
Relative contribution to aggregate progress.

```ts
retries: int
```
Additional attempts after the initial load, clamped to zero or greater.

```ts
constructor( key: AssetKey<any>, dependencies: Array<AssetKey<any>> = [], loader: any = null, weight: int = 1, retries: int = 0 )
```
Captures policy, coercing non-positive weight to one and negative retries to zero.

## AssetPlanResult

```ts
import { AssetPlanResult } from "gamekit";
class AssetPlanResult
```

Aggregate handles, failures, counts, and cancellation state from one plan run.

**Members**

```ts
isOk: boolean = true
```
Remains `true` only when no entry failed and cancellation did not occur.

```ts
isCancelled: boolean = false
```
Whether cooperative cancellation stopped traversal between entries.

```ts
loadedCount: int = 0
```
Number of handles acquired successfully.

```ts
failedCount: int = 0
```
Number of loader failures plus dependency-blocked entries.

```ts
handles: Array<AssetHandle<any>> = []
```
Successful handles in plan execution order.

```ts
failures: Array<AssetFailure> = []
```
Terminal failures in plan execution order.

```ts
hasHandle(key: AssetKey<any>): boolean
```
Tests successful handle presence by exact key identity.

```ts
getHandle<T>(key: AssetKey<T>): AssetHandle<T> | null
```
Returns the successful handle for a key, or `null`.

```ts
getFailure(key: AssetKey<any>): AssetFailure | null
```
Returns the terminal failure for a key, or `null`.

```ts
getFailureTrace(key: AssetKey<any>): string | null
```
Joins per-attempt trace lines, or returns `null` when the key did not fail.

## AssetScope

```ts
import { AssetScope } from "gamekit";
class AssetScope implements IAssetHandleScope
```

Groups asset handles so a scene, screen, or other owner can release them together.

**Members**

```ts
name: string
```
Optional label used in diagnostics.

```ts
isDisposed: boolean = false
```
Whether this resource has released its owned references.

```ts
constructor(manager: IAssetScopeManager, name: string = "")
```
Creates a scope registered with an asset manager.

```ts
async load<T>(key: AssetKey<T>): Promise<AssetHandle<T>>
```
Loads an asset and attaches the resulting handle to this scope. If disposal wins the asynchronous race, the returned handle is already released.

```ts
acquire<T>(key: AssetKey<T>): AssetHandle<T>
```
Acquires an already loaded asset and records the handle in this scope.

- Throws: GameKitError When the scope has been disposed.

```ts
has(key: AssetKey<any>): boolean
```
Reports whether this live scope retains a handle for the key.

```ts
get<T>(key: AssetKey<T>): T | null
```
Finds the retained value for a key without changing its reference count.

```ts
getRequired<T>(key: AssetKey<T>): T
```
Finds a retained value and treats absence as a configuration error.

- Throws: MissingRegistration When the scope has no live handle for the key.

```ts
getHandle<T>(key: AssetKey<T>): AssetHandle<T> | null
```
Finds this scope's live handle for a key.

```ts
release(key: AssetKey<any>): void
```
Disposes this scope and releases a snapshot of all of its handles. It unregisters itself after release; repeated calls are harmless.

```ts
releaseAll(): void
```
Alias for `releaseAll` for owners that use disposable lifecycle terminology.

```ts
dispose(): void
```
Disposable-lifecycle alias for `releaseAll`.

## Attribute

```ts
import { Attribute } from "gamekit";
class Attribute<T>
```

Lazily computes a value from a base or dependency set, then applies ordered modifiers and a final clamp. Changes notify a listener snapshot only after a successful recalculation.

**Members**

```ts
constructor(baseValue: T, clamp: Function | null = null)
```
Starts dirty with a base value and optional final-value clamp.

```ts
get value(): T
```
Recalculates when dirty and returns the cached effective value.

```ts
get baseValue(): T
```
Unmodified source value; derived attributes retain it but do not read it.

```ts
get dirty(): boolean
```
Whether the effective value requires recalculation.

```ts
get recalculations(): int
```
Number of successful effective-value calculations.

```ts
setBase(value: T): void
```
Replaces a non-derived base, recalculates immediately, and notifies on change.

```ts
addModifier(modifier: AttributeModifier<T>): void
```
Adds a unique modifier, ordered by priority then insertion order, and recalculates.

```ts
removeModifier(id: string): boolean
```
Removes a modifier by id and reports whether recalculation occurred.

```ts
derive(dependencies: Attribute<any>[], calculate: Function): void
```
Replaces base calculation with a dependency snapshot callback and subscribes to dependency changes. Direct and transitive cycles are rejected before existing derivation state changes.

```ts
clearDerived(): void
```
Drops dependency subscriptions and resumes calculation from the retained base value.

```ts
subscribe(listener: Function): AttributeSubscription<T>
```
Appends a `(next, previous)` observer and returns its idempotent lifetime handle.

```ts
inspect(): AttributeInspection<T>
```
Forces refresh and captures counts plus current base/effective values.

```ts
removeSubscription(subscription: AttributeSubscription<T>): void
```
Deactivates an observer handle and removes it from future snapshots.

## AttributeInspection

```ts
import { AttributeInspection } from "gamekit";
class AttributeInspection<T>
```

Point-in-time diagnostic snapshot of an Attribute after refresh.

**Members**

```ts
baseValue: T
```
Retained source value, even when derivation currently replaces it.

```ts
value: T
```
Effective derived, modified, and clamped value.

```ts
modifierCount: int
```
Number of transformations currently attached.

```ts
dependencyCount: int
```
Number of attributes feeding a derived calculation.

```ts
listenerCount: int
```
Number of active change observers.

```ts
recalculations: int
```
Successful calculations since construction.

```ts
dirty: boolean
```
Whether another read would need recalculation at capture time.

```ts
constructor(baseValue: T, value: T, modifierCount: int, dependencyCount: int, listenerCount: int, recalculations: int, dirty: boolean)
```
Captures values and counters without retaining a reference to the Attribute.

## AttributeModifier

```ts
import { AttributeModifier } from "gamekit";
class AttributeModifier<T>
```

Named pure transformation applied to an Attribute at an explicit priority.

**Members**

```ts
id: string
```
Stable identifier for this AttributeModifier.

```ts
order: int
```
Ascending priority; equal priorities retain insertion order.

```ts
apply: Function
```
Callback receiving the preceding effective value and returning the next value.

```ts
constructor(id: string, order: int, apply: Function)
```
Captures a non-empty unique id, priority, and transformation callback.

## AttributeSubscription

```ts
import { AttributeSubscription } from "gamekit";
class AttributeSubscription<T>
```

Idempotent lifetime handle for one Attribute change observer.

**Members**

```ts
active: boolean = true
```
Whether this AttributeSubscription still accepts work.

```ts
constructor(owner: Attribute<T>, entry: AttributeListenerEntry<T>)
```
Binds the handle to its owner and private listener entry.

```ts
dispose(): void
```
Removes the listener from future notifications; repeated calls do nothing.

```ts
matches(entry: AttributeListenerEntry<T>): boolean
```
Tests private listener-entry identity during owner cleanup.

```ts
deactivate(): void
```
Marks the handle inactive and drops its owner reference without re-entry.

## cloneValue

```ts
import { cloneValue } from "gamekit";
function cloneValue(val: any): any
```

Deep-copies arrays, maps, and object properties while preserving primitive values.

## ComponentKey

```ts
import { ComponentKey } from "gamekit";
class ComponentKey<T> extends TypedKey<T>
```

Identifies one component capability or ECS store independently of its label.

**Members**

```ts
constructor(label: string)
```
Allocates a fresh component identity with the label shown in diagnostics.

## Condition

```ts
import { Condition } from "gamekit";
class Condition<TContext>
```

Normalizes boolean, string, or ConditionResult evaluators into composable diagnostic outcomes.

**Members**

```ts
id: string
```
Stable identifier for this Condition.

```ts
description: string
```
Human-readable explanation of this item.

```ts
constructor(id: string, description: string, evaluator: Function)
```
Binds a non-empty diagnostic id and description to a context evaluator.

```ts
evaluate(context: TContext): ConditionResult
```
Converts `true` or empty string to pass, `false` or non-empty string to failure, and preserves explicit results.

```ts
and(other: Condition<TContext>, shortCircuit: boolean = true): Condition<TContext>
```
Builds a two-condition conjunction using a derived composite id.

```ts
or(other: Condition<TContext>, shortCircuit: boolean = true): Condition<TContext>
```
Builds a two-condition disjunction using a derived composite id.

```ts
not(failureReason: string = ""): Condition<TContext>
```
Builds an inverse condition with an optional reason for an unexpected pass.

```ts
static all<T>(conditions: Condition<T>[], shortCircuit: boolean = true, id: string = "all"): Condition<T>
```
Builds a conjunction that either stops at the first failure or aggregates failure reasons.

```ts
static any<T>(conditions: Condition<T>[], shortCircuit: boolean = true, id: string = "any"): Condition<T>
```
Builds a disjunction that can stop at the first pass and reports every failure when none pass.

```ts
static not<T>(condition: Condition<T>, failureReason: string = "", id: string = "not"): Condition<T>
```
Builds a condition that passes only when the wrapped condition fails.

## ConditionResult

```ts
import { ConditionResult } from "gamekit";
class ConditionResult
```

Normalized condition outcome with a primary explanation and optional aggregate reasons.

**Members**

```ts
passed: boolean
```
`true` when evaluation permits the guarded operation.

```ts
conditionId: string
```
Identity of the decisive condition or composite.

```ts
reason: string
```
Primary human-readable outcome explanation.

```ts
reasons: string[]
```
Aggregate failure explanations; defaults to the primary reason when non-empty.

```ts
constructor(passed: boolean, conditionId: string = "", reason: string = "", reasons: string[] = [])
```
Captures an outcome and normalizes its reason list.

```ts
get ok(): boolean
```
Alias for `passed` used by result-oriented call sites.

```ts
static pass(conditionId: string = "", reason: string = ""): ConditionResult
```
Creates a successful outcome with optional identity and explanation.

```ts
static fail(conditionId: string, reason: string, reasons: string[] = []): ConditionResult
```
Creates a failed outcome, defaulting the aggregate list to the primary reason.

## ContextKey

```ts
import { ContextKey } from "gamekit";
class ContextKey<T> extends TypedKey<T>
```

Identifies a typed hierarchical context value without relying on string lookup.

**Members**

```ts
constructor(label: string)
```
Allocates a fresh context identity with the label shown in diagnostics.

## CyclicDefinition

```ts
import { CyclicDefinition } from "gamekit";
class CyclicDefinition extends DefinitionError
```

Reports an inheritance cycle discovered while resolving definitions.

**Members**

```ts
cycle: string[]
```
Ordered ids that form the detected cycle.

```ts
constructor(message: string, cycle: string[] = [])
```
Uses the first cycle id as the inherited definition id when available.

## CyclicDependency

```ts
import { CyclicDependency } from "gamekit";
class CyclicDependency extends GameKitError
```

Reports a directed dependency cycle, such as an asset load-plan loop.

**Members**

```ts
cycle: string[]
```
Ordered labels participating in the detected loop.

```ts
constructor(message: string, cycle: string[] = [])
```
Retains the cycle alongside the human-readable message.

## Definition

```ts
import { Definition } from "gamekit";
class Definition
```

Immutable source definition with copied data and ordered parent ids.

**Members**

```ts
readonly id: string
```
Stable identifier for this Definition.

```ts
readonly inherits: string[]
```
Parent ids merged left to right before this definition's data.

```ts
readonly data: any
```
Deep copy of the registered source data.

```ts
constructor(id: string, data: any, inherits: string[] = [])
```
Validates non-empty ids and copies data plus the inheritance list.

## DefinitionError

```ts
import { DefinitionError } from "gamekit";
class DefinitionError extends GameKitError
```

Adds definition identity and provenance to a registry resolution failure.

**Members**

```ts
definitionId: string
```
Definition id being resolved, or an empty string when no single id applies.

```ts
provenance: string[]
```
Resolution path from the requested definition to the failure point.

```ts
constructor(message: string, definitionId: string = "", provenance: string[] = [])
```
Captures a diagnostic message with optional definition and resolution path context.

## DefinitionRegistry

```ts
import { DefinitionRegistry } from "gamekit";
class DefinitionRegistry
```

Resolves named definitions through ordered multiple inheritance and validator callbacks. Every public resolution returns detached data and reports cycles or missing parents with provenance.

**Members**

```ts
define(id: string, data: any, inherits: string[] = []): Definition
```
Constructs and registers a copied source definition.

```ts
register(def: Definition): Definition
```
Registers one unique Definition by id and returns the same source object.

```ts
has(id: string): boolean
```
Tests exact string-id registration without resolving parents.

```ts
addValidator(validator: Function): void
```
Appends a validator run against each fully merged candidate.

```ts
resolve(id: string): ResolvedDefinition
```
Resolves parents left to right, overlays child data, validates, and returns detached data.

```ts
get(id: string): ResolvedDefinition | null
```
Returns a resolved snapshot, or `null` only when the requested root id is absent.

```ts
getRequired(id: string): ResolvedDefinition
```
Returns a resolved snapshot and throws `MissingRegistration` when the root id is absent.

```ts
instantiate(id: string, factory: Function, context: any = null): any
```
Resolves fresh data and invokes `factory(resolvedDefinition, context)`.

```ts
createPrefab(id: string, factory: Function): Prefab
```
Creates a reusable factory binding after verifying that the root id exists.

## DuplicateRegistration

```ts
import { DuplicateRegistration } from "gamekit";
class DuplicateRegistration extends GameKitError
```

Reports a second registration for an identity that must be unique.

**Members**

```ts
definitionId: string
```
Conflicting definition or registration id, when one is available.

```ts
provenance: string[]
```
Resolution or registration path that exposed the conflict.

```ts
constructor(message: string, definitionId: string = "", provenance: string[] = [])
```
Captures optional identity and provenance context for diagnostics.

## EffectApplication

```ts
import { EffectApplication } from "gamekit";
class EffectApplication<T>
```

Incoming typed effect payload and policy options passed through the application pipeline.

**Members**

```ts
key: EffectKey<T>
```
Effect identity used for collision and lookup.

```ts
payload: T
```
Game-owned behavior or data being attached.

```ts
options: EffectOptions<T>
```
Source, duration, scheduler, and stacking policy for this attempt.

```ts
constructor(key: EffectKey<T>, payload: T, options: EffectOptions<T>)
```
Captures one pre-attachment request for pipeline inspection.

## EffectCollection

```ts
import { EffectCollection } from "gamekit";
class EffectCollection
```

Owns effect handles, applies admission and stacking policy, and mirrors owner lifecycle callbacks. Handles remain insertion ordered and terminal removal cleans timers plus source observation exactly once.

**Members**

```ts
owner: IEffectOwner
```
Entity or game object passed to effect lifecycle callbacks.

```ts
pipeline: MutablePipeline<EffectApplication<any>, any> = ...
```
Pre-admission pipeline that may cancel an application before collision policy.

```ts
constructor(owner: IEffectOwner)
```
Starts an empty collection bound to one lifecycle owner.

```ts
add<T>(key: EffectKey<T>, value: T, options: EffectOptions<T> | null = null): EffectHandle<T> | null
```
Runs admission, resolves same-key collisions, and enters the accepted effect into current owner lifecycle. Returns `null` for pipeline cancellation or policy rejection.

```ts
get<T>(key: EffectKey<T>): EffectHandle<T>[]
```
Returns a new insertion-ordered array of live handles matching exact key identity.

```ts
lifecycleEntries(): EffectHandle<any>[]
```
Returns a detached snapshot used to interleave effects with other owner capabilities.

```ts
contains(effect: EffectHandle<any>): boolean
```
Tests exact handle identity, not key equivalence.

```ts
activate(effect: EffectHandle<any>): void
```
Activates a currently retained handle; foreign or terminal handles are ignored.

```ts
suspend(effect: EffectHandle<any>): void
```
Suspends a currently retained active handle; foreign handles are ignored.

```ts
remove(effect: EffectHandle<any>, reason: EffectRemovalReason = EffectRemovalReason.REMOVED): void
```
Terminally removes a retained handle and emits lifecycle callbacks for the stated reason.

```ts
expire(effect: EffectHandle<any>): void
```
Applies the special expiration boundary without a preceding suspend callback.

```ts
refresh(effect: EffectHandle<any>, duration: float | null): void
```
Replaces a retained effect's non-negative duration and restarts its scheduler timer.

```ts
removeAll(reason: EffectRemovalReason): void
```
Removes a reverse-order snapshot so teardown mirrors capability unwinding.

## EffectHandle

```ts
import { EffectHandle } from "gamekit";
class EffectHandle<T>
```

Stable handle controlling one effect's lifecycle, timer, and source cleanup.

**Members**

```ts
id: int
```
Stable identifier for this EffectHandle.

```ts
key: EffectKey<T>
```
Typed effect identity shared by colliding applications.

```ts
value: T
```
Attached game-owned effect behavior or data.

```ts
source: any | null
```
Optional lifetime owner whose disposal removes this effect.

```ts
duration: float | null
```
Current expiration delay, or `null` for no timer.

```ts
state: EffectState = EffectState.SUSPENDED
```
Suspended, active, removed, or expired lifecycle state.

```ts
order: int
```
Monotonic capability order shared with the owning Entity.

```ts
attached: boolean = false
```
Whether `onAttach` has run at least once.

```ts
constructor(collection: any, id: int, order: int, key: EffectKey<T>, value: T, options: EffectOptions<T>)
```
Captures collection ownership and options; attachment occurs separately.

```ts
get active(): boolean
```
Whether the effect currently participates in active owner behavior.

```ts
get removed(): boolean
```
Whether the effect reached either terminal removed or expired state.

```ts
suspend(): void
```
Requests idempotent suspension through the owning collection.

```ts
activate(): void
```
Requests attachment if needed, then idempotent activation through the collection.

```ts
remove(): void
```
Requests terminal manual removal through the owning collection.

```ts
refresh(duration: float | null = this.duration): void
```
Restarts timed expiration, defaulting to the current duration.

## EffectKey

```ts
import { EffectKey } from "gamekit";
class EffectKey<T> extends TypedKey<T>
```

Identifies an effect kind and its typed payload across an entity's collection.

**Members**

```ts
constructor(label: string)
```
Allocates a fresh effect identity with the label shown in diagnostics.

## EffectOptions

```ts
import { EffectOptions } from "gamekit";
class EffectOptions<T>
```

Optional collision, source-lifetime, and timed-expiration policy for an effect.

**Members**

```ts
policy: Function | null
```
Stacking callback required when the key already has live effects.

```ts
source: any | null
```
Optional object whose disposal removes this effect.

```ts
duration: float | null
```
Non-negative lifetime in seconds of the scheduler's time, or `null` for no timer.

```ts
scheduler: any | null
```
Explicit core `Ticker` (`App.ticker`, `node.ticker`) required whenever duration is present; headless tests may pass a `ClockScheduler`.

```ts
constructor(policy: Function | null = null, source: any | null = null, duration: float | null = null, scheduler: any | null = null)
```
Validates that timed effects have a non-negative duration and scheduler.

## EffectRemovalReason

```ts
import { EffectRemovalReason } from "gamekit";
enum EffectRemovalReason
```

Defines the closed effect removal reason value set. Store and compare these values directly rather than introducing string aliases;

| Member | Meaning |
|---|---|
| `REMOVED = "removed"` | The owner explicitly removed the effect. |
| `REPLACED = "replaced"` | A replacement displaced the effect. |
| `REJECTED = "rejected"` | Stacking rules rejected the effect. |
| `EXPIRED = "expired"` | The effect reached its expiration condition. |
| `SOURCE_DISPOSED = "source-disposed"` | The effect's source owner was disposed. |
| `TARGET_DISPOSED = "target-disposed"` | The effect's target owner was disposed. |

## EffectStacking

```ts
import { EffectStacking } from "gamekit";
class EffectStacking
```

Factory for common collision policies consumed by EffectCollection.

**Members**

```ts
static accumulate(): Function
```
Accepts every incoming effect alongside existing matches.

```ts
static replace(): Function
```
Removes all existing matches before accepting the incoming effect.

```ts
static strongest(compare: Function): Function
```
Rejects incoming payloads not strictly stronger than every existing value; otherwise replaces them.

```ts
static refreshDuration(): Function
```
Keeps the most recently added match and restarts its timer using incoming duration.

## EffectStackingContext

```ts
import { EffectStackingContext } from "gamekit";
class EffectStackingContext<T>
```

Collision-policy view of the incoming application and matching handles in insertion order.

**Members**

```ts
incoming: EffectApplication<T>
```
Application currently seeking admission.

```ts
existing: EffectHandle<T>[]
```
Live handles with the same key, oldest first.

```ts
constructor(incoming: EffectApplication<T>, existing: EffectHandle<T>[])
```
Captures the collision inputs for one synchronous policy decision.

```ts
accept(): EffectStackingResolution<T>
```
Chooses to retain matches and add the incoming effect.

```ts
reject(): EffectStackingResolution<T>
```
Chooses to reject incoming payload with a removal callback.

```ts
replace(): EffectStackingResolution<T>
```
Chooses to remove every match and add the incoming effect.

```ts
refresh(effect: EffectHandle<T>): EffectStackingResolution<T>
```
Chooses one existing handle to retain and retime instead of adding.

## EffectStackingResolution

```ts
import { EffectStackingResolution } from "gamekit";
class EffectStackingResolution<T>
```

Policy decision naming `accept`, `reject`, `replace`, or `refresh` plus an optional retained handle.

**Members**

```ts
action: string
```
Decision string interpreted and validated by EffectCollection.

```ts
retained: EffectHandle<T> | null
```
Existing handle required only for `refresh`.

```ts
constructor(action: string, retained: EffectHandle<T> | null = null)
```
Captures a policy decision; collection application validates action semantics.

## EffectState

```ts
import { EffectState } from "gamekit";
enum EffectState
```

Defines the closed effect state value set. Store and compare these values directly rather than introducing string aliases;

| Member | Meaning |
|---|---|
| `ACTIVE = "active"` | The effect currently applies. |
| `SUSPENDED = "suspended"` | The effect is retained but not currently applied. |
| `EXPIRED = "expired"` | The effect ended because its duration elapsed. |
| `REMOVED = "removed"` | The effect is no longer retained by its collection. |

## Entity

```ts
import { Entity } from "gamekit";
class Entity implements IEffectOwner
```

Owns a game object's hierarchy, local facts, components, and effects. An Entity is detached until attached to an active root; its identity and owned state survive reparenting but not dispose.

**Members**

```ts
parent: Entity | null = null
```
Current hierarchy owner, or `null` for a root or detached entity.

```ts
state: EntityState = EntityState.DETACHED
```
Detached, attached, active, or terminal disposed lifecycle state.

```ts
events: EventScope
```
Local non-bubbling event scope closed before disposal callbacks.

```ts
effects: EffectCollection
```
Effect collection whose lifecycle follows this entity.

```ts
constructor(eventErrorSink: Function | null = null)
```
Creates a detached entity with local events and effects; the optional sink observes listener errors.

```ts
onAttach(): void
```
Override hook called parent-before-child when entering a hierarchy.

```ts
onActivate(): void
```
Override hook called parent-before-child when entering active state.

```ts
onDeactivate(): void
```
Override hook called child-before-parent when leaving active state.

```ts
onDetach(): void
```
Override hook called child-before-parent before hierarchy unlinking.

```ts
onDispose(): void
```
Terminal override hook called child-before-parent during recursive disposal.

```ts
onContextChanged(key: ContextKey<any>): void
```
Override invalidation hook delivered parent-before-child for a changed context key.

```ts
children(): Entity[]
```
Returns a detached snapshot of non-disposed direct children in attachment order.

```ts
ancestors(): Entity[]
```
Returns live ancestors nearest-first up to the hierarchy root.

```ts
descendants(): Entity[]
```
Returns live descendants in parent-before-child preorder.

```ts
addComponent<T>(key: ComponentKey<T>, value: T): void
```
Attaches one game-defined capability under its explicit identity key. The component becomes visible immediately and receives the Entity's current lifecycle; mutation from a component callback throws.

- Throws: Error when the key is already present or lifecycle mutation is re-entrant.

```ts
replaceComponent<T>(key: ComponentKey<T>, value: T): T | null
```
Removes the prior keyed component through lifecycle callbacks, then attaches its replacement. Returns the former value, or `null` when the key was absent.

```ts
removeComponent<T>(key: ComponentKey<T>): T | null
```
Deactivates and detaches a keyed component before returning its value, or `null` when absent.

```ts
getComponent<T>(key: ComponentKey<T>): T | null
```
Looks up a component without turning absence into a programming error. This reads only this Entity's explicit component table and returns `null` after disposal.

```ts
getAncestorComponent<T>(key: ComponentKey<T>): T | null
```
Finds the nearest ancestor value for a key, deliberately excluding local membership.

```ts
getDescendantComponents<T>(key: ComponentKey<T>): T[]
```
Collects matching descendant values in hierarchy preorder, excluding this entity.

```ts
inspectComponents(): any[]
```
Captures key labels, attachment order, and game-owned value references for tooling.

```ts
addEffect<T>(key: EffectKey<T>, value: T, options: EffectOptions<T> | null = null): EffectHandle<T> | null
```
Applies an effect through admission/stacking and current entity lifecycle.

```ts
getEffects<T>(key: EffectKey<T>): EffectHandle<T>[]
```
Returns a detached insertion-ordered array of live handles matching exact key identity.

```ts
attach(parent: Entity): void
```
Links a detached subtree under a live parent and activates it when that parent is active.

```ts
activate(): void
```
Activates a root or child of an active parent in parent-before-child order.

```ts
deactivate(): void
```
Deactivates an active root subtree in child-before-parent order.

```ts
detach(): void
```
Deactivates and detaches the subtree child-before-parent while preserving all owned state.

```ts
reparent(newParent: Entity): void
```
Transfers synchronously through detach and attach, then activates under an active new parent.

```ts
dispose(): void
```
Idempotently closes events and disposes descendants, capabilities, and this entity child-first.

```ts
disposeDeferred(queue: any): void
```
Enqueues terminal disposal while leaving the entity live until queue flush.

```ts
setContext<T>(key: ContextKey<T>, value: T): void
```
Adds or replaces a local context value, then invalidates this subtree parent-first.

```ts
removeContext<T>(key: ContextKey<T>): boolean
```
Removes a local context value and invalidates descendants only when membership changed.

```ts
getContext<T>(key: ContextKey<T>): T | null
```
Resolves the nearest local-or-ancestor context value, or `null` at an absent boundary.

## EntityAllocator

```ts
import { EntityAllocator } from "gamekit";
class EntityAllocator
```

Issues compact generational entity ids and recycles released slots without reviving stale handles.

**Members**

```ts
create(): EntityId
```
Allocates a live id, preferring the most recently released reusable slot.

```ts
seedGeneration(index: int, generation: int): void
```
Sets a slot generation for boundary tests and persisted-id hardening; inactive seeded slots become reusable.

```ts
isAlive(id: EntityId): boolean
```
Returns `true` only when the index exists, is live, and has the exact generation.

```ts
resolve(id: EntityId): EntityId | null
```
Returns the supplied id when live, or `null` for unknown and stale identities.

```ts
requireAlive(id: EntityId): void
```
Enforces liveness at mutation boundaries.

```ts
destroy(id: EntityId): boolean
```
Invalidates a live id and increments its generation before recycling the slot. A slot at `EntityId.MAX_GENERATION` is retired permanently.

## EntityId

```ts
import { EntityId } from "gamekit";
class EntityId
```

Names one lifetime of an allocator slot using an index-and-generation pair.

**Members**

```ts
static const MAX_GENERATION: int = 2147483647
```
Highest generation value before allocator slots retire instead of wrapping.

```ts
index: int
```
Reusable allocator slot index; it is not unique without `generation`.

```ts
generation: int
```
Slot generation that prevents a stale id from resolving after reuse.

```ts
constructor(index: int, generation: int)
```
Captures an allocator-issued slot and generation without validating liveness.

```ts
equals(other: EntityId): boolean
```
Requires both slot and generation to match.

```ts
toString(): string
```
Formats the identity as `entity index:generation` for diagnostics.

## EntityState

```ts
import { EntityState } from "gamekit";
enum EntityState
```

Defines the closed entity state value set. Store and compare these values directly rather than introducing string aliases;

| Member | Meaning |
|---|---|
| `DETACHED = "Detached"` | The entity has no parent owner. |
| `ATTACHED = "Attached"` | The entity belongs to a parent but is inactive. |
| `ACTIVE = "Active"` | The entity is attached and receiving active lifecycle work. |
| `DISPOSED = "Disposed"` | The entity has completed teardown. |

## EntityTeardownQueue

```ts
import { EntityTeardownQueue } from "gamekit";
class EntityTeardownQueue
```

Deduplicates deferred Entity disposal until an explicit FIFO flush boundary.

**Members**

```ts
defer(entity: Entity): void
```
Enqueues a live entity once by object identity; disposed entities are ignored.

```ts
flush(): void
```
Disposes the current snapshot in issue order; callback additions wait for the next flush.

## EventKey

```ts
import { EventKey } from "gamekit";
class EventKey<T> extends TypedKey<T>
```

Identifies an event channel and statically carries the emitted payload type.

**Members**

```ts
constructor(label: string)
```
Allocates a fresh event identity with the label shown in diagnostics.

## EventScope

```ts
import { EventScope } from "gamekit";
class EventScope
```

Owns typed local event listeners and delivers snapshot notifications in subscription order. Listener failures are isolated and optionally reported without aborting later listeners.

**Members**

```ts
constructor(errorSink: Function | null = null)
```
Starts an open local scope with an optional `(error, eventKey)` reporting sink.

```ts
get subscriptionCount(): int
```
Number of active listener handles owned by this scope.

```ts
subscribe<T>(key: EventKey<T>, listener: Function): EventSubscription
```
Appends a listener for exact key identity and returns its idempotent cancellation handle. Subscribing after close returns an already inactive handle.

```ts
emit<T>(key: EventKey<T>, event: T): void
```
Delivers a listener snapshot in subscription order; changes affect only later emissions. Closing during delivery stops remaining callbacks, while listener errors go to the sink.

```ts
forward<T>(target: EventScope, key: EventKey<T>, event: T): void
```
Explicitly emits on another scope without introducing hierarchy or bubbling.

```ts
close(): void
```
Idempotently prevents future delivery and deactivates every owned subscription.

```ts
get isClosed(): boolean
```
Whether the scope has permanently stopped accepting listeners and events.

```ts
removeSubscription(subscription: EventSubscription): void
```
Deactivates and removes an owned handle; repeated or foreign removal is harmless.

## EventSubscription

```ts
import { EventSubscription } from "gamekit";
class EventSubscription
```

Idempotent handle controlling one listener's lifetime in an EventScope.

**Members**

```ts
active: boolean = true
```
Whether this EventSubscription still accepts work.

```ts
constructor(scope: EventScope, entry: ListenerEntry)
```
Binds the handle to its owning scope and private listener entry.

```ts
dispose(): void
```
Stops future delivery and detaches from the scope; repeated calls do nothing.

```ts
matches(entry: ListenerEntry): boolean
```
Tests the private listener-entry identity during owner cleanup.

```ts
deactivate(): void
```
Marks the handle inactive and drops its owner reference without re-entering the owner.

## FakeAssetLoader

```ts
import { FakeAssetLoader } from "gamekit";
class FakeAssetLoader
```

Deterministic in-memory loader with configurable failures, delays, and call-order inspection.

**Members**

```ts
loadOrder: Array<AssetKey<any>> = []
```
Asset keys requested in chronological order, including failed attempts.

```ts
loadOrderLabels: Array<string> = []
```
Labels captured at each request for concise assertions.

```ts
unloadOrder: Array<AssetKey<any>> = []
```
Keys unloaded in chronological order.

```ts
set<T>(key: AssetKey<T>, value: T): void
```
Associates a value with exact key identity for future successful loads.

```ts
setFailures(key: AssetKey<any>, errors: string[]): void
```
Replaces the queue of error messages thrown by successive loads.

```ts
setFailure(key: AssetKey<any>, error: string): void
```
Configures one failing attempt for a key.

```ts
setDelay(key: AssetKey<any>, delayMs: int): void
```
Sets an asynchronous delay in milliseconds before outcome selection.

```ts
getLoadCount(key: AssetKey<any>): int
```
Returns attempted loads for exact key identity.

```ts
getUnloadCount(key: AssetKey<any>): int
```
Returns unload calls for exact key identity.

```ts
async load(key: AssetKey<any>): Promise<any>
```
Records the attempt, waits its delay, consumes one queued failure, then returns configured or default mock data.

```ts
unload(key: AssetKey<any>, asset: any): void
```
Records unload and invokes `dispose` on the asset.

```ts
reset(): void
```
Clears configured data, failures, delays, counters, and order traces.

## GameKitError

```ts
import { GameKitError } from "gamekit";
class GameKitError extends Error
```

Base error type for GameKit style guide and lifecycle violations.

**Members**

```ts
constructor(message: string)
```
Preserves a consumer-facing explanation through the standard Error surface.

## Gauge

```ts
import { Gauge } from "gamekit";
class Gauge
```

Neutral rate-filled value for cooldowns, charge bars and any meter that fills with time. Time arrives through `advance`, never read from a clock, so a crossing lands on the same tick every run.

**Members**

```ts
value: float
```
Current fill, always within 0 and `capacity`.

```ts
capacity: float
```
Fill at which the gauge is full.

```ts
rate: float
```
Fill added per unit of time given to `advance`.

```ts
paused: boolean = false
```
While true, `advance` leaves the value unchanged.

```ts
constructor(capacity: float, rate: float, start: float = 0.0)
```
Starts at `start` (clamped into range, default empty).

- Throws: InvalidArgument when capacity is not above zero or rate is negative.

```ts
advance(dt: float): boolean
```
Adds `rate * dt`, clamped to capacity. Does nothing while paused.

- `dt`: Time passed, not negative.
- Returns: true only on the call that takes the gauge from below capacity to full.
- Throws: InvalidArgument when dt is negative.

```ts
consume(amount: float): void
```
Removes `amount`, flooring at zero.

- Throws: InvalidArgument when amount is negative.

```ts
fill(): void
```
Sets the value to capacity without reporting a crossing.

## InteractionContext

```ts
import { InteractionContext } from "gamekit";
class InteractionContext<TActor, TTarget, TEnv>
```

Typed actor, target, and environment tuple shared across interaction discovery.

**Members**

```ts
actor: TActor
```
Game object attempting the interaction.

```ts
target: TTarget
```
Game object being inspected or acted upon.

```ts
environment: TEnv
```
Optional world or presentation context interpreted by providers.

```ts
constructor(actor: TActor, target: TTarget, environment: TEnv = null)
```
Captures game-owned references without copying them.

## InteractionDefinition

```ts
import { InteractionDefinition } from "gamekit";
class InteractionDefinition<TMetadata>
```

Builds one executable offer from context, optional availability logic, and metadata.

**Members**

```ts
id: string
```
Stable identifier for this InteractionDefinition.

```ts
action: Action<any, any>
```
Action executed if the resulting offer is enabled.

```ts
requestFactory: Function
```
Callback converting discovery context into an ActionRequest.

```ts
condition: Condition<any> | null
```
Optional availability test evaluated during offer creation.

```ts
metadataFactory: Function | null
```
Optional `(context, enabled, conditionResult)` presentation-data callback.

```ts
constructor( id: string, action: Action<any, any>, requestFactory: Function, condition: Condition<any> | null = null, metadataFactory: Function | null = null )
```
Captures a non-empty offer id and its request, action, condition, and metadata factories.

```ts
createOffer(context: InteractionContext<any, any, any>): InteractionOffer<TMetadata>
```
Evaluates availability once and captures the request plus metadata in a new offer.

## InteractionOffer

```ts
import { InteractionOffer } from "gamekit";
class InteractionOffer<TMetadata>
```

Point-in-time executable interaction choice produced during discovery.

**Members**

```ts
id: string
```
Stable identifier for this InteractionOffer.

```ts
action: Action<any, any>
```
Action invoked when this offer executes while enabled.

```ts
request: ActionRequest<any>
```
Prebuilt invocation captured during discovery.

```ts
enabled: boolean
```
Whether this behavior is currently enabled.

```ts
conditionResult: ConditionResult | null
```
Availability explanation, or `null` when no condition was configured.

```ts
metadata: TMetadata
```
Game-defined display or ranking data captured during discovery.

```ts
constructor( id: string, action: Action<any, any>, request: ActionRequest<any>, enabled: boolean = true, conditionResult: ConditionResult | null = null, metadata: TMetadata = null )
```
Captures a non-empty id and the discovery-time execution state.

```ts
execute(targetScope: EventScope | null = null): ActionResult<any>
```
Returns denial without invoking the action when disabled; otherwise executes the captured request.

## InteractionProvider

```ts
import { InteractionProvider } from "gamekit";
class InteractionProvider<TActor, TTarget, TEnv>
```

Named discovery callback that produces zero or more offers for one context.

**Members**

```ts
id: string
```
Stable identifier for this InteractionProvider.

```ts
constructor(id: string, discoverFn: Function)
```
Binds a non-empty provider id to a discovery callback.

```ts
discover(context: InteractionContext<TActor, TTarget, TEnv>): InteractionOffer<any>[]
```
Normalizes a null callback result to an empty offer list.

```ts
static fromDefinition(definition: InteractionDefinition<any>): InteractionProvider<any, any, any>
```
Wraps a single definition as a provider that always returns one captured offer.

## InteractionRegistry

```ts
import { InteractionRegistry } from "gamekit";
class InteractionRegistry
```

Aggregates providers in registration order without imposing ranking or deduplication.

**Members**

```ts
register(provider: InteractionProvider<any, any, any>): void
```
Appends a provider; duplicate ids remain independently discoverable.

```ts
unregister(id: string): boolean
```
Removes the first provider with the id and reports whether one existed.

```ts
discover(actor: any, target: any, environment: any = null): InteractionOffer<any>[]
```
Builds one shared context and concatenates provider offers in stable order.

## InvalidArgument

```ts
import { InvalidArgument } from "gamekit";
class InvalidArgument extends GameKitError
```

Reports a public API argument that violates an immediate precondition.

**Members**

```ts
constructor(message: string)
```
Captures the failed precondition in the inherited error message.

## InvalidDefinition

```ts
import { InvalidDefinition } from "gamekit";
class InvalidDefinition extends DefinitionError
```

Reports definition data that cannot be validated or resolved.

**Members**

```ts
reason: string
```
Machine-comparable validation reason, separate from the display message.

```ts
constructor(message: string, definitionId: string = "", provenance: string[] = [], reason: string = "")
```
Captures definition identity, provenance, and a concise validation reason.

## ISpatialIndex

```ts
import { ISpatialIndex } from "gamekit";
interface ISpatialIndex<T>
```

Defines deterministic identity-based insertion and broad-phase 2D spatial queries.

**Members**

```ts
upsert(value: T, bounds: Rect): void
```
Inserts a value or replaces its copied bounds when the same object identity exists.

```ts
remove(value: T): boolean
```
Removes exact object identity and reports whether membership changed.

```ts
point(point: Vec2): T[]
```
Returns values whose half-open bounds contain a point (left/top inclusive, right/bottom exclusive).

```ts
area(bounds: Rect): T[]
```
Returns values whose bounds overlap an area (touching edges do not overlap).

```ts
nearest(point: Vec2, maxDistance?: float): T | null
```
Finds the first nearest bounds, optionally limited by a world-unit radius.

```ts
swept(bounds: Rect, delta: Vec2): T[]
```
Broad-phases against the union of starting and translated bounds.

```ts
readonly size: int
```
Number of distinct value identities currently indexed.

## KeyedRegistry

```ts
import { KeyedRegistry } from "gamekit";
class KeyedRegistry
```

Associates heterogeneous values with exact typed-key identities in registration order.

**Members**

```ts
register<T>(key: TypedKey<T>, value: T): void
```
Retains a value under a key that must not already be present.

```ts
get<T>(key: TypedKey<T>): T | null
```
Reads by key identity, returning `null` when no registration exists.

```ts
getRequired<T>(key: TypedKey<T>): T
```
Reads by key identity and treats absence as a programming error.

## LinearSpatialIndex

```ts
import { LinearSpatialIndex } from "gamekit";
class LinearSpatialIndex<T> implements ISpatialIndex<T>
```

Simple insertion-ordered spatial index that linearly scans copied bounds.

**Members**

```ts
upsert(value: T, bounds: Rect): void
```
Inserts by object identity or replaces that value's copied bounds in place.

```ts
remove(value: T): boolean
```
Removes exact object identity and returns whether an entry existed.

```ts
point(point: Vec2): T[]
```
Collects containing entries in insertion order. Uses half-open bounds semantics: left/top edges are inclusive, right/bottom edges are exclusive.

```ts
area(bounds: Rect): T[]
```
Collects overlapping entries in insertion order. Touching edges do not overlap.

```ts
nearest(point: Vec2, maxDistance: float = -1.0): T | null
```
Finds the first entry at minimum squared distance from a point to its bounds. A radius of `-1` means unlimited; other negative values throw.

```ts
swept(bounds: Rect, delta: Vec2): T[]
```
Broad-phases the union of starting and translated bounds, not the exact swept shape.

```ts
get size(): int
```
Number of distinct value identities currently indexed.

## mergeData

```ts
import { mergeData } from "gamekit";
function mergeData(base: any, override: any): any
```

Recursively overlays plain objects and maps, while other values replace the base. The returned structure does not share nested containers with either input.

## MissingRegistration

```ts
import { MissingRegistration } from "gamekit";
class MissingRegistration extends GameKitError
```

Reports a required typed-key, component, or definition registration that is absent.

**Members**

```ts
missingId: string
```
Missing definition or registration identity, when known.

```ts
provenance: string[]
```
Lookup path that led to the absent registration.

```ts
constructor(message: string, missingId: string = "", provenance: string[] = [])
```
Captures optional missing-id and lookup-path context for diagnostics.

## MutablePipeline

```ts
import { MutablePipeline } from "gamekit";
class MutablePipeline<I, O>
```

Runs mutable processing stages over one shared context snapshot in insertion order.

**Members**

```ts
add(stage: Function): PipelineSubscription<I, O>
```
Appends a stage and returns an idempotent handle that can remove it.

```ts
run(input: I): PipelineResult<O>
```
Runs the entry snapshot until exhausted or cancelled, then captures the optional output.

```ts
dispose(): void
```
Removes all stages and deactivates their handles; repeated calls are harmless.

```ts
removeSubscription(subscription: PipelineSubscription<I, O>): void
```
Deactivates and removes one stage; an in-progress run keeps its entry snapshot.

## PipelineContext

```ts
import { PipelineContext } from "gamekit";
class PipelineContext<I, O>
```

Mutable per-run input, cancellation flag, and optional output shared by pipeline stages.

**Members**

```ts
input: I
```
Original input reference supplied to `MutablePipeline.run`.

```ts
cancelled: boolean = false
```
Set once a stage requests that later stages be skipped.

```ts
constructor(input: I)
```
Starts an uncancelled run with no produced output.

```ts
cancel(): void
```
Prevents later stages in the current snapshot from running.

```ts
produce(result: O): void
```
Replaces the output; the last stage to produce wins.

```ts
get result(): O | null
```
Latest produced output, or `null` when no stage produced one.

## PipelineResult

```ts
import { PipelineResult } from "gamekit";
class PipelineResult<O>
```

Immutable-by-convention snapshot of a completed pipeline's cancellation and output state.

**Members**

```ts
cancelled: boolean
```
Whether a stage stopped traversal before the snapshot ended.

```ts
result: O | null
```
Last produced output, or `null` when no stage produced one.

```ts
constructor(cancelled: boolean, result: O | null)
```
Captures terminal context values after pipeline traversal.

## PipelineSubscription

```ts
import { PipelineSubscription } from "gamekit";
class PipelineSubscription<I, O>
```

Idempotent lifetime handle for one stage in a MutablePipeline.

**Members**

```ts
active: boolean = true
```
Whether this PipelineSubscription still accepts work.

```ts
constructor(pipeline: MutablePipeline<I, O>, entry: PipelineStageEntry)
```
Binds the handle to its owner and private stage entry.

```ts
dispose(): void
```
Removes the stage from future runs; repeated calls do nothing.

```ts
matches(entry: PipelineStageEntry): boolean
```
Tests private stage-entry identity during owner cleanup.

```ts
deactivate(): void
```
Marks the handle inactive and drops its owner reference without re-entry.

## Prefab

```ts
import { Prefab } from "gamekit";
class Prefab
```

Reusable factory binding for one definition id in a specific registry.

**Members**

```ts
readonly definitionId: string
```
Registered definition resolved for every instantiation.

```ts
constructor(registry: any, definitionId: string, factory: Function)
```
Binds a non-null registry and factory to a non-empty definition id.

```ts
instantiate(context: any = null): any
```
Resolves fresh data and calls the factory as `(resolvedDefinition, context)`.

## ResolvedDefinition

```ts
import { ResolvedDefinition } from "gamekit";
class ResolvedDefinition
```

Fully merged definition data plus the ordered ids that contributed to it.

**Members**

```ts
readonly id: string
```
Stable identifier for this ResolvedDefinition.

```ts
readonly data: any
```
Merged data snapshot returned independently to each resolver caller.

```ts
readonly provenance: string[]
```
Unique parent-first contribution order ending with `id`.

```ts
constructor(id: string, data: any, provenance: string[])
```
Captures a completed resolution result.

## StaleHandle

```ts
import { StaleHandle } from "gamekit";
class StaleHandle extends GameKitError
```

Reports mutation through an entity or effect handle whose lifetime has ended.

**Members**

```ts
constructor(message: string)
```
Captures which retired identity was used in the inherited message.

## StateMachine

```ts
import { StateMachine } from "gamekit";
class StateMachine<TOwner>
```

Runs explicit named-state callbacks with guarded, FIFO transitions and optional clock scheduling. Transitions requested from callbacks queue behind the current callback and obey a per-drain work cap.

**Members**

```ts
constructor(owner: TOwner, clock: any | null = null, transitionWorkCap: int = 64)
```
Binds an owner, optional scheduler, and positive transition-chain safety cap.

```ts
get stateName(): string | null
```
Current state name, or `null` before start and after disposal.

```ts
get processing(): boolean
```
Whether an enter, exit, update, or transition drain is active.

```ts
get disposed(): boolean
```
Whether teardown has permanently disabled the machine.

```ts
addState(state: StateMachineState<TOwner>): void
```
Registers a uniquely named state before the machine starts.

```ts
permit(source: string, target: string, guard: Function | null = null): void
```
Declares one directed transition with an optional `(owner, context)` guard.

```ts
start(name: string, context: any = null): void
```
Enters the initial state, then drains transitions queued by its callback.

```ts
transition(target: string, context: any = null): boolean
```
Evaluates the declared guard and queues a permitted transition. Returns `false` only when the guard rejects it; callback requests return before the queue drains.

```ts
update(delta: float): void
```
Invokes the current state's `(owner, deltaSeconds)` callback and drains queued transitions.

```ts
transitionAfter(delay: float, target: string, context: any = null): any
```
Schedules a transition on the injected clock and returns its cancellable work handle.

```ts
dispose(context: any = null): void
```
Idempotently cancels scheduled work, clears queued transitions, and exits the current state.

```ts
inspect(): StateMachineInspection
```
Captures current state, queue, transition, processing, disposal, and timer counts.

## StateMachineInspection

```ts
import { StateMachineInspection } from "gamekit";
class StateMachineInspection
```

Point-in-time diagnostic counters and lifecycle flags for a StateMachine.

**Members**

```ts
stateName: string | null
```
Current state name, or `null` when not started or disposed.

```ts
queuedTransitions: int
```
FIFO requests waiting behind current callback work.

```ts
transitionCount: int
```
Successful initial entry and state changes completed so far.

```ts
processing: boolean
```
Whether callback or transition work was active at capture time.

```ts
disposed: boolean
```
Whether the machine had permanently completed teardown.

```ts
scheduledTransitions: int
```
Timer handles retained for cancellation on dispose.

```ts
constructor(stateName: string | null, queuedTransitions: int, transitionCount: int, processing: boolean, disposed: boolean, scheduledTransitions: int)
```
Captures scalar state without retaining the inspected machine.

## StateMachineState

```ts
import { StateMachineState } from "gamekit";
class StateMachineState<TOwner>
```

Named state with optional owner callbacks for entry, exit, and fixed updates.

**Members**

```ts
name: string
```
Optional label used in diagnostics.

```ts
enter: Function | null
```
Optional `(owner, context)` callback invoked after becoming current.

```ts
exit: Function | null
```
Optional `(owner, context)` callback invoked before leaving current state.

```ts
update: Function | null
```
Optional `(owner, deltaSeconds)` callback invoked by machine updates.

```ts
constructor(name: string, callbacks: any = {})
```
Captures a non-empty name and the recognized callbacks from an options object.

## Transform2D

```ts
import { Transform2D } from "gamekit";
class Transform2D
```

Mutable 2D position, rotation, and scale value with no scene-graph ownership.

**Members**

```ts
position: Vec2
```
Translation in world units.

```ts
rotation: float
```
Clockwise rotation in radians.

```ts
scale: Vec2
```
Independent x/y scale multipliers.

```ts
constructor(position: Vec2 = Vec2{}, rotation: float = 0.0, scale: Vec2 = Vec2{ x: 1.0, y: 1.0 })
```
Retains the supplied mutable vectors and rotation value.

```ts
copy(): Transform2D
```
Deep-copies position and scale so later vector edits are independent.

## TypedKey

```ts
import { TypedKey } from "gamekit";
class TypedKey<T>
```

Provides a process-unique, type-carrying identity for registries; labels are diagnostic only.

**Members**

```ts
label: string
```
Human-readable name shown in errors and inspection output.

```ts
constructor(kind: string, label: string)
```
Allocates a fresh identity token for a non-empty diagnostic label.

```ts
equals(other: TypedKey<any>): boolean
```
Compares identity tokens, so separately constructed keys never alias by label.

```ts
getToken(): int
```
Exposes the process-local token used for equality and deterministic diagnostics.

```ts
describe(): string
```
Formats the key kind, label, and unique token for error messages.

## WeightedPick

```ts
import { WeightedPick } from "gamekit";
class WeightedPick<T>
```

Weighted choice over an injected `Random`, the only source of chance, so a seed gives a fixed sequence. Entries with weight 0 are never chosen. `fork(name)` derives an independent stream from the original seed, so several tables stay reproducible whatever order they are created in.

**Members**

```ts
constructor(random: Random)
```
Uses `random` for every draw; the table starts empty.

```ts
get count(): int
```
Number of entries, including zero-weight ones.

```ts
add(item: T, weight: float): void
```
Appends an entry. Higher weight is proportionally more likely; 0 is never chosen.

- Throws: InvalidArgument when weight is negative or not a number.

```ts
pick(): T
```
Draws one entry.

- Throws: InvalidArgument when the table has no entry with a weight above zero.

```ts
fork(name: string): WeightedPick<T>
```
Copies the entries onto a table that draws from `random.fork(name)`; later `add` calls on either table do not affect the other.

---

URL: https://thicketscript.com/gamekit/reference/ecs

# ecs family

The World, component stores, queries, phase schedules and the world ticker.

Every symbol on this page is exported from the package root: `import { Name } from "gamekit";`

10 symbols.

| Symbol | Summary |
|---|---|
| [`createConventionalSchedule`](#createconventionalschedule) | *function*. Creates the opt-in `input -> simulate -> resolve -> present -> flush` phase chain. |
| [`DenseStore`](#densestore) | *class*. Stores one component value per live generational entity id. |
| [`DenseStoreFactory`](#densestorefactory) | *class*. Creates GameKit's default dense component stores. |
| [`IComponentStore`](#icomponentstore) | *interface*. Defines the indexed membership operations required by World and Query. |
| [`IComponentStoreFactory`](#icomponentstorefactory) | *interface*. Creates game-selected component stores for a World. |
| [`PhaseSchedule`](#phaseschedule) | *class*. Orders named simulation phases by explicit dependencies and preserves system registration order within each phase. |
| [`Query`](#query) | *class*. Visits the live intersection of World ownership and one component store in stable entity-id order. |
| [`Query2`](#query2) | *class*. Visits entities present in two component stores, choosing the smaller store as the candidate set. |
| [`World`](#world) | *class*. Owns one simulation domain's entities, component stores, and deferred structural work. |
| [`WorldTicker`](#worldticker) | *class*. Steps a `World` through a `PhaseSchedule` once per tick of a node's `onTick` hook. |

## createConventionalSchedule

```ts
import { createConventionalSchedule } from "gamekit";
function createConventionalSchedule(): PhaseSchedule
```

Creates the opt-in `input -> simulate -> resolve -> present -> flush` phase chain.

- Returns: A mutable schedule that flushes the World after every phase succeeds.

## DenseStore

```ts
import { DenseStore } from "gamekit";
class DenseStore<T> implements IComponentStore<T>
```

Stores one component value per live generational entity id. Removal may move the final dense entry, while snapshots remain ordered by id rather than storage position.

**Members**

```ts
constructor(allocator: EntityAllocator)
```
Binds membership checks to the allocator that issued the entity ids.

- `allocator`: Source of generation and liveness checks for every access.

```ts
register(id: EntityId, value: T): void
```
Adds a value for a live id, evicting only a stale occupant of a recycled index.

- `id`: Exact index-and-generation identity receiving the component.
- `value`: Component reference retained until removal or entity release.
- Throws: DuplicateRegistration when the same live id already has a value.
- Throws: StaleHandle when `id` is no longer live in the allocator.

```ts
get(id: EntityId): T | null
```
Reads exact live membership without treating absence or a stale generation as an error.

- `id`: Index-and-generation identity to test.
- Returns: The registered value, or `null` when the id is stale or absent.

```ts
getRequired(id: EntityId): T
```
Reads a component when both the identity and its membership must exist.

- `id`: Exact live identity to read.
- Returns: The value registered for `id`.
- Throws: StaleHandle when the allocator has retired `id`.
- Throws: MissingRegistration when the live id has no component here.

```ts
remove(id: EntityId): T | null
```
Removes exact membership using swap compaction without changing query order.

- `id`: Index-and-generation identity to remove.
- Returns: The former value, or `null` when no exact membership exists.

```ts
has(id: EntityId): boolean
```
Tests exact membership independently of whether `T` itself permits null-like values.

- `id`: Identity whose current generation must match.
- Returns: `true` only for a live id registered in this store.

```ts
snapshotIds(): EntityId[]
```
Captures current members in ascending index then generation order.

- Returns: A detached id array unaffected by later registrations or compaction.

```ts
get size(): int
```
Number of exact current memberships.

## DenseStoreFactory

```ts
import { DenseStoreFactory } from "gamekit";
class DenseStoreFactory implements IComponentStoreFactory
```

Creates GameKit's default dense component stores. Usage: World constructs this factory when no replacement is supplied.

**Members**

```ts
create(allocator: EntityAllocator, key: ComponentKey<any>): IComponentStore<any>
```
Creates a dense store sharing the World's identity allocator.

## IComponentStore

```ts
import { IComponentStore } from "gamekit";
interface IComponentStore<T>
```

Defines the indexed membership operations required by World and Query. Usage: implement this interface when dense storage is unsuitable for a game.

**Members**

```ts
register(id: EntityId, value: T): void
```
Registers one live entity identity and value.

```ts
get(id: EntityId): T | null
```
Returns a current value or null for absence.

```ts
getRequired(id: EntityId): T
```
Returns a current value and throws for absent membership.

```ts
remove(id: EntityId): T | null
```
Removes exact current membership and returns its prior value.

```ts
has(id: EntityId): boolean
```
Reports exact current membership independently of nullable values.

```ts
snapshotIds(): EntityId[]
```
Returns an independent candidate snapshot for deterministic query ordering.

```ts
readonly size: int
```
Reports the number of current registrations.

## IComponentStoreFactory

```ts
import { IComponentStoreFactory } from "gamekit";
interface IComponentStoreFactory
```

Creates game-selected component stores for a World. Usage: pass an implementation to the World constructor before registering stores.

**Members**

```ts
create(allocator: EntityAllocator, key: ComponentKey<any>): IComponentStore<any>
```
Creates one store for the supplied allocator and typed key.

## PhaseSchedule

```ts
import { PhaseSchedule } from "gamekit";
class PhaseSchedule
```

Orders named simulation phases by explicit dependencies and preserves system registration order within each phase. A phase may define the command-buffer flush boundary; the schedule never invents phases or systems.

**Members**

```ts
addPhase(name: string, after: string[] = [], flushAfter: boolean = false): void
```
Declares a phase and the phase names that must precede it.

- `name`: Non-empty identity unique within this schedule.
- `after`: Dependency names resolved when `run` begins; declaration order breaks unrelated ties.
- `flushAfter`: Whether to flush the World after every system in this phase succeeds.
- Throws: Error for an empty or duplicate name, or mutation during a run.

```ts
addSystem(phaseName: string, work: Function): void
```
Appends a system to a declared phase.

- `phaseName`: Existing phase that owns the callback order.
- `work`: Callback receiving `(world, deltaSeconds, tickNumber)`.
- Throws: Error when the phase is unknown or the schedule is running.

```ts
run(world: World, delta: float, tick: int): void
```
Resolves dependencies, then invokes systems phase by phase under the World's structural guard. A thrown system aborts remaining work and prevents that phase's automatic flush.

- `world`: Simulation domain passed to every system.
- `delta`: Fixed-step duration in seconds.
- `tick`: Monotonic simulation tick supplied unchanged to callbacks.
- Throws: Error for recursion, dependency cycles, missing dependencies, or a system failure.

## Query

```ts
import { Query } from "gamekit";
class Query<T>
```

Visits the live intersection of World ownership and one component store in stable entity-id order.

**Members**

```ts
constructor(world: any, key: ComponentKey<T>)
```
Captures the World and component identity; membership is snapshotted later by `each`.

- `world`: World that owns entity resolution and query guards.
- `key`: Registered component store to traverse.

```ts
each(visitor: Function): void
```
Visits a membership snapshot in ascending entity-id order while direct structural mutation is forbidden. Deferred commands remain invisible until a later explicit `World.flush`.

- `visitor`: Callback receiving `(entity, component)` for each still-live member.
- Throws: MissingRegistration when the component store was not registered.

## Query2

```ts
import { Query2 } from "gamekit";
class Query2<A, B>
```

Visits entities present in two component stores, choosing the smaller store as the candidate set.

**Members**

```ts
constructor(world: any, first: ComponentKey<A>, second: ComponentKey<B>)
```
Captures the World and two component identities; membership is snapshotted by `each`.

- `world`: World that owns entity resolution and query guards.
- `first`: First registered component store and first callback value.
- `second`: Second registered component store and second callback value.

```ts
each(visitor: Function): void
```
Visits the live intersection in ascending entity-id order under the World's query guard.

- `visitor`: Callback receiving `(entity, firstValue, secondValue)` for every exact match.
- Throws: MissingRegistration when either component store was not registered.

## World

```ts
import { World } from "gamekit";
class World implements IEntityWorldOwner
```

Owns one simulation domain's entities, component stores, and deferred structural work. Game code retains the World and advances its explicit phases; it has no import-time registration.

**Members**

```ts
constructor(storeFactory: IComponentStoreFactory = new DenseStoreFactory())
```
Starts an open simulation domain with no entities or component stores.

- `storeFactory`: Factory invoked once for each key registered with the World.

```ts
createEntity(): Entity
```
Creates and adopts an active root Entity in this World. Use this helper when the World should construct the object. Use `adoptEntity` when game code constructs an Entity or subtype first. The returned Entity is immediately World-owned and gets a fresh generational identity.

- Returns: A new active root owned by this World.
- Throws: Error when the World is closed or structural work is currently deferred.

```ts
adoptEntity(entity: Entity): EntityId
```
Adopts a detached Entity into this World and activates it as a root. This is the ownership primitive. Use it when game code constructs an Entity or subtype first; use `createEntity` for the shorthand that constructs a plain Entity before adoption. Each adoption issues a fresh runtime identity.

- `entity`: Detached object to claim; its local components and effects survive transfer.
- Returns: A fresh generational identity valid only while this World owns the entity.
- Throws: Error when the entity is not detached or structural mutation is guarded.

```ts
removeEntity(entity: Entity): void
```
Releases an Entity, its runtime id, and indexed components without disposing local state. This is the ownership-removal primitive used for transfer and pooling. Use `disposeEntity` when the object itself must become terminal.

- `entity`: Current member, detached before its identity is retired.
- Throws: Error when the entity is foreign or structural mutation is guarded.

```ts
disposeEntity(entity: Entity): void
```
Removes one owned Entity and then disposes that object permanently. This helper combines the `removeEntity` ownership primitive with `Entity.dispose`. Use `removeEntity` instead for transfer or pooling.

- `entity`: Current member to remove and dispose.
- Throws: Error when the target is foreign or structural mutation is guarded.

```ts
dispose(): void
```
Closes this World and disposes every Entity it owns. A bare verb acts on its receiver; use `disposeEntity(entity)` to dispose one named Entity. Repeated calls are harmless.

```ts
onEntityDisposed(entity: Entity): void
```
Releases World indexes after an owned Entity completes disposal. This public hook keeps `core` independent from `ecs`; game code normally calls `disposeEntity`.

- `entity`: Possibly owned object issuing its disposal notification.

```ts
beforeEntityDispose(entity: Entity): void
```
Rejects direct Entity disposal during query, phase, or flush callbacks.

- `entity`: Object about to enter its disposal callbacks.
- Throws: Error when direct structural mutation is not currently safe.

```ts
idOf(entity: Entity): EntityId
```
Reads the entity's current World-local generational identity.

- `entity`: Object whose ownership must be current.
- Returns: An id invalidated when the object is removed or disposed.
- Throws: Error when this World does not own `entity`.

```ts
resolve(id: EntityId): Entity | null
```
Resolves an exact generation without reviving recycled identities.

- `id`: World-issued identity to resolve.
- Returns: The owned Entity, or `null` when the id is stale, released, or foreign.

```ts
owns(entity: Entity): boolean
```
Tests object ownership without throwing for detached or foreign entities.

- `entity`: Object reference to compare with current members.
- Returns: `true` only while this World retains that exact object.

```ts
get entityCount(): int
```
Number of roots currently owned by this World.

```ts
entities(): Entity[]
```
Captures owned roots in adoption order.

- Returns: A detached array unaffected by later World mutation.

```ts
registerStore<T>(key: ComponentKey<T>): IComponentStore<T>
```
Creates the sole indexed store associated with a typed component key.

- `key`: Identity token used for later access; equal labels do not make keys equal.
- Returns: The factory-created store retained by this World.
- Throws: DuplicateRegistration when the exact key is already registered.

```ts
store<T>(key: ComponentKey<T>): IComponentStore<T> | null
```
Looks up a component store by typed-key identity.

- `key`: Exact key originally registered with this World.
- Returns: The store, or `null` when that key was never registered.

```ts
storeRequired<T>(key: ComponentKey<T>): IComponentStore<T>
```
Retrieves a store when absence indicates a configuration error.

- `key`: Exact registered component identity.
- Returns: The store associated with `key`.
- Throws: MissingRegistration when no store uses that key.

```ts
put<T>(entity: Entity, key: ComponentKey<T>, value: T): void
```
Registers an indexed component immediately for an owned entity.

- `entity`: Current member receiving the component.
- `key`: Registered store identity.
- `value`: Component reference retained by the store.
- Throws: Error during a query, phase, or flush callback; use `deferPutComponent` there.

```ts
get<T>(entity: Entity, key: ComponentKey<T>): T | null
```
Reads indexed membership without treating a foreign entity or unregistered key as an error.

- `entity`: Object to resolve in this World.
- `key`: Component identity to inspect.
- Returns: The current value, or `null` for absent ownership, store, or membership.

```ts
getRequired<T>(entity: Entity, key: ComponentKey<T>): T
```
Reads indexed membership when ownership, store registration, and presence are invariants.

- `entity`: Object that must currently belong to this World.
- `key`: Component identity that must have a store and value.
- Returns: The exact component reference in the store.
- Throws: Error when any required ownership or membership is absent.

```ts
removeComponent<T>(entity: Entity, key: ComponentKey<T>): T | null
```
Removes indexed membership immediately when ownership, store, and value are present.

- `entity`: Object to inspect in this World.
- `key`: Component identity to remove.
- Returns: The former value, or `null` for absent ownership, store, or membership.
- Throws: Error during a query, phase, or flush callback; use `deferRemoveComponent` there.

```ts
query<T>(key: ComponentKey<T>): Query<T>
```
Creates a reusable one-store query; membership is captured when `each` starts.

- `key`: Registered component identity required by the query.
- Returns: A lightweight query bound to this World and key.

```ts
query2<A, B>(first: ComponentKey<A>, second: ComponentKey<B>): Query2<A, B>
```
Creates a reusable two-store intersection query; membership is captured by `each`.

- `first`: Registered key whose value is the visitor's second argument.
- `second`: Registered key whose value is the visitor's third argument.
- Returns: A lightweight query bound to this World and both keys.

```ts
runPhase(work: Function): void
```
Runs a callback inside a structural-mutation guard without implicitly flushing commands. Nested phases are allowed, and the guard is released even when the callback throws.

- `work`: Synchronous simulation callback.

```ts
deferCreateEntity(): Entity
```
Queues creation and returns the detached Entity that later commands may reference.

- Returns: An object not owned or query-visible until a successful `flush`.

```ts
deferDisposeEntity(entity: Entity): void
```
Appends entity disposal to the command buffer.

- `entity`: Current member, or an earlier `deferCreateEntity` result in the same batch.

```ts
deferPutComponent<T>(entity: Entity, key: ComponentKey<T>, value: T): void
```
Appends component registration to the command buffer in issue order.

- `entity`: Current member, or an earlier deferred creation in the batch.
- `key`: Store identity validated during flush preflight.
- `value`: Component reference made visible only after the batch applies.

```ts
deferRemoveComponent<T>(entity: Entity, key: ComponentKey<T>): void
```
Appends component removal to the command buffer in issue order.

- `entity`: Current member whose eventual membership is targeted.
- `key`: Component identity to remove when the batch applies.

```ts
flush(): void
```
Preflights and applies the current command batch atomically in issue order. Invalid batches are discarded before mutation; callback commands wait for the next flush.

- Throws: Error inside a query or phase, on recursive flush, or for a conflicting batch.

## WorldTicker

```ts
import { WorldTicker } from "gamekit";
class WorldTicker
```

Steps a `World` through a `PhaseSchedule` once per tick of a node's `onTick` hook. The runtime owns the fixed tick (`App.tps`, catch-up cap, pause and time scale); this class only forwards each tick, so pausing or disposing the node stops or ends the world step with it.

**Members**

```ts
constructor(node: any, world: World, schedule: PhaseSchedule, tickDelta: float)
```
Installs the step as `node.onTick`.

- `node`: Scene node whose `onTick` hook drives the world; its previous hook is replaced.
- `world`: Simulation domain passed to every system.
- `schedule`: Ordering of the systems inside one step.
- `tickDelta`: Positive seconds per tick, normally `App.tickDelta`.
- Throws: Error for a null node or a non-positive delta.

```ts
get tickCount(): int
```
Counts steps run so far, which is also the next tick number passed to the systems.

```ts
dispose(): void
```
Detaches the hook from the node; later ticks no longer step the world. Safe to call twice.

---

URL: https://thicketscript.com/gamekit/reference/

# Reference

gamekit `0.1.0-rc1`. The family pages below list every public class, interface, enum and function with its signature and documentation, generated from the gamekit source.

## Import paths

| Import from | Gives you |
|---|---|
| `"gamekit"` | The package root: `core`, `ecs`, `app`, `save` and `audio`, plus `DebugTools`, `DebugScenario` and `DebugTrace` from `testing`. |
| `"gamekit/src/willow"` | Presentation bindings and the willow input bridge. |
| `"gamekit/src/ui"` | `SceneWindowLayer`. |
| `"gamekit/src/testing"` | Clocks, schedulers and the debug tools. |
| `"gamekit/src/save"` | Everything in `save`, including `FsByteStorage`, which the root leaves out. |

## Families

| Family | Contents |
|---|---|
| [core](./core.html) | Entities, keys, events and pipelines, attributes and state machines, effects, definitions and prefabs, conditions, actions and interactions, assets, spatial types, `Gauge`, `WeightedPick`, errors. |
| [ecs](./ecs.html) | `World`, stores, `Query`, `Query2`, `PhaseSchedule`, `WorldTicker`, `createConventionalSchedule`. |
| [app](./app.html) | `AppScene`, `SceneStack`, `SceneCoordinator`, `ScreenLayers`, focus, and input actions, routing and replay. |
| [save](./save.html) | Codecs, schemas, migrations, storage, slots, settings. |
| [audio](./audio.html) | `MusicDirector`, `IMusicBackend`. |
| [willow](./willow.html) | `WillowPresentationAdapter`, bindings and tickets, `WillowInputBridge` and its samples and viewport. |
| [ui](./ui.html) | `SceneWindowLayer`. |
| [testing](./testing.html) | `SimulationClock`, `PresentationClock`, `ClockScheduler`, `DebugTools`, `DebugScenario`, `DebugTrace`. |

## Errors

All gamekit errors extend `GameKitError`:

| Error | Thrown when |
|---|---|
| `StaleHandle` | An asset handle is used after its scope was disposed. |
| `DuplicateRegistration` | Something is registered twice under one id. |
| `MissingRegistration` | A lookup names something that was never registered. |
| `CyclicDefinition` | Definition inheritance loops. |
| `InvalidDefinition` | A definition validator failed. |
| `CyclicDependency` | An asset plan's dependencies loop. |
| `InvalidArgument` | An argument is out of range, such as a gauge with zero capacity. |

## Requirements

gamekit needs a `thicket` compiler built from thicketscript `main` commit `9dde0bd0` or later (it uses `export *`, folder index imports and `static const` class members). Its manifest declares `compiler: ">=0.1.13-9dde0bd0"`. Projects list the `willow` and `bitmap` systems; the save family's `FsByteStorage` also needs `fs`.

---

URL: https://thicketscript.com/gamekit/reference/save

# save family

Codecs, save schemas and migrations, save documents, byte storage, save slots and the settings store.

Most symbols on this page come from the package root, `import { Name } from "gamekit";`. The rest come from `gamekit/src/save`, as each entry shows.

26 symbols.

| Symbol | Summary |
|---|---|
| [`canonicalizeValue`](#canonicalizevalue) | *function*. Recursively rebuilds objects with lexicographically sorted keys while preserving array order and scalar values. |
| [`Codec`](#codec) | *class*. Extensible bidirectional boundary between a runtime type and JSON-compatible save data. |
| [`CodecContext`](#codeccontext) | *class*. Per-operation codec services and policy, including reference resolution and preserved unknown fields. |
| [`Codecs`](#codecs) | *class*. Factory namespace for primitive and compositional save codecs. |
| [`FaultInjectingByteStorage`](#faultinjectingbytestorage) | *class*. Test decorator that injects deterministic storage failures, partial writes, and corruption before delegating. |
| [`FsByteStorage`](#fsbytestorage) | *class*. FsByteStorage implements byte-oriented persistence for save documents and slots. |
| [`IByteStorage`](#ibytestorage) | *interface*. Asynchronous text-blob storage boundary used by atomic save and settings workflows. |
| [`inspectSaveDocument`](#inspectsavedocument) | *function*. Parses only a save envelope's positive integer version and optional string schema ID. |
| [`MemoryByteStorage`](#memorybytestorage) | *class*. Deterministic process-local `IByteStorage` for tests and ephemeral saves. |
| [`MigrationStep`](#migrationstep) | *class*. One consecutive schema migration with optional validation on both sides of its version boundary. |
| [`RecordField`](#recordfield) | *class*. Declares one named field in a record codec, including decode presence and default rules. |
| [`ReferencePolicy`](#referencepolicy) | *enum*. Chooses whether an unresolved persisted reference fails decoding (`STRICT`) or decodes as `null` (`ALLOW_NULL`). |
| [`ReferenceResolver`](#referenceresolver) | *class*. Resolves persisted `(kind, id)` pairs to live objects from a local registry with an optional fallback. |
| [`SaveDocument`](#savedocument) | *class*. In-memory representation of a versioned save envelope and its encoded payload. |
| [`SaveDocumentHeader`](#savedocumentheader) | *class*. Lightweight version and schema identity read without decoding a save payload. |
| [`SaveResult`](#saveresult) | *class*. Non-throwing outcome for expected persistence, compatibility, and data-quality failures. |
| [`SaveResultKind`](#saveresultkind) | *enum*. Distinguishes success, environmental unavailability, invalid data, version incompatibility, and unreadable serialization. |
| [`SaveSchema`](#saveschema) | *class*. Versioned codec pipeline that canonicalizes writes and validates every consecutive migration boundary on reads. |
| [`SaveSlotInfo`](#saveslotinfo) | *class*. Listing result for one primary slot, including recoverability and metadata health. |
| [`SaveSlotManager`](#saveslotmanager) | *class*. Coordinates named, game-defined save documents over caller-provided byte storage. |
| [`SaveSlotManagerOptions`](#saveslotmanageroptions) | *class*. Naming and rotation configuration for `SaveSlotManager` storage keys. |
| [`SaveSlotMetadata`](#saveslotmetadata) | *class*. User-facing and schema metadata embedded beside a slot's encoded game data. |
| [`serializeCanonical`](#serializecanonical) | *function*. Serializes JSON-compatible data after recursively sorting object keys. |
| [`SettingsStore`](#settingsstore) | *class*. Atomic single-document settings storage, separate from named game-save slots. |
| [`SlotCancellationToken`](#slotcancellationtoken) | *class*. Cooperative preflight cancellation flag for queued slot saves and loads. |
| [`UnknownFieldPolicy`](#unknownfieldpolicy) | *enum*. Chooses whether record decoding rejects undeclared fields or preserves them in `CodecContext` for round trips. |

## canonicalizeValue

```ts
import { canonicalizeValue } from "gamekit";
function canonicalizeValue(val: any): any
```

Recursively rebuilds objects with lexicographically sorted keys while preserving array order and scalar values.

- `val`: JSON-compatible value to normalize.
- Returns: Detached arrays/objects suitable for deterministic serialization.

## Codec

```ts
import { Codec } from "gamekit";
class Codec<T>
```

Extensible bidirectional boundary between a runtime type and JSON-compatible save data. The base implementation is an identity codec; concrete codecs validate decode input and report expected failures through `SaveResult`.

**Members**

```ts
encode(value: T, context?: CodecContext): any
```
Encodes a runtime value; subclasses may consult resolver and preservation policy from the context.

- `value`: Runtime value to encode.
- `context`: Optional per-operation reference and unknown-field state.

```ts
decode(data: any, context?: CodecContext): SaveResult<T>
```
Decodes persisted data; the base class accepts it unchanged.

- `data`: JSON-compatible representation to decode.
- `context`: Optional resolver and preservation state shared by nested codecs.
- Returns: Successful typed value or a categorized validation failure.

## CodecContext

```ts
import { CodecContext } from "gamekit";
class CodecContext
```

Per-operation codec services and policy, including reference resolution and preserved unknown fields. Reuse the same context across decode and encode when `PRESERVE` must round-trip forward-compatible fields.

**Members**

```ts
resolver: ReferenceResolver | null
```
Registry consulted by reference codecs, or `null` when references cannot resolve.

```ts
unknownFieldPolicy: UnknownFieldPolicy
```
Whether record codecs reject or retain undeclared properties.

```ts
referencePolicy: ReferencePolicy
```
Whether unresolved references fail or become `null`.

```ts
constructor( resolver: ReferenceResolver | null = null, unknownFieldPolicy: UnknownFieldPolicy = UnknownFieldPolicy.REJECT, referencePolicy: ReferencePolicy = ReferencePolicy.STRICT )
```
Configures services shared by nested codec calls.

- `resolver`: Reference registry, if the schema contains object identities.
- `unknownFieldPolicy`: Record behavior for undeclared properties.
- `referencePolicy`: Decode behavior for missing reference targets.

```ts
setPreservedUnknownFields(id: string, fields: any): void
```
Associates detached unknown-field data with a record identity for later encoding.

- `id`: Record identity chosen by the record codec.
- `fields`: Undeclared field object to retain.

```ts
getPreservedUnknownFields(id: string): any
```
Looks up unknown fields previously captured for a record identity.

- `id`: Record identity used during decoding.
- Returns: Preserved object, or `undefined` when none was captured.

## Codecs

```ts
import { Codecs } from "gamekit";
class Codecs
```

Factory namespace for primitive and compositional save codecs.

**Members**

```ts
static int(): Codec<int>
```
Creates a codec accepting only finite integral JSON numbers.

```ts
static float(): Codec<float>
```
Creates a codec accepting finite JSON numbers.

```ts
static string(): Codec<string>
```
Creates a codec accepting string values.

```ts
static boolean(): Codec<boolean>
```
Creates a codec accepting boolean values.

```ts
static id(): Codec<string>
```
Creates a codec for non-empty string identifiers.

```ts
static optional<T>(codec: Codec<T>): Codec<T | null>
```
Wraps a codec so `null` round-trips without invoking the inner codec.

- `codec`: Inner codec for non-null values.

```ts
static array<T>(elementCodec: Codec<T>): Codec<T[]>
```
Applies one codec to each array element in order and stops at the first decode failure.

- `elementCodec`: Codec for every element.

```ts
static record<T>( fields: RecordField[], factory: (fields: any) => T, extractor: ((val: T, fieldName: string) => any) | null = null ): Codec<T>
```
Builds a record codec from declared fields and bidirectional value adapters.

- `fields`: Ordered field definitions written to the record.
- `factory`: Creates a typed value from successfully decoded named fields.
- `extractor`: Optional `(value, fieldName)` reader; direct property access is the default.

```ts
static taggedVariant<T>( tagField: string, variants: Map<string, Codec<any>>, tagExtractor: (value: T) => string ): Codec<T>
```
Builds a discriminated-union codec using a tag persisted in each record.

- `tagField`: Persisted discriminator property name.
- `variants`: Codecs indexed by accepted discriminator values.
- `tagExtractor`: Reads the discriminator from a runtime value during encode.

```ts
static reference<T>(kind: string, idExtractor: (value: T) => string): Codec<T>
```
Builds a codec that persists object identity and resolves it on load.

- `kind`: Namespace supplied to the context resolver.
- `idExtractor`: Reads the stable identifier written during encode.

## FaultInjectingByteStorage

```ts
import { FaultInjectingByteStorage } from "gamekit";
class FaultInjectingByteStorage implements IByteStorage
```

Test decorator that injects deterministic storage failures, partial writes, and corruption before delegating. One-shot flags clear only when their operation and optional path pattern match.

**Members**

```ts
inner: IByteStorage
```
Underlying storage used whenever no fault intercepts the call.

```ts
failNextWrite: boolean = false
```
One-shot injected failure flag for the next matching write.

```ts
failNextRename: boolean = false
```
One-shot injected failure flag for the next matching rename.

```ts
failNextRead: boolean = false
```
One-shot injected failure flag for the next matching read.

```ts
failNextCopy: boolean = false
```
One-shot injected failure flag for the next matching copy.

```ts
failNextRemove: boolean = false
```
One-shot injected failure flag for the next matching remove.

```ts
failNextExists: boolean = false
```
One-shot injected failure flag for the next matching exists.

```ts
failNextList: boolean = false
```
One-shot injected failure flag for the next matching list.

```ts
failPattern: string = ""
```
Optional substring limiting path-sensitive one-shot faults; empty matches every path.

```ts
quotaExceeded: boolean = false
```
Persistent flag making every matching write report quota exhaustion.

```ts
storageMissing: boolean = false
```
Persistent flag making all storage operations report a missing device.

```ts
partialWriteBytes: int = -1
```
Non-negative one-shot character count written instead of complete content; `-1` disables it.

```ts
corruptOnWrite: boolean = false
```
One-shot flag prefixing matching write content with an invalid marker.

```ts
constructor(inner: IByteStorage)
```
Wraps an existing storage implementation without copying its contents.

- `inner`: Backend receiving non-intercepted calls.

```ts
async read(path: string): Promise<SaveResult<string>>
```
Injects missing-device or matching one-shot read failure before delegating.

- `path`: Key tested against `failPattern`.

```ts
async write(path: string, content: string): Promise<SaveResult<boolean>>
```
Applies missing-device, quota, one-shot failure, partial-write, then corruption behavior in that priority.

- `path`: Destination key tested against `failPattern`.
- `content`: Original complete content.

```ts
async remove(path: string): Promise<SaveResult<boolean>>
```
Injects missing-device or matching one-shot removal failure before delegating.

- `path`: Key tested against `failPattern`.

```ts
async exists(path: string): Promise<SaveResult<boolean>>
```
Injects missing-device or matching one-shot existence failure before delegating.

- `path`: Key tested against `failPattern`.

```ts
async rename(oldPath: string, newPath: string): Promise<SaveResult<boolean>>
```
Injects rename failure when either source or destination matches, then delegates otherwise.

- `oldPath`: Source key.
- `newPath`: Rename destination participating in pattern matching.

```ts
async copy(srcPath: string, destPath: string): Promise<SaveResult<boolean>>
```
Injects copy failure when either key matches, then delegates otherwise.

- `srcPath`: Source key.
- `destPath`: Copy destination participating in pattern matching.

```ts
async list(prefix: string = ""): Promise<SaveResult<string[]>>
```
Injects missing-device or one-shot listing failure before delegation; `failPattern` does not filter list faults.

- `prefix`: Prefix forwarded to the underlying storage.

## FsByteStorage

```ts
import { FsByteStorage } from "gamekit/src/save";
class FsByteStorage implements IByteStorage
```

FsByteStorage implements byte-oriented persistence for save documents and slots.

**Members**

```ts
baseDir: string
```
Directory used to resolve relative storage paths.

```ts
constructor(baseDir: string)
```
Initializes a fs byte storage with explicit dependencies.

- `baseDir`: Directory prepended to relative paths; absolute paths bypass it.

```ts
async read(path: string): Promise<SaveResult<string>>
```
FsByteStorage Reads bytes from the requested location.

- `path`: Source file as an absolute path or relative to `baseDir`.
- Returns: File contents, or an unavailable result when the file is absent or unreadable.

```ts
async write(path: string, content: string): Promise<SaveResult<boolean>>
```
FsByteStorage Persists the supplied bytes at the requested location.

- `path`: Destination file as an absolute path or relative to `baseDir`.
- `content`: Text payload written after creating missing parent directories.
- Returns: Success with true, or an unavailable result describing the filesystem error.

```ts
async remove(path: string): Promise<SaveResult<boolean>>
```
FsByteStorage Removes the current value if it is registered.

- `path`: Entry to remove, resolved against `baseDir` when relative.
- Returns: Success with true even when the path is already absent; filesystem failures are unavailable results.

```ts
async exists(path: string): Promise<SaveResult<boolean>>
```
FsByteStorage Reports whether the requested persisted entry exists.

- `path`: Entry to query, resolved against `baseDir` when relative.
- Returns: Success containing the existence flag, or an unavailable result if the check fails.

```ts
async rename(oldPath: string, newPath: string): Promise<SaveResult<boolean>>
```
Moves one entry, creating the destination's parent directories first.

- `oldPath`: Existing absolute path or path relative to `baseDir`.
- `newPath`: Destination absolute path or path relative to `baseDir`.
- Returns: Success with true, or an unavailable result describing the filesystem error.

```ts
async copy(srcPath: string, destPath: string): Promise<SaveResult<boolean>>
```
FsByteStorage Returns a detached copy safe to retain independently.

- `srcPath`: Existing absolute path or path relative to `baseDir`.
- `destPath`: Destination absolute path or path relative to `baseDir`.
- Returns: Success with true, or an unavailable result describing the filesystem error.

```ts
async list(prefix: string = ""): Promise<SaveResult<string[]>>
```
Lists direct entries in `baseDir` in lexical order.

- `prefix`: Optional filename prefix; an empty string includes every entry.
- Returns: Matching entry names, an empty list for a missing directory, or an unavailable result on failure.

## IByteStorage

```ts
import { IByteStorage } from "gamekit";
interface IByteStorage
```

Asynchronous text-blob storage boundary used by atomic save and settings workflows. Environmental failures are returned as `SaveResult` rather than thrown. Paths are opaque keys to non-filesystem implementations.

**Members**

```ts
read(path: string): Promise<SaveResult<string>>
```
Reads the complete text blob at a path.

- `path`: Storage-relative key.
- Returns: Content or `UNAVAILABLE` when it cannot be read.

```ts
write(path: string, content: string): Promise<SaveResult<boolean>>
```
Replaces or creates a complete text blob.

- `path`: Destination storage key.
- `content`: Exact text to persist.

```ts
remove(path: string): Promise<SaveResult<boolean>>
```
Removes a blob; implementations may treat an absent path as success.

- `path`: Storage key to remove.

```ts
exists(path: string): Promise<SaveResult<boolean>>
```
Checks path presence without reading content.

- `path`: Storage key to test.

```ts
rename(oldPath: string, newPath: string): Promise<SaveResult<boolean>>
```
Moves one blob to a new key for final atomic replacement where the backend supports it.

- `oldPath`: Source key that must exist.
- `newPath`: Destination key to replace.

```ts
copy(srcPath: string, destPath: string): Promise<SaveResult<boolean>>
```
Copies source content to a second key without removing the source.

- `srcPath`: Source key to read without removal.
- `destPath`: Destination key to replace.

```ts
list(prefix?: string): Promise<SaveResult<string[]>>
```
Lists storage keys beginning with an optional prefix.

- `prefix`: Key prefix, or empty/omitted for all entries.
- Returns: Matching keys; deterministic implementations should sort them.

## inspectSaveDocument

```ts
import { inspectSaveDocument } from "gamekit";
function inspectSaveDocument(text: string): SaveResult<SaveDocumentHeader>
```

Parses only a save envelope's positive integer version and optional string schema ID.

- `text`: Candidate JSON document.
- Returns: Header without touching payload data, or `CORRUPT`/`MALFORMED` for invalid input.

## MemoryByteStorage

```ts
import { MemoryByteStorage } from "gamekit";
class MemoryByteStorage implements IByteStorage
```

Deterministic process-local `IByteStorage` for tests and ephemeral saves. Paths map directly to strings; all operations resolve immediately and listings are sorted.

**Members**

```ts
async read(path: string): Promise<SaveResult<string>>
```
Reads the exact string associated with a key.

- `path`: In-memory key.
- Returns: Content or `UNAVAILABLE` when absent.

```ts
async write(path: string, content: string): Promise<SaveResult<boolean>>
```
Creates or replaces one in-memory entry.

- `path`: Key to create or replace.
- `content`: Exact string to retain.

```ts
async remove(path: string): Promise<SaveResult<boolean>>
```
Deletes a key and succeeds even when it was absent.

- `path`: Key to delete.

```ts
async exists(path: string): Promise<SaveResult<boolean>>
```
Reports map membership without reading the value.

- `path`: Key to test.

```ts
async rename(oldPath: string, newPath: string): Promise<SaveResult<boolean>>
```
Moves content and replaces any destination entry.

- `oldPath`: Key whose entry is moved.
- `newPath`: Key receiving the moved entry.
- Returns: `UNAVAILABLE` if the source is absent.

```ts
async copy(srcPath: string, destPath: string): Promise<SaveResult<boolean>>
```
Duplicates content to a destination key, replacing its old value.

- `srcPath`: Key whose string is duplicated.
- `destPath`: Key receiving the duplicate.
- Returns: `UNAVAILABLE` if the source is absent.

```ts
async list(prefix: string = ""): Promise<SaveResult<string[]>>
```
Returns matching keys in lexical order.

- `prefix`: Optional prefix filter.

```ts
clear(): void
```
Deletes every in-memory entry synchronously.

## MigrationStep

```ts
import { MigrationStep } from "gamekit";
class MigrationStep
```

One consecutive schema migration with optional validation on both sides of its version boundary.

**Members**

```ts
sourceVersion: int
```
Version accepted before migration.

```ts
targetVersion: int
```
Version produced after migration; always `sourceVersion + 1`.

```ts
migrateFn: (data: any) => any
```
Synchronous transform from source-shaped data to target-shaped data.

```ts
validateSourceFn: ((data: any) => SaveResult<boolean>) | null
```
Optional validation run immediately before the transform.

```ts
validateTargetFn: ((data: any) => SaveResult<boolean>) | null
```
Optional validation run immediately after the transform.

```ts
constructor( sourceVersion: int, targetVersion: int, migrateFn: (data: any) => any, validateSourceFn: ((data: any) => SaveResult<boolean>) | null = null, validateTargetFn: ((data: any) => SaveResult<boolean>) | null = null )
```
Defines a single `n -> n+1` migration boundary.

- `sourceVersion`: Input document version.
- `targetVersion`: Exactly the next integer version.
- `migrateFn`: Transform returning non-null target data.
- `validateSourceFn`: Optional source-shape validator.
- `validateTargetFn`: Optional target-shape validator.
- Throws: Error unless target is exactly one greater than source.

## RecordField

```ts
import { RecordField } from "gamekit";
class RecordField
```

Declares one named field in a record codec, including decode presence and default rules.

**Members**

```ts
name: string
```
Persisted property name.

```ts
codec: Codec<any>
```
Codec applied to this property's runtime and serialized values.

```ts
required: boolean
```
Whether a missing property is a malformed decode.

```ts
defaultValue: any
```
Runtime value supplied when an optional property is absent.

```ts
constructor(name: string, codec: Codec<any>, required: boolean = true, defaultValue: any = null)
```
Defines record behavior for one property.

- `name`: Persisted key.
- `codec`: Value codec for the key.
- `required`: Whether absence fails decoding.
- `defaultValue`: Value used when a non-required key is absent.

## ReferencePolicy

```ts
import { ReferencePolicy } from "gamekit";
enum ReferencePolicy
```

Chooses whether an unresolved persisted reference fails decoding (`STRICT`) or decodes as `null` (`ALLOW_NULL`).

| Member | Meaning |
|---|---|
| `STRICT = 0` | Fail decoding when a referenced value cannot be resolved. |
| `ALLOW_NULL = 1` | Represent an unresolved reference as null. |

## ReferenceResolver

```ts
import { ReferenceResolver } from "gamekit";
class ReferenceResolver
```

Resolves persisted `(kind, id)` pairs to live objects from a local registry with an optional fallback.

**Members**

```ts
constructor(fallbackResolver: ((kind: string, id: string) => any) | null = null)
```
Creates an empty local registry.

- `fallbackResolver`: Optional `(kind, id)` lookup used only after a local miss.

```ts
register(kind: string, id: string, target: any): void
```
Registers or replaces the local target for one namespaced identity.

- `kind`: Reference namespace.
- `id`: Stable identifier within that namespace.
- `target`: Live object returned by later resolution.

```ts
resolve(kind: string, id: string): any
```
Resolves locally first, then delegates to the fallback.

- `kind`: Reference namespace to search.
- `id`: Stable identity within the namespace.
- Returns: Registered/fallback target, or `null` when unresolved.

```ts
has(kind: string, id: string): boolean
```
Tests only the local registry without invoking the fallback.

- `kind`: Local reference namespace.
- `id`: Identity to test.

## SaveDocument

```ts
import { SaveDocument } from "gamekit";
class SaveDocument
```

In-memory representation of a versioned save envelope and its encoded payload.

**Members**

```ts
version: int
```
Positive schema version describing `data`.

```ts
schemaId: string
```
Schema identity, or an empty string for legacy/unidentified documents.

```ts
data: any
```
Codec-produced JSON-compatible payload.

```ts
constructor(version: int, data: any, schemaId: string = "")
```
Wraps already encoded data; validation is performed by `SaveSchema.load`.

- `version`: Schema version of the payload.
- `data`: Encoded payload.
- `schemaId`: Optional schema identity.

## SaveDocumentHeader

```ts
import { SaveDocumentHeader } from "gamekit";
class SaveDocumentHeader
```

Lightweight version and schema identity read without decoding a save payload.

**Members**

```ts
version: int
```
Positive version declared by the envelope.

```ts
schemaId: string
```
Declared schema identity, or empty when absent/non-string.

```ts
constructor(version: int, schemaId: string = "")
```
Captures inspected envelope metadata.

- `version`: Validated positive document version.
- `schemaId`: Optional schema identity.

## SaveResult

```ts
import { SaveResult } from "gamekit";
class SaveResult<T>
```

Non-throwing outcome for expected persistence, compatibility, and data-quality failures. Successful results carry `value`; failures carry `kind`, `message`, and the version boundary where known.

**Members**

```ts
isOk: boolean
```
`true` only when `value` contains the requested result.

```ts
value: any
```
Successful payload, or `null` for factory-created failures.

```ts
kind: SaveResultKind
```
Machine-readable outcome category.

```ts
message: string
```
Human-readable diagnostic for a failed operation.

```ts
version: int
```
Document or migration version associated with the outcome; zero means unavailable.

```ts
constructor(isOk: boolean, value: any, kind: SaveResultKind, message: string, version: int = 0)
```
Creates an explicit outcome record; prefer the named factories at call sites.

- `isOk`: Success flag governing whether `value` is meaningful.
- `value`: Decoded value or operation payload.
- `kind`: Stable outcome category.
- `message`: Human-readable diagnostic, normally empty on success.
- `version`: Relevant schema version, or zero when unknown.

```ts
static ok<T>(value: any, version: int = 0): SaveResult<T>
```
Creates a successful result with kind `OK` and no diagnostic message.

- `value`: Successful payload.
- `version`: Schema version attached to the payload.

```ts
static unavailable<T>(message: string, version: int = 0): SaveResult<T>
```
Reports missing storage, missing slots, cancellation, or environmental I/O failure.

- `message`: Diagnostic suitable for logs or UI translation.
- `version`: Known document version, if any.

```ts
static malformed<T>(message: string, version: int = 0): SaveResult<T>
```
Reports a structurally valid envelope whose fields, validation, or migration data are invalid.

- `message`: Description of the rejected shape or boundary.
- `version`: Version at which validation failed.

```ts
static incompatible<T>(message: string, version: int = 0): SaveResult<T>
```
Reports a schema ID/version mismatch or missing migration path.

- `message`: Compatibility explanation.
- `version`: Document or boundary version that cannot be consumed.

```ts
static corrupt<T>(message: string, version: int = 0): SaveResult<T>
```
Reports unreadable serialization or a non-object save envelope.

- `message`: Parse or envelope diagnostic.
- `version`: Known version, normally zero when parsing failed.

## SaveResultKind

```ts
import { SaveResultKind } from "gamekit";
enum SaveResultKind
```

Distinguishes success, environmental unavailability, invalid data, version incompatibility, and unreadable serialization.

| Member | Meaning |
|---|---|
| `OK = "ok"` | The operation completed with a value. |
| `UNAVAILABLE = "unavailable"` | Environment or storage access prevented the operation. |
| `MALFORMED = "malformed"` | The data does not match its expected encoding. |
| `INCOMPATIBLE = "incompatible"` | The data version cannot be read by this schema. |
| `CORRUPT = "corrupt"` | Persisted bytes are damaged or incomplete. |

## SaveSchema

```ts
import { SaveSchema } from "gamekit";
class SaveSchema<T>
```

Versioned codec pipeline that canonicalizes writes and validates every consecutive migration boundary on reads. Expected document failures return `SaveResult`; constructor/registration misuse throws.

**Members**

```ts
schemaId: string
```
Identity compared with non-empty document schema IDs.

```ts
currentVersion: int
```
Positive version written by `dump` and reached by all migration paths.

```ts
codec: Codec<T>
```
Codec applied after migration on load and before envelope creation on dump.

```ts
constructor(schemaId: string, currentVersion: int, codec: Codec<T>)
```
Creates a schema with no historical migration steps or validators.

- `schemaId`: Expected envelope identity; empty accepts unidentified documents.
- `currentVersion`: Positive version for new writes.
- `codec`: Runtime payload codec.
- Throws: Error if current version is not positive.

```ts
addMigration(step: MigrationStep): void
```
Registers one migration keyed by its source version.

- `step`: Consecutive boundary used when loading that source version.
- Throws: Error if a step for the source version already exists.

```ts
addValidator(version: int, validator: (data: any) => SaveResult<boolean>): void
```
Registers a validation callback for one historical schema version.

- `version`: Document version whose encoded payload shape is checked.
- `validator`: Callback returning a success or diagnostic failure.

```ts
inspect(text: string): SaveResult<SaveDocumentHeader>
```
Reads version and schema ID without checking this schema's identity or decoding payload data.

- `text`: Candidate JSON envelope.
- Returns: Header metadata or categorized parse/shape failure.

```ts
dump(value: T, context?: CodecContext, pretty: boolean = false): SaveResult<string>
```
Encodes a runtime value into a canonical current-version envelope.

- `value`: Runtime payload to persist.
- `context`: Optional reference and unknown-field state passed to the codec.
- `pretty`: Whether to emit two-space-indented canonical JSON.
- Returns: Successful JSON text tagged with `currentVersion`.

```ts
load(text: string, context?: CodecContext): SaveResult<T>
```
Parses an envelope, verifies identity/version, migrates consecutively with before-and-after validation, then decodes.

- `text`: Candidate save JSON.
- `context`: Optional services shared through nested decode calls.
- Returns: Current-version value, or `CORRUPT`, `MALFORMED`, or `INCOMPATIBLE` without throwing expected data failures.

## SaveSlotInfo

```ts
import { SaveSlotInfo } from "gamekit";
class SaveSlotInfo
```

Listing result for one primary slot, including recoverability and metadata health.

**Members**

```ts
slotId: string
```
Logical slot name without storage extensions.

```ts
metadata: SaveSlotMetadata | null
```
Parsed primary-or-backup metadata, or `null` when inspection failed.

```ts
hasBackup: boolean
```
Whether a backup blob exists for possible recovery.

```ts
isCorrupt: boolean
```
Whether metadata inspection failed for the listed slot.

```ts
constructor( slotId: string, metadata: SaveSlotMetadata | null, hasBackup: boolean = false, isCorrupt: boolean = false )
```
Captures one detached slot-list entry.

- `slotId`: Name represented by this listing entry.
- `metadata`: Parsed metadata when available.
- `hasBackup`: Backup-presence flag.
- `isCorrupt`: Inspection-failure flag.

## SaveSlotManager

```ts
import { SaveSlotManager } from "gamekit";
class SaveSlotManager<T>
```

Coordinates named, game-defined save documents over caller-provided byte storage. One manager owns its per-slot operation queues until shutdown; schemas and storage remain supplied by the game.

**Members**

```ts
storage: IByteStorage
```
Byte storage receiving primary, temporary, and backup blobs.

```ts
schema: SaveSchema<T>
```
Current codec and migration pipeline for slot payloads.

```ts
extension: string
```
Primary key suffix.

```ts
tempExtension: string
```
Sibling temporary-write suffix.

```ts
backupExtension: string
```
Previous-primary backup suffix.

```ts
maxAutosaves: int
```
Autosave ring cardinality.

```ts
autosavePrefix: string
```
Prefix for zero-based autosave names.

```ts
constructor( storage: IByteStorage, schema: SaveSchema<T>, options?: any )
```
Creates independent per-slot queues and an autosave cursor at index zero.

- `storage`: Backend used for every blob operation.
- `schema`: Current payload schema.
- `options`: Optional suffix, autosave size, and prefix overrides.

```ts
async shutdown(): Promise<void>
```
Rejects new saves/loads/inspections and waits for all already queued slot operations to settle.

```ts
async saveSlot( slotId: string, data: T, metadata?: any, cancelToken?: SlotCancellationToken ): Promise<SaveResult<SaveSlotMetadata>>
```
Serializes behind prior work for the same slot, then writes temp, validates, backs up, and atomically renames.

- `slotId`: Logical name used to derive storage keys.
- `data`: Runtime payload encoded by the schema codec.
- `metadata`: Metadata instance or partial metadata object; missing schema fields are filled.
- `cancelToken`: Optional token checked when queued work begins.
- Returns: Final metadata on success, otherwise a categorized storage or validation failure.

```ts
async loadSlot( slotId: string, cancelToken?: SlotCancellationToken ): Promise<SaveResult<T>>
```
Loads through the schema after earlier work for this slot, falling back to backup and restoring primary when recovery succeeds.

- `slotId`: Slot to load from primary or backup.
- `cancelToken`: Optional token checked before storage access.
- Returns: Decoded current-version payload or the primary failure when recovery fails.

```ts
async inspectSlot( slotId: string ): Promise<SaveResult<SaveSlotMetadata>>
```
Reads metadata without decoding game data, trying backup after any primary inspection failure.

- `slotId`: Logical slot name serialized behind work for the same slot.
- Returns: Parsed primary or backup metadata.

```ts
async listSlots(): Promise<SaveResult<SaveSlotInfo[]>>
```
Lists primary slot keys, inspects their metadata, and returns entries sorted by slot ID.

- Returns: Slot information including backup presence and corruption flags.

```ts
async deleteSlot(slotId: string): Promise<SaveResult<boolean>>
```
Serially requests removal of a slot's primary, temporary, and backup blobs.

- `slotId`: Slot whose three derived keys are removed.
- Returns: Success after all removal attempts; individual removal results are intentionally ignored.

```ts
async rotateAutosave(data: T, metadata?: any): Promise<SaveResult<SaveSlotMetadata>>
```
Advances the in-memory round-robin cursor and saves to `<prefix><index>`.

- `data`: Runtime payload for the chosen autosave slot.
- `metadata`: Optional display and timestamp metadata.
- Returns: The delegated slot-save result.

```ts
async latestAutosave(): Promise<SaveResult<SaveSlotMetadata>>
```
Inspects the configured autosave ring and selects the greatest metadata timestamp.

- Returns: Latest readable metadata, or `UNAVAILABLE` when none can be inspected.

## SaveSlotManagerOptions

```ts
import { SaveSlotManagerOptions } from "gamekit";
class SaveSlotManagerOptions
```

Naming and rotation configuration for `SaveSlotManager` storage keys.

**Members**

```ts
extension: string = ".sav"
```
Primary slot suffix, default `.sav`.

```ts
tempExtension: string = ".tmp"
```
Sibling temporary-write suffix, default `.tmp`.

```ts
backupExtension: string = ".bak"
```
Previous-primary backup suffix, default `.bak`.

```ts
maxAutosaves: int = 3
```
Number of names in the round-robin autosave ring.

```ts
autosavePrefix: string = "autosave_"
```
Prefix placed before the zero-based autosave ring index.

```ts
constructor( extension: string = ".sav", tempExtension: string = ".tmp", backupExtension: string = ".bak", maxAutosaves: int = 3, autosavePrefix: string = "autosave_" )
```
Supplies storage naming defaults and autosave ring size.

- `extension`: Primary suffix.
- `tempExtension`: Temporary suffix.
- `backupExtension`: Backup suffix.
- `maxAutosaves`: Autosave ring cardinality.
- `autosavePrefix`: Autosave name prefix.

## SaveSlotMetadata

```ts
import { SaveSlotMetadata } from "gamekit";
class SaveSlotMetadata
```

User-facing and schema metadata embedded beside a slot's encoded game data.

**Members**

```ts
slotId: string
```
Logical slot name without file suffixes.

```ts
schemaId: string
```
Schema identity recorded at save time.

```ts
version: int
```
Payload schema version recorded at save time.

```ts
timestamp: int
```
Game-supplied integer timestamp used to choose the latest autosave.

```ts
playTime: float
```
Game-supplied play duration, conventionally in seconds.

```ts
title: string
```
Display label for save-selection UI.

```ts
custom: any
```
Game-defined JSON-compatible metadata; null construction input becomes an empty object.

```ts
constructor( slotId: string = "", schemaId: string = "", version: int = 1, timestamp: int = 0, playTime: float = 0.0, title: string = "", custom: any = null )
```
Builds metadata without imposing clock or presentation conventions.

- `slotId`: Name embedded in the slot envelope.
- `schemaId`: Save schema identity.
- `version`: Payload version.
- `timestamp`: Comparable game-selected timestamp.
- `playTime`: Game-selected duration.
- `title`: Human-readable slot label.
- `custom`: Additional JSON-compatible fields.

## serializeCanonical

```ts
import { serializeCanonical } from "gamekit";
function serializeCanonical(value: any, pretty: boolean = false): string
```

Serializes JSON-compatible data after recursively sorting object keys.

- `value`: Data to canonicalize and encode.
- `pretty`: Whether to indent with two spaces; compact output is the default.
- Returns: Deterministic JSON text for equivalent values.

## SettingsStore

```ts
import { SettingsStore } from "gamekit";
class SettingsStore<T>
```

Atomic single-document settings storage, separate from named game-save slots. Writes use temp validation, backup, and rename; loads recover a valid backup and restore primary.

**Members**

```ts
storage: IByteStorage
```
Backend holding primary, temporary, and backup settings blobs.

```ts
filename: string
```
Primary settings storage key.

```ts
schema: SaveSchema<T>
```
Codec and migration pipeline for the settings payload.

```ts
tempFilename: string
```
Sibling temporary key derived as `<filename>.tmp`.

```ts
backupFilename: string
```
Previous-primary key derived as `<filename>.bak`.

```ts
constructor( storage: IByteStorage, filename: string = "settings.json", schema: SaveSchema<T> )
```
Derives sibling temp and backup names from the primary key.

- `storage`: Backend for all settings blobs.
- `filename`: Primary key, defaulting to `settings.json`.
- `schema`: Versioned settings schema.

```ts
async save(settings: T): Promise<SaveResult<boolean>>
```
Encodes settings, validates a sibling temporary blob, backs up an existing primary, then renames the temp.

- `settings`: Runtime settings value.
- Returns: Success at the schema's current version, or a categorized encode/storage/validation failure.

```ts
async load(): Promise<SaveResult<T>>
```
Loads and migrates primary settings, or recovers a valid backup and copies it back to primary.

- Returns: Decoded settings; if recovery fails, the original primary failure is retained.

```ts
async hasSettings(): Promise<boolean>
```
Returns `true` only when the primary key's existence check succeeds and reports presence.

```ts
async clear(): Promise<SaveResult<boolean>>
```
Requests removal of primary, temp, and backup settings blobs.

- Returns: Success after all attempts; individual removal failures are intentionally ignored.

## SlotCancellationToken

```ts
import { SlotCancellationToken } from "gamekit";
class SlotCancellationToken
```

Cooperative preflight cancellation flag for queued slot saves and loads. Cancellation is checked when an operation reaches the front of its per-slot queue, not during storage I/O already underway.

**Members**

```ts
cancel(): void
```
Permanently marks the token cancelled; repeated calls are inert.

```ts
get isCancelled(): boolean
```
Is `true` after cancellation has been requested.

## UnknownFieldPolicy

```ts
import { UnknownFieldPolicy } from "gamekit";
enum UnknownFieldPolicy
```

Chooses whether record decoding rejects undeclared fields or preserves them in `CodecContext` for round trips.

| Member | Meaning |
|---|---|
| `REJECT = 0` | Fail decoding when an undeclared field is present. |
| `PRESERVE = 1` | Retain undeclared fields for a later round trip. |

---

URL: https://thicketscript.com/gamekit/reference/testing

# testing family

Deterministic clocks and schedulers, test asset loaders, debug inspection, scenarios and traces.

Import these from `gamekit/src/testing` (a few are also re-exported by the package root, as noted on each).

8 symbols, 3 of them also in the package root.

| Symbol | Summary |
|---|---|
| [`ClockScheduler`](#clockscheduler) | *class*. Schedules deterministic one-shot and periodic callbacks against explicitly advanced seconds. |
| [`DebugScenario`](#debugscenario) | *class*. Builds a detached input sequence, reproduces its first deterministic failure, and deletion-minimizes it. |
| [`DebugTools`](#debugtools) | *class*. Produces detached, stable descriptions of GameKit ownership and ordering for headless diagnostics. |
| [`DebugTrace`](#debugtrace) | *class*. Bounded opt-in diagnostic ring that detaches and optionally redacts each event. |
| [`PresentationClock`](#presentationclock) | *class*. Independently pausable, scalable clock for presentation-domain timers. |
| [`ScheduledWork`](#scheduledwork) | *class*. Stable control handle for one scheduler entry. |
| [`ScheduleOwner`](#scheduleowner) | *class*. Generation token that prevents scheduled callbacks from surviving disposal or object-pool reuse. |
| [`SimulationClock`](#simulationclock) | *class*. Fixed-step simulation time domain with a scheduler advanced before each user tick callback. |

## ClockScheduler

```ts
import { ClockScheduler } from "gamekit/src/testing";
class ClockScheduler
```

Schedules deterministic one-shot and periodic callbacks against explicitly advanced seconds. Each advance snapshots eligible work, orders equal due times by stable ID, and defers work created by callbacks until the next advance.

**Members**

```ts
constructor(catchUpCap: int = DEFAULT_SCHEDULER_CATCH_UP_CAP)
```
Creates an empty scheduler at time zero.

- `catchUpCap`: Positive limit on periodic catch-up callbacks per advance.
- Throws: Error if the cap is not positive.

```ts
get time(): float
```
Elapsed scheduler time in explicitly supplied seconds.

```ts
get catchUpCap(): int
```
Maximum periodic catch-up callbacks attempted in one advance.

```ts
get advancing(): boolean
```
Is `true` while the due-work snapshot is executing.

```ts
get activeCount(): int
```
Number of retained active entries, including future and backlogged periodic work.

```ts
schedule(delay: float, callback: Function, owner: ScheduleOwner | null = null): ScheduledWork
```
Enqueues a one-shot callback relative to current scheduler time.

- `delay`: Non-negative seconds before eligibility.
- `callback`: Synchronous work invoked at most once.
- `owner`: Optional generation-checked lifetime owner.
- Returns: Stable handle for cancellation or rescheduling.
- Throws: Error if delay is negative.

```ts
scheduleEvery(period: float, callback: Function, owner: ScheduleOwner | null = null): ScheduledWork
```
Enqueues periodic work whose first due time is one period from now.

- `period`: Positive seconds between due times.
- `callback`: Synchronous work that may run repeatedly during catch-up.
- `owner`: Optional generation-checked lifetime owner.
- Returns: Stable handle retaining one identity across repetitions.
- Throws: Error if period is not positive.

```ts
advance(elapsed: float): int
```
Advances time, snapshots due entries, and invokes them by due time then ID. Cancellation inside a callback does not remove another callback already in the snapshot; newly scheduled work waits for a later call.

- `elapsed`: Non-negative seconds to add, including zero for draining eligible deferred work.
- Returns: Number of callbacks invoked.
- Throws: Error for negative elapsed time, recursive advancement, or a callback failure.

```ts
cancelEntry(entry: ScheduledEntry): void
```
Invalidates an active internal entry; inactive entries are ignored.

- `entry`: Entry owned by a `ScheduledWork` handle.

```ts
rescheduleEntry(entry: ScheduledEntry, delay: float): void
```
Replaces an active entry's due time without changing its ID or creating a second callback.

- `entry`: Entry owned by a `ScheduledWork` handle.
- `delay`: Non-negative seconds relative to current scheduler time.
- Throws: Error if delay is negative.

## DebugScenario

```ts
import { DebugScenario } from "gamekit";
class DebugScenario
```

Builds a detached input sequence, reproduces its first deterministic failure, and deletion-minimizes it. Transitions and assertions run synchronously from copied state and inputs.

**Members**

```ts
constructor(seed: int)
```
Creates an empty scenario carrying the seed reported to every transition and result.

- `seed`: Game-selected reproduction seed; the scenario does not interpret it.

```ts
step(label: string, input: any): DebugScenario
```
Appends a detached input with a diagnostic label.

- `label`: Non-empty human-readable step name.
- `input`: Value copied now for later replay.
- Returns: This scenario for chaining.
- Throws: Error if `label` is empty.

```ts
steps(): any[]
```
Returns detached `{label, input}` records in execution order.

```ts
run(initial: any, apply: Function, assertFailure: Function | null = null): any
```
Applies steps until the assertion returns a reason, capturing the failing boundary and canonical diff.

- `initial`: State copied before the first transition.
- `apply`: Synchronous `(state, input, seed, index)` transition returning next state.
- `assertFailure`: Optional `(state, seed, index, input)` callback returning a reason or `null`.
- Returns: Failure details at the first reason, otherwise final state and a complete transcript.

```ts
minimize(stillFails: Function): DebugScenario
```
Removes contiguous chunks while the supplied clean-run predicate still reproduces failure.

- `stillFails`: Synchronous predicate receiving each candidate scenario.
- Returns: New scenario with retained step order and the same seed; the original is unchanged.

## DebugTools

```ts
import { DebugTools } from "gamekit";
class DebugTools
```

Produces detached, stable descriptions of GameKit ownership and ordering for headless diagnostics. Object keys are sorted, functions are omitted, and cycles become the literal `[circular]`.

**Members**

```ts
static inspect(value: any): any
```
Recursively copies data into sorted debug-safe objects without live references.

- `value`: Value to detach; repeated references on one traversal are rendered as `[circular]`.

```ts
static inspectWorld(world: any): any
```
Describes entities, stores, components, effects, deferred commands, guard depths, and teardown state without mutation.

- `world`: World whose public and diagnostic state is copied.
- Returns: Detached snapshot ordered by the world's current entity and registration order.

```ts
static inspectQuery(query: any): any
```
Reads required component labels from a `Query` or `Query2` without executing iteration.

- `query`: Query whose one or two keys are inspected.

```ts
static inspectPhases(schedule: any): any
```
Copies declared phase order, dependencies, system counts, flush flags, and current running state.

- `schedule`: Phase schedule inspected without resolving or running it.

```ts
static inspectClock(clock: any): any
```
Normalizes a simulation clock, presentation clock, or bare scheduler into one timing snapshot.

- `clock`: Clock or scheduler to inspect without advancing it.

```ts
static inspectInputRouter(router: any): any
```
Copies context precedence, action captures, and queued-release count without routing a frame.

- `router`: Input router whose current ownership is inspected.

```ts
static inspectScenes(scenes: any): any
```
Copies bottom-to-top scene names, count, and transition activity without invoking hooks.

- `scenes`: Sole scene stack to inspect.

```ts
static inspectEffects(effects: any): any
```
Copies effect IDs, keys, order, state, and values without exposing handles.

- `effects`: Collection whose lifecycle entries are inspected.

```ts
static inspectAssets(manager: any): any
```
Copies asset keys, states, reference counts, generations, and errors without exposing loaded assets.

- `manager`: Asset manager inspected without changing loads or scopes.

```ts
static inspectSaves(manager: any): any
```
Reports slot extension, autosave limit, shutdown flag, and per-slot queue count without storage I/O.

- `manager`: Save-slot manager whose configuration is inspected.

```ts
static canonicalSnapshot(value: any): string
```
Detaches a value and serializes it with canonical object-key ordering.

- `value`: Debug state to snapshot.

```ts
static diff(before: any, after: any): any
```
Compares detached canonical values and lists changed top-level keys in sorted order.

- `before`: Earlier diagnostic state.
- `after`: Later diagnostic state.
- Returns: `{changed, before, after}`; scalar differences use the synthetic key `value`.

```ts
static assertTranscript(actual: any, expected: any): void
```
Compares canonical detached transcripts and includes both serialized forms on mismatch.

- `actual`: Produced transcript.
- `expected`: Expected transcript.
- Throws: Error when canonical transcripts differ.

## DebugTrace

```ts
import { DebugTrace } from "gamekit";
class DebugTrace
```

Bounded opt-in diagnostic ring that detaches and optionally redacts each event. Disabled recording returns before allocation, redaction, or observer callbacks.

**Members**

```ts
constructor(enabled: boolean = false, maxEntries: int = 128, redactor: Function | null = null, callback: Function | null = null)
```
Configures trace retention and enabled-only hooks.

- `enabled`: Initial recording state.
- `maxEntries`: Positive capacity; the oldest entry is evicted on overflow.
- `redactor`: Optional transform applied before detaching a recorded value.
- `callback`: Optional observer receiving a detached entry after retention.
- Throws: Error if capacity is not positive.

```ts
get enabled(): boolean
```
Is `true` when `record` will retain data and invoke hooks.

```ts
get count(): int
```
Number of retained entries, never greater than configured capacity.

```ts
setEnabled(enabled: boolean): void
```
Changes recording state without clearing existing entries.

- `enabled`: Whether later calls may retain and observe events.

```ts
record(kind: string, value: any): void
```
Redacts, detaches, retains, and observes one event when enabled.

- `kind`: Non-empty stable event category.
- `value`: Live game value; neither retention nor observer receives this reference.
- Throws: Error for an empty kind when enabled.

```ts
entries(): any[]
```
Returns detached entries from oldest retained to newest.

```ts
clear(): void
```
Clears retained entries without changing enabled state or hooks.

## PresentationClock

```ts
import { PresentationClock } from "gamekit/src/testing";
class PresentationClock
```

Independently pausable, scalable clock for presentation-domain timers. It advances only from supplied elapsed seconds and owns a scheduler in the same scaled time domain.

**Members**

```ts
constructor(schedulerCatchUpCap: int = DEFAULT_SCHEDULER_CATCH_UP_CAP)
```
Creates a time-zero presentation domain.

- `schedulerCatchUpCap`: Positive periodic callback cap for the owned scheduler.
- Throws: Error if the scheduler cap is not positive.

```ts
get scheduler(): ClockScheduler
```
Scheduler sharing this clock's scaled seconds and pause behavior.

```ts
get time(): float
```
Total scaled seconds accepted while unpaused.

```ts
get timeScale(): float
```
Multiplier applied to later elapsed-time advances.

```ts
get paused(): boolean
```
Is `true` when advances discard elapsed time and run no callbacks.

```ts
setTimeScale(scale: float): void
```
Changes the multiplier for future advances without altering accumulated time.

- `scale`: Non-negative elapsed-time multiplier; zero freezes progression without setting `paused`.
- Throws: Error if scale is negative.

```ts
pause(): void
```
Starts discarding subsequent elapsed-time advances.

```ts
resume(): void
```
Accepts later advances again without replaying time discarded while paused.

```ts
advance(elapsed: float): int
```
Adds scaled elapsed seconds and runs scheduler work due in the new interval.

- `elapsed`: Non-negative unscaled seconds from the presentation loop.
- Returns: Callback count, or zero while paused.
- Throws: Error for negative elapsed time or scheduler callback failures.

## ScheduledWork

```ts
import { ScheduledWork } from "gamekit/src/testing";
class ScheduledWork
```

Stable control handle for one scheduler entry. Its ID survives rescheduling; completed, cancelled, or stale-owner work becomes inactive permanently.

**Members**

```ts
constructor(scheduler: any, entry: ScheduledEntry)
```
Binds an internal entry to the scheduler that created it.

- `scheduler`: Scheduler receiving handle operations.
- `entry`: Internal entry whose identity and state are exposed.

```ts
get id(): int
```
Scheduler-local monotonic identity used to order equal due times.

```ts
get active(): boolean
```
Is `true` while the entry remains eligible for future invocation.

```ts
cancel(): void
```
Prevents future invocations; repeated cancellation has no effect.

```ts
reschedule(delay: float): void
```
Moves active work relative to current scheduler time while preserving its ID.

- `delay`: Non-negative seconds from now; inactive work remains inactive.
- Throws: Error if delay is negative.

## ScheduleOwner

```ts
import { ScheduleOwner } from "gamekit/src/testing";
class ScheduleOwner
```

Generation token that prevents scheduled callbacks from surviving disposal or object-pool reuse. Schedulers capture the generation at scheduling time and retire work when it no longer matches.

**Members**

```ts
get generation(): int
```
Revision number incremented on each dispose and revive boundary.

```ts
get disposed(): boolean
```
Is `true` while no callbacks may target this owner.

```ts
dispose(): void
```
Invalidates all work scheduled against the current generation; repeated calls are inert.

```ts
revive(): void
```
Begins a fresh live generation without reviving stale work.

- Throws: Error when the owner is already live.

## SimulationClock

```ts
import { SimulationClock } from "gamekit/src/testing";
class SimulationClock
```

Fixed-step simulation time domain with a scheduler advanced before each user tick callback. Pausing discards supplied time, while manual stepping still executes exactly one tick.

**Members**

```ts
constructor(tickDuration: float, catchUpCap: int, tickWork: Function, schedulerCatchUpCap: int = DEFAULT_SCHEDULER_CATCH_UP_CAP)
```
Creates a time-zero fixed-step domain and its timer scheduler.

- `tickDuration`: Positive simulated seconds per tick.
- `catchUpCap`: Positive tick limit per advance.
- `tickWork`: Callback receiving `(tickDuration, zeroBasedTickNumber)` after due timers.
- `schedulerCatchUpCap`: Positive periodic callback cap per scheduler advance.
- Throws: Error if either duration or cap is invalid.

```ts
get scheduler(): ClockScheduler
```
Timer scheduler sharing fixed-step simulated seconds.

```ts
get time(): float
```
Total seconds in successfully started fixed ticks; fractional remainder is excluded.

```ts
get timeScale(): float
```
Multiplier applied to later elapsed-time advances.

```ts
get paused(): boolean
```
Is `true` when `advance` discards time; manual steps remain available.

```ts
get tickCount(): int
```
Count of successfully completed fixed ticks, starting at zero.

```ts
get interpolation(): float
```
Buffered fraction of the next fixed tick, clamped to `[0, 1]`.

```ts
setTimeScale(scale: float): void
```
Changes the multiplier for future automatic advances.

- `scale`: Non-negative multiplier; zero freezes automatic ticks.
- Throws: Error if scale is negative.

```ts
pause(): void
```
Makes later automatic advances discard time without clearing an existing fractional remainder.

```ts
resume(): void
```
Re-enables automatic advancement without replaying discarded time.

```ts
advance(elapsed: float): int
```
Scales elapsed seconds and runs as many complete ticks as the catch-up cap permits.

- `elapsed`: Non-negative unscaled seconds since the previous call.
- Returns: Completed tick count, or zero while paused.
- Throws: Error for negative elapsed time, recursive stepping, or callback failures.

```ts
step(): void
```
Runs one fixed tick immediately, including due timers, without consuming the stepper remainder.

```ts
singleStep(): void
```
Alias for `step`, emphasizing its use while automatic advancement is paused.

---

URL: https://thicketscript.com/gamekit/reference/ui

# ui family

Scene windows and screen windows on willowui.

Import these from `gamekit/src/ui` (a few are also re-exported by the package root, as noted on each).

1 symbols, 0 of them also in the package root.

| Symbol | Summary |
|---|---|
| [`SceneWindowLayer`](#scenewindowlayer) | *class*. Connects one WillowUI WindowManager to each scene and one persistent manager to the screen. |

## SceneWindowLayer

```ts
import { SceneWindowLayer } from "gamekit/src/ui";
class SceneWindowLayer implements IFocusGroup
```

Connects one WillowUI WindowManager to each scene and one persistent manager to the screen. WillowUI retains window ordering, modal overlays, dragging, suspension, and widget focus; GameKit supplies scene ownership and application focus resolution.

**Members**

```ts
readonly screenWindows: WindowManager
```
Persistent windows drawn above the complete scene stack.

```ts
constructor(scenes: SceneStack, createManager: (() => WindowManager) | null = null, keyboardHandler: ((window: Window, input: any) => boolean) | null = null, widgetFocus: FocusManager | null = null)
```
Creates scene-owned and screen-owned WillowUI window layers over one scene stack.

- `scenes`: Sole scene stack whose cover, resume, and exit lifecycle is observed.
- `createManager`: Optional factory returning a WillowUI WindowManager; omitted, each layer gets a plain `new WindowManager()`.
- `keyboardHandler`: Optional `(window, input) => boolean` handler for a focused window group.
- `widgetFocus`: Optional WillowUI FocusManager used for widget focus inside the selected window.

```ts
sceneWindows(scene: any): WindowManager
```
Returns the WillowUI manager owned by one scene, creating its empty layer when first requested.

- `scene`: Scene that owns the layer.
- Returns: Per-scene WillowUI WindowManager.

```ts
openSceneWindow(scene: any, window: Window): Window
```
Adds a WillowUI window to its owning scene layer. Floating windows start unfocused; a modal focuses automatically through WillowUI and the resolver.

- `scene`: Active or covered scene that owns the window.
- `window`: WillowUI window to add.
- Returns: The supplied window.

```ts
openScreenWindow(window: Window): Window
```
Adds a persistent WillowUI window above the complete scene stack.

- `window`: WillowUI window to add.
- Returns: The supplied window.

```ts
closeWindow(window: Window): boolean
```
Removes a window from whichever GameKit layer owns it without disposing the WillowUI object.

- `window`: Window to detach from its manager.
- Returns: True when a layer owned the window.

```ts
get focusedWindow(): Window | null
```
Returns the focused WillowUI window, or null while the scene owns focus.

```ts
get isFocused(): boolean
```
Reports whether a window layer, rather than the top scene, owns focus.

```ts
activateFocus(): void
```
Resolves the highest-priority window group and gives it focus when one exists.

```ts
blur(): void
```
Clears focus from every WindowManager while retaining all layer membership.

```ts
clickWindow(window: Window): void
```
Focuses a floating or modal window after pointer interaction.

- `window`: Window clicked by the user.
- Throws: Error when the window does not belong to this layer.

```ts
clickScene(): void
```
Returns focus to the top scene and blurs all floating windows.

```ts
handleInput(input: any): boolean
```
Offers keyboard input to the focused window or, when none is focused, the top scene.

- `input`: Caller-defined keyboard value.
- Returns: True when the selected focus group handled the value.

```ts
dispatchKeyboard(input: any): boolean
```
Convenience alias for offering keyboard input to the resolved application focus group.

- `input`: Caller-defined keyboard value.
- Returns: True when handled.

```ts
dispose(): void
```
Releases observer registration and removes all windows from GameKit-owned managers.

---

URL: https://thicketscript.com/gamekit/reference/willow

# willow family

Presentation bindings from game records to willow nodes, and the pointer and key input bridge.

Import these from `gamekit/src/willow` (a few are also re-exported by the package root, as noted on each).

15 symbols, 0 of them also in the package root.

| Symbol | Summary |
|---|---|
| [`WillowBinding`](#willowbinding) | *class*. Coordinates the WillowBinding presentation resource and its lifetime. |
| [`WillowBindingTicket`](#willowbindingticket) | *class*. Coordinates the WillowBindingTicket presentation resource and its lifetime. |
| [`WillowInputBridge`](#willowinputbridge) | *class*. Adapts Willow pointer samples into explicit game-owned input offers. |
| [`WillowInputConsumer`](#willowinputconsumer) | *enum*. Defines the closed willow input consumer value set. |
| [`WillowInputFrame`](#willowinputframe) | *class*. Carries WillowInputFrame state across the presentation-to-game boundary. |
| [`WillowInputInspection`](#willowinputinspection) | *class*. Carries WillowInputInspection state across the presentation-to-game boundary. |
| [`WillowInputOwner`](#willowinputowner) | *class*. Carries WillowInputOwner state across the presentation-to-game boundary. |
| [`WillowInputTarget`](#willowinputtarget) | *class*. Carries WillowInputTarget state across the presentation-to-game boundary. |
| [`WillowKeySample`](#willowkeysample) | *class*. Represents the runtime willow key sample value and its explicit state. |
| [`WillowPointerPhase`](#willowpointerphase) | *enum*. Defines the closed willow pointer phase value set. |
| [`WillowPointerSample`](#willowpointersample) | *class*. Represents the runtime willow pointer sample value and its explicit state. |
| [`WillowPresentation`](#willowpresentation) | *class*. Coordinates the WillowPresentation presentation resource and its lifetime. |
| [`WillowPresentationAdapter`](#willowpresentationadapter) | *class*. Coordinates the WillowPresentationAdapter presentation resource and its lifetime. |
| [`WillowPresentationState`](#willowpresentationstate) | *class*. Coordinates the WillowPresentationState presentation resource and its lifetime. |
| [`WillowViewport`](#willowviewport) | *class*. Represents the runtime willow viewport value and its explicit state. |

## WillowBinding

```ts
import { WillowBinding } from "gamekit/src/willow";
class WillowBinding<T>
```

Coordinates the WillowBinding presentation resource and its lifetime.

**Members**

```ts
constructor(adapter: any, record: T)
```
Initializes a willow binding with explicit dependencies.

- `adapter`: Presentation adapter that creates and synchronizes the Willow node.
- `record`: Initial game record retained until replacement, pooling, or disposal.

```ts
get active(): boolean
```
Reports whether the binding participates in the next presentation pass.

- Returns: True only in the active lifecycle state.

```ts
get detached(): boolean
```
Reports whether the binding retains a node that has been removed from its parent.

- Returns: True only after `detach` and before `attach` or another terminal transition.

```ts
get pooled(): boolean
```
Reports whether the binding retains a detached node but no game record.

- Returns: True only after `pool` and before `reuse` or disposal.

```ts
get disposed(): boolean
```
Reports whether the binding has permanently released its node and record.

- Returns: True after `dispose`; the state never becomes live again.

```ts
get generation(): int
```
Exposes the revision used to invalidate asynchronous tickets.

- Returns: A monotonically increasing revision changed by each lifecycle mutation.

```ts
ticket(): WillowBindingTicket<T>
```
Captures the current generation for guarded asynchronous completion.

- Returns: A ticket that applies callbacks only while this binding remains active at that generation.

```ts
detach(): void
```
Removes the node from Willow while retaining it for a later attach.

- Throws: Error When called on a pooled binding.

```ts
attach(): void
```
Reactivates a detached binding; the next presentation pass reparents its node.

- Throws: Error Unless the binding is detached and not disposed.

```ts
pool(): void
```
Detaches the node, clears the record, and invalidates all outstanding tickets.

```ts
reuse(record: T): void
```
Reactivates a pooled node for a new record and generation.

- `record`: New record synchronized on the next presentation pass.
- Throws: Error Unless the binding is pooled and not disposed.

```ts
replace(record: T): void
```
Invalidates tickets and disposes the current node before adopting a replacement record.

- `record`: Replacement record whose node is created on the next presentation pass.
- Throws: Error When the binding is pooled or disposed.

```ts
dispose(): void
```
Permanently releases the record and owned node; repeated calls do nothing.

## WillowBindingTicket

```ts
import { WillowBindingTicket } from "gamekit/src/willow";
class WillowBindingTicket<T>
```

Coordinates the WillowBindingTicket presentation resource and its lifetime.

**Members**

```ts
constructor(binding: any, generation: int)
```
Initializes a willow binding ticket with explicit dependencies.

- `binding`: Binding consulted when asynchronous work completes.
- `generation`: Binding revision captured before that work began.

```ts
apply(callback: Function): boolean
```
Guards a deferred node mutation against lifecycle and record changes.

- `callback`: Function invoked as `(node, record)` only while the captured generation is live.
- Returns: True when the callback ran; false when the ticket is stale or its binding is inactive.

## WillowInputBridge

```ts
import { WillowInputBridge } from "gamekit/src/willow";
class WillowInputBridge
```

Adapts Willow pointer samples into explicit game-owned input offers. Retain one bridge per presentation boundary and register targets in explicit priority order; it never owns a simulation World.

**Members**

```ts
constructor(policy: InputPolicy | null = null)
```
Initializes WillowInputBridge with explicit dependencies and configuration.

- `policy`: Optional neutral policy used to build action frames and process focus loss.

```ts
register(target: WillowInputTarget): void
```
Adds a registration and rejects a duplicate live identity.

- `target`: Target retained until explicitly unregistered.
- Throws: Error When its id or priority is already registered, or its viewport is unknown.

```ts
unregister(id: string): boolean
```
Removes a registration and releases any state it owns.

- `id`: Target identifier to remove.
- Returns: True when a target was removed; false when no registration matched.

```ts
addViewport(viewport: WillowViewport): void
```
Registers a viewport for pointer projection and overlap selection.

- `viewport`: Viewport retained until the bridge is released.
- Throws: Error When its id or priority is already registered.

```ts
pointer(sample: WillowPointerSample): WillowInputFrame
```
Routes one pointer sample to the highest eligible target and maintains capture. A DOWN sample captures its selected owner until UP or focus loss, so later samples cannot retarget mid-gesture.

- `sample`: Willow-normalized pointer fact for this presentation frame.
- Returns: Owner and offers for the selected target plus the neutral button sample.

```ts
actionFrame(): ActionFrame | null
```
Builds a policy-resolved action frame from the core `InputMap` when a policy is configured.

- Returns: The policy-resolved frame, or null when the bridge has no policy.

```ts
focusLost(): ActionFrame | null
```
Cancels active captures and forwards focus loss to the input policy.

- Returns: The policy's focus-loss frame, or null when no policy is configured.

```ts
drainCancelled(): WillowInputOwner[]
```
Returns and clears the queued cancelled interaction owners.

- Returns: Independent snapshots in cancellation order; a second drain is empty.

```ts
inspect(): WillowInputInspection
```
Builds a copy suitable for diagnostic inspection.

- Returns: Capture snapshots and registered ids that can be retained independently.

## WillowInputConsumer

```ts
import { WillowInputConsumer } from "gamekit/src/willow";
enum WillowInputConsumer
```

Defines the closed willow input consumer value set. Store and compare these values directly rather than introducing string aliases;

| Member | Meaning |
|---|---|
| `WORLD = "world"` | Input is offered to world presentation. |
| `UI = "ui"` | Input is offered to ordinary interface controls. |
| `MODAL = "modal"` | Input is offered to a blocking interface layer. |
| `TEXT_ENTRY = "text-entry"` | Input is offered to editable text controls. |
| `DEBUG = "debug"` | Input is offered to diagnostic controls. |

## WillowInputFrame

```ts
import { WillowInputFrame } from "gamekit/src/willow";
class WillowInputFrame
```

Carries WillowInputFrame state across the presentation-to-game boundary.

**Members**

```ts
owner: WillowInputOwner | null
```
Pointer capture owner selected for this frame, or null when no target matched.

```ts
offers: any[]
```
Detached interaction offers returned by the selected target.

```ts
sample: InputSample
```
Neutral input sample derived from the Willow pointer event.

```ts
constructor(owner: WillowInputOwner | null, offers: any[], sample: InputSample)
```
Initializes a willow input frame with explicit dependencies.

- `owner`: Selected pointer capture owner, copied when non-null.
- `offers`: Interaction offers copied into the frame.
- `sample`: Neutral input sample for the current presentation frame.

## WillowInputInspection

```ts
import { WillowInputInspection } from "gamekit/src/willow";
class WillowInputInspection
```

Carries WillowInputInspection state across the presentation-to-game boundary.

**Members**

```ts
owners: WillowInputOwner[]
```
Snapshots of active pointer capture owners.

```ts
targetIds: string[]
```
Registered target identifiers in bridge order.

```ts
viewportIds: string[]
```
Registered viewport identifiers in bridge order.

```ts
constructor(owners: WillowInputOwner[], targetIds: string[], viewportIds: string[])
```
Initializes a willow input inspection with explicit dependencies.

- `owners`: Active capture snapshots prepared by the bridge.
- `targetIds`: Registered target identifiers.
- `viewportIds`: Registered viewport identifiers.

## WillowInputOwner

```ts
import { WillowInputOwner } from "gamekit/src/willow";
class WillowInputOwner
```

Carries WillowInputOwner state across the presentation-to-game boundary.

**Members**

```ts
pointerId: int
```
Pointer identifier retained for the full capture lifetime.

```ts
targetId: string
```
Identifier of the target that won capture.

```ts
consumer: WillowInputConsumer
```
Consumer notified for this captured interaction.

```ts
screen: Vec2
```
Most recent pointer position in screen coordinates.

```ts
world: Vec2 | null
```
Most recent camera-projected position, or null outside a viewport.

```ts
viewportId: string | null
```
Viewport used for world projection, or null when none matched.

```ts
cancelled: boolean
```
WillowInputOwner: whether this interaction ended through cancellation.

```ts
constructor(pointerId: int, targetId: string, consumer: WillowInputConsumer, screen: Vec2, world: Vec2 | null, viewportId: string | null, cancelled: boolean = false)
```
Initializes a willow input owner with explicit dependencies.

- `pointerId`: Pointer identifier whose capture is represented.
- `targetId`: Identifier of the target that won capture.
- `consumer`: Recipient for interaction callbacks.
- `screen`: Pointer position in screen coordinates; copied on construction.
- `world`: Projected world position, or null; copied when present.
- `viewportId`: Viewport used for projection, or null.
- `cancelled`: True when focus loss cancelled the interaction.

```ts
copy(): WillowInputOwner
```
Returns a snapshot with independent coordinate values.

- Returns: A copy retaining the same consumer reference and capture facts.

## WillowInputTarget

```ts
import { WillowInputTarget } from "gamekit/src/willow";
class WillowInputTarget
```

Carries WillowInputTarget state across the presentation-to-game boundary.

**Members**

```ts
id: string
```
Unique identifier used for registration and capture ownership.

```ts
consumer: WillowInputConsumer
```
Consumer that receives interactions selected for this target.

```ts
node: any
```
Willow node whose hit-test ancestry makes a sample eligible; null matches globally.

```ts
priority: int
```
Explicit ordering priority; larger values win conflicts.

```ts
viewportId: string | null
```
Viewport used to project matching pointer coordinates, or null.

```ts
constructor(id: string, consumer: WillowInputConsumer, node: any, priority: int, viewportId: string | null = null, offersFor: Function | null = null)
```
Initializes a willow input target with explicit dependencies.

- `id`: Non-empty registration and capture identifier.
- `consumer`: Recipient for interactions selected for the target.
- `node`: Willow hit-test node, or null to match every sample.
- `priority`: Selection priority; larger values win.
- `viewportId`: Optional viewport for world-coordinate projection.
- `offersFor`: Optional callback returning offers for a newly captured owner.
- Throws: Error When `id` is empty.

```ts
matches(sample: WillowPointerSample): boolean
```
WillowInputTarget Tests whether the sample is eligible for this target.

- `sample`: Pointer sample carrying the Willow hit ancestry.
- Returns: True for a global target or when `node` appears in the hit ancestry.

```ts
offers(owner: WillowInputOwner): any[]
```
Evaluates the optional offer factory for a captured interaction.

- `owner`: Snapshot passed to the offer factory.
- Returns: A detached offer list, or an empty list when no offers are available.

## WillowKeySample

```ts
import { WillowKeySample } from "gamekit/src/willow";
class WillowKeySample
```

Represents the runtime willow key sample value and its explicit state.

**Members**

```ts
control: string
```
Neutral control name, conventionally `Key.<keyCode>` for Willow events.

```ts
down: boolean
```
True for key-down and false for key-up.

```ts
repeating: boolean
```
True when Willow marks the key event as an auto-repeat.

```ts
constructor(control: string, down: boolean, repeating: boolean = false)
```
Initializes a willow key sample with explicit dependencies.

- `control`: Non-empty neutral control name.
- `down`: True for press and false for release.
- `repeating`: Whether this is an auto-repeat event.
- Throws: Error When `control` is empty.

```ts
inputSample(): InputSample
```
Converts the key fact to the neutral input representation.

- Returns: A keyboard sample with value 1 for down or 0 for up.

```ts
static fromWillow(event: any, down: boolean): WillowKeySample
```
Adapts a Willow key event without retaining the event object.

- `event`: Willow event exposing `keyCode` and `repeat`.
- `down`: True for a key-down callback and false for key-up.
- Returns: A sample named from the Willow key code.

## WillowPointerPhase

```ts
import { WillowPointerPhase } from "gamekit/src/willow";
enum WillowPointerPhase
```

Defines the closed willow pointer phase value set. Store and compare these values directly rather than introducing string aliases;

| Member | Meaning |
|---|---|
| `DOWN = "down"` | The pointer began contact. |
| `MOVE = "move"` | The pointer moved while tracked. |
| `UP = "up"` | The pointer ended contact. |

## WillowPointerSample

```ts
import { WillowPointerSample } from "gamekit/src/willow";
class WillowPointerSample
```

Represents the runtime willow pointer sample value and its explicit state.

**Members**

```ts
pointerId: int
```
Pointer identity used to maintain capture across event phases.

```ts
phase: WillowPointerPhase
```
Current down, move, or up phase.

```ts
screen: Vec2
```
Pointer position in Willow screen coordinates.

```ts
button: int
```
Willow button number associated with the event.

```ts
hit: any
```
Primary Willow hit target, or null when nothing was hit.

```ts
hits: any[]
```
Hit-test ancestry used to select eligible input targets.

```ts
constructor(pointerId: int, phase: WillowPointerPhase, screenX: float, screenY: float, button: int = 0, hit: any = null, hits: any[] = [])
```
Initializes a willow pointer sample with explicit dependencies.

- `pointerId`: Pointer identity retained through capture.
- `phase`: Current pointer event phase.
- `screenX`: Horizontal screen coordinate.
- `screenY`: Vertical screen coordinate.
- `button`: Willow button number.
- `hit`: Primary hit target, inserted into `hits` when absent.
- `hits`: Hit ancestry copied into the sample.

```ts
static fromWillow(event: any, phase: WillowPointerPhase, hits: any[] = []): WillowPointerSample
```
Adapts Willow pointer coordinates, button, and target without retaining the event.

- `event`: Willow event exposing `screenX`, `screenY`, `button`, and `target`. The screen position is kept raw, because the bridge converts it to world through the viewport camera exactly once.
- `phase`: Phase assigned by the callback that received the event.
- `hits`: Hit ancestry supplied by the game integration.
- Returns: A pointer-zero sample containing copies of the supplied hit list.

```ts
inputSample(): InputSample
```
Converts the pointer button phase to the neutral input representation.

- Returns: A device-specific button sample with value 0 on up and 1 otherwise.

## WillowPresentation

```ts
import { WillowPresentation } from "gamekit/src/willow";
class WillowPresentation<T>
```

Coordinates the WillowPresentation presentation resource and its lifetime.

**Members**

```ts
constructor(adapter: WillowPresentationAdapter<T>, record: T)
```
Initializes a willow presentation with explicit dependencies.

- `adapter`: Adapter that owns bindings and presentation passes.
- `record`: Initial game record represented by the component.

```ts
onAttach(owner: Entity): void
```
Creates, reattaches, or reuses the binding when the component enters an entity.

- `owner`: Entity receiving the component; ownership itself remains with the ECS.

```ts
onDetach(owner: Entity): void
```
Detaches the Willow node while preserving it for a later entity transfer.

- `owner`: Entity releasing the component.

```ts
onDispose(owner: Entity): void
```
Permanently disposes the binding when the owning entity is torn down.

- `owner`: Entity whose component lifetime has ended.

```ts
replace(record: T): void
```
Replaces the game record and invalidates any node created for the previous record.

- `record`: Record to present on the next adapter pass.

```ts
ticket(): WillowBindingTicket<T>
```
Captures the attached binding generation for guarded asynchronous work.

- Returns: A ticket tied to the current record and lifecycle revision.
- Throws: Error Before the component has attached to an entity.

## WillowPresentationAdapter

```ts
import { WillowPresentationAdapter } from "gamekit/src/willow";
class WillowPresentationAdapter<T>
```

Coordinates the WillowPresentationAdapter presentation resource and its lifetime.

**Members**

```ts
constructor(createNode: Function, readState: Function, syncNode: Function | null = null)
```
Initializes a willow presentation adapter with explicit dependencies.

- `createNode`: Factory called with a record when an active binding has no node.
- `readState`: Callback returning transform and parent state for each presented record.
- `syncNode`: Optional callback for content synchronization after transform state is copied.

```ts
get disposed(): boolean
```
Reports whether all bindings have been disposed and future binds are forbidden.

- Returns: True after the first call to `dispose`.

```ts
bind(record: T): WillowBinding<T>
```
Associates supplied records with the caller's presentation factory.

- `record`: Game record retained by the new binding.
- Returns: An active binding whose node is created at the next presentation boundary.
- Throws: Error After the adapter has been disposed.

```ts
present(): void
```
Presents a snapshot of current bindings and then forgets disposed entries.

```ts
dispose(): void
```
WillowPresentationAdapter Releases retained resources and makes later use invalid.

- Throws: Error When the supplied value violates this operation’s preconditions.

## WillowPresentationState

```ts
import { WillowPresentationState } from "gamekit/src/willow";
class WillowPresentationState
```

Coordinates the WillowPresentationState presentation resource and its lifetime.

**Members**

```ts
parent: any
```
Willow container that should own the presented node.

```ts
x: float = 0.0
```
Horizontal position in parent coordinates.

```ts
y: float = 0.0
```
Vertical position in parent coordinates.

```ts
rotation: float = 0.0
```
Node rotation forwarded to Willow.

```ts
scaleX: float = 1.0
```
Horizontal scale factor; defaults to 1.

```ts
scaleY: float = 1.0
```
Vertical scale factor; defaults to 1.

```ts
pivotX: float = 0.0
```
Horizontal transform pivot in node coordinates.

```ts
pivotY: float = 0.0
```
Vertical transform pivot in node coordinates.

```ts
skewX: float = 0.0
```
Horizontal skew forwarded to Willow.

```ts
skewY: float = 0.0
```
Vertical skew forwarded to Willow.

```ts
alpha: float = 1.0
```
Opacity forwarded to Willow; defaults to fully opaque.

```ts
visible: boolean = true
```
Whether Willow should render the node.

```ts
zOrder: int = 0
```
Sibling ordering value forwarded to Willow.

```ts
constructor(parent: any)
```
Initializes a willow presentation state with explicit dependencies.

- `parent`: Willow container that receives the node during presentation.

## WillowViewport

```ts
import { WillowViewport } from "gamekit/src/willow";
class WillowViewport
```

Represents the runtime willow viewport value and its explicit state.

**Members**

```ts
id: string
```
Unique identifier referenced by input targets and capture owners.

```ts
screen: Rect
```
Screen-space rectangle in which this viewport participates.

```ts
camera: Camera2D
```
Camera used to project matching screen coordinates into world space.

```ts
priority: int
```
Explicit ordering priority; larger values win conflicts.

```ts
constructor(id: string, screen: Rect, camera: Camera2D, priority: int)
```
Initializes a willow viewport with explicit dependencies.

- `id`: Non-empty viewport identifier.
- `screen`: Screen-space bounds copied into the viewport.
- `camera`: Camera retained for coordinate projection.
- `priority`: Selection priority; larger values win overlaps.
- Throws: Error When `id` is empty.

```ts
contains(point: Vec2): boolean
```
Tests a point against the inclusive screen-space bounds.

- `point`: Screen-space coordinate to test.
- Returns: True when both coordinates lie on or inside the rectangle edges.