Multi-Mode Card Framework

A production-grade, modular card game engine demonstrating senior-level software architecture, decoupled MVC design patterns, and cross-platform deployment.

👀 EPIC 3 Current State Overview

🎯 Project Overview

Multi-Mode Card Framework is a comprehensive, decoupled card game engine built with Unity that demonstrates professional game development practices. The core game logic is completely isolated from the presentation layer, enabling 100% reusability across platforms and future projects.

What Makes This Different

Pure C# Core: All game logic lives in POCO (Plain Old C# Objects) with zero Unity dependencies—enabling clean unit testing and reusability
True Modularity: Core engine can be extracted and used in any C# project (RPGs, puzzle games, etc.)
Multi-Platform: Single codebase deploys to WebGL, PC, Mobile, and Meta Quest 3 with adaptive UI
Production Architecture: MVC pattern, dependency injection, event-driven systems, and assembly definitions
Portfolio Quality: Comprehensive documentation, 85%+ test coverage, and CI/CD automation

🎮 Features

Current Implementation (EPIC-03 ✅ | EPIC-02-04 🔄)

Game Engines

⏳ Blackjack (21): Full rules with Ace mechanics and dealer AI (stand on soft 17)
⏳ Solitaire: Klondike variant with move validation and win conditions
⏳ Texas Hold'em: Poker rules engine (future phase)

Architecture

✅ Decoupled MVC: Model (Core), View (UI), Controller (Orchestration)
✅ Dependency Injection: Lightweight DI container preventing singletons
✅ Assembly Definitions: Clean layer separation (Core, Presentation, Input, Cloud, Tests)
✅ Event System: UnityEvent-based pub/sub for loose coupling
✅ Unit Testing: NUnit EditMode tests (85%+ coverage)

Platform Support

✅ WebGL: Browser-based gameplay
✅ PC Standalone: Windows/Mac (60fps @ 1920x1080)
✅ Mobile: iOS/Android (30fps adaptive)
🔄 Meta Quest 3: VR gameplay (90fps target)

Backend (Optional - Configured)

🔄 Cloud Persistence: PlayFab integration
- Cross-progression via PIN linking
- Cloud save synchronization
- Player profiles and accounts
💬 LootLocker Alternative: Planned fallback with Non-commercial license license

🏗️ Architecture

Layer Separation

┌─────────────────────────────────────────┐
│        Presentation Layer (Views)       │ (MonoBehaviour)
│  CardView, PlayerStatusView, UIManager  │
└────────────────────┬────────────────────┘
                     │ UnityEvents
                     ▼
┌─────────────────────────────────────────┐
│      Controller Layer (Orchestration)   │ (MonoBehaviour)
│ BlackjackController, TableController    │
└────────────────────┬────────────────────┘
                     │ Direct access
                     ▼
┌─────────────────────────────────────────┐
│      Model Layer (Pure C#, NO Unity)    │ (POCO)
│ CardData, Deck, BlackjackEngine, etc.   │
└─────────────────────────────────────────┘

Assembly Definitions (AsmDef)

Project.Core: Pure C# game logic (zero dependencies)
Project.Presentation: Views & Controllers (references Core)
Project.Input: Input handling (references Core)
Project.Cloud: Backend services (references Core)
Project.XR: VR/Meta Quest support (optional, references Core & Presentation)
Project.Tests: Unit & integration tests
Project.Editor: Editor tools and utilities

Key Design Patterns

Pattern	Usage	Benefit
MVC	Separation of concerns	Testable, reusable
Dependency Injection	Service registration	No singletons, testable
Strategy	Game variant engines	Swappable implementations
Observer (UnityEvents)	Event propagation	Loose coupling
Adapter	Platform-specific input	Single interface, multiple platforms
Finite State Machine	Game phase management	Clear state transitions

🚀 Quick Start

Requirements

Unity: 6.3 LTS
Git: Latest version
IDE: Visual Studio Code
RAM: 8GB minimum, 16GB recommended
Disk: 50GB+ free space

Setup (15 minutes)

# 1. Clone repository
git clone https://github.com/yourusername/multi-mode-card-framework.git
cd multi-mode-card-framework

# 2. Open in Unity (2022 LTS or later)
# File > Open Project > select folder

# 3. Wait for initial import and compilation (~2-3 minutes)

# 4. Verify setup
# Window > Test Runner > EditMode > Run All
# Expected: ~104 tests passing, 87% coverage

# 5. Open demo scene
# Scenes/Initialization.unity (then GameScene_Blackjack.unity)

First Build (WebGL Example)

# File > Build Settings
# - Select WebGL platform
# - Click "Build"
# - Output directory: Builds/WebGL
# - Build time: ~2-3 minutes

📖 Documentation

Document	Purpose
BACKLOG.md	Detailed task breakdown, dependencies, and tracking
PROJECT_STRUCTURE.md	Folder hierarchy and assembly definition strategy
ARCHITECTURE.md	Architecture decisions and design rationale (coming soon)

🧪 Testing

Run Tests Locally

# EditMode tests (fast, no scenes)
Window > Test Runner > EditMode > Run All

# Or from command line:
~/Unity/Editor/Unity -projectPath . \
  -runTests -testPlatform editmode \
  -logFile test-results.log

Test Coverage

Target: 85%+
Current: 87% (EPIC-01)
Tools: NUnit + OpenCover

Coverage Report

# Generate coverage report (CI/CD automation)
# Results available in: test-results/coverage.html

🔄 Development Workflow

Branching Strategy

main (stable releases only)
  ↓
develop (integration branch)
  ↓
feature/EPIC-XX-description (individual work)
  ↓
feature/TASK-X.X-description (granular tasks)

Commit Convention

# Format:
git commit -m "TASK-X.X: Brief description

Details:
- What was implemented
- Why this approach was chosen
- Any blockers or considerations"

# Examples:
git commit -m "TASK-1.1: Implement CardData and Deck with Fisher-Yates shuffle"
git commit -m "TASK-2.1: Setup LootLocker integration with guest authentication"

Creating a PR

Create feature branch: feature/TASK-X.X-description
Commit frequently with clear messages
Push to GitHub: git push origin feature/TASK-X.X-description
Create Pull Request
Verify CI/CD tests pass (GitHub Actions)
Request code review
Merge to develop after approval

📊 Project Status

EPIC Progress

Epic	Tasks	Status	Target Completion
EPIC-01: Core Pure C# Game Logic	4/4	✅ COMPLETED	Week 4
EPIC-02: Architecture & DI Scoping	3/3	✅ COMPLETED	Week 8
EPIC-03: UI/UX Presentation Layer	3/3	✅ COMPLETED	Week 12
EPIC-04: Cloud Infrastructure & State	0/3	🔄 IN PROGRESS	Week 16
EPIC-05: XR Integration & Meta Quest	0/4	⏳ PLANNED	Week 20

Granular Phase Updates (EPIC-03 ✅)

TASK-3.5: Extracted loose modal windows out of specific views into an independent ModalServiceView driven by on-demand runtime lifecycle queries to prevent UI Toolkit panel focus leakages.
TASK-3.6: Standardized multi-platform input mappings by abstracting interactions behind an agnostically injected IInputContext strategy pattern.
TASK-3.7: Completed responsive elastic USS parameters for mobile portrait WebGL setups alongside 3D local coordinate mathematical hand layout auto-centering.

Timeline

Part-time (20-25 hrs/week): 16-20 weeks
Full-time (40 hrs/week): 7-9 weeks
Current Phase: Starting EPIC-04 | ✅

🚀 AI-Accelerated Velocity & Sprint Metrics

This project demonstrates hyper-efficient development velocity by integrating advanced AI-assisted engineering workflows (GitHub Copilot, Cursor, Ollama, and LLM orchestration) to compress traditional enterprise timelines.

Sprint 1 Summary (Duration: 2 Weeks)

Traditional Baseline Estimation: 12 Weeks (To research, scaffold core architectures, and implement fully responsive multi-platform UI layouts from scratch).
Actual AI-Augmented Timeline: 2 Weeks (Completed Sprint 1 today).
Velocity Multiplier: ~6x development speed optimization.

Timeline Compression Breakdown

Phase / Milestone	Estimated (Manual)	Actual (AI-Driven)	Status	Efficiency Gain
EPIC-01: Pure C# Domain Engine	Weeks 1 - 4	Days 1 - 4	Decoupled	85% Time Reduc.
EPIC-02: Architecture & DI Layer	Weeks 5 - 8	Days 5 - 8	Solidified	80% Time Reduc.
EPIC-03: Responsive UI Toolkit	Weeks 9 - 12	Days 9 - 14	Production	88% Time Reduc.

💡 Architectural Note: This acceleration wasn't achieved by cutting corners. The code maintains a strict Decoupled MVC design pattern, uses VContainer for dependency injection, features adaptive spatial calculation algorithms for portrait mobile viewports, and maintains a stable 90% min Unit Test coverage.

🌍 Backend Services

PlayFab Cloud Infrastructure (Primary System)

Free tier: Up to 100,000 user accounts
API: REST endpoints (similar to LootLocker)
Docs: https://docs.microsoft.com/gaming/playfab/

Status: Free Tier Ecosystem (Sandbox Mode)
Authentication Vector: Silent Device ID authentication for friction-free modern player profile creation.
Features Used:

Guest Device Lifecycle Management
Cloud Save JSON State Synchronization
Cross-progression Data Synchronization

Configuration Workflow:

# Securely loaded inside CI/CD runner secrets—NEVER commit raw data variants to repo
PLAYFAB_TITLE_ID=your_playfab_title_id

LootLocker (Alternative)

Status: Free tier (no monetization)
License: Applied for enterprise free tier (waiting approval)
Features Used:

Guest authentication
Cloud save persistence
Player profiles
Cross-progression (PIN linking)

Configuration:

# Store in CI/CD secrets, NOT in repository
LOOTLOCKER_GAME_ID=your_game_id
LOOTLOCKER_API_KEY=your_api_key

Migration Path:

Implement ICloudService interface abstraction
Create PlayFabCloudService implementation
Update DI container bindings
Update configuration

🛠️ Development Tools

Required

Unity 6.3 LTS+: Game engine
Visual Studio Code or Rider: C# IDE with debugger
Git: Version control
GitHub CLI: Optional, for PR management

Optional (Recommended)

Git Desktop: GUI for Git
Unity Profiler: Built-in performance analysis
Visual Studio: Advanced C# debugging
Meta XR All-in-One SDK: For Quest 3 development

Setup VS Code Extensions

Extensions to install:
- C# (powered by OmniSharp)
- Debugger for Unity
- GitLens
- Thunder Client (REST testing)

🚢 Deployment

Platform Targets

Platform	Status	Build Time	Output Size
WebGL	✅ Ready	~2-3 min	<50MB
Windows PC	✅ Ready	~3-5 min	~150MB
macOS	✅ Ready	~5-7 min	~150MB
iOS	🔄 EPIC-04	~10 min	~200MB
Android	🔄 EPIC-04	~8 min	~200MB
Meta Quest 3	⏳ EPIC-05	~5-7 min	~250MB

Build Commands (CLI)

# WebGL
~/Unity/Editor/Unity -projectPath . -buildTarget WebGL \
  -executeMethod BuildScript.BuildWebGL

# Windows
~/Unity/Editor/Unity -projectPath . -buildTarget StandaloneWindows64 \
  -executeMethod BuildScript.BuildWindows

# Android
~/Unity/Editor/Unity -projectPath . -buildTarget Android \
  -executeMethod BuildScript.BuildAndroid

🤝 Contributing

This is a solo development portfolio project.

For feedback or suggestions:

Create GitHub Issue
Include: description, reproduction steps, expected behavior

📚 References & Resources

Documentation

BACKLOG.md - Detailed task tracking
PROJECT_STRUCTURE.md - Folder organization

External Resources

Useful Tools

GitHub Actions - CI/CD automation
Game-CI - Unity CI/CD workflows
ShaderGraph - Visual shader creation

🎓 Learning Resources

Architecture & Design Patterns

MVC Pattern: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller
Dependency Injection: https://en.wikipedia.org/wiki/Dependency_injection
Unity Best Practices: https://learn.unity.com/

Game Development

Brackeys Game Development: https://www.youtube.com/c/Brackeys
Game Programming Patterns: https://gameprogrammingpatterns.com/

🐛 Troubleshooting

Build Issues

Problem: "Assembly not found"

Solution: Verify .asmdef files exist and references are correct
Command: Assets > Reimport All

Problem: "Input System not responding"

Solution: Verify GameplayActions.inputactions asset exists
Path: Assets/_Project/Input/GameplayActions.inputactions

Performance Issues

Problem: "Game dropping below 60fps"

Solution: Open Window > Analysis > Profiler and identify bottleneck
Common Fixes:
- Reduce draw calls (batch static geometry)
- Lower shadow distance (20-30 meters)
- Disable MSAA on mobile

📞 Support

Getting Help

GitHub Issues: Create an issue if you find a bug or have a feature request
Search Existing Issues: Your question may already be answered

Reporting Bugs

Please include:

Description of the issue
Reproduction steps
Expected vs actual behavior
Environment (Unity version, platform, etc.)

🎉 Acknowledgments

This project demonstrates professional game development practices through:

Clean Architecture: Decoupled MVC pattern
Quality Assurance: 85%+ test coverage with NUnit
Documentation: Comprehensive guides and code examples
Cross-Platform Support: WebGL, PC, Mobile, and VR
CI/CD Integration: Automated testing and builds

Built as a senior-level portfolio project showcasing production-ready code quality and architectural best practices.

📊 Project Metrics

Code Coverage: 90% (target: 85%+)
Documentation: (BACKLOG, STRUCTURE)
Assembly Definitions: 7 (clean separation)
CI/CD Pipeline: GitHub Actions (automated)
Test Suite: 102 unit tests (EditMode)
Target Platforms: (WebGL, PC, Mobil, Quest 3)

Last Updated: July 2026
Maintenance Status: Active Development
Project Type: Solo Portfolio | Production-Grade Game Engine

Quick Links

🌐 Play Online: (Coming soon - WebGL build)
📦 Releases: GitHub Releases
📋 Issues: GitHub Issues
📖 Wiki: GitHub Wiki

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github		.github
.vscode		.vscode
Assets		Assets
Packages		Packages
ProjectSettings		ProjectSettings
ReadMePreviewImages		ReadMePreviewImages
UIElementsSchema		UIElementsSchema
graphify-out		graphify-out
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.graphify_python		.graphify_python
CLAUDE.md		CLAUDE.md
MultiModeCardFramework.slnx		MultiModeCardFramework.slnx
README.md		README.md
merge_semantic.py		merge_semantic.py

Folders and files

Latest commit

History

Repository files navigation