[RFC] Proposed Upgrade of Editor to ES6 build

[marklundin]

Proposed Upgrade of Editor to ES6 build

ESM Script has now shipped #5764. Users should be able to use import playcanvas in their scripts like;

import { Vec3, Color } from 'playcanvas'

However the launch page and exported projects both use the older ES5/UMD build which cannot be imported using ES6 import syntax. Therefore we need to upgrade the editor to use the ES6 build in a way that is backwardly compatible with existing projects.

The PC global

One of the main distinctions is that the UMD build exports a global pc object namespace whereas the ES6 build does not. All existing project scripts depend upon this, and so it cannot be removed.

Proposed Upgrade

From :

<script src="{{ umd_engine_url }}"">

To:

<script type='import-map'>
  {
    "imports": {
      "playcanvas": "{{ ES6_engine_url }}"
    }
  }
</script>
<script type='module'>
  import * as pc from 'playcanvas';
  window.pc = { ...pc }; // re-export as mutable object 
</script>
<script nomodule src="{{ umd_engine_url }}"">

Note: There is currently an issue with the engine build that prevents the UMD build parsing in non older browsers #6011.*

Should the UMD build deprecated?

As of Feb 24, ES modules stands at 97% support, and our UMD build adds less than 0.1% (TBC) more users. Legacy Scripts have been deprecated in projects.

• Does this additional reach warrant the overhead of maintaining an extra build target?
• What would be a reasonable timeframe to deprecate?

Provide clear direction to developers

Even if we do continue to support an ES5 workflow, we should provide a consistent and ciherent recommended approach for using scripts

We Need Your Feedback

Your insights are crucial to ensure a smooth transition. Specifically, we're looking for feedback on:

• Any potential challenges or concerns with the upgrade process.
• Experiences with targeting ES5 devices and how the proposed bundling step may affect your workflow.

Please share your thoughts directly in this thread. Your input will help us cover all bases and support everyone through these changes.

[LeXXik]

Let's say I make a library MyLibrary that creates a new component system in a given application instance. I would want it to eventually work for both engine-only and Editor users. Could you please guide me through the path I would expect the users take to import my library and my bundling? Say, I don't support ES5 devices, would this be the flow:

Editor user creates an .mjs script and imports my library:

// say my library is an asset script called `library.min.js` and inits via a promise

import { init } from 'library.min.js'; // or should it use a lib name instead of filename?

class MyClass {
    async initialize() {
        await init(this.app);
    }
}

Lets say my library is not using any of the PlayCanvas engine systems, but it wants to instantiate some defaults, like vectors. Today, it would be this way, if the lib is run in Launcher:

function(a = pc.Vec3.ZERO) {}

This assumes there is a pc namespace registered on window that allows me to get access to the vector constructor at runtime. If I remove the namespace, I would probably have to do:

import { Vec3 } from 'playcanvas';
function (a = Vec3.ZERO) {}

But that will import the class into the library, which will increase its size. Or is there another way?

[marklundin]

If your library is publicly available on npm or github, there will be import-map style imports. Install it and import as follows;

import { init } from '@my-utils/library'; // doesn't need to be pre bundled or minified

class MyClass {
    async initialize() {
        await init(this.app);
    }
}

If your lib also depends upon playcanvas (likely) then as long as you're not pre-bundling, the import will also resolve to the engine. In practice we'll probably want to ensure semver ranges etc.

[yaustar]

How will this affect existing PlayCanvas editor projects? Will they all need to be updated when this is deprecated?

[marklundin]

We should be able to migrate to the ES6 build without any impact to projects. If we do eventually remove the pc object, it will have a long timeline (TBD) with adequate warnings and notice.

[LeXXik]

Would we be able to define our own importmap entry? We'd like to export all related SDK classes in a single file and refer to it in importmaps. Then all game scripts can use some alias, like

import { Animation } from 'SDK';

[marklundin]

Yep we have a ticket for this playcanvas/editor#1108