@casual-simulation/aux-common 3.1.35 → 3.2.0

package/bots/Bot.d.ts

@@ -41,10 +41,28 @@ export declare const REPLACE_BOT_SYMBOL: unique symbol;
  * are calculated values and raw is the original tag values.
  *
  * i.e. tags will evaluate formulas while raw will return the formula scripts themselves.
+ *
+ * @dochash types/core
+ * @docgroup 01-core
+ * @doctitle Core Types
+ * @docsidebar Core
+ * @docdescription Documentation for core types that are used throughout CasualOS.
+ * @docid RuntimeBot
+ * @docname Bot
  */
 export interface RuntimeBot {
+    /**
+     * The ID of the bot.
+     */
     id: string;
+    /**
+     * The link to the bot.
+     */
     link: string;
+    /**
+     * The space that the bot is in.
+     * Defaults to `"shared"`
+     */
     space?: BotSpace;
     /**
      * The calculated tag values.
@@ -77,6 +95,8 @@ export interface RuntimeBot {
     maskChanges: BotTagMasks;
     /**
      * The signatures that are on the bot.
+     *
+     * @hidden
      */
     signatures: BotSignatures;
     /**
@@ -86,40 +106,74 @@ export interface RuntimeBot {
     listeners: CompiledBotListeners;
     /**
      * A function that can clear all the changes from the runtime bot.
+     *
+     * @hidden
      */
     [CLEAR_CHANGES_SYMBOL]: () => void;
     /**
      * A function that can set a tag mask on the bot.
+     *
+     * @hidden
      */
     [SET_TAG_MASK_SYMBOL]: (tag: string, value: any, space?: string) => void;
     /**
      * A function that can be used to get the tag masks for a bot.
+     *
+     * @hidden
      */
     [GET_TAG_MASKS_SYMBOL]: () => BotTagMasks;
     /**
      * A function that can clear the tag masks from the bot.
      * @param space The space that the masks should be cleared from. If not specified then all tag masks in all spaces will be cleared.
+     *
+     * @hidden
      */
     [CLEAR_TAG_MASKS_SYMBOL]: (space?: string) => any;
     /**
      * A function that can manipulate a tag using the given edit operations.
+     *
+     * @hidden
      */
     [EDIT_TAG_SYMBOL]: (tag: string, ops: TagEditOp[]) => any;
     /**
      * A function that can manipulate a tag mask using the given edit operations.
+     *
+     * @hidden
      */
     [EDIT_TAG_MASK_SYMBOL]: (tag: string, ops: TagEditOp[], space: string) => any;
     /**
      * A function that can cause all tags to be fowarded to the given bot.
+     *
+     * @hidden
      */
     [REPLACE_BOT_SYMBOL]: (bot: RuntimeBot) => void;
     /**
-     * Gets the listener with the given name.
+     * Gets the listener or bot property with the given name.
+     *
+     * If given a property name, like `"tags"` or `"vars"`, then it will return the value of that property.
+     * Alternatively, if the name does not match an existing property on the bot, then it will return the listener with the given name.
+     *
+     * @example Get the tags of a bot
+     * let tags = bot.tags;
+     *
+     * @example Get the links of a bot
+     * let links = bot.links;
+     *
+     * @example Get the @onClick listener of a bot
+     * let onClick = bot.onClick;
+     *
+     * @example Get a property on a bot by a variable
+     * let propertyToGet = 'tags';
+     * let tags = bot[propertyToGet];
      */
-    [listener: string]: CompiledBotListener | any;
+    [listenerOrProperty: string]: ((arg?: any) => any) | any;
 }
 /**
  * Defines an interface that represents a bot link that was parsed from a tag.
+ *
+ * @dochash types/core
+ * @docgroup 01-core
+ * @docname ParsedBotLink
  */
 export interface ParsedBotLink {
     /**
@@ -133,24 +187,79 @@ export interface ParsedBotLink {
 }
 /**
  * Defines an interface that represents the bot links a bot can have.
+ *
+ * ```typescript
+ * interface Links {
+ *      [link: string]: Bot | Bot[];
+ * }
+ * ```
+ *
+ * @dochash types/core
+ * @docgroup 01-core
+ * @docname Links
+ * @docid RuntimeBotLinks
  */
 export interface RuntimeBotLinks {
+    /**
+     * Gets the bot or bots that are linked in the given tag.
+     *
+     * @example Get a bot that is linked in the #manager tag
+     * let managerBot = thisBot.links.manager;
+     *
+     * @example Link a bot to another bot in the #manager tag
+     * thisBot.links.manager = managerBot;
+     */
     [tag: string]: RuntimeBot | RuntimeBot[];
 }
 /**
  * Defines an interface that represents the variables a bot can have.
+ * Variables are useful for storing data that is not able to be saved to a tag.
+ *
+ * ```typescript
+ * interface Variables {
+ *      [variable: string]: any;
+ * }
+ * ```
+ *
+ * @dochash types/core
+ * @docgroup 01-core
+ * @docname Variables
+ * @docid RuntimeBotVars
  */
 export interface RuntimeBotVars {
+    /**
+     * Gets or sets a variable on the bot.
+     *
+     * @example Get a variable on thisBot
+     * let variable = thisBot.vars.variable;
+     *
+     * @example Save a variable on thisBot
+     * thisBot.vars.variable = variable;
+     */
     [variable: string]: any;
 }
 /**
  * An interface that maps tag names to compiled listener functions.
+ *
+ * ```typescript
+ * interface Listeners {
+ *      [tag: string]: (arg?: any) => any;
+ * }
+ * ```
+ *
+ * @dochash types/core
+ * @docgroup 01-core
+ * @docname Listeners
+ * @docid CompiledBotListeners
  */
 export interface CompiledBotListeners {
-    [tag: string]: CompiledBotListener;
+    /**
+     * Gets the listener in the given tag.
+     */
+    [tag: string]: (arg?: any) => any;
 }
 /**
- * The type of a compiled bot listener.
+ * The function signature of a bot listener.
  */
 export type CompiledBotListener = (arg?: any) => any;
 /**
@@ -174,6 +283,9 @@ export interface PrecalculatedTags {
 }
 /**
  * Defines an interface for a bot.
+ *
+ * @docid Bot
+ * @docrename RuntimeBot
  */
 export interface Bot {
     /**
@@ -254,16 +366,18 @@ export interface UpdatedBot {
     signatures?: string[];
 }
 /**
- * The possible bot types.
+ * The possible bot spaces.
+ *
+ * - `"shared"` means that the bot is a normal bot.
+ * - `"local"` means that the bot is stored in the [local storage](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Client-side_storage) partition.
+ * - `"tempLocal"` means that the bot is stored in the [temporary](https://en.wikipedia.org/wiki/In-memory_database) partition.
+ * - `"tempShared"` means that the bot is temporary and shared with other devices.
+ * - `"remoteTempShared"` means that the bot is temporary and shared with this device from a remote device.
  *
- * - "shared" means that the bot is a normal bot.
- * - "local" means that the bot is stored in the local storage partition.
- * - "tempLocal" means that the bot is stored in the temporary partition.
- * - "history" means that the bot represents a version of another space.
- * - "admin" means that the bot is shared across all instances.
- * - "tempShared" means that the bot is temporary and shared with other devices.
- * - "remoteTempShared" means that the bot is temporary and shared with this device from a remote device.
- * - "certified" means that the bot is a certificate.
+ * @dochash types/core
+ * @docgroup 01-core
+ * @docname Space
+ * @docid BotSpace
  */
 export type BotSpace = 'shared' | 'local' | 'tempLocal' | 'history' | 'admin' | 'tempShared' | 'remoteTempShared' | 'certified';
 /**
@@ -281,8 +395,15 @@ export type RecordSpace = 'tempGlobal' | 'tempRestricted' | 'permanentGlobal' |
 export declare const DEFAULT_RECORD_SPACE: RecordSpace;
 /**
  * The possible portal types.
+ *
+ * @dochash types/core
+ * @docname PortalType
  */
 export type PortalType = 'grid' | 'miniGrid' | 'menu' | 'sheet' | 'meet' | 'system' | string;
+/**
+ * @docid ScriptTags
+ * @docrename BotTags
+ */
 export interface ScriptTags extends PrecalculatedTags {
     toJSON(): any;
 }
@@ -307,122 +428,381 @@ export interface BotSignatures {
  * The actual data structure is similar to the bot tags structure except that tags are additionally
  * split by the space that they originated from. This makes it possible to identify which space a tag came from and also
  * prevents cross-space conflicts.
+ *
+ * ```typescript
+ * interface TagMasks {
+ *      [space: string]: Tags;
+ * }
+ * ```
+ *
+ * @dochash types/core
+ * @docgroup 01-core
+ * @docname TagMasks
+ * @docid BotTagMasks
  */
 export interface BotTagMasks {
+    /**
+     * Gets or sets the tag masks that are specific to the given space.
+     */
     [space: string]: BotTags;
 }
+/**
+ * Defines an interface that represents a set of tags and their related values.
+ *
+ * ```typescript
+ * interface Tags {
+ *      [tag: string]: any
+ * }
+ * ```
+ *
+ * @dochash types/core
+ * @docgroup 01-core
+ * @docname Tags
+ * @docid BotTags
+ */
 export interface BotTags {
+    /**
+     * @hidden
+     */
     ['color']?: unknown;
+    /**
+     * @hidden
+     */
     ['draggable']?: unknown;
+    /**
+     * @hidden
+     */
     ['draggableMode']?: unknown;
+    /**
+     * @hidden
+     */
     ['destroyable']?: unknown;
+    /**
+     * @hidden
+     */
     ['editable']?: unknown;
+    /**
+     * @hidden
+     */
     ['strokeColor']?: unknown;
+    /**
+     * @hidden
+     */
     ['strokeWidth']?: unknown;
+    /**
+     * @hidden
+     */
     ['scale']?: number;
+    /**
+     * @hidden
+     */
     ['scaleX']?: number;
+    /**
+     * @hidden
+     */
     ['scaleY']?: number;
+    /**
+     * @hidden
+     */
     ['scaleZ']?: number;
+    /**
+     * @hidden
+     */
     ['scaleMode']?: BotScaleMode | null | string;
+    /**
+     * @hidden
+     */
     ['lineTo']?: unknown;
+    /**
+     * @hidden
+     */
     ['lineWidth']?: number;
+    /**
+     * @hidden
+     */
     ['lineStyle']?: unknown;
+    /**
+     * @hidden
+     */
     ['lineColor']?: unknown;
+    /**
+     * @hidden
+     */
     ['label']?: unknown;
+    /**
+     * @hidden
+     */
     ['labelColor']?: unknown;
+    /**
+     * @hidden
+     */
     ['labelSize']?: unknown;
+    /**
+     * @hidden
+     */
     ['labelSizeMode']?: 'auto' | null;
+    /**
+     * @hidden
+     */
     ['labelPosition']?: BotLabelAnchor | null | string;
+    /**
+     * @hidden
+     */
     ['labelAlignment']?: BotLabelAlignment | null | string;
+    /**
+     * @hidden
+     */
     ['labelFontAddress']?: BotLabelFontAddress;
+    /**
+     * @hidden
+     */
     ['listening']?: unknown;
+    /**
+     * @hidden
+     */
     ['form']?: BotShape;
+    /**
+     * @hidden
+     */
     ['formAnimation']?: string;
+    /**
+     * @hidden
+     */
     ['formAddress']?: string;
+    /**
+     * @hidden
+     */
     ['formOpacity']?: unknown;
+    /**
+     * @hidden
+     */
     ['orientationMode']?: string;
+    /**
+     * @hidden
+     */
     ['anchorPoint']?: string;
+    /**
+     * @hidden
+     */
     ['creator']?: string;
+    /**
+     * @hidden
+     */
     ['progressBar']?: unknown;
+    /**
+     * @hidden
+     */
     ['progressBarColor']?: unknown;
+    /**
+     * @hidden
+     */
     ['progressBarBackgroundColor']?: unknown;
+    /**
+     * @hidden
+     */
     ['progressBarPosition']?: unknown;
+    /**
+     * @hidden
+     */
     ['pointable']?: unknown;
+    /**
+     * @hidden
+     */
     ['focusable']?: unknown;
+    /**
+     * @hidden
+     */
     ['auxPlayerActive']?: boolean;
+    /**
+     * @hidden
+     */
     ['gridPortal']?: string | boolean;
+    /**
+     * @hidden
+     */
     ['sheetPortal']?: string | boolean;
+    /**
+     * @hidden
+     */
     ['inst']?: string | string[];
+    /**
+     * @hidden
+     */
     ['miniGridPortal']?: string;
+    /**
+     * @hidden
+     */
     ['menuPortal']?: string;
+    /**
+     * @hidden
+     */
     ['leftWristPortal']?: string;
+    /**
+     * @hidden
+     */
     ['rightWristPortal']?: string;
+    /**
+     * @hidden
+     */
     ['editingBot']?: string;
+    /**
+     * @hidden
+     */
     cursorStartIndex?: number;
+    /**
+     * @hidden
+     */
     cursorEndIndex?: number;
+    /**
+     * @hidden
+     */
     ['pixelWidth']?: number;
+    /**
+     * @hidden
+     */
     ['pixelHeight']?: number;
-    ['auxRunningTasks']?: boolean;
-    ['auxFinishedTasks']?: boolean;
-    ['taskOutput']?: unknown;
-    ['taskError']?: unknown;
-    ['taskTime']?: unknown;
-    ['taskShell']?: string;
-    ['taskBackup']?: boolean;
-    ['taskBackupType']?: BackupType;
-    ['taskBackupUrl']?: string;
+    /**
+     * @hidden
+     */
     ['portalColor']?: string;
+    /**
+     * @hidden
+     */
     ['portalLocked']?: unknown;
+    /**
+     * @hidden
+     */
     ['portalGridScale']?: number;
+    /**
+     * @hidden
+     */
     ['portalSurfaceScale']?: number;
+    /**
+     * @hidden
+     */
     ['portalCameraRotationX']?: number;
+    /**
+     * @hidden
+     */
     ['portalCameraRotationY']?: number;
+    /**
+     * @hidden
+     */
     ['portalCameraZoom']?: number;
+    /**
+     * @hidden
+     */
     ['portalPannable']?: number | null;
+    /**
+     * @hidden
+     */
     [`portalPannableMinX`]?: number | null;
+    /**
+     * @hidden
+     */
     [`portalPannableMaxX`]?: number | null;
+    /**
+     * @hidden
+     */
     [`portalPannableMinY`]?: number | null;
+    /**
+     * @hidden
+     */
     [`portalPannableMaxY`]?: number | null;
+    /**
+     * @hidden
+     */
     ['portalZoomable']?: number | null;
+    /**
+     * @hidden
+     */
     [`portalZoomableMin`]?: number | null;
+    /**
+     * @hidden
+     */
     [`portalZoomableMax`]?: number | null;
+    /**
+     * @hidden
+     */
     ['portalRotatable']?: number | null;
+    /**
+     * @hidden
+     */
     ['portalShowFocusPoint']?: boolean | null;
+    /**
+     * @hidden
+     */
     ['portalDisableCanvasTransparency']?: boolean;
+    /**
+     * @hidden
+     */
     ['miniPortalHeight']?: unknown;
+    /**
+     * @hidden
+     */
     ['miniPortalResizable']?: boolean;
+    /**
+     * @hidden
+     */
     ['wristPortalHeight']?: number;
+    /**
+     * @hidden
+     */
     ['wristPortalWidth']?: number;
-    ['stripeCharges']?: boolean;
-    ['stripeSuccessfulCharges']?: boolean;
-    ['stripeFailedCharges']?: boolean;
-    ['stripeCharge']?: string;
-    ['stripeChargeReceiptUrl']?: string;
-    ['stripeChargeReceiptNumber']?: string;
-    ['stripeChargeDescription']?: string;
-    ['stripeOutcomeNetworkStatus']?: string;
-    ['stripeOutcomeReason']?: string;
-    ['stripeOutcomeRiskLevel']?: string;
-    ['stripeOutcomeRiskScore']?: number;
-    ['stripeOutcomeRule']?: string | string[];
-    ['stripeOutcomeSellerMessage']?: string;
-    ['stripeOutcomeType']?: string;
-    ['stripeErrors']?: boolean;
-    ['stripeError']?: string;
-    ['stripeErrorType']?: string;
-    [key: string]: any;
+    /**
+     * Gets or sets the given tag on the bot.
+     *
+     * @example Get the #color on this bot
+     * let color = thisBot.tags.color;
+     *
+     * @example Get a raw tag on this bot
+     * let rawTag = thisBot.raw.tag;
+     *
+     * @example Set the #color tag to "red" on this bot
+     * thisBot.tags.color = "red";
+     *
+     * @example Set a tempLocal tag mask for #color on this bot
+     * thisBot.masks.color = "red";
+     */
+    [tag: string]: any;
 }
 /**
- * Defines an interface for the state that an AUX bot can contain.
+ * Defines an interface that contains a set of bots that have been indexed by their IDs.
+ *
+ * Generally, this is only used when working with groups of bots.
+ * For example, the {@link diffSnapshots} function takes two bot states and produces the difference between them.
+ *
+ * @dochash types/core
+ * @docgroup 01-core
+ * @docname BotState
+ *
+ * @example Create a bot state with two bots
+ * let state = {
+ *    [bot1.id]: bot1,
+ *    [bot2.id]: bot2
+ * };
+ *
+ * @example Get a bot by its ID from a bot state
+ * let bot = state[botId];
  */
 export interface BotsState {
+    /**
+     * Gets or sets the bot in the state with the given ID.
+     */
     [id: string]: Bot;
 }
 /**
- * Defines an interface for a partial bot state.
+ * Defines an interface that contains a set of partial bots that have been indexed by their IDs.
+ *
+ * Generally, this is only used when working with differences between groups of bots.
+ * For example, the {@link applyDiffToSnapshot} function takes a bot state and a partial bot state and produces a final state that contains the combined result.
+ *
+ * @dochash types/core
+ * @docgroup 01-core
+ * @docname PartialBotState
  */
 export interface PartialBotsState {
-    [id: string]: PartialBot;
+    [id: string]: Partial<Bot>;
 }
 /**
  * Defines an interface for a set of bots that have precalculated formulas.
@@ -509,6 +889,9 @@ export type BotLabelWordWrap = 'breakWords' | 'breakCharacters' | 'none';
 export type BotOrientationMode = 'absolute' | 'billboard' | 'billboardTop' | 'billboardFront';
 /**
  * Defines the possible bot anchor points.
+ *
+ * @dochash types/core
+ * @docname BotAnchorPoint
  */
 export type BotAnchorPoint = 'top' | 'front' | 'back' | 'left' | 'right' | 'bottom' | 'center' | readonly [number, number, number];
 /**