Skip to main content
Version: v3.1.36

Tags

CasualOS has many tags.

Tag types​

Tags are peices of data that are contained in bots. They are used to describe all sorts of properties about a bot, including how the bot looks, where it is visible, and what it does.

Each tag is made up of two parts: a name and a value.

The name is just that: a name. It describes what the value represents and makes the value easily accessible via scripting.

Tag values can be pretty much anything, and CasualOS is able to automatically understand some values based on how they are formatted. For example, CasualOS knows that the string "true" represents the special boolean value true. When we're talking about the different formats that CasualOS automatically understands, we call them tag types. Tag types are the kinds of data that CasualOS automatically understands and supports in built-in tags. Below, you can find a list of the various tag types and how CasualOS understands them.

In some sense, tag types are like how spreadsheet software can automatically detect different data formats and present them in a nice manner. However, unlike spreadsheet software, CasualOS always preserves the original tag values and simply inteprets the ones it understands. The interpreted values are used by built-in tags, but both are available to scripts.

Boolean Tags​

Boolean tags are tags whose value contains a boolean value. That is, either true or false.

Number Tags​

Number tags are tags whose value contains a number value. CasualOS currently supports the following number formats:

  • Integer numbers
    • 123, -123
  • Decimal numbers
    • 1.23, -1.23
    • .23, -.23
  • Scientific notation
    • 1.23E2, 1.23E-2, -1.23E2, -1.23E-2
  • Special numbers
    • Infinity, -Infinity
  • Tagged numbers
    • 🔢123, 🔢-123
    • 🔢1.23, 🔢-1.23
    • 🔢.23, 🔢-.23
    • 🔢1.23E2, 🔢1.23E-2
    • 🔢Infinity, 🔢-Infinity

String Tags​

String tags are tags whose value contains a string value. In CasualOS, tag values that aren't recognized as a number or boolean are treated as strings. Basically, if the tag value is typed in by the user and doesn't look like a boolean or number and isn't started with a tag prefix (i.e. 🔢 for numbers, @ for scripts, 🧬 for mods, etc.), then the tag value is treated like a string.

In addition to this automatic behavior, CasualOS supports using the 📝 emoji to mark a tag value as a string. This is useful in cases where you want the value to start with another prefix but don't want the tag to be interpreted as that tag type. For example, if you want the text to be the word "true" but want the interpreted tag value to be a string instead of a number, you can set the tag value to 📝true.

Mod Tags​

Mod tags are tags whose value is prefixed with 🧬 and contains a JSON value. CasualOS interprets mod tags into JavaScript objects. Mod tags are essentially a convienent way of storing JSON and having CasualOS automatically run the JSON.parse() function on it.

Examples​

🧬{
"firstName": "Bob",
"lastName": "Johnson",
"phoneNumber": "+15555555555"
}

Date Tags​

Date tags are tags whose value is prefixed with the 📅 emoji and contains date and time information. Handling date and time information in JavaScript is complicated, so CasualOS tries to make this as easy as possible by integrating storage of date values. When CasualOS runs across a date tag, it parses the date and converts it into a DateTime object for scripts to use.

CasualOS currently supports the following date formats:

  • Formats that assume the UTC-0 time zone
    • 📅2022: Midnight January 1st on the given year (2022)
    • 📅2022-05: Midnight on the 1st of the given month (May) and year (2022)
    • 📅2022-10-03: Midnight on the given day (3rd), month (October), and year (2022)
    • 📅2022-10-03T07:30:00: Given year (2022), month (October), day (3rd), hour (7), minute (30), and second (0)
  • Formats that use the specified time zone
    • 📅2022-10-03T07:30:00Z: Given year (2022), month (October), day (3rd), hour (7), minute (30), and second (0) in the UTC-0 time zone
    • 📅2022-10-03T07:30:00-05:00: Given year (2022), month (October), day (3rd), hour (7), minute (30), and second (0) in the UTC-5 time zone.
    • 📅2022-10-03T07:30:00 America/New_York: Given year (2022), month (October), day (3rd), hour (7), minute (30), second (0), in the specified IANA time zone(America/New_York)
    • 📅2022-10-03T07:30:00-05:00 America/Chicago: Given year (2022), month (October), day (3rd), hour (7), minute (30), second (0) in the UTC-5 timezone that is converted to the specified IANA time zone(America/Chicago)
    • 📅2022-10-03T07:30:00 local: Given year (2022), month (October), day (3rd), hour (7), minute (30), and second (0) in the local time zone.
    • 📅2022-10-03T07:30:00-05:00 local: Given year (2022), month (October), day (3rd), hour (7), minute (30), and second (0) in the UTC-5 timezone that is converted to the local time zone.

See the documentation on DateTime for information and examples on scripting.

Vector tags​

Vector tags are tags whose value is prefixed with the ➡️ emoji and represents a 2D or 3D point or direction. In math, a vector simply a list of numbers, but in CasualOS a vector specifically refers either to a pair of numbers (representing a 2D vector) or a trio of numbers (representing a 3D vector). When CasualOS runs across a vector tag, it parses the numbers and converts it into a Vector2 or Vector3 object depending on if it contains 2 or 3 numbers.

Vector tags are useful for easily setting the X, Y, and Z components of supported tags like #[dimension]Position.

CasualOS currently supports the following vector formats:

  • 2D vectors
    • ➡️1,2, ➡️-1,-2, ➡️1.23,4.56
  • 3D vectors
    • ➡️1,2,3, ➡️-1,-2,-3, ➡️1.23,4.56,7.89

See the documentation on Vectors for more information and examples for scripting.

Rotation tags​

Rotation tags are tags whose value is prefixed with the 🔁 emoji and represents a 3D rotation or orientation. In math, a rotation represents a change in orientation. This rotation can then be applied to vectors and bots to modify their orientation.

For an interactive explanation of rotations and quaternions, see this video.

When CasualOS runs across a rotation tag, it parses the numbers and converts it into a Rotation object.

Rotation tags are useful for easily setting the X, Y, and Z components of supported tags like #[dimension]Rotation.

CasualOS currently supports the following rotation format:

  • Quaternion
    • 🔁0,0,0,1: Identity rotation (no rotation)
    • 🔁0.7071068,0,0,0.7071068: 90 Degree rotation around the X axis
    • 🔁0,0,0.7071068,0.7071068: 90 Degree rotation around the Z axis

See the documentation on Rotations for more information and examples for scripting.

Script tags​

Script tags are tags whose value is prefixed with the @ symbol and they represent JavaScript code that can be executed by CasualOS in response to user actions. (Like clicking a bot)

Script tags (also known as listeners) must be valid JavaScript code and can perform fairly arbitrary actions. This includes searching, creating and destroying bots, changing bot tags, showing messages to the user, making web requests, saving permanent records, and more.

Script tags that have one of the names listed here can be executed directly by CasualOS. Additionally, it is possible to trigger scripts from other scripts using the shout(name, arg?) and whisper(bot, name, arg?) actions.

