@trioforge/crucible 0.0.0-stage → 0.1.0

package/out/internal/runner.luau

@@ -0,0 +1,86 @@
+-- Compiled with roblox-ts v3.0.0
+--* @internal 
+--* @internal The error value of a call that yielded. 
+local YIELDED = "yielded; only start may yield"
+local DONE = {}
+local free = {}
+local owners = {}
+local function loop(work, a, b)
+	while true do
+		-- The only resumer is `call`, which always passes a function and its two arguments.
+		local result = work(a, b)
+		-- A parked worker must not keep its last arguments alive.
+		work = nil
+		a = nil
+		b = nil
+		local nextWork, nextA, nextB = coroutine.yield(DONE, result)
+		work = nextWork
+		a = nextA
+		b = nextB
+	end
+end
+--[[
+	*
+	 * @internal
+	 * Runs every callback that must not yield: hooks other than `start`, constructors, `accepts`, and `All<T>`
+	 * callbacks. A pool of parked worker coroutines (GoodSignal's free-runner trick) detects a yield, which
+	 * `pcall` cannot. A worker returns to the pool after a call that returned, so steady-state calls allocate
+	 * nothing. A throw kills its worker, and a yield gets its worker cancelled, so only failures allocate a new
+	 * one. A callback that calls `call` again takes another worker, and the pool grows to the deepest nesting.
+	 *
+	 * `owner` becomes the worker's owner for the call, which is what `current()` reads. Without one the call is
+	 * ownerless. Returns the callback's result on Ok, or the error (with a traceback) on Threw and Yielded.
+	 
+]]
+local function call(work, a, b, owner)
+	-- ▼ Array.pop ▼
+	local _length = #free
+	local _result = free[_length]
+	free[_length] = nil
+	-- ▲ Array.pop ▲
+	local _condition = _result
+	if _condition == nil then
+		_condition = coroutine.create(loop)
+	end
+	local worker = _condition
+	if owner ~= nil then
+		local _owner = owner
+		owners[worker] = _owner
+	end
+	local ok, marker, value = coroutine.resume(worker, work, a, b)
+	owners[worker] = nil
+	if not ok then
+		return 1, debug.traceback(worker, tostring(marker))
+	end
+	if marker ~= DONE then
+		local trace = debug.traceback(worker, YIELDED)
+		-- A failed cancel leaves the worker suspended, so it never returns to the pool.
+		local cancelled, err = pcall(task.cancel, worker)
+		return 2, if cancelled then trace else `{trace}\ncancellation failed: {err}`
+	end
+	table.insert(free, worker)
+	return 0, value
+end
+--* @internal The object that owns `thread`: a runner worker during an owned call, or a start thread for its life. 
+local function ownerOf(thread)
+	local _thread = thread
+	return owners[_thread]
+end
+--* @internal 
+local function own(thread, owner)
+	local _thread = thread
+	local _owner = owner
+	owners[_thread] = _owner
+end
+--* @internal 
+local function disown(thread)
+	local _thread = thread
+	owners[_thread] = nil
+end
+return {
+	call = call,
+	ownerOf = ownerOf,
+	own = own,
+	disown = disown,
+	YIELDED = YIELDED,
+}

package/out/internal/scheduler.d.ts

@@ -0,0 +1 @@
+export {};

package/out/internal/scheduler.luau

@@ -0,0 +1,207 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local runtimeDiagnostic = TS.import(script, script.Parent, "diagnostics").runtimeDiagnostic
+local DenseList = TS.import(script, script.Parent, "dense-list").DenseList
+local within = TS.import(script, script.Parent, "lifecycle").within
+--* @internal 
+--* @internal 
+--* @internal 
+--* @internal 
+local MAX_FIXED_STEPS = 4
+--* @internal 
+local MAX_FRAME_SECONDS = 0.25
+--* @internal 
+local function accumulate(carry, frameDt, step)
+	local total = carry + math.clamp(frameDt, 0, MAX_FRAME_SECONDS)
+	local whole = math.floor(total / step)
+	return math.min(whole, MAX_FIXED_STEPS), math.max(total - whole * step, 0)
+end
+local Lane
+do
+	Lane = setmetatable({}, {
+		__tostring = function()
+			return "Lane"
+		end,
+	})
+	Lane.__index = Lane
+	function Lane.new(...)
+		local self = setmetatable({}, Lane)
+		return self:constructor(...) or self
+	end
+	function Lane:constructor(hook, frame)
+		self.members = DenseList.new()
+		self.dt = 0
+		local caller = function(s, dt)
+			return frame[hook](s.object, dt)
+		end
+		self.visit = function(s)
+			return within(s, s, 6, caller, s, self.dt)
+		end
+	end
+	function Lane:run(dt)
+		self.dt = dt
+		self.members:forEach(self.visit)
+	end
+end
+--* @internal 
+local Scheduler
+do
+	Scheduler = setmetatable({}, {
+		__tostring = function()
+			return "Scheduler"
+		end,
+	})
+	Scheduler.__index = Scheduler
+	function Scheduler.new(...)
+		local self = setmetatable({}, Scheduler)
+		return self:constructor(...) or self
+	end
+	function Scheduler:constructor(port, config, frame)
+		self.port = port
+		self.config = config
+		self.frame = frame
+		self.renderLanes = {}
+		self.refusedClasses = {}
+		self.carry = 0
+		self.step = 1 / config.fixedRate
+		self.lanes = {
+			[0] = Lane.new(0, frame),
+			[1] = Lane.new(1, frame),
+			[2] = Lane.new(2, frame),
+			[3] = Lane.new(3, frame),
+		}
+	end
+	function Scheduler:add(s)
+		local record = s.record
+		local mask = record.hooks
+		if not self.config.renders and ((bit32.band(mask, (bit32.lshift(1, 0)))) ~= 0 or record.renderPriority ~= nil) then
+			local _refusedClasses = self.refusedClasses
+			local _id = record.id
+			if not (_refusedClasses[_id] ~= nil) then
+				local _refusedClasses_1 = self.refusedClasses
+				local _id_1 = record.id
+				_refusedClasses_1[_id_1] = true
+				runtimeDiagnostic("error", `Crucible server refuses preRender and renderPriority for {record.id}`)
+			end
+			return nil
+		end
+		if (bit32.band(mask, (bit32.lshift(1, 0)))) ~= 0 then
+			self:join(self:renderLaneOf(s), 0, s)
+		end
+		for _, hook in { 1, 2, 3 } do
+			if (bit32.band(mask, (bit32.lshift(1, hook)))) ~= 0 then
+				self:join(self.lanes[hook], hook, s)
+			end
+		end
+	end
+	function Scheduler:remove(s)
+		local priority = (s.record).renderPriority
+		local render = if priority == nil then self.lanes[0] else self.renderLanes[priority]
+		if render ~= nil and render.members:remove(s) and render.members:size() == 0 then
+			local _result = render.disconnect
+			if _result ~= nil then
+				_result()
+			end
+			render.disconnect = nil
+		end
+		local fixed = self.lanes[1]
+		if fixed.members:remove(s) and fixed.members:size() == 0 then
+			local _result = fixed.disconnect
+			if _result ~= nil then
+				_result()
+			end
+			fixed.disconnect = nil
+			self.carry = 0
+		end
+		local update = self.lanes[2]
+		local late = self.lanes[3]
+		local changed = update.members:remove(s)
+		if (late.members:remove(s) or changed) and update.members:size() == 0 and late.members:size() == 0 then
+			local _result = self.postSimulation
+			if _result ~= nil then
+				_result()
+			end
+			self.postSimulation = nil
+		end
+	end
+	function Scheduler:renderLaneOf(s)
+		local priority = (s.record).renderPriority
+		if priority == nil then
+			return self.lanes[0]
+		end
+		local lane = self.renderLanes[priority]
+		if lane == nil then
+			lane = Lane.new(0, self.frame)
+			local _renderLanes = self.renderLanes
+			local _lane = lane
+			_renderLanes[priority] = _lane
+		end
+		return lane
+	end
+	function Scheduler:join(lane, hook, s)
+		if not lane.members:add(s) then
+			return nil
+		end
+		local port = self.port
+		repeat
+			local _fallthrough = false
+			if hook == 0 then
+				if lane.disconnect ~= nil or not self.config.renders then
+					return nil
+				end
+				local priority = (s.record).renderPriority
+				local run = function(dt)
+					return lane:run(dt)
+				end
+				lane.disconnect = if priority == nil then port.onFrame(0, run) else port.bindRenderStep(`crucible:{priority}`, priority, run)
+				return nil
+			end
+			if hook == 1 then
+				if lane.disconnect ~= nil then
+					return nil
+				end
+				lane.disconnect = port.onFrame(1, function(dt)
+					local steps, carry = accumulate(self.carry, dt, self.step)
+					self.carry = carry
+					do
+						local i = 0
+						local _shouldIncrement = false
+						while true do
+							if _shouldIncrement then
+								i += 1
+							else
+								_shouldIncrement = true
+							end
+							if not (i < steps) then
+								break
+							end
+							lane:run(self.step)
+						end
+					end
+				end)
+				return nil
+			end
+			if hook == 2 then
+				_fallthrough = true
+			end
+			if _fallthrough or hook == 3 then
+				if self.postSimulation ~= nil then
+					return nil
+				end
+				local update = self.lanes[2]
+				local late = self.lanes[3]
+				self.postSimulation = port.onFrame(2, function(dt)
+					update:run(dt)
+					late:run(dt)
+				end)
+				return nil
+			end
+		until true
+	end
+end
+return {
+	accumulate = accumulate,
+	MAX_FIXED_STEPS = MAX_FIXED_STEPS,
+	MAX_FRAME_SECONDS = MAX_FRAME_SECONDS,
+	Scheduler = Scheduler,
+}

package/out/internal/state.d.ts

@@ -0,0 +1 @@
+export {};

package/out/internal/state.luau

@@ -0,0 +1,41 @@
+-- Compiled with roblox-ts v3.0.0
+--* @internal Public API rule 1: a Subsystem has `awake` and `start` but no `onEnable`, `onDisable` or `onDestroy`. 
+--* @internal What lifecycle reads from a class record. The registry's records extend it. 
+--* @internal An object the `construct` effect built. Lifecycle never reads it. 
+--[[
+	*
+	 * @internal
+	 * Where one generation of an object is. A phase also records which inverse hooks are owed: from Awake on,
+	 * one `onDestroy`; in Enabled, one `onDisable`. Each step enters its phase before running its hook, so a
+	 * hook that throws part way still owes its inverse. Faulted and Destroyed are terminal.
+	 *
+	 *   Unconstructed --constructor--> Constructed --awake--> Awake --onEnable--> Enabled <--onDisable / onEnable--> Disabled
+	 *         |                             |                   |  \--(want Disabled, no hook)---------------------------^
+	 *         +--------Drop, no hooks-------+                   +--------onDestroy (from Awake or Disabled)--> Destroyed | Faulted
+	 
+]]
+--* @internal `start` runs once per generation, the first time the object is Enabled with the gate at Start. 
+--[[
+	*
+	 * @internal How far the object's batch has opened. A batch raises the gate on all its objects together, so
+	 * every object is awake before any is enabled and enabled before any starts. After its batch an object sits at Start.
+	 
+]]
+--* @internal What the outside world asked for. The latest request wins; Destroyed is absorbing. 
+--* @internal Where a failure happened. The first one is the object's primary diagnostic. 
+--* @internal One atomic move. Each runs at most one hook or changes one index. 
+--* @internal Discriminates the two kinds of entry on the work stack. 
+--* @internal The first failure, with every later failure during its cleanup attached. 
+--* @internal The inputs `nextStep` reads. Lifecycle owns every field; nothing else writes them. 
+--* @internal Runtime state of one generation. 
+--* @internal 
+--* @internal New generations going through construct, awake, enable and start together. 
+--[[
+	*
+	 * @internal
+	 * Everything a step does outside lifecycle state. Boot installs the real ones; specs install doubles.
+	 * Lifecycle runs `construct` and every hook caller through `runner.call` with the object as owner, so a throw
+	 * or a yield comes back as a failure, and `start` on its own thread.
+	 
+]]
+return nil

package/out/log-level.d.ts

@@ -0,0 +1,7 @@
+export declare enum LogLevel {
+    Debug = 0,
+    Info = 1,
+    Warning = 2,
+    Error = 3,
+    Off = 4
+}

package/out/log-level.luau

@@ -0,0 +1,21 @@
+-- Compiled with roblox-ts v3.0.0
+local LogLevel
+do
+	local _inverse = {}
+	LogLevel = setmetatable({}, {
+		__index = _inverse,
+	})
+	LogLevel.Debug = 0
+	_inverse[0] = "Debug"
+	LogLevel.Info = 1
+	_inverse[1] = "Info"
+	LogLevel.Warning = 2
+	_inverse[2] = "Warning"
+	LogLevel.Error = 3
+	_inverse[3] = "Error"
+	LogLevel.Off = 4
+	_inverse[4] = "Off"
+end
+return {
+	LogLevel = LogLevel,
+}

package/out/logging.d.ts

@@ -0,0 +1,34 @@
+import { LogLevel } from "./log-level";
+export { LogLevel } from "./log-level";
+export type LogContext = Readonly<Record<string, unknown>>;
+export type LogProperties = Readonly<Record<string, string | number | boolean>>;
+export interface LogRecord {
+    readonly sequence: number;
+    readonly time: number;
+    readonly source: string;
+    readonly level: Exclude<LogLevel, LogLevel.Off>;
+    readonly template: string;
+    readonly context: LogProperties;
+    readonly message: string;
+    readonly traceback?: string;
+}
+export interface LogSink {
+    readonly write: (record: LogRecord) => void;
+}
+export interface SinkSubscription {
+    setMinimum(level: LogLevel): void;
+    disconnect(): void;
+}
+export interface Logger {
+    isEnabled(level: Exclude<LogLevel, LogLevel.Off>): boolean;
+    debug(template: string, context?: LogContext): void;
+    info(template: string, context?: LogContext): void;
+    warn(template: string, context?: LogContext): void;
+    error(template: string, context?: LogContext): void;
+}
+export declare class Logging {
+    private constructor();
+    static readonly defaultSink: SinkSubscription;
+    static getLogger(source: string): Logger;
+    static addSink(sink: LogSink, minimum?: LogLevel): SinkSubscription;
+}

package/out/logging.luau

@@ -0,0 +1,233 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local LogLevel = TS.import(script, script.Parent, "log-level").LogLevel
+local runtimeDiagnostic = TS.import(script, script.Parent, "internal", "diagnostics").runtimeDiagnostic
+local loggingPort = TS.import(script, script.Parent, "internal", "log-output").loggingPort
+local call = TS.import(script, script.Parent, "internal", "runner").call
+exports.LogLevel = TS.import(script, script.Parent, "log-level").LogLevel
+local registrations = {}
+local snapshot = {}
+local minimum = LogLevel.Off
+local sequence = 0
+local emitting = false
+local function derive(added)
+	local entries = {}
+	minimum = LogLevel.Off
+	-- roblox-ts Maps compile to unordered Luau tables. The array owns delivery order.
+	for _, registration in snapshot do
+		if not registration.connected then
+			continue
+		end
+		table.insert(entries, registration)
+		minimum = math.min(minimum, registration.minimum)
+	end
+	if added ~= nil then
+		local _added = added
+		table.insert(entries, _added)
+		minimum = math.min(minimum, added.minimum)
+	end
+	snapshot = table.freeze(entries)
+end
+local function validateMinimum(level)
+	local _arg0 = level >= LogLevel.Debug and level <= LogLevel.Off and level % 1 == 0
+	assert(_arg0, "Invalid log minimum")
+end
+local function register(sink, level)
+	validateMinimum(level)
+	local _sink = sink
+	local existing = registrations[_sink]
+	if existing ~= nil then
+		return existing.subscription
+	end
+	local _write = sink.write
+	local _arg0 = type(_write) == "function"
+	assert(_arg0, "Log sink requires write")
+	local registration
+	registration = {
+		sink = sink,
+		minimum = level,
+		connected = true,
+		subscription = {
+			setMinimum = function(self, value)
+				validateMinimum(value)
+				if not registration.connected then
+					return nil
+				end
+				registration.minimum = value
+				derive()
+			end,
+			disconnect = function(self)
+				if not registration.connected then
+					return nil
+				end
+				registration.connected = false
+				local _sink_1 = sink
+				registrations[_sink_1] = nil
+				derive()
+			end,
+		},
+	}
+	local _sink_1 = sink
+	registrations[_sink_1] = registration
+	derive(registration)
+	return registration.subscription
+end
+local function normalize(input)
+	local context = {}
+	if input ~= nil then
+		for key, value in pairs(input) do
+			context[key] = if typeof(value) == "Instance" then loggingPort().describeInstance(value) elseif type(value) == "string" or type(value) == "number" or type(value) == "boolean" then value else tostring(value)
+		end
+	end
+	return table.freeze(context)
+end
+local function render(template, context)
+	local parts = {}
+	local index = 1
+	while index <= #template do
+		local _template = template
+		local _index = index
+		local _index_1 = index
+		local char = string.sub(_template, _index, _index_1)
+		local _template_1 = template
+		local _index_2 = index
+		local _arg1 = index + 1
+		local pair = string.sub(_template_1, _index_2, _arg1)
+		if pair == "{{" or pair == "}}" then
+			table.insert(parts, char)
+			index += 2
+		elseif char == "{" then
+			local _template_2 = template
+			local _arg1_1 = index + 1
+			local close = string.find(_template_2, "}", _arg1_1, true)
+			if close ~= nil then
+				local _template_3 = template
+				local _arg0 = index + 1
+				local _arg1_2 = close - 1
+				local key = string.sub(_template_3, _arg0, _arg1_2)
+				local value = context[key]
+				local _result
+				if value == nil then
+					local _template_4 = template
+					local _index_3 = index
+					_result = string.sub(_template_4, _index_3, close)
+				else
+					_result = tostring(value)
+				end
+				table.insert(parts, _result)
+				index = close + 1
+			else
+				table.insert(parts, char)
+				index += 1
+			end
+		else
+			table.insert(parts, char)
+			index += 1
+		end
+	end
+	return table.concat(parts, "")
+end
+local function emit(source, level, template, input)
+	if emitting or level < minimum then
+		return nil
+	end
+	emitting = true
+	local trace = if level == LogLevel.Error then debug.traceback("", 3) else nil
+	local result, failure = call(function()
+		-- ▼ ReadonlyArray.filter ▼
+		local _newValue = {}
+		local _callback = function(r)
+			return level >= r.minimum
+		end
+		local _length = 0
+		for _k, _v in snapshot do
+			if _callback(_v, _k - 1, snapshot) == true then
+				_length += 1
+				_newValue[_length] = _v
+			end
+		end
+		-- ▲ ReadonlyArray.filter ▲
+		local accepted = _newValue
+		local context = normalize(input)
+		local _object = {}
+		local _left = "sequence"
+		sequence += 1
+		_object[_left] = sequence
+		_object.time = loggingPort().now()
+		_object.source = source
+		_object.level = level
+		_object.template = template
+		_object.context = context
+		_object.message = render(template, context)
+		_object.traceback = trace
+		local record = table.freeze(_object)
+		for _, registration in accepted do
+			if not registration.connected then
+				continue
+			end
+			local status, err = call(registration.sink.write, record, nil)
+			if status ~= 0 then
+				registration.subscription:disconnect()
+				runtimeDiagnostic("error", `Log sink failed: {tostring(err)}`)
+			end
+		end
+	end, nil, nil)
+	if result ~= 0 then
+		runtimeDiagnostic("error", `Logging failed: {tostring(failure)}`)
+	end
+	emitting = false
+end
+local Logging
+do
+	Logging = setmetatable({}, {
+		__tostring = function()
+			return "Logging"
+		end,
+	})
+	Logging.__index = Logging
+	function Logging.new(...)
+		local self = setmetatable({}, Logging)
+		return self:constructor(...) or self
+	end
+	function Logging:constructor()
+	end
+	function Logging:getLogger(source)
+		local _arg0 = #source > 0 and #source <= 256 and (string.find(source, "%c")) == nil
+		assert(_arg0, "Invalid logger name")
+		for _, segment in string.split(source, ".") do
+			local _arg0_1 = #segment > 0
+			assert(_arg0_1, "Invalid logger name segment")
+		end
+		return {
+			isEnabled = function(self, level)
+				return level >= minimum
+			end,
+			debug = function(self, template, context)
+				emit(source, LogLevel.Debug, template, context)
+			end,
+			info = function(self, template, context)
+				emit(source, LogLevel.Info, template, context)
+			end,
+			warn = function(self, template, context)
+				emit(source, LogLevel.Warning, template, context)
+			end,
+			error = function(self, template, context)
+				emit(source, LogLevel.Error, template, context)
+			end,
+		}
+	end
+	function Logging:addSink(sink, minimum)
+		if minimum == nil then
+			minimum = LogLevel.Info
+		end
+		return register(sink, minimum)
+	end
+	Logging.defaultSink = register({
+		write = function(record)
+			return loggingPort().writeGame(record)
+		end,
+	}, if loggingPort().isStudio() then LogLevel.Debug else LogLevel.Info)
+end
+exports.Logging = Logging
+return exports

package/out/server/index.d.ts

@@ -0,0 +1,2 @@
+import type { BootOptions } from "../index";
+export declare function boot(options: BootOptions): void;

package/out/server/init.luau

@@ -0,0 +1,16 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local bootSide = TS.import(script, script.Parent, "internal", "boot").boot
+if not game:GetService("RunService"):IsServer() then
+	error("@trioforge/crucible/server loaded on the client")
+end
+local function boot(options)
+	bootSide({
+		name = "server",
+		renders = false,
+		booted = function() end,
+	}, options)
+end
+return {
+	boot = boot,
+}

package/out/subsystem.d.ts

@@ -0,0 +1,4 @@
+import { CrucibleObject } from "./crucible-object";
+export declare abstract class Subsystem extends CrucibleObject {
+    protected onShutdown(): void;
+}

package/out/subsystem.luau

@@ -0,0 +1,30 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local CrucibleObject = TS.import(script, script.Parent, "crucible-object").CrucibleObject
+local installSubsystemHooks = TS.import(script, script.Parent, "internal", "hooks").installSubsystemHooks
+local Subsystem
+do
+	local super = CrucibleObject
+	Subsystem = setmetatable({}, {
+		__tostring = function()
+			return "Subsystem"
+		end,
+		__index = super,
+	})
+	Subsystem.__index = Subsystem
+	function Subsystem:constructor(...)
+		super.constructor(self, ...)
+	end
+	function Subsystem:onShutdown()
+	end
+	do
+		installSubsystemHooks({
+			onShutdown = function(o)
+				return o:onShutdown()
+			end,
+		})
+	end
+end
+return {
+	Subsystem = Subsystem,
+}