Model

Afficher les obsolètes

*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.

Les modèles sont des objets de conteneur, ce qui signifie qu'ils regroupent des objets ensemble.Ils sont mieux utilisés pour contenir des collections de BaseParts et ont un certain nombre de fonctions qui étendent leur fonctionnalité.

Les modèles sont destinés à représenter des groupements géométriques .Si votre regroupement n'a pas d'interprétation géométrique, par exemple une collection de Scripts , utilisez un Folder à la place.

Les modèles dont les parties constitutives sont jointes avec des articulations (de sorte qu'elles puissent se déplacer ou être détruites via une simulation de physique) ont généralement un configurerPrimaryPart, car il spécifie quelle partie du modèle la rotule et la boîte de contour s'abonnerlorsque le modèle se déplace.Les modèles statiques qui restent à un endroit ne bénéficient pas d'avoir un ensemble de parties primaires.

Les modèles ont une large gamme d'applications, y compris les personnages de joueurs Roblox.Ils ont également un certain nombre de comportements uniques qui sont importants à garder à l'esprit :

  • Lorsqu'un Humanoid et un Part nommé Tête sont parentés sous un modèlisation, une interface de nom/santé apparaîtra au-dessus du modèlisation; voir Nom/affichage de la santé du personnage pour les détails.
  • Si la position d'une partie sur l'axe Y atteint la valeur Workspace.FallenPartsDestroyHeight, et qu'elle était le dernier objet à l'intérieur d'un Model, le modèle sera également détruit.
  • Lorsqu'il est utilisé dans un endroit avec Workspace.StreamingEnabled défini sur vrai, la valeur de ModelStreamingMode contrôle divers comportements autour de la façon dont le modèle et tous les descendants sont répliqués et/ou supprimés des clients.En outre, la valeur de LevelOfDetail a un impact sur la rendu du modèlisation.

Comme pour tous les types Instance types, le fait qu'un parent Model soit répliqué vers un client ne garantit pas que tous ses enfants soient répliqués.Ceci est particulièrement important si ces instances sont accessibles par du code s'exécutant sur le client, comme dans un LocalScript .L'utilisation de ModelStreamingMode avec des valeurs telles que Atomic peut garantir que l'ensemble du modèle et tous ses descendants sont présents si le modèle parent existe sur le client, ou vous pouvez utiliser WaitForChild() lorsque l'atomisation n'est pas souhaitée.

Échantillons de code

The following sample includes a basic function that takes a table of objects and parents them into a new Model, returning that Model.

Basic Model Instantiation

local function groupObjects(objectTable)
local model = Instance.new("Model")
for _, object in pairs(objectTable) do
object.Parent = model
end
return model
end
local objects = {
Instance.new("Part"),
Instance.new("Part"),
}
groupObjects(objects)

Résumé

Propriétés

  • Sécurité des plugins
    Lecture parallèle

    Définit le niveau de détail sur le modèle pour les expériences avec streaming d'instance activé.

  • Contrôle le comportement de streaming du modèle sur Models lorsque le streaming d'instance est activé.

  • Lecture parallèle

    La partie principale de la Model ou nil si elle n'est pas explicitement configurer.

  • Non répliqué
    Non scriptable
    Lecture parallèle

    Propriété réservée aux éditeurs utilisée pour dimensionner le modèle autour de son pivot. Le réglage de cette propriété déplacera la mesure comme si Model/ScaleTo était appelé sur elle.

  • Non répliqué
    Lecture parallèle

    Détermine où se trouve le pivot d'un Model qui ne fait pas **** avoir un ensemble Model.PrimaryPart.

Propriétés hérités de PVInstance

Méthodes

  • AddPersistentPlayer(playerInstance : Player):()

    Définit ce modèle pour être persistant pour le joueur spécifié.Model.ModelStreamingMode doit être défini sur PersistantParJoueur pour que le comportement soit modifié en raison de l'ajout.

  • Renvoie une description d'un volume qui contient toutes les parties d'un modèle.

  • Renvoie la taille de la plus petite boîte de bordure qui contient tout le BaseParts dans le Model, alignée sur le Model.PrimaryPart si elle est configurer.

  • Renvoie tous les objets Player que cet objet de modèle est persistant pour.Le comportement varie en fonction de si cette méthode est appelée à partir d'un Script ou d'un LocalScript .

  • Renvoie la taille canonique du modèlisation, qui est par défaut de 1 pour les modèles créés récemment et qui changera lorsqu'elle sera mise à l'échelle via Model/ScaleTo.

  • MoveTo(position : Vector3):()

    Déplace le PrimaryPart à la position donnée. Si aucune partie principale n'a été spécifiée, la partie racine du modèle sera utilisée.

  • RemovePersistentPlayer(playerInstance : Player):()

    Rend ce modèle non persistant pour le joueur spécifié.Model.ModelStreamingMode doit être défini sur PersistantParJoueur pour que le comportement soit modifié en raison de la suppression.

  • ScaleTo(newScaleFactor : number):()

    Définit le facteur d'échelle du modèlisation, ajustant la taille et l'emplacement de toutes les instances descendantes afin qu'elles aient ce facteur d'échelle par rapport à leurs tailles et emplacements initiaux lorsque le facteur d'échelle était de 1.

  • TranslateBy(delta : Vector3):()

    Déplace un Model par le décentragedonné Vector3, en conservant l'orientation du modèlisation.Si un autre BasePart ou Terrain existe déjà à la nouvelle position, alors le Model couvrira cet objet.

Méthodes hérités de PVInstance

Propriétés

Sécurité des plugins
Lecture parallèle

Définit le niveau de détail sur le modèle pour les expériences avec la diffusion en continu d'instance activée.

Lorsqu'il est défini à StreamingMesh , un maillage «imposteur» de résolution inférieure (maillage grossier qui enveloppe toutes les parties enfant du modèlisation) rendu en dehors du rayon de diffusion.

Lorsque la valeur est définie sur Disabled ou Automatic, les mailles de résolution inférieure ne seront pas affichées.

ModelStreamingMode

Lecture parallèle

Contrôle comment Models sont diffusés à l'intérieur et à l'extérieur lorsque l'instance streaming est activée.Le comportement dépend de l'Enum sélectionné.N'a aucun effet lorsque le streaming n'est pas activé.

Cette propriété ne doit être modifiée dans Studio que via la fenêtre propriétés lorsque le streaming est activé, ou dans Scripts , mais jamais dans LocalScripts (le faire peut entraîner un comportement non défini).

PrimaryPart

Lecture parallèle

Pointe vers la partie principale du Model.La partie principale est la BasePart qui agit comme référence physique pour le pivot du modèlisation.C'est-à-dire que lorsque des parties dans le modèle sont déplacées en raison de la simulation physique ou d'un autre moyen, le pivot se déplacera en même temps que la partie principale.

Notez que Models n'ont pas PrimaryPart par défaut défini.Si vous créez un modèle qui doit être agi par la physique, vous devez définir manuellement cette propriété dans Studio ou dans un script.Si la partie principale n'est pas pas configurer, le pivot restera à la même position dans l'espace du monde, même si des parties dans le modèle sont déplacées.

Notez également que lorsque vous définissez cette propriété, il doit s'agir d'un BasePart qui est un descendant du modèlisation.Si vous essayez de définir à un qui n'est pas un descendant du modèlisation, il sera défini à cette partie mais réinitialisé à lors de la prochaine étape de simulation — c'est un comportement hérité pour prendre en charge les scripts qui supposent qu'ils peuvent temporairement définir la partie principale sur un qui n'est pas un descendant du modèlisation.

La règle générale pour les modèles est que :

  • Les modèles dont les parties sont jointes par des jointures physiques telles que WeldConstraints ou Motor6Ds devraient avoir une partie principale attribuée.Par exemple, les modèles de personnage Roblox ont leur Model.PrimaryPart défini par défaut sur le HumanoidRootPart .
  • Les modèles statiques (généralement Anchored ) qui restent à un endroit jusqu'à ce qu'un script les déplace explicitement n'ont pas besoin d'un Model.PrimaryPart et ont tendance à ne pas profiter d'avoir un configurer.

Échantillons de code

This code sample creates and throws a dice model, then outputs whether it landed with the blue side facing up. If Model.PrimaryPart was not set, the pivot / bounding box of the dice would rotate, as the parts inside of it are physically simulated during the roll.

Throwing Dice

-- Create a dice model with two halves and attach them together
local diceModel = Instance.new("Model")
diceModel.Name = "ChanceCube"
local diceTop = Instance.new("Part")
diceTop.Size = Vector3.new(4, 2, 4)
diceTop.Position = Vector3.new(0, 1, 0)
diceTop.Color = Color3.new(0, 0, 1)
diceTop.Parent = diceModel
local diceBottom = diceTop:Clone()
diceBottom.Position = Vector3.new(0, -1, 0)
diceBottom.Color = Color3.new(1, 0, 0)
diceBottom.Parent = diceModel
local weld = Instance.new("WeldConstraint")
weld.Part0 = diceTop
weld.Part1 = diceBottom
weld.Parent = diceModel
-- Put the dice up in the air above the workspace origin (does not require a primary part)
diceModel.Parent = workspace
diceModel:PivotTo(CFrame.new(0, 10, 0))
-- Assign the primary part before physical simulation
-- Without this line, the script will always output the same thing and the bounding box of the model will not change orientation
diceModel.PrimaryPart = diceTop
-- Wait a bit before rolling the dice (let it settle onto the floor)
for i = 5, 1, -1 do
print("Rolling dice in...", i)
task.wait(1)
end
diceTop:ApplyAngularImpulse(Vector3.new(15000, 1000, 5000))
diceTop:ApplyImpulse(Vector3.new(0, 3000, 0))
task.wait(1)
-- Wait for the roll to complete
while diceTop.AssemblyLinearVelocity.Magnitude > 0.1 or diceTop.AssemblyAngularVelocity.Magnitude > 0.1 do
task.wait()
end
-- Get the dice orientation, impacted by the primary part
local orientation = diceModel:GetBoundingBox()
if orientation.YVector.Y > 0.5 then
print("It's the boy!")
else
print("It's his mother!")
end

Scale

Non répliqué
Non scriptable
Lecture parallèle

Définir cette propriété dans la fenêtre propriétés va mettre à l'échelle le modèle comme si Model/ScaleTo était appelé dessus, en mettant à l'échelle toutes les instances descendantes du modèlisation, telles que les matériaux, les images et la géométrie 3D des pièces, afin que le modèle ait le facteur d'échelle spécifié par rapport à sa taille originale.

Cette propriété n'est disponible que dans Studio et lancera une erreur si elle est utilisée dans un Script ou LocalScript .Model/ScaleTo et Model/GetScale doivent être utilisés à partir de scripts.

WorldPivot

Non répliqué
Lecture parallèle

Cette propriété détermine où se trouve le pivot d'un qui ne dispose pas de set défini.Si le fait a un , le pivot de la partie principale est égale au pivot de cette partie principale à la place, et cette propriété est ignorée.

Pour un nouveau créé Model , son pivot sera traité comme le centre de la boîte de conteneur de ses contenus jusqu'à ce que la propriété première fois de son Model.WorldPivot soit configurer.Une fois le pivot du monde défini pour la première fois, il est impossible de restaurer ce comportement initial.

Le plus souvent, déplacer le modèle avec les outils de Studio, ou avec des fonctions de déplacement de modèle telles que PVInstance:PivotTo() et Model:MoveTo(), définira le pivot du monde et mettra fin à ce nouveau comportement du modèle.

Le but de ce comportement est de permettre au code Luau d'obtenir un pivot sensé simplement en créant un nouveau modèle et en le parentant, évitant le besoin de définir explicitement Model.WorldPivot à chaque fois que vous créez un modèle en code.


local Workspace = game:GetService("Workspace")
local model = Instance.new("Model")
Workspace.BluePart.Parent = model
Workspace.RedPart.Parent = model
model.Parent = Workspace
print(model:GetPivot()) -- Currently equal to the center of the bounding box containing "BluePart" and "RedPart"
model:PivotTo(CFrame.new(0, 10, 0)) -- This works without needing to explicitly set "model.WorldPivot"

Échantillons de code

This code sample shows a custom function for resetting the pivot of a model back to the center of that model's bounding box.

Reset Pivot

local function resetPivot(model)
local boundsCFrame = model:GetBoundingBox()
if model.PrimaryPart then
model.PrimaryPart.PivotOffset = model.PrimaryPart.CFrame:ToObjectSpace(boundsCFrame)
else
model.WorldPivot = boundsCFrame
end
end
resetPivot(script.Parent)

Méthodes

AddPersistentPlayer

()

Paramètres

playerInstance: Player
Valeur par défaut : "nil"

Retours

()

GetBoundingBox

Cette fonction renvoie une description d'un volume qui contient tous les enfants BasePart dans un Model .L'orientation du volume est basée sur l'orientation du PrimaryPart , et correspond à la boîte de sélection rendue dans Studio lorsque le modèle est sélectionné.En miroir du comportement de Terrain:FillBlock() , il renvoie un CFrame représentant le centre de cette boîte de bordure et un Vector3 représentant sa taille.

S'il n'y a pas de PrimaryPart pour le modèlisation, la boîte de bordure sera alignée sur les axes du monde.


local Workspace = game:GetService("Workspace")
local model = Workspace.Model
local part = Workspace.Part
local orientation, size = model:GetBoundingBox()
-- Redimensionner et positionner une partie égale à la boîte de bordure du modèlisation
part.Size = size
part.CFrame = orientation

Retours

Un CFrame représentant l'orientation du volume suivi d'un Vector3 représentant la taille du volume.

GetExtentsSize

Renvoie la taille de la plus petite boîte de bordure qui contient tout le BaseParts dans le Model.Si Model.PrimaryPart existe, la boîte de bord sera alignée sur cette partie.Si une partie principale n'a pas été définie, la fonction choisira une partie dans le modèle pour aligner la boîte de bordure.Comme la sélection de cette partie n'est pas déterministe, il est recommandé de définir un Model.PrimaryPart pour obtenir des résultats cohérents avec cette fonction.

Notez que cette fonction ne renvoie que la taille de la plus petite boîte de boîte de modélisation, et que le développeur doit utiliser sa propre méthode pour obtenir la position de la boîte de boîte de modélisation.


Retours

La taille des extensions Vector3 de la Model.

Échantillons de code

The code sample below demonstrates how Model.GetExtentsSize can be used to get the size of the bounding box containing the parts.

Model GetExtentsSize

local model = Instance.new("Model")
model.Parent = workspace
local RNG = Random.new()
for _ = 1, 5 do
local part = Instance.new("Part")
part.Anchored = true
part.Size = Vector3.new(RNG:NextNumber(0.05, 5), RNG:NextNumber(0.05, 5), RNG:NextNumber(0.05, 5))
part.Parent = model
end
print(model:GetExtentsSize())

GetPersistentPlayers

Instances

Lorsque cette méthode est appelée à partir d'un Script , elle renvoie tous les objets Player persistants pour lesquels ce modèle est persistant.Lorsqu'il est appelé à partir d'un LocalScript , cette méthode ne vérifie que si ce modèle est persistant pour le LocalPlayer .


Retours

Instances

Une table avec tous les objets Player persistants pour lesquels cet objet de modèle est persistant.

GetScale

Les modèles contiennent un facteur de canal persistant, qui commence à 1 pour les modèles nouvellement créés et change lorsque le modèle est échelonné en appelant Model/ScaleTo .Cette fonction renvoie le facteur d'échelle canonique actuel du modèlisation.

Le facteur d'échelle actuel n'a pas directement d'impact sur la taille des instances sous le modèlisation.Il est utilisé à des fins d'auteur de contenu et de script pour se souvenir comment le modèle a été redimensionné par rapport à sa taille originale.

Au sein d'une session donnée, le modèle enregistrera les informations de taille originales précises des instances descendantes après le premier appel Model/ScaleTo .Cela signifie que l'appel de suivi de vous ramènera exactement la configuration originale du modèle sans dérive de point flottant.Éviter la dérive de point flottant est la motivation d'avoir une fonction Scale vers au lieu d'une fonction Scale par .

Le facteur d'échelle a un impact sur le comportement du moteur d'une manière : le facteur d'échelle d'un modèle sera appliqué aux décalages joints de animations joués sur un AnimationController sous ce modèlisation, afin que les animations animées soient correctement rejouées même lorsqu'elles sont redimensionnées.


Retours

Le facteur de taille canonique actuel du modèlisation.

Échantillons de code

This code sample demonstrates substituting in a replacement for all the copies of a tree model using PivotTo and ScaleTo. The pivot and scale of the models are used as a reference ensuring that the relative sizes and locations of the replacement models match those of the originals.

Substituting in a replacement model using PivotTo and ScaleTo

local CollectionService = game:GetService("CollectionService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- Find all the models with the tag we want to replace
local items = CollectionService:GetTagged("Tree")
local newModel = ReplicatedStorage.FancyTreeReplacementModel
for _, item in items do
-- Make the new item and scale / position it where the old one was
local newItem = newModel:Clone()
newItem:ScaleTo(item:GetScale())
newItem:PivotTo(item:GetPivot())
-- Add the same tag to the replacement
CollectionService:AddTag(newItem, "Tree")
-- Delete the old item and parent the new one
newItem.Parent = item.Parent
item:Destroy()
end

MoveTo

()

Déplace le PrimaryPart à la position donnée.Si une partie principale n'a pas été spécifiée, la partie racine du modèle sera utilisée, mais la partie racine n'est pas déterministe et il est recommandé de toujours définir une partie principale lors de l'utilisation de MoveTo() .

S'il y a des obstacles où le modèle doit être déplacé, comme Terrain ou autre BaseParts, le modèle sera déplacé verticalement vers le haut jusqu'à ce qu'il n'y ait rien sur le chemin.Si ce comportement n'est pas souhaité, PVInstance:PivotTo() devrait être utilisé à la place.

Notez que la rotation n'est pas conservée lors du déplacement d'un modèle avec MoveTo() .Il est recommandé d'utiliser TranslateBy() ou PVInstance:PivotTo() si la rotation actuelle du modèle doit être préservée.

Paramètres

position: Vector3

Le Vector3 le Model est déplacé vers.

Valeur par défaut : ""

Retours

()

Échantillons de code

This sample demonstrates how Model:MoveTo avoids collisions.

A simple two part Model is created, and its PrimaryPart is set. An large obstruction part is placed next to it.

After 5 seconds Model:MoveTo is used to direct the model to move inside the obstruction part. However, as MoveTo will not move a model inside of an obstruction the Model is moved up on the Y axis and placed above the obstruction.

Model MoveTo

local START_POSITION = Vector3.new(-20, 10, 0)
local END_POSITION = Vector3.new(0, 10, 0)
local model = Instance.new("Model")
model.Parent = workspace
local part1 = Instance.new("Part")
part1.Size = Vector3.new(4, 4, 4)
part1.Position = START_POSITION
part1.Anchored = true
part1.BrickColor = BrickColor.new("Bright yellow")
part1.Parent = model
local part2 = Instance.new("Part")
part2.Size = Vector3.new(2, 2, 2)
part2.Position = START_POSITION + Vector3.new(0, 3, 0)
part2.Anchored = true
part2.BrickColor = BrickColor.new("Bright blue")
part2.Parent = model
model.PrimaryPart = part1
model.Parent = workspace
local obstruction = Instance.new("Part")
obstruction.Name = "Obstruction"
obstruction.Size = Vector3.new(10, 10, 10)
obstruction.Position = Vector3.new(0, 10, 0)
obstruction.Anchored = true
obstruction.BrickColor = BrickColor.new("Bright green")
obstruction.Parent = workspace
task.wait(3)
model:MoveTo(END_POSITION)

RemovePersistentPlayer

()

Paramètres

playerInstance: Player
Valeur par défaut : "nil"

Retours

()

ScaleTo

()

Les modèles contiennent un facteur de taille canonique persistant, qui commence à 1 pour les modèles créés récemment.Cette fonction met à l'échelle le modèlisation, autour de la position de pivot, par rapport à la façon dont il regarderait un facteur d'échelle de 1.Pour accomplir cela, il fait deux choses :

  • Définit le facteur d'échelle actuel du modèle sur la valeur spécifiée
  • Redimensionne et répositionne toutes les instances descendantes en conséquence

L'ajustement des localisations est effectué autour de la localisation pivot.

Toutes les propriétés « géométriques » des instances descendantes seront redimensionnées.Cela inclut évidemment les tailles des parties, mais voici quelques autres exemples de propriétés qui sont dimensionnées :

  • La longueur des jointures comme WeldConstraints , et Class.Rope|Ropes
  • Vélocités et forces physiques comme Hinge.MaxServoTorque
  • Propriétés visuelles comme les tailles des émetteurs de particules
  • D'autres propriétés de longueur comme Sound.RollOffMinDistance

Paramètres

newScaleFactor: number
Valeur par défaut : ""

Retours

()

TranslateBy

()

Déplace un Model par le décentragedonné Vector3, en conservant l'orientation du modèlisation.Si un autre BasePart ou Terrain existe déjà à la nouvelle position, alors le Model couvrira cet objet.

La traduction est appliquée dans l'espace du monde plutôt que dans l'espace d'objets, ce qui signifie que même si les parties du modèlisationsont orientées différemment, elles se déplaceront toujours le long de l'axe standard.

Paramètres

delta: Vector3

Le Vector3 pour traduire le Model par.

Valeur par défaut : ""

Retours

()

Échantillons de code

This sample demonstrates how Model:TranslateBy ignores collisions and respects the orientation of the model.

A simple two part Model is created, rotated 45 degrees on the Y axis, and its PrimaryPart is set. An large obstruction part is placed next to it.

After 5 seconds Model:TranslateBy is used to direct the model to move inside the obstruction part. The model will move inside of the obstruction and maintain it's current orientation.

Model TranslateBy

local START_POSITION = Vector3.new(-20, 10, 0)
local END_POSITION = Vector3.new(0, 10, 0)
local model = Instance.new("Model")
local part1 = Instance.new("Part")
part1.Size = Vector3.new(4, 4, 4)
part1.CFrame = CFrame.new(START_POSITION) * CFrame.Angles(0, math.rad(45), 0)
part1.Anchored = true
part1.BrickColor = BrickColor.new("Bright yellow")
part1.Parent = model
local part2 = Instance.new("Part")
part2.Size = Vector3.new(2, 2, 2)
part2.CFrame = part1.CFrame * CFrame.new(0, 3, 0)
part2.Anchored = true
part2.BrickColor = BrickColor.new("Bright blue")
part2.Parent = model
model.PrimaryPart = part1
model.Parent = workspace
local obstruction = Instance.new("Part")
obstruction.Name = "Obstruction"
obstruction.Size = Vector3.new(10, 10, 10)
obstruction.Position = Vector3.new(0, 10, 0)
obstruction.Transparency = 0.5
obstruction.Anchored = true
obstruction.BrickColor = BrickColor.new("Bright green")
obstruction.Parent = workspace
task.wait(3)
-- use TranslateBy to shift the model into the obstruction
model:TranslateBy(END_POSITION - START_POSITION)

Évènements