MoonSharp 文档五

目录

13.Coroutines（协程）

Lua中的协程

从CLR代码中的协程

从CLR代码中的协程作为CLR迭代器

注意事项

抢占式协程

14.Hardwire descriptors（硬编码描述符）

为什么需要“硬编码”

什么是“硬编码”

如何进行硬编码

硬编码的优缺点

硬编码是实现IL2CPP、AOT或iOS兼容性的必要条件吗？

术语表

15.Sandboxing（沙盒）

为什么需要沙盒化

沙盒化检查清单

移除“危险”的 API

16.Tips and tricks for Unity3D（Unity3D的提示和技巧）

支持的平台

其他建议

使用更显式的构造函数之一初始化脚本加载器

17.FAQ / Recipes

如何重定向打印函数的输出？

如何将输入重定向到Lua程序？

如何重定向Lua程序的IO流？

如何限制脚本在不丢失状态的情况下执行的指令数？

---

MoonSharp 文档一-CSDN博客

MoonSharp 文档二-CSDN博客

MoonSharp 文档三-CSDN博客

MoonSharp 文档四-CSDN博客

13.Coroutines（协程）

来自 C# 和 Lua。

文档地址：MoonSharp

Lua中的协程

Lua 中的协程是开箱即用的支持。实际上，只要你不故意排除协程模块（参见沙盒化），它们就可以免费使用。有很多注意事项（这些也偶然适用于原始的 Lua 实现），并在下面的 “注意事项” 部分进行了讨论。

使用任何 Lua 协程教程来操作它们。

从CLR代码中的协程

协程可以通过脚本 CreateCoroutine 方法创建，该方法接受一个必须是函数的 DynValue。

string code = @"return function()local x = 0while true dox = x + 1coroutine.yield(x)endend";// Load the code and get the returned function
Script script = new Script();
DynValue function = script.DoString(code);// Create the coroutine in C#
DynValue coroutine = script.CreateCoroutine(function);// Resume the coroutine forever and ever..
while (true)
{DynValue x = coroutine.Coroutine.Resume();Console.WriteLine("{0}", x);
}

从CLR代码中的协程作为CLR迭代器

可以像调用迭代器一样调用协程：

string code = @"return function()local x = 0while true dox = x + 1coroutine.yield(x)if (x > 5) thenreturn 7endendend";// Load the code and get the returned function
Script script = new Script();
DynValue function = script.DoString(code);// Create the coroutine in C#
DynValue coroutine = script.CreateCoroutine(function);// Loop the coroutine 
string ret = "";foreach (DynValue x in coroutine.Coroutine.AsTypedEnumerable())
{ret = ret + x.ToString();
}Assert.AreEqual("1234567", ret);

注意事项

现在我们来到了协程相关内容中最重要的部分。就像在原始的 Lua 中一样，无法从嵌套调用中执行 yield 操作。

特别是在 MoonSharp 中，如果你在从 Lua 调用的 C# 函数中调用一个脚本，你不能使用 yield 来恢复到 C# 调用外部的协程。

不过有一个解决办法：返回一个 TailCallRequest 类型的 DynValue。

return DynValue.NewTailCallReq(luafunction, arg1, arg2...); 

还可以指定一个 continuation（延续）——这是一段函数，它将在尾调用执行完成后被调用。

在 99% 的情况下，这可能是过度设计——甚至在大多数情况下，Lua 标准库也无法正确处理回调与 yield 的结合。但如果你计划自己实现像 `load`、`pcall` 或 `coroutine.resume` 这样的 API，这就是必需的。

另外，在某些边缘情况下，MoonSharp 处理 yield 的方式与标准 Lua 不同（在我尝试过的所有情况中，MoonSharp 的方式都更好，但谁知道呢）。例如，`tostring()` 支持在调用 `__tostring` 元方法时执行 yield 操作，而不会引发错误。

抢占式协程

在 MoonSharp 中，即使协程没有调用 `coroutine.yield`，也可以将其挂起。例如，如果想要非破坏性地限制脚本占用的 CPU 时间，这可能会很有用。但为了保持脚本的一致性，有一些需要注意的地方。

让我们从一个例子开始：

string code = @"function fib(n)if (n == 0 or n == 1) thenreturn 1;elsereturn fib(n - 1) + fib(n - 2);endend";// Load the code and get the returned function
Script script = new Script(CoreModules.None);
script.DoString(code);// get the function
DynValue function = script.Globals.Get("fib");// Create the coroutine in C#
DynValue coroutine = script.CreateCoroutine(function);// Set the automatic yield counter every 10 instructions. 
// 10 is likely too small! Use a much bigger value in your code to avoid interrupting too often!
coroutine.Coroutine.AutoYieldCounter = 10;int cycles = 0;
DynValue result = null;// Cycle until we get that the coroutine has returned something useful and not an automatic yield..
for (result = coroutine.Coroutine.Resume(8); result.Type == DataType.YieldRequest;result = coroutine.Coroutine.Resume()) 
{cycles += 1;
}// Check the values of the operation
Assert.AreEqual(DataType.Number, result.Type);
Assert.AreEqual(34, result.Number);

步骤如下：

1. 创建一个协程 

2. 将 `AutoYieldCounter` 设置为一个大于 0 的数字。1000 是一个不错的起点，可以根据需要调整。这个数字表示在执行多少条指令后，协程会主动挂起并返回给调用者。  

3. 调用 `coroutine.Coroutine.Resume(...)` 并传入适当的参数。

4. 如果上述调用的返回类型是 `DataType.YieldRequest`，则不带参数调用 `coroutine.Coroutine.Resume()`。 

5. 重复上一步，直到返回一个真正的结果类型。 

6. 完成。  

注意事项：

1. 如果代码重新进入（例如，`string.gsub` 的回调函数），在返回到“可挂起状态”之前，它不会被抢占。

2. 将标准协程操作与抢占式操作混合使用是可能的，但危险且复杂。请记住，协程可以在任何地方被抢占式挂起，因此无法保证操作的原子性等。如果混合使用，请务必小心。

14.Hardwire descriptors（硬编码描述符）

自2016年以来帮助 AOT 和 IL2CPP

文档地址：MoonSharp

如果您不知道本页中使用的某些术语，请参阅底部的术语表部分。

为什么需要“硬编码”

MoonSharp 像大多数类库一样，使用反射，有时还会在运行时生成代码，以便从 Lua 脚本中访问 C# 代码。

从根本上说，MoonSharp 已经比大多数其他脚本引擎更加温和，原因在于：

理论上，它可以在完全不使用反射的情况下运行（尽管需要编写大量代码），这有助于提高速度并避免一些麻烦（如 IL2CPP 的 link.xml 问题）。
它不会在不应该生成IL代码的平台上生成IL代码（如 Xamarin 的 iOS、Unity 的 IL2CPP 平台等）。
前一点不会导致功能损失，只是速度会稍微慢一些。
这些都是优点，并且带来了很大的兼容性，但还可以做得更多。

如果大部分反射都被移除（剩下的少量反射也无害），并且还能获得更好的性能，那会怎样？

听起来好得不像真的？从某种意义上说，是的。这就是“硬编码”的用武之地，但需要付出一些代价。

什么是“硬编码”

这个想法很简单。为了避免反射，目前唯一的方法是编写大量的 C# 胶水代码。非常多。而且是难以编写的 C# 代码。但这并不是必须的——我们可以稍微简化一下编写方式。但这仍然是一项枯燥的工作，而且很容易出错。

然而，事实证明，这种枯燥、困难且容易出错的工作正是自动化的理想场景。而 MoonSharp 拥有完成这项工作所需的所有信息。

所以，简而言之，通过“硬编码”，MoonSharp 可以生成一堆不需要进一步反射类型就能运行的 C# 代码。

如何进行硬编码

很简单。嗯，几乎很简单。

MoonSharp 需要将已注册的所有类型的信息导出到某个地方。为此，需要编写一小段临时代码：

Table dump = UserData.GetDescriptionOfRegisteredTypes(true);
File.WriteAllText(@"c:\temp\testdump.lua", dump.Serialize());

重要的是，上述代码必须在所有类型都已注册之后运行。因此，硬编码的第一条规则是确保所有注册的顺序正确。

现在，可以使用 MoonSharp 的 REPL 解释器生成代码：

moonsharp -W c:\temp\testdump.lua c:\temp\out.cs --internals --class:MyClass --namespace:MyNamespace

此时，生成过程可能会输出大量警告/错误。它们会显示在控制台输出中，并作为代码中的注释。即使存在警告/错误，生成的代码仍然可以工作，但请花时间阅读这些警告/错误，因为如果你的脚本代码引用了触发这些警告/错误的成员，行为可能会与预期不同。

如果你没有 Windows 电脑，你可以轻松地使用 Mono 在 Mac 或 Linux 上运行 MoonSharp 解释器！

生成的代码将包含一个单一的公共静态类，其中有一个公共的静态 `Initialize` 方法，你应该在使用 MoonSharp 进行任何其他操作之前调用这个方法。非常简单。

如果你注册了一个系统类型（例如，数组），在硬编码时可能会遇到一些问题。原因是硬编码将使用生成 “dump” 时运行时的类型定义，如果你更改了 .NET 版本或平台，运行时可能会有所不同。虽然这看起来像是一个边缘情况，但在 Unity 的 Windows Phone 和 Windows Store 应用中会发生这种情况。在最坏的情况下，可以在生成的代码周围加上条件编译指令。

硬编码的优缺点

优点：

•  大幅减少反射的使用
•  在元数据被剥离的情况下（如IL2CPP），无需白名单类型
•  无需运行时代码生成
•  显著提升性能，尤其是在不支持运行时代码生成的平台上

缺点：

•  需要在工作流程中加入代码生成步骤
•  代码生成仅支持 C# 或 VB.NET
•  暴露的类型和成员必须对其他类可访问——简而言之，必须是`public`的，或者在同一程序集中为`internal`
•  某些类型的成员可能不受支持（例如事件，至少在当前版本中）  
•  值类型的设置器可能无法正常工作——或者比平时更糟，尽量避免使用它们
•  硬编码系统目前涵盖了所有通过 `UserDataType` 注册的类型，而不传递用户数据描述符。除了自定义描述符（显然需要你自己处理）之外，这意味着与 `PropertyTableAssigner` 和扩展方法一起使用的类型不包括在内。通常这问题不大，因为它们往往用于 IL2CPP 启发式算法可见的类型，未来可能会实现支持。

硬编码是实现IL2CPP、AOT或iOS兼容性的必要条件吗？

AOT 兼容性通过 `PlatformAccessor` 管理。实际上，唯一的行为变化是在 AOT 平台上不执行运行时代码生成，而是使用纯反射。

对于 IL2CPP 兼容性，硬编码简化了这一过程——通过消除为不应剥离的元数据维护 `link.xml` 文件的需求——并使其更高效，因为反射速度较慢。但你仍然可以通过向 `link.xml` 添加条目来实现兼容性。

术语表

反射（Reflection）：  
一组允许代码“检查”自身并最终调用方法、读取和写入字段及属性等的类型和方法。虽然功能强大，但速度较慢。详见 MSDN 文档。

运行时代码生成（Runtime code generation）：  
在运行时生成代码以优化通过反射完成的操作的做法。MoonSharp 在某些地方使用了这一技术，但在 AOT 平台上会被禁用。

IL（Intermediate Language，中间语言）：  
.NET/mono 程序集中的代码以 IL（中间语言字节码）形式存储。这种字节码不能直接执行，必须在执行前转换为本地指令。

JIT（Just-In-Time，即时编译）：  
通常，当 .NET 或 mono 加载程序集时，它们会对IL代码进行即时编译，将其转换为本地代码。这也可能在程序集的生命周期后期发生——例如，如果泛型类型的某个类型参数是值类型，通常会即时重新编译。

AOT（Ahead-of-Time，预先编译）：  
mono 提供的一种选项（某种程度上 ngen 和 .NET Native 也提供，但与此讨论无关，至少目前如此），可以提前将代码编译为本地代码或其他形式。这并不简单，可能无法编译所有需要的代码。例如，如果使用反射来实例化代码中从未引用的类型，则该特定代码可能未被编译。在 iOS 设备上运行需要 AOT 执行。

IL2CPP：  
一种将 IL 转换为 C++ 源代码的出色软件。它是那种极难编写但大多数人谈论它时只是为了抱怨的软件。说真的，它试图解决的问题非常复杂，需要一些合作来确保兼容性。特别是，除了所有 AOT 问题（IL2CPP 必须使用 AOT）外，IL2CPP 还会对程序集元数据进行选择性剥离，这可能会干扰反射。在 Unity3D 下，IL2CPP 是 iOS、tvOS 和 WebGL 的强制要求，并在更多平台上作为选项提供。

link.xml：  
一个告诉 IL2CPP 应保留哪些类型的元数据的文件。

值类型（Value-type）：  
值类型是按值传递而不是按引用传递的类型。它包括数值基元类型、枚举和结构体。当谈论值类型问题时，通常指的是结构体。详见 MSDN 上的结构体文档。最佳实践建议值类型应为不可变的，即它们的字段和属性应为只读的，如果需要更改它们，应创建一个新对象（对于结构体来说，这非常廉价）。MoonSharp 与可变结构体的兼容性不佳，因为它们是一种与许多事物都不兼容的奇怪存在，因此请不要使用它们。如果必须使用，请考虑使用代理对象进行变通。

15.Sandboxing（沙盒）

限制 Lua 脚本的功能

文档地址：MoonSharp

为什么需要沙盒化

沙盒化很可能是你使用 MoonSharp 时的关键功能。除非你以某种方式控制脚本提供者（可能还包括用户），否则在运行时加载脚本（或任何类型的代码，有时甚至是数据）时存在一个基本的信任问题：安全性。

例如，假设你正在编写一款视频游戏，并使用 Lua 使游戏“可修改”。用户可以访问某个社区网站并下载包含新关卡、AI等的模组，这些模组都使用 MoonSharp 编写以实现最大灵活性。大家都很开心。现在想象一下，如果某个恶意用户上传了一些隐藏在漂亮关卡中的恶意脚本，会发生什么……比如一个在桌面上创建 .exe 文件的脚本，其他用户可能会不小心点击它。

除非你信任用户，或者明显可以防止恶意使用，否则你不想向普通用户公开某些 API（如`os`、`io`和`file`）。

沙盒化检查清单

这份清单可以帮助你入门，但并不全面。

1. 确保脚本无法访问所有“危险”的标准 API。这肯定包括`io`、`os`和`file`，但根据你的脚本和偏执程度，可能还包括更多。请参阅下一章，了解如何轻松地使整个API集不可访问。

2. 不要使用 `InteropRegistrationPolicy.Automatic`。永远不要。

3. 检查你是否向脚本暴露了不应暴露的类型或类型成员。避免直接暴露你不拥有的类型，如 .NET 框架类型或 Unity 类型。如果需要，请参阅关于“代理对象”的部分，以及如何使用 `MoonSharpHide` 和 `MoonSharpHidden`。

4. 如果你希望脚本的某些部分访问这些危险的 API，请将它们放在单独的 `Script` 对象中，并确保其他脚本无法访问这些对象。

5. 如果绝对必须仅对脚本的一部分进行“沙盒化”，请参考这份经典指南。

移除“危险”的 API

移除危险 API 的最简单方法是使用接受 `CoreModules` 枚举的 `Script` 构造函数。

`CoreModules` 枚举的含义非常直观：

/// <summary>
/// Enumeration (combinable as flags) of all the standard library modules
/// </summary>
[Flags]
public enum CoreModules
{/// <summary>/// Value used to specify no modules to be loaded (equals 0)./// </summary>None = 0,/// <summary>/// The basic methods. Includes "assert", "collectgarbage", "error", "print", "select", "type", "tonumber" and "tostring"./// </summary>Basic = 0x40,/// <summary>/// The global constants: "_G", "_VERSION" and "_MOONSHARP"./// </summary>GlobalConsts = 0x1,/// <summary>/// The table iterators: "next", "ipairs" and "pairs"./// </summary>TableIterators = 0x2,/// <summary>/// The metatable methods : "setmetatable", "getmetatable", "rawset", "rawget", "rawequal" and "rawlen"./// </summary>Metatables = 0x4,/// <summary>/// The string package/// </summary>String = 0x8,/// <summary>/// The load methods: "load", "loadsafe", "loadfile", "loadfilesafe", "dofile" and "require"/// </summary>LoadMethods = 0x10,/// <summary>/// The table package /// </summary>Table = 0x20,/// <summary>/// The error handling methods: "pcall" and "xpcall"/// </summary>ErrorHandling = 0x80,/// <summary>/// The math package/// </summary>Math = 0x100,/// <summary>/// The coroutine package/// </summary>Coroutine = 0x200,/// <summary>/// The bit32 package/// </summary>Bit32 = 0x400,/// <summary>/// The time methods of the "os" package: "clock", "difftime", "date" and "time"/// </summary>OS_Time = 0x800,/// <summary>/// The methods of "os" package excluding those listed for OS_Time. These are not supported under Unity./// </summary>OS_System = 0x1000,/// <summary>/// The methods of "io" and "file" packages. These are not supported under Unity./// </summary>IO = 0x2000,/// <summary>/// The "debug" package (it has limited support)/// </summary>Debug = 0x4000,/// <summary>/// The "dynamic" package (introduced by MoonSharp)./// </summary>Dynamic = 0x8000,/// <summary>/// A sort of "hard" sandbox preset, including string, math, table, bit32 packages, constants and table iterators./// </summary>Preset_HardSandbox = GlobalConsts | TableIterators | String | Table | Basic | Math | Bit32,/// <summary>/// A softer sandbox preset, adding metatables support, error handling, coroutine, time functions and dynamic evaluations./// </summary>Preset_SoftSandbox = Preset_HardSandbox | Metatables | ErrorHandling | Coroutine | OS_Time | Dynamic,/// <summary>/// The default preset. Includes everything except "debug" as now./// Beware that using this preset allows scripts unlimited access to the system./// </summary>Preset_Default = Preset_SoftSandbox | LoadMethods | OS_System | IO,/// <summary>/// The complete package./// Beware that using this preset allows scripts unlimited access to the system./// </summary>Preset_Complete = Preset_Default | Debug,}

16.Tips and tricks for Unity3D（Unity3D的提示和技巧）

为在 Unity 上使用 MoonSharp 的用户提供的快速提示集

文档地址：MoonSharp

支持的平台

一般来说，MoonSharp 的目标是支持所有平台。然而，在 Unity 中测试 MoonSharp 在所有平台上的表现是非常困难的，几乎是不可能的。

因此，平台被分为不同的等级。

1.预计完全支持独立的 Windows、Linux 和 OS/X * 安卓 * iOS * tvOS

2.预计零星支持，将在可能的情况下测试小问题/不支持的功能 WebGL * Windows 应用商店应用程序 Windows Phone

3.应该有效，但我很难提供支持其他层没有的东西

4.不支持，您只能自己使用目前尚不清楚，将进行更新以防

其他建议

•  如果可能，不要暴露 Unity 类型  
•  尽可能使用代理对象  
•  在运行于 IL2CPP 和/或 AOT 平台之前，使用硬编码  
•  如果可能，永远不要暴露结构体  

使用更显式的构造函数之一初始化脚本加载器

使用 UnityAssetsScriptLoader 的显式构造函数来注册所有脚本文件。通过在项目的最开始使用这个小片段，您不需要将 Unity 自带的库添加到 link.xml 中，就可以在 IL2CPP 平台上运行。

示例：

Dictionary<string, string> scripts = new  Dictionary<string, string>();object[] result = Resources.LoadAll("Lua", typeof(TextAsset));foreach(TextAsset ta in result.OfType<TextAsset>()){scripts.Add(ta.name, ta.text);}Script.DefaultOptions.ScriptLoader = new MoonSharp.Interpreter.Loaders.UnityAssetsScriptLoader(scripts);

17.FAQ / Recipes

常见问题的简单示例

文档地址：MoonSharp

如何重定向打印函数的输出？

script.Options.DebugPrint = s => { Console.WriteLine(s); }

如何将输入重定向到Lua程序？

script.Options.DebugInput = () => { return Console.ReadLine(); }

如何重定向Lua程序的IO流？

IoModule.SetDefaultFile(script, Platforms.StandardFileType.StdIn, myInputStream);
IoModule.SetDefaultFile(script, Platforms.StandardFileType.StdOut, myOutputStream);
IoModule.SetDefaultFile(script, Platforms.StandardFileType.StdErr, myErrorStream);

如何限制脚本在不丢失状态的情况下执行的指令数？

参考 Preemptive coroutines.

end