# Player Death & Respawn System - Setup Guide

## 📋 Overview

A complete death and respawn system has been implemented for your dungeon crawler. The system features:

- ✅ **Automatic death detection** when all party members die
- ✅ **Smooth fade transitions** between death and respawn
- ✅ **Checkpoint system** to save progress
- ✅ **Death screen UI** with respawn button
- ✅ **Full party restoration** (HP, stamina, mana)
- ✅ **Optional penalties** (configurable)

---

## 🎮 How It Works

### Death Flow:
1. **Character HP reaches 0** → Character dies and UI card is removed
2. **All party members dead** → Party wipe detected
3. **Screen fades to black** (smooth transition)
4. **Death screen appears** with respawn button
5. **Player clicks Respawn** → Teleports to last checkpoint
6. **Party fully restored** → All characters revived with full HP/stamina
7. **Fade back in** → Gameplay resumes

### Checkpoint System:
- Checkpoints save: Player position, party state, character stats
- Respawning loads the last checkpoint
- Initial checkpoint saved automatically 2 seconds after game start

---

## 🛠️ Unity Setup Instructions

### Step 1: Create Required GameObjects

In your Unity scene hierarchy, create these GameObjects:

#### 1. **GameManager** (Main Controller)
```
1. Create Empty GameObject: "GameManager"
2. Add Component: GameManager.cs
3. In Inspector, assign:
   - Team Cohesion Manager (reference from scene)
   - Checkpoint System (create next)
   - Death Screen UI (create later)
   - Player Movement (GridMovement component on player)
4. Configure settings:
   - Death Delay: 2 seconds (default)
   - Respawn Fade Time: 1 second
   - Reset Monsters On Respawn: ☐ (optional)
   - Apply Gold Penalty: ☐ (disabled by default)
```

#### 2. **CheckpointSystem**
```
1. Create Empty GameObject: "CheckpointSystem"
2. Add Component: CheckpointSystem.cs
3. In Inspector, assign:
   - Cohesion Manager (reference from scene)
   - Player Transform (your player GameObject)
   - Player Movement (GridMovement component)
4. Settings:
   - Auto Save On Checkpoint: ☑ (enabled)
   - Checkpoint Radius: 3 meters
```

#### 3. **DeathScreenUI**
```
1. Create Empty GameObject: "DeathScreenUI"
2. Add Component: DeathScreenUI.cs
3. The script will auto-create the UI if not manually designed
4. Optional: Customize death messages in Inspector array
5. Settings:
   - Fade In Duration: 1 second
   - Randomize Message: ☑ (enabled)
```

### Step 2: Create Checkpoint Zones (Optional)

To add checkpoint zones throughout your dungeon:

```
1. Create Empty GameObject at desired checkpoint location
2. Name it: "Checkpoint_01" (or descriptive name)
3. Add Component: BoxCollider
4. Add Component: CheckpointTrigger.cs
5. In Inspector:
   - Box Collider: Set size (e.g., 5x3x5) and mark as Trigger
   - Show Visual Feedback: ☑
   - One Time Use: ☑ (recommended)
   - Checkpoint Message: "Safe Zone Reached"
6. Tag the object as "Checkpoint" (optional)
```

**Note:** Yellow wireframe cube shows checkpoint location in Scene view.

### Step 3: Update Existing Components

Your existing scripts have been updated automatically:
- ✅ `CharacterUIController.cs` - Now notifies GameManager on party wipe
- ✅ `GameInitializer.cs` - Saves initial checkpoint on game start

### Step 4: Player Setup

Ensure your Player GameObject has:
- ✅ Tag: "Player" (important!)
- ✅ Rigidbody or CharacterController
- ✅ Collider for checkpoint triggers

### Step 5: Testing

#### Test Death:
1. Enter Play Mode
2. Wait 2 seconds (initial checkpoint saves)
3. Let monsters kill all party members
4. Death screen should appear after 2 second delay
5. Click "RESPAWN" button
6. Party should respawn at starting position, fully healed

#### Test Checkpoint:
1. Create a checkpoint trigger in your scene
2. Walk player through it
3. Console should show "Checkpoint Saved"
4. Move away and die
5. Should respawn at checkpoint location

---

## ⚙️ Configuration Options

### GameManager Settings:

| Setting | Default | Description |
|---------|---------|-------------|
| Death Delay | 2s | Time before death screen appears |
| Respawn Fade Time | 1s | Duration of fade transition |
| Reset Monsters On Respawn | false | Respawn all monsters (harder) |
| Apply Gold Penalty | false | Lose gold percentage on death |
| Gold Penalty Percent | 0% | How much gold to lose |

### CheckpointSystem Settings:

| Setting | Default | Description |
|---------|---------|-------------|
| Auto Save On Checkpoint | true | Save when entering checkpoint zones |
| Checkpoint Radius | 3m | Trigger distance for checkpoints |

### CheckpointTrigger Settings:

| Setting | Default | Description |
|---------|---------|-------------|
| Show Visual Feedback | true | Play effects on activation |
| One Time Use | false | Only trigger once per checkpoint |
| Checkpoint Message | Custom | Log message on save |

---

## 🎨 Customization

### Custom Death Screen UI

If you want to design your own death screen instead of the auto-generated one:

```
1. Create Canvas → Panel in UI
2. Add background image (dark/ominous)
3. Add TextMeshPro text for death message
4. Add Button with "RESPAWN" text
5. Add CanvasGroup to panel
6. Assign references in DeathScreenUI Inspector:
   - Death Panel: Your panel GameObject
   - Death Message Text: Your TextMeshPro text
   - Respawn Button: Your button
   - Canvas Group: CanvasGroup component
```

### Custom Checkpoint Visual Effects

Add visual flair to checkpoints:

```
1. Create particle effect prefab (glowing portal, sparkles, etc.)
2. Assign to CheckpointTrigger → Checkpoint VFX
3. Add checkpoint sound effect AudioClip
4. Effects play automatically when triggered
```

### Custom Death Penalties

Enable penalties for hardcore mode:

```csharp
// In GameManager Inspector:
Apply Gold Penalty: ☑
Gold Penalty Percent: 10-50%

// Or extend GameManager.cs to add custom penalties:
private void ApplyGoldPenalty()
{
    // Your custom penalty logic
    // Examples:
    // - Lose items
    // - Reduce experience
    // - Drop equipped weapons
}
```

---

## 🔧 Advanced Features

### Manual Checkpoint Saving

Call from your own scripts:

```csharp
// Save checkpoint at current position
CheckpointSystem.Instance.SaveCheckpoint();

// Save checkpoint at specific location
CheckpointSystem.Instance.SaveCheckpointAt(position, rotation);
```

### Check If Player Is Dead

```csharp
if (GameManager.Instance.IsPlayerDead())
{
    // Disable certain features during death
}
```

### Force Respawn

```csharp
// Trigger respawn manually
GameManager.Instance.RespawnParty();
```

---

## 📝 Scene Hierarchy Example

```
Scene
├── GameManager (GameManager.cs)
├── CheckpointSystem (CheckpointSystem.cs)
├── DeathScreenUI (DeathScreenUI.cs)
├── Player
│   └── [GridMovement, TeamCohesionManager, etc.]
├── Canvas (UI)
│   └── PartyUIManager
├── Dungeon
│   ├── Checkpoint_Entrance (CheckpointTrigger)
│   ├── Checkpoint_MidLevel (CheckpointTrigger)
│   └── Checkpoint_Boss (CheckpointTrigger)
└── Monsters
```

---

## 🐛 Troubleshooting

### Problem: Death screen doesn't appear
**Solution:** Check that GameManager is in scene and DeathScreenUI is assigned.

### Problem: Respawn doesn't restore party
**Solution:** Ensure CheckpointSystem is assigned to GameManager and initial checkpoint was saved.

### Problem: Checkpoints don't trigger
**Solution:** 
- Player must have "Player" tag
- CheckpointTrigger BoxCollider must be marked as Trigger
- CheckpointTrigger collider must be large enough

### Problem: UI doesn't rebuild after respawn
**Solution:** Make sure PartyUIManager exists in scene and is properly referenced.

### Problem: Player falls through floor on respawn
**Solution:** Ensure saved checkpoint position has valid ground underneath.

---

## 📊 System Architecture

```
┌─────────────────┐
│ MonsterAttack   │ Deals damage to character
└────────┬────────┘
         │
         ▼
┌─────────────────────┐
│ CharacterUIController│ Detects HP ≤ 0
└────────┬────────────┘
         │
         ▼
┌──────────────────┐
│ TeamCohesion     │ Checks if all dead
│ Manager          │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ GameManager      │ Orchestrates death/respawn
└────────┬─────────┘
         │
         ├─► Fade to Black
         ├─► Show Death Screen
         └─► On Respawn Click
                  │
                  ▼
          ┌──────────────────┐
          │ CheckpointSystem │ Restore party & position
          └──────────────────┘
```

---

## ✅ Quick Checklist

Before testing, verify:

- [ ] GameManager in scene with all references assigned
- [ ] CheckpointSystem in scene with player reference
- [ ] DeathScreenUI in scene (can be empty, auto-creates UI)
- [ ] Player GameObject has "Player" tag
- [ ] GameInitializer saves initial checkpoint
- [ ] At least one checkpoint exists in scene (or initial checkpoint saves)
- [ ] All scripts compiled without errors

---

## 🎯 Next Steps

**Enhancement Ideas:**
1. Add checkpoint visual markers (glowing pillars, flags)
2. Create safe zone audio ambiance
3. Add "lives" system (3 respawns before game over)
4. Implement permadeath hardcore mode
5. Add respawn animation sequences
6. Create checkpoint UI indicator (minimap marker)
7. Add respawn countdown timer
8. Implement death statistics (death counter, causes)

---

## 📞 Support

If you encounter issues:
1. Check Unity Console for error messages (prefix: `[GameManager]`, `[CheckpointSystem]`, `[Death]`)
2. Verify all GameObjects exist in scene hierarchy
3. Ensure all references are assigned in Inspector
4. Check that scripts are attached to correct GameObjects

All debug logs are prefixed with system name for easy filtering.

---

**System Version:** 1.0  
**Created:** October 2025  
**Compatible with:** Unity 2021.3+

---

Enjoy your robust respawn system! 🎮✨