Sistema de Personajes

Para qué sirve este sistema

Cada enemigo de un juego de acción o por oleadas es una variación de la misma idea: un arquetipo con un prefab, puntos de vida y una velocidad de movimiento, spawneado muchas veces, con cada instancia seguida desde que aparece hasta que muere. Cablearlo a mano significa dispersar campos de vida, contabilidad de spawns y referencias de prefab por MonoBehaviours sin una única fuente de verdad.

El Sistema de Personajes de Serenity lo separa limpiamente en un arquetipo que creas una vez y un servicio de runtime que sigue cada instancia viva. Un soldado, un tanque y un jefe son cada uno un CharacterConfigSO validado; ICharacterService se encarga del resto, moviendo cada instancia spawneada por spawn, activo, muriendo y muerto mientras emite las señales a las que Puntuación y Combo reaccionan.

El problema en Unity

Las definiciones de enemigo que viven como campos sueltos en el MonoBehaviour de un prefab son fáciles de duplicar mal y difíciles de validar — nada impide que un diseñador publique un arquetipo con cero puntos de vida o una referencia de prefab ausente hasta que falla en runtime. No hay un lugar único que responda cuántos enemigos de este tipo están vivos ahora mismo.

El estado de combate agrava el problema. Los contadores de munición, los flags de recarga y los modos de disparo atornillados directamente al MonoBehaviour de un personaje mezclan si el actor está vivo con si el arma puede disparar ahora — dos ciclos de vida que deberían ser independientes se enredan, y probar uno implica arrastrar el otro.

Cómo lo aborda Serenity

Un CharacterConfigSO define el prefab, la vida máxima y la velocidad de movimiento de un arquetipo, validados al importar — una vida máxima menor que uno se rechaza de plano. ICharacterService es el único objeto que registra, activa, golpea y despawnea cada instancia viva, moviendo cada una por CharacterState de Spawning a Active, Dying y Dead, y emitiendo CharacterSpawnSignal, CharacterHitSignal, CharacterKilledSignal y CharacterAttackSignal por el camino, alimentando a Puntuación y Combo sin que ninguno de los dos sistemas meta la mano en las tripas del personaje.

La disponibilidad de combate es una preocupación aparte e independiente, gestionada por IGameWeaponService — una máquina de estados de runtime pura para gatillo, recarga, modo de disparo y cargador, seguida mediante WeaponState, MagazineState y WeaponSnapshot. Impone sus propias invariantes, como no disparar durante la recarga ni con el cargador vacío, y deja deliberadamente los proyectiles, el apuntado y el daño al resto de tu juego.

Cómo encaja en Serenity

Personajes compone con Oleadas y Escenario para el spawn: las entradas de spawn de una oleada nombran un arquetipo y un punto de spawn del escenario, y el servicio de oleadas instancia allí el prefab del arquetipo antes de registrarlo en ICharacterService. Los assets CharacterConfigSO descubiertos se etiquetan con la label de Addressables type:character para que el instalador autodescubra cada arquetipo en el arranque sin un registro mantenido a mano.

GameWeapon es un agregado estructuralmente independiente, sin asset de configuración ni contrato de señales propio — cada arma se registra y se dirige por completo mediante llamadas a IGameWeaponService. Compone con Personajes solo a través del código de gameplay que tú escribes, manteniendo la contabilidad de munición y modos de disparo desacoplada del seguimiento de vida y muerte.

Flujo de trabajo práctico

1. Abre Tools ▸ Serenity ▸ Create ▸ Character ▸ Create Character y recorre Intent ▸ Configure ▸ Mount ▸ Preview ▸ Done para crear un arquetipo — prefab, vida máxima, velocidad de movimiento.
2. En el paso Mount de la 1.3.0, elige cómo se mueve el prefab del arquetipo: móntalo en un seguidor de Game Rail, o apúntalo a referenciar un punto de spawn de Escenario a través de los datos de oleada.
3. Comprueba el estado de la etiqueta de Addressables en línea en el inspector del arquetipo y usa el botón Fix (retag) de un clic si falta la label type:character antes del arranque.
4. Referencia el arquetipo desde una entrada de spawn de Oleada para que el servicio de oleadas instancie su prefab y llame a RegisterCharacter en el punto de spawn correcto.
5. Suscríbete a CharacterKilledSignal desde Puntuación o Combo para reaccionar a las kills sin que ninguno de los dos sistemas dependa directamente de las tripas de Personajes.
6. Para el combate, llama a IGameWeaponService.RegisterWeapon con una capacidad de cargador y un modo de disparo, y dirige TriggerPressed, TriggerReleased y ReloadRequested/ReloadComplete desde el input.

Qué incluye

• Arquetipos CharacterConfigSO con prefab, vida máxima y velocidad de movimiento, validados al importar (la vida máxima debe ser al menos uno)
• Ciclo de vida de ICharacterService que cubre spawn, activo, muriendo y muerto para cada instancia viva, indexada por CharacterId
• CharacterSpawnSignal, CharacterHitSignal, CharacterKilledSignal y CharacterAttackSignal alimentando a Puntuación y Combo
• Asistente Create Character — Intent ▸ Configure ▸ Mount ▸ Preview ▸ Done — con el paso Mount de la 1.3.0 para montar en Game Rail o punto de spawn de Escenario
• Estado de etiqueta de Addressables en línea con botón Fix (retag) de un clic directamente en el inspector del arquetipo
• Autodescubrimiento de cada arquetipo etiquetado type:character en el arranque, sin registro mantenido a mano
• Máquina de estados de arma IGameWeaponService — WeaponState, MagazineState, WeaponSnapshot y FireMode — para el seguimiento de gatillo, recarga y cargador
• Invariantes de arma impuestas en el dominio: no disparar durante la recarga ni con el cargador vacío, dejando deliberadamente proyectiles y daño a tu juego

Cuándo usarlo

• Juegos de acción o por oleadas que necesitan varios arquetipos de enemigo validados — soldados, tanques, jefes — seguidos del spawn a la muerte.
• Proyectos que quieren señales de kill alimentando a Puntuación y Combo sin acoplar ninguno de los dos sistemas a las tripas del personaje.
• Equipos que quieren que el paso de etiquetado de Addressables de un arquetipo nuevo se detecte en el inspector, antes de convertirse en un bug silencioso de cero arquetipos en el arranque.
• Juegos que necesitan seguir la munición, la recarga y el modo de disparo de un arma de jugador o enemigo con independencia de la vida y el ciclo de vida del personaje.

Sistemas relacionados

• Sistema de Oleadas Un spawner de oleadas que guioniza quién aparece, dónde y cuándo, encadena las oleadas en sets que avanzan solos y las spawnea en puntos con nombre del escenario que las aloja.
• Sistema de Spawn y Object Pooling Un servicio de spawn de entidades que abstrae el pooling de objetos detrás de handles opacos para que la lógica de juego nunca toque la instanciación del motor directamente.
• Sistema de Puntuación Multi-Métrica Un modelo de puntuación dinámico que rastrea cualquier número de métricas nombradas a través de un único servicio, devolviendo instantáneas inmutables que las reglas de juego nunca necesitan poseer.
• Sistema de Movimiento sobre Raíles Un servicio de raíles pasivo basado en snapshots que rastrea el progreso normalizado de 0 a 1 a lo largo de caminos de nodos con nombre, manteniendo los sistemas de movimiento, IA y cámara completamente desacoplados.