godot-mechanic-revival

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):

1. revival_global_manager.gd — Autoload owns death → delay → respawn; resolve player via group Player.
2. revival_death_timer.gd — 1–2s fade / death anim; never snap-respawn.
3. revival_state_reset_guard.gd — zero velocity / clear locks before teleport.
4. revival_health_restitution.gd — health restore + I-frames.
5. 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.

revival_global_manager.gd

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.

revival_checkpoint_persistence.gd

Resource-based system for saving last checkpoint and world state to disk.

revival_health_restitution.gd

Professional I-frame and health replenishment logic for post-revive stability.

revival_soul_grave.gd

Expert 'Soul Retrieval' mechanic for spawning graves at death coordinates.

revival_checkpoint_validator.gd

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.

revival_death_timer.gd

Professional respawn delay manager with UI and animation hooks.

revival_ghost_mode.gd

Expert 'Spirit World' transition logic involving collision layer swapping.

revival_state_reset_guard.gd

Essential utility for purging velocity and state locks upon player respawn.

revival_checkpoint_visuals.gd

Material-swapping logic for providing clear 'Active' feedback to players.

revival_auto_save_manager.gd

Automatic save-trigger logic for ensuring checkpoint persistence.

revival_spectral_shader.gdshader

Translucent, glowing "ghost" effect for downed players.

revival_async_restorer.gd

Smooth stat restoration logic using Tweens for organic recovery.

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

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.