@galacean/engine-physics-physx 0.0.0-experimental-2.0-skill.0 → 0.0.0-experimental-2.0-migrate.7

package/types/PhysXDynamicCollider.d.ts

@@ -21,6 +21,18 @@ export declare enum CollisionDetectionMode {
 export declare class PhysXDynamicCollider extends PhysXCollider implements IDynamicCollider {
     private static _tempTranslation;
     private static _tempRotation;
+    /**
+     * Whether actor is currently kinematic.
+     * PhysX 拒绝在 kinematic actor 上启用 CCD（会打印警告并忽略），
+     * 所以 setCollisionDetectionMode 在 kinematic 状态下只缓存目标值，
+     * 等切回 dynamic 时再真正写到 PhysX。
+     */
+    private _isKinematic;
+    /**
+     * Cached collision detection mode. Always reflects user's intent.
+     * 实际 PhysX CCD flag 可能跟这个不一致（kinematic 时强制 Discrete）。
+     */
+    private _collisionDetectionMode;
     constructor(physXPhysics: PhysXPhysics, position: Vector3, rotation: Quaternion);
     /**
      * {@inheritDoc IDynamicCollider.setLinearDamping }
@@ -80,7 +92,7 @@ export declare class PhysXDynamicCollider extends PhysXCollider implements IDyna
     setMaxDepenetrationVelocity(value: number): void;
     /**
      * {@inheritDoc IDynamicCollider.setSleepThreshold }
-     * @default 1e-5f * PxTolerancesScale::speed * PxTolerancesScale::speed
+     * @default 5e-5f * PxTolerancesScale::speed * PxTolerancesScale::speed
      */
     setSleepThreshold(value: number): void;
     /**
@@ -89,6 +101,15 @@ export declare class PhysXDynamicCollider extends PhysXCollider implements IDyna
     setSolverIterations(value: number): void;
     /**
      * {@inheritDoc IDynamicCollider.setCollisionDetectionMode }
+     *
+     * PhysX 在 kinematic actor 上调用 setRigidBodyFlag(eENABLE_CCD, true) 会触发警告:
+     *   "kinematic bodies with CCD enabled are not supported! CCD will be ignored"
+     * 虽然 PhysX 会忽略这次调用而非真的拒绝（切回 dynamic 时 flag 不会自动恢复），
+     * 但每次 setIsKinematic 切换都会让这个 warning 重复打印，污染日志，
+     * 同时让 actor 在 dynamic 状态下 CCD flag 状态不确定。
+     *
+     * 解决: 只在 dynamic 状态时立即 apply CCD flags。kinematic 时仅缓存到
+     * `_collisionDetectionMode`，等切回 dynamic 时由 setIsKinematic 重新 apply。
      */
     setCollisionDetectionMode(value: number): void;
     /**
@@ -97,14 +118,25 @@ export declare class PhysXDynamicCollider extends PhysXCollider implements IDyna
     setUseGravity(value: boolean): void;
     /**
      * {@inheritDoc IDynamicCollider.setIsKinematic }
+     *
+     * 切换 kinematic 状态时同步处理 CCD flag：
+     *   - 切到 kinematic 前先关 CCD（避免 PhysX 警告 + 让状态显式）
+     *   - 切回 dynamic 后恢复用户期望的 CCD mode（来自 `_collisionDetectionMode` 缓存）
      */
     setIsKinematic(value: boolean): void;
+    private _applyCollisionDetectionFlags;
     /**
      * {@inheritDoc IDynamicCollider.setConstraints }
      */
     setConstraints(flags: number): void;
     /**
      * {@inheritDoc IDynamicCollider.addForce }
+     *
+     * PhysX 在 kinematic actor 上调 addForce 是 no-op（doc: "kinematic bodies don't
+     * respond to forces"）。提前 return 避免无意义的 wasm boundary cross。
+     *
+     * Sleeping actor 不需要显式 wakeUp — wasm binding 调用 `addForce(force, eFORCE,
+     * autowake=true)`，PhysX 自动唤醒（已通过 `applyForce on sleeping actor` 测试验证）。
      */
     addForce(force: Vector3): void;
     /**
@@ -113,10 +145,15 @@ export declare class PhysXDynamicCollider extends PhysXCollider implements IDyna
     addForceAtPosition(force: Vector3, position: Vector3): void;
     /**
      * {@inheritDoc IDynamicCollider.addTorque }
+     *
+     * 同 addForce — kinematic 提前 return，sleeping 由 PhysX autowake 自动处理。
      */
     addTorque(torque: Vector3): void;
     /**
      * {@inheritDoc IDynamicCollider.move }
+     *
+     * PhysX 要求 setKinematicTarget 的 rotation 是 normalized quaternion，否则会触发
+     * 内部 assertion / 警告，并把 actor 转到错误的姿态。所以在写入 wasm 边界前统一 normalize。
      */
     move(positionOrRotation: Vector3 | Quaternion, rotation?: Quaternion): void;
     /**

package/types/PhysXPhysics.d.ts

@@ -16,12 +16,17 @@ export declare class PhysXPhysics implements IPhysics {
     private _tolerancesScale;
     private _wasmSIMDModeUrl;
     private _wasmModeUrl;
+    private _tolerancesScaleOptions;
+    private _defaultContactOffset;
+    private _defaultSleepThreshold;
     /**
      * Create a PhysXPhysics instance.
      * @param runtimeMode - Runtime mode, `Auto` prefers WebAssembly SIMD if supported @see {@link PhysXRuntimeMode}
      * @param runtimeUrls - Manually specify the runtime URLs
+     * @param options - PhysX options.
      */
-    constructor(runtimeMode?: PhysXRuntimeMode, runtimeUrls?: PhysXRuntimeUrls);
+    constructor(runtimeMode?: PhysXRuntimeMode, runtimeUrls?: PhysXRuntimeUrls, options?: PhysXPhysicsOptions);
+    constructor(options?: PhysXPhysicsOptions);
     /**
      * Initialize PhysXPhysics.
      * @param runtimeMode - Runtime mode
@@ -40,6 +45,14 @@ export declare class PhysXPhysics implements IPhysics {
      * {@inheritDoc IPhysics.createPhysicsScene }
      */
     createPhysicsScene(physicsManager: PhysXPhysicsManager): IPhysicsScene;
+    /**
+     * {@inheritDoc IPhysics.getDefaultContactOffset }
+     */
+    getDefaultContactOffset(): number;
+    /**
+     * {@inheritDoc IPhysics.getDefaultSleepThreshold }
+     */
+    getDefaultSleepThreshold(): number;
     /**
      * {@inheritDoc IPhysics.createStaticCollider }
      */
@@ -97,6 +110,10 @@ export declare class PhysXPhysics implements IPhysics {
      */
     setColliderLayerCollision(layer1: number, layer2: number, isCollide: boolean): void;
     private _init;
+    private _applyTolerancesScale;
+    private _assertPositiveFinite;
+    private _validateTolerancesScale;
+    private _updateScaledDefaults;
 }
 interface PhysXRuntimeUrls {
     /*** The URL of `PhysXRuntimeMode.WebAssembly` mode. */
@@ -104,4 +121,14 @@ interface PhysXRuntimeUrls {
     /*** The URL of `PhysXRuntimeMode.WebAssemblySIMD` mode. */
     wasmSIMDModeUrl?: string;
 }
+export interface PhysXTolerancesScale {
+    /** Approximate object length in the simulation unit. PhysX default is 1. */
+    length?: number;
+    /** Typical object speed in the simulation unit. PhysX default is 10. */
+    speed?: number;
+}
+export interface PhysXPhysicsOptions {
+    /** PhysX world unit scale used before PxPhysics, PxSceneDesc and PxCookingParams are created. */
+    tolerancesScale?: PhysXTolerancesScale;
+}
 export {};

package/types/PhysXPhysicsScene.d.ts

@@ -29,6 +29,7 @@ export declare class PhysXPhysicsScene implements IPhysicsScene {
     private _activeTriggers;
     private _contactEvents;
     private _contactEventCount;
+    private _contactEventEnabled;
     private _triggerEvents;
     private _physicsEvents;
     private _triggerEventPool;
@@ -57,6 +58,10 @@ export declare class PhysXPhysicsScene implements IPhysicsScene {
      * {@inheritDoc IPhysicsScene.update }
      */
     update(elapsedTime: number): void;
+    /**
+     * {@inheritDoc IPhysicsScene.setContactEventEnabled }
+     */
+    setContactEventEnabled(enabled: boolean): void;
     /**
      * {@inheritDoc IPhysicsScene.updateEvents }
      */

package/types/index.d.ts

@@ -1,3 +1,4 @@
 export { PhysXPhysics } from "./PhysXPhysics";
+export type { PhysXPhysicsOptions, PhysXTolerancesScale } from "./PhysXPhysics";
 export { PhysXRuntimeMode } from "./enum/PhysXRuntimeMode";
 export declare const version = "__buildVersion";