@hadoku/game-server 0.0.0-stage → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/dist/base-path.d.ts +29 -0
- package/dist/base-path.js +30 -0
- package/dist/busy.d.ts +40 -0
- package/dist/busy.js +23 -0
- package/dist/capacity.d.ts +9 -0
- package/dist/capacity.js +6 -0
- package/dist/config.d.ts +247 -0
- package/dist/config.js +271 -0
- package/dist/edge-auth.d.ts +43 -0
- package/dist/edge-auth.js +47 -0
- package/dist/erase/anonymise.d.ts +7 -0
- package/dist/erase/anonymise.js +7 -0
- package/dist/erase/index.d.ts +18 -0
- package/dist/erase/index.js +20 -0
- package/dist/erase/legacy-ids.d.ts +7 -0
- package/dist/erase/legacy-ids.js +24 -0
- package/dist/erase/recordings.d.ts +26 -0
- package/dist/erase/recordings.js +128 -0
- package/dist/erase/rooms.d.ts +63 -0
- package/dist/erase/rooms.js +67 -0
- package/dist/gate.d.ts +27 -0
- package/dist/gate.js +15 -0
- package/dist/http/client-events.d.ts +25 -0
- package/dist/http/client-events.js +15 -0
- package/dist/http/page.d.ts +26 -0
- package/dist/http/page.js +35 -0
- package/dist/http/prepared.d.ts +14 -0
- package/dist/http/prepared.js +16 -0
- package/dist/http/request.d.ts +59 -0
- package/dist/http/request.js +37 -0
- package/dist/http/room-core.d.ts +160 -0
- package/dist/http/room-core.js +278 -0
- package/dist/http/trim.d.ts +23 -0
- package/dist/http/trim.js +76 -0
- package/dist/http/usage.d.ts +22 -0
- package/dist/http/usage.js +16 -0
- package/dist/kernel.d.ts +4 -0
- package/dist/kernel.js +26 -0
- package/dist/log.d.ts +9 -0
- package/dist/log.js +9 -0
- package/dist/people.d.ts +105 -0
- package/dist/people.js +145 -0
- package/dist/play/clock.d.ts +39 -0
- package/dist/play/clock.js +81 -0
- package/dist/play/diagnostics.d.ts +21 -0
- package/dist/play/diagnostics.js +35 -0
- package/dist/play/engine-runtime.d.ts +200 -0
- package/dist/play/engine-runtime.js +309 -0
- package/dist/play/game-adapter.d.ts +158 -0
- package/dist/play/game-adapter.js +1 -0
- package/dist/play/host.d.ts +482 -0
- package/dist/play/host.js +950 -0
- package/dist/play/jvm-transport.d.ts +25 -0
- package/dist/play/jvm-transport.js +1 -0
- package/dist/play/local-jvm.d.ts +325 -0
- package/dist/play/local-jvm.js +829 -0
- package/dist/play/match/hosted.d.ts +92 -0
- package/dist/play/match/hosted.js +151 -0
- package/dist/play/match/outcome.d.ts +26 -0
- package/dist/play/match/outcome.js +21 -0
- package/dist/play/match/shell.d.ts +378 -0
- package/dist/play/match/shell.js +613 -0
- package/dist/play/recording/retention.d.ts +36 -0
- package/dist/play/recording/retention.js +89 -0
- package/dist/play/recording/writer.d.ts +185 -0
- package/dist/play/recording/writer.js +90 -0
- package/dist/play/relay-socket.d.ts +128 -0
- package/dist/play/relay-socket.js +194 -0
- package/dist/play/runtimes/in-process.d.ts +47 -0
- package/dist/play/runtimes/in-process.js +43 -0
- package/dist/play/runtimes/relay-match.d.ts +166 -0
- package/dist/play/runtimes/relay-match.js +240 -0
- package/dist/play/runtimes/relay.d.ts +128 -0
- package/dist/play/runtimes/relay.js +183 -0
- package/dist/play/runtimes/streamed.d.ts +116 -0
- package/dist/play/runtimes/streamed.js +148 -0
- package/dist/play/start-queue.d.ts +65 -0
- package/dist/play/start-queue.js +187 -0
- package/dist/room/avatar.d.ts +1 -0
- package/dist/room/avatar.js +28 -0
- package/dist/room/caller.d.ts +21 -0
- package/dist/room/caller.js +1 -0
- package/dist/room/constants.d.ts +27 -0
- package/dist/room/constants.js +27 -0
- package/dist/room/events.d.ts +59 -0
- package/dist/room/events.js +174 -0
- package/dist/room/identity.d.ts +89 -0
- package/dist/room/identity.js +98 -0
- package/dist/room/lobby.d.ts +426 -0
- package/dist/room/lobby.js +880 -0
- package/dist/room/membership.d.ts +64 -0
- package/dist/room/membership.js +76 -0
- package/dist/room/provisioning.d.ts +22 -0
- package/dist/room/provisioning.js +46 -0
- package/dist/room/record.d.ts +63 -0
- package/dist/room/record.js +39 -0
- package/dist/room/room-list.d.ts +67 -0
- package/dist/room/room-list.js +66 -0
- package/dist/room/seats.d.ts +39 -0
- package/dist/room/seats.js +58 -0
- package/dist/room/session.d.ts +91 -0
- package/dist/room/session.js +156 -0
- package/dist/room/socket-auth.d.ts +2 -0
- package/dist/room/socket-auth.js +10 -0
- package/dist/room/watching.d.ts +35 -0
- package/dist/room/watching.js +72 -0
- package/dist/room/watchparty-link.d.ts +1 -0
- package/dist/room/watchparty-link.js +17 -0
- package/dist/stream/alloc.d.ts +115 -0
- package/dist/stream/alloc.js +368 -0
- package/dist/stream/index.d.ts +66 -0
- package/dist/stream/index.js +293 -0
- package/dist/telemetry.d.ts +46 -0
- package/dist/telemetry.js +25 -0
- package/dist/testPort.d.ts +1 -0
- package/dist/testPort.js +28 -0
- package/package.json +36 -4
- package/README.md +0 -3
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `HostedMatch`: the shell lifecycle ({@link MatchShell}) plus the host lifecycle every engine
|
|
3
|
+
* needs the same way — start, resume-after-a-restart, the replay gag's `replayed` hook, and the
|
|
4
|
+
* sweep at stop/fail/exit (`GameSession.ended`). Nothing here is Forge-specific:
|
|
5
|
+
* `play/match.ts`'s `Match` is `HostedMatch<BridgeLine, BridgeCommand>` with a `ForgeSession`;
|
|
6
|
+
* `fixtures/toy-game/match.ts`'s `ToyMatch` is `HostedMatch<ToyLine, ToyCmd>` with the toy's;
|
|
7
|
+
* `runtimes/relay-match.ts`'s `RelayMatch` is `HostedMatch<RelayLine, RelayCommand>` with a
|
|
8
|
+
* `RelaySession`. What stays abstract here (`seats`, `onLine`, `concedeCommand`, `forceConcede`)
|
|
9
|
+
* is exactly what only the game itself can answer.
|
|
10
|
+
*
|
|
11
|
+
* Moved out of `play/match.ts` (a pure move — no behaviour changed, every importer
|
|
12
|
+
* rewritten, no shim): `match.ts` keeps `Match`, Forge's own `HostedMatch`.
|
|
13
|
+
*/
|
|
14
|
+
import type { HostEvents, MatchHost, MatchHostFactory, MatchSpec, TurnSnapshot } from '../host.js';
|
|
15
|
+
import type { StartEvents } from '../start-queue.js';
|
|
16
|
+
import { MatchShell, type ShellDeps } from './shell.js';
|
|
17
|
+
/** What any `HostedMatch` needs beyond {@link ShellDeps}: a factory for the host its own engine runs on. */
|
|
18
|
+
export interface HostedMatchDeps<Line extends {
|
|
19
|
+
t: string;
|
|
20
|
+
}, Cmd extends {
|
|
21
|
+
t: string;
|
|
22
|
+
}> extends ShellDeps {
|
|
23
|
+
host: MatchHostFactory<Line, Cmd>;
|
|
24
|
+
/**
|
|
25
|
+
* `GameAdapter.restoreSpec`, generically: a match restored from a checkpoint
|
|
26
|
+
* (`restore.checkpoint`, below) opens on it rather than fresh. Absent: a restore with a
|
|
27
|
+
* checkpoint keeps the spec it was given. Forge's own is `match/registry.ts`'s `restoredSpec`,
|
|
28
|
+
* wired in once by `createMatchRegistry` (never caller-settable — `RegistryDeps` omits this
|
|
29
|
+
* field). Forge's checkpoint IS its `TurnSnapshot`, the same value `latestSnapshot`/
|
|
30
|
+
* `MatchRecord.snapshot` already carry, so `match/registry.ts`'s `create`/`restore` pass it
|
|
31
|
+
* through as `restore.checkpoint` and let this constructor transform the spec, rather than
|
|
32
|
+
* calling `restoredSpec` themselves before `new Match(...)` — one path, not two.
|
|
33
|
+
*/
|
|
34
|
+
restoreSpec?(spec: MatchSpec, cp: unknown): MatchSpec;
|
|
35
|
+
}
|
|
36
|
+
export declare abstract class HostedMatch<Line extends {
|
|
37
|
+
t: string;
|
|
38
|
+
}, Cmd extends {
|
|
39
|
+
t: string;
|
|
40
|
+
}> extends MatchShell<Line, Cmd> {
|
|
41
|
+
protected readonly deps: HostedMatchDeps<Line, Cmd>;
|
|
42
|
+
/**
|
|
43
|
+
* `spec` is transformed through {@link HostedMatchDeps.restoreSpec} right here, before
|
|
44
|
+
* `MatchShell`'s own constructor ever sees it, when this match is being restored from a
|
|
45
|
+
* checkpoint. `Match`'s own restore carries one too now — `match/registry.ts`'s `create`/
|
|
46
|
+
* `restore` pass its `TurnSnapshot` through as `restore.checkpoint`, and `createMatchRegistry`
|
|
47
|
+
* wires `restoredSpec` in as `deps.restoreSpec` — so Forge resumes through the exact same hook
|
|
48
|
+
* the toy game does. A subclass with no checkpoint, or no `restoreSpec` of its own, passes
|
|
49
|
+
* `spec` through unchanged, exactly as before this constructor existed.
|
|
50
|
+
*/
|
|
51
|
+
constructor(id: string, spec: MatchSpec, deps: HostedMatchDeps<Line, Cmd>, restore?: {
|
|
52
|
+
epoch: string | null;
|
|
53
|
+
startedAt: number;
|
|
54
|
+
snapshot?: TurnSnapshot | null;
|
|
55
|
+
checkpoint?: unknown;
|
|
56
|
+
clockMs?: [number, number];
|
|
57
|
+
});
|
|
58
|
+
/**
|
|
59
|
+
* The newest `{ t: 'checkpoint' }` line any `onLine` override classified, kept exactly like
|
|
60
|
+
* Forge's own `latestSnapshot` (parking and restore both go through it, via
|
|
61
|
+
* {@link MatchShell.remember} and this constructor's own `restoreSpec` call above). A game
|
|
62
|
+
* whose engine produces one calls this from its own `onLine`'s `'checkpoint'` case —
|
|
63
|
+
* `fixtures/toy-game/match.ts`'s `ToyMatch` first, then `play/match.ts`'s `Match` on Forge's
|
|
64
|
+
* own `'snapshot'` line.
|
|
65
|
+
*/
|
|
66
|
+
protected noteCheckpoint(cp: unknown): void;
|
|
67
|
+
/**
|
|
68
|
+
* Start the host. Separate from the constructor so nothing can emit before the match is
|
|
69
|
+
* registered. A host that throws fails the match here, so a start never leaves one
|
|
70
|
+
* `starting` for good and never escapes the route as an exception.
|
|
71
|
+
*/
|
|
72
|
+
start(): void;
|
|
73
|
+
/**
|
|
74
|
+
* Take over a host that is already playing this match, left running by a server that has
|
|
75
|
+
* exited (Wave 22 §E). `attach` replays that server's whole line stream into `onLine` before
|
|
76
|
+
* it returns, so by the time this call is done every seat holds the history, cursor and open
|
|
77
|
+
* asks it held — same epoch, same owners — and a client resyncs rather than starting over.
|
|
78
|
+
*
|
|
79
|
+
* Separate from `start` for the same reason `start` is separate from the constructor: nothing
|
|
80
|
+
* may emit before the match is in the registry.
|
|
81
|
+
*/
|
|
82
|
+
resume(attach: (events: HostEvents<Line, Cmd>) => MatchHost<Cmd>): void;
|
|
83
|
+
protected hostEvents(): StartEvents<Line, Cmd>;
|
|
84
|
+
/** Stop on purpose. The host's exit that follows is then not a failure. */
|
|
85
|
+
stop(): void;
|
|
86
|
+
/**
|
|
87
|
+
* `frames`: where the engine threw (Forge's bridge `fatal` line) — the log row names the
|
|
88
|
+
* iteration a bare message cannot.
|
|
89
|
+
*/
|
|
90
|
+
fail(reason: string, frames?: string[]): void;
|
|
91
|
+
private onExit;
|
|
92
|
+
}
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `HostedMatch`: the shell lifecycle ({@link MatchShell}) plus the host lifecycle every engine
|
|
3
|
+
* needs the same way — start, resume-after-a-restart, the replay gag's `replayed` hook, and the
|
|
4
|
+
* sweep at stop/fail/exit (`GameSession.ended`). Nothing here is Forge-specific:
|
|
5
|
+
* `play/match.ts`'s `Match` is `HostedMatch<BridgeLine, BridgeCommand>` with a `ForgeSession`;
|
|
6
|
+
* `fixtures/toy-game/match.ts`'s `ToyMatch` is `HostedMatch<ToyLine, ToyCmd>` with the toy's;
|
|
7
|
+
* `runtimes/relay-match.ts`'s `RelayMatch` is `HostedMatch<RelayLine, RelayCommand>` with a
|
|
8
|
+
* `RelaySession`. What stays abstract here (`seats`, `onLine`, `concedeCommand`, `forceConcede`)
|
|
9
|
+
* is exactly what only the game itself can answer.
|
|
10
|
+
*
|
|
11
|
+
* Moved out of `play/match.ts` (a pure move — no behaviour changed, every importer
|
|
12
|
+
* rewritten, no shim): `match.ts` keeps `Match`, Forge's own `HostedMatch`.
|
|
13
|
+
*/
|
|
14
|
+
import { MatchShell } from './shell.js';
|
|
15
|
+
export class HostedMatch extends MatchShell {
|
|
16
|
+
/**
|
|
17
|
+
* `spec` is transformed through {@link HostedMatchDeps.restoreSpec} right here, before
|
|
18
|
+
* `MatchShell`'s own constructor ever sees it, when this match is being restored from a
|
|
19
|
+
* checkpoint. `Match`'s own restore carries one too now — `match/registry.ts`'s `create`/
|
|
20
|
+
* `restore` pass its `TurnSnapshot` through as `restore.checkpoint`, and `createMatchRegistry`
|
|
21
|
+
* wires `restoredSpec` in as `deps.restoreSpec` — so Forge resumes through the exact same hook
|
|
22
|
+
* the toy game does. A subclass with no checkpoint, or no `restoreSpec` of its own, passes
|
|
23
|
+
* `spec` through unchanged, exactly as before this constructor existed.
|
|
24
|
+
*/
|
|
25
|
+
constructor(id, spec, deps, restore) {
|
|
26
|
+
super(id, restore?.checkpoint !== undefined && deps.restoreSpec !== undefined ? deps.restoreSpec(spec, restore.checkpoint) : spec, deps, restore);
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* The newest `{ t: 'checkpoint' }` line any `onLine` override classified, kept exactly like
|
|
30
|
+
* Forge's own `latestSnapshot` (parking and restore both go through it, via
|
|
31
|
+
* {@link MatchShell.remember} and this constructor's own `restoreSpec` call above). A game
|
|
32
|
+
* whose engine produces one calls this from its own `onLine`'s `'checkpoint'` case —
|
|
33
|
+
* `fixtures/toy-game/match.ts`'s `ToyMatch` first, then `play/match.ts`'s `Match` on Forge's
|
|
34
|
+
* own `'snapshot'` line.
|
|
35
|
+
*/
|
|
36
|
+
noteCheckpoint(cp) {
|
|
37
|
+
this.latestCheckpoint = cp;
|
|
38
|
+
this.remember();
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Start the host. Separate from the constructor so nothing can emit before the match is
|
|
42
|
+
* registered. A host that throws fails the match here, so a start never leaves one
|
|
43
|
+
* `starting` for good and never escapes the route as an exception.
|
|
44
|
+
*/
|
|
45
|
+
start() {
|
|
46
|
+
if (this.host !== null)
|
|
47
|
+
return;
|
|
48
|
+
try {
|
|
49
|
+
this.host = this.deps.host(this.id, this.spec, this.hostEvents());
|
|
50
|
+
}
|
|
51
|
+
catch (err) {
|
|
52
|
+
this.refuseStart(err);
|
|
53
|
+
return;
|
|
54
|
+
}
|
|
55
|
+
this.remember();
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Take over a host that is already playing this match, left running by a server that has
|
|
59
|
+
* exited (Wave 22 §E). `attach` replays that server's whole line stream into `onLine` before
|
|
60
|
+
* it returns, so by the time this call is done every seat holds the history, cursor and open
|
|
61
|
+
* asks it held — same epoch, same owners — and a client resyncs rather than starting over.
|
|
62
|
+
*
|
|
63
|
+
* Separate from `start` for the same reason `start` is separate from the constructor: nothing
|
|
64
|
+
* may emit before the match is in the registry.
|
|
65
|
+
*/
|
|
66
|
+
resume(attach) {
|
|
67
|
+
if (this.host !== null)
|
|
68
|
+
return;
|
|
69
|
+
this.replaying = true;
|
|
70
|
+
try {
|
|
71
|
+
this.host = attach(this.hostEvents());
|
|
72
|
+
}
|
|
73
|
+
finally {
|
|
74
|
+
this.replaying = false;
|
|
75
|
+
}
|
|
76
|
+
this.syncClock();
|
|
77
|
+
this.remember();
|
|
78
|
+
this.deps.log({
|
|
79
|
+
evt: 'match-resumed',
|
|
80
|
+
matchId: this.id,
|
|
81
|
+
status: this.status,
|
|
82
|
+
epoch: this.epoch,
|
|
83
|
+
seats: this.seats.map((s) => ({ seat: s.seat, playerId: s.playerId, asks: this.game.openAsks(s.seat) })),
|
|
84
|
+
});
|
|
85
|
+
this.armRejoinGrace();
|
|
86
|
+
}
|
|
87
|
+
hostEvents() {
|
|
88
|
+
return {
|
|
89
|
+
line: (line) => this.onLine(line),
|
|
90
|
+
exit: (reason) => this.onExit(reason),
|
|
91
|
+
log: (entry) => this.deps.log(entry),
|
|
92
|
+
replayed: (command) => this.game.replayed(command),
|
|
93
|
+
queued: (place) => {
|
|
94
|
+
this.queuePlace = place;
|
|
95
|
+
},
|
|
96
|
+
booting: () => {
|
|
97
|
+
this.queuePlace = null;
|
|
98
|
+
for (const arm of this.bootWaiters.splice(0))
|
|
99
|
+
arm();
|
|
100
|
+
},
|
|
101
|
+
unstartable: (err) => this.refuseStart(err),
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
/** Stop on purpose. The host's exit that follows is then not a failure. */
|
|
105
|
+
stop() {
|
|
106
|
+
if (this.status !== 'starting' && this.status !== 'running' && this.status !== 'over')
|
|
107
|
+
return;
|
|
108
|
+
this.status = 'stopped';
|
|
109
|
+
this.stopClock();
|
|
110
|
+
this.closeTakeBack();
|
|
111
|
+
this.game.ended(null);
|
|
112
|
+
for (const done of this.runningWaiters.splice(0))
|
|
113
|
+
done({ ok: false, error: 'stopped' });
|
|
114
|
+
this.host?.stop();
|
|
115
|
+
this.tellEnded();
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* `frames`: where the engine threw (Forge's bridge `fatal` line) — the log row names the
|
|
119
|
+
* iteration a bare message cannot.
|
|
120
|
+
*/
|
|
121
|
+
fail(reason, frames) {
|
|
122
|
+
if (this.status === 'failed' || this.status === 'stopped')
|
|
123
|
+
return;
|
|
124
|
+
this.status = 'failed';
|
|
125
|
+
this.failure = reason;
|
|
126
|
+
this.stopClock();
|
|
127
|
+
this.deps.log({ evt: 'match-failed', matchId: this.id, reason, ...(frames === undefined ? {} : { frames }) });
|
|
128
|
+
this.game.ended(reason);
|
|
129
|
+
for (const done of this.runningWaiters.splice(0))
|
|
130
|
+
done({ ok: false, error: reason });
|
|
131
|
+
this.host?.stop();
|
|
132
|
+
this.tellEnded();
|
|
133
|
+
}
|
|
134
|
+
onExit(reason) {
|
|
135
|
+
if (this.overTimer !== null)
|
|
136
|
+
clearTimeout(this.overTimer);
|
|
137
|
+
this.stopClock();
|
|
138
|
+
const dying = this.status === 'starting' || this.status === 'running';
|
|
139
|
+
// A game that already ended naturally (`status === 'over'`) is not told "cannot continue" —
|
|
140
|
+
// its seats already have their result; `ended(null)` still sweeps asks/probes/frames.
|
|
141
|
+
this.game.ended(dying ? reason : null);
|
|
142
|
+
if (dying) {
|
|
143
|
+
this.fail(reason);
|
|
144
|
+
return;
|
|
145
|
+
}
|
|
146
|
+
if (this.status !== 'over')
|
|
147
|
+
return;
|
|
148
|
+
this.status = 'stopped';
|
|
149
|
+
this.tellEnded();
|
|
150
|
+
}
|
|
151
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
export type MatchStatus = 'starting' | 'running' | 'over' | 'failed' | 'stopped';
|
|
2
|
+
/** What {@link gameOutcome} reads off a match. */
|
|
3
|
+
export interface OutcomeFacts {
|
|
4
|
+
endedAt: number | null;
|
|
5
|
+
winner: string | null;
|
|
6
|
+
winnerSeat: 0 | 1 | null;
|
|
7
|
+
concededBy: number | null;
|
|
8
|
+
/** The seat whose chess clock ran out; its concede is the server's ({@link Match.timedOut}). */
|
|
9
|
+
timedOut?: number | null;
|
|
10
|
+
spec: {
|
|
11
|
+
seats: readonly {
|
|
12
|
+
name: string;
|
|
13
|
+
}[];
|
|
14
|
+
};
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Which of two seats won, from Forge's `losers` (player ids): a seat whose
|
|
18
|
+
* player id is among them lost, so the other won; with only one seat's id
|
|
19
|
+
* known (an AI game — the AI never opens a view), that seat won exactly when
|
|
20
|
+
* somebody lost and it was not that seat. Null for anything else: no losers,
|
|
21
|
+
* both or neither known seat lost, or more than two seats.
|
|
22
|
+
*/
|
|
23
|
+
export declare function winnerSeatFromLosers(seats: readonly {
|
|
24
|
+
seat: number;
|
|
25
|
+
playerId: number | null;
|
|
26
|
+
}[], losers: readonly number[] | undefined): 0 | 1 | null;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which of two seats won, from Forge's `losers` (player ids): a seat whose
|
|
3
|
+
* player id is among them lost, so the other won; with only one seat's id
|
|
4
|
+
* known (an AI game — the AI never opens a view), that seat won exactly when
|
|
5
|
+
* somebody lost and it was not that seat. Null for anything else: no losers,
|
|
6
|
+
* both or neither known seat lost, or more than two seats.
|
|
7
|
+
*/
|
|
8
|
+
export function winnerSeatFromLosers(seats, losers) {
|
|
9
|
+
if (losers === undefined || losers.length === 0 || seats.length !== 2)
|
|
10
|
+
return null;
|
|
11
|
+
const known = seats.filter((s) => s.playerId !== null);
|
|
12
|
+
const lost = known.filter((s) => losers.includes(s.playerId));
|
|
13
|
+
const other = (seat) => (seat === 0 ? 1 : seat === 1 ? 0 : null);
|
|
14
|
+
if (known.length === 2)
|
|
15
|
+
return lost.length === 1 ? other(lost[0].seat) : null;
|
|
16
|
+
if (known.length === 1) {
|
|
17
|
+
const only = known[0].seat;
|
|
18
|
+
return lost.length === 1 ? other(only) : only === 0 || only === 1 ? only : null;
|
|
19
|
+
}
|
|
20
|
+
return null;
|
|
21
|
+
}
|
|
@@ -0,0 +1,378 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The platform half of a match (`play/match.ts`'s `Match` is this plus its game's {@link GameSession}):
|
|
3
|
+
* its lifecycle and its seats' holders, never what the game in it is. Who holds which seat and whether
|
|
4
|
+
* they are here, the grace a match nobody comes back to gets, the chess clock, the concede that
|
|
5
|
+
* always ends a game, the start queue's waiters, the record a restart re-attaches from, and the
|
|
6
|
+
* take-back ask between the two seats (restart the turn, or undo the last action). Every fact about the game itself — is a seat's own decision
|
|
7
|
+
* open, whose turn it is, what a seat's asks are — is asked of {@link MatchShell.game}.
|
|
8
|
+
*
|
|
9
|
+
* Nothing here imports Magic: a game that is not Forge runs under the same shell.
|
|
10
|
+
*/
|
|
11
|
+
import { type ParticipantId } from '@wolffm/rooms-protocol';
|
|
12
|
+
import { ChessClock } from '../clock.js';
|
|
13
|
+
import type { GameSession } from '../game-adapter.js';
|
|
14
|
+
import type { MatchHost, MatchSpec, TurnSnapshot } from '../host.js';
|
|
15
|
+
import type { MatchStatus } from './outcome.js';
|
|
16
|
+
export type ClaimOutcome = {
|
|
17
|
+
ok: true;
|
|
18
|
+
seat: number;
|
|
19
|
+
fresh: boolean;
|
|
20
|
+
} | {
|
|
21
|
+
ok: false;
|
|
22
|
+
error: string;
|
|
23
|
+
};
|
|
24
|
+
export type ClientOutcome = {
|
|
25
|
+
ok: true;
|
|
26
|
+
} | {
|
|
27
|
+
ok: false;
|
|
28
|
+
error: string;
|
|
29
|
+
};
|
|
30
|
+
/** How far back {@link MatchShell.activity} counts the seconds in which the table changed. */
|
|
31
|
+
export declare const ACTIVITY_WINDOW_MS = 120000;
|
|
32
|
+
/** How long a take-back ask (restart or undo) waits for the other seat before it counts as declined. */
|
|
33
|
+
export declare const RESTART_ASK_MS = 30000;
|
|
34
|
+
/**
|
|
35
|
+
* How long Forge gets to end the game after a seat concedes before the concede is sent again, and
|
|
36
|
+
* again before the server ends the game itself. Forge ends a conceded game within the act's own
|
|
37
|
+
* turn at the gate (`ActGate`, at most 5 s); the monkey's matches met concedes Forge received, logged
|
|
38
|
+
* no error for, and never ended, each holding its place under the ceiling for good.
|
|
39
|
+
*/
|
|
40
|
+
export declare const CONCEDE_ANSWER_MS = 10000;
|
|
41
|
+
/** A seat's restart act: `@hadoku/shared`'s `RESTART_ACTS`, the four the wire carries. */
|
|
42
|
+
export type RestartAct = 'ask' | 'allow' | 'decline' | 'cancel';
|
|
43
|
+
/** What a take-back ask takes back: the turn from its start, or the asker's last action (`docs/planning/undo-plan.md`). */
|
|
44
|
+
export type TakeBackKind = 'restart' | 'undo';
|
|
45
|
+
/** One take-back asked for: its kind, the asking seat, the turn it was asked in, and for an undo the history it rewinds. */
|
|
46
|
+
interface TakeBack {
|
|
47
|
+
kind: TakeBackKind;
|
|
48
|
+
from: number;
|
|
49
|
+
turn: number;
|
|
50
|
+
version: number;
|
|
51
|
+
}
|
|
52
|
+
/** Where a take-back stands: `@hadoku/shared`'s `RestartState`, the payload the wire carries. */
|
|
53
|
+
export interface RestartState {
|
|
54
|
+
matchId: string;
|
|
55
|
+
turn: number;
|
|
56
|
+
ask: {
|
|
57
|
+
from: number;
|
|
58
|
+
kind: TakeBackKind;
|
|
59
|
+
} | null;
|
|
60
|
+
declined: boolean;
|
|
61
|
+
restorable: boolean;
|
|
62
|
+
/** The seats that may ask to undo now: their game says so ({@link GameSession.takeBack}), and no undo of theirs was declined since. */
|
|
63
|
+
undoable: number[];
|
|
64
|
+
}
|
|
65
|
+
/** What the shell keeps of a seat: who holds it and whether they are here. The game's own seat state extends it. */
|
|
66
|
+
export interface ShellSeat {
|
|
67
|
+
seat: number;
|
|
68
|
+
ai: boolean;
|
|
69
|
+
/** Bound on first claim, never changed. */
|
|
70
|
+
owner: ParticipantId | null;
|
|
71
|
+
/** From this seat's `openView`. Null until Forge has opened the game. */
|
|
72
|
+
playerId: number | null;
|
|
73
|
+
/** Armed when the seat's last connection went; aborts its asks when it fires. */
|
|
74
|
+
departure: NodeJS.Timeout | null;
|
|
75
|
+
/** A person is on this seat: connected, or gone for less than the grace. Never true for an AI seat. */
|
|
76
|
+
here: boolean;
|
|
77
|
+
/**
|
|
78
|
+
* The person on this seat LEFT: they were here, and have been gone past the
|
|
79
|
+
* grace. Told to the other seat (`SeatIdentity.away`) so it is not left
|
|
80
|
+
* reading "is choosing…" for a player who closed the tab (the rejoin audit,
|
|
81
|
+
* 2026-10-19). A seat nobody has joined yet is not away — it is starting.
|
|
82
|
+
*/
|
|
83
|
+
away: boolean;
|
|
84
|
+
}
|
|
85
|
+
/** What the shell is handed: the log, and the graces and hooks of a seat's presence, a restart and an ending. */
|
|
86
|
+
export interface ShellDeps {
|
|
87
|
+
log(entry: Record<string, unknown>): void;
|
|
88
|
+
/**
|
|
89
|
+
* How long a match with no seat here waits for one to come back before it stops
|
|
90
|
+
* ({@link Match.armRejoinGrace}). Absent or 0: never — a suite that drives a match without
|
|
91
|
+
* sockets has no seat to be here. `attachPlay` passes 5 minutes (`socket.ts`'s
|
|
92
|
+
* `DEFAULT_REJOIN_GRACE_MS`).
|
|
93
|
+
*/
|
|
94
|
+
rejoinGraceMs?: number;
|
|
95
|
+
/**
|
|
96
|
+
* Whether a seat's holder is still connected to this server — watching another match, or on the
|
|
97
|
+
* room's own screens, whose feed is a socket too (the operator,
|
|
98
|
+
* 2026-10-23: *"even people who are seated and have an active game to play should be able to
|
|
99
|
+
* spectate other people and their games"*). A holder watching another table is still in the room's
|
|
100
|
+
* games, so the rejoin grace waits for them rather than stopping their own. Absent: nobody is.
|
|
101
|
+
*/
|
|
102
|
+
ownerOnline?(owner: ParticipantId): boolean;
|
|
103
|
+
/**
|
|
104
|
+
* How long a seat with no connection still counts as at the table
|
|
105
|
+
* ({@link Match.anyoneHere}). 0 (the default) is gone at once; `attachPlay`
|
|
106
|
+
* passes 30 s so a refresh is not a departure. Its asks stay open either way.
|
|
107
|
+
*/
|
|
108
|
+
disconnectGraceMs?: number;
|
|
109
|
+
/** Where a restart stands ({@link Match.restartState}) changed: the socket layer tells every socket of the match. */
|
|
110
|
+
restartChanged?(state: RestartState): void;
|
|
111
|
+
/**
|
|
112
|
+
* A restart of the current turn was allowed ({@link Match.restartAct}): start this match again from
|
|
113
|
+
* its latest turn-start snapshot. The registry's {@link MatchRegistry.restore} of this match. Absent
|
|
114
|
+
* (a unit suite with no registry): no restart can be made.
|
|
115
|
+
*/
|
|
116
|
+
restartTurn?(): void;
|
|
117
|
+
/**
|
|
118
|
+
* Nobody came back ({@link Match.armRejoinGrace}): the match is about to be stopped with its game
|
|
119
|
+
* unfinished. Told before the stop, while the match still holds what a later resume needs — its
|
|
120
|
+
* latest turn-start snapshot, its seats' owners, its clock.
|
|
121
|
+
*/
|
|
122
|
+
abandoned?(): void;
|
|
123
|
+
/** The match let go of its JVM for good, stopped or failed, and says nothing more. Told once. */
|
|
124
|
+
ended?(): void;
|
|
125
|
+
now?: () => number;
|
|
126
|
+
}
|
|
127
|
+
export declare abstract class MatchShell<Line extends {
|
|
128
|
+
t: string;
|
|
129
|
+
}, Cmd extends {
|
|
130
|
+
t: string;
|
|
131
|
+
}> {
|
|
132
|
+
readonly id: string;
|
|
133
|
+
/** Minted per match-process start: a restart is a new epoch. */
|
|
134
|
+
readonly epoch: string;
|
|
135
|
+
status: MatchStatus;
|
|
136
|
+
failure: string | null;
|
|
137
|
+
/** The seat whose concede Forge was sent, or null — the one end reason the board cannot show. */
|
|
138
|
+
concededBy: number | null;
|
|
139
|
+
/** The seat whose chess clock ran out, or null. The server conceded the game for it ({@link flag}). */
|
|
140
|
+
timedOut: number | null;
|
|
141
|
+
/**
|
|
142
|
+
* The chess clock (`clock.ts`), or null in a game without one (`MatchSpec.clockMs`). A seat's
|
|
143
|
+
* runs exactly while {@link waitingOnFor} names it — the same fact the other seat's banner
|
|
144
|
+
* reads — so a window the server answers for it never reaches it live and never costs it time.
|
|
145
|
+
* A disconnected seat's keeps running: being away answers nothing.
|
|
146
|
+
*/
|
|
147
|
+
readonly clock: ChessClock | null;
|
|
148
|
+
/** Fires when the running seat with the least time left runs out ({@link syncClock}). */
|
|
149
|
+
protected flagTimer: NodeJS.Timeout | null;
|
|
150
|
+
/**
|
|
151
|
+
* When the match was started, in ms. A match taken back after a restart
|
|
152
|
+
* keeps the start its JVM's record has (`MatchRecord.startedAt`), so this is
|
|
153
|
+
* the same instant whichever process ends it.
|
|
154
|
+
*/
|
|
155
|
+
readonly startedAt: number;
|
|
156
|
+
readonly spec: MatchSpec;
|
|
157
|
+
host: MatchHost<Cmd> | null;
|
|
158
|
+
protected readonly now: () => number;
|
|
159
|
+
readonly runningWaiters: ((outcome: ClientOutcome) => void)[];
|
|
160
|
+
/** `whenRunning` timeouts not yet started, because the match is waiting for a boot slot. */
|
|
161
|
+
protected readonly bootWaiters: (() => void)[];
|
|
162
|
+
/**
|
|
163
|
+
* This match's place among the starts waiting for a boot slot (`start-queue.ts`), 1-based, or
|
|
164
|
+
* null once its JVM is booting — and for a match that never waited.
|
|
165
|
+
*/
|
|
166
|
+
queuePlace: number | null;
|
|
167
|
+
protected overTimer: NodeJS.Timeout | null;
|
|
168
|
+
/** Waiting on Forge to end a conceded game: {@link watchConcede}. */
|
|
169
|
+
protected concedeWatch: NodeJS.Timeout | null;
|
|
170
|
+
/**
|
|
171
|
+
* True while `resume` is feeding an earlier server's lines back in. Nothing
|
|
172
|
+
* may go OUT during that: every command in the stream was already sent by the
|
|
173
|
+
* server that read it, and sending it twice would act twice in Forge.
|
|
174
|
+
*/
|
|
175
|
+
replaying: boolean;
|
|
176
|
+
/** Armed while no seat is here ({@link Match.armRejoinGrace}): a match nobody comes back to is stopped. */
|
|
177
|
+
protected rejoinTimer: NodeJS.Timeout | null;
|
|
178
|
+
/** Whether {@link MatchDeps.ended} was told. */
|
|
179
|
+
protected endedTold: boolean;
|
|
180
|
+
/**
|
|
181
|
+
* The game at the start of its latest turn, from the bridge's `snapshot` line: what
|
|
182
|
+
* {@link MatchRegistry.restore} starts this match again from. Kept here and in the match's
|
|
183
|
+
* record on disk (`remember`), never only on the JVM's host.
|
|
184
|
+
*/
|
|
185
|
+
latestSnapshot: TurnSnapshot | null;
|
|
186
|
+
/**
|
|
187
|
+
* The newest `{ t: 'checkpoint' }` line `GameAdapter.classify` read, opaque to the shell —
|
|
188
|
+
* The generic twin of {@link latestSnapshot}, which stays Forge's own. Set by the composing
|
|
189
|
+
* match whenever its own `onLine` sees one (`fixtures/toy-game/match.ts`'s `ToyMatch` is the
|
|
190
|
+
* first caller; a generic `HostedMatch` reading `classify` directly is a later step), and
|
|
191
|
+
* written down with the record exactly like {@link latestSnapshot} ({@link remember}). A spec
|
|
192
|
+
* restored through `GameAdapter.restoreSpec` is what actually resumes the game from it; this
|
|
193
|
+
* field is only the shell's bookkeeping of what the last one was.
|
|
194
|
+
*/
|
|
195
|
+
latestCheckpoint: unknown | null;
|
|
196
|
+
/**
|
|
197
|
+
* The open take-back ask: what it takes back, the asking seat, the turn it is about, for an undo the history it
|
|
198
|
+
* would rewind ({@link GameSession.takeBack}'s `version`), and its {@link RESTART_ASK_MS} expiry. One at a time.
|
|
199
|
+
*/
|
|
200
|
+
protected takeBackAsk: (TakeBack & {
|
|
201
|
+
timer: ReturnType<typeof setTimeout>;
|
|
202
|
+
}) | null;
|
|
203
|
+
/** The turn a restart ask was declined in: no second ask until the next. */
|
|
204
|
+
protected restartDeclined: number | null;
|
|
205
|
+
/** Each seat's history an undo was declined at: no second ask until it moves. */
|
|
206
|
+
protected undoDeclined: Map<number, number>;
|
|
207
|
+
/** What {@link Match.restartState} last told, so a turn or snapshot that changes nothing tells no one. */
|
|
208
|
+
protected restartKey: string;
|
|
209
|
+
/**
|
|
210
|
+
* Why this server could not give the match a Forge at all (the host threw: a full
|
|
211
|
+
* disk, a JVM that could not be spawned), or null. The match is `failed` with it;
|
|
212
|
+
* `POST /play/matches` answers it as 503, since it says nothing about the match.
|
|
213
|
+
*/
|
|
214
|
+
unstartable: string | null;
|
|
215
|
+
/**
|
|
216
|
+
* A match with no seat here is a JVM nobody is using: the seats have
|
|
217
|
+
* {@link MatchDeps.rejoinGraceMs} to come back before it is stopped for good. Armed when the
|
|
218
|
+
* match goes running or is taken back (its seats can join from then on, not while Forge boots)
|
|
219
|
+
* and when the last seat's departure grace runs out; {@link Match.seatConnected} disarms it. Before this covered every match, only a
|
|
220
|
+
* re-attached one had it, and a match both players had left held one of the server's two slots
|
|
221
|
+
* for ~2 h (2026-10-11: `seat-departing` for both seats, then nothing, then a refused rematch).
|
|
222
|
+
*/
|
|
223
|
+
armRejoinGrace(): void;
|
|
224
|
+
/** The host could not give this match a JVM, now or from the start queue: see {@link unstartable}. */
|
|
225
|
+
protected refuseStart(err: Error): void;
|
|
226
|
+
/** seat → owner, for the on-disk record a re-attach reads and for a restore. */
|
|
227
|
+
owners(): (string | null)[];
|
|
228
|
+
/** What a re-attach or a restore of this match needs that only the match knows, onto its record on disk. */
|
|
229
|
+
/**
|
|
230
|
+
* Also the chess clock's time left: written at the start, at each turn's snapshot and when the
|
|
231
|
+
* server hands the match over, so a crash between two of those gives a seat back at most a turn.
|
|
232
|
+
*/
|
|
233
|
+
protected remember(): void;
|
|
234
|
+
/** Each seat's chess-clock time left, or null in a game without one. */
|
|
235
|
+
clockLeft(): [number, number] | null;
|
|
236
|
+
/**
|
|
237
|
+
* Run each seat's clock exactly while the game waits on it, and re-tell the roster when that
|
|
238
|
+
* changed — the clock rides on `forge:seats` ({@link seatIdentities}), so both screens and every
|
|
239
|
+
* watcher draw the same reading. Called wherever {@link waitingOnFor}'s inputs move: every
|
|
240
|
+
* {@link checkWaitingOn}, and every bar {@link send} puts on the wire.
|
|
241
|
+
*/
|
|
242
|
+
syncClock(): void;
|
|
243
|
+
/**
|
|
244
|
+
* Time the next flag: a timer for the running seat with the least time left. When it fires with time
|
|
245
|
+
* still on that seat's clock, it is armed again for what is left. Node fires a timer by the event
|
|
246
|
+
* loop's own clock, cut to the millisecond, and `now` reads the wall clock, so a timer armed for the
|
|
247
|
+
* 20 000 ms left can fire when the wall clock has moved 19 999: that seat then has 1 ms left, nothing
|
|
248
|
+
* about who runs has changed, and without the re-arm the seat sat at 0:00 and never lost.
|
|
249
|
+
*/
|
|
250
|
+
private armFlag;
|
|
251
|
+
/** Nobody's time runs any more: the match is letting go of its game. */
|
|
252
|
+
protected stopClock(): void;
|
|
253
|
+
/**
|
|
254
|
+
* A seat's chess clock reached zero: it loses (the operator, 2026-10-30: *"at zero, that player
|
|
255
|
+
* loses the match"*). The server concedes the game for it, exactly as its own Concede would, and
|
|
256
|
+
* {@link gameOutcome} marks the win `timedOut`, which the room logs; the game is lost like any other.
|
|
257
|
+
*/
|
|
258
|
+
protected flag(seat: number): void;
|
|
259
|
+
/**
|
|
260
|
+
* A concede always ends the game. If Forge has not ended it {@link CONCEDE_ANSWER_MS} after the
|
|
261
|
+
* concede, it is sent once more (Forge's concede is idempotent: an out player conceding again only
|
|
262
|
+
* re-runs the game-over check); if the game is still running after that, the server ends it as
|
|
263
|
+
* Forge would have, the conceding seat the loser, and Forge's game is stopped with the match.
|
|
264
|
+
*/
|
|
265
|
+
watchConcede(seat: number, resent?: boolean): void;
|
|
266
|
+
/** The seat this participant holds, or null. */
|
|
267
|
+
seatOf(participantId: ParticipantId): number | null;
|
|
268
|
+
/**
|
|
269
|
+
* Bind a participant to a seat, or find the one they already hold.
|
|
270
|
+
* Idempotent, permanent, and refused to anyone who could not come back.
|
|
271
|
+
*/
|
|
272
|
+
claim(participantId: ParticipantId): ClaimOutcome;
|
|
273
|
+
/**
|
|
274
|
+
* Resolves when every human seat knows its Forge player, or the match has failed. `timeoutMs`
|
|
275
|
+
* counts from when its JVM began booting: a start waiting its turn (`start-queue.ts`) is not
|
|
276
|
+
* Forge failing to start.
|
|
277
|
+
*/
|
|
278
|
+
whenRunning(timeoutMs: number): Promise<ClientOutcome>;
|
|
279
|
+
/**
|
|
280
|
+
* The seat's last connection is gone. It stops counting as at the table once
|
|
281
|
+
* it has stayed gone for `disconnectGraceMs` — at once when that is 0. Its
|
|
282
|
+
* asks stay open: they are re-sent when it comes back.
|
|
283
|
+
*/
|
|
284
|
+
seatDisconnected(seat: number): void;
|
|
285
|
+
/**
|
|
286
|
+
* Somebody is at the table: a seat connected now, or gone for less than the grace.
|
|
287
|
+
* A running match nobody is at is not worth holding a deploy for — the deploy hands
|
|
288
|
+
* it over, and nobody's game is interrupted (`busy.ts`).
|
|
289
|
+
*/
|
|
290
|
+
anyoneHere(): boolean;
|
|
291
|
+
/** A connection for this seat is back: whatever `seatDisconnected` armed is off. */
|
|
292
|
+
seatConnected(seat: number): void;
|
|
293
|
+
/**
|
|
294
|
+
* This process is stopping and this match is NOT: let go of the JVM without
|
|
295
|
+
* killing it, so the next process can take it back. False when the match
|
|
296
|
+
* cannot outlive us — the caller then owes its seats `serverStopping`.
|
|
297
|
+
*
|
|
298
|
+
* A FINISHED match (`over`, inside its `overGraceMs`) is handed over too: its
|
|
299
|
+
* players are on its result screen, and the board and the ending they are
|
|
300
|
+
* looking at are this match's to answer after a deploy exactly as a running
|
|
301
|
+
* game's are (the operator, 2026-10-17, prod m-e055472e0d6e: a deploy turned
|
|
302
|
+
* a result screen into "no longer running"). The next process's replay ends
|
|
303
|
+
* on the same `gameover`, which re-arms the grace from there.
|
|
304
|
+
*
|
|
305
|
+
* **Nothing is emitted here, on purpose.** A frame sent now would take a `seq`
|
|
306
|
+
* that the next server's replay cannot reproduce, and the seat's cursor would
|
|
307
|
+
* be one ahead of a stream that then reuses the number. The seats learn what
|
|
308
|
+
* happened from the reconnect, which is what the client is already built for.
|
|
309
|
+
*/
|
|
310
|
+
handOver(): boolean;
|
|
311
|
+
protected tellEnded(): void;
|
|
312
|
+
/**
|
|
313
|
+
* The whole seconds in which the table changed, oldest first, for the last {@link ACTIVITY_WINDOW_MS}.
|
|
314
|
+
* Stamped on every watcher-channel state frame, so one act's burst of frames is one second, and a
|
|
315
|
+
* game waiting on a player stamps nothing. `featured.ts` reads it through {@link activity}.
|
|
316
|
+
*/
|
|
317
|
+
protected activeSeconds: number[];
|
|
318
|
+
/** When the table last changed, and in how many of the last {@link ACTIVITY_WINDOW_MS}'s seconds. */
|
|
319
|
+
activity(now?: number): {
|
|
320
|
+
lastAt: number | null;
|
|
321
|
+
recent: number;
|
|
322
|
+
};
|
|
323
|
+
noteActivity(): void;
|
|
324
|
+
/** Where a take-back stands, the same for every socket of the match. */
|
|
325
|
+
restartState(): RestartState;
|
|
326
|
+
/** The open ask, if it still stands: a restart ask is about one turn only. */
|
|
327
|
+
protected openAsk(turn: number | null): (TakeBack & {
|
|
328
|
+
timer: ReturnType<typeof setTimeout>;
|
|
329
|
+
}) | null;
|
|
330
|
+
/** Whether `turn` can be played again from its start: the match holds that turn's snapshot, and it holds the whole game. */
|
|
331
|
+
protected restorable(turn: number): boolean;
|
|
332
|
+
/** The history `seat` may ask to undo, or null: its game says it can take an action back, and no undo of it was declined. */
|
|
333
|
+
protected undoable(seat: number): number | null;
|
|
334
|
+
/**
|
|
335
|
+
* A seat's take-back act (`docs/planning/restart-turn-plan.md`, `docs/planning/undo-plan.md`). `ask`: the seat
|
|
336
|
+
* wants its turn played again from its start (`restart`, only the seat whose turn it is) or its last action
|
|
337
|
+
* taken back (`undo`, when its game has one to take back); an AI opponent allows at once, a human one is asked,
|
|
338
|
+
* and no answer in {@link RESTART_ASK_MS} is a decline. `allow` / `decline`: the other seat's answer. `cancel`:
|
|
339
|
+
* the asker takes the ask back. One ask at a time, of either kind. The game is not paused while an ask is open:
|
|
340
|
+
* a restart undoes everything since the turn began anyway, and an undo ask lapses once the asker's history moves
|
|
341
|
+
* ({@link undoMoved}).
|
|
342
|
+
*/
|
|
343
|
+
restartAct(seat: number, act: RestartAct, kind?: TakeBackKind): ClientOutcome;
|
|
344
|
+
protected answerTakeBack(seat: number, allow: boolean, why: 'player' | 'timeout'): ClientOutcome;
|
|
345
|
+
protected takeBackNow(ask: TakeBack, allowedBy: 'ai' | 'opponent'): ClientOutcome;
|
|
346
|
+
/**
|
|
347
|
+
* What `seat` could take back moved ({@link GameSession.takeBack}): it acted, or a barrier fell. Its open undo
|
|
348
|
+
* ask lapses, and a decline no longer holds once the history it was about is gone.
|
|
349
|
+
*/
|
|
350
|
+
undoMoved(seat: number): void;
|
|
351
|
+
protected closeTakeBack(): void;
|
|
352
|
+
/** Tell every socket where a restart stands, when it changed (or always, `force`: an act's own answer). */
|
|
353
|
+
tellRestart(force?: boolean): void;
|
|
354
|
+
/** The game this match plays: every fact about it the shell needs is asked of it. Set by the composing match, before anything can reach it. */
|
|
355
|
+
protected game: GameSession<Line, Cmd>;
|
|
356
|
+
abstract readonly seats: readonly ShellSeat[];
|
|
357
|
+
protected readonly deps: ShellDeps;
|
|
358
|
+
constructor(id: string, spec: MatchSpec, deps: ShellDeps, restore?: {
|
|
359
|
+
epoch: string | null;
|
|
360
|
+
startedAt: number;
|
|
361
|
+
snapshot?: TurnSnapshot | null;
|
|
362
|
+
checkpoint?: unknown;
|
|
363
|
+
clockMs?: [number, number];
|
|
364
|
+
});
|
|
365
|
+
/** One line from the engine, as the composing match reads it: a concede the engine never ends ends here as its game-over would. */
|
|
366
|
+
protected abstract onLine(line: Line): void;
|
|
367
|
+
/** `Match`'s literal `{t:'act',…method:'concede'}` / the toy's `toyAdapter.concede(seat)` — the shell asks for the command, never builds one itself. */
|
|
368
|
+
protected abstract concedeCommand(seat: number): Cmd;
|
|
369
|
+
/**
|
|
370
|
+
* Forge did not confirm `watchConcede`'s concede in time: end the game now, as if it just had,
|
|
371
|
+
* `seat` the loser. `Match`'s is its own literal `gameover` line, through the ordinary `onLine`
|
|
372
|
+
* path; a generic `HostedMatch` applies the {@link GameAdapter.classify}-shaped outcome directly.
|
|
373
|
+
*/
|
|
374
|
+
protected abstract forceConcede(seat: number): void;
|
|
375
|
+
abstract fail(reason: string, frames?: string[]): void;
|
|
376
|
+
abstract stop(): void;
|
|
377
|
+
}
|
|
378
|
+
export {};
|