@galacean/engine-core 2.0.0-alpha.37 → 2.0.0-alpha.39

package/package.json

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

package/types/Canvas.d.ts

@@ -1,19 +1,35 @@
 /**
- * Canvas.
+ * The canvas the engine renders to; owns the render-buffer resolution.
  */
 export declare abstract class Canvas {
     private _width;
     private _height;
     /**
-     * The width of the canvas.
+     * The width component of the canvas resolution, in pixels.
      */
     get width(): number;
-    set width(value: number);
     /**
-     *The height of the canvas.
+     * The height component of the canvas resolution, in pixels.
      */
     get height(): number;
-    set height(value: number);
-    protected abstract _onWidthChanged(value: number): void;
-    protected abstract _onHeightChange(value: number): void;
+    /**
+     * Lock the render buffer to an explicit resolution and stop following the display size.
+     * @param width - Render buffer width in pixels
+     * @param height - Render buffer height in pixels
+     *
+     * @throws
+     * Throw an error if width or height is not a positive finite number.
+     */
+    setResolution(width: number, height: number): void;
+    /**
+     * Make the render buffer automatically follow the canvas display size.
+     * @param scale - Multiplier applied to the device pixel ratio (1 = native sharpness, 0.7 = save GPU, 2 = supersample), defaults to `1`
+     *
+     * @throws
+     * Throw an error if scale is not a positive finite number.
+     */
+    abstract setAutoResolution(scale?: number): void;
+    protected _setResolution(width: number, height: number): void;
+    protected _exitAutoResolution(): void;
+    protected abstract _onResolutionChanged(width: number, height: number): void;
 }

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;
@@ -110,6 +110,12 @@ export declare class ResourceManager {
     private _parseURL;
     private _parseQueryPath;
     private _releaseSubAssetPromiseCallback;
+    /**
+     * Register virtual asset paths and their load descriptors.
+     * @remarks References inside runtime scenes and Prefabs can keep stable virtual paths while the backing URLs
+     * are generated dynamically, such as object URLs created from a resource package.
+     */
+    registerVirtualResources(resources: readonly VirtualResource[]): void;
 }
 /**
  * Declare ResourceLoader's decorator.
@@ -119,3 +125,13 @@ export declare class ResourceManager {
 export declare function resourceLoader(assetType: string, extNames: string[], useCache?: boolean): <T extends Loader<any>>(Target: {
     new (useCache: boolean): T;
 }) => void;
+export interface VirtualResource {
+    virtualPath: string;
+    path: string;
+    type: string;
+    dependentAssetMap?: {
+        [key: string]: string;
+    };
+    subpackageName?: string;
+    params?: Record<string, any>;
+}

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/index.d.ts

@@ -23,7 +23,7 @@ export type { RequestConfig } from "./asset/request";
 export { Loader } from "./asset/Loader";
 export { ContentRestorer } from "./asset/ContentRestorer";
 export { RenderingStatistics } from "./asset/RenderingStatistics";
-export { ResourceManager, resourceLoader } from "./asset/ResourceManager";
+export { ResourceManager, resourceLoader, type VirtualResource } from "./asset/ResourceManager";
 export { AssetPromise } from "./asset/AssetPromise";
 export type { LoadItem } from "./asset/LoadItem";
 export { AssetType } from "./asset/AssetType";

package/types/particle/ParticleGenerator.d.ts

@@ -21,6 +21,7 @@ export declare class ParticleGenerator {
     private static _tempVector30;
     private static _tempVector31;
     private static _tempVector32;
+    private static _tempVector33;
     private static _tempMat;
     private static _tempColor;
     private static _tempQuat0;
@@ -118,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/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/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