fixed #17833: [v3.8.5] Add an ability to load wasm/asmjs module manua…

…lly (#17844)

EngineErrorMap.md

@@ -3238,6 +3238,14 @@ Can't getGFXSampler with out device
 
 [Physics][cannon.js]: sweep functions are not supported in cannon.js
 
+### 9642
+
+[Physics] PhysicsSystem initDefaultMaterial() Failed to load builtinMaterial.
+
+### 9643
+
+[Physics] Failed to load user customized default physics material: %s, will fallback to built-in default physics material
+
 ### 10001
 
 The sub-mesh contains %d vertices, which beyonds the capability (%d vertices most) of renderer of your platform.

cc.config.json

@@ -696,6 +696,30 @@
             "type": "boolean",
             "value": true,
             "internal": true
+        },
+        "LOAD_SPINE_MANUALLY": {
+            "comment": "An internal constant to indicate whether we need to load spine wasm/asmjs module manually.",
+            "type": "boolean",
+            "value": false,
+            "internal": true
+        },
+        "LOAD_BOX2D_MANUALLY": {
+            "comment": "An internal constant to indicate whether we need to load box2d wasm/asmjs module manually.",
+            "type": "boolean",
+            "value": false,
+            "internal": true
+        },
+        "LOAD_BULLET_MANUALLY": {
+            "comment": "An internal constant to indicate whether we need to load bullet wasm/asmjs module manually.",
+            "type": "boolean",
+            "value": false,
+            "internal": true
+        },
+        "LOAD_PHYSX_MANUALLY": {
+            "comment": "An internal constant to indicate whether we need to load physx wasm/asmjs module manually.",
+            "type": "boolean",
+            "value": false,
+            "internal": true
         }
     },
 

cocos/physics-2d/box2d-wasm/instantiate.ts

@@ -22,6 +22,7 @@
  THE SOFTWARE.
 */
 
+import { BUILD, LOAD_BOX2D_MANUALLY } from 'internal:constants';
 import { selector } from '../framework/physics-selector';
 import { B2PhysicsWorld } from './physics-world';
 import { B2RigidBody2D } from './rigid-body';
@@ -38,6 +39,8 @@ import { B2WheelJoint } from './joints/wheel-joint';
 import { B2HingeJoint } from './joints/hinge-joint';
 
 import { Game, game } from '../../game';
+import { waitForBox2dWasmInstantiation } from './instantiated';
+import { PhysicsSystem2D } from '../framework';
 
 game.once(Game.EVENT_PRE_SUBSYSTEM_INIT, () => {
     selector.register('box2d-wasm', {
@@ -58,3 +61,17 @@ game.once(Game.EVENT_PRE_SUBSYSTEM_INIT, () => {
         HingeJoint: B2HingeJoint,
     });
 });
+
+let loadBox2dPromise: Promise<void> | undefined;
+
+export function loadWasmModuleBox2D (): Promise<void> {
+    if (BUILD && LOAD_BOX2D_MANUALLY) {
+        if (loadBox2dPromise) return loadBox2dPromise;
+        loadBox2dPromise = Promise.resolve()
+            .then(() => waitForBox2dWasmInstantiation())
+            .then(() => PhysicsSystem2D.constructAndRegister());
+        return loadBox2dPromise;
+    } else {
+        return Promise.resolve();
+    }
+}

cocos/physics-2d/box2d-wasm/instantiated.ts

@@ -23,7 +23,7 @@
 */
 
 import { instantiateWasm, ensureWasmModuleReady } from 'pal/wasm';
-import { NATIVE_CODE_BUNDLE_MODE } from 'internal:constants';
+import { BUILD, LOAD_BOX2D_MANUALLY, NATIVE_CODE_BUNDLE_MODE } from 'internal:constants';
 
 import { game } from '../../game';
 import { error, sys, IVec2Like, log } from '../../core';
@@ -193,4 +193,6 @@ export function waitForBox2dWasmInstantiation (): Promise<void> {
     }).catch(errorReport);
 }
 
-game.onPostInfrastructureInitDelegate.add(waitForBox2dWasmInstantiation);
+if (!BUILD || !LOAD_BOX2D_MANUALLY) {
+    game.onPostInfrastructureInitDelegate.add(waitForBox2dWasmInstantiation);
+}

cocos/physics-2d/framework/physics-system.ts

@@ -22,7 +22,7 @@
  THE SOFTWARE.
 */
 
-import { EDITOR_NOT_IN_PREVIEW } from 'internal:constants';
+import { BUILD, EDITOR_NOT_IN_PREVIEW, LOAD_BOX2D_MANUALLY } from 'internal:constants';
 import { System, Vec2, IVec2Like, Rect, Eventify, Enum, Settings, settings, cclegacy, SettingsCategory } from '../../core';
 import { createPhysicsWorld, selector, IPhysicsSelector } from './physics-selector';
 
@@ -383,4 +383,6 @@ export class PhysicsSystem2D extends Eventify(System) {
     }
 }
 
-director.once(DirectorEvent.INIT, (): void => { PhysicsSystem2D.constructAndRegister(); });
+if (!BUILD || !LOAD_BOX2D_MANUALLY) {
+    director.once(DirectorEvent.INIT, (): void => { PhysicsSystem2D.constructAndRegister(); });
+}

cocos/physics/bullet/instantiate.ts

@@ -22,6 +22,7 @@
  THE SOFTWARE.
 */
 
+import { BUILD, LOAD_BULLET_MANUALLY } from 'internal:constants';
 import { Game, game } from '../../game';
 import { selector } from '../framework/physics-selector';
 import { BulletRigidBody } from './bullet-rigid-body';
@@ -42,6 +43,8 @@ import { BulletConfigurableConstraint } from './constraints/bullet-configurable-
 
 import { BulletCapsuleCharacterController } from './character-controllers/bullet-capsule-character-controller';
 import { BulletBoxCharacterController } from './character-controllers/bullet-box-character-controller';
+import { waitForAmmoInstantiation } from './instantiated';
+import { PhysicsSystem } from '../framework';
 
 game.once(Game.EVENT_PRE_SUBSYSTEM_INIT, () => {
     selector.register('bullet', {
@@ -67,3 +70,17 @@ game.once(Game.EVENT_PRE_SUBSYSTEM_INIT, () => {
         CapsuleCharacterController: BulletCapsuleCharacterController,
     });
 });
+
+let loadBulletPromise: Promise<void> | undefined;
+
+export function loadWasmModuleBullet (): Promise<void> {
+    if (BUILD && LOAD_BULLET_MANUALLY) {
+        if (loadBulletPromise) return loadBulletPromise;
+        loadBulletPromise = Promise.resolve()
+            .then(() => waitForAmmoInstantiation())
+            .then(() => PhysicsSystem.constructAndRegisterManually());
+        return loadBulletPromise;
+    } else {
+        return Promise.resolve();
+    }
+}

cocos/physics/bullet/instantiated.ts

@@ -23,7 +23,7 @@
 */
 
 import { ensureWasmModuleReady, instantiateWasm } from 'pal/wasm';
-import { NATIVE_CODE_BUNDLE_MODE } from 'internal:constants';
+import { BUILD, LOAD_BULLET_MANUALLY, NATIVE_CODE_BUNDLE_MODE } from 'internal:constants';
 import { game } from '../../game';
 import { error, log, sys } from '../../core';
 import { NativeCodeBundleMode } from '../../misc/webassembly-support';
@@ -155,4 +155,6 @@ export function waitForAmmoInstantiation (): Promise<void> {
     }).catch(errorReport);
 }
 
-game.onPostInfrastructureInitDelegate.add(waitForAmmoInstantiation);
+if (!BUILD || !LOAD_BULLET_MANUALLY) {
+    game.onPostInfrastructureInitDelegate.add(waitForAmmoInstantiation);
+}

cocos/physics/framework/physics-system.ts

@@ -22,8 +22,8 @@
  THE SOFTWARE.
 */
 
-import { EDITOR_NOT_IN_PREVIEW } from 'internal:constants';
-import { Vec3, RecyclePool, Enum, System, cclegacy, settings, geometry, warn, IQuatLike, IVec3Like, SettingsCategory } from '../../core';
+import { BUILD, EDITOR, EDITOR_NOT_IN_PREVIEW, LOAD_BULLET_MANUALLY, LOAD_PHYSX_MANUALLY, PREVIEW } from 'internal:constants';
+import { Vec3, RecyclePool, Enum, System, cclegacy, settings, geometry, warn, IQuatLike, IVec3Like, SettingsCategory, errorID, warnID } from '../../core';
 import { IPhysicsWorld, IRaycastOptions } from '../spec/i-physics-world';
 import { director, Director, DirectorEvent, game } from '../../game';
 import { PhysicsMaterial } from './assets/physics-material';
@@ -223,11 +223,11 @@ export class PhysicsSystem extends System implements IWorldInitData {
 
         const builtinMaterial = builtinResMgr.get<PhysicsMaterial>('default-physics-material');
         if (!builtinMaterial) {
-            console.error('PhysicsSystem initDefaultMaterial() Failed to load builtinMaterial');
+            errorID(9642);
             return Promise.resolve();
         }
 
-        const userMaterial = settings.querySettings(SettingsCategory.PHYSICS, 'defaultMaterial');
+        const userMaterial: string | null = settings.querySettings(SettingsCategory.PHYSICS, 'defaultMaterial');
         if (!userMaterial) { //use built-in default physics material
             this.setDefaultPhysicsMaterial(builtinMaterial);
             return Promise.resolve();
@@ -240,7 +240,7 @@ export class PhysicsSystem extends System implements IWorldInitData {
                 this.setDefaultPhysicsMaterial(asset);
             }).catch((reason): void => {
                 warn(reason);
-                warn(`Failed to load user customized default physics material: ${userMaterial}, will fallback to built-in default physics material`);
+                warnID(9643, userMaterial);
                 this.setDefaultPhysicsMaterial(builtinMaterial);
             });
         }
@@ -866,18 +866,35 @@ export class PhysicsSystem extends System implements IWorldInitData {
      * 预先加载模块的情况下，会自动执行。
      */
     static constructAndRegister (): void {
+        if (BUILD && (LOAD_BULLET_MANUALLY || LOAD_PHYSX_MANUALLY)) return;
+        if (!PhysicsSystem._instance) {
+            const sys = this.doConstructAndRegister();
+            if (sys) game.onPostProjectInitDelegate.add(sys.initDefaultMaterial.bind(sys));
+        }
+    }
+
+    static constructAndRegisterManually (): Promise<void> {
+        if (BUILD && (LOAD_BULLET_MANUALLY || LOAD_PHYSX_MANUALLY)) {
+            if (!PhysicsSystem._instance) {
+                const sys = this.doConstructAndRegister();
+                if (sys) return sys.initDefaultMaterial();
+            }
+        }
+        return Promise.resolve();
+    }
+
+    private static doConstructAndRegister (): PhysicsSystem | null {
         const enabled = settings.querySettings(SettingsCategory.PHYSICS, 'enabled') ?? true;
-        if (!enabled) { return; }
+        if (!enabled) { return null; }
         if (!PhysicsSystem._instance) {
             // Construct physics world and physics system only once
             const sys = new PhysicsSystem();
             (PhysicsSystem._instance as unknown as PhysicsSystem) = sys;
             sys.resetConfiguration();
             constructDefaultWorld(sys);
             director.registerSystem(PhysicsSystem.ID, sys, sys.priority);
-
-            game.onPostProjectInitDelegate.add(sys.initDefaultMaterial.bind(sys));
         }
+        return PhysicsSystem._instance;
     }
 }
 

cocos/physics/physx/instantiate.jsb.ts

@@ -29,3 +29,7 @@
 import { selector, IPhysicsSelector } from '../framework/physics-selector';
 
 (selector as Mutable<IPhysicsSelector>).id = 'physx';
+
+export function loadWasmModulePhysX (): Promise<void> {
+    return Promise.resolve();
+}

cocos/physics/physx/instantiate.ts

@@ -22,6 +22,7 @@
  THE SOFTWARE.
 */
 
+import { BUILD, LOAD_PHYSX_MANUALLY } from 'internal:constants';
 import { selector } from '../framework/physics-selector';
 
 import { PhysXWorld } from './physx-world';
@@ -45,6 +46,8 @@ import { PhysXBoxCharacterController } from './character-controllers/physx-box-c
 import { PhysXCapsuleCharacterController } from './character-controllers/physx-capsule-character-controller';
 
 import { Game, game } from '../../game';
