Skip to main content
Version: v3.1.36

Listen Tag Variables

CasualOS defines some variables for each listen tag that you create. Unlike actions, variables exist to make it easy to access common data.

thisBot​

The bot that the listen tag is defined in. This makes it easy to edit and read tag data in the bot that the listen tag was created in.

Also known as: bot, this.

Examples:​

  1. Set the current bot's color to "green".
thisBot.tags.color = "green";
  1. Whisper to the "myShout" tag on this bot.
whisper(thisBot, "myShout");

that​

The data which was included in a shout or whisper. It is also known as an "argument". It can be any kind of JavaScript data. This includes strings, numbers, booleans, objects (Bots, arrays, etc.) and more.

Most listen tags specify what kind of data that is. Usually it is an object that contains properties which describe the action in further detail.

Examples:​

  1. The @onAnyBotClicked listen tag specifies the bot which was clicked. You could set the clicked bot's color to "green" using a tag mask.
that.bot.masks.color = "green";
  1. The @onBarcodeScanned listen tag only specifies the barcode string which was scanned. You could toast it like this:
os.toast(that);
  1. You can include your own that variable when you shout or whisper to other bots.

First you have to have a script which sends the shout and argument.

// In a normal listener like @onClick
const myThatObject = {
    message: "This is a custom message which I am including in the shout"
};
shout("myShout", myThatObject);

Second you have to have a listener for your shout.

// Put this in @myShout
os.toast(that.message);

tagName​

The name of the tag that this listener is defined in. This can be useful when you want to copy a listener between different tags but still want to be able to tell which is which.

Examples:​

  1. Toast the current tag name.
os.toast('Current tag ' + tagName);

tags​

The tags object of thisBot. Essentially a shortcut for thisBot.tags.

Examples:​

  1. Set the current bot's color to "green".
tags.color = "green";
  1. Delete the myNumber tag.
delete tags.myNumber;
  1. Get a tag by a variable name.
tags.myTag = '123';
let tagToGet = 'myTag';
let myTagValue = tags[tagToGet];

// toasts "Type is number"
os.toast("Type is " + typeof myTagValue);

raw​

The "raw tags" object of thisBot. Essentially a shortcut for thisBot.raw.

Whereas the tags variable will convert strings to numerical or boolean values, the raw variable provides the exact value that was stored. This can be useful for copying because you can ensure that everything will be what it was originally.

  1. Set the current bot's color to "green".
raw.color = "green";
  1. Delete the myNumber tag.
delete raw.myNumber;
  1. Get a tag by a variable name.
tags.myTag = '123';
let tagToGet = 'myTag';
let myTagValue = raw[tagToGet];

// toasts "Type is string"
os.toast("Type is " + typeof myTagValue);

creatorBot​

The bot that is set as the #creator of thisBot. Essentially a shortcut for getBot('creator', tags.creator).

If there is no creator then creatorBot will be null.

Examples:​

  1. Check if thisBot has a creator.
const hasCreator = !!creatorBot;
  1. Whisper to the creator bot.
whisper(creatorBot, 'myWhisper');

configBot​

The bot that configures the current browsing session. This used to be called the "player bot" but was renamed to configBot to better indicate what it is used for.

You can find the list of tags that CasualOS uses for the configBot here.

Examples:​

  1. Set the sheetPortal to "home".
configBot.tags.sheetPortal = "home";
  1. Set the gridPortal to "myDimension".
configBot.tags.gridPortal = "myDimension";

gridPortalBot​

The bot that is used to configure the grid portal. By default this is a tempLocal bot that is generated automatically.

Supports the following tags:

Examples:​

  1. Set the grid portal color to "blue".
gridPortalBot.tags.portalColor = "blue";

sheetPortalBot​

The bot that should be used to configure the #sheetPortal.

systemPortalBot​

The bot that should be used to configure the #systemPortal.

miniGridPortalBot​

The bot that should be used to configure the miniGridPortal.

Supports the following tags:

mapPortalBot​

The bot that should be used to configure the map portal.

Supports the following tags:

miniMapPortalBot​

The bot that should be used to configure the mini map portal.

Supports the following tags:

The bot that should be used to configure the #menuPortal.

Supports the following tags:

leftWristPortalBot​

The bot that should be used to configure the #leftWristPortal.

Supports the following tags:

rightWristPortalBot​

The bot that should be used to configure the #rightWristPortal.

Supports the following tags:

meetPortalBot​

The bot that should be used to configure the #meetPortal.

Supports the following tags: