UI Components

These are the visual elements you drag onto the canvas in CCraft Studio. On export, each one becomes an instance of a Lua class in components/ (see Generated File Reference). This page lists every component and the properties it carries into the generated code.

All components share a common set of base properties; each type then adds its own. The tables below list the property name and type that appear in the exported Lua — not editor defaults, since every element is written with its current values.

Shared properties

Every element is created from screens/<ScreenName>.lua with these base fields:

Property	Type	Description
name	string	Unique element name (used by getChild)
type	string	Element type: label, button, container, …
x, y	number	Resolved top‑left position (1‑based)
width, height	number	Resolved size in characters
widthUnit, heightUnit	px | % | fill	How the size was specified
rawWidth, rawHeight	number	Original %/fill value (only when not px)
bgColor	color	Background color
visible	boolean	Whether the element is drawn / hit‑tested
zIndex	number	Draw + hit‑test order (higher is on top)
parentName	string	Name of the containing container/panel (if nested)
screenName	string	Name of the owning screen

Size units

Unit	Meaning
px	Fixed number of characters
%	Percentage of the parent's inner size (stored in rawWidth/rawHeight)
fill	Grow to fill the available space

Components

Label

Static, non‑interactive text.

Property	Type	Description
text	string	The text to display
textAlign	left | center | right	Horizontal alignment
textColor	color	Text color

Button

A clickable button with separate colors for its focused (pressed) state.

Property	Type	Description
text	string	Button label
textAlign	left | center | right	Horizontal alignment
textColor	color	Text color
focusBgColor	color	Background while pressed
focusTextColor	color	Text color while pressed

Events: clicked, focused, released, text_changed.

Container

An invisible layout group. Lays out its children with flex or grid rules (see Layout).

Property	Type	Description
display	flex | grid	Layout algorithm
flexDirection	row | column	Main axis (flex only)
gap, gapUnit	number, px | %	Space between children
alignItems	start | center | end	Cross‑axis alignment
justifyContent	start | center | end | space-between	Main‑axis distribution
gridTemplateCols, gridTemplateRows	number	Grid size (grid only)
padding, paddingUnit	number, px | %	Inner spacing

Panel

A titled, bordered container. Same layout options as Container, plus a title bar and border. The border insets its content by one character on every side.

Property	Type	Description
text	string	Title shown in the bar
textAlign	left | center | right	Title alignment
textColor	color	Title text color
borderColor	color	Border color
titleBgColor	color	Title bar background
…all Container layout props		Same flex/grid options as Container

ProgressBar

A fillable bar that can fill in any direction.

Property	Type	Description
text	string	Label drawn over the bar
textAlign	left | center | right	Label alignment
progress	number (0–100)	Fill amount
progressColor	color	Filled portion color
textColor	color	Label color
orientation	see Orientation	Fill direction

Events: progress_changed, text_changed.

Slider

A draggable control that maps a handle position to a value range.

Property	Type	Description
from, to	number	Value range bounds
value	number	Current value
handleColor	color	Handle color
filledColor	color	Filled track color
orientation	see Orientation	Travel direction

Events: value_changed.

CheckBox

A labelled toggle.

Property	Type	Description
text	string	Label text
checked	boolean	Whether it's ticked
checkIcon	string	Character shown when checked
textColor	color	Label color
boxColor	color	Box color when unchecked
checkedColor	color	Box color when checked
textAlign	left | center | right	Label alignment

Events: toggled, checked, unchecked, text_changed.

Input

An editable single‑line text field with a placeholder.

Property	Type	Description
text	string	Current text value
placeholder	string	Hint shown when empty
textColor	color	Text color
placeholderColor	color	Placeholder color
textAlign	left | center | right	Text alignment

Events: key_pressed, focused, text_changed.

Layout: containers & panels

Containers and panels position their children automatically; the exporter pre‑computes the resulting coordinates, and the runtime re‑resolves them for the actual display size.

• Flex (display = "flex") lays children along a main axis set by flexDirection (row or column). justifyContent distributes space along that axis; alignItems aligns on the cross axis; gap spaces children apart.
• Grid (display = "grid") arranges children into gridTemplateCols × gridTemplateRows cells.
• padding insets the children; a Panel additionally reserves one character of border on every side.
• % and fill sized children share the leftover space; mixing them with px children works as you'd expect.

Orientation

ProgressBar and Slider fill/travel in one of four directions:

Value	Direction
hltr	Horizontal, left → right
hrtl	Horizontal, right → left
vttb	Vertical, top → bottom
vbtt	Vertical, bottom → top

Colors

Colors map directly to the 16 CC: Tweaked colors and are emitted as colors.<name> in the generated Lua.

Name	Lua	Hex
white	colors.white	#F0F0F0
orange	colors.orange	#F2B233
magenta	colors.magenta	#E57FD8
lightBlue	colors.lightBlue	#99B2F2
yellow	colors.yellow	#DEDE6C
lime	colors.lime	#7FCC19
pink	colors.pink	#F2B2CC
gray	colors.gray	#4C4C4C
lightGray	colors.lightGray	#999999
cyan	colors.cyan	#4C99B2
purple	colors.purple	#B266E5
blue	colors.blue	#3366CC
brown	colors.brown	#7F664C
green	colors.green	#57A64E
red	colors.red	#CC4C4C
black	colors.black	#111111

Special characters in text

Any text property can embed a CC: Tweaked character code using a \NN token, where NN is the character's number. At render time the runtime converts it with string.char. For example "Button \17" renders the ▶ arrow glyph (character 17).

See also

• Runtime API — the methods these components expose at runtime
• Blocks — how block logic reads and writes these properties
• Generated File Reference