### 1. Kurzbeschreibung
- (Sicher) Das Feature `spawn_egg_state_restore` speichert Fahrzeugzustände (z. B. Leben, Farbe, Fuel) in Spawn-Egg-Lore und stellt diese Zustände beim nächsten Spawn des Fahrzeugs wieder her.
- (Sicher) Zweck ist zustandsbehaftetes Respawn-Verhalten statt "frischer" Standard-Entitys nach Drop/Refund von Spawn-Eggs.

### 2. Systemübersicht
- (Sicher) `BP/scripts/planes/spawn_egg_state_restore.js`: Zentrale Logik für State-Extraktion, Lore-Erzeugung, Lore-Parsing, Pending-Restore-Matching und Apply-Retries.
- (Sicher) `BP/scripts/main.js`: Lädt das Modul global via `import "./planes/spawn_egg_state_restore.js"`.
- (Sicher) `BP/animation_controllers/aria/pp/v/all_planes.json`: Triggert über `"/scriptevent aria_pp:plane_state drop_egg"` den Egg-Drop-Pfad für zerstörte Fahrzeuge.
- (Sicher) `BP/scripts/planes/c17.js`: Nutzt Exporte (`getPlaneSpawnEggState`, `giveSpawnEggWithStateToPlayer`) für C17-/G-Class-Refunds mit Zustand.

### 3. Kernlogik
- (Sicher) Type-Mapping:
  - Plane-Type -> Egg-Type via Suffix `_spawn_egg`.
  - Egg-Type -> Plane-Type rückwärts über denselben Suffix.
- (Sicher) `getPlaneSpawnEggState(entity)` liest:
  - `aria:crash_lives`
  - Variant (Property/Component-Fallbacks)
  - `aria:fuel`, `aria:fuel_max`
  - bei `aria_pp:c17` zusätzlich Cargo-Slot-Zustände (`c17_loaded_g_state_slot_1/2`).
- (Sicher) `buildStateLore(state)` erzeugt Lore-Zeilen wie:
  - `Spawn Egg`
  - Health-Bar
  - Color
  - Fuel
  - optional Cargo-Infos.
- (Sicher) `createSpawnEggItemStack(eggTypeId, state)` erstellt ein Spawn-Egg-Item mit Lore.
- (Sicher) Input-Pfad (Egg-Nutzung):
  - Hooks auf `beforeEvents.itemUse`, `beforeEvents.itemUseOn`, `beforeEvents.playerInteractWithBlock`.
  - Lore wird bevorzugt aus selected Slot gelesen, fallback aus Event-Stack.
  - Bei parsebarem Lore-State wird ein Pending-Restore für den Player gequeued (inkl. Type, Tick, Position, Dimension, Ablaufzeit).
- (Sicher) Spawn-Pfad:
  - Hook auf `afterEvents.entitySpawn`.
  - Nur `aria_pp:*`-Entities (ohne `_crash`) werden betrachtet.
  - Pending-Restore wird strikt gematcht auf Egg-Type, Plane-Type, Dimension und Distanz (Radius 8 Blöcke).
  - Treffer wird konsumiert und Apply geplant.
- (Sicher) Apply-Pfad:
  - Mehrfachversuch mit Delays `[1, 3, 8]` Ticks.
  - Setzt Crash Lives, Fuel/FuelMax, Variant.
  - Bei C17 werden Cargo-Slot-Dynamic-Properties gesetzt und `aria:loaded_g_count` synchronisiert.
  - Crash-Feedback-Partikel werden beim Restore kurz deaktiviert und nach 10 Ticks wieder aktiviert.
- (Sicher) Drop-/Refund-Pfade:
  - `scriptEventReceive` mit `aria_pp:plane_state drop_egg` droppt ein Spawn-Egg mit aktuellem State am Flugzeug.
  - `giveSpawnEggWithStateToPlayer(...)` gibt/Droppt stateful Spawn-Eggs direkt in Inventar/Welt (verwendet u. a. im C17-Refund-Flow).

