Brs-engine NPM

BrightScript Simulation Engine

An intepreter for the BrightScript language that runs Roku apps on browser platforms and Node.js.

GitHub

The Project

The BrightScript Simulation Engine implements an interpreter for the BrightScript language, that can be embedded in Web, Electron and Node.js applications, allowing Roku apps to be executed in several different non-Roku platforms.

Initially the focus was on the Draw 2D API components (roScreen, roCompositor, roRegion, etc.) along with the core elements of the BrightScript language, allowing a full Roku app execution over an HTML5 Canvas, but it was extended to include simulation of the Roku file system, registry, remote control and the Micro Debugger.

This repository was originally a fork from brs, a BrightScript command line interpreter.

Important Notes:

At this stage, apps based on SceneGraph are not yet supported, but this feature is in the backlog to be implemented. Please check the Current Limitations document for further details on what else is still missing and what is out of scope.
Although brs-engine runs channels with user interface, it has no intention of emulating the full Roku OS or hardware devices, it is primarily aimed as a development tool for the Roku Community, and also to be used as a framework for running the BrighScript language in other platforms.

Technology and Compatibility

The brs-engine is developed in TypeScript and bundled as the following collection of Webpack JavaScript libraries:

Library File	Description
`app/lib/brs.api.js`	Provides the Engine API to be imported and used by the Web applications hosting the Simulator.
`app/lib/brs.worker.js`	A Web Worker library that runs the language parser and interpreter in a background thread on the browser platform.
`bin/brs.cli.js`	Executable CLI application that can be used from the terminal: - As a language shell - REPL (read-eval-print loop)- Executing `brs`, `zip` or `bpk` files- Packaging `zip` files into encrypted `bpk` packages.
`bin/brs.node.js`	A NodeJS library, similar to `brs.worker.js` that exposes the language parser and interpreter to be used by Node.js applications, the engine CLI and automated tests.
`bin/brs.ecp.js`	A NodeJS Worker library, used by the CLI to launch the ECP and SSDP services.

The Web Worker library require features like SharedArrayBuffer and OffScreenCanvas, that are relatively recent in the browser engines, because of that, it can only be executed on recent versions of:

Chromium/Chrome version 69 or newer.
Chrome Android version 89 or newer.
Edge, version 79 or newer.
Opera, version 56 or newer.
Firefox, version 105 or newer.
Safari macOS/iOS/ipadOS, version 16.4 or newer.
Electron, version 4.0 or newer.

Note: The engine libraries are client-side only, nothing needs to be sent or processed in the server side.

How to Use the Simulator

Web Applications

This repository provides a sample web application you can build and run (learn how), but if you just want to use the simulation engine, not installing or downloading anything, try one of the web applications below:

BrightScript TV - Run full Roku games and apps in your browser: https://lvcabral.com/brs
brsFiddle - BrightScript playground to test and share code with others: http://brsFiddle.net
- Hello World - Shared Link
- Bouncing Square - Shared Link
- Calculate Easter Day - Shared Link
- Download Image and Music - Shared Link
- Video Playback - Shared Link
- API Call Example - Shared Link

Desktop Application

The simulator is also available as a multi-platform desktop application (Windows, Linux & macOS) that uses the package published by this project. The application introduces several aditional Roku features, such as the ECP (External Control Protocol) and Remote Console servers to allow integration with tools like Telnet or VSCode BrightScript Extension. You can also change the device configurations such as screen resolution, keyboard control customization, localization, among others. Download the installers and find more information in the links below: