62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# Magic: The Gathering Rules Engine
|
|
|
|
A Python-based rules engine designed to validate card text, game actions, and game states against the comprehensive rules of Magic: The Gathering (MTG).
|
|
|
|
## Overview
|
|
|
|
This engine provides a programmatic way to handle the complexities of MTG keywords and rules. It allows developers to verify if card text is consistent with established keywords and to validate whether specific game actions are legal according to the rules database.
|
|
|
|
## Key Features
|
|
|
|
- **Comprehensive Keyword Database**: Manages hundreds of keyword abilities, keyword actions, and ability words, complete with their corresponding rule numbers and definitions.
|
|
- **Card Text Validation**: Analyzes card text to identify keywords and flag potential errors or misspellings.
|
|
- **Action & State Validation**: Provides logic to verify if a specific game action (e.g., an attack or a cast) is valid given the current game state.
|
|
- **Rule Reference Lookup**: Quick retrieval of rule text and summaries for any supported keyword.
|
|
- **Automatic Update System**: Includes an updater to keep the rules database current.
|
|
|
|
## Project Structure
|
|
|
|
| File | Description |
|
|
| :--- | :--- |
|
|
| `engine.py` | High-level interface for the rules engine. |
|
|
| `rules_engine.py` | Core logic for rule application and game state validation. |
|
|
| `keywords.py` | The primary definitions and data for MTG keywords. |
|
|
| `keywords_db.py` | Handles the loading and management of the keyword database. |
|
|
| `keyword_validator.py` | Logic for parsing text and validating keywords. |
|
|
| `validator.py` | General purpose validation utilities. |
|
|
| `updater.py` & `update_check.py` | Tools for checking and applying engine updates. |
|
|
| `test_engine.py` | Comprehensive test suite for verifying engine stability. |
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- Python 3.10+
|
|
|
|
### Running Tests
|
|
To verify the installation and ensure the engine is functioning correctly, run the test suite:
|
|
|
|
```bash
|
|
python3 test_engine.py
|
|
```
|
|
|
|
## Usage Example
|
|
|
|
```python
|
|
from mtg_rules_engine.engine import RulesEngine
|
|
|
|
engine = RulesEngine()
|
|
|
|
# Validate card text
|
|
errors = engine.validate_card("Flying, Trample")
|
|
if not errors:
|
|
print("Card text is valid.")
|
|
|
|
# Get rule information
|
|
info = engine.get_keyword_info('flying')
|
|
print(f"Rule {info['rule']}: {info['definition']}")
|
|
```
|
|
|
|
## Maintenance
|
|
|
|
The engine includes an automated update mechanism. Use `update_check.py` to determine if a newer version of the rules database is available, and `updater.py` to apply those changes.
|