For a tutorial on scripting and the basics of CasualOS, check out the Pillars of Casual Simulation. Finally, you can check out the comprehensive list of actions that are supported in CasualOS.

Info Tags​

id​

Read-OnlyVideo

The ID of the bot.

Every bot has an automatically generated unique ID that cannot be changed.

space​

Read-OnlyExample

The space the bot lives in.

Every bot is stored in a space that specifies how long the bot lives and if it is shared with other people.

Possible values are:​

ValueDescription
sharedThe bot is saved in the inst and is shared with everyone else. (default)
localThe bot is saved on the device it was created from and is not shared with other devices.
tempLocalThe bot is not saved (it is temporary) and is not shared with other sessions. When the current session is closed (by refreshing or closing the tab), the bot is destroyed.
tempSharedThe bot is not saved (it is temporary) and is shared with everyone else. Bots in this space show up in the `remoteTempShared` space to other devices. Only the current session can create, edit, and destroy bots in this space. When the current session is closed, the bot is destroyed.
remoteTempSharedThe bot is not saved (it is temporary) and is shared with everyone else. Bots appear in this space when another remote puts a bot in their `tempShared` space. Only the other remote's session can create, edit, and destroy bots in this space. When the other remote's session is closed, the bot is destroyed.
historyThe bot represents a mark (save point). The history space is not available by default. You need to use the server.browseHistory() function to load it. Additionally, the history space is read-only. This means that bots cannot be added or removed from it and they also cannot be edited.
adminThe bot is saved on the server and is shared across all instances. Admin space is initially locked whenever a new session starts. While locked, it is impossible to create, update, or destroy bots in the admin space. You must use the adminSpace.unlock(password) function to unlock it.
certifiedThe bot represents a cryptographic certificate. Certified bots cannot be edited or destroyed using traditional means. Instead, you can create and destroy certificates using the crypto.createCertificate(certificate, password, keypair) andcrypto.revokeCertificate(certificate, password, signer?) functions.

Record Spaces​

Records can be stored in spaces as well. Like bot spaces, record spaces determine how long the record lives and if it is shared with other people.

Possible values are:​

ValueDescription
tempRestrictedThe record is saved but will be deleted at the end of the day and is only retrievable by the user and appBundle that created them. (default)
tempGlobalThe record is saved but will be deleted at the end of the day and it is shared with everyone.
permanentRestrictedThe record is saved and is only retrievable by the user and appBundle that created them.
permanentGlobalThe record is saved and is shared with everyone.

creator​

The ID of the bot that created this bot. The creator bot must be in the same space as this bot.

Behavior Tags​

These tags affect how CasualOS allows the users to interact with bots.

draggable​

Whether the bot is able to be moved by the built-in CasualOS system.

Note that this value only controls whether CasualOS can move bots automatically as the result of user interaction. If set to false, then CasualOS will not change any tags, but it will still send events for the bot (e.g. @onDrag, @onAnyBotDrag, @onDrop, @onAnyBotDrop, etc.).

Possible values are:​

ValueDescription
trueThe bot is able to be dragged. (default)
falseThe bot cannot be dragged.

pointable​

Whether the bot interacts with the pointer.

Bots that are pointable can receive clicks, pointer enter/exit, and drop events. Note that the #pointable tag also affects whether the content inside an iframe form is interactable.

Possible values are:​

ValueDescription
trueThe bot interacts with the pointer. (default)
falseThe bot does not interact with the pointer.

focusable​

Whether the bot is able to be focused.

Bots that are focusable can receive focus events like @onFocusEnter.

Possible values are:​

ValueDescription
trueThe bot is focusable. (default)
falseThe bot is not focusable.

destroyable​

Whether the bot is able to be destroyed.

Possible values are:​

ValueDescription
trueThe bot will be able to be destroyed. (default)
falseThe bot will not be able to be destroyed.

editable​

Whether the bot is able to be edited in the sheet in Channel Designer.

Possible values are:​

ValueDescription
trueThe bot can be edited via the sheet. (default)
falseThe bot cannot be edited via the sheet. (including being able to set editable back to true)

listening​

Determines whether this bot responds to whispers or shouts. If this tag is set to true it will respond to them. If set to false, it will not.

Possible values are:​

ValueDescription
trueThe bot will respond to whispers and shouts. (default)
falseThe bot will not respond to whispers or shouts.

system​

The "system" that this bot represents. Bots with a #system tag will be able to appear in the systemPortal. The you can kinda think of the #system tag as the name that the systemPortal uses for bots. #system tag values should ideally be three sections separated by a ..

Note that this tag can be changed by using the #systemTagName tag.

For example, the first section might be the name of the app bundle, the second section would be the area that the bot belongs in, and the third section would be the name of the bot. e.g. myAppBundle.managers.timeline would specify that a bot belongs in myAppBundle and is one of the manager bots. The systemPortal would then show each bot organized by #system tag.

Image of bots in the systemPortal

Possible values are:​

ValueDescription
null(default)
Any StringThe system that this bot belongs to.

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.
clearThe 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
lineDisplays the line without additional decoration. (Default)
arrowDisplays the line with an arrow at the tip pointing to the target bot.
wallDisplays the line as a vertical wall.

lineWidth​

The width of the lines from this bot.

Possible values are:​

ValueDescription
1The width of the line is 1 unit. (default)
Any Number > 0The 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 <= 1The 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
autoThe label font size is automatically scaled to fit the text in the bot. (Default)
Any Number > 0The 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
0There is no space between the edge of the bot and the edge of the label. (Default)
Any Number > 0The 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
0There is no space between the edge of the bot and the edge of the label. (Default)
Any Number > 0The 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
0There is no space between the edge of the bot and the edge of the label. (Default)
Any Number > 0The 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
normalDon't automatically scale the label size. (default)
autoAutomatically 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.

labelAlignment​

The text alignment for the label.

Possible values are:​

ValueDescription
centerThe text is aligned around the center of the face that the label is anchored to. (default)
leftThe text is aligned on the left side of the face that the label is anchored to.
rightThe 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
robotoSpecifies that the Roboto font should be used. (default)
noto-sans-krSpecifies that the Noto Sans KR font should be used. This is a font with support for the Korean language.
Any URLSpecifies 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
breakCharactersLine breaks may be inserted inside a word to fit the label on the bot. (default)
breakWordsLine breaks may be inserted between words to fit the label on the bot.
noneLine breaks will not be inserted.

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
fitThe form is scaled to fit inside the bot's unit cube. The aspect ratio will be preserved. (default)
absoluteThe form is not scaled.

form​

The shape that the bot should be displayed as.

Possible values are:​

ValueDescription
cubeCube mesh (default)
skyboxA Sphere mesh optimal for "skybox" implementation.
sphereSphere mesh
spriteCamera facing (billboarded) sprite/quad images.
meshA mesh loaded from the web. See #formSubtype for additional options.
frustumA camera frustum mesh.
helixA double helix mesh (like DNA).
eggA egg mesh.
hexA hexagon mesh.
circleA circle mesh.
keyboardAn interactive keyboard. Clicking the keys will generate @onKeyClick whispers that are sent to the bot.
iframeA webpage loaded into a 3D iframe. See #formSubtype for additional options.
dimensionThe bot will display the dimension specified by #formAddress.
portalThe bot will display the dimension specified by #formAddress. This is an alias for "dimension".
spherePortalThe bot will display the dimension specified by #formAddress in a spherical manner, using the X and Y coordinates as latitude and longitude coordinates.
cursorThe 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.

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

formSubtype​

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

Possible values are:​

ValueDescription
nullNo subtype (default)
gltfA GLTF mesh loaded from a URL.
htmlThe HTML code that should be loaded into an iframe when #form is set to iframe. (Default when #form is set to iframe)
srcThe URL that should be loaded into an iframe when #form is set to iframe.

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
1Square aspect ratio. (default)
Any NumberCustom aspect ratio.

formAnimation​

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

ValueDescription
nullPlay the first animation.
falseStops animating the mesh.
Any StringPlay the animation with the given name.
Any Integer >= 0Play the animation at the given index. Useful for exploring possible animations if you don't have the name.
An array of numbers or stringsPlays 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
nullUse the animations that were built into the mesh.
Any URLUse the animations from the given GLTF file.

formOpacity​

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

Possible values are:​

ValueDescription
1(default)
Any Number >= 0 and <= 1The 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
0Use the automatic render ordering. (Default)
Any NumberUse the given render ordering. Bots are rendered from the highest value to the lowest value.

gltfVersion​

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

Possible values are:​

ValueDescription
2Load the GLTF model with version 2 of the specification. (default)
Numbers < 2Load 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.

anchorPoint​

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

Possible values are:​

ValueDescription
bottomThe bot rotates and scales around its bottom point. (default)
centerThe bot rotates and scales around its center point.
frontThe bot rotates and scales around the point at the center of the Bot's front face.
backThe bot rotates and scales around the point at the center of the Bot's back face.
topThe bot rotates and scales around its top point.
leftThe bot rotates and scales around the point at the center of the Bot's left face.
rightThe 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 VectorThe 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
absoluteThe bot does not rotate automatically. (default)
billboardThe bot rotates left, right, up, and down automatically to point its top face towards the player.
billboardTopThe bot rotates left and right automatically to point its top face towards the player.
billboardFrontThe 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.03The bot enters the maximum LOD when it takes up 3% of the screen space. (default)
Numbers > 0 and < 1The 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.0005The bot enters the minimum LOD when it takes up 0.05% of the screen space. (default)
Numbers > 0 and < 1The 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
nullThe bot is positioned on the grid. (default)
Any StringThe 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
nullNo special styling. (Default)
Any ObjectThe 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
nullNo special styling. (Default)
Any ObjectThe 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
autoThe bot will appear hoverable if it has a @onClick tag. (Default)
hoverThe bot will appear hoverable.
noneThe 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
nullNo text in the input box. (Default)
falseNo 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 StringThe 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
falseThe submit button will only show when the input box is not empty. (Default)
trueThe submit button will always show.

Dimension Tags​

[dimension]​

Add a bot to a dimension.

Example: Set #room1 to true for the bot to appear in a dimension named room1.

Possible values are:​

ValueDescription
falseRemoves the bot from the dimension. (default)
truePuts the bot into the dimension.

[dimension]SortOrder​

The order that the bot should be in a stack of bots.

When bots are stacked, they are placed from the bottom to the top based on the sort order. So a bot with a sort order of 1 is going to be placed on top of a bot with a sort order of 2.

Possible values are:​

ValueDescription
Any NumberSpecifies the sort order of a bot in a stack of bots. (Default is 0)

[dimension]Position​

The vector position of a bot on the grid in the specified dimension. Must be a vector type. If not specified or the value is not a vector, then #[dimension]X, #[dimension]Y, and #[dimension]Z will be used.

Integer values are mapped directly to the grid. e.g. 1.5 means halfway between the 1 and 2 grid squares.

Possible values are:​

ValueDescription
➡️0,0,0The bot will be placed in the center of the grid. (Default)
Any VectorSpecifies the X, Y, and Z position of a bot in a dimension.

Examples​

Place this bot at (1, 2, 3) in the home dimension.
tags.homePosition = new Vector3(1, 2, 3);
Toast the position of this bot in the home dimension.
const homePosition = getBotPosition(thisBot, 'home');
os.toast('home Position: ' + homePosition);

[dimension]X​

The X (east-west) position of a bot on the grid in the specified dimension.

Integer values are mapped directly to the grid. e.g. 1.5 means halfway between the 1 and 2 grid squares.

Possible values are:​

ValueDescription
Any NumberSpecifies the X position of a bot in a dimension. (Default is 0)

[dimension]Y​

The Y (north-south) position of a bot on the grid in the specified dimension.

Integer values are mapped directly to the grid. e.g. 1.5 means halfway between the 1 and 2 grid squares.

Possible values are:​

ValueDescription
Any NumberSpecifies the Y position of a bot in a dimension. (Default is 0)

[dimension]Z​

The Z (up-down) offset that the bot is offset above/below the grid.

Possible values are:​

ValueDescription
Any NumberSpecifies the Z position of a bot in a dimension. (Default is 0)

[dimension]Rotation​

The rotation in that the bot should be oriented by in the specified dimension. Must be a rotation type. If not specified or the value is not a rotation, then #[dimension]RotationX, #[dimension]RotationY, and #[dimension]RotationZ will be used.

Possible values are:​

ValueDescription
🔁0,0,0,1The bot will be placed flat on the grid. (Default)
Any RotationSpecifies the rotation of a bot in a dimension.

Examples:​

Rotate this bot by 90 degrees around the X axis in the home dimension
tags.homeRotation = new Rotation({
axis: new Vector3(1, 0, 0),
angle: Math.PI / 2
});
Toast the rotation of this bot in the home dimension
const homeRotation = getBotRotation(thisBot, 'home');
os.toast('home Rotation: ' + homeRotation);

Possible values are:​

ValueDescription
Any NumberSpecifies the X rotation of a bot in a dimension. (Default is 0)

[dimension]RotationX​

The X (pitch) rotation in radians that the bot should be rotated by.

Possible values are:​

ValueDescription
Any NumberSpecifies the X rotation of a bot in a dimension. (Default is 0)

[dimension]RotationY​

The Y (roll) rotation in radians that the bot should be rotated by.

Possible values are:​

ValueDescription
Any NumberSpecifies the Y rotation of a bot in a dimension. (Default is 0)

[dimension]RotationZ​

The Z (yaw) rotation in radians that the bot should be rotated by.

Possible values are:​

ValueDescription
Any NumberSpecifies the Z rotation of a bot in a dimension. (Default is 0)

[dimension]Start​

The start value for bots that are in the multi-line editor (tag portal/sheet portal).

For cursor bots, this value indicates the character index that selection starts at.

For codeButton bots, this value indicates the line number that the button should appear above.

For codeHint bots, this value can indicate the character index that the hint starts at. Alternatively, it can indicate the line and column numbers that the hint starts at.

Possible values are:​

ValueDescription
Any NumberSpecifies the value at which the bot starts in the dimension. (Default is 0)
Any VectorSpecifies the line (x component) and column (y component) that the hint starts at. Only applicable to codeHint bots.

[dimension]End​

The end value for bots that are in the multi-line editor (tag portal/sheet portal).

For cursor bots, this value indicates the character index that the selection stops at.

The codeButton bots, this value indicates the priority for the button. Priority determines the order that buttons on the same line are shown in. (Higher numbers means lower priority)

For codeHint bots, this value can indicate the character index that the hint end at. Alternatively, it can indicate the line and column numbers that the hint end at.

Possible values are:​

ValueDescription
Any NumberSpecifies the index at which the bot ends in the dimension. (Default is 0)
Any VectorSpecifies the line (x component) and column (y component) that the hint ends at. Only applicable to codeHint bots.

Portal Bot Tags​

These tags are used to configure portals. They can be set on the corresponding portal bot.

Some of them are automatically set by the corresponding portal but most of them (like the cameraPositionOffset tags) can be changed manually.

portalColor​

The color of the background of the portal.

Possible values are:​

ValueDescription
#263238(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.

portalCursor​

The cursor that should be used when the mouse is hovered over the portal. The portal cursor is overriden when a bot with a #cursor tag is hovered.

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.

portalCursorHotspot​

The X 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.

portalBackgroundAddress​

The URL of the image or video that should be displayed as the background of the portal.

When specified, this tag overrides ##portalColor. Additionally, this tag does nothing when in VR.

Possible values are:​

ValueDescription
null(default)
Any URLSpecifies that the portal background should use the given image or video.
"casualos://camera-feed"Display a feed of the main camera as the background.
"casualos://camera-feed/rear"Display a feed of the rear (environment) facing camera as the background.
"casualos://camera-feed/front"Display a feed of the front (user) facing camera as the background.

portalLocked​

Determines if the portal can be loaded.

Possible values are:​

ValueDescription
trueThe portal can be loaded. (Default)
falseThe portal cannot be loaded.

portalPannable​

Whether the player will be able to pan the camera inside the portal.

Possible values are:​

ValueDescription
trueThe camera is pannable in this portal. (Default)
falseThe camera is not pannable in this portal.

portalPannableMin​

The minimum values that the camera can pan to in the portal.

See the documentation on Vectors for more info.

Possible values are:​

ValueDescription
Any VectorMinimum X and Y values that the camera can pan to. (Default is Negative Infinity)

portalPannableMax​

The maximum X and Y values that the camera can pan to in the portal.

See the documentation on Vectors for more info.

Possible values are:​

ValueDescription
Any VectorMaximum X and Y values that the camera can pan to. (Default is Infinity)

portalRotatable​

Whether the player will be able to rotate the camera inside the miniGridPortal.

Possible values are:​

ValueDescription
trueThe miniGridPortal is rotatable. (Default)
falseThe miniGridPortal is not rotatable.

portalCameraRotation​

The up and down rotation that the camera starts at in the portal. Units are in radians.

Because the bot and miniGridPortals use polar coordinates to orbit around the focus point, we only need two numbers to specify where the camera should be pointing. Polar coordinates work by specifying two angles (X and Y - also known as "phi" and "theta") which position the camera around its focus point. Therefore, these rotation values actually cause the camera to turn around the focus point and not simply turn the camera itself.

The X angle (phi) is used to rotate the camera up and down. Mathematically, a value of 0 means the camera is facing directly down and a value of π / 2 means the camera is perfectly parallel with the ground. For usability reasons, CasualOS limits this value to between 0 and 58 degrees (~1.01229 radians).

The Y angle (theta) is used to rotate the camera left and right. Mathematically, a value of 0 means the camera is facing the front face of bots and a value of π / 2 means the camera is facing the left face of the bots.

See the documentation on Vectors for more info.

Possible values are:​

ValueDescription
Any VectorThe X and Y rotation values that should be used for the initial camera rotation. Units are in radians.

portalZoomable​

Whether the player will be able to zoom the camera inside the portal.

Possible values are:​

ValueDescription
trueThe camera is zoomable in this portal. (Default)
falseThe camera is not zoomable in this portal.

portalZoomableMin​

The minimum value that the camera can zoom to in the portal. Does not affect VR/AR sessions. For the mapPortal and miniMapPortal, the value is measured in meters.

Possible values are:​

ValueDescription
Any Number > 0Minimum value that the camera zoom to. (Default is 0.4 for the grid portals and -Infinity for the map portals)

portalZoomableMax​

The maximum value that the camera can zoom to in the portal. Does not affect VR/AR sessions. For the mapPortal and miniMapPortal, the value is measured in meters.

Possible values are:​

ValueDescription
Any Number > 0Maximum value that the camera can zoom to. (Default is 80 for the grid portals and EARTH_RADIUS * 4 for the map portals)

portalCameraZoom​

The zoom value that the camera starts at in the portal.

Possible values are:​

ValueDescription
Any Number > 0The initial zoom value. (Default is 1)

portalGridScale​

The size of bots in the portal.

Possible values are:​

ValueDescription
Any Number > 0The size of bots in the portal. (Default is 0.025 for wrist portals and 0.2 for all other portals)

portalSurfaceScale​

The scale of surfaces.

Possible values are:​

ValueDescription
Any Number > 0The scale of surface for the dimension. (Default is 2)

portalCameraControls​

The mode that specifies how the camera controls work in the portal.

Possible values are:​

ValueDescription
"player"Specifies that the player should be able to control the camera. Individual options like #portalZoomable override this option.
falseSpecifies that the player should not be able to control the camera in the portal.

portalShowFocusPoint​

Whether the focus point of the portal camera should be shown as a small sphere.

The focus point is the position that the camera orbits (rotates) around and is always facing.

When a bot is between the focus point and the camera, then focus events will trigger.

Possible values are:​

ValueDescription
falseDon't show an indicator for the focus point. (Default)
trueShow an indicator for the focus point.

portalCameraType​

The type of camera that should be used for the portal. The "type" of a camera determines how objects are visualized and how they appear. Conceptually, camera types are similar to camera lenses.

Possible values are:​

ValueDescription
orthographicThe camera uses an orthographic projection. This camera type preserves parallel lines so lines that are parallel to each other will remain parallel in the 2D image. As a consequence, objects that are the same size always appear the same size no matter how far away they are from the camera. (Default)
perspectiveThe camera uses a perspective projection. This camera type makes objects appear larger or smaller based on how far away they are from the camera.

portalDisableCanvasTransparency​

Whether to disable transparency on the canvas element that the 3D content is displayed on.

Set this tag to true on the grid portal to fix rendering issues with 3D models that use alpha cutoff. Note that when this value is true, iframe forms will cease to function properly.

Possible values are:​

ValueDescription
falseThe canvas element is transparent to support iframe forms. (Default)
trueThe canvas element is not transparent 3D models that use alpha cutoff.

miniPortalHeight​

