uebliche

Appearance

Feature Plan: NPC System ​

Summary ​

  • Owner: Freddi
  • Status: Delivery
  • Target Release: Rolling
  • Backlog Entry: Projects/Uebliche/agendas.md ▸ 📦 Backlog ▸ NPC interactions

Goals ​

  • Provide configurable non-player characters for lobbies, tutorials, and interactive experiences.
  • Support scripted behaviors, dialogues, and cosmetic customization.
  • Ensure NPC updates propagate safely across clustered Minestom instances.

Scope ​

  • Manage NPC definitions under features/npc, including spawn rules and skins.
  • Integrate with features/dialog and features/links for interactions.
  • Surface NPC configuration to the desktop management app (future roadmap).
  • Exclude combat AI or pathfinding beyond simple waypoints (handled by other modules if needed).

Implementation Outline ​

  1. Core NPC registry loads definitions and syncs them across shards.
  2. Hook spawn/despawn lifecycle into platform/minestom/GameServer.
  3. Provide API endpoints or command hooks for runtime refreshes.
  4. Document configuration format and editor requirements here and in the vault mirror.

Dependencies ​

  • Minestom instance lifecycle management.
  • Skin/texture delivery via resource pack pipeline.
  • Future desktop UI modules for authoring NPCs.

Risks & Mitigations ​

  • Performance: limit NPC counts per chunk; profile under load.
  • Desync: use actor system or event bus to broadcast updates.
  • Content drift: keep definitions source-controlled and review via pull requests.

Validation Plan ​

  • Add integration tests spawning NPCs in a test world and verifying metadata.
  • Manual staging test: deploy to dev server and inspect NPC behavior.
  • Monitor CPU/memory metrics via monitoring feature during load tests.

Notes & Decisions ​

  • Log behavior model changes or new interaction models under agenda ⚖️ Decisions.
  • Mirror this plan to /Projects/Uebliche/docs/gameserver/features/npc/plan.md.
  • 2025-10-23: Dashboard besitzt jetzt eine NPC Detail-/Editorseite inkl. /api/npcs/{id} Update-Flow; Listenansicht verlinkt direkt in den Editor.
  • 2025-10-23: NPC-Daten referenzieren SkinTexture Datensätze (skinTextureId); die Dashboard-Skinbibliothek (/skins) liefert Vorschau und Auswahl für NPCs.
  • 2025-10-23: Skin-Detailseiten (/skins/:id) erlauben das Pflegen von Base64-Werten, Hash und Flags inklusive Vorschau – zentrale Quelle für NPC-Skins.
  • 2025-10-18: Dashboard erhielt eine NPC-Liste (read-only) samt /api/npcs Endpoint als ersten UI-Schritt.

References ​

  • services/gameserver/src/main/java/net/uebliche/features/npc/BasicNPC.java
  • services/gameserver/src/main/java/net/uebliche/features/dialog
  • services/gameserver/src/main/java/net/uebliche/platform/minestom