[RFC] ES Modules

[marklundin]

ES Modules

This is a working doc that collates the discussion around ES Modules from #4767, outlines user pain points, current architectural roadblocks, and offers proposed solutions and roadmap. It is not intended to outline implementation detail. We want to gather feedback and involve the wider PlayCanvas community as we start to roll this out.

Motivation

There are a number of pain points and issues with the current scripting system, these can be roughly outlined as follows:

• Script syntax is outmoded. This is not just cosmetic, modern tools are important to users
• Users want to use modern tools like TypeScript and bundlers
• Ecosystem. Users cannot leverage existing large JS ecosystems such as NPM/ESM.sh etc
• Dependency hell. Users cannot easily structure code in their projects, and must manually manage dependencies
• Scripts cannot run in a Node env which is an issue for testing. (May also be an issue with other headless environments like Bun/Deno)
• Intellisense. Attributes do not work with Intellisense #4767

var MyScript = pc.createScript('myScript');

MyScript.attritbues.add('aNumber', { name: 'String', default: 10, min: 0, max: 199, ... });

// initialize code called once per entity
MyScript.prototype.initialize = function() {
};

// update code called every frame
MyScript.prototype.update = function(dt) {
};

In addition, the above system can also result in a number of more subtle, less obvious issues:

• Developers often directly load in multiple large UMD bundles which can often contain duplicate and redundant copies of the same dependency or library
• Scripts are defined in a global scope which can make collisions more likely as projects get larger

It's also worth noting, what does work well in the current implementation...

• Scripts provide a HMR style method for swapping state between new instances. For those who use this, this is super valuable
• They provide an event system when attributes change. Again, not widely used, but heavily relied upon by those who do use them.

Proposal

Upgrade the PlayCanvas platform to natively support ES Modules, TypeScript and modern tools Fundamentally this is about improving both the developer and end user experience. Adopt ES Modules natively which opens users up to a wider JS ecosystem (NPM/esm.sh etc) allowing them to create richer, more complex projects. Adding support for modern tools like TypeScript/JSX to help devs work in a way more aligned with their expectations.

Requirements

At the very least users should be able to...

• import NPM/CDN esm module into their projects
• import local modules from their asset registry
• Use TypeScript
• Bundle code, including tree-shaking, minification, optimizing etc etc
• See Intellisense suggestions correctly for attributes etc

However it's important that in doing so we do not compromise...

• The fast iterative PlayCanvas developer experience that people expect. Do not add any friction to the process
• Not add any overhead/cost to the end user experience. Ideally we should improve upon this (faster perceived load times)
• Not impact any secondary tooling like playcanvas-sync
• Maintain support for Scripts 2.0

New ESM Script API

Retain the semantics behind existing lifecycle methods in line with Script 2.0 functionality. Keep the api simple, do not include any unnecessary overhead. New Lifecycle methods can be added on use case basis.

export const attributes = {
    aNumber: { name: 'String', default: 10, min: 0, max: 199, ... }
}

class MyModule {

    initialize(){}
    update(dt){}
    destroy(){}
    swap(oldInstance){}

}

export default MyModule

• Familiar API to existing scripts
• Clear transparent Class based syntax
• Additional functionality (events etc) can be optionally be provided via a base Class
• Attribute definition is isolated from the class definition, it simply describes metadata for class props that are exposed to the editor. This metadata is not required at runtime. Attribute code can be shaken out.
• One module exports one script
• Attributes can be statically analyzed. An error in code, should not prevent attributes being parsed
• Forward compatibility with TS

Considerations

• To make Intellisense work requires 're-declaring' an attribute in the class definition. There a more exotic ways this could be done, eg define attribute metadata using JSDoc/TSDoc which might lead to a cleaner syntax and less duplication, however this is outside of scope of this PR and can be investigated separately. For now the proposed approach does not litter the class with unnecessary prop metadata, and is compatible with Intellisense but at the cost of some redundancy.

Architectural concerns

In order to move forward, there are a number of practical architectural points that need addressing;

Asset paths - See #4767

The Asset registry is presented as a filesystem and developers would expect to import local modules using paths that correlate to the asset registry import * from './dir/module', however assets paths are currently as follows:

/files/assets/${filepath}?asset_id&branch_id, this is because they are stored in S3 as ${config.aws.s3.prefix + asset_id}/${asset.revision}/${filepath} and the asset_id is needed.

The asset_id is the part of the DB index, but this is not transparent to the user. This also means that 2 assets can have the same name in the asset registry because they have different id's. This is confusing from a UX perspective but there may be legitimate reasons for this. Ideally we could have a the following:

${project_id}/{filepath}

To do this we would need a KV DB that points ${project_id}/{filepath} => asset_id An edge function with local cache would look up the asset_id and return the S3 object. This needs further discussion with.

Discussion points

• Should this new system only apply to modules. Should it also extend to other assets?
• Should this only work for new assets or existing ones too?
• This would potentially mean 2 routes/paths to access the same asset. Is this an issue?
• What are the lamda@edge costs?

Script parsing

Monaco ships with the TypeScript Language service which could be used to statically analyze script attributes without actually running code. It’s not definite that we need to use this, but if we do allow TS eventually, this this will help.

Bundling

Bundling will be separated out as it's own RFC. As bundling is not mandatory it will be an opt-in feature.

PC global object

