Skip to content

yusufkaraaslan/deck_deck_go

BranchesTags

Repository files navigation

Card Master Sort

A Unity 6 card sorting puzzle game where you compete against a smart AI algorithm. Arrange 14 cards into valid groups using sequences and sets to maximize your score.

Unity Version C# Version License

🎮 Game Overview

Card Master Sort is a competitive card arrangement puzzle where you face off against an AI opponent using a sophisticated smart sorting algorithm. Your goal is to arrange 14 randomly dealt cards into valid groups while minimizing leftover cards.

Key Features

  • 🤖 AI Competition: Play against a smart AI that uses dynamic programming to find optimal arrangements
  • 🃏 104-Card Deck System: Two complete decks with 4 colors and 13 numbers each
  • 🎯 Three Sorting Algorithms: Numeric Sort, Color Sort, and Smart Sort with joker support
  • 🎨 Modern UI: Clean split-screen interface with animations and drag-and-drop
  • ⚡ Real-time Validation: Manual arrangement validation with group detection
  • 🔄 Command Pattern: Full undo/redo support for all actions
  • 📊 Scoring System: Dynamic scoring based on grouped cards vs leftovers

🎲 Game Rules

Card Groups

You can create two types of valid groups:

1. Sequences (Runs)

  • Same color, sequential numbers
  • Minimum 3 cards, no maximum
  • Example: Red-7, Red-8, Red-9, Red-10

2. Sets

  • Different colors, same number
  • Minimum 3 cards, maximum 4 cards
  • Example: Blue-5, Black-5, Yellow-5, Red-5

Joker (Wildcard)

  • One random card per round becomes a joker
  • Can substitute any card in sequences or sets
  • Only one joker per group
  • Can be placed at start, middle, or end of groups

Scoring

  • Each card in a valid group: +1 point
  • Each leftover card: -2 points
  • Best possible score: 14 points (all cards grouped, 0 leftover)

🎯 How to Play

  1. Arrange Cards

    • Drag and drop cards to manually arrange them
    • OR click NUMERIC, COLOR, or SMART buttons for auto-sorting

  2. Calculate (Validate)

    • Click CALCULATE button to validate your manual arrangement
    • Groups are detected left-to-right with spacers added between them

  3. Compare (Compete!)

    • Click COMPARE button to compete against the AI
    • AI uses the SMART algorithm with dynamic programming
    • Winner popup shows results

  4. Next Round

    • Click NEXT ROUND to start a new round
    • Cards animate back to deck and new cards are auto-dealt

Keyboard Shortcuts

  • 1 - Numeric Sort
  • 2 - Color Sort
  • 3 - Smart Sort
  • Z - Undo
  • Y - Redo

🛠️ Technical Stack

Core Technologies

  • Unity 6.0+ - Game engine
  • C# 9.0 - Primary programming language
  • Universal Render Pipeline (URP) - Rendering pipeline
  • Unity Input System - Modern input handling
  • TextMeshPro - UI text rendering

Architecture Patterns

  • Command Pattern - All user actions (Deal, Sort, Undo/Redo)
  • Strategy Pattern - Three sorting algorithm implementations
  • Unidirectional Data Flow (UDF) - Redux-like state management
  • Object Pooling - Card GameObject reuse for performance
  • Event-Driven Architecture - Decoupled component communication

📁 Project Structure

Assets/
├── _Project/
│   ├── Scenes/
│   │   ├── MainMenu.unity        # Main menu with instructions
│   │   └── MainGame.unity        # Game scene with split-screen layout
│   ├── Scripts/
│   │   ├── Actions/              # State actions (InitializeDeck, DealCards, SortCards)
│   │   ├── Commands/             # ICommand implementations (DealCardsCommand, SortCardsCommand)
│   │   ├── Components/           # MonoBehaviour UI components (CardView, WinnerPopup)
│   │   ├── Core/                 # Pure C# sorting logic (no Unity dependencies)
│   │   │   ├── NumericSortStrategy.cs
│   │   │   ├── ColorSortStrategy.cs
│   │   │   ├── SmartSortStrategy.cs
│   │   │   ├── ManualArrangementValidator.cs
│   │   │   └── DPCardSolver.cs
│   │   ├── Managers/             # GameManager, CommandManager, GridManager, CardPool
│   │   ├── Models/               # Data structures (Card, CardGroup, SortResult)
│   │   ├── Reducers/             # State reducers for UDF pattern
│   │   ├── State/                # Global state schema (GameState, CardSystemState)
│   │   ├── Utils/                # Helper utilities
│   │   └── Editor/               # Unity Editor tools and setup scripts
│   ├── Prefabs/
│   │   ├── P_Card.prefab         # Card prefab with CardView component
│   │   └── P_Spacer.prefab       # Group separator prefab
│   └── Settings/                 # URP and Input System settings
├── Docs/                         # Design documents (GDD, TDD, Project Brief)
└── Tests/                        # Unit tests for sorting algorithms

