# BrightScript Simulation Engine for Web

An interpreter for the BrightScript language that runs Roku apps in browser-based platforms.

[![NPM Version](https://img.shields.io/npm/v/brs-engine?logo=npm&label=brs-engine&color=blue)](https://npmjs.org/package/brs-engine)
[![License](https://img.shields.io/github/license/lvcabral/brs-engine?logo=github)](https://github.com/lvcabral/brs-engine/blob/master/LICENSE)
[![Build](https://github.com/lvcabral/brs-engine/actions/workflows/build.yml/badge.svg)](https://github.com/lvcabral/brs-engine/actions/workflows/build.yml)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=lvcabral_brs-emu&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=lvcabral_brs-emu)
[![Slack](https://img.shields.io/badge/Slack-RokuCommunity-4A154B?logo=slack)](https://join.slack.com/t/rokudevelopers/shared_invite/zt-4vw7rg6v-NH46oY7hTktpRIBM_zGvwA)

## Overview

The **BrightScript Simulation Engine** provides a complete BrightScript interpreter that runs directly in web browsers, allowing [Roku apps](https://developer.roku.com/develop) to be executed in web applications, PWAs and Electron applications.
This package includes a **Web Worker** library and an **Engine API** library for embedding the interpreter into web applications.
> 🚨 Important:
>
> Since v1.9.0, this package no longer brings the **CLI** app and **Node.js** libraries for the **simulation engine**, for those use cases we created the new [brs-node](https://www.npmjs.com/package/brs-node) package. Check it out!

<p align="center"><img alt="Simulator Web and Desktop" title="Simulator Web and Desktop" src="https://raw.githubusercontent.com/lvcabral/brs-engine/refs/heads/master/docs/images/screenshots.png"/></p>

## Key Features

### 🌐 Web Browser Support

- **Client-side only** - No server required
- Runs in modern web browsers using **Web Workers**
- Full **HTML5 Canvas** rendering support
- Audio and video playback via HTML5 elements
- Release your Roku apps as web applications, PWAs or Electron apps

### ⚙️ BrightScript Interpreter

- Full BrightScript language interpreter, with specs aligned up to Roku OS 15.3
- **Draw 2D API** - Full support for the BrightScript 2D drawing components
- **SceneGraph Framework** - Experimental support for the BrightScript SceneGraph components
- **Video Playback** - Via `roVideoPlayer` and `Video` node
- **Audio Playback** - Via `roAudioResources`, `roAudioPlayer` and `Audio` node
- **Image Processing** - Support for PNG, JPEG, GIF, BMP and WEBP formats

### 📺 Device Simulation

- **Screen resolutions** - Support for various Roku display modes
- **Input Handling** - Keyboard and gamepad simulation for remote control input, see [docs](https://github.com/lvcabral/brs-engine/blob/master/docs/remote-control.md) for more details
- **File System Simulation** - Including `pkg:/`, `tmp:/`, `cachefs:/`, `common:/` and `ext1:/` volumes
- **Registry simulation** - Roku device registry emulation saved on browser local storage
- **Micro Debugger** - Step-through debugging capabilities, similar to the Roku experience
- **Localization** - Language and region settings
- **Customization** - You can customize device features and behaviors, see [docs](https://github.com/lvcabral/brs-engine/blob/master/docs/customization.md) for more details

## SceneGraph Extension

SceneGraph support is provided by the optional [`brs-scenegraph`](https://www.npmjs.com/package/brs-scenegraph) extension. When your Roku app bundle contains `pkg:/components/`, the packaging step automatically instructs the worker to load `lib/brs-sg.js` so `roSGScreen` based apps run inside the browser. See [extensions guide](https://github.com/lvcabral/brs-engine/blob/master/docs/extensions.md) for deployment details.


> ⚠️ Note:
>
> **SceneGraph** extension is mostly complete, with **beta** versions available for testing. See the current state of the SceneGraph implementation and other limitations of the **engine** in the [Current Limitations](https://github.com/lvcabral/brs-engine/blob/master/docs/limitations.md) document.

## Installation

```bash
npm install brs-engine
```

### Libraries

| Library File | Description |
| --- | --- |
| `lib/brs.api.js` | The **[Engine API](https://github.com/lvcabral/brs-engine/blob/master/docs/engine-api.md)** library to be imported and used by the applications hosting the Simulator. |
| `lib/brs.worker.js` | A **[Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers)** library that runs the language interpreter in a background thread on the browser platform. |
| `lib/brs-sg.js` | The optional **[SceneGraph extension](https://www.npmjs.com/package/brs-scenegraph)** bundle, loaded by the worker when the app contains `pkg:/components/`. Must be deployed in the same folder as the worker. |

### Compatibility

The Web Worker library require features like [SharedArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) and [OffScreenCanvas](https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas), that are _relatively recent_ in the browser engines, because of that, it can only be executed on the following versions of the major browsers:

- [Chromium](https://www.chromium.org/Home)/[Chrome](https://www.google.com/chrome) version 69 or newer.
- [Chrome Android](https://www.google.com/chrome) version 89 or newer.
- [Edge](https://www.microsoft.com/en-us/edge), version 79 or newer.
- [Opera](https://www.opera.com), version 56 or newer.
- [Firefox](https://firefox.com), version 105 or newer.
- [Safari macOS/iOS/ipadOS](https://www.apple.com/safari), version 16.4 or newer.
- [Electron](https://electronjs.org), version 4.0 or newer.

## Documentation

This package repository provides a sample web application you can quickly run and test the engine, check the docs to learn more:

- [How to integrate the engine to your app](https://github.com/lvcabral/brs-engine/blob/master/docs/integrating.md)
- [How to customize the Engine behavior](https://github.com/lvcabral/brs-engine/blob/master/docs/customization.md)
- [Simulation Engine API Reference](https://github.com/lvcabral/brs-engine/blob/master/docs/engine-api.md)
- [Remote Control Simulation](https://github.com/lvcabral/brs-engine/blob/master/docs/remote-control.md)
- [How to build from source](https://github.com/lvcabral/brs-engine/blob/master/docs/build-from-source.md)
- [How to contribute to this Project](https://github.com/lvcabral/brs-engine/blob/master/docs/contributing.md)

### Changelog

- Read the [project changelog](https://github.com/lvcabral/brs-engine/blob/master/CHANGELOG.md) to view the release notes.

## Applications

These are the applications already using `brs-engine` to run apps and help developers to learn coding in BrightScript.

### Live Web Applications

Try the engine in action with these web applications:

- **BrightScript TV** - A demo web application to run full Roku games and apps: <https://lvcabral.com/brs>
- **brsFiddle** - BrightScript playground to test and share code with your friends: <https://brsFiddle.net>
  - Hello World - [Shared Link](https://brsfiddle.net?code=XQAAAAL1AQAAAAAAAABJKoLnIqZU8B3-6dP2NsOmYLl2BuS_zvKqVwuCb900INmQka2JaG6109nguctrC4j5eeejusZdPZeqN7ODPGAHtZa3CitoUr0Lzf0CNfBMe_fKYxZVbBd3SFCx2pochQ8vXiLaMlX28Cc1xvIyR03lxJtEM3BO0wVuiOYr28HsPq0Yh-7QOe8y1A-TeWsDOMOEQO0YDxB86jAP7EXurCri8pscM-e70RBruCRmIlFupFBKRsE2GneP6qIr0cz0r69DJ9xuBnscqSBt8CvQFz5haqlrzi9T-BRs4qM1qQid4peKgfvF6s9QEy9nHMwtR_YJMI-5PBvHmU0E4knAAMoNG-Sy1UydLH0sb8RiwTn9IajExgUnwz89MTn5AWfJx2KPUY5QPhpAyFDZnR1H_-j54Fw)
  - Bouncing Square - [Shared Link](https://brsfiddle.net? )
  - Calculate Easter Day - [Shared Link](https://brsfiddle.net? )
  - Download Image and Music - [Shared Link](https://brsfiddle.net? )
  - Video Playback - [Shared Link](https://brsfiddle.net? )
  - API Call Example - [Shared Link](https://brsfiddle.net? )
  - Snake Game - [Shared Link](https://brsfiddle.net? )

### 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 additional Roku features, such as the **ECP** (External Control Protocol) and **Remote Console** servers to allow integration with tools like Telnet or [VSCode BrightScript Extension](https://marketplace.visualstudio.com/items?itemName=RokuCommunity.brightscript). 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:

- Source code and documentation: [app repository](https://github.com/lvcabral/brs-desktop).
- Architecture Overview: [diagram picture](https://github.com/lvcabral/brs-desktop/blob/master/docs/images/brs-desktop-architecture-overview.png).
- Installation packages: [release page](https://github.com/lvcabral/brs-desktop/releases).

## Developer Links

- My website: [https://lvcabral.com](https://lvcabral.com)
- My threads: [@lvcabral](https://www.threads.net/@lvcabral)
- My Bluesky: [@lvcabral.com](https://bsky.app/profile/lvcabral.com)
- My X/twitter: [@lvcabral](https://twitter.com/lvcabral)
- My podcast: [PODebug Podcast](http://podebug.com)
- Check my other [GitHub repositories](https://github.com/lvcabral)

## License

Copyright © 2019-2026 Marcelo Lv Cabral. All rights reserved.

Licensed under the [MIT](https://github.com/lvcabral/brs-engine/blob/master/LICENSE) license.