Repository navigation
01 Prototype 04 Upgrade Shop
Design and implement the player-facing shop: a rotating selection of items the player can browse and purchase with friendship. The rotation system ensures the right items appear at the right moments without feeling scripted.
Points: 5 Dependencies: Upgrade Mechanics (item data model), Progression System (friendship economy) Unlocks: The Shopkeeper and the Tinkerer (character integration), UX Design (shop UI pass)
The shop is not available from game start. It unlocks when the player hits a specific milestone. Before that point the player earns friendship but has nowhere to spend it, which creates anticipation. The exact milestone is a narrative and balance decision (see Milestone Design).
Prototype: The full milestone system is a Beta feature. For prototype, the shop unlocks at a hardcoded friendship threshold. The threshold is a tuning target for the Make Fun pass; the default starting point is 50 friendship. The shop panel is hidden and the HUD button is absent until this threshold is crossed.
The shop shows 5 item slots at a time. The player sees the item name, description, and friendship cost. There is no mechanical description. The player discovers what an item does by owning it.
Items can be purchased directly from the shop. Purchased items are added to the player's inventory immediately and their effects apply from that moment. Each item can only be purchased once. Owned items are excluded from the rotation.
When a player destroys an item, a second chance version of that item enters the current act's pool -- same effects, a variant of the original name, same sprite with a shader applied (see Upgrade Mechanics: Item Variants). In Act 1 it re-enters the shop rotation normally. In Act 2 it surfaces through rummaging, which is narratively appropriate: you destroyed something and then find something like it while going through old boxes. If the second chance version is also destroyed, that item is removed from all pools permanently.
The shop is accessible from the HUD at any time. The game continues running behind it. No pause.
The shop refreshes when both triggers have fired:
- Session start. A refresh is queued when the player opens the game.
- Timer. A background timer fires after a set interval while the game is running. Tune interval during Make Fun pass.
Both conditions must be satisfied before the rotation changes. Opening and immediately closing the game does not grant a new rotation -- the timer must also have elapsed. This prevents the player from farming new stock by restarting. An idle player who returns after the timer has run will see new stock as soon as they open the game.
Open problem. Friendship accumulates during idle play. If item costs are too low relative to idle friendship rates, the player can passively afford items without engagement, draining the shop without the decision-making that makes purchasing feel meaningful.
The rotation already limits access (the player can only buy what is currently displayed), which helps. But item costs must be tuned high enough that idle friendship represents meaningful progress toward a purchase, not trivial pocket change. This is a Make Fun pass tuning target.
One mitigation: levelling items at the Tinkerer is the primary ongoing friendship sink. Buying a new item is a decision; levelling it to max is the sustained investment. If levelling costs are appropriately steep, the economy remains meaningful even when idle friendship builds up.
The shop rotation is not random: it is shaped by four layers that work together silently.
Items belong to phase-gated pools (e.g. "pre_break", "post_break", "post_game"). Each pool unlocks at the start of its phase. The rotation can only draw from unlocked pools. New pools entering the rotation makes the shop feel changed without the change being explicitly announced.
When the player owns a max-level item that has a synergy partner (Beta), that partner's weight in the rotation is elevated. The player does not see this. They notice that the other item tends to appear once they have maxed its pair -- which is when they are ready to attempt a synergy anyway.
The elevation lasts for three rotation cycles, then resets. If the player purchases the partner, gravity clears immediately.
In prototype, this layer is implemented but has no visible effect until synergy pairs are authored in Beta.
One of the five slots is reserved as the shopkeeper's pick. This slot draws from a separate narrative pool rather than the main gameplay pool. Narrative items are hand-ordered and paced to match the clue ladder: lighter items early, heavier items as progression deepens.
The main pool is gameplay items: stat modifiers, causality effects. The narrative pool is items with descriptions that carry clue weight, things that feel personal, things the shopkeeper is deliberately putting in front of the player. The player doesn't know the difference. They just notice that one slot sometimes has something that feels different.
As the shopkeeper becomes more distant across pre-break, the pick slot is the first thing that changes. The shopkeeper stops curating. The slot enters the main pool rotation. The narrative items stop appearing. The player loses something they didn't know they had.
Every three rotation cycles, at least one slot must contain an item the player does not own that belongs to a synergy pair they have not yet discovered (if any such items are available in the current pool). Silent guarantee against long periods with no synergy progress visible.
This floor activates only if the normal rotation would otherwise produce a cycle with no synergy-relevant items. It is not visible to the player.
One item per phase pool is designated as the safety net item. It never appears in normal rotation. It surfaces only when both conditions are true simultaneously: the player owns no items and the available pool is otherwise empty (all items owned, destroyed, or unavailable). It is a last resort, not a shortcut. Once purchased it leaves the safety net slot and the player is back in the normal system.
The safety net item should be cheap and mechanically neutral -- something that gets the player moving again without being a meaningful upgrade.
When the pool is empty and the player has 2 or fewer items (but not yet zero), the Tinkerer or Shopkeeper delivers a condition-based hint nudging the player toward clearing their remaining items. See The Shopkeeper and the Tinkerer: Scorched Earth Hint.
With 50 items and 25 synergy pairs, there are C(50,2) = 1,225 possible combinations. The base discovery rate per new attempt is 25/1,225 = 2.0%.
In practice with ~12 items owned, the accessible combination space is C(12,2) = 66 pairs. If 3-5 synergies exist within those pairs, the effective discovery rate on owned items is 5-8%. Paired gravity pushes this higher for items with known synergy partners.
The real pacing lever is the rotation, not the ratio.
Shop closing, post-break item acquisition, and post-game item acquisition are narrative rework territory; the shape lives in ../narrative/outline.md.
Contributing
The game
The Cast
Process
Reference