Skip to main content
Version: Current

Portal Actions

os.closeCircleWipe(options?: Partial<OpenCircleWipeOptions>): Promise<void>​

Causes a circular wipe animation to close around the screen. This can be used to cover the grid portal while transitioning between scenes. Returns a promise that resolves when the animation has finished running. The promise will throw an exception if os.openCircleWipe(options) is called while the animation is running.

The first parameter is optional and is a Partial<OpenCircleWipeOptions> and is the options that should be used for the effect.

Examples

Hide the grid portal with a circular wipe animation.
await os.closeCircleWipe();
os.toast("Hidden!");
Hide the grid portal and show it after an additional second.
await os.closeCircleWipe();
await os.sleep(1000);
await os.openCircleWipe();
Use a custom color for the circle wipe.
await os.closeCircleWipe({
    color: '#63f1aa'
});
Make the circle wipe take 5 seconds to complete.
await os.closeCircleWipe({
    duration: 5
});

os.openCircleWipe(options?: Partial<OpenCircleWipeOptions>): Promise<void>​

Causes the circular wipe animation to open around the screen. This can be used to reveal the grid portal after transitioning between screens. Returns a promise that resolves when the animation has finished running. The promise will throw an exception if os.closeCircleWipe(options) is called while the animation is running.

The first parameter is optional and is a Partial<OpenCircleWipeOptions> and is the options that should be used for the effect.

Examples

Reveal the grid portal with a circular wipe animation.
await os.openCircleWipe();
os.toast("Revealed!");
Hide the grid portal and show it after an additional second.
await os.closeCircleWipe();
await os.sleep(1000);
await os.openCircleWipe();
Use a custom color for the circle wipe.
await os.openCircleWipe({
    color: '#63f1aa'
});
Make the circle wipe take 5 seconds to complete.
await os.openCircleWipe({
    duration: 5
});

os.getCurrentDimension(): string​

Gets the dimension that is loaded into the #gridPortal portal.

This function behaves exactly like os.getPortalDimension(portal) when given "gridPortal".

Examples

Show a message of the dimension that is currently in the #gridPortal portal.
const dimension = os.getCurrentDimension();
os.toast(dimension);

os.getCurrentInst(): string​

Gets the inst that is loaded.

Examples

Show a message of the current inst.
const inst = os.getCurrentInst();
os.toast(inst);

os.getDimensionalDepth(dimension: string): number​

Gets the distance that the player bot is from the given dimension.

Returns 0 if the player bot is in the dimension, 1 if the dimension is in a portal, and -1 if neither are true.

The first parameter is a string and is the dimension to check for.

Examples

Get the distance to the "fun" dimension.
const distance = os.getDimensionalDepth("fun");
if (distance === 0) {
    os.toast("Player is in the fun dimension");
} else if(distance === 1) {
    os.toast("Player is viewing the fun dimension");
} else {
    os.toast("Player cannot access the fun dimension");
}

os.getMenuDimension(): string​

Gets the dimension that is loaded into the #menuPortal portal.

This function behaves exactly like os.getPortalDimension(portal) when given "menuPortal".

Examples

Show a message of the dimension that is currently in the #menuPortal portal.
const dimension = os.getMenuDimension();
os.toast(dimension);

os.getMiniPortalDimension(): string​

Gets the dimension that is loaded into the #miniGridPortal portal.

This function behaves exactly like os.getPortalDimension(portal) when given "miniGridPortal".

Examples

Show a message of the dimension that is currently in the #miniGridPortal portal.
const dimension = os.getMiniPortalDimension();
os.toast(dimension);

os.getPortalDimension(portal: string): string​

Gets the dimension that is loaded into the given portal. If no dimension is loaded, then null is returned.

The first parameter is a string and is the portal that the dimension should be retrieved for

Examples

Get the dimension that is currently showing in the #gridPortal.
const dimension = os.getPortalDimension('grid');
Get the dimension that is currently showing in the #miniGridPortal.
const dimension = os.getPortalDimension('miniGrid');

os.hasBotInMiniPortal(bots: (Bot | Bot[])): boolean​

