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 the buddy's bare art at each stage. If the buddy has marketplace items equipped, Hatched then renders those items over the new base_image_url and reports that composite through buddy.appearance.

Example

Stage 2 unlocks at total XP ≥ 500 + "Streak 7" badge. When met, evolution.ready fires. If auto-evolve is off, your backend calls buddies.evolve(buddyId) and operations.wait returns the new buddy stage in 5–20s. Check buddy.appearance.status to confirm whether any equipped items have finished rendering on the new stage.

Runtime loop

Event ingestion reports readiness, but the stage transition is a separate operation unless the customer's config has auto_evolve enabled:

const effects = await hatched.events.send({
  eventId,
  userId,
  type: 'lesson_completed',
});

if (effects.evolutionReady) {
  const op = await hatched.buddies.evolve(buddyId);
  await hatched.operations.wait(op.operationId);
}

With auto_evolve: true, Hatched starts that operation when readiness is detected and still emits the evolution.ready webhook for observability.

Appearance after evolve

Evolution commits the stage transition first. Item compositing is attempted in the same operation, but a credit shortage or provider failure does not roll the stage back. Instead, the buddy response exposes:

• base_image_url — the trustworthy bare image for the new stage.
• image_url — the current display image.
• appearance.status — ready, pending, awaiting_credits, or failed.
• rendered_equipped_item_ids — the item layers currently visible in image_url.

Widgets poll /widget/state and show the latest safe visual while a composite is pending. For failed appearances with error.code === 'needs_rerender', call buddies.rerenderAppearance(buddyId) before re-equipping items.

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. In that mode, call buddies.evolve(buddyId) from your backend when you want to advance the stage.
• 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, and monitor buddy.appearance for delayed composites.

Related

• Compositing & stages — how items survive a stage change, and the appearance state machine.
• Buddy & hatch — where a buddy starts.
• Skills — a common evolution trigger.
• Customize buddy — equip + evolve end to end.