BeziqueCardGame.SDK 1.5.0

Bezique Card Game SDK

A comprehensive C# SDK for implementing the Bezique card game in Unity and .NET applications. The SDK provides complete game logic, rule enforcement, AI opponents, and online multiplayer capabilities through a server-authoritative architecture.

Features

• Complete Game Rules - Full implementation of Bezique rules including melds, tricks, trump mechanics, and scoring
• Server-Authoritative - All game logic resides server-side; clients are pure presentation layers
• Unity Compatible - Targets netstandard2.1 for Unity 2021.3+ compatibility
• AI Opponents - Built-in AI bot controllers for single-player scenarios
• Online Multiplayer - SignalR-based real-time multiplayer with matchmaking
• Authentication - Built-in authentication (guest, email/password, Google OAuth)
• Event-Driven API - Clean event system for UI updates and game state changes

Installation

.NET Projects

Install the SDK via NuGet Package Manager or .NET CLI:

dotnet add package BeziqueCardGame.SDK

Unity Projects

Using NuGetForUnity (recommended):

1. Install NuGetForUnity
2. Search for BeziqueCardGame.SDK in the NuGet window
3. Click Install

The SDK will automatically include all required dependencies:

• BeziqueCardGame.SDK.Core - Data models and types
• BeziqueCardGame.SDK.Local - Local gameplay and AI
• BeziqueCardGame.SDK.MatchMaker - Online multiplayer client
• BeziqueCardGame.Sdk.Auth - Authentication

Quick Start

Single-Player Game (Human vs AI)

using BeziqueCardGame.SDK.Core;
using BeziqueCardGame.SDK.Local;

// Configure the match
var config = new MatchConfig(
    GameMode.Standard,   // Standard or Advanced
    targetScore: 750,
    playerCount: 2
);

// Set up controllers: Human vs AI
var controllers = new IPlayerController[]
{
    new HumanController(),
    new AiBotController(new LocalRandom())
};

// Create and start the game
var client = new LocalGameClient(config, controllers);

// Subscribe to game events
client.OnTrumpRevealed += (suit, card) => {
    Console.WriteLine($"Trump card: {card.ToCardString()}");
};

client.OnTrickEvaluated += (winner, cards) => {
    Console.WriteLine($"Player {winner} won the trick!");
};

client.OnRoundEnded += (scores) => {
    Console.WriteLine($"Final scores: {scores[0]} - {scores[1]}");
};

// Start the game
if (client.TryStartSinglePlayerGame(out string error))
{
    // Game is running - call RunUntilHumanInput() after each human action
    client.RunUntilHumanInput();
}
else
{
    Console.WriteLine($"Failed to start: {error}");
}

Playing Cards

// Human player plays a card
byte playerId = 0;
byte cardToPlay = hand[0];  // Card byte from player's hand

if (client.TryPlayCard(playerId, cardToPlay, out string error))
{
    // Card accepted - let AI play until next human input needed
    client.RunUntilHumanInput();
}
else
{
    Console.WriteLine($"Invalid play: {error}");
}

Declaring Melds

// After winning a trick, declare a meld
var meldCards = new List<byte> { card1, card2, card3, card4, card5 };

if (client.TryDeclareMeld(playerId, meldCards, out string error))
{
    Console.WriteLine("Meld accepted!");
}
else
{
    Console.WriteLine($"Invalid meld: {error}");
}

API Reference

LocalGameClient

The main class for managing local games.

Constructor

LocalGameClient(MatchConfig config, IPlayerController[] controllers)

Key Methods

State Queries

Events

MatchConfig

Game configuration settings.

public struct MatchConfig
{
    public readonly GameMode GameMode;     // Standard or Advanced
    public readonly ushort TargetScore;    // 750, 1000, or 1500
    public readonly byte PlayerCount;      // 2 or 4 players
    public readonly byte AceTenThreshold;  // Calculated based on player count
}

IPlayerController

Interface for player input controllers.