+import { initPhysXLibs } from './physx-adapter';
+import { PhysicsSystem } from '../framework/physics-system';
 
 game.once(Game.EVENT_PRE_SUBSYSTEM_INIT, () => {
     selector.register('physx', {
@@ -69,3 +72,17 @@ game.once(Game.EVENT_PRE_SUBSYSTEM_INIT, () => {
         CapsuleCharacterController: PhysXCapsuleCharacterController,
     });
 });
+
+let loadPhysXPromise: Promise<void> | undefined;
+
+export function loadWasmModulePhysX (): Promise<void> {
+    if (BUILD && LOAD_PHYSX_MANUALLY) {
+        if (loadPhysXPromise) return loadPhysXPromise;
+        loadPhysXPromise = Promise.resolve()
+            .then(() => initPhysXLibs())
+            .then(() => PhysicsSystem.constructAndRegisterManually());
+        return loadPhysXPromise;
+    } else {
+        return Promise.resolve();
+    }
+}

cocos/physics/physx/physx-adapter.ts

@@ -32,7 +32,7 @@
 
 import { NativeCodeBundleMode } from '../../misc/webassembly-support';
 import { ensureWasmModuleReady, instantiateWasm } from 'pal/wasm';
-import { EDITOR, TEST, NATIVE_CODE_BUNDLE_MODE } from 'internal:constants';
+import { EDITOR, TEST, NATIVE_CODE_BUNDLE_MODE, LOAD_PHYSX_MANUALLY, BUILD } from 'internal:constants';
 import { IQuatLike, IVec3Like, Quat, RecyclePool, Vec3, cclegacy, geometry, sys, Color, error, IVec3 } from '../../core';
 import { shrinkPositions } from '../utils/util';
 import { IRaycastOptions } from '../spec/i-physics-world';
@@ -49,10 +49,12 @@ const globalThis = cclegacy._global;
 // Use bytedance native or js physics if nativePhysX is not null.
 const USE_EXTERNAL_PHYSX = !!globalThis.PHYSX;
 
-// Init physx libs when engine init.
-game.onPostInfrastructureInitDelegate.add(InitPhysXLibs);
+if (!BUILD || !LOAD_PHYSX_MANUALLY) {
+    // Init physx libs when engine init.
+    game.onPostInfrastructureInitDelegate.add(initPhysXLibs);
+}
 
-export function InitPhysXLibs (): Promise<void> {
+export function initPhysXLibs (): Promise<void> {
     const errorReport = (msg: any): void => { error(msg); };
     return ensureWasmModuleReady().then(() => {
         if (shouldUseWasmModule()) {
@@ -71,7 +73,7 @@ export function InitPhysXLibs (): Promise<void> {
     }).catch(errorReport);
 }
 
-function initASM (physxAsmFactory): any {
+function initASM (physxAsmFactory): Promise<void> {
     globalThis.PhysX = globalThis.PHYSX ? globalThis.PHYSX : physxAsmFactory;
     if (globalThis.PhysX != null) {
         return globalThis.PhysX().then((Instance: any): void => {
@@ -88,7 +90,7 @@ function initASM (physxAsmFactory): any {
     }
 }
 
-function initWASM (physxWasmFactory, physxWasmUrl: string): any {
+function initWASM (physxWasmFactory, physxWasmUrl: string): Promise<void> {
     globalThis.PhysX = globalThis.PHYSX ? globalThis.PHYSX : physxWasmFactory;
     if (globalThis.PhysX != null) {
         return globalThis.PhysX({

cocos/spine/index.jsb.ts

@@ -112,3 +112,6 @@ ccenum(AnimationEventType);
 
 legacyCC.internal.SpineAnimationEventType = AnimationEventType;
 
+export function loadWasmModuleSpine (): Promise<void> {
+    return Promise.resolve();
+}

cocos/spine/index.ts

@@ -22,9 +22,10 @@
  THE SOFTWARE.
 */
 
+import { BUILD, LOAD_SPINE_MANUALLY } from 'internal:constants';
 import { ccenum } from '../core';
 import spine from './lib/spine-core';
-import './lib/instantiated';
+import { waitForSpineWasmInstantiation } from './lib/instantiated';
 
 /**
  * @en
@@ -119,3 +120,16 @@ export enum AnimationEventType {
     EVENT = 5
 }
 ccenum(AnimationEventType);
+
+let loadSpinePromise: Promise<void> | undefined;
+
+export function loadWasmModuleSpine (): Promise<void> {
+    if (BUILD && LOAD_SPINE_MANUALLY) {
+        if (loadSpinePromise) return loadSpinePromise;
+        loadSpinePromise = Promise.resolve()
+            .then(() => waitForSpineWasmInstantiation());
+        return loadSpinePromise;
+    } else {
+        return Promise.resolve();
+    }
+}

cocos/spine/lib/instantiated.ts

@@ -23,9 +23,9 @@
 */
 
 import { instantiateWasm, fetchBuffer, ensureWasmModuleReady } from 'pal/wasm';
-import { JSB, NATIVE_CODE_BUNDLE_MODE } from 'internal:constants';
+import { BUILD, JSB, LOAD_SPINE_MANUALLY, NATIVE_CODE_BUNDLE_MODE } from 'internal:constants';
 import { game } from '../../game';
-import { getError, error, sys } from '../../core';
+import { error, sys } from '../../core';
 import { NativeCodeBundleMode } from '../../misc/webassembly-support';
 import { overrideSpineDefine } from './spine-define';
 
@@ -120,8 +120,10 @@ export function waitForSpineWasmInstantiation (): Promise<void> {
     }).catch(errorReport);
 }
 
-if (!JSB) {
+if (!JSB && (!BUILD || !LOAD_SPINE_MANUALLY)) {
     game.onPostInfrastructureInitDelegate.add(waitForSpineWasmInstantiation);
-    registerList.push(overrideSpineDefine);
 }
+
+registerList.push(overrideSpineDefine);
+
 export const SPINE_WASM = 1;

exports/physics-2d-box2d-wasm.ts

@@ -24,3 +24,5 @@
  */
 
 import '../cocos/physics-2d/box2d-wasm/instantiate';
+
+export { loadWasmModuleBox2D } from '../cocos/physics-2d/box2d-wasm/instantiate';

exports/physics-ammo.ts

@@ -24,3 +24,5 @@
  */
 
 import '../cocos/physics/bullet/instantiate';
+
+export { loadWasmModuleBullet } from '../cocos/physics/bullet/instantiate';