@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,223 @@
|
|
|
1
|
+
--!strict
|
|
2
|
+
-- Economy source/sink analytics. Currency mutations tagged via Increment/Decrement (and
|
|
3
|
+
-- Data.Purchase) auto-emit AnalyticsService:LogEconomyEvent, with the currency taken from
|
|
4
|
+
-- the mutated field's name. Custom fields, an ambient Resolve and a label override are
|
|
5
|
+
-- declared once in options.Economy. Failures log at Debug and never block gameplay.
|
|
6
|
+
|
|
7
|
+
local AnalyticsService = game:GetService("AnalyticsService")
|
|
8
|
+
|
|
9
|
+
local Internal = script.Parent.Parent.Internal
|
|
10
|
+
local Log = require(Internal.Log)
|
|
11
|
+
local Metrics = require(Internal.Metrics)
|
|
12
|
+
local Types = require(script.Parent.Parent.Types)
|
|
13
|
+
|
|
14
|
+
local Analytics = {}
|
|
15
|
+
|
|
16
|
+
-- Roblox exposes exactly three economy custom-field slots.
|
|
17
|
+
local MAX_FIELDS = 3
|
|
18
|
+
|
|
19
|
+
-- Resolve a transaction type from the tag: an Enum.AnalyticsEconomyTransactionType
|
|
20
|
+
-- (a real EnumItem, or the headless test fake, which is a table carrying .Name),
|
|
21
|
+
-- a plain string, or nil -> "Gameplay".
|
|
22
|
+
local function txnName(value: any): string
|
|
23
|
+
if value == nil then
|
|
24
|
+
return "Gameplay"
|
|
25
|
+
end
|
|
26
|
+
if typeof(value) == "EnumItem" then
|
|
27
|
+
return (value :: EnumItem).Name
|
|
28
|
+
end
|
|
29
|
+
if type(value) == "table" and type((value :: any).Name) == "string" then
|
|
30
|
+
return (value :: any).Name
|
|
31
|
+
end
|
|
32
|
+
return tostring(value)
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
type FieldSpec = { Name: string, Prefix: boolean }
|
|
36
|
+
type Currency = {
|
|
37
|
+
Label: string?,
|
|
38
|
+
Resolve: ((player: Player) -> { [string]: any })?,
|
|
39
|
+
Fields: { FieldSpec },
|
|
40
|
+
Declared: { [string]: boolean },
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
function Analytics.new(ctx: any)
|
|
44
|
+
local self = {} :: any
|
|
45
|
+
local options = ctx.Options or {}
|
|
46
|
+
local economy = options.Economy or {}
|
|
47
|
+
local devMode: boolean = ctx.DevMode == true
|
|
48
|
+
|
|
49
|
+
-- Cast the (any-typed) override to the seam's function type so the default
|
|
50
|
+
-- and the call site below are both concretely callable, not `~(false?)`.
|
|
51
|
+
local logEconomy = (economy.LogEconomyEvent :: Types.EconomyLogFn?)
|
|
52
|
+
or function(
|
|
53
|
+
player: Player,
|
|
54
|
+
flowType: Enum.AnalyticsEconomyFlowType,
|
|
55
|
+
currency: string,
|
|
56
|
+
amount: number,
|
|
57
|
+
balance: number,
|
|
58
|
+
transactionType: string,
|
|
59
|
+
itemSku: string?,
|
|
60
|
+
customFields: { [string]: any }?
|
|
61
|
+
)
|
|
62
|
+
AnalyticsService:LogEconomyEvent(
|
|
63
|
+
player,
|
|
64
|
+
flowType,
|
|
65
|
+
currency,
|
|
66
|
+
amount,
|
|
67
|
+
balance,
|
|
68
|
+
transactionType,
|
|
69
|
+
itemSku,
|
|
70
|
+
customFields
|
|
71
|
+
)
|
|
72
|
+
end
|
|
73
|
+
|
|
74
|
+
local defaultPrefix: boolean = economy.Prefix ~= false -- default true
|
|
75
|
+
local globalResolve = economy.Resolve
|
|
76
|
+
|
|
77
|
+
-- CustomField01/02/03 key names (the strings LogEconomyEvent expects).
|
|
78
|
+
local slotKeys: { string } = {}
|
|
79
|
+
for i = 1, MAX_FIELDS do
|
|
80
|
+
slotKeys[i] = (Enum.AnalyticsCustomFieldKeys :: any)[string.format("CustomField%02d", i)].Name
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
-- Precompile each currency's ordered slot specs (capped at the Roblox slots), a
|
|
84
|
+
-- declared-name set for typo warnings, and its label and resolver overrides.
|
|
85
|
+
local currencies: { [string]: Currency } = {}
|
|
86
|
+
for name, raw in (economy.Currencies or {}) :: { [string]: any } do
|
|
87
|
+
local fields: { FieldSpec } = {}
|
|
88
|
+
local declared: { [string]: boolean } = {}
|
|
89
|
+
for _, spec in (raw.Fields or {}) :: { any } do
|
|
90
|
+
local fieldName: any
|
|
91
|
+
local fieldPrefix: boolean
|
|
92
|
+
if type(spec) == "table" then
|
|
93
|
+
fieldName = spec.Name
|
|
94
|
+
fieldPrefix = if spec.Prefix == nil then defaultPrefix else spec.Prefix == true
|
|
95
|
+
else
|
|
96
|
+
fieldName = spec
|
|
97
|
+
fieldPrefix = defaultPrefix
|
|
98
|
+
end
|
|
99
|
+
if type(fieldName) ~= "string" then
|
|
100
|
+
error(
|
|
101
|
+
`Scribe: Economy.Currencies["{name}"].Fields entries must be a field name or \{ Name = "..." }`,
|
|
102
|
+
0
|
|
103
|
+
)
|
|
104
|
+
end
|
|
105
|
+
declared[fieldName] = true
|
|
106
|
+
if #fields >= MAX_FIELDS then
|
|
107
|
+
-- Silent truncation would read as "recorded" when it wasn't.
|
|
108
|
+
if devMode then
|
|
109
|
+
Log.Warn(
|
|
110
|
+
"Integrity",
|
|
111
|
+
"ECONOMY_FIELDS_OVERFLOW",
|
|
112
|
+
`currency "{name}" declares more than {MAX_FIELDS} custom fields; "{fieldName}" and any beyond it are dropped (Roblox allows {MAX_FIELDS})`,
|
|
113
|
+
{ Currency = name, Field = fieldName }
|
|
114
|
+
)
|
|
115
|
+
end
|
|
116
|
+
else
|
|
117
|
+
table.insert(fields, { Name = fieldName, Prefix = fieldPrefix })
|
|
118
|
+
end
|
|
119
|
+
end
|
|
120
|
+
currencies[name] = { Label = raw.Label, Resolve = raw.Resolve, Fields = fields, Declared = declared }
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
-- Merge a resolver's output into the pool, fail-safe: a throwing resolver
|
|
124
|
+
-- drops its fields (logged at Debug) rather than losing the whole event.
|
|
125
|
+
local function resolveInto(pool: { [string]: any }, fn: any, player: Player)
|
|
126
|
+
if not fn then
|
|
127
|
+
return
|
|
128
|
+
end
|
|
129
|
+
local ok, res = pcall(fn, player)
|
|
130
|
+
if ok and type(res) == "table" then
|
|
131
|
+
for key, value in res do
|
|
132
|
+
pool[key] = value
|
|
133
|
+
end
|
|
134
|
+
elseif not ok then
|
|
135
|
+
Log.Debug("Integrity", "ANALYTICS_FAIL", `economy Resolve threw: {tostring(res)}`, { Player = player })
|
|
136
|
+
end
|
|
137
|
+
end
|
|
138
|
+
|
|
139
|
+
local function buildCustomFields(player: Player, currency: Currency?, tags: { [string]: any }): { [string]: any }?
|
|
140
|
+
-- Custom fields need a declared slot mapping; an undeclared currency, or one with
|
|
141
|
+
-- no Fields, logs a plain event.
|
|
142
|
+
if not currency or #currency.Fields == 0 then
|
|
143
|
+
return nil
|
|
144
|
+
end
|
|
145
|
+
local pool: { [string]: any } = {}
|
|
146
|
+
resolveInto(pool, globalResolve, player)
|
|
147
|
+
resolveInto(pool, currency.Resolve, player)
|
|
148
|
+
local perCall = tags.Fields
|
|
149
|
+
if type(perCall) == "table" then
|
|
150
|
+
for key, value in perCall do
|
|
151
|
+
pool[key] = value
|
|
152
|
+
if devMode and not currency.Declared[key] then
|
|
153
|
+
Log.Warn(
|
|
154
|
+
"Integrity",
|
|
155
|
+
"ECONOMY_FIELD_UNDECLARED",
|
|
156
|
+
`economy field "{key}" is not declared for this currency and will not be recorded (typo?)`,
|
|
157
|
+
{ Player = player, Field = key }
|
|
158
|
+
)
|
|
159
|
+
end
|
|
160
|
+
end
|
|
161
|
+
end
|
|
162
|
+
local out: { [string]: any } = {}
|
|
163
|
+
local any = false
|
|
164
|
+
for i, spec in currency.Fields do
|
|
165
|
+
local value = pool[spec.Name]
|
|
166
|
+
if value ~= nil then
|
|
167
|
+
out[slotKeys[i]] = if spec.Prefix then `{spec.Name} - {value}` else value
|
|
168
|
+
any = true
|
|
169
|
+
end
|
|
170
|
+
end
|
|
171
|
+
return if any then out else nil
|
|
172
|
+
end
|
|
173
|
+
|
|
174
|
+
function self.Economy(
|
|
175
|
+
player: Player,
|
|
176
|
+
path: { string | number },
|
|
177
|
+
delta: number,
|
|
178
|
+
newValue: number,
|
|
179
|
+
tags: { [string]: any }
|
|
180
|
+
)
|
|
181
|
+
local fieldName = tostring(path[#path]) -- internal path segment; always safe
|
|
182
|
+
local currency = currencies[fieldName]
|
|
183
|
+
local flowType = if tags.Flow == "Sink"
|
|
184
|
+
then Enum.AnalyticsEconomyFlowType.Sink
|
|
185
|
+
else Enum.AnalyticsEconomyFlowType.Source
|
|
186
|
+
-- Safe fallback so the failure log below always has a label, even when the
|
|
187
|
+
-- caller-supplied Currency is the value that threw.
|
|
188
|
+
local currencyLabel = fieldName
|
|
189
|
+
|
|
190
|
+
-- One guard around formatting, field building and the log: every value here is
|
|
191
|
+
-- caller-supplied, and a throwing `__tostring` or `__iter` must not escape into
|
|
192
|
+
-- the Increment/Decrement caller after the write already applied.
|
|
193
|
+
local ok, err = pcall(function()
|
|
194
|
+
currencyLabel = tostring(tags.Currency or (currency and currency.Label) or fieldName)
|
|
195
|
+
local transactionType = txnName(if tags.TransactionType ~= nil then tags.TransactionType else tags.Source)
|
|
196
|
+
local itemSkuRaw = if tags.ItemSku ~= nil then tags.ItemSku else tags.Item
|
|
197
|
+
local itemSku = if itemSkuRaw ~= nil then tostring(itemSkuRaw) else nil
|
|
198
|
+
local customFields = buildCustomFields(player, currency, tags)
|
|
199
|
+
logEconomy(
|
|
200
|
+
player,
|
|
201
|
+
flowType,
|
|
202
|
+
currencyLabel,
|
|
203
|
+
math.abs(delta),
|
|
204
|
+
newValue,
|
|
205
|
+
transactionType,
|
|
206
|
+
itemSku,
|
|
207
|
+
customFields
|
|
208
|
+
)
|
|
209
|
+
end)
|
|
210
|
+
if ok then
|
|
211
|
+
Metrics.Add("EconomyEvents") -- count successes, not attempts
|
|
212
|
+
else
|
|
213
|
+
-- Debug logs are suppressed in production, so the counter is what makes a
|
|
214
|
+
-- systematically failing pipeline visible.
|
|
215
|
+
Metrics.Add("EconomyEventFailures")
|
|
216
|
+
Log.Debug("Integrity", "ANALYTICS_FAIL", tostring(err), { Player = player, Currency = currencyLabel })
|
|
217
|
+
end
|
|
218
|
+
end
|
|
219
|
+
|
|
220
|
+
return self
|
|
221
|
+
end
|
|
222
|
+
|
|
223
|
+
return Analytics
|