@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.
Files changed (56) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE +21 -0
  3. package/README.md +100 -0
  4. package/Scribe-source-map.json +1 -0
  5. package/licenses/ProfileStore-Apache-2.0.txt +201 -0
  6. package/package.json +32 -0
  7. package/src/Client/DebugHook.luau +457 -0
  8. package/src/Client/init.luau +1607 -0
  9. package/src/Internal/Addons.luau +68 -0
  10. package/src/Internal/Big.luau +582 -0
  11. package/src/Internal/Budget.luau +377 -0
  12. package/src/Internal/Clock.luau +75 -0
  13. package/src/Internal/Config.luau +17 -0
  14. package/src/Internal/Conform.luau +400 -0
  15. package/src/Internal/Datatypes.luau +653 -0
  16. package/src/Internal/Defaults.luau +12 -0
  17. package/src/Internal/Derived.luau +428 -0
  18. package/src/Internal/Exchange.luau +556 -0
  19. package/src/Internal/ExchangeLeg.luau +1368 -0
  20. package/src/Internal/ExchangeVerdict.luau +179 -0
  21. package/src/Internal/Failure.luau +148 -0
  22. package/src/Internal/Health.luau +320 -0
  23. package/src/Internal/LeaderboardDiagnostics.luau +36 -0
  24. package/src/Internal/Log.luau +378 -0
  25. package/src/Internal/Marker.luau +76 -0
  26. package/src/Internal/Metrics.luau +152 -0
  27. package/src/Internal/Node.luau +3954 -0
  28. package/src/Internal/Profile.luau +69 -0
  29. package/src/Internal/Rng.luau +83 -0
  30. package/src/Internal/Sched.luau +56 -0
  31. package/src/Internal/Signal.luau +199 -0
  32. package/src/Internal/Store/ProfileStore.luau +3019 -0
  33. package/src/Internal/Store/init.luau +18 -0
  34. package/src/Internal/StudioCodec.luau +155 -0
  35. package/src/Internal/Template.luau +1848 -0
  36. package/src/Internal/Transport.luau +169 -0
  37. package/src/Internal/Util.luau +517 -0
  38. package/src/Internal/Version.luau +4 -0
  39. package/src/Internal/Wire.luau +1283 -0
  40. package/src/Server/Analytics.luau +223 -0
  41. package/src/Server/Commands.luau +728 -0
  42. package/src/Server/DebugHook.luau +1490 -0
  43. package/src/Server/Exchanges.luau +737 -0
  44. package/src/Server/Leaderboards.luau +2143 -0
  45. package/src/Server/Monetization.luau +3212 -0
  46. package/src/Server/Persistence.luau +3775 -0
  47. package/src/Server/Replication.luau +1253 -0
  48. package/src/Server/ServerStore.luau +81 -0
  49. package/src/Server/Timed.luau +579 -0
  50. package/src/Server/init.luau +672 -0
  51. package/src/Types.luau +480 -0
  52. package/src/init.luau +2231 -0
  53. package/types/api.d.ts +252 -0
  54. package/types/common.d.ts +355 -0
  55. package/types/index.d.ts +226 -0
  56. package/types/schema.d.ts +276 -0
@@ -0,0 +1,653 @@
1
+ --!strict
2
+ -- Packed-buffer codecs for Roblox datatypes. Declared fields (Scribe.Vector3,
3
+ -- Scribe.CFrame, ...) store this packed form; persistence, replication, cloning and the
4
+ -- wipe guard only ever see plain buffers, and the node accessor converts at the boundary
5
+ -- (Set packs, Get unpacks). Roblox stores these types as f32 internally, so f32 packing
6
+ -- is lossless; DataStores keep buffers as base64, about 4/3 of the raw size.
7
+
8
+ local Datatypes = {}
9
+
10
+ type Codec = {
11
+ -- The field's declared Scribe Precision, threaded through from the schema. nil
12
+ -- is the default form and what every codec that ignores the argument produces.
13
+ Pack: (value: any, precision: (string | number)?) -> buffer,
14
+ Unpack: (b: buffer) -> any,
15
+ -- The Precision values this codec accepts, as a set. nil means no Precision
16
+ -- option at all, which is every codec but CFrame. The template compiler reads
17
+ -- this to refuse a bad declaration at startup rather than at the first write.
18
+ Precisions: { [string]: true }?,
19
+ }
20
+
21
+ local codecs: { [string]: Codec } = {}
22
+
23
+ local function checkLen(b: buffer, expected: number, name: string)
24
+ if buffer.len(b) < expected then
25
+ error(`Scribe: malformed packed {name}`)
26
+ end
27
+ end
28
+
29
+ -- Checked f32 writer: rejects NaN/inf components so a corrupt datatype can never
30
+ -- be silently persisted. The `NONFINITE` prefix lets validateWrite turn this into
31
+ -- a path-tagged validation error.
32
+ local NONFINITE = "Scribe:nonfinite:"
33
+
34
+ local function wf32(b: buffer, offset: number, value: number)
35
+ if value ~= value or value == math.huge or value == -math.huge then
36
+ error(NONFINITE, 0)
37
+ end
38
+ buffer.writef32(b, offset, value)
39
+ end
40
+
41
+ Datatypes.NONFINITE = NONFINITE
42
+
43
+ -- Vectors -----------------------------------------------------------------------
44
+
45
+ codecs.Vector3 = {
46
+ Pack = function(v: Vector3): buffer
47
+ local b = buffer.create(12)
48
+ wf32(b, 0, v.X)
49
+ wf32(b, 4, v.Y)
50
+ wf32(b, 8, v.Z)
51
+ return b
52
+ end,
53
+ Unpack = function(b: buffer): Vector3
54
+ checkLen(b, 12, "Vector3")
55
+ return Vector3.new(buffer.readf32(b, 0), buffer.readf32(b, 4), buffer.readf32(b, 8))
56
+ end,
57
+ }
58
+
59
+ codecs.Vector2 = {
60
+ Pack = function(v: Vector2): buffer
61
+ local b = buffer.create(8)
62
+ wf32(b, 0, v.X)
63
+ wf32(b, 4, v.Y)
64
+ return b
65
+ end,
66
+ Unpack = function(b: buffer): Vector2
67
+ checkLen(b, 8, "Vector2")
68
+ return Vector2.new(buffer.readf32(b, 0), buffer.readf32(b, 4))
69
+ end,
70
+ }
71
+
72
+ codecs.Vector3int16 = {
73
+ Pack = function(v: Vector3int16): buffer
74
+ local b = buffer.create(6)
75
+ buffer.writei16(b, 0, v.X)
76
+ buffer.writei16(b, 2, v.Y)
77
+ buffer.writei16(b, 4, v.Z)
78
+ return b
79
+ end,
80
+ Unpack = function(b: buffer): Vector3int16
81
+ checkLen(b, 6, "Vector3int16")
82
+ return Vector3int16.new(buffer.readi16(b, 0), buffer.readi16(b, 2), buffer.readi16(b, 4))
83
+ end,
84
+ }
85
+
86
+ codecs.Vector2int16 = {
87
+ Pack = function(v: Vector2int16): buffer
88
+ local b = buffer.create(4)
89
+ buffer.writei16(b, 0, v.X)
90
+ buffer.writei16(b, 2, v.Y)
91
+ return b
92
+ end,
93
+ Unpack = function(b: buffer): Vector2int16
94
+ checkLen(b, 4, "Vector2int16")
95
+ return Vector2int16.new(buffer.readi16(b, 0), buffer.readi16(b, 2))
96
+ end,
97
+ }
98
+
99
+ -- CFrame ------------------------------------------------------------------------
100
+ -- Layout: [u8 rotation tag][3xf32 position][rotation payload chosen by the tag].
101
+ --
102
+ -- tag < 36 13 bytes. One of the 24 axis-aligned orientations, encoded as
103
+ -- rightAxisCode * 6 + upAxisCode. The common case for placed parts.
104
+ -- tag == 254 49 bytes. Opt-in, Precision = "exact": the nine rotation
105
+ -- components verbatim. See CFRAME_FULL below.
106
+ -- tag == 255 29 bytes. Quaternion. The default for any other rotation.
107
+ --
108
+ -- 36..253 are unassigned and decode as a malformed orientation.
109
+
110
+ local AXIS_EPSILON = 1e-4
111
+
112
+ -- Full-precision CFrame, opt-in via Precision = "exact": the nine rotation components as
113
+ -- f32, in GetComponents order. The 29-byte default re-derives those nine from four, so a
114
+ -- stored orientation comes back slightly turned; the loss is the re-derivation, not the
115
+ -- float width, so widening the quaternion cannot close it. Roblox stores CFrame
116
+ -- components as f32, which makes all twelve as f32 a bit-for-bit round trip.
117
+ --
118
+ -- 254 sits just below the quaternion's 255, leaving 36..253 contiguous for a future
119
+ -- compact orientation code. No buffer written before it existed carries tag 254 or is
120
+ -- 49 bytes long, so old data stays distinguishable.
121
+ local CFRAME_FULL = 254
122
+
123
+ -- Returns 0-5 (axis index * 2 + negative bit) when the vector is a unit axis.
124
+ local function unitAxisCode(x: number, y: number, z: number): number?
125
+ local ax, ay, az = math.abs(x), math.abs(y), math.abs(z)
126
+ if ax > 1 - AXIS_EPSILON and ay < AXIS_EPSILON and az < AXIS_EPSILON then
127
+ return 0 + (if x < 0 then 1 else 0)
128
+ elseif ay > 1 - AXIS_EPSILON and ax < AXIS_EPSILON and az < AXIS_EPSILON then
129
+ return 2 + (if y < 0 then 1 else 0)
130
+ elseif az > 1 - AXIS_EPSILON and ax < AXIS_EPSILON and ay < AXIS_EPSILON then
131
+ return 4 + (if z < 0 then 1 else 0)
132
+ end
133
+ return nil
134
+ end
135
+
136
+ local function axisFromCode(code: number): Vector3
137
+ local sign = if code % 2 == 1 then -1 else 1
138
+ local axis = math.floor(code / 2)
139
+ if axis == 0 then
140
+ return Vector3.new(sign, 0, 0)
141
+ elseif axis == 1 then
142
+ return Vector3.new(0, sign, 0)
143
+ end
144
+ return Vector3.new(0, 0, sign)
145
+ end
146
+
147
+ codecs.CFrame = {
148
+ Precisions = { exact = true },
149
+ Pack = function(cf: CFrame, precision: (string | number)?): buffer
150
+ local x, y, z, r00, r01, r02, r10, r11, r12, r20, r21, r22 = cf:GetComponents()
151
+
152
+ -- Declared exact always writes 49 bytes, even where the 13-byte path would fit:
153
+ -- that path snaps. unitAxisCode accepts an axis within AXIS_EPSILON of a unit
154
+ -- axis and rebuilds the exact axis, so a rotation a fraction of a degree off
155
+ -- square silently becomes square, a larger loss than the quaternion's.
156
+ if precision == "exact" then
157
+ local b = buffer.create(49)
158
+ buffer.writeu8(b, 0, CFRAME_FULL)
159
+ wf32(b, 1, x)
160
+ wf32(b, 5, y)
161
+ wf32(b, 9, z)
162
+ wf32(b, 13, r00)
163
+ wf32(b, 17, r01)
164
+ wf32(b, 21, r02)
165
+ wf32(b, 25, r10)
166
+ wf32(b, 29, r11)
167
+ wf32(b, 33, r12)
168
+ wf32(b, 37, r20)
169
+ wf32(b, 41, r21)
170
+ wf32(b, 45, r22)
171
+ return b
172
+ end
173
+
174
+ local rightCode = unitAxisCode(r00, r10, r20)
175
+ local upCode = unitAxisCode(r01, r11, r21)
176
+ if rightCode and upCode and math.floor(rightCode / 2) ~= math.floor(upCode / 2) then
177
+ local b = buffer.create(13)
178
+ buffer.writeu8(b, 0, rightCode * 6 + upCode)
179
+ wf32(b, 1, x)
180
+ wf32(b, 5, y)
181
+ wf32(b, 9, z)
182
+ return b
183
+ end
184
+
185
+ -- Standard rotation-matrix -> quaternion conversion.
186
+ local qx, qy, qz, qw
187
+ local trace = r00 + r11 + r22
188
+ if trace > 0 then
189
+ local s = math.sqrt(trace + 1) * 2
190
+ qw = s / 4
191
+ qx = (r21 - r12) / s
192
+ qy = (r02 - r20) / s
193
+ qz = (r10 - r01) / s
194
+ elseif r00 > r11 and r00 > r22 then
195
+ local s = math.sqrt(1 + r00 - r11 - r22) * 2
196
+ qw = (r21 - r12) / s
197
+ qx = s / 4
198
+ qy = (r01 + r10) / s
199
+ qz = (r02 + r20) / s
200
+ elseif r11 > r22 then
201
+ local s = math.sqrt(1 + r11 - r00 - r22) * 2
202
+ qw = (r02 - r20) / s
203
+ qx = (r01 + r10) / s
204
+ qy = s / 4
205
+ qz = (r12 + r21) / s
206
+ else
207
+ local s = math.sqrt(1 + r22 - r00 - r11) * 2
208
+ qw = (r10 - r01) / s
209
+ qx = (r02 + r20) / s
210
+ qy = (r12 + r21) / s
211
+ qz = s / 4
212
+ end
213
+
214
+ local b = buffer.create(29)
215
+ buffer.writeu8(b, 0, 255)
216
+ wf32(b, 1, x)
217
+ wf32(b, 5, y)
218
+ wf32(b, 9, z)
219
+ wf32(b, 13, qx)
220
+ wf32(b, 17, qy)
221
+ wf32(b, 21, qz)
222
+ wf32(b, 25, qw)
223
+ return b
224
+ end,
225
+ Unpack = function(b: buffer): CFrame
226
+ checkLen(b, 13, "CFrame")
227
+ local tag = buffer.readu8(b, 0)
228
+ local position = Vector3.new(buffer.readf32(b, 1), buffer.readf32(b, 5), buffer.readf32(b, 9))
229
+ if tag == CFRAME_FULL then
230
+ -- Re-check before reading the 36-byte rotation payload: a truncated or hostile
231
+ -- buffer must fail as a clean malformed error, not an out-of-bounds read.
232
+ checkLen(b, 49, "CFrame")
233
+ -- The twelve-argument CFrame.new is the exact inverse of GetComponents and
234
+ -- does not re-orthonormalize, so the round trip is the identity.
235
+ return CFrame.new(
236
+ position.X,
237
+ position.Y,
238
+ position.Z,
239
+ buffer.readf32(b, 13),
240
+ buffer.readf32(b, 17),
241
+ buffer.readf32(b, 21),
242
+ buffer.readf32(b, 25),
243
+ buffer.readf32(b, 29),
244
+ buffer.readf32(b, 33),
245
+ buffer.readf32(b, 37),
246
+ buffer.readf32(b, 41),
247
+ buffer.readf32(b, 45)
248
+ )
249
+ end
250
+ if tag == 255 then
251
+ checkLen(b, 29, "CFrame")
252
+ return CFrame.new(
253
+ position.X,
254
+ position.Y,
255
+ position.Z,
256
+ buffer.readf32(b, 13),
257
+ buffer.readf32(b, 17),
258
+ buffer.readf32(b, 21),
259
+ buffer.readf32(b, 25)
260
+ )
261
+ end
262
+ local rightCode = math.floor(tag / 6)
263
+ local upCode = tag % 6
264
+ if rightCode > 5 or math.floor(rightCode / 2) == math.floor(upCode / 2) then
265
+ error("Scribe: malformed packed CFrame orientation")
266
+ end
267
+ return CFrame.fromMatrix(position, axisFromCode(rightCode), axisFromCode(upCode))
268
+ end,
269
+ }
270
+
271
+ -- Colors ------------------------------------------------------------------------
272
+ -- Layout: [u8 mode] then 3xu8 (mode 0, exact fromRGB colors) or 3xf32 (mode 1).
273
+
274
+ local function packColor3Into(b: buffer, offset: number, color: Color3): number
275
+ local r255, g255, b255 = color.R * 255, color.G * 255, color.B * 255
276
+ local function exact(n: number): boolean
277
+ -- Only components that round to a whole 0-255 byte take the compact u8
278
+ -- mode; HDR/negative values fall through to f32 so writeu8's mod-256
279
+ -- wrap cannot corrupt them.
280
+ return math.abs(n - math.round(n)) < 1e-4 and n >= -1e-4 and n <= 255 + 1e-4
281
+ end
282
+ if exact(r255) and exact(g255) and exact(b255) then
283
+ buffer.writeu8(b, offset, 0)
284
+ buffer.writeu8(b, offset + 1, math.round(r255))
285
+ buffer.writeu8(b, offset + 2, math.round(g255))
286
+ buffer.writeu8(b, offset + 3, math.round(b255))
287
+ return offset + 4
288
+ end
289
+ buffer.writeu8(b, offset, 1)
290
+ wf32(b, offset + 1, color.R)
291
+ wf32(b, offset + 5, color.G)
292
+ wf32(b, offset + 9, color.B)
293
+ return offset + 13
294
+ end
295
+
296
+ local function unpackColor3From(b: buffer, offset: number): (Color3, number)
297
+ local mode = buffer.readu8(b, offset)
298
+ if mode == 0 then
299
+ return Color3.fromRGB(buffer.readu8(b, offset + 1), buffer.readu8(b, offset + 2), buffer.readu8(b, offset + 3)),
300
+ offset + 4
301
+ end
302
+ return Color3.new(buffer.readf32(b, offset + 1), buffer.readf32(b, offset + 5), buffer.readf32(b, offset + 9)),
303
+ offset + 13
304
+ end
305
+
306
+ codecs.Color3 = {
307
+ Pack = function(color: Color3): buffer
308
+ local b = buffer.create(13)
309
+ local used = packColor3Into(b, 0, color)
310
+ if used == buffer.len(b) then
311
+ return b
312
+ end
313
+ local out = buffer.create(used)
314
+ buffer.copy(out, 0, b, 0, used)
315
+ return out
316
+ end,
317
+ Unpack = function(b: buffer): Color3
318
+ checkLen(b, 4, "Color3")
319
+ -- checkLen(4) covers only the mode byte plus the mode-0 RGB path, and
320
+ -- unpackColor3From takes the 13-byte branch for any non-zero mode, so re-check
321
+ -- on `~= 0` rather than `== 1`: mode 2..255 must not read out of bounds.
322
+ if buffer.readu8(b, 0) ~= 0 then
323
+ checkLen(b, 13, "Color3")
324
+ end
325
+ local color = unpackColor3From(b, 0)
326
+ return color
327
+ end,
328
+ }
329
+
330
+ codecs.BrickColor = {
331
+ Pack = function(color: BrickColor): buffer
332
+ local b = buffer.create(2)
333
+ buffer.writeu16(b, 0, color.Number)
334
+ return b
335
+ end,
336
+ Unpack = function(b: buffer): BrickColor
337
+ checkLen(b, 2, "BrickColor")
338
+ return BrickColor.new(buffer.readu16(b, 0))
339
+ end,
340
+ }
341
+
342
+ -- UI ---------------------------------------------------------------------------
343
+
344
+ codecs.UDim = {
345
+ Pack = function(value: UDim): buffer
346
+ local b = buffer.create(8)
347
+ wf32(b, 0, value.Scale)
348
+ buffer.writei32(b, 4, value.Offset)
349
+ return b
350
+ end,
351
+ Unpack = function(b: buffer): UDim
352
+ checkLen(b, 8, "UDim")
353
+ return UDim.new(buffer.readf32(b, 0), buffer.readi32(b, 4))
354
+ end,
355
+ }
356
+
357
+ codecs.UDim2 = {
358
+ Pack = function(value: UDim2): buffer
359
+ local b = buffer.create(16)
360
+ wf32(b, 0, value.X.Scale)
361
+ buffer.writei32(b, 4, value.X.Offset)
362
+ wf32(b, 8, value.Y.Scale)
363
+ buffer.writei32(b, 12, value.Y.Offset)
364
+ return b
365
+ end,
366
+ Unpack = function(b: buffer): UDim2
367
+ checkLen(b, 16, "UDim2")
368
+ return UDim2.new(buffer.readf32(b, 0), buffer.readi32(b, 4), buffer.readf32(b, 8), buffer.readi32(b, 12))
369
+ end,
370
+ }
371
+
372
+ codecs.Rect = {
373
+ Pack = function(value: Rect): buffer
374
+ local b = buffer.create(16)
375
+ wf32(b, 0, value.Min.X)
376
+ wf32(b, 4, value.Min.Y)
377
+ wf32(b, 8, value.Max.X)
378
+ wf32(b, 12, value.Max.Y)
379
+ return b
380
+ end,
381
+ Unpack = function(b: buffer): Rect
382
+ checkLen(b, 16, "Rect")
383
+ return Rect.new(
384
+ Vector2.new(buffer.readf32(b, 0), buffer.readf32(b, 4)),
385
+ Vector2.new(buffer.readf32(b, 8), buffer.readf32(b, 12))
386
+ )
387
+ end,
388
+ }
389
+
390
+ -- Ranges and sequences -------------------------------------------------------------
391
+
392
+ codecs.NumberRange = {
393
+ Pack = function(value: NumberRange): buffer
394
+ local b = buffer.create(8)
395
+ wf32(b, 0, value.Min)
396
+ wf32(b, 4, value.Max)
397
+ return b
398
+ end,
399
+ Unpack = function(b: buffer): NumberRange
400
+ checkLen(b, 8, "NumberRange")
401
+ return NumberRange.new(buffer.readf32(b, 0), buffer.readf32(b, 4))
402
+ end,
403
+ }
404
+
405
+ codecs.NumberSequence = {
406
+ Pack = function(value: NumberSequence): buffer
407
+ local keypoints = value.Keypoints
408
+ if #keypoints > 255 then
409
+ error("Scribe: NumberSequence has too many keypoints")
410
+ end
411
+ local b = buffer.create(1 + #keypoints * 12)
412
+ buffer.writeu8(b, 0, #keypoints)
413
+ local offset = 1
414
+ for _, keypoint in keypoints do
415
+ wf32(b, offset, keypoint.Time)
416
+ wf32(b, offset + 4, keypoint.Value)
417
+ wf32(b, offset + 8, keypoint.Envelope)
418
+ offset += 12
419
+ end
420
+ return b
421
+ end,
422
+ Unpack = function(b: buffer): NumberSequence
423
+ checkLen(b, 1, "NumberSequence")
424
+ local count = buffer.readu8(b, 0)
425
+ checkLen(b, 1 + count * 12, "NumberSequence")
426
+ local keypoints = table.create(count) :: { NumberSequenceKeypoint }
427
+ local offset = 1
428
+ for _ = 1, count do
429
+ table.insert(
430
+ keypoints,
431
+ NumberSequenceKeypoint.new(
432
+ buffer.readf32(b, offset),
433
+ buffer.readf32(b, offset + 4),
434
+ buffer.readf32(b, offset + 8)
435
+ )
436
+ )
437
+ offset += 12
438
+ end
439
+ return NumberSequence.new(keypoints)
440
+ end,
441
+ }
442
+
443
+ codecs.ColorSequence = {
444
+ Pack = function(value: ColorSequence): buffer
445
+ local keypoints = value.Keypoints
446
+ if #keypoints > 255 then
447
+ error("Scribe: ColorSequence has too many keypoints")
448
+ end
449
+ local b = buffer.create(1 + #keypoints * 16)
450
+ buffer.writeu8(b, 0, #keypoints)
451
+ local offset = 1
452
+ for _, keypoint in keypoints do
453
+ wf32(b, offset, keypoint.Time)
454
+ wf32(b, offset + 4, keypoint.Value.R)
455
+ wf32(b, offset + 8, keypoint.Value.G)
456
+ wf32(b, offset + 12, keypoint.Value.B)
457
+ offset += 16
458
+ end
459
+ return b
460
+ end,
461
+ Unpack = function(b: buffer): ColorSequence
462
+ checkLen(b, 1, "ColorSequence")
463
+ local count = buffer.readu8(b, 0)
464
+ checkLen(b, 1 + count * 16, "ColorSequence")
465
+ local keypoints = table.create(count) :: { ColorSequenceKeypoint }
466
+ local offset = 1
467
+ for _ = 1, count do
468
+ table.insert(
469
+ keypoints,
470
+ ColorSequenceKeypoint.new(
471
+ buffer.readf32(b, offset),
472
+ Color3.new(
473
+ buffer.readf32(b, offset + 4),
474
+ buffer.readf32(b, offset + 8),
475
+ buffer.readf32(b, offset + 12)
476
+ )
477
+ )
478
+ )
479
+ offset += 16
480
+ end
481
+ return ColorSequence.new(keypoints)
482
+ end,
483
+ }
484
+
485
+ -- Time, enums, fonts, physics ---------------------------------------------------------
486
+
487
+ codecs.DateTime = {
488
+ Pack = function(value: DateTime): buffer
489
+ local b = buffer.create(8)
490
+ buffer.writef64(b, 0, value.UnixTimestampMillis)
491
+ return b
492
+ end,
493
+ Unpack = function(b: buffer): DateTime
494
+ checkLen(b, 8, "DateTime")
495
+ return DateTime.fromUnixTimestampMillis(buffer.readf64(b, 0))
496
+ end,
497
+ }
498
+
499
+ local function writeShortString(b: buffer, offset: number, s: string): number
500
+ buffer.writeu8(b, offset, #s)
501
+ buffer.writestring(b, offset + 1, s)
502
+ return offset + 1 + #s
503
+ end
504
+
505
+ local function readShortString(b: buffer, offset: number): (string, number)
506
+ local length = buffer.readu8(b, offset)
507
+ -- Bounds-check the declared length before reading, so a truncated buffer fails
508
+ -- as a clean malformed error rather than a raw out-of-bounds read.
509
+ checkLen(b, offset + 1 + length, "string")
510
+ return buffer.readstring(b, offset + 1, length), offset + 1 + length
511
+ end
512
+
513
+ local function enumItemFromValue(enumTypeName: string, value: number): EnumItem
514
+ -- Indexing Enum with an unknown name throws a raw Roblox error, which would
515
+ -- escape the "Scribe:"-prefixed malformed contract, so resolve it under pcall.
516
+ local gotType, enumType = pcall(function()
517
+ return (Enum :: any)[enumTypeName]
518
+ end)
519
+ if not gotType or enumType == nil then
520
+ error(`Scribe: malformed packed EnumItem (unknown enum type "{enumTypeName}")`)
521
+ end
522
+ local ok, item = pcall(function()
523
+ return enumType:FromValue(value)
524
+ end)
525
+ if ok and item then
526
+ return item
527
+ end
528
+ for _, candidate in enumType:GetEnumItems() do
529
+ if candidate.Value == value then
530
+ return candidate
531
+ end
532
+ end
533
+ error(`Scribe: no {enumTypeName} enum item with value {value}`)
534
+ end
535
+
536
+ codecs.EnumItem = {
537
+ Pack = function(value: EnumItem): buffer
538
+ local typeName = tostring(value.EnumType)
539
+ if #typeName > 255 then
540
+ error("Scribe: enum type name too long")
541
+ end
542
+ local b = buffer.create(1 + #typeName + 4)
543
+ local offset = writeShortString(b, 0, typeName)
544
+ buffer.writeu32(b, offset, value.Value)
545
+ return b
546
+ end,
547
+ Unpack = function(b: buffer): EnumItem
548
+ checkLen(b, 5, "EnumItem")
549
+ local typeName, offset = readShortString(b, 0)
550
+ -- Re-check for the u32 value that follows the variable-length type name.
551
+ checkLen(b, offset + 4, "EnumItem")
552
+ return enumItemFromValue(typeName, buffer.readu32(b, offset))
553
+ end,
554
+ }
555
+
556
+ codecs.Font = {
557
+ Pack = function(value: Font): buffer
558
+ local family = value.Family
559
+ if #family > 255 then
560
+ error("Scribe: font family too long")
561
+ end
562
+ local b = buffer.create(1 + #family + 3)
563
+ local offset = writeShortString(b, 0, family)
564
+ buffer.writeu16(b, offset, value.Weight.Value)
565
+ buffer.writeu8(b, offset + 2, value.Style.Value)
566
+ return b
567
+ end,
568
+ Unpack = function(b: buffer): Font
569
+ checkLen(b, 4, "Font")
570
+ local family, offset = readShortString(b, 0)
571
+ -- Re-check for the u16 weight + u8 style that follow the variable-length family.
572
+ checkLen(b, offset + 3, "Font")
573
+ local weight = enumItemFromValue("FontWeight", buffer.readu16(b, offset))
574
+ local style = enumItemFromValue("FontStyle", buffer.readu8(b, offset + 2))
575
+ return Font.new(family, weight :: any, style :: any)
576
+ end,
577
+ }
578
+
579
+ codecs.PhysicalProperties = {
580
+ Pack = function(value: PhysicalProperties): buffer
581
+ local b = buffer.create(20)
582
+ wf32(b, 0, value.Density)
583
+ wf32(b, 4, value.Friction)
584
+ wf32(b, 8, value.Elasticity)
585
+ wf32(b, 12, value.FrictionWeight)
586
+ wf32(b, 16, value.ElasticityWeight)
587
+ return b
588
+ end,
589
+ Unpack = function(b: buffer): PhysicalProperties
590
+ checkLen(b, 20, "PhysicalProperties")
591
+ return PhysicalProperties.new(
592
+ buffer.readf32(b, 0),
593
+ buffer.readf32(b, 4),
594
+ buffer.readf32(b, 8),
595
+ buffer.readf32(b, 12),
596
+ buffer.readf32(b, 16)
597
+ )
598
+ end,
599
+ }
600
+
601
+ --------------------------------------------------------------------------------
602
+
603
+ function Datatypes.IsSupported(name: string): boolean
604
+ return codecs[name] ~= nil
605
+ end
606
+
607
+ --- The Precision values `name` accepts, sorted, or nil when it accepts none.
608
+ --- The template compiler reads this to refuse a bad declaration at startup.
609
+ function Datatypes.PrecisionValues(name: string): { string }?
610
+ local codec = codecs[name]
611
+ local accepted = codec and codec.Precisions
612
+ if not accepted then
613
+ return nil
614
+ end
615
+ local out: { string } = {}
616
+ for value in accepted do
617
+ table.insert(out, value)
618
+ end
619
+ table.sort(out)
620
+ return out
621
+ end
622
+
623
+ --- Packs `value` as `name`. `precision` is optional; omitted, every datatype packs its
624
+ --- default form. Validated here rather than inside each codec so a codec with no
625
+ --- Precision option gets the refusal for free, and so a typo is reported instead of
626
+ --- quietly yielding the default form.
627
+ function Datatypes.Pack(name: string, value: any, precision: (string | number)?): buffer
628
+ local codec = codecs[name]
629
+ if not codec then
630
+ error(`Scribe: unsupported datatype "{name}"`, 2)
631
+ end
632
+ if precision ~= nil then
633
+ local accepted = codec.Precisions
634
+ if type(precision) ~= "string" or not accepted or not accepted[precision] then
635
+ local values = Datatypes.PrecisionValues(name)
636
+ local detail = if values
637
+ then `it accepts "{table.concat(values, '", "')}"`
638
+ else `datatype "{name}" has no Precision option`
639
+ error(`Scribe: invalid Precision {tostring(precision)} for {name} ({detail})`, 2)
640
+ end
641
+ end
642
+ return codec.Pack(value, precision)
643
+ end
644
+
645
+ function Datatypes.Unpack(name: string, b: buffer): any
646
+ local codec = codecs[name]
647
+ if not codec then
648
+ error(`Scribe: unsupported datatype "{name}"`, 2)
649
+ end
650
+ return codec.Unpack(b)
651
+ end
652
+
653
+ return Datatypes
@@ -0,0 +1,12 @@
1
+ --!strict
2
+ -- Timeout defaults. The client waits only on the handshake; a server load can sit
3
+ -- behind a session steal, which is the 30 against the 60.
4
+
5
+ return table.freeze({
6
+ ClientWaitForData = 30,
7
+ ServerWaitForData = 60,
8
+ Request = 10,
9
+ OwnsAsync = 10,
10
+ ProductInfo = 10,
11
+ AwaitBudget = 120,
12
+ })