uebliche

Appearance

Feature Plan: Item Management ​

Summary ​

  • Owner: Freddi
  • Status: Delivery
  • Target Release: Rolling
  • Backlog Entry: Projects/Uebliche/agendas.md ▸ 📦 Backlog ▸ Item editor enhancements

Goals ​

  • Manage custom item definitions shared between the desktop editor and the Minestom server.
  • Provide CRUD APIs for item models, textures, and metadata consumed by gameplay features.
  • Keep item schema stable and extensible for future crafting, quests, and shops.

Scope ​

  • Maintain REST endpoints for /api/item-models with validation and partial updates.
  • Persist item definitions via Mongo managers under platform/data/mongo.
  • Sync changes to the resource pack pipeline so updated models appear in game.
  • Surface item configurations to gameplay features through dependency-injected registries.
  • Exclude gameplay balancing rules (handled by individual features like quests/economy).

Implementation Outline ​

  1. features/item registers repositories and domain models for custom items.
  2. REST layer (EditorWebService) handles list, create, update, delete operations.
  3. Desktop app (ItemModels.vue, itemModelStore.ts) edits entries and triggers rebuilds.
    • 2025-10-22 - Control Center Items tab manages base items, item abilities, and tier overrides.
  4. Keep schema docs and migration notes here and in the vault mirror when fields change.

Dependencies ​

  • MongoDB collections for item definitions and localization.
  • Resource pack feature for supplying corresponding assets.
  • Desktop application editors for authoring.

Risks & Mitigations ​

  • Schema changes: version payloads; add migration scripts in CollectionManager.
  • Broken models: add preview and validation hooks before persisting.
  • Consistency with resource pack: automate rebuilds and add notification hooks.

Validation Plan ​

  • Unit tests for item serialization adapters (platform/data/gson/ItemStackTypeAdapter).
  • Regression checks by loading items on a dev server and inspecting render output.
  • Future integration tests once quest/economy modules depend on items.

Notes & Decisions ​

  • Capture schema changes (new fields, deprecated properties) under agenda ⚖️ Decisions.
  • Mirror this file to /Projects/Uebliche/docs/gameserver/features/item/plan.md after each edit.
  • 2025-10-18: Dashboard Item-Model-Detailansicht erlaubt jetzt Umbenennen, Beschreibungspflege und direkten .bbmodel-Upload/-Download.
  • 2025-10-18: Multipart-Flag pro Item-Model verfügbar; Root-Gruppen werden virtuell gesplittet und beim Resourcepack-Export berücksichtigt.
  • 2025-10-22: Item ability registry exposed via REST; dashboard Items tab validates ability parameters, tier overrides, and spawn metadata.
  • 2025-10-22: Base-Items unterstützen Model-Overrides mit Overlay/Event-Triggern; Editor bietet Pflege der alternativen ItemModel-IDs und führt zusätzliche Waffen-, Rüstungs- und Namens-Cosmetic-Typen (MiniMessage-basiert) ein.

References ​

  • services/gameserver/src/main/java/net/uebliche/features/item
  • services/gameserver/src/main/java/net/uebliche/platform/data/gson/ItemStackTypeAdapter.java
  • Desktop item editor under app/dashboard/src/views/home/ItemModels.vue