rs-runec 0.5.18

Compiler, linter, and language server for RuneScript, ClientScript, and GlobalScript, with ClientScript decompilation
Documentation

RuneScape Compiler (runec)

runec compiles RuneScript (.rs2) for the server and ClientScript (.cs2) for the client. GlobalScript (.gs2) holds code shared by both. It also provides an editor language server and a Rust library with ClientScript decompilation.

The examples assume runec is installed and on your PATH. Run commands from your project's root directory and adjust the source, pack and output paths to match your project.

Project layout

A revision has one scripts root. Organize its contents by feature or any other convention:

content/
├── scripts/
│   ├── engine.rs2
│   ├── engine.cs2
│   ├── interface_bank/
│   │   ├── scripts/bank.rs2
│   │   ├── client/bank.cs2
│   │   └── global/bank.gs2
│   ├── skill_combat/
│   └── quests/
└── pack/                 # script IDs, command opcodes and named assets

Discovery searches the whole scripts root recursively. File extensions select the target: .rs2 runs on the server, .cs2 on the client, and .gs2 is compiled for both. Folder names have no effect. Each file can contain multiple scripts. Keep existing feature names and nested source/config folders when adding client or shared scripts to a server project. Existing runescript, clientscript and globalscript folders still work; passing one of those paths resolves to its ancestor scripts root.

Configs and constants are shared by default. To restrict a file, put // @scope(server) or // @scope(client) in its leading comments. // @scope(shared) states the default explicitly. This ownership travels with the file when it moves. Shared scripts can only use shared definitions; each target can also use its own private definitions. Script ownership always comes from the extension.

Your project supplies the engine commands, asset names and script IDs. engine.rs2 and engine.cs2 declare command parameters and return types. They can be anywhere under the root; duplicate engine files are an error. Client commands follow their declared argument order. A command whose first component parameter is evaluated last uses @stack(component_last):

@stack(component_last)
[command,if_setcolour](component $component, rgb $colour)

@signature(hook_component)
@stack(component_last)
[command,if_setontimer](component $component, clientscript $callback, string $signature)

Annotations precede a command declaration and control its calling convention independently of opcode IDs. @signature accepts fixed, hook, hook_component, enum, enum_output, or param; @stack accepts component_last and requires a first component parameter. The editor highlights annotations, explains their behavior on hover, and completes annotation names and their supported values. Rust integrations set SymbolRegistry::set_component_first_command(name, true); portable command definitions use "stack": "component_last".

The pack directory maps names to IDs:

Files Purpose
command.pack Server command opcodes; server script IDs are generated in memory
cs2_command.pack and clientscript.pack Client opcodes and script IDs
Other packs, such as obj.pack and inv.pack Named assets and game data

Client opcode mappings come from the project, so there is no client revision flag to set.

Compile server scripts

runec compile --source content/scripts --pack content/pack --output data/server

This reads the server and shared scripts, checks them, and writes script.dat and script.idx. Batch compilation updates the script ID registry.

Optional flags:

Flag Effect
--lint Also report unused locals and unreachable code
--low-mem Use less memory at the cost of more compilation work

If you omit --output, server output goes to ./data/pack/server. --source and --output can also be written as -s and -o.

Compile client scripts

runec compile-client --source content/scripts --pack content/pack --output data/clientscript

This reads the client and shared scripts and writes one <id>.dat file per script. Existing IDs are preserved; successful compilation adds new scripts to clientscript.pack.

Keep explicit ID entries when renaming scripts. For example, renaming clientscript_1465 to bank_refresh requires 1465=[proc,bank_refresh] in clientscript.pack to preserve that client's script ID.

Check server scripts

runec lint --source content/scripts --pack content/pack

This reports compiler errors, pointer warnings, unused locals and unreachable code without writing bytecode output. Client diagnostics are available during compile-client and through the ClientScript language server.

Server procs and labels also warn when a direct command reads inherited last_* or find_* context. Pass event values as arguments, or initialize iterator state locally before using it. A local setter or successful guard covers only paths where it establishes that context. These warnings do not change emitted bytecode.

Use --help for all available options:

runec --help
runec compile --help
runec compile-client --help
runec lsp --help

Hooks and client callbacks

Hooks take a quoted callback expression. Arguments inside it are code, so variables, constants and nested calls work normally:

if_setontimer(bank_v2_main:com93, "bank_v2_rebuild_delayed(%varc_193)");
if_setontimer(bank_v2_main:com93, null);

