godot-mechanic-revival

What this skill does

# Revival & Resurrection Mechanics

## Overview
This skill provides a robust framework for handling player mortality and return. It moves beyond simple "Game Over" screens to integrated risk/reward systems like those found in *Sekiro*, *Hades*, or *Dark Souls*.

## NEVER Do (Expert Revival Rules)

### Lifecycle & State
- **NEVER respawn the player with existing velocity** — Always zero out `velocity` and `angular_velocity` in `revival_state_reset_guard.gd` or the player will fly into a wall upon respawning.
- **NEVER trust the nearest checkpoint by distance** — Always use a 'Progress Index' (`revival_checkpoint_validator.gd`). Players in non-linear games may wander back to the start area; don't downgrade their respawn point.
- **NEVER skip 'Invincibility Frames' (I-frames)** — Respawning inside a hazard or near an enemy without a 2s invincibility buffer leads to "Death Loops" and player frustration.

### Persistence & Data
- **NEVER save checkpoints solely in RAM** — If the game crashes, the player loses progress. Use `revival_checkpoint_persistence.gd` to write to `user://` immediately.
- **NEVER hardcode checkpoint coordinates** — Use `Marker3D` or `Area3D` nodes in the scene. Hardcoded coords break as soon as level geometry changes.
- **NEVER delete the player node on death** — `queue_free()`ing the player breaks UI refs and references from enemies. Disable processing, hide the mesh, and 'Revive' the existing instance instead.

### UX & Pacing
- **NEVER respawn instantly** — An instant snap is disorienting. Always use a 1-2s delay with a screen fade or death animation to allow the player to process the failure.
- **NEVER reset the entire world on player death** — In modern design, opened doors and collected unique items should stay persisted. Use a bitmask in the checkpoint resource to track 'World Progress'.

---

## Available Scripts

> **MANDATORY**: Read the appropriate script before implementing the corresponding pattern.

### [revival_global_manager.gd](scripts/revival_global_manager.gd)
Expert singleton for managing the global respawn loop and death transitions.

### [revival_checkpoint_persistence.gd](scripts/revival_checkpoint_persistence.gd)
Resource-based system for saving last checkpoint and world state to disk.

### [revival_health_restitution.gd](scripts/revival_health_restitution.gd)
Professional I-frame and health replenishment logic for post-revive stability.

### [revival_soul_grave.gd](scripts/revival_soul_grave.gd)
Expert 'Soul Retrieval' mechanic for spawning graves at death coordinates.

### [revival_checkpoint_validator.gd](scripts/revival_checkpoint_validator.gd)
Progress-aware validator that prevents backtracking from overwriting newer checkpoints.

### [revival_death_timer.gd](scripts/revival_death_timer.gd)
Professional respawn delay manager with UI and animation hooks.

### [revival_ghost_mode.gd](scripts/revival_ghost_mode.gd)
Expert 'Spirit World' transition logic involving collision layer swapping.

### [revival_state_reset_guard.gd](scripts/revival_state_reset_guard.gd)
Essential utility for purging velocity and state locks upon player respawn.

### [revival_checkpoint_visuals.gd](scripts/revival_checkpoint_visuals.gd)
Material-swapping logic for providing clear 'Active' feedback to players.

### [revival_auto_save_manager.gd](scripts/revival_auto_save_manager.gd)
Automatic save-trigger logic for ensuring checkpoint persistence.

### [revival_spectral_shader.gdshader](scripts/revival_spectral_shader.gdshader)
Translucent, glowing "ghost" effect for downed players.

### [revival_async_restorer.gd](scripts/revival_async_restorer.gd)
Smooth stat restoration logic using Tweens for organic recovery.

### [revival_death_analytics.gd](scripts/revival_death_analytics.gd)
Persistent logging of death telemetry (cause, location, time) for balancing.

---

## Expert Revival Patterns

### 1. Spectral Visual Feedback
Don't just hide the player. Use a **Spectral Shader** to communicate the "Downed" state.
- **Implementation**: Apply a `ShaderMaterial` with additive blending and a pulsing `ALPHA` to the player mesh.
- **Juice**: Combine with a grayscale `ColorRect` post-process effect to sell the "Spirit Realm" transition.

### 2. Death Analytics Ledger
Use **Death Analytics** to find "Difficulty Spikes".
- **Tracking**: Log `global_position` and `cause_of_death` to a JSON file.
- **Optimization**: Export these logs to a heatmap tool to identify areas where players are struggling.

## Reference
- Master Skill: [godot-master](../godot-master/SKILL.md)