Space Actions

• os.loadInst(id: string): LoadInstAction

  Loads the given inst into the current browser tab. When the inst is loaded, the @onInstJoined shout will be triggered.

  Note that separate instances cannot interact directly. They must instead interact via super shouts

  The first parameter is a string and is the ID of the inst to load.

  Examples

  Load the "fun" inst.

  os.loadInst("fun");

• os.unloadInst(id: string): UnloadInstAction

  Unloads the given inst from the current browser tab. When the inst is unloaded, the @onInstLeave shout will be triggered.

  The first parameter is a string and is the name of the inst to unload.

  Examples

  Unload the "fun" inst.

  os.unloadInst("fun");

• os.enableCollaboration(): Promise<void>

  Attempts to enable collaboration features on the device.

  Examples

  Enable collaboration on this device.

  await os.enableCollaboration();

• os.isCollaborative(): boolean

  Gets whether the current session was loaded with collaborative features enabled.

  When true, CasualOS will attempt to sync the shared (including tempShared and remoteTempShared) spaces with other players. When false, CasualOS will treat all the shared spaces like they are all tempLocal.

  Examples

  Toast whether the current session is collaborative.

  const isCollaborative = os.isCollaborative();
  os.toast(isCollaborative ? "We are collaborative!" : "We are not collaborative!");

• os.applyUpdatesToInst(updates: InstUpdate[]): Promise<void>

  Applies the given updates to the current inst. Returns a promise that resolves once the updates have been applied.

  Note that you can call this function with the same update multiple times and you will end up with only one version of the bots saved in the update. Additionally, future changes to the bots will be preserved even if the update is applied again.

  This feature makes inst updates useful when you want to ensure that an experience starts in an initial state but also able to change over time.

  The first parameter is a InstUpdate[] and is the list of updates that should be applied to this inst.

  Examples

  Apply an update that was saved to a tag

  await os.applyUpdatesToInst([ tags.savedUpdate ]);

• os.createInitializationUpdate(bots: Bot[]): Promise<InstUpdate>

  Creates an inst update that, when applied, ensures the given bots are created on this inst. Returns a promise that resolves with the inst update.

  Note that you can apply the same update multiple times and you will end up with only one version of the bots saved in the update. Additionally, future changes to the bots will be preserved even if the update is applied again.

  This feature makes inst updates useful when you want to ensure that an experience starts in an initial state but also able to change over time.

  Unlike os.getCurrentInstUpdate(), this function creates an update that is not linked to this inst. This means that applying the update to the inst it was created in will create duplicate bots.

  The first parameter is a Bot[] and is the list of bots that should be included in the update.

  Examples

  Create an update with this bot and save it to a tag

  const update = await os.createInitializationUpdate([thisBot]);
  tags.savedUpdate = update;

  Create an update with all the bots in the home dimension

  const update = await os.createInitializationUpdate(getBots(inDimension('home')));
  tags.savedUpdate = update;

• os.getCurrentInstUpdate(): Promise<InstUpdate>

  Retrieves an inst update that represents the current local shared state of the inst. Returns a promise that resolves with the update.

  Note that the inst update only contains bots and tag masks from the shared space. Useful for saving the current shared state of the inst so that it can be restored later or transferred to another inst.

  Unlike os.createInitializationUpdate(bots), this function creates an update that is linked to this inst. This means that applying the update to the inst it was created in will not create duplicate bots. It is still possible to apply the update to other insts, but it may create duplicate bots depending on the history of the other inst.

  Examples

  Save the current inst state to a local bot

  const update = await os.getCurrentInstUpdate();
  create({
      space: 'local',
      backup: true,
      timestamp: update.timestamp,
      update: update
  });

  Restore from a local bot

  const savedUpdates = getBots(bySpace('local'), byTag('backup', true));
  savedUpdates.sort((a, b) => b.timestamp - a.timestamp);
  
  if (savedUpdates.length > 0) {
      const update = savedUpdates[0].tags.update;
      await os.applyUpdatesToInst([update]);
      os.toast("Restored!");
  }

• os.getInstStateFromUpdates(updates: InstUpdate[]): Promise<BotState>

  Calculates the inst state from the given list of updates. Returns a promise that resolves with the bot state that the updates produce.

  Useful for tracking the history of an inst over time.

  The first parameter is a InstUpdate[] and is the updates that the state should be calculated from.

  Examples

  Get the last 5 inst states in the shared space

  const updates = await os.listInstUpdates();
  
  let states = [];
  for(let i = 5; i >= 0; i--) {
      const state = await os.getInstStateFromUpdates(updates.slice(0, updates.length - i));
      states.push(state);
  }
  
  console.log('States: ', states);

  Calculate the last deltas from shared space updates

  const updates = await os.listInstUpdates();
  
  let lastState;
  let deltas = [];
  for(let i = 5; i >= 0; i--) {
      const state = await os.getInstStateFromUpdates(updates.slice(0, updates.length - i));
  
      if (lastState) {
          const delta = diffSnapshots(lastState, state);
          deltas.push(delta);
      }
  
      lastState = state;
  }
  console.log('Deltas: ', deltas);

• os.listInstUpdates(): Promise<InstUpdate[]>

  Gets the list of updates that have occurred in the shared space. Returns a promise that resolves with the list of updates.

  Useful when combined with os.getInstStateFromUpdates(updates) to track the history of an inst over time.

  Examples

  Get a list of updates to shared space

  const updates = await os.listInstUpdates();

• os.mergeInstUpdates(updates: InstUpdate[]): InstUpdate

  Merges the given updates into a single update. Returns the merged update.

  This function is useful for compressing a list of updates into a single update that can be applied to an inst.

  The first parameter is a InstUpdate[] and is the list of updates that should be merged.

  Examples

  Merge a list of updates

  const merged = os.mergeInstUpdates(updates);