🧠 Smart Sort Algorithm

The core technical challenge is the Smart Sort algorithm, which uses dynamic programming with bitmask optimization:

Algorithm Overview

  1. Generate All Possible Groups - Both sequences and sets (with/without joker)
  2. Evaluate Combinations - Use bitmask to represent selected groups
  3. Validate Non-Overlapping - Ensure no card is used in multiple groups
  4. Optimize Score - Maximize grouped cards, minimize leftovers

Performance

  • Target: <10ms execution time for 14-card hand
  • Approach: Bitmask DP for efficient state exploration
  • Optimization: Early pruning of invalid combinations

Scoring Formula

totalScore = groupedCards - (leftoverCards * 2)

🎨 Design Decisions

Separation of Concerns

Critical principle: Sorting logic in Core/ is pure C# with no Unity dependencies. This allows:

  • Unit testing without Unity Test Framework overhead
  • Algorithm validation independent of UI
  • Potential reuse in other contexts

State Management

Global state follows Redux-like UDF pattern:

User Input → Command → Action → Reducer → State Update → View Update

All state changes flow through GameStore with event notifications.

Manual vs Auto Arrangement

  • Auto-sort buttons use full optimization algorithms
  • Manual dragging preserves player intent
  • Calculate button validates manual arrangements in exact visual order
  • Compare button re-validates current arrangement before competing

Joker Flexibility

Joker rules designed for maximum flexibility:

  • Can start groups (second card establishes pattern)
  • Works in both sequences and sets
  • Only one per group (standard Rummikub rules)

🚀 Getting Started

Prerequisites

  • Unity 6.0 or later
  • Git (for cloning)

Installation

  1. Clone the repository:
git clone https://github.com/yourusername/card-master-sort.git
cd card-master-sort

  1. Open in Unity Hub:

    • Open Unity Hub
    • Click "Add" and select the project folder
    • Select Unity 6.0+ and open the project

  2. Open the MainMenu scene:

    • Navigate to Assets/_Project/Scenes/MainMenu.unity
    • Press Play to start

Building

To build a standalone version:

  1. Go to File > Build Settings
  2. Add scenes: MainMenu.unity and MainGame.unity
  3. Select your target platform (Windows/Mac/Linux)
  4. Click Build and choose output directory

🧪 Testing

Unit tests are located in Assets/Tests/EditMode/:

  • SortingEngineTests.cs - Algorithm validation tests
  • Tests for numeric sequences, color sets, joker handling
  • Edge case validation

To run tests:

  1. Open Unity Test Runner: Window > General > Test Runner
  2. Select "EditMode" tab
  3. Click "Run All"

📊 Performance Metrics

  • Target Frame Rate: 60 FPS (16.6ms frame time)
  • Smart Sort Execution: <10ms per sort
  • Object Pooling: Card instantiation eliminated during gameplay
  • Animation Performance: Smooth 0.5s transitions with easing curves

🎯 Key Achievements

  • ✅ Clean architecture with separation of concerns
  • ✅ Comprehensive state management with UDF pattern
  • ✅ Smart AI opponent with optimal play
  • ✅ Full undo/redo support via Command pattern
  • ✅ Joker wildcard support in all detection algorithms
  • ✅ Manual arrangement validation with group detection
  • ✅ Real-time re-validation on Compare button
  • ✅ Smooth animations with object pooling
  • ✅ Auto-deal on scene start for streamlined UX

🔮 Future Enhancements

  • Sound effects and music
  • Particle effects for card animations
  • Multiple difficulty levels for AI
  • Tournament mode with multiple rounds
  • Online multiplayer
  • Card skin customization
  • Achievement system
  • Replay system
  • Mobile platform support

📝 Documentation

  • Game Design Document - Assets/Docs/GDD.md
  • Technical Design Document - Assets/Docs/TDD.md
  • Project Brief - Assets/Docs/ProjectBrief.md
  • Workflow Guide - WORKFLOW.md
  • Coding Standards - CLAUDE.md

🤝 Contributing

This is a solo project, but suggestions and feedback are welcome! Feel free to:

  • Open issues for bugs or feature requests
  • Submit pull requests with improvements
  • Share your high scores and strategies

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

👏 Acknowledgments

  • Unity Technologies for the excellent game engine
  • TextMeshPro for beautiful text rendering
  • Claude AI for development assistance and architecture guidance
  • Rummikub for game rule inspiration

📧 Contact

For questions or feedback, please open an issue on GitHub.

Built with ❤️ using Unity 6 and C#

Compete against the AI and see if you can beat the smart sorting algorithm!

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages