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: