An emulator for the Roku BrightScript language that runs on Chromium based browsers and Electron applications.
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.
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.
If you just want to try the emulator, not installing or downloading anything, then simply try the demo website at: https://lvcabral.com/brs
The brs-emu project is published as a node package, so use npm:
$ npm install brs-emuor yarn if that's your preference:
$ yarn add brs-emuThe 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));
}
}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/
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.
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.
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!
- Prince of Persia for Roku port by Marcelo Lv Cabral - Download zip file
- Lode Runner for Roku remake by Marcelo Lv Cabral - Download zip file
- Retaliate game by Romans I XVI - Download zip file
There are many ways in which you can participate in the project, read documents below to know the details:
- My website is https://lvcabral.com
- My twitter is @lvcabral
- My podcast is PODebug Podcast
- Check my other GitHub repositories
Copyright © Marcelo Lv Cabral. All rights reserved.
Licensed under the MIT license.