NicyRuntime

A blazing-fast Luau runtime environment with a modular architecture. Built in Rust.

NicyRuntime is a high-performance runtime for executing Luau scripts — Roblox’s gradual typing dialect of Lua. It’s designed for embedding in applications, game engines, or any system that needs a fast, sandboxable scripting layer.

Why NicyRuntime?

⚡ Performance

Built entirely in Rust, NicyRuntime leverages the safety and speed of systems-level programming. With optional Luau CodeGen/JIT support, your scripts compile to native machine code at runtime for maximum performance.

🔌 Dynamic Library Architecture

The core runtime is a cdylib (dynamic library) that can be loaded at runtime by any host application. This means:

• Zero coupling: Your host app doesn’t need to link against the runtime at compile time
• Hot-reloadable: Update the runtime without recompiling your host
• Language agnostic: Embed from C, C++, Rust, Python, Node.js — anything with C FFI support

📦 Custom Module Resolver

A sophisticated require() implementation with:

• Smart caching based on file fingerprint (mtime + size)
• .luaurc alias support with directory tree inheritance
• Circular dependency detection with clear error messages
• Concurrent loading support with cooperative yielding
• Bytecode priority (.luauc > .luau > .lua)

🔄 Async Task Scheduler

Cooperative multitasking built on Luau coroutines:

task.spawn(function()
    print("Running concurrently!")
end)

local id = task.delay(2.0, function()
    print("Delayed execution")
end)

task.wait(1.0)  -- Non-blocking wait

task.cancel(id) -- Cancel a delayed task

🌍 Cross-Platform

Pre-built binaries for every major platform:

🛡️ Robust Error Handling

• Concise errors by default — clean, readable output
• Verbose mode via NICY_VERBOSE_ERRORS=1 — full stack traces with require chain tracking
• SEH crash protection on Windows for runtime.loadlib()
• Memory safety with complete static state cleanup between runtime calls

Architecture Overview

Host Application (C / C++ / Rust)
         │
         ▼
┌───────────────────────────┐
│   nicyruntime (cdylib)    │
│                           │
│  ┌───────────────────┐    │
│  │  Luau VM          │    │
│  │  (mlua-sys)       │    │
│  │  + CodeGen (JIT)  │    │
│  └───────────────────┘    │
│                           │
│  ┌───────────────────┐    │
│  │  Module Resolver  │    │
│  │  + Cache System   │    │
│  └───────────────────┘    │
│                           │
│  ┌───────────────────┐    │
│  │  Task Scheduler   │    │
│  │  (coroutines)     │    │
│  └───────────────────┘    │
│                           │
│  ┌───────────────────┐    │
│  │  Error Reporter   │    │
│  └───────────────────┘    │
└───────────────────────────┘
         ▲
         │
┌───────────────────────────┐
│   nicy (CLI)              │
│   Dynamic loader + router │
└───────────────────────────┘

Project Structure

NicyRuntime/
├── Runtime/              # Core cdylib library
│   ├── src/
│   │   ├── lib.rs                # Main entry point, FFI
│   │   ├── require_resolver.rs   # Custom module resolver
│   │   ├── task_scheduler.rs     # Async task scheduler
│   │   ├── ffi_exports.rs        # 65+ C-ABI Lua API wrappers
│   │   └── error.rs              # Error reporting system
│   └── tests/            # Luau test suite (32 files)
├── Nicy/                 # CLI executable
│   └── src/main.rs       # Dynamic loading & routing
├── build.ps1             # Multi-platform build script
└── Docs/                 # This documentation site

Quick Links

• Getting Started — Install and run your first script
• CLI Reference — All nicy commands
• Runtime API — FFI functions for embedding
• FFI Reference — Complete Lua C API wrapper docs
• Guides — Practical tutorials

License

NicyRuntime is licensed under the Mozilla Public License Version 2.0 (MPL 2.0).

Source Code · Releases · Report Bug