BrightScript Simulation Engine
How to Use the BrightScript TV
– Pick how do you want to start, in the browser, full screen or using touch screen mode.
– Navigate on the home screen using the keyboard, a game pad or screen controls (in case of touch mode) and select any app to run, just like on a Roku device.
– You can also run your own code (.zip, .bpk or .brs) using the purple button to side load the app.
– In Browser mode you can make the simulator full screen by double-clicking on the display canvas, in touch mode use your browser shortcut (e.g. F11 in Windows).
– Check the image on the side of the TV to learn the keys and gamepad buttons mapped to the Roku remote control.
About the Project
As a BrightScript developer since 2012, I always wanted a way to test my code without the need of a Roku device, in situations like a long flight or a place without any wireless network available. The solution would be to develop a simulator for the platform, so in 2019, I learned about the project brs, an open source command line interpreter for BrightScript created by Sean Barag and his Hulu team.
I could immediately see, that this project was the missing piece to turn my simulator project a reality! I forked it and started collaborating, sending pull requests to the project, so the interpreter could have the minimum set of components that would make possible for me to work upon it. Very soon, I developed a working proof-of-concept using HTML5 Canvas, and after a month of nights and weekends studying TypeScript/Javascript, and exploring all sort of options to overcome different challenges, I finally came up with a working simulator prototype. I've been improving the simulation engine since then, and this website is based on the latest stable version of it for anyone to use.
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 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.
Notes 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 app. Exceptions from the engine will be shown there too. The Roku registry data is stored on the browser Local Storage and you can inspect it also using the Developer Tools.
If you added a break point (stop) in your code, you can debug using the browser console, just send the commands using the debug method like this: brs.debug("help")
For a better debugging experience, is recommended to use the simulator desktop app integrated with Visual Studio Code, you will find more details in the project repository (links below).
Current Limitations
At this stage, apps based on SceneGraph framework are not yet supported, but this feature is now in the backlog to be implemented. Please check the project documentation to get an updated list of all current limitations.Games and Demos
The source code for some Roku apps and games are available in GitHub for you to learn:- Prince of Persia port for Roku by Marcelo Lv Cabral.
- Lode Runner remake for Roku by Marcelo Lv Cabral.
- Retaliate game created by Romans-I-XVI.
- Pong example game for the Roku Game Engine by Romans-I-XVI.
- Draw2d Performance Test a Benchmarking App by Mark Pearce
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 3rd party development tools like Telnet or VSCode BrightScript Extension. You can also change the device configurations such as screen resolution, keyboard control customization, localization, among others.
Documentation and Downloads
To learn more about the project visit the repository at: https://github.com/lvcabral/brs-engine
To download the Desktop Applications for Windows, macOS and Linux go to: https://github.com/lvcabral/brs-desktop/releases.
You can download the source code of this project in either zip or tar formats.
You can also clone the project with Git by running:
$ git clone git://github.com/lvcabral/brs-engine.git