beam transparency tween util module

beamTweenUtils.lua

local TweenService = game:GetService("TweenService")

local function lerp(a: number, b: number, t: number): number
	return a * (1 - t) + (b * t)
end

local function evalNS(sequence: NumberSequence, t: number): number
	if t == 0 then
		return sequence.Keypoints[1].Value
	end
	if t == 1 then
		return sequence.Keypoints[#sequence.Keypoints].Value
	end
	for i = 1, #sequence.Keypoints - 1 do
		local thisKp = sequence.Keypoints[i]
		local nextKp = sequence.Keypoints[i + 1]
		if t >= thisKp.Time and t < nextKp.Time then
			local alpha = (t - thisKp.Time) / (nextKp.Time - thisKp.Time)
			return (nextKp.Value - thisKp.Value) * alpha + thisKp.Value
		end
	end
	return 0
end

type AnimateNumberSequenceOptions = {
	from: NumberSequence,
	to: NumberSequence,
	tweenInfo: TweenInfo,
	onUpdate: (NumberSequence) -> nil,
}

local function animateNumberSequence(options: AnimateNumberSequenceOptions): Tween
	local from = options.from
	local to = options.to
	local tweenInfo = options.tweenInfo
	local onUpdate = options.onUpdate

	local function computeLerpedNumberSequence(alpha: number)
		local keypoints = {}
		local steps = math.max(#from.Keypoints, #to.Keypoints)
		for i = 1, steps do
			local t = (i - 1) / (steps - 1)
			local fromValue = evalNS(from, t)
			local toValue = evalNS(to, t)
			local lerpedKeypoint = NumberSequenceKeypoint.new(t, lerp(fromValue, toValue, alpha))
			table.insert(keypoints, lerpedKeypoint)
		end
		return NumberSequence.new(keypoints)
	end

	local value = Instance.new("NumberValue")
	value.Changed:Connect(function()
		onUpdate(computeLerpedNumberSequence(value.Value))
	end)

	local tween = TweenService:Create(value, tweenInfo, { Value = 1 })
	tween:Play()
	return tween
end

local function map(number: number, inMin: number, inMax: number, outMin: number, outMax: number): number
	return (number - inMin) * (outMax - outMin) / (inMax - inMin) + outMin
end

local function animateNumberSequenceSweep(options: AnimateNumberSequenceOptions): Tween
	local from = options.from
	local to = options.to
	local tweenInfo = options.tweenInfo
	local onUpdate = options.onUpdate

	local function computeLerpedNumberSequence(alpha: number)
		local keypoints = {}
		local steps = 15
		for i = 0, steps - 1 do
			local t = i / (steps - 1)
			local fromValue = evalNS(from, t)
			local toValue = evalNS(to, t)
			local lerpedKeypoint
			if t >= alpha then
				lerpedKeypoint = NumberSequenceKeypoint.new(t, 1)
			else
				local nextT = math.clamp((i + 5) / (steps - 1), 0, 1)
				local normalizedAlpha = math.clamp(map(alpha, t, nextT, 0, 1), 0, 1)
				lerpedKeypoint = NumberSequenceKeypoint.new(t, lerp(fromValue, toValue, normalizedAlpha))
			end
			table.insert(keypoints, lerpedKeypoint)
		end
		return NumberSequence.new(keypoints)
	end

	local value = Instance.new("NumberValue")
	value.Changed:Connect(function()
		onUpdate(computeLerpedNumberSequence(value.Value))
	end)

	local tween = TweenService:Create(value, tweenInfo, { Value = 1 })
	tween:Play()
	return tween
end

-- demo code
--[[
	task.spawn(function()
		local beams = {}
		for _, instance in workspace.TweenTest:GetDescendants() do
			if instance:IsA("Beam") then
				table.insert(beams, instance)
			end
		end

		while task.wait(4) do
			for _, beam in beams do
				animateNumberSequenceSweep({
					from = NumberSequence.new(1),
					to = beam.Transparency,
					tweenInfo = TweenInfo.new(3, Enum.EasingStyle.Linear, Enum.EasingDirection.InOut),
					onUpdate = function(sequence)
						beam.Transparency = sequence
					end,
				})
			end
		end
	end)
]]

return {
	animateNumberSequence = animateNumberSequence,
	animateNumberSequenceSweep = animateNumberSequenceSweep,
}