cluaupp 0.2.3 → 1.3.0

package/templates/game/libs/Fusion/Types.luau

@@ -0,0 +1,318 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Stores common public-facing type information for Fusion APIs.
+]]
+
+export type Error = {
+	type: "Error",
+	raw: string,
+	message: string,
+	trace: string,
+	context: string?
+}
+
+-- Types that can be expressed as vectors of numbers, and so can be animated.
+export type Animatable =
+	number |
+	CFrame |
+	Color3 |
+	ColorSequenceKeypoint |
+	DateTime |
+	NumberRange |
+	NumberSequenceKeypoint |
+	PhysicalProperties |
+	Ray |
+	Rect |
+	Region3 |
+	Region3int16 |
+	UDim |
+	UDim2 |
+	Vector2 |
+	Vector2int16 |
+	Vector3 |
+	Vector3int16
+
+-- A task which can be accepted for cleanup.
+export type Task =
+	Instance |
+	RBXScriptConnection |
+	() -> () |
+	{destroy: (unknown) -> ()} |
+	{Destroy: (unknown) -> ()} |
+	{disconnect: (unknown) -> ()} |
+	{Disconnect: (unknown) -> ()} |
+	{Task}
+
+-- A scope of tasks to clean up.
+export type Scope<Constructors = any> = {Task} & Constructors
+
+-- An object which uses a scope to dictate how long it lives.
+export type ScopedObject = {
+	scope: Scope<unknown>?,
+	oldestTask: unknown
+}
+
+-- Script-readable version information.
+export type Version = {
+	major: number,
+	minor: number,
+	isRelease: boolean
+}
+
+-- An object which stores a value scoped in time.
+export type Contextual<T> = {
+	type: "Contextual",
+	now: (Contextual<T>) -> T,
+	is: (Contextual<T>, T) -> ContextualIsMethods
+}
+
+type ContextualIsMethods = {
+	during: <R, A...>(ContextualIsMethods, (A...) -> R, A...) -> R
+}
+
+-- A graph object which can have dependencies and dependencies.
+export type GraphObject = ScopedObject & {
+	createdAt: number,
+	dependencySet: {[GraphObject]: unknown},
+	dependentSet: {[GraphObject]: unknown},
+	lastChange: number?,
+	timeliness: "lazy" | "eager",
+	validity: "valid" | "invalid" | "busy",
+	_evaluate: (GraphObject) -> boolean
+}
+
+-- An object which stores a piece of reactive state.
+export type StateObject<T> = GraphObject & {
+	type: "State",
+	kind: string,
+	_EXTREMELY_DANGEROUS_usedAsValue: T
+}
+
+-- Passing values of this type to `Use` returns `T`.
+export type UsedAs<T> = StateObject<T> | T
+
+-- Function signature for use callbacks.
+export type Use = <T>(target: UsedAs<T>) -> T
+
+-- A state object whose value can be set at any time by the user.
+export type Value<T, S = T> = StateObject<T> & {
+	kind: "State",
+	timeliness: "lazy",
+ 	set: (Value<T, S>, newValue: S, force: boolean?) -> S,
+	____phantom_setType: (never) -> S -- phantom data so this contains S
+}
+export type ValueConstructor = <T>(
+	scope: Scope<unknown>,
+	initialValue: T
+) -> Value<T, any>
+
+-- A state object whose value is derived from other objects using a callback.
+export type Computed<T> = StateObject<T> & {
+	kind: "Computed",
+	timeliness: "lazy"
+}
+export type ComputedConstructor = <T, S>(
+	scope: S & Scope<unknown>,
+	callback: (Use, S) -> T
+) -> Computed<T>
+
+-- A state object which maps over keys and/or values in another table.
+export type For<KO, VO> = StateObject<{[KO]: VO}>  & {
+	kind: "For"
+}
+export type ForPairsConstructor =  <KI, KO, VI, VO, S>(
+	scope: S & Scope<unknown>,
+	inputTable: UsedAs<{[KI]: VI}>,
+	processor: (Use, S, key: KI, value: VI) -> (KO, VO)
+) -> For<KO, VO>
+export type ForKeysConstructor =  <KI, KO, V, S>(
+	scope: S & Scope<unknown>,
+	inputTable: UsedAs<{[KI]: V}>,
+	processor: (Use, S, key: KI) -> KO
+) -> For<KO, V>
+export type ForValuesConstructor =  <K, VI, VO, S>(
+	scope: S & Scope<unknown>,
+	inputTable: UsedAs<{[K]: VI}>,
+	processor: (Use, S, value: VI) -> VO
+) -> For<K, VO>
+
+-- An object which can listen for updates on another state object.
+export type Observer = GraphObject & {
+	type: "Observer",
+	timeliness: "eager",
+	onChange: (Observer, callback: () -> ()) -> (() -> ()),
+	onBind: (Observer, callback: () -> ()) -> (() -> ())
+}
+export type ObserverConstructor = (
+	scope: Scope<unknown>,
+	watching: unknown
+) -> Observer
+
+-- A state object which follows another state object using tweens.
+export type Tween<T> = StateObject<T> & {
+	kind: "Tween"
+}
+export type TweenConstructor = <T>(
+	scope: Scope<unknown>,
+	goalState: UsedAs<T>,
+	tweenInfo: UsedAs<TweenInfo>?
+) -> Tween<T>
+
+-- A state object which follows another state object using spring simulation.
+export type Spring<T> = StateObject<T>  & {
+	kind: "Spring",
+	setPosition: (Spring<T>, newPosition: T) -> (),
+	setVelocity: (Spring<T>, newVelocity: T) -> (),
+	addVelocity: (Spring<T>, deltaVelocity: T) -> ()
+}
+export type SpringConstructor = <T>(
+	scope: Scope<unknown>,
+	goalState: UsedAs<T>,
+	speed: UsedAs<number>?,
+	damping: UsedAs<number>?
+) -> Spring<T>
+
+-- Denotes children instances in an instance or component's property table.
+export type SpecialKey = {
+	type: "SpecialKey",
+	kind: string,
+	stage: "self" | "descendants" | "ancestor" | "observer",
+	apply: (
+		self: SpecialKey,
+		scope: Scope<unknown>,
+		value: unknown,
+		applyTo: Instance
+	) -> ()
+}
+
+-- A collection of instances that may be parented to another instance.
+export type Child = Instance | StateObject<Child> | {[unknown]: Child}
+
+-- A table that defines an instance's properties, handlers and children.
+export type PropertyTable = {[string | SpecialKey]: unknown}
+
+export type NewConstructor = (
+	scope: Scope<unknown>,
+	className: string
+) -> (propertyTable: PropertyTable) -> Instance
+
+export type HydrateConstructor = (
+	scope: Scope<unknown>,
+	target: Instance
+) -> (propertyTable: PropertyTable) -> Instance
+
+-- Is there a sane way to write out this type?
+-- ... I sure hope so.
+
+export type DeriveScopeConstructor = (<S>(Scope<S>) -> Scope<S>)
+	& (<S, A>(Scope<S>, A & {}) -> Scope<S & A>)
+	& (<S, A, B>(Scope<S>, A & {}, B & {}) -> Scope<S & A & B>)
+	& (<S, A, B, C>(Scope<S>, A & {}, B & {}, C & {}) -> Scope<S & A & B & C>)
+	& (<S, A, B, C, D>(Scope<S>, A & {}, B & {}, C & {}, D & {}) -> Scope<S & A & B & C & D>)
+	& (<S, A, B, C, D, E>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}) -> Scope<S & A & B & C & D & E>)
+	& (<S, A, B, C, D, E, F>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}) -> Scope<S & A & B & C & D & E & F>)
+	& (<S, A, B, C, D, E, F, G>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}) -> Scope<S & A & B & C & D & E & F & G>)
+	& (<S, A, B, C, D, E, F, G, H>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}) -> Scope<S & A & B & C & D & E & F & G & H>)
+	& (<S, A, B, C, D, E, F, G, H, I>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}) -> Scope<S & A & B & C & D & E & F & G & H & I>)
+	& (<S, A, B, C, D, E, F, G, H, I, J>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}) -> Scope<S & A & B & C & D & E & F & G & H & I & J>)
+	& (<S, A, B, C, D, E, F, G, H, I, J, K>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}, K & {}) -> Scope<S & A & B & C & D & E & F & G & H & I & J & K>)
+	& (<S, A, B, C, D, E, F, G, H, I, J, K, L>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}, K & {}, L & {}) -> Scope<S & A & B & C & D & E & F & G & H & I & J & K & L>)
+
+export type ScopedConstructor = (() -> Scope<{}>)
+	& (<A>(A & {}) -> Scope<A>)
+	& (<A, B>(A & {}, B & {}) -> Scope<A & B>)
+	& (<A, B, C>(A & {}, B & {}, C & {}) -> Scope<A & B & C>)
+	& (<A, B, C, D>(A & {}, B & {}, C & {}, D & {}) -> Scope<A & B & C & D>)
+	& (<A, B, C, D, E>(A & {}, B & {}, C & {}, D & {}, E & {}) -> Scope<A & B & C & D & E>)
+	& (<A, B, C, D, E, F>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}) -> Scope<A & B & C & D & E & F>)
+	& (<A, B, C, D, E, F, G>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}) -> Scope<A & B & C & D & E & F & G>)
+	& (<A, B, C, D, E, F, G, H>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}) -> Scope<A & B & C & D & E & F & G & H>)
+	& (<A, B, C, D, E, F, G, H, I>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}) -> Scope<A & B & C & D & E & F & G & H & I>)
+	& (<A, B, C, D, E, F, G, H, I, J>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}) -> Scope<A & B & C & D & E & F & G & H & I & J>)
+	& (<A, B, C, D, E, F, G, H, I, J, K>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}, K & {}) -> Scope<A & B & C & D & E & F & G & H & I & J & K>)
+	& (<A, B, C, D, E, F, G, H, I, J, K, L>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}, K & {}, L & {}) -> Scope<A & B & C & D & E & F & G & H & I & J & K & L>)
+
+export type ContextualConstructor = <T>(defaultValue: T) -> Contextual<T>
+
+export type Safe = <Success, Fail>(
+	callbacks: {
+		try: () -> Success,
+		fallback: (err: unknown) -> Fail
+	}
+) -> Success | Fail
+
+export type Fusion = {
+	version: Version,
+	Contextual: ContextualConstructor,
+	Safe: Safe,
+
+	doCleanup: (Task) -> (),
+	scoped: ScopedConstructor,
+	deriveScope: DeriveScopeConstructor,
+	innerScope: DeriveScopeConstructor,
+	insert: <Tasks...>(scope: Scope<unknown>, Tasks...) -> Tasks...,
+
+	peek: Use,
+	Value: ValueConstructor,
+	Computed: ComputedConstructor,
+	ForPairs: ForPairsConstructor,
+	ForKeys: ForKeysConstructor,
+	ForValues: ForValuesConstructor,
+	Observer: ObserverConstructor,
+
+	Tween: TweenConstructor,
+	Spring: SpringConstructor,
+
+	New: NewConstructor,
+	Hydrate: HydrateConstructor,
+
+	Child: ({Child}) -> Child,
+	Children: SpecialKey,
+	Out: (propertyName: string) -> SpecialKey,
+	OnEvent: (eventName: string) -> SpecialKey,
+	OnChange: (propertyName: string) -> SpecialKey,
+	Attribute: (attributeName: string) -> SpecialKey,
+	AttributeChange: (attributeName: string) -> SpecialKey,
+	AttributeOut: (attributeName: string) -> SpecialKey,
+	Tag: (tagName: string) -> SpecialKey,
+}
+
+export type ExternalProvider = {
+	policies: {
+		allowWebLinks: boolean
+	},
+
+	logErrorNonFatal: (
+		errorString: string
+	) -> (),
+	logWarn: (
+		errorString: string
+	) -> (),
+
+	doTaskImmediate: (
+		resume: () -> ()
+	) -> (),
+	doTaskDeferred: (
+		resume: () -> ()
+	) -> (),
+	startScheduler: () -> (),
+	stopScheduler: () -> ()
+}
+
+export type ExternalDebugger = {
+	startDebugging: () -> (),
+	stopDebugging: () -> (),
+
+	trackScope: (
+		scope: Scope<unknown>
+	) -> (),
+	untrackScope: (
+		scope: Scope<unknown>
+	) -> ()
+}
+
+return nil

