@galacean/engine-core 2.0.0-alpha.32 → 2.0.0-alpha.34

package/package.json

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

package/types/Entity.d.ts

@@ -109,19 +109,19 @@ export declare class Entity extends EngineObject {
      * @deprecated Please use `children` property instead.
      * Find child entity by index.
      * @param index - The index of the child entity
-     * @returns	The component which be found
+     * @returns The entity that was found
      */
     getChild(index: number): Entity;
     /**
      * Find entity by name.
-     * @param name - The name of the entity which want to be found
-     * @returns The component which be found
+     * @param name - The name of the entity to find
+     * @returns The entity that was found
      */
     findByName(name: string): Entity;
     /**
      * Find the entity by path.
      * @param path - The path of the entity eg: /entity
-     * @returns The component which be found
+     * @returns The entity that was found
      */
     findByPath(path: string): Entity;
     /**

package/types/RenderPipeline/BasicRenderPipeline.d.ts

@@ -42,7 +42,7 @@ export declare class BasicRenderPipeline {
      * @param renderElement - Render element
      */
     pushRenderElement(context: RenderContext, renderElement: RenderElement): void;
-    private pushRenderElementByType;
+    private _pushRenderElementByType;
     private _drawBackgroundTexture;
     private _prepareRender;
 }

package/types/RenderPipeline/RenderElement.d.ts

@@ -1,12 +1,23 @@
+import { Renderer } from "../Renderer";
+import { Primitive, SubMesh } from "../graphic";
+import { Material } from "../material";
+import { ShaderData, SubShader } from "../shader";
+import { Texture2D } from "../texture";
 import { IPoolElement } from "../utils/ObjectPool";
-import { RenderQueueFlags } from "./BasicRenderPipeline";
-import { SubRenderElement } from "./SubRenderElement";
+import { SubPrimitiveChunk } from "./SubPrimitiveChunk";
 export declare class RenderElement implements IPoolElement {
     priority: number;
     distanceForSort: number;
-    subRenderElements: SubRenderElement[];
-    renderQueueFlags: RenderQueueFlags;
-    set(priority: number, distanceForSort: number): void;
-    addSubRenderElement(element: SubRenderElement): void;
+    component: Renderer;
+    primitive: Primitive;
+    material: Material;
+    subPrimitive: SubMesh;
+    subShader: SubShader;
+    shaderData?: ShaderData;
+    instancedRenderers: Renderer[];
+    subDistancePriority: number;
+    texture?: Texture2D;
+    subChunk?: SubPrimitiveChunk;
+    set(component: Renderer, material: Material, primitive: Primitive, subPrimitive: SubMesh, texture?: Texture2D, subChunk?: SubPrimitiveChunk): void;
     dispose(): void;
 }

package/types/RenderPipeline/index.d.ts

@@ -1,5 +1,6 @@
 export { BasicRenderPipeline, RenderQueueFlags } from "./BasicRenderPipeline";
-export { BatchUtils } from "./BatchUtils";
+export { VertexMergeBatcher } from "./VertexMergeBatcher";
 export { Blitter } from "./Blitter";
+export { RenderElement } from "./RenderElement";
 export { RenderQueue } from "./RenderQueue";
 export { PipelineStage } from "./enums/PipelineStage";

package/types/Renderer.d.ts

@@ -1,4 +1,4 @@
-import { BoundingBox, Matrix, Vector4 } from "@galacean/engine-math";
+import { BoundingBox, Vector4 } from "@galacean/engine-math";
 import { Component } from "./Component";
 import { Entity } from "./Entity";
 import { RenderContext } from "./RenderPipeline/RenderContext";
@@ -13,13 +13,9 @@ import { ShaderData } from "./shader/ShaderData";
 export declare class Renderer extends Component {
     private static _tempVector0;
     private static _receiveShadowMacro;
-    private static _localMatrixProperty;
-    private static _worldMatrixProperty;
     private static _mvMatrixProperty;
     private static _mvpMatrixProperty;
-    private static _mvInvMatrixProperty;
     private static _normalMatrixProperty;
-    private static _rendererLayerProperty;
     _renderFrameCount: number;
     _maskLayer: SpriteMaskLayer;
     protected _overrideUpdate: boolean;
@@ -31,7 +27,6 @@ export declare class Renderer extends Component {
     private _shaderData;
     private _mvMatrix;
     private _mvpMatrix;
-    private _mvInvMatrix;
     private _normalMatrix;
     private _materialsInstanced;
     private _priority;
@@ -117,11 +112,14 @@ export declare class Renderer extends Component {
     setMaterials(materials: Material[]): void;
     update(deltaTime: number): void;
     /**
-     * Update once per frame per renderer, not influenced by batched.
+     * Update once per frame per renderer.
      */
     protected _update(context: RenderContext): void;
-    protected _updateWorldViewRelatedShaderData(context: RenderContext, worldMatrix: Matrix, batched: boolean): void;
-    protected _updateProjectionRelatedShaderData(context: RenderContext, worldMatrix: Matrix, batched: boolean): void;
+    /**
+     * Update transform shader data for world-space vertices (2D renderers).
+     * Vertices are already in world space, so model matrix is identity.
+     */
+    protected _updateWorldSpaceTransformShaderData(context: RenderContext, onlyMVP: boolean): void;
     protected _updateBounds(worldBounds: BoundingBox): void;
     protected _render(context: RenderContext): void;
     private _createInstanceMaterial;

package/types/animation/Animator.d.ts

@@ -3,13 +3,14 @@ import { Component } from "../Component";
 import { AnimatorController } from "./AnimatorController";
 import { AnimatorControllerLayer } from "./AnimatorControllerLayer";
 import { AnimatorControllerParameter, AnimatorControllerParameterValue } from "./AnimatorControllerParameter";
-import { AnimatorState } from "./AnimatorState";
+import { AnimatorStateInstance } from "./AnimatorStateInstance";
 import { AnimatorCullingMode } from "./enums/AnimatorCullingMode";
 /**
  * The controller of the animation system.
  */
 export declare class Animator extends Component {
     private static _passedTriggerParameterNames;
+    private static _tempScripts;
     /** Culling mode of this Animator. */
     cullingMode: AnimatorCullingMode;
     /** The playback speed of the Animator, 1.0 is normal playback speed. */
@@ -19,7 +20,6 @@ export declare class Animator extends Component {
     protected _updateMark: number;
     private _animatorLayersData;
     private _curveOwnerPool;
-    private _animationEventHandlerPool;
     private _parametersValueMap;
     private _tempAnimatorStateInfo;
     private _controlledRenderers;
@@ -65,16 +65,21 @@ export declare class Animator extends Component {
      */
     update(deltaTime: number): void;
     /**
-     * Get the playing state from the target layerIndex.
+     * Get the state instance currently playing on the target layer.
      * @param layerIndex - The layer index
+     * @returns The state instance, or null if nothing is playing
+     * @remarks The returned instance is tied to the current controller's layer data. After a controller structure change (layers added or removed), the instance is invalidated; re-call this method to get a fresh one.
      */
-    getCurrentAnimatorState(layerIndex: number): AnimatorState;
+    getCurrentAnimatorState(layerIndex: number): AnimatorStateInstance | null;
     /**
-     * Get the state by name.
+     * Get the state instance for a named state on this Animator.
+     * Overrides on the returned instance only affect this Animator.
      * @param stateName - The state name
-     * @param layerIndex - The layer index(default -1). If layer is -1, find the first state with the given state name
+     * @param layerIndex - The layer index (default -1, searches all layers)
+     * @returns The state instance, or null if no state matches
+     * @remarks The returned instance is tied to the current controller's layer data. After a controller structure change (layers added or removed), the instance is invalidated; re-call this method to get a fresh one.
      */
-    findAnimatorState(stateName: string, layerIndex?: number): AnimatorState;
+    findAnimatorState(stateName: string, layerIndex?: number): AnimatorStateInstance | null;
     /**
      * Get the layer by name.
      * @param name - The layer's name.
@@ -107,12 +112,13 @@ export declare class Animator extends Component {
      * @param name - The name of the trigger parameter
      */
     deactivateTriggerParameter(name: string): void;
+    private _resetIfControllerUpdated;
     protected _onDestroy(): void;
     private _crossFade;
     private _getAnimatorStateInfo;
     private _getAnimatorStateData;
     private _saveAnimatorStateData;
-    private _saveAnimatorEventHandlers;
+    private _ensureEventHandlers;
     private _clearCrossData;
     private _addCrossOwner;
     private _prepareCrossFading;

package/types/animation/AnimatorStateInstance.d.ts

@@ -0,0 +1,38 @@
+import { AnimationClip } from "./AnimationClip";
+import { WrapMode } from "./enums/WrapMode";
+/**
+ * Per-Animator view of an `AnimatorState`.
+ *
+ * Override fields (speed, wrapMode) are scoped to this Animator; unset fields
+ * fall through to the underlying state asset.
+ */
+export declare class AnimatorStateInstance {
+    private _speed;
+    private _wrapMode;
+    /**
+     * The name of the underlying state.
+     */
+    get name(): string;
+    /**
+     * The animation clip of the underlying state.
+     */
+    get clip(): AnimationClip;
+    /**
+     * The normalized clip start time of the underlying state.
+     */
+    get clipStartTime(): number;
+    /**
+     * The normalized clip end time of the underlying state.
+     */
+    get clipEndTime(): number;
+    /**
+     * Playback speed for this Animator; overrides the underlying state when set.
+     */
+    get speed(): number;
+    set speed(value: number);
+    /**
+     * Wrap mode for this Animator; overrides the underlying state when set.
+     */
+    get wrapMode(): WrapMode;
+    set wrapMode(value: WrapMode);
+}

package/types/animation/AnimatorStateMachine.d.ts

@@ -12,9 +12,9 @@ export declare class AnimatorStateMachine {
     private _engine;
     /**
      * The state will be played automatically.
-     * @remarks When the Animator's AnimatorController changed or the Animator's onEnable be triggered.
+     * @remarks When the Animator's AnimatorController changed or the Animator's onEnable be triggered. Cleared to `null` if the state is removed via `removeState`.
      */
-    defaultState: AnimatorState;
+    defaultState: AnimatorState | null;
     private _statesMap;
     /**
      * The list of entry transitions in the state machine.

package/types/animation/index.d.ts

@@ -10,6 +10,7 @@ export { Animator } from "./Animator";
 export { AnimatorController } from "./AnimatorController";
 export { AnimatorControllerLayer } from "./AnimatorControllerLayer";
 export { AnimatorState } from "./AnimatorState";
+export { AnimatorStateInstance } from "./AnimatorStateInstance";
 export { AnimatorStateMachine } from "./AnimatorStateMachine";
 export { AnimatorStateTransition } from "./AnimatorStateTransition";
 export { AnimatorConditionMode } from "./enums/AnimatorConditionMode";

package/types/asset/AssetType.d.ts

@@ -44,7 +44,7 @@ export declare enum AssetType {
     Font = "Font",
     /** Source Font, include ttf, otf and woff. */
     SourceFont = "SourceFont",
-    /** AudioClip, include ogg, wav and mp3. */
+    /** AudioClip, include ogg, wav, mp3, m4a, aac and flac. */
     Audio = "Audio",
     /** Project asset. */
     Project = "project",

package/types/graphic/enums/BufferBindFlag.d.ts

@@ -5,5 +5,7 @@ export declare enum BufferBindFlag {
     /** Vertex buffer binding flag. */
     VertexBuffer = 0,
     /** Index buffer binding flag. */
-    IndexBuffer = 1
+    IndexBuffer = 1,
+    /** Constant buffer binding flag (WebGL2 only). */
+    ConstantBuffer = 2
 }

package/types/particle/ParticleGenerator.d.ts

@@ -1,5 +1,6 @@
 import { ParticleStopMode } from "./enums/ParticleStopMode";
 import { ColorOverLifetimeModule } from "./modules/ColorOverLifetimeModule";
+import { CustomDataModule } from "./modules/CustomDataModule";
 import { EmissionModule } from "./modules/EmissionModule";
 import { ForceOverLifetimeModule } from "./modules/ForceOverLifetimeModule";
 import { LimitVelocityOverLifetimeModule } from "./modules/LimitVelocityOverLifetimeModule";
@@ -47,6 +48,8 @@ export declare class ParticleGenerator {
     readonly textureSheetAnimation: TextureSheetAnimationModule;
     /** Noise module. */
     readonly noise: NoiseModule;
+    /** Custom data module. */
+    readonly customData: CustomDataModule;
     private _isPlaying;
     private _instanceBufferResized;
     private _waitProcessRetiredElementCount;

package/types/particle/ParticleMaterial.d.ts

@@ -1,5 +1,6 @@
 import { Engine } from "../Engine";
 import { EffectMaterial } from "../material/EffectMaterial";
+import { Shader } from "../shader/Shader";
 /**
  * Particle Material.
  */
@@ -7,8 +8,9 @@ export declare class ParticleMaterial extends EffectMaterial {
     /**
      * Create a particle material instance.
      * @param engine - Engine to which the material belongs
+     * @param shader - Shader used by the material
      */
-    constructor(engine: Engine);
+    constructor(engine: Engine, shader?: Shader);
     /**
      * @inheritdoc
      */

package/types/particle/index.d.ts

@@ -9,6 +9,7 @@ export { ParticleSimulationSpace } from "./enums/ParticleSimulationSpace";
 export { ParticleStopMode } from "./enums/ParticleStopMode";
 export { Burst } from "./modules/Burst";
 export { ColorOverLifetimeModule } from "./modules/ColorOverLifetimeModule";
+export { CustomDataModule } from "./modules/CustomDataModule";
 export { EmissionModule } from "./modules/EmissionModule";
 export { MainModule } from "./modules/MainModule";
 export { ParticleCompositeCurve } from "./modules/ParticleCompositeCurve";

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

@@ -0,0 +1,82 @@
+import { ParticleCompositeCurve } from "./ParticleCompositeCurve";
+import { ParticleCompositeGradient } from "./ParticleCompositeGradient";
+import { ParticleGeneratorModule } from "./ParticleGeneratorModule";
+/**
+ * Custom data module — exposes any number of named per-particle data channels
+ * (scalars or colors) readable from a custom particle shader by their generated
+ * `renderer_<name>...` uniforms.
+ *
+ * Each stream is one uniform shared across the drawcall, not a per-particle
+ * attribute (unlike Unity's `SetCustomParticleData`); shader-side
+ * differentiation must mix in `a_Random*` / `normalizedAge` / etc.
+ *
+ * Register streams BEFORE attaching the entity to the scene — `ParticleRenderer._onEnable`
+ * uploads on the first frame and won't see entries added afterward.
+ */
+export declare class CustomDataModule extends ParticleGeneratorModule {
+    private static readonly _streamNamePattern;
+    private static readonly _reservedPrefixPattern;
+    private static readonly _zeroCurveArray;
+    private static readonly _zeroGradientColorArray;
+    private static readonly _zeroGradientAlphaArray;
+    private static readonly _zeroColor;
+    private static readonly _zeroVector4;
+    private _curves;
+    private _gradients;
+    private _curveStreams;
+    private _gradientStreams;
+    /**
+     * Curves keyed by name.
+     */
+    get curves(): ReadonlyMap<string, ParticleCompositeCurve>;
+    /**
+     * Gradients keyed by name.
+     */
+    get gradients(): ReadonlyMap<string, ParticleCompositeGradient>;
+    /**
+     * Add a scalar curve. Shader-side uniforms by `curve.mode`:
+     *
+     * | Mode         | Uniforms                                |
+     * |--------------|-----------------------------------------|
+     * | Constant     | `float renderer_<name>MaxConst`         |
+     * | TwoConstants | + `float renderer_<name>MinConst`       |
+     * | Curve        | `vec2 renderer_<name>MaxGradient[4]`    |
+     * | TwoCurves    | + `vec2 renderer_<name>MinGradient[4]`  |
+     *
+     * @param name  - Must contain only letters, digits, or underscores, and not already be in use.
+     * @param curve - Stored by reference.
+     */
+    addCurve(name: string, curve: ParticleCompositeCurve): void;
+    /**
+     * Add a color gradient. Shader-side uniforms by `gradient.mode`:
+     *
+     * | Mode         | Uniforms                                                                                                              |
+     * |--------------|-----------------------------------------------------------------------------------------------------------------------|
+     * | Constant     | `vec4 renderer_<name>MaxConst`                                                                                        |
+     * | TwoConstants | + `vec4 renderer_<name>MinConst`                                                                                      |
+     * | Gradient     | `vec4 renderer_<name>MaxGradientColor[4]`, `vec2 renderer_<name>MaxGradientAlpha[4]`, `vec4 renderer_<name>KeysCount` |
+     * | TwoGradients | + `vec4 renderer_<name>MinGradientColor[4]`, `vec2 renderer_<name>MinGradientAlpha[4]`                                |
+     *
+     * `KeysCount` packs `(colorMin, alphaMin, colorMax, alphaMax)` last-keyframe times for shader-side normalization;
+     * in single-Gradient mode the min lanes mirror the max lanes.
+     *
+     * @param name     - Same validation as {@link addCurve}.
+     * @param gradient - Stored by reference.
+     */
+    addGradient(name: string, gradient: ParticleCompositeGradient): void;
+    /**
+     * Remove a curve. Shader uniforms read 0 after removal.
+     * @param name - The name passed to {@link addCurve}
+     */
+    removeCurve(name: string): void;
+    /**
+     * Remove a gradient. Shader uniforms read 0 after removal.
+     * @param name - The name passed to {@link addGradient}
+     */
+    removeGradient(name: string): void;
+    private _uploadCurveStream;
+    private _uploadGradientStream;
+    private _zeroCurveUniforms;
+    private _zeroGradientUniforms;
+    private _validateName;
+}

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

@@ -6,11 +6,15 @@ import { BaseShape } from "./shape/BaseShape";
  * The EmissionModule of a Particle Generator.
  */
 export declare class EmissionModule extends ParticleGeneratorModule {
+    private static _tempEmitPosition;
     /**  The rate of particle emission. */
     rateOverTime: ParticleCompositeCurve;
     /**  The rate at which the emitter spawns new particles over distance. */
     rateOverDistance: ParticleCompositeCurve;
     _shape: BaseShape;
+    private _distanceAccumulator;
+    private _lastEmitPosition;
+    private _hasLastEmitPosition;
     private _bursts;
     private _currentBurstIndex;
     private _burstRand;
@@ -48,6 +52,7 @@ export declare class EmissionModule extends ParticleGeneratorModule {
      */
     clearBurst(): void;
     private _emitByRateOverTime;
+    private _emitByRateOverDistance;
     private _emitByBurst;
     private _emitBySubBurst;
 }

package/types/shader/ShaderBlockProperty.d.ts

@@ -0,0 +1 @@
+export {};

package/types/shader/ShaderData.d.ts

@@ -8,6 +8,7 @@ import { ShaderProperty } from "./ShaderProperty";
  * Shader data collection,Correspondence includes shader properties data and macros data.
  */
 export declare class ShaderData implements IReferable, IClone {
+    private _batchSharedFields;
     private _macroMap;
     private _refCount;
     /**
@@ -346,5 +347,6 @@ export declare class ShaderData implements IReferable, IClone {
     getProperties(out: ShaderProperty[]): void;
     clone(): ShaderData;
     cloneTo(target: ShaderData): void;
+    private _updateRendererBatchSharedFields;
 }
 export type ShaderPropertyValueType = number | Vector2 | Vector3 | Vector4 | Color | Matrix | Texture | Texture[] | Int32Array | Float32Array;

package/types/shader/ShaderFactory.d.ts

@@ -1,12 +1,22 @@
+import { Engine } from "../Engine";
 /**
  * Shader registry and GLSL utilities. Holds the `#include` lookup table
- * the runtime preprocessor reads, and the GLSL ES 100 → 300 syntax
- * converter the WebGL2 path uses.
+ * the runtime preprocessor reads, the GLSL ES 100 → 300 syntax converter
+ * the WebGL2 path uses, and the GPU-instancing UBO injector that
+ * `ShaderPass` runs over compiled GLSL source.
  */
 export declare class ShaderFactory {
+    static readonly RENDERER_INSTANCE_BLOCK_NAME = "RendererInstanceData";
+    static readonly uniformBlockBindingMap: Record<number, number>;
     static readonly includeMap: Record<string, string>;
     static readonly shaderExtension: string;
+    private static readonly _std140TypeInfoMap;
     private static readonly _has300OutInFragReg;
+    private static readonly _derivedDefines;
+    private static readonly _builtinRendererUniforms;
+    private static readonly _cameraMatrixCandidates;
+    private static readonly _uboUniformRegex;
+    private static _packFuncMap;
     /**
      * Register a chunk source so `#include` resolves it.
      * @param includeName - The path key referenced in `#include "..."`.
@@ -24,5 +34,22 @@ export declare class ShaderFactory {
      * @param isFrag - Whether it is a fragment shader.
      */
     static convertTo300(shader: string, isFrag?: boolean): string;
+    /**
+     * Scan VS/FS for renderer-group `uniform` declarations, replace them with a shared
+     * std140 UBO (instanced array), and emit `#define` remapping so original uniform
+     * names resolve to `rendererData[instanceID].field`.
+     *
+     * Inputs are expected to be already preprocessor-evaluated (no `#ifdef` left).
+     */
+    static injectInstanceUBO(engine: Engine, vertexSource: string, fragmentSource: string): {
+        vertexSource: string;
+        fragmentSource: string;
+        instanceLayout: InstanceBufferLayout | null;
+    };
+    private static _scanInstanceUniforms;
+    private static _buildLayout;
+    private static _buildMissingCameraDecls;
+    private static _buildUBODeclaration;
+    private static _buildFieldDefines;
     private static _replaceMRTShader;
 }

package/types/shader/ShaderPass.d.ts

@@ -16,6 +16,5 @@ export declare class ShaderPass extends ShaderPart {
      * @param tags - Tags
      */
     constructor(name: string, vertexShaderInstructions: ShaderInstruction[], fragmentShaderInstructions: ShaderInstruction[], platformTarget: ShaderLanguage, tags?: Record<string, number | string | boolean>);
-    private _getCanonicalShaderProgram;
     private _compileShaderSource;
 }

package/types/shader/ShaderProgramMap.d.ts

@@ -0,0 +1 @@
+export {};

package/types/shader/enums/ConstantBufferBindingPoint.d.ts

@@ -0,0 +1 @@
+export {};

package/types/trail/TrailRenderer.d.ts

@@ -85,6 +85,6 @@ export declare class TrailRenderer extends Renderer {
     private _addPoint;
     private _getActivePointCount;
     private _addActivePointsToVertexBuffer;
-    private _addSubRenderElement;
+    private _addRenderElement;
     private _onTextureScaleChanged;
 }

package/types/RenderPipeline/SubRenderElement.d.ts

@@ -1,22 +0,0 @@
-import { Renderer } from "../Renderer";
-import { Primitive, SubMesh } from "../graphic";
-import { Material } from "../material";
-import { ShaderData, ShaderPass } from "../shader";
-import { Texture2D } from "../texture";
-import { IPoolElement } from "../utils/ObjectPool";
-import { RenderQueueFlags } from "./BasicRenderPipeline";
-import { SubPrimitiveChunk } from "./SubPrimitiveChunk";
-export declare class SubRenderElement implements IPoolElement {
-    component: Renderer;
-    primitive: Primitive;
-    material: Material;
-    subPrimitive: SubMesh;
-    shaderPasses: ReadonlyArray<ShaderPass>;
-    shaderData?: ShaderData;
-    batched: boolean;
-    renderQueueFlags: RenderQueueFlags;
-    texture?: Texture2D;
-    subChunk?: SubPrimitiveChunk;
-    set(component: Renderer, material: Material, primitive: Primitive, subPrimitive: SubMesh, texture?: Texture2D, subChunk?: SubPrimitiveChunk): void;
-    dispose(): void;
-}