route-lab

The evidence and route-content layer for qw-ctf/rtx development.

rtx is a Rust bot engine for QuakeWorld. Its repo holds the how — mesh generation, movement executor, combat. What it cannot hold is the what and how well: which routes a DM3 bot must master, what a strong human actually achieves on them, and the proof that a given engine build clears that bar. route-lab is that layer — the umbrella repo for a DM3-specialized bot lab built around rtx.

This repo contains no production bot code (see the boundary note below). It is where human evidence becomes specifications, curated navigation content, and pass/fail baselines that rtx development is measured against.

What this adds to rtx development

Human corpus baselines as pass bars. CLIs over a mined corpus of thousands of human DM3 demos (dm3-route-report, dm3-cohort, dm3-route-search, dm3-objective-matrix) produce aggregate route timings — median, no-combat median, fastest — that turn "the bot is decent" into "the bot beats the same-life human median on this exact route". Routes are defined declaratively in route_lab/routes_dm3.json.

Gap specifications. artifacts/nav-patches/*-missing-spec.json (qw-missing-spec/1) formalize what humans do that the current mesh or executor cannot: named canonical jumps with measured variations, required takeoff speeds, router-today comparisons, and owner intent. Each spec's iteration log records what was tried, what worked, and the engine-side ("kodlane") facts discovered on the way — an evidence-driven backlog and changelog for rtx.

Curated navigation content. qw-nav-patch/1 patches: hand-planted certified links (including curl-profiled jumps derived from human lines) and removals of broken generated-link families. This is deployable route content layered on top of rtx's generated mesh — the difference between a bot that survives a map and one that runs routes like a player.

Booked gate evidence. Every certified route ships with its acceptance evidence (artifacts/*.jsonl): consecutive-streak trials from freshly restarted servers, with provenance. Engine regressions are caught by re-running gates against these baselines.

A standalone mesh viewer. qw-nav-viewer/ renders BSP geometry, nav graphs, overlays, live bot/human positions and demo replays in the browser. Its nav-core crate is a small self-contained re-implementation of the nav model (32u graph, link kinds, 8u nearfield) for rendering — not engine code.

Match/bench tooling. match-deck/ (match & bench MCP + deck UI) and plugins/qw-bot-control (Codex operator plugin) drive bot matches and benches against rtx servers.

Getting started

Run under WSL/Linux (process ownership and control-port locking use /proc, sockets and fcntl):

uv sync
uv run python -m unittest discover -s tests -v
uv run dm3-route-report --help
uv run dm3-objective-matrix route ring quad --no-combat

The only third-party runtime dependency is DuckDB. The demo corpus itself is not in this repo (external dataset; QW_DM3_CORPUS points at it), and the generated DuckDB index stays local and git-ignored. Checked-in JSON reports and summaries are aggregate-only.

The viewer needs .bsp map files under qw-nav-viewer/assets/maps/ — the original id Software maps are not distributed here; see qw-nav-viewer/assets/maps/README.md.

Start with AGENTS.md — the model-agnostic runbook that governs work in this repo — and HANDOVER.md for historical lab state. The live experiment bench that produces the evidence archived here is the companion repo qw-fasttrack.

The hard boundary

Human demo data is calibration evidence only. Placements, required speeds and timings from human play may inform specs and planted links; trajectories and user commands are never fed into bot runtime code. The canonical Rust engine source lives in its own repos and is deliberately not mirrored here.

MIT license. Prose is a mix of English and Swedish (the lab's working language).