MaxBittker/rs-sdk

RS‑SDK – RuneScape 스타일 봇을 위한 연구 중심 스타터 킷

무엇인가요 – RS‑SDK는 오픈소스 도구상자로, 완전히 에뮬레이트된 RuneScape 스타일 MMO에서 자율 에이전트(봇)을 작성하고 실행하며 평가할 수 있게 해줍니다. 다음을 포함합니다:

고수준 게임 동작(bot.*)과 저수준 패킷 헬퍼(sdk.send*)를 노출하는 TypeScript SDK
게임 상태를 SDK에 미러링하는 가벼운 웹클라이언트("botclient")
SDK와 클라이언트를 연결하는 게이트웨이
LostCity 2004scape 프로젝트에서 파생된 서버 에뮬레이터로, 빠른 레벨업, 무한한 런 에너지, 그리고 봇 방지 랜덤 이벤트 없이 단순화된 게임 버전을 실행

이 모든 스택은 로컬에서 실행하거나 공개된 데모 서버에 연결할 수 있어, 목표 지향적 프로그램 합성, LLM 기반 에이전트, 다중 에이전트 경쟁 연구를 위한 편리한 사전 환경을 제공합니다.

주요 기능

기능	AI/ML 연구에서의 중요성
타입 안전한 TypeScript API (`sdk/API.md`)	에이전트에게 명확하고 자동 문서화된 행동 공간을 제공하며, CI가 공개 API가 소스 타입과 일치하는지 확인합니다.
실행 가능한 스크립트 사전 환경 (`bots/<name>/script.ts` 또는 `execute_code` 스니펫)	에이전트는 `bot`과 `sdk` 전역 변수를 받는 비동기 JavaScript/TypeScript 함수로 작성 가능해 LLM 생성 정책의 빠른 프로토타이핑이 가능합니다.
빠른 피드백을 위한 서버 수정	가속된 경험치 곡선, 무한한 런 에너지, 랜덤 이벤트 비활성화로 실험이 수분 내에 완료되어 수시간이 아닌 빠르게 진행됩니다.
조정 가능한 타이크 레이트 (`NODE_TICKRATE`)	연구자는 게임 루프를 30 ms 타이크로 높여 고처리량 시뮬레이션을 수행하거나, 400 ms로 현실적인 상태를 유지할 수 있습니다.
리더보드 및 벤치마크 링크	공개된 히스코어 페이지와 별도의 `rs‑bench` 리포지토리가 다양한 LLM의 기준 성능 수치를 제공하여 재현 가능성을 높입니다.
그랜드 엑스체인지 시뮬레이션	세금과 가격 대시보드를 갖춘 간단한 시장으로, 경제적 에이전트 행동이나 다중 에이전트 거래 전략을 탐색할 수 있습니다.
로컬 배포 용이성	`bun run` 명령어 3개로 엔진, 웹클라이언트, 게이트웨이를 시작할 수 있으며, 데모 서버는 이들 없이도 사용 가능해 빠른 테스트가 가능합니다.
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, 전투, 아이템, 그랜드 엑스체인지 포함 게임 세계를 실행. 타이크 레이트와 부적절한 언어 필터 조정 가능.
웹 클라이언트 (botclient) – 웹 기반 클라이언트로 세계 업데이트를 수신하고 플레이어 행동을 전달.
게이트웨이 – WebSocket 브리지로 SDK 인스턴스와 botclient를 연결. 각 사용자 이름에 고유한 채널이 할당됨.
SDK – bot.* 고수준 헬퍼(예: bot.walkTo(x, y), bot.attack(target))와 저수준 sdk.send* 패킷 함수를 노출하는 TypeScript 라이브러리. 스크립트는 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 인터페이스를 제공하여, 실제 RuneScape 게임의 법적·기술적 제약 없이 LLM 기반 에이전트, 프로그램 합성 루프, 다중 에이전트 경제 실험에 최적의 플랫폼을 제공합니다.