How drcheeseface/mahc works
Main Components
• CLI Interface – This is where user commands (arguments and flags) enter the system (e.g., from src/main.rs). It handles mode selection (manual mode, normal mode, analyse mode) and file inputs.
• Core Scoring Engine – Modules in the calc directory (src/calc.rs and src/calc/*) implement the core logic. This engine receives validated input (hand details or manual han/fu inputs) and drives the scoring calculations.
• Hand and Tile Representation – Modules for hand (src/hand.rs, src/hand/error.rs) and tiles (src/tile.rs, src/tile_group.rs, src/suit.rs) model the game’s structure. They represent the raw game states (tiles, suits, groups, etc.) and are essential for detecting valid yaku and calculating fu.
• Payment Logic – The module in src/payment.rs calculates and returns payment values once han/fu (score) have been computed.
• Library Interface – The lib.rs file exposes public functions and types of the library, so users can utilize it directly in their Rust projects.
• Additional Supporting Modules – Other modules like src/limit_hand.rs, src/fu.rs, src/score.rs, and src/yaku.rs are used to handle specific scoring rules, limits and validations based on riichi mahjong rules.
Relationships and Interactions
• User Input flows from the CLI interface. Depending on the selected mode:
– In Calculator Mode, input parameters like han and fu are forwarded directly to the scoring and payment modules.
– In Normal Mode, the CLI passes the tile information and any additional flags to the hand/tile parser, then forwards the constructed Hand object to the scoring engine.
• The parsed hand or tiles are used by the scoring engine, which collaborates with the yaku and fu modules to determine valid scoring patterns.
• Once the score is established, the payment module computes point values based on whether the player is dealer or non-dealer.
• Finally, the results are serialized or printed (optionally as JSON) back through the CLI.
Architectural Patterns and Design Principles
• Modular Design: The project is organized into clear, modular components (e.g., calc, hand, tile, payment) that each serve specific roles.
• Separation of Concerns: There is a clear distinction between the core scoring logic and the CLI presentation—making the library reusable.
• Domain-Specific Abstraction: The code models Riichi Mahjong concepts directly (tiles, suits, yaku, etc.), which simplifies reasoning about the game logic.
• Error Handling: There are error modules within subdirectories (e.g., src/calc/error.rs, src/hand/error.rs) suggesting a separation of error concerns.
Relevant Technologies and Frameworks
• Rust: The entire project is built in Rust, and the Cargo.toml file indicates dependency management.
• GitHub Actions: The .github/workflows directory (with rust.yml) suggests automated CI/CD.
• CLI Parsing: Likely uses a CLI argument parser (such as clap or structopt) though it is not explicitly shown, it is implied by the mode-specific command usage.