Skip to main content
Version: Current

Visualization Tags

Visualization Tags

These tags change how CasualOS displays bots.

color

The color of the bot.

Possible values are:

ValueDescription
white

(default)

#858585

(default for keyboards)

Any X11 ColorX11 colors are a list of standard colors that web browsers support.
Any Hex ColorHex colors are three or six digit numbers that specify a color by its red, green, and blue components.
clear

The bot's body will be invisible.

cursor

The cursor that should be used when the mouse pointer is hovering over the bot in the bot and menu portals.

Note that when using a custom cursor image, the image should be 32x32 pixels or smaller. This is because that is the largest cursor image size that some operating systems support.

Possible values are:

ValueDescription
autoThe cursor automatically changes its look based on the context. For grid portal bots, this means that the arrow cursor is used. For menu portal bots, this means that the pointer is used when the bot has a @onClick and the arrow is used otherwise. (default)
defaultThe cursor looks like the default cursor for the platform. Generally, this means the arrow cursor.
noneThe cursor is invisible.
waitwait
context-menucontext-menu
helphelp
pointerpointer
progressprogress
cellcell
crosshaircrosshair
texttext
vertical-textvertical-text
aliasalias
copycopy
movemove
no-dropno-drop
not-allowednot-allowed
grabgrab
grabbinggrabbing
all-scrollall-scroll
col-resizecol-resize
row-resizerow-resize
n-resizen-resize
e-resizee-resize
s-resizes-resize
w-resizew-resize
ne-resizene-resize
nw-resizenw-resize
se-resizese-resize
sw-resizesw-resize
ew-resizeew-resize
ns-resizens-resize
nesw-resizenesw-resize
nwse-resizenwse-resize
zoom-inzoom-in
zoom-outzoom-out
Any URLThe image at the given URL will be used as the cursor. Images should be 32x32 pixels or smaller otherwise they may not work.

cursorHotspot

The X and Y position of the pixel in the cursor image that is the "hotspot". That is, the pixel which represents the point or tip of the cursor.

The top left of the image is (0, 0).

Possible values are:

ValueDescription
➡️0,0(default)
Any Vector > ➡️0,0The position that the cursor hotspot should be at.

strokeColor

The color of the bot's outline.

Possible values are:

ValueDescription
clear

(default)

Any X11 ColorX11 colors are a list of standard colors that web browsers support.
Any Hex ColorHex colors are three or six digit numbers that specify a color by its red, green, and blue components.

strokeWidth

The width of the bot's outline.

lineTo

The bot, bot ID, list of bots, or list of bot IDs that this bot should draw lines to.

lineStyle

The style of the lines.

Possible values are:

ValueDescription
line

Displays the line without additional decoration. (Default)

arrow

Displays the line with an arrow at the tip pointing to the target bot.

wall

Displays the line as a vertical wall.

lineWidth

The width of the lines from this bot.

Possible values are:

ValueDescription
1

The width of the line is 1 unit. (default)

Any Number > 0

The width of the line is the given size.

lineColor

The color of the lines.

Possible values are:

ValueDescription
white

(default)

Any X11 ColorX11 colors are a list of standard colors that web browsers support.
Any Hex ColorHex colors are three or six digit numbers that specify a color by its red, green, and blue components.

label

The text that the bot should show in a label.

labelColor

The color of the text in the label.

Possible values are:

ValueDescription
black

(default)

Any X11 ColorX11 colors are a list of standard colors that web browsers support.
Any Hex ColorHex colors are three or six digit numbers that specify a color by its red, green, and blue components.

labelOpacity

The opacity of the text in the label.

Possible values are:

ValueDescription
1

(default)

Any Number >= 0 and <= 1

The label will use the given opacity.

labelFontSize

The font size of the text in the label. Changing this value scales the text characters in the label which changes the text layout.

Possible values are:

ValueDescription
auto

The label font size is automatically scaled to fit the text in the bot. (Default)

Any Number > 0

The label will use the given font size.

labelPadding

The amount of space that should be between the edge of the bot and the edge of the label. Units are in grid spaces.