Sets the initial height of the viewport for the miniGridPortal/miniMapPortal.

This should be the percentage of the "available screen height" that the miniGridPortal/miniMapPortal should take. The "available screen height" is a portion of the full screen calculated such that when there is some space left between the left and right edges of the screen there will be some space at the bottom of the portal. However, when the #miniPortalWidth tag is set to 1, there will be no space between the bottom of the screen and the bottom of the portal.

Possible values are:​

ValueDescription
Numbers >= 0 and <= 1The percentage of the screen height that the portal should take. (Default is 0.2)

miniPortalWidth​

Sets the width of the viewport for the miniGridPortal/miniMapPortal. This should be a percentage between 0 and 1 that specifies how much of the screen width should be taken.

Possible values are:​

ValueDescription
Numbers >= 0 and <= 1The percentage of the screen width that the portal should take. (Default is 0.8)

miniPortalResizable​

Whether the player will be able to resize the viewport for the miniGridPortal/miniMapPortal.

Possible values are:​

ValueDescription
trueThe portal is resizable. (Default)
falseThe portal is not resizable.

mapPortalBasemap​

Sets the style of the bottom layer of the map in the mapPortal/miniMapPortal.

Possible values are:​

ValueDescription
dark-gray(Default)
Any BasemapSee this for a full list.

wristPortalHeight​

The number of grid spaces that the wrist portal should have in the Y direction.

Possible values are:​

ValueDescription
Numbers >= 1The number of of grid spaces that the portal should have in the Y direction. (Default is 6)

wristPortalWidth​

The number of grid spaces that the wrist portal should have in the X direction.

Possible values are:​

ValueDescription
Numbers >= 1The number of of grid spaces that the portal should have in the X direction. (Default is 6)

meetPortalVisible​

Whether the meet portal should be visible. This is useful for hiding the meet portal while still in a meeting.

Possible values are:​

ValueDescription
trueThe meet portal will be visible. (Default)
falseThe meet portal will be hidden.

meetPortalAnchorPoint​

The position on the screen that the meet portal should be anchored to. Overrides any conflicting properties set by #meetPortalStyle.

Possible values are:​

