@rbxts/scribe 2.5.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/LICENSE +21 -0
- package/NOTICE +21 -0
- package/README.md +100 -0
- package/Scribe-source-map.json +1 -0
- package/licenses/ProfileStore-Apache-2.0.txt +201 -0
- package/package.json +32 -0
- package/src/Client/DebugHook.luau +457 -0
- package/src/Client/init.luau +1607 -0
- package/src/Internal/Addons.luau +68 -0
- package/src/Internal/Big.luau +582 -0
- package/src/Internal/Budget.luau +377 -0
- package/src/Internal/Clock.luau +75 -0
- package/src/Internal/Config.luau +17 -0
- package/src/Internal/Conform.luau +400 -0
- package/src/Internal/Datatypes.luau +653 -0
- package/src/Internal/Defaults.luau +12 -0
- package/src/Internal/Derived.luau +428 -0
- package/src/Internal/Exchange.luau +556 -0
- package/src/Internal/ExchangeLeg.luau +1368 -0
- package/src/Internal/ExchangeVerdict.luau +179 -0
- package/src/Internal/Failure.luau +148 -0
- package/src/Internal/Health.luau +320 -0
- package/src/Internal/LeaderboardDiagnostics.luau +36 -0
- package/src/Internal/Log.luau +378 -0
- package/src/Internal/Marker.luau +76 -0
- package/src/Internal/Metrics.luau +152 -0
- package/src/Internal/Node.luau +3954 -0
- package/src/Internal/Profile.luau +69 -0
- package/src/Internal/Rng.luau +83 -0
- package/src/Internal/Sched.luau +56 -0
- package/src/Internal/Signal.luau +199 -0
- package/src/Internal/Store/ProfileStore.luau +3019 -0
- package/src/Internal/Store/init.luau +18 -0
- package/src/Internal/StudioCodec.luau +155 -0
- package/src/Internal/Template.luau +1848 -0
- package/src/Internal/Transport.luau +169 -0
- package/src/Internal/Util.luau +517 -0
- package/src/Internal/Version.luau +4 -0
- package/src/Internal/Wire.luau +1283 -0
- package/src/Server/Analytics.luau +223 -0
- package/src/Server/Commands.luau +728 -0
- package/src/Server/DebugHook.luau +1490 -0
- package/src/Server/Exchanges.luau +737 -0
- package/src/Server/Leaderboards.luau +2143 -0
- package/src/Server/Monetization.luau +3212 -0
- package/src/Server/Persistence.luau +3775 -0
- package/src/Server/Replication.luau +1253 -0
- package/src/Server/ServerStore.luau +81 -0
- package/src/Server/Timed.luau +579 -0
- package/src/Server/init.luau +672 -0
- package/src/Types.luau +480 -0
- package/src/init.luau +2231 -0
- package/types/api.d.ts +252 -0
- package/types/common.d.ts +355 -0
- package/types/index.d.ts +226 -0
- package/types/schema.d.ts +276 -0
|
@@ -0,0 +1,1848 @@
|
|
|
1
|
+
--!strict
|
|
2
|
+
-- Template compiler + runtime schema derivation. Walks the user template with
|
|
3
|
+
-- sorted keys (deterministic on server and client), strips declarator markers,
|
|
4
|
+
-- assigns a u16 field ID to every static path node, and records declared
|
|
5
|
+
-- type/bounds/visibility metadata for validation and wire packing.
|
|
6
|
+
|
|
7
|
+
local Util = require(script.Parent.Util)
|
|
8
|
+
local Marker = require(script.Parent.Marker)
|
|
9
|
+
local Big = require(script.Parent.Big)
|
|
10
|
+
local Datatypes = require(script.Parent.Datatypes)
|
|
11
|
+
local DerivedModule = require(script.Parent.Derived)
|
|
12
|
+
|
|
13
|
+
--- A declared bound that is NaN or infinite cannot bound anything: nothing exceeds
|
|
14
|
+
--- math.huge, and every comparison against NaN is false.
|
|
15
|
+
local function isFiniteBound(n: number): boolean
|
|
16
|
+
return n == n and n ~= math.huge and n ~= -math.huge
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
-- The wire width a Scribe.Number takes, opt-in via Precision. FLOAT_F64 is the default
|
|
20
|
+
-- and is what an undeclared Number stays; Min/Max alone select nothing. FLOAT_F32 is
|
|
21
|
+
-- Precision = "f32", IEEE binary32 in 4 bytes. FLOAT_Q8/16/32 is Precision = <step>, a
|
|
22
|
+
-- fixed-point grid over [Min, Max] whose nearest-point index travels in the narrowest
|
|
23
|
+
-- of 1, 2 or 4 bytes that holds the step count.
|
|
24
|
+
-- Lives here rather than in Wire (where its sibling intWidth does) because the compiler
|
|
25
|
+
-- has to agree with the encoder and the decoder: "the declared bounds cannot be
|
|
26
|
+
-- represented in the chosen width" is a startup refusal.
|
|
27
|
+
local FLOAT_F64, FLOAT_F32, FLOAT_Q8, FLOAT_Q16, FLOAT_Q32 = 0, 1, 2, 3, 4
|
|
28
|
+
|
|
29
|
+
-- The extremes of IEEE binary32: the largest finite value and the smallest normal
|
|
30
|
+
-- magnitude. Wire.canSchemaEncode tests values against both, because a value outside
|
|
31
|
+
-- them must degrade to exact f64 rather than round to infinity or flush to zero.
|
|
32
|
+
local F32_MAX = 3.4028234663852886e38
|
|
33
|
+
local F32_MIN_NORMAL = 1.1754943508222875e-38
|
|
34
|
+
-- Largest grid index a fixed-point field can carry, i.e. the u32 the widest form
|
|
35
|
+
-- writes. A range needing more steps than this is refused at compile time.
|
|
36
|
+
local Q_MAX_STEPS = 4294967295
|
|
37
|
+
|
|
38
|
+
--- How many grid steps `[Min, Max]` needs at a step of `Precision`. The grid
|
|
39
|
+
--- index runs 0..steps INCLUSIVE, so a width holding `steps` holds every index.
|
|
40
|
+
local function quantSteps(min: number, max: number, precision: number): number
|
|
41
|
+
return math.ceil((max - min) / precision)
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
export type Visibility = "Replicated" | "ServerOnly" | "Shared"
|
|
45
|
+
|
|
46
|
+
export type SchemaNode = {
|
|
47
|
+
Id: number?, -- nil for dynamic (any) pseudo-nodes
|
|
48
|
+
Name: string?,
|
|
49
|
+
Path: { string },
|
|
50
|
+
Kind: "leaf" | "table" | "any",
|
|
51
|
+
ValueType: "number"
|
|
52
|
+
| "int"
|
|
53
|
+
| "boolean"
|
|
54
|
+
| "string"
|
|
55
|
+
| "enum"
|
|
56
|
+
| "flags"
|
|
57
|
+
| "big"
|
|
58
|
+
| "buffer"
|
|
59
|
+
| "datatype"
|
|
60
|
+
| "table"
|
|
61
|
+
| "any",
|
|
62
|
+
Datatype: string?, -- typeof() name when ValueType == "datatype"
|
|
63
|
+
Visibility: Visibility, -- who receives diffs
|
|
64
|
+
Persist: boolean, -- false for a Scribe.Session subtree; orthogonal to Visibility
|
|
65
|
+
Timed: boolean,
|
|
66
|
+
Min: number?,
|
|
67
|
+
Max: number?,
|
|
68
|
+
-- Scribe.Number only, opt-in: nil is f64, "f32" is IEEE binary32, a positive
|
|
69
|
+
-- number is the step of a fixed-point grid over [Min, Max]. Wire.floatPlan is the
|
|
70
|
+
-- one place that turns this into a width.
|
|
71
|
+
Precision: (number | string)?,
|
|
72
|
+
MaxLength: number?,
|
|
73
|
+
Members: { string }?,
|
|
74
|
+
MemberIndex: { [string]: number }?, -- 0-based, for u8 packing
|
|
75
|
+
Default: any,
|
|
76
|
+
Factory: (() -> any)?, -- Scribe.Dynamic: seeds this field on a brand-new profile
|
|
77
|
+
-- Scribe.Derived: computed from other declared fields, never written. Resolved in
|
|
78
|
+
-- a post-pass (see Compile), because an input may name a root that has not been
|
|
79
|
+
-- built yet when this node is created.
|
|
80
|
+
Derived: {
|
|
81
|
+
Inputs: { SchemaNode },
|
|
82
|
+
InputPaths: { { string } },
|
|
83
|
+
Compute: (...any) -> any,
|
|
84
|
+
Transmit: boolean, -- server computes and REPLICATES (an input the audience cannot see)
|
|
85
|
+
OfflineComputable: boolean, -- root-level, and every input persists
|
|
86
|
+
Label: string,
|
|
87
|
+
}?,
|
|
88
|
+
Children: { [string]: SchemaNode }?,
|
|
89
|
+
ChildOrder: { string }?, -- sorted; ordinal i encodes child ChildOrder[i]
|
|
90
|
+
ChildOrdinal: { [string]: number }?,
|
|
91
|
+
Parent: SchemaNode?,
|
|
92
|
+
AnyChild: SchemaNode?, -- dynamic-key child: the compiled element schema on an
|
|
93
|
+
-- ArrayOf/DictOf node (set at compile time), otherwise a generic pseudo-node
|
|
94
|
+
-- synthesized lazily on first access
|
|
95
|
+
HasPacked: boolean?, -- true if a declared descendant stores a different shape than
|
|
96
|
+
-- it reads (a packed datatype buffer, a Scribe.Big pair); lets container reads
|
|
97
|
+
-- skip the deep-unpack walk when there is nothing to convert
|
|
98
|
+
-- Scribe.ArrayOf / Scribe.DictOf. `Container` is the discriminator (nil on every
|
|
99
|
+
-- other node, untyped dynamic containers included); `IsElement` marks the compiled
|
|
100
|
+
-- element root under AnyChild; `Closed` marks an element record whose field set is
|
|
101
|
+
-- fixed, so an undeclared key is a write error rather than a synthesized `any` child.
|
|
102
|
+
Container: ("Array" | "Dict")?,
|
|
103
|
+
IsElement: boolean?,
|
|
104
|
+
Closed: boolean?,
|
|
105
|
+
-- Scribe.Optional: the field may legitimately be absent. Its Default is nil, so
|
|
106
|
+
-- it is not seeded into a new profile and not filled into a partial element.
|
|
107
|
+
Nullable: boolean?,
|
|
108
|
+
-- Element default with ServerOnly subtrees removed, used when a client mirror
|
|
109
|
+
-- materializes a fresh entry (see Node.resolveContainer).
|
|
110
|
+
ClientDefault: any,
|
|
111
|
+
MaxItems: number?,
|
|
112
|
+
Evict: string?,
|
|
113
|
+
Unique: boolean?,
|
|
114
|
+
KeyType: string?,
|
|
115
|
+
MaxKeys: number?,
|
|
116
|
+
MaxKeyLength: number?,
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
export type Compiled = {
|
|
120
|
+
Root: SchemaNode,
|
|
121
|
+
ById: { [number]: SchemaNode },
|
|
122
|
+
NodeCount: number,
|
|
123
|
+
Hash: number,
|
|
124
|
+
RootOrder: { string },
|
|
125
|
+
-- Whether the template declares a Scribe.Shared root. Replication uses it to skip
|
|
126
|
+
-- the per-player work only Shared data justifies: an O(N) broadcast on every leave
|
|
127
|
+
-- and an O(N) entry scan on every join.
|
|
128
|
+
HasShared: boolean,
|
|
129
|
+
DynamicNodes: { SchemaNode }, -- fields with a Scribe.Dynamic factory, in id order
|
|
130
|
+
DerivedNodes: { SchemaNode }, -- Scribe.Derived fields in topological order
|
|
131
|
+
-- pathKey of an input (or any ancestor of one) -> the fields to recompute. A
|
|
132
|
+
-- write looks up its own pathKey and finds every dependent in one hop.
|
|
133
|
+
DerivedByWrite: { [string]: { SchemaNode } },
|
|
134
|
+
-- Root views. Player is the compiled itself when no store is declared; views share
|
|
135
|
+
-- everything but Root, RootOrder and HasShared by reference.
|
|
136
|
+
Views: { Player: Compiled, Store: Compiled? },
|
|
137
|
+
Config: CompileConfig,
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
export type CompileConfig = {
|
|
141
|
+
ReplicateRobuxLog: boolean?,
|
|
142
|
+
ReplicateInGameLog: boolean?,
|
|
143
|
+
-- Roots owned by the server, not a player. Same compile state as the player roots,
|
|
144
|
+
-- so one id space and one hash.
|
|
145
|
+
ServerStore: { [string]: any }?,
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
local RESERVED_ROOT = "_Scribe"
|
|
149
|
+
local SESSION_ROOT = "_ScribeSession"
|
|
150
|
+
-- Cooldown slots share the flat _Scribe.Timed dict with timed-field pathKeys and
|
|
151
|
+
-- are namespaced by this prefix. Owned here (not in Server/Timed) so Compile can
|
|
152
|
+
-- reject a root field that would alias a cooldown slot.
|
|
153
|
+
local COOLDOWN_PREFIX = "@cd|"
|
|
154
|
+
-- Online-only cooldowns share that dict but hold remaining seconds rather than a
|
|
155
|
+
-- deadline. The prefixes differ at byte 4 ("|" vs "o"), so no wall-clock key text can
|
|
156
|
+
-- ever spell an online slot.
|
|
157
|
+
local ONLINE_COOLDOWN_PREFIX = "@cdo|"
|
|
158
|
+
|
|
159
|
+
local Template = {}
|
|
160
|
+
|
|
161
|
+
Template.FLOAT_F64 = FLOAT_F64
|
|
162
|
+
Template.FLOAT_F32 = FLOAT_F32
|
|
163
|
+
Template.FLOAT_Q8 = FLOAT_Q8
|
|
164
|
+
Template.FLOAT_Q16 = FLOAT_Q16
|
|
165
|
+
Template.FLOAT_Q32 = FLOAT_Q32
|
|
166
|
+
Template.F32_MAX = F32_MAX
|
|
167
|
+
Template.F32_MIN_NORMAL = F32_MIN_NORMAL
|
|
168
|
+
Template.Q_MAX_STEPS = Q_MAX_STEPS
|
|
169
|
+
Template.QuantSteps = quantSteps
|
|
170
|
+
|
|
171
|
+
--- The wire width `node` takes. Total by construction: every shape the validator
|
|
172
|
+
--- refuses answers FLOAT_F64 here, so a node that somehow reached the encoder
|
|
173
|
+
--- unvalidated gets the lossless encoding rather than a corrupt one.
|
|
174
|
+
function Template.FloatPlan(node: SchemaNode): number
|
|
175
|
+
local p = node.Precision
|
|
176
|
+
if p == nil then
|
|
177
|
+
return FLOAT_F64
|
|
178
|
+
end
|
|
179
|
+
if p == "f32" then
|
|
180
|
+
return FLOAT_F32
|
|
181
|
+
end
|
|
182
|
+
local min, max = node.Min, node.Max
|
|
183
|
+
if type(p) ~= "number" or p ~= p or p <= 0 or p == math.huge or min == nil or max == nil or max < min then
|
|
184
|
+
return FLOAT_F64
|
|
185
|
+
end
|
|
186
|
+
local steps = quantSteps(min, max, p)
|
|
187
|
+
if steps < 256 then
|
|
188
|
+
return FLOAT_Q8
|
|
189
|
+
elseif steps < 65536 then
|
|
190
|
+
return FLOAT_Q16
|
|
191
|
+
elseif steps <= Q_MAX_STEPS then
|
|
192
|
+
return FLOAT_Q32
|
|
193
|
+
end
|
|
194
|
+
return FLOAT_F64
|
|
195
|
+
end
|
|
196
|
+
Template.RESERVED_ROOT = RESERVED_ROOT
|
|
197
|
+
Template.SESSION_ROOT = SESSION_ROOT
|
|
198
|
+
Template.COOLDOWN_PREFIX = COOLDOWN_PREFIX
|
|
199
|
+
Template.ONLINE_COOLDOWN_PREFIX = ONLINE_COOLDOWN_PREFIX
|
|
200
|
+
|
|
201
|
+
local function compileError(path: { string }, message: string): never
|
|
202
|
+
error(`Scribe: template error at "{table.concat(path, ".")}": {message}`, 0)
|
|
203
|
+
end
|
|
204
|
+
|
|
205
|
+
-- A Scribe declarator anywhere inside an array-like container would be silently
|
|
206
|
+
-- stored as its raw marker table instead of compiled into a schema field, so reject
|
|
207
|
+
-- the shape outright. A valid data blob contains no markers, so scanning it is safe.
|
|
208
|
+
local function rejectNestedMarkers(path: { string }, value: any)
|
|
209
|
+
local function walk(v: any, where: string)
|
|
210
|
+
if Marker.inspect(v) ~= nil then
|
|
211
|
+
compileError(
|
|
212
|
+
path,
|
|
213
|
+
`"{where}" is a Scribe declarator inside an array-like container, which stores its `
|
|
214
|
+
.. `entries as opaque data and so has no schema for the declarator to compile into. `
|
|
215
|
+
.. `Declare the element shape instead: Scribe.ArrayOf(\{ ... }) for a list, or `
|
|
216
|
+
.. `Scribe.DictOf(\{ ... }) for a string-keyed table. That is also the only way to `
|
|
217
|
+
.. `store a Roblox datatype inside a container`
|
|
218
|
+
)
|
|
219
|
+
elseif type(v) == "table" then
|
|
220
|
+
for k, child in v do
|
|
221
|
+
walk(child, if where == "" then tostring(k) else where .. "." .. tostring(k))
|
|
222
|
+
end
|
|
223
|
+
end
|
|
224
|
+
end
|
|
225
|
+
for k, v in value do
|
|
226
|
+
walk(v, tostring(k))
|
|
227
|
+
end
|
|
228
|
+
end
|
|
229
|
+
|
|
230
|
+
-- Declarators that cannot appear inside an ArrayOf/DictOf element shape, each with
|
|
231
|
+
-- the reason it is unsound there. Scanned over the RAW shape at compile time so a
|
|
232
|
+
-- bad template fails at startup rather than behaving subtly wrong per element.
|
|
233
|
+
local FORBIDDEN_IN_ELEMENT: { [string]: string } = {
|
|
234
|
+
Timed = "timed state is keyed by path and element paths are positional (an array index shifts on every"
|
|
235
|
+
.. " insert or remove), so a running timer would resolve to the wrong element; store an expiry field"
|
|
236
|
+
.. " on the element instead",
|
|
237
|
+
Dynamic = "a Scribe.Dynamic factory seeds a field once per brand-new profile, and elements do not exist"
|
|
238
|
+
.. " then; generate per-element values at Insert time",
|
|
239
|
+
Derived = "a derived field reads a fixed set of declared paths, and element paths are positional (an array"
|
|
240
|
+
.. " index shifts on every insert or remove), so its inputs would name a different entry after every"
|
|
241
|
+
.. " structural write; derive at the root from a field the element writes instead",
|
|
242
|
+
Shared = "Scribe.Shared is only supported on root fields",
|
|
243
|
+
Session = "Scribe.Session is only supported on root fields",
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
local function rejectInElementShape(path: { string }, shape: any)
|
|
247
|
+
local function walk(v: any)
|
|
248
|
+
if type(v) ~= "table" then
|
|
249
|
+
return
|
|
250
|
+
end
|
|
251
|
+
local kind, default, meta = Marker.inspect(v)
|
|
252
|
+
if kind ~= nil then
|
|
253
|
+
local reason = FORBIDDEN_IN_ELEMENT[kind :: string]
|
|
254
|
+
if reason then
|
|
255
|
+
compileError(path, `Scribe.{kind} is not supported inside an element shape: {reason}`)
|
|
256
|
+
end
|
|
257
|
+
if kind == "ArrayOf" or kind == "DictOf" or kind == "SetOf" or kind == "MapOf" then
|
|
258
|
+
-- A nested container hides its shape in Meta.Element, not in Default.
|
|
259
|
+
walk(if meta then meta.Element else nil)
|
|
260
|
+
else
|
|
261
|
+
walk(default)
|
|
262
|
+
end
|
|
263
|
+
return
|
|
264
|
+
end
|
|
265
|
+
for _, child in v do
|
|
266
|
+
walk(child)
|
|
267
|
+
end
|
|
268
|
+
end
|
|
269
|
+
walk(shape)
|
|
270
|
+
end
|
|
271
|
+
|
|
272
|
+
-- Whether reading this node (or anything below it) has to convert a stored shape back
|
|
273
|
+
-- to its read shape: a datatype packs to a buffer, a Scribe.Big stores a
|
|
274
|
+
-- { mantissa, exponent } pair. One predicate, so a third such type cannot reach some
|
|
275
|
+
-- read paths and miss the others.
|
|
276
|
+
local function isPacked(node: SchemaNode): boolean
|
|
277
|
+
return node.ValueType == "datatype" or node.ValueType == "big" or node.HasPacked == true
|
|
278
|
+
end
|
|
279
|
+
|
|
280
|
+
local function checkContainerCap(path: { string }, label: string, value: any)
|
|
281
|
+
if value == nil then
|
|
282
|
+
return
|
|
283
|
+
end
|
|
284
|
+
if type(value) ~= "number" or value % 1 ~= 0 or value < 1 then
|
|
285
|
+
compileError(path, `{label} must be a positive integer`)
|
|
286
|
+
end
|
|
287
|
+
end
|
|
288
|
+
|
|
289
|
+
-- Element subtrees are addressed only through AnyChild, never by field id, so they
|
|
290
|
+
-- carry none. See the id-less rationale at the ArrayOf/DictOf branch in buildNode.
|
|
291
|
+
local function clearIds(node: SchemaNode)
|
|
292
|
+
node.Id = nil
|
|
293
|
+
if node.Children then
|
|
294
|
+
for _, child in node.Children do
|
|
295
|
+
clearIds(child)
|
|
296
|
+
end
|
|
297
|
+
end
|
|
298
|
+
if node.AnyChild then
|
|
299
|
+
clearIds(node.AnyChild)
|
|
300
|
+
end
|
|
301
|
+
end
|
|
302
|
+
|
|
303
|
+
-- Deepest declared level below and including `node`, counting a nested container's
|
|
304
|
+
-- element as one further level (an element is reached through a key of its own).
|
|
305
|
+
local function declaredDepth(node: SchemaNode): number
|
|
306
|
+
local deepest = 0
|
|
307
|
+
if node.Children then
|
|
308
|
+
for _, child in node.Children do
|
|
309
|
+
local d = declaredDepth(child)
|
|
310
|
+
if d > deepest then
|
|
311
|
+
deepest = d
|
|
312
|
+
end
|
|
313
|
+
end
|
|
314
|
+
end
|
|
315
|
+
if node.AnyChild then
|
|
316
|
+
local d = declaredDepth(node.AnyChild)
|
|
317
|
+
if d > deepest then
|
|
318
|
+
deepest = d
|
|
319
|
+
end
|
|
320
|
+
end
|
|
321
|
+
return deepest + 1
|
|
322
|
+
end
|
|
323
|
+
|
|
324
|
+
-- Element default with ServerOnly subtrees dropped, mirroring BuildDefaults'
|
|
325
|
+
-- buildClient. A client mirror seeds fresh entries from this, so that writing one
|
|
326
|
+
-- field of a new element cannot conjure a ServerOnly sibling's declared value.
|
|
327
|
+
local function buildClientDefault(node: SchemaNode): any
|
|
328
|
+
if node.Visibility == "ServerOnly" then
|
|
329
|
+
return nil
|
|
330
|
+
end
|
|
331
|
+
if node.Kind ~= "table" or not node.Children then
|
|
332
|
+
return Util.deepClone(node.Default)
|
|
333
|
+
end
|
|
334
|
+
local out = {}
|
|
335
|
+
for key, child in node.Children do
|
|
336
|
+
local value = buildClientDefault(child)
|
|
337
|
+
if value ~= nil then
|
|
338
|
+
out[key] = value
|
|
339
|
+
end
|
|
340
|
+
end
|
|
341
|
+
return out
|
|
342
|
+
end
|
|
343
|
+
|
|
344
|
+
local function checkDefaultValue(path: { string }, value: any)
|
|
345
|
+
local t = typeof(value)
|
|
346
|
+
if t == "table" then
|
|
347
|
+
local hasNum, hasStr = false, false
|
|
348
|
+
for k, v in value do
|
|
349
|
+
local kt = type(k)
|
|
350
|
+
if kt ~= "string" and kt ~= "number" then
|
|
351
|
+
compileError(path, `unsupported key type "{kt}"`)
|
|
352
|
+
end
|
|
353
|
+
hasNum = hasNum or kt == "number"
|
|
354
|
+
hasStr = hasStr or kt == "string"
|
|
355
|
+
if hasNum and hasStr then
|
|
356
|
+
-- A mixed table cannot be JSON-encoded, so the very first save of a
|
|
357
|
+
-- new profile seeded with this default would fail outright.
|
|
358
|
+
compileError(path, "a default cannot mix array indices and string keys (it would fail the save)")
|
|
359
|
+
end
|
|
360
|
+
-- A string default key becomes a persisted JSON object key, so it must
|
|
361
|
+
-- be valid UTF-8 or the very first save of a new profile fails.
|
|
362
|
+
if kt == "string" and not Util.isUtf8(k :: string) then
|
|
363
|
+
compileError(path, `default key "{k}" contains invalid UTF-8 bytes`)
|
|
364
|
+
end
|
|
365
|
+
local childPath = table.clone(path)
|
|
366
|
+
table.insert(childPath, tostring(k))
|
|
367
|
+
checkDefaultValue(childPath, v)
|
|
368
|
+
end
|
|
369
|
+
elseif t ~= "boolean" and t ~= "number" and t ~= "string" and t ~= "buffer" then
|
|
370
|
+
compileError(path, `unsupported value type "{t}" (only booleans, numbers, strings, buffers and tables persist)`)
|
|
371
|
+
elseif t == "number" and (value ~= value or value == math.huge or value == -math.huge) then
|
|
372
|
+
compileError(path, "NaN/inf default")
|
|
373
|
+
elseif t == "string" and not Util.isUtf8(value :: string) then
|
|
374
|
+
-- A string default is seeded verbatim into every new profile and saved.
|
|
375
|
+
compileError(path, "string default contains invalid UTF-8 bytes")
|
|
376
|
+
end
|
|
377
|
+
end
|
|
378
|
+
|
|
379
|
+
-- Builds one schema node from a (possibly marker-wrapped) template value.
|
|
380
|
+
type PendingDerived = { Node: SchemaNode, InputPaths: { string }, Compute: (...any) -> any }
|
|
381
|
+
-- `Derived` is absent on the throwaway state an element shape compiles against; a
|
|
382
|
+
-- derived field is refused inside an element shape before it could be reached.
|
|
383
|
+
type CompileState = { NextId: number, ById: { [number]: SchemaNode }, Derived: { PendingDerived }? }
|
|
384
|
+
|
|
385
|
+
local function buildNode(
|
|
386
|
+
state: CompileState,
|
|
387
|
+
name: string?,
|
|
388
|
+
rawValue: any,
|
|
389
|
+
path: { string },
|
|
390
|
+
inheritedVisibility: Visibility,
|
|
391
|
+
inheritedPersist: boolean,
|
|
392
|
+
parent: SchemaNode?
|
|
393
|
+
): SchemaNode
|
|
394
|
+
-- A field name is a persisted JSON object key, so reject invalid UTF-8 at compile
|
|
395
|
+
-- time rather than at the first save.
|
|
396
|
+
if name ~= nil and not Util.isUtf8(name) then
|
|
397
|
+
compileError(path, `field name contains invalid UTF-8 bytes`)
|
|
398
|
+
end
|
|
399
|
+
|
|
400
|
+
local visibility: Visibility = inheritedVisibility
|
|
401
|
+
local persist: boolean = inheritedPersist
|
|
402
|
+
-- Markers seen on THIS node, tracked separately from the inherited values so a
|
|
403
|
+
-- nested ServerOnly under a ServerOnly parent is still allowed. Replication and
|
|
404
|
+
-- persistence are independent axes: one of each combines, two of the same do not.
|
|
405
|
+
local replicationSeen: string? = nil
|
|
406
|
+
local sessionSeen = false
|
|
407
|
+
local timed = false
|
|
408
|
+
local derivedInputs: { string }? = nil
|
|
409
|
+
local derivedCompute: ((...any) -> any)? = nil
|
|
410
|
+
local dynamicSeen = false
|
|
411
|
+
local meta: Marker.Meta? = nil
|
|
412
|
+
local valueType: string? = nil
|
|
413
|
+
local containerKind: ("Array" | "Dict")? = nil
|
|
414
|
+
local containerDeclarator: string? = nil
|
|
415
|
+
local nullable = false
|
|
416
|
+
local value = rawValue
|
|
417
|
+
|
|
418
|
+
-- Unwrap (possibly nested) markers, e.g. Scribe.Session wrapping a table
|
|
419
|
+
-- whose fields use Scribe.Int.
|
|
420
|
+
while true do
|
|
421
|
+
local kind, default, markerMeta = Marker.inspect(value)
|
|
422
|
+
if kind == nil then
|
|
423
|
+
break
|
|
424
|
+
end
|
|
425
|
+
if kind == "Session" then
|
|
426
|
+
if sessionSeen then
|
|
427
|
+
compileError(path, "Scribe.Session is already applied to this field")
|
|
428
|
+
end
|
|
429
|
+
sessionSeen = true
|
|
430
|
+
if #path > 1 then
|
|
431
|
+
compileError(path, "Scribe.Session is only supported on root fields")
|
|
432
|
+
end
|
|
433
|
+
persist = false
|
|
434
|
+
elseif kind == "ServerOnly" or kind == "Shared" then
|
|
435
|
+
-- A field has ONE replication target, so these two cannot both apply:
|
|
436
|
+
-- letting the inner win makes Scribe.Shared(Scribe.ServerOnly(x)) broadcast
|
|
437
|
+
-- a field the outer wrapper says nobody should receive.
|
|
438
|
+
if replicationSeen ~= nil then
|
|
439
|
+
compileError(
|
|
440
|
+
path,
|
|
441
|
+
`Scribe.{replicationSeen} cannot wrap Scribe.{kind}: a field has one replication target, `
|
|
442
|
+
.. `not two. Combine either one with Scribe.Session instead, which sets whether it saves.`
|
|
443
|
+
)
|
|
444
|
+
end
|
|
445
|
+
replicationSeen = kind
|
|
446
|
+
if kind == "Shared" and #path > 1 then
|
|
447
|
+
compileError(path, "Scribe.Shared is only supported on root fields")
|
|
448
|
+
end
|
|
449
|
+
visibility = kind :: Visibility
|
|
450
|
+
elseif kind == "Timed" then
|
|
451
|
+
timed = true
|
|
452
|
+
elseif kind == "Int" then
|
|
453
|
+
valueType = "int"
|
|
454
|
+
meta = markerMeta
|
|
455
|
+
elseif kind == "Number" then
|
|
456
|
+
valueType = "number"
|
|
457
|
+
meta = markerMeta
|
|
458
|
+
elseif kind == "Big" then
|
|
459
|
+
valueType = "big"
|
|
460
|
+
meta = markerMeta
|
|
461
|
+
elseif kind == "String" then
|
|
462
|
+
valueType = "string"
|
|
463
|
+
meta = markerMeta
|
|
464
|
+
elseif kind == "Enum" then
|
|
465
|
+
valueType = "enum"
|
|
466
|
+
meta = markerMeta
|
|
467
|
+
elseif kind == "Flags" then
|
|
468
|
+
valueType = "flags"
|
|
469
|
+
meta = markerMeta
|
|
470
|
+
elseif kind == "Datatype" then
|
|
471
|
+
valueType = "datatype"
|
|
472
|
+
meta = markerMeta
|
|
473
|
+
elseif kind == "Optional" then
|
|
474
|
+
-- Wraps another declarator: keep unwrapping so the inner type and bounds
|
|
475
|
+
-- still compile, and drop the default to nil at the end of buildNode.
|
|
476
|
+
nullable = true
|
|
477
|
+
elseif kind == "ArrayOf" or kind == "DictOf" or kind == "SetOf" or kind == "MapOf" then
|
|
478
|
+
-- The element shape lives in Meta.Element and the marker's Default is nil,
|
|
479
|
+
-- so the `value = default` below ends the unwrap loop here. A SetOf is an
|
|
480
|
+
-- Array container with a uniqueness invariant on top, so it reuses the
|
|
481
|
+
-- whole element schema, wire and validation path.
|
|
482
|
+
containerKind = if kind == "DictOf" or kind == "MapOf" then "Dict" else "Array"
|
|
483
|
+
-- Keep the declarator the USER wrote: containerKind collapses SetOf into
|
|
484
|
+
-- Array and MapOf into Dict, so error text built from it names a declarator
|
|
485
|
+
-- the author never used.
|
|
486
|
+
containerDeclarator = `Scribe.{kind}`
|
|
487
|
+
meta = markerMeta
|
|
488
|
+
elseif kind == "Derived" then
|
|
489
|
+
-- A derived field is computed, never written, never persisted. Its Default is
|
|
490
|
+
-- the output declarator, so the loop keeps unwrapping into it and the
|
|
491
|
+
-- type/bounds machinery below is reached unchanged.
|
|
492
|
+
if derivedInputs ~= nil then
|
|
493
|
+
compileError(path, "Scribe.Derived is already applied to this field")
|
|
494
|
+
end
|
|
495
|
+
local inputs = if markerMeta then markerMeta.Inputs else nil
|
|
496
|
+
local compute = if markerMeta then markerMeta.Compute else nil
|
|
497
|
+
if type(inputs) ~= "table" then
|
|
498
|
+
compileError(path, "Scribe.Derived requires a table of input paths")
|
|
499
|
+
end
|
|
500
|
+
if type(compute) ~= "function" then
|
|
501
|
+
compileError(path, "Scribe.Derived requires a compute function")
|
|
502
|
+
end
|
|
503
|
+
-- Persistence is per ROOT (see Node.storeFor), so a derived field under a
|
|
504
|
+
-- persisted root would be written into profile.Data and saved. A root field
|
|
505
|
+
-- becomes non-persisted here, exactly as Scribe.Session would; anything
|
|
506
|
+
-- deeper has to already be.
|
|
507
|
+
if #path == 1 then
|
|
508
|
+
persist = false
|
|
509
|
+
elseif persist then
|
|
510
|
+
compileError(
|
|
511
|
+
path,
|
|
512
|
+
`a derived field is never persisted, so it must be a root field or live inside a `
|
|
513
|
+
.. `Scribe.Session root ("{path[1]}" is persisted)`
|
|
514
|
+
)
|
|
515
|
+
end
|
|
516
|
+
derivedInputs = inputs :: { string }
|
|
517
|
+
derivedCompute = compute :: (...any) -> any
|
|
518
|
+
elseif kind == "Dynamic" then
|
|
519
|
+
dynamicSeen = true
|
|
520
|
+
-- `default` is the sample (the factory ran once at declaration). Infer the
|
|
521
|
+
-- field type from it and carry the factory forward.
|
|
522
|
+
if default == nil then
|
|
523
|
+
compileError(path, "Scribe.Dynamic factory must return a non-nil value")
|
|
524
|
+
end
|
|
525
|
+
-- Dynamic seeds into the persistent store on a brand-new profile, but
|
|
526
|
+
-- Session data lives in a separate store rebuilt from its default every
|
|
527
|
+
-- session, so a Session+Dynamic seed would land in the wrong store.
|
|
528
|
+
if not persist then
|
|
529
|
+
compileError(
|
|
530
|
+
path,
|
|
531
|
+
"Scribe.Dynamic is not supported on a Session field; generate per-session values in OnPlayerInit instead"
|
|
532
|
+
)
|
|
533
|
+
end
|
|
534
|
+
local factory = if markerMeta then markerMeta.Factory else nil
|
|
535
|
+
local sampleType = typeof(default)
|
|
536
|
+
if Datatypes.IsSupported(sampleType) then
|
|
537
|
+
valueType = "datatype"
|
|
538
|
+
meta = { Datatype = sampleType, Factory = factory } :: Marker.Meta
|
|
539
|
+
elseif type(default) == "table" then
|
|
540
|
+
compileError(path, "Scribe.Dynamic only wraps leaf values (numbers, strings, datatypes, ...)")
|
|
541
|
+
else
|
|
542
|
+
meta = { Factory = factory } :: Marker.Meta
|
|
543
|
+
end
|
|
544
|
+
end
|
|
545
|
+
value = default
|
|
546
|
+
end
|
|
547
|
+
|
|
548
|
+
-- Wrapper combinations that contradict what a derived field IS. Checked after the
|
|
549
|
+
-- unwrap loop so the order the user wrote them in does not matter.
|
|
550
|
+
if derivedInputs ~= nil then
|
|
551
|
+
if sessionSeen then
|
|
552
|
+
compileError(path, "Scribe.Session is redundant on a derived field: a derived field never persists")
|
|
553
|
+
end
|
|
554
|
+
if timed then
|
|
555
|
+
compileError(path, "Scribe.Timed cannot wrap a derived field: a derived value has no expiry, only inputs")
|
|
556
|
+
end
|
|
557
|
+
if dynamicSeen then
|
|
558
|
+
compileError(
|
|
559
|
+
path,
|
|
560
|
+
"Scribe.Dynamic cannot wrap a derived field: a factory seeds a stored value, and a derived field "
|
|
561
|
+
.. "stores nothing"
|
|
562
|
+
)
|
|
563
|
+
end
|
|
564
|
+
if nullable then
|
|
565
|
+
compileError(
|
|
566
|
+
path,
|
|
567
|
+
"Scribe.Optional cannot wrap a derived field: its value is whatever the compute function returns"
|
|
568
|
+
)
|
|
569
|
+
end
|
|
570
|
+
if containerKind ~= nil then
|
|
571
|
+
compileError(
|
|
572
|
+
path,
|
|
573
|
+
`Scribe.Derived cannot wrap {containerDeclarator or "a container"}: a derived field produces one `
|
|
574
|
+
.. "scalar value"
|
|
575
|
+
)
|
|
576
|
+
end
|
|
577
|
+
end
|
|
578
|
+
|
|
579
|
+
-- Scribe.ArrayOf / Scribe.DictOf: a dynamic container carrying a compiled element
|
|
580
|
+
-- schema. Returns early, before the leaf and default machinery below: the container
|
|
581
|
+
-- declares no data of its own, and its element shape hangs off AnyChild, the node
|
|
582
|
+
-- every dynamic key resolves through (Template.ChildSchema).
|
|
583
|
+
if containerKind ~= nil then
|
|
584
|
+
local declarator = containerDeclarator or `Scribe.{containerKind}Of`
|
|
585
|
+
local elementShape = if meta then meta.Element else nil
|
|
586
|
+
if elementShape == nil then
|
|
587
|
+
compileError(path, `{declarator} requires an element shape`)
|
|
588
|
+
end
|
|
589
|
+
if timed then
|
|
590
|
+
compileError(path, `Scribe.Timed cannot wrap {declarator}`)
|
|
591
|
+
end
|
|
592
|
+
if nullable then
|
|
593
|
+
compileError(
|
|
594
|
+
path,
|
|
595
|
+
`Scribe.Optional cannot wrap {declarator}; an empty container is already the absent case`
|
|
596
|
+
)
|
|
597
|
+
end
|
|
598
|
+
rejectInElementShape(path, elementShape)
|
|
599
|
+
checkContainerCap(path, "MaxItems", meta and meta.MaxItems)
|
|
600
|
+
checkContainerCap(path, "MaxKeys", meta and meta.MaxKeys)
|
|
601
|
+
checkContainerCap(path, "MaxKeyLength", meta and meta.MaxKeyLength)
|
|
602
|
+
local evict = meta and meta.Evict
|
|
603
|
+
if evict ~= nil then
|
|
604
|
+
if evict ~= "Front" and evict ~= "Back" then
|
|
605
|
+
compileError(path, `Scribe.ArrayOf Evict must be "Front" or "Back", got {tostring(evict)}`)
|
|
606
|
+
end
|
|
607
|
+
-- Evict has nothing to drop from without a cap, so a bare Evict is a
|
|
608
|
+
-- config mistake rather than a no-op.
|
|
609
|
+
if not (meta and meta.MaxItems) then
|
|
610
|
+
compileError(path, "Scribe.ArrayOf Evict requires MaxItems")
|
|
611
|
+
end
|
|
612
|
+
end
|
|
613
|
+
|
|
614
|
+
local node: SchemaNode = {
|
|
615
|
+
Id = state.NextId,
|
|
616
|
+
Name = name,
|
|
617
|
+
Path = table.clone(path),
|
|
618
|
+
Kind = "table",
|
|
619
|
+
ValueType = "table",
|
|
620
|
+
Visibility = visibility,
|
|
621
|
+
Persist = persist,
|
|
622
|
+
Timed = false,
|
|
623
|
+
Container = containerKind :: "Array" | "Dict",
|
|
624
|
+
MaxItems = meta and meta.MaxItems,
|
|
625
|
+
Evict = meta and meta.Evict,
|
|
626
|
+
Unique = meta and meta.Unique,
|
|
627
|
+
KeyType = meta and meta.KeyType,
|
|
628
|
+
MaxKeys = meta and meta.MaxKeys,
|
|
629
|
+
MaxKeyLength = meta and meta.MaxKeyLength,
|
|
630
|
+
Default = {},
|
|
631
|
+
Parent = parent,
|
|
632
|
+
}
|
|
633
|
+
state.ById[state.NextId :: number] = node
|
|
634
|
+
state.NextId += 1
|
|
635
|
+
if state.NextId > 65535 then
|
|
636
|
+
error("Scribe: template exceeds 65535 static fields", 0)
|
|
637
|
+
end
|
|
638
|
+
|
|
639
|
+
-- Compile the element against a throwaway id counter, then strip the ids. Element
|
|
640
|
+
-- fields are reachable only through AnyChild, while Template.Resolve follows
|
|
641
|
+
-- Children and Wire.EncodePath sources ids from it, so an id here would be
|
|
642
|
+
-- unaddressable at best and a decoder collision at worst.
|
|
643
|
+
local elementPath = table.clone(path)
|
|
644
|
+
table.insert(elementPath, "[]")
|
|
645
|
+
local element = buildNode({ NextId = 0, ById = {} }, nil, elementShape, elementPath, visibility, persist, node)
|
|
646
|
+
clearIds(element)
|
|
647
|
+
element.IsElement = true
|
|
648
|
+
if element.Children and next(element.Children) == nil then
|
|
649
|
+
compileError(path, `{declarator} element shape declares no fields`)
|
|
650
|
+
end
|
|
651
|
+
-- A declared record has a fixed field set at EVERY depth: an undeclared key on
|
|
652
|
+
-- the element or on any nested sub-record is a write error. Nested containers
|
|
653
|
+
-- ran this same post-processing in their own buildNode call, so the walk stops
|
|
654
|
+
-- at container boundaries.
|
|
655
|
+
local function closeRecords(n: SchemaNode)
|
|
656
|
+
if n.Container == nil and n.Children then
|
|
657
|
+
if next(n.Children) ~= nil then
|
|
658
|
+
n.Closed = true
|
|
659
|
+
end
|
|
660
|
+
for _, child in n.Children do
|
|
661
|
+
closeRecords(child)
|
|
662
|
+
end
|
|
663
|
+
end
|
|
664
|
+
end
|
|
665
|
+
closeRecords(element)
|
|
666
|
+
-- A set stores its members deduplicated and sorted, so the element has to be
|
|
667
|
+
-- orderable. Anything else compiles clean, accepts the first Add, then throws a
|
|
668
|
+
-- bare "attempt to compare table < table" on the second.
|
|
669
|
+
if node.Unique then
|
|
670
|
+
local vt = element.ValueType
|
|
671
|
+
if not (vt == "int" or vt == "number" or vt == "string" or vt == "enum") then
|
|
672
|
+
-- A Flags element carries Children = {}, so "has children" alone would
|
|
673
|
+
-- call it a record. Name the declarator's own value type first.
|
|
674
|
+
local kind
|
|
675
|
+
if vt == "table" and element.Container ~= nil then
|
|
676
|
+
kind = "nested container"
|
|
677
|
+
elseif vt == "table" then
|
|
678
|
+
kind = "record"
|
|
679
|
+
else
|
|
680
|
+
kind = vt
|
|
681
|
+
end
|
|
682
|
+
compileError(
|
|
683
|
+
path,
|
|
684
|
+
`Scribe.SetOf element must be an Int, Number, String or Enum, got a {kind}: members are `
|
|
685
|
+
.. "compared by value and stored in a sorted canonical order. Use Scribe.ArrayOf, or "
|
|
686
|
+
.. "hold a scalar identity field"
|
|
687
|
+
)
|
|
688
|
+
end
|
|
689
|
+
end
|
|
690
|
+
element.ClientDefault = buildClientDefault(element)
|
|
691
|
+
node.AnyChild = element
|
|
692
|
+
node.HasPacked = isPacked(element)
|
|
693
|
+
|
|
694
|
+
local deepest = #path + declaredDepth(element)
|
|
695
|
+
if deepest > Util.MAX_VALUE_DEPTH then
|
|
696
|
+
compileError(
|
|
697
|
+
path,
|
|
698
|
+
`element shape nests {deepest} levels deep, past the {Util.MAX_VALUE_DEPTH}-level write limit`
|
|
699
|
+
)
|
|
700
|
+
end
|
|
701
|
+
|
|
702
|
+
return node
|
|
703
|
+
end
|
|
704
|
+
|
|
705
|
+
local datatypeName: string? = nil
|
|
706
|
+
local datatypePrecision: string? = nil
|
|
707
|
+
if valueType == "datatype" then
|
|
708
|
+
datatypeName = meta and meta.Datatype
|
|
709
|
+
if not datatypeName or not Datatypes.IsSupported(datatypeName) then
|
|
710
|
+
compileError(path, `unsupported datatype declarator`)
|
|
711
|
+
end
|
|
712
|
+
if typeof(value) ~= datatypeName then
|
|
713
|
+
compileError(path, `default must be a {datatypeName}, got {typeof(value)}`)
|
|
714
|
+
end
|
|
715
|
+
-- Refused HERE, before the default is packed, rather than in the
|
|
716
|
+
-- declarator-sanity block below: Datatypes.Pack validates the argument itself
|
|
717
|
+
-- and would throw a raw, path-less error on the very next line.
|
|
718
|
+
local declared = meta and meta.Precision
|
|
719
|
+
if declared ~= nil then
|
|
720
|
+
local accepted = Datatypes.PrecisionValues(datatypeName :: string)
|
|
721
|
+
if not accepted then
|
|
722
|
+
compileError(
|
|
723
|
+
path,
|
|
724
|
+
`Scribe.{datatypeName} has no Precision option`
|
|
725
|
+
.. ` (only Scribe.Number and Scribe.CFrame take one)`
|
|
726
|
+
)
|
|
727
|
+
elseif type(declared) ~= "string" or not table.find(accepted, declared :: string) then
|
|
728
|
+
local offered = table.concat(accepted, '" or "')
|
|
729
|
+
compileError(path, `Scribe.{datatypeName} Precision must be "{offered}", got {tostring(declared)}`)
|
|
730
|
+
end
|
|
731
|
+
datatypePrecision = declared :: string
|
|
732
|
+
end
|
|
733
|
+
-- Profile data only ever holds the packed form.
|
|
734
|
+
value = Datatypes.Pack(datatypeName :: string, value, datatypePrecision)
|
|
735
|
+
end
|
|
736
|
+
|
|
737
|
+
-- checkDefaultValue validates raw persistable leaf data. Run it for leaves and for
|
|
738
|
+
-- array-like default blobs, whose elements are stored as data rather than recursed
|
|
739
|
+
-- as schema. A named container's children are validated when buildNode recurses into
|
|
740
|
+
-- them; here `value` still holds their un-stripped markers, so walking the whole
|
|
741
|
+
-- container would wrongly reject valid nested declarators.
|
|
742
|
+
if type(value) ~= "table" or Util.hasNumericKeys(value) then
|
|
743
|
+
-- Marker scan FIRST: a declarator holding a non-persistable default would
|
|
744
|
+
-- otherwise trip checkDefaultValue's generic "unsupported value type" on the
|
|
745
|
+
-- marker's raw .Default and bury the real problem, which is the declarator
|
|
746
|
+
-- being inside an array at all.
|
|
747
|
+
if type(value) == "table" then
|
|
748
|
+
rejectNestedMarkers(path, value)
|
|
749
|
+
end
|
|
750
|
+
checkDefaultValue(path, value)
|
|
751
|
+
end
|
|
752
|
+
|
|
753
|
+
local node: SchemaNode = {
|
|
754
|
+
Id = state.NextId,
|
|
755
|
+
Name = name,
|
|
756
|
+
Path = table.clone(path),
|
|
757
|
+
Kind = if type(value) == "table" then "table" else "leaf",
|
|
758
|
+
ValueType = (valueType or (if type(value) == "table" then "table" else type(value))) :: any,
|
|
759
|
+
Visibility = visibility,
|
|
760
|
+
Persist = persist,
|
|
761
|
+
Timed = timed,
|
|
762
|
+
Datatype = datatypeName,
|
|
763
|
+
Default = nil,
|
|
764
|
+
Parent = parent,
|
|
765
|
+
}
|
|
766
|
+
state.ById[state.NextId :: number] = node
|
|
767
|
+
state.NextId += 1
|
|
768
|
+
if state.NextId > 65535 then
|
|
769
|
+
error("Scribe: template exceeds 65535 static fields", 0)
|
|
770
|
+
end
|
|
771
|
+
|
|
772
|
+
if meta then
|
|
773
|
+
node.Min = meta.Min
|
|
774
|
+
node.Max = meta.Max
|
|
775
|
+
node.Precision = meta.Precision
|
|
776
|
+
node.MaxLength = meta.MaxLength
|
|
777
|
+
if meta.Members then
|
|
778
|
+
local members = table.clone(meta.Members)
|
|
779
|
+
local index: { [string]: number } = {}
|
|
780
|
+
for i, member in members do
|
|
781
|
+
if type(member) ~= "string" then
|
|
782
|
+
compileError(path, "enum members must be strings")
|
|
783
|
+
end
|
|
784
|
+
index[member] = i - 1
|
|
785
|
+
end
|
|
786
|
+
if #members > 255 then
|
|
787
|
+
compileError(path, "enums support at most 255 members")
|
|
788
|
+
end
|
|
789
|
+
node.Members = members
|
|
790
|
+
node.MemberIndex = index
|
|
791
|
+
end
|
|
792
|
+
end
|
|
793
|
+
|
|
794
|
+
-- Scribe.Dynamic: record the factory. Datatype results are packed (profile.Data
|
|
795
|
+
-- holds the packed form); other leaves pass through unchanged.
|
|
796
|
+
if meta and meta.Factory then
|
|
797
|
+
local rawFactory = meta.Factory
|
|
798
|
+
if datatypeName then
|
|
799
|
+
local dtName = datatypeName :: string
|
|
800
|
+
-- Always nil today: a Scribe.Dynamic datatype field is inferred from the
|
|
801
|
+
-- factory's sample, so there is no way to declare a Precision on one. Threaded
|
|
802
|
+
-- anyway, so a seeded value always lands in the form a Set would have written.
|
|
803
|
+
local dtPrecision = datatypePrecision
|
|
804
|
+
node.Factory = function()
|
|
805
|
+
return Datatypes.Pack(dtName, rawFactory(), dtPrecision)
|
|
806
|
+
end
|
|
807
|
+
else
|
|
808
|
+
node.Factory = rawFactory
|
|
809
|
+
end
|
|
810
|
+
end
|
|
811
|
+
|
|
812
|
+
-- Precision names what a field is stored and sent at, not a direction: on
|
|
813
|
+
-- Scribe.Number it narrows from f64, on Scribe.CFrame it widens from a lossy
|
|
814
|
+
-- quaternion. Anywhere else it would sit in the meta table doing nothing, so refuse
|
|
815
|
+
-- it. Datatype fields are exempt, having been validated above against the set their
|
|
816
|
+
-- codec publishes.
|
|
817
|
+
if node.Precision ~= nil and node.ValueType ~= "number" and node.ValueType ~= "datatype" then
|
|
818
|
+
compileError(
|
|
819
|
+
path,
|
|
820
|
+
`Precision is a Scribe.Number option and has no meaning on a {node.ValueType} field`
|
|
821
|
+
.. ` (Scribe.Int already packs from its Min/Max alone)`
|
|
822
|
+
)
|
|
823
|
+
end
|
|
824
|
+
if node.ValueType == "int" then
|
|
825
|
+
if type(value) ~= "number" or value % 1 ~= 0 then
|
|
826
|
+
compileError(path, "Scribe.Int default must be an integer")
|
|
827
|
+
end
|
|
828
|
+
-- Fractional bounds skew fixed-width int packing (value - Min is
|
|
829
|
+
-- truncated), so require integer Min/Max on Int fields.
|
|
830
|
+
if (node.Min ~= nil and node.Min % 1 ~= 0) or (node.Max ~= nil and node.Max % 1 ~= 0) then
|
|
831
|
+
compileError(path, "Scribe.Int Min/Max must be integers")
|
|
832
|
+
end
|
|
833
|
+
elseif node.ValueType == "number" then
|
|
834
|
+
if type(value) ~= "number" then
|
|
835
|
+
compileError(path, "Scribe.Number default must be a number")
|
|
836
|
+
end
|
|
837
|
+
-- A bound that cannot bound anything. A numeric literal above ~1.8e308 IS
|
|
838
|
+
-- math.huge, so `Max = 1e400` declares a ceiling no value can reach; NaN is worse,
|
|
839
|
+
-- since `value < nan` and `value > nan` are both false, disabling the very check
|
|
840
|
+
-- it was written to add.
|
|
841
|
+
if (node.Min ~= nil and not isFiniteBound(node.Min)) or (node.Max ~= nil and not isFiniteBound(node.Max)) then
|
|
842
|
+
compileError(path, "Scribe.Number Min/Max must be finite")
|
|
843
|
+
end
|
|
844
|
+
-- Narrowing is refused at configure time, not at runtime: the runtime answer
|
|
845
|
+
-- would be the encoder quietly taking the generic path, with correct bytes,
|
|
846
|
+
-- none of the saving, and no way to tell the narrowing never took effect.
|
|
847
|
+
local precision = node.Precision
|
|
848
|
+
if precision == "f32" then
|
|
849
|
+
-- Not a packing constraint (the bounds do not enter the f32 encoding) but a
|
|
850
|
+
-- contradiction: a bound past the binary32 range describes values the encoder
|
|
851
|
+
-- must refuse one by one, so the field would silently spend nine bytes at the
|
|
852
|
+
-- end of the range it was widened to reach.
|
|
853
|
+
if
|
|
854
|
+
(node.Min ~= nil and math.abs(node.Min) > F32_MAX)
|
|
855
|
+
or (node.Max ~= nil and math.abs(node.Max) > F32_MAX)
|
|
856
|
+
then
|
|
857
|
+
compileError(
|
|
858
|
+
path,
|
|
859
|
+
`Scribe.Number Precision = "f32" cannot represent a bound past {F32_MAX}`
|
|
860
|
+
.. ` (Min = {node.Min or "nil"}, Max = {node.Max or "nil"}); drop Precision to keep f64`
|
|
861
|
+
)
|
|
862
|
+
end
|
|
863
|
+
elseif precision ~= nil then
|
|
864
|
+
if type(precision) ~= "number" then
|
|
865
|
+
compileError(
|
|
866
|
+
path,
|
|
867
|
+
`Scribe.Number Precision must be "f32" or a positive number, got a {type(precision)}`
|
|
868
|
+
)
|
|
869
|
+
end
|
|
870
|
+
local p = precision :: number
|
|
871
|
+
if not isFiniteBound(p) or p <= 0 then
|
|
872
|
+
compileError(path, `Scribe.Number Precision must be finite and greater than zero, got {p}`)
|
|
873
|
+
end
|
|
874
|
+
-- A fixed-point grid is measured FROM Min and bounded BY Max: without both
|
|
875
|
+
-- there is no origin to index from and no step count to pick a width from.
|
|
876
|
+
if node.Min == nil or node.Max == nil then
|
|
877
|
+
compileError(path, `Scribe.Number Precision = {p} requires both Min and Max`)
|
|
878
|
+
end
|
|
879
|
+
local min, max = node.Min :: number, node.Max :: number
|
|
880
|
+
-- Min > Max is reported by the shared check below, in its own words; do
|
|
881
|
+
-- not pre-empt it with arithmetic on a negative range.
|
|
882
|
+
if max >= min then
|
|
883
|
+
local steps = quantSteps(min, max, p)
|
|
884
|
+
if steps > Q_MAX_STEPS then
|
|
885
|
+
compileError(
|
|
886
|
+
path,
|
|
887
|
+
`Scribe.Number range {min}..{max} needs {steps} steps of {p}, past the {Q_MAX_STEPS}`
|
|
888
|
+
.. ` a fixed-point field can index; widen Precision, or use Precision = "f32"`
|
|
889
|
+
)
|
|
890
|
+
end
|
|
891
|
+
-- The grid must be coarser than the double under it: at a large
|
|
892
|
+
-- magnitude a double's own spacing can exceed Precision, breaking the
|
|
893
|
+
-- promised error bound before the codec does anything. The step count
|
|
894
|
+
-- above stays small in that case, so test the bounds directly.
|
|
895
|
+
local extreme = math.max(math.abs(min), math.abs(max))
|
|
896
|
+
if extreme + p == extreme or extreme - p == extreme then
|
|
897
|
+
compileError(
|
|
898
|
+
path,
|
|
899
|
+
`Scribe.Number Precision = {p} is finer than a double's own spacing at {extreme},`
|
|
900
|
+
.. ` so the bound cannot step by it; widen Precision or narrow the range`
|
|
901
|
+
)
|
|
902
|
+
end
|
|
903
|
+
end
|
|
904
|
+
end
|
|
905
|
+
elseif node.ValueType == "enum" then
|
|
906
|
+
if not node.MemberIndex or node.MemberIndex[value] == nil then
|
|
907
|
+
compileError(path, "enum default must be one of its members")
|
|
908
|
+
end
|
|
909
|
+
elseif node.ValueType == "big" then
|
|
910
|
+
local parsed = Big.from(value)
|
|
911
|
+
if parsed == nil then
|
|
912
|
+
compileError(path, `Scribe.Big default must be a number or a numeric string, got {tostring(value)}`)
|
|
913
|
+
end
|
|
914
|
+
if node.Min ~= nil and Big.from(node.Min) == nil then
|
|
915
|
+
compileError(path, "Scribe.Big Min must be a number or a numeric string")
|
|
916
|
+
end
|
|
917
|
+
if node.Max ~= nil and Big.from(node.Max) == nil then
|
|
918
|
+
compileError(path, "Scribe.Big Max must be a number or a numeric string")
|
|
919
|
+
end
|
|
920
|
+
elseif node.ValueType == "flags" then
|
|
921
|
+
-- bit32 is 32 bits wide, so a 33rd member would silently fall off the wire
|
|
922
|
+
-- packing rather than round-tripping.
|
|
923
|
+
if #(node.Members :: { string }) > 32 then
|
|
924
|
+
compileError(path, `Scribe.Flags takes at most 32 members, got {#(node.Members :: { string })}`)
|
|
925
|
+
end
|
|
926
|
+
-- A member name is persisted verbatim and is the one persisted string with no
|
|
927
|
+
-- write-path guard, since it comes from the template rather than from a Set:
|
|
928
|
+
-- invalid UTF-8 fails the whole profile save the first time that flag is enabled.
|
|
929
|
+
-- A duplicate is refused because MemberIndex keeps only the last, leaving the
|
|
930
|
+
-- earlier bit unreachable.
|
|
931
|
+
local seenMember: { [string]: boolean } = {}
|
|
932
|
+
for _, member in node.Members :: { string } do
|
|
933
|
+
if type(member) ~= "string" then
|
|
934
|
+
compileError(path, `Scribe.Flags member names must be strings, got a {typeof(member)}`)
|
|
935
|
+
end
|
|
936
|
+
if not Util.isUtf8(member) then
|
|
937
|
+
compileError(
|
|
938
|
+
path,
|
|
939
|
+
`Scribe.Flags member "{member}" contains invalid UTF-8, which would fail the profile save`
|
|
940
|
+
)
|
|
941
|
+
end
|
|
942
|
+
if seenMember[member] then
|
|
943
|
+
compileError(path, `Scribe.Flags declares "{member}" twice; member names must be unique`)
|
|
944
|
+
end
|
|
945
|
+
seenMember[member] = true
|
|
946
|
+
end
|
|
947
|
+
if type(value) ~= "table" then
|
|
948
|
+
compileError(path, "Scribe.Flags default must be a table of member names")
|
|
949
|
+
end
|
|
950
|
+
for _, member in value :: { any } do
|
|
951
|
+
if not node.MemberIndex or node.MemberIndex[member] == nil then
|
|
952
|
+
compileError(path, `Scribe.Flags default contains "{tostring(member)}", which is not a member`)
|
|
953
|
+
end
|
|
954
|
+
end
|
|
955
|
+
elseif node.ValueType == "string" then
|
|
956
|
+
if type(value) ~= "string" then
|
|
957
|
+
compileError(path, "Scribe.String default must be a string")
|
|
958
|
+
end
|
|
959
|
+
-- MaxLength is a byte budget, not a comparison bound: inf or NaN leaves the field
|
|
960
|
+
-- silently unbounded, and a negative value is worse than a no-op, since
|
|
961
|
+
-- truncateUtf8 ends in string.sub(s, 1, cut) and a negative index counts from the
|
|
962
|
+
-- end, quietly deleting the tail of every value.
|
|
963
|
+
if node.MaxLength ~= nil then
|
|
964
|
+
local n = node.MaxLength
|
|
965
|
+
if not isFiniteBound(n) or n % 1 ~= 0 or n < 0 then
|
|
966
|
+
compileError(path, "Scribe.String MaxLength must be a non-negative integer")
|
|
967
|
+
end
|
|
968
|
+
end
|
|
969
|
+
end
|
|
970
|
+
if node.ValueType == "big" then
|
|
971
|
+
-- A big bound past 1.8e308 can only be written as a numeric string, so the pair
|
|
972
|
+
-- has to be ordered by Big.compare: a raw `>` either throws on a mixed pair or
|
|
973
|
+
-- orders two strings lexically, which rejects "2" < "1e50" and accepts the
|
|
974
|
+
-- inverted "1e50" > "2" this guard exists to catch.
|
|
975
|
+
if node.Min ~= nil and node.Max ~= nil then
|
|
976
|
+
local minBig = Big.from(node.Min) :: any
|
|
977
|
+
local maxBig = Big.from(node.Max) :: any
|
|
978
|
+
if Big.compare(minBig, maxBig) > 0 then
|
|
979
|
+
compileError(path, "Min > Max")
|
|
980
|
+
end
|
|
981
|
+
end
|
|
982
|
+
elseif node.Min and node.Max and node.Min > node.Max then
|
|
983
|
+
compileError(path, "Min > Max")
|
|
984
|
+
end
|
|
985
|
+
if timed and type(value) == "table" then
|
|
986
|
+
compileError(path, "Scribe.Timed only wraps leaf values")
|
|
987
|
+
end
|
|
988
|
+
|
|
989
|
+
if node.Kind == "table" then
|
|
990
|
+
if Util.hasNumericKeys(value) then
|
|
991
|
+
-- Array-like default: entries are DATA (deep-cloned, generically encoded),
|
|
992
|
+
-- not schema. rejectNestedMarkers already ran above and refused any
|
|
993
|
+
-- declarator nested in here.
|
|
994
|
+
node.Default = Util.deepClone(value)
|
|
995
|
+
else
|
|
996
|
+
for k in value do
|
|
997
|
+
-- sortedKeys would silently drop a non-string key, compiling a schema
|
|
998
|
+
-- missing the field with no diagnostic at all.
|
|
999
|
+
if type(k) ~= "string" then
|
|
1000
|
+
compileError(path, `record fields must have string names, got a {typeof(k)} key`)
|
|
1001
|
+
end
|
|
1002
|
+
end
|
|
1003
|
+
local children: { [string]: SchemaNode } = {}
|
|
1004
|
+
local order = Util.sortedKeys(value)
|
|
1005
|
+
local ordinal: { [string]: number } = {}
|
|
1006
|
+
local default = {}
|
|
1007
|
+
local hasPacked = false
|
|
1008
|
+
for i, key in order do
|
|
1009
|
+
local childPath = table.clone(path)
|
|
1010
|
+
table.insert(childPath, key)
|
|
1011
|
+
local child = buildNode(state, key, value[key], childPath, visibility, persist, node)
|
|
1012
|
+
children[key] = child
|
|
1013
|
+
ordinal[key] = i
|
|
1014
|
+
default[key] = child.Default
|
|
1015
|
+
-- Bubble the packed marker up (post-order: child is fully built).
|
|
1016
|
+
if isPacked(child) then
|
|
1017
|
+
hasPacked = true
|
|
1018
|
+
end
|
|
1019
|
+
end
|
|
1020
|
+
node.Children = children
|
|
1021
|
+
node.ChildOrder = order
|
|
1022
|
+
node.ChildOrdinal = ordinal
|
|
1023
|
+
node.Default = default
|
|
1024
|
+
node.HasPacked = hasPacked
|
|
1025
|
+
end
|
|
1026
|
+
elseif node.ValueType == "big" then
|
|
1027
|
+
-- The canonical { mantissa, exponent } form, so the schema default matches
|
|
1028
|
+
-- what every write produces rather than the raw declarator argument.
|
|
1029
|
+
node.Default = Big.toStored(Big.from(value) :: any)
|
|
1030
|
+
else
|
|
1031
|
+
node.Default = value
|
|
1032
|
+
end
|
|
1033
|
+
|
|
1034
|
+
-- Collected, not resolved: an input may name a root this walk has not reached
|
|
1035
|
+
-- yet, so Compile finishes the job once every node exists.
|
|
1036
|
+
if derivedInputs ~= nil then
|
|
1037
|
+
local collected = state.Derived
|
|
1038
|
+
if collected == nil then
|
|
1039
|
+
compileError(path, "Scribe.Derived is not supported here")
|
|
1040
|
+
end
|
|
1041
|
+
table.insert(collected :: any, {
|
|
1042
|
+
Node = node,
|
|
1043
|
+
InputPaths = derivedInputs :: { string },
|
|
1044
|
+
Compute = derivedCompute :: (...any) -> any,
|
|
1045
|
+
})
|
|
1046
|
+
end
|
|
1047
|
+
|
|
1048
|
+
-- Scribe.Optional: the inner declarator supplied the type and bounds; the default is
|
|
1049
|
+
-- dropped so the field is neither seeded into a new profile nor filled into a
|
|
1050
|
+
-- partial element write.
|
|
1051
|
+
if nullable then
|
|
1052
|
+
if timed then
|
|
1053
|
+
compileError(path, "Scribe.Optional cannot wrap Scribe.Timed: a lapsed timer restores the default")
|
|
1054
|
+
end
|
|
1055
|
+
if node.Factory then
|
|
1056
|
+
compileError(path, "Scribe.Optional cannot wrap Scribe.Dynamic: a factory exists to seed a value")
|
|
1057
|
+
end
|
|
1058
|
+
if node.Kind == "table" then
|
|
1059
|
+
compileError(path, "Scribe.Optional only wraps leaf values")
|
|
1060
|
+
end
|
|
1061
|
+
node.Nullable = true
|
|
1062
|
+
node.Default = nil
|
|
1063
|
+
end
|
|
1064
|
+
|
|
1065
|
+
return node
|
|
1066
|
+
end
|
|
1067
|
+
|
|
1068
|
+
-- Reserved internal roots: built server-only by default, then per-subkey
|
|
1069
|
+
-- visibility applied explicitly so the rules are exact.
|
|
1070
|
+
local function buildInternalRoots(state: any, root: SchemaNode, config: CompileConfig)
|
|
1071
|
+
local scribeTemplate = {
|
|
1072
|
+
-- GiftAims is not a second PendingGifts: a pending gift is a live intent counted
|
|
1073
|
+
-- against GiftMaxPending, an aim is the recipient identity that survives a stale
|
|
1074
|
+
-- prompt so a late receipt can still be routed. They expire on separate clocks;
|
|
1075
|
+
-- see the GIFT AIM block in Server/Monetization.
|
|
1076
|
+
GiftAims = {},
|
|
1077
|
+
GiftCredits = {},
|
|
1078
|
+
PendingGifts = {},
|
|
1079
|
+
Perks = {},
|
|
1080
|
+
ProcessedPurchaseIds = {},
|
|
1081
|
+
ReceiptReservations = {},
|
|
1082
|
+
PurchaseLogs = {
|
|
1083
|
+
InGame = {},
|
|
1084
|
+
Robux = {},
|
|
1085
|
+
},
|
|
1086
|
+
-- Exchange holds the in-flight record per exchange id; ExchangeInbox holds value
|
|
1087
|
+
-- settled to this player but not yet delivered onto a game path. Untyped, like
|
|
1088
|
+
-- PendingGifts, because a settle must not be refusable by a declared shape.
|
|
1089
|
+
Exchange = {},
|
|
1090
|
+
ExchangeInbox = {},
|
|
1091
|
+
Timed = {},
|
|
1092
|
+
-- Per periodic board: the gain baseline and the first period written, for the erase sweep.
|
|
1093
|
+
Boards = {},
|
|
1094
|
+
Version = Marker.make("Int", 1, { Min = 0 }),
|
|
1095
|
+
}
|
|
1096
|
+
|
|
1097
|
+
local scribeNode = buildNode(state, RESERVED_ROOT, scribeTemplate, { RESERVED_ROOT }, "ServerOnly", true, root)
|
|
1098
|
+
local children = scribeNode.Children :: { [string]: SchemaNode }
|
|
1099
|
+
local function setVisibility(node: SchemaNode, visibility: Visibility)
|
|
1100
|
+
node.Visibility = visibility
|
|
1101
|
+
if node.Children then
|
|
1102
|
+
for _, child in node.Children do
|
|
1103
|
+
setVisibility(child, visibility)
|
|
1104
|
+
end
|
|
1105
|
+
end
|
|
1106
|
+
end
|
|
1107
|
+
setVisibility(children.Perks, "Replicated")
|
|
1108
|
+
setVisibility(children.GiftCredits, "Replicated")
|
|
1109
|
+
-- Purchase logs are opt-in per kind (PurchaseLog.ReplicateRobux/InGame);
|
|
1110
|
+
-- the container itself only replicates when at least one kind does, so the
|
|
1111
|
+
-- default sends nothing at all.
|
|
1112
|
+
local logs = children.PurchaseLogs
|
|
1113
|
+
local replicateRobux = config.ReplicateRobuxLog == true
|
|
1114
|
+
local replicateInGame = config.ReplicateInGameLog == true
|
|
1115
|
+
logs.Visibility = if replicateRobux or replicateInGame then "Replicated" else "ServerOnly"
|
|
1116
|
+
local logChildren = logs.Children :: { [string]: SchemaNode }
|
|
1117
|
+
setVisibility(logChildren.Robux, (if replicateRobux then "Replicated" else "ServerOnly") :: Visibility)
|
|
1118
|
+
setVisibility(logChildren.InGame, (if replicateInGame then "Replicated" else "ServerOnly") :: Visibility)
|
|
1119
|
+
|
|
1120
|
+
-- _ScribeSession: never persisted, replicated to the owner. Holds the pass/Plus
|
|
1121
|
+
-- ownership cache, the player's own save info, and a sync flag the server flips
|
|
1122
|
+
-- true once the async gamepass refresh completes, so the client can await it
|
|
1123
|
+
-- before trusting OwnsCache (see Client/Server OwnsAsync).
|
|
1124
|
+
local sessionTemplate = {
|
|
1125
|
+
OwnsCache = {},
|
|
1126
|
+
SaveInfo = {},
|
|
1127
|
+
OwnsSynced = false,
|
|
1128
|
+
Timed = {},
|
|
1129
|
+
}
|
|
1130
|
+
local sessionNode = buildNode(state, SESSION_ROOT, sessionTemplate, { SESSION_ROOT }, "Replicated", false, root)
|
|
1131
|
+
|
|
1132
|
+
return scribeNode, sessionNode
|
|
1133
|
+
end
|
|
1134
|
+
|
|
1135
|
+
-- A DataStore serializes every object key to a JSON string, so a Scribe.MapOf with
|
|
1136
|
+
-- integer keys comes back holding "123" where it stored 123. The declared key type is
|
|
1137
|
+
-- what makes converting them back unambiguous. Runs on raw stored data before
|
|
1138
|
+
-- Reconcile, so every later read sees the keys the template promised.
|
|
1139
|
+
function Template.CoerceMapKeys(compiled: Compiled, data: any)
|
|
1140
|
+
local function walk(node: SchemaNode, value: any, depth: number)
|
|
1141
|
+
if type(value) ~= "table" or depth > 32 then
|
|
1142
|
+
return
|
|
1143
|
+
end
|
|
1144
|
+
if node.Container == "Dict" and node.KeyType == "integer" then
|
|
1145
|
+
local rename: { [string]: number }? = nil
|
|
1146
|
+
local blocked = false
|
|
1147
|
+
for key in value do
|
|
1148
|
+
if type(key) == "string" then
|
|
1149
|
+
local asNumber = tonumber(key)
|
|
1150
|
+
-- Only a canonical integer spelling converts. A key like "07" or
|
|
1151
|
+
-- "1.5" was never written by this map, so leaving it alone keeps
|
|
1152
|
+
-- foreign data intact rather than silently relocating it.
|
|
1153
|
+
if asNumber ~= nil and asNumber % 1 == 0 and tostring(asNumber) == key then
|
|
1154
|
+
rename = rename or {}
|
|
1155
|
+
(rename :: { [string]: number })[key] = asNumber
|
|
1156
|
+
else
|
|
1157
|
+
blocked = true
|
|
1158
|
+
end
|
|
1159
|
+
end
|
|
1160
|
+
end
|
|
1161
|
+
-- ALL of them or none. Converting only the canonical ones leaves the
|
|
1162
|
+
-- container holding a number key and a string key at once, a mixed table
|
|
1163
|
+
-- no DataStore will store, so every save for that profile would fail.
|
|
1164
|
+
if rename and not blocked then
|
|
1165
|
+
for from, to in rename do
|
|
1166
|
+
value[to] = value[from]
|
|
1167
|
+
value[from] = nil
|
|
1168
|
+
end
|
|
1169
|
+
end
|
|
1170
|
+
end
|
|
1171
|
+
local children = node.Children
|
|
1172
|
+
if children then
|
|
1173
|
+
for name, child in children do
|
|
1174
|
+
walk(child, value[name], depth + 1)
|
|
1175
|
+
end
|
|
1176
|
+
elseif node.Container ~= nil then
|
|
1177
|
+
for key in value do
|
|
1178
|
+
local element = Template.ChildSchema(node, key)
|
|
1179
|
+
if element then
|
|
1180
|
+
walk(element, value[key], depth + 1)
|
|
1181
|
+
end
|
|
1182
|
+
end
|
|
1183
|
+
end
|
|
1184
|
+
end
|
|
1185
|
+
walk(compiled.Root, data, 0)
|
|
1186
|
+
end
|
|
1187
|
+
|
|
1188
|
+
function Template.Compile(userTemplate: any, config: CompileConfig?): Compiled
|
|
1189
|
+
local cfg: CompileConfig = config or {}
|
|
1190
|
+
if type(userTemplate) ~= "table" then
|
|
1191
|
+
error("Scribe: Template must be a table", 0)
|
|
1192
|
+
end
|
|
1193
|
+
for key in userTemplate do
|
|
1194
|
+
if type(key) ~= "string" then
|
|
1195
|
+
error("Scribe: template root keys must be strings", 0)
|
|
1196
|
+
end
|
|
1197
|
+
-- A top-level field's pathKey is just its name, so a root named "@cd|Daily"
|
|
1198
|
+
-- would collide with the cooldown slot of the same name. Nested fields are
|
|
1199
|
+
-- safe: their pathKeys always contain the \31 separator, which a cooldown key
|
|
1200
|
+
-- never has.
|
|
1201
|
+
if string.sub(key, 1, 3) == "@cd" then
|
|
1202
|
+
error(
|
|
1203
|
+
`Scribe: template may not declare a "{key}" key: the "{COOLDOWN_PREFIX}" prefix is reserved for cooldown slots`,
|
|
1204
|
+
0
|
|
1205
|
+
)
|
|
1206
|
+
end
|
|
1207
|
+
if string.sub(key, 1, #RESERVED_ROOT) == RESERVED_ROOT then
|
|
1208
|
+
error(`Scribe: template may not declare a "{key}" key: the {RESERVED_ROOT} root is library-owned`, 0)
|
|
1209
|
+
end
|
|
1210
|
+
end
|
|
1211
|
+
|
|
1212
|
+
-- Held separately as well as on `state`, so the post-pass below reads it without
|
|
1213
|
+
-- the optionality buildNode's signature needs for the element-shape case.
|
|
1214
|
+
local pendingDerived: { PendingDerived } = {}
|
|
1215
|
+
local state: CompileState = { NextId = 1, ById = {} :: { [number]: SchemaNode }, Derived = pendingDerived }
|
|
1216
|
+
local root: SchemaNode = {
|
|
1217
|
+
Id = 0,
|
|
1218
|
+
Name = nil,
|
|
1219
|
+
Path = {},
|
|
1220
|
+
Kind = "table",
|
|
1221
|
+
ValueType = "table",
|
|
1222
|
+
Visibility = "Replicated",
|
|
1223
|
+
Persist = true,
|
|
1224
|
+
Timed = false,
|
|
1225
|
+
Default = nil,
|
|
1226
|
+
Parent = nil,
|
|
1227
|
+
}
|
|
1228
|
+
state.ById[0] = root
|
|
1229
|
+
|
|
1230
|
+
local children: { [string]: SchemaNode } = {}
|
|
1231
|
+
local userOrder = Util.sortedKeys(userTemplate)
|
|
1232
|
+
for _, key in userOrder do
|
|
1233
|
+
children[key] = buildNode(state, key, userTemplate[key], { key }, "Replicated", true, root)
|
|
1234
|
+
end
|
|
1235
|
+
|
|
1236
|
+
-- persist = false is what keeps these out of every save.
|
|
1237
|
+
local storeTemplate = cfg.ServerStore
|
|
1238
|
+
local storeOrder: { string } = {}
|
|
1239
|
+
if storeTemplate ~= nil then
|
|
1240
|
+
if type(storeTemplate) ~= "table" then
|
|
1241
|
+
error("Scribe: ServerStore must be a table", 0)
|
|
1242
|
+
end
|
|
1243
|
+
storeOrder = Util.sortedKeys(storeTemplate)
|
|
1244
|
+
for _, key in storeOrder do
|
|
1245
|
+
if type(key) ~= "string" then
|
|
1246
|
+
error("Scribe: ServerStore root keys must be strings", 0)
|
|
1247
|
+
end
|
|
1248
|
+
if string.sub(key, 1, 3) == "@cd" or string.sub(key, 1, #RESERVED_ROOT) == RESERVED_ROOT then
|
|
1249
|
+
error(`Scribe: ServerStore may not declare a "{key}" key: that prefix is library-owned`, 0)
|
|
1250
|
+
end
|
|
1251
|
+
if children[key] ~= nil then
|
|
1252
|
+
error(
|
|
1253
|
+
`Scribe: ServerStore declares "{key}", which the Template already declares. The two share `
|
|
1254
|
+
.. "one field-id space and one schema, so one would silently shadow the other. Rename one.",
|
|
1255
|
+
0
|
|
1256
|
+
)
|
|
1257
|
+
end
|
|
1258
|
+
-- Caught on the declarator: it cannot be told apart after building.
|
|
1259
|
+
local markerKind = Marker.inspect(storeTemplate[key])
|
|
1260
|
+
if markerKind == "Session" then
|
|
1261
|
+
error(
|
|
1262
|
+
`Scribe: ServerStore root "{key}" is Scribe.Session. A server store is never saved, so the `
|
|
1263
|
+
.. "marker sets nothing that is not already true. Drop the wrapper.",
|
|
1264
|
+
0
|
|
1265
|
+
)
|
|
1266
|
+
end
|
|
1267
|
+
local node = buildNode(state, key, storeTemplate[key], { key }, "Replicated", false, root)
|
|
1268
|
+
children[key] = node
|
|
1269
|
+
|
|
1270
|
+
-- Load-bearing, not tidiness: hasShared scans every child of the root, so one
|
|
1271
|
+
-- Shared store root switches on the whole per-player fanout.
|
|
1272
|
+
if node.Visibility == "Shared" then
|
|
1273
|
+
error(
|
|
1274
|
+
`Scribe: ServerStore root "{key}" is Scribe.Shared. Every store root already reaches every `
|
|
1275
|
+
.. "client, and a store has no owning player for Shared to name. Drop the wrapper, or use "
|
|
1276
|
+
.. "Scribe.ServerOnly to keep it off the wire.",
|
|
1277
|
+
0
|
|
1278
|
+
)
|
|
1279
|
+
end
|
|
1280
|
+
|
|
1281
|
+
-- A deadline is swept per profile entry and a Dynamic factory is sampled per profile
|
|
1282
|
+
-- load. A store has neither, and both would fail silently.
|
|
1283
|
+
local function refuseSubtree(n: SchemaNode)
|
|
1284
|
+
local where = if n.Name then `"{Util.pathString(n.Path :: any)}"` else `root "{key}"`
|
|
1285
|
+
if n.Timed then
|
|
1286
|
+
error(
|
|
1287
|
+
`Scribe: ServerStore field {where} is Scribe.Timed. A deadline lives in a player's `
|
|
1288
|
+
.. "_Scribe.Timed dict and is swept per profile, so a server store has nowhere to "
|
|
1289
|
+
.. "hold one and nothing to expire it.",
|
|
1290
|
+
0
|
|
1291
|
+
)
|
|
1292
|
+
end
|
|
1293
|
+
if n.Factory ~= nil then
|
|
1294
|
+
error(
|
|
1295
|
+
`Scribe: ServerStore field {where} is Scribe.Dynamic. The factory is sampled once when `
|
|
1296
|
+
.. "a brand-new profile is created, and a store has no profile. Set the value from "
|
|
1297
|
+
.. "your own code after the bundle is built.",
|
|
1298
|
+
0
|
|
1299
|
+
)
|
|
1300
|
+
end
|
|
1301
|
+
if n.Children then
|
|
1302
|
+
for _, child in n.Children do
|
|
1303
|
+
refuseSubtree(child)
|
|
1304
|
+
end
|
|
1305
|
+
end
|
|
1306
|
+
if n.AnyChild then
|
|
1307
|
+
refuseSubtree(n.AnyChild)
|
|
1308
|
+
end
|
|
1309
|
+
end
|
|
1310
|
+
refuseSubtree(node)
|
|
1311
|
+
end
|
|
1312
|
+
end
|
|
1313
|
+
|
|
1314
|
+
local scribeNode, sessionNode = buildInternalRoots(state, root, cfg)
|
|
1315
|
+
children[RESERVED_ROOT] = scribeNode
|
|
1316
|
+
children[SESSION_ROOT] = sessionNode
|
|
1317
|
+
|
|
1318
|
+
local order = table.clone(userOrder)
|
|
1319
|
+
for _, key in storeOrder do
|
|
1320
|
+
table.insert(order, key)
|
|
1321
|
+
end
|
|
1322
|
+
table.insert(order, RESERVED_ROOT)
|
|
1323
|
+
table.insert(order, SESSION_ROOT)
|
|
1324
|
+
table.sort(order)
|
|
1325
|
+
|
|
1326
|
+
local ordinal: { [string]: number } = {}
|
|
1327
|
+
for i, key in order do
|
|
1328
|
+
ordinal[key] = i
|
|
1329
|
+
end
|
|
1330
|
+
root.Children = children
|
|
1331
|
+
root.ChildOrder = order
|
|
1332
|
+
root.ChildOrdinal = ordinal
|
|
1333
|
+
-- The root node is hand-built here rather than by buildNode, so bubble its
|
|
1334
|
+
-- HasPacked flag the same way (else a whole-data Get()/Clone() on the root
|
|
1335
|
+
-- accessor would leak packed buffers for a ROOT-level datatype field).
|
|
1336
|
+
local rootHasPacked = false
|
|
1337
|
+
for _, child in children do
|
|
1338
|
+
if isPacked(child) then
|
|
1339
|
+
rootHasPacked = true
|
|
1340
|
+
break
|
|
1341
|
+
end
|
|
1342
|
+
end
|
|
1343
|
+
root.HasPacked = rootHasPacked
|
|
1344
|
+
|
|
1345
|
+
-- Scribe.Shared cannot appear below a root field, so this scan is exhaustive.
|
|
1346
|
+
local hasShared = false
|
|
1347
|
+
for _, child in children do
|
|
1348
|
+
if child.Visibility == "Shared" then
|
|
1349
|
+
hasShared = true
|
|
1350
|
+
break
|
|
1351
|
+
end
|
|
1352
|
+
end
|
|
1353
|
+
|
|
1354
|
+
-- Derived fields, once every node they could name exists: resolve the input
|
|
1355
|
+
-- paths, order the graph, decide who computes each field, and seed the defaults.
|
|
1356
|
+
-- Before the hash fold, which folds the result.
|
|
1357
|
+
local derivedNodes: { SchemaNode } = {}
|
|
1358
|
+
local derivedByWrite: { [string]: { SchemaNode } } = {}
|
|
1359
|
+
if #pendingDerived > 0 then
|
|
1360
|
+
local reservedRoots = { [RESERVED_ROOT] = true, [SESSION_ROOT] = true }
|
|
1361
|
+
derivedNodes, derivedByWrite =
|
|
1362
|
+
DerivedModule.Resolve(root, pendingDerived :: any, reservedRoots, compileError :: any)
|
|
1363
|
+
DerivedModule.SeedDefaults(derivedNodes :: any, compileError :: any)
|
|
1364
|
+
|
|
1365
|
+
-- A derived field recomputes on whichever tree took the write, so an input on the
|
|
1366
|
+
-- far side would settle into the wrong one.
|
|
1367
|
+
if storeTemplate ~= nil then
|
|
1368
|
+
local function isStoreRoot(path: { any }): boolean
|
|
1369
|
+
return #path > 0 and storeTemplate[path[1]] ~= nil
|
|
1370
|
+
end
|
|
1371
|
+
for _, node in derivedNodes do
|
|
1372
|
+
local spec = (node :: any).Derived
|
|
1373
|
+
if spec ~= nil and spec.Inputs ~= nil then
|
|
1374
|
+
local outputInStore = isStoreRoot(node.Path)
|
|
1375
|
+
for _, input in spec.Inputs do
|
|
1376
|
+
if isStoreRoot(input.Path) ~= outputInStore then
|
|
1377
|
+
error(
|
|
1378
|
+
`Scribe: derived field "{Util.pathString(node.Path)}" reads `
|
|
1379
|
+
.. `"{Util.pathString(input.Path)}", which is on the other side of the `
|
|
1380
|
+
.. "ServerStore boundary. A derived field recomputes on whichever tree took "
|
|
1381
|
+
.. "the write, and the two trees hold different data.",
|
|
1382
|
+
0
|
|
1383
|
+
)
|
|
1384
|
+
end
|
|
1385
|
+
end
|
|
1386
|
+
end
|
|
1387
|
+
end
|
|
1388
|
+
end
|
|
1389
|
+
-- A record's Default table was composed from its children while they were
|
|
1390
|
+
-- built, so a nested derived field's freshly seeded default has to be written
|
|
1391
|
+
-- back up: anything reading a record's Default directly would otherwise see
|
|
1392
|
+
-- the output declarator's default rather than the computed one.
|
|
1393
|
+
for _, node in derivedNodes do
|
|
1394
|
+
local child = node
|
|
1395
|
+
local parent = node.Parent
|
|
1396
|
+
while parent ~= nil and type(parent.Default) == "table" and child.Name ~= nil do
|
|
1397
|
+
(parent.Default :: { [string]: any })[child.Name :: string] = child.Default
|
|
1398
|
+
child = parent
|
|
1399
|
+
parent = parent.Parent
|
|
1400
|
+
end
|
|
1401
|
+
end
|
|
1402
|
+
end
|
|
1403
|
+
|
|
1404
|
+
-- Folded into the schema hash below: Transmit decides whether the field crosses
|
|
1405
|
+
-- the wire at all, and the input set decides what a locally computing client
|
|
1406
|
+
-- reads, so a drift in either has to fail the handshake rather than diverge.
|
|
1407
|
+
local function derivedSig(node: SchemaNode): string
|
|
1408
|
+
local spec = node.Derived
|
|
1409
|
+
if spec == nil then
|
|
1410
|
+
return "nil"
|
|
1411
|
+
end
|
|
1412
|
+
local ids = table.create(#spec.Inputs)
|
|
1413
|
+
for i, input in spec.Inputs do
|
|
1414
|
+
ids[i] = tostring(input.Id)
|
|
1415
|
+
end
|
|
1416
|
+
return `d{if spec.Transmit then "1" else "0"}:{table.concat(ids, ",")}`
|
|
1417
|
+
end
|
|
1418
|
+
|
|
1419
|
+
--- Precision drives a float's wire width, so it belongs in the hash for the same
|
|
1420
|
+
--- reason Min/Max do. %.17g rather than tostring: 17 significant digits round-trip
|
|
1421
|
+
--- every double, so the fold does not depend on tostring's shortest-round-trip
|
|
1422
|
+
--- behaviour, which nothing here pins.
|
|
1423
|
+
local function precisionSig(n: SchemaNode): string
|
|
1424
|
+
local p = n.Precision
|
|
1425
|
+
if p == nil then
|
|
1426
|
+
return "nil"
|
|
1427
|
+
elseif type(p) == "number" then
|
|
1428
|
+
return string.format("%.17g", p)
|
|
1429
|
+
end
|
|
1430
|
+
return tostring(p)
|
|
1431
|
+
end
|
|
1432
|
+
|
|
1433
|
+
-- The hash must fold every field that affects the wire byte layout, or a
|
|
1434
|
+
-- server/client schema drift decodes silently wrong. Min/Max drive int
|
|
1435
|
+
-- width; Precision drives float width; Members drive enum indexing;
|
|
1436
|
+
-- Datatype/MaxLength are semantic.
|
|
1437
|
+
local hash = 2166136261
|
|
1438
|
+
for id = 0, state.NextId - 1 do
|
|
1439
|
+
local node = state.ById[id]
|
|
1440
|
+
if node then
|
|
1441
|
+
local members = ""
|
|
1442
|
+
if node.Members then
|
|
1443
|
+
local parts = table.create(#node.Members)
|
|
1444
|
+
for i, m in node.Members do
|
|
1445
|
+
parts[i] = `{#m}:{m}`
|
|
1446
|
+
end
|
|
1447
|
+
members = table.concat(parts, ",")
|
|
1448
|
+
end
|
|
1449
|
+
hash = Util.fnv32(
|
|
1450
|
+
-- Persist is folded too: without it a stale copy that moved a field
|
|
1451
|
+
-- on or off Session would hash identically to the current one.
|
|
1452
|
+
`{id}:{node.Name or ""}:{node.ValueType}:{node.Visibility}:{node.Persist}`
|
|
1453
|
+
.. `:{node.Min or "nil"}:{node.Max or "nil"}:{precisionSig(node)}:{node.MaxLength or "nil"}`
|
|
1454
|
+
.. `:{node.Datatype or "nil"}:{members}:{node.Container or "nil"}`
|
|
1455
|
+
.. `:{node.MaxItems or "nil"}:{node.Evict or "nil"}:{if node.Unique then "u" else "nil"}:{node.KeyType or "nil"}:{node.MaxKeys or "nil"}:{node.MaxKeyLength or "nil"}`
|
|
1456
|
+
.. `:{node.Nullable == true}:{if node.ChildOrder then #node.ChildOrder else -1}`
|
|
1457
|
+
.. `:{derivedSig(node)}`,
|
|
1458
|
+
hash
|
|
1459
|
+
)
|
|
1460
|
+
end
|
|
1461
|
+
end
|
|
1462
|
+
|
|
1463
|
+
-- Element subtrees carry no ids, so the ById fold above cannot see them, but their
|
|
1464
|
+
-- Min/Max/Precision drive scalar width and their Members drive enum indexing: an
|
|
1465
|
+
-- element-only drift would pass the Hello schema guard and then decode every
|
|
1466
|
+
-- following op in the frame as garbage. ChildOrder is sorted at compile time, so the
|
|
1467
|
+
-- walk order is identical on both realms.
|
|
1468
|
+
local elementOrdinal = 0
|
|
1469
|
+
local function foldElementNode(n: SchemaNode)
|
|
1470
|
+
local members = ""
|
|
1471
|
+
if n.Members then
|
|
1472
|
+
local parts = table.create(#n.Members)
|
|
1473
|
+
for i, m in n.Members do
|
|
1474
|
+
parts[i] = `{#m}:{m}`
|
|
1475
|
+
end
|
|
1476
|
+
members = table.concat(parts, ",")
|
|
1477
|
+
end
|
|
1478
|
+
-- Leaf defaults matter here, unlike static nodes whose defaults only seed new
|
|
1479
|
+
-- profiles server-side: mirrors materialize fresh element entries from these,
|
|
1480
|
+
-- so a drift would seed different content on each realm.
|
|
1481
|
+
local dflt = ""
|
|
1482
|
+
local d = n.Default
|
|
1483
|
+
local dt = type(d)
|
|
1484
|
+
if dt == "boolean" or dt == "string" then
|
|
1485
|
+
dflt = tostring(d)
|
|
1486
|
+
elseif dt == "number" then
|
|
1487
|
+
dflt = string.format("%.17g", d)
|
|
1488
|
+
elseif dt == "buffer" then
|
|
1489
|
+
dflt = buffer.tostring(d)
|
|
1490
|
+
elseif n.ValueType == "big" and dt == "table" then
|
|
1491
|
+
-- A big's default is the stored { mantissa, exponent } pair, not a scalar,
|
|
1492
|
+
-- so the branches above skip it and a drift in one would otherwise hash
|
|
1493
|
+
-- identically on both realms.
|
|
1494
|
+
dflt = string.format("%.17g:%.17g", (d :: any)[1], (d :: any)[2])
|
|
1495
|
+
end
|
|
1496
|
+
hash = Util.fnv32(
|
|
1497
|
+
`@{elementOrdinal}:{n.Name or ""}:{n.ValueType}:{n.Visibility}`
|
|
1498
|
+
.. `:{n.Min or "nil"}:{n.Max or "nil"}:{precisionSig(n)}:{n.MaxLength or "nil"}`
|
|
1499
|
+
.. `:{n.Datatype or "nil"}:{members}:{n.Container or "nil"}`
|
|
1500
|
+
.. `:{n.MaxItems or "nil"}:{n.Evict or "nil"}:{if n.Unique then "u" else "nil"}:{n.KeyType or "nil"}:{n.MaxKeys or "nil"}:{n.MaxKeyLength or "nil"}`
|
|
1501
|
+
.. `:{n.Nullable == true}:{if n.ChildOrder then #n.ChildOrder else -1}`
|
|
1502
|
+
.. `:{#dflt}:{dflt}`,
|
|
1503
|
+
hash
|
|
1504
|
+
)
|
|
1505
|
+
elementOrdinal += 1
|
|
1506
|
+
local nodeChildren = n.Children
|
|
1507
|
+
if n.ChildOrder and nodeChildren then
|
|
1508
|
+
for _, key in n.ChildOrder do
|
|
1509
|
+
foldElementNode(nodeChildren[key])
|
|
1510
|
+
end
|
|
1511
|
+
end
|
|
1512
|
+
if n.AnyChild then
|
|
1513
|
+
foldElementNode(n.AnyChild)
|
|
1514
|
+
end
|
|
1515
|
+
-- Subtree terminator: without it a field moved from a sub-record up to the
|
|
1516
|
+
-- element root folds to the same preorder byte stream as before the move.
|
|
1517
|
+
hash = Util.fnv32("/", hash)
|
|
1518
|
+
end
|
|
1519
|
+
local function foldElements(n: SchemaNode)
|
|
1520
|
+
local anyChild = n.AnyChild
|
|
1521
|
+
if anyChild and anyChild.IsElement then
|
|
1522
|
+
foldElementNode(anyChild)
|
|
1523
|
+
end
|
|
1524
|
+
local nodeChildren = n.Children
|
|
1525
|
+
if n.ChildOrder and nodeChildren then
|
|
1526
|
+
for _, key in n.ChildOrder do
|
|
1527
|
+
foldElements(nodeChildren[key])
|
|
1528
|
+
end
|
|
1529
|
+
end
|
|
1530
|
+
end
|
|
1531
|
+
foldElements(root)
|
|
1532
|
+
|
|
1533
|
+
-- Flatten the fields carrying a Scribe.Dynamic factory (in id order), so the
|
|
1534
|
+
-- load path can seed them on a new profile without walking the whole tree.
|
|
1535
|
+
local dynamicNodes: { SchemaNode } = {}
|
|
1536
|
+
for id = 0, state.NextId - 1 do
|
|
1537
|
+
local node = state.ById[id]
|
|
1538
|
+
if node and node.Factory then
|
|
1539
|
+
table.insert(dynamicNodes, node)
|
|
1540
|
+
end
|
|
1541
|
+
end
|
|
1542
|
+
|
|
1543
|
+
local compiled: Compiled = {
|
|
1544
|
+
Root = root,
|
|
1545
|
+
ById = state.ById,
|
|
1546
|
+
NodeCount = state.NextId,
|
|
1547
|
+
Hash = hash,
|
|
1548
|
+
RootOrder = order,
|
|
1549
|
+
HasShared = hasShared,
|
|
1550
|
+
DynamicNodes = dynamicNodes,
|
|
1551
|
+
DerivedNodes = derivedNodes,
|
|
1552
|
+
DerivedByWrite = derivedByWrite,
|
|
1553
|
+
Views = nil :: any,
|
|
1554
|
+
Config = cfg,
|
|
1555
|
+
}
|
|
1556
|
+
|
|
1557
|
+
-- A view is the compiled with its root scoped to a subset of the children. Node reads
|
|
1558
|
+
-- only Root, DerivedByWrite, DerivedNodes and Template.Resolve, so this costs nothing
|
|
1559
|
+
-- in Node itself.
|
|
1560
|
+
local function makeView(keys: { string }): Compiled
|
|
1561
|
+
local viewChildren: { [string]: SchemaNode } = {}
|
|
1562
|
+
local viewOrdinal: { [string]: number } = {}
|
|
1563
|
+
local viewShared = false
|
|
1564
|
+
for index, key in keys do
|
|
1565
|
+
local child = children[key]
|
|
1566
|
+
viewChildren[key] = child
|
|
1567
|
+
viewOrdinal[key] = index
|
|
1568
|
+
if child.Visibility == "Shared" then
|
|
1569
|
+
viewShared = true
|
|
1570
|
+
end
|
|
1571
|
+
end
|
|
1572
|
+
local viewRoot: SchemaNode = table.clone(root)
|
|
1573
|
+
-- No Id: a view must never reach an encoder. EncodePath would write id 0 and decode
|
|
1574
|
+
-- to a valid but schemaless path instead of raising.
|
|
1575
|
+
viewRoot.Id = nil
|
|
1576
|
+
viewRoot.Children = viewChildren
|
|
1577
|
+
viewRoot.ChildOrder = keys
|
|
1578
|
+
viewRoot.ChildOrdinal = viewOrdinal
|
|
1579
|
+
local view: Compiled = table.clone(compiled)
|
|
1580
|
+
view.Root = viewRoot
|
|
1581
|
+
view.RootOrder = keys
|
|
1582
|
+
view.HasShared = viewShared
|
|
1583
|
+
return view
|
|
1584
|
+
end
|
|
1585
|
+
|
|
1586
|
+
if #storeOrder == 0 then
|
|
1587
|
+
-- No store, so the player view IS the compiled and nothing else changes shape.
|
|
1588
|
+
compiled.Views = { Player = compiled, Store = nil }
|
|
1589
|
+
else
|
|
1590
|
+
local declared = storeTemplate :: { [string]: any }
|
|
1591
|
+
local playerKeys: { string } = {}
|
|
1592
|
+
for _, key in order do
|
|
1593
|
+
if declared[key] == nil then
|
|
1594
|
+
table.insert(playerKeys, key)
|
|
1595
|
+
end
|
|
1596
|
+
end
|
|
1597
|
+
compiled.Views = { Player = makeView(playerKeys), Store = makeView(table.clone(storeOrder)) }
|
|
1598
|
+
end
|
|
1599
|
+
return compiled
|
|
1600
|
+
end
|
|
1601
|
+
|
|
1602
|
+
-- Shared with Node, whose read paths all have to agree on which nodes need an unpack.
|
|
1603
|
+
function Template.IsPacked(node: SchemaNode?): boolean
|
|
1604
|
+
return node ~= nil and isPacked(node)
|
|
1605
|
+
end
|
|
1606
|
+
|
|
1607
|
+
-- Schema node for a child key: the static child when one exists, otherwise a cached
|
|
1608
|
+
-- dynamic pseudo-node inheriting the parent's visibility. Returns nil for children of
|
|
1609
|
+
-- leaves.
|
|
1610
|
+
function Template.ChildSchema(node: SchemaNode, key: string | number): SchemaNode?
|
|
1611
|
+
if node.Kind == "leaf" then
|
|
1612
|
+
return nil
|
|
1613
|
+
end
|
|
1614
|
+
if type(key) == "string" and node.Children then
|
|
1615
|
+
local child = node.Children[key]
|
|
1616
|
+
if child then
|
|
1617
|
+
return child
|
|
1618
|
+
end
|
|
1619
|
+
end
|
|
1620
|
+
-- A compiled element record has a fixed field set, so an undeclared key resolves
|
|
1621
|
+
-- to nothing and the caller rejects the write. Without this, ChildSchema would
|
|
1622
|
+
-- synthesize a generic `any` node and CACHE it on the shared element schema,
|
|
1623
|
+
-- which both accepts the typo forever and mutates the compiled tree at runtime.
|
|
1624
|
+
if node.Closed then
|
|
1625
|
+
return nil
|
|
1626
|
+
end
|
|
1627
|
+
local anyChild = node.AnyChild
|
|
1628
|
+
if not anyChild then
|
|
1629
|
+
local created: SchemaNode = {
|
|
1630
|
+
Id = nil,
|
|
1631
|
+
Name = nil,
|
|
1632
|
+
Path = node.Path,
|
|
1633
|
+
Kind = "any",
|
|
1634
|
+
ValueType = "any",
|
|
1635
|
+
Persist = node.Persist,
|
|
1636
|
+
Visibility = node.Visibility,
|
|
1637
|
+
Timed = false,
|
|
1638
|
+
Default = nil,
|
|
1639
|
+
Parent = node,
|
|
1640
|
+
}
|
|
1641
|
+
node.AnyChild = created
|
|
1642
|
+
anyChild = created
|
|
1643
|
+
end
|
|
1644
|
+
return anyChild
|
|
1645
|
+
end
|
|
1646
|
+
|
|
1647
|
+
-- Resolve a path to (deepest static schema node, index of the first dynamic
|
|
1648
|
+
-- segment). If the whole path is static, the index is #path + 1.
|
|
1649
|
+
function Template.Resolve(compiled: Compiled, path: { string | number }): (SchemaNode, number)
|
|
1650
|
+
local node = compiled.Root
|
|
1651
|
+
for i, seg in path do
|
|
1652
|
+
if type(seg) == "string" and node.Children and node.Children[seg] then
|
|
1653
|
+
node = node.Children[seg]
|
|
1654
|
+
else
|
|
1655
|
+
return node, i
|
|
1656
|
+
end
|
|
1657
|
+
end
|
|
1658
|
+
return node, #path + 1
|
|
1659
|
+
end
|
|
1660
|
+
|
|
1661
|
+
-- Effective visibility of a path (deepest static node's visibility; dynamic
|
|
1662
|
+
-- segments inherit).
|
|
1663
|
+
function Template.VisibilityOf(compiled: Compiled, path: { string | number }): Visibility
|
|
1664
|
+
local node = Template.Resolve(compiled, path)
|
|
1665
|
+
return node.Visibility
|
|
1666
|
+
end
|
|
1667
|
+
|
|
1668
|
+
-- The persistence axis, for callers that only have a path. Separate from
|
|
1669
|
+
-- VisibilityOf because a field can be Session (never saves) AND ServerOnly or
|
|
1670
|
+
-- Shared (who receives it) at the same time.
|
|
1671
|
+
function Template.PersistOf(compiled: Compiled, path: { string | number }): boolean
|
|
1672
|
+
local node = Template.Resolve(compiled, path)
|
|
1673
|
+
return node.Persist
|
|
1674
|
+
end
|
|
1675
|
+
|
|
1676
|
+
-- Deep-cloned default data. `which`:
|
|
1677
|
+
-- "Persistent": everything saved (Persist); the ProfileStore template
|
|
1678
|
+
-- "Session": non-persisted roots only
|
|
1679
|
+
-- "Client": everything except ServerOnly subtrees (the owner's mirror)
|
|
1680
|
+
function Template.BuildDefaults(compiled: Compiled, which: "Persistent" | "Session" | "Client"): { [string]: any }
|
|
1681
|
+
local function include(node: SchemaNode): boolean
|
|
1682
|
+
if which == "Persistent" then
|
|
1683
|
+
return node.Persist
|
|
1684
|
+
elseif which == "Session" then
|
|
1685
|
+
return not node.Persist
|
|
1686
|
+
else
|
|
1687
|
+
return node.Visibility ~= "ServerOnly"
|
|
1688
|
+
end
|
|
1689
|
+
end
|
|
1690
|
+
|
|
1691
|
+
-- Client defaults strip ServerOnly subtrees but keep mixed-visibility
|
|
1692
|
+
-- containers whose children are visible (the _Scribe reserved root).
|
|
1693
|
+
local function buildClient(node: SchemaNode): any
|
|
1694
|
+
if node.Kind ~= "table" or not node.Children then
|
|
1695
|
+
return if node.Visibility == "ServerOnly" then nil else Util.deepClone(node.Default)
|
|
1696
|
+
end
|
|
1697
|
+
local out = {}
|
|
1698
|
+
local anyVisible = false
|
|
1699
|
+
for key, child in node.Children do
|
|
1700
|
+
local value = buildClient(child)
|
|
1701
|
+
if value ~= nil then
|
|
1702
|
+
out[key] = value
|
|
1703
|
+
anyVisible = true
|
|
1704
|
+
end
|
|
1705
|
+
end
|
|
1706
|
+
if node.Visibility == "ServerOnly" and not anyVisible then
|
|
1707
|
+
return nil
|
|
1708
|
+
end
|
|
1709
|
+
return out
|
|
1710
|
+
end
|
|
1711
|
+
|
|
1712
|
+
local function build(node: SchemaNode): any
|
|
1713
|
+
if node.Kind ~= "table" or not node.Children then
|
|
1714
|
+
return Util.deepClone(node.Default)
|
|
1715
|
+
end
|
|
1716
|
+
local out = {}
|
|
1717
|
+
for key, child in node.Children do
|
|
1718
|
+
out[key] = build(child)
|
|
1719
|
+
end
|
|
1720
|
+
return out
|
|
1721
|
+
end
|
|
1722
|
+
|
|
1723
|
+
local out = {}
|
|
1724
|
+
for key, child in compiled.Root.Children :: { [string]: SchemaNode } do
|
|
1725
|
+
if which == "Client" then
|
|
1726
|
+
out[key] = buildClient(child)
|
|
1727
|
+
elseif include(child) then
|
|
1728
|
+
out[key] = build(child)
|
|
1729
|
+
end
|
|
1730
|
+
end
|
|
1731
|
+
return out
|
|
1732
|
+
end
|
|
1733
|
+
|
|
1734
|
+
-- Clone `value` at `node`, stripping ServerOnly subtrees (Init snapshots, offline
|
|
1735
|
+
-- perk reads). Mixed-visibility containers such as the _Scribe root keep their
|
|
1736
|
+
-- visible children; returns nil only when nothing is visible AND the node itself is
|
|
1737
|
+
-- ServerOnly.
|
|
1738
|
+
function Template.CloneVisible(node: SchemaNode, value: any): any
|
|
1739
|
+
-- A locally computed derived field is never sent: every realm that receives it can
|
|
1740
|
+
-- also see all of its inputs, so the client recomputes it from its own mirror.
|
|
1741
|
+
local derived = node.Derived
|
|
1742
|
+
if derived ~= nil and not derived.Transmit then
|
|
1743
|
+
return nil
|
|
1744
|
+
end
|
|
1745
|
+
if type(value) ~= "table" then
|
|
1746
|
+
if node.Visibility == "ServerOnly" then
|
|
1747
|
+
return nil
|
|
1748
|
+
end
|
|
1749
|
+
-- Packed datatypes are buffers, which are mutable and whose only reference here
|
|
1750
|
+
-- is live profile state. Callers mutate the returned tree in place, so hand
|
|
1751
|
+
-- back a copy.
|
|
1752
|
+
if type(value) == "buffer" then
|
|
1753
|
+
return Util.cloneBuffer(value)
|
|
1754
|
+
end
|
|
1755
|
+
return value
|
|
1756
|
+
end
|
|
1757
|
+
local out = {}
|
|
1758
|
+
local anyVisible = false
|
|
1759
|
+
for k, v in value do
|
|
1760
|
+
local childNode = if type(k) == "string" and node.Children then node.Children[k] else nil
|
|
1761
|
+
-- An ArrayOf/DictOf element schema describes EVERY entry, numeric keys
|
|
1762
|
+
-- included, so a ServerOnly field inside an element shape is stripped like a
|
|
1763
|
+
-- static one. Gated on IsElement so untyped dynamic containers keep the
|
|
1764
|
+
-- wholesale deepClone below, which otherwise starts aliasing live buffers.
|
|
1765
|
+
if childNode == nil and node.AnyChild ~= nil and node.AnyChild.IsElement then
|
|
1766
|
+
childNode = node.AnyChild
|
|
1767
|
+
end
|
|
1768
|
+
if childNode then
|
|
1769
|
+
local cloned = Template.CloneVisible(childNode, v)
|
|
1770
|
+
if cloned ~= nil then
|
|
1771
|
+
out[k] = cloned
|
|
1772
|
+
anyVisible = true
|
|
1773
|
+
end
|
|
1774
|
+
elseif node.Visibility ~= "ServerOnly" then
|
|
1775
|
+
-- Dynamic entries inherit this node's visibility.
|
|
1776
|
+
out[k] = Util.deepClone(v)
|
|
1777
|
+
anyVisible = true
|
|
1778
|
+
end
|
|
1779
|
+
end
|
|
1780
|
+
if node.Visibility == "ServerOnly" and not anyVisible then
|
|
1781
|
+
return nil
|
|
1782
|
+
end
|
|
1783
|
+
return out
|
|
1784
|
+
end
|
|
1785
|
+
|
|
1786
|
+
-- Backfills element fields added to an ArrayOf/DictOf shape after profiles exist.
|
|
1787
|
+
-- ProfileStore's Reconcile walks the static template only, and an element shape is
|
|
1788
|
+
-- reachable solely through AnyChild, so without this a field added in v2 stays missing
|
|
1789
|
+
-- on every stored entry forever. Fills a missing key, never touches an existing one;
|
|
1790
|
+
-- a Nullable field has a nil default and is skipped. Returns true when anything changed.
|
|
1791
|
+
function Template.ReconcileElements(compiled: Compiled, data: { [string]: any }): boolean
|
|
1792
|
+
-- `inElement` flips true under a container's AnyChild and stays true beneath it, so
|
|
1793
|
+
-- fills happen at every depth of an element subtree. Static template fields are
|
|
1794
|
+
-- never filled here; profile:Reconcile owns those.
|
|
1795
|
+
local function walk(node: SchemaNode, value: any, inElement: boolean): boolean
|
|
1796
|
+
if type(value) ~= "table" then
|
|
1797
|
+
return false
|
|
1798
|
+
end
|
|
1799
|
+
local changed = false
|
|
1800
|
+
if node.Container ~= nil then
|
|
1801
|
+
local element = node.AnyChild
|
|
1802
|
+
if element then
|
|
1803
|
+
for _, entry in value do
|
|
1804
|
+
if walk(element, entry, true) then
|
|
1805
|
+
changed = true
|
|
1806
|
+
end
|
|
1807
|
+
end
|
|
1808
|
+
end
|
|
1809
|
+
return changed
|
|
1810
|
+
end
|
|
1811
|
+
if node.Children then
|
|
1812
|
+
for name, child in node.Children do
|
|
1813
|
+
if inElement and value[name] == nil and child.Default ~= nil then
|
|
1814
|
+
value[name] = Util.deepClone(child.Default)
|
|
1815
|
+
changed = true
|
|
1816
|
+
end
|
|
1817
|
+
if walk(child, value[name], inElement) then
|
|
1818
|
+
changed = true
|
|
1819
|
+
end
|
|
1820
|
+
end
|
|
1821
|
+
end
|
|
1822
|
+
return changed
|
|
1823
|
+
end
|
|
1824
|
+
|
|
1825
|
+
local changed = false
|
|
1826
|
+
for key, child in compiled.Root.Children :: { [string]: SchemaNode } do
|
|
1827
|
+
if walk(child, data[key], false) then
|
|
1828
|
+
changed = true
|
|
1829
|
+
end
|
|
1830
|
+
end
|
|
1831
|
+
return changed
|
|
1832
|
+
end
|
|
1833
|
+
|
|
1834
|
+
-- Top-level keys present in `data` but absent from the schema (dev-mode warning;
|
|
1835
|
+
-- `nil :: T?` template fields are invisible at runtime).
|
|
1836
|
+
function Template.UnknownRootKeys(compiled: Compiled, data: { [string]: any }): { string }
|
|
1837
|
+
local unknown = {}
|
|
1838
|
+
local children = compiled.Root.Children :: { [string]: SchemaNode }
|
|
1839
|
+
for key in data do
|
|
1840
|
+
if type(key) ~= "string" or not children[key] then
|
|
1841
|
+
table.insert(unknown, tostring(key))
|
|
1842
|
+
end
|
|
1843
|
+
end
|
|
1844
|
+
table.sort(unknown)
|
|
1845
|
+
return unknown
|
|
1846
|
+
end
|
|
1847
|
+
|
|
1848
|
+
return Template
|