ReplicatedTweening.lua

local TweenService = game:GetService("TweenService")

--[=[
	@class ReplicatedTweening
	
	A lightweight tween manager.  
	Each instance of ReplicatedTweening manages its own tweens.

	Usage:

	local ReplicatedTweening = require(game:GetService("ReplicatedStorage").ReplicatedTweening)

	local tweener = ReplicatedTweening.new()

	local part = Instance.new("Part", workspace)
	local info = TweenInfo.new(1, Enum.EasingStyle.Quad, Enum.EasingDirection.Out)
	local goal = { Position = Vector3.new(0, 10, 0) }

	-- Runs immediately
	tweener:Run(part, info, goal)

	-- Queues behind existing tweens
	tweener:Queue(part, info, { Position = Vector3.new(0, 20, 0) })

	-- Pause, Resume (via Run/Queue), Stop
	tweener:Pause(part)
	tweener:Stop(part)

	-- Clean up all tweens managed by this instance
	tweener:Destroy()
]=]

local ReplicatedTweening = {}
ReplicatedTweening.ClassName = "ReplicatedTweening"
ReplicatedTweening.__index = ReplicatedTweening

--[=[
	Creates a new ReplicatedTweening instance.
	
	Each instance manages its own active tweens, queue timing state and cleanup lifecycle  
]=]
function ReplicatedTweening.new()
	return setmetatable({
		_nextAllowedTime = {},
		_activeTweens = {},
		_destroyed = false,
	}, ReplicatedTweening)
end

function ReplicatedTweening:_ensureNotDestroyed()
	if self._destroyed then
		error("ReplicatedTweening: Attempted to use after Destroy()", 2)
	end
end

--[=[
	Converts a TweenInfo object into a serializable table.  
	This mirrors the original system ReplicatedTweening was based on.  
]=]
function ReplicatedTweening.TweenInfoToTable(info)
	return {
		info.Time or 1,
		info.EasingStyle or Enum.EasingStyle.Quad,
		info.EasingDirection or Enum.EasingDirection.Out,
		info.RepeatCount or 0,
		info.Reverses or false,
		info.DelayTime or 0,
	}
end

--[=[
	Converts a previously generated table back into TweenInfo.
]=]
function ReplicatedTweening.TableToTweenInfo(tbl)
	return TweenInfo.new(unpack(tbl))
end

--[=[
	Internal tween runner.
]=]
function ReplicatedTweening:_runList(list, queued)
	self:_ensureNotDestroyed()

	for _, entry in pairs(list) do
		coroutine.wrap(function()
			local instance = entry[1]
			local tweenInfo = entry[2]
			local goal = entry[3]

			if not instance then return end

			local nextAllowed = self._nextAllowedTime[instance] or os.time()
			self._nextAllowedTime[instance] = nextAllowed

			local previousTime = nextAllowed

			if queued then
				if os.time() <= previousTime then
					local waitTime = previousTime - os.time()

					self._nextAllowedTime[instance] =
						os.time() + tweenInfo.Time + waitTime

					previousTime = self._nextAllowedTime[instance]

					wait(waitTime)
				end
			end

			self._nextAllowedTime[instance] = os.time() + tweenInfo.Time

			local existing = self._activeTweens[instance]
			if existing then
				existing:Cancel()
			end

			local tween = TweenService:Create(instance, tweenInfo, goal)
			self._activeTweens[instance] = tween
			tween:Play()

			wait(tweenInfo.Time or 1)

			if self._nextAllowedTime[instance] == previousTime then
				self._nextAllowedTime[instance] = nil
			end

			if self._activeTweens[instance] == tween then
				self._activeTweens[instance] = nil
			end
		end)()
	end
end

--[=[
	Starts a tween immediately, canceling any existing tween on the same instance.

	tweener:Run(part, TweenInfo.new(1), {Transparency = 0})
]=]
function ReplicatedTweening:Run(instance, tweenInfo, goal)
	self:_ensureNotDestroyed()
	self:_runList({
		{ instance, tweenInfo, goal }
	})
end

--[=[
	Queues the tween so it will run *after* any currently running tween
	for the same instance.

	tweener:Queue(part, TweenInfo.new(1), { Size = Vector3.new(5,5,5) })
]=]
function ReplicatedTweening:Queue(instance, tweenInfo, goal)
	self:_ensureNotDestroyed()
	self:_runList({
		{ instance, tweenInfo, goal }
	}, true)
end

--[=[
	Pauses the currently active tween on the given instance.
]=]
function ReplicatedTweening:Pause(instance)
	self:_ensureNotDestroyed()
	local tween = self._activeTweens[instance]
	if tween then
		tween:Pause()
	end
end

--[=[
	Stops the currently active tween on the given instance and removes it
	from management.

	tweener:Stop(part)
]=]
function ReplicatedTweening:Stop(instance)
	self:_ensureNotDestroyed()
	local tween = self._activeTweens[instance]
	if tween then
		tween:Cancel()
		self._activeTweens[instance] = nil
	end
end

--[=[
	Cleans up all tweens managed by this ReplicatedTweening instance.

	This does NOT destroy any Roblox instances, just running tweens.

	tweener:Destroy()
]=]
function ReplicatedTweening:Destroy()
	if self._destroyed then return end
	self._destroyed = true

	for _, tween in pairs(self._activeTweens) do
		tween:Cancel()
	end

	self._nextAllowedTime = {}
	self._activeTweens = {}
end

return ReplicatedTweening