docs: Add detailed card systems documentation files

Author: tyler274

docs/card_systems/database/card_attributes.md

@@ -0,0 +1,142 @@
+# Card Attributes
+
+This document details the attributes tracked for each card in the Rummage database. These attributes define a card's characteristics, behavior, and appearance.
+
+## Core Attributes
+
+### Identification
+
+- **Oracle ID**: Unique identifier for the card's Oracle text
+- **Name**: The card's name
+- **Set Code**: The three or four-letter code for the card's set
+- **Collector Number**: The card's number within its set
+- **Rarity**: Common, uncommon, rare, mythic rare, or special
+
+### Card Type Information
+
+- **Type Line**: The full type line text
+- **Supertypes**: Legendary, Basic, Snow, etc.
+- **Card Types**: Creature, Instant, Sorcery, etc.
+- **Subtypes**: Human, Wizard, Equipment, Aura, etc.
+
+### Mana and Color
+
+- **Mana Cost**: The card's mana cost
+- **Mana Value**: The converted mana cost (total mana)
+- **Colors**: The card's colors
+- **Color Identity**: Colors in mana cost and rules text
+- **Color Indicator**: For cards with no mana cost but have a color
+
+### Rules Text
+
+- **Oracle Text**: The official rules text
+- **Flavor Text**: The card's flavor text
+- **Keywords**: Keyword abilities (Flying, Trample, etc.)
+- **Ability Words**: Words that have no rules meaning (Landfall, etc.)
+
+### Combat Stats
+
+- **Power**: Creature's power (attack strength)
+- **Toughness**: Creature's toughness (health)
+- **Loyalty**: Starting loyalty for planeswalkers
+- **Defense**: Defense value for battles
+
+### Legality
+
+- **Format Legality**: Legal status in various formats
+- **Reserved List**: Whether the card is on the Reserved List
+- **Banned/Restricted**: Status in various formats
+
+## Special Card Attributes
+
+### Multi-faced Cards
+
+- **Card Faces**: Data for each face of the card
+- **Layout**: Card layout type (normal, split, flip, etc.)
+- **Face Relationship**: How faces relate to each other
+
+### Tokens
+
+- **Token Information**: Data for tokens created by the card
+- **Token Colors**: Colors of created tokens
+- **Token Types**: Types of created tokens
+
+### Counters
+
+- **Counter Types**: Types of counters the card uses
+- **Counter Placement**: Where counters can be placed
+- **Counter Effects**: Effects of counters on the card
+
+## Implementation
+
+Card attributes are implemented as components in the ECS:
+
+```rust
+// Example of card type components
+#[derive(Component)]
+pub struct CardName(pub String);
+
+#[derive(Component)]
+pub struct ManaCost {
+    pub cost_string: String,
+    pub parsed: ParsedManaCost,
+}
+
+#[derive(Component)]
+pub struct CardTypes {
+    pub supertypes: Vec<Supertype>,
+    pub card_types: Vec<CardType>,
+    pub subtypes: Vec<Subtype>,
+}
+
+#[derive(Component)]
+pub struct OracleText(pub String);
+
+#[derive(Component)]
+pub struct PowerToughness {
+    pub power: String,
+    pub toughness: String,
+}
+```
+
+## Attribute Modification
+
+Card attributes can be modified by:
+
+- **Static Effects**: Continuous modifications
+- **One-time Effects**: Temporary changes
+- **Counters**: Modifications from counters
+- **State-Based Actions**: Automatic modifications
+
+## Attribute Access
+
+Systems access card attributes through queries:
+
+```rust
+// Example of a system that queries card attributes
+fn check_creature_types(
+    creatures: Query<(Entity, &CardTypes, &CardName)>,
+) {
+    for (entity, card_types, name) in creatures.iter() {
+        if card_types.card_types.contains(&CardType::Creature) {
+            // Process creature card
+            let creature_subtypes = &card_types.subtypes;
+            // ...
+        }
+    }
+}
+```
+
+## Attribute Serialization
+
+Attributes are serialized for:
+
+- **Persistence**: Saving game state
+- **Networking**: Transmitting card data
+- **UI Display**: Showing card information
+
+## Related Documentation
+
+- [Data Structure](data_structure.md): Overall structure of card data
+- [Card Database](index.md): How card data is stored and retrieved
+- [Card Rendering](../rendering/index.md): How attributes affect card appearance 

docs/card_systems/database/data_structure.md

