cluaupp 1.5.0 → 1.5.1

package/examples/game/libs/Stage/init.luau

@@ -0,0 +1,178 @@
+--!native
+--!optimize 2
+--!strict
+-- Stage — ViewportFrame 3D (Module3D successor).
+
+local Sweep = require(script.Parent.Sweep)
+
+local Stage = {}
+Stage.__index = Stage
+
+export type Stage = typeof(setmetatable(
+	{} :: {
+		Object3D: Model,
+		AdornFrame: GuiObject,
+		Camera: Camera,
+		Visible: boolean,
+		Viewport: ViewportFrame,
+		World: WorldModel,
+	},
+	Stage
+))
+
+local function wrapModel(source: Instance): Model
+	local clone = source:Clone()
+	if clone:IsA("Model") then
+		if clone.PrimaryPart == nil then
+			clone.PrimaryPart = clone:FindFirstChildWhichIsA("BasePart", true)
+		end
+		return clone
+	end
+	local wrap = Instance.new("Model")
+	wrap.Name = clone.Name
+	clone.Parent = wrap
+	if clone:IsA("BasePart") then
+		wrap.PrimaryPart = clone
+	else
+		wrap.PrimaryPart = wrap:FindFirstChildWhichIsA("BasePart", true)
+	end
+	return wrap
+end
+
+local function fit(model: Model): (Vector3, number)
+	local cf, size = model:GetBoundingBox()
+	local extent = math.max(size.X, size.Y, size.Z)
+	return cf.Position, math.max(extent, 1)
+end
+
+local function distance(extent: number, camera: Camera, depth: number): number
+	local fov = math.rad(camera.FieldOfView)
+	local half = math.tan(fov * 0.5)
+	if half <= 1e-4 then
+		half = 1e-4
+	end
+	return ((extent * 0.5) / half) * 1.25 * math.max(depth, 0.05)
+end
+
+local function look(self: any)
+	local model = self.Object3D
+	if not model or not model.Parent then
+		return
+	end
+	local center, extent = fit(model)
+	self._center = center
+	local dist = distance(extent, self.Camera, self._depth or 1)
+	local relative: CFrame = self._relative or CFrame.identity
+	local offset = relative:VectorToWorldSpace(Vector3.new(0, extent * 0.12, dist))
+	self.Camera.CFrame = CFrame.lookAt(center + offset, center)
+end
+
+function Stage.Attach(frame: GuiObject, model: Instance): Stage
+	local viewport = Instance.new("ViewportFrame")
+	viewport.Name = "Stage"
+	viewport.Size = UDim2.fromScale(1, 1)
+	viewport.BackgroundTransparency = 1
+	viewport.Ambient = Color3.fromRGB(186, 186, 186)
+	viewport.LightColor = Color3.fromRGB(255, 255, 255)
+	viewport.LightDirection = Vector3.new(-1, -1, -1)
+	viewport.Parent = frame
+
+	local camera = Instance.new("Camera")
+	camera.FieldOfView = 70
+	camera.Parent = viewport
+	viewport.CurrentCamera = camera
+
+	local world = Instance.new("WorldModel")
+	world.Name = "StageWorld"
+	world.Parent = viewport
+
+	local clone = wrapModel(model)
+	clone.Parent = world
+
+	local sweep = Sweep.new()
+	sweep:Add(viewport)
+	sweep:LinkToInstance(frame)
+
+	local self = setmetatable({
+		Object3D = clone,
+		AdornFrame = frame,
+		Camera = camera,
+		Visible = true,
+		Viewport = viewport,
+		World = world,
+		_depth = 1,
+		_relative = CFrame.identity,
+		_orbit = 0,
+		_center = Vector3.zero,
+		_sweep = sweep,
+	}, Stage)
+	look(self)
+	return self
+end
+
+Stage.new = function(model: Instance): Stage
+	local holder = Instance.new("Frame")
+	holder.Name = "Stage"
+	holder.Size = UDim2.fromScale(1, 1)
+	holder.BackgroundTransparency = 1
+	return Stage.Attach(holder, model)
+end
+
+function Stage:SetCFrame(newCF: CFrame)
+	self._relative = newCF
+	self._orbit = 0
+	if self.Visible then
+		look(self)
+	end
+end
+
+function Stage:GetCFrame(): CFrame
+	return self._relative or CFrame.identity
+end
+
+function Stage:SetDepthMultiplier(multiplier: number)
+	self._depth = multiplier
+	if self.Visible then
+		look(self)
+	end
+end
+
+function Stage:GetDepthMultiplier(): number
+	return self._depth or 1
+end
+
+function Stage:SetActive(active: boolean)
+	self.Viewport.Visible = active
+	self.Visible = active
+end
+
+function Stage:GetActive(): boolean
+	return self.Visible
+end
+
+function Stage:Update(dt: number?)
+	if not self.Visible then
+		return
+	end
+	if typeof(dt) == "number" then
+		self._orbit += dt
+		self._relative = CFrame.Angles(0, self._orbit, 0)
+	end
+	look(self)
+end
+
+function Stage:Destroy()
+	local sweep = self._sweep
+	if sweep then
+		sweep:Destroy()
+		self._sweep = nil
+	elseif self.Viewport then
+		self.Viewport:Destroy()
+	end
+	self.Visible = false
+end
+
+Stage.End = Stage.Destroy
+Stage.Attach3D = Stage.Attach
+
+return Stage

package/examples/game/libs/Sweep/init.luau

@@ -0,0 +1,259 @@
+--!native
+--!optimize 2
+--!strict
+-- Sweep — Cluaupp zelador. Flare sends; Sweep clears.
+-- Auto-detects Disconnect / Destroy / task.cancel / call / Promise cancel.
+-- Indexed Add replaces and cleans the previous task.
+
+local Sweep = {}
+Sweep.__index = Sweep
+
+export type Sweep = typeof(setmetatable(
+	{} :: {
+		CurrentlyCleaning: boolean,
+		_frozen: boolean,
+		_tasks: { any },
+		_methods: { any },
+		_indices: { [any]: number },
+		_links: { RBXScriptConnection },
+	},
+	Sweep
+))
+
+local function typeofOk(value: any): string
+	return typeof(value)
+end
+
+local function cleanupOne(object: any, method: any)
+	if object == nil then
+		return
+	end
+	local kind = typeofOk(object)
+	if method == true or typeofOk(method) == "function" then
+		local fn = if typeofOk(method) == "function" then method else object
+		if typeofOk(fn) == "function" then
+			fn()
+		end
+		return
+	end
+	if typeofOk(method) == "string" then
+		local fn = object[method]
+		if typeofOk(fn) == "function" then
+			if method == "Destroy" and kind == "Instance" then
+				pcall(fn, object)
+			else
+				fn(object)
+			end
+		end
+		return
+	end
+	if kind == "RBXScriptConnection" then
+		if object.Connected then
+			object:Disconnect()
+		end
+		return
+	end
+	if kind == "Instance" then
+		pcall(function()
+			(object :: Instance):Destroy()
+		end)
+		return
+	end
+	if kind == "thread" then
+		pcall(task.cancel, object)
+		return
+	end
+	if kind == "function" then
+		object()
+		return
+	end
+	if kind == "table" then
+		if typeofOk(object.Cancel) == "function" and object.getStatus then
+			pcall(object.Cancel, object)
+			return
+		end
+		if typeofOk(object.Destroy) == "function" then
+			object:Destroy()
+			return
+		end
+		if typeofOk(object.Disconnect) == "function" then
+			object:Disconnect()
+			return
+		end
+		if typeofOk(object.DisconnectAll) == "function" then
+			object:DisconnectAll()
+		end
+	end
+end
+
+local function detect(object: any): any
+	local kind = typeofOk(object)
+	if kind == "RBXScriptConnection" then
+		return "Disconnect"
+	end
+	if kind == "Instance" then
+		return "Destroy"
+	end
+	if kind == "thread" then
+		return true
+	end
+	if kind == "function" then
+		return true
+	end
+	if kind == "table" then
+		if typeofOk(object.Cancel) == "function" and object.getStatus then
+			return "Cancel"
+		end
+		if typeofOk(object.Destroy) == "function" then
+			return "Destroy"
+		end
+		if typeofOk(object.Disconnect) == "function" then
+			return "Disconnect"
+		end
+		if typeofOk(object.DisconnectAll) == "function" then
+			return "DisconnectAll"
+		end
+	end
+	return "Destroy"
+end
+
+function Sweep.new(): Sweep
+	return setmetatable({
+		CurrentlyCleaning = false,
+		_frozen = false,
+		_tasks = {},
+		_methods = {},
+		_indices = {},
+		_links = {},
+	}, Sweep)
+end
+
+function Sweep:Add<T>(object: T, methodName: (boolean | string)?, index: any?): T
+	if self._frozen or self.CurrentlyCleaning then
+		return object
+	end
+	local method: any = methodName
+	if method == nil then
+		method = detect(object)
+	end
+	if index ~= nil then
+		local previous = self._indices[index]
+		if previous then
+			local oldObject = self._tasks[previous]
+			local oldMethod = self._methods[previous]
+			self._tasks[previous] = nil
+			self._methods[previous] = nil
+			self._indices[index] = nil
+			cleanupOne(oldObject, oldMethod)
+		end
+		table.insert(self._tasks, object)
+		table.insert(self._methods, method)
+		self._indices[index] = #self._tasks
+		return object
+	end
+	table.insert(self._tasks, object)
+	table.insert(self._methods, method)
+	return object
+end
+
+function Sweep:Remove(index: any): Sweep
+	local slot = self._indices[index]
+	if not slot then
+		return self
+	end
+	local object = self._tasks[slot]
+	local method = self._methods[slot]
+	self._tasks[slot] = nil
+	self._methods[slot] = nil
+	self._indices[index] = nil
+	cleanupOne(object, method)
+	return self
+end
+
+function Sweep:RemoveNoClean(index: any): Sweep
+	local slot = self._indices[index]
+	if not slot then
+		return self
+	end
+	self._tasks[slot] = nil
+	self._methods[slot] = nil
+	self._indices[index] = nil
+	return self
+end
+
+function Sweep:Get(index: any): any
+	local slot = self._indices[index]
+	if not slot then
+		return nil
+	end
+	return self._tasks[slot]
+end
+
+function Sweep:Cleanup()
+	if self.CurrentlyCleaning then
+		return
+	end
+	self.CurrentlyCleaning = true
+	for i = #self._tasks, 1, -1 do
+		local object = self._tasks[i]
+		local method = self._methods[i]
+		self._tasks[i] = nil
+		self._methods[i] = nil
+		cleanupOne(object, method)
+	end
+	table.clear(self._indices)
+	self.CurrentlyCleaning = false
+end
+
+function Sweep:Destroy()
+	self:Cleanup()
+	self._frozen = true
+	for _, link in self._links do
+		if link.Connected then
+			link:Disconnect()
+		end
+	end
+	table.clear(self._links)
+end
+
+function Sweep:LinkToInstance(object: Instance, allowMultiple: boolean?): RBXScriptConnection
+	if self._frozen then
+		return (nil :: any)
+	end
+	if not allowMultiple then
+		self:Remove("LinkToInstance")
+	end
+	local function onGone()
+		self:Destroy()
+	end
+	local destroying = object.Destroying:Connect(onGone)
+	local ancestry = object.AncestryChanged:Connect(function(_, parent)
+		if parent == nil then
+			onGone()
+		end
+	end)
+	table.insert(self._links, destroying)
+	table.insert(self._links, ancestry)
+	if not allowMultiple then
+		self._indices["LinkToInstance"] = #self._links
+	end
+	return destroying
+end
+
+function Sweep.Is(value: any): boolean
+	return typeof(value) == "table" and getmetatable(value) == Sweep
+end
+
+Sweep.AddPromise = function(self: Sweep, promise: any, index: any?): any
+	return self:Add(promise, "Cancel", index)
+end
+
+Sweep.New = Sweep.new
+
+setmetatable(Sweep, {
+	__call = function()
+		return Sweep.new()
+	end,
+})
+
+return Sweep