Determines if the given bot is in the dimension that is currently loaded into the #miniGridPortal portal.

The first parameter is a (Bot | Bot[]) and is the bot or bots that should be checked.

Examples

Show a message if a bot named "bob" is in the miniGridPortal.
const bob = getBot("#name", "bob");
if (os.hasBotInMiniPortal(bob)) {
    os.toast("bob is in the miniGridPortal!");
}

os.inSheet(): boolean​

Gets whether the player is viewing the sheetPortal

Examples

Show a toast if the player is viewing the sheet.
if (os.inSheet()) {
    os.toast("You are in the sheet!");
}

os.isInDimension(dimension: string): boolean​

Gets whether the given dimension is loaded into the #gridPortal portal.

The first parameter is a string and is the dimension to check for.

Examples

Show a toast if the player is viewing the abc dimension.
if (os.isInDimension("abc")) {
    os.toast("In the dimension!");
}

os.exitFullscreenMode(): ExitFullscreenAction​

Exits fullscreen mode.

Examples

Exit fullscreen mode.
os.exitFullscreenMode();

os.requestFullscreenMode(): RequestFullscreenAction​

Attempts to enter fullscreen mode. Depending on which web browser the player is using, this might ask for permission to go fullscreen.

Note that iPhones currently don't support fullscreen mode.

Examples

Enter fullscreen mode.
os.requestFullscreenMode();

os.goToDimension(dimension: string): GoToDimensionAction​

Loads the given dimension into the #gridPortal portal. Triggers the @onPortalChanged shout for the gridPortal.

The first parameter is a string and is the dimension that should be loaded.

Examples

Load the abc dimension.
os.goToDimension("abc");

os.goToURL(url: string): GoToURLAction​

Redirects the current tab to the given URL. Useful for sending the player to another webpage or ambient experience.

The first parameter is a string and is the URL that the player should be sent to. Usually this is a website like https://example.com .

Examples

Send the player to https://example.com.
os.goToURL("https://example.com");

os.openURL(url: string): OpenURLAction​

Opens a new tab with the given URL. Useful for opening another webpage without redirecting the current tab.

The first parameter is a string and is the URL that the player should be sent to. Usually this is a website like https://example.com .

Examples

Open https://example.com in a new tab.
os.openURL("https://example.com");

os.getInputList(): string[]​

Gets the list of supported inputs. The returned strings can be used for the controller property in os.getInputState(controller, button) calls.

Examples

Get a list of inputs and toast them.
const state = os.getInputList();
os.toast(state);

os.getInputState(controller: string, button: string): (null | "down" | "held")​

Gets the state of the given button on the given controller.

The first parameter is a string and is the name of the controller that should be checked. Possible values are:

  • mousePointer - The mouse.
  • leftPointer - The left controller.
  • rightPointer - The right controller.
  • keyboard - The keyboard.
  • touch - The touchscreen.

The second parameter is a string and is the name of the button that you want to get the state of. Possible values are:

  • left - The left mouse button. Only available on the mouse pointer. On mobile devices this will also be the state of the first touch.
  • right - The right mouse button. Only available on the mouse pointer.
  • middle - The middle mouse button. Only available on the mouse pointer.
  • primary - The primary controller button. Only available on the left and right pointers.
  • squeeze - The squeeze controller button. Only available on the left and right pointers.
  • Any Key - The button for the given key. Only available on the keyboard.
  • 0 - The first touch. Only available on the touchscreen.
  • 1 - The second touch. Only available on the touchscreen.
  • 2 - The third touch. Only available on the touchscreen.
  • 3 - The fourth touch. Only available on the touchscreen.
  • 5 - The fifth touch. Only available on the touchscreen.

Examples

Send a toast if the left mouse button is clicked.
const state = os.getInputState("mousePointer", "left");
if (state) {
    os.toast("Left mouse button is down!");
}
Send a toast if the shift key is down.
const state = os.getInputState("keyboard", "Shift");
if (state) {
    os.toast("Shift is down!");
}

os.getCameraPosition(portal: ("grid" | "miniGrid")): Vector3​