When #labelFontSize is set to auto, this setting affects both the label height and width. Otherwise, it only affects the width.

Possible values are:

ValueDescription
0

There is no space between the edge of the bot and the edge of the label. (Default)

Any Number > 0

The label is sized so that it fits in the space provided by the bot minus the padding.

labelPaddingX

The amount of space that should be between the side of the bot and the side of the label. Units are in grid spaces.

This tag is similar to #labelPadding except that it only affects the width of the label.

Possible values are:

ValueDescription
0

There is no space between the edge of the bot and the edge of the label. (Default)

Any Number > 0

The label is sized so that it fits in the space provided by the bot minus the padding.

labelPaddingY

The amount of space that should be between the top of the bot and the top of the label. Units are in grid spaces.

This tag is similar to #labelPadding except that it only affects the height of the label. As such, this tag only has an effect when #labelFontSize is set to auto.

Possible values are:

ValueDescription
0

There is no space between the edge of the bot and the edge of the label. (Default)

Any Number > 0

The label is sized so that it fits in the space provided by the bot minus the padding.

labelSize

The size of the label. Default is 1. Changing this value scales the label text in size without changing the text layout. This is useful for floating labels where you want the bubble to be larger without changing the size of the font.

labelSizeMode

The sizing mode for the label.

Possible values are:

ValueDescription
normal

Don't automatically scale the label size. (default)

auto

Automatically scale the label to keep the same size on the screen.

labelPosition

The anchor position for the label.

Possible values are:

ValueDescription
topTop of the bot facing world oriented up. (default)
frontFront of the bot facing world oriented forward.
backBack of the bot facing world oriented back.
rightRight of the bot facing world oriented right.
leftLeft of the bot facing world oriented left.
floatingFloating above the bot.
floatingBillboardFloating above the bot and billboarded to face the camera. Like floating, but the label background won't have an arrow and the label will always face the camera.

labelAlignment

The text alignment for the label.

Possible values are:

ValueDescription
center

The text is aligned around the center of the face that the label is anchored to. (default)

left

The text is aligned on the left side of the face that the label is anchored to.

right

The text is aligned on the right side of the face that the label is anchored to.

labelFontAddress

The address of the font that the label should use.

If the current font does not support a specific character, the character will be displayed as a crossed out box (i.e. ).

Possible values are:

ValueDescription
roboto

Specifies that the Roboto font should be used. (default)

noto-sans-kr

Specifies that the Noto Sans KR font should be used. This is a font with support for the Korean language.

Any URL

Specifies that the font to be used should be downloaded from the given URL. Currently supports WOFF and OTF fonts.

labelWordWrapMode

The word wrapping mode that the label should use. Useful for automatically fitting the text onto the bot.

Possible values are:

ValueDescription
breakCharacters

Line breaks may be inserted inside a word to fit the label on the bot. (default)

breakWords

Line breaks may be inserted between words to fit the label on the bot.

none

Line breaks will not be inserted.

labelFloatingBackgroundColor

The background color of the floating label. Only works when #labelPosition is set to floating or floatingBillboard.

Possible values are:

ValueDescription
white

(default)

Any X11 ColorX11 colors are a list of standard colors that web browsers support.
Any Hex ColorHex colors are three or six digit numbers that specify a color by its red, green, and blue components.
clear

The background will be invisible.

scale

The uniform scale of the bot.

Defaults to 1.

scaleX

The X scale (width) of the bot. Combines with the #scale tag to determine the final width of the bot.

Defaults to 1.

scaleY

The Y scale (length) of the bot. Combines with the #scale tag to determine the final length of the bot. For menu bots, you can use auto. This scales the bot's height to fit its label.

Defaults to 1.

scaleZ

The Z scale (height) of the bot. Combines with the #scale tag to determine the final height of the bot.

Defaults to 1.

scaleMode

How the form is scaled to fit inside the bot.

Note that this setting does not affect #scale, #scaleX, #scaleY or #scaleZ. Instead, it changes how custom forms like meshes are scaled to fit inside the unit cube.

Also note that this setting affects a bot's collision volume. The collision volume will always try to wrap the bot's form to the best of its ability. This means that if you have a really large mesh the collider will scale up to surround the mesh.

Possible values are:

ValueDescription
fit

The form is scaled to fit inside the bot's unit cube. The aspect ratio will be preserved. (default)

absolute

The form is not scaled.

form

The shape that the bot should be displayed as.

Possible values are:

ValueDescription
cube

Cube mesh (default)

skybox

A Sphere mesh optimal for "skybox" implementation.

sphere

Sphere mesh

sprite

Camera facing (billboarded) sprite/quad images.

mesh

A mesh loaded from the web. See #formSubtype for additional options.

frustum

A camera frustum mesh.

helix

A double helix mesh (like DNA).

egg

A egg mesh.

hex

A hexagon mesh.

circle

A circle mesh.

keyboard

An interactive keyboard. Clicking the keys will generate @onKeyClick whispers that are sent to the bot.

iframe

A webpage loaded into a 3D iframe. See #formSubtype for additional options.

dimension

The bot will display the dimension specified by #formAddress.

portal

The bot will display the dimension specified by #formAddress. This is an alias for "dimension".

spherePortal

The bot will display the dimension specified by #formAddress in a spherical manner, using the X and Y coordinates as latitude and longitude coordinates.

cursor

The bot will appear as a cursor in the multi-line editor. You also need to place the bot in the same dimension that the tag portal uses for the cursor to appear.

codeButton

The bot will appear as a clickable button in the multi-line editor when placed in the same the same dimension that the tag portal uses. The bot will also need a label in order to appear.

The Start position of the bot the line number that the button should appear above, and the End position specifies the priority of the button compared to other buttons on the same line (larger numbers indicate lower priorities).

Additionally, it is possible to display code buttons in the multi-line editor's context menu by setting the #true tag to true. In this case, the #true tag represents putting the codeButton in the code editor for every tag.

codeHint

The bot will appear as a hint in the multi-line editor when placed in the same the same dimension that the uses. If a #color is specified, then the code that the hint covers will use the specified background color. If a #strokeColor is specified, then the code that the hint covers will use the stroke as a box border around the code. If given a #label, it will be rendered before the start position.

Use the #[dimension]Start and #[dimension]End tags to position the hint.

Additionally, codeHint bots support the @onClick listener for when their label text is clicked.

input

The bot will appear as an input box in the menu portal. You also need to place the bot in the dimension that the menu portal is showing for the input to appear. You can change the type of input using the #formSubtype tag.

light

The bot will appear as a light. You can change the type of light using the #formSubtype tag.

formSubtype

The subtype that the form should use. Useful for specifying how a mesh should be loaded.

Possible values are:

ValueDescription
null

No subtype (default)

gltf

A GLTF mesh loaded from a URL.

jsonObject

A Three.js JSON Object Scene loaded from a URL.

ldraw

A LDraw mesh loaded from a URL.

ldrawText

A LDraw mesh loaded from the text in the #formAddress tag.

html

The HTML code that should be loaded into an iframe when #form is set to iframe. (Default when #form is set to iframe)

src

The URL that should be loaded into an iframe when #form is set to iframe.

pointLight

A bot with the #form set to light will appear as a pointlight.

ambientLight

A bot with the #form set to light will appear as an ambientLight.

directionalLight

A bot with the #form set to light will appear as a directionalLight.

spotLight

A bot with the #form set to light will appear as a spotLight.

hemisphereLight

A bot with the #form set to light will appear as a hemisphereLight.

password

A bot with the #form set to input will function as a password input. (Characters are masked)

formLightIntensity

The intensity of the light.

Possible values are:

ValueDescription
1

(default)

Any Number

Changes the intensity of the light.

formLightTarget

The target of the light. Bot must have a #formSubtype of directionalLight or spotLight. Bot can not target self.

Possible values are:

ValueDescription
null

Light will target (0, 0, 0). (default)

Any Bot ID

The bot with the specified ID acts as the light's target. The light's direction is defined by the direction from the position of the light to the target.

