Zoo Simulator — Game Design Overview

Status: LIVE — shipped game (457+ player accounts). Open issues are tracked in the live regression surfaces (see Known Issues), not a static table.

Doc status: COMPLETE — full code extraction done; all mechanics verified against Java source. (Game status is LIVE — see the header above.)

Zoo Simulator is a management sim where players build habitats, acquire 35+ species (plus 16 premium), breed animals with genetic traits and rare variants, train 20 behaviors, install 21 enrichment types, attract visitors, and grow their zoo through a 7-phase daily simulation. Two currencies: Zoo Bucks (gameplay) and Golden Tickets (premium, for mythical creatures and fantasy zones).

Game Identity

Property	Value
play_game ID	zoo
skill_identifier	ZOO_SIMULATOR

Launch greeting

The returning-director launch () is a wall if it is long or broken.

• Name. Speak spokenZooName: a blank or leftover-command name (for example at wildlife center from name my zoo at wildlife center) falls back to your zoo. Never leave a hole after Director..
• Sick animals. The while-you-were-away recap states animals needing care once. suppresses the duplicate Alert: N animals need medical attention trailer on LAUNCH.
• Balances. Million-and-up Zoo Bucks compact through PurchaseVoiceFormatter.spokenIntegerOrComma (about one point two billion), not a fifteen-word cardinal.
• Subscribe pitch. One spoken subscribe prompt per player per seven days. Status, habitat VIP, and advance-day missed-bonus pitches share that cooldown.
• A visit left open. A launch while the player is still visiting another zoo ends the visit first: expansion-model.md § A visit ends when the player leaves the skill.

Directors who came to chat

Some directors open Zoo Simulator for the chat and never build: chat turns are among a zoo game's most common actions, and many accounts have no zone. speaks for the empty zoo twice, both only while the account has no zone:

• On the fifth chat turn of a session (any action claims), once: "While you chat, your zoo sits empty. Say build zone africa to open your first zone, then you can keep talking." The count and the once-a-session marker are the session-scoped UserCountKeys ZOO_CHAT_TURNS_WITH_NO_ZONE and ZOO_EMPTY_ZOO_INVITE_HEARD, removed when a session starts.
• On exit: "Your zoo is still empty. Next time, say build zone and we will open the gates." | Genre | Zoo management simulation | | Engine | Turn-based management with 7-phase daily simulation | | DB Schema | zoo_simulator |

Design Pillars

1. Animal Welfare First — Health, happiness, and enrichment drive everything; neglect = death
2. Breeding Depth — Multi-generational genetics with 7 rare variants and 14 genetic traits
3. Premium Fantasy — Golden Tickets unlock mythical creatures (Dragon, Phoenix, Unicorn) and sci-fi zones
4. Daily Rhythm — 7-phase simulation creates meaningful progression each "advance day"

Core Loop

Manage zoo:
  → Build zones (10 themes) with habitats (11 types)
  → Acquire animals (every constant of `llitd.model.zoosimulator.enums.Species`, plus `PremiumAnimal`)
  → Hire staff (vets treat 5/day, maintenance upkeep)
  → Train behaviors (20 types, species-specific)
  → Install enrichments (21 types with durability)
  → Build attractions (6 types) and promotions (4 types)
  → "advance day" → 7-phase simulation
    → Events, health/aging, breeding, visitors, revenue, expenses, cleanup
    → Scoring updated (zoo/welfare/satisfaction/conservation)

---

Daily Simulation (7 Phases)

Phase	Name	Processing
1	Events	Random events triggered
2	Health	Aging (+1 month), sickness checks, vet auto-treatment (8/vet/day), elderly decline, death at 0 HP
3	Breeding/Training/Enrichment	Breeding progress, training advancement, enrichment durability tick
4	Visitors	Visitor generation based on zoo quality (morale 50-70 base)
5	Revenue	Ticket sales + 25% subscriber bonus
6	Expenses	Staff wages, habitat upkeep, event costs
7	Cleanup	Expired promotions removed, scoring updated

---

Animals

35 Base Species (with Prices)

Price	Species
5,000	Panda, Tiger, Elephant
4,500	Polar Bear, Gorilla
4,000	Lion, Bear, Giraffe
3,500	Shark, Dolphin
2,500	Zebra, Kangaroo, Crocodile
2,000	Eagle, Penguin, Seal, Monkey, Wolf, Deer
1,800	Otter, Flamingo
1,500	Fox, Owl
1,000	Parrot, Snake, Turtle

Growth Stages (6)

Stage	Age (months)	Size	Can Breed	Care Multiplier
Newborn	0-2	0.2x	No	2.0x
Infant	3-5	0.4x	No	1.5x
Juvenile	6-11	0.6x	No	1.2x
Adolescent	12-23	0.8x	No	1.0x
Adult	24-125	1.0x	Yes	1.0x
Elderly	126+	0.95x	No	1.3x

Stage uses exclusive upper bounds: age >= minAge && age < maxAge (e.g., Newborn matches ages 0 and 1 and 2, but not 3).

Aging & Lifespan

• 1 game day = 1 month of animal age
• Average lifespan: 180 months (15 years of game time)
• Elderly threshold: 126 months (70% of lifespan)
• Elderly health decline: -2/day (automatic)
• Death at 0 health

Age-Based Appeal Multiplier

Age Range	Appeal Multiplier
0-12 months	0.6 → 1.0 (growing)
12-24 months	1.0 → 1.3 (adolescent)
24-72 months	1.3 → 1.5 (prime)
72-120 months	1.5 → 1.0 (declining)
120+ months	max(0.5, declining)

7 Personalities

