> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://documentation.celestory.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Ajouter personnage

# 🟧 Ajouter personnage

${frame}[Vidéo : anatomie du bloc Ajouter personnage](https://celestory-docs-videos.netlify.app/fr/anatomie-bloc/addcharacter.html)

Le bloc **Ajouter personnage** permet de faire entrer un personnage sur la scène d'un Visual Novel, à une place et sur un plan précis, avec une animation d'arrivée.

C'est le bloc qui fait exister un personnage à l'écran. Tant qu'il n'a pas été joué, le personnage n'existe que dans les réglages du module : les blocs Déplacer personnage, Changer humeur, Retourner personnage et Enlever personnage n'ont alors aucun effet sur lui.

## 📥 Entrées

*   **in (Flux)** : Point d'entrée. Dès que le flux arrive, le personnage entre en scène ; le flux repart une fois l'animation d'entrée terminée.
*   **personnage (Référence de personnage)** : Liste déroulante des personnages déclarés dans les réglages du module (onglet « Personnages »). Un second menu, « Choisir une humeur », sélectionne l'humeur affichée à l'arrivée.
*   **place (Nombre, 1 par défaut)** : Numéro de l'emplacement horizontal, de 1 au nombre de « places » déclaré par le bloc Scène. Une valeur hors limites est ramenée dans la grille (0 ou 12 dans une scène à 3 places donnent la place 1 ou la place 3).
*   **plan (Nombre, 1 par défaut)** : Numéro du plan de profondeur, de 1 au nombre de « plans » du bloc Scène. Chaque plan supplémentaire réduit le personnage de 10 % : plan 1 = 100 %, plan 2 = 90 %, plan 3 = 80 %.
*   **miroir (Booléen, faux par défaut)** : Affiche le personnage retourné horizontalement, pour qu'il regarde dans l'autre sens.
*   **transition (Choix, « instantané » par défaut)** : Manière dont le personnage arrive. `instantané` l'affiche d'un coup ; `d'en haut`, `de droite`, `d'en bas` et `de gauche` le font glisser depuis le bord correspondant jusqu'à sa place ; `fade out` le fait apparaître en fondu (le libellé est trompeur : à l'entrée, c'est bien un fondu d'apparition).

Ce bloc n'a **pas** d'entrée de durée : la durée de l'animation d'entrée vient du réglage du module « Durée de transition d'entrée des personnages » (0,8 s par défaut).

## 📤 Sorties

*   **out (Flux)** : Le flux repart une fois le personnage installé et son animation d'entrée jouée. Enchaînez typiquement sur un bloc Dialogue, ou sur un autre Ajouter personnage pour composer la scène.

## 💡 Exemple d'utilisation

**Scénario : l'arrivée de la libraire**

1. Un bloc Scène affiche l'intérieur de la boutique, avec 3 places et 2 plans.
2. Un premier bloc Ajouter personnage installe « Client » en place 1, plan 2, humeur « Neutre », transition `instantané` : il est déjà là, en arrière-plan, légèrement plus petit.
3. Le joueur choisit « Pousser la porte ».
4. Un second bloc Ajouter personnage installe « Libraire » en place 3, plan 1, humeur « Joyeux », transition `de droite` : elle glisse depuis le bord droit de l'écran en 0,8 s.
5. Le flux continue vers un bloc Dialogue où la libraire prend la parole.

## ⚙️ Détails Techniques

*   **Identifiant interne** : `addCharacter`
*   **Un bloc Scène est obligatoire en amont** : la grille de places et de plans est créée par le bloc Scène. Si aucun bloc Scène n'a été joué dans le module, Ajouter personnage — comme les quatre autres blocs de personnage — ne fait strictement rien, sans message d'erreur. À l'inverse, chaque nouveau bloc Scène vide le plateau : tous les personnages présents sortent en fondu.
*   **L'humeur, c'est l'image** : pour un personnage en image (le cas courant), ce qui s'affiche à l'écran *est* l'image de l'humeur sélectionnée. Sans humeur choisie, ou si l'humeur n'a pas d'image, le personnage occupe bien sa place dans la scène mais **rien n'apparaît**. Les humeurs se créent dans les réglages du module → onglet « Personnages » → sélection du personnage → section « Humeurs » → bouton « Ajouter une humeur » : chaque humeur est un nom plus une ressource Image. Pour un personnage Spine (case « Utiliser Spine »), la section s'appelle « Animations » et le nom de l'humeur doit correspondre exactement au nom d'une animation du squelette.
*   **Place déjà occupée** : si un autre personnage occupe la place visée, il est d'abord déplacé vers la première place libre du même plan, à défaut vers n'importe quelle place libre de la scène. Si la scène est pleine, il est retiré avec la transition choisie.
*   **Ajouter deux fois le même personnage** : le bloc ne vérifie pas qu'il est déjà en scène, et un second exemplaire est créé à l'écran. Passez par Enlever personnage avant de le réintroduire.
*   **Ordre d'application** : place → miroir → humeur → glissement d'entrée. Pour un personnage en image, le miroir posé ici retourne la texture de l'humeur, alors que Retourner personnage anime l'échelle du sprite : combiner les deux donne un résultat incohérent, à vérifier dans le lecteur.
*   **Réglage « Désactiver toutes les transitions et délais »** : quand il est actif dans les réglages du module, toutes les durées tombent à 0 et les personnages apparaissent instantanément.
*   Le panneau des délais du module affiche **deux fois** le champ « Durée de transition d'entrée des personnages » : les deux pilotent le même réglage.

## 🔗 Voir aussi

*   **Scène** : à jouer avant, pour déclarer le nombre de places et de plans.
*   **Enlever personnage** : pour faire sortir de scène un personnage ajouté.
*   **Déplacer personnage** / **Changer humeur** / **Retourner personnage** : pour agir ensuite sur un personnage déjà en scène.

---

*Version documentée : v1*