Repolode
Submit
Calix-L

Calix-L/DanKS

An open-source reinforcement learning agent for competitive Guandan, a four-player partnership card game, with a playable web table.

View on GitHubWebsite
Stars
705
Forks
22
Open issues
1
Last commit
15 days ago

What is it?

DanKS is a research codebase for building AI players for GuanDan, a four-player partnership card game with hidden information. Its agent ranks legal plays by first retrieving structured candidate actions, then evaluating how each play affects the combinations left in the hand, and finally learning the choice with a state- and candidate-conditioned Actor-Critic network trained with PPO and GAE.

The repository is organized into three AI generations (V1, V2, V3) plus a V3Pro inference-refinement package that adds asset protection, equivalent-play rules, and endgame search without retraining. It also includes the KSPlay GuanDan Service in two versions: a browser-based room backend, referee, and frontend that can run locally with rule-based example bots and accept external AI through an HTTP interface.

The project links to a public dataset of human GuanDan matches maintained in a sister repository, and provides examples for retrieval, model inference, and V3Pro integration using synthetic inputs. Trained weights and private serving infrastructure are not included.

Key features

  • 01Structured candidate retrieval that evaluates the remaining hand after each play
  • 02Actor-Critic policy trained with PPO and GAE self-play
  • 03V3Pro inference refinement for endgame search and equivalent-play rules
  • 04Browser-based GuanDan table with room backend and referee
  • 05HTTP interface for connecting a custom AI to the service
  • 06Link to a public dataset of 899 human GuanDan matches

Use cases

  • Studying decision-making under hidden information in a partnership card game
  • Training and comparing reinforcement learning policies on a card game environment
  • Building a custom GuanDan AI and connecting it to a local web table
  • Analyzing human match records for hand structure and partnership play

Quick start

  1. 1

    Clone the repository

    git clone https://github.com/Calix-L/DanKS.git
  2. 2

    Enter the service directory and create a Python 3.12 virtual environment

    cd DanKS/services/v2 && python3.12 -m venv .venv && source .venv/bin/activate
  3. 3

    Install requirements and build the arranger

    python -m pip install -r requirements.txt && python scripts/build_arranger.py
  4. 4

    Start the local table, then open http://127.0.0.1:8000/solo

    python run.py

Things to know

  • Needs Python 3.12 and Go 1.23+ for the local table.
  • Trained model weights and private AI serving infrastructure are not included.

Topics

#reinforcement-learning#game-ai#pytorch#card-games#ppo#guandan

FAQ

What is DanKS?
An open-source reinforcement learning agent for competitive Guandan, a four-player partnership card game, with a playable web table. DanKS is a research codebase for building AI players for GuanDan, a four-player partnership card game with hidden information. Its agent ranks legal plays by first retrieving structured candidate actions, then evaluating how each play affects the combinations left in the hand, and finally learning the choice with a state- and candidate-conditioned Actor-Critic network trained with PPO and GAE.
Is DanKS free to use? What license does it have?
DanKS is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is DanKS still maintained?
Actively maintained. The last commit to DanKS was on Oct 5, 2026.
What can I use DanKS for?
Studying decision-making under hidden information in a partnership card game Training and comparing reinforcement learning policies on a card game environment Building a custom GuanDan AI and connecting it to a local web table Analyzing human match records for hand structure and partnership play
How do I install DanKS?
Clone the repository: git clone https://github.com/Calix-L/DanKS.git Enter the service directory and create a Python 3.12 virtual environment: cd DanKS/services/v2 && python3.12 -m venv .venv && source .venv/bin/activate Install requirements and build the arranger: python -m pip install -r requirements.txt && python scripts/build_arranger.py Start the local table, then open http://127.0.0.1:8000/solo: python run.py
Where can I get DanKS?
The source code and installation instructions are on GitHub: https://github.com/Calix-L/DanKS

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects