☾ LCLite

A RuneLite-style mod layer for the Lost City / 2004Scape webclient.

_{OSRS camera · XP tracker · stat orbs · true tile · WebGPU renderer · TCG packs — press F1 in your game.
No fork. No hand-merges. Survives the next build.}

---

Warning

Do not point LCLite at Lost City's own servers. LCLite is a modified client — it changes the game code you run. Lost City's servers, and any server built on their framework, do not accept modified clients: connecting to them with LCLite is likely to get your account flagged and banned, and that is your risk, not theirs.

Play LCLite only on a world you host yourself, or on a server whose owner has explicitly said modified clients are welcome and can accept them. If you are not the host and nobody has told you yes, the answer is no.

Why

Lost City's webclient moves fast, and every update turns your hand-picked tweaks into a merge conflict. LCLite ends that. Mods live out-of-tree as identity-anchored patch hunks; you pick them once and LCLite layers them onto whatever revision you're running, verifies the result, and rebuilds. When Lost City lands code under a mod's anchor, the installer says exactly where it moved — you reseat it in minutes and every other mod applies untouched.

No game files are distributed. You bring your own Lost City installation — or any 2004Scape-lineage client (LCLite is host-agnostic).

Quick start

1. Get the launcher — one line: cd launcher && go run build.go, or grab the portable zip from Releases when one is published. It's a single ~8 MB static binary with no runtime.
2. Double-click LCLite.bat — the wizard asks which revision you want (the branch Lost City is developing right now is pre-picked), then clones, builds and starts it for you. A first boot repacks the cache, so give it a minute.
3. Press F1 in-game — every mod is a toggle, live, no reload.

After that the launcher is your dashboard: mods, extra revisions side by side, running a world, joining someone else's.

Any OS / terminal — the Node CLI

The overlay is plain scripts and runs anywhere. Nothing is cloned into this repo: the launcher installs each revision into its own data folder (%LOCALAPPDATA%\LCLite\installs\<rev>\{webclient,engine,content,lclite}, or ~/.local/share/lclite elsewhere) and drives this overlay against it.

node tools/lclite.mjs list                                    # machine-readable mod state
LCLITE_ROOT=/path/to/install node tools/lclite.mjs apply      # apply every mod
LCLITE_ROOT=/path/to/install node tools/lclite.mjs apply --check
LCLITE_ROOT=/path/to/install node tools/lclite.mjs build      # bundle + deploy client.js
LCLITE_ROOT=/path/to/install node tools/lclite.mjs doctor     # health report

An "install" is any folder holding webclient/ + engine/. Copy this repo inside one as lclite/ and the tools find it without LCLITE_ROOT.

The mods

Seventeen mods, one folder each. Names are the ones you'll read in the panel.

They are not tied to one revision. Pick 274 in the launcher instead of 289 and every mod comes with it — each of the primary corpus's anchors still matches 274's source byte-for-byte, and node tools/matrix.mjs re-verifies that claim against real clones. 254 has a corpus of its own and 6 of the 17 mods; the other eleven hook code 254 does not have yet. The launcher tells you exactly which mods a revision gets; how that works, and how a revision is added, is docs/REVS.md.

	Mod	What you notice
