uebliche

Appearance

Feature Plan: Placement Inspector Tool ​

Summary ​

  • Owner: Yuna (review: Freddi)
  • Status: Implementation (edit-session teleport alpha)
  • Backlog Link: docs/agendas/uebliche.md → 📥 Inbox (Schematic Placement Bearbeitungstool)
  • Target Release: 2025.11.x (after overlay rollout hardening)

Goals ​

  1. Give builders a single “Placement Inspector” item that visualises all schematic placements inside editor instances without needing debug commands.
  2. Provide contextual actions (edit, duplicate, delete, overlay switch) via a right-click dialog on the highlighted placement.
  3. When “Edit Schematic” is chosen, teleport the builder into a dedicated editing instance containing only that schematic, keeping their relative offset/orientation intact so it feels seamless.
  4. Ensure every action is audit logged and respects overlay/base-layer separation.

Non-Goals ​

  • Replacing the existing /overlay command set (will coexist).
  • Building a full schematic editor UI inside the dashboard—this tool is in-world only.
  • Handling non-schematic objects (e.g., NPCs, particles); future extensions can hook into the same inspector.

User Stories ​

  1. Builder wants visual context: When I equip the inspector item, I immediately see holographic boxes for each placement plus a label showing schematic name, overlay key, and spawn group.
  2. Builder wants contextual actions: When I right-click while aiming at a placement hologram, I get a small modal with options (Edit schematic, Shift position, Duplicate to overlay, Delete).
  3. Builder wants deep editing: If I choose Edit schematic, I am moved to an isolated editing world where the schematic is pasted at origin and I am teleported to the same relative offset I had in the editor instance. Exiting the edit session returns me to my previous location via /schedit return.
  4. Builder wants collisions to stay safe: When multiple builders inspect concurrently, their holograms/actions should be scoped per player so we do not leak selections.

Scope ​

  • New Minestom item (likely a named nether star) granted automatically while inside ÜEditorInstance.
  • Placement visualisation pipeline that reuses PlacementBlockDisplay but scopes them to the holding player and includes floating text labels.
  • Raycast-based selection + action dialog (custom inventory or chat prompt) triggered via right-click.
  • Schematic edit session manager that spins up (or reuses) lightweight “edit worlds”, pastes the schematic, teleports the player, and tracks return location/orientation.
  • Audit logging for all actions (inspector open, edit session start/end, delete, duplicate).

Out of Scope ​

  • World save diffing after edit session (manual export/import remains required).
  • Automatic overlay activation; inspector only manipulates metadata/positions.

UX Flow ​

  1. Equip inspector: Player enters editor instance → PlacementInspectorService checks inventory each tick and inserts the custom item into a fixed slot (cannot drop).
  2. Visual overlay: Holding the item triggers per-player hologram spawn for placements within 96 blocks. Holograms show:
    • Bounding box via PlacementBlockDisplay
    • Billboard text (TextDisplay entity) with schematic name + overlay key + spawn group/probability.
  3. Selection: Player aims at a hologram and right-clicks:
    • Client ray is mapped to our phantom entity ID → service resolves the SchematicPlacement.
    • Open PlacementInspectorMenu (custom inventory) listing actions with short descriptions.
  4. Edit session:
    • EditSessionManager provisions an instance: clone from schematic-editor-template or reuse cached empty void world keyed by schematicId+userId.
    • Paste schematic at origin (respect rotation).
    • Compute relative offset from placement to player (position - placement origin) and teleport player so vantage point matches.
    • Provide exit command /schedit done or Return button that teleports player back and optionally captures modifications (future).
  5. Other actions:
    • Shift: open small GUI for +/- X/Y/Z (snap to block) and immediately update SchematicPlacement.
    • Duplicate to overlay: choose overlay key, copy placement, adjust metadata, respawn holograms.
    • Delete: soft-delete with confirmation + audit.

