refactor: particle track time synchronization logic

[wumaolinmaoan]

Summary by CodeRabbit

• Refactor
  • Enhanced particle system timing with incremental simulation steps for improved accuracy.
  • Optimized particle system initialization with lazy loading.
  • Simplified particle effect lifecycle management and reduced per-frame overhead for better performance.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The changes refactor the particle system simulation architecture by introducing a new public simulate(time) method that advances particles by a specified time duration, making the existing update(delta) method private. The particle-vfx-item class is refactored to use lazy initialization and frame-stepped simulation, while timeline track cleanup removes redundant particle system helper methods.

Changes

Cohort / File(s)	Summary
Particle System Core packages/effects-core/src/plugins/particle/particle-system.ts	Added public simulate(time: number) method for time-based advancement; made update(delta) private; added runtime guard to skip updates when frozen; internal execution condition narrowed from requiring started and unfrozen to only started.
Particle VFX Item Updates packages/effects-core/src/plugins/particle/particle-vfx-item.ts	Replaced public particleSystem field with private nullable field; added getParticleSystem(context) helper for lazy initialization; removed start() method; refactored processFrame() to use frame-stepped simulation loop with maxSimulateTime constant and multiple simulate() calls instead of direct update() invocations.
Timeline Track Cleanup packages/effects-core/src/plugins/timeline/track.ts	Removed particleSystem field and getParticleSystem() helper from RuntimeClip; simplified end-of-clip logic by eliminating conditional particle-system checks when endBehavior is destroy.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• fix: particles did not replay during the composition replay #1286: Directly related—modifies the same particle system codepaths by adding simulate(time) method, making update(delta) private, and updating callers to use simulate() instead of update().

Suggested reviewers

• yiiqii

Poem

🐰 A rabbit hops through time with grace,
Simulating frames at quickened pace,
No longer frozen, the particles dance,
In stepped increments, they prance and prance,
Lazily born when first they're called,
The system thrives, no longer stalled! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'refactor: particle track time synchronization logic' accurately summarizes the main changes, which involve refactoring time synchronization and simulation logic in the particle system and track components.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

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

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@packages/effects-core/src/plugins/particle/particle-system.ts`:
- Around line 349-358: The simulate method sets this.frozen unconditionally even
when update early-returns because the system hasn’t started; change simulate in
the ParticleSystem class so it only sets this.frozen when a simulation actually
ran (e.g., check this.started before calling update and return early, or have
update return a success boolean and set this.frozen only when that is true),
referencing the simulate, update and started/frozen members and keeping onUpdate
behavior unchanged.

In `@packages/effects-core/src/plugins/particle/particle-vfx-item.ts`:
- Around line 35-37: After resetting the particle system in the time-seek branch
(where you call particleSystem.reset()), ensure the system is re-enabled for
simulation by also calling particleSystem.startEmit() so the internal started
flag is set and subsequent particleSystem.simulate() calls will advance; update
the logic around the reset in particle-vfx-item.ts to call startEmit() after
reset (but only when you intend to resume emitting) to avoid leaving
started=false after a seek-back.