ProceduralModels 是一種以參數驅動的 Model，讓你使用程式碼建立和生成 3D 物件。你不是手動編輯模型的內容，而是通過一個 生成模組 和一組屬性定義其結構。當這些屬性改變，或當模型被調整尺寸時，生成器會自動運行以更新模型。
程式化模型使得以下幾點變得更容易：
- 透過更改參數而非重建模型，非破壞性地調整模型。例如，在螺旋樓梯上更改 StepSize 值會自動重新生成帶有更新步數的樓梯。
- 透過實現單一的 OnGenerate 函數，自動與現有的 Studio 系統如撤銷/重做、團隊創建和拖曳工具整合。
- 保持性能高效，模型在參數變更之前表現得像標準物件。
- 在編輯時和運行時生成內容，使用 Studio 和遊戲中的相同系統。
- 在創作者商店分享參數化模型，使資源更靈活和可定製。
插入程式化模型
你可以透過以下方式將程式化模型添加到你的遊戲中：
手動將 ProceduralModel 物件插入到工作區。此選項包含一個範本生成器 ModuleScript 以幫助你入門。
使用 助手 或 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: 一個參數，反映模型在比例為一的情況下的尺寸。
- Pause: 一個方法，允許在複雜的生成任務中高效地進行生成。
OnGenerate 函數應該在 targetContainer 的原點附近生成內容。它不應直接修改主 DataModel 層級。
參數
參數 是控制生成的輸入。這些包括 ProceduralModel 的內建 Size 屬性，以及在生成器模組中指定的自訂屬性。這些 顯式參數 直接傳遞給 OnGenerate。隱式參數，如模組的源代碼或沙盒狀態，當改變時也會觸發再生，但不會傳遞給 OnGenerate。
完整的參數集合包括：
- 顯式：
- Size: 定義圍繞原點生成內容的區域。
- Attributes: 一個包含當前輸入屬性值的映射。
- 隱式：
- 生成器：提供生成邏輯的模組。
- 源代碼：生成器模組的 Luau 代碼的變更。
- 沙盒：生成器模組的沙盒狀態的變更。
再生行為
為了保持性能和簡化 API 互動，當參數改變時不會立即調用 OnGenerate。相反，ProceduralModel 被標記為 dirty，表示再生已待處理。這一待處理的再生通常會在同一幀的稍後進行。
如果再生失敗，髒狀態會在發生另一個參數變更之前被清除。如果在模型髒的情況下儲存地方，其狀態會保留，並且模型會在下一次遊戲載入時添加到生成隊列中。
執行過程
當有可用的處理時間時，引擎通過執行以下步驟來重新生成髒模型：
- 載入生成器模組，必要時暫停。
- 開始生成過程的新執行緒。
- 構建參數表，根據模型當前的比例規範化 Size。
- 對任何缺少的屬性應用默認屬性值。
- 初始化一個臨時的 GeneratedFolder 作為 targetContainer。
- 調用 OnGenerate。
- 在 OnGenerate 返回後：
- 如果成功，將 targetContainer 中的結果遷移到 ProceduralModel。
- 如果生成失敗，則使用失敗佔位符。
如果在生成執行緒被暫停時參數再次改變，未完成的生成會被取消並使用更新的參數重新啟動。
生成結果
將生成的結果置入模型涉及以下步驟：
- 終止生成過程中泄漏的任何子執行緒。
- 使用 PivotTo 將結果放置。
- 如果模型的 Scale 不是 1，使用 ScaleTo 來撤消尺寸的規範化。
- 將結果歸屬於模型的 GeneratedFolder。
- 如果生成器模組是沙盒的，確保結果中的 ModuleScripts 不超過生成器模組的能力。
- 用其默認值填充模型中缺失的任何屬性。
- 清除模型的髒狀態。
生成細節
除了核心生成流程外，以下細節描述影響 ProceduralModel 生成工作的一些行為和考慮事項。
尺寸調整
由於在生成期間應用的比例規範化，ProceduralModel 支持多種尺寸調整工作流：
- 更改 Size 屬性會使用新內容重新生成模型。
- 更改 Scale 會使用 ScaleTo 均勻縮放現有結果。
超時
作為一個安全機制，執行太多工作而不進行暫停的生成器模組會被終止。如果生成遇到 "Script Timeout" 錯誤，請添加額外的 parameters:Pause() 調用，以便讓引擎將剩餘的工作推遲到稍後的幀。
調用 parameters:Pause() 是非常廉價的，通常在正常生成執行期間立即返回，所以可以在循環的開始處隨意調用，而不會影響性能。
撤銷歷史
生成的結果與觸發它們的參數變更一起使用撤銷路徑覆蓋進行分組。如果在同一幀中發生多次參數變更，則結果將與最近的路徑相關聯。
沙箱
ProceduralModel 支持沙盒。你從創作者商店插入的所有第三方程式化模型默認為沙盒，以幫助防止對你的遊戲進行不必要的變更。
生成代碼在生成器模組的上下文中運行，並使用該模組的沙盒狀態。這些設置默認情況下不可見。要查看或修改它們，請設置 Workspace.SandboxedInstanceMode = Experimental。這會顯示 ModuleScript 上的 Sandboxed 和 Capabilities 屬性。
一個沙盒的生成器模組通常至少需要以下能力：
- RunServerScript（執行模組）
- CreateInstances
- Basic
ProceduralModel 和其生成器模組的沙盒狀態彼此獨立。應用於生成器模組的沙盒不影響 ProceduralModel 中的正常運行時腳本。這讓你保持編輯時生成的嚴格限制，而不影響遊戲內的行為。
嵌套
ProceduralModels 可以生成其他 ProceduralModels。當這發生時，引擎在可能的情況下在同一生成步驟中自上而下處理層級，深度嵌套的模型最後生成。
限制
- 在 Actor 實例中不支持生成。
- 模型不能轉換為包。
- 使用啟用關節表面的拖拉工具時創建的關節在 ProceduralModel 再生過程中不會被保留。