formLightDistance

The maximum range of the light. Bot must have a #formSubtype of spotLight.

Possible values are:

ValueDescription
0

No limit (default)

Any Number

When distance is non-zero, light will attenuate according to inverse-square law until near the distance cutoff, where it will then attenuate quickly and smoothly to 0.

formLightAngle

Represents the angle between edges of spotLight. Bot must have a #formSubtype of spotLight. Angle is in radians.

Possible values are:

ValueDescription
null

Math.PI / 3 (default)

Any Number

Changes the angle of the light in radians.

formLightPenumbra

Represents the percent of the spotlight cone that is attenuated due to penumbra. Bot must have a #formSubtype of spotLight. Takes values between 0 and 1.

Possible values are:

ValueDescription
0

(default)

Any Number between 0 and 1

Percent of the spotlight cone that is attenuated due to penumbra.

formLightDecay

The amount the light dims along the distance of the light. Bot must have a #formSubtype of spotLight. In context of physically-correct rendering the default value should not be changed.

Possible values are:

ValueDescription
2

(default)

Any Number

The amount the light dims along the distance of the light.

formLightGroundColor

The light's ground color. Bot must have a #formSubtype of hemisphereLight.

Possible values are:

ValueDescription
white

(default)

Any X11 ColorX11 colors are a list of standard colors that web browsers support.
Any Hex ColorHex colors are three or six digit numbers that specify a color by its red, green, and blue components.

formAddress

The address that the bot should represent data from.

When #form is set to cube, skybox, sphere, or sprite, the address should be the URL of the image that the bot should display.

When #form is set to mesh and #formSubtype is set to gltf, the address should be the URL of the GLTF file that should be displayed.

When #form is set to iframe and #formSubtype is set to html, the address should be the HTML that should be displayed.

When #form is set to iframe and #formSubtype is set to src, the address should be the URL of the webpage that should be displayed.

When the bot is in the menu portal, this is the URL of the image or video that should be shown on the menu item. It can also be cube to show an icon of a cube, egg to show an egg icon, and helix to show an icon of a DNA helix. If the given value is not a URL or one of the predefined icons, then the specified Material Icon will be shown.

formAddressAspectRatio

The aspect ratio that should be used to ensure that the image/video from #formAddress is displayed correctly. Aspect ratio is the numerical ratio representing the width of an image divided by the height. For example, a 1080p image has a resolution of 1920x1080 which means it has an aspect ratio of 1920/1080 = 16/9 = ~1.7777777.

By default, CasualOS displays all images with an aspect ratio of 1. An aspect ratio of 1 ensures that the entire bot is covered, but if the original image has a different aspect ratio then it will appear distorted. To solve this, you can use the #formAddressAspectRatio tag to ensure that the aspect ratio that the image is displayed at matches the original aspect ratio.

Also note that negative aspect ratios will mirror the image horizontally.

Currently only supported by the cube, circle, and sprite forms.

Possible values are:

ValueDescription
1

Square aspect ratio. (default)

Any Number

Custom aspect ratio.

formAnimation

The name of the animation that the mesh should play. Only works for mesh forms.

ValueDescription
null

Play the first animation.

false

Stops animating the mesh.

Any String

Play the animation with the given name.

Any Integer >= 0

Play the animation at the given index. Useful for exploring possible animations if you don't have the name.

An array of numbers or strings

Plays the given list of animations in sequence. The last animation will loop forever.

formAnimationAddress

The URL that the animations for the mesh should be loaded from. For GLTF forms, this should be the URL of the GLTF file that contains the animations that should be used for the mesh.

ValueDescription
null

Use the animations that were built into the mesh.

Any URL

Use the animations from the given GLTF file.

meshPositioningMode

The positioning mode that should be used for GLTF meshes.

Possible values are:

ValueDescription
center

The mesh is positioned so it is centered around the bot's center. (default)

absolute

The mesh is not repositioned.

formOpacity

The opacity of the bot's form. Allows bots to be semi-transparent.

Possible values are:

ValueDescription
1

(default)

