{"id":44737138,"url":"https://github.com/wowemulation-dev/rilua","last_synced_at":"2026-02-23T07:54:50.255Z","repository":{"id":337056894,"uuid":"1152003956","full_name":"wowemulation-dev/rilua","owner":"wowemulation-dev","description":"A zero-dependency Rust port of Lua 5.1.1 as supported in the World of Warcraft game client.","archived":false,"fork":false,"pushed_at":"2026-02-16T00:13:15.000Z","size":941,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-16T00:29:43.582Z","etag":null,"topics":["lua","lua-5-1","reverse-engineering","rust","world-of-warcraft","wow"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wowemulation-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-07T07:53:29.000Z","updated_at":"2026-02-16T00:12:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wowemulation-dev/rilua","commit_stats":null,"previous_names":["wowemulation-dev/rilua"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/wowemulation-dev/rilua","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wowemulation-dev%2Frilua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wowemulation-dev%2Frilua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wowemulation-dev%2Frilua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wowemulation-dev%2Frilua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wowemulation-dev","download_url":"https://codeload.github.com/wowemulation-dev/rilua/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wowemulation-dev%2Frilua/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29642905,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T05:21:04.652Z","status":"ssl_error","status_checked_at":"2026-02-20T05:21:04.238Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lua","lua-5-1","reverse-engineering","rust","world-of-warcraft","wow"],"created_at":"2026-02-15T20:07:10.568Z","updated_at":"2026-02-20T06:01:30.691Z","avatar_url":"https://github.com/wowemulation-dev.png","language":"Rust","readme":"# rilua\n\nA Rust implementation of [Lua 5.1.1](https://lua.org/manual/5.1/).\n\n[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue)](LICENSE-MIT)\n[![Rust Version](https://img.shields.io/badge/rust-1.92+-orange.svg)](https://www.rust-lang.org)\n\n## Overview\n\nrilua is a from-scratch Lua 5.1.1 interpreter written in Rust. It targets\nbehavioral equivalence with the PUC-Rio reference interpreter -- executed\nLua code must produce identical results.\n\nPart of the [WoW Emulation project](https://github.com/wowemulation-dev).\nZero external dependencies -- only Rust's standard library.\n\n### Use Cases\n\nrilua is built for the World of Warcraft emulation ecosystem:\n\n- **Addon development and testing** -- Run and test WoW addons outside the\n  game client without launching WoW\n- **Server-side scripting** -- Embed in private server emulators (CMaNGOS,\n  TrinityCore, AzerothCore) for scripted encounters, quests, and NPC\n  behavior\n- **Client Lua environment emulation** -- Reproduce the WoW client's Lua\n  sandbox including restricted stdlib, taint system, and WoW-specific\n  extensions (bit library, string functions, global aliases)\n- **Addon compatibility testing** -- Automated test harness for verifying\n  addons against the Lua 5.1.1 spec\n\nIt also serves as an embeddable Lua 5.1.1 interpreter for Rust applications\nand as a readable reference implementation for studying Lua internals.\nSee `docs/use-cases.md` for details.\n\n### Why Lua 5.1.1\n\nWorld of Warcraft's addon system uses Lua 5.1.1. Key 5.1-specific traits:\n`unpack` is a global (moved to `table.unpack` in 5.2), all numbers are `f64`\n(5.3 added integers), no `goto` keyword (added in 5.2). See\n[Warcraft Wiki: Lua](https://warcraft.wiki.gg/wiki/Lua).\n\n## Usage\n\n### Standalone Interpreter\n\n`rilua` reproduces the PUC-Rio `lua` command-line interface:\n\n```bash\n# Run a Lua script\nrilua script.lua\n\n# Execute a string\nrilua -e 'print(\"hello\")'\n\n# Interactive REPL\nrilua -i\n\n# All flags: -e stat, -l name, -i, -v, --, -\nrilua -v\n# Lua 5.1.1  Copyright (C) 1994-2006 Lua.org, PUC-Rio\n```\n\n### Bytecode Compiler\n\n`riluac` reproduces the PUC-Rio `luac` bytecode compiler and lister:\n\n```bash\n# Compile to bytecode\nriluac -o output.luac script.lua\n\n# List bytecode instructions\nriluac -l script.lua\n\n# Detailed listing (constants, locals, upvalues)\nriluac -l -l script.lua\n\n# Syntax check only\nriluac -p script.lua\n```\n\nBinary chunks are cross-compatible with PUC-Rio in both directions.\n\n### Embedding in Rust\n\nrilua provides a Rust-idiomatic API with `IntoLua`/`FromLua` conversion\ntraits (inspired by [mlua](https://github.com/mlua-rs/mlua)):\n\n```rust\nuse rilua::{Lua, StdLib};\n\n// Create interpreter with all standard libraries\nlet mut lua = Lua::new_with(StdLib::ALL)?;\n\n// Execute Lua code\nlua.exec(\"x = 1 + 2\")?;\n\n// Read and write globals with automatic type conversion\nlet x: f64 = lua.global(\"x\")?;\nassert_eq!(x, 3.0);\nlua.set_global(\"greeting\", \"hello\")?;\n\n// Selective library loading for sandboxing\nlet mut sandbox = Lua::new_with(StdLib::BASE | StdLib::STRING | StdLib::TABLE)?;\n```\n\nSee `docs/api.md` for the full API reference.\n\n## Supported Features\n\n### Language\n\nAll Lua 5.1.1 language features are implemented:\n\n- Variables, assignments, local declarations\n- Control flow: `if`/`elseif`/`else`, `while`, `repeat`/`until`, numeric\n  `for`, generic `for`, `break`, `return`\n- Functions: closures, varargs (`...`), multiple return values, tail calls,\n  method syntax (`obj:method()`)\n- Tables: array and hash parts, constructors (`{1, 2, key = \"val\"}`)\n- Metatables: all 17 metamethods (`__index`, `__newindex`, `__call`,\n  `__add`, `__sub`, `__mul`, `__div`, `__mod`, `__pow`, `__unm`, `__eq`,\n  `__lt`, `__le`, `__concat`, `__len`, `__gc`, `__tostring`)\n- String metatable: method syntax (`(\"hello\"):upper()`)\n- Coroutines: `create`, `resume`, `yield`, `wrap`, `status`, `running`\n- Environments: `setfenv`/`getfenv`, per-closure global tables\n- Protected calls: `pcall`, `xpcall` with error objects and stack traces\n- Error messages with variable names (matching PUC-Rio format)\n\n### Standard Libraries\n\nAll 9 standard libraries with all functions:\n\n| Library | Functions | Notes |\n|---------|-----------|-------|\n| base | 29 | `print`, `assert`, `type`, `tostring`, `tonumber`, `pairs`, `ipairs`, `next`, `select`, `unpack`, `pcall`, `xpcall`, `error`, `loadstring`, `loadfile`, `dofile`, `load`, `setmetatable`, `getmetatable`, `rawget`, `rawset`, `rawequal`, `setfenv`, `getfenv`, `collectgarbage`, `newproxy`, `_G`, `_VERSION` |\n| string | 14 | `len`, `byte`, `char`, `sub`, `rep`, `reverse`, `lower`, `upper`, `format`, `find`, `match`, `gmatch`, `gsub`, `dump`. Pattern matching with all Lua 5.1.1 features. `gfind` alias included. |\n| table | 9 | `concat`, `insert`, `remove`, `sort`, `maxn`, `getn`, `setn`, `foreach`, `foreachi`. Sort uses PUC-Rio's median-of-three quicksort. |\n| math | 28 | `abs` through `tanh`, `pi`, `huge`, `mod` alias. |\n| io | 18 | 11 library functions + 7 file methods. `stdin`/`stdout`/`stderr` handles. |\n| os | 11 | `clock`, `date`, `difftime`, `execute`, `exit`, `getenv`, `remove`, `rename`, `setlocale`, `time`, `tmpname`. |\n| debug | 14 | `getinfo`, `getlocal`, `setlocal`, `getupvalue`, `setupvalue`, `traceback`, `getregistry`, `getmetatable`, `setmetatable`, `getfenv`, `setfenv`, `gethook`, `sethook`, `debug`. |\n| package | 9 | `require`, `module`, `loaded`, `preload`, `loaders`, `config`, `path`, `cpath`, `seeall`, `loadlib`. |\n| coroutine | 6 | `create`, `resume`, `yield`, `wrap`, `status`, `running`. |\n\n### Bytecode and Compatibility\n\n- 38 register-based opcodes matching PUC-Rio encoding\n- `string.dump` and binary chunk loading\n- Binary chunks are cross-compatible with PUC-Rio (byte-identical output\n  for simple programs, loadable in both directions)\n- Non-UTF-8 source files supported (`\\255`, `\\0` in string literals)\n\n### Garbage Collector\n\nArena-based incremental mark-sweep with generational indices:\n\n- 5-state incremental collection (Pause, Propagate, SweepString, Sweep,\n  Finalize)\n- Write barriers (backward for tables, forward for upvalues)\n- `__gc` finalizers with error propagation\n- Weak tables (`__mode` = \"k\", \"v\", or \"kv\")\n- `collectgarbage()` API: collect, stop, restart, count, step, setpause,\n  setstepmul\n\n## Known Limitations\n\n### Not Yet Implemented\n\n- **`debug.debug()` interactive mode**: Stub (returns immediately).\n- **C library loading**: `package.loadlib` returns \"not supported\"\n  (incompatible ABI). Lua file loading via `require` works.\n\n### Platform Notes\n\n- **SIGINT handling**: Ctrl+C interrupts running code on Unix and Windows.\n  Second Ctrl+C terminates immediately. No-op on other platforms (e.g. WASM).\n\n### PUC-Rio Test Suite Compatibility\n\nAll 23 official Lua 5.1.1 test files pass, including the `all.lua`\nrunner which executes all tests sequentially with aggressive GC settings.\nTests: api, attrib, big, calls, checktable, closure, code, constructs,\ndb, errors, events, files, gc, literals, locals, main, math, nextvar,\npm, sort, strings, vararg, verybig.\n\nThe `all.lua` runner completes in ~3 seconds (release mode).\n\nSee `docs/testing.md` for details on running modes and the comparison\nscript.\n\n## Architecture\n\nPipeline: **Source -\u003e Lexer -\u003e Parser -\u003e AST -\u003e Compiler -\u003e Proto -\u003e VM**\n\n| Component | Description |\n|-----------|-------------|\n| Lexer | Tokenizer with one-token lookahead, byte-based (`\u0026[u8]`) |\n| Parser | Recursive descent producing typed AST |\n| Compiler | AST walker emitting register-based bytecode into Proto |\n| VM | Register-based dispatch, PUC-Rio's 38 opcodes, CallInfo chain |\n| GC | Arena-based incremental mark-sweep, write barriers, finalizers |\n| API | Trait-based Rust-idiomatic embedding (`IntoLua`/`FromLua`) |\n\nSee `docs/architecture.md` for design documentation.\n\n## Building\n\nDevelopment tools (Rust 1.92.0, markdownlint) can be installed automatically\nwith [Mise](https://mise.jdx.dev/):\n\n```bash\nmise install\n```\n\n```bash\n# Build\ncargo build\n\n# Run the interpreter\ncargo run -- script.lua\n\n# Run tests\ncargo test\n\n# Run quality gate\ncargo fmt -- --check \u0026\u0026 cargo clippy --all-targets \u0026\u0026 cargo test \u0026\u0026 cargo doc --no-deps\n```\n\n## Testing\n\nFive test layers: unit tests inside compiler and VM modules,\nintegration tests (Lua scripts with `assert()`), oracle comparison\ntests (same Lua code run in both rilua and PUC-Rio, comparing output),\nthe PUC-Rio official test suite as a compatibility target, and\nbehavioral equivalence tests for edge cases.\n\nPUC-Rio tests pass both individually and through the `all.lua` runner.\nSee `docs/testing.md` for the testing strategy and\n[lua.org/tests/](https://lua.org/tests/) for the official test\ndocumentation.\n\n## License\n\nDual-licensed under either:\n\n- MIT License ([LICENSE-MIT](LICENSE-MIT))\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))\n\n## Acknowledgments\n\n- Roberto Ierusalimschy, Waldemar Celes, and Luiz Henrique de Figueiredo for\n  [Lua](https://lua.org)\n- The [Luau](https://github.com/luau-lang/luau) team at Roblox for\n  demonstrating AST-based Lua compilation at scale\n- The [mlua](https://github.com/mlua-rs/mlua) project for Rust-idiomatic\n  Lua API patterns\n- Matthew Orlando (cogwheel) for\n  [lua-wow](https://github.com/cogwheel/lua-wow), documenting the WoW\n  client's Lua configuration\n\n## Resources\n\n- [Lua 5.1 Reference Manual](https://lua.org/manual/5.1/)\n- [PUC-Rio Lua 5.1.1 Source](https://github.com/lua/lua/tree/v5.1.1)\n- [Warcraft Wiki: Lua](https://warcraft.wiki.gg/wiki/Lua)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwowemulation-dev%2Frilua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwowemulation-dev%2Frilua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwowemulation-dev%2Frilua/lists"}