package/templates/game/libs/Fusion/Utility/Contextual.luau

@@ -0,0 +1,91 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+    Time-based contextual values, to allow for transparently passing values down
+	the call stack.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+-- Logging
+local parseError = require(Package.Logging.parseError)
+
+export type Self<T> = Types.Contextual<T> & {
+	_valuesNow: {[thread]: {value: T}},
+	_defaultValue: T
+}
+
+local class = {}
+class.type = "Contextual"
+
+local METATABLE = table.freeze {__index = class}
+local WEAK_KEYS_METATABLE = table.freeze {__mode = "k"}
+
+local function Contextual<T>(
+	defaultValue: T
+): Types.Contextual<T>
+	local self: Self<T> = setmetatable(
+		{
+			-- if we held strong references to threads here, then if a thread was
+			-- killed before this contextual had a chance to finish executing its
+			-- callback, it would be held strongly in this table forever
+			_valuesNow = setmetatable({}, WEAK_KEYS_METATABLE),
+			_defaultValue = defaultValue
+		}, 
+		METATABLE
+	) :: any
+
+	return self
+end
+
+--[[
+	Returns the current value of this contextual.
+]]
+function class.now<T>(
+	self: Self<T>
+): T
+	local thread = coroutine.running()
+	local value = self._valuesNow[thread]
+	if typeof(value) ~= "table" then
+		return self._defaultValue
+	else
+		return value.value
+	end
+end
+
+--[[
+	Temporarily assigns a value to this contextual.
+]]
+function class.is<T>(
+	self: Self<T>,
+	newValue: T
+)
+	local methods = {}
+	
+	function methods.during<T, A...>(
+		_: any, -- during is called with colon syntax but we don't care
+		callback: (A...) -> T,
+		...: A...
+	): T
+		local thread = coroutine.running()
+		local prevValue = self._valuesNow[thread]
+		-- Storing the value in this format allows us to distinguish storing
+		-- `nil` from not calling `:during()` at all.
+		self._valuesNow[thread] = { value = newValue }
+		local ok, value = xpcall(callback, parseError, ...)
+		self._valuesNow[thread] = prevValue
+		if not ok then
+			External.logError("callbackError", value :: any)
+		end
+		return value
+	end
+
+	return methods
+end
+
+table.freeze(class)
+return Contextual

