mruby/cs

MRubyCS is a pure C# mruby virtual machine designed for seamless integration with C# game engines. It combines high Ruby-level compatibility with the performance and extensibility of modern C#.

Easily embed Ruby into Unity or .NET—empowering users to script game logic while keeping your core engine in C#.

[!NOTE] VitalRouter.MRuby provides a high-level framework for integrating MRubyCS with Unity (and .NET, including command routing and script lifecycle management.

Why MRubyCS?

• Zero native dependencies — runs anywhere Unity/.NET runs. No per-platform native builds to maintain.
• High performance — leverages .NET JIT, GC, and modern C# optimizations with minimal overhead.
• Ruby compatible — all opcodes implemented; passes mruby's official test suite
  • Syntax, Literals, Lang, Methods, Module, Exception, ...
  • Supported Types: Array, Class, Fiber, Float, Hash, Integer, Module, Nil, Proc, Random, Range, Symbol, String, Time
• Fiber & async/await — suspend Ruby execution and await C# async methods without blocking threads.
• Prism-based compiler — uses mruby-compiler2, the next-generation mruby compiler built on Prism (the official CRuby parser), for more accurate and modern Ruby syntax support.

Performance

In the .NET JIT environment, execution speeds are equal to or faster than the original native mruby.

<img width="594" height="389" alt="ss 2026-03-04 22 11 01" src="https://github.com/user-attachments/assets/00cd3644-e460-4b21-a41e-661d484fe30c" />

The above results were obtained on macOS with Apple M4 over 10 iterations.

Please refer to the following for the benchmark code.

Limitations

• As of mruby 3.3, almost all bundled classes/methods are supported.
  • Support for extensions split into mrbgems remains limited.
  • Some methods/specs added in 3.4 are not yet covered.
• However, basic private/protected visibility is already supported.

Table of Contents

• Installation
  • NuGet
  • Unity
• Basic Usage
  • MRubyState Lifecycle
  • MRubyValue
    • Symbol/String
    • Array/Hash
    • Embedded custom C# data into MRubyValue
  • Define ruby class/module/method by C#
    • Error handling & validation in C# methods
    • Constants
  • Call ruby method from C# side
    • Send with block / keyword arguments
    • Type conversion & introspection
    • Instance variables / class variables
    • Clone / Dup / Freeze
• Compiling Ruby source code
  • MRubyCS.Compiler.Cli (dotnet tool)
  • MRubyCS.Compiler (library)
• Fiber (Coroutine)
• MRubyCS.Serializer

Installation

NuGet

| Package | Description | Latest version | |:----------|:---------------|----------------| | MRubyCS | Main package. A mruby vm implementation. | | | MRubyCS.Compiler | Compile ruby source code utility. (Native binding) | | | MRubyCS.Compiler.Cli | dotnet tool for compiling Ruby source to bytecode | | | MRubyCS.Serializer | Converting Ruby and C# Objects Between Each Other | |

Unity

[!NOTE] Requirements: Unity 2021.3 or later.

1. Install NuGetForUnity.
2. Install following packages via NugetForUnity
   • Utf8StringInterpolation
   • MRubyCS
   • (Optional) MRubyCS.Serializer
3. (Optional) To install utilities for generating mrb bytecode, refer to the Compiling Ruby source code section.

Basic Usage

MRubyState Lifecycle

MRubyState is the central object that holds the entire Ruby VM — symbol table, built-in classes, call stack, and all runtime state.

// Create a new VM instance.
var mrb = MRubyState.Create();

// Or, with additional configuration.
var mrb = MRubyState.Create(state =>
{
    state.DefineMethod(state.KernelModule, state.Intern("puts"u8), (s, self) =>
    {
        Console.WriteLine(s.GetArgumentAt(0));
        return MRubyValue.Nil;
    });
});

• No Dispose needed — MRubyState is fully managed by .NET GC. No native resources to release.
• Not thread-safe — each MRubyState instance must be used from a single thread. For multi-threaded scenarios, create a separate instance per thread.

MRubyState exposes all built-in Ruby classes as properties, which are used for class definitions, type checks, and method definitions:

| Property | Ruby class | Property | Ruby class | |:---------|:-----------|:---------|:-----------| | BasicObjectClass | BasicObject | IntegerClass | Integer | | ObjectClass | Object | FloatClass | Float | | ClassClass | Class | TrueClass | TrueClass | | ModuleClass | Module | FalseClass | FalseClass | | KernelModule | Kernel | NilClass | NilClass | | StringClass | String | SymbolClass | Symbol | | ArrayClass | Array | ProcClass | Proc | | HashClass | Hash | FiberClass | Fiber | | RangeClass | Range | ExceptionClass | Exception | | | | StandardErrorClass | StandardError |

[!TIP] Option A is recommended for production. Option B is convenient for development and prototyping.

Option A: Pre-compile bytecode

Pre-compiling Ruby source to .mrb bytecode keeps the native compiler out of your production deployment. You can use either the CLI tool or the C# API.

A-1. CLI tool

dotnet tool install -g MRubyCS.Compiler.Cli
mruby-compiler fibonacci.rb -o fibonacci.mrb

[!TIP] For local tool installation, use dotnet tool install MRubyCS.Compiler.Cli and run with dotnet mruby-compiler.

A-2. C# API

using MRubyCS;
using MRubyCS.Compiler;

var mrb = MRubyState.Create();
var compiler = MRubyCompiler.Create(mrb);

var source = """
    def fibonacci(n)
      return n if n <= 1
      fibonacci(n - 1) + fibonacci(n - 2)
    end

    fibonacci 10
    """u8;

// Compile and save as .mrb file
using var compilation = compiler.Compile(source);
File.WriteAllBytes("fibonacci.mrb", compilation.AsBytecode());

Execute pre-compiled bytecode

using MRubyCS;

var mrb = MRubyState.Create();
var bytecode = File.ReadAllBytes("fibonacci.mrb");
var result = mrb.LoadBytecode(bytecode);

result.IntegerValue //=> 55

Option B: Using Compiler library (runtime compile)

dotnet add package MRubyCS
dotnet add package MRubyCS.Compiler

using MRubyCS;
using MRubyCS.Compiler;

var mrb = MRubyState.Create();
var compiler = MRubyCompiler.Create(mrb);

var result = compiler.LoadSourceCode("""
    def fibonacci(n)
      return n if n <= 1
      fibonacci(n - 1) + fibonacci(n - 2)
    end

    fibonacci 10
    """u8);

result.IntegerValue //=> 55

[!NOTE] MRubyCS.Compiler includes native binaries. See Compiling Ruby source code for supported platforms.

Irep

You can also parse bytecode in advance. The result is called Irep in mruby terminology. Pre-parsing is useful when you want to execute the same