Wichtige Zustände / States
- (Sicher) Lore-State-Felder: `crashLives`, `variant`, `fuel`, `fuelMax`, optional `loadedGStates`.
- (Sicher) Pending-Restore-Felder: `eggTypeId`, `planeTypeId`, `useLocation`, `dimensionId`, `tick`, `expiresAtTick`, plus State-Felder.
- (Sicher) Relevante C17 Dynamic Properties: `c17_loaded_g_state_slot_1`, `c17_loaded_g_state_slot_2`.
- (Sicher) Interne Schutz-Maps:
  - `pendingRestoreByPlayerId`
  - `handledEggUseTickByPlayerAndEgg`
  - `crashFeedbackRestoreByEntityId`.

Events / Trigger
- (Sicher) `beforeEvents.itemUse` / `itemUseOn` / `playerInteractWithBlock`: Erzeugen Pending-Restore aus Egg-Lore.
- (Sicher) `afterEvents.entitySpawn`: Verbraucht Pending-Restore und spielt State zurück.
- (Sicher) `afterEvents.scriptEventReceive` (`aria_pp:plane_state` + `drop_egg`): Erzeugt zustandsbehaftetes Egg beim Entity-Drop.

### 4. Ablauf (Flow-Diagramm in Textform)
- (Sicher) Drop bei Zerstörung:
Destroy Controller -> `scriptevent aria_pp:plane_state drop_egg` -> State aus Entity lesen -> Spawn-Egg mit Lore in Welt droppen

- (Sicher) Nutzen eines Spawn-Eggs:
Player uses Egg -> Lore parse -> Pending-Restore (Type+Ort+Zeit) speichern -> Plane spawned -> Matching Pending-Restore finden -> State mit Retry anwenden

- (Sicher) C17-Refund:
C17-Despawn-Refund -> `giveSpawnEggWithStateToPlayer(...)` -> Player erhält stateful C17/G-Class-Egg -> späteres Nutzen folgt Standard-Restore-Pfad

### 5. Challenges & Edge Cases
- (Sicher) Dedupe: Gleiche Egg-Nutzung im selben Tick pro `player+eggType` wird nur einmal verarbeitet.
- (Sicher) Pending-Restore hat TTL (5 Sekunden) und wird regelmäßig bereinigt.
- (Sicher) Matching ist absichtlich streng (Type + Dimension + Distanz), um falsche State-Zuordnungen zu vermeiden.
- (Sicher) State-Apply wird mehrfach verzögert versucht, um frühe Spawn-Tick-Rennen abzufangen.
- (Sicher) Lore-Parser ist robust gegenüber Farbformatierung (`§`-Codes) und liest Health-Bar über Block-Zählung.
- (Sicher) Variant-Apply hat mehrere Fallback-Ebenen (set_variant Event, Property/Component, notfalls `aria:change_variant`-Zyklus).
- (Sicher) Inventar-Fallback: Falls Container/Slotzugriff fehlschlägt, wird Event-Item-Lore genutzt.
- (Wahrscheinlich) Parsing von `Cargo X Color` ist Kompatibilitätspfad für ältere/alternative Lore-Formate, da der aktuelle Lore-Builder primär Cargo-Fuel-Zeilen schreibt.
- (Unklar) In sehr dichten Spawn-Situationen mit mehreren gleichartigen Eggs im Radius könnte das nearest/strict-Matching subjektiv als "unerwartete" Zuordnung wahrgenommen werden, obwohl es regelkonform ist.

### 6. Portfolio-Zusammenfassung
- (Sicher) `spawn_egg_state_restore` implementiert ein vollständiges State-Serialization/Deserialization-System auf Basis von Spawn-Egg-Lore und Event-getriebenem Restore.
- (Sicher) Technisch interessant ist die Kombination aus Bedrock-Events, robustem Lore-Parsing, räumlich-zeitlichem Matching und mehrstufiger Retry-Apply-Strategie.
- (Sicher) Die Komplexität liegt in der fehlerresistenten Zuordnung zwischen Item-Nutzung und späterem Entity-Spawn sowie in kompatiblen Fallbacks für Properties, Variant-System und C17-Cargozustände.