be

brs-emu

BrightScript 2D API Emulator - Runs on Chromium based browsers and Electron applications.

Showing:

Popularity

Downloads/wk

1

GitHub Stars

30

Maintenance

Last Commit

3mos ago

Contributors

29

Package

Dependencies

17

License

MIT

Type Definitions

Built-In

Tree-Shakeable

No?

Categories

Readme

BRS-EMU: BrightScript 2D API Emulator

An emulator for the Roku BrightScript language that runs on Chromium based browsers and Electron applications.

NPM Version

The Library

This library extends brs, a command line interpreter for BrightScript language, by implementing the Draw 2D API components (roScreen, roCompositor, roRegion, etc.) and several other BrightScript components allowing a full channel execution over an HTML5 Canvas, including emulation of the Roku remote control.

Note: Although brs-emu runs channels with user interface, it has no intention of emulating the full Roku OS user interface, see Current Limitations page for full details on what is out of scope.

Emulator Web and Desktop

Technology and Compatibility

This emulator is bundled as a Webpack Javascript library that runs as a Web Worker, and it uses features like SharedArrayBuffer and OffScreenCanvas, that are bleeding edge in the browser engines implementation, because of that, at this moment, it can only be executed in Chromium based browsers, like Chrome, Brave, Opera, Edge or embedded on an Electron application.

The BrightScript 2D API Emulator is a full client-side library, nothing is sent or processed in the server side. In addition to the included sample web application, every release also includes a multi-platform desktop application (Windows, Linux & macOS) that uses the same library generated by this project.

The desktop app, introduces several aditional features, such as the full screen support, ECP (External Control Protocol) and Remote Console servers to allow integration with 3rd party development tools like the VSCode BrightScript Extension. The Electron app source code and documentation is available in another repository, located at https://github.com/lvcabral/brs-emu-app.

Usage

If you just want to try the emulator, not installing or downloading anything, then simply try the demo website at: https://lvcabral.com/brs

Installation

The brs-emu project is published as a node package, so use npm:

$ npm install brs-emu

or yarn if that's your preference:

$ yarn add brs-emu

Integrating to your Code

The full documentation for integrating the library to an application is not available yet, please take a look at the file app/index.js for reference on how to use it. Below a simple code using the library to display its version on the console.

// Initialize Worker
let brsWorker = new Worker("node_modules/brs-emu/app/lib/brsEmu.js");
brsWorker.addEventListener("message", receiveMessage);
brsWorker.postMessage("getVersion");
// Web Worker Callback
function receiveMessage(event) {
if (event.data.substr(0, 8) === "version:") {
        console.log(event.data.substr(8));
    }
}

Web Application

This repository provides a sample web appplication for testing the emulator, located under the app folder. The application cannot be run as pure HTML page, because some functionalities used by the emulator have security restrictions on the browser engine, so you will need a web server to run it. For that you can use Apache, IIS or any simpler web server, but please note that starting from Chrome version 92, the emulator web app will require to be hosted with COOP and COEP custom headers to allow isolation and enable usage of ShareArrayBuffer. More information visit: https://developer.chrome.com/blog/enabling-shared-array-buffer/

Desktop Application

You can also run the emulator as a desktop application, download and install the specific OS package from the latest release. For the app source and documentation check the app repository.

Note for BrightScript Developers

You can see the debug messages from print statements in your code using the browser console, just make sure you open the Developer Tools (Ctrl+Shift+i) before loading your channel package or brs file. Exceptions from the emulator will be shown there too. If your code does show an error in some scenario not listed on the limitations documentation, feel free to open an issue.

Games and Demos

You can try the emulator by running one of the demonstration channels included in the repository, these are pre-configured as clickable icons on index.html. In addition to those, you can load your own code, either as a single .brs file or a channel .zip package. Below there is a list of tested games that are publicly available with source code, download the zip files and have fun!

Contributing

There are many ways in which you can participate in the project, read documents below to know the details:

License

Copyright © Marcelo Lv Cabral. All rights reserved.

Licensed under the MIT license.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100