Mental Card Games

Appearance

Module Responsibilities ​

1. Frontend (frontend/) ​

The frontend is the user's entry point. It handles:

  • Rendering: Uses egui immediate mode GUI.
  • State Management: Holds a local replica of GameStatePublic.
  • Routing: Manages screens (/receive, /transmit, /game, etc.) via a registry.
  • Camera/QR: Wraps browser media APIs (via web-sys) to capture video frames for QR scanning.

2. Backend (native_mcg/) ​

The native server application. It handles:

  • Game Engine Integration: Utilize the Game Engine to step through game loops.
  • HTTP/WS Server: Serves the WASM assets and handles WebSocket connections at /ws.
  • Asset Serving & CLI: Parses command-line arguments and runs an HTTP server to serve the HTML, compiled WASM, and other artifacts required by the frontend.
  • Connection Management (Custom Tokio Actors): Concurrently manages local WebSocket connections (to frontends) and P2P connections (to other players' backends). The actor system is a custom, lightweight implementation built natively on top of tokio channels (e.g., tokio::mpsc).
  • Game Engine (CGDL): Parses Card Game Domain Specific Language (CGDL) files to understand the rules and state machine of the current game.
  • Action Verification: The engine processes incoming actions and verifies them using the cryptography layer before transitioning the game state.

3. Shared (shared/) ​

Contains the "business logic" and "domain objects":

  • Protocol Enums: Frontend2BackendMsg, Backend2FrontendMsg, and Peer2PeerMsg define the serialization contracts.
  • Game Types: Core poker logic like Game, Player, Card.

4. Cryptography Layer (WIP) ​

A dedicated layer (living within shared/communication and upcoming modules) for Mental Card Game mechanics:

  • Verifiable Actions: Provides traits and structures (e.g., ElgamalCiphertext, ModularElement) so that MCG actions (like drawing or shuffling cards) can be cryptographically verified by other players without trusting a central server.
  • Protocols: Supports ZK proofs and encrypted state transitions.

5. Card Game DSL (CGDSL) ​

A bespoke language and compiler toolchain designed to generalize the game rules beyond hardcoded poker.

  • front_end: The compiler front-end that parses .cg files. It converts the syntax into an Abstract Syntax Tree (AST), performs semantic validation, and lowers the logic into an Intermediate Representation (IR) / Finite State Machine (FSM).
  • code_gen: A macro-heavy crate that automates the generation of spanned ASTs (retaining code source locations) to remove structural boilerplate.
  • Future Integration: A dedicated Game Engine (currently on the dev/akeller branch) runs the IR generated by this DSL. The Native Backend will utilize this Game Engine to execute arbitrary card games.

6. QR Comm (crates/qr_comm/) ​

Implements the protocol for transmitting data over a series of QR codes.

  • Network Coding: Uses Galois Field arithmetic to create linear combinations of data fragments.
  • Fountain Code: Allows the receiver to reconstruct the original data from any sufficient subset of received frames, handling packet loss gracefully.