@casual-simulation/aux-common 2.0.16 → 2.0.21

package/runtime/AuxLibraryDefinitions.def

@@ -965,6 +965,31 @@ declare interface WebhookOptions {
      * The shout that should be made when the request finishes.
      */
     responseShout?: string;
+
+    /**
+     * The number of retries that should be attempted for the webhook if it fails.
+     * Defaults to 0.
+     */
+    retryCount?: number;
+
+    /**
+     * The HTTP response status codes that should allow the web request to be retried.
+     * Defaults to:
+     *  - 408 - Request Timeout
+     *  - 429 - Too Many Requests
+     *  - 500 - Internal Server Error
+     *  - 502 - Bad Gateway
+     *  - 503 - Service Unavailable
+     *  - 504 - Gateway Timeout
+     *  - 0 - Network Failure / CORS
+     */
+    retryStatusCodes?: number[];
+
+    /**
+     * The number of miliseconds to wait between retry requests.
+     * Defaults to 3000ms (3 seconds).
+     */
+    retryAfterMs?: number;
 }
 
 /**
@@ -2303,6 +2328,26 @@ export interface DeletableRecord {
      address: string;
 };
 
+/**
+ * Defines an interface that represents options for converting a geolocation to a what3words address.
+ */
+export interface ConvertGeolocationToWhat3WordsOptions {
+    /**
+     * The latitude to convert.
+     */
+    latitude: number;
+
+    /**
+     * The longitude to convert.
+     */
+    longitude: number;
+
+    /**
+     * The identifier of the language that should be used for the resulting what3words address.
+     */
+    language?: string;
+}
+
 /**
  * Defines an interface for options that show a payment box.
  */
@@ -2432,6 +2477,32 @@ declare interface BotTags {
     [key: string]: any;
 }
 
+/**
+ * Defines an interface that represents a bot link that was parsed from a tag.
+ */
+declare interface ParsedBotLink {
+    /**
+     * The tag that the link was parsed from.
+     */
+    tag: string;
+
+    /**
+     * The bot IDs that the link references.
+     */
+    botIDs: string[];
+}
+
+declare interface BotVars {
+    [variable: string]: any;
+}
+
+/**
+ * Defines an interface that represents the bot links a bot can have.
+ */
+declare interface BotLinks {
+    [tag: string]: Bot | Bot[];
+}
+
 /**
  * Defines the basic structure of a bot.
  */
