BrightScript Simulator (Dockerized)

A lightweight BrightScript simulator running in a Node.js + Docker environment — designed to let you execute and iterate on Roku .brs projects directly from your browser.

This is not a full Roku device emulator, but a generic simulator built on top of brs, the open-source BrightScript interpreter.
Currently, it supports simple script execution and live reload, with plans to expand toward UI scene simulation.

---

🧩 Overview

The simulator runs a Node.js web server that:

• Watches your BrighterScript project (source/**/*.bs) for changes (hot-reload).
• Compiles BrighterScript → BrightScript using bsc (from the brighterscript package).
• Generates compiled .brs files into the project's dist/ directory (staging dir).
• Serves a web UI with:
  • Build log showing compile status, errors, and warnings.
  • Compiled file viewer for inspecting generated .brs source code.
  • Execute button to run the compiled code via the brs CLI and display runtime output.
• Uses Server-Sent Events (SSE) to stream logs live to connected browser clients.

This is intended as a local dev environment to quickly test BrightScript logic (console output), not full Roku SceneGraph rendering.

---

🐳 Docker Setup

docker-compose.yml example:

services:
  brs-sim:
    build: .
    container_name: brs-sim
    ports:
      - "8080:8080"
    environment:
      - PROJECT_PATH=/app/projects
      - PROJECT=hello-world  # or hello-screen
      - FILE=source/main.brs
      - PORT=8080
    volumes:
      - ./projects:/app/projects
    working_dir: /app/projects/hello-world

Build and Run

docker compose up --build

Then open in your browser:

http://localhost:8080

You will see:

• Build Log: Live updates as you edit .bs files.
• Compiled Files: Click a file tab to view the generated .brs code.
• Execute Button: Run the compiled code and see runtime stdout output.

---

🗂️ Project Structure

.
├── Dockerfile                   # Node 18 + brighterscript + brs
├── docker-compose.yml          # Service config with hot-reload mounts
├── server.js                   # Express server + watcher + compile/execute orchestration
├── package.json                # Dependencies: express, brighterscript, brs, chokidar
├── public/                     # Static web UI (build log, file viewer, Execute button)
├── projects/
│   ├── hello-world/            # Simple console output example
│   │   ├── bsconfig.json       # BrighterScript compiler config
│   │   ├── manifest            # Roku manifest (metadata)
│   │   ├── source/             # BrighterScript source (.bs files)
│   │   │   ├── main.bs
│   │   │   └── greet.bs
│   │   └── dist/               # Generated by bsc (staging dir)
│   └── hello-screen/           # UI scene example with ASCII rendering
│       ├── bsconfig.json       # BrighterScript compiler config
│       ├── manifest            # Roku manifest (metadata)
│       ├── source/             # BrighterScript source (.bs files)
│       │   └── main.bs
│       └── dist/               # Generated by bsc (staging dir)

Sample BrighterScript app

projects/hello-world/source/main.bs

import "./greet.bs"

sub main() as void
    print "Hello from main.bs"
    Greet.Greet_Hello("developer")
end sub

main()

projects/hello-world/source/greet.bs

namespace Greet

function Greet_Hello(name as string)
    print "Hello " + name
end function

end namespace

When you click Execute, the server runs the compiled .brs files (via npx brs) and displays output:

Hello from main.bs
Hello developer

Sample Roku UI Scene (hello-screen)

projects/hello-screen/source/main.bs demonstrates a simple scene with UI elements:

sub main() as void
    print "=== Hello Screen Demo ==="
    scene = CreateHelloScene()
    print "Message: " + scene.message
    RenderScene(scene)
end sub

function CreateHelloScene() as object
    scene = {
        message: "Welcome to BrightScript UI Demo!"
        colors: { background: "#1a1a1a", text: "#ffffff", accent: "#00a8ff" }
        elements: [
            { type: "Label", text: "Hello Screen" }
            { type: "Button", text: "Start", width: 200, height: 50 }
        ]
    }
    return scene
end function

function RenderScene(scene as object) as void
    print "┌" + string(50, "─") + "┐"
    print "│ " + CenterText(scene.message, 48) + " │"
    print "├" + string(50, "─") + "┤"
    ' Render UI elements with ASCII art...'
    print "└" + string(50, "─") + "┘"
end function

Output when executed:

=== Hello Screen Demo ===
Message: Welcome to BrightScript UI Demo!

┌──────────────────────────────────────────────────────┐
│ Welcome to BrightScript UI Demo! │
├──────────────────────────────────────────────────────┤
│ Hello Screen
│ ╔════════════════════════╗
│ ║       Start        ║
│ ╚════════════════════════╝
└──────────────────────────────────────────────────────┘

To test the hello-screen project, update your docker-compose.yml:

• Change PROJECT=hello-world to PROJECT=hello-screen
• Change working_dir to /app/projects/hello-screen
• Then run docker compose up --build

---

🧠 How It Works

1. Watch: chokidar monitors projects/<PROJECT>/source/**/*.bs for changes.
2. Compile: On file change, runs npx bsc --project bsconfig.json (with cwd set to the project folder) to transpile BrighterScript → BrightScript into dist/source/.
3. List: Scans dist/ for compiled .brs files and broadcasts "Build completed" to all connected UI clients via SSE.
4. Serve UI: / serves a web page with a build log (live streamed), a compiled-files viewer, and an Execute button.
5. Execute: GET /execute runs npx brs <compiled-files...> (excluding bslib.brs) and returns runtime stdout.

Important notes:

• The compiler runs from the project directory so stagingDir: "dist" resolves correctly inside the project (avoiding nested dist/dist/... issues).
• Compiled files are filtered to exclude bslib.brs from execution (it's a runtime support library).
• All events (build status, errors, runtime output) are streamed to the browser via SSE so the UI stays synchronized.

---

🔧 Environment Variables

Variable	Default / Example	Description
PROJECT_PATH	/app/projects	Root directory of projects
PROJECT	hello-world	Target project folder name
FILE	source/main.brs	Entry BrightScript file path
PORT	8080	Port for the simulator UI

---

🚫 Limitations (for now)

• No SceneGraph or UI rendering — console-only output.
• Limited BrightScript APIs — depends on what brs supports.
• No package or Roku channel bundling — runs individual .brs files only.
• Environment variables are not yet exposed inside BrightScript global AA.

Planned improvements:

• Basic SceneGraph mock rendering (HTML canvas-based).
• API stubs for Roku built-ins.
• UI to edit and run scripts inline from the browser.

---

⚙️ Local Development

If you prefer to run directly without Docker:

npm install
npm start

Then set your .env:

PROJECT_PATH=./projects
PROJECT=hello-world
FILE=source/main.brs
PORT=8080

---

🔍 API Endpoints

Method	Path	Description
GET	/	Web UI
GET	/compiled-files	Returns JSON array of compiled .brs files in dist/
GET	/execute	Runs compiled code via npx brs and returns { output: "..." }
GET	/status	Returns simulator status
GET	/restart	Restarts BrightScript process
GET	/events	Server-sent event stream (live logs)

---

📜 License

MIT — free to use and extend.