package/examples/game/libs/Trace/init.luau

@@ -0,0 +1,213 @@
+--!optimize 2
+--!strict
+-- Trace — pretty-print values.
+
+local Trace = {}
+
+local DEFAULT_DEPTH = 4
+local DEFAULT_INDENT = "  "
+
+local function formatNumber(value: number): string
+	if value ~= value then
+		return "nan"
+	end
+	if value == math.huge then
+		return "inf"
+	end
+	if value == -math.huge then
+		return "-inf"
+	end
+	return tostring(value)
+end
+
+local function formatVector(prefix: string, ...: number): string
+	local parts = { prefix, "(" }
+	local count = select("#", ...)
+	for i = 1, count do
+		if i > 1 then
+			table.insert(parts, ", ")
+		end
+		table.insert(parts, formatNumber(select(i, ...)))
+	end
+	table.insert(parts, ")")
+	return table.concat(parts)
+end
+
+local function isArray(value: { [any]: any }): boolean
+	local count = 0
+	for key in value do
+		if typeof(key) ~= "number" or key ~= math.floor(key) or key < 1 then
+			return false
+		end
+		count += 1
+	end
+	return count == #value
+end
+
+local function formatValue(value: any, depth: number, maxDepth: number, indentWith: string, seen: { [any]: boolean }): string
+	local kind = typeof(value)
+	if kind == "string" then
+		return string.format("%q", value)
+	end
+	if kind == "number" then
+		return formatNumber(value)
+	end
+	if kind == "boolean" or kind == "nil" then
+		return tostring(value)
+	end
+	if kind == "Instance" then
+		local ok, fullName = pcall(function()
+			return value:GetFullName()
+		end)
+		if ok then
+			return `{value.ClassName}({fullName})`
+		end
+		return `{value.ClassName}({value.Name})`
+	end
+	if kind == "Vector3" then
+		return formatVector("Vector3", value.X, value.Y, value.Z)
+	end
+	if kind == "Vector2" then
+		return formatVector("Vector2", value.X, value.Y)
+	end
+	if kind == "Vector3int16" then
+		return formatVector("Vector3int16", value.X, value.Y, value.Z)
+	end
+	if kind == "Vector2int16" then
+		return formatVector("Vector2int16", value.X, value.Y)
+	end
+	if kind == "CFrame" then
+		local x, y, z, r00, r01, r02, r10, r11, r12, r20, r21, r22 = value:GetComponents()
+		return formatVector("CFrame", x, y, z, r00, r01, r02, r10, r11, r12, r20, r21, r22)
+	end
+	if kind == "Color3" then
+		return formatVector("Color3", value.R, value.G, value.B)
+	end
+	if kind == "UDim" then
+		return formatVector("UDim", value.Scale, value.Offset)
+	end
+	if kind == "UDim2" then
+		return formatVector("UDim2", value.X.Scale, value.X.Offset, value.Y.Scale, value.Y.Offset)
+	end
+	if kind == "Rect" then
+		return formatVector("Rect", value.Min.X, value.Min.Y, value.Max.X, value.Max.Y)
+	end
+	if kind == "NumberRange" then
+		return formatVector("NumberRange", value.Min, value.Max)
+	end
+	if kind == "BrickColor" then
+		return `BrickColor({string.format("%q", value.Name)})`
+	end
+	if kind == "EnumItem" then
+		return tostring(value)
+	end
+	if kind == "buffer" then
+		return `buffer({buffer.len(value)})`
+	end
+	if kind == "table" then
+		if seen[value] then
+			return "<circular>"
+		end
+		if depth >= maxDepth then
+			return "{...}"
+		end
+		seen[value] = true
+		local pad = string.rep(indentWith, depth)
+		local inner = string.rep(indentWith, depth + 1)
+		local parts = { "{" }
+		if isArray(value) then
+			if #value == 0 then
+				seen[value] = nil
+				return "{}"
+			end
+			for index, child in ipairs(value) do
+				table.insert(parts, `\n{inner}[{index}] = {formatValue(child, depth + 1, maxDepth, indentWith, seen)},`)
+			end
+		else
+			local keys = {}
+			for key in value do
+				table.insert(keys, key)
+			end
+			table.sort(keys, function(a, b)
+				if typeof(a) == "number" and typeof(b) == "number" then
+					return a < b
+				end
+				if typeof(a) == "string" and typeof(b) == "string" then
+					return a < b
+				end
+				return tostring(a) < tostring(b)
+			end)
+			if #keys == 0 then
+				seen[value] = nil
+				return "{}"
+			end
+			for _, key in keys do
+				table.insert(
+					parts,
+					`\n{inner}[{formatValue(key, depth + 1, maxDepth, indentWith, seen)}] = {formatValue(value[key], depth + 1, maxDepth, indentWith, seen)},`
+				)
+			end
+		end
+		table.insert(parts, `\n{pad}}`)
+		seen[value] = nil
+		return table.concat(parts)
+	end
+	return `{kind}({tostring(value)})`
+end
+
+local function stringify(value: any, level: number?, maxDepth: number?, indentWith: string?): string
+	return formatValue(value, level or 0, maxDepth or DEFAULT_DEPTH, indentWith or DEFAULT_INDENT, {})
+end
+
+function Trace.display(value: any, level: number?): string
+	return stringify(value, level, DEFAULT_DEPTH, DEFAULT_INDENT)
+end
+
+function Trace.Display(value: any, level: number?): string
+	return stringify(value, level, DEFAULT_DEPTH, DEFAULT_INDENT)
+end
+
+function Trace.Print(value: any)
+	print(Trace.Display(value))
+end
+
+Trace.Dump = Trace.Print
+
+function Trace.builder()
+	local maxDepth = DEFAULT_DEPTH
+	local indentWith = DEFAULT_INDENT
+	local builder = {}
+
+	function builder:MaxDepth(depth: number)
+		if typeof(depth) ~= "number" then
+			return self
+		end
+		maxDepth = math.max(0, depth)
+		return self
+	end
+
+	function builder:Indent(indent: string)
+		indentWith = indent
+		return self
+	end
+
+	function builder:Display(value: any, level: number?): string
+		return stringify(value, level, maxDepth, indentWith)
+	end
+
+	function builder:display(value: any, level: number?): string
+		return stringify(value, level, maxDepth, indentWith)
+	end
+
+	function builder:Print(value: any)
+		print(self:Display(value))
+	end
+
+	function builder:build()
+		return self
+	end
+
+	return builder
+end
+
+return Trace