⚙	LCLite	The panel itself: search, favorites, per-mod settings, Alt+drag placement, fullscreen, screenshots
☾	Camera	Wheel zoom (0.4–2.6×, eased), middle-drag rotate, one-shot walk pick, chatbox scroll — the OSRS feel. It also stops the client sending the legacy mouse/camera/anticheat telemetry, so "anti-cheat off" is part of this mod now
📈	XP drops	Floating +N rows with skill icons plus a tan level-progress tracker, auto-hiding
🔮	Stat orbs	HP / Prayer / Energy orbs down the minimap's lower-left, numbers always visible; click the run orb to run, the prayer orb for the prayer book, the special attack orb to arm your special attack
🃏	TCG (beta)	Credits from xp, level-ups and kills → 5-card packs (7 tiers, foils, rare apex packs) → a 6,376-card album, cut to the cards your revision could have (1,388 of them at 289)
🟩	True tile	Three tile markers in one mod, each with its own color/border/fill: the tile the server has you on, the tile your mouse is over, and the tile you're walking to
🤬	Disable profanity filter	Chat is not censored: your own messages, other players' and private messages alike
🚀	GPU (beta)	WebGPU render of the 3D world at software-exact parity; falls back on any driver error, reason shown in the panel
🏠	Hide roofs	Roofs everywhere, not only while you stand under them
🧱	Low detail	RuneLite's Low Detail switch: untextured ground, no decorations, half-size textures
⇧	Shift-click drop	Hold Shift and left-click an item to drop it, skipping the menu
⌨	Hotkeys	F-key sidebar tabs, Esc closes interfaces, Space and 1-5 drive dialogues, WASD camera with press-enter-to-chat
📖	Wiki lookup	A wiki button on the minimap: arm it, click any NPC, object or item, and its OSRS wiki page opens
🌍	World map	A globe orb beside the wiki orb: click it and the client's own world map fills the window — labels, POI icons, spawn layers, dungeon and extra sheets, and a you-are-here marker that follows you
🏷	Ground item labels	Labels on the items lying on the ground; hold Alt to see every item and click - / + to hide or show one
🔥	True tile+	Ground effects on your true tile: flat flames licking off its border, or a ripple wave sweeping out of it
📍	Tile markers	RuneLite's Ground Markers: Shift+right-click a tile and the right-click menu gains a Mark tile / Unmark tile row. The marks are yours, they persist, and they draw only on the plane you made them on

How it works

RuneLite injects plugins into a running client. A compiled, minified TypeScript bundle can't be hot-swapped like that — so LCLite adapts the idea instead of the mechanism.

pristine upstream clone  +  this overlay  →  apply  →  bun build  →  your client

• Hunks are the durable artifact. A mod is a folder: minimal {find, replace} anchors plus plain code files. On a new rev a hunk either applies clean or names the line its anchor moved to.
• Ownership is declared, never guessed. Every added block carries a lclite:<mod> marker, so the tools route by identity with 100% precision.
• The contract is boring on purpose. Settings are localStorage keys read at each mod's own hook; the panel discovers mods from a manifest, so a new mod folder appears in-game with zero panel edits.
• Mods fail alone. A hunk that can't reseat goes quiet; the client and every other mod keep working.

When Lost City moves on

Two things move independently, and the launcher keeps them apart. LCLite — this repo: the mods, tools and page assets — is the header's Check for update, which reads the repo and turns into Update (pull it), Up-to-date (nothing to pull) or Offline (the repo could not be reached). Lost City — the client, engine and content a revision is built from — is Update from GitHub on the install. By hand:

git -C <install>/webclient pull && git -C <install>/engine pull
LCLITE_ROOT=<install> node tools/lclite.mjs apply --check   # ✗0 on every mod
LCLITE_ROOT=<install> node tools/lclite.mjs                 # picker → apply → build

A failing hunk prints ↳ where the anchor moved; fix that find[], rerun, then node tools/regen.mjs snapshots the reseat so the overlay tracks the new rev. Full walkthrough: CONTRIBUTING.md.

And when a revision moves on

Every revision LCLite supports is declared in revs.json, and node tools/matrix.mjs replays all of them over pristine clones to prove the claim is still true. A revision whose source drifted gets ported in one command:

node tools/port.mjs 254      # re-anchor the corpus, drop what will not compile there
LCLITE_ROOT=<install> node tools/regen.mjs

port.mjs prints every hunk it re-anchored and every one it could not place, with the anchor text and where that text went. Details, and the honest list of what is not ported yet: docs/REVS.md.

Custom 2004 server

Tell LCLite what your project looks like by editing root.json — the one file that declares your repo directories and remotes. Hunks reseat against your client's code like any Lost City rev, and your players install mods the same double-click way.

The launcher

LCLite.exe     single Go binary · ~8 MB · static · Windows / Linux / macOS

