A medida que tu jugabilidad crece, eventualmente necesitarás objetos que se comporten de manera diferente según lo que estén haciendo actualmente. Un enemigo puede estar inactivo, patrullando, persiguiendo, atacando, aturdido o muerto. Una puerta puede estar cerrada, abriéndose, abierta o bloqueada. Una pelea contra un jefe puede pasar por varias fases.

Aquí es donde las Máquinas de Estado se vuelven útiles.

En la imagen de arriba, puedes ver el enemigo predeterminado que Crave crea para el nuevo proyecto, con su Máquina de Estado abierta en el lado derecho. Estamos dentro del estado "wander" que tiene estados internos, como el "random selector" (el estado inicial, representado por el color verde), el "go to random" y el "idle". Puedes ver las transiciones entre los estados representadas por las flechas, y que cada estado puede tener su propia lógica, ya sea en Python, como se muestra en la imagen, o en logic bricks.

Una máquina de estados te ayuda a organizar el comportamiento en estados claros en lugar de escribir un script grande lleno de condiciones no relacionadas.

En esta lección aprenderás:

Qué es un Estado.
Qué es una Transición.
Por qué las máquinas de estados jerárquicas son útiles.
Cómo el Componente de Máquina de Estado de Cave encaja en una entidad.
Cómo funcionan On Enter, On Update y On Exit.
Cómo se puede usar Python y Logic Bricks dentro de estados y transiciones.

El objetivo es entender primero el modelo mental. Una vez que eso tiene sentido, el editor se vuelve mucho más fácil de usar.

¿Qué es un Estado?

Un estado describe lo que un objeto está haciendo actualmente.

Por ejemplo, un enemigo podría tener estos estados:

Idle
Patrol
Chase
Attack
Dead

Por lo general, solo uno de esos estados debería controlar al enemigo a la vez. Si el enemigo está en Patrol, no debería estar también ejecutando el comportamiento de ataque. Si está en Dead, no debería seguir persiguiendo al jugador.

Esto hace que la jugabilidad sea más fácil de entender porque cada estado tiene un trabajo claro.

Estado	Lo Que Podría Hacer
`Idle`	Quedarse quieto y esperar.
`Patrol`	Moverse entre puntos.
`Chase`	Moverse hacia el jugador.
`Attack`	Reproducir una animación de ataque y causar daño.
`Dead`	Desactivar el movimiento y reproducir una animación de muerte.

En lugar de preguntar "¿qué debería hacer el enemigo este cuadro?" desde un script enorme, puedes preguntar "¿en qué estado está el enemigo actualmente?"

¿Qué es una Transición?

Una transición es la regla que mueve la máquina de estados de un estado a otro.

Por ejemplo:

De Idle a Patrol cuando el enemigo debe empezar a moverse, después de un temporizador.
De Patrol a Chase cuando se detecta al jugador.
De Chase a Attack cuando el enemigo está lo suficientemente cerca.
De Attack a Chase cuando el ataque termina.
De cualquier estado a Dead cuando la salud llega a cero.

La transición no es el comportamiento en sí. Es la decisión que dice: "ahora debemos cambiar de estado."

Esa separación es importante. El estado Attack puede centrarse en atacar, mientras que la transición decide cuándo es momento de entrar o salir de ese estado.

Por qué las Máquinas de Estado Jerárquicas Ayudan

Cave usa un enfoque de máquina de estados jerárquica. Esto significa que los estados pueden organizarse dentro de otros estados. Eso es útil porque muchos comportamientos comparten una idea padre común.

Por ejemplo, un enemigo podría organizarse así:

Alive
    Idle
    Patrol
    Chase
    Attack
Dead

Los estados Idle, Patrol, Chase y Attack pertenecen al estado más amplio Alive. Esto hace que la estructura sea más fácil de entender y puede ayudarte a evitar repetir la misma lógica en varios lugares.

Para un proyecto para principiantes, puedes comenzar con una máquina de estados plana y simple. Pero a medida que tu jugabilidad se vuelve más compleja, la jerarquía ayuda a mantener la lógica limpia.

El Componente de Máquina de Estado

Para usar una máquina de estados en una escena, una entidad necesita un Componente de Máquina de Estado.

El componente conecta la entidad con un asset de Máquina de Estado. El asset define los estados, transiciones y lógica, mientras que el componente ejecuta esa lógica en la entidad durante la jugabilidad.

Esto es similar a otros sistemas de Cave:

Asset	Componente
Python Script	El Componente Python lo ejecuta.
Animación	El Componente de Animación la reproduce.
Máquina de Estado	El Componente de Máquina de Estado la ejecuta.

