@trioforge/crucible 0.2.0 → 0.3.0

package/out/maths/spline/index.d.ts

@@ -0,0 +1,2 @@
+export { catmullRom, cubicBezier, uniformBSpline } from "./curve";
+export type { CatmullRomOptions, Curve, CurveFrame, CurveOptions, CurveProjection, CurveVector } from "./curve";

package/out/maths/spline/init.luau

@@ -0,0 +1,8 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local _curve = TS.import(script, script, "curve")
+exports.catmullRom = _curve.catmullRom
+exports.cubicBezier = _curve.cubicBezier
+exports.uniformBSpline = _curve.uniformBSpline
+return exports

package/out/server/index.d.ts

@@ -1,6 +1,7 @@
 import type { BootOptions } from "../index";
 import type { PayloadArgs, ToClient } from "../network";
 import "../internal/data/record-bindings";
+export declare const BOOTED_ATTRIBUTE = "CrucibleBooted";
 export { config, playerConfig, configReady, refreshConfigs } from "../configs";
 export type { Config, PlayerConfig } from "../configs";
 export { publish } from "./publish";

package/out/server/init.luau

@@ -13,6 +13,7 @@ if not game:GetService("RunService"):IsServer() then
 	error("@trioforge/crucible/server loaded on the client")
 end
 local session
+local BOOTED_ATTRIBUTE = "CrucibleBooted"
 local _configs = TS.import(script, script.Parent, "configs")
 exports.config = _configs.config
 exports.playerConfig = _configs.playerConfig
@@ -37,7 +38,13 @@ local function boot(options)
 	bootSide({
 		name = "server",
 		renders = false,
-		booted = function() end,
+		booted = function()
+			local service = game:GetService("ServerScriptService")
+			service:SetAttribute(BOOTED_ATTRIBUTE, true)
+			return function()
+				return service:SetAttribute(BOOTED_ATTRIBUTE, nil)
+			end
+		end,
 		network = network,
 	}, options)
 end
@@ -58,5 +65,6 @@ do
 	_container.broadcast = broadcast
 end
 exports.boot = boot
+exports.BOOTED_ATTRIBUTE = BOOTED_ATTRIBUTE
 exports.Network = Network
 return exports

package/out/testing/index.d.ts

@@ -0,0 +1,38 @@
+import type { CrucibleBehaviour } from "../crucible-behaviour";
+import { type MessageKind } from "../internal/network/catalog";
+import type { Branch } from "../internal/network/schema";
+import type { Subsystem } from "../subsystem";
+export { n } from "../internal/network/schema";
+/**
+ * Builds one Subsystem with the constructor arguments given, without `boot`. Its `receive()` fields register, and
+ * the spec calls its hooks as methods.
+ */
+export declare function subsystem<T extends Subsystem, A extends unknown[]>(klass: new (...args: A) => T, ...args: A): T;
+/**
+ * Builds one behaviour bound to `instance`, which may be a plain table. Each `attribute()` field reads the instance
+ * through `GetAttribute` and is refused as binding refuses it.
+ */
+export declare function behaviour<T extends CrucibleBehaviour<string>, A extends unknown[]>(klass: new (...args: A) => T, instance: Instance, ...args: A): T;
+/** The callback a built Subsystem's `receive()` field registered for `message`. */
+export declare function receiver(message: unknown): ((...args: never[]) => unknown) | undefined;
+/** The name, kind and schema nodes of a declared message. */
+export declare function message(token: unknown): {
+    name: string;
+    kind: MessageKind;
+    input: Branch;
+    output?: Branch;
+} | undefined;
+/** Sends `value` through the message's compiled codec and back, as the wire does, and returns what arrives. */
+export declare function transfer<T>(token: unknown, value: T, which?: "input" | "output"): T;
+/** Seals the message catalog and lists the names in wire order. It seals once per module graph. */
+export declare function sealMessages(): readonly string[];
+/** What the transformer registered for a class. */
+export declare function registration(klass: object): {
+    id: string;
+    kind: "subsystem";
+} | {
+    id: string;
+    kind: "behaviour";
+    tag: string;
+    instanceClasses: readonly string[];
+};

package/out/testing/init.luau

