Les Entity Templates sont le système d'entités réutilisables de Cave.

Ils permettent de construire une configuration d'entité une fois, de la sauvegarder comme asset, et de placer des instances de celle-ci dans différentes scènes.

Si vous venez d'un autre moteur, vous pouvez considérer les Entity Templates comme le système de prefab de Cave. Si vous débutez avec les moteurs de jeu, pensez-y comme des recettes d'objets réutilisables.

Au lieu de reconstruire la même porte, ennemi, objet à ramasser, ou widget UI à chaque fois, vous créez la configuration une fois et la réutilisez où vous en avez besoin.

Qu'est-ce qu'une Entity Template ?

Une Entity Template est un asset qui stocke une structure d'entité.

Elle peut inclure :

Une entité racine (chaque template DOIT avoir une et une seule entité racine).
Des entités enfants.
Des composants.
Les réglages des composants.
Des références vers des assets.
Des propriétés.
Des tags.

Quand vous placez un template dans une scène, Cave crée une instance de ce template.

L'instance utilise l'asset template comme base, ce qui signifie qu'elle garde la même structure interne tout en existant comme un objet placé dans une scène spécifique.

Pourquoi les Entity Templates sont importantes

Beaucoup d'objets de jeu ne sont pas juste un maillage unique.

Un objet à ramasser peut inclure :

Un modèle visible.
Un déclencheur.
Une lumière.
Un effet de particules.
Un son.
La logique qui donne la récompense.

Un template vous permet de garder toute cette configuration assemblée.

Utilisez les Entity Templates pour des choses comme :

Personnages joueurs.
Ennemis.
Objets à ramasser.
Portes.
Projectiles.
Véhicules.
Portails.
Volumes de dégâts.
Accessoires.
Éléments UI.
Objets de gameplay réutilisables.

Les templates font gagner du temps, mais maintiennent aussi la cohérence des objets répétés. Si chaque objet de soin vient du même template, vous pouvez améliorer ce template une fois et garder le projet organisé.

Créer une Entity Template

Vous pouvez créer une Entity Template depuis l'Asset Browser ou promouvoir une entité déjà présente dans la scène en template en cliquant-droit dessus dans le Scene Graph ou en appuyant sur Ctrl + T pour promouvoir l'entité sélectionnée.

Un workflow courant consiste à construire l'objet directement dans une scène d'abord, le tester, et ne le transformer en template que lorsque la configuration est utile. Cela se déroule ainsi :

Construire une entité dans une scène.
Ajouter les composants et enfants nécessaires.
Ajuster ses réglages.
Promouvoir en Entity Template.
Réutiliser ce template dans la même scène ou d'autres scènes.

Mais dès que vous êtes sûr de réutiliser cet objet, comme le joueur, les ennemis, les objets à ramasser, etc., il est recommandé de le créer immédiatement, soit dans l'Asset Browser soit par promotion comme indiqué précédemment.

Dans le Scene Graph, le menu d'édition rapide peut promouvoir une entité en template. Le raccourci indiqué par l'éditeur est Ctrl + T.

Asset Template vs Instance de Template

Il est utile de distinguer l'asset template de l'instance placée.

Concept	Signification
Asset template	La configuration d'objet réutilisable stockée dans l'Asset Browser.
Instance template	Une copie placée de ce template dans une scène.

L'asset définit la structure réutilisable.

L'instance est là où cette structure apparaît dans une scène spécifique.

Éditer une Entity Template

Les templates sont édités en tant qu'assets indépendants.

Lorsque vous ouvrez un template pour l'éditer, Cave bascule vers une scène d'édition spécifique où vous pouvez modifier directement la structure interne des entités du template.

L'idée importante est :

> Le template possède sa hiérarchie interne.

Les instances dans la scène utilisent cette hiérarchie, mais ne possèdent pas directement chaque enfant à l'intérieur. Cela maintient toutes les instances connectées à la même configuration réutilisable.

Il est important de noter que cela devient faux une fois que le jeu démarre, car à ce moment-là toute la hiérarchie du template est disponible pour personnalisation. Ainsi, lors de la programmation de votre logique de jeu, vous pouvez interagir avec l'instance d'un Entity Template, ses enfants, etc.

Par exemple, si vous ouvrez un template Enemy et ajoutez un nouvel enfant Health Bar dedans, toutes les instances de ce template d'ennemi bénéficieront de cette mise à jour.

Pourquoi les enfants du template ne sont pas édités directement dans la scène

Quand une instance de template est placée dans une scène, ses enfants internes appartiennent toujours au template. C'est pourquoi Cave protège ces enfants de modification directe dans la scène.

