cluaupp 0.1.0

package/runtime/Fusion/_impl/Animation/Spring.luau

@@ -0,0 +1,313 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	A specialised state object for following a goal state smoothly over time,
+	using physics to shape the motion.
+
+	https://elttob.uk/Fusion/0.3/api-reference/animation/types/spring/
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+-- Memory
+local checkLifetime = require(Package.Memory.checkLifetime)
+-- Graph
+local depend = require(Package.Graph.depend)
+local change = require(Package.Graph.change)
+local evaluate = require(Package.Graph.evaluate)
+-- State
+local castToState = require(Package.State.castToState)
+local peek = require(Package.State.peek)
+-- Animation
+local ExternalTime = require(Package.Animation.ExternalTime)
+local Stopwatch = require(Package.Animation.Stopwatch)
+local packType = require(Package.Animation.packType)
+local unpackType = require(Package.Animation.unpackType)
+local springCoefficients = require(Package.Animation.springCoefficients)
+-- Utility
+local nicknames = require(Package.Utility.nicknames)
+
+local EPSILON = 0.00001
+
+type Self<T> = Types.Spring<T> & {
+	_activeDamping: number,
+	_activeGoal: T,
+	_activeLatestP: {number},
+	_activeLatestV: {number},
+	_activeNumSprings: number,
+	_activeSpeed: number,
+	_activeStartP: {number},
+	_activeStartV: {number},
+	_activeTargetP: {number},
+	_activeType: string,
+	_speed: Types.UsedAs<number>,
+	_damping: Types.UsedAs<number>,
+	_goal: Types.UsedAs<T>,
+	_stopwatch: Stopwatch.Stopwatch
+}
+
+local class = {}
+class.type = "State"
+class.kind = "Spring"
+class.timeliness = "eager"
+
+local METATABLE = table.freeze {__index = class}
+
+local function Spring<T>(
+	scope: Types.Scope<unknown>,
+	goal: Types.UsedAs<T>,
+	speed: Types.UsedAs<number>?,
+	damping: Types.UsedAs<number>?
+): Types.Spring<T>
+	local createdAt = os.clock()
+
+	local goalState = castToState(goal)
+	local stopwatch = nil
+	if goalState ~= nil then
+		stopwatch = Stopwatch(scope, ExternalTime(scope))
+		stopwatch:unpause()
+	end
+
+	local speed = speed or 10
+	local damping = damping or 1
+
+	local self: Self<T> = setmetatable(
+		{
+			createdAt = createdAt,
+			dependencySet = {},
+			dependentSet = {},
+			lastChange = nil,
+			scope = scope,
+			validity = "invalid",
+			_activeDamping = -1,
+			_activeGoal = nil,
+			_activeLatestP = {},
+			_activeLatestV = {},
+			_activeNumSprings = 0,
+			_activeSpeed = -1,
+			_activeStartP = {},
+			_activeStartV = {},
+			_activeTargetP = {},
+			_activeType = "",
+			_damping = damping,
+			_EXTREMELY_DANGEROUS_usedAsValue = peek(goal),
+			_goal = goal,
+			_speed = speed,
+			_stopwatch = stopwatch
+		},
+		METATABLE
+	) :: any
+	local destroy = function()
+		self.scope = nil
+		for dependency in pairs(self.dependencySet) do
+			dependency.dependentSet[self] = nil
+		end
+	end
+	self.oldestTask = destroy
+	nicknames[self.oldestTask] = "Spring"
+	table.insert(scope, destroy)
+	
+	if goalState ~= nil then
+		checkLifetime.bOutlivesA(
+			scope, self.oldestTask,
+			goalState.scope, goalState.oldestTask,
+			checkLifetime.formatters.animationGoal
+		)
+	end
+	local speedState = castToState(speed)
+	if speedState ~= nil then
+		checkLifetime.bOutlivesA(
+			scope, self.oldestTask,
+			speedState.scope, speedState.oldestTask,
+			checkLifetime.formatters.parameter, "speed"
+		)
+	end
+	local dampingState = castToState(damping)
+	if dampingState ~= nil then
+		checkLifetime.bOutlivesA(
+			scope, self.oldestTask,
+			dampingState.scope, dampingState.oldestTask,
+			checkLifetime.formatters.parameter, "damping"
+		)
+	end
+
+	-- Eagerly evaluated objects need to evaluate themselves so that they're
+	-- valid at all times.
+	evaluate(self, true)
+
+	return self
+end
+
+function class.addVelocity<T>(
+	self: Self<T>,
+	deltaValue: T
+): ()
+	evaluate(self, false) -- ensure the _active params are up to date
+	local deltaType = typeof(deltaValue)
+	if deltaType ~= self._activeType then
+		External.logError("springTypeMismatch", nil, deltaType, self._activeType)
+	end
+	local newStartV = unpackType(deltaValue, deltaType)
+	for index, velocity in self._activeLatestV do
+		newStartV[index] += velocity
+	end
+	self._activeStartP = table.clone(self._activeLatestP)
+	self._activeStartV = newStartV
+	self._stopwatch:zero()
+	self._stopwatch:unpause()
+	change(self)
+end
+
+function class.setPosition<T>(
+	self: Self<T>,
+	newValue: T
+): ()
+	evaluate(self, false) -- ensure the _active params are up to date
+	local newType = typeof(newValue)
+	if newType ~= self._activeType then
+		External.logError("springTypeMismatch", nil, newType, self._activeType)
+	end
+	self._activeStartP = unpackType(newValue, newType)
+	self._activeStartV = table.clone(self._activeLatestV)
+	self._stopwatch:zero()
+	self._stopwatch:unpause()
+	change(self)
+end
+
+function class.setVelocity<T>(
+	self: Self<T>,
+	newValue: T
+): ()
+	evaluate(self, false) -- ensure the _active params are up to date
+	local newType = typeof(newValue)
+	if newType ~= self._activeType then
+		External.logError("springTypeMismatch", nil, newType, self._activeType)
+	end
+	self._activeStartP = table.clone(self._activeLatestP)
+	self._activeStartV = unpackType(newValue, newType)
+	self._stopwatch:zero()
+	self._stopwatch:unpause()
+	change(self)
+end
+
+function class._evaluate<T>(
+	self: Self<T>
+): boolean
+	local goal = castToState(self._goal)
+	-- Allow non-state goals to pass through transparently.
+	if goal == nil then
+		self._EXTREMELY_DANGEROUS_usedAsValue = self._goal :: T
+		return false
+	end
+	-- depend(self, goal)
+	local nextFrameGoal = peek(goal)
+	-- Protect against NaN goals.
+	if nextFrameGoal ~= nextFrameGoal then
+		External.logWarn("springNanGoal")
+		return false
+	end
+	local nextFrameGoalType = typeof(nextFrameGoal)
+	local discontinuous = nextFrameGoalType ~= self._activeType
+
+	local stopwatch = self._stopwatch :: Stopwatch.Stopwatch
+	local elapsed = peek(stopwatch)
+	depend(self, stopwatch)
+
+	local oldValue = self._EXTREMELY_DANGEROUS_usedAsValue
+	local newValue: T
+
+	if discontinuous then
+		-- Propagate changes in type instantly throughout the whole reactive
+		-- graph, even if simulation is logically one frame behind, because it
+		-- makes the whole graph behave more consistently.
+		newValue = nextFrameGoal
+	elseif elapsed <= 0 then
+		newValue = oldValue
+	else
+		-- Calculate spring motion.
+		-- IMPORTANT: use the parameters from last frame, not this frame. We're
+		-- integrating the motion that happened over the last frame, after all.
+		-- The stopwatch will have captured the length of time needed correctly.
+		local posPos, posVel, velPos, velVel = springCoefficients(
+			elapsed, 
+			self._activeDamping, 
+			self._activeSpeed
+		)
+		local isMoving = false
+		for index = 1, self._activeNumSprings do
+			local startP = self._activeStartP[index]
+			local targetP = self._activeTargetP[index]
+			local startV = self._activeStartV[index]
+			local startD = startP - targetP
+			local latestD = startD * posPos + startV * posVel
+			local latestV = startD * velPos + startV * velVel
+			if latestD ~= latestD or latestV ~= latestV then
+				External.logWarn("springNanMotion")
+				latestD, latestV = 0, 0
+			end
+			if math.abs(latestD) > EPSILON or math.abs(latestV) > EPSILON then
+				isMoving = true
+			end
+			local latestP = latestD + targetP
+			self._activeLatestP[index] = latestP
+			self._activeLatestV[index] = latestV
+		end
+		-- Sleep and snap to goal if the motion has decayed to a negligible amount.
+		if not isMoving then
+			for index = 1, self._activeNumSprings do
+				self._activeLatestP[index] = self._activeTargetP[index]
+			end
+			-- TODO: figure out how to do sleeping correctly for single frame
+			-- changes
+			-- stopwatch:pause()
+			-- stopwatch:zero()
+		end
+		-- Pack springs into final value.
+		newValue = packType(self._activeLatestP, self._activeType) :: any
+	end
+
+	-- Reconfigure spring when any of its parameters are changed.
+	-- This should happen after integrating the last frame's motion.
+	-- NOTE: don't need to add a dependency on these objects! they do not cause
+	-- a spring to wake from sleep, so the stopwatch dependency is sufficient.
+	local nextFrameSpeed = peek(self._speed) :: number
+	local nextFrameDamping = peek(self._damping) :: number
+	if
+		discontinuous or
+		nextFrameGoal ~= self._activeGoal or
+		nextFrameSpeed ~= self._activeSpeed or
+		nextFrameDamping ~= self._activeDamping
+	then
+		self._activeTargetP = unpackType(nextFrameGoal, nextFrameGoalType)
+		self._activeNumSprings = #self._activeTargetP
+		if discontinuous then
+			self._activeStartP = table.clone(self._activeTargetP)
+			self._activeLatestP = table.clone(self._activeTargetP)
+			self._activeStartV = table.create(self._activeNumSprings, 0)
+			self._activeLatestV = table.create(self._activeNumSprings, 0)
+		else
+			self._activeStartP = table.clone(self._activeLatestP)
+			self._activeStartV = table.clone(self._activeLatestV)
+		end
+		self._activeType = nextFrameGoalType
+		self._activeGoal = nextFrameGoal
+		self._activeDamping = nextFrameDamping
+		self._activeSpeed = nextFrameSpeed
+		stopwatch:zero()
+		stopwatch:unpause()
+	end
+
+	-- Push update and check for similarity.
+	-- Don't need to use the similarity test here because this code doesn't
+	-- deal with tables, and NaN is already guarded against, so the similarity
+	-- test doesn't actually add any new safety here.
+	self._EXTREMELY_DANGEROUS_usedAsValue = newValue
+	return oldValue ~= newValue
+end
+
+table.freeze(class)
+return Spring :: Types.SpringConstructor

