Files
NX2navi/runtime/coop_offer.h
chrg6 7e07e13bac Add co-op, off by default: rooms through a relay, progress sync between the players' own saves, and a Co-op tab.
Each player keeps their own game and save. One player makes a room, the others join it with its secret, and story flags and, by the room's rules, items, songs, quest items, small keys (a shared pool), rupees and ammunition reach every save. The layer is a host thread with one UDP socket to a relay the players run themselves (tools/coop_relay.py, Python's standard library only); the messages between the players are sealed with a key from the room's secret (XChaCha20-Poly1305, Monocypher 4.0.2 vendored with its licence and a row in THIRD_PARTY_NOTICES.md), every change is signed by the player who made it, a player accepts a room by its members' keys and the key of its rules, the save is copied to coop-backup before anything is applied, and values are set through the game's own routines between frames. The Co-op tab makes, joins, accepts, removes and leaves, and the menu takes typed text for the name, the relay and the secret. This is the contributor's pull request #518 on this line.

Nothing reaches the network while co-op is off: the socket is opened, and the relay's name looked up, only after co-op is on, a relay is set and a room is made or joined. There is no default relay.

Left out of the pull request: the other players drawn in the world (the "puppets") with the copied engine they need. They were unfinished, added two patch sites to the game's per-frame update that could not be put through the differential tests here, and their file helpers clashed with the ones this line already has. So no position is sent: the POS message's codec stays, nothing sends it.

Changed against the pull request:
- The menu's test hook drives the Co-op tab only when it comes from the environment. From nx2navi.ini it could turn co-op on, join a room and accept its offer.
- The log's label for a room is hashed from the secret instead of being its first three characters.
- A game that has not saved yet has no save to copy, and takes nothing from the room until it has saved once; that used to count as a copy made.
- A PING's token no longer carries the PC's uptime.
- On Windows the maker's key file and its folder get an access list with the player's account alone.
- The tests that link the platform layer get the socket library, and the save test a stand-in for the title screen's hook.

Checked on Windows, where the pull request had never been compiled: the runtime builds and links; --probe-coop passes (sockets on 127.0.0.1, the codec against its byte vectors, a fuzz of every parser, two sessions through a hostile mock relay, a relay restart, the sync engine); tests/coop_relay_test.py passes its 61 tests, with the probe through the real relay on 127.0.0.1 at 0 and 30 % loss; tests/coop_page_check.py passes and its deliberate fault fails 48 checks. Not checked: two games in one room (one game runs at a time here), any real network, the tab in the game.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-11 00:11:41 -05:00

46 lines
3.9 KiB
C

// What the menu's Co-op tab reads of a room and asks of it (coop_game.c), in a header of its own without host.h so that
// the menu's C++ can include it. Every call may be made from any thread and never waits for the sync engine: what is
// read is a copy the coop thread publishes at each of its steps, and what is asked is carried out by the coop thread at
// its next step (a few ms in a room), which logs the outcome.
#pragma once
#include "coop_proto.h"
#include "coop_state.h"
// What joining the room means, for the player to accept: the engine's offer (coop_state.h: CoopOffer), with the
// relay's names for members not identified yet. Nothing from a room is applied to the game before the player accepted
// its offer and a copy of the save was made (<profile>/coop-backup/<time>/, docs/coop.md; the first copy for a room is
// "first-<time>" and is never pruned). An accepted offer stays accepted while every member is an identity accepted,
// the rules and the key that signs them stay the same and the same save is played; anything else is a new offer, and
// nothing more is applied until that one is accepted. A member in the room that never identified itself keeps the room
// unaccepted. The offer's number is random for each start of the game. The COOP_ACCEPT setting accepts one offer by its
// number (the log shows it) or, from the environment only, every offer with "always"; the menu calls coop_game_accept.
// 1 when there is an offer; without one (token 0) the members and disagree are still filled in while in a room.
int coop_game_offer(CoopOffer *out);
// Accepts the offer of that number, the one the player was shown: 1 when it is the offer published last (or that offer
// is accepted already) and no member in the room is unidentified; 0 otherwise, and nothing changes (ask again once
// unidentified is 0). The coop thread accepts it at its next step only while it is still the room's offer.
int coop_game_accept(uint32_t token);
// The room's maker (its game holds the key that signs the rules, kept in the profile across restarts) resets the pools:
// every game joins them again with what they held for the players in the room. 1 when asked (this game is the maker).
// The setting COOP_RESET_POOLS does it too (when it changes to a value other than 0).
int coop_game_reset_pools(void);
// The room's maker removes a key by its fingerprint (xxxx-xxxx-xxxx-xxxx, as the offer, the contributors and the log
// show it), also of a member that left: every game drops it and its pool records, and a member in the room that holds
// it is removed at the relay too. 1 when asked (a fingerprint, and this game is the maker). The setting COOP_REMOVE
// takes a fingerprint too. A member is never removed by its id from here: ids pass to other players as members come
// and go.
int coop_game_remove_key(const char *fingerprint);
// The identities the pools admit and what each took beyond what it brought, per pool (coop_state.h: CoopContributor):
// whom the maker would remove after a drain. Their count (at most max), as published at most half a second ago.
int coop_game_contributors(CoopContributor *out, int max);
// This game holds the key that signs the room's rules (it made the room, in this start of the game or an earlier one):
// its removals and pool resets act.
int coop_game_is_maker(void);
// The members this game would show in its world (nothing draws them in this build), one bit per member id: identified (heard, so not disputed
// between two keys), not removed, and with a key this player accepted under the name it signs now (no accepted_as).
// A member the player has not accepted, or who is not identified, shows no puppet. accepted(key fingerprint, user): 1
// when this player accepted that key. Kept apart from the game so that --probe-coop checks it (coop_proto.c).
uint32_t coop_offer_shown(const CoopOffer *o, int (*accepted)(const char *key, void *user), void *user);
// The same, as the coop thread last published it (0 outside a room).
uint32_t coop_game_shown(void);