@galacean/engine-core 2.0.0-alpha.36 → 2.0.0-alpha.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@galacean/engine-core",
-  "version": "2.0.0-alpha.36",
+  "version": "2.0.0-alpha.38",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -18,10 +18,10 @@
     "types/**/*"
   ],
   "dependencies": {
-    "@galacean/engine-math": "2.0.0-alpha.36"
+    "@galacean/engine-math": "2.0.0-alpha.38"
   },
   "devDependencies": {
-    "@galacean/engine-design": "2.0.0-alpha.36"
+    "@galacean/engine-design": "2.0.0-alpha.38"
   },
   "scripts": {
     "b:types": "tsc"

package/types/Engine.d.ts

@@ -35,6 +35,7 @@ export declare class Engine extends EventDispatcher {
     private _waitingGC;
     private _postProcessPasses;
     private _activePostProcessPasses;
+    private _onCanvasResize;
     private _animate;
     /**
      * Settings of Engine.

package/types/Entity.d.ts

@@ -84,9 +84,10 @@ export declare class Entity extends EngineObject {
     getComponents<T extends Component>(type: ComponentConstructor<T>, results: T[]): T[];
     /**
      * Get the components which match the type of the entity and it's children.
+     * @remarks The components are returned in depth-first pre-order: the entity itself first, then each child's subtree in sibling order.
      * @param type - The component type
      * @param results - The components collection
-     * @returns	The components collection which match the type
+     * @returns The components collection which match the type
      */
     getComponentsIncludeChildren<T extends Component>(type: ComponentConstructor<T>, results: T[]): T[];
     /**

package/types/Signal.d.ts

@@ -13,9 +13,11 @@ export declare class Signal<T extends any[] = []> {
     on(fn: (...args: T) => void, target?: any): void;
     /**
      * Add a structured binding listener. Structured bindings support clone remapping.
+     * The target method will be invoked as `method(...signalArgs, ...args)` —
+     * runtime signal arguments come first, bound arguments are appended.
      * @param target - The target component
      * @param methodName - The method name to invoke on the target
-     * @param args - Pre-resolved arguments
+     * @param args - Pre-resolved arguments appended after the runtime signal arguments
      */
     on(target: Component, methodName: string, ...args: any[]): void;
     /**
@@ -26,9 +28,11 @@ export declare class Signal<T extends any[] = []> {
     once(fn: (...args: T) => void, target?: any): void;
     /**
      * Add a one-time structured binding listener.
+     * The target method will be invoked as `method(...signalArgs, ...args)` —
+     * runtime signal arguments come first, bound arguments are appended.
      * @param target - The target component
      * @param methodName - The method name to invoke on the target
-     * @param args - Pre-resolved arguments
+     * @param args - Pre-resolved arguments appended after the runtime signal arguments
      */
     once(target: Component, methodName: string, ...args: any[]): void;
     /**

package/types/animation/AnimationClip.d.ts

@@ -1,6 +1,6 @@
 import { EngineObject } from "../base/EngineObject";
 import { Component } from "../Component";
-import { ComponentConstructor } from "../Entity";
+import { ComponentConstructor, Entity } from "../Entity";
 import { AnimationClipCurveBinding } from "./AnimationClipCurveBinding";
 import { AnimationCurve } from "./animationCurve/AnimationCurve";
 import { AnimationEvent } from "./AnimationEvent";
@@ -84,4 +84,10 @@ export declare class AnimationClip extends EngineObject {
      * Clears all curve bindings from the clip.
      */
     clearCurveBindings(): void;
+    /**
+     * Samples an animation at a given time.
+     * @param entity - The animated entity
+     * @param time - The time to sample an animation
+     */
+    sampleAnimation(entity: Entity, time: number): void;
 }

package/types/animation/Animator.d.ts

@@ -15,6 +15,8 @@ export declare class Animator extends Component {
     cullingMode: AnimatorCullingMode;
     /** The playback speed of the Animator, 1.0 is normal playback speed. */
     speed: number;
+    /** Whether the Animator sends AnimationEvent callbacks. */
+    fireEvents: boolean;
     protected _animatorController: AnimatorController;
     protected _controllerUpdateFlag: BoolUpdateFlag;
     protected _updateMark: number;

package/types/animation/AnimatorController.d.ts

@@ -7,6 +7,7 @@ import { Engine } from "../Engine";
  */
 export declare class AnimatorController extends ReferResource {
     private _updateFlagManager;
+    private _onStatesInvalidate;
     /**
      * The layers in the controller.
      */

package/types/animation/AnimatorControllerLayer.d.ts

@@ -10,10 +10,16 @@ export declare class AnimatorControllerLayer {
     weight: number;
     /** The blending mode used by the layer. It is not taken into account for the first layer. */
     blendingMode: AnimatorLayerBlendingMode;
-    /** The state machine for the layer. */
-    stateMachine: AnimatorStateMachine;
     /** The AnimatorLayerMask is used to mask out certain entities from being animated by an AnimatorLayer. */
     mask: AnimatorLayerMask;
+    private _stateMachine;
+    private _engine;
+    private _onStatesInvalidate;
+    /**
+     * The state machine for the layer.
+     */
+    get stateMachine(): AnimatorStateMachine;
+    set stateMachine(value: AnimatorStateMachine);
     /**
      * @param name - The layer's name
      */

package/types/animation/AnimatorStateMachine.d.ts

@@ -10,6 +10,7 @@ export declare class AnimatorStateMachine {
     /** The list of states. */
     readonly states: AnimatorState[];
     private _engine;
+    private _onStatesInvalidate;
     /**
      * The state will be played automatically.
      * @remarks When the Animator's AnimatorController changed or the Animator's onEnable be triggered. Cleared to `null` if the state is removed via `removeState`.

package/types/asset/ResourceManager.d.ts

@@ -100,7 +100,7 @@ export declare class ResourceManager {
      * @param restorer - The restorer
      */
     addContentRestorer<T extends EngineObject>(restorer: ContentRestorer<T>): void;
-    private _assignDefaultOptions;
+    private _resolveLoadItemOptions;
     private _loadSingleItem;
     private _loadSubpackageAndMainAsset;
     private _loadMainAsset;

package/types/audio/AudioManager.d.ts

@@ -6,6 +6,8 @@ export declare class AudioManager {
     private static _gainNode;
     private static _resumePromise;
     private static _needsUserGestureResume;
+    private static _suspendedByCaller;
+    private static _recovering;
     /**
      * Suspend the audio context.
      * @returns A promise that resolves when the audio context is suspended
@@ -18,5 +20,7 @@ export declare class AudioManager {
      */
     static resume(): Promise<void>;
     private static _onVisibilityChange;
+    private static _recoverPlaybackContext;
+    private static _onPageShow;
     private static _resumeAfterInterruption;
 }

package/types/audio/AudioSource.d.ts

@@ -67,6 +67,7 @@ export declare class AudioSource extends Component {
      */
     pause(): void;
     private _onPlayEnd;
+    private _ensureGainNode;
     private _startPlayback;
     private _initSourceNode;
     private _clearSourceNode;

package/types/particle/ParticleGenerator.d.ts

@@ -10,6 +10,7 @@ import { SizeOverLifetimeModule } from "./modules/SizeOverLifetimeModule";
 import { TextureSheetAnimationModule } from "./modules/TextureSheetAnimationModule";
 import { NoiseModule } from "./modules/NoiseModule";
 import { VelocityOverLifetimeModule } from "./modules/VelocityOverLifetimeModule";
+import { SubEmittersModule } from "./modules/SubEmittersModule";
 /**
  * Particle Generator.
  */
@@ -20,8 +21,10 @@ export declare class ParticleGenerator {
     private static _tempVector30;
     private static _tempVector31;
     private static _tempVector32;
+    private static _tempVector33;
     private static _tempMat;
-    private static _tempColor0;
+    private static _tempColor;
+    private static _tempQuat0;
     private static _tempParticleRenderers;
     private static readonly _particleIncreaseCount;
     private static readonly _transformedBoundsIncreaseCount;
@@ -48,8 +51,11 @@ export declare class ParticleGenerator {
     readonly textureSheetAnimation: TextureSheetAnimationModule;
     /** Noise module. */
     readonly noise: NoiseModule;
+    /** Sub emitters module. */
+    readonly subEmitters: SubEmittersModule;
     /** Custom data module. */
     readonly customData: CustomDataModule;
+    private _feedbackReadback;
     private _isPlaying;
     private _instanceBufferResized;
     private _waitProcessRetiredElementCount;
@@ -61,6 +67,13 @@ export declare class ParticleGenerator {
     private _firstActiveTransformedBoundingBox;
     private _firstFreeTransformedBoundingBox;
     private _playStartDelay;
+    private _eventPos;
+    private _eventColor;
+    private _eventSize;
+    private _eventRotation;
+    private _eventDir;
+    private _emitLocalPos;
+    private _emitDirection;
     /**
      * Whether the particle generator is contain alive or is still creating particles.
      */
@@ -91,9 +104,13 @@ export declare class ParticleGenerator {
      */
     emit(count: number): void;
     private _addNewParticle;
+    private _onParticleBirth;
     private _addFeedbackParticle;
     private _clearActiveParticles;
     private _retireActiveParticles;
+    private _readbackFeedback;
+    private _onParticleDeath;
+    private _evaluateOverLifetime;
     private _freeRetiredParticles;
     private _addActiveParticlesToVertexBuffer;
     private _addVertexBufferBindingsFilterDuplicate;
@@ -102,6 +119,12 @@ export declare class ParticleGenerator {
     private _calculateGeneratorBounds;
     private _mergeTransformedBounds;
     private _calculateTransformedBounds;
+    private _useOrbitalBounds;
+    private _getNoiseBoundsExtents;
+    private _getGravityBoundsReach;
+    private _getRangeReach;
+    private _getVectorReach;
+    private _getCurveMagnitudeFromZero;
     private _addGravityToBounds;
     private _getExtremeValueFromZero;
 }

package/types/particle/enums/ParticleSubEmitterInheritProperty.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Optional parent properties a sub-emitter inherits
+ * Sub particles are always emitted at the parent particle's position; these flags only select
+ * which additional properties are inherited on top of that.
+ */
+export declare enum ParticleSubEmitterInheritProperty {
+    /** Inherit no additional properties; sub particles are still emitted at the parent's position. */
+    None = 0,
+    /** Multiply parent's current color into the sub particle's start color. */
+    Color = 1,
+    /** Multiply parent's current size into the sub particle's start size. */
+    Size = 2,
+    /** Add parent's current rotation onto the sub particle's start rotation. */
+    Rotation = 4,
+    /** Emit the sub particle along the parent's velocity direction. */
+    Velocity = 8
+}

package/types/particle/enums/ParticleSubEmitterType.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Particle sub emitter trigger type.
+ */
+export declare enum ParticleSubEmitterType {
+    /** Triggered when a parent particle is born. */
+    Birth = 0,
+    /** Triggered when a parent particle dies (lifetime expired). */
+    Death = 1
+}

package/types/particle/index.d.ts

@@ -7,6 +7,8 @@ export { ParticleRenderMode } from "./enums/ParticleRenderMode";
 export { ParticleScaleMode } from "./enums/ParticleScaleMode";
 export { ParticleSimulationSpace } from "./enums/ParticleSimulationSpace";
 export { ParticleStopMode } from "./enums/ParticleStopMode";
+export { ParticleSubEmitterType } from "./enums/ParticleSubEmitterType";
+export { ParticleSubEmitterInheritProperty } from "./enums/ParticleSubEmitterInheritProperty";
 export { Burst } from "./modules/Burst";
 export { ColorOverLifetimeModule } from "./modules/ColorOverLifetimeModule";
 export { CustomDataModule } from "./modules/CustomDataModule";
@@ -22,4 +24,6 @@ export { TextureSheetAnimationModule } from "./modules/TextureSheetAnimationModu
 export { VelocityOverLifetimeModule } from "./modules/VelocityOverLifetimeModule";
 export { LimitVelocityOverLifetimeModule } from "./modules/LimitVelocityOverLifetimeModule";
 export { NoiseModule } from "./modules/NoiseModule";
+export { SubEmitter } from "./modules/SubEmitter";
+export { SubEmittersModule } from "./modules/SubEmittersModule";
 export * from "./modules/shape/index";

package/types/particle/modules/ParticleCompositeCurve.d.ts

@@ -4,6 +4,7 @@ import { ParticleCurve } from "./ParticleCurve";
  * Particle composite curve.
  */
 export declare class ParticleCompositeCurve {
+    private static _minMaxRange;
     private _updateManager;
     private _mode;
     private _constantMin;
@@ -75,7 +76,6 @@ export declare class ParticleCompositeCurve {
      * @returns - The result curve value
      */
     evaluate(time: number, lerpFactor: number): number;
-    private _getMaxKeyValue;
-    private _getMinKeyValue;
+    private _getKeyMinMax;
     private _onCurveChange;
 }

package/types/particle/modules/ParticleCompositeGradient.d.ts

@@ -5,6 +5,7 @@ import { ParticleGradient } from "./ParticleGradient";
  * Particle composite gradient.
  */
 export declare class ParticleCompositeGradient {
+    private static _tempColor;
     /** The gradient mode. */
     mode: ParticleGradientMode;
     constantMin: Color;

package/types/particle/modules/ParticleGeneratorModule.d.ts

@@ -1,11 +1,9 @@
 import { ShaderData, ShaderMacro } from "../../shader";
-import { ParticleGenerator } from "../ParticleGenerator";
 import { ParticleCompositeCurve } from "./ParticleCompositeCurve";
 /**
  * Particle generator module.
  */
 export declare abstract class ParticleGeneratorModule {
-    protected _generator: ParticleGenerator;
     protected _enabled: boolean;
     /**
      * Specifies whether the module is enabled or not.

package/types/particle/modules/SubEmitter.d.ts

@@ -0,0 +1,27 @@
+import { ParticleRenderer } from "../ParticleRenderer";
+import { ParticleSubEmitterInheritProperty } from "../enums/ParticleSubEmitterInheritProperty";
+import { ParticleSubEmitterType } from "../enums/ParticleSubEmitterType";
+/**
+ * One slot in `SubEmittersModule.subEmitters`. Configures which sub-emitter
+ * fires, on which parent event, with what inheritance, probability, and count.
+ */
+export declare class SubEmitter {
+    /** Bitmask of properties inherited from the parent particle. */
+    inheritProperties: ParticleSubEmitterInheritProperty;
+    /** Probability (0..1) the sub-emitter fires for any given event. */
+    emitProbability: number;
+    /** Number of sub particles emitted per parent event. */
+    emitCount: number;
+    private _emitter;
+    private _type;
+    /**
+     * Target particle renderer the sub particles emit into.
+     */
+    get emitter(): ParticleRenderer;
+    set emitter(value: ParticleRenderer);
+    /**
+     * Which parent-particle event drives this slot.
+     */
+    get type(): ParticleSubEmitterType;
+    set type(value: ParticleSubEmitterType);
+}

package/types/particle/modules/SubEmittersModule.d.ts

@@ -0,0 +1,36 @@
+import { ParticleSubEmitterInheritProperty } from "../enums/ParticleSubEmitterInheritProperty";
+import { ParticleSubEmitterType } from "../enums/ParticleSubEmitterType";
+import { ParticleRenderer } from "../ParticleRenderer";
+import { ParticleGeneratorModule } from "./ParticleGeneratorModule";
+import { SubEmitter } from "./SubEmitter";
+/**
+ * Fires sub-emitters on parent particle lifecycle events (Birth / Death).
+ * @remarks Requires WebGL2; the module stays inactive on WebGL1.
+ */
+export declare class SubEmittersModule extends ParticleGeneratorModule {
+    private static _cycleVisited;
+    private static _cycleStack;
+    private static _wouldCreateCycle;
+    private _subEmitters;
+    /**
+     * The configured sub-emitters.
+     */
+    get subEmitters(): readonly SubEmitter[];
+    private _probabilityRand;
+    /**
+     * Add a sub-emitter slot.
+     * @param emitter - Target particle renderer
+     * @param type - Trigger event (`Birth` / `Death`)
+     * @param inheritProperties - Bitmask of properties inherited from the parent particle
+     * @param emitProbability - Per-event fire probability [0, 1]
+     * @param emitCount - Number of sub particles emitted per parent event
+     */
+    addSubEmitter(emitter: ParticleRenderer, type: ParticleSubEmitterType, inheritProperties?: ParticleSubEmitterInheritProperty, emitProbability?: number, emitCount?: number): void;
+    /**
+     * Remove the sub-emitter at the given index.
+     * @param index - Index of the sub-emitter to remove
+     */
+    removeSubEmitterByIndex(index: number): void;
+    get enabled(): boolean;
+    set enabled(value: boolean);
+}

package/types/particle/modules/VelocityOverLifetimeModule.d.ts

@@ -1,3 +1,4 @@
+import { Vector3 } from "@galacean/engine-math";
 import { ShaderMacro } from "../../shader";
 import { ShaderProperty } from "../../shader/ShaderProperty";
 import { ParticleSimulationSpace } from "../enums/ParticleSimulationSpace";
@@ -20,14 +21,45 @@ export declare class VelocityOverLifetimeModule extends ParticleGeneratorModule
     static readonly _maxGradientYProperty: ShaderProperty;
     static readonly _maxGradientZProperty: ShaderProperty;
     static readonly _spaceProperty: ShaderProperty;
+    static readonly _orbitalConstantModeMacro: ShaderMacro;
+    static readonly _orbitalCurveModeMacro: ShaderMacro;
+    static readonly _orbitalRandomModeMacro: ShaderMacro;
+    static readonly _radialConstantModeMacro: ShaderMacro;
+    static readonly _radialCurveModeMacro: ShaderMacro;
+    static readonly _radialRandomModeMacro: ShaderMacro;
+    static readonly _orbitalMinConstantProperty: ShaderProperty;
+    static readonly _orbitalMaxConstantProperty: ShaderProperty;
+    static readonly _orbitalMinCurveXProperty: ShaderProperty;
+    static readonly _orbitalMinCurveYProperty: ShaderProperty;
+    static readonly _orbitalMinCurveZProperty: ShaderProperty;
+    static readonly _orbitalMaxCurveXProperty: ShaderProperty;
+    static readonly _orbitalMaxCurveYProperty: ShaderProperty;
+    static readonly _orbitalMaxCurveZProperty: ShaderProperty;
+    static readonly _radialMinConstantProperty: ShaderProperty;
+    static readonly _radialMaxConstantProperty: ShaderProperty;
+    static readonly _radialMinCurveProperty: ShaderProperty;
+    static readonly _radialMaxCurveProperty: ShaderProperty;
+    static readonly _offsetProperty: ShaderProperty;
     private _velocityMinConstant;
     private _velocityMaxConstant;
     private _velocityMacro;
     private _randomModeMacro;
+    private _orbitalMinConstant;
+    private _orbitalConstant;
+    private _orbitalMacro;
+    private _orbitalRandomModeMacro;
+    private _radialMacro;
+    private _radialRandomModeMacro;
     private _velocityX;
     private _velocityY;
     private _velocityZ;
+    private _orbitalX;
+    private _orbitalY;
+    private _orbitalZ;
+    private _radial;
+    private _offset;
     private _space;
+    private readonly _onTransformFeedbackDirty;
     /**
      * Velocity over lifetime for x axis.
      */
@@ -43,6 +75,35 @@ export declare class VelocityOverLifetimeModule extends ParticleGeneratorModule
      */
     get velocityZ(): ParticleCompositeCurve;
     set velocityZ(value: ParticleCompositeCurve);
+    /**
+     * Orbital velocity (radians/second) around the x axis of the system.
+     * @remarks Requires WebGL2.
+     */
+    get orbitalX(): ParticleCompositeCurve;
+    set orbitalX(value: ParticleCompositeCurve);
+    /**
+     * Orbital velocity (radians/second) around the y axis of the system.
+     * @remarks Requires WebGL2.
+     */
+    get orbitalY(): ParticleCompositeCurve;
+    set orbitalY(value: ParticleCompositeCurve);
+    /**
+     * Orbital velocity (radians/second) around the z axis of the system.
+     * @remarks Requires WebGL2.
+     */
+    get orbitalZ(): ParticleCompositeCurve;
+    set orbitalZ(value: ParticleCompositeCurve);
+    /**
+     * Radial velocity moving particles away from (or towards) the center.
+     * @remarks Requires WebGL2.
+     */
+    get radial(): ParticleCompositeCurve;
+    set radial(value: ParticleCompositeCurve);
+    /**
+     * The center offset of orbital/radial motion from the particle system origin.
+     */
+    get centerOffset(): Vector3;
+    set centerOffset(value: Vector3);
     /**
      * Velocity space.
      */
@@ -51,4 +112,5 @@ export declare class VelocityOverLifetimeModule extends ParticleGeneratorModule
     get enabled(): boolean;
     set enabled(value: boolean);
     constructor(generator: ParticleGenerator);
+    private _onOrbitalRadialChange;
 }

package/types/physics/DynamicCollider.d.ts

@@ -118,6 +118,12 @@ export declare class DynamicCollider extends Collider {
      * @param force - The force make the collider move
      */
     applyForce(force: Vector3): void;
+    /**
+     * Apply a force to the DynamicCollider at a given position in world space.
+     * @param force - The force to apply, in world space
+     * @param position - The position where the force is applied, in world space
+     */
+    applyForceAtPosition(force: Vector3, position: Vector3): void;
     /**
      * Apply a torque to the DynamicCollider.
      * @param torque - The force make the collider rotate