Generic Card Game Engine

A lightweight, engine-independent C# card game logic library built for .NET Framework 4.8.

The project is intentionally generic. It provides basic building blocks for turn-based card games without depending on Unity, networking, Firebase, or any game-specific mechanic.

Repository Structure

GenericCardGameEngine/
├── src/
│   └── GenericCardGameEngine/
│       ├── GenericCardGameEngine.csproj
│       ├── CardGameEngineApi.cs
│       ├── Models/
│       └── Services/
│
├── tests/
│   └── GenericCardGameEngine.Tests/
│       ├── GenericCardGameEngine.Tests.csproj
│       └── Program.cs
│
├── examples/
│   └── UnityExample/
│       └── BasicUsageExample.cs
│
├── GenericCardGameEngine.sln
├── README.md
├── LICENSE
└── .gitignore

Features

• Generic card types: Card1 to Card13
• Default score mapping: Card1 = 1, Card2 = 2, ..., Card13 = 13
• Deck creation and shuffling
• Player hand dealing
• Round and game state tracking
• Play-card action validation
• Simple round and final score calculation
• Optional seeded shuffle for deterministic tests

Basic Usage

using GenericCardGameEngine;
using GenericCardGameEngine.Models;

GameState state = CardGameEngineApi.CreateNewGameState(
    playerCount: 4,
    roundCount: 3,
    turnCount: 5,
    shuffleSeed: 12345
);

PlayerHand firstPlayerHand = state.Hands[0];
Card selectedCard = firstPlayerHand.Cards[0];

GameAction action = CardGameEngineApi.CreatePlayCardAction(
    playerIndex: 0,
    cardId: selectedCard.Id,
    roundNumber: state.CurrentRoundNumber,
    turnNumber: state.CurrentTurnNumber
);

GameActionResult result = CardGameEngineApi.ApplyAction(state, action);

Game Flow

The engine uses a simple turn-based flow:

Create a new game state
↓
Create and shuffle a deck
↓
Deal cards to players
↓
Wait for player actions
↓
Validate and apply played cards
↓
Advance the turn when all players have played
↓
Calculate round scores when the round ends
↓
Start the next round or finish the game
↓
Return the final result

Each player can play one card per turn. When every player has played, the engine automatically advances to the next turn. When all turns in the current round are completed, the engine calculates round scores and either starts the next round or finishes the game.

By default, each round starts with a new shuffled deck and newly dealt player hands.

The engine does not enforce a strict player order inside a turn. Players may submit valid actions in any order, but each player can only play once per turn.

Unity Usage

Build the class library project and copy the generated plugin files into Unity:

src/GenericCardGameEngine/bin/Release/GenericCardGameEngine.dll
src/GenericCardGameEngine/bin/Release/GenericCardGameEngine.xml

Recommended Unity location:

YourUnityProject/
└── Assets/
    └── Plugins/
        ├── GenericCardGameEngine.dll
        └── GenericCardGameEngine.xml

Then import the namespace from your Unity scripts:

using GenericCardGameEngine;
using GenericCardGameEngine.Models;

A minimal Unity example is available here:

examples/UnityExample/BasicUsageExample.cs

Running Tests

The repository includes a dependency-free console test runner.

To run the tests in Visual Studio:

1. Open GenericCardGameEngine.sln.
2. Set GenericCardGameEngine.Tests as the startup project.
3. Run the project.
4. Confirm that the console prints:

ALL TESTS PASSED

The test runner covers the public API, core models, deck creation, shuffling, dealing, scoring, round simulation, game simulation, game state creation, and action validation.

Customization

The default scoring is intentionally simple:

public static int GetCardScore(CardType type)
{
    return (int)type;
}

To create your own game rules, start by editing:

• src/GenericCardGameEngine/Models/CardType.cs
• src/GenericCardGameEngine/Services/DeckFactory.cs
• src/GenericCardGameEngine/Services/RoundScoreCalculator.cs
• src/GenericCardGameEngine/Services/GameActionResolver.cs

Notes

This project does not include Unity-specific runtime logic, networking code, Firebase code, or game-specific mechanics. It is designed to be used as a clean starting point for a custom card game engine.