@hypersoniclabs/helix-sdk 0.1.2 → 0.1.9
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 +859 -8
- package/dist/action-surface.d.ts +182 -0
- package/dist/action-surface.js +1032 -0
- package/dist/action-surface.js.map +1 -0
- package/dist/camera.d.ts +65 -1
- package/dist/camera.js +568 -0
- package/dist/camera.js.map +1 -1
- package/dist/dev-shell/criteria.d.ts +46 -0
- package/dist/dev-shell/criteria.js +98 -0
- package/dist/dev-shell/criteria.js.map +1 -0
- package/dist/dev-shell/index.d.ts +189 -0
- package/dist/dev-shell/index.js +287 -0
- package/dist/dev-shell/index.js.map +1 -0
- package/dist/dev-shell/keys.d.ts +14 -0
- package/dist/dev-shell/keys.js +78 -0
- package/dist/dev-shell/keys.js.map +1 -0
- package/dist/dev-shell/simulator.d.ts +436 -0
- package/dist/dev-shell/simulator.js +1634 -0
- package/dist/dev-shell/simulator.js.map +1 -0
- package/dist/dev-shell/state.d.ts +148 -0
- package/dist/dev-shell/state.js +196 -0
- package/dist/dev-shell/state.js.map +1 -0
- package/dist/device-definition-resolver.d.ts +34 -0
- package/dist/device-definition-resolver.js +172 -0
- package/dist/device-definition-resolver.js.map +1 -0
- package/dist/device-trial.d.ts +3 -0
- package/dist/device-trial.js +132 -0
- package/dist/device-trial.js.map +1 -0
- package/dist/devices.d.ts +228 -0
- package/dist/devices.js +198 -0
- package/dist/devices.js.map +1 -0
- package/dist/dreamerAudio.d.ts +126 -0
- package/dist/dreamerAudio.js +135 -0
- package/dist/dreamerAudio.js.map +1 -0
- package/dist/generated/runtime-contract.d.ts +15529 -0
- package/dist/generated/runtime-contract.js +20470 -0
- package/dist/generated/runtime-contract.js.map +1 -0
- package/dist/index.d.ts +272 -15
- package/dist/index.js +1401 -91
- package/dist/index.js.map +1 -1
- package/dist/interaction-mode.d.ts +172 -0
- package/dist/interaction-mode.js +553 -0
- package/dist/interaction-mode.js.map +1 -0
- package/dist/internal/avatar-pose.d.ts +25 -0
- package/dist/internal/avatar-pose.js +46 -0
- package/dist/internal/avatar-pose.js.map +1 -0
- package/dist/internal/keyed-collection.d.ts +2 -0
- package/dist/internal/keyed-collection.js +12 -0
- package/dist/internal/keyed-collection.js.map +1 -0
- package/dist/internal/vehicle-detach-action.d.ts +2 -0
- package/dist/internal/vehicle-detach-action.js +6 -0
- package/dist/internal/vehicle-detach-action.js.map +1 -0
- package/dist/matchmaking.d.ts +433 -0
- package/dist/matchmaking.js +1487 -0
- package/dist/matchmaking.js.map +1 -0
- package/dist/materials.d.ts +122 -0
- package/dist/materials.js +217 -0
- package/dist/materials.js.map +1 -0
- package/dist/multiplayer-accessors.d.ts +100 -0
- package/dist/multiplayer-accessors.js +200 -0
- package/dist/multiplayer-accessors.js.map +1 -0
- package/dist/multiplayer-contract/avatar-pose.d.ts +112 -0
- package/dist/multiplayer-contract/avatar-pose.js +250 -0
- package/dist/multiplayer-contract/avatar-pose.js.map +1 -0
- package/dist/multiplayer-contract/credential.d.ts +38 -0
- package/dist/multiplayer-contract/final-rest.d.ts +66 -0
- package/dist/multiplayer-contract/final-rest.js +38 -0
- package/dist/multiplayer-contract/final-rest.js.map +1 -0
- package/dist/multiplayer-contract/index.d.ts +11 -5
- package/dist/multiplayer-contract/index.js +16 -5
- package/dist/multiplayer-contract/index.js.map +1 -1
- package/dist/multiplayer-contract/messages.d.ts +461 -14
- package/dist/multiplayer-contract/messages.js +141 -15
- package/dist/multiplayer-contract/messages.js.map +1 -1
- package/dist/multiplayer-contract/room.d.ts +55 -4
- package/dist/multiplayer-contract/state.d.ts +181 -1
- package/dist/multiplayer-contract/state.js.map +1 -1
- package/dist/multiplayer-final-rest.d.ts +32 -0
- package/dist/multiplayer-final-rest.js +217 -0
- package/dist/multiplayer-final-rest.js.map +1 -0
- package/dist/multiplayer.d.ts +507 -16
- package/dist/multiplayer.js +2242 -73
- package/dist/multiplayer.js.map +1 -1
- package/dist/package.json +3 -0
- package/dist/protocol.d.ts +668 -5
- package/dist/protocol.js +101 -1
- package/dist/protocol.js.map +1 -1
- package/dist/runtime-contract/index.d.ts +15 -0
- package/dist/runtime-contract/index.js +12 -0
- package/dist/runtime-contract/index.js.map +1 -0
- package/dist/server-clock.d.ts +25 -0
- package/dist/server-clock.js +88 -0
- package/dist/server-clock.js.map +1 -0
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/dist/universal-vehicles.d.ts +111 -0
- package/dist/universal-vehicles.js +2 -0
- package/dist/universal-vehicles.js.map +1 -0
- package/dist/vault.d.ts +562 -0
- package/dist/vault.js +365 -0
- package/dist/vault.js.map +1 -0
- package/dist/vehicle-specialty-placement.d.ts +28 -0
- package/dist/vehicle-specialty-placement.js +154 -0
- package/dist/vehicle-specialty-placement.js.map +1 -0
- package/dist/vehicle-specialty-transport.d.ts +78 -0
- package/dist/vehicle-specialty-transport.js +183 -0
- package/dist/vehicle-specialty-transport.js.map +1 -0
- package/dist/voice.d.ts +229 -0
- package/dist/voice.js +1348 -0
- package/dist/voice.js.map +1 -0
- package/generated/runtime-contract/helix-runtime-contract.json +13332 -0
- package/generated/runtime-contract/known-answer.json +20471 -0
- package/generated/runtime-contract/known-answer.schema.json +630 -0
- package/generated/runtime-contract/runtime-contract.schema.json +607 -0
- package/generated/runtime-contract/unreal/HelixRuntimeContract.generated.h +908 -0
- package/package.json +32 -6
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
// The Data Store KEY POLICY as it applies to a WORLD SESSION — the writer class a shell always is.
|
|
2
|
+
//
|
|
3
|
+
// SYNC OBLIGATION: a port of helix-backend-api/src/data-store/data-store-keys.ts (the session branch of
|
|
4
|
+
// checkDataStoreWrite + checkDataStoreRead). The rule strings ARE the errorCodes a world branches on
|
|
5
|
+
// (the shell forwards a refusal's `rule` as helix:response.errorCode), so they must match byte for byte.
|
|
6
|
+
// A simulator more permissive than production manufactures false positives: a world that writes
|
|
7
|
+
// `player:{id}:score` locally would 403 the moment it ships.
|
|
8
|
+
const PLATFORM_PREFIX = 'helix:';
|
|
9
|
+
const RESERVED_PREFIXES = [
|
|
10
|
+
{ prefix: 'leaderboard:', owner: 'leaderboards', writtenBy: 'POST /api/v1/leaderboard/{board}/score' },
|
|
11
|
+
{ prefix: 'mail:', owner: 'player mailboxes' },
|
|
12
|
+
{ prefix: 'trade:', owner: 'player-to-player exchange' },
|
|
13
|
+
{ prefix: 'guild:', owner: 'group-owned shared state' },
|
|
14
|
+
{ prefix: 'party:', owner: 'group-owned shared state' },
|
|
15
|
+
{ prefix: 'index:', owner: 'queryable views over the store' },
|
|
16
|
+
{ prefix: 'log:', owner: "the KV layer's append-log entries" },
|
|
17
|
+
];
|
|
18
|
+
/** The one key a player's own session may write. */
|
|
19
|
+
export const playerSaveKey = (sub) => `player:${sub}`;
|
|
20
|
+
export const isPlatformKey = (key) => key.toLowerCase().startsWith(PLATFORM_PREFIX);
|
|
21
|
+
const isUnder = (key, prefix) => key === prefix || key.startsWith(prefix.endsWith(':') ? prefix : `${prefix}:`);
|
|
22
|
+
/** Reads are world-open except the platform's own namespace (it holds every player's entitlement doc). */
|
|
23
|
+
export function checkDevShellRead(key) {
|
|
24
|
+
if (isPlatformKey(key)) {
|
|
25
|
+
return {
|
|
26
|
+
allowed: false,
|
|
27
|
+
rule: 'platform-reserved',
|
|
28
|
+
message: `The "${PLATFORM_PREFIX}" prefix is platform state and is not readable through this API — entitlements are served by /api/v1/iwp/entitlements.`,
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
return { allowed: true };
|
|
32
|
+
}
|
|
33
|
+
// Namespace reservations match case-INSENSITIVELY (`HELIX:x` is `helix:x`), so a namespace cannot be
|
|
34
|
+
// squatted by shouting it; the own-key rule stays byte-exact against the session's subject.
|
|
35
|
+
export function checkDevShellWrite(key, sub) {
|
|
36
|
+
const namespaceKey = key.toLowerCase();
|
|
37
|
+
if (namespaceKey.startsWith(PLATFORM_PREFIX)) {
|
|
38
|
+
return {
|
|
39
|
+
allowed: false,
|
|
40
|
+
rule: 'platform-reserved',
|
|
41
|
+
message: `The "${PLATFORM_PREFIX}" prefix is written by the HELIX platform itself and is not writable through this API.`,
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
for (const { prefix, owner, writtenBy } of RESERVED_PREFIXES) {
|
|
45
|
+
if (isUnder(namespaceKey, prefix)) {
|
|
46
|
+
return {
|
|
47
|
+
allowed: false,
|
|
48
|
+
rule: 'prefix-reserved',
|
|
49
|
+
message: writtenBy
|
|
50
|
+
? `The "${prefix}" namespace is reserved for ${owner}: write it through ${writtenBy}, not this API.`
|
|
51
|
+
: `The "${prefix}" namespace is reserved for ${owner} and has no writer yet.`,
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
const own = playerSaveKey(sub);
|
|
56
|
+
if (key === own)
|
|
57
|
+
return { allowed: true };
|
|
58
|
+
if (key.startsWith(`${own}:`)) {
|
|
59
|
+
return {
|
|
60
|
+
allowed: false,
|
|
61
|
+
rule: 'session-sub-key',
|
|
62
|
+
message: `A world may write only the exact key "${own}" from a player's session — sub-keys under it are server-written. Keep the whole save in one JSON document at "${own}".`,
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
if (isUnder(key, 'player')) {
|
|
66
|
+
return {
|
|
67
|
+
allowed: false,
|
|
68
|
+
rule: 'session-foreign-key',
|
|
69
|
+
message: `A player's session may write only its own key "${own}", never another player's.`,
|
|
70
|
+
};
|
|
71
|
+
}
|
|
72
|
+
return {
|
|
73
|
+
allowed: false,
|
|
74
|
+
rule: 'session-server-key',
|
|
75
|
+
message: `"${key}" is a server-owned key: world-global and room state are written by the game server, not by a player's session. A session may write only "${own}".`,
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
//# sourceMappingURL=keys.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/dev-shell/keys.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,436 @@
|
|
|
1
|
+
import type { Balance, Entitlements, HelixEvent, HelixRequestMethod, LeaderboardOrder } from '../protocol.js';
|
|
2
|
+
import { type DevShellProductsSeed, type DevShellState } from './state.js';
|
|
3
|
+
/** Stamped on every simulated answer. Never call this mode "test" — Roblox's test mode costs real money. */
|
|
4
|
+
export declare const DEV_SHELL_LOG_PREFIX = "[helix dev \u00B7 SIMULATED]";
|
|
5
|
+
/**
|
|
6
|
+
* The SHELL lane's real limits, with their production sources. Enforcing them is what keeps a local pass
|
|
7
|
+
* meaningful — and matching the loud shapes exercises a world's error paths for free.
|
|
8
|
+
*/
|
|
9
|
+
export declare const DEV_SHELL_CAPS: {
|
|
10
|
+
/** data-store.constants.ts DATA_STORE_USER_WRITE_LIMIT_PER_WINDOW. */
|
|
11
|
+
readonly playerWritesPerMinute: 30;
|
|
12
|
+
/** The free KvStoragePlan's writeOpsPerMinute (DATA_STORE_WRITE_LIMIT_PER_WINDOW is its fallback). */
|
|
13
|
+
readonly worldWritesPerMinute: 600;
|
|
14
|
+
/** entitlements.service.ts CONSUME_RATE_MAX. */
|
|
15
|
+
readonly consumesPerMinute: 120;
|
|
16
|
+
readonly windowMs: 60000;
|
|
17
|
+
/** DATA_STORE_MAX_VALUE_BYTES. */
|
|
18
|
+
readonly maxValueBytes: number;
|
|
19
|
+
/** DATA_STORE_MAX_KEYS / DATA_STORE_MAX_TOTAL_BYTES. */
|
|
20
|
+
readonly maxKeys: 50000;
|
|
21
|
+
readonly maxTotalBytes: number;
|
|
22
|
+
/** DATA_STORE_LIST_MAX_LIMIT. */
|
|
23
|
+
readonly listPageMax: 100;
|
|
24
|
+
/** LeaderboardController.DEFAULT_LIMIT, and the SDK's own MAX_LEADERBOARD_LIMIT. */
|
|
25
|
+
readonly leaderboardPageDefault: 25;
|
|
26
|
+
readonly leaderboardPageMax: 100;
|
|
27
|
+
/** DATA_STORE_SESSION_BOARD_CAP — boards a session may lazily create. */
|
|
28
|
+
readonly sessionBoardCap: 8;
|
|
29
|
+
/** LEADERBOARD_DEFAULT_SIZE — entries a board keeps. */
|
|
30
|
+
readonly boardSize: 100;
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* How long a real-flow poke (a data-store write, a purchase settle) waits before criteria re-evaluate —
|
|
34
|
+
* the backend's ACHIEVEMENT_CRITERIA_DEBOUNCE_MS default. Debug-menu evidence evaluates immediately
|
|
35
|
+
* (the local analog of the admin sweep). Local unlocks are therefore never SLOWER than production's.
|
|
36
|
+
*/
|
|
37
|
+
export declare const DEV_SHELL_ACHIEVEMENT_DEBOUNCE_MS = 3000;
|
|
38
|
+
/** What the host page hears when a simulated unlock happens. Worlds hear nothing pushed — the protocol
|
|
39
|
+
* has no achievements event, so a world observes an unlock by re-polling, exactly as in production. */
|
|
40
|
+
export type DevShellEarnedAchievement = {
|
|
41
|
+
key: string;
|
|
42
|
+
name: string;
|
|
43
|
+
points: number;
|
|
44
|
+
hidden: boolean;
|
|
45
|
+
via: string;
|
|
46
|
+
};
|
|
47
|
+
/** One row of the debug menu's progress print: how far each registered achievement is from unlocking. */
|
|
48
|
+
export type DevShellAchievementProgress = {
|
|
49
|
+
key: string;
|
|
50
|
+
name: string;
|
|
51
|
+
earned: boolean;
|
|
52
|
+
unlockMode?: string;
|
|
53
|
+
criteria: string | null;
|
|
54
|
+
measured: number | null;
|
|
55
|
+
};
|
|
56
|
+
/** What the host's simulated confirm popup shows — the real shell's dialog fields for one attempt. */
|
|
57
|
+
export type DevShellPurchaseConfirm = {
|
|
58
|
+
ref: string;
|
|
59
|
+
idempotencyKey: string;
|
|
60
|
+
title: string;
|
|
61
|
+
priceLix: number;
|
|
62
|
+
isFree: boolean;
|
|
63
|
+
balanceLix: number;
|
|
64
|
+
balanceAfterLix: number;
|
|
65
|
+
};
|
|
66
|
+
/** How the next purchase fails while failure injection is armed. `Pending` throws and leaves the row. */
|
|
67
|
+
export type DevShellPurchaseFailureMode = 'InsufficientFunds' | 'PriceChanged' | 'Pending';
|
|
68
|
+
export declare const DEV_SHELL_PURCHASE_FAILURE_MODES: readonly DevShellPurchaseFailureMode[];
|
|
69
|
+
/** One answer to one helix:request — mapped straight onto the helix:response envelope. */
|
|
70
|
+
export type DevShellAnswer = {
|
|
71
|
+
ok: true;
|
|
72
|
+
result?: unknown;
|
|
73
|
+
} | {
|
|
74
|
+
ok: false;
|
|
75
|
+
error: string;
|
|
76
|
+
errorCode?: string;
|
|
77
|
+
};
|
|
78
|
+
export type DevShellLogger = (message: string, detail?: unknown) => void;
|
|
79
|
+
/** One declared room type, the two manifest fields the join API reads (`multiplayer.roomTypes.<name>`). */
|
|
80
|
+
export type DevShellRoomTypeSeed = {
|
|
81
|
+
access: 'open' | 'ticketed';
|
|
82
|
+
maxPlayers: number;
|
|
83
|
+
};
|
|
84
|
+
/** The world's declared room types, keyed by name. Mirrors the manifest block; the default type is implicit. */
|
|
85
|
+
export type DevShellRoomTypesSeed = Record<string, DevShellRoomTypeSeed>;
|
|
86
|
+
/** The manifest validator's room-type name grammar (`default` is reserved, at most 8 types). */
|
|
87
|
+
export declare const DEV_SHELL_ROOM_TYPE_NAME_PATTERN: RegExp;
|
|
88
|
+
export declare const DEV_SHELL_ROOM_TYPES_MAX = 8;
|
|
89
|
+
/**
|
|
90
|
+
* How long a simulated ticket stays redeemable. The contract pins the ticket CREDENTIAL at 60 s; the ticket
|
|
91
|
+
* row's own lifetime is the backend's choice, so this is a stand-in, overridable per ticket (`ttlMs`).
|
|
92
|
+
*/
|
|
93
|
+
export declare const DEV_SHELL_ROOM_TICKET_TTL_MS = 60000;
|
|
94
|
+
/** The `helix:room-ticket` payload, with `expiresAt` in epoch milliseconds (what room.onTicket hands a world). */
|
|
95
|
+
export type DevShellRoomTicket = {
|
|
96
|
+
roomType: string;
|
|
97
|
+
ticketId: string;
|
|
98
|
+
instanceId: string;
|
|
99
|
+
expiresAt: number;
|
|
100
|
+
};
|
|
101
|
+
/** The join request body: none / `{}` = default type, `{ roomType }` = an open type, `{ ticket }` = redeem. */
|
|
102
|
+
export type DevShellJoinBody = {
|
|
103
|
+
roomType?: string;
|
|
104
|
+
ticket?: string;
|
|
105
|
+
};
|
|
106
|
+
/**
|
|
107
|
+
* The simulated join answer. On success it carries exactly the two optional JoinResponse fields the SDK
|
|
108
|
+
* forwards as join options — and nothing a client could connect with: no wsUrl, no credential.
|
|
109
|
+
*/
|
|
110
|
+
export type DevShellJoinAnswer = {
|
|
111
|
+
ok: true;
|
|
112
|
+
status: 200;
|
|
113
|
+
roomType?: string;
|
|
114
|
+
instanceKey?: string;
|
|
115
|
+
} | {
|
|
116
|
+
ok: false;
|
|
117
|
+
status: 403 | 404 | 410;
|
|
118
|
+
body: DevShellRoomRefusalBody;
|
|
119
|
+
};
|
|
120
|
+
export type DevShellRejoinAnswer = {
|
|
121
|
+
ok: true;
|
|
122
|
+
status: 200;
|
|
123
|
+
ticket: DevShellRoomTicket;
|
|
124
|
+
} | {
|
|
125
|
+
ok: false;
|
|
126
|
+
status: 404 | 410;
|
|
127
|
+
body: DevShellRoomRefusalBody;
|
|
128
|
+
};
|
|
129
|
+
/**
|
|
130
|
+
* The backend's refusal `code`s for the room-types routes, with the status each is served under. A client
|
|
131
|
+
* branches on the CODE: two of the 410s and two of the 404s mean different things, and an unrelated 404
|
|
132
|
+
* (world not found) shares a status with all of them.
|
|
133
|
+
*/
|
|
134
|
+
export declare const DEV_SHELL_ROOM_REFUSALS: {
|
|
135
|
+
readonly 'unknown-room-type': 404;
|
|
136
|
+
readonly 'ticket-required': 403;
|
|
137
|
+
readonly 'unknown-room-ticket': 404;
|
|
138
|
+
readonly 'room-ticket-expired': 410;
|
|
139
|
+
readonly 'room-ticket-used': 410;
|
|
140
|
+
readonly 'room-instance-closed': 410;
|
|
141
|
+
readonly 'unknown-room-instance': 404;
|
|
142
|
+
};
|
|
143
|
+
export type DevShellRoomRefusalCode = keyof typeof DEV_SHELL_ROOM_REFUSALS;
|
|
144
|
+
/** The error body the backend serves for a refused room-types request. */
|
|
145
|
+
export type DevShellRoomRefusalBody = {
|
|
146
|
+
statusCode: number;
|
|
147
|
+
code: DevShellRoomRefusalCode;
|
|
148
|
+
message: string;
|
|
149
|
+
};
|
|
150
|
+
/** One declared queue, the manifest fields the routes read (`matchmaking.queues.<id>`). */
|
|
151
|
+
export type DevShellQueueSeed = {
|
|
152
|
+
roomType: string;
|
|
153
|
+
teams?: number;
|
|
154
|
+
teamSize?: number;
|
|
155
|
+
};
|
|
156
|
+
/** The world's declared queues, keyed by id. Omitted / empty = matchmaking is not enabled for this world. */
|
|
157
|
+
export type DevShellQueuesSeed = Record<string, DevShellQueueSeed>;
|
|
158
|
+
export declare const DEV_SHELL_QUEUE_ID_PATTERN: RegExp;
|
|
159
|
+
export declare const DEV_SHELL_QUEUES_MAX = 16;
|
|
160
|
+
/** The platform's party size cap. */
|
|
161
|
+
export declare const DEV_SHELL_PARTY_MAX_SIZE = 12;
|
|
162
|
+
/** Pending invites one party may have out at a time. */
|
|
163
|
+
export declare const DEV_SHELL_PARTY_PENDING_INVITES_MAX = 10;
|
|
164
|
+
/** How long a party invite stays answerable. */
|
|
165
|
+
export declare const DEV_SHELL_PARTY_INVITE_TTL_MS: number;
|
|
166
|
+
/** What a simulated v1 route answers: the HTTP status and the JSON body (`undefined` for a 204). */
|
|
167
|
+
export type DevShellPlatformAnswer = {
|
|
168
|
+
status: number;
|
|
169
|
+
body?: unknown;
|
|
170
|
+
};
|
|
171
|
+
export type DevShellPartyMember = {
|
|
172
|
+
userId: string;
|
|
173
|
+
displayName: string;
|
|
174
|
+
};
|
|
175
|
+
export type DevShellParty = {
|
|
176
|
+
id: string;
|
|
177
|
+
leaderId: string;
|
|
178
|
+
maxSize: number;
|
|
179
|
+
members: DevShellPartyMember[];
|
|
180
|
+
};
|
|
181
|
+
/** A party join code (`expiresAt` is ISO-8601 on the wire). */
|
|
182
|
+
export type DevShellPartyCode = {
|
|
183
|
+
code: string;
|
|
184
|
+
expiresAt: string;
|
|
185
|
+
};
|
|
186
|
+
/** How long a simulated join code lasts. */
|
|
187
|
+
export declare const DEV_SHELL_PARTY_CODE_TTL_MS: number;
|
|
188
|
+
/** An incoming invite, as `GET /parties/current` lists it (`expiresAt` is ISO-8601 on the wire). */
|
|
189
|
+
export type DevShellPartyInvite = {
|
|
190
|
+
id: string;
|
|
191
|
+
partyId: string;
|
|
192
|
+
from: DevShellPartyMember;
|
|
193
|
+
expiresAt: string;
|
|
194
|
+
};
|
|
195
|
+
export type DevShellSimulatorOptions = {
|
|
196
|
+
state: DevShellState;
|
|
197
|
+
products?: DevShellProductsSeed;
|
|
198
|
+
/** The world's declared room types (the manifest's `multiplayer.roomTypes`). Omitted = none declared. */
|
|
199
|
+
roomTypes?: DevShellRoomTypesSeed;
|
|
200
|
+
/** The world's declared matchmaking queues (the manifest's `matchmaking.queues`). Omitted = none declared. */
|
|
201
|
+
queues?: DevShellQueuesSeed;
|
|
202
|
+
/** Pushes a helix:event to the world. */
|
|
203
|
+
emit: (event: HelixEvent, data?: unknown) => void;
|
|
204
|
+
log: DevShellLogger;
|
|
205
|
+
onStateChange?: (state: DevShellState) => void;
|
|
206
|
+
/** Host-page unlock feedback (toast). Never forwarded to the world. */
|
|
207
|
+
onAchievementEarned?: (achievement: DevShellEarnedAchievement) => void;
|
|
208
|
+
/** Real-flow poke delay. Default DEV_SHELL_ACHIEVEMENT_DEBOUNCE_MS; 0 evaluates synchronously (specs). */
|
|
209
|
+
achievementDebounceMs?: number;
|
|
210
|
+
};
|
|
211
|
+
/** The 21 methods `helix dev` answers from simulated state. */
|
|
212
|
+
export declare const DEV_SHELL_SIMULATED_METHODS: readonly HelixRequestMethod[];
|
|
213
|
+
/** The 13 methods `helix dev` refuses — they need a real platform surface, asset pipeline, camera rig,
|
|
214
|
+
* or (the quick-slot six) the platform's one-place state machine and the creator's own owned instances. */
|
|
215
|
+
export declare const DEV_SHELL_REFUSED_METHODS: readonly HelixRequestMethod[];
|
|
216
|
+
export declare class DevShellSimulator {
|
|
217
|
+
private readonly options;
|
|
218
|
+
private state;
|
|
219
|
+
private products;
|
|
220
|
+
private listings;
|
|
221
|
+
private playerWrites;
|
|
222
|
+
private worldWrites;
|
|
223
|
+
private consumes;
|
|
224
|
+
private consumeOps;
|
|
225
|
+
private purchaseFailure;
|
|
226
|
+
private forceSaveFailure;
|
|
227
|
+
private achievementPokeTimer;
|
|
228
|
+
private roomTypes;
|
|
229
|
+
private roomInstances;
|
|
230
|
+
private roomTickets;
|
|
231
|
+
private roomSerial;
|
|
232
|
+
private queues;
|
|
233
|
+
private queueTicket;
|
|
234
|
+
private party;
|
|
235
|
+
private partyInvites;
|
|
236
|
+
private outgoingInvites;
|
|
237
|
+
private partyCode;
|
|
238
|
+
private queueEnded;
|
|
239
|
+
private memberWithMatch;
|
|
240
|
+
private foreignCodes;
|
|
241
|
+
private socialSerial;
|
|
242
|
+
constructor(options: DevShellSimulatorOptions);
|
|
243
|
+
/** Route one helix:request. Never throws — a thrown handler would strand the world's promise. */
|
|
244
|
+
handle(method: HelixRequestMethod, payload: unknown): DevShellAnswer;
|
|
245
|
+
snapshot(): DevShellState;
|
|
246
|
+
replaceState(state: DevShellState): void;
|
|
247
|
+
setProducts(seed: DevShellProductsSeed | undefined): void;
|
|
248
|
+
/** Cancel a pending debounced evaluation — the dispose() seam. A cancelled poke heals on the next one. */
|
|
249
|
+
cancelPendingAchievementPoke(): void;
|
|
250
|
+
private log;
|
|
251
|
+
private touched;
|
|
252
|
+
private emit;
|
|
253
|
+
private charge;
|
|
254
|
+
private rateLimited;
|
|
255
|
+
getBalance(): DevShellAnswer;
|
|
256
|
+
getListings(query: Record<string, unknown>): DevShellAnswer;
|
|
257
|
+
/**
|
|
258
|
+
* What the host's confirm popup should show for this attempt, or null when production would not pop
|
|
259
|
+
* one either: a missing ref/key (the request will refuse), an unknown ref (ProductNotFound is the
|
|
260
|
+
* world's own bug), or a settled row (the answer is an idempotent replay, no new confirmation).
|
|
261
|
+
*/
|
|
262
|
+
purchaseConfirmContext(ref: string, idempotencyKey: string): DevShellPurchaseConfirm | null;
|
|
263
|
+
/**
|
|
264
|
+
* The popup's Cancel: nothing was charged, nothing is recorded — production's cancel-before-charge
|
|
265
|
+
* leaves no backend row, so a retried attempt (same key) confirms again instead of replaying Cancelled.
|
|
266
|
+
*/
|
|
267
|
+
cancelPurchase(ref: string): DevShellAnswer;
|
|
268
|
+
/**
|
|
269
|
+
* Settle a purchase against simulated state. NEVER mints a receipt: settlePurchaseResult forwards on
|
|
270
|
+
* receipt PRESENCE (index.ts:1156-1162) and a junk receipt reaching a real room kicks the buyer.
|
|
271
|
+
*/
|
|
272
|
+
purchase(ref: string, idempotencyKey: string): DevShellAnswer;
|
|
273
|
+
private injectedPurchaseFailure;
|
|
274
|
+
private recordPurchase;
|
|
275
|
+
getPurchase(idempotencyKey: string, ref?: string): DevShellAnswer;
|
|
276
|
+
getPurchaseContext(ref: string): DevShellAnswer;
|
|
277
|
+
getEntitlements(): DevShellAnswer;
|
|
278
|
+
/** Atomic floor-at-zero spend, idempotent per opId — the same shape the backend's shaped op returns. */
|
|
279
|
+
consumeEntitlement(code: string, amount: number, opId: string): DevShellAnswer;
|
|
280
|
+
hasItem(itemId: string): DevShellAnswer;
|
|
281
|
+
getQuantity(itemId: string): DevShellAnswer;
|
|
282
|
+
getMyItems(): DevShellAnswer;
|
|
283
|
+
equipItem(itemId: string): DevShellAnswer;
|
|
284
|
+
dataStoreGet(key: string): DevShellAnswer;
|
|
285
|
+
dataStoreGetEntry(key: string): DevShellAnswer;
|
|
286
|
+
dataStoreSet(key: string, value: unknown, expectedVersion?: number): DevShellAnswer;
|
|
287
|
+
dataStoreDelete(key: string, expectedVersion?: number): DevShellAnswer;
|
|
288
|
+
dataStoreList(payload: Record<string, unknown>): DevShellAnswer;
|
|
289
|
+
private storedBytes;
|
|
290
|
+
private chargePlayerWrite;
|
|
291
|
+
private chargeWorldWrite;
|
|
292
|
+
private refuseWrite;
|
|
293
|
+
private versionConflict;
|
|
294
|
+
leaderboardSubmit(board: string, score: number, order?: LeaderboardOrder): DevShellAnswer;
|
|
295
|
+
leaderboardTop(board: string, limit?: number, order?: LeaderboardOrder): DevShellAnswer;
|
|
296
|
+
achievementsList(): DevShellAnswer;
|
|
297
|
+
achievementsMine(): DevShellAnswer;
|
|
298
|
+
/**
|
|
299
|
+
* The player's equipped emote wheel — a STUB, and one that says so on every petal.
|
|
300
|
+
*
|
|
301
|
+
* There is no account here to read a wheel from, so the only two honest answers were a refusal or a
|
|
302
|
+
* loadout that cannot be mistaken for a real one. A refusal is what this used to be by omission, and
|
|
303
|
+
* it was the wrong one: the engine's native avatar runtime reports an unanswered read as "Couldn't
|
|
304
|
+
* load your emotes", so `helix dev` — the platform's own local command — could not show a creator
|
|
305
|
+
* the wheel at all.
|
|
306
|
+
*
|
|
307
|
+
* Read from state rather than returned as a constant so a creator can point it at their own clips by
|
|
308
|
+
* editing .helix/dev-state.json, and so `--reset` restores the stub. An older state file has no
|
|
309
|
+
* `emotes` field, hence the fallback.
|
|
310
|
+
*/
|
|
311
|
+
emotesGetEquipped(): DevShellAnswer;
|
|
312
|
+
private summaryOf;
|
|
313
|
+
private pokeAchievements;
|
|
314
|
+
private evaluateAchievements;
|
|
315
|
+
private criteriaEvidence;
|
|
316
|
+
/** Append to earned + notify the host. The caller batches touched(); no world event exists to push. */
|
|
317
|
+
private earnAchievement;
|
|
318
|
+
grantAllEntitlements(): void;
|
|
319
|
+
grantEntitlement(ref: string): void;
|
|
320
|
+
removeEntitlement(ref: string): void;
|
|
321
|
+
entitlementsSnapshot(): Entitlements;
|
|
322
|
+
setPurchasesAlwaysFail(mode: DevShellPurchaseFailureMode | 'off'): void;
|
|
323
|
+
/** The debug-menu button: off → InsufficientFunds → PriceChanged → Pending → off. */
|
|
324
|
+
cyclePurchasesAlwaysFail(): DevShellPurchaseFailureMode | 'off';
|
|
325
|
+
purchasesAlwaysFail(): DevShellPurchaseFailureMode | 'off';
|
|
326
|
+
resetPlayerDocument(): void;
|
|
327
|
+
setForceSaveFailure(on: boolean): void;
|
|
328
|
+
forceSaveFailureOn(): boolean;
|
|
329
|
+
/** Fill the consume window so the next consume hits the real 120/min refusal. */
|
|
330
|
+
exhaustConsumeFence(): void;
|
|
331
|
+
setWallet(wallet: Partial<Balance>): void;
|
|
332
|
+
/** The room/platform award lanes' stand-in. Refuses a key outside the registry, as the backend would. */
|
|
333
|
+
awardAchievement(key: string): boolean;
|
|
334
|
+
/** Local-only re-test convenience: production never revokes. Finer-grained than --reset. */
|
|
335
|
+
resetAchievements(): void;
|
|
336
|
+
/** Playtime evidence — the shell page ticks this while open; the debug button adds minutes at once. */
|
|
337
|
+
addPlaytime(seconds: number): void;
|
|
338
|
+
/** Analytics evidence. Counts only — analytics.track never reaches a shell, so nothing flows here live. */
|
|
339
|
+
bumpAnalyticsEvent(eventName: string, count?: number): void;
|
|
340
|
+
/** The room's flush, by hand: writes the { v, vars } envelope a real room persists, then pokes. */
|
|
341
|
+
setMpPlayerVar(field: string, value: number): void;
|
|
342
|
+
/**
|
|
343
|
+
* The room's leaderboard submit, by hand: declared boards are written by room rules in production, so
|
|
344
|
+
* with no room a board a world only READS stays empty forever. Seeds any subject (default the player),
|
|
345
|
+
* skips the session fences (the room lane has its own, unreachable here), and keeps board shape rules:
|
|
346
|
+
* creation fixes the order, best-per-subject wins, sorted and trimmed to size.
|
|
347
|
+
*/
|
|
348
|
+
seedLeaderboardScore(board: string, score: number, opts?: {
|
|
349
|
+
subject?: string;
|
|
350
|
+
displayName?: string;
|
|
351
|
+
order?: LeaderboardOrder;
|
|
352
|
+
}): void;
|
|
353
|
+
/**
|
|
354
|
+
* The server's hand on the data store: write ANY key, including the ones a session may not touch
|
|
355
|
+
* (world-global, mp:world:*, the reserved namespaces) — in production those are room/backend-written,
|
|
356
|
+
* so a world that only READS them sees null locally until something stands in for the writer. Bypasses
|
|
357
|
+
* the session key policy and the write fences deliberately; criteria evidence re-evaluates at once.
|
|
358
|
+
*/
|
|
359
|
+
seedDocument(key: string, value: unknown): void;
|
|
360
|
+
/** The debug menu's progress print: measured-vs-target for every registered achievement. */
|
|
361
|
+
achievementsProgress(): DevShellAchievementProgress[];
|
|
362
|
+
private applyProduct;
|
|
363
|
+
private afterDebugGrant;
|
|
364
|
+
private titleOf;
|
|
365
|
+
/** Replace the declared room types. A name the manifest validator would reject is ignored, loudly. */
|
|
366
|
+
setRoomTypes(seed: DevShellRoomTypesSeed | undefined): void;
|
|
367
|
+
/**
|
|
368
|
+
* `POST /instant-worlds/:worldId/join`, decided but not served: the body table of the join API.
|
|
369
|
+
* No body / `{}` is the default room. With NO room types declared every typed body is `unknown-room-type`,
|
|
370
|
+
* which is also what the backend answers while its ROOM_TYPES_ENABLED flag is off.
|
|
371
|
+
*/
|
|
372
|
+
joinRoom(body?: DevShellJoinBody): DevShellJoinAnswer;
|
|
373
|
+
/**
|
|
374
|
+
* The room's `openRoom` effect, by hand: open (or reuse) an instance of a TICKETED type and mint this
|
|
375
|
+
* player's ticket to it — the `helix:room-ticket` payload a room would send. Null when the type is not
|
|
376
|
+
* declared ticketed, which is the same condition under which the real effect is a publish-time error.
|
|
377
|
+
*/
|
|
378
|
+
issueRoomTicket(roomType: string, opts?: {
|
|
379
|
+
instanceId?: string;
|
|
380
|
+
ttlMs?: number;
|
|
381
|
+
}): DevShellRoomTicket | null;
|
|
382
|
+
/**
|
|
383
|
+
* `POST …/room-instances/:instanceId/rejoin`: a fresh ticket for a player whose first one is spent, while
|
|
384
|
+
* the instance is open and they hold a ticket row. 404 = no such instance for this player; 410 = closed.
|
|
385
|
+
*/
|
|
386
|
+
rejoinRoomInstance(instanceId: string): DevShellRejoinAnswer;
|
|
387
|
+
/** The ticketed room disposing (it closes its backend instance). Idempotent; false = no such instance. */
|
|
388
|
+
closeRoomInstance(instanceId: string): boolean;
|
|
389
|
+
/** Replace the declared queues. One the manifest validator would reject is ignored, loudly. */
|
|
390
|
+
setQueues(seed: DevShellQueuesSeed | undefined): void;
|
|
391
|
+
/**
|
|
392
|
+
* The v1 matchmaking / party route table, decided but not served. `path` is the request path with or
|
|
393
|
+
* without the `/api/v1` prefix; the world id segment is not checked (there is one world here). The caller
|
|
394
|
+
* is always the simulated player, who is an account — the guest refusals are the SDK's to make.
|
|
395
|
+
* With NO queues declared every queue route answers 404 `matchmaking-disabled`, which is also what the
|
|
396
|
+
* backend answers while its MATCHMAKING_ENABLED flag is off.
|
|
397
|
+
*/
|
|
398
|
+
platformRequest(method: string, path: string, body?: unknown): DevShellPlatformAnswer;
|
|
399
|
+
/**
|
|
400
|
+
* The debug hand standing in for the matcher: the waiting ticket's match forms. Opens an instance of the
|
|
401
|
+
* queue's ticketed room type and issues this player's room ticket from the simulated room-types table —
|
|
402
|
+
* the ticket `GET …/queues/tickets/current` then reports as `matched`, redeemable with `joinRoom({ ticket })`.
|
|
403
|
+
* Null when there is no waiting ticket.
|
|
404
|
+
*/
|
|
405
|
+
formMatch(opts?: {
|
|
406
|
+
ttlMs?: number;
|
|
407
|
+
}): DevShellRoomTicket | null;
|
|
408
|
+
/** Debug hand: another player invites the simulated player to their party. Shows up in `GET /parties/current`. */
|
|
409
|
+
receivePartyInvite(from?: Partial<DevShellPartyMember>, opts?: {
|
|
410
|
+
ttlMs?: number;
|
|
411
|
+
}): DevShellPartyInvite;
|
|
412
|
+
/** Debug hand: the player an invite was sent to accepts it and joins the party. False = no such pending invite, or no room. */
|
|
413
|
+
acceptPartyInvite(inviteId: string, displayName?: string): boolean;
|
|
414
|
+
/**
|
|
415
|
+
* Debug hand: the waiting ticket ends the way the platform would end it — `timeout`, `heartbeat-lapsed`,
|
|
416
|
+
* `member-absent`, `build-changed`, `queue-removed`, or `replaced` (the player queued in another world).
|
|
417
|
+
* `GET …/queues/tickets/current` then answers `none` with `ended` for 60 s. False when nothing is waiting.
|
|
418
|
+
*/
|
|
419
|
+
endQueueTicket(reason: string): boolean;
|
|
420
|
+
/** Debug hand: a party member holds a match that still stands (null clears it). Enqueue is then refused naming them. */
|
|
421
|
+
setPartyMemberMatch(userId: string | null): void;
|
|
422
|
+
private closeQueueTicket;
|
|
423
|
+
/** Debug hand: another player's party has a join code. Returns it, for `POST /parties/join`. */
|
|
424
|
+
openPartyCode(host?: Partial<DevShellPartyMember>, opts?: {
|
|
425
|
+
ttlMs?: number;
|
|
426
|
+
}): DevShellPartyCode;
|
|
427
|
+
/** Debug hand: another player joins the simulated player's party with its code. False = no such live code, or no room. */
|
|
428
|
+
usePartyCode(code: string, member?: Partial<DevShellPartyMember>): boolean;
|
|
429
|
+
private partyBody;
|
|
430
|
+
private moveToParty;
|
|
431
|
+
private currentQueueTicket;
|
|
432
|
+
private queuedPlayers;
|
|
433
|
+
private selfMember;
|
|
434
|
+
private partyChanged;
|
|
435
|
+
private mintRoomTicket;
|
|
436
|
+
}
|