ProceduralModel
Procedural models support edit-time procedural generation. Instead of manually constructing model content, a procedural model generates its contents automatically in response to parameter changes.
| Memory category | BaseParts |
|---|
Member index 5
Removed member index 1
| History | Member |
|---|
Description
ProceduralModel inherits from Model and supports edit-time
procedural generation of its contents. Instead of manually constructing model
content, a procedural model generates its contents automatically in response
to parameter changes.
Generation is defined by a generator module, a ModuleScript
referenced by the Generator property. The
engine invokes the module's OnGenerate function to produce the model's
contents.
A procedural model regenerates when any of the following inputs change:
- The Size property of the procedural model, which defines a bounding box for the model to generate within.
- Any attributes on the procedural mode, as defined by the generator module.
- The generator's module sandboxing configuration (
SandboxedandCapabilities). - The source code of the generator module.
When any of these inputs change, the engine schedules regeneration. This
scheduled regeneration is performed by calling OnGenerate and applying its
results once it returns. In most cases, generation happens within the same
frame, but can be deferred to maintain performance.
History 10
- 726 Change Default of Size from Vector3(12, 12, 12) to
- 726 Change Default of Generator from to
- 726 Remove
- 715 Add WaitForGenerationAsync
- 715 Add ForceGeneration
- 715 Add Size
- 715 Add Generator
- 715 Add GenerationError
- 715 Add
- 715 Add ProceduralModel
Members 5
ForceGeneration
| Parameters (0) | ||
|---|---|---|
| No parameters. | ||
| Returns (1) | ||
| bool | ||
| Thread safety | Unsafe |
|---|
History 1
- 715 Add ForceGeneration
GenerationError
| Type | Default | |
|---|---|---|
| string | ||
If the generator module encounters an error during generation, the
contents of the ProceduralModel are replaced with an error state
placeholder. The error is stored in the GenerationError property to give
you visibility into why the generation failed.
| Thread safety | ReadSafe |
|---|---|
| Category | Behavior |
| Loaded/Saved | false/true |
History 1
- 715 Add GenerationError
Generator
| Type | Default | |
|---|---|---|
| ModuleScript | ||
A reference to a ModuleScript containing code that defines how the
ProceduralModel generates its contents in response to parameter changes.
Setting Generator triggers generation using the new generator module.
The Attributes table exported by the module is automatically applied as
default attribute values on the ProceduralModel.
Clearing Generator preserves the current contents of the
ProceduralModel, and prevents further generation until a new generator
is assigned.
Guidelines for writing the generator module's OnGenerate function:
- Only write results into the provided
targetContainer.OnGenerateshould not modify the DataModel directly; writes elsewhere may not interact correctly with engine systems. OnGenerateis allowed to yield and call yielding methods (for example, GeometryService CSG APIs). Generation is considered complete wheneverOnGeneratereturns.- Calling
parameters:Pause()inside long-running loops lets the engine break up work. It only yields when needed to avoid dropping frames, so calls are low-cost when the frame budget is not exceeded.
| Thread safety | ReadSafe |
|---|---|
| Category | Behavior |
| Loaded/Saved | true |
Size
| Type | Default | |
|---|---|---|
| Vector3 | ||
The Size of a ProceduralModel defines the bounding volume used for
generation.
In a standard model, size is a derived output value based on its contents
and can be queried using GetBoundingBox().
A procedural model inverts this relationship: Size is an input that
determines how generation occurs, and is explicitly set as a property.
The Size property represents the physical dimensions of the
ProceduralModel and is affected by ScaleTo. The
OnGenerate function in a generator module doesn't need to account for
position or scaling: it produces a result of the specified Size around
the origin at a scale of 1, and the procedural model system automatically
uses PivotTo() and
ScaleTo() to place and scale the output in the
ProceduralModel.
| Thread safety | ReadSafe |
|---|---|
| Category | Transform |
| Loaded/Saved | true |
WaitForGenerationAsync
| Parameters (0) | ||
|---|---|---|
| No parameters. | ||
| Returns (1) | ||
| bool | ||
Generation is scheduled to run as soon as possible after a parameter
changes, but not immediately. Use WaitForGenerationAsync() to wait for
generation to complete before parameters are changed.
This method errors if called on a ProceduralModel that is not in the DataModel because generation isn't performed for instances without a parent.
This method returns false if the ProceduralModel is removed from
the DataModel while generation is in progress, since this cancels
the operation.
| Thread safety | Unsafe |
|---|