Skip to main content

​
Quickstart Guide

Get up and running with SolarSharp in just a few minutes. This guide will walk you through installing SolarSharp and running your first Lua script.

​
Installation

Install SolarSharp via NuGet in your .NET project: 
dotnet add package SolarSharp.Interpreter
SolarSharp targets .NET Standard 2.0, 2.1, and .NET 9.0+, so it works with most .NET projects.

​
Your First Script

Let’s start with a simple example that demonstrates how easy it is to execute Lua code from C#.

​
Simple Factorial Example

Here’s a complete example that calculates a factorial using Lua: 
using SolarSharp.Interpreter;
using SolarSharp.Interpreter.DataTypes;

double Factorial()
{
    string script = @"    
        -- defines a factorial function
        function fact (n)
            if (n == 0) then
                return 1
            else
                return n*fact(n - 1)
            end
        end

        return fact(5)";

    LuaValue res = Script.RunString(script);
    return res.Number;
}
That’s it! With just a few lines of code, you’ve executed Lua code and retrieved the result.
The Script.RunString() method is the quickest way to run Lua code. It creates a new Script instance, executes the code, and returns the result.

​
Understanding the Basics

​
The Script Class

The Script class is the core of SolarSharp. It represents a Lua scripting session: 
using SolarSharp.Interpreter;

// Create a new script instance
Script script = new Script();

// Load and execute Lua code
LuaValue result = script.DoString("return 2 + 2");

Console.WriteLine(result.Number); // Output: 4

​
LuaValue Type

The LuaValue class represents any value in Lua. It can hold:
  • Numbers (double)
  • Strings
  • Booleans
  • Tables
  • Functions
  • And more
LuaValue numberValue = script.DoString("return 42");
Console.WriteLine(numberValue.Number); // 42

LuaValue stringValue = script.DoString("return 'hello'");
Console.WriteLine(stringValue.String); // hello

LuaValue boolValue = script.DoString("return true");
Console.WriteLine(boolValue.Boolean); // true

​
Common Usage Patterns

​
Pattern 1: Quick Execution

For simple, one-off script execution: 
// Static method for quick experimentation
LuaValue result = Script.RunString("return math.sqrt(16)");
Console.WriteLine(result.Number); // 4

​
Pattern 2: Reusable Script Instance

For multiple executions with shared state: 
Script script = new Script();

// Set a global variable
script.Globals["myVar"] = 10;

// Access it in scripts
LuaValue result = script.DoString("return myVar * 2");
Console.WriteLine(result.Number); // 20

​
Pattern 3: Loading Functions

Load a function and call it multiple times: 
Script script = new Script();

// Load a function
string luaCode = @"
    function greet(name)
        return 'Hello, ' .. name .. '!'
    end
    return greet
";

LuaValue greetFunc = script.DoString(luaCode);

// Call it multiple times
LuaValue result1 = script.Call(greetFunc, "Alice");
LuaValue result2 = script.Call(greetFunc, "Bob");

Console.WriteLine(result1.String); // Hello, Alice!
Console.WriteLine(result2.String); // Hello, Bob!

​
Working with Tables

Lua tables are the primary data structure. Here’s how to work with them: 
Script script = new Script();

// Create and populate a Lua table
string luaCode = @"
    return {
        name = 'SolarSharp',
        version = '2.0.0',
        features = {'Fast', 'Easy', 'Powerful'}
    }
";

LuaValue result = script.DoString(luaCode);
Table table = result.Table;

// Access table values
Console.WriteLine(table["name"].String);    // SolarSharp
Console.WriteLine(table["version"].String); // 2.0.0

// Access array elements (Lua arrays are 1-indexed)
Table features = table["features"].Table;
Console.WriteLine(features[1].String); // Fast

​
Error Handling

Script errors are thrown as exceptions: 
using SolarSharp.Interpreter;
using SolarSharp.Interpreter.Errors;

try
{
    Script script = new Script();
    script.DoString("return undefinedVariable");
}
catch (ScriptRuntimeException ex)
{
    Console.WriteLine($"Runtime error: {ex.Message}");
}
catch (SyntaxErrorException ex)
{
    Console.WriteLine($"Syntax error: {ex.Message}");
}
Always wrap script execution in try-catch blocks when running untrusted or user-provided code.

​
Next Steps

Now that you’ve run your first script, explore these topics:

CLR Interop

Learn how to call C# code from Lua and vice versa

Script Class

Explore the complete Script API

Working with Tables

Master Lua’s primary data structure

Coroutines

Learn about Lua coroutines and async execution

​
Complete Example

Here’s a complete console application that demonstrates various SolarSharp features: 
using System;
using SolarSharp.Interpreter;
using SolarSharp.Interpreter.DataTypes;
using SolarSharp.Interpreter.Errors;

class Program
{
    static void Main()
    {
        // Create a script instance
        Script script = new Script();
        
        // Define a Lua function
        script.DoString(@"
            function calculate(x, y, operation)
                if operation == 'add' then
                    return x + y
                elseif operation == 'multiply' then
                    return x * y
                elseif operation == 'power' then
                    return x ^ y
                else
                    return nil
                end
            end
        ");
        
        // Get the function
        LuaValue calcFunc = script.Globals["calculate"];
        
        // Call it with different operations
        var sum = script.Call(calcFunc, 5, 3, "add");
        var product = script.Call(calcFunc, 5, 3, "multiply");
        var power = script.Call(calcFunc, 5, 3, "power");
        
        Console.WriteLine($"5 + 3 = {sum.Number}");       // 8
        Console.WriteLine($"5 * 3 = {product.Number}");   // 15
        Console.WriteLine($"5 ^ 3 = {power.Number}");     // 125
    }
}
Check out the API Reference for complete documentation on all available methods and properties.

Build docs developers (and LLMs) love

Get started for freeTalk to us