Beef bindings for Lua, inspired by LuaTinker and NLua but with heavy use of compile-time code generation. Expose Beef types and functions to Lua, and call Lua from Beef with almost no runtime reflection.
- Beef-Lua interaction made simple.
- Compile-time binding generation.
- Binding can be fully automatic or manual.
- Bidirectional function calls between
BeefandLua. - Fully compatible with
Luacoroutines and threads - First-class support for key
Beeflanguage features: - Frictionless
Beefinterop:- Tables can be used as Beef spans.
- Lua callbacks can be used as Beef delegates.
- Numeric and enum overloads can be easily disambiguated.
Warning
LuaTinker-Beef is experimental and under active development. APIs and behavior may change. Use the latest Beef nightly release for compiler compatibility.
- KeraLua-Beef for Lua 5.4.
- For Lua 5.1 or LuaJIT, use KeraLua51-Beef instead.
GameSample and Playground use Beef's bundled SDL2 bindings for windows and input, BeefGL for rendering, and SDL2_mixer for audio. Playground also uses StbImageBeef and SDL2_image to load images.
The browser version of Playground is built with Emscripten through scripts/build-wasm.ps1. Building its React interface also requires Node.js and npm. See frontend development for UI-only builds.
Create a Lua state, register a Beef type, and exchange values with a script:
public static void Main()
{
let lua = scope Lua(true);
lua.Encoding = System.Text.Encoding.UTF8;
let tinker = scope LuaTinker(lua);
tinker.AutoTinkClass<System.String>(.Shallow, name: "StringBuilder");
tinker.SetValue("name", "Ada");
tinker.SetValue("score", 10);
if (tinker.Eval("""
message = StringBuilder()
message:Append("Hello, ")
message:Append(name)
print(message) -- Hello, Ada
score = score + 5
player = { name = name, score = score }
function add(a, b)
return a + b
end
""") case .Err(let error))
{
Console.WriteLine(error);
return;
}
// Read a global, evaluate an expression, and call a Lua function.
Console.WriteLine(tinker.GetValue<int>("score").Get()); // 15
Console.WriteLine(tinker.Eval<int>("return score * 2").Get()); // 30
Console.WriteLine(tinker.Call<int, ?>("add", (2, 3)).Get()); // 5
// Read and modify a Lua table from Beef.
if (tinker.GetTable!("player") case .Ok(var player))
{
Console.WriteLine(player.GetValue<StringView>("name").Get()); // Ada
player.SetValue("score", 25);
}
Console.WriteLine(tinker.Eval<int>("return player.score").Get()); // 25
}AutoTinkClass exposes a Beef type's supported public members, including indexers. Use .Shallow to register just that type:
tinker.AutoTinkClass<System.Console>(.Shallow);
tinker.AutoTinkClass<System.String>(.Shallow, name: "StringBuilder");local text = StringBuilder()
text:Append("Hello, ")
text:Append("LuaTinker", 0, 3) -- Uses the offset and length overload.
text:AppendF(" from {}!", "Beef")
Console.WriteLine(text) -- Hello, Lua from Beef!Note
Constant fields still need explicit registration.
Use .Deep to register related types too. Registering Players below also makes Player available in Lua:
public struct Player : this(int32 Score);
public static class Players
{
public static int32 GetScore(Player player) => player.Score;
}
tinker.AutoTinkClass<Players>(.Deep);local player = Player(100)
print(Players.GetScore(player)) -- 100Use BeginClass to choose which members Lua can access from a type. The binding below gives Vector2 a constructor, writable coordinates, and a method:
public struct Vector2 : this(float x, float y)
{
public float LengthSquared() => x * x + y * y;
}
using (let vector = tinker.BeginClass<Vector2>())
{
vector.AddCtor<(float, float)>();
vector.AddVar<const "x">();
vector.AddVar<const "y">();
vector.AddMethod<const "LengthSquared">();
}local vec = Vector2(3, 4)
print(vec.x) -- 3
vec.y = 5
print(vec:LengthSquared()) -- 34AddMethod exposes the Beef addition function as Lua's Add. The script uses it to define AddThenDouble, which Beef then calls through Call. LuaTinker converts the arguments and results between Lua numbers and the int32 type.
tinker.AddMethod<function int32(int32, int32)>(
"Add", (left, right) => left + right);
if (tinker.Eval("""
function AddThenDouble(a, b)
return Add(a, b) * 2
end
print(Add(2, 3)) -- Lua calls Beef: 5.
""") case .Err(let error))
{
Console.WriteLine(error);
return;
}
// Beef calls Lua, which calls Beef again.
if (tinker.Call<int32, ?>("AddThenDouble", (4, 6)) case .Ok(let result))
Console.WriteLine(result); // 20Lua can return several values from one call. A Beef tuple receives them together, with a type for each result:
let pair = tinker.Eval<(int, bool)>("return 7, true").Get();
Console.WriteLine(pair.0); // 7
Console.WriteLine(pair.1); // TrueOnce MyBase and MyTest are registered, AddClassParent connects them in Lua. A MyTest instance can then access the inherited field a alongside its own field b.
class MyBase
{
public int a = 15;
}
class MyTest : MyBase
{
public int b = 14;
}
// Register both types and link the child to its parent.
tinker.AddClass<MyBase>();
tinker.AddClassVar<MyBase, const "a">();
tinker.AddClass<MyTest>();
tinker.AddClassCtor<MyTest>();
tinker.AddClassParent<MyTest, MyBase>();
tinker.AddClassVar<MyTest, const "b">();local test = MyTest()
print(test.a) -- 15, inherited from MyBase.
print(test.b) -- 14AddClassIndexer lets Lua read and write a Beef collection through []. For this System.Collections.List<float>, list[0] reads the first element and assigning list[1] changes the original list's second element.
List<float> values = scope .() { 1.0f, 2.0f, 3.0f };
tinker.AddMethod<delegate List<float>()>("GetList", new () => values);
tinker.AddClass<List<float>>("FloatList");
tinker.AddClassIndexer<List<float>, int>();local list = GetList()
print(list[0]) -- 1.0
list[1] = 99.0
print(list[1]) -- 99.0A value type can cross into Lua while boxed in an Object. The same Beef function can receive an existing box or a value constructed in Lua, then unbox it to calculate the vector's squared length.
tinker.AddClass<Vector2>();
tinker.AddClassCtor<Vector2, (float, float)>();
Object boxedVector = scope box Vector2(3, 4);
tinker.SetValue("vector", boxedVector);
tinker.AddMethod<function float(Object)>(
"LengthSquared", (value) => ((Vector2)value).LengthSquared());
tinker.Eval("""
print(LengthSquared(vector)) -- 25
print(LengthSquared(Vector2(5, 12))) -- 169
""").Get();Lua sequences can be passed to Beef functions taking Span<T>. The script below supplies three scores, which LuaTinker copies into a span for Sum to add together.
tinker.AddMethod<function int32(Span<int32>)>("Sum", (values) =>
{
int32 total = 0;
for (let value in values)
total += value;
return total;
});
tinker.Eval("""
scores = {10, 20, 30}
print(Sum(scores)) -- 60
""").Get();To work with the same sequence directly in Beef, use GetSpan!. Its copied storage lasts for the calling scope:
if (tinker.GetSpan!<int32>("scores") case .Ok(let scores))
{
for (let score in scores)
Console.WriteLine(score); // 10, then 20, then 30.
}RegisterDelegate lets a Lua function fill a Beef delegate parameter for the duration of the call. Here, Apply calls the supplied Lua function with 21 and returns its result.
tinker.RegisterDelegate<delegate int32(int32)>();
tinker.AddMethod<function int32(delegate int32(int32), int32)>(
"Apply", (callback, value) => callback(value));
tinker.Eval("""
print(Apply(function(value)
return value * 2
end, 21)) -- 42
""").Get();Numeric casts let Lua choose the Beef parameter type when numeric and enum overloads compete. Here, int32.cast(2) selects the multiplier overload, while the typed Difficulty constants and casts select the difficulty overload.
public enum Difficulty
{
Normal = 1,
Hard = 2
}
public static class Rewards
{
public static int32 Bonus(int64 dummy) => 0;
public static int32 Bonus(int32 multiplier) => 10 * multiplier;
public static int32 Bonus(Difficulty difficulty) =>
difficulty == .Hard ? 50 : 10;
}
tinker.AddEnum<Difficulty>("Difficulty", true); // Register typed enum constants.
using (let ns = tinker.BeginNamespace("Rewards"))
{
ns.AddMethod<Rewards, const "Bonus">();
}print(Rewards.Bonus(int32.cast(2))) -- 20
print(Rewards.Bonus(Difficulty.Hard)) -- 50
print(Rewards.Bonus(Difficulty.cast(1))) -- 10Contributions are welcome! Feel free to open an issue to report a bug or suggest a feature, or submit a pull request with your improvements.
This project is licensed under the ISC License - see the LICENSE file for details.