# OSRS Codex — Universal Action Grammar

The action grammar is the **bridge** between codex entries (client-agnostic)
and real scripts (client-specific). An entry never names a client API; it
uses a **verb** from this file. Each agent maintains the mapping table for
its own client.

A `verb` is one primitive, atomic capability. Compound behaviour is built by
chaining verbs in the entry's `actions[]` list and wiring the state machine.

Legend for the mapping table:
- `DB`  = DreamBot (tblkit / OSBot-style Java)
- `MB`  = Microbot
- `RL`  = RuneLite plugin
- `—`   = not expressible as a single primitive; entry should decompose.

> Columns are filled by each client owner as their client support lands.
> `—` is a legal value: it means "decompose into smaller verbs."

---

## A. World / presence

| verb            | meaning                                        | DB           | MB          | RL |
|-----------------|------------------------------------------------|--------------|-------------|----|
| `login`         | authenticate the account                       | —            | —           | —  |
| `select_world`  | join a specific world by id/type               | —            | —           | —  |
| `hop_world`     | switch worlds (F2P or P2P hop)                 | —            | —           | —  |
| `is_logged_in`  | predicate: authenticated & in-game             | —            | —           | —  |

## B. Movement

| verb            | meaning                                          | DB | MB | RL |
|-----------------|--------------------------------------------------|----|----|----|
| `move_to`       | get to a named location (teleport-or-walk)       | —  | —  | —  |
| `walk_to`       | path-walk to a tile                              | —  | —  | —  |
| `teleport`      | use a teleport (spell/item/scroll/portal)        | —  | —  | —  |
| `enter_region`  | assert we are inside a named area (predicate)    | —  | —  | —  |
| `open_door`     | open/lock an interactable door                   | —  | —  | —  |

## C. Interaction (the core)

| verb               | meaning                                            | DB | MB | RL |
|--------------------|----------------------------------------------------|----|----|----|
| `use_item_on`      | use inventory item `X` on target `Y` (or itself)   | —  | —  | —  |
| `click_object`     | left-click a world object (NPC/NPC tile/thing)     | —  | —  | —  |
| `right_click`      | click a specific menu option on a target           | —  | —  | —  |
| `talk_to`          | open an NPC dialogue and pick a line               | —  | —  | —  |
| `click_button`     | click a UI widget by stable reference              | —  | —  | —  |
| `menu_option`      | select from an in-game menu (F-keys, menus)        | —  | —  | —  |

## D. Inventory / bank

| verb               | meaning                                            | DB | MB | RL |
|--------------------|----------------------------------------------------|----|----|----|
| `bank_inventory`   | open bank, deposit/withdraw per params, close      | —  | —  | —  |
| `deposit_all`      | deposit every bankable item                        | —  | —  | —  |
| `withdraw`         | withdraw a named item up to a quantity             | —  | —  | —  |
| `has_item`         | predicate: inventory holds item ≥ qty              | —  | —  | —  |
| `count_item`       | read inventory quantity of an item                 | —  | —  | —  |
| `move_to_inv`      | move item from bank/ground into inventory          | —  | —  | —  |
| `sort_inventory`   | reorder inventory into a known layout              | —  | —  | —  |

## E. Exchange (Grand Exchange)

| verb               | meaning                                            | DB | MB | RL |
|--------------------|----------------------------------------------------|----|----|----|
| `ge_open`          | open GE at a bank                                  | —  | —  | —  |
| `ge_buy`           | buy `qty` of `item` at offer price, paced          | —  | —  | —  |
| `ge_sell`          | sell `qty` of `item`, confirm                      | —  | —  | —  |
| `ge_cancel`        | abort an offer (quote_age_policy only — stale edge or strategy reallocation, never a 4h limit-window reset): BUY — filled items + refunded CASH (unspent remainder) enter the GE COLLECTION BOX; SELL — unsold units + proceeds received so far enter the box; NEVER directly to inventory; the 4h buy limit is NOT renewed | —  | —  | —  |
| `ge_offers_done`   | predicate: no pending buy/sell offers              | —  | —  | —  |
| `ge_collect`       | withdraw from the GE collection box: bought (filled) items, refunded CASH, unsold units, sale proceeds; reconcile the SIDE-AWARE per-slot ledger (buy: quoted = filled + still_open + cancelled_unfilled; sell: quoted = sold + still_open + returned_unsold) before any slot reuse; a completed cycle closes with the ledger reconciled + ARCHIVED and the same pass releases the physical slot to free (`closed -> free` archival transition), so the slot immediately runs the next flip (governor 10471) | —  | —  | —  |
| `ge_check_price`   | read current buy/sell price of an item             | —  | —  | —  |

## F. Combat

| verb               | meaning                                            | DB | MB | RL |
|--------------------|----------------------------------------------------|----|----|----|
| `attack`           | start/continue attacking a target                  | —  | —  | —  |
| `prayer`           | toggle a prayer on/off                             | —  | —  | —  |
| `buff`             | apply a buff item/potion                           | —  | —  | —  |
| `eat`              | heal when HP < threshold                           | —  | —  | —  |
| `retreat`          | disengage and reposition                            | —  | —  | —  |
| `is_dead`          | predicate: account is dead                         | —  | —  | —  |
| `respawn`          | return to a spawn/bank after death                  | —  | —  | —  |

## G. Observation (predicates)

Predicates return a boolean and drive `state_machine.transitions`. They are
**free** (no anti-ban cost) and may be polled every tick.

| verb             | meaning                                  |
|------------------|------------------------------------------|
| `is_at`          | at a named location                      |
| `has_item`       | inventory holds item ≥ qty               |
| `item_count`     | quantity of an item in inv/bank          |
| `level_is`       | a skill is at/above a level              |
| `xp_is`          | a skill's xp at/above a threshold        |
| `hp_is`          | HP below a threshold                     |
| `is_dead`        | dead                                     |
| `ge_clear`       | no pending GE offers                     |
| `bank_open`      | a bank is open                           |
| `quest_state`    | a quest is started/completed             |
| `npc_present`    | a named NPC is in range/visible          |

## H. Housekeeping / safety

| verb            | meaning                                          | DB | MB | RL |
|-----------------|--------------------------------------------------|----|----|----|
| `log`           | write a sentinel log line (RESULT/DONE/ERROR)    | —  | —  | —  |
| `alert`         | raise a humanised alert (operator inbox)         | —  | —  | —  |
| `sleep`         | humanised pause `delay:[min,max]`                | —  | —  | —  |
| `human_move`    | anti-ban mouse wander / cursor nudge             | —  | —  | —  |
| `take_break`    | scheduled AFK pause (run_control.break)          | —  | —  | —  |

---

## Parameter conventions

`params` are key/value and client-agnostic. Recognised keys:

- `location` — a **named** place. Must resolve to a real, named OSRS
  location (never a bare coordinate in the entry; coordinates live in the
  client mapping).
- `item` / `on` — canonical item names (exact wiki names).
- `qty`, `buffer` — counts.
- `method` — ordered preference list for how to achieve the verb
  (e.g. `[teleport, walk]`); the client tries in order.
- `menu`, `option` — the exact right-click/option string.
- `price` / `max_price` — GP ceiling for a GE buy (anti-loss).
- `threshold` — a level/xp/hp cutoff for predicates and `eat`.

## Anti-ban hints (optional, per action)

- `delay: [min, max]` — randomised ms to sleep after the action.
- `mouse` — free-text humanisation directive (wander, jitter, bezier).
- `jitter` — randomise click offset in px.

These are **hints**, not guarantees. The translating agent may strengthen
them, never weaken a codex-mandated value.