pbwraith/osrs-codex
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Client-agnostic source of truth for everything botable in OSRS: activities, ordering, actions, requirements. AI agents translate entries into client APIs.
5 Commits 7 Branches 0 Tags 961 KiB
Python 100%
75a9965c9f
Go to file
Claude 75a9965c9f codex: bounce-fix attempt 2 — additive pacing, cast-unit breaks, concrete SII recipes, validator crash guard (issue #5) 
Governor-review (PR #10, attempt 2) findings, same issue-5 branch:

1. Pacing is additive. action-grammar.md defines anti_ban.delay as sleep
   AFTER the action, so a cast takes 1.8s + 1.6-3.4s = 3.4-5.2s (mid
   4.3s), ~837 casts/hr, not 1,400 or 1,800. Both entries now pin the
   midpoint rate with the formula documented: LA 25,953 / SII 44,372 /
   HLA 54,419 xp/hr. low-alch-f2p gp_per_hour bracketed by the delay
   endpoints (-119,000 / -78,000).

2. run_control units agree: schema.md 'every' counts iterations and
   iteration is one cast, so break.every [8, 14] is casts (comment no
   longer claims bank cycles).

3. SII is now a concrete recipe. New top-level recipes: table models all
   eight F2P smithable bars (bronze/iron/silver/steel/gold/mithril/
   adamantite/runite) with every input and quantity (coal 2/4/6/8,
   Smithing gates, bar ids) from the OSRS wiki smelting table. The
   cast-superheat action pins params.recipe (steel-bar anchor) plus a
   recipe_rule: smithing gate + complete input cost + one nature rune <
   bar price; buy/withdraw the exact unnoted inputs; bank the bar.
   entry.schema.json gains the optional 'recipes' section. Validator
   gains recipe/SII checks and a deterministic steel-bar fixture
   (1 iron + 2 coal = 3 inputs; margin 600 - (100 + 2*150 + 145) = 55).

4. Validator no longer crashes on malformed docs: scalar/empty YAML is
   rejected with a normal ERROR (document shape check) and
   supply_limit_conflicts guards non-mapping rows; regression fixtures
   cover (bad.yaml, None), scalar docs, and undeclared recipe ids.

Tests: python3 tools/validate.py -> 2 entries, 0 errors, 0 warnings
(exit 0); --selftest -> 14 PASS; live negatives: scalar + empty docs
error cleanly (exit 1, no traceback), reintroduced 12500 divergence is
caught (supply-fact gate), git diff --check clean.
2026-08-27 17:01:54 -05:00
codex codex: bounce-fix attempt 2 — additive pacing, cast-unit breaks, concrete SII recipes, validator crash guard (issue #5) 2026-08-27 17:01:54 -05:00
docs Codex skeleton: schema contract, action grammar, data-sources rules, JSON schema, validator, golden example (low-alch-f2p, wiki+price verified), README 2026-08-27 02:59:55 -05:00
schemas codex: bounce-fix attempt 2 — additive pacing, cast-unit breaks, concrete SII recipes, validator crash guard (issue #5) 2026-08-27 17:01:54 -05:00
tools codex: bounce-fix attempt 2 — additive pacing, cast-unit breaks, concrete SII recipes, validator crash guard (issue #5) 2026-08-27 17:01:54 -05:00
README.md Codex skeleton: schema contract, action grammar, data-sources rules, JSON schema, validator, golden example (low-alch-f2p, wiki+price verified), README 2026-08-27 02:59:55 -05:00

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)

  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.