Cardryl - Configurable Card Game Engine

A cross-platform card game engine built with Flutter that allows users to create and play custom card games with configurable rule sets over LAN multiplayer.

🎯 Features

• Configurable Rule Sets: Create custom card games using JSON-based rule files
• LAN Multiplayer: Host and join games over local network
• Standard 52-Card Deck: Support for multiple decks
• Flexible Game Rules: Define dealing patterns, turn orders, actions, and win conditions
• Poker Support: Full Texas Hold'em with betting, hand ranking, and community cards
• Cross-Platform: Works on Android, iOS, Web, and Desktop (via Flutter)

🏗️ Project Structure

cardryl/
├── lib/
│   ├── core/                    # Constants and utilities
│   │   ├── constants.dart
│   │   └── extensions.dart
│   ├── models/                  # Data models
│   │   ├── card.dart           # Playing card model
│   │   ├── deck.dart           # Deck management
│   │   ├── player.dart         # Player model
│   │   ├── rule_set.dart       # Rule set model
│   │   └── game_state.dart     # Game state model
│   ├── services/               # Business logic
│   │   ├── rule_parser.dart    # Rule set parser
│   │   ├── action_validator.dart # Action validation
│   │   ├── game_engine.dart    # Core game engine
│   │   ├── poker_hand_evaluator.dart # Poker hand ranking
│   │   ├── poker_betting_service.dart # Poker betting logic
│   │   └── network/            # Networking layer
│   ├── ui/                     # User interface
│   │   ├── screens/
│   │   └── widgets/
│   ├── providers/              # State management
│   └── main.dart               # App entry point
├── assets/
│   └── rules/                  # Rule set JSON files
│       ├── rummy.json
│       ├── hearts.json
│       └── crazy_eights.json
└── test/                       # Tests

📋 Rule Set Format

Rule sets are defined using JSON files with the following structure:

{
  "metadata": {
    "name": "Game Name",
    "version": "1.0",
    "description": "Game description",
    "minPlayers": 2,
    "maxPlayers": 6,
    "deckCount": 1
  },
  "setup": {
    "dealPattern": "roundRobin",
    "cardsPerPlayer": 7,
    "startingPlayer": "random"
  },
  "turns": {
    "order": "clockwise",
    "actionsPerTurn": ["draw", "play", "discard"],
    "mandatoryActions": ["discard"]
  },
  "actions": {
    "draw": { /* action config */ },
    "play": { /* action config */ }
  },
  "validation": {
    /* validation rules */
  },
  "winCondition": {
    "type": "nocard",  // or "maxcards", "card_name", "points"
    /* additional config */
  }
}

Preset Win Conditions

• nocard: First player to empty their hand wins
• maxcards: Game ends when all cards are played, winner determined by score
• card_name: Win by having (or not having) a specific card
• points: First player to reach target points wins

🚀 Getting Started

Prerequisites

• Flutter SDK (3.0.0 or higher)
• Dart SDK
• Android Studio / Xcode (for mobile development)

Installation

1. Clone the repository:

git clone <repository-url>
cd cardryl

2. Install dependencies:

flutter pub get

3. Run the app:

flutter run

🎮 How to Play

1. Create a Room: Host a game by selecting a rule set and creating a room
2. Join a Room: Discover and join available rooms on your local network
3. Play: Follow the rules defined in the selected rule set
4. Win: Achieve the win condition specific to the game

🛠️ Development Status

✅ Completed

• Core data models (Card, Deck, Player, RuleSet, GameState)
• Rule set parser and validator
• Game engine with turn management
• Action validation system
• Win condition checking
• Poker support: Hand evaluation, betting system, community cards
• LAN networking: Discovery, room management, client-server communication
• Four example rule sets (Rummy, Hearts, Crazy Eights, Texas Hold'em)
• Basic UI structure

🚧 In Progress

• Game UI screens (lobby, game table)
• Card widgets and animations

📝 Planned

• State management with Riverpod
• Rule set editor
• More example games
• Sound effects
• Statistics tracking

📝 Planned

• Rule set editor
• More example games
• Card animations
• Sound effects
• Statistics tracking

📖 Creating Custom Rule Sets

See the example rule Sets in assets/rules/ for reference. You can create your own by:

1. Creating a new JSON file following the rule set schema
2. Placing it in the assets/rules/ directory
3. Loading it in the app's Rule Set Manager

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests.

📄 License

This project is open source and available under the MIT License.

🎯 Roadmap

• Complete LAN networking
• Add more card game rule sets
• Implement rule set visual editor
• Add tournament mode
• Support for custom card graphics
• AI players for single-player mode