# MoonSharp for .NET and Unity: Lua scripting with debugger support

> MoonSharp embeds Lua in .NET, Mono, Xamarin and Unity applications through a C# interpreter with CLR interop, coroutines, JSON conversion and remote debugging. Its weak-table gap and package licensing terms require review before adoption.

**moonsharp-devs/moonsharp** — An interpreter for the Lua language, written entirely in C# for the .NET, Mono, Xamarin and Unity3D platforms, including handy remote debugger facilities.

- Repository: https://github.com/moonsharp-devs/moonsharp
- Website: http://www.moonsharp.org
- Stars: 1,624 · Forks: 250
- Language: C#
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/moonsharp-devs-moonsharp

## MoonSharp's embedded Lua scope

MoonSharp solves the problem of executing Lua inside a managed application. It is intended for developers building .NET, Mono, Xamarin or Unity software that needs scripts, configuration logic or user-defined behavior without launching a separate native Lua process. The README describes the implementation as written entirely in C#, with no external dependencies. Its documented targets include .NET 4.5, .NET Platform, Mono, Xamarin, Unity and ahead-of-time platforms such as iOS.

The README also describes support for IL2CPP-converted code. That is relevant when an application uses a managed runtime environment that differs from ordinary desktop execution. MoonSharp therefore applies to conventional .NET applications as well as managed game and mobile environments, although the correct package, target and interoperability configuration depend on the host platform.

This is primarily an embeddable library rather than a conventional standalone Lua distribution. Its distinguishing capabilities include access to CLR methods, extension methods, overloads, fields, properties and indexers. The README mentions runtime code generation where supported, indicating that interoperability behavior may vary with platform restrictions.

MoonSharp does not claim perfect Lua equivalence. It is described as 99% compatible with Lua 5.2, with weak-table support identified as the only unsupported feature. The README also mentions a few standard-library exceptions, mainly in the `debug` module, and extensions in the string library. Scripts that depend on weak references, exact `debug` behavior or the absence of MoonSharp-specific string behavior need review rather than an assumption of direct compatibility.

## How MoonSharp executes Lua and connects it to C#

The documented execution path places the interpreter inside the managed application. A host passes Lua source to `Script.RunString`, receives a `DynValue`, and reads the result through the appropriate typed member. Script errors are described as exceptions, allowing host code to handle failures through the normal C# exception mechanism rather than treating every failure as a Lua return value.

MoonSharp's CLR interoperability is the central architectural difference from a standalone Lua runtime. According to the README, scripts can use methods, extension methods, overloads, fields, properties and indexers. This lets application services and managed objects participate in Lua execution, subject to the configuration established by the host. The README's factorial example does not show the object-registration process, so that example alone cannot establish how CLR members are exposed.

The library also provides coroutines, including invocation as C# iterators, asynchronous method support and an embedded JSON parser for conversion between JSON and Lua tables. Since the JSON parser has no separate dependency, a host does not need a separate MoonSharp dependency solely for that conversion task.

MoonSharp can also dump and load bytecode. The README associates this feature with obfuscation and quicker parsing at runtime, but its example does not document the generation, loading, version compatibility or deployment details for bytecode. A project that changes interpreter versions should therefore verify those points rather than assume that saved bytecode remains portable.

Standard library modules can be disabled to limit what scripts can access. The README calls this a sandboxing option, but it does not claim that disabling modules creates a complete security boundary. A host that accepts scripts from users or other external parties still needs to decide which Lua modules and CLR objects should be available.

## Installing MoonSharp as a Unity UPM package

For Unity, the README documents installation through the project's `Packages/manifest.json`. The interpreter package is identified as `org.moonsharp.moonsharp`, using the repository's `/interpreter` path. The documented version reference is `upm/v3.0`, while `upm/v3` is available when the application should pin only the major version.

The README also documents `org.moonsharp.debugger.vscode` as a separate package under the `/debugger/vscode` path. Installing the interpreter entry does not install debugger support by itself. Teams that expect visual debugging in Visual Studio Code need to account for the additional package.

The README identifies beta package branches with names such as `upm/beta/v3.0`. This creates a deliberate distinction between the `3.0`, major-version and beta references. A production project should record which reference it uses because changing the branch can alter the package Unity resolves.

For .NET, Mono or Xamarin use outside Unity, the README does not provide a full package installation command in the displayed installation instructions. It directs readers to `http://www.moonsharp.org` for downloads, information and tutorials. The repository also links the getting-started page at `http://www.moonsharp.org/getting_started.html` for detailed managed-host examples.

## Running MoonSharp's documented factorial example

The README provides a first use through `Script.RunString`. Its Lua source defines `fact`, calls it with `5`, and the C# method returns the numeric result stored in `DynValue.Number`.

The complete example below is copied from the README:

```csharp
double MoonSharpFactorial()
{
	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)";

	DynValue res = Script.RunString(script);
	return res.Number;
}
```

`Script.RunString` executes the Lua source, while `DynValue` carries the returned value into C#. Reading `res.Number` is appropriate because the Lua function returns a number.

The README does not show imports, a containing class or dependency installation around this method, so the snippet is not a complete standalone host project. It also does not demonstrate debugger attachment, CLR object registration or standard-library module configuration. The example establishes basic script execution, while those integration tasks require separate setup described by the project documentation.

A host should also account for the documented exception behavior. Since script errors are exceptions, failure handling belongs in the managed call path around script execution. The factorial example itself does not show a try-and-catch block, so it should not be mistaken for an error-handling example.

## MoonSharp compatibility limits and debugger boundaries

The clearest functional limitation is Lua weak tables. The README calls MoonSharp 99% compatible with Lua 5.2 while explicitly identifying weak-table support as unsupported. Scripts using weak keys or weak values cannot be accepted unchanged. This affects a language-level capability rather than only an optional library extension.

The README says the complete Lua standard library is supported with very few exceptions, mainly in `debug`, and it also identifies extensions in the string library. A migration should check code that depends on exact debugger functions, implementation-specific strings or behavior shared with another Lua runtime.

Debugger integration uses the Debug Adapter Protocol, with Visual Studio Code given as an example. For Unity UPM users, the debugger package is separate from the interpreter. The repository layout places debugger components in `src/MoonSharp.RemoteDebugger` and `src/MoonSharp.VsCodeDebugger`, and the Dockerfile copies both directories for its CI environment. The README does not document production ports, authentication, launch configuration or host-side debugger initialization, so those details should not be assumed.

Bytecode presents another verification point. MoonSharp supports dumping and loading it, and the README associates it with obfuscation and faster runtime parsing. It does not state whether bytecode is portable across MoonSharp versions or platforms. A project that upgrades the interpreter should check the selected release before retaining previously generated bytecode.

The repository is not archived, and its last push was on 2026-10-14. The most recent listed release is `v3.0.0-beta.1`, dated 2026-03-03. Earlier releases are listed for 2016. Repository activity and release status answer different questions, so the last push date does not make the beta API a stable contract.

## MoonSharp licensing and version selection

The repository metadata labels the license as `Other`, explaining that GitHub cannot classify the custom license. The README states that the program and libraries are released under a 3-clause BSD license and directs readers to the license section. It also says parts of the string library are based on KopiLua and that debugger icons come from Eclipse.

The `LICENSE` file is therefore the real source for release review. The repository classification, README summary and files included in a package should be compared rather than treating one GitHub label as the complete licensing record. This is a compliance review step, not legal advice.

The Unity package references distinguish `upm/v3.0`, `upm/v3` and beta branches such as `upm/beta/v3.0`. A production application should record the branch or package artifact it uses because changing these references can change what Unity resolves. The README does not describe a separate versioning policy for non-Unity package consumers.

It also documents local UPM package creation. The commands below are copied directly from the README and stage a local package before packing it.

```bash
tools/upm/stage-local-package.sh 3.0.0-local
cd .upm-staging/org.moonsharp.moonsharp
npm pack
```

The README says this produces a tarball such as `org.moonsharp.moonsharp-3.0.0-local.tgz`. That output belongs to the documented Unity package workflow. The README does not provide a matching local-build command for a general NuGet or .NET distribution.

## MoonSharp versus a standalone Lua runtime

A standalone Lua deployment generally runs through a native Lua runtime, with scripts accessed through the Lua C API or another process. MoonSharp takes a different approach by implementing Lua in C# so the interpreter can live inside a managed application. The host receives `DynValue` results, script errors become exceptions, and Lua code can interact with CLR methods and members.

This approach is useful when the application, host API and debugger integration are already built around .NET, Mono, Xamarin or Unity. The README lists support for constrained targets such as ahead-of-time iOS platforms and Unity IL2CPP-converted code. Those are concrete deployment considerations rather than generic portability claims.

The trade-off is compatibility with a conventional Lua 5.2 environment. MoonSharp lacks weak tables and has documented differences in `debug` and string behavior. Its bytecode and Debug Adapter Protocol support are MoonSharp-specific concerns and should not be treated as automatically interchangeable with a separate native Lua installation.

A team requiring Lua 5.2 weak-table behavior should reject MoonSharp or verify another approach before committing. A team embedding scripts in a managed application can evaluate it directly, using the README's factorial example for the first execution check and then reviewing CLR exposure, module selection, debugger setup and the `LICENSE` file in the intended package.

## Conclusion

Adopt MoonSharp when an application needs an in-process Lua interpreter for .NET, Mono, Xamarin or Unity and its CLR interoperability model fits the project. Do not select it for scripts that require Lua 5.2 weak tables, because the README identifies weak-table support as unsupported. Before adoption, inspect the LICENSE file and package-specific terms, then verify the required standard library modules, debugger configuration and target platform in the selected release.

## FAQ

### Which platforms does MoonSharp support?

The README lists .NET 4.5, .NET Platform, Mono, Xamarin, Unity and ahead-of-time platforms such as iOS. It also states that MoonSharp supports IL2CPP-converted code.

### Is MoonSharp fully compatible with Lua 5.2?

No. The README describes MoonSharp as 99% compatible with Lua 5.2 and identifies weak tables as unsupported. It also notes standard-library exceptions, mainly in `debug`, and string-library extensions.

### How is MoonSharp installed in a Unity project?

The README documents adding `org.moonsharp.moonsharp` to `Packages/manifest.json` with a Git URL using `/interpreter` and either `upm/v3.0` or `upm/v3`. The Visual Studio Code debugger is distributed as a separate package.

## Sources

- [Issues](https://github.com/moonsharp-devs/moonsharp/issues)
- [moonsharp-devs/moonsharp on GitHub](https://github.com/moonsharp-devs/moonsharp)
- [Project website](http://www.moonsharp.org)
- [README](https://github.com/moonsharp-devs/moonsharp/blob/master/README.md)
- [Releases](https://github.com/moonsharp-devs/moonsharp/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/moonsharp-devs-moonsharp