2026 10 28 my party overhaul design - xopherdeep/do-it-for-the-xp GitHub Wiki

My Party overhaul: parties, friends and raids — design

Status: draft for owner review, 2026-10-28. This is Part 2 of multiplayer (Family Sync, 2026-10-22, is Part 3 and lists parties as out of scope).

Why

The My Party tab is a household roster with two "coming soon" tabs. The owner wants it overhauled: people form parties, invite friends, run raids together, and households can party together. Chores are already enemy strikes in the battle engine, so a raid is that idea shared across people.

Decisions (owner, 2026-10-28)

  • Household = the default party. Every family's heroes are automatically a party (the Home party). A hero can also belong to outside parties. It is not a second system: the household party is the same Roster/Activity/Raids views fed from local stores.
  • Friends connect by party code or QR only (a Game Master scans or types it, as in "Link a phone"). No search, no directory. A family friend list between Game Masters comes as a follow-up.
  • Raids are an async shared boss. Chores strike the beast; nobody has to be online together. A live "rally" (a short damage multiplier when several members are online) is a later polish.
  • Kid safety is per hero: Open / Ask first / Home only. Kids default to Ask first, adults to Open. A Game Master approves a given party once; raids inside it need no re-approval.
  • Cross-family chat is preset phrases and emoji only, plus Cheer and Poke. No free text leaves a family.
  • The four tabs stay (Roster, Activity, Synergies, Raids): the owner never hides a tab. Controls sit at the bottom of phone screens (thumb reach).
  • Settings > Party is rebuilt as the Game Master's control room.
  • No new backend: everything outside the app lives in xophz-compass-xp under a new xp-party/v1 route group.

Assumption to confirm: outside parties ride on XP Pro (the Family Sync gate). The Home party and household raids are free.

1. Scope

In: the Home party views; outside parties (form, code/QR, join requests, approvals, leave/remove, block); raids for both (household local, outside via the site); a small Synergies buff; preset chat, Cheer and Poke; the Settings > Party page; the site tables and routes; tests.

Out (later): family friend list between Game Masters; a public "looking for heroes" board; live rally; free-text chat; family circle posts (stay as a greyed planned card); push notifications beyond the existing alert bridge.

2. Model

  • Home party: derived from the family's profiles; admin = the Game Master. Cannot be dissolved.
  • Outside party: {id, name, banner, emblem, leader_hero, invite_rule (leader | members), code, created}. Members are {hero ref, household (family_id), role (leader | member), joined}.
  • Public hero card (the only thing that leaves a family): nickname, level, class, look. Never real names, photos, PINs, chore names or location.
  • Hero party setting (per hero, in the family's data): open | ask | home, default ask for kids and open for adults. Approved parties (per hero): the party ids the Game Master has okayed once.

3. Joining, leaving, safety

  1. A leader forms a party (name, banner, emblem). The site returns a code and QR. The code expires and can be rotated; rotating kills outstanding invites.
  2. A hero's Game Master scans or types the code and picks the hero: that creates a join request.
  3. Two approvals when needed: the leader (or a member, if the invite rule allows sharing the code, still needs the leader to accept) and the hero's Game Master when the setting is ask. open skips the Game Master step, home refuses.
  4. Leaving is always free. A Game Master can remove their hero or block a code at any time.
  5. Cross-family chat: preset phrases and emoji only. Cheer and Poke are fixed actions.

4. Raids

  • A raid is a great beast from the bestiary (a boss tier above chore beasts). HP is set from party size and the chosen window, so a small party does not face a big party's boss.
  • Windows: Quick 3 days, Standard 7, Epic 14. If the beast outlasts the window it retreats: no HP loss, no streak break, no penalty; the party can try again.
  • The leader picks beast and length. Outside raids need 2 or more members; the Home party can raid with one household.
  • Strikes come only from completed, approved quests. A quest awaiting approval shows as a pending strike and lands on approval; a rejected or reverted chore withdraws its strike. Damage comes from the chore's Fibonacci difficulty (the value battle uses), never from hero level. One completion = one strike. A daily cap per hero stops one grinder carrying the party.
  • Rewards on defeat: everyone who struck at least once gets the full base reward (XP, AP, a loot drop, cosmetic trophies). Extras by contribution only: top-striker title and a last-hit flourish. GP stays small, in line with the economy rebalance (epic #1633); raids must not mint money.
  • Each hero's own device pays the reward exactly once, keyed raid:{raid_id}:{hero_id}.

5. The site (xp-party/v1, in xophz-compass-xp)

Tables: xp_parties, xp_party_members, xp_party_requests, xp_party_events (a per-party change number, as the family records use), xp_raids, xp_raid_strikes (unique on the strike key).

Route Caller Does
POST /parties parent, hero key (adult) Forms a party, returns code
POST /parties/join {code, hero} parent Opens a join request
POST /parties/{id}/requests/{rid} {approve|decline} leader, or the hero's Game Master Resolves one side of a request
DELETE /parties/{id}/members/{hero} leader, hero's Game Master, the hero Leave or remove
POST /parties/{id}/code/rotate, POST /codes/{code}/block leader, Game Master Code safety
GET /parties/mine, GET /parties/{id}/feed?since= member families Roster and change feed
POST /parties/{id}/raids leader Starts a raid (beast, window)
POST /raids/{id}/strikes, DELETE /raids/{id}/strikes/{key} the hero's device Adds or withdraws a strike (idempotent)
POST /parties/{id}/presets member Sends a preset, Cheer or Poke

The site derives raid HP from the sum of strikes and enforces the daily cap and the window; a device never writes HP. Every route requires an entitled family (the same Gatekeeper_Xp_Pro_Licenses check as Family Sync) except nothing in the Home party touches the site. Public hero cards only; the site rejects any other field.

6. The app

  • src/lib/services/party/: pure modules with jest specs: raidDamage.ts (difficulty to damage, daily cap), raidState.ts (derive HP, retreat, defeat), partyRules.ts (open/ask/home gate, approvals), presets.ts.
  • A partyStore (Pinia, persisted) for outside parties, the hero settings and the approved list; a usePartyFeed composable polls the change number on the same cadence as Family Sync.
  • Strike capture hooks into QuestCompletionService (and its revert path) so strikes ride the existing completion event.
  • MyParty.vue gains the party switcher strip (Home first); the four tabs read the active party. New: PartySwitcher, raid card and strike ledger, PartyFormJoin panel, preset bar (bottom).
  • Synergies: same-day chores by 2 or more heroes give a small raid-strike buff for that day; cosmetic-sized, no GP/XP.
  • Settings > Party (PartySettings.vue): per-hero Open/Ask/Home, pending requests, parties my heroes are in (Remove, Block), my party code with QR and invite rule, raid defaults and raid alerts. PARTY_COMING_SOON shrinks to the planned family circle posts. PartyRaidsTab/PartySynergiesTab stop being "coming soon" cards.
  • Styling stays SNES-RPG (banners, emblems, StatusPlz HUD text, duotone icons).

7. When things go wrong

Offline: strikes queue in an outbox and send on reconnect (idempotent, so retries are safe). A lapsed Pro hides outside parties read-only and keeps the Home party and household raids. A raid that outlives its window retreats. A removed hero's strikes stay counted but the hero stops receiving rewards for later raids. A blocked or rotated code never reveals who held it.

8. Slices

  1. Shell + Settings + Home party: switcher, Synergies buff, household raids, the rebuilt Settings page. Free, no site.
  2. Site: tables, routes, tests (rehearsed on the local Docker WordPress).
  3. Outside parties: form, code/QR, join and approvals, roster, presets.
  4. Outside raids: strikes, HP, retreat, rewards payout.
  5. Follow-ups: friend list between Game Masters, rally, board.

Slices 1 and 2 are independent and can run in parallel. Household raids across devices need Family Sync (Part 3); on one device they work from slice 1.

9. Testing

Jest: damage and cap math, raid state (strike, withdraw, defeat, retreat), party rules (open/ask/home), preset allow-list, the Settings page and the tab views. PHP: route permissions, idempotent strikes, caps, code rotation and blocking, the Pro gate. E2E: seed a world, run a household raid to defeat, and a two-family join on the local WordPress.

10. Open items for the owner

  • Confirm outside parties are XP Pro (assumed).
  • Raid reward numbers (XP, AP, loot tiers) and the daily cap: starting values are tuned with the economy rebalance.
  • Beast roster for boss tier: pick from the bestiary or paint new ones.
⚠️ **GitHub.com Fallback** ⚠️