A front door, not a reimplementation: every mod operation still runs tools/lclite.mjs, so the overlay stays the single source of truth. It adds the revision picker (installs a branch as a self-contained folder, npm install included), "use an existing folder", the convergent mod list — one Apply changes button, because unticking a mod and applying is how a mod comes off — and the two things a terminal can't do:

• Host a world — start a Lost City server on this machine: the launcher installs the revision, picks free ports, runs the engine and opens the client.
• Join somebody else's with your client — a localhost bridge answers /client/* from your install and bridges everything else to the remote, so your mods follow you onto their world. Type an address and your client opens by itself. Nothing is negotiated with the far end, so the panel describes what you are serving and never guesses at what they are running.

Check for update in the header keeps the overlay itself current: it reads the LCLite repo, offers the pull when there is something new, and says Up-to-date or Offline when there isn't — an answer, not a failure.

The world's characters are listed under Your Server, with one button to open the save folder. A character is a file on the host's disk — the client never sees one — so that is all the launcher honestly offers; the old "save vault" that copied characters between worlds is gone (see launcher/README.md).

cd launcher && go run build.go     # → dist/LCLite-<os>-<arch>

Design notes, the HTTP API and the known limits: launcher/README.md.

For mod authors & AI agents

Making a mod — a mod is a folder in mods/, discovered by scan; the launcher lists it, applies it and strips it like every other mod, with no registry to edit.

node tools/lclite.mjs new my-thing     # copies the working layout example (mods/_template)
node tools/lclite.mjs list             # what every mod folder resolves to, here and now
node tools/selfcheck.mjs               # the drop-in contract, asserted

• docs/MAKING-A-MOD.md — the on-ramp: the folder contract, the two delivery lanes (hunks / files/ payload), how the launcher sees a mod, the loop and its gates.
• mods/_template/ — the annotated layout example new copies. Not a mod: _-prefixed folders are skipped by every reader.
• docs/MODS.md — how to author a mod (TYPE A UI / TYPE B engine / TYPE C entities), the panel↔engine contract, the ideas register.
• FOR_AGENTS_README.md — the hard rules, and the loop to follow when you're an AI session working on this repo.
• node tools/doctor.mjs — one command that machine-checks the whole overlay (hunk coverage, markers, rev pins, wording drift).
• bash tools/acceptance.sh — the strong gate: pristine clones at the pinned revs + apply must reproduce a live install byte-for-byte, then a strip/re-apply converge round-trip must land on the same bytes.

Layout

LCLite.bat / LCLite.exe   ← what players double-click
launcher/                 ← its Go source (stdlib only)
tools/                    ← lclite.mjs (apply/build/doctor) · regen.mjs (hunks) · selfcheck.mjs · acceptance.sh
mods/<name>/              ← patches/<rev>/*.json + files/ payload + README.md
mods/_template/           ← the layout example `new` copies (skipped: not a mod)
docs/                     ← MAKING-A-MOD.md, MODS.md guide, HOOKS map, architecture dossier, screens/, archive/
root.json                 ← host project layout (edit for custom servers)
FOR_AGENTS_README.md      ← read this first if you're an agent

Revisions live outside git, in the launcher's data folder (installs/<rev>/{webclient,engine,content}). tree = f(upstream@rev, overlay) still holds — the overlay just no longer has to live inside the tree it patches.

Status

CI runs two canaries weekly and on every PR — pinned revs + apply --check + structural doctor — and the launcher is built and smoke-tested on every release tag. Issues and PRs welcome: CONTRIBUTING.md · RELEASING.md.

Disclaimer

Not endorsed by, authorized by, or affiliated with the Lost City / 2004Scape project. "Lost City" and "2004Scape" are the work of their contributors under their own licenses; "RuneLite" is a trademark of the RuneLite project — the name "LCLite" and this mod-overlay concept are homages only. No game files, assets or cache data are distributed with this repository; you supply your own installation.

_{☾ — “lite”: a crescent moon cradling a lightning bolt over your old favorite client.}