MaxBittker/rs-sdk

RS‑SDK – Research‑oriented starter kit for RuneScape‑style bots

What it is – RS‑SDK is an open‑source toolbox that lets you write, run, and evaluate autonomous agents (bots) in a fully emulated, RuneScape‑inspired MMO. It bundles:

a TypeScript SDK that exposes high‑level game actions (bot.*) and low‑level packet helpers (sdk.send*),
a lightweight web‑client (“botclient”) that mirrors the game state to the SDK,
a gateway that bridges the SDK and the client, and
a server emulator (derived from the LostCity 2004scape project) that runs a stripped‑down version of the game with faster leveling, infinite run energy, and no anti‑bot random events.

The whole stack runs locally or can connect to a public demo server, making it a convenient sandbox for goal‑directed program synthesis, LLM‑driven agents, and multi‑agent competition research.

Key Features

Feature	Why it matters for AI/ML research
Typed TypeScript API (`sdk/API.md`)	Gives agents a clear, auto‑documented action space; the CI checks that the public API matches the source types.
Executable script sandbox (`bots/<name>/script.ts` or `execute_code` snippets)	Agents can be written as async JavaScript/TypeScript functions that receive `bot` and `sdk` globals, enabling rapid prototyping of LLM‑generated policies.
Server modifications for fast feedback	Accelerated XP curve, infinite run energy, and disabled random events let experiments finish in minutes rather than hours.
Adjustable tickrate (`NODE_TICKRATE`)	Researchers can crank the game loop to 30 ms ticks for high‑throughput simulation or keep it realistic at 400 ms.
Leaderboard & benchmark links	A public hiscores page and a separate `rs‑bench` repo provide baseline performance numbers for different LLMs, useful for reproducibility.
Grand Exchange simulation	A simple market with taxes and a price dashboard lets you explore economic agent behavior or multi‑agent trading strategies.
Easy local deployment	Three `bun run` commands start the engine, web client, and gateway; the demo server can be used without any of them for quick tests.
Discord community	A dedicated chat for troubleshooting, sharing bots, and discussing research ideas.

Typical Use‑Cases

LLM‑driven bot synthesis – Prompt an LLM (e.g., Claude, GPT‑4) to generate a script.ts that levels a character, then run it on the emulator to measure success.
Goal‑directed program synthesis (Ralph loops, etc.) – Use the SDK as the execution environment for iterative refinement loops that propose, test, and improve action sequences.
Multi‑agent competition – Deploy several bots simultaneously; the leaderboard ranks them by total level per playtime, encouraging research on cooperation/competition dynamics.
Economic agent experiments – Interact with the Grand Exchange to study market‑making, price‑prediction, or tax‑impact strategies.
Benchmarking LLMs – Compare how different language models perform on the same tasks using the rs‑bench repository.

Getting Started (quick‑start)

# Clone the repo
git clone https://github.com/MaxBittker/rs-sdk.git
cd rs-sdk

# Install dependencies (uses bun – a fast JS runtime)
bun install

# Connect to the public demo server and create a bot
bun bots/create-bot.ts myBotName

# Run a simple script (replace with your own or an LLM‑generated one)
bun bots/myBotName/script.ts

If you prefer an LLM to write the script for you, the README shows a one‑liner:

claude "start a new bot with name: myBotName"

For full control you can spin up the local server stack:

# Engine (game logic)
cd server/engine && bun run start

# Web client (bundles the browser UI used by botclient)
cd server/webclient && bun run watch

# Gateway (SDK ↔ botclient bridge)
cd server/gateway && bun run gateway

Then point your bot at ws://localhost:7780 by leaving SERVER= empty in bots/<bot>/bot.env.

Architecture Overview

Server Engine – Runs the game world (NPCs, combat, items, Grand Exchange). Configurable tickrate and profanity filter.
Web Client (botclient) – A browser‑based client that receives world updates and forwards player actions.
Gateway – WebSocket bridge that connects the SDK instance to the botclient; each username gets its own channel.
SDK – TypeScript library that exposes bot.* high‑level helpers (e.g., bot.walkTo(x, y), bot.attack(target)) and low‑level sdk.send* packet functions. Scripts are executed in an async sandbox that receives bot and sdk globals.

Documentation & Resources

API reference – sdk/API.md (auto‑generated, kept in sync by CI).
Market guide – sdk/MARKET.md and docs/grand-exchange.md.
Learning examples – learnings/README.md contains copy‑paste scripts for common tasks.
Benchmark results – Separate repo rs-bench linked from the README.
Community – Discord link in the badge at the top of the README.

License

MIT – permissive open‑source license, allowing commercial, academic, or hobby use.

Bottom Line

RS‑SDK provides a ready‑to‑run, fully controllable MMO environment plus a typed JavaScript/TypeScript interface, making it an excellent platform for experimenting with LLM‑driven agents, program synthesis loops, and multi‑agent economics without dealing with the legal or technical constraints of the real RuneScape game.