# bworld mods specification

Status: **draft, format_version 1**. Nothing here is implemented yet, see [Implementation plan](#implementation-plan).

Mods add blocks, items, textures, recipes, world generation, game logic and GUIs to bworld. A mod is installed **on the
server**. Players who join download its client code, data and textures from the server automatically, so they don't
install anything themselves. bworld is always played on a server; there is no single player mode.

This borrows from Minecraft Bedrock add-ons: data lives in JSON, blocks get behavior from named custom components, and
scripts use before/after events. Bedrock servers also push resource packs to joining players, and their server scripts
can show forms that the client draws (`@minecraft/server-ui`). bworld goes one step further and pushes client _scripts_
too, since the client is already a web page.

## Contents

- [Overview](#overview)
- [Creating a mod](#creating-a-mod)
- [Mod layout](#mod-layout)
- [manifest.json](#manifestjson)
- [Identifiers](#identifiers)
- [Textures](#textures)
- [Blocks](#blocks)
- [Items](#items)
- [Recipes](#recipes)
- [Server scripts](#server-scripts)
- [Client scripts](#client-scripts)
- [GUIs](#guis)
- [Mod channels](#mod-channels)
- [World generation](#world-generation)
- [Delivery to clients](#delivery-to-clients)
- [Security](#security)
- [Example mod](#example-mod)
- [The base game as a mod](#the-base-game-as-a-mod)
- [Implementation plan](#implementation-plan)
- [Open questions](#open-questions)

## Overview

A mod can have up to three scripts, each running in a different place:

| Script     | Runs on                         | Sent to clients | Owns                                                                           |
| ---------- | ------------------------------- | --------------- | ------------------------------------------------------------------------------ |
| `server`   | the server, in a worker         | **never**       | game logic: block components, ticking, tile data, containers, commands, events |
| `client`   | every client, main thread       | yes             | presentation: custom screens, HUD, keybinds                                    |
| `worldgen` | server and client chunk workers | yes             | terrain features, must be deterministic                                        |

The mod's JSON data and textures go to both sides.

**The server is the authority.** Clients send what the player is trying to do ("break the block at x, y, z", "click slot
3"). The server checks it, runs mod logic and sends back what happened. For responsiveness, clients show the expected
result of breaking and placing immediately, and the server sends a correction if it disagrees.

```
            server process                                     browser
┌───────────────────────────────────────┐          ┌──────────────────────────────────┐
│ host: http, websocket, files          │          │ game client (rendering, input)   │
│ ┌───────────────────────────────────┐ │  ws      │   + mod client scripts           │
│ │ game server worker                │◄├──────────┤►  (screens, HUD, keybinds)       │
│ │   world, inventories, tile data   │ │ protocol │                                  │
│ │   + mod server scripts            │ │          │ chunk workers                    │
│ └───────────────────────────────────┘ │          │   + mod worldgen scripts         │
│ chunk workers + mod worldgen scripts  │          └──────────────────────────────────┘
└───────────────────────────────────────┘
```

Moving from the current setup to this is a big change, see the [Implementation plan](#implementation-plan). Right now
the server only relays block changes and doesn't know about blocks, inventories or terrain.

## Creating a mod

```sh
deno task new-mod copper_tools "Copper Tools"   # copies templates/mod to mods/copper_tools
deno task check-mods                            # validates every mod in mods/
```

The template has one of everything: a block with a custom component, an item, a shaped recipe, textures, and all three
scripts. `check-mods` checks manifests and data files against this spec, checks that every id, item and texture a mod
refers to exists (and that it depends on the mods those come from), and typechecks scripts against the API types in
`common/mod_api/`, which scripts import as `bworld/server`, `bworld/client` and `bworld/worldgen`. Folders in `mods/`
starting with `_` or `.` are ignored.

`deno task build` builds every mod in `mods/` and fails if any has errors; `deno task server` then loads them. What
works so far is listed in the [Implementation plan](#implementation-plan).

## Mod layout

```
mods/
  copper_tools/
    manifest.json
    blocks/*.json
    items/*.json
    recipes/*.json
    worldgen/ores.json
    textures/*.png
    scripts/
      server.ts        # game logic, stays on the server
      client.ts        # sent to players
      worldgen.ts      # sent to players, also runs on the server
      shared/          # anything both sides import, bundled into each
```

Only `manifest.json` is required. Data folders can have subfolders, with one definition per file.

## manifest.json

```json
{
	"format_version": 1,
	"id": "copper_tools",
	"name": "Copper Tools",
	"description": "Copper blocks, a copper pickaxe and a smelter with its own screen.",
	"version": "1.0.0",
	"authors": ["paula"],
	"game_version": ">=0.1.0",
	"dependencies": [
		{ "id": "more_ores", "version": "^2.0.0" }
	],
	"scripts": {
		"server": "scripts/server.ts",
		"client": "scripts/client.ts",
		"worldgen": "scripts/worldgen.ts"
	}
}
```

| Field              | Required | Meaning                                                                                   |
| ------------------ | -------- | ----------------------------------------------------------------------------------------- |
| `format_version`   | yes      | Version of this spec the mod targets. Loaders reject versions they don't know.            |
| `id`               | yes      | The mod's namespace, see [Identifiers](#identifiers). Must match the folder name.         |
| `name`             | yes      | Display name, shown to players when joining.                                              |
| `description`      | no       | One or two sentences.                                                                     |
| `version`          | yes      | Semver of the mod itself.                                                                 |
| `authors`          | no       | List of names.                                                                            |
| `game_version`     | no       | Semver range of bworld versions the mod works with.                                       |
| `dependencies`     | no       | Other mods by `id`, with a semver range. Missing or mismatched dependencies fail loading. |
| `scripts.server`   | no       | Server entry. Never sent to clients.                                                      |
| `scripts.client`   | no       | Client entry, sent to every player.                                                       |
| `scripts.worldgen` | no       | Worldgen entry, sent to every player and also run on the server.                          |
| `credits`          | no       | A markdown file in the mod, shown on the Credits screen. For asset licenses and thanks.   |

Scripts can be `.js` or `.ts`. The build bundles each entry separately into one ES module. Code imported by both the
server and client entries is copied into both bundles, so **don't import secrets into shared code**. Anything the client
bundle imports is visible to players.

## Identifiers

Everything a mod registers has an id of the form `namespace:name`:

- `namespace` is the mod's `id`. It must match `^[a-z0-9_]+$` and be at most 32 characters.
- Two namespaces are reserved. `bworld` belongs to the base game mod shipped in `mods/bworld` (see
  [The base game as a mod](#the-base-game-as-a-mod)). `engine` belongs to the engine itself, for things every game
  needs, like the block-breaking cracks. The one exception is `bworld:air`: it's the engine's empty block, but it keeps
  that id because every save already contains it.
- `name` must match `^[a-z0-9_]+$`.
- A mod only registers ids in its own namespace: blocks, items, components, screens, channels and HUD elements. It can
  _refer to_ any id.
- Registering an id that already exists is a load error.

Blocks get a numeric id when they register, and chunk data stores those numbers. Numeric ids are **local to one running
program**, so the server and each client can number blocks differently. Saves and the network always use string ids.

## Textures

- Every `.png` in `textures/` becomes a texture with id `<mod_id>:<file name without .png>`. Subfolders are joined with
  `_`, so `textures/ores/tin.png` becomes `<mod_id>:ores_tin`.
- Textures are 16×16. The server's build puts every installed mod's textures into one atlas with the base game's, and
  clients download that atlas instead of using their own.
- A missing texture shows the magenta and black checker (`engine:missing`) and logs a warning. It isn't a load error.
- The engine's own textures use the `engine` namespace: `engine:missing` and the breaking cracks `engine:break_0` to
  `engine:break_8`. They come from `assets/`, not from a mod.

## Blocks

`blocks/copper_block.json`:

```json
{
	"format_version": 1,
	"block": {
		"id": "copper_tools:copper_block",
		"textures": "copper_tools:copper_block",
		"collision": true,
		"mining": { "toughness": 5, "tool": "pickaxe", "requires_tool": true },
		"drops": "copper_tools:copper_block",
		"item": true,
		"components": {
			"copper_tools:oxidizes": { "seconds": 600, "into": "copper_tools:oxidized_copper_block" }
		}
	}
}
```

| Field                  | Default     | Maps to `BlockRegistry` | Meaning                                                                                      |
| ---------------------- | ----------- | ----------------------- | -------------------------------------------------------------------------------------------- |
| `id`                   | required    | `id`                    | The block's id.                                                                              |
| `textures`             | required    | `textures`              | One texture id, `{ top, bottom, side }` or `{ front, side }`.                                |
| `render_layer`         | `solid`     | `render_layer`          | `solid`, `cutout` (texels fully opaque or fully clear, like leaves) or `translucent` (blended, like water and glass). Non-solid blocks don't hide their neighbors' faces. |
| `cull_same`            | see meaning | `cull_same`             | Hide faces between two of this block. Defaults to `true` for translucent blocks, `false` otherwise. |
| `light_emission`       | `0`         | `light_emission`        | Light level 0-15 it gives off, like a torch (14). |
| `light_opacity`        | see meaning | `light_opacity`         | How much light passing through it loses, 0-15. Defaults to `15` (blocks all light) for solid blocks and `0` otherwise. Leaves and water use `1`. |
| `alpha`                | `1`         | `alpha`                 | Opacity for translucent blocks.                                                              |
| `collision`            | `true`      | `has_collision`         | Whether entities collide with it.                                                            |
| `mining.toughness`     | unbreakable | `toughness`             | Seconds to break by hand. A matching tool is 2× faster.                                      |
| `mining.tool`          | none        | `tool_to_break`         | Tool type that speeds it up, like `pickaxe`, `axe` or `shovel`.                              |
| `mining.requires_tool` | `false`     | `requires_tool`         | Only drops when broken with `mining.tool`.                                                   |
| `drops`                | nothing     | `drop_table`            | Item id dropped on the ground when broken, for players to pick up.                           |
| `item`                 | `true`      | `register_block_item`   | Also register an item that places this block, with the same id.                              |
| `interactive`          | `false`     | `interactive`           | Right clicking it does something (opens a screen), so clients don't guess it places a block. |
| `replaceable`          | `false`     | new                     | Placing a block into it replaces it, like water.                                             |
| `states`               | none        | `states`                | Up to 16 bits of named state, like `hoed_dirt` has now.                                      |
| `components`           | none        | the `on_*` hooks        | Custom components with parameters, handled by server scripts.                                |

The client needs this data too (for meshing, mining time and collision), so it's sent to every player. It can't contain
functions.

Block states are declared like `[{ "name": "facing", "bits": 2, "default": 0 }]`, at most 16 bits in total. A block
starts with its defaults when it's placed or generated, and server scripts read and change them with
`ctx.world.get_state` / `set_state`. States are saved with the world and synced to players. They can't change textures
yet, because the mesher ignores them. `variants` is reserved for that.

## Items

`items/copper_pickaxe.json`:

```json
{
	"format_version": 1,
	"item": {
		"id": "copper_tools:copper_pickaxe",
		"texture": "copper_tools:copper_pickaxe",
		"tool": "pickaxe",
		"max_stack": 1,
		"lore": "Better than wood, worse than iron.",
		"components": { "copper_tools:durability": { "max": 250 } }
	}
}
```

| Field        | Default  | Maps to `ItemRegistry`   | Meaning                                            |
| ------------ | -------- | ------------------------ | -------------------------------------------------- |
| `id`         | required | registry key             | The item's id.                                     |
| `texture`    | required | `texture_id`             | Texture id.                                        |
| `tool`       | none     | `tool_type`              | Tool type used by blocks' `mining.tool`.           |
| `places`     | none     | `block_id`               | Block placed when used on a block face.            |
| `max_stack`  | `64`     | new                      | Largest stack size.                                |
| `lore`       | none     | `get_lore`               | Static tooltip text.                               |
| `components` | none     | `on_create` / `get_lore` | Custom item components, handled by server scripts. |

Item stacks can carry `data`, a JSON value set by the server (like the watering can's water level). It's synced to
clients as part of the container it's in, so client screens can show it.

## Recipes

`recipes/smelt_copper_block.json`:

```json
{
	"format_version": 1,
	"recipe": {
		"type": "furnace",
		"input": "copper_tools:copper_block",
		"output": { "id": "bworld:copper_ingot", "count": 9 },
		"cook_time": 400
	}
}
```

| `type`    | Fields                                                                             | Notes                                                                        |
| --------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `shaped`  | `pattern` rows (space is empty), `key` letter to item id, `result` `{ id, count }` | Fits anywhere in the 3×3 grid, like the recipes in `server/game/crafting.ts` |
| `furnace` | `input` item id, `output` `{ id, count }`, `cook_time` in ticks                    | Same as `FURNACE_RECIPES` in `server/game/blocks.ts`                         |
| `fuel`    | `item` id, `burn_time` in ticks                                                    | Same as `FUEL_VALUES` in `server/game/blocks.ts`                             |

A shaped recipe, for the crafting grid in the player's inventory screen:

```json
{
	"format_version": 1,
	"recipe": {
		"type": "shaped",
		"pattern": ["PPP", "P P", "PPP"],
		"key": { "P": "bworld:planks" },
		"result": { "id": "bworld:chest", "count": 1 }
	}
}
```

Two furnace recipes with the same `input`, or two shaped recipes with the same pattern and key, are a load error. Server
scripts can also register recipe types of their own through `ctx.recipes`.

## Server scripts

`scripts.server` exports `setup`, called once when the server starts:

```ts
import type { ServerContext } from "bworld/server";

export function setup(ctx: ServerContext) {
	// register components, commands, containers, event handlers
}
```

Server scripts run in the game server worker with **no Deno permissions** (see [Security](#security)). They get the mod
API and standard JavaScript, but no file, network or subprocess access; persistent state goes through `ctx.storage`.

```ts
interface ServerContext {
	mod: { id: string; version: string };
	components: ComponentRegistry; // only during setup
	commands: CommandRegistry; // only during setup
	events: { before: ServerBeforeEvents; after: ServerAfterEvents };
	system: System;
	world: ServerWorld;
	players: PlayerList;
	containers: ContainerApi;
	recipes: RecipeApi;
	ui: ServerUi; // see GUIs
	net: ServerNet; // see Mod channels
	storage: ModStorage;
	log(...args: unknown[]): void;
}
```

### Block and item components

Blocks and items get behavior from components registered here:

```ts
ctx.components.register_block("copper_tools:oxidizes", {
	on_create(block) {
		block.data = { age: 0 };
	},
	on_second(block, params, dt) {
		block.data.age += dt;
		if (block.data.age >= params.seconds) {
			ctx.world.set_block(block.x, block.y, block.z, params.into);
		}
	},
});
```

| Handler                              | Called when                               | Return value                               |
| ------------------------------------ | ----------------------------------------- | ------------------------------------------ |
| `on_create(block, params)`           | The block is placed or set.               | ignored                                    |
| `on_break(block, params, player?)`   | The block is broken or replaced.          | ignored                                    |
| `on_click(block, params, player)`    | A player starts hitting it.               | ignored                                    |
| `on_interact(block, params, player)` | A player right clicks it.                 | `true` if handled, so no block gets placed |
| `on_tick(block, params, dt)`         | Every tick (20 per second) near a player. | ignored                                    |
| `on_second(block, params, dt)`       | Every second near a player.               | ignored                                    |

`block` is `{ id, x, y, z, data }`. `data` is tile data: any JSON value, `undefined` until a handler sets it, saved with
the world and **never sent to clients**. To show tile data to a player, open a screen with it (see [GUIs](#guis)).
`on_tick` and `on_second` only run for blocks that have tile data, so a component that ticks from the start sets
`block.data` in `on_create`. They run within 6 chunks of a player. `dt` is in seconds: 0.05 for `on_tick`, 1 for
`on_second`.

The server runs a fixed 20 ticks per second. When a tick takes too long, the next ones run back to back until it has
caught up, so game time keeps pace with real time. When it's more than ten ticks behind it skips the rest and logs a
warning. `/tps` shows how it's doing. Timers (`ctx.system`) count these ticks.

When a block lists several components, each handler runs in the listed order. `on_interact` counts as handled if any
component returns `true`.

Item components use
`ctx.components.register_item(id, { on_create(item, params), get_lore(item, params), on_use(item,
params, player) })`.
`on_use` runs when a player right clicks while holding the item, both at nothing and at a block. At a block, the block's
own interaction comes first, and an item with `on_use` is used instead of being placed.

### Events

**Before events** fire before something happens. Handlers can read and change the event, or set `cancel = true` to stop
it. They can't change the world themselves; use the after event or `system.run_timeout(fn, 0)` for that. **After
events** fire once it has happened.

| Event            | before | after | Payload                                                  |
| ---------------- | ------ | ----- | -------------------------------------------------------- |
| `block_break`    | ✓      | ✓     | `player`, `block`, `item`                                |
| `block_place`    | ✓      | ✓     | `player`, `block`, `face`, `item`                        |
| `block_interact` | ✓      | ✓     | `player`, `block`, `item`                                |
| `chat_send`      | ✓      | ✓     | `player`, `message` (before events can change `message`) |
| `player_join`    |        | ✓     | `player`                                                 |
| `player_leave`   |        | ✓     | `player`                                                 |
| `server_start`   |        | ✓     | none                                                     |
| `tick`           |        | ✓     | `dt` in seconds, 20 times per second                     |

These fire for **every** player's actions, because they all go through the server. When a before event cancels a break
or place, the server tells that player's client to undo what it already showed.

### World, players, system, storage

```ts
interface ServerWorld {
	get_block(x: number, y: number, z: number): string | undefined; // undefined when the chunk isn't loaded
	set_block(x: number, y: number, z: number, id: string): boolean; // runs on_break / on_create, synced to everyone
	get_state(x: number, y: number, z: number, name: string): number | undefined;
	set_state(x: number, y: number, z: number, name: string, value: number): boolean;
	get_block_data<T>(x: number, y: number, z: number): T | undefined;
	is_loaded(x: number, z: number): boolean;
	readonly seed: string;
}

interface Player {
	readonly id: string;
	readonly name: string;
	readonly position: { x: number; y: number; z: number };
	readonly inventory: Container; // 36 slots, hotbar is 0-8
	readonly selected_slot: number;
	readonly held_item: ItemStack | undefined;
	// what doesn't fit in the inventory drops at their feet
	give_item(id: string, count?: number, data?: unknown): void;
	send_message(text: string): void;
	teleport(x: number, y: number, z: number): void;
}

interface PlayerList {
	all(): Player[];
	get(id: string): Player | undefined;
	by_name(name: string): Player | undefined;
}

interface System {
	run_timeout(fn: () => void, ticks: number): number;
	run_interval(fn: () => void, ticks: number): number;
	clear_run(handle: number): void;
	readonly current_tick: number;
}

// small key value store per mod, saved with the world
interface ModStorage {
	get<T>(key: string): T | undefined;
	set(key: string, value: unknown): void; // JSON values only
	delete(key: string): void;
}
```

The server loads chunks around every player (its simulation distance) and generates them itself with the same generator
as the clients. Blocks in unloaded chunks can't be read or changed, and don't tick.

### Commands

```ts
ctx.commands.register("heal", {
	description: "Heal yourself",
	usage: "/heal [amount]",
	run(args, player) {
		player.send_message(`healed ${args[0] ?? "all"}`);
	},
});
```

Commands run on the server when a player types `/name` in chat. Two mods using the same name, or a mod using one of the
engine's (`give` and `tps`), is a load error. `/copper_tools:heal` always works as the unambiguous form.

## Client scripts

`scripts.client` exports `setup`, called after the client has downloaded the server's mods and before the world appears:

```ts
import type { ClientContext } from "bworld/client";

export function setup(ctx: ClientContext) {
	// register screens, HUD elements, keybinds, channel handlers
}
```

```ts
interface ClientContext {
	mod: { id: string; version: string };
	ui: ClientUi; // see GUIs
	hud: HudRegistry;
	input: { bind(id: string, default_key: KeyCode, on_press: () => void): void };
	net: ClientNet; // see Mod channels
	player: { readonly name: string; readonly position: { x: number; y: number; z: number } };
	world: { get_block(x: number, y: number, z: number): string | undefined }; // read only, what the client sees
	log(...args: unknown[]): void;
}
```

Client scripts are for presentation. They can't change the world or inventories; they ask the server over a
[mod channel](#mod-channels). Anything they show should be treated as a view of the server's state. Everything in a
client script is visible to players and can be changed by them, so it must not be trusted for anything that matters.

Keybinds registered with `ctx.input.bind` get an id (`copper_tools:open_smelter`) so a future controls menu can rebind
them. They only fire while no screen is open.

## GUIs

There are three ways to show a GUI. They're listed from least code to most. Pick the first one that's enough.

### 1. Forms (server only)

Simple dialogs defined entirely by server code, like Bedrock's `@minecraft/server-ui`. The client draws them with the
game's UI style. No client script is needed.

```ts
const result = await ctx.ui.action_form(player, {
	title: "Teleporter",
	body: "Where to?",
	buttons: [
		{ text: "Spawn", icon: "bworld:compass" },
		{ text: "Home" },
	],
});
if (!result.canceled && result.selection === 0) {
	player.teleport(0, 100, 0);
}

const settings = await ctx.ui.modal_form(player, {
	title: "Smelter settings",
	fields: [
		{ type: "toggle", label: "Auto-eject", default: true },
		{ type: "slider", label: "Speed", min: 1, max: 4, step: 1, default: 1 },
		{ type: "dropdown", label: "Output", options: ["Chest", "Ground"] },
		{ type: "text", label: "Name", placeholder: "smelter", max_length: 32 },
	],
});
// settings.values = [true, 3, 0, "smelter"], checked against the fields before your code sees them
```

| Form           | Shows                          | Resolves with                                           |
| -------------- | ------------------------------ | ------------------------------------------------------- |
| `message_form` | title, body, two buttons       | `{ canceled, selection: 0 \| 1 }`                       |
| `action_form`  | title, body, a list of buttons | `{ canceled, selection: number }`                       |
| `modal_form`   | title, input fields            | `{ canceled, values: (boolean \| number \| string)[] }` |

The promise resolves with `canceled: true` when the player closes the form, disconnects, or another screen replaces it.
The engine checks every response against the form's definition (types, ranges, option counts, text length) before your
code sees it.

### 2. Container screens (server only)

For inventories and machines. The server owns the container's contents and syncs them to every player viewing it. Clicks
go to the server, which applies them. The chest and furnace would be rebuilt this way instead of their hand-written
`GuiChest` / `GuiFurnace` classes.

```ts
ctx.components.register_block("copper_tools:smelter", {
	on_create(block) {
		block.data = { container: ctx.containers.create(3).id, progress: 0 };
	},
	on_interact(block, _params, player) {
		const container = ctx.containers.get(block.data.container)!;
		const screen = ctx.ui.open_container(player, {
			title: "Smelter",
			layout: [
				{ slot: 0, x: 3, y: 0, filter: "smeltable" },
				{ slot: 1, x: 3, y: 2, filter: (item) => ctx.recipes.is_fuel(item.id) },
				{ slot: 2, x: 5, y: 1, output_only: true },
			],
			container,
			player_inventory: true,
			bars: [{ id: "progress", x: 4, y: 1, texture: "bworld:arrow" }],
		});
		screen.set_property("progress", block.data.progress);
		return true;
	},
});
```

- `x` / `y` are in slot units on a grid. The client scales and centers the screen, and draws the player's inventory
  below it when `player_inventory` is true.
- `filter` is a function `(item) => boolean` or one of the built-in filters `"smeltable"` (has a furnace recipe) and
  `"fuel"`. It and `output_only` run **on the server**, so players can't put the wrong items in by editing their client.
- `bars` are progress bars filled from 0 to 1 by `screen.set_property(id, value)`. Properties can also be shown as text
  with `labels: [{ x, y, property }]`.
- The screen handle has `set_property`, `close()` and `on_close(fn)`. Changes to the container (from scripts, hoppers,
  other players) show up for everyone viewing it.

```ts
interface ContainerApi {
	create(size: number): Container; // saved with the world
	get(id: string): Container | undefined;
	delete(id: string): void;
}

interface Container {
	readonly id: string;
	readonly size: number;
	get(slot: number): ItemStack | undefined;
	set(slot: number, item: ItemStack | undefined): void;
	add(item: ItemStack): ItemStack | undefined; // returns what didn't fit
	on_change(fn: (slot: number) => void): () => void;
}
```

### 3. Custom screens (client code)

For anything forms and containers can't do: maps, skill trees, minigames, custom layouts. The client script registers a
screen class, and the server opens it with some props:

```ts
// client.ts
import type { ClientContext, Graphics, ModScreen } from "bworld/client";

export function setup(ctx: ClientContext) {
	ctx.ui.register_screen("copper_tools:smelter_stats", (props) => new SmelterStats(ctx, props));
}

class SmelterStats implements ModScreen {
	constructor(private ctx: ClientContext, private props: { total_smelted: number; top: [string, number][] }) {}

	on_render(g: Graphics) {
		g.panel(g.width / 2 - 200, g.height / 2 - 150, 400, 300);
		g.text(`Smelted: ${this.props.total_smelted}`, g.width / 2 - 180, g.height / 2 - 130, { scale: 2 });
		this.props.top.forEach(([id, count], i) => {
			g.item(id, g.width / 2 - 180, g.height / 2 - 90 + i * 60);
			g.text(`${count}`, g.width / 2 - 110, g.height / 2 - 75 + i * 60);
		});
		if (g.button("Reset", g.width / 2 - 60, g.height / 2 + 100, 120, 32)) {
			this.ctx.net.send("copper_tools:reset_stats", {});
		}
	}

	// the server sent new props for this screen
	on_props(props: SmelterStats["props"]) {
		this.props = props;
	}
}
```

```ts
// server.ts
const screen = ctx.ui.open_screen(player, "copper_tools:smelter_stats", { total_smelted: 42, top: [] });
screen.update({ total_smelted: 43, top: [] }); // calls on_props on the client
screen.on_close(() => ctx.log("closed"));
```

```ts
interface ModScreen {
	on_open?(): void;
	on_tick?(dt: number): void;
	on_render(g: Graphics): void;
	on_props?(props: unknown): void;
	on_close?(): void;
	// return true to keep the screen open when escape is pressed
	on_escape?(): boolean;
}

// immediate mode, like the debug ui, styled with assets/sprites/ui.png
interface Graphics {
	readonly width: number;
	readonly height: number;
	readonly mouse: { x: number; y: number; down: boolean; pressed: boolean };
	rect(x: number, y: number, w: number, h: number, color?: [number, number, number, number]): void;
	panel(x: number, y: number, w: number, h: number): void; // nine slice background
	text(text: string, x: number, y: number, options?: { scale?: number; color?: number[] }): void;
	measure_text(text: string, scale?: number): number;
	texture(id: string, x: number, y: number, w: number, h: number): void; // any atlas texture
	item(id: string, x: number, y: number, count?: number): void;
	clip(x: number, y: number, w: number, h: number, draw: () => void): void;
	button(label: string, x: number, y: number, w: number, h: number): boolean; // true on the frame it's clicked
	text_input(id: string, x: number, y: number, w: number): string;
	slider(id: string, x: number, y: number, w: number, min: number, max: number): number;
	// server synced slots, same behavior as container screens
	slots(container: string, layout: { slot: number; x: number; y: number }[], x: number, y: number): void;
	key_pressed(key: KeyCode): boolean;
}
```

Custom screens can also show server containers. The server passes them in when opening:
`ctx.ui.open_screen(player, id, props, { containers: { input: container } })`, and the screen draws them with
`g.slots("input", layout, x, y)`. Clicks still go to the server and follow the container rules, so a custom screen can't
bypass `filter`.

A client script can also open its own screens with `ctx.ui.open(id, props)`, for things like a settings page that
doesn't involve the server.

### HUD

```ts
ctx.hud.register("copper_tools:heat", {
	on_render(g) {
		g.text(`Heat: ${heat}`, 8, 8);
	},
});
```

HUD elements draw every frame after the world, under open screens. They get their data from mod channels.

## Mod channels

Client and server parts of a mod talk over named channels. Messages are JSON.

```ts
// server.ts
ctx.net.on("copper_tools:reset_stats", (player, _data) => {
	if (!is_admin(player)) return;
	stats.clear();
});
ctx.net.send(player, "copper_tools:heat", { value: 12 });
ctx.net.broadcast("copper_tools:announcement", { text: "the smelter exploded" });

// client.ts
ctx.net.on("copper_tools:heat", (data) => {
	heat = data.value;
});
ctx.net.send("copper_tools:reset_stats", {});
```

- Channel ids are in the mod's namespace. A mod can listen to other mods' channels but only send on its own.
- A message is at most 16 KB of JSON. Each player can send at most 60 mod messages per second in total; the server drops
  anything over that and logs it.
- **Everything a client sends is untrusted.** Check the player's permission, check every field's type and range, and
  never use client data as an item id or amount without validating it.
- Messages to a channel nobody listens to are dropped, with a warning in development builds.
- On the wire this is one protocol message, `{ type: "mod", channel, data }`, in both directions.

## World generation

Chunks are generated from the world seed by chunk workers on **both** the server and every client, and all of them must
produce identical terrain. So worldgen scripts must be **deterministic**.

Each chunk is generated in three passes:

1. **Terrain.** One terrain generator fills in the ground, water and trees.
2. **Ores.** Every mod's `worldgen/ores.json`, in load order.
3. **Features.** Every mod's registered features, in load order.

The world is 256 blocks tall and the sea is at y 64 (`CHUNK_HEIGHT` and `SEA_LEVEL` in `common/constants.ts`). The
base overworld lives in `common/worldgen/` until phase 3 moves it into `mods/bworld`. It works like Minecraft 1.18+ and
the Terralith datapack: continentalness, erosion and weirdness noises feed nested splines that give every column a
height, jaggedness and roughness, a 3D density around that height is sampled on a coarse grid and interpolated, and
caves are cut out of it. On top of that come Terralith-style shapes: terraced plateaus, shattered hills, river valleys
and gorges, jagged peaks and rare sky islands. Its biome ids (`biome_at`) are the keys of `BIOMES` in
`common/worldgen/overworld.ts`, like `bworld:yosemite_cliffs` or `bworld:skylands`. Trees
(`common/worldgen/trees.ts`) are spread out like Poisson disk sampling, never closer than 4 blocks, and each biome sets
how many grow and which kinds. `deno run -A tools/worldgen_preview.ts [seed]` renders it to PNG files.

### Terrain generators

A world uses exactly one terrain generator, registered by a worldgen script. The base game's is `bworld:overworld`.
Which one a world uses is saved with the world. A new world uses the only one installed, or the server's `TERRAIN`
setting when there are several. A server with no terrain generator refuses to start.

```ts
export function setup(gen: WorldgenContext) {
	gen.register_terrain("bworld:overworld", (chunk) => {
		const height_noise = chunk.noise_2d("height");
		for (let x = 0; x < 16; x++) {
			for (let z = 0; z < 16; z++) {
				const wx = chunk.x * 16 + x;
				const wz = chunk.z * 16 + z;
				const height = Math.floor((height_noise(wx * 0.01, wz * 0.01) + 1) * 15 + 50);
				for (let y = 0; y <= height; y++) {
					chunk.set_block(wx, y, wz, y === height ? "bworld:grass" : "bworld:stone");
				}
				chunk.set_height(wx, wz, height);
				chunk.set_biome(wx, wz, "bworld:plains");
			}
		}
	});
}
```

A terrain generator gets a `TerrainChunk`: a `FeatureChunk` (below) plus `set_height(x, z, height)` and
`set_biome(x, z, biome)`, which feed `height_at` / `biome_at` in later passes. Its `set_block` can write up to one chunk
away, like trees. Writes into another chunk only fill air, so the result doesn't depend on which chunk generates first.

Seeding is exact, so a generator ported from the current code produces the same terrain:

- `noise_2d(name)` is `create_noise_2d(new Alea(seed + "_" + name))` from `@paulaboks/rng`, and `noise_3d` is the same
  with `create_noise_3d`. Both are cached per seed and name.
- A terrain generator's `rng` is `new Alea(seed + "_chunk_" + x + "_" + z)`.
- A feature's `rng` is `new Alea(seed + "_feature_" + feature_id + "_" + x + "_" + z)`.

### Ores

`worldgen/ores.json` uses the same fields as the `BASE_ORES` table in `common/generation.ts`:

```json
{
	"format_version": 1,
	"ores": [
		{
			"id": "copper_tools:rich_copper_ore",
			"replaces": "bworld:stone",
			"min_y": 5,
			"max_y": 40,
			"scale": 0.05,
			"threshold": 0.72
		}
	]
}
```

Each block in the chunk that is `replaces` and between `min_y` and `max_y` becomes the first ore whose `noise_3d(id)` at
`(x, y, z) * scale` is above `threshold`.

### Features

`scripts.worldgen` registers features, which run on each chunk after terrain and ores:

```ts
import type { WorldgenContext } from "bworld/worldgen";

export function setup(gen: WorldgenContext) {
	gen.register_feature("copper_tools:boulders", (chunk) => {
		if (chunk.rng.next() > 0.1) return;
		const x = chunk.x * 16 + Math.floor(chunk.rng.next() * 16);
		const z = chunk.z * 16 + Math.floor(chunk.rng.next() * 16);
		chunk.set_block(x, chunk.height_at(x, z) + 1, z, "bworld:stone");
	});
}
```

```ts
interface FeatureChunk {
	x: number; // chunk coordinates
	z: number;
	seed: string;
	rng: { next(): number }; // seeded from the seed, chunk and feature id
	noise_2d(name: string): (x: number, z: number) => number; // cached per seed and name
	noise_3d(name: string): (x: number, y: number, z: number) => number;
	height_at(x: number, z: number): number; // surface height, inside this chunk only
	biome_at(x: number, z: number): string;
	get_block(x: number, y: number, z: number): string | undefined; // inside this chunk only
	set_block(x: number, y: number, z: number, id: string): void; // up to one chunk away, like trees
}
```

- **No `Math.random`, `Date`, `performance.now` or network access.** Use `chunk.rng` and the noise helpers.
- Worldgen can't use server or client APIs, and generated blocks don't run `on_create`.
- Each feature's `rng` is seeded with its own id, so adding or removing another mod's feature doesn't change what this
  one generates.

## Delivery to clients

### Build

`deno task build` builds each mod in `mods/` into two places:

```
build/mods/<id>/<hash>/          # public, served to players
  manifest.json
  data.json                      # all blocks, items, recipes and ores merged
  client.js
  worldgen.js
server_mods/<id>/<hash>/         # private, outside the static root, never served
  server.js
```

`<hash>` is a content hash of the mod's public files, so URLs never change content. The server sends them with
`Cache-Control: immutable`, and players only download a mod again when it changes. Textures from every mod go into the
server's atlas, which gets a hash-named URL the same way.

### Joining

```
client                                     server
  │  hello { name, protocol }               │
  ├────────────────────────────────────────►│   a different protocol gets rejected { reason }
  │  welcome { protocol, seed, atlas,       │   mods[i] = { id, name, version, hash,
  │            mods[] }                     │              data, client?, worldgen?, sha256 }
  │◄────────────────────────────────────────┤   atlas = { png, json, sha256 }  (paths on the server)
  │                                         │
  │  [cross-origin: confirm screen]         │
  │  download the atlas and every mod file, │
  │  check each one's sha256, register data │
  │  in the listed order, run client        │
  │  setup(), start chunk workers           │
  │                                         │
  │  ready                                  │
  ├────────────────────────────────────────►│
  │  join { id, name, players, entities,    │   the player is created here, player_join fires,
  │         changes, spawn, selected_slot } │   and their inventory follows as container messages
  │◄────────────────────────────────────────┤
```

- The client registers each mod's data **in the order the server lists them**.
- Every file is checked against its SHA-256 before it's used, and scripts are imported from the checked bytes (as
  `blob:` URLs), so what runs is exactly what was checked. The client code is in `client/handshake.ts` and
  `client/mods.ts`.
- If any download, hash check or `setup` fails, the client disconnects and shows which mod failed. It never joins with
  some mods missing.
- The `protocol` in `hello` is the game's protocol version (`PROTOCOL_VERSION` in `common/protocol.ts`). A mismatch is
  rejected before anything is downloaded.
- Until `ready`, the connection isn't a player: other players don't see it, and anything it sends besides `ready` is
  ignored. A client that doesn't send `ready` within 60 seconds is rejected.
- Mod files and the atlas are served with `Access-Control-Allow-Origin: *` and cached for a year, since their paths
  change whenever their content does.
- Leaving a server reloads the page, so one server's mod code never stays loaded while playing on another.

## Security

**Client scripts.** Mod client code runs in the game page with the page's full access. How much that matters depends on
where the page came from:

- **Page served by the game server** (the default): that server already chose every line of JavaScript on the page, so
  running its mods doesn't trust it any more than loading the page did.
- **Page from one origin, game server on another** (a different server typed in the title screen, or `?server=`): mod
  code from that server runs with _the page's_ origin, including its local storage. The client shows the server's mod
  list and asks before loading anything, and remembers the answer per server and mod hash. The server needs CORS
  headers on `build/mods/`.
- The hash check confirms the files are the ones the server listed. It doesn't protect against a malicious server.

**Server scripts.** They run in a worker with **no Deno permissions** (Deno worker permissions; currently needs
`--unstable-worker-options`). They can't read files, open connections or run programs. Everything they need goes through
the mod API. Installing a server mod still means trusting it with the game world and everything players send.

**Players.** Clients are untrusted. The server checks reach and the item being held for every break, place and interact,
applies container rules on the server, validates form responses, and rate-limits mod channels. Server script code and
tile data are never sent to clients.

## Example mod

A smelter block with a container screen, a stats screen written in client code, and a channel between them.

`mods/copper_tools/manifest.json`

```json
{
	"format_version": 1,
	"id": "copper_tools",
	"name": "Copper Tools",
	"version": "1.0.0",
	"scripts": { "server": "scripts/server.ts", "client": "scripts/client.ts" }
}
```

`mods/copper_tools/blocks/smelter.json`

```json
{
	"format_version": 1,
	"block": {
		"id": "copper_tools:smelter",
		"textures": { "front": "copper_tools:smelter_front", "side": "bworld:stone" },
		"mining": { "toughness": 5, "tool": "pickaxe", "requires_tool": true },
		"drops": "copper_tools:smelter",
		"components": { "copper_tools:smelter": { "speed": 2 } }
	}
}
```

`mods/copper_tools/scripts/server.ts`

```ts
import type { ServerContext } from "bworld/server";

interface SmelterData {
	container: string;
	progress: number;
	smelted: number;
}

export function setup(ctx: ServerContext) {
	ctx.components.register_block("copper_tools:smelter", {
		on_create(block) {
			block.data = { container: ctx.containers.create(3).id, progress: 0, smelted: 0 } satisfies SmelterData;
		},
		on_break(block) {
			ctx.containers.delete((block.data as SmelterData).container);
		},
		on_interact(block, _params, player) {
			const data = block.data as SmelterData;
			ctx.ui.open_container(player, {
				title: "Smelter",
				container: ctx.containers.get(data.container)!,
				layout: [
					{ slot: 0, x: 3, y: 0, filter: "smeltable" },
					{ slot: 1, x: 3, y: 2, filter: "fuel" },
					{ slot: 2, x: 5, y: 1, output_only: true },
				],
				player_inventory: true,
				bars: [{ id: "progress", x: 4, y: 1, texture: "bworld:arrow" }],
			}).set_property("progress", data.progress);
			return true;
		},
		on_tick(block, params) {
			const data = block.data as SmelterData;
			// ... smelt using ctx.recipes, data.progress += params.speed, data.smelted += 1 when done
		},
	});

	ctx.commands.register("smelterstats", {
		description: "Show stats for the smelter you're looking at",
		usage: "/smelterstats",
		run(_args, player) {
			ctx.ui.open_screen(player, "copper_tools:smelter_stats", { smelted: count_all_smelted() });
		},
	});

	ctx.net.on("copper_tools:reset_stats", (player) => {
		if (player.name !== ctx.storage.get("owner")) return;
		reset_all_smelted();
	});
}
```

`mods/copper_tools/scripts/client.ts`

```ts
import type { ClientContext, Graphics, ModScreen } from "bworld/client";

export function setup(ctx: ClientContext) {
	ctx.ui.register_screen("copper_tools:smelter_stats", (props) => new SmelterStats(ctx, props));
}

class SmelterStats implements ModScreen {
	constructor(private ctx: ClientContext, private props: { smelted: number }) {}

	on_render(g: Graphics) {
		const x = g.width / 2 - 150;
		const y = g.height / 2 - 80;
		g.panel(x, y, 300, 160);
		g.text(`Smelted: ${this.props.smelted}`, x + 20, y + 20, { scale: 2 });
		if (g.button("Reset", x + 90, y + 100, 120, 32)) {
			this.ctx.net.send("copper_tools:reset_stats", {});
		}
	}

	on_props(props: { smelted: number }) {
		this.props = props;
	}
}
```

## The base game as a mod

Everything that makes bworld _bworld_ (its blocks, items, recipes, textures, block behavior and terrain) moves into a
mod at `mods/bworld`, written against the same API as any other mod. The engine keeps only what every game built on it
needs.

This is how the mod API gets tested for real: if the base game can't be written as a mod, the API is missing something,
and other mods would hit the same wall. It also means there's one way content works instead of two, so mods can do
anything the base game does.

### What moves

| Content                              | Now                            | In `mods/bworld`                                                |
| ------------------------------------ | ------------------------------ | --------------------------------------------------------------- |
| 18 blocks                            | `common/blocks/*.ts`           | `blocks/*.json`                                                 |
| 11 items                             | `common/items/*.ts`            | `items/*.json`                                                  |
| 62 textures                          | `assets/sprites/textures/`     | `textures/`                                                     |
| 5 crafting recipes                   | `server/game/crafting.ts`      | `recipes/*.json`, type `shaped`                                 |
| 6 furnace recipes, 2 fuels           | `server/game/blocks.ts`        | `recipes/*.json`, types `furnace` and `fuel`                    |
| Hoeing grass and dirt                | `server/game/blocks.ts`        | component `bworld:hoeable`, params `{ tool, into }`             |
| Chest                                | `server/game/blocks.ts`        | component `bworld:storage`, params `{ rows }`                   |
| Furnace (smelting, fuel, its screen) | `server/game/blocks.ts`        | component `bworld:furnace`                                      |
| Watering can's starting water        | `common/items/watering_can.ts` | item component `bworld:watering_can`, params `{ max_water }`    |
| Terrain and biomes                   | `common/worldgen/`             | terrain generator `bworld:overworld` in `scripts/worldgen.ts`   |
| Ore table (`BASE_ORES`)              | `common/generation.ts`         | `worldgen/ores.json`, unchanged                                 |
| Texture credits (the Kenney packs)   | `assets/ASSETS.md`             | `CREDITS.md`, listed in the manifest's `credits`                |

Not moved:

- **Crops** (`common/blocks/crops.ts`) are unfinished and mostly commented out. They stay where they are and get rebuilt
  as a component once server scripts exist, as a good first test of tile data plus ticking.
- **The watering can's lore** (`get_lore`) isn't shown anywhere yet, because the game has no item tooltips. It moves
  once tooltips exist.

### What stays in the engine

Rendering, physics and player controls; chunks, meshing and the generation passes (noise helpers, chunk assembly, ores,
features); networking, saving and the game server; registries and the mod loader; inventories, the crafting grid, slot
click rules and the generic container screen; chat and `/give`; `bworld:air`; and the engine assets in `assets/`: the UI
sprites, font, player sprite and the `engine:` textures (the breaking cracks and the missing texture).

### Rules that keep existing worlds working

Worlds saved before the move must load afterwards with nothing changed:

1. **Ids don't change.** Saves store blocks and items by string id, including player inventories and chest contents. The
   JSON uses exactly the ids the TypeScript files register now.
2. **Terrain is identical, block for block.** A save only stores what players changed _on top of_ generated terrain. If
   the generator's output changes at all, every existing world silently changes with it: trees move and blocks players
   broke reappear. The golden terrain test (phase 0) enforces this.
3. **Tile data keeps its shape.** Chests store their items in `containers.main`, and furnaces keep `containers.main`
   plus `progress`, `progress_max`, `fuel` and `fuel_max` in `data`. The components read exactly those, so tiles saved
   by the current code load into them.
4. **The save format and protocol don't change.** Clients receive `mods/bworld` like any other mod.

### Phases

Each phase ends with every test passing and the game playable.

**Phase 0: safety net.** Do this first, before any other mod work. Started: `deno task test` runs `tests/`, which covers
loading mods (the base game and the template), their scripts and worldgen, saves, and the mod tools.

- Move the test scripts used while building steps 1–3 into the repo as `deno test` files under `tests/`: server logic
  (breaking, placing, crafting, chest, furnace, saves), client and server terrain agreement, click prediction, and the
  end-to-end WebSocket test.
- Record golden fixtures from the current code: `tests/fixtures/registry.json`, every block and item with all its fields
  (functions left out), and `tests/fixtures/terrain.json`, a SHA-256 of the final blocks of 64 chunks for 3 seeds,
  including negative coordinates and chunks with trees on their borders.
- Save a world from the current code with chests, a running furnace and some player inventories as
  `tests/fixtures/world_v2.json`, with a test that loads it and checks everything is where it was.

**Phase 1: data** (after steps 4 and 5). _Done._

- Create `mods/bworld` with its manifest and credits, and move the 62 textures there. Rename the breaking cracks to
  `engine:break_0`–`8` and the fallback to `engine:missing`.
- Generate the block, item and recipe JSON with a script that reads the current registries, instead of writing it by
  hand. Hand-copying 18 blocks' fields is how typos get in. They were generated this way, checked equal to the
  TypeScript definitions, and those were then deleted.
- The loader registers the recipes and `server/game/crafting.ts` matches against them. Behaviors stay in
  `server/game/blocks.ts`, still keyed by block id, for now.
- Delete `common/blocks/` and `common/items/`.
- Check: the registry built from JSON equals `registry.json`, and all tests pass.

**Phase 2: behavior** (after step 6, and container screens from step 7).

- `mods/bworld/scripts/server.ts` registers `bworld:hoeable`, `bworld:storage`, `bworld:furnace` and
  `bworld:watering_can`. The chest and furnace open their screens with `ctx.ui.open_container`, whose layouts are the
  `ScreenLayout`s the server sends now.
- The block JSON lists the components. Delete `server/game/blocks.ts`.
- Check: the server logic tests (hoeing, chest, furnace smelting, breaking a chest gives its contents back) and
  `world_v2.json` still pass.

**Phase 3: world generation** (after step 9).

- Port `common/worldgen/` to `mods/bworld/scripts/worldgen.ts` as the `bworld:overworld` terrain generator. It's a
  straight port: it only uses named noises, which are exactly `noise_2d` / `noise_3d` in
  [Terrain generators](#terrain-generators).
- Move `BASE_ORES` to `mods/bworld/worldgen/ores.json`. They already run through the same ore pass as mods' ores, in
  the same order, so the result is identical.
- Remove the content from `common/generation.ts`, leaving the passes and noise helpers.
- Check: `terrain.json` matches exactly, client and server terrain still agree, and `world_v2.json` loads unchanged.

**Phase 4: engine cleanup.**

- Replace the hardcoded water checks in `server/game/game_server.ts` with the `replaceable` block field, like
  `client/game_mode.ts` already does.
- `/give` stops assuming `bworld:`. It looks names up across all namespaces and asks for the full id when two mods have
  the same name.
- Rename engine asset keys like `bworld:ui` and `bworld:m6x11` in `client/main.ts` to `engine:`, so `bworld:` only means
  content.
- The Credits screen (title screen and pause menu) shows the engine's `assets/ASSETS.md` plus every loaded mod's credits.
  _Done._ Credits are published next to the mod's data and checked by hash like everything else.
- The server refuses to start without a terrain generator, naming the mods that could provide one.

### Done when

- Searching `client/`, `common/` and `server/` for `"bworld:` finds only `bworld:air`.
- Removing `mods/bworld` gives an engine that starts and says it needs a terrain generator, instead of crashing
  somewhere.
- All tests pass, the golden fixtures are unchanged, and a world saved before the move plays exactly the same after it.

## Implementation plan

Steps 1–6 are done and 9 mostly, enough that a mod made from the template loads and runs. Each step keeps the game
working:

1. **Game server core.** Move `client/generation.ts` to `common/` (it already only needs constants and the rng package)
   and have the server generate terrain. Move world state, chunks, tile data and player inventories into a game server
   module that runs in a Deno worker, with `server/main.ts` handling HTTP, WebSockets and files.
2. **Server authority.** Change the protocol from "here's the block I changed" to intents (`break_block`, `place_block`,
   `interact`, `select_slot`, `container_click`). The client keeps showing breaks and places immediately and accepts
   corrections. Move inventories, drops and `/give` to the server. Replace `GuiChest` / `GuiFurnace` with server-synced
   containers.
3. **Server only.** Remove the offline fallback in `client/main.ts`, which currently starts a local game when it can't
   reach a server, and show a connection error instead.
4. **Mod loader and build.** Discover mods, check manifests, sort by dependencies, turn JSON into registry entries,
   build the combined atlas (textures are currently all named `bworld:<file>`), bundle scripts per side, and write
   hashed output to `build/mods/` and `server_mods/`. _Done._
5. **Delivery.** Split `welcome` into `welcome` / `ready` / `join`. Clients download, verify and run mods before
   joining. Add the confirm screen for cross-origin servers and CORS headers on the server. _Done._
6. **Server scripts.** Components, events, commands, system, storage and `ctx.recipes`. Move `FURNACE_RECIPES` and
   `FUEL_VALUES` into the recipe registry. _Done_ (`server/game/mod_runtime.ts`, with the loop in
   `server/game/game_loop.ts`). `ctx.containers`, `ctx.ui` and `ctx.net` throw until steps 7 and 8, and so do the
   client's `ctx.ui`, `ctx.hud`, `ctx.input` and `ctx.net`.
7. **GUIs.** Forms, then container screens (rebuild chest and furnace with them), then custom screens, the `Graphics`
   API (built on the existing renderer and debug UI widgets) and the HUD.
8. **Mod channels** and keybinds.
9. **Worldgen mods.** Worldgen URLs and mod ores go into the chunk worker `init` message. Workers must finish importing
   before generating anything. _Done for features and ores._ `register_terrain` throws until phase 3 moves the base
   terrain out of the engine.

Steps 1–3 are engine work every multiplayer feature needs, with or without mods. Mods could start with data only (step 4
plus data in step 5) before scripts exist.

Moving the base game into `mods/bworld` happens alongside steps 4–9. See
[The base game as a mod](#the-base-game-as-a-mod) for which phase follows which step.

## Open questions

- **Chunk delivery.** Clients generate terrain from the seed, which needs deterministic worldgen and trusts clients to
  run the same generator. Sending chunks from the server instead (like Minecraft) removes both problems but costs
  bandwidth, roughly 5–15 KB per chunk compressed. It could be worth it once the server generates terrain anyway.
- **Client-only mods.** Should players be able to install their own client mods (minimaps, UI tweaks) that work on any
  server? They'd need a separate `"side": "client"` kind of mod that can't add content, and servers might want to forbid
  them.
- **Client-side prediction for mods.** Custom block components only run on the server, so interacting with a mod block
  always waits one round trip. Optional client-side component handlers for prediction could fix that later.
- **Overriding base game content.** Replacing `bworld:` blocks is forbidden for now. An `"extends"` field that adds
  components to an existing block (for example to `bworld:grass`) is a possible middle ground.
- **Screen scaling.** The GUI currently works in raw canvas pixels (`SLOT_SIZE` is 54). `Graphics` should probably use a
  UI scale the player can change, with screens laid out in scaled units.
- **Entities.** The only entities are players (`client/entity/`), so mob mods are out of scope until there are more
  entity types.
- **Hot reload.** Restarting the server and reconnecting is the version 1 answer.