---
title: City of Sleeping Giants world
date: 2026-06-19
status: draft
tags: [world-design, city-of-sleeping-giants, stirring, recurrence, deck-pressure]
modules: [world-data, themes, game-view]
related: [.lore/reference/worlds/authoring/theme-authoring.md, src/game/assets/themes/city-of-sleeping-giants/CATACLYSM.md]
req-prefix: GIANTS
---
# City of Sleeping Giants world
The City of Sleeping Giants is a violet-cyan metropolis built across bodies too large and too deeply asleep to notice it. The Walker does not wake the giants outright. It gives their sleeping bodies one impossible stimulus to remember: a footprint crossing nerves, roads, bones, bridges, canals, and old wounds that the city mistook for geography.
Threat verb: **stir**. The world attacks through accumulating disturbance. Hazards start as civic tremors, surveys, relocation orders, and infrastructure failures, then return, repeat, or transform as the body beneath the city begins remembering the player's path.
This spec targets a complete first implementation using existing engine vocabulary. It does not require a new shared awareness counter. The authored expression of **Stirring** is top-decked body-reflex hazards, recurring (top-decked) world cards, partial-clear penalties, draw/discard disruption, and reward cards that trade immediate tempo for repeated future pressure.
## Ratified decisions (2026-06-20)
Resolved with the user during planning and folded into the requirements below (trail: `.lore/work/plans/city-of-sleeping-giants.md`):
- **`Hidden` → `Obstructed`** everywhere. The engine has no `Hidden` keyword (`KeywordName = "Obstructed" | "Creature" | "Slow" | "Spore" | "Concealed"`). REQ-GIANTS-19/22/24/25/27 now read `Obstructed`.
- **Recurrence is top-decked, not returned** (REQ-GIANTS-23/27/28/46). `ReturnWorldCards` is inert on world auto-hooks (it reads a player selection auto-hooks never supply), is boon-signed where it does fire, and there is no world discard pile to pull from. Every recurrence hook is re-expressed as `AddWorldCardToDeck { bTop: true }` of the relevant escalation hazard.
- **Surveyors Mark A Pulse gives a boon choice, not a five-card dump** (REQ-GIANTS-24). Its `onCleared` runs `OfferBoon` over the five tools instead of `Sequence[GainCard ×5]`.
- **Tremor / giant-movement hazards snatch cards** (REQ-GIANTS-23/28). Fingerquake Ward and The Giant Turns In Sleep use `ForceDestroy` rather than `Damage` so the `Brace` rewards (Brace The Ward, Bone Pin) have something to absorb; without a snatch source `Brace` is inert. City has no `Creature` cards, so the snatch reads as the body's movement shaking a card loose.
- **Vocabulary** (REQ-GIANTS-9): adds `ForceDestroy` and `OfferBoon`, both existing engine effects.
## World Contract
**REQ-GIANTS-1:** The world id must be `city-of-sleeping-giants` everywhere: `cards.json`, `meta.ts`, `theme.ts`, `index.ts`, registry entry, `VisualTheme.worldId`, asset keys, and asset binding imports.
**REQ-GIANTS-2:** Theme assets must live under `src/game/assets/themes/city-of-sleeping-giants/`. The existing base assets are canonical and must be wired, not regenerated by default:
- `city-of-sleeping-giants-reality.webp`
- `intrusion-overlay.webp`
- `city-of-sleeping-giants-cardfront.webp`
**REQ-GIANTS-3:** The implementation must add one inset asset per City of Sleeping Giants card under `src/game/assets/themes/city-of-sleeping-giants/insets/`, use a `giants-inset-*` key namespace, and register every referenced inset key in `src/game/worlds/assetBindings.ts`.
**REQ-GIANTS-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-GIANTS-5:** The three-beat fiction is: ordinary impossible metropolis built across sleeping giant bodies, Walker passage makes the bodies remember one footprint as a nerve signal, the Door opens where the remembered route bends the city map back into anatomy.
**REQ-GIANTS-6:** The Walker, `Summon Door`, and `Door` remain shared starter templates. City of Sleeping Giants data must not redefine any of them.
**REQ-GIANTS-7:** The exclusive signature verb is `stir`: unresolved or exploited hazards make the same body movement return at a larger or worse scale. Giants reward cards may use draw, deck control, top-deck placement, progress, and bracing, but their identity must be quieting, surveying, bracing, or exploiting body motion rather than Light, Heat, freezing, Spore scaling, concealment, or incubation.
**REQ-GIANTS-8:** The catastrophe identity must appear in reflex hazards, reward tradeoffs, deck composition, display/help copy, visual theme, intrusion overlay, cardfront, and card insets. The world is not "giant monster attacks"; it is "the battlefield becomes a sleeping body's reflex."
## Stirring Without New Core State
**REQ-GIANTS-9:** The first implementation must express Stirring using existing effects only: `AddWorldCardToDeck`, `AddThreatToWorldDeck`, `AddPlayerCardToTop`, `DiscardThenDraw`, `Draw`, `GainCard`, `OfferBoon`, `GainEnergy`, `DealProgress`, `DealProgressAll`, `Damage`, `DamageScaled`, `ForceDestroy`, `Brace`, `DestroySelf`, `Modal`, `Sequence`, `ExileTopWorldCards`, and `None`. (`ReturnWorldCards` is intentionally **not** used: it is inert on world auto-hooks, which never supply the player selection it reads, and there is no world discard pile for it to draw from.)
**REQ-GIANTS-10:** The authored JSON must use current effect names. Top-decking a world card is `AddWorldCardToDeck` with `bTop: true`; do not use stale `AddWorldCardToTop` wording from the cataclysm note.
**REQ-GIANTS-11:** `Minor Tremor` must be the repeatable low-tier stir card. It represents the city feeling the first nerve signal and must be cheap, discardable, and safe enough to teach the recurrence pattern before act-2 reflex pressure.
**REQ-GIANTS-12:** At least two hazards must use the self-transform pattern: end-turn `Sequence` of `AddWorldCardToDeck { bTop: true }` followed by `DestroySelf`. This is the shipped "the district remembers the movement" behavior: the civic problem disappears and its body-reflex consequence appears next.
**REQ-GIANTS-13:** `worldThreatTemplateByWorldId` must map `city-of-sleeping-giants` to `The Giant Turns In Sleep` so `AddThreatToWorldDeck` repeats the City of Sleeping Giants signature threat.
**REQ-GIANTS-14:** Future work may add a true shared `awareness` or `stir` counter that advances at end of turn and triggers threshold reflexes. This implementation must still be considered complete without that counter if authored cards reliably create repeated, escalating body-reflex pressure.
## Reward Card Recipe
The following numbers are initial tuning. Costs, counts, progress values, and exact return ranges may change during playtest as long as the roles remain intact.
**REQ-GIANTS-15:** `Quiet Survey` must be a player reward card that studies the next movement and quiets a small reflex. Initial effect: `Sequence` of `ExileTopWorldCards amount 1` and `Draw player 1`, `energyCost 1`. Its role is deck control plus tempo, representing seeing which body part is about to move.
**REQ-GIANTS-16:** `Brace The Ward` must be a player reward card that answers body-reflex hazards and braces against the snatch when the body shakes a card loose. Initial effect: `Sequence` of `DealProgress base 2 bonus Slow +2` and `Brace amount 1`, `energyCost 1`. Its role is keeping one neighborhood physically quiet.
**REQ-GIANTS-17:** `Follow The Vein` must be a player reward card that exploits body motion for speed while adding future Stirring. Initial effect: `Sequence` of `Draw player 2`, `GainEnergy 1`, and `AddWorldCardToDeck { template: "Vein-Road Surge", bTop: true }`, `energyCost 0`, `exhaust: true`. Its role is useful tempo with a known next-world-card cost.
**REQ-GIANTS-18:** `Bone Pin` must be a player reward card that anchors a plan in the player deck. Initial effect should be `Modal` with branches `AddPlayerCardToTop "Quiet Survey"` and `AddPlayerCardToTop "Brace The Ward"`, `energyCost 1`. If self-referential reward generation proves too repetitive in playtest, replace the branches with `Draw player 1` and `Brace amount 2`; the role remains controlled top-deck anchoring.
**REQ-GIANTS-19:** `Contour Map` must be a player reward card that handles a cluster by reading city-as-body topology. Initial effect: `DealProgressAll base 1 bonus Obstructed +1`, `energyCost 2`, `exhaust: true`. Its role is broad but modest stabilization against civic hazards.
**REQ-GIANTS-20:** Giants 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-GIANTS-21:** `Minor Tremor` must be an act-1 ambient hazard. Initial shape: cost 1, no keywords, discardable, `onCleared: None`, `onDiscarded: None`, `onPartialClear: None`, `onEndOfTurn: Sequence` of `AddWorldCardToDeck { template: "Fingerquake Ward", bTop: true }` and `DestroySelf`.
**REQ-GIANTS-22:** `Relocation Order` must be an act-1 civic hazard that teaches top-of-player-deck disruption. Initial shape: cost 2, `Obstructed`, discardable, `onCleared: GainCard "Quiet Survey"`, `onDiscarded: AddPlayerCardToTop "Panic"`, `onPartialClear: None`, `onEndOfTurn: AddPlayerCardToTop "Panic"`.
**REQ-GIANTS-23:** `Fingerquake Ward` must be an act-1/2 body-reflex hazard, and the tremor shakes a card loose rather than dealing HP damage. Initial shape: cost 3, `Slow`, discardable, `onCleared: GainCard "Brace The Ward"`, `onDiscarded: ForceDestroy 1`, `onPartialClear: AddWorldCardToDeck { template: "Minor Tremor", bTop: true }`, `onEndOfTurn: Sequence` of `ForceDestroy 1` and `AddWorldCardToDeck { template: "Minor Tremor", bTop: true }`. *(Ratified 2026-06-20: `Damage` → `ForceDestroy` so Brace The Ward — this card's own clear reward — has a snatch to absorb; the `onEndOfTurn` `ReturnWorldCards` half is re-expressed as a `Minor Tremor` top-deck since `ReturnWorldCards` is inert on auto-hooks.)*
**REQ-GIANTS-24:** `Surveyors Mark A Pulse` must be the tool-fetch hazard. Initial shape: cost 6, `Obstructed`, discardable, `onCleared: OfferBoon { setId: "pool-survey-results", offeredCount: 3, chooseCount: 1 }` (offers three of the five tools — `Quiet Survey`, `Brace The Ward`, `Follow The Vein`, `Bone Pin`, `Contour Map` — and the player keeps one), `onDiscarded: AddWorldCardToDeck { template: "Minor Tremor", bTop: true }`, `onPartialClear: None`, `onEndOfTurn: AddWorldCardToDeck { template: "Vein-Road Surge", bTop: true }`. *(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-GIANTS-25:** `Vein-Road Surge` must be an act-2 transit/circulation hazard. Initial shape: cost 3, `Obstructed`, discardable, `onCleared: GainEnergy 1`, `onDiscarded: DiscardThenDraw player 1`, `onPartialClear: DiscardThenDraw player 1`, `onEndOfTurn: Sequence` of `DiscardThenDraw player 1`, `AddWorldCardToDeck { template: "Bone Anchor Failure", bTop: true }`, and `DestroySelf`.
**REQ-GIANTS-26:** `Bone Anchor Failure` must be an act-2/3 heavy infrastructure hazard. Initial shape: cost 4, `Slow`, discardable, `onCleared: GainCard "Bone Pin"`, `onDiscarded: Damage 2`, `onPartialClear: AddWorldCardToDeck { template: "Fingerquake Ward", bTop: true }`, `onEndOfTurn: Damage 2`.
**REQ-GIANTS-27:** `District Recall` must be an act-2/3 recurrence hazard that represents neighborhoods being recalled into the body. Initial shape: cost 4, `Obstructed` and `Slow`, discardable, `onCleared: GainCard "Contour Map"`, `onDiscarded: AddWorldCardToDeck { template: "Vein-Road Surge", bTop: true }`, `onPartialClear: AddWorldCardToDeck { template: "Vein-Road Surge", bTop: true }`, `onEndOfTurn: Sequence` of `AddWorldCardToDeck { template: "Vein-Road Surge", bTop: true }` and `AddWorldCardToDeck { template: "Bone Anchor Failure", bTop: true }`. *(Ratified 2026-06-20: both `ReturnWorldCards` hooks re-expressed as top-decked recurrence hazards — `ReturnWorldCards` is inert on auto-hooks and there is no world discard pile.)*
**REQ-GIANTS-28:** `The Giant Turns In Sleep` must be the act-3 signature threat. Initial shape: cost 6, `Slow`, discardable only with a high penalty, `onCleared: None`, `onDiscarded: ForceDestroy 2`, `onPartialClear: AddThreatToWorldDeck`, `onEndOfTurn: Sequence` of `Damage 2`, `AddWorldCardToDeck { template: "Bone Anchor Failure", bTop: true }`, and `AddThreatToWorldDeck`. It should make the player relive the same movement at a larger scale. *(Ratified 2026-06-20: `onDiscarded` `Damage 3` → `ForceDestroy 2` — the giant's shift buries a card — while `onEndOfTurn` keeps `Damage 2` for HP pressure; the `ReturnWorldCards` half is re-expressed as a `Bone Anchor Failure` top-deck.)*
**REQ-GIANTS-29:** Every City of Sleeping Giants world card must define `onDiscarded`, `onCleared`, `onPartialClear`, and `onEndOfTurn`. Use `{ "kind": "None" }` for unused hooks.
**REQ-GIANTS-30:** At least one early hazard must have no discard damage, 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 hazards before `Surveyors Mark A Pulse` can grant the reward kit.
## Deck Composition
**REQ-GIANTS-31:** The deck must have exactly three acts. Act 1 teaches civic tremors and small returns; Act 2 introduces reflex districts and top-deck recurrence; Act 3 peaks repeated body-memory pressure and converges on the Walker.
**REQ-GIANTS-32:** Initial act composition should be:
| Act | Cards |
| --- | --- |
| Act 1 - Civic Tremors | `Minor Tremor` x3, `Relocation Order` x3, `Fingerquake Ward` x1, `Surveyors Mark A Pulse` x3 |
| Act 2 - Reflex Districts | `Fingerquake Ward` x2, `Vein-Road Surge` x3, `Bone Anchor Failure` x2, `District Recall` x1, `Surveyors Mark A Pulse` x2 |
| Act 3 - The Body Remembers | `Bone Anchor Failure` x2, `District Recall` x2, `Vein-Road Surge` x2, `The Giant Turns In Sleep` x3, `The Walker` x1 |
Counts are tuning values; act roles and the fixed Walker closer are not.
**REQ-GIANTS-33:** Act 3 must always end with exactly one `{ "templateId": "The Walker", "count": 1 }`.
**REQ-GIANTS-34:** The deck must introduce `Surveyors Mark A Pulse` early enough that the player can learn quieting and exploitation tools before Act 2 recurrence becomes dense. If playtest shows the reward kit appears too late, increase Act 1 `Surveyors Mark A Pulse` count before weakening the signature threat.
## Visual Theme
**REQ-GIANTS-35:** The visual keynote is violet-cyan city light invaded by emerald vascular glow and bone-white anatomical motion. Suggested values: `intrusionHue #9d6cff`, door glow tint `0x9d6cff`, emerald progress accents, warm violet-pink danger accents, cool cyan return/retreat accents, and bone-white target glow.
**REQ-GIANTS-36:** The reality backdrop must remain the violet-cyan metropolis of bone-white towers, emerald terraces, canals, airships, and continent-sized sleeping figures hidden in plain sight. It should not show a fully awakened titan.
**REQ-GIANTS-37:** The intrusion overlay must show the Remembering around the perimeter while preserving central play readability: violet cracks along vein-roads, lifted bridge/finger geometry, bone anchors pulling free, emerald vascular light under canals and plazas, anatomical contour marks bending toward footprint geometry, and eyelids or knuckles becoming subtly more awake.
**REQ-GIANTS-38:** The cardfront must read as city-map anatomy: street grids, canal lines, bone-white tower silhouettes, survey markings, violet nerve cracks, and emerald circulation underlay. Runtime text must remain readable at card scale.
**REQ-GIANTS-39:** Card insets must make Stirring legible. Hazards should show tremoring wards, marked pulses, vein-roads, bone anchors, district recall geometry, and a sleeping giant's reflex. Reward insets should show survey instruments, braced neighborhoods, vein-following transit routes, bone pins, and contour maps.
## Display And Help
**REQ-GIANTS-40:** `meta.ts` display copy must describe the place-vs-disaster contrast: a beautiful metropolis built on sleeping bodies becomes dangerous when the Walker makes those bodies remember the player's route.
**REQ-GIANTS-41:** Help text must fit the existing world help budget and cover: unresolved hazards can return or top-deck stronger reflexes, some rewards quiet or survey the next movement, `Follow The Vein` gives tempo at the cost of a known future hazard, and the signature threat repeatedly returns known problems until cleared or escaped.
**REQ-GIANTS-42:** If the world select layout cannot display another world cleanly, City of Sleeping Giants registration may remain data-ready but hidden from normal selection until the layout supports it. `buildWorld("city-of-sleeping-giants")` and `selectTheme("city-of-sleeping-giants")` must still work in tests.
## Documentation
**REQ-GIANTS-43:** `.lore/reference/worlds/authoring/theme-authoring.md` must be updated when this world is implemented: add City of Sleeping Giants to the signature verb table and document that `city-of-sleeping-giants` owns Stirring as recurrence/escalation from unresolved or exploited body movement.
**REQ-GIANTS-44:** 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 a true awareness counter beyond this spec.
## Tests And Validation
**REQ-GIANTS-45:** World data tests must verify no duplicate template ids, all City of Sleeping Giants world cards define all required hooks, all keywords are valid, Act 3 ends with `The Walker`, the City bundle is in `worldDataRegistry`, and `buildWorld("city-of-sleeping-giants")` succeeds.
**REQ-GIANTS-46:** Effect/data tests must cover the shipped Stirring patterns: `Minor Tremor` top-decks `Fingerquake Ward`, `Surveyors Mark A Pulse` creates a boon offer from the `pool-survey-results` pool when cleared (not a five-card grant) and top-decks `Vein-Road Surge` if ignored, `Vein-Road Surge` creates `Bone Anchor Failure`, `District Recall` top-decks recurrence hazards (`Vein-Road Surge`; and `Vein-Road Surge` + `Bone Anchor Failure` at end of turn), `Fingerquake Ward` `onEndOfTurn` queues `ForceDestroy` (not HP `Damage`) with a `Brace` charge absorbing the snatch end-to-end, and `The Giant Turns In Sleep` uses `AddThreatToWorldDeck` through the Giants threat mapping.
**REQ-GIANTS-47:** Asset validation must verify every `giants-inset-*` key, `city-of-sleeping-giants-cardfront`, `city-of-sleeping-giants-bg`, and `city-of-sleeping-giants-overlay` has a matching manifest binding and loads without falling back to starter art.
**REQ-GIANTS-48:** Presentation tests or a smoke run must verify `selectTheme("city-of-sleeping-giants")` returns the Giants palette, backdrop, intrusion overlay, and cardfront, and that a representative Giants world card renders with its inset.
**REQ-GIANTS-49:** A seeded gameplay test must demonstrate the three-act identity: Act 1 creates manageable civic tremors, Act 2 hazards repeatedly top-deck related reflex cards, and Act 3 can chain `The Giant Turns In Sleep` until the player clears it, quiets the deck, or reaches the Door.
## 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("city-of-sleeping-giants")`, registry inclusion, unique template ids, valid hooks, valid keywords, and Walker closer.
3. A targeted effect test confirms the Minor Tremor, Surveyors Mark A Pulse, Vein-Road Surge, District Recall, and `AddThreatToWorldDeck` mapping behaviors.
4. Asset validation confirms all `giants-inset-*` keys and base Giants image keys are registered and preloadable.
5. A presentation smoke test confirms the Giants visual theme, backdrop, overlay, cardfront, and at least one themed inset render instead of falling back to starter assets.