ESM script base class

[marklundin]

This PR proposes a new Script base class for ESM Scripts. Attributes are declared via jsdoc tags as opposed to Script.attributes.add(). ScriptType class persists for legacy support. The new Script base class:

• does not use the ScriptAttribtues class
• does not override class members with getters/setters. Fixing [RFC] JSDoc Script Attributes editor#1148
• is compatible with JSDoc style attributes
• is assigned any attributes based upon the json schema in it's corresponding asset

API Changes

• New ESM Script Class
  A new minimal base. Attributes are declared via jsdoc tags. Runtime attributes via Script.attributes.add() is removed. Fixes ScriptType does not support class syntax #6316

• assignRawToValue - New method that takes a script instance, a schema and value and assigns a new value on the script instance`

• ScriptRegistry.addSchema/getSchema - Stores and fetches an attributes schema from it's associated asset <scriptName, schema>

Files renaming

For consistency, the following files have been renamed
script.js -> script-create.js - Contains legacy pc.createScript() and pc.registerScript()
script.js contains new Script base class
script-type.js contains legacy ScriptType class

Tests

npm run test:karma

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
engine	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 21, 2024 4:05pm

[Maksims]

What would be the impact to users in terms of migrations or API changes?

[marklundin]

What would be the impact to users in terms of migrations or API changes?

pc.createScript() will still work and return a ScriptType which should function in the same way. ESM users will use Script as a base class without any ScriptAttribute functionality (events, rawToValue deep copying)

[mvaligursky]

Looks good to me, added few small comments.
But I'd suggest some additional approvals before merging.
Please make sure no unwanted functions are exposed in the public API here.

[Maksims]

This is amazing!

Can we provide a few examples of old-vs-new ways for most common use cases?
As I understand, this is fully compatible with the current ScriptComponent system and can mix with legacy scripts within the component, so devs can gradually migrate current scripts to ESM scripts?

Also, as there are expected few other systems and improvements for ESM (engine and editor), would it be beneficial to mark this API in a way that devs know it is still in the works? So the community can try and battle test the new ESM system fully, before it is a recommended way for everyone?

adressed

[marklundin]

Can we provide a few examples of old-vs-new ways for most common use cases? As I understand, this is fully compatible with the current ScriptComponent system and can mix with legacy scripts within the component, so devs can gradually migrate current scripts to ESM scripts?

Yep thats right. Both types of scripts can be used interchangeably within the same component.

1. Legacy scripts will continue to use pc.createScript
2. ESM Scripts will use class based syntax inheriting from Script

Also, as there are expected few other systems and improvements for ESM (engine and editor), would it be beneficial to mark this API in a way that devs know it is still in the works? So the community can try and battle test the new ESM system fully, before it is a recommended way for everyone?

For now ESM Scripts will be opt-in. You need to manually create a script with the .mjs suffix in a project to use them. If you don't provide a suffix, it will create a legacy script by default.

For engine only, entity.script.create(class, values) with ScriptType will work in the same way as now. If not a ScriptType, values will only be assigned if an corresponding schema is found in the ScriptRegistry.getSchema().