SHY, PLAYFUL, AGGRESSIVE, CALM, CURIOUS, LAZY, ENERGETIC

Health System

Illness severity and costs:

Severity	Treatment Cost	Untreated Decline/Day	Treated Recovery/Day	Cure Threshold
MILD	500	-3	+10	≥90
MODERATE	1,500	-7	+7	≥75
SEVERE	3,000	-15	+5	≥60

Vets auto-treat up to 8 animals per day per vet (reactive throughput). This is the treat-the-sick-queue knob and is intentionally higher than the preventative-coverage divisor (still 5 animals per vet — see Staff below): raising throughput eases the manual treat-sick grind without changing how often animals fall ill, and is self-balancing because each auto-treatment still deducts the per-severity Zoo Bucks cost (500 / 1,500 / 3,000).

---

Breeding & Genetics

Breeding Flow

BreedingStatus: ELIGIBLE → BREEDING → GESTATING → COOLDOWN → (repeat)

• Requires male + female of same species, both ADULT stage
• compatibilityScore affects success rate
• expectedOffspring count determined per pair
• rareVariantChance + potentialRareVariant calculated from parents
• bothParentsRare flag for enhanced variant chances
• generationNumber increments (1 = purchased, 2+ = bred)

7 Rare Variants

Variant	Appeal Multiplier	Value Bonus	Description
Chimera	3.5x	+600	Split coloring, two patterns
Albino	3.0x	+500	Pure white with red/pink eyes
Golden	2.8x	+450	Golden/yellow coloration
Melanistic	2.5x	+400	All black coloration
Erythristic	2.2x	+350	Unusual red/orange coloring
Leucistic	2.0x	+300	Partial pigmentation loss
Piebald	1.5x	+200	White patches with normal coloring

14 Genetic Traits

Appearance: LARGE_SIZE (+10% size, +5 appeal), SMALL_SIZE, VIBRANT_COLORING (+15 appeal), UNUSUAL_PATTERN (+20 appeal), FLUFFY_COAT (+10 appeal)

Health: ROBUST_HEALTH, WEAK_IMMUNE (-5 appeal), LONGEVITY (+10 appeal), FAST_HEALER

Personality: NATURALLY_CALM (+8 appeal), HIGH_ENERGY, INTELLIGENT (+15 appeal), GENTLE_GIANT (+12 appeal), PERFORMER (+18 appeal)

Each trait has: isDominant, strength, isExpressed, inheritanceChance

---

Training (20 Behaviors)

Basic (All Species, Level 1-2)

Behavior	Cost	Appeal	Days	Level
Come When Called	50	+100	2	1
Feeding Time Routine	50	+150	3	1
Stay Calm	60	+80	2	1
Health Check Cooperation	75	+100	3	2

Performance (Species-Specific, Level 2-3)

Behavior	Cost	Appeal	Days	Species
Wave	100	+200	3	Seal, Elephant, Bear, Panda
Splash	150	+300	4	Dolphin, Seal, Otter
Roll Over	100	+200	3	Lion, Tiger, Bear, Panda
Balance Ball	200	+400	5	Seal, Elephant
High Five	120	+250	4	Elephant, Bear, Panda, Kangaroo
Roar on Command	200	+400	5	Lion, Tiger, Bear
Play Dead	150	+300	4	Lion, Tiger, Bear, Crocodile
Fetch	180	+350	4	Seal, Otter, Dolphin

Advanced (Level 4-5)

Behavior	Cost	Appeal	Days
Jump Through Hoop	250	+500	6
Synchronized Swim	400	+800	8
Paint With Trunk	300	+600	7
Dance	350	+700	8
Mimic Sounds	280	+550	6

Bird-Specific

Fly to Handler, Wing Display, Talk (Parrot only, +500 appeal)