Technical Implementation ​

  1. Inspector Item & Lifecycle
    • Create PlacementInspectorService (depends on EditorSessionManager, WorldOverlayManager).
    • Inject custom item when editor mode starts; remove on exit.
    • Listen to PlayerItemUseEvent to detect right-click while aiming at hologram.
    • 2025-10-25 – Service scaffolding grants a reserved Netherstar (slot 8), restores previous hotbar items on exit, and cancels drops to keep the tool persistent.
  2. Per-Player Holograms
    • Extend SchematicPlacement to spawn per-player PlacementBlockDisplay + TextDisplay.
    • Maintain InspectorView objects keyed by player UUID → track active placements + cooldown for refresh.
    • Refresh radius & interval configurable.
    • 2025-10-25 – Inspector item spawns up to 80 glowing holograms within 96 Blöcken, tied to slot 8 selection and cleared automatically on slot/instance changes.
  3. Action Menu
    • Build a lightweight inventory GUI (e.g., size 9) with actions and tooltips.
    • When action selected, delegate to dedicated handlers.
    • All handlers call AuditLogService.record with action=editor.placement.*.
    • 2025-10-25 – Inspector item bereits per Raycast, zeigt Overlay/Spawn Infos und öffnet ein Chest-Menü (PlacementInspectorMenu) mit Info- und „Edit (coming soon)“-Buttons; PlacementEditSessionManager wird dabei schon vor-initialisiert.
    • 2025-11-06 – „Schematic bearbeiten“ öffnet nun eine temporäre Edit-Instanz und weist auf /schedit return als Ausstieg hin.
  4. Edit Session Manager
    • Manage pool of Minestom instances; use SchematicEditorInstance class wrapping ÜInstance.
    • On start: store original instance UUID, position, yaw/pitch. Provide scoreboard reminder and /schedit return.
    • On end: teleport player back, cleanup (optionally keep instance warm for 2 minutes).
    • 2025-10-25 – PlacementEditSessionManager placeholder tracks intent (player, schematic, source instance) so teleport/backfill logic can plug in later.
    • 2025-11-06 – Teleportflow implementiert: Session lädt Void-Instanz, pastet Schematic per Rotation, behält Spieler-Offset bei und räumt Instanz nach Rückkehr auf.
  5. Teleport Offset Calculation
    • Compute vector playerPos - placement.position.
    • Apply same vector relative to pasted schematic origin inside edit instance.
    • Preserve yaw/pitch for intuitive orientation.
  6. Data Writes
    • Position shifts & metadata changes persist via existing WorldAccess APIs; ensure overlay-specific updates respect overlayKey.
    • Duplicate/delete operations update Mongo and re-sync runtime placements via WorldOverlayManager.

API & Command Hooks ​

  • REST: extend /api/world/overlays to expose placement metadata needed by dashboard (no change required for in-world inspector).
  • Commands:
    • /schedit return – manual escape hatch.
    • /schedit reload – in case the edit template becomes corrupted.
    • /schedit sync <placementId> – optional future hook to push modifications back.

Dependencies ​

  • WorldOverlayManager (for placement listings + refresh).
  • AuditLogService (action tracking).
  • EditorSessionManager (detect players in editor mode).
  • Optional: SchematicCache for faster paste into edit instance.

Validation Plan ​

  1. Unit-test EditSessionManager offset calculations.
  2. Manual QA:
    • Equip inspector, verify holograms appear/disappear with item.
    • Right-click variations (base placement vs overlay) produce correct action menu.
    • Edit session returns player to exact original coordinates/orientation.
  3. Regression: ensure inspector item is removed on logout/instance exit.
  4. Load test: spawn 5 builders, confirm per-player holograms do not leak/duplicate.

Open Questions ​

  • Should edit sessions auto-import/export schematic changes? (current plan: manual workflow, future enhancement).
  • Where do we surface the action dialog (inventory UI vs chat prompt) for best responsiveness?
  • Do we need permissions granularity (e.g., editor.placements.delete) before exposing delete/duplicate?

Next Steps ​

  1. Implement die restlichen Inspector-Actions (Shift, Duplicate, Delete) inklusive Audit Logging.
  2. Ergänze /schedit-Hilfen (Scoreboard-Hinweis, optional /schedit reload) und definiere Cleanup-Timeout für Edit-Instanzen.
  3. Dokumentiere den vollständigen QA-Flow inkl. Diff-/Export-Schritten und aktualisiere die Dashboard-Doku, sobald die übrigen Aktionen live sind.

References ​

  • services/gameserver/src/main/java/net/uebliche/features/world/data/SchematicPlacement.java
  • services/gameserver/src/main/java/net/uebliche/features/world/entitis/PlacementBlockDisplay.java
  • docs/gameserver/features/world-overlays/plan.md