godot-mechanic-revival

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.

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.

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.
Spatial shader — Spectral downed visuals use spatial ALPHA/EMISSION pulses instead of hiding the mesh.

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.