From fc6b87515e53458ed4e07997a25d2ff9fc77660b Mon Sep 17 00:00:00 2001 From: admin Date: Sat, 25 Jul 2026 21:25:53 +0000 Subject: [PATCH] docs: update documentation for rules engine integration - HANDOFF.md: Added rules engine section, updated architecture diagram - state.json: Updated project summary, files_created, files_modified, commit_hash - README.md: Added rules engine to features and architecture - ROADMAP.md: Added MTG Rules Engine Integration section (2.10) --- HANDOFF.md | 40 +++++++++++++++++++++++++++------------- README.md | 12 ++++++++++++ ROADMAP.md | 12 +++++++++++- state.json | 26 +++++++++++++++++++------- 4 files changed, 69 insertions(+), 21 deletions(-) diff --git a/HANDOFF.md b/HANDOFF.md index 4bef473..4f5516e 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -72,21 +72,27 @@ All planned tasks have been completed: ``` mtgonline/ ├── backend/ # FastAPI application +│ ├── mtg_rules_engine/ # MTG rules engine (rules enforcement) +│ │ ├── engine.py # Core game engine +│ │ ├── rules_engine.py # Rules engine core +│ │ ├── keywords.py # Card keywords +│ │ ├── keywords_db.py # Keywords database +│ │ ├── keyword_validator.py # Keyword validation +│ │ ├── validator.py # Card validation +│ │ ├── updater.py # Engine updater +│ │ ├── update_check.py # Update checker +│ │ ├── test_engine.py # Engine tests +│ │ └── README.md # Rules engine docs │ ├── app/ │ │ ├── core/ # Settings, database engines, Redis client │ │ ├── models/ # SQLAlchemy ORM models (user_data.py - 16 models) -│ │ ├── routers/ # API route modules (auth, users, decks, rooms, games, admin, cards, interactions, refresh, ws) -│ │ │ ├── user_data.py # User data endpoints (replays, collections, groups, etc.) -│ │ ├── schemas/ # Pydantic request/response schemas (user_data_schemas.py) +│ │ ├── routers/ # API route modules +│ │ ├── schemas/ # Pydantic request/response schemas │ │ ├── services/ # Business logic (MTGJSON manager, card DB, game server, deck parser) -│ │ └── main.py # FastAPI app entry point (user-data mounted at /api/v1/user-data) +│ │ └── main.py # FastAPI app entry point │ ├── alembic/ # Database migrations -│ │ ├── env.py # Async Alembic configuration -│ │ └── versions/ # Migration scripts -│ │ └── 001_initial_user_schema.py -│ ├── scripts/ # Utility scripts (downloads, migrations, checks) -│ │ └── run_migrations.sh -│ ├── Dockerfile # Updated to run migrations on startup +│ ├── scripts/ # Utility scripts +│ ├── Dockerfile │ ├── requirements.txt │ └── .env.example ├── docker-compose.dev.yml # Development stack @@ -300,11 +306,19 @@ The v1 backend work has been completed. The following features were implemented: - **Admin**: User list, ban management - **Data Management**: MTGJSON refresh +#### 5. MTG Rules Engine +- **Integrated in `backend/mtg_rules_engine/`** +- **Core modules**: `engine.py`, `rules_engine.py`, `keywords.py`, `validator.py` +- **Supporting modules**: `keywords_db.py`, `keyword_validator.py`, `updater.py`, `update_check.py` +- **Test suite**: `test_engine.py` +- **Purpose**: Enforces MTG game rules (mana, phases, priority, stack resolution, combat) for multiplayer server + ### Testing & Verification - ✅ All API endpoints tested and working - ✅ Database migrations applied successfully - ✅ Docker deployment verified - ✅ Integration tests passing +- ✅ Rules engine source files extracted and integrated --- @@ -633,10 +647,10 @@ Current state saved at: `/home/wall-o/projects/mtgonline/state.json` --- -**Last Updated**: 2026-07-24T04:35:00-04:00 -**Status**: Phase 1-2 Complete. Phase 3 (Multiplayer Game Server) in progress. Game engine code incoming. +**Last Updated**: 2026-07-25T19:58:00-04:00 +**Status**: Phase 1-2 Complete. Phase 3 (Multiplayer Game Server) in progress. Rules engine integrated in `backend/mtg_rules_engine/`. -**Next Action**: Begin Phase 3 — set up multiplayer server scaffolding, integrate game engine, implement WebSocket hub with chat support. +**Next Action**: Begin Phase 3 — set up multiplayer server scaffolding, integrate rules engine, implement WebSocket hub with chat support. **Timeline**: | Phase | Duration | Status | diff --git a/README.md b/README.md index e0d71a3..86e61b4 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ This project provides a backend API for a Magic: The Gathering Online platform. - **Redis Caching** — Used for card lookup caching and interaction pipeline state. - **Card Import Feature** — Users can import their card collection (fuzzy matching enabled) for deckbuilding constraints. - **Deck Management** — Full deck CRUD with precedents, suggestions, and status tracking (DRAFT/FINAL). +- **MTG Rules Engine** — Integrated in `backend/mtg_rules_engine/` for multiplayer game server (rules enforcement, card validation, keyword processing). - **REST API** — `/docs` (Swagger) available at runtime. ## Architecture @@ -20,6 +21,17 @@ This project provides a backend API for a Magic: The Gathering Online platform. ``` mtgonline/ ├── backend/ # FastAPI application +│ ├── mtg_rules_engine/ # MTG rules engine (rules enforcement for multiplayer) +│ │ ├── engine.py # Core game engine +│ │ ├── rules_engine.py # Rules engine core +│ │ ├── keywords.py # Card keywords +│ │ ├── keywords_db.py # Keywords database +│ │ ├── keyword_validator.py # Keyword validation +│ │ ├── validator.py # Card validation +│ │ ├── updater.py # Engine updater +│ │ ├── update_check.py # Update checker +│ │ ├── test_engine.py # Engine tests +│ │ └── README.md # Rules engine docs │ ├── app/ │ │ ├── core/ # Settings, database engines, Redis client │ │ ├── models/ # SQLAlchemy ORM models (app + MTG) diff --git a/ROADMAP.md b/ROADMAP.md index 78f4c76..42acae8 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -162,7 +162,17 @@ A modern web-based implementation of the MTG Online multiplayer Magic: The Gathe - [x] Import workflow documentation - [x] Play backend integration guide -### 2.10 Multiplayer Play Backend — Architecture Blueprint (DERIVED FROM COCKATRICE ANALYSIS) +### 2.10 MTG Rules Engine Integration + +The MTG rules engine has been integrated into the backend for multiplayer game server support: + +- [x] **Integrated in `backend/mtg_rules_engine/`** +- [x] Core modules: `engine.py`, `rules_engine.py`, `keywords.py`, `validator.py` +- [x] Supporting modules: `keywords_db.py`, `keyword_validator.py`, `updater.py`, `update_check.py` +- [x] Test suite: `test_engine.py` +- [x] Purpose: Enforces MTG game rules (mana, phases, priority, stack resolution, combat) for multiplayer server + +### 2.11 Multiplayer Play Backend — Architecture Blueprint (DERIVED FROM COCKATRICE ANALYSIS) A detailed architecture analysis of **Cockatrice** (v3.1.0 "Graduation Day") — the mature open-source MTG online client/server — has been completed at `/home/wall-o/projects/mtgonline/C++/ARCHITECTURE_ANALYSIS.md`. diff --git a/state.json b/state.json index 026032f..1a3f8fe 100644 --- a/state.json +++ b/state.json @@ -1,5 +1,5 @@ { - "project_summary": "MTG Online Backend API with PostgreSQL database. Implements card game platform with deck management, card import, and user data features. Uses FastAPI, SQLAlchemy async, and Alembic for database migrations. Now expanding to multiplayer game server phase.", + "project_summary": "MTG Online Backend API with PostgreSQL database. Implements card game platform with deck management, card import, and user data features. Uses FastAPI, SQLAlchemy async, and Alembic for database migrations. MTG rules engine integrated in backend/mtg_rules_engine/ for multiplayer game server phase.", "roadmap": [ { "phase": 1, @@ -57,9 +57,9 @@ "redis[hiredis]==5.1.0" ] }, - "architectural_notes": "Dual database setup: mtgonline for app data, mtgdata for MTGJSON card data. Alembic migrations run on container startup. Async SQLAlchemy with asyncpg driver. Card mirrors in mtgo_platform for fast deckbuilding queries. User data API mounted at /api/v1/user-data. Card import router mounted at /api/v1/card-import. Phase 3 adds server-authoritative game engine with WebSocket real-time multiplayer, 11-phase MTG turn structure, stack resolution, card zones, deck validation, and replay recording.", + "architectural_notes": "Dual database setup: mtgonline for app data, mtgdata for MTGJSON card data. Alembic migrations run on container startup. Async SQLAlchemy with asyncpg driver. Card mirrors in mtgo_platform for fast deckbuilding queries. User data API mounted at /api/v1/user-data. Card import router mounted at /api/v1/card-import. Phase 3 adds server-authoritative game engine with WebSocket real-time multiplayer, 11-phase MTG turn structure, stack resolution, card zones, deck validation, and replay recording. MTG rules engine integrated in backend/mtg_rules_engine/.", "task_description": "Multiplayer game server — Phase 3 handoff. Architecture derived from Cockatrice analysis (v3.1.0 Graduation Day). Server-authoritative game engine with WebSocket real-time multiplayer, 11-phase MTG turn structure, stack resolution, card zones, deck validation, and replay recording. Handoff document at handoff.md provides complete blueprint.", - "current_step": "Phase 2 complete. Handoff document prepared for Phase 3: Multiplayer game server. Ready to begin implementation.", + "current_step": "Phase 2 complete. MTG rules engine integrated in backend/mtg_rules_engine/. Ready to begin Phase 3: Multiplayer game server implementation.", "files_created": [ "alembic.ini", "alembic/env.py", @@ -82,7 +82,18 @@ "TEST_PLAN.md", "API_DOCUMENTATION.md", "C++/ARCHITECTURE_ANALYSIS.md", - "handoff.md" + "handoff.md", + "backend/mtg_rules_engine/engine.py", + "backend/mtg_rules_engine/rules_engine.py", + "backend/mtg_rules_engine/keywords.py", + "backend/mtg_rules_engine/keywords_db.py", + "backend/mtg_rules_engine/keyword_validator.py", + "backend/mtg_rules_engine/validator.py", + "backend/mtg_rules_engine/updater.py", + "backend/mtg_rules_engine/update_check.py", + "backend/mtg_rules_engine/test_engine.py", + "backend/mtg_rules_engine/__init__.py", + "backend/mtg_rules_engine/README.md" ], "files_modified": [ "app/models/__init__.py", @@ -90,8 +101,9 @@ "app/main.py", "README.md (card import section added)", "backend/README.md (API endpoint reference)", - "state.json (Phase 3 handoff)", - "ROADMAP.md (Phase 3+ documented)" + "state.json (rules engine integrated)", + "ROADMAP.md (rules engine documented)", + "HANDOFF.md (rules engine documented)" ], "decisions": [ "Using Alembic for version-controlled database migrations", @@ -122,6 +134,6 @@ "Update documentation and push to Gitea" ], "blockers": [], - "commit_hash": "1e7c762", + "commit_hash": "165a6f1", "timestamp": "2026-07-25T19:58:00-04:00" }