Model¶
Models are container objects, meaning they group objects together. They are best used to hold collections of BaseParts and have a number of functions that extend their functionality.
Description¶
Models are container objects, meaning they group objects together. They are best used to hold collections of BaseParts and have a number of functions that extend their functionality.
Models are intended to represent geometric groupings. If your grouping has no geometric interpretation, for instance a collection of Scripts, use a Folder instead.
Models whose constituent parts are joined together with joints (so that they can move around or be destroyed via physics simulation) usually have a PrimaryPart set, as it specifies which part within the model the pivot and bounding box will "follow" as the model moves. Static models which stay in one place do not benefit from having a primary part set.
Models have a wide range of applications, including Roblox player characters. They also have a number of unique behaviors that are important to keep in mind:
- When a Humanoid and a Part named Head are parented under a model, a name/health GUI will appear over the model; see Character Name/Health Display for details.
- If a part's position on the Y axis hits the Workspace.FallenPartsDestroyHeight value, and it was the last object inside of a Model, the model will be destroyed as well.
- When used in a place with Workspace.StreamingEnabled set to true, the value of ModelStreamingMode controls various behaviors around how the model and any descendants are replicated and/or removed from clients. In addition, the value of LevelOfDetail impacts rendering of the model.
As with all Instance types, the fact that a parent Model is replicated to a client does not guarantee that all its children are replicated. This is particularly important if these instances are being accessed by code running on the client, such as in a LocalScript. Using ModelStreamingMode with values such as Atomic can ensure that the entire model and all of its descendants are present if the parent model exists on the client, or you can use WaitForChild() when atomicity is not desired.
Inheritance¶
Object → Instance → PVInstance → Model
Nova inheritance: Instance → PVInstance → Model
Known subclasses: Actor, BackpackItem, ProceduralModel, RootInstance, Status, WorldRoot
Properties¶
ModelStreamingMode Supported Property Stored streaming preference. Nova's streaming path does not read it.
Stored streaming preference. Nova's streaming path does not read it.
Nova stores and replicates the enum, but the current instance-streaming implementation does not use this per-model preference.
PrimaryPart Supported Property The primary part of the Model, or nil if not explicitly set.
The primary part of the Model, or nil if not explicitly set.
Points to the primary part of the Model. The primary part is the BasePart that acts as the physical reference for the pivot of the model. That is, when parts within the model are moved due to physical simulation or other means, the pivot will move in sync with the primary part.
Note that Models do not have PrimaryPart set by default.
If you are creating a model that needs to be acted upon by physics, you
should manually set this property in Studio or within a script. If the
primary part is not set, the pivot will remain at the same location in
world space, even if parts within the model are moved.
Also note that when setting this property, it must be a BasePart
that is a descendant of the model. If you try to set
Model.PrimaryPart to a BasePart that is not a
descendant of the model, it will be set to that part but reset to nil
during the next simulation step — this is legacy behavior to support
scripts which assume they can temporarily set the primary part to a
BasePart which isn't a descendant of the model.
The general rule for models is that:
- Models whose parts are joined together via physical joints such as WeldConstraints or Motor6Ds should have a primary part assigned. For example, Roblox character models have their Model.PrimaryPart set to the HumanoidRootPart by default.
- Static (usually Anchored) models which stay in one place unless a script explicitly moves them don't require a Model.PrimaryPart and tend not to benefit from having one set.
WorldPivot Supported Property Determines where the pivot of a Model which does not have a set Model.PrimaryPart is located.
This property determines where the pivot of a Model which does not have a set Model.PrimaryPart is located. If the Model does have a PrimaryPart, the pivot of the Model is equal to the pivot of that primary part instead, and this WorldPivot property is ignored.
For a newly created Model, its pivot will be treated as the center of the bounding box of its contents until the first time its Model.WorldPivot property is set. Once the world pivot is set for the first time, it is impossible to restore this initial behavior.
Most commonly, moving the model with the Studio tools, or with model movement functions such as PVInstance.PivotTo() and Model.MoveTo(), will set the world pivot and thus end this new model behavior.
The purpose of this behavior is to allow Luau code to get a sensible pivot simply by creating a new model and parenting objects to it, avoiding the need to explicitly set Model.WorldPivot every time you create a model in code.
Methods¶
BreakJoints Supported Function Deprecated Breaks connections between BaseParts, including surface connections with any adjacent parts, WeldConstraints and all Welds and other JointInstances.
Breaks connections between BaseParts, including surface connections with
any adjacent parts, WeldConstraints, and all
Welds and other JointInstances.
When BreakJoints is used on a Player character Model, the character's Humanoid will die as it relies on the Neck joint.
Note that although joints produced by surface connections with adjacent Parts can technically be recreated using Model.MakeJoints(), this will only recreate joints produced by surfaces. Developers should not rely on this as following the joints being broken parts may no longer be in contact with each other.
breakJoints Supported Function Deprecated
No description available.
GetBoundingBox Supported Function Returns a description of a volume that contains all parts of a Model.
Returns a description of a volume that contains all parts of a Model.
This function returns a description of a volume that contains all BasePart children within a Model. The volume's orientation is based on the orientation of the PrimaryPart, and matches the selection box rendered in Studio when the model is selected. Mirroring the behavior of Terrain.FillBlock(), it returns a CFrame representing the center of that bounding box and a Vector3 representing its size. The size may be inaccurate at runtime if physics constraints are acting upon the parts within the Model.
The orientation of the bounding box matches the orientation of the Pivot - either the pivot of the PrimaryPart (if present) or the WorldPivot of the model.
GetExtentsSize Supported Function 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.
Returns the size of the smallest bounding box that contains all of the BaseParts in the Model. The orientation matches the orientation of the Pivot - either the pivot of the PrimaryPart (if present) or the WorldPivot of the model.
Note this function only returns the size of the smallest bounding box, and the developer must employ their own method to obtain the position of the bounding box.
GetModelCFrame Supported Function Deprecated This value historically returned the CFrame of a central position in the model.
This value historically returned the CFrame of a central position in the model.
GetModelSize Supported Function Deprecated Returns the Vector3 size of the Model.
GetPivot Supported Function Gets the pivot of a PVInstance.
This function gets the pivot of a PVInstance. This is often used with PVInstance.PivotTo() to move a model.
Models and BaseParts are both PVInstances ("Position Velocity Instances") and so both have this function.
GetPrimaryPartCFrame Supported Function Deprecated Returns the CFrame of the model's Model.PrimaryPart. This function will throw an error if no primary part exists for the Model.
This function has been superseded by PVInstance.GetPivot() which acts as a replacement and does not change your code's behavior. Use PVInstance.GetPivot() for new work and migrate your existing Model.GetPrimaryPartCFrame() calls when convenient.
Returns the CFrame of the model's Model.PrimaryPart.
This function is equivalent to the following.
Model.PrimaryPart.CFrame
Note this function will throw an error if no primary part exists for the
Model. If this behavior is not desired developers can do the
following, which will be equal to nil if there is no primary part.
local cFrame = Model.PrimaryPart and Model.PrimaryPart.CFrame
MakeJoints Supported Function Deprecated 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.
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.
SurfaceType based joining is deprecated. Don't use MakeJoints for new projects. Use WeldConstraints and HingeConstraints instead.
Goes through all Parts in the Model and creates joints between the specified Parts and any planar touching surfaces, depending on the parts' surfaces.
- Smooth surfaces will not create joints
- Glue surfaces will create a Glue joint
- Weld will create a Weld joint with any surface except for Unjoinable
- Studs, Inlet, or Universal will each create a Snap joint with either of other the other two surfaces (e.g. Studs with Inlet and Universal)
- Hinge and Motor surfaces create Rotate and RotateV joint instances
This function doesn't work if the Part is not a descendant of Workspace. Therefore, you must first ensure the Model is parented to Workspace before using MakeJoints.
makeJoints Supported Function Deprecated Use MakeJoints() instead
Use MakeJoints() instead
move Supported Function Deprecated Use MoveTo() instead
Use MoveTo() instead
MoveTo Supported Function Moves the PrimaryPart to the given position. If a primary part has not been specified, the root part of the model will be used.
Moves the PrimaryPart to the given position. If a primary part has not been specified, the root part of the model will be used, but the root part is not deterministic and it is recommended that you always set a primary part when using MoveTo().
If there are any obstructions where the model is to be moved, such as Terrain or other BaseParts, the model will be moved vertically upward until there is nothing in the way. If this behavior is not desired, PVInstance.PivotTo() should be used instead.
Note that rotation is not preserved when moving a model with MoveTo(). It is recommended to use either TranslateBy() or PVInstance.PivotTo() if the current rotation of the model needs to be preserved.
moveTo Supported Function Deprecated
No description available.
PivotTo Supported Function Transforms the PVInstance along with all of its descendant PVInstances such that the pivot is now located at the specified CFrame.
Transforms the PVInstance along with all of its descendant PVInstances such that the pivot is now located at the specified CFrame. This is the primary function that should be used to move Models via scripting.
BaseParts are moved in this way by having their CFrame transformed by the necessary offset. Models are moved in this way by having their Model.WorldPivot transformed by the necessary offset.
Note that for efficiency purposes, Object.Changed events are not fired for Position and Orientation of BaseParts moved in this way; they are only fired for CFrame.
When calling PivotTo on Models, the offsets of the descendant parts and models are cached, such that subsequent calls to PivotTo on the same model do not accumulate floating point drift between the parts making up the model.
Models and BaseParts are both PVInstances ("Position Velocity Instances") and so both have this function.
ResetOrientationToIdentity Supported Function Deprecated Resets the rotation of the model's parts to the previously set identity rotation, which is done through the Model.SetIdentityOrientation() method.
Resets the rotation of the model's parts to the previously set identity rotation, which is done through the Model.SetIdentityOrientation() method.
SetIdentityOrientation Supported Function Deprecated Sets the identity rotation of the given model, allowing you to reset the rotation of the entire model later, through the use of the ResetOrientationT…
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.
SetPrimaryPartCFrame Supported Function Deprecated 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 of…
This function has been superseded by PVInstance.PivotTo() which acts as a more performant replacement and does not change your code's behavior. Use PVInstance.PivotTo() for new work and migrate your existing Model.SetPrimaryPartCFrame() calls when convenient.
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.
Note, this function will throw an error if no Model.PrimaryPart exists for the model. This can cause issues if, for example, the primary part was never set or has been destroyed.
TranslateBy Supported Function Shifts a Model by the given Vector3 offset, preserving the model's orientation. If another BasePart or Terrain already exists at the new position the…
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.
The translation is applied in world space rather than object space, meaning even if the model's parts are orientated differently it will still move along the standard axis.
Inherited members¶
Inherited from PVInstance: 9 properties, 36 methods, 7 events. They are documented on the base class page.
6 modern Roblox member(s) are not implemented yet — expand to inspect
Members declared by Roblox's Model class (or by a missing base class) that Nova does not expose. Use this list to scope a migration; the compatibility guide has the recommended workaround.
Properties¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
LevelOfDetail |
LevelOfDetail: ModelLevelOfDetail |
Not yet | Sets the level of detail on the model for experiences with instance streaming enabled. | PluginSecurity |
Methods¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
AddPersistentPlayer |
Model:AddPersistentPlayer(playerInstance: Player = nil): null |
Not yet | Sets this model to be persistent for the specified player. ModelStreamingMode must be set to [PersistentPerPlayer](../enums/ModelStreaming… | — |
GetPersistentPlayers |
Model:GetPersistentPlayers(): Instances |
Not yet | Returns all the Player objects that this model object is persistent for. Behavior varies based on whether this method is called from a Script o… | — |
GetScale |
Model:GetScale(): float |
Not yet | 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(). | — |
RemovePersistentPlayer |
Model:RemovePersistentPlayer(playerInstance: Player = nil): null |
Not yet | Makes this model no longer persistent for the specified player. ModelStreamingMode must be set to [PersistentPerPlayer](../enums/ModelStre… | — |
ScaleTo |
Model:ScaleTo(newScaleFactor: float): null |
Not yet | 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 a… | — |
Roblox reference: Model
Generated from Nova's API dump and Roblox creator-docs. Nova-only members come from the engine's reflection metadata.