Core Card Animations - Intake Brief

Implement core card animations (deal, move/place, discard) for Main Street and ensure animation helpers are reusable engine components.

Users

• Players: Receive visual feedback for card actions (dealing cards, placing them on the street, discarding used cards), making gameplay easier to follow and more satisfying.
• Game developers: Reuse modular card animation helpers from the engine without reimplementing animation logic for each new game.

User stories

• As a player, I want to see cards animate when they are dealt so I can easily track which card entered my hand.
• As a player, I want to see cards animate when placed on my street so I can confirm the action succeeded.
• As a player, I want to see cards animate when discarded so I understand they are no longer in play.
• As a developer, I want reusable animation helpers in the engine so I can add animations to any game with minimal code.

Success criteria

1. Deal animation: When a card is added to the player's hand, a deal animation plays; GameEventEmitter fires a 'card:dealt' event on completion.
2. Move/place animation: When a card is placed on the street, a move animation plays; state transitions happen after animation completes; a 'card:placed' event fires.
3. Discard animation: When a card is discarded, a discard animation removes it visually; a 'card:discarded' event fires with the card ID.
4. Reusability: Animation helpers are in src/ui/ and exported via the engine's public API (src/ui/index.ts).
5. Testability: Unit tests or browser tests verify callbacks fire and state is correct after animations complete.
6. Documentation: Animation timings and usage examples are documented in docs/ or README.
7. All related documentation is updated to reflect the changes, including code comments, README, and any relevant wiki or docs site entries.
8. Full project test suite must pass with the new changes.

Constraints

• Use existing GameEventEmitter (src/core-engine/GameEventEmitter.ts) for event emissions - do not create new callback mechanisms.
• Follow animation timing guidelines in docs/main-street/ux-visual-audio.md (Section 4) but adjust as needed for good feel.
• Put animation helpers in src/ui/ (engine) not in example-games/.
• Keep engine and public APIs unchanged where possible; prefer extending over modifying existing interfaces.
• Accessibility: Animation should respect reduced-motion settings if present.

Existing state

• Core engine provides moveGameObject.ts (positional tween helper) and flipCard.ts (card flip animation) in src/ui/.
• Main Street scene renders cards via refreshPlayerHand() in scenes/MainStreetScene.ts.
• Commands in MainStreetCommands.ts handle game actions but currently have no visual animation.
• GameEventEmitter exists in src/core-engine/ for event handling.

Desired change

• Create card-specific animation helpers in src/ui/ (e.g., dealCard.ts, placeCard.ts, discardCard.ts) that:
  • Accept a Phaser scene and card sprite
  • Use appropriate easing and duration from UX guidelines
  • Emit events via GameEventEmitter on completion
  • Handle reduced-motion accessibility
• Integrate animations into Main Street scene command handlers
• Add tests for animation callbacks and state consistency
• Document animation helpers and timings

Related work

• Parent: Main Street: PRD Milestone 4 -- Visual Polish, Animation, and Audio (CG-0MM4RF91E1LR5RSY)
• Existing: src/ui/moveGameObject.ts - reusable positional tween helper (can be reused)
• Existing: src/ui/flipCard.ts - card flip animation (reference for card animations)
• Existing: src/core-engine/GameEventEmitter.ts - event emission system to use
• Existing: docs/main-street/ux-visual-audio.md - animation timing guidelines
• Related: MainStreetScene.ts - where animations will be integrated

Risks & assumptions

• Risk: Scope creep — temptation to add more animations (card flip, hover effects, etc.) beyond the three core animations.
  • Mitigation: If additional animations are needed, create separate work items linked to this one rather than expanding scope.
• Risk: Animation timing may not "feel right" on first implementation — requires iteration.
  • Mitigation: Use existing UX doc as starting point; allow implementer to adjust for good feel; document final timings.
• Assumption: GameEventEmitter is already integrated into the Main Street scene and can be used for event emission.

Related work (automated report)

• Parent: Main Street: PRD Milestone 4 -- Visual Polish, Animation, and Audio (CG-0MM4RF91E1LR5RSY) — Parent epic for M4; this item is a child task.
• Prior art: Add card/noble movement animations to SplendorScene (CG-0MM4RIKWT0EKGP0P) — Completed work for Splendor; likely similar implementation pattern.
• Code reference: src/ui/moveGameObject.ts — Reusable positional tween helper; used as foundation for deal/place animations.
• Code reference: src/ui/flipCard.ts — Card flip animation; reference for card-specific animation patterns.
• Code reference: src/core-engine/GameEventEmitter.ts — Event emission system to use for animation callbacks.
• Design doc: docs/main-street/ux-visual-audio.md — Section 4 contains animation timing guidelines.

Appendix: Clarifying questions & answers

• Q: "The acceptance criteria mentions callbacks - should these be event emissions that external code can subscribe to (using the existing GameEventEmitter), or should they be Promise-based awaitables, or both?" — Answer (user): "Use existing GameEventEmitter". Source: interactive reply. Final: yes.
• Q: "For animation timings, should I follow the guidelines from docs/main-street/ux-visual-audio.md (Section 4: Animation and Juice) or use custom timings?" — Answer (user): "Follow the doc but feel free to adjust". Source: interactive reply. Final: yes.
• Q: "The deliverable mentions 'animation helpers in example-games/main-street/animations.ts' - is that the intended location, or would you prefer them in the scenes directory or exported from the engine?" — Answer (user): "From engine". Source: interactive reply. Final: yes.