Phoenix Prime: Manual de Usuario

Versión Actual: v1.2.0

Phoenix Prime es un framework profesional de orquestación de ciclo de vida para Unity. Su objetivo principal es eliminar el caos de Awake/Start no determinista, reemplazándolo con un Plan de Ejecución Determinista, Visual, Resiliente y Asíncrono.

---

1. ¿Por qué usar Phoenix Prime?

El Problema

En proyectos medianos y grandes de Unity, la inicialización del juego se vuelve impredecible.

• "¿Por qué falla el AudioManager?" -> "Porque intentó acceder al SaveSystem antes de que este cargara".
• "¿Por qué se congela el juego al inicio?" -> "Porque estamos cargando 10 sistemas en el mismo frame".

La Solución Phoenix

Phoenix divide tu arranque en fases estrictas y controladas:

1. Diseño (Editor): Creas un grafo visual de dependencias ("El Audio necesita la Configuración").
2. Configuración Visual: Ajustas parámetros (vitalidad, reintentos, prefabs) directamente en el nodo, sin tocar código.
3. Compilación (Baking): El sistema analiza tu grafo y genera un Plan de Ejecución optimizado (Topological Sort) que garantiza el orden correcto.
4. Ejecución (Runtime): El motor ejecuta los lotes de forma asíncrona, gestiona la inyección de dependencias, reintenta módulos fallidos y reporta el progreso real de carga.

---

2. Instalación

Desde el Unity Package Manager (UPM):

1. Abre Window > Package Manager.
2. Click en el icono + > Add package from git URL....
3. Pega: https://github.com/nlelouche/PhoenixPrime.git#v1.2.0

---

3. Guía Rápida: Tu Primer Módulo

Paso 1: Crear el Script

Crea un script (ej. InventorySystem.cs) e implementa IBootModule.

using Phoenix.Runtime.Core;
using System.Threading.Tasks;
using UnityEngine;

// [Exposed] permite editar variables en el grafo
// [RetryPolicy] define reintentos automáticos
[RetryPolicy(MaxRetries = 3, DelayMs = 200)]
public class InventorySystem : MonoBehaviour, IBootModule
{
    // Prioridad visual (para organizar el grafo)
    public int Priority => 10;

    [Exposed] public int StartingSlots = 10;

    // Inyección de dependencias automática
    // [Inject] private SaveSystem _saveSystem; 

    public async Task<NodeResult> InitializeAsync(IPhoenixContainer container, System.IProgress<float> progress)
    {
        Debug.Log($"Iniciando Inventario con {StartingSlots} espacios...");
        
        // Simular carga asíncrona
        await Task.Delay(500);

        // Registrarse para que otros puedan usarnos
        container.Register(this);

        return NodeResult.Success;
    }
}

Paso 2: El Grafo

1. Ve a Window > Phoenix Prime > Execution Graph.
2. Click derecho > Create Node. Busca tu InventorySystem.
3. Si tienes otro módulo (ej. SaveSystem), conéctalos: Salida de SaveSystem -> Entrada de InventorySystem. Esto le dice a Phoenix: "No inicies el Inventario hasta que el Guardado esté listo".

Paso 3: Configuración y Bake

1. Selecciona el nodo InventorySystem.
2. En el Inspector del Grafo, verás:
   • Is Vital?: Si falla, ¿se detiene el juego?
   • Prefab (Optional): (Ver Sección 4).
   • Starting Slots: Tu variable expuesta. Edítala aquí.
3. Haz click en Bake Execution Plan (arriba a la derecha) y guarda el archivo .asset.

Paso 4: Ejecución

1. Crea una escena vacía (BootScene).
2. Crea un GameObject y añádele el componente GameInitializer.
3. Asigna el archivo .asset que creaste al campo Execution Plan.
4. Dale a Play.

---

4. Características Avanzadas (v1.1+)

4.1 Soporte para Prefabs y MonoBehaviours

A partir de la v1.1, Phoenix puede instanciar objetos en la escena. Esto es ideal para Managers que necesitan UI, AudioSources o Colliders.

Uso:

1. Crea un Prefab: Tu script debe heredar de MonoBehaviour e implementar IBootModule.

   public class MyVisualManager : MonoBehaviour, IBootModule { ... }

2. En el Grafo, selecciona el nodo correspondiente.
3. Arrastra el Prefab al campo "Prefab (Optional)".
4. Al hacer Bake y Play, Phoenix instanciará ese Prefab automáticamente.

Nota: Si dejas el campo vacío, Phoenix creará una instancia "pura" de C# (POCO), ideal para servicios de lógica pura.

4.2 Persistencia (DontDestroyOnLoad)

Para servicios globales (Audio, Red, Input) que deben sobrevivir entre cambios de escena.

Uso:

1. En el nodo del grafo, marca la casilla "Keep Alive (DontDestroy)".
2. El objeto instanciado se moverá automáticamente a la escena DontDestroyOnLoad.

4.3 Parámetros Expuestos

Permite a los Game Designers ajustar la configuración inicial sin tocar código. Soporta: int, float, string, bool.

[Exposed] public float Volume = 1.0f;
[Exposed] public string ServerUrl = "api.game.com";

4.4 Patrón: Graceful Degradation (Degradación Elegante)

Este patrón permite que el juego continúe funcionando aunque un servicio falle o el entorno no sea el ideal, ajustándose automáticamente.

Ejemplo: Gestor de Calidad Gráfica Este módulo intenta configurar gráficos en ULTRA. Si detecta que el dispositivo es débil (o falla al aplicar settings), baja a LOW y reporta Degraded. El juego arranca igual, pero optimizado.

public class GraphicsQualityManager : MonoBehaviour, IBootModule
{
    public int Priority => 50; // Configurar gráficos temprano

    public async Task<NodeResult> InitializeAsync(IPhoenixContainer container, System.IProgress<float> progress)
    {
        Debug.Log("Configurando Gráficos...");
        
        try 
        {
            // Intentamos poner todo al máximo
            if (SystemInfo.systemMemorySize < 4000 || SystemInfo.graphicsMemorySize < 2000)
            {
                throw new System.Exception("Dispositivo con poca memoria detectado.");
            }

            QualitySettings.SetQualityLevel(5); // Ultra
            return NodeResult.Success;
        }
        catch (System.Exception e)
        {
            Debug.LogWarning($"No se pudo aplicar Calidad Ultra: {e.Message}. Degradando a Low.");
            
            // Fallback: Gráficos al mínimo para asegurar rendimiento
            QualitySettings.SetQualityLevel(0); // Low
            
            // Informamos al Engine que funcionamos pero en modo degradado (icono amarillo en el monitor).
            return NodeResult.Degraded; 
        }
    }
}

---

5. API Reference

Core Interfaces

• IBootModule: Contrato obligatorio.
  • InitializeAsync(container, progress): Lógica de arranque. Devuelve Task<NodeResult>.
• IPhoenixContainer: Sistema de Inyección de Dependencias.
  • Register<T>(instance): Publica un servicio.
  • Resolve<T>(): Obtiene un servicio.
• NodeResult:
  • Success: Todo correcto.
  • FailVital: Error crítico, abortar arranque.
  • FailOptional: Error menor, continuar (warning).

Atributos

• [Inject]: Marca campos para ser inyectados automáticamente antes de InitializeAsync.
• [Exposed]: Expone variables simples al editor del grafo.
• [RetryPolicy]: Configura reintentos automáticos para operaciones inestables.

---

6. Resolución de Problemas Frecuentes

• "Cyclic Dependency Detected": Tienes un bucle en tu grafo (A depende de B, y B depende de A). El sistema impide hornear esto. Revisa tus conexiones.
• "Component not found in Prefab": Asignaste un Prefab al nodo, pero ese Prefab no contiene el script IBootModule que dice el nodo.
• Errores de Tests: Si mueves scripts de carpeta, recuerda actualizar los .asmdef o regenerarlos.

---

Phoenix Prime - Orchestrating Chaos into Order.