uebliche

Appearance

Feature Plan: Friends & Presence System ​

Summary ​

  • Owner: Freddi
  • Status: Delivery
  • Target Release: 2025.12.x
  • Backlog Entry: docs/agendas/uebliche.md → 📥 Inbox (Freunde- & Präsenz-System)

Goals ​

  • Give players a persistent friends graph that follows them between launcher, dashboard, proxy, and in-game sessions.
  • Enable low-friction social actions (chat, party-invite, join friend) that extend the existing party system instead of duplicating it.
  • Surface cross-platform presence (online, server, party state, voice) with privacy boundaries so players can control visibility.
  • Capture telemetry (requests sent/accepted, churn) to inform future clubs/social-network work.

Scope ​

  • Friend requests with optional note, expiration, and double-opt-in acceptance flow, plus reminders when pending.
  • Presence service that aggregates launcher logins, proxy connections, and world hops into a single stream for clients.
  • Social actions menu (mod + dashboard) for whisper, jump-to-server, invite to party, mute/unfriend.
  • Privacy controls per user: global visibility (public/friends only/offline) and per-friend overrides (favorite, limited visibility).
  • Audit trail for trust & safety: store who sent/accepted/blocked, timestamps, reasons.
  • Explicitly excluded: Clubs/groups beyond 1:1 relationships, gifting/inventory sharing, cross-network messaging relays, or third-party contact imports; these will be separate follow-up features.

Implementation Outline ​

  1. Domain Model & Storage
    • Introduce friends Mongo collection with composite documents { userId, friendId, status, visibility, favorite, createdAt, updatedAt }.
    • Add lightweight friendRequests collection for pending requests (message, origin, expiresAt) with TTL index to auto-clean stale invites.
    • Extend user profile document to cache counts + privacy defaults to avoid expensive aggregations per render.
  2. Friend Service (Server)
    • Kotlin service managing CRUD, validation (self-requests, duplicates, blocklist), and event dispatch.
    • REST routes: /api/friends (list + filters), /api/friends/requests, /api/friends/{friendId} (accept/reject/remove/favorite/block).
    • WebSocket channel (reuse auth WS infra) for push events: requestReceived, requestExpired, friendOnline/offline, statusChanged.
  3. Presence Aggregator
    • Hook Velocity plugin + Minestom game servers to emit presence events into Redis or Kafka-lite queue (existing collector bus if available).
    • Server module consumes events, maintains in-memory cache + publishes incremental deltas to connected clients.
    • Normalize states: OFFLINE, ONLINE, LOBBY, PLAYING:<serverId>, QUEUE, DND, IN_PARTY, IN_VOICE.
  4. Client/Mod Integration
    • common mod: add /friend command suite + UI overlay (list, filters, quick actions, notifications) leveraging existing Partys HUD components.
    • common/client-api: expose FriendService client with request/accept events for other mods (e.g., quest party matchmaker).
    • Dashboard/app: add Friends page under Social module with search, request queue, privacy settings.
  5. Proxy & Party Hooks
    • Velocity: auto-publish joinable server info + handle /friend join <name> by routing through permission checks/party capacity.
    • Party system integration: contextual action “Invite to party” from friend list, auto-join prompts when both parties opt in.
  6. Moderation & Safety
    • Reuse existing block/mute systems; ensure blocking auto-deletes friendships and prevents future requests.
    • Archive auditing data (actor, action, reason) into audit collection for dashboard review.

Dependencies ​

  • MongoDB collections + TTL indices provisioned by infrastructure team.
  • Redis/Message bus (reuse collector bus) for real-time presence fan-out.
  • Existing authentication/JWT context to authorize friend actions.
  • Client UI frameworks (Vue dashboard, in-game mod UI) and translation keys.
  • Integration with SimpleVoiceChat status events if we wish to show “in voice channel”.

Risks & Mitigations ​

  • Presence accuracy drift: lean on heartbeat + leave events with guard timers; fall back to periodic full-sync jobs to correct stale sessions.
  • Notification spam: batch presence updates and add rate limits per-user plus client-side throttling.
  • Privacy regressions: enforce visibility rules server-side; add integration tests for “appear offline” to ensure no metadata leaks.
  • Data skew/dupes: unique compound index (userId, friendId) + symmetrical write operations; scheduled reconciliation job to heal mismatched rows.
  • Scope creep into clubs/social graph: document explicit out-of-scope items and guard backlog from bundling them into this release.

Validation Plan ​

  • Unit tests for FriendService operations, blocklist enforcement, and privacy gating.
  • Integration tests covering REST + WebSocket flows (request, accept, revoke, presence updates).
  • Load test presence fan-out with synthetic players via existing simulator to ensure <200 ms fan-out to 2k subscribers.
  • Manual QA scripts for dashboard + mod UI (pending requests, favorites, offline mode, block/unfriend).
  • Canary rollout: enable for staff accounts first via feature flag, then widen using staged config.

Notes & Decisions ​

  • 2025-11-14 – Favor dedicated friends/friendRequests collections instead of embedding arrays in user docs to keep writes isolated and indices simpler.
  • 2025-11-14 – Use existing party HUD components for the in-game friends list to minimize UI work and ensure consistent theming.
  • 2025-11-14 – Presence payload will include server metadata (name, type, queue) but omit coordinates to respect privacy.
  • 2025-11-14 – First iteration shipped: Mongo-backed FriendService + REST (/api/social/friends*) behind new social:friends.* nodes and a Vue dashboard page (src/modules/social/pages/Friends.vue) for lists, requests, and privacy.
  • 2025-11-14 – /friend Minestom command now mirrors the REST feature set (list, add, accept/decline/cancel, remove) and is guarded by the new command:friend.* permissions.
  • 2025-11-15 – Admins with social:friends.read can inspect any player’s friends from the dashboard user detail view via /api/users/{id}/friends, mirroring the in-game data (counts, presence, privacy state).

References ​

  • docs/gameserver/features/party/README.md – existing party workflow to piggyback on invites and UI affordances.
  • docs/gameserver/features/feature-plan-template.md – base structure followed for this plan.