@@ -0,0 +1,145 @@
+# Data Structure
+
+This document details the structure of card data in the Rummage database, explaining how card information is organized and stored.
+
+## Card Data Model
+
+The core card data is modeled using a structured format:
+
+### Primary Card Entities
+
+- **CardDefinition**: The fundamental card entry containing all card data
+- **CardEdition**: Specific information for a card in a particular set
+- **CardFace**: Data for one face of a card (for multi-faced cards)
+
+### Core Card Data
+
+Each card contains these core attributes:
+
+```rust
+// Simplified example of core card data structure
+pub struct CardDefinition {
+    pub oracle_id: Uuid,          // Unique identifier
+    pub name: String,             // Card name
+    pub mana_cost: Option<String>,// Mana cost string
+    pub type_line: String,        // Type line text
+    pub oracle_text: String,      // Oracle rules text
+    pub colors: Vec<Color>,       // Card colors
+    pub color_identity: Vec<Color>,// Color identity
+    pub keywords: Vec<String>,    // Keyword abilities
+    pub power: Option<String>,    // Power (for creatures)
+    pub toughness: Option<String>,// Toughness (for creatures)
+    pub loyalty: Option<String>,  // Loyalty (for planeswalkers)
+    pub card_faces: Vec<CardFace>,// Multiple faces if applicable
+    pub legalities: Legalities,   // Format legalities
+    pub reserved: bool,           // On the reserved list?
+}
+```
+
+## Storage Format
+
+Card data is stored in multiple formats:
+
+- **JSON files**: Static card data stored on disk
+- **Binary format**: Optimized runtime representation
+- **Database**: For web-based implementations
+
+### JSON Structure
+
+The JSON structure follows a standardized format for interoperability:
+
+```json
+{
+  "oracle_id": "a3fb7228-e76b-4e96-a40e-20b5fed75685",
+  "name": "Lightning Bolt",
+  "mana_cost": "{R}",
+  "type_line": "Instant",
+  "oracle_text": "Lightning Bolt deals 3 damage to any target.",
+  "colors": ["R"],
+  "color_identity": ["R"],
+  "keywords": [],
+  "legalities": {
+    "standard": "not_legal",
+    "modern": "legal",
+    "commander": "legal"
+  }
+}
+```
+
+## Parsed Structures
+
+Rules text and other complex fields are parsed into structured data:
+
+### Mana Cost Representation
+
+Mana costs are parsed into a structured format:
+
+```rust
+pub struct ManaCost {
+    pub generic: u32,            // Generic mana amount
+    pub white: u32,              // White mana symbols
+    pub blue: u32,               // Blue mana symbols
+    pub black: u32,              // Black mana symbols
+    pub red: u32,                // Red mana symbols
+    pub green: u32,              // Green mana symbols
+    pub colorless: u32,          // Colorless mana symbols
+    pub phyrexian: Vec<Color>,   // Phyrexian mana symbols
+    pub hybrid: Vec<(Color, Color)>, // Hybrid mana pairs
+    pub x: bool,                 // Contains X in cost?
+}
+```
+
+### Rules Text Parsing
+
+Rules text is parsed into an abstract syntax tree:
+
+```rust
+pub enum RulesTextNode {
+    Text(String),
+    Keyword(KeywordAbility),
+    TriggeredAbility {
+        trigger: Trigger,
+        effect: Effect,
+    },
+    ActivatedAbility {
+        cost: Vec<Cost>,
+        effect: Effect,
+    },
+    StaticAbility(StaticEffect),
+}
+```
+
+## Card Relationships
+
+The database tracks relationships between cards:
+
+- **Token creators**: Cards that create tokens
+- **Meld pairs**: Cards that meld together
+- **Companions**: Cards with companion relationships
+- **Partners**: Cards with partner abilities
+- **Flip sides**: Two sides of double-faced cards
+
+## Indexing and Lookup
+
+The data structure includes optimized indexes for:
+
+- **Name lookup**: Fast retrieval by card name
+- **Type lookup**: Finding cards by type
+- **Text search**: Finding cards with specific rules text
+- **Color lookup**: Finding cards by color identity
+- **Format lookup**: Finding cards legal in specific formats
+
+## Data Versioning
+
+The database supports versioning of card data:
+
+- **Oracle updates**: Tracking rules text changes
+- **Erratas**: Handling card corrections
+- **Set releases**: Managing new card additions
+- **Format changes**: Updating format legalities
+
+## Related Documentation
+
+- [Card Attributes](card_attributes.md): Detailed information about card attributes
+- [Effect Implementation](../effects/index.md): How card effects are implemented from data
+- [Card Database](index.md): Overview of the card database system