package/runtime/Fusion/_impl/Animation/Stopwatch.luau

@@ -0,0 +1,128 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	State object for measuring time since an event using a reference timer.
+
+	TODO: this should not be exposed to users until it has a proper reactive API
+	surface
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+-- Memory
+local checkLifetime = require(Package.Memory.checkLifetime)
+-- Graph
+local depend = require(Package.Graph.depend)
+local change = require(Package.Graph.change)
+-- State
+local peek = require(Package.State.peek)
+-- Utility
+local nicknames = require(Package.Utility.nicknames)
+
+export type Stopwatch = Types.StateObject<number> & {
+	zero: (Stopwatch) -> (),
+	pause: (Stopwatch) -> (),
+	unpause: (Stopwatch) -> ()
+}
+
+type Self = Stopwatch & {
+	_measureTimeSince: number,
+	_playing: boolean,
+	_timer: Types.StateObject<number>
+}
+
+local class = {}
+class.type = "State"
+class.kind = "Stopwatch"
+class.timeliness = "lazy"
+
+local METATABLE = table.freeze {__index = class}
+
+local function Stopwatch(
+	scope: Types.Scope<unknown>,
+	timer: Types.StateObject<number>
+): Stopwatch
+	local createdAt = os.clock()
+	local self: Self = setmetatable(
+		{
+			awake = true,
+			createdAt = createdAt,
+			dependencySet = {},
+			dependentSet = {},
+			lastChange = nil,
+			scope = scope,
+			validity = "invalid",
+			_EXTREMELY_DANGEROUS_usedAsValue = 0,
+			_measureTimeSince = 0, -- this should be set on unpause
+			_playing = false,
+			_timer = timer
+		}, 
+		METATABLE
+	) :: any
+	local destroy = function()
+		self.scope = nil
+	end
+	self.oldestTask = destroy
+	nicknames[self.oldestTask] = "Stopwatch"
+	table.insert(scope, destroy)
+
+	checkLifetime.bOutlivesA(
+		scope, self.oldestTask,
+		timer.scope, timer.oldestTask,
+		checkLifetime.formatters.parameter, "timer"
+	)
+	depend(self, timer)
+	return self
+end
+
+function class.zero(
+	self: Self
+): ()
+	local newTimepoint = peek(self._timer)
+	if newTimepoint ~= self._measureTimeSince then
+		self._measureTimeSince = newTimepoint
+		self._EXTREMELY_DANGEROUS_usedAsValue = 0
+		change(self)
+	end
+end
+
+function class.pause(
+	self: Self
+): ()
+	if self._playing == true then
+		self._playing = false
+		change(self)
+	end
+end
+
+function class.unpause(
+	self: Self
+): ()
+	if self._playing == false then
+		self._playing = true
+		self._measureTimeSince = peek(self._timer) - self._EXTREMELY_DANGEROUS_usedAsValue
+		change(self)
+	end
+end
+
+function class._evaluate(
+	self: Self
+): boolean
+	if self._playing then
+		depend(self, self._timer)
+		local currentTime = peek(self._timer)
+		local oldValue = self._EXTREMELY_DANGEROUS_usedAsValue
+		local newValue = currentTime - self._measureTimeSince
+		self._EXTREMELY_DANGEROUS_usedAsValue = newValue
+		return oldValue ~= newValue
+	else
+		return false
+	end
+	
+end
+
+table.freeze(class)
+return Stopwatch

package/runtime/Fusion/_impl/Animation/Tween.luau

@@ -0,0 +1,178 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	A specialised state object for following a goal state smoothly over time,
+	using a TweenInfo to shape the motion.
+
+	https://elttob.uk/Fusion/0.3/api-reference/animation/types/tween/
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+-- Memory
+local checkLifetime = require(Package.Memory.checkLifetime)
+-- Graph
+local depend = require(Package.Graph.depend)
+local evaluate = require(Package.Graph.evaluate)
+-- State
+local castToState = require(Package.State.castToState)
+local peek = require(Package.State.peek)
+-- Animation
+local ExternalTime = require(Package.Animation.ExternalTime)
+local Stopwatch = require(Package.Animation.Stopwatch)
+local lerpType = require(Package.Animation.lerpType)
+local getTweenRatio = require(Package.Animation.getTweenRatio)
+local getTweenDuration = require(Package.Animation.getTweenDuration)
+-- Utility
+local nicknames = require(Package.Utility.nicknames)
+
+export type Self<T> = Types.Tween<T> & {
+	_activeDuration: number,
+	_activeElapsed: number,
+	_activeFrom: T,
+	_activeTo: T,
+	_activeTweenInfo: TweenInfo,
+	_goal: Types.UsedAs<T>,
+	_stopwatch: Stopwatch.Stopwatch?,
+	_tweenInfo: Types.UsedAs<TweenInfo>,
+}
+
+local class = {}
+class.type = "State"
+class.kind = "Tween"
+class.timeliness = "eager"
+
+local METATABLE = table.freeze {__index = class}
+
+local function Tween<T>(
+	scope: Types.Scope<unknown>,
+	goal: Types.UsedAs<T>,
+	tweenInfo: Types.UsedAs<TweenInfo>?
+): Types.Tween<T>
+	local createdAt = os.clock()
+
+	local goalState = castToState(goal)
+	local stopwatch = nil
+	if goalState ~= nil then
+		stopwatch = Stopwatch(scope, ExternalTime(scope))
+	end
+
+	local self: Self<T> = setmetatable(
+		{
+			createdAt = createdAt,
+			dependencySet = {},
+			dependentSet = {},
+			lastChange = nil,
+			scope = scope,
+			validity = "invalid",
+			_activeDuration = nil,
+			_activeElapsed = nil,
+			_activeFrom = nil,
+			_activeTo = nil,
+			_activeTweenInfo = nil,
+			_EXTREMELY_DANGEROUS_usedAsValue = peek(goal),
+			_goal = goal,
+			_stopwatch = stopwatch,
+			_tweenInfo = tweenInfo or TweenInfo.new()
+		},
+		METATABLE
+	) :: any
+	local destroy = function()
+		self.scope = nil
+		for dependency in pairs(self.dependencySet) do
+			dependency.dependentSet[self] = nil
+		end
+	end
+	self.oldestTask = destroy
+	nicknames[self.oldestTask] = "Tween"
+	table.insert(scope, destroy)
+
+	if goalState ~= nil then
+		checkLifetime.bOutlivesA(
+			scope, self.oldestTask,
+			goalState.scope, goalState.oldestTask,
+			checkLifetime.formatters.animationGoal
+		)
+	end
+
+	local tweenInfoState = castToState(tweenInfo)
+	if tweenInfoState ~= nil then
+		checkLifetime.bOutlivesA(
+			scope, self.oldestTask,
+			tweenInfoState.scope, tweenInfoState.oldestTask,
+			checkLifetime.formatters.parameter, "tween info"
+		)
+	end
+
+	-- Eagerly evaluated objects need to evaluate themselves so that they're
+	-- valid at all times.
+	evaluate(self, true)
+
+	return self
+end
+
+function class._evaluate<T>(
+	self: Self<T>
+): boolean
+	local goal = castToState(self._goal)
+	-- Allow non-state goals to pass through transparently.
+	if goal == nil then
+		self._EXTREMELY_DANGEROUS_usedAsValue = self._goal :: T
+		return false
+	end
+	depend(self, goal)
+	local newTweenTo = peek(goal)
+	-- Protect against NaN goals.
+	if newTweenTo ~= newTweenTo then
+		External.logWarn("tweenNanGoal")
+		return false
+	end
+	local stopwatch = self._stopwatch :: Stopwatch.Stopwatch
+	local tweenInfo = peek(self._tweenInfo) :: TweenInfo
+	-- Restart animation when the goal changes, or if the tween info changes
+	-- partway through another animation.
+	if 
+		self._activeTo ~= newTweenTo or
+		(self._activeElapsed < self._activeDuration and self._activeTweenInfo ~= tweenInfo)
+	then
+		self._activeDuration = getTweenDuration(tweenInfo)
+		self._activeFrom = self._EXTREMELY_DANGEROUS_usedAsValue
+		self._activeTo = newTweenTo
+		self._activeTweenInfo = tweenInfo
+		stopwatch:zero()
+		stopwatch:unpause()
+	end
+	depend(self, stopwatch)
+	self._activeElapsed = peek(stopwatch)
+	if
+		self._activeFrom == self._activeTo or -- endpoints match
+		self._activeElapsed >= self._activeDuration or -- animation is done
+		typeof(self._activeTo) ~= typeof(self._activeFrom) -- type difference
+	then
+		self._activeFrom = self._activeTo
+		self._activeElapsed = self._activeDuration
+		stopwatch:pause()
+	end
+	-- Compute actual tweened value.
+	local ratio = getTweenRatio(tweenInfo, self._activeElapsed)
+	local oldValue = self._EXTREMELY_DANGEROUS_usedAsValue
+	local newValue = lerpType(self._activeFrom, self._activeTo, ratio) :: T
+	-- Protect against NaN after motion.
+	if newValue ~= newValue then
+		External.logWarn("tweenNanMotion")
+		newValue = self._activeTo
+	end
+	-- Push update and check for similarity.
+	-- Don't need to use the similarity test here because this code doesn't
+	-- deal with tables, and NaN is already guarded against, so the similarity
+	-- test doesn't actually add any new safety here.
+	self._EXTREMELY_DANGEROUS_usedAsValue = newValue
+	return oldValue ~= newValue
+end
+
+table.freeze(class)
+return Tween :: Types.TweenConstructor

package/runtime/Fusion/_impl/Animation/getTweenDuration.luau

@@ -0,0 +1,27 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Given a `tweenInfo`, returns how many seconds it will take before the tween
+	finishes moving. The result may be infinite if the tween repeats forever.
+]]
+
+local TweenService = game:GetService("TweenService")
+
+local function getTweenDuration(
+	tweenInfo: TweenInfo
+): number
+	if tweenInfo.RepeatCount <= -1 then
+		return math.huge
+	end
+	local tweenDuration = tweenInfo.DelayTime + tweenInfo.Time
+	if tweenInfo.Reverses then
+		tweenDuration += tweenInfo.Time
+	end
+	tweenDuration *= tweenInfo.RepeatCount + 1
+	return tweenDuration
+end
+
+return getTweenDuration

package/runtime/Fusion/_impl/Animation/getTweenRatio.luau

@@ -0,0 +1,47 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Given a `tweenInfo` and `currentTime`, returns a ratio which can be used to
+	tween between two values over time.
+]]
+
+local TweenService = game:GetService("TweenService")
+
+local function getTweenRatio(
+	tweenInfo: TweenInfo,
+	currentTime: number
+): number
+	local delay = tweenInfo.DelayTime
+	local duration = tweenInfo.Time
+	local reverses = tweenInfo.Reverses
+	local numCycles = 1 + tweenInfo.RepeatCount
+	local easeStyle = tweenInfo.EasingStyle
+	local easeDirection = tweenInfo.EasingDirection
+	local cycleDuration = delay + duration
+	if reverses then
+		cycleDuration += duration
+	end
+	-- If currentTime is infinity, then presumably the tween should be over.
+	-- This avoids NaN when the duration of an infinitely repeating tween is given.
+	if currentTime == math.huge then
+		return 1
+	end
+	if currentTime >= cycleDuration * numCycles and tweenInfo.RepeatCount > -1 then
+		return 1
+	end
+	local cycleTime = currentTime % cycleDuration
+	if cycleTime <= delay then
+		return 0
+	end
+	local tweenProgress = (cycleTime - delay) / duration
+	if tweenProgress > 1 then
+		tweenProgress = 2 - tweenProgress
+	end
+	local ratio = TweenService:GetValue(tweenProgress, easeStyle, easeDirection)
+	return ratio
+end
+
+return getTweenRatio