Bot Filters

• atPosition(dimension: string, x: number, y: number): BotFilter

  Creates a bot filter that includes bots that are in the given dimension and at the given X and Y position.

  When this filter is used with getBots(...filters), the returned bots are sorted in the same order that they are stacked. This means that the first bot in the array is at the bottom of the stack and the last bot is at the top of the stack (assuming they're stackable).

  The first parameter is a string and is the name of the dimension.

  The second parameter is a number and is the X position. That is, the left-right position of the bots in the dimension.

  The third parameter is a number and is the Y position. That is, the forward-backward position of the bots in the dimension.

  Examples

  Find all the bots at (1, 2) in the "test" dimension.

  let bots = getBots(atPosition("test", 1, 2));

• byCreator(bot: (string | Bot)): BotFilter

  Creates a bot filter that includes bots created by the given bot. That is, they have #creator set to the #id of the given bot.

  This function behaves exactly like byTag("creator", getID(bot)).

  The first parameter is a (string | Bot) and is the bot that created the other bots.

  Examples

  Find all the bots created by this bot.

  let bots = getBots(byCreator(thisBot));

• byID(id: string): BotFilter

  Creates a bot filter that includes the bot with the given ID.

  The first parameter is a string and is the ID of the bot.

  Examples

  Find the bot with the ID '123'

  let bot = getBot(byID("123"));

• byMod(mod: Mod): BotFilter

  Creates a bot filter that includes bots that match the given mod.

  The first parameter is a Mod and is the bot or mod that the other bots should match.

  Examples

  Find all the bots with #height set to 1 and #color set to red.

  const bots = getBots(byMod({
      height: 1,
      color: "red"
  }));

• bySpace(space: string): BotFilter

  Creates a bot filter that includes bots in the given space. That is, they have #space set to the given value.

  This function behaves exactly like byTag("space", getID(bot)).

  The first parameter is a string and is the space that the bots are in.

  Examples

  Find all bots in the tempLocal space.

  let bots = getBots(bySpace("tempLocal"));

• byTag(tag: string, filter?: TagFilter): BotFilter

  Creates a bot filter that includes bots that have the given tag that matches the given value.

  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 TagFilter and is the value that 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 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(byTag("#name", "bob"));

  Find all bots with a height larger than 2.

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

  Find all bots with the "test" tag.

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

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

  Creates a bot filter that includes bots which match any (i.e. one or more) of the given filters.

  Each parameter is a (bot: Bot) => boolean and are the filters that should be used.

  Examples

  Find all bots with the #name bob or a #height of 2

  const bots = getBots(
      either(
          byTag("#name", "bob"),
          byTag("height", 2)
      )
  );

• inDimension(dimension: string): BotFilter

  Creates a bot filter that includes bots that are in the given dimension. That is, they have the given tag set to true.

  This function behaves exactly like byTag(tag, filter) with the value parameter set to true.

  The first parameter is a string and is the name of the dimension.

  Examples

  Find all the bots in the "test" dimension.

  let bots = getBots(inDimension("test"));

• inStack(bot: Bot, dimension: string): BotFilter

  Creates a bot filter that includes bots in the same stack as the given bot. The given bot will always be included by this filter as long the given bot is in the given dimension.

  When this filter is used with getBots(...filters), the returned bots are sorted in the same order that they are stacked. This means that the first bot in the array is at the bottom of the stack and the last bot is at the top of the stack (assuming they're stackable).

  The first parameter is a Bot and is the bot that other bots should be in the same stack with.

  The second parameter is a string and is the name of the dimension.

  Examples

  Find all bots in the same stack as thisBot in the "test" dimension.

  let bots = getBots(inStack(this, "test"));

• neighboring(bot: Bot, dimension: string, direction?: ("front" | "back" | "left" | "right")): BotFilter

  Creates a bot filter that includes bots which are neighboring the given bot. Optionally takes a direction that the neighboring bots must be in.

  The first parameter is a Bot and is the bot that the other bots need to be neighboring.

  The second parameter is a string and is the dimension that the other bots need to be in.

  The third parameter is optional and is a ("front" | "back" | "left" | "right") and is the neighboring direction to check. If not specified, then all of the supported directions will be checked. Currently, the supported directions are front, right, back, and left. If an unsupported direction is specified, then no bots will be included.

  Examples

  Find all bots in front of this bot in the test dimension.

  const bots = getBots(neighboring(this, "test", "front"));

  Find all bots around this bot in the test dimension.

  const bots = getBots(neighboring(this, "test"));

• not(filter: (bot: Bot) => boolean): BotFilter

  Creates a function that includes bots which do not match the given filter.

  The first parameter is a (bot: Bot) => boolean and is the bot filter whose results should be negated.

  Examples

  Find all bots that are not in the test dimension

  const bots = getBots(not(inDimension("test")));