Ui

Description

This component establishes a User Interface in relation to the entity.

Properties

Property	Type	Default	Description
type (Required)	string		Supported types are: 'overlay' and '3d'
font	string		Font to use
fontSize	f32		Size of the text
position	string	'relative'	Choice of: 'relative' or 'absolute'
opacity	f32	1	Overall opacity of the object
backgroundOpacity	f32	0	Opacity of the background
backgroundSize	string		Background sizing behavior. Choose between ‘stretch’, 'contain’, 'cover’, 'nineSlice’
background	string		Background color. Supports color and image.
color	string		Foreground (text) color
text	string	""	Text content of the object
image	string	null	Image resource
fixedSize	boolean		Determines if size is fixed
width	string	100	Width of the object
height	string	100	Height of the object
top	string		Vertical position from top border
left	string		Horizontal position from left border
bottom	string		Vertical position from bottom border
right	string		Horizontal position from right border
borderColor	string		Color of the border
borderRadius	f32	0	Rounds the corners of the element
borderRadiusTopLeft	f32	0	Rounds the top left corner of the element
borderRadiusTopRight	f32	0	Rounds the top right corner of the element
borderRadiusBottomLeft	f32	0	Rounds the bottom left corner of the element
borderRadiusBottomRight	f32	0	Rounds the bottom right corner of the element
alignContent	string		Distribution of space between content items; allowed values: 'flex-start’, 'center’, 'flex-end’, 'stretch’, 'space-between’, 'space-around’
alignItems	string		Alignment of items on the cross axis; allowed values: 'flex-start’, 'center’, 'flex-end’, 'stretch’, 'baseline’
alignSelf	string		Alignment of an individual flex item; allowed values: 'auto’, 'flex-start’, 'center’, 'flex-end’, 'stretch’, 'baseline’
borderWidth	f32	0	Width of the border
columnGap	string		Gap between columns
direction	string		Text direction; allowed values: 'inherit’, 'LTR’, 'RTL’
display	string		Display type of the element; allowed values: 'flex’, 'none’
flex	f32		Flex grow, shrink, and basis shorthand
flexBasis	string		Initial main size of a flex item
flexDirection	string		Direction of flex items in the container; allowed values: 'column’, 'column-reverse’, 'row’, 'row-reverse’
flexGrow	f32		Defines the ability for a flex item to grow
flexShrink	f32		Defines the ability for a flex item to shrink
flexWrap	string		Whether flex items wrap; allowed values: 'no-wrap’, 'wrap’, 'wrap-reverse’
gap	string		Gap between flex items
justifyContent	string		Alignment of items on the main axis; allowed values: 'flex-start’, 'center’, 'flex-end’, 'space-between’, 'space-around’, 'space-evenly’
margin	string		Margin around the element
marginBottom	string		Bottom margin
marginLeft	string		Left margin
marginRight	string		Right margin
marginTop	string		Top margin
maxHeight	string		Maximum height of the element
maxWidth	string		Maximum width of the element
minHeight	string		Minimum height of the element
minWidth	string		Minimum width of the element
overflow	string		How content that exceeds the element’s size is handled; allowed values: 'visible’, 'hidden’, 'scroll’
padding	string		Padding inside the element
paddingBottom	string		Bottom padding
paddingLeft	string		Left padding
paddingRight	string		Right padding
paddingTop	string		Top padding
rowGap	string		Gap between rows
textAlign	string		Alignment of text within the element; allowed values: 'left’, 'right’, 'center’, 'justify’
ignoreRaycast	boolean	false	Determines whether the UI element should respond to user interactions like clicks or taps
stackingOrder	f32	0	Determines the rendering order of UI elements. Elements with higher values are drawn above those with lower values. By default elements are rendered according to their order in the scene hierarchy
nineSliceBorderTop	string		Size of the top border used in nine-slice scaling. Defines how much of the top portion is preserved without scaling.
nineSliceBorderBottom	string		Size of the bottom border used in nine-slice scaling. Defines how much of the bottom portion is preserved without scaling.
nineSliceBorderLeft	string		Size of the left border used in nine-slice scaling. Defines how much of the left portion is preserved without scaling.
nineSliceBorderRight	string		Size of the right border used in nine-slice scaling. Defines how much of the right portion is preserved without scaling.
nineSliceScaleFactor	f32		Multiplier applied to the scaled center area in nine-slice backgrounds. Allows finer control over the scaling of the center portion.

Functions

Get

Returns a read-only reference.

Example

ecs.Ui.get(world, component.eid)

Set

Ensures the component exists on the entity, then assigns the (optional) data to the component.

Example

ecs.Ui.set(world, component.eid, {
  type: 'overlay',
  background: '#FFFFFF'
})

Mutate

Perform an update to the component within a callback function. Return true to indicate no changes made.

Example

ecs.Ui.mutate(world, component.eid, (cursor) => {
  cursor.opacity = 0.5;
  cursor.text = 'Hello World!';
  cursor.width = 150;
  return false;
})

Remove

Removes the component from the entity.

Example

ecs.Ui.remove(world, component.eid)

Has

Returns true if the component is present on the entity.

Example

ecs.Ui.has(world, component.eid)

Reset

Adds, or resets the component to its default state.

Example

ecs.Ui.reset(world, component.eid)

Advanced Functions

Cursor

Returns a mutable reference. Cursors are reused so only one cursor for each component can exist at a time.

Example

ecs.Ui.cursor(world, component.eid)

Acquire

Same behavior as cursor, but commit must be called after the cursor is done being used.

Example

ecs.Ui.acquire(world, component.eid)

Commit

Called after acquire. An optional third argument determines whether the cursor was mutated or not.

Example

ecs.Ui.commit(world, component.eid)
ecs.Ui.commit(world, component.eid, false)

Dirty

Mark the entity as having been mutated. Only needed in a specific case where systems are mutating data.

Example

ecs.Ui.dirty(world, component.eid)