Skip to main content
TokoTubeIC OS

Cards Against IC

A decentralized, multiplayer Cards Against Humanity game built on the Internet Computer blockchain with server-authoritative game state and real-time updates.

Cards Against IC

Cards Against IC

Decentralized multiplayer card game on the Internet Computer

Cards Against IC is a decentralized, multiplayer Cards Against Humanity game built on the Internet Computer blockchain. This project demonstrates complex multiplayer game mechanics on ICP with server-authoritative game state, real-time updates, and secure authentication.

What is Cards Against IC?

Cards Against IC brings the popular party card game to the blockchain with enhanced security and fairness. Built entirely on the Internet Computer, it features:

  • Server-authoritative game state with complete validation
  • Real-time multiplayer support for 3-10 players per game
  • Secure authentication via Internet Identity principals
  • Atomic operations to prevent race conditions
  • Fair card dealing with cryptographically secure shuffling

Key Features

Gameplay Mechanics

Lobby System

  • Automatic game start when 3+ players join
  • Support for 3-10 players per game
  • Real-time player count updates

Card Management

  • Server-shuffled decks with fair distribution
  • 10 cards dealt to each player's hand
  • Configurable card packs and custom cards

Game Flow

  • Multiple game phases: Submission → Judging → Results → Next Round
  • Card Czar rotation for fair turn-based judging
  • Points awarded for winning rounds
  • Configurable round limits (default: 10 rounds)

Security & Fairness

Server Validation

  • All moves validated server-side
  • Zero-trust architecture - never trust client input
  • Principal-based authentication prevents impersonation

Privacy Protection

  • Hands hidden from other players
  • Anonymous submissions during judging phase
  • Only revealed to Card Czar

Fair Randomness

  • Cryptographically secure card shuffling
  • Deterministic dealing across all players
  • No predictable patterns or exploits

Technical Architecture

Cards Against IC follows the proven Reversi reference architecture for IC games:

		┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Internet       │    │   Canister      │
│   (SvelteKit)   │◄──►│   Identity       │◄──►│   (Motoko)      │
│                 │    │                  │    │                 │
│ • Game UI       │    │ • Auth           │    │ • Game State    │
│ • Real-time     │    │ • Principal IDs  │    │ • Card Logic    │
│ • Polling       │    │                  │    │ • Validation    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Technology Stack

Backend (Motoko Canister)

  • Complete game state management
  • Player authentication and authorization
  • Card dealing and shuffling algorithms
  • Move validation and scoring
  • Efficient data structures for ICP cycles

Frontend (SvelteKit)

  • Responsive UI with mobile-first design
  • Real-time polling for game state updates
  • Component-based architecture
  • Error boundaries and graceful failure handling
  • @dfinity/agent for canister communication
  • @dfinity/auth-client for Internet Identity

AI Integration

  • Autonomous development workflows
  • Feature tracking in ai/tracker.md
  • Architecture mapping in ai/sitemap.md
  • Custom AI commands for game-specific workflows

Development Status

Component Status Progress
Backend Canister ✅ Complete 100%
AI Integration ✅ Complete 100%
Implementation Guide ✅ Complete 100%
Frontend 🔄 In Progress 30%
Testing 🔄 Planned 10%
Deployment 🔄 Planned 0%

Completed Features

  • ✅ Complete Motoko backend implementation
  • ✅ Exact type definitions matching specification
  • ✅ Comprehensive API with proper query/update separation
  • ✅ Security-first design with zero-trust validation
  • ✅ Performance optimization for ICP cycles
  • ✅ AI infrastructure integration
  • ✅ Complete implementation guide

In Development

  • 🔄 Frontend UI components
  • 🔄 Internet Identity authentication integration
  • 🔄 Real-time game state polling
  • 🔄 Mobile-responsive design

How It Works

Data Flow

  1. Authentication: User authenticates via Internet Identity → gets Principal
  2. Lobby: Frontend polls canister for lobby status
  3. Game Start: Automatic start when 3+ players join
  4. Gameplay: User actions (submit cards, judge) → canister update calls
  5. Validation: Canister validates moves → updates state → returns result
  6. Updates: Frontend reflects changes via polling

Game Logic

