Examples Overhaul

examples/.gitignore

@@ -0,0 +1,5 @@
+# Prettier config
+.prettierrc
+
+# Cache directory
+cache

examples/README.md

@@ -33,64 +33,59 @@ Or directly from the source:
 ENGINE_PATH=../src/index.js npm run develop
 ```
 
-To create the side bar thumbnails run the following script:
-```
-npm run build:thumbnails
-```
-
 Please note that the examples app requires a built version of the engine to be present in the engine repo within the `../build` folder. If you haven't already done so, run `npm install` followed by `npm run build` in the engine repo.
 
 As Monaco is supporting IntelliSense via type definitions files, you will also need to build the type definitions in the engine repo with `npm run build:types`.
 
 ## Creating an example
 
-The available examples are written as classes in JavaScript under the paths `./src/examples/\<categoryName\>/\<exampleName>.mjs.
-To create a new example you can copy any of the existing examples as a template and update its path.
+The available examples are written as classes in JavaScript under the paths `./src/examples/<category>/<exampleName>`.
+To create a new example you can copy any of the existing examples as a template.
 
-Each example can implement two methods to define its functionality:
+Each example consists of three modules to define its behavior:
 
-### `example` function
+### `example.mjs`
 
 ```js
 import * as pc from 'playcanvas';
-/**
- * @param {import('../../../app/example.mjs').ExampleOptions} options - The example options.
- * @returns {Promise<pc.AppBase>} The example application.
- */
-async function example({ canvas, deviceType, assetPath, scriptsPath }) {
-    const app = new pc.Application(canvas, {});
+
+const canvas = document.getElementById('application-canvas');
+if (!(canvas instanceof HTMLCanvasElement)) {
+    throw new Error('No canvas found');
 }
+
+const app = new pc.Application(canvas, {});
+
+export { app };
 ```
 
-This is the only function that's required to run an example. The code defined in this function is executed each time the example play button is pressed. It takes the example's canvas element from the options and usually begins by creating a new PlayCanvas `Application` or `AppBase` using that canvas.
+This is the only file that's required to run an example. The code defined in this function is executed each time the example play button is pressed. It takes the example's canvas element from the DOM and usually begins by creating a new PlayCanvas `Application` or `AppBase` using that canvas.
 
 You can load external scripts into an example using the `loadES5` function as follows:
 
 ```js
-import { loadES5 } from '../../loadES5.mjs';
-async function example({ canvas, deviceType, files, assetPath, glslangPath, twgslPath }) {
-    const CORE  = await loadES5('https://cdn.jsdelivr.net/npm/@loaders.gl/core@2.3.6/dist/dist.min.js');
-    const DRACO = await loadES5('https://cdn.jsdelivr.net/npm/@loaders.gl/draco@2.3.6/dist/dist.min.js');
-    console.log({ CORE, DRACO })
-}
+import { loadES5 } from '@examples/utils';
+
+const CORE  = await loadES5('https://cdn.jsdelivr.net/npm/@loaders.gl/core@2.3.6/dist/dist.min.js');
+const DRACO = await loadES5('https://cdn.jsdelivr.net/npm/@loaders.gl/draco@2.3.6/dist/dist.min.js');
 ```
 
-However, depending on external URL's is maybe not what you want as it breaks your examples once your internet connection is gone - you can simply install a NPM package and use it instead aswell:
+However, depending on external URL's is maybe not what you want as it breaks your examples once your internet connection is gone - you can simply import modules directly as follows:
 
 ```js
-import * as TWEEN from '@tweenjs/tween.js';
+import confetti from "https://esm.sh/canvas-confetti@1.6.0"
 ```
 
-### `controls` function
+### `controls.mjs`
 
-This function allows you to define a set of PCUI based interface which can be used to display stats from your example or provide users with a way of controlling the example.
+This file allows you to define a set of PCUI based interface which can be used to display stats from your example or provide users with a way of controlling the example.
 
 ```js
 /**
- * @param {import('../../app/example.mjs').ControlOptions} options - The options.
+ * @param {import('../../../app/Example.mjs').ControlOptions} options - The options.
  * @returns {JSX.Element} The returned JSX Element.
  */
-function controls({ observer, ReactPCUI, React, jsx, fragment }) {
+export function controls({ observer, ReactPCUI, React, jsx, fragment }) {
     const { Button } = ReactPCUI;
     return fragment(
         jsx(Button, {
@@ -105,13 +100,33 @@ function controls({ observer, ReactPCUI, React, jsx, fragment }) {
 
 The controls function takes a [pcui observer](https://playcanvas.github.io/pcui/data-binding/using-observers/) as its parameter and returns a set of PCUI components. Check this [link](https://playcanvas.github.io/pcui/examples/todo/) for an example of how to create and use PCUI.
 
-The data observer used in the `controls` function will be made available as a property in the example function:
+The data observer used in the `controls` function will be made available as an import `@examples/observer` to use in the example file:
 
 ```js
-example({ canvas, assets, data }) {
-    const app = new pc.Application(canvas, {});
-    console.log(data.get('flash'));
-}
+import { data } from '@examples/observer';
+
+console.log(data.get('flash'));
+```
+
+### `config.mjs`
+
+This file allows you to define the default configuration for your examples as well as overrides to particular settings such as `deviceType` and additional files (e.g. vertex and fragment shaders). Check the config options `ExampleConfig` in `types.mjs` file.
+
+```js
+/**
+ * @type {import('../../../../types.mjs').ExampleConfig}
+ */
+export default {
+    WEBGPU_ENABLED: true,
+    FILES: {
+        "shader.vert": /* glsl */`
+            // vertex shader
+        `
+        "shader.frag": /* glsl */`
+            // fragment shader
+        `
+    }
+};
 ```
 
 ### Testing your example
@@ -122,6 +137,15 @@ You can view the full collection of example iframes by visiting [http://localhos
 ### Debug and performance engine development
 By default, the examples app uses the local version of the playcanvas engine located at `../build/playcanvas.js`. If you'd like to test the examples browser with the debug or performance versions of the engine instead, you can run `npm run watch:debug` or `npm run watch:profiler` commands.
 
+## Example Modules
+
+The example script allows you to import examples only modules that interact with the environment such as the device selector and controls. These are listed below:
+
+- `@examples/config` - The example config defined in `./src/examples/<category>/<exampleName>/config.mjs`.
+- `@examples/utils` - Contains utilities functions such as `loadES5`. The full list of functions can be found in `./iframe/utils.mjs`.
+- `@examples/observer` - The observer object `data`.
+- `@examples/files` - The reatime file contents of all files used in the example (includes `FILES` property from `config.mjs`).
+
 ## Deployment
 
 1) **Build the latest engine** by running the following in the `/engine` directory:
@@ -138,7 +162,7 @@ npm run build
 npm run serve
 ```
 
-3) **Generate thumbnails** This step will create the thumbnails directory for the browser and may take a while depending on the number of new examples or if this is first time it has been run locally.
+3) **Generate thumbnails (Case-by-case basis)** This step will create the thumbnails directory for the browser. This only needs to be run if the examples thumbnails are updated or new examples are added.
 ```
 npm run build:thumbnails
 ```