Playing Cards Simulator

• 

  Game menu

Inspiration

I spend a lot of time playing card games online, but learning them can be frustrating. Tutorials are not always available, translations can be unclear, and most lessons force players through a fixed sequence of prescribed actions. They also make it difficult to revisit a specific situation or experiment with alternative moves.

I wanted a more interactive way to learn existing card games, recreate scenarios, and design new games with an agent that can explain the state, suggest actions, and participate in the simulation.

What it does

How I built it

Playing Cards Simulator exposes WebMCP tools that let an AI agent create a custom card game from an XState-compatible finite-state machine definition or launch an existing game such as Blackjack, War, Go Fish, Crazy Eights, Euchre, Gin Rummy, Bullshit, or Texas Hold'em.

The agent can inspect the current game state, explain what is happening, highlight available controls, coach the player through the next action, wait for the player's input, and act as a bot or dealer. This makes tutorials adaptive instead of forcing every player through the same fixed sequence.

The app is built with Next.js, TypeScript, React, XState, and WebMCP. XState provides a predictable model for phases, turns, actions, rewards, and transitions, while WebMCP exposes tools for creating sessions, reading state, guiding players, and performing simulated actions.

Challenges I ran into

The hardest part was designing a general game model that could support both predefined and agent-generated card games. The tools also needed to stay synchronized with the browser session while handling navigation, stale connections, turn order, hidden information, and invalid actions safely. The latency was unbarely and the UX of the user nudging the ai via the agent chat every turn was awkward.

Accomplishments that I'm proud of

I built one simulator that supports both a catalog of familiar games and custom games defined by an agent. The same interface can teach rules, recreate a specific situation, guide a player interactively, and run bots or dealers without relying on a rigid tutorial script. I thought of the tool which waits for user input making the process fully immersive.

What I learned

Finite-state machines are a strong foundation for agent-controlled games because they make valid actions and transitions explicit. I also learned that effective agent guidance requires more than reading state: the agent needs tools to explain, highlight, pause for input, and act within clearly defined boundaries.

What's next for Playing Cards Simulator

Next, I want to expand the game catalog, improve custom game validation, add richer animations, and make tutorials more responsive to each player's choices. I also plan to improve session persistence and make it easier to share custom games and specific learning scenarios. I would love to repurpose this for RTS or create a DND game where the agent is the game master.

Built With

• nextjs
• react
• typescript
• webmcp
• xstate