69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
# 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)
|
|
|
|
1. **One entry = one activity.** State machine + action list, both mandatory.
|
|
2. **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 against `prices.runescape.wiki` on every bump.
|
|
3. **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 requires `improvised: true`.
|
|
4. **Anti-ban is first-class.** Every action declares delay bounds and
|
|
movement style; entries carry `risk.ban_level` + notes.
|
|
5. **The gate must pass** before a PR merges: `python3 tools/validate.py`.
|
|
6. **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.
|