coop-session

name: coop-session description: >- Architecture blueprint for drop-in/drop-out co-op and multiplayer sessions: lobby lifecycle, join rules, authority, replication, late-join snapshots, anti-grief content rules, scaling, topology, matchmaking, host migration, split-screen, loot distribution, revive, cross-play, and co-op design. Use when designing co-op, lobbies, netcode, matchmaking, or when late joiners desync, hosts gain unfair advantage, rewards conflict, or co-op is not fun.

Co-op Session

Build the drop-in co-op layer (2–4 players) of an open-world action RPG — the Genshin lobby model: guests visit the host's world, content rules make griefing structurally impossible, and the session ends gracefully when the host leaves. Architecture level (authority, prediction, relevance) — no low-level netcode. The hub also maps the wider netcode landscape (lockstep, rollback, FPS lag-comp, MMO scale, matchmaking) and the co-op design craft so you can pick the model that fits your genre, not just copy Genshin. Primary evidence: the Grasscutter server reimplementation + the verified co-op rules already sourced across this skill family.

The architecture rule

The host's world is a server instance, authority is a per-category dial, and the content matrix is data.

SESSION (the host's-world model)
  the "host's world" = a SERVER-SIDE world instance the host owns —
  never the host's machine (no host advantage, no NAT, no exposed
  IPs; host disconnect = the instance closes)
  guests' own worlds DON'T EXIST while visiting (instance destroyed/
  suspended; their state untouched)
  join = the same EnterScene handshake as solo with a TeamJoin
  reason; the host's world flips to MP mode; guest spawns at host
  leave = graceful re-creation of the guest's own instance
  host leaves = warn -> complete -> close: everyone ejected to
  their own worlds; claimed rewards survive (server-side)
  NO host migration — acceptable because returning home is painless

AUTHORITY (a spectrum, not a switch — the datamined Genshin hybrid)
  server-HARD     economy, claims, inventory, progression (always)
  server-owned    enemy AI state, spawns, world events
  client-trusted  movement (plausibility-validated after the fact)
                  and even damage in Genshin's PvE (client computes,
                  server applies + sanity-checks) — viable ONLY in
                  coop PvE where combat cheats can't touch the
                  economy; PvP or shared stakes = server computes
  the rule: protect PERSISTENCE hard; tolerate trust on EPHEMERA

REPLICATION (the canon, architecture level)
  local player: predict inputs, server corrects, replay unacked
  remote players: interpolate ~100-200 ms in the past
  abilities: client requests + cosmetic prediction, server
  validates outcome (cooldown/cost) and broadcasts
  relevance: replicate (and SIMULATE) only near players;
  hysteresis at boundaries
  late join: ONE full world-state snapshot at entry (chests, dead
  enemies, weather, host clock) from the world-state store — then
  deltas; never a replayed event history

CONTENT RULES (the matrix as data — the anti-grief)
  host-only   chests, collectibles, NPCs, quests, time-of-day
  instanced   enemy drops, ore, energy-gated claims (per-player
              resin; respawn after the LAST claim)
  shared      plants/specialties (first-come), fishing spots
  + story content disables co-op entirely; cutscenes are
  host-only presentation (guests keep playing, see a frozen avatar)

Reference map

Build order (4 shippable tiers)

Tier 1 — Session skeleton
- [ ] Session service: create/invite/join-request (with expiry ~10s)
      /approve/kick/leave; the three host permission modes (reject /
      direct / approval)
- [ ] The host's-world instance model: guest world teardown on join,
      graceful re-creation on leave; spawn-at-host placement
- [ ] Join gates as data: progression unlock, world-level rules
      (guest's WL >= host's; the endgame free-join exception)
- [ ] The host-leave protocol: warn -> complete encounter -> eject
      all (rewards already committed server-side)
Tier 2 — Replication core
- [ ] Authority dial per data category (the spectrum above);
      server-hard transactions reuse progression-economy idempotency
- [ ] Local prediction + smoothed reconciliation; remote
      interpolation buffer (~100-200 ms / 2 snapshots)
- [ ] Late-join snapshot from the world-state store (ALL mutable
      state — the single source from quest/save skills)
- [ ] Relevance: radius-based replication AND simulation bounding,
      with hysteresis; degressive update rates by distance
Tier 3 — Content rules
- [ ] The matrix as data per content type (host-only / instanced /
      shared); interaction authority = world owner
- [ ] Party composition budget (total 4: 2+2 / 2+1+1 / 1x4; dupes
      allowed in overworld, denied in instances)
- [ ] Enemy scaling by player count (HP-only is the shipped lesson:
      150/200/250%, ATK flat — Genshin removed ATK scaling);
      per-player threat in the AI (enemy-ai-framework)
- [ ] Co-op gating: story quests disable sessions; host cutscenes =
      per-player presentation (guests unaffected)
Tier 4 — Polish and services
- [ ] Domain/instance co-op: per-player claims, no-dupe team rule,
      targeted matchmaking (content-scoped, not open-world)
- [ ] Disconnect handling: idempotent transactions across drops;
      rejoin = a fresh join request (no session reconnect)
- [ ] Regions/platforms: regional servers (no cross-region),
      cross-platform within region; the latency-tolerant combat
      design pass (no cross-player frame-perfect mechanics)
- [ ] Network debug: emulated lag/loss testing, the desync
      detection overlay

Numbers (starting points — sourced anchors)

Flagged — never invent: the official server tick rate (Grasscutter's 1 Hz logic loop is NOT representative), AFK kick timers, the host disconnect grace period, per-player session bandwidth, Genshin replication radii, CCU figures. Full tables in session-authority.md and replication.md.

Engine mapping

Failure modes

The 16 classic co-op bugs (host advantage, late-join desync, the singleplayer-assumptions retrofit — with three documented postmortems, misprediction pops, the trust-the-client hole, relevance popping, the shared-interactable race, host-leave data loss, time/weather divergence, the cutscene collision, quest-state contamination, the bandwidth whale, disconnect mid-transaction, the desync iceberg, the netcode-model mismatch, and co-op designed as a single-player afterthought) are cataloged in pitfalls.md with symptom → root cause → prevention.

Related skills

• progression-economy — server-authoritative transactions and idempotency keys reused for every network op.
• character-controller — the deterministic tick + intent + snapshot structure that prediction/reconciliation build on.
• save-persistence — the world-state store feeding the late-join snapshot; server-authoritative as one of its four save models.
• quest-system — host-only progression, the world-state store the late-join snapshot reads from.
• world-time-weather — host-clock authority, seed replication.
• loot-drop-system — the instanced/shared drop matrix, per-player claims.
• enemy-ai-framework — server-owned AI, per-player threat.
• scene-flow-manager — the EnterScene handshake the join flow reuses.
• dialogue-system / cinematic-system — per-player presentation (host cutscenes don't capture guests).
• camera-system — the multi-target framing rig reused for shared-screen / split-screen co-op (coop-design.md).
• hud-system — co-op nameplates, player colors, through-wall silhouettes, and pingless ping comms live in the HUD layer.