Add Particles System

[CoffeeStraw]

We'd like to design and integrate a lightweight, user-friendly particle system. It will manage a list of pixels (x, y, color, alpha), be able to apply chained per-frame operations, and generates individual ASS override-tagged dialogue lines per pixel. Convert.text_to_pixels and other pixels-related method could potentially integrate with it directly.

---

1. Core Structures

Pixel (already available)

• Immutable: x: float, y: float, color: (r,g,b), alpha: float

Particle

• Dynamic wrapper around Pixel
• Properties: vx, vy, age, lifetime
• update(dt): advances position/age, applies logic (e.g. fade)

ParticleSystem

• Tracks a list of Particle objects

• Attributes: particles, ops, layer, style, resolution, start_time, end_time

• Methods:

  • add_op(op): enqueue operation
  • update(dt): apply ops, clean expired
  • build_line(...): return ASS dialogue strings per pixel
  • __iter__(): yield current Pixel states

2. Effects API (via .add_op(...) helpers)

🔄 Transform

• .translate(dx, dy)
• .rotate(angle, origin)
• .scale(sx, sy, origin)

🎨 Color & Alpha

• .tint(rgb)
• .fade_to(alpha)
• .color_shift(delta_rgb)

⚙️ Physics

• .apply_gravity(gx, gy)
• .apply_drag(coef)
• .apply_wind(fn)

🎲 Randomness

• .jitter(max_dx, max_dy)
• .random_velocity(min_v, max_v)
• .variation(fn)

🔁 Lifecycle

• .on_expire(callback)
• .emit(rate, factory_fn)

🧰 Utility

• .limit(max_count)
• .spin(speed_deg)

3. ASS Output

Each pixel becomes a line with per-pixel override tags:

Dialogue: {layer},{start},{end},{style},,0,0,0,,\1c&H{BGR}&\alpha&H{AA}&\p1{path}

build_line(...) → List[str]

Generates one line per pixel for the given frame range.

4. Example

ps = ParticleSystem(pixels)
ps.random_velocity(20, 50)\
  .apply_gravity(0, 9.8)\
  .fade_to(0)\
  .jitter(0.3, 0.3)\
  .limit(500)

for px in ps:
    use(px.color, px.alpha)

dialogues = ps.build_line(layer=1, start=0, end=3, style="Particles")

If you have thoughts on how to improve it, feel free to start a discussion!