ValueDescription
fullscreenThe meet portal will occupy the entire screen. (Default)
topThe meet portal will occupy the top of the screen.
topRightThe meet portal will occupy the top-right corner of the screen.
topLeftThe meet portal will occupy the top-left corner of the screen.
bottomThe meet portal will occupy the bottom of the screen.
bottomRightThe meet portal will occupy the bottom-right corner of the screen.
bottomLeftThe meet portal will occupy the bottom-left corner of the screen.
leftThe meet portal will occupy the left side of the screen.
rightThe meet portal will occupy the right side of the screen.
[top, right, bottom, left]The meet portal will use the given values for the CSS [top](https://developer.mozilla.org/en-US/docs/Web/CSS/top), [right](https://developer.mozilla.org/en-US/docs/Web/CSS/right), [left](https://developer.mozilla.org/en-US/docs/Web/CSS/left), and [bottom](https://developer.mozilla.org/en-US/docs/Web/CSS/bottom) properties of the container.

meetPortalStyle​

The custom CSS styles that should be applied to the meet portal container. This is useful for positioning the meet portal in ways that are not possible using #meetPortalAnchorPoint. Overridden by conflicting properties set by #meetPortalAnchorPoint.

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
nullNo special styling. (Default)
Any ObjectThe properties of the object will be applied as special styling to the meet portal container.

Examples​

  1. Put the meet portal in the center of the screen.
🧬{
"top": "10%",
"bottom": "10%",
"left": "10%",
"right": "10%",
}

meetPortalPrejoinEnabled​

Whether the meet portal should have the prejoin screen enabled. The prejoin screen is where the user can setup their display name, microphone, camera, and other settings, before actually joining the meet.

Possible values are:​

ValueDescription
trueThe prejoin screen is enabled. (Default)
falseThe prejoin screen is disabled.

meetPortalStartWithVideoMuted​

Whether the meet portal should start with video muted. Video in this context is equivalent to the user's camera.

Possible values are:​

ValueDescription
trueThe meet portal starts with video muted. (Default)
falseThe meet portal starts with video unmuted.

meetPortalStartWithAudioMuted​

Whether the meet portal should start with audio muted. Audio in this context is equivalent to the user's microphone.

Possible values are:​

ValueDescription
trueThe meet portal starts with audio muted.
falseThe meet portal starts with audio unmuted. (Default)

meetPortalRequireDisplayName​

Whether the meet portal should require the user define a display name.

Possible values are:​

ValueDescription
trueThe meet portal requires a user display name. (Default)
falseThe meet portal does not require a user display name.

meetPortalDisablePrivateMessages​

Whether the meet portal should hide the option to send private chat messages to other participants.

Possible values are:​

ValueDescription
falseThe meet portal allows sending private messages to other participants. (Default)
trueThe meet portal hides the option to start a new private message chat with another participant. Replies to private messages are still allowed.

meetPortalLanguage​

The language that should be used for the meet portal interface by default. Only works if this tag is set before the meet portal is loaded.

Possible Values are:​

ValueDescription
nullThe user-configured value will be used for the meetPortal interface. (Default)
Any ISO 639-1 CodeThe interface will use the given ISO 639-1 language code. Note that not all langauge codes are supported. The full list of supported translations can be found here.

meetPortalJWT​

The JSON Web Token (JWT) that should be used to join the meeting. Used to give the current user moderator permissions.

Possible Values are:​

ValueDescription
nullThe user will be a normal user in the meet portal. (Default)
Any StringThe user will use the JWT for authentication in the meet portal. Depending on the settings used to create the JWT, this may make the user a moderator.

botPortalAnchorPoint​

The position on the screen that the bot portal should be anchored to. Overrides any conflicting properties set by #botPortalStyle

Possible values are:​

ValueDescription
fullscreenThe bot portal will occupy the entire screen. (Default)
topThe bot portal will occupy the top of the screen.
topRightThe bot portal will occupy the top-right corner of the screen.
topLeftThe bot portal will occupy the top-left corner of the screen.
bottomThe bot portal will occupy the bottom of the screen.
bottomRightThe bot portal will occupy the bottom-right corner of the screen.
bottomLeftThe bot portal will occupy the bottom-left corner of the screen.
leftThe bot portal will occupy the left side of the screen.
rightThe bot portal will occupy the right side of the screen.
[top, right, bottom, left]The bot portal will use the given values for the CSS [top](https://developer.mozilla.org/en-US/docs/Web/CSS/top), [right](https://developer.mozilla.org/en-US/docs/Web/CSS/right), [left](https://developer.mozilla.org/en-US/docs/Web/CSS/left), and [bottom](https://developer.mozilla.org/en-US/docs/Web/CSS/bottom) properties of the container.

botPortalStyle​

The custom CSS styles that should be applied to the bot portal container. This is useful for positioning the tag portal in ways that are not possible using #botPortalAnchorPoint. Overridden by conflicting properties set by #botPortalAnchorPoint.

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
nullNo special styling. (Default)
Any ObjectThe properties of the object will be applied as special styling to the bot portal container.

Examples​

  1. Put the bot portal in the center of the screen.
🧬{
"top": "10%",
"bottom": "10%",
"left": "10%",
"right": "10%",
}

tagPortalAnchorPoint​

The position on the screen that the tag portal should be anchored to. Overrides any conflicting properties set by #tagPortalStyle.

Possible values are:​

ValueDescription
fullscreenThe tag portal will occupy the entire screen. (Default)
topThe tag portal will occupy the top of the screen.
topRightThe tag portal will occupy the top-right corner of the screen.
topLeftThe tag portal will occupy the top-left corner of the screen.
bottomThe tag portal will occupy the bottom of the screen.
bottomRightThe tag portal will occupy the bottom-right corner of the screen.
bottomLeftThe tag portal will occupy the bottom-left corner of the screen.
leftThe tag portal will occupy the left side of the screen.
rightThe tag portal will occupy the right side of the screen.
[top, right, bottom, left]The tag portal will use the given values for the CSS [top](https://developer.mozilla.org/en-US/docs/Web/CSS/top), [right](https://developer.mozilla.org/en-US/docs/Web/CSS/right), [left](https://developer.mozilla.org/en-US/docs/Web/CSS/left), and [bottom](https://developer.mozilla.org/en-US/docs/Web/CSS/bottom) properties of the container.

tagPortalStyle​

The custom CSS styles that should be applied to the tag portal container. This is useful for positioning the tag portal in ways that are not possible using #tagPortalAnchorPoint. Overridden by conflicting properties set by #tagPortalAnchorPoint.

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
nullNo special styling. (Default)
Any ObjectThe properties of the object will be applied as special styling to the tag portal container.

Examples​

  1. Put the tag portal in the center of the screen.
🧬{
"top": "10%",
"bottom": "10%",
"left": "10%",
"right": "10%",
}

tagPortalShowButton​

Whether the tag portal should show a button that allows a custom action. When set to true, the button will be displayed in the lower right hand corner of the tag portal.

Clicking the button will trigger a @onClick on the tag portal config bot.

Possible values are:​

ValueDescription
falseNo button is shown. (Default)
trueThe button is shown.

tagPortalButtonIcon​

The Material Icon that should be shown on the tag portal button.

Possible values are:​

ValueDescription
Empty StringNo icon. (Default)
Any Material IconSee https://material.io/resources/icons/?style=baseline.

tagPortalButtonHint​

The tooltip that should be shown on the tag portal button.

Possible values are:​

ValueDescription
Empty StringNo hint. (Default)
Any StringThe text that should be displayed as a hint when the user hovers their mouse over the button.

The custom CSS styles that should be applied to the menu portal container. This is useful for positioning the menu portal in ways that are not possible normally.

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
nullNo special styling. (Default)
Any ObjectThe properties of the object will be applied as special styling to the menu portal container.

Examples​

  1. Make the menu portal 80% of the screen width.
🧬{
"width": "80%",
}

sheetPortalShowButton​

Whether the sheet portal should show a button that allows a custom action. When set to true, the button will be displayed in the lower right hand corner of the sheet portal.

Clicking the button will trigger a @onClick on the sheet portal config bot. If there is no @onClick, then the sheet portal will be closed.

Possible values are:​

ValueDescription
trueThe button is shown. (Default)
falseNo button is shown.

sheetPortalButtonIcon​

The Material Icon that should be shown on the sheet portal button.

Possible values are:​

ValueDescription
web_assetThe Web Asset icon. (Default)
Any Material IconSee https://material.io/resources/icons/?style=baseline.

sheetPortalButtonHint​

The tooltip that should be shown on the sheet portal button.

Possible values are:​

ValueDescription
Grid Portal"Grid Portal" (Default)
Any StringThe text that should be displayed as a hint when the user hovers their mouse over the button.

sheetPortalAllowedTags​

The list of tags that should be allowed in the sheet portal.

Possible values are:​

ValueDescription
nullAll tags are allowed. (Default)
Any ArrayOnly the specified tags can be shown in the sheet portal.

sheetPortalAddedTags​

The list of tags that should be shown in the sheet even if they do not have a value.

Possible values are:​

ValueDescription
nullNo additional tags are shown. (Default)
Any ArrayThe specified tags are shown in the sheet portal.

pixelWidth​

AutomaticgridPortalBot

The width of the grid portal in pixels. Because the miniGridPortal is contained by the grid portal, this value also applies to the miniGridPortal.

Note that a device with a larger pixel value is not necessarily physically larger than a device with a smaller pixel value. Additionally, a device with a larger width than height does not necessarily mean that it is in landscape mode.

Finally, #pixelHeight and #pixelWidth use CSS pixels which are dependent on the #defaultPixelRatio specified by the web browser. You can find the physical pixel width of the device by calculating pixelWidth * defaultPixelRatio.

pixelHeight​

AutomaticgridPortalBot

The height of the grid portal in pixels. Because the miniGridPortal is contained by the grid portal, this value also applies to the miniGridPortal.

Note that a device with a larger pixel value is not necessarily physically larger than a device with a smaller pixel value. Additionally, a device with a larger height than width does not necessarily mean that it is in portrait mode.

Finally, #pixelHeight and #pixelWidth use CSS pixels which are dependent on the #defaultPixelRatio specified by the web browser. You can find the physical pixel width of the device by calculating pixelHeight * defaultPixelRatio.

pixelRatio​

Config Bot

The pixel ratio that should be used to determine how many physical pixels should be used to draw each pixel in the 3D portals. Higher values will make the 3D portals appear smoother but will also cause CausalOS to run slower.

Possible values are:​

ValueDescription
nullUse the default pixel ratio. (Default)
Any Number > 0The pixel ratio that should be used.

defaultPixelRatio​

AutomaticConfig Bot

The pixel ratio that is used when the #pixelRatio tag is not set. This value is determined by the web browser and cannot be changed. High resolution/Retina displays tend to have a pixel ratio of 2 or higher while devices with lower resolution displays tend to have a pixel ratio of 1.

pointerPixel​

AutomaticgridPortalBot

The X and Y position (location along width) of the pointer (usually mouse, but can also be the position of the first finger to touch the screen) in the grid portal in pixels.

Larger X values are closer to the right of the screen and lower values are closer to the left part of the screen.

Larger Y values are closer to the bottom of the screen and lower values are closer to the top part of the screen.

cameraPosition​

The 3D position of the player's camera in the grid portal.

See the documentation on Vectors for more info.

cameraPositionOffset​

The offset that should be applied to the 3D position of the player's camera in the grid portal.

Useful for moving the player around in VR.

See the documentation on Vectors for more info.

cameraRotation​

The 3D rotation of the player's camera in the grid portal.

Units are in radians.

See the documentation on Rotations for more info.

cameraRotationOffset​

The offset that should be applied to the 3D rotation of the player's camera in the grid portal.

Units are in radians.

See the documentation on Rotations for more info.

cameraZoom​

The zoom value that the camera is at. This is an arbitrary value that specifies how far the camera is zoomed in or out.

Larger values indicate that the camera is zoomed in more (objects appear bigger) and smaller values indicate that the camera is zoomed out (objects appear smaller).

cameraZoomOffset​

The offset that should be applied to the camera zoom. You can use this to change the zoom of the camera.

Larger values indicate that the camera is zoomed in more (objects appear bigger) and smaller values indicate that the camera is zoomed out (objects appear smaller).

cameraFocus​

The 3D position of the focus point for the player's camera in the grid portal.

See the documentation on Vectors for more info.

imuSupported​

Automatic

Whether IMU data is supported on this device.

deviceRotation​

Automatic

The 3D rotation of the device as determined by the IMU.

See the documentation on Rotations for more info.

History Tags​

History tags are tags that are automatically applied to bots in the history space.

history​

History Bot

Whether the bot is in the history dimension.

markHash​

History Bot

The SHA-256 hash that the mark represents.

previousMarkHash​

History Bot

The #markHash of the mark that was created before this mark. You can use this tag as a way to find previous marks from a mark.

markTime​

History Bot

The time that the mark was created.

Config bot Tags​

All tags on the config bot will be synced with the URL query parameters. This means that setting the #abc tag on the config bot to hello will update the URL to include abc=hello. It also means that putting miniGridPortal=myDimension into the query string will set the #miniGridPortal tag to myDimension.

inst​

Config Bot

The instance that is loaded into CasualOS.

theme​

Config Bot

The theme that CasualOS should use.

Possible values are:​

ValueDescription
nullCasualOS is displayed with a color theme matching the system default. (Default)
lightCasualOS is displayed with a white-like-paper color theme.
darkCasualOS is displayed with a dark theme.

Only available on the config bot.

gridPortal​

Config Bot

The dimension that is loaded into the 'grid' portal in CasualOS. This is the portal that is loaded by default. Only available on the config bot.

miniGridPortal​

Config Bot

The dimension that is loaded into the "mini" portal in CasualOS. Only available on the config bot.

sheetPortal​

Config Bot

The dimension that is loaded into the "sheet" portal in CasualOS. Only available on the config bot.

systemPortal​

Config Bot

The search value that is loaded into the "system" portal in CasualOS. Setting this to true will show every bot that has a #system tag in the system portal. Only available on the config bot.

systemTagName​

Config Bot

The name of the tag that should be used when showing bots in the systemPortal. For example, setting #systemTagName on the configBot to "test" will cause the systemPortal to only show bots that have a "test" tag instead of a "system" tag.

Possible values are:​

ValueDescription
nullThe "system" tag is used. (Default)
Any StringThe given tag is used.

Only available on the config bot.

Examples​

  1. Use the "myCustomSystem" tag for the systemPortal instead of the "system" tag.
configBot.tags.systemPortalTagName = "myCustomSystem";

systemPortalBot​

Config Bot

The ID of the bot that is selected in the systemPortal. Only available on the config bot.

systemPortalTag​

Config Bot

The name of the tag that is selected in the systemPortal.

Defaults to system.

Only available on the config bot.

systemPortalTagSpace​

Config Bot

The space of the tag that is selected in the systemPortal. If null, then the tag space is the same as the #systemPortalBot space. Only available on the config bot.

systemPortalSearch​

Config Bot

The value that should be used to search across all the tags in all the bots in the inst. The results of the search will be displayed in the systemPortal. Only available on the config bot.

systemPortalDiff​

The name of the tag should be used as a second system portal to compare with the tag specified by the #systemPortalTag (system by default).

If both the #systemPortal and #systemPortalDiff tags are specified, then the system portal will be shown comparing bots whose system matches.

For example, if #systemPortal is set to true and #systemPortalDiff is set to history, then a Bot that has #system set to my.system will be compared with another bot that has #history set to my.system. The result of this comparision will be shown in the system portal, indicating what was changed between the two bots.

systemPortalDiffBot​

The ID of the bot that is currently selected in the system portal diff. Only available on the config bot.

systemPortalDiffTag​

The name of the tag that is currently selected in the system portal diff. Only available on the config bot.

systemPortalDiffTagSpace​

The space of the tag that is selected in the system portal diff. If null, then the tag space is the same as the #systemPortalDiffBot space. Only available on the config bot.

systemPortalPane​

Config Bot

The pane that the user is currently viewing in the system portal.

Possible values are:​

ValueDescription
nullThe system portal figures out which pane to show based on the other system portal tags. (Default)
botsThe "bots" pane is shown.
sheetThe "sheet" pane is shown.
searchThe "search" pane is shown.
diffThe "diff" pane is shown.

idePortal​

Config Bot

The prefix that indicates which tags should be loaded into the "IDE" portal in CasualOS. Only available on the config bot.

mapPortal​

Config Bot

The dimension that is loaded into the "map" portal in CasualOS.

The map portal displays a 3D globe representing earth. Bots represented in the map portal use longitude for X and latitude for Y and are 10 meters by 10 meters large by default.

Only available on the config bot.

miniMapPortal​

Config Bot

The dimension that is loaded into the "mini map" portal in CasualOS.

The mini map portal displays a 3D globe representing earth. Bots represented in the mini map portal use longitude for X and latitude for Y and are 10 meters by 10 meters large by default.

Only available on the config bot.

Config Bot

The dimension that is loaded into the "menu" portal in CasualOS. Only available on the config bot.

leftWristPortal​

Config Bot

The dimension that is loaded onto the left controller near the wrist when in VR. Only available on the config bot.

rightWristPortal​

Config Bot

The dimension that is loaded onto the right controller near the wrist when in VR. Only available on the config bot.

meetPortal​

Config Bot

The Jitsi Meet room code of the meeting that should be joined. This will join the current tab to the meeting and provide audiovisual communication between everyone that is joined.

This is similar to a Skype or Zoom call except that all data is encrypted and is deleted once you are done with it. Check out the Jitsi Meet privacy policy here.

Only available on the config bot.

botPortal​

Config Bot

The ID of the bot whose data should be shown in the bot portal. This will show the raw JSON data of the bot in a raw text portal.

Only available on the config bot.

Open the botPortal for the current bot
configBot.tags.botPortal = thisBot.id;
Open the botPortal along the top of the screen
configBot.tags.botPortal = thisBot.id;
botPortalBot.tags.botPortalAnchorPoint = 'top';

tagPortal​

Config Bot

The Bot ID and tag that should be edited in the tag portal. This will show just the code editor without the rest of the sheet and makes it possible to edit just a single tag at a time.

When you are setting the tag portal, you should format it so the bot ID and tag name are separated by a single period (.).

Only available on the config bot.

Examples:​

  1. Open the tag portal for the abc tag on the config bot.
const tag = "abc";
configBot.tags.tagPortal = getID(configBot) + "." + tag;

tagPortalSpace​

Config Bot

The space of the tag mask that should be edited in the tag portal. If not set, then the tag on the bot will be edited. If set, then the tag mask in the given space will be edited.

Only available on the config bot.

Examples:​

  1. Open the tag portal for the abc tag mask in the tempLocal space on the config bot.
const tag = "abc";
configBot.tags.tagPortal = getID(configBot) + "." + tag;
configBot.tags.tagPortalSpace = "tempLocal";

codeToolsPortal​

Config Bot

The dimension of bots that should be shown in the multi-line editor toolbar. This is useful for displaying small buttons that are easy to access while writing code.

Only available on the config bot.

Examples:​

  1. Open the codeToolsPortal to the home dimension.
configBot.tags.codeToolsPortal = 'home';

imuPortal​

Config Bot

Determines if the IMU portal should be constantly reading IMU (inertial measurement unit) data for the device. When set to true, CasualOS will start updating the imuPortalBot with the data from the IMU.

Note that not all devices support the IMU portal. In particular, laptops and desktop computers will likely not support the IMU portal while mobile devices probably will.

Only available on the config bot.

dataPortal​

The data portal is a special portal that can be used in a web request to get bot data directly from the inst. Similar to webhooks, you specify the inst and data portal in the query string of the URL.

If given a bot ID, then the bot will be returned as JSON.

If no bot matches the given value, then it will be treated as a tag and all the values for the given tag will be returned.

If the tag ends with a common extension (like .html or .txt or .json), then the returned data will be tagged with the corresponding MIME type. This will let web browsers and other common software know what type of data they are dealing with and handle it correctly. (i.e. display a webpage) Alternatively, you can specify the dataPortalContentType query parameter to override the default content type.

If there is only one tag and it ends with an extension like specified above then the content directly from the tag will be returned.

Examples:​

  1. Request the JSON of the Bot with the given ID:
https://auxplayer.org?inst=my-aux&dataPortal=bf68e5cc-993b-42fd-a142-a23de6d2cdcb
  1. Request all the #label tags values.
https://auxplayer.org?inst=my-aux&dataPortal=label
  1. Request a web page from the test.html tag.
https://auxplayer.org?inst=my-aux&dataPortal=test.html

mousePointerPosition​

The 3D position of the player's mouse pointer.

See the documentation on Vectors for more info.

mousePointerRotation​

The 3D rotation of the player's mouse pointer.

See the documentation on Rotations for more info.

mousePointerPortal​

The portal that the player's mouse pointer is in.

leftPointerPosition​

The 3D position of the player's left controller.

See the documentation on Vectors for more info.

leftPointerRotation​

The 3D rotation of the player's left controller.

See the documentation on Rotations for more info.

leftPointerPortal​

The portal that the player's left controller is in.

rightPointerPosition​

The 3D position of the player's right controller.

See the documentation on Vectors for more info.

rightPointerRotation​

The 3D rotation of the player's right controller.

See the documentation on Rotations for more info.

rightPointerPortal​

The portal that the player's right controller is in.

mousePointer_left​

The state that the left mouse button is currently in.

Possible values are:​

ValueDescription
nullThe button is not pressed. (default)
downThe button was just pressed.
heldThe button is being held down.

mousePointer_right​

The state that the right mouse button is currently in.

Possible values are:​

ValueDescription
nullThe button is not pressed. (default)
downThe button was just pressed.
heldThe button is being held down.

mousePointer_middle​

The state that the middle mouse button is currently in.

Possible values are:​

ValueDescription
nullThe button is not pressed. (default)
downThe button was just pressed.
heldThe button is being held down.

rightPointer_primary​

The state that the primary button on the right controller is currently in. The primary input on most contollers is the trigger button.

Possible values are:​

ValueDescription
nullThe button is not pressed. (default)
downThe button was just pressed.
heldThe button is being held down.

rightPointer_squeeze​

The state that the squeeze button on the right controller is currently in. Some controllers have buttons on the side that count as "squeezing" the controller.

Possible values are:​

ValueDescription
nullThe button is not pressed. (default)
downThe button was just pressed.
heldThe button is being held down.

leftPointer_primary​

The state that the primary button on the left controller is currently in. The primary input on most contollers is the trigger button.

Possible values are:​

ValueDescription
nullThe button is not pressed. (default)
downThe button was just pressed.
heldThe button is being held down.

leftPointer_squeeze​

The state that the squeeze button on the left controller is currently in. Some controllers have buttons on the side that count as "squeezing" the controller.

Possible values are:​

ValueDescription
nullThe button is not pressed. (default)
downThe button was just pressed.
heldThe button is being held down.

keyboard_[key]​

The state that the given key on the keyboard is currently in.

Possible values are:​

ValueDescription
nullThe key is not pressed. (default)
downThe key was just pressed.
heldThe key is being held down.

touch_[index]​

The state that the given touch index is in.

Possible values are:​

ValueDescription
nullThe touch is not pressed. (default)
downThe touch was just pressed.
heldThe touch is being held down.

forceSignedScripts​

Whether to force all shared scripts to have been signed by a certificate in order to be executed.

This option only takes effect if it is set in the query string of the URL. Additionally, changing the tag value has no effect.

If the inst is loaded with forceSignedScripts set to true, then scripts will be required to be signed for the entire session.

tempLocal and local spaces are exempt from this requirement.

Possible values are:​

ValueDescription
falseScripts do not have to be signed in order to be executed. (default)
trueScripts have to be signed in order to be executed.

url​

The URL that is currently specified in the tab.

Possible values are:​

ValueDescription
Any StringThe URL that is loaded in the tab.

pageTitle​

The title that should be displayed on the web browser tab.

Possible values are:​

ValueDescription
Any StringThe title that should be displayed.

editingBot​

Config Bot

The ID of the bot that the user is currently editing. Only available on the config bot.

editingTag​

Config Bot

The tag that the user is currently editing. Only available on the config bot.

cursorStartIndex​

Config Bot

The selection start index of the player's cursor in the current #editingTag.

Note that when #cursorStartIndex is larger than #cursorEndIndex it means that the player has selected text from the right to the left. This is important because text will always be inserted at #cursorEndIndex.

Only available on the config bot.

cursorEndIndex​

Config Bot

The selection end index of the player's cursor in the current #editingTag.

Note that when #cursorEndIndex is smaller than #cursorStartIndex it means that the player has selected text from the right to the left. This is important because text will always be inserted at #cursorEndIndex.

Only available on the config bot.

Auth Bot Tags​

These are tags that are automatically set on the authBot.

avatarAddress​

The address that the user's avatar mesh can be found at. This can be used with #form and #formAddress to display the avatar in the bot or miniGridPortals.

name​

The name that the user specified for their account.

hasActiveSubscription​

Whether the user has an active subscription to the CasualOS Beta Program. On deployments that do not support subscriptions, this is always true.

subscriptionTier​

The subscription tier that is currently active for the user. It is a string containing the feature level that should be active for the user.

openAiKey​

The OpenAI API Key that the user has configured in their profile.

It has the following format:

vAI1.{base64OfKey}

Hidden Tags​

Hidden tags are tags that are hidden in the sheet by default.