cluaupp 0.1.0

package/runtime/Janitor/init.luau

@@ -0,0 +1,45 @@
+--!strict
+-- Cluaupp Janitor — typed border. Engine: howmanysmall/Janitor (_impl).
+-- Requires the sibling CluauppLibs.Promise module, never a nested stub.
+
+--[=[
+	@class Janitor
+	Cleans up connections, instances, promises, and threads.
+]=]
+
+local PromiseMod = require(script.Parent.Promise)
+type Promise<T...> = PromiseMod.Promise<T...>
+
+local Impl = require(script._impl)
+
+export type Janitor = {
+	CurrentlyCleaning: boolean,
+	SuppressInstanceReDestroy: boolean,
+	UnsafeThreadCleanup: boolean,
+	Add: <T>(self: Janitor, object: T, methodName: (boolean | string)?, index: string?) -> T,
+	AddObject: <T, A...>(
+		self: Janitor,
+		constructor: { new: (A...) -> T },
+		methodName: (boolean | string)?,
+		index: string?,
+		A...
+	) -> T,
+	AddPromise: <T...>(self: Janitor, promiseObject: Promise<T...>, index: string?) -> Promise<T...>,
+	Remove: (self: Janitor, index: string) -> Janitor,
+	RemoveNoClean: (self: Janitor, index: string) -> Janitor,
+	RemoveList: (self: Janitor, ...string) -> Janitor,
+	Get: <T>(self: Janitor, index: string) -> T?,
+	GetAll: (self: Janitor) -> { [string]: unknown },
+	Has: (self: Janitor, index: string) -> boolean,
+	Cleanup: (self: Janitor) -> (),
+	Destroy: (self: Janitor) -> (),
+	LinkToInstance: (self: Janitor, object: Instance, allowMultiple: boolean?) -> RBXScriptConnection,
+	LinkToInstances: (self: Janitor, ...Instance) -> Janitor,
+}
+
+type JanitorStatic = {
+	new: () -> Janitor,
+	Is: (value: unknown) -> boolean,
+}
+
+return Impl :: JanitorStatic

package/runtime/MathUtils/init.luau

