WIP (session wrap-up 2026-10-15): unfinished, not reviewed

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Trial spawners run in game
2026-11-07 11:06:11 -10:00 · 2026-10-15 12:36:19 +02:00 · 2026-10-15 12:20:30 +02:00 · 2026-10-15 12:20:29 +02:00 · 2026-10-15 11:39:03 +02:00 · 2026-10-15 11:38:57 +02:00
725 changed files with 117408 additions and 7552 deletions
@@ -0,0 +1,8 @@
+# Docker builds (the relay) need the Rust sources only.
+target/
+.local/
+**/node_modules/
+website/
+benchmarks/
+packs/
+mods/
@@ -0,0 +1,3 @@
+self-hosted-runner:
+  # The Mac mini's runner (ludovics-mac-mini), which holds the maintainer's own Minecraft files.
+  labels: [horizon-game, ludovics-mac-mini]
@@ -0,0 +1,19 @@
+## What and why
+
+<!-- What this changes, and why. Link the issue it fixes ("Fixes #123"). -->
+
+## Vanilla reference
+
+<!-- The vanilla classes and methods this follows (tools/rea_vanilla.py), and the harness that checks it.
+     "Horizon-only" for a feature vanilla doesn't have; "none" for tooling or docs. -->
+
+## Self-check
+
+<!-- Paste the block `python3 tools/pr_ready.py` prints (`--base upstream/main` from a fork). -->
+
+## Screenshots
+
+<!-- For anything players see: before and after. Delete this section otherwise. -->
+
+<!-- Please tick "Allow edits by maintainers": we push small fixups ourselves instead of a round trip.
+     See CONTRIBUTING.md. -->
@@ -1,14 +1,25 @@
 name: checks
+# verify: every pull request and every push to main, on GitHub's runners (the repository is public).
+# parity: the vanilla harnesses a pull request's changes can affect, on the Mac mini's runner, which holds the
+# maintainer's own Minecraft files (Horizon never downloads the game). A fork's pull request runs it only when
+# a maintainer adds the run-parity label, once per label. See docs/release-flow.md.
 on:
  push:
    branches: [main]
  pull_request:
+    types: [opened, synchronize, reopened, labeled]
  workflow_dispatch:
 permissions:
  contents: read
+concurrency:
+  # A new push to a pull request replaces its running checks; main's runs all finish (releases follow them).
+  group: checks-${{ github.event.pull_request.number || github.sha }}-${{ github.event.action == 'labeled' && 'label' || 'run' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 jobs:
  verify:
+    if: github.event.action != 'labeled'
    runs-on: ubuntu-latest
+    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
        with:
@@ -22,16 +33,54 @@ jobs:
          python tools/check_public_tree.py --history
      - name: Test offline research tooling
        run: python -m unittest discover -s tests -v
-      - name: Install Rust toolchain and the ALSA headers the client's audio links against
+      - name: Install Rust toolchain and the ALSA and udev headers the client links against
        run: |
-          sudo apt-get update && sudo apt-get install -y --no-install-recommends libasound2-dev
+          sudo apt-get update && sudo apt-get install -y --no-install-recommends libasound2-dev libudev-dev
          rustup toolchain install stable --profile minimal --component rustfmt --component clippy
+      # Dependencies and the workspace's own build, saved from main's runs (pull requests read main's cache).
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: verify
+          save-if: ${{ github.ref == 'refs/heads/main' }}
      - name: Check formatting and lint
        run: |
          cargo +stable fmt --all -- --check
          cargo +stable clippy --workspace --all-targets -- -D warnings
      - name: Test Rust core and voxel kernel correctness
        run: cargo +stable test --workspace
+  parity:
+    if: >-
+      github.event_name == 'pull_request' && (
+        (github.event.pull_request.head.repo.full_name == github.repository && github.event.action != 'labeled') ||
+        (github.event.action == 'labeled' && github.event.label.name == 'run-parity'))
+    runs-on: [self-hosted, horizon-game]
+    timeout-minutes: 120  # a change to core crates reruns ~300 harnesses: ~60-90 min on the Mac mini
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The commit the event names: a fork's later pushes need another run-parity label.
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+          # Keeps .local/ (parity state, probe builds, oracle results) and target/ between runs.
+          clean: false
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Tools from the runner
+        run: bash tools/ci/runner-env.sh
+      - name: Vanilla data, and resources prepared by this preparer
+        run: bash tools/ci/vanilla-data.sh
+      - name: The harnesses this change can affect
+        env:
+          PARITY_HOSTS: ''
+        run: python3 tools/parity.py --changed ${{ github.event.pull_request.base.sha }} --timeout 1500
+      - name: Logs of the failed harnesses
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: parity-logs
+          path: .local/parity-runner/logs/
+          if-no-files-found: ignore
+          retention-days: 3
  # Horizon never downloads the game. These jobs need a self-hosted Linux runner
  # (label horizon-game) holding the maintainer's own copy: the official launcher's
  # game directory in HORIZON_MINECRAFT_DIR and the pinned server jar in
@@ -493,3 +542,4 @@ jobs:
            dist/client-graphics-smoke.json
            dist/client-graphics-macos-title.json
            dist/client-graphics-macos-world.json
+          retention-days: 3
@@ -1,86 +1,253 @@
 name: launcher
-# Builds the launcher on Linux, macOS and Windows. A pushed `launcher-vX.Y.Z` tag also puts the
-# three archives on a draft GitHub release of that tag, to publish by hand. Horizon's own
-# releases are tagged `vYYYY.MM.DD`; the launcher reads only `launcher-v*` releases for itself.
+# Builds the launcher on Linux, macOS and Windows, and releases it by itself (docs/release-flow.md): after a
+# push to main that changes the launcher or what it builds in (crates/horizon-prepare, crates/horizon-theme),
+# every 10 minutes (a release waiting for merges to settle goes out) and by hand, tools/release_train.py decides as
+# for the game.
+# A release is launcher-vX.Y.Z: the patch after the last launcher tag, or the next minor when a merged pull
+# request is labelled feature. The version is given to the build (HORIZON_LAUNCHER_VERSION): no bump commits.
+# Never marked latest. Pushes to launcher branches only build. RELEASES_PAUSED=1 stops releases.
+#   gh workflow run launcher --ref <branch>                    # dry run: builds everything, publishes nothing
+#   gh workflow run launcher --ref main -f dry_run=false -f force=true

 on:
-  workflow_dispatch:
  push:
-    branches: [launcher]
-    tags: ['launcher-v*']
+    branches: [main, launcher, 'launcher-*']
+    paths:
+      - 'launcher/**'
+      - 'crates/horizon-prepare/**'
+      - 'crates/horizon-theme/**'
+      - '.github/workflows/launcher.yml'
+  schedule:
+    - cron: '7-59/10 * * * *'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Build everything and write the notes, but publish nothing
+        type: boolean
+        default: true
+      force:
+        description: Release even without launcher changes, before merges settle or while paused
+        type: boolean
+        default: false

 permissions:
  contents: read

+concurrency:
+  group: launcher-${{ github.ref == 'refs/heads/main' && 'release' || github.ref }}
+  cancel-in-progress: false
+
 jobs:
+  decide:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      release: ${{ steps.decide.outputs.release }}
+      tag: ${{ steps.decide.outputs.tag }}
+      head: ${{ steps.decide.outputs.head }}
+      version: ${{ steps.decide.outputs.version }}
+      dry_run: ${{ steps.mode.outputs.dry_run }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - id: mode
+        # Off main every run is a dry run (a launcher branch's push only builds).
+        run: echo "dry_run=${{ github.ref != 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && inputs.dry_run) }}" >> "$GITHUB_OUTPUT"
+      - id: decide
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASES_PAUSED: ${{ vars.RELEASES_PAUSED }}
+          # A push or a run off main builds its own commit; otherwise main's newest commit with green checks.
+          HEAD_SHA: ${{ (github.event_name == 'push' || steps.mode.outputs.dry_run == 'true') && github.sha || '' }}
+          FORCE: ${{ inputs.force && 'yes' || '' }}
+        run: |
+          python3 tools/release_train.py decide --kind launcher ${HEAD_SHA:+--head "$HEAD_SHA"} ${FORCE:+--force} | tee decision.json
+          echo "### $(jq -r '.reason' decision.json)" >> "$GITHUB_STEP_SUMMARY"
+          tag=$(jq -r '.tag' decision.json)
+          echo "version=${tag#launcher-v}" >> "$GITHUB_OUTPUT"
+          # A dry run (and a launcher branch's push) builds whatever the decision.
+          if [[ "${{ steps.mode.outputs.dry_run }}" == true ]]; then
+            echo "release=true" >> "$GITHUB_OUTPUT"
+            echo "head=$GITHUB_SHA" >> "$GITHUB_OUTPUT"
+          fi
+
  build:
+    needs: decide
+    if: needs.decide.outputs.release == 'true'
+    name: build ${{ matrix.name }}
    strategy:
      fail-fast: false
      matrix:
        include:
-          - os: ubuntu-latest
+          - name: linux
+            os: ubuntu-22.04
            asset: horizon-launcher-linux-x86_64.tar.gz
            binary: horizon-launcher
-          - os: macos-latest
+          - name: macos
+            mac: true
            asset: horizon-launcher-macos-arm64.zip
            binary: horizon-launcher
-          - os: windows-latest
+          - name: windows
+            os: windows-latest
            asset: horizon-launcher-windows-x64.zip
            binary: horizon-launcher.exe
-    runs-on: ${{ matrix.os }}
+            # The C runtime linked in: without it the launcher asks for VCRUNTIME140.dll,
+            # which only the Visual C++ redistributable installs.
+            rustflags: -C target-feature=+crt-static
+    runs-on: ${{ matrix.mac && (vars.MAC_RUNNER || 'ludovics-mac-mini') || matrix.os }}
+    timeout-minutes: 40
+    env:
+      RUSTFLAGS: ${{ matrix.rustflags }}
+      # Horizon's Azure app for Microsoft sign-in (docs/microsoft-account.md): a repository
+      # variable, not a secret. Unset, the launcher says sign-in is not configured.
+      HORIZON_MSA_CLIENT_ID: ${{ vars.HORIZON_MSA_CLIENT_ID }}
+      # The release's version, built in (launcher/src/backend.rs VERSION); a launcher branch's build keeps
+      # Cargo.toml's.
+      HORIZON_LAUNCHER_VERSION: ${{ (github.event_name != 'push' || github.ref == 'refs/heads/main') && needs.decide.outputs.version || '' }}
    defaults:
      run:
        working-directory: launcher
        shell: bash
    steps:
      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.decide.outputs.head }}
+          persist-credentials: false
+          # The Mac mini's runner keeps its target/ between runs.
+          clean: ${{ runner.environment == 'github-hosted' }}
      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2
+        if: runner.environment == 'github-hosted'
        with:
          workspaces: launcher
+          shared-key: launcher-${{ matrix.name }}
      - name: Linux libraries GPUI links to
        if: runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y libxkbcommon-x11-dev libwayland-dev libx11-xcb-dev libfontconfig-dev libvulkan-dev libasound2-dev
-      - name: The tag matches Cargo.toml
-        if: startsWith(github.ref, 'refs/tags/launcher-v')
-        run: grep -qx "version = \"${GITHUB_REF_NAME#launcher-v}\"" Cargo.toml
-      - run: cargo test --release --locked --lib
-      - run: cargo build --release --locked
+      - name: Metal shaders compiled now, or at run time without the Metal toolchain
+        # GPUI compiles its Metal shaders when it builds; the Mac mini has Xcode without the Metal toolchain
+        # (xcodebuild -downloadComponent MetalToolchain), so there they are compiled when the launcher starts.
+        if: runner.os == 'macOS'
+        run: |
+          if ! xcrun metal --version > /dev/null 2>&1; then
+            echo "::notice::No Metal toolchain on this runner: GPUI compiles its shaders at run time"
+            echo "LAUNCHER_FEATURES=gpui/runtime_shaders" >> "$GITHUB_ENV"
+          fi
+      - run: cargo test --release --locked --lib ${LAUNCHER_FEATURES:+--features "$LAUNCHER_FEATURES"}
+      - run: cargo build --release --locked ${LAUNCHER_FEATURES:+--features "$LAUNCHER_FEATURES"}
+      - name: The version is the release's
+        run: |
+          out=$(target/release/${{ matrix.binary }} --version)
+          echo "$out"
+          expected="${HORIZON_LAUNCHER_VERSION:-$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1)}"
+          [[ "$out" == "horizon-launcher $expected" ]] || { echo "::error::expected horizon-launcher $expected"; exit 1; }
+      - name: Only system libraries
+        run: |
+          file=target/release/${{ matrix.binary }}
+          case "$RUNNER_OS" in
+            Windows) python ../tools/check_imports.py "$file" ;;
+            macOS) others=$(otool -L "$file" | tail -n +2 | awk '{print $1}' | grep -v -E '^(/usr/lib/|/System/Library/)' || true)
+                   [[ -z "$others" ]] || { echo "::error::links $others"; exit 1; } ;;
+          esac
+      - name: Smoke test
+        env:
+          HORIZON_LAUNCHER_NO_SELF_UPDATE: '1'
+          HORIZON_GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          export HORIZON_LAUNCHER_HOME="${RUNNER_TEMP//\\//}/horizon-launcher-smoke"
+          export HORIZON_HOME="$HORIZON_LAUNCHER_HOME/game"
+          rm -rf "$HORIZON_LAUNCHER_HOME"
+          launcher="$PWD/target/release/${{ matrix.binary }}"
+          # GitHub's API rate-limits shared runner addresses now and then: try a few times.
+          retry() { for i in 1 2 3 4; do "$@" && return 0; sleep $((i * 15)); done; return 1; }
+          retry "$launcher" versions
+          retry "$launcher" install latest
+          "$launcher" versions --installed
+          "$launcher" links --json
+          "$launcher" menu-style classic
+          grep -qx 'menuStyle:classic' "$HORIZON_HOME/horizon.txt"
+          "$launcher" menu-style horizon
+          clients=("$HORIZON_LAUNCHER_HOME"/versions/v*/horizon-client*)
+          client="${clients[0]}"
+          echo "installed client: $client"
+          # The game's Linux build is the game's to keep portable (release.yml checks it): a
+          # release linked to a Nix store is a warning here, not a broken launcher.
+          soft() { if [[ "$RUNNER_OS" == "Linux" ]]; then "$@" || echo "::warning::$* failed"; else "$@"; fi; }
+          if [[ "$RUNNER_OS" == "Windows" ]]; then
+            python ../tools/check_imports.py "$client"
+          elif [[ "$RUNNER_OS" == "Linux" ]]; then
+            soft python3 ../tools/check_imports.py "$client"
+          fi
+          # The client starts: --help prints before any window or GPU is needed.
+          help() { "$client" --help > "$RUNNER_TEMP/help.txt" 2>&1 && head -3 "$RUNNER_TEMP/help.txt" && grep -q -- '--resources' "$RUNNER_TEMP/help.txt"; }
+          soft help
+          rm -rf "$HORIZON_LAUNCHER_HOME"
      - name: Package
        run: |
-          mkdir -p dist
-          cp target/release/${{ matrix.binary }} dist/
-          cd dist
-          if [[ "${{ matrix.asset }}" == *.tar.gz ]]; then
-            tar czf ../${{ matrix.asset }} ${{ matrix.binary }}
-          elif [[ "$RUNNER_OS" == "Windows" ]]; then
-            7z a ../${{ matrix.asset }} ${{ matrix.binary }}
+          rm -rf dist out && mkdir -p out
+          if [[ "$RUNNER_OS" == "macOS" ]]; then
+            # Horizon.app, zipped (self-update) and in a .dmg (installer): packaging/macos.
+            python3 -m venv "$RUNNER_TEMP/dmg" && "$RUNNER_TEMP/dmg/bin/pip" install --quiet dmgbuild==1.6.5
+            version=${HORIZON_LAUNCHER_VERSION:-$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1)}
+            DMGBUILD="$RUNNER_TEMP/dmg/bin/dmgbuild" ../packaging/macos/package.sh target/release/${{ matrix.binary }} "$version" out
+            rm -rf out/Horizon.app
          else
-            zip ../${{ matrix.asset }} ${{ matrix.binary }}
+            mkdir -p dist
+            cp target/release/${{ matrix.binary }} dist/
+            if [[ "${{ matrix.asset }}" == *.tar.gz ]]; then
+              (cd dist && tar czf ../out/${{ matrix.asset }} ${{ matrix.binary }})
+            else
+              (cd dist && 7z a ../out/${{ matrix.asset }} ${{ matrix.binary }})
+            fi
          fi
+          ls -l out
      - uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.asset }}
-          path: launcher/${{ matrix.asset }}
+          path: launcher/out/*
+          retention-days: 3

  release:
-    if: startsWith(github.ref, 'refs/tags/launcher-v')
-    needs: build
+    needs: [decide, build]
    runs-on: ubuntu-latest
+    timeout-minutes: 10
    permissions:
      contents: write
    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          python3 tools/release_train.py notes --kind launcher --tag "${{ needs.decide.outputs.tag }}" \
+            --head "${{ needs.decide.outputs.head }}" --out notes > /dev/null
+          { echo "## $(cat notes/title.txt)"; echo; cat notes/body.md; } >> "$GITHUB_STEP_SUMMARY"
      - uses: actions/download-artifact@v4
        with:
          path: dist
          merge-multiple: true
-      # A draft, and never marked latest: Horizon's own releases stay the repository's latest.
-      - uses: softprops/action-gh-release@v2
+      # Never marked latest: Horizon's own releases stay the repository's latest.
+      - name: Publish ${{ needs.decide.outputs.tag }}
+        if: needs.decide.outputs.dry_run != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.decide.outputs.tag }}
+        run: |
+          gh release create "$TAG" --target "${{ needs.decide.outputs.head }}" --title "$(cat notes/title.txt)" \
+            --notes-file notes/body.md --latest=false dist/horizon-launcher-*
+      - name: Dry run, the release that would be published
+        if: needs.decide.outputs.dry_run == 'true'
+        run: |
+          echo "Would publish ${{ needs.decide.outputs.tag }} at ${{ needs.decide.outputs.head }}: $(cat notes/title.txt)"
+          ls -l dist
+      - uses: actions/upload-artifact@v4
        with:
-          tag_name: ${{ github.ref_name }}
-          name: Horizon launcher ${{ github.ref_name }}
-          draft: true
-          make_latest: false
-          files: dist/*
+          name: launcher-release-notes
+          path: notes/
+          retention-days: 3
@@ -0,0 +1,79 @@
+name: nightly audit
+# Every vanilla harness, from scratch, on main, at 03:00 Paris time on the Mac mini's runner (it holds the
+# maintainer's own Minecraft files). The resources are prepared again first when the preparer or its exporters
+# changed (tools/ci/vanilla-data.sh). A harness that passed in the previous audit and fails now gets an issue
+# labelled parity-regression (one per harness); its issue closes when it passes again
+# (tools/ci/parity_issues.py). The bugs session picks those up. See docs/release-flow.md.
+#   gh workflow run "nightly audit"                    # now
+#   gh workflow run "nightly audit" -f dry_run=true    # the audit, without touching issues
+on:
+  schedule:
+    # GitHub's schedules are in UTC: both, and the first step keeps the one that is 03:00 in Paris.
+    - cron: '7 1 * * *'
+    - cron: '7 2 * * *'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Run the audit, but only print what it would do with issues
+        type: boolean
+        default: false
+permissions:
+  contents: read
+  issues: write
+concurrency:
+  group: nightly-audit
+  cancel-in-progress: false
+jobs:
+  audit:
+    runs-on: [self-hosted, horizon-game]
+    timeout-minutes: 150
+    steps:
+      - name: 03:00 in Paris
+        id: when
+        run: |
+          hour=$(TZ=Europe/Paris date +%H)
+          if [[ "${{ github.event_name }}" == schedule && "$hour" != 03 ]]; then
+            echo "It is ${hour}:00 in Paris: the other schedule runs the audit."
+            echo "run=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: actions/checkout@v4
+        if: steps.when.outputs.run == 'true'
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          # Keeps .local/ (parity state, probe builds, the previous audit) and target/.
+          clean: false
+      - uses: dtolnay/rust-toolchain@stable
+        if: steps.when.outputs.run == 'true'
+      - name: Tools from the runner
+        if: steps.when.outputs.run == 'true'
+        run: bash tools/ci/runner-env.sh
+      - name: Vanilla data, prepared again if the preparer changed
+        if: steps.when.outputs.run == 'true'
+        run: bash tools/ci/vanilla-data.sh
+      - name: Every harness
+        id: audit
+        if: steps.when.outputs.run == 'true'
+        env:
+          PARITY_HOSTS: ''
+        run: |
+          echo "since=$(date +%Y-%m-%dT%H:%M:%S)" >> "$GITHUB_OUTPUT"
+          set +e
+          python3 tools/parity.py --all --timeout 1800 2>&1 | tee "$RUNNER_TEMP/audit.log"
+          echo "exit=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT"
+          { echo '```'; tail -40 "$RUNNER_TEMP/audit.log"; echo '```'; } >> "$GITHUB_STEP_SUMMARY"
+      - name: Issues for the harnesses that regressed
+        if: steps.when.outputs.run == 'true' && always() && steps.audit.outputs.since
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python3 tools/ci/parity_issues.py --since "${{ steps.audit.outputs.since }}" ${{ inputs.dry_run && '--dry-run' || '' }} | tee -a "$GITHUB_STEP_SUMMARY"
+      - name: Logs of the failed harnesses
+        if: steps.when.outputs.run == 'true' && steps.audit.outputs.exit != '0'
+        uses: actions/upload-artifact@v4
+        with:
+          name: nightly-parity-logs
+          path: .local/parity-runner/logs/
+          if-no-files-found: ignore
+          retention-days: 7
@@ -1,27 +1,225 @@
-name: release builds
-# Started by hand: gh workflow run release.yml --ref <branch>
-# Builds the Windows x64 client and uploads the playable folder as an artifact.
-# Linux and macOS builds are made on the development machines.
+name: release
+# Automatic game releases (docs/release-flow.md). After every green `checks` run on main, every 10 minutes (so a
+# release waiting for merges to settle goes out without another merge) and by hand, tools/release_train.py decides:
+# a release when pull requests merged since the last one changed what players run and the newest merged 15 minutes
+# ago (the oldest an hour ago, if merges never pause), or at once for a pull request labelled release-now.
+# RELEASES_PAUSED=1 (repository variable) stops them.
+# Builds Linux (an older Ubuntu, so the binary runs on any recent distribution and on NixOS through nix-ld) and
+# Windows on GitHub, macOS on the Mac mini's runner (MAC_RUNNER=macos-latest sends it to GitHub), then
+# publishes vYYYY.MM.DD[.N] with notes from the merged pull requests.
+#   gh workflow run release --ref <branch>                       # dry run: builds and notes, publishes nothing
+#   gh workflow run release -f dry_run=false -f force=true       # on main: release now, whatever the rules say
 on:
+  workflow_run:
+    workflows: [checks]
+    types: [completed]
+    branches: [main]
+  schedule:
+    - cron: '2-59/10 * * * *'
  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Build everything and write the notes, but publish nothing
+        type: boolean
+        default: true
+      force:
+        description: Release even without player-facing changes, before merges settle or while paused
+        type: boolean
+        default: false
 permissions:
  contents: read
+concurrency:
+  group: game-release
+  cancel-in-progress: false
 jobs:
-  windows:
-    runs-on: windows-latest
+  decide:
+    if: >-
+      github.event_name != 'workflow_run' ||
+      (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      release: ${{ steps.decide.outputs.release }}
+      tag: ${{ steps.decide.outputs.tag }}
+      head: ${{ steps.decide.outputs.head }}
+      dry_run: ${{ steps.mode.outputs.dry_run }}
    steps:
      - uses: actions/checkout@v4
-      - name: Install Rust toolchain
-        run: rustup toolchain install stable --profile minimal
-      - name: Build the client
-        # The C runtime linked in, so the game runs without the Visual C++ redistributable.
+        with:
+          fetch-depth: 0
+      - id: mode
+        # A dry run never publishes; a hand-started run off main is always one.
+        run: echo "dry_run=${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref != 'refs/heads/main') }}" >> "$GITHUB_OUTPUT"
+      - id: decide
        env:
-          RUSTFLAGS: -C target-feature=+crt-static
-        run: cargo +stable build --release --locked -p horizon-client --bin horizon-client
-      - name: Package
+          GH_TOKEN: ${{ github.token }}
+          RELEASES_PAUSED: ${{ vars.RELEASES_PAUSED }}
+          # The commit whose checks just passed; a dry run builds the branch it was started on; otherwise
+          # main's newest commit with green checks.
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha || (steps.mode.outputs.dry_run == 'true' && github.sha) || '' }}
+          FORCE: ${{ inputs.force && 'yes' || '' }}
+        run: |
+          python3 tools/release_train.py decide --kind game ${HEAD_SHA:+--head "$HEAD_SHA"} ${FORCE:+--force} | tee decision.json
+          echo "### $(jq -r '.reason' decision.json)" >> "$GITHUB_STEP_SUMMARY"
+          # A dry run builds whatever the decision, to test the builds.
+          if [[ "${{ steps.mode.outputs.dry_run }}" == true ]]; then echo "release=true" >> "$GITHUB_OUTPUT"; fi
+
+  build:
+    needs: decide
+    if: needs.decide.outputs.release == 'true'
+    name: build ${{ matrix.name }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux
+            os: ubuntu-22.04
+            dir: horizon-linux-x86_64
+            asset: horizon-linux-x86_64.tar.gz
+          - name: windows
+            os: windows-latest
+            dir: horizon-windows-x64
+            asset: horizon-windows-x64.zip
+            exe: .exe
+            # The C runtime linked in, so the game runs without the Visual C++ redistributable.
+            rustflags: -C target-feature=+crt-static
+          - name: macos
+            mac: true
+            dir: horizon-macos-arm64
+            asset: horizon-macos-arm64.zip
+    runs-on: ${{ matrix.mac && (vars.MAC_RUNNER || 'ludovics-mac-mini') || matrix.os }}
+    timeout-minutes: 40
+    env:
+      RUSTFLAGS: ${{ matrix.rustflags }}
+    defaults:
+      run:
        shell: bash
-        run: packaging/package.sh target/release/horizon-client.exe dist/horizon-windows-x64
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.decide.outputs.head }}
+          persist-credentials: false
+          # On the Mac mini's runner, keep target/ (incremental) and .local/ (the prepared resources).
+          clean: ${{ runner.environment == 'github-hosted' }}
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        if: runner.environment == 'github-hosted'
+        with:
+          shared-key: release-${{ matrix.name }}
+      - name: ALSA and udev headers
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends libasound2-dev libudev-dev
+      - name: Build the client, horizon-ctl and horizon-prepare
+        run: cargo build --release --locked -p horizon-client --bin horizon-client --bin horizon-ctl -p horizon-prepare --bin horizon-prepare
+      - name: Every program the release folder takes was built
+        run: |
+          for binary in horizon-client horizon-ctl horizon-prepare; do
+            test -f "target/release/$binary${{ matrix.exe }}" || { echo "::error::target/release/$binary${{ matrix.exe }} is missing"; exit 1; }
+          done
+      - name: Only system libraries
+        # Windows: no non-system DLL (a "DLL not found" dialog on some players' machines). Linux: the standard
+        # loader and libraries every desktop distribution has. macOS: only the system's own libraries.
+        run: |
+          for binary in horizon-client horizon-ctl horizon-prepare; do
+            file="target/release/$binary${{ matrix.exe }}"
+            if [[ "$RUNNER_OS" == macOS ]]; then
+              others=$(otool -L "$file" | tail -n +2 | awk '{print $1}' | grep -v -E '^(/usr/lib/|/System/Library/)' || true)
+              [[ -z "$others" ]] || { echo "::error::$binary links $others"; exit 1; }
+            else
+              ${{ runner.os == 'Windows' && 'python' || 'python3' }} tools/check_imports.py "$file"
+            fi
+          done
+      - name: Every program starts
+        run: |
+          set -euo pipefail
+          bin=target/release
+          "$bin/horizon-client${{ matrix.exe }}" --help | grep -q -- '--resources'
+          "$bin/horizon-ctl${{ matrix.exe }}" --help > /dev/null
+          "$bin/horizon-prepare${{ matrix.exe }}" --version
+          "$bin/horizon-prepare${{ matrix.exe }}" --help | grep -q -- '--minecraft-dir'
+      - name: Tools from the runner
+        if: runner.environment == 'self-hosted'
+        run: bash tools/ci/runner-env.sh
+      - name: Resources prepared from the runner's own Minecraft
+        if: runner.environment == 'self-hosted'
+        run: bash tools/ci/vanilla-data.sh
+      - name: The game runs (offscreen, a new world, 1500 frames)
+        if: runner.environment == 'self-hosted'
+        run: |
+          set -euo pipefail
+          # From a scratch folder: the game keeps its saves and options in the folder it starts in.
+          home="$RUNNER_TEMP/horizon-smoke"
+          rm -rf "$home" && mkdir -p "$home"
+          version=$(sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' research-lock.json | head -1)
+          client="$PWD/target/release/horizon-client"
+          resources="$PWD/.local/horizon-client/$version"
+          (cd "$home" && HORIZON_HOME="$home" HORIZON_NO_AUDIO=1 "$client" --resources "$resources" --offscreen \
+            --world smoke --seed 1 --render-distance 4 --frames 1500 --timeout-seconds 180 \
+            --smoke-report "$home/smoke.json" > "$home/client.log" 2>&1) || { tail -40 "$home/client.log"; exit 1; }
+          python3 - "$home/smoke.json" <<'EOF'
+          import json, sys
+          report = json.load(open(sys.argv[1]))
+          print(json.dumps(report))
+          if report.get("error") is not None or report.get("frames", 0) < 1500 or not report.get("chunks") \
+                  or not report.get("meshed_sections") or not report.get("player"):
+              sys.exit("the smoke run did not draw a world")
+          EOF
+      - name: Package
+        run: |
+          set -euo pipefail
+          cargo run --locked -p xtask -- package "target/release/horizon-client${{ matrix.exe }}" "dist/${{ matrix.dir }}"
+          cd dist
+          rm -f "${{ matrix.asset }}"
+          case "${{ matrix.asset }}" in
+            *.tar.gz) tar czf "${{ matrix.asset }}" "${{ matrix.dir }}" ;;
+            *) if [[ "$RUNNER_OS" == Windows ]]; then 7z a -tzip "${{ matrix.asset }}" "${{ matrix.dir }}" > /dev/null
+               else ditto -c -k --keepParent "${{ matrix.dir }}" "${{ matrix.asset }}"; fi ;;
+          esac
+          ls -l "${{ matrix.asset }}"
      - uses: actions/upload-artifact@v4
        with:
-          name: horizon-windows-x64
-          path: dist/horizon-windows-x64
+          name: ${{ matrix.asset }}
+          path: dist/${{ matrix.asset }}
+          if-no-files-found: error
+          retention-days: 3
+
+  publish:
+    needs: [decide, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          python3 tools/release_train.py notes --kind game --tag "${{ needs.decide.outputs.tag }}" \
+            --head "${{ needs.decide.outputs.head }}" --out notes > /dev/null
+          { echo "## $(cat notes/title.txt)"; echo; cat notes/body.md; } >> "$GITHUB_STEP_SUMMARY"
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Publish ${{ needs.decide.outputs.tag }}
+        if: needs.decide.outputs.dry_run != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.decide.outputs.tag }}
+        run: |
+          gh release create "$TAG" --target "${{ needs.decide.outputs.head }}" --title "$(cat notes/title.txt)" \
+            --notes-file notes/body.md --latest dist/horizon-linux-x86_64.tar.gz dist/horizon-windows-x64.zip \
+            dist/horizon-macos-arm64.zip
+      - name: Dry run, the release that would be published
+        if: needs.decide.outputs.dry_run == 'true'
+        run: |
+          echo "Would publish ${{ needs.decide.outputs.tag }} at ${{ needs.decide.outputs.head }}: $(cat notes/title.txt)"
+          ls -l dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-notes
+          path: notes/
+          retention-days: 3
@@ -0,0 +1,34 @@
+name: telemetry-server
+# The ingest server is its own workspace (crates/horizon-telemetry-server), so the checks job doesn't build
+# it: this one does, when it or the crate it shares with the launcher and the game changes.
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'crates/horizon-telemetry/**'
+      - 'crates/horizon-telemetry-server/**'
+      - '.github/workflows/telemetry-server.yml'
+  pull_request:
+    paths:
+      - 'crates/horizon-telemetry/**'
+      - 'crates/horizon-telemetry-server/**'
+      - '.github/workflows/telemetry-server.yml'
+permissions:
+  contents: read
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: crates/horizon-telemetry-server
+    steps:
+      - uses: actions/checkout@v4
+      - run: rustup toolchain install stable --profile minimal --component rustfmt --component clippy
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: crates/horizon-telemetry-server
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+      - run: cargo +stable fmt --check
+      - run: cargo +stable clippy --all-targets --locked -- -D warnings
+      - run: cargo +stable test --locked
@@ -16,5 +16,15 @@
 /dist/
 /mods/horizon/build/
 /saves/
+/backups/
 /tools/logs/
 .DS_Store
+# What the client writes to its working directory when run from the repo root.
+/options.txt
+/horizon.txt
+/horizon-graphics.txt
+/horizon-controller.txt
+/servers.dat
+/screenshots/
+/crash-reports/
+/debug/
@@ -0,0 +1,77 @@
+# Contributing to Horizon
+
+Thanks for helping. Horizon is Minecraft: Java Edition 26.3 rewritten in Rust, and the one rule that shapes
+everything is that **it plays exactly like vanilla**. This page is the short version of how we work; questions are
+welcome on [Discord](https://discord.gg/HcTeMZxe5E).
+
+## Build it
+
+You need Rust (stable), Python 3.10+, JDK 25, and on Linux the ALSA and udev headers (`libasound2-dev libudev-dev`).
+Horizon never downloads the game: it prepares its resources from your own copy of Minecraft 26.3, as described in
+[Build from source](README.md#build-from-source).
+
+```sh
+cargo run --release -p horizon-prepare -- --prepare --server-jar ~/Downloads/server.jar
+cargo run --release -p horizon-client
+```
+
+The launcher is its own Cargo workspace in `launcher/` (`cd launcher && cargo run`; on NixOS, `nix-shell` first).
+
+## Vanilla first
+
+Wherever vanilla has a feature, vanilla is the specification, down to the order of random calls. "Parity" here
+means Horizon gives the same results as the pinned 26.3 client and server for the same inputs, checked by a
+**harness**: a `tools/test_*_parity.py` script that runs a small Java oracle against the real game and a Rust
+probe against Horizon, and compares their outputs. There are about 290 of them.
+
+- **Read the vanilla code before writing Horizon's.** `tools/rea_vanilla.py` queries the pinned game bytecode:
+  `python3 tools/rea_vanilla.py method net.minecraft.world.level.block.DispenserBlock dispenseFrom`.
+  Say in your pull request which vanilla classes and methods you followed.
+- **Gameplay changes come with a harness**, new or extended, so the next change can't silently break them.
+  [The parity workflow](docs/parity-workflow.md) shows how harnesses run; copy a nearby one.
+- **Horizon's own features** (the launcher, the new menus) follow [the design system](docs/design-system.md) and are
+  off by default wherever they would change the vanilla look.
+- **Everything players run is Rust.** Python and Java are fine for dev tools and harness drivers in `tools/`, never
+  for player-facing code.
+
+Never commit game files, decompiled source or prepared resources (`.local/`): `tools/check_public_tree.py` rejects
+them (`git config core.hooksPath .githooks` runs it before every commit).
+
+## Before asking for review
+
+Run the self-check and paste the block it prints into your pull request:
+
+```sh
+python3 tools/pr_ready.py --base upstream/main   # or origin/main if you work on the main repository
+```
+
+It looks at what your branch changes and runs what matters: rustfmt, clippy with warnings denied, the tests of the
+crates you touched (and the launcher's), generated files, `Cargo.lock`, the Python tests, and the vanilla harnesses
+your change can affect. Without the vanilla data on your machine it lists those harnesses instead; CI runs them.
+`--quick` skips the harnesses. It exits non-zero when something fails.
+
+## Pull requests
+
+- **Small.** One change per pull request, under about 500 lines of code where you can; split bigger work into
+  pieces that each make sense alone. Small pull requests get reviewed and merged the same day.
+- **Fill in the template**: what and why, the vanilla reference, the pr_ready block, screenshots for anything you
+  can see.
+- **Tick "Allow edits by maintainers".** When something small is left (a lint, a rebase, a nit) we push the fixup
+  ourselves instead of sending it back to you; only design questions come back.
+- **Labels** (we set them if you can't): `feature` when players get something new (it appears under "New" in the
+  release notes), `skip-release` when players see no change (tooling, docs, tests), nothing for a fix.
+  `release-now` is for crash fixes that shouldn't wait. pr_ready suggests one.
+
+Every merge to main is released automatically ([release flow](docs/release-flow.md)), so main always stays playable.
+
+## Parity checks on forks
+
+The `verify` check (formatting, lints, tests) runs on every pull request. The `parity` check runs the affected
+harnesses on a maintainer's machine, which holds the game files, so it never runs a fork's code on its own: a
+maintainer reads your change, then adds the `run-parity` label, which runs it once on your current commit. After
+new pushes, we add it again.
+
+## Talk to us
+
+[Discord](https://discord.gg/HcTeMZxe5E) for questions and ideas, [issues](https://github.com/ludovic111/horizon/issues)
+for bugs. If you want to take something on, say so in its issue so nobody else starts the same work.
@@ -1,6 +1,6 @@
 [workspace]
-exclude = ["launcher"]
-members = ["crates/horizon-core", "crates/horizon-world", "crates/voxel-kernels", "crates/horizon-client", "crates/horizon-assets", "crates/horizon-protocol"]
+exclude = ["launcher", "crates/horizon-telemetry-server"]
+members = ["crates/horizon-core", "crates/horizon-world", "crates/voxel-kernels", "crates/horizon-client", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "xtask"]
 resolver = "2"

 [workspace.package]
@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/media/banner.jpg" alt="Horizon: Minecraft Java Edition 26.3, rewritten from scratch in Rust" width="100%">
+  <img src="docs/media/banner.webp" alt="Horizon: Minecraft: Java Edition 26.3, rewritten in Rust and checked against vanilla by 281 differential harnesses" width="100%">
 </p>

 <p align="center">
@@ -12,7 +12,9 @@
 </p>

 <p align="center">
+  <a href="https://playhorizon.dev"><b>Website</b></a> ·
  <a href="#download"><b>Download</b></a> ·
+  <a href="#what-changed-in-v202610131"><b>What changed</b></a> ·
  <a href="#screenshots"><b>Screenshots</b></a> ·
  <a href="#project-status"><b>Parity status</b></a> ·
  <a href="docs/README.md"><b>Documentation</b></a>
@@ -20,15 +22,24 @@

 # Horizon

-A Rust rewrite of Minecraft: Java Edition 26.3 with one-to-one vanilla parity, checked against the game itself with differential tests.
+A Rust rewrite of Minecraft: Java Edition 26.3 built for one-to-one vanilla parity, checked against the game itself with differential tests.

 Every subsystem matches vanilla in all 281 parity harnesses, on Linux and macOS: 100% of what the harnesses compare (see [Project status](#project-status)). The native client is playable on Linux, macOS (Apple Silicon) and Windows.

 > Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft. Horizon contains no Minecraft code, assets or data: you need your own legally obtained copy of Minecraft: Java Edition 26.3.

+## What changed in v2026.10.13.1
+
+The latest release ([notes](https://github.com/ludovic111/horizon/releases/tag/v2026.10.13.1)):
+
+- **Horizon's own menus:** a new title screen, world list, options and pause menu in the launcher's style, over a live frozen landscape. The vanilla look is still available: Options → Interface → Menu style → Classic.
+- **Graphics settings, Simple and Advanced:** presets (Performance, Balanced, Quality, Ultra), or every rendering, quality, display and performance setting, each with a short description and its cost, plus a performance overlay.
+- **Much faster rendering:** for example, at render distance 8 over a village, 363 → 2,409 FPS on an RTX 4080. Render distance 32 still stutters in places.
+- **Fixed:** no sound on Linux; Linux builds that only ran on the machine they were built on; a missing DLL on Windows (the launcher no longer needs the Visual C++ runtime); memory growing and the frame rate dropping near villages (mobs were duplicated when chunks reloaded); resource preparation failing on Linux with "Missing … java-objc-bridge" ([#41](https://github.com/ludovic111/horizon/issues/41)); the hand and held item at high FOV; missing swing animations.
+
 ## Download

-**[Download the Horizon launcher](https://github.com/ludovic111/horizon/releases?q=launcher-v&expanded=true)** for Linux x86-64, macOS Apple Silicon or Windows x64: take the newest `launcher-v*` release (currently [launcher-v0.1.1](https://github.com/ludovic111/horizon/releases/tag/launcher-v0.1.1)); the launcher then updates itself. The launcher is the way to get Horizon: it installs and updates the game, prepares its resources from your own copy of Minecraft, and starts the client or a dedicated server.
+Horizon is downloaded only through **the Horizon launcher**: get it from [playhorizon.dev](https://playhorizon.dev) or from [the launcher's releases](https://github.com/ludovic111/horizon/releases?q=launcher-v&expanded=true) (the newest `launcher-v*` release, currently [launcher-v0.1.3](https://github.com/ludovic111/horizon/releases/tag/launcher-v0.1.3)), for Linux x86-64, macOS Apple Silicon or Windows x64. The launcher installs and updates the game, prepares its resources from your own copy of Minecraft, starts the client or a dedicated server, and updates itself.

 **You need** Minecraft: Java Edition installed with the official launcher, with 26.3 played once; Python 3.10 or newer and Java 25 (a JDK, e.g. Eclipse Temurin 25) for the one-time resource preparation; and a GPU with Vulkan on Linux and Windows, or any Apple Silicon Mac.

@@ -36,31 +47,47 @@ Every subsystem matches vanilla in all 281 parity harnesses, on Linux and macOS:

 <table>
  <tr>
-    <td width="50%"><img src="launcher/docs/play.png" alt="The launcher's Play page"></td>
-    <td width="50%"><img src="launcher/docs/versions.png" alt="The launcher's Versions page"></td>
+    <td width="50%"><img src="docs/media/launcher-play.webp" alt="The launcher's Play page: v2026.10.14.1 ready to play, its summary, Client and Server, the version picker and Play, the resources and the Minecraft folder as a numbered list"></td>
+    <td width="50%"><img src="docs/media/launcher-patch-notes.webp" alt="The launcher's Patch notes page, showing the notes of Horizon 2026.10.14.1"></td>
  </tr>
 </table>

-It lists Horizon's releases and installs the build for your platform, shows each release's patch notes and the roadmap, updates Horizon and itself, and doubles as a command-line tool and an MCP server. See [the launcher's README](launcher/README.md).
+It lists Horizon's releases and installs the build for your platform, shows each release's patch notes, updates Horizon and itself, and doubles as a command-line tool and an MCP server. See [the launcher's README](launcher/README.md).

 ## Screenshots

 Captured in the Rust client itself, with vanilla assets and no mods or shaders.

+### Menus and settings
+
 <table>
  <tr>
-    <td colspan="2"><img src="docs/media/sunset.jpg" alt="Sunset over a savanna river valley and a plains village"></td>
+    <td colspan="2"><img src="docs/media/menu-title.webp" alt="Horizon's title screen: the mark and the pages on the left, the Horizon title, Singleplayer and Multiplayer, and the last world played and the faint wordmark, over a veiled snowy landscape"></td>
  </tr>
  <tr>
-    <td width="50%"><img src="docs/media/village.jpg" alt="A plains village with farms, an iron golem and animals"></td>
-    <td width="50%"><img src="docs/media/survival.jpg" alt="Survival at dusk: a zombie attacks near the village"></td>
+    <td width="50%"><img src="docs/media/menu-worlds.webp" alt="The Singleplayer page: three worlds with their dates and game modes, and Create world and Play buttons"></td>
+    <td width="50%"><img src="docs/media/settings.webp" alt="The Video settings in their Simple view: a preset, render distance, field of view, framerate, VSync and GUI scale, each with what it costs"></td>
+  </tr>
+</table>
+
+The vanilla menus are one setting away: Options → Interface → Menu style → Classic. See [Graphics settings](docs/graphics.md).
+
+### In game
+
+<table>
+  <tr>
+    <td colspan="2"><img src="docs/media/sunset.webp" alt="Sunset over a savanna river valley and a plains village"></td>
  </tr>
  <tr>
-    <td width="50%"><img src="docs/media/nether.jpg" alt="A crimson forest in the Nether with a zombified piglin"></td>
-    <td width="50%"><img src="docs/media/night.jpg" alt="Moonrise over a torch-lit village and river"></td>
+    <td width="50%"><img src="docs/media/village.webp" alt="A plains village with farms, an iron golem and animals"></td>
+    <td width="50%"><img src="docs/media/survival.webp" alt="Survival at dusk: a zombie attacks near the village"></td>
  </tr>
  <tr>
-    <td width="50%"><img src="docs/media/underwater.jpg" alt="Salmon swimming in a river"></td>
+    <td width="50%"><img src="docs/media/nether.webp" alt="A crimson forest in the Nether with a zombified piglin"></td>
+    <td width="50%"><img src="docs/media/night.webp" alt="Moonrise over a torch-lit village and river"></td>
+  </tr>
+  <tr>
+    <td width="50%"><img src="docs/media/underwater.webp" alt="Salmon swimming in a river"></td>
    <td width="50%" valign="middle">
      Vanilla world generation ported to Rust (terrain, aquifers, carvers, features, villages and the Nether), every block model with smooth lighting and biome tints, the vanilla sky and fog, mobs, the HUD, chat and advancements: everything in these frames is drawn by Horizon.
    </td>
@@ -86,9 +113,24 @@ The [native client](docs/native-client.md) opens on a vanilla-style title screen
 - shields, maps, books, fireworks, beacons, advancements and statistics;
 - Anvil saves, joining vanilla servers, and opening a world to LAN.

+## Agent control
+
+AI agents and scripts can play Horizon. `horizon-ctl`, shipped beside the game in every release folder, is a command line that reads the game as JSON and acts like a player; `horizon-ctl mcp` serves the same commands as an MCP server (one tool per command, screenshots returned as images).
+
+```sh
+horizon-ctl launch --world Survival --seed 5 --wait   # finds the version the launcher installed
+horizon-ctl state                                       # position, health, food, target, screen...
+horizon-ctl find-block birch_log                        # the nearest logs
+horizon-ctl goto -0.5 65 -2.5 --near 2.5                # walks there along a path
+horizon-ctl break -1 65 -3                              # mines it; replies with the drops
+horizon-ctl open-inventory && horizon-ctl click-slot 0  # menus: slots, buttons by label, text fields
+```
+
+Commands block until the action is done and reply with what happened; errors are JSON with distinct exit codes, `horizon-ctl help` lists every command and `horizon-ctl COMMAND --help` explains one with examples. It talks to the game over a Unix socket on Linux and macOS and over a token-protected localhost port on Windows. See [Agent control in the native client guide](docs/native-client.md#agent-control-horizon-ctl-and-mcp).
+
 ## Build from source

-For developers. Requirements: Rust 1.90 or newer, Python 3.10 or newer, JDK 25, and on Linux the ALSA development headers (`libasound2-dev` on Debian and Ubuntu). Development and the vanilla harnesses run on Linux.
+For developers. Requirements: Rust 1.90 or newer, Python 3.10 or newer, JDK 25, and on Linux the ALSA and udev development headers (`libasound2-dev libudev-dev` on Debian and Ubuntu). Development and the vanilla harnesses run on Linux.

 Horizon contains no game files and never downloads them. It builds its resources from **your own copy** of Minecraft: Java Edition 26.3, verified against the checksums in `research-lock.json`:

@@ -98,18 +140,18 @@ Horizon contains no game files and never downloads them. It builds its resources
 ```sh
 git clone https://github.com/ludovic111/horizon.git
 cd horizon
-python3 tools/prepare_native_client.py --prepare --server-jar ~/Downloads/server.jar   # needs JDK 25
-python3 tools/fetch_sounds.py                      # optional: sounds from your launcher install
+cargo run --release -p horizon-prepare -- --prepare --server-jar ~/Downloads/server.jar   # needs JDK 25
+cargo run --release -p horizon-prepare -- sounds   # optional: sounds from your launcher install
 cargo run --release -p horizon-client
 ```

 Everything prepared lands in the gitignored `.local/`. It is derived from the game: never commit it or share it.

-The client starts on the title screen. Command-line options (`--world`, `--seed`, `--creative`, `--render-distance`, `--dedicated`), controls, scripting through `horizon-ctl`, and the architecture are described in [the native client guide](docs/native-client.md). The rest of the documentation is indexed in [docs/README.md](docs/README.md), including [the parity workflow](docs/parity-workflow.md).
+The client starts on the title screen. Command-line options (`--world`, `--seed`, `--creative`, `--render-distance`, `--dedicated`), controls, playing and scripting through `horizon-ctl` and its MCP server, and the architecture are described in [the native client guide](docs/native-client.md). The rest of the documentation is indexed in [docs/README.md](docs/README.md), including [the parity workflow](docs/parity-workflow.md).

 ## Project status

-The table below is the project's own audit of each subsystem. Every subsystem now matches vanilla in every harness that compares it. 100% means 100% of what the harnesses compare, not proof that nothing else differs. The remaining known differences and the final checks are listed in the roadmap.
+The table below is the project's own audit of each subsystem. Every subsystem now matches vanilla in every harness that compares it. 100% means 100% of what the harnesses compare, not proof that nothing else differs. The remaining known differences are listed below.

 ### Java parity: 100%

@@ -138,34 +180,20 @@ them too (Rust uses Java's own float maths on each platform).
 | Audio | 1 | None: the sound engine, sound events, music, situational music, ambience and subtitles match vanilla |
 | Block behaviours and ticking | 1 | None: block updates, random ticks, redstone, dispensers (6,000 cases), crafters (4,000 crafts), block entity removal (containers spill, 4,000 cases), copper golem chest sorting and the sculk family (435 scenarios: shrieker warnings and warden summoning included) match vanilla |

-### Roadmap
+### Known issues

-**Known differences.** Online-mode servers (Mojang's session servers) are not supported; skins served over https show the default skin unless already cached; pack icons show the unknown-pack texture in game; the creative hotbar keys (C/X) aren't wired to the hotbar loader; item tooltips lack attribute lines.
-
-**Final checks.** A from-scratch audit (`tools/parity.py --all`) on Linux and on macOS, and the launch checks on the packaged Linux, macOS and Windows builds listed in [Rust rewrite status](docs/rust-parity.md#completion-criteria-and-playable-builds).
-
-**Next.** With vanilla parity as the base:
-
- **Performance:** optimize the client and the server as far as they can go (rendering, chunk generation and meshing, memory, multithreaded ticking) while the differential harnesses keep gameplay identical to vanilla.
- **Modding support:** a stable API for writing mods against Horizon.
- **Agent control:** an MCP server and a CLI so AI agents and scripts can play and drive the game, growing out of today's `horizon-ctl` scripting socket.
- **Built-in recording:** capture gameplay video in a keypress, without external tools.
- **Automatic version updates:** a pipeline that ports each new Minecraft release on its own: compare the new version with the pinned one, regenerate the data, rewrite the changed parts and prove them with the same differential harnesses.
+Online-mode servers (Mojang's session servers) are not supported; skins served over https show the default skin unless already cached; pack icons show the unknown-pack texture in game; the creative hotbar keys (C/X) aren't wired to the hotbar loader; item tooltips lack attribute lines.

 ## Contributing

-Issues and pull requests are welcome. Before opening a pull request, run the offline checks:
+Issues and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md) for how we work (vanilla first, small pull requests, labels). Before opening a pull request, run the self-check and paste the block it prints:

 ```sh
 git config core.hooksPath .githooks
-python3 -m unittest discover -s tests -v
-cargo fmt --all -- --check
-cargo clippy --workspace --all-targets -- -D warnings
-cargo test --workspace
-python3 tools/check_public_tree.py --history
+python3 tools/pr_ready.py
 ```

-CI runs these checks on GitHub's Linux runners. The vanilla comparisons need the game, which Horizon never downloads, so they run only when started by hand on a self-hosted runner holding the maintainer's own copy. Never commit game files, decompiled source or prepared resources: `tools/check_public_tree.py` rejects them, and tracked Java is allowed only under the project's own `dev/horizonlab` namespace.
+It runs rustfmt, clippy with warnings denied, the tests of the crates you touched, the Python tests, the public-tree check, and the vanilla harnesses your change can affect. CI runs the same checks on GitHub's Linux runners; the vanilla harnesses need the game, which Horizon never downloads, so they run on a self-hosted runner holding the maintainer's own copy. Never commit game files, decompiled source or prepared resources: `tools/check_public_tree.py` rejects them, and tracked Java is allowed only under the project's own `dev/horizonlab` namespace.

 ## Licence

@@ -0,0 +1,78 @@
+# Entity model document loading
+
+The three startup batches (boats/chest boats, minecarts, armor stands/player armor)
+now share one parsed document. For this fixture, that replaces 43 full document
+reads/parses (boat discovery plus 42 selected layers) with one. Selected models
+still produce independent `Part` trees; the document is dropped after the batches
+are built. Other entity loaders retain their existing behavior.
+
+## Reproduce
+
+From the repository root:
+
+```sh
+python3 benchmarks/entity-model-document-2026-10-14/generate_fixture.py /tmp/horizon-entity-model-document-fixture.json
+ENTITY_MODEL_BENCH_DOCUMENT=/tmp/horizon-entity-model-document-fixture.json \
+  CARGO_TARGET_DIR=/home/bob/Documents/horizon/target \
+  cargo test -p horizon-client --profile fast --bin horizon-client \
+  entity_model_document_benchmark -- --ignored --nocapture
+```
+
+`CARGO_TARGET_DIR` is optional and can be changed for another machine. Supply a
+prepared `entity-models.json` through `ENTITY_MODEL_BENCH_DOCUMENT` to benchmark
+that document instead; the harness copies only that file to a temporary root.
+`ENTITY_MODEL_BENCH_REPETITIONS` controls repetitions (default 15).
+
+The opt-in Rust test calls the actual three optimized production loaders and
+compares every selected part name, pose, polygon normal/vertex and child against
+the previous algorithm using the compatible per-model `load_model` API. Timings
+include reading, parsing, constructing, normalizing into a common result map, and
+dropping the result. Each variant gets three warmups and 15 measured calls, with
+order alternating. `black_box` consumes inputs/results. No other builds or
+optimization benchmarks ran during the measured calls.
+
+## Input and limitations
+
+Prepared resources were unavailable in the repository and local Horizon asset
+directories. This is a **synthetic** 2,473,695-byte document with 458 model layers,
+each containing 12 posed parts with six exported quads and normals. It selects 22
+boat/chest-boat layers, six minecart layers and 14 armor/player layers (42 total).
+One wood name is synthetic (`test_wood`); boat discovery accepts arbitrary wood
+names. The extra layers model the cost of parsing a full production-size document
+for each selected model.
+
+File data is warm in the OS page cache. Equipment files are absent, so equipment
+texture loading is excluded. This measures the entity-model batch only and does
+not establish overall startup, frame time or FPS improvement. Shapes/layer counts
+in real prepared documents can produce different absolute timings.
+
+Machine: AMD Ryzen 5 5600X (6 cores / 12 threads), Linux x86_64,
+Rust 1.99.0 (b940084d7, LLVM 23.1.1), Cargo `fast` profile (opt-level 3,
+16 codegen units, no LTO). Baseline algorithm corresponds to main
+`73a019967e9665c6b96332988c13cb66679d8477`.
+
+## Results
+
+| Variant | Median batch time | Full document reads/parses |
+| --- | ---: | ---: |
+| Previous per-model algorithm | 1,434.974 ms | 43 |
+| Shared document | 33.420 ms | 1 |
+
+The measured batch is **42.94× faster** on this synthetic input. All 15 samples
+for both variants, warmup count, document size and selected model count are in
+[`results.json`](results.json).
+
+## Validation
+
+```sh
+cargo fmt --all -- --check
+CARGO_TARGET_DIR=/home/bob/Documents/horizon/target \
+  cargo test -p horizon-client --profile fast --bin horizon-client \
+  entity_model_loading_tests -- --nocapture
+CARGO_TARGET_DIR=/home/bob/Documents/horizon/target \
+  cargo clippy -p horizon-client --profile fast --lib --bin horizon-client --tests -- -D warnings
+```
+
+The regular tests cover full/sparse documents, unrelated layers, a missing file,
+invalid JSON, non-object JSON, missing model keys, independent model trees, and
+equipment loading when the document is unavailable.
@@ -0,0 +1,31 @@
+"""Generate a production-size synthetic document; no prepared assets required."""
+import json
+import pathlib
+import sys
+
+woods = "oak spruce birch jungle acacia dark_oak mangrove cherry bamboo pale_oak test_wood".split()
+carts = "minecart chest_minecart hopper_minecart furnace_minecart tnt_minecart command_block_minecart".split()
+keys = [f"minecraft:{prefix}/{wood}#main" for prefix in ("boat", "chest_boat") for wood in woods]
+keys += [f"minecraft:{cart}#main" for cart in carts]
+keys += [f"minecraft:{model}#{slot}" for model in ("player", "armor_stand", "armor_stand_small")
+         for slot in ("helmet", "chestplate", "leggings", "boots")]
+keys += [f"minecraft:{model}#main" for model in ("armor_stand", "armor_stand_small")]
+
+face = [[0, 0, 0, 0, 0], [16, 0, 0, 1, 0], [16, 16, 0, 1, 1], [0, 16, 0, 0, 1]]
+part = {"pose": [1, 2, 3, 0.25, -0.5, 0.75, 1, 1, 1], "polygons": [face] * 6,
+        "normals": [[0, 0, 1]] * 6}
+model = {"pose": [0, 0, 0, 0, 0, 0, 1, 1, 1],
+         "children": {f"part_{i}": part for i in range(12)}}
+encoded = json.dumps(model, separators=(",", ":"))
+entries = [json.dumps(key) + ":" + encoded for key in keys]
+size = 2 + sum(map(len, entries)) + len(entries) - 1
+index = 0
+while size < 2_470_000:
+    entry = json.dumps(f"minecraft:fixture_{index}#main") + ":" + encoded
+    entries.append(entry)
+    size += 1 + len(entry)
+    index += 1
+output = pathlib.Path(sys.argv[1])
+output.write_text("{" + ",".join(entries) + "}")
+print(json.dumps({"path": str(output), "bytes": output.stat().st_size,
+                  "layers": len(entries), "selected_layers": len(keys)}))
@@ -0,0 +1,43 @@
+{
+  "baseline_median_ms": 1434.973835,
+  "baseline_ms": [
+    1400.008286,
+    1406.761694,
+    1408.9131360000001,
+    1418.6680549999999,
+    1419.149658,
+    1427.082872,
+    1433.088092,
+    1434.973835,
+    1449.7688150000001,
+    1452.143883,
+    1453.987998,
+    1455.518231,
+    1457.0334540000001,
+    1458.588552,
+    1485.34133
+  ],
+  "document_bytes": 2473695,
+  "optimized_median_ms": 33.419768000000005,
+  "optimized_ms": [
+    32.64795,
+    32.812732,
+    33.054488,
+    33.056914,
+    33.102999000000004,
+    33.23532,
+    33.28287,
+    33.419768000000005,
+    33.610569,
+    33.874749,
+    33.915657,
+    33.93877,
+    34.009893999999996,
+    34.550526,
+    36.096408000000004
+  ],
+  "repetitions": 15,
+  "selected_models": 42,
+  "speedup": 42.937875421516985,
+  "warmup_pairs": 3
+}
@@ -0,0 +1,546 @@
+{
+  "label": "after-4080",
+  "date": "2026-10-13",
+  "commit": "9006566b",
+  "host": "ludodesktop",
+  "offscreen": true,
+  "seed": "1234",
+  "flight_seconds": 12.0,
+  "scenes": {
+    "village": {
+      "from": [
+        -960.0,
+        125.0,
+        80.0
+      ],
+      "to": [
+        -960.0,
+        125.0,
+        272.0
+      ],
+      "pitch": 35.0
+    },
+    "forest": {
+      "from": [
+        -1100.0,
+        120.0,
+        -560.0
+      ],
+      "to": [
+        -1100.0,
+        120.0,
+        -368.0
+      ],
+      "pitch": 25.0
+    },
+    "ocean": {
+      "from": [
+        -300.0,
+        85.0,
+        -420.0
+      ],
+      "to": [
+        -300.0,
+        85.0,
+        -228.0
+      ],
+      "pitch": 10.0
+    },
+    "mountain": {
+      "from": [
+        560.0,
+        260.0,
+        860.0
+      ],
+      "to": [
+        752.0,
+        260.0,
+        860.0
+      ],
+      "pitch": 30.0
+    }
+  },
+  "distances": {
+    "8": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 133,
+        "gpu": "NVIDIA GeForce RTX 4080",
+        "present_mode": "Immediate",
+        "size": [
+          1280,
+          720
+        ],
+        "uploaded_bytes": 941908352
+      },
+      "village": {
+        "avg_fps": 2409.179688612205,
+        "cpu": {
+          "avg_ms": 0.41004928978864236,
+          "max_ms": 18.15971565246582,
+          "p50_ms": 0.2718150019645691,
+          "p95_ms": 0.7112299799919128,
+          "p99_ms": 1.316559076309204
+        },
+        "frames": 28910,
+        "gpu": {
+          "avg_ms": 0.09866036293994015,
+          "max_ms": 0.25088000297546387,
+          "p50_ms": 0.08806400001049042,
+          "p95_ms": 0.1740799993276596,
+          "p99_ms": 0.19968000054359436
+        },
+        "low_1pct_fps": 160.80638022914025,
+        "max_ms": 18.175312042236328,
+        "p50_ms": 0.2760099768638611,
+        "p95_ms": 0.7161250114440918,
+        "p99_ms": 1.4078609943389893,
+        "phases_avg_ms": {
+          "prepare": 0.20953580908804606,
+          "render": 0.12439006986512069,
+          "tick": 0.05299293669455945,
+          "update": 0.023244019639293335
+        },
+        "seconds": 11.999935138359666,
+        "slow_phases_avg_ms": {
+          "prepare": 0.4052206484151298,
+          "render": 0.41893499056840766,
+          "tick": 5.252727109792939,
+          "update": 0.0936474929949076
+        }
+      },
+      "forest": {
+        "avg_fps": 1099.4635681039538,
+        "cpu": {
+          "avg_ms": 0.9003613499442573,
+          "max_ms": 23.31729507446289,
+          "p50_ms": 0.6657320261001587,
+          "p95_ms": 0.9898859858512878,
+          "p99_ms": 9.592857360839844
+        },
+        "frames": 13194,
+        "gpu": {
+          "avg_ms": 0.2639814413552015,
+          "max_ms": 3.0013439655303955,
+          "p50_ms": 0.2549760043621063,
+          "p95_ms": 0.3553279936313629,
+          "p99_ms": 0.37171199917793274
+        },
+        "low_1pct_fps": 82.87026130908886,
+        "max_ms": 27.990703582763672,
+        "p50_ms": 0.6705269813537598,
+        "p95_ms": 1.0082690715789795,
+        "p99_ms": 9.64776611328125,
+        "phases_avg_ms": {
+          "prepare": 0.571024256178027,
+          "render": 0.12442494783992657,
+          "tick": 0.1706307831885292,
+          "update": 0.03442592136820218
+        },
+        "seconds": 12.000397632777691,
+        "slow_phases_avg_ms": {
+          "prepare": 0.7136096191225629,
+          "render": 0.43175565880356415,
+          "tick": 10.713303016893791,
+          "update": 0.05390534066651581
+        }
+      },
+      "ocean": {
+        "avg_fps": 687.0806476294383,
+        "cpu": {
+          "avg_ms": 1.4490217101725757,
+          "max_ms": 29.75178337097168,
+          "p50_ms": 0.9425880312919617,
+          "p95_ms": 1.6511069536209106,
+          "p99_ms": 15.603099822998047
+        },
+        "frames": 8245,
+        "gpu": {
+          "avg_ms": 0.3711021953564546,
+          "max_ms": 1.5022079944610596,
+          "p50_ms": 0.3665919899940491,
+          "p95_ms": 0.43827199935913086,
+          "p99_ms": 0.4679679870605469
+        },
+        "low_1pct_fps": 47.486143092805435,
+        "max_ms": 29.770263671875,
+        "p50_ms": 0.947784960269928,
+        "p95_ms": 1.6628600358963013,
+        "p99_ms": 15.621638298034668,
+        "phases_avg_ms": {
+          "prepare": 0.8449565766073126,
+          "render": 0.1554101111230668,
+          "tick": 0.3840128544967872,
+          "update": 0.06481705411812297
+        },
+        "seconds": 12.000046906352043,
+        "slow_phases_avg_ms": {
+          "prepare": 1.2885668083845851,
+          "render": 0.45316039797771407,
+          "tick": 19.216593845781073,
+          "update": 0.08380924088947744
+        }
+      },
+      "mountain": {
+        "avg_fps": 343.77852072094186,
+        "cpu": {
+          "avg_ms": 1.5961282111390964,
+          "max_ms": 22.24184799194336,
+          "p50_ms": 0.8254669904708862,
+          "p95_ms": 11.660508155822754,
+          "p99_ms": 14.398658752441406
+        },
+        "frames": 4113,
+        "gpu": {
+          "avg_ms": 0.3449904050323872,
+          "max_ms": 2.9040639400482178,
+          "p50_ms": 0.3338240087032318,
+          "p95_ms": 0.43724799156188965,
+          "p99_ms": 0.5171200037002563
+        },
+        "low_1pct_fps": 29.95597087331344,
+        "max_ms": 33.422760009765625,
+        "p50_ms": 0.8299460411071777,
+        "p95_ms": 33.33942413330078,
+        "p99_ms": 33.37727355957031,
+        "phases_avg_ms": {
+          "prepare": 0.7147062004496516,
+          "render": 0.14707977256612884,
+          "tick": 0.6855548198381525,
+          "update": 0.04897363143349227
+        },
+        "seconds": 11.96409825539589,
+        "slow_phases_avg_ms": {
+          "prepare": 0.8949875491006034,
+          "render": 0.6183000469491595,
+          "tick": 14.63794419879005,
+          "update": 0.8699657806594457
+        }
+      }
+    },
+    "16": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 0,
+        "gpu": "NVIDIA GeForce RTX 4080",
+        "present_mode": "Immediate",
+        "size": [
+          1280,
+          720
+        ],
+        "uploaded_bytes": 16462208
+      },
+      "village": {
+        "avg_fps": 1041.3622747953375,
+        "cpu": {
+          "avg_ms": 0.9549695556642304,
+          "max_ms": 26.009796142578125,
+          "p50_ms": 0.4810290038585663,
+          "p95_ms": 2.5506999492645264,
+          "p99_ms": 9.879941940307617
+        },
+        "frames": 12496,
+        "gpu": {
+          "avg_ms": 0.22781361336253403,
+          "max_ms": 1.7469439506530762,
+          "p50_ms": 0.18534399569034576,
+          "p95_ms": 0.6113280057907104,
+          "p99_ms": 0.809984028339386
+        },
+        "low_1pct_fps": 64.04348583959742,
+        "max_ms": 26.032779693603516,
+        "p50_ms": 0.48582199215888977,
+        "p95_ms": 2.5584940910339355,
+        "p99_ms": 9.892412185668945,
+        "phases_avg_ms": {
+          "prepare": 0.37678885421859964,
+          "render": 0.3450905326050295,
+          "tick": 0.1742891420732452,
+          "update": 0.0590072420405441
+        },
+        "seconds": 11.999666496902703,
+        "slow_phases_avg_ms": {
+          "prepare": 1.4649118003845214,
+          "render": 1.1414484503269196,
+          "tick": 12.881806396484375,
+          "update": 0.11011978423595428
+        }
+      },
+      "forest": {
+        "avg_fps": 316.2068527731055,
+        "cpu": {
+          "avg_ms": 3.154168446387541,
+          "max_ms": 26.147607803344727,
+          "p50_ms": 2.2156569957733154,
+          "p95_ms": 12.254712104797363,
+          "p99_ms": 17.7707462310791
+        },
+        "frames": 3795,
+        "gpu": {
+          "avg_ms": 0.7502970771905776,
+          "max_ms": 2.599936008453369,
+          "p50_ms": 0.7239680290222168,
+          "p95_ms": 1.3158400058746338,
+          "p99_ms": 1.3772799968719482
+        },
+        "low_1pct_fps": 49.59272936233826,
+        "max_ms": 26.164094924926758,
+        "p50_ms": 2.222438097000122,
+        "p95_ms": 12.270298957824707,
+        "p99_ms": 17.786956787109375,
+        "phases_avg_ms": {
+          "prepare": 1.5666706890613822,
+          "render": 0.7056146899387927,
+          "tick": 0.7469899302897249,
+          "update": 0.13521884845002838
+        },
+        "seconds": 12.001637430429458,
+        "slow_phases_avg_ms": {
+          "prepare": 1.9408628783727948,
+          "render": 1.194917630208166,
+          "tick": 16.762235842253034,
+          "update": 0.24904731876756014
+        }
+      },
+      "ocean": {
+        "avg_fps": 385.09978163469907,
+        "cpu": {
+          "avg_ms": 2.589322079316407,
+          "max_ms": 18.984909057617188,
+          "p50_ms": 2.0551369190216064,
+          "p95_ms": 8.740593910217285,
+          "p99_ms": 11.559625625610352
+        },
+        "frames": 4622,
+        "gpu": {
+          "avg_ms": 0.6778284030938654,
+          "max_ms": 2.398207902908325,
+          "p50_ms": 0.7833600044250488,
+          "p95_ms": 0.9431040287017822,
+          "p99_ms": 1.511423945426941
+        },
+        "low_1pct_fps": 71.97424221133898,
+        "max_ms": 19.0070858001709,
+        "p50_ms": 2.061105966567993,
+        "p95_ms": 8.753417015075684,
+        "p99_ms": 11.577004432678223,
+        "phases_avg_ms": {
+          "prepare": 1.3568510900633204,
+          "render": 0.7359144338432817,
+          "tick": 0.41578289517198963,
+          "update": 0.0810434000275639
+        },
+        "seconds": 12.002084188103677,
+        "slow_phases_avg_ms": {
+          "prepare": 1.6523635336693296,
+          "render": 1.2426407299143203,
+          "tick": 10.818658037388579,
+          "update": 0.16372418847489864
+        }
+      },
+      "mountain": {
+        "avg_fps": 219.70895893367268,
+        "cpu": {
+          "avg_ms": 3.098228604710274,
+          "max_ms": 23.518693923950195,
+          "p50_ms": 2.0422279834747314,
+          "p95_ms": 10.511551856994629,
+          "p99_ms": 16.436803817749023
+        },
+        "frames": 2634,
+        "gpu": {
+          "avg_ms": 0.9377313036310374,
+          "max_ms": 9.588735580444336,
+          "p50_ms": 0.8488960266113281,
+          "p95_ms": 0.9728000164031982,
+          "p99_ms": 3.4201600551605225
+        },
+        "low_1pct_fps": 29.957383952355947,
+        "max_ms": 33.38852310180664,
+        "p50_ms": 2.0481808185577393,
+        "p95_ms": 33.341556549072266,
+        "p99_ms": 33.377445220947266,
+        "phases_avg_ms": {
+          "prepare": 1.3405477057013806,
+          "render": 0.8202416233113071,
+          "tick": 0.8190081106798682,
+          "update": 0.11872799601335143
+        },
+        "seconds": 11.988587141752243,
+        "slow_phases_avg_ms": {
+          "prepare": 1.648652986243919,
+          "render": 1.7585702317732352,
+          "tick": 14.372832368921351,
+          "update": 1.0560209235107456
+        }
+      }
+    },
+    "32": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 212,
+        "gpu": "NVIDIA GeForce RTX 4080",
+        "present_mode": "Immediate",
+        "size": [
+          1280,
+          720
+        ],
+        "uploaded_bytes": 255897088
+      },
+      "village": {
+        "avg_fps": 48.3055081533635,
+        "cpu": {
+          "avg_ms": 9.376506657416572,
+          "max_ms": 861.2249145507812,
+          "p50_ms": 3.0502548217773438,
+          "p95_ms": 32.94725036621094,
+          "p99_ms": 74.04153442382812
+        },
+        "frames": 1271,
+        "gpu": {
+          "avg_ms": 1.7700931664342303,
+          "max_ms": 20.69094467163086,
+          "p50_ms": 1.2410880327224731,
+          "p95_ms": 7.598080158233643,
+          "p99_ms": 15.925248146057129
+        },
+        "low_1pct_fps": 0.761712600806078,
+        "max_ms": 14330.3583984375,
+        "p50_ms": 3.071429967880249,
+        "p95_ms": 33.099002838134766,
+        "p99_ms": 75.7547378540039,
+        "phases_avg_ms": {
+          "prepare": 1.518610580008767,
+          "render": 1.6828305973582713,
+          "tick": 5.15484752775804,
+          "update": 1.020680267595335
+        },
+        "seconds": 26.31169919514656,
+        "slow_phases_avg_ms": {
+          "prepare": 0.9654910931220422,
+          "render": 3.5708756630237284,
+          "tick": 196.6683132465069,
+          "update": 14.971596607795128
+        }
+      },
+      "forest": {
+        "avg_fps": 27.53318156189366,
+        "cpu": {
+          "avg_ms": 40.13187835841161,
+          "max_ms": 1166.3994140625,
+          "p50_ms": 6.5535569190979,
+          "p95_ms": 63.877315521240234,
+          "p99_ms": 1108.11865234375
+        },
+        "frames": 271,
+        "gpu": {
+          "avg_ms": 2.297342118961785,
+          "max_ms": 22.554624557495117,
+          "p50_ms": 0.7065600156784058,
+          "p95_ms": 7.245823860168457,
+          "p99_ms": 9.055232048034668
+        },
+        "low_1pct_fps": 0.8848759980013957,
+        "max_ms": 1166.4168701171875,
+        "p50_ms": 6.675865173339844,
+        "p95_ms": 59.150550842285156,
+        "p99_ms": 1108.134521484375,
+        "phases_avg_ms": {
+          "prepare": 2.83869483858017,
+          "render": 2.5961379855321343,
+          "tick": 33.04425997872419,
+          "update": 1.6535338119387186
+        },
+        "seconds": 9.842669267654419,
+        "slow_phases_avg_ms": {
+          "prepare": 2.766425689061483,
+          "render": 4.919464270273845,
+          "tick": 1112.3431803385417,
+          "update": 10.057182629903158
+        }
+      },
+      "ocean": {
+        "avg_fps": 67.01857611699128,
+        "cpu": {
+          "avg_ms": 14.669945189483148,
+          "max_ms": 113.66764068603516,
+          "p50_ms": 4.473541736602783,
+          "p95_ms": 51.374263763427734,
+          "p99_ms": 94.75230407714844
+        },
+        "frames": 802,
+        "gpu": {
+          "avg_ms": 2.9074973299021734,
+          "max_ms": 22.526975631713867,
+          "p50_ms": 1.8206720352172852,
+          "p95_ms": 8.869888305664062,
+          "p99_ms": 11.596799850463867
+        },
+        "low_1pct_fps": 10.111656570136391,
+        "max_ms": 113.68443298339844,
+        "p50_ms": 4.488469123840332,
+        "p95_ms": 51.39033508300781,
+        "p99_ms": 94.76870727539062,
+        "phases_avg_ms": {
+          "prepare": 2.4291724538862556,
+          "render": 2.242118674918006,
+          "tick": 9.334139847333992,
+          "update": 0.6651962902814967
+        },
+        "seconds": 11.966831384181976,
+        "slow_phases_avg_ms": {
+          "prepare": 2.7512698968251548,
+          "render": 3.2687110900878906,
+          "tick": 90.47323608398438,
+          "update": 2.3865103986528187
+        }
+      },
+      "mountain": {
+        "avg_fps": 28.70327462003782,
+        "cpu": {
+          "avg_ms": 16.062305691622306,
+          "max_ms": 67.72319793701172,
+          "p50_ms": 10.215509414672852,
+          "p95_ms": 45.747154235839844,
+          "p99_ms": 63.64399337768555
+        },
+        "frames": 345,
+        "gpu": {
+          "avg_ms": 8.470281650363535,
+          "max_ms": 21.519359588623047,
+          "p50_ms": 8.845312118530273,
+          "p95_ms": 15.868927955627441,
+          "p99_ms": 17.557504653930664
+        },
+        "low_1pct_fps": 15.182693348952107,
+        "max_ms": 67.74352264404297,
+        "p50_ms": 33.36533737182617,
+        "p95_ms": 46.64082336425781,
+        "p99_ms": 63.65925979614258,
+        "phases_avg_ms": {
+          "prepare": 0.8729904708654984,
+          "render": 3.4296869785889337,
+          "tick": 8.941314909811826,
+          "update": 2.8190046198558116
+        },
+        "seconds": 12.01953451538086,
+        "slow_phases_avg_ms": {
+          "prepare": 0.8918330073356628,
+          "render": 4.432150959968567,
+          "tick": 50.667978286743164,
+          "update": 9.854933142662048
+        }
+      }
+    }
+  },
+  "load_before": [
+    1.86328125,
+    2.111328125,
+    3.9072265625
+  ],
+  "load_after": [
+    8.4560546875,
+    5.08544921875,
+    4.68798828125
+  ]
+}
@@ -0,0 +1,546 @@
+{
+  "label": "after-lavapipe",
+  "date": "2026-10-13",
+  "commit": "9006566b",
+  "host": "ludodesktop",
+  "offscreen": false,
+  "seed": "1234",
+  "flight_seconds": 12.0,
+  "scenes": {
+    "village": {
+      "from": [
+        -960.0,
+        125.0,
+        80.0
+      ],
+      "to": [
+        -960.0,
+        125.0,
+        272.0
+      ],
+      "pitch": 35.0
+    },
+    "forest": {
+      "from": [
+        -1100.0,
+        120.0,
+        -560.0
+      ],
+      "to": [
+        -1100.0,
+        120.0,
+        -368.0
+      ],
+      "pitch": 25.0
+    },
+    "ocean": {
+      "from": [
+        -300.0,
+        85.0,
+        -420.0
+      ],
+      "to": [
+        -300.0,
+        85.0,
+        -228.0
+      ],
+      "pitch": 10.0
+    },
+    "mountain": {
+      "from": [
+        560.0,
+        260.0,
+        860.0
+      ],
+      "to": [
+        752.0,
+        260.0,
+        860.0
+      ],
+      "pitch": 30.0
+    }
+  },
+  "distances": {
+    "8": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 156,
+        "gpu": "llvmpipe (LLVM 21.1.8, 256 bits)",
+        "present_mode": "Mailbox",
+        "size": [
+          1600,
+          1000
+        ],
+        "uploaded_bytes": 1278284288
+      },
+      "village": {
+        "avg_fps": 58.3354572261441,
+        "cpu": {
+          "avg_ms": 11.363309368576322,
+          "max_ms": 36.24496841430664,
+          "p50_ms": 13.213258743286133,
+          "p95_ms": 19.535802841186523,
+          "p99_ms": 24.83148956298828
+        },
+        "frames": 700,
+        "gpu": {
+          "avg_ms": 13.518205827985492,
+          "max_ms": 34.97639083862305,
+          "p50_ms": 13.195829391479492,
+          "p95_ms": 18.039182662963867,
+          "p99_ms": 23.378856658935547
+        },
+        "low_1pct_fps": 31.312386939419746,
+        "max_ms": 36.36259078979492,
+        "p50_ms": 16.02706527709961,
+        "p95_ms": 21.249738693237305,
+        "p99_ms": 29.130090713500977,
+        "phases_avg_ms": {
+          "prepare": 0.2306461141364915,
+          "render": 9.720663217795746,
+          "tick": 1.3112367039202113,
+          "update": 0.10169148096282567
+        },
+        "seconds": 11.99956310081482,
+        "slow_phases_avg_ms": {
+          "prepare": 0.35282185673713684,
+          "render": 25.05345916748047,
+          "tick": 3.1022580585309436,
+          "update": 0.38026727948869976
+        }
+      },
+      "forest": {
+        "avg_fps": 41.90001789962103,
+        "cpu": {
+          "avg_ms": 18.045572770611635,
+          "max_ms": 36.546627044677734,
+          "p50_ms": 20.543725967407227,
+          "p95_ms": 30.5231990814209,
+          "p99_ms": 34.017364501953125
+        },
+        "frames": 504,
+        "gpu": {
+          "avg_ms": 21.35815803588383,
+          "max_ms": 36.23066329956055,
+          "p50_ms": 19.825437545776367,
+          "p95_ms": 29.274858474731445,
+          "p99_ms": 33.32203674316406
+        },
+        "low_1pct_fps": 20.022920779459263,
+        "max_ms": 99.08029174804688,
+        "p50_ms": 22.576229095458984,
+        "p95_ms": 32.772239685058594,
+        "p99_ms": 36.67753982543945,
+        "phases_avg_ms": {
+          "prepare": 0.22351377572686898,
+          "render": 16.234788014183916,
+          "tick": 1.4387834655649459,
+          "update": 0.14943464463281017
+        },
+        "seconds": 12.028634479522704,
+        "slow_phases_avg_ms": {
+          "prepare": 0.2705736731489499,
+          "render": 32.015567461649574,
+          "tick": 2.741411516830946,
+          "update": 0.3076988315830628
+        }
+      },
+      "ocean": {
+        "avg_fps": 60.413862302111134,
+        "cpu": {
+          "avg_ms": 10.874024665643429,
+          "max_ms": 29.430055618286133,
+          "p50_ms": 12.944002151489258,
+          "p95_ms": 17.997587203979492,
+          "p99_ms": 25.568126678466797
+        },
+        "frames": 725,
+        "gpu": {
+          "avg_ms": 12.736994123787715,
+          "max_ms": 28.143625259399414,
+          "p50_ms": 12.234904289245605,
+          "p95_ms": 15.61594295501709,
+          "p99_ms": 24.476089477539062
+        },
+        "low_1pct_fps": 34.82401357005238,
+        "max_ms": 33.36631393432617,
+        "p50_ms": 16.01299476623535,
+        "p95_ms": 18.74709701538086,
+        "p99_ms": 26.6020565032959,
+        "phases_avg_ms": {
+          "prepare": 0.4042872669162421,
+          "render": 9.401332649341946,
+          "tick": 0.9126873913477977,
+          "update": 0.15663292961387798
+        },
+        "seconds": 12.000557030677795,
+        "slow_phases_avg_ms": {
+          "prepare": 0.3962315060198307,
+          "render": 26.506223678588867,
+          "tick": 0.0020812499860767275,
+          "update": 0.5454612672328949
+        }
+      },
+      "mountain": {
+        "avg_fps": 37.77761368324693,
+        "cpu": {
+          "avg_ms": 11.491443304826092,
+          "max_ms": 34.474151611328125,
+          "p50_ms": 13.871685981750488,
+          "p95_ms": 20.351163864135742,
+          "p99_ms": 23.77434539794922
+        },
+        "frames": 453,
+        "gpu": {
+          "avg_ms": 14.109076927302953,
+          "max_ms": 35.115882873535156,
+          "p50_ms": 13.555350303649902,
+          "p95_ms": 18.336809158325195,
+          "p99_ms": 30.865131378173828
+        },
+        "low_1pct_fps": 27.343844611059406,
+        "max_ms": 39.0676155090332,
+        "p50_ms": 33.33863830566406,
+        "p95_ms": 33.36062240600586,
+        "p99_ms": 34.297752380371094,
+        "phases_avg_ms": {
+          "prepare": 0.22927819613457778,
+          "render": 9.350584785242217,
+          "tick": 1.7383085893987211,
+          "update": 0.17420387428015405
+        },
+        "seconds": 11.991228556632995,
+        "slow_phases_avg_ms": {
+          "prepare": 0.2908208012580872,
+          "render": 25.648976135253907,
+          "tick": 1.9043863375205548,
+          "update": 0.7624145835638046
+        }
+      }
+    },
+    "16": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 0,
+        "gpu": "llvmpipe (LLVM 21.1.8, 256 bits)",
+        "present_mode": "Mailbox",
+        "size": [
+          1600,
+          1000
+        ],
+        "uploaded_bytes": 36807552
+      },
+      "village": {
+        "avg_fps": 20.701493975921895,
+        "cpu": {
+          "avg_ms": 31.808356682459515,
+          "max_ms": 74.47195434570312,
+          "p50_ms": 41.86561584472656,
+          "p95_ms": 56.75548553466797,
+          "p99_ms": 73.00084686279297
+        },
+        "frames": 249,
+        "gpu": {
+          "avg_ms": 40.500388481140135,
+          "max_ms": 67.22461700439453,
+          "p50_ms": 40.38219451904297,
+          "p95_ms": 50.01243209838867,
+          "p99_ms": 62.00723648071289
+        },
+        "low_1pct_fps": 8.83914293384798,
+        "max_ms": 133.2972869873047,
+        "p50_ms": 47.37559509277344,
+        "p95_ms": 61.3382682800293,
+        "p99_ms": 74.61792755126953,
+        "phases_avg_ms": {
+          "prepare": 0.30830518620081215,
+          "render": 25.584145257750667,
+          "tick": 5.116575629957185,
+          "update": 0.8002672145165592
+        },
+        "seconds": 12.028117404937744,
+        "slow_phases_avg_ms": {
+          "prepare": 0.3641819953918457,
+          "render": 44.77838750680288,
+          "tick": 6.285618623097737,
+          "update": 22.415442685286205
+        }
+      },
+      "forest": {
+        "avg_fps": 18.118065350089793,
+        "cpu": {
+          "avg_ms": 36.827518428137545,
+          "max_ms": 85.7597427368164,
+          "p50_ms": 49.536197662353516,
+          "p95_ms": 62.31198501586914,
+          "p99_ms": 66.591064453125
+        },
+        "frames": 218,
+        "gpu": {
+          "avg_ms": 47.82228247616269,
+          "max_ms": 76.9173355102539,
+          "p50_ms": 46.98957824707031,
+          "p95_ms": 57.49673843383789,
+          "p99_ms": 69.92066192626953
+        },
+        "low_1pct_fps": 11.528998473378772,
+        "max_ms": 93.62928009033203,
+        "p50_ms": 53.71598434448242,
+        "p95_ms": 66.69908905029297,
+        "p99_ms": 80.71000671386719,
+        "phases_avg_ms": {
+          "prepare": 0.29564340877423595,
+          "render": 30.678313442326466,
+          "tick": 4.647872053591402,
+          "update": 1.206680115073099
+        },
+        "seconds": 12.032189739227295,
+        "slow_phases_avg_ms": {
+          "prepare": 0.37793900569279987,
+          "render": 66.15962092081706,
+          "tick": 5.583541075388591,
+          "update": 1.5741689602533977
+        }
+      },
+      "ocean": {
+        "avg_fps": 8.272097120557788,
+        "cpu": {
+          "avg_ms": 96.70907358733974,
+          "max_ms": 208.84027099609375,
+          "p50_ms": 89.04510498046875,
+          "p95_ms": 169.3397979736328,
+          "p99_ms": 208.84027099609375
+        },
+        "frames": 98,
+        "gpu": {
+          "avg_ms": 57.298700176939676,
+          "max_ms": 66.62165832519531,
+          "p50_ms": 57.89077377319336,
+          "p95_ms": 65.73504638671875,
+          "p99_ms": 66.62165832519531
+        },
+        "low_1pct_fps": 4.785729156618201,
+        "max_ms": 208.95457458496094,
+        "p50_ms": 140.0601348876953,
+        "p95_ms": 178.57022094726562,
+        "p99_ms": 208.95457458496094,
+        "phases_avg_ms": {
+          "prepare": 3.3946731230434106,
+          "render": 34.994675042982,
+          "tick": 57.14290783599932,
+          "update": 1.177816742536973
+        },
+        "seconds": 11.847056262969971,
+        "slow_phases_avg_ms": {
+          "prepare": 7.7776899337768555,
+          "render": 70.36097717285156,
+          "tick": 128.46734619140625,
+          "update": 2.2351090908050537
+        }
+      },
+      "mountain": {
+        "avg_fps": 11.65883600782651,
+        "cpu": {
+          "avg_ms": 56.6912090659987,
+          "max_ms": 107.11215209960938,
+          "p50_ms": 77.04230499267578,
+          "p95_ms": 97.60908508300781,
+          "p99_ms": 104.08527374267578
+        },
+        "frames": 141,
+        "gpu": {
+          "avg_ms": 70.81221792731486,
+          "max_ms": 96.33728790283203,
+          "p50_ms": 69.16046905517578,
+          "p95_ms": 86.61634063720703,
+          "p99_ms": 92.56858825683594
+        },
+        "low_1pct_fps": 4.93309783391495,
+        "max_ms": 216.64273071289062,
+        "p50_ms": 81.59197235107422,
+        "p95_ms": 104.20377349853516,
+        "p99_ms": 188.7820281982422,
+        "phases_avg_ms": {
+          "prepare": 0.31791428133105554,
+          "render": 45.35119773817401,
+          "tick": 9.391353438086544,
+          "update": 1.6317692605104852
+        },
+        "seconds": 12.093831657409668,
+        "slow_phases_avg_ms": {
+          "prepare": 0.348672017455101,
+          "render": 86.63534545898438,
+          "tick": 13.065274715423584,
+          "update": 5.5503233671188354
+        }
+      }
+    },
+    "32": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 119,
+        "gpu": "llvmpipe (LLVM 21.1.8, 256 bits)",
+        "present_mode": "Mailbox",
+        "size": [
+          1600,
+          1000
+        ],
+        "uploaded_bytes": 222619264
+      },
+      "village": {
+        "avg_fps": 5.310476400246329,
+        "cpu": {
+          "avg_ms": 111.2176975607872,
+          "max_ms": 224.16696166992188,
+          "p50_ms": 76.4469985961914,
+          "p95_ms": 218.82273864746094,
+          "p99_ms": 224.16696166992188
+        },
+        "frames": 64,
+        "gpu": {
+          "avg_ms": 121.35315322875977,
+          "max_ms": 171.11207580566406,
+          "p50_ms": 125.45780944824219,
+          "p95_ms": 166.71322631835938,
+          "p99_ms": 171.11207580566406
+        },
+        "low_1pct_fps": 3.59762228435401,
+        "max_ms": 277.96136474609375,
+        "p50_ms": 192.1078338623047,
+        "p95_ms": 232.86318969726562,
+        "p99_ms": 277.96136474609375,
+        "phases_avg_ms": {
+          "prepare": 0.524940284434706,
+          "render": 56.89460512250662,
+          "tick": 38.0364211499691,
+          "update": 15.762759290635586
+        },
+        "seconds": 12.051649452209473,
+        "slow_phases_avg_ms": {
+          "prepare": 0.5129500031471252,
+          "render": 147.3928985595703,
+          "tick": 62.813438415527344,
+          "update": 13.448556900024414
+        }
+      },
+      "forest": {
+        "avg_fps": 3.899515654388116,
+        "cpu": {
+          "avg_ms": 155.46855975211935,
+          "max_ms": 270.7467041015625,
+          "p50_ms": 83.60679626464844,
+          "p95_ms": 268.6576843261719,
+          "p99_ms": 270.7467041015625
+        },
+        "frames": 47,
+        "gpu": {
+          "avg_ms": 192.77972445280656,
+          "max_ms": 225.69723510742188,
+          "p50_ms": 189.4962615966797,
+          "p95_ms": 217.36190795898438,
+          "p99_ms": 225.69723510742188
+        },
+        "low_1pct_fps": 3.3773198460417087,
+        "max_ms": 296.0927734375,
+        "p50_ms": 259.49017333984375,
+        "p95_ms": 283.4007568359375,
+        "p99_ms": 296.0927734375,
+        "phases_avg_ms": {
+          "prepare": 0.5114446409205173,
+          "render": 99.58217374821926,
+          "tick": 43.03971359577585,
+          "update": 12.336258025879555
+        },
+        "seconds": 12.052778900146484,
+        "slow_phases_avg_ms": {
+          "prepare": 0.5626839995384216,
+          "render": 208.71124267578125,
+          "tick": 53.47932052612305,
+          "update": 7.994467258453369
+        }
+      },
+      "ocean": {
+        "avg_fps": 2.9455219461811217,
+        "cpu": {
+          "avg_ms": 287.98993862376494,
+          "max_ms": 464.7646484375,
+          "p50_ms": 286.4447326660156,
+          "p95_ms": 444.6121520996094,
+          "p99_ms": 464.7646484375
+        },
+        "frames": 34,
+        "gpu": {
+          "avg_ms": 116.96576734270369,
+          "max_ms": 158.26394653320312,
+          "p50_ms": 106.45819854736328,
+          "p95_ms": 158.1454620361328,
+          "p99_ms": 158.26394653320312
+        },
+        "low_1pct_fps": 2.151113067092828,
+        "max_ms": 464.8756103515625,
+        "p50_ms": 315.1367492675781,
+        "p95_ms": 456.3304138183594,
+        "p99_ms": 464.8756103515625,
+        "phases_avg_ms": {
+          "prepare": 4.395756518139558,
+          "render": 69.52432030789993,
+          "tick": 206.13154108384077,
+          "update": 7.93927874284632
+        },
+        "seconds": 11.542945739746093,
+        "slow_phases_avg_ms": {
+          "prepare": 4.144052982330322,
+          "render": 166.14959716796875,
+          "tick": 285.5132751464844,
+          "update": 8.958683967590332
+        }
+      },
+      "mountain": {
+        "avg_fps": 3.983176689759444,
+        "cpu": {
+          "avg_ms": 171.41208145466257,
+          "max_ms": 413.8367919921875,
+          "p50_ms": 164.3318328857422,
+          "p95_ms": 360.7731628417969,
+          "p99_ms": 413.8367919921875
+        },
+        "frames": 47,
+        "gpu": {
+          "avg_ms": 166.80018520355225,
+          "max_ms": 304.8785400390625,
+          "p50_ms": 143.19728088378906,
+          "p95_ms": 275.3953552246094,
+          "p99_ms": 304.8785400390625
+        },
+        "low_1pct_fps": 2.418344167836982,
+        "max_ms": 413.5060729980469,
+        "p50_ms": 230.7030029296875,
+        "p95_ms": 365.4028625488281,
+        "p99_ms": 413.5060729980469,
+        "phases_avg_ms": {
+          "prepare": 0.496992789684458,
+          "render": 94.4349257743105,
+          "tick": 61.33542941478973,
+          "update": 15.14569672117842
+        },
+        "seconds": 11.799627197265625,
+        "slow_phases_avg_ms": {
+          "prepare": 0.4748440086841583,
+          "render": 312.3215637207031,
+          "tick": 86.37409973144531,
+          "update": 14.667168617248535
+        }
+      }
+    }
+  },
+  "load_before": [
+    8.4560546875,
+    5.08544921875,
+    4.68798828125
+  ],
+  "load_after": [
+    10.98291015625,
+    7.201171875,
+    5.5615234375
+  ]
+}
@@ -0,0 +1,392 @@
+{
+  "label": "baseline-4080",
+  "date": "2026-10-13",
+  "commit": "27a32cc3",
+  "host": "ludodesktop",
+  "offscreen": true,
+  "seed": "1234",
+  "flight_seconds": 12.0,
+  "scenes": {
+    "village": {
+      "from": [
+        -960.0,
+        125.0,
+        80.0
+      ],
+      "to": [
+        -960.0,
+        125.0,
+        272.0
+      ],
+      "pitch": 35.0
+    },
+    "forest": {
+      "from": [
+        -1100.0,
+        120.0,
+        -560.0
+      ],
+      "to": [
+        -1100.0,
+        120.0,
+        -368.0
+      ],
+      "pitch": 25.0
+    },
+    "ocean": {
+      "from": [
+        -300.0,
+        85.0,
+        -420.0
+      ],
+      "to": [
+        -300.0,
+        85.0,
+        -228.0
+      ],
+      "pitch": 10.0
+    },
+    "mountain": {
+      "from": [
+        560.0,
+        260.0,
+        860.0
+      ],
+      "to": [
+        752.0,
+        260.0,
+        860.0
+      ],
+      "pitch": 30.0
+    }
+  },
+  "distances": {
+    "8": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 158,
+        "gpu": "NVIDIA GeForce RTX 4080",
+        "present_mode": "Immediate",
+        "size": [
+          1280,
+          720
+        ],
+        "uploaded_bytes": 1137747200
+      },
+      "village": {
+        "avg_fps": 362.94072531330323,
+        "cpu": {
+          "avg_ms": 2.734311161203731,
+          "max_ms": 68.06377410888672,
+          "p50_ms": 1.4820960760116577,
+          "p95_ms": 7.922675609588623,
+          "p99_ms": 35.78989028930664
+        },
+        "frames": 4373,
+        "gpu": {
+          "avg_ms": 0.4188921034758625,
+          "max_ms": 2.5876479148864746,
+          "p50_ms": 0.4106239974498749,
+          "p95_ms": 0.5283839702606201,
+          "p99_ms": 0.5427200198173523
+        },
+        "low_1pct_fps": 21.64332698060583,
+        "max_ms": 68.08219146728516,
+        "p50_ms": 1.4894599914550781,
+        "p95_ms": 7.936410427093506,
+        "p99_ms": 36.54151153564453,
+        "seconds": 12.048799418210983
+      },
+      "forest": {
+        "avg_fps": 613.1553113846195,
+        "cpu": {
+          "avg_ms": 1.6186122214214547,
+          "max_ms": 216.98960876464844,
+          "p50_ms": 1.10076105594635,
+          "p95_ms": 3.0016868114471436,
+          "p99_ms": 10.144570350646973
+        },
+        "frames": 6746,
+        "gpu": {
+          "avg_ms": 0.395751640401594,
+          "max_ms": 1.99782395362854,
+          "p50_ms": 0.3983359932899475,
+          "p95_ms": 0.4833280146121979,
+          "p99_ms": 0.5375999808311462
+        },
+        "low_1pct_fps": 49.639170314777054,
+        "max_ms": 217.0211181640625,
+        "p50_ms": 1.109616994857788,
+        "p95_ms": 3.0161218643188477,
+        "p99_ms": 10.163111686706543,
+        "seconds": 11.002106439828873
+      },
+      "ocean": {
+        "avg_fps": 323.23791637473414,
+        "cpu": {
+          "avg_ms": 2.7230400277200597,
+          "max_ms": 4748.7744140625,
+          "p50_ms": 0.9233829975128174,
+          "p95_ms": 1.677724003791809,
+          "p99_ms": 7.7397589683532715
+        },
+        "frames": 3870,
+        "gpu": {
+          "avg_ms": 0.24116999250656182,
+          "max_ms": 0.954367995262146,
+          "p50_ms": 0.2754560112953186,
+          "p95_ms": 0.3389439880847931,
+          "p99_ms": 0.3532800078392029
+        },
+        "low_1pct_fps": 5.421154869716093,
+        "max_ms": 4748.80615234375,
+        "p50_ms": 0.9285120368003845,
+        "p95_ms": 1.7079449892044067,
+        "p99_ms": 33.33257293701172,
+        "seconds": 11.97260532861948
+      },
+      "mountain": {
+        "avg_fps": 28.19080143244723,
+        "cpu": {
+          "avg_ms": 12.358911560308298,
+          "max_ms": 187.3409881591797,
+          "p50_ms": 9.513923645019531,
+          "p95_ms": 25.783824920654297,
+          "p99_ms": 110.71585845947266
+        },
+        "frames": 338,
+        "gpu": {
+          "avg_ms": 0.46002139662497143,
+          "max_ms": 1.5626239776611328,
+          "p50_ms": 0.4546560049057007,
+          "p95_ms": 0.5140479803085327,
+          "p99_ms": 0.5959680080413818
+        },
+        "low_1pct_fps": 7.428141780247131,
+        "max_ms": 187.36033630371094,
+        "p50_ms": 33.334835052490234,
+        "p95_ms": 35.65903854370117,
+        "p99_ms": 110.73509216308594,
+        "seconds": 11.98972653579712
+      }
+    },
+    "16": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 1,
+        "gpu": "NVIDIA GeForce RTX 4080",
+        "present_mode": "Immediate",
+        "size": [
+          1280,
+          720
+        ],
+        "uploaded_bytes": 54284928
+      },
+      "village": {
+        "avg_fps": 7.569165639843409,
+        "cpu": {
+          "avg_ms": 138.25648041658624,
+          "max_ms": 877.6473999023438,
+          "p50_ms": 103.97663879394531,
+          "p95_ms": 318.5262145996094,
+          "p99_ms": 877.6473999023438
+        },
+        "frames": 86,
+        "gpu": {
+          "avg_ms": 3.585262137790059,
+          "max_ms": 8.415231704711914,
+          "p50_ms": 3.299328088760376,
+          "p95_ms": 7.171072006225586,
+          "p99_ms": 8.415231704711914
+        },
+        "low_1pct_fps": 2.44461512120682,
+        "max_ms": 409.0623474121094,
+        "p50_ms": 104.01687622070312,
+        "p95_ms": 318.5569763183594,
+        "p99_ms": 409.0623474121094,
+        "seconds": 11.361886381149292
+      },
+      "forest": {
+        "avg_fps": 27.65529078792617,
+        "cpu": {
+          "avg_ms": 37.926895780927815,
+          "max_ms": 3484.08349609375,
+          "p50_ms": 3.398620128631592,
+          "p95_ms": 44.56385040283203,
+          "p99_ms": 684.4393920898438
+        },
+        "frames": 314,
+        "gpu": {
+          "avg_ms": 2.683724634467986,
+          "max_ms": 9.881600379943848,
+          "p50_ms": 1.8923519849777222,
+          "p95_ms": 7.221248149871826,
+          "p99_ms": 9.04089641571045
+        },
+        "low_1pct_fps": 0.4753349245465373,
+        "max_ms": 3484.115234375,
+        "p50_ms": 3.5420219898223877,
+        "p95_ms": 44.591251373291016,
+        "p99_ms": 159.3817901611328,
+        "seconds": 11.354066113710404
+      },
+      "ocean": {
+        "avg_fps": 59.16125632179682,
+        "cpu": {
+          "avg_ms": 16.807428855239674,
+          "max_ms": 106.0348129272461,
+          "p50_ms": 9.335607528686523,
+          "p95_ms": 44.57380294799805,
+          "p99_ms": 84.97154998779297
+        },
+        "frames": 712,
+        "gpu": {
+          "avg_ms": 1.958949391112736,
+          "max_ms": 8.635392189025879,
+          "p50_ms": 1.1182080507278442,
+          "p95_ms": 5.493760108947754,
+          "p99_ms": 7.108607769012451
+        },
+        "low_1pct_fps": 10.542641239411056,
+        "max_ms": 106.06544494628906,
+        "p50_ms": 9.364562034606934,
+        "p95_ms": 45.14366912841797,
+        "p99_ms": 84.9927749633789,
+        "seconds": 12.034903317928315
+      },
+      "mountain": {
+        "avg_fps": 26.78175419456072,
+        "cpu": {
+          "avg_ms": 20.230309660251326,
+          "max_ms": 128.05508422851562,
+          "p50_ms": 15.369550704956055,
+          "p95_ms": 67.15973663330078,
+          "p99_ms": 104.6961898803711
+        },
+        "frames": 325,
+        "gpu": {
+          "avg_ms": 7.143625645270714,
+          "max_ms": 21.25823974609375,
+          "p50_ms": 7.187456130981445,
+          "p95_ms": 12.228608131408691,
+          "p99_ms": 19.310592651367188
+        },
+        "low_1pct_fps": 7.777799947825389,
+        "max_ms": 155.30685424804688,
+        "p50_ms": 33.335182189941406,
+        "p95_ms": 68.94293975830078,
+        "p99_ms": 109.09304809570312,
+        "seconds": 12.135127431869506
+      }
+    },
+    "32": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 0,
+        "gpu": "NVIDIA GeForce RTX 4080",
+        "present_mode": "Immediate",
+        "size": [
+          1280,
+          720
+        ],
+        "uploaded_bytes": 4829184
+      },
+      "village": {
+        "avg_fps": 4.1477100728464,
+        "cpu": {
+          "avg_ms": 244.17284844846142,
+          "max_ms": 386.7664489746094,
+          "p50_ms": 244.8783416748047,
+          "p95_ms": 363.0765380859375,
+          "p99_ms": 386.7664489746094
+        },
+        "frames": 49,
+        "gpu": {
+          "avg_ms": 10.357822744213806,
+          "max_ms": 23.010303497314453,
+          "p50_ms": 9.227264404296875,
+          "p95_ms": 19.309568405151367,
+          "p99_ms": 23.010303497314453
+        },
+        "low_1pct_fps": 2.5853636290905797,
+        "max_ms": 386.79278564453125,
+        "p50_ms": 230.8652801513672,
+        "p95_ms": 363.0941162109375,
+        "p99_ms": 386.79278564453125,
+        "seconds": 11.813747619628906
+      },
+      "forest": {
+        "avg_fps": 8.3624969613463,
+        "cpu": {
+          "avg_ms": 118.74922356747165,
+          "max_ms": 278.8187255859375,
+          "p50_ms": 123.03407287597656,
+          "p95_ms": 231.6608123779297,
+          "p99_ms": 260.8450622558594
+        },
+        "frames": 101,
+        "gpu": {
+          "avg_ms": 15.898816661669477,
+          "max_ms": 72.880126953125,
+          "p50_ms": 20.789247512817383,
+          "p95_ms": 28.441600799560547,
+          "p99_ms": 60.816383361816406
+        },
+        "low_1pct_fps": 3.7057290596141406,
+        "max_ms": 278.83917236328125,
+        "p50_ms": 123.19290161132812,
+        "p95_ms": 231.68026733398438,
+        "p99_ms": 260.8656921386719,
+        "seconds": 12.077732340812684
+      },
+      "ocean": {
+        "avg_fps": 2.3954947141714045,
+        "cpu": {
+          "avg_ms": 424.7621285574777,
+          "max_ms": 625.8532104492188,
+          "p50_ms": 435.64044189453125,
+          "p95_ms": 577.7593994140625,
+          "p99_ms": 625.8532104492188
+        },
+        "frames": 28,
+        "gpu": {
+          "avg_ms": 9.483117733682905,
+          "max_ms": 12.973055839538574,
+          "p50_ms": 9.90719985961914,
+          "p95_ms": 12.610560417175293,
+          "p99_ms": 12.973055839538574
+        },
+        "low_1pct_fps": 1.5977632874291703,
+        "max_ms": 625.8749389648438,
+        "p50_ms": 433.9859619140625,
+        "p95_ms": 577.7803955078125,
+        "p99_ms": 625.8749389648438,
+        "seconds": 11.688608551025391
+      },
+      "mountain": {
+        "avg_fps": 3.3756775332390268,
+        "cpu": {
+          "avg_ms": 300.512197249975,
+          "max_ms": 407.4363708496094,
+          "p50_ms": 292.483642578125,
+          "p95_ms": 394.8424377441406,
+          "p99_ms": 407.4363708496094
+        },
+        "frames": 39,
+        "gpu": {
+          "avg_ms": 9.728866460995796,
+          "max_ms": 18.930688858032227,
+          "p50_ms": 8.820735931396484,
+          "p95_ms": 17.399808883666992,
+          "p99_ms": 18.930688858032227
+        },
+        "low_1pct_fps": 2.4541792422631716,
+        "max_ms": 407.46820068359375,
+        "p50_ms": 292.4177551269531,
+        "p95_ms": 394.8649597167969,
+        "p99_ms": 407.46820068359375,
+        "seconds": 11.553236236572266
+      }
+    }
+  }
+}
@@ -0,0 +1,392 @@
+{
+  "label": "baseline-lavapipe",
+  "date": "2026-10-13",
+  "commit": "27a32cc3",
+  "host": "ludodesktop",
+  "offscreen": false,
+  "seed": "1234",
+  "flight_seconds": 12.0,
+  "scenes": {
+    "village": {
+      "from": [
+        -960.0,
+        125.0,
+        80.0
+      ],
+      "to": [
+        -960.0,
+        125.0,
+        272.0
+      ],
+      "pitch": 35.0
+    },
+    "forest": {
+      "from": [
+        -1100.0,
+        120.0,
+        -560.0
+      ],
+      "to": [
+        -1100.0,
+        120.0,
+        -368.0
+      ],
+      "pitch": 25.0
+    },
+    "ocean": {
+      "from": [
+        -300.0,
+        85.0,
+        -420.0
+      ],
+      "to": [
+        -300.0,
+        85.0,
+        -228.0
+      ],
+      "pitch": 10.0
+    },
+    "mountain": {
+      "from": [
+        560.0,
+        260.0,
+        860.0
+      ],
+      "to": [
+        752.0,
+        260.0,
+        860.0
+      ],
+      "pitch": 30.0
+    }
+  },
+  "distances": {
+    "8": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 146,
+        "gpu": "llvmpipe (LLVM 21.1.8, 256 bits)",
+        "present_mode": "Mailbox",
+        "size": [
+          1600,
+          1000
+        ],
+        "uploaded_bytes": 1288851072
+      },
+      "village": {
+        "avg_fps": 16.38225374384963,
+        "cpu": {
+          "avg_ms": 48.17248754105975,
+          "max_ms": 134.31028747558594,
+          "p50_ms": 44.57072067260742,
+          "p95_ms": 97.15985870361328,
+          "p99_ms": 127.31073760986328
+        },
+        "frames": 199,
+        "gpu": {
+          "avg_ms": 26.732369270324707,
+          "max_ms": 47.3107795715332,
+          "p50_ms": 26.284116744995117,
+          "p95_ms": 35.006874084472656,
+          "p99_ms": 39.38005828857422
+        },
+        "low_1pct_fps": 6.569673692138871,
+        "max_ms": 169.97352600097656,
+        "p50_ms": 56.791988372802734,
+        "p95_ms": 109.15220642089844,
+        "p99_ms": 134.45559692382812,
+        "seconds": 12.147290788650512
+      },
+      "forest": {
+        "avg_fps": 19.917172468484612,
+        "cpu": {
+          "avg_ms": 31.039839970568817,
+          "max_ms": 106.39506530761719,
+          "p50_ms": 33.26064682006836,
+          "p95_ms": 70.09876251220703,
+          "p99_ms": 86.21255493164062
+        },
+        "frames": 240,
+        "gpu": {
+          "avg_ms": 37.272586759195285,
+          "max_ms": 77.586669921875,
+          "p50_ms": 34.38500213623047,
+          "p95_ms": 59.649635314941406,
+          "p99_ms": 66.52396392822266
+        },
+        "low_1pct_fps": 9.909291086862112,
+        "max_ms": 106.57542419433594,
+        "p50_ms": 46.05862808227539,
+        "p95_ms": 80.38935852050781,
+        "p99_ms": 94.94140625,
+        "seconds": 12.049903186798096
+      },
+      "ocean": {
+        "avg_fps": 27.969763129786234,
+        "cpu": {
+          "avg_ms": 25.69895526429727,
+          "max_ms": 930.7354125976562,
+          "p50_ms": 18.981081008911133,
+          "p95_ms": 39.42117691040039,
+          "p99_ms": 168.07225036621094
+        },
+        "frames": 336,
+        "gpu": {
+          "avg_ms": 18.856842384451912,
+          "max_ms": 57.835872650146484,
+          "p50_ms": 18.172868728637695,
+          "p95_ms": 28.62451171875,
+          "p99_ms": 44.414398193359375
+        },
+        "low_1pct_fps": 1.527565223414601,
+        "max_ms": 930.8734741210938,
+        "p50_ms": 26.45800018310547,
+        "p95_ms": 50.053672790527344,
+        "p99_ms": 180.92478942871094,
+        "seconds": 12.012972667694092
+      },
+      "mountain": {
+        "avg_fps": 26.5942562164059,
+        "cpu": {
+          "avg_ms": 22.482411369495093,
+          "max_ms": 104.89199829101562,
+          "p50_ms": 22.033512115478516,
+          "p95_ms": 46.385555267333984,
+          "p99_ms": 61.15697479248047
+        },
+        "frames": 320,
+        "gpu": {
+          "avg_ms": 23.762589550018312,
+          "max_ms": 48.10239028930664,
+          "p50_ms": 22.580347061157227,
+          "p95_ms": 35.14606475830078,
+          "p99_ms": 42.47938919067383
+        },
+        "low_1pct_fps": 11.197907022053611,
+        "max_ms": 105.07585906982422,
+        "p50_ms": 33.362815856933594,
+        "p95_ms": 53.36695098876953,
+        "p99_ms": 74.80219268798828,
+        "seconds": 12.03267342376709
+      }
+    },
+    "16": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 1,
+        "gpu": "llvmpipe (LLVM 21.1.8, 256 bits)",
+        "present_mode": "Mailbox",
+        "size": [
+          1600,
+          1000
+        ],
+        "uploaded_bytes": 16106880
+      },
+      "village": {
+        "avg_fps": 10.754658718707336,
+        "cpu": {
+          "avg_ms": 69.22208800682655,
+          "max_ms": 193.21267700195312,
+          "p50_ms": 66.95130157470703,
+          "p95_ms": 154.44834899902344,
+          "p99_ms": 191.29208374023438
+        },
+        "frames": 130,
+        "gpu": {
+          "avg_ms": 49.041961078495945,
+          "max_ms": 73.83775329589844,
+          "p50_ms": 48.90928268432617,
+          "p95_ms": 60.60416793823242,
+          "p99_ms": 66.1044921875
+        },
+        "low_1pct_fps": 4.171866301284614,
+        "max_ms": 252.21458435058594,
+        "p50_ms": 79.8940200805664,
+        "p95_ms": 173.05947875976562,
+        "p99_ms": 227.18716430664062,
+        "seconds": 12.087784782409669
+      },
+      "forest": {
+        "avg_fps": 12.167278778001634,
+        "cpu": {
+          "avg_ms": 58.366991678873696,
+          "max_ms": 156.683349609375,
+          "p50_ms": 69.24014282226562,
+          "p95_ms": 110.83757019042969,
+          "p99_ms": 134.16554260253906
+        },
+        "frames": 147,
+        "gpu": {
+          "avg_ms": 56.45229888606716,
+          "max_ms": 78.26596069335938,
+          "p50_ms": 55.92947006225586,
+          "p95_ms": 63.54412841796875,
+          "p99_ms": 66.5202407836914
+        },
+        "low_1pct_fps": 5.722095670390665,
+        "max_ms": 212.99729919433594,
+        "p50_ms": 77.36986541748047,
+        "p95_ms": 122.84784698486328,
+        "p99_ms": 136.52499389648438,
+        "seconds": 12.081583950042724
+      },
+      "ocean": {
+        "avg_fps": 7.681804845753147,
+        "cpu": {
+          "avg_ms": 98.35419226740743,
+          "max_ms": 385.2493591308594,
+          "p50_ms": 78.85044860839844,
+          "p95_ms": 225.36231994628906,
+          "p99_ms": 385.2493591308594
+        },
+        "frames": 91,
+        "gpu": {
+          "avg_ms": 71.51263585297957,
+          "max_ms": 128.29212951660156,
+          "p50_ms": 67.92412567138672,
+          "p95_ms": 101.93219757080078,
+          "p99_ms": 128.29212951660156
+        },
+        "low_1pct_fps": 2.5948566279945817,
+        "max_ms": 385.37774658203125,
+        "p50_ms": 123.91693878173828,
+        "p95_ms": 225.49420166015625,
+        "p99_ms": 385.37774658203125,
+        "seconds": 11.846174411773681
+      },
+      "mountain": {
+        "avg_fps": 5.886844433101332,
+        "cpu": {
+          "avg_ms": 124.87309415575484,
+          "max_ms": 321.2157897949219,
+          "p50_ms": 117.2811050415039,
+          "p95_ms": 237.34304809570312,
+          "p99_ms": 321.2157897949219
+        },
+        "frames": 71,
+        "gpu": {
+          "avg_ms": 95.46965434816148,
+          "max_ms": 166.9488067626953,
+          "p50_ms": 83.54202270507812,
+          "p95_ms": 160.2403564453125,
+          "p99_ms": 166.9488067626953
+        },
+        "low_1pct_fps": 3.111272818975726,
+        "max_ms": 321.411865234375,
+        "p50_ms": 153.0963134765625,
+        "p95_ms": 275.37579345703125,
+        "p99_ms": 321.411865234375,
+        "seconds": 12.060790939331055
+      }
+    },
+    "32": {
+      "renderer": {
+        "backend": "Vulkan",
+        "drawn_sections": 1,
+        "gpu": "llvmpipe (LLVM 21.1.8, 256 bits)",
+        "present_mode": "Mailbox",
+        "size": [
+          1600,
+          1000
+        ],
+        "uploaded_bytes": 19154560
+      },
+      "village": {
+        "avg_fps": 2.5956714101148957,
+        "cpu": {
+          "avg_ms": 345.63314671670236,
+          "max_ms": 474.2013854980469,
+          "p50_ms": 347.07415771484375,
+          "p95_ms": 468.0090026855469,
+          "p99_ms": 474.2013854980469
+        },
+        "frames": 31,
+        "gpu": {
+          "avg_ms": 85.50063645839691,
+          "max_ms": 134.11460876464844,
+          "p50_ms": 82.40946960449219,
+          "p95_ms": 133.71929931640625,
+          "p99_ms": 134.11460876464844
+        },
+        "low_1pct_fps": 2.01406006678458,
+        "max_ms": 496.509521484375,
+        "p50_ms": 390.230224609375,
+        "p95_ms": 493.8070373535156,
+        "p99_ms": 496.509521484375,
+        "seconds": 11.942960067749024
+      },
+      "forest": {
+        "avg_fps": 2.2283930626963917,
+        "cpu": {
+          "avg_ms": 354.7813931978666,
+          "max_ms": 611.8099975585938,
+          "p50_ms": 293.61376953125,
+          "p95_ms": 601.3502197265625,
+          "p99_ms": 611.8099975585938
+        },
+        "frames": 26,
+        "gpu": {
+          "avg_ms": 201.54420654296874,
+          "max_ms": 357.0310363769531,
+          "p50_ms": 172.65980529785156,
+          "p95_ms": 341.8655700683594,
+          "p99_ms": 357.0310363769531
+        },
+        "low_1pct_fps": 1.52339962842959,
+        "max_ms": 656.4265747070312,
+        "p50_ms": 407.1051330566406,
+        "p95_ms": 611.97119140625,
+        "p99_ms": 656.4265747070312,
+        "seconds": 11.667600494384766
+      },
+      "ocean": {
+        "avg_fps": 2.6137193379326398,
+        "cpu": {
+          "avg_ms": 330.783615620931,
+          "max_ms": 730.7304077148438,
+          "p50_ms": 296.65692138671875,
+          "p95_ms": 680.8717041015625,
+          "p99_ms": 730.7304077148438
+        },
+        "frames": 30,
+        "gpu": {
+          "avg_ms": 113.80178985595703,
+          "max_ms": 216.57342529296875,
+          "p50_ms": 104.23703002929688,
+          "p95_ms": 193.67672729492188,
+          "p99_ms": 216.57342529296875
+        },
+        "low_1pct_fps": 1.1784160273210693,
+        "max_ms": 848.5967407226562,
+        "p50_ms": 346.120849609375,
+        "p95_ms": 681.0716552734375,
+        "p99_ms": 848.5967407226562,
+        "seconds": 11.477896484375
+      },
+      "mountain": {
+        "avg_fps": 2.72441042065798,
+        "cpu": {
+          "avg_ms": 325.24547207740045,
+          "max_ms": 578.7177124023438,
+          "p50_ms": 295.25457763671875,
+          "p95_ms": 569.8099975585938,
+          "p99_ms": 578.7177124023438
+        },
+        "frames": 31,
+        "gpu": {
+          "avg_ms": 104.99177145957947,
+          "max_ms": 163.95635986328125,
+          "p50_ms": 99.96784210205078,
+          "p95_ms": 160.04824829101562,
+          "p99_ms": 163.95635986328125
+        },
+        "low_1pct_fps": 1.7544071931551564,
+        "max_ms": 569.9931030273438,
+        "p50_ms": 378.246337890625,
+        "p95_ms": 555.5369873046875,
+        "p99_ms": 569.9931030273438,
+        "seconds": 11.378608657836914
+      }
+    }
+  }
+}
@@ -0,0 +1,69 @@
+# Reuse parsed model states
+
+`models::prepare` parsed `model-states.json` to select blocks, then
+`StateModels::load` reopened and parsed the same document for binding and baking.
+`StateModels::from_facts` now borrows the first parsed map. The public `load`
+entry point still reads, parses and validates its own document. Both paths retain
+the `fs::read` + `serde_json::from_slice` strategy merged in PR #205.
+
+The shared map uses `BTreeMap`, preserving the original catalog loader's JSON
+validation, including rejection of top-level `null`. The old selection map was
+`serde_json::Map`, also backed by a BTreeMap with the project's current features.
+Catalog binding, model selection and baking are unchanged. Preparation no longer
+holds a second complete JSON tree while constructing the catalog; no persistent
+cache or extra clones were added.
+
+## Measurement
+
+The committed `model_states_bench` example runs main's two-parse sequence after PR #205
+(first a serde JSON map, then `StateModels::load`) and the new one-parse sequence
+(first a BTreeMap, then `StateModels::from_facts`). Both select blocks from the
+same generated document with slice parsing and call the actual catalog binding/baking code. Timing
+includes file reads, parsing, filtering, binding, baking and result destruction.
+Fixture generation and equality checks run outside the timed region.
+
+Prepared Minecraft resources were unavailable locally, so this is a synthetic
+2,836,696-byte document containing 843 block schemas and 53,952 states. Schemas
+combine integer and named properties. Blockstate resources use weighted and
+conditional multipart choices with rotations and UV locking, sharing one model
+with a baked face. Its absent texture uses the normal missing-sprite fallback.
+Both paths read identical files with a warm OS cache. The workload does not
+represent the full diversity of production model and texture assets.
+
+On AMD Ryzen 5 5600X, Linux 7.2.8-zen1-2-zen x86_64, rustc 1.99.0
+(b940084d7 2026-09-28), Cargo `fast` profile, serial execution:
+
+| Path | Median (15 samples) |
+| --- | ---: |
+| Before: parse twice, with #205 slice readers | 96.080 ms |
+| After: reuse first parse, with #205 slice readers | 73.585 ms |
+
+**1.306x speedup; 23.41% less elapsed time** for this loading segment after PR #205. Each path
+has two warmups, sample order alternates, and inputs/results use `black_box`.
+This excludes gallery placements, GPU work and overall application startup.
+
+These measurements supersede the original unbuffered-reader timings
+(2732.004 ms → 1386.060 ms, 1.971x) after rebasing onto main at
+`e96e1571`. The reviewer measured approximately 1.05x with real prepared resources;
+the generated fixture's balance of parsing and binding differs from production.
+The change still removes one complete document read, parse and JSON tree.
+
+Equality validation compares every state's selected variants and baked geometry
+at three positions, plus sprite layers and opacity/translucency flags. The
+focused test also checks matching schema/registry errors, malformed/missing
+source files, rejection of `null`, and successful shared-facts loading after the
+source file has been deleted.
+
+## Reproduce
+
+```sh
+export CARGO_TARGET_DIR=/home/bob/Documents/horizon/target
+export CARGO_INCREMENTAL=0
+cargo run -p horizon-client --profile fast --example model_states_bench -- 15
+cargo test -p horizon-client --profile fast --example model_states_bench
+cargo clippy -p horizon-client --all-targets --profile fast -- -D warnings
+cargo fmt --all -- --check
+```
+
+The target directory can be changed for another machine. The example creates and
+removes its fixtures in the system temporary directory.
@@ -0,0 +1,54 @@
+{
+  "date": "2026-10-15",
+  "environment": "Linux x86_64/ext4/NVMe, Ryzen5 5600X, Rust1.99.0, Cargo fast",
+  "scope": "actual resource_root vs original wrapper/builder; warmed storage; output equivalence outside timing",
+  "warmups": 2,
+  "median_samples": 11,
+  "prepared_minecraft": "26.3",
+  "prepared_schema": 7,
+  "prepared_manifest_sha256": "fd03c686302748748e132ef3978b7b0bcf42024257e802985a5cc7175cc74298",
+  "packs": [
+    {
+      "project": "faithful-32x",
+      "version": "lDYpMiqk",
+      "version_name": "[26.3] Faithful 32x \u2013 September 2026 Release",
+      "publisher_page": "https://modrinth.com/resourcepack/faithful-32x/version/lDYpMiqk",
+      "download_url": "https://cdn.modrinth.com/data/w0TnApzs/versions/lDYpMiqk/Faithful%2032x%20-%2026.3.zip",
+      "zip_bytes": 13116019,
+      "zip_sha512": "e90ec63af7f239dbb99aa20c98b23d830e76898f65d3e31b7f0b53bb36db12dcd8c38d6930c743237c9c3db7bf708423fa1d1b2fd497dd6c281dbe216b779db9",
+      "asset_files": 5063,
+      "assets_uncompressed_bytes": 12524266,
+      "original_ms": 159.827,
+      "cold_ms": 162.711,
+      "hit_ms": 0.707
+    },
+    {
+      "project": "default-hd-128x",
+      "version": "rErHu3BE",
+      "version_name": "Default HD 128x Demo/Alpha 1.8.2.7",
+      "publisher_page": "https://modrinth.com/resourcepack/default-hd-128x/version/rErHu3BE",
+      "download_url": "https://cdn.modrinth.com/data/orfTV6nk/versions/rErHu3BE/Default%20HD%20128x%20Demo%201.8.2.7.zip",
+      "zip_bytes": 16876419,
+      "zip_sha512": "f5f9606e92b986cd9c8b8e5ff2bb52db720cc7b38e013355bdc90089e01975a08d09750ef2fd727f753d88ec3fbcd067355179b490587f667b2995f8be81640f",
+      "asset_files": 2318,
+      "assets_uncompressed_bytes": 17315416,
+      "original_ms": 111.501,
+      "cold_ms": 114.386,
+      "hit_ms": 0.31
+    },
+    {
+      "project": "fpbr",
+      "version": "dynf82xk",
+      "version_name": "support 1.21.9 and newer",
+      "publisher_page": "https://modrinth.com/resourcepack/fpbr/version/dynf82xk",
+      "download_url": "https://cdn.modrinth.com/data/nvEpbd8t/versions/dynf82xk/FPBR-Main-1.21.9-R1.3.zip",
+      "zip_bytes": 46737770,
+      "zip_sha512": "64f1bbd036e205118f1d9c49a79558db2c1356ee988fb939c0023db1967d78e1bd05047f341ce6d65355717ba7ddb1330af57edbb4d5b8713c96ae62987274c5",
+      "asset_files": 7001,
+      "assets_uncompressed_bytes": 56356903,
+      "original_ms": 347.639,
+      "cold_ms": 348.012,
+      "hit_ms": 0.448
+    }
+  ]
+}
@@ -0,0 +1,10 @@
+[package]
+name = "horizon-bench"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+description = "The benchmark report format (docs/benchmark-report.md), shared by the game, the launcher and the upload"
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
@@ -0,0 +1,259 @@
+//! The machine a report was measured on. CPU, RAM and OS are detected here; the GPU and the display
+//! come from the program that rendered (the game knows its adapter, the launcher its window).
+
+use std::process::Command;
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct Hardware {
+    /// `macos`, `linux`, `windows`.
+    pub os: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub os_version: Option<String>,
+    pub arch: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cpu: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cpu_threads: Option<usize>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub ram_mb: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gpu: Option<Gpu>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub display: Option<Display>,
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct Gpu {
+    pub name: String,
+    pub vendor: String,
+    pub driver: String,
+    /// `metal`, `vulkan`, `dx12`, `gl`.
+    pub backend: String,
+    /// `integrated`, `discrete`, `virtual`, `cpu`, `other`.
+    pub kind: String,
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct Display {
+    /// Physical pixels.
+    pub width: u32,
+    pub height: u32,
+    pub scale: f64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub refresh_hz: Option<u32>,
+}
+
+impl Hardware {
+    pub fn detect() -> Hardware {
+        Hardware {
+            os: std::env::consts::OS.to_owned(),
+            os_version: os_version(),
+            arch: std::env::consts::ARCH.to_owned(),
+            cpu: cpu(),
+            cpu_threads: std::thread::available_parallelism().ok().map(|n| n.get()),
+            ram_mb: ram_bytes().map(|b| b >> 20),
+            gpu: None,
+            display: None,
+        }
+    }
+}
+
+/// The one-minute load average: above about the number of threads the machine was busy.
+pub fn load_average() -> Option<f64> {
+    if cfg!(target_os = "macos") {
+        // "{ 1.23 1.10 1.00 }"
+        output("sysctl", &["-n", "vm.loadavg"])?
+            .trim_start_matches('{')
+            .split_whitespace()
+            .next()?
+            .parse()
+            .ok()
+    } else {
+        std::fs::read_to_string("/proc/loadavg")
+            .ok()?
+            .split_whitespace()
+            .next()?
+            .parse()
+            .ok()
+    }
+}
+
+/// `ac` or `battery`; `None` where it can't be read (and on machines without a battery on Linux).
+pub fn power_source() -> Option<&'static str> {
+    if cfg!(target_os = "macos") {
+        let batt = output("pmset", &["-g", "batt"])?;
+        return Some(if batt.contains("'Battery Power'") {
+            "battery"
+        } else {
+            "ac"
+        });
+    }
+    let mut on_battery = None;
+    for entry in std::fs::read_dir("/sys/class/power_supply").ok()?.flatten() {
+        let read =
+            |name: &str| std::fs::read_to_string(entry.path().join(name)).unwrap_or_default();
+        match read("type").trim() {
+            "Mains" if read("online").trim() == "1" => return Some("ac"),
+            "Battery" => on_battery = Some("battery"),
+            _ => {}
+        }
+    }
+    on_battery
+}
+
+/// Resident memory of a process, in bytes (macOS, Linux).
+pub fn rss_bytes(pid: u32) -> Option<u64> {
+    if cfg!(target_os = "macos") {
+        return output("ps", &["-o", "rss=", "-p", &pid.to_string()])?
+            .parse::<u64>()
+            .ok()
+            .map(|kb| kb * 1024);
+    }
+    let status = std::fs::read_to_string(format!("/proc/{pid}/status")).ok()?;
+    let line = status.lines().find(|l| l.starts_with("VmRSS:"))?;
+    line.split_whitespace()
+        .nth(1)?
+        .parse::<u64>()
+        .ok()
+        .map(|kb| kb * 1024)
+}
+
+/// CPU time a process has used, user and system, in seconds (macOS, Linux).
+pub fn cpu_seconds(pid: u32) -> Option<f64> {
+    if cfg!(target_os = "macos") {
+        // "[[dd-]hh:]mm:ss.cc"
+        let time = output("ps", &["-o", "time=", "-p", &pid.to_string()])?;
+        let (rest, days) = match time.split_once('-') {
+            Some((d, rest)) => (rest.to_owned(), d.parse::<f64>().ok()?),
+            None => (time, 0.0),
+        };
+        let seconds = rest.split(':').try_fold(0.0, |acc, part| {
+            part.parse::<f64>().ok().map(|v| acc * 60.0 + v)
+        })?;
+        return Some(days * 86_400.0 + seconds);
+    }
+    // utime and stime, fields 14 and 15, in clock ticks (100 per second on Linux).
+    let stat = std::fs::read_to_string(format!("/proc/{pid}/stat")).ok()?;
+    let fields: Vec<&str> = stat.rsplit_once(')')?.1.split_whitespace().collect();
+    let ticks: f64 = fields.get(11)?.parse::<f64>().ok()? + fields.get(12)?.parse::<f64>().ok()?;
+    Some(ticks / 100.0)
+}
+
+fn output(program: &str, args: &[&str]) -> Option<String> {
+    let out = Command::new(program).args(args).output().ok()?;
+    let text = String::from_utf8(out.stdout).ok()?.trim().to_owned();
+    (out.status.success() && !text.is_empty()).then_some(text)
+}
+
+#[cfg(target_os = "macos")]
+fn os_version() -> Option<String> {
+    output("sw_vers", &["-productVersion"])
+}
+
+#[cfg(target_os = "macos")]
+fn cpu() -> Option<String> {
+    output("sysctl", &["-n", "machdep.cpu.brand_string"])
+}
+
+#[cfg(target_os = "macos")]
+fn ram_bytes() -> Option<u64> {
+    output("sysctl", &["-n", "hw.memsize"])?.parse().ok()
+}
+
+#[cfg(target_os = "linux")]
+fn os_version() -> Option<String> {
+    let release = std::fs::read_to_string("/etc/os-release").ok()?;
+    let name = key_value(&release, "PRETTY_NAME", '=')?
+        .trim_matches('"')
+        .to_owned();
+    Some(match output("uname", &["-r"]) {
+        Some(kernel) => format!("{name} (kernel {kernel})"),
+        None => name,
+    })
+}
+
+#[cfg(target_os = "linux")]
+fn cpu() -> Option<String> {
+    let info = std::fs::read_to_string("/proc/cpuinfo").ok()?;
+    // x86 names the CPU per core; ARM boards name the machine once.
+    key_value(&info, "model name", ':')
+        .or_else(|| key_value(&info, "Model", ':'))
+        .map(str::to_owned)
+}
+
+#[cfg(target_os = "linux")]
+fn ram_bytes() -> Option<u64> {
+    let info = std::fs::read_to_string("/proc/meminfo").ok()?;
+    let kb = key_value(&info, "MemTotal", ':')?
+        .trim_end_matches("kB")
+        .trim();
+    kb.parse::<u64>().ok().map(|kb| kb * 1024)
+}
+
+#[cfg(target_os = "linux")]
+fn key_value<'a>(text: &'a str, key: &str, sep: char) -> Option<&'a str> {
+    text.lines().find_map(|line| {
+        let (k, v) = line.split_once(sep)?;
+        (k.trim() == key).then(|| v.trim())
+    })
+}
+
+#[cfg(target_os = "windows")]
+fn os_version() -> Option<String> {
+    output("cmd", &["/C", "ver"])
+}
+
+#[cfg(target_os = "windows")]
+fn cpu() -> Option<String> {
+    std::env::var("PROCESSOR_IDENTIFIER").ok()
+}
+
+#[cfg(target_os = "windows")]
+fn ram_bytes() -> Option<u64> {
+    let out = output(
+        "powershell",
+        &[
+            "-NoProfile",
+            "-Command",
+            "(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory",
+        ],
+    )?;
+    out.parse().ok()
+}
+
+#[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
+fn os_version() -> Option<String> {
+    None
+}
+
+#[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
+fn cpu() -> Option<String> {
+    None
+}
+
+#[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
+fn ram_bytes() -> Option<u64> {
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn detects_this_machine() {
+        let hw = Hardware::detect();
+        assert_eq!(hw.os, std::env::consts::OS);
+        assert!(hw.cpu_threads.unwrap() >= 1);
+        if cfg!(any(target_os = "macos", target_os = "linux")) {
+            assert!(hw.cpu.is_some(), "{hw:?}");
+            assert!(hw.ram_mb.unwrap() > 256, "{hw:?}");
+            assert!(hw.os_version.is_some(), "{hw:?}");
+            assert!(load_average().is_some());
+            assert!(rss_bytes(std::process::id()).unwrap() > 1 << 20);
+            assert!(cpu_seconds(std::process::id()).unwrap() >= 0.0);
+        }
+    }
+}
@@ -0,0 +1,457 @@
+//! The benchmark report format, version 1 (docs/benchmark-report.md).
+//!
+//! One JSON file per run, the same for the game, the launcher and `tools/perf_bench.py`: the local log
+//! a player can attach, and, with consent, what the telemetry upload sends ([`Report::for_upload`]).
+//! It holds summaries and fixed-edge histogram counts, never raw frame streams.
+
+use std::collections::BTreeMap;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde::{Deserialize, Serialize};
+
+mod hardware;
+
+pub use hardware::{cpu_seconds, load_average, power_source, rss_bytes, Display, Gpu, Hardware};
+
+pub const FORMAT: &str = "horizon-benchmark-report";
+pub const VERSION: u32 = 1;
+
+/// Lower edges of the frame-time histogram buckets, in milliseconds; the last bucket is 1000 ms and
+/// over. Fixed by the format version so histograms from any number of reports add up.
+pub const HISTOGRAM_EDGES_MS: [f64; 24] = [
+    0.0, 1.0, 2.0, 3.0, 4.17, 5.0, 6.0, 7.0, 8.33, 10.0, 12.0, 14.0, 16.67, 20.0, 25.0, 33.33,
+    40.0, 50.0, 66.67, 100.0, 150.0, 250.0, 500.0, 1000.0,
+];
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Kind {
+    Game,
+    Launcher,
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct App {
+    pub name: String,
+    pub version: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub commit: Option<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub mods: Vec<Mod>,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct Mod {
+    pub name: String,
+    pub version: String,
+}
+
+/// What has to match for two reports to be compared. Every field is optional.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct Conditions {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub scenario: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub seed: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub render_distance: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub simulation_distance: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub window: Option<[u32; 2]>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub vsync: Option<bool>,
+    /// Absent: unlimited.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub fps_cap: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub offscreen: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub repeats: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub warmup_s: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub power: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub load_avg_1m: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub backend: Option<String>,
+}
+
+/// A measurement over a run's repeats.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct Summary {
+    pub n: usize,
+    pub mean: f64,
+    /// Sample standard deviation; `None` for a single value.
+    pub stdev: Option<f64>,
+    pub min: f64,
+    pub max: f64,
+    /// Half-width of the 95% confidence interval of the mean (Student's t); `None` for a single value.
+    pub ci95: Option<f64>,
+}
+
+impl Summary {
+    /// `None` for no values.
+    pub fn of(values: &[f64]) -> Option<Summary> {
+        let n = values.len();
+        if n == 0 {
+            return None;
+        }
+        let mean = values.iter().sum::<f64>() / n as f64;
+        let (stdev, ci95) = if n > 1 {
+            let var = values.iter().map(|v| (v - mean).powi(2)).sum::<f64>() / (n - 1) as f64;
+            let sd = var.sqrt();
+            (Some(sd), Some(t95(n - 1) * sd / (n as f64).sqrt()))
+        } else {
+            (None, None)
+        };
+        Some(Summary {
+            n,
+            mean: round(mean),
+            stdev: stdev.map(round),
+            min: round(values.iter().copied().fold(f64::INFINITY, f64::min)),
+            max: round(values.iter().copied().fold(f64::NEG_INFINITY, f64::max)),
+            ci95: ci95.map(round),
+        })
+    }
+}
+
+/// Two-sided 95% critical value of Student's t for `df` degrees of freedom.
+fn t95(df: usize) -> f64 {
+    const TABLE: [f64; 30] = [
+        12.706, 4.303, 3.182, 2.776, 2.571, 2.447, 2.365, 2.306, 2.262, 2.228, 2.201, 2.179, 2.160,
+        2.145, 2.131, 2.120, 2.110, 2.101, 2.093, 2.086, 2.080, 2.074, 2.069, 2.064, 2.060, 2.056,
+        2.052, 2.048, 2.045, 2.042,
+    ];
+    TABLE.get(df.wrapping_sub(1)).copied().unwrap_or(1.96)
+}
+
+/// One measured phase of one repeat.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct Frames {
+    pub phase: String,
+    pub repeat: u32,
+    pub frames: usize,
+    pub seconds: f64,
+    pub avg_fps: f64,
+    pub low_1pct_fps: f64,
+    pub low_01pct_fps: f64,
+    pub p50_ms: f64,
+    pub p95_ms: f64,
+    pub p99_ms: f64,
+    pub p999_ms: f64,
+    pub max_ms: f64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cpu_p50_ms: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gpu_p50_ms: Option<f64>,
+    /// Frame counts per bucket of [`HISTOGRAM_EDGES_MS`].
+    pub histogram: Vec<u64>,
+}
+
+impl Frames {
+    /// The figures of a phase from its frame times in milliseconds (time between the starts of
+    /// consecutive frames); `None` for no frames. CPU and GPU times are per frame too, when measured.
+    pub fn of(
+        phase: &str,
+        repeat: u32,
+        frame_ms: &[f32],
+        cpu_ms: &[f32],
+        gpu_ms: &[f32],
+    ) -> Option<Frames> {
+        let times = sorted(frame_ms);
+        let n = times.len();
+        if n == 0 {
+            return None;
+        }
+        let total: f64 = times.iter().sum();
+        // The average frame time of the slowest `share` of frames, as frames per second.
+        let low = |share: f64| {
+            let slowest = &times[n - ((n as f64 * share).ceil() as usize).max(1)..];
+            1000.0 * slowest.len() as f64 / slowest.iter().sum::<f64>()
+        };
+        let mut histogram = vec![0; HISTOGRAM_EDGES_MS.len()];
+        for &t in &times {
+            histogram[HISTOGRAM_EDGES_MS.partition_point(|&edge| edge <= t).max(1) - 1] += 1;
+        }
+        Some(Frames {
+            phase: phase.to_owned(),
+            repeat,
+            frames: n,
+            seconds: round(total / 1000.0),
+            avg_fps: round(n as f64 * 1000.0 / total),
+            low_1pct_fps: round(low(0.01)),
+            low_01pct_fps: round(low(0.001)),
+            p50_ms: round(percentile(&times, 0.5)),
+            p95_ms: round(percentile(&times, 0.95)),
+            p99_ms: round(percentile(&times, 0.99)),
+            p999_ms: round(percentile(&times, 0.999)),
+            max_ms: round(times[n - 1]),
+            cpu_p50_ms: (!cpu_ms.is_empty()).then(|| round(percentile(&sorted(cpu_ms), 0.5))),
+            gpu_p50_ms: (!gpu_ms.is_empty()).then(|| round(percentile(&sorted(gpu_ms), 0.5))),
+            histogram,
+        })
+    }
+}
+
+fn sorted(ms: &[f32]) -> Vec<f64> {
+    let mut v: Vec<f64> = ms
+        .iter()
+        .map(|&m| f64::from(m))
+        .filter(|m| m.is_finite())
+        .collect();
+    v.sort_by(f64::total_cmp);
+    v
+}
+
+/// Three decimals: plenty for milliseconds and FPS, short in JSON, and parsed back exactly.
+fn round(v: f64) -> f64 {
+    (v * 1000.0).round() / 1000.0
+}
+
+/// Nearest-rank percentile of sorted, non-empty values.
+fn percentile(sorted: &[f64], p: f64) -> f64 {
+    let n = sorted.len();
+    sorted[((n as f64 * p).ceil() as usize).clamp(1, n) - 1]
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct Report {
+    pub format: String,
+    pub version: u32,
+    pub kind: Kind,
+    /// When the run ended, UTC, `YYYY-MM-DDTHH:MM:SSZ`.
+    pub created: String,
+    pub app: App,
+    pub hardware: Hardware,
+    #[serde(default)]
+    pub conditions: Conditions,
+    /// Scalar measurements by name; the unit is the name's suffix (`_ms`, `_mb`...).
+    #[serde(default)]
+    pub metrics: BTreeMap<String, Summary>,
+    #[serde(default)]
+    pub frames: Vec<Frames>,
+    /// Local only: a name the person running it chose.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub label: Option<String>,
+    /// Local only: logs the run wrote next to the report.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub local: Vec<PathBuf>,
+}
+
+impl Report {
+    /// An empty report for this machine, created now.
+    pub fn new(kind: Kind, app: App) -> Report {
+        Report {
+            format: FORMAT.to_owned(),
+            version: VERSION,
+            kind,
+            created: utc_now(),
+            app,
+            hardware: Hardware::detect(),
+            conditions: Conditions::default(),
+            metrics: BTreeMap::new(),
+            frames: Vec::new(),
+            label: None,
+            local: Vec::new(),
+        }
+    }
+
+    /// Records a measurement over the repeats; no values records nothing.
+    pub fn metric(&mut self, name: &str, values: &[f64]) {
+        if let Some(summary) = Summary::of(values) {
+            self.metrics.insert(name.to_owned(), summary);
+        }
+    }
+
+    /// Reads a report, rejecting other formats and newer versions.
+    pub fn parse(json: &str) -> Result<Report, String> {
+        let report: Report = serde_json::from_str(json).map_err(|e| e.to_string())?;
+        if report.format != FORMAT {
+            return Err(format!(
+                "not a benchmark report: format {:?}",
+                report.format
+            ));
+        }
+        if report.version > VERSION {
+            return Err(format!(
+                "report version {} is newer than {VERSION}",
+                report.version
+            ));
+        }
+        Ok(report)
+    }
+
+    /// The report without its local-only fields, dated to the day: what an upload sends.
+    pub fn for_upload(&self) -> Report {
+        let day = self.created.get(..10).unwrap_or_default();
+        Report {
+            label: None,
+            local: Vec::new(),
+            created: format!("{day}T00:00:00Z"),
+            ..self.clone()
+        }
+    }
+
+    pub fn to_json(&self) -> String {
+        serde_json::to_string_pretty(self).expect("a report always serializes")
+    }
+
+    /// Writes `<dir>/<kind>-<created>-<scenario>.json` and returns its path.
+    pub fn write_to(&self, dir: &Path) -> io::Result<PathBuf> {
+        std::fs::create_dir_all(dir)?;
+        let kind = match self.kind {
+            Kind::Game => "game",
+            Kind::Launcher => "launcher",
+        };
+        let stamp: String = self.created.chars().filter(char::is_ascii_digit).collect();
+        let scenario: String = self
+            .conditions
+            .scenario
+            .as_deref()
+            .unwrap_or("run")
+            .chars()
+            .map(|c| {
+                if c.is_ascii_alphanumeric() || c == '-' {
+                    c
+                } else {
+                    '_'
+                }
+            })
+            .collect();
+        let path = dir.join(format!("{kind}-{stamp}-{scenario}.json"));
+        std::fs::write(&path, self.to_json() + "\n")?;
+        Ok(path)
+    }
+}
+
+/// The current time, UTC, `YYYY-MM-DDTHH:MM:SSZ`.
+pub fn utc_now() -> String {
+    let secs = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |d| d.as_secs());
+    utc(secs)
+}
+
+fn utc(secs: u64) -> String {
+    let (days, rem) = (secs / 86_400, secs % 86_400);
+    // Civil date from days since 1970-01-01 (Howard Hinnant's algorithm).
+    let z = days as i64 + 719_468;
+    let era = z.div_euclid(146_097);
+    let doe = z - era * 146_097;
+    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let day = doy - (153 * mp + 2) / 5 + 1;
+    let month = if mp < 10 { mp + 3 } else { mp - 9 };
+    let year = yoe + era * 400 + i64::from(month <= 2);
+    format!(
+        "{year:04}-{month:02}-{day:02}T{:02}:{:02}:{:02}Z",
+        rem / 3600,
+        rem / 60 % 60,
+        rem % 60
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn utc_dates() {
+        assert_eq!(utc(0), "1970-01-01T00:00:00Z");
+        assert_eq!(utc(951_782_400), "2000-02-29T00:00:00Z");
+        assert_eq!(utc(1_791_983_007), "2026-10-14T13:03:27Z");
+    }
+
+    #[test]
+    fn summary_of_repeats() {
+        assert_eq!(Summary::of(&[]), None);
+        let one = Summary::of(&[5.0]).unwrap();
+        assert_eq!((one.n, one.mean, one.stdev, one.ci95), (1, 5.0, None, None));
+        let s = Summary::of(&[2.0, 4.0, 6.0]).unwrap();
+        assert_eq!((s.mean, s.min, s.max), (4.0, 2.0, 6.0));
+        assert_eq!(s.stdev, Some(2.0));
+        assert_eq!(s.ci95, Some(4.969), "4.303 * 2 / sqrt(3)");
+    }
+
+    #[test]
+    fn frame_figures_and_histogram() {
+        // 998 frames of 2 ms, one of 20 ms, one of 1500 ms.
+        let mut ms = vec![2.0f32; 998];
+        ms.extend([20.0, 1500.0]);
+        let f = Frames::of("flight", 0, &ms, &[], &[]).unwrap();
+        assert_eq!(f.frames, 1000);
+        assert_eq!(f.seconds, 3.516);
+        assert_eq!((f.p50_ms, f.p999_ms, f.max_ms), (2.0, 20.0, 1500.0));
+        // Slowest 1% = 10 frames: 8 of 2 ms, 20 ms, 1500 ms.
+        assert_eq!(f.low_1pct_fps, 6.51, "1000 * 10 / 1536");
+        // Slowest 0.1% = the 1500 ms frame.
+        assert_eq!(f.low_01pct_fps, 0.667);
+        assert_eq!(f.histogram.len(), HISTOGRAM_EDGES_MS.len());
+        assert_eq!(f.histogram[2], 998, "2 ms falls in [2, 3)");
+        assert_eq!(f.histogram[13], 1, "20 ms falls in [20, 25)");
+        assert_eq!(f.histogram[23], 1, "1500 ms falls in [1000, inf)");
+        assert_eq!(f.histogram.iter().sum::<u64>(), 1000);
+        assert_eq!((f.cpu_p50_ms, f.gpu_p50_ms), (None, None));
+        assert_eq!(Frames::of("x", 0, &[], &[], &[]), None);
+    }
+
+    #[test]
+    fn round_trip_and_upload_strips_local_fields() {
+        let mut r = Report::new(
+            Kind::Game,
+            App {
+                name: "horizon-client".into(),
+                version: "0.1.0".into(),
+                ..App::default()
+            },
+        );
+        r.conditions.scenario = Some("flight".into());
+        r.metric("startup.title_ms", &[800.0, 820.0]);
+        r.frames
+            .extend(Frames::of("village", 0, &[2.0, 3.0], &[1.0], &[]));
+        r.label = Some("my run".into());
+        r.local.push("/home/someone/logs/latest.log".into());
+        let back = Report::parse(&r.to_json()).unwrap();
+        assert_eq!(back, r);
+        r.created = "2026-10-15T14:03:27Z".into();
+        let upload = r.for_upload();
+        assert_eq!(upload.created, "2026-10-15T00:00:00Z", "the day only");
+        let upload = upload.to_json();
+        assert!(
+            !upload.contains("my run") && !upload.contains("someone"),
+            "{upload}"
+        );
+    }
+
+    #[test]
+    fn rejects_other_formats_and_newer_versions() {
+        let r = Report::new(Kind::Launcher, App::default());
+        let newer = r.to_json().replace("\"version\": 1", "\"version\": 2");
+        assert!(Report::parse(&newer).unwrap_err().contains("newer"));
+        let other = r.to_json().replace(FORMAT, "something-else");
+        assert!(Report::parse(&other).is_err());
+    }
+
+    #[test]
+    fn writes_into_a_folder() {
+        let dir = std::env::temp_dir().join(format!("horizon-bench-test-{}", std::process::id()));
+        let mut r = Report::new(Kind::Launcher, App::default());
+        r.created = "2026-10-15T14:03:27Z".into();
+        r.conditions.scenario = Some("cold start".into());
+        let path = r.write_to(&dir).unwrap();
+        assert_eq!(
+            path.file_name().unwrap(),
+            "launcher-20261015140327-cold_start.json"
+        );
+        assert_eq!(
+            Report::parse(&std::fs::read_to_string(&path).unwrap()).unwrap(),
+            r
+        );
+        std::fs::remove_dir_all(dir).unwrap();
+    }
+}
@@ -12,16 +12,37 @@ horizon-assets = { path = "../horizon-assets" }
 horizon-core = { path = "../horizon-core" }
 horizon-world = { path = "../horizon-world" }
 horizon-protocol = { path = "../horizon-protocol" }
+horizon-friends = { path = "../horizon-friends" }
 wgpu = { version = "30.0.1", default-features = false, features = ["std", "parking_lot", "vulkan", "metal", "wgsl"] }
 winit = "0.30.13"
 pollster = "0.4"
 bytemuck = { version = "1.24", features = ["derive"] }
 glam = "0.30"
 png = "0.18"
+sha2 = "0.10.9"
+serde = { version = "1", features = ["derive"] }
 serde_json = { version = "1.0.151", features = ["raw_value"] }
 cpal = "0.16"
 symphonia = { version = "0.5", default-features = false, features = ["ogg", "vorbis"] }
 miniz_oxide = "0.8"
+ab_glyph = "0.2.32"
+log = "0.4"
+chrono = { version = "0.4.42", default-features = false, features = ["clock", "std"] }
+flate2 = { version = "1.1.10", default-features = false, features = ["rust_backend"] }
+horizon-theme = { path = "../horizon-theme" }
+# Opt-in data collection: the game keeps, the launcher sends (docs/telemetry.md).
+horizon-telemetry = { path = "../horizon-telemetry", default-features = false }
+horizon-bench = { path = "../horizon-bench" }
+arboard = { version = "3.6.1", default-features = false, features = ["wayland-data-control"] }
+zip = { version = "2", default-features = false, features = ["deflate"] }
+# Controllers (evdev + libudev on Linux, IOKit on macOS, Windows.Gaming.Input).
+gilrs = "0.11"
+# HTTPS to the Minecraft services (online-mode session join).
+ureq = { version = "2", default-features = false, features = ["tls"] }
+
+[target.'cfg(windows)'.build-dependencies]
+# The icon resource in the .exe (build.rs).
+winresource = "0.1"

 [features]
 # Records the call sites of mob random draws (`mob_ai_probe` traces).
@@ -29,3 +50,7 @@ rng-trace = ["horizon-core/rng-trace"]

 [lints]
 workspace = true
+
+[dev-dependencies]
+# Parses and validates the composed entity shader (already built for wgpu).
+naga = { version = "30.0.1", features = ["wgsl-in"] }
@@ -0,0 +1,15 @@
+//! Embeds Horizon's icon (`packaging/icons/horizon.ico`) in the Windows executables, as icon
+//! resource 1: Explorer and the task bar show it, and the window takes it as its icon.
+fn main() {
+    let dir = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_default();
+    let ico = format!("{dir}/../../packaging/icons/horizon.ico");
+    println!("cargo:rerun-if-changed={ico}");
+    #[cfg(windows)]
+    if std::env::var("CARGO_CFG_TARGET_OS").as_deref() == Ok("windows") {
+        let mut resource = winresource::WindowsResource::new();
+        resource.set_icon(&ico);
+        if let Err(e) = resource.compile() {
+            panic!("embedding {ico}: {e}");
+        }
+    }
+}
@@ -0,0 +1,313 @@
+//! Arrows over the client's resident scene (`arrows::tick`), for
+//! tools/test_arrow_parity.py: one line of state and one of events per operation.
+#![forbid(unsafe_code)]
+use horizon_client::{
+    Result,
+    arrows::{
+        self, ArrowEvent, ArrowParticle, ArrowScene, ArrowSound, BlockReaction, Pickup, Touch,
+    },
+    assets::Assets,
+    blocks::BlockFacts,
+    collisions,
+    items::ItemStack,
+    mobs::Who,
+    motion::{LAVA, MotionResources, WATER},
+    projectiles::{Projectile, ProjectileKind},
+    world::World,
+};
+use horizon_core::{
+    geometry::Vec3,
+    random::{LegacyRandom, RandomSource},
+};
+use serde_json::Value;
+use std::{
+    fs,
+    io::{BufRead, Write},
+    path::PathBuf,
+};
+fn number(v: &Value) -> f64 {
+    f64::from_bits(u64::from_str_radix(v.as_str().unwrap(), 16).unwrap())
+}
+fn vector(v: &Value) -> Vec3 {
+    Vec3::new(number(&v[0]), number(&v[1]), number(&v[2]))
+}
+fn bits(v: Vec3) -> String {
+    format!(
+        "{:016x},{:016x},{:016x}",
+        v.x.to_bits(),
+        v.y.to_bits(),
+        v.z.to_bits()
+    )
+}
+fn seed(v: &Value) -> i64 {
+    v.as_str().unwrap().parse().unwrap()
+}
+fn particle(k: ArrowParticle) -> &'static str {
+    match k {
+        ArrowParticle::Bubble => "bubble",
+        ArrowParticle::Crit => "crit",
+        ArrowParticle::Splash => "splash",
+    }
+}
+fn main() -> Result<()> {
+    let args: Vec<_> = std::env::args().skip(1).collect();
+    if args.len() != 3 {
+        return Err("usage: arrow_probe RESOURCES FIXTURE_DIRECTORY --describe|REFERENCE".into());
+    }
+    let root = PathBuf::from(&args[0]);
+    let dir = PathBuf::from(&args[1]);
+    let assets = Assets::load(&root)?;
+    let mut scene = World::test_scene(&assets, 1)?;
+    fs::write(
+        dir.join("scene.json"),
+        serde_json::to_vec(
+            &serde_json::json!({"radius":1,"resident_chunks":scene.chunks.len(),"model_gallery":assets.model_gallery}),
+        )?,
+    )?;
+    if args[2] == "--describe" {
+        return Ok(());
+    }
+    let binding = collisions::load(&root, assets.registry)?;
+    let motion = MotionResources::load(&root, &assets)?;
+    let facts = BlockFacts::load(&root, assets.registry)?;
+    let side = &args[2];
+    let mut out = std::io::BufWriter::new(fs::File::create(dir.join(format!("rust-{side}.txt")))?);
+    let mut level_random = LegacyRandom::new(0);
+    for line in std::io::BufReader::new(fs::File::open(dir.join("inputs.txt"))?).lines() {
+        let f: Value = serde_json::from_str(&line?)?;
+        let kind = ProjectileKind::Arrow {
+            base_damage: 2.0,
+            critical: f["crit"].as_bool().unwrap(),
+            effect: None,
+        };
+        let mut arrow = Projectile::new(kind, vector(&f["position"]), None)
+            .with_arrow_random(LegacyRandom::new(seed(&f["seed"])));
+        arrow.velocity = vector(&f["velocity"]);
+        arrow.arrow.as_mut().unwrap().no_physics = f["no_physics"].as_bool().unwrap();
+        // ProjectileWeaponItem.useAmmo's stack, intangible when no ammo was used.
+        arrow.arrow.as_mut().unwrap().set_item(&arrows::drawn_ammo(
+            &ItemStack::new("minecraft:arrow", 1),
+            f["intangible"].as_bool().unwrap(),
+        ));
+        for op in f["ops"].as_array().unwrap() {
+            let mut events = Vec::new();
+            let mut touched = "-".to_string();
+            match op["mode"].as_str().unwrap() {
+                "tick" => {
+                    if !arrow.arrow.as_ref().unwrap().removed {
+                        let no_rain = |_| false;
+                        let view = ArrowScene {
+                            world: &scene,
+                            registry: assets.registry,
+                            facts: &facts,
+                            collision: &binding,
+                            fluids: &motion.fluids,
+                            raining: &no_rain,
+                            mob_griefing: true,
+                            tnt_explodes: true,
+                        };
+                        arrows::tick(&mut arrow, &view, &[]);
+                    }
+                    for event in arrow.arrow.as_mut().unwrap().events.drain(..) {
+                        match event {
+                            ArrowEvent::Particle {
+                                kind,
+                                position,
+                                velocity,
+                            } => events.push(format!(
+                                "particle {} {} {}",
+                                particle(kind),
+                                bits(position),
+                                bits(velocity)
+                            )),
+                            ArrowEvent::Sound {
+                                sound,
+                                volume,
+                                pitch,
+                            } => events.push(format!(
+                                "sound {} {:08x} {:08x}",
+                                match sound {
+                                    ArrowSound::HitGround => "hit",
+                                    ArrowSound::Splash => "splash",
+                                    ArrowSound::Extinguish => "extinguish",
+                                },
+                                volume.to_bits(),
+                                pitch.to_bits()
+                            )),
+                            ArrowEvent::BubbleColumnParticles { pos } => {
+                                for _ in 0..2 {
+                                    let x = f64::from(pos.x) + level_random.next_double();
+                                    let z = f64::from(pos.z) + level_random.next_double();
+                                    let at = Vec3::new(x, f64::from(pos.y + 1), z);
+                                    events.push(format!(
+                                        "sent splash {} {} {:016x}",
+                                        bits(at),
+                                        bits(Vec3::ZERO),
+                                        1.0f64.to_bits()
+                                    ));
+                                    let x = f64::from(pos.x) + level_random.next_double();
+                                    let z = f64::from(pos.z) + level_random.next_double();
+                                    let at = Vec3::new(x, f64::from(pos.y + 1), z);
+                                    events.push(format!(
+                                        "sent bubble {} {} {:016x}",
+                                        bits(at),
+                                        bits(Vec3::new(0.0, 0.01, 0.0)),
+                                        0.2f64.to_bits()
+                                    ));
+                                }
+                            }
+                            ArrowEvent::Block { pos, reaction } => match reaction {
+                                BlockReaction::PrimeTnt => {
+                                    // TntBlock.prime: PrimedTnt draws its push from the
+                                    // level random, then removeBlock(pos, false).
+                                    let _ = level_random.next_double();
+                                    let at = Vec3::new(
+                                        f64::from(pos.x) + 0.5,
+                                        f64::from(pos.y),
+                                        f64::from(pos.z) + 0.5,
+                                    );
+                                    events.push(format!("spawn tnt {} 80", bits(at)));
+                                    events.push(format!(
+                                        "sound tnt_primed {:08x} {:08x}",
+                                        1.0f32.to_bits(),
+                                        1.0f32.to_bits()
+                                    ));
+                                    events.push("prime-event".into());
+                                    let air =
+                                        assets.registry.default_state("minecraft:air").unwrap();
+                                    scene.set(pos.x, pos.y, pos.z, air)?;
+                                    events.push(format!(
+                                        "write {},{},{} {} 3",
+                                        pos.x, pos.y, pos.z, air.0
+                                    ));
+                                }
+                                BlockReaction::Light(lit) => {
+                                    scene.set(pos.x, pos.y, pos.z, lit)?;
+                                    events.push(format!(
+                                        "write {},{},{} {} 11",
+                                        pos.x, pos.y, pos.z, lit.0
+                                    ));
+                                }
+                            },
+                            ArrowEvent::SplashEvent => events.push("splash-event".into()),
+                            ArrowEvent::ShootEvent => events.push("shoot-event".into()),
+                        }
+                    }
+                }
+                "block" => {
+                    let p = &op["position"];
+                    let mut state = assets
+                        .registry
+                        .default_state(op["name"].as_str().unwrap())
+                        .ok_or("missing fixture block")?;
+                    if let Some(properties) = op["properties"].as_object() {
+                        let mut definition = assets.registry.state(state).unwrap().clone();
+                        for (name, value) in properties {
+                            definition
+                                .properties
+                                .insert(name.clone(), value.as_str().unwrap().into());
+                        }
+                        state = assets
+                            .registry
+                            .id(&definition)
+                            .ok_or("missing fixture state")?;
+                    }
+                    scene.set(
+                        p[0].as_i64().unwrap() as i32,
+                        p[1].as_i64().unwrap() as i32,
+                        p[2].as_i64().unwrap() as i32,
+                        state,
+                    )?;
+                }
+                "velocity" => arrow.velocity = vector(&op["value"]),
+                "ignite" => arrow
+                    .arrow
+                    .as_mut()
+                    .unwrap()
+                    .ignite_for_seconds(f32::from_bits(
+                        u32::from_str_radix(op["value"].as_str().unwrap(), 16).unwrap(),
+                    )),
+                "level_seed" => level_random.set_seed(seed(&op["value"])),
+                "owner" => arrow
+                    .arrow
+                    .as_mut()
+                    .unwrap()
+                    .set_owner(match op["value"].as_str() {
+                        Some("player") => Some(Who::Player),
+                        Some("mob") => Some(Who::Mob(1)),
+                        _ => None,
+                    }),
+                "pickup" => {
+                    arrow.arrow.as_mut().unwrap().pickup =
+                        Pickup::from_byte(op["value"].as_i64().unwrap())
+                }
+                // The game's touch: the inventory takes the arrow unless full,
+                // and a creative player takes it anyway.
+                "touch" => {
+                    let creative = op["creative"].as_bool().unwrap();
+                    let full = op["inventory"] == "full";
+                    let a = arrow.arrow.as_mut().unwrap();
+                    let (taken, arrows) = match a.player_touch(creative) {
+                        Touch::Ignore => (false, 0),
+                        Touch::Take => (true, 0),
+                        Touch::Give(_) => (!full || creative, u32::from(!full)),
+                    };
+                    if taken {
+                        a.removed = true;
+                    }
+                    touched = format!("{taken} {arrows}");
+                }
+                other => return Err(format!("unknown operation {other}").into()),
+            }
+            let a = arrow.arrow.as_ref().unwrap();
+            writeln!(
+                out,
+                "arrow {} {} {:08x} {:08x} {} {} {} {} {} {} {} {} {} {:016x} {:016x} {} {} {:016x} {}",
+                bits(arrow.position),
+                bits(arrow.velocity),
+                arrow.pitch.to_bits(),
+                arrow.yaw.to_bits(),
+                a.in_ground,
+                a.in_ground_time,
+                a.life,
+                a.shake,
+                a.last_state.map_or("none".into(), |s| s.0.to_string()),
+                a.fire_ticks,
+                a.was_touching_water,
+                a.was_eye_in_water,
+                a.first_tick,
+                a.fluids.fluid_height(&Tags, WATER).to_bits(),
+                a.fluids.fluid_height(&Tags, LAVA).to_bits(),
+                a.removed,
+                arrow.critical(),
+                a.fall_distance.to_bits(),
+                bits(arrow.previous)
+            )?;
+            writeln!(out, "events {}", events.join(" | "))?;
+            let a = arrow.arrow.as_ref().unwrap();
+            let intangible = a
+                .pickup_item
+                .data()
+                .and_then(|d| d.other(arrows::INTANGIBLE))
+                .is_some();
+            writeln!(out, "pickup {} {intangible} {touched}", a.pickup.byte())?;
+        }
+        writeln!(out, "end")?;
+    }
+    Ok(())
+}
+struct Tags;
+impl horizon_world::entity_fluid::FluidMembership for Tags {
+    fn fluid_in_tag(
+        &self,
+        kind: horizon_world::fluid::FluidKind,
+        tag: horizon_world::entity_fluid::FluidTagId,
+    ) -> bool {
+        use horizon_world::fluid::FluidKind;
+        if tag == WATER {
+            matches!(kind, FluidKind::Water | FluidKind::FlowingWater)
+        } else {
+            matches!(kind, FluidKind::Lava | FluidKind::FlowingLava)
+        }
+    }
+}
@@ -0,0 +1,61 @@
+//! Transport for ClientLevel shape-aware terrain-particle placement.
+use horizon_client::{assets::Assets, blocks::BlockFacts, mesher::MeshTables, models, particles};
+use horizon_core::random::{LegacyRandom, RandomSource};
+use horizon_world::registry::BlockStateId;
+use serde_json::{Value, json};
+use std::{
+    fs,
+    io::{BufRead, BufReader, BufWriter, Write},
+    path::Path,
+};
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let args: Vec<_> = std::env::args().collect();
+    let root = Path::new(&args[1]);
+    let assets = Assets::load(root)?;
+    let facts = BlockFacts::load(root, assets.registry)?;
+    let tables = MeshTables::new(
+        &assets,
+        &facts,
+        models::load_visibility(root, assets.registry)?,
+    )?;
+    let mut output = BufWriter::new(fs::File::create(&args[3])?);
+    for line in BufReader::new(fs::File::open(&args[2])?).lines() {
+        let row: Value = serde_json::from_str(&line?)?;
+        let state = BlockStateId(row["state"].as_u64().unwrap() as u32);
+        let pos: [i32; 3] = serde_json::from_value(row["pos"].clone())?;
+        let offset = if facts.get(state).outline_offset {
+            tables.offset(state, pos[0], pos[2]).unwrap_or([0.0; 3])
+        } else {
+            [0.0; 3]
+        };
+        let boxes: Vec<[f64; 6]> = facts
+            .get(state)
+            .outline
+            .iter()
+            .map(|b| std::array::from_fn(|i| b[i] + offset[i % 3]))
+            .collect();
+        let mut hits = Vec::new();
+        let mut next = Vec::new();
+        for face in [
+            [0, -1, 0],
+            [0, 1, 0],
+            [0, 0, -1],
+            [0, 0, 1],
+            [-1, 0, 0],
+            [1, 0, 0],
+        ] {
+            let mut random = LegacyRandom::new(row["seed"].as_i64().unwrap());
+            hits.push(particles::breaking_position(&mut random, pos, face, &boxes));
+            next.push(random.next_long());
+        }
+        let mut destroy = Vec::new();
+        particles::destroy_positions(pos, &boxes, |p, _| destroy.push(p));
+        serde_json::to_writer(
+            &mut output,
+            &json!({"case":row["case"],"hits":hits,"next":next,"destroy":destroy}),
+        )?;
+        output.write_all(&[10])?;
+    }
+    output.flush()?;
+    Ok(())
+}
@@ -0,0 +1,74 @@
+//! Headless transport for real model-shaped breaking overlays.
+use horizon_client::{
+    assets::Assets,
+    blocks::{BlockFacts, RenderShape},
+    breaking,
+    mesher::MeshTables,
+    models,
+};
+use horizon_core::position::BlockPos;
+use horizon_world::registry::BlockStateId;
+use serde_json::{Value, json};
+use std::{
+    fs,
+    io::{BufRead, BufReader, BufWriter, Write},
+    path::Path,
+};
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let args: Vec<_> = std::env::args().collect();
+    let root = Path::new(&args[1]);
+    let assets = Assets::load(root)?;
+    let facts = BlockFacts::load(root, assets.registry)?;
+    let tables = MeshTables::new(
+        &assets,
+        &facts,
+        models::load_visibility(root, assets.registry)?,
+    )?;
+    let mut output = BufWriter::new(fs::File::create(&args[3])?);
+    for line in BufReader::new(fs::File::open(&args[2])?).lines() {
+        let row: Value = serde_json::from_str(&line?)?;
+        let state = BlockStateId(row["state"].as_u64().unwrap() as u32);
+        let p: [i32; 3] = serde_json::from_value(row["pos"].clone())?;
+        let camera: [f64; 3] = serde_json::from_value(row["camera"].clone())?;
+        let mut vertices = Vec::new();
+        let mut translucent = false;
+        if facts.get(state).render_shape == RenderShape::Model {
+            let models = assets
+                .model_catalog
+                .collect(state, BlockPos::new(p[0], p[1], p[2]))?;
+            let offset = tables.offset(state, p[0], p[2]).unwrap_or([0.0; 3]);
+            let origin = (glam::DVec3::new(f64::from(p[0]), f64::from(p[1]), f64::from(p[2]))
+                - glam::DVec3::from(camera))
+            .as_vec3()
+                + glam::DVec3::from(offset).as_vec3();
+            translucent = models
+                .iter()
+                .any(|(_, m)| m.faces.iter().any(|f| f.translucent));
+            for (_, m) in models {
+                breaking::geometry(m, origin, translucent, &mut vertices);
+            }
+        }
+        let quads: Vec<_> = vertices
+            .as_chunks::<4>()
+            .0
+            .iter()
+            .map(|q| {
+                q.iter()
+                    .map(|v| {
+                        assert_eq!(v.color, 0xffff_ffff);
+                        assert_eq!(v.light, 240 | (240 << 8));
+                        assert_eq!(v.layer, if translucent { 12 } else { 11 });
+                        [v.pos[0], v.pos[1], v.pos[2], v.uv[0], v.uv[1]]
+                    })
+                    .collect::<Vec<_>>()
+            })
+            .collect();
+        serde_json::to_writer(
+            &mut output,
+            &json!({"case":row["case"],"translucent":translucent,"quads":quads}),
+        )?;
+        output.write_all(&[10])?;
+    }
+    output.flush()?;
+    Ok(())
+}
@@ -5,7 +5,7 @@ use horizon_client::{
    Result,
    camera::{
        AvatarBob, BobState, Camera, CameraEntity, CameraFluid, CameraType, FovPlayer, HurtBob,
-        LivingCamera, UseItem, bob_matrix, field_of_view_modifier,
+        LivingCamera, UseItem, bob_matrix, field_of_view_modifier, perspective,
    },
 };
 use horizon_core::{
@@ -258,6 +258,15 @@ fn camera(c: &Value, out: &mut impl Write) -> Result<()> {
                    fb(fov),
                    fb(hud)
                )?;
+                let (w, h, far) = (fl(&op[4]), fl(&op[5]), fl(&op[6]));
+                let matrix =
+                    |m: [f32; 16]| m.iter().map(|&x| format!(" {}", fb(x))).collect::<String>();
+                writeln!(
+                    out,
+                    "projection{}{}",
+                    matrix(perspective(fov, w, h, far, 0.05, true)),
+                    matrix(perspective(hud, w, h, far, 0.05, true))
+                )?;
            }
            other => panic!("{other}"),
        }
@@ -87,6 +87,7 @@ fn main() -> horizon_client::Result<()> {
        recipes: &recipes,
        brewing: &brewing,
        banners: &banners,
+        trade: None,
    };
    let mut out = String::new();
    for line in input.lines() {
@@ -9,7 +9,7 @@ use horizon_client::{
    biome::Biomes,
    blocks::BlockFacts,
    chunk::{Chunk, MIN_Y, SECTIONS},
-    light::{LightTables, light_chunk},
+    light::{LightTables, apply_lighting, light_chunk},
    mesher::{MeshTables, Mesher},
    models,
    streaming::{ChunkGenerator, Proto},
@@ -105,7 +105,7 @@ fn main() -> Result<()> {
    );
    let mut chunks: Vec<Chunk> = chunks.iter().map(|c| (**c).clone()).collect();
    for ((x, z), sections) in lit {
-        chunks[((z - 1) * inner + x - 1) as usize].sections = sections;
+        apply_lighting(&mut chunks[((z - 1) * inner + x - 1) as usize], sections);
    }
    let chunks: Vec<Arc<Chunk>> = chunks.into_iter().map(Arc::new).collect();
    let at = |x: i32, z: i32| chunks[((z - 1) * inner + x - 1) as usize].clone();
@@ -0,0 +1,39 @@
+//! CloudRenderer face selection and mesh traversal, without a GPU.
+use horizon_client::clouds;
+use std::{fmt::Write, fs};
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let args: Vec<_> = std::env::args().collect();
+    let mut output = String::new();
+    for (case, line) in fs::read_to_string(&args[1])?.lines().enumerate() {
+        let values: Vec<i32> = line
+            .split_whitespace()
+            .map(|v| v.parse().unwrap())
+            .collect();
+        let [kind, x, z, bottom, neighbors] = values.as_slice() else {
+            panic!("invalid case")
+        };
+        write!(output, "{case}")?;
+        let mut cell = |x, z, neighbors| {
+            let empty = std::array::from_fn(|i| neighbors & (1 << i) != 0);
+            for (direction, inside) in clouds::faces(clouds::face_mask(x, z, *bottom as f32, empty))
+            {
+                write!(output, " {x},{z},{direction},{}", u8::from(inside)).unwrap();
+            }
+        };
+        let radius = if *kind == 2 {
+            clouds::radius_cells(*x)
+        } else {
+            *x
+        };
+        if *kind == 0 {
+            cell(*x, *z, *neighbors);
+        } else {
+            for (x, z) in clouds::cells(radius) {
+                cell(x, z, 0);
+            }
+        }
+        output.push('\n');
+    }
+    fs::write(&args[2], output)?;
+    Ok(())
+}
@@ -0,0 +1,86 @@
+#![forbid(unsafe_code)]
+//! Runs tools/test_container_screen_parity.py's screens and mouse events
+//! through `horizon_client::container_screen`.
+use horizon_client::{
+    Result,
+    container_screen::{Book, Button, Clicks, Image, Release, Target, clicked_outside},
+    menu::Input,
+};
+use serde_json::Value;
+use std::{
+    fs::File,
+    io::{BufRead, BufReader, BufWriter, Write},
+};
+
+fn input_name(input: Input) -> &'static str {
+    match input {
+        Input::Pickup => "PICKUP",
+        Input::QuickMove => "QUICK_MOVE",
+        Input::Swap => "SWAP",
+        Input::Clone => "CLONE",
+        Input::Throw => "THROW",
+        Input::QuickCraft => "QUICK_CRAFT",
+        Input::PickupAll => "PICKUP_ALL",
+    }
+}
+
+fn main() -> Result<()> {
+    let args: Vec<String> = std::env::args().collect();
+    let input = BufReader::new(File::open(&args[1])?);
+    let mut out = BufWriter::new(File::create(&args[2])?);
+    for (n, line) in input.lines().enumerate() {
+        let c: Value = serde_json::from_str(&line?)?;
+        writeln!(out, "== {n}")?;
+        let int = |v: &Value| v.as_i64().unwrap() as i32;
+        let image = Image {
+            left: int(&c["image"][0]),
+            top: int(&c["image"][1]),
+            width: int(&c["image"][2]),
+            height: int(&c["image"][3]),
+        };
+        let book = c.get("book").map(|b| Book {
+            visible: b[0].as_bool().unwrap(),
+            selected_tab_hovered: b[1].as_bool().unwrap(),
+        });
+        let mut clicks = Clicks::default();
+        for ev in c["events"].as_array().unwrap() {
+            let name = ev[0].as_str().unwrap();
+            let (x, y) = (ev[1].as_f64().unwrap(), ev[2].as_f64().unwrap());
+            let outside = clicked_outside(x, y, image, book);
+            let mut line = format!("{name} {outside}");
+            if name != "point" {
+                // The case says whether the event is over the menu's slot (7).
+                let on_slot = ev[6].as_bool().unwrap();
+                line += &format!(" {on_slot}");
+                let target = Target::of(on_slot.then_some(7), outside);
+                let button = match ev[3].as_i64().unwrap() {
+                    1 => Button::Left,
+                    3 => Button::Right,
+                    _ => Button::Middle,
+                };
+                let shift = ev[4].as_i64().unwrap() & 3 != 0;
+                let carried_empty = !ev[5].as_bool().unwrap();
+                let click = if name == "press" {
+                    clicks.press(&target, button, carried_empty, shift, false)
+                } else {
+                    match clicks.release(&target, button, carried_empty, false, shift, false) {
+                        Release::Click(input) => Some(input),
+                        Release::QuickCraft => panic!("no drags in these cases"),
+                        Release::Nothing => None,
+                    }
+                };
+                if let Some(input) = click {
+                    let id = match target {
+                        Target::Slot(s) => s,
+                        Target::Outside => -999,
+                        Target::Nothing => -1,
+                    };
+                    line += &format!(" click {id} {} {}", button.menu_button(), input_name(input));
+                }
+            }
+            writeln!(out, "{line}")?;
+        }
+    }
+    out.flush()?;
+    Ok(())
+}
@@ -0,0 +1,53 @@
+//! The creative inventory, for tools/test_creative_parity.py: loads an
+//! exported `creative-inventory.json` into `horizon_client::creative::Creative`
+//! and prints the tabs it shows (canonical stacks) and the search tab's
+//! results for every query of the vanilla oracle's output.
+//!
+//! usage: creative_search_fixture RESOURCES CREATIVE_JSON VANILLA_JSON OUTPUT
+use horizon_client::{
+    creative::{Creative, Names},
+    item_data::canon_stack,
+};
+use serde_json::{Value, json};
+use std::{fs, path::Path};
+
+fn main() -> horizon_client::Result<()> {
+    let args: Vec<String> = std::env::args().collect();
+    let usage = "usage: creative_search_fixture RESOURCES CREATIVE_JSON VANILLA_JSON OUTPUT";
+    let names = Names::load(Path::new(args.get(1).ok_or(usage)?));
+    let creative = Creative::from_json(&serde_json::from_slice(&fs::read(
+        args.get(2).ok_or(usage)?,
+    )?)?)?;
+    let vanilla: Value = serde_json::from_slice(&fs::read(args.get(3).ok_or(usage)?)?)?;
+    let tabs: Vec<Value> = creative
+        .tabs
+        .iter()
+        .map(|t| {
+            json!({
+                "id": t.id,
+                "title": t.title,
+                "icon": t.icon,
+                "row": if t.top { "TOP" } else { "BOTTOM" },
+                "column": t.column,
+                "items": t.items.iter().map(|s| canon_stack(Some(s))).collect::<Vec<_>>(),
+            })
+        })
+        .collect();
+    let searches: Vec<Value> = vanilla["searches"]
+        .as_array()
+        .ok_or("searches")?
+        .iter()
+        .map(|s| {
+            let query = s["query"].as_str().unwrap_or_default();
+            json!({"query": query, "results": creative.search_results(query, &names)})
+        })
+        .collect();
+    let search: Vec<String> = creative
+        .search_items()
+        .iter()
+        .map(|s| canon_stack(Some(s)))
+        .collect();
+    let out = json!({"tabs": tabs, "search": search, "searches": searches});
+    fs::write(args.get(4).ok_or(usage)?, out.to_string())?;
+    Ok(())
+}
@@ -0,0 +1,74 @@
+#![forbid(unsafe_code)]
+//! Runs tools/test_emitter_particles_parity.py's emitters through
+//! `particles::on_block_faces`, `particles::along_axis` and
+//! `particles::item_use_particles`.
+use horizon_client::{Result, particles};
+use horizon_core::random::{LegacyRandom, RandomSource};
+use serde_json::Value;
+use std::{
+    fs::File,
+    io::{BufRead, BufReader, BufWriter, Write},
+};
+
+fn d(v: f64) -> String {
+    format!("{:016x}", v.to_bits())
+}
+
+fn main() -> Result<()> {
+    let args: Vec<String> = std::env::args().collect();
+    let mut out = BufWriter::new(File::create(&args[2])?);
+    for (n, line) in BufReader::new(File::open(&args[1])?).lines().enumerate() {
+        let c: Value = serde_json::from_str(&line?)?;
+        writeln!(out, "== {n}")?;
+        let mut random = LegacyRandom::new(c["seed"].as_i64().ok_or("seed")?);
+        let mut lines = Vec::new();
+        let record = |kind: &str| {
+            let kind = kind.to_owned();
+            move |p: [f64; 3], v: [f64; 3]| {
+                format!(
+                    "+ {kind} {} {} {} {} {} {}",
+                    d(p[0]),
+                    d(p[1]),
+                    d(p[2]),
+                    d(v[0]),
+                    d(v[1]),
+                    d(v[2])
+                )
+            }
+        };
+        if c["kind"] == "item_use" {
+            let p: [f64; 3] = std::array::from_fn(|i| c["pos"][i].as_f64().unwrap_or(0.0));
+            let f = |k: &str| c[k].as_f64().unwrap_or(0.0) as f32;
+            let line = record("item");
+            particles::item_use_particles(
+                &mut random,
+                f("pitch"),
+                f("yaw"),
+                p,
+                p[1] + f64::from(f("eye")),
+                c["count"].as_u64().unwrap_or(0) as u32,
+                |p, v| lines.push(line(p, v)),
+            );
+        } else {
+            let p: [i32; 3] = std::array::from_fn(|i| c["pos"][i].as_i64().unwrap_or(0) as i32);
+            match c["axis"].as_i64() {
+                Some(axis @ 0..=2) => {
+                    let line = record("electric_spark");
+                    particles::along_axis(&mut random, axis as usize, p, |p, v| {
+                        lines.push(line(p, v))
+                    });
+                }
+                _ => {
+                    let line = record("wax_on");
+                    particles::on_block_faces(&mut random, p, |p, v| lines.push(line(p, v)));
+                }
+            }
+        }
+        for l in lines {
+            writeln!(out, "{l}")?;
+        }
+        writeln!(out, "next {}", random.next_long())?;
+    }
+    out.flush()?;
+    Ok(())
+}
@@ -1,14 +1,17 @@
 //! Replays the render states of the vanilla entity-animation oracle through
-//! Horizon's `mobs::anim::setup` and writes every part's pose.
+//! Horizon's `mobs::anim::setup` and writes every part's pose, then draws the
+//! posed model with `mobs::render::draw` under the case's living-entity root
+//! transform and writes each drawn part's packed vertex normals.
 //!
 //! cargo run --profile fast -p horizon-client --example entity_anim_fixture -- \
 //!     RESOURCES VANILLA.jsonl OUT.jsonl
+use horizon_client::mesher::Vertex;
 use horizon_client::mobs::{
    Mob, MobData, MobTypes, Part, Species, allay,
    anim::{self, Poses, State},
    aquatic, body_anim as b_anim, equine, guardian,
    keyframes::AnimationState,
-    shulker, sniffer, species, tame,
+    render, shulker, sniffer, species, tame,
 };
 use horizon_core::geometry::Vec3;
 use serde_json::{Value, json};
@@ -44,6 +47,61 @@ fn walk(part: &Part, path: &str, poses: &Poses, out: &mut BTreeMap<String, Value
    }
 }

+/// Splits the vertices `render::draw` emitted for `part` into its drawn parts,
+/// following draw's walk: a hidden or zero-scaled part ends its branch, a
+/// skip-draw part keeps its children. Per part: n = packed normal bytes per
+/// vertex, p = sum of x + 2y + 3z over the positions.
+fn drawn(
+    part: &Part,
+    path: &str,
+    poses: &Poses,
+    vertices: &[Vertex],
+    cursor: &mut usize,
+    out: &mut BTreeMap<String, Value>,
+) {
+    let p = poses.pose(part);
+    if poses.is_hidden(part) || p[6] == 0.0 && p[7] == 0.0 && p[8] == 0.0 {
+        return;
+    }
+    let count = if poses.skips(part) {
+        0
+    } else {
+        part.polygons.len() * 4
+    };
+    if count > 0 {
+        let own = &vertices[*cursor..*cursor + count];
+        let normals: Vec<i8> = own.iter().flat_map(|v| v.normal[..3].to_vec()).collect();
+        let sum: f64 = own
+            .iter()
+            .map(|v| f64::from(v.pos[0]) + 2.0 * f64::from(v.pos[1]) + 3.0 * f64::from(v.pos[2]))
+            .sum();
+        out.insert(path.to_owned(), json!({"n": normals, "p": sum}));
+    }
+    *cursor += count;
+    for c in &part.children {
+        let child = if path.is_empty() {
+            c.name.clone()
+        } else {
+            format!("{path}/{}", c.name)
+        };
+        drawn(c, &child, poses, vertices, cursor, out);
+    }
+}
+
+/// LivingEntityRenderer's root transform without the entity's position:
+/// rotate 180 - yaw about Y, scale(-1, -1, 1), the renderer's own scale, then
+/// translate(0, -1.501, 0) (as `render::base_transform`).
+fn root_transform(case: &Value) -> glam::Mat4 {
+    let yaw = case["@rootYaw"].as_f64().unwrap_or(0.0) as f32;
+    let scale = case["@rootScale"].as_array().map_or(glam::Vec3::ONE, |s| {
+        glam::Vec3::from_array(std::array::from_fn(|i| s[i].as_f64().unwrap_or(1.0) as f32))
+    });
+    glam::Mat4::from_rotation_y((180.0 - yaw).to_radians())
+        * glam::Mat4::from_scale(glam::Vec3::new(-1.0, -1.0, 1.0))
+        * glam::Mat4::from_scale(scale)
+        * glam::Mat4::from_translation(glam::Vec3::new(0.0, -1.501, 0.0))
+}
+
 /// The entity-side values behind the render-state fields the case sets, for
 /// the species whose Horizon animation reads them from the `Mob`.
 fn entity_state(mob: &mut Mob, species: Species, case: &Value) {
@@ -236,12 +294,26 @@ fn main() -> horizon_client::Result<()> {
    let types = MobTypes::load(&root)?;
    let animations = MobData::load_animations(&root);
    let mut out = String::new();
+    let crystal = horizon_client::mobs::load_model(&root, "minecraft:end_crystal#main");
    for line in fs::read_to_string(&args[1])?.lines() {
        let v: Value = serde_json::from_str(line)?;
        let layer = v["layer"]
            .as_str()
            .unwrap_or_default()
            .trim_start_matches("minecraft:");
+        // EndCrystalModel is not a mob's: horizon_client::end_crystal poses it.
+        if layer == "end_crystal#main"
+            && let Some(model) = &crystal
+        {
+            let case = &v["case"];
+            let mut poses = horizon_client::end_crystal::poses(
+                model,
+                case["ageInTicks"].as_f64().unwrap_or(0.0) as f32,
+                case["showsBottom"].as_bool().unwrap_or(false),
+            );
+            out.push_str(&format!("{}\n", emit(model, &mut poses, case, layer)));
+            continue;
+        }
        let baby = layer.contains("_baby#");
        let adult = layer.replace("_baby#", "#");
        // Variant layers (sizes, hatless villagers, climate cows...) animate
@@ -518,10 +590,38 @@ fn main() -> horizon_client::Result<()> {
            }
            _ => anim::setup(&mob, s, p, &animations),
        }
-        let mut parts = BTreeMap::new();
-        walk(&model, "", &poses, &mut parts);
-        out.push_str(&format!("{}\n", json!({"parts": parts})));
+        out.push_str(&format!("{}\n", emit(&model, &mut poses, case, layer)));
    }
    fs::write(&args[2], out)?;
    Ok(())
 }
+
+/// Every part's pose, and the vertices drawn under the harness's root transform.
+fn emit(model: &Part, poses: &mut Poses, case: &Value, layer: &str) -> Value {
+    // The harness's part-scale override, set after setupAnim as the oracle does.
+    if let Some(scale) = case["@partScale"].as_array() {
+        let pose = poses.get(scale[0].as_str().unwrap_or_default());
+        for i in 0..3 {
+            pose[6 + i] = scale[1 + i].as_f64().unwrap_or(1.0) as f32;
+        }
+    }
+    let poses = &*poses;
+    let mut parts = BTreeMap::new();
+    walk(model, "", poses, &mut parts);
+    let mut emitted = Vec::new();
+    render::draw(
+        model,
+        root_transform(case),
+        poses,
+        [0.0, 0.0, 1.0, 1.0],
+        0xFFFF_FFFF,
+        240 | 240 << 8,
+        0,
+        &mut emitted,
+    );
+    let mut vertices = BTreeMap::new();
+    let mut cursor = 0;
+    drawn(model, "", poses, &emitted, &mut cursor, &mut vertices);
+    assert_eq!(cursor, emitted.len(), "{layer}: draw's walk changed");
+    json!({"parts": parts, "vertices": vertices})
+}
@@ -0,0 +1,89 @@
+#![forbid(unsafe_code)]
+//! Runs tools/test_entity_components_parity.py's entities and advancement
+//! entity predicates through `horizon_client::advancements::entity`, with the
+//! variant component `mobs::finalize::species_variant_component` reports.
+use horizon_client::{
+    Result,
+    advancements::{EntityView, World, entity},
+    mobs::{
+        Species,
+        finalize::{species_variant_component, variant_index},
+    },
+};
+use serde_json::Value;
+use std::{
+    collections::BTreeMap,
+    fs::File,
+    io::{BufRead, BufReader, BufWriter, Write},
+};
+
+/// Nothing but the entity: these predicates read only its type and components.
+struct Empty;
+impl World for Empty {
+    fn dimension(&self) -> &str {
+        "minecraft:overworld"
+    }
+    fn biome(&self, _: [i32; 3]) -> String {
+        "minecraft:plains".into()
+    }
+    fn structures(&self, _: [i32; 3]) -> Vec<String> {
+        Vec::new()
+    }
+    fn block(&self, _: [i32; 3]) -> (String, BTreeMap<String, String>) {
+        ("minecraft:air".into(), BTreeMap::new())
+    }
+    fn fluid(&self, _: [i32; 3]) -> Option<String> {
+        None
+    }
+    fn can_see_sky(&self, _: [i32; 3]) -> bool {
+        true
+    }
+    fn light(&self, _: [i32; 3]) -> i32 {
+        15
+    }
+    fn smokey(&self, _: [i32; 3]) -> bool {
+        false
+    }
+    fn in_tag(&self, _: &str, _: &str, _: &str) -> bool {
+        false
+    }
+}
+
+fn species(id: &str) -> Species {
+    match id {
+        "minecraft:wolf" => Species::Wolf,
+        "minecraft:cat" => Species::Cat,
+        "minecraft:frog" => Species::Frog,
+        "minecraft:pig" => Species::Pig,
+        "minecraft:cow" => Species::Cow,
+        "minecraft:chicken" => Species::Chicken,
+        other => panic!("no species for {other}"),
+    }
+}
+
+fn main() -> Result<()> {
+    let args: Vec<String> = std::env::args().collect();
+    let input = BufReader::new(File::open(&args[1])?);
+    let mut out = BufWriter::new(File::create(&args[2])?);
+    for (n, line) in input.lines().enumerate() {
+        let c: Value = serde_json::from_str(&line?)?;
+        writeln!(out, "== {n}")?;
+        let kind = c["type"].as_str().unwrap();
+        let s = species(kind);
+        let variant = variant_index(s, c["variant"].as_str().unwrap());
+        let view = EntityView {
+            kind: kind.to_owned(),
+            position: [0.5, 64.0, 0.5],
+            components: species_variant_component(s, variant)
+                .map(|(id, v)| (id.to_owned(), v))
+                .into_iter()
+                .collect(),
+            ..Default::default()
+        };
+        for p in c["predicates"].as_array().unwrap() {
+            writeln!(out, "{}", entity(p, &view, &Empty, [2.5, 64.0, 0.5]))?;
+        }
+    }
+    out.flush()?;
+    Ok(())
+}
@@ -21,6 +21,7 @@ fn stack(spec: &str) -> LootStack {
        enchantments: Vec::new(),
        potion: None,
        map: false,
+        exploration: None,
        ominous_amplifier: None,
    };
    for e in parts {
@@ -0,0 +1,140 @@
+//! Isolated production mob-model builder benchmark; no assets, Game, GPU or full-frame work.
+//! CARGO_TARGET_DIR=/home/bob/Documents/horizon/target CARGO_INCREMENTAL=0 \
+//! cargo run --profile fast -p horizon-client --example entity_geometry_bench
+use horizon_client::{
+    mesher::Vertex,
+    mobs::{Part, Polygon, anim::Poses, render},
+};
+use std::{hint::black_box, time::Instant};
+
+fn cube(name: String, position: f32) -> Part {
+    let polygons = (0..6)
+        .map(|face| {
+            let axis = face / 2;
+            let side = (face % 2) as f32;
+            let mut normal = [0.0; 3];
+            normal[axis] = side * 2.0 - 1.0;
+            Polygon {
+                normal,
+                vertices: [[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0]].map(|uv| {
+                    let mut vertex = [0.0; 5];
+                    vertex[axis] = side * 8.0;
+                    vertex[(axis + 1) % 3] = uv[0] * 8.0;
+                    vertex[(axis + 2) % 3] = uv[1] * 8.0;
+                    vertex[3] = uv[0];
+                    vertex[4] = uv[1];
+                    vertex
+                }),
+            }
+        })
+        .collect();
+    Part {
+        name,
+        pose: [position, 0.0, 0.0, 0.1, 0.2, 0.0, 1.0, 1.0, 1.0],
+        polygons,
+        children: Vec::new(),
+    }
+}
+
+fn build(model: &Part, poses: &Poses, count: usize, out: &mut Vec<Vertex>) {
+    for i in 0..count {
+        render::draw(
+            black_box(model),
+            glam::Mat4::from_translation(glam::Vec3::new((i % 32) as f32, 0.0, (i / 32) as f32)),
+            black_box(poses),
+            [0.125, 0.25, 0.5, 0.75],
+            0xffc0_d0e0,
+            0xf0f0,
+            0,
+            out,
+        );
+    }
+    black_box(out.as_slice());
+}
+
+fn measure(model: &Part, poses: &Poses, count: usize, iterations: usize, reuse: bool) -> f64 {
+    let mut retained = Vec::new();
+    build(model, poses, count, &mut retained); // Untimed warmup.
+    let start = Instant::now();
+    for _ in 0..iterations {
+        let mut out = if reuse {
+            std::mem::take(&mut retained)
+        } else {
+            Vec::new()
+        };
+        out.clear();
+        build(model, poses, count, &mut out);
+        if reuse {
+            retained = out;
+        }
+    }
+    start.elapsed().as_secs_f64() * 1e6 / iterations as f64
+}
+
+fn main() {
+    let mut model = cube("body".into(), 0.0);
+    model.children = (1..6).map(|i| cube(format!("part{i}"), i as f32)).collect();
+    let poses = Poses::new(&model);
+    for count in [32, 256, 1024, 4096, 8192] {
+        let mut expected = Vec::new();
+        build(&model, &poses, count, &mut expected);
+        let mut retained = Vec::new();
+        build(&model, &poses, count, &mut retained);
+        let (pointer, capacity) = (retained.as_ptr(), retained.capacity());
+        // Populated -> empty/reset -> smaller -> populated must never leave stale vertices.
+        for n in [0, count / 2, count, count] {
+            retained.clear();
+            build(&model, &poses, n, &mut retained);
+            let mut fresh = Vec::new();
+            build(&model, &poses, n, &mut fresh);
+            assert_eq!(
+                bytemuck::cast_slice::<Vertex, u8>(&retained),
+                bytemuck::cast_slice::<Vertex, u8>(&fresh)
+            );
+            assert_eq!(
+                (retained.as_ptr(), retained.capacity()),
+                (pointer, capacity)
+            );
+        }
+        assert_eq!(
+            bytemuck::cast_slice::<Vertex, u8>(&retained),
+            bytemuck::cast_slice::<Vertex, u8>(&expected)
+        );
+        let iterations = (100_000 / count).clamp(40, 1000);
+        let mut fresh = Vec::new();
+        let mut reused = Vec::new();
+        let mut paired_speedups = Vec::new();
+        // Alternate order, reporting medians over eleven warmed batches.
+        for batch in 0..11 {
+            let mut pair = [0.0; 2];
+            for reuse in if batch % 2 == 0 {
+                [false, true]
+            } else {
+                [true, false]
+            } {
+                let time = measure(&model, &poses, count, iterations, reuse);
+                pair[usize::from(reuse)] = time;
+                if reuse {
+                    reused.push(time);
+                } else {
+                    fresh.push(time);
+                }
+            }
+            paired_speedups.push(pair[0] / pair[1]);
+        }
+        paired_speedups.sort_by(f64::total_cmp);
+        fresh.sort_by(f64::total_cmp);
+        reused.sort_by(f64::total_cmp);
+        println!(
+            "entities={count} vertices={} capacity={capacity} retained_bytes={} fresh_us={:.3} reused_us={:.3} speedup={:.3}x paired_speedup_median={:.3}x paired_speedup_range={:.3}..{:.3}x iterations={iterations} batches=11 byte_equivalence=pass pointer_capacity_reuse=pass",
+            retained.len(),
+            capacity * size_of::<Vertex>(),
+            fresh[5],
+            reused[5],
+            fresh[5] / reused[5],
+            paired_speedups[5],
+            paired_speedups[0],
+            paired_speedups[10]
+        );
+    }
+}
@@ -0,0 +1,51 @@
+#![forbid(unsafe_code)]
+//! Runs tools/test_entity_particles_parity.py's entity events through
+//! `particles::entity_event_burst` and `particles::around_self`.
+use horizon_client::{Result, particles};
+use horizon_core::random::{LegacyRandom, RandomSource};
+use serde_json::Value;
+use std::{
+    fs::File,
+    io::{BufRead, BufReader, BufWriter, Write},
+};
+
+fn d(v: f64) -> String {
+    format!("{:016x}", v.to_bits())
+}
+
+fn main() -> Result<()> {
+    let args: Vec<String> = std::env::args().collect();
+    let mut out = BufWriter::new(File::create(&args[2])?);
+    for (n, line) in BufReader::new(File::open(&args[1])?).lines().enumerate() {
+        let c: Value = serde_json::from_str(&line?)?;
+        writeln!(out, "== {n}")?;
+        let mut random = LegacyRandom::new(c["seed"].as_i64().ok_or("seed")?);
+        let feet: [f64; 3] = std::array::from_fn(|i| c["feet"][i].as_f64().unwrap_or(0.0));
+        // EntityDimensions hold floats.
+        let width = f64::from(c["width"].as_f64().unwrap_or(0.0) as f32);
+        let height = f64::from(c["height"].as_f64().unwrap_or(0.0) as f32);
+        let entity = c["entity"].as_str().unwrap_or("");
+        if let Some((kind, burst)) =
+            particles::entity_event_burst(entity, c["event"].as_u64().unwrap_or(0) as u8)
+        {
+            let mut lines = Vec::new();
+            particles::around_self(&mut random, feet, width, height, burst, |p, v| {
+                lines.push(format!(
+                    "+ {kind} {} {} {} {} {} {}",
+                    d(p[0]),
+                    d(p[1]),
+                    d(p[2]),
+                    d(v[0]),
+                    d(v[1]),
+                    d(v[2])
+                ));
+            });
+            for l in lines {
+                writeln!(out, "{l}")?;
+            }
+        }
+        writeln!(out, "next {}", random.next_long())?;
+    }
+    out.flush()?;
+    Ok(())
+}
@@ -64,6 +64,10 @@ fn main() -> horizon_client::Result<()> {
        );
        put("visual/fog_start_distance", format!("{:?}", sky.fog_start));
        put("visual/fog_end_distance", format!("{:?}", sky.fog_end));
+        put(
+            "visual/cloud_fog_end_distance",
+            format!("{:?}", sky.cloud_fog_end),
+        );
        out.push_str(&row);
        out.push_str("}\n");
    }
@@ -0,0 +1,32 @@
+#![forbid(unsafe_code)]
+//! Runs tools/test_fire_starter_sound_parity.py's level random seeds through
+//! the fire charge's use sound (`horizon_client::items::fire_starter_pitch`).
+use horizon_client::{
+    Result,
+    items::{fire_starter_pitch, fire_starter_sound},
+};
+use horizon_core::random::{LegacyRandom, RandomSource};
+use std::{
+    fs::File,
+    io::{BufRead, BufReader, BufWriter, Write},
+};
+
+fn main() -> Result<()> {
+    let args: Vec<String> = std::env::args().collect();
+    let input = BufReader::new(File::open(&args[1])?);
+    let mut out = BufWriter::new(File::create(&args[2])?);
+    for line in input.lines() {
+        let mut random = LegacyRandom::new(line?.trim().parse()?);
+        let pitch = fire_starter_pitch(true, &mut random);
+        writeln!(
+            out,
+            "{} {} {} {}",
+            fire_starter_sound(true),
+            1.0f32.to_bits() as i32,
+            pitch.to_bits() as i32,
+            random.next_long()
+        )?;
+    }
+    out.flush()?;
+    Ok(())
+}
@@ -0,0 +1,472 @@
+//! Probe for test_first_person_parity.py: drives horizon_client::first_person
+//! and attack_strength over the harness's scripted clicks, targets and use
+//! results, printing what VanillaFirstPersonOracle prints.
+use horizon_client::{
+    Result,
+    attack_strength::{AttackStrength, HeldStack},
+    first_person::{
+        Clicks, Hand, HandHeights, HandSway, HandWorld, Hit, SwingAnimation, SwingState, UseResult,
+        swing_duration,
+    },
+};
+use serde_json::Value;
+use std::{
+    collections::HashMap,
+    fs::File,
+    io::{BufRead, BufReader, BufWriter, Write},
+};
+
+fn fb(v: f32) -> String {
+    format!("{:08x}", v.to_bits())
+}
+fn fl(v: &Value) -> f32 {
+    f32::from_bits(u32::from_str_radix(v.as_str().unwrap(), 16).unwrap())
+}
+fn dl(v: &Value) -> f64 {
+    f64::from_bits(u64::from_str_radix(v.as_str().unwrap(), 16).unwrap())
+}
+
+/// An `ItemStack` object: the hands hold indices into `Probe::stacks`, so
+/// shrinking keeps its identity as vanilla's in-place `shrink` does.
+#[derive(Clone)]
+struct Stack {
+    item: String,
+    count: i32,
+}
+impl Stack {
+    fn empty(&self) -> bool {
+        self.item == "minecraft:air" || self.count <= 0
+    }
+    /// `getItem` and `getCount` of an empty stack are air and 0.
+    fn effective(&self) -> (&str, i32) {
+        if self.empty() {
+            ("minecraft:air", 0)
+        } else {
+            (&self.item, self.count)
+        }
+    }
+}
+
+struct Probe<'a> {
+    case: &'a Value,
+    step: &'a Value,
+    creative: bool,
+    stacks: Vec<Stack>,
+    /// The stacks in the main and off hand.
+    hands: [usize; 2],
+    blocks: HashMap<[i32; 3], String>,
+    swing: SwingState,
+    events: Vec<String>,
+    heights: HandHeights,
+}
+fn hand_name(hand: Hand) -> &'static str {
+    match hand {
+        Hand::Main => "main",
+        Hand::Off => "off",
+    }
+}
+impl Probe<'_> {
+    fn stack(&self, hand: Hand) -> &Stack {
+        &self.stacks[self.hands[hand as usize]]
+    }
+    fn new_stack(&mut self, v: &Value) -> usize {
+        // ItemStack.EMPTY is index 0.
+        if v.is_null() {
+            return 0;
+        }
+        self.stacks.push(Stack {
+            item: v[0].as_str().unwrap().into(),
+            count: v[1].as_i64().unwrap() as i32,
+        });
+        self.stacks.len() - 1
+    }
+    fn table<'b>(&'b self, name: &str) -> &'b Value {
+        &self.case["rust"][name]
+    }
+    fn attack_speed(&self) -> f64 {
+        let item = self.stack(Hand::Main).effective().0;
+        self.table("attack_speed").get(item).map_or(4.0, dl)
+    }
+    fn scripted(&mut self, kind: &str, hand: Hand) -> UseResult {
+        let name = self.step["uses"][kind].as_str().unwrap().to_string();
+        self.events
+            .push(format!("use {kind} {} {name}", hand_name(hand)));
+        let result = match name.as_str() {
+            "success" => UseResult::Success { swing: true },
+            "server" | "consume" => UseResult::Success { swing: false },
+            "fail" => UseResult::Fail,
+            _ => UseResult::Pass,
+        };
+        if matches!(result, UseResult::Success { .. }) && self.step["shrink"].as_bool().unwrap() {
+            let i = self.hands[hand as usize];
+            if i != 0 {
+                self.stacks[i].count -= 1;
+            }
+        }
+        result
+    }
+}
+impl HandWorld for Probe<'_> {
+    fn hit(&mut self) -> Hit {
+        let h = &self.step["hit"];
+        match h[0].as_str().unwrap() {
+            "block" => Hit::Block {
+                pos: [0, 1, 2].map(|i| h[i + 1].as_i64().unwrap() as i32),
+                face: h[4].as_u64().unwrap() as u8,
+            },
+            "entity" => Hit::Entity,
+            _ => Hit::Miss,
+        }
+    }
+    fn is_air(&mut self, pos: [i32; 3]) -> bool {
+        self.blocks.get(&pos).is_none_or(|b| b == "minecraft:air")
+    }
+    fn creative(&self) -> bool {
+        self.creative
+    }
+    fn spectator(&self) -> bool {
+        false
+    }
+    fn instabuild(&self) -> bool {
+        self.creative
+    }
+    fn hands_busy(&self) -> bool {
+        self.step["busy"].as_bool().unwrap()
+    }
+    fn using_item(&self) -> bool {
+        self.step["using"].as_bool().unwrap()
+    }
+    fn item_enabled(&mut self, _: Hand) -> bool {
+        true
+    }
+    fn held_empty(&mut self, hand: Hand) -> bool {
+        self.stack(hand).empty()
+    }
+    fn held_count(&mut self, hand: Hand) -> i32 {
+        self.stack(hand).effective().1
+    }
+    fn infinite_materials(&self) -> bool {
+        self.creative
+    }
+    fn cannot_attack(&mut self) -> bool {
+        false
+    }
+    fn piercing_weapon(&mut self) -> bool {
+        false
+    }
+    fn attack_animation(&mut self) -> SwingAnimation {
+        SwingAnimation::DEFAULT
+    }
+    fn interact_animation(&mut self, _: Hand) -> SwingAnimation {
+        SwingAnimation::DEFAULT
+    }
+    fn piercing_attack(&mut self, _: SwingAnimation) {
+        unreachable!()
+    }
+    fn attack_entity(&mut self) -> bool {
+        self.events.push("attack".into());
+        true
+    }
+    fn block_action_restricted(&mut self, _: [i32; 3]) -> bool {
+        false
+    }
+    fn within_border(&mut self, _: [i32; 3]) -> bool {
+        true
+    }
+    fn attack_block(&mut self, _: [i32; 3]) {}
+    /// `BlockBehaviour.getDestroyProgress` with `Player.getDestroySpeed` for
+    /// a player on the ground, out of water, with no mining efficiency.
+    fn destroy_progress(&mut self, pos: [i32; 3]) -> f32 {
+        let block = self.blocks.get(&pos).cloned().unwrap_or_default();
+        let b = &self.table("blocks")[block.as_str()];
+        let hardness = fl(&b[0]);
+        if hardness == -1.0 {
+            return 0.0;
+        }
+        let item = self.stack(Hand::Main).effective().0.to_string();
+        let tool = &self.table("tools")[format!("{item} {block}").as_str()];
+        let (mut speed, correct) = if tool.is_null() {
+            (1.0f32, false)
+        } else {
+            (fl(&tool[0]), tool[1].as_bool().unwrap())
+        };
+        if let Some(amp) = self.case["haste"].as_i64() {
+            speed *= 1.0 + (amp as i32 + 1) as f32 * 0.2;
+        }
+        if let Some(amp) = self.case["fatigue"].as_i64() {
+            speed *= horizon_core::jmath::pow(0.3, f64::from(amp as i32 + 1)) as f32;
+        }
+        let harvest = !b[1].as_bool().unwrap() || correct;
+        speed / hardness / if harvest { 30.0 } else { 100.0 }
+    }
+    fn destroy_block(&mut self, pos: [i32; 3]) -> bool {
+        let item = self.stack(Hand::Main).effective().0;
+        // Item.canDestroyBlock: swords' tools cannot destroy in creative.
+        let sword = item.ends_with("_sword");
+        let ok = !(sword && self.creative) && !self.is_air(pos);
+        if ok {
+            self.blocks.insert(pos, "minecraft:air".into());
+        }
+        self.events
+            .push(format!("destroy {} {} {} {ok}", pos[0], pos[1], pos[2]));
+        ok
+    }
+    /// The stack object itself: `destroyingItem` is a reference.
+    fn main_hand_key(&mut self) -> String {
+        self.hands[0].to_string()
+    }
+    fn same_destroying_item(&mut self, key: &str) -> bool {
+        // ItemStack.EMPTY (index 0) before any break.
+        let then = &self.stacks[key.parse::<usize>().unwrap_or(0)];
+        then.effective().0 == self.stack(Hand::Main).effective().0
+    }
+    fn destroy_stage(&mut self, pos: [i32; 3], stage: Option<i32>) {
+        self.events.push(format!(
+            "stage {} {} {} {}",
+            pos[0],
+            pos[1],
+            pos[2],
+            stage.unwrap_or(-1)
+        ));
+    }
+    fn swing(&mut self, hand: Hand, animation: SwingAnimation) {
+        let duration = swing_duration(
+            animation,
+            self.case["haste"].as_i64().map(|a| a as i32),
+            self.case["fatigue"].as_i64().map(|a| a as i32),
+        );
+        let started = self.swing.start_if_able(hand, animation, duration);
+        self.events.push(format!(
+            "swing {} {} {started}",
+            hand_name(hand),
+            animation.duration
+        ));
+    }
+    fn reset_attack_strength(&mut self) {
+        unreachable!("ResetWorld resets the tickers")
+    }
+    fn entity_within_border(&mut self) -> bool {
+        true
+    }
+    fn use_on_entity(&mut self, hand: Hand) -> Option<UseResult> {
+        self.step["hit"][1]
+            .as_bool()
+            .unwrap()
+            .then(|| self.scripted("entity", hand))
+    }
+    fn use_on_block(&mut self, hand: Hand) -> UseResult {
+        self.scripted("block", hand)
+    }
+    fn use_item(&mut self, hand: Hand) -> UseResult {
+        self.scripted("item", hand)
+    }
+    fn item_used(&mut self, hand: Hand) {
+        self.events.push(format!("used {}", hand_name(hand)));
+        self.heights.item_used(hand);
+    }
+    fn release_using(&mut self) {
+        self.events.push("release".into());
+    }
+}
+fn held(stack: &Stack) -> Option<HeldStack> {
+    (!stack.empty()).then(|| HeldStack {
+        item: stack.item.clone(),
+        rest: stack.count.to_string(),
+    })
+}
+
+fn run(case: &Value, out: &mut impl Write) -> Result<()> {
+    let empty = Value::Null;
+    let mut probe = Probe {
+        case,
+        step: &empty,
+        creative: case["creative"].as_bool().unwrap(),
+        stacks: vec![Stack {
+            item: "minecraft:air".into(),
+            count: 0,
+        }],
+        hands: [0, 0],
+        blocks: case["blocks"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .map(|b| {
+                (
+                    [0, 1, 2].map(|i| b[i].as_i64().unwrap() as i32),
+                    b[3].as_str().unwrap().to_string(),
+                )
+            })
+            .collect(),
+        swing: SwingState::default(),
+        events: Vec::new(),
+        heights: HandHeights::default(),
+    };
+    probe.hands[0] = probe.new_stack(&case["main"]);
+    probe.hands[1] = probe.new_stack(&case["off"]);
+    writeln!(out, "attack_speed {:x}", probe.attack_speed().to_bits())?;
+    let mut clicks = Clicks::default();
+    let mut strength = AttackStrength::default();
+    // FirstPersonHandsAndItems' visible items start as ItemStack.EMPTY.
+    let mut visible = [0usize, 0usize];
+    // The player's xRot and yRot, and the hands' lag behind them.
+    let mut rot = [0.0f32; 2];
+    let mut sway = HandSway::default();
+    for (s, step) in case["steps"].as_array().unwrap().iter().enumerate() {
+        probe.step = step;
+        probe.events.clear();
+        if !step["set"].is_null() {
+            let i = probe.new_stack(&step["set"]["stack"]);
+            let hand = if step["set"]["hand"] == "main" { 0 } else { 1 };
+            probe.hands[hand] = i;
+        }
+        clicks.tick(
+            &mut ResetWorld {
+                probe: &mut probe,
+                strength: &mut strength,
+            },
+            step["ac"].as_u64().unwrap() as u32,
+            step["uc"].as_u64().unwrap() as u32,
+            step["ad"].as_bool().unwrap(),
+            step["ud"].as_bool().unwrap(),
+        );
+        probe.swing.tick();
+        if let Some(r) = step["rot"].as_array() {
+            rot = [fl(&r[0]), fl(&r[1])];
+        }
+        sway.tick(rot[0], rot[1]);
+        let main = probe.stack(Hand::Main).clone();
+        strength.tick(held(&main));
+        // FirstPersonHandsAndItems.tick: shouldInstantlyReplaceVisibleItem
+        // (ItemStack.matchesIgnoringComponents; every item plays the swap
+        // animation), then the heights.
+        let mut changed = [false; 2];
+        for h in 0..2 {
+            let (a, b) = (visible[h], probe.hands[h]);
+            let same = a == b || probe.stacks[a].effective() == probe.stacks[b].effective();
+            if same {
+                visible[h] = b;
+            }
+            changed[h] = visible[h] != b;
+        }
+        let speed = probe.attack_speed();
+        let replace = probe.heights.tick(
+            probe.step["busy"].as_bool().unwrap(),
+            strength.swap_scale(1.0, speed),
+            changed,
+        );
+        for h in 0..2 {
+            if replace[h] {
+                visible[h] = probe.hands[h];
+            }
+        }
+        for e in &probe.events {
+            writeln!(out, "{e}")?;
+        }
+        let sw = &probe.swing;
+        let current = sw.current.map_or("- 0".to_string(), |c| {
+            format!("{} {}", hand_name(c.hand), c.duration_ticks)
+        });
+        let h = &probe.heights;
+        let d = &clicks.destroying;
+        writeln!(
+            out,
+            "tick {s} {current} {} {} {} {} {} {} {} {} {} {} {} {} {} {} {} {} {} {} {} {}",
+            sw.ticks,
+            fb(sw.animation),
+            fb(sw.old_animation),
+            fb(sw.animation(0.5)),
+            strength.ticker,
+            strength.swap_ticker,
+            fb(strength.swap_scale(1.0, speed)),
+            fb(h.main),
+            fb(h.old_main),
+            fb(h.off),
+            fb(h.old_off),
+            clicks.miss_time,
+            clicks.right_click_delay,
+            d.delay,
+            d.active,
+            fb(d.progress),
+            fb(sway.x_bob),
+            fb(sway.y_bob),
+            fb(sway.x_bob_o),
+            fb(sway.y_bob_o)
+        )?;
+    }
+    Ok(())
+}
+
+/// The probe with the attack-strength tickers it resets.
+struct ResetWorld<'p, 'c> {
+    probe: &'p mut Probe<'c>,
+    strength: &'p mut AttackStrength,
+}
+macro_rules! forward {
+    ($($name:ident($($arg:ident: $t:ty),*) -> $r:ty;)*) => {
+        $(fn $name(&mut self, $($arg: $t),*) -> $r { self.probe.$name($($arg),*) })*
+    };
+}
+impl HandWorld for ResetWorld<'_, '_> {
+    forward! {
+        hit() -> Hit;
+        is_air(pos: [i32; 3]) -> bool;
+        item_enabled(hand: Hand) -> bool;
+        held_empty(hand: Hand) -> bool;
+        held_count(hand: Hand) -> i32;
+        cannot_attack() -> bool;
+        piercing_weapon() -> bool;
+        attack_animation() -> SwingAnimation;
+        interact_animation(hand: Hand) -> SwingAnimation;
+        piercing_attack(a: SwingAnimation) -> ();
+        attack_entity() -> bool;
+        block_action_restricted(pos: [i32; 3]) -> bool;
+        within_border(pos: [i32; 3]) -> bool;
+        attack_block(pos: [i32; 3]) -> ();
+        destroy_progress(pos: [i32; 3]) -> f32;
+        destroy_block(pos: [i32; 3]) -> bool;
+        main_hand_key() -> String;
+        same_destroying_item(key: &str) -> bool;
+        destroy_stage(pos: [i32; 3], stage: Option<i32>) -> ();
+        swing(hand: Hand, a: SwingAnimation) -> ();
+        entity_within_border() -> bool;
+        use_on_entity(hand: Hand) -> Option<UseResult>;
+        use_on_block(hand: Hand) -> UseResult;
+        use_item(hand: Hand) -> UseResult;
+        item_used(hand: Hand) -> ();
+        release_using() -> ();
+    }
+    fn creative(&self) -> bool {
+        self.probe.creative()
+    }
+    fn spectator(&self) -> bool {
+        false
+    }
+    fn instabuild(&self) -> bool {
+        self.probe.instabuild()
+    }
+    fn hands_busy(&self) -> bool {
+        self.probe.hands_busy()
+    }
+    fn using_item(&self) -> bool {
+        self.probe.using_item()
+    }
+    fn infinite_materials(&self) -> bool {
+        self.probe.infinite_materials()
+    }
+    fn reset_attack_strength(&mut self) {
+        self.strength.reset();
+    }
+}
+
+fn main() -> Result<()> {
+    let args: Vec<String> = std::env::args().collect();
+    let input = BufReader::new(File::open(&args[1])?);
+    let mut out = BufWriter::new(File::create(&args[2])?);
+    for (n, line) in input.lines().enumerate() {
+        let c: Value = serde_json::from_str(&line?)?;
+        writeln!(out, "== {n}")?;
+        run(&c, &mut out)?;
+    }
+    out.flush()?;
+    Ok(())
+}
@@ -93,8 +93,9 @@ fn encode(draws: &[GuiDraw]) -> Vec<Value> {
                h,
                region,
                color,
+                blend,
            } => {
-                json!({"type": "sprite", "sprite": sprite, "x": x, "y": y, "w": w, "h": h, "region": region, "color": *color as i32})
+                json!({"type": "sprite", "sprite": sprite, "x": x, "y": y, "w": w, "h": h, "region": region, "color": *color as i32, "pipeline": blend.pipeline()})
            }
            GuiDraw::AtlasSprite {
                sprite,
@@ -190,7 +191,12 @@ fn decorations(c: &Value, atlas: &HudAtlas) -> Vec<GuiDraw> {
    // Spectators only see it over a spectatable target (none here).
    if c["crosshair"].as_bool().unwrap_or(false) && mode != "spectator" {
        let attack = (indicator == "CROSSHAIR").then(|| float("attackScale", 1.0));
-        draws.extend(hud_layout::crosshair(w, h, attack, false));
+        // crosshairPickEntity: absent, or a living entity alive or not.
+        let target = c["target"].as_bool();
+        let full = attack.is_some_and(|a| {
+            hud_layout::full_attack_indicator(a, float("attackDelay", 5.0), target)
+        });
+        draws.extend(hud_layout::crosshair(w, h, attack, full));
    }
    if mode != "spectator" {
        let pop = |v: &Value| v.as_f64().map(|p| p as f32 - partial);
@@ -0,0 +1,124 @@
+//! Compare the read + Value parse stages in BlockFacts::load and Assets::load.
+//! Usage: json_load_bench RESOURCE_ROOT [REPETITIONS]; see tools/json_load_fixtures.py.
+use serde_json::Value;
+use std::{
+    fs::{self, File},
+    hint::black_box,
+    io::BufReader,
+    path::Path,
+    time::{Duration, Instant},
+};
+
+type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
+
+fn reader(path: &Path) -> Result<Value> {
+    Ok(serde_json::from_reader(BufReader::new(File::open(path)?))?)
+}
+
+fn slice(path: &Path) -> Result<Value> {
+    Ok(serde_json::from_slice(&fs::read(path)?)?)
+}
+
+fn measure(path: &Path, load: fn(&Path) -> Result<Value>) -> Result<Duration> {
+    let start = Instant::now();
+    let value = black_box(load(black_box(path))?);
+    let elapsed = start.elapsed();
+    // Value destruction is excluded; the temporary byte buffer is released by slice().
+    drop(value);
+    Ok(elapsed)
+}
+
+fn main() -> Result<()> {
+    let mut args = std::env::args().skip(1);
+    let root = args
+        .next()
+        .ok_or("usage: json_load_bench ROOT [REPETITIONS]")?;
+    let repetitions: usize = args.next().map_or(Ok(15), |s| s.parse())?;
+    if repetitions == 0 {
+        return Err("REPETITIONS must be positive".into());
+    }
+    for name in ["gameplay-facts.json", "facts.json"] {
+        let path = Path::new(&root).join(name);
+        // Validate complete parsed trees on the exact files being timed.
+        assert_eq!(reader(&path)?, slice(&path)?);
+        for _ in 0..2 {
+            measure(&path, reader)?;
+            measure(&path, slice)?;
+        }
+        let (mut before, mut after) = (Vec::new(), Vec::new());
+        for i in 0..repetitions {
+            // Alternate order to reduce filesystem cache / frequency bias.
+            if i % 2 == 0 {
+                before.push(measure(&path, reader)?);
+                after.push(measure(&path, slice)?);
+            } else {
+                after.push(measure(&path, slice)?);
+                before.push(measure(&path, reader)?);
+            }
+        }
+        before.sort_unstable();
+        after.sort_unstable();
+        let median = |samples: &[Duration]| {
+            (samples[(samples.len() - 1) / 2].as_secs_f64()
+                + samples[samples.len() / 2].as_secs_f64())
+                * 500.0
+        };
+        let (before, after) = (median(&before), median(&after));
+        println!(
+            "{name}: {} bytes; {repetitions} samples; reader {before:.3} ms; slice {after:.3} ms; {:.2}x",
+            fs::metadata(&path)?.len(),
+            before / after
+        );
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn reader_and_slice_preserve_values_and_error_categories() -> Result<()> {
+        let path =
+            std::env::temp_dir().join(format!("horizon-json-load-{}.json", std::process::id()));
+        let check = || -> Result<()> {
+            fs::write(
+                &path,
+                br#"{"states":[{"id":0,"hardness":-1.5,"name":"escaped\n\u2603","outline":[[0,0,0,1,1,1]],"enabled":true}],"defaults":null}"#,
+            )?;
+            assert_eq!(reader(&path)?, slice(&path)?);
+            for invalid in [
+                &b"{\"states\":["[..],
+                &b"{\"states\":tru}"[..],
+                &b"{} trailing"[..],
+                &b"{\"name\":\"\xff\"}"[..],
+            ] {
+                fs::write(&path, invalid)?;
+                let before = reader(&path).unwrap_err();
+                let after = slice(&path).unwrap_err();
+                assert_eq!(
+                    before
+                        .downcast_ref::<serde_json::Error>()
+                        .unwrap()
+                        .classify(),
+                    after
+                        .downcast_ref::<serde_json::Error>()
+                        .unwrap()
+                        .classify()
+                );
+            }
+            fs::remove_file(&path)?;
+            for load in [reader, slice] {
+                let error = load(&path).unwrap_err();
+                assert_eq!(
+                    error.downcast_ref::<std::io::Error>().unwrap().kind(),
+                    std::io::ErrorKind::NotFound
+                );
+            }
+            Ok(())
+        };
+        let result = check();
+        let _ = fs::remove_file(path);
+        result
+    }
+}
@@ -0,0 +1,205 @@
+//! Compare the exact read/deserialize sequences used by the model loaders.
+//! Run with `cargo run -p horizon-client --profile fast --example json_readers_bench`.
+//! Optional arguments: resource directory, repetitions (default 9).
+use serde_json::{Map, Value, json};
+use std::{
+    collections::BTreeMap,
+    fmt::Debug,
+    fs::{self, File},
+    hint::black_box,
+    io::BufReader,
+    path::{Path, PathBuf},
+    time::Instant,
+};
+
+type Result<T> = horizon_client::Result<T>;
+
+#[derive(Clone, Copy)]
+enum Reader {
+    File,
+    Buffered,
+    Slice,
+}
+const READERS: [Reader; 3] = [Reader::File, Reader::Buffered, Reader::Slice];
+
+// These match the map types and reader expressions at all three production sites.
+macro_rules! reader {
+    ($name:ident, $map:ty) => {
+        fn $name(path: &Path, reader: Reader) -> Result<$map> {
+            Ok(match reader {
+                Reader::File => serde_json::from_reader(File::open(path)?)?,
+                Reader::Buffered => serde_json::from_reader(BufReader::new(File::open(path)?))?,
+                Reader::Slice => serde_json::from_slice(&fs::read(path)?)?,
+            })
+        }
+    };
+}
+reader!(prepare_facts, Map<String, Value>);
+reader!(catalog_facts, BTreeMap<String, Value>);
+
+struct Fixture(PathBuf);
+impl Fixture {
+    fn new() -> Result<Self> {
+        let root =
+            std::env::temp_dir().join(format!("horizon-json-readers-{}", std::process::id()));
+        fs::create_dir(&root)?;
+        Ok(Self(root))
+    }
+}
+impl Drop for Fixture {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.0);
+    }
+}
+
+fn fixtures(root: &Path) -> Result<()> {
+    let states: Vec<_> = (0..56)
+        .map(|i| {
+            json!({"facing": (["north", "east", "south", "west"][i % 4]),
+                "powered": if i / 4 % 2 == 0 { "false" } else { "true" },
+                "age": (i / 8).to_string()})
+        })
+        .collect();
+    let mut models = Map::new();
+    let mut render = Map::new();
+    for i in 0..1024 {
+        let name = format!("minecraft:fixture_block_{i:04}");
+        models.insert(
+            name.clone(),
+            json!({
+                "schema": {"facing": {"named": ["north", "east", "south", "west"]},
+                    "powered": {"named": ["false", "true"]}, "age": {"integer": [0, 6]}},
+                "states": states
+            }),
+        );
+        render.insert(
+            name,
+            json!({"rule": "never", "can_occlude": true, "bars_tag": false}),
+        );
+    }
+    fs::write(root.join("model-states.json"), serde_json::to_vec(&models)?)?;
+    fs::write(
+        root.join("render-definitions.json"),
+        serde_json::to_vec(&render)?,
+    )?;
+    Ok(())
+}
+
+fn benchmark<T: PartialEq + Debug>(
+    label: &str,
+    path: &Path,
+    repetitions: usize,
+    read: impl Fn(&Path, Reader) -> Result<T>,
+) -> Result<()> {
+    let expected = read(path, Reader::File)?;
+    for reader in READERS {
+        assert_eq!(expected, read(path, reader)?);
+        for _ in 0..2 {
+            black_box(read(black_box(path), reader)?);
+        }
+    }
+    drop(expected);
+    let mut samples: [Vec<f64>; 3] = std::array::from_fn(|_| Vec::new());
+    for repetition in 0..repetitions {
+        // Rotate reader order to distribute drift across implementations.
+        for offset in 0..3 {
+            let index = (repetition + offset) % 3;
+            let start = Instant::now();
+            let value = black_box(read(black_box(path), READERS[index])?);
+            samples[index].push(start.elapsed().as_secs_f64() * 1000.0);
+            drop(value); // Match the loaders: retain the parsed tree after loading.
+        }
+    }
+    let median: Vec<_> = samples
+        .iter_mut()
+        .map(|s| {
+            s.sort_by(f64::total_cmp);
+            s[s.len() / 2]
+        })
+        .collect();
+    println!(
+        "{label}: {} bytes, {repetitions} samples/reader, median ms: File={:.3}, BufReader={:.3}, read+slice={:.3}; slice speedup={:.2}x",
+        fs::metadata(path)?.len(),
+        median[0],
+        median[1],
+        median[2],
+        median[0] / median[2]
+    );
+    Ok(())
+}
+
+fn main() -> Result<()> {
+    let args: Vec<_> = std::env::args().skip(1).collect();
+    let fixture = if args.is_empty() {
+        Some(Fixture::new()?)
+    } else {
+        None
+    };
+    let root = fixture
+        .as_ref()
+        .map(|f| f.0.clone())
+        .unwrap_or_else(|| PathBuf::from(&args[0]));
+    if fixture.is_some() {
+        fixtures(&root)?;
+        println!(
+            "Generated representative fixtures: 1024 blocks, 57344 model states; warm filesystem cache."
+        );
+    }
+    let repetitions = args.get(1).map(|s| s.parse()).transpose()?.unwrap_or(9);
+    assert!(repetitions > 0, "repetitions must be positive");
+    benchmark(
+        "prepare model states",
+        &root.join("model-states.json"),
+        repetitions,
+        prepare_facts,
+    )?;
+    benchmark(
+        "catalog model states",
+        &root.join("model-states.json"),
+        repetitions,
+        catalog_facts,
+    )?;
+    benchmark(
+        "render definitions",
+        &root.join("render-definitions.json"),
+        repetitions,
+        catalog_facts,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn reader_equivalence_and_errors() -> Result<()> {
+        let fixture = Fixture::new()?;
+        let path = fixture.0.join("test.json");
+        fs::write(&path, br#"{"minecraft:stone":{"schema":{},"states":[{}]},"unicode":"\u2603","duplicate":1,"duplicate":2}"#)?;
+        let expected = prepare_facts(&path, Reader::File)?;
+        for reader in READERS {
+            assert_eq!(expected, prepare_facts(&path, reader)?);
+            assert_eq!(
+                expected.iter().collect::<BTreeMap<_, _>>(),
+                catalog_facts(&path, reader)?.iter().collect()
+            );
+        }
+        for invalid in [b"{\"a\": ".as_slice(), b"{} trailing", b"{\"a\":\"\xff\"}"] {
+            fs::write(&path, invalid)?;
+            for reader in READERS {
+                let error = prepare_facts(&path, reader).unwrap_err();
+                assert!(error.downcast_ref::<serde_json::Error>().is_some());
+                assert!(catalog_facts(&path, reader).is_err());
+            }
+        }
+        fs::remove_file(&path)?;
+        for reader in READERS {
+            let error = prepare_facts(&path, reader).unwrap_err();
+            assert_eq!(
+                error.downcast_ref::<std::io::Error>().unwrap().kind(),
+                std::io::ErrorKind::NotFound
+            );
+        }
+        Ok(())
+    }
+}
@@ -9,7 +9,7 @@ use horizon_client::{
    biome::Biomes,
    blocks::BlockFacts,
    chunk::{Chunk, MIN_Y, SECTIONS, index},
-    light::{LightTables, light_chunk},
+    light::{LightTables, apply_lighting, light_chunk},
    save,
 };
 use horizon_core::position::ChunkPos;
@@ -101,7 +101,7 @@ fn main() -> horizon_client::Result<()> {
                .unwrap_or((None, None));
            let nib = |a: &Option<Vec<u8>>| a.as_ref().map(|a| (a[i >> 1] >> ((i & 1) * 4)) & 15);
            let id = chunks[&(x, z)].get(wx & 15, wy, wz & 15);
-            let packed = lit[si].light(i);
+            let packed = lit[si].get(i);
            println!(
                "{wy}: {} horizon sky {} block {} vanilla sky {:?} block {:?}",
                facts.states[id as usize].name,
@@ -157,7 +157,7 @@ fn main() -> horizon_client::Result<()> {
                        .map_or(15, |a| (a[(i & 255) >> 1] >> ((i & 1) * 4)) & 15),
                };
                let vb = nibble(&block, 0);
-                let packed = section.light(i);
+                let packed = section.get(i);
                let (hs, hb) = (packed >> 4, packed & 15);
                total += 1;
                if hs != vs {
@@ -228,7 +228,7 @@ fn incremental(
            std::array::from_fn(|dx| chunks.get(&(x + dx as i32 - 1, z + dz as i32 - 1)))
        });
        let mut c = chunks[&(x, z)].clone();
-        c.sections = light_chunk(&region, tables, sky_light);
+        apply_lighting(&mut c, light_chunk(&region, tables, sky_light));
        c.lit = true;
        world.insert((x, z), Arc::new(c));
    }
@@ -299,7 +299,7 @@ fn incremental(
                let full = light_chunk(&region, tables, sky_light);
                for (si, s) in full.iter().enumerate() {
                    for i in 0..4096 {
-                        let (a, b) = (s.light(i), world[&(kx, kz)].sections[si].light(i));
+                        let (a, b) = (s.get(i), world[&(kx, kz)].sections[si].light(i));
                        if a != b {
                            bad += 1;
                            if bad < 20 {
@@ -1,9 +1,11 @@
 //! Menu clicks for tools/test_menu_click_parity.py: reads one JSON case per
 //! line (menu, creative, slots, carried, data, ops) and prints the oracle's
-//! state lines after every click.
+//! state lines after every click. The `*_be` furnace menus run over a furnace
+//! block entity: its data slots follow `Furnace::input_clicked`.
 //!
 //! usage: menu_fixture RESOURCES INPUT OUTPUT
 use horizon_client::{
+    containers::{Furnace, FurnaceKind},
    crafting::Recipes,
    item_data::{canon_stack, parse_stack},
    items::Items,
@@ -41,11 +43,25 @@ fn main() -> horizon_client::Result<()> {
        recipes: &recipes,
        brewing: &brewing,
        banners: &banners,
+        trade: None,
    };
    let mut out = String::new();
    for line in input.lines() {
        let case: Value = serde_json::from_str(line)?;
-        let kind = Kind::parse(case["menu"].as_str().unwrap_or_default()).ok_or("menu kind")?;
+        let name = case["menu"].as_str().unwrap_or_default();
+        // FurnaceMenu over the server's AbstractFurnaceBlockEntity.
+        let furnace_kind = match name {
+            "furnace_be" => Some(FurnaceKind::Furnace),
+            "blast_furnace_be" => Some(FurnaceKind::BlastFurnace),
+            "smoker_be" => Some(FurnaceKind::Smoker),
+            _ => None,
+        };
+        let kind = Kind::parse(
+            name.strip_suffix("_be")
+                .filter(|_| furnace_kind.is_some())
+                .unwrap_or(name),
+        )
+        .ok_or("menu kind")?;
        let mut menu = Menu::new(kind);
        menu.creative = case["creative"].as_bool().unwrap_or(false);
        for (i, slot) in case["slots"].as_array().ok_or("slots")?.iter().enumerate() {
@@ -56,6 +72,15 @@ fn main() -> horizon_client::Result<()> {
        for (i, v) in case["data"].as_array().ok_or("data")?.iter().enumerate() {
            menu.data[i] = v.as_i64().unwrap_or(0) as i32;
        }
+        let mut furnace = furnace_kind.map(|kind| Furnace {
+            kind,
+            items: [0, 1, 2].map(|i| menu.slot(i).cloned()),
+            lit_remaining: menu.data[0],
+            lit_total: menu.data[1],
+            cooking_timer: menu.data[2],
+            cooking_total: menu.data[3],
+            speed: 1.0,
+        });
        menu.drops.clear();
        out += &format!("init {}\n", state(&menu));
        for op in case["ops"].as_array().ok_or("ops")? {
@@ -79,7 +104,15 @@ fn main() -> horizon_client::Result<()> {
                _ => {}
            }
            let kind = Input::parse(op[2].as_str().unwrap_or_default()).ok_or("input")?;
-            match menu.click(&env, slot, button, kind) {
+            let clicked = menu.click(&env, slot, button, kind);
+            if let Some(f) = furnace.as_mut() {
+                let before = f.items[0].clone();
+                f.items = [0, 1, 2].map(|i| menu.slot(i).cloned());
+                f.input_clicked(&recipes, before);
+                menu.data[2] = f.cooking_timer;
+                menu.data[3] = f.cooking_total;
+            }
+            match clicked {
                Ok(()) => out += &format!("{}\n", state(&menu)),
                Err(name) => out += &format!("error {name}\n"),
            }
@@ -0,0 +1,54 @@
+//! Horizon's sprite mip levels for tools/test_mipmap_parity.py: each sprite
+//! loads through `sprites::Sprites` (its .mcmeta settings and transparency)
+//! and `mipmap::generate` makes its levels down to 1x1, printed as RGBA hex
+//! rows like VanillaMipmapOracle.
+use std::{fmt::Write as _, fs, path::Path};
+
+fn main() -> horizon_client::Result<()> {
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    let input = fs::read_to_string(&args[0])?;
+    let mut lines = input.lines();
+    let root = Path::new(lines.next().ok_or("no resources root")?);
+    let names: Vec<&str> = lines.collect();
+    let mut sprites = horizon_client::sprites::Sprites::default();
+    let layers = names
+        .iter()
+        .map(|name| sprites.insert(root, name))
+        .collect::<horizon_client::Result<Vec<u32>>>()?;
+    sprites.finish();
+    let size = sprites.size;
+    let bytes = (size * size * 4) as usize;
+    let mut out = String::new();
+    for (name, layer) in names.iter().zip(layers) {
+        let start = layer as usize * bytes;
+        let base = horizon_client::mipmap::Image {
+            width: size,
+            height: size,
+            pixels: sprites.pixels[start..start + bytes]
+                .as_chunks::<4>()
+                .0
+                .to_vec(),
+        };
+        let s = sprites.mips[layer as usize];
+        writeln!(out, "== {name}")?;
+        for mip in horizon_client::mipmap::generate(
+            base,
+            size.trailing_zeros(),
+            s.strategy,
+            s.alpha_cutoff_bias,
+            s.has_transparent,
+            s.item,
+        ) {
+            write!(out, "{}x{}", mip.width, mip.height)?;
+            for row in mip.pixels.chunks(mip.width as usize) {
+                out.push(' ');
+                for p in row {
+                    write!(out, "{:02x}{:02x}{:02x}{:02x}", p[0], p[1], p[2], p[3])?;
+                }
+            }
+            out.push('\n');
+        }
+    }
+    fs::write(&args[1], out)?;
+    Ok(())
+}
@@ -5,13 +5,14 @@
 //! usage: mob_ai_probe RESOURCES SCENARIOS OUTPUT
 use horizon_client::{
    assets::Assets,
+    beehive::HiveHost,
    biome::Biomes,
    blocks::BlockFacts,
    chunk::{Chunk, HEIGHT, MIN_Y},
    collisions,
    containers::{BlockEntity, CreakingHeart},
    items::{ItemStack, Items},
-    light::{LightTables, light_chunk},
+    light::{LightTables, apply_lighting, light_chunk},
    mobs::{
        Damage, MobType, creaking,
        creaking_heart::{self, HeartEvent, HeartHost},
@@ -27,7 +28,13 @@ use horizon_core::{
    random::LegacyRandom,
 };
 use horizon_world::{chunk::BlockState, registry::BlockRegistry, registry::BlockStateId};
-use std::{collections::BTreeMap, fmt::Write as _, fs, path::Path, sync::Arc};
+use std::{
+    collections::{BTreeMap, HashMap},
+    fmt::Write as _,
+    fs,
+    path::Path,
+    sync::Arc,
+};

 struct MobSpec {
    kind: String,
@@ -54,8 +61,13 @@ struct Scenario {
    hearts: Vec<Vec<String>>,
    /// `ServerLevel.isSpawningMonsters`.
    spawning: bool,
+    /// The day time moves on with every tick.
+    daycycle: bool,
    /// The player hits a mob for 1 at the start of a tick: (tick, mob index).
    hurts: Vec<(i32, usize)>,
+    /// The player feeds an animal at the start of a tick (Animal.mobInteract):
+    /// (tick, mob index); the scenario only feeds each animal its food.
+    feeds: Vec<(i32, usize)>,
    hand: Option<String>,
    mobs: Vec<MobSpec>,
 }
@@ -82,6 +94,7 @@ fn parse(text: &str) -> Vec<Scenario> {
                        "thunder" => s.thunder = true,
                        "levelseed" => {}
                        "spawning" => s.spawning = true,
+                        "daycycle" => s.daycycle = true,
                        _ => panic!("unknown scenario option {kv}"),
                    }
                }
@@ -92,6 +105,7 @@ fn parse(text: &str) -> Vec<Scenario> {
            }
            "heart" => s.hearts.push(f.iter().map(|x| (*x).to_owned()).collect()),
            "hurt" => s.hurts.push((f[1].parse().unwrap(), f[2].parse().unwrap())),
+            "feed" => s.feeds.push((f[1].parse().unwrap(), f[2].parse().unwrap())),
            "player" => {
                s.player = Some([
                    f[1].parse().unwrap(),
@@ -403,6 +417,65 @@ impl HeartHost for Host<'_> {
        self.spawning
    }
 }
+/// A scenario's beehives as `BeehiveBlockEntity.serverTick` sees the level:
+/// the bees let out are newcomers seeded as the oracle seeds them.
+struct ProbeHive<'a, 'w> {
+    w: &'a MobWorld<'w>,
+    random: &'a mut LegacyRandom,
+    types: &'a HashMap<String, Arc<MobType>>,
+    /// The index of the first newcomer of this tick.
+    first: usize,
+    added: &'a mut Vec<Mob>,
+    honey: &'a mut Vec<([i32; 3], i32)>,
+    events: &'a mut Vec<MobEvent>,
+}
+impl HiveHost for ProbeHive<'_, '_> {
+    fn random(&mut self) -> &mut LegacyRandom {
+        self.random
+    }
+    fn bees_stay_in_hive(&self, _at: [i32; 3]) -> bool {
+        horizon_client::mobs::bee::bees_stay_in_hive(self.w)
+    }
+    fn blocked(&self, at: [i32; 3]) -> bool {
+        !self.w.block_collision_boxes(at[0], at[1], at[2]).is_empty()
+    }
+    fn set_honey_level(&mut self, at: [i32; 3], level: i32) {
+        self.honey.push((at, level));
+    }
+    fn load(&mut self, tag: &horizon_world::nbt::Tag) -> Option<Mob> {
+        let index = self.first + self.added.len();
+        let mut m =
+            horizon_client::entity_nbt::mob_from_nbt(tag, self.types, 100_000 + index as u32)?;
+        if m.species() != Species::Bee {
+            return None;
+        }
+        m.random = LegacyRandom::new(spawn_seed(index));
+        horizon_client::mobs::bee::draw_cooldowns(&mut m);
+        Some(m)
+    }
+    fn add(&mut self, m: Mob) -> bool {
+        self.added.push(m);
+        true
+    }
+    fn sound(&mut self, name: &'static str, at: [f64; 3]) {
+        self.events.push(MobEvent::Sound(name, at, 1.0, 1.0));
+    }
+}
+/// The hive's honey level and front from its block state.
+fn hive_state(registry: &BlockRegistry, world: &World, at: [i32; 3]) -> (Option<i32>, [i32; 2]) {
+    let props = registry
+        .state(world.block(at[0], at[1], at[2]))
+        .map(|s| s.properties.clone())
+        .unwrap_or_default();
+    let honey = props.get("honey_level").and_then(|v| v.parse().ok());
+    let facing = horizon_client::beehive::facing_step(props.get("facing").map(String::as_str));
+    (honey, facing)
+}
+fn is_hive(b: &[String]) -> bool {
+    b[0] == "block"
+        && (b[4].starts_with("minecraft:beehive") || b[4].starts_with("minecraft:bee_nest"))
+}
+
 /// The heart's state, block entity and the level random, as the oracle
 /// prints them.
 fn print_heart(
@@ -466,7 +539,7 @@ fn player_hurt(player: Option<&PlayerView>, e: &MobEvent) -> bool {

 /// `player_down`: the scenario's player is no valid target (creative, or
 /// killed this tick).
-fn print(out: &mut String, t: i32, i: usize, m: &Mob, player_down: bool) {
+fn print(out: &mut String, t: i32, i: usize, m: &Mob, player_down: bool, now: i64) {
    let _ = write!(out, "{t} {i}");
    if m.removed {
        // Entity.RemovalReason: the end of the death animation, else a discard.
@@ -585,6 +658,21 @@ fn print(out: &mut String, t: i32, i: usize, m: &Mob, player_down: bool) {
            .map_or("-".into(), |p| format!("{},{},{}", p[0], p[1], p[2]));
        let _ = write!(out, "\tcg {} {held} {opened}", m.extra.variant3);
    }
+    if let Some(b) = horizon_client::mobs::bee::get(m) {
+        let anger = if b.anger_end > 0 {
+            b.anger_end - now
+        } else {
+            -1
+        };
+        let flower = b
+            .flower
+            .map_or("-".into(), |p| format!("{},{},{}", p[0], p[1], p[2]));
+        let _ = write!(
+            out,
+            "\tbee {} {anger} {} {} {flower}",
+            b.flags, b.ticks_without_nectar, b.flower_cooldown
+        );
+    }
    out.push('\n');
 }

@@ -680,8 +768,15 @@ fn main() -> horizon_client::Result<()> {
    let assets = Assets::load(root)?;
    let registry = assets.registry;
    let facts = BlockFacts::load(root, registry)?;
+    let motion = horizon_client::motion::MotionResources::load(root, &assets)?;
    let data = MobData::load(root, &facts);
    let types = MobTypes::load(root)?;
+    // The types a bee leaving its hive is loaded with (EntityType.loadEntityRecursive).
+    let arc_types: HashMap<String, Arc<MobType>> = types
+        .types
+        .iter()
+        .map(|(k, v)| (k.clone(), Arc::new(v.clone())))
+        .collect();
    let biomes = Biomes::load(root)?;
    let items = Items::load(root, registry, &facts)?;
    let tables = LightTables::load(root, registry, &facts)?;
@@ -724,6 +819,11 @@ fn main() -> horizon_client::Result<()> {
            let n = |i: usize| b[i].parse::<i32>().unwrap();
            if b[0] == "block" || b[0] == "chest" {
                world.set(n(1), n(2), n(3), state(registry, &b[4]))?;
+                if is_hive(b) {
+                    world
+                        .block_entities
+                        .insert((n(1), n(2), n(3)), BlockEntity::Beehive(Box::default()));
+                }
                if b[0] == "chest" {
                    // chest X Y Z STATE SLOTS: item*count or - per slot.
                    let mut slots = vec![None; 27];
@@ -774,7 +874,7 @@ fn main() -> horizon_client::Result<()> {
                    })
                });
                let mut c = (*world.chunks[&(x, z)]).clone();
-                c.sections = light_chunk(&region, &tables, true);
+                apply_lighting(&mut c, light_chunk(&region, &tables, true));
                c.lit = true;
                ((x, z), c)
            })
@@ -810,6 +910,7 @@ fn main() -> horizon_client::Result<()> {
                        &mut Vec::new(),
                    ),
                    "inlove" => m.extra.in_love = 600,
+                    "nectar" => horizon_client::mobs::bee::set_has_nectar(&mut m, true),
                    "tame" => m.extra.tame = true,
                    x if x.starts_with("age=") => m.extra.age = x[4..].parse().unwrap(),
                    x if x.starts_with("strength=") => m.extra.variant2 = x[9..].parse().unwrap(),
@@ -830,6 +931,10 @@ fn main() -> horizon_client::Result<()> {
                }
            }
            m.random = LegacyRandom::new(spec.seed);
+            if m.species() == Species::Bee {
+                // The oracle draws the constructor's cooldowns again once seeded.
+                horizon_client::mobs::bee::draw_cooldowns(&mut m);
+            }
            if horizon_client::mobs::monster_brain::has_brain(m.species()) {
                // The oracle delays the sensors again with the seeded random
                // and seeds RunOne's shuffles with the mob's seed.
@@ -893,8 +998,11 @@ fn main() -> horizon_client::Result<()> {
            }
        });
        let mut scratch = LegacyRandom::new(0);
+        // The level's random for eating sounds: only goats and sniffers draw
+        // from it, and the scenarios feed neither.
+        let mut level_random = LegacyRandom::new(0);
        for (i, m) in mobs.iter().enumerate() {
-            print(&mut out, 0, i, m, s.creative);
+            print(&mut out, 0, i, m, s.creative, world.game_time);
        }
        // The MobWorld every step sees, over a snapshot of the mobs.
        macro_rules! mob_world {
@@ -904,11 +1012,12 @@ fn main() -> horizon_client::Result<()> {
                    world: &world,
                    registry,
                    facts: &facts,
+                    movement: &motion.blocks,
                    collision: &collision,
                    data: &data,
                    player: player.clone(),
                    others: $snapshot,
-                    daylight: (s.time.rem_euclid(24000)) < 12000,
+                    daylight: (world.day_time.rem_euclid(24000)) < 12000,
                    game_time: world.game_time,
                    day_time: world.day_time,
                    raining: s.rain,
@@ -928,6 +1037,9 @@ fn main() -> horizon_client::Result<()> {
        }
        for t in 1..=s.ticks {
            world.game_time += 1;
+            if s.daycycle {
+                world.day_time = s.time + i64::from(t);
+            }
            let mut heart_events_later: Vec<HeartEvent> = Vec::new();
            // Creaking.tick reads the heart's block entity.
            for (at, h) in &hearts {
@@ -996,6 +1108,16 @@ fn main() -> horizon_client::Result<()> {
                }
                events.append(&mut mobs[i].outbox);
            }
+            for &(tick, i) in &s.feeds {
+                if tick != t || i >= mobs.len() || mobs[i].removed {
+                    continue;
+                }
+                if let Some(Some((name, volume, pitch))) =
+                    horizon_client::mobs::ai::feed_animal(&mut mobs[i], &mut level_random)
+                {
+                    events.push(MobEvent::Sound(name, [0.0; 3], volume, pitch));
+                }
+            }
            #[allow(unused_mut)] // filled only with the rng-trace feature
            let mut traces: Vec<String> = Vec::new();
            let mut pushes = Vec::new();
@@ -1083,6 +1205,41 @@ fn main() -> horizon_client::Result<()> {
                        _ => {}
                    }
                }
+                // BeeEnterHiveGoal.start: BeehiveBlockEntity.addOccupant.
+                let entering: Vec<[i32; 3]> = events[from.min(events.len())..]
+                    .iter()
+                    .filter_map(|e| match e {
+                        MobEvent::EnterHive { hive, .. } => Some(*hive),
+                        _ => None,
+                    })
+                    .collect();
+                for at in entering {
+                    let key = (at[0], at[1], at[2]);
+                    let Some(BlockEntity::Beehive(mut hive)) = world.block_entities.remove(&key)
+                    else {
+                        continue;
+                    };
+                    let tag = horizon_client::entity_nbt::mob_to_nbt(&mobs[i], [0; 4], None);
+                    let flower = horizon_client::mobs::bee::get(&mobs[i]).and_then(|b| b.flower);
+                    let mut honey = Vec::new();
+                    let stored = {
+                        let w = mob_world!(&snapshot);
+                        let mut host = ProbeHive {
+                            w: &w,
+                            random: &mut scratch,
+                            types: &arc_types,
+                            first: 0,
+                            added: &mut Vec::new(),
+                            honey: &mut honey,
+                            events: &mut events,
+                        };
+                        hive.add_occupant(at, tag, flower, &mut host)
+                    };
+                    world.block_entities.insert(key, BlockEntity::Beehive(hive));
+                    if stored {
+                        mobs[i].removed = true;
+                    }
+                }
                // ServerLevel ticks entities one after another: the ones
                // after this mob see it as it is now.
                if let Some(e) = snapshot.iter_mut().find(|e| e.id == mobs[i].id) {
@@ -1115,6 +1272,43 @@ fn main() -> horizon_client::Result<()> {
                added.append(&mut host.added);
            }
            drop(w);
+            // Then the hives (BeehiveBlockEntity.serverTick).
+            let mut hive_keys: Vec<(i32, i32, i32)> = world
+                .block_entities
+                .iter()
+                .filter(|(_, e)| matches!(e, BlockEntity::Beehive(_)))
+                .map(|(k, _)| *k)
+                .collect();
+            hive_keys.sort_unstable();
+            let mut honey = Vec::new();
+            for key in hive_keys {
+                let at = [key.0, key.1, key.2];
+                let (level, facing) = hive_state(registry, &world, at);
+                let Some(BlockEntity::Beehive(mut hive)) = world.block_entities.remove(&key) else {
+                    continue;
+                };
+                {
+                    let w = mob_world!(&snapshot);
+                    let mut host = ProbeHive {
+                        w: &w,
+                        random: &mut scratch,
+                        types: &arc_types,
+                        first: mobs.len() + born.len(),
+                        added: &mut added,
+                        honey: &mut honey,
+                        events: &mut events,
+                    };
+                    hive.server_tick(at, facing, level, &mut host);
+                }
+                world.block_entities.insert(key, BlockEntity::Beehive(hive));
+            }
+            for (at, level) in honey {
+                if let Some(mut st) = registry.state(world.block(at[0], at[1], at[2])).cloned() {
+                    st.properties
+                        .insert("honey_level".to_owned(), level.to_string());
+                    world.set(at[0], at[1], at[2], registry.resolve(&st)?)?;
+                }
+            }
            mobs.append(&mut born);
            mobs.append(&mut added);
            for e in &heart_events {
@@ -1133,7 +1327,14 @@ fn main() -> horizon_client::Result<()> {
                .iter()
                .any(|e| player_hurt(player.as_ref(), e) && player_damage(e) >= 20.0);
            for (i, m) in mobs.iter().enumerate() {
-                print(&mut out, t, i, m, s.creative || player_killed);
+                print(
+                    &mut out,
+                    t,
+                    i,
+                    m,
+                    s.creative || player_killed,
+                    world.game_time,
+                );
            }
            for e in &events {
                if let MobEvent::Sound(name, _, volume, pitch) = e {
@@ -1190,6 +1391,35 @@ fn main() -> horizon_client::Result<()> {
                    }
                );
            }
+            for b in s.blocks.iter().filter(|b| is_hive(b)) {
+                let n = |i: usize| b[i].parse::<i32>().unwrap();
+                let Some(BlockEntity::Beehive(hive)) =
+                    world.block_entities.get(&(n(1), n(2), n(3)))
+                else {
+                    continue;
+                };
+                let (level, _) = hive_state(registry, &world, [n(1), n(2), n(3)]);
+                let bees: Vec<String> = hive
+                    .bees
+                    .iter()
+                    .map(|b| format!("{}/{}", b.ticks_in_hive, b.min_ticks_in_hive))
+                    .collect();
+                let _ = writeln!(
+                    out,
+                    "{t} hive {},{},{} honey {} bees {} flower {}",
+                    b[1],
+                    b[2],
+                    b[3],
+                    level.unwrap_or(-1),
+                    if bees.is_empty() {
+                        "-".into()
+                    } else {
+                        bees.join(",")
+                    },
+                    hive.flower
+                        .map_or("-".into(), |f| format!("{},{},{}", f[0], f[1], f[2]))
+                );
+            }
            for line in traces {
                let _ = writeln!(out, "{line}");
            }
@@ -0,0 +1,291 @@
+//! Compare the old two-parse loading path with catalog construction from shared facts.
+//! Run: cargo run -p horizon-client --profile fast --example model_states_bench -- 15
+use horizon_client::{Result, models::StateModels, sprites::Sprites};
+use horizon_core::position::BlockPos;
+use horizon_world::{
+    DATA_VERSION,
+    chunk::BlockState,
+    nbt::Tag,
+    registry::{BlockRegistry, BlockStateId},
+};
+use serde_json::{Value, json};
+use std::{collections::BTreeMap, fs, hint::black_box, path::PathBuf, time::Instant};
+
+struct Fixture {
+    root: PathBuf,
+    registry: BlockRegistry,
+    bytes: usize,
+    blocks: usize,
+}
+impl Fixture {
+    fn new(target_bytes: usize) -> Result<Self> {
+        let root =
+            std::env::temp_dir().join(format!("horizon-model-states-{}", std::process::id()));
+        fs::create_dir_all(root.join("assets/minecraft/blockstates"))?;
+        fs::create_dir_all(root.join("assets/minecraft/models/block"))?;
+        let mut possible = Vec::new();
+        for age in 0..8 {
+            for facing in ["north", "south", "east", "west"] {
+                for waterlogged in ["false", "true"] {
+                    possible.push(
+                        json!({"age":age.to_string(), "facing":facing, "waterlogged":waterlogged}),
+                    );
+                }
+            }
+        }
+        let fact = json!({"schema":{
+            "age":{"integer":[0,7]},
+            "facing":{"named":["north","south","east","west"]},
+            "waterlogged":{"named":["false","true"]}
+        },"states":possible});
+        let blocks = (target_bytes / (serde_json::to_vec(&fact)?.len() + 26)).max(1);
+        let mut facts = BTreeMap::new();
+        let mut states = Vec::new();
+        let mut defaults = BTreeMap::new();
+        for i in 0..blocks {
+            let block = format!("fixture_{i:04}");
+            let name = format!("minecraft:{block}");
+            defaults.insert(name.as_str().into(), Tag::Int(states.len() as i32));
+            for properties in &possible {
+                let state = BlockState {
+                    name: name.clone(),
+                    properties: serde_json::from_value(properties.clone())?,
+                };
+                states.push(state.to_nbt());
+            }
+            facts.insert(name, fact.clone());
+            fs::write(
+                root.join(format!("assets/minecraft/blockstates/{block}.json")),
+                r#"{"multipart":[{"apply":[{"model":"minecraft:block/fixture","weight":2},{"model":"minecraft:block/fixture","y":90,"weight":1}]},{"when":{"waterlogged":"true"},"apply":{"model":"minecraft:block/fixture","y":180,"uvlock":true}}]}"#,
+            )?;
+        }
+        fs::write(
+            root.join("assets/minecraft/models/block/fixture.json"),
+            r##"{"textures":{"all":"minecraft:block/fixture"},"elements":[{"from":[0,0,0],"to":[16,16,16],"faces":{"north":{"texture":"#all","cullface":"north"}}}]}"##,
+        )?;
+        let document = serde_json::to_vec(&facts)?;
+        let bytes = document.len();
+        fs::write(root.join("model-states.json"), document)?;
+        let registry = BlockRegistry::from_nbt(&Tag::compound([
+            ("DataVersion", Tag::Int(DATA_VERSION)),
+            ("states", Tag::List(states)),
+            ("defaults", Tag::Compound(defaults)),
+        ]))?;
+        Ok(Self {
+            root,
+            registry,
+            bytes,
+            blocks,
+        })
+    }
+    fn facts(&self) -> Result<BTreeMap<String, Value>> {
+        Ok(serde_json::from_slice(&fs::read(
+            self.root.join("model-states.json"),
+        )?)?)
+    }
+    fn block_names<'a>(&self, names: impl Iterator<Item = &'a String>) -> Vec<&'a str> {
+        names
+            .filter(|name| self.registry.default_state(name).is_some())
+            .filter_map(|name| name.strip_prefix("minecraft:"))
+            .collect()
+    }
+    fn load(&self, reuse: bool) -> Result<(StateModels, Sprites)> {
+        // The first parse and block filtering match models::prepare in both paths.
+        let mut sprites = Sprites::default();
+        let catalog = if reuse {
+            let facts = self.facts()?;
+            let blocks = self.block_names(facts.keys());
+            StateModels::from_facts(&self.root, &self.registry, &blocks, &mut sprites, &facts)?
+        } else {
+            let facts: serde_json::Map<String, Value> =
+                serde_json::from_slice(&fs::read(self.root.join("model-states.json"))?)?;
+            let blocks = self.block_names(facts.keys());
+            StateModels::load(&self.root, &self.registry, &blocks, &mut sprites)?
+        };
+        Ok((catalog, sprites))
+    }
+    fn verify(&self) -> Result<()> {
+        let (before, before_sprites) = self.load(false)?;
+        let (after, after_sprites) = self.load(true)?;
+        assert_eq!(before_sprites.layers, after_sprites.layers);
+        assert_eq!(before_sprites.opaque, after_sprites.opaque);
+        assert_eq!(before_sprites.translucent, after_sprites.translucent);
+        for id in 0..self.registry.len() {
+            for position in [
+                BlockPos::new(0, 0, 0),
+                BlockPos::new(12, -4, 7),
+                BlockPos::new(42, 9, -19),
+            ] {
+                let a = before.collect(BlockStateId(id as u32), position)?;
+                let b = after.collect(BlockStateId(id as u32), position)?;
+                assert_eq!(a.len(), b.len());
+                for ((av, am), (bv, bm)) in a.into_iter().zip(b) {
+                    assert_eq!(av, bv);
+                    assert_eq!(am.ambient_occlusion, bm.ambient_occlusion);
+                    assert_eq!(am.cube, bm.cube);
+                    assert_eq!(am.faces.len(), bm.faces.len());
+                    for (af, bf) in am.faces.iter().zip(&bm.faces) {
+                        assert_eq!(af.quad, bf.quad);
+                        assert_eq!(
+                            (af.layer, af.opaque, af.translucent),
+                            (bf.layer, bf.opaque, bf.translucent)
+                        );
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+}
+impl Drop for Fixture {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.root);
+    }
+}
+fn median(values: &mut [f64]) -> f64 {
+    values.sort_by(f64::total_cmp);
+    values[values.len() / 2]
+}
+fn main() -> Result<()> {
+    let repetitions: usize = std::env::args()
+        .nth(1)
+        .map(|s| s.parse())
+        .transpose()?
+        .unwrap_or(15);
+    if repetitions == 0 {
+        return Err("repetitions must be positive".into());
+    }
+    let fixture = Fixture::new(2_840_000)?;
+    fixture.verify()?;
+    for _ in 0..2 {
+        for reuse in [false, true] {
+            drop(black_box(fixture.load(reuse)?));
+        }
+    }
+    let mut before = Vec::new();
+    let mut after = Vec::new();
+    for iteration in 0..repetitions {
+        // Alternate order to limit cache/order bias. Both paths use slice parsing.
+        for reuse in if iteration % 2 == 0 {
+            [false, true]
+        } else {
+            [true, false]
+        } {
+            let started = Instant::now();
+            drop(black_box(fixture.load(black_box(reuse))?));
+            let ms = started.elapsed().as_secs_f64() * 1000.0;
+            if reuse {
+                after.push(ms);
+            } else {
+                before.push(ms);
+            }
+        }
+    }
+    let before = median(&mut before);
+    let after = median(&mut after);
+    println!(
+        "fixture: {} bytes, {} blocks, {} states; equality: all states at 3 positions",
+        fixture.bytes,
+        fixture.blocks,
+        fixture.registry.len()
+    );
+    println!(
+        "2 warmups/path, {repetitions} samples/path; median before {before:.3} ms, after {after:.3} ms; {:.3}x speedup ({:.2}% less time)",
+        before / after,
+        (1.0 - after / before) * 100.0
+    );
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn shared_facts_match_load_and_preserve_errors() -> Result<()> {
+        let fixture = Fixture::new(1)?;
+        fixture.verify()?;
+        let mut facts = fixture.facts()?;
+        let blocks = ["fixture_0000"];
+        let load_error = |facts: &BTreeMap<String, Value>| -> Result<String> {
+            fs::write(
+                fixture.root.join("model-states.json"),
+                serde_json::to_vec(facts)?,
+            )?;
+            let a = StateModels::load(
+                &fixture.root,
+                &fixture.registry,
+                &blocks,
+                &mut Sprites::default(),
+            )
+            .err()
+            .ok_or("expected load error")?
+            .to_string();
+            let b = StateModels::from_facts(
+                &fixture.root,
+                &fixture.registry,
+                &blocks,
+                &mut Sprites::default(),
+                facts,
+            )
+            .err()
+            .ok_or("expected shared facts error")?
+            .to_string();
+            assert_eq!(a, b);
+            Ok(a)
+        };
+        let good = facts.clone();
+        facts.clear();
+        assert_eq!(load_error(&facts)?, "missing block model state schema");
+        facts = good.clone();
+        facts.get_mut("minecraft:fixture_0000").unwrap()["schema"] = Value::Null;
+        assert_eq!(load_error(&facts)?, "invalid model schema");
+        facts = good.clone();
+        facts.get_mut("minecraft:fixture_0000").unwrap()["states"]
+            .as_array_mut()
+            .unwrap()
+            .reverse();
+        assert_eq!(
+            load_error(&facts)?,
+            "model state definitions disagree with the imported block registry"
+        );
+        fs::remove_file(fixture.root.join("model-states.json"))?;
+        // A parsed document remains usable without reopening its source file.
+        StateModels::from_facts(
+            &fixture.root,
+            &fixture.registry,
+            &blocks,
+            &mut Sprites::default(),
+            &good,
+        )?;
+        assert!(
+            StateModels::load(
+                &fixture.root,
+                &fixture.registry,
+                &blocks,
+                &mut Sprites::default()
+            )
+            .is_err()
+        );
+        fs::write(fixture.root.join("model-states.json"), b"null")?;
+        assert!(
+            StateModels::load(
+                &fixture.root,
+                &fixture.registry,
+                &blocks,
+                &mut Sprites::default()
+            )
+            .is_err()
+        );
+        fs::write(fixture.root.join("model-states.json"), b"{")?;
+        assert!(
+            StateModels::load(
+                &fixture.root,
+                &fixture.registry,
+                &blocks,
+                &mut Sprites::default()
+            )
+            .is_err()
+        );
+        Ok(())
+    }
+}
@@ -9,6 +9,14 @@
 //! 1.0), foxes and axolotls from the third, sulfur cubes have size 2, salmon
 //! are small, slimes and magma cubes keep size 1, tropical fish school.
 //!
+//! Spawner cases (`mode=spawner`, tools/test_spawner_parity.py) tick a
+//! `mobs::spawner::Spawner` loaded from the case's SNBT on the same world and
+//! print its events tick by tick.
+//!
+//! Trial spawner cases (`mode=trial`, tools/test_trial_spawner_parity.py) tick
+//! a `mobs::trial_spawner::TrialSpawner` with the game time advancing and
+//! print its states, events, spawns and ejected items.
+//!
 //! usage: natural_spawn_fixture RESOURCES INPUT OUTPUT
 use horizon_client::{
    assets::Assets,
@@ -25,7 +33,9 @@ use horizon_client::{
            SpawnPlayer, SpawnRequest, SpawnState, Spawned, StructureAt, StructureSpawns,
            spawn_box,
        },
+        spawner::{Spawner, SpawnerAdded, SpawnerEvent, SpawnerLevel, SpawnerSpawn},
        species::{self, Baby},
+        trial_spawner::{TrialEvent, TrialPlayer, TrialSpawner, TrialSpawnerLevel, TrialState},
    },
 };
 use horizon_core::{
@@ -33,11 +43,11 @@ use horizon_core::{
    random::{LegacyRandom, RandomSource},
 };
 use horizon_world::{
-    block_collision::BlockCollisionRegistry, chunk::BlockState, registry::BlockStateId,
+    block_collision::BlockCollisionRegistry, chunk::BlockState, nbt::Tag, registry::BlockStateId,
 };
 use serde_json::Value;
 use std::{
-    cell::RefCell,
+    cell::{Cell, RefCell},
    collections::{BTreeMap, HashMap, HashSet},
    fmt::Write as _,
    fs,
@@ -73,6 +83,8 @@ struct Shared<'a> {
    structures: &'a StructureSpawns,
    collision: &'a BlockCollisionRegistry<'a>,
    air: BlockStateId,
+    /// Every entity type id (`entity-types.json`).
+    entity_types: &'a HashSet<String>,
 }
 struct World<'a> {
    s: &'a Shared<'a>,
@@ -95,8 +107,16 @@ struct World<'a> {
    respawn: Option<[i32; 3]>,
    unloaded: HashSet<(i32, i32)>,
    spawn_mobs: bool,
-    /// Boxes of living entities (case entities, then spawned mobs).
-    entities: RefCell<Vec<Aabb>>,
+    /// The `spawner_blocks_work` game rule.
+    spawners_work: bool,
+    /// Types and boxes of living entities (case entities, then spawned mobs).
+    entities: RefCell<Vec<(String, Aabb)>>,
+    /// Blocks set since the case started (a trial spawner's states).
+    placed: RefCell<Vec<([i32; 3], BlockStateId)>>,
+    /// The game time (trial cases advance it).
+    time: Cell<i64>,
+    /// The mobs a trial spawner added: UUID, position and box.
+    trial_mobs: RefCell<Vec<([i32; 4], [f64; 3], Aabb)>>,
 }
 impl World<'_> {
    fn biome_at(&self, x: i32, y: i32, z: i32) -> &str {
@@ -120,6 +140,15 @@ impl World<'_> {
 }
 impl SpawnLevel for World<'_> {
    fn state(&self, x: i32, y: i32, z: i32) -> BlockStateId {
+        if let Some((_, s)) = self
+            .placed
+            .borrow()
+            .iter()
+            .rev()
+            .find(|(p, _)| *p == [x, y, z])
+        {
+            return *s;
+        }
        self.blocks
            .iter()
            .rev()
@@ -280,10 +309,21 @@ impl NaturalLevel for World<'_> {
            block: &lookup,
            binding: self.s.collision,
        };
+        // getEntityCollisions(null, box): living shulkers are solid.
+        let grown = bounds.inflate(horizon_core::geometry::Vec3::new(1e-7, 1e-7, 1e-7));
        no_collision_empty(&mut world, bounds)
+            && !self
+                .entities
+                .borrow()
+                .iter()
+                .any(|(id, b)| id == "minecraft:shulker" && b.intersects(grown))
    }
    fn unobstructed(&self, bounds: Aabb) -> bool {
-        !self.entities.borrow().iter().any(|b| b.intersects(bounds))
+        !self
+            .entities
+            .borrow()
+            .iter()
+            .any(|(_, b)| b.intersects(bounds))
    }
    fn spawn_mobs(&self) -> bool {
        self.spawn_mobs
@@ -299,6 +339,72 @@ impl NaturalLevel for World<'_> {
    }
 }

+impl SpawnerLevel for World<'_> {
+    fn alive_player_near(&self, x: f64, y: f64, z: f64, range: f64) -> bool {
+        self.players.iter().any(|(p, mode)| {
+            let d = (p[0] - x).powi(2) + (p[1] - y).powi(2) + (p[2] - z).powi(2);
+            mode != "spectator" && (range < 0.0 || d < range * range)
+        })
+    }
+    fn spawner_blocks_work(&self) -> bool {
+        self.spawners_work
+    }
+    fn entity_exists(&self, id: &str) -> bool {
+        self.s.types.types.contains_key(id) || self.s.entity_types.contains(id)
+    }
+    fn count_entities(&self, id: &str, bounds: Aabb) -> usize {
+        self.entities
+            .borrow()
+            .iter()
+            .filter(|(k, b)| k == id && b.intersects(bounds))
+            .count()
+    }
+}
+
+impl TrialSpawnerLevel for World<'_> {
+    fn game_time(&self) -> i64 {
+        self.time.get()
+    }
+    fn mob_spawning(&self) -> bool {
+        self.spawn_mobs
+    }
+    fn players(&self) -> Vec<TrialPlayer> {
+        self.players
+            .iter()
+            .enumerate()
+            .map(|(i, (p, mode))| TrialPlayer {
+                uuid: [0, 0, 0, i as i32 + 1],
+                block: p.map(|v| v.floor() as i32),
+                eye: [p[0], p[1] + f64::from(1.62f32), p[2]],
+                creative: mode == "creative",
+                spectator: mode == "spectator",
+            })
+            .collect()
+    }
+    fn visual_hit(&self, from: [f64; 3], to: [f64; 3]) -> Option<[i32; 3]> {
+        let lookup = |x: i32, y: i32, z: i32| self.state(x, y, z);
+        let mut scene = LookupCollisions {
+            block: &lookup,
+            binding: self.s.collision,
+        };
+        let v = |p: [f64; 3]| horizon_core::geometry::Vec3::new(p[0], p[1], p[2]);
+        horizon_client::mobs::visual_clip(
+            self.s.facts,
+            self.s.collision,
+            &mut scene,
+            &lookup,
+            v(from),
+            v(to),
+        )
+        .flatten()
+    }
+    fn entity_block(&self, uuid: [i32; 4]) -> Option<[i32; 3]> {
+        let mobs = self.trial_mobs.borrow();
+        let (_, p, _) = mobs.iter().find(|(u, ..)| *u == uuid)?;
+        Some(p.map(|v| v.floor() as i32))
+    }
+}
+
 /// The box a mob is left with by `finalizeSpawn` under the oracle's fixed random.
 fn neutral_box(l: &World, r: &SpawnRequest) -> Aabb {
    let t = &l.s.types.types[r.entity];
@@ -365,10 +471,28 @@ fn main() -> horizon_client::Result<()> {
    let facts = BlockFacts::load(root, registry)?;
    let data = MobData::load(root, &facts);
    let items = Items::tags_only(root)?;
+    // Trial spawner rewards: the loot tables and the configs.
+    let loot = if input.contains("mode=trial") {
+        horizon_client::mobs::trial_spawner::load_registry(root);
+        horizon_client::structure_blocks::loot_data(root)
+    } else {
+        None
+    };
    let types = MobTypes::load(root)?;
    let biomes = Biomes::load(root)?;
    let structures = StructureSpawns::load(root);
    let collision = collisions::load(root, registry)?;
+    let entity_types: HashSet<String> = fs::read(root.join("entity-types.json"))
+        .ok()
+        .and_then(|b| serde_json::from_slice::<Value>(&b).ok())
+        .and_then(|v| {
+            v.as_object().map(|o| {
+                o.keys()
+                    .map(|k| horizon_client::command::args::normalize(k))
+                    .collect()
+            })
+        })
+        .unwrap_or_default();
    let shared = Shared {
        facts: &facts,
        data: &data,
@@ -378,6 +502,7 @@ fn main() -> horizon_client::Result<()> {
        structures: &structures,
        collision: &collision,
        air: facts.air,
+        entity_types: &entity_types,
    };
    let mut adaptation: HashMap<String, bool> = HashMap::new();
    let mut out = String::new();
@@ -538,12 +663,21 @@ fn main() -> horizon_client::Result<()> {
            respawn,
            unloaded,
            spawn_mobs: get("rules", "1") != "0",
+            spawners_work: get("spawners", "1") != "0",
+            placed: RefCell::new(Vec::new()),
+            time: Cell::new(0),
+            trial_mobs: RefCell::new(Vec::new()),
            entities: RefCell::new(
                case_entities
                    .iter()
-                    .filter_map(|(t, p, _)| {
-                        let t = types.types.get(t)?;
-                        Some(spawn_box(p[0], p[1], p[2], t.width as f32, t.height as f32))
+                    .filter_map(|(id, p, _)| {
+                        let t = types.types.get(id)?;
+                        // Entity.setPos (a shulker sits at its block's centre).
+                        let p = horizon_client::mobs::spawner::entity_position(t.species, *p);
+                        Some((
+                            id.clone(),
+                            spawn_box(p[0], p[1], p[2], t.width as f32, t.height as f32),
+                        ))
                    })
                    .collect(),
            ),
@@ -560,14 +694,19 @@ fn main() -> horizon_client::Result<()> {
        let mut log: Vec<String> = Vec::new();
        let mut spawn = |l: &World, r: &SpawnRequest| -> Option<Spawned> {
            let bounds = neutral_box(l, r);
-            l.entities.borrow_mut().push(bounds);
+            l.entities.borrow_mut().push((r.entity.to_owned(), bounds));
            Some(Spawned {
                bounds,
                school: true,
            })
        };
        let mode = get("mode", "chunk");
-        if mode == "gen" {
+        if mode == "spawner" {
+            spawner_case(&world, &get, &mut random, &mut log)?;
+        } else if mode == "trial" {
+            let loot = loot.as_ref().ok_or("no loot tables")?;
+            trial_case(&world, registry, loot, &get, &mut random, &mut log)?;
+        } else if mode == "gen" {
            let mut gen_random = LegacyRandom::new(get("gseed", "0").parse()?);
            // The level random of the spawn predicates: no creature's predicate
            // draws from it (the oracle's answers fixed values).
@@ -686,3 +825,279 @@ fn main() -> horizon_client::Result<()> {
    fs::write(args.get(3).ok_or("missing OUTPUT")?, out)?;
    Ok(())
 }
+
+/// `SpawnerBlockEntity.serverTick` `ticks` times at `spos` for the spawner in
+/// `snbt` (base64 SNBT), as the oracle logs it.
+fn spawner_case(
+    world: &World,
+    get: &dyn Fn(&str, &'static str) -> String,
+    random: &mut LegacyRandom,
+    log: &mut Vec<String>,
+) -> horizon_client::Result<()> {
+    let v: Vec<i32> = get("spos", "0,0,0")
+        .split(',')
+        .map(|n| n.parse().unwrap_or(0))
+        .collect();
+    let pos = [v[0], v[1], v[2]];
+    let text = horizon_client::skins::base64_decode(&get("snbt", "")).ok_or("bad snbt")?;
+    let tag = horizon_world::nbt::parse_snbt(&String::from_utf8(text)?)?.0;
+    let mut spawner = Spawner::load(&tag);
+    let ticks: i32 = get("ticks", "1").parse()?;
+    for tick in 0..ticks {
+        let mut events = Vec::new();
+        let mut spawned = std::collections::VecDeque::new();
+        let mut spawn = |l: &World, r: &SpawnerSpawn| -> Option<SpawnerAdded> {
+            let t = l.s.types.types.get(r.id)?;
+            let [x, y, z] = r.position;
+            let bounds = spawn_box(x, y, z, t.width as f32, t.height as f32);
+            l.entities.borrow_mut().push((r.id.to_owned(), bounds));
+            spawned.push_back(format!(
+                "{tick} spawn {} {} {} {} {}",
+                r.id,
+                bits(x),
+                bits(y),
+                bits(z),
+                // Shulker.finalizeSpawn faces it south.
+                yaw_text(
+                    r.id,
+                    if r.finalize && r.id == "minecraft:shulker" {
+                        0.0
+                    } else {
+                        r.yaw
+                    }
+                )
+            ));
+            Some(SpawnerAdded {
+                id: spawned.len() as u32,
+                bounds,
+                mob: true,
+            })
+        };
+        spawner.server_tick(world, random, pos, &mut spawn, &mut events);
+        for e in events {
+            match e {
+                SpawnerEvent::BlockUpdated => log.push(format!("{tick} update")),
+                SpawnerEvent::BlockEvent(id) => log.push(format!("{tick} bevent {id} 0")),
+                // Each spawn's level event follows its tryAddFreshEntityWithPassengers.
+                SpawnerEvent::LevelEvent(id) => {
+                    log.extend(spawned.pop_front());
+                    log.push(format!("{tick} levent {id} 0"));
+                }
+                SpawnerEvent::EntityPlace(_, p) => log.push(format!(
+                    "{tick} gevent minecraft:entity_place {} {} {}",
+                    p[0], p[1], p[2]
+                )),
+                SpawnerEvent::SpawnAnim(_) => log.push(format!("{tick} eevent 20")),
+            }
+        }
+    }
+    let next = spawner
+        .next_data()
+        .and_then(|d| d.id())
+        .unwrap_or_else(|| "-".into());
+    let pots: Vec<String> = spawner
+        .potentials
+        .iter()
+        .map(|(d, w)| format!("{}*{w}", d.id().unwrap_or_else(|| "-".into())))
+        .collect();
+    log.push(format!(
+        "end delay={} next={next} pots={}",
+        spawner.spawn_delay as i16,
+        pots.join(",")
+    ));
+    log.push(format!("next {}", random.next_int_bound(1000).unwrap_or(0)));
+    Ok(())
+}
+
+/// `TrialSpawner.tickServer` `ticks` times from game time `t0` at `spos` on a
+/// trial spawner block in state `state` (ominous with `ominous=1`) loaded from
+/// `snbt` (base64 SNBT), as the oracle logs it. Every `kill` ticks the mobs it
+/// spawned die.
+fn trial_case(
+    world: &World,
+    registry: &horizon_world::registry::BlockRegistry,
+    loot: &horizon_world::loot::LootData,
+    get: &dyn Fn(&str, &'static str) -> String,
+    random: &mut LegacyRandom,
+    log: &mut Vec<String>,
+) -> horizon_client::Result<()> {
+    let v: Vec<i32> = get("spos", "0,0,0")
+        .split(',')
+        .map(|n| n.parse().unwrap_or(0))
+        .collect();
+    let pos = [v[0], v[1], v[2]];
+    let block_state = |state: TrialState, ominous: bool| {
+        parse_state(&format!(
+            "minecraft:trial_spawner[trial_spawner_state={},ominous={ominous}]",
+            state.name()
+        ))
+    };
+    let mut state =
+        TrialState::from_name(&get("state", "waiting_for_players")).ok_or("bad state")?;
+    let mut ominous = get("ominous", "0") == "1";
+    world
+        .placed
+        .borrow_mut()
+        .push((pos, registry.resolve(&block_state(state, ominous))?));
+    let text = horizon_client::skins::base64_decode(&get("snbt", "")).ok_or("bad snbt")?;
+    let tag = horizon_world::nbt::parse_snbt(&String::from_utf8(text)?)?.0;
+    let mut spawner = TrialSpawner::load(&tag);
+    let ticks: i64 = get("ticks", "1").parse()?;
+    let t0: i64 = get("t0", "0").parse()?;
+    let kill: i64 = get("kill", "0").parse()?;
+    let seed = world.seed;
+    let mut sequences = horizon_client::random_sequences::RandomSequences::default();
+    let center = pos.map(|v| f64::from(v) + 0.5);
+    for tick in 0..ticks {
+        world.time.set(t0 + tick);
+        let mut events = Vec::new();
+        let mut spawned = std::collections::VecDeque::new();
+        let mut items = Vec::new();
+        let mut spawn = |l: &World, r: &SpawnerSpawn| {
+            let t = l.s.types.types.get(r.id)?;
+            // Slime.readAdditionalSaveData: size Size + 1, clamped to 1..=127.
+            let size = match r.entity.get(&horizon_world::nbt::JavaString::from("Size")) {
+                Some(Tag::Byte(v)) => i32::from(*v),
+                Some(Tag::Short(v)) => i32::from(*v),
+                Some(Tag::Int(v)) => *v,
+                Some(Tag::Long(v)) => *v as i32,
+                _ => 0,
+            };
+            let size = if matches!(r.id, "minecraft:slime" | "minecraft:magma_cube") {
+                size.saturating_add(1).clamp(1, 127)
+            } else {
+                1
+            };
+            let [x, y, z] = r.position;
+            let scale = size as f32;
+            let bounds = spawn_box(x, y, z, t.width as f32 * scale, t.height as f32 * scale);
+            l.entities.borrow_mut().push((r.id.to_owned(), bounds));
+            let uuid = [1, 0, 0, l.trial_mobs.borrow().len() as i32];
+            l.trial_mobs.borrow_mut().push((uuid, r.position, bounds));
+            spawned.push_back(format!(
+                "{tick} spawn {} {} {} {} {}",
+                r.id,
+                bits(x),
+                bits(y),
+                bits(z),
+                if size == 1 {
+                    yaw_text(r.id, r.yaw)
+                } else {
+                    "head".to_owned()
+                }
+            ));
+            Some(uuid)
+        };
+        let mut eject = |table: &str, random: &mut LegacyRandom| {
+            let drops = match loot.random_sequence(table) {
+                Some(s) => loot.roll_split(table, sequences.get(s, seed)),
+                None => loot.roll_split(table, random),
+            };
+            for stack in &drops {
+                random.next_double();
+                let spread = 0.017_227_5 * 2.0;
+                let v = [
+                    random.triangle(0.0, spread),
+                    random.triangle(0.2, spread),
+                    random.triangle(0.0, spread),
+                ];
+                items.push(format!(
+                    "{tick} item {} {} {} {} {} {} {} {}",
+                    stack.item,
+                    stack.count,
+                    bits(center[0]),
+                    bits(center[1] + 0.7 - 0.125),
+                    bits(center[2]),
+                    bits(v[0]),
+                    bits(v[1]),
+                    bits(v[2])
+                ));
+            }
+            !drops.is_empty()
+        };
+        let next = spawner.server_tick(
+            world,
+            random,
+            pos,
+            state,
+            ominous,
+            &mut spawn,
+            &mut eject,
+            &mut events,
+        );
+        for e in events {
+            match e {
+                TrialEvent::BlockUpdated => log.push(format!("{tick} update")),
+                TrialEvent::LevelEvent(id, _, data) => {
+                    // A spawn's events follow its tryAddFreshEntityWithPassengers,
+                    // a reward's its items.
+                    match id {
+                        3011 => log.extend(spawned.pop_front()),
+                        3014 => log.append(&mut items),
+                        _ => {}
+                    }
+                    log.push(format!("{tick} levent {id} {data}"));
+                }
+                TrialEvent::Sound(name) => log.push(format!(
+                    "{tick} sound minecraft:{name} {} {} {} 1.0 1.0",
+                    bits(center[0]),
+                    bits(center[1]),
+                    bits(center[2])
+                )),
+                TrialEvent::EntityPlace(_, p) => log.push(format!(
+                    "{tick} gevent minecraft:entity_place {} {} {}",
+                    p[0], p[1], p[2]
+                )),
+                TrialEvent::OminousSet(set) => {
+                    ominous = set;
+                    world
+                        .placed
+                        .borrow_mut()
+                        .push((pos, registry.resolve(&block_state(state, ominous))?));
+                    log.push(format!("{tick} state {} {ominous}", state.name()));
+                }
+            }
+        }
+        if next != state || spawner.is_ominous != ominous {
+            state = next;
+            ominous = spawner.is_ominous;
+            world
+                .placed
+                .borrow_mut()
+                .push((pos, registry.resolve(&block_state(state, ominous))?));
+            log.push(format!("{tick} state {} {ominous}", state.name()));
+        }
+        if kill > 0 && tick % kill == kill - 1 {
+            let dead: Vec<Aabb> = world
+                .trial_mobs
+                .borrow_mut()
+                .drain(..)
+                .map(|(.., b)| b)
+                .collect();
+            world
+                .entities
+                .borrow_mut()
+                .retain(|(_, b)| !dead.iter().any(|d| d == b));
+            if !dead.is_empty() {
+                log.push(format!("{tick} kill {}", dead.len()));
+            }
+        }
+    }
+    log.push(format!(
+        "end state={} players={} mobs={} cooldown={} next_spawn={} total={} data={} eject={}",
+        state.name(),
+        spawner.detected_players.len(),
+        spawner.current_mobs.len(),
+        spawner.cooldown_ends_at,
+        spawner.next_mob_spawns_at,
+        spawner.total_mobs_spawned,
+        spawner
+            .next_spawn_data
+            .as_ref()
+            .and_then(|d| d.id())
+            .unwrap_or_else(|| "-".into()),
+        spawner.ejecting_loot_table.as_deref().unwrap_or("-")
+    ));
+    log.push(format!("next {}", random.next_int_bound(1000).unwrap_or(0)));
+    Ok(())
+}
@@ -0,0 +1,92 @@
+//! The resource root Horizon builds for a pack selection (`packs::build_overlay`)
+//! and what its loaders read from it, for VanillaPackResourcesOracle.
+use horizon_client::{lang::Language, packs, sound_events::SoundRegistry};
+use std::{fmt::Write, fs, path::PathBuf};
+fn fnv(bytes: &[u8]) -> u64 {
+    bytes.iter().fold(0xcbf2_9ce4_8422_2325, |h, b| {
+        (h ^ u64::from(*b)).wrapping_mul(0x100_0000_01b3)
+    })
+}
+/// `namespace:path` to a file under the root's `assets/`.
+fn asset(root: &std::path::Path, id: &str, prefix: &str, suffix: &str) -> PathBuf {
+    let (namespace, path) = id.split_once(':').unwrap_or(("minecraft", id));
+    root.join("assets")
+        .join(namespace)
+        .join(format!("{prefix}{path}{suffix}"))
+}
+fn types(root: &std::path::Path, file: PathBuf, key: &str) -> String {
+    let _ = root;
+    let value: serde_json::Value = fs::read(file)
+        .ok()
+        .and_then(|b| serde_json::from_slice(&b).ok())
+        .unwrap_or_default();
+    value[key]
+        .as_array()
+        .into_iter()
+        .flatten()
+        .map(|v| {
+            let t = v["type"].as_str().unwrap_or("?");
+            format!(" {}", t.strip_prefix("minecraft:").unwrap_or(t))
+        })
+        .collect()
+}
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let args: Vec<_> = std::env::args().collect();
+    let input = fs::read_to_string(&args[1])?;
+    let mut lines = input.lines();
+    let root: Vec<&str> = lines.next().ok_or("empty input")?.split(' ').collect();
+    let vanilla = PathBuf::from(root[1]);
+    let ids: Vec<String> = root[3..].iter().map(|s| (*s).to_owned()).collect();
+    let all = packs::discover(&vanilla, &PathBuf::from(root[2]));
+    let enabled = packs::enabled(&all, &ids);
+    let overlay = PathBuf::from(&args[2]).with_extension("overlay");
+    packs::build_overlay(&vanilla, &enabled, &overlay)?;
+    let language = Language::load(&[&overlay], "en_us");
+    let sounds = SoundRegistry::load(&overlay);
+    let mut out = String::new();
+    for line in lines {
+        let (kind, arg) = line.split_once(' ').unwrap_or((line, ""));
+        write!(out, "{line} =>")?;
+        match kind {
+            "file" => match fs::read(asset(&overlay, arg, "", "")) {
+                Ok(bytes) => write!(out, " {:x}", fnv(&bytes))?,
+                Err(_) => out.push_str(" missing"),
+            },
+            "lang" => write!(out, " {}", language.get(arg).unwrap_or(arg))?,
+            "sound" => {
+                let event = if arg.contains(':') {
+                    arg.to_owned()
+                } else {
+                    format!("minecraft:{arg}")
+                };
+                match sounds.get(&event) {
+                    None => out.push_str(" missing"),
+                    Some(e) => {
+                        write!(out, " subtitle={}", e.subtitle.as_deref().unwrap_or("none"))?;
+                        for s in &e.sounds {
+                            if s.event {
+                                out.push_str(" event");
+                            } else {
+                                write!(out, " {}*{}", s.location, s.weight)?;
+                            }
+                        }
+                    }
+                }
+            }
+            "font" => out.push_str(&types(
+                &overlay,
+                asset(&overlay, arg, "font/", ".json"),
+                "providers",
+            )),
+            "atlas" => out.push_str(&types(
+                &overlay,
+                asset(&overlay, arg, "atlases/", ".json"),
+                "sources",
+            )),
+            _ => return Err(format!("unknown query {line}").into()),
+        }
+        out.push('\n');
+    }
+    fs::write(&args[2], out)?;
+    Ok(())
+}
@@ -0,0 +1,233 @@
+#![forbid(unsafe_code)]
+//! Runs tools/test_particle_providers_parity.py's particles through
+//! `ParticleEngine`: built with the seeds the vanilla oracle recovered, then
+//! ticked over air or a stone floor at y 63, printing their state each tick.
+use horizon_client::{
+    Result,
+    assets::Assets,
+    blocks::BlockFacts,
+    chunk::Chunk,
+    collisions,
+    particles::{ParticleEngine, ParticleLevel, ParticleOptions, ParticleSnapshot, ParticleType},
+    world::World,
+};
+use serde_json::Value;
+use std::{
+    collections::HashMap,
+    fs::File,
+    io::{BufRead, BufReader, BufWriter, Write},
+    path::Path,
+    sync::Arc,
+};
+
+fn d(v: f64) -> String {
+    format!("{:016x}", v.to_bits())
+}
+fn f(v: f32) -> String {
+    format!("{:08x}", v.to_bits())
+}
+fn color(v: &Value, default: u32) -> u32 {
+    v.as_u64().map_or(default, |c| c as u32)
+}
+fn rgb(c: u32) -> [f32; 3] {
+    [
+        ((c >> 16) & 255) as f32 / 255.0,
+        ((c >> 8) & 255) as f32 / 255.0,
+        (c & 255) as f32 / 255.0,
+    ]
+}
+fn options(case: &Value) -> Option<ParticleOptions> {
+    let ty = ParticleType::from_name(case["type"].as_str()?)?;
+    let o = &case["options"];
+    let scale = o["scale"].as_f64().unwrap_or(1.0) as f32;
+    let c = color(&o["color"], 0xFFFF_FFFF);
+    let argb = {
+        let [r, g, b] = rgb(c);
+        [r, g, b, ((c >> 24) & 255) as f32 / 255.0]
+    };
+    Some(match ty {
+        ParticleType::Block
+        | ParticleType::BlockCrumble
+        | ParticleType::DustPillar
+        | ParticleType::BlockMarker => ParticleOptions::block(ty, "terrain".into(), 0xFF_FFFF),
+        // Stone's map colour: FallingDustParticle.Provider's tint without a tint source.
+        ParticleType::FallingDust => ParticleOptions::block(ty, "terrain".into(), 0x70_7070),
+        ParticleType::Dust => ParticleOptions::dust(rgb(c), scale),
+        ParticleType::DustColorTransition => {
+            ParticleOptions::dust_transition(rgb(c), rgb(color(&o["to"], 0)), scale)
+        }
+        ParticleType::Effect | ParticleType::InstantEffect => ParticleOptions {
+            scale,
+            ..ParticleOptions::colored(ty, argb)
+        },
+        // The oracle's item models: one layer whose sprite is named after the item.
+        ParticleType::Item => {
+            let item = o["item"].as_str()?;
+            ParticleOptions::item(vec![format!(
+                "item_{}",
+                item.strip_prefix("minecraft:").unwrap_or(item)
+            )])
+        }
+        ParticleType::EntityEffect | ParticleType::TintedLeaves | ParticleType::Flash => {
+            ParticleOptions::colored(ty, argb)
+        }
+        ParticleType::DragonBreath => ParticleOptions {
+            scale,
+            ..ParticleOptions::simple(ty)
+        },
+        ParticleType::SculkCharge => ParticleOptions::sculk_charge(scale),
+        ParticleType::Shriek => ParticleOptions::shriek(scale as i32),
+        ParticleType::Trail => {
+            let t = &o["target"];
+            ParticleOptions::trail(
+                [t[0].as_f64()?, t[1].as_f64()?, t[2].as_f64()?],
+                c & 0xFF_FFFF,
+                o["duration"].as_i64()? as i32,
+            )
+        }
+        _ => ParticleOptions::simple(ty),
+    })
+}
+fn state(s: &ParticleSnapshot) -> String {
+    let mut out = format!(
+        "{} {} {} {}",
+        s.age,
+        s.lifetime,
+        u8::from(s.removed),
+        u8::from(s.on_ground)
+    );
+    for v in s.position.iter().chain(&s.velocity).chain(&s.previous) {
+        out += &format!(" {}", d(*v));
+    }
+    if let Some(q) = &s.quad {
+        out += &format!(" | {} {}", f(q.size[0]), f(q.size[1]));
+        for v in q.rgba.iter().chain(&q.roll) {
+            out += &format!(" {}", f(*v));
+        }
+        out += &format!(" {}", q.sprite);
+        for v in q.uv {
+            out += &format!(" {}", f(v));
+        }
+        out += &format!(" {:x}", q.light);
+    }
+    out
+}
+fn world(assets: &Assets, facts: &BlockFacts, floor: bool) -> Result<World> {
+    let mut world = World::new(facts.air, 0);
+    let stone = assets
+        .registry
+        .default_state("minecraft:stone")
+        .ok_or("missing stone")?;
+    for cz in -3..=2 {
+        for cx in -3..=2 {
+            world
+                .chunks
+                .insert((cx, cz), Arc::new(Chunk::empty(cx, cz)));
+            if floor {
+                for z in 0..16 {
+                    for x in 0..16 {
+                        world.set(cx * 16 + x, 63, cz * 16 + z, stone)?;
+                    }
+                }
+            }
+        }
+    }
+    Ok(world)
+}
+
+fn main() -> Result<()> {
+    let args: Vec<String> = std::env::args().collect();
+    let root = Path::new(".local/horizon-client/26.3");
+    let assets = Assets::load(root)?;
+    let facts = BlockFacts::load(root, assets.registry)?;
+    let collision = collisions::load(root, assets.registry)?;
+    let worlds = [
+        world(&assets, &facts, false)?,
+        world(&assets, &facts, true)?,
+    ];
+    let mut engine = ParticleEngine::new(root, &HashMap::new());
+    for (ty, item) in [
+        (ParticleType::ItemSlime, "item_slime_ball"),
+        (ParticleType::ItemSnowball, "item_snowball"),
+        (ParticleType::ItemCobweb, "item_cobweb"),
+    ] {
+        engine.item_sprites.insert(ty, vec![item.to_owned()]);
+    }
+    // The oracle's output: the seed line of each case.
+    let mut seeds = Vec::new();
+    for line in BufReader::new(File::open(&args[2])?).lines() {
+        let line = line?;
+        if line.starts_with("seed ") || line.starts_with("null ") || line == "no provider" {
+            seeds.push(line);
+        }
+    }
+    let mut out = BufWriter::new(File::create(&args[3])?);
+    for (n, line) in BufReader::new(File::open(&args[1])?).lines().enumerate() {
+        let case: Value = serde_json::from_str(&line?)?;
+        writeln!(out, "== {n}")?;
+        let Some(options) = options(&case) else {
+            writeln!(out, "no provider")?;
+            continue;
+        };
+        let seed = case["seed"].as_i64().ok_or("seed")?;
+        engine.seed_randoms(seed, seed ^ 0x6C_6576_656C, seed ^ 0x73_7065_6C6C);
+        engine.requested = Some(Vec::new());
+        engine.sounds.clear();
+        let level = ParticleLevel {
+            world: &worlds[usize::from(case["floor"].as_bool() == Some(true))],
+            facts: &facts,
+            collision: &collision,
+            player: None,
+        };
+        let v = |key: &str| -> [f64; 3] {
+            std::array::from_fn(|i| case[key][i].as_f64().unwrap_or(0.0))
+        };
+        let seed_line = seeds.get(n).cloned().unwrap_or_default();
+        let local = seed_line
+            .split(' ')
+            .nth(1)
+            .and_then(|s| s.parse::<i64>().ok())
+            .unwrap_or(0);
+        let Some(mut particle) = engine.probe_create(&options, v("pos"), v("vel"), local, &level)
+        else {
+            writeln!(out, "null {}", engine.next_randoms()[0])?;
+            continue;
+        };
+        writeln!(out, "{seed_line}")?;
+        let [a, b, c] = engine.next_randoms();
+        writeln!(out, "next {a} {b} {c}")?;
+        let events = |engine: &mut ParticleEngine, out: &mut BufWriter<File>| -> Result<()> {
+            for (o, p, v) in engine.requested.replace(Vec::new()).unwrap_or_default() {
+                write!(out, "+ {}", o.ty.name())?;
+                for x in p.iter().chain(&v) {
+                    write!(out, " {}", d(*x))?;
+                }
+                writeln!(out)?;
+            }
+            for (name, p, volume, pitch) in std::mem::take(&mut engine.sounds) {
+                writeln!(
+                    out,
+                    "~ {name} {} {} {} {} {}",
+                    d(p[0]),
+                    d(p[1]),
+                    d(p[2]),
+                    f(volume),
+                    f(pitch)
+                )?;
+            }
+            Ok(())
+        };
+        writeln!(out, "0 {}", state(&engine.snapshot(&particle)))?;
+        events(&mut engine, &mut out)?;
+        let ticks = case["ticks"].as_i64().unwrap_or(0);
+        let mut t = 1;
+        while t <= ticks && particle.is_alive() {
+            engine.probe_tick(&mut particle, &level);
+            writeln!(out, "{t} {}", state(&engine.snapshot(&particle)))?;
+            events(&mut engine, &mut out)?;
+            t += 1;
+        }
+    }
+    out.flush()?;
+    Ok(())
+}
@@ -43,6 +43,7 @@ fn main() -> horizon_client::Result<()> {
        recipes: &recipes,
        brewing: &brewing,
        banners: &banners,
+        trade: None,
    };
    let mut out = String::new();
    for (line, order) in cases.lines().zip(orders.lines()) {
@@ -0,0 +1,260 @@
+//! Synthetic village/storage save batches, using the production snapshot and
+//! full chunk NBT encoder. Run with `cargo run --profile fast -p horizon-client
+//! --example save_batch_bench`. Add `-- --nbt` to also time serialization.
+//! Exact NBT equality is always validated. No GPU, compression or disk I/O timed.
+use horizon_client::{
+    biome::Biomes,
+    chunk::{BLOCK_STRATEGY, Chunk},
+    containers::BlockEntity,
+    items::ItemStack,
+    save::{self, ChunkExtras},
+};
+use horizon_core::paletted::PalettedContainer;
+use horizon_world::{
+    DATA_VERSION,
+    nbt::{self, Limits, Tag},
+    registry::BlockRegistry,
+};
+use std::{collections::HashMap, hint::black_box, sync::Arc, time::Instant};
+
+type Entities = HashMap<(i32, i32, i32), BlockEntity>;
+type Names = HashMap<(i32, i32, i32), String>;
+const BLOCKS: [&str; 5] = [
+    "minecraft:air",
+    "minecraft:stone",
+    "minecraft:chest",
+    "minecraft:furnace",
+    "minecraft:oak_sign",
+];
+
+// The pre-change with_entities path, with the same Chunk clone and outputs.
+fn baseline(chunks: &[Arc<Chunk>], entities: &Entities, names: &Names) -> Vec<Chunk> {
+    chunks
+        .iter()
+        .map(|chunk| {
+            let mut c = (**chunk).clone();
+            c.block_entities = entities
+                .iter()
+                .filter(|(p, _)| p.0 >> 4 == c.x && p.2 >> 4 == c.z)
+                .map(|(p, e)| (*p, e.clone()))
+                .collect();
+            c.block_names = names
+                .iter()
+                .filter(|(p, _)| p.0 >> 4 == c.x && p.2 >> 4 == c.z)
+                .map(|(p, n)| (*p, n.clone()))
+                .collect();
+            c
+        })
+        .collect()
+}
+
+fn fixture(per_chunk: usize) -> (Vec<Arc<Chunk>>, Entities, Names) {
+    let mut chunks = Vec::new();
+    let mut entities = Entities::new();
+    let mut names = Names::new();
+    let stack = ItemStack {
+        item: "minecraft:stone".into(),
+        count: 64,
+        damage: 0,
+        extra: horizon_client::item_data::decode_components(Some(&Tag::compound([(
+            "minecraft:custom_data",
+            Tag::compound([("fixture", Tag::String("save batch".into()))]),
+        )])))
+        .1,
+    };
+    let mut template = Chunk::empty(0, 0);
+    for s in &mut template.sections[..8] {
+        Arc::make_mut(s).blocks = PalettedContainer::new(BLOCK_STRATEGY, 1);
+    }
+    template.heights = Arc::new([64; 256]);
+    for i in 0..256 {
+        let x = i % 16 - 8;
+        let z = i / 16 - 8;
+        let mut c = template.clone();
+        c.x = x;
+        c.z = z;
+        let mut extras = ChunkExtras::default();
+        extras.root.insert("InhabitedTime".into(), Tag::Long(12000));
+        for j in 0..per_chunk {
+            let p = (
+                x * 16 + (j % 16) as i32,
+                64 + (j / 256) as i32,
+                z * 16 + ((j / 16) % 16) as i32,
+            );
+            let (block, mut e) = match j % 4 {
+                0 => (4, BlockEntity::for_block(BLOCKS[4]).unwrap()),
+                1 => (3, BlockEntity::for_block(BLOCKS[3]).unwrap()),
+                _ => (2, BlockEntity::Chest(vec![Some(stack.clone()); 27])),
+            };
+            if let BlockEntity::Furnace(f) = &mut e {
+                f.items[0] = Some(stack.clone());
+                f.lit_remaining = 120;
+                f.cooking_timer = 45;
+            }
+            if let BlockEntity::Sign(s) = &mut e {
+                s.front.lines[0] = "Village storage".into();
+            }
+            c.set(p.0 & 15, p.1, p.2 & 15, block);
+            if j % 4 == 2 {
+                names.insert(p, format!("Storage {x},{z}/{j}"));
+            }
+            // Exercise the existing NBT overlay and saved list order as well.
+            if j % 8 == 2 {
+                let mut raw = save::encode_block_entity(p, &e, BLOCKS[block as usize]);
+                if let Tag::Compound(map) = &mut raw {
+                    map.insert(
+                        "LootTable".into(),
+                        Tag::String("minecraft:chests/simple_dungeon".into()),
+                    );
+                }
+                extras.block_entity_sources.push((p, raw));
+            }
+            extras.block_entity_order.push(p);
+            entities.insert(p, e);
+        }
+        // An unmodelled block entity, retained from the original chunk.
+        extras.block_entities.push(Tag::compound([
+            ("id", Tag::String("minecraft:end_gateway".into())),
+            ("x", Tag::Int(x * 16)),
+            ("y", Tag::Int(80)),
+            ("z", Tag::Int(z * 16)),
+            ("Age", Tag::Long(200)),
+        ]));
+        c.saved = Some(Arc::new(extras));
+        chunks.push(Arc::new(c));
+    }
+    (chunks, entities, names)
+}
+
+fn encoding_fixture() -> horizon_client::Result<(BlockRegistry, Biomes)> {
+    let registry = BlockRegistry::from_nbt(&Tag::compound([
+        ("DataVersion", Tag::Int(DATA_VERSION)),
+        (
+            "states",
+            Tag::List(BLOCKS.iter().map(|n| Tag::String((*n).into())).collect()),
+        ),
+        (
+            "defaults",
+            Tag::compound(
+                BLOCKS
+                    .iter()
+                    .enumerate()
+                    .map(|(i, n)| (*n, Tag::Int(i as i32))),
+            ),
+        ),
+    ]))?;
+    let temp = std::env::temp_dir().join(format!("horizon-save-batch-{}", std::process::id()));
+    let result = (|| {
+        let textures = temp.join("assets/minecraft/textures/colormap");
+        let biomes = temp.join("data/minecraft/worldgen/biome");
+        std::fs::create_dir_all(&textures)?;
+        std::fs::create_dir_all(&biomes)?;
+        for name in ["grass", "foliage", "dry_foliage"] {
+            let mut encoder = png::Encoder::new(
+                std::fs::File::create(textures.join(format!("{name}.png")))?,
+                1,
+                1,
+            );
+            encoder.set_color(png::ColorType::Rgb);
+            encoder.write_header()?.write_image_data(&[0, 128, 0])?;
+        }
+        std::fs::write(biomes.join("plains.json"), b"{}")?;
+        Biomes::load(&temp)
+    })();
+    std::fs::remove_dir_all(&temp)?;
+    Ok((registry, result?))
+}
+
+fn serialize(chunks: &[Chunk], registry: &BlockRegistry, biomes: &Biomes) -> Vec<Vec<u8>> {
+    chunks
+        .iter()
+        .map(|c| nbt::write_named(&save::encode(c, registry, biomes), Limits::default()).unwrap())
+        .collect()
+}
+
+fn measure(mut f: impl FnMut(), repetitions: usize) -> f64 {
+    let start = Instant::now();
+    for _ in 0..repetitions {
+        f();
+    }
+    start.elapsed().as_secs_f64() * 1e6 / repetitions as f64
+}
+
+fn compare(mut before: impl FnMut(), mut after: impl FnMut()) -> (f64, f64, usize) {
+    for _ in 0..5 {
+        before();
+        after();
+    }
+    let estimate = measure(&mut before, 1).max(measure(&mut after, 1));
+    let repetitions = (10_000.0 / estimate.max(0.01)).ceil().clamp(1.0, 10_000.0) as usize;
+    let mut old = Vec::new();
+    let mut new = Vec::new();
+    for i in 0..21 {
+        if i % 2 == 0 {
+            old.push(measure(&mut before, repetitions));
+            new.push(measure(&mut after, repetitions));
+        } else {
+            new.push(measure(&mut after, repetitions));
+            old.push(measure(&mut before, repetitions));
+        }
+    }
+    old.sort_by(f64::total_cmp);
+    new.sort_by(f64::total_cmp);
+    (old[10], new[10], repetitions)
+}
+
+fn main() -> horizon_client::Result<()> {
+    let include_nbt = std::env::args().any(|arg| arg == "--nbt");
+    let (registry, biomes) = encoding_fixture()?;
+    println!(
+        "stage,fixture,chunks,world_entities,world_names,saved_entities,bytes,before_us,after_us,speedup,samples,reps"
+    );
+    for (name, density) in [("village", 12), ("storage", 48)] {
+        let (chunks, entities, names) = fixture(density);
+        for count in [0, 1, 16, 64, 256] {
+            let batch = &chunks[..count];
+            let before = baseline(batch, &entities, &names);
+            let after = save::chunks_with_block_entities(batch, &entities, &names);
+            for (a, b) in before.iter().zip(&after) {
+                assert_eq!(a.block_names, b.block_names);
+            }
+            let encoded = serialize(&before, &registry, &biomes);
+            assert_eq!(
+                encoded,
+                serialize(&after, &registry, &biomes),
+                "exact NBT bytes: {name}/{count}"
+            );
+            let bytes: usize = encoded.iter().map(Vec::len).sum();
+            for encode in [false, true] {
+                if encode && !include_nbt {
+                    continue;
+                }
+                let run = |optimized| {
+                    let snapshots = if optimized {
+                        save::chunks_with_block_entities(
+                            black_box(batch),
+                            black_box(&entities),
+                            black_box(&names),
+                        )
+                    } else {
+                        baseline(black_box(batch), black_box(&entities), black_box(&names))
+                    };
+                    if encode {
+                        black_box(serialize(black_box(&snapshots), &registry, &biomes));
+                    }
+                    black_box(snapshots);
+                };
+                let (old, new, reps) = compare(|| run(false), || run(true));
+                println!(
+                    "{},{name},{count},{},{},{},{bytes},{old:.3},{new:.3},{:.3},21,{reps}",
+                    if encode { "snapshot+nbt" } else { "snapshot" },
+                    entities.len(),
+                    names.len(),
+                    count * density,
+                    old / new
+                );
+            }
+        }
+    }
+    Ok(())
+}
@@ -10,7 +10,7 @@ use horizon_client::{
    biome::Biomes,
    blocks::BlockFacts,
    chunk::{Chunk, MIN_Y, SECTIONS},
-    light::{LightTables, light_chunk},
+    light::{LightTables, apply_lighting, light_chunk},
    save::{self, SaveTables},
 };
 use horizon_core::position::ChunkPos;
@@ -157,7 +157,7 @@ fn main() -> horizon_client::Result<()> {
            std::array::from_fn(|dx| chunks.get(&(x + dx as i32 - 1, z + dz as i32 - 1)))
        });
        let mut chunk = chunks[&(x, z)].clone();
-        chunk.sections = light_chunk(&region, &lights, sky_light);
+        apply_lighting(&mut chunk, light_chunk(&region, &lights, sky_light));
        chunk.lit = true;
        let ours = save::encode_with(&chunk, assets.registry, &biomes, Some(&tables), sky_light);
        let theirs = &originals[&(x, z)];
@@ -40,6 +40,7 @@ fn main() -> Result<()> {
    let mut scene = collisions::SceneCollisions {
        world: &world,
        binding: &binding,
+        subject: None,
    };
    fs::write(
        dir.join("scene.json"),
@@ -4,7 +4,7 @@ use horizon_client::{
    Result,
    assets::Assets,
    collisions,
-    motion::{MotionEvent, MotionResources, MotionWorld, PlayerMotion},
+    motion::{LAVA, MotionEvent, MotionResources, MotionWorld, PlayerMotion, WATER},
    world::World,
 };
 use horizon_core::geometry::Vec3;
@@ -165,6 +165,64 @@ fn snapshot(out: &mut impl Write, player: &PlayerMotion) -> Result<()> {
        .filter_map(|e| match e {
            MotionEvent::Fall(e) => Some(e.trace()),
            MotionEvent::Health(e) => Some(e.trace()),
+            MotionEvent::Snowflake { position, velocity } => Some(format!(
+                "snowflake {:016x},{:016x},{:016x} {:016x},{:016x},{:016x}",
+                position.x.to_bits(),
+                position.y.to_bits(),
+                position.z.to_bits(),
+                velocity.x.to_bits(),
+                velocity.y.to_bits(),
+                velocity.z.to_bits()
+            )),
+            MotionEvent::Splash {
+                high_speed,
+                volume,
+                pitch,
+            } => Some(format!(
+                "sound {} entity {:08x} {:08x}",
+                if *high_speed { "splash-high" } else { "splash" },
+                volume.to_bits(),
+                pitch.to_bits()
+            )),
+            MotionEvent::SplashParticle {
+                bubble,
+                position,
+                velocity,
+            } => Some(format!(
+                "splash-particle {} {:016x},{:016x},{:016x} {:016x},{:016x},{:016x}",
+                if *bubble { "bubble" } else { "splash" },
+                position.x.to_bits(),
+                position.y.to_bits(),
+                position.z.to_bits(),
+                velocity.x.to_bits(),
+                velocity.y.to_bits(),
+                velocity.z.to_bits()
+            )),
+            MotionEvent::SplashEvent => Some("splash-event".into()),
+            MotionEvent::Swim { volume, pitch } => Some(format!(
+                "sound swim entity {:08x} {:08x}",
+                volume.to_bits(),
+                pitch.to_bits()
+            )),
+            MotionEvent::Emission {
+                state,
+                in_water: true,
+                ..
+            } => Some(format!("muffled-step {}", state.0)),
+            MotionEvent::BubbleColumnParticle { bubble, position } => Some(format!(
+                "column-particle {} {:016x},{:016x},{:016x} 1 {:016x},{:016x},{:016x} {:016x}",
+                if *bubble { "bubble" } else { "splash" },
+                position.x.to_bits(),
+                position.y.to_bits(),
+                position.z.to_bits(),
+                0f64.to_bits(),
+                if *bubble { 0.01f64 } else { 0.0 }.to_bits(),
+                0f64.to_bits(),
+                if *bubble { 0.2f64 } else { 1.0 }.to_bits()
+            )),
+            MotionEvent::Drown => Some("broadcast 67".into()),
+            // The oracle marks every getAdvancements call (ENTER_BLOCK.trigger) so.
+            MotionEvent::EnterBlock { .. } => Some("hurt-criterion".into()),
            MotionEvent::Waypoint { receiver, enabled } => Some(format!(
                "waypoint {} {enabled}",
                if *receiver { "receive" } else { "transmit" }
@@ -232,6 +290,12 @@ fn main() -> Result<()> {
                instances.next().expect("unexpected instance allocation")
            }),
        )?;
+        // The oracle runs block-inside effects only in "snow_tick".
+        player.block_effects = false;
+        // Entity.portalCooldown and portalProcess, and the entry of the last
+        // portal_tick that went through.
+        let mut portal = horizon_client::nether_portal::PortalState::default();
+        let mut travel: Option<horizon_core::position::BlockPos> = None;
        for op in f["ops"].as_array().unwrap() {
            let mut world = MotionWorld {
                player: &mut player,
@@ -261,6 +325,7 @@ fn main() -> Result<()> {
                        jump: mask & 16 != 0,
                        shift: mask & 32 != 0,
                        sprint: mask & 64 != 0,
+                        analog: None,
                    })?;
                }
                "movement_statistics" => world.check_movement_statistics(vector(&op["value"]))?,
@@ -356,7 +421,8 @@ fn main() -> Result<()> {
                        Some(vector(&op["value"]))
                    },
                ),
-                "block" => {
+                // A block, or every block of the box from position to "to".
+                "block" | "fill" => {
                    let p = &op["position"];
                    let mut state = assets
                        .registry
@@ -374,12 +440,15 @@ fn main() -> Result<()> {
                            .id(&definition)
                            .ok_or("missing fixture state")?;
                    }
-                    world.scene.set(
-                        p[0].as_i64().unwrap() as i32,
-                        p[1].as_i64().unwrap() as i32,
-                        p[2].as_i64().unwrap() as i32,
-                        state,
-                    )?;
+                    let at = |v: &Value, i: usize| v[i].as_i64().unwrap() as i32;
+                    let to = if op["to"].is_array() { &op["to"] } else { p };
+                    for x in at(p, 0)..=at(to, 0) {
+                        for y in at(p, 1)..=at(to, 1) {
+                            for z in at(p, 2)..=at(to, 2) {
+                                world.scene.set(x, y, z, state)?;
+                            }
+                        }
+                    }
                }
                "landing" => {
                    let p = &op["position"];
@@ -397,6 +466,26 @@ fn main() -> Result<()> {
                        p,
                    )?;
                }
+                // Entity.baseTick's fluid phase alone (wasEyeInWater,
+                // updateFluidInteraction, lava fall halving, firstTick).
+                "fluid_tick" => world.fluid_base_tick()?,
+                // LivingEntity.baseTick's air supply alone.
+                "air_tick" => world.tick_environment_damage()?,
+                "air" => world.player.air = op["value"].as_i64().unwrap() as i32,
+                "pitch" => world.player.pitch = single(&op["value"]),
+                "swimming" => world.player.swimming = op["value"].as_bool().unwrap(),
+                "effect" => {
+                    let on = op["value"].as_bool().unwrap();
+                    let status = &mut world.player.status;
+                    match op["name"].as_str().unwrap() {
+                        "minecraft:dolphins_grace" => status.dolphins_grace = on,
+                        "minecraft:water_breathing" | "minecraft:conduit_power" => {
+                            status.water_breathing = on
+                        }
+                        "minecraft:breath_of_the_nautilus" => status.breath_of_the_nautilus = on,
+                        other => return Err(format!("unknown fixture effect {other}").into()),
+                    }
+                }
                "travel" => world.travel_in_air(vector(&op["value"]))?,
                "tick" => {
                    let v = vector(&op["value"]);
@@ -409,6 +498,40 @@ fn main() -> Result<()> {
                        op["jumping"].as_bool().unwrap(),
                    )?;
                }
+                "snow_tick" => {
+                    // The clock, then the player tick: baseTick's powder snow
+                    // flags lead PlayerMotion::player_movement_tick.
+                    world.player.health.advance_clock();
+                    let v = vector(&op["value"]);
+                    world.player.block_effects = true;
+                    let ticked = world.player_movement_tick(
+                        [v.x as f32, v.z as f32],
+                        op["jumping"].as_bool().unwrap(),
+                    );
+                    world.player.block_effects = false;
+                    ticked?;
+                }
+                "boots" => {
+                    // Leather boots are also freeze-immune wearables.
+                    let boots = op["value"].as_bool().unwrap();
+                    world.player.leather_boots = boots;
+                    world.player.freeze_immune = boots;
+                }
+                "frozen" => world.player.ticks_frozen = op["value"].as_i64().unwrap() as i32,
+                "portal_tick" => {
+                    // Entity.handlePortal without the destination: players wait
+                    // the creative delay (0) when invulnerable, else 80 ticks.
+                    let creative = op["creative"].as_bool().unwrap();
+                    let transition = if creative { 0 } else { 80 };
+                    let alive = !world.player.health.dead_or_dying();
+                    travel = portal.handle(alive, transition, 10);
+                }
+                "weaving" => world.player.status.weaving = op["value"].as_bool().unwrap(),
+                "flying" => {
+                    let flying = op["value"].as_bool().unwrap();
+                    world.player.may_fly = op["may_fly"].as_bool().unwrap_or(flying);
+                    world.player.flying = flying;
+                }
                "trigger" => world.player.jump_trigger_time = op["value"].as_i64().unwrap() as i32,
                "delay" => world.player.no_jump_delay = op["value"].as_i64().unwrap() as i32,
                "move" => world.move_self(vector(&op["value"]))?,
@@ -476,9 +599,49 @@ fn main() -> Result<()> {
                }
                _ => return Err("unknown motion operation".into()),
            }
+            // NetherPortalBlock.entityInside: canUsePortal, setAsInsidePortal.
+            for e in &player.events {
+                if let MotionEvent::InsidePortal { pos } = e
+                    && !player.health.dead_or_dying()
+                {
+                    portal.set_inside(*pos, 10);
+                }
+            }
            let check_block = scene.block(25, 3, 25);
            snapshot(&mut out, &player)?;
-            writeln!(out, "block {}", check_block.0)?;
+            let stuck = player.stuck_multiplier;
+            writeln!(
+                out,
+                "block {} frozen {} {} {} {:016x},{:016x},{:016x} fluid {} {} {} {} {:016x} {:016x} swim {} {} air {}",
+                check_block.0,
+                player.ticks_frozen,
+                player.in_powder_snow,
+                player.was_in_powder_snow,
+                stuck.x.to_bits(),
+                stuck.y.to_bits(),
+                stuck.z.to_bits(),
+                player.fluids.was_touching_water,
+                player.fluids.was_eye_in_water,
+                player.is_eye_in_fluid(WATER),
+                player.fluids.first_tick,
+                player.fluid_height(WATER).to_bits(),
+                player.fluid_height(LAVA).to_bits(),
+                player.swimming,
+                player.fluids.was_eye_in_water,
+                player.air
+            )?;
+            writeln!(
+                out,
+                "portal {} {} {}",
+                portal.cooldown,
+                portal.process.map_or("none".into(), |p| format!(
+                    "{},{},{} {} {}",
+                    p.entry.x, p.entry.y, p.entry.z, p.time, p.inside
+                )),
+                travel
+                    .take()
+                    .map_or("-".into(), |t| format!("{},{},{}", t.x, t.y, t.z))
+            )?;
            let h = &player.health;
            let canonical = |v: f32| {
                if v.is_nan() {
@@ -7,7 +7,7 @@ use horizon_client::{
    biome::{BiomeInfo, Biomes, GrassModifier},
    blocks::BlockFacts,
    chunk::{Chunk, Light, MIN_Y, index},
-    mesher::{MeshTables, Mesher, OPAQUE_LAYER, Vertex},
+    mesher::{MeshTables, Mesher, OPAQUE_LAYER, TerrainVertex},
    models,
 };
 use horizon_core::biome::BiomeZoom;
@@ -33,7 +33,8 @@ fn argb(color: u32) -> i32 {
 }
 /// Horizon keeps sky*16 in the low byte and block*16 above it; vanilla's light
 /// coords keep block in the low half-word and sky in the high one.
-fn light_coords(light: u32) -> i32 {
+fn light_coords(light: u16) -> i32 {
+    let light = u32::from(light);
    ((light & 0xFF) << 16 | (light >> 8 & 0xFF)) as i32
 }
 /// Scenes cover the 3x3 chunk region around chunk (0, 0).
@@ -146,9 +147,12 @@ fn scene(
        }
        for quad in vertices {
            let sprite = names
-                .get(&(quad[0].layer & !OPAQUE_LAYER))
+                .get(&u32::from(quad[0].layer & !OPAQUE_LAYER))
                .ok_or("unknown sprite layer")?;
-            if quad.iter().any(|v: &Vertex| v.layer != quad[0].layer) {
+            if quad
+                .iter()
+                .any(|v: &TerrainVertex| v.layer != quad[0].layer)
+            {
                return Err("quad mixes sprite layers".into());
            }
            let vertices: Vec<Value> = quad
@@ -17,6 +17,7 @@ fn keys(mask: u64) -> Keys {
        jump: mask & 16 != 0,
        shift: mask & 32 != 0,
        sprint: mask & 64 != 0,
+        analog: None,
    }
 }
 fn main() -> Result<()> {
@@ -0,0 +1,143 @@
+//! Resident-key synchronization used by Game (registration callback work excluded).
+//! Run: CARGO_INCREMENTAL=0 cargo run -p horizon-client --profile fast --example tick_chunk_membership_bench
+use horizon_client::{
+    chunk::Chunk, chunk_map::ChunkMap, tick_chunk_membership::TickChunkMembership,
+};
+use std::{collections::HashSet, hint::black_box, sync::Arc, time::Instant};
+
+type Key = (i32, i32);
+#[derive(Default)]
+struct Old {
+    keys: HashSet<Key>,
+}
+impl Old {
+    fn sync(&mut self, map: &ChunkMap) -> (usize, usize) {
+        let loaded: HashSet<_> = map.keys().copied().collect();
+        let mut counts = (0, 0);
+        for key in loaded.difference(&self.keys.clone()) {
+            black_box(key);
+            counts.0 += 1;
+        }
+        for key in self.keys.difference(&loaded) {
+            black_box(key);
+            counts.1 += 1;
+        }
+        self.keys = loaded;
+        counts
+    }
+}
+fn new_sync(cache: &mut TickChunkMembership, map: &ChunkMap) -> (usize, usize) {
+    if !cache.synchronize(map) {
+        return (0, 0);
+    }
+    let added = cache.take_added();
+    for key in &added {
+        black_box(key);
+    }
+    for key in cache.removed() {
+        black_box(key);
+    }
+    let counts = (added.len(), cache.removed().len());
+    cache.recycle_added(added);
+    counts
+}
+fn map(offset: i32) -> ChunkMap {
+    let mut map = ChunkMap::default();
+    // Share a payload: the synchronization path reads only keys, not block data.
+    let chunk = Arc::new(Chunk::empty(0, 0));
+    for x in -16..=16 {
+        for z in -16..=16 {
+            map.insert((x + offset, z), chunk.clone());
+        }
+    }
+    map
+}
+fn run(new: bool, scenario: usize, iterations: usize) -> (f64, (usize, usize)) {
+    let mut a = map(0);
+    let b = map(33);
+    let chunk = Arc::new(Chunk::empty(0, 0));
+    let mut old = Old::default();
+    let mut cache = TickChunkMembership::default();
+    for _ in 0..64 {
+        if new {
+            black_box(new_sync(&mut cache, &a));
+        } else {
+            black_box(old.sync(&a));
+        }
+    }
+    let mut total = (0, 0);
+    let start = Instant::now();
+    for i in 0..iterations {
+        let resident = match scenario {
+            0 => &a,
+            1 => {
+                let (previous, next) = if i % 2 == 0 {
+                    ((-16, -16), (-17, -16))
+                } else {
+                    ((-17, -16), (-16, -16))
+                };
+                a.remove(&previous);
+                a.insert(next, chunk.clone());
+                &a
+            }
+            2 => {
+                if i % 2 == 0 {
+                    &b
+                } else {
+                    &a
+                }
+            }
+            _ => unreachable!(),
+        };
+        let counts = if new {
+            new_sync(black_box(&mut cache), black_box(resident))
+        } else {
+            old.sync(black_box(resident))
+        };
+        total.0 += counts.0;
+        total.1 += counts.1;
+    }
+    (
+        start.elapsed().as_secs_f64() * 1e9 / iterations as f64,
+        black_box(total),
+    )
+}
+fn main() {
+    println!("1089 keys, 64 warmup calls, 9 samples; ns/sync, median");
+    for (scenario, name, iterations) in [
+        (0, "stable", 10_000),
+        (1, "one-key same-count replacement", 2_000),
+        (2, "whole-map replacement", 1_000),
+    ] {
+        let mut before = Vec::new();
+        let mut after = Vec::new();
+        for sample in 0..9 {
+            let (old, new) = if sample % 2 == 0 {
+                (
+                    run(false, scenario, iterations),
+                    run(true, scenario, iterations),
+                )
+            } else {
+                let new = run(true, scenario, iterations);
+                (run(false, scenario, iterations), new)
+            };
+            assert_eq!(old.1, new.1);
+            let expected = match scenario {
+                0 => (0, 0),
+                1 => (iterations, iterations),
+                _ => (1089 * iterations, 1089 * iterations),
+            };
+            assert_eq!(new.1, expected);
+            before.push(old.0);
+            after.push(new.0);
+        }
+        before.sort_by(f64::total_cmp);
+        after.sort_by(f64::total_cmp);
+        println!(
+            "{name}: {:.1} -> {:.1} ns, {:.2}x; {iterations} iterations/sample",
+            before[4],
+            after[4],
+            before[4] / after[4]
+        );
+    }
+}
@@ -0,0 +1,548 @@
+//! Trading for tools/test_trading_parity.py: runs each case of INPUT as
+//! VanillaTradingOracle does (offer generation, special prices, restocks,
+//! the merchant menu, NBT) and prints the same lines.
+//!
+//! usage: trading_fixture RESOURCES INPUT VANILLA_OUTPUT OUTPUT
+use horizon_client::{
+    enchant::Enchantments,
+    entity_nbt,
+    gossip::{GossipType, Gossips},
+    items::{ItemStack, Items},
+    menu::{Env, Input, Kind, Menu},
+    merchant::{self, Event, MerchantOffer, Session, TradeContext, TradeEnv, Trader, Trades},
+    random_sequences::RandomSequences,
+};
+use horizon_core::random::{LegacyRandom, RandomSource};
+use horizon_world::nbt::Tag;
+use std::{collections::HashMap, fmt::Write as _, fs, path::Path};
+
+const PLAYER: [i32; 4] = [0, 0x1234, 0, 0x5678];
+
+/// Canonical NBT text, as VanillaTradingOracle prints it.
+fn canon(t: &Tag, out: &mut String) {
+    match t {
+        Tag::Compound(c) => {
+            out.push('{');
+            let mut keys: Vec<String> = c.keys().map(|k| k.to_string_lossy()).collect();
+            keys.sort_by(|a, b| a.encode_utf16().cmp(b.encode_utf16()));
+            for (i, k) in keys.iter().enumerate() {
+                if i > 0 {
+                    out.push(',');
+                }
+                quote(k, out);
+                out.push(':');
+                canon(t.get(k).expect("key"), out);
+            }
+            out.push('}');
+        }
+        Tag::List(l) => {
+            out.push('[');
+            for (i, v) in l.iter().enumerate() {
+                if i > 0 {
+                    out.push(',');
+                }
+                canon(v, out);
+            }
+            out.push(']');
+        }
+        Tag::String(s) => quote(&s.to_string_lossy(), out),
+        Tag::Byte(v) => write!(out, "{v}b").unwrap(),
+        Tag::Short(v) => write!(out, "{v}s").unwrap(),
+        Tag::Int(v) => write!(out, "{v}").unwrap(),
+        Tag::Long(v) => write!(out, "{v}L").unwrap(),
+        Tag::Float(v) => write!(out, "f:{v:x}").unwrap(),
+        Tag::Double(v) => write!(out, "d:{v:x}").unwrap(),
+        Tag::ByteArray(v) => {
+            out.push_str("[B;");
+            let s: Vec<String> = v.iter().map(|b| (*b as i8).to_string()).collect();
+            out.push_str(&s.join(","));
+            out.push(']');
+        }
+        Tag::IntArray(v) => {
+            out.push_str("[I;");
+            let s: Vec<String> = v.iter().map(i32::to_string).collect();
+            out.push_str(&s.join(","));
+            out.push(']');
+        }
+        Tag::LongArray(v) => {
+            out.push_str("[L;");
+            let s: Vec<String> = v.iter().map(i64::to_string).collect();
+            out.push_str(&s.join(","));
+            out.push(']');
+        }
+        Tag::End => out.push_str("?End"),
+    }
+}
+fn quote(s: &str, out: &mut String) {
+    out.push('"');
+    for c in s.chars() {
+        if c == '"' || c == '\\' {
+            out.push('\\');
+        }
+        out.push(c);
+    }
+    out.push('"');
+}
+fn canon_str(t: &Tag) -> String {
+    let mut s = String::new();
+    canon(t, &mut s);
+    s
+}
+fn stack(s: Option<&ItemStack>) -> String {
+    match s {
+        None => "-".into(),
+        Some(s) => canon_str(&horizon_client::save::item_to_nbt(s)),
+    }
+}
+
+struct World<'a> {
+    items: &'a Items,
+    enchantments: &'a Enchantments,
+    trades: &'a Trades,
+    sequences: RandomSequences,
+    seed: i64,
+}
+/// A merchant from PROF:TYPE:LEVEL or "wt", generated level by level.
+struct Merchant {
+    villager: bool,
+    profession: String,
+    variant: String,
+    level: i32,
+    trader: Trader,
+}
+impl World<'_> {
+    fn reset(&mut self, seed: i64) {
+        self.sequences = RandomSequences::default();
+        self.seed = seed;
+    }
+    fn add_set(
+        &mut self,
+        offers: &mut Vec<MerchantOffer>,
+        set: &str,
+        variant: &str,
+        origin: [f64; 3],
+    ) {
+        let Some(sequence) = self.trades.sequence(set) else {
+            return;
+        };
+        let ctx = TradeContext {
+            items: self.items,
+            enchantments: self.enchantments,
+            variant,
+            origin,
+            maps: None,
+        };
+        let random = self.sequences.get(&sequence, self.seed);
+        offers.extend(self.trades.offers_from_set(&ctx, set, random));
+    }
+    fn merchant(&mut self, spec: &str, origin: [f64; 3]) -> Merchant {
+        let mut offers = Vec::new();
+        if spec == "wt" {
+            for set in ["buying", "uncommon", "common"] {
+                self.add_set(
+                    &mut offers,
+                    &format!("minecraft:wandering_trader/{set}"),
+                    "minecraft:plains",
+                    origin,
+                );
+            }
+            return Merchant {
+                villager: false,
+                profession: "minecraft:wandering_trader".into(),
+                variant: "minecraft:plains".into(),
+                level: 1,
+                trader: Trader {
+                    offers,
+                    ..Default::default()
+                },
+            };
+        }
+        let p: Vec<&str> = spec.split(':').collect();
+        let (profession, variant) = (format!("minecraft:{}", p[0]), format!("minecraft:{}", p[1]));
+        let max: i32 = p[2].parse().unwrap_or(1);
+        for level in 1..=max {
+            let set = Trades::set_for(&profession, level);
+            if self.trades.sets.contains_key(&set) {
+                self.add_set(&mut offers, &set, &variant, origin);
+            }
+        }
+        Merchant {
+            villager: true,
+            profession,
+            variant,
+            level: max,
+            trader: Trader {
+                offers,
+                ..Default::default()
+            },
+        }
+    }
+}
+
+fn kv(fields: &[&str]) -> HashMap<String, String> {
+    let mut m: HashMap<String, String> = HashMap::new();
+    for f in &fields[2..] {
+        if let Some((k, v)) = f.split_once('=') {
+            m.entry(k.to_owned())
+                .and_modify(|e| {
+                    e.push(' ');
+                    e.push_str(v);
+                })
+                .or_insert_with(|| v.to_owned());
+        }
+    }
+    m
+}
+
+/// Uses, demand, gossip, xp and restock state, as the oracle's `prepare`.
+fn prepare(m: &mut Merchant, gossips: &mut Gossips, kv: &HashMap<String, String>) {
+    for key in ["uses", "demand"] {
+        let Some(list) = kv.get(key) else { continue };
+        for s in list.split(' ') {
+            let mut f = s.split(':');
+            let i: usize = f.next().and_then(|v| v.parse().ok()).unwrap_or(0);
+            let n: i32 = f.next().and_then(|v| v.parse().ok()).unwrap_or(0);
+            let Some(o) = m.trader.offers.get_mut(i) else {
+                continue;
+            };
+            if key == "uses" {
+                o.uses += n;
+            } else {
+                o.demand = n;
+            }
+        }
+    }
+    if let Some(list) = kv.get("gossip") {
+        for s in list.split(' ') {
+            let (kind, n) = s.split_once(':').unwrap_or((s, "0"));
+            if let Some(kind) = GossipType::from_id(kind) {
+                gossips.add(PLAYER, kind, n.parse().unwrap_or(0));
+            }
+        }
+    }
+    if let Some(xp) = kv.get("xp") {
+        m.trader.xp = xp.parse().unwrap_or(0);
+    }
+    if let Some(v) = kv.get("lastrestock") {
+        m.trader.last_restock = v.parse().unwrap_or(0);
+    }
+    if let Some(v) = kv.get("restocks") {
+        m.trader.restocks_today = v.parse().unwrap_or(0);
+    }
+}
+
+fn main() -> horizon_client::Result<()> {
+    let args: Vec<String> = std::env::args().collect();
+    let usage = "usage: trading_fixture RESOURCES INPUT VANILLA_OUTPUT OUTPUT";
+    let root = Path::new(args.get(1).ok_or(usage)?);
+    let input = fs::read_to_string(args.get(2).ok_or(usage)?)?;
+    let vanilla = fs::read_to_string(args.get(3).ok_or(usage)?)?;
+    let items = Items::catalog(root)?;
+    let enchantments = Enchantments::load(root);
+    let trades = Trades::load(root);
+    let recipes = horizon_client::crafting::Recipes::load(root, &items)?;
+    let brewing = horizon_client::brewing::Brewing::load(root, &items);
+    let banners = horizon_client::banner::Banners::load(root);
+    let types: HashMap<_, _> = horizon_client::mobs::MobTypes::load(root)?
+        .types
+        .into_iter()
+        .map(|(k, v)| (k, std::sync::Arc::new(v)))
+        .collect();
+    // The vanilla villagers the nbt cases read.
+    let snbt: HashMap<&str, &str> = vanilla
+        .lines()
+        .filter_map(|l| {
+            let (name, rest) = l.split_once(' ')?;
+            Some((name, rest.strip_prefix("snbt ")?))
+        })
+        .collect();
+    let mut world = World {
+        items: &items,
+        enchantments: &enchantments,
+        trades: &trades,
+        sequences: RandomSequences::default(),
+        seed: 0,
+    };
+    let mut out = String::new();
+    for line in input.lines().filter(|l| !l.trim().is_empty()) {
+        let fields: Vec<&str> = line.split(' ').collect();
+        let (kind, name) = (fields[0], fields[1]);
+        let kv = kv(&fields);
+        let seed: i64 = kv.get("seed").and_then(|s| s.parse().ok()).unwrap_or(0);
+        world.reset(seed);
+        let origin = [0.5, -60.0, 0.5];
+        match kind {
+            "gen" => {
+                let specs: Vec<String> = kv["v"].split(' ').map(str::to_owned).collect();
+                for (k, spec) in specs.iter().enumerate() {
+                    let m = world.merchant(spec, origin);
+                    writeln!(
+                        out,
+                        "{name} v{k} {}",
+                        canon_str(&entity_nbt::offers_to_nbt(&m.trader.offers))
+                    )?;
+                }
+                let mut line = format!("{name} draws");
+                for id in trades.sequences() {
+                    write!(line, " {}", world.sequences.get(&id, seed).next_int())?;
+                }
+                writeln!(out, "{line}")?;
+            }
+            "price" => {
+                let mut m = world.merchant(&kv["v"], origin);
+                let mut gossips = Gossips::default();
+                prepare(&mut m, &mut gossips, &kv);
+                let hero = kv.get("hero").and_then(|h| h.parse().ok());
+                let rep = gossips.reputation(PLAYER);
+                merchant::update_special_prices(&mut m.trader.offers, rep, hero);
+                let mut line = format!("{name} rep {rep}");
+                for o in &m.trader.offers {
+                    write!(line, " {}/{}", o.cost_a_count(&items), o.special_price_diff)?;
+                }
+                writeln!(out, "{line}")?;
+            }
+            "restock" => {
+                let mut m = world.merchant(&kv["v"], origin);
+                let mut gossips = Gossips::default();
+                prepare(&mut m, &mut gossips, &kv);
+                let steps = kv.get("steps").cloned().unwrap_or_default();
+                for (k, s) in steps.split(',').filter(|s| !s.is_empty()).enumerate() {
+                    let f: Vec<&str> = s.split(':').collect();
+                    let mut line = format!("{name} {k} {s}");
+                    match f[0] {
+                        "use" => {
+                            let i: usize = f[1].parse().unwrap_or(0);
+                            if let Some(o) = m.trader.offers.get_mut(i) {
+                                o.uses += f[2].parse::<i32>().unwrap_or(0);
+                            }
+                        }
+                        "check" => {
+                            let time: i64 = f[1].parse().unwrap_or(0);
+                            let day: i64 = f[2].parse().unwrap_or(0);
+                            let should = m.trader.should_restock(time, day);
+                            if should {
+                                m.trader.restock(time);
+                            }
+                            write!(line, " {should}")?;
+                        }
+                        _ => {}
+                    }
+                    write!(
+                        line,
+                        " lr {} rt {} cd {}",
+                        m.trader.last_restock, m.trader.restocks_today, m.trader.check_day
+                    )?;
+                    for o in &m.trader.offers {
+                        write!(line, " {}/{}", o.uses, o.demand)?;
+                    }
+                    writeln!(out, "{line}")?;
+                }
+            }
+            "nbt" => {
+                let text = snbt.get(name).ok_or("missing vanilla snbt")?;
+                let (tag, _) = horizon_world::nbt::parse_snbt(text)?;
+                let id = if kv["v"] == "wt" {
+                    "minecraft:wandering_trader"
+                } else {
+                    "minecraft:villager"
+                };
+                let mut tag = tag;
+                if let Tag::Compound(c) = &mut tag {
+                    c.insert("id".into(), Tag::String(id.into()));
+                }
+                let mob = entity_nbt::mob_from_nbt(&tag, &types, 1).ok_or("unreadable villager")?;
+                let back = entity_nbt::mob_to_nbt(&mob, [0; 4], None);
+                writeln!(out, "{name} snbt {text}")?;
+                let mut kept = horizon_world::nbt::Compound::new();
+                for key in [
+                    "Offers",
+                    "Xp",
+                    "LastRestock",
+                    "RestocksToday",
+                    "VillagerData",
+                ] {
+                    if let Some(v) = back.get(key) {
+                        kept.insert(key.into(), v.clone());
+                    }
+                }
+                writeln!(out, "{name} canon {}", canon_str(&Tag::Compound(kept)))?;
+            }
+            "trade" => {
+                let env_trade = TradeEnv {
+                    trades: &trades,
+                    enchantments: &enchantments,
+                    maps: None,
+                };
+                let env = Env {
+                    items: &items,
+                    recipes: &recipes,
+                    brewing: &brewing,
+                    banners: &banners,
+                    trade: Some(&env_trade),
+                };
+                trade(&mut out, name, &kv, &mut world, &env, origin)?;
+            }
+            _ => return Err(format!("unknown case {kind}").into()),
+        }
+    }
+    fs::write(args.get(4).ok_or(usage)?, out)?;
+    Ok(())
+}
+
+fn trade(
+    out: &mut String,
+    name: &str,
+    kv: &HashMap<String, String>,
+    world: &mut World,
+    env: &Env,
+    origin: [f64; 3],
+) -> horizon_client::Result<()> {
+    let vseed: i64 = kv.get("vseed").and_then(|s| s.parse().ok()).unwrap_or(0);
+    let mut m = world.merchant(&kv["v"], origin);
+    let mut gossips = Gossips::default();
+    if m.villager {
+        prepare(&mut m, &mut gossips, kv);
+    }
+    let hero: Option<i32> = kv.get("hero").and_then(|h| h.parse().ok());
+    let mut menu = Menu::new(Kind::Merchant);
+    if let Some(inv) = kv.get("inv") {
+        for s in inv.split(',') {
+            let (slot, rest) = s.split_once(':').ok_or("inv")?;
+            let (item, count) = rest.rsplit_once('*').ok_or("inv")?;
+            let item = if item.contains(':') {
+                item.to_owned()
+            } else {
+                format!("minecraft:{item}")
+            };
+            menu.set_player_item(slot.parse()?, Some(ItemStack::new(&item, count.parse()?)));
+        }
+    }
+    menu.selected = kv.get("hand").and_then(|h| h.parse().ok()).unwrap_or(8);
+    // Villager.mobInteract / WanderingTrader.mobInteract.
+    let open = !m.trader.offers.is_empty();
+    let unhappy = if m.villager && !open { 40 } else { 0 };
+    let mut voice = LegacyRandom::new(vseed);
+    if unhappy > 0 {
+        // setUnhappy: makeSound(VILLAGER_NO) draws the voice pitch.
+        voice.next_float();
+        voice.next_float();
+    }
+    writeln!(out, "{name} open {open} unhappy {unhappy}")?;
+    let mut session = Session::new(m.trader.offers.clone(), m.villager);
+    session.xp = m.trader.xp;
+    session.level = m.level;
+    session.profession = m.profession.clone();
+    session.variant = m.variant.clone();
+    session.random = voice.clone();
+    session.origin = origin;
+    session.reputation = gossips.reputation(PLAYER);
+    session.hero = hero;
+    for id in Session::sequences_needed(world.trades, &m.profession, m.level) {
+        let r = world.sequences.lend(&id, world.seed);
+        session.sequences.insert(id, r);
+    }
+    session.update_special_prices();
+    let mut regen = false;
+    let mut open_menu = open;
+    if open_menu {
+        menu.merchant = Some(Box::new(session));
+    }
+    let steps = kv.get("steps").cloned().unwrap_or_default();
+    let mut session_after: Option<Box<Session>> = None;
+    for (k, s) in steps.split(',').filter(|s| !s.is_empty()).enumerate() {
+        let f: Vec<&str> = s.split(':').collect();
+        match f[0] {
+            "select" if open_menu => menu.merchant_select(env, f[1].parse().unwrap_or(0)),
+            "click" if open_menu => {
+                let input = Input::parse(&f[3].to_uppercase()).ok_or("input")?;
+                let _ = menu.click(env, f[1].parse()?, f[2].parse()?, input);
+            }
+            "tick" => {
+                let sess = menu.merchant.as_mut().or(session_after.as_mut());
+                if let Some(sess) = sess
+                    && sess.villager
+                    && sess.last_traded
+                {
+                    sess.last_traded = false;
+                    gossips.add(PLAYER, GossipType::Trading, 2);
+                    sess.reputation = gossips.reputation(PLAYER);
+                    if open_menu {
+                        sess.update_special_prices();
+                        menu.merchant_update(env);
+                    }
+                }
+            }
+            "close" if open_menu => {
+                menu.merchant_close(env);
+                open_menu = false;
+                session_after = Some(menu.merchant.take().ok_or("session")?);
+            }
+            _ => {}
+        }
+        let mut line = format!("{name} {k} {s} menu {open_menu}");
+        if open_menu {
+            for i in 0..3 {
+                write!(line, " {}", stack(menu.slot(i)))?;
+            }
+            write!(
+                line,
+                " fxp {}",
+                menu.merchant.as_ref().map_or(0, |s| s.future_xp)
+            )?;
+        }
+        write!(line, " carried {}", stack(menu.carried.as_ref()))?;
+        line.push_str(" inv");
+        for i in 0..36 {
+            if let Some(st) = menu.player_item(i) {
+                write!(line, " {i}={}", stack(Some(st)))?;
+            }
+        }
+        let sess = menu
+            .merchant
+            .as_deref_mut()
+            .or(session_after.as_deref_mut());
+        let (xp, level, offers, orbs) = match sess {
+            Some(sess) => {
+                let mut orbs = Vec::new();
+                for e in sess.events.drain(..) {
+                    match e {
+                        Event::Orb(v) => orbs.push(v),
+                        Event::LevelUp(_) => regen = true,
+                        _ => {}
+                    }
+                }
+                (sess.xp, sess.level, sess.offers.clone(), orbs)
+            }
+            None => (m.trader.xp, m.level, m.trader.offers.clone(), Vec::new()),
+        };
+        write!(line, " xp {xp}")?;
+        if m.villager {
+            write!(
+                line,
+                " lvl {level} rep {} regen {regen}",
+                gossips.reputation(PLAYER)
+            )?;
+        }
+        line.push_str(" offers");
+        for o in &offers {
+            write!(
+                line,
+                " {}/{}/{}",
+                o.uses,
+                o.special_price_diff,
+                o.cost_a_count(env.items)
+            )?;
+        }
+        line.push_str(" orbs");
+        for v in orbs {
+            write!(line, " {v}")?;
+        }
+        writeln!(out, "{line}")?;
+    }
+    let random = match menu.merchant.as_mut().or(session_after.as_mut()) {
+        Some(s) => s.random.next_int(),
+        None => voice.next_int(),
+    };
+    writeln!(out, "{name} next {random}")?;
+    Ok(())
+}
@@ -0,0 +1,59 @@
+//! WeatherEffectRenderer column instances and quads, without a GPU.
+use horizon_client::weather;
+use std::{fmt::Write, fs};
+fn bits(value: f32) -> String {
+    if value.is_nan() {
+        "nan".into()
+    } else {
+        format!("{:x}", value.to_bits())
+    }
+}
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let args: Vec<_> = std::env::args().collect();
+    let mut output = String::new();
+    for (case, line) in fs::read_to_string(&args[1])?.lines().enumerate() {
+        let p: Vec<&str> = line.split_whitespace().collect();
+        let int = |i: usize| p[i].parse::<i32>().unwrap();
+        let kind = int(0);
+        let ticks: i64 = p[1].parse()?;
+        let (x, bottom, top, z, light) = (int(2), int(3), int(4), int(5), int(6));
+        let partial: f32 = p[7].parse()?;
+        let camera = [p[8].parse()?, p[9].parse()?, p[10].parse()?];
+        let radius = int(11);
+        let intensity: f32 = p[12].parse()?;
+        let mut random = weather::column_random(x, z);
+        let column = if kind == 0 {
+            weather::rain_column(&mut random, ticks, x, bottom, top, z, light, partial)
+        } else {
+            weather::snow_column(&mut random, ticks, x, bottom, top, z, light, partial)
+        };
+        write!(
+            output,
+            "{case} {} {} {} {} {} {} {}",
+            column.x,
+            column.z,
+            column.bottom_y,
+            column.top_y,
+            bits(column.u_offset),
+            bits(column.v_offset),
+            column.light_coords
+        )?;
+        let max_alpha = if kind == 0 { 1.0 } else { 0.8 };
+        for v in weather::column_quad(&column, camera, max_alpha, radius, intensity) {
+            write!(
+                output,
+                " |{},{},{},{},{},{:x},{}",
+                bits(v.pos[0]),
+                bits(v.pos[1]),
+                bits(v.pos[2]),
+                bits(v.uv[0]),
+                bits(v.uv[1]),
+                v.color,
+                v.light_coords
+            )?;
+        }
+        output.push('\n');
+    }
+    fs::write(&args[2], output)?;
+    Ok(())
+}
@@ -294,6 +294,8 @@ pub struct EntityView {
    pub struck: Vec<EntityView>,
    pub fishing_open_water: Option<bool>,
    pub variant: Option<String>,
+    /// The data components the entity reports (`Entity.get`): id and value.
+    pub components: Vec<(String, String)>,
 }
 fn range_f(v: &Value, x: f64) -> bool {
    match v {
@@ -310,7 +312,7 @@ fn range_i(v: &Value, x: i64) -> bool {
    range_f(v, x as f64)
 }
 /// A registry id, `#tag`, or list matched against one id.
-fn id_matches(v: &Value, registry: &str, id: &str, w: &dyn World) -> bool {
+pub fn id_matches(v: &Value, registry: &str, id: &str, w: &dyn World) -> bool {
    match v {
        Value::Null => true,
        Value::String(s) => match s.strip_prefix('#') {
@@ -442,6 +444,26 @@ pub fn location(v: &Value, p: [f64; 3], w: &dyn World) -> bool {
    }
    true
 }
+/// `DataComponentExactPredicate.test` on an entity: every expected
+/// component equals what the entity reports (absent ones never match).
+fn components(expected: &Value, have: &[(String, String)]) -> bool {
+    let full = |id: &str| {
+        if id.contains(':') {
+            id.to_owned()
+        } else {
+            format!("minecraft:{id}")
+        }
+    };
+    expected.as_object().is_some_and(|o| {
+        o.iter().all(|(id, want)| {
+            let id = full(id);
+            want.as_str().is_some_and(|want| {
+                have.iter()
+                    .any(|(k, v)| full(k) == id && full(v) == full(want))
+            })
+        })
+    })
+}
 /// `EntityPredicate` (26.x keyed sub-predicates).
 pub fn entity(v: &Value, e: &EntityView, w: &dyn World, origin: [f64; 3]) -> bool {
    if v.is_null() {
@@ -521,7 +543,8 @@ pub fn entity(v: &Value, e: &EntityView, w: &dyn World, origin: [f64; 3]) -> boo
            "minecraft:type_specific/fishing_hook" => p["in_open_water"]
                .as_bool()
                .is_none_or(|want| e.fishing_open_water == Some(want)),
-            "minecraft:components" | "minecraft:predicates" => true,
+            "minecraft:components" => components(p, &e.components),
+            "minecraft:predicates" => true,
            _ => false,
        };
        if !ok {
@@ -571,6 +594,7 @@ pub fn conditions(v: &Value, ctx: &Entities, w: &dyn World) -> bool {
                        w,
                    )
                }
+                "minecraft:match_block" => ctx.block_pos.is_some_and(|b| block(v, b, w)),
                "minecraft:block_state_property" => ctx.block_pos.is_some_and(|b| {
                    let mut pred = serde_json::Map::new();
                    pred.insert("blocks".into(), v["block"].clone());
@@ -929,6 +953,24 @@ mod tests {
        }
    }
    #[test]
+    fn bucket_axolotl_block_advancements_require_the_placed_block() {
+        let ctx = Entities {
+            this: None,
+            origin: [0.0; 3],
+            tool: None,
+            block_pos: Some([0; 3]),
+        };
+        let stone = serde_json::json!({"type":"minecraft:match_block","blocks":"minecraft:stone"});
+        let wheat = serde_json::json!({"type":"minecraft:match_block","blocks":"minecraft:wheat"});
+        assert!(conditions(&stone, &ctx, &Flat));
+        assert!(!conditions(&wheat, &ctx, &Flat));
+        let absent = Entities {
+            block_pos: None,
+            ..ctx
+        };
+        assert!(!conditions(&stone, &absent, &Flat));
+    }
+    #[test]
    fn predicates_match_tags_ranges_and_locations() {
        let w = Flat;
        let stone = ItemView {
@@ -9,7 +9,7 @@ use horizon_world::{
 use serde_json::Value;
 use std::{
    collections::BTreeSet,
-    fs::File,
+    fs::{self, File},
    io::{self, BufReader},
    path::Path,
    sync::Arc,
@@ -55,6 +55,7 @@ pub struct Assets {
    pub properties: Properties,
    pub material_states: [BlockStateId; 6],
    pub sprite_size: u32,
+    pub sprite_minimum_size: u32,
    pub pixels: Vec<u8>,
    pub texture_layers: u32,
    pub model_catalog: crate::models::StateModels,
@@ -63,6 +64,8 @@ pub struct Assets {
    pub animations: Vec<crate::sprites::SpriteAnimation>,
    pub sprite_layers: std::collections::BTreeMap<String, u32>,
    pub translucent_layers: Vec<bool>,
+    /// Each layer's `MipmapGenerator` settings.
+    pub sprite_mips: Vec<crate::mipmap::Settings>,
    /// Block names in `#minecraft:blocks_fluid_flow` (fluid flow vectors).
    pub blocks_fluid_flow: BTreeSet<String>,
 }
@@ -95,8 +98,7 @@ impl Assets {
        if manifest["data_version"].as_i64() != Some(i64::from(DATA_VERSION)) {
            return Err(invalid("resources do not match Horizon's pinned data version").into());
        }
-        let facts: Value =
-            serde_json::from_reader(BufReader::new(File::open(root.join("facts.json"))?))?;
+        let facts: Value = serde_json::from_slice(&fs::read(root.join("facts.json"))?)?;
        let states = facts["states"]
            .as_array()
            .ok_or_else(|| invalid("missing registry state facts"))?;
@@ -180,15 +182,43 @@ impl Assets {
                .collect::<Result<_>>()?,
        ));
        let mut material_states = [BlockStateId(0); 6];
-        let mut sprites = crate::sprites::Sprites::default();
        for (layer, name) in MATERIALS.iter().enumerate() {
-            let state = registry
+            material_states[layer] = registry
                .default_state(&format!("minecraft:{name}"))
                .ok_or_else(|| invalid("missing test-scene material"))?;
-            material_states[layer] = state;
-            sprites.insert(root, &format!("minecraft:block/{name}"))?;
        }
        let registry: &'static BlockRegistry = Box::leak(Box::new(registry));
+        Self::with_models(
+            root,
+            registry,
+            properties,
+            material_states,
+            blocks_fluid_flow,
+        )
+    }
+    /// The same blocks with the models and sprites of another resource root
+    /// (resource packs changed): the registry and block facts come from the
+    /// game data, which resource packs do not touch.
+    pub fn reload(&self, root: &Path) -> Result<Self> {
+        Self::with_models(
+            root,
+            self.registry,
+            self.properties.clone(),
+            self.material_states,
+            self.blocks_fluid_flow.clone(),
+        )
+    }
+    fn with_models(
+        root: &Path,
+        registry: &'static BlockRegistry,
+        properties: Properties,
+        material_states: [BlockStateId; 6],
+        blocks_fluid_flow: BTreeSet<String>,
+    ) -> Result<Self> {
+        let mut sprites = crate::sprites::Sprites::default();
+        for name in MATERIALS {
+            sprites.insert(root, &format!("minecraft:block/{name}"))?;
+        }
        let models = crate::models::prepare(root, registry, &mut sprites)?;
        // Fluids are drawn by the fluid renderer, not block models; breaking
        // progress uses the destroy-stage overlays.
@@ -204,11 +234,13 @@ impl Assets {
        for stage in 0..10 {
            sprites.insert(root, &format!("minecraft:block/destroy_stage_{stage}"))?;
        }
+        sprites.finish();
        Ok(Self {
            registry,
            properties,
            material_states,
            sprite_size: sprites.size,
+            sprite_minimum_size: sprites.minimum_size,
            texture_layers: u32::try_from(sprites.layers.len())?,
            pixels: sprites.pixels,
            model_catalog: models.catalog,
@@ -217,6 +249,7 @@ impl Assets {
            animations: sprites.animations,
            sprite_layers: sprites.layers,
            translucent_layers: sprites.translucent,
+            sprite_mips: sprites.mips,
            blocks_fluid_flow,
        })
    }
@@ -61,10 +61,78 @@ pub struct Heard {
 pub struct MixerBackend {
    mixer: Arc<Mutex<Mixer>>,
    root: PathBuf,
-    cache: HashMap<String, Option<(Arc<Vec<f32>>, u32)>>,
+    cache: Arc<Mutex<SoundCache>>,
+    /// The decoder thread for static sounds, started with the first one.
+    decoder: Option<std::sync::mpsc::Sender<Decode>>,
    next: ChannelId,
    live: bool,
 }
+/// Decoded samples and their rate (`None`: the file did not load).
+type Samples = Option<(Arc<Vec<f32>>, u32)>;
+/// Decoded static sounds (`SoundBufferLibrary`'s buffers), dropped least
+/// recently used first past `CACHE_BYTES`: kept forever, every sound heard in
+/// a session stayed (up to 1.4 GiB of samples, villages playing hundreds).
+#[derive(Default)]
+struct SoundCache {
+    entries: HashMap<String, (Samples, u64)>,
+    bytes: usize,
+    clock: u64,
+}
+const CACHE_BYTES: usize = 64 << 20;
+impl SoundCache {
+    fn get(&mut self, key: &str) -> Option<Samples> {
+        self.clock += 1;
+        let entry = self.entries.get_mut(key)?;
+        entry.1 = self.clock;
+        Some(entry.0.clone())
+    }
+    fn insert(&mut self, key: String, samples: Samples) {
+        self.clock += 1;
+        self.bytes += Self::size(&samples);
+        if let Some((old, _)) = self.entries.insert(key, (samples, self.clock)) {
+            self.bytes -= Self::size(&old);
+        }
+        while self.bytes > CACHE_BYTES && self.entries.len() > 1 {
+            let Some(oldest) = self
+                .entries
+                .iter()
+                .min_by_key(|(_, (_, used))| *used)
+                .map(|(k, _)| k.clone())
+            else {
+                break;
+            };
+            if let Some((gone, _)) = self.entries.remove(&oldest) {
+                self.bytes -= Self::size(&gone);
+            }
+        }
+    }
+    fn size(samples: &Samples) -> usize {
+        samples
+            .as_ref()
+            .map_or(0, |(s, _)| s.len() * std::mem::size_of::<f32>())
+    }
+}
+/// A static sound to decode for a channel waiting on it.
+struct Decode {
+    key: String,
+    file: PathBuf,
+    channel: ChannelId,
+}
+/// Give a channel waiting on its sound the decoded samples and start it, as
+/// the buffer future attaching and playing the source. A source stopped or
+/// released meanwhile stays so.
+fn attach(mixer: &Mutex<Mixer>, channel: ChannelId, samples: Samples, looping: bool) {
+    if let Some(samples) = samples
+        && let Ok(mut m) = mixer.lock()
+        && let Some(c) = m.channels.get_mut(&channel)
+        && c.state == State::Initial
+    {
+        c.samples = Some(samples);
+        c.position = 0.0;
+        c.state = State::Playing;
+        c.looping |= looping;
+    }
+}
 pub struct Audio {
    _stream: Option<cpal::Stream>,
    pub engine: SoundEngine,
@@ -176,53 +244,59 @@ impl Backend for MixerBackend {
    fn set_relative(&mut self, channel: ChannelId, relative: bool) {
        self.with(channel, |c| c.relative = relative);
    }
-    /// `getCompleteBuffer` (decoded now, cached) or `getStream` (decoded on a
-    /// worker), then attach and `alSourcePlay`. A sound that cannot load
-    /// leaves its source initial, as a failed buffer future does in vanilla.
+    /// `getCompleteBuffer` (cached, else decoded on the decoder thread) or
+    /// `getStream` (decoded on a thread of its own), then attach and
+    /// `alSourcePlay`. A sound that cannot load leaves its source initial,
+    /// as a failed buffer future does in vanilla.
    fn start(&mut self, channel: ChannelId, sound: &Sound, looping: bool) {
        if !self.live {
            return;
        }
        let (namespace, path) = sound.path();
        let file = self.root.join("assets").join(namespace).join(&path);
-        let attach = move |mixer: &Mutex<Mixer>, samples: Option<(Arc<Vec<f32>>, u32)>| {
-            if let Some(samples) = samples
-                && let Ok(mut m) = mixer.lock()
-                && let Some(c) = m.channels.get_mut(&channel)
-            {
-                c.samples = Some(samples);
-                c.position = 0.0;
-                c.state = State::Playing;
-            }
-        };
        if sound.stream {
            // A streamed sound loops by restarting its stream.
            let mixer = self.mixer.clone();
            std::thread::spawn(move || {
                let samples = decode(&file).map(|(s, r)| (Arc::new(s), r));
-                if looping
-                    && let Ok(mut m) = mixer.lock()
-                    && let Some(c) = m.channels.get_mut(&channel)
-                {
-                    c.looping = true;
-                }
-                attach(&mixer, samples);
+                attach(&mixer, channel, samples, looping);
            });
-        } else {
-            let samples = self
-                .cache
-                .entry(format!("{namespace}:{path}"))
-                .or_insert_with(|| decode(&file).map(|(s, r)| (Arc::new(s), r)))
-                .clone();
-            attach(&self.mixer, samples);
+            return;
        }
-    }
-    fn stop(&mut self, channel: ChannelId) {
-        self.with(channel, |c| {
-            if c.state != State::Initial {
-                c.state = State::Stopped;
-            }
+        let key = format!("{namespace}:{path}");
+        let cached = self.cache.lock().ok().and_then(|mut c| c.get(&key));
+        if let Some(samples) = cached {
+            attach(&self.mixer, channel, samples, false);
+            return;
+        }
+        let decoder = self.decoder.get_or_insert_with(|| {
+            let (send, receive) = std::sync::mpsc::channel::<Decode>();
+            let (mixer, cache) = (self.mixer.clone(), self.cache.clone());
+            std::thread::Builder::new()
+                .name("sound decoder".into())
+                .spawn(move || {
+                    for job in receive {
+                        // Queued twice before the first decode finished.
+                        let cached = cache.lock().ok().and_then(|mut c| c.get(&job.key));
+                        let samples = cached.unwrap_or_else(|| {
+                            let samples = decode(&job.file).map(|(s, r)| (Arc::new(s), r));
+                            if let Ok(mut c) = cache.lock() {
+                                c.insert(job.key, samples.clone());
+                            }
+                            samples
+                        });
+                        attach(&mixer, job.channel, samples, false);
+                    }
+                })
+                .expect("sound decoder thread");
+            send
        });
+        let _ = decoder.send(Decode { key, file, channel });
+    }
+    /// `alSourceStop`: any state becomes stopped, an initial source too (a
+    /// sound still decoding then never starts).
+    fn stop(&mut self, channel: ChannelId) {
+        self.with(channel, |c| c.state = State::Stopped);
    }
    fn pause(&mut self, channel: ChannelId) {
        self.with(channel, |c| {
@@ -327,6 +401,71 @@ fn mix(mixer: &mut Mixer, data: &mut [f32], channels: usize, rate: u32) {
        *s = s.clamp(-1.0, 1.0);
    }
 }
+/// Why the game should not open an output, if it should not:
+/// `HORIZON_NO_AUDIO`, or a virtual screen (`vscreen`), where agents and
+/// harnesses run the game and must stay off the user's speakers.
+/// `HORIZON_AUDIO=1` opens the output anyway (testing into a null sink).
+fn output_disabled(var: impl Fn(&str) -> Option<std::ffi::OsString>) -> Option<String> {
+    if var("HORIZON_NO_AUDIO").is_some() {
+        return Some("audio off: HORIZON_NO_AUDIO is set".into());
+    }
+    if var("HORIZON_AUDIO").is_some_and(|v| v == "1") {
+        return None;
+    }
+    let display = var("WAYLAND_DISPLAY")?;
+    Path::new(&display)
+        .components()
+        .any(|c| c.as_os_str() == "vscreen")
+        .then(|| "audio off on a virtual screen (vscreen); HORIZON_AUDIO=1 opens it".into())
+}
+/// An output stream on `device` in its default configuration, whatever its
+/// sample format: the mixer works in f32 and converts.
+fn open_device(
+    device: &cpal::Device,
+    mixer: Arc<Mutex<Mixer>>,
+) -> Result<(cpal::Stream, cpal::SupportedStreamConfig)> {
+    use cpal::SampleFormat as F;
+    let config = device.default_output_config()?;
+    let stream = match config.sample_format() {
+        F::F32 => build_stream::<f32>(device, &config, mixer),
+        F::F64 => build_stream::<f64>(device, &config, mixer),
+        F::I16 => build_stream::<i16>(device, &config, mixer),
+        F::I32 => build_stream::<i32>(device, &config, mixer),
+        F::I8 => build_stream::<i8>(device, &config, mixer),
+        F::U16 => build_stream::<u16>(device, &config, mixer),
+        F::U32 => build_stream::<u32>(device, &config, mixer),
+        F::U8 => build_stream::<u8>(device, &config, mixer),
+        other => Err(format!("unsupported sample format {other}").into()),
+    }?;
+    stream.play()?;
+    Ok((stream, config))
+}
+fn build_stream<T: cpal::SizedSample + cpal::FromSample<f32>>(
+    device: &cpal::Device,
+    config: &cpal::SupportedStreamConfig,
+    mixer: Arc<Mutex<Mixer>>,
+) -> Result<cpal::Stream> {
+    let rate = config.sample_rate().0;
+    let channels = config.channels() as usize;
+    let mut scratch = Vec::new();
+    let stream = device.build_output_stream(
+        &config.config(),
+        move |data: &mut [T], _| {
+            scratch.resize(data.len(), 0.0f32);
+            if let Ok(mut m) = mixer.lock() {
+                mix(&mut m, &mut scratch, channels, rate);
+            } else {
+                scratch.fill(0.0);
+            }
+            for (out, s) in data.iter_mut().zip(&scratch) {
+                *out = T::from_sample(*s);
+            }
+        },
+        |e| log::warn!("Horizon: audio stream error: {e}"),
+        None,
+    )?;
+    Ok(stream)
+}
 impl Audio {
    pub fn new(root: &Path) -> Self {
        Self::with_output(root, true)
@@ -347,7 +486,7 @@ impl Audio {
            Ok(v) => (Some(v), true),
            Err(e) => {
                if output {
-                    eprintln!("Horizon: audio unavailable: {e}");
+                    log::warn!("Horizon: no sound: {e}");
                }
                (None, false)
            }
@@ -360,7 +499,8 @@ impl Audio {
            backend: MixerBackend {
                mixer,
                root: root.to_owned(),
-                cache: HashMap::new(),
+                cache: Arc::default(),
+                decoder: None,
                next: 0,
                live,
            },
@@ -374,32 +514,40 @@ impl Audio {
        }
    }
    fn open(mixer: Arc<Mutex<Mixer>>) -> Result<cpal::Stream> {
-        // Test runs (harnesses, agents) launch the game on a virtual screen;
-        // keep them off the user's speakers.
-        if std::env::var_os("HORIZON_NO_AUDIO").is_some() {
-            return Err("audio output disabled by HORIZON_NO_AUDIO".into());
+        if let Some(reason) = output_disabled(|name| std::env::var_os(name)) {
+            return Err(reason.into());
        }
        let host = cpal::default_host();
-        let device = host
-            .default_output_device()
-            .ok_or("no audio output device")?;
-        let config = device.default_output_config()?;
-        let rate = config.sample_rate().0;
-        let channels = config.channels() as usize;
-        let stream = device.build_output_stream(
-            &config.into(),
-            move |data: &mut [f32], _| {
-                if let Ok(mut m) = mixer.lock() {
-                    mix(&mut m, data, channels, rate);
-                } else {
-                    data.fill(0.0);
+        let mut errors = Vec::new();
+        // The default device first, then any other output a host lists:
+        // a default that cannot open (busy, or a stale ALSA default) should
+        // not leave the game silent when another device works.
+        let default = host.default_output_device();
+        let others = host.output_devices().into_iter().flatten();
+        let mut tried = Vec::new();
+        for device in default.into_iter().chain(others) {
+            let name = device.name().unwrap_or_else(|_| "unnamed device".into());
+            if tried.contains(&name) {
+                continue;
+            }
+            tried.push(name.clone());
+            match open_device(&device, mixer.clone()) {
+                Ok((stream, config)) => {
+                    log::info!(
+                        "Horizon: audio output {name} ({} Hz, {} channels, {})",
+                        config.sample_rate().0,
+                        config.channels(),
+                        config.sample_format()
+                    );
+                    return Ok(stream);
                }
-            },
-            |e| eprintln!("Horizon: audio stream error: {e}"),
-            None,
-        )?;
-        stream.play()?;
-        Ok(stream)
+                Err(e) => errors.push(format!("{name}: {e}")),
+            }
+        }
+        if errors.is_empty() {
+            return Err(format!("no audio output device on the {} host", host.id().name()).into());
+        }
+        Err(format!("no audio output device opened ({})", errors.join("; ")).into())
    }
    fn bound(&mut self) -> Bound<'_, MixerBackend> {
        Bound {
@@ -452,6 +600,16 @@ impl Audio {
    pub fn stop_all(&mut self) {
        self.engine.stop_all(&mut self.backend);
    }
+    /// `SoundManager.reload` (resource packs changed): stop every sound, then
+    /// read sound events and sound files from the new resource root.
+    pub fn reload(&mut self, root: &Path) {
+        self.stop_all();
+        self.engine.registry = SoundRegistry::load(root);
+        self.backend.root = root.to_owned();
+        let mut cache = self.backend.cache.lock().unwrap();
+        cache.entries.clear();
+        cache.bytes = 0;
+    }
    /// Play a sound event at a world position, as `ClientLevel.playLocalSound`
    /// (a `SimpleSoundInstance` seeded from the level random), or relative to
    /// the listener without attenuation (`None`).
@@ -459,6 +617,23 @@ impl Audio {
        let seed = self.random.next_long();
        self.play_seeded(event, at, volume, pitch, seed);
    }
+    /// `LivingEntity.handleDamageEvent`'s pitch, `(r - r) * 0.2 + 1`, drawn on the
+    /// client (the entity's own random there, never the server's world random).
+    pub fn hurt_pitch(&mut self) -> f32 {
+        (self.random.next_float() - self.random.next_float()) * 0.2 + 1.0
+    }
+    /// `AbstractWidget.playButtonClickSound`: an unseeded, relative UI sound.
+    pub fn play_button_click(&mut self) {
+        self.play_instance(
+            SoundInstance::for_ui(
+                "minecraft:ui.button.click",
+                1.0,
+                0.25,
+                SoundEngine::unseeded(),
+            ),
+            false,
+        );
+    }
    /// `play` with the seed a sound packet carries.
    pub fn play_seeded(
        &mut self,
@@ -525,6 +700,21 @@ impl Audio {
        self.release(id);
    }
    /// Every sound event id (for command completion).
+    /// The engine's table sizes and the mixer's channels (`status`).
+    pub fn census(&self) -> serde_json::Value {
+        let mut census = self.engine.census();
+        census["channels"] = self
+            .backend
+            .mixer
+            .lock()
+            .map_or(0, |m| m.channels.len())
+            .into();
+        if let Ok(cache) = self.backend.cache.lock() {
+            census["decoded"] = cache.entries.len().into();
+            census["decoded_mib"] = (cache.bytes >> 20).into();
+        }
+        census
+    }
    pub fn event_names(&self) -> Vec<String> {
        let mut v: Vec<String> = self.engine.registry.names().cloned().collect();
        v.sort();
@@ -576,6 +766,38 @@ impl Sounds for Audio {
 mod tests {
    use super::*;

+    #[test]
+    fn button_click_uses_vanilla_ui_parameters_without_advancing_world_random() {
+        let mut audio = Audio::silent(Path::new("/nonexistent/horizon-test-assets"));
+        audio.engine.registry.add_file(
+            "minecraft",
+            br#"{"ui.button.click":{"sounds":["gui/button"]}}"#,
+            &|_, _| true,
+        );
+        // Exercise the mixer without opening an output device. The missing
+        // sample is harmless: this test checks the source the engine creates.
+        audio.engine.loaded = true;
+        audio.backend.live = true;
+        let mut random = audio.random.clone();
+        audio.play_button_click();
+        let instance = audio.engine.instance(1).expect("click reached the engine");
+        assert_eq!(instance.identifier, "minecraft:ui.button.click");
+        assert_eq!(instance.source, crate::sound_engine::UI);
+        assert_eq!(instance.volume, 0.25);
+        assert_eq!(instance.pitch, 1.0);
+        assert_eq!(instance.attenuation, Attenuation::None);
+        assert_eq!(instance.position, [0.0; 3]);
+        assert!(instance.relative);
+        assert!(!instance.looping);
+        assert_eq!(audio.random.next_long(), random.next_long());
+        audio.pause();
+        assert_eq!(
+            audio.backend.mixer.lock().unwrap().channels[&1].state,
+            State::Initial
+        );
+        audio.stop_all();
+    }
+
    fn channel(samples: Vec<f32>, linear: Option<f32>, at: [f32; 3], looping: bool) -> Channel {
        Channel {
            samples: Some((Arc::new(samples), 48_000)),
@@ -590,6 +812,47 @@ mod tests {
        }
    }

+    #[test]
+    fn decoded_sounds_stay_within_the_budget_least_recently_used_out() {
+        let mut cache = SoundCache::default();
+        let quarter = CACHE_BYTES / 4 / std::mem::size_of::<f32>();
+        let sound = || Some((Arc::new(vec![0.0f32; quarter]), 44100));
+        for key in ["a", "b", "c", "d"] {
+            cache.insert(key.into(), sound());
+        }
+        assert!(cache.get("a").is_some());
+        cache.insert("e".into(), sound());
+        assert!(cache.bytes <= CACHE_BYTES);
+        assert!(
+            cache.get("b").is_none(),
+            "the least recently used goes first"
+        );
+        assert!(cache.get("a").is_some() && cache.get("e").is_some());
+        // A failed load is remembered without counting.
+        cache.insert("missing".into(), None);
+        assert_eq!(cache.get("missing"), Some(None));
+    }
+    #[test]
+    fn output_stays_off_on_a_virtual_screen_unless_asked() {
+        let env = |pairs: &'static [(&'static str, &'static str)]| {
+            move |name: &str| {
+                pairs
+                    .iter()
+                    .find(|(k, _)| *k == name)
+                    .map(|(_, v)| std::ffi::OsString::from(*v))
+            }
+        };
+        assert!(output_disabled(env(&[("WAYLAND_DISPLAY", "wayland-1")])).is_none());
+        assert!(output_disabled(env(&[])).is_none());
+        const VSCREEN: &str = "/run/user/1000/vscreen/main/wayland-1";
+        assert!(output_disabled(env(&[("WAYLAND_DISPLAY", VSCREEN)])).is_some());
+        assert!(
+            output_disabled(env(&[("WAYLAND_DISPLAY", VSCREEN), ("HORIZON_AUDIO", "1")])).is_none()
+        );
+        assert!(
+            output_disabled(env(&[("HORIZON_NO_AUDIO", "1"), ("HORIZON_AUDIO", "1")])).is_some()
+        );
+    }
    #[test]
    fn linear_attenuation_reaches_zero_at_the_max_distance() {
        assert_eq!(distance_gain(None, 100.0), 1.0);
@@ -0,0 +1,343 @@
+//! The Microsoft account the launcher signed in, handed over in a session
+//! file (docs/microsoft-account.md), and the Minecraft services call
+//! online-mode servers need: authlib's MinecraftServicesSessionService.joinServer
+//! through the services discovery document. The access token stays in this
+//! process's memory: it is never logged, printed or written anywhere.
+use std::{
+    path::Path,
+    sync::{Arc, Mutex, OnceLock},
+    time::{Duration, SystemTime},
+};
+
+/// MinecraftServicesEnvironment.PROD.
+pub const DEFAULT_DISCOVERY: &str = "https://discovery.minecraftservices.com/minecraft/client";
+/// A session file older than this is refused: it can't be replayed later.
+const MAX_SESSION_FILE_AGE: Duration = Duration::from_secs(120);
+
+/// A signed-in account (vanilla's User with type msa).
+pub struct AuthSession {
+    pub name: String,
+    pub uuid: u128,
+    pub xuid: Option<String>,
+    access_token: String,
+}
+impl std::fmt::Debug for AuthSession {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("AuthSession")
+            .field("name", &self.name)
+            .field("uuid", &horizon_protocol::crypto::uuid_string(self.uuid))
+            .field("access_token", &"<hidden>")
+            .finish()
+    }
+}
+
+/// A UUID with or without dashes.
+pub fn parse_uuid(text: &str) -> Option<u128> {
+    let hex: String = text.chars().filter(|c| *c != '-').collect();
+    (hex.len() == 32)
+        .then(|| u128::from_str_radix(&hex, 16).ok())
+        .flatten()
+}
+
+impl AuthSession {
+    /// For tests and harnesses.
+    pub fn new(name: &str, uuid: u128, access_token: &str) -> Self {
+        Self {
+            name: name.to_owned(),
+            uuid,
+            xuid: None,
+            access_token: access_token.to_owned(),
+        }
+    }
+    /// The session file's JSON: {"name", "uuid", "access_token", "user_type": "msa", "xuid"}.
+    pub fn parse(text: &str) -> Result<Self, String> {
+        let v: serde_json::Value =
+            serde_json::from_str(text).map_err(|_| "the session file is not valid JSON")?;
+        let field = |k: &str| v.get(k).and_then(|s| s.as_str());
+        let name = field("name").ok_or("the session file has no name")?;
+        if name.is_empty() || name.chars().count() > 16 {
+            return Err("the session file's name is not a valid player name".into());
+        }
+        let uuid = field("uuid")
+            .and_then(parse_uuid)
+            .ok_or("the session file has no valid uuid")?;
+        let access_token = field("access_token")
+            .filter(|t| !t.is_empty())
+            .ok_or("the session file has no access token")?;
+        if field("user_type").is_some_and(|t| t != "msa") {
+            return Err("the session file is not a Microsoft account session".into());
+        }
+        Ok(Self {
+            name: name.to_owned(),
+            uuid,
+            xuid: field("xuid").map(str::to_owned),
+            access_token: access_token.to_owned(),
+        })
+    }
+    /// Read the session file the launcher wrote and delete it at once. It
+    /// must be fresh and, on Unix, readable by its owner only.
+    pub fn load(path: &Path) -> Result<Self, String> {
+        let meta = std::fs::metadata(path).map_err(|e| format!("{}: {e}", path.display()))?;
+        let refuse = |why: &str| {
+            let _ = std::fs::remove_file(path);
+            Err(format!("{}: {why}", path.display()))
+        };
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            if meta.permissions().mode() & 0o077 != 0 {
+                return refuse("other users can read it");
+            }
+        }
+        let age = meta
+            .modified()
+            .ok()
+            .and_then(|m| SystemTime::now().duration_since(m).ok())
+            .unwrap_or_default();
+        if age > MAX_SESSION_FILE_AGE {
+            return refuse("it is too old (start the game from the launcher)");
+        }
+        let text = std::fs::read_to_string(path);
+        let _ = std::fs::remove_file(path);
+        Self::parse(&text.map_err(|e| format!("{}: {e}", path.display()))?)
+    }
+}
+
+static CURRENT: OnceLock<Arc<AuthSession>> = OnceLock::new();
+
+/// The account this game was started with (set once at start).
+pub fn set_current(session: AuthSession) {
+    let _ = CURRENT.set(Arc::new(session));
+}
+pub fn current() -> Option<Arc<AuthSession>> {
+    CURRENT.get().cloned()
+}
+
+/// Why joining a server through the session service failed, like the
+/// AuthenticationException subclasses authlib throws.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum JoinError {
+    /// No answer, or a 5xx (AuthenticationUnavailableException).
+    Unavailable,
+    /// 401 or ForbiddenOperationException (InvalidCredentialsException).
+    InvalidSession,
+    /// InsufficientPrivilegesException: multiplayer is off for the account.
+    InsufficientPrivileges,
+    /// multiplayer.access.banned or FORCED_USERNAME_CHANGE.
+    Banned,
+    /// Anything else, with the service's message.
+    Other(String),
+}
+impl JoinError {
+    /// MinecraftClientHttpException.toAuthenticationException.
+    pub fn from_response(status: u16, body: &str) -> Self {
+        let v: serde_json::Value = serde_json::from_str(body).unwrap_or_default();
+        let error = v.get("error").and_then(|e| e.as_str()).unwrap_or("");
+        match error {
+            "ForbiddenOperationException" => return Self::InvalidSession,
+            "multiplayer.access.banned" | "FORCED_USERNAME_CHANGE" => return Self::Banned,
+            "InsufficientPrivilegesException" => return Self::InsufficientPrivileges,
+            _ => {}
+        }
+        match status {
+            401 => Self::InvalidSession,
+            500.. => Self::Unavailable,
+            _ => Self::Other(
+                v.get("errorMessage")
+                    .and_then(|m| m.as_str())
+                    .map_or_else(|| format!("Status: {status}"), str::to_owned),
+            ),
+        }
+    }
+    /// ClientHandshakePacketListenerImpl.authenticateServer's message: the
+    /// key of the reason inside "disconnect.loginFailedInfo", or its text.
+    pub fn reason(&self) -> Result<&'static str, &str> {
+        match self {
+            Self::Unavailable => Ok("disconnect.loginFailedInfo.serversUnavailable"),
+            Self::InvalidSession => Ok("disconnect.loginFailedInfo.invalidSession"),
+            Self::InsufficientPrivileges => Ok("disconnect.loginFailedInfo.insufficientPrivileges"),
+            Self::Banned => Ok("disconnect.loginFailedInfo.userBanned"),
+            Self::Other(message) => Err(message),
+        }
+    }
+}
+
+/// The services discovery document URL: `HORIZON_API_DISCOVERY` overrides
+/// it like authlib's `-Dminecraft.api.discovery.host`.
+pub fn discovery_url() -> String {
+    std::env::var("HORIZON_API_DISCOVERY")
+        .ok()
+        .filter(|u| !u.is_empty())
+        .unwrap_or_else(|| DEFAULT_DISCOVERY.to_owned())
+}
+
+fn agent() -> ureq::Agent {
+    ureq::AgentBuilder::new()
+        .timeout(Duration::from_secs(15))
+        .user_agent(concat!("Horizon/", env!("CARGO_PKG_VERSION")))
+        .build()
+}
+
+/// The discovery document, fetched once per game (a failure is retried next time).
+fn discovery() -> Result<Arc<serde_json::Value>, JoinError> {
+    static CACHE: Mutex<Option<Arc<serde_json::Value>>> = Mutex::new(None);
+    if let Some(d) = CACHE.lock().unwrap().clone() {
+        return Ok(d);
+    }
+    let doc: serde_json::Value = agent()
+        .get(&discovery_url())
+        .call()
+        .ok()
+        .and_then(|r| r.into_string().ok())
+        .and_then(|t| serde_json::from_str(&t).ok())
+        .ok_or(JoinError::Unavailable)?;
+    let doc = Arc::new(doc);
+    *CACHE.lock().unwrap() = Some(doc.clone());
+    Ok(doc)
+}
+
+/// MinecraftServicesDiscoveryService.getUrl(service, endpoint).
+pub fn endpoint(doc: &serde_json::Value, service: &str, name: &str) -> Option<String> {
+    doc.pointer(&format!("/discovery/{service}/endpoints/{name}/uri"))
+        .and_then(|u| u.as_str())
+        .map(str::to_owned)
+}
+
+/// The JoinMinecraftServerRequest body; `selectedProfile` is the undashed UUID.
+pub fn join_request(session: &AuthSession, server_hash: &str) -> String {
+    serde_json::json!({
+        "accessToken": session.access_token,
+        "selectedProfile": format!("{:032x}", session.uuid),
+        "serverId": server_hash,
+    })
+    .to_string()
+}
+
+/// MinecraftServicesSessionService.joinServer: tell the session service this
+/// account is joining the server whose hash is `server_hash`.
+pub fn join_server(session: &AuthSession, server_hash: &str) -> Result<(), JoinError> {
+    let doc = discovery()?;
+    let url = endpoint(&doc, "session", "join").ok_or(JoinError::Unavailable)?;
+    match agent()
+        .post(&url)
+        .set("Content-Type", "application/json; charset=utf-8")
+        .send_string(&join_request(session, server_hash))
+    {
+        Ok(_) => Ok(()),
+        Err(ureq::Error::Status(status, response)) => Err(JoinError::from_response(
+            status,
+            &response.into_string().unwrap_or_default(),
+        )),
+        Err(ureq::Error::Transport(_)) => Err(JoinError::Unavailable),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const UUID: u128 = 0x069a79f444e94726a5befca90e38aaf5;
+
+    fn write(dir: &Path, text: &str, mode: u32) -> std::path::PathBuf {
+        let path = dir.join("session.json");
+        std::fs::write(&path, text).unwrap();
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            std::fs::set_permissions(&path, std::fs::Permissions::from_mode(mode)).unwrap();
+        }
+        let _ = mode;
+        path
+    }
+
+    #[test]
+    fn session_files_are_read_once_and_must_be_private() {
+        let dir = std::env::temp_dir().join(format!("horizon-auth-test-{}", std::process::id()));
+        std::fs::create_dir_all(&dir).unwrap();
+        let text = r#"{"name":"Notch","uuid":"069a79f4-44e9-4726-a5be-fca90e38aaf5","access_token":"mock-token","user_type":"msa"}"#;
+        let path = write(&dir, text, 0o600);
+        let s = AuthSession::load(&path).unwrap();
+        assert_eq!((s.name.as_str(), s.uuid), ("Notch", UUID));
+        assert!(!path.exists(), "deleted after reading");
+        assert!(!format!("{s:?}").contains("mock-token"));
+        #[cfg(unix)]
+        {
+            let path = write(&dir, text, 0o644);
+            assert!(
+                AuthSession::load(&path)
+                    .unwrap_err()
+                    .contains("other users")
+            );
+            assert!(!path.exists());
+        }
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn session_file_fields() {
+        assert!(
+            AuthSession::parse(r#"{"name":"Notch","uuid":"069a79f444e94726a5befca90e38aaf5"}"#)
+                .is_err()
+        );
+        assert!(
+            AuthSession::parse(
+                r#"{"name":"","uuid":"069a79f444e94726a5befca90e38aaf5","access_token":"t"}"#
+            )
+            .is_err()
+        );
+        assert!(AuthSession::parse(r#"{"name":"A","uuid":"nope","access_token":"t"}"#).is_err());
+        assert!(AuthSession::parse(r#"{"name":"A","uuid":"069a79f444e94726a5befca90e38aaf5","access_token":"t","user_type":"legacy"}"#).is_err());
+        let s = AuthSession::parse(r#"{"name":"A","uuid":"069a79f444e94726a5befca90e38aaf5","access_token":"t","xuid":"25"}"#).unwrap();
+        assert_eq!(s.xuid.as_deref(), Some("25"));
+    }
+
+    #[test]
+    fn join_request_like_authlib() {
+        let s = AuthSession::new("Notch", UUID, "tok");
+        let v: serde_json::Value = serde_json::from_str(&join_request(&s, "-7c9d")).unwrap();
+        assert_eq!(
+            v,
+            serde_json::json!({"accessToken": "tok", "selectedProfile": "069a79f444e94726a5befca90e38aaf5", "serverId": "-7c9d"})
+        );
+    }
+
+    #[test]
+    fn errors_map_like_authlib() {
+        let e = |status, body| JoinError::from_response(status, body);
+        assert_eq!(
+            e(
+                403,
+                r#"{"error":"ForbiddenOperationException","errorMessage":"Invalid token"}"#
+            ),
+            JoinError::InvalidSession
+        );
+        assert_eq!(e(401, ""), JoinError::InvalidSession);
+        assert_eq!(
+            e(403, r#"{"error":"InsufficientPrivilegesException"}"#),
+            JoinError::InsufficientPrivileges
+        );
+        assert_eq!(
+            e(403, r#"{"error":"multiplayer.access.banned"}"#),
+            JoinError::Banned
+        );
+        assert_eq!(e(503, "down"), JoinError::Unavailable);
+        assert_eq!(
+            e(429, r#"{"errorMessage":"Too many"}"#),
+            JoinError::Other("Too many".into())
+        );
+        assert_eq!(
+            JoinError::InvalidSession.reason(),
+            Ok("disconnect.loginFailedInfo.invalidSession")
+        );
+    }
+
+    #[test]
+    fn discovery_endpoints() {
+        let doc = serde_json::json!({"discovery": {"session": {"endpoints": {"join": {"uri": "https://s/join"}}}}});
+        assert_eq!(
+            endpoint(&doc, "session", "join").as_deref(),
+            Some("https://s/join")
+        );
+        assert_eq!(endpoint(&doc, "session", "verify"), None);
+    }
+}
@@ -0,0 +1,438 @@
+//! Beehives and bee nests (`BeehiveBlockEntity`): up to three bees stored as
+//! entity tags, let out when their time inside is up (never at night or in
+//! the rain, nor through a blocked front, unless the hive is emptied in an
+//! emergency), honey for every bee coming home with nectar. The host (the game
+//! or the mob AI probe) loads and adds the bees through [`HiveHost`].
+use crate::mobs::{Mob, Species, bee};
+use horizon_core::random::{LegacyRandom, RandomSource};
+use horizon_world::nbt::{Compound, Tag};
+
+pub const MAX_OCCUPANTS: usize = 3;
+/// `BeehiveBlockEntity.IGNORED_BEE_TAGS`: dropped from a bee going in, and
+/// again from the tag it comes out with.
+const IGNORED_BEE_TAGS: [&str; 25] = [
+    "Air",
+    "drop_chances",
+    "equipment",
+    "Brain",
+    "CanPickUpLoot",
+    "DeathTime",
+    "fall_distance",
+    "FallFlying",
+    "Fire",
+    "HurtTime",
+    "LeftHanded",
+    "Motion",
+    "NoGravity",
+    "OnGround",
+    "PortalCooldown",
+    "Pos",
+    "Rotation",
+    "sleeping_pos",
+    "CannotEnterHiveTicks",
+    "TicksSincePollination",
+    "CropsGrownSincePollination",
+    "hive_pos",
+    "Passengers",
+    "leash",
+    "UUID",
+];
+
+/// `BeehiveBlockEntity`: the bees inside and the flower one of them knew.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct Beehive {
+    pub bees: Vec<Occupant>,
+    pub flower: Option<[i32; 3]>,
+}
+/// `BeehiveBlockEntity.Occupant`: a bee's tag (with its `id`), its time in
+/// the hive and the time it stays at least.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Occupant {
+    pub entity_data: Tag,
+    pub ticks_in_hive: i32,
+    pub min_ticks_in_hive: i32,
+}
+/// `BeehiveBlockEntity.BeeReleaseStatus`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Release {
+    HoneyDelivered,
+    BeeReleased,
+    Emergency,
+}
+
+/// What a hive needs from the level it is in.
+pub trait HiveHost {
+    /// `level.getRandom()`.
+    fn random(&mut self) -> &mut LegacyRandom;
+    /// `EnvironmentAttributes.BEES_STAY_IN_HIVE` at a position.
+    fn bees_stay_in_hive(&self, at: [i32; 3]) -> bool;
+    /// A non-empty collision shape at a block.
+    fn blocked(&self, at: [i32; 3]) -> bool;
+    /// `BlockState.setValue(HONEY_LEVEL, level)` on the hive.
+    fn set_honey_level(&mut self, at: [i32; 3], level: i32);
+    /// `EntityType.loadEntityRecursive` (the tag has its `id` and a `Pos`):
+    /// a new entity, or `None` for anything but a `#beehive_inhabitors`.
+    fn load(&mut self, tag: &Tag) -> Option<Mob>;
+    /// `Level.addFreshEntity`.
+    fn add(&mut self, m: Mob) -> bool;
+    fn sound(&mut self, name: &'static str, at: [f64; 3]);
+}
+
+fn strip_ignored(c: &mut Compound) {
+    for key in IGNORED_BEE_TAGS {
+        c.remove(&key.into());
+    }
+}
+fn int(tag: Option<&Tag>) -> Option<i32> {
+    match tag {
+        Some(Tag::Int(v)) => Some(*v),
+        _ => None,
+    }
+}
+fn pos(tag: Option<&Tag>) -> Option<[i32; 3]> {
+    match tag {
+        Some(Tag::IntArray(p)) if p.len() == 3 => Some([p[0], p[1], p[2]]),
+        _ => None,
+    }
+}
+
+impl Occupant {
+    /// `Occupant.of`: the bee's saved tag without the ignored tags, staying
+    /// 2400 ticks with nectar, else 600.
+    pub fn of(mut tag: Tag) -> Self {
+        if let Tag::Compound(c) = &mut tag {
+            strip_ignored(c);
+        }
+        let nectar = matches!(tag.get("HasNectar"), Some(Tag::Byte(v)) if *v != 0);
+        Self {
+            entity_data: tag,
+            ticks_in_hive: 0,
+            min_ticks_in_hive: if nectar { 2400 } else { 600 },
+        }
+    }
+    /// `Occupant.create`: a worldgen nest's bee, a bare bee tag.
+    pub fn create(ticks_in_hive: i32) -> Self {
+        Self {
+            entity_data: Tag::compound([("id", Tag::String("minecraft:bee".into()))]),
+            ticks_in_hive,
+            min_ticks_in_hive: 600,
+        }
+    }
+    fn has_nectar(&self) -> bool {
+        matches!(self.entity_data.get("HasNectar"), Some(Tag::Byte(v)) if *v != 0)
+    }
+    fn from_nbt(tag: &Tag) -> Option<Self> {
+        let data = tag.get("entity_data")?;
+        if !matches!(data, Tag::Compound(c) if c.contains_key(&"id".into())) {
+            return None;
+        }
+        Some(Self {
+            entity_data: data.clone(),
+            ticks_in_hive: int(tag.get("ticks_in_hive"))?,
+            min_ticks_in_hive: int(tag.get("min_ticks_in_hive"))?,
+        })
+    }
+    fn to_nbt(&self) -> Tag {
+        Tag::compound([
+            ("entity_data", self.entity_data.clone()),
+            ("ticks_in_hive", Tag::Int(self.ticks_in_hive)),
+            ("min_ticks_in_hive", Tag::Int(self.min_ticks_in_hive)),
+        ])
+    }
+}
+
+impl Beehive {
+    pub fn full(&self) -> bool {
+        self.bees.len() == MAX_OCCUPANTS
+    }
+    /// `loadAdditional`: `bees` (all or none, as the list codec reads them)
+    /// and `flower_pos`.
+    pub fn from_nbt(tag: &Tag) -> Self {
+        let bees = match tag.get("bees") {
+            Some(Tag::List(list)) => list
+                .iter()
+                .map(Occupant::from_nbt)
+                .collect::<Option<Vec<_>>>()
+                .unwrap_or_default(),
+            _ => Vec::new(),
+        };
+        Self {
+            bees,
+            flower: pos(tag.get("flower_pos")),
+        }
+    }
+    /// `saveAdditional`.
+    pub fn to_nbt(&self) -> Vec<(&'static str, Tag)> {
+        let mut out = vec![(
+            "bees",
+            Tag::List(self.bees.iter().map(Occupant::to_nbt).collect()),
+        )];
+        if let Some(f) = self.flower {
+            out.push(("flower_pos", Tag::IntArray(f.to_vec())));
+        }
+        out
+    }
+    /// `addOccupant` (the bee's own tag, saved by the host): the hive keeps
+    /// the bee's flower, or now and then swaps its own for it. The host then
+    /// discards the bee.
+    pub fn add_occupant(
+        &mut self,
+        at: [i32; 3],
+        tag: Tag,
+        bee_flower: Option<[i32; 3]>,
+        host: &mut impl HiveHost,
+    ) -> bool {
+        if self.bees.len() >= MAX_OCCUPANTS {
+            return false;
+        }
+        self.bees.push(Occupant::of(tag));
+        if let Some(f) = bee_flower
+            && (self.flower.is_none() || host.random().next_boolean())
+        {
+            self.flower = Some(f);
+        }
+        let corner = at.map(f64::from);
+        host.sound("block.beehive.enter", corner);
+        true
+    }
+    /// `serverTick`: the bees whose time is up come out, then the hive
+    /// hums now and then while it holds any. `honey` is the hive state's
+    /// honey level as the tick starts (`None` without the property);
+    /// `facing` its front.
+    pub fn server_tick(
+        &mut self,
+        at: [i32; 3],
+        facing: [i32; 2],
+        honey: Option<i32>,
+        host: &mut impl HiveHost,
+    ) {
+        let flower = self.flower;
+        let mut i = 0;
+        while i < self.bees.len() {
+            // BeeData.tick: ticksInHive++ > minTicksInHive.
+            let b = &mut self.bees[i];
+            let up = b.ticks_in_hive > b.min_ticks_in_hive;
+            b.ticks_in_hive += 1;
+            if up {
+                let status = if b.has_nectar() {
+                    Release::HoneyDelivered
+                } else {
+                    Release::BeeReleased
+                };
+                let occupant = b.clone();
+                if release(host, at, facing, honey, &occupant, status, flower).is_some() {
+                    self.bees.remove(i);
+                    continue;
+                }
+            }
+            i += 1;
+        }
+        if !self.bees.is_empty() && host.random().next_double() < 0.005 {
+            let hum = [
+                f64::from(at[0]) + 0.5,
+                f64::from(at[1]),
+                f64::from(at[2]) + 0.5,
+            ];
+            host.sound("block.beehive.work", hum);
+        }
+    }
+    /// `releaseAllOccupants`: the ids of the bees let out.
+    pub fn release_all(
+        &mut self,
+        at: [i32; 3],
+        facing: [i32; 2],
+        honey: Option<i32>,
+        status: Release,
+        host: &mut impl HiveHost,
+    ) -> Vec<u32> {
+        let flower = self.flower;
+        let mut out = Vec::new();
+        self.bees.retain(
+            |b| match release(host, at, facing, honey, b, status, flower) {
+                Some(id) => {
+                    out.extend(id);
+                    false
+                }
+                None => true,
+            },
+        );
+        out
+    }
+}
+
+/// `releaseOccupant`: `None` while the bee stays in, else the id of the bee
+/// let out (`Some(None)` when the level refused it).
+fn release(
+    host: &mut impl HiveHost,
+    at: [i32; 3],
+    facing: [i32; 2],
+    honey: Option<i32>,
+    occupant: &Occupant,
+    status: Release,
+    flower: Option<[i32; 3]>,
+) -> Option<Option<u32>> {
+    let emergency = status == Release::Emergency;
+    if host.bees_stay_in_hive(at) && !emergency {
+        return None;
+    }
+    let blocked = host.blocked([at[0] + facing[0], at[1], at[2] + facing[1]]);
+    if blocked && !emergency {
+        return None;
+    }
+    // Occupant.createEntity: the tag without the ignored tags.
+    let mut tag = occupant.entity_data.clone();
+    if let Tag::Compound(c) = &mut tag {
+        strip_ignored(c);
+        let center = [at[0], at[1], at[2]].map(|v| Tag::Double((f64::from(v) + 0.5).to_bits()));
+        c.insert("Pos".into(), Tag::List(center.to_vec()));
+    }
+    let mut m = host.load(&tag)?;
+    m.no_gravity = true;
+    if m.species() == Species::Bee {
+        bee::set_hive(&mut m, Some(at));
+        // setBeeReleaseData: the time inside counts towards growing up and
+        // away from love.
+        let ticks = occupant.ticks_in_hive;
+        if !m.extra.age_locked {
+            let age = m.extra.age;
+            m.extra.age = if age < 0 {
+                (age + ticks).min(0)
+            } else if age > 0 {
+                (age - ticks).max(0)
+            } else {
+                age
+            };
+        }
+        m.extra.in_love = (m.extra.in_love - ticks).max(0);
+        if let Some(f) = flower
+            && bee::get(&m).is_none_or(|b| b.flower.is_none())
+            && host.random().next_float() < 0.9
+        {
+            bee::set_flower(&mut m, Some(f));
+        }
+        if status == Release::HoneyDelivered {
+            bee::drop_off_nectar(&mut m);
+            if let Some(level) = honey.filter(|&l| l < 5) {
+                let mut increase = if host.random().next_int_bound(100).unwrap_or(1) == 0 {
+                    2
+                } else {
+                    1
+                };
+                if level + increase > 5 {
+                    increase -= 1;
+                }
+                host.set_honey_level(at, level + increase);
+            }
+        }
+        let delta = if blocked {
+            0.0
+        } else {
+            0.55 + f64::from(m.width() / 2.0)
+        };
+        let p = horizon_core::geometry::Vec3::new(
+            f64::from(at[0]) + 0.5 + delta * f64::from(facing[0]),
+            f64::from(at[1]) + 0.5 - f64::from(m.height() / 2.0),
+            f64::from(at[2]) + 0.5 + delta * f64::from(facing[1]),
+        );
+        m.position = p;
+        m.previous = p;
+    }
+    host.sound(
+        "block.beehive.exit",
+        [
+            f64::from(at[0]) + 0.5,
+            f64::from(at[1]) + 0.5,
+            f64::from(at[2]) + 0.5,
+        ],
+    );
+    let id = m.id;
+    Some(host.add(m).then_some(id))
+}
+
+/// `CampfireBlock.isSmokeyPos`: a lit campfire up to five blocks below,
+/// unless a block whose collision crosses the smoke's centre post comes
+/// first (a lit campfire right under that block still counts).
+pub fn smokey(w: &crate::mobs::MobWorld, at: [i32; 3]) -> bool {
+    let lit = |y: i32| {
+        w.has_tag("minecraft:campfires", w.block_name(at[0], y, at[2]))
+            && w.prop(at[0], y, at[2], "lit") == Some("true")
+    };
+    for i in 1..=5 {
+        let y = at[1] - i;
+        if lit(y) {
+            return true;
+        }
+        // SHAPE_VIRTUAL_POST: Block.column(4, 0, 16), the middle quarter.
+        let (x0, z0) = (f64::from(at[0]), f64::from(at[2]));
+        let blocked = w.block_collision_boxes(at[0], y, at[2]).iter().any(|b| {
+            let (min, max) = (b.min_position(), b.max_position());
+            min.x < x0 + 0.625 && max.x > x0 + 0.375 && min.z < z0 + 0.625 && max.z > z0 + 0.375
+        });
+        if blocked {
+            return lit(y - 1);
+        }
+    }
+    false
+}
+
+/// `HorizontalDirectionalBlock.FACING` as an x/z step.
+pub fn facing_step(facing: Option<&str>) -> [i32; 2] {
+    match facing {
+        Some("south") => [0, 1],
+        Some("west") => [-1, 0],
+        Some("east") => [1, 0],
+        _ => [0, -1],
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn nbt_round_trips_in_vanilla_order() {
+        let tag = Tag::compound([
+            (
+                "bees",
+                Tag::List(vec![
+                    Occupant::create(37).to_nbt(),
+                    Occupant::create(0).to_nbt(),
+                ]),
+            ),
+            ("flower_pos", Tag::IntArray(vec![1, -60, 3])),
+        ]);
+        let hive = Beehive::from_nbt(&tag);
+        assert_eq!(hive.bees.len(), 2);
+        assert_eq!(hive.bees[0].ticks_in_hive, 37);
+        assert_eq!(hive.flower, Some([1, -60, 3]));
+        assert_eq!(Tag::compound(hive.to_nbt()), tag);
+    }
+
+    #[test]
+    fn a_bad_bee_drops_the_whole_list() {
+        let tag = Tag::compound([(
+            "bees",
+            Tag::List(vec![
+                Occupant::create(1).to_nbt(),
+                Tag::compound([("ticks_in_hive", Tag::Int(3))]),
+            ]),
+        )]);
+        assert!(Beehive::from_nbt(&tag).bees.is_empty());
+    }
+
+    #[test]
+    fn going_in_strips_the_ignored_tags() {
+        let tag = Tag::compound([
+            ("id", Tag::String("minecraft:bee".into())),
+            ("UUID", Tag::IntArray(vec![1, 2, 3, 4])),
+            ("Health", Tag::Float(10.0_f32.to_bits())),
+            ("HasNectar", Tag::Byte(1)),
+            ("hive_pos", Tag::IntArray(vec![0, 0, 0])),
+        ]);
+        let o = Occupant::of(tag);
+        assert_eq!(o.min_ticks_in_hive, 2400);
+        assert!(o.entity_data.get("UUID").is_none());
+        assert!(o.entity_data.get("hive_pos").is_none());
+        assert!(o.entity_data.get("Health").is_some());
+    }
+}
@@ -0,0 +1,427 @@
+//! `horizon-client --benchmark SCENARIO`: the run `tools/perf_bench.py` drives from outside, driven
+//! from inside, so anyone can measure their machine with nothing but the game. A thread sends the
+//! same control commands `horizon-ctl` would, through the game's own command queue, and writes a
+//! report (docs/benchmark-report.md) to `benchmarks/` in the game folder.
+//!
+//! The scenes, the world (seed 1234, creative) and every step and figure match `tools/perf_bench.py`,
+//! so reports from the two can be compared.
+
+use std::path::{Path, PathBuf};
+use std::sync::mpsc::{self, Sender};
+use std::thread;
+use std::time::{Duration, Instant};
+
+use horizon_bench::{App, Frames, Kind, Report};
+use serde_json::Value;
+
+use crate::control::Request;
+
+pub const SEED: i64 = 1234;
+/// The world the benchmark creates under `saves/`, replaced on every run.
+pub const WORLD: &str = "horizon-benchmark";
+/// Written into the world so a later run only ever replaces its own world.
+const MARKER: &str = "horizon-benchmark.txt";
+
+/// A straight flight over terrain: name, start, end, pitch (`tools/graphics_bench.py`'s paths).
+type Scene = (&'static str, [f64; 3], [f64; 3], f64);
+pub const SCENES: [Scene; 4] = [
+    (
+        "village",
+        [-960.0, 125.0, 80.0],
+        [-960.0, 125.0, 272.0],
+        35.0,
+    ),
+    (
+        "forest",
+        [-1100.0, 120.0, -560.0],
+        [-1100.0, 120.0, -368.0],
+        25.0,
+    ),
+    (
+        "ocean",
+        [-300.0, 85.0, -420.0],
+        [-300.0, 85.0, -228.0],
+        10.0,
+    ),
+    (
+        "mountain",
+        [560.0, 260.0, 860.0],
+        [752.0, 260.0, 860.0],
+        30.0,
+    ),
+];
+const FLIGHT_SECONDS: f64 = 12.0;
+const SETTLE: Duration = Duration::from_secs(2);
+const LOAD_LIMIT: Duration = Duration::from_secs(600);
+
+/// `standard` flies every scene; a scene's name flies only that one.
+pub fn scenes(scenario: &str) -> Option<Vec<Scene>> {
+    match scenario {
+        "standard" => Some(SCENES.to_vec()),
+        name => SCENES.iter().find(|s| s.0 == name).map(|s| vec![*s]),
+    }
+}
+
+/// What the game knows about the run before it starts.
+pub struct Setup {
+    pub scenario: String,
+    pub started: Instant,
+    pub app: App,
+    pub simulation_distance: u32,
+    pub vsync: bool,
+    /// `None`: unlimited.
+    pub fps_cap: Option<u32>,
+    pub offscreen: bool,
+    pub game_dir: PathBuf,
+}
+
+/// Starts the driver; the game quits when it is done, and the report's path is printed.
+pub fn start(requests: Sender<Request>, setup: Setup) {
+    thread::Builder::new()
+        .name("horizon-benchmark".into())
+        .spawn(move || {
+            let control = Control(requests);
+            match run(&control, setup) {
+                Ok(path) => println!("Horizon: benchmark report {}", path.display()),
+                Err(e) => eprintln!("Horizon: benchmark failed: {e}"),
+            }
+            let _ = control.call("quit");
+        })
+        .expect("spawn the benchmark thread");
+}
+
+struct Control(Sender<Request>);
+
+impl Control {
+    fn call(&self, line: &str) -> Result<Value, String> {
+        let (reply, response) = mpsc::channel();
+        self.0
+            .send(Request {
+                line: line.to_owned(),
+                reply,
+            })
+            .map_err(|_| "the game has exited".to_owned())?;
+        // Flights and loads reply when they finish.
+        let text = response
+            .recv_timeout(LOAD_LIMIT)
+            .map_err(|_| format!("{line}: no reply"))?;
+        let value: Value = serde_json::from_str(&text).map_err(|e| e.to_string())?;
+        match value.get("error").and_then(Value::as_str) {
+            Some(e) => Err(format!("{line}: {e}")),
+            None => Ok(value),
+        }
+    }
+    fn status(&self) -> Value {
+        self.call("status").unwrap_or(Value::Null)
+    }
+}
+
+fn run(control: &Control, setup: Setup) -> Result<PathBuf, String> {
+    let scenes =
+        scenes(&setup.scenario).ok_or_else(|| format!("unknown scenario {}", setup.scenario))?;
+    let mut report = Report::new(Kind::Game, setup.app.clone());
+    let pid = std::process::id();
+    report.conditions.load_avg_1m = horizon_bench::load_average();
+    report.conditions.power = horizon_bench::power_source().map(str::to_owned);
+    let rss = RssSampler::start(pid);
+
+    let title = poll(control, LOAD_LIMIT, |s| {
+        s["screen"] == "title" && !s["renderer"].is_null()
+    })?;
+    report.metric("startup.title_ms", &[ms(setup.started.elapsed())]);
+    let renderer = &title["renderer"];
+    report.hardware.gpu = Some(horizon_bench::Gpu {
+        name: text(&renderer["gpu"]),
+        vendor: match text(&renderer["vendor"]) {
+            // Metal reports no vendor ID.
+            v if v.is_empty() && text(&renderer["gpu"]).starts_with("Apple") => "apple".into(),
+            v => v,
+        },
+        driver: text(&renderer["driver"]),
+        backend: text(&renderer["backend"]).to_lowercase(),
+        kind: text(&renderer["device_type"]),
+    });
+    report.hardware.display = serde_json::from_value(title["display"].clone()).ok();
+
+    replace_world(&setup.game_dir)?;
+    control.call(&format!("open {WORLD} {SEED} creative"))?;
+    std::fs::write(
+        setup.game_dir.join("saves").join(WORLD).join(MARKER),
+        "Created by horizon-client --benchmark; replaced by the next run.\n",
+    )
+    .map_err(|e| e.to_string())?;
+    let loaded = wait_loaded(control, |_| true)?;
+    report.metric("startup.world_ms", &[ms(loaded - setup.started)]);
+
+    let mut steady = Vec::new();
+    for (name, start, end, pitch) in scenes {
+        control.call("time 6000")?;
+        let meshed = control.status()["meshed_sections"].as_f64().unwrap_or(0.0);
+        let generated = control.status()["generated_chunks"].as_f64().unwrap_or(0.0);
+        let [x, y, z] = start;
+        control.call(&format!("tp {x} {y} {z}"))?;
+        let teleported = Instant::now();
+        // A zero-length flight holds the player at the start, flying.
+        control.call(&format!("fly {x} {y} {z} {x} {y} {z} 0.1 {pitch}"))?;
+        control.call(&format!("look {:.3} {pitch}", yaw(start, end)))?;
+        let near = |p: &Value| {
+            let p: Vec<f64> = p
+                .as_array()
+                .into_iter()
+                .flatten()
+                .filter_map(Value::as_f64)
+                .collect();
+            p.len() == 3 && (0..3).map(|i| (p[i] - start[i]).powi(2)).sum::<f64>() < 4.0
+        };
+        let loaded = wait_loaded(control, near)?;
+        let load = loaded - teleported;
+        report.metric(&format!("chunks.{name}.load_ms"), &[ms(load)]);
+        let status = control.status();
+        let meshes = status["meshed_sections"].as_f64().unwrap_or(0.0) - meshed;
+        let chunks = status["generated_chunks"].as_f64().unwrap_or(0.0) - generated;
+        report.metric(&format!("chunks.{name}.meshed_count"), &[meshes]);
+        report.metric(&format!("chunks.{name}.generated_count"), &[chunks]);
+        if load.as_secs_f64() > 0.0 {
+            report.metric(
+                &format!("chunks.{name}.generated_per_s"),
+                &[chunks / load.as_secs_f64()],
+            );
+        }
+        thread::sleep(SETTLE);
+        let [ex, ey, ez] = end;
+        let begin = Instant::now();
+        let flight = control.call(&format!(
+            "fly {x} {y} {z} {ex} {ey} {ez} {FLIGHT_SECONDS} {pitch} raw"
+        ))?;
+        steady.push((begin, Instant::now()));
+        let series = |key: &str| -> Vec<f32> {
+            flight[key]
+                .as_array()
+                .into_iter()
+                .flatten()
+                .filter_map(Value::as_f64)
+                .map(|v| v as f32)
+                .collect()
+        };
+        let frames = Frames::of(
+            name,
+            0,
+            &series("frame_ms"),
+            &series("cpu_ms"),
+            &series("gpu_ms"),
+        )
+        .ok_or("the flight drew no frames")?;
+        report.metric(&format!("fps.{name}.avg_fps"), &[frames.avg_fps]);
+        report.metric(&format!("fps.{name}.low_1pct_fps"), &[frames.low_1pct_fps]);
+        report.metric(
+            &format!("fps.{name}.low_01pct_fps"),
+            &[frames.low_01pct_fps],
+        );
+        report.frames.push(frames);
+    }
+
+    let status = control.status();
+    let renderer = &status["renderer"];
+    let c = &mut report.conditions;
+    c.scenario = Some(setup.scenario.clone());
+    c.seed = Some(SEED.to_string());
+    c.render_distance = status["render_distance"].as_u64().map(|d| d as u32);
+    c.simulation_distance = Some(setup.simulation_distance);
+    c.window = serde_json::from_value(renderer["size"].clone()).ok();
+    c.vsync = Some(setup.vsync);
+    c.fps_cap = setup.fps_cap;
+    c.offscreen = Some(setup.offscreen);
+    c.repeats = Some(1);
+    c.warmup_s = Some(SETTLE.as_secs_f64());
+    if let Some(bytes) = renderer["gpu_allocated_bytes"].as_f64() {
+        report.metric("memory.gpu_mb", &[bytes / f64::from(1 << 20)]);
+    }
+    let samples = rss.stop();
+    if let Some(peak) = samples.iter().map(|s| s.1).max() {
+        report.metric("memory.rss_peak_mb", &[peak as f64 / f64::from(1 << 20)]);
+    }
+    let mut during: Vec<u64> = samples
+        .iter()
+        .filter(|(t, _)| steady.iter().any(|(a, b)| a <= t && t <= b))
+        .map(|s| s.1)
+        .collect();
+    during.sort_unstable();
+    if let Some(&median) = during.get(during.len() / 2) {
+        report.metric(
+            "memory.rss_steady_mb",
+            &[median as f64 / f64::from(1 << 20)],
+        );
+    }
+    if let Ok(meta) = std::env::current_exe().and_then(std::fs::metadata) {
+        report.metric("game.binary_bytes", &[meta.len() as f64]);
+    }
+    crate::telemetry::keep_benchmark(&crate::logging::game_home(), &report);
+    report
+        .write_to(&setup.game_dir.join("benchmarks"))
+        .map_err(|e| e.to_string())
+}
+
+/// Removes the previous run's world, never one the benchmark didn't create.
+fn replace_world(game_dir: &Path) -> Result<(), String> {
+    let world = game_dir.join("saves").join(WORLD);
+    if !world.exists() {
+        return Ok(());
+    }
+    if !world.join(MARKER).exists() {
+        return Err(format!(
+            "{} exists and was not created by the benchmark: rename it",
+            world.display()
+        ));
+    }
+    std::fs::remove_dir_all(&world).map_err(|e| e.to_string())
+}
+
+fn poll(
+    control: &Control,
+    limit: Duration,
+    ready: impl Fn(&Value) -> bool,
+) -> Result<Value, String> {
+    let deadline = Instant::now() + limit;
+    while Instant::now() < deadline {
+        let status = control.status();
+        if ready(&status) {
+            return Ok(status);
+        }
+        thread::sleep(Duration::from_millis(50));
+    }
+    Err(format!("not ready after {} s", limit.as_secs()))
+}
+
+/// Fewer section meshes than this in a second is the game remeshing blocks that change (random
+/// ticks), not loading.
+const QUIET_MESHES_PER_S: f64 = 100.0;
+
+/// Waits until the player is spawned where `near` says, nothing is queued, the resident and
+/// generated chunk counts have not changed for a second and the last sections are drawn (they wait
+/// for their neighbours' light, so after the counts settle); returns when the last of these
+/// happened (`tools/perf_bench.py`'s `wait_loaded`). With `status.streaming`, the sections are
+/// drawn once no stage has held work for half a second: blocks changing after the load (fluids
+/// settling, random ticks) only remesh in bursts. Without it, meshing has to go quiet.
+fn wait_loaded(control: &Control, near: impl Fn(&Value) -> bool) -> Result<Instant, String> {
+    let deadline = Instant::now() + LOAD_LIMIT;
+    let (mut last, mut changed, mut meshing) = (None, Instant::now(), Instant::now());
+    let mut previous: Option<(Instant, f64)> = None;
+    while Instant::now() < deadline {
+        let s = control.status();
+        let now = Instant::now();
+        let position = &s["player"]["position"];
+        if position.is_null()
+            || !near(position)
+            || s["pending_chunks"] != 0
+            || s["screen"] == "title"
+        {
+            (last, changed, previous, meshing) = (None, now, None, now);
+        } else {
+            let counts = (s["chunks"].as_u64(), s["generated_chunks"].as_u64());
+            if last != Some(counts) {
+                (last, changed) = (Some(counts), now);
+            }
+            let meshed = s["meshed_sections"].as_f64().unwrap_or(0.0);
+            let quiet = if let Some(stages) = s["streaming"].as_object() {
+                // Protos outside the view distance wait for neighbours that are never generated.
+                if stages
+                    .iter()
+                    .any(|(k, v)| k != "protos" && v.as_u64().unwrap_or(0) > 0)
+                {
+                    meshing = now;
+                }
+                Duration::from_millis(500)
+            } else {
+                if let Some((at, before)) = previous
+                    && meshed - before > QUIET_MESHES_PER_S * (now - at).as_secs_f64()
+                {
+                    meshing = now;
+                }
+                Duration::from_secs(1)
+            };
+            previous = Some((now, meshed));
+            if now - changed >= Duration::from_secs(1) && now - meshing >= quiet {
+                return Ok(changed.max(meshing));
+            }
+        }
+        thread::sleep(Duration::from_millis(50));
+    }
+    Err(format!("not loaded after {} s", LOAD_LIMIT.as_secs()))
+}
+
+/// Vanilla's yaw facing from `start` to `end`.
+fn yaw(start: [f64; 3], end: [f64; 3]) -> f64 {
+    (-(end[0] - start[0])).atan2(end[2] - start[2]).to_degrees()
+}
+
+fn ms(d: Duration) -> f64 {
+    d.as_secs_f64() * 1000.0
+}
+
+fn text(v: &Value) -> String {
+    v.as_str().unwrap_or_default().to_owned()
+}
+
+/// Samples the process's resident memory four times a second, as `tools/perf_bench.py` does.
+struct RssSampler {
+    stop: Sender<()>,
+    thread: thread::JoinHandle<Vec<(Instant, u64)>>,
+}
+
+impl RssSampler {
+    fn start(pid: u32) -> Self {
+        let (stop, stopped) = mpsc::channel();
+        let thread = thread::spawn(move || {
+            let mut samples = Vec::new();
+            while let Err(mpsc::RecvTimeoutError::Timeout) =
+                stopped.recv_timeout(Duration::from_millis(250))
+            {
+                samples.extend(horizon_bench::rss_bytes(pid).map(|b| (Instant::now(), b)));
+            }
+            samples
+        });
+        Self { stop, thread }
+    }
+    fn stop(self) -> Vec<(Instant, u64)> {
+        let _ = self.stop.send(());
+        self.thread.join().unwrap_or_default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn scenarios() {
+        assert_eq!(scenes("standard").unwrap().len(), 4);
+        assert_eq!(scenes("ocean").unwrap()[0].0, "ocean");
+        assert!(scenes("nether").is_none());
+    }
+
+    #[test]
+    fn yaw_matches_vanilla() {
+        // South (+Z) is 0, west (-X) 90, east (+X) -90.
+        assert!((yaw([0.0; 3], [0.0, 0.0, 10.0])).abs() < 1e-9);
+        assert!((yaw([0.0; 3], [-10.0, 0.0, 0.0]) - 90.0).abs() < 1e-9);
+        assert!((yaw([0.0; 3], [10.0, 0.0, 0.0]) + 90.0).abs() < 1e-9);
+    }
+
+    #[test]
+    fn only_replaces_its_own_world() {
+        let dir =
+            std::env::temp_dir().join(format!("horizon-benchmark-test-{}", std::process::id()));
+        let world = dir.join("saves").join(WORLD);
+        std::fs::create_dir_all(&world).unwrap();
+        assert!(
+            replace_world(&dir).is_err(),
+            "a player's world of that name stays"
+        );
+        assert!(world.exists());
+        std::fs::write(world.join(MARKER), "").unwrap();
+        replace_world(&dir).unwrap();
+        assert!(!world.exists());
+        replace_world(&dir).unwrap();
+        std::fs::remove_dir_all(dir).unwrap();
+    }
+}
@@ -1,204 +0,0 @@
-//! horizon-ctl: drive a running Horizon client through its control socket.
-#![forbid(unsafe_code)]
-use std::{
-    io::{BufRead, BufReader, Write},
-    path::{Path, PathBuf},
-    process::{Command, ExitCode, Stdio},
-    thread,
-    time::{Duration, Instant},
-};
-
-use horizon_client::control::UnixStream;
-
-const USAGE: &str = "usage: horizon-ctl [--socket PATH] COMMAND [ARGS...]
-
-Local commands:
-  launch [GAME ARGS...]      start horizon-client with a control socket and wait for it
-  hold KEY SECONDS           press KEY, wait, release it
-  wait-ready [SECONDS]       wait until the player has spawned and no chunks are pending
-  -                          run commands from stdin, one per line (\"sleep S\" waits locally)
-
-Game commands (run \"horizon-ctl help\" against a running game for the full list):
-  status, key, mouse, look, turn, tp, hotbar, give, render-distance, time,
-  screenshot PATH, stats, bench SECONDS, open, save, quit
-
-Replies are JSON lines; the exit status is 1 when the reply has an \"error\".
-The socket defaults to $HORIZON_CONTROL or $XDG_RUNTIME_DIR/horizon-control.sock.";
-
-struct Client {
-    writer: UnixStream,
-    reader: BufReader<UnixStream>,
-}
-
-impl Client {
-    fn connect(path: &Path) -> Result<Self, String> {
-        let stream = UnixStream::connect(path).map_err(|e| {
-            format!(
-                "cannot connect to {} ({e}); is the game running with --control?",
-                path.display()
-            )
-        })?;
-        let reader = BufReader::new(stream.try_clone().map_err(|e| e.to_string())?);
-        Ok(Self {
-            writer: stream,
-            reader,
-        })
-    }
-    fn send(&mut self, line: &str) -> Result<String, String> {
-        writeln!(self.writer, "{line}").map_err(|e| e.to_string())?;
-        let mut reply = String::new();
-        if self
-            .reader
-            .read_line(&mut reply)
-            .map_err(|e| e.to_string())?
-            == 0
-        {
-            return Err("the game closed the connection".into());
-        }
-        Ok(reply.trim_end().to_owned())
-    }
-}
-
-fn is_error(reply: &str) -> bool {
-    serde_json::from_str::<serde_json::Value>(reply).map_or(true, |v| v.get("error").is_some())
-}
-
-/// Screenshot paths are written by the game process: make them absolute here.
-fn absolute_paths(words: &mut [String]) {
-    if words.first().map(String::as_str) == Some("screenshot")
-        && let Some(path) = words.get_mut(1)
-        && let Ok(cwd) = std::env::current_dir()
-    {
-        *path = cwd.join(&*path).display().to_string();
-    }
-}
-
-fn run_line(client: &mut Client, words: &mut [String]) -> Result<bool, String> {
-    match words.first().map(String::as_str) {
-        Some("sleep") => {
-            let seconds: f64 = words
-                .get(1)
-                .ok_or("sleep SECONDS")?
-                .parse()
-                .map_err(|_| "sleep SECONDS")?;
-            thread::sleep(Duration::from_secs_f64(seconds));
-            Ok(true)
-        }
-        Some("hold") => {
-            let (key, seconds) = match words {
-                [_, key, seconds] => (
-                    key.clone(),
-                    seconds.parse::<f64>().map_err(|_| "hold KEY SECONDS")?,
-                ),
-                _ => return Err("hold KEY SECONDS".into()),
-            };
-            let down = client.send(&format!("key {key} down"))?;
-            if is_error(&down) {
-                println!("{down}");
-                return Ok(false);
-            }
-            thread::sleep(Duration::from_secs_f64(seconds));
-            let up = client.send(&format!("key {key} up"))?;
-            println!("{up}");
-            Ok(!is_error(&up))
-        }
-        Some("wait-ready") => {
-            let limit = words
-                .get(1)
-                .map_or(Ok(120.0), |s| s.parse::<f64>())
-                .map_err(|_| "wait-ready [SECONDS]")?;
-            let deadline = Instant::now() + Duration::from_secs_f64(limit);
-            loop {
-                let reply = client.send("status")?;
-                let status: serde_json::Value =
-                    serde_json::from_str(&reply).map_err(|e| e.to_string())?;
-                if !status["player"].is_null() && status["pending_chunks"] == 0 {
-                    println!("{reply}");
-                    return Ok(true);
-                }
-                if Instant::now() > deadline {
-                    println!(
-                        "{{\"error\":\"not ready after {limit} seconds\",\"status\":{reply}}}"
-                    );
-                    return Ok(false);
-                }
-                thread::sleep(Duration::from_millis(250));
-            }
-        }
-        _ => {
-            absolute_paths(words);
-            let reply = client.send(&words.join(" "))?;
-            println!("{reply}");
-            Ok(!is_error(&reply))
-        }
-    }
-}
-
-fn launch(socket: &Path, args: &[String]) -> Result<bool, String> {
-    let exe = std::env::current_exe().map_err(|e| e.to_string())?;
-    let game = exe.with_file_name("horizon-client");
-    let log = socket.with_extension("log");
-    let file = std::fs::File::create(&log).map_err(|e| format!("{}: {e}", log.display()))?;
-    let child = Command::new(&game)
-        .args(args)
-        .arg("--control-socket")
-        .arg(socket)
-        .stdin(Stdio::null())
-        .stdout(file.try_clone().map_err(|e| e.to_string())?)
-        .stderr(file)
-        .spawn()
-        .map_err(|e| format!("{}: {e}", game.display()))?;
-    let deadline = Instant::now() + Duration::from_secs(300);
-    while Instant::now() < deadline {
-        if UnixStream::connect(socket).is_ok() {
-            println!(
-                "{}",
-                serde_json::json!({ "ok": true, "pid": child.id(), "socket": socket, "log": log })
-            );
-            return Ok(true);
-        }
-        thread::sleep(Duration::from_millis(100));
-    }
-    println!(
-        "{}",
-        serde_json::json!({ "error": "control socket did not open within 300 seconds", "log": log })
-    );
-    Ok(false)
-}
-
-fn main() -> ExitCode {
-    let mut args: Vec<String> = std::env::args().skip(1).collect();
-    let mut socket = horizon_client::control::default_path();
-    if args.first().map(String::as_str) == Some("--socket") && args.len() >= 2 {
-        socket = PathBuf::from(args.remove(1));
-        args.remove(0);
-    }
-    let result = match args.first().map(String::as_str) {
-        None | Some("-h" | "--help") => {
-            println!("{USAGE}");
-            return ExitCode::SUCCESS;
-        }
-        Some("launch") => launch(&socket, &args[1..]),
-        Some("-") => Client::connect(&socket).and_then(|mut client| {
-            let mut all_ok = true;
-            for line in std::io::stdin().lock().lines() {
-                let line = line.map_err(|e| e.to_string())?;
-                let mut words: Vec<String> = line.split_whitespace().map(str::to_owned).collect();
-                if words.is_empty() || words[0].starts_with('#') {
-                    continue;
-                }
-                all_ok &= run_line(&mut client, &mut words)?;
-            }
-            Ok(all_ok)
-        }),
-        Some(_) => Client::connect(&socket).and_then(|mut client| run_line(&mut client, &mut args)),
-    };
-    match result {
-        Ok(true) => ExitCode::SUCCESS,
-        Ok(false) => ExitCode::from(1),
-        Err(e) => {
-            eprintln!("horizon-ctl: {e}");
-            ExitCode::from(2)
-        }
-    }
-}
@@ -0,0 +1,614 @@
+//! Every command horizon-ctl knows: its usage, help, examples and arguments.
+//! The same table prints `help`, checks `COMMAND --help` and describes the
+//! MCP tools, so the CLI and the MCP server always offer the same commands.
+use serde_json::{Map, Value, json};
+
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum Ty {
+    Int,
+    Num,
+    Str,
+    Bool,
+    /// One of these words.
+    Enum(&'static [&'static str]),
+    /// The rest of the line, spaces included.
+    Rest,
+}
+
+#[derive(Clone, Copy)]
+pub struct Param {
+    pub name: &'static str,
+    pub ty: Ty,
+    pub required: bool,
+    /// Sent as `--name value` (`--name` alone for booleans), not by position.
+    pub flag: bool,
+    pub help: &'static str,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum Group {
+    Session,
+    Observe,
+    Move,
+    Act,
+    Screens,
+    World,
+    Scripting,
+}
+impl Group {
+    pub const ALL: [Group; 7] = [
+        Group::Session,
+        Group::Observe,
+        Group::Move,
+        Group::Act,
+        Group::Screens,
+        Group::World,
+        Group::Scripting,
+    ];
+    pub fn title(self) -> &'static str {
+        match self {
+            Group::Session => "Session",
+            Group::Observe => "Observe (JSON state)",
+            Group::Move => "Move and look",
+            Group::Act => "Act on the world",
+            Group::Screens => "Screens, menus and chat",
+            Group::World => "World and cheats",
+            Group::Scripting => "Scripting and benchmarks",
+        }
+    }
+}
+
+pub struct Cmd {
+    pub name: &'static str,
+    /// What the game receives instead of `name` (aliases such as look-at-block).
+    pub wire: Option<&'static str>,
+    pub group: Group,
+    pub usage: &'static str,
+    pub summary: &'static str,
+    pub details: &'static str,
+    pub examples: &'static [&'static str],
+    pub params: &'static [Param],
+    /// Offered as an MCP tool.
+    pub mcp: bool,
+    /// Runs in horizon-ctl itself, not in the game.
+    pub local: bool,
+}
+
+const fn p(name: &'static str, ty: Ty, help: &'static str) -> Param {
+    Param {
+        name,
+        ty,
+        required: true,
+        flag: false,
+        help,
+    }
+}
+const fn opt(name: &'static str, ty: Ty, help: &'static str) -> Param {
+    Param {
+        name,
+        ty,
+        required: false,
+        flag: false,
+        help,
+    }
+}
+const fn flag(name: &'static str, ty: Ty, help: &'static str) -> Param {
+    Param {
+        name,
+        ty,
+        required: false,
+        flag: true,
+        help,
+    }
+}
+const XYZ: [Param; 3] = [
+    p("x", Ty::Num, "X coordinate"),
+    p("y", Ty::Num, "Y coordinate"),
+    p("z", Ty::Num, "Z coordinate"),
+];
+const BLOCK_XYZ: [Param; 3] = [
+    p("x", Ty::Int, "block X"),
+    p("y", Ty::Int, "block Y"),
+    p("z", Ty::Int, "block Z"),
+];
+const OVER: Param = flag(
+    "over",
+    Ty::Num,
+    "turn with mouse motion spread over this many seconds (eased), as a player would",
+);
+const FACE: Ty = Ty::Enum(&["down", "up", "north", "south", "west", "east"]);
+
+macro_rules! cmd {
+    ($name:expr, $group:ident, $usage:expr, $summary:expr, $details:expr, [$($ex:expr),* $(,)?], $params:expr, mcp: $mcp:expr, local: $local:expr $(, wire: $wire:expr)?) => {
+        Cmd {
+            name: $name,
+            wire: cmd!(@wire $($wire)?),
+            group: Group::$group,
+            usage: $usage,
+            summary: $summary,
+            details: $details,
+            examples: &[$($ex),*],
+            params: $params,
+            mcp: $mcp,
+            local: $local,
+        }
+    };
+    (@wire) => { None };
+    (@wire $w:expr) => { Some($w) };
+}
+
+pub const COMMANDS: &[Cmd] = &[
+    // Session
+    cmd!("launch", Session, "launch [--world NAME] [--seed N] [--creative] [--version TAG] [--game PATH] [--wait] [GAME ARGS...]",
+        "start Horizon with the control socket and wait until it answers",
+        "Finds the game in this order: --game PATH; a horizon-client next to horizon-ctl (a build folder, a release folder or a launcher install); the newest version installed by the Horizon launcher (--version TAG picks one). Launcher installs run with their prepared resources and keep saves in the game home ($HORIZON_HOME, else ~/.local/share/horizon). --wait also waits until the player has spawned and chunks are loaded. Other arguments go to the game (horizon-client --help lists them). The game's output goes to a .log file beside the socket.",
+        ["horizon-ctl launch --world Survival --seed 42 --wait", "horizon-ctl launch --world Flat --creative --render-distance 8"],
+        &[flag("world", Ty::Str, "world folder to open or create"), flag("seed", Ty::Str, "seed for a new world"), flag("creative", Ty::Bool, "creative mode for a new world"),
+          flag("version", Ty::Str, "an installed launcher version tag such as v2026.10.13"), flag("game", Ty::Str, "path to a horizon-client binary"),
+          flag("wait", Ty::Bool, "also wait until the world is ready (default in MCP)")],
+        mcp: true, local: true),
+    cmd!("wait-ready", Session, "wait-ready [SECONDS]", "wait until the player has spawned and no chunks are pending",
+        "Polls status every 250 ms; replies with the status, or an error after SECONDS (default 120).",
+        ["horizon-ctl wait-ready 300"], &[opt("seconds", Ty::Num, "how long to wait (default 120)")], mcp: true, local: true),
+    cmd!("logs", Session, "logs [--lines N] [--crash]", "the end of the game's log, or its newest crash report",
+        "Reads the game home ($HORIZON_HOME, else ~/.local/share/horizon): logs/latest.log (the last N lines, default 100) or, with --crash, the newest file in crash-reports. Read-only; works whether the game runs or not.",
+        ["horizon-ctl logs", "horizon-ctl logs --lines 300", "horizon-ctl logs --crash"],
+        &[flag("lines", Ty::Int, "how many lines of latest.log (default 100)"), flag("crash", Ty::Bool, "the newest crash report instead")],
+        mcp: true, local: true),
+    cmd!("status", Session, "status", "game, renderer and streaming state (the scripting socket's original summary)",
+        "", ["horizon-ctl status"], &[], mcp: false, local: false),
+    cmd!("open", Session, "open WORLD [SEED] [creative]", "open or create a world from the title screen",
+        "Opens saves/WORLD, creating it with SEED (and creative mode) when it doesn't exist.",
+        ["horizon-ctl open Test 12345", "horizon-ctl open Build 0 creative"],
+        &[p("world", Ty::Str, "world folder"), opt("seed", Ty::Int, "seed for a new world"), opt("mode", Ty::Enum(&["creative"]), "creative for a creative world")], mcp: true, local: false),
+    cmd!("save", Session, "save", "save the world", "", ["horizon-ctl save"], &[], mcp: true, local: false),
+    cmd!("quit", Session, "quit", "save and exit the game", "", ["horizon-ctl quit"], &[], mcp: true, local: false),
+    cmd!("screenshot", Session, "screenshot PATH", "write the next rendered frame as a PNG",
+        "Relative paths are taken from horizon-ctl's directory. Over MCP the image is returned directly.",
+        ["horizon-ctl screenshot view.png"], &[], mcp: true, local: false),
+    // Observe
+    cmd!("state", Observe, "state", "player, world, screen and crosshair target in one reply",
+        "position, block_pos, eye, yaw, pitch, velocity, on_ground, health, food, saturation, xp, effects, gamemode, dimension, time, weather, the screen or title menu, the held item, what the crosshair points at and whether an action is running.",
+        ["horizon-ctl state"], &[], mcp: true, local: false),
+    cmd!("looking-at", Observe, "looking-at", "the block or entity under the crosshair",
+        "kind is block, entity or none; a block has pos, state, face, point and distance; an entity has id, type, health and distance.",
+        ["horizon-ctl looking-at"], &[], mcp: true, local: false),
+    cmd!("entities", Observe, "entities [RADIUS] [TYPE]", "mobs, dropped items and experience orbs near the player, nearest first",
+        "RADIUS defaults to 32. TYPE filters by entity type (pig, minecraft:item, ...). Mobs have an id for look-at entity and attack.",
+        ["horizon-ctl entities", "horizon-ctl entities 16 cow", "horizon-ctl entities 8 item"],
+        &[opt("radius", Ty::Num, "search radius in blocks (default 32)"), opt("type", Ty::Str, "entity type filter")], mcp: true, local: false),
+    cmd!("block", Observe, "block X Y Z", "the block state at a position", "",
+        ["horizon-ctl block 10 64 -3"], &BLOCK_XYZ, mcp: true, local: false),
+    cmd!("blocks", Observe, "blocks X1 Y1 Z1 X2 Y2 Z2", "the non-air blocks of a box, with counts per block",
+        "At most 32768 blocks per request.", ["horizon-ctl blocks 0 60 0 15 70 15"],
+        &[p("x1", Ty::Int, "corner X"), p("y1", Ty::Int, "corner Y"), p("z1", Ty::Int, "corner Z"), p("x2", Ty::Int, "opposite X"), p("y2", Ty::Int, "opposite Y"), p("z2", Ty::Int, "opposite Z")], mcp: true, local: false),
+    cmd!("find-block", Observe, "find-block BLOCK [RADIUS]", "the nearest loaded blocks of a kind",
+        "Searches a cube of RADIUS (default 32, at most 64) around the player; returns the count and the 16 nearest.",
+        ["horizon-ctl find-block oak_log", "horizon-ctl find-block diamond_ore 48"],
+        &[p("block", Ty::Str, "block id such as oak_log"), opt("radius", Ty::Int, "search radius (default 32)")], mcp: true, local: false),
+    cmd!("inventory", Observe, "inventory", "hotbar, main inventory, armor, offhand, carried stack and item counts",
+        "Slots carry the ids click-slot takes: 0-8 hotbar, 9-35 inventory, 500-503 armor (head to feet), 504 offhand. Stacks with components list them as SNBT.",
+        ["horizon-ctl inventory"], &[], mcp: true, local: false),
+    cmd!("screen", Observe, "screen", "the open screen or title menu, its buttons and its slots",
+        "buttons are what click-button takes; slots are what click-slot takes (crafting grid 100-103 in the inventory, 100-108 at a crafting table, result 200, containers from 300, stations from 600). On the title screen, menu has the mode, worlds and the create-world fields.",
+        ["horizon-ctl screen"], &[], mcp: true, local: false),
+    cmd!("messages", Observe, "messages [N]", "recent chat and system messages, the title and the action bar",
+        "N defaults to 20; chat is newest first.", ["horizon-ctl messages 5"], &[opt("n", Ty::Int, "how many chat lines (default 20)")], mcp: true, local: false),
+    cmd!("menu", Observe, "menu", "the open menu's slots and carried stack, with station details", "",
+        ["horizon-ctl menu"], &[], mcp: false, local: false),
+    // Move
+    cmd!("move", Move, "move forward|back|left|right SECONDS [--sprint] [--sneak] [--jump]", "walk in a direction relative to the view for a time",
+        "Replies when done with the start and end positions.",
+        ["horizon-ctl move forward 2", "horizon-ctl move forward 1.5 --sprint --jump"],
+        &[p("direction", Ty::Enum(&["forward", "back", "left", "right"]), "direction relative to the view"), p("seconds", Ty::Num, "how long to walk"),
+          flag("sprint", Ty::Bool, "sprint"), flag("sneak", Ty::Bool, "sneak"), flag("jump", Ty::Bool, "keep jumping")], mcp: true, local: false),
+    cmd!("goto", Move, "goto X Y Z [--near R] [--sprint] [--direct] [--timeout S]", "walk to a position, finding a path through loaded terrain",
+        "A* over standable blocks (steps up one block, drops up to three, avoids lava, swims when it must), then steering with jumps when stuck. Without a path it fails at once (--direct walks straight at the target anyway, falls included). --near R stops within R blocks (use 1.5-3 to reach a block you then break). Replies with arrived, position and distance, or an error when stuck or out of time (default 60 s).",
+        ["horizon-ctl goto 120 70 -40", "horizon-ctl goto 8 64 3 --near 2 --sprint"],
+        &[XYZ[0], XYZ[1], XYZ[2], flag("near", Ty::Num, "arrive within this many blocks (default 0.6)"), flag("sprint", Ty::Bool, "sprint"), flag("direct", Ty::Bool, "walk straight when no path is found"), flag("timeout", Ty::Num, "give up after this many seconds (default 60)")], mcp: true, local: false),
+    cmd!("jump", Move, "jump", "jump once and reply when landed", "", ["horizon-ctl jump"], &[], mcp: true, local: false),
+    cmd!("look", Move, "look YAW PITCH", "set the view direction in degrees",
+        "Yaw 0 faces south (+Z), 90 west (-X), 180 north, -90 east; pitch 90 looks straight down.",
+        ["horizon-ctl look 90 10"], &[p("yaw", Ty::Num, "yaw in degrees"), p("pitch", Ty::Num, "pitch in degrees (-90 up .. 90 down)")], mcp: true, local: false),
+    cmd!("turn", Move, "turn DYAW DPITCH [--over S]", "rotate the view by an amount",
+        "Without --over the view jumps. With --over S the turn is mouse motion fed over S seconds with ease-in-out, through the same path as a real mouse (sensitivity, inverted axes, cinematic camera), and the reply comes once it is done.",
+        ["horizon-ctl turn 45 0", "horizon-ctl turn -90 10 --over 0.5"],
+        &[p("dyaw", Ty::Num, "yaw change in degrees"), p("dpitch", Ty::Num, "pitch change in degrees"), OVER], mcp: true, local: false),
+    cmd!("mouse-move", Move, "mouse-move DX DY", "move the mouse: relative motion that turns the view like a player's mouse",
+        "DX and DY are mouse units (pixels of relative motion) added to the frame's accumulated movement and turned by MouseHandler.turnPlayer: degrees = units x 0.15 x (sensitivity x 0.6 + 0.2)^3 x 8 (without the 8 while scoping), inverted axes and the cinematic camera included. Positive DX turns right, positive DY looks down. Works in the world with no screen open; replies with yaw and pitch after the frame that turned.",
+        ["horizon-ctl mouse-move 100 0", "horizon-ctl mouse-move -25 40"],
+        &[p("dx", Ty::Num, "horizontal motion (positive turns right)"), p("dy", Ty::Num, "vertical motion (positive looks down)")], mcp: true, local: false),
+    cmd!("look-at", Move, "look-at X Y Z | look-at block X Y Z [FACE] | look-at entity ID  [--over S]", "turn to face a point, a block (a visible face of it) or an entity",
+        "look-at block aims at a face the crosshair can reach and fails when none is visible. --over S turns there with mouse motion over S seconds (the shorter way round) instead of jumping.",
+        ["horizon-ctl look-at 10.5 65 3.5", "horizon-ctl look-at block 10 64 3 up", "horizon-ctl look-at entity 42 --over 0.4"],
+        &[XYZ[0], XYZ[1], XYZ[2], OVER], mcp: true, local: false),
+    cmd!("look-at-block", Move, "look-at-block X Y Z [FACE] [--over S]", "aim the crosshair at a block (same as look-at block)", "",
+        ["horizon-ctl look-at-block 10 64 3", "horizon-ctl look-at-block 10 64 3 up --over 0.3"], &[BLOCK_XYZ[0], BLOCK_XYZ[1], BLOCK_XYZ[2], opt("face", FACE, "which face to aim at"), OVER], mcp: true, local: false, wire: "look-at block"),
+    cmd!("look-at-entity", Move, "look-at-entity ID [--over S]", "face an entity (same as look-at entity)", "",
+        ["horizon-ctl look-at-entity 42"], &[p("id", Ty::Int, "entity id from entities"), OVER], mcp: true, local: false, wire: "look-at entity"),
+    cmd!("tp", Move, "tp X Y Z", "teleport the player", "", ["horizon-ctl tp 0 80 0"], &XYZ, mcp: true, local: false),
+    // Act
+    cmd!("break", Act, "break X Y Z [--timeout S]", "mine a block, holding the attack button until it breaks",
+        "Aims at a visible face (the block must be within reach: use goto --near 2 first), mines with the held item, then waits up to a second for the drops. Replies with block_before, block, ticks, drops and picked_up (inventory change).",
+        ["horizon-ctl break 10 64 3"], &[BLOCK_XYZ[0], BLOCK_XYZ[1], BLOCK_XYZ[2], flag("timeout", Ty::Num, "give up after this many seconds (default 30)")], mcp: true, local: false),
+    cmd!("place", Act, "place X Y Z [--item ITEM]", "place the held item (or ITEM from the hotbar) at an empty position",
+        "Clicks the face of a solid neighbour touching X Y Z. Replies with the block placed and the inventory change.",
+        ["horizon-ctl place 10 64 4 --item oak_planks"], &[BLOCK_XYZ[0], BLOCK_XYZ[1], BLOCK_XYZ[2], flag("item", Ty::Str, "hotbar item to select first")], mcp: true, local: false),
+    cmd!("interact", Act, "interact X Y Z [FACE]", "right-click a block: open a chest or crafting table, press a button, open a door",
+        "Replies with the screen afterwards and whether the block changed.", ["horizon-ctl interact 5 64 2"],
+        &[BLOCK_XYZ[0], BLOCK_XYZ[1], BLOCK_XYZ[2], opt("face", FACE, "which face to click")], mcp: true, local: false),
+    cmd!("use-item", Act, "use-item [--hold SECONDS]", "right-click with the held item: eat, drink, throw, draw a bow",
+        "Hold for 1.7 s to eat.", ["horizon-ctl use-item --hold 1.7"], &[flag("hold", Ty::Num, "hold the button this long")], mcp: true, local: false),
+    cmd!("attack", Act, "attack [ID]", "swing at what the crosshair targets (after facing entity ID)",
+        "Replies with the target's health before and after.", ["horizon-ctl attack", "horizon-ctl attack 42"],
+        &[opt("id", Ty::Int, "entity id to face first")], mcp: true, local: false),
+    cmd!("select", Act, "select SLOT|ITEM", "select a hotbar slot 1-9, or the hotbar slot holding ITEM", "",
+        ["horizon-ctl select 3", "horizon-ctl select oak_planks"], &[p("slot", Ty::Str, "1-9 or an item id")], mcp: true, local: false),
+    cmd!("drop", Act, "drop [all]", "drop one of the held item, or the whole stack", "", ["horizon-ctl drop", "horizon-ctl drop all"],
+        &[opt("all", Ty::Bool, "drop the whole stack")], mcp: true, local: false),
+    cmd!("hold", Act, "hold KEY SECONDS", "press a key, wait, release it", "Keys as for key.", ["horizon-ctl hold w 2"],
+        &[p("key", Ty::Str, "key name"), p("seconds", Ty::Num, "how long")], mcp: false, local: true),
+    cmd!("key", Act, "key KEY down|up|tap", "press or release a key (w a s d space shift ctrl e q esc f3 1-9 arrows ...)", "",
+        ["horizon-ctl key space tap"], &[p("key", Ty::Str, "key name"), p("action", Ty::Enum(&["down", "up", "tap"]), "what to do")], mcp: true, local: false),
+    cmd!("mouse", Act, "mouse left|right|middle down|up|click", "press or release a mouse button in the world", "",
+        ["horizon-ctl mouse right click"], &[p("button", Ty::Enum(&["left", "right", "middle"]), "button"), p("action", Ty::Enum(&["down", "up", "click"]), "what to do")], mcp: false, local: false),
+    cmd!("pad", Act, "pad BUTTON down|up|tap | pad stick left|right X Y | pad trigger left|right V | pad release | pad status", "a virtual controller: buttons, sticks and triggers as a real pad would send them",
+        "Buttons by position: south east west north lb rb lt rt select start ls rs up down left right (south is Xbox A / PlayStation cross). Sticks run -1..1 with up positive and stay tilted until centred; triggers 0..1. Merged with any real controller; status lists the connected ones and what is held.",
+        ["horizon-ctl pad south tap", "horizon-ctl pad stick left 0 1", "horizon-ctl pad trigger right 1", "horizon-ctl pad status"],
+        &[p("what", Ty::Str, "a button name, stick, trigger, release or status"), opt("a", Ty::Str, "down|up|tap, or left|right"), opt("b", Ty::Num, "stick X or trigger value"), opt("c", Ty::Num, "stick Y")], mcp: false, local: false),
+    cmd!("release", Act, "release", "release every key and mouse button", "", ["horizon-ctl release"], &[], mcp: false, local: false),
+    cmd!("stop", Act, "stop", "cancel the running action (goto, break...) and release every key", "", ["horizon-ctl stop"], &[], mcp: true, local: false),
+    // Screens
+    cmd!("open-inventory", Screens, "open-inventory", "open the inventory screen (crafting grid 100-103, result 200)", "",
+        ["horizon-ctl open-inventory"], &[], mcp: true, local: false),
+    cmd!("click-slot", Screens, "click-slot SLOT [right] [shift]", "click a slot of the open inventory or menu",
+        "SLOT ids as listed by screen: 0-8 hotbar, 9-35 inventory, 100+ crafting grid, 200 result, 300+ container, 500-503 armor, 504 offhand, 600+ station. A left click picks up or puts down the carried stack; right puts down one item; shift moves the stack across.",
+        ["horizon-ctl click-slot 36", "horizon-ctl click-slot 100 right", "horizon-ctl click-slot 200 shift"],
+        &[p("slot", Ty::Int, "slot id"), opt("right", Ty::Bool, "right-click"), opt("shift", Ty::Bool, "shift-click")], mcp: true, local: false),
+    cmd!("close", Screens, "close", "close the open menu and return to the game", "", ["horizon-ctl close"], &[], mcp: true, local: false),
+    cmd!("click-button", Screens, "click-button LABEL", "click a button of the open screen or title menu by its label",
+        "Case-insensitive; a unique part of the label is enough. screen lists the buttons.",
+        ["horizon-ctl click-button Singleplayer", "horizon-ctl click-button \"Create New World\"", "horizon-ctl click-button respawn"],
+        &[p("label", Ty::Rest, "button label")], mcp: true, local: false),
+    cmd!("click-at", Screens, "click-at X Y [right]", "click at GUI pixel X Y of the window (screen gives button rectangles)", "",
+        ["horizon-ctl click-at 200 120"], &[p("x", Ty::Num, "GUI x"), p("y", Ty::Num, "GUI y"), opt("right", Ty::Bool, "right-click")], mcp: true, local: false),
+    cmd!("type", Screens, "type [--field name|seed] [--replace] TEXT", "type into the focused text field (chat box, world name, anvil, sign...)",
+        "On the title's create-world screen, --field name|seed picks the field and --replace clears it first; type \\b deletes one character.",
+        ["horizon-ctl type hello everyone", "horizon-ctl type --field name --replace Agent World", "horizon-ctl type --field seed 12345"], &[flag("field", Ty::Enum(&["name", "seed"]), "create-world field to type into"), flag("replace", Ty::Bool, "clear the field first"), p("text", Ty::Rest, "text to type")], mcp: true, local: false),
+    cmd!("chat", Screens, "chat TEXT", "send a chat line (or a /command) as if typed", "", ["horizon-ctl chat hello"],
+        &[p("text", Ty::Rest, "message")], mcp: true, local: false),
+    cmd!("command", Screens, "command TEXT", "run a command (the leading / is optional)", "",
+        ["horizon-ctl command time set day", "horizon-ctl command /give @s oak_log 4"], &[p("command", Ty::Rest, "command line")], mcp: true, local: false),
+    cmd!("respawn", Screens, "respawn", "respawn from the death screen", "", ["horizon-ctl respawn"], &[], mcp: true, local: false),
+    cmd!("pause", Screens, "pause", "open the pause menu", "", ["horizon-ctl pause"], &[], mcp: true, local: false),
+    cmd!("resume", Screens, "resume", "leave the pause menu", "", ["horizon-ctl resume"], &[], mcp: true, local: false),
+    cmd!("chat-log", Screens, "chat-log [N]", "the newest N chat messages", "", ["horizon-ctl chat-log 5"], &[], mcp: false, local: false),
+    // World
+    cmd!("give", World, "give ITEM [COUNT]", "add items to the inventory", "", ["horizon-ctl give oak_log 16"],
+        &[p("item", Ty::Str, "item id"), opt("count", Ty::Int, "how many (default 1)")], mcp: true, local: false),
+    cmd!("time", World, "time TICKS", "set the time of day (0 sunrise, 6000 noon, 13000 night)", "", ["horizon-ctl time 6000"],
+        &[p("ticks", Ty::Int, "day time")], mcp: true, local: false),
+    cmd!("setblock", World, "setblock X Y Z BLOCK[props]", "set a block (with neighbour updates)", "", ["horizon-ctl setblock 0 64 0 stone"],
+        &[BLOCK_XYZ[0], BLOCK_XYZ[1], BLOCK_XYZ[2], p("block", Ty::Str, "block state such as oak_stairs[facing=east]")], mcp: true, local: false),
+    cmd!("summon", World, "summon KIND [X Y Z] [baby]", "spawn a mob", "", ["horizon-ctl summon cow"], &[p("kind", Ty::Str, "mob type")], mcp: true, local: false),
+    cmd!("effect", World, "effect ID SECONDS [AMPLIFIER] | effect clear", "give a status effect", "", ["horizon-ctl effect speed 30 1"], &[], mcp: false, local: false),
+    cmd!("render-distance", World, "render-distance N", "chunks, 2..64", "", ["horizon-ctl render-distance 8"], &[p("chunks", Ty::Int, "render distance")], mcp: false, local: false),
+    cmd!("wait", World, "wait TICKS", "wait until TICKS game ticks have passed (20 per second)", "", ["horizon-ctl wait 40"],
+        &[p("ticks", Ty::Int, "game ticks")], mcp: true, local: false),
+    // Scripting
+    cmd!("script", Scripting, "script [FILE] [--keep-going]", "run commands from FILE (or stdin), one per line",
+        "Lines are split like a shell (quotes keep spaces); # starts a comment; sleep SECONDS waits. Stops at the first error unless --keep-going. horizon-ctl - is the older form: read stdin and keep going.",
+        ["horizon-ctl script play.txt", "printf 'state\\ngoto 0 64 0\\n' | horizon-ctl script"], &[], mcp: false, local: true),
+    cmd!("sleep", Scripting, "sleep SECONDS", "wait (in scripts)", "", ["sleep 0.5"], &[], mcp: false, local: true),
+    cmd!("mcp", Scripting, "mcp", "serve the Model Context Protocol on stdin/stdout, one tool per command",
+        "Add it to an MCP client as a stdio server: command horizon-ctl, args [\"mcp\"] (with --socket PATH first if needed). The screenshot tool returns the image.",
+        ["horizon-ctl mcp"], &[], mcp: false, local: true),
+    cmd!("bench", Scripting, "bench SECONDS", "reset frame stats, wait, reply with the summary", "", ["horizon-ctl bench 10"], &[], mcp: false, local: false),
+    cmd!("stats", Scripting, "stats [reset]", "frame-time summary since the last reset", "", ["horizon-ctl stats"], &[], mcp: false, local: false),
+    cmd!("fly", Scripting, "fly X1 Y1 Z1 X2 Y2 Z2 SECONDS [PITCH [raw]]", "fly the camera along a line, then reply with the frame summary",
+        "With raw, the reply also lists every frame time in milliseconds (frame_ms).",
+        ["horizon-ctl fly 0 100 0 500 100 0 20"], &[], mcp: false, local: false),
+];
+
+pub fn find(name: &str) -> Option<&'static Cmd> {
+    COMMANDS.iter().find(|c| c.name == name)
+}
+
+/// `horizon-ctl help`.
+pub fn overview() -> String {
+    let mut out = String::from(
+        "horizon-ctl: play and script a running Horizon from the command line.\n\n\
+         usage: horizon-ctl [--socket PATH] [--timeout SECONDS] [--pretty] COMMAND [ARGS...]\n\
+         \x20      horizon-ctl COMMAND --help      (or: horizon-ctl help COMMAND)\n",
+    );
+    for group in Group::ALL {
+        out.push_str(&format!("\n{}:\n", group.title()));
+        for c in COMMANDS.iter().filter(|c| c.group == group) {
+            out.push_str(&format!("  {:<16} {}\n", c.name, c.summary));
+        }
+    }
+    out.push_str(
+        "\nEvery reply is one JSON line. Errors are {\"error\": \"...\"}; the exit status is 0 on\n\
+         success, 1 when the game replied with an error, 2 for a usage error and 3 when the\n\
+         game cannot be reached or started. Actions (goto, break, place...) block until done.\n\
+         horizon-ctl help --game lists the running game's own commands, test hooks included.\n\
+         The socket is $HORIZON_CONTROL, else $XDG_RUNTIME_DIR/horizon-control.sock (on Windows\n\
+         %TEMP%\\horizon-control.json, a localhost TCP port with a token; any path ending in .json\n\
+         uses that transport).\n\n\
+         First steps:\n\
+         \x20 horizon-ctl launch --world Test --seed 1 --wait\n\
+         \x20 horizon-ctl state\n\
+         \x20 horizon-ctl find-block oak_log\n\
+         \x20 horizon-ctl goto X Y Z --near 2 && horizon-ctl break X Y Z\n\
+         \x20 horizon-ctl inventory\n",
+    );
+    out
+}
+
+/// `horizon-ctl COMMAND --help`.
+pub fn detail(c: &Cmd) -> String {
+    let mut out = format!(
+        "usage: horizon-ctl {}\n\n{}.\n",
+        c.usage,
+        capitalize(c.summary)
+    );
+    if !c.details.is_empty() {
+        out.push('\n');
+        out.push_str(&wrap(c.details, 78));
+    }
+    if !c.examples.is_empty() {
+        out.push_str("\nExamples:\n");
+        for e in c.examples {
+            out.push_str(&format!("  {e}\n"));
+        }
+    }
+    out
+}
+
+fn capitalize(s: &str) -> String {
+    let mut chars = s.chars();
+    chars
+        .next()
+        .map(|c| c.to_uppercase().chain(chars).collect())
+        .unwrap_or_default()
+}
+
+fn wrap(text: &str, width: usize) -> String {
+    let mut out = String::new();
+    let mut line = String::new();
+    for word in text.split_whitespace() {
+        if !line.is_empty() && line.len() + 1 + word.len() > width {
+            out.push_str(&line);
+            out.push('\n');
+            line.clear();
+        }
+        if !line.is_empty() {
+            line.push(' ');
+        }
+        line.push_str(word);
+    }
+    if !line.is_empty() {
+        out.push_str(&line);
+        out.push('\n');
+    }
+    out
+}
+
+/// The MCP tool name of a command (`look-at-block` gives `look_at_block`).
+pub fn tool_name(c: &Cmd) -> String {
+    c.name.replace('-', "_")
+}
+
+/// The JSON schema of a command's arguments.
+pub fn schema(c: &Cmd) -> Value {
+    let mut props = Map::new();
+    let mut required = Vec::new();
+    for p in c.params {
+        let mut s = match p.ty {
+            Ty::Int => json!({ "type": "integer" }),
+            Ty::Num => json!({ "type": "number" }),
+            Ty::Str | Ty::Rest => json!({ "type": "string" }),
+            Ty::Bool => json!({ "type": "boolean" }),
+            Ty::Enum(values) => json!({ "type": "string", "enum": values }),
+        };
+        s["description"] = json!(p.help);
+        props.insert(p.name.to_owned(), s);
+        if p.required {
+            required.push(p.name);
+        }
+    }
+    json!({ "type": "object", "properties": props, "required": required })
+}
+
+/// The command line for an MCP call's arguments: positional values in order,
+/// then `--flag value` options.
+pub fn line_for(c: &Cmd, args: &Value) -> Result<Vec<String>, String> {
+    let mut words: Vec<String> = c
+        .wire
+        .unwrap_or(c.name)
+        .split(' ')
+        .map(str::to_owned)
+        .collect();
+    let mut flags = Vec::new();
+    let mut gap: Option<&str> = None;
+    let mut rest: Option<String> = None;
+    for p in c.params {
+        let value = args.get(p.name).filter(|v| !v.is_null());
+        let text = match value {
+            None => {
+                if p.required {
+                    return Err(format!("{} is required", p.name));
+                }
+                if !p.flag {
+                    gap.get_or_insert(p.name);
+                }
+                continue;
+            }
+            Some(Value::Bool(b)) => {
+                if p.ty != Ty::Bool {
+                    return Err(format!("{} must be a {}", p.name, ty_name(p.ty)));
+                }
+                if *b {
+                    if p.flag {
+                        flags.push(format!("--{}", p.name));
+                    } else {
+                        words.push(p.name.to_owned());
+                    }
+                }
+                continue;
+            }
+            Some(Value::String(s)) => s.clone(),
+            Some(Value::Number(n)) => n.to_string(),
+            Some(other) => {
+                return Err(format!(
+                    "{} must be a {}, not {other}",
+                    p.name,
+                    ty_name(p.ty)
+                ));
+            }
+        };
+        match p.ty {
+            Ty::Int if text.parse::<i64>().is_err() => {
+                return Err(format!("{} must be an integer, not {text}", p.name));
+            }
+            Ty::Num if text.parse::<f64>().is_err() => {
+                return Err(format!("{} must be a number, not {text}", p.name));
+            }
+            Ty::Enum(values) if !values.contains(&text.as_str()) => {
+                return Err(format!("{} must be one of {values:?}, not {text}", p.name));
+            }
+            _ => {}
+        }
+        if p.flag {
+            flags.push(format!("--{}", p.name));
+            flags.push(text);
+        } else {
+            if let Some(missing) = gap {
+                return Err(format!("{} needs {missing} to be given too", p.name));
+            }
+            if p.ty == Ty::Rest {
+                rest = Some(text);
+            } else if text.contains(char::is_whitespace) || text.is_empty() {
+                return Err(format!("{} must be a single word", p.name));
+            } else {
+                words.push(text);
+            }
+        }
+    }
+    // Options go before free text, which runs to the end of the line.
+    words.extend(flags);
+    words.extend(rest);
+    Ok(words)
+}
+
+fn ty_name(ty: Ty) -> &'static str {
+    match ty {
+        Ty::Int => "integer",
+        Ty::Num => "number",
+        Ty::Bool => "boolean",
+        _ => "string",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn names_are_unique_and_documented() {
+        let mut seen = std::collections::HashSet::new();
+        for c in COMMANDS {
+            assert!(seen.insert(c.name), "duplicate command {}", c.name);
+            assert!(
+                c.usage.starts_with(c.name.split('-').next().unwrap()),
+                "{}",
+                c.name
+            );
+            assert!(
+                !c.summary.is_empty() && !c.examples.is_empty(),
+                "{}",
+                c.name
+            );
+        }
+    }
+
+    #[test]
+    fn mcp_arguments_become_command_lines() {
+        let goto = find("goto").unwrap();
+        let words = line_for(
+            goto,
+            &json!({ "x": 1.5, "y": 64, "z": -3, "near": 2, "sprint": true }),
+        )
+        .unwrap();
+        assert_eq!(
+            words,
+            ["goto", "1.5", "64", "-3", "--near", "2", "--sprint"]
+        );
+        assert!(
+            line_for(goto, &json!({ "x": 1, "y": 2 }))
+                .unwrap_err()
+                .contains("z is required")
+        );
+        assert!(line_for(goto, &json!({ "x": "a", "y": 2, "z": 3 })).is_err());
+        let block = find("look-at-block").unwrap();
+        assert_eq!(
+            line_for(block, &json!({ "x": 1, "y": 2, "z": 3, "face": "up" })).unwrap(),
+            ["look-at", "block", "1", "2", "3", "up"]
+        );
+        assert!(
+            line_for(
+                block,
+                &json!({ "x": 1, "y": 2, "z": 3, "face": "sideways" })
+            )
+            .is_err()
+        );
+        let turn = find("turn").unwrap();
+        assert_eq!(
+            line_for(turn, &json!({ "dyaw": -90, "dpitch": 10.5, "over": 0.5 })).unwrap(),
+            ["turn", "-90", "10.5", "--over", "0.5"]
+        );
+        let mouse = find("mouse-move").unwrap();
+        assert_eq!(tool_name(mouse), "mouse_move");
+        assert_eq!(
+            line_for(mouse, &json!({ "dx": -25, "dy": 40 })).unwrap(),
+            ["mouse-move", "-25", "40"]
+        );
+        assert_eq!(
+            line_for(block, &json!({ "x": 1, "y": 2, "z": 3, "over": 0.3 })).unwrap(),
+            ["look-at", "block", "1", "2", "3", "--over", "0.3"]
+        );
+        let button = find("click-button").unwrap();
+        assert_eq!(
+            line_for(button, &json!({ "label": "Create New World" })).unwrap(),
+            ["click-button", "Create New World"]
+        );
+        let slot = find("click-slot").unwrap();
+        assert_eq!(
+            line_for(slot, &json!({ "slot": 200, "shift": true })).unwrap(),
+            ["click-slot", "200", "shift"]
+        );
+        let open = find("open").unwrap();
+        assert!(
+            line_for(open, &json!({ "world": "A", "mode": "creative" }))
+                .unwrap_err()
+                .contains("seed")
+        );
+    }
+
+    #[test]
+    fn schemas_list_required_parameters() {
+        let s = schema(find("break").unwrap());
+        assert_eq!(s["required"], json!(["x", "y", "z"]));
+        assert_eq!(s["properties"]["timeout"]["type"], "number");
+        assert_eq!(tool_name(find("look-at-entity").unwrap()), "look_at_entity");
+    }
+
+    #[test]
+    fn help_mentions_every_command() {
+        let text = overview();
+        for c in COMMANDS {
+            assert!(text.contains(c.name));
+            assert!(detail(c).contains("usage: horizon-ctl"));
+        }
+    }
+}
@@ -0,0 +1,357 @@
+//! `horizon-ctl launch`: find a Horizon to start and start it with a control
+//! socket. Mirrors where the launcher puts things (launcher/src/backend.rs):
+//! versions under `<launcher home>/versions/<tag>`, each with its prepared
+//! resources in `.local/horizon-client/<minecraft version>` and run from the
+//! game home, where saves and options.txt live.
+use std::{
+    path::{Path, PathBuf},
+    process::{Command, Stdio},
+    thread,
+    time::{Duration, Instant},
+};
+
+use horizon_client::logging::{data_dir, game_home};
+use serde_json::{Value, json};
+
+#[cfg(windows)]
+const CLIENT: &str = "horizon-client.exe";
+#[cfg(not(windows))]
+const CLIENT: &str = "horizon-client";
+
+pub fn launcher_home() -> PathBuf {
+    match std::env::var_os("HORIZON_LAUNCHER_HOME").filter(|h| !h.is_empty()) {
+        Some(h) => PathBuf::from(h),
+        None => data_dir().join("horizon-launcher"),
+    }
+}
+/// `v2026.10.13.1` gives [2026, 10, 13, 1]; a pre-release suffix is ignored.
+pub fn version_parts(tag: &str) -> Vec<u64> {
+    tag.trim_start_matches('v')
+        .split('-')
+        .next()
+        .unwrap_or("")
+        .split('.')
+        .map(|p| p.parse().unwrap_or(0))
+        .collect()
+}
+
+/// Installed launcher versions, newest first.
+pub fn installed(versions: &Path) -> Vec<String> {
+    let mut tags: Vec<String> = std::fs::read_dir(versions)
+        .into_iter()
+        .flatten()
+        .flatten()
+        .filter(|e| e.path().join(".installed").exists() && e.path().join(CLIENT).exists())
+        .filter_map(|e| e.file_name().into_string().ok())
+        .collect();
+    tags.sort_by_key(|t| std::cmp::Reverse(version_parts(t)));
+    tags
+}
+
+/// A folder's prepared resources, as the launcher prepares them.
+pub fn prepared_resources(dir: &Path) -> Option<PathBuf> {
+    let version = std::fs::read_to_string(dir.join("research-lock.json"))
+        .ok()
+        .and_then(|t| serde_json::from_str::<Value>(&t).ok())
+        .and_then(|v| v["minecraft"]["version"].as_str().map(str::to_owned))
+        .unwrap_or_else(|| "26.3".into());
+    let resources = dir.join(".local/horizon-client").join(version);
+    resources
+        .join("horizon-resources.json")
+        .exists()
+        .then_some(resources)
+}
+
+#[derive(Debug, PartialEq)]
+pub struct Install {
+    pub game: PathBuf,
+    /// Passed as --resources unless the caller gave their own.
+    pub resources: Option<PathBuf>,
+    /// The working directory (the game home for prepared installs).
+    pub cwd: Option<PathBuf>,
+    pub source: &'static str,
+    pub version: Option<String>,
+}
+
+/// Which game to start: an explicit binary, the one beside horizon-ctl, or a
+/// launcher install.
+pub fn find(
+    game: Option<&Path>,
+    version: Option<&str>,
+    beside: Option<&Path>,
+    launcher: &Path,
+) -> Result<Install, String> {
+    let prepared = |dir: &Path, source, version| {
+        let resources = prepared_resources(dir);
+        Install {
+            game: dir.join(CLIENT),
+            cwd: resources.as_ref().map(|_| game_home()),
+            resources,
+            source,
+            version,
+        }
+    };
+    if let Some(game) = game {
+        if !game.is_file() {
+            return Err(format!("{} is not a file", game.display()));
+        }
+        let dir = game.parent().unwrap_or(Path::new("."));
+        let mut install = prepared(dir, "--game", None);
+        install.game = game.to_owned();
+        return Ok(install);
+    }
+    let versions = launcher.join("versions");
+    if version.is_none()
+        && let Some(dir) = beside
+        && dir.join(CLIENT).is_file()
+    {
+        return Ok(prepared(dir, "beside horizon-ctl", None));
+    }
+    let tags = installed(&versions);
+    let tag = match version {
+        Some(v) => {
+            let want = if v.starts_with('v') { v.to_owned() } else { format!("v{v}") };
+            tags.iter()
+                .find(|t| **t == want || **t == v)
+                .cloned()
+                .ok_or_else(|| format!("version {v} is not installed in {} (installed: {tags:?})", versions.display()))?
+        }
+        None => tags.first().cloned().ok_or_else(|| {
+            format!(
+                "no Horizon found: no horizon-client beside horizon-ctl and no version installed by the launcher in {}. Install one with the launcher (horizon-launcher install latest) or pass --game PATH.",
+                versions.display()
+            )
+        })?,
+    };
+    let dir = versions.join(&tag);
+    let install = prepared(&dir, "launcher", Some(tag.clone()));
+    if install.resources.is_none() {
+        return Err(format!(
+            "{tag} is installed but not prepared; prepare it in the launcher first (horizon-launcher prepare {tag})"
+        ));
+    }
+    Ok(install)
+}
+
+pub struct Options {
+    pub game: Option<PathBuf>,
+    pub version: Option<String>,
+    pub wait: bool,
+    pub game_args: Vec<String>,
+}
+
+pub fn parse(args: &[String]) -> Result<Options, String> {
+    let mut o = Options {
+        game: None,
+        version: None,
+        wait: false,
+        game_args: Vec::new(),
+    };
+    let mut i = 0;
+    while i < args.len() {
+        let value = |i: usize| {
+            args.get(i + 1)
+                .cloned()
+                .ok_or_else(|| format!("{} needs a value", args[i]))
+        };
+        match args[i].as_str() {
+            "--game" => {
+                o.game = Some(value(i)?.into());
+                i += 1;
+            }
+            "--version" => {
+                o.version = Some(value(i)?);
+                i += 1;
+            }
+            "--wait" | "--wait-ready" => o.wait = true,
+            other => o.game_args.push(other.to_owned()),
+        }
+        i += 1;
+    }
+    Ok(o)
+}
+
+/// Start the game and wait for its control endpoint; Ok(reply) or Err(reply).
+pub fn launch(socket: &Path, args: &[String]) -> Result<Value, Value> {
+    let o = parse(args).map_err(|e| json!({ "error": e, "kind": "usage" }))?;
+    if horizon_client::control::connect(socket).is_ok() {
+        return Err(json!({
+            "error": format!("a game is already listening on {}; quit it first or pass another --socket", socket.display()),
+            "kind": "connection",
+        }));
+    }
+    let exe = std::env::current_exe().ok();
+    let beside = exe.as_deref().and_then(Path::parent);
+    let install = find(
+        o.game.as_deref(),
+        o.version.as_deref(),
+        beside,
+        &launcher_home(),
+    )
+    .map_err(|e| json!({ "error": e, "kind": "launch" }))?;
+    let log = socket.with_extension("log");
+    let file = std::fs::File::create(&log)
+        .map_err(|e| json!({ "error": format!("{}: {e}", log.display()), "kind": "launch" }))?;
+    let mut cmd = Command::new(&install.game);
+    let gave_resources = o.game_args.iter().any(|a| a == "--resources");
+    if let Some(resources) = install.resources.as_ref().filter(|_| !gave_resources) {
+        cmd.arg("--resources").arg(resources);
+    }
+    if let Some(cwd) = &install.cwd {
+        let _ = std::fs::create_dir_all(cwd);
+        cmd.current_dir(cwd);
+    }
+    let stderr = file
+        .try_clone()
+        .map_err(|e| json!({ "error": e.to_string(), "kind": "launch" }))?;
+    let mut child = cmd
+        .args(&o.game_args)
+        .arg("--control-socket")
+        .arg(socket)
+        .stdin(Stdio::null())
+        .stdout(file)
+        .stderr(stderr)
+        .spawn()
+        .map_err(
+            |e| json!({ "error": format!("{}: {e}", install.game.display()), "kind": "launch" }),
+        )?;
+    let deadline = Instant::now() + Duration::from_secs(300);
+    let info = json!({
+        "pid": child.id(),
+        "socket": socket,
+        "log": log,
+        "game": install.game,
+        "source": install.source,
+        "version": install.version,
+        "resources": install.resources,
+        "home": install.cwd,
+    });
+    while Instant::now() < deadline {
+        if horizon_client::control::connect(socket).is_ok() {
+            let mut reply = json!({ "ok": true });
+            reply
+                .as_object_mut()
+                .unwrap()
+                .extend(info.as_object().unwrap().clone());
+            return Ok(reply);
+        }
+        if let Ok(Some(status)) = child.try_wait() {
+            let tail = std::fs::read_to_string(&log).unwrap_or_default();
+            let tail: Vec<&str> = tail.lines().rev().take(15).collect();
+            return Err(json!({
+                "error": format!("the game exited ({status}) before opening the control socket"),
+                "kind": "launch",
+                "log_tail": tail.into_iter().rev().collect::<Vec<_>>(),
+                "log": log,
+            }));
+        }
+        thread::sleep(Duration::from_millis(100));
+    }
+    Err(
+        json!({ "error": "control socket did not open within 300 seconds", "kind": "launch", "log": log }),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn temp(name: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!("horizon-ctl-{name}-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+    fn fake_version(versions: &Path, tag: &str, prepared: bool) -> PathBuf {
+        let dir = versions.join(tag);
+        std::fs::create_dir_all(&dir).unwrap();
+        std::fs::write(dir.join(CLIENT), "").unwrap();
+        std::fs::write(dir.join(".installed"), "").unwrap();
+        std::fs::write(
+            dir.join("research-lock.json"),
+            r#"{"minecraft":{"version":"26.3"}}"#,
+        )
+        .unwrap();
+        if prepared {
+            let res = dir.join(".local/horizon-client/26.3");
+            std::fs::create_dir_all(&res).unwrap();
+            std::fs::write(res.join("horizon-resources.json"), "{}").unwrap();
+        }
+        dir
+    }
+
+    #[test]
+    fn versions_sort_newest_first() {
+        let home = temp("sort");
+        let versions = home.join("versions");
+        for tag in ["v2026.9.30", "v2026.10.13", "v2026.10.13.1", "v2026.10.2"] {
+            fake_version(&versions, tag, true);
+        }
+        assert_eq!(
+            installed(&versions),
+            ["v2026.10.13.1", "v2026.10.13", "v2026.10.2", "v2026.9.30"]
+        );
+        let install = find(None, None, None, &home).unwrap();
+        assert_eq!(install.version.as_deref(), Some("v2026.10.13.1"));
+        assert!(
+            install
+                .resources
+                .unwrap()
+                .ends_with(".local/horizon-client/26.3")
+        );
+        assert_eq!(install.cwd, Some(game_home()));
+        let picked = find(None, Some("2026.10.2"), None, &home).unwrap();
+        assert_eq!(picked.version.as_deref(), Some("v2026.10.2"));
+        assert!(find(None, Some("v1.0"), None, &home).is_err());
+        let _ = std::fs::remove_dir_all(home);
+    }
+
+    #[test]
+    fn a_game_beside_ctl_wins_and_dev_builds_keep_the_directory() {
+        let home = temp("beside");
+        fake_version(&home.join("versions"), "v2026.10.13", true);
+        let build = temp("build");
+        std::fs::write(build.join(CLIENT), "").unwrap();
+        let install = find(None, None, Some(&build), &home).unwrap();
+        assert_eq!(install.source, "beside horizon-ctl");
+        assert_eq!((install.resources, install.cwd), (None, None));
+        // --version always means a launcher install.
+        assert_eq!(
+            find(None, Some("v2026.10.13"), Some(&build), &home)
+                .unwrap()
+                .source,
+            "launcher"
+        );
+        let _ = std::fs::remove_dir_all(home);
+        let _ = std::fs::remove_dir_all(build);
+    }
+
+    #[test]
+    fn unprepared_or_missing_installs_explain_themselves() {
+        let home = temp("unprepared");
+        assert!(
+            find(None, None, None, &home)
+                .unwrap_err()
+                .contains("no Horizon found")
+        );
+        fake_version(&home.join("versions"), "v2026.10.13", false);
+        assert!(
+            find(None, None, None, &home)
+                .unwrap_err()
+                .contains("not prepared")
+        );
+        let _ = std::fs::remove_dir_all(home);
+    }
+
+    #[test]
+    fn launch_options_pass_the_rest_to_the_game() {
+        let args: Vec<String> = ["--world", "A", "--version", "v1", "--wait", "--seed", "3"]
+            .map(String::from)
+            .to_vec();
+        let o = parse(&args).unwrap();
+        assert_eq!(o.version.as_deref(), Some("v1"));
+        assert!(o.wait);
+        assert_eq!(o.game_args, ["--world", "A", "--seed", "3"]);
+        assert!(parse(&["--game".to_owned()]).is_err());
+    }
+}
@@ -0,0 +1,585 @@
+//! horizon-ctl: play and script a running Horizon client through its control
+//! socket, from a shell, a script or an AI agent (`horizon-ctl mcp`).
+#![forbid(unsafe_code)]
+mod commands;
+mod launch;
+mod mcp;
+
+use std::{
+    io::{BufRead, BufReader, Write},
+    path::{Path, PathBuf},
+    process::ExitCode,
+    thread,
+    time::{Duration, Instant},
+};
+
+use horizon_client::control::Stream;
+use serde_json::{Value, json};
+
+/// Exit statuses.
+const GAME_ERROR: u8 = 1;
+const USAGE: u8 = 2;
+const UNREACHABLE: u8 = 3;
+
+/// A failure, with the exit status it maps to.
+#[derive(Debug)]
+pub struct Failure {
+    pub reply: Value,
+    pub status: u8,
+}
+impl Failure {
+    fn usage(message: impl Into<String>) -> Self {
+        Self {
+            reply: json!({ "error": message.into(), "kind": "usage" }),
+            status: USAGE,
+        }
+    }
+    fn unreachable(message: impl Into<String>) -> Self {
+        Self {
+            reply: json!({ "error": message.into(), "kind": "connection" }),
+            status: UNREACHABLE,
+        }
+    }
+}
+
+pub struct Client {
+    writer: Stream,
+    reader: BufReader<Stream>,
+}
+
+impl Client {
+    fn connect(path: &Path, timeout: Option<Duration>) -> Result<Self, Failure> {
+        let stream = horizon_client::control::connect(path).map_err(|e| {
+            Failure::unreachable(format!(
+                "cannot connect to {} ({e}); is the game running with --control? Start one with: horizon-ctl launch --world NAME",
+                path.display()
+            ))
+        })?;
+        stream
+            .set_read_timeout(timeout)
+            .map_err(|e| Failure::unreachable(e.to_string()))?;
+        let reader = BufReader::new(
+            stream
+                .try_clone()
+                .map_err(|e| Failure::unreachable(e.to_string()))?,
+        );
+        Ok(Self {
+            writer: stream,
+            reader,
+        })
+    }
+    /// Send one line and read its JSON reply.
+    fn send(&mut self, line: &str) -> Result<Value, Failure> {
+        writeln!(self.writer, "{line}").map_err(|e| Failure::unreachable(e.to_string()))?;
+        let mut reply = String::new();
+        let n = self.reader.read_line(&mut reply).map_err(|e| {
+            Failure::unreachable(
+                if matches!(
+                    e.kind(),
+                    std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut
+                ) {
+                    "timed out waiting for the game's reply (--timeout)".to_owned()
+                } else {
+                    e.to_string()
+                },
+            )
+        })?;
+        if n == 0 {
+            return Err(Failure::unreachable("the game closed the connection"));
+        }
+        serde_json::from_str(reply.trim_end()).map_err(|_| Failure {
+            reply: json!({ "error": "the game sent a reply that is not JSON", "reply": reply.trim_end() }),
+            status: GAME_ERROR,
+        })
+    }
+}
+
+/// Global options and the connection, opened on first use.
+pub struct Session {
+    pub socket: PathBuf,
+    pub timeout: Option<Duration>,
+    client: Option<Client>,
+}
+
+impl Session {
+    pub fn new(socket: PathBuf, timeout: Option<Duration>) -> Self {
+        Self {
+            socket,
+            timeout,
+            client: None,
+        }
+    }
+    fn client(&mut self) -> Result<&mut Client, Failure> {
+        if self.client.is_none() {
+            self.client = Some(Client::connect(&self.socket, self.timeout)?);
+        }
+        Ok(self.client.as_mut().unwrap())
+    }
+    /// Send a line to the game; a reply with "error" is a failure.
+    pub fn game(&mut self, line: &str) -> Result<Value, Failure> {
+        let result = self.client()?.send(line);
+        if result.as_ref().is_err_and(|f| f.status == UNREACHABLE) {
+            // Reconnect next time (the game may have restarted).
+            self.client = None;
+        }
+        let reply = result?;
+        if reply.get("error").is_some() {
+            return Err(Failure {
+                reply,
+                status: GAME_ERROR,
+            });
+        }
+        Ok(reply)
+    }
+
+    /// Run one command (CLI words); Ok(reply) or a failure.
+    pub fn run(&mut self, words: &[String]) -> Result<Value, Failure> {
+        let Some(name) = words.first().map(String::as_str) else {
+            return Err(Failure::usage("no command; try horizon-ctl help"));
+        };
+        if words.iter().skip(1).any(|w| w == "--help" || w == "-h") {
+            return Err(Failure::usage(
+                "use horizon-ctl COMMAND --help outside scripts",
+            ));
+        }
+        let number = |i: usize, what: &str| -> Result<f64, Failure> {
+            words
+                .get(i)
+                .ok_or_else(|| Failure::usage(format!("missing {what}; usage: {}", usage(name))))?
+                .parse::<f64>()
+                .map_err(|_| {
+                    Failure::usage(format!("{what} must be a number; usage: {}", usage(name)))
+                })
+        };
+        match name {
+            "sleep" => {
+                thread::sleep(Duration::from_secs_f64(number(1, "SECONDS")?.max(0.0)));
+                Ok(json!({ "ok": true }))
+            }
+            "launch" => {
+                let socket = self.socket.clone();
+                let wait = words.iter().any(|w| w == "--wait" || w == "--wait-ready");
+                let reply = launch::launch(&socket, &words[1..]).map_err(|reply| Failure {
+                    status: if reply["kind"] == "usage" {
+                        USAGE
+                    } else {
+                        UNREACHABLE
+                    },
+                    reply,
+                })?;
+                if !wait {
+                    return Ok(reply);
+                }
+                let mut ready = self.wait_ready(300.0)?;
+                ready["launch"] = reply;
+                Ok(ready)
+            }
+            "hold" => {
+                let (key, seconds) = match words {
+                    [_, key, _] => (key.clone(), number(2, "SECONDS")?),
+                    _ => return Err(Failure::usage(format!("usage: {}", usage(name)))),
+                };
+                self.game(&format!("key {key} down"))?;
+                thread::sleep(Duration::from_secs_f64(seconds.max(0.0)));
+                self.game(&format!("key {key} up"))
+            }
+            "logs" => logs(&horizon_client::logging::game_home(), &words[1..]),
+            "wait-ready" => {
+                let limit = if words.len() > 1 {
+                    number(1, "SECONDS")?
+                } else {
+                    120.0
+                };
+                self.wait_ready(limit)
+            }
+            "help" if words.get(1).is_some_and(|w| w == "--game") => self.game("help"),
+            _ => {
+                let mut words = words.to_vec();
+                if let Some(cmd) = commands::find(name) {
+                    if cmd.local {
+                        return Err(Failure::usage(format!(
+                            "{name} runs only as horizon-ctl {name}, not inside a script"
+                        )));
+                    }
+                    if let Some(wire) = cmd.wire {
+                        words.splice(0..1, wire.split(' ').map(str::to_owned));
+                    }
+                }
+                absolute_paths(&mut words);
+                self.game(&words.join(" "))
+            }
+        }
+    }
+
+    fn wait_ready(&mut self, limit: f64) -> Result<Value, Failure> {
+        let deadline = Instant::now() + Duration::from_secs_f64(limit.max(0.0));
+        loop {
+            let status = self.game("status")?;
+            if !status["player"].is_null() && status["pending_chunks"] == 0 {
+                return Ok(status);
+            }
+            if Instant::now() > deadline {
+                return Err(Failure {
+                    reply: json!({ "error": format!("not ready after {limit} seconds"), "status": status }),
+                    status: GAME_ERROR,
+                });
+            }
+            thread::sleep(Duration::from_millis(250));
+        }
+    }
+}
+
+/// `logs [--lines N] [--crash]` for the game in `home`: the reply's `text` is the log's last
+/// lines or the report.
+fn logs(home: &Path, words: &[String]) -> Result<Value, Failure> {
+    use horizon_client::logging;
+    let mut lines = 100;
+    let mut crash = false;
+    let mut it = words.iter();
+    while let Some(word) = it.next() {
+        match word.as_str() {
+            "--crash" => crash = true,
+            "--lines" => {
+                lines = it
+                    .next()
+                    .and_then(|n| n.parse::<usize>().ok())
+                    .filter(|&n| n > 0)
+                    .ok_or_else(|| Failure::usage("--lines takes a number above 0"))?;
+            }
+            other => {
+                return Err(Failure::usage(format!(
+                    "unknown argument {other}; usage: {}",
+                    usage("logs")
+                )));
+            }
+        }
+    }
+    let missing = |what: String| Failure {
+        reply: json!({ "error": what }),
+        status: GAME_ERROR,
+    };
+    if crash {
+        let path = logging::newest_crash_report(home).ok_or_else(|| {
+            missing(format!(
+                "no crash report in {}",
+                logging::crash_reports_dir(home).display()
+            ))
+        })?;
+        let text = std::fs::read_to_string(&path)
+            .map_err(|e| missing(format!("{}: {e}", path.display())))?;
+        return Ok(json!({ "path": path, "text": text }));
+    }
+    let path = logging::logs_dir(home).join("latest.log");
+    let tail =
+        logging::tail(&path, lines).map_err(|e| missing(format!("{}: {e}", path.display())))?;
+    Ok(json!({ "path": path, "text": tail.join("\n") + "\n" }))
+}
+
+fn usage(name: &str) -> String {
+    commands::find(name).map_or_else(|| name.to_owned(), |c| format!("horizon-ctl {}", c.usage))
+}
+
+/// Screenshot paths are written by the game process: make them absolute here.
+fn absolute_paths(words: &mut [String]) {
+    if words.first().map(String::as_str) == Some("screenshot")
+        && let Some(path) = words.get_mut(1)
+        && let Ok(cwd) = std::env::current_dir()
+    {
+        *path = cwd.join(&*path).display().to_string();
+    }
+}
+
+/// Split a script line like a shell: quotes keep spaces, backslash escapes.
+pub fn split_line(line: &str) -> Result<Vec<String>, String> {
+    let mut words = Vec::new();
+    let mut word = String::new();
+    let mut in_word = false;
+    let mut quote: Option<char> = None;
+    let mut chars = line.chars();
+    while let Some(c) = chars.next() {
+        match (quote, c) {
+            (Some(q), c) if c == q => quote = None,
+            (Some('"'), '\\') => word.push(chars.next().unwrap_or('\\')),
+            (Some(_), c) => word.push(c),
+            (None, '"' | '\'') => {
+                quote = Some(c);
+                in_word = true;
+            }
+            (None, '\\') => {
+                word.push(chars.next().unwrap_or('\\'));
+                in_word = true;
+            }
+            (None, '#') if !in_word => break,
+            (None, c) if c.is_whitespace() => {
+                if in_word {
+                    words.push(std::mem::take(&mut word));
+                    in_word = false;
+                }
+            }
+            (None, c) => {
+                word.push(c);
+                in_word = true;
+            }
+        }
+    }
+    if quote.is_some() {
+        return Err("unterminated quote".into());
+    }
+    if in_word {
+        words.push(word);
+    }
+    Ok(words)
+}
+
+fn print(value: &Value, pretty: bool) {
+    let text = if pretty {
+        serde_json::to_string_pretty(value).unwrap_or_default()
+    } else {
+        value.to_string()
+    };
+    println!("{text}");
+}
+
+/// Run a script; the exit status of the first failure (or the last one with --keep-going).
+fn script(session: &mut Session, reader: impl BufRead, keep_going: bool, pretty: bool) -> u8 {
+    let mut status = 0;
+    for (n, line) in reader.lines().enumerate() {
+        let Ok(line) = line else { break };
+        let words = match split_line(&line) {
+            Ok(w) if w.is_empty() => continue,
+            Ok(w) => w,
+            Err(e) => {
+                print(
+                    &json!({ "error": e, "kind": "usage", "line": n + 1 }),
+                    pretty,
+                );
+                status = USAGE;
+                if keep_going {
+                    continue;
+                }
+                break;
+            }
+        };
+        match session.run(&words) {
+            Ok(reply) => print(&reply, pretty),
+            Err(mut f) => {
+                f.reply["line"] = json!(n + 1);
+                print(&f.reply, pretty);
+                status = f.status;
+                if !keep_going || f.status == UNREACHABLE {
+                    break;
+                }
+            }
+        }
+    }
+    status
+}
+
+fn main() -> ExitCode {
+    let mut args: Vec<String> = std::env::args().skip(1).collect();
+    let mut socket = horizon_client::control::default_path();
+    let mut timeout = None;
+    let mut pretty = false;
+    // Global options before the command.
+    loop {
+        match args.first().map(String::as_str) {
+            Some("--socket") if args.len() >= 2 => {
+                socket = PathBuf::from(args.remove(1));
+                args.remove(0);
+            }
+            Some("--timeout") if args.len() >= 2 => {
+                let Ok(s) = args[1].parse::<f64>() else {
+                    print(
+                        &json!({ "error": "--timeout takes seconds", "kind": "usage" }),
+                        false,
+                    );
+                    return ExitCode::from(USAGE);
+                };
+                timeout = Some(Duration::from_secs_f64(s.max(0.001)));
+                args.drain(0..2);
+            }
+            Some("--pretty") => {
+                pretty = true;
+                args.remove(0);
+            }
+            _ => break,
+        }
+    }
+    let mut session = Session::new(socket, timeout);
+    let name = args.first().cloned();
+    let status = match name.as_deref() {
+        None | Some("-h" | "--help") => {
+            print!("{}", commands::overview());
+            0
+        }
+        Some("help") if args.get(1).is_none_or(|a| a != "--game") => match args.get(1) {
+            None => {
+                print!("{}", commands::overview());
+                0
+            }
+            Some(c) => match commands::find(c) {
+                Some(cmd) => {
+                    print!("{}", commands::detail(cmd));
+                    0
+                }
+                None => {
+                    print(
+                        &json!({ "error": format!("unknown command {c}; horizon-ctl help lists them, horizon-ctl help --game lists the game's own"), "kind": "usage" }),
+                        pretty,
+                    );
+                    USAGE
+                }
+            },
+        },
+        Some(c) if args.len() == 2 && matches!(args[1].as_str(), "--help" | "-h") => {
+            match commands::find(c) {
+                Some(cmd) => {
+                    print!("{}", commands::detail(cmd));
+                    0
+                }
+                None => {
+                    print(
+                        &json!({ "error": format!("no help for {c}; horizon-ctl help --game lists the game's own commands"), "kind": "usage" }),
+                        pretty,
+                    );
+                    USAGE
+                }
+            }
+        }
+        Some("mcp") => match mcp::serve(&mut session) {
+            Ok(()) => 0,
+            Err(e) => {
+                eprintln!("horizon-ctl mcp: {e}");
+                UNREACHABLE
+            }
+        },
+        // The original form: stdin, keep going after errors.
+        Some("-") => script(&mut session, std::io::stdin().lock(), true, pretty),
+        Some("script") => {
+            let keep_going = args.iter().any(|a| a == "--keep-going");
+            match args.iter().skip(1).find(|a| !a.starts_with("--")) {
+                Some(file) if file != "-" => match std::fs::File::open(file) {
+                    Ok(f) => script(&mut session, BufReader::new(f), keep_going, pretty),
+                    Err(e) => {
+                        print(
+                            &json!({ "error": format!("{file}: {e}"), "kind": "usage" }),
+                            pretty,
+                        );
+                        USAGE
+                    }
+                },
+                _ => script(&mut session, std::io::stdin().lock(), keep_going, pretty),
+            }
+        }
+        // Text for people; scripts and MCP get the JSON reply.
+        Some("logs") => match session.run(&args) {
+            Ok(reply) => {
+                print!("{}", reply["text"].as_str().unwrap_or_default());
+                0
+            }
+            Err(f) => {
+                print(&f.reply, pretty);
+                f.status
+            }
+        },
+        Some(_) => match session.run(&args) {
+            Ok(reply) => {
+                print(&reply, pretty);
+                0
+            }
+            Err(f) => {
+                print(&f.reply, pretty);
+                f.status
+            }
+        },
+    };
+    ExitCode::from(status)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn logs_reads_the_end_of_latest_log_and_the_newest_crash_report() {
+        let home = std::env::temp_dir().join(format!("horizon-ctl-logs-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&home);
+        let words = |s: &str| -> Vec<String> { s.split_whitespace().map(String::from).collect() };
+        let failure = logs(&home, &words("")).unwrap_err();
+        assert!(
+            failure.reply["error"]
+                .as_str()
+                .unwrap()
+                .contains("latest.log")
+        );
+        std::fs::create_dir_all(home.join("logs")).unwrap();
+        let text: String = (1..=150)
+            .map(|i| format!("[10:00:00] [Render thread/INFO]: line {i}\n"))
+            .collect();
+        std::fs::write(home.join("logs/latest.log"), text).unwrap();
+        let reply = logs(&home, &words("")).unwrap();
+        let tail = reply["text"].as_str().unwrap();
+        assert_eq!(tail.lines().count(), 100);
+        assert!(tail.starts_with("[10:00:00] [Render thread/INFO]: line 51\n"));
+        assert!(tail.ends_with("line 150\n"));
+        let reply = logs(&home, &words("--lines 2")).unwrap();
+        assert_eq!(
+            reply["text"],
+            "[10:00:00] [Render thread/INFO]: line 149\n[10:00:00] [Render thread/INFO]: line 150\n"
+        );
+        assert_eq!(logs(&home, &words("--lines 0")).unwrap_err().status, USAGE);
+        assert_eq!(logs(&home, &words("--tail")).unwrap_err().status, USAGE);
+        assert!(logs(&home, &words("--crash")).is_err());
+        std::fs::create_dir_all(home.join("crash-reports")).unwrap();
+        std::fs::write(
+            home.join("crash-reports/crash-2026-10-13_10.00.00-client.txt"),
+            "old",
+        )
+        .unwrap();
+        std::fs::write(
+            home.join("crash-reports/crash-2026-10-14_10.00.00-client.txt"),
+            "new",
+        )
+        .unwrap();
+        let reply = logs(&home, &words("--crash")).unwrap();
+        assert_eq!(reply["text"], "new");
+        let _ = std::fs::remove_dir_all(&home);
+    }
+
+    #[test]
+    fn script_lines_split_like_a_shell() {
+        assert_eq!(
+            split_line("goto 1 2 3 --near 2").unwrap(),
+            ["goto", "1", "2", "3", "--near", "2"]
+        );
+        assert_eq!(
+            split_line("click-button \"Create New World\"").unwrap(),
+            ["click-button", "Create New World"]
+        );
+        assert_eq!(
+            split_line("type 'it''s'  # comment").unwrap(),
+            ["type", "its"]
+        );
+        assert_eq!(split_line("chat a\\ b").unwrap(), ["chat", "a b"]);
+        assert_eq!(split_line("chat issue#4").unwrap(), ["chat", "issue#4"]);
+        assert!(split_line("   # only a comment").unwrap().is_empty());
+        assert!(split_line("type \"open").is_err());
+    }
+
+    #[test]
+    fn unreachable_games_fail_with_status_3() {
+        let mut s = Session::new(std::env::temp_dir().join("horizon-ctl-nobody.sock"), None);
+        let f = s.run(&["state".to_owned()]).unwrap_err();
+        assert_eq!(f.status, UNREACHABLE);
+        assert_eq!(f.reply["kind"], "connection");
+        let f = s.run(&["sleep".to_owned(), "x".to_owned()]).unwrap_err();
+        assert_eq!(f.status, USAGE);
+    }
+
+    #[test]
+    fn screenshot_paths_become_absolute() {
+        let mut words = vec!["screenshot".to_owned(), "a.png".to_owned()];
+        absolute_paths(&mut words);
+        assert!(Path::new(&words[1]).is_absolute());
+    }
+}
@@ -0,0 +1,254 @@
+//! `horizon-ctl mcp`: the Model Context Protocol over stdin and stdout
+//! (JSON-RPC 2.0, one message per line, like the launcher's `mcp`), so AI
+//! agents can play Horizon. Each tool is a horizon-ctl command from the
+//! shared table, run through the same `Session` as the CLI.
+use crate::{Session, commands};
+use serde_json::{Value, json};
+use std::io::{BufRead, Write};
+
+const PROTOCOL: &str = "2025-06-18";
+
+fn tools() -> Vec<Value> {
+    commands::COMMANDS
+        .iter()
+        .filter(|c| c.mcp)
+        .map(|c| {
+            let mut description = format!("{}. Usage: horizon-ctl {}", capital(c.summary), c.usage);
+            if !c.details.is_empty() {
+                description.push_str(". ");
+                description.push_str(c.details);
+            }
+            let mut schema = commands::schema(c);
+            if c.name == "screenshot" {
+                schema = json!({ "type": "object", "properties": {} });
+                description = "Capture the game window and return it as a PNG image.".into();
+            }
+            json!({ "name": commands::tool_name(c), "description": description, "inputSchema": schema })
+        })
+        .collect()
+}
+
+fn capital(s: &str) -> String {
+    let mut c = s.chars();
+    c.next()
+        .map(|f| f.to_uppercase().chain(c).collect())
+        .unwrap_or_default()
+}
+
+/// Standard base64 (RFC 4648) for image content.
+pub fn base64(bytes: &[u8]) -> String {
+    const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let mut out = String::with_capacity(bytes.len().div_ceil(3) * 4);
+    for chunk in bytes.chunks(3) {
+        let n = (u32::from(chunk[0]) << 16)
+            | (u32::from(*chunk.get(1).unwrap_or(&0)) << 8)
+            | u32::from(*chunk.get(2).unwrap_or(&0));
+        for i in 0..4 {
+            if i <= chunk.len() {
+                out.push(ALPHABET[(n >> (18 - 6 * i) & 63) as usize] as char);
+            } else {
+                out.push('=');
+            }
+        }
+    }
+    out
+}
+
+impl Session {
+    /// One tool call: (content blocks, is_error).
+    fn call(&mut self, name: &str, args: &Value) -> (Vec<Value>, bool) {
+        let text = |v: &Value| json!({ "type": "text", "text": serde_json::to_string_pretty(v).unwrap_or_default() });
+        let Some(cmd) = commands::COMMANDS
+            .iter()
+            .find(|c| c.mcp && commands::tool_name(c) == name)
+        else {
+            return (
+                vec![text(&json!({ "error": format!("unknown tool {name}") }))],
+                true,
+            );
+        };
+        if cmd.name == "screenshot" {
+            let path = std::env::temp_dir().join(format!("horizon-ctl-{}.png", std::process::id()));
+            let result = self
+                .run(&["screenshot".to_owned(), path.display().to_string()])
+                .and_then(|reply| {
+                    std::fs::read(&path)
+                        .map(|png| (reply, png))
+                        .map_err(|e| crate::Failure {
+                            reply: json!({ "error": format!("{}: {e}", path.display()) }),
+                            status: 1,
+                        })
+                });
+            let _ = std::fs::remove_file(&path);
+            return match result {
+                Ok((reply, png)) => (
+                    vec![
+                        json!({ "type": "image", "data": base64(&png), "mimeType": "image/png" }),
+                        text(&reply),
+                    ],
+                    false,
+                ),
+                Err(f) => (vec![text(&f.reply)], true),
+            };
+        }
+        if cmd.name == "logs" {
+            let words = match commands::line_for(cmd, args) {
+                Ok(w) => w,
+                Err(e) => return (vec![text(&json!({ "error": e, "kind": "usage" }))], true),
+            };
+            return match self.run(&words) {
+                Ok(reply) => (
+                    vec![
+                        json!({ "type": "text", "text": format!("{}\n\n{}", reply["path"].as_str().unwrap_or_default(), reply["text"].as_str().unwrap_or_default()) }),
+                    ],
+                    false,
+                ),
+                Err(f) => (vec![text(&f.reply)], true),
+            };
+        }
+        let mut words = match commands::line_for(cmd, args) {
+            Ok(w) => w,
+            Err(e) => return (vec![text(&json!({ "error": e, "kind": "usage" }))], true),
+        };
+        if cmd.name == "launch" {
+            // An agent wants a world it can play once the call returns.
+            if args.get("wait").and_then(Value::as_bool) != Some(false)
+                && !words.contains(&"--wait".to_owned())
+            {
+                words.push("--wait".into());
+            }
+            words.push("--no-pause".into());
+        }
+        match self.run(&words) {
+            Ok(reply) => (vec![text(&reply)], false),
+            Err(f) => (vec![text(&f.reply)], true),
+        }
+    }
+
+    fn handle(&mut self, method: &str, params: &Value) -> Result<Value, (i64, String)> {
+        match method {
+            "initialize" => Ok(json!({
+                "protocolVersion": params.get("protocolVersion").and_then(Value::as_str).unwrap_or(PROTOCOL),
+                "capabilities": { "tools": {} },
+                "serverInfo": { "name": "horizon-ctl", "version": env!("CARGO_PKG_VERSION") },
+                "instructions": "Play Horizon, a Rust reimplementation of Minecraft Java Edition. Start with launch (it finds the game installed by the Horizon launcher and opens or creates a world), then read the world with state, inventory, screen, entities and find_block, and act with goto, look_at_block, break, place, interact, click_slot and click_button. Actions block until they finish and report what happened. Coordinates are block coordinates; yaw 0 faces south (+Z).",
+            })),
+            "ping" => Ok(json!({})),
+            "tools/list" => Ok(json!({ "tools": tools() })),
+            "tools/call" => {
+                let name = params
+                    .get("name")
+                    .and_then(Value::as_str)
+                    .ok_or((-32602, "name is required".to_string()))?;
+                if !tools().iter().any(|t| t["name"] == name) {
+                    return Err((-32602, format!("Unknown tool {name}")));
+                }
+                let args = params.get("arguments").cloned().unwrap_or(json!({}));
+                let (content, error) = self.call(name, &args);
+                Ok(json!({ "content": content, "isError": error }))
+            }
+            _ => Err((-32601, format!("Method not found: {method}"))),
+        }
+    }
+}
+
+pub fn serve(session: &mut Session) -> Result<(), String> {
+    let stdin = std::io::stdin();
+    let mut stdout = std::io::stdout();
+    for line in stdin.lock().lines() {
+        let Ok(line) = line else { break };
+        if line.trim().is_empty() {
+            continue;
+        }
+        let reply = match serde_json::from_str::<Value>(&line) {
+            Err(e) => Some(
+                json!({ "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": e.to_string() } }),
+            ),
+            Ok(msg) => {
+                let method = msg
+                    .get("method")
+                    .and_then(Value::as_str)
+                    .unwrap_or_default();
+                let params = msg.get("params").cloned().unwrap_or(json!({}));
+                // Notifications (no id) get no reply.
+                msg.get("id").cloned().map(|id| match session.handle(method, &params) {
+                    Ok(result) => json!({ "jsonrpc": "2.0", "id": id, "result": result }),
+                    Err((code, message)) => json!({ "jsonrpc": "2.0", "id": id, "error": { "code": code, "message": message } }),
+                })
+            }
+        };
+        if let Some(reply) = reply {
+            writeln!(stdout, "{reply}")
+                .and_then(|_| stdout.flush())
+                .map_err(|e| e.to_string())?;
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn base64_matches_rfc_4648() {
+        assert_eq!(base64(b""), "");
+        assert_eq!(base64(b"f"), "Zg==");
+        assert_eq!(base64(b"fo"), "Zm8=");
+        assert_eq!(base64(b"foo"), "Zm9v");
+        assert_eq!(base64(b"foobar"), "Zm9vYmFy");
+    }
+
+    #[test]
+    fn tools_have_schemas_and_unique_names() {
+        let list = tools();
+        let mut names = std::collections::HashSet::new();
+        for t in &list {
+            assert!(names.insert(t["name"].as_str().unwrap().to_owned()));
+            assert_eq!(t["inputSchema"]["type"], "object");
+        }
+        for want in [
+            "launch",
+            "state",
+            "goto",
+            "break_block",
+            "place",
+            "click_slot",
+            "click_button",
+            "screenshot",
+            "inventory",
+            "logs",
+        ] {
+            let want = if want == "break_block" { "break" } else { want };
+            assert!(names.contains(want), "{want}");
+        }
+    }
+
+    #[test]
+    fn protocol_basics() {
+        let mut s = Session::new(std::env::temp_dir().join("horizon-ctl-mcp-test.sock"), None);
+        let init = s
+            .handle("initialize", &json!({ "protocolVersion": "2025-03-26" }))
+            .unwrap();
+        assert_eq!(init["protocolVersion"], "2025-03-26");
+        assert!(s.handle("nope", &json!({})).is_err());
+        let r = s
+            .handle(
+                "tools/call",
+                &json!({ "name": "goto", "arguments": { "x": 1 } }),
+            )
+            .unwrap();
+        assert_eq!(r["isError"], true);
+        assert!(
+            r["content"][0]["text"]
+                .as_str()
+                .unwrap()
+                .contains("y is required")
+        );
+        // No game: a connection error, reported as a tool error.
+        let r = s
+            .handle("tools/call", &json!({ "name": "state", "arguments": {} }))
+            .unwrap();
+        assert_eq!(r["isError"], true);
+    }
+}
@@ -143,6 +143,7 @@ pub fn draw_part(
        let color = pack_color(tint, 255, diffuse(normal, lights));
        for (v, position) in poly.iter().zip(pos) {
            out.push(Vertex {
+                normal: [0; 4],
                pos: position.to_array(),
                uv: [r.u0 + (r.u1 - r.u0) * v[3], r.v0 + (r.v1 - r.v0) * v[4]],
                layer: 0,
@@ -637,6 +638,7 @@ fn draw_text(scene: &Scene, call: &TextCall, out: &mut Vec<Vertex>) {
                    0xFF00_0000 | (argb & 255) << 16 | (argb >> 8 & 255) << 8 | (argb >> 16 & 255);
                for ((cx, cy), uv) in corners.into_iter().zip(uvs) {
                    out.push(Vertex {
+                        normal: [0; 4],
                        pos: call
                            .matrix
                            .transform_point3(Vec3::new(cx, cy, 0.0))
@@ -1587,6 +1589,7 @@ impl BeamPart {
                (at(b, self.end), [s.u0, v1]),
            ] {
                out.push(Vertex {
+                    normal: [0; 4],
                    pos: p.to_array(),
                    uv,
                    layer: 6,
@@ -1656,6 +1659,7 @@ fn portal_cube(m: Mat4, faces: &[Direction], layer: u32, out: &mut Vec<Vertex>)
    for &d in faces {
        for c in PORTAL_FACES[d as usize] {
            out.push(Vertex {
+                normal: [0; 4],
                pos: m.transform_point3(Vec3::from(c)).to_array(),
                uv: [0.0; 2],
                layer,
@@ -3,7 +3,13 @@
 use crate::Result;
 use horizon_world::registry::{BlockRegistry, BlockStateId};
 use serde_json::Value;
-use std::{collections::HashMap, fs::File, io::BufReader, path::Path, sync::Arc};
+use std::{
+    collections::HashMap,
+    fs::{self, File},
+    io::BufReader,
+    path::Path,
+    sync::Arc,
+};

 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum RenderShape {
@@ -54,6 +60,8 @@ pub struct StateFacts {
    pub waterlogged: bool,
    /// `hasOffsetFunction`: the model is jittered per column.
    pub random_offset: bool,
+    /// Whether the outline, not just the model, follows BlockState.getOffset.
+    pub outline_offset: bool,
    /// `BlockState.isSolid()` (legacy solidity; fluid surfaces read it).
    pub legacy_solid: bool,
    /// `isFaceSturdy(.., SupportType.FULL)` by Direction ordinal.
@@ -62,8 +70,8 @@ pub struct StateFacts {
    pub classes: Arc<[Arc<str>]>,
    /// `getShape` (the outline used for picking) as boxes in block space,
    /// without the random offset; and its edges as LevelRenderer draws them.
-    pub outline: Arc<[[f32; 6]]>,
-    pub outline_edges: Arc<[[f32; 6]]>,
+    pub outline: Arc<[[f64; 6]]>,
+    pub outline_edges: Arc<[[f64; 6]]>,
    /// `getMapColor(..).id` (0 = NONE).
    pub map_color: u8,
 }
@@ -78,11 +86,11 @@ pub const MAP_COLORS: [u32; 62] = [
    14200723, 8365974,
 ];
 /// The 12 edges of the unit cube (outline data predating the export).
-fn cube_edges() -> Vec<[f32; 6]> {
+fn cube_edges() -> Vec<[f64; 6]> {
    let mut edges = Vec::new();
    for a in 0..3 {
        for (u, v) in [(0., 0.), (1., 0.), (0., 1.), (1., 1.)] {
-            let mut from = [0.0f32; 3];
+            let mut from = [0.0f64; 3];
            let (b, c) = ((a + 1) % 3, (a + 2) % 3);
            from[b] = u;
            from[c] = v;
@@ -104,9 +112,7 @@ pub struct BlockFacts {
 }
 impl BlockFacts {
    pub fn load(root: &Path, registry: &BlockRegistry) -> Result<Self> {
-        let raw: Value = serde_json::from_reader(BufReader::new(File::open(
-            root.join("gameplay-facts.json"),
-        )?))?;
+        let raw: Value = serde_json::from_slice(&fs::read(root.join("gameplay-facts.json"))?)?;
        let entries = raw["states"]
            .as_array()
            .ok_or("missing gameplay state facts")?;
@@ -147,8 +153,8 @@ impl BlockFacts {
                .or_insert_with(|| Arc::from(s))
                .clone()
        };
-        let mut shapes: HashMap<String, Arc<[[f32; 6]]>> = HashMap::new();
-        let mut shape = |v: &Value, fallback: &dyn Fn() -> Vec<[f32; 6]>| -> Arc<[[f32; 6]]> {
+        let mut shapes: HashMap<String, Arc<[[f64; 6]]>> = HashMap::new();
+        let mut shape = |v: &Value, fallback: &dyn Fn() -> Vec<[f64; 6]>| -> Arc<[[f64; 6]]> {
            let Some(list) = v.as_array() else {
                return fallback().into();
            };
@@ -158,8 +164,7 @@ impl BlockFacts {
                    list.iter()
                        .filter_map(|b| {
                            let b = b.as_array()?;
-                            let n =
-                                |i: usize| b.get(i).and_then(Value::as_f64).unwrap_or(0.0) as f32;
+                            let n = |i: usize| b.get(i).and_then(Value::as_f64).unwrap_or(0.0);
                            Some([n(0), n(1), n(2), n(3), n(4), n(5)])
                        })
                        .collect()
@@ -263,6 +268,9 @@ impl BlockFacts {
                fluid_falling,
                waterlogged: prop("waterlogged") == Some("true"),
                random_offset: flag("offset"),
+                outline_offset: entry["outline_offset"]
+                    .as_bool()
+                    .unwrap_or_else(|| flag("offset")),
                legacy_solid: behaviour_states[index][1].as_u64().unwrap_or(0) & 1 != 0,
                sturdy_full: (behaviour_states[index][0].as_u64().unwrap_or(0) & 63) as u8,
                classes: classes
@@ -0,0 +1,109 @@
+//! BlockModelFeatureRenderer breaking quads and SheetedDecalTextureGenerator UVs.
+use crate::{camera::joml, mesher::Vertex, models::catalog::BakedModel};
+use horizon_assets::model::Direction;
+use std::f32::consts::{FRAC_PI_2, PI};
+
+/// Project in model space: the inverse decal pose cancels the block translation/offset.
+pub fn decal_uv([x, y, z]: [f32; 3], direction: Direction) -> [f32; 2] {
+    let sy = joml::sin(PI);
+    let cy = joml::cos_from_sin(sy, PI);
+    let sx = joml::sin(-FRAC_PI_2);
+    let cx = joml::cos_from_sin(sx, -FRAC_PI_2);
+    let p = [cy * x + sy * z, y, -sy * x + cy * z];
+    let p = [p[0], cx * p[1] - sx * p[2], sx * p[1] + cx * p[2]];
+    let (angle_x, angle_z) = match direction {
+        Direction::Down => (PI, 0.0),
+        Direction::Up => (0.0, 0.0),
+        Direction::North => (FRAC_PI_2, PI),
+        Direction::South => (FRAC_PI_2, 0.0),
+        Direction::West => (FRAC_PI_2, FRAC_PI_2),
+        Direction::East => (FRAC_PI_2, -FRAC_PI_2),
+    };
+    let p = joml::Quat::rotation_yxz(0.0, angle_x, angle_z).transform(p);
+    [-p[0], -p[1]]
+}
+
+pub fn geometry(model: &BakedModel, origin: glam::Vec3, translucent: bool, out: &mut Vec<Vertex>) {
+    // Vanilla visits all six cull groups and then the unculled faces, even beside solid neighbours.
+    for cull in Direction::ALL.map(Some).into_iter().chain([None]) {
+        for face in model.faces.iter().filter(|face| face.quad.cull == cull) {
+            for pos in face.quad.positions {
+                out.push(Vertex {
+                    pos: (origin + glam::Vec3::from(pos)).to_array(),
+                    uv: decal_uv(pos, face.quad.facing),
+                    layer: if translucent { 12 } else { 11 },
+                    color: 0xffff_ffff,
+                    light: 240 | (240 << 8),
+                    normal: [0; 4],
+                });
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::catalog::BakedFace;
+    use horizon_assets::{bake::ModelQuad, model::Material};
+    fn slab_top() -> BakedModel {
+        BakedModel {
+            ambient_occlusion: true,
+            cube: None,
+            faces: vec![BakedFace {
+                layer: 0,
+                opaque: true,
+                translucent: false,
+                quad: ModelQuad {
+                    positions: [
+                        [0.0, 0.5, 0.0],
+                        [0.0, 0.5, 1.0],
+                        [1.0, 0.5, 1.0],
+                        [1.0, 0.5, 0.0],
+                    ],
+                    uv: [[0.0; 2]; 4],
+                    facing: Direction::Up,
+                    cull: None,
+                    material: Material {
+                        sprite: "block/stone".into(),
+                        force_translucent: false,
+                    },
+                    tint_index: -1,
+                    shade_direction_override: None,
+                    light_emission: 0,
+                },
+            }],
+        }
+    }
+    #[test]
+    fn slab_overlay_follows_baked_top_not_unit_cube() {
+        let model = slab_top();
+        let mut vertices = Vec::new();
+        geometry(&model, glam::Vec3::new(2.0, 3.0, 4.0), false, &mut vertices);
+        assert_eq!(vertices.len(), 4);
+        for (v, p) in vertices.iter().zip(model.faces[0].quad.positions) {
+            assert_eq!(v.pos, [p[0] + 2.0, p[1] + 3.0, p[2] + 4.0]);
+            assert_eq!(v.color, 0xffff_ffff);
+        }
+    }
+    #[test]
+    fn small_faces_use_projected_not_stretched_uvs() {
+        let a = decal_uv([0.0, 0.0, 0.0], Direction::North);
+        let b = decal_uv([0.0, 0.5, 0.0], Direction::North);
+        assert!(((b[1] - a[1]).abs() - 0.5).abs() < 1e-6);
+    }
+    #[test]
+    fn translucent_overlay_has_its_own_pass() {
+        let mut vertices = Vec::new();
+        geometry(&slab_top(), glam::Vec3::ZERO, true, &mut vertices);
+        assert!(vertices.iter().all(|v| v.layer == 12));
+    }
+    #[test]
+    fn empty_model_has_no_cube_overlay() {
+        let mut model = slab_top();
+        model.faces.clear();
+        let mut vertices = Vec::new();
+        geometry(&model, glam::Vec3::ZERO, false, &mut vertices);
+        assert!(vertices.is_empty());
+    }
+}
@@ -288,6 +288,13 @@ pub mod joml {
 }
 use joml::{Mat4, Quat};

+/// Camera-relative world view used by terrain, sky and the first-person hand.
+pub fn view_matrix(yaw: f32, pitch: f32) -> glam::Mat4 {
+    // Vanilla uses the conjugate of Camera.rotation, not a world-up look-at.
+    let q = Quat::rotation_yxz(PI - yaw * DEG_TO_RAD, -pitch * DEG_TO_RAD, 0.0);
+    glam::Mat4::from_quat(glam::Quat::from_xyzw(-q.x, -q.y, -q.z, q.w))
+}
+
 /// `CameraType`.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum CameraType {
@@ -583,6 +590,50 @@ impl Camera {
        modify_fov_based_on_death_or_fluid(partial, 70.0, effect_scale, dead, fluid)
    }
 }
+/// `Camera.update`: the far plane covers four times the render distance and
+/// the whole cloud range (`depthFar`).
+pub fn depth_far(render_distance_chunks: i32, cloud_range_chunks: i32) -> f32 {
+    (render_distance_chunks as f32 * 16.0 * 4.0).max((cloud_range_chunks * 16) as f32)
+}
+
+/// `Projection.getMatrix` for a perspective set up by `setupPerspective`:
+/// JOML's `Matrix4f.setPerspective(fov * DEG_TO_RAD, width / height, near,
+/// far, zZeroToOne)`, column-major. Vanilla's `Projection` passes its planes
+/// reversed (`near` is `zFar`) for reversed depth.
+pub fn perspective(
+    fov_degrees: f32,
+    width: f32,
+    height: f32,
+    near: f32,
+    far: f32,
+    zero_to_one: bool,
+) -> [f32; 16] {
+    let h = horizon_core::jmath::tan(f64::from(fov_degrees * DEG_TO_RAD * 0.5)) as f32;
+    let aspect = width / height;
+    let mut m = [0.0f32; 16];
+    m[0] = 1.0 / (h * aspect);
+    m[5] = 1.0 / h;
+    let e = 1.0e-6f32;
+    if far > 0.0 && far.is_infinite() {
+        m[10] = e - 1.0;
+        m[14] = (e - if zero_to_one { 1.0 } else { 2.0 }) * near;
+    } else if near > 0.0 && near.is_infinite() {
+        m[10] = (if zero_to_one { 0.0 } else { 1.0 }) - e;
+        m[14] = ((if zero_to_one { 1.0 } else { 2.0 }) - e) * far;
+    } else {
+        m[10] = (if zero_to_one { far } else { far + near }) / (near - far);
+        m[14] = (if zero_to_one { far } else { far + far }) * near / (near - far);
+    }
+    m[11] = -1.0;
+    m
+}
+/// `GameRenderer.render3dHud`: the first-person hand and held items are
+/// drawn with their own projection at `hudFov` (70 degrees, changed only by
+/// death and fluids), never the FOV option or the sprint, speed and bow
+/// modifier.
+pub fn hand_projection(hud_fov: f32, width: f32, height: f32, far: f32) -> [f32; 16] {
+    perspective(hud_fov, width, height, far, 0.05, true)
+}
 /// `Camera.modifyFovBasedOnDeathOrFluid`. `dead` is the camera entity's
 /// `deathTime` while it is a living entity that is dead or dying.
 pub fn modify_fov_based_on_death_or_fluid(
@@ -723,8 +774,36 @@ pub fn bob_matrix(state: &BobState, damage_tilt_strength: f64, bob_view_option:

 #[cfg(test)]
 mod tests {
+    #[test]
+    fn depth_far_covers_the_cloud_range() {
+        // renderDistance 2 with the default Cloud Distance (128 chunks).
+        assert_eq!(super::depth_far(2, 128), 2048.0);
+        assert_eq!(super::depth_far(32, 2), 2048.0);
+        assert_eq!(super::depth_far(12, 12), 768.0);
+    }
    use super::*;
    #[test]
+    fn view_keeps_yaw_at_vertical_pitch_limits() {
+        for yaw in [0.0, 45.0, 90.0, 180.0, -90.0, 360.0] {
+            for pitch in [-90.0, -89.999, 0.0, 89.999, 90.0] {
+                let view = view_matrix(yaw, pitch);
+                let mut camera = Camera::default();
+                camera.set_rotation(yaw, pitch);
+                for (world, expected) in [
+                    (camera.forwards, -glam::Vec3::Z),
+                    (camera.up, glam::Vec3::Y),
+                    (camera.left, -glam::Vec3::X),
+                ] {
+                    let got = view.transform_vector3(glam::Vec3::from(world));
+                    assert!(
+                        (got - expected).length() < 1e-5,
+                        "yaw={yaw}, pitch={pitch}: {got:?} != {expected:?}"
+                    );
+                }
+            }
+        }
+    }
+    #[test]
    fn camera_eases_eye_height_and_fov() {
        let mut camera = Camera::default();
        camera.tick(Some(1.62), 1.0);
@@ -9,9 +9,13 @@ use crate::{
    hud::{HudAtlas, HudBatch},
    hud_layout::{self, GuiDraw, PoseOp},
    screen_draw::{self as d, Draw, Measure, TextField},
-    text::{self, Style, Text},
+    text::{self, ClickEvent, Style, Text},
 };

+#[cfg(test)]
+#[path = "chat_tests.rs"]
+mod tests;
+
 /// GuiMessageTag.systemSinglePlayer's indicator colour.
 pub const SYSTEM_INDICATOR: u32 = 0xD0D0D0;

@@ -113,6 +117,8 @@ impl Chat {
        ticks: u64,
        focused: bool,
    ) {
+        // ChatComponent.logChatMessage: every message is in the log.
+        crate::logging::write_only(log::Level::Info, &format!("[CHAT] {}", content.plain()));
        if self.log {
            println!("[CHAT] {}", content.plain());
        }
@@ -291,6 +297,35 @@ impl Chat {
        let draws = self.layout(batch.height as i32, ticks, focused);
        hud_layout::paint(batch, atlas, &draws);
    }
+    /// The click action under a GUI-space cursor while chat is focused.
+    pub fn click_at(
+        &self,
+        font: &crate::font::Font,
+        height: i32,
+        x: f64,
+        y: f64,
+    ) -> Option<ClickEvent> {
+        let scale = self.options.scale as f32;
+        let mut x = x / f64::from(scale) - 4.0;
+        let bottom = hud_layout::floor((height - 40) as f32 / scale);
+        let from_bottom = f64::from(bottom) - y / f64::from(scale);
+        if x < 0.0 || x >= f64::from(self.max_width()) || from_bottom <= 0.0 {
+            return None;
+        }
+        let row = (from_bottom / f64::from(self.options.line_height())).ceil() as usize - 1;
+        if row >= self.lines_per_page(true) {
+            return None;
+        }
+        let line = self.lines.get(self.scroll + row)?;
+        let content = line.content.resolve_legacy();
+        for (c, style) in content.chars() {
+            x -= f64::from(font.advance(c, style));
+            if x < 0.0 {
+                return style.click.clone();
+            }
+        }
+        None
+    }
    /// Plain text of the newest messages (for tests and the control socket).
    pub fn recent_lines(&self, n: usize) -> Vec<String> {
        self.messages
@@ -418,6 +453,11 @@ impl ChatScreen {
    pub fn value(&self) -> &str {
        &self.input.value
    }
+    /// Replace the input for a suggest-command link and refresh completions.
+    pub fn suggest_command(&mut self, m: &Measure, c: &Commands, command: &str) {
+        self.input.set_value(m, command);
+        self.edited(m, c);
+    }
    /// `ChatScreen.resize`: a new screen with the current text.
    pub fn resize(&mut self, m: &Measure, c: &Commands, width: i32, height: i32) {
        if (width, height) != (self.width, self.height) {
@@ -432,6 +472,18 @@ impl ChatScreen {
        self.allow_suggestions = true;
        self.update_command_info(m, c);
    }
+    /// Ctrl+A/C/V/X in the input box.
+    pub fn shortcut(
+        &mut self,
+        m: &Measure,
+        c: &Commands,
+        shortcut: crate::clipboard::EditShortcut,
+        clipboard: &mut dyn crate::clipboard::Clipboard,
+    ) {
+        if self.input.shortcut(m, shortcut, clipboard) {
+            self.edited(m, c);
+        }
+    }
    /// Typed text (`charTyped` per character).
    pub fn type_text(&mut self, m: &Measure, c: &Commands, text: &str) {
        for ch in text.chars() {
@@ -0,0 +1,165 @@
+use super::*;
+use crate::{font::Font, hud::Rect};
+use std::{collections::HashMap, path::Path};
+
+fn font() -> Font {
+    // The missing-glyph metrics let these tests run without game assets.
+    Font::load(
+        Path::new("/nonexistent-horizon-chat-test-resources"),
+        &HashMap::new(),
+        &[],
+        (1, 1),
+        (0, 0),
+        Rect {
+            u0: 0.0,
+            v0: 0.0,
+            u1: 1.0,
+            v1: 1.0,
+            w: 1,
+            h: 1,
+        },
+    )
+}
+
+fn add(chat: &mut Chat, font: &Font, content: Text) {
+    for content in font.wrap_components(&content, chat.max_width()) {
+        chat.lines.insert(
+            0,
+            Line {
+                added: 0,
+                content,
+                indicator: None,
+            },
+        );
+    }
+}
+
+#[test]
+fn clicking_seed_copies_the_raw_value_only_inside_the_link() {
+    let font = font();
+    for seed in [1, -42, i64::MIN, i64::MAX] {
+        let mut chat = Chat::default();
+        let seed_text = Text::copyable(seed.to_string()).with_color(text::GOLD);
+        assert_eq!(seed_text.plain(), format!("[{seed}]"));
+        assert_eq!(seed_text.spans[0].style.color, Some(text::GOLD));
+        assert_eq!(seed_text.spans[1].style.color, Some(text::GREEN));
+        assert_eq!(seed_text.spans[2].style.color, Some(text::GOLD));
+        add(&mut chat, &font, Text::literal("Seed: ").append(seed_text));
+        let expected = Some(ClickEvent::CopyToClipboard(seed.to_string()));
+        let start = 4.0 + f64::from(font.width("Seed: ["));
+        let end = start + f64::from(font.width(&seed.to_string()));
+        assert_eq!(chat.click_at(&font, 360, start, 315.0), expected);
+        assert_eq!(chat.click_at(&font, 360, end - 0.5, 315.0), expected);
+        for (x, y) in [
+            (start - 0.5, 315.0),
+            (end, 315.0),
+            (3.0, 315.0),
+            (start, 320.0),
+            (start, 310.0),
+        ] {
+            assert_eq!(chat.click_at(&font, 360, x, y), None, "{x}, {y}");
+        }
+    }
+}
+
+#[test]
+fn click_targets_match_rendered_spans_when_scaled_wrapped_and_scrolled() {
+    let font = font();
+    let screenshot = ClickEvent::OpenFile("/tmp/My screenshots/世界.png".into());
+    for scale in [0.5, 0.75, 1.0] {
+        for line_spacing in [0.0, 0.5, 1.0] {
+            let mut chat = Chat::default();
+            chat.options.scale = scale;
+            chat.options.width = 0.0;
+            chat.options.line_spacing = line_spacing;
+            for _ in 0..20 {
+                add(
+                    &mut chat,
+                    &font,
+                    Text::literal("Saved screenshot as ").append(Text::styled(
+                        "2026-10-14_18.55.14.png",
+                        Style {
+                            click: Some(screenshot.clone()),
+                            bold: Some(true),
+                            underlined: Some(true),
+                            ..Style::default()
+                        },
+                    )),
+                );
+            }
+            for scroll in [0, 3, 12] {
+                chat.scroll = scroll;
+                let mut links = 0;
+                for draw in chat.layout(361, 0, true) {
+                    if let GuiDraw::Text { text, x, y, .. } = draw {
+                        let mut at = x as f64;
+                        for (c, style) in text.chars() {
+                            let width = f64::from(font.advance(c, style));
+                            let cursor_x = (4.0 + at + width / 2.0) * scale;
+                            let cursor_y = (y as f64 + 3.0) * scale;
+                            assert_eq!(
+                                chat.click_at(&font, 361, cursor_x, cursor_y),
+                                style.click,
+                                "scale={scale}, spacing={line_spacing}, scroll={scroll}, char={c}"
+                            );
+                            links += usize::from(style.click.is_some());
+                            at += width;
+                        }
+                    }
+                }
+                assert!(links > 0);
+                // The history above the focused viewport is not clickable.
+                let top = ((361 - 40) as f64 / scale).floor()
+                    - chat.lines_per_page(true) as f64 * chat.options.line_height() as f64;
+                assert_eq!(
+                    chat.click_at(&font, 361, 10.0 * scale, (top - 1.0) * scale),
+                    None
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn locate_coordinates_fill_chat_with_teleport_without_submitting() {
+    let font = font();
+    let m = Measure(&font);
+    let registries = Registries::default();
+    let commands = Commands {
+        dispatcher: crate::command::vanilla::game_dispatcher(),
+        registries: &registries,
+    };
+    // Structures and POIs use relative Y; biome results include absolute Y.
+    for (y, expected) in [
+        (None, "/tp @s -1136 ~ 848"),
+        (Some(73), "/tp @s -1136 73 848"),
+    ] {
+        let link = Text::teleport_link(-1136, y, 848);
+        assert_eq!(link.component()["click_event"]["action"], "suggest_command");
+        assert_eq!(link.component()["click_event"]["command"], expected);
+        let mut chat = Chat::default();
+        add(&mut chat, &font, Text::literal("Found at ").append(link));
+        let mut screen = ChatScreen::new(&m, &commands, "draft", 0, 640, 360);
+        let x = 4.0 + f64::from(font.width("Found at "));
+        assert!(!screen.click(&m, &commands, x, 315.0));
+        let Some(ClickEvent::SuggestCommand(command)) = chat.click_at(&font, 360, x, 315.0) else {
+            panic!("locate coordinates must suggest a command");
+        };
+        screen.suggest_command(&m, &commands, &command);
+        assert_eq!(screen.value(), expected);
+        assert_eq!(screen.input.cursor, expected.chars().count());
+        assert_eq!(screen.input.highlight, screen.input.cursor);
+        // Submission is a separate, explicit Enter press.
+        assert_eq!(
+            screen.key(
+                &m,
+                &commands,
+                &[],
+                winit::keyboard::KeyCode::Enter,
+                false,
+                false
+            ),
+            ChatAction::Submit(expected.to_owned())
+        );
+    }
+}
@@ -20,6 +20,15 @@ pub enum Light {
    Uniform(u8),
    Full(Box<[u8; 4096]>),
 }
+impl Light {
+    #[inline]
+    pub fn get(&self, i: usize) -> u8 {
+        match self {
+            Self::Uniform(v) => *v,
+            Self::Full(a) => a[i],
+        }
+    }
+}
 #[inline]
 pub fn index(x: i32, y: i32, z: i32) -> usize {
    ((y & 15) << 8 | (z & 15) << 4 | (x & 15)) as usize
@@ -59,10 +68,7 @@ impl Section {
    }
    #[inline]
    pub fn light(&self, i: usize) -> u8 {
-        match &self.light {
-            Light::Uniform(v) => *v,
-            Light::Full(a) => a[i],
-        }
+        self.light.get(i)
    }
    pub fn is_uniform(&self, v: u16) -> bool {
        self.blocks.is_uniform(u32::from(v))
@@ -0,0 +1,122 @@
+//! Resident chunk membership, with a token for consumers that cache its keys.
+use crate::{chunk::Chunk, fast_hash::FxHashMap};
+use std::{
+    collections::hash_map::{Iter, ValuesMut},
+    ops::Deref,
+    sync::{
+        Arc,
+        atomic::{AtomicU64, Ordering},
+    },
+};
+
+type Key = (i32, i32);
+type Columns = FxHashMap<Key, Arc<Chunk>>;
+static NEXT_REVISION: AtomicU64 = AtomicU64::new(1);
+fn next_revision() -> u64 {
+    NEXT_REVISION.fetch_add(1, Ordering::Relaxed)
+}
+
+/// Read access behaves like a map. Structural writes are explicit so edits to
+/// blocks or light don't invalidate consumers of the loaded chunk key set.
+/// Tokens are process-wide: replacing the entire map also invalidates caches.
+pub struct ChunkMap {
+    columns: Columns,
+    revision: u64,
+}
+impl Default for ChunkMap {
+    fn default() -> Self {
+        Self {
+            columns: Columns::default(),
+            revision: next_revision(),
+        }
+    }
+}
+impl ChunkMap {
+    pub fn membership_revision(&self) -> u64 {
+        self.revision
+    }
+    pub fn insert(&mut self, key: Key, chunk: Arc<Chunk>) -> Option<Arc<Chunk>> {
+        let previous = self.columns.insert(key, chunk);
+        if previous.is_none() {
+            self.revision = next_revision();
+        }
+        previous
+    }
+    pub fn remove(&mut self, key: &Key) -> Option<Arc<Chunk>> {
+        let previous = self.columns.remove(key);
+        if previous.is_some() {
+            self.revision = next_revision();
+        }
+        previous
+    }
+    pub fn clear(&mut self) {
+        if !self.columns.is_empty() {
+            self.columns.clear();
+            self.revision = next_revision();
+        }
+    }
+    pub fn get_mut(&mut self, key: &Key) -> Option<&mut Arc<Chunk>> {
+        self.columns.get_mut(key)
+    }
+    pub fn values_mut(&mut self) -> ValuesMut<'_, Key, Arc<Chunk>> {
+        self.columns.values_mut()
+    }
+}
+impl Deref for ChunkMap {
+    type Target = Columns;
+    fn deref(&self) -> &Columns {
+        &self.columns
+    }
+}
+impl<'a> IntoIterator for &'a ChunkMap {
+    type Item = (&'a Key, &'a Arc<Chunk>);
+    type IntoIter = Iter<'a, Key, Arc<Chunk>>;
+    fn into_iter(self) -> Self::IntoIter {
+        self.columns.iter()
+    }
+}
+impl crate::light::LightWorld for ChunkMap {
+    fn state(&self, x: i32, y: i32, z: i32) -> Option<u16> {
+        self.columns.state(x, y, z)
+    }
+    fn light(&self, x: i32, y: i32, z: i32) -> Option<u8> {
+        self.columns.light(x, y, z)
+    }
+    fn set_light(&mut self, x: i32, y: i32, z: i32, packed: u8) {
+        self.columns.set_light(x, y, z, packed);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn membership_tokens_track_keys_and_map_replacement_only() {
+        let mut map = ChunkMap::default();
+        let empty = map.membership_revision();
+        map.clear();
+        map.remove(&(0, 0));
+        assert_eq!(empty, map.membership_revision());
+        let chunk = Arc::new(Chunk::empty(0, 0));
+        map.insert((0, 0), chunk.clone());
+        let inserted = map.membership_revision();
+        assert_ne!(empty, inserted);
+        map.insert((0, 0), chunk.clone());
+        Arc::make_mut(map.get_mut(&(0, 0)).unwrap()).lit = true;
+        for column in map.values_mut() {
+            Arc::make_mut(column).light_loaded = true;
+        }
+        crate::light::LightWorld::set_light(&mut map, 0, 0, 0, 0);
+        assert_eq!(inserted, map.membership_revision());
+        map.remove(&(0, 0));
+        map.insert((1, 0), chunk);
+        assert_eq!(map.len(), 1);
+        assert_ne!(inserted, map.membership_revision());
+        let replaced = map.membership_revision();
+        map.clear();
+        assert_ne!(replaced, map.membership_revision());
+        let cleared = map.membership_revision();
+        map = ChunkMap::default();
+        assert_ne!(cleared, map.membership_revision());
+    }
+}
@@ -0,0 +1,455 @@
+//! The system clipboard and the text-editing shortcuts of 26.3:
+//! `KeyboardHandler.getClipboard`/`setClipboard`, `InputWithModifiers.isSelectAll`,
+//! `isCopy`, `isPaste` and `isCut`, `StringUtil.filterText` and
+//! `ChatFormatting.stripFormatting`.
+
+use winit::keyboard::{Key, KeyCode, PhysicalKey};
+
+/// A text-editing shortcut (`InputWithModifiers.isSelectAll`, `isCopy`,
+/// `isPaste`, `isCut`).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum EditShortcut {
+    SelectAll,
+    Copy,
+    Paste,
+    Cut,
+}
+
+/// The letter a key stands for in shortcuts (`KeyEvent.shortcutKey`, SDL's
+/// keycode): the layout's letter, or the key's US-layout letter when the
+/// layout's is not a Latin one (SDL's default `latin_letters` keycode option).
+pub fn shortcut_letter(logical: &Key, physical: PhysicalKey) -> Option<char> {
+    if let Key::Character(s) = logical {
+        let mut chars = s.chars();
+        if let (Some(c), None) = (chars.next(), chars.next())
+            && c.is_ascii_alphabetic()
+        {
+            return Some(c.to_ascii_lowercase());
+        }
+    }
+    let PhysicalKey::Code(code) = physical else {
+        return None;
+    };
+    Some(match code {
+        KeyCode::KeyA => 'a',
+        KeyCode::KeyC => 'c',
+        KeyCode::KeyV => 'v',
+        KeyCode::KeyX => 'x',
+        _ => return None,
+    })
+}
+
+/// `InputWithModifiers.isSelectAll`/`isCopy`/`isPaste`/`isCut`: A, C, V or X
+/// with the edit modifier (`InputQuirks.EDIT_SHORTCUT_KEY_MODIFIER`: Cmd on
+/// macOS, Ctrl elsewhere) and neither Shift nor Alt.
+pub fn edit_shortcut(
+    letter: Option<char>,
+    edit_modifier: bool,
+    shift: bool,
+    alt: bool,
+) -> Option<EditShortcut> {
+    if !edit_modifier || shift || alt {
+        return None;
+    }
+    Some(match letter? {
+        'a' => EditShortcut::SelectAll,
+        'c' => EditShortcut::Copy,
+        'v' => EditShortcut::Paste,
+        'x' => EditShortcut::Cut,
+        _ => return None,
+    })
+}
+
+/// `StringUtil.isAllowedChatCharacter`.
+pub fn is_allowed_chat_character(c: char) -> bool {
+    c != '§' && c >= ' ' && c != '\u{7f}'
+}
+
+/// `StringUtil.filterText`: the allowed characters, and line breaks where
+/// the field takes several lines.
+pub fn filter_text(input: &str, multiline: bool) -> String {
+    input
+        .chars()
+        .filter(|&c| is_allowed_chat_character(c) || (multiline && c == '\n'))
+        .collect()
+}
+
+/// `ChatFormatting.stripFormatting`: `§` followed by a format code removed.
+pub fn strip_formatting(input: &str) -> String {
+    let mut out = String::with_capacity(input.len());
+    let mut chars = input.chars().peekable();
+    while let Some(c) = chars.next() {
+        if c == '§'
+            && chars.peek().is_some_and(
+                |n| matches!(n.to_ascii_lowercase(), '0'..='9' | 'a'..='f' | 'k'..='o' | 'r'),
+            )
+        {
+            chars.next();
+            continue;
+        }
+        out.push(c);
+    }
+    out
+}
+
+/// `TextFieldHelper.getClipboardContents`: formatting and carriage returns
+/// removed (signs).
+pub fn helper_clipboard_contents(clipboard: &str) -> String {
+    strip_formatting(&clipboard.replace('\r', ""))
+}
+
+/// A clipboard: the system's, or an in-memory one in tests.
+pub trait Clipboard {
+    /// `KeyboardHandler.getClipboard`: empty when there is no text.
+    fn get(&mut self) -> String;
+    /// `KeyboardHandler.setClipboard`: empty text is not copied.
+    fn set(&mut self, text: &str);
+}
+
+/// The system clipboard (`ClipboardManager`). On Wayland, arboard uses the
+/// data-control protocol and falls back to X11 (XWayland) on compositors
+/// without it. When no system clipboard can be reached, text copied in the
+/// game can still be pasted in the game.
+#[derive(Default)]
+pub struct SystemClipboard {
+    system: Option<arboard::Clipboard>,
+    /// The text Horizon last copied (`horizon-ctl status`).
+    copied: Option<String>,
+}
+
+impl SystemClipboard {
+    /// The text last copied by the game.
+    pub fn copied(&self) -> Option<&str> {
+        self.copied.as_deref()
+    }
+    fn system(&mut self) -> Option<&mut arboard::Clipboard> {
+        if self.system.is_none() {
+            self.system = arboard::Clipboard::new().ok();
+        }
+        self.system.as_mut()
+    }
+}
+
+impl Clipboard for SystemClipboard {
+    fn get(&mut self) -> String {
+        let Some(system) = self.system() else {
+            return self.copied.clone().unwrap_or_default();
+        };
+        match system.get_text() {
+            Ok(text) => text,
+            Err(arboard::Error::ContentNotAvailable) => String::new(),
+            Err(_) => {
+                // A lost connection (a restarted compositor): reconnect next time.
+                self.system = None;
+                String::new()
+            }
+        }
+    }
+    fn set(&mut self, text: &str) {
+        if text.is_empty() {
+            return;
+        }
+        self.copied = Some(text.to_owned());
+        if let Some(system) = self.system()
+            && system.set_text(text.to_owned()).is_err()
+        {
+            self.system = None;
+        }
+    }
+}
+
+/// A clipboard in memory.
+#[derive(Default, Debug)]
+pub struct MemoryClipboard(pub String);
+
+impl Clipboard for MemoryClipboard {
+    fn get(&mut self) -> String {
+        self.0.clone()
+    }
+    fn set(&mut self, text: &str) {
+        if !text.is_empty() {
+            self.0 = text.to_owned();
+        }
+    }
+}
+
+/// A text field with a cursor and a selection (`EditBox`).
+pub trait Editable {
+    /// Select All: the cursor at the end, the selection from the start.
+    fn select_all(&mut self);
+    /// `getHighlighted`.
+    fn selected_text(&self) -> String;
+    /// `insertText`, with the field's own filter and length limit. True when
+    /// the value changed.
+    fn insert(&mut self, text: &str) -> bool;
+}
+
+/// `EditBox.keyPressed`'s shortcuts. True when the value changed.
+pub fn apply(
+    field: &mut dyn Editable,
+    shortcut: EditShortcut,
+    clipboard: &mut dyn Clipboard,
+) -> bool {
+    match shortcut {
+        EditShortcut::SelectAll => {
+            field.select_all();
+            false
+        }
+        EditShortcut::Copy => {
+            clipboard.set(&field.selected_text());
+            false
+        }
+        EditShortcut::Paste => field.insert(&clipboard.get()),
+        EditShortcut::Cut => {
+            clipboard.set(&field.selected_text());
+            field.insert("")
+        }
+    }
+}
+
+/// Which append-only field a Select All covers: a name and an index (a
+/// sign line, a book page).
+pub type FieldId = (&'static str, usize);
+
+/// The selection of Horizon's append-only fields, whose cursor stays at the
+/// end: Select All selects the whole value, which the next copy, cut, paste,
+/// typed text or backspace replaces. It is forgotten as soon as the field or
+/// its value changes.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct AppendSelection(Option<(FieldId, String)>);
+
+impl AppendSelection {
+    /// Whether `value` of field `id` is wholly selected.
+    pub fn covers(&self, id: FieldId, value: &str) -> bool {
+        self.0.as_ref().is_some_and(|(i, v)| *i == id && v == value)
+    }
+    /// Before typing or a backspace: an all-selected value is cleared (true).
+    pub fn take(&mut self, id: FieldId, value: &mut String) -> bool {
+        let covered = self.covers(id, value);
+        self.0 = None;
+        if covered {
+            value.clear();
+        }
+        covered
+    }
+    /// A shortcut in an append-only field. `insert` adds pasted text to a
+    /// value the field's own way and says whether it accepted it (a field
+    /// that rejects it keeps its value, as `TextFieldHelper.insertText`).
+    /// True when the value changed.
+    pub fn apply(
+        &mut self,
+        id: FieldId,
+        value: &mut String,
+        shortcut: EditShortcut,
+        clipboard: &mut dyn Clipboard,
+        insert: impl FnOnce(&mut String, &str) -> bool,
+    ) -> bool {
+        let covered = self.covers(id, value);
+        match shortcut {
+            EditShortcut::SelectAll => {
+                self.0 = Some((id, value.clone()));
+                false
+            }
+            EditShortcut::Copy => {
+                if covered {
+                    clipboard.set(value);
+                }
+                false
+            }
+            EditShortcut::Cut => {
+                self.0 = None;
+                if !covered {
+                    return false;
+                }
+                clipboard.set(value);
+                let changed = !value.is_empty();
+                value.clear();
+                changed
+            }
+            EditShortcut::Paste => {
+                self.0 = None;
+                let text = clipboard.get();
+                let mut next = if covered {
+                    String::new()
+                } else {
+                    value.clone()
+                };
+                if !insert(&mut next, &text) || next == *value {
+                    return false;
+                }
+                *value = next;
+                true
+            }
+        }
+    }
+}
+
+/// `EditBox.insertText` for a field without a cursor: the filtered text,
+/// cut to the room left by `max_chars`.
+pub fn append_limited(value: &mut String, text: &str, max_chars: usize) -> bool {
+    let room = max_chars.saturating_sub(value.chars().count());
+    if room == 0 {
+        return false;
+    }
+    value.extend(filter_text(text, false).chars().take(room));
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn shortcuts_need_the_edit_modifier_alone() {
+        let c = Some('c');
+        assert_eq!(
+            edit_shortcut(c, true, false, false),
+            Some(EditShortcut::Copy)
+        );
+        assert_eq!(
+            edit_shortcut(Some('v'), true, false, false),
+            Some(EditShortcut::Paste)
+        );
+        assert_eq!(
+            edit_shortcut(Some('x'), true, false, false),
+            Some(EditShortcut::Cut)
+        );
+        assert_eq!(
+            edit_shortcut(Some('a'), true, false, false),
+            Some(EditShortcut::SelectAll)
+        );
+        assert_eq!(edit_shortcut(c, false, false, false), None);
+        assert_eq!(edit_shortcut(c, true, true, false), None);
+        assert_eq!(edit_shortcut(c, true, false, true), None);
+        assert_eq!(edit_shortcut(Some('b'), true, false, false), None);
+    }
+
+    #[test]
+    fn the_layout_letter_decides_and_non_latin_layouts_use_the_position() {
+        let q = PhysicalKey::Code(KeyCode::KeyQ);
+        // AZERTY: the key at Q's position types an A.
+        assert_eq!(shortcut_letter(&Key::Character("a".into()), q), Some('a'));
+        // Russian: the key at C's position types с.
+        let c = PhysicalKey::Code(KeyCode::KeyC);
+        assert_eq!(shortcut_letter(&Key::Character("с".into()), c), Some('c'));
+        assert_eq!(shortcut_letter(&Key::Character("C".into()), q), Some('c'));
+    }
+
+    #[test]
+    fn filter_text_keeps_line_breaks_only_for_multiline_fields() {
+        let s = "a\u{7}b§c\nd\re\u{80}";
+        assert_eq!(filter_text(s, false), "abcde\u{80}");
+        assert_eq!(filter_text(s, true), "abc\nde\u{80}");
+        assert_eq!(strip_formatting("§aRed§r §zx§"), "Red §zx§");
+        assert_eq!(helper_clipboard_contents("§lone\r\ntwo"), "one\ntwo");
+    }
+
+    struct Field {
+        value: String,
+        cursor: usize,
+        highlight: usize,
+    }
+    impl Editable for Field {
+        fn select_all(&mut self) {
+            self.cursor = self.value.len();
+            self.highlight = 0;
+        }
+        fn selected_text(&self) -> String {
+            let (a, b) = (
+                self.cursor.min(self.highlight),
+                self.cursor.max(self.highlight),
+            );
+            self.value[a..b].to_owned()
+        }
+        fn insert(&mut self, text: &str) -> bool {
+            let (a, b) = (
+                self.cursor.min(self.highlight),
+                self.cursor.max(self.highlight),
+            );
+            self.value.replace_range(a..b, text);
+            self.cursor = a + text.len();
+            self.highlight = self.cursor;
+            true
+        }
+    }
+
+    #[test]
+    fn edit_box_shortcuts() {
+        let mut clip = MemoryClipboard("old".into());
+        let mut f = Field {
+            value: "hello".into(),
+            cursor: 5,
+            highlight: 5,
+        };
+        // Nothing selected: copying leaves the clipboard alone (setClipboard skips "").
+        apply(&mut f, EditShortcut::Copy, &mut clip);
+        assert_eq!(clip.0, "old");
+        apply(&mut f, EditShortcut::SelectAll, &mut clip);
+        apply(&mut f, EditShortcut::Copy, &mut clip);
+        assert_eq!(clip.0, "hello");
+        assert!(apply(&mut f, EditShortcut::Cut, &mut clip));
+        assert_eq!(f.value, "");
+        assert!(apply(&mut f, EditShortcut::Paste, &mut clip));
+        assert!(apply(&mut f, EditShortcut::Paste, &mut clip));
+        assert_eq!(f.value, "hellohello");
+    }
+
+    #[test]
+    fn append_only_fields_select_everything_or_nothing() {
+        let id = ("search", 0);
+        let mut clip = MemoryClipboard("stone".into());
+        let mut sel = AppendSelection::default();
+        let mut value = String::from("dirt");
+        let insert = |v: &mut String, t: &str| append_limited(v, t, 6);
+        // Without Select All, copy and cut do nothing and paste appends.
+        sel.apply(id, &mut value, EditShortcut::Copy, &mut clip, insert);
+        assert_eq!(clip.0, "stone");
+        assert!(!sel.apply(id, &mut value, EditShortcut::Cut, &mut clip, insert));
+        assert!(sel.apply(id, &mut value, EditShortcut::Paste, &mut clip, insert));
+        assert_eq!(value, "dirtst");
+        // Select All then paste replaces the value.
+        sel.apply(id, &mut value, EditShortcut::SelectAll, &mut clip, insert);
+        assert!(sel.apply(id, &mut value, EditShortcut::Paste, &mut clip, insert));
+        assert_eq!(value, "stone");
+        // Select All then cut empties it and copies it.
+        sel.apply(id, &mut value, EditShortcut::SelectAll, &mut clip, insert);
+        clip.0 = "x".into();
+        assert!(sel.apply(id, &mut value, EditShortcut::Cut, &mut clip, insert));
+        assert_eq!((value.as_str(), clip.0.as_str()), ("", "stone"));
+        // A selection is forgotten once the value changes or another field is used.
+        value = "ab".into();
+        sel.apply(id, &mut value, EditShortcut::SelectAll, &mut clip, insert);
+        assert!(!sel.covers(("other", 0), &value));
+        value.push('c');
+        assert!(!sel.take(id, &mut value));
+        assert_eq!(value, "abc");
+        sel.apply(id, &mut value, EditShortcut::SelectAll, &mut clip, insert);
+        assert!(sel.take(id, &mut value));
+        assert_eq!(value, "");
+    }
+
+    #[test]
+    fn a_rejected_paste_keeps_the_selected_value() {
+        // TextFieldHelper.insertText: a line too wide is not set at all.
+        let id = ("sign", 1);
+        let mut clip = MemoryClipboard("far too long".into());
+        let mut sel = AppendSelection::default();
+        let mut value = String::from("ok");
+        sel.apply(
+            id,
+            &mut value,
+            EditShortcut::SelectAll,
+            &mut clip,
+            |_, _| true,
+        );
+        let fits = |v: &mut String, t: &str| {
+            let next = format!("{v}{t}");
+            next.len() <= 5 && {
+                *v = next;
+                true
+            }
+        };
+        assert!(!sel.apply(id, &mut value, EditShortcut::Paste, &mut clip, fits));
+        assert_eq!(value, "ok");
+    }
+}
@@ -0,0 +1,140 @@
+//! Cloud visibility and flat/fancy cell geometry (`CloudRenderer`).
+/// `LevelRenderer`: skip OFF clouds and colors with no packed alpha.
+pub fn visible(mode: &str, alpha: f32) -> bool {
+    mode != "false" && (alpha.clamp(0.0, 1.0) * 255.0) as u8 > 0
+}
+
+/// `buildFlatCell`: bottom plane, in both windings for the culled cloud pipeline.
+pub fn flat_cell(x: f32, z: f32, bottom: f32) -> [[[f32; 3]; 4]; 2] {
+    let p = [
+        [x + 12.0, bottom, z],
+        [x + 12.0, bottom, z + 12.0],
+        [x, bottom, z + 12.0],
+        [x, bottom, z],
+    ];
+    [p, [p[3], p[2], p[1], p[0]]]
+}
+
+/// Direction order is DOWN, UP, NORTH, SOUTH, WEST, EAST; inward faces use bits 6..12.
+pub fn face_mask(x: i32, z: i32, bottom: f32, empty: [bool; 4]) -> u16 {
+    let mut mask = 0;
+    if bottom <= 0.0 {
+        mask |= 1 << 1;
+    }
+    if bottom + 4.0 >= 0.0 {
+        mask |= 1;
+    }
+    for (i, visible) in [z > 0, z < 0, x > 0, x < 0].into_iter().enumerate() {
+        if empty[i] && visible {
+            mask |= 1 << (i + 2);
+        }
+    }
+    if x.abs() <= 1 && z.abs() <= 1 {
+        mask |= 63 << 6;
+    }
+    mask
+}
+
+/// Exterior faces first, then reversed interior faces, in vanilla emission order.
+pub fn faces(mask: u16) -> impl Iterator<Item = (u8, bool)> {
+    [1, 0, 2, 3, 4, 5]
+        .into_iter()
+        .filter(move |d| mask & (1 << d) != 0)
+        .map(|d| (d, false))
+        .chain(
+            (0..6)
+                .filter(move |d| mask & (1 << (d + 6)) != 0)
+                .map(|d| (d, true)),
+        )
+}
+
+/// `CloudRenderer.prepare`: the cell radius for the Cloud Distance option
+/// (in chunks), independent of the render distance.
+pub fn radius_cells(cloud_range_chunks: i32) -> i32 {
+    ((cloud_range_chunks * 16) as f32 / 12.0).ceil() as i32
+}
+
+/// CloudRenderer builds cells in expanding Manhattan rings, nearest first.
+pub fn cells(radius: i32) -> impl Iterator<Item = (i32, i32)> {
+    (0..=2 * radius).flat_map(move |ring| {
+        (-ring..=ring).flat_map(move |x| {
+            let z = ring - x.abs();
+            let visible = z <= radius && x * x + z * z <= radius * radius;
+            (visible && z != 0)
+                .then_some((x, -z))
+                .into_iter()
+                .chain(visible.then_some((x, z)))
+        })
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn settings_and_packed_alpha_gate_clouds() {
+        for mode in ["false", "fast", "true"] {
+            assert_eq!(visible(mode, 1.0), mode != "false");
+            assert!(!visible(mode, 0.0));
+            assert!(!visible(mode, 0.5 / 255.0));
+        }
+        assert!(visible("fast", 1.0 / 255.0));
+    }
+
+    #[test]
+    fn fast_cells_are_flat_at_the_bottom_and_visible_from_both_sides() {
+        for bottom in [-10.0, 0.0, 10.0] {
+            let [down, up] = flat_cell(-3.0, 7.0, bottom);
+            assert_eq!(
+                down,
+                [
+                    [9.0, bottom, 7.0],
+                    [9.0, bottom, 19.0],
+                    [-3.0, bottom, 19.0],
+                    [-3.0, bottom, 7.0],
+                ]
+            );
+            assert_eq!(up, [down[3], down[2], down[1], down[0]]);
+            for (quad, sign) in [(down, -1.0), (up, 1.0)] {
+                let [a, b, c] = [quad[0], quad[1], quad[2]].map(glam::Vec3::from_array);
+                assert!((b - a).cross(c - a).y * sign > 0.0);
+            }
+        }
+    }
+
+    #[test]
+    fn cells_are_nearest_first_and_unique() {
+        let cells: Vec<_> = cells(2).collect();
+        assert_eq!(cells[0], (0, 0));
+        assert_eq!(cells.len(), 13);
+        assert!(
+            cells
+                .windows(2)
+                .all(|w| w[0].0.abs() + w[0].1.abs() <= w[1].0.abs() + w[1].1.abs())
+        );
+        assert_eq!(
+            cells.iter().collect::<std::collections::HashSet<_>>().len(),
+            cells.len()
+        );
+    }
+    #[test]
+    fn only_camera_facing_exterior_faces() {
+        assert_eq!(face_mask(2, 2, 10.0, [true; 4]), 1 | 4 | 16);
+        assert_eq!(face_mask(-2, -2, -5.0, [true; 4]), 2 | 8 | 32);
+        assert_eq!(face_mask(2, 2, 0.0, [false; 4]), 3);
+    }
+    #[test]
+    fn cloud_distance_sets_the_radius() {
+        assert_eq!(radius_cells(2), 3);
+        assert_eq!(radius_cells(12), 16);
+        assert_eq!(radius_cells(128), 171);
+    }
+    #[test]
+    fn connected_cells_have_no_exterior_walls() {
+        assert_eq!(face_mask(2, 2, 10.0, [false; 4]), 1);
+    }
+    #[test]
+    fn nearby_cells_keep_inward_faces_for_camera_inside_clouds() {
+        assert_eq!(face_mask(0, 0, 0.0, [false; 4]), 3 | (63 << 6));
+    }
+}
@@ -10,10 +10,10 @@ use horizon_world::{
    block_collision::{BlockCollisionRegistry, DynamicCollisionWorld, ShulkerCollisionState},
    block_collision_scan::{BlockCollisionWorld, CollisionBlock},
    collision::CachedCollisionRegistry,
-    collision_context::CollisionContext,
+    collision_context::{CollisionContext, CollisionEntity, CollisionItem},
    dynamic_support::DynamicSupportWorld,
    entity_obstruction::EntityIdentity,
-    fluid::FluidState,
+    fluid::{FluidKind, FluidState},
    liquid_collision::LiquidCollisionWorld,
    nbt::{self, Limits},
    powder_snow_collision::{PowderSnowEntity, PowderSnowWorld},
@@ -39,13 +39,36 @@ pub fn load<'r>(root: &Path, registry: &'r BlockRegistry) -> Result<BlockCollisi
    Ok(BlockCollisionRegistry::new(Arc::new(cached))?)
 }

+/// What powder snow's and liquids' contextual collisions ask of the colliding
+/// entity (`PowderSnowBlock` and `LiquidBlock.getCollisionShape`).
+#[derive(Clone, Copy, Debug, Default)]
+pub struct PowderSnowSubject {
+    pub fall_distance: f64,
+    /// `FallingBlockEntity`.
+    pub falling_block: bool,
+    /// A living entity with leather boots on its feet.
+    pub leather_boots: bool,
+    /// `EntityTypeTags.POWDER_SNOW_WALKABLE_MOBS`.
+    pub walkable_type: bool,
+    /// A strider: lava sources hold it up (`canStandOnFluid`), on its
+    /// `getLiquidCollisionShape`.
+    pub lava_walker: bool,
+}
+/// `Strider.getLiquidCollisionShape`: `Block.column(16.0, 0.0, 8.0)`.
+fn strider_liquid_shape() -> VoxelShape {
+    VoxelShape::from_cube([1, 2, 1], &[true, false]).expect("a valid half-block column")
+}
+
 pub struct SceneCollisions<'w, 'r> {
    pub world: &'w World,
    pub binding: &'w BlockCollisionRegistry<'r>,
+    /// The entity colliding, for powder snow; None: no fall, no boots.
+    pub subject: Option<PowderSnowSubject>,
 }
 impl SceneCollisions<'_, '_> {
    /// Position contexts permit geometric movement probes without inventing a
-    /// player, inventory, effects or fluid-standing behavior.
+    /// player, inventory, effects or fluid-standing behavior; a lava walker
+    /// collides as the living entity it is, empty-handed.
    pub fn resolve(
        &mut self,
        bounds: Aabb,
@@ -57,7 +80,7 @@ impl SceneCollisions<'_, '_> {
            self,
            MovementRequest {
                entity: EntityIdentity(0),
-                context: CollisionContext::position(bounds.min_position().y),
+                context: self.context(bounds),
                bounds,
                movement,
                max_step,
@@ -66,6 +89,21 @@ impl SceneCollisions<'_, '_> {
            },
        )?)
    }
+    fn context(&self, bounds: Aabb) -> CollisionContext<'static> {
+        let y = bounds.min_position().y;
+        if !self.subject.is_some_and(|s| s.lava_walker) {
+            return CollisionContext::position(y);
+        }
+        CollisionContext::for_entity(
+            CollisionEntity {
+                identity: EntityIdentity(0),
+                y,
+                descending: false,
+                main_hand: Some(CollisionItem::EMPTY),
+            },
+            false,
+        )
+    }
    pub fn unobstructed(&mut self, bounds: Aabb) -> Result<bool> {
        Ok(no_world_collision(
            self,
@@ -81,6 +119,20 @@ impl SceneCollisions<'_, '_> {
 /// `noCollision(null, box)`: block collisions under the empty collision
 /// context, as entity-less queries such as spawn checks use.
 pub fn no_collision_empty<W, E>(world: &mut W, bounds: Aabb) -> bool
+where
+    W: BlockCollisionWorld<Error = E> + EntityMovementWorld<Error = E>,
+{
+    no_collision_in(world, bounds, false)
+}
+/// `noCollision(null, box, true)`: the same with liquids colliding as
+/// blocks (`CollisionContext.emptyWithFluidCollisions`).
+pub fn no_collision_or_liquid<W, E>(world: &mut W, bounds: Aabb) -> bool
+where
+    W: BlockCollisionWorld<Error = E> + EntityMovementWorld<Error = E>,
+{
+    no_collision_in(world, bounds, true)
+}
+fn no_collision_in<W, E>(world: &mut W, bounds: Aabb, fluids: bool) -> bool
 where
    W: BlockCollisionWorld<Error = E> + EntityMovementWorld<Error = E>,
 {
@@ -88,7 +140,7 @@ where
        world,
        CollisionCheckRequest {
            entity: EntityIdentity(0),
-            context: CollisionContext::empty(false),
+            context: CollisionContext::empty(fluids),
            bounds,
            candidate_budget: 1_000_000,
        },
@@ -151,9 +203,13 @@ impl DynamicCollisionWorld for SceneCollisions<'_, '_> {
 }
 impl LiquidCollisionWorld for SceneCollisions<'_, '_> {
    type Error = io::Error;
-    /// Players and the supported mobs cannot stand on fluids (no striders).
+    /// Only striders stand on fluids.
    fn entity_liquid_shape(&mut self, _: EntityIdentity) -> io::Result<VoxelShape> {
-        Ok(VoxelShape::empty())
+        Ok(if self.subject.is_some_and(|s| s.lava_walker) {
+            strider_liquid_shape()
+        } else {
+            VoxelShape::empty()
+        })
    }
    fn fluid(&mut self, p: BlockPos) -> io::Result<FluidState> {
        FluidState::from_block(
@@ -163,24 +219,26 @@ impl LiquidCollisionWorld for SceneCollisions<'_, '_> {
                .ok_or_else(|| io::Error::other("scene fluid state outside registry"))?,
        )
    }
-    fn entity_can_stand(&mut self, _: EntityIdentity, _: FluidState) -> io::Result<bool> {
-        Ok(false)
+    /// `Strider.canStandOnFluid`: lava.
+    fn entity_can_stand(&mut self, _: EntityIdentity, fluid: FluidState) -> io::Result<bool> {
+        Ok(self.subject.is_some_and(|s| s.lava_walker)
+            && matches!(fluid.kind(), FluidKind::Lava | FluidKind::FlowingLava))
    }
 }
 impl PowderSnowWorld for SceneCollisions<'_, '_> {
    type Error = io::Error;
-    // Entities here are never falling blocks and wear no leather boots.
    fn powder_snow_entity(&mut self, _: EntityIdentity) -> io::Result<PowderSnowEntity> {
+        let subject = self.subject.unwrap_or_default();
        Ok(PowderSnowEntity {
-            fall_distance: 0.0,
-            falling_block: false,
+            fall_distance: subject.fall_distance,
+            falling_block: subject.falling_block,
        })
    }
    fn powder_snow_walkable_tag(&mut self, _: EntityIdentity) -> io::Result<bool> {
-        Ok(false)
+        Ok(self.subject.is_some_and(|s| s.walkable_type))
    }
    fn feet_are_leather_boots(&mut self, _: EntityIdentity) -> io::Result<bool> {
-        Ok(false)
+        Ok(self.subject.is_some_and(|s| s.leather_boots))
    }
 }

@@ -0,0 +1,278 @@
+//! The mouse handling every survival and container screen shares
+//! (`AbstractContainerScreen.mouseClicked` / `mouseReleased`): which slot id
+//! a click targets (-999 outside the window, `hasClickedOutside` with the
+//! recipe book's own rule) and which `ContainerInput` it sends. Shift is
+//! the event's own modifiers (`InputWithModifiers.hasShiftDown`: the
+//! physical Shift keys, never the remapped or toggled sneak key).
+
+use crate::menu::Input;
+
+/// The screen's window: `leftPos`, `topPos`, `imageWidth`, `imageHeight`.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub struct Image {
+    pub left: i32,
+    pub top: i32,
+    pub width: i32,
+    pub height: i32,
+}
+
+/// The recipe book of an `AbstractRecipeBookScreen`.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub struct Book {
+    /// `RecipeBookComponent.isVisible`.
+    pub visible: bool,
+    /// `selectedTab.isHoveredOrFocused()`.
+    pub selected_tab_hovered: bool,
+}
+
+/// `RecipeBookComponent.IMAGE_WIDTH`.
+const BOOK_WIDTH: i32 = 147;
+
+fn outside(mx: f64, my: f64, image: Image) -> bool {
+    mx < f64::from(image.left)
+        || my < f64::from(image.top)
+        || mx >= f64::from(image.left + image.width)
+        || my >= f64::from(image.top + image.height)
+}
+
+/// `AbstractContainerScreen.hasClickedOutside`, or
+/// `AbstractRecipeBookScreen.hasClickedOutside` when the screen has a book
+/// (`RecipeBookComponent.hasClickedOutside`: a click on the book, or with
+/// its selected tab hovered, is not outside).
+pub fn clicked_outside(mx: f64, my: f64, image: Image, book: Option<Book>) -> bool {
+    let out = outside(mx, my, image);
+    let Some(book) = book else {
+        return out;
+    };
+    let book_outside = !book.visible || {
+        let on_book = f64::from(image.left - BOOK_WIDTH) < mx
+            && mx < f64::from(image.left)
+            && f64::from(image.top) < my
+            && my < f64::from(image.top + image.height);
+        out && !on_book && !book.selected_tab_hovered
+    };
+    book_outside && out
+}
+
+/// What a click points at: a slot, outside the window (slot id -999), or
+/// neither (slot id -1).
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum Target<S> {
+    Slot(S),
+    Outside,
+    Nothing,
+}
+
+impl<S> Target<S> {
+    /// Outside wins over a hovered slot, as in `mouseClicked`.
+    pub fn of(slot: Option<S>, outside: bool) -> Self {
+        match slot {
+            _ if outside => Self::Outside,
+            Some(s) => Self::Slot(s),
+            None => Self::Nothing,
+        }
+    }
+}
+
+/// The left, right and middle buttons (SDL's 1, 3 and 2).
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum Button {
+    Left,
+    Right,
+    Middle,
+}
+
+impl Button {
+    /// `getContainerClickButton`: the button a menu click carries.
+    pub fn menu_button(self) -> i32 {
+        match self {
+            Self::Left => 0,
+            Self::Right => 1,
+            Self::Middle => 2,
+        }
+    }
+}
+
+/// The input state `mouseClicked`/`mouseReleased` keep between events.
+#[derive(Clone, Debug, Default)]
+pub struct Clicks {
+    /// `isQuickCrafting` with `quickCraftingButton`.
+    quick_crafting: Option<Button>,
+    skip_next_release: bool,
+}
+
+/// What a release does.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum Release {
+    /// `slotClicked` with this input on the release's target.
+    Click(Input),
+    /// `quickCraftToSlots` over the dragged slots.
+    QuickCraft,
+    Nothing,
+}
+
+impl Clicks {
+    /// A quick craft drag in progress, and the button that started it.
+    pub fn quick_crafting(&self) -> Option<Button> {
+        self.quick_crafting
+    }
+
+    /// A press Horizon handled itself (a double click's `PICKUP_ALL`): its
+    /// release clicks nothing more.
+    pub fn skip_release(&mut self) {
+        self.quick_crafting = None;
+        self.skip_next_release = true;
+    }
+
+    /// `mouseClicked` (no double click): the `slotClicked` input it sends on
+    /// `target`, if any. A press holding a stack starts a quick craft drag
+    /// instead. `cloning` is `keyPickItem` with infinite materials.
+    pub fn press<S>(
+        &mut self,
+        target: &Target<S>,
+        button: Button,
+        carried_empty: bool,
+        shift: bool,
+        cloning: bool,
+    ) -> Option<Input> {
+        self.skip_next_release = false;
+        if button == Button::Middle && !cloning {
+            return None;
+        }
+        if matches!(target, Target::Nothing) || self.quick_crafting.is_some() {
+            return None;
+        }
+        if !carried_empty {
+            self.quick_crafting = Some(button);
+            return None;
+        }
+        self.skip_next_release = true;
+        Some(if cloning {
+            Input::Clone
+        } else if shift && !matches!(target, Target::Outside) {
+            Input::QuickMove
+        } else if matches!(target, Target::Outside) {
+            Input::Throw
+        } else {
+            Input::Pickup
+        })
+    }
+
+    /// `mouseReleased` (no double click). `dragged` is whether the quick
+    /// craft drag collected any slots; `pick_item` is the release of the
+    /// `keyPickItem` button.
+    pub fn release<S>(
+        &mut self,
+        target: &Target<S>,
+        button: Button,
+        carried_empty: bool,
+        dragged: bool,
+        shift: bool,
+        pick_item: bool,
+    ) -> Release {
+        if self.quick_crafting.is_some_and(|b| b != button) {
+            self.quick_crafting = None;
+            self.skip_next_release = true;
+            return Release::Nothing;
+        }
+        if self.skip_next_release {
+            self.skip_next_release = false;
+            return Release::Nothing;
+        }
+        let quick_crafting = self.quick_crafting.take().is_some();
+        if quick_crafting && dragged {
+            Release::QuickCraft
+        } else if carried_empty {
+            Release::Nothing
+        } else if pick_item {
+            Release::Click(Input::Clone)
+        } else if shift && !matches!(target, Target::Outside) {
+            Release::Click(Input::QuickMove)
+        } else {
+            Release::Click(Input::Pickup)
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const INV: Image = Image {
+        left: 100,
+        top: 50,
+        width: 176,
+        height: 166,
+    };
+
+    #[test]
+    fn window_edges() {
+        assert!(!clicked_outside(100.0, 50.0, INV, None));
+        assert!(clicked_outside(99.9, 60.0, INV, None));
+        assert!(clicked_outside(276.0, 60.0, INV, None));
+        assert!(!clicked_outside(275.9, 215.9, INV, None));
+    }
+
+    #[test]
+    fn the_open_book_is_not_outside() {
+        let book = Book {
+            visible: true,
+            selected_tab_hovered: false,
+        };
+        assert!(!clicked_outside(10.0, 100.0, INV, Some(book)));
+        assert!(clicked_outside(-60.0, 100.0, INV, Some(book)));
+        assert!(!clicked_outside(
+            -60.0,
+            100.0,
+            INV,
+            Some(Book {
+                selected_tab_hovered: true,
+                ..book
+            })
+        ));
+        let closed = Book {
+            visible: false,
+            ..book
+        };
+        assert!(clicked_outside(10.0, 100.0, INV, Some(closed)));
+    }
+
+    #[test]
+    fn a_carried_stack_thrown_outside() {
+        let mut clicks = Clicks::default();
+        let out = Target::<usize>::Outside;
+        assert_eq!(clicks.press(&out, Button::Left, false, false, false), None);
+        assert_eq!(
+            clicks.release(&out, Button::Left, false, false, false, false),
+            Release::Click(Input::Pickup)
+        );
+        // Shift never quick-moves outside, and an empty hand throws nothing.
+        assert_eq!(
+            clicks.press(&out, Button::Right, true, true, false),
+            Some(Input::Throw)
+        );
+        assert_eq!(
+            clicks.release(&out, Button::Right, true, false, true, false),
+            Release::Nothing
+        );
+    }
+
+    #[test]
+    fn another_button_cancels_the_drag() {
+        let mut clicks = Clicks::default();
+        let slot = Target::Slot(3);
+        clicks.press(&slot, Button::Left, false, false, false);
+        assert_eq!(
+            clicks.release(&slot, Button::Right, false, true, false, false),
+            Release::Nothing
+        );
+        assert_eq!(
+            clicks.release(&slot, Button::Left, false, true, false, false),
+            Release::Nothing
+        );
+        assert_eq!(
+            clicks.release(&slot, Button::Left, false, true, true, false),
+            Release::Click(Input::QuickMove)
+        );
+    }
+}
@@ -66,6 +66,12 @@ pub enum BlockEntity {
    Banner(Banner),
    /// `CrafterBlockEntity`.
    Crafter(Crafter),
+    /// `SpawnerBlockEntity` (`crate::mobs::spawner`).
+    Spawner(Box<crate::mobs::spawner::Spawner>),
+    /// `TrialSpawnerBlockEntity` (`crate::mobs::trial_spawner`).
+    TrialSpawner(Box<crate::mobs::trial_spawner::TrialSpawner>),
+    /// `BeehiveBlockEntity` of beehives and bee nests (`crate::beehive`).
+    Beehive(Box<crate::beehive::Beehive>),
 }
 /// `CrafterBlockEntity`: nine slots that can be disabled, the powered flag
 /// and the ticks left in the crafting animation.
@@ -180,6 +186,15 @@ impl BlockEntity {
        if name == "minecraft:creaking_heart" {
            return Some(Self::CreakingHeart(Box::default()));
        }
+        if name == "minecraft:spawner" {
+            return Some(Self::Spawner(Box::default()));
+        }
+        if name == "minecraft:trial_spawner" {
+            return Some(Self::TrialSpawner(Box::default()));
+        }
+        if name == "minecraft:beehive" || name == "minecraft:bee_nest" {
+            return Some(Self::Beehive(Box::default()));
+        }
        if name == "minecraft:lectern" {
            return Some(Self::Lectern(Lectern::default()));
        }
@@ -255,6 +270,9 @@ impl BlockEntity {
            Self::Banner(_) => "minecraft:banner",
            Self::Crafter(_) => "minecraft:crafter",
            Self::CreakingHeart(_) => "minecraft:creaking_heart",
+            Self::Spawner(_) => "minecraft:mob_spawner",
+            Self::TrialSpawner(_) => "minecraft:trial_spawner",
+            Self::Beehive(_) => "minecraft:beehive",
        }
    }
    pub fn contents(&self) -> Vec<ItemStack> {
@@ -264,7 +282,11 @@ impl BlockEntity {
            Self::Brewing(b) => b.items.iter().flatten().cloned().collect(),
            Self::Sign(_) => Vec::new(),
            Self::Jukebox(j) => j.record.iter().cloned().collect(),
-            Self::Beacon(_) | Self::CreakingHeart(_) => Vec::new(),
+            Self::Beacon(_)
+            | Self::CreakingHeart(_)
+            | Self::Spawner(_)
+            | Self::TrialSpawner(_)
+            | Self::Beehive(_) => Vec::new(),
            Self::Lectern(l) => l.book.iter().cloned().collect(),
            Self::Sculk(_) => Vec::new(),
            Self::Banner(_) => Vec::new(),
@@ -283,7 +305,10 @@ impl BlockEntity {
            | Self::Sculk(_)
            | Self::Banner(_) => &[],
            Self::Crafter(c) => &c.items,
-            Self::CreakingHeart(_) => &[],
+            Self::CreakingHeart(_)
+            | Self::Spawner(_)
+            | Self::TrialSpawner(_)
+            | Self::Beehive(_) => &[],
        }
    }
    pub fn slots_mut(&mut self) -> &mut [Option<ItemStack>] {
@@ -298,7 +323,10 @@ impl BlockEntity {
            | Self::Sculk(_)
            | Self::Banner(_) => &mut [],
            Self::Crafter(c) => &mut c.items,
-            Self::CreakingHeart(_) => &mut [],
+            Self::CreakingHeart(_)
+            | Self::Spawner(_)
+            | Self::TrialSpawner(_)
+            | Self::Beehive(_) => &mut [],
        }
    }
 }
@@ -427,6 +455,32 @@ fn remainder(item: &str) -> Option<&'static str> {
    }
 }
 impl Furnace {
+    /// `AbstractFurnaceBlockEntity.setItem` on the input slot: anything but
+    /// the same item with the same components restarts cooking, with the
+    /// total time of the new input's recipe (200 ticks without one).
+    pub fn set_input(&mut self, recipes: &Recipes, stack: Option<ItemStack>) {
+        let same = match (&self.items[0], &stack) {
+            (Some(old), Some(new)) => old.same_item_same_components(new),
+            _ => false,
+        };
+        self.items[0] = stack;
+        if !same {
+            self.cooking_total = self.items[0]
+                .as_ref()
+                .and_then(|input| recipes.cook(self.kind.recipe_type(), input))
+                .map_or(200, |recipe| total_time(recipe.time, self.speed));
+            self.cooking_timer = 0;
+        }
+    }
+    /// A menu click wrote its slots into `items`, and `before` was the input
+    /// slot until then: the menu called `setItem` on it only if it changed
+    /// (`Slot.setByPlayer`; partial takes and merges keep the stack).
+    pub fn input_clicked(&mut self, recipes: &Recipes, before: Option<ItemStack>) {
+        if self.items[0] != before {
+            let after = std::mem::replace(&mut self.items[0], before);
+            self.set_input(recipes, after);
+        }
+    }
    /// One server tick. Returns `Some(lit)` when the LIT block state must change.
    pub fn tick(
        &mut self,
@@ -3,8 +3,15 @@
 //! Each connection sends commands as text lines and receives one JSON line per
 //! command. Commands are executed on the game thread between frames; replies
 //! that depend on a later frame (screenshots, benchmarks) arrive when ready.
+//!
+//! Two transports carry the same lines. On Linux and macOS the endpoint is a
+//! Unix domain socket. Where those don't exist (Windows), or when the endpoint
+//! path ends in `.json`, the game listens on a random localhost TCP port and
+//! writes `{"transport":"tcp","port":N,"token":"..."}` to the path, readable
+//! only by its user; a client's first line must then be `auth TOKEN`.
 use std::{
-    io::{BufRead, BufReader, Write},
+    io::{self, BufRead, BufReader, Read, Write},
+    net::{Ipv4Addr, TcpListener, TcpStream},
    path::{Path, PathBuf},
    sync::mpsc,
    thread,
@@ -12,54 +19,128 @@ use std::{

 #[cfg(unix)]
 pub use std::os::unix::net::{UnixListener, UnixStream};
-#[cfg(not(unix))]
-pub use unsupported::{UnixListener, UnixStream};

-/// Windows' standard library has no Unix domain sockets: there the control
-/// socket reports itself unavailable and the game runs without it.
-#[cfg(not(unix))]
-mod unsupported {
-    use std::{io, path::Path};
+/// A connection to the control endpoint, over either transport.
+pub enum Stream {
+    #[cfg(unix)]
+    Unix(UnixStream),
+    Tcp(TcpStream),
+}

-    fn unavailable() -> io::Error {
-        io::Error::new(
-            io::ErrorKind::Unsupported,
-            "the control socket needs Unix domain sockets (Linux or macOS)",
-        )
+impl Stream {
+    pub fn try_clone(&self) -> io::Result<Self> {
+        Ok(match self {
+            #[cfg(unix)]
+            Self::Unix(s) => Self::Unix(s.try_clone()?),
+            Self::Tcp(s) => Self::Tcp(s.try_clone()?),
+        })
    }
-    pub struct UnixStream;
-    impl UnixStream {
-        pub fn connect<P: AsRef<Path>>(_: P) -> io::Result<Self> {
-            Err(unavailable())
-        }
-        pub fn try_clone(&self) -> io::Result<Self> {
-            Err(unavailable())
+    /// A read timeout (None waits forever).
+    pub fn set_read_timeout(&self, timeout: Option<std::time::Duration>) -> io::Result<()> {
+        match self {
+            #[cfg(unix)]
+            Self::Unix(s) => s.set_read_timeout(timeout),
+            Self::Tcp(s) => s.set_read_timeout(timeout),
        }
    }
-    impl io::Read for UnixStream {
-        fn read(&mut self, _: &mut [u8]) -> io::Result<usize> {
-            Err(unavailable())
+}
+impl Read for Stream {
+    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        match self {
+            #[cfg(unix)]
+            Self::Unix(s) => s.read(buf),
+            Self::Tcp(s) => s.read(buf),
        }
    }
-    impl io::Write for UnixStream {
-        fn write(&mut self, _: &[u8]) -> io::Result<usize> {
-            Err(unavailable())
-        }
-        fn flush(&mut self) -> io::Result<()> {
-            Ok(())
+}
+impl Write for Stream {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        match self {
+            #[cfg(unix)]
+            Self::Unix(s) => s.write(buf),
+            Self::Tcp(s) => s.write(buf),
        }
    }
-    pub struct UnixListener;
-    impl UnixListener {
-        pub fn bind<P: AsRef<Path>>(_: P) -> io::Result<Self> {
-            Err(unavailable())
-        }
-        pub fn incoming(&self) -> std::iter::Empty<io::Result<UnixStream>> {
-            std::iter::empty()
+    fn flush(&mut self) -> io::Result<()> {
+        match self {
+            #[cfg(unix)]
+            Self::Unix(s) => s.flush(),
+            Self::Tcp(s) => s.flush(),
        }
    }
 }

+/// Whether the endpoint at `path` is a TCP port described by a JSON file.
+pub fn uses_tcp(path: &Path) -> bool {
+    !cfg!(unix) || path.extension().is_some_and(|e| e == "json")
+}
+
+/// The TCP endpoint file: (port, token).
+fn read_endpoint(path: &Path) -> io::Result<(u16, String)> {
+    let text = std::fs::read_to_string(path)?;
+    let bad = || io::Error::new(io::ErrorKind::InvalidData, "not a control endpoint file");
+    let v: serde_json::Value = serde_json::from_str(&text).map_err(|_| bad())?;
+    let port = v["port"]
+        .as_u64()
+        .and_then(|p| u16::try_from(p).ok())
+        .ok_or_else(bad)?;
+    let token = v["token"].as_str().ok_or_else(bad)?.to_owned();
+    Ok((port, token))
+}
+
+/// Connect to a running game's control endpoint (and authenticate over TCP).
+pub fn connect(path: &Path) -> io::Result<Stream> {
+    #[cfg(unix)]
+    if !uses_tcp(path) {
+        return UnixStream::connect(path).map(Stream::Unix);
+    }
+    let (port, token) = read_endpoint(path)?;
+    let mut stream = TcpStream::connect((Ipv4Addr::LOCALHOST, port))?;
+    stream.set_nodelay(true)?;
+    writeln!(stream, "auth {token}")?;
+    let mut reply = String::new();
+    BufReader::new(stream.try_clone()?).read_line(&mut reply)?;
+    if !reply.contains("\"ok\"") {
+        return Err(io::Error::new(
+            io::ErrorKind::PermissionDenied,
+            format!("the game refused the token: {}", reply.trim()),
+        ));
+    }
+    Ok(Stream::Tcp(stream))
+}
+
+/// 128 random bits as hex, from the standard library's OS-seeded hasher keys.
+fn random_token() -> String {
+    use std::hash::{BuildHasher, Hasher};
+    (0..2)
+        .map(|i| {
+            let mut h = std::collections::hash_map::RandomState::new().build_hasher();
+            h.write_u64(i);
+            h.write_u128(
+                std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)
+                    .map_or(0, |d| d.as_nanos()),
+            );
+            h.write_u32(std::process::id());
+            format!("{:016x}", h.finish())
+        })
+        .collect()
+}
+
+/// Write the endpoint file so that only this user can read it.
+fn write_private(path: &Path, text: &str) -> io::Result<()> {
+    let mut options = std::fs::OpenOptions::new();
+    options.write(true).create(true).truncate(true);
+    #[cfg(unix)]
+    std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
+    options.open(path)?.write_all(text.as_bytes())
+}
+
+/// Constant-time comparison of the presented token.
+fn same_token(a: &str, b: &str) -> bool {
+    a.len() == b.len() && a.bytes().zip(b.bytes()).fold(0u8, |d, (x, y)| d | (x ^ y)) == 0
+}
+
 /// One command line from a client, with the channel for its JSON reply.
 pub struct Request {
    pub line: String,
@@ -69,40 +150,78 @@ pub struct Request {
 pub struct Server {
    path: PathBuf,
    requests: mpsc::Receiver<Request>,
+    sender: mpsc::Sender<Request>,
 }

-/// `$HORIZON_CONTROL`, else `horizon-control.sock` in the user's runtime directory.
+/// `$HORIZON_CONTROL`, else `horizon-control.sock` in the user's runtime
+/// directory (`horizon-control.json` in the temporary directory on Windows).
 pub fn default_path() -> PathBuf {
    if let Some(path) = std::env::var_os("HORIZON_CONTROL") {
        return path.into();
    }
+    if !cfg!(unix) {
+        return std::env::temp_dir().join("horizon-control.json");
+    }
    let dir = std::env::var_os("XDG_RUNTIME_DIR").map_or_else(std::env::temp_dir, PathBuf::from);
    dir.join("horizon-control.sock")
 }

 impl Server {
-    pub fn start(path: &Path) -> std::io::Result<Self> {
-        // A socket left by a crashed game refuses connections; replace it.
-        if path.exists() && UnixStream::connect(path).is_err() {
+    pub fn start(path: &Path) -> io::Result<Self> {
+        // An endpoint left by a crashed game refuses connections; replace it.
+        if path.exists() && connect(path).is_err() {
            std::fs::remove_file(path)?;
        }
-        let listener = UnixListener::bind(path)?;
        let (sender, requests) = mpsc::channel();
-        thread::Builder::new()
-            .name("horizon-control".into())
-            .spawn(move || {
-                for stream in listener.incoming().flatten() {
-                    let sender = sender.clone();
-                    let _ = thread::Builder::new()
-                        .name("horizon-control-client".into())
-                        .spawn(move || serve(stream, &sender));
-                }
-            })?;
+        let local = sender.clone();
+        if uses_tcp(path) {
+            let listener = TcpListener::bind((Ipv4Addr::LOCALHOST, 0))?;
+            let token = random_token();
+            let port = listener.local_addr()?.port();
+            write_private(
+                path,
+                &serde_json::json!({ "transport": "tcp", "port": port, "token": token })
+                    .to_string(),
+            )?;
+            spawn_listener(
+                move || listener.accept().map(|(s, _)| s),
+                sender,
+                move |stream: TcpStream| {
+                    let _ = stream.set_nodelay(true);
+                    let mut stream = Stream::Tcp(stream);
+                    authenticate(&mut stream, &token).then_some(stream)
+                },
+            )?;
+        } else {
+            #[cfg(unix)]
+            {
+                let listener = UnixListener::bind(path)?;
+                spawn_listener(
+                    move || listener.accept().map(|(s, _)| s),
+                    sender,
+                    |s| Some(Stream::Unix(s)),
+                )?;
+            }
+        }
        Ok(Self {
            path: path.to_owned(),
            requests,
+            sender: local,
        })
    }
+    /// Commands from inside the process only (`--benchmark` without `--control`).
+    pub fn local() -> Self {
+        let (sender, requests) = mpsc::channel();
+        Self {
+            path: PathBuf::new(),
+            requests,
+            sender,
+        }
+    }
+    /// Sends commands as a socket client would, from another thread.
+    pub fn sender(&self) -> mpsc::Sender<Request> {
+        self.sender.clone()
+    }
    pub fn path(&self) -> &Path {
        &self.path
    }
@@ -111,13 +230,68 @@ impl Server {
    }
 }

+/// Accept connections on a thread, one more thread per client.
+fn spawn_listener<S: Send + 'static>(
+    mut accept_next: impl FnMut() -> io::Result<S> + Send + 'static,
+    sender: mpsc::Sender<Request>,
+    accept: impl Fn(S) -> Option<Stream> + Send + Sync + 'static,
+) -> io::Result<()> {
+    let accept = std::sync::Arc::new(accept);
+    thread::Builder::new()
+        .name("horizon-control".into())
+        .spawn(move || {
+            loop {
+                let Ok(stream) = accept_next() else {
+                    thread::sleep(std::time::Duration::from_millis(10));
+                    continue;
+                };
+                let sender = sender.clone();
+                let accept = accept.clone();
+                let _ = thread::Builder::new()
+                    .name("horizon-control-client".into())
+                    .spawn(move || {
+                        if let Some(stream) = accept(stream) {
+                            serve(stream, &sender);
+                        }
+                    });
+            }
+        })?;
+    Ok(())
+}
+
+/// The first line of a TCP client must be `auth TOKEN`.
+fn authenticate(stream: &mut Stream, token: &str) -> bool {
+    let mut line = Vec::new();
+    let mut byte = [0u8; 1];
+    // Read the line byte by byte so nothing after it is buffered away.
+    while line.len() < 256 {
+        match stream.read(&mut byte) {
+            Ok(1) if byte[0] == b'\n' => break,
+            Ok(1) => line.push(byte[0]),
+            _ => return false,
+        }
+    }
+    let line = String::from_utf8_lossy(&line);
+    let ok = line
+        .trim()
+        .strip_prefix("auth ")
+        .is_some_and(|t| same_token(t.trim(), token));
+    let reply = if ok {
+        r#"{"ok":true}"#
+    } else {
+        r#"{"error":"bad or missing token: the first line must be auth TOKEN"}"#
+    };
+    let _ = writeln!(stream, "{reply}");
+    ok
+}
+
 impl Drop for Server {
    fn drop(&mut self) {
        let _ = std::fs::remove_file(&self.path);
    }
 }

-fn serve(stream: UnixStream, sender: &mpsc::Sender<Request>) {
+fn serve(stream: Stream, sender: &mpsc::Sender<Request>) {
    let Ok(mut writer) = stream.try_clone() else {
        return;
    };
@@ -140,10 +314,86 @@ fn serve(stream: UnixStream, sender: &mpsc::Sender<Request>) {
    }
 }

-/// Frame durations since the last reset, summarized like the Java recorder.
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn tcp_endpoint_round_trip() {
+        let path =
+            std::env::temp_dir().join(format!("horizon-ctl-test-{}.json", std::process::id()));
+        let server = Server::start(&path).unwrap();
+        let text = std::fs::read_to_string(&path).unwrap();
+        assert!(text.contains("\"tcp\""));
+        let mut client = connect(&path).unwrap();
+        writeln!(client, "status").unwrap();
+        let request = loop {
+            if let Some(r) = server.try_recv() {
+                break r;
+            }
+            thread::sleep(std::time::Duration::from_millis(5));
+        };
+        assert_eq!(request.line, "status");
+        request.reply.send(r#"{"ok":true}"#.into()).unwrap();
+        let mut reply = String::new();
+        BufReader::new(client).read_line(&mut reply).unwrap();
+        assert_eq!(reply.trim(), r#"{"ok":true}"#);
+        drop(server);
+        assert!(!path.exists());
+    }
+
+    #[test]
+    fn tcp_refuses_a_wrong_token() {
+        let path =
+            std::env::temp_dir().join(format!("horizon-ctl-bad-{}.json", std::process::id()));
+        let _server = Server::start(&path).unwrap();
+        let (port, _) = read_endpoint(&path).unwrap();
+        let mut stream = TcpStream::connect((Ipv4Addr::LOCALHOST, port)).unwrap();
+        writeln!(stream, "auth nope").unwrap();
+        let mut reply = String::new();
+        BufReader::new(stream).read_line(&mut reply).unwrap();
+        assert!(reply.contains("error"));
+    }
+
+    #[test]
+    fn tokens_differ() {
+        assert_ne!(random_token(), random_token());
+        assert_eq!(random_token().len(), 32);
+        assert!(same_token("abc", "abc") && !same_token("abc", "abd") && !same_token("a", "ab"));
+    }
+}
+
+/// Frame durations since the last reset, summarized like the Java recorder,
+/// with the CPU part of each frame and GPU times from timestamp queries.
 #[derive(Default)]
 pub struct FrameStats {
    millis: Vec<f32>,
+    cpu: Vec<f32>,
+    gpu: Vec<f32>,
+    /// Milliseconds per frame phase (`PHASES`), one entry per rendered frame.
+    phases: Vec<[f32; PHASES.len()]>,
+}
+
+/// The parts of a frame's CPU time: world streaming and uploads, game ticks,
+/// building the frame's geometry and HUD, and the renderer's own work.
+pub const PHASES: [&str; 4] = ["update", "tick", "prepare", "render"];
+
+fn percentiles(values: &[f32]) -> serde_json::Value {
+    let mut sorted = values.to_vec();
+    sorted.sort_by(f32::total_cmp);
+    let n = sorted.len();
+    if n == 0 {
+        return serde_json::Value::Null;
+    }
+    let total: f64 = sorted.iter().map(|&m| f64::from(m)).sum();
+    let percentile = |p: f64| sorted[((n as f64 * p).ceil() as usize).clamp(1, n) - 1];
+    serde_json::json!({
+        "avg_ms": total / n as f64,
+        "p50_ms": percentile(0.5),
+        "p95_ms": percentile(0.95),
+        "p99_ms": percentile(0.99),
+        "max_ms": sorted[n - 1],
+    })
 }

 impl FrameStats {
@@ -153,8 +403,60 @@ impl FrameStats {
            self.millis.push(millis);
        }
    }
+    /// The frame's own work: its duration minus waits for the GPU, the
+    /// display and the frame limiter.
+    pub fn record_cpu(&mut self, millis: f32) {
+        if self.cpu.len() < Self::LIMIT {
+            self.cpu.push(millis);
+        }
+    }
+    pub fn record_phases(&mut self, millis: [f32; PHASES.len()]) {
+        if self.phases.len() < Self::LIMIT {
+            self.phases.push(millis);
+        }
+    }
+    /// Average milliseconds per phase over the frames whose CPU time is at
+    /// least `min_cpu` (all frames for 0): where the slow frames go.
+    fn phase_average(&self, min_cpu: f32) -> serde_json::Value {
+        let mut sums = [0.0f64; PHASES.len()];
+        let mut n = 0;
+        for (i, phases) in self.phases.iter().enumerate() {
+            if self.cpu.get(i).is_some_and(|&c| c >= min_cpu) {
+                for (sum, m) in sums.iter_mut().zip(phases) {
+                    *sum += f64::from(*m);
+                }
+                n += 1;
+            }
+        }
+        PHASES
+            .iter()
+            .zip(sums)
+            .map(|(name, sum)| (name.to_string(), (sum / f64::from(n.max(1))).into()))
+            .collect::<serde_json::Map<_, _>>()
+            .into()
+    }
+    pub fn record_gpu(&mut self, millis: &[f32]) {
+        if self.gpu.len() < Self::LIMIT {
+            self.gpu.extend_from_slice(millis);
+        }
+    }
+    /// Every recorded frame time, in milliseconds, in order.
+    pub fn frame_millis(&self) -> &[f32] {
+        &self.millis
+    }
+    /// CPU time of every recorded frame, in milliseconds.
+    pub fn cpu_millis(&self) -> &[f32] {
+        &self.cpu
+    }
+    /// GPU time of every frame the GPU timed, in milliseconds.
+    pub fn gpu_millis(&self) -> &[f32] {
+        &self.gpu
+    }
    pub fn reset(&mut self) {
        self.millis.clear();
+        self.cpu.clear();
+        self.gpu.clear();
+        self.phases.clear();
    }
    pub fn summary(&self) -> serde_json::Value {
        let mut sorted = self.millis.clone();
@@ -172,6 +474,15 @@ impl FrameStats {
            .map(|&m| f64::from(m))
            .sum::<f64>()
            / slowest as f64;
+        // Where the slowest 1% of frames by CPU time go.
+        let slow_phases = {
+            let mut cpu = self.cpu.clone();
+            cpu.sort_by(f32::total_cmp);
+            let p99 = cpu
+                .get(cpu.len().saturating_sub(cpu.len().div_ceil(100)))
+                .copied();
+            p99.map_or(serde_json::Value::Null, |p| self.phase_average(p))
+        };
        serde_json::json!({
            "frames": n,
            "seconds": total / 1000.0,
@@ -181,6 +492,10 @@ impl FrameStats {
            "p95_ms": percentile(0.95),
            "p99_ms": percentile(0.99),
            "max_ms": sorted[n - 1],
+            "cpu": percentiles(&self.cpu),
+            "gpu": percentiles(&self.gpu),
+            "phases_avg_ms": self.phase_average(0.0),
+            "slow_phases_avg_ms": slow_phases,
        })
    }
 }
@@ -1061,7 +1061,7 @@ impl Special {
    }
 }
 /// `DyedItemColor.applyDyes` over dye indexes.
-fn apply_dyes(current: Option<i32>, dyes: &[usize]) -> i32 {
+pub(crate) fn apply_dyes(current: Option<i32>, dyes: &[usize]) -> i32 {
    let (mut r, mut g, mut b, mut intensity, mut n) = (0i32, 0i32, 0i32, 0i32, 0i32);
    let mut add = |rgb: u32| {
        let (red, green, blue) = (
@@ -0,0 +1,622 @@
+//! Crash reports, laid out like vanilla's CrashReport.getFriendlyReport: a comment, the time,
+//! a description, the error with its stack, then the details of the game and the machine.
+//! Written to `crash-reports/crash-<yyyy-MM-dd_HH.mm.ss>-client.txt` in the game folder when
+//! the main thread panics or `main` gets an error back. It leaves the machine only scrubbed, and
+//! only if the player allows crash reports (`telemetry`).
+use std::fmt::Write as _;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use chrono::{DateTime, Local};
+
+/// What the game is doing, set as it goes: graphics adapter, settings, packs, world.
+static DETAILS: Mutex<Vec<(&'static str, String)>> = Mutex::new(Vec::new());
+static REPORTED: AtomicBool = AtomicBool::new(false);
+
+/// Sets one line of the report's details (replacing the last value under `key`).
+pub fn set_detail(key: &'static str, value: impl Into<String>) {
+    let mut details = DETAILS.lock().unwrap_or_else(|e| e.into_inner());
+    let value = value.into();
+    match details.iter_mut().find(|(k, _)| *k == key) {
+        Some(entry) => entry.1 = value,
+        None => details.push((key, value)),
+    }
+}
+
+pub fn clear_detail(key: &'static str) {
+    DETAILS
+        .lock()
+        .unwrap_or_else(|e| e.into_inner())
+        .retain(|(k, _)| *k != key);
+}
+
+fn details() -> Vec<(&'static str, String)> {
+    DETAILS.lock().unwrap_or_else(|e| e.into_inner()).clone()
+}
+
+/// Vanilla picks a line from a list of jokes; these only say what happened.
+const COMMENTS: &[&str] = &[
+    "Something went wrong.",
+    "The game stopped here.",
+    "This should not have happened.",
+    "Details below.",
+];
+
+/// One crash, ready to be written.
+pub struct Report {
+    pub time: DateTime<Local>,
+    pub description: String,
+    /// The error's message, first line of the stack section.
+    pub error: String,
+    /// Where it happened and how it got there: one frame a line (`function (file:line:col)`).
+    pub stack: String,
+    pub thread: String,
+    /// `client` or `server`, the end of the file name.
+    pub side: &'static str,
+    pub details: Vec<(String, String)>,
+    pub log: Vec<String>,
+}
+
+/// `crash-2026-10-14_09.05.07-client.txt`
+pub fn file_name(time: &DateTime<Local>, side: &str) -> String {
+    format!("crash-{}-{side}.txt", time.format("%Y-%m-%d_%H.%M.%S"))
+}
+
+impl Report {
+    /// The report's text.
+    pub fn text(&self) -> String {
+        let comment = COMMENTS[self.time.timestamp().rem_euclid(COMMENTS.len() as i64) as usize];
+        let mut out = String::new();
+        let _ = writeln!(out, "---- Horizon Crash Report ----");
+        let _ = writeln!(out, "// {comment}\n");
+        let _ = writeln!(out, "Time: {}", self.time.format("%Y-%m-%d %H:%M:%S"));
+        let _ = writeln!(out, "Description: {}\n", self.description);
+        let _ = writeln!(out, "{}", self.error);
+        for line in self.stack.lines() {
+            let _ = writeln!(out, "\tat {line}");
+        }
+        let _ = writeln!(
+            out,
+            "\n\nA detailed walkthrough of the error, its code path and all known details is as follows:"
+        );
+        let _ = writeln!(out, "{}\n", "-".repeat(87));
+        let _ = writeln!(out, "-- Head --");
+        let _ = writeln!(out, "Thread: {}\n", self.thread);
+        let _ = writeln!(out, "-- System Details --");
+        let _ = writeln!(out, "Details:");
+        for (key, value) in &self.details {
+            let _ = writeln!(out, "\t{key}: {value}");
+        }
+        let _ = writeln!(out, "\n-- Last {} log lines --", self.log.len());
+        for line in &self.log {
+            let _ = writeln!(out, "{line}");
+        }
+        out
+    }
+
+    /// Writes the report in `home/crash-reports` and returns its path.
+    pub fn save(&self, home: &Path) -> std::io::Result<PathBuf> {
+        let dir = crate::logging::crash_reports_dir(home);
+        std::fs::create_dir_all(&dir)?;
+        let path = dir.join(file_name(&self.time, self.side));
+        std::fs::write(&path, self.text())?;
+        Ok(path)
+    }
+}
+
+/// The release tag (the launcher installs each build in a folder named after it) and the client's
+/// own version, or just the latter.
+pub fn version() -> String {
+    let version = env!("CARGO_PKG_VERSION");
+    match release_tag() {
+        Some(tag) => format!("{tag} (client {version})"),
+        None => version.to_owned(),
+    }
+}
+
+/// The release this binary came with: launcher installs live in a folder named after the tag.
+pub fn release_tag() -> Option<String> {
+    let exe = std::env::current_exe().ok()?;
+    let folder = exe.parent()?.file_name()?.to_str()?;
+    (folder.starts_with('v') && folder[1..].starts_with(|c: char| c.is_ascii_digit()))
+        .then(|| folder.to_owned())
+}
+
+fn command_output(program: &str, args: &[&str]) -> Option<String> {
+    let out = std::process::Command::new(program)
+        .args(args)
+        .output()
+        .ok()?;
+    let text = String::from_utf8_lossy(&out.stdout).trim().to_owned();
+    (out.status.success() && !text.is_empty()).then_some(text)
+}
+
+fn read(path: &str) -> Option<String> {
+    std::fs::read_to_string(path).ok()
+}
+
+/// `PRETTY_NAME` of /etc/os-release and the kernel, or the system's own version string.
+fn operating_system() -> String {
+    let arch = std::env::consts::ARCH;
+    let version = if cfg!(target_os = "linux") {
+        let name = read("/etc/os-release").and_then(|t| {
+            t.lines()
+                .find_map(|l| l.strip_prefix("PRETTY_NAME="))
+                .map(|v| v.trim_matches('"').to_owned())
+        });
+        let kernel = read("/proc/sys/kernel/osrelease").map(|k| k.trim().to_owned());
+        match (name, kernel) {
+            (Some(n), Some(k)) => Some(format!("{n}, kernel {k}")),
+            (n, k) => n.or(k),
+        }
+    } else if cfg!(target_os = "macos") {
+        command_output("sw_vers", &["-productVersion"]).map(|v| format!("macOS {v}"))
+    } else if cfg!(windows) {
+        command_output("cmd", &["/C", "ver"])
+    } else {
+        None
+    };
+    format!(
+        "{} ({arch}) version {}",
+        std::env::consts::OS,
+        version.unwrap_or_else(|| "unknown".into())
+    )
+}
+
+fn cpu() -> String {
+    let threads = std::thread::available_parallelism().map_or(0, |n| n.get());
+    let name = if cfg!(target_os = "linux") {
+        read("/proc/cpuinfo").and_then(|t| {
+            t.lines()
+                .find(|l| l.starts_with("model name"))
+                .and_then(|l| l.split_once(':'))
+                .map(|(_, v)| v.trim().to_owned())
+        })
+    } else if cfg!(target_os = "macos") {
+        command_output("sysctl", &["-n", "machdep.cpu.brand_string"])
+    } else {
+        std::env::var("PROCESSOR_IDENTIFIER").ok()
+    };
+    format!(
+        "{threads}x {}",
+        name.unwrap_or_else(|| std::env::consts::ARCH.into())
+    )
+}
+
+/// Total memory and what this process uses, in MiB where the system says.
+fn memory() -> String {
+    const MIB: u64 = 1024 * 1024;
+    let kib = |text: &str, key: &str| -> Option<u64> {
+        text.lines()
+            .find(|l| l.starts_with(key))?
+            .split_whitespace()
+            .nth(1)?
+            .parse()
+            .ok()
+    };
+    let (total, used) = if cfg!(target_os = "linux") {
+        (
+            read("/proc/meminfo")
+                .and_then(|t| kib(&t, "MemTotal:"))
+                .map(|k| k * 1024),
+            read("/proc/self/status")
+                .and_then(|t| kib(&t, "VmRSS:"))
+                .map(|k| k * 1024),
+        )
+    } else if cfg!(target_os = "macos") {
+        (
+            command_output("sysctl", &["-n", "hw.memsize"]).and_then(|v| v.parse().ok()),
+            None,
+        )
+    } else if cfg!(windows) {
+        (
+            command_output(
+                "powershell",
+                &[
+                    "-NoProfile",
+                    "-Command",
+                    "(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory",
+                ],
+            )
+            .and_then(|v| v.parse().ok()),
+            None,
+        )
+    } else {
+        (None, None)
+    };
+    match (total, used) {
+        (Some(t), Some(u)) => format!(
+            "{} MiB used by the game, {} MiB installed",
+            u / MIB,
+            t / MIB
+        ),
+        (Some(t), None) => format!("{} MiB installed", t / MIB),
+        _ => "unknown".into(),
+    }
+}
+
+/// The report's details: Horizon's and the machine's, then what the game set as it ran.
+pub fn system_details() -> Vec<(String, String)> {
+    let mut out = vec![
+        ("Horizon Version".to_owned(), version()),
+        ("Minecraft Version".to_owned(), "26.3".to_owned()),
+        ("Operating System".to_owned(), operating_system()),
+        ("CPU".to_owned(), cpu()),
+        ("Memory".to_owned(), memory()),
+    ];
+    out.extend(details().into_iter().map(|(k, v)| (k.to_owned(), v)));
+    out
+}
+
+fn thread_name() -> String {
+    let current = std::thread::current();
+    match current.name() {
+        Some("main") | None => "Render thread".into(),
+        Some(name) => name.into(),
+    }
+}
+
+/// Writes the report and tells where it is; the log gets the error too.
+fn deliver(home: &Path, report: Report) -> Option<PathBuf> {
+    if REPORTED.swap(true, Ordering::SeqCst) {
+        return None;
+    }
+    // The panic is on stderr already: the stack goes to the log only.
+    crate::logging::write_only(
+        log::Level::Error,
+        &format!(
+            "Horizon crashed: {}\n{}",
+            report.error,
+            report
+                .stack
+                .lines()
+                .map(|l| format!("\tat {l}"))
+                .collect::<Vec<_>>()
+                .join("\n")
+        ),
+    );
+    crate::logging::flush();
+    crate::telemetry::keep_crash(home, &report);
+    match report.save(home) {
+        Ok(path) => {
+            eprintln!("Horizon: crash report saved to {}", path.display());
+            Some(path)
+        }
+        Err(e) => {
+            eprintln!("Horizon: could not save a crash report: {e}");
+            eprintln!("{}", report.text());
+            None
+        }
+    }
+}
+
+fn panic_message(info: &std::panic::PanicHookInfo) -> String {
+    let payload = info.payload();
+    let text = payload
+        .downcast_ref::<&str>()
+        .map(|s| s.to_string())
+        .or_else(|| payload.downcast_ref::<String>().cloned())
+        .unwrap_or_else(|| "Box<dyn Any>".into());
+    match info.location() {
+        Some(at) => format!("panicked at {at}:\n{text}"),
+        None => format!("panicked:\n{text}"),
+    }
+}
+
+/// A `std::backtrace` as one line a frame, `function (file:line:col)`. Captured in a panic hook
+/// (`from_panic`), it starts at the frame that panicked: the hook's and the panic machinery's
+/// frames go. Paths inside the workspace lose the build machine's prefix.
+pub fn stack_lines(backtrace: &str, from_panic: bool) -> String {
+    // The workspace as it was on the machine that built this binary (it need not exist here).
+    let manifest = env!("CARGO_MANIFEST_DIR");
+    let root = manifest
+        .strip_suffix("crates/horizon-client")
+        .unwrap_or(manifest);
+    let mut frames: Vec<(String, Option<String>)> = Vec::new();
+    for line in backtrace.lines() {
+        let line = line.trim();
+        if let Some(at) = line.strip_prefix("at ") {
+            if let Some(frame) = frames.last_mut() {
+                frame.1 = Some(short_path(at, root).to_owned());
+            }
+        } else if let Some((n, name)) = line.split_once(": ")
+            && n.chars().all(|c| c.is_ascii_digit())
+        {
+            frames.push((name.to_owned(), None));
+        }
+    }
+    let machinery = |name: &str| {
+        [
+            "std::panicking::",
+            "core::panicking::",
+            "std::sys::backtrace::",
+            "__rustc::",
+        ]
+        .iter()
+        .any(|p| name.starts_with(p))
+            || name.contains("rust_begin_unwind")
+    };
+    // The hook's frames, then the panic machinery's, then the code that panicked.
+    let top = frames.iter().take(30).position(|(name, _)| machinery(name));
+    let first = match top.filter(|_| from_panic) {
+        Some(start) => {
+            start
+                + frames[start..]
+                    .iter()
+                    .take_while(|(name, _)| machinery(name))
+                    .count()
+        }
+        None => 0,
+    };
+    // Some platforms keep std's own capture frames (`<std::backtrace::Backtrace>::create`).
+    let first = first
+        + frames[first..]
+            .iter()
+            .take_while(|(name, _)| name.trim_start_matches('<').starts_with("std::backtrace"))
+            .count();
+    frames[first..]
+        .iter()
+        .map(|(name, at)| match at {
+            Some(at) => format!("{name} ({at})\n"),
+            None => format!("{name}\n"),
+        })
+        .collect()
+}
+
+/// A source path without the build machine's folders: relative to the workspace, or from the
+/// crate's folder for dependencies (`winit-0.30.13/src/event_loop.rs:642:56`).
+fn short_path<'a>(path: &'a str, root: &str) -> &'a str {
+    if let Some(rest) = path.strip_prefix(root) {
+        return rest;
+    }
+    if let Some(i) = path.find("/registry/src/") {
+        let rest = &path[i + "/registry/src/".len()..];
+        if let Some((_index, krate)) = rest.split_once('/') {
+            return krate;
+        }
+    }
+    path
+}
+
+/// A report for a panic, with the stack captured now (RUST_BACKTRACE or not).
+pub fn panic_report(info: &std::panic::PanicHookInfo, side: &'static str) -> Report {
+    Report {
+        time: Local::now(),
+        description: "Unexpected error".into(),
+        error: panic_message(info),
+        stack: stack_lines(
+            &std::backtrace::Backtrace::force_capture().to_string(),
+            true,
+        ),
+        thread: thread_name(),
+        side,
+        details: system_details(),
+        log: crate::logging::recent_lines(),
+    }
+}
+
+/// Reports panics: on the main thread a crash report (the panic then ends the game, exit code
+/// 101); on other threads the error goes to the log, as vanilla's uncaught exception handler
+/// does. The default hook still prints the panic.
+pub fn install(home: PathBuf, side: &'static str) {
+    let default = std::panic::take_hook();
+    std::panic::set_hook(Box::new(move |info| {
+        default(info);
+        let main = std::thread::current().name() == Some("main");
+        if main {
+            deliver(&home, panic_report(info, side));
+        } else {
+            log::error!(
+                "Caught previously unhandled exception in thread {}: {}",
+                thread_name(),
+                panic_message(info)
+            );
+        }
+    }));
+}
+
+/// Vanilla's debug crash (`key.debug.crash` held for ten seconds): the error `main` gets back,
+/// with the stack where it was raised.
+#[derive(Debug)]
+pub struct DebugCrash {
+    stack: String,
+}
+
+impl DebugCrash {
+    pub const MESSAGE: &str = "Manually triggered debug crash";
+    #[allow(clippy::new_without_default)]
+    pub fn new() -> Self {
+        Self {
+            stack: stack_lines(
+                &std::backtrace::Backtrace::force_capture().to_string(),
+                false,
+            ),
+        }
+    }
+}
+
+impl std::fmt::Display for DebugCrash {
+    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+        f.write_str(Self::MESSAGE)
+    }
+}
+
+impl std::error::Error for DebugCrash {}
+
+/// A report for an error `main` got back: the game ends with it.
+pub fn report_error(
+    home: &Path,
+    side: &'static str,
+    error: &(dyn std::error::Error + 'static),
+) -> Option<PathBuf> {
+    if let Some(debug) = error.downcast_ref::<DebugCrash>() {
+        return deliver(
+            home,
+            Report {
+                time: Local::now(),
+                description: DebugCrash::MESSAGE.into(),
+                error: DebugCrash::MESSAGE.into(),
+                stack: debug.stack.clone(),
+                thread: thread_name(),
+                side,
+                details: system_details(),
+                log: crate::logging::recent_lines(),
+            },
+        );
+    }
+    let mut message = error.to_string();
+    let mut source = error.source();
+    while let Some(e) = source {
+        let _ = write!(message, "\nCaused by: {e}");
+        source = e.source();
+    }
+    deliver(
+        home,
+        Report {
+            time: Local::now(),
+            description: "Fatal error".into(),
+            error: message,
+            stack: String::new(),
+            thread: thread_name(),
+            side,
+            details: system_details(),
+            log: crate::logging::recent_lines(),
+        },
+    )
+}
+
+/// Called every frame: panics once `HORIZON_DEBUG_CRASH` asks (development builds only).
+pub fn debug_crash_tick() {
+    static AT: std::sync::OnceLock<Option<(std::time::Instant, std::time::Duration)>> =
+        std::sync::OnceLock::new();
+    if let Some((first, after)) =
+        AT.get_or_init(|| debug_crash_after().map(|d| (std::time::Instant::now(), d)))
+        && first.elapsed() >= *after
+    {
+        panic!("Manually triggered debug crash");
+    }
+}
+
+/// Development builds crash on purpose when `HORIZON_DEBUG_CRASH` is set (vanilla has F3+C held
+/// for ten seconds): the number is seconds after the first frame (default 5).
+pub fn debug_crash_after() -> Option<std::time::Duration> {
+    if !cfg!(debug_assertions) {
+        return None;
+    }
+    let value = std::env::var("HORIZON_DEBUG_CRASH").ok()?;
+    let seconds = value.parse::<f64>().unwrap_or(5.0).max(0.0);
+    Some(std::time::Duration::from_secs_f64(seconds))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn report() -> Report {
+        Report {
+            time: chrono::TimeZone::with_ymd_and_hms(&Local, 2026, 10, 14, 9, 5, 7).unwrap(),
+            description: "Unexpected error".into(),
+            error: "panicked at src/game.rs:10:5:\nboom".into(),
+            stack: "horizon_client::game::frame (src/game.rs:10:5)\n".into(),
+            thread: "Render thread".into(),
+            side: "client",
+            details: vec![
+                ("Horizon Version".into(), "0.1.0".into()),
+                ("Minecraft Version".into(), "26.3".into()),
+                ("Graphics".into(), "Test GPU (Vulkan), driver 1.0".into()),
+            ],
+            log: vec!["[09:05:06] [Render thread/INFO]: load assets: 1.20s".into()],
+        }
+    }
+
+    #[test]
+    fn file_names_are_vanillas() {
+        assert_eq!(
+            file_name(&report().time, "client"),
+            "crash-2026-10-14_09.05.07-client.txt"
+        );
+    }
+
+    #[test]
+    fn the_report_reads_like_vanillas() {
+        let text = report().text();
+        let lines: Vec<&str> = text.lines().collect();
+        assert_eq!(lines[0], "---- Horizon Crash Report ----");
+        assert!(lines[1].starts_with("// "));
+        assert_eq!(lines[3], "Time: 2026-10-14 09:05:07");
+        assert_eq!(lines[4], "Description: Unexpected error");
+        assert_eq!(lines[6], "panicked at src/game.rs:10:5:");
+        assert_eq!(lines[7], "boom");
+        assert_eq!(
+            lines[8],
+            "\tat horizon_client::game::frame (src/game.rs:10:5)"
+        );
+        assert!(text.contains("-- Head --\nThread: Render thread\n"));
+        assert!(text.contains(
+            "-- System Details --\nDetails:\n\tHorizon Version: 0.1.0\n\tMinecraft Version: 26.3\n\tGraphics: Test GPU (Vulkan), driver 1.0\n"
+        ));
+        assert!(text.ends_with(
+            "-- Last 1 log lines --\n[09:05:06] [Render thread/INFO]: load assets: 1.20s\n"
+        ));
+    }
+
+    #[test]
+    fn stacks_start_at_the_panicking_frame() {
+        let bt = format!(
+            "   0: horizon_client::crash::panic_report\n             at {root}/src/crash.rs:296:16\n   1: std::panicking::panic_with_hook\n             at /rustc/abc/library/std/src/panicking.rs:823:13\n   2: core::panicking::panic_fmt\n             at /rustc/abc/library/core/src/panicking.rs:80:14\n   3: horizon_client::crash::debug_crash_tick\n             at {root}/src/crash.rs:359:9\n   4: winit::dispatch\n             at /home/someone/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/winit-0.30.13/src/event_loop.rs:642:56\n   5: main\n",
+            root = env!("CARGO_MANIFEST_DIR")
+        );
+        assert_eq!(
+            stack_lines(&bt, true),
+            "horizon_client::crash::debug_crash_tick (crates/horizon-client/src/crash.rs:359:9)\nwinit::dispatch (winit-0.30.13/src/event_loop.rs:642:56)\nmain\n"
+        );
+    }
+
+    #[test]
+    fn the_debug_crash_is_reported_as_vanillas() {
+        let error: Box<dyn std::error::Error> = DebugCrash::new().into();
+        assert_eq!(error.to_string(), "Manually triggered debug crash");
+        let debug = error.downcast_ref::<DebugCrash>().unwrap();
+        // The stack starts where the crash was raised (DebugCrash::new, in this file).
+        let first = debug.stack.lines().next().unwrap();
+        assert!(first.contains("crash.rs"), "{}", debug.stack);
+    }
+
+    #[test]
+    fn a_panic_becomes_a_report() {
+        // A real panic through a hook, as the game's would be.
+        let caught = std::sync::Arc::new(Mutex::new(None));
+        let sink = caught.clone();
+        let previous = std::panic::take_hook();
+        std::panic::set_hook(Box::new(move |info| {
+            if panic_message(info).contains("the test crash") {
+                *sink.lock().unwrap() = Some(panic_report(info, "client"));
+            }
+        }));
+        let _ = std::panic::catch_unwind(|| panic!("the test crash"));
+        std::panic::set_hook(previous);
+        let report = caught.lock().unwrap().take().expect("the hook ran");
+        assert!(report.error.contains("the test crash"));
+        assert!(report.error.contains("crash.rs"));
+        // The first frame is the test's own code, not the panic machinery.
+        let first = report.stack.lines().next().unwrap();
+        assert!(first.contains("crash.rs"), "{}", report.stack);
+        let text = report.text();
+        assert!(text.contains("Description: Unexpected error"));
+        assert!(text.contains("\tMinecraft Version: 26.3\n"));
+        assert!(text.contains("\tOperating System: "));
+        assert!(text.contains("\tCPU: "));
+        let home = std::env::temp_dir().join(format!("horizon-crash-save-{}", std::process::id()));
+        let path = report.save(&home).unwrap();
+        assert_eq!(std::fs::read_to_string(&path).unwrap(), text);
+        assert!(
+            path.file_name()
+                .unwrap()
+                .to_str()
+                .unwrap()
+                .ends_with("-client.txt")
+        );
+        let _ = std::fs::remove_dir_all(&home);
+    }
+}
@@ -1,7 +1,7 @@
 //! Creative inventory (CreativeModeInventoryScreen): vanilla's tabs and their
 //! contents as built by the game's own display generators
-//! (`creative-tabs.json`), a 9x5 scrolling grid and the search tab.
-use crate::Result;
+//! (`creative-inventory.json`), a 9x5 scrolling grid and the search tab.
+use crate::{Result, items::ItemStack};
 use serde_json::Value;
 use std::{collections::HashMap, fs, path::Path};

@@ -10,19 +10,35 @@ pub struct Tab {
    pub id: String,
    pub title: String,
    pub icon: String,
-    pub items: Vec<String>,
+    pub items: Vec<ItemStack>,
    pub top: bool,
    pub column: u32,
    pub search: bool,
    pub inventory: bool,
 }
+/// What the client's creative search trees (SessionSearchTrees) index for one
+/// stack of the search tab: its creative tooltip lines and its item tags.
+#[derive(Clone, Debug, Default)]
+struct SearchEntry {
+    /// The item id's namespace and path, lower-cased.
+    namespace: String,
+    path: String,
+    /// Tooltip lines, lower-cased; empty when the resources predate them.
+    lines: Vec<String>,
+    /// Item tags as (namespace, path), lower-cased.
+    tags: Vec<(String, String)>,
+}
 pub struct Creative {
    pub tabs: Vec<Tab>,
    pub selected: usize,
-    /// Scroll position 0..1.
+    /// Scroll position 0..1 (scrollOffs).
    pub scroll: f32,
+    /// The scrollbar is held (scrolling): dragging moves it.
+    pub scrolling: bool,
    pub search: String,
-    all_items: Vec<String>,
+    /// The search tab's stacks, in its display order.
+    search_items: Vec<ItemStack>,
+    search_index: Vec<SearchEntry>,
 }
 /// Display names from the pinned en_us language file.
 pub struct Names {
@@ -51,26 +67,120 @@ impl Names {
 impl Creative {
    pub const WIDTH: f32 = 195.0;
    pub const HEIGHT: f32 = 136.0;
+    pub const TRASH_POSITION: (f32, f32) = (173.0, 112.0);
+
+    /// Visible player slots in the creative inventory tab (game slot ids).
+    pub fn inventory_slots() -> impl Iterator<Item = usize> {
+        (0..36).chain(500..505)
+    }
+
+    /// CreativeModeInventoryScreen.selectTab positions its InventoryMenu wrappers.
+    pub fn inventory_slot_position(slot: usize) -> Option<(f32, f32)> {
+        match slot {
+            0..9 => Some((9.0 + slot as f32 * 18.0, 112.0)),
+            9..36 => Some((
+                9.0 + ((slot - 9) % 9) as f32 * 18.0,
+                54.0 + ((slot - 9) / 9) as f32 * 18.0,
+            )),
+            500..504 => {
+                let position = slot - 500;
+                Some((
+                    54.0 + (position / 2) as f32 * 54.0,
+                    6.0 + (position % 2) as f32 * 27.0,
+                ))
+            }
+            504 => Some((35.0, 20.0)),
+            _ => None,
+        }
+    }
+    /// The scrollbar track (insideScrollbar), relative to the screen origin.
+    pub const SCROLL_X: f32 = 175.0;
+    pub const SCROLL_Y: f32 = 18.0;
+    pub const SCROLL_WIDTH: f32 = 14.0;
+    pub const SCROLL_HEIGHT: f32 = 112.0;
+    /// `creative-inventory.json` (VanillaCreativeTabsExporter); resources
+    /// prepared before it fall back to `creative-tabs.json`'s item ids.
    pub fn load(root: &Path) -> Result<Self> {
-        let raw: Value = serde_json::from_slice(&fs::read(root.join("creative-tabs.json"))?)?;
+        let path = root.join("creative-inventory.json");
+        if path.exists() {
+            Self::from_json(&serde_json::from_slice(&fs::read(path)?)?)
+        } else {
+            Self::from_legacy(&serde_json::from_slice(&fs::read(
+                root.join("creative-tabs.json"),
+            )?)?)
+        }
+    }
+    pub fn from_json(raw: &Value) -> Result<Self> {
        let mut tabs = Vec::new();
-        let mut all_items: Vec<String> = Vec::new();
-        for t in raw.as_array().into_iter().flatten() {
-            let items: Vec<String> = t["items"]
-                .as_array()
-                .into_iter()
-                .flatten()
-                .filter_map(|v| v.as_str().map(str::to_owned))
-                .collect();
-            for i in &items {
-                if !all_items.contains(i) {
-                    all_items.push(i.clone());
+        let mut search_items = Vec::new();
+        let mut search_index = Vec::new();
+        for t in raw["tabs"].as_array().into_iter().flatten() {
+            let mut items = Vec::new();
+            for v in t["items"].as_array().into_iter().flatten() {
+                let snbt = v.as_str().unwrap_or("-");
+                if let Some(stack) = crate::item_data::parse_stack(snbt)? {
+                    items.push(stack);
                }
            }
            let kind = t["type"].as_str().unwrap_or("");
+            if kind == "SEARCH" {
+                let strings = |v: &Value| -> Vec<String> {
+                    v.as_array()
+                        .into_iter()
+                        .flatten()
+                        .filter_map(|s| s.as_str().map(java_lower))
+                        .collect()
+                };
+                for (i, stack) in items.iter().enumerate() {
+                    let (namespace, path) = split_id(&java_lower(&stack.item));
+                    search_index.push(SearchEntry {
+                        namespace,
+                        path,
+                        lines: strings(&t["lines"][i]),
+                        tags: strings(&t["tags"][i]).iter().map(|t| split_id(t)).collect(),
+                    });
+                }
+                search_items = items.clone();
+            }
+            if kind == "HOTBAR" || t["visible"] == false {
+                continue;
+            }
+            let icon = t["icon"]
+                .as_str()
+                .and_then(|s| crate::item_data::parse_stack(s).ok().flatten());
+            tabs.push(Tab {
+                id: t["id"].as_str().unwrap_or("").to_owned(),
+                title: t["title"].as_str().unwrap_or("").to_owned(),
+                icon: icon.map_or_else(|| "minecraft:stone".to_owned(), |s| s.item.to_string()),
+                items,
+                top: t["row"] == "TOP",
+                column: t["column"].as_u64().unwrap_or(0) as u32,
+                search: kind == "SEARCH",
+                inventory: kind == "INVENTORY",
+            });
+        }
+        Ok(Self::new(tabs, search_items, search_index))
+    }
+    /// The old export: item ids per tab, no components, tooltips or tags.
+    fn from_legacy(raw: &Value) -> Result<Self> {
+        let mut tabs = Vec::new();
+        let mut search_items: Vec<ItemStack> = Vec::new();
+        for t in raw.as_array().into_iter().flatten() {
+            let items: Vec<ItemStack> = t["items"]
+                .as_array()
+                .into_iter()
+                .flatten()
+                .filter_map(|v| v.as_str().map(|id| ItemStack::new(id, 1)))
+                .collect();
            if t["id"] == "minecraft:hotbar" || t["id"] == "minecraft:op_blocks" {
                continue;
            }
+            for i in &items {
+                if !search_items.iter().any(|s| s.item == i.item) {
+                    search_items.push(i.clone());
+                }
+            }
+            let kind = t["type"].as_str().unwrap_or("");
            tabs.push(Tab {
                id: t["id"].as_str().unwrap_or("").to_owned(),
                title: t["title"].as_str().unwrap_or("").to_owned(),
@@ -82,31 +192,101 @@ impl Creative {
                inventory: kind == "INVENTORY",
            });
        }
-        Ok(Self {
+        let search_index = search_items
+            .iter()
+            .map(|s| {
+                let (namespace, path) = split_id(&java_lower(&s.item));
+                SearchEntry {
+                    namespace,
+                    path,
+                    ..Default::default()
+                }
+            })
+            .collect();
+        Ok(Self::new(tabs, search_items, search_index))
+    }
+    fn new(tabs: Vec<Tab>, search_items: Vec<ItemStack>, search_index: Vec<SearchEntry>) -> Self {
+        Self {
            tabs,
            selected: 0,
            scroll: 0.0,
+            scrolling: false,
            search: String::new(),
-            all_items,
-        })
+            search_items,
+            search_index,
+        }
    }
    pub fn tab(&self) -> &Tab {
        &self.tabs[self.selected.min(self.tabs.len() - 1)]
    }
-    /// Items shown by the selected tab (the search tab filters by name).
-    pub fn items(&self, names: &Names) -> Vec<String> {
+    /// selectTab: a different tab empties the search box; the scrollbar goes to the top.
+    pub fn select(&mut self, tab: usize) {
+        if tab != self.selected {
+            self.search.clear();
+        }
+        self.selected = tab;
+        self.scroll = 0.0;
+    }
+    /// The search tab's stacks.
+    pub fn search_items(&self) -> &[ItemStack] {
+        &self.search_items
+    }
+    /// Indices into `search_items` that CreativeModeInventoryScreen.refreshSearchResults
+    /// shows for `term`: the whole tab when empty, the tag tree after `#`, else
+    /// the name tree, both over vanilla's suffix arrays (substring matches,
+    /// results in the tab's order).
+    pub fn search_results(&self, term: &str, names: &Names) -> Vec<usize> {
+        let all = 0..self.search_index.len();
+        if term.is_empty() {
+            return all.collect();
+        }
+        if let Some(tag) = term.strip_prefix('#') {
+            // IdSearchTree over the stacks' tags.
+            let text = java_lower(tag);
+            return all
+                .filter(|&i| {
+                    let tags = &self.search_index[i].tags;
+                    match text.split_once(':') {
+                        None => any(tags.iter().map(|t| t.1.as_str()), &text),
+                        Some((ns, path)) => {
+                            let (ns, path) = (java_trim(ns), java_trim(path));
+                            any(tags.iter().map(|t| t.0.as_str()), ns)
+                                && any(tags.iter().map(|t| t.1.as_str()), path)
+                        }
+                    }
+                })
+                .collect();
+        }
+        // FullTextSearchTree: tooltip lines, and the item id after a colon.
+        let text = java_lower(term);
+        all.filter(|&i| {
+            let e = &self.search_index[i];
+            let fallback;
+            let lines: &[String] = if e.lines.is_empty() {
+                fallback = [java_lower(&names.item(&self.search_items[i].item))];
+                &fallback
+            } else {
+                &e.lines
+            };
+            match text.split_once(':') {
+                None => any(lines.iter().map(String::as_str), &text),
+                Some((ns, path)) => {
+                    let (ns, path) = (java_trim(ns), java_trim(path));
+                    e.namespace.contains(ns)
+                        && (e.path.contains(path) || any(lines.iter().map(String::as_str), path))
+                }
+            }
+        })
+        .collect()
+    }
+    /// Items shown by the selected tab (the search tab filters by `search`).
+    pub fn items(&self, names: &Names) -> Vec<ItemStack> {
        let tab = self.tab();
        if tab.search {
-            let query = self.search.to_lowercase();
            return self
-                .all_items
-                .iter()
-                .filter(|i| {
-                    query.is_empty()
-                        || names.item(i).to_lowercase().contains(&query)
-                        || i.contains(&query)
-                })
-                .cloned()
+                .search_results(&self.search, names)
+                .into_iter()
+                .map(|i| self.search_items[i].clone())
                .collect();
        }
        tab.items.clone()
@@ -114,10 +294,60 @@ impl Creative {
    pub fn rows(&self, names: &Names) -> usize {
        self.items(names).len().div_ceil(9)
    }
-    /// First visible grid row for the scroll position.
+    /// ItemPickerMenu.calculateRowCount: rows beyond the five shown.
+    fn hidden_rows(&self, names: &Names) -> i32 {
+        self.rows(names) as i32 - 5
+    }
+    /// First visible grid row for the scroll position (getRowIndexForScroll).
    pub fn first_row(&self, names: &Names) -> usize {
-        let hidden = self.rows(names).saturating_sub(5);
-        (self.scroll * hidden as f32 + 0.5) as usize
+        ((self.scroll * self.hidden_rows(names) as f32 + 0.5) as i32).max(0) as usize
+    }
+    /// CreativeModeInventoryScreen.canScroll: more than five rows, on a tab with a scrollbar.
+    pub fn can_scroll(&self, names: &Names) -> bool {
+        !self.tab().inventory && self.items(names).len() > 45
+    }
+    /// insideScrollbar, for a point relative to the screen origin.
+    pub fn inside_scrollbar(&self, x: f32, y: f32) -> bool {
+        x >= Self::SCROLL_X
+            && y >= Self::SCROLL_Y
+            && x < Self::SCROLL_X + Self::SCROLL_WIDTH
+            && y < Self::SCROLL_Y + Self::SCROLL_HEIGHT
+            && !self.tab().inventory
+    }
+    /// mouseClicked on the scrollbar: it is held only if the tab can scroll
+    /// (the thumb doesn't move until the mouse does).
+    pub fn press_scrollbar(&mut self, x: f32, y: f32, names: &Names) -> bool {
+        if !self.inside_scrollbar(x, y) {
+            return false;
+        }
+        self.scrolling = self.can_scroll(names);
+        true
+    }
+    /// mouseDragged while the scrollbar is held, at a cursor height relative to
+    /// the screen origin, wherever the cursor is (even off the track or the window).
+    pub fn drag_scrollbar(&mut self, y: f32) -> bool {
+        if !self.scrolling {
+            return false;
+        }
+        let (top, bottom) = (Self::SCROLL_Y, Self::SCROLL_Y + Self::SCROLL_HEIGHT);
+        self.scroll = ((y - top - 7.5) / (bottom - top - 15.0)).clamp(0.0, 1.0);
+        true
+    }
+    /// mouseReleased.
+    pub fn release(&mut self) {
+        self.scrolling = false;
+    }
+    /// mouseScrolled: ItemPickerMenu.subtractInputFromScroll.
+    pub fn wheel(&mut self, amount: f64, names: &Names) {
+        if !self.can_scroll(names) {
+            return;
+        }
+        let rows = self.hidden_rows(names) as f64;
+        self.scroll = (self.scroll - (amount / rows) as f32).clamp(0.0, 1.0);
+    }
+    /// The scroller sprite's offset from the top of the track.
+    pub fn scroller_offset(&self) -> f32 {
+        ((Self::SCROLL_HEIGHT - 17.0) * self.scroll) as i32 as f32
    }
    /// Tab button position relative to the screen origin (CreativeModeInventoryScreen.getTabX/Y).
    pub fn tab_position(tab: &Tab) -> (f32, f32) {
@@ -130,3 +360,209 @@ impl Creative {
        (x, y)
    }
 }
+/// Whether a suffix array of `strings` has a suffix starting with `text`:
+/// some string contains it (none for no strings, even when `text` is empty).
+fn any<'a>(strings: impl IntoIterator<Item = &'a str>, text: &str) -> bool {
+    strings.into_iter().any(|s| s.contains(text))
+}
+/// String.toLowerCase(Locale.ROOT).
+fn java_lower(s: &str) -> String {
+    s.to_lowercase()
+}
+/// String.trim: strips code points up to U+0020.
+fn java_trim(s: &str) -> &str {
+    s.trim_matches(|c: char| c <= ' ')
+}
+/// Identifier.parse's namespace and path (default namespace `minecraft`).
+fn split_id(id: &str) -> (String, String) {
+    match id.split_once(':') {
+        Some((ns, path)) => (ns.to_owned(), path.to_owned()),
+        None => ("minecraft".to_owned(), id.to_owned()),
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn creative(items: usize) -> Creative {
+        let mut stacks: Vec<String> = ["anvil", "crafting_table", "wooden_hoe"]
+            .iter()
+            .map(|i| format!("{{count:1,id:\"minecraft:{i}\"}}"))
+            .collect();
+        stacks.extend((0..items).map(|i| format!("{{count:1,id:\"minecraft:item_{i}\"}}")));
+        let mut lines = vec![
+            vec!["Anvil"],
+            vec!["Crafting Table"],
+            vec!["Wooden Hoe", "When in Main Hand:", "-3 Attack Speed"],
+        ];
+        lines.extend(vec![vec!["Thing"]; items]);
+        let mut tags = vec![
+            vec!["minecraft:anvil"],
+            vec![],
+            vec!["minecraft:hoes", "minecraft:enchantable/mining"],
+        ];
+        tags.extend(vec![vec![]; items]);
+        let raw = serde_json::json!({"schema": 2, "tabs": [
+            {"id": "minecraft:functional_blocks", "type": "CATEGORY", "row": "TOP", "column": 3, "title": "Functional Blocks",
+             "icon": "{count:1,id:\"minecraft:oak_sign\"}", "visible": true,
+             "items": ["{count:1,id:\"minecraft:anvil\"}", "{count:1,id:\"minecraft:crafting_table\"}"]},
+            {"id": "minecraft:op_blocks", "type": "CATEGORY", "row": "BOTTOM", "column": 5, "title": "Operator Utilities",
+             "icon": "{count:1,id:\"minecraft:command_block\"}", "visible": false, "items": []},
+            {"id": "minecraft:search", "type": "SEARCH", "row": "TOP", "column": 6, "title": "Search Items",
+             "icon": "{count:1,id:\"minecraft:compass\"}", "visible": true,
+             "items": stacks, "lines": lines, "tags": tags},
+            {"id": "minecraft:inventory", "type": "INVENTORY", "row": "BOTTOM", "column": 6, "title": "Survival Inventory",
+             "icon": "{count:1,id:\"minecraft:chest\"}", "visible": true, "items": []}
+        ]});
+        Creative::from_json(&raw).unwrap()
+    }
+
+    #[test]
+    fn inventory_tab_slot_layout_matches_vanilla() {
+        assert_eq!(Creative::inventory_slots().count(), 41);
+        for (slot, expected) in [
+            (0, (9.0, 112.0)),
+            (8, (153.0, 112.0)),
+            (9, (9.0, 54.0)),
+            (35, (153.0, 90.0)),
+            (500, (54.0, 6.0)),
+            (501, (54.0, 33.0)),
+            (502, (108.0, 6.0)),
+            (503, (108.0, 33.0)),
+            (504, (35.0, 20.0)),
+        ] {
+            assert_eq!(Creative::inventory_slot_position(slot), Some(expected));
+        }
+        assert_eq!(Creative::inventory_slot_position(100), None);
+        assert_eq!(Creative::TRASH_POSITION, (173.0, 112.0));
+        let mut c = creative(90);
+        c.select(2);
+        assert!(c.tab().inventory);
+        assert!(!c.can_scroll(&Names {
+            map: HashMap::new()
+        }));
+    }
+
+    #[test]
+    fn inventory_tab_can_return_to_category_and_search() {
+        let mut c = creative(90);
+        for (selected, inventory, search) in [
+            (2, true, false),
+            (0, false, false),
+            (1, false, true),
+            (2, true, false),
+        ] {
+            c.search = "anvil".into();
+            c.scroll = 0.5;
+            c.select(selected);
+            assert_eq!(c.selected, selected);
+            assert_eq!(c.tab().inventory, inventory);
+            assert_eq!(c.tab().search, search);
+            assert!(c.search.is_empty());
+            assert_eq!(c.scroll, 0.0);
+        }
+    }
+
+    #[test]
+    fn hidden_tabs_are_skipped() {
+        let c = creative(0);
+        let ids: Vec<&str> = c.tabs.iter().map(|t| t.id.as_str()).collect();
+        assert_eq!(
+            ids,
+            [
+                "minecraft:functional_blocks",
+                "minecraft:search",
+                "minecraft:inventory"
+            ]
+        );
+        assert_eq!(c.tabs[0].items[0].item.as_ref(), "minecraft:anvil");
+        let mut c = c;
+        c.select(1);
+        c.search = "anvil".into();
+        c.scroll = 0.5;
+        c.select(1);
+        assert_eq!((c.search.as_str(), c.scroll), ("anvil", 0.0));
+        c.select(0);
+        assert_eq!(c.search, "");
+    }
+
+    #[test]
+    fn search_matches_vanilla_trees() {
+        let c = creative(0);
+        let names = Names {
+            map: HashMap::new(),
+        };
+        let q = |s: &str| c.search_results(s, &names);
+        assert_eq!(q(""), [0, 1, 2]);
+        assert_eq!(q("ANVIL"), [0]);
+        assert_eq!(q("table"), [1]);
+        assert_eq!(q("a"), [0, 1, 2]);
+        // Tooltip lines, not just names; no trimming without a colon.
+        assert_eq!(q("attack speed"), [2]);
+        assert_eq!(q(" anvil"), Vec::<usize>::new());
+        // A colon searches the id: namespace, then the path or a tooltip line.
+        assert_eq!(q("minecraft:crafting_t"), [1]);
+        assert_eq!(q(" minecraft : hoe "), [2]);
+        assert_eq!(q("mine:anvil"), [0]);
+        assert_eq!(q("other:anvil"), Vec::<usize>::new());
+        assert_eq!(q(":"), [0, 1, 2]);
+        // Tags after "#": only stacks with tags.
+        assert_eq!(q("#"), [0, 2]);
+        assert_eq!(q("#hoe"), [2]);
+        assert_eq!(q("#minecraft:enchantable/"), [2]);
+        assert_eq!(q("#craft"), Vec::<usize>::new());
+    }
+
+    #[test]
+    fn scrollbar_drag_follows_the_mouse_while_held() {
+        let mut c = creative(90);
+        let names = Names {
+            map: HashMap::new(),
+        };
+        c.selected = 1;
+        // Pressing the track holds the scrollbar without moving it.
+        assert!(c.press_scrollbar(180.0, 60.0, &names));
+        assert!(c.scrolling);
+        assert_eq!(c.scroll, 0.0);
+        // Dragging maps the cursor height onto the track (minus half the thumb).
+        assert!(c.drag_scrollbar(18.0 + 7.5 + 48.5));
+        assert!((c.scroll - 0.5).abs() < 1e-6);
+        // The cursor may leave the track, the panel or the window: it keeps scrolling.
+        c.drag_scrollbar(400.0);
+        assert_eq!(c.scroll, 1.0);
+        c.drag_scrollbar(-50.0);
+        assert_eq!(c.scroll, 0.0);
+        c.drag_scrollbar(18.0 + 7.5 + 97.0 * 0.25);
+        assert!((c.scroll - 0.25).abs() < 1e-6);
+        let rows = (93usize.div_ceil(9) - 5) as f32;
+        assert_eq!(c.first_row(&names), (0.25 * rows + 0.5) as usize);
+        // Releasing stops it.
+        c.release();
+        assert!(!c.drag_scrollbar(400.0));
+        assert!((c.scroll - 0.25).abs() < 1e-6);
+        // Off the track, or with too few items, it isn't held.
+        assert!(!c.press_scrollbar(170.0, 60.0, &names));
+        assert!(!c.press_scrollbar(180.0, 130.0, &names));
+        c.selected = 0;
+        assert!(c.press_scrollbar(180.0, 60.0, &names));
+        assert!(!c.scrolling);
+    }
+
+    #[test]
+    fn wheel_moves_one_row_per_notch() {
+        let mut c = creative(90);
+        let names = Names {
+            map: HashMap::new(),
+        };
+        c.selected = 1;
+        let rows = (93usize.div_ceil(9) - 5) as f32;
+        c.wheel(-1.0, &names);
+        assert!((c.scroll - 1.0 / rows).abs() < 1e-6);
+        assert_eq!(c.first_row(&names), 1);
+        c.wheel(5.0, &names);
+        assert_eq!(c.scroll, 0.0);
+        assert_eq!(c.scroller_offset(), 0.0);
+        c.scroll = 1.0;
+        assert_eq!(c.scroller_offset(), 95.0);
+    }
+}
@@ -0,0 +1,579 @@
+//! The debug charts (26.3 `debugchart`): F3+2 shows the frame times and, in
+//! single player, the integrated server's tick times; F3+3 the ping and, on a
+//! remote server, the bandwidth. Each chart keeps the last 240 samples
+//! (`LocalSampleLogger`) and draws one bar per sample over a 60 pixel high
+//! box (`AbstractDebugChart`).
+use crate::{
+    font::Font,
+    hud_layout::{GuiDraw, argb, fill},
+    text::Text,
+};
+use std::{
+    collections::VecDeque,
+    time::{Duration, Instant},
+};
+
+/// `LocalSampleLogger.CAPACITY`.
+pub const CAPACITY: usize = 240;
+/// `AbstractDebugChart.CHART_HEIGHT`.
+pub const CHART_HEIGHT: i32 = 60;
+/// `TpsDebugDimensions`: a tick sample's values.
+pub const FULL_TICK: usize = 0;
+pub const TICK_SERVER_METHOD: usize = 1;
+pub const SCHEDULED_TASKS: usize = 2;
+pub const IDLE: usize = 3;
+
+/// `LocalSampleLogger`: the last [`CAPACITY`] samples, oldest first; a
+/// sample has up to four values (`TpsDebugDimensions`), the first the main.
+#[derive(Clone, Debug, Default)]
+pub struct SampleLogger {
+    samples: VecDeque<[i64; 4]>,
+}
+impl SampleLogger {
+    /// `logSample`.
+    pub fn log(&mut self, value: i64) {
+        self.log_full([value, 0, 0, 0]);
+    }
+    /// `logFullSample`.
+    pub fn log_full(&mut self, sample: [i64; 4]) {
+        if self.samples.len() == CAPACITY {
+            self.samples.pop_front();
+        }
+        self.samples.push_back(sample);
+    }
+    pub fn len(&self) -> usize {
+        self.samples.len()
+    }
+    pub fn is_empty(&self) -> bool {
+        self.samples.is_empty()
+    }
+    pub fn reset(&mut self) {
+        self.samples.clear();
+    }
+    fn get(&self, index: usize, dimension: usize) -> i64 {
+        self.samples[index][dimension]
+    }
+}
+
+/// `DebugScreenOverlay`'s chart switches and the samples behind them.
+#[derive(Clone, Debug, Default)]
+pub struct DebugCharts {
+    /// `renderFpsCharts` (F3+2).
+    pub fps: bool,
+    /// `renderNetworkCharts` (F3+3).
+    pub network: bool,
+    /// `renderLightmapTexture` (F3+4).
+    pub lightmap: bool,
+    /// `frameTimeLogger`: nanoseconds between frames.
+    pub frame_times: SampleLogger,
+    /// `tickTimeLogger`: the integrated server's ticks.
+    pub tick_times: SampleLogger,
+    /// `pingLogger`: milliseconds.
+    pub ping: SampleLogger,
+    /// `bandwidthLogger`: bytes received per tick.
+    pub bandwidth: SampleLogger,
+    previous_tick: Option<Instant>,
+    bytes_seen: Option<i64>,
+}
+impl DebugCharts {
+    /// `toggleFpsCharts`; `overlay` is the debug overlay's visibility.
+    pub fn toggle_fps(&mut self, overlay: &mut bool) {
+        self.fps = !*overlay || !self.fps;
+        if self.fps {
+            *overlay = true;
+            self.network = false;
+            self.lightmap = false;
+        }
+    }
+    /// `toggleNetworkCharts`.
+    pub fn toggle_network(&mut self, overlay: &mut bool) {
+        self.network = !*overlay || !self.network;
+        if self.network {
+            *overlay = true;
+            self.fps = false;
+            self.lightmap = false;
+        }
+    }
+    /// `toggleLightmapTexture`.
+    pub fn toggle_lightmap(&mut self, overlay: &mut bool) {
+        self.lightmap = !*overlay || !self.lightmap;
+        if self.lightmap {
+            *overlay = true;
+            self.fps = false;
+            self.network = false;
+        }
+    }
+    /// `reset`: leaving a world.
+    pub fn reset(&mut self) {
+        self.tick_times.reset();
+        self.ping.reset();
+        self.bandwidth.reset();
+        self.previous_tick = None;
+        self.bytes_seen = None;
+    }
+    /// One integrated server tick that started at `started` and ran its
+    /// tick method for `method` (`MinecraftServer.logFullTickTime` and
+    /// `logTickMethodTime`): the full tick runs from one start to the next,
+    /// and what the tick method leaves of it is idle.
+    pub fn log_tick(&mut self, started: Instant, method: Duration) {
+        let method = method.as_nanos() as i64;
+        let full = self
+            .previous_tick
+            .map_or(method, |p| (started - p).as_nanos() as i64)
+            .max(method);
+        self.previous_tick = Some(started);
+        self.tick_times.log_full([full, method, 0, full - method]);
+    }
+    /// `BandwidthDebugMonitor.tick`: the bytes received since the last
+    /// tick, from the connection's running total.
+    pub fn log_bandwidth(&mut self, total: i64) {
+        if let Some(seen) = self.bytes_seen {
+            self.bandwidth.log(total - seen);
+        }
+        self.bytes_seen = Some(total);
+    }
+    /// The charts along the bottom of the screen (`extractRenderState`):
+    /// frame times left and tick times right, or bandwidth left (remote
+    /// servers only) and ping right. `mspt` is the level's milliseconds
+    /// per tick.
+    pub fn draw(
+        &self,
+        font: &Font,
+        width: i32,
+        height: i32,
+        framerate_limit: u32,
+        mspt: f32,
+        remote: bool,
+    ) -> Vec<GuiDraw> {
+        let mut out = Vec::new();
+        let max_width = width / 2;
+        let chart_width = Chart::width(max_width);
+        if self.fps {
+            let fps = Chart::Fps { framerate_limit };
+            out.extend(fps.draw(font, &self.frame_times, 0, chart_width, height));
+            if !self.tick_times.is_empty() {
+                let tps = Chart::Tps { mspt };
+                out.extend(tps.draw(
+                    font,
+                    &self.tick_times,
+                    width - chart_width,
+                    chart_width,
+                    height,
+                ));
+            }
+        }
+        if self.network {
+            if remote {
+                out.extend(Chart::Bandwidth.draw(font, &self.bandwidth, 0, chart_width, height));
+            }
+            out.extend(Chart::Ping.draw(
+                font,
+                &self.ping,
+                width - chart_width,
+                chart_width,
+                height,
+            ));
+        }
+        out
+    }
+}
+
+/// The lightmap view (`showLightmapTexture`): the 16 by 16 texture at 64
+/// by 64 in the bottom right corner on a black border, sky light up and
+/// block light right (the blit flips the texture's rows). `pixels` are RGBA
+/// rows of sky level by block level.
+pub fn lightmap(pixels: &[u8; 16 * 16 * 4], width: i32, height: i32) -> Vec<GuiDraw> {
+    let (x, y) = (width - 64 - 2, height - 64 - 2);
+    let mut out = vec![fill(x - 1, y - 1, x + 64 + 1, y + 64 + 1, 0xFF00_0000)];
+    for (i, p) in pixels.as_chunks::<4>().0.iter().enumerate() {
+        let (sky, block) = ((i / 16) as i32, (i % 16) as i32);
+        let color = argb(255, u32::from(p[0]), u32::from(p[1]), u32::from(p[2]));
+        let (cx, cy) = (x + block * 4, y + (15 - sky) * 4);
+        out.push(fill(cx, cy, cx + 4, cy + 4, color));
+    }
+    out
+}
+
+/// The four charts and what each needs to scale its bars.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Chart {
+    /// `FpsDebugChart`: frame durations in nanoseconds; the frame rate limit
+    /// option (`maxFps`).
+    Fps { framerate_limit: u32 },
+    /// `TpsDebugChart`: tick samples in nanoseconds; the level's
+    /// milliseconds per tick.
+    Tps { mspt: f32 },
+    /// `PingDebugChart`: round trips in milliseconds.
+    Ping,
+    /// `BandwidthDebugChart`: bytes received per tick.
+    Bandwidth,
+}
+
+/// The labels' colour and the backdrop of the box and shaded labels.
+const LABEL: u32 = 0xFFE0_E0E0;
+const BACKDROP: u32 = 0x9050_5050;
+const WHITE: u32 = 0xFFFF_FFFF;
+const GREEN: u32 = 0xFF00_FF00;
+const YELLOW: u32 = 0xFFFF_FF00;
+const RED: u32 = 0xFFFF_0000;
+const CYAN: u32 = 0xFF00_FFFF;
+/// `BandwidthDebugChart.MID_COLOR`.
+const LAVENDER: u32 = 0xFFA0_A0FF;
+/// `TpsDebugChart`'s bar parts.
+const TICK_METHOD_COLOR: u32 = 0xFF99_1111;
+const TASK_COLOR: u32 = 0xFFBA_995F;
+const OTHER_COLOR: u32 = 0xFF5F_0E8C;
+const MEGABYTE: f64 = 1_048_576.0;
+
+impl Chart {
+    /// `AbstractDebugChart.getWidth`.
+    pub fn width(max_width: i32) -> i32 {
+        (CAPACITY as i32 + 2).min(max_width)
+    }
+    /// `getFullHeight`: the box and the min/avg/max line above it.
+    pub fn full_height() -> i32 {
+        CHART_HEIGHT + 9
+    }
+    /// `AbstractDebugChart.extractRenderState`.
+    pub fn draw(
+        self,
+        font: &Font,
+        samples: &SampleLogger,
+        left: i32,
+        width: i32,
+        bottom: i32,
+    ) -> Vec<GuiDraw> {
+        let mut out = vec![fill(
+            left,
+            bottom - CHART_HEIGHT,
+            left + width,
+            bottom,
+            BACKDROP,
+        )];
+        let (mut sum, mut min, mut max) = (0i64, i64::from(i32::MAX), i64::from(i32::MIN));
+        let start = CAPACITY.saturating_sub((width - 2).max(0) as usize);
+        let count = samples.len().saturating_sub(start);
+        for i in 0..count {
+            let x = left + i as i32 + 1;
+            let index = start + i;
+            let value = self.aggregated(samples, index);
+            min = min.min(value);
+            max = max.max(value);
+            sum += value;
+            self.bars(&mut out, samples, bottom, x, index);
+        }
+        horizontal_line(
+            &mut out,
+            left,
+            left + width - 1,
+            bottom - CHART_HEIGHT,
+            WHITE,
+        );
+        horizontal_line(&mut out, left, left + width - 1, bottom - 1, WHITE);
+        vertical_line(&mut out, left, bottom - CHART_HEIGHT, bottom, WHITE);
+        vertical_line(
+            &mut out,
+            left + width - 1,
+            bottom - CHART_HEIGHT,
+            bottom,
+            WHITE,
+        );
+        if count > 0 {
+            let y = bottom - CHART_HEIGHT - 9;
+            let min_text = format!("{} min", self.display(min as f64));
+            let avg_text = format!("{} avg", self.display(sum as f64 / count as f64));
+            let max_text = format!("{} max", self.display(max as f64));
+            text(&mut out, min_text, left + 2, y, LABEL, true);
+            let avg_x = left + width / 2 - font.width(&avg_text) as i32 / 2;
+            text(&mut out, avg_text, avg_x, y, LABEL, true);
+            let max_x = left + width - font.width(&max_text) as i32 - 2;
+            text(&mut out, max_text, max_x, y, LABEL, true);
+        }
+        self.lines_and_labels(&mut out, font, left, width, bottom);
+        out
+    }
+    fn bars(
+        self,
+        out: &mut Vec<GuiDraw>,
+        samples: &SampleLogger,
+        bottom: i32,
+        x: i32,
+        index: usize,
+    ) {
+        let value = samples.get(index, 0);
+        let height = self.height(value as f64);
+        out.push(fill(x, bottom - height, x + 1, bottom, self.color(value)));
+        if let Chart::Tps { .. } = self {
+            let method = samples.get(index, TICK_SERVER_METHOD);
+            let method_h = self.height(method as f64);
+            out.push(fill(x, bottom - method_h, x + 1, bottom, TICK_METHOD_COLOR));
+            let tasks = samples.get(index, SCHEDULED_TASKS);
+            let tasks_h = self.height(tasks as f64);
+            out.push(fill(
+                x,
+                bottom - method_h - tasks_h,
+                x + 1,
+                bottom - method_h,
+                TASK_COLOR,
+            ));
+            let other = value - samples.get(index, IDLE) - method - tasks;
+            let other_h = self.height(other as f64);
+            out.push(fill(
+                x,
+                bottom - other_h - tasks_h - method_h,
+                x + 1,
+                bottom - tasks_h - method_h,
+                OTHER_COLOR,
+            ));
+        }
+    }
+    /// `getValueForAggregation`: a tick's time without its idle part.
+    fn aggregated(self, samples: &SampleLogger, index: usize) -> i64 {
+        match self {
+            Chart::Tps { .. } => samples.get(index, 0) - samples.get(index, IDLE),
+            _ => samples.get(index, 0),
+        }
+    }
+    /// `extractAdditionalLinesAndLabels`.
+    fn lines_and_labels(
+        self,
+        out: &mut Vec<GuiDraw>,
+        font: &Font,
+        left: i32,
+        width: i32,
+        bottom: i32,
+    ) {
+        match self {
+            Chart::Fps { framerate_limit } => {
+                shaded(out, font, "30 fps", left + 1, bottom - CHART_HEIGHT + 1);
+                shaded(out, font, "60 fps", left + 1, bottom - 30 + 1);
+                horizontal_line(out, left, left + width - 1, bottom - 30, WHITE);
+                if framerate_limit > 0 && framerate_limit <= 250 {
+                    let y = bottom - self.height(1.0e9 / f64::from(framerate_limit)) - 1;
+                    horizontal_line(out, left, left + width - 1, y, CYAN);
+                }
+            }
+            Chart::Tps { mspt } => {
+                let tps = 1000.0 / mspt;
+                shaded(
+                    out,
+                    font,
+                    &format!("{tps:.1} tps"),
+                    left + 1,
+                    bottom - CHART_HEIGHT + 1,
+                );
+            }
+            Chart::Ping => shaded(out, font, "500 ms", left + 1, bottom - CHART_HEIGHT + 1),
+            Chart::Bandwidth => {
+                for bytes in [64.0, 1024.0, 16384.0] {
+                    let y = bottom - bandwidth_height(bytes);
+                    shaded(out, font, &bandwidth_display(bytes), left + 1, y + 1);
+                    horizontal_line(out, left, left + width - 1, y, WHITE);
+                }
+                let y = bottom - bandwidth_height(MEGABYTE) + 1;
+                shaded(out, font, &bandwidth_display(MEGABYTE), left + 1, y);
+            }
+        }
+    }
+    /// `toDisplayString`.
+    fn display(self, sample: f64) -> String {
+        match self {
+            Chart::Fps { .. } | Chart::Tps { .. } => format!("{} ms", java_round(sample / 1.0e6)),
+            Chart::Ping => format!("{} ms", java_round(sample)),
+            Chart::Bandwidth => bandwidth_display(sample * 20.0),
+        }
+    }
+    /// `getSampleHeight`.
+    fn height(self, sample: f64) -> i32 {
+        match self {
+            Chart::Fps { .. } => java_round(sample / 1.0e6 * 60.0 / 33.333333333333336) as i32,
+            Chart::Tps { mspt } => java_round(sample / 1.0e6 * 60.0 / f64::from(mspt)) as i32,
+            Chart::Ping => java_round(sample * 60.0 / 500.0) as i32,
+            Chart::Bandwidth => bandwidth_height(sample * 20.0),
+        }
+    }
+    /// `getSampleColor`.
+    fn color(self, sample: i64) -> u32 {
+        let s = sample as f64;
+        match self {
+            Chart::Fps { .. } => gradient(s / 1.0e6, 0.0, GREEN, 28.0, YELLOW, 56.0, RED),
+            Chart::Tps { mspt } => {
+                let m = f64::from(mspt);
+                gradient(s / 1.0e6, m, GREEN, m * 1.125, YELLOW, m * 1.25, RED)
+            }
+            Chart::Ping => gradient(s, 0.0, GREEN, 250.0, YELLOW, 500.0, RED),
+            Chart::Bandwidth => gradient(s * 20.0, 0.0, CYAN, 8192.0, LAVENDER, 1.048576e7, RED),
+        }
+    }
+}
+
+/// `BandwidthDebugChart.toDisplayStringInternal`.
+fn bandwidth_display(bytes_per_second: f64) -> String {
+    if bytes_per_second >= MEGABYTE {
+        format!("{:.1} MiB/s", bytes_per_second / MEGABYTE)
+    } else if bytes_per_second >= 1024.0 {
+        format!("{:.1} KiB/s", bytes_per_second / 1024.0)
+    } else {
+        format!("{} B/s", bytes_per_second.floor() as i64)
+    }
+}
+/// `BandwidthDebugChart.getSampleHeightInternal`: logarithmic, 1 MiB/s at
+/// the top.
+fn bandwidth_height(bytes_per_second: f64) -> i32 {
+    java_round((bytes_per_second + 1.0).ln() * 60.0 / MEGABYTE.ln()) as i32
+}
+/// `Math.round(double)`: halves round up.
+fn java_round(v: f64) -> i64 {
+    (v + 0.5).floor() as i64
+}
+/// `AbstractDebugChart.getSampleColor(sample, min, minColor, mid, ...)`.
+fn gradient(
+    sample: f64,
+    min: f64,
+    min_color: u32,
+    mid: f64,
+    mid_color: u32,
+    max: f64,
+    max_color: u32,
+) -> u32 {
+    let sample = sample.clamp(min, max);
+    if sample < mid {
+        srgb_lerp(((sample - min) / (mid - min)) as f32, min_color, mid_color)
+    } else {
+        srgb_lerp(((sample - mid) / (max - mid)) as f32, mid_color, max_color)
+    }
+}
+/// `ARGB.srgbLerp`: each channel by `Mth.lerpInt`.
+fn srgb_lerp(alpha: f32, p0: u32, p1: u32) -> u32 {
+    let channel = |shift: u32| {
+        let (a, b) = (((p0 >> shift) & 255) as i32, ((p1 >> shift) & 255) as i32);
+        (a + (alpha * (b - a) as f32).floor() as i32) as u32
+    };
+    argb(channel(24), channel(16), channel(8), channel(0))
+}
+/// `GuiGraphicsExtractor.horizontalLine`.
+fn horizontal_line(out: &mut Vec<GuiDraw>, x0: i32, x1: i32, y: i32, color: u32) {
+    out.push(fill(x0.min(x1), y, x0.max(x1) + 1, y + 1, color));
+}
+/// `GuiGraphicsExtractor.verticalLine`.
+fn vertical_line(out: &mut Vec<GuiDraw>, x: i32, y0: i32, y1: i32, color: u32) {
+    out.push(fill(x, y0.min(y1) + 1, x + 1, y0.max(y1), color));
+}
+fn text(out: &mut Vec<GuiDraw>, s: String, x: i32, y: i32, color: u32, shadow: bool) {
+    out.push(GuiDraw::Text {
+        text: Text::literal(s),
+        x,
+        y,
+        color,
+        shadow,
+    });
+}
+/// `extractStringWithShade`: a label on a dark backdrop, without shadow.
+fn shaded(out: &mut Vec<GuiDraw>, font: &Font, s: &str, x: i32, y: i32) {
+    out.push(fill(x, y, x + font.width(s) as i32 + 1, y + 9, BACKDROP));
+    text(out, s.to_owned(), x + 1, y + 1, LABEL, false);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_logger_keeps_the_last_240_samples() {
+        let mut l = SampleLogger::default();
+        for i in 0..300 {
+            l.log(i);
+        }
+        assert_eq!(l.len(), CAPACITY);
+        assert_eq!(l.get(0, 0), 60);
+        assert_eq!(l.get(CAPACITY - 1, 0), 299);
+    }
+
+    #[test]
+    fn chart_toggles_show_the_overlay_and_exclude_each_other() {
+        let mut c = DebugCharts::default();
+        let mut overlay = false;
+        c.toggle_fps(&mut overlay);
+        assert!(overlay && c.fps);
+        c.toggle_network(&mut overlay);
+        assert!(c.network && !c.fps);
+        c.toggle_network(&mut overlay);
+        assert!(!c.network && overlay);
+        c.toggle_lightmap(&mut overlay);
+        c.toggle_fps(&mut overlay);
+        assert!(c.fps && !c.lightmap);
+        // With the overlay hidden, the key shows it again with the chart on.
+        c.toggle_fps(&mut overlay);
+        overlay = false;
+        c.toggle_fps(&mut overlay);
+        assert!(overlay && c.fps);
+    }
+
+    #[test]
+    fn the_lightmap_puts_full_sky_light_at_the_top_left() {
+        let mut pixels = [0u8; 16 * 16 * 4];
+        // Sky 15, block 0: the last row's first texel.
+        pixels[15 * 64..15 * 64 + 4].copy_from_slice(&[10, 20, 30, 255]);
+        let draws = lightmap(&pixels, 427, 240);
+        assert_eq!(draws[0], fill(360, 173, 426, 239, 0xFF00_0000));
+        assert_eq!(draws.len(), 257);
+        assert!(draws.contains(&fill(361, 174, 365, 178, 0xFF0A_141E)));
+    }
+
+    #[test]
+    fn ticks_and_bandwidth_log_their_differences() {
+        let mut c = DebugCharts::default();
+        let t0 = Instant::now();
+        c.log_tick(t0, Duration::from_millis(5));
+        c.log_tick(t0 + Duration::from_millis(50), Duration::from_millis(7));
+        assert_eq!(
+            c.tick_times.samples[1],
+            [50_000_000, 7_000_000, 0, 43_000_000]
+        );
+        c.log_bandwidth(1000);
+        c.log_bandwidth(1600);
+        assert_eq!(c.bandwidth.len(), 1);
+        assert_eq!(c.bandwidth.get(0, 0), 600);
+    }
+
+    #[test]
+    fn heights_match_vanilla_scales() {
+        let fps = Chart::Fps {
+            framerate_limit: 260,
+        };
+        // 33.3 ms (30 fps) fills the chart; 16.7 ms half of it.
+        assert_eq!(fps.height(33_333_333.0), 60);
+        assert_eq!(fps.height(16_666_667.0), 30);
+        let tps = Chart::Tps { mspt: 50.0 };
+        assert_eq!(tps.height(25e6), 30);
+        assert_eq!(Chart::Ping.height(250.0), 30);
+        // 1 MiB/s at the top; 52 bytes per tick is 1 KiB/s.
+        assert_eq!(bandwidth_height(MEGABYTE), 60);
+        assert_eq!(Chart::Bandwidth.height(51.2), 30);
+    }
+
+    #[test]
+    fn labels_match_vanilla_formats() {
+        assert_eq!(
+            Chart::Fps { framerate_limit: 0 }.display(16_500_000.0),
+            "17 ms"
+        );
+        assert_eq!(Chart::Ping.display(12.4), "12 ms");
+        assert_eq!(Chart::Bandwidth.display(3.0), "60 B/s");
+        assert_eq!(Chart::Bandwidth.display(100.0), "2.0 KiB/s");
+        assert_eq!(bandwidth_display(MEGABYTE), "1.0 MiB/s");
+    }
+
+    #[test]
+    fn colours_go_green_yellow_red() {
+        let fps = Chart::Fps { framerate_limit: 0 };
+        assert_eq!(fps.color(0), GREEN);
+        assert_eq!(fps.color(28_000_000), YELLOW);
+        assert_eq!(fps.color(100_000_000), RED);
+        // Halfway between green and yellow: Mth.lerpInt floors.
+        assert_eq!(fps.color(14_000_000), 0xFF7F_FF00);
+        let tps = Chart::Tps { mspt: 50.0 };
+        assert_eq!(tps.color(10_000_000), GREEN);
+        assert_eq!(Chart::Bandwidth.color(0), CYAN);
+    }
+}
@@ -0,0 +1,473 @@
+//! The debug keys (26.3 `KeyboardHandler`): `key.debug.modifier` (F3) held
+//! with another key runs a debug action (`handleDebugKeys`), released alone
+//! it toggles the debug overlay (`key.debug.overlay`, F3 too by default);
+//! with Escape it pauses without the menu; held with `key.debug.crash` (C)
+//! for ten seconds it crashes the game (`tick`).
+use crate::keybinds::KeyBinds;
+
+/// A debug mapping's action, as `handleDebugKeys` tests them.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum DebugAction {
+    ReloadChunks,
+    ShowHitboxes,
+    ClearChat,
+    ShowChunkBorders,
+    AdvancedTooltips,
+    CopyRecreateCommand,
+    Spectate,
+    SwitchGameMode,
+    DebugOptions,
+    FocusPause,
+    DumpDynamicTextures,
+    ReloadResourcePacks,
+    Profiling,
+    CopyLocation,
+    DumpVersion,
+    ProfilingChart,
+    FpsCharts,
+    NetworkCharts,
+    LightmapTexture,
+    ImprovedTransparency,
+}
+
+/// The mappings `handleDebugKeys` tests, in its order.
+pub const ACTIONS: [(&str, DebugAction); 20] = [
+    ("key.debug.reloadChunk", DebugAction::ReloadChunks),
+    ("key.debug.showHitboxes", DebugAction::ShowHitboxes),
+    ("key.debug.clearChat", DebugAction::ClearChat),
+    ("key.debug.showChunkBorders", DebugAction::ShowChunkBorders),
+    (
+        "key.debug.showAdvancedTooltips",
+        DebugAction::AdvancedTooltips,
+    ),
+    (
+        "key.debug.copyRecreateCommand",
+        DebugAction::CopyRecreateCommand,
+    ),
+    ("key.debug.spectate", DebugAction::Spectate),
+    ("key.debug.switchGameMode", DebugAction::SwitchGameMode),
+    ("key.debug.debugOptions", DebugAction::DebugOptions),
+    ("key.debug.focusPause", DebugAction::FocusPause),
+    (
+        "key.debug.dumpDynamicTextures",
+        DebugAction::DumpDynamicTextures,
+    ),
+    (
+        "key.debug.reloadResourcePacks",
+        DebugAction::ReloadResourcePacks,
+    ),
+    ("key.debug.profiling", DebugAction::Profiling),
+    ("key.debug.copyLocation", DebugAction::CopyLocation),
+    ("key.debug.dumpVersion", DebugAction::DumpVersion),
+    ("key.debug.profilingChart", DebugAction::ProfilingChart),
+    ("key.debug.fpsCharts", DebugAction::FpsCharts),
+    ("key.debug.networkCharts", DebugAction::NetworkCharts),
+    ("key.debug.lightmapTexture", DebugAction::LightmapTexture),
+    (
+        "key.debug.improvedTransparency",
+        DebugAction::ImprovedTransparency,
+    ),
+];
+
+/// GLFW's key actions.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum KeyAction {
+    Release,
+    Press,
+    Repeat,
+}
+
+/// The screen open when a key reaches the game (after the screen itself
+/// passed on it).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum OpenScreen {
+    None,
+    /// `PauseScreen` without its menu (F3+Escape).
+    PauseWithoutMenu,
+    GameModeSwitcher,
+    Other,
+}
+
+/// What the game does for `KeyboardHandler.keyPress`.
+pub trait DebugHost {
+    fn screen(&self) -> OpenScreen;
+    /// `DebugScreenEntries.toggleDebugOverlay`.
+    fn toggle_overlay(&mut self);
+    /// `Minecraft.pauseGame(suppressPauseMenu)`.
+    fn pause_game(&mut self, without_menu: bool);
+    /// One matching mapping of `handleDebugKeys`; whether its condition held
+    /// (vanilla's `debugAction = true`). `shift`: `event.hasShiftDown()`.
+    fn debug_action(&mut self, action: DebugAction, shift: bool) -> bool;
+}
+
+/// What `KeyboardHandler.tick` reports while the debug crash keys are held.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum CrashNotice {
+    /// `debug.crash.message`, a second after the keys went down.
+    Message,
+    /// `debug.crash.warning` with the seconds left.
+    Warning(i32),
+    /// "Manually triggered debug crash".
+    Crash,
+}
+
+/// `KeyboardHandler`'s state, with the down state of `keyDebugModifier`.
+#[derive(Clone, Debug, Default)]
+pub struct DebugKeys {
+    pub used_debug_key_as_modifier: bool,
+    /// `debugCrashKeyTime`: when the crash keys went down (milliseconds),
+    /// 0 never, -1 released.
+    pub crash_key_time: i64,
+    pub crash_key_reported_time: i64,
+    pub crash_key_reported_count: i64,
+    /// `keyDebugModifier.isDown()`.
+    pub modifier_down: bool,
+}
+
+impl DebugKeys {
+    /// `keyPress` once the open screen (if any) did not take the key. `key`
+    /// is the physical key's name (`key.keyboard.f3`); `crash_key_down`
+    /// whether the crash mapping's key is held (`InputConstants.isKeyDown`).
+    /// Returns whether the key goes on to the game's key mappings
+    /// (`KeyMapping.set(key, true)` and `click`): only without a screen and
+    /// when it ran no debug action.
+    #[allow(clippy::too_many_arguments)]
+    pub fn key_press(
+        &mut self,
+        host: &mut impl DebugHost,
+        binds: &KeyBinds,
+        key: &str,
+        action: KeyAction,
+        shift: bool,
+        crash_key_down: bool,
+        now: i64,
+    ) -> bool {
+        let modifier = binds.get("key.debug.modifier");
+        let overlay = binds.get("key.debug.overlay");
+        let same = modifier == overlay;
+        let modifier_down = self.modifier_down;
+        let crash = binds.get("key.debug.crash") != "key.keyboard.unknown" && crash_key_down;
+        if self.crash_key_time > 0 {
+            if !crash || !modifier_down {
+                self.crash_key_time = -1;
+            }
+        } else if crash && modifier_down {
+            self.used_debug_key_as_modifier = same;
+            self.crash_key_time = now;
+            self.crash_key_reported_time = now;
+            self.crash_key_reported_count = 0;
+        }
+        let screen = host.screen();
+        let handles_game = screen == OpenScreen::None;
+        let handles_global = handles_game
+            || matches!(
+                screen,
+                OpenScreen::PauseWithoutMenu | OpenScreen::GameModeSwitcher
+            );
+        if same && key == modifier && action == KeyAction::Release {
+            if self.used_debug_key_as_modifier {
+                self.used_debug_key_as_modifier = false;
+            } else {
+                host.toggle_overlay();
+            }
+        } else if !same && key == overlay && action == KeyAction::Press {
+            host.toggle_overlay();
+        }
+        if action == KeyAction::Release {
+            // KeyMapping.set(key, false).
+            if key == modifier {
+                self.modifier_down = false;
+            }
+            return false;
+        }
+        let mut did = false;
+        if handles_global && key == "key.keyboard.escape" {
+            host.pause_game(modifier_down);
+            did = modifier_down;
+        } else if modifier_down {
+            did = self.handle_debug_keys(host, binds, key, shift, now);
+        }
+        if same {
+            self.used_debug_key_as_modifier |= did;
+        }
+        // KeyMapping.set(key, !did) for the game, setDown(!did) behind a screen.
+        if key == modifier {
+            self.modifier_down = !did;
+        }
+        handles_game && !did
+    }
+    /// `handleDebugKeys`: every debug mapping on this key, in order.
+    fn handle_debug_keys(
+        &mut self,
+        host: &mut impl DebugHost,
+        binds: &KeyBinds,
+        key: &str,
+        shift: bool,
+        now: i64,
+    ) -> bool {
+        // Once the crash keys have been down a tenth of a second.
+        if self.crash_key_time > 0 && self.crash_key_time < now - 100 {
+            return true;
+        }
+        let mut did = false;
+        for (name, action) in ACTIONS {
+            if binds.get(name) == key {
+                did |= host.debug_action(action, shift);
+            }
+        }
+        did
+    }
+    /// `KeyboardHandler.tick`.
+    pub fn tick(&mut self, now: i64) -> Option<CrashNotice> {
+        if self.crash_key_time <= 0 {
+            return None;
+        }
+        let remaining = 10000 - (now - self.crash_key_time);
+        let reported = now - self.crash_key_reported_time;
+        if remaining < 0 {
+            return Some(CrashNotice::Crash);
+        }
+        if reported >= 1000 {
+            let notice = if self.crash_key_reported_count == 0 {
+                CrashNotice::Message
+            } else {
+                // Mth.ceil(remainingTime / 1000.0F).
+                CrashNotice::Warning((remaining as f32 / 1000.0).ceil() as i32)
+            };
+            self.crash_key_reported_time = now;
+            self.crash_key_reported_count += 1;
+            return Some(notice);
+        }
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[derive(Default)]
+    struct Host {
+        screen: Option<OpenScreen>,
+        overlay: u32,
+        paused: Vec<bool>,
+        actions: Vec<(DebugAction, bool)>,
+        /// Actions whose condition fails (no player, reduced debug info...).
+        refused: Vec<DebugAction>,
+    }
+    impl DebugHost for Host {
+        fn screen(&self) -> OpenScreen {
+            self.screen.unwrap_or(OpenScreen::None)
+        }
+        fn toggle_overlay(&mut self) {
+            self.overlay += 1;
+        }
+        fn pause_game(&mut self, without_menu: bool) {
+            self.paused.push(without_menu);
+        }
+        fn debug_action(&mut self, action: DebugAction, shift: bool) -> bool {
+            self.actions.push((action, shift));
+            !self.refused.contains(&action)
+        }
+    }
+    const F3: &str = "key.keyboard.f3";
+
+    fn press(k: &mut DebugKeys, h: &mut Host, b: &KeyBinds, key: &str, now: i64) -> bool {
+        k.key_press(h, b, key, KeyAction::Press, false, false, now)
+    }
+    fn release(k: &mut DebugKeys, h: &mut Host, b: &KeyBinds, key: &str) -> bool {
+        k.key_press(h, b, key, KeyAction::Release, false, false, 0)
+    }
+
+    #[test]
+    fn f3_alone_toggles_the_overlay_on_release() {
+        let (mut k, mut h, b) = (DebugKeys::default(), Host::default(), KeyBinds::default());
+        // The F3 press goes to the game's mappings (key.debug.* are down now).
+        assert!(press(&mut k, &mut h, &b, F3, 0));
+        assert!(k.modifier_down);
+        assert_eq!(h.overlay, 0);
+        assert!(!release(&mut k, &mut h, &b, F3));
+        assert_eq!(h.overlay, 1);
+        assert!(!k.modifier_down);
+    }
+
+    #[test]
+    fn a_combination_runs_its_action_and_keeps_the_overlay() {
+        let (mut k, mut h, b) = (DebugKeys::default(), Host::default(), KeyBinds::default());
+        press(&mut k, &mut h, &b, F3, 0);
+        // F3+G: the action, and G does not reach the game.
+        assert!(!press(&mut k, &mut h, &b, "key.keyboard.g", 10));
+        assert_eq!(h.actions, [(DebugAction::ShowChunkBorders, false)]);
+        release(&mut k, &mut h, &b, "key.keyboard.g");
+        release(&mut k, &mut h, &b, F3);
+        assert_eq!(h.overlay, 0);
+        // The next F3 alone toggles again.
+        press(&mut k, &mut h, &b, F3, 20);
+        release(&mut k, &mut h, &b, F3);
+        assert_eq!(h.overlay, 1);
+    }
+
+    #[test]
+    fn c_copies_the_location_and_both_c_mappings_share_the_key() {
+        let (mut k, mut h, b) = (DebugKeys::default(), Host::default(), KeyBinds::default());
+        press(&mut k, &mut h, &b, F3, 0);
+        k.key_press(
+            &mut h,
+            &b,
+            "key.keyboard.c",
+            KeyAction::Press,
+            true,
+            true,
+            5,
+        );
+        assert_eq!(h.actions, [(DebugAction::CopyLocation, true)]);
+        // The crash keys are down: from a tenth of a second on, debug keys
+        // are swallowed.
+        assert_eq!(k.crash_key_time, 5);
+        k.key_press(
+            &mut h,
+            &b,
+            "key.keyboard.c",
+            KeyAction::Repeat,
+            false,
+            true,
+            50,
+        );
+        assert_eq!(h.actions.len(), 2);
+        assert!(!k.key_press(
+            &mut h,
+            &b,
+            "key.keyboard.c",
+            KeyAction::Repeat,
+            false,
+            true,
+            200
+        ));
+        assert_eq!(h.actions.len(), 2);
+    }
+
+    #[test]
+    fn held_crash_keys_warn_every_second_then_crash() {
+        let (mut k, mut h, b) = (DebugKeys::default(), Host::default(), KeyBinds::default());
+        press(&mut k, &mut h, &b, F3, 0);
+        k.key_press(
+            &mut h,
+            &b,
+            "key.keyboard.c",
+            KeyAction::Press,
+            false,
+            true,
+            1000,
+        );
+        assert_eq!(k.tick(1500), None);
+        assert_eq!(k.tick(2000), Some(CrashNotice::Message));
+        assert_eq!(k.tick(2999), None);
+        assert_eq!(k.tick(3000), Some(CrashNotice::Warning(8)));
+        assert_eq!(k.tick(4100), Some(CrashNotice::Warning(7)));
+        assert_eq!(k.tick(11_000), Some(CrashNotice::Warning(0)));
+        assert_eq!(k.tick(11_001), Some(CrashNotice::Crash));
+        // Releasing either key stops it on the next key event.
+        let mut k2 = DebugKeys::default();
+        press(&mut k2, &mut h, &b, F3, 0);
+        k2.key_press(
+            &mut h,
+            &b,
+            "key.keyboard.c",
+            KeyAction::Press,
+            false,
+            true,
+            1000,
+        );
+        k2.key_press(
+            &mut h,
+            &b,
+            "key.keyboard.c",
+            KeyAction::Release,
+            false,
+            false,
+            1200,
+        );
+        assert_eq!(k2.crash_key_time, -1);
+        assert_eq!(k2.tick(20_000), None);
+        // The crash used F3 as a modifier: its release does not toggle the overlay.
+        release(&mut k2, &mut h, &b, F3);
+        assert_eq!(h.overlay, 0);
+    }
+
+    #[test]
+    fn refused_actions_do_not_count() {
+        let (mut k, mut h, b) = (DebugKeys::default(), Host::default(), KeyBinds::default());
+        h.refused.push(DebugAction::ShowHitboxes);
+        press(&mut k, &mut h, &b, F3, 0);
+        // F3+B without a player (or with reduced debug info): B reaches the
+        // game and F3's release still toggles the overlay.
+        assert!(press(&mut k, &mut h, &b, "key.keyboard.b", 1));
+        release(&mut k, &mut h, &b, F3);
+        assert_eq!(h.overlay, 1);
+    }
+
+    #[test]
+    fn escape_pauses_with_or_without_the_menu() {
+        let (mut k, mut h, b) = (DebugKeys::default(), Host::default(), KeyBinds::default());
+        assert!(press(&mut k, &mut h, &b, "key.keyboard.escape", 0));
+        press(&mut k, &mut h, &b, F3, 1);
+        assert!(!press(&mut k, &mut h, &b, "key.keyboard.escape", 2));
+        assert_eq!(h.paused, [false, true]);
+        release(&mut k, &mut h, &b, F3);
+        assert_eq!(h.overlay, 0);
+        // Behind another screen, Escape is the screen's.
+        h.screen = Some(OpenScreen::Other);
+        press(&mut k, &mut h, &b, "key.keyboard.escape", 3);
+        assert_eq!(h.paused.len(), 2);
+    }
+
+    #[test]
+    fn behind_a_screen_combinations_work_but_keys_stay_with_the_screen() {
+        let (mut k, mut h, b) = (DebugKeys::default(), Host::default(), KeyBinds::default());
+        h.screen = Some(OpenScreen::Other);
+        assert!(!press(&mut k, &mut h, &b, F3, 0));
+        assert!(k.modifier_down);
+        assert!(!press(&mut k, &mut h, &b, "key.keyboard.h", 1));
+        assert_eq!(h.actions, [(DebugAction::AdvancedTooltips, false)]);
+        release(&mut k, &mut h, &b, F3);
+        assert_eq!(h.overlay, 0);
+    }
+
+    #[test]
+    fn switcher_modifier_release_does_not_toggle_the_debug_overlay() {
+        let (mut k, mut h, mut b) = (DebugKeys::default(), Host::default(), KeyBinds::default());
+        // Screen release handling must also work with rebound debug keys.
+        b.set("key.debug.modifier", "key.keyboard.f7");
+        b.set("key.debug.overlay", "key.keyboard.f7");
+        b.set("key.debug.switchGameMode", "key.keyboard.f8");
+        press(&mut k, &mut h, &b, "key.keyboard.f7", 0);
+        assert!(!press(&mut k, &mut h, &b, "key.keyboard.f8", 1));
+        assert_eq!(h.actions, [(DebugAction::SwitchGameMode, false)]);
+        h.screen = Some(OpenScreen::GameModeSwitcher);
+        release(&mut k, &mut h, &b, "key.keyboard.f8");
+        release(&mut k, &mut h, &b, "key.keyboard.f7");
+        assert!(!k.modifier_down);
+        assert_eq!(h.overlay, 0);
+    }
+
+    #[test]
+    fn a_separate_overlay_key_toggles_on_press() {
+        let (mut k, mut h, mut b) = (DebugKeys::default(), Host::default(), KeyBinds::default());
+        b.set("key.debug.overlay", "key.keyboard.f7");
+        press(&mut k, &mut h, &b, "key.keyboard.f7", 0);
+        assert_eq!(h.overlay, 1);
+        press(&mut k, &mut h, &b, F3, 1);
+        release(&mut k, &mut h, &b, F3);
+        assert_eq!(h.overlay, 1);
+    }
+
+    #[test]
+    fn rebound_mappings_follow_their_keys() {
+        let (mut k, mut h, mut b) = (DebugKeys::default(), Host::default(), KeyBinds::default());
+        b.set("key.debug.showChunkBorders", "key.keyboard.k");
+        press(&mut k, &mut h, &b, F3, 0);
+        assert!(press(&mut k, &mut h, &b, "key.keyboard.g", 1));
+        press(&mut k, &mut h, &b, "key.keyboard.k", 2);
+        assert_eq!(h.actions, [(DebugAction::ShowChunkBorders, false)]);
+    }
+}
@@ -283,8 +283,11 @@ impl PlayerEffects {
            levitation: self.amplifier("levitation"),
            resistance: self.amplifier("resistance"),
            fire_resistance: self.get("fire_resistance").is_some(),
+            dolphins_grace: self.get("dolphins_grace").is_some(),
+            weaving: self.get("weaving").is_some(),
            water_breathing: self.get("water_breathing").is_some()
                || self.get("conduit_power").is_some(),
+            breath_of_the_nautilus: self.get("breath_of_the_nautilus").is_some(),
            protection: Vec::new(),
        }
    }
@@ -365,12 +368,7 @@ impl PlayerEffects {
            f *= 1.0 + (a + 1) as f32 * 0.2;
        }
        if let Some(a) = self.amplifier("mining_fatigue") {
-            f *= match a {
-                0 => 0.3,
-                1 => 0.09,
-                2 => 0.0027,
-                _ => 8.1e-4,
-            };
+            f *= horizon_core::jmath::pow(0.3, f64::from(a + 1)) as f32;
        }
        f
    }
@@ -383,7 +381,11 @@ pub struct StatusFlags {
    pub levitation: Option<i32>,
    pub resistance: Option<i32>,
    pub fire_resistance: bool,
+    pub dolphins_grace: bool,
+    /// Weaving: cobwebs hold half as much (`WebBlock.entityInside`).
+    pub weaving: bool,
    pub water_breathing: bool,
+    pub breath_of_the_nautilus: bool,
    /// Armor enchantment protection per damage type id (`EnchantmentHelper.getDamageProtection`).
    pub protection: Vec<(String, f32)>,
 }
@@ -628,7 +628,8 @@ impl Enchantments {
                } else {
                    spec
                };
-                spec.is_null() && entity.is_some() || self.entity_matches(spec, entity)
+                (spec.is_null() && entity.is_some() || self.entity_matches(spec, entity))
+                    && movement_matches(&c["predicate"], role_state(c, ctx))
            }
            "minecraft:random_chance" => {
                let chance = match &c["chance"] {
@@ -661,6 +662,38 @@ pub struct EffectContext<'a> {
    pub this: Option<&'a str>,
    pub attacker: Option<&'a str>,
    pub direct_attacker: Option<&'a str>,
+    /// The direct attacker's fall distance and whether it flies (elytra or
+    /// abilities), for `movement` and `flags` predicates.
+    pub direct_motion: Option<(f64, bool)>,
+}
+/// The fall distance and flying flag known for an `entity_properties` role.
+fn role_state(c: &Value, ctx: &EffectContext<'_>) -> Option<(f64, bool)> {
+    match c["entity"].as_str().unwrap_or("this") {
+        "direct_attacker" => ctx.direct_motion,
+        _ => None,
+    }
+}
+/// `EntityPredicate`'s `minecraft:movement` fall distance and
+/// `minecraft:flags` is_flying (the parts enchantment requirements use); an
+/// entity whose state is unknown matches neither.
+fn movement_matches(predicate: &Value, state: Option<(f64, bool)>) -> bool {
+    let fall = &predicate["minecraft:movement"]["fall_distance"];
+    let flying = predicate["minecraft:flags"]["is_flying"].as_bool();
+    if fall.is_null() && flying.is_none() {
+        return true;
+    }
+    let Some((distance, is_flying)) = state else {
+        return false;
+    };
+    // MinMaxBounds.Doubles: a number is an exact bound.
+    let bound = |key: &str| {
+        fall.as_f64()
+            .or_else(|| fall.get(key).and_then(Value::as_f64))
+    };
+    // MinMaxBounds.Doubles.matches
+    bound("min").is_none_or(|min| min <= distance)
+        && bound("max").is_none_or(|max| distance <= max)
+        && flying.is_none_or(|f| f == is_flying)
 }
 fn next_int<R: RandomSource>(random: &mut R, bound: i32) -> i32 {
    random.next_int_bound(bound.max(1)).unwrap_or(0)
@@ -0,0 +1,38 @@
+//! `EndCrystalRenderer` and `EndCrystalModel.setupAnim`: the crystal's bob
+//! and the poses of its base, glass and cube.
+use crate::mobs::{Part, anim::Poses};
+use horizon_core::geometry::trig::Mth;
+
+/// `EndCrystalRenderer.getY`: the crystal's bob below its resting height.
+pub fn y(age: f32) -> f32 {
+    let hh = (age * 0.2).msin() / 2.0 + 0.5;
+    (hh * hh + hh) * 0.4 - 1.4
+}
+
+/// `EndCrystalModel.setupAnim`: the base shown or not, the glass raised by
+/// half the bob (in model pixels) and the three cubes turned with
+/// `ModelPart.rotateBy`, which stores the composed rotation as ZYX angles.
+pub fn poses(model: &Part, age: f32, show_bottom: bool) -> Poses {
+    let mut poses = Poses::new(model);
+    poses.visible("base", show_bottom);
+    let speed = age * 3.0;
+    let sin45 = std::f32::consts::FRAC_PI_4.sin();
+    let tilt = glam::Quat::from_axis_angle(
+        glam::Vec3::new(sin45, 0.0, sin45),
+        std::f32::consts::FRAC_PI_3,
+    );
+    let spin = glam::Quat::from_rotation_y(speed.to_radians());
+    poses.get("outer_glass")[1] += y(age) * 16.0 / 2.0;
+    for (part, rotation) in [
+        ("outer_glass", spin * tilt),
+        ("inner_glass", tilt * spin),
+        ("cube", tilt * spin),
+    ] {
+        let (z, y, x) = rotation.to_euler(glam::EulerRot::ZYX);
+        let pose = poses.get(part);
+        pose[3] = x;
+        pose[4] = y;
+        pose[5] = z;
+    }
+    poses
+}