OS Actions
configBot: Bot
Gets the config bot (formerly known as the player bot). This is the bot that represents the player's browser tab.
It is tempLocal and is used to configure various portals.
Examples
configBot.tags.username = "bob";
configBot.tags.sheetPortal = "testDimension";
os.hideChat(): ShowChatBarAction
Hides the "chat bar" at the top of the screen in CasualOS.
Examples
os.hideChat();
os.showChat(options?: ShowChatOptions): void
Shows the "chat bar" at the top of the screen in CasualOS, optionally using the given text as the placeholder.
Typing in the chat bar will send @onChatTyping shouts and pressing Enter will send a @onChat shout and clear the chat bar.
The first parameter is optional and is a ShowChatOptions and is the options that the chat bar should use.
Examples
os.showChat({
placeholder: "hello"
});
os.showChat({
prefill: "this is prefilled"
});
os.showChat({
prefill: "this is prefilled",
placeholder: "hello"
});
os.showChat({
placeholder: "hello",
placeholderColor: '#44a471'
});
os.showChat({
placeholder: "hello",
backgroundColor: '#f1abe2'
});
os.showChat({
placeholder: "hello",
foregroundColor: '#531234'
});
os.showChat(placeholder?: string): void
Shows the "chat bar" at the top of the screen in CasualOS, optionally using the given text as the placeholder.
Typing in the chat bar will send @onChatTyping shouts and pressing Enter will send a @onChat shout and clear the chat bar.
The first parameter is optional and is a string and is the text that the chat bar should show as the placeholder.
Examples
os.showChat();
os.showChat("hello");
os.convertGeolocationToWhat3Words(location: ConvertGeolocationToWhat3WordsOptions): Promise<string>
Converts the given geolocation to a what3words address. Returns a promise that resolves with the 3 word address.
The first parameter is a ConvertGeolocationToWhat3WordsOptions and is the latitude and longitude that should be converted to a 3 word address.
Examples
const location = await os.getGeolocation();
if (location.success) {
const address = await os.convertGeolocationToWhat3Words(location);
os.toast(address);
} else {
os.tost("Could not get geolocation");
}
const address = await os.convertGeolocationToWhat3Words({
latitude: 42.966824756903755,
longitude: -85.67309821404483,
});
os.toast(address);
os.getGeolocation(): Promise<Geolocation>
Gets the geographic location that the current device is at in the world.
Returns a promise that resolves with the location.
Examples
const location = await os.getGeolocation();
if (location.success) {
os.toast(`You are at (${location.latitude}, ${location.longitude})`);
} else {
os.toast(location.errorMessage);
}
os.hideHtml(): HideHtmlAction
Closes the HTML popup modal.
Examples
os.hideHtml();
os.showHtml(html: string): ShowHtmlAction
Shows some HTML to the player in a popup modal. This can be useful for loading a separate webpage or providing some formatted text.
The first parameter is a string and is the HTML that should be shown to the user.
Examples
os.showHtml(`
<h1>This is some text!</h1>
`);
os.showHtml(`
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/BHACKCNDMW8"
frameborder="0"
allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen>
</iframe>
`);
os.loadInst(id: string): LoadServerAction
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
os.loadInst("fun");
os.unloadInst(id: string): UnloadServerAction
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
os.unloadInst("fun");
os.device(): CasualOSDevice
Gets information about the device that the player is using.
Examples
const info = os.device();
os.toast(info);
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
const isCollaborative = os.isCollaborative();
os.toast(isCollaborative ? "We are collaborative!" : "We are not collaborative!");
os.version(): CasualOSVersion
Gets information about the version of CasualOS.
Examples
const info = os.version();
os.toast(info.version);
const info = os.version();
const isPlayer = info.playerMode === "player";
os.toast('Is Player: ' + isPlayer);
os.instStatuses(): Promise<object[]>
Gets the list of instances that are stored on the server along with the last time that they were updated. Returns a promise that resolves with the list of instances.
The resolved list is sorted by the most recently updated first and the least recently updated last.
Examples
const instances = await os.instStatuses();
os.toast("Instances " + getJSON(instances));
os.instances(): Promise<string[]>
Gets the list of instances that are stored on the server. Returns a promise that resolves with the list of inst names.
Examples
const instances = await os.instances();
os.toast("Instances " + instances.join(','));
os.remoteCount(inst?: string): Promise<number>
Gets the number of remotes that are viewing the current inst. Optionally takes a parameter which is the inst that the number of remotes should be retrieved for. If omitted, then the current inst will be checked. Returns a promise that resolves with the number of active remotes.
The first parameter is optional and is a string and is the name of the inst that the number of remotes should be retrieved for. If not specified, then the current inst current inst will be used.
Examples
const numberOfRemotes = await os.remoteCount();
os.toast("Number of Remotes: " + numberOfRemotes);
const numberOfRemotes = await os.remoteCount('test');
os.toast("Number of Remotes: " + numberOfRemotes);
os.remotes(): Promise<string[]>
Gets the list of remote IDs that are connected to the current inst. Returns a promise that resolves with the list of remote IDs.
The resolved list will always have at least one value that represents the current remote.
Examples
const remotes = await os.remotes();
os.toast("Remotes " + remotes.join(','));
os.totalRemoteCount(): Promise<number>
Gets the number of devices that are connected to the server. Returns a promise that resolves with the number of active devices.
Examples
const numberOfDevices = await os.totalRemoteCount();
os.toast("Number of Devices: " + numberOfDevices);
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
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
const update = await os.createInitializationUpdate([thisBot]);
tags.savedUpdate = update;
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
const update = await os.getCurrentInstUpdate();
create({
space: 'local',
backup: true,
timestamp: update.timestamp,
update: update
});
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
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);
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
const updates = await os.listInstUpdates();
os.disableWakeLock(): Promise<void>
Disables the wake lock that was previously enabled. Returns a promise that resolves once the wake lock has been disabled.
Examples
await os.disableWakeLock();
os.getWakeLockConfiguration(): Promise<WakeLockConfiguration>
Retrieves the current wake lock state. Returns a promise that resolves with an object that contains information about the current wake lock state.
Examples
const configuration = await os.getWakeLockConfiguration();
if (configuration.enabled) {
os.toast('Wake lock is enabled!');
} else {
os.toast('Wake lock is disabled.');
}
os.requestWakeLock(): Promise<void>
Requests a wake lock that will keep the device screen awake. This will ask the user for permission to keep the screen awake. Returns a promise that resolves once the wake lock has been granted. If the wake lock is denied, then an error will be thrown.
Useful for a kiosk mode where the screen is always supposed to be on.
Examples
await os.requestWakeLock();
os.openDevConsole(): OpenConsoleAction
Instructs CasualOS to open the built-in developer console. The dev console provides easy access to error messages and debug logs for formulas and actions.
Examples
os.openDevConsole();
os.meetCommand(command: string, ...args: any): Promise<void>
Send a command to the Jitsi Meet API. The commands are only valid if the meet portal is fully loaded (see @onMeetLoaded).
Returns a promise that resolves when the command has been executed.
The first parameter is a string and is the command to execute.
The second parameter is a any and is the arguments for the command (if any).
Examples
os.meetCommand('displayName', 'ABC123');
os.meetCommand('hangup')
os.meetFunction(functionName: string, ...args: any[]): Promise<any>
Executes the given function on the Jitsi Meet API and returns a promise that resolves with the result. The functions are only valid if the meet portal is fully loaded (see @onMeetLoaded).
The first parameter is a string and is the name of the function to execute.
Each other parameter is a any and are the arguments to provide to the function.
Examples
const participants = await os.meetFunction('getParticipantsInfo')
const rooms = await os.meetFunction('listBreakoutRooms');
os.getAverageFrameRate(): Promise<number>
Gets the number of frames that have occurred over the last second. Returns a promise that resolves with the number of frames that have ocurred in the last second.
Examples
let fps = await os.getAverageFrameRate();
setInterval(async () => {
masks.label = await os.getAverageFrameRate();
}, 1000);
os.getMediaPermission(options: MediaPermissionOptions): Promise<any>
Gets permission from user to access audio and/or video streams from the device.
Returns a promise that resolves if the user grants the specified media permission(s). If the user blocks permission or has previously blocked permission or any other problem occurs, an error will be thrown.
The first parameter is a MediaPermissionOptions and is the options that should be used for requesting media permissions. At least one of
audio
or
video
must be set to
true
.
Examples
try {
await os.getMediaPermission({ audio: true });
} catch (e) {
console.error('Could not get permission for microphone:', e);
}
try {
await os.getMediaPermission({ audio: true, video: true });
} catch (e) {
console.error('Could not get permission for microphone and/or camera:', e);
}
os.log(...args: any[]): void
Logs the given data to the developer console.
Each parameter is a any and are the data that should be logged.
Examples
os.log("Hello, World!");
os.run(script: string): Promise<any>
Runs the given script.
The script will be executed in a separate environment with no bot, tags, this, thisBot, data, and that variables.
This means that you need to use the getBot(...filters) or getBots(...filters) functions to read bot data.
Returns a promise that resolves with the returned script value after it has been executed.
The first parameter is a string and is the script that should be executed.
Examples
os.run("os.toast('hello');");
os.run(tags.script);
const result = await os.run("return 594 + 391");
os.toast(result);
os.setClipboard(text: string): SetClipboardAction
Copies the given text to the player's clipboard. On Chrome and Firefox, this will act like a Ctrl+C/Cmd+C.
On Safari and all iOS browsers this will open a popup which prompts the player to copy the text.
The first parameter is a string and is the text that should be copied to the player's clipboard.
Examples
os.setClipboard("hello");
os.share(options: ShareOptions): Promise<void>
Shares the given URL or text via the device's social share capabilities. Returns a Promise that resolves when sharing has succeeded or failed.
The first parameter is a ShareOptions and is the options for sharing.
Examples
os.share({
url: 'https://example.com'
});
os.share({
text: 'abcdefghijklmnopqrstuvwxyz'
});
os.sleep(time: number): Promise<void>
Waits the amount of time provided, in miliseconds.
Returns a promise that resolves when the time has been waited.
The first parameter is a number and is the Time to wait in ms. 1 second is 1000 ms.
Examples
os.toast("Stop!");
await os.sleep(2000);
os.toast("Hammer Time!");
os.toast(message: (string | number | boolean | object | any[]), duration: number): ShowToastAction
Shows a temporary "toast" notification to the player at the bottom of the screen with the given message. Optionally accepts a duration parameter which is the number of seconds that the message should be on the screen.
The first parameter is a (string | number | boolean | object | any[]) and is the text that the toast message should show.
The second parameter is a number and is the number of seconds that the message should be on the screen. (Default is 2)
Examples
os.toast("Hello!");
os.toast("this is the code", 5);
