Merge origin/main into origin/dev

[yiiqii]

Summary by CodeRabbit

• New Features

  • Introduced an animation graph system with advanced blending, state machines, and parameter control.
  • Added support for animation curves, including position, scale, rotation, Euler, float, and color curves.
  • Enabled configurable drag event exclusion zones and improved drag inertia for interactive elements.
  • Enhanced event system with new play, pause, and resume events for players and compositions.
  • Added new node graph editor tools for creating, editing, and compiling animation graphs.

• Improvements

  • Refined mask handling and transform initialization for components.
  • Improved time tracking and playback synchronization for sprites, particles, and effects.
  • Updated UI and inspector panels for better property editing and visualization.
  • Expanded documentation and changelog with new release entries and feature descriptions.

• Bug Fixes

  • Fixed issues with animation time resets, event triggering during reverse playback, and SSR environment checks.
  • Addressed problems with 3D JSON converter types, spine animation loop ends, and event unbinding.

• Documentation

  • Updated changelogs and version numbers across packages.
  • Added detailed JSON demo scene configuration.

• Chores

  • Updated package versions and dependencies to 2.6.0.

• Refactor

  • Removed unused internal methods and streamlined code for better maintainability.
  • Replaced deprecated methods and improved internal property handling.

• Style

  • Applied minor code style and formatting adjustments for clarity.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

This update introduces a major new animation graph system, including core infrastructure, node types, blending logic, and editor support. It also refactors transform and mask initialization, enhances event emission for playback controls, and adds new features like drag border exclusion and improved time tracking for components. Significant changes span both runtime and editor code, with extensive additions and removals.

Changes

Cohort / File(s)	Change Summary
Changelog & Version Bumps CHANGELOG.md, CHANGELOG-zh_CN.md, packages/effects-core/package.json, packages/effects-helper/package.json, packages/effects-threejs/package.json, packages/effects-webgl/package.json, packages/effects/package.json, plugin-packages/alipay-downgrade/package.json, plugin-packages/downgrade/package.json, plugin-packages/editor-gizmo/package.json, plugin-packages/model/package.json, plugin-packages/multimedia/package.json, plugin-packages/rich-text/package.json, plugin-packages/spine/package.json	Added changelog entries for 2.6.0/2.5.6, updated package versions, and updated dependencies where relevant.
Animation Graph System Core packages/effects-core/src/components/animator.ts, .../animation-graph/animation-graph-asset.ts, .../animation-graph/graph-instance.ts, .../animation-graph/graph-node.ts, .../animation-graph/graph-context.ts, .../animation-graph/graph-data-set.ts, .../animation-graph/pose-result.ts, .../animation-graph/pose.ts, .../animation-graph/skeleton.ts, .../animation-graph/blender.ts, .../animation-graph/node-asset-type.ts, .../animation-graph/index.ts, .../animation-graph/nodes/index.ts	Introduced the animation graph system: asset, instance, node, context, pose, skeleton, blender, node registry, and barrel files.
Animation Graph Node Types .../animation-graph/nodes/animation-clip-node.ts, .../animation-graph/nodes/apply-additive-node.ts, .../animation-graph/nodes/blend-node.ts, .../animation-graph/nodes/bool-nodes.ts, .../animation-graph/nodes/const-value-nodes.ts, .../animation-graph/nodes/control-parameter-nodes.ts, .../animation-graph/nodes/layer-blend-node.ts, .../animation-graph/nodes/operator-nodes.ts, .../animation-graph/nodes/state-machine-node.ts, .../animation-graph/nodes/state-node.ts, .../animation-graph/nodes/transition-node.ts	Added node classes for animation clips, blending, additive, boolean logic, constants, control parameters, operators, state machines, states, transitions, and layer blending.
Animation Curve and Value Getter Enhancements .../math/value-getters/color-curve.ts, .../math/value-getters/value-getter-map.ts, .../math/value-getters/vector-curves.ts	Added Vector3Curve, improved max time calculation, updated value getter mapping for new curve types.
Component and Mask Refactors .../components/base-render-component.ts, .../components/effect-component.ts, .../components/shape-component.ts, .../material/mask-ref-manager.ts	Refactored color/mask assignment, internal time tracking, and mask option setting methods.
Composition and Event Enhancements .../composition.ts, .../events/types.ts, .../src/types.ts, .../src/player.ts, packages/effects-threejs/src/three-display-object.ts	Added startTime, getComponent, new play/pause/resume events, and updated event emission logic.
Transform and VFXItem Refactor .../transform.ts, .../vfx-item.ts, .../comp-vfx-item.ts, .../decorators.ts, .../asset-loader.ts	Refactored transform initialization, deprecated color/opacity setters, removed unused properties, and updated class registry accessor.
Migration and 3D JSON Converter .../fallback/migration.ts, plugin-packages/model/src/gltf/json-converter.ts	Updated migration logic for new versioning and property handling; added optional chaining in JSON converter.
Particle System Refactor .../plugins/particle/particle-system.ts, .../plugins/particle/particle-vfx-item.ts	Unified time tracking, removed unused methods, refactored mask handling, and simplified update logic.
Sprite and Effect Component Time Management .../plugins/sprite/sprite-item.ts, .../plugins/cal/calculate-item.ts, .../plugins/cal/calculate-vfx-item.ts	Added time/duration properties, new playable/track classes, and improved animation curve handling.
Interact Component: Drag and Border Range .../plugins/interact/interact-item.ts	Added support for invalid border range (drag exclusion near edges), speed property, and refined event logic.
Spine Component Mask and Animation Queue plugin-packages/spine/src/spine-component.ts	Refactored mask assignment, renamed lifecycle method, and changed animation queuing to use addAnimation.
Text Plugin Cleanup .../plugins/text/text-item.ts	Removed unused interface TextItemProps.
Post-Process Pass Minor Fix .../render/post-process-pass.ts	Switched from loose to strict equality.
Editor: Node Graph System Overhaul web-packages/imgui-demo/src/panels/node-graph/node-graph.ts, .../tools-graph/*, .../visual-graph/*, .../panels/node-graph/bezier-math.ts, .../panels/node-graph/compilation.ts, .../panels/node-graph/visual-graph/im-rect.ts, .../panels/node-graph/visual-graph/imgui-x.ts, .../panels/node-graph/visual-graph/comment-node.ts, .../panels/node-graph/visual-graph/index.ts	Major refactor: replaced old node flow system with a new visual node graph/editor, added graph compilation, new node/graph/pin classes, drawing context, utilities, and color constants.
Editor: Node Graph System Removals web-packages/imgui-demo/src/panels/node-graph/base-node.ts, .../node-flow.ts, .../pin.ts, .../link.ts	Removed legacy node flow, pin, and link classes.
Editor: Demo and Inspector Updates web-packages/imgui-demo/src/demo.json, .../ge.ts, .../object-inspectors/vfx-item-inspector.ts, .../panels/inspector.ts, .../core/asset-data-base.ts, .../custom-editors/editor.ts	Added external demo JSON, updated initialization, improved inspector with default fallback, and refactored property rendering.
Web Demo: Event Logging web-packages/demo/src/interactive.ts	Added logging for new play, pause, and resume events.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Player
  participant Composition
  participant Animator
  participant AnimationGraph

  User->>Player: play()
  Player->>Composition: play()
  Composition->>Animator: onStart()
  Animator->>AnimationGraph: initialize()
  loop update
    Player->>Composition: onUpdate(dt)
    Composition->>Animator: onUpdate(dt)
    Animator->>AnimationGraph: evaluateGraph(dt)
    AnimationGraph->>Animator: PoseResult
    Animator->>Composition: apply pose
  end
  Player-->>User: emit 'play' event
  Player-->>User: emit 'pause'/'resume' event (on state change)

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~90+ minutes

• Complexity: Extensive new features (animation graph system), major refactors, and editor overhaul.
• Scope: Dozens of files across runtime and editor, with many high-complexity additions and removals.
• Review Time: Will require deep architectural and integration review.

Possibly related PRs

• fix: migration add json version modify #1107: Updates JSON scene version fields and migration logic, directly related to migration changes here.
• refactor: transform initialization #1076: Refactors transform initialization in the same files (transform.ts, vfx-item.ts), matching the changes in this PR.
• feat: add animation graph system #1064: Implements core animation graph system, matching the major feature additions in this PR.

Suggested reviewers

• wumaolinmaoan

Poem

In fields of code where rabbits leap,
A graph of motion, wide and deep—
Nodes and blends, with poses spun,
New timelines dance, old flows undone.
With paws on keys, we bound ahead,
Animation dreams now widely spread!
🐇✨

Note

⚡️ Unit Test Generation is now available in beta!

Learn more here, or try it out under "Finishing Touches" below.

✨ Finishing Touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch main

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai generate unit tests to generate unit tests for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.