Gets the 3D position that the player's camera is at in the given portal.

The first parameter is a ("grid" | "miniGrid") and is the portal that the camera position should be retrieved for.

Examples

Get the position of the camera in the grid portal.
const position = os.getCameraPosition('grid');
Get the position of the camera in the miniGridPortal.
const position = os.getCameraPosition("mini");

os.getCameraRotation(portal: ("grid" | "miniGrid")): object​

Gets the 3D rotation that the player's camera is at in the given portal.

The first parameter is a ("grid" | "miniGrid") and is the portal that the camera rotation should be retrieved for.

Examples

Get the rotation of the player in the grid portal.
const rotation = os.getCameraRotation('grid');
Get the rotation of the player in the miniGridPortal.
const rotation = os.getCameraRotation("mini");

os.getFocusPoint(portal: ("grid" | "miniGrid")): Vector3​

Gets the 3D position that the player's camera is focusing on in the given portal.

This is the same point that is highlighted when #portalShowFocusPoint is enabled for a portal.

The first parameter is a ("grid" | "miniGrid") and is the portal that the camera focus point should be retrieved for.

Examples

Get the focus point of the player in the grid portal.
const focusPoint = os.getFocusPoint('grid');
Get the focus point of the player in the miniGridPortal.
const focusPoint = os.getFocusPoint("mini");

os.getPointerDirection(pointer: ("left" | "right" | "mouse")): Vector3​

Gets the direction that the given pointer is pointed in.

Can be combined with math.intersectPlane(origin, direction, planeNormal, planeOrigin) to find where on the ground the pointer is pointing.

The first parameter is a ("left" | "right" | "mouse") and is the pointer that the direction should be retrieved for.

Examples

Get the direction of the mouse pointer.
const direction = os.getPointerDirection("mouse");
Get the direction of the left pointer.
const direction = os.getPointerDirection("left");
Find where the mouse is pointing on the ground.
const position = os.getPointerPosition();
const direction = os.getPointerDirection();
const groundPosition = math.intersectPlane(position, direction);

os.getPointerPosition(pointer: ("left" | "right" | "mouse")): Vector3​

Gets the position that the given pointer is at.

The first parameter is a ("left" | "right" | "mouse") and is the pointer that the position should be retrieved for.

Examples

Get the position of the mouse pointer.
const position = os.getPointerPosition("mouse");
Get the position of the left pointer.
const position = os.getPointerPosition("left");

os.getPointerRotation(pointer: ("left" | "right" | "mouse")): object​

Gets the rotation (in euler angles) that the given pointer is at.

The first parameter is a ("left" | "right" | "mouse") and is the pointer that the rotation should be retrieved for.

Examples

Get the rotation of the mouse pointer.
const rotation = os.getPointerRotation("mouse");
Get the rotation of the left pointer.
const rotation = os.getPointerRotation("left");

os.disablePointOfView(): EnablePOVAction​

Disables Point-of-View mode on the device. This will return the camera to its original position, set the camera type back to what it was before, and change the camera controls to the defaults.

Examples

Disable POV mode.
os.disablePointOfView();

os.enablePointOfView(center: object, imu?: boolean): EnablePOVAction​

Enables Point-of-View mode on the device. Useful for getting a "ground level" view in the grid portal. This will move the camera to the given position, set the camera type to perspective, and change the camera controls so that dragging the screen causes the camera to look around.

It is not possible to manually move the camera in this mode, however it is still possible to use os.focusOn(bot, options) to move the camera.

The first parameter is a object and is the position that the camera should be placed at. If not specified, then the camera will be placed at (0, 0, 0) .

The second parameter is optional and is a boolean and whether the imuPortal should be used to control the camera rotation while in Point-of-View mode.

Examples

Enable POV mode.
os.enablePointOfView();
Enable POV mode at `(5, 0, 3)`.
os.enablePointOfView({
    x: 5,
    y: 0,
    z: 3
});
Enable POV mode with the IMU.
os.enablePointOfView(undefined, true);

os.calculateRayFromCamera(portal: ("grid" | "miniGrid" | "map" | "miniMap"), viewportCoordinates: Vector2): Promise<RaycastRay>​

