[RFC] Scripts 3.0

[marklundin]

ESM Scripts

Important

This document is being continually updated to reflect new design decisions

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.

Table of Contents

• Background
• Requirements
• Proposal
  • ESM Script API
  • Asset Path Mapping
  • Attribute Parsing
  • Bundling
  • PC global
  • Importing PlayCanvas
  • Dependancy Management
  • Script Component

Project Status

• Roadmap
• Kanban
• Backlog

Background #

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

• Outdated coding style. 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 wider JS ecosystems (NPM)
• Dependency issues Users cannot easily structure code in their projects, and must manually manage dependencies
• Environments 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) 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. Improve the overall DX!

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

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 class MyModule extends Script {
   
   /**
    * @attribute
    * @range [0, 199]
    */ 
    aNumber = 10

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

}

• Familiar API to existing scripts
• Clear transparent Class based syntax
• Additional functionality (events etc) can be optionally be provided via a base Class
• JSDoc Script Attributes Attributes are defined on class attributes using JSDoc tags. See [RFC] JSDoc Script Attributes editor#1148
• Multiple Scripts can be exported per module
• 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. This has now been implemented in [RFC] JSDoc Script Attributes editor#1148.

Asset path mapping #

In an earlier revision of this doc, we outlined the issues around resolving module paths due to how assets are stored and referenced in the back-end. Essentially the asset registry represents a virtual file system

• /scripts/utils/math.mjs - This is the virtual path presented in the asset registry
• files/assets/math.mjs?id=123- This the real url that resolves the asset

This presents a problem when importing relative modules from within the asset registry. We need a way to map an import path of /scripts/utils/math.mjs => files/assets/math.mjs?id=123. The original approach discussed involved creating a backend service that could map these paths at runtime, however a more straightforward approach is to do this on the client side at the network layer via a Service Worker. The Service Worker would intercept any fetch request at runtime (including static and dynamic imports) and resolve the module paths to the real asset-backed URL's. At build time these import paths are remapped to their actual file paths, so no SW is needed for built apps.

See https://github.com/playcanvas/editor-ui/pull/221

Why import maps are not suitable

Whilst this sounds like a plausible candidate for Import Maps, it requires that the imports are known ahead-of-time, as import maps cannot be dynamically updated. This would break any hot-reloading features if files were added, removed or renamed.

A Service Worker based solution, provides a clean solution that doesn't require any modification of the engine whilst allowing for a dynamic and changing file system.

Discussion points

• Should this new system only apply to modules. Can it be extend to other assets?
• This would potentially mean 2 routes/paths to access the same asset. Is this an issue?
• What are the lamda@edge costs? Path resolution is now a local operation

Attribute parsing #

The initial design considered using TypeScript from within Monaco to parse script attributes, however this is not public api. Instead we now ship a version of the TypeScript compiler within a webworker which is able to correctly parse attributes. There is a separate RFC discussing the attribute parsing system playcanvas/editor#1148

See https://github.com/playcanvas/editor-ui/pull/264 for more information

Bundling

Existing scripts are concatenated into a single file. At the very least, ESM Scripts should provide a similar features set using a modern bundler like Rollup. This can bundle, minify and code-split and opens the door for more complex, richer set of bundling feartures/

See playcanvas/editor#1109

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.

See playcanvas/editor#1108, playcanvas/editor#1108

Dependancy Management

User will expect to import external 3rd party dependencies import _ from 'lodash'. By allowing users to manually search for and "install" dependencies from NPM, we can provide better DX including importing any types into Monaco to help Intellisense

See https://github.com/playcanvas/editor-ui/pull/254

ES Modules as an ~~new~ existing Component a href="#script-component" id="script-component">

After lengthy discussion it was decided that a new Script Component System was unnecessary and the existing component system could be used to support ESM Scripts. Doing this allows legacy scripts to be used interchangeably with ESM Scripts within the same a component. This allows users to gradually migrate to the new scripting system and preserves the execution order between both script types.

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)

See the Product Roadmap for a more complete, up-to-date overview

[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.