En la práctica, esto significa que tu entidad enemigo puede tener un Componente de Máquina de Estado, y ese componente puede ejecutar una máquina de estados para la IA del enemigo.

Un asset de máquina de estados puede tener propiedades, como puedes ver al ir a la pestaña de propiedades, y esas propiedades pueden cambiarse localmente en el componente de máquina de estados, permitiéndote crear máquinas de estados modulares que tengan diferentes configuraciones en distintos tipos de entidades.

Eventos de Estado

Cada estado puede reaccionar a tres momentos importantes:

Evento	Cuándo se Ejecuta	Uso Común
`On Enter`	Cuando el estado comienza.	Reiniciar temporizadores, inicializar variables, reproducir una animación, elegir un objetivo.
`On Update`	Mientras el estado está activo.	Moverse, chequear distancias, actualizar temporizadores.
`On Exit`	Al salir del estado.	Detener efectos, borrar valores temporales.

Por ejemplo, un estado Attack podría funcionar así:

On Enter: reproducir la animación de ataque.
On Update: esperar el momento del golpe o el callback de la animación.
On Exit: borrar la bandera de ataque.

Esto hace que cada estado se sienta como un pequeño comportamiento autónomo.

Python Dentro de los Estados

Las máquinas de estados pueden usar Python para la lógica.

Dentro del código Python de cada Estado, Cave proporciona variables útiles como entity y scene, para que el estado pueda controlar la entidad que posee el Componente de Máquina de Estado.

Por ejemplo, un estado podría reproducir un sonido al ser activado:

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

O podría leer una propiedad de la entidad:

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

Esto mantiene la lógica del estado cerca del comportamiento al que pertenece.

Python Dentro de las Transiciones

Las transiciones también pueden usar Python. Para la lógica Python en transiciones, Cave usa una variable llamada result. Si result se vuelve True, la transición puede ocurrir. Por ejemplo, una transición a un estado Dead podría verificar la salud así:

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

Una transición de Chase a Attack podría chequear la distancia si tu script o propiedades del enemigo proporcionan ese valor:

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

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

Los datos exactos dependen de tu juego, pero la idea siempre es la misma: la transición decide si es momento de pasar de un estado a otro.

TIP: Durante una transición, todas las variables locales definidas en el estado desde donde viene la transición están disponibles para ti. Así que en el ejemplo anterior, donde calculamos la distancia entre la entidad y el jugador, podríamos guardar el transform del jugador y el transform de la entidad en dos variables en el evento on-enter del estado del que viene esta transición para ahorrar un poco de recursos, ya que entonces está en caché y no necesitaríamos obtener esos datos cada cuadro.

Logic Bricks Dentro de las Máquinas de Estado

Las máquinas de estado también pueden usar Logic Bricks.

Esto es útil cuando quieres construir el comportamiento visualmente en lugar de escribir código Python. Para muchas tareas de jugabilidad, los Logic Bricks son una forma muy accesible de conectar eventos, condiciones y acciones.

Funcionan exactamente igual que en el caso del código Python dentro del estado o para una transición. Los Logic Bricks del Estado y los Logic Bricks de la Transición ya están inicializados con los bricks que necesitas para comenzar.

Puedes mezclar Python y Logic Bricks según lo que te resulte más claro para el comportamiento que estás construyendo. Si un Estado o una Transición tienen ambos, entonces ambos se ejecutarán y la transición ocurrirá si uno O el otro sucede.

Cuándo Usar una Máquina de Estado

Usa una máquina de estado cuando un objeto tiene modos de comportamiento claros.

Buenos ejemplos incluyen:

IA de enemigos.
Fases de jefes.
Puertas y objetos interactivos.
Flujo de misiones o quests.
Progresión de escenas cinemáticas.
Estados de habilidades de personajes.

Puede que no necesites una máquina de estado para objetos pequeños de una sola acción. Si un pickup solo reproduce un sonido y desaparece, un script Python pequeño o una configuración de Logic Bricks pueden ser suficientes.

Lo Que Debes Recordar

Una máquina de estado organiza la jugabilidad en estados y transiciones.

Los estados describen lo que está ocurriendo actualmente. Las transiciones deciden cuándo cambiar a otra cosa. On Enter, On Update y On Exit ayudan a mantener cada estado enfocado y legible.

Para comportamientos simples, un script puede ser suficiente. Para comportamientos con múltiples modos, una máquina de estado generalmente facilita entender la lógica y ampliarla.

Cave: Guía de Inicio