Calculates the ray that starts at the given portal camera and travels along the path emanating from the given viewport position. Returns a promise that resolves with information about the calculated ray.

The first parameter is a ("grid" | "miniGrid" | "map" | "miniMap") and is the name of the portal that should be tested.

The second parameter is a Vector2 and is the 2D viewport position that the ray should start at. Viewport positions locate a specific point on the image that the camera produces. (X: 0, Y: 0) represents the center of the camera while (X: -1, Y: -1) represents the lower left corner and (X: 1, Y: 1) represents the upper right corner.

Examples

Find the ray that passes through the center of the screen
const ray = await os.calculateRayFromCamera("grid", new Vector2(0, 0));
os.toast('Calculated ray: ' + ray);
Find the ray that passes through the left-center edge of the screen
const ray = await os.raycastFromCamera("grid", new Vector2(-1, 0));
os.toast('Calculated ray: ' + ray);

os.raycast(portal: ("grid" | "miniGrid" | "map" | "miniMap"), origin: Vector3, direction: Vector3): Promise<RaycastResult>​

Finds the list of bots that are in the given portal and are intersected by a ray starting at the given origin position and traveling in the given direction. Returns a promise that resolves with information about the intersected bots.

The first parameter is a ("grid" | "miniGrid" | "map" | "miniMap") and is the name of the portal that should be tested.

The second parameter is a Vector3 and is the 3D position that the ray should start at.

The third parameter is a Vector3 and is the 3D direction that the ray should travel along.

Examples

Find the bots that are directly to the right of `(0,0,0)` in the grid portal
const result = await os.raycast("grid", new Vector3(0, 0, 0), new Vector3(1, 0, 0));
os.toast('Found Bots: ' + result.botIntersections.map(b => b.id).join(', '));
Find the bots that the mouse pointer is pointing at in the grid portal
const result = await os.raycast("grid", os.getPointerPosition("mouse"), os.getPointerDirection("mouse"));
os.toast('Found Bots: ' + result.botIntersections.map(b => b.id).join(', '));

os.raycastFromCamera(portal: ("grid" | "miniGrid" | "map" | "miniMap"), viewportCoordinates: Vector2): Promise<RaycastResult>​

Finds the list of bots that are in the given portal and are intersected by a ray starting at the portal camera and traveling along a path emanating from the given viewport position. Returns a promise that resolves with information about the intersected bots.

The first parameter is a ("grid" | "miniGrid" | "map" | "miniMap") and is the portal that should be tested.

The second parameter is a Vector2 and is the 2D viewport position that the ray should start at. Viewport positions locate a specific point on the image that the camera produces. (X: 0, Y: 0) represents the center of the camera while (X: -1, Y: -1) represents the lower left corner and (X: 1, Y: 1) represents the upper right corner.

Examples

Find the bots that are in the center of the screen
const result = await os.raycastFromCamera("grid", new Vector2(0, 0));
os.toast('Found Bots: ' + result.botIntersections.map(b => b.id).join(', '));
Find the bots that are on the left-center edge of the screen
const result = await os.raycastFromCamera("grid", new Vector2(-1, 0));
os.toast('Found Bots: ' + result.botIntersections.map(b => b.id).join(', '));

os.showConfirm(options: ShowConfirmOptions): Promise<boolean>​

Shows a confirmation dialog using the given options. Confirmation dialogs are useful for giving users the ability to quickly confirm or cancel an action.

Returns a promise that resolves with true if the user clicked the "Confirm" button and false if they closed the dialog or clicked the "Cancel" button.

The first parameter is a ShowConfirmOptions and is the options that should be used for the confirmation dialog.

Examples

Show a confirmation dialog
let confirmed = await os.showConfirm({
    title: 'Confirm',
    content: 'Please confirm the action.'
});

os.toast('Confirmed: ' + (confirmed ? 'Yes' : 'No'));
Show a confirmation dialog with custom button text
let confirmed = await os.showConfirm({
    title: 'Confirm',
    content: 'Are you sure?',
    confirmText: 'Yes',
    cancelText: 'No'
});

