rs-runec 0.2.1

A RuneScript 2 Compiler and Linter Built Entirely in Rust
Documentation

RuneScript Compiler (runec)

A compiler for RuneScript (.rs2), the scripting language used by RuneScape's game engine. Compiles source scripts into binary script.dat/script.idx output consumed by the game server.

Prerequisites

Installation

Windows (PowerShell)

powershell -ExecutionPolicy Bypass -File install.ps1

Linux / macOS / Git Bash

chmod +x install.sh
./install.sh

This builds the compiler in release mode and installs it to ~/.runec/bin as runec. The install script adds the directory to your PATH and creates a shell alias. Restart your terminal after installation.

Usage

Compiling Scripts

runec compile -s <source-dir> -o <output-dir>

Compiles all .rs2 files in the source directory and writes script.dat and script.idx to the output directory.

# Compile with default output (./data/pack/server)
runec compile -s data/src/scripts

# Specify both source and output
runec compile -s data/src/scripts -o data/pack/server

# Provide an explicit pack directory for symbol resolution
runec compile -s data/src/scripts -o data/pack/server --pack data/pack

# Compile and run lint passes
runec compile -s data/src/scripts -o data/pack/server --lint

The compiler runs the following phases in order:

  1. Parse -- Lexes and parses all .rs2 files into an AST
  2. Symbol registration -- Registers script names, loads entity pack files (items, NPCs, interfaces, etc.), engine commands, and constants
  3. Type check -- Validates types, resolves references, and checks trigger signatures across all scripts
  4. Code generation -- Emits bytecode from the AST
  5. Pointer check -- Static analysis for active-entity pointer hazards (warnings)
  6. Lint (optional) -- Detects unused locals and unreachable code (warnings)
  7. Write output -- Writes compiled script.dat and script.idx

Linting Scripts

Run all analysis passes without writing any output:

runec lint -s <source-dir>

# With explicit pack directory
runec lint -s data/src/scripts --pack data/pack

This runs the full pipeline (parse, type-check, codegen, pointer-check, lints) and reports diagnostics. Useful for editor tooling and CI lint gates.

Development

Building from Source

cargo build

Running Tests

cargo test

Running without Installing

cargo run -- compile -s data/src/scripts -o data/pack/server
cargo run -- lint -s data/src/scripts

Library Usage

The compiler is also available as a library crate on crates.io.

Installation

cargo add rs-runec

Or add it to your Cargo.toml manually:

[dependencies]
rs-runec = "0.0.9"

Example

use std::path::Path;

// Compile scripts and write output
runec::compile(
    Path::new("data/src/scripts"),
    Some(Path::new("data/pack")),
    Path::new("data/pack/server"),
    true, // run lint passes
).unwrap();

// Lint only (no output written)
runec::lint(
    Path::new("data/src/scripts"),
    Some(Path::new("data/pack")),
).unwrap();

License

This project is licensed under the MIT License.