Data Actions

• applyDiffToSnapshot(snapshot: BotState, diff: PartialBotState): BotState

  Applies the given difference to the given snapshot and returns a new snapshot that represents the result.

  The first parameter is a BotState and is the snapshot that the delta should be applied to. This is also called the baseline snapshot.

  The second parameter is a PartialBotState and is the delta that should be applied to the snapshot. You can create a delta from two snapshots by using the diffSnapshots(first, second) function.

• changeState(bot: Bot, stateName: string, groupName?: string): void

  Changes the state that the given bot occupies in the given group. If the state was changed, then the @[groupName][stateName]OnExit and @[groupName][stateName]OnEnter whispers are sent to the bot.

  The first parameter is a Bot and is the bot whose state should be changed.

  The second parameter is a string and is the value that should be set on the bot.

  The third parameter is optional and is a string and is the name of the tag that should be changed on the bot. If not specified, then the #state tag will be used.

  Examples

  Change the #state of the bot to "Running"

  // Triggers

  Change the #playbackState of the bot to "Playing"

  // Triggers

• create(...mods: Mod[]): (Bot | Bot[])

  Creates a new bot or combination of bots with the given mods. Also triggers @onCreate on all the created bots. By default, bots are created with a unique #id, #creator set to the current bot.id, and #space set to shared. Bots must be created with at least one tag. If create() tries to make a bot with zero tags then an error will be thrown.

  If #creator references a non-existent bot or a bot with a different #space than the created bot, then #creator will be set to null.

  Each parameter is a Mod and are the mods that should be applied to the new bot(s). If no parameters are specified, then the new bot will have its #creator set to bot.id and #space set to shared . If an array of mods is used for a parameter, then one bot will be created for each unique combination of mods .

  Examples

  Create a red bot

  let redBot = create({
      color: "red"
  });

  Create a parent and a child bot

  let myParentBot = create({
    creator: null,
     label: "Parent"
  });
  let myChildBot = create({
     creator: getID(myParentBot),
     label: "Child"
  });

  Create a red bot in the tempLocal space

  let myBot = create({ space: "tempLocal", color: "red" });

  Create a bot from multiple mods

  // myBot is placed in the "myDimension" dimension and is colored green
  let myBot = create({ myDimension: true }, {
      color: "green"
  });

  Create a red bot and a blue bot

  let [myRedBot, myBlueBot] = create({ creator: null}, [
      {
         color: "red"
      },
      {
        color: "blue"
      }
  });

• destroy(bot: (string | string[] | Bot | Bot[])): void

  Removes the given bot, list of bots, or bot by #id and triggers

  The first parameter is a (string | string[] | Bot | Bot[]) and is the bot, bot ID, or list of bots to destroy.

  Examples

  Destroy a the bot with the name "bob"

  destroy(getBot("#name", "bob"));

  Destroy all bots that are colored red

  destroy(getBots("#color", "red"));

  Destroy a bot by its ID

  // Destroy the bot with the #id: "config"
  destroy("config");

• diffSnapshots(first: BotState, second: BotState): PartialBotState

  Calculates the difference between the two given snapshots. The returned value is such that if you were to apply the changes (using applyDiffToSnapshot(snapshot, diff)) it represents to the first snapshot you would end up with the second snapshot.

  The first parameter is a BotState and is the snapshot that should be used as the baseline for the diff.

  The second parameter is a BotState and is the snapshot that should be used as the target for the diff.

  Examples

  Calculate the diff between two snapshots

  const first = getSnapshot([thisBot]);
  thisBot.tags.color = 'red';
  const second = getSnapshot([thisBot]);
  const diff = diffSnapshots(first, second);
  
  console.log(diff);

• getBotLinks(bot: Bot): ParsedBotLink[]

  Gets the list of bot links that are stored in tags on the specified bot.

  This function can be useful if you want to discover what tags are linking to bots and get those bot IDs.

  The first parameter is a Bot and is the bot to get the links for.

  Examples

  Get the list of bot links on this bot

  let botLinks = getBotLinks(thisBot);

• getBotPosition(bot: (string | Bot), dimension: string): Vector3

  Gets the 3D position of the given bot in the given dimension.

  The first parameter is a (string | Bot) and is the bot or bot ID whose position should be retrieved.

  The second parameter is a string and is the dimension that the position should be retrieved for.

  Examples

  Get the position of this bot in the #home dimension

  let position = getBotPosition(thisBot, "home");

• getBotRotation(bot: (string | Bot), dimension: string): Rotation

  Gets the 3D rotation of the given bot in the given dimension.

  The first parameter is a (string | Bot) and is the bot or bot ID whose rotation should be retrieved.

  The second parameter is a string and is the dimension that the rotation should be retrieved for.

  Examples

  Get the rotation of this bot in the #home dimension

  let rotation = getBotRotation(thisBot, "home");

• getBotTagValues(tag: string, filter?: TagFilter): any[]

  Gets a list of all the values in the inst for the given tag. Optionally accepts a filter for the tag values.

  The first parameter is a string and is the name of the tag to search for.

  The second parameter is optional and is a TagFilter and is the filter that the tag values should match. If not specified, then all the tag values are included. If it is a function, then it will be used to match values. Otherwise, only tags that match the value will be included.

  Examples

  Find the number of bots named bob and print it

  const numberOfBobs = getBotTagValues("#name", "bob").length;
  os.toast(numberOfBobs);

  Find all the bot ages above 10

  const agesOver10 = getBotTagValues("#age", age => age > 10);

• getFormattedJSON(data: any): string

  Gets the JSON representation of the given data formatted in a human-readable manner.

  The first parameter is a any and is the data that should be cloned into the JSON format. If given a bot, then the returned JSON will be able to be able to be converted back into a mod via getMod(bot, ...tags) .

  Examples

  Sort a nicely formatted copy of a bot in a tag

  let bob = getBot("#name", "bob");
  tags.savedBot = getFormattedJSON(bob);

• getID(bot: (string | Bot)): string

  Gets the #id of the given bot.

  The first parameter is a (string | Bot) and is the bot whose ID should be retrieved. If given a bot ID, then it will be returned. If given null or something that is not a bot, then null will be returned.

  Examples

  Get the ID of the current bot

  let id = getID(thisBot);

  Get the ID of a bot with #name set to "bob"

  let id = getID(getBot("#name", "bob"));

• getJSON(data: any): string

  Gets the JSON representation of the given data.

  The first parameter is a any and is the data that should be cloned into the JSON format. If given a bot, then the returned JSON will be able to be able to be converted back into a mod via getMod(bot, ...tags) .

  Examples

  Store a copy of a bot in a tag

  let bob = getBot("#name", "bob");
  tags.savedBot = getJSON(bob);

• getLink(...bots: (string | Bot | (string | Bot)[])[]): string

  Creates and returns a bot link that references the given bots. The link can then be stored in a tag to save it. Useful for creating bot links for an arbitrary number of bots.

  Each parameter is a (string | Bot | (string | Bot)[]) and are the bots that the link should point to.

  Examples

  Create a link to this bot

  let link = getLink(thisBot);

• getSnapshot(bots: (Bot | Bot[])): BotState

  Gets a snapshot of the given bots. Snapshots are like mods (see getMod(bot, ...tags)) except they contain multiple bots and include the ID, space, tags, and tag masks of the bots.

  The first parameter is a (Bot | Bot[]) and is the bot or list of bots that a snapshot should be created out of.

• getBot(...filters: ((bot: Bot) => boolean)[]): Bot

  Get the first bot that matches all of the given filter(s). If multiple bots match the given filter(s), then bots are sorted alphabetically by the #id tag and the first one is returned. If no bots match the given filter(s), then undefined is returned.

  Each parameter is a (bot: Bot) => boolean and are if no filters are specified, then all bots in the inst are returned. If multiple filters are specified, then only the bots that match all of the filters are returned.

  Examples

  Find a bot with the #test tag

  let foundBot = getBot(byTag("#test"));

  Find a bot with #name set to "bob" and in the #people dimension

  let foundBot = getBot(byTag("#name", "bob"), inDimension("people"));

• getBot(tag: string, value?: any): Bot

  Gets the first bot that matches the given tag and value. If multiple bots match the given tag and value, then bots are sorted alphabetically by the #id tag and the first one is returned. If no bots match the given tag and value, then undefined is returned.

  The first parameter is a string and is the name of the tag to search for.

  The second parameter is optional and is a any and is the value the tag should match. If not specified, then the first bot with the tag will be returned. If specified, then the first bot that has the same tag and value will be returned. If you specify a function as the value, then it will be used to match tag values.

  Examples

  Find the first bot with #name set to "bob"

  let foundBot = getBot("#name", "bob");

  Find the first bot with a #height larger than 2

  let foundBot = getBot("#height", height => height > 2);

  Find the first bot with the #test tag

  let foundBot = getBot("#test");

• getBots(...filters: ((bot: Bot) => boolean)[]): Bot[]

  Gets an array of bots that match all of the given filter(s). The returned array is sorted alphabetically by the #id tag.

  Each parameter is a (bot: Bot) => boolean and are if no filters are specified, then all bots in the inst are returned. If multiple filters are specified, then only the bots that match all of the filters are returned.

  Examples

  Gets all the bots in the inst.

  let bots = getBots();

  Find all bots with the "test" tag

  let bots = getBots(byTag("#test"));

  Find all bots with #name set to "bob" and in the #people dimension

  let bots = getBots(byTag("#name", "bob"), inDimension("people"));

• getBots(tag: string, value?: any): Bot[]

  Gets an array of bots that match the given tag and value. The returned array is sorted alphabetically by the #id tag.

  The first parameter is a string and is the name of the tag. Bots that have this tag will be included as long as they also match the second parameter.

  The second parameter is optional and is a any and is the value the tag should match. If not specified, then all bots with the tag will be included. If specified, then only bots that have the same tag and value will be included. If you specify a function as the value, then it will be used to match tag values.

  Examples

  Find all the bots with #name set to "bob"

  let bots = getBots("#name", "bob");

  Find all bots with a #height larger than 2

  let bots = getBots("#height", height => height > 2);

  Find all bots with the #test tag

  let bots = getBots("#test");

• removeTags(bot: (Bot | Bot[]), tagSection: (string | RegExp)): void

  Removes all the tags from the given bot that match the given tag section.

  The first parameter is a (Bot | Bot[]) and is the bot or list of bots that should have the tags removed.

  The second parameter is a (string | RegExp) and is the string or regex that specifies which tags to remove. If given a string, then all the tags that start with the given string will be removed. If given a regex, then all the tags which match the regex will be removed.

  Examples

  Remove tags named starting with "abc" from this bot.

  removeTags(thisBot, "abc");

  Remove tags named "hello" using a case-insensitive regex from this bot.

  removeTags(thisBot, /^hello$/gi);

• renameTag(bot: (Bot | Bot[]), originalTag: string, newTag: string): void

  Renames the given original tag on the given bot or list of bots to the given new tag. If the original tag does not exist on the bot, then no changes will take place. If the new tag already exists on the bot, then it will be overwritten with the contents of the original tag.

  The first parameter is a (Bot | Bot[]) and is the bot or list of bots that should have the tag renamed.

  The second parameter is a string and is the name of the tag that should be renamed.

  The third parameter is a string and is the new name that the tag should have.

  Examples

  Rename the "auxColor" tag to "color"

  renameTag(thisBot, "auxColor", "color");

• updateBotLinks(bot: Bot, idMap: object): void

  Updates the links in the given bot to point to the new Bot IDs specified in the given ID map.

  This function is useful if you know that the links in the given bot are outdated and you know which IDs map to the new IDs.

  The first parameter is a Bot and is the bot whose links should be updated.

  The second parameter is a object and is the map of old bot IDs to the new IDs that should replace them. Each property should be an old ID and each value should be a new ID.

  Examples

  Change all references to "botA" to "botB" on this bot

  updateBotLinks(thisBot, {
     "botA": "botB"
  });

• uuid(): string

  Creates a Universally Unique IDentifier (UUID). Useful for generating a random identifier that is guaranteed to be unique

  Examples

  Generate a new UUID and toast it

  const id = uuid();
  os.toast(id);

• clearTagMasks(bot: (Bot | Bot[]), space?: string): void

  Clears the tag masks on the given bot or list of bots. If a space is specified, then only the tag masks in that space will be deleted.

  The first parameter is a (Bot | Bot[]) and is the bot or list of bots that the tag mask should be set on.

  The second parameter is optional and is a string and is the space that the tag mask should exist in. If omitted, then the tag masks in all spaces will be deleted.