os.toast('Confirmed: ' + (confirmed ? 'Yes' : 'No'));

os.showInput(currentValue?: any, options?: Partial<ShowInputOptions>): Promise<any>​

Shows an input modal with the given value and options. When shown, the player will be able to change the value.

Returns a Promise that resolves with the final value when the user is finished editing. This function is similar to os.showInputForTag(bot, tag, options) except it doesn't require a bot and a tag.

The first parameter is optional and is a any and is the value that should be shown in the input modal.

The second parameter is optional and is a Partial<ShowInputOptions> and is the options that indicate how the input box should be customized.

Examples

Show a basic text input modal and displays a toast message with the input value.
const value = await os.showInput();
os.toast(value);
Show a text input modal with a placeholder.
const name = await os.showInput(null, {
    placeholder: 'Enter a name'
});
os.toast(name);
Show a input modal with a custom title.
const name = await os.showInput('My Name', {
    title: 'Edit name'
});
os.toast(name);
Show a color input modal with a custom title.
const color = await os.showInput('green', {
    type: 'color',
    title: 'Enter a custom color'
});
os.toast(color);
Show an input for entering secrets (like passwords).
const secret = await os.showInput('', {
    type: 'secret',
    title: 'Enter a secret key'
});
os.toast(secret);
Show an input for entering dates.
const date = await os.showInput('', {
    type: 'date',
    title: 'Enter a date'
});
os.toast(date);
Show an input with a list of options.
// Null means nothing is selected
// To pre-select an item, pass in the index of the item you want selected.
const selectedItem = await os.showInput(null, {
    title: 'Select your favorite superhero',
    type: 'list',
    placeholder: 'Superhero',
    items: [
        {
            label: 'Superman',
            value: 1
        },
        {
            label: 'Iron Man',
            value: 2
        },
        {
            label: 'Batman',
            value: 3
        },
        {
            label: 'Wonder Woman',
            value: 4
        }
    ]
});
os.toast(selectedItem);
Show an input with a list of checkboxes.
// Empty array means nothing is selected.
// To pre-select items, pass in an array with the indexes of the items you want selected.
const selectedItems = await os.showInput([], {
    title: 'Check your favorite superheroes',
    type: 'list',
    subtype: 'checkbox',
    items: [
        {
            label: 'Superman',
            value: 1
        },
        {
            label: 'Iron Man',
            value: 2
        },
        {
            label: 'Batman',
            value: 3
        },
        {
            label: 'Wonder Woman',
            value: 4
        }
    ]
});
os.toast(selectedItems);
Show an input with a dropdown of checkboxes.
// Empty array means nothing is selected.
// To pre-select items, pass in an array with the indexes of the items you want selected.
const selectedItems = await os.showInput([], {
    title: 'Select your favorite superheroes',
    type: 'list',
    subtype: 'multiSelect',
    placeholder: 'Superhero',
    items: [
        {
            label: 'Superman',
            value: 1
        },
        {
            label: 'Iron Man',
            value: 2
        },
        {
            label: 'Batman',
            value: 3
        },
        {
            label: 'Wonder Woman',
            value: 4
        }
    ]
});
os.toast(selectedItems);
Show an input with a list of radio buttons.
// Null means nothing is selected.
// To pre-select an item, pass in the index of the item you want selected.
const selectedItem = await os.showInput(null, {
    title: 'Check your favorite superheroe',
    type: 'list',
    subtype: 'radio',
    placeholder: 'Superhero',
    items: [
        {
            label: 'Superman',
            value: 1
        },
        {
            label: 'Iron Man',
            value: 2
        },
        {
            label: 'Batman',
            value: 3
        },
        {
            label: 'Wonder Woman',
            value: 4
        }
    ]
});
os.toast(selectedItem);

os.showInputForTag(bot: (string | Bot), tag: string, options?: Partial<ShowInputOptions>): ShowInputForTagAction​

Shows an input modal for the given bot and tag with the given options. When shown, the player will be able to change the value stored in the given tag. Triggers the @onSaveInput whisper when the modal is closed with saving and the @onCloseInput whisper when the modal is closed without saving.