package/templates/game/libs/Fusion/Utility/Safe.luau

@@ -0,0 +1,23 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+    A variant of xpcall() designed for inline usage, letting you define fallback
+	values based on caught errors.
+]]
+
+local Package = script.Parent.Parent
+
+local function Safe<Success, Fail>(
+	callbacks: {
+		try: () -> Success,
+		fallback: (err: unknown) -> Fail
+	}
+): Success | Fail
+	local _, value = xpcall(callbacks.try, callbacks.fallback)
+	return value
+end
+
+return Safe

package/templates/game/libs/Fusion/Utility/isSimilar.luau

@@ -0,0 +1,29 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Implements the 'similarity test' used to determine whether two values have
+	a meaningful difference.
+
+	https://elttob.uk/Fusion/0.3/tutorials/best-practices/optimisation/#similarity
+]]
+
+local function isSimilar(
+	a: unknown, 
+	b: unknown
+): boolean
+	local typeA = typeof(a)
+	local isTable = typeA == "table"
+	local isUserdata = typeA == "userdata"
+	return
+		if not (isTable or isUserdata) then
+			a == b or a ~= a and b ~= b
+		elseif typeA == typeof(b) and (isUserdata or table.isfrozen(a :: any) or getmetatable(a :: any) ~= nil) then
+			a == b
+		else
+			false
+end
+
+return isSimilar

