Ajedrez_Purgatorio/UNITY_SETUP_GUIDE.md

🎮 Guía de Configuración Unity — Acción Inmediata

Ajedrez Purgatorio — Sprint 3 Setup

---

📋 Checklist Rápido

✅ Pre-requisitos (Sprint 1 & 2)

Antes de configurar el Purgatorio, verifica que esto esté hecho:

• 16 PieceIdentity assets creados en Assets/Data/Identities/
• CampaignState.asset creado en Assets/Data/
• AIPositionTables.asset creado en Assets/Data/AI/
• PromotionUI configurado en escena Game.unity
• PieceTooltip configurado en escena Game.unity
• Escenas: MainMenu.unity, Game.unity, Dialogue.unity, Purgatory.unity, DeadKing.unity en Build Settings

Si falta alguno, ver /production/sprints/sprint-01-foundation.md y sprint-02-chess-ai.md

---

🎯 Setup del Purgatorio (Sprint 3)

Paso 1: Abrir Escena de Juego

1. Abrir Unity Editor
2. File → Open Scene → Assets/Scenes/Game.unity

---

Paso 2: Crear PurgatoryManager GameObject

2.1 Crear GameObject Principal

1. En Hierarchy, clic derecho → Create Empty
2. Renombrar a PurgatoryManager
3. Position: (0, 0, 0) — no importa, será DontDestroyOnLoad
4. Agregar componente PurgatoryManager (script)
5. Agregar componente DiceSystem (script) al mismo GameObject

2.2 Configurar DiceSystem en Inspector

Seleccionar PurgatoryManager → Buscar componente DiceSystem:

Balance:
├─ Piece Bonus Queen: 2
├─ Piece Bonus Major: 1
├─ Piece Bonus Pawn: 0
├─ Desperation Threshold: 4
├─ Desperation Bonus: 1
└─ Penalty Per Visit: 1

Estos valores son según el GDD — NO cambiar sin testeo.

---

Paso 3: Crear Canvas de Purgatorio UI

3.1 Crear Canvas Principal

1. Hierarchy → clic derecho → UI → Canvas

2. Renombrar a PurgatoryCanvas

3. En Inspector del Canvas:

   Render Mode: Screen Space - Overlay
   Pixel Perfect: ✓ (checked)
   Sort Order: 10 (sobre cualquier otro UI)
   

4. Agregar/Verificar componente Canvas Scaler:

   UI Scale Mode: Scale With Screen Size
   Reference Resolution: 1920 x 1080
   Screen Match Mode: Match Width Or Height
   Match: 0.5
   

5. Agregar/Verificar componente Graphic Raycaster (debe estar por defecto)

3.2 Crear EventSystem (si no existe)

Si no hay EventSystem en la escena:

1. Hierarchy → clic derecho → UI → Event System

---

Paso 4: Crear Offer Panel (Pantalla de Oferta)

4.1 Crear Panel Base

1. Seleccionar PurgatoryCanvas
2. Clic derecho → UI → Panel
3. Renombrar a OfferPanel
4. En Inspector del Panel (Image component):

   Color: Negro semi-transparente (0, 0, 0, 200)
   

5. Rect Transform → Ancla a toda la pantalla:

   Anchors: Stretch-Stretch (centro + extremos coinciden)
   Left: 0, Right: 0, Top: 0, Bottom: 0
   

4.2 Crear Contenido del Panel

Estructura a crear:

OfferPanel
├─ TitleText (TMP)
├─ PieceInfoPanel
│   ├─ PieceNameText (TMP)
│   ├─ RoleText (TMP)
│   └─ RelationshipText (TMP)
├─ FlavorText (TMP)
└─ ButtonsPanel
    ├─ AcceptButton
    └─ DeclineButton

Crear cada elemento:

1. TitleText:

   • Seleccionar OfferPanel → clic derecho → UI → Text - TextMeshPro
   • Renombrar: TitleText
   • Text: "¿Desafiar a la Muerte?"
   • Font Size: 72
   • Alignment: Center + Middle
   • Color: Amarillo (#FFD700)
   • Posición: Centrado arriba (Y: 300)

2. PieceInfoPanel:

   • Seleccionar OfferPanel → clic derecho → UI → Panel
   • Renombrar: PieceInfoPanel
   • Width: 600, Height: 300
   • Posición: Centro (Y: 0)
   • Color: Negro más opaco (0, 0, 0, 230)

3. PieceNameText (dentro de PieceInfoPanel):

   • Clic derecho en PieceInfoPanel → UI → Text - TextMeshPro
   • Renombrar: PieceNameText
   • Text: "Nombre de Pieza"
   • Font Size: 48
   • Alignment: Center + Top
   • Color: Blanco
   • Posición: Y: 80

4. RoleText (dentro de PieceInfoPanel):

   • Similar a PieceNameText
   • Renombrar: RoleText
   • Text: "Rol"
   • Font Size: 32
   • Color: Gris claro (#CCCCCC)
   • Posición: Y: 20

5. RelationshipText (dentro de PieceInfoPanel):

   • Similar anterior
   • Renombrar: RelationshipText
   • Text: "Relación"
   • Font Size: 28
   • Color: Gris (#AAAAAA)
   • Posición: Y: -30

6. FlavorText (fuera de PieceInfoPanel):

   • Seleccionar OfferPanel → UI → Text - TextMeshPro
   • Renombrar: FlavorText
   • Text: "Quote de la Muerte..."
   • Font Size: 28
   • Style: Italic
   • Alignment: Center + Middle
   • Color: Rojo oscuro (#AA0000)
   • Posición: Y: -180

7. ButtonsPanel:

   • Seleccionar OfferPanel → clic derecho → Create Empty
   • Renombrar: ButtonsPanel
   • Add Component → Horizontal Layout Group
   • Spacing: 40
   • Child Alignment: Middle Center
   • Posición: Y: -300

8. AcceptButton (dentro de ButtonsPanel):

   • Seleccionar ButtonsPanel → UI → Button - TextMeshPro
   • Renombrar: AcceptButton
   • Width: 200, Height: 80
   • Color: Verde oscuro (#006400)
   • Text en hijo: "Sí"
   • Font Size: 36
   • Color texto: Blanco

9. DeclineButton (dentro de ButtonsPanel):

   • Similar a AcceptButton
   • Renombrar: DeclineButton
   • Color: Rojo oscuro (#8B0000)
   • Text: "No"

4.3 Agregar Script PurgatoryOfferUI

1. Seleccionar OfferPanel
2. Add Component → PurgatoryOfferUI (script)
3. Desactivar el Panel por defecto: Uncheck el checkbox arriba en Inspector

4.4 Asignar Referencias en Inspector

Seleccionar OfferPanel → Componente PurgatoryOfferUI:

Referencias UI:
├─ Offer Panel: OfferPanel (arrastrar desde Hierarchy)
├─ Title Text: TitleText (arrastrar)
├─ Piece Name Text: PieceNameText (arrastrar)
├─ Role Text: RoleText (arrastrar)
├─ Relationship Text: RelationshipText (arrastrar)
├─ Flavor Text: FlavorText (arrastrar)
├─ Accept Button: AcceptButton (arrastrar)
└─ Decline Button: DeclineButton (arrastrar)

---

Paso 5: Crear Dice Panel (Pantalla de Dados)

5.1 Crear Panel Base

1. Seleccionar PurgatoryCanvas
2. Clic derecho → UI → Panel
3. Renombrar a DicePanel
4. Color: Negro semi-transparente (0, 0, 0, 200)
5. Ancla: Stretch-Stretch (pantalla completa)

5.2 Crear Contenido

Estructura:

DicePanel
├─ StatusText (TMP)
├─ PlayerSection
│   ├─ PlayerLabel (TMP)
│   ├─ PlayerRollText (TMP)
│   ├─ PlayerModifiersText (TMP)
│   └─ PlayerTotalText (TMP)
└─ DeathSection
    ├─ DeathLabel (TMP)
    ├─ DeathRollText (TMP)
    └─ DeathTotalText (TMP)

Crear elementos:

1. StatusText:

   • UI → Text - TextMeshPro
   • Renombrar: StatusText
   • Text: "Tirando dados..."
   • Font Size: 48
   • Alignment: Center + Top
   • Color: Blanco
   • Posición: Y: 350

2. PlayerSection:

   • Create Empty → PlayerSection
   • Posición: X: -300, Y: 0
   • Width: 400, Height: 500

3. PlayerLabel (dentro de PlayerSection):

   • Text - TextMeshPro
   • Text: "TU TIRADA"
   • Font Size: 36
   • Color: Cyan (#00FFFF)
   • Posición: Y: 200

4. PlayerRollText:

   • Text - TextMeshPro
   • Text: "?"
   • Font Size: 120
   • Font Style: Bold
   • Alignment: Center
   • Color: Blanco
   • Posición: Y: 80

5. PlayerModifiersText:

   • Text - TextMeshPro
   • Text: "" (vacío)
   • Font Size: 24
   • Alignment: Center
   • Color: Verde (#00FF00)
   • Posición: Y: -30
   • Width: 350, Height: 150

6. PlayerTotalText:

   • Text - TextMeshPro
   • Text: "?"
   • Font Size: 48
   • Font Style: Bold
   • Color: Amarillo (#FFD700)
   • Posición: Y: -150

7. DeathSection (similar a PlayerSection):

   • Create Empty → DeathSection
   • Posición: X: 300, Y: 0
   • Repetir estructura pero con:
     • DeathLabel: "LA MUERTE"
     • Color: Rojo (#FF0000)

5.3 Agregar Script DiceRollUI

1. Seleccionar DicePanel
2. Add Component → DiceRollUI (script)
3. Desactivar el Panel: Uncheck arriba en Inspector

5.4 Asignar Referencias

Seleccionar DicePanel → Componente DiceRollUI:

Referencias UI:
├─ Dice Panel: DicePanel
├─ Player Roll Text: PlayerRollText
├─ Player Modifiers Text: PlayerModifiersText
├─ Player Total Text: PlayerTotalText
├─ Death Roll Text: DeathRollText
├─ Death Total Text: DeathTotalText
└─ Status Text: StatusText

Animación:
├─ Roll Duration: 2
└─ Reveal Delay: 0.5

---

Paso 6: Crear Result Panel (Pantalla de Resultado)

6.1 Crear Panel Base

1. Seleccionar PurgatoryCanvas
2. UI → Panel
3. Renombrar: ResultPanel
4. Color: Negro semi-transparente (0, 0, 0, 220)
5. Ancla: Stretch-Stretch

6.2 Crear Contenido

Estructura:

ResultPanel
├─ FlashOverlay (Image)
├─ OutcomeText (TMP)
├─ DeathQuoteText (TMP)
├─ DetailsText (TMP)
└─ ContinueButton (Button)

Crear elementos:

1. FlashOverlay:

   • Seleccionar ResultPanel → UI → Image
   • Renombrar: FlashOverlay
   • Ancla: Stretch-Stretch (pantalla completa)
   • Color: Blanco (1, 1, 1, 0.5) — con alpha 0.5
   • Desactivar este GameObject (será activado por script)

2. OutcomeText:

   • Text - TextMeshPro
   • Text: "¡VICTORIA!"
   • Font Size: 96
   • Font Style: Bold
   • Alignment: Center + Middle
   • Color: Amarillo (#FFD700)
   • Posición: Y: 200

3. DeathQuoteText:

   • Text - TextMeshPro
   • Text: "Quote de la Muerte..."
   • Font Size: 32
   • Style: Italic
   • Alignment: Center
   • Color: Rojo (#FF4444)
   • Posición: Y: 80
   • Width: 1000

4. DetailsText:

   • Text - TextMeshPro
   • Text: "Tu tirada: X\nLa Muerte: Y"
   • Font Size: 28
   • Alignment: Center
   • Color: Blanco
   • Posición: Y: -50
   • Width: 800, Height: 200

5. ContinueButton:

   • UI → Button - TextMeshPro
   • Width: 300, Height: 80
   • Color: Azul oscuro (#000080)
   • Text: "Continuar"
   • Font Size: 36
   • Posición: Y: -250

6.3 Agregar Script DiceResultUI

1. Seleccionar ResultPanel
2. Add Component → DiceResultUI (script)
3. Desactivar el Panel: Uncheck

6.4 Asignar Referencias

Seleccionar ResultPanel → Componente DiceResultUI:

Referencias UI:
├─ Result Panel: ResultPanel
├─ Outcome Text: OutcomeText
├─ Death Quote Text: DeathQuoteText
├─ Details Text: DetailsText
├─ Continue Button: ContinueButton
└─ Flash Overlay: FlashOverlay

Colores:
├─ Victory Color: #FFD700 (amarillo dorado)
└─ Defeat Color: #8B0000 (rojo oscuro)

---

Paso 7: Conectar PurgatoryManager

7.1 Asignar Referencias al Manager

Seleccionar PurgatoryManager en Hierarchy → Componente PurgatoryManager:

Referencias:
├─ Dice System: DiceSystem (en mismo GameObject)
└─ Campaign State: Arrastrar CampaignState.asset desde Assets/Data/

UI:
├─ Offer UI: OfferPanel (componente PurgatoryOfferUI)
├─ Dice Roll UI: DicePanel (componente DiceRollUI)
└─ Result UI: ResultPanel (componente DiceResultUI)

Configuración:
└─ Max Visits Per Board: 3

CRÍTICO: Verificar que CampaignState.asset tenga:

• Array de allIdentities con las 16 PieceIdentity assets
• Array de chapterDifficulties configurado

---

Paso 8: Verificar GameManager

1. Seleccionar GameObject GameManager en Hierarchy
2. Verificar que tiene referencias a:
   • pieceTooltip (PieceTooltip component)
   • promotionUI (PromotionUI component)

NO requiere referencia a PurgatoryManager — usa Singleton pattern.

---

Paso 9: Guardar y Testear

9.1 Guardar Todo

1. File → Save Scene (Ctrl+S)
2. File → Save Project (Ctrl+Shift+S)

9.2 Testing Básico

Test 1: Verificar que no haya errores

1. Presionar Play
2. Verificar Console — no debe haber errores rojos
3. Si hay errores de referencias faltantes, revisar el Paso 7

Test 2: Capturar pieza blanca

1. Play mode
2. Mover pieza negra (IA) para capturar pieza blanca
3. Debe aparecer OfferPanel con nombre de pieza
4. Click "Sí"
5. Debe aparecer DicePanel con animación de dados
6. Debe aparecer ResultPanel con resultado

Test 3: Verificar modificadores

1. Capturar diferentes tipos de piezas:
   • Peón → +0 bonus
   • Caballo/Alfil/Torre → +1 bonus
   • Reina → +2 bonus
2. Verificar que modificadores se muestren correctamente en DiceRollUI

Test 4: Verificar límite de visitas

1. Capturar 3 piezas y aceptar Purgatorio las 3 veces
2. Capturar 4ta pieza
3. NO debe aparecer oferta — muerte directa
4. Verificar Console: debe decir "cuota agotada"

---

⚠️ Troubleshooting Común

Error: "PurgatoryManager no encontrado"

• Causa: PurgatoryManager no está en escena o está desactivado
• Fix: Verificar que GameObject exista y esté activo

Error: "Referencias UI no asignadas"

• Causa: No asignaste las referencias en Inspector
• Fix: Revisar Paso 4.4, 5.4, 6.4, 7.1 — todas las referencias deben estar asignadas

Error: "Time.timeScale no se resetea"

• Causa: Excepción durante flujo de Purgatorio
• Fix: En Editor, pausar y ejecutar en Console: Time.timeScale = 1

UI no se muestra

• Causa: Panels están activos por defecto o Canvas Sort Order bajo
• Fix:
  • Verificar que OfferPanel, DicePanel, ResultPanel estén desactivados por defecto
  • Verificar Canvas Sort Order = 10

Dados no animan

• Causa: Time.timeScale = 0 y coroutine usa WaitForSeconds
• Fix: Verificar que DiceRollUI use WaitForSecondsRealtime (ya está en código)

---

✅ Checklist Final

Antes de marcar como completo:

• PurgatoryManager existe en Game.unity y está activo
• DiceSystem configurado con valores correctos
• 3 Panels creados (Offer, Dice, Result) y DESACTIVADOS por defecto
• 3 Scripts UI agregados y con referencias asignadas
• PurgatoryManager tiene referencias a 3 UI components
• CampaignState.asset asignado en PurgatoryManager
• Testing: Captura de pieza → Oferta aparece
• Testing: Dados ruedan y muestran modificadores
• Testing: Resultado muestra victoria/derrota correctamente
• Testing: Límite de 3 visitas funciona
• Console sin errores rojos
• Escena guardada

---

📚 Referencia Rápida

• Documentación completa: /Assets/Game/Scripts/Mono/Purgatory/SETUP_INSTRUCTIONS.md
• GDD del Sistema: /design/gdd/dice-system.md
• Sprint Plan: /production/sprints/sprint-03-purgatorio.md
• Estado del Proyecto: /PROJECT_STATUS.md

---

Tiempo estimado total: 45-60 minutos
Dificultad: Media (requiere familiaridad con Unity UI)

¡Buena suerte con el setup! 🎲