Client-agnostic source of truth for everything botable in OSRS: activities, ordering, actions, requirements. AI agents translate entries into client APIs.
765505ed0f
Governor bounce 4 + owner guidance 2026-08-28 (structured, provable, full lifecycle):
1. site model is data, not prose: new mine_sites table (ore, gates, rock_count,
respawn_seconds, rolls_per_ore, modeled_ores_per_hour, world_hop, selectable,
inventory_policy, access, safety, route). Adamantite @ Al Kharid south is now
respawn-BOUND (2 rocks, 240 s respawn): modeled 120 ores/hr ONLY with world
hopping (wiki F2P adamantite guide) = 70,080 gp/hr; no-hop ceiling ~30/hr =
17,520; the 839 ores/hr iron-cadence fantasy is gone and a cadence-ceiling
gate rejects it. Runite is selectable:false (Wilderness PK risk, ~12 min
respawn) — refused, not hand-waved. New hop state + hop_world action (a14)
implement the world-hop policy; long-respawn selectable sites REQUIRE
world_hop + a hop_world action (validator).
2. fast-xp success model: rolls_per_ore 1.33 (61+, derived from the wiki 52,500
benchmark: 1,500 ores/hr / 2,000 3-tick rolls/hr); rates recomputed with
success rolls + respawn math (3 rocks x 3.59 s = 10.8 s > 5.4 s respawn ->
zero idle, pinned) + drop/bank + breaks: xp_per_hour 28,000 (was 32,400 with
a flat 0.3 s and 1 ore/click); 52,500 stays a labeled external benchmark.
3. sub-29 fast-xp preserved: South-east Varrock DROP site (safe, same mode) —
the mode never silently switches to banking.
4. tool prep executable end to end: check-tool (has_item) -> withdraw-tool
(owned branch, bank_inventory) or buy-tool + wait-ge-fill (ge_offers_done) +
collect-tool (ge_collect, verify) -> equip-tool via menu_option Wield with
the Attack gate; recovery on purchase/equip failure (3 -> failed).
5. VALIDATOR PROVES THE CONTRACT (no phrase-search): pickaxe_tiers must match
the canonical F2P table exactly (Mining=use gate, Attack=equip gate,
roll_ticks); pickaxe_examples recomputed per row (1-Attack/41-Mining must
select + CARRY rune; 40-Attack/70-Mining equips; 5-Attack/30-Mining carries
mithril); both modes declared with fixed inventory policies; mode refs must
resolve to declared selectable policy-matching sites; Wilderness selectable
-> error; modeled ores/hr <= 3600/(rolls_per_ore x 2.7 s); xp_per_hour
within 2% of the modeled fast-xp rate. 13 committed --selftest fixtures
(negative cases included) wired into every gate run.
Evidence: validate 2 entries 0 errors 1 pre-existing WARN; --selftest 13 PASS;
synthetic 3-way merge main
|
||
|---|---|---|
| codex | ||
| docs | ||
| schemas | ||
| tools | ||
| README.md | ||
OSRS Codex
One source of truth for everything that can be botted in OSRS.
Every bot-able activity — alching, mining, slayer, bosses, trading — is described here once, in a strict client-agnostic YAML structure: requirements, execution order (state machine), the exact action sequence, economics, best-in-class setup, and anti-ban notes.
AI agents building scripts do not re-learn the game. They read a codex entry and translate it into the target client API (DreamBot / Microbot / Storm / RuneLite plugins / …). The game knowledge lives in this repo; the client glue lives in whatever script is being written.
client-agnostic client-specific (NOT in this repo)
+----------------+ +-------------------+
| codex entry | translate | DreamBot Java |
| (YAML, strict) | ---------> | Microbot JS |
| actions: verbs | | RuneLite plugin |
+----------------+ +-------------------+
Layout
codex/<domain>/<entry-id>.yaml # one entry per activity
economy/ trading, alching, flipping
training/ skill grinds (magic, mining, woodcutting, ...)
combat/ bosses
combat-slayers/
quests/ quest entries (referenced by requires_quest)
transport/ teleport/teleport-reach recipes (shared by many entries)
meta/ account rotation, world hopping, break scheduling
docs/schema.md # the entry contract (read this first)
docs/action-grammar.md # the universal verb vocabulary
docs/data-sources.md # where every fact must come from + how to verify
schemas/entry.schema.json
tools/validate.py # the gate: python3 tools/validate.py (must exit 0)
The rules (short version)
- One entry = one activity. State machine + action list, both mandatory.
- Every fact carries a source. Wiki-cited or
researched <date>(a TODO: follow-up issue must land the proper citation). Live prices are re-verified againstprices.runescape.wikion every bump. - Best-in-class setup is mandatory (
best_practice). Top-operator execution: staff of fire for alchemy, noted items, shortest routes. Translators adopt it by default; deviating requiresimprovised: true. - Anti-ban is first-class. Every action declares delay bounds and
movement style; entries carry
risk.ban_level+ notes. - The gate must pass before a PR merges:
python3 tools/validate.py. - Never mix in client knowledge. No DreamBot/Microbot/Storm API names in entries. Translations live in script repos, referencing the entry id.
Entry lifecycle
draft → verified (all facts sourced, prices re-checked, validator
clean) → stale (facts > 30d old or prices moved materially). Stale
entries are skipped by translators unless explicitly allowed.
Contributing
This repo is issue-driven: all content is specified in Gitea issues
(acceptance criteria + source URLs + expected output path), implemented in
branches, and gated by tools/validate.py in CI. No direct pushes.