rs-fleet-dashboard

A dashboard for a team of rs-sdk bots, in the style of the RuneLite client. It is a static site: no build step, no framework and no server of its own. site/ is the whole site.

The page shows:

• a live 3D view of the game world that follows one bot, or up to 16 bots at once
• a world map and a minimap with each bot as a dot
• the skills, the inventory, the worn items and the quests of each bot
• an XP tracker with XP for each hour and the time to the next level
• the hiscore ranks of each bot and the players above them
• game results, alerts and market prices in a plugin sidebar

Live example: giftedx.github.io/rs-fleet-command shows a fleet of bots on the rs-sdk demo world.

This is an independent project. It is not the RuneLite client. It is not affiliated with RuneLite or with Jagex.

Try it with demo data

You need Bun.

bun install

bun run demo

Open http://127.0.0.1:3200. The command writes demo/public.json with six made-up bots and serves the page with it. The picture above is this demo. The 3D view stays empty until you install the game cache (below).

Show your own bots

The page reads one file, public.json, from the folder that serves it. A program that writes this file is a publisher. site/shim.js loads before the page and answers each request of the page from that file.

The ready publisher

scripts/publish.ts needs no access to your bots. It reads two public sources of the game server: the world feed, and the hiscore pages. Give it the names of your bots:

bun scripts/publish.ts --names Alice,Bob --out demo

In a second terminal, serve the page with that folder:

bun run serve --data demo

The publisher writes a new file each 60 seconds. It shows where each bot is, if it is online, its levels, its hiscore ranks and the top 10 of each board.

Option	Meaning
--names a,b	The account names of your bots
--server <host>	The game server. The default is rs-sdk-demo.fly.dev
--out <folder>	Where to write public.json. The default is demo
--every <seconds>	The time between two files. The default is 60
--once	Write one file and stop

The public sources do not give inventories, worn items, quests, XP or goals. Those parts of the page stay empty.

Your own publisher

A publisher that reads your bots can fill every part of the page.

• docs/data-format.md describes each key of the file.
• scripts/make-demo.ts builds a full file in 100 lines. Start from it.

The 3D view

site/viewer/ is a build of the rs-world fork, which adds an embed API and camera flight to MaxBittker/rs-world. Its multi-view is a port of work by Stunned (TestingPurposes/rs-world). The view streams players from the world feed of the game server, so the server must run with WORLD_FEED=true.

The view needs the game cache. The cache is not in this repository.

1. Clone the rs-world fork.
2. In that folder, run yarn sync-cache. Its README gives the options for a local engine and for a remote server.
3. In this folder, run the command below.

bun scripts/install-cache.ts ../rs-world

Settings

site/config.js holds the settings.

Setting	Meaning
server	The game server. The 3D view streams wss://<server>/worldfeed. The Hiscores link opens https://<server>/hiscores.
repo	The GitHub repository (owner/name) for the owner sign-in. On <owner>.github.io/<name>/ the page takes it from the address. If there is no repository, the page is public view only.

After you change config.js or shim.js, run this command. It stamps each script link with a hash of its file, so a browser loads the new file.

bun scripts/apply-config.ts

Names in the 3D view

• site/api/our-names is a JSON list of your bot names. The 3D view draws these names in gold.
• site/api/hidden-names is a JSON list of names that the 3D view must not show. An entry is a name, or h: and the FNV-1a hash of the lower-case name as 8 hex digits.

Host it on GitHub Pages

Keep your data off the main branch. One command puts the page and your public.json on a branch named site:

bun scripts/deploy.ts --data demo

The branch holds one commit. Each run replaces it, so the branch keeps no history of your data. The command copies public.json and map.bin only. It never copies control.json.

1. Make your own repository from this one and clone it.
2. Start a publisher, so the folder has a fresh public.json.
3. Run the command above. Run it again when you want the hosted page to show new data, at most 6 times an hour. GitHub Pages builds at most 10 times an hour.
4. In the repository settings, set Pages to deploy from the branch site, folder / (root).

--dry-run builds the folder and pushes nothing. --remote and --branch name a different target.

Owner sign-in and commands

The owner can sign in on the page with a fine-grained GitHub token for the repository. The token goes to the GitHub API only. Then the page does these things:

• It reads control.json from the branch data through the GitHub API. This file can hold data that the public file must not hold.
• It writes each command as commands/<uuid>.json on main. Your publisher reads the file, applies the command and writes a receipt into control.json.

The page accepts a token only when its user is the owner of the repository. Your publisher must check each command too: the committer, the age and the id. docs/data-format.md gives the command format.

This is the beginning of the README. Read the rest at the original. Read the full README ↗