Facepunch.Breen

Breen

Breen is a scripting language for C# applications. It looks and works like C#, because that's the idea.

Use the Facepunch.Breen package with .NET 10. Scripts run as compiled code, with inputs and C# APIs supplied by your application.

Example script

Save this as score.breen:

// A global keeps its value between runs. This initializer runs once.
[Global]
int TotalScore = 0;

// Define a struct to keep a round's data and scoring logic together.
struct RoundScore
{
    public int Kills;
    public int Bonus;

    // Structs can have methods too.
    public int Total() => Kills * 100 + Bonus;
}

// Define a function we can call for each round.
int AddRound(int kills, int bonus)
{
    // This local struct belongs to this call.
    var round = new RoundScore { Kills = kills, Bonus = bonus };

    // Call its method and add the result to our running total.
    TotalScore += round.Total();
    return TotalScore;
}

// Kills and Bonus are inputs supplied by the application.
// With 3 kills and a bonus of 5, each run adds 305 to the total.
return AddRound(Kills, Bonus);

Quick start

dotnet add package Facepunch.Breen --prerelease

using Breen;

var system = new ScriptSystem(new ScriptSystemOptions
{
    Resolver = new DefaultResolver()
});

system.SetStore("global", new ScriptStore());

var script = system.CreateScript(File.ReadAllText("score.breen"));
script.Set("Kills", 3);
script.Set("Bonus", 5);

var result = script.Run();
if (!result.Success)
{
    throw new InvalidOperationException(result.Error!.Message, result.Exception);
}

int score = script.ReturnValue.Get<int>(); // 305

[Breen.Store("global")]
[AttributeUsage(AttributeTargets.Field)]
public sealed class GlobalAttribute : Attribute { }

Keep the system and script around for repeated runs; Run() compiles on first use. Change inputs with Set() and run again. Use them sequentially on one thread.

DefaultResolver exposes public C# APIs. Supply your own IResolver to restrict which types and members scripts can access.

Features

Script.Call() invokes a top-level function and keeps initialized script state between calls. Run() reruns top-level setup. To call an object's method from C#, wrap it in a top-level script function.

Execution has a configurable instruction budget and a 128-call recursion limit. Unused function and type declarations preserve the normal execution fast paths.