GUI

Solid-coloured rectangle. Tinted by .Color; sized by .Size.

Solid-coloured circle inscribed in .Size. The major axis follows the longer of .Size.X and .Size.Y, pass equal width / height for a true circle.

Solid-coloured triangle inscribed in .Size: apex at top-center, base on the bottom edge. Useful for arrows / indicators, rotate via a custom shader if you need arbitrary orientations.

Textured rectangle. Pass an ImageAsset; the asset's pixels become the surface.

Text label. Pass a FontAsset; glyphs are rasterised at runtime sized by .TextSize and colored by the primitive's .Color. Supports synthetic styling (.FontStyle, .Underline, .Strikethrough) and inline color escapes in .Text (see below). Styling is applied at bake time — weight is a coverage dilation, italic is a horizontal shear, and underline / strikethrough are drawn rules. Pair with a real bold / italic TTF for pixel-perfect typography.

local label = GUI.Basic.Font(font)
label.Text          = "Headline {#ff5050}danger{} resumed"
label.TextSize      = 48
label.FontStyle     = "BoldItalic"
label.Underline     = true
label.Visible       = true

Invisible clip container with a pixel-space .Position, .Size, and .Rotation. Doesn't render anything itself — its job is to be a parent for children added via :AddClippable(child). Anything inside those children that falls outside the Clippable's shape is discarded in the children's fragment shader. Resizing, moving, or rotating the Clippable retroactively re-clips every child the next frame, so it works as a scrolling viewport, masked overlay, draggable panel, or rotating reticle without having to re-add children.

The clip area can be reshaped via :SetShape("Square" | "Circle" | "Triangle"). The default is "Square" (axis-aligned rect in the Clippable's local space). Each child's fragment shader transforms its pixel into the Clippable's local UV space (accounting for rotation), tests it against the chosen shape, and discards if outside — so a rotated Circle clip really is a rotated ellipse, not an AABB approximation.

local mask = GUI.Basic.Clippable()
mask.Position = Dim.new(100, 100)
mask.Size     = Dim.new(400, 300)
mask.Rotation = 15                       -- degrees; children clip to the rotated rect
mask:SetShape("Circle")               -- or "Square" (default) / "Triangle"

local img = GUI.Basic.Image(asset)
img.Position = Dim.new(80, 90)            -- partly outside the mask
img.Size     = Dim.new(500, 500)
mask:AddClippable(img)                     -- only pixels inside the rotated ellipse render

Polyline primitive. Unlike the other GUI.Basic.* factories, a Spline has no global Position or Size — the nodes determine its shape. Each node contributes a position (Dim), a per-node thickness (pixels), and a per-node tangent angle that rotates how the curve enters and leaves the node. With angle = 0 you get a straight polyline through the nodes; non-zero angles bend the curve to leave / arrive at that tangent direction, so you can build arcs and S-curves with just a handful of nodes. Geometry is sampled along a cubic Bezier per segment (control points derived from the node tangents), then triangulated into a ribbon with caps at the start/end.

local line = GUI.Basic.Spline()
line.Color = Primitives.Color3.fromRGB(120, 200, 255)
line.Cap   = "Rounded"

-- All Angle = 0 gives a straight polyline through the points.
line:SetNodes{
    { Position = Dim.new(100, 200), Thickness = 6 },
    { Position = Dim.new(300, 200), Thickness = 8 },
    { Position = Dim.new(500, 120), Thickness = 4 },
}

-- Add tangent angles to arc the line through the middle node.
-- The first & last nodes' angles control how the line enters/leaves the endpoints;
-- the middle node's 45 degrees pulls the curve into a smooth arc through it.
line:SetNodes{
    { Position = Dim.new(100, 300), Thickness = 6, Angle = 0   },   -- leaves horizontally
    { Position = Dim.new(300, 200), Thickness = 8, Angle = 45  },   -- curve passes through at +45
    { Position = Dim.new(500, 300), Thickness = 4, Angle = 0   },   -- arrives horizontally
}

Replace the entire node array. Cancels any active tween. Fires .Changed("Nodes").

Snapshot copy of the current node array.

1-based insertion. index = 1 prepends, index > NodeCount appends. Doesn't touch the tween — useful for hand-editing during an animation.

1-based removal. Errors if out of range.

Replace a single node in place.

Attach a FragmentAsset (or ShaderAsset) as the fragment stage. The shader receives the same U: RuzitUni uniform and the standard prelude; in.uv.x is the along-line parameter (0 at start, 1 at end) and in.uv.y is the cross-line parameter (0 on one edge, 1 on the other).

Detach all shaders; reverts to the default solid-color fragment.

Mark dead; the spline stops rendering and is reaped on the next snapshot.

"Text" covers both Font and StyledFont primitives — styling is a property toggle, not a separate shape.

Pixel-space size. For Text this is (0, 0), size is driven by .TextSize.

Top-left position. Origin at the top-left of the window.

Fractional anchor in 0..1 used by layout systems (e.g. Declar) to position the primitive relative to its own pixel rectangle: (0, 0) anchors the top-left corner, (0.5, 0.5) centres the primitive on its .Position, (1, 1) anchors the bottom-right. The engine reads this for baked-text re-centring and for Billboard alignment; the renderer itself still uses .Position as a top-left anchor, so most game code only touches .AnchorPoint through a layout library. No .Changed fire — it's a layout input, not an observable visual property.

Rotation around the primitive's center. 0 is the natural orientation; positive values rotate clockwise in screen space (Y-down). Applies to every primitive shape and inherits through AnimatedImage / DrawableImg since both render via a Primitive. Note: spatial queries (GUI.Raycast, GUI.OverlapBox, etc.) still hit-test against the un-rotated AABB — visual rotation only.

Tint when texture-less; image tint when textured; box colour for Text.

0 opaque, 1 fully transparent.

Higher = drawn on top.

Hide without destroying. Defaults to false on every freshly-created primitive — flip it to true once you've finished configuring size / position / image / text, so half-built primitives don't flash on screen for a frame.

Text content. No-op on non-Text primitives. Glyphs are colored by the primitive's regular .Color — there's no separate TextColor. Inline color escapes are supported: {#RRGGBB} or {#RGB} switches the active color, {} resets to the base .Color, and {{ writes a literal {. Tags whose contents don't match are left as literal text.

label.Text = "Loaded {#3cb371}OK{}, {#ff5050}3 errors{} found"

Glyph height in pixels.

Synthetic font variant applied at bake time. Defaults to "Regular". Setting an unknown value errors; call primitive:ListFontStyles() to enumerate. Italic variants shear the glyphs ~12°; weight variants dilate (or erode) glyph coverage. Both are inexpensive but visibly approximate — pair with a real bold / italic TTF if you need typographic precision.

Draw a baseline rule. Off by default.

Draw a rule through x-height. Combinable with .Underline.

Per-property change signal. Fires with the new value as its only argument every time propName is set — "Position" fires with a Dim, "Color" with a Color3, "Transparency" with a number, etc. Lazily created: properties no one listens to cost zero. When the last connection disconnects the engine stops firing it entirely.

square:GetPropertyChanged("Position"):Connect(function(p)
    print(p.x, p.y)
end)

Only valid on Font primitives. Returns every value accepted by .FontStyle, in canonical casing: Regular, Italic, Light, LightItalic, Medium, MediumItalic, SemiBold, SemiBoldItalic, Bold, BoldItalic, ExtraBold, ExtraBoldItalic, Black, BlackItalic. Use to populate a dropdown or validate user input.

for _, style in label:ListFontStyles() do
    print(style)
end

Only valid on Shape == "Clippable" primitives. Register child to be clipped to this primitive's current shape, position, size, and rotation every frame. Pixels of child outside the (possibly rotated) shape are discarded in the child's fragment shader. Reading the Clippable's Size / Position / Rotation / Shape retroactively re-clips every child on the next snapshot — no need to re-add. Last-add-wins for re-parenting.

Only valid on Shape == "Clippable" primitives. Choose the clip-area shape: "Square" (default — axis-aligned rectangle in the Clippable's local space), "Circle" (ellipse inscribed in the Size box), or "Triangle" (apex-up isosceles triangle). Combined with .Rotation you get rotated ellipses, rotated triangles, etc. Children re-clip on the next frame without needing to be re-added.

Detach a child added via :AddClippable. The child resumes rendering unclipped. Idempotent if child wasn't added to this specific Clippable.

Attach a 2D fragment shader to this primitive's draw call. priority (integer, default 0) controls draw order when multiple shaders are attached: lower values are drawn first (become the base layer); higher values are drawn later (appear on top). Ties keep the attach order. For an effect that overlays an underlying one, give the underneath shader a lower priority — prim:AttachShader(base, 0); prim:AttachShader(overlay, 1) draws base first then overlay over it.

Mirror of the underlying Image primitive's Size. Writing squashes / stretches the currently-displayed frame.

Top-left position of the rendered image.

Higher = drawn on top.

Defaults to false like every other GUI primitive. Flip to true after creating tracks so you don't flash a half-set-up animation for a frame.

Tint multiplied into the current frame's pixels.

0 opaque, 1 fully transparent.

Total number of <SubTexture> entries parsed from the XML.

False after :Destroy().

Build an AnimatedImageTrack from a sequence of SubTexture names. frames is either an array ({"Down0000", "Down0001"}) or a comma-separated string ("Down0000,Down0001,Down0002"). Unknown frame names error. opts is an optional table with FPS (default 12), Looped (default false), and Priority (default 1). Returns a fresh track with its own state and signals — useful for layered animation. Tracks are owned by this AnimatedImage; :Destroy() stops them.

Snap the displayed frame to a specific SubTexture by name ("Down0000") or by zero-based index. The pinned frame stays visible until a track is :Play()'d on top — priority playback wins. Useful for video-game icons that flip between named static frames.

Release the manual frame override.

Whether the parsed atlas contains a SubTexture with this name.

Every SubTexture name in source order. Handy for picking frame names dynamically (e.g. all frames starting with "down").

The underlying GUI Image primitive. Useful for clipping (clippable:AddClippable(image:GetPrimitive())) or attaching a shader (:AttachShader(asset)).

Destroy the underlying primitive and stop every track. All :CreateTrack handles still resolve but their ticks stop firing.

Playback rate. Live-editable; the next tick uses the new value. Clamped to a small positive minimum to avoid divide-by-zero.

When true, the track wraps at the end and fires DidLoop. When false, it stops at the end and fires Ended.

Higher priority wins when multiple tracks are Playing. When a higher-priority track ends (non-looped) and a lower-priority track is still Playing, the lower one takes over the display. Default 1.

How many frames this track plays through.

Seconds elapsed in the current play cycle.

Fires every time a looped track wraps. If the heart loop skipped multiple cycles in one tick (lag spike), the signal fires multiple times in a row.

Fires once when a non-looped track reaches its end. Does NOT fire on :Stop().

Start the track. Resets Elapsed to 0 and transitions state to "Playing". Calling on an already-Playing track is a no-op.

Stop the track immediately. State goes to "Stopped". Does NOT fire Ended. The displayed frame switches to whichever lower-priority Playing track wins next tick.

Pause without resetting (state goes "Idle"). Elapsed is preserved so :Resume() continues from where you paused.

Resume from "Idle" back to "Playing".

Yield the calling coroutine until Ended fires. Must be called from inside a coroutine.

Debug label for the drawable (e.g. "<drawable:128x128>"). Useful in logs.

Return the current pixel buffer as a binary string (width * height * 4 bytes of RGBA). Snapshot value; further draws don't mutate the returned string.

Set one pixel. color is a Color3. transparency defaults to 0 (opaque). Out-of-bounds coordinates are clipped.

Fill a rectangle. x, y is the top-left; w, h is the size. Clipped to the drawable's bounds.

Alias for :DrawRect.

Bresenham line from (x0,y0) to (x1,y1).

Circle centered on (cx, cy) with radius radius. filled defaults to false (outline). Clipped to bounds.

Fill the whole drawable with one color.

Zero out every byte (fully transparent black).

Blit a CanvasBuffer into this drawable at offset (atX, atY) (defaults to 0, 0). Source pixels with non-zero alpha are copied; clipped to bounds. Use this to batch many CPU draws into a CanvasBuffer cheaply, then commit to the GPU-visible DrawableImg in one shot.

Free the drawable. After this, IsAlive() is false and primitives that referenced it stop refreshing.

Snapshot of the current pixel buffer as RGBA bytes.

Alias for :DrawRect.

Zero out every byte.

Blit this canvas onto a DrawableImg at offset (atX, atY) (defaults to 0, 0). One texture upload happens at this point; the canvas itself never touches the GPU. Use it to commit batched CPU work.

Force-spawn n particles now (default 1).

Same particle WGSL contract as the 3D EffectVolume — see Particle shaders for the binding layout and the VsOut inputs. Both 2D and 3D particles use the same shader shape; the only difference is in.life_t is always 0 on 2D particles and the time field is F.resolution.z instead of F.viewport.z.

GPU-dispatched 2D ray test. Cubes / Images / Fonts / Clippables test as axis-aligned rectangles (Position .. Position + Size); circles as the inscribed ellipse; triangles as the actual triangle (apex at the top-middle of the AABB, base across the bottom). direction is normalized internally; zero-length errors. Hits are visited nearest-first; filter returns true to accept, false / nil to skip past. Returns nil when nothing was hit. Falls back to no-op if the GPU has not been initialized yet (no window opened).

local hit = GUI.Raycast(Dim.new(100, 100), Dim.new(1, 0))
if hit then
    print("hit at ", hit.Position.X, hit.Position.Y, "dist ", hit.Distance)
end

Every visible primitive whose AABB overlaps the rectangle centered at center with full extents size. quality is accepted for parity with the 3D API but ignored — 2D primitives have no sub-quad geometry.

Every visible primitive whose AABB intersects the circle at center with the given radius. (Named "Sphere" to mirror the 3D API.)

Every visible primitive whose AABB intersects the oriented box at center with full extents size, rotated by rotation radians (defaults to 0). The GPU test is exact OBB-vs-AABB via the separating-axis theorem.

Every visible primitive whose AABB intersects the current viewport rect (0, 0)..(window width, height). Useful as a fast pass for "what's on-screen right now."

Oriented zone query. cframe accepts a CFrame (uses position.xy and rotation.z), a Dim, or a plain { X, Y } table. Equivalent to OverlapBox on the 2D system; the 3D version's "mesh-precise" semantics don't apply here since GUI primitives have no sub-quad geometry.