package/templates/game/libs/Fusion/Utility/merge.luau

@@ -0,0 +1,35 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Attempts to merge a variadic number of tables together.
+]]
+
+local Package = script.Parent.Parent
+local External = require(Package.External)
+
+local function merge(
+	overwrite: boolean,
+	into: {[unknown]: unknown},
+	...: {[unknown]: unknown}
+): {[unknown]: unknown}
+	local fromTables = {...}
+	if #fromTables < 1 then
+		return into
+	else
+		for _, fromTable in fromTables do
+			for key, value in fromTable do
+				if overwrite or into[key] == nil then
+					into[key] = value
+				elseif not overwrite then
+					External.logError("mergeConflict", nil, tostring(key))
+				end
+			end
+		end
+		return into
+	end
+end
+
+return merge

package/templates/game/libs/Fusion/Utility/nameOf.luau

@@ -0,0 +1,35 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Returns the most specific custom name for the given object.
+]]
+
+local Package = script.Parent.Parent
+-- Utility
+local nicknames = require(Package.Utility.nicknames)
+
+local function nameOf(
+	x: unknown,
+	defaultName: string
+): string
+	local nickname = nicknames[x]
+	if typeof(nickname) == "string" then
+		return nickname
+	end
+	if typeof(x) == "table" then
+		local x = x :: {[any]: any}
+		if typeof(x.name) == "string" then
+			return x.name
+		elseif typeof(x.kind) == "string" then
+			return x.kind
+		elseif typeof(x.type) == "string" then
+			return x.type
+		end
+	end
+	return defaultName
+end
+
+return nameOf

