Card Components & GSAP Animations
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The card system in Dreamcats is a sophisticated implementation of interactive UI components driven by React and the GreenSock Animation Platform (GSAP). It manages the visual representation of the game's 54-card deck, including standard number cards and special action cards like "Take 2", "Peek 1", and "Swap 2". The system ensures high performance and visual fidelity through 3D CSS transforms and hardware-accelerated animations.
The architecture separates card logic into specialized components: GameCard for high-fidelity interactive cards, PileCard for static deck/discard piles, and PlayerHand for managing layouts and group interactions. This structure supports complex game states such as peeking, swapping, and special ability activations while maintaining a "dreamy" aesthetic through custom shaders, vignettes, and GSAP-driven glow effects.
Sources: src/components/Card.tsx:1-20, README.md:14-18, convex/game_core.ts:16-40
Card Component Architecture
The GameCard Component
The GameCard is the primary interactive unit. it uses a 3D flip architecture to hide or reveal card data. This prevent DOM inspection cheating by conditionally rendering the front asset only when isFaceUp is true.
- 3D Flip Logic: Utilizes
transform-style: preserve-3dandbackface-visibility: hiddento create a realistic card flip effect. - Static Mode: Includes a fallback mechanism for browsers or environments that do not support 3D transforms, ensuring broad compatibility.
- Security: Card values and labels are only present in the DOM when the card is face-up.
Sources: src/components/Card.tsx:40-100, src/components/Card.tsx:140-155, src/index.css:260-275
The PileCard Component
A specialized, lightweight component designed for the Draw and Discard piles. Unlike GameCard, it avoids complex 3D perspective to prevent rendering glitches in static stacks.
Sources: src/components/PileCard.tsx:15-30
PlayerHand and Layout Management
PlayerHand acts as a container for multiple GameCard instances. It handles the logic for targeting specific cards during game phases like "Swap 2" or "Peek 1".
Sources: src/components/PlayerHand.tsx:25-50
The diagram shows the component hierarchy from the main Gameboard down to the individual card rendering layers.
Sources: src/components/Gameboard.tsx:100-150, src/components/PlayerHand.tsx:230-250
GSAP Animation System
GSAP is used for state-driven animations that go beyond simple CSS transitions. The project utilizes the @gsap/react hook to manage animation lifecycles within the React component tree.
Key Animation Patterns
| Animation Type | Trigger | Implementation Details |
|---|---|---|
| 3D Flip | isFaceUp change | gsap.to(ref, { rotateY: 180, duration: 0.6 }) |
| Special Glow | card.isSpecial && isFaceUp | Repeating yoyo pulse with drop-shadow |
| Card Pop | Card swap/change | Scale (1.06) and translateY (-6px) "lift" |
| Aura Pulse | Special action active | Radial gradient scale and opacity oscillation |
| Screen Shake | "Swap 2" or "Take 2" | Horizontal vibration on completion of action |
Sources: src/components/Card.tsx:55-80, src/index.css:333-345, src/components/Gameboard.tsx:280-320
Interaction Flow
Animations are often triggered by the broadcastAction utility, which updates the shared GameState. When a move is registered, the lastMove object in state triggers localized animations in PlayerHand or Gameboard.
This sequence illustrates how a player action initiates a state change that GSAP then translates into a smooth 3D visual transition.
Sources: src/components/Card.tsx:55-65, src/components/PlayerHand.tsx:150-180
Visual Styles and Effects
Asset Management
Card images are preloaded to ensure zero-latency during flips. The system supports WebP with PNG fallbacks and uses cache-busting versions (e.g., ?v3).
- Normal Cards: Values 0-9.
- Special Cards:
podjerzyj1(Peek),zamien2(Swap),wez2(Take 2). - Vignettes: Both light and dark mode vignettes are applied via CSS radial gradients to counteract baked-in image lighting.
Sources: src/lib/cardAssets.ts:1-40, src/components/Card.tsx:115-130
Technical Constraints
The game implements a game-compact mode and useScaleToFit hook to ensure the card board fits various viewport heights.
| Property | Value | File |
|---|---|---|
| Perspective | 1000px | src/index.css |
| Flip Duration | 0.6s | src/components/Card.tsx |
| Min Card Scale | 0.65 | src/components/Gameboard.tsx |
| Shadow (Soft) | 0 6px 16px rgba(0,0,0,0.12) | src/components/Card.tsx |
Sources: src/index.css:260-270, src/components/Gameboard.tsx:55-65
Conclusion
The Card Components and GSAP Animations system provides the core interactive experience for Dreamcats. By combining React's state management with GSAP's high-performance animation engine and robust 3D CSS transforms, the project achieves a polished, secure, and responsive card-playing environment. The separation into GameCard, PileCard, and PlayerHand ensures that the complex logic of the game's phases remains manageable and visually consistent across devices.
Sources: README.md:14-20, src/components/Gameboard.tsx:450-480