Any Number >= 0 and <= 1

The bot's form will use the given opacity.

formRenderOrder

The render order that should be used for this bot in the grid portals. Setting this property to a value other than 0 overrides the automatically calculated render order which is based on the distance of each bot to the portal camera.

It is not recommended to use this tag unless you are dealing with transparency issues caused by overlapping PNG #formAddress images.

Higher values mean the bot will be rendered first, and lower values means the bot will be rendered last.

Possible values are:

ValueDescription
0

Use the automatic render ordering. (Default)

Any Number

Use the given render ordering. Bots are rendered from the highest value to the lowest value.

formDepthTest

Whether depth testing is enabled for this bot in the grid portals.

Possible values are:

ValueDescription
true

(Default)

false

Disable depth testing.

formDepthWrite

Whether depth writing is enabled for this bot in the grid portals.

Possible values are:

ValueDescription
true

(Default)

false

Disable depth writing.

formBuildStep

The build step that should be displayed for the bot's LDraw file. Only works for bots that have a #form of mesh and a #formSubtype of ldraw or ldrawText.

Use os.ldrawCountAddressBuildSteps() or os.ldrawCountTextBuildSteps() to get the number of build steps that an LDraw file has.

Possible values are:

ValueDescription
Infinity

Display the result of all the build steps. (Default)

Numbers >= 0

Display only the result of the given build step.

formLDrawPartsAddress

The address that additional parts should be loaded from for the bot's LDraw file. Only works for bots that have a #form of mesh and a #formSubtype of ldraw or ldrawText.

Possible values are:

ValueDescription
Any URL

Load LDraw parts from the given URL path.

gltfVersion

The GLTF specification version that should be used to load a GLTF model.

Possible values are:

ValueDescription
2

Load the GLTF model with version 2 of the specification. (default)

Numbers < 2

Load the GLTF Model with version 1 of the specification. This is useful for loading meshes from poly.google.com.

progressBar

Causes a progress bar to be shown for the bot. Range is between 0 and 1. Needs both progressBarBackgroundColor and progressBarColor to visualize the progress

Possible values are:

ValueDescription
Numbers >= 0 and <= 1

progressBarColor

The foreground color of the progress bar.

Possible values are:

ValueDescription
black

(default)

Any X11 ColorX11 colors are a list of standard colors that web browsers support.
Any Hex ColorHex colors are three or six digit numbers that specify a color by its red, green, and blue components.

progressBarBackgroundColor

The background color of the progress bar.

ValueDescription
white

(default)

Any X11 ColorX11 colors are a list of standard colors that web browsers support.
Any Hex ColorHex colors are three or six digit numbers that specify a color by its red, green, and blue components.

progressBarPosition

The anchor position for the progress bar.

Possible values are:

ValueDescription
topTop of the bot facing world oriented up. (default)
frontFront of the bot facing world oriented forward.
backBack of the bot facing world oriented back.
rightRight of the bot facing world oriented right.
leftLeft of the bot facing world oriented left.
floatingFloating above the bot.
floatingBillboardFloating above the bot and billboarded to face the camera. Like floating, but the label background won't have an arrow and the label will always face the camera.

anchorPoint

The position that the bot form should rotate and scale around.

Possible values are:

ValueDescription
bottom

The bot rotates and scales around its bottom point. (default)

center

The bot rotates and scales around its center point.

front

The bot rotates and scales around the point at the center of the Bot's front face.

back

The bot rotates and scales around the point at the center of the Bot's back face.

top

The bot rotates and scales around its top point.

left

The bot rotates and scales around the point at the center of the Bot's left face.

right

The bot rotates and scales around the point at the center of the Bot's right face.

[x,y,z]

The bot rotates and scales around the specified point. Should be an array of 3 numbers representing X, Y, and Z respectively. Numbers between 0.5 and -0.5 map to the edges of the bot.

Any 3D Vector

The bot rotates and scales around the specified point. Should be a 3D bot vector representing X, Y, and Z respectively. Numbers between 0.5 and -0.5 map to the edges of the bot.

orientationMode

