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! 🎲