cluaupp 0.1.0

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

@@ -0,0 +1,164 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Linearly interpolates the given animatable types by a ratio.
+	If the types are different or not animatable, then the first value will be
+	returned for ratios below 0.5, and the second value for 0.5 and above.
+]]
+
+local Package = script.Parent.Parent
+local Oklab = require(Package.Colour.Oklab)
+
+local function lerpType(
+	from: unknown, 
+	to: unknown, 
+	ratio: number
+): unknown
+	local typeString = typeof(from)
+
+	if typeof(to) == typeString then
+		-- both types must match for interpolation to make sense
+		if typeString == "number" then
+			local to, from = to :: number, from :: number
+			return (to - from) * ratio + from
+
+		elseif typeString == "CFrame" then
+			local to, from = to :: CFrame, from :: CFrame
+			return from:Lerp(to, ratio)
+
+		elseif typeString == "Color3" then
+			local to, from = to :: Color3, from :: Color3
+			local fromLab = Oklab.fromSRGB(from)
+			local toLab = Oklab.fromSRGB(to)
+			return Oklab.toSRGB(
+				fromLab:Lerp(toLab, ratio),
+				false
+			)
+
+		elseif typeString == "ColorSequenceKeypoint" then
+			local to, from = to :: ColorSequenceKeypoint, from :: ColorSequenceKeypoint
+			local fromLab = Oklab.fromSRGB(from.Value)
+			local toLab = Oklab.fromSRGB(to.Value)
+			return ColorSequenceKeypoint.new(
+				(to.Time - from.Time) * ratio + from.Time,
+				Oklab.toSRGB(
+					fromLab:Lerp(toLab, ratio),
+					false
+				)
+			)
+
+		elseif typeString == "DateTime" then
+			local to, from = to :: DateTime, from :: DateTime
+			return DateTime.fromUnixTimestampMillis(
+				(to.UnixTimestampMillis - from.UnixTimestampMillis) * ratio + from.UnixTimestampMillis
+			)
+
+		elseif typeString == "NumberRange" then
+			local to, from = to :: NumberRange, from :: NumberRange
+			return NumberRange.new(
+				(to.Min - from.Min) * ratio + from.Min,
+				(to.Max - from.Max) * ratio + from.Max
+			)
+
+		elseif typeString == "NumberSequenceKeypoint" then
+			local to, from = to :: NumberSequenceKeypoint, from :: NumberSequenceKeypoint
+			return NumberSequenceKeypoint.new(
+				(to.Time - from.Time) * ratio + from.Time,
+				(to.Value - from.Value) * ratio + from.Value,
+				(to.Envelope - from.Envelope) * ratio + from.Envelope
+			)
+
+		elseif typeString == "PhysicalProperties" then
+			local to, from = to :: PhysicalProperties, from :: PhysicalProperties
+			return PhysicalProperties.new(
+				(to.Density - from.Density) * ratio + from.Density,
+				(to.Friction - from.Friction) * ratio + from.Friction,
+				(to.Elasticity - from.Elasticity) * ratio + from.Elasticity,
+				(to.FrictionWeight - from.FrictionWeight) * ratio + from.FrictionWeight,
+				(to.ElasticityWeight - from.ElasticityWeight) * ratio + from.ElasticityWeight
+			)
+
+		elseif typeString == "Ray" then
+			local to, from = to :: Ray, from :: Ray
+			return Ray.new(
+				from.Origin:Lerp(to.Origin, ratio),
+				from.Direction:Lerp(to.Direction, ratio)
+			)
+
+		elseif typeString == "Rect" then
+			local to, from = to :: Rect, from :: Rect
+			return Rect.new(
+				from.Min:Lerp(to.Min, ratio),
+				from.Max:Lerp(to.Max, ratio)
+			)
+
+		elseif typeString == "Region3" then
+			local to, from = to :: Region3, from :: Region3
+			-- FUTURE: support rotated Region3s if/when they become constructable
+			local position = from.CFrame.Position:Lerp(to.CFrame.Position, ratio)
+			local halfSize = from.Size:Lerp(to.Size, ratio) / 2
+			return Region3.new(position - halfSize, position + halfSize)
+
+		elseif typeString == "Region3int16" then
+			local to, from = to :: Region3int16, from :: Region3int16
+			return Region3int16.new(
+				Vector3int16.new(
+					(to.Min.X - from.Min.X) * ratio + from.Min.X,
+					(to.Min.Y - from.Min.Y) * ratio + from.Min.Y,
+					(to.Min.Z - from.Min.Z) * ratio + from.Min.Z
+				),
+				Vector3int16.new(
+					(to.Max.X - from.Max.X) * ratio + from.Max.X,
+					(to.Max.Y - from.Max.Y) * ratio + from.Max.Y,
+					(to.Max.Z - from.Max.Z) * ratio + from.Max.Z
+				)
+			)
+
+		elseif typeString == "UDim" then
+			local to, from = to :: UDim, from :: UDim
+			return UDim.new(
+				(to.Scale - from.Scale) * ratio + from.Scale,
+				(to.Offset - from.Offset) * ratio + from.Offset
+			)
+
+		elseif typeString == "UDim2" then
+			local to, from = to :: UDim2, from :: UDim2
+			return from:Lerp(to, ratio)
+
+		elseif typeString == "Vector2" then
+			local to, from = to :: Vector2, from :: Vector2
+			return from:Lerp(to, ratio)
+
+		elseif typeString == "Vector2int16" then
+			local to, from = to :: Vector2int16, from :: Vector2int16
+			return Vector2int16.new(
+				(to.X - from.X) * ratio + from.X,
+				(to.Y - from.Y) * ratio + from.Y
+			)
+
+		elseif typeString == "Vector3" then
+			local to, from = to :: Vector3, from :: Vector3
+			return from:Lerp(to, ratio)
+
+		elseif typeString == "Vector3int16" then
+			local to, from = to :: Vector3int16, from :: Vector3int16
+			return Vector3int16.new(
+				(to.X - from.X) * ratio + from.X,
+				(to.Y - from.Y) * ratio + from.Y,
+				(to.Z - from.Z) * ratio + from.Z
+			)
+		end
+	end
+
+	-- fallback case: the types are different or not animatable
+	if ratio < 0.5 then
+		return from
+	else
+		return to
+	end
+end
+
+return lerpType

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

@@ -0,0 +1,100 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Packs an array of numbers into a given animatable data type.
+	If the type is not animatable, nil will be returned.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local Oklab = require(Package.Colour.Oklab)
+
+local function packType(
+	numbers: {number},
+	typeString: string
+): Types.Animatable?
+	if typeString == "number" then
+		return numbers[1]
+
+	elseif typeString == "CFrame" then
+		return
+			CFrame.new(numbers[1], numbers[2], numbers[3]) *
+			CFrame.fromAxisAngle(
+				Vector3.new(numbers[4], numbers[5], numbers[6]).Unit,
+				numbers[7]
+			)
+
+	elseif typeString == "Color3" then
+		return Oklab.toSRGB(
+			Vector3.new(numbers[1], numbers[2], numbers[3]),
+			false
+		)
+
+	elseif typeString == "ColorSequenceKeypoint" then
+		return ColorSequenceKeypoint.new(
+			numbers[4],
+			Oklab.toSRGB(
+				Vector3.new(numbers[1], numbers[2], numbers[3]),
+				false
+			)
+		)
+
+	elseif typeString == "DateTime" then
+		return DateTime.fromUnixTimestampMillis(numbers[1])
+
+	elseif typeString == "NumberRange" then
+		return NumberRange.new(numbers[1], numbers[2])
+
+	elseif typeString == "NumberSequenceKeypoint" then
+		return NumberSequenceKeypoint.new(numbers[2], numbers[1], numbers[3])
+
+	elseif typeString == "PhysicalProperties" then
+		return PhysicalProperties.new(numbers[1], numbers[2], numbers[3], numbers[4], numbers[5])
+
+	elseif typeString == "Ray" then
+		return Ray.new(
+			Vector3.new(numbers[1], numbers[2], numbers[3]),
+			Vector3.new(numbers[4], numbers[5], numbers[6])
+		)
+
+	elseif typeString == "Rect" then
+		return Rect.new(numbers[1], numbers[2], numbers[3], numbers[4])
+
+	elseif typeString == "Region3" then
+		-- FUTURE: support rotated Region3s if/when they become constructable
+		local position = Vector3.new(numbers[1], numbers[2], numbers[3])
+		local halfSize = Vector3.new(numbers[4] / 2, numbers[5] / 2, numbers[6] / 2)
+		return Region3.new(position - halfSize, position + halfSize)
+
+	elseif typeString == "Region3int16" then
+		return Region3int16.new(
+			Vector3int16.new(math.round(numbers[1]), math.round(numbers[2]), math.round(numbers[3])),
+			Vector3int16.new(math.round(numbers[4]), math.round(numbers[5]), math.round(numbers[6]))
+		)
+
+	elseif typeString == "UDim" then
+		return UDim.new(numbers[1], math.round(numbers[2]))
+
+	elseif typeString == "UDim2" then
+		return UDim2.new(numbers[1], math.round(numbers[2]), numbers[3], math.round(numbers[4]))
+
+	elseif typeString == "Vector2" then
+		return Vector2.new(numbers[1], numbers[2])
+
+	elseif typeString == "Vector2int16" then
+		return Vector2int16.new(math.round(numbers[1]), math.round(numbers[2]))
+
+	elseif typeString == "Vector3" then
+		return Vector3.new(numbers[1], numbers[2], numbers[3])
+
+	elseif typeString == "Vector3int16" then
+		return Vector3int16.new(math.round(numbers[1]), math.round(numbers[2]), math.round(numbers[3]))
+	else
+		return nil
+	end
+end
+
+return packType

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

