rs-sdk/CLAUDE.md

RS-Agent Bot Guide

You're here to play the mmo game through the progressive development of botting scripts, starting small then adapting to your desires and ideas. It is strongly recommended to get started and make the first step towards your goals, then researching and learning as you go.

First Time Setup

Create a new bot using the setup script:

Ask the user for a bot name (max 12 chars, alphanumeric). If they skip, use the command without a username to auto-generate a random 9-character name.

# With custom username
bun bots/create-bot.ts {username}

# Auto-generate random username
bun bots/create-bot.ts

# Use local server (sets SERVER=localhost in bot.env)
bun bots/create-bot.ts {username} --local

# Use a custom server
bun bots/create-bot.ts {username} --server=myserver.example.com

This automatically creates:

• bots/{username}/bot.env - Credentials with auto-generated password
• bots/{username}/lab_log.md - Session notes template
• bots/{username}/script.ts - Ready-to-run starter script

Start a Game Client (scripts only)

Scripts (bun bots/{username}/*.ts) and bun sdk/cli.ts need a running game client; they never start one. Before running a script, start the headless lite client in the background and leave it running:

cd server/webclient && bun install && bun src/lite/runner.ts {username}

It logs Gateway connected, registering as '{username}' once it's ready. One process per bot; it exits non-zero if the game session ends. Without it, a script exits with No game client is attached. MCP execute_code doesn't need this step; it opens a browser client itself.

Quick Start

1. Install dependencies: bun install (from project root)
2. Open project in your AI coding tool — the MCP server will be available automatically
3. Control your bot with suggestions.

Tools

Tool	Description
execute_code(bot_name, code)	Run code on a bot. Auto-connects on first use.
list_bots()	List connected bots
disconnect_bot(name)	Disconnect a bot

Example

// Just execute - auto-connects on first use
execute_code({
  bot_name: "mybot",
  code: `
    const state = sdk.getState();
    console.log('Position:', state.player.worldX, state.player.worldZ);

    // Chop trees for 1 minute
    const endTime = Date.now() + 60_000;
    while (Date.now() < endTime) {
      const tree = sdk.findNearbyLoc(/^tree$/i);
      if (tree) await bot.chopTree(tree);
    }

    return sdk.getInventory();
  `,
});

See mcp/README.md for detailed API reference.

Code runs in an async context with bot (BotActions) and sdk (BotSDK) available as globals.

Reporting SDK Bugs

When the SDK has a bug or rough edge, first find a workaround, then file a report. One command, no auth, no permission needed:

bun sdk/bug-report.ts "incorrect results from bot.foo(), had to use raw sdk.sendFoo() instead for xyz reason."

Important note: The game itself is extremely well tested and complete, it's not buggy. If you can't figure out how to do something, don't blame the game, blame your assumptions and keep investigating. File a bug report after you figure out what's going on, don't just assume the game is broken because you got confused, and give up. The SDK is a thin layer on top of the game, and the game is the source of truth.

After filing the bug, keep working on your goal!

Session Workflow

This is a persistent character - you don't restart fresh each time. The workflow is:

1. Check World State First

Before writing any script, check where the bot is and what it has:

bun sdk/cli.ts {username}

This shows: position, inventory, skills, nearby NPCs/objects, and more.

Exception: Skip this if you just created the character and know it's at spawn.

Tutorial Check: If the character is in the tutorial area, call await bot.skipTutorial() before running any other scripts. The tutorial blocks normal gameplay.

2. Write Your Script

Edit bots/{username}/script_name.ts with your goal. Keep scripts focused on one task. you may write multiple scripts for different tasks and switch between them.

3. Run the Script

bun bots/{username}/script_name.ts

4. Observe and Iterate

Watch the output. After the script finishes (or fails), check state again:

bun sdk/cli.ts {username}

Record observations in lab_log.md, then improve the script.

Chatting Without Taking Control

To talk in-game (or read chat) without disturbing whatever script currently owns the bot, use the chat CLI — it connects in observe mode, which can send chat (and nothing else) and never pre-empts (or gets pre-empted by) a controller:

bun sdk/chat.ts {username} "meet me at the bank"   # send public chat
bun sdk/chat.ts {username} --to {player} "on my way"  # send a private message
bun sdk/chat.ts {username}                          # recent chat
bun sdk/chat.ts {username} --watch                  # tail live

Public chat is capped at 400 chars per message; sdk.say() auto-splits longer text into wire-safe chunks.

Private messages (sdk.dm(name, text) / sdk.sendPrivateMessage(name, msg)) reach the target anywhere in the world - no friends-list setup needed - and show up in getChat() as type 3 (received) / 6 (sent). The server accepts one social packet (say or PM) per tick; dm() paces its chunks automatically.

Script Duration Guidelines

Start short, extend as you gain confidence:

Duration	Use When
10s	New script, single actions, untested logic, debugging
30s-1 min	Validated approach, building confidence
5+ min	Proven strategy, grinding runs. USE SPARINGLY

A failed 5-minute run wastes more time than five 30 second diagnostic runs. Fail fast and start simple.

Look out for "I can't reach" messages - the solution is often to open closed gates or that the item isn't accessible.

Read and grep in the learnings/ and wiki/ folder for tips, skill guides, item and npc locations, and shop information.

SDK API Reference

For the complete method reference, see sdk/API.md (auto-generated from source).

Quick overview:

• bot.* - High-level actions that attempt to observe method-specific evidence (chopTree, walkTo, attack, etc.). Check a result when the method returns one.
• sdk.* - State queries and low-level browser-client dispatches. A successful send* result does not prove the game server applied the effect.

bot.* Quick Reference

Method	What it does
walkTo(x, z, tolerance?)	Pathfind to coords, opens doors along the way
talkTo(target)	Walk to NPC, start dialog
interactNpc(target, option?)	Walk to NPC, interact with any option (e.g. 'trade', 'fish')
interactLoc(target, option?)	Walk to loc, interact with any option (e.g. 'mine', 'smelt')
attack(target)	Walk to an NPC or player and start combat
castSpell(target, spell)	Cast a combat spell on an NPC or player
pickpocketNpc(target)	Pickpocket NPC, detects XP gain vs stun
chopTree(target?)	Chop tree, wait for logs
pickupItem(target)	Pick up ground item
openDoor(target?)	Open a door or gate
openBank()	Open nearest bank
depositItem(target, amount?)	Deposit item to bank
withdrawItem(slot, amount?)	Withdraw item from bank
closeInterface()	Close any open modal (shop, bank, book, quest scroll)
closeShop() / closeBank()	Close the shop / bank interface
openShop(target?)	Open shop via shopkeeper NPC
buyFromShop(target, amount?)	Buy item from open shop
sellToShop(target, amount?)	Sell item to open shop
equipItem(target)	Equip from inventory
unequipItem(target)	Unequip to inventory
eatFood(target)	Eat food, returns HP gained
useItemOnLoc(item, loc)	Use inventory item on loc (e.g. fish on range)
useItemOnNpc(item, npc)	Use inventory item on NPC
burnLogs(target?)	Light logs with tinderbox
fletchLogs(product?)	Fletch logs with knife
craftLeather(product?)	Craft leather with needle
smithAtAnvil(product)	Smith bars at anvil
dismissBlockingUI()	Dismiss level-up dialogs (called automatically by all actions)
navigateDialog(choices)	Auto-click through dialog options
skipTutorial()	Skip the tutorial island

sdk.* Commonly Used Directly

Method	What it does
getState()	Full world state snapshot
getSkill(name) / getSkillXp(name)	Skill info
getInventory() / findInventoryItem(pattern)	Inventory queries
findNearbyNpc(pattern) / findNearbyLoc(pattern)	Find nearby entities
findNearbyPlayer(pattern) / getNearbyPlayers()	Find other players
findGroundItem(pattern)	Find ground items
getDialog()	Current dialog state
sendClickDialog(option)	Click dialog option by its published index
clickDialogByText(pattern)	Click dialog option by label — prefer this
sendClickComponent(id)	Click interface button
sendCloseModal() / sendCloseShop()	Close the open modal / shop
sendDropItem(slot)	Drop inventory item
sendUseItem(slot)	Use inventory item (bury, etc.)
sendUseItemOnItem(src, dst)	Combine two items
say(text)	Send chat, auto-chunked past the length cap
dm(name, text)	Send a private message, auto-chunked
getChat(opts?) / getNewChat(opts?)	Read chat history (500-deep) / only unseen messages
waitForChat(opts?)	Wait for a message ({from, matching, timeout})
waitForCondition(pred)	Wait for state predicate
waitForTicks(n)	Wait n game ticks
scanNearbyLocs(radius?)	Async extended-range loc scan; must be awaited

See sdk/API.md for exact async signatures, parameter defaults, and return types.

Code environments

MCP execute_code exposes bot and sdk directly. Standalone bots/{username}/*.ts files must import runScript and receive { bot, sdk } in its callback. Do not paste runner-context expressions into execute_code.

Only one control connection should own a bot. Use observe mode for read-only monitoring, avoid overlapping action programs on the same bot, and inspect sdk.getStateAge() before acting after a disconnect or long pause.

---

Modals Hide the Inventory

A shop or bank modal replaces the inventory tab, so the server rejects inventory packets sent underneath it as "component not visible" — with no game message. Close the modal before doing anything else:

await bot.closeInterface(); // any modal
await bot.closeShop(); // shop specifically
await sdk.sendCloseModal(); // low-level

Don't click the interface's own "Close Window" component id. It's a client-side close button with no server trigger; the SDK now routes those to a close for you, but the named methods above are what to reach for.

Dialog Options Are Not In Product Order

Skill dialogs (fletching, crafting) publish four buttons per product — Make X, Make 10, Make 5, then one labelled with the product name. Arrow shafts are option 4 of 12, not option 1. Never assume ordering:

const dialog = sdk.getDialog();
console.log(dialog?.options.map((o) => `${o.index}: ${o.text}`));
await sdk.clickDialogByText(/arrow shaft/i); // or bot.fletchLogs('arrow shaft')

Dismiss Level-Up Dialogs

All BotActions methods automatically dismiss blocking UI (level-up dialogs, etc.) before executing. You don't need to call this manually in loops.

// Only needed if using low-level sdk methods directly:
await bot.dismissBlockingUI();

// Or manually check
if (sdk.getState()?.dialog.isOpen) {
  await sdk.sendClickDialog(0);
}

Error Handling

const result = await bot.chopTree();
if (!result.success) {
  console.log(`Failed: ${result.message}`);
  // Handle failure - maybe walk somewhere else
}

Project Structure

bots/
└── {username}/
    ├── bot.env        # Credentials (BOT_USERNAME, PASSWORD, SERVER)
    ├── lab_log.md     # Session notes and observations
    └── script.ts      # Current script

sdk/
├── index.ts           # BotSDK (low-level)
├── actions.ts         # BotActions (high-level)
├── cli.ts             # CLI for checking state
└── types.ts           # Type definitions

learnings/
├── banking.md
└── ...etc

wiki/
├── npcs/
├── items/
├── skills/
└── shops/

Troubleshooting

"No game client is attached" / "No state received" - No client is publishing state for the bot. Start the lite client (cd server/webclient && bun src/lite/runner.ts {username}) or open the bot's browser URL, then rerun.

"Client out of date" / "the server now runs revision N" / lite runner exits with code 3 - The game server was upgraded to a new game revision. Update your checkout (git pull, then cd server/webclient && bun install) and restart the lite runner. Browser clients only need a page reload.

Script stalls - Check for open dialogs (state.dialog.isOpen). Level-ups block everything.

"Can't reach" - Path is blocked. Try walking closer first, or find a different target.

Wrong target - Use more specific regex patterns: /^tree$/i not /tree/i (which matches "tree stump").

Everything succeeds and nothing happens - The two silent failure modes. A send* returning success only means the client wrote bytes; it is not an ack.

• The client never sent anything. The client pathfinds before every interaction, and when it can't route it returns cant_reach without writing a packet - so the server never replies "I can't reach that!" either. Check reachable on the target before using it. find* already prefers reachable matches; pass {reachable: true} to get null instead of an unreachable one.
• The server discarded the op. A refused op (mid-action, stunned, target gone or out of view, bad option) gets UNSET_MAP_FLAG and nothing else - no message, no error. A blocking modal is worse: the op is accepted and the trigger never runs. Check state.opFeedback.opRejectedCount around a send, and gate loops on an observed effect rather than on a timer.

Start small and build up!