package/templates/game/libs/Fusion/Utility/never.luau

@@ -0,0 +1,14 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Never returns.
+]]
+
+local function never(): never
+	error("This codepath should not be reachable")
+end
+
+return never

package/templates/game/libs/Fusion/Utility/nicknames.luau

@@ -0,0 +1,11 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Stores nicknames for values that don't support metatables, so that `nameOf`
+	can return values for them.
+]]
+
+return setmetatable({}, {__mode = "k"})

package/templates/game/libs/Fusion/Utility/xtypeof.luau

@@ -0,0 +1,27 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Extended typeof, designed for identifying custom objects.
+	If given a table with a `type` string, returns that.
+	Otherwise, returns `typeof()` the argument.
+]]
+
+local function xtypeof(
+	x: unknown
+): string
+	local typeString = typeof(x)
+
+	if typeString == "table" then
+		local x = x :: {type: unknown?}
+		if typeof(x.type) == "string" then
+			return x.type
+		end
+	end
+
+	return typeString
+end
+
+return xtypeof

package/templates/game/libs/Fusion/_impl/Animation/ExternalTime.luau

@@ -0,0 +1,84 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Outputs the current external time as a state object.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+-- Graph
+local change = require(Package.Graph.change)
+-- Utility
+local nicknames = require(Package.Utility.nicknames)
+
+type ExternalTime = Types.StateObject<number>
+
+type Self = ExternalTime
+
+local class = {}
+class.type = "State"
+class.kind = "ExternalTime"
+class.timeliness = "lazy"
+class.dependencySet = table.freeze {}
+class._EXTREMELY_DANGEROUS_usedAsValue = External.lastUpdateStep()
+
+local METATABLE = table.freeze {__index = class}
+
+local allTimers: {Self} = {}
+
+local function ExternalTime(
+	scope: Types.Scope<unknown>
+): ExternalTime
+	local createdAt = os.clock()
+	local self: Self = setmetatable(
+		{
+			createdAt = createdAt,
+			dependentSet = {},
+			lastChange = nil,
+			scope = scope,
+			validity = "invalid"
+		}, 
+		METATABLE
+	) :: any
+	local destroy = function()
+		self.scope = nil
+		local index = table.find(allTimers, self)
+		if index ~= nil then
+			table.remove(allTimers, index)
+		end
+	end
+	self.oldestTask = destroy
+	nicknames[self.oldestTask] = "ExternalTime"
+	table.insert(scope, destroy)
+	table.insert(allTimers, self)
+	return self
+end
+
+function class._evaluate(
+	self: Self
+): boolean
+	-- While someone else could call `change()` on this object, it wouldn't be
+	-- idiomatic. So, since the only idiomatic time this function runs is when
+	-- the external update step runs, it's safe enough to assume that the result
+	-- has always meaningfully changed. The worst that can happen is unexpected
+	-- refreshing for people doing unorthodox shenanigans, which is an OK trade.
+	return true
+end
+
+External.bindToUpdateStep(function(
+	externalNow: number
+): ()
+	class._EXTREMELY_DANGEROUS_usedAsValue = External.lastUpdateStep()
+	for _, timer in allTimers do
+		change(timer)
+	end
+end)
+
+-- Do *not* freeze the class table, because it stores the shared value of all
+-- external time objects, and is updated every frame because of that.
+-- table.freeze(class)
+return ExternalTime