Introduction & Gameplay Rules

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• RULES.md
• AGENTS.md
• src/locales/en/translation.json
• convex/tests/rooms-and-games.test.ts
• src/state/useGame.ts
• convex/tests/actions-flow.test.ts

Dreamcats is a real-time, multiplayer memory card game built with React, TypeScript, and Convex. The game is inspired by classic memory card games where players travel to a dream world populated by fairytale lands and dark nightmares full of cats. The primary objective is to manage a "Dream" consisting of four cards to achieve the lowest possible total value, representing the fewest number of cats encountered.

The system supports various game modes, including Solo vs AI, Online Multiplayer, and Local Hot-seat. It leverages a robust tech stack featuring Convex for real-time state synchronization, Zustand for local state management, and GSAP for fluid animations.

Sources: README.md:1-15, RULES.md:3-10, src/locales/en/translation.json:108-142

Game Components & Setup

The deck consists of 54 cards representing different "Lands." Card values determine the score, with standard number cards, high-value "Cat" cards, and Special cards.

Deck Composition

Card Type	Value/Name	Count	Description
Standard	0 - 8	36 (4 each)	Basic number cards.
Nightmare	9	9	High-value "Cat" cards; common bad cards.
Special	Take 2	3	Allows drawing two cards from the deck.
Special	Peek 1	3	Allows looking at one card on the table.
Special	Swap 2	3	Allows swapping two cards on the table.

Sources: RULES.md:15-28, src/locales/en/translation.json:251-260

Initial Setup logic

1. Dealing: Each player is dealt 4 cards face-down.
2. Initial Peek: Players may look at exactly 2 of their own cards to memorize them.
3. Piles: The remaining cards form the Stos Zakryty (Draw Pile). The top card is flipped to start the Stos Odkryty (Discard Pile).
4. Validation: The backend ensures that a minimum of 2 players are present and enough cards (Players * 4 + 1) exist in the deck to start.

Sources: RULES.md:30-40, convex/tests/rooms-and-games.test.ts:145-173, src/state/useGame.ts:162-180

Gameplay Loop & Turn Logic

The game progresses clockwise. On each turn, a player must choose between drawing from the Discard Pile or the Draw Pile.

Turn Phases

The following diagram illustrates the standard decision flow during a player's turn:

The logic differentiates between the two piles: drawing from the discard pile forces a swap, while drawing from the deck allows the player to discard the drawn card if it is undesirable.

Sources: RULES.md:43-62, src/state/useGame.ts:390-415, convex/tests/actions-flow.test.ts:139-165

Special Powers (Krainy Specjalne)

Special powers can only be activated if the card was drawn from the Draw Pile and immediately discarded. If picked from the Discard Pile, they function as standard high-value number cards (values 5, 6, or 7).

Special Action Details

• Weź 2 (Take 2): The player draws 2 cards from the deck, chooses one to keep (for a swap or another special action), and discards the other.
• Podejrzyj 1 (Peek 1): The player views one card in any player's dream (including their own or an opponent's) before returning it face-down.
• Zamień 2 (Swap 2): The player swaps the positions of any two cards on the table without looking at them. Valid combinations include Own ↔ Own, Own ↔ Opponent, or Opponent A ↔ Opponent B.

Sources: RULES.md:65-85, src/locales/en/translation.json:200-215, convex/tests/actions-flow.test.ts:168-210

Round Termination: "POBUDKA!" (Wake Up)

A round ends when a player believes they have the lowest score among all participants.

The Wake Up Process

Scoring Logic

• Reveal: All players flip their 4 cards face-up.
• Caller's Risk: If the caller has the strictly lowest score (or ties), they score their sum. If they do not have the lowest score, they receive their sum plus a 5-point penalty.
• Winning Condition: The game ends when a player reaches 100 points. The player with the overall lowest score is declared the winner.

Sources: RULES.md:88-105, convex/tests/rooms-and-games.test.ts:176-258, src/locales/en/translation.json:217-220

Technical Implementation of Rules

The gameplay logic is distributed between the Convex backend (authoritative state) and the Zustand store (local UI state).

Data Structures

The game state is governed by the GameStateSchema, which tracks:

• gamePhase: Enum including peeking, playing, holding_card, and various special action states.
• players: An array of player objects containing their id, name, hand (4 slots), and score.
• piles: drawPile and discardPile arrays containing Card objects.

Sources: convex/tests/rooms-and-games.test.ts:16-83, src/state/useGame.ts:100-115

Role of AI Agents

The system includes an AiGameAgent used for end-to-end testing of gameplay rules. It exercises all player actions, including deterministic peeking and "priming" the deck to ensure special card paths are covered.
Sources: scripts/ai-agent.ts:14-45, src/state/useGame.ts:316-370

State Transitions

State transitions are handled by the broadcastAction function, which maps UI interactions (like clicking a card or pile) to backend mutations such as DRAW_FROM_DECK, SWAP_HELD_CARD, or CALL_POBUDKA.
Sources: src/state/useGame.ts:380-450, src/components/Gameboard.tsx:125-145

The Dreamcats gameplay system ensures a balance of memory, strategy, and risk-taking, enforced by a real-time synchronized state engine that validates every move against the defined ruleset.