BRS-EMU: BrightScript Emulator

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

The Library

This library extends brs, a command line interpreter for BrightScript language, with the objective of implementing a full emulator for the BrightScript developer community. Initially the focus was on the Draw 2D API components (roScreen, roCompositor, roRegion, etc.) along with most of the basic elements of the BrightScript language, allowing a full channel execution over an HTML5 Canvas, including emulation of the Roku file system, registry, remote control and the Micro Debugger. At this stage, SceneGraph channels and video playback are not supported, but the implementation of these features is now being considered.

Note: Although brs-emu runs channels with user interface, it has no intention of emulating the full Roku OS, it is primarily aimed as a development tool for the BrighScript Community. Please check the Current Limitations documentation for further details on what is out of scope.

Technology and Compatibility

This emulator is bundled as a couple of Webpack Javascript libraries:

• brsEmu.js the emulator API to be used by the client application.
• brsEmu.worker.js the Web Worker that runs the language interpreter in a background thread on the browser platform.

It uses features like SharedArrayBuffer and OffScreenCanvas, that are bleeding edge in the browser engines, because of that, at this moment, it can only be executed in:

1. Chromium based browsers, like Chrome, Brave, Opera and Edge.
2. Electron applications.
3. Firefox, version 105 or higher.
4. Safari, version 16.4 or higher.

Note: The BrightScript Emulator is a full client-side library, nothing needs to be sent or processed in the server side.

How to use it

If you just want to use the emulator, not installing or downloading anything, try the applications below:

• BrightScript TV - Run full emulated games and channels in your browser: https://lvcabral.com/brs
• brsFiddle - BrightScript playground to test and share code with others: http://brsFiddle.net

Desktop Application

You can also run the emulator as a multi-platform desktop application (Windows, Linux & macOS) that uses the same library generated by this project. The app, introduces several aditional features, such as the ECP (External Control Protocol) and Remote Console servers to allow integration with 3rd party development tools like the VSCode BrightScript Extension. It also allows you to control the device configuration like screen resolution, localization, among others.

Download Links

• Installation packages: release page.
• Source code and documentation: app repository.

How to Integrate to my App

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

Documentation

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

• How to build from source
• How add the Emulator to a Web Application
• BrightScript Emulator API
• How to contribute

Notes for BrightScript Developers

You can see the debug messages from print statements in your code using the browser or desktop app 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 you added a break point (stop) in your code, you can also debug using the browser console, just send the commands using: brsEmu.debug("help"). For a better debugging experience, is recommended to use the emulator desktop app integrated with VSCode.

The Roku registry data is stored on the browser Local Storage and you can inspect it using the Developer Tools.

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!

• 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

Author Links

• My website is https://lvcabral.com
• My twitter is @lvcabral
• My podcast is PODebug Podcast
• Check my other GitHub repositories

License

Copyright © Marcelo Lv Cabral. All rights reserved.

Licensed under the MIT license.