RS-SDK

面向研究的Runescape风格机器人入门套件，包含TypeScript SDK、代理文档与绑定，以及服务器模拟器。开箱即用——只需告诉它要自动化什么！

在复杂的经济角色扮演MMO中构建和运行机器人。你可以自动化游戏进程，将一个账号练到所有技能99级，并在一个完全由机器人组成的安全环境中尝试智能体开发技术。

该项目的目标是为以目标为导向的程序合成技术（如Ralph循环等）提供丰富的测试环境，并促进对智能体之间协作与竞争的研究。

目前有一个在演示服务器上运行的机器人排行榜（https://rs-sdk-demo.fly.dev/hiscores），排名依据是每个账号在最短游戏时间内达到的总等级最高值。

有关不同LLM的评估结果，请参阅模型比较基准。

[!注意] RS-SDK是LostCity引擎/客户端的一个分支，这是一个非常出色的项目，没有它RS-SDK将无法实现。 他们的代码可以在这里找到，或者阅读他们的历史与理念。

快速开始：

git clone https://github.com/MaxBittker/rs-sdk.git

开箱即用，你可以连接到提供的演示服务器，并选择一个尚未被占用的用户名！

使用Claude Code：

bun install
claude "start a new bot with name: {username}"

手动操作：

bun install
bun bots/create-bot.ts {username}
bun bots/{username}/script.ts 

默认情况下聊天功能已关闭，以防止诈骗和提示注入攻击，但你可以在bot.env文件中通过设置SHOW_CHAT=true来启用它。

警告：演示服务器仅作为便利设施提供，我们不保证其正常运行时间和数据持久性。请谨慎对待你的账号，并考虑自行托管服务器实例。请勿在演示服务器上手动游玩。

游戏玩法修改

该服务器对原版游戏进行了一些修改，以便于开发和机器人测试：

• 更快升级 - 经验曲线加速且坡度更缓。
• 无限跑步能量 - 玩家永远不会耗尽能量。
• 无随机事件 - 禁用了反机器人随机事件。

架构：

rs-sdk运行在一个增强的基于Web的客户端（botclient）之上，该客户端连接到LostCity 2004scape服务器模拟器。

有一个网关服务器，它接受来自botclient和SDK实例的连接，并根据用户名在它们之间转发消息。 一旦连接到网关，botclient会将游戏状态传递给SDK，并执行从SDK通过网关发送的低级别动作（例如walkTo(x,y)）。

这意味着SDK不能直接与游戏服务器通信，而必须通过botclient。如果启动时未运行botclient，它将尝试自动启动。

你不需要运行网关/botclient即可在演示服务器上运行自动化脚本，但如果你正在修复bug或为rs-sdk项目添加功能，则可以选择运行它们。

在本地运行服务器

在本地运行服务器有许多优势，最主要的是可以设置较高的更新频率。

你可以在server/engine/.env文件中通过TICK_RATE变量设置更新频率（默认为600毫秒，可尝试200毫秒或30毫秒以获得更快的游戏体验，尤其适用于无头测试）。

你需要同时运行以下三个服务：

# 游戏引擎
cd server/engine && bun run start

# Web客户端打包工具
cd server/webclient && bun run watch

# 网关（连接SDK与bot客户端）
cd server/gateway && bun run gateway

网关默认监听ws://localhost:7780（可通过AGENT_PORT环境变量配置）。

2. 将机器人连接到本地网关

bot.env文件中的SERVER变量控制机器人连接的地址。要使用你的本地网关，请将SERVER留空：

BOT_USERNAME=mybot
PASSWORD=test
SERVER=
SHOW_CHAT=false

当SERVER为空时，所有连接路径（脚本、命令行）都会默认连接到ws://localhost:7780。

当SERVER设置为某个主机名（例如rs-sdk-demo.fly.dev）时，它们则会连接到wss://{SERVER}/gateway。

免责声明

