MaxBittker/rs-sdk

RS‑SDK – 為 RuneScape 風格機器人研究設計的研發起始套件

是什麼 – RS‑SDK 是一個開源工具箱，讓你能在完全模擬的 RuneScape 風格 MMO 中撰寫、執行與評估自主代理（機器人）。它包含：

一個 TypeScript SDK，提供高階遊戲操作（bot.*）與低階封包輔助函數（sdk.send*）
一個輕量級網頁客戶端（"botclient"），將遊戲狀態鏡像至 SDK
一個連接 SDK 與客戶端的閘道
一個源自 LostCity 2004scape 專案的伺服器模擬器，運行簡化版遊戲，具備加速升級、無限奔跑能量，且無反機器人隨機事件

整個架構可在本機執行，或連接至公開的示範伺服器，使其成為目標導向程式合成、LLM 驅動代理與多代理競爭研究的便捷沙盒。

主要功能

功能	對 AI/ML 研究的重要性
類型安全的 TypeScript API (`sdk/API.md`)	為代理提供清晰、自動文件化的操作空間；CI 會檢查公開 API 是否與原始碼類型一致。
可執行腳本沙盒 (`bots/<name>/script.ts` 或 `execute_code` 片段)	代理可作為接收 `bot` 與 `sdk` 全域變數的非同步 JavaScript/TypeScript 函數撰寫，便於快速原型化 LLM 生成的策略。
加速反饋的伺服器修改	加速的經驗值曲線、無限奔跑能量與禁用隨機事件，使實驗可在數分鐘內完成，而非數小時。
可調節的 tickrate (`NODE_TICKRATE`)	研究人員可將遊戲迴圈提速至 30 ms tick 以實現高吞吐量模擬，或維持 400 ms 以保持現實感。
排行榜與基準連結	公開的排行榜頁面與獨立的 `rs‑bench` 倉儲提供不同 LLM 的基準性能數據，有助於可重現性。
大交易市場模擬	一個包含稅收與價格儀表板的簡單市場，可用於探索經濟代理行為或多代理交易策略。
本地部署便捷	三個 `bun run` 命令即可啟動引擎、網頁客戶端與閘道；示範伺服器無需這些組件即可快速測試。
Discord 社群	用於故障排除、分享機器人與討論研究想法的專用聊天室。

典型使用情境

LLM 驅動的機器人合成 – 向 LLM（如 Claude、GPT‑4）提示生成 script.ts 以提升角色等級，然後在模擬器中執行以衡量成功率。
目標導向程式合成（Ralph 循環等） – 將 SDK 作為迭代優化循環（提出、測試、改進）的執行環境。
多代理競爭 – 同時部署多個機器人；排行榜按每單位遊戲時間的總等級排名，鼓勵對合作/競爭動態的研究。
經濟代理實驗 – 與大交易市場互動，研究市場做市、價格預測或稅收影響策略。
LLM 基準測試 – 使用 rs‑bench 倉儲比較不同語言模型在相同任務上的表現。

快速入門

# 克隆倉儲
git clone https://github.com/MaxBittker/rs-sdk.git
cd rs-sdk

# 安裝相依性（使用 bun – 快速 JS 執行時）
bun install

# 連接至公開示範伺服器並建立機器人
bun bots/create-bot.ts myBotName

# 執行一個簡單腳本（替換為自己的或 LLM 生成的）
bun bots/myBotName/script.ts

若希望 LLM 為你撰寫腳本，README 中提供了一行指令：

claude "start a new bot with name: myBotName"

如需完全控制，可啟動本機伺服器架構：

# 引擎（遊戲邏輯）
cd server/engine && bun run start

# 網頁客戶端（botclient 使用的瀏覽器 UI 打包）
cd server/webclient && bun run watch

# 閘道（SDK ↔ botclient 橋接）
cd server/gateway && bun run gateway

然後在 bots/<bot>/bot.env 中將 SERVER= 留空，將機器人指向 ws://localhost:7780。

架構概覽

伺服器引擎 – 運行遊戲世界（NPC、戰鬥、物品、大交易市場）。支援可設定的 tickrate 與不當言語過濾。
網頁客戶端（botclient） – 基於瀏覽器的客戶端，接收世界更新並轉發玩家操作。
閘道 – WebSocket 橋接，連接 SDK 實例與 botclient；每個使用者名稱擁有獨立通道。
SDK – TypeScript 庫，暴露 bot.* 高階輔助函數（如 bot.walkTo(x, y)、bot.attack(target)）與低階 sdk.send* 封包函數。腳本在接收 bot 與 sdk 全域變數的非同步沙盒中執行。

文件與資源

API 參考 – sdk/API.md（由 CI 自動產生並保持同步）。
市場指南 – sdk/MARKET.md 與 docs/grand-exchange.md。
學習範例 – learnings/README.md 包含常見任務的可複製腳本。
基準結果 – README 中連結的獨立倉儲 rs-bench。
社群 – README 頂部徽章中包含 Discord 連結。

授權

MIT – 允許商業、學術或個人用途的寬鬆開源授權。

總結

RS‑SDK 提供一個即開即用、完全可控的 MMO 環境，以及一個類型安全的 JavaScript/TypeScript 介面，使其成為實驗 LLM 驅動代理、程式合成循環與多代理經濟的理想平台，無需面對真實 RuneScape 遊戲的法律或技術限制。