@@ -0,0 +1,189 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local _construction_claim = TS.import(script, script.Parent, "internal", "construction-claim")
+local clearClaim = _construction_claim.clearClaim
+local setClaim = _construction_claim.setClaim
+local track = TS.import(script, script.Parent, "internal", "lifecycle").track
+local _claims = TS.import(script, script.Parent, "internal", "network", "claims")
+local closeClaims = _claims.closeClaims
+local openClaims = _claims.openClaims
+local receiverOf = _claims.receiverOf
+local _catalog = TS.import(script, script.Parent, "internal", "network", "catalog")
+local definitionOf = _catalog.definitionOf
+local seal = _catalog.seal
+local _codec = TS.import(script, script.Parent, "internal", "network", "codec")
+local Reader = _codec.Reader
+local Writer = _codec.Writer
+local recordOf = TS.import(script, script.Parent, "internal", "registry").recordOf
+exports.n = TS.import(script, script.Parent, "internal", "network", "schema").n
+local function recordFor(klass)
+	return recordOf(klass) or error(`{tostring(klass)} is not a registered Crucible class; compile it with the Crucible transformer`, 0)
+end
+local function definitionFor(token)
+	return definitionOf(token) or error("not a message declared with toServer, toClient or askServer", 0)
+end
+local function construct(klass, state, args)
+	local id = (state.record).id
+	local thread = coroutine.create(function()
+		setClaim(state)
+		return klass.new(unpack(args))
+	end)
+	local ok, result = coroutine.resume(thread)
+	local yielded = ok and coroutine.status(thread) ~= "dead"
+	if yielded then
+		coroutine.close(thread)
+	end
+	clearClaim(thread)
+	if yielded then
+		error(`{id}'s constructor yielded; boot faults a constructor that yields`, 0)
+	end
+	if not ok then
+		error(result, 0)
+	end
+	return result
+end
+--[[
+	*
+	 * Builds one Subsystem with the constructor arguments given, without `boot`. Its `receive()` fields register, and
+	 * the spec calls its hooks as methods.
+	 
+]]
+local function subsystem(klass, ...)
+	local args = { ... }
+	local record = recordFor(klass)
+	if record.kind ~= 0 then
+		error(`{record.id} is a behaviour; build it with behaviour()`, 0)
+	end
+	-- A spec's RunService double only needs IsClient when the class has a receive() field.
+	openClaims({
+		side = function()
+			return if game:GetService("RunService"):IsClient() then "client" else "server"
+		end,
+		retired = function() end,
+	})
+	local ok, result = pcall(construct, klass, track(record), args)
+	closeClaims(false)
+	if not ok then
+		error(result, 0)
+	end
+	return result
+end
+--[[
+	*
+	 * Builds one behaviour bound to `instance`, which may be a plain table. Each `attribute()` field reads the instance
+	 * through `GetAttribute` and is refused as binding refuses it.
+	 
+]]
+local function behaviour(klass, instance, ...)
+	local args = { ... }
+	local record = recordFor(klass)
+	if record.kind ~= 1 then
+		error(`{record.id} is a Subsystem; build it with subsystem()`, 0)
+	end
+	local attributes
+	if record.attributes ~= nil then
+		attributes = {}
+		for field, descriptor in record.attributes do
+			local value = instance:GetAttribute(descriptor.name)
+			if not (if value == nil then not descriptor.required else descriptor.check(value)) then
+				error(`{record.id}: attribute {descriptor.name} is invalid ({typeof(value)})`, 0)
+			end
+			attributes[field] = value
+		end
+	end
+	return construct(klass, track(record, instance, attributes), args)
+end
+--* The callback a built Subsystem's `receive()` field registered for `message`. 
+local function receiver(message)
+	local _result = receiverOf(definitionFor(message))
+	if _result ~= nil then
+		_result = _result.callback
+	end
+	return _result
+end
+--* The name, kind and schema nodes of a declared message. 
+local function message(token)
+	local definition = definitionOf(token)
+	if definition == nil then
+		return nil
+	end
+	local _object = {
+		name = definition.name,
+		kind = definition.kind,
+		input = definition.input.node,
+	}
+	local _left = "output"
+	local _result = definition.output
+	if _result ~= nil then
+		_result = _result.node
+	end
+	_object[_left] = _result
+	return _object
+end
+local function failure(err)
+	local _err = err
+	local _condition = type(_err) == "table"
+	if _condition then
+		_condition = err.codecFailure == true
+	end
+	if _condition then
+		local _binding = err
+		local path = _binding.path
+		local reason = _binding.reason
+		return `{path}: {reason}`
+	end
+	return tostring(err)
+end
+--* Sends `value` through the message's compiled codec and back, as the wire does, and returns what arrives. 
+local function transfer(token, value, which)
+	if which == nil then
+		which = "input"
+	end
+	local definition = definitionFor(token)
+	local codec = definition[which] or error(`{definition.name} has no {which} codec`, 0)
+	local writer = Writer.new()
+	local encoded, encodeError = pcall(codec.encode, writer, value, "payload")
+	if not encoded then
+		error(`{definition.name} refused to encode {failure(encodeError)}`, 0)
+	end
+	local packet, sidecar, slots = writer:finish(buffer.create(0))
+	local reader = Reader.new(packet, 0, sidecar, slots)
+	local decoded, result = pcall(codec.decode, reader, "payload")
+	if not decoded then
+		error(`{definition.name} failed to decode {failure(result)}`, 0)
+	end
+	if not reader:finished() then
+		error(`{definition.name} left trailing bytes or slots`, 0)
+	end
+	return result
+end
+--* Seals the message catalog and lists the names in wire order. It seals once per module graph. 
+local function sealMessages()
+	local catalog = seal()
+	return if catalog == "" then {} else string.split(catalog, "\n")
+end
+--* What the transformer registered for a class. 
+local function registration(klass)
+	local record = recordFor(klass)
+	if record.kind == 0 then
+		return {
+			id = record.id,
+			kind = "subsystem",
+		}
+	end
+	return {
+		id = record.id,
+		kind = "behaviour",
+		tag = record.tag,
+		instanceClasses = record.instanceClasses,
+	}
+end
+exports.subsystem = subsystem
+exports.behaviour = behaviour
+exports.receiver = receiver
+exports.message = message
+exports.transfer = transfer
+exports.sealMessages = sealMessages
+exports.registration = registration
+return exports

