goscape-client

A Go port of the RuneScape 2 client (client revisions 225–274), translated from the original Java client. The goal is a faithful, line-by-line reimplementation of the original game logic in idiomatic Go, runnable natively (desktop, via GLFW + OpenGL) and in the browser (WebAssembly + WebGL).

Disclaimer. goscape-client is an unofficial, fan-made preservation and study project. It is not affiliated with, endorsed by, or associated with Jagex Ltd. "RuneScape" is a trademark of Jagex. This repository contains only original source code — no game assets, cache, or content are included or distributed. To run the client you must supply your own compatible server and game cache.

Repository layout

This repository uses a branch-per-revision layout. The default main branch holds documentation only — the runnable client lives on the rev-* branches, each targeting a specific RS2 client revision:

Branch	Client revision	Notes
rev-225	225	Base port
rev-244	244
rev-245.2	245.2
rev-254	254
rev-274	274	Latest — start here

Pick a revision branch to build and run; rev-274 is the most recent.

Requirements

• Go 1.27 or newer.
• A C toolchain and OpenGL/GLFW system libraries for the native build (the renderer uses cgo via go-gl/glfw and go-gl/gl). On Linux that means a C compiler plus the X11/Wayland and OpenGL development packages; GLFW also supports macOS and Windows. The browser build needs none of these.
• A compatible RS2 server and game cache. The client connects to an RS2-protocol server over TCP (or WebSocket) and fetches game cache data from an on-demand server. A compatible server implementation is LostCityRS / Engine-TS; pair each revision branch with the matching server revision. The defaults below assume such a server running locally.
  • The on-demand transport is revision-dependent. rev-225 fetches the cache over plain HTTP from -ondemand-server; rev-244–rev-254 use the socket-based on-demand protocol alongside an HTTP /ondemand.zip bulk path; rev-274 uses the socket protocol exclusively (streamed over the world-server connection — the HTTP /ondemand.zip path was retired). The -ondemand-server URL is still used for HTTP "codebase" fetches on every revision.

Build & run (native desktop)

git clone https://github.com/zsrv/goscape-client.git
cd goscape-client
git switch rev-274          # choose a revision branch

go build ./...              # compile

# Run against a local server using all defaults:
go run ./cmd/client

# Or specify everything explicitly:
go run ./cmd/client -node-id 10 -mem high -world-type members \
    -world-server tcp://127.0.0.1:43594 -ondemand-server http://127.0.0.1:8080

Command-line flags

Flag	Default	Description
-node-id	10	Server node id.
-mem	high	Memory mode: high or low.
-world-type	members	World type: free or members.
-world-server	tcp://127.0.0.1:43594	World server URL. Scheme tcp://, ws://, or wss://.
-ondemand-server	http://127.0.0.1:8080	On-demand (cache) server URL. Scheme http:// or https://.
-store-id †	32	Disk cache directory id (.file_store_<id>, clamped to 32–34).
-version	false	Print build version information and exit.

† -store-id is available on rev-244 and later; it does not exist on rev-225. All other flags (and their defaults) apply to every revision branch.

To connect over WebSocket (e.g. for a remote or browser-style deployment):

go run ./cmd/client -world-server wss://play.example.com:443/ws

Developer mode

Set DEVELOPER_MODE=true to surface config-type ids in the in-game Examine menus:

DEVELOPER_MODE=true go run ./cmd/client -mem high -world-type members

Build & run (browser / WebAssembly)

The client can run in a browser via its js/wasm target (syscall/js + WebGL). Game data and the WebSocket server are served from the same origin as the page; the client derives its server target from window.location automatically.

git switch rev-274

# 1. Build the wasm bundle into build/web/ (plain `go build`, no extra tooling).
make wasm

# 2. Serve it locally (maps .wasm to application/wasm, required for streaming).
make wasm-serve

# 3. Open the client, passing the non-host args via the ?argv= query parameter
#    (same -flag syntax as the desktop build; the server target is auto-derived):
#    http://localhost:8080/?argv=-node-id 10 -mem high -world-type members

Notes on the browser build:

• The server host/scheme are auto-derived from the page origin (ws:// over HTTP, wss:// over HTTPS), so — unlike the desktop build — you do not pass a server argument.
• The downloaded cache persists across page reloads via IndexedDB, with an automatic in-memory fallback when IndexedDB is unavailable (e.g. private browsing). The client id is a fixed value in this build, not a persisted per-client id.
• Audio plays through the Web Audio API (music and sound effects, pre-rendered to audio buffers). Per browser autoplay policy, sound starts after the first user interaction with the page.

To build and serve this wasm client from another Go project (e.g. a server serving its own client), see docs/wasm-embedding.md.

Documentation

Project documentation lives under docs/ on this branch:

• docs/shared/PORTING.md — the porting roadmap and Java→Go translation conventions.
• docs/shared/REFERENCES.md — upstream reference repositories (Java/TypeScript clients, server) with pinned commits.
• docs/shared/PORTING-LESSONS.md — cross-revision lessons learned.
• docs/wasm-embedding.md — building and serving the browser client from another Go module.
• docs/releasing.md — how to tag and publish a release of a revision.
• docs/rev-*/ — per-revision parity audits, rename maps, and design notes.
• docs/design/ — feature design specs and implementation plans.

Contributing

This is a translation project: the original Java client is the authoritative reference, and every Go change is expected to map to a corresponding piece of Java. Each rev-* branch also carries a CLAUDE.md with an architecture overview and the package layout. Start with docs/shared/PORTING.md for the conventions before making changes.

License

goscape-client's original Go code is released under the MIT License. Because it is a port that builds on the Lost City project's clients, see NOTICE for third-party attribution — including the reproduced MIT license of the upstream TypeScript client.

Acknowledgements

This port is indebted to the Lost City project:

• Client-Java — the deobfuscated Java RuneScape 2 client, used as the authoritative reference for the translation.
• Client-TS — the MIT-licensed TypeScript client, used both as a cross-check for ambiguous Java → Go translations and as the reference for browser/WebAssembly features that have no Java counterpart — notably developer mode, same-origin networking, IndexedDB cache persistence, and Web Audio playback behavior.