Skip to content

ab

Jump to bottom
Ryan Cook edited this page Dec 5, 2025 · 18 revisions

ab spinning

Overview

AB is a set of tools that make building in CasualOS simple and user-friendly. AB manifests itself as a spinning cube that can be interacted with. It's designed to be usable across a wide spectrum of device types including desktops, phones, tablets, and AR/VR headsets. Due to ab's device-agnostic focus, using ab is intentionally designed to be very simple: clicks/taps, as well as drags and drops. Beyond the physical interactions, ab will manifest its context-sensitive options in menus using the CasualOS menuPortal.

This document is intended to provide some context for the pieces that make up ab as well as how you can utilize the many tools it provides and extend it.

Table of Contents

Note

Sections marked with 🚧 are still being worked on.

abCore

abCore acts as the core/root of ab. It's primary purpose is to initialize ab and contain the functionality for loading ab skills that extend the functionality of ab. abCore is also where the functionality of updating ab at runtime occurs.

abCore can be accessed with the helper variable ab which is available to any scripts in CasualOS once the shouts @onABInitialized, @onABAdded, or the whisper @onEggHatch has occurred.

Tip

ab is a direct reference to the abCore learn bot and is considered the top-level ab bot. You can reach most of the ab skills from here as well using the link tags store on the learn bot.

// Use abCore's search bot link to call onLookupABEggs on search.
ab.links.search.onLookupABEggs({...})
// Get the current dimension that ab is in from the remember bot.
const abDim = ab.links.remember.abActiveDimension;

abConfig

abConfig is the configuration aux for ab. abConfig is separate from abCore because abConfig is designed to be unique to each CasualOS environment. abConfig contains many tags that abCore and ab skills will read to setup functionality and behavior.

Tags

abActiveDimension

The dimension that ab was last manifested in.

value description
Any String The name of the dimension.

↑ back to top

abAllowChatBar

Wether or not the ab chat bar is allowed to be opened. The chat bar is typically opened with the ` key.

value description
true The ab chat bar is allowed. (default)
false The ab chat bar is not allowed.

↑ back to top

abAlwaysStartAwake

Wether or not ab will always wake up during boot regardless of if a pattern or ask was loaded during initial boot. This is ignored if abSleep is set to true on configBot.

value description
true ab will always wake up during boot.
false ab will only wake if its during initial boot and a pattern or ask is not being loaded (default)

↑ back to top

abBaseColor

The color that the manifested ab bot is.

Note

This is copied by abPersonality and customized by the user.
If you want the current value use ab.links.personality.tags.abBaseColor.

value description
Any Color (RGB, Hex, Web color) Any color that is in RGB format, Hexadecimal format (3 or 6 digit) or web color name

↑ back to top

abBaseStrokeColor

The color of the stroke that the manifested ab bot is.

Note

This is copied by abPersonality and customized by the user.
If you want the current value use ab.links.personality.tags.abBaseStrokeColor.

value description
Any Color (RGB, Hex, Web color) Any color that is in RGB format, Hexadecimal format (3 or 6 digit) or web color name

↑ back to top

abBlueprintColor

The color of the blueprint portal.

Note

This is copied by abPersonality and customized by the user.
If you want the current value use ab.links.personality.tags.abBlueprintColor.

value description
Any Color (RGB, Hex, Web color) Any color that is in RGB format, Hexadecimal format (3 or 6 digit) or web color name

↑ back to top

abBotSnapState

Wether or not to enable bot face snapping when dragging bots.

value description
true Dragged bots can be snapped to other bot faces. (default)
false Dragged bots will not snap to other bot faces.

↑ back to top

abBuilderIdentity

The name that the ab will refer to itself as.

Note

This is copied by abPersonality and customized by the user.
If you want the current value use ab.links.personality.tags.abBuilderIdentity.

value description
Any String The name that ab will refer to itself as.

↑ back to top

abGridSnapState

Wether or not to enable grid snapping when dragging bots.

value description
true Dragged bots can be snapped to grid. (default)
false Dragged bots will not snap to grid.

↑ back to top

abListeningForFileUploads

Wether or not users are able to upload files that are drag and dropped into the portal. If enabled and the drag and drop file is supported, it will be uploaded to the user's studio and a bot representing the uploaded file will be created in the current grid/map portal.

Supported file types:

  • .jpg
  • .jpeg
  • .webp
  • .gif
  • .png
  • .svg
  • .glb
  • .exr
  • .gltf
  • .aux *
  • .pdf **
  • .mp3
  • .mp4
  • .otf
  • .woff

* .aux and .pdf files are not uploaded, they instead be parsed for bot data and if any is found will be created in the current inst.

** only .pdf files created by using the pdf export functionality of os.downloadBots are currently supported.

value description
true Supported files that are drag and dropped into the portal will upload. (default)
false Drag and drop file upload is disabled.

↑ back to top

abPreferredAIModel

The AI model name that the ab will prefer to use by default when submitRequestGPT is called. If one is not given CasualOS itself also has a built-in default AI model, but this is ab's own default.

Note

This is copied by abPersonality and customized by the user.
If you want the current value use ab.links.personality.tags.abPreferredAIModel.

value description
Any String The ai model name that ab will prefer to use by default in submitRequestGPT.

↑ back to top

abRecordKey

The key for the public ab record. This should be a key to access the ab public record by the name of abRecordName.

Important

It is not recommended to change this once it has been setup. Much of ab's file IO is dependent on this being static for the CasualOS environment.

value description
Record Key The record key for use to access the public ab record. Can be generated with for a given public record name using os.getPublicRecordKey.

↑ back to top

abRecordName

The name of the public ab record. If a key is needed to access this record use abRecordKey.

Important

It is not recommended to change this once it has been setup. Much of ab's file IO is dependent on this being static for the CasualOS environment.

value description
Any String The record name for the public ab record.

↑ back to top

allowChannels

Wether or not ab channels are allowed to be used.

value description
true Channels are allowed (default)
false Channels are not allowed.

↑ back to top

builderSkillArray

An Array of ab skills to load at boot when running CasualOS in builder mode. Builder mode is enabled for CasualOS deployments that allow users to create experiences.

value description
Array of strings Array of ab skill names.

↑ back to top

casualCatalogEnv

The environment to load files from in the casual catalog.

value description
prod Load casual catalog files from the production environment.
dev Load casual catalog files from the development environment.

↑ back to top

casualCatalogURL

The base URL of the casual catalog.

value description
Any public URL Base URL of the casual catalog.

↑ back to top

initialBoot

Wether or not ab is to perform initial boot logic when the inst is loaded. This always becomes masked with false after ab has performed its initial boot.

value description
true ab will perform initial boot logic. (default)
false ab will no longer perform initial boot logic.

↑ back to top

playerSkillArray

An Array of ab skills to load at boot when running CasualOS in player mode. Player mode is enabled for CasualOS deployments that only allow users to use experiences.

value description
Array of strings Array of ab skill names.

↑ back to top

subscriptionsEnabled

Wether or not subscriptions are enabled for the CasualOS environment that ab is being loaded in.

Important

It is not recommended to change this once it has been setup. This is just reference for ab to show proper functionality depending on how the CasualOS environment has been configured and does not generally change.

value description
true Subscriptions are enabled in this CasualOS environment.
false Subscriptions are not enabled in this CasualOS environment.

↑ back to top

toolbox_array

Array of toolkits to make available in the ab catalog menu.

value description
Array of toolkit entries List of toolkits to show in the ab catalog menu.

Toolkit entry:

field type required description
title string No Display-friendly name of the toolkit. Will use name if left undefined.
name string ✅ Yes The name of the toolkit file.
studio false or string No Wether the toolkit should be loaded from a specified studio. If left undefined or false will load from the casual catalog.

Example:

🧬[
    {
        "title": "toolkit a",
        "name": "toolkit_a",
        "studio": false
    },
    {
        "title": "toolkit b",
        "name": "toolkit_b",
        "studio": false
    },
    {
        "title": "other tools",
        "name": "the_other_tools",
        "studio": "00000000-0000-0000-0000-000000000000"
    }
]

↑ back to top

skills

Skills are the components that ab loads to extend its capabilities.

abShell

🚧 artifact

Warning

This section is under construction

↑ back to top

🚧 create

Warning

This section is under construction

↑ back to top

🚧 grid

Warning

This section is under construction

↑ back to top

🚧 input

The input bot is where abShell houses its commands and chat bar functionality.

chat bar

The ab chat bar can be opened with either the ` key or by using the finger tap code 3342 on a mobile device.
The chat bar can be closed by pressing the esc key, click/tapping on an empty grid space.

The ab chat bar is primarily used for entering ab commands, but is internally just using os.showChat and os.hideChat.

You can programmatically open/close the ab chat bar with @abChatBarOpen and @abChatBarClose respectively.

commands

AB Commands are built are terminal style commands that can be entered into the ab chat bar (` key).

Tip

.help in the ab chat bar shows a full list of available commands.

ab spinning

add your own commands

AB Commands system is extensible, allowing users to add their own commands.

  1. Listen for @onABCommandsManagerCreated
  2. @onABCommandsManagerCreated will be passed an instance of ABCommandsManager 
// at the top of your `@onABCommandsManagerCreated` tag:
const abCommandsManager: ABCommandsManager = that;
  1. Add your own commands like so:
const abCommandsManager: ABCommandsManager = that;

abCommandsManager.addCommand('myCoolCommand', (args) => {
    // This is your callback function that executes when your command is used.
    // ...
    // ...
}, {
    shortDescription: 'This is a short description for the command.',
    longDescription: `This is an OPTIONAL much longer description for the command that only shows up in the help page specific to this command.
    
    It supports line breaks which make doing some basic formatting a lot easier.
    
    =========
    Header 01
    =========
    
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius, ligula vitae tincidunt lacinia, mauris libero convallis justo, et tincidunt libero nunc vehicula nisi.

    > Duis non gravida sem.

    =========
    Header 02
    =========

    Aenean porta efficitur mattis. Curabitur iaculis porta ullamcorper. Nunc sodales lectus et dolor tincidunt, eu vulputate elit tincidunt. In id dolor non tortor commodo suscipit.
    `,
    usage: [
        '.myCoolCommand',
        '.myCoolCommand -v 3 -d',
    ],
    args: [
        {
            identifier: '-v',
            description: 'This is the -v parameter and it takes a number.',
        },
        {
            identifier: '-d',
            description: 'This is the -d flag',
        },
    ]
});

Tip

You can check out ab's built-in commands on the ab.shell.input bot in the @onABCommandsManagerCreated tag.

↑ back to top

🚧 search

Warning

This section is under construction

↑ back to top

🚧 store

Warning

This section is under construction

↑ back to top

🚧 utils

Warning

This section is under construction

↑ back to top

🚧 abInterface

Warning

This section is under construction

↑ back to top

nuggets

Nuggets allow the loading and publishing of code snippets while in the sheet, tag, or system portal. It utilizes the codeButton form to offer several options to users while scripting in a tag.

To load a nugget, you can put the name of a nugget (no spaces) inside a set of brackets. Adding a period and v with a number to the end of the nugget name (.v#) allows the user to specify the version of the nugget that they would like to load.

loading nuggets

Loading a nugget:

{hello} // loads the latest version of hello

Loading a specific version of a nugget:

{hello.v1} // loads hello version 1

publishing nuggets

To publish a nugget, you use a similar format to loading with the addition of .nug and a space before it. Then, using the cursor, highlight the segment you wish to publish. With it still highlighted, press the codeButton.

.nug {myNugget}

↑ back to top

🚧 abAction

Warning

This section is under construction

↑ back to top

🚧 abPersonality

Warning

This section is under construction

↑ back to top

🚧 config

Warning

This section is under construction

↑ back to top

🚧 manifestation

Warning

This section is under construction

↑ back to top

🚧 arm

Warning

This section is under construction

↑ back to top

🚧 abChannel

Warning

This section is under construction

↑ back to top

Clone this wiki locally