public interface IPlayerController
{
    byte ChooseCard(IReadOnlyList<byte> hand, GameStateView state);
    List<byte> ChooseMeld(IReadOnlyList<byte> hand, byte trumpSuit, GameStateView state);
    bool ChooseTrump7Swap(GameStateView state);
}

Unity Integration

MonoBehaviour Example

using UnityEngine;
using BeziqueCardGame.SDK.Core;
using BeziqueCardGame.SDK.Local;

public class BeziqueGameManager : MonoBehaviour
{
    private LocalGameClient _client;
    private byte _humanPlayerId = 0;

    void Start()
    {
        var config = new MatchConfig(GameMode.Standard, 750, 2);
        var controllers = new IPlayerController[]
        {
            new HumanController(),
            new AiBotController(new LocalRandom())
        };

        _client = new LocalGameClient(config, controllers);
        SubscribeToEvents();

        if (!_client.TryStartSinglePlayerGame(out string error))
        {
            Debug.LogError($"Failed to start: {error}");
            return;
        }

        RefreshUI();
    }

    // Called from UI when player taps a card
    public void OnCardTapped(byte cardByte)
    {
        if (_client.CurrentPlayerId != _humanPlayerId) return;

        if (!_client.TryPlayCard(_humanPlayerId, cardByte, out string error))
        {
            ShowErrorToast(error);
            return;
        }

        _client.RunUntilHumanInput();
        RefreshUI();
    }

    void RefreshUI()
    {
        if (_client.TryGetPlayerHand(_humanPlayerId, out var hand, out _))
        {
            UpdateHandDisplay(hand);
        }

        ushort[] scores = _client.GetAllScores();
        UpdateScoreDisplay(scores);

        // Update UI based on current game phase
        switch (_client.CurrentPhase)
        {
            case GamePhase.Playing:
                ShowPlayCardUI();
                break;
            case GamePhase.MeldDecision:
                ShowMeldUI();
                break;
            case GamePhase.Trump7Swap:
                ShowTrump7SwapUI();
                break;
            case GamePhase.GameOver:
                ShowGameOverScreen();
                break;
        }
    }

    void SubscribeToEvents()
    {
        _client.OnTrumpRevealed += (suit, card) => {
            UpdateTrumpIndicator(card);
        };

        _client.OnTrickEvaluated += (winner, cards) => {
            AnimateTrickWin(winner, cards);
        };

        _client.OnRoundEnded += (scores) => {
            ShowRoundSummary(scores);
        };
    }
}

For detailed Unity integration instructions, see the Consumer Guide.

Online Multiplayer

For online multiplayer functionality, use the AuthClient and GameClient classes from the included MatchMaker SDK.

using BeziqueCardGame.Sdk.Auth;
using BeziqueCardGame.SDK.MatchMaker;

// Authenticate
var authClient = new AuthClient("https://your-server.com");
var loginResult = await authClient.GuestLoginAsync();

// Connect to game hub
var gameClient = await loginResult.Session.ConnectToGameAsync();

// Create or join a room
var roomResult = await gameClient.CreateOrJoinRoomAsync("Bezique");

// Listen for game events
gameClient.OnGameState += (state) => {
    // Update UI with server state
};

Game Rules Overview

Bezique is a trick-taking card game for 2-4 players using 4 standard decks plus 4 jokers (132 cards total).

Objective

First player to reach the target score (750, 1,000, or 1,500 points) wins.

Scoring

Card Ranking

Ace > 10 > King > Queen > Jack > 9 > 8 > 7

For complete rules, see the Game Rules Documentation.

Requirements

• .NET 10.0 or .NET Standard 2.1 (for Unity compatibility)
• Unity 2021.3+ (for Unity projects)

Documentation

Consumer Documentation (SDK Users)

Developer Documentation

License

This project is licensed under the MIT License.

Package ID: BeziqueCardGame.SDK Version: 1.0.5 Authors: CoreLoopStudio