Modèles procéduraux

ProceduralModels sont un type de Model drivé par des paramètres qui vous permet de créer et de générer des objets 3D à l'aide de code. Au lieu de modifier manuellement le contenu d'un modèle, vous définissez sa structure à travers un module générateur et un ensemble d'attributs. Lorsque ces attributs changent, ou lorsque le modèle est redimensionné, le générateur s'exécute automatiquement pour mettre à jour le modèle.

Les modèles procéduraux facilitent :

• L'ajustement des modèles de manière non destructive en changeant les paramètres au lieu de les reconstruire. Par exemple, changer la valeur de StepSize sur un escalier en spirale régénère automatiquement l'escalier avec le nombre de marches mis à jour.
• L'intégration automatique avec les systèmes Studio existants comme l'annulation/rétablissement, Team Create, et les outils de glissement en implémentant une seule fonction OnGenerate.
• Le maintien d'une haute performance, avec les modèles se comportant comme des objets standards jusqu'à ce que leurs paramètres changent.
• La génération de contenu à la fois au moment de l'édition et au moment de l'exécution, en utilisant le même système dans Studio et dans le jeu.
• Le partage de modèles paramétrés sur le Creator Store, rendant les actifs plus flexibles et personnalisables.

Insérer des modèles procéduraux

Vous pouvez ajouter des modèles procéduraux à votre jeu de plusieurs manières :

• Insérer manuellement un objet ProceduralModel dans l'espace de travail. Cette option inclut un module générateur ModuleScript modèle pour vous aider à démarrer.

  

• Générer un modèle procédural à l'aide de Assistant ou du serveur MCP de Roblox Studio.

• Insérer un modèle procédural depuis le Creator Store pour utiliser ou personnaliser un modèle existant.

Pour personnaliser la manière dont les modèles procéduraux sont générés, vous pouvez définir vos propres modules générateurs.

Fonction OnGenerate

La fonction OnGenerate est au cœur de chaque ProceduralModel sous la forme de OnGenerate(params, targetContainer).

Cette fonction définie par le développeur est responsable de la génération du contenu du modèle en fonction des paramètres fournis et d'écriture des résultats dans le conteneur donné.

OnGenerate a deux principales responsabilités :

• Traiter les paramètres d'entrée pour déterminer la structure du modèle
• Écrire les résultats générés selon cette structure dans le targetContainer fourni

Les sections suivantes décrivent :

• Quand et comment le moteur invoque OnGenerate
• Comment le moteur traite le contenu écrit dans le targetContainer

Modules générateurs

La fonction OnGenerate est définie à l'intérieur d'un ModuleScript connu sous le nom de module générateur. Le ProceduralModel identifie quel module générateur utiliser par sa propriété Generator.

Les modules générateurs sont des modules Luau standards, mais sont requis directement par le moteur dans le cadre du processus de génération. Ils suivent une structure définie et renvoient une table avec des champs standardisés.

Structure du module générateur
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

Les champs standardisés incluent :

• Attributes: Une map qui définit les noms des paramètres et leurs valeurs par défaut.
• OnGenerate: La fonction qui reçoit une table params et un targetContainer.

La table params à l'intérieur de OnGenerate inclut :

• Attributes: Une table qui contient soit les attributs définis par le module, soit tous les attributs du modèle si aucun n'est spécifié.
• Size: Un paramètre qui reflète les dimensions du modèle à une échelle de un.
• Pause: Une méthode qui permet à la génération de se suspendre efficacement lors de tâches de génération complexes.

La fonction OnGenerate devrait générer du contenu autour de l'origine dans le targetContainer. Elle ne devrait jamais modifier directement la hiérarchie principale de DataModel.

Paramètres

Les paramètres sont les entrées qui contrôlent la génération. Celles-ci incluent la propriété intégrée Size du ProceduralModel, ainsi que des attributs personnalisés spécifiés dans le module générateur. Ces paramètres explicites sont passés directement à OnGenerate. Les paramètres implicites, tels que le code source du module ou l'état de sandboxing, déclenchent également la régénération lorsqu'ils changent mais ne sont pas passés à OnGenerate.

L'ensemble complet des paramètres inclut :

• Explicites :

  • Size: Définit la région autour de l'origine où le contenu est généré.
  • Attributes: Une map contenant les valeurs d'attributs d'entrée actuelles.
• Implicites :

  • Generator: Le module qui fournit la logique de génération.
  • Code source: Modifications du code Luau du module générateur.
  • Sandboxing: Modifications de l'état de sandboxing du module générateur.

Comportement de régénération

Pour maintenir la performance et simplifier les interactions API, OnGenerate n'est pas appelé immédiatement lorsque les paramètres changent. Au lieu de cela, le ProceduralModel est marqué comme sale, indiquant que la régénération est en attente. Cette régénération en attente se produit généralement plus tard dans le même frame.