Currently, the pc object is exposed as a global, which is an issue for node.js. It was originally necessary as the pc.createScript method was required to register scripts with the Script Registry. It is likely that with ES Modules we do not need a Registry.

Importing PlayCanvas

Users will want to import PlayCanvas specific code ie. import { Entity } from 'playcanvas', so we'll need to ensure the correct version is used. Also, if a submodule depends upon a different version of 'playcanvas' this may cause multiple playcanvas libs being imported. It's possible that we can catch these at author time using an author-time module resolution step, that checks the dependency graph and flags issues to the user.

ES Modules as a new Component

The current script logic is tightly integrated with the legacy scripts system which has caused a lot of run time checks as they share a lot of the same code paths. Ideally, we create a new 'ES Module' component which is distinct from the scripts. This separates out a lot of the internal code paths, and makes it much easier to support both concurrently, and when scrips 2.0 and legacy scripts is eventually sunset, the code is more isolated and easier to do without causing issues.

Roadmap

We will need to progressively rollout support for ES Modules which can be done in various stages. We'll also need to support the existing Scripting 2.0 system until all work is complete. (Editor is constantly bumped to a new engine version, which means, engine must support Scripts 2.0 forever)

• Phase 1 - ES Modules (CDN only, no local modules)
  • Implement basic ES Module component system ESM Scripts #5764
  • Add support for launch.playcanvas.com and other environments
  • Implement ES Component support in editor + any design considerations
• Phase 2 - Local modules. Work involved to map paths correctly and use local modules
  • Add a KV store for to map semantic paths to S3 paths
  • Update pipeline.asset.upload function to write to KV store on upload for modules/scripts
  • Add a lamda@edge function on routes which checks permissions, looks up the asset id and returns the object
• Phase 3 - Bundling (TBD)
• Phase 4 - TypeScript (TBD)

[marklundin]

Scripts meeting - 19/10

Few discussion points:

1. How can we support Engine only projects? Do we need an ES script registry?
2. Swap method is not widely used, but we should not remove this functionality for those that heavily depend upon it.
3. Users also need the event system. Does this require a base class? Are there other alternatives?
4. What happens if ES Script Instance imports another ES Script Instance?

Outcomes

• to implement implement both project and engine based test so we can test the all use cases

[LeXXik]

Nice, looking forward importing ES modules. Even from CDN is already good. This will allow us to work with our libs more naturally, without having to dance around the table first.

[marklundin]

Thanks @LeXXik Yep the hope is that even with initial support for external CDN's we can start testing any friction points and edge cases.

[slimbuck]

Few notes:

• A script registry will be needed when loading scenes because scene data is just a json object with hierarchy of entities and components and their respective component/attribute data. For an entity with attached script, scene data will include:
  • an entity with esm-script component
  • an identifier indicating which script is attached (id is presumably the script name/id/path?)
  • the attribute data used to initialise the esm-script instance attributes
• It might be useful to have a module version that replicates 'pc' namespace to help users migrate from scripts 2.0

[marklundin]

The component data should ideally include a unique path used directly to import the module. This wouldn't require a script registry.

{
  modules: [{
    moduleSpecifier : string, // path to module
    attributes: Object
  }]
}

In practice however, this might be challenging as we currently allow assets to share identical paths. So for now, the moduleSpecifier can be an asset id, which is unique and aligns with how other components reference items in the registry.

IMHO I'd prefer not to rely on a user defined 'id' or 'name' in the Class definition itself, as it's often been a source of confusion and it's easy to collide with other scripts.

[slimbuck]

Wouldn't this assume all modules are dynamically loaded?

If a project is bundled (say), how do we get the module object from path specifier?

[marklundin]

If a module is bundled, we shouldn't necessarily need to rewrite the asset.file path in the scene json. As long as we have a fixed entry point for the bundle eg. preload.modules.js we should be able to use the module specifier to import from the bundle.

[slimbuck]

Ok so bundle will include an import map for bundled esm-script modules?

Presumably this means the esm-script must export the module as default (and be imported as default)?

[marklundin]

Yep, so the bundle would re-export all modules, then importing in a bundled context would resolve to the following

 import('default.bundle.js).then((bundleExports) => bundleExports[moduleSpecifier] );

This logic should be wrapped in an internal pcImport which is used to transparently resolve to a bundled/non-bundled context

[Maksims]

Other thing to take in account is different case scenarios of how developers are loading scripts:

1. All concatenated to ensure a single network request
2. Some concatenated for preloading, some loaded later.
3. Ability to load scripts from bundles.
4. Abilty to load script and unload a script at any point.

Also regarding running scripts on the backend using node.js, we've used vm.runInNewContext in production successfully. So it is possible to run and even use hot-swap on the backend.

[marklundin]

We'll handle module bundling as a separate piece of work, as it should be really be opt-in only. Suffice to say it will handle concatenation and different entry points etc. Asset bundles will also need to be handled separately

[Maksims]

Lack of concatenation/bundling will not allow this to be used in most commercial projects.

[marklundin]

Bundling will definitely be a feature. It will just be optional, similar to how it is now.

[Maksims]

It is pretty much a default for everyone now.
Deploying commercially well performant projects is mandatory to minimize number of network requests. Even relatively small projects can have at least dozens of scripts.

Concatenation was an essential part for scripting very early in PlayCanvas development.

[marklundin]

Yep, it's more just how to plan and separate out the work really. Bundling will happen, but will take a bit of planning. However it shouldn't block us getting initial support for script ES modules in the engine.