@@ -2441,6 +2512,11 @@ export interface Bot {
      */
     id: string;
 
+    /**
+     * The link to this bot.
+     */
+    link: string;
+
     /**
      * The space the bot lives in.
      */
@@ -2456,6 +2532,16 @@ export interface Bot {
      */
     masks: BotTags;
 
+    /**
+     * The links that this bot has to other bots.
+     */
+    links: BotLinks;
+
+    /**
+     * THe variables that are stored in this bot.
+     */
+    vars: BotVars;
+
     /**
      * The raw tag values that the bot contains.
      * If you want to access the script code for a formula, use this.
@@ -2575,6 +2661,11 @@ declare interface BotsState {
     [id: string]: Bot;
 }
 
+declare type PartialBot = Partial<Bot>;
+
+declare interface PartialBotsState {
+    [id: string]: PartialBot;
+}
 
 /**
  * The possible bot spaces.
@@ -2934,6 +3025,34 @@ declare global {
      */
     function getJSON(data: any): string;
 
+    /**
+     * Gets nicely formatted JSON for the given data.
+     * @param data The data.
+     */
+    function getFormattedJSON(data: any): string;
+
+    /**
+     * Makes a snapshot of the given bot(s).
+     * Snapshots are like mods except they contain multiple bots and include the ID, space, tags, and tag masks of the bots.
+     * @param bots The bots to make a snapshot of.
+     */
+    function getSnapshot(bots: Bot | Bot[]): BotsState;
+
+    /**
+     * Calculates the difference between the two given snapshots.
+     * @param first The first snapshot.
+     * @param second The second snapshot.
+     */
+    function diffSnapshots(first: BotsState, second: BotsState): PartialBotsState;
+
+    /**
+     * Applies the given delta to the given snapshot and returns the result.
+     * This is essentially the opposite of diffSnapshots().
+     * @param snapshot The snapshot that the diff should be applied to.
+     * @param diff The delta that should be applied to the snapshot.
+     */
+    function applyDiffToSnapshot(snapshot: BotsState, diff: PartialBotsState): BotsState;
+
     /**
      * Shouts the given events in order until a bot returns a result.
      * Returns the result that was produced or undefined if no result was produced.
@@ -2942,6 +3061,26 @@ declare global {
      */
      function priorityShout(eventNames: string[], arg?: any): any;
 
+     /**
+     * Creates a tag value that can be used to link to the given bots.
+     * @param bots The bots that the link should point to.
+     */
+    function createBotLink(...bots: (Bot | string | (Bot | string)[])[]): string;
+
+    /**
+     * Gets the list of bot links that are stored in this bot's tags.
+     * @param bot The bot to get the links for.
+     */
+    function getBotLinks(bot: Bot): ParsedBotLink[];
+
+    /**
+     * Updates all the links in the given bot using the given ID map.
+     * Useful if you know that the links in the given bot are outdated and you know which IDs map to the new IDs.
+     * @param bot The bot to update.
+     * @param idMap The map of old IDs to new IDs that should be used.
+     */
+    function updateBotLinks(bot: Bot, idMap: Map<string, string | Bot> | { [id: string]: string | Bot }): void;
+
     /**
      * Asks every bot in the inst to run the given action.
      * In effect, this is like shouting to a bunch of people in a room.
@@ -2962,7 +3101,39 @@ declare global {
      * // Tell every bot say "Hi" to you.
      * shout("sayHi()", "My Name");
      */
-    function shout(name: string, arg?: any): any[];
+    const shout: {
+        /**
+         * Asks every bot in the inst to run the given action.
+         * In effect, this is like shouting to a bunch of people in a room.
+         *
+         * @param name The event name.
+         * @param arg The optional argument to include in the shout.
+         * @returns Returns a list which contains the values returned from each script that was run for the shout.
+         *
+         * @example
+         * // Tell every bot to reset themselves.
+         * shout("reset()");
+         *
+         * @example
+         * // Ask every bot for its name.
+         * const names = shout("getName()");
+         *
+         * @example
+         * // Tell every bot say "Hi" to you.
+         * shout("sayHi()", "My Name");
+         */
+        (name: string, arg?: any): any[],
+        [name: string]: {
+            /**
+             * Asks every bot in the inst to run the given action.
+             * In effect, this is like shouting to a bunch of people in a room.
+             *
+             * @param arg The optional argument to include in the shout.
+             * @returns Returns a list which contains the values returned from each script that was run for the shout.
+             */
+            (arg?: any): any[]
+        }
+    };
 
     /**
      * Asks the given bots to run the given action.
@@ -3658,14 +3829,62 @@ interface Debugger {
       * @param data The data.
       */
      getJSON(data: any): string;
- 
+
+     /**
+     * Gets nicely formatted JSON for the given data.
+     * @param data The data.
+     */
+    getFormattedJSON(data: any): string;
+
+    /**
+     * Makes a snapshot of the given bot(s).
+     * Snapshots are like mods except they contain multiple bots and include the ID, space, tags, and tag masks of the bots.
+     * @param bots The bots to make a snapshot of.
+     */
+    getSnapshot(bots: Bot | Bot[]): BotsState;
+
+    /**
+     * Calculates the difference between the two given snapshots.
+     * @param first The first snapshot.
+     * @param second The second snapshot.
+     */
+    diffSnapshots(first: BotsState, second: BotsState): PartialBotsState;
+
+    /**
+     * Applies the given delta to the given snapshot and returns the result.
+     * This is essentially the opposite of diffSnapshots().
+     * @param snapshot The snapshot that the diff should be applied to.
+     * @param diff The delta that should be applied to the snapshot.
+     */
+    applyDiffToSnapshot(snapshot: BotsState, diff: PartialBotsState): BotsState;
+
+     /**
+     * Creates a tag value that can be used to link to the given bots.
+     * @param bots The bots that the link should point to.
+     */
+    createBotLink(...bots: (Bot | string | (Bot | string)[])[]): string;
+
+    /**
+     * Gets the list of bot links that are stored in this bot's tags.
+     * @param bot The bot to get the links for.
+     */
+    getBotLinks(bot: Bot): ParsedBotLink[];
+
+     /**
+     * Updates all the links in the given bot using the given ID map.
+     * Useful if you know that the links in the given bot are outdated and you know which IDs map to the new IDs.
+     * @param bot The bot to update.
+     * @param idMap The map of old IDs to new IDs that should be used.
+     */
+    updateBotLinks(bot: Bot, idMap: Map<string, string | Bot> | { [id: string]: string | Bot }): void
+
      /**
       * Shouts the given events in order until a bot returns a result.
       * Returns the result that was produced or undefined if no result was produced.
       * @param eventNames The names of the events to shout.
       * @param arg The argument to shout.
       */
-      priorityShout(eventNames: string[], arg?: any): any;
+    priorityShout(eventNames: string[], arg?: any): any;
  
      /**
       * Asks every bot in the inst to run the given action.
@@ -4933,11 +5152,17 @@ interface Os {
       */
      getRecords: MaskFunc<(...filters: RecordFilters[]) => Promise<GetRecordsResult>>;
 
-     /**
-      * Requests that the given record be destroyed.
-      * @param record The record that should be deleted.
-      */
-     destroyRecord: MaskFunc<(record: DeletableRecord) => Promise<void>>;
+    /**
+     * Requests that the given record be destroyed.
+     * @param record The record that should be deleted.
+     */
+    destroyRecord: MaskFunc<(record: DeletableRecord) => Promise<void>>;
+
+    /**
+     * Converts the given geolocation to a what3words (https://what3words.com/) address.
+     * @param location The latitude and longitude that should be converted to a 3 word address.
+     */
+    convertGeolocationToWhat3Words(location: ConvertGeolocationToWhat3WordsOptions): Promise<string>;
 
      /**
       * Specifies that the given prefix should be interpreted as code.
@@ -4987,6 +5212,16 @@ interface Os {
       * @param options The options that should be used for the debugger.
       */
      createDebugger(options?: DebuggerOptions): Debugger;
+
+     /**
+      * Gets the debugger that this script is currently running in.
+      */
+     getExecutingDebugger(): Debugger;
+
+     /**
+      * The global variables that are stored in the OS.
+      */
+     vars: typeof globalThis;
 }
 
 interface Server {

package/runtime/AuxRuntime.d.ts

@@ -57,6 +57,7 @@ export declare class AuxRuntime implements RuntimeBotInterface, RuntimeBotFactor
      */
     private _autoBatch;
     private _forceSyncScripts;
+    private _currentDebugger;
     private _libraryFactory;
     get forceSignedScripts(): boolean;
     get context(): AuxGlobalContext;
@@ -94,6 +95,7 @@ export declare class AuxRuntime implements RuntimeBotInterface, RuntimeBotFactor
      * @param actions The actions to process.
      */
     process(actions: BotAction[]): void;
+    private _getExecutingDebugger;
     private _createDebugger;
     private _processCore;
     private _processAction;
@@ -153,6 +155,7 @@ export declare class AuxRuntime implements RuntimeBotInterface, RuntimeBotFactor
     updateTagMask(bot: CompiledBot, tag: string, spaces: string[], value: any): RealtimeEditMode;
     getTagMask(bot: CompiledBot, tag: string): RealtimeEditMode;
     getListener(bot: CompiledBot, tag: string): CompiledBotListener;
+    getTagLink(bot: CompiledBot, tag: string): RuntimeBot | RuntimeBot[];
     getSignature(bot: CompiledBot, signature: string): string;
     private _compileTagOrMask;
     private _compileTag;

package/runtime/AuxRuntime.js

@@ -5,7 +5,7 @@
 // 3. Channel - These are manager objects which handle the persistence and runtime aspects of an AUX.
 // 4. Partitions - These are services which manage the persistence and realtime sync of the AUX data model.
 // 5. Runtimes - These are services which manage script execution and formula precalculation.
-import { hasValue, tagsOnBot, isFormula, isScript, isNumber, BOT_SPACE_TAG, botUpdated, isBot, ORIGINAL_OBJECT, DEFAULT_ENERGY, getBotSpace, ON_ACTION_ACTION_NAME, breakIntoIndividualEvents, ON_BOT_ADDED_ACTION_NAME, ON_ANY_BOTS_ADDED_ACTION_NAME, ON_ANY_BOTS_REMOVED_ACTION_NAME, ON_BOT_CHANGED_ACTION_NAME, ON_ANY_BOTS_CHANGED_ACTION_NAME, updatedBot, TAG_MASK_SPACE_PRIORITIES, CLEAR_CHANGES_SYMBOL, DNA_TAG_PREFIX, isRuntimeBot, createBot, ON_ERROR, action, isBotInDimension, asyncResult, registerBuiltinPortal, defineGlobalBot, } from '../bots';
+import { hasValue, tagsOnBot, isFormula, isScript, isNumber, BOT_SPACE_TAG, botUpdated, isBot, ORIGINAL_OBJECT, DEFAULT_ENERGY, getBotSpace, ON_ACTION_ACTION_NAME, breakIntoIndividualEvents, ON_BOT_ADDED_ACTION_NAME, ON_ANY_BOTS_ADDED_ACTION_NAME, ON_ANY_BOTS_REMOVED_ACTION_NAME, ON_BOT_CHANGED_ACTION_NAME, ON_ANY_BOTS_CHANGED_ACTION_NAME, updatedBot, TAG_MASK_SPACE_PRIORITIES, CLEAR_CHANGES_SYMBOL, DNA_TAG_PREFIX, isRuntimeBot, createBot, ON_ERROR, action, isBotInDimension, asyncResult, registerBuiltinPortal, defineGlobalBot, isBotLink, parseBotLink, } from '../bots';
 import { Subject, Subscription } from 'rxjs';
 import { AuxCompiler } from './AuxCompiler';
 import { addToContext, MemoryGlobalContext, removeFromContext, isInContext, } from './AuxGlobalContext';
@@ -16,7 +16,7 @@ import { convertToCopiableValue, DeepObjectError, formatAuthToken, } from './Uti
 import { DefaultRealtimeEditModeProvider, } from './AuxRealtimeEditModeProvider';
 import { sortBy, forOwn, merge, union } from 'lodash';
 import { tagValueHash } from '../aux-format-2/AuxOpTypes';
-import { applyEdit, isTagEdit, mergeVersions } from '../aux-format-2';
+import { applyTagEdit, isTagEdit, mergeVersions } from '../aux-format-2';
 import { replaceMacros } from './Transpiler';
 /**
  * Defines an class that is able to manage the runtime state of an AUX.
@@ -65,6 +65,7 @@ export class AuxRuntime {
          */
         this._autoBatch = true;
         this._forceSyncScripts = false;
+        this._currentDebugger = null;
         this._libraryFactory = libraryFactory;
         this._globalContext = new MemoryGlobalContext(version, device, this, this);
         this._forceSyncScripts = forceSyncScripts;
@@ -73,6 +74,7 @@ export class AuxRuntime {
             api: {
                 os: {
                     createDebugger: this._createDebugger.bind(this),
+                    getExecutingDebugger: this._getExecutingDebugger.bind(this),
                 },
             },
         });
@@ -196,6 +198,9 @@ export class AuxRuntime {
         this._processCore(actions);
         this._processBatch();
     }
+    _getExecutingDebugger() {
+        return this._currentDebugger;
+    }
     _createDebugger(options) {
         const runtime = new AuxRuntime(this._globalContext.version, this._globalContext.device, this._libraryFactory, this._editModeProvider, this._forceSignedScripts, this._exemptSpaces, !(options === null || options === void 0 ? void 0 : options.allowAsynchronousScripts));
         runtime._autoBatch = false;
@@ -237,7 +242,7 @@ export class AuxRuntime {
         runtime.context.createBot(createBot(configBotId, configBotTags, 'tempLocal'));
         runtime.process(this._builtinPortalBots.map((b) => registerBuiltinPortal(b)));
         runtime.userId = configBotId;
-        return Object.assign(Object.assign({}, runtime._library.api), { getAllActions, getCommonActions: () => {
+        const debug = Object.assign(Object.assign({}, runtime._library.api), { getAllActions, getCommonActions: () => {
                 return getAllActions().filter(isCommonAction);
             }, getBotActions: () => {
                 return getAllActions().filter((a) => !isCommonAction(a));
@@ -246,6 +251,8 @@ export class AuxRuntime {
                 allErrors.push(...errors);
                 return allErrors;
             }, create });
+        runtime._currentDebugger = debug;
+        return debug;
     }
     _processCore(actions) {
         for (let action of actions) {
@@ -581,9 +588,11 @@ export class AuxRuntime {
                 }
                 if (!hasChange && removedBots && removedBots.length > 0) {
                     for (let bot of removedBots) {
-                        if (isBotInDimension(null, bot, dimension)) {
-                            hasChange = true;
-                            break;
+                        if (bot) {
+                            if (isBotInDimension(null, bot, dimension)) {
+                                hasChange = true;
+                                break;
+                            }
                         }
                     }
                 }
@@ -710,7 +719,7 @@ export class AuxRuntime {
                     const tagValue = u.tags[tag];
                     if (hasValue(tagValue) || tagValue === null) {
                         if (isTagEdit(tagValue)) {
-                            compiled.tags[tag] = applyEdit(compiled.tags[tag], tagValue);
+                            compiled.tags[tag] = applyTagEdit(compiled.tags[tag], tagValue);
                         }
                         else {
                             compiled.tags[tag] = tagValue;
@@ -742,7 +751,7 @@ export class AuxRuntime {
                                 delete compiled.masks[space][tag];
                             }
                             else if (isTagEdit(tagValue)) {
-                                compiled.masks[space][tag] = applyEdit(compiled.masks[space][tag], tagValue);
+                                compiled.masks[space][tag] = applyTagEdit(compiled.masks[space][tag], tagValue);
                             }
                             else {
                                 compiled.masks[space][tag] = tagValue;
@@ -1078,6 +1087,18 @@ export class AuxRuntime {
         this.getValue(bot, tag);
         return bot.listeners[tag] || null;
     }
+    getTagLink(bot, tag) {
+        const tagValue = bot.values[tag];
+        if (isBotLink(tagValue)) {
+            const links = parseBotLink(tagValue);
+            const bots = links.map((link) => this.context.state[link] || null);
+            if (bots.length === 1) {
+                return bots[0];
+            }
+            return bots;
+        }
+        return undefined;
+    }
     getSignature(bot, signature) {
         return !!bot.signatures ? bot.signatures[signature] : undefined;
     }
@@ -1130,7 +1151,7 @@ export class AuxRuntime {
             }
         }
         if (isTagEdit(tagValue)) {
-            tagValue = bot.tags[tag] = applyEdit(bot.tags[tag], tagValue);
+            tagValue = bot.tags[tag] = applyTagEdit(bot.tags[tag], tagValue);
         }
         else {
             if (hasValue(tagValue)) {
@@ -1233,7 +1254,7 @@ export class AuxRuntime {
                 throw data;
             },
             constants: Object.assign(Object.assign({}, this._library.api), { tagName: tag, globalThis: this._globalObject }),
-            variables: Object.assign(Object.assign({}, this._library.tagSpecificApi), { this: (ctx) => (ctx.bot ? ctx.bot.script : null), thisBot: (ctx) => (ctx.bot ? ctx.bot.script : null), bot: (ctx) => (ctx.bot ? ctx.bot.script : null), tags: (ctx) => (ctx.bot ? ctx.bot.script.tags : null), raw: (ctx) => (ctx.bot ? ctx.bot.script.raw : null), masks: (ctx) => (ctx.bot ? ctx.bot.script.masks : null), creatorBot: (ctx) => ctx.creator, configBot: () => this.context.playerBot }),
+            variables: Object.assign(Object.assign({}, this._library.tagSpecificApi), { this: (ctx) => (ctx.bot ? ctx.bot.script : null), thisBot: (ctx) => (ctx.bot ? ctx.bot.script : null), bot: (ctx) => (ctx.bot ? ctx.bot.script : null), tags: (ctx) => (ctx.bot ? ctx.bot.script.tags : null), raw: (ctx) => (ctx.bot ? ctx.bot.script.raw : null), masks: (ctx) => (ctx.bot ? ctx.bot.script.masks : null), creatorBot: (ctx) => ctx.creator, configBot: () => this.context.playerBot, links: (ctx) => (ctx.bot ? ctx.bot.script.links : null) }),
             arguments: [['that', 'data']],
         });
         if (hasValue(bot)) {