12 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

ProceduralModel

Inherits from: Model → PVInstance → Instance → Object

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 (Sandboxed and Capabilities).
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.

Inherits from: Model

Memory category: BaseParts

Properties

Name	Type / Returns	Description
ProceduralModel.GenerationError	string	Stores errors that the generator module might encounter during generation.
ProceduralModel.Generator	ModuleScript	A reference to a `ModuleScript` that contains code which defines how the `ProceduralModel` generates its contents in response to parameter changes.
ProceduralModel.Size	Vector3	Defines the bounding volume used for generation.

Inherited from Model

Name	Type / Returns	Description
Model.LevelOfDetail	ModelLevelOfDetail	Sets the level of detail on the model for experiences with instance streaming enabled.
Model.ModelStreamingMode	ModelStreamingMode	Controls the model streaming behavior on `Models` when instance streaming is enabled.
Model.PrimaryPart	BasePart	The primary part of the `Model`, or `nil` if not explicitly set.
Model.Scale	float	Editor-only property used to scale the model around its pivot. Setting this property will move the scale as though `Model:ScaleTo()` was called on it.
Model.WorldPivot	CFrame	Determines where the pivot of a `Model` which does not have a set `Model.PrimaryPart` is located.

Inherited from PVInstance

Name	Type / Returns	Description
PVInstance.Origin	CFrame	Editor-only property that reads and sets the world `CFrame` of the `PVInstance`'s pivot, moving the entire instance when changed from the Studio Properties window.
PVInstance.Pivot Offset	CFrame	Editor-only property that displays and edits the pivot's `CFrame` relative to the instance, moving only the pivot and leaving the instance in place.

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

ProceduralModel.GenerationError

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.

Field	Value
type	string
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Behavior
serialization	{"can_load":false,"can_save":true}
capabilities	["Basic"]

ProceduralModel.Generator

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. OnGenerate should not modify the DataModel directly; writes elsewhere may not interact correctly with engine systems.
OnGenerate is allowed to yield and call yielding methods (for example, GeometryService CSG APIs). Generation is considered complete whenever OnGenerate returns.
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.

Field	Value
type	ModuleScript
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Behavior
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Code samples: View on Creator Hub (ProceduralModel-Generator-Default, ProceduralModel-Generator-Ladder).

ProceduralModel.Size

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.

Field	Value
type	Vector3
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Transform
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Methods

Name	Type / Returns	Description
ProceduralModel:ForceGeneration	boolean	Immediately runs any pending generation instead of waiting for the scheduled regeneration.
ProceduralModel:WaitForGenerationAsync	boolean	Waits for generation to complete after making parameter changes.

Inherited from Model

Name	Type / Returns	Description
Model:AddPersistentPlayer	()	Sets this model to be persistent for the specified player. `ModelStreamingMode` must be set to `PersistentPerPlayer` for behavior to be changed as a result of addition.
Model:BreakJoints	()	Breaks connections between `BaseParts`, including surface connections with any adjacent parts, `WeldConstraints` and all `Welds` and other `JointInstances`.
Model:breakJoints	()
Model:GetBoundingBox	Tuple	Returns a description of a volume that contains all parts of a Model.
Model:GetExtentsSize	Vector3	Returns the size of the smallest bounding box that contains all of the `BaseParts` in the `Model`, aligned with the `Model.PrimaryPart` if it is set.
Model:GetModelCFrame	CFrame	This value historically returned the CFrame of a central position in the model.
Model:GetModelSize	Vector3	Returns the Vector3 size of the Model.
Model:GetPersistentPlayers	List	Returns all the `Player` objects that this model object is persistent for. Behavior varies based on whether this method is called from a `Script` or a `LocalScript`.
Model:GetPrimaryPartCFrame	CFrame	Returns the `CFrame` of the model's `Model.PrimaryPart`. This function will throw an error if no primary part exists for the `Model`.
Model:GetScale	float	Returns the canonical scale of the model, which defaults to 1 for newly created models and will change as it is scaled via `Model:ScaleTo()`.
Model:MakeJoints	()	Goes through all `BaseParts` in the `Model`. If any part's side has a SurfaceType that can make a joint it will create a joint with any adjacent parts.
Model:makeJoints	()
Model:move	()
Model:MoveTo	()	Moves the `PrimaryPart` to the given position. If a primary part has not been specified, the root part of the model will be used.
Model:moveTo	()
Model:RemovePersistentPlayer	()	Makes this model no longer persistent for the specified player. `ModelStreamingMode` must be set to `PersistentPerPlayer` for behavior to be changed as a result of removal.
Model:ResetOrientationToIdentity	()	Resets the rotation of the model's parts to the previously set identity rotation, which is done through the `Model:SetIdentityOrientation()` method.
Model:ScaleTo	()	Sets the scale factor of the model, adjusting the sizing and location of all descendant Instances such that they have that scale factor relative to their initial sizes and locations when scale factor was 1.
Model:SetIdentityOrientation	()	Sets the identity rotation of the given model, allowing you to reset the rotation of the entire model later, through the use of the `ResetOrientationToIdentity` method.
Model:SetPrimaryPartCFrame	()	Sets the `BasePart.CFrame` of the model's `Model.PrimaryPart`. All other parts in the model will also be moved and will maintain their orientation and offset respective to the `Model.PrimaryPart`.
Model:TranslateBy	()	Shifts a `Model` by the given `Vector3` offset, preserving the model's orientation. If another `BasePart` or `Terrain` already exists at the new position then the `Model` will overlap said object.

Inherited from PVInstance

Name	Type / Returns	Description
PVInstance:GetPivot	CFrame	Gets the pivot of a `PVInstance`.
PVInstance:PivotTo	()	Transforms the `PVInstance` along with all of its descendant `PVInstances` such that the pivot is now located at the specified `CFrame`.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

ProceduralModel:ForceGeneration

Generation is normally scheduled soon after a parameter changes so work can be deferred for performance. ForceGeneration() instead runs any pending generation synchronously and returns whether the ProceduralModel is up to date.

If nothing is pending, returns true without regenerating. Otherwise runs the generator to completion under a hard timeout, then returns true only if the model is no longer waiting to regenerate and produced no GenerationError. On failure or timeout, returns false and re-queues normal scheduled generation. Unlike scheduled generation, a forced generation doesn't yield to preserve the frame budget, so parameters:Pause() inside the generator returns without pausing.

Throws if called from within a generator's OnGenerate function.

Returns

Type	Description
boolean	Whether the `ProceduralModel` is up to date after the call: `true` if generation completed successfully or nothing needed to be regenerated, `false` otherwise.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Basic"]

ProceduralModel:WaitForGenerationAsync

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.

Returns

Type	Description
boolean	Was the generation successful?

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Basic"]

Code samples: View on Creator Hub (ProceduralModel-WaitForGenerationAsync).

Events

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.