Design and balance new game levels for Adorable Bites. Use this skill whenever the user wants to create, design, add, or balance a game level — even if they just say "what should level 31 look like" or "add a new level". Also trigger when the user asks about level timing, customer counts, Poisson rates, economy projections, or whether the player can afford things at a certain point. Covers anything related to level design, difficulty tuning, or resource economy planning.
Design new Adorable Bites levels with proper timing, customer counts, arrival rates, and economy balance. Every number is derived from the timing model — no guessing.
Levels are designed 10 at a time in a single docs/levels-X-Y.md file. Each file is self-contained: narrative design, per-level config, AND the resource economy for that batch.
Each batch starts near zero and depletes to near zero (or negative) by the end. Bands operate relatively independently — no large surplus carries across batches.
When a tool is introduced (made available for purchase), the player's expected balance must be negative at that point. They cannot afford it immediately — they must earn over the next few levels before buying.
Once the player buys the tool, customers start ordering recipes that need it. The flow is:
Never introduce a tool and immediately require it in the very next level. There must always be a gap for earning.
Tools can open at any point in a band (beginning, middle, or end). The recommendation is towards the end of a band to set up the next batch, but this is flexible. The hard rule is the negative balance on introduction.
Exception: The very first chair purchase (L1-10 training) can be immediately affordable — this is the player's first shop experience and should feel rewarding, not frustrating.
Items that can be bought multiple times follow a backwards design process:
You always design backwards from the difficulty target, not forwards from the tool availability.
The plan should show a negative balance when a tool becomes available. This is a planning artefact only — in the game, the player simply can't purchase until they have enough. The negative value shows how many levels of earning are needed before the tool is affordable.
Until dishwashing is introduced, customers per level must never exceed plate count. After dishwashing, plates become a reusable resource.
Run the calculator from the repo root:
python3 .claude/skills/create-level/scripts/level_calculator.py --economy # Full economy projection
python3 .claude/skills/create-level/scripts/level_calculator.py --all # Timing for all levels
python3 .claude/skills/create-level/scripts/level_calculator.py 31 --chairs 5 # Analyse specific level
Read the previous batch's docs/levels-X-Y.md to find:
The starting balance for the new band = the previous band's ending balance (in-game this clamps to 0 since you can't spend what you don't have, but the plan tracks the deficit).
For each level, align on:
Ensure:
python3 .claude/skills/create-level/scripts/level_calculator.py --economy
Check:
Create docs/levels-X-Y.md with these sections:
Per-level descriptions with goals, new mechanics, recipes.
| Level | Chairs | Plates | Customers | Arrival | Recipes | Frozen | Duration | New |
|---|
Must include:
This section is read by the next band to set up its starting state. Must include:
### Carry-Forward into Levels X--Y
| Resource | Value |
|----------|-------|
| Money | $XX |
| Snowflakes | XX |
| Purchased chairs | X |
| Purchased plates | X |
| Purchased items | knife_board, ... |
| Unlocked tiers | 1, ... |
#### Available recipes
- Fried Egg, Pan Toast, ...
#### Available ingredients
- egg, bread, butter, ...
#### Tools introduced but not yet purchased
- (tools made available in this band that player can't afford yet — next band must budget for these)
#### Pending shop unlocks
- (tiers or items that unfreeze at the end of this band — next band's first purchases)
This is the ONLY section the next band needs to read. Keep it complete and accurate — run --seed N (where N is the last level) to get the exact balance.
Each 10-level band has a special final level with a Princess Hallmark photo:
For each band's final level:
/generate-art (asset: hallmark_XX)PrincessHallmarkScene.hallmarkEntriesshopEvent: "hallmark" on the final level's LevelConfigprogress.hallmarkPhotosFor the NEXT band's first level, add a new empty frame placeholder in PrincessHallmarkScene.hallmarkEntries.
Add levels to AdorableBites/Models/LevelConfig.swift. Include newIngredients for any level that introduces ingredients.
Add new recipes to RECIPES, new levels to CURRENT_LEVELS, new spending to MONEY_SPENDING / SNOWFLAKE_PURCHASES.
Run --economy and check the Tool Price Validation section at the bottom (runs for average player automatically):
python3 .claude/skills/create-level/scripts/level_calculator.py --economy
Every tool must show ✓ (negative balance after purchase). If any tool shows ✗, raise its price until the balance goes negative. This is a BLOCKING check — do not finalise levels with ✗ violations.
Also verify:
Tool prices are derived from the economy, not guessed. When setting a tool price, look at the average player's running balance at the point of introduction. The price must be higher than that balance (creating a deficit the player earns back over 2-3 levels).
Active time per customer = quiz+pickup (13s/ingredient) + steps (3s/step) + mixer overhead (5s if mixing) + device handling (4s) + post-serve taps (varies by level automation)
Passive time = mixer animation (2s if mixing) + cook time (sum of ingredient cook times, halved for L1-10 training) + eating (6s)
Parallelism overhead: 2 chairs = 1.15, 3 = 1.10, 4 = 1.08, 5 = 1.05
Duration target: 5-7.5 min for post-training levels.