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 and .Size. 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 rect is cut at the GPU scissor stage. Resizing or moving the Clippable retroactively re-clips every child the next frame, so it works as a scrolling viewport, masked overlay, or draggable panel without having to re-add children. Works on every other primitive type — including DynImg-backed Image primitives, since by the time clipping runs they're a single textured rectangle.

local mask = GUI.Basic.Clippable()
mask.Position = Dim.new(100, 100)
mask.Size     = Dim.new(400, 300)

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)              -- pixels outside (100,100,400,300) are cut

-- Move the mask -- the image gets re-clipped automatically.
mask.Position = Dim.new(200, 100)

"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.

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 scissored to this primitive's current Position+Size every frame. Pixels of child outside this rect are cut. Reading the Clippable's Size or Position retroactively re-clips every child on the next snapshot — no need to re-add. Last-add-wins for re-parenting.

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.

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.