这是一个免费、开源、由社区运营的项目。

其目的严格限于教育和科学研究。

LostCity服务器是在经过长时间的研究和同行评审后从零开始编写的。你所看到的一切都是完全透明的开源内容。

我们在此项工作上并未得到Jagex Ltd.的认可、授权或官方沟通。

你无法在这里玩《老派RuneScape》，购买RuneScape金币，或访问任何官方游戏的服务！在此开发的机器人将无法在官方游戏服务器上运行。

许可证

本项目采用MIT许可证。详细信息请参阅LICENSE文件。

rs-sdk 快速上手指南

rs-sdk 是一个面向研究的开源工具包，用于在类 RuneScape 的 MMO 环境中构建和运行自动化机器人（Bot）。它提供了 TypeScript SDK、代理文档绑定以及服务器模拟器，旨在为目标导向的程序合成技术及多智能体协作/竞争研究提供安全的测试环境。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (推荐 WSL2)
• Node.js 运行时: 本项目使用 bun 作为包管理器和运行时，需先安装 bun。

  curl -fsSL https://bun.sh/install | bash
  

• Git: 用于克隆代码仓库。
• 网络环境: 需要能够访问 GitHub 及项目演示服务器 (rs-sdk-demo.fly.dev)。若连接演示服务器不稳定，建议参考下文“本地部署”方案。

安装步骤

1. 克隆仓库 将项目代码克隆到本地：

   git clone https://github.com/MaxBittker/rs-sdk.git
   cd rs-sdk
   

2. 安装依赖 使用 bun 安装项目所需依赖：

   bun install
   

基本使用

您可以选择直接连接官方提供的演示服务器进行快速体验，或者在本地运行服务器以获得更稳定的开发和测试环境。

方案 A：连接演示服务器 (最快上手)

官方提供了一个公共演示服务器，无需配置即可运行 Bot。请注意：演示服务器不保证数据持久性，且禁止手动玩游戏。

方式 1：使用 Claude Code (推荐)

如果您已配置好 Claude Code 环境，可直接通过自然语言指令创建并启动 Bot：

claude "start a new bot with name: {username}"

请将 {username} 替换为您想要的唯一用户名。

方式 2：手动运行

依次执行以下命令来创建并运行脚本：

# 1. 创建新 Bot (替换 {username} 为您的用户名)
bun bots/create-bot.ts {username}

# 2. 运行 Bot 脚本
bun bots/{username}/script.ts 

注意: 默认情况下聊天功能已关闭以防止攻击。如需开启，请在生成的 bots/{username}/bot.env 文件中设置 SHOW_CHAT=true。

---

方案 B：本地运行服务器 (推荐用于开发)

本地运行允许您调整游戏速度（Tickrate），适合高频测试和功能开发。您需要同时启动三个服务：游戏引擎、Web 客户端打包器和网关。

1. 启动游戏引擎

   cd server/engine && bun run start
   

2. 启动 Web 客户端打包器 (在新终端窗口运行)

   cd server/webclient && bun run watch
   

3. 启动网关 (在新终端窗口运行) 网关负责桥接 SDK 与 Bot 客户端，默认监听 ws://localhost:7780。

   cd server/gateway && bun run gateway
   

4. 配置 Bot 连接本地网关 编辑您的 Bot 配置文件 bots/<botname>/bot.env，留空 SERVER 变量以强制连接本地网关：

   BOT_USERNAME=mybot
   PASSWORD=test
   SERVER=
   SHOW_CHAT=false
   

5. 运行 Bot 配置完成后，再次运行脚本即可连接本地服务器：

   bun bots/{username}/script.ts 
   

进阶配置：加速游戏节奏

在本地运行时，您可以通过修改 server/engine/.env 中的 TICK_RATE 变量来加快游戏速度，这对于无头测试（headless testing）非常有用。

• 默认值：600 (ms)
• 推荐测试值：200 或 30 (ms)