Core API Functions

  • joinLobby(playerName) - Join the game lobby
  • leaveLobby() - Leave before game starts
  • loadCards() - Load card packs after game starts
  • submitCards() - Submit your cards for the round
  • judgeWinner() - Card Czar selects the winning submission
  • nextRound() - Start the next round
  • getGameState() - Query current game state
  • getLobbyStatus() - Check lobby waiting status

Game States

  • #Waiting - Waiting for players to join
  • #Playing - Cards being submitted
  • #Judging - Card Czar selecting winner
  • #RoundEnd - Showing round results
  • #GameEnd - Game finished with final scores

Development & AI Integration

Cards Against IC is integrated into the shared AI development infrastructure following the same patterns as tokotube and seachan projects.

AI Commands Available

  • ./ai/autonomous.sh - Full AI development workflow
  • ./ai/game:validate - Validate game logic and CAH rule compliance
  • ./ai/frontend:implement - Implement frontend features and UI components
  • ./ai/canister:test - Test canister functions and performance
  • ./ai/multiplayer:test - Test multiplayer scenarios and synchronization

Containerized Development

Cards Against IC uses a containerized development environment:

		# Start the full development environment
pnpm dev
 
# This will:
# 1. Build the development container (first time only)
# 2. Start local Internet Computer replica
# 3. Deploy canisters
# 4. Start frontend development server
# 5. Mount your workspace for live development

Access Points:

Security Considerations

Authentication & Authorization

  • Internet Identity provides cryptographically secure principal-based authentication
  • Server validates caller identity for all operations
  • Principal IDs prevent user impersonation
  • Stateless authentication via signed requests

Game Logic Security

  • All game logic runs server-side
  • Zero-trust architecture - client inputs are validated
  • Atomic operations prevent race conditions
  • Strict validation of card submissions and turn order

Data Privacy & Fairness

  • Only player's own cards visible to them
  • Card submissions anonymized until judging phase
  • Server-side card shuffling with cryptographically secure random
  • Deterministic dealing across all players

Testing Strategy

Backend Testing (80%+ Coverage)

  • Unit tests for game logic functions
  • Integration tests for canister calls
  • Load tests for concurrent games
  • Security validation tests

Frontend Tests (Planned)

  • Component unit tests
  • E2E multiplayer testing with Playwright
  • Mobile responsiveness tests
  • Performance benchmarks

Multiplayer Scenarios

  • Lobby joining and auto-start with 3+ players
  • Card submission race conditions
  • Czar judging with timeouts
  • Player disconnection handling
  • State synchronization across clients

Deployment

Local Development

		dfx start --background
dfx deploy
# Frontend available at localhost:4943

Mainnet Deployment

		dfx deploy --network ic
# Get production URLs
dfx canister info cards_against_ic_frontend

Use Cases

For Players

  • Play Cards Against Humanity with friends online
  • Secure, fair gameplay with blockchain verification
  • No central server or trust required
  • Mobile-friendly responsive design

For Developers

  • Reference implementation for multiplayer games on ICP
  • Server-authoritative game state patterns
  • Real-time polling and state synchronization
  • Security best practices for blockchain games

For the ICP Ecosystem

  • Demonstrates complex game mechanics on IC
  • Proves feasibility of real-time multiplayer games
  • Educational resource for game developers
  • Showcases AI-powered development workflows

Metrics & Success Criteria

  • Performance: <2s response times for game actions
  • Reliability: 99.9% uptime with graceful error handling
  • Security: Zero-trust validation, no game state exploits
  • Scalability: Support 100+ concurrent games
  • User Experience: Smooth real-time gameplay across devices

Links

Why Cards Against IC?

Cards Against IC serves as a comprehensive reference for building complex multiplayer games on the Internet Computer. By implementing the full game logic with server-authoritative state, secure authentication, and real-time updates, it demonstrates:

  • Security: Zero-trust architecture with comprehensive validation
  • Fairness: Cryptographically secure random and transparent game state
  • Scalability: Efficient data structures for ICP cycles
  • User Experience: Smooth real-time gameplay with responsive UI
  • Development: AI-powered autonomous development workflows

This implementation provides a solid foundation for building any multiplayer game on the Internet Computer, from card games to board games to real-time strategy games.

This project demonstrates advanced ICP development patterns and serves as educational reference material for building multiplayer games on the Internet Computer.