The first call sets the hook; null clears it. Empty callback parentheses are optional: "callback" and "callback()" both mean no arguments.

Transmit hooks add a list of triggers inside the quotes:

if_setonvarctransmit(bank_v2_main:com21, "clientscript_1465(){varc_192, varc_1038, varc_1324}");

Use bare names in {...}. These refer to trigger IDs, not the current values of the variables. Depending on the hook, the names identify varps, integer or string varcs, inventories, or stats.

Server scripts use the same callback syntax with runclientscript:

runclientscript("playerdesign4_submit_name(0, 1, 1)");

The compiler reads ClientScript sources throughout the root to resolve callbacks and check their arguments. runclientscript takes one quoted callback; the old runclientscript* and unquoted forms are errors.

String literals inside a callback need escaped quotes:

runclientscript("show_message(\"Hello\")");

This example assumes a client callback named show_message that takes a string. The editor understands callback names, arguments and named transmit triggers for navigation, completion, highlighting and inlay hints.

Editor setup

Use your editor's LSP client to launch one runec process over stdio for each revision, with your project root as the working directory:

runec lsp --source content/scripts --pack content/pack

It loads separate server and client analysis contexts from the available engine files. Shared scripts are checked against both. Use --server or --client to restrict a process to one target when needed.

If the editor has separate fields for the executable and arguments, use runec as the executable and everything after it as the arguments. Leave initialization options blank for this directory-based setup. If the editor cannot find runec, use the full path to the installed executable.

With --source, only that revision's scripts tree, packs and supported cache asset folders belong to the server. Files from other revisions opened by project-wide search are ignored, so their script names cannot create duplicates.

Map all three script extensions to this server:

File pattern Language ID
*.rs2 rs2
*.cs2 cs2
*.gs2 gs2

The language server provides diagnostics, completion, hover, definitions, references, rename, syntax highlighting, signature help, inlay hints, formatting, quick fixes and Extract Proc. Changes refresh diagnostics in affected open files.

Inlay hints show constant types and parameter names. A parameter name appears only before a literal (number, string, boolean, null, coord) or a calc argument, in calls with more than one parameter, and only when the name says more than its type, the call's name or its numbered siblings: inv_add(bank, coins, count: 5) gets a hint, if_settext(component, "Hi") and append("a", "b") do not.

Script headers show an @requires active_player, active_npc CodeLens tag with the pointers needed on entry, including requirements inherited from proc and label calls. Pointers established inside the script are excluded; @requires none means no entry pointers are needed. The tag updates after pointer analysis finishes and does not add comments to the source. In LSP4IJ, set Settings > Inlay Hints > LSP CodeLens to Top for an author-tag layout.

Headers also show @effects may suspend; writes %variable when known effects are found. These include transitive proc/label calls, assignments to game variables, and suspension recorded in the engine's command pointer contracts. No source effect annotation is needed. Missing or ambiguous calls mark the summary incomplete; an absent tag does not promise purity. Effect summaries and pointer requirements are cached and computed during idle analysis, never by a CodeLens request. Click either header tag to open the full pointer and effect report. The compact writes label shows six entries plus +N more; clicking anywhere on that tag opens every entry. Reports use current cached analysis, including while analysis is paused. If an edit invalidates a tag, clicking it reports that analysis changed instead of showing stale results.

Click Inspect bytecode above a script header to open that script's instructions and stack effects. This link is available even when background analysis is paused. In IntelliJ/LSP4IJ it appears alongside the clickable pointer/effect tags.

To inspect just one call, select it and choose Inspect generated bytecode from the editor's code actions where available. Selection may include indentation and the trailing semicolon. The inspector compiles the containing script and shows the selected call's actual emitted instructions, including argument evaluation, and int/string/long stack pops and pushes. Highlighting a statement or block that does not identify one call shows the entire containing script, clearly labeled in the report. Selections crossing script declarations and invalid source produce a visible error. It opens a temporary Markdown document when the editor supports window/showDocument, otherwise displays a message. If opening the report fails, its contents are shown as a message instead. Unknown stack effects are explicit. Custom clients can invoke runec.inspectBytecode with [{"textDocument":{"uri":"..."},"range":{"start":...,"end":...}}] to receive the instruction rows and Markdown directly. Requesting code actions does not compile the script.

Switches without a default warn about missing boolean/intbool cases. Other finite types require an explicit domain supplied through SymbolRegistry::set_switch_values or the LSP switchValues field; ordinary integers and asset IDs remain open sets. For example, "switchValues":[{"type":"chatfilter","values":[{"value":0,"name":"on"}, {"value":1,"name":"friends"},{"value":2,"name":"off"}]}] declares a complete domain. These warnings do not change emitted bytecode.

The following controls are accepted in initializationOptions.performance or workspace/didChangeConfiguration under settings.runec.performance:

{"maxWorkers":2,"analysisPaused":false,"watchDebounceMs":300}

maxWorkers caps LSP worker concurrency (1–32; default 2), including initial project loading. analysisPaused pauses idle compilation, lints, pointer and effect analysis; navigation, completion and lightweight type diagnostics remain available. Cached hints remain visible until their source changes. watchDebounceMs combines watched-file notifications into one update (50–2000 ms; default 300), retaining unsaved buffers. Partial settings updates preserve the other values. These controls do not change CLI compiler parallelism.

Color previews show the resolved color beside supported script literals, constants, text tags and config values. The server distinguishes RGB24, RGB15, ARGB32, packed HSL16, world-map HSL32 and texture grayscale values. HSL16 previews use the client's palette conversion at gamma 0.7; client brightness can change their appearance. The color picker preserves the value's encoding and numeric notation; constant references show previews without replacing their names. Runtime expressions cannot be previewed. LSP4IJ displays these swatches automatically for files mapped to the language server.

Config and pack files use language ID rs2config for navigation and editing. Any file mapped to it opens as a config file, so add a pattern for each extension in use: *.anim, *.area, *.bas, *.billboard, *.category, *.varconbit, *.constant, *.controller, *.cursor, *.dbrow, *.dbtable, *.defaults, *.enum, *.flo, *.flu, *.fontmetrics, *.hashes, *.hitmark, *.hunt, *.idk, *.if, *.if3, *.inv, *.itemcode, *.jingle, *.jm2, *.light, *.loc, *.locshape, *.material, *.mel, *.mesanim, *.midi, *.model, *.msi, *.npc, *.obj, *.order, *.overlayinterface, *.pack, *.param, *.particleeffector, *.particleemitter, *.quest, *.quickchatcat, *.quickchatphrase, *.screen, *.seq, *.spotanim, *.stat, *.struct, *.synth, *.texture, *.varpbit, *.varc, *.varclan, *.varclansetting, *.varcon, *.varn, *.varnbit, *.varobj, *.varp, *.vars, *.wma and floorcol.txt.

*.anim;*.bas;*.category;*.config15;*.config18;*.config19;*.config20;*.config21;*.config22;*.config23;*.config24;*.config25;*.config37;*.config38;*.config39;*.config40;*.config41;*.config42;*.config43;*.varconbit;*.config45;*.config47;*.config48;*.config7;*.constant;*.cursor;*.dbrow;*.dbtable;*.enum;*.flo;*.flu;*.fontmetrics;*.hashes;*.hitmark;*.hunt;*.idk;*.if;*.inv;*.jingle;*.jm2;*.light;*.loc;*.locshape;*.material;*.mel;*.mesanim;*.midi;*.model;*.msi;*.npc;*.obj;*.order;*.overlayinterface;*.pack;*.param;*.quest;*.screen;*.seq;*.spotanim;*.stat;*.struct;*.synth;*.texture;*.varpbit;*.varc;*.varclansetting;*.varn;*.varp;*.vars;*.billboard;*.controller;*.defaults;*.area;*.if3;*.itemcode;*.particleeffector;*.particleemitter;*.quickchatcat;*.quickchatphrase;*.varclan;*.varcon;*.varnbit;*.varobj;*.wma;*.fm;*.fms;floorcol.txt

Optional syntax color settings:

The language server does not write source files or ID packs. Restart the configured servers after updating runec so they load the new executable.

Rust integrations

The package is rs-runec; Rust imports use runec.

[dependencies]
rs-runec = "0.5"

Use Project to manage source documents in memory:

Method Purpose
open / update / close Manage source documents
analyze Parse, register symbols and check types
check Also check code generation, pointers and lints
compile Return compiled artifacts and diagnostics

The host supplies a SymbolRegistry and owns storage and script ID persistence. EngineProfile describes engine-specific triggers and pointer rules.

For ClientScript tools, use Format for opcode mappings, Script::decode for binary decoding, and the decompiler for source generation. Decompilation is a library API, not a CLI command.

Custom LSP hosts can run runec lsp without --source and supply their environment through initializationOptions. See project_from_json for the supported fields.

License

MIT.