Si la régénération échoue, l'état sale est effacé jusqu'à ce qu'un autre changement de paramètre se produise. Si un lieu est enregistré pendant que le modèle est sale, l'état persiste et le modèle est ajouté à la file d'attente de génération la prochaine fois que le jeu se charge.

Processus d'exécution

Lorsque le temps de traitement est disponible, le moteur régénère les modèles sales en exécutant les étapes suivantes :

1. Exige le module générateur, se suspendant si nécessaire.
2. Démarre un nouveau fil pour le processus de génération.
3. Construit la table de paramètres, normalisant le Size par rapport à l'échelle actuelle du modèle.
4. Applique les valeurs d'attribut par défaut pour tout attribut manquant.
5. Initialise un GeneratedFolder temporaire comme targetContainer.
6. Invoque OnGenerate.
7. Après le retour de OnGenerate :

   • Si c'est réussi, migre les résultats dans le targetContainer vers le ProceduralModel.
   • Si la génération échoue, utilise un espace réservé de défaillance à la place.

Si les paramètres changent à nouveau pendant qu'un fil de génération est suspendu, la génération en attente est annulée et redémarrée avec les paramètres mis à jour.

Résultats de génération

Placer les résultats générés dans le modèle implique les étapes suivantes :

1. Termine tout fil enfant qui a fuité pendant la génération.
2. Positionne les résultats en utilisant PivotTo.
3. Si l'échelle du modèle n'est pas 1, utilise ScaleTo pour annuler la normalisation de la taille.
4. Parent les résultats vers le GeneratedFolder du modèle.
5. Si le module générateur est en sandboxing, s'assure que les ModuleScripts dans le résultat ne dépassent pas les capacités du module générateur.
6. Remplit tous les attributs manquants du modèle avec leurs valeurs par défaut.
7. Efface l'état sale du modèle.

Détails de génération

En plus du flux de génération principal, les détails suivants décrivent les comportements et considérations qui affectent le fonctionnement de la génération des ProceduralModel.

Dimensionnement

En raison de la normalisation de l'échelle appliquée lors de la génération, ProceduralModel prend en charge plusieurs flux de travail de dimensionnement :

• Changer la propriété Size régénère le modèle avec un nouveau contenu.
• Changer l'Échelle redimensionne uniformément les résultats existants à l'aide de ScaleTo.

Délais

En tant que mesure de sécurité, un module générateur qui effectue trop de travail sans se suspendre est terminé. Si la génération atteint une erreur "Script Timeout", ajoutez des appels supplémentaires à parameters:Pause() pour permettre au moteur de différer le travail restant à une frame ultérieure.

Appeler parameters:Pause() est très peu coûteux et revient généralement immédiatement pendant l'exécution normale du générateur, il peut donc être appelé librement au début des boucles sans affecter la performance.

Historique d'annulation

Les résultats générés sont regroupés avec le changement de paramètre qui les a déclenchés à l'aide de remplacements de point de chemin d'annulation. Si plusieurs changements de paramètres se produisent dans une seule frame, les résultats sont associés au point de chemin le plus récent.

Sandboxing

ProceduralModel prend en charge le sandboxing. Tous les modèles procéduraux tiers que vous insérez depuis le Creator Store sont sandboxés par défaut pour éviter les modifications indésirables de votre jeu.

Le code de génération s'exécute dans le contexte du module générateur et utilise l'état de sandboxing de ce module. Ces paramètres ne sont pas visibles par défaut. Pour les afficher ou les modifier, définissez Workspace.SandboxedInstanceMode = Experimental. Cela expose les propriétés Sandboxed et Capabilities sur le ModuleScript.

Un module générateur sandboxé nécessite généralement au moins les capacités suivantes :

• RunServerScript (pour exécuter le module)
• CreateInstances
• Basic

Le sandboxing pour le ProceduralModel et son module générateur sont indépendants l'un de l'autre. Lorsqu'il est appliqué au module générateur, le sandboxing n'affecte pas les scripts d'exécution normaux au sein du ProceduralModel. Cela vous permet de garder la génération en temps d'édition strictement restreinte sans impacter le comportement dans le jeu.

Imbrication

Les ProceduralModels peuvent générer d'autres ProceduralModels. Lorsque cela se produit, le moteur traite la hiérarchie de haut en bas dans la même étape de génération lorsque cela est possible, les modèles plus profondément imbriqués étant générés en dernier.

Limitations

• La génération n'est pas prise en charge au sein des instances Actor.
• Les modèles ne peuvent pas être convertis en paquets.
• Les joints créés lors de l'utilisation de glisseurs avec les Surfaces de Jointure activées ne sont pas préservés lors des régénérations de ProceduralModel.