PlayCanvas + Standalone Viewer (#205)

.github/actions/npm-install-build-and-cache/action.yaml

@@ -47,4 +47,5 @@ runs:
         path: |
           packages/**/build/*
           e2e-tests/build/*
+          github-pages-publisher/build/*
         if-no-files-found: error

.github/workflows/pr-close.yaml

@@ -0,0 +1,37 @@
+name: delete preview on PR close
+
+# only trigger on pull request closed events
+on:
+  pull_request:
+    types: [closed]
+
+permissions:
+  id-token: write
+  contents: write
+  pull-requests: write
+  checks: write
+
+jobs:
+  delete_preview:
+    runs-on: ubuntu-latest
+    env:
+      PR_PATH: pull/${{github.event.number}}
+    steps:
+      - name: make empty dir
+        run: mkdir empty-dir
+
+      - name: delete folder
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./empty-dir
+          destination_dir: ${{ env.PR_PATH }}
+
+      - name: Comment on PR
+        uses: hasura/[email protected]
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          number: ${{ github.event.number }}
+          id: deploy-preview
+          message: "🪓 PR closed, deleted preview at https://github.com/${{ github.repository }}/tree/gh-pages/${{ env.PR_PATH }}/"

.github/workflows/pr.yaml

@@ -110,6 +110,42 @@ jobs:
           name: images
           path: e2e-tests/test/__image_snapshots__/
 
+  publish-gh-pages:
+    name: Publish GitHub Pages
+    needs: [ build ]
+    runs-on: ubuntu-latest
+    env:
+      PR_PATH: pull/${{github.event.number}}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          lfs: true
+          persist-credentials: false
+
+      - name: "Retrieve Dependencies and Build Artifacts"
+        id: retrieve-deps-and-build
+        uses: ./.github/actions/retrieve-deps-and-build
+
+      - name: Set base URL for preview if PR
+        run: echo "BASE_URL=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ env.PR_PATH }}/" >> $GITHUB_ENV
+
+      - name: Deploy to PR preview
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./github-pages-publisher/build
+          destination_dir: ${{ env.PR_PATH }}
+
+      - name: Add PR Preview comment
+        uses: hasura/[email protected]
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          number: ${{ github.event.number }}
+          id: deploy-preview
+          message: "A preview of this PR can be seen here:\n\n ✨ ${{ env.BASE_URL }} ✨\n\nChanges may take a few minutes to propagate. The source is here: https://github.com/${{ github.repository }}/tree/gh-pages/${{ env.PR_PATH }}/"
+
   summary:
     name: Summary
     needs: [build, test, type-check, lint, e2e-test]

README.md

@@ -58,32 +58,49 @@ The Networked DOM server and MML client can then be used to allow multiple users
 * **Portability**: MML documents can run in any modern web browser, making them easy to share and view.
 * **Composability**: MML documents can be composed of multiple documents running on different servers, making it possible to create complex virtual world objects without having to provide all the compute power and technical capability on a single server.
 
-# High-Level Package Architecture
+# Packages
 
 ## Language (MML)
-MML is a set of HTML elements and attributes that can be used to describe 3D objects and experiences.
+MML is a set of HTML elements and attributes that can be used to describe 3D objects and experiences. The schema for these elements and attributes is defined in XML Schema Definition Language (XSD).
 
-These elements and attributes can be used without networking. However, when a HTML document including MML tags is run on a server and exposed via a websocket multiple users can interact with the same instance of the document at the same time.
+* [./packages/schema](./packages/schema) - `@mml-io/schema` - MML Schema in XML Schema Definition Language (XSD)
+* [./packages/schema-validator](./packages/schema-validator) - `@mml-io/schema-validator` - A package for validating MML document using the MML Schema
+* [./packages/mml-react-types](./packages/mml-react-types) - `@mml-io/mml-react-types` - TypeScript types for using MML components in React
 
-* [./packages/mml-web](./packages/mml-web) - Web THREE.js MML Library
-* [./packages/mml-web-client](./packages/mml-web-client) - Web THREE.js MML Client
-* [./packages/mml-web-runner](./packages/mml-web-runner) - Web Runner (for running MML documents in a web browser rather than a server)
-* [./packages/schema](./packages/schema) - MML Schema in XML Schema Definition Language (XSD)
-* [./packages/schema-validator](./packages/schema-validator) - A package for validating MML document using the MML Schema
+## Web Packages
+MML can be used in a web browser to create 3D web experiences. Networking is optional and different libraries can be used to provide the 3D graphics.
+
+* [./packages/mml-web](./packages/mml-web) - `@mml-io/mml-web` - MML Library that handles MML elements and attributes
+* [./packages/mml-web-client](./packages/mml-web-client) - `@mml-io/mml-web-client` - Web MML Client (standalone script / example)
+* [./packages/mml-web-threejs](./packages/mml-web-threejs) - `@mml-io/mml-web-threejs` - Graphics Adapter for MML to THREE.js
+* [./packages/mml-web-threejs-standalone](./packages/mml-web-threejs-standalone) - `@mml-io/mml-web-threejs-standalone` - THREE.js app for viewing MML documents in a web browser
+* [./packages/mml-web-playcanvas](./packages/mml-web-playcanvas) - `@mml-io/mml-web-playcanvas` - Graphics Adapter for MML to PlayCanvas
+* [./packages/mml-web-playcanvas-standalone](./packages/mml-web-playcanvas-standalone) - `@mml-io/mml-web-playcanvas-standalone` - PlayCanvas app for viewing MML documents in a web browser
 
 ## Networking (Networked DOM)
 MML is based on a set of libraries (built expressly for MML) called "Networked DOM".
 
+Networked DOM allows running a HTML document including script tags on a server and exposing it via a websocket which allows multiple users to interact with the same instance of the document at the same time.
+
 The server and network components necessary to support the multi-user mode are independent of the MML additions to HTML (and can be used with regular 2D HTML).
 
 * Networked DOM
-  * [./packages/networked-dom-web](./packages/networked-dom-web) - Web Networked DOM Library
-  * [./packages/networked-dom-web-client](./packages/networked-dom-web-client) - Web Networked DOM Client
-  * [./packages/networked-dom-web-runner](./packages/networked-dom-web-runner) - Web Networked DOM Runner (for running Networked DOM documents in a web browser rather than a server)
-  * [./packages/networked-dom-protocol](./packages/networked-dom-protocol) - Networked DOM WebSocket Protocol TypeScript Definition
-  * [./packages/observable-dom-common](./packages/observable-dom-common) - Observable DOM Common
-  * [./packages/observable-dom](./packages/observable-dom) - Observable DOM (JSDOM Execution) Library
-  * [./packages/networked-dom-document](./packages/networked-dom-document) - Networked DOM Document Library
+  * [./packages/mml-web-runner](./packages/mml-web-runner) - `@mml-io/mml-web-runner` - Web Runner (for running MML documents in a web browser rather than a server)
+  * [./packages/networked-dom-server](./packages/networked-dom-server) - `@mml-io/networked-dom-server` - Networked DOM Library for running documents on a Node.JS server
+  * [./packages/networked-dom-web](./packages/networked-dom-web) - `@mml-io/networked-dom-web` - Web Networked DOM Library (WebSocket client for Networked DOM)
+  * [./packages/networked-dom-web-client](./packages/networked-dom-web-client) - `@mml-io/networked-dom-web-client` - Web Networked DOM Client (Standalone script / example)
+  * [./packages/networked-dom-web-runner](./packages/networked-dom-web-runner) - `@mml-io/networked-dom-web-runner` - Web Networked DOM Runner (for running Networked DOM documents in a web browser rather than a server)
+  * [./packages/networked-dom-protocol](./packages/networked-dom-protocol) - `@mml-io/networked-dom-protocol` - Networked DOM WebSocket Protocol TypeScript Definition
+  * [./packages/observable-dom-common](./packages/observable-dom-common) - `@mml-io/observable-dom-common` - Observable DOM Common
+  * [./packages/observable-dom](./packages/observable-dom) - `@mml-io/observable-dom` - Observable DOM (JSDOM Execution) Library
+  * [./packages/networked-dom-document](./packages/networked-dom-document) - `@mml-io/networked-dom-document` - Networked DOM Document Library
+
+## MML Viewer
+MML Viewer is a standalone app that can be used to view MML documents in a web browser.
+
+It is available at [https://viewer.mml.io/main/v1/](https://viewer.mml.io/main/v1/).
+
+* [./packages/mml-viewer](./packages/mml-viewer) - `@mml-io/mml-viewer` - MML Viewer
 
 # Usage of this repo
 

e2e-tests/package.json

@@ -19,7 +19,7 @@
     "express": "4.21.0",
     "express-ws": "5.0.2",
     "jest-image-snapshot": "6.4.0",
-    "networked-dom-server": "^0.18.1",
+    "@mml-io/networked-dom-server": "^0.18.1",
     "puppeteer": "22.6.5",
     "wait-on": "8.0.1",
     "ws": "8.18.0"

e2e-tests/setup.ts

@@ -13,6 +13,7 @@ if (process.env.HEADLESS === "true") {
 
 module.exports = async function () {
   const browser = await puppeteer.launch({
+    args: ["--no-sandbox"],
     headless: headless ? "shell" : false,
   });
   // store the browser instance so we can teardown it later

e2e-tests/src/click-position-test.html

@@ -9,6 +9,7 @@
 
   myPlane.addEventListener("click", (e) => {
     toggle = !toggle;
-    myLabel.setAttribute("content", JSON.stringify(e.detail.position));
+    const {x, y, z} = e.detail.position;
+    myLabel.setAttribute("content", JSON.stringify({x: x.toFixed(3),y: y.toFixed(3),z: z.toFixed(3)}));
   });
 </script>

e2e-tests/src/index.ts

@@ -1,10 +1,11 @@
 import { Stats } from "node:fs";
+import * as QueryString from "node:querystring";
 
+import { EditableNetworkedDOM, LocalObservableDOMFactory } from "@mml-io/networked-dom-server";
 import * as chokidar from "chokidar";
 import express, { Request, static as expressStatic } from "express";
 import enableWs from "express-ws";
 import * as fs from "fs";
-import { EditableNetworkedDOM, LocalObservableDOMFactory } from "networked-dom-server";
 import * as path from "path";
 import * as url from "url";
 
@@ -102,14 +103,14 @@ app.ws("/:pathName", (ws, req) => {
 app.get("/:documentPath/", (req, res) => {
   const html = `<html><script src="${req.secure ? "https" : "http"}://${req.get(
     "host",
-  )}/client/index.js?defineGlobals=true&websocketUrl=${getWebsocketUrl(req)}"></script></html>`;
+  )}/client/index.js?defineGlobals=true&url=${getWebsocketUrl(req)}"></script></html>`;
 
   res.send(html);
 });
 
 app.use(
   "/client/",
-  expressStatic(path.resolve(dirname, "../../node_modules/mml-web-client/build/")),
+  expressStatic(path.resolve(dirname, "../../node_modules/@mml-io/mml-web-client/build/")),
 );
 
 app.get("/:documentPath/reset", (req, res) => {
@@ -122,8 +123,10 @@ app.get("/:documentPath/reset", (req, res) => {
     return;
   }
 
+  const queryString = QueryString.encode(req.query as QueryString.ParsedUrlQueryInput);
+
   currentDocument.reload();
-  res.redirect("/" + documentPath);
+  res.redirect("/" + documentPath + "?" + queryString);
 });
 
 console.log("Serving on port:", port);

e2e-tests/src/m-frame-bounds-load-range-test.html

@@ -13,6 +13,7 @@
     unload-range="2"
     y="1"
     src="/assets/static-mml.html"
+    debug="true"
 ></m-frame>
 
 <m-label width="1.5" content="into range" id="set-into-range-label" color="red" x="-2" z="5" y="6.5"></m-label>

e2e-tests/src/m-interaction-test.html

@@ -41,6 +41,6 @@
   let interactionToggle = false;
   myInteraction.addEventListener("interact", () => {
     interactionToggle = !interactionToggle;
-    myPlane.setAttribute("color", interactionToggle ? "orange" : originalColor);
+    myPlane.setAttribute("color", interactionToggle ? "blue" : originalColor);
   });
 </script>

e2e-tests/src/m-label-emissive-test.html

@@ -73,4 +73,4 @@
   font-size="85"
   alignment="center"
   emissive="5"
-></m-label>
+></m-label>

e2e-tests/src/m-label-test.html

@@ -3,10 +3,11 @@
 <m-label
   content="Hello, World!"
   y="4"
+  z="4"
   width="10"
   height="5"
-  color="red"
-  font-color="white"
+  color="rgba(255,0,0,0.5)"
+  font-color="rgba(0,0,255,0.5)"
   font-size="200"
   alignment="center"
 ></m-label>

e2e-tests/src/m-model-socket-test.html

@@ -8,7 +8,7 @@
   anim="/assets/idle.glb" src="/assets/Body.glb"
   anim-start-time="-2000" anim-pause-time="0"
 >
-  <m-cube id="socketed-cube" x="0" socket="head" sx="0.25" sy="0.25" sz="0.25"></m-cube>
+  <m-cube id="socketed-cube" x="0" color="purple" socket="head" sx="0.25" sy="0.25" sz="0.25"></m-cube>
 </m-character>
 
 <script>