Event Actions

• action.perform(action: any): any

  Performs the given action. This function can be used to perform actions that you have stored as data without having to find out which function to call. You can find a list of action types here.

  The first parameter is a any and is the action that should be performed.

  Examples

  Perform a toast action

  action.perform({
      type: 'show_toast',
      message: 'Hello, world!',
      duration: 2000
  });

  Perform an add bot action

  action.perform({
      type: 'add_bot',
      id: 'bot_id',
      bot: {
          id: 'bot_id',
          tags: {
              home: true,
              label: 'Hello, World!'
          }
      }
  });

• action.reject(action: any): RejectAction

  Prevents a previous action from being performed.

  This is especially useful when used in a @onAnyAction listener since it lets you reject actions before they are performed.

  The first parameter is a any and is the action that should be prevented/rejected.

  Examples

  Prevent a toast message from being performed.

  const toastAction = os.toast("my message");
  action.reject(toastAction);

• priorityShout(eventNames: string[], arg?: any): any

  Shouts to all bots that are #listening and have a listen tag for the specified events until one of the bots returns a value. Optionally includes a custom that argument. Also triggers @onListen and @onAnyListen for the bots that the shout was sent to.

  This function is useful when you want to shout but only want one bot to process the shout.

  The first parameter is a string[] and is the array of event names that should be shouted. e.g. Using onClick for the name will trigger the @onClick listener until a bot returns a value.

  The second parameter is optional and is a any and is the that argument to send with the shout. You do not need to specify this parameter if you do not want to.

  Examples

  Shout to the first bot that handles @onClick

  priorityShout(['onClick']);

  Shout to the first bot that handles @myTest or @mySecondTest

  priorityShout(['myTest', 'mySecondTest']);

  Priority shout with a color

  priorityShout(['myTest', 'mySecondTest'], "blue");

• remote(action: BotAction, selector?: (string | SessionSelector | (string | SessionSelector)[]), allowBatching?: boolean): (RemoteAction | RemoteAction[])

  Sends the given action to another remote.

  In CasualOS, all actions are messages which are placed in a queue and processed one at at time.

  For example, the os.toast(message, duration) action queues a message which, when processed, will show a toast message. However, before any action is performed, it is run through the @onAnyAction listener which can decide whether to reject an action using action.reject(action). This lets you write rules for what actions each player is allowed to take.

  There are a couple special cases. First, when you send/receive an action from someone else (i.e. they sent an action to you using the remote(action, selector, allowBatching) function), it won't run by default. Instead it is wrapped as a device action and sent to @onAnyAction for processing. This lets you decide whether to allow players to send messages to each other and what the effect of those messages are. If you want to perform the action, you can use action.perform(action) on the inner device action to queue it for execution.

  The first parameter is a BotAction and is the action to send.

  The second parameter is optional and is a (string | SessionSelector | (string | SessionSelector)[]) and is the object specifing which remote to send the action to. If not specified, then the action is sent to the server. If specified, then the action is sent to all remotes that match the given values. If given a string, then the action is sent to the remote with the matching ID.

  The third parameter is optional and is a boolean and whether to allow batching this remote event with other remote events. This will preserve ordering between remote events but may not preserve ordering with respect to other events. Defaults to true.

  Examples

  Send a toast message to another remote.

  // Get the configBot ID of the other remote.
  const otherRemoteId = 'otherRemoteId';
  
  // Create a toast action
  const toastAction = os.toast('My message!');
  
  // Send the action to the other remote
  // The toastAction will not be performed locally because
  // it is being sent to another remote.
  remote(toastAction, otherRemoteId);

• sendRemoteData(remoteId: (string | string[]), name: string, arg?: any): (RemoteAction | RemoteAction[])

  Sends a @onRemoteData shout to the remote with the given ID or remotes if given a list of IDs. This is useful for sending arbitrary messages to specific remotes.

  In effect, this allows remotes to communicate with each other by sending arbitrary events.

  The first parameter is a (string | string[]) and is the remote ID or list of remote IDs that the shout should be sent to.

  The second parameter is a string and is the name of the event that is being sent. This is useful for telling the difference between different messages.

  The third parameter is optional and is a any and is the that argument to send with the shout. You do not need to specify this parameter if you do not want to.

  Examples

  Send a "custom" message to another remote.

  const otherRemoteId = "otherRemoteId";
  
  // The other remote will receive a

  Send a message to all other remotes.

  const remotes = await os.remotes();
  const remoteId = getID(configBot);
  const otherRemotes = remotes.filter(id => id !== remoteId);
  
  // All other remotes will receive a

• shout(name: string, arg?: any): any

  Sends a shout to all bots that are #listening and have a listen tag for the specified name. Optionally includes a custom that argument. Also triggers @onListen and @onAnyListen.

  The first parameter is a string and is the name of the shout. e.g. Using onClick for the name will trigger all @onClick listeners.

  The second parameter is optional and is a any and is the that argument to send with the shout. You do not need to specify this parameter if you do not want to.

  Examples

  Send a @reset event to all bots

  shout("reset");

  Send a @hello event with your name

  shout("hello", "Bob");

• superShout(eventName: string, arg?: any): SuperShoutAction

  Sends a shout to all of the other instances that are loaded.

  The first parameter is a string and is the name of the shout. e.g. Using onClick for the name will trigger all the @onClick listeners.

  The second parameter is optional and is a any and is the optional that argument to include with the shout.

  Examples

  Send a hello super shout to all the loaded instances.

  superShout("hello");

• whisper(bot: (string | Bot | (string | Bot)[]), eventName: string, arg?: any): any

  Sends a whisper to all bots that are #listening and have a listen tag for the specified name. Optionally includes a custom that argument. Also triggers @onListen and @onAnyListen.

  The first parameter is a (string | Bot | (string | Bot)[]) and is the bot, array of bots, bot #id , or array of bot #id that the whisper should be sent to.

  The second parameter is a string and is the name of the whisper. e.g. Using onClick for the name will trigger the @onClick listener for the specified bots.

  The third parameter is optional and is a any and is the that argument to send with the shout. You do not need to specify this parameter if you do not want to.

  Examples

  Send a @reset event to all bots named "Bob"

  let bots = getBots("#name", "Bob");
  whisper(bots, "reset");

  Send a @setColor event to ourself

  whisper(this, "setColor", "red");