Add support for hot reload of modified code (#49)

* Make copy of hello-world sample as basis for debuggable hot reloading sample

* Update the npm run debug script to watch for file changes

* Add VSCode launch configuration for attaching debugger to hot reloadable sample

* Add 1 second delay on launch when debugging to allow debugger time to connect

* Update README for debuggable hot reload sample

* Delete hello-world-with-debuggable-hot-reload sample in favor of making existing samples hot reloadable

* Update sample npm run debug scripts to watch for file system changes

* Avoid race condition between tsc compiler and nodemod file system watcher

* Add 1 second delay on launch when debugging to allow debugger time to connect

* Modify VSCode launch configurations to allow debugging while hot reloading

* Improve sample READMEs to include debugging instructions

* Update VSCode launch config to include both attach and launch configurations

* Move concurrently from dependencies to devDependencies

* Create separate debug-watch and debug commands

* Add attach configs to launch.json while keeping existing attach configs intact

* Only need one attach config for debugger

* Make copy of hello-world sample as basis for debuggable hot reloading sample

* Update the npm run debug script to watch for file changes

* Add VSCode launch configuration for attaching debugger to hot reloadable sample

* Add 1 second delay on launch when debugging to allow debugger time to connect

* Update README for debuggable hot reload sample

* Delete hello-world-with-debuggable-hot-reload sample in favor of making existing samples hot reloadable

* Update sample npm run debug scripts to watch for file system changes

* Avoid race condition between tsc compiler and nodemod file system watcher

* Add 1 second delay on launch when debugging to allow debugger time to connect

* Modify VSCode launch configurations to allow debugging while hot reloading

* Improve sample READMEs to include debugging instructions

* Update VSCode launch config to include both attach and launch configurations

* Move concurrently from dependencies to devDependencies

* Create separate debug-watch and debug commands

* Add attach configs to launch.json while keeping existing attach configs intact

* Only need one attach config for debugger

* Tweaks to hot reload and docs

* apostrophe

* Update package-lock.json

* Remove accidentally added eslint-plugin-header package

* Update package-lock.json files

* Remove startup delay from app.ts

* Add startup delay to other samples.

* Fix line endings.

* Remove opinionated text.

* Propagate doc updates to other samples.

Co-authored-by: Eric Anderson <[email protected]>

.vscode/launch.json

@@ -7,14 +7,14 @@
     {
       "type": "node",
       "request": "launch",
-      "name": "Launch tic-tac-toe project",
+      "name": "Launch hello-world project",
       "runtimeExecutable": "npm",
       "runtimeArgs": [
         "run-script",
         "debug"
       ],
       "port": 9229,
-      "cwd": "${workspaceFolder}/samples/tic-tac-toe",
+      "cwd": "${workspaceFolder}/samples/hello-world",
       "internalConsoleOptions": "openOnSessionStart",
       "autoAttachChildProcesses": true,
       "console": "internalConsole",
@@ -23,14 +23,14 @@
     {
       "type": "node",
       "request": "launch",
-      "name": "Launch hello-world project",
+      "name": "Launch solar-system project",
       "runtimeExecutable": "npm",
       "runtimeArgs": [
         "run-script",
         "debug"
       ],
       "port": 9229,
-      "cwd": "${workspaceFolder}/samples/hello-world",
+      "cwd": "${workspaceFolder}/samples/solar-system",
       "internalConsoleOptions": "openOnSessionStart",
       "autoAttachChildProcesses": true,
       "console": "internalConsole",
@@ -39,14 +39,14 @@
     {
       "type": "node",
       "request": "launch",
-      "name": "Launch solar-system project",
+      "name": "Launch tic-tac-toe project",
       "runtimeExecutable": "npm",
       "runtimeArgs": [
         "run-script",
         "debug"
       ],
       "port": 9229,
-      "cwd": "${workspaceFolder}/samples/solar-system",
+      "cwd": "${workspaceFolder}/samples/tic-tac-toe",
       "internalConsoleOptions": "openOnSessionStart",
       "autoAttachChildProcesses": true,
       "console": "internalConsole",
@@ -67,6 +67,14 @@
       "autoAttachChildProcesses": true,
       "console": "internalConsole",
       "outputCapture": "std"
-    }
+    },
+    {
+      "type": "node",
+      "request": "attach",
+      "name": "Attach to running project",
+      "port": 9229,
+      "internalConsoleOptions": "openOnSessionStart",
+      "restart": true,
+    },
   ]
 }

DEVELOPER.md

@@ -1,11 +1,10 @@
 ## Building Sample Apps Against SDK Source Code
 
-If you wish to build and debug the samples against the cloced source code for the SDK, we have provided a script to help
+If you wish to build and debug the samples against the cloned source code for the SDK, we have provided a script to help
 you to point your app to the local source code package of the SDK rather than the one published to NPM.  To do this you
 will first need to clone the [Mixed Reality Extension SDK](https://github.com/Microsoft/mixed-reality-extension-sdk)
 and add a sdk-path-config.json file that contains the json `{ "sdkPath": "<path_to_sdk>"}` where the `<path_to_sdk>` is
-the root folder of your SDK repo clone. This json file should be added to the `./scripts` directory where the
-helper script is located.  
+the root folder of your SDK repo clone. This json file should be added to the `./scripts` directory where the helper script is located.
 See `sdk-path-config-example.json` as an example that assumes you have cloned the SDK and sample repositories with their default names into the same parent folder.
 
 Once added you can simply run the following npm scripts within the `./scripts` directory to
@@ -14,4 +13,4 @@ switch between SDK source code and the NPM package for the sample apps.
 - `npm run use-sdk-source` to use the SDK source code.
 - `npm run use-sdk-npm` to use the SDK NPM package.
 
-The script requires shelljs to be installed, so you may need to use `npm install shelljs`.
+The script requires shelljs to be installed, so you may need to use `npm install shelljs`.

README.md

@@ -23,7 +23,7 @@ little if there are no changes)
 In AltspaceVR
 * Go to your personal home
 * Make sure you are signed in properly, not a guest
-* Activate the Space Editor
+* Activate the Space Editor (only available if you indicate you want to participate in the Early Access Program in your AltspaceVR settings)
 * Click Basics group
 * Click on SDKApp
 * For the URL field, enter `ws://localhost:3901`
@@ -47,10 +47,10 @@ To learn more about the SDK, please read the [MRE SDK readme](
 https://github.com/Microsoft/mixed-reality-extension-sdk/blob/master/README.md).
 
 ## Sample Descriptions
-* Hello World - shows a text that animates when highlighting or clicking on a
-cube
-* Solar System - loads a 3d model for each planet, generates keyframe
-animations, and when all assets are ready, start all animations simultaneously.
+* Hello World - Shows text and a cube that animates when highlighted or clicked. Demonstrates basic scene creation and interaction.
+* Solar System - Loads a 3d model for each planet and animates planetary motion. Demonstrates animation generation and more advanced scene creation.
+* Tic-Tac-Toe - The classic game also known as "Noughts & Crosses". Demonstrates gameplay with win/lose conditions.
+* Wear A Hat - Users can choose a hat from a menu and it will appear on their head. Demonstrates attachments.
 
 ## Contributing
 

samples/hello-world/README.md

@@ -1,15 +1,54 @@
 Shows a text that animates when highlighting or clicking on a cube.
 
-## Editing
+## Setup
 
-* Open this folder in VSCode.
+* Open a command prompt to this sample's folder and run `npm install`. Keep the command prompt open if you wish to follow the command-oriented instructions that follow.
+* Open the root folder of this repo in VSCode if you wish to follow the VSCode-oriented instructions.
 
-## Building
+## Build
 
-* From inside VSCode: `Shift+Ctrl+B`
-* From command line: `npm run build`
+* Command line: `npm run build`.
+* VSCode: `Shift+Ctrl+B`, then select 'build samples/hello-world'.
 
-## Running
+## Run
 
-* From inside VSCode: `F5`
-* From command line: `npm start`
+* Command line: `npm start`.
+* VSCode: Switch to the 'Run' tab (`Ctrl+Shift+D` will open it), select 'Launch hello-world project' from the dropdown at the top, and then `F5` to start it.
+
+MRE apps are NodeJS servers. They operate akin to a web server. When you start your MRE, it won't do much until you connect to it from a client application like AltspaceVR or the MRETestBed.
+
+## Test in [AltspaceVR](https://altvr.com)
+
+* Download [AltspaceVR](https://altvr.com) and create an account.
+* Launch the application and sign in. You'll start in your "home space".
+* Open the World Editor (only available if you indicate you want to participate in the [Early Access Program](https://altvr.com/early-access-program/) in your AltspaceVR settings).
+* Add a `Basics` / `SDK App` object with a Target URI of `ws://127.0.0.1:3901`.
+* See the the app appear in your space.
+
+## Test in Unity using the [MRETestBed](https://www.github.com/mixed-reality-extension-sdk-samples)
+
+* Install [Unity](https://unity3d.com/get-unity/download), version 2019.2.12f1 or later.
+* Clone the [MRE Unity repo](https://github.com/microsoft/mixed-reality-extension-unity).
+* Open the 'MRETestBed' Unity project.
+* Select the 'Standalone' scene. This scene is preconfigured to connect to your MRE running locally.
+* Start the Unity scene, and see the app appear.
+
+## Advanced: Debug with Hot-Reload
+
+Whether developing an MRE or another kind of app, an efficient dev/test loop is essential. Devs familiar with making browser-based apps will be familiar with webpack's notion of "hot reload", that is, automatically applying changes as they're made without the need to explicitly stop/rebuild/restart your app. NodeJS apps can do this too.
+
+This setup requires launching the app from a terminal. VSCode has a built-in terminal, or you can open a separate command prompt.
+
+### Start the MRE with hot-reload enabled
+
+1. In the terminal, in this project's folder, run: `npm run debug-watch`. This will build and start the MRE. The `debug-watch` task continues to run in the background, watching for code changes. It will rebuild and restart the app whenever files are modified.
+2. In VSCode, press `Ctrl+Shift+D` to open the 'Run' tab, select 'Attach to running project' from the drop down at the top, then press `F5` to attach the VSCode debugger. This step isn't required, but allows you to set breakpoints and debug MRE execution.
+
+### See hot-reload in action
+
+Once you have your MRE up and running, and you've successfully spawned an instance in AltspaceVR or another supported platform, it is time to make some code changes and see hot reload in action:
+
+* In VSCode, open `samples/hello-world/app.ts`.
+* In the `App.started()` method, find the line that reads `contents: "Hello World!",` and change the string to `"Hello Brave New World!"`.
+* Save the file.
+* Watch how the changes to your code are automatically detected and reloaded. The text in your app should change to `"Hello Brave New World!"`