@rbxts/scribe-leaderstats 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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ericplane
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICE ADDED
@@ -0,0 +1,21 @@
1
+ Scribe
2
+ Copyright (c) 2026 ericplane
3
+ Licensed under the MIT License (see LICENSE).
4
+
5
+ This product bundles a modified copy of ProfileStore v1.0.3:
6
+
7
+ ProfileStore
8
+ Copyright (c) loleris / MAD STUDIO
9
+ https://github.com/MadStudioRoblox/ProfileStore
10
+ Licensed under the Apache License, Version 2.0.
11
+
12
+ The bundled copy lives at src/Internal/Store/ProfileStore.luau and HAS BEEN
13
+ MODIFIED. Every modification is marked `SCRIBE PATCH` in that file and summarised
14
+ in its header. A copy of the Apache License, Version 2.0 is included at
15
+ licenses/ProfileStore-Apache-2.0.txt.
16
+
17
+ The licence text is kept OUTSIDE src/ on purpose. Everything under src/ is packed
18
+ into the released .rbxm, where a plain text file has no place and whose contents
19
+ Roblox scans for off-platform links -- and the licence is full of them. Attribution
20
+ travels with the code in the file header, which is what Apache-2.0 section 4
21
+ actually asks for; the full text travels with the source package.
package/README.md ADDED
@@ -0,0 +1,5 @@
1
+ # @rbxts/scribe-leaderstats
2
+
3
+ Optional Scribe addon. Install only if you use it.
4
+
5
+ See [the roblox-ts guide](https://scribe.ericplane.dev/roblox-ts/) for usage.
@@ -0,0 +1 @@
1
+ {"version":"2.5.0","format":1,"description":"Segments are [packedLine, sourceLine]. Use the last segment at or before the packed line, then add its line offset.","files":{"addons/leaderstats/ScribeLeaderstats.luau":{"sourceSha256":"baceac185a04d1dd5cc2fe590e778913f5d737175aef7ccffb3459be1e96afba","packedSha256":"333d4e4272e0a3d8504e9f534f8db488caa256162b348f3b20ef748cd9294a22","segments":[[1,1]],"packagePath":"init.luau"}}}
package/index.d.ts ADDED
@@ -0,0 +1,42 @@
1
+ import type Scribe from "@rbxts/scribe";
2
+
3
+ /** Optional server-side bridge to Roblox's built-in player list. */
4
+ declare namespace ScribeLeaderstats {
5
+ interface DataAPI {
6
+ readonly WaitForData: (this: void, player: Player, timeout?: number) => LuaTuple<[
7
+ { readonly Get: (this: void) => unknown } | undefined,
8
+ string | undefined,
9
+ ]>;
10
+ readonly SessionEnded: Pick<Scribe.Signal<[Player, Scribe.LifecycleReason]>, "Connect">;
11
+ }
12
+ type Join<Key extends string, Path> = Path extends string ? `${Key}.${Path}` : never;
13
+ /** Static, always-present scalar paths. Containers, optional fields and Big values are excluded. */
14
+ type Paths<T, Depth extends unknown[] = []> =
15
+ Depth extends [unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown] ? never
16
+ : undefined extends T ? never
17
+ : T extends number | string | boolean ? ""
18
+ : T extends Scribe.BigValue | Scribe.Datatype | buffer | ReadonlyArray<unknown> | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> ? never
19
+ : T extends object ? {
20
+ [Key in Extract<keyof T, string>]: string extends Key ? never
21
+ : Key extends "" | `${string}.${string}` ? never
22
+ : Paths<T[Key], [...Depth, unknown]> extends infer Path
23
+ ? Path extends "" ? Key : Join<Key, Path> : never
24
+ }[Extract<keyof T, string>] : never;
25
+ type Values<Data extends DataAPI> = ReturnType<NonNullable<ReturnType<Data["WaitForData"]>[0]>["Get"]>;
26
+ type Stats<Data extends DataAPI> = { readonly [displayName: string]: Paths<Values<Data>> };
27
+ interface Handle {
28
+ /** Disconnect and remove only the instances created by this handle. Safe to repeat. */
29
+ Stop(): void;
30
+ }
31
+ /** Dependency overrides for isolated tests. Omit in game code. */
32
+ interface Dependencies {
33
+ Players?: Pick<Players, "GetPlayers" | "PlayerAdded" | "PlayerRemoving">;
34
+ NewInstance?: (this: void, className: string) => Instance;
35
+ IsServer?: (this: void) => boolean;
36
+ Warn?: (this: void, message: string) => void;
37
+ }
38
+ /** Every selected stat is public to every client, including ServerOnly/Session paths. */
39
+ function Start<Data extends DataAPI>(data: Data, stats: Stats<NoInfer<Data>>, dependencies?: Dependencies): Handle;
40
+ }
41
+
42
+ export = ScribeLeaderstats;
package/init.luau ADDED
@@ -0,0 +1,220 @@
1
+ --!strict
2
+ -- An opt-in, one-way bridge from Scribe accessors to Roblox's player list.
3
+ -- Every selected value becomes public, regardless of its template visibility.
4
+
5
+ local Players = game:GetService("Players")
6
+ local RunService = game:GetService("RunService")
7
+
8
+ export type Stats = { [string]: string }
9
+ export type Handle = { Stop: (self: Handle) -> () }
10
+ export type DataAPI = {
11
+ WaitForData: (player: Player, timeout: number?) -> (any?, string?),
12
+ SessionEnded: { Connect: (self: any, callback: (player: Player, reason: string) -> ()) -> any },
13
+ }
14
+ --- Test dependencies; normal game code omits this argument.
15
+ export type Dependencies = {
16
+ Players: any?,
17
+ NewInstance: ((className: string) -> any)?,
18
+ IsServer: (() -> boolean)?,
19
+ Warn: ((message: string) -> ())?,
20
+ }
21
+
22
+ local ScribeLeaderstats = {}
23
+ type Definition = { Name: string, Path: string, Segments: { string } }
24
+ local active: { [any]: boolean } = setmetatable({}, { __mode = "k" }) :: any
25
+ local classes = { number = "NumberValue", string = "StringValue", boolean = "BoolValue" }
26
+ local LOAD_WAIT = 10
27
+
28
+ local function validText(value: any): boolean
29
+ return type(value) == "string" and #value > 0 and utf8.len(value) ~= nil and string.find(value, "%c") == nil
30
+ end
31
+
32
+ local function scalarClass(value: any): string?
33
+ if type(value) == "number" and (value ~= value or math.abs(value) == math.huge) then
34
+ return nil
35
+ end
36
+ return (classes :: any)[type(value)]
37
+ end
38
+
39
+ function ScribeLeaderstats.Start(data: DataAPI, stats: Stats, dependencies: Dependencies?): Handle
40
+ local deps: Dependencies = dependencies or {}
41
+ local isServer = deps.IsServer or function()
42
+ return RunService:IsServer()
43
+ end
44
+ assert(isServer(), "ScribeLeaderstats: Start must run on the server")
45
+ assert(
46
+ type(data) == "table" and type(data.WaitForData) == "function" and data.SessionEnded ~= nil,
47
+ "ScribeLeaderstats: expected Scribe's server Data API"
48
+ )
49
+ assert(not active[data], "ScribeLeaderstats: already started for this Data API; Stop() the running one first")
50
+ assert(type(stats) == "table", "ScribeLeaderstats: stats must map display names to paths")
51
+ local definitions: { Definition } = {}
52
+ for name, path in stats do
53
+ assert(
54
+ validText(name),
55
+ "ScribeLeaderstats: display names must be non-empty UTF-8 strings without control characters"
56
+ )
57
+ assert(validText(path), `ScribeLeaderstats: invalid path for "{name}"`)
58
+ local segments = string.split(path, ".")
59
+ for _, segment in segments do
60
+ assert(#segment > 0, `ScribeLeaderstats: invalid path "{path}"`)
61
+ end
62
+ table.insert(definitions, { Name = name, Path = path, Segments = segments })
63
+ end
64
+ assert(#definitions > 0, "ScribeLeaderstats: configure at least one stat")
65
+ table.sort(definitions, function(a: Definition, b: Definition)
66
+ return a.Name < b.Name
67
+ end)
68
+
69
+ local players: any = deps.Players or Players
70
+ local create = deps.NewInstance or function(className: string): any
71
+ return Instance.new(className)
72
+ end
73
+ local report = deps.Warn or warn
74
+ local stopped = false
75
+ local states: { [any]: any } = {}
76
+ local connections: { any } = {}
77
+ local handle = {} :: Handle
78
+
79
+ local function release(player: any)
80
+ local state = states[player]
81
+ if not state then
82
+ return
83
+ end
84
+ states[player] = nil
85
+ for _, disconnect in state.Disconnects do
86
+ disconnect()
87
+ end
88
+ for _, instance in state.Values do
89
+ instance:Destroy()
90
+ end
91
+ -- Another script may have added children to our folder after startup.
92
+ -- Never destroy those children or a folder we did not create.
93
+ if state.OwnFolder and state.Folder and #state.Folder:GetChildren() == 0 then
94
+ state.Folder:Destroy()
95
+ end
96
+ end
97
+
98
+ local function mount(player: any, state: any, accessor: any)
99
+ local resolved = {}
100
+ local folder = player:FindFirstChild("leaderstats")
101
+ assert(folder == nil or folder:IsA("Folder"), "an existing leaderstats instance is not a Folder")
102
+ -- Validate every selected value before adding any instances or observers.
103
+ for _, definition in definitions do
104
+ assert(
105
+ folder == nil or folder:FindFirstChild(definition.Name) == nil,
106
+ `stat "{definition.Name}" already exists`
107
+ )
108
+ local node = accessor
109
+ for _, segment in definition.Segments do
110
+ node = node.Child(segment)
111
+ end
112
+ local value = node.Get()
113
+ local className = scalarClass(value)
114
+ assert(className ~= nil, `path "{definition.Path}" must contain a finite number, string, or boolean`)
115
+ table.insert(resolved, { Definition = definition, Node = node, Value = value, Class = className })
116
+ end
117
+ state.OwnFolder = folder == nil
118
+ if folder == nil then
119
+ folder = create("Folder")
120
+ folder.Name = "leaderstats"
121
+ end
122
+ state.Folder = folder
123
+ for _, item in resolved do
124
+ local instance = create(item.Class)
125
+ table.insert(state.Values, instance)
126
+ instance.Name = item.Definition.Name
127
+ instance.Value = item.Value
128
+ instance.Parent = folder
129
+ local disconnect = item.Node.Observe(function(value: any)
130
+ if stopped or states[player] ~= state then
131
+ return
132
+ end
133
+ if scalarClass(value) ~= item.Class then
134
+ release(player)
135
+ report(
136
+ `ScribeLeaderstats: removed stats for {player.Name}: path "{item.Definition.Path}" changed type or became absent`
137
+ )
138
+ return
139
+ end
140
+ if instance.Value ~= value then
141
+ instance.Value = value
142
+ end
143
+ end)
144
+ if states[player] ~= state then
145
+ disconnect()
146
+ return
147
+ end
148
+ table.insert(state.Disconnects, disconnect)
149
+ end
150
+ if state.OwnFolder then
151
+ folder.Parent = player
152
+ end
153
+ end
154
+
155
+ local function join(player: any)
156
+ if stopped or states[player] ~= nil then
157
+ return
158
+ end
159
+ local state = { Disconnects = {}, Values = {} }
160
+ states[player] = state
161
+ task.spawn(function()
162
+ -- WaitForData owns a signal connection while yielding. Let each bounded
163
+ -- wait finish instead of cancelling its coroutine and stranding it.
164
+ while not stopped and states[player] == state do
165
+ local ok, accessor, reason = pcall(data.WaitForData, player, LOAD_WAIT)
166
+ if stopped or states[player] ~= state then
167
+ return
168
+ end
169
+ if ok and accessor ~= nil then
170
+ local mounted, err = pcall(mount, player, state, accessor)
171
+ if not mounted then
172
+ release(player)
173
+ report(`ScribeLeaderstats: could not attach stats for {player.Name}: {tostring(err)}`)
174
+ end
175
+ return
176
+ elseif ok and reason == "still-loading" then
177
+ continue
178
+ else
179
+ release(player)
180
+ if not ok then
181
+ report(`ScribeLeaderstats: could not load stats for {player.Name}: {tostring(accessor)}`)
182
+ end
183
+ return
184
+ end
185
+ end
186
+ end)
187
+ end
188
+
189
+ function handle:Stop()
190
+ if stopped then
191
+ return
192
+ end
193
+ stopped = true
194
+ for _, connection in connections do
195
+ connection:Disconnect()
196
+ end
197
+ table.clear(connections)
198
+ for player in states do
199
+ release(player)
200
+ end
201
+ active[data] = nil
202
+ end
203
+
204
+ active[data] = true
205
+ local ok, err = pcall(function()
206
+ table.insert(connections, (players.PlayerAdded:Connect(join)))
207
+ table.insert(connections, (players.PlayerRemoving:Connect(release)))
208
+ table.insert(connections, data.SessionEnded:Connect(release))
209
+ for _, player in players:GetPlayers() do
210
+ join(player)
211
+ end
212
+ end)
213
+ if not ok then
214
+ handle:Stop()
215
+ error(err, 2)
216
+ end
217
+ return handle
218
+ end
219
+
220
+ return table.freeze(ScribeLeaderstats)
package/package.json ADDED
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "@rbxts/scribe-leaderstats",
3
+ "version": "2.5.0",
4
+ "description": "Optional leaderstats addon for Scribe",
5
+ "main": "init.luau",
6
+ "types": "index.d.ts",
7
+ "license": "MIT",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "https://github.com/ericplane/Scribe.git"
11
+ },
12
+ "homepage": "https://scribe.ericplane.dev/",
13
+ "author": "ericplane",
14
+ "peerDependencies": {
15
+ "@rbxts/scribe": "^2.5.0"
16
+ },
17
+ "publishConfig": {
18
+ "access": "public"
19
+ }
20
+ }