@crowdedkingdomstudios/crowdyjs 5.1.0 → 5.2.1
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/MIGRATION.md +64 -0
- package/README.md +19 -0
- package/dist/client.d.ts +98 -5
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +74 -5
- package/dist/crowdy-client.d.ts +31 -0
- package/dist/crowdy-client.d.ts.map +1 -1
- package/dist/crowdy-client.js +8 -0
- package/dist/domains/actors.d.ts +88 -5
- package/dist/domains/actors.d.ts.map +1 -1
- package/dist/domains/actors.js +89 -6
- package/dist/domains/apps.d.ts +95 -41
- package/dist/domains/apps.d.ts.map +1 -1
- package/dist/domains/apps.js +80 -33
- package/dist/domains/auth.d.ts +139 -19
- package/dist/domains/auth.d.ts.map +1 -1
- package/dist/domains/auth.js +137 -17
- package/dist/domains/channels.d.ts +264 -5
- package/dist/domains/channels.d.ts.map +1 -1
- package/dist/domains/channels.js +264 -5
- package/dist/domains/chunks.d.ts +116 -3
- package/dist/domains/chunks.d.ts.map +1 -1
- package/dist/domains/chunks.js +116 -3
- package/dist/domains/gameModel.d.ts +412 -6
- package/dist/domains/gameModel.d.ts.map +1 -1
- package/dist/domains/gameModel.js +412 -6
- package/dist/domains/platform.d.ts +36 -20
- package/dist/domains/platform.d.ts.map +1 -1
- package/dist/domains/platform.js +29 -18
- package/dist/domains/serverStatus.d.ts +74 -6
- package/dist/domains/serverStatus.d.ts.map +1 -1
- package/dist/domains/serverStatus.js +74 -6
- package/dist/domains/state.d.ts +50 -2
- package/dist/domains/state.d.ts.map +1 -1
- package/dist/domains/state.js +50 -2
- package/dist/domains/teams.d.ts +265 -7
- package/dist/domains/teams.d.ts.map +1 -1
- package/dist/domains/teams.js +267 -9
- package/dist/domains/teleport.d.ts +30 -2
- package/dist/domains/teleport.d.ts.map +1 -1
- package/dist/domains/teleport.js +30 -2
- package/dist/domains/udp.d.ts +341 -5
- package/dist/domains/udp.d.ts.map +1 -1
- package/dist/domains/udp.js +341 -5
- package/dist/domains/users.d.ts +42 -11
- package/dist/domains/users.d.ts.map +1 -1
- package/dist/domains/users.js +41 -10
- package/dist/domains/voxels.d.ts +107 -2
- package/dist/domains/voxels.d.ts.map +1 -1
- package/dist/domains/voxels.js +107 -2
- package/dist/errors.d.ts +116 -0
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +100 -0
- package/dist/generated/graphql.d.ts +1787 -110
- package/dist/generated/graphql.d.ts.map +1 -1
- package/dist/generated/graphql.js +75 -9
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -1
- package/dist/realtime.d.ts +226 -0
- package/dist/realtime.d.ts.map +1 -1
- package/dist/realtime.js +90 -0
- package/dist/session.d.ts +46 -0
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +35 -0
- package/dist/types.d.ts +429 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +53 -0
- package/dist/utils.d.ts +86 -0
- package/dist/utils.d.ts.map +1 -1
- package/dist/utils.js +86 -0
- package/dist/world.d.ts +192 -0
- package/dist/world.d.ts.map +1 -1
- package/dist/world.js +170 -0
- package/package.json +1 -1
package/dist/domains/udp.d.ts
CHANGED
|
@@ -3,37 +3,318 @@ import type { SubscriptionManager, UdpNotificationHandlers } from '../subscripti
|
|
|
3
3
|
import { type ConnectUdpProxyMutation, type UdpProxyConnectionStatusQuery, type SendActorUpdateMutationVariables, type SendVoxelUpdateMutationVariables, type SendAudioPacketMutationVariables, type SendTextPacketMutationVariables, type SendClientEventMutationVariables, type SendSingleActorMessageMutationVariables, type SendChannelMessageMutationVariables } from '../generated/graphql.js';
|
|
4
4
|
import type { SpatialNotification } from '../realtime.js';
|
|
5
5
|
/**
|
|
6
|
-
* UDP proxy access for browser-style clients that can't open raw UDP
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
6
|
+
* UDP proxy access for browser-style clients that can't open raw UDP sockets.
|
|
7
|
+
* Exposed as `client.udp`; for game loops prefer the ergonomic, app-scoped
|
|
8
|
+
* facade `client.world(appId)`, which passes `appId` for you and tracks the
|
|
9
|
+
* current chunk so you don't repeat it on every send.
|
|
10
|
+
*
|
|
11
|
+
* All send mutations go over the **game-api** GraphQL HTTP endpoint and are
|
|
12
|
+
* forwarded to the assigned game server by the API's UDP proxy module;
|
|
13
|
+
* notifications come back over a single shared `graphql-transport-ws`
|
|
14
|
+
* WebSocket (same game-api endpoint) managed by `SubscriptionManager` — the
|
|
15
|
+
* first subscriber opens it and the last to unsubscribe closes it. Every call
|
|
16
|
+
* requires an authenticated session carrying a **bearer game token** (minted
|
|
17
|
+
* by the management-api, set via `client.auth.login()` or `client.setToken()`);
|
|
18
|
+
* a UDP proxy session is opened lazily on the first send or subscribe if you
|
|
19
|
+
* didn't call {@link connect} first.
|
|
20
|
+
*
|
|
21
|
+
* Each packet type comes in two shapes:
|
|
22
|
+
* - Plain `send*` — fire-and-forget. Resolves to a `boolean` ack that the proxy
|
|
23
|
+
* *accepted the datagram for sending*; it does **not** confirm the world
|
|
24
|
+
* applied it or that it was delivered.
|
|
25
|
+
* - `send*AndWait` — allocates a `sequenceNumber`, then resolves with the
|
|
26
|
+
* server's matching echo (a {@link SpatialNotification}) correlated by that
|
|
27
|
+
* sequence, or rejects on timeout. Only actor and voxel updates are echoed
|
|
28
|
+
* back to the sender (`ActorUpdateResponse` / `VoxelUpdateResponse`); audio,
|
|
29
|
+
* text, and event sends are not.
|
|
30
|
+
*
|
|
31
|
+
* Spatial caveats: a `sequenceNumber` is a uint8 (0-255) used for
|
|
32
|
+
* **correlation only** — not an idempotency key, and the server does not dedupe
|
|
33
|
+
* replays. The **first** spatial message to a brand-new chunk may be dropped
|
|
34
|
+
* server-side while grid permissions load, so clients should re-send (the
|
|
35
|
+
* two-client tests register twice for this reason). To receive any
|
|
36
|
+
* `...AndWait` echo or notification you must have an active {@link subscribe}.
|
|
11
37
|
*/
|
|
12
38
|
export declare class UdpAPI {
|
|
13
39
|
private gql;
|
|
14
40
|
private subs;
|
|
15
41
|
private readonly sequences;
|
|
16
42
|
constructor(gql: GraphQLClient, subs: SubscriptionManager);
|
|
43
|
+
/**
|
|
44
|
+
* Open (or re-fetch) the UDP proxy session for this game token. Idempotent:
|
|
45
|
+
* if a session is already open it returns the existing status; on first open
|
|
46
|
+
* it binds a socket and selects the game server with the fewest clients.
|
|
47
|
+
* Calling this is optional — any `send*` mutation or {@link subscribe} opens a
|
|
48
|
+
* session lazily — but use it to pre-warm the socket or surface auth/
|
|
49
|
+
* connectivity problems eagerly. To force a fresh socket, call
|
|
50
|
+
* {@link disconnect} first.
|
|
51
|
+
*
|
|
52
|
+
* @returns The {@link UdpProxyConnectionStatus}: `connected`, plus (when
|
|
53
|
+
* connected) `serverIp6`, `serverClientPort`, and `lastMessageTime`.
|
|
54
|
+
* @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the request carries no
|
|
55
|
+
* valid bearer game token.
|
|
56
|
+
*/
|
|
17
57
|
connect(): Promise<ConnectUdpProxyMutation['connectUdpProxy']>;
|
|
58
|
+
/**
|
|
59
|
+
* Close the UDP proxy session and socket for this game token. Note that
|
|
60
|
+
* unsubscribing from notifications does **not** disconnect — call this (or
|
|
61
|
+
* rely on the server's inactivity timeout) to release the session, e.g. to
|
|
62
|
+
* force a fresh socket on the next {@link connect} or send.
|
|
63
|
+
*
|
|
64
|
+
* @returns `true` once the session has been closed.
|
|
65
|
+
* @throws {CrowdyGraphQLError} on auth failures.
|
|
66
|
+
*/
|
|
18
67
|
disconnect(): Promise<boolean>;
|
|
68
|
+
/**
|
|
69
|
+
* Read the current UDP proxy session status **without** opening one. With no
|
|
70
|
+
* game token it simply reports `connected: false` rather than throwing.
|
|
71
|
+
* Inspect `lastMessageTime` to gauge connection health.
|
|
72
|
+
*
|
|
73
|
+
* @returns The {@link UdpProxyConnectionStatus} (`connected`, plus when
|
|
74
|
+
* connected `serverIp6`, `serverClientPort`, and `lastMessageTime`).
|
|
75
|
+
*/
|
|
19
76
|
connectionStatus(): Promise<UdpProxyConnectionStatusQuery['udpProxyConnectionStatus']>;
|
|
77
|
+
/**
|
|
78
|
+
* Send an actor (player/NPC) state update for spatial replication to nearby
|
|
79
|
+
* chunks. Fire-and-forget; opens a UDP proxy session automatically if none
|
|
80
|
+
* exists. The applied echo (`ActorUpdateResponse`) and any failure
|
|
81
|
+
* (`GenericErrorResponse`) arrive asynchronously on {@link subscribe},
|
|
82
|
+
* correlated by `sequenceNumber`; use {@link sendActorUpdateAndWait} to await
|
|
83
|
+
* that echo inline.
|
|
84
|
+
*
|
|
85
|
+
* @param input - {@link ActorUpdateRequestInput}:
|
|
86
|
+
* - `appId` — owning app id (`BigInt` as a decimal string).
|
|
87
|
+
* - `chunk` — `{ x, y, z }` chunk address; each axis is a signed int64
|
|
88
|
+
* decimal string. A chunk is a 16x16x16 voxel cube.
|
|
89
|
+
* - `uuid` — the actor id: exactly 32 ASCII characters (the UDP-wire id),
|
|
90
|
+
* **not** an RFC-4122 UUID.
|
|
91
|
+
* - `state` — actor state blob, base64-encoded; may be `''` for a
|
|
92
|
+
* registration-only update.
|
|
93
|
+
* - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
|
|
94
|
+
* to 8 for actor updates.
|
|
95
|
+
* - `decayRate` — replication decay algorithm: 0 none, 1 exponential,
|
|
96
|
+
* 2 linear 50%, 3 linear 25%, 4 linear 10%, 5 linear 5%; defaults to 1
|
|
97
|
+
* (exponential) for actor updates.
|
|
98
|
+
* - `sequenceNumber` — optional uint8 (0-255) correlation id; not an
|
|
99
|
+
* idempotency key.
|
|
100
|
+
* @returns `true` when the datagram was accepted for sending to the game
|
|
101
|
+
* server — **not** confirmation that the world applied it.
|
|
102
|
+
* @throws {CrowdyGraphQLError} e.g. `UNAUTHENTICATED` without a valid game
|
|
103
|
+
* token, or `BAD_USER_INPUT` for a malformed packet.
|
|
104
|
+
*/
|
|
20
105
|
sendActorUpdate(input: SendActorUpdateMutationVariables['input']): Promise<boolean>;
|
|
106
|
+
/**
|
|
107
|
+
* Send an actor update and wait for the server's applied echo. Allocates a
|
|
108
|
+
* `sequenceNumber` when `input.sequenceNumber` is omitted, registers the wait
|
|
109
|
+
* *before* sending, then resolves with the matching `ActorUpdateResponse`.
|
|
110
|
+
* Requires an active {@link subscribe} so the echo can be delivered over the
|
|
111
|
+
* shared WebSocket.
|
|
112
|
+
*
|
|
113
|
+
* @param input - {@link ActorUpdateRequestInput} (see {@link sendActorUpdate}
|
|
114
|
+
* for field units/encoding). Omit `sequenceNumber` to let the SDK allocate
|
|
115
|
+
* one.
|
|
116
|
+
* @param options - `timeoutMs`: how long to wait for the echo, in
|
|
117
|
+
* milliseconds; defaults to the client's realtime `waitTimeoutMs` (5000).
|
|
118
|
+
* @returns The correlated {@link SpatialNotification} (the `ActorUpdateResponse`
|
|
119
|
+
* echo).
|
|
120
|
+
* @throws {CrowdyGraphQLError} if the underlying send is rejected.
|
|
121
|
+
* @throws {CrowdyTimeoutError} if the HTTP send leg exceeds the client's
|
|
122
|
+
* request timeout.
|
|
123
|
+
* @throws {CrowdyRealtimeError} if no echo arrives within `timeoutMs`
|
|
124
|
+
* (`code === 'UDP_SEQUENCE_TIMEOUT'`, retryable), or the server returns a
|
|
125
|
+
* matching `GenericErrorResponse` (its `code` is the server's `errorCode`).
|
|
126
|
+
* @example
|
|
127
|
+
* ```ts
|
|
128
|
+
* const unsubscribe = client.udp.subscribe({}, appId); // echoes need an open WS
|
|
129
|
+
* const echo = await client.udp.sendActorUpdateAndWait({
|
|
130
|
+
* appId,
|
|
131
|
+
* chunk: { x: '0', y: '0', z: '0' },
|
|
132
|
+
* uuid,
|
|
133
|
+
* state: 'AA==',
|
|
134
|
+
* distance: 8,
|
|
135
|
+
* });
|
|
136
|
+
* console.log(echo.__typename, echo.sequenceNumber);
|
|
137
|
+
* ```
|
|
138
|
+
*/
|
|
21
139
|
sendActorUpdateAndWait(input: SendActorUpdateMutationVariables['input'], options?: {
|
|
22
140
|
timeoutMs?: number;
|
|
23
141
|
}): Promise<SpatialNotification>;
|
|
142
|
+
/**
|
|
143
|
+
* Send a single voxel (block) update for spatial replication to nearby
|
|
144
|
+
* chunks. Fire-and-forget; opens a UDP proxy session automatically. The
|
|
145
|
+
* applied echo (`VoxelUpdateResponse`) and failures (`GenericErrorResponse`)
|
|
146
|
+
* arrive asynchronously on {@link subscribe}; use
|
|
147
|
+
* {@link sendVoxelUpdateAndWait} to await the echo inline.
|
|
148
|
+
*
|
|
149
|
+
* @param input - {@link VoxelUpdateRequestInput}:
|
|
150
|
+
* - `appId` — owning app id (`BigInt` as a decimal string).
|
|
151
|
+
* - `chunk` — `{ x, y, z }` chunk address (signed int64 decimal strings); a
|
|
152
|
+
* chunk is a 16x16x16 voxel cube.
|
|
153
|
+
* - `uuid` — 32-ASCII-character actor/source id (not RFC-4122).
|
|
154
|
+
* - `voxel` — `{ x, y, z }` voxel coordinates within the chunk; each is an
|
|
155
|
+
* int16 (-32768 to 32767).
|
|
156
|
+
* - `voxelType` — the new voxel type id.
|
|
157
|
+
* - `voxelState` — voxel state blob, base64-encoded.
|
|
158
|
+
* - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
|
|
159
|
+
* to 8 for voxel updates.
|
|
160
|
+
* - `decayRate` — decay algorithm 0-5 (see {@link sendActorUpdate});
|
|
161
|
+
* defaults to 0 (none) for voxel updates.
|
|
162
|
+
* - `sequenceNumber` — optional uint8 (0-255) correlation id.
|
|
163
|
+
* @returns `true` when accepted for sending — **not** confirmation the world
|
|
164
|
+
* applied the change.
|
|
165
|
+
* @throws {CrowdyGraphQLError} on auth/validation failures.
|
|
166
|
+
*/
|
|
24
167
|
sendVoxelUpdate(input: SendVoxelUpdateMutationVariables['input']): Promise<boolean>;
|
|
168
|
+
/**
|
|
169
|
+
* Send a voxel update and wait for the server's applied `VoxelUpdateResponse`
|
|
170
|
+
* echo. Allocates a `sequenceNumber` when omitted and requires an active
|
|
171
|
+
* {@link subscribe}.
|
|
172
|
+
*
|
|
173
|
+
* @param input - {@link VoxelUpdateRequestInput} (see {@link sendVoxelUpdate}
|
|
174
|
+
* for field units/encoding).
|
|
175
|
+
* @param options - `timeoutMs`: echo wait in milliseconds; defaults to the
|
|
176
|
+
* client's realtime `waitTimeoutMs` (5000).
|
|
177
|
+
* @returns The correlated {@link SpatialNotification} (`VoxelUpdateResponse`).
|
|
178
|
+
* @throws {CrowdyGraphQLError} if the underlying send is rejected.
|
|
179
|
+
* @throws {CrowdyTimeoutError} if the HTTP send leg times out.
|
|
180
|
+
* @throws {CrowdyRealtimeError} on echo timeout
|
|
181
|
+
* (`code === 'UDP_SEQUENCE_TIMEOUT'`) or a matching `GenericErrorResponse`
|
|
182
|
+
* (its `code` is the server's `errorCode`).
|
|
183
|
+
*/
|
|
25
184
|
sendVoxelUpdateAndWait(input: SendVoxelUpdateMutationVariables['input'], options?: {
|
|
26
185
|
timeoutMs?: number;
|
|
27
186
|
}): Promise<SpatialNotification>;
|
|
187
|
+
/**
|
|
188
|
+
* Send a spatial voice/audio packet, fanned out to nearby actors as a
|
|
189
|
+
* `ClientAudioNotification`. Fire-and-forget; opens a UDP proxy session
|
|
190
|
+
* automatically. Voice may be gated by a runtime grid permission
|
|
191
|
+
* (`use_voice_chat`) for the region — if the caller lacks it the game server
|
|
192
|
+
* replies asynchronously with a `GenericErrorResponse` (`errorCode`
|
|
193
|
+
* `UNAUTHORIZED`) on {@link subscribe}. The sender receives no success echo.
|
|
194
|
+
*
|
|
195
|
+
* @param input - {@link ClientAudioPacketInput}:
|
|
196
|
+
* - `appId` — owning app id (`BigInt` as a decimal string).
|
|
197
|
+
* - `chunk` — `{ x, y, z }` chunk address (signed int64 decimal strings).
|
|
198
|
+
* - `uuid` — 32-ASCII-character source id (typically the player; not
|
|
199
|
+
* RFC-4122).
|
|
200
|
+
* - `audioData` — compressed audio, base64-encoded.
|
|
201
|
+
* - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
|
|
202
|
+
* to 1 for audio packets.
|
|
203
|
+
* - `decayRate` — decay algorithm 0-5 (see {@link sendActorUpdate});
|
|
204
|
+
* defaults to 0 (none) for audio packets.
|
|
205
|
+
* - `sequenceNumber` — optional uint8 (0-255) correlation id.
|
|
206
|
+
* @returns `true` when accepted for sending — **not** confirmation of
|
|
207
|
+
* delivery.
|
|
208
|
+
* @throws {CrowdyGraphQLError} on auth/validation failures.
|
|
209
|
+
*/
|
|
28
210
|
sendAudioPacket(input: SendAudioPacketMutationVariables['input']): Promise<boolean>;
|
|
211
|
+
/**
|
|
212
|
+
* Send a voice/audio packet and wait for a response correlated by
|
|
213
|
+
* `sequenceNumber`. **Note:** the server does not echo audio packets back to
|
|
214
|
+
* the sender (only `GenericErrorResponse` failures are correlated), so on
|
|
215
|
+
* success there is usually nothing to resolve and this rejects on timeout —
|
|
216
|
+
* prefer the fire-and-forget {@link sendAudioPacket} unless you specifically
|
|
217
|
+
* want to surface a send error inline. Requires an active {@link subscribe}.
|
|
218
|
+
*
|
|
219
|
+
* @param input - {@link ClientAudioPacketInput} (see {@link sendAudioPacket}).
|
|
220
|
+
* @param options - `timeoutMs`: wait in milliseconds; defaults to the client's
|
|
221
|
+
* realtime `waitTimeoutMs` (5000).
|
|
222
|
+
* @returns The correlated {@link SpatialNotification}, if one is delivered.
|
|
223
|
+
* @throws {CrowdyGraphQLError} if the underlying send is rejected.
|
|
224
|
+
* @throws {CrowdyTimeoutError} if the HTTP send leg times out.
|
|
225
|
+
* @throws {CrowdyRealtimeError} on timeout (`code === 'UDP_SEQUENCE_TIMEOUT'`)
|
|
226
|
+
* or a matching `GenericErrorResponse` (its `code` is the server's
|
|
227
|
+
* `errorCode`, e.g. `UNAUTHORIZED` for a missing voice permission).
|
|
228
|
+
*/
|
|
29
229
|
sendAudioPacketAndWait(input: SendAudioPacketMutationVariables['input'], options?: {
|
|
30
230
|
timeoutMs?: number;
|
|
31
231
|
}): Promise<SpatialNotification>;
|
|
232
|
+
/**
|
|
233
|
+
* Send a spatial text/chat packet, fanned out to nearby actors as a
|
|
234
|
+
* `ClientTextNotification`. Fire-and-forget; opens a UDP proxy session
|
|
235
|
+
* automatically. The sender receives no success echo; failures arrive
|
|
236
|
+
* asynchronously as `GenericErrorResponse` on {@link subscribe}.
|
|
237
|
+
*
|
|
238
|
+
* @param input - {@link ClientTextPacketInput}:
|
|
239
|
+
* - `appId` — owning app id (`BigInt` as a decimal string).
|
|
240
|
+
* - `chunk` — `{ x, y, z }` chunk address (signed int64 decimal strings).
|
|
241
|
+
* - `uuid` — 32-ASCII-character source id (not RFC-4122).
|
|
242
|
+
* - `text` — message content, UTF-8 (sent as plain text, not base64).
|
|
243
|
+
* - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
|
|
244
|
+
* to 8 for text packets.
|
|
245
|
+
* - `decayRate` — decay algorithm 0-5 (see {@link sendActorUpdate});
|
|
246
|
+
* defaults to 0 (none) for text packets.
|
|
247
|
+
* - `sequenceNumber` — optional uint8 (0-255) correlation id.
|
|
248
|
+
* @returns `true` when accepted for sending — **not** confirmation of
|
|
249
|
+
* delivery.
|
|
250
|
+
* @throws {CrowdyGraphQLError} on auth/validation failures.
|
|
251
|
+
*/
|
|
32
252
|
sendTextPacket(input: SendTextPacketMutationVariables['input']): Promise<boolean>;
|
|
253
|
+
/**
|
|
254
|
+
* Send a text/chat packet and wait for a response correlated by
|
|
255
|
+
* `sequenceNumber`. **Note:** the server does not echo text packets back to
|
|
256
|
+
* the sender (only `GenericErrorResponse` failures are correlated), so on
|
|
257
|
+
* success there is usually nothing to resolve and this rejects on timeout —
|
|
258
|
+
* prefer the fire-and-forget {@link sendTextPacket} unless you specifically
|
|
259
|
+
* want to surface a send error inline. Requires an active {@link subscribe}.
|
|
260
|
+
*
|
|
261
|
+
* @param input - {@link ClientTextPacketInput} (see {@link sendTextPacket}).
|
|
262
|
+
* @param options - `timeoutMs`: wait in milliseconds; defaults to the client's
|
|
263
|
+
* realtime `waitTimeoutMs` (5000).
|
|
264
|
+
* @returns The correlated {@link SpatialNotification}, if one is delivered.
|
|
265
|
+
* @throws {CrowdyGraphQLError} if the underlying send is rejected.
|
|
266
|
+
* @throws {CrowdyTimeoutError} if the HTTP send leg times out.
|
|
267
|
+
* @throws {CrowdyRealtimeError} on timeout (`code === 'UDP_SEQUENCE_TIMEOUT'`)
|
|
268
|
+
* or a matching `GenericErrorResponse` (its `code` is the server's
|
|
269
|
+
* `errorCode`).
|
|
270
|
+
*/
|
|
33
271
|
sendTextPacketAndWait(input: SendTextPacketMutationVariables['input'], options?: {
|
|
34
272
|
timeoutMs?: number;
|
|
35
273
|
}): Promise<SpatialNotification>;
|
|
274
|
+
/**
|
|
275
|
+
* Send a custom, app-defined client event for spatial replication to nearby
|
|
276
|
+
* chunks; nearby actors receive it as a `ClientEventNotification`.
|
|
277
|
+
* Fire-and-forget; opens a UDP proxy session automatically. The sender
|
|
278
|
+
* receives no success echo; failures arrive asynchronously as
|
|
279
|
+
* `GenericErrorResponse` on {@link subscribe}.
|
|
280
|
+
*
|
|
281
|
+
* @param input - {@link ClientEventNotificationInput}:
|
|
282
|
+
* - `appId` — owning app id (`BigInt` as a decimal string).
|
|
283
|
+
* - `chunk` — `{ x, y, z }` chunk address (signed int64 decimal strings).
|
|
284
|
+
* - `uuid` — 32-ASCII-character id of the object controlling the event
|
|
285
|
+
* (not RFC-4122).
|
|
286
|
+
* - `eventType` — app-defined event id, a uint16 (0-65535).
|
|
287
|
+
* - `state` — event state blob, base64-encoded; format defined by the event
|
|
288
|
+
* type.
|
|
289
|
+
* - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
|
|
290
|
+
* to 8 for events.
|
|
291
|
+
* - `decayRate` — decay algorithm 0-5 (see {@link sendActorUpdate});
|
|
292
|
+
* defaults to 0 (none) for events.
|
|
293
|
+
* - `sequenceNumber` — optional uint8 (0-255) correlation id.
|
|
294
|
+
* @returns `true` when accepted for sending — **not** confirmation the world
|
|
295
|
+
* processed it.
|
|
296
|
+
* @throws {CrowdyGraphQLError} on auth/validation failures.
|
|
297
|
+
*/
|
|
36
298
|
sendClientEvent(input: SendClientEventMutationVariables['input']): Promise<boolean>;
|
|
299
|
+
/**
|
|
300
|
+
* Send a client event and wait for a response correlated by `sequenceNumber`.
|
|
301
|
+
* **Note:** the server does not echo events back to the sender (only
|
|
302
|
+
* `GenericErrorResponse` failures are correlated), so on success there is
|
|
303
|
+
* usually nothing to resolve and this rejects on timeout — prefer the
|
|
304
|
+
* fire-and-forget {@link sendClientEvent} unless you specifically want to
|
|
305
|
+
* surface a send error inline. Requires an active {@link subscribe}.
|
|
306
|
+
*
|
|
307
|
+
* @param input - {@link ClientEventNotificationInput} (see
|
|
308
|
+
* {@link sendClientEvent}).
|
|
309
|
+
* @param options - `timeoutMs`: wait in milliseconds; defaults to the client's
|
|
310
|
+
* realtime `waitTimeoutMs` (5000).
|
|
311
|
+
* @returns The correlated {@link SpatialNotification}, if one is delivered.
|
|
312
|
+
* @throws {CrowdyGraphQLError} if the underlying send is rejected.
|
|
313
|
+
* @throws {CrowdyTimeoutError} if the HTTP send leg times out.
|
|
314
|
+
* @throws {CrowdyRealtimeError} on timeout (`code === 'UDP_SEQUENCE_TIMEOUT'`)
|
|
315
|
+
* or a matching `GenericErrorResponse` (its `code` is the server's
|
|
316
|
+
* `errorCode`).
|
|
317
|
+
*/
|
|
37
318
|
sendClientEventAndWait(input: SendClientEventMutationVariables['input'], options?: {
|
|
38
319
|
timeoutMs?: number;
|
|
39
320
|
}): Promise<SpatialNotification>;
|
|
@@ -43,6 +324,20 @@ export declare class UdpAPI {
|
|
|
43
324
|
* Fire-and-forget: the sender receives no echo, so there is no
|
|
44
325
|
* `sendSingleActorMessageAndWait` variant. The target receives a
|
|
45
326
|
* `SingleActorMessageNotification` on its `udpNotifications` subscription.
|
|
327
|
+
*
|
|
328
|
+
* @param input - {@link SingleActorMessageInput}:
|
|
329
|
+
* - `appId` — the destination actor's app id (`BigInt` as a decimal string).
|
|
330
|
+
* - `chunk` — the **destination** actor's current `{ x, y, z }` chunk
|
|
331
|
+
* (signed int64 decimal strings); the sender must know it.
|
|
332
|
+
* - `targetUuid` — the destination actor's id: exactly 32 ASCII characters
|
|
333
|
+
* (not RFC-4122).
|
|
334
|
+
* - `payload` — message body, base64-encoded; opaque to the server (embed
|
|
335
|
+
* the sender identity yourself if needed).
|
|
336
|
+
* - `sequenceNumber` — optional uint8 (0-255) correlation id (used only to
|
|
337
|
+
* correlate a `GenericErrorResponse`).
|
|
338
|
+
* @returns `true` when accepted for sending — **not** confirmation of
|
|
339
|
+
* delivery.
|
|
340
|
+
* @throws {CrowdyGraphQLError} on auth/validation failures.
|
|
46
341
|
*/
|
|
47
342
|
sendSingleActorMessage(input: SendSingleActorMessageMutationVariables['input']): Promise<boolean>;
|
|
48
343
|
/**
|
|
@@ -51,6 +346,19 @@ export declare class UdpAPI {
|
|
|
51
346
|
* `udpNotifications` subscription. Requires the channel `send_messages`
|
|
52
347
|
* permission; the server drops the message otherwise. Fire-and-forget: the
|
|
53
348
|
* sender receives no echo.
|
|
349
|
+
*
|
|
350
|
+
* @param input - {@link ChannelMessageInput}:
|
|
351
|
+
* - `channelId` — the channel id (`groups.group_id`) as a `BigInt` decimal
|
|
352
|
+
* string.
|
|
353
|
+
* - `uuid` — the sender's own actor id: exactly 32 ASCII characters (not
|
|
354
|
+
* RFC-4122).
|
|
355
|
+
* - `payload` — message body, base64-encoded; opaque to the server, max
|
|
356
|
+
* 1024 bytes.
|
|
357
|
+
* - `sequenceNumber` — optional uint8 (0-255) correlation id.
|
|
358
|
+
* @returns `true` when accepted for sending — **not** confirmation of
|
|
359
|
+
* delivery; note that a message dropped for a missing `send_messages`
|
|
360
|
+
* permission still returns `true`.
|
|
361
|
+
* @throws {CrowdyGraphQLError} on auth/validation failures.
|
|
54
362
|
*/
|
|
55
363
|
sendChannelMessage(input: SendChannelMessageMutationVariables['input']): Promise<boolean>;
|
|
56
364
|
/**
|
|
@@ -62,6 +370,34 @@ export declare class UdpAPI {
|
|
|
62
370
|
* only delivers that app's spatial notifications and rejects app-agnostic
|
|
63
371
|
* subscriptions (a single game token reused across apps would otherwise
|
|
64
372
|
* cross-deliver). Use a separate client per app (sharing the token store).
|
|
373
|
+
*
|
|
374
|
+
* A missing `appId` is rejected by the game-api with a `RealtimeConnectionEvent`
|
|
375
|
+
* (`code === 'APP_ID_REQUIRED'`) delivered to your `connectionEvent` handler,
|
|
376
|
+
* after which the stream ends. Subscribing without a session token throws
|
|
377
|
+
* synchronously instead.
|
|
378
|
+
*
|
|
379
|
+
* @param handlers - {@link UdpNotificationHandlers}: optional per-typename
|
|
380
|
+
* callbacks (`actorUpdate`, `voxelUpdate`, `audio`, `text`, `clientEvent`,
|
|
381
|
+
* `singleActorMessage`, `channelMessage`, `genericError`, `connectionEvent`,
|
|
382
|
+
* etc.) plus `any` (every notification) and `error` (a
|
|
383
|
+
* {@link CrowdyRealtimeError}).
|
|
384
|
+
* @param appId - The app to scope delivery to (`BigInt` as a decimal string).
|
|
385
|
+
* Required.
|
|
386
|
+
* @returns An unsubscribe function that detaches these handlers (and closes
|
|
387
|
+
* the shared WebSocket if it was the last subscription).
|
|
388
|
+
* @throws {CrowdyRealtimeError} `code === 'AUTH_REQUIRED'` if called with no
|
|
389
|
+
* session token. Server-side connection problems (e.g. `APP_ID_REQUIRED`,
|
|
390
|
+
* `UDP_PROXY_CONNECTION_FAILED`) are delivered to the `connectionEvent` /
|
|
391
|
+
* `error` handlers rather than thrown.
|
|
392
|
+
* @example
|
|
393
|
+
* ```ts
|
|
394
|
+
* const unsubscribe = client.udp.subscribe({
|
|
395
|
+
* actorUpdate: (n) => console.log('actor', n.uuid, n.sequenceNumber),
|
|
396
|
+
* genericError: (e) => console.warn('udp error', e.errorCode),
|
|
397
|
+
* }, appId);
|
|
398
|
+
* // later…
|
|
399
|
+
* unsubscribe();
|
|
400
|
+
* ```
|
|
65
401
|
*/
|
|
66
402
|
subscribe(handlers: UdpNotificationHandlers, appId: string): () => void;
|
|
67
403
|
private withSequence;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"udp.d.ts","sourceRoot":"","sources":["../../src/domains/udp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEL,KAAK,uBAAuB,EAG5B,KAAK,6BAA6B,EAElC,KAAK,gCAAgC,EAErC,KAAK,gCAAgC,EAErC,KAAK,gCAAgC,EAErC,KAAK,+BAA+B,EAEpC,KAAK,gCAAgC,EAErC,KAAK,uCAAuC,EAE5C,KAAK,mCAAmC,EACzC,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG1D
|
|
1
|
+
{"version":3,"file":"udp.d.ts","sourceRoot":"","sources":["../../src/domains/udp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEL,KAAK,uBAAuB,EAG5B,KAAK,6BAA6B,EAElC,KAAK,gCAAgC,EAErC,KAAK,gCAAgC,EAErC,KAAK,gCAAgC,EAErC,KAAK,+BAA+B,EAEpC,KAAK,gCAAgC,EAErC,KAAK,uCAAuC,EAE5C,KAAK,mCAAmC,EACzC,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,MAAM;IAIf,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,IAAI;IAJd,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;gBAG3C,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,mBAAmB;IAGnC;;;;;;;;;;;;;OAaG;IACG,OAAO,IAAI,OAAO,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;IAKpE;;;;;;;;OAQG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAKpC;;;;;;;OAOG;IACG,gBAAgB,IAAI,OAAO,CAC/B,6BAA6B,CAAC,0BAA0B,CAAC,CAC1D;IAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAO/B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKnB;;;;;;;;;;;;;;;OAeG;IACG,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAO/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKnB;;;;;;;;;;;;;;;;;OAiBG;IACG,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAO/B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,cAAc,CAClB,KAAK,EAAE,+BAA+B,CAAC,OAAO,CAAC,GAC9C,OAAO,CAAC,OAAO,CAAC;IAKnB;;;;;;;;;;;;;;;;;OAiBG;IACG,qBAAqB,CACzB,KAAK,EAAE,+BAA+B,CAAC,OAAO,CAAC,EAC/C,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAO/B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKnB;;;;;;;;;;;;;;;;;;OAkBG;IACG,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAO/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,sBAAsB,CAC1B,KAAK,EAAE,uCAAuC,CAAC,OAAO,CAAC,GACtD,OAAO,CAAC,OAAO,CAAC;IAOnB;;;;;;;;;;;;;;;;;;;OAmBG;IACG,kBAAkB,CACtB,KAAK,EAAE,mCAAmC,CAAC,OAAO,CAAC,GAClD,OAAO,CAAC,OAAO,CAAC;IAKnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,SAAS,CAAC,QAAQ,EAAE,uBAAuB,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI;IAIvE,OAAO,CAAC,YAAY;CAQrB"}
|