Debugger

• Debugger

  Defines an interface that represents a debugger.

  Members

  • Extra Functions

    The extra functions that are available on this type.

    Details

    See the following functions for more information:

    • changeState(bot, stateName, groupName)
    • create(...mods)
    • destroy(bot)
    • priorityShout(eventNames, arg)
    • shout(name, arg)
    • updateBotLinks(bot, idMap)
    • whisper(bot, eventName, arg)
    • applyDiffToSnapshot(snapshot, diff)
    • applyMod(bot, ...mods)
    • assert(condition, message)
    • assertEqual(first, second)
    • atPosition(dimension, x, y)
    • byCreator(bot)
    • byID(id)
    • byMod(mod)
    • bySpace(space)
    • byTag(tag, filter)
    • clearAnimations(bot, tag)
    • clearTagMasks(bot, space)
    • deleteTagMaskText(bot, tag, index, count, space)
    • deleteTagText(bot, tag, index, count)
    • diffSnapshots(first, second)
    • either(...filters)
    • getBotLinks(bot)
    • getBotPosition(bot, dimension)
    • getBotRotation(bot, dimension)
    • getBotTagValues(tag, filter)
    • getFormattedJSON(data)
    • getID(bot)
    • getJSON(data)
    • getLink(...bots)
    • getMod(bot, ...tags)
    • getSnapshot(bots)
    • getTag(bot, ...tags)
    • inDimension(dimension)
    • inStack(bot, dimension)
    • insertTagMaskText(bot, tag, index, text, space)
    • insertTagText(bot, tag, index, text)
    • neighboring(bot, dimension, direction)
    • not(filter)
    • remote(action, selector, allowBatching)
    • sendRemoteData(remoteId, name, arg)
    • removeTags(bot, tagSection)
    • renameTag(bot, originalTag, newTag)
    • sendRemoteData(remoteId, name, arg)
    • setTag(bot, tag, value)
    • setTagMask(bot, tag, value, space)
    • subtractMods(bot, ...mods)
    • superShout(eventName, arg)
    • uuid()

  • action ActionActions

    The action-related actions that are available in this debugger.

    Details

    See the following functions for more information:

    • action.perform(action)
    • action.reject(action)

  • os OSActions

    The OS actions that are available in this debugger.

    Details

    See the following functions for more information:

    • os.beginAudioRecording(options)
    • os.endAudioRecording()
    • os.attachDebugger(debug, options)
    • os.createDebugger(options)
    • os.createDebugger(options)
    • os.focusOn(bot, options)
    • os.focusOn(position, options)
    • os.getExecutingDebugger()
    • os.showInput(currentValue, options)
    • os.addBotDropGrid(bot, ...targets)
    • os.addBotDropSnap(bot, ...targets)
    • os.addDropGrid(...targets)
    • os.addDropSnap(...targets)
    • os.applyUpdatesToInst(updates)
    • os.arSupported()
    • os.beginAudioRecording(options)
    • os.bufferFormAddressGLTF(address)
    • os.bufferSound(url)
    • os.calculateRayFromCamera(portal, viewportCoordinates)
    • os.calculateScreenCoordinatesFromViewportCoordinates(portal, coordinates)
    • os.calculateViewportCoordinatesFromPosition(portal, position)
    • os.calculateViewportCoordinatesFromScreenCoordinates(portal, coordinates)
    • os.cancelSound(soundId)
    • os.capturePhoto(options)
    • os.capturePortalScreenshot()
    • os.classifyImages(options)
    • os.closeBarcodeScanner()
    • os.closeCircleWipe(options)
    • os.closeImageClassifier()
    • os.closePhotoCamera()
    • os.closeQRCodeScanner()
    • os.compileApp(appId, content)
    • os.convertGeolocationToWhat3Words(location)
    • os.countEvents(recordNameOrKey, eventName, endpoint)
    • os.createInitializationUpdate(bots)
    • os.device()
    • os.disableAR()
    • os.disablePointOfView()
    • os.disableVR()
    • os.disableWakeLock()
    • os.download(data, filename, mimeType)
    • os.downloadBots(bots, filename)
    • os.downloadBotsAsInitialzationUpdate(bots, filename)
    • os.downloadInst()
    • os.downloadInst()
    • os.enableAR(options)
    • os.enableCollaboration()
    • os.enableCustomDragging()
    • os.enablePointOfView(center, imu)
    • os.enableVR(options)
    • os.endAudioRecording()
    • os.eraseData(recordKeyOrName, address, endpoint)
    • os.eraseFile(recordKeyOrName, result, endpoint)
    • os.eraseFile(recordKeyOrName, url, endpoint)
    • os.eraseManualApprovalData(recordKeyOrName, address, endpoint)
    • os.eraseNotification(recordName, address, options)
    • os.eraseWebhook(recordName, address, options)
    • os.exitFullscreenMode()
    • os.getAverageFrameRate()
    • os.getCameraPosition(portal)
    • os.getCameraRotation(portal)
    • os.getCurrentDimension()
    • os.getCurrentInst()
    • os.getCurrentInstRecord()
    • os.getCurrentInstUpdate()
    • os.getCurrentInst()
    • os.getData(recordKeyOrName, address, endpoint)
    • os.getDimensionalDepth(dimension)
    • os.getFile(result, endpoint)
    • os.getFile(url, endpoint)
    • os.getFocusPoint(portal)
    • os.getGeolocation()
    • os.getInputList()
    • os.getInputState(controller, button)
    • os.getInstStateFromUpdates(updates)
    • os.getManualApprovalData(recordKeyOrName, address, endpoint)
    • os.getMediaPermission(options)
    • os.getMenuDimension()
    • os.getMiniPortalDimension()
    • os.getWebhook(recordName, address, options)
    • os.getPointerDirection(pointer)
    • os.getPointerPosition(pointer)
    • os.getPointerRotation(pointer)
    • os.getPortalDimension(portal)
    • os.getPrivateFile(result, endpoint)
    • os.getPrivateFile(url, endpoint)
    • os.getPublicFile(result)
    • os.getPublicFile(url)
    • os.getPublicRecordKey(name)
    • os.getRecordsEndpoint()
    • os.getRoomOptions(roomName)
    • os.getRoomRemoteOptions(roomName, remoteId)
    • os.getRoomTrackOptions(roomName, address)
    • os.getSubjectlessPublicRecordKey(name)
    • os.getWakeLockConfiguration()
    • os.getWebhook(recordName, address, options)
    • os.goToDimension(dimension)
    • os.goToURL(url)
    • os.grantInstAdminPermission(recordName, options)
    • os.grantInstRole(recordName, role, inst, expireTimeMs, options)
    • os.grantPermission(recordName, permission, options)
    • os.grantUserRole(recordName, role, userId, expireTimeMs, options)
    • os.hasBotInMiniPortal(bots)
    • os.hideBarcode()
    • os.hideChat()
    • os.hideHtml()
    • os.hideQRCode()
    • os.hideTips(tipIds)
    • os.importAUX(urlOrJSON)
    • os.inSheet()
    • os.isCollaborative()
    • os.isInDimension(dimension)
    • os.isRecordKey(key)
    • os.joinRoom(roomName, options)
    • os.ldrawCountTextBuildSteps(address)
    • os.ldrawCountTextBuildSteps(text)
    • os.leaveRoom(roomName, options)
    • os.listBuiltinTags()
    • os.listData(recordKeyOrName, startingAddress, endpoint)
    • os.listDataByMarker(recordKeyOrName, marker, startingAddress, options)
    • os.listFormAnimations(botOrAddress)
    • os.listInstUpdates()
    • os.listNotificationSubscriptions(recordName, address, options)
    • os.listNotifications(recordName, startingAddress, options)
    • os.listNotificationsByMarker(recordName, marker, startingAddress, options)
    • os.listUserNotificationSubscriptions(options)
    • os.listUserStudios(endpoint)
    • os.listWebhooks(recordName, startingAddress, options)
    • os.listWebhooksByMarker(recordName, marker, startingAddress, options)
    • os.loadInst(id)
    • os.loadInst(id)
    • os.log(...args)
    • os.meetCommand(command, ...args)
    • os.meetFunction(functionName, ...args)
    • os.mergeInstUpdates(updates)
    • os.openBarcodeScanner(camera)
    • os.openCircleWipe(options)
    • os.openDevConsole()
    • os.openImageClassifier(options)
    • os.openPhotoCamera(options)
    • os.openQRCodeScanner(camera)
    • os.openURL(url)
    • os.parseBotsFromData(jsonOrPdf)
    • os.playSound(url)
    • os.raycast(portal, origin, direction)
    • os.raycastFromCamera(portal, viewportCoordinates)
    • os.recordData(recordKeyOrRecordName, address, data, endpointOrOptions)
    • os.recordEvent(recordKeyOrName, eventName, endpoint)
    • os.recordFile(recordKeyOrName, data, options, endpoint)
    • os.recordManualApprovalData(recordKeyOrRecordName, address, data, endpointOrOptions)
    • os.recordNotification(recordName, notification, options)
    • os.recordWebhook(recordName, webhook, options)
    • os.registerApp(portalId, bot)
    • os.registerTagPrefix(prefix, options)
    • os.remoteCount(inst)
    • os.remotes()
    • os.replaceDragBot(bot)
    • os.reportInst()
    • os.requestAuthBot()
    • os.requestAuthBotInBackground()
    • os.requestFullscreenMode()
    • os.requestWakeLock()
    • os.revokeInstRole(recordName, role, inst, options)
    • os.revokePermission(recordName, permissionId, options)
    • os.revokeUserRole(recordName, role, userId, options)
    • os.run(script)
    • os.runWebhook(recordName, address, input, options)
    • os.sendNotification(recordName, address, payload, options)
    • os.setClipboard(text)
    • os.setRoomOptions(roomName, options)
    • os.setRoomTrackOptions(roomName, address, options)
    • os.share(options)
    • os.showAccountInfo()
    • os.showBarcode(code, format)
    • os.showConfirm(options)
    • os.showHtml(html)
    • os.showInputForTag(bot, tag, options)
    • os.showJoinCode(inst, dimension)
    • os.showQRCode(code)
    • os.showUploadAuxFile()
    • os.showUploadFiles()
    • os.sleep(time)
    • os.startFormAnimation(botOrBots, nameOrIndex, options)
    • os.stopFormAnimation(botOrBots, options)
    • os.subscribeToNotification(recordName, address, options)
    • os.tip(message, pixelX, pixelY, duration)
    • os.toast(message, duration)
    • os.totalRemoteCount()
    • os.unloadInst(id)
    • os.unloadInst(id)
    • os.unregisterApp(appId)
    • os.unsubscribeFromNotification(subscriptionId, options)
    • os.version()
    • os.vrSupported()
    • os.agreedUponTime
    • os.deadReckoningTime
    • os.instLatency
    • os.instTimeOffset
    • os.instTimeOffsetSpread
    • os.localTime
    • os.registerTagPrefix(prefix, options)
    • os.remotes()
    • os.remotes()
    • os.remoteCount(inst)
    • os.remoteCount(inst)
    • os.totalRemoteCount()
    • os.totalRemoteCount()
    • os.sleep(time)

  • web WebActions

    The web actions that are available in this debugger.

    Details

    See the following functions for more information:

    • web.get(url, options)
    • web.hook(options)
    • web.post(url, data, options)

  • getAllActions(): BotAction[]

    Gets the list of action objects that have been performed by bots in the current debugger. Action objects are used by CasualOS to represent changes to bots or external effects that should be performed. Examples of this are create(...mods), os.toast(message, duration) and os.enableVR(options).

    Examples

    Get the list of bot changes and actions that have been performed in a debugger

    const debug = await os.createDebugger();
    debug.create({
        test: '@os.toast("Hello")'
    });
    debug.shout("test");
    
    const actions = debug.getAllActions();
    
    assertEqual(actions, [
        {
            type: 'add_bot',
            id: 'uuid-1',
            bot: {
                id: 'uuid-1',
                tags: {
                    test: '@os.toast("Hello")'
                }
            }
        },
        {
            type: 'show_toast',
            message: 'Hello',
            duration: 2000
        }
    ]);

  • getBotActions(): BotAction[]

    Gets the list of bot actions that have been performed by bots in the current debugger. Action objects are used by CasualOS to represent changes to bots or external effects that should be performed. Bot actions are actions that immediately change bots or bot tags or masks.

    Examples of bot actions are create(...mods), destroy(bot) or setTagMask(bot, tag, value, space).

    Examples

    Get the list of bot changes that have been performed in a debugger

    const debug = await os.createDebugger();
    debug.create({
        test: '@os.toast("Hello")'
    });
    debug.shout("test");
    
    const actions = debug.getBotActions();
    
    assertEqual(actions, [
        {
            type: 'add_bot',
            id: 'uuid-1',
            bot: {
                id: 'uuid-1',
                tags: {
                    test: '@os.toast("Hello")'
                }
            }
        },
    ]);

  • getCommonActions(): BotAction[]

    Gets the list of common action objects that have been performed by bots in the current debugger. Action objects are used by CasualOS to represent changes to bots or external effects that should be performed. Common actions are actions that do not immediately change bots or bot tags or masks.

    Examples of common actions are os.toast(message, duration) and os.enableVR(options).

    Examples

    Get the list of actions that have been performed in a debugger

    const debug = await os.createDebugger();
    debug.create({
        test: '@os.toast("Hello")'
    });
    debug.shout("test");
    
    const actions = debug.getCommonActions();
    
    assertEqual(actions, [
        {
            type: 'show_toast',
            message: 'Hello',
            duration: 2000
        }
    ]);

  • getErrors(): any[]

    Gets the list of errors that have occurred in the current debugger. Errors occur when an exceptional event happens in a script and prevents the rest of the script from executing.

    Debuggers capture these errors and let you inspect them afterwards.

    Examples

    Get the list of errors that have happened in a debugger

    const debug = await os.createDebugger();
    debug.create({
        test: '@throw new Error("My Error")'
    });
    debug.shout("test");
    
    const errors = debug.getErrors();
    
    assertEqual(errors.length, 1);
    assertEqual(errors[0].error, new Error("My Error"));
    assertEqual(errors[0].tag, "test");

  • getPortalBots(): Map<string, Bot>

    Gets the list of portal bots in the debugger.

  • onAfterAction(handler: (action: BotAction) => void): void

    Registers the given handler to be called after a bot action is executed in this debugger.

    The first parameter is a (action: BotAction) => void and is the handler that should be called.

  • onAfterScriptUpdatedTag(listener: (update: DebuggerTagUpdate) => void): void

    Registers the given handler function to be called after any tag is updated in the debugger.

    The first parameter is a (update: DebuggerTagUpdate) => void and is the function that should be called when a tag is updated.

    Examples

    Listen for tag updates in a debugger

    const debug = await os.createDebugger({
        pausable: true
    });
    
    // Register a listener that gets called whenever a tag is updated.
    debug.onAfterScriptUpdatedTag(update => {
        console.log('tag updated', update);
    });
    
    // Because the debugger is pausable, the create() function returns a promise
    // because it calls

  • onAfterScriptUpdatedTagMask(listener: (update: DebuggerTagMaskUpdate) => void): void

    Registers the given handler function to be called after any tag mask is updated in the debugger.

    The first parameter is a (update: DebuggerTagMaskUpdate) => void and is the function that should be called when a tag mask is updated.

    Examples

    Listen for tag mask updates in a debugger

    const debug = await os.createDebugger({
        pausable: true
    });
    
    // Register a listener that gets called whenever a tag mask is updated.
    debug.onAfterScriptUpdatedTagMask(update => {
        console.log('tag mask updated', update);
    });
    
    // Because the debugger is pausable, the create() function returns a promise
    // because it calls

  • onBeforeAction(handler: (action: BotAction) => void): void

    Registers the given handler to be called before a bot action is executed in this debugger.

    The first parameter is a (action: BotAction) => void and is the handler that should be called.

  • onBeforeUserAction(listener: (action: BotAction) => void): void

    Registers the given handler function to be called before a user action is performed in the debugger.

    User actions are like normal actions, except they are generated by the CasualOS frontend. Generally, this only happens for built-in shouts and whispers. Additionally, these actions can only be automatically created for debuggers that are attached using os.attachDebugger(debug, options).

    The first parameter is a (action: BotAction) => void and is the function that should be called before a user action is performed.

    Examples

    Listen for tag updates in a debugger

    const debug = await os.createDebugger({
        pausable: true
    });
    
    // Register a listener that gets called whenever a user action is about to be performed.
    debug.onBeforeUserAction(update => {
        console.log('user action', update);
    });
    
    // Because the debugger is pausable, the create() function returns a promise
    // because it calls

  • onScriptActionEnqueued(listener: (action: BotAction) => void): void

    Registers the given handler function to be called by the debugger whenever a script enqueues an action. This occurrs for common actions like os.toast(message, duration) and os.showInput(currentValue, options).

    Every action that is enqueued ends up being performed.

    The first parameter is a (action: BotAction) => void and is the function that should be called whenever an action is scheduled to be performed.

    Examples

    Listen for actions to be enqueued in a debugger

    const debug = await os.createDebugger({
        pausable: true
    });
    
    // Register a listener that gets called whenever an action is scheduled to be performed.
    debug.onScriptActionEnqueued(action => {
        console.log('action enqueued', action);
    });
    
    // Because the debugger is pausable, the create() function returns a promise
    // because it calls

  • performUserAction(...actions: BotAction[]): Promise<any[][]>

    Performs the given actions in order as if they were user actions.

    This function works similarly to action.perform(action) except that actions performed with it will also call handlers registered with debug.onBeforeUserAction.

    Each parameter is a BotAction and are the actions that should be performed.