feat: Add Mathdoku game to Sir Lancebot

[daDevBoat]

Co-authors

Co-authored-by: JannisHaeffner jannis.haeffner@yahoo.de
Co-authored-by: djonte djonatanbolenius@gmail.com
Co-authored by: arpega75 arnau.pelechano@gmail.com
Co-authored by: knasssss alexander.mannertorn@gmail.com

Relevant Issues

Closes #989

Description

Implement a mathdoku game, in the style proposed by the issue.

The Mathdoku feature is implemented as a subsystem across three modules with clear separation of responsibilities.

1. Game Logic (mathdoku.py)

This module contains the core game model:

• Cell: stores coordinates (row, column), block, player guess, and correct value.
• Block: stores block metadata (id, operation, number, assigned cells, color).
• Grid: stores board state and game rules (latin-square rules, full-board checks, check block constraints, evaluates win condition, hint cooldown handling...).

This module is independent from Discord commands, so game correctness can be verified independently from the bot's event handling.

2. Board Parsing (mathdoku_parser.py)

This module reads mathdoku_boards.txt, extract board definitions, builds Grid objects, assign blocks and operations, and loads the correct solution values.

This module acts as the entry point for board data, transforming raw text into structured game objects ready to be used by the game logic.

3. Discord Integration (mathdoku_integration.py)

This module connects the game to Discord and manages the full interaction flow with the player:

• Starts a game session.
• Wait for player input messages with a 10 minutes inactivity timeout.
• Handles guesses from user inputs.
• Handles emoji reactions for hints and block validation.

This module contains no game rules. It receives player input messages,
delegates to the game logic, and sends the result back to Discord.

How to run and play

Start a mathdoku game by typing .md start SIZE DIFFICULTY where size can be any integer from 3-9, and difficulty must be either easy, medium or hard.

You fill in a number by typing its position, followed by your guess. For example: A1 3 to put number 3 in field A1 (top left corner)

To display further rules click the book emoji

Did you:

• Join the Python Discord Community?
• Read all the comments in this template?
• Ensure there is an issue open, or link relevant discord discussions?
• Read and agree to the contributing guidelines?