Evolution

Evolution stages (typically 3–6) trigger when conditions are met: total XP, specific skill levels, badges earned, coin thresholds. Each stage gets a new look.

Why evolution exists

Evolution is the long-horizon motivator. Coins reward today. Streaks reward this week. Evolution is the story that spans weeks or months: "egg → baby → teen → master".

The image pipeline regenerates art at each stage so the change is visible immediately.

Example

Stage 2 unlocks at total XP ≥ 500 + "Streak 7" badge. When met, evolution.ready fires. If auto-evolve is off, the widget shows an "Evolve now" CTA; when the user taps it, operations.wait returns the new buddy art in 5–20s.

Modes

• Preset — a fixed set of 5 sprite stages per preset.
• Generative — AI-generated art per buddy at each stage. Slower, more unique.
• Hybrid — preset base with a generative overlay for personalised details.

How to set it up

1. Pick an evolution model (preset / generative / hybrid).
2. Set conditions per stage (XP, skill level, badge, coin).
3. Pick a creature style (cute, sci-fi, fantasy, minimal).
4. Decide auto vs. manual evolve.

Gotchas

• evolution.ready fires even if auto-evolve is off. Show an "Evolve now" CTA so the user knows they can trigger it.
• Generative mode takes 5–20s per stage; treat it as an async operation and use operations.wait or the widget's built-in loading state.
• Equipped marketplace items must work on all stages — test early stage equipment against late stage art.