The first parameter is a (string | Bot) and is the bot or bot ID that the input should be shown for.

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

The third parameter is optional and is a Partial<ShowInputOptions> and is the possible cusomization options for the input modal.

Examples

Show a basic text input modal for the #name tag on this bot.
os.showInputForTag(this, "name");
Show a text input modal with a placeholder for the #name tag.
os.showInputForTag(this, "name", {
    placeholder: 'Enter a name'
});
Show a input modal with a custom title.
os.showInputForTag(this, "name", {
    title: 'Edit name'
});
Show a color input modal with a custom title.
os.showInputForTag(this, "color", {
    type: 'color',
    title: 'Enter a custom color'
});

os.hideTips(tipIds?: (number | number[])): Promise<void>​

Hides the tooltips that have the specified IDs. If no arguments are specified, then all tooltips will be hidden. Returns a promise that resolves when the tooltips have been hidden.

The first parameter is optional and is a (number | number[]) and is the tooltip ID or array of tooltip IDs that should be hidden.

Examples

Show and hide a tooltip message.
const id = await os.tip("Hello!");
await os.sleep(1000);
await os.hideTips(id);

os.tip(message: (string | number | boolean | object | any[]), pixelX?: number, pixelY?: number, duration?: number): Promise<number>​

Shows a temporary "tooltip" message on the screen. Optionally placed at the specified position and shown for the given duration. Returns a promise that resolves with the ID of the new tooltip.

If a position is not specified, then a position just below the current mouse position will be used. If on mobile, then the last touch position will be used or the center of the screen if the user has not touched the screen. Additionally, if a position is not specified then the tooltip will be automatically hidden if the user moves the mouse significantly away from the position that the mouse was at when the tooltip was shown.

The first parameter is a (string | number | boolean | object | any[]) and is the text that the tooltip message should show.

The second parameter is optional and is a number and is the horizontal pixel position that the tooltip should be shown at on the screen. If not specified then the current mouse position will be used.

The third parameter is optional and is a number and is the vertical position that the tooltip should be shown at on the screen. If not specified then a position just below the current mouse position will be used.

The fourth parameter is optional and is a number and is the number of seconds that the toast should be shown for before automatically being hidden. (Default is 2)

Examples

Show a "Hello!" tip message.
os.tip("Hello!");
Show a tip at the center of the screen.
os.tip("This is in the center of the screen.", gridPortalBot.tags.pixelWidth / 2, gridPortalBot.tags.pixelHeight / 2);
Show a tip near the mouse cursor for 5 seconds.
os.tip("5 second tip.", null, null, 5);
Show a tip and record its ID in a tag mask.
masks.tipID = await os.tip("Hello!");

os.addBotDropGrid(bot: (string | Bot), ...targets: SnapGridTarget[]): AddDropGridTargetsAction​

Specifies a list of grids that can be used to position the currently dragged bot when it is being dropped on the given bot.

If called when the user is not dragging anything, then this function does nothing.

The first parameter is a (string | Bot) and is the bot which, when the dragged bot is being dropped onto it (as indicated by @onDropEnter / @onDropExit ), the specified snap targets will take effect.

Each other parameter is a SnapGridTarget and are the list of grids to add.

Examples

Add a grid for the portal that the bot currently exists in when it is being dropped on this bot.
os.addDropGrid(thisBot, {});
Add a grid with a 60 degree X rotation when it is being dropped on this bot.
os.addBotDropGrid(thisBot, {
    position: { x: 0, y: 0, z: 0 },
    rotation: { x: 60 * (Math.PI / 180), y: 0, z: 0 },
});
Add a grid for a specific portal bot when it is being dropped on this bot.
os.addBotDropGrid(thisBot, {
    portalBot: getBot(byTag('form', 'portal'), byTag('formAddress', 'myDimension')),
});
Add a grid with a custom size when it is being dropped on this bot.
os.addBotDropGrid(thisBot, {
    position: { x: 0, y: 0, z: 3 },
    bounds: { x: 20, y: 10 }
});
Add a grid that the user can see when it is being dropped on this bot.
os.addBotDropGrid(thisBot, {
    position: { x: 0, y: 0, z: 3 },
    showGrid: true
});
Add multiple grids with custom priorities when it is being dropped on this bot.
os.addBotDropGrid(thisBot, {
    position: { x: 0, y: 0, z: 3 },
    bounds: { x: 10, y: 10 },
    showGrid: true,
    priority: 10
}, {
    position: { x: 0, y: 0, z: 0 },
    bounds: { x: 20, y: 20 },
    showGrid: true,
    priority: 20
});
Add a spherical grid that the user can see.
os.addBotDropGrid(thisBot, {
    type: "sphere",
    position: { x: 0, y: 0, z: 3 },
    showGrid: true
});

os.addBotDropSnap(bot: (string | Bot), ...targets: SnapTarget[]): AddDropSnapTargetsAction​

Specifies a list of snap targets that can be used to position the currently dragged bot when it is being dropped on the given bot. This function is useful for making some bots act like a "selector" or mask for drop areas.

If called when the user is not dragging anything, then this function does nothing.

The first parameter is a (string | Bot) and is the bot which, when the dragged bot is being dropped onto it (as indicated by @onDropEnter / @onDropExit ), the specified snap targets will take effect.

Each other parameter is a SnapTarget and are the snap targets that should be enabled when the bot is being dropped on.

Examples

Snap the dragged bot to the grid when it is being dropped on this bot.
os.addBotDropSnap(thisBot, "grid");
Snap the dragged bot to this bot's faces.
os.addBotDropSnap(thisBot, "face");
Snap the dragged bot to a point when it is being dropped on this bot.
os.addBotDropSnap(thisBot, {
    position: {
        x: 0,
        y: 0,
        z: 3,
    },
    distance: 1
});
Snap the dragged bot to the center or bot faces when it is being dropped on this bot.
os.addBotDropSnap(thisBot, {
    position: {
        x: 0,
        y: 0,
        z: 0,
    },
    distance: 1
}, "face");

os.addDropGrid(...targets: SnapGridTarget[]): AddDropGridTargetsAction​

Specifies a list of grids that can be used to position the currently dragged bot.

If called when the user is not dragging anything, then this function does nothing.

Each parameter is a SnapGridTarget and are the list of grids to add.

Examples

Add a grid for the portal that the bot currently exists in.
os.addDropGrid({});
Add a grid with a 60 degree X rotation.
os.addDropGrid({
    position: { x: 0, y: 0, z: 0 },
    rotation: { x: 60 * (Math.PI / 180), y: 0, z: 0 },
});
Add a grid for a specific portal bot.
os.addDropGrid({
    portalBot: getBot(byTag('form', 'portal'), byTag('formAddress', 'myDimension')),
});
Add a grid with a custom size.
os.addDropGrid({
    position: { x: 0, y: 0, z: 3 },
    bounds: { x: 20, y: 10 }
});
Add a grid that the user can see.
os.addDropGrid({
    position: { x: 0, y: 0, z: 3 },
    showGrid: true
});
Add multiple grids with custom priorities
os.addDropGrid({
    position: { x: 0, y: 0, z: 3 },
    bounds: { x: 10, y: 10 },
    showGrid: true,
    priority: 10
}, {
    position: { x: 0, y: 0, z: 0 },
    bounds: { x: 20, y: 20 },
    showGrid: true,
    priority: 20
});
Add a spherical grid that the user can see.
os.addDropGrid({
    type: "sphere",
    position: { x: 0, y: 0, z: 3 },
    showGrid: true
});

os.addDropSnap(...targets: SnapTarget[]): AddDropSnapTargetsAction​

Specifies a list of snap targets that can be used to position the currently dragged bot.

If called when the user is not dragging anything, then this function does nothing.

Each parameter is a SnapTarget and are the list of snap targets to add.

Examples

Snap the dragged bot to the grid.
os.addDropSnap("grid");
Snap the dragged bot to other bot faces.
os.addDropSnap("face");
Snap the dragged bot to a point.
os.addDropSnap({
    position: {
        x: 0,
        y: 0,
        z: 3,
    },
    distance: 1
});
Snap the dragged bot to the global X axis.
os.addDropSnap({
    direction: {
        x: 1,
        y: 0,
        z: 0,
    },
    origin: {
        x: 0,
        y: 0,
        z: 0
    },
    distance: 2
});
Snap the dragged bot to the center or bot faces.
os.addDropSnap({
    position: {
        x: 0,
        y: 0,
        z: 0,
    },
    distance: 1
}, "face");

os.enableCustomDragging(): EnableCustomDraggingAction​

Enables "custom dragging" for the current bot drag operation.

Custom dragging tells CasualOS to not move the bot to the dragged position. Instead, it will calculate where the bot would be dragged and send that information in the @onDragging and @onAnyBotDragging listeners.

This is useful for custom bot dragging behavior like choosing to scale or rotate a bot instead of moving it.

Examples

Enable custom dragging for the current drag operation
os.enableCustomDragging();

os.focusOn(bot: (string | Bot), options?: FocusOnOptions): Promise<void>​

Focuses on the given bot. For bots in the bot or miniGridPortals, this animates the camera such that the portal focus point is placed on the given bot or position. For input bots in menu portal, this gives keyboard focus to them.

Returns a promise which resolves when the bot has been focused. For the bot and miniGridPortals this is when the animation finishes and rejects if the user takes control of the camera during the animation. For menu bots this is when the input field is focused and rejects if the bot is not a input bot.

The first parameter is a (string | Bot) and

The second parameter is optional and is a FocusOnOptions and is the additional options to use for the focus operation. This can be used to change how the camera moves or to specify which portal the bot should be focused in.

Examples

Move the player's view to show a bot named bob.
await os.focusOn(getBot("#name", "bob"));
Move the player's view to show this bot from the top.
await os.focusOn(thisBot, {
    rotation: {
        x: 0,
        y: 0
    }
});
Move the player's view to show this bot with a particular zoom value.
await os.focusOn(thisBot, {
    zoom: 15
});
Focus on this bot in the menu portal
await os.focusOn(thisBot, {
    portal: 'menu'
});
Rotate the camera around the focus point 3 times.
await os.focusOn(thisBot, {
    rotation: {
        y: (Math.PI * 2) * 3,
        normalize: false
    }
});
Focus the onClick tag in the systemPortal
await os.focusOn(thisBot, {
    tag: 'onClick',
    portal: 'system'
});
Focus line 2 in the onClick tag in the sheetPortal
await os.focusOn(thisBot, {
    tag: 'onClick',
    lineNumber: 2,
    portal: 'sheet'
});
Focus index 9 through 15 in the onClick tag in the tagPortal
await os.focusOn(thisBot, {
    tag: 'onClick',
    startIndex: 9,
    endIndex: 15,
    portal: 'tag'
});

os.focusOn(position: object, options?: FocusOnOptions): Promise<void>​

Focuses on the given position.

Returns a promise which resolves when the position has been focused.

The first parameter is a object and

The second parameter is optional and is a FocusOnOptions and is the additional options to use for the focus operation. This can be used to change how the camera moves or to specify which portal the bot should be focused in.

Examples

Move the player's view to a specific position.
await os.focusOn({
    x: 15,
    y: 9.5
});
Focus on Buckingham Palace in the map portal
await os.focusOn({
    x: -0.141329,
    y: 51.501541
}, {
    portal: 'map',
    zoom: 10000
});

os.replaceDragBot(bot: Bot): ReplaceDragBotAction​

Replaces the bot that the user is dragging with the given bot.

If called when the user is not dragging anything, then the given bot or mod will be dragged using the current input method. When in VR, the current input method is the most recently used VR controller. Otherwise it is the mouse/touchscreen.

The first parameter is a Bot and is the bot that should be dragged. If given a bot while dragging, then that bot's @onDrag will be skippped but @onDrop will be called. If given a bot when not dragging, then that bot's @onDrag and @onDrop will be called.

Examples

Drag a clone of this bot.
let clone = create(thisBot);
os.replaceDragBot(clone);