@@ -0,0 +1,80 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Returns a 2x2 matrix of coefficients for a given time, damping and angular
+	frequency (aka 'speed').
+	
+	Specifically, this returns four coefficients - posPos, posVel, velPos, and
+	velVel - which can be multiplied with position and velocity like so:
+
+	local newPosition = oldPosition * posPos + oldVelocity * posVel
+	local newVelocity = oldPosition * velPos + oldVelocity * velVel
+
+	For speed = 1 and damping = 0, the result is a simple harmonic oscillator
+	with a period of tau.
+
+	Special thanks to AxisAngle for helping to improve numerical precision.
+]]
+
+local function springCoefficients(
+	time: number,
+	damping: number,
+	speed: number
+): (number, number, number, number)
+	-- if time or speed is 0, then the spring won't move
+	if time == 0 or speed == 0 then
+		return 1, 0, 0, 1
+	end
+	local posPos, posVel, velPos, velVel
+
+	if damping > 1 then
+		-- overdamped spring
+
+		local alpha = math.sqrt(damping^2 - 1)
+		local negHalf_over_alpha_speed = -0.5 / (alpha * speed)
+		local z1 = speed * (alpha + damping) * -1
+		local z2 = speed * (alpha - damping)
+		local exp1 = math.exp(time * z1)
+		local exp2 = math.exp(time * z2)
+
+		posPos = (exp2 * z1 - exp1 * z2) * negHalf_over_alpha_speed
+		posVel = (exp1 - exp2) * negHalf_over_alpha_speed / speed
+		velPos = (exp2 - exp1) * negHalf_over_alpha_speed * speed
+		velVel = (exp1 * z1 - exp2 * z2) * negHalf_over_alpha_speed
+
+	elseif damping == 1 then
+		-- critically damped spring
+
+		local time_speed = time * speed
+		local time_speed_neg1 = time_speed * -1
+		local exp = math.exp(time_speed_neg1)
+
+		posPos = exp * (time_speed + 1)
+		posVel = exp * time
+		velPos = exp * (time_speed_neg1 * speed)
+		velVel = exp * (time_speed_neg1 + 1)
+	else
+		-- underdamped spring
+
+		local alpha = speed * math.sqrt(1 - damping^2)
+		local overAlpha = 1 / alpha
+		local exp = math.exp(-1 * time * speed * damping)
+		local sin = math.sin(alpha * time)
+		local cos = math.cos(alpha * time)
+		local exp_sin = exp * sin
+		local exp_cos = exp * cos
+		local exp_sin_speed_damping_overAlpha = exp_sin * speed * damping * overAlpha
+
+		posPos = exp_sin_speed_damping_overAlpha + exp_cos
+		posVel = exp_sin * overAlpha
+		velPos = -1 * ( exp_sin * alpha + speed * damping * exp_sin_speed_damping_overAlpha )
+		velVel = exp_cos - exp_sin_speed_damping_overAlpha
+	end
+
+	return posPos, posVel, velPos, velVel
+end
+
+return springCoefficients

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