• deleteTagMaskText(bot: Bot, tag: string, index: number, count: number, space?: string): string

  Deletes the specified number of characters from the given tag mask at the given index. Useful for editing the text in a tag without interrupting other players that are editing the same tag. If a space is specified, then only the tag mask in that space will be changed.

  Returns the resulting raw tag value.

  The first parameter is a Bot and is the bot that should be edited.

  The second parameter is a string and is the tag that should be edited.

  The third parameter is a number and is the zero-based index that the text should start to be deleted at.

  The fourth parameter is a number and is the number of characters that should be deleted.

  The fifth parameter is optional and is a string and is the space that the tag mask is in. If omitted, then the tempLocal space will be used.

  Examples

  Delete the last two characters from a tag mask.

  deleteTagMaskText(bot, "myTag", tags.myTag.length - 2, 2);

  Delete the first 3 characters from a tag mask in the local space.

  deleteTagMaskText(bot, "myTag", 0, 3, "local");

• deleteTagText(bot: Bot, tag: string, index: number, count: number): string

  Deletes the specified number of characters from the given tag at the given index. Useful for editing the text in a tag without interrupting other players that are editing the same tag. Returns the resulting raw tag value.

  The first parameter is a Bot and is the bot that should be edited.

  The second parameter is a string and is the tag that should be edited.

  The third parameter is a number and is the zero-based index that the text should start to be deleted at.

  The fourth parameter is a number and is the number of characters that should be deleted.

  Examples

  Delete the last two characters from a tag.

  deleteTagText(bot, "myTag", tags.myTag.length - 2, 2);

  Delete the first 3 characters from a tag.

  deleteTagText(bot, "myTag", 0, 3);

• getTag(bot: Bot, ...tags: string[]): any

  Gets the given tag value from the given bot.

  The first parameter is a Bot and is the bot that the tag should be retrieved from.

  Each other parameter is a string and are

  Examples

  Get the "color" tag from this bot.

  let color = getTag(thisBot, "color");

• insertTagMaskText(bot: Bot, tag: string, index: number, text: string, space?: Space): string

  Inserts the given text into the tag mask at the given index. Useful for editing the text in a tag without interrupting other players that are editing the same tag. If a space is specified, then only the tag mask in that space will be changed.

  The first parameter is a Bot and is the bot that should be edited.

  The second parameter is a string and is the tag that should be edited.

  The third parameter is a number and is the zero-based index that the text should be inserted at.

  The fourth parameter is a string and is the string of text that should be inserted.

  The fifth parameter is optional and is a Space and is the space that the tag mask is in. If omitted, then the tempLocal space will be used.

  Examples

  Add some text to the end of a tag mask.

  insertTagMaskText(thisBot, "myTag", tags.myTag.length, "xyz");

  Add some text to the beginning of a tag mask that is in the local space.

  insertTagMaskText(thisBot, "myTag", 0, "abc", "local");

• insertTagText(bot: Bot, tag: string, index: number, text: string): string

  Inserts the given text into the tag at the given index. Useful for editing the text in a tag without interrupting other players that are editing the same tag. Returns the resulting raw tag value.

  The first parameter is a Bot and is the bot that should be edited.

  The second parameter is a string and is the tag that should be edited.

  The third parameter is a number and is the zero-based index that the text should be inserted at.

  The fourth parameter is a string and is the string of text that should be inserted.

  Examples

  Add some text to the end of a tag.

  insertTagText(thisBot, "myTag", tags.myTag.length, "xyz");

  Add some text to the beginning of a tag.

  insertTagText(thisBot, "myTag", 0, "abc");

• setTag(bot: (Bot | Bot[] | Tags), tag: string, value: any): any

  Sets the given tag to the given value on the given bot, list of bots, or mod.

  The first parameter is a (Bot | Bot[] | Tags) and is the bot, list of bots, or mod that the tag should be set on.

  The second parameter is a string and is the tag that should be changed.

  The third parameter is a any and is the value that should be placed into the tag(s).

  Examples

  Set a bot's color to "green".

  setTag(this, "color", "green");

• setTagMask(bot: (Bot | Bot[]), tag: string, value: any, space?: string): any

  Sets the given tag mask to the given value on the given bot or list of bots. If a space is specified, then the tag mask will be set inside that space.

  The first parameter is a (Bot | Bot[]) and is the bot or list of bots that the tag mask should be set on.

  The second parameter is a string and is the tag that should be changed.

  The third parameter is a any and is the value that should be placed into the tag(s).

  The fourth parameter is optional and is a string and is the space that the tag mask should exist in. If omitted, then the tag mask will be created in the tempLocal space.

  Examples

  Set a bot's color to "green".

  setTagMask(this, "color", "green")

  Set a bot's #color to green in the local space.

  setTagMask(this, "#color", "green", "local");