---
title: The Ember Orchard world
date: 2026-06-19
status: draft
tags: [world-design, the-ember-orchard, incubation, delayed-threat, deck-pressure]
modules: [world-data, themes, game-view]
related: [.lore/reference/worlds/authoring/theme-authoring.md, src/game/assets/themes/the-ember-orchard/CATACLYSM.md]
req-prefix: EMBER
---
# The Ember Orchard world
The Ember Orchard is a warm twilight orchard where fruit-stars, village lanterns, hearth-stars, and constellations are bound by an old harvest covenant: take one star, leave one star. The Walker's passage reverses the harvest. Unpicked stars fall into the soil, stored stars hatch in homes and cellars, and the sky goes dark because the constellations are being born on the ground.
Threat verb: **incubate**. The world attacks tempo through delayed consequences. Hazards and rewards can look useful now, then hatch, split, return, or turn stored advantage into world pressure later.
This spec targets a complete first implementation using the current engine vocabulary. It does not require a new timed card-state system. The authored expression of **Dormant Stars** is a world-specific player card plus top-decked world threats, self-transforming hazards, partial-clear punishments, and rewards that deliberately borrow warmth at a known future cost.
## Ratified decisions (2026-06-20)
Resolved with the user during planning and folded into the requirements below (trail: `.lore/work/plans/the-ember-orchard.md`):
- **`Hidden` → `Obstructed`** everywhere. The engine has no `Hidden` keyword (`KeywordName = "Obstructed" | "Creature" | "Slow" | "Spore" | "Concealed"`). REQ-EMBER-12/18/22/23/25/26 now read `Obstructed`.
- **Hatchery Cellar gives a boon choice, not a five-card dump** (REQ-EMBER-26). Its `onCleared` runs `OfferBoon` over the five tools instead of `Sequence[GainCard ×5]`, which floods the deck across the card's copies.
- **Creatures snatch cards** (REQ-EMBER-27/29). Ember Moth and Ground Constellation use `ForceDestroy` rather than `Damage` so the `Brace` reward cards (REQ-EMBER-11/17/19) have something to absorb; without a snatch source `Brace` is inert.
- **Ember Moth drops `ReturnWorldCards`** (REQ-EMBER-27): inert on world auto-hooks (needs player selection input that auto-hooks never supply) and boon-signed where it does fire.
- **Vocabulary** (REQ-EMBER-9): adds `ForceDestroy` and `OfferBoon`, both existing engine effects.
## World Contract
**REQ-EMBER-1:** The world id must be `the-ember-orchard` everywhere: `cards.json`, `meta.ts`, `theme.ts`, `index.ts`, registry entry, `VisualTheme.worldId`, asset keys, and asset binding imports.
**REQ-EMBER-2:** Theme assets must live under `src/game/assets/themes/the-ember-orchard/`. The existing base assets are canonical and must be wired, not regenerated by default:
- `the-ember-orchard-reality.webp`
- `intrusion-overlay.webp`
- `the-ember-orchard-cardfront.webp`
**REQ-EMBER-3:** The implementation must add one inset asset per Ember Orchard card under `src/game/assets/themes/the-ember-orchard/insets/`, use an `ember-inset-*` key namespace, and register every referenced inset key in `src/game/worlds/assetBindings.ts`.
**REQ-EMBER-4:** The world must register through the existing `WorldDataBundle` and `worldDataRegistry` pattern. Do not add one-off theme selection, world building, or manifest code when registry derivation can carry the world.
## Narrative And Identity
**REQ-EMBER-5:** The three-beat fiction is: ordinary star-fruit orchard and village harvest covenant, Walker passage breaks the direction of harvest and makes stored stars hatch, the Door opens in a field of fallen stars and footprint-shaped constellations.
**REQ-EMBER-6:** The Walker, `Summon Door`, and `Door` remain shared starter templates. Ember Orchard data must not redefine any of them.
**REQ-EMBER-7:** The exclusive signature verb is `incubate`: immediate warmth or tempo creates delayed, known future pressure. Ember Orchard reward cards may use draw, brace, progress, and top-deck manipulation, but their identity must be delayed hatching rather than raw damage, Light, Heat, freeze, concealment, Spore scaling, or discard-memory recall.
**REQ-EMBER-8:** The catastrophe identity must appear in the Dormant Star pattern, hazards, rewards, deck composition, display/help copy, visual theme, intrusion overlay, cardfront, and card insets. The world is not "orchard fire"; it is "birth in the wrong place."
## Incubation Without New Core State
**REQ-EMBER-9:** The first implementation must express incubation using existing effects only: `AddWorldCardToDeck`, `AddPlayerCardToTop`, `AddThreatToWorldDeck`, `GainCard`, `OfferBoon`, `Draw`, `DiscardThenDraw`, `ExileTopWorldCards`, `DestroySelf`, `DealProgress`, `DealProgressAll`, `Damage`, `DamageScaled`, `ForceDestroy`, `GainEnergy`, `Brace`, `Modal`, `Sequence`, and `None`. (`ReturnWorldCards` is intentionally **not** used: it is inert on world auto-hooks, which never supply the player selection it reads.)
**REQ-EMBER-10:** The data must use current effect names. `AddWorldCardToDeck` with `bTop: true` is the top-of-world-deck hatch tool; do not use stale `AddWorldCardToTop` wording in authored JSON.
**REQ-EMBER-11:** `Dormant Star` must be a world-specific player card that represents carrying a safe-looking harvested star. Initial shape: energy cost 0, `exhaust: true`, effect `Sequence` of `Draw player 1`, `Brace amount 1`, and `AddWorldCardToDeck { template: "Ember Moth", bTop: true }`. Its role is immediate warmth with a known hatch next in the world deck.
**REQ-EMBER-12:** The world must not add a new `Dormant`, `Incubating`, or timer keyword in the first implementation. Valid authored keywords are only current engine keywords: `Obstructed`, `Creature`, and `Slow` for Ember Orchard cards.
**REQ-EMBER-13:** At least two world hazards must use the self-transform pattern: end-turn `Sequence` of `AddWorldCardToDeck { bTop: true }` followed by `DestroySelf`. This is the shipped "hatch" behavior: the seed/star disappears and its awakened hazard appears next.
**REQ-EMBER-14:** `worldThreatTemplateByWorldId` must map `the-ember-orchard` to `Ground Constellation` so `AddThreatToWorldDeck` repeats the Ember Orchard signature threat.
**REQ-EMBER-15:** Future work may add true timed incubation state, but this implementation must be considered complete without it if the authored deck reliably creates delayed, visible, and recurring hatch pressure.
## Reward Card Recipe
The following numbers are initial tuning. Costs, counts, and exact progress values may change during playtest as long as the roles remain intact.
**REQ-EMBER-16:** `Take One` must be a player reward card that gives strong immediate tempo and plants a future hatch. Initial effect: `Sequence` of `DealProgress base 4` and `AddWorldCardToDeck { template: "Falling Fruit", bTop: true }`. Its role is greed with a known next-world-card cost.
**REQ-EMBER-17:** `Leave One` must be a player reward card that delays or cuts off the next hatch using existing deck tools. Initial effect: `Sequence` of `ExileTopWorldCards amount 1` and `Brace amount 1`, `exhaust: true`. Its role is weak on a quiet board and excellent when a hatch card was just top-decked.
**REQ-EMBER-18:** `Star-Pruner` must be a player reward card that answers Orchard hazards without becoming another world's signature. Initial effect: `DealProgress base 2` with bonus `{ tag: "Obstructed", amount: 2 }` or `{ tag: "Slow", amount: 2 }` after playtest. Its role is pruning planted stars and rooted hazards.
**REQ-EMBER-19:** `Glasshouse Lantern` must be a player reward card that borrows light and risks a future hazard. Initial effect: `Sequence` of `Draw player 2`, `Brace amount 1`, and `AddWorldCardToDeck { template: "Cracked Hearth-Star", bTop: true }`, `exhaust: true`.
**REQ-EMBER-20:** `Constellation Shears` must be a player reward card that handles clusters. Initial effect: `DealProgressAll base 1` with bonus `{ tag: "Creature", amount: 1 }`, `exhaust: true`. It is the late answer to moths and ground constellations.
**REQ-EMBER-21:** Ember Orchard reward cards must not claim another world's exclusive mechanics as their main identity. They must not use `GainLight`, `GainHeat`, `FreezeCards`, `ThawCards`, `BurnForHeat`, `DealProgressScaled`, `Concealed`, or `Spore`.
## World Card Recipe
**REQ-EMBER-22:** `Cracked Hearth-Star` must be an act-1 stored-star hazard. Initial shape: cost 2, `Obstructed`, discardable, `onCleared: GainCard "Dormant Star"`, `onDiscarded: None`, `onPartialClear: None`, `onEndOfTurn: Sequence` of `AddWorldCardToDeck { template: "Ember Moth", bTop: true }` and `DestroySelf`.
**REQ-EMBER-23:** `Falling Fruit` must be an act-1/2 falling-star hazard. Initial shape: cost 2, `Obstructed`, discardable, `onCleared: GainEnergy 1`, `onDiscarded: AddPlayerCardToTop "Dormant Star"`, `onPartialClear: AddPlayerCardToTop "Dormant Star"`, `onEndOfTurn: AddWorldCardToDeck { template: "Rooted Meteor", bTop: true }`.
**REQ-EMBER-24:** `Rooted Meteor` must be an act-2 tempo blocker. Initial shape: cost 3, `Slow`, discardable, `onCleared: None`, `onDiscarded: Damage 1`, `onPartialClear: AddWorldCardToDeck { template: "Falling Fruit", bTop: true }`, `onEndOfTurn: Damage 1`.
**REQ-EMBER-25:** `The Orchard Counts Wrong` must be an act-2 rule-pressure hazard. Initial shape: cost 4, `Obstructed`, discardable, `onCleared: GainCard "Star-Pruner"`, `onDiscarded: Damage 2`, `onPartialClear: AddPlayerCardToTop "Dormant Star"`, `onEndOfTurn: Sequence` of `Draw player 1` and `AddPlayerCardToTop "Dormant Star"`. It should feel like extra draw is advancing incubation.
**REQ-EMBER-26:** `Hatchery Cellar` must be the tool-fetch hazard. Initial shape: cost 6, `Obstructed`, discardable, `onCleared: OfferBoon { setId: "pool-ember-cellar", offeredCount: 3, chooseCount: 1 }` (offers three of the five tools — `Take One`, `Leave One`, `Star-Pruner`, `Glasshouse Lantern`, `Constellation Shears` — and the player keeps one), `onDiscarded: None`, `onPartialClear: None`, `onEndOfTurn: Sequence` adding `Ember Moth` and `Falling Fruit` to the top of the world deck, with the last-added card order verified by tests or adjusted to match engine semantics. *(Ratified 2026-06-20: was `Sequence[GainCard ×5]`, which floods a starter-sized deck across this card's copies; the boon set is authored as a single source shared with the hazards' fixed `GainCard` grants.)*
**REQ-EMBER-27:** `Ember Moth` must be the basic hatched creature, and as a `Creature` it snatches cards rather than dealing HP damage. Initial shape: cost 4, `Creature`, discardable, `onCleared: None`, `onDiscarded: ForceDestroy 2`, `onPartialClear: ForceDestroy 1`, `onEndOfTurn: ForceDestroy 1`. *(Ratified 2026-06-20: damage hooks converted from `Damage` to `ForceDestroy` so the `Brace` rewards have a snatch to absorb — matching the `bird-building` creature-snatch language; the spec's `onEndOfTurn` `ReturnWorldCards` half is dropped as inert and boon-signed.)*
**REQ-EMBER-28:** `Lantern Brood` must be an act-2/3 cluster hazard. Initial shape: cost 4, `Creature` and `Slow`, discardable, `onCleared: GainCard "Leave One"`, `onDiscarded: AddWorldCardToDeck { template: "Ember Moth", bTop: true }`, `onPartialClear: AddWorldCardToDeck { template: "Ember Moth", bTop: true }`, `onEndOfTurn: AddThreatToWorldDeck`.
**REQ-EMBER-29:** `Ground Constellation` must be the act-3 signature threat. Initial shape: cost 6, `Creature` and `Slow`, discardable only with a high penalty, `onCleared: GainCard "Constellation Shears"`, `onDiscarded: ForceDestroy 2`, `onPartialClear: AddWorldCardToDeck { template: "Ember Moth", bTop: true }`, `onEndOfTurn: Sequence` of `DamageScaled { base: 0, per: { kind: "KeywordInHand", keyword: "Creature" }, amount: 1 }` and `AddThreatToWorldDeck`. If Creature-in-hand scaling is too weak or unavailable for visible board pressure, replace the scaled damage with `Damage 2` plus top-decking `Falling Fruit`. *(Ratified 2026-06-20: `onDiscarded` converted from `Damage 3` to `ForceDestroy 2` — the boss creature grips the hand when ignored — while the scaling `onEndOfTurn` keeps real HP pressure so loss stays a fail state.)*
**REQ-EMBER-30:** Every Ember Orchard world card must define `onDiscarded`, `onCleared`, `onPartialClear`, and `onEndOfTurn`. Use `{ "kind": "None" }` for unused hooks.
**REQ-EMBER-31:** At least one early hazard must be low-damage or no-damage when discarded, and at least one mid-game hazard must make clearing versus discarding a meaningful choice. The player must not be soft-locked by repeated top-deck hatching before the reward kit appears.
## Deck Composition
**REQ-EMBER-32:** The deck must have exactly three acts. Act 1 teaches warm harvest and individual dormant costs; Act 2 cracks stored stars and introduces recurrence; Act 3 peaks clustered hatch pressure and converges on the Walker.
**REQ-EMBER-33:** Initial act composition should be:
| Act | Cards |
| --- | --- |
| Act 1 - Warm Harvest | `Cracked Hearth-Star` x3, `Falling Fruit` x3, `Hatchery Cellar` x2 |
| Act 2 - Cracked Lanterns | `Rooted Meteor` x3, `The Orchard Counts Wrong` x2, `Ember Moth` x2, `Hatchery Cellar` x1 |
| Act 3 - Ground Constellation | `Lantern Brood` x2, `Rooted Meteor` x2, `Ember Moth` x2, `Ground Constellation` x2, `The Walker` x1 |
Counts are tuning values; act roles and the fixed Walker closer are not.
**REQ-EMBER-34:** Act 3 must always end with exactly one `{ "templateId": "The Walker", "count": 1 }`.
**REQ-EMBER-35:** The deck must introduce `Hatchery Cellar` early enough that the player can learn the reward kit before clustered hatch pressure arrives. If playtest shows the reward kit appears too late, increase `Hatchery Cellar` count in Act 1 rather than weakening the Act 3 threats first.
## Visual Theme
**REQ-EMBER-36:** The visual keynote is warm harvest orange invaded by impossible violet-magenta and white stellar cores. Suggested values: `intrusionHue #d45cff`, door glow tint `0xd45cff`, warm progress accents in ember gold, danger/destruction accents in hot orange-red, return/retreat accents in cool violet.
**REQ-EMBER-37:** The reality backdrop must remain the warm twilight orchard: orange fruit-stars, village lanterns, crowded impossible botany, ink-line naturalist detail, and harvest-festival warmth.
**REQ-EMBER-38:** The intrusion overlay must show the Counterfall around the perimeter while preserving central play readability: cracked lantern-stars opening like pods, ember-winged hatchlings, meteor-fruit falling into roads and roots, violet-magenta trails bending toward empty footprint geometry, and broken constellation diagrams tangled in branches and furrows.
**REQ-EMBER-39:** The cardfront must read as orchard material under stellar rupture: warm bark, lantern glass, seed-pod cracks, harvest labels, constellation linework, and violet-white hatch cores. Runtime text must remain readable at card scale.
**REQ-EMBER-40:** Card insets must make delayed hatching legible. Hazards should show stars as eggs, moth-seeds, rooted meteors, cracked cellars, and falling constellation fruit. Reward insets should show deliberate harvest choices, pruning tools, lantern glass, and one-star-left covenant imagery.
## Display And Help
**REQ-EMBER-41:** `meta.ts` display copy must describe the place-vs-disaster contrast: a generous star-fruit orchard whose stored warmth is hatching from the inside after the Walker reverses the harvest.
**REQ-EMBER-42:** Help text must fit the existing world help budget and cover: Dormant Stars give immediate warmth but add future hazards, some world hazards hatch into stronger cards at end of turn, partial clears and discards can plant delayed threats, and `Leave One`/`Star-Pruner` are the pressure valves.
**REQ-EMBER-43:** If the world select layout cannot display another world cleanly, Ember Orchard registration may remain data-ready but hidden from normal selection until the layout supports it. `buildWorld("the-ember-orchard")` and `selectTheme("the-ember-orchard")` must still work in tests.
## Documentation
**REQ-EMBER-44:** `.lore/reference/worlds/authoring/theme-authoring.md` must be updated when this world is implemented: add Ember Orchard to the signature verb table and document that `the-ember-orchard` owns incubation-as-delayed-known-cost as its exclusive reward space.
**REQ-EMBER-45:** Any implementation plan derived from this spec must split the work into at least three reviewable slices: world data and registration, assets/presentation/help, and tests/validation. A core-engine slice is only required if implementation chooses to add true timed incubation beyond this spec.
## Tests And Validation
**REQ-EMBER-46:** World data tests must verify no duplicate template ids, all Ember Orchard world cards define all required hooks, all keywords are valid, Act 3 ends with `The Walker`, the Ember Orchard bundle is in `worldDataRegistry`, and `buildWorld("the-ember-orchard")` succeeds.
**REQ-EMBER-47:** Effect/data tests must cover the shipped incubation patterns: `Dormant Star` adds `Ember Moth` to the top of the world deck, `Cracked Hearth-Star` self-transforms into `Ember Moth`, `Falling Fruit` can plant a `Dormant Star`, `Ground Constellation` uses `AddThreatToWorldDeck` through the Ember threat mapping, `Hatchery Cellar` `onCleared` creates a boon offer from the `pool-ember-cellar` pool (not a five-card grant), `Ember Moth` `onEndOfTurn` queues `ForceDestroy` (not HP `Damage`), and a `Brace` charge absorbs a creature snatch end-to-end.
**REQ-EMBER-48:** Asset validation must verify every `ember-inset-*` key, `the-ember-orchard-cardfront`, `the-ember-orchard-bg`, and `the-ember-orchard-overlay` has a matching manifest binding and loads without falling back to starter art.
**REQ-EMBER-49:** Presentation tests or a smoke run must verify `selectTheme("the-ember-orchard")` returns the Ember palette, backdrop, intrusion overlay, and cardfront, and that a representative Ember world card renders with its inset.
**REQ-EMBER-50:** A seeded gameplay test must demonstrate the three-act identity: early Dormant Stars provide immediate benefit, mid-game hazards recur or top-deck hatch cards, and the Act 3 signature threat can repeatedly add Orchard threats until cleared or escaped.
## AI Validation
An AI implementing this spec should verify completion by running or observing:
1. `bun test` passes.
2. A targeted world-data test confirms `buildWorld("the-ember-orchard")`, registry inclusion, unique template ids, valid hooks, valid keywords, and Walker closer.
3. A targeted effect test confirms the Dormant Star, self-transform, top-deck hatch, partial-clear planting, and `AddThreatToWorldDeck` mapping behaviors.
4. Asset validation confirms all `ember-inset-*` keys and base Ember Orchard image keys are registered and preloadable.
5. A local game smoke test can directly start or select `the-ember-orchard`, clear `Hatchery Cellar`, gain at least one reward card, play `Take One` or `Glasshouse Lantern`, and observe a future Orchard hazard placed on top of the world deck.
6. A visual smoke test confirms the warm orchard backdrop, Counterfall overlay, and cardfront render without obscuring the central play area or card text.