@rbxts/scribe 2.6.0 → 2.7.0

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/types/api.d.ts CHANGED
@@ -18,7 +18,8 @@ export interface LeaderboardConfig<T = unknown> {
18
18
  export interface ProductConfig<T = unknown> {
19
19
  Id: number;
20
20
  Category?: string;
21
- Grant?: (this: void, data: PlayerData<T>) => void;
21
+ /** Runs on the buyer's data, or the recipient's for gifts. */
22
+ Grant?: (this: void, data: PlayerData<T>, player: Player) => void;
22
23
  Grants?: string;
23
24
  PaidRandom?: boolean;
24
25
  }
@@ -27,7 +28,8 @@ export interface PurchaseSpec<T = unknown> {
27
28
  Cost: { Path: NumericPaths<T, true>; Amount: BigOperand };
28
29
  Category?: string;
29
30
  ItemId: string;
30
- Grant?: (this: void, data: PlayerData<T>) => void;
31
+ /** Runs on the buyer's data. */
32
+ Grant?: (this: void, data: PlayerData<T>, player: Player) => void;
31
33
  Meta?: UnknownRecord;
32
34
  IdempotencyKey?: string;
33
35
  PaidRandom?: boolean;
@@ -64,103 +66,184 @@ type ClientStoreMember<S> = keyof S extends never ? { readonly ServerStore?: nev
64
66
  export type SharedData<T> = ValueOf<SharedSchema<ClientSchema<T>>>;
65
67
 
66
68
  export interface ServerAPI<T, C = {}> {
69
+ /** Returns the player's accessor tree; errors unless the profile is Ready. */
67
70
  readonly Get: (this: void, player: Player) => PlayerData<T>;
71
+ /** Waits for a Ready profile, returning `undefined` and a reason on failure. */
68
72
  readonly WaitForData: (this: void, player: Player, timeout?: number) => LuaTuple<[PlayerData<T> | undefined, LifecycleReason | undefined]>;
73
+ /** Reads session state and loading phase without yielding. */
69
74
  readonly GetState: (this: void, player: Player) => LuaTuple<[SessionState, LoadPhase | undefined]>;
75
+ /** Groups writes into one replication flush and container notification pass. */
70
76
  readonly Batch: (this: void, player: Player, callback: (this: void) => void) => void;
77
+ /** Runs non-yielding writes atomically in memory; does not save them. */
71
78
  readonly Transaction: (this: void, player: Player, callback: (this: void) => void) => OperationResult;
79
+ /** Waits for pending changes to save; requires a Ready profile. */
72
80
  readonly Flush: (this: void, player: Player, options?: FlushOptions) => boolean;
81
+ /** Reads the player's last save result and pending-change state. */
73
82
  readonly GetSaveInfo: (this: void, player: Player) => SaveInfo;
74
- /** Offline/history reads are packed, potentially old schemas, not live accessor values. */
83
+ /** Returns a raw profile snapshot; packed values may use an older schema. */
75
84
  readonly GetOffline: (this: void, userId: number) => UnknownRecord | undefined;
85
+ /** Updates an offline profile, with optional template validation. */
76
86
  readonly UpdateOffline: (this: void, userId: number, callback: (this: void, rawData: UnknownRecord) => void, options?: UpdateOfflineOptions) => LuaTuple<[boolean, string | undefined, SchemaViolation[] | undefined]>;
87
+ /** Lists saved profile versions for support tools. */
77
88
  readonly ListVersions: (this: void, userId: number, limit?: number) => VersionRecord[];
89
+ /** Reads a historical raw snapshot, which may use an older schema. */
78
90
  readonly GetVersion: (this: void, userId: number, versionId: string) => UnknownRecord | undefined;
91
+ /** Restores an existing offline profile while preserving reserved data by default. */
79
92
  readonly RestoreVersion: (this: void, userId: number, versionId: string, options?: RestoreOptions) => OperationResult;
93
+ /** Deletes the profile and leaderboard records while blocking this user's joins. */
80
94
  readonly Erase: (this: void, userId: number) => OperationResult;
95
+ /** Serializes a profile to JSON, or returns `undefined` when absent. */
81
96
  readonly Export: (this: void, userId: number) => string | undefined;
97
+ /** Registers a validated, rate-limited command for Ready players. */
82
98
  readonly Command: RegisterCommand<C>;
99
+ /** Reads cached board results without a live DataStore request. */
83
100
  readonly GetLeaderboard: (this: void, name: string, limit?: number, offset?: number) => LeaderboardEntry[];
101
+ /** Reads the player's rank from the leaderboard cache. */
84
102
  readonly GetMyRank: (this: void, player: Player, name: string) => number | undefined;
103
+ /** Reads the next scheduled refresh delay; `undefined` until scheduled. */
85
104
  readonly GetLeaderboardRefreshIn: (this: void, name: string) => number | undefined;
105
+ /** Reads board health without a DataStore request. */
86
106
  readonly GetLeaderboardStatus: (this: void, name: string) => LeaderboardStatusInfo | undefined;
107
+ /** Reads the time remaining in a periodic board's current period. */
87
108
  readonly GetLeaderboardResetIn: (this: void, name: string) => number | undefined;
109
+ /** Opens a validated product or pass prompt; success does not mean the purchase completed. */
88
110
  readonly PromptPurchase: (this: void, player: Player, name: string) => OperationResult;
111
+ /** Reads the ownership and policy state used by purchase prompts. */
89
112
  readonly GetProductState: (this: void, player: Player, name: string) => ProductState;
113
+ /** Gifts a product perk using a credit or a paid prompt with a saved recipient. */
90
114
  readonly PromptGift: (this: void, buyer: Player, productName: string, recipientUserId: number) => OperationResult;
115
+ /** Reads the player's unassigned gift credits. */
91
116
  readonly GetGiftCredits: (this: void, player: Player) => { [product: string]: number };
117
+ /** Processes a Scribe receipt with persisted deduplication. */
92
118
  readonly HandleReceipt: (this: void, receipt: ReceiptInfo) => Enum.ProductPurchaseDecision;
119
+ /** Processes known products and returns `undefined` for another receipt handler. */
93
120
  readonly TryHandleReceipt: (this: void, receipt: ReceiptInfo) => Enum.ProductPurchaseDecision | undefined;
121
+ /** Reads cached pass, perk, or Roblox Plus ownership without yielding. */
94
122
  readonly Owns: (this: void, player: Player, key: string) => boolean;
123
+ /** Verifies uncached pass ownership with Roblox before returning. */
95
124
  readonly OwnsAsync: (this: void, player: Player, key: string, timeout?: number) => boolean;
125
+ /** Reports ownership now and on changes; returns a disconnect function. */
96
126
  readonly ObserveOwned: (this: void, player: Player, key: string, callback: (this: void, owned: boolean) => void) => Disconnect;
127
+ /** Grants a perk through Scribe's ownership state. */
97
128
  readonly GrantPerk: (this: void, player: Player, key: string) => void;
129
+ /** Removes a granted perk from Scribe's ownership state. */
98
130
  readonly RevokePerk: (this: void, player: Player, key: string) => void;
131
+ /** Debits, grants, and logs atomically; failures roll back the purchase. */
99
132
  readonly Purchase: (this: void, player: Player, spec: PurchaseSpec<T>) => OperationResult;
133
+ /** Adds a game-defined entry to the in-game purchase log. */
100
134
  readonly RecordPurchase: (this: void, player: Player, entry: UnknownRecord) => void;
135
+ /** Reads filtered purchase history, newest first. */
101
136
  readonly GetPurchases: (this: void, player: Player, filter?: PurchaseFilter) => PurchaseEntry[];
137
+ /** Starts an inactive cooldown; returns its previous state and seconds left. */
102
138
  readonly OnCooldown: (this: void, player: Player, key: string, seconds: number, options?: CooldownOptions) => LuaTuple<[boolean, number]>;
139
+ /** Reads cooldown state without starting or extending it. */
103
140
  readonly PeekCooldown: (this: void, player: Player, key: string) => LuaTuple<[boolean, number]>;
141
+ /** Clears a stored cooldown. */
104
142
  readonly ClearCooldown: (this: void, player: Player, key: string) => void;
143
+ /** Queues a durable message; receiving handlers must tolerate repeats. */
105
144
  readonly SendMessage: (this: void, userId: number, message: unknown) => boolean;
145
+ /** Trades declared value between players and recovers unfinished exchanges. */
106
146
  readonly Exchange: ExchangeAPI;
147
+ /** Fires after each save attempt, including failures. */
107
148
  readonly OnSave: Signal<[SaveEvent]>;
149
+ /** Fires when a player's session ends. */
108
150
  readonly SessionEnded: Signal<[Player, LifecycleReason]>;
151
+ /** Fires when data validation or integrity checks detect an anomaly. */
109
152
  readonly OnAnomaly: Signal<[Anomaly]>;
153
+ /** Fires when a player receives a gift. */
110
154
  readonly OnGiftReceived: Signal<[Player, GiftReceived]>;
155
+ /** Fires when a player receives an unassigned gift credit. */
111
156
  readonly OnGiftCredit: Signal<[Player, string]>;
157
+ /** Fires when effective ownership changes after load. */
112
158
  readonly OnOwnershipChanged: Signal<[Player, string, boolean]>;
159
+ /** Fires when a cooldown expires during an active session. */
113
160
  readonly OnCooldownEnded: Signal<[Player, string]>;
161
+ /** Fires when cached board contents change. */
114
162
  readonly OnLeaderboard: Signal<[string, LeaderboardEntry[]]>;
163
+ /** Delivers durable messages; handlers must be idempotent. */
115
164
  readonly OnMessage: Signal<[Player, unknown]>;
116
165
  /** External ProfileStore implementation; narrow to its own public package type before use. */
117
166
  readonly ProfileStore: unknown;
118
167
  /** Escape hatch requiring explicit validation/assertion at its boundary. */
119
168
  readonly Raw: unknown;
169
+ /** Stops this bundle's workers and releases its listeners. */
120
170
  readonly Stop: (this: void) => void;
121
171
  }
122
172
  export type ServerData<T, S = {}, C = {}> = ServerAPI<T, C> & ServerStoreMember<S>;
123
173
 
124
- /** Partial records for Mock; arrays and Roblox engine datatypes remain whole values. */
174
+ /** Mock merges records, dictionaries and maps by key. Arrays, sets, Flags and engine datatypes replace whole values. */
125
175
  export type MockValues<T> = T extends Datatype | buffer | BigValue | ReadonlyArray<unknown> | ReadonlyMap<unknown, unknown> ? T : T extends object ? { [K in keyof T]?: MockValues<T[K]> } : T;
126
176
  export interface ClientAPI<T, C = {}> {
177
+ /** Reads snapshot readiness without yielding. */
127
178
  readonly IsReady: (this: void) => boolean;
179
+ /** Waits for the first snapshot, returning false on timeout. */
128
180
  readonly WaitForData: (this: void, timeout?: number) => boolean;
181
+ /** Coalesces local container notifications; writes stay on this client. */
129
182
  readonly Batch: (this: void, callback: (this: void) => void) => void;
183
+ /** Sends a command to the server and waits for its reply. */
130
184
  readonly Request: RequestFunction<C>;
185
+ /** Sends a keyed command so retries reuse a retained server result. */
131
186
  readonly RequestOnce: RequestOnceFunction<C>;
187
+ /** Reads the replicated leaderboard cache without requesting a refresh. */
132
188
  readonly GetLeaderboard: (this: void, name: string, limit?: number) => LeaderboardEntry[];
189
+ /** Finds the local player's rank in the replicated board. */
133
190
  readonly GetMyRank: (this: void, name: string) => number | undefined;
191
+ /** Fires when a replicated leaderboard changes. */
134
192
  readonly OnLeaderboard: Signal<[string, LeaderboardEntry[]]>;
193
+ /** Reads the replicated data-service health. */
135
194
  readonly GetServiceStatus: (this: void) => Status;
195
+ /** Fires when the replicated service health changes. */
136
196
  readonly OnServiceStatus: Signal<[Status]>;
197
+ /** Reads another player's replicated Shared roots. */
137
198
  readonly GetShared: (this: void, playerOrUserId: Player | number) => SharedData<T> | undefined;
199
+ /** Fires when another player's Shared roots change or are removed. */
138
200
  readonly OnSharedChanged: Signal<[number, SharedData<T> | undefined]>;
201
+ /** Reads mirrored ownership after the profile loads. */
139
202
  readonly Owns: (this: void, key: string) => boolean;
203
+ /** Waits for the server's initial ownership sync before reading the mirror. */
140
204
  readonly OwnsAsync: (this: void, key: string, timeout?: number) => boolean;
205
+ /** Returns a disconnect immediately. Reports current ownership once loaded and on changes. */
141
206
  readonly ObserveOwned: (this: void, key: string, callback: (this: void, owned: boolean) => void) => Disconnect;
207
+ /** Fires for ownership changes after the initial baseline. */
142
208
  readonly OnOwnershipChanged: Signal<[string, boolean]>;
209
+ /** Reads cached player-specific marketplace info, fetching on demand. */
143
210
  readonly GetProductInfo: (this: void, name: string) => ProductInfo | undefined;
211
+ /** Reads the local player's cached Robux price, or `undefined` while loading. */
144
212
  readonly GetPrice: (this: void, name: string) => number | undefined;
213
+ /** Waits for marketplace info, returning `undefined` on timeout or failure. */
145
214
  readonly GetProductInfoAsync: (this: void, name: string, timeout?: number) => ProductInfo | undefined;
215
+ /** Waits for the local player's Robux price. */
146
216
  readonly GetPriceAsync: (this: void, name: string, timeout?: number) => number | undefined;
217
+ /** Reports cached product info and updates; returns a disconnect function. */
147
218
  readonly ObserveProductInfo: (this: void, name: string, callback: (this: void, info: ProductInfo | undefined) => void) => Disconnect;
219
+ /** Warms selected product info in one batch. */
148
220
  readonly PrefetchProductInfo: (this: void, names?: ReadonlyArray<string>) => void;
221
+ /** Invalidates cached marketplace info and starts fresh reads. */
149
222
  readonly RefreshProductInfo: (this: void, name?: string) => void;
150
223
  /** Asks the server to validate and prompt for the local player. Success is not a completed purchase; a timeout may occur after the prompt opens. No automatic retry. */
151
224
  readonly PromptPurchase: (this: void, name: string) => LuaTuple<[boolean, string | undefined, RequestFailedMarker | undefined]>;
225
+ /** Reads the mirrored ownership and policy state for shop UI. */
152
226
  readonly GetProductState: (this: void, name: string) => ProductState;
227
+ /** Reports shop state now and on changes; returns a disconnect function. */
153
228
  readonly ObserveProductState: (this: void, name: string, callback: (this: void, state: ProductState) => void) => Disconnect;
229
+ /** Waits for load, then reads the owner's replicated save status. */
154
230
  readonly GetSaveInfo: (this: void) => SaveInfo;
231
+ /** Waits for load, then reads unassigned gift credits. */
155
232
  readonly GetGiftCredits: (this: void) => { [product: string]: number };
233
+ /** Waits for load, then reads the enabled purchase logs. */
156
234
  readonly GetPurchases: (this: void, filter?: PurchaseFilter) => PurchaseEntry[];
235
+ /** Seeds local mirror data in edit mode only. */
157
236
  readonly Mock: (this: void, values?: MockValues<InputOf<ClientSchema<T>>>, state?: MockState) => void;
237
+ /** Registers an edit-mode command handler without a server. */
158
238
  readonly MockCommand: MockCommand<C>;
239
+ /** Exposes the raw API; validate or assert its type before use. */
159
240
  readonly Raw: unknown;
241
+ /** Releases this bundle's listeners, retry loop, and mirror. */
160
242
  readonly Stop: (this: void) => void;
161
243
  }
162
- /** Client field writes are local optimistic edits; server-owned roots remain read-only. */
163
- export type ClientData<T, S = {}, C = {}> = Omit<PlayerData<ClientSchema<T>>, Extract<keyof PlayerData<ClientSchema<T>>, keyof ClientAPI<T, C> | "ServerStore">> & ClientAPI<T, C> & ClientStoreMember<S>;
244
+ type ClientTree<T> = Accessor<ClientSchema<T>, true, false, false, false, true>;
245
+ /** Client writes are local; server-owned roots and timer deadlines are read-only. */
246
+ export type ClientData<T, S = {}, C = {}> = Omit<ClientTree<T>, Extract<keyof ClientTree<T>, keyof ClientAPI<T, C> | "ServerStore">> & ClientAPI<T, C> & ClientStoreMember<S>;
164
247
  export interface Bundle<T, S = {}, C = {}> { readonly Server: ServerData<T, S, C>; readonly Client: ClientData<T, S, C>; }
165
248
 
166
249
  /** Both templates share root field IDs. Broad dictionaries are validated at runtime. */
package/types/common.d.ts CHANGED
@@ -11,22 +11,32 @@ export interface Op { Kind: OpKind; Path: Path; Value?: unknown; Index?: number;
11
11
  export interface ScribeTransport {
12
12
  readonly Name: string;
13
13
  readonly MaxFrameBytes?: number;
14
+ /** Sends an encoded frame to one client. */
14
15
  SendToClient(player: Player, bytes: buffer): void;
16
+ /** Sends an encoded frame to every client. */
15
17
  SendToAllClients?(bytes: buffer): void;
18
+ /** Registers the server callback for incoming client frames. */
16
19
  ListenServer(callback: (this: void, player: Player, bytes: buffer) => void): void;
20
+ /** Sends an encoded frame to the server. */
17
21
  SendToServer(bytes: buffer): void;
22
+ /** Registers the client callback for incoming server frames. */
18
23
  ListenClient(callback: (this: void, bytes: buffer) => void): void;
24
+ /** Disconnects the client listener when Client.Stop runs. */
19
25
  Release?(): void;
20
26
  }
21
27
 
22
28
  export interface Connection {
23
29
  readonly Connected: boolean;
30
+ /** Stops this connection from receiving events. */
24
31
  Disconnect(): void;
25
32
  }
26
33
  /** Read-only event surface. Scribe owns firing and destroying these signals. */
27
34
  export interface Signal<Args extends unknown[]> {
35
+ /** Runs the callback on each event until disconnected. */
28
36
  Connect(callback: (this: void, ...args: Args) => void): Connection;
37
+ /** Runs the callback on the next event only. */
29
38
  Once(callback: (this: void, ...args: Args) => void): Connection;
39
+ /** Yields until the next event and returns its arguments. */
30
40
  Wait(): LuaTuple<Args>;
31
41
  }
32
42
 
@@ -208,6 +218,7 @@ export type LogCode =
208
218
  | "LISTENER_ERROR"
209
219
  | "ON_PLAYER_INIT_ERROR"
210
220
  | "ON_PLAYER_INIT_LEDGER"
221
+ | "ON_PLAYER_INIT_SESSION"
211
222
  | "PLAYER_LEAVING_HOOK_SLOW"
212
223
  | "SANDBOXED"
213
224
  | "SERVER_STARTED"
@@ -235,7 +246,7 @@ declare const requestFailedBrand: unique symbol;
235
246
  export interface RequestFailedMarker { readonly [requestFailedBrand]: true; }
236
247
  export type RequestFailure = LuaTuple<[false, RequestReason, RequestFailedMarker]>;
237
248
  export type ProductState = "purchasable" | "owned" | "paid-random-restricted" | "policy-pending" | "not-loaded";
238
- export type PurchaseReason = "player data not loaded" | "invalid Cost spec" | "invalid Cost amount" | "invalid cost path" | "cost path is not a spendable number" | "insufficient funds" | "paid random items are not available for this account" | "cannot check account settings right now; try again in a moment";
249
+ export type PurchaseReason = "player data not loaded" | "invalid Cost spec" | "invalid Cost amount" | "invalid cost path" | "cost path is not a spendable number" | "insufficient funds" | "paid random items are not available for this account" | "cannot check account settings right now; try again in a moment" | "invalid IdempotencyKey";
239
250
  export type GiftReason = "buyer data not loaded" | "invalid recipient" | "cannot gift yourself" | "gift cooldown" | "product retired" | "too many pending gifts" | "data services are experiencing issues; try again later" | "recipient already owns this" | "could not reserve gift credit; try again later" | "could not deliver gift; try again later" | "gift delivery could not be confirmed; do not send it again" | "a gift of this item is already pending; try again shortly" | "could not record gift intent; try again later" | "paid random items are not available for this account" | "cannot check account settings right now; try again in a moment";
240
251
  export type OperationResult = LuaTuple<[boolean, string | undefined]>;
241
252
 
@@ -251,6 +262,7 @@ export interface UpdateOfflineOptions { Validate?: boolean; }
251
262
  export interface RestoreOptions { RollBackReserved?: boolean; }
252
263
  export interface CooldownOptions { IncludeOfflineTime?: boolean; }
253
264
  export interface MigrationContext {
265
+ /** Waits for request allowance; call the returned release after issuing requests. */
254
266
  readonly AwaitBudget: (this: void, requestType: string, count?: number, timeout?: number) => LuaTuple<[boolean, Disconnect]>;
255
267
  }
256
268
 
@@ -330,10 +342,15 @@ export type ExchangeLeg =
330
342
  export interface OpenLeg { Path: Path; Kind: "Key" | "Qty" | "Stack"; Key?: unknown; Amount?: number; }
331
343
  export interface OpenExchange { Id: string; State: "Claimed" | "Staked" | "Delivering"; Partner?: number; Staked: OpenLeg[]; Owed: OpenLeg[]; Since?: number; }
332
344
  export interface ExchangeAPI {
345
+ /** Trades baskets between loaded players; a verdict can precede delivery. */
333
346
  readonly Attempt: (this: void, playerA: Player, basketA: ReadonlyArray<ExchangeLeg>, playerB: Player, basketB: ReadonlyArray<ExchangeLeg>) => LuaTuple<["Committed" | "Aborted" | undefined, string | undefined]>;
347
+ /** Lists the player's unfinished exchanges and held value. */
334
348
  readonly Open: (this: void, player: Player) => OpenExchange[];
349
+ /** Drops an unstaked claim only when no verdict exists. */
335
350
  readonly Discard: (this: void, exchangeId: string) => OperationResult;
351
+ /** Settles a stalled exchange; an existing verdict wins. */
336
352
  readonly Settle: (this: void, exchangeId: string, verdict: "Commit" | "Abort") => OperationResult;
353
+ /** Moves a parked delivery to another key in the same container. */
337
354
  readonly Redirect: (this: void, exchangeId: string, userId: number, newKey: string) => OperationResult;
338
355
  }
339
356
 
@@ -342,7 +359,11 @@ export interface MetricObservation { Count: number; Average: number; Max: number
342
359
  export type Metrics = { [name: string]: number | MetricObservation };
343
360
  export interface Percentiles { P50: number; P90: number; P99: number; Samples: number; Age: number; Window: number; }
344
361
  export type PercentileSnapshot = { [name: string]: Percentiles };
345
- export interface AddonAction { Run: (this: void, args: unknown) => unknown; Writes?: boolean; }
362
+ export interface AddonAction {
363
+ /** Runs the action with arguments from the Studio plugin. */
364
+ Run: (this: void, args: unknown) => unknown;
365
+ Writes?: boolean;
366
+ }
346
367
  export type AddonActions = { [name: string]: AddonAction };
347
368
  export interface ConfigureOptions { AutoSaveInterval?: number; }
348
369
  export interface StatusThresholds { FailWindow?: number; FailCount?: number; RecoverStreak?: number; }
package/types/index.d.ts CHANGED
@@ -6,63 +6,118 @@ declare const Scribe: Scribe.ScribeModule;
6
6
 
7
7
  declare namespace Scribe {
8
8
  interface ScribeModule {
9
+ /** Creates the server and client APIs from a shared template. */
9
10
  <T, S = {}, C = {}>(options: API.ScribeOptions<T, S, C>): API.Bundle<T, S, C>;
11
+ /** Creates the server and client APIs from a shared template. */
10
12
  readonly new: <T, S = {}, C = {}>(this: void, options: API.ScribeOptions<T, S, C>) => API.Bundle<T, S, C>;
11
13
  readonly Version: string;
14
+ /** Keeps a field and its subtree off the client. */
12
15
  readonly ServerOnly: <T>(this: void, value: T) => Schema.ServerOnly<T>;
16
+ /** Replicates a root field to every client. */
13
17
  readonly Shared: <T>(this: void, value: T) => Schema.Shared<T>;
18
+ /** Keeps a root field unsaved; its visibility wrappers still apply. */
14
19
  readonly Session: <T>(this: void, value: T) => Schema.Session<T>;
20
+ /** Declares integer data with optional bounds. */
15
21
  readonly Int: (this: void, value: number, meta?: NumberMeta) => number;
22
+ /** Declares floating-point data with optional bounds and wire precision. */
16
23
  readonly Number: (this: void, value: number, meta?: FloatMeta) => number;
24
+ /** Declares large-range numbers; numeric strings are limited to 256 bytes. */
17
25
  readonly Big: (this: void, value?: number | string, meta?: BigMeta) => Schema.BigSchema;
26
+ /** Declares string data with an optional byte limit. */
18
27
  readonly String: (this: void, value: string, meta?: StringMeta) => string;
28
+ /** Restricts a string field to the declared members. */
19
29
  readonly Enum: <K extends string>(this: void, value: NoInfer<K>, members: readonly K[]) => Schema.EnumValue<K>;
30
+ /** Stores up to 32 named booleans as one field. */
20
31
  readonly Flags: <K extends string>(this: void, members: readonly K[]) => Schema.Flags<K>;
32
+ /** Declares a leaf reset to its default after SetTimed expires. */
21
33
  readonly Timed: <T>(this: void, value: T) => Schema.Timed<T>;
34
+ /** Builds a default per profile with the supplied factory. */
22
35
  readonly Dynamic: <T>(this: void, factory: (this: void) => T) => T;
23
- /** Annotate compute arguments: the enclosing template is not in scope here. */
36
+ /** Computes a read-only field from paths; annotate compute arguments explicitly. */
24
37
  readonly Derived: <T, A extends unknown[]>(this: void, output: T, inputs: readonly string[], compute: (this: void, ...args: A) => Schema.ValueOf<T>) => Schema.Derived<T>;
38
+ /** Allows an absent leaf value without seeding the inner default. */
25
39
  readonly Optional: <T>(this: void, value: T) => Schema.Optional<T>;
40
+ /** Declares a typed array with optional size and eviction limits. */
26
41
  readonly ArrayOf: <T>(this: void, shape: T, options?: ArrayOpts) => Schema.ArrayOf<T>;
42
+ /** Declares unique scalar members with an optional size limit. */
27
43
  readonly SetOf: <T>(this: void, element: T, options?: SetOpts) => Schema.SetOf<T>;
44
+ /** Declares a map with integer or string keys and a value schema. */
28
45
  readonly MapOf: <K extends "integer" | "string", T>(this: void, keyType: K, shape: T, options?: DictOpts) => Schema.MapOf<K, T>;
46
+ /** Declares string-keyed values with a schema and optional limits. */
29
47
  readonly DictOf: <T>(this: void, shape: T, options?: DictOpts) => Schema.DictOf<T>;
48
+ /** Declares Vector3 data, packed for storage and replication. */
30
49
  readonly Vector3: (this: void, value: Vector3) => Vector3;
50
+ /** Declares Vector2 data, packed for storage and replication. */
31
51
  readonly Vector2: (this: void, value: Vector2) => Vector2;
52
+ /** Declares Vector3int16 data, packed for storage and replication. */
32
53
  readonly Vector3int16: (this: void, value: Vector3int16) => Vector3int16;
54
+ /** Declares Vector2int16 data, packed for storage and replication. */
33
55
  readonly Vector2int16: (this: void, value: Vector2int16) => Vector2int16;
56
+ /** Declares packed CFrame data; Precision = "exact" preserves its f32 components. */
34
57
  readonly CFrame: (this: void, value: CFrame, meta?: CFrameMeta) => CFrame;
58
+ /** Declares Color3 data, packed for storage and replication. */
35
59
  readonly Color3: (this: void, value: Color3) => Color3;
60
+ /** Declares BrickColor data, packed for storage and replication. */
36
61
  readonly BrickColor: (this: void, value: BrickColor) => BrickColor;
62
+ /** Declares UDim data, packed for storage and replication. */
37
63
  readonly UDim: (this: void, value: UDim) => UDim;
64
+ /** Declares UDim2 data, packed for storage and replication. */
38
65
  readonly UDim2: (this: void, value: UDim2) => UDim2;
66
+ /** Declares Rect data, packed for storage and replication. */
39
67
  readonly Rect: (this: void, value: Rect) => Rect;
68
+ /** Declares NumberRange data, packed for storage and replication. */
40
69
  readonly NumberRange: (this: void, value: NumberRange) => NumberRange;
70
+ /** Declares NumberSequence data, packed for storage and replication. */
41
71
  readonly NumberSequence: (this: void, value: NumberSequence) => NumberSequence;
72
+ /** Declares ColorSequence data, packed for storage and replication. */
42
73
  readonly ColorSequence: (this: void, value: ColorSequence) => ColorSequence;
74
+ /** Declares DateTime data, packed for storage and replication. */
43
75
  readonly DateTime: (this: void, value: DateTime) => DateTime;
76
+ /** Declares EnumItem data, packed for storage and replication. */
44
77
  readonly EnumItem: <T extends EnumItem>(this: void, value: T) => T;
78
+ /** Declares Font data, packed for storage and replication. */
45
79
  readonly Font: (this: void, value: Font) => Font;
80
+ /** Declares PhysicalProperties data, packed for storage and replication. */
46
81
  readonly PhysicalProperties: (this: void, value: PhysicalProperties) => PhysicalProperties;
82
+ /** Formats a number or Big value with suffixes and decimal places. */
47
83
  readonly Short: (this: void, value?: number | Schema.BigValue, decimals?: number) => string;
84
+ /** Replaces suffixes used by Short; the first suffix must be empty. */
48
85
  readonly SetShortSuffixes: (this: void, suffixes: readonly string[]) => void;
86
+ /** Sets process-wide options before any bundle is built; conflicting calls error. */
49
87
  readonly Configure: (this: void, config: Common.ConfigureOptions) => void;
88
+ /** Returns the server bundle prefix, or PLAYER_ before setup and on clients. */
50
89
  readonly GetProfileKeyPrefix: (this: void) => string;
90
+ /** Returns current DataStore health. */
51
91
  readonly GetStatus: (this: void) => Common.Status;
92
+ /** Fires when data-service health changes, with the new and previous status. */
52
93
  readonly OnStatusChanged: Common.Signal<[Common.Status, Common.Status]>;
94
+ /** Fires for each Error or Fatal log entry. */
53
95
  readonly OnIssue: Common.Signal<[Common.LogEntry]>;
96
+ /** Adds a filtered, bounded log sink; returns its disconnect function. */
54
97
  readonly AddLogSink: (this: void, callback: (this: void, entry: Common.LogEntry) => void, options?: Common.LogSinkOptions) => Schema.Disconnect;
98
+ /** Registers plugin actions; returned cleanup removes only this registration. */
55
99
  readonly RegisterAddon: (this: void, name: string, actions: Common.AddonActions) => Schema.Disconnect;
100
+ /** Returns filtered retained logs, oldest first; Limit keeps the newest entries. */
56
101
  readonly GetRecentLogs: (this: void, filter?: Common.LogFilter) => Common.LogEntry[];
102
+ /** Returns this context's counters and distribution summaries. */
57
103
  readonly GetMetrics: (this: void) => Common.Metrics;
104
+ /** Returns recent distribution percentiles with sample age and window size. */
58
105
  readonly GetPercentiles: (this: void) => Common.PercentileSnapshot;
106
+ /** Reads current DataStore allowances; Available is false if the query fails. */
59
107
  readonly GetBudgetSnapshot: (this: void) => Common.BudgetSnapshot;
108
+ /** Returns cached board health without DataStore requests; empty on clients. */
60
109
  readonly GetLeaderboardSnapshot: (this: void) => Common.LeaderboardSnapshotEntry[];
110
+ /** Distinguishes framework request failures from handler replies. */
61
111
  readonly RequestFailed: Common.RequestFailedMarker;
112
+ /** Codec helpers for packing and unpacking Roblox datatypes. */
62
113
  readonly Datatypes: {
114
+ /** Checks whether a datatype has a registered codec. */
63
115
  readonly IsSupported: (this: void, name: string) => boolean;
116
+ /** Lists supported precision options, or returns `undefined` when none exist. */
64
117
  readonly PrecisionValues: (this: void, name: string) => string[] | undefined;
118
+ /** Encodes a supported datatype into a buffer. */
65
119
  readonly Pack: <K extends keyof DatatypeValues>(this: void, name: K, value: DatatypeValues[K], precision?: K extends "CFrame" ? "exact" : never) => buffer;
120
+ /** Decodes a buffer into the named datatype. */
66
121
  readonly Unpack: <K extends keyof DatatypeValues>(this: void, name: K, bytes: buffer) => DatatypeValues[K];
67
122
  readonly NONFINITE: "Scribe:nonfinite:";
68
123
  };
@@ -109,7 +164,7 @@ declare namespace Scribe {
109
164
  export type ClientSchema<T> = Schema.ClientSchema<T>;
110
165
  export type SharedSchema<T> = Schema.SharedSchema<T>;
111
166
  export type ReadableNode<T> = Schema.ReadableNode<T>;
112
- export type Accessor<T, Root extends boolean = false, Missing extends boolean = false, ReadOnly extends boolean = false, Closed extends boolean = false> = Schema.Accessor<T, Root, Missing, ReadOnly, Closed>;
167
+ export type Accessor<T, Root extends boolean = false, Missing extends boolean = false, ReadOnly extends boolean = false, Closed extends boolean = false, Client extends boolean = false> = Schema.Accessor<T, Root, Missing, ReadOnly, Closed, Client>;
113
168
  export type PlayerData<T> = Schema.PlayerData<T>;
114
169
  export type ReadonlyAccessor<T, Root extends boolean = false> = Schema.ReadonlyAccessor<T, Root>;
115
170
  export type NumericPaths<T, IncludeBig extends boolean = false, Depth extends unknown[] = []> = Schema.NumericPaths<T, IncludeBig, Depth>;
@@ -208,7 +263,7 @@ declare namespace Scribe {
208
263
  interface ScribeModule {
209
264
  readonly Reason: { readonly LoadFailed: "load-failed"; readonly MigrationFailed: "migration-failed"; readonly Erasing: "erasing"; readonly SessionEnded: "session-ended"; readonly PlayerLeft: "player-left"; readonly Shutdown: "shutdown"; readonly StillLoading: "still-loading"; readonly Timeout: "timeout"; };
210
265
  readonly RequestReason: { readonly RateLimited: "rate-limited"; readonly NotReady: "not-ready"; readonly UnknownCommand: "unknown-command"; readonly BadArgs: "bad-args"; readonly BadIdempotencyKey: "bad-idempotency-key"; readonly Error: "error"; readonly ReplyEncodeFailed: "reply-encode-failed"; readonly Timeout: "timeout"; readonly SendFailed: "send-failed"; readonly EditMode: "edit-mode"; readonly MockError: "mock-error"; };
211
- readonly PurchaseReason: { readonly DataNotLoaded: "player data not loaded"; readonly InvalidCostSpec: "invalid Cost spec"; readonly InvalidCostAmount: "invalid Cost amount"; readonly InvalidCostPath: "invalid cost path"; readonly CostPathNotSpendable: "cost path is not a spendable number"; readonly InsufficientFunds: "insufficient funds"; readonly PaidRandomRestricted: "paid random items are not available for this account"; readonly PolicyPending: "cannot check account settings right now; try again in a moment"; };
266
+ readonly PurchaseReason: { readonly DataNotLoaded: "player data not loaded"; readonly InvalidCostSpec: "invalid Cost spec"; readonly InvalidCostAmount: "invalid Cost amount"; readonly InvalidCostPath: "invalid cost path"; readonly CostPathNotSpendable: "cost path is not a spendable number"; readonly InsufficientFunds: "insufficient funds"; readonly PaidRandomRestricted: "paid random items are not available for this account"; readonly PolicyPending: "cannot check account settings right now; try again in a moment"; readonly InvalidIdempotencyKey: "invalid IdempotencyKey"; };
212
267
  readonly GiftReason: { readonly ProductRetired: "product retired"; readonly BuyerDataNotLoaded: "buyer data not loaded"; readonly InvalidRecipient: "invalid recipient"; readonly CannotGiftYourself: "cannot gift yourself"; readonly GiftCooldown: "gift cooldown"; readonly TooManyPending: "too many pending gifts"; readonly DataServicesDown: "data services are experiencing issues; try again later"; readonly RecipientAlreadyOwns: "recipient already owns this"; readonly CreditReserveFailed: "could not reserve gift credit; try again later"; readonly DeliveryFailed: "could not deliver gift; try again later"; readonly DeliveryUnconfirmed: "gift delivery could not be confirmed; do not send it again"; readonly AlreadyPending: "a gift of this item is already pending; try again shortly"; readonly IntentRecordFailed: "could not record gift intent; try again later"; readonly PaidRandomRestricted: "paid random items are not available for this account"; readonly PolicyPending: "cannot check account settings right now; try again in a moment"; };
213
268
  readonly ProductState: { readonly Purchasable: "purchasable"; readonly Owned: "owned"; readonly PaidRandomRestricted: "paid-random-restricted"; readonly PolicyPending: "policy-pending"; readonly NotLoaded: "not-loaded"; };
214
269
  readonly OpKind: { readonly Init: "Init"; readonly Set: "Set"; readonly Insert: "Insert"; readonly Remove: "Remove"; readonly Clear: "Clear"; };