Lua-CSharp/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Lua-CSharp is a high-performance Lua interpreter implemented in C# for .NET and Unity. It provides a Lua 5.2 interpreter with async/await integration, Source Generator support for easy C#-Lua interop, and Unity support.

Common Development Commands

Building

# Build entire solution
dotnet build

# Build in Release mode
dotnet build -c Release

# Build specific project
dotnet build src/Lua/Lua.csproj

Running

Write lua to sandbox/ConsoleApp1/test.lua, then:

# Run simple tests
dotnet run --project sandbox/ConsoleApp1/ConsoleApp1.csproj

# For pattern matching testing, you can run specific Lua scripts like:
# echo 'print(string.gsub("hello", "()l", function(pos) return "[" .. pos .. "]" end))' > sandbox/ConsoleApp1/test.lua
# echo 'print(string.gsub("abc", "", "."))' > sandbox/ConsoleApp1/test.lua  
# echo 'print(string.gsub("(hello) and (world)", "%b()", function(s) return s:upper() end))' > sandbox/ConsoleApp1/test.lua

Testing

# Run all tests
dotnet test

# Run tests with detailed output
dotnet test --logger "console;verbosity=detailed"

# Run specific test project
dotnet test tests/Lua.Tests/Lua.Tests.csproj

Benchmarking

# Run performance benchmarks
dotnet run -c Release --project sandbox/Benchmark/Benchmark.csproj

Packaging

# Create NuGet package
dotnet pack -c Release

Architecture Overview

Core Components

1. Lua Runtime (src/Lua/)

   • LuaState.cs: Main entry point for Lua execution
   • LuaValue.cs: Represents values in Lua (nil, boolean, number, string, table, function, userdata, thread)
   • Runtime/LuaVirtualMachine.cs: Core VM implementation that executes Lua bytecode
   • Runtime/OpCode.cs, Runtime/Instruction.cs: VM instruction definitions
   • CodeAnalysis/: Lexer, parser, and compiler that converts Lua source to bytecode

2. Source Generator (src/Lua.SourceGenerator/)

   • Generates code for classes marked with [LuaObject] attribute
   • Enables seamless C#-Lua interop by auto-generating wrapper code
   • Key file: LuaObjectGenerator.cs

3. Standard Libraries (src/Lua/Standard/)

   • Implementations of Lua standard libraries (math, string, table, io, etc.)
   • Entry point: OpenLibsExtensions.cs

Key Design Patterns

1. Async/Await Integration

   • All Lua execution methods are async (DoStringAsync, DoFileAsync)
   • LuaFunction can wrap async C# methods
   • Enables non-blocking execution of Lua scripts

2. Value Representation

   • LuaValue is a discriminated union struct
   • Implicit conversions between C# and Lua types
   • Zero-allocation for primitive types

3Memory Management

• Heavy use of object pooling (Pool.cs, PooledArray.cs, PooledList.cs)
• Stack-based value types where possible
• Careful management of closures and upvalues

Unity Integration (src/Lua.Unity/)

• Custom asset importer for .lua files
• Integration with Unity's Resources and Addressables systems
• Works with both Mono and IL2CPP

Testing Structure

• Unit tests in tests/Lua.Tests/
• Lua test suite from official Lua 5.2 in tests/Lua.Tests/tests-lua/
• Benchmarks comparing with MoonSharp and NLua in sandbox/Benchmark/

Important Notes

• The project targets .NET Standard 2.1, .NET 6.0, and .NET 8.0
• Uses C# 13 language features
• Heavy use of unsafe code for performance
• Strings are UTF-16 (differs from standard Lua)

TODO

• ILuaStream Interface Changes: The ILuaStream interface has been updated with new methods:
  • Added IsOpen property to track stream state
  • Added ReadNumberAsync() for reading numeric values (supports formats like "6.0", "-3.23", "15e12", hex numbers)
  • Changed ReadLineAsync() to accept a keepEol parameter for controlling line ending behavior
  • Renamed ReadStringAsync() to ReadAsync()
  • Added CloseAsync() method for async stream closing
  • ✅ Implemented ReadNumberAsync() in all implementations
  • Need to properly implement the keepEol parameter in ReadLineAsync() for TextLuaStream