Feature Plan: Twitch Streamer Cosmetics & Scheduling

Summary

• Owner: Freddi
• Status: Discovery
• Target Release: 2025.11.x
• Backlog Entry: docs/agendas/uebliche.md → 📥 Inbox (Twitch-linked cosmetics page & scheduling)

Goals

• Reward players who stream Übliche with exclusive cosmetics and timed perks once their Twitch account is linked and currently live.
• Give staff tooling to configure which cosmetics unlock for all streamers vs. specific featured creators, and to schedule availability windows.
• Provide streamers with transparency: view eligible cosmetics, schedule participation windows, and confirm live status recognition.

Scope

• Cosmetics catalog extension with Twitch-tagged rewards (prefixes, particle trails, titles, etc.) and per-cosmetic unlock rules (global streamer, curated streamer list, time-bound events).
• Dashboard module/page for managing streamer cosmetics: assign cosmetics to streamers or groups, set start/end windows, and review active schedules.
• Event scheduler integration that triggers cosmetic grants/removals when streaming windows begin/end or when stream goes live/offline.
• Player-facing view (streamer control panel) showing upcoming cosmetic rotations, current unlock state, and manual recheck button.
• Out of scope: cosmetic rendering implementation (existing system handles equip visuals) and Twitch Connect flow (handled separately).

Implementation Outline

1. Data Model & Storage
   • Extend cosmetics schema to include twitchUnlockPolicy (global, curated list, event key) and required live duration thresholds.
   • Create linking table between Twitch user IDs and cosmetics with schedule metadata (start/end, timezone, recurrence).
   • Ensure audit logging for manual assignments/removals.
2. Scheduler & Event Hooks
   • Leverage existing event scheduler to watch streaming status + schedule windows; on match, enqueue grant job to the Minecraft server.
   • Support idle cleanup: revoke cosmetics when schedule expires or streamer offline beyond grace period.
3. Dashboard Admin UI
   • Build StreamerCosmeticsPage under dashboard modules with tabs: Catalog, Assignments, Schedule.
   • Provide filters by rank, Twitch user, cosmetic category; include bulk actions and confirmation modals.
   • Integrate with event actions so admins can attach cosmetics to temporal events for special campaigns.
4. Streamer Self-Service UI
   • Add dashboard page accessible to users with linked Twitch accounts showing available cosmetics, unlock conditions, and schedule timeline.
   • Offer manual status refresh (calls live status endpoint) and contact hint if they believe they’re eligible but not flagged.
5. Game Server Integration
   • Update cosmetic grant pipeline to accept Twitch-triggered events; ensure equip updates broadcast to active players.
   • Add grace period handling and persistence for unlocked cosmetics so they reapply on login during active window.
6. Notifications & Messaging
   • Optional: send Discord or in-game mail when new streamer cosmetics unlock; include summary in dashboard notifications.

Dependencies

• Twitch Connect live status service for real-time streaming detection.
• Cosmetics backend (services/gameserver/src/main/java/net/uebliche/features/cosmetics) for grant/revoke operations.
• Event scheduler infrastructure for timed triggers (services/gameserver/src/main/java/net/uebliche/platform/events).
• Dashboard UI framework for new pages (likely under app/dashboard/src/modules/cosmetics or new module).

Risks & Mitigations

• Complex scheduling: Start with simple one-off windows + recurring weekly slots; add validation to prevent overlapping conflicts.
• False positives (live status): Require confirmation of game category before granting; allow manual override and audit trail.
• Abuse potential: Limit cosmetics to opt-in/approved streamers; require staff approval for curated lists.
• Operational load: Provide bulk update tools and default templates to reduce manual work; document runbooks for seasonal events.

Validation Plan

• Tests for unlock policy evaluation (live status, schedules, curated lists).
• Stage end-to-end test: link Twitch test account, schedule cosmetic, start stream, verify grant appears in dashboard + in-game.
• QA revocation flow when stream ends or window expires.
• Post-launch monitoring on grant events, error logs, and streamer feedback loop.

Notes & Decisions

• 2025-11-05 – Initial cosmetics pool: glowing nameplates, trail variants, lobby emotes; expand after first iteration.
• 2025-11-05 – Scheduling UI will lean on existing event timeline components to reduce build time.

References

• Cosmetics service: services/gameserver/src/main/java/net/uebliche/features/cosmetics
• Event scheduler: services/gameserver/src/main/java/net/uebliche/features/events/schedule
• Dashboard modules boilerplate: app/dashboard/src/modules/* (reference events and roles modules for patterns)