@@ -0,0 +1,103 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Unpacks an animatable type into an array of numbers.
+	If the type is not animatable, an empty array will be returned.
+]]
+
+local Package = script.Parent.Parent
+local Oklab = require(Package.Colour.Oklab)
+
+local function unpackType(
+	value: unknown,
+	typeString: string
+): {number}
+	if typeString == "number" then
+		local value = value :: number
+		return {value}
+
+	elseif typeString == "CFrame" then
+		local value = value :: CFrame
+		-- FUTURE: is there a better way of doing this? doing distance
+		-- calculations on `angle` may be incorrect
+		local axis, angle = value:ToAxisAngle()
+		return {value.X, value.Y, value.Z, axis.X, axis.Y, axis.Z, angle}
+
+	elseif typeString == "Color3" then
+		local value = value :: Color3
+		local lab = Oklab.fromSRGB(value)
+		return {lab.X, lab.Y, lab.Z}
+
+	elseif typeString == "ColorSequenceKeypoint" then
+		local value = value :: ColorSequenceKeypoint
+		local lab = Oklab.fromSRGB(value.Value)
+		return {lab.X, lab.Y, lab.Z, value.Time}
+
+	elseif typeString == "DateTime" then
+		local value = value :: DateTime
+		return {value.UnixTimestampMillis}
+
+	elseif typeString == "NumberRange" then
+		local value = value :: NumberRange
+		return {value.Min, value.Max}
+
+	elseif typeString == "NumberSequenceKeypoint" then
+		local value = value :: NumberSequenceKeypoint
+		return {value.Value, value.Time, value.Envelope}
+
+	elseif typeString == "PhysicalProperties" then
+		local value = value :: PhysicalProperties
+		return {value.Density, value.Friction, value.Elasticity, value.FrictionWeight, value.ElasticityWeight}
+
+	elseif typeString == "Ray" then
+		local value = value :: Ray
+		return {value.Origin.X, value.Origin.Y, value.Origin.Z, value.Direction.X, value.Direction.Y, value.Direction.Z}
+
+	elseif typeString == "Rect" then
+		local value = value :: Rect
+		return {value.Min.X, value.Min.Y, value.Max.X, value.Max.Y}
+
+	elseif typeString == "Region3" then
+		local value = value :: Region3
+		-- FUTURE: support rotated Region3s if/when they become constructable
+		return {
+			value.CFrame.X, value.CFrame.Y, value.CFrame.Z,
+			value.Size.X, value.Size.Y, value.Size.Z
+		}
+
+	elseif typeString == "Region3int16" then
+		local value = value :: Region3int16
+		return {value.Min.X, value.Min.Y, value.Min.Z, value.Max.X, value.Max.Y, value.Max.Z}
+
+	elseif typeString == "UDim" then
+		local value = value :: UDim
+		return {value.Scale, value.Offset}
+
+	elseif typeString == "UDim2" then
+		local value = value :: UDim2
+		return {value.X.Scale, value.X.Offset, value.Y.Scale, value.Y.Offset}
+
+	elseif typeString == "Vector2" then
+		local value = value :: Vector2
+		return {value.X, value.Y}
+
+	elseif typeString == "Vector2int16" then
+		local value = value :: Vector2int16
+		return {value.X, value.Y}
+
+	elseif typeString == "Vector3" then
+		local value = value :: Vector3
+		return {value.X, value.Y, value.Z}
+
+	elseif typeString == "Vector3int16" then
+		local value = value :: Vector3int16
+		return {value.X, value.Y, value.Z}
+	else
+		return {}
+	end
+end
+
+return unpackType

package/runtime/Fusion/_impl/Colour/Oklab.luau

@@ -0,0 +1,70 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Provides functions for converting Color3s into Oklab space, for more
+	perceptually uniform colour blending.
+
+	See: https://bottosson.github.io/posts/oklab/
+]]
+
+local sRGB = require(script.Parent.sRGB)
+
+local Oklab = {}
+
+-- Converts a Color3 in linear RGB space to a Vector3 in Oklab space.
+function Oklab.fromLinear(rgb: Color3): Vector3
+
+	local l = rgb.R * 0.4122214708 + rgb.G * 0.5363325363 + rgb.B * 0.0514459929
+	local m = rgb.R * 0.2119034982 + rgb.G * 0.6806995451 + rgb.B * 0.1073969566
+	local s = rgb.R * 0.0883024619 + rgb.G * 0.2817188376 + rgb.B * 0.6299787005
+
+	local lRoot = l ^ (1/3)
+	local mRoot = m ^ (1/3)
+	local sRoot = s ^ (1/3)
+
+	return Vector3.new(
+		lRoot * 0.2104542553 + mRoot * 0.7936177850 - sRoot * 0.0040720468,
+		lRoot * 1.9779984951 - mRoot * 2.4285922050 + sRoot * 0.4505937099,
+		lRoot * 0.0259040371 + mRoot * 0.7827717662 - sRoot * 0.8086757660
+	)
+end
+
+-- Converts a Color3 in sRGB space to a Vector3 in Oklab space.
+function Oklab.fromSRGB(srgb: Color3): Vector3
+	return Oklab.fromLinear(sRGB.toLinear(srgb))
+end
+
+-- Converts a Vector3 in Oklab space to a Color3 in linear RGB space.
+-- The Color3 will be clamped by default unless specified otherwise.
+function Oklab.toLinear(lab: Vector3, unclamped: boolean?): Color3
+	local lRoot = lab.X + lab.Y * 0.3963377774 + lab.Z * 0.2158037573
+	local mRoot = lab.X - lab.Y * 0.1055613458 - lab.Z * 0.0638541728
+	local sRoot = lab.X - lab.Y * 0.0894841775 - lab.Z * 1.2914855480
+
+	local l = lRoot ^ 3
+	local m = mRoot ^ 3
+	local s = sRoot ^ 3
+
+	local red = l * 4.0767416621 - m * 3.3077115913 + s * 0.2309699292
+	local green = l * -1.2684380046 + m * 2.6097574011 - s * 0.3413193965
+	local blue = l * -0.0041960863 - m * 0.7034186147 + s * 1.7076147010
+
+	if not unclamped then
+		red = math.clamp(red, 0, 1)
+		green = math.clamp(green, 0, 1)
+		blue = math.clamp(blue, 0, 1)
+	end
+
+	return Color3.new(red, green, blue)
+end
+
+-- Converts a Vector3 in Oklab space to a Color3 in sRGB space.
+-- The Color3 will be clamped by default unless specified otherwise.
+function Oklab.toSRGB(lab: Vector3, unclamped: boolean?): Color3
+	return sRGB.fromLinear(Oklab.toLinear(lab, unclamped))
+end
+
+return Oklab

package/runtime/Fusion/_impl/Colour/sRGB.luau

@@ -0,0 +1,47 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+    Provides transformation functions for converting linear RGB values
+    into sRGB values.
+
+    RGB color channel transformations are outlined here:
+    https://bottosson.github.io/posts/colorwrong/#what-can-we-do%3F
+]]
+
+local sRGB = {}
+
+-- Equivalent to f_inv. Takes a linear sRGB channel and returns
+-- the sRGB channel
+local function transform(channel: number): number
+    if channel < 0.04045 then
+        return channel / 12.92
+    end
+
+    return ((channel + 0.055) / 1.055) ^ 2.4
+end
+
+-- Equivalent to f. Takes an sRGB channel and returns
+-- the linear sRGB channel
+local function inverse(channel: number): number
+    if channel < 0.0031308 then
+        return 12.92 * channel
+    end
+
+    return (1.055 * channel ^ (1 / 2.4)) - 0.055
+end
+
+-- Uses a transformation to convert linear RGB into sRGB.
+function sRGB.fromLinear(rgb: Color3): Color3
+    return Color3.new(inverse(rgb.R), inverse(rgb.G), inverse(rgb.B))
+end
+
+-- Converts an sRGB into linear RGB using a
+-- (The inverse of sRGB.fromLinear).
+function sRGB.toLinear(srgb: Color3): Color3
+    return Color3.new(transform(srgb.R), transform(srgb.G), transform(srgb.B))
+end
+
+return sRGB