Par exemple, si un template ennemi contient :

Enemy
  Body Mesh
  Detection Area
  Health Bar

Vous devez modifier ces enfants internes dans le template, pas comme des objets séparés appartenant à la scène.

Cela garantit que chaque instance reste cohérente. Si chaque ennemi placé pouvait modifier librement ses enfants internes, le template ne serait plus un objet réutilisable fiable.

Instancier un template dans une scène

Une fois qu'un template existe, vous pouvez le placer dans une scène.

Par exemple, vous pouvez glisser un template de l'Asset Browser vers la 3D View.

Quand le template est placé :

Il apparaît dans le Scene Graph comme une instance de template.
Cave utilise une couleur différente (vert) pour l'instance.
L'instance garde sa connexion avec l'asset template.

En termes de workflow, c'est l'une des façons les plus rapides de construire des niveaux. Vous créez une porte, un objet à ramasser, un ennemi ou un accessoire réutilisable une fois, puis placez des instances partout où le niveau en a besoin.

Personnalisation locale d'une instance de template

Les instances de template peuvent encore être personnalisées localement :

Le principal moyen d'effectuer cela est via les propriétés exposées par l'entité racine du template.

Cela offre un bon équilibre :

La structure reste réutilisable.
Chaque instance placée peut avoir ses propres valeurs.

Par exemple, plusieurs ennemis peuvent utiliser le même template ennemi, tandis que chaque instance aura une santé, une vitesse, des réglages de patrouille ou des options de comportement différents.

Exemples de propriétés locales d'un template

Les propriétés locales utiles comprennent :

Propriété	Exemple d'utilisation
Santé de l'ennemi	Rendre un ennemi plus faible ou plus fort.
Vitesse de l'ennemi	Créer des variantes lentes et rapides.
Quantité de dégâts	Réutiliser une source de danger avec différents niveaux de danger.
Niveau cible du portail	Envoyer chaque portail vers une scène différente.
Valeur d'un objet à ramasser	Rendre les pièces, gemmes ou récompenses de différentes valeurs.
État verrouillé d'une porte	Réutiliser une configuration de porte verrouillée ou déverrouillée.
Texte UI	Réutiliser un widget UI avec des étiquettes différentes.

Par exemple, un template Portal peut être utilisé à plusieurs endroits si chaque portail placé a une propriété locale qui choisit la scène cible.

Exemples de templates dans le projet de démarrage

Les projets de démarrage peuvent inclure plusieurs templates utiles selon les options choisies.

Vous pourriez y trouver des exemples tels que :

Template joueur.
Template ennemi.
Template dégâts.
Template portail.
Template véhicule.
Pièces de gameplay réutilisables.

Ces exemples valent la peine d'être examinés. Ouvrez-les, regardez la hiérarchie, inspectez les composants et voyez quelles propriétés sont exposées.

Le contenu généré n'est pas seulement là pour être utilisé. Il sert aussi à vous apprendre comment les objets Cave réels peuvent être construits.

Bonnes pratiques pour les Entity Templates

Créez un template lorsqu'un objet est :

Répété plusieurs fois.
Utilisé dans plusieurs scènes.
Construit à partir de plusieurs composants.
Composé de plusieurs entités enfants.
Destiné à avoir un comportement cohérent.
Utile comme pièce de gameplay réutilisable.

De bons candidats incluent :

Ennemis.
PNJ.
Armes.
Projectiles.
Objets à ramasser.
Portes.
Points de contrôle.
Pièges.
Portails de niveau.
Véhicules.
Accessoires destructibles.
Widgets UI.
Pièces de level design réutilisables.

Plus vous réutilisez un objet souvent, plus un template devient précieux.

Quand ne pas utiliser un template

Tout n'a pas besoin d'être un template.

Un objet unique qui n'apparaît qu'une fois et qui n'a de sens que dans une scène spécifique peut rester une entité normale de scène.

Par exemple :

Un accessoire de cinématique unique.
Un déclencheur spécifique à un niveau.
Une décoration unique qui ne sera jamais réutilisée.
Un objet test temporaire.

Les templates sont puissants, mais leur intérêt est maximal lorsque la réutilisation est importante. Transformer trop tôt chaque petit objet en template peut rendre le projet plus difficile à gérer, pas plus facile.

Une règle simple pour les templates

Si vous vous surprenez à copier plusieurs fois la même configuration d'entité, envisagez d'en faire un Entity Template.

Cette habitude seule peut faire gagner beaucoup de temps et garder votre projet bien plus propre à mesure qu'il grandit.

Cave : Guide de démarrage