karata

Karata (cards) is a Swahili word that refers to both the Kenyan game of cards and the cards used to play it.

Real-time Kenyan street poker over ASP.NET Core SignalR/websockets.

The game is currently playable and implements all game logic.

There is also a custom cards library with a complete test suite.

Features

• Game rules
• Real-time gameplay
• Real-time in-game chat
• Activity feed
• Password-protected rooms
• Player disconnection/reconnection handling
• Resumable games
• Configurable rules
• Game replays
• Friend system
• Tournaments/Knockouts
• Fines for illegal moves
• Bots
• Learner mode
• Desktop app (Experimental)

How to run this

.NET Aspire

Note

This method requires both the .NET 10 SDK and the .NET Aspire CLI.

PostgreSQL and Keycloak are provisioned automatically as Docker containers by Aspire, so no separate installation is required.

The easiest way to run everything locally is to run the Aspire AppHost:

git clone https://github.com/peter-mghendi/karata.git
cd karata

aspire run
# OR
dotnet run --project src/Karata.AppHost/Karata.AppHost.csproj

This starts the follwing services:

• A PostgreSQL database.
• A Keycloak server
• Karata.Platform
• Karata.Cards
• Karata.Trivia
• Karata.Bot
• Karata.Web
• Karata.Desktop

Important

Every application is configured as an OAuth 2.0/OpenID Connect (OIDC) client.

Confidential clients are created with a default client secret. You can regenerate this secret at any time from the Keycloak Admin Console.

For more information, see the Keycloak Server Administration guide:

• OIDC authentication flows
• Confidential client credentials

Individual Projects

Karata.Platform

Karata.Platform is mostly infrastructure, a centralized user service that currently stores user data and activity as reported by other services. It is built on the the Karata.Runtime "framework".

Docker (recommended)

The latest server image is published to GitHub Container Registry:

Pull

docker pull ghcr.io/peter-mghendi/karata-platform:latest

Run:

docker run -d \
  --name karata-platform \
  --env-file path/to/your/.env \
  -p 5000:5000 \
  ghcr.io/peter-mghendi/karata-platform:latest

A PostgreSQL-compatible database is required.

Pre-built binary

Pre-built server binaries are attached to GitHub Releases.

Builds are currently available for:

• linux-arm64
• linux-x64

chmod +x karata-server
source path/to/your/.env ./karata-server

The server expects its configuration to be supplied via environment variables.

Building from source

Build from source:

git clone https://github.com/peter-mghendi/karata.git
cd karata

dotnet publish src/Karata.Platform -c Release

---

Karata.Cards

Karata.Cards is the supported card game server runtime. It is built on the the Karata.Runtime "framework".

Docker (recommended)

The latest server image is published to GitHub Container Registry:

Pull

docker pull ghcr.io/peter-mghendi/karata-cards:latest

Run:

docker run -d \
  --name karata-cards \
  --env-file path/to/your/.env \
  -p 5000:5000 \
  ghcr.io/peter-mghendi/karata-cards:latest

A PostgreSQL-compatible database is required.

Pre-built binary

Pre-built server binaries are attached to GitHub Releases.

Builds are currently available for:

• linux-arm64
• linux-x64

chmod +x karata-server
source path/to/your/.env ./karata-server

The server expects its configuration to be supplied via environment variables.

Building from source

Build from source:

git clone https://github.com/peter-mghendi/karata.git
cd karata

dotnet publish src/Karata.Cards -c Release

---

Karata.Trivia

Karata.Trivia is the supported trivia game server runtime, adapted from QuizWars with support for Karata auth. It is built on the the Karata.Runtime "framework".

Docker (recommended)

The latest server image is published to GitHub Container Registry:

Pull

docker pull ghcr.io/peter-mghendi/karata-trivia:latest

Run:

docker run -d \
  --name karata-trivia \
  --env-file path/to/your/.env \
  -p 5000:5000 \
  ghcr.io/peter-mghendi/karata-trivia:latest

A PostgreSQL-compatible database is required.

Pre-built binary

Pre-built server binaries are attached to GitHub Releases.

Builds are currently available for:

• linux-arm64
• linux-x64

chmod +x karata-server
source path/to/your/.env ./karata-server

The server expects its configuration to be supplied via environment variables.

Building from source

Build from source:

git clone https://github.com/peter-mghendi/karata.git
cd karata

dotnet publish src/Karata.Trivia -c Release

---

Karata.Web

Karata.Web is the official browser client built completely on public, documented APIs, the Karata.Kit SDK and the Karata.Surface UI kit.

Release Artifact

Compiled frontend assets are attached to GitHub Releases as karata-web.tar.gz.

Extract the archive and serve the resulting files using any static web server.

tar -xzf karata-web.tar.gz

Published Assets Branch

The latest generated frontend assets are also available in the releases-web branch.

This branch contains build output only and may be used directly with static hosting providers.

Building from source

Build from source:

