Contributing#

Game on, Yasuki! is a personal, educational project, but contributions are welcome.

Workflow#

  1. Fork the repo and create a feature branch.

  2. Install dependencies and hooks: pixi install && pre-commit install.

  3. Make your changes and add tests.

  4. Run pixi run test and pre-commit run --all.

  5. Open a pull request.

New to the codebase? Start with Setup, then read Design & Architecture for how the pieces fit together.

Running Tests#

# Python tests
pixi run test

# JS deck builder tests
pixi run test-js

# With coverage
pixi run test -- --cov=yasuki_core --cov=yasuki_gui --cov=yasuki_web --cov-report=html

Linting#

This project uses pre-commit with ruff:

pre-commit install       # once
pre-commit run --all     # run on all files

Project Structure#

src/
├── yasuki_core/          # Game engine and data layer
│   ├── engine/           #   Table state, zones, players, and the rules/ subpackage
│   │   └── rules/        #   State, flow, actions, decisions, abilities, effects, triggers
│   ├── game_pieces/      #   Cards, decks, counters, constants
│   ├── search/           #   Scryfall-style query parser
│   ├── install/          #   Database bootstrap
│   ├── database.py       #   PostgreSQL queries
│   ├── paths.py          #   Asset path configuration
│   └── assets/           #   Bundled data + images
│
├── yasuki_web/           # FastAPI web server
│   ├── main.py           #   App, CORS, static mounts
│   ├── cards.py          #   Card search API
│   ├── rooms.py          #   Game room management
│   ├── websocket.py      #   Multiplayer websockets
│   ├── schemas.py        #   Pydantic message schemas
│   └── static/           #   Deck builder SPA
│
└── yasuki_gui/           # Tkinter desktop client
    ├── __main__.py       #   Entry point
    ├── field_view.py     #   Game board rendering
    ├── controller.py     #   User interaction
    ├── services/         #   Drag-drop, hit-testing, actions
    ├── ui/               #   Dialogs, deck builder, menus
    └── visuals/          #   Sprite and zone rendering

Tests mirror this structure under tests/yasuki_core/, tests/yasuki_web/, tests/yasuki_gui/.

Adding a Card Set#

Card data is committed YAML — the full workflow (set YAML, image manifests, errata) lives in Database & card data. The short version:

  1. Add the set’s card data to src/yasuki_core/assets/database/sets/<slug>.yaml and its metadata to set_info.yaml.

  2. Add the image manifest at src/yasuki_core/assets/database/images/<slug>.yaml.

  3. Reload the database: pixi run install-db --force.