b06b168c55
- Powermine drop loop: model per-slot Dropping of non-stackable ores — drop_run now self-loops (count_item ore > 0 -> drop_run) until the inventory is empty, then back to mine; a6 drops one occupied slot per execution and its params state the iteration contract. - Click cadence: a2 delay was 600-1400ms, below the rune pickaxe 3-tick (1.8s) mining roll — replaced with 2000-4200ms and comment distinguishing the roll interval from translator re-click cadence (bronze 8 ticks = 4.8s note). - Al Kharid survivability: route gate modeled - scorpion is level 14 and attacks players at combat <= 28 (wiki Aggressiveness, 2x rule), so Al Kharid powermine requires combat 29+ or food; new survive state with eat/ retreat actions (a7/a8), hard-failure path (food exhausted + low HP -> failed; death = hard failure, no respawn claim). Banked South-east Varrock route preserved for sub-29 accounts. version 1 -> 2. Validator: 0 errors, 1 pre-existing F2P WARN. |
||
|---|---|---|
| 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.