git clone https://github.com/sixpeteunder/karata.git
cd karata

dotnet publish src/Karata.Web -c Release

---

Karata.Bot

Karata.Bot is a reference bot implementation built on the Karata.Runtime server "framework", which in turn builds on primitives defined in Karata.Kit.

Docker (recommended)

The latest bot image is published to GitHub Container Registry:

Pull

docker pull ghcr.io/peter-mghendi/karata-bot:latest

Run:

docker run -d \
  --name karata-bot \
  --env-file path/to/your/.env \
  -p 5000:5000 \
  ghcr.io/peter-mghendi/karata-bot:latest

A PostgreSQL-compatible database is required.

Pre-built binary

Pre-built bot binaries are attached to GitHub Releases.

Builds are currently available for:

• linux-arm64
• linux-x64

chmod +x karata-bot
source path/to/your/.env ./karata-bot

The bot expects its configuration to be supplied via environment variables.

Building from source

Build from source:

git clone https://github.com/peter-mghendi/karata.git
cd karata

dotnet publish src/Karata.Bot -c Release

---

Karata.Desktop

Karata.Desktop is a multiplatform Photino desktop app built completely on public, documented APIs, the Karata.Kit SDK and the Karata.Surface UI kit.

Pre-built binary (recommended)

Pre-built desktop binaries are attached to GitHub Releases.

Builds are currently available for:

• linux-arm64
• linux-x64

chmod +x karata-desktop
source path/to/your/.env ./karata-dektop

The bot expects its configuration to be supplied via environment variables.

Building from source

Build from source:

git clone https://github.com/peter-mghendi/karata.git
cd karata

dotnet publish src/Karata.Dektop -c Release

---

Included Packages

• Karata.Pips - a .NET class library that defines some common card-game primitives - cards, suits, faces/ranks, decks and piles.
• Karata.Pebble - a tiny, platform-agnostic, Flux-inspired state store built around System.Reactive BehaviourSubjects
• Karata.Kit - an all-encompassing, platform-agnostic SDK classlib that contains the majority of client functionality for Karata.Bot, Karata.Cards (including the game rules engine), Karata.Platform and Karata.Trivia.
• Karata.Runtime - a server focused lib that bootstraps functionality common to Karata servers including OAuth2/OIDC (including RFC 8693 Token Exchange for delegated/"on-behalf-of" auth), health checks, OpenTelemetry, SignalR, WebPush, CORS and more.
• Karata.Surface - a Razor class library that contains shared frontend functionality including Razor UI Components and frontend OAuth2/OIDC auth.

---

Rules

The rules are automatically applied to games, you do not need to actively think about them (unless fines are enabled!) This is mostly included for reference and troubleshooting the game's behaviour. I should probably add these to an in-game "rules" page.

None of the sources I consulted could agree on a canonical set of rules (nor should they!) so I implemented some sensible defaults:

Basics

• The game can only start and end with a non-special card (any card other than those described below).
• Players may choose to enable a one or two card "fine" for invalid moves.
• Fines are off by default and enabled on a per-game basis.
• The winner is the first player to discard all of their cards while on "last card" status.
• A player cannot enter "last card" status while in possession of an Ace, "Bomb", Jack or King.
• A card sequence that would usually cause the player to play again, e.g. two Kings or "jumping" everyone, is counted as its own turn.

Aces

• Ace of Spades equals two regular Aces.
• One Ace can be used to request a suit.
• Two Aces (or equivalent) can be used to request a specific card.
• Aces can be used to block "bomb" cards.
• Aces can play anywhere.
• Any number of Aces is valid, but three or four aces have no special effects.
• Two aces can request a specific Joker but one Ace can not request a Joker.

"Bombs" - Twos, Threes and Jokers

• Two, three and joker cards cause the next player to pick two, three or five cards respectively.
• Two and three cards can be countered by jokers or "bomb" cards of the same face or suit.
• Jokers can only be countered by jokers or blocked by a single Ace.
• Two and three cards can only play on top cards of the same face or suit.
• Jokers can play anywhere.
• Anything can play on top of jokers.
• Picking is not cumulative. Only the top card's value need be picked.
• Picking cannot be "jumped" or "kicked back".

"Jumps" - Jacks

• A Jack played will "jump" the next player (two Jacks played in succession will jump two players, etc.).
• A Jack must be played on top of a card of the same face(Jack) or suit.
• Jumping cannot be blocked, e.g. by another Jack placed by a "jumped player".

"Questions" - Queens and Eights

• Queen and Eight cards are "Question" cards which require an "Answer".
• A Queen or Eight must be played on top of a card of the same face or suit.
• Valid answer cards are any cards of the same face or suit (including other questions).
• Every rank of card (Ace to King) is a valid answer card.

"Kickbacks" - Kings

• A King will cause the direction of the game to reverse.
• A King must be played on top of a card of the same face(King) or suit.
• An even number of Kings played at once will cause the current player to play again.
• A single King played in a two-person game will have no effect.