Skip to main content
The UserData class allows CLR objects to be exposed to Lua scripts. It provides a bridge between C# and Lua, enabling Lua code to interact with C# objects.

Properties

Object
object
Gets the CLR object associated with this userdata (null for static userdata).
MyClass obj = userData.Object as MyClass;
Descriptor
IUserDataDescriptor
Gets the type descriptor of this userdata.
UserValue
LuaValue
Gets or sets the “uservalue” associated with this userdata. See Lua’s debug.getuservalue and debug.setuservalue.
userData.UserValue = LuaValue.NewTable(script);

Static Configuration

DefaultAccessMode
InteropAccessMode
Gets or sets the default access mode to be used for userdata registration in the whole application.
UserData.DefaultAccessMode = InteropAccessMode.Reflection;
RegistrationPolicy
IRegistrationPolicy
Gets or sets the registration policy to be used in the whole application.

Registration Methods

RegisterType<T>
method
Registers a type for userdata interop.
returns
IUserDataDescriptor
The descriptor for the registered type
UserData.RegisterType<MyClass>();
UserData.RegisterType<SecureClass>(InteropAccessMode.HideMembers);
RegisterType
method
Registers a type for userdata interop.
returns
IUserDataDescriptor
The descriptor for the registered type
UserData.RegisterType(typeof(MyClass));
RegisterAssembly
method
Registers all types marked with MoonSharpUserDataAttribute in an assembly.
UserData.RegisterAssembly(); // Current assembly
UserData.RegisterAssembly(typeof(MyClass).Assembly);
UnregisterType<T>
method
Unregisters a type. WARNING: Use only for testing. It’s dangerous to unregister types at runtime.
UserData.UnregisterType<MyClass>();

Creation Methods

Create
method
Creates a userdata LuaValue from the specified CLR object.
returns
LuaValue
A LuaValue containing the userdata
var myObj = new MyClass();
LuaValue userData = UserData.Create(myObj);
script.Globals["myObject"] = userData;
Create(object, IUserDataDescriptor)
method
Creates a userdata LuaValue using a specific descriptor.
returns
LuaValue
A LuaValue containing the userdata
CreateStatic<T>
method
Creates static userdata for accessing static members of a type.
returns
LuaValue
A LuaValue containing static userdata
LuaValue mathType = UserData.CreateStatic<Math>();
script.Globals["Math"] = mathType;
// Now Lua can call: Math.Sqrt(16)
CreateStatic(Type)
method
Creates static userdata for the specified type.
returns
LuaValue
A LuaValue containing static userdata
LuaValue consoleType = UserData.CreateStatic(typeof(Console));
script.Globals["Console"] = consoleType;

Query Methods

IsTypeRegistered<T>
method
Determines whether the specified type is registered.
returns
bool
True if registered
if (!UserData.IsTypeRegistered<MyClass>()) {
    UserData.RegisterType<MyClass>();
}
GetDescriptorForType<T>
method
Gets the best possible type descriptor for a specified CLR type.
returns
IUserDataDescriptor
The descriptor
var descriptor = UserData.GetDescriptorForType<MyClass>(true);
GetDescriptorForObject
method
Gets the best possible type descriptor for a specified CLR object.
returns
IUserDataDescriptor
The descriptor
var obj = new MyClass();
var descriptor = UserData.GetDescriptorForObject(obj);

Extension Methods

RegisterExtensionType
method
Registers an extension type (a type containing extension methods).
UserData.RegisterExtensionType(typeof(MyExtensions));

Example Usage

using SolarSharp.Interpreter;
using SolarSharp.Interpreter.DataTypes;
using SolarSharp.Interpreter.Interop;

// Define a C# class
public class Player
{
    public string Name { get; set; }
    public int Health { get; set; }
    public int MaxHealth { get; set; }
    
    public void TakeDamage(int amount)
    {
        Health = Math.Max(0, Health - amount);
    }
    
    public void Heal(int amount)
    {
        Health = Math.Min(MaxHealth, Health + amount);
    }
}

// Register the type
UserData.RegisterType<Player>();

var script = new Script();

// Create and expose a Player instance
var player = new Player 
{ 
    Name = "Hero", 
    Health = 100, 
    MaxHealth = 100 
};

script.Globals["player"] = UserData.Create(player);

// Use from Lua
script.DoString(@"
    print(player.Name)       -- Hero
    print(player.Health)     -- 100
    
    player:TakeDamage(30)
    print(player.Health)     -- 70
    
    player:Heal(20)
    print(player.Health)     -- 90
    
    player.Health = 50       -- Direct property access
    print(player.Health)     -- 50
");

// Expose static members
UserData.RegisterType<Math>();
script.Globals["Math"] = UserData.CreateStatic<Math>();

script.DoString(@"
    local result = Math.Sqrt(16)
    print(result)  -- 4
");

// Configure access mode for security
UserData.RegisterType<SecureData>(InteropAccessMode.HideMembers);

Build docs developers (and LLMs) love