BrightScript Simulation Engine for Node.js

July 27, 2026 · View on GitHub

An interpreter for the BrightScript language that runs as a CLI and Roku apps in Node.js.

Overview

The BrightScript Simulation Engine provides a complete BrightScript interpreter, bundled as a set of libraries and a command-line interface, for executing, testing, and packaging Roku apps on Node.js platforms. Perfect for automation, CI/CD pipelines, development workflows, and server-side BrightScript execution.

🚨 Important:

Since v1.9.0, this package was split from the browser package, to use the simulation engine with web based applications check out the brs-engine package.

Simulator CLI

Key Features

🖥️ Command Line Interface

Interactive REPL - Read-eval-print loop for BrightScript
File Execution - Run .brs, .zip, and .bpk files directly
Folder Execution - Run BrightScript apps from a folder
App Packaging - Create encrypted .bpk packages from .zip files
Terminal Screen Rendering - Show the app screen as ASCII art, Unicode blocks or real images (iTerm2/Kitty)
Interactive Control - Keyboard remote control, PNG screenshots (Ctrl+S) and text output logging to file
Batch Processing - Execute multiple files and automate workflows

⚙️ 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 Roku SceneGraph components (see section below)
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 for more details
File System Simulation - Including pkg:/, tmp:/, cachefs:/, common:/ and ext1:/ volumes
Registry simulation - Roku device registry emulation, persisted to a local registry.json in the user data folder when --registry is used
Micro Debugger - Step-through debugging capabilities, similar to the Roku experience
ECP Server - External Control Protocol for remote control
SSDP Discovery - Device discovery simulation
Localization - Language and region settings
Customization - You can customize device features and behaviors, see docs for more details

SceneGraph Extension

The brs-scenegraph extension is bundled with the brs-node package (as bin/brs-sg.node.js). The CLI loads it automatically so the REPL and apps can run SceneGraph without additional setup — use the --no-sg flag to disable it for a given CLI session. When embedding the library:

With the synchronous executeFile, register it in-process: registerExtension(() => new BrightScriptExtension()).
With the worker-based executeApp, declare it on the payload (payload.extensions + payload.device.extensions) so every worker thread loads its own instance — see the Node.js library guide.

Refer to the extensions guide for more information about the extension architecture.

⚠️ 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 document.

Installation

Global Installation (CLI)

npm install -g brs-node

Project Installation (Library)

npm install brs-node

Libraries

The package libraries require Node.js v22 or higher, and are organized as follows:

Library File	Description
`bin/brs.cli.js`	Executable CLI application that can be used from the terminal
`bin/brs.node.js`	The engine library (the package `main`): exposes the interpreter to Node.js applications, and is also the worker entry used to run apps and SceneGraph Tasks on worker threads
`bin/brs.ecp.js`	A worker thread library, used by the CLI to launch the ECP and SSDP services
`bin/brs-sg.node.js`	The SceneGraph extension bundle, loaded dynamically into the engine (and into each worker thread) when SceneGraph support is needed

How the libraries relate

brs.node.js is the core — everything else plugs into it. It offers two execution models:
- executeFile(payload) runs the interpreter synchronously on the calling thread — ideal for tests, CI and scripting. SceneGraph Task nodes do not spawn in this mode.
- executeApp(payload) runs the app on a dedicated worker thread and spawns one worker per running SceneGraph Task, mirroring the browser engine and a real Roku device. The worker entry is brs.node.js itself.
brs-sg.node.js is deliberately a separate bundle (not compiled into the core): the interpreter stays SceneGraph-agnostic and loads it through the public extension API — the same contract available to third-party extensions. It binds to the running engine at load time (its brs-engine import resolves to the already-loaded brs.node.js module), so both must always come from the same package version. The CLI loads it automatically (--no-sg disables); library consumers register it per the examples in the Node.js library guide.
brs.cli.js is a consumer of the other three: it requires brs.node.js for execution, loads brs-sg.node.js for SceneGraph apps, and spawns brs.ecp.js as a worker when --ecp is passed.

Documentation

Learn how to use the package and its libraries by reading the documents below:

Changelog

Read the project changelog to view the release notes.

Developer Links

My website: https://lvcabral.com
My threads: @lvcabral
My Bluesky: @lvcabral.com
My X/twitter: @lvcabral
My podcast: PODebug Podcast
Check my other GitHub repositories

License

Licensed under the MIT license.