brs-engine: Release v1.0.0 (#199)

This commit has all the changes needed for the first fulll release of the library, with the project renamed from `brs-emu` to `brs-engine`, see the CHANGELOG.md file for all the details.
lvcabral · Dec 16, 2023 · 581dfc0 · 581dfc0
1 parent 6382621
commit 581dfc0
Show file tree

Hide file tree

Showing 140 changed files with 2,944 additions and 1,243 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -29,4 +29,6 @@ jobs:
     - name: Build
       run: |
         yarn install
+        yarn lint
+        yarn prettier
         yarn build
diff --git a/.gitignore b/.gitignore
@@ -1,12 +1,14 @@
 .vscode/
 .idea/
 app/lib/
+bin/
 types/
 node_modules*/
 dist/
 out/
 /channels/
 *.pkg
+*.bpk
 desktop.ini
 .DS_Store
 .husky

diff --git a/.prettierignore b/.prettierignore
@@ -1,4 +1,5 @@
 types
 app/lib
+bin
 package.json
 **/*.js.snap
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/LICENSE b/LICENSE
@@ -1,7 +1,7 @@
 MIT License
 
 Copyright (c) 2019-2023, Marcelo Lv Cabral
-Copyright (c) 2018-2023, Sean Barag for BRS Interpreter
+Copyright (c) 2018-2021, Sean Barag for original BRS parser/interpreter code
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
diff --git a/app/channels/Collisions.zip b/app/channels/Collisions.zip
diff --git a/app/css/default.css b/app/css/default.css
@@ -21,6 +21,7 @@ body {
 	min-height: 90%;
 	padding: 30px;
 	padding-top: 10px;
+	padding-bottom: 5px;
 	border-radius: 5px;
 	box-shadow: 3px 3px 5px #444;
 }

diff --git a/app/favicon.ico b/app/favicon.ico
diff --git a/app/images/brightscript-tv.png b/app/images/brightscript-tv.png
diff --git a/app/images/collapse.png b/app/images/collapse.png
diff --git a/app/images/expand-new.png b/app/images/expand-new.png
diff --git a/app/images/expand.png b/app/images/expand.png
diff --git a/app/images/icon.png b/app/images/icon.png
diff --git a/app/images/ball-boing-icon.png → app/images/icons/ball-boing-icon.png b/app/images/ball-boing-icon.png → app/images/icons/ball-boing-icon.png
diff --git a/app/images/collisions-icon.png → app/images/icons/collisions-icon.png b/app/images/collisions-icon.png → app/images/icons/collisions-icon.png
diff --git a/app/images/rect-bounce-icon.png → app/images/icons/rect-bounce-icon.png b/app/images/rect-bounce-icon.png → app/images/icons/rect-bounce-icon.png
diff --git a/app/index.html b/app/index.html
@@ -5,80 +5,85 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta http-equiv="X-UA-Compatible" content="ie=edge">
-    <meta http-equiv="Content-Security-Policy" content="default-src 'unsafe-inline' 'unsafe-eval' data: blob: 'self' 
+    <meta http-equiv="Content-Security-Policy" content="default-src 'unsafe-inline' 'unsafe-eval' data: blob: 'self'
         https://fonts.googleapis.com
         https://fonts.gstatic.com
         https://www.googletagmanager.com
         https://www.google-analytics.com;">
-    <title>BrightScript Emulator</title>
+    <title>BrightScript Engine</title>
     <link href="css/default.css" rel="stylesheet" type="text/css" />
     <link href='https://fonts.googleapis.com/css?family=Maven+Pro|Muli|Istok+Web' rel='stylesheet' type='text/css' />
     <link rel="icon" href="./favicon.ico" type="image/x-icon" />
 </head>
 
 <body>
-    <a href="https://github.com/lvcabral/brs-emu/"><img style="position: absolute; top: 0; right: 0; border: 0;"
-            src="images/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
     <div id="container">
-        <h2>BrightScript Emulator :: v<span id="libVersion"></span> Beta
-            <hr>
-        </h2>
+        <a href="https://github.com/lvcabral/brs-engine/"><img style="position: absolute; top: 0; right: 0; border: 0;"
+            src="images/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
         <div style="position: relative; left: 0px; top: 0px">
             <img class="img" src="images/brightscript-tv.png" width="1252" height="650" alt="tv background" />
             <img id="loading" src="images/loading.gif" width="854px" height="480px" alt="loading..." />
             <div id="stats"></div>
             <canvas id="display" width="854px" height="480px"></canvas>
-            <a href="#" onclick="loadZip('channels/Rect-Bounce.zip')">
-                <img id="channel1" src="images/rect-bounce-icon.png" title="Open Rectangle Bounce demo app" alt="Reclangle Bounce app icon" />
-            </a>
-            <a href="#" onclick="loadZip('channels/Ball-Boing.zip')">
-                <img id="channel2" src="images/ball-boing-icon.png" title="Open Ball Boing demo app" alt="Ball Boing app icon" />
-            </a>
-            <a href="#" onclick="loadZip('channels/Collisions.zip')">
-                <img id="channel3" src="images/collisions-icon.png" title="Open Sprite Collisions demo app" alt="Sprite Collision app icon" />
-            </a>
+            <img id="channel1" src="images/icons/rect-bounce-icon.png" title="Open Rectangle Bounce demo app" alt="Rectangle Bounce app icon" onclick="loadZip('channels/Rect-Bounce.zip')" style="cursor: pointer;" />
+            <img id="channel2" src="images/icons/ball-boing-icon.png" title="Open Ball Boing demo app" alt="Ball Boing app icon" onclick="loadZip('channels/Ball-Boing.zip')" style="cursor: pointer;" />
+            <img id="channel3" src="images/icons/collisions-icon.png" title="Open Sprite Collisions demo app" alt="Sprite Collision app icon" onclick="loadZip('channels/Collisions.zip')" style="cursor: pointer;" />
             <span id="channelInfo"></span>
             <input type="file" id="file" accept=".brs,.zip,.bpk" style="display: none;" />
             <input type="button" id="fileButton" class="fileButton" value="Open a ZIP, BPK or BRS file..." />
+            <br /><br /><br /><br /><br /><br /><br />
+            <div id="expand-new" style="text-align: center;">
+                <img src="./images/expand-new.png" title="Expand Project Information" alt="expand icon" width="298" height="100" onclick="toggleDiv('details');" style="vertical-align: bottom; cursor: pointer;" />
+            </div>
+            <div id="expand" style="text-align: center; display: none;">
+                <img src="./images/expand.png" title="Expand Project Information" alt="expand icon" width="298" height="100" onclick="toggleDiv('details');" style="vertical-align: bottom; cursor: pointer;" />
+            </div>
+            <div id="collapse" style="text-align: center; display: none;">
+                <img src="./images/collapse.png" title="Hide Project Information" alt="collapse icon" width="298" height="100" onclick="toggleDiv('details');" style="vertical-align: bottom; cursor: pointer;" />
+            </div>
         </div>
-        <br /><br /><br /><br /><br /><br />
-
-        <h3>How to Use the BrightScript Emulator</h3>
-        <p>&ndash;&nbsp;Click on any app icon in the BrightScript TV menu screen or load your own app or code using the purple button above.</p>
-        <p>&ndash;&nbsp;When an app is running, you can make it <b>full screen</b> by double-clicking on the emulator display.</p>
-        <p>&ndash;&nbsp;Use your keyboard to navigate on the games and apps, the image you see on the right side, shows what keys 
-            that are mapped to the Roku remote control buttons.</p>
+        <div id="details" style="display: none;">
+            <hr>
+            <img src="./images/icon.png" alt="brs-engine icon" width="48" height="48" style="float: right; margin-top: 1px;" />
+            <h2>BrightScript Simulation Engine :: v<span id="libVersion"></span>
+                <hr>
+            </h2>
+            <h3>How to Use the BrightScript TV</h3>
+            <p>&ndash;&nbsp;Click on any app icon in the BrightScript TV menu screen or load your own app or code using the purple button above.</p>
+            <p>&ndash;&nbsp;When an app is running, you can make it <b>full screen</b> by double-clicking on the display.</p>
+            <p>&ndash;&nbsp;Use your keyboard to navigate on the games and apps, the image you see on the right side, shows what keys
+                that are mapped to the Roku remote control buttons.</p>
 
-        <h3>Notes for BrightScript Developers</h3>
-        <p>You can see the debug messages from <code>print</code> statements in your code using the <em>browser
-            console</em>, just right click anywhere in the page and select <em>Inspect (Ctrl+Shift+i)</em>. 
-            Exceptions from the emulator will be shown there too.</p>
-        <p>If you added a break point (<b>stop</b>) in your code, you can also debug using the <em>browser console</em>, 
-            just send the commands using: <code>brsEmu.debug("help")</code></p>
-        <p>The Roku `registry` data is stored on the browser Local Storage and you can inspect it using the Developer Tools.</p>
-        <p>For a better debugging experience, is recommended to use the emulator desktop app integrated with <b>Visual Studio Code</b>, you will
-        find more details in the links below.</p>
+            <h3>Notes for BrightScript Developers</h3>
+            <p>You can see the debug messages from <code>print</code> statements in your code using the <em>browser
+                console</em>, just right click anywhere in the page and select <em>Inspect (Ctrl+Shift+i)</em>.
+                Exceptions from the engine library will be shown there too.</p>
+            <p>If you added a break point (<b>stop</b>) in your code, you can also debug using the <em>browser console</em>,
+                just send the commands using: <code>brs.debug("help")</code></p>
+            <p>The Roku `registry` data is stored on the browser Local Storage and you can inspect it using the Developer Tools.</p>
+            <p>For a better debugging experience, is recommended to use the engine desktop application integrated with <b>Visual Studio Code</b>, you will
+            find more details in the links below.</p>
 
-        <h3>Documentation and Downloads</h3>
-        <p>To learn more about the project visit the repository at:
-            <a href="https://github.com/lvcabral/brs-emu/#readme">https://github.com/lvcabral/brs-emu/</a>
-        </p>
-        <p>To download the <b>Desktop Applications</b> for <b>Windows, macOS and Linux</b> go to the
-            <a href="https://github.com/lvcabral/brs-emu-app/releases">releases page</a>.
-        </p>
-        <p>You can download the source code of this project in either <a
-                href="https://github.com/lvcabral/brs-emu/zipball/master">zip</a> or <a
-                href="https://github.com/lvcabral/brs-emu/tarball/master">tar</a> formats.
-        </p>
-        <p>You can also clone the project with <a href="http://git-scm.com">Git</a> by running:
-        <pre>$ git clone https://github.com/lvcabral/brs-emu</pre>
-        </p>
-        <div class="footer">
-            <hr>Copyright © 2019-2023 by <a href="https://lvcabral.com">Marcelo Lv Cabral</a>
-            - contact: <a href="https://twitter.com/lvcabral">@lvcabral</a>
+            <h3>Documentation and Downloads</h3>
+            <p>To learn more about the project visit the repository at:
+                <a href="https://github.com/lvcabral/brs-engine/#readme">https://github.com/lvcabral/brs-engine/</a>
+            </p>
+            <p>To download the <b>Desktop Applications</b> for <b>Windows, macOS and Linux</b> go to the
+                <a href="https://github.com/lvcabral/brs-emu-app/releases">releases page</a>.
+            </p>
+            <p>You can download the source code of this project in either <a
+                    href="https://github.com/lvcabral/brs-engine/zipball/master">zip</a> or <a
+                    href="https://github.com/lvcabral/brs-engine/tarball/master">tar</a> formats.
+            </p>
+            <p>You can also clone the project with <a href="http://git-scm.com">Git</a> by running:
+            <pre>$ git clone https://github.com/lvcabral/brs-engine</pre>
+            </p>
+            <div class="footer">
+                <hr>Copyright © 2019-2023 by <a href="https://lvcabral.com">Marcelo Lv Cabral</a>
+            </div>
         </div>
     </div>
-    <script type="text/javascript" src="lib/brsEmu.js"></script>
+    <script type="text/javascript" src="lib/brs.api.js"></script>
     <script type="text/javascript" src="index.js"></script>
 </body>
 

diff --git a/app/index.js b/app/index.js
@@ -1,5 +1,5 @@
 /*---------------------------------------------------------------------------------------------
- *  BrightScript Emulator (https://github.com/lvcabral/brs-emu)
+ *  BrightScript Engine (https://github.com/lvcabral/brs-engine)
  *
  *  Copyright (c) 2019-2023 Marcelo Lv Cabral. All Rights Reserved.
  *
@@ -18,9 +18,9 @@ const channel3 = document.getElementById("channel3");
 // Channel status object
 let currentChannel = { id: "", running: false };
 
-// Start the emulator
+// Start the engine
 channelInfo.innerHTML = "<br/>";
-// Custom Device Configuration (see /api/index.ts for all fields)
+// Custom device configuration (see /api/index.ts for all fields)
 const customDeviceInfo = {
     developerId: "UniqueDeveloperId", // As in Roku devices, segregates Registry data
     locale: "en_US", // Used if channel supports localization
@@ -39,14 +39,14 @@ customKeys.set("PageUp", "ignore"); // do not handle on browser
 customKeys.set("PageDown", "ignore"); // do not handle on browser
 customKeys.set("Digit8", "info");
 
-// Initialize Device Emulator and subscribe to events
-libVersion.innerHTML = brsEmu.getVersion();
-brsEmu.initialize(customDeviceInfo, {
+// Initialize device and subscribe to events
+libVersion.innerHTML = brs.getVersion();
+brs.initialize(customDeviceInfo, {
     debugToConsole: true,
     customKeys: customKeys,
     showStats: true,
 });
-brsEmu.subscribe("app", (event, data) => {
+brs.subscribe("app", (event, data) => {
     if (event === "loaded") {
         currentChannel = data;
         fileButton.style.visibility = "hidden";
@@ -97,13 +97,13 @@ fileSelector.onchange = function () {
                 password = prompt("Please enter the password to decrypt the package.");
             }
             if (password !== null) {
-                brsEmu.execute(file.name, evt.target.result, {
+                brs.execute(file.name, evt.target.result, {
                     clearDisplayOnExit: true,
                     muteSound: false,
                     execSource: "open_app_button",
                     password: password,
+                    debugOnCrash: true,
                 });
-                channelIcons("hidden");
             }
         };
         reader.onerror = function (evt) {
@@ -128,7 +128,7 @@ function loadZip(zip) {
             if (response.status === 200 || response.status === 0) {
                 return response.blob().then(function (zipBlob) {
                     zipBlob.arrayBuffer().then(function (zipData) {
-                        brsEmu.execute(zip, zipData, { execSource: "homescreen" });
+                        brs.execute(zip, zipData, { execSource: "homescreen" });
                         display.focus();
                     });
                 });
@@ -188,3 +188,20 @@ function parseVersionString(str) {
         patch: parseInt(vArray[2]) || 0,
     };
 }
+
+function toggleDiv(divId) {
+    const objDiv = document.getElementById(divId);
+    const butExpNew = document.getElementById("expand-new");
+    const butExp = document.getElementById("expand");
+    const butCol = document.getElementById("collapse");
+    if (objDiv.style.display == "") {
+        objDiv.style.display = "none";
+        butExp.style.display = "";
+        butCol.style.display = "none";
+    } else {
+        objDiv.style.display = "";
+        butExp.style.display = "none";
+        butExpNew.style.display = "none";
+        butCol.style.display = "";
+    }
+}
diff --git a/app/web-server.py b/app/web-server.py
diff --git a/docs/build-from-source.md b/docs/build-from-source.md
@@ -1,10 +1,10 @@
 # Building from Source
 
-The BRS project follows pretty standard `node` development patterns, with the caveat that it uses `yarn` for dependency management.
+The brs-engine project follows pretty standard `node` development patterns, with the caveat that it uses `yarn` for dependency management.
 
 ## Prerequisites
 
-BRS builds (and runs) in `node`, so you'll need to [install that first](https://nodejs.org).
+As it builds (and runs the CLI) in `node`, so you'll need to [install that first](https://nodejs.org).
 
 Once that's ready, install [yarn](https://yarnpkg.com).  Installing it with `npm` is probably the simplest:
 
@@ -17,7 +17,7 @@ $ npm install -g yarn
 1. Clone this repo:
 
    ```shell
-   $ git clone https://github.com/lvcabral/brs-emu.git
+   $ git clone https://github.com/lvcabral/brs-engine.git
    ```
 
 2. Install dependencies:
@@ -30,47 +30,47 @@ $ npm install -g yarn
 
 ### Build
 
-This project is written in TypeScript, so it needs to be compiled before it can be executed.  `yarn build` compiles files in `src/` into JavaScript and TypeScript declarations, and puts them in `lib/` and `types/` respectively.
+This project is written in TypeScript, so it needs to be compiled before it can be executed. `yarn build` compiles files in `src/` into JavaScript and TypeScript declarations, and puts them in `lib/`, `bin/` and `types/`.
 
 ```shell
 $ yarn build
 
 $ ls app/lib/
-brsEmu.js
-brsEmu.worker.js
+brs.api.js
+brs.worker.js
+
+$ ls bin/
+brs.cli.js
 
 $ ls types/
 index.d.ts (and friends)
 ```
 
 ### Release
 
-To release a smaller library Webpack can create a *minified* version by running `yarn release`.
-
-```shell
-$ yarn release
+To release a smaller version of the libraries Webpack can create a *minified* version by running `yarn release`.
 
-$ ls app/lib/
-brsEmu.min.js
-brsEmu.worker.min.js
-```
+### Running the Example Web Application
 
-If you want to use this release version, remember to update `app/index.js` to use `brsEmu.min.js` instead of `brsEmu.js`.
+To build and start the web application on your default browser just execute `yarn start`.
 
 ### Testing
 
 Tests are currently broken, the ones we have in the repository came with the fork from `brs`, and were written in plain-old JavaScript with [Facebook's Jest](http://facebook.github.io/jest/). If you are a test expert, or just want to help, this is a great area to collaborate.
 
 ### Cleaning
 
-Compiled output in `lib/` and `types/` can be removed with the `clean` target:
+Compiled output in `lib/`, `bin/` and `types/` can be removed with the `clean` target:
 
 ```shell
 $ yarn clean
 
 $ ls lib/
 ls: cannot access 'lib': No such file or directory
 
+$ ls bin/
+ls: cannot access 'bin': No such file or directory
+
 $ ls types/
 ls: cannot access 'types': No such file or directory
 ```