Crash Recovery System

One of the biggest challenges in minigame development is handling unexpected server stops (crashes, force kills, or ungraceful reloads). Usually, when a server crashes mid-game, temporary blocks and entities are left behind, cluttering the world and requiring manual cleanup.

Santa Says includes a robust Smart Recovery System that automatically tracks every temporary change and reverts them instantly upon the next server startup.

---

How It Works

The recovery system operates silently in the background, ensuring your arenas remain clean without any manual intervention.

1. Live Tracking

   During a game, whenever the plugin places a block (e.g., barriers, game props) or spawns an entity (e.g., Santa, custom mobs), it acts as a “temporary object.”

   The system immediately logs the Location and UUID of these objects into a secure memory cache.

2. Persistence (Auto-Save)

   To survive a crash, this data must exist outside the RAM. The ArenaRecoveryManager asynchronously flushes this tracking data to a flat-file database located at:

   plugins/SantaSays/recovery/arena-recoveries.yml

3. Automatic Restoration

   When your server starts up (or the server is reloaded), the system checks this recovery file.

   • Blocks: Any block locations found in the file are immediately set to AIR.
   • Entities: Any entity UUIDs found are searched for in all worlds and removed.

   This ensures that even if the server power was cut mid-game, the arena resets to its pristine state on the next boot.

Tip

No Performance Cost The saving process happens asynchronously, meaning it runs on a separate thread and does not impact your server’s TPS (Ticks Per Second) during gameplay.

---

What It Prevents

Without this system, a server crash during a game could lead to:

• Ghost Entities: Dozens of “Santa” NPCs or game mobs left floating in the arena.
• Corrupted Maps: Walls or platforms placed by tasks remaining permanently, blocking future games.
• Duplicate Objects: New games spawning entities on top of old ones, causing glitchy physics and confusion.

With this recovery system, the plugin guarantees a clean slate every time it enables.

---

Manual Cleanup

While the system is fully automatic, you may occasionally want to inspect or clear the recovery data manually.

The Recovery File

You can view tracked objects in recovery/arena-recoveries.yml. The structure looks like this:

arena_1:
  blocks:
    - "world, 1.522, 50.000, -1.015, -0.906, 0.000"
    - "world, 1.522, 50.000, -1.015, -1.198, 0.000"
  entities:
    - "550e8400-e29b-41d4-a716-446655440000"
    - "7d444840-9dc0-11d1-b245-5ffdce74fad2"

Caution

Do not edit this file manually unless you know exactly what you are doing. Removing lines from this file prevents the plugin from cleaning up those specific blocks or entities.