Adds Script scriptName field (#7593)

* Enhance script registration with static "scriptName" validation

Added warnings for ESM Script classes lacking a static "scriptName" property. Updated the ScriptComponent and ScriptHandler to infer script names and log appropriate debug messages. Enhanced getScriptName function to return the scriptName if defined. Added tests to verify the new behavior.

* Refine script registration validation and enhance test coverage

Updated the ScriptComponent to ensure that a static "scriptName" property is required only for non-ScriptType instances. Modified tests to check for script existence using the `has` method and added a new test to confirm that no warnings are logged when a ScriptType is used. This improves the robustness of script registration and validation.

Author: marklundin

src/framework/components/script/component.js

@@ -712,7 +712,16 @@ class ScriptComponent extends Component {
         if (typeof scriptType === 'string') {
             scriptType = this.system.app.scripts.get(scriptType);
         } else if (scriptType) {
-            scriptName = scriptType.__name ??= toLowerCamelCase(getScriptName(scriptType));
+
+            const inferredScriptName = getScriptName(scriptType);
+            const lowerInferredScriptName = toLowerCamelCase(inferredScriptName);
+
+            if (!(scriptType.prototype instanceof ScriptType) && !scriptType.scriptName) {
+                Debug.warnOnce(`The Script class "${inferredScriptName}" must have a static "scriptName" property: \`${inferredScriptName}.scriptName = "${lowerInferredScriptName}";\`. This will be an error in future versions of PlayCanvas.`);
+            }
+
+            scriptType.__name ??= scriptType.scriptName ?? lowerInferredScriptName;
+            scriptName = scriptType.__name;
         }
 
         if (scriptType) {

src/framework/handlers/script.js

@@ -1,4 +1,5 @@
 import { platform } from '../../core/platform.js';
+import { Debug } from '../../core/debug.js';
 import { script } from '../script.js';
 import { ScriptTypes } from '../script/script-types.js';
 import { registerScript } from '../script/script-create.js';
@@ -137,7 +138,13 @@ class ScriptHandler extends ResourceHandler {
 
                 if (extendsScriptType) {
 
-                    const scriptName = toLowerCamelCase(scriptClass.name);
+                    const lowerCamelCaseName = toLowerCamelCase(scriptClass.name);
+
+                    if (!scriptClass.scriptName) {
+                        Debug.warnOnce(`The Script class "${scriptClass.name}" must have a static "scriptName" property: \`${scriptClass.name}.scriptName = "${lowerCamelCaseName}";\`. This will be an error in future versions of PlayCanvas.`);
+                    }
+
+                    const scriptName = scriptClass.scriptName ?? lowerCamelCaseName;
 
                     // Register the script name
                     registerScript(scriptClass, scriptName);

src/framework/script/script.js

@@ -347,6 +347,7 @@ const funcNameRegex = /^\s*function(?:\s|\s*\/\*.*\*\/\s*)+([^(\s\/]*)\s*/;
  */
 export function getScriptName(constructorFn) {
     if (typeof constructorFn !== 'function') return undefined;
+    if (constructorFn.scriptName) return constructorFn.scriptName;
     if ('name' in Function.prototype) return constructorFn.name;
     if (constructorFn === Function || constructorFn === Function.prototype.constructor) return 'Function';
     const match = (`${constructorFn}`).match(funcNameRegex);

test/framework/components/script/component.test.mjs

@@ -1,8 +1,10 @@
 import { expect } from 'chai';
 
+import { Debug } from '../../../../src/core/debug.js';
 import { Asset } from '../../../../src/framework/asset/asset.js';
 import { Entity } from '../../../../src/framework/entity.js';
 import { createScript } from '../../../../src/framework/script/script-create.js';
+import { Script } from '../../../../src/framework/script/script.js';
 import { createApp } from '../../../app.mjs';
 import { jsdomSetup, jsdomTeardown } from '../../../jsdom.mjs';
 
@@ -2925,4 +2927,56 @@ describe('ScriptComponent', function () {
         expect(e.script.has(null)).to.equal(false);
     });
 
+    it('warns when an ESM Script class does not have a static "scriptName" property', function () {
+        class TestScript extends Script {}
+        const a =  new Entity();
+        a.addComponent('script', { enabled: true });
+        a.script.create(TestScript);
+
+        expect(Debug._loggedMessages.has(
+            'The Script class "TestScript" must have a static "scriptName" property: `TestScript.scriptName = "testScript";`. This will be an error in future versions of PlayCanvas.'
+        )).to.equal(true);
+    });
+
+    it('correctly registers an ESM script with its scriptName', function () {
+        class TestScript extends Script {
+            static scriptName = 'myTestScript';
+        }
+        const a = new Entity();
+        a.addComponent('script', { enabled: true });
+        a.script.create(TestScript);
+
+        expect(a.script.has('testScript')).to.equal(false);
+        expect(a.script.has('myTestScript')).to.equal(true);
+    });
+
+    it('falls back to camelCase script name if scriptName is not defined', function () {
+        class TestScript extends Script {}
+        const a = new Entity();
+        a.addComponent('script', { enabled: true });
+        a.script.create(TestScript);
+
+        expect(a.script.has('testScript')).to.equal(true);
+        expect(a.script.has('myTestScript')).to.equal(false);
+    });
+
+    it('does not warn when a ScriptType is used', function () {
+        Debug._loggedMessages.clear();
+        createScript('nullScript');
+        const e = new Entity();
+        e.addComponent('script', {
+            enabled: true,
+            order: ['nullScript'],
+            scripts: {
+                nullScript: {
+                    enabled: true
+                }
+            }
+        });
+        app.root.addChild(e);
+
+        expect(Debug._loggedMessages.size).to.equal(0);
+        expect(e.script.has('nullScript')).to.equal(true);
+    });
+
 });