rs-runec 0.2.2

A RuneScript 2 Compiler and Linter Built Entirely in Rust
Documentation
<div align="center">
<pre>
██████╗ ██╗   ██╗███████╗████████╗ ██████╗██╗████████╗██╗   ██╗
██╔══██╗██║   ██║██╔════╝╚══██╔══╝██╔════╝██║╚══██╔══╝╚██╗ ██╔╝
██████╔╝██║   ██║███████╗   ██║   ██║     ██║   ██║    ╚████╔╝ 
██╔══██╗██║   ██║╚════██║   ██║   ██║     ██║   ██║     ╚██╔╝  
██║  ██║╚██████╔╝███████║   ██║   ╚██████╗██║   ██║      ██║   
╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝    ╚═════╝╚═╝   ╚═╝      ╚═╝   
</pre>
</div>

----

# 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

- [Rust 1.95+]https://www.rust-lang.org/tools/install

## Installation

### Windows (PowerShell)

```powershell
powershell -ExecutionPolicy Bypass -File install.ps1
```

### Linux / macOS / Git Bash

```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

```bash
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.

```bash
# 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:

```bash
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

```bash
cargo build
```

### Running Tests

```bash
cargo test
```

### Running without Installing

```bash
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](https://crates.io/crates/rs-runec).

### Installation

```bash
cargo add rs-runec
```

Or add it to your `Cargo.toml` manually:

```toml
[dependencies]
rs-runec = "0.0.9"
```

### Example

```rust
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](LICENSE).