Objects

A misc library of useful non-specific composition objects. ClonableContainer deep-clones its children; Movable and Sizable are transform groupers that move or scale every child relative to that child's individual baseline.

local Objects = import("Objects")

local rack = Objects.Sizable()
rack:AddChild(crateA)
rack:AddChild(crateB)
rack.Size = Vector.new(0.5, 0.5, 0.5) -- crates shrink to half size

local copy = Objects.ClonableContainer()
copy:AddChild(playerModel)
local npc = copy:Clone()                -- new player with the same shaders / deformations

Shared behavior

All three container types share:

• Children added later don't see prior transforms. Adding a part to a container is a snapshot — the child's current position / size is left alone. Only subsequent moves / resizes after the add propagate as deltas. So if you shrink a container, then add a fresh child, then shrink again: the old child shrinks twice, the new child only once.
• Containers can nest. Movable can contain Movable / Sizable children; same for Sizable. Moving / scaling the outer container propagates recursively through inner containers down to the actual leaf BaseParts / GUI primitives. The only nesting that's forbidden is ClonableContainer inside ClonableContainer (you can put a Movable / Sizable inside a Clonable, but not another Clonable).
• Children are not destroyed when the container is. :Destroy() tears down the container's child list but leaves every child userdata alive. Pass a removeFn to :AddChild(child, removeFn) if you want a hook on destruction (gets called once with the child as its only argument).
• Type-locking. Movable and Sizable auto-detect 2D vs 3D from the first :AddChild call (including any nested container's leaf mode). After that, the wrong type errors on add. ClonableContainer happily mixes both.
• :GetChildren() returns a Lua array of every alive child as fresh userdata wrappers.
• :RemoveChild(child) detaches a child from the container's list. Returns true if found. Fires the child's removeFn callback if one was registered at :AddChild time. The child userdata itself is left alive.

Movable / Sizable: inherit-on-empty

When a Movable or Sizable is empty and you add a leaf (BasePart / GUI primitive) or a nested container that already has the right mode, the container adopts that child's state as its own:

• 3D Movable + first BasePart child: container's CFrame snaps to the part's CFrame. The next m.CFrame = X moves the part by exactly X - part.CFrame — no surprise jump from origin.
• 2D Movable + first GUI child: container's Position snaps to the primitive's Position.
• 3D Sizable + first BasePart child: container's Size snaps to the part's Size.
• 2D Sizable + first GUI child: container's Size snaps to the primitive's Size.

Inheritance only happens when the container is empty — later adds use the current container state as the baseline (so the "shrink, add, shrink again" semantics still hold).

ClonableContainer

Movable

Carries either a CFrame (3D mode) or a Dim Position (2D mode). Writing the property applies the delta to every child, where the delta is measured from that specific child's baseline of the container, recorded when it was added.

Sizable

Carries a Size property of either type Vector (3D mode) or Dim (2D mode). Writing it scales every child by the per-axis ratio of Size to the child's baseline container size. Heterogeneous: a tiny child added to a small container scales the same proportionally as a big child added later.

Billboard

World-anchored UI surface. Link GUI primitives to a Billboard with :AddChild(primitive) and they render in the 3D scene at the Billboard's Position instead of on screen. Each linked primitive's Position is its offset (in pixels) inside the Billboard's local canvas; the canvas itself is centered on the world point. Behind-camera Billboards are culled.

A primitive can be linked to at most one Billboard at a time. Re-linking it to a different Billboard errors. Destroying a Billboard unlinks every child — those primitives fall back to normal screen-space rendering at whatever Position they currently hold.

local Objects = import("Objects")
local GUI     = import("GUI")
local Asset   = import("Asset")
local Vector  = import("Primitives").Vector
local Dim     = import("Primitives").Dim

local bb = Objects.Billboard()
bb.Position = Vector.new(5, 3, 0)
bb.Size     = Dim.new(300, 120)

local bg = GUI.Basic.Square()
bg.Size     = Dim.new(300, 120)
bg.Position = Dim.new(0, 0)        -- top-left of canvas
bb:AddChild(bg)

local name = GUI.Basic.Font(Asset.GetAsset("Font", "ui.body"))
name.Position = Dim.new(12, 12)
bb:AddChild(name)

Properties

ScaleWithCamera

False (default): the canvas is a fixed pixel size on screen. A 300×300 Billboard always covers 300×300 pixels regardless of camera distance — the classic Roblox-style nameplate billboard.

True: the canvas scales with distance like a real 3D object. The pixel size becomes a world-space size at the Billboard's depth, so walking closer makes it bigger and walking away makes it smaller, same falloff as a sprite in 3D.

Methods

Tweening

A Billboard is a valid target for TweenService.new. Tweenable properties:

• Position — goal is a Vector
• Size — goal is a Dim

Movable and Sizable are also valid tween targets:

• Movable.CFrame (3D mode, goal is a CFrame) or .Position (2D mode, goal is a Dim) — children follow by delta each tick.
• Sizable.Size (goal is a Vector in 3D mode or a Dim in 2D mode) — children scale by the ratio each tick.

UIEnvironment

Container for 3D parts that should render on top of the 2D GUI instead of in the world. Drop a BasePart in with :AddChild(part) and the renderer pulls it out of the normal world pass, then redraws it in a follow-up pass that clears the depth buffer first. The effect: the part always wins against world geometry (it appears in front of everything), but still depth-tests against other parts in the same UI overlay (so a closer cube can still occlude a farther one inside the same UIEnvironment).

Use it for 3D-in-a-window UI: inventory previews, character portraits, model turntables in menus, anything where the part is "decoration on the HUD" rather than part of the world.

local Objects    = import("Objects")
local Renderable = import("Renderable")
local Primitives = import("Primitives")
local Heart      = import("RunService").Heartbeat

local ui3d = Objects.UIEnvironment()
ui3d.ZIndex = 10

local trophy = Renderable.BasePart("Cube")
trophy.Size = Primitives.Vector.new(1, 1, 1)
trophy.CFrame = Primitives.CFrame.new(Primitives.Vector.new(0, 0, -3))
ui3d:AddChild(trophy)

Heart:Connect(function(dt)
    trophy.CFrame = trophy.CFrame * Primitives.CFrame.Angles(0, dt, 0)
end)

Properties

Methods

Render order

Pipeline ordering each frame:

1. Skybox
2. World 3D parts (depth-tested, deepest first)
3. 3D particles
4. 2D GUI items (z-index sorted)
5. UI overlay 3D parts — in a fresh render pass that clears the depth buffer, sorted by each environment's ZIndex ascending (higher ZIndex draws later, so it appears on top of lower ones).
6. Optional post-effect pass