# Matchy Cat ## Updated Implementation Briefing ## One-Line Brief A tactical match-3 virtual pet game where players match themed tiles to charge colored resource meters, spend those resources on playful interactions that increase a stubborn cat’s willingness, and then drag the cat to care stations to satisfy its persistent needs. ## Portfolio Setup * **Portfolio Tier**: Vault Adapt, using an existing cat character and proven match-3 structure while focusing new production on character reactions, interaction feedback, and progression. * **Target IP/Anchor**: Matchy Cat. * **Primary Genre**: Match-3 RPG / Virtual Pet / Character Interaction Game. * **Experience Goals**: * Feel Constant Progress through visible movement from board resources to cat willingness and need satisfaction. * Feel Expressive and Seen through direct manipulation of the cat and readable reactions to every action. * **Persona Fit**: Web Gen-Z Drifter, 13+, playing on mobile browsers, desktop browsers, and Chromebooks. Designed for 2–5 minute sessions, pointer-only input, immediate feedback, and minimal reading. --- # Reference Trinity ## Primary Reference: Puzzle Quest: Challenge of the Warlords ### Intended Contribution Define the board economy, colored resource accumulation, action costs, ability availability, and progress against an opposing character. ### Direct Mechanical Mapping | Puzzle Quest | Matchy Cat | | ---------------------------- | ----------------------------------------------------- | | Colored gems | Themed cat-resource tiles | | Colored mana meters | Six colored resource meters | | Spell or ability | Willingness-generator interaction | | Spell mana cost | Combination of colored resource costs | | Enemy health | Cat willingness, or inverse stubbornness | | Damage dealt by spell | Willingness generated by an interaction | | Disabled spell | Interaction without enough colored resources | | Enabled spell | Interaction whose complete resource cost is available | | Spell animation | Timed cat interaction and reaction | | Opponent health reaches zero | Cat becomes willing enough to accept a care action | The board should not generate willingness directly. Successful matches fill the corresponding colored resource meters. Those resources are then spent on willingness-generator actions, such as patting the cat. Each generator has a defined colored-resource cost and a defined willingness reward. Example: * **Puzzle Quest ability**: Stun costs 6 green mana and 5 red mana. * **Matchy Cat interaction**: Pat the Head costs 6 red fish resources and 5 yellow cupcake resources. * **Result**: After the patting interaction completes, the colored resources are spent and the cat gains a defined amount of willingness. This preserves the primary reference’s proven structure: ```text Match gems → Fill colored meters → Activate an affordable action → Play the action → Change the target’s central progress meter ``` ## Secondary Reference: My Talking Tom ### Intended Contribution Provide persistent needs, understandable care goals, emotional familiarity, and a lightweight reason to return. ### Application in Matchy Cat The cat maintains persistent needs such as: * Hunger * Thirst * Hygiene * Play Each short challenge focuses on one active need. The current need determines which care station the player is trying to use. The persistent need creates the reason for the challenge. It does not replace the Puzzle Quest-inspired match-3 economy. ## Tertiary Reference: Clumsy Ninja ### Intended Contribution Define direct character manipulation, physical reactions, interaction timing, and the use of props or stations. ### Application in Matchy Cat The player does not normally drag care items onto the cat. The player drags the cat to an environmental care station or interaction point: * Drag the cat to the food station. * Drag the cat to the water station. * Drag the cat to the brushing station. * Drag the cat to the play station. The cat may resist, grab nearby objects, stumble, pull away, reluctantly participate, or create a short physical-comedy sequence. --- # How the References Come Together Puzzle Quest defines the tactical economy. The player matches themed tiles to accumulate six colored resources. When enough resources are available, willingness-generator actions become enabled. Activating one spends its colored resources and increases the cat’s willingness after a timed interaction. My Talking Tom defines why the player is trying to make the cat willing. The cat has a persistent need, such as hunger, that must be addressed. Clumsy Ninja defines how care is performed. Once the cat is sufficiently willing, the player directly drags the cat to the relevant care station. The cat performs a physical interaction with the station, and the need changes only after that interaction is completed. The full structure is: ```text Match resources → Perform willingness generator → Increase willingness → Drag cat to need station → Spend willingness → Improve need → Repeat ``` --- # Core Economic Model ## 1. Colored Resources Successful matches fill the resource meter associated with the matched tile. The first iteration uses six existing tile types: | Color | Tile Theme | Resource Identifier | | ------ | ------------- | ------------------- | | Green | Tuna can | `GreenTuna` | | Orange | Cat food bowl | `OrangeBowl` | | Purple | Cat food box | `PurpleFoodBox` | | Blue | Milk box | `BlueMilk` | | Red | Fish | `RedFish` | | Yellow | Cat cupcake | `YellowCupcake` | The icons on the board, resource meters, action costs, and resource-transfer effects must use matching shapes and colors. A red fish tile must visibly feed the red fish meter. An action that costs red fish must show the same icon and color. ## 2. Willingness Willingness is the central glue resource connecting match-3 actions to need care. It functions similarly to an adversary’s health in Puzzle Quest, except progress moves upward instead of downward: * Puzzle Quest abilities damage the opponent. * Matchy Cat interactions increase willingness. * Increasing willingness can also be presented as reducing stubbornness. Willingness and stubbornness should not be implemented as two independent values. Recommended relationship: ```text stubbornness = maximumWillingness - currentWillingness ``` The interface may display either willingness increasing or stubbornness decreasing, but the runtime should maintain one authoritative value. ## 3. Willingness-Generator Actions Willingness generators are the equivalent of Puzzle Quest spells. Each generator defines: * One or more colored-resource costs. * A willingness reward. * A duration. * A cat interaction. * A reaction pool. * Whether activating it consumes the player’s turn. * Visual resource-transfer effects. An action remains disabled until every resource requirement is available. Its UI must clearly show: * Required resource icons. * Required amount of each resource. * Current amount available. * Whether the action is affordable. * How much willingness it will generate, where appropriate. ## 4. Care Stations Care stations improve the cat’s active need. Each care station defines: * The need it affects. * Its willingness cost. * The duration of the care interaction. * The amount of need progress. * Its valid cat drop area. * Its refusal reaction. * Its successful reaction pool. The player activates a care station by dragging the cat to it. The player does not activate the station by dragging the food, brush, toy, or water onto the cat. ## 5. Temporary Willingness Rules Willingness is temporary challenge currency. Core rules: 1. Willingness starts at zero when a need challenge begins. 2. Matches do not generate willingness directly. 3. Matches generate colored resources. 4. Willingness-generator actions spend colored resources and generate willingness. 5. Care stations spend willingness and improve the active need. 6. Willingness has a visible maximum capacity. 7. Willingness resets when the active need is resolved or the challenge ends. 8. Willingness does not carry between needs, sessions, or days in the first playable. 9. Care stations remain unavailable when their willingness cost cannot be paid. 10. An unsuccessful attempt to use a locked station does not spend willingness. --- # Timed Interaction Transactions Both willingness-generator actions and care-station actions take time to complete. Resource changes must not be applied immediately when an action begins. ## Transaction Sequence When an interaction starts: 1. Validate that all required resources are available. 2. Reserve the required resources. 3. Disable conflicting input. 4. Begin the cat animation and reaction. 5. Play visual transfers between the UI and the cat. 6. Wait for the action’s completion point. 7. Commit the resource changes. 8. Update the meters. 9. Return control to the player. The displayed meter values change only when the timed action completes. Internally, resources should be reserved at action start to prevent the player from activating multiple actions using the same resource balance. If an action is cancelled or interrupted before its valid completion point: * Release the reservation. * Do not change willingness. * Do not change the need. * Restore player control safely. ## Willingness-Generator Transaction Example: Pat the Head. At action start: * Reserve the required red fish and yellow cupcake resources. * Lock board and action input. * Begin the patting animation. During the interaction: * Small red fish-colored circles travel from the red fish meter toward the cat. * Small yellow cupcake-colored circles travel from the yellow cupcake meter toward the cat. * Willingness-colored circles travel from the cat toward the willingness meter. * The cat performs the appropriate positive or comedic reaction. At action completion: * Subtract the reserved colored resources. * Add the action’s willingness reward. * Refresh action availability. * Return to the board. The resource meters should not visibly decrease and the willingness meter should not visibly increase before the completion point. ## Care-Station Transaction Example: Food station. At action start: * Validate that the station’s willingness cost is available. * Reserve the willingness. * Confirm that the cat has been dragged into the valid station area. * Begin the feeding interaction. During the interaction: * Willingness-colored circles travel out of the willingness meter toward the station or cat. * Hunger-colored circles travel out of the cat toward the hunger indicator. * The cat performs the feeding reaction. * The station visibly participates in the action. At action completion: * Subtract the reserved willingness. * Reduce the cat’s hunger need. * Refresh station availability. * Return control to the board or complete the challenge. The hunger value should decrease toward zero. A presentation based on satisfaction filling upward is also possible, but the internal model and all documentation must use one convention consistently. For the first implementation: ```text Hunger starts above zero. Feeding reduces hunger. The challenge ends when hunger reaches zero. ``` --- # UI Feedback Language The player must be able to understand the economy without reading an explanation. ## Resource Gain from Matches When tiles are matched: * Small circles or particles matching the tile’s color and icon travel from the board to its corresponding meter. * The meter increases after the board resolution completes. * Newly affordable actions pulse or become visibly enabled. * Actions that remain unaffordable continue displaying their missing costs. ## Resource Spending on Willingness Generators During a generator: * Resource-colored particles leave the relevant colored meters. * Those particles travel toward the cat. * Willingness-colored particles travel from the cat to the willingness meter. * Meter changes commit at interaction completion. ## Willingness Spending at a Care Station During care: * Willingness particles leave the willingness meter. * The particles travel to the cat or station. * Need particles leave the cat and move toward the need indicator. * Willingness and need values update at interaction completion. ## Locked Interaction Feedback When the player attempts an unavailable action: ### Unavailable Willingness Generator * The action does not start. * Missing resource costs pulse. * The required icons briefly enlarge or shake. * No resources are reserved. ### Unavailable Care Station * The cat refuses the station. * The station displays or pulses its willingness cost. * The willingness meter responds visually. * No willingness is spent. * The refusal should be short enough not to punish experimentation. --- # Core Loop 1. **Present Need** The cat visibly communicates one active need, such as hunger. 2. **Attempt Care** The player may try to drag the cat to the relevant care station. 3. **Refuse if Unwilling** If willingness is too low, the cat refuses and the station indicates its willingness requirement. 4. **Match Tiles** The player performs a valid match-3 move. 5. **Fill Colored Resources** The matched tile types increase their corresponding colored meters. 6. **Evaluate Generator Actions** Willingness-generator actions become enabled when their complete colored-resource costs are available. 7. **Activate Generator** The player clicks or taps an enabled willingness-generator action. 8. **Perform Timed Interaction** The cat performs the interaction while resource particles communicate what is being spent and gained. 9. **Commit Generator Result** After the interaction completes, colored resources decrease and willingness increases. 10. **Unlock Care Station** When enough willingness is available, the active need station becomes usable. 11. **Drag Cat to Station** The player physically drags the cat to the care station. 12. **Perform Timed Care Interaction** The cat interacts with the station and performs a comedic reaction. 13. **Commit Care Result** After the interaction completes, willingness decreases and the active need improves. 14. **Return to Matching** Board input resumes immediately. 15. **Repeat** The player alternates between matching, willingness generation, and care. 16. **Resolve Need** The challenge ends when the active need reaches its completion condition. 17. **Persist Cat State** The updated need and mood are saved before the next challenge or check-in. --- # First Playable Objective Build one complete hunger challenge using the integrated loop. ## Expected First-Playable Flow 1. The hungry cat visibly needs food. 2. The food station is visible. 3. A valid first match is highlighted. 4. The player swaps two tiles. 5. The colored resource meters associated with the matched tiles fill. 6. The player attempts to drag the cat to the food station. 7. The cat refuses because it is not willing to eat. 8. The food station indicates its willingness requirement. 9. The player performs additional matches. 10. The Pat the Head action becomes active. 11. The action clearly displays its red fish and yellow cupcake costs. 12. The player clicks or taps Pat the Head. 13. The cat performs a positive or comedic patting reaction. 14. Red fish and yellow cupcake particles travel out of their meters toward the cat. 15. Willingness particles travel from the cat toward the willingness meter. 16. After the reaction completes, the colored meters decrease and willingness increases. 17. Matching resumes. 18. The player repeats the match-and-pat loop. 19. After enough willingness has been generated, the food station becomes active. 20. The player drags the cat to the food station. 21. The cat performs a comedic feeding reaction. 22. Willingness particles travel from the willingness meter toward the food station or cat. 23. Hunger particles travel from the cat toward the hunger UI. 24. After the reaction completes, willingness decreases and hunger decreases. 25. Matching resumes immediately. 26. After approximately three successful feeding interactions, hunger reaches zero. 27. The cat enters a satisfied state. 28. The challenge ends. --- # First-Playable Resource Set ## Colored Resource Meters The first playable includes all six board resources even if only some are used by the first generator action. | Meter | Board Tile | First-Playable Requirement | | --------------- | ------------------- | --------------------------- | | Green Tuna | Green tuna can | Accumulates through matches | | Orange Bowl | Orange food bowl | Accumulates through matches | | Purple Food Box | Purple cat food box | Accumulates through matches | | Blue Milk | Blue milk box | Accumulates through matches | | Red Fish | Red fish | Used by Pat the Head | | Yellow Cupcake | Yellow cat cupcake | Used by Pat the Head | Showing all six meters preserves the board economy and makes later generator actions easier to add. The interface may visually compress the meters for small screens, but their current values and action relationships must remain understandable. ## Central Indicators The first playable requires: * Six colored resource meters. * One willingness meter. * One hunger meter. * One Pat the Head action. * One food care station. * Action-cost indicators. * Station willingness-cost indicator. * Active-need indicator. --- # Suggested Willingness Generators The available generators depend on existing vault assets and animation feasibility. The following are design candidates rather than committed content. | Generator | Interaction | Resource Cost | Willingness Reward | Asset Considerations | | ------------------------- | ---------------------------------------------------------- | ----------------------------- | ------------------ | -------------------------------------------------------------- | | **Pat the Head** | Player activates a short patting animation | 6 Red Fish + 5 Yellow Cupcake | Configurable | Best first candidate if pat and positive-reaction assets exist | | **Scratch the Chin** | Cat leans toward or resists a chin scratch | Two-color cost TBD | Configurable | Requires close-contact head animation | | **Wiggle Mouse Toy** | Mouse toy moves near the cat and triggers a short response | Two-color cost TBD | Configurable | Requires mouse-toy prop and tracking animation | | **Roll a Ball** | A ball rolls past the cat and triggers a playful reaction | Two-color cost TBD | Configurable | Requires ball prop, movement, and cat tracking | | **Offer a Cardboard Box** | Cat investigates or jumps toward a box | Two-color cost TBD | Configurable | Requires box prop and compatible cat poses | ## Generator Selection Rules For the first playable: * Implement only one confirmed generator. * Pat the Head is the current recommended candidate. * Do not assign the same prop as both a generator and the active need station in the same challenge. * Select additional generators only after checking vault assets. * Resource combinations and willingness rewards must be data-driven. * Thematic relationships between tile icons and actions are optional; gameplay readability is more important than literal logic. --- # Care Stations Potential need stations include: | Active Need | Station | Direct Interaction | | ----------- | ------------------------- | -------------------------------------------- | | Hunger | Food station | Drag the cat to its food | | Thirst | Water station | Drag the cat to its water | | Hygiene | Brush or cleaning station | Drag the cat into brushing or cleaning range | | Play | Play station | Drag the cat to a defined toy or play area | A care station should feel like a physical object or location in the scene, not a menu button. The player’s direct manipulation target is the cat. --- # Turn and Interaction Cadence The game should preserve a Puzzle Quest-like sequence of discrete decisions. A player decision is one of: * Make one board swap. * Activate one willingness-generator action. * Attempt or activate one care station. For the first playable: 1. Only one decision resolves at a time. 2. Board input is disabled during cascades. 3. Board input is disabled during timed cat interactions. 4. Generator actions cannot be activated during board resolution. 5. Care stations cannot begin during board resolution. 6. After an action completes, the game returns to the player decision state. 7. There is no autonomous cat board turn in the first playable. Whether a willingness generator or care action formally consumes a board turn should remain configurable. The recommended first-iteration rule is: * A board swap is one turn. * Activating a generator is one turn. * Performing care is one turn. * No separate opponent action follows those turns yet. --- # Value Curve and ERRC Matrix | Attribute | Primary | Secondary | Tertiary | Matchy Cat | ERRC | Rationale | | -------------------------------- | ------: | --------: | -------: | ---------: | --------- | ------------------------------------------------------------------------------------------------------------------ | | **Colored Resource Economy** | 5 | 0 | 0 | 5 | Raise | Preserve the primary reference’s mana structure rather than converting matches directly into a universal currency. | | **Action Cost Readability** | 4 | 1 | 1 | 5 | Raise | Every generator must visibly communicate the colored resources required to activate it. | | **Opponent Progress Equivalent** | 5 | 0 | 0 | 4 | Adapt | Willingness replaces enemy health as the central progress value affected by resource-costed actions. | | **Persistent Needs** | 1 | 5 | 2 | 5 | Raise | Needs provide the reason for each challenge and create the return loop. | | **Direct Cat Manipulation** | 0 | 3 | 5 | 5 | Create | Care is performed by moving the cat to physical stations. | | **Timed Character Interactions** | 1 | 3 | 5 | 5 | Raise | Resource changes occur through readable, watchable character actions rather than instant button results. | | **Physical Comedy** | 0 | 3 | 5 | 4 | Create | Cat reactions make every economic transaction entertaining and understandable. | | **Customization** | 1 | 5 | 4 | 0 | Eliminate | Outfits, accessories, and room decoration remain outside the first-playable scope. | | **Text Dependence** | 4 | 3 | 2 | 0 | Eliminate | Costs, availability, need state, and progress should be understood visually. | --- # Design Pillars ## Preserve the Proven Board Economy Matches fill colored resource meters. They do not bypass the action layer by generating willingness directly. The player should make decisions about which colors to match based on the actions they want to activate. ## Actions Make the Cat Willing Willingness is generated through interactions with the cat, not through abstract board clearing. Each generator converts a specific combination of colored resources into a defined willingness reward. ## Move the Cat, Not the Care Item The Clumsy Ninja influence should be visible in the player’s physical relationship with the character. Care is performed by dragging the cat to stations and props in the scene. ## Every Resource Change Is Performed Resource changes should feel like events involving the cat. Colored resources travel from their meters into the interaction. Willingness travels between the cat and its meter. Need state visibly leaves or changes within the cat. ## Commit After Completion No resource or need value changes until its associated timed interaction reaches the completion point. The animation is not merely decorative. It defines when the transaction becomes valid. ## One Active Need The persistent system may track several needs, but each short challenge presents one active objective and one relevant care station. --- # Must-Have Systems | System | Why It Exists | Primary Reference | | --------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------- | | **Match-3 Board** | Generates colored resources through tile matches. | Puzzle Quest | | **Six-Color Resource Bank** | Stores the equivalent of colored mana. | Puzzle Quest | | **Action Cost and Availability System** | Enables or disables generators based on their complete resource requirements. | Puzzle Quest | | **Willingness-Generator System** | Converts colored resources into willingness through timed cat interactions. | Puzzle Quest adapted through Clumsy Ninja | | **Willingness State** | Represents reduced stubbornness and gates care stations. | Puzzle Quest | | **Persistent Need System** | Determines which care challenge the player must complete. | My Talking Tom | | **Care Station System** | Converts willingness into need improvement. | My Talking Tom | | **Cat Drag Controller** | Allows the player to physically move the cat to care stations. | Clumsy Ninja | | **Timed Interaction Controller** | Manages action duration, input locks, reservation, completion, and cancellation. | Clumsy Ninja | | **Resource Transaction System** | Reserves and commits resources only when interactions complete. | Matchy Cat integration | | **Visual Resource Transfer System** | Shows what is being spent and gained during each cat interaction. | Matchy Cat integration | | **Cat Reaction Controller** | Selects physical and emotional responses for generators, refusals, care, and completion. | Clumsy Ninja | | **Turn Controller** | Preserves a discrete match-or-action decision cadence. | Puzzle Quest | | **Responsive Layout System** | Keeps the cat, board, meters, actions, and station readable across aspect ratios. | Persona requirements | --- # Suggested Runtime Flow ```text Need Introduction ↓ Player Decision ├── Board Swap │ ↓ │ Board Resolution │ ↓ │ Colored Resource Gain │ ↓ │ Refresh Action Availability │ ↓ │ Player Decision │ ├── Willingness Generator │ ↓ │ Validate and Reserve Colored Resources │ ↓ │ Timed Cat Interaction │ ↓ │ Commit Resource Spend │ ↓ │ Commit Willingness Gain │ ↓ │ Refresh Actions and Stations │ ↓ │ Player Decision │ └── Drag Cat to Care Station ↓ Check Willingness ├── Insufficient │ ↓ │ Refusal Reaction │ ↓ │ Player Decision │ └── Sufficient ↓ Reserve Willingness ↓ Timed Care Interaction ↓ Commit Willingness Spend ↓ Commit Need Improvement ↓ Need Resolved? ├── No → Player Decision └── Yes → Need Complete ``` --- # Core Entities ## `ResourceType` ```text ResourceType - GreenTuna - OrangeBowl - PurpleFoodBox - BlueMilk - RedFish - YellowCupcake ``` ## `ColoredResourceBank` Tracks Puzzle Quest-style colored resources. ```text ColoredResourceBank - currentAmountByType - maximumAmountByType - Add(resourceType, amount) - CanAfford(cost) - Reserve(cost) - CommitReservation(reservationId) - CancelReservation(reservationId) ``` ## `ActionCost` ```text ActionCost - resourceType - requiredAmount ``` A generator may contain multiple `ActionCost` entries. ## `WillingnessState` ```text WillingnessState - current - maximum - reserved - CanAfford(amount) - Reserve(amount) - Add(amount) - CommitSpend(reservationId) - CancelReservation(reservationId) - Reset() ``` Willingness is challenge-local and is not saved. ## `WillingnessGeneratorDefinition` ```text WillingnessGeneratorDefinition - generatorId - displayIcon - resourceCosts - willingnessReward - duration - reactionPool - consumesTurn - requiredAssets ``` ## `NeedStationDefinition` ```text NeedStationDefinition - stationId - needType - willingnessCost - needReduction - interactionDuration - validDropArea - refusalReactionPool - successReactionPool ``` ## `CatState` ```text CatState - hunger - thirst - hygiene - play - mood - activeNeedType - interactionState ``` ## `TimedInteraction` ```text TimedInteraction - interactionId - interactionType - duration - completionPoint - reservationId - canCancel - currentState ``` Possible states: ```text Idle Reserved Starting Performing Completing Committed Cancelled ``` ## `InteractionTransaction` ```text InteractionTransaction - reservedColoredResources - reservedWillingness - pendingWillingnessGain - pendingNeedReduction - Commit() - Cancel() ``` ## `CatDragController` ```text CatDragController - BeginDrag() - UpdateDrag() - EndDrag() - FindOverlappingStation() - ReturnCatToIdleAnchor() ``` ## `CatReactionController` ```text CatReactionController - PlayGeneratorReaction() - PlayCareReaction() - PlayRefusalReaction() - PlayNeedCompleteReaction() ``` ## `VisualTransferController` ```text VisualTransferController - BoardToResourceMeter() - ResourceMeterToCat() - CatToWillingnessMeter() - WillingnessMeterToStation() - CatToNeedMeter() ``` ## `TurnController` ```text TurnController - currentPhase - BeginBoardTurn() - BeginGeneratorTurn() - BeginCareTurn() - LockInput() - ReleaseInput() ``` --- # First-Session Clarity Requirements The first challenge must communicate: * The cat is hungry. * The food station is the objective. * The cat currently refuses the food station. * Matching tiles fills colored meters. * Pat the Head requires red fish and yellow cupcake resources. * The generator becomes active when both costs are available. * Patting the cat increases willingness. * The food station requires willingness. * The player must drag the cat to the station. * Feeding spends willingness. * Feeding reduces hunger. * The loop must be repeated until hunger reaches zero. ## Recommended Onboarding Sequence 1. Show the hungry cat looking toward the food station. 2. Briefly pulse the food station. 3. Allow or encourage the player to drag the cat toward it. 4. Play a short refusal. 5. Pulse the willingness requirement. 6. Highlight one valid board swap. 7. Animate matched resources into their colored meters. 8. Continue highlighting useful matches until Pat the Head is affordable. 9. Pulse the Pat the Head action and its complete cost. 10. After activation, use transfer particles to explain the transaction. 11. Once the food station becomes affordable, pulse the cat and station. 12. Show a short drag path from the cat to the station. 13. Remove explicit guidance after the first successful feeding. Avoid modal tutorial screens and explanatory text paragraphs. --- # First-Playable Acceptance Criteria The first playable succeeds when: 1. A match fills the correct colored resource meter. 2. No match directly increases willingness. 3. Pat the Head remains disabled until all of its colored costs are available. 4. Its red fish and yellow cupcake requirements are clearly visible. 5. Activating it reserves but does not immediately subtract the resources. 6. The cat performs a timed patting interaction. 7. Colored particles move from the relevant meters to the cat. 8. Willingness particles move from the cat to the willingness meter. 9. The colored meters decrease only after the interaction completes. 10. Willingness increases only after the interaction completes. 11. Dragging the cat to the food station with insufficient willingness triggers a refusal. 12. The failed attempt spends nothing. 13. The food station becomes active when enough willingness is available. 14. The player drags the cat, not the food item, to the station. 15. Feeding plays as a timed interaction. 16. Willingness and hunger do not change before the feeding completion point. 17. After completion, willingness decreases and hunger decreases. 18. Board interaction resumes automatically. 19. Approximately three feeding interactions satisfy the need. 20. The complete challenge works in portrait and landscape layouts. --- # Deferred Systems * Additional need types. * Multiple simultaneous active needs. * Additional willingness generators. * Cat customization. * Room customization. * Persistent willingness. * Long-term currency shops. * Complex generator loadouts. * Advanced ragdoll simulation. * Autonomous opponent AI. * Narrative dialogue. * Punitive offline deterioration. * Cat interference with the board. * Permanent statistical upgrades. --- # Known Risks ## Resource Economy Is Visually Dense Six colored meters, willingness, hunger, generator costs, and station costs may overwhelm the player. ### Mitigation * Keep only one generator visible in the first playable. * Use identical icons across tiles, meters, and costs. * Use animation to direct attention. * Avoid displaying unnecessary numbers. * Show one active need and one care station. ## Players May Confuse Resources with Literal Food The board contains tuna, bowls, food boxes, milk, fish, and cupcakes, but these function as Puzzle Quest-style colored resources. ### Mitigation * Use consistent color coding. * Avoid narrative explanations that every icon is physically consumed. * Treat them as a playful resource language. * Let the interaction animation explain their mechanical purpose. ## Timed Interactions May Slow the Loop Every generator and care action takes several seconds. ### Mitigation * Keep common interactions short. * Recommended generator duration: approximately 1.5–3 seconds. * Recommended care duration: approximately 2–4 seconds. * Return control immediately after completion. * Reserve longer comedy sequences for rare reactions and challenge completion. ## Animation and State May Desynchronize A reaction could be interrupted before its economic result is applied. ### Mitigation * Use explicit transaction reservations. * Commit at a defined completion marker. * Cancel safely if the interaction fails. * Do not tie permanent state changes to arbitrary visual effects. * Ensure every interaction has a timeout and recovery path. ## Refusal May Feel Like Punishment Trying the food station before gaining willingness could appear to waste time. ### Mitigation * Keep the refusal brief. * Make it funny and informative. * Pulse the exact missing willingness requirement. * Do not spend resources. * Use the first refusal as onboarding. --- # Implementation Notes for Coding Agent ## Required Interaction Sequence: Match ```text Player Swap → Validate Match → Resolve Match and Cascades → Calculate Resources by Tile Type → Animate Board-to-Meter Transfers → Add Colored Resources → Refresh Generator Availability → Return to Player Decision ``` ## Required Interaction Sequence: Willingness Generator ```text Player Activates Generator → Validate Complete Colored Cost → Reserve Colored Resources → Lock Board and Other Actions → Begin Timed Cat Interaction → Animate Resources from Meters to Cat → Animate Willingness from Cat to Meter → Reach Completion Point → Commit Colored Resource Spend → Commit Willingness Gain → Refresh Availability → Unlock Input ``` ## Required Interaction Sequence: Care Station ```text Player Drags Cat → Detect Station → Validate Willingness Cost → If Insufficient: Play Refusal and Return Cat → If Sufficient: Reserve Willingness → Lock Board and Other Actions → Begin Timed Care Interaction → Animate Willingness from Meter to Station → Animate Need State from Cat to Need UI → Reach Completion Point → Commit Willingness Spend → Commit Need Reduction → Check Challenge Completion → Unlock Input or Complete Challenge ``` ## Architecture Rules * Matches update only colored resources. * Generators update willingness. * Care stations update needs. * Do not allow one system to bypass another. * All action costs, rewards, durations, and need effects must be data-driven. * Reserve resources when interactions start. * Commit changes when interactions complete. * Cancel reservations if the interaction fails. * Prevent multiple actions from sharing the same reserved resources. * Disable board interaction while the cat performs a timed action. * Keep gameplay state authoritative and animation state presentational. * The player drags the cat to care stations. * Do not implement persistent willingness storage. * Do not implement a separate care screen. * Do not modify the board through cat physics in the first playable. --- # Open Design Questions ## Care Action Variety The first playable should contain one need station and one willingness generator. Additional interactions should be introduced only after confirming that players understand: ```text Colored resources → Willingness generator → Willingness → Care station → Need progress ``` Vault assets should determine which generators are practical. ## Turn Consumption Puzzle Quest abilities participate in a turn-based economy. A decision is still needed on whether: * A willingness generator always consumes the player’s turn. * A care-station interaction always consumes the player’s turn. * Some generators grant another turn. * Some high-cost actions have special turn behavior. For the first playable, every match or interaction should be treated as one discrete action, without a separate opponent turn. ## Cat-to-Board Interference Any later cat interference should follow Puzzle Quest’s turn-based structure rather than becoming unrelated real-time physics disruption. Reference-aligned possibilities include: * The cat takes a reaction turn after certain player actions. * The cat converts selected tiles. * The cat creates blocker tiles. * The cat removes stored colored resources. * The cat shuffles part of the board. * A mood state modifies which colors are valuable. * A stubbornness effect temporarily increases an action’s cost. These effects should occur at defined turn boundaries and be communicated as the cat’s equivalent of an opponent action. They should not be added until the first playable proves that the basic resource and willingness loop is readable. ## Long-Term Progression Long-term progression should primarily follow Clumsy Ninja’s interaction-driven model. Potential progression includes: * Unlocking new ways to interact with the cat. * Unlocking new willingness-generator actions. * Introducing new props and stations. * Expanding the cat’s reaction library. * Unlocking longer or more elaborate physical-comedy sequences. * Introducing new contexts for existing interactions. * Increasing the player’s mastery over handling the cat. * Revealing new need situations and behavioral challenges. The first progression layer should emphasize new interactions and reactions rather than numerical stat upgrades or persistent willingness. ## Persistent Needs Persistent needs should follow the My Talking Tom reference. Recommended direction: * The cat maintains hunger, thirst, hygiene, and play state between sessions. * One need is selected as the active challenge when the player checks in. * Need state gives the player a clear reason to enter the match-3 loop. * Needs should change slowly enough that returning feels inviting rather than punitive. * The first playable should not include aggressive real-time decay. * The cat should visibly communicate its highest-priority need. * Resolving a need should visibly improve the cat’s mood or behavior. * Multiple needs may exist persistently, but only one should drive the current challenge. ## Generator Loadout A later version may let the player choose several willingness generators, similar to selecting abilities in an RPG. Questions include: * How many generators should be visible at once? * Do different generators compete for the same colors? * Are generators unlocked through interaction progression? * Can the active need make certain generators more or less effective? * Should a generator sometimes produce an extra turn? This system is outside the first-playable scope. --- # Implementation Priorities / In Orde ## Phase 1: Board and Colored Resources * Six tile types. * Six resource meters. * Match resolution. * Board-to-meter visual transfer. * Action-cost display. * Generator availability checks. ## Phase 2: Pat the Head and Willingness * Pat the Head action. * Red fish and yellow cupcake costs. * Timed patting interaction. * Resource reservation. * Resource-to-cat particles. * Cat-to-willingness particles. * Willingness meter. * Completion-point transaction commit. ## Phase 3: Hunger Station * Persistent hunger value. * Food station. * Cat dragging. * Insufficient-willingness refusal. * Timed feeding interaction. * Willingness-to-station particles. * Cat-to-hunger-indicator particles. * Hunger reduction. * Challenge completion. ## Phase 4: Clarity and Responsiveness * Guided first match. * Guided first refusal. * Cost pulsing. * Responsive portrait layout. * Responsive landscape layout. * Interaction recovery behavior. * Improved effect timing. ## Phase 5: Additional Reactions * Pat reaction variants. * Refusal variants. * Feeding variants. * Rare reaction escalation. * Improved sound, anticipation, and recovery. ## Phase 6: Additional Needs and Generators * Additional vault-supported generators. * Water station. * Hygiene station. * Play station. * Persistent need selection. * Interaction-focused progression. --- # Explicit Non-Goals for the First Playable * Matches directly generating willingness. * Spending willingness on buttons that remotely apply care. * Dragging food or brushes onto the cat as the standard care input. * Separate puzzle and care screens. * Persistent willingness storage. * Multiple visible willingness generators. * Multiple simultaneous active needs. * Autonomous opponent AI. * Real-time cat disruption of the board. * Customization systems. * Shops and currency exchange. * Permanent numerical upgrades. * Complex narrative or dialogue.