cluaupp 1.5.0 → 1.5.1

package/examples/game/libs/Shift/init.luau

@@ -0,0 +1,238 @@
+--!native
+--!optimize 2
+--!strict
+-- Shift — compiled FSM/HSM. State ids are u8. No per-frame OnDataChanged.
+
+local Shift = {}
+Shift.__index = Shift
+
+export type ShiftMachine = typeof(setmetatable(
+	{} :: {
+		State: number,
+		Previous: number,
+		History: { number },
+		Ids: { [string]: number },
+		Names: { [number]: string },
+		Parents: { [string]: string },
+		Transitions: { { From: string, To: string, Guard: string } },
+		Data: { [string]: any },
+		Alive: boolean,
+		_guards: { [string]: () -> boolean },
+		_enters: { [string]: () -> () },
+		_leaves: { [string]: () -> () },
+	},
+	Shift
+))
+
+local function ancestorChain(self: ShiftMachine, name: string?): { string }
+	local chain = {}
+	local current = name
+	local seen: { [string]: boolean } = {}
+	while current and not seen[current] do
+		seen[current] = true
+		table.insert(chain, 1, current)
+		current = self.Parents[current]
+	end
+	return chain
+end
+
+local function inBranch(self: ShiftMachine, name: string): boolean
+	local current = self.Names[self.State]
+	local seen: { [string]: boolean } = {}
+	while current and not seen[current] do
+		if current == name then
+			return true
+		end
+		seen[current] = true
+		current = self.Parents[current]
+	end
+	return false
+end
+
+local function edgeAllowed(self: ShiftMachine, fromName: string?, toName: string): boolean?
+	if fromName == nil then
+		return nil
+	end
+	for _, edge in self.Transitions do
+		if edge.From == fromName and edge.To == toName then
+			if edge.Guard == "" or edge.Guard == nil then
+				return true
+			end
+			local guard = self._guards[edge.Guard]
+			if not guard then
+				return true
+			end
+			return guard()
+		end
+	end
+	return nil
+end
+
+function Shift.New(ids: { [string]: number }, transitions: { any }, parents: { [string]: string }?): ShiftMachine
+	local names = {}
+	local initial = 0
+	for name, id in ids do
+		names[id] = name
+		if id == 0 then
+			initial = 0
+		end
+	end
+	return setmetatable({
+		State = initial,
+		Previous = initial,
+		History = { initial },
+		Ids = ids,
+		Names = names,
+		Parents = parents or {},
+		Transitions = transitions,
+		Data = {},
+		Alive = true,
+		_guards = {} :: { [string]: () -> boolean },
+		_enters = {} :: { [string]: () -> () },
+		_leaves = {} :: { [string]: () -> () },
+	}, Shift)
+end
+
+function Shift:Guard(name: string, fn: () -> boolean)
+	self._guards[name] = fn
+end
+
+function Shift:OnEnter(name: string, fn: () -> ())
+	self._enters[name] = fn
+	if self.Alive and self.Names[self.State] == name then
+		fn()
+	end
+end
+
+function Shift:OnLeave(name: string, fn: () -> ())
+	self._leaves[name] = fn
+end
+
+function Shift:CanEnter(toName: string, visiting: { [string]: boolean }?): boolean
+	if not self.Alive then
+		return false
+	end
+	if self.Ids[toName] == nil then
+		return false
+	end
+	local fromName = self.Names[self.State]
+	if fromName == toName then
+		return false
+	end
+	local explicit = edgeAllowed(self, fromName, toName)
+	if explicit ~= nil then
+		return explicit
+	end
+	local parent = self.Parents[toName]
+	if parent == nil then
+		return false
+	end
+	if inBranch(self, parent) then
+		return true
+	end
+	local seen = visiting or {}
+	if seen[toName] then
+		return false
+	end
+	seen[toName] = true
+	return self:CanEnter(parent, seen)
+end
+
+local function switchTo(self: ShiftMachine, name: string, id: number)
+	local fromName = self.Names[self.State]
+	local leaveChain = ancestorChain(self, fromName)
+	local enterChain = ancestorChain(self, name)
+	local common = 0
+	local limit = math.min(#leaveChain, #enterChain)
+	for index = 1, limit do
+		if leaveChain[index] == enterChain[index] then
+			common = index
+		else
+			break
+		end
+	end
+	for index = #leaveChain, common + 1, -1 do
+		local fn = self._leaves[leaveChain[index]]
+		if fn then
+			fn()
+		end
+	end
+	self.Previous = self.State
+	self.State = id
+	table.insert(self.History, id)
+	for index = common + 1, #enterChain do
+		local fn = self._enters[enterChain[index]]
+		if fn then
+			fn()
+		end
+	end
+end
+
+function Shift:ChangeState(name: string)
+	if not self.Alive then
+		return
+	end
+	local id = self.Ids[name]
+	if id == nil then
+		return
+	end
+	if self.State == id then
+		return
+	end
+	if not self:CanEnter(name) then
+		return
+	end
+	switchTo(self, name, id)
+end
+
+function Shift:GetState(): string
+	return self.Names[self.State] or ""
+end
+
+function Shift:GetCurrentState(): string
+	return self:GetState()
+end
+
+function Shift:GetPreviousState(): string
+	return self.Names[self.Previous] or ""
+end
+
+function Shift:GetId(): number
+	return self.State
+end
+
+function Shift:WriteId(): buffer
+	local buf = buffer.create(1)
+	buffer.writeu8(buf, 0, self.State)
+	return buf
+end
+
+function Shift:ReadId(buf: buffer)
+	if not self.Alive then
+		return
+	end
+	local id = buffer.readu8(buf, 0)
+	local name = self.Names[id]
+	if name == nil or self.State == id then
+		return
+	end
+	switchTo(self, name, id)
+end
+
+function Shift:GetData()
+	return self.Data
+end
+
+function Shift:ChangeData(index: string, value: any)
+	self.Data[index] = value
+end
+
+function Shift:Destroy()
+	self.Alive = false
+	table.clear(self.Data)
+	table.clear(self._guards)
+	table.clear(self._enters)
+	table.clear(self._leaves)
+end
+
+return Shift

package/examples/game/libs/Spark/init.luau

@@ -0,0 +1,487 @@
+--!native
+--!optimize 2
+--!strict
+-- Spark — engine-grade yield-safe signal.
+-- Intrusive doubly-linked list (O(1) Disconnect, Fire-safe unhook).
+-- Pooled runner threads (GoodSignal). Reentrant Fire is queued, not stacked.
+-- Destroy seals the signal. ConnectParallel never reuses the serial runner.
+
+export type SparkConnection = {
+	Connected: boolean,
+	Disconnect: (self: SparkConnection) -> (),
+	Destroy: (self: SparkConnection) -> (),
+}
+
+export type Connection = SparkConnection
+
+export type Spark<T...> = {
+	Fire: (self: Spark<T...>, T...) -> (),
+	FireDeferred: (self: Spark<T...>, T...) -> (),
+	Connect: (self: Spark<T...>, fn: (T...) -> ()) -> SparkConnection,
+	ConnectParallel: (self: Spark<T...>, fn: (T...) -> ()) -> SparkConnection,
+	Once: (self: Spark<T...>, fn: (T...) -> ()) -> SparkConnection,
+	OnceParallel: (self: Spark<T...>, fn: (T...) -> ()) -> SparkConnection,
+	ConnectOnce: (self: Spark<T...>, fn: (T...) -> ()) -> SparkConnection,
+	DisconnectAll: (self: Spark<T...>) -> (),
+	GetConnections: (self: Spark<T...>) -> { SparkConnection },
+	Destroy: (self: Spark<T...>) -> (),
+	IsDestroyed: (self: Spark<T...>) -> boolean,
+	Wait: (self: Spark<T...>) -> T...,
+}
+
+type Handler = (...any) -> ()
+type Packed = { n: number, [number]: any }
+
+type ConnectionNode = {
+	Connected: boolean,
+	_signal: SparkImpl?,
+	_fn: Handler?,
+	_next: ConnectionNode?,
+	_prev: ConnectionNode?,
+	_once: boolean,
+	_parallel: boolean,
+	Disconnect: (self: ConnectionNode) -> (),
+	Destroy: (self: ConnectionNode) -> (),
+}
+
+type SparkImpl = {
+	_head: ConnectionNode?,
+	_tail: ConnectionNode?,
+	_count: number,
+	_destroyed: boolean,
+	_firing: boolean,
+	_queue: { Packed },
+	_queueN: number,
+	_proxyHandler: RBXScriptConnection?,
+	_yieldedThreads: { [thread]: boolean }?,
+	Fire: (self: SparkImpl, ...any) -> (),
+	FireDeferred: (self: SparkImpl, ...any) -> (),
+	Connect: (self: SparkImpl, fn: Handler) -> ConnectionNode,
+	ConnectParallel: (self: SparkImpl, fn: Handler) -> ConnectionNode,
+	Once: (self: SparkImpl, fn: Handler) -> ConnectionNode,
+	OnceParallel: (self: SparkImpl, fn: Handler) -> ConnectionNode,
+	ConnectOnce: (self: SparkImpl, fn: Handler) -> ConnectionNode,
+	DisconnectAll: (self: SparkImpl) -> (),
+	GetConnections: (self: SparkImpl) -> { SparkConnection },
+	Destroy: (self: SparkImpl) -> (),
+	IsDestroyed: (self: SparkImpl) -> boolean,
+	Wait: (self: SparkImpl) -> ...any,
+}
+
+local MAX_CONNECTIONS = 4096
+local MAX_REENTRY = 64
+local PACK_POOL_CAP = 16
+local SNAP_POOL_CAP = 8
+
+local freeRunnerThread: thread? = nil
+local packPool: { Packed } = {}
+local packPoolN = 0
+local snapPool: { { ConnectionNode } } = {}
+local snapPoolN = 0
+
+local function acquirePack(...: any): Packed
+	local packed: Packed
+	if packPoolN > 0 then
+		packed = packPool[packPoolN]
+		packPool[packPoolN] = nil
+		packPoolN -= 1
+	else
+		packed = table.pack(...)
+		return packed
+	end
+	local n = select("#", ...)
+	packed.n = n
+	for i = 1, n do
+		packed[i] = select(i, ...)
+	end
+	return packed
+end
+
+local function releasePack(packed: Packed)
+	for i = 1, packed.n do
+		packed[i] = nil
+	end
+	packed.n = 0
+	if packPoolN < PACK_POOL_CAP then
+		packPoolN += 1
+		packPool[packPoolN] = packed
+	end
+end
+
+local function acquireSnap(): { ConnectionNode }
+	if snapPoolN > 0 then
+		local snap = snapPool[snapPoolN]
+		snapPool[snapPoolN] = nil
+		snapPoolN -= 1
+		return snap
+	end
+	return {}
+end
+
+local function releaseSnap(snap: { ConnectionNode }, n: number)
+	for i = 1, n do
+		snap[i] = nil
+	end
+	if snapPoolN < SNAP_POOL_CAP then
+		snapPoolN += 1
+		snapPool[snapPoolN] = snap
+	end
+end
+
+local function acquireRunnerThreadAndCallEventHandler(fn: Handler, ...: any)
+	local acquired = freeRunnerThread
+	freeRunnerThread = nil
+	fn(...)
+	freeRunnerThread = acquired
+end
+
+local function runEventHandlerInFreeThread(...: any)
+	acquireRunnerThreadAndCallEventHandler(...)
+	while true do
+		acquireRunnerThreadAndCallEventHandler(coroutine.yield())
+	end
+end
+
+local function runParallelHandler(fn: Handler, ...: any)
+	local desynced = pcall(task.desynchronize)
+	fn(...)
+	if desynced then
+		pcall(task.synchronize)
+	end
+end
+
+local function expectFunction(method: string, fn: Handler)
+	if type(fn) ~= "function" then
+		error(`Spark.{method} expected function, got {typeof(fn)}`, 4)
+	end
+end
+
+local Connection = {}
+Connection.__index = Connection
+
+local function unlink(node: ConnectionNode)
+	local signal = node._signal
+	if not signal then
+		return
+	end
+	local prev = node._prev
+	local next = node._next
+	if prev then
+		prev._next = next
+	elseif signal._head == node then
+		signal._head = next
+	end
+	if next then
+		next._prev = prev
+	elseif signal._tail == node then
+		signal._tail = prev
+	end
+	node._prev = nil
+	-- Keep _next so an in-flight Fire iterator can continue.
+	if node.Connected then
+		signal._count -= 1
+		if signal._count < 0 then
+			signal._count = 0
+		end
+	end
+end
+
+local function clearNode(node: ConnectionNode)
+	node._fn = nil
+	node._signal = nil
+	node._once = false
+	node._parallel = false
+end
+
+function Connection.Disconnect(self: ConnectionNode)
+	if not self.Connected then
+		return
+	end
+	unlink(self)
+	self.Connected = false
+	clearNode(self)
+end
+
+Connection.Destroy = Connection.Disconnect
+
+local function deadConnection(): ConnectionNode
+	return setmetatable({
+		Connected = false,
+		_signal = nil,
+		_fn = nil,
+		_next = nil,
+		_prev = nil,
+		_once = false,
+		_parallel = false,
+	}, Connection) :: any
+end
+
+local Spark = {}
+Spark.__index = Spark
+
+local function invoke(conn: ConnectionNode, ...: any)
+	local fn = conn._fn
+	if not fn then
+		return
+	end
+	local parallel = conn._parallel
+	if conn._once then
+		conn:Disconnect()
+	end
+	if parallel then
+		task.spawn(runParallelHandler, fn, ...)
+		return
+	end
+	if not freeRunnerThread then
+		freeRunnerThread = coroutine.create(runEventHandlerInFreeThread)
+	end
+	task.spawn(freeRunnerThread :: thread, fn, ...)
+end
+
+local function dispatchList(self: SparkImpl, ...: any)
+	local item = self._head
+	while item do
+		if item.Connected then
+			invoke(item, ...)
+		end
+		item = item._next
+	end
+end
+
+local function bind(self: SparkImpl, fn: Handler, once: boolean, parallel: boolean): ConnectionNode
+	if self._destroyed then
+		return deadConnection()
+	end
+	expectFunction(if parallel then "ConnectParallel" else "Connect", fn)
+	if self._count >= MAX_CONNECTIONS then
+		warn(`Spark: connection cap ({MAX_CONNECTIONS}) reached; refusing Connect`)
+		return deadConnection()
+	end
+
+	local node = setmetatable({
+		Connected = true,
+		_signal = self,
+		_fn = fn,
+		_next = self._head,
+		_prev = nil,
+		_once = once,
+		_parallel = parallel,
+	}, Connection) :: ConnectionNode
+
+	if self._head then
+		self._head._prev = node
+	else
+		self._tail = node
+	end
+	self._head = node
+	self._count += 1
+	return node
+end
+
+function Spark.new<T...>(): Spark<T...>
+	return setmetatable({
+		_head = nil,
+		_tail = nil,
+		_count = 0,
+		_destroyed = false,
+		_firing = false,
+		_queue = {},
+		_queueN = 0,
+		_proxyHandler = nil,
+		_yieldedThreads = nil,
+	}, Spark) :: any
+end
+
+Spark.New = Spark.new
+
+function Spark.Wrap<T...>(rbxScriptSignal: RBXScriptSignal): Spark<T...>
+	if typeof(rbxScriptSignal) ~= "RBXScriptSignal" then
+		error("Spark.Wrap expected RBXScriptSignal, got " .. typeof(rbxScriptSignal), 2)
+	end
+	local spark = Spark.new() :: SparkImpl
+	spark._proxyHandler = rbxScriptSignal:Connect(function(...: any)
+		if not spark._destroyed then
+			spark:Fire(...)
+		end
+	end)
+	return spark :: any
+end
+
+function Spark.Is(obj: any): boolean
+	return type(obj) == "table" and getmetatable(obj) == Spark
+end
+
+function Spark.Connect(self: SparkImpl, fn: Handler): ConnectionNode
+	return bind(self, fn, false, false)
+end
+
+function Spark.ConnectParallel(self: SparkImpl, fn: Handler): ConnectionNode
+	return bind(self, fn, false, true)
+end
+
+function Spark.Once(self: SparkImpl, fn: Handler): ConnectionNode
+	return bind(self, fn, true, false)
+end
+
+function Spark.OnceParallel(self: SparkImpl, fn: Handler): ConnectionNode
+	return bind(self, fn, true, true)
+end
+
+function Spark.ConnectOnce(self: SparkImpl, fn: Handler): ConnectionNode
+	return bind(self, fn, true, false)
+end
+
+function Spark.GetConnections(self: SparkImpl): { SparkConnection }
+	local items = table.create(self._count)
+	local i = 0
+	local item = self._head
+	while item do
+		if item.Connected then
+			i += 1
+			items[i] = item
+		end
+		item = item._next
+	end
+	return items
+end
+
+function Spark.IsDestroyed(self: SparkImpl): boolean
+	return self._destroyed
+end
+
+function Spark.DisconnectAll(self: SparkImpl)
+	if not self then
+		return
+	end
+	local item = self._head
+	self._head = nil
+	self._tail = nil
+	self._count = 0
+	while item do
+		local next = item._next
+		item.Connected = false
+		clearNode(item)
+		item = next
+	end
+
+	local yielded = self._yieldedThreads
+	if not yielded then
+		return
+	end
+	for thread in yielded do
+		if coroutine.status(thread) == "suspended" then
+			warn(debug.traceback(thread, "spark disconnected; yielded thread cancelled", 2))
+			task.cancel(thread)
+		end
+	end
+	table.clear(yielded)
+end
+
+function Spark.Fire(self: SparkImpl, ...: any)
+	if self._destroyed or self._count == 0 then
+		return
+	end
+	if self._firing then
+		if self._queueN >= MAX_REENTRY then
+			warn("Spark: reentrant Fire dropped (queue full)")
+			return
+		end
+		self._queueN += 1
+		self._queue[self._queueN] = acquirePack(...)
+		return
+	end
+
+	self._firing = true
+	dispatchList(self, ...)
+	local i = 1
+	while i <= self._queueN do
+		local packed = self._queue[i]
+		self._queue[i] = nil
+		dispatchList(self, table.unpack(packed, 1, packed.n))
+		releasePack(packed)
+		i += 1
+	end
+	self._queueN = 0
+	self._firing = false
+end
+
+local function deferredFlush(snap: { ConnectionNode }, n: number, packed: Packed)
+	for i = 1, n do
+		local conn = snap[i]
+		if conn and conn.Connected then
+			invoke(conn, table.unpack(packed, 1, packed.n))
+		end
+	end
+	releaseSnap(snap, n)
+	releasePack(packed)
+end
+
+function Spark.FireDeferred(self: SparkImpl, ...: any)
+	if self._destroyed or self._count == 0 then
+		return
+	end
+	local snap = acquireSnap()
+	local n = 0
+	local item = self._head
+	while item do
+		if item.Connected then
+			n += 1
+			snap[n] = item
+		end
+		item = item._next
+	end
+	if n == 0 then
+		releaseSnap(snap, 0)
+		return
+	end
+	task.defer(deferredFlush, snap, n, acquirePack(...))
+end
+
+function Spark.Wait(self: SparkImpl): ...any
+	if self._destroyed then
+		error("Spark.Wait on destroyed signal", 2)
+	end
+
+	local yielded = self._yieldedThreads
+	if not yielded then
+		yielded = {}
+		self._yieldedThreads = yielded
+	end
+
+	local thread = coroutine.running()
+	yielded[thread] = true
+	local pending: Packed? = nil
+
+	self:Once(function(...: any)
+		yielded[thread] = nil
+		if coroutine.status(thread) == "suspended" then
+			task.spawn(thread, ...)
+		else
+			pending = table.pack(...)
+		end
+	end)
+
+	if pending then
+		return table.unpack(pending, 1, pending.n)
+	end
+	return coroutine.yield()
+end
+
+function Spark.Destroy(self: SparkImpl)
+	if self._destroyed then
+		return
+	end
+	self._destroyed = true
+	self:DisconnectAll()
+	local proxy = self._proxyHandler
+	if proxy then
+		proxy:Disconnect()
+		self._proxyHandler = nil
+	end
+	table.clear(self._queue)
+	self._queueN = 0
+end
+
+Spark.Connection = Connection
+
+return Spark