À mesure que votre gameplay évolue, vous aurez finalement besoin d'objets qui se comportent différemment selon ce qu'ils font actuellement. Un ennemi peut être inactif, en patrouille, en poursuite, en attaque, étourdi ou mort. Une porte peut être fermée, en train de s'ouvrir, ouverte ou verrouillée. Un combat de boss peut se dérouler en plusieurs phases.

C'est là que les State Machines deviennent utiles.

Sur l'image ci-dessus, vous pouvez voir l'ennemi par défaut que Crave crée pour le nouveau projet, avec sa State Machine ouverte sur le côté droit. Nous sommes à l'intérieur de l'état "wander" qui contient des états internes, tels que le "random selector" (l'état initial, représenté par la couleur verte), le "go to random" et le "idle". Vous pouvez voir les transitions entre les états représentées par les flèches, et chaque état peut avoir sa propre logique, soit en Python, comme montré dans l'image, soit en Logic Bricks.

Une state machine vous aide à organiser le comportement en états clairs au lieu d'écrire un grand script rempli de conditions non liées.

Dans cette leçon, vous apprendrez :

Ce qu'est un État.
Ce qu'est une Transition.
Pourquoi les state machines hiérarchiques sont utiles.
Comment le State Machine Component de Cave s'intègre dans une entité.
Comment fonctionnent On Enter, On Update et On Exit.
Comment Python et Logic Bricks peuvent être utilisés à l'intérieur des états et des transitions.

L'objectif est de comprendre d'abord le modèle mental. Une fois cela clair, l'éditeur devient beaucoup plus facile à utiliser.

Qu'est-ce qu'un État ?

Un état décrit ce que fait actuellement un objet.

Par exemple, un ennemi pourrait avoir ces états :

Idle
Patrol
Chase
Attack
Dead

En général, un seul de ces états doit contrôler l'ennemi à la fois. Si l'ennemi est en Patrol, il ne devrait pas aussi exécuter le comportement d'attaque. S'il est en Dead, il ne devrait plus poursuivre le joueur.

Cela rend le gameplay plus facile à comprendre, car chaque état a une tâche claire.

État	Ce qu'il fait
`Idle`	Rester immobile et attendre.
`Patrol`	Se déplacer entre des points.
`Chase`	Se diriger vers le joueur.
`Attack`	Jouer une animation d'attaque et infliger des dégâts.
`Dead`	Désactiver le mouvement et jouer une animation de mort.

Au lieu de demander "que doit faire l'ennemi cette frame ?" dans un énorme script, vous pouvez demander "dans quel état est l'ennemi actuellement ?"

Qu'est-ce qu'une Transition ?

Une transition est la règle qui fait passer la state machine d'un état à un autre.

Par exemple :

Idle vers Patrol quand l'ennemi doit commencer à bouger, après un délai.
Patrol vers Chase quand le joueur est détecté.
Chase vers Attack quand l'ennemi est assez proche.
Attack vers Chase quand l'attaque se termine.
De n'importe quel état vers Dead lorsque la santé atteint zéro.

La transition n'est pas le comportement lui-même. C'est la décision qui dit : "maintenant, nous devons changer d'état."

Cette séparation est importante. L'état Attack se concentre sur l'attaque, tandis que la transition décide quand entrer ou quitter cet état.

Pourquoi les State Machines Hiérarchiques sont utiles

Cave utilise une approche de state machine hiérarchique. Cela signifie que des états peuvent être organisés à l'intérieur d'autres états. C'est utile car beaucoup de comportements partagent une idée parente commune.

Par exemple, un ennemi pourrait être organisé ainsi :

Alive
    Idle
    Patrol
    Chase
    Attack
Dead

Les états Idle, Patrol, Chase et Attack appartiennent tous à l'état plus large Alive. Cela rend la structure plus facile à comprendre et peut vous aider à éviter de répéter la même logique à plusieurs endroits.

Pour un projet débutant, vous pouvez commencer par une state machine simple et plate. Mais à mesure que votre gameplay devient plus complexe, la hiérarchie aide à garder la logique propre.

Le State Machine Component

Pour utiliser une state machine dans une scène, une entité a besoin d'un State Machine Component.

Ce composant connecte l'entité à un asset State Machine. L'asset définit les états, transitions et la logique, tandis que le composant exécute cette logique sur l'entité pendant le gameplay.

C'est similaire à d'autres systèmes de Cave :

Asset	Composant
Python Script	Le Python Component l'exécute.
Animation	Le Animation Component la joue.
State Machine	Le State Machine Component l'exécute.

En pratique, cela signifie que votre entité ennemi peut avoir un State Machine Component qui exécute une state machine d'IA d'ennemi.

Un asset state machine peut avoir des propriétés, comme vous pouvez le voir dans l'onglet propriétés, et ces propriétés peuvent être modifiées localement dans le composant state machine, vous permettant de créer des state machines modulaires avec des réglages différents selon les types d'entités.

Événements d'État

Chaque état peut réagir à trois moments importants :

Événement	Quand il se déclenche	Usage courant
`On Enter`	Lorsque l'état démarre.	Réinitialiser les timers, initialiser des variables, jouer une animation, choisir une cible.
`On Update`	Pendant que l'état est actif.	Se déplacer, vérifier des distances, mettre à jour les timers.
`On Exit`	En quittant l'état.	Arrêter des effets, effacer des valeurs temporaires.

Par exemple, un état Attack pourrait fonctionner ainsi :

On Enter : jouer l'animation d'attaque.
On Update : attendre le moment du coup ou un callback d'animation.
On Exit : effacer le flag d'attaque.

Cela donne à chaque état un comportement petit et autonome.

Python dans les États

Les state machines peuvent utiliser Python pour la logique.

Dans le code Python de chaque état, Cave fournit des variables utiles telles que entity et scene, ce qui permet à l'état de contrôler l'entité propriétaire du State Machine Component.

Par exemple, un état pourrait jouer un son à l'entrée :

cave.playSound("Enemy Alert", volume=0.8)

Ou lire une propriété de l'entité :

health = entity.properties.get("health", 100)

Cela maintient la logique d'état proche du comportement auquel elle appartient.

Python dans les Transitions

Les transitions peuvent aussi utiliser Python. Pour la logique Python des transitions, Cave utilise une variable appelée result. Si result devient True, la transition peut se faire. Par exemple, une transition vers l'état Dead pourrait vérifier la santé ainsi :

health = entity.properties.get("health", 100)
result = health <= 0

Une transition de Chase vers Attack pourrait vérifier la distance si votre script ennemi ou vos propriétés fournissent cette valeur :

player = scene.get("Player")
playerPos = player.getTransform().getWorldPosition()
entityPos = entity.getTransform().getWorldPosition()

distanceToPlayer = (playerPos - entityPos).length()
result = distanceToPlayer < 2.0

Les données exactes dépendent de votre jeu, mais l'idée reste la même : la transition décide s'il est temps de passer d'un état à un autre.

CONSEIL : Pendant une transition, toutes les variables locales définies dans l'état d'où provient la transition sont disponibles. Ainsi, dans l'exemple précédent où nous calculons la distance entre l'entité et le joueur, on pourrait stocker les transformées du joueur et de l'entité dans deux variables lors de l'entrée dans l'état d'où vient la transition pour économiser des ressources, car ces données seraient alors mises en cache et il ne serait plus nécessaire de les récupérer à chaque frame.

Logic Bricks dans les State Machines

Les state machines peuvent également utiliser Logic Bricks.

C'est utile quand on veut construire un comportement visuellement plutôt qu'écrire du code Python. Pour de nombreuses tâches de gameplay, Logic Bricks sont une méthode très accessible pour connecter événements, conditions et actions.

Ils fonctionnent exactement de la même manière que pour le code Python à l'intérieur d'un état ou d'une transition. Les Logic Bricks de l'État et ceux de la Transition sont déjà initialisés avec les briques nécessaires pour démarrer.

Vous pouvez mélanger Python et Logic Bricks selon ce qui vous paraît plus clair pour le comportement que vous construisez. Si un État ou une Transition a les deux, les deux seront exécutés et la transition se produira si l'un OU l'autre se produit.

Quand utiliser une State Machine

Utilisez une state machine lorsqu'un objet a des modes de comportement clairs.

Exemples typiques :

IA ennemie.
Phases de boss.
Portes et objets interactifs.
Progression de mission ou quête.
Déroulement des cutscenes.
États des capacités du personnage.

Vous n'aurez peut-être pas besoin d'une state machine pour de petits objets à une seule action. Si un objet ramassable ne fait qu'émettre un son puis disparaît, un petit script Python ou un ensemble de Logic Bricks peut suffire.

À retenir

Une state machine organise le gameplay en états et transitions.

Les états décrivent ce qui se passe actuellement. Les transitions décident quand passer à autre chose. On Enter, On Update et On Exit aident à garder chaque état concentré et lisible.

Pour un comportement simple, un script peut suffire. Pour un comportement avec plusieurs modes, une state machine rend généralement la logique plus facile à comprendre et à étendre.

Cave : Guide de démarrage