package/out/util/random/index.d.ts

@@ -0,0 +1,24 @@
+export type SeedPart = string | number;
+export type RngState = readonly [number, number, number, number];
+export declare class Rng {
+    private a;
+    private b;
+    private c;
+    private d;
+    constructor(...seed: SeedPart[]);
+    static fromState(state: RngState): Rng;
+    state(): RngState;
+    clone(): Rng;
+    fork(): Rng;
+    uint32(): number;
+    float(): number;
+    float(min: number, max: number): number;
+    int(min: number, max: number): number;
+    chance(probability: number): boolean;
+    normal(mean?: number, deviation?: number): number;
+    pick<T extends defined>(items: readonly T[]): T;
+    weightedIndex(weights: readonly number[]): number;
+    weighted<T extends defined>(items: readonly T[], weight: (item: T, index: number) => number): T;
+    shuffle<T extends defined>(items: readonly T[]): T[];
+    sample<T extends defined>(items: readonly T[], count: number): T[];
+}

package/out/util/random/init.luau

@@ -0,0 +1,301 @@
+-- Compiled with roblox-ts v3.0.0
+local WORD = 2 ^ 32
+local DOUBLE = 2 ^ 53
+-- Luau has no 32-bit multiply, and a full product of two words overflows a double's 53 bits, so it splits one side.
+local function imul(a, b)
+	local low = a * (b % 65536)
+	local high = ((a * math.floor(b / 65536)) % WORD) * 65536
+	return (low + high) % WORD
+end
+local function fmix(h)
+	h = imul(bit32.bxor(h, bit32.rshift(h, 16)), 0x85ebca6b)
+	h = imul(bit32.bxor(h, bit32.rshift(h, 13)), 0xc2b2ae35)
+	return bit32.bxor(h, bit32.rshift(h, 16))
+end
+local STRING = 0x5354524e
+local NUMBER = 0x4e554d42
+local function words(parts)
+	local result = { #parts }
+	for _, part in parts do
+		if type(part) == "string" then
+			local _arg1 = #part
+			-- ▼ Array.push ▼
+			table.insert(result, STRING)
+			table.insert(result, _arg1)
+			-- ▲ Array.push ▲
+			for index = 1, #part, 4 do
+				local a, b, c, d = string.byte(part, index, index + 3)
+				local _condition = a
+				if _condition == nil then
+					_condition = 0
+				end
+				local _condition_1 = b
+				if _condition_1 == nil then
+					_condition_1 = 0
+				end
+				local _exp = _condition + _condition_1 * 0x100
+				local _condition_2 = c
+				if _condition_2 == nil then
+					_condition_2 = 0
+				end
+				local _exp_1 = _exp + _condition_2 * 0x10000
+				local _condition_3 = d
+				if _condition_3 == nil then
+					_condition_3 = 0
+				end
+				table.insert(result, _exp_1 + _condition_3 * 0x1000000)
+			end
+		else
+			if part ~= part or part % 1 ~= 0 or math.abs(part) > DOUBLE then
+				error(`a seed number must be an integer within ±2^53, got {part}`, 3)
+			end
+			local _arg1 = part % WORD
+			local _arg2 = math.floor(part / WORD) % WORD
+			-- ▼ Array.push ▼
+			table.insert(result, NUMBER)
+			table.insert(result, _arg1)
+			table.insert(result, _arg2)
+			-- ▲ Array.push ▲
+		end
+	end
+	return result
+end
+local LANES = { 0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a }
+local function hashState(input)
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#LANES)
+	local _callback = function(lane)
+		local h = lane
+		for _, word in input do
+			h = fmix((imul(bit32.bxor(h, word), 0x9e3779b1) + lane) % WORD)
+		end
+		return fmix(h)
+	end
+	for _k, _v in LANES do
+		_newValue[_k] = _callback(_v, _k - 1, LANES)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	local state = _newValue
+	-- ▼ ReadonlyArray.every ▼
+	local _result = true
+	local _callback_1 = function(word)
+		return word == 0
+	end
+	for _k, _v in state do
+		if not _callback_1(_v, _k - 1, state) then
+			_result = false
+			break
+		end
+	end
+	-- ▲ ReadonlyArray.every ▲
+	if _result then
+		state[1] = 1
+	end
+	return { state[1], state[2], state[3], state[4] }
+end
+local function entropy()
+	return { math.random(0, 0xffff), math.random(0, 0xffff), math.random(0, 0xffff), math.floor(os.clock() * 1e6) % WORD }
+end
+local Rng
+do
+	Rng = setmetatable({}, {
+		__tostring = function()
+			return "Rng"
+		end,
+	})
+	Rng.__index = Rng
+	function Rng.new(...)
+		local self = setmetatable({}, Rng)
+		return self:constructor(...) or self
+	end
+	function Rng:constructor(...)
+		local seed = { ... }
+		local _binding = hashState(if #seed > 0 then words(seed) else entropy())
+		self.a = _binding[1]
+		self.b = _binding[2]
+		self.c = _binding[3]
+		self.d = _binding[4]
+	end
+	function Rng:fromState(state)
+		local rng = Rng.new(0)
+		for _, word in state do
+			if word % 1 ~= 0 or word < 0 or word >= WORD then
+				error(`a state word must be a uint32, got {word}`, 2)
+			end
+		end
+		-- ▼ ReadonlyArray.every ▼
+		local _result = true
+		local _callback = function(word)
+			return word == 0
+		end
+		for _k, _v in state do
+			if not _callback(_v, _k - 1, state) then
+				_result = false
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.every ▲
+		if _result then
+			error("a state can't be all zeroes", 2)
+		end
+		local _binding = state
+		rng.a = _binding[1]
+		rng.b = _binding[2]
+		rng.c = _binding[3]
+		rng.d = _binding[4]
+		return rng
+	end
+	function Rng:state()
+		return { self.a, self.b, self.c, self.d }
+	end
+	function Rng:clone()
+		return Rng:fromState(self:state())
+	end
+	function Rng:fork()
+		return Rng.new(self:uint32(), self:uint32(), self:uint32(), self:uint32())
+	end
+	function Rng:uint32()
+		local result = (bit32.lrotate((self.b * 5) % WORD, 7) * 9) % WORD
+		local t = bit32.lshift(self.b, 9)
+		self.c = bit32.bxor(self.c, self.a)
+		self.d = bit32.bxor(self.d, self.b)
+		self.b = bit32.bxor(self.b, self.c)
+		self.a = bit32.bxor(self.a, self.d)
+		self.c = bit32.bxor(self.c, t)
+		self.d = bit32.lrotate(self.d, 11)
+		return result
+	end
+	function Rng:float(min, max)
+		local unit = (bit32.rshift(self:uint32(), 5) * 2 ^ 26 + bit32.rshift(self:uint32(), 6)) / DOUBLE
+		if min == nil or max == nil then
+			return unit
+		end
+		if not (min <= max) then
+			error(`float needs min <= max, got {min} and {max}`, 2)
+		end
+		return min + unit * (max - min)
+	end
+	function Rng:int(min, max)
+		if min % 1 ~= 0 or max % 1 ~= 0 then
+			error(`int needs integer bounds, got {min} and {max}`, 2)
+		end
+		local span = max - min + 1
+		if span < 1 then
+			error(`int needs min <= max, got {min} and {max}`, 2)
+		end
+		if span > WORD then
+			error(`int spans at most 2^32 values, got {span}`, 2)
+		end
+		local limit = WORD - (WORD % span)
+		local value = self:uint32()
+		while value >= limit do
+			value = self:uint32()
+		end
+		return min + (value % span)
+	end
+	function Rng:chance(probability)
+		return self:float() < probability
+	end
+	function Rng:normal(mean, deviation)
+		if mean == nil then
+			mean = 0
+		end
+		if deviation == nil then
+			deviation = 1
+		end
+		local radius = math.sqrt(-2 * math.log(1 - self:float()))
+		return mean + deviation * radius * math.cos(2 * math.pi * self:float())
+	end
+	function Rng:pick(items)
+		if #items == 0 then
+			error("can't pick from an empty array", 2)
+		end
+		return items[self:int(0, #items - 1) + 1]
+	end
+	function Rng:weightedIndex(weights)
+		local total = 0
+		for _, weight in weights do
+			if not (weight >= 0 and weight < math.huge) then
+				error(`a weight must be finite and non-negative, got {weight}`, 2)
+			end
+			total += weight
+		end
+		if total <= 0 then
+			error("weights must add up to more than zero", 2)
+		end
+		local roll = self:float() * total
+		local last = 0
+		for index = 0, #weights - 1 do
+			if weights[index + 1] <= 0 then
+				continue
+			end
+			last = index
+			roll -= weights[index + 1]
+			if roll < 0 then
+				return index
+			end
+		end
+		-- Rounding can leave a sliver of the roll past the last bucket.
+		return last
+	end
+	function Rng:weighted(items, weight)
+		local _exp = items
+		local _self = self
+		local _items = items
+		local _weight = weight
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue = table.create(#_items)
+		for _k, _v in _items do
+			_newValue[_k] = _weight(_v, _k - 1, _items)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		return _exp[_self:weightedIndex(_newValue) + 1]
+	end
+	function Rng:shuffle(items)
+		local _array = {}
+		local _length = #_array
+		table.move(items, 1, #items, _length + 1, _array)
+		local result = _array
+		for index = #result - 1, 1, -1 do
+			local other = self:int(0, index)
+			local _index = index + 1
+			local _index_1 = other + 1
+			result[_index], result[_index_1] = result[other + 1], result[index + 1]
+		end
+		return result
+	end
+	function Rng:sample(items, count)
+		if count % 1 ~= 0 or count < 0 or count > #items then
+			error(`sample needs a count from 0 to {#items}, got {count}`, 2)
+		end
+		local _array = {}
+		local _length = #_array
+		table.move(items, 1, #items, _length + 1, _array)
+		local pool = _array
+		local result = {}
+		do
+			local index = 0
+			local _shouldIncrement = false
+			while true do
+				if _shouldIncrement then
+					index += 1
+				else
+					_shouldIncrement = true
+				end
+				if not (index < count) then
+					break
+				end
+				local other = self:int(index, #pool - 1)
+				local _index = index + 1
+				local _index_1 = other + 1
+				pool[_index], pool[_index_1] = pool[other + 1], pool[index + 1]
+				local _arg0 = pool[index + 1]
+				table.insert(result, _arg0)
+			end
+		end
+		return result
+	end
+end
+return {
+	Rng = Rng,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@trioforge/crucible",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"license": "MIT",
 	"main": "out/init.luau",
 	"types": "out/index.d.ts",
@@ -25,6 +25,18 @@
 			"types": "./out/vide/index.d.ts",
 			"default": "./out/vide/init.luau"
 		},
+		"./util/random": {
+			"types": "./out/util/random/index.d.ts",
+			"default": "./out/util/random/init.luau"
+		},
+		"./maths/spline": {
+			"types": "./out/maths/spline/index.d.ts",
+			"default": "./out/maths/spline/init.luau"
+		},
+		"./testing": {
+			"types": "./out/testing/index.d.ts",
+			"default": "./out/testing/init.luau"
+		},
 		"./transformer": "./transformer/index.js"
 	},
 	"peerDependencies": {
@@ -43,6 +55,9 @@
 		"client",
 		"emit",
 		"vide",
+		"util",
+		"maths",
+		"testing",
 		"LICENSE"
 	],
 	"repository": {

package/testing/package.json

@@ -0,0 +1,4 @@
+{
+	"main": "../out/testing/init.luau",
+	"types": "../out/testing/index.d.ts"
+}