Examples Rework

[kpal81xd]

This issue is for the discussion of reworking the examples to make the development and experimentation experience easier. Stage 1 of the refactor and cleanup has already been completed and merged in #6005.

Stage 1

• [x] Fix linting issues
• [x] Speed up thumbnail generation
• [x] Maintain state for collapsing on SideBar

Stage 2

• [x] Remove wrapping example and controls functions
• [x] Support for imports
• [x] Remove abstraction to allow for user development outside of examples playground

Stage 3

• [x] Fix controls taking up the entire screen on mobile #3991
• [ ] Better interfacing of state between controls UI and example context (Currently needs to expose functions to global context)
• [ ] Replace jsx wrapper for controls to use jsx components (Will probably require PCUI rebuild/state optimisation)

[mvaligursky]

• Abstract app configuration into separate file (boilerplate code)

This was considered during last refactoring, but at the end keeping all / as much code required to run the example in the same file was decided is a good way to show people what needs to be done to get an app running, as examples are in a way tutorials too. Kind of self contained examples, similar to a completely self-contained html files examples used to be a long time ago.

[mvaligursky]

Love the idea of imports, and would appreciate some more details on what you're hoping to do this, what the end goal is.

Few other points could do with more information as well to make it more clear what the goal here is.

[marklundin]

It would be great if we can remove the direct dependancy on the node_modules of the engine, and just symlink it directly using npm workspace which doesn't require building the parent engine first

[mvaligursky]

The examples no longer need to build the engine first. Just npm run develop in the examples, that builds the engine it needs.

[marklundin]

But npm run build in example doesn't work unless you build the engine first.

[kungfooman]

IIRC the only missing thing is the engine playcanvas.d.ts generation for Monaco examples editor to make /examples/ fully standalone, which would be nice to add here too

[Maksims]

Currently the example code, shows the core of the example stuff, but at the same time, it is not easily replicable from the scratch. Maybe it is not related to examples, but amount of build processes, the wrapping, lack of debugging and proper error handling - all this moves away from users being able to take an example, and expand from it.

In contrast, three.js example - is a html file, with everything in it, you can just take it and experiment with it, without need of complex build processes, understanding of project structure, etc.

[willeastcott]

The PCUI examples browser is like that:

https://github.com/playcanvas/pcui/tree/main/examples

[kungfooman]

I just wanted to update my RTI pull request and running into regressions:

• ENGINE_PATH doesn't seem to work any longer
• Loading an UMD build doesn't seem to work any longer
• Edits in examples/scripts/standalone-html.mjs are not reflected during a npm run develop session

Examples README.md needs a little change:

https://github.com/playcanvas/engine/blob/d8072265a79b57f9e773eea400140de555476f9f/examples/README.md?plain=1#L24-L28

(build/playcanvas.mjs is now our bundled file)

[kpal81xd]

I just wanted to update my RTI pull request and running into regressions:

• ENGINE_PATH doesn't seem to work any longer
• Loading an UMD build doesn't seem to work any longer
• Edits in examples/scripts/standalone-html.mjs are not reflected during a npm run develop session

Examples README.md needs a little change:

https://github.com/playcanvas/engine/blob/d8072265a79b57f9e773eea400140de555476f9f/examples/README.md?plain=1#L24-L28

(build/playcanvas.mjs is now our bundled file)

• ENGINE_PATH seems to work fine for me so long as its a ESM build of the engine (UMD is not supported anymore)
• Yea the standalone-html.mjs only triggers a rollup rebuild, standalone files are generated via a script so this needs to be changes

[kungfooman]

• ENGINE_PATH seems to work fine for me so long as its a ESM build of the engine (UMD is not supported anymore)

Thank you for the feedback @kpal81xd! I still can't get it to work on my machine, can you test this?

cd examples
npm run clean
ENGINE_PATH=../build/playcanvas.mjs npm run build

Then I get this error:

[marklundin]

Not sure if it has any effect @kungfooman @kpal81xd, but would the new ESM build have changed this? Previously ../build/playcanvas.mjs was a directory and now it's the bundled version?

Unrelated (more out of curiosity) but can ENGINE_PATH now point directly to src?

[kungfooman]

I don't think it's related to the bundle/dir rewrite, it should still work (I edited ENGINE_PATH using [TAB]-completion to make sure the path is right)

Unrelated (more out of curiosity) but can ENGINE_PATH now point directly to src?

(that worked through my refactor to cut down on build time for quick/explorative coding, unsure about current situation because of the error I get)

[kungfooman]

Standalone example path's also seem to be broken, repro:

• npm run develop
• open http://localhost:5000/iframe/graphics_lights-baked-a-o.html

It used to work: https://pc.runtimetypeinspector.org/iframe/Graphics_LightsBakedAO.html

[kpal81xd]

• ENGINE_PATH seems to work fine for me so long as its a ESM build of the engine (UMD is not supported anymore)

Thank you for the feedback @kpal81xd! I still can't get it to work on my machine, can you test this?

cd examples
npm run clean
ENGINE_PATH=../build/playcanvas.mjs npm run build

Then I get this error:

Ahh I see so ENGINE_PATH expected an unpacked version of the engine (i.e. a folder) with the entry point being index.js. I should be able to support both these however in the build script