程序化模型

ProceduralModels 是一种以参数驱动的 Model，使您能够使用代码构建和生成 3D 对象。您无需手动编辑模型的内容，而是通过一个生成器模块和一组属性来定义其结构。当这些属性发生变化，或者模型被调整大小时，生成器会自动运行以更新模型。

程序化模型使得以下操作更加容易：

通过更改参数而不是重建模型以非破坏性方式调整模型。例如，更改螺旋楼梯上的 StepSize 值会自动用更新的步骤数量重新生成楼梯。
通过实现一个单一的 OnGenerate 函数，自动与现有的 Studio 系统（如撤销/重做，团队创作和拖拽工具）集成。
保持高性能，模型在参数改变之前表现得像标准对象。
在编辑时和运行时都生成内容，在 Studio 和游戏中使用相同的系统。
在创作者商店分享带参数的模型，使资产更加灵活和可定制。

示例：随着桌子宽度或长度的增加，动态添加更多椅子的程序化模型。

插入程序化模型

您可以通过以下方式将程序化模型添加到您的游戏中：

手动将 ProceduralModel 对象插入工作区。此选项包括一个模板生成器 ModuleScript，可以帮助您入门。
使用 Assistant 或 Roblox Studio MCP 服务器生成程序化模型。
从创作者商店插入一个程序化模型，以使用或自定义现有模型。

程序化模型可以在编辑时对您的游戏进行永久性更改。为了防止不必要的更改，从创作者商店插入的任何程序化模型的生成器模块将自动启用 Sandboxed = true。

要定制程序化模型的生成方式，您可以定义自己的生成器模块。

OnGenerate 函数

OnGenerate 函数是每个 ProceduralModel 的核心，形式为 OnGenerate(params, targetContainer)。

这个开发者定义的函数负责根据提供的参数生成模型的内容，并将结果写入给定的容器中。

OnGenerate 有两个主要职责：

处理输入参数以确定模型的结构
根据该结构将生成的结果写入提供的 targetContainer

以下部分描述了：

引擎何时以及如何调用 OnGenerate
引擎如何处理写入 targetContainer 的内容

生成器模块

OnGenerate 函数在一个称为生成器模块的 ModuleScript 内定义。ProceduralModel 通过其 Generator 属性识别要使用的生成器模块。

生成器模块是标准的 Luau 模块，但作为生成过程的一部分由引擎直接要求。它们遵循定义的结构并返回一个包含标准化字段的表。

生成器模块结构
local MyGenerator = {}

MyGenerator.Attributes = {
    DoSomething = true,
    AmountOfSomething = 137,
}

type Params = {
    Size: Vector3,
    Attributes: typeof(MyGenerator.Attributes),
    Pause: (self: any) -> (),
}
function MyGenerator.OnGenerate(params: Params, targetContainer: GeneratedFolder)
    
end

return MyGenerator

标准化字段包括：

Attributes：一个映射，定义参数名称及其默认值。
OnGenerate：接收 params 表和 targetContainer 的函数。

OnGenerate 中的 params 表包含：

Attributes：一个包含模块定义属性或所有模型属性的表（如果未指定）。
Size：反映模型在比例为 1 时的尺寸的参数。
Pause：一个允许在复杂生成任务中有效地停止生成的方法。

OnGenerate 函数应在 targetContainer 中围绕原点生成内容。它不应直接修改主 DataModel 层次结构。

参数

参数是控制生成的输入。这些包括 ProceduralModel 的内置 Size 属性，以及生成器模块中指定的自定义属性。这些显式参数直接传递给 OnGenerate。隐式参数，如模块的源代码或沙盒状态，在发生变化时也触发再生成，但不会传递给 OnGenerate。

完整的参数集合包括：

显式参数：
- Size：定义围绕原点生成内容的区域。
- Attributes：一个包含当前输入属性值的映射。
隐式参数：
- Generator：提供生成逻辑的模块。
- 源代码：对生成器模块的 Luau 代码的更改。
- 沙盒：对生成器模块的沙盒状态的更改。

再生行为

为了保持性能和简化 API 交互，OnGenerate 在参数更改时不会立即调用。相反，ProceduralModel 被标记为脏，表示再生待定。此待定再生通常在同一帧稍后发生。

如果再生失败，脏状态将被清除，直到发生另一个参数更改。如果在模型处于脏状态时保存游戏，该状态将持续，并且模型将在下一次加载游戏时添加到生成队列中。

执行过程

在处理时间可用时，引擎通过执行以下步骤再生脏模型：

需要生成器模块，根据需要进行等待。
为生成过程启动一个新线程。
构建参数表，通过模型的当前缩放归一化 Size。
将默认属性值应用于任何缺失的属性。
初始化一个临时的 GeneratedFolder 作为 targetContainer。
调用 OnGenerate。
在 OnGenerate 返回后：
- 如果成功，将 targetContainer 中的结果迁移到 ProceduralModel。
- 如果生成失败，则使用失败占位符代替。