@@ -0,0 +1,100 @@
+--!strict
+--[=[
+	@class MathUtils
+	Numbers and vectors used in gameplay: lerp, map, clamp, angles.
+]=]
+local MathUtils = {}
+
+--[=[
+	@within MathUtils
+]=]
+function MathUtils.Lerp(a: number, b: number, alpha: number): number
+	return a + (b - a) * alpha
+end
+
+--[=[
+	@within MathUtils
+	Remap `value` from [inMin, inMax] into [outMin, outMax].
+]=]
+function MathUtils.Map(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number
+	if inMax == inMin then
+		return outMin
+	end
+	return outMin + (outMax - outMin) * ((value - inMin) / (inMax - inMin))
+end
+
+--[=[
+	@within MathUtils
+]=]
+function MathUtils.Clamp(value: number, min: number, max: number): number
+	if value < min then
+		return min
+	elseif value > max then
+		return max
+	end
+	return value
+end
+
+--[=[
+	@within MathUtils
+]=]
+function MathUtils.Round(value: number, digits: number?): number
+	local places = digits or 0
+	local m = 10 ^ places
+	return math.floor(value * m + 0.5) / m
+end
+
+--[=[
+	@within MathUtils
+	Shortest signed difference from `a` to `b` in radians.
+]=]
+function MathUtils.AngleDiff(a: number, b: number): number
+	local diff = (b - a + math.pi) % (math.pi * 2) - math.pi
+	return diff
+end
+
+--[=[
+	@within MathUtils
+]=]
+function MathUtils.LerpAngle(a: number, b: number, alpha: number): number
+	return a + MathUtils.AngleDiff(a, b) * alpha
+end
+
+--[=[
+	@within MathUtils
+]=]
+function MathUtils.Random(min: number, max: number): number
+	return min + math.random() * (max - min)
+end
+
+--[=[
+	@within MathUtils
+	@param weights {number}
+	@return number -- 1-based index
+]=]
+function MathUtils.Weighted(weights: { number }): number
+	local total = 0
+	for _, w in weights do
+		total += w
+	end
+	local pick = math.random() * total
+	local acc = 0
+	for index, w in weights do
+		acc += w
+		if pick <= acc then
+			return index
+		end
+	end
+	return #weights
+end
+
+--[=[
+	@within MathUtils
+]=]
+function MathUtils.LerpVector(a: Vector3, b: Vector3, alpha: number): Vector3
+	return a:Lerp(b, alpha)
+end
+
+export type MathUtils = typeof(MathUtils)
+
+return MathUtils

package/runtime/Module3D/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 TheNexusAvenger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/runtime/Module3D/_impl/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 TheNexusAvenger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/runtime/Module3D/_impl/init.luau

@@ -0,0 +1,269 @@
+--[[
+TheNexusAvenger
+Adorns a 3D model to a frame.
+GitHub: https://github.com/TheNexusAvenger/Module3D
+
+
+
+Module3D.new(Model): Module3D
+    Creates a Model3D object.
+Module3D:Attach3D(Frame: Frame, Model: BasePart | Model): Module3D
+    Attaches a model or part to a frame. Returns a Model3D object.
+    Does not use a clone of the model so it can be referenced directly.
+
+
+
+Model3D object (extends ViewportFrame):
+    Model3D.Object3D: Model - the model for the bounding box. If the input model was a model, it will be the same as the input.
+    Model3D.AdornFrame: ViewportCFrame - the frame the model is adorned to.
+    Model3D.Camera: Camera - the camera used by the viewport frame.
+        [Deprecated; use Model3D.CurrentCamera]
+    
+    Model3D:Update(): ()
+        Force updates the camera CFrame.
+    Model3D:SetActive(Active: boolean): ()
+        [Deprecated, use Model3D.Visible]
+        Sets the frame being active.
+    Model3D:GetActive(): boolean
+        [Deprecated, use Model3D.Visible]
+        Reutrns if the frame is active.
+    Model3D:SetCFrame(NewCFrame: CFrame): ()
+        Sets the CFrame offset.
+        Automatically updates the camera CFrame.
+    Model3D:GetCFrame(): CFrame
+        Returns the CFrame offset.
+    Model3D:SetDepthMultiplier(Multiplier: number): ()
+        Sets the multiplier for how far back the camera should go.
+        Automatically updates the camera CFrame.
+    Model3D:GetDepthMultiplier(): number
+        Returns the depth multiplier
+    Model3D:End(): ()
+        [Deprecated, use Model3D:Destroy()]
+        Destroys the frame and unparents the model.
+--]]
+--!strict
+
+--Position to move the part/model to. Used to ensure the physics don't interact with the game.
+local FAR_POSITION = Vector3.new(0, 10000, 0)
+
+
+
+local Module3D = {}
+Module3D.__index = Module3D
+
+export type Module3D = {
+    CFrameOffset: CFrame,
+    DepthMultiplier: number,
+    Object3D: Model,
+    AdornFrame: ViewportFrame,
+    Camera: Camera,
+} & typeof(setmetatable({}, Module3D)) & ViewportFrame
+
+
+
+--[[
+Creates a Model3D object.
+--]]
+function Module3D.new(ModelOrPart: BasePart | Model): Module3D
+    local self = {
+        CFrameOffset = CFrame.new(),
+        DepthMultiplier = 1,
+    }
+    self.Object3D = ModelOrPart :: Model
+    
+    --If the model is a BasePart, make it a model.
+    if ModelOrPart:IsA("BasePart") then
+        local NewModel = Instance.new("Model")
+        NewModel.Name = "Model3D"
+        ModelOrPart.Parent = NewModel
+        NewModel.PrimaryPart = ModelOrPart
+        
+        self.Object3D = NewModel
+    end
+    local Model = self.Object3D :: Model
+    
+    --Create the viewport frame.
+    local ViewportFrame = Instance.new("ViewportFrame")
+    ViewportFrame.BackgroundTransparency = 1
+    self.AdornFrame = ViewportFrame
+    
+    --Create the camera.
+    local Camera = Instance.new("Camera")
+    Camera.Parent = ViewportFrame
+    ViewportFrame.CurrentCamera = Camera
+    
+    --Set up the model.
+    local BasePrimaryPart = Model.PrimaryPart
+    if not BasePrimaryPart then
+        Model.PrimaryPart = Model:FindFirstChildWhichIsA("BasePart",true)
+    end
+    
+    --If a primary part exists, move the model.
+    if Model.PrimaryPart then
+        Model:PivotTo(CFrame.new(FAR_POSITION - Model.PrimaryPart.Position) * Model.PrimaryPart.CFrame)
+        Model.PrimaryPart = BasePrimaryPart
+    end
+    Model.Parent = ViewportFrame
+    
+    --Create and set the object metatable.
+    local Metatable = {}
+    setmetatable(self, Metatable)
+    Metatable.__index = function(self, Index: string): any
+        --Return the camera (deprecated property).
+        if Index == "Camera" then
+            warn("Module3D.Camera is deprecated. Use Module3D.CurrentCamera instead.")
+            return ViewportFrame.CurrentCamera
+        end
+        
+        --Return the object value.
+        local ObjectValue = rawget(Module3D :: any, Index)
+        if ObjectValue ~= nil then
+            return ObjectValue
+        end
+        local ClassValue = rawget(Module3D :: any, Index)
+        if ClassValue ~= nil then
+            return ClassValue
+        end
+        
+        --Return the frame's value.
+        return (ViewportFrame :: any)[Index]
+    end
+    Metatable.__newindex = function(self, Index: string, NewValue: any)
+        if rawget(self :: any, Index) ~= nil then
+            return
+        end
+        (ViewportFrame :: any)[Index] = NewValue
+    end
+    
+    self:UpdateCFrame()
+    return (self :: any) :: Module3D
+end
+
+--[[
+Updates the camera's CFrame.
+--]]
+function Module3D.UpdateCFrame(self: Module3D): ()
+    local BoundingCFrame,BoundingSize = self.Object3D:GetBoundingBox()
+    local ModelCenter = BoundingCFrame.Position
+    
+    --Determine the distance back.
+    local MaxSize = math.max(BoundingSize.X, BoundingSize.Y, BoundingSize.Z)
+    local CurrentCamera = self.CurrentCamera :: Camera
+    local DistanceBack = ((MaxSize / math.tan(math.rad(CurrentCamera.FieldOfView)))) * self.DepthMultiplier
+    local Center = CFrame.new(ModelCenter)
+    CurrentCamera.CFrame = Center * self.CFrameOffset * CFrame.new(0, 0, (MaxSize / 2) + DistanceBack)
+    CurrentCamera.Focus = Center
+end
+
+--[[
+Force updates the camera CFrame.
+--]]
+function Module3D.Update(self: Module3D): ()
+    self:UpdateCFrame()
+end
+
+--[[
+Sets the frame being active.
+--]]
+function Module3D.SetActive(self: Module3D, Active: boolean): ()
+    warn("Module3D:SetActive(Active) is deprecated. Use Module3D.Visible instead.")
+    self.AdornFrame.Visible = Active
+end
+
+--[[
+Reutrns if the frame is active.
+--]]
+function Module3D.GetActive(self: Module3D): boolean
+    warn("Module3D:GetActive() is deprecated. Use Module3D.Visible instead.")
+    return self.AdornFrame.Visible
+end
+
+--[[
+Sets the CFrame offset.
+--]]
+function Module3D.SetCFrame(self: Module3D, NewCFrame: CFrame): ()
+    self.CFrameOffset = NewCFrame
+    self:UpdateCFrame()
+end
+
+--[[
+Returns the CFrame offset.
+--]]
+function Module3D.GetCFrame(self: Module3D): CFrame
+    return self.CFrameOffset
+end
+
+--[[
+Sets the multiplier for how far back the camera should go.
+--]]
+function Module3D.SetDepthMultiplier(self: Module3D, Multiplier: number): ()
+    self.DepthMultiplier = Multiplier
+    self:UpdateCFrame()
+end
+
+--[[
+Returns the depth multiplier
+--]]
+function Module3D.GetDepthMultiplier(self: Module3D): number
+    return self.DepthMultiplier
+end
+
+--[[
+Destroys the frame and unparents the model.
+--]]
+function Module3D.Destroy(self: Module3D): ()
+    self.AdornFrame:Destroy()
+    self.Object3D:Destroy()
+end
+
+--[[
+Destroys the frame and unparents the model.
+--]]
+function Module3D.End(self: Module3D): ()
+    warn("Module3D:End() is deprecated. Use Module3D:Destroy() instead.")
+    self:Destroy()
+end
+
+--[[
+Adorns a 3D model to a frame.
+Returns a Model3D object.
+--]]
+function Module3D.Attach3D(self: typeof(Module3D), Frame: Frame, Model: BasePart | Model): Module3D
+    --Create the Model3D object.
+    local Model3D = Module3D.new(Model)
+    Model3D.AnchorPoint = Vector2.new(0.5, 0.5)
+    Model3D.Position = UDim2.new(0.5, 0, 0.5, 0)
+    Model3D.Visible = false
+    Model3D.Parent = Frame
+
+    --[[
+    Updates the frame size.
+    --]]
+    local function UpdateFrameSize()
+        local AbsoluteSize = Frame.AbsoluteSize
+        local MinSize = math.abs(math.min(AbsoluteSize.X, AbsoluteSize.Y)) 
+        Model3D.AdornFrame.Size = UDim2.new(0, MinSize, 0, MinSize)
+    end
+    local FrameChanged = Frame.Changed:Connect(UpdateFrameSize)
+    UpdateFrameSize()
+
+    --Override the destroy method to disconnect the events.
+    local BaseDestroy = Model3D.Destroy
+    local function NewDestroy(self: Module3D)
+        BaseDestroy(self)
+        
+        --Disconnect the resize event.
+        if FrameChanged then
+            FrameChanged:Disconnect()
+            FrameChanged = nil :: any
+        end
+    end
+    rawset(Model3D, "Destroy", NewDestroy)
+
+    --Return the Model3D.
+    return Model3D
+end
+
+
+
+return Module3D

package/runtime/Module3D/init.luau

@@ -0,0 +1,14 @@
+--!strict
+-- Cluaupp Module3D — typed border over TheNexusAvenger/Module3D (_impl).
+
+--[=[
+	@class Module3D
+	Adorn a 3D model to a GuiObject via ViewportFrame.
+]=]
+
+local Impl = require(script._impl)
+
+export type Module3D = Impl.Module3D
+export type Model3D = Impl.Module3D
+
+return Impl

package/runtime/Net/init.luau

@@ -0,0 +1,125 @@
+--!strict
+--[=[
+	@class Net
+	Buffer-packed RemoteEvent / RemoteFunction. Public API is generic; the codec is internal.
+]=]
+local RunService = game:GetService("RunService")
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local codec = require(script.src.codec)
+
+export type Event<T...> = {
+	Fire: (self: Event<T...>, player: Player, T...) -> (),
+	FireAll: (self: Event<T...>, T...) -> (),
+	FireServer: (self: Event<T...>, T...) -> (),
+	On: (self: Event<T...>, callback: (Player?, T...) -> ()) -> RBXScriptConnection,
+}
+
+export type Function<R, T...> = {
+	On: (self: Function<R, T...>, callback: (Player?, T...) -> R) -> (),
+	Invoke: (self: Function<R, T...>, player: Player, T...) -> R,
+	InvokeServer: (self: Function<R, T...>, T...) -> R,
+}
+
+local function folder(): Folder
+	local existing = ReplicatedStorage:FindFirstChild("CluauppNet")
+	if existing and existing:IsA("Folder") then
+		return existing
+	end
+	local created = Instance.new("Folder")
+	created.Name = "CluauppNet"
+	created.Parent = ReplicatedStorage
+	return created
+end
+
+local function remote(kind: "RemoteEvent" | "RemoteFunction", name: string): Instance
+	local parent = folder()
+	local existing = parent:FindFirstChild(name)
+	if existing then
+		return existing
+	end
+	if RunService:IsServer() then
+		local inst = Instance.new(kind)
+		inst.Name = name
+		inst.Parent = parent
+		return inst
+	end
+	return parent:WaitForChild(name)
+end
+
+local Event = {}
+Event.__index = Event
+
+function Event.new<T...>(name: string): Event<T...>
+	return setmetatable({ _name = name, _remote = remote("RemoteEvent", name) :: RemoteEvent }, Event) :: Event<T...>
+end
+
+function Event:Fire<T...>(player: Player, ...: T...)
+	assert(RunService:IsServer(), "Net.Event:Fire is server-only")
+	self._remote:FireClient(player, codec.encode({ ... }))
+end
+
+function Event:FireAll<T...>(...: T...)
+	assert(RunService:IsServer(), "Net.Event:FireAll is server-only")
+	self._remote:FireAllClients(codec.encode({ ... }))
+end
+
+function Event:FireServer<T...>(...: T...)
+	assert(RunService:IsClient(), "Net.Event:FireServer is client-only")
+	self._remote:FireServer(codec.encode({ ... }))
+end
+
+function Event:On<T...>(callback: (Player?, T...) -> ()): RBXScriptConnection
+	if RunService:IsServer() then
+		return self._remote.OnServerEvent:Connect(function(player: Player, payload: buffer)
+			callback(player, table.unpack(codec.decode(payload)))
+		end)
+	end
+	return self._remote.OnClientEvent:Connect(function(payload: buffer)
+		callback(nil, table.unpack(codec.decode(payload)))
+	end)
+end
+
+local Fn = {}
+Fn.__index = Fn
+
+function Fn.new<R, T...>(name: string): Function<R, T...>
+	return setmetatable({ _name = name, _remote = remote("RemoteFunction", name) :: RemoteFunction }, Fn) :: Function<R, T...>
+end
+
+function Fn:On<R, T...>(callback: (Player?, T...) -> R)
+	if RunService:IsServer() then
+		self._remote.OnServerInvoke = function(player: Player, payload: buffer)
+			return codec.encode({ callback(player, table.unpack(codec.decode(payload))) })
+		end
+	else
+		self._remote.OnClientInvoke = function(payload: buffer)
+			return codec.encode({ callback(nil, table.unpack(codec.decode(payload))) })
+		end
+	end
+end
+
+function Fn:Invoke<R, T...>(player: Player, ...: T...): R
+	assert(RunService:IsServer(), "Net.Function:Invoke is server-only")
+	local reply = self._remote:InvokeClient(player, codec.encode({ ... }))
+	return table.unpack(codec.decode(reply)) :: R
+end
+
+function Fn:InvokeServer<R, T...>(...: T...): R
+	assert(RunService:IsClient(), "Net.Function:InvokeServer is client-only")
+	local reply = self._remote:InvokeServer(codec.encode({ ... }))
+	return table.unpack(codec.decode(reply)) :: R
+end
+
+local Net = {}
+
+function Net.Event<T...>(name: string): Event<T...>
+	return Event.new(name)
+end
+
+function Net.Function<R, T...>(name: string): Function<R, T...>
+	return Fn.new(name)
+end
+
+export type Net = typeof(Net)
+
+return Net