The mode that determines how the bot automatically rotates.

Possible values are:

ValueDescription
absolute

The bot does not rotate automatically. (default)

billboard

The bot rotates left, right, up, and down automatically to point its top face towards the player.

billboardTop

The bot rotates left and right automatically to point its top face towards the player.

billboardFront

The bot rotates left and right automatically to point its front face towards the player.

maxLODThreshold

The minimum percentage of the screen that the bot form should take up in order to enter the maximum Level-Of-Detail. When the maximum LOD is entered the @onMaxLODEnter listener is triggered. When the maximum LOD is exited the @onMaxLODExit listener is triggered.

ValueDescription
0.03

The bot enters the maximum LOD when it takes up 3% of the screen space. (default)

Numbers > 0 and < 1

The bot enters the maximum LOD when it takes up more screen space than the value.

minLODThreshold

The maximum percentage of the screen that the bot form should take up in order to enter the minimum Level-Of-Detail. When the minimum LOD is entered the @onMinLODEnter listener is triggered. When the minimum LOD is exited the @onMinLODExit listener is triggered.

ValueDescription
0.0005

The bot enters the minimum LOD when it takes up 0.05% of the screen space. (default)

Numbers > 0 and < 1

The bot enters the minimum LOD when it takes up less screen space than the value.

transformer

The ID of the bot that should transform this bot in the bot and miniGridPortals. When the transformer bot and this bot are in the same dimension, this bot will inherit the position and rotation of the transformer bot.

When set on a portal bot (like gridPortalBot), this will transform the portal camera by the specified bot.

ValueDescription
null

The bot is positioned on the grid. (default)

Any String

The bot is positioned on the bot with the given ID.

The custom CSS styles that should be applied to the menu item. Only applies to bots that are being shown in the menu portal.

This is useful for positioning and styling the item in ways that are not possible using normal tags. Overridden by conflicting properties like #color or #labelColor.

When setting this tag via the sheet, it is useful to utilize DNA tags to ensure that the resulting value is considered an object.

Possible values are:

ValueDescription
null

No special styling. (Default)

Any Object

The properties of the object will be applied as special styling to the menu item.

Examples:

  1. Round the top corners of the menu bot.
🧬{
"border-radius": "8px 8px 0 0",
"margin-top": "8px"
}

The custom CSS styles that should be applied to the menu item label. Only applies to bots that are being shown in the menu portal.

This is useful for styling the label in ways that are not possible using normal tags. Overrides conflicting properties like #color or #labelColor.

When setting this tag via the sheet, it is useful to utilize DNA tags to ensure that the resulting value is considered an object.

Note: when using a larger font size you may also need to increase the line-height. The default line-height is "24px".

Possible values are:

ValueDescription
null

No special styling. (Default)

Any Object

The properties of the object will be applied as special styling to the menu item.

Examples:

  1. Use custom font settings on the menu bot label.
🧬{
"font-size": "36px",
"line-height": "36px",
"font-weight": "bold"
}

The mode that menu items should use when the cursor hovers over the bot when it is in the menu portal. Currently only affects menu bots that are buttons (input bots are not hoverable).

Note that this only determines how the menu item looks when the mouse pointer hovers over the item. It does not affect the @onClick, @onPointerEnter, @onPointerExit, etc. listeners.

Possible values are:

ValueDescription
auto

The bot will appear hoverable if it has a @onClick tag. (Default)

hover

The bot will appear hoverable.

none

The bot will not appear hoverable.

The text that has been entered in the menu item's input box. Only has an effect on menu items that have #form set to input.

This tag will also be updated in the tempLocal space when the user types in the input box.

Possible values are:

ValueDescription
null

No text in the input box. (Default)

false

No text in the input box. CasualOS will use this when the user has deleted all the text from the input box and there is a non-null value in the menuItemText tag.

Any String

The text will appear in the input box.

Whether to show the submit button on input menu items even if the input box is empty. Only has an effect on menu items that have #form set to input.

Possible values are:

ValueDescription
false

The submit button will only show when the input box is not empty. (Default)

true

The submit button will always show.