mk2lib 1.1.0

Machi Koro 2 Game Engine

mk2lib

Machi Koro 2 Game Engine

A Python library for modeling and simulating the rules, components, and gameplay logic of Machi Koro 2 boardgame that focuses on correctness, which could be used for AI training, trying out custom house rules or new cards, etc.

---

Table of Contents

• Features
• What is it not
• Getting Started
  • Requirements
  • Installation
• Usage
• Tests
• Contributing
• License
• Acknowledgements

---

Features

• Complete implementation of core mechanics and rules of Machi Koro 2 (including landmark promo pack).
• Full encapsulation of game logic within mk2lib and presentation abstraction, you can build any UI on top of it easily.
• Rule enforcement: mk2lib tracks everything and checks move legality. You only need to input moves.
• Event bus architecture that allows end application to observe game state and handle changes.
• Support for 2-5 players.
• Modular design: can be easily extended for new house rules, possible future addons, etc.
• Support for fast game serialization/deserialization and AI agent friendly design.
• Comprehensive pytest testsuite with 100% coverage to ensure implementation correctness.

---

What is it not

• A standalone ready-to-play game (unless you're willing to play from interactive Python REPL).
• Machi Koro 2 AI/Bot (although it includes random fuzzing agent in test_fuzzing.py, which could be used as baseline for measuring AI performance).

---

Getting Started

Requirements

• Python 3.10+
• (Optional) pytest for running the test suite.

Installation

Install module from PyPI:

pip install mk2lib

Or just clone this repository:

git clone https://github.com/ostrosablin/mk2lib.git
cd mk2lib

---

Usage

Here's a minimal example to give you an idea how to use this library.

from mk2lib import MachiKoroGame

# Initialize game with player ID 1 as owner.
game = MachiKoroGame(1)

# Player with ID 2 joins lobby.
game.join(2)

# Owner (1) starts game with landmark promo pack and random player order.
game.start(1, use_promo=True, randomize_players=True)

# Try to build a Convenience Store as current player.
game.build_card(None, "convenience_store")

# Read out all game's events.
while not game.events.empty():
    print(game.events.get())

You can find more complex example of game being (auto-)played from start to end in test_fuzzing.py.

---

Tests

Tests are included in tests/ directory within this repo. To run them, execute:

pytest --cov=mk2lib --cov-report=html

In root of repo. Ensure all tests pass before making changes or opening pull requests.

---

Contributing

Contributions are welcome! If you'd like to help, please:

1. Fork the repository.
2. Create a branch with bugfix or feature.
3. Make changes and cover them with tests.
4. Open a pull request.

Please follow the existing code style, add documentation for new features and ensure tests cover your changes.

---

License

mk2lib is licensed under GNU General Public License, Version 3.0. See LICENSE for full license text.

---

Acknowledgements

DISCLAIMER: This is an unofficial fan project, based on board game ‘Machi Koro 2’. ‘Machi Koro’ is a trademark of its respective owners. This project is not affiliated with or endorsed by them in any way.