Skip to content

Latest commit

 

History

History
126 lines (93 loc) · 4.13 KB

CLAUDE.md

File metadata and controls

126 lines (93 loc) · 4.13 KB

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