Skip to content

Latest commit

 

History

History
49 lines (43 loc) · 10.1 KB

engine-api.md

File metadata and controls

49 lines (43 loc) · 10.1 KB
Raw

BrightScript Engine API

The engine worker library has a programable interface to make it easy to integrate into any web based application.

Check the documentation to learn how to start using it. The only pre-requisites are to expose, on the default document, a canvas object named display and a video object named player, and optionally, if you want to show the performance statistics, you also need to expose a div object named stats.

Methods

Method Description Parameters / Details
initialize(customDeviceInfo?, options?) Initializes the engine simulated device
  • customDeviceInfo? (object): customized device information, see /src/worker/common.ts for valid properties.
  • options? (object): init options, valid properties are:
    - showStats(boolean): if true the performance statistics overlay will be shown over the display when the app is running, default is false.
    - disableDebug(boolean): if true prevents any debug command/data to be sent or received by the engine, for production to avoid code injection, default is false.
    - debugToConsole(boolean): if false prevents messages to be sent to the console, you still can debug messages via debug event, default is true.
    - disableKeys(boolean): if the engine is running on a device with no keyboard, or you don't need keyboard control, set this option to true to disable keyboard control, default is false
    - customKeys(Map): a custom map of keyboard keys to add/remove from the remote control simulation, see /src/api/control.ts for the default mappings.
    - disableGamePads(boolean): Set this option to true if you want to disable the game pad control support, default is false
    - customPadButtons(Map): a custom map of GamePad buttons (0-31) to add/remove from the remote control simulation, see /src/api/control.ts for the default mappings.
subscribe(observerId, observerCallback) Subscribes to the engine events (see list below)
  • observerId (string): identifier of the subscriber process.
  • observerCallback (function): callback function to receive the events from the engine.
unsubscribe(observerId) Unsubscribes to the engine events
  • observerId (string): identifier of the subscriber process.
execute(filePath, fileData, options?) Loads and run an app package (.zip/.bpk), a source code file (.brs) or plain text BrightScript code
  • filePath (string): path of the loaded file, make sure extension is .zip or .bpk if loading a full app.
  • fileData (ArrayBuffer/Blob/string): contents of the file or just a string with BrightScript code.
  • options? (object): execution options, valid properties are:
    - clearDisplayOnExit (boolean): if false the display will keep the last image when app ends, default is true.
    - muteSound (boolean): if true the engine will mute all audio but events are still raised, default is false.
    - execSource (string): the execution source to be sent on the input params (see Roku docs).
    - debugOnCrash (boolean): if true stops on the Micro Debugger when a crash happens, default is false.
    - password (string): the password to decrypt a .bpk, or encrypt a .zip package, default is "".
terminate(reason) Terminates the current app/source code execution
  • reason (string): the reason for the termination to be shown on debug.
redraw(fullScreen, width?, height?, dpr?) Requests a display redraw (always keeps the aspect ratio based on display mode)
  • fullScreen (boolean): Flag to inform if the full screen mode is activated.
  • width? (number): width of the canvas, if not passed uses window.innerWidth.
  • height? (number): height of the canvas, if not passed uses window.innerHeight.
  • dpr? (number): device pixel ratio, if not passed uses window.devicePixelRatio.
setDisplayMode(mode) Configures the display mode (if an app is running will reset the simulated device)
  • mode (string): supported modes are "480p" (SD), "720p" (HD) or "1080p"(FHD).
getDisplayMode() Returns the current display mode.
setOverscanMode(mode) Configures the overscan mode.
  • mode (string): supported modes are "disabled", "guidelines" or "overscan".
getOverscanMode() Returns the current overscan mode.
enableStats(state) Enables or disables the performance stats overlay
  • state (boolean): if true performance statistics will be shown over the display, on the top left.
setAudioMute(mute) Mutes or un-mutes the audio during app execution
  • mute (boolean): if true the executing app audio and video will be muted.
getAudioMute() Returns true if the audio is muted
getSerialNumber() Returns the device serial number, this value changes when the deviceData.deviceModel is updated.
setControlMode(controls) Enable/Disable the remote control simulation controls (object) contains following properties:
  • keyboard (boolean): if true enables the keyboard control.
  • gamePads (boolean): if true enables game pad control.
getControlMode() Returns an object with the control mode flags Same options sent to the setControlMode above.
setCustomKeys(keysMap) Sends a custom map of keyboard keys to add/remove from the remote control simulation
setCustomPadButtons(buttonsMap) Sends a custom map of game pad buttons to add/remove from the remote control simulation
sendKeyDown(key, remote?, index?) Sends a remote control key down event to the engine
  • key (string): one of valid key codes (see Roku doc).
  • remote (number): one of valid remote types (see /src/api/common.ts) default is ECP.
  • index (number): The index of the remote control, default is 0.
sendKeyUp(key, remote?, index?) Sends a remote control key up event to the engine
  • key (string): one of valid key codes (see Roku doc).
  • remote (number): one of valid remote types (see /src/api/common.ts) default is ECP.
  • index (number): The index of the remote control, default is 0.
sendKeyPress(key, delay?, remote?, index?) Sends a remote control key press event to the engine
  • key (string): one of valid key codes (see Roku doc).
  • delay (number): the delay (in milliseconds) between sending Key Up and Key Down (default is 300ms).
  • remote (number): one of valid remote types (see /src/api/common.ts) default is ECP.
  • index (number): The index of the remote control, default is 0.
debug(command) Sends a debug command to the Engine
  • command (string): the Micro Debugger can be enabled sending break command, and after that, any valid BrightScript expression or debug commands can be sent. You can also send pause to interrupt the interpreter, for instance, when the app loses focus. The command cont restarts the app. You can use this method on the browser console to debug your app.
getVersion() Returns the version of the API library

Events

Event Description Data Type
loaded Triggered when the source code data has finished loading object: {id: string, file: string, title: string, subtitle: string, version: string, running: boolean}
icon Triggered when the zip file is loaded and manifest links to a valid icon for the app base64: A base64 string of the app icon, extracted from the zip file.
registry Triggered when the app updates the registry Map: the registry with all recent recent updates.
started Triggered when the engine started running the source code object: {id: string, file: string, title: string, subtitle: string, version: string, running: boolean}
closed Triggered when the engine terminated the execution of the source code string: the exit reason based on Roku documentation
reset Triggered when the RebootSystem() function is executed from the engine null: Nothing is returned as data
control Triggered when a control key is sent to the engine object: {key: string, mod: number}. The property key contains an ECP key code and mod contains 0 for keydown or 100 for keyup
redraw Triggered when the display canvas is redrawn/resized boolean: If true the display canvas is in full screen mode
resolution Triggered when the emulated screen resolution changes (controlled via BrightScript) object: {width: integer, height: integer}
debug Triggered when debug messages arrive from the worker library (BrightScript Interpreter) object: {level: string, content: string}, levels are: print, beacon, warning, error, stop, pause, continue
error Triggered when the any execution exception happens on the API library string: The message describing the error