uebliche

Appearance

Feature Plan: World Overlays & Base World Editing ​

Summary ​

  • Owner: Freddi (delegate: Yuna)
  • Status: Implementation (data layer)
  • Target Release: 2025.11.??-a (tentative)
  • Backlog Entry: docs/agendas/uebliche.md → 📦 Backlog (2025-10-21)

Goals ​

  • Allow the world to load optional placement overlays per event/minigame.
  • Keep the base world editable in editor mode without overlay interference.
  • Provide runtime hooks so overlays can be toggled by schedule, events, or commands.

Scope ​

  • Data model support for marking placements with an overlayKey (null => base).
  • Overlay activation manager that applies/removes placements on demand.
  • Editor tooling to choose the active overlay, copy base placements, and preview overlays in-world.
  • Block-display based preview toggles in editor mode so builders can inspect overlay placements without applying them permanently.
  • Minimal API surface (REST + commands) so runtime automation can flip overlays.
  • Backup browsing & restore flow so S3 snapshots can be inspected and optionally restored as new world instances.

Out of Scope ​

  • Full event scheduling UI (reuse existing event/minigame services for triggers).
  • Non-placement overlay assets (e.g. block regen or scoreboard wiring) beyond references in overlay metadata.

Implementation Outline ​

  1. Data layer: add overlayKey to SchematicPlacement; optional WorldOverlay collection linking overlays to map versions and placement IDs.
    • 2025-10-21 – Implemented overlayKey on placements, persisted overlay groups in world data, and created a WorldOverlay Mongo model.
  2. Runtime: introduce WorldOverlayManager (depends on WorldManager + event/minigame services) to load/unload overlays and track active state.
    • 2025-10-21 - Manager handles hologram previews, full block application with rollback, and automation hooks from temporal events.
    • 2025-10-22 - Overlay activation now evaluates spawn groups (requires/excludes) with deterministic probabilities so minigame-specific placements stay consistent.
  3. Editing UX: extend PlacementsEditor + editor UIs with overlay selection (base or named overlay), duplication from base, block-display previews, and “apply overlay” actions.
    • 2025-10-21 – Placements editor keeps a per-player overlay selection (base vs overlay) so placement tools only target the chosen layer.
    • 2025-10-21 – /overlay copy-base <key> clones current base placements into an overlay and switches the editor context automatically.
  4. API/Commands: endpoints for listing/creating overlays (/api/world/overlays), and commands (/overlay reload <key>, /overlay activate/deactivate).
    • 2025-10-21 – Added /overlay Minestom command (list/select/copy-base/activate/deactivate) plus /api/world/overlays REST endpoints (list/create/delete/update placements) backed by WorldOverlayManager.
  5. Integration: wire event/minigame activation hooks to call the overlay manager; update /itemmodel inventory listing to display overlay slug.
    • 2025-10-21 – Temporal events expose WORLD_OVERLAY_SET_ACTIVE actions that toggle overlays via the runtime manager for all registered instances.
  6. Backups & Restore: schedule S3 snapshot jobs; expose endpoints/commands to list, preview, and restore backups (restore spins up isolated instances).
    • 2025-10-21 – Runtime state now persists block snapshots per overlay activation and restores them automatically when instances bind.
  7. Observability & Docs: update monitoring/logging to record overlay toggles; document workflow in vault + README.
    • 2025-10-21 – Debug sidebar now surfaces the active editor map/version plus overlay label so builders can confirm their world context at a glance.
    • 2025-10-21 – Dashboard Overview + Overlays-Ansicht bieten CRUD auf /api/world/overlays samt Map-Version-Kontext.
    • 2025-10-21 – /api/world/overlays/state exposes current runtime overlay state; S3 backups logged per activation for audit/monitoring.

Dependencies ​

  • MongoDB schema migration for placements + optional overlays collection.
  • Event/minigame services to signal overlay activation.
  • Dashboard/API team for overlay management UI (optional after initial CLI/API).

Risks & Mitigations ​

  • Risk: Overlay misconfiguration corrupts base world ⇒ keep base overlay separate, require explicit apply/remove commands.
  • Risk: Performance when swapping large overlays ⇒ cache placements per overlay, diff load/unload operations.
  • Risk: Editors forget to switch overlay ⇒ make selection explicit in UI, default to base (null).

Validation Plan ​

  • Automated tests for overlay manager (activation/deactivation, base editing).
  • Manual QA: apply overlays in dev instance, ensure base editing unaffected.
  • Smoke tests: start with overlay disabled/enabled combination, ensure commands/events toggle correctly.
  • Nightly backup job syncs base + overlay placements to S3 so we can roll back if an overlay rollout corrupts state.
  • Manual verification of backup browsing + restore flow: list archives, preview metadata, restore into new world instance, confirm isolation, and clean-up.

Notes & Decisions ​

  • 2025-10-21: Chosen overlayKey approach (null => base) to keep backward compatibility.
  • 2025-10-21: Overlay manager responsible for both runtime toggles and editor previews.
  • 2025-10-21: Preview mode will rely on holograms until reversible block-application routines (diff + rollback) are in place.
  • 2025-10-22: Placement metadata now supports spawn groups, dependencies, and mutually exclusive variants for event overlays.

References ​

  • Agenda backlog entry → docs/agendas/uebliche.md (📦 Backlog, 2025-10-21).
  • Existing placement/editor code (PlacementsEditor, WorldManager, ÜInstanceManger).
  • Event/minigame service docs.
  • New runtime pieces: WorldOverlay, WorldOverlayManager, and WorldAccess overlay storage.
  • Editor REST: /api/world/overlays handled by OverlayRoutes (list/create/delete) with caching via WorldOverlayManager.