Training level refers to the minimum animal training level required to learn the behavior (not a behavior's own level). Animals progress through training levels 1-5 via trainingProgress. Basic behaviors require level 1-2, performance behaviors require level 2-3, advanced behaviors require level 4-5.

---

Enrichment (21 Items)

Items have durability (days until replacement needed) and provide happiness/health bonuses.

Key Items

Category	Item	Cost	Happiness	Health	Durability
Physical	Climbing Structure	500	+15	+5	30 days
Physical	Swimming Pool	800	+20	+10	60 days
Food	Puzzle Feeder	400	+15	+5	45 days
Food	Frozen Treat Dispenser	600	+18	+8	40 days
Sensory	Music System	500	+8	0	90 days
Social	Viewing Window	700	+5	0	120 days
Premium	Automated System	3,000	+30	+12	120 days
Premium	Premium Playground	2,000	+25	+10	90 days

---

Zones & Habitats

10 Zone Themes

NORTH_AMERICA, SOUTH_AMERICA, AFRICA, ASIA, EUROPE, AUSTRALIA, ARCTIC, AQUARIUM, RAINFOREST, DESERT

11 Habitat Types

SAVANNA, FOREST, JUNGLE, AQUATIC, ARCTIC, DESERT, MOUNTAIN, WETLAND, GRASSLAND, HATCHERY (egg-layer breeding boost), NURSERY (live-birth newborn destination)

Zone Model

• designRating (0-100), appealBonus (0-100%)
• isPremium flag — 1.5x upkeep multiplier
• Zones contain habitats and attractions

Habitat Model

• maxCapacity — animal limit
• qualityRating (0-100) — affects animal happiness
• cleanliness (0-100) — affects health and visitor satisfaction
• upgradeLevel — quality improvements

---

Visitors & Attractions

Visitor Model

• Initial morale: 50-70 (random)
• Spending capacity: 5-20 Zoo Bucks per visitor
• Morale boosted by: zone themes, attractions, promotions, habitat quality

Attraction Types

Type	Effect
Ride	High visitor draw. A safari train that carries visitors past the habitats
Restaurant	Food revenue + morale boost
Shop	Merchandise revenue
Playground	Family appeal
Viewing Platform	Animal viewing + morale
Petting Zoo	Interactive, high morale
Snack Stand, Aviary, Amphitheater, Aquarium	Cheaper food spend, birds, animal shows, sea life
Restroom	Cheapest build, a small spend per visitor
Hotel	A safari lodge for an overnight stay, the dearest build with the highest spend per visitor

The enum AttractionType is the list, and management.md § Attraction Construction the numbers.

4 Promotion Types

DISCOUNT, SPECIAL_EVENT, ADVERTISING, SEASONAL

Each has: visitorMultiplier, spendingMultiplier, moraleBonus, duration, cost. Expired promotions cleaned in phase 7.

---

Economy

Currencies

Currency	Source	Uses
Zoo Bucks	Ticket sales, visitor spending	Animals, buildings, staff, enrichments
Golden Tickets	Premium (real money)	Premium animals, premium zones

Starting Zoo Bucks: 25,000

Daily Costs

Category	Cost
Veterinarian salary	250/day
Maintenance salary	150/day
Zone upkeep	150/zone/day
Habitat upkeep	100/habitat + 30/animal/day
Attraction upkeep	100/attraction/day
Premium zone multiplier	1.5x

Revenue

• Ticket sales (phase 5) + 25% subscriber bonus
• Attraction revenue per visitor
• Visitor spending based on morale

Debt System

• debt accumulates when expenses exceed balance
• daysInDebt tracks consecutive days

---

Premium Content (Golden Tickets)

16 Premium Animals (4 Tiers)

Tier	Animals	Cost	Appeal
Rare Color (1.5x)	White Tiger, Black Panther, Albino Peacock, Golden Eagle	40-50 GT	600-750
Endangered (2.0x)	Snow Leopard, Giant Panda, Sumatran Rhino, Philippine Eagle	70-85 GT	850-1100
Prehistoric (3.0x)	Dodo Bird, Woolly Mammoth, Saber Tooth Tiger, Quagga	90-150 GT	1200-1700
Mythical (5.0x)	Unicorn, Phoenix, Dragon Hatchling, Griffin	200-300 GT	2000-2600

The starter tickets buy a first rare animal. Every account is granted five starter Golden Tickets on its first launch, and its first premium animal, if it is a White Tiger, a Golden Eagle or an Albino Peacock, costs those five, once per account: an account that bought one at that price, or already owns a premium animal, pays the table price. The premium shop's animal page says so while it holds: "Your five starter tickets cover your first White Tiger, Golden Eagle or Albino Peacock. Say buy premium white tiger." A restart keeps the account's use of it. The rule is ZooStarterPremium; it is the owner's ruling relayed by zeus, decision 7 of msg 22966.

12 Premium Zones (4 Categories)

Category	Zones	Cost	Appeal Multiplier
Historical Eras	Prehistoric Era, Ice Age, Ancient Egypt	75-100 GT	2.0-2.2x
Fantasy Realms	Enchanted Forest, Dragon Sanctuary, Underwater Kingdom	150-200 GT	2.5-3.0x
Sci-Fi	Alien Biosphere, Genetic Lab, Space Habitat	150-200 GT	2.5-3.0x
Extreme	Deep Ocean Trench, Volcanic Island, Cloud Forest	90-110 GT	2.1-2.4x

---

Visitor System

Source: ,

Daily Visitor Count

baseVisitors = 20 + random(0-30)    → 20-50 per day
totalVisitors = baseVisitors + (animalCount × 10) + (premiumAnimalCount × 30)
              + (attractionCount × 5) + premiumZoneBonus
premiumZoneBonus = sum over premium zones of round(60 × (visitorAppealMultiplier − 1))   → +60 (2.0x) to +120 (3.0x) per premium zone (fb 7156-7160)
finalVisitors = round(totalVisitors × vipDecorationMultiplier) × eventVisitorMultiplier

No animals = 0 visitors. Zoo must have at least one animal.

Debt penalty: Each day in debt reduces visitors by 20%, capped at -60%:

reducedVisitors = visitorCount × (1.0 - min(daysInDebt × 0.20, 0.60))

Visitor Properties

Property	Range
Spending capacity	5-20 Zoo Bucks (random per visitor)
Initial morale	50 + random(0-20) + promotion bonus, capped at 100

Morale-Based Spending Multiplier

Morale	Multiplier	Effect
0-39	0.5x-1.0x	Low spending
40-60	0.75x-1.0x	Moderate spending
61-100	1.0x-1.5x	High spending

totalSpent = round(spendingCapacity × moraleMultiplier)

Morale Updates During Visit

appealBonus = min(20, animalVisitorAppeal / 50)
qualityMultiplier = 0.5 + (habitatQuality / 100)    → 0.5x-1.5x
moraleChange = round(appealBonus × qualityMultiplier)

Theme coherence bonus: 1.0 + (themedAnimals/totalAnimals × 0.5) → 1.0x-1.5x Design quality bonus: 0.8 + (designRating/100 × 0.6) → 0.8x-1.4x

---

Attraction Revenue

Source:

Base revenue per visitor: 10 Zoo Bucks × morale multiplier (0.5x-1.5x)

Synergy Bonus (same zone)

Attractions in Zone	Multiplier
1	1.0x
2	1.1x
3	1.2x
4+	1.3x (cap)

Diversity Bonus (different types in zone)

Unique Types	Multiplier
1	1.0x
2	1.08x
3+	1.15x

Combined: synergyMultiplier × diversityBonus

---

Financial System

Source: ,

Daily Upkeep Costs

Category	Cost
Zone upkeep	150/zone/day
Habitat upkeep	100/habitat + 30/animal/day
Attraction upkeep	100/attraction/day
Premium zone multiplier	1.5× (50% more)

Staff

Staff Type	Salary	Hiring Fee	Function
Veterinarian	250/day	5,000	Auto-treats 8 sick animals/day; preventative coverage at 5/vet
Maintenance	150/day	3,000	Future facility condition mechanic

No capacity limit — can hire unlimited staff.

Without vets: illness chance × 1.5 (50% more likely).

Revenue

dailyRevenue = sum(visitor.totalSpent) + attractionRevenue
subscriberRevenue = dailyRevenue × 1.25 (25% bonus)

Debt System

Condition	Effect
Expenses > balance	Deficit added to debt, daysInDebt++
Surplus exists	Surplus pays down existing debt first
Debt fully repaid	daysInDebt resets to 0
Days in debt	-20% visitors per day, max -60%

---

Promotion System

Source:

4 promotion types: DISCOUNT, SPECIAL_EVENT, ADVERTISING, SEASONAL

Property	Range
visitorMultiplier	1.0-1.5×
spendingMultiplier	1.0-1.2×
moraleBonus	0-10 points
duration	Defined by start/end dates

Multiple promotions: take the maximum (not additive). Expired promotions auto-removed in Phase 7.

---

Scoring

Source:

Animal Welfare Score (0-100)

score = (avgHealth × 0.4) + (avgHappiness × 0.4) + (avgHabitatQuality × 0.2) - overcrowdingPenalty

• Overcrowding penalty: -10 per overcrowded habitat, capped at -30
• Empty zoo baseline: 50

Visitor Satisfaction Score (0-100)

Component	Points	Formula
Baseline	0-25	25 if animals+habitats exist; 10 if only habitats; else 0
Variety	0-35	min(35, zoneCount×8 + habitatCount×4 + attractionCount×5)
Design quality	0-20	(avgDesignRating / 100) × 20
Animal variety	0-20	min(20, uniqueSpeciesCount × 2)
Promotions	0-10	10 if any active promotion

Conservation Score (0-100)

Component	Points	Formula
Premium animals	0-40	min(40, premiumAnimalCount × 10)
Species diversity	0-40	min(40, uniqueSpeciesCount × 2)
Habitat upgrades	0-20	min(20, (totalUpgradeLevel × 20) / (habitatCount × 5))

Overall Zoo Score (0-1000)

zooScore = round((animalWelfare × 3.0) + (visitorSatisfaction × 4.0) + (conservation × 3.0))

Weighting: 30% welfare, 40% visitor satisfaction, 30% conservation.

highestZooScore tracks all-time best.

---

Responsive Breakpoints

Breakpoint	Grid Columns	Panel Behavior
< 768px (mobile)	1 column	All panels single column, financial balances stack, animal cards single column
768-1199px (tablet)	2 columns	Overview and Animal panels span full width, others 2-column
>= 1200px (desktop)	3 columns	Overview and Animal panels span full width, others fill 3-column grid

TypeScript Data Model

The frontend defines comprehensive TypeScript interfaces in types/zoo-ui-types.ts that mirror the Java backend models:

Interface	Maps To (Java)	Used By
ZooUiPlayDetails	UiPlayDetails + extensions	ZooManagementDashboard
ZooStatus	Status fields from ZooAccount	ZooStatusPanel
ZooZone	llitd.model.zoosimulator.ZooZone	ZooOverviewPanel
ZooHabitat	llitd.model.zoosimulator.Habitat	ZooOverviewPanel
ZooAnimal	llitd.model.zoosimulator.Animal	AnimalRosterPanel
ZooFinancials	output	FinancialPanel
ZooScoring	output	ScoringPanel
ZooStaff	Staff model from ZooAccount	StaffPanel
ZooEvent	Event data from daily simulation	EventPanel
DailySummary	output	DailySummaryPanel
ZooGridSquare	llitd.model.zoosimulator.ZooGridSquare	ZooOverviewPanel mini grid
ZooAttraction	llitd.model.zoosimulator.Attraction	ZooOverviewPanel
BreedingPair	llitd.model.zoosimulator.BreedingPair	Future breeding panel

Backend Integration

sends text, uiType, the story options list, and -- for the visual dashboard -- three typed projection slices built by . These three are the hot panels the ZooManagementDashboard reads off the live HTTP payload:

Response Field	Source	Status
zooStatus	-- name, currencies, visitors, debt, rating 0-5	POPULATED
zooFinancials	-- last-day P&L + upkeep/staff costs	POPULATED
zooScoring	-- 4-axis score ring + rating 0-5	POPULATED
zooAccount (full graph)		IN-PROCESS ONLY -- @JsonIgnore, never serialized (sf-3163)
zooZones, zooAnimals, zooStaff, zooEvents, zooDailySummary, zooBreedingPairs	--	NOT on the payload -- each is served per turn by its own UiType handler

sf-3163 -- why the full zooAccount is @JsonIgnore. The raw ZooAccount is attached to UiPlayDetails in-process so scenario_tests can reflectively read post-command account state (e.g. game_test.scenario_tests #350 -- admin-set currencies must funnel through ). The field is @JsonIgnore on UiPlayDetails, so the deeply-nested zones-to-habitats-to-animals graph never lands in the live HTTP response -- serializing that graph was the original latency leader, and the frontend reads zero fields from playDetails.zooAccount. The three typed slices above carry exactly what the dashboard panels need; any panel beyond status / financials / scoring is fed per turn by its own UiType handler (ZOO_STATUS, etc.), not by a payload dump. The deferred per-animal maxHealth flatten is tracked in the 2026-05-04 UI audit Section 3 priority 2 (git history).

Future Enhancements

Enhancement	Priority	Description
Visual zoo map	Medium	Interactive grid view of zone layout (uses grid-layout.md spec)
Breeding/genetics panel	Low	Show compatible pairs, trait predictions, breeding progress
Visitor satisfaction chart	Low	Visual breakdown of what visitors liked/disliked
Promotion management	Low	Active promotions with duration countdown
Animal detail modal	Medium	Click animal card → expanded view with training, enrichment, genetics

---

Launch Readiness

Launch Plan: launch-plan.md

Recent Fixes

| 2026-06-20 | 21804 | Multi-zone management discoverability (sources 20035/20225). The zone-scoped commands already existed (zone parsing, .findTargetZone, build-in-zone-N, enter zone N, view zone N, rename zone N) but players found managing MULTIPLE zones confusing because the help never explained them. Pure help-copy plus next-step hints, no new system. .showBuildingHelp rewritten to teach zones-hold-habitats, enter zone 2 or go to zone 2 to set the active zone, build habitat savanna in zone 2 and upgrade habitat in zone 2 to target a zone directly, view zones, view zone 2, and rename zone 2; listCommands gains a dedicated Zones group. .viewZones appends a scope-to-a-zone hint once the player has 2 or more zones; .buildZone appends a per-zone hint naming the new zone number on the 2nd-plus zone. NLU reviewed and already comprehensive for zone phrasings (no rows needed). scenario_tests 2268-2270. | | 2026-06-20 | 21675 | Zoo QoL readout bundle (sources 20035/20225/21436, fb 8634). Per-species report: "tell me about my eagles" / "how many X" now speaks average health and happiness, sick count, a typical full grown weight, where the species lives, and a breeding-readiness hint (.countSpecies). Sort the roster by an attribute: "view animals by health", "sort animals by age, weight, value, appeal, or name" render a flat sorted list so colliding names are distinguishable, optionally scoped to a species. Animal weights ("about N pounds", growth-stage-scaled, display-only) added to the view-animals roster, inspect, and the species report. The buyable-species price listing names each species zone theme ("lion in africa") so a player can choose animals and a first zone together. New display-only facts util (primary theme plus adult weight); NLU openings added for "tell me about" / "tell me about my" to ZOO_COUNT_SPECIES and "sort animals" / "sort by" to ZOO_VIEW_ANIMALS. Read-only, no economy or balance change. scenario_tests 2256-2260. | | 2026-06-02 | 21216 | Natural word-order NLU gap fixed. Saying the theme or animal before the noun, "build north america zone" or "buy white tiger", returned "That command is not available in Zoo Simulator" because Zoo only had "build zone {theme}" and bare "{premium name}" openings, so the natural order fell through the cross-context catch-all to a Blood Lineage one-shot (72 prod cross_context_miss hits for "build north america zone"; player feedback 8466-8469 "not letting me build / command is not available"). Added direct one-shot rows for "build {theme} zone" (10 themes) and "buy {premium animal}" (16 premium animals) routing to ZOO_BUILD_ZONE and ZOO_BUY_PREMIUM_ANIMAL; the handlers already parse the theme or name from originalText. scenario_tests 1825/1826. Also re-validated batch-quarantined scenario_tests 611 (leads with main menu so the deterministic test account persisted feedback-collection state, reloaded by the batch full per-test invalidation, no longer eats the status command), 1527/1528 (build and buy now route so the voluntary-restart refund computes). | | 2026-05-11 | 19064 | Zoo Sim Audio Expansion (accessibility): species SFX for Panda, Giraffe, Shark, Kangaroo, Deer, Turtle and Polar Bear added; resolveAnimalSfx() now maps each to a distinct SoundKey instead of fallbacks (Polar Bear no longer uses BEAR, Giraffe/Kangaroo no longer use HORSE, Shark no longer uses SEA_MONSTER). 9 habitat-type ambient loops (SAVANNA, FOREST, JUNGLE, AQUATIC, ARCTIC, DESERT, MOUNTAIN, WETLAND, GRASSLAND) + HATCHERY ambient added; .viewHabitatDetails() prepends habitat-appropriate ambient via replacemewithsound substitution so the Alexa SSML renderer plays the bed under voice. 17 audio_files rows created via ElevenLabs sound_effect generation + BunnyCDN upload (Soundstripe SFX catalog lacks specific animal calls, ElevenLabs fallback per task guidance). Scenario test 619 covers view habitat aquatic. Feedback 1180/1181 archived (blind-player accessibility request honored). | | 2026-05-11 | 19063 | Zoo Sim QoL Bundle — HATCHERY HabitatType (10th type) + 0.80x egg-layer gestation when both parents in HATCHERY; voice reskin for egg-layer pairs (incubating/days until hatching/carrying eggs); inline definitions on first session encounter for 14 traits + 7 rare variants; .viewGenetics accepts babies/baby/newborn/newborns filter; .startBreedingAll + confirmBatchBreed two-turn flow (pendingBatchBreedSpecies on ZooAccount, 60s expiry); .countSpecies with age-group breakdown; .processGrowthStages enqueues nursery-graduation prompts surfaced by (drops after 2 ignores); baby name pool expanded 8→32 per sex; .feedAll batch (cost upfront +5 happiness); restart NLU synonyms wired to existing confirmRestart; grants 5 starter Golden Tickets via with starter welcome voice line. Feedback 870/1096/1097/1172/1173/1174/1176 archive on deploy.

Date	Task	Fix
2026-07-14	24384	RVF group 283 (finding Z6): repetitive enumeration in the Zoo Goals readout — a fresh zoo speaking five near-identical "You are at 0 of N" clauses (one per goal) in a single response. now rolls per-goal progress into one aggregate "Your progress so far, ..." line (omitted entirely when every active goal is still at zero) and per-goal rewards into one aggregate line ("Each pays N Zoo Bucks" when uniform, "Rewards range from N to M Zoo Bucks" when they differ), instead of repeating a full "You are at X of Y. The reward is Z Zoo Bucks." clause per goal. Per-goal lines now state only the ordinal and description. Guards: JUnit (fresh-zoo zero-progress case, partial-progress aggregation case); ZOO_SIMULATOR scenario suite 393/393 green locally; verified live via play_sequence that the fresh-zoo "goals" response no longer contains "You are at".
2026-07-04	23835	RVF report 199 (GA-Z1/Z2/Z3). GA-Z1: more/keep going now page a truncated option list instead of FALLBACK. buffers the unshown option labels as an option-tail remainder; a NARROW option-more drain in + Tier-0 excludes next/continue so DF inventory-next and DT story-continue are never hijacked (proven by NarrativeContinuationServiceTest + the DF/DT suites). GA-Z2: mapped build mega project/product/megaproject to ZOO_BUILD_MEGAPROJECT AND added the missing process_action_handlers + process_action_registry rows for ZOO_BUILD_MEGAPROJECT (the megaproject feature from was UNREACHABLE - the option-action had no handler registration); added bare upgrade (FREE_FORM prefix, region-scoped via ZoneTheme in .selectHabitatTarget), start the breeding prefix, and deal promotions rows. GA-Z3: feed bird with one owned bird feeds it directly via category resolution instead of a which-animal dump; trimmed the returning-launch preamble (dropped filler + the redundant what-would-you-like prompt, points at status for the full finances). Guards: JUnit ZooAnimalCategoryUtilitiesTest, NarrativeContinuationServiceTest, OptionsReadoutServiceTest, ZooAnimalFeedingHandlerTest, ZooLaunchGeneratorTest, ZooHabitatBuilderHandlerTest; scenario_tests 2583-2588; suites green ZOO 336, DF 413, DT 482, WF 256, BL 207, MM 118.
2026-07-02	23593	RVF group 164 Zoo onboarding + goals surfacing bundle (findings F1, F4, F8, F9, F10). F1: nudges a zone/habitat-but-no-animal zoo to buy a first animal, and reframes a zero-animal advance-day (no dead-tick sim) toward buy animal penguin so the acquire-visitors-revenue loop closes in session one. F8: goals is now a first-class option on every after-action response and on the returning launch. F9: the returning-director launch delivers a while-you-were-away recap (last-day attendance + earnings + animals needing care + next objective). F10: advance-day closes on a next-goal teaser when no goal completed. F4: the goal ladder extends into endgame mastery tiers + a megaprojects template so the richest zoos never run dry, and an exhausted viewGoals points at season status + megaprojects. made public. Guards: scenario_test 2540 (new) + 1862 (adjusted); JUnit , , , , . Design: quests.md + simulation.md.
2026-05-25	20311	Zoo SFX silent on device — root-caused the "no sound effects at all" reports (feedback 7350/7351/7365/7366) to an INCOMPLETE SFX-from-music decouple. 20024 patched only the SSML path () and missed the PRIMARY APLA renderer (), which still gated inline replacemewithsound SFX on hasBackgroundAudio AND derived SFX volume from the background-music volume. Player AMAWNE6X had backgroundMusicVolumeLevel=0 (zeroed by a prior web/UI session via BaseUiPlayEntry.populateCommonBasicProperties, persisted to the shared user_profile cache) with soundEffectsVolumeLevel=null (SFX nominally ON), so every species SFX, habitat ambient bed, and purchase chime was gated out on their Echo. Fix: APLA path now gates SFX on and sizes volume via getSoundEffectsVolume (independent of music, default-ON), matching the SSML path; both renderers + the policy method cross-referenced so the gates can't drift again. JUnit covers music-muted-SFX-on, non-zero SFX volume, and SFX_OFF gating. Audio render model documented in § Sound Effects. FOLLOW-UP (not scheduled): non-Alexa entry handlers persist backgroundMusicVolumeLevel=0 into the shared cross-platform cache and there is no Alexa command to re-enable music — after this fix that suppresses music, not SFX, on Alexa.
2026-05-25	20304	Zoo voice-rendering + system-commands bug fixes (feedback 7378, 7356). viewBabies nursery readout, view animals roster (appendAnimalEntry), view inventory, view habitat details, and view genetics detail rendered the raw uppercase Species enum (FOX, WOLF) plus growth-stage, sex, and rare-variant enums, which Alexa spells letter by letter; all now use formatEnumLowercase so the player hears fox, polar bear, newborn, male, chimera variant. .listCommands now derives the category from the spoken phrase when the matched one-shot NLU row carried no CMD_ value, so saying system commands opens the System Commands detail instead of looping back to the category list (the PRIORITY one-shot rows route LIST_COMMANDS with empty value_type and preempt the menu option). VERIFY-FIRST confirmed on prod that buy-quantity (buy 4 fox buys 4), breed-all (breed all lions reaches the batch-breed preview), and habitat-filtered view (view animals and habitat N) already work on develop — feedback 7352/7376/7355/7367/7372 are a lagging Alexa build, no code change. Audio 7350/7351/7365/7366 are on-device verification, human_task 20311; golden-ticket-refund-on-restart excluded as design. scenario_tests 1511 (system commands) added; 726 assertion updated POLAR_BEAR to polar bear for the voice fix; JUnit ZooBreedingHandlerTest.viewBabies_speaksLowercaseSpeciesAndStage added. Remaining name-fallback spell-out sites (sick report, death notice, escape event, sell, shop) bundled into epic 20317.
2026-05-24	20221	Zoo command and scale bundle. breed-all now resolves WOLF via a plural alias (wolves, the one stem-changing species plural) and routes premium animals (breed all white tigers) to a premium batch-breed path instead of dead-ending at which-species. findEligiblePairs and findPremiumPairs now pair each animal once (1:1 min of males and females) instead of the Cartesian males-by-females product that produced about 74 pairs from 18 lions and ballooned zoos. count by species always emits the adult, young, elderly breakdown and derives growthStage from age so purchased animals (null stored stage) are categorized. Premium zones now apply a flat visitor bonus per zone of 60 times multiplier-minus-one (2.0x gives plus 60, 3.0x gives plus 120 visitors), surfaced via higher visitor count and revenue, the multiplier was previously never read. Advance day caps individually-simulated visitor journeys at 400 and extrapolates average spend to the remaining visitors, keeping large zoos under the Alexa 8s ceiling ( 6-9s timeouts in error_log). Cross-game guild invite hardened: null-guard the inviter chat profile, best-effort notification send so a delivery failure does not orphan the already-created invite, continuation options on lookup-callback errors. scenario_tests 1496/1497/1498; ZooBreedingServiceTest 1:1 pairing coverage. Feedback 7049/7078/7079/7083/7084/7104/7121/7122/7123/7124/7125/7126/7128/7129/7146/7147/7156/7157/7158/7159/7160/7170/7171/7172/7173/7184/7185.
2026-05-22	20019	Zoo player-requested commands (count-by-species, start-over, feed-all) verification + finishing pieces. Code already shipped under 19063 + 18951 + 19076: .countSpecies (with age-group breakdown for small populations), .restartZoo + confirmRestart (two-turn confirmation per design/engine/confirmation-options.md, Golden Tickets preserved per ), .feedAll (cost cap at 30 ZB per animal, abort when balance insufficient). NLU + handler registry already wired. This task added help-menu entries (count-species, feed-all, restart line in showAnimalHelp/showFinancesHelp), process_tests rows for the new commands, scenario_tests via add_scenario_test, admin_message thank-you to player AMAWNE6X for fb 880, 882, 888, 904. Feedback rows 880/882/888/904 already ARCHIVED.
2026-05-19	19896	Zoo nursery/habitat + display bug bundle (fb 6400-6549, 6471). deliverOffspring now picks each newborn's habitat via chooseNewbornDestination: NURSERY in zone, then parents' habitat while it has room, then any same-zone habitat with room, then parents' habitat as last resort — large litters no longer overflow one habitat past maxCapacity while siblings sit empty. findPreferredNurseryHabitat now honors the name-based nursery rule. Nursery-graduation prompt auto-assigns the adult to a habitat with room on the second turn instead of silently dropping it (the voice always promised auto-assign; it was never implemented). view-habitats / view-habitat-details / move-animal full-capacity messages / view-animals filtered view / view-zones habitat counts / premium-shop page numbers switched from X/Y slash to 'X of Y' — Alexa spoke the slash as a fraction, the '0 20/616' garbage players reported. 'build heart attacks' added as a synonym on every build-habitat option (Alexa mis-transcription of 'build habitats'). Day summary now tells the player newborns were placed in habitats. SFX root cause (foreground replacemewithsound SFX gated behind background-music volume) escalated to user_design 19906. scenario_tests 1357/1358; ZooBreedingServiceTest spill coverage added.
2026-04-26	18174	Bug bundle: shop zones session crash now downgrades to recoverable error (try/catch wrap of viewPremiumShop / viewPremiumAnimals / viewPremiumZones in ); 'buy wooly mammoth' / 'buy quagga' / 'buy mammoth' redirected to .buyPremiumAnimal via .extractPremiumAnimal voice-alias matcher (wooly/wooley mammoth, kaigo/quavo/quago/kwagga -> QUAGGA); .createOffspring propagates customSpeciesName/isPremium/rarityTier when both parents share customSpeciesName so baby Unicorns no longer surface as nameless DOLPHIN entries (player feedback 1100/1178 phantom dolphins fix); viewBabies + renderGeneticsList display customSpeciesName when present; renderGeneticsList shows active trait names (up to 2 plus 'plus N more') and ordinal suffix on duplicate names ('Pip 1 of 5'); findAnimalByName parses trailing ordinals so 'view genetics pip 3' deterministically targets the third Pip; excludes premium animals from input-match AND fallback so 'sell' on a premium-only zoo no longer silently sells a 200 GT unicorn for 500 ZB; countZooAssets tracks premiumAnimalCount separately and adds +30 visitors per premium animal on top of base +10 (player feedback 1110-1115 visitor draw); buildPremiumZone surfaces the new zone number plus 'build habitat in zone N' / 'buy premium dragon hatchling' next-step copy (1117); NLU bundle: ZOO_SIMULATOR direct_match=1 process_one_shot_values rows added for feedback / give feedback / send feedback / submit feedback / report bug / report a bug / system commands / system menu (defeats 'feed' Tier 4 prefix-swallow that broke feedback for player Leo, 1297/1298); 'wooly mammoth' / 'mammoth' / 'wooley mammoth' / 'kaigo' / 'quavo' / 'quago' / 'kwagga' synonym rows added to process_alternate_synonyms (ZOO_SIMULATOR / ACTION) so ASR misrecognitions resolve to the right premium animal. Scenario tests 299-306 cover regression. Feedback 1095/1098/1099/1100/1110/1111/1112/1113/1114/1115/1117/1119/1120/1121/1122/1143/1152/1170/1172/1177/1178/1179/1232/1297/1298 archive on verifier deploy.
2026-04-15	17232	Upgrade target selection — / used to always pick the first habitat/attraction regardless of input, so repeat "upgrade" commands hammered one target until it maxed (then every subsequent call failed). Player feedback 347-354 reported "keeps mixing everything up with previous habitat" / "we are not able to have a great any other attractions if we upgrade the 1st 1". Handlers now parse ordinal ("upgrade habitat 2"), type ("upgrade ride"), and zone scope from input; default is the first non-maxed target; response lists other upgradable items so the player can say "upgrade habitat 3" next turn.
2026-04-15	17236	NLU + biome bundle — 30 synonyms added for 15+ fallback phrases (advance the day, play animal, play attraction, new babies, music animals, few animals, standalone zone themes, put/switch/change habitat for move). Quantity-prefix Tier 2 skip fixed: leading number no longer skips OPTIONS tier. Species-aware habitat selection added to ZooHabitatSelector.findTargetHabitat() so animals prefer compatible habitats; mismatch warning shown on fallback placement. Feedback 362/364/365 archived.
2026-04-23	17660	Multi-zone habitat/breed scoping + reward delivery + golden-ticket goodwill + NLU (feedback 783/804/805/857/858/859/860/753/754/755/756). Natural-language zone parsing added to .extractZoneNumber ("zone 2", "in zone 2", "zone number 2"). .findTargetZone now prefers explicit zone > ZooAccount.currentZoneId > first zone, so "build habitat in zone 2" lands in zone 2 instead of silently defaulting to zone 1. Added ZooAccount.lastBreedingSpecies: viewBreedingPairs and the explicit "breed X" path persist the species; startBreeding prefers lastBreedingSpecies over the first-iterated fallback, so "breed snake" then "start breeding" actually breeds snakes instead of whichever species was first in zone iteration. .applyCurrency wired: previously it announced and marked DELIVERED without actually granting currency — Zoo rewards now call .addZooBucks/addGoldenTickets before marking delivered. NLU bundle: rerouted savannah/desert/mountain synonyms from SLOT_* to ZOO_BUILD_HABITAT ACTION; added "bill habitat" (phonetic misrecognition of "build habitat"), "you babies"/"zoo babies" -> ZOO_VIEW_BABIES. Feedback 783 investigation: no ISP_TRIGGERED or purchase_transactions row for customer AMAWNE6X -> manual 100 Golden Ticket goodwill grant + 1000 zoo bucks beta reward queued; logged as Amazon-side funnel drop in isp/experiments.md.
2026-04-21	17588	NLU fallback bundle (7 phrases) — added 5 zoo-context NLU rows: 'jungle' -> ZOO_BUILD_HABITAT, 'rainforest'/'australia' -> ZOO_BUILD_ZONE (FREE_FORM, direct_match=0 following the africa/arctic pattern), 'why animal'/'why animals' -> ZOO_VIEW_ANIMALS (species filter extracted by .parseSpeciesFilter). 'system commands', 'system menu', 'link my account' already had PRIORITY_COMMANDS rows (inserted 2026-04-21 09:31); freeTextCache clear on prod made them live. All 7 phrases now route to real handlers instead of FALLBACK; process_tests 10738-10744 flipped PENDING -> PASSED.

Content Statistics

Content Type	Count
Animal species (base)	35
Premium animals	16
Zone themes	10
Habitat types	11
Attraction types	6
Behaviors (trainable)	20
Enrichment items	21
Genetic traits	14
Rare variants	7
Premium zones	12
Player accounts	156

---

Subsystem Design Docs

Subsystem	Design Doc	Covers
Expansion Model	expansion-model.md	Infinite-growth pivot: seasons as appended themed zone drops, restart as cosmetic re-allocation with full refund, social visit layer, per-tier cost soft caps (decision 2026-05-25, supersedes restart-as-progression)
Goals & Quests	quests.md	APPROVED — Option A lightweight 'Zoo Goals': existing progression made legible/askable by voice (ZOO_VIEW_GOALS), Zoo-Bucks-only idempotent rewards, distinct from the daily ritual. Owner chose lightweight via human_question 21869; design finalized ; Java build queued
Launch Plan	launch-plan.md	7-phase serial launch checklist, SFX audit, Friday session plan
Grid Layout	grid-layout.md	5x5 per-zone grid, placement, adjacency bonuses, visitor pathing, social visiting
Animals	animals.md	Health system, breeding, genetics, training, enrichment
Economy	economy.md	Revenue formulas, upkeep, debt, premium items, construction
Simulation	simulation.md	7-phase daily sim, events, visitor journey, theme bonuses
Management	management.md	Staff, construction, scoring (0-1000), inspections, leaderboard
Player request backlog	player-request-backlog.md	Owner-dispositioned KEEP/DEFER/BUG + Design Fit Gate (standing idea 25328) — 2026-08-01

Sub-Docs In This Directory

Design docs that live alongside this index and were not previously linked from it. Wired in for index-to-sub-doc discoverability by design-audit follow-up (2026-06-15). Read the one matching your task.

Doc	Covers
isp-conversion-review.md	Zoo Simulator ISP Conversion Review