@pieai/swimmer-game-server-kit 0.2.2 → 0.2.4

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/README.md CHANGED
@@ -62,7 +62,7 @@ Install the exact reviewed npm version:
62
62
  ```json
63
63
  {
64
64
  "dependencies": {
65
- "@pieai/swimmer-game-server-kit": "0.1.0"
65
+ "@pieai/swimmer-game-server-kit": "0.2.4"
66
66
  }
67
67
  }
68
68
  ```
@@ -121,6 +121,23 @@ const client = await connectSwimmerGameClient({
121
121
  client.sendInput({ jump: true });
122
122
  ```
123
123
 
124
+ For an invitation or an exact-room return, pass `roomId` as a top-level option.
125
+ The Kit then uses the SDK's `joinById`, without falling back to `joinOrCreate`
126
+ when that room is full, expired, locked or unavailable. Omitting `roomId` preserves
127
+ existing creation behavior. The product owns invitation parsing, consent, protocol
128
+ compatibility and seat/reconnection rules; a public room ID grants no identity or
129
+ right to take an occupied seat. Actual loopback tests cover both admission paths.
130
+
131
+ `onConnectionChange` reports only `connected`, `reconnecting` or `closed` from
132
+ the official SDK's lifecycle events, not raw close reasons. A product that owns
133
+ explicit reauthenticated seat recovery can set `reconnectAutomatically: false`:
134
+ the SDK then makes no hidden retries, disconnected input/restart sends are dropped,
135
+ and the product may offer its own exact-room retry. Default SDK reconnection and
136
+ message buffering are otherwise unchanged. Automatic SDK recovery still requires
137
+ server-side `allowReconnection`; an application-specific seat reservation alone
138
+ does not enable that transport flow. Intentional `leave()` does not emit a user
139
+ connection-failure callback and remains safe after the transport already closed.
140
+
124
141
  ## Auth Usage
125
142
 
126
143
  ```ts
package/dist/client.d.ts CHANGED
@@ -2,13 +2,22 @@ import { type Room } from '@colyseus/sdk';
2
2
  import { type SwimmerGameMessages } from './definition.js';
3
3
  export interface SwimmerGameClient<TInput, TSnapshot, TPlayerId extends string = string> {
4
4
  readonly playerId: TPlayerId | null;
5
+ readonly connectionState: SwimmerConnectionState;
5
6
  readonly room: Room<unknown, TSnapshot>;
6
7
  leave(): Promise<void>;
7
8
  sendInput(input: TInput): void;
8
9
  sendRestart(): void;
9
10
  }
11
+ export type SwimmerConnectionState = 'connected' | 'reconnecting' | 'closed';
10
12
  export interface ConnectSwimmerGameClientOptions<TSnapshot extends object, TPlayerId extends string = string> {
11
13
  endpoint: string;
14
+ /** Join this existing room through the SDK's joinById. Failure must never
15
+ * create a replacement room. Omit for the existing joinOrCreate behavior. */
16
+ roomId?: string;
17
+ /** Keep SDK defaults unless the product owns explicit, reauthenticated
18
+ * exact-room recovery. False also drops gameplay sends while disconnected. */
19
+ reconnectAutomatically?: boolean;
20
+ onConnectionChange?: (state: SwimmerConnectionState) => void;
12
21
  joinOptions?: Record<string, unknown>;
13
22
  messages?: Partial<SwimmerGameMessages>;
14
23
  onError?: (message: string) => void;
package/dist/client.js CHANGED
@@ -2,9 +2,40 @@ import { Client } from '@colyseus/sdk';
2
2
  import { resolveSwimmerGameMessages } from './definition.js';
3
3
  export async function connectSwimmerGameClient(options) {
4
4
  const messages = resolveSwimmerGameMessages(options.messages);
5
+ if (options.roomId !== undefined &&
6
+ (typeof options.roomId !== 'string' ||
7
+ options.roomId.length === 0 ||
8
+ options.roomId.length > 128 ||
9
+ !/^[a-zA-Z0-9_-]+$/.test(options.roomId))) {
10
+ throw new Error('A bounded existing room ID is required.');
11
+ }
5
12
  const client = new Client(options.endpoint);
6
- const room = await client.joinOrCreate(options.roomName, options.joinOptions ?? {});
13
+ const room = options.roomId === undefined
14
+ ? await client.joinOrCreate(options.roomName, options.joinOptions ?? {})
15
+ : await client.joinById(options.roomId, options.joinOptions ?? {});
7
16
  let playerId = null;
17
+ let connectionState = 'connected';
18
+ let leaving = false;
19
+ if (options.reconnectAutomatically !== undefined)
20
+ room.reconnection.enabled = options.reconnectAutomatically;
21
+ const changed = (next) => {
22
+ if (connectionState === next)
23
+ return;
24
+ connectionState = next;
25
+ if (next === 'closed')
26
+ playerId = null;
27
+ if (!leaving)
28
+ options.onConnectionChange?.(next);
29
+ };
30
+ // The SDK emits drop even when retry is disabled; do not promise automatic
31
+ // recovery in that mode or report the following leave as another failure.
32
+ room.onDrop(() => changed(options.reconnectAutomatically === false ? 'closed' : 'reconnecting'));
33
+ room.onReconnect(() => {
34
+ changed('connected');
35
+ if (!leaving)
36
+ room.send(messages.identify);
37
+ });
38
+ room.onLeave(() => changed('closed'));
8
39
  room.onMessage(messages.welcome, (payload) => {
9
40
  playerId = payload.playerId;
10
41
  options.onWelcome?.(payload);
@@ -17,18 +48,29 @@ export async function connectSwimmerGameClient(options) {
17
48
  options.onError?.(payload.message ?? 'Unknown game server error.');
18
49
  });
19
50
  room.send(messages.identify);
51
+ options.onConnectionChange?.(connectionState);
20
52
  return {
21
53
  get playerId() {
22
54
  return playerId;
23
55
  },
56
+ get connectionState() {
57
+ return connectionState;
58
+ },
24
59
  room,
25
60
  async leave() {
61
+ leaving = true;
62
+ if (connectionState === 'closed')
63
+ return;
26
64
  await room.leave();
27
65
  },
28
66
  sendInput(input) {
67
+ if (options.reconnectAutomatically === false && connectionState !== 'connected')
68
+ return;
29
69
  room.send(messages.input, { input });
30
70
  },
31
71
  sendRestart() {
72
+ if (options.reconnectAutomatically === false && connectionState !== 'connected')
73
+ return;
32
74
  room.send(messages.restart);
33
75
  },
34
76
  };
@@ -1 +1 @@
1
- {"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAA4B,MAAM,iBAAiB,CAAC;AAuBvF,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAK5C,OAA8D;IAE9D,MAAM,QAAQ,GAAG,0BAA0B,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,YAAY,CAAY,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IAC/F,IAAI,QAAQ,GAAqB,IAAI,CAAC;IAEtC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAkD,EAAE,EAAE;QACtF,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QAC5B,OAAO,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC;QAC7B,OAAO,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,OAA6B,EAAE,EAAE;QAC/D,OAAO,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,OAA6B,EAAE,EAAE;QAC/D,OAAO,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,OAAO,IAAI,4BAA4B,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAE7B,OAAO;QACL,IAAI,QAAQ;YACV,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,IAAI;QACJ,KAAK,CAAC,KAAK;YACT,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;QACD,SAAS,CAAC,KAAa;YACrB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,WAAW;YACT,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pieai/swimmer-game-server-kit",
3
- "version": "0.2.2",
3
+ "version": "0.2.4",
4
4
  "description": "Shared Colyseus game server kit for PieAI Swimmer-based games.",
5
5
  "keywords": [
6
6
  "colyseus",