ProceduralModels は、コードを使用して3Dオブジェクトを構築および生成できるパラメータ駆動の Model の一種です。モデルの内容を手動で編集する代わりに、ジェネレータモジュールと一連の属性を通じてその構造を定義します。これらの属性が変更されると、またはモデルのサイズが変更されると、ジェネレータが自動的に実行されてモデルが更新されます。
手続き型モデルを使用すると、以下のことが容易になります：
- パラメータを変更することでモデルを非破壊的に調整でき、再構築する必要がありません。たとえば、螺旋階段の StepSize 値を変更すると、自動的に更新された段数で階段が再生成されます。
- 単一の OnGenerate 関数を実装することで、元の編集を介して既存のStudioシステム（元に戻す/やり直し、チーム作成、ドラッグツールなど）と自動で統合します。
- パラメータが変更されるまで標準オブジェクトのように動作するため、パフォーマンスを高く保つことができます。
- Studioおよびゲーム内で同じシステムを使用して、編集時と実行時の両方でコンテンツを生成します。
- Creator Storeでパラメトリックなモデルを共有し、アセットをより柔軟でカスタマイズ可能にします。
手続き型モデルの挿入
ゲームに手続き型モデルを追加する方法は以下の通りです：
ProceduralModel オブジェクトをWorkspaceに手動で挿入します。このオプションには、開始するためのテンプレートジェネレータ ModuleScript が含まれています。
Assistant または Roblox Studio MCPサーバー を使用して手続き型モデルを生成します。
Creator Storeから手続き型モデルを挿入して、既存のモデルを使用またはカスタマイズします。
手続き型モデルは、編集時にゲームに永久的な変更を加える可能性があります。不要な変更から保護するために、Creator Store から挿入された手続き型モデルのジェネレータモジュールには Sandboxed = true が自動的に有効になります。
手続き型モデルがどのように生成されるかをカスタマイズするには、自分自身のジェネレータモジュールを定義できます。
OnGenerate関数
OnGenerate 関数は、OnGenerate(params, targetContainer) という形で、すべての ProceduralModel の中心にあります。
この開発者定義の関数は、提供されたパラメータに基づいてモデルの内容を生成し、結果を指定されたコンテナに書き込む責任があります。
OnGenerate には2つの主な責任があります：
- 入力パラメータを処理してモデルの構造を決定する
- その構造に従って結果を提供された 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: 複雑な生成タスクの最中に生成を効率的にyieldできるメソッド。
OnGenerate 関数は、targetContainer の原点の周辺でコンテンツを生成する必要があります。メインの DataModel 階層を直接変更するべきではありません。
パラメータ
パラメータは生成を制御する入力です。これには、手続き型モデルの組み込み Size プロパティや、ジェネレータモジュールで指定されたカスタム属性が含まれます。これらの明示的パラメータは、OnGenerate に直接渡されます。暗黙的パラメータ（モジュールのソースコードやサンドボックス状態など）は変更されたときに再生成をトリガーしますが、OnGenerate に渡されることはありません。
全パラメータセットには次が含まれます：
- 明示的：
- Size: 原点の周囲でコンテンツが生成される領域を定義します。
- Attributes: 現在の入力属性値を含むマップ。
- 暗黙的：
- ジェネレーター: 生成ロジックを提供するモジュール。
- ソースコード: ジェネレータモジュールのLuauコードへの変更。
- サンドボックス: ジェネレータモジュールのサンドボックス状態への変更。
再生成の動作
パフォーマンスを維持しAPIの相互作用を簡素化するため、パラメータが変更されたときに OnGenerate は即座に呼び出されません。代わりに、ProceduralModel は汚れているとしてマークされ、再生成が保留されていることを示します。この保留中の再生成は通常、同じフレーム内で後に発生します。
再生成に失敗した場合、汚れた状態は別のパラメータ変更が発生するまでクリアされません。モデルが汚れた状態のまま保存されると、その状態は持続し、ゲームが次回読み込まれるときに生成キューに追加されます。
実行プロセス
処理時間が利用可能な場合、エンジンは次のステップを実行して汚れたモデルを再生成します：
- ジェネレータモジュールを要求し、必要に応じてyieldします。
- 生成プロセスのために新しいスレッドを開始します。
- パラメータテーブルを構築し、モデルの現在のスケールで Size を正規化します。
- 欠落している属性へデフォルトの属性値を適用します。
- targetContainer として一時的な GeneratedFolder を初期化します。
- OnGenerate を呼び出します。
- OnGenerate が戻った後：
- 成功した場合、targetContainer の結果を ProceduralModel に移行します。
- 生成に失敗した場合は、代わりに失敗プレースホルダーを使用します。
生成スレッドがyieldされている間に再度パラメータが変更されると、その未解決の生成はキャンセルされ、更新されたパラメータで再起動されます。
生成結果
生成された結果をモデルに配置するには、次の手順を実行します：
- 生成中に漏れた子スレッドを終了します。
- PivotTo を使用して結果の位置を決定します。
- モデルの Scale が1でない場合、ScaleTo を使用してサイズの正規化を元に戻します。
- 結果をモデルの GeneratedFolder の親とします。
- ジェネレータモジュールがサンドボックス化されている場合、結果の ModuleScripts がジェネレータモジュールの能力を超えないようにします。
- モデルの欠落している属性にデフォルト値を設定します。
- モデルの汚れた状態をクリアします。
生成の詳細
コアの生成フローに加え、以下の詳細が ProceduralModel の生成動作に影響を与える動作や考慮事項を説明します。
サイズ調整
生成中に適用されるスケールの正規化のおかげで、ProceduralModel は複数のサイズ調整ワークフローをサポートしています：
- Size プロパティを変更することで、新しいコンテンツでモデルが再生成されます。
- Scale を変更することで、既存の結果が ScaleTo を使用して均一にスケールされます。
タイムアウト
安全策として、過剰な作業をしてyieldせずに実行されるジェネレータモジュールは終了されます。生成が「スクリプトタイムアウト」エラーに達した場合は、残りの作業を次のフレームに延期できるように、追加の parameters:Pause() コールを追加します。
parameters:Pause() を呼び出すことは非常に安価であり、通常は通常のジェネレータ実行中にはすぐに戻るため、パフォーマンスに影響を与えることなくループの開始時に自由に呼び出すことができます。
元に戻し履歴
生成された結果は、それらをトリガーしたパラメータ変更と元に戻しウェイポイントオーバーライドを使ってグループ化されます。単一のフレーム内で複数のパラメータ変更が発生した場合、結果は最も最近のウェイポイントに関連付けられます。
サンドボックス化
ProceduralModel はサンドボックス化をサポートしています。Creator Store から挿入するすべてのサードパーティ製手続き型モデルは、デフォルトでサンドボックス化され、ゲームへの意図しない変更を防ぐのに役立ちます。
生成コードはジェネレータモジュールのコンテキスト内で実行され、そのモジュールのサンドボックス状態を使用します。これらの設定はデフォルトでは表示されません。それらを表示または変更するには、Workspace.SandboxedInstanceMode = Experimental に設定します。これにより、ModuleScript の Sandboxed および Capabilities プロパティが表示されます。
サンドボックス化されたジェネレータモジュールは通常、少なくとも次の機能を必要とします：
- RunServerScript（モジュールを実行するため）
- CreateInstances
- Basic
手続き型モデルとそのジェネレータモジュールのサンドボックス化は互いに独立しています。ジェネレータモジュールに対してサンドボックス化が適用されても、ProceduralModel 内の通常のランタイムスクリプトには影響しません。これにより、編集時の生成を厳しく制限しながら、ゲーム内の動作に影響を与えずに済みます。
ネスト
ProceduralModels は他の ProceduralModels を生成できます。これが発生した場合、エンジンは可能な限り同じ生成ステップ内で階層を上から下に処理し、より深くネストされたモデルが最後に生成されます。
制限事項
- Actor インスタンス内での生成はサポートされていません。
- モデルはパッケージに変換できません。
- Joint Surfaces が有効なドラッガーを使用して作成されたジョイントは、ProceduralModel の再生成の間に保持されません。