| name | godot-mechanic-revival |
| description | Expert blueprint for player mortality loops: progress-index checkpoints, soul graves, ghost/spirit layers, I-frame restitution, world-progress persistence, and death analytics. Use when implementing respawn, shrine checkpoints, corpse-run retrieval, or second-chance mechanics. Keywords revival, respawn, checkpoint, soul grave, ghost mode, I-frames, death analytics, progress index. |
Overview
Mortality beyond Game Over: progress-index checkpoints, soul graves, ghost/spirit collision layers, I-frame restitution, world-progress bitmasks, and death analytics (Sekiro / Hades / Souls-like).
Golden Path — Death → Fade → Restore → I-frame → World Persist
MANDATORY script order (read before improvising):
- revival_global_manager.gd — Autoload owns death → delay → respawn; resolve player via group
Player.
- revival_death_timer.gd — 1–2s fade / death anim; never snap-respawn.
- revival_state_reset_guard.gd — zero velocity / clear locks before teleport.
- revival_health_restitution.gd — health restore + I-frames.
- revival_checkpoint_persistence.gd — write world-progress bitmask to
user://.
Optional layers: revival_soul_grave.gd, revival_ghost_mode.gd, revival_death_analytics.gd.
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.
Expert singleton for the global respawn loop. Autoload boot: register as RevivalGlobalManager before level scenes. Resolves the living body with get_tree().get_first_node_in_group("Player") — put the player in group Player (exact name). Owns player_died / player_respawned; levels and UI must not queue_free() the player.
Resource-based system for saving last checkpoint and world state to disk.
Professional I-frame and health replenishment logic for post-revive stability.
Expert 'Soul Retrieval' mechanic for spawning graves at death coordinates.
Progress-aware shrine/Area3D gate. Export progress_index + checkpoint_id; on enter, call RevivalGlobalManager.set_active_checkpoint(...) only if progress_index >= RevivalGlobalManager.get_progress(). Group the detector / player interact area so backtracking cannot downgrade the active shrine. Pair with revival_checkpoint_persistence.gd for durable writes.
Professional respawn delay manager with UI and animation hooks.
Expert 'Spirit World' transition logic involving collision layer swapping.
Essential utility for purging velocity and state locks upon player respawn.
Material-swapping logic for providing clear 'Active' feedback to players.
Automatic save-trigger logic for ensuring checkpoint persistence.
Translucent, glowing "ghost" effect for downed players.
Smooth stat restoration logic using Tweens for organic recovery.
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
Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.
Official Documentation
- Saving games — Checkpoint and world-progress persistence must survive crashes; pair Resource/
FileAccess saves with an immediate write on shrine activation.
- File paths in Godot — Use
user:// for checkpoint and death-analytics files so saves work outside the project folder and across platforms.
- Resources — Model checkpoint payloads (
last_checkpoint_id, position, triggered events) as Resource data with ResourceSaver/ResourceLoader, not ad-hoc globals.
- Singletons (Autoload) — A revival/respawn manager Autoload owns the death → delay → restore loop so levels and UI never
queue_free() the player.
- Using signals — Emit
player_died / player_respawned / true_death so HUD, graves, and analytics subscribe without coupling into the Character script.
- Groups — Resolve the living player via the
Player group for respawn teleports and soul-grave pickup without brittle node paths.
- Physics introduction — Ghost/spirit modes swap collision layers/masks; never rely on modulate alone to stop hazard overlaps.
- CharacterBody3D — Zero
velocity (and clear angular impulse) on revive or residual momentum throws the body into walls.
- SceneTreeTimer — Death→respawn delay and I-frame windows use
create_timer / one-shot timers so fades and UI can finish before restore.
- Tween — Smooth health restitution and I-frame opacity pulses; kill/recreate tweens if the player dies mid-restore.
- FileAccess — Append death telemetry JSON lines under
user:// for heatmaps and balancer input.
Related Skills
Prerequisites
- godot-signal-architecture — Death, revive-available, and true-death events need clear ownership so UI, graves, and analytics stay decoupled from the player node.
- godot-resource-data-patterns — Checkpoint state and world-progress bitmasks belong in typed Resources with safe save/load, not mutable singletons alone.
- godot-save-load-systems — Checkpoint activation should trigger a durable auto-save path (
user://) so progress survives crashes mid-run.
- godot-composition — Keep revival charges, I-frames, and grave droppers as components rather than baking mortality into a monolithic Character script.
Complements
- godot-combat-system — Combat
died / health-zero signals are the usual entry into revival charges, true death, and corpse-run drops.
- godot-rpg-stats — Post-revive health/mana restitution and invincibility flags should write through the same stats layer combat reads.
- godot-tweening — Async restorers and I-frame modulate loops need interruptible Tween lifecycles, not stacked parallel flashes.
- godot-shaders-basics — Spectral/ghost materials and spirit-realm post-process cues live in the shader skill once the revive state machine exists.
- godot-economy-system — Corpse-run currency loss and soul-grave recovery must reconcile with the wallet/ledger so pickups cannot duplicate funds.
- godot-scene-management — Prefer disabling/hiding the existing player instance over reloading the whole level; graves and world progress must outlive the death transition.
Downstream / consumers
- godot-monte-carlo-balancer — Feed
revival_death_analytics cause/position logs into Monte Carlo runs to prove difficulty spikes and I-frame TTK bands before shipping.
- godot-genre-action-rpg — Souls-like shrine, ghost, and soul-retrieval loops assemble this skill with combat, stats, and save systems.
- godot-genre-roguelike — Run-ending deaths, meta penalties, and consequence trackers consume revival/true-death outcomes for permadeath or mercy variants.
Master
- godot-master — Library router and mirrored module entry; use when discovering peer skills or syncing shared script mirrors after Domain Skill edits.
