AI Agent Scripts
Relevant source files
The following files were used as context for generating this wiki page:
AI Agent Scripts in the Dreamcats project serve two primary purposes: end-to-end automated testing of game logic and providing the gameplay intelligence for solo game modes. These scripts exercise the Convex backend mutations and queries to simulate real-player behavior across various game phases, including peeking, drawing, swapping, and calling "Pobudka" (Wake Up).
The system is split between a standalone test agent (scripts/ai-agent.ts) used for CI/CD and coverage validation, and an in-app bot logic module (src/lib/bot-logic) integrated into the React state management to handle Solo vs AI gameplay.
Sources: scripts/ai-agent.ts:1-18, src/state/useGame.ts:311-350, AGENTS.md:21-25
Standalone Test Agent Architecture
The standalone AI agent is a Bun-powered script that utilizes convex-test to simulate a full game environment in-memory without network calls. It provides switchable modes for local (hotseat) or online simulation and can run in basic or advanced configurations to ensure full coverage of special card actions.
Core Components
- AiGameAgent Class: Manages the lifecycle of a test run, including room creation, player joining, and turn execution.
- convexTest: An environment provided by the
convex-testpackage that mirrors the backend environment, allowing mutations likeapi.actions.performActionto be executed against a mock database. - Deck Priming: In "advanced" mode, the script patches the server-side state to reorder the draw pile, ensuring that special actions like "Take 2", "Peek 1", and "Swap 2" are triggered for coverage.
Sources: scripts/ai-agent.ts:10-30, scripts/ai-agent.ts:74-100, scripts/ai-agent.ts:133-160
Test Agent Flow
The following diagram illustrates the initialization and execution loop of the standalone AI agent:
The script uses a guard variable to prevent infinite loops, and a "last-resort" coverage fallback to patch the state if specific actions were not naturally triggered during play.
Sources: scripts/ai-agent.ts:46-68, scripts/ai-agent.ts:182-225, scripts/ai-agent.ts:380-410
Bot Logic and Difficulty Rebalance
The bot logic used in solo gameplay is integrated via the useGame hook. It employs a "single scheduler pattern" to manage turn processing, ensuring that bots act sequentially after human moves.
Difficulty Levels
Bots behave differently based on the selected difficulty level, primarily adjusting their thresholds for taking cards from the discard pile and their aggression with special cards.
| Difficulty | Discard Take Threshold | Special Action Chance | Pobudka Confidence |
|---|---|---|---|
| Easy | 2 (Lenient) | Lower | Low (0.08 chance) |
| Normal | Balanced | Balanced | Moderate |
| Hard | High (Aggressive) | High (0.85 chance) | High (Threshold 11) |
Sources: src/tests/bot-difficulty.test.ts:31-70, src/state/useGame.ts:352-365
Solo Mode Execution Flow
In solo mode, the client manages bot actions locally using the gameReducer.
The bot memory is updated during these turns to track cards peeked or swapped, allowing the AI to make informed decisions about calling "Pobudka" based on its known card values.
Sources: src/state/useGame.ts:470-510, src/state/useGame.ts:352-425
Action Coverage and Testing
The scripts/ai-agent.ts script tracks a specific set of ActionName types to ensure every possible game interaction is exercised.
Monitored Actions
- Initialization:
START_NEW_ROUND,PEEK_CARD,FINISH_PEEKING. - Standard Turns:
DRAW_FROM_DECK,DRAW_FROM_DISCARD,DISCARD_HELD_CARD,SWAP_HELD_CARD. - Special Abilities:
USE_SPECIAL_ACTION,ACTION_PEEK_1_SELECT,ACTION_SWAP_2_SELECT,ACTION_TAKE_2_CHOOSE. - Termination:
CALL_POBUDKA.
Implementation Detail: Bot Policy
The AI follows a "worst-card" policy:
- Evaluation: It identifies the highest-value card in its hand (
worstCardIndex). - Comparison: If the drawn/visible card's value is lower than the worst card in hand, it performs a swap.
- Specials: If a special card is drawn from the deck, it typically prioritizes using the special power over swapping.
Sources: scripts/ai-agent.ts:241-255, scripts/ai-agent.ts:312-340, RULES.md:42-65
Summary
AI Agent Scripts bridge the gap between automated testing and single-player functionality. By using convex-test for standalone scripts and an integrated scheduler for the UI, the project ensures game logic remains robust. The bot intelligence, while adhering to simple optimization policies, scales across difficulty levels by adjusting randomness and decision thresholds, providing a realistic challenge for players in Solo mode.
Sources: AGENTS.md:21-30, src/state/useGame.ts:600-610