mantimon-tcg/docs/GAME_RULES.md

# Mantimon TCG - Game Rules

This document defines the home-rule modifications for Mantimon TCG, based on a custom hybrid of Pokemon TCG eras. The game features an RPG-style campaign inspired by the Gameboy Color *Pokemon Trading Card Game*.

> **Note**: This is a template. Sections marked with `[TBD]` need to be filled in with your specific rule choices.

## Table of Contents

1. [Campaign Structure](#campaign-structure)
2. [Base Ruleset](#base-ruleset)
3. [Energy System Modifications](#energy-system-modifications)
4. [Deck Building Rules](#deck-building-rules)
5. [Win Conditions](#win-conditions)
6. [Turn Structure](#turn-structure)
7. [Card Types](#card-types)
8. [Status Conditions](#status-conditions)
9. [Glossary](#glossary)

---

## Campaign Structure

The core gameplay loop is a single-player campaign where you challenge NPCs, build your collection, and progress toward becoming the champion.

### Inspiration

The campaign is inspired by **Pokemon Trading Card Game** for Gameboy Color (1998):
- Visit themed "Clubs" (Fire Club, Water Club, etc.)
- Challenge club members to earn booster packs
- Defeat Club Leaders to earn medals
- Collect all medals to challenge the Grand Masters
- Defeat the Grand Masters to become Champion

### Clubs

| Club | Theme | Leader | Medal |
|------|-------|--------|-------|
| [TBD] | Fire-type focused | [TBD] | [TBD] Medal |
| [TBD] | Water-type focused | [TBD] | [TBD] Medal |
| [TBD] | Grass-type focused | [TBD] | [TBD] Medal |
| [TBD] | Lightning-type focused | [TBD] | [TBD] Medal |
| [TBD] | Psychic-type focused | [TBD] | [TBD] Medal |
| [TBD] | Fighting-type focused | [TBD] | [TBD] Medal |
| [TBD] | Mixed/balanced | [TBD] | [TBD] Medal |
| [TBD] | Mixed/balanced | [TBD] | [TBD] Medal |

### NPC Types

| Type | Description | Rewards |
|------|-------------|---------|
| **Club Member** | Regular NPCs in each club | 1-2 booster packs |
| **Club Leader** | Boss of each club, must defeat to earn medal | Medal + 2-4 booster packs |
| **Grand Master** | Elite opponents, require all medals to challenge | Special rewards |
| **Champion** | Final opponent | Champion title |

### Progression

1. **New Player**: Start with a starter deck, can challenge any club
2. **Club Progression**: Defeat club members to practice, then challenge the leader
3. **Medal Collection**: Earn medals by defeating Club Leaders
4. **Grand Masters**: Once all medals collected, Grand Masters become available
5. **Champion**: Defeat all Grand Masters to face the Champion

### Match Rewards

| Outcome | Reward |
|---------|--------|
| Victory vs Club Member | 1-2 booster packs (based on NPC difficulty) |
| Victory vs Club Leader | Medal + 2-4 booster packs |
| Victory vs Grand Master | [TBD] special reward |
| Defeat | No reward, can retry immediately |

### Rematch Rules

- Club Members can be rechallenged anytime for pack rewards
- Club Leaders can be rechallenged after defeat (for packs, medal already earned)
- Grand Masters and Champion can be rechallenged for bragging rights

---

## Base Ruleset

Mantimon TCG uses a **custom hybrid** ruleset, cherry-picking mechanics from multiple Pokemon TCG eras.

### Era Influences

| Mechanic | Era Source | Notes |
|----------|------------|-------|
| Basic turn structure | Classic (Base-Neo) | [TBD] |
| Pokemon stages | [TBD] | Basic, Stage 1, Stage 2, and/or EX/V variants? |
| Trainer card types | [TBD] | Item/Supporter/Stadium split, or classic Trainer? |
| Energy types | [TBD] | How many types? Special energy? |

### What's NOT Included

List of official mechanics that are explicitly excluded:

- [TBD] - e.g., "No VMAX or Gigantamax mechanics"
- [TBD]
- [TBD]

---

## Energy System Modifications

> **Home Rule Focus Area**: Energy attachment rules

### Standard Rule (for reference)

In standard Pokemon TCG, you may attach **one energy card** per turn from your hand to one of your Pokemon.

### Modified Rule

[TBD] - Describe your energy system changes here. Examples of possible modifications:

- [ ] **Multiple attachments**: Attach up to X energy per turn
- [ ] **Type-free energy**: All basic energy counts as colorless
- [ ] **Energy acceleration**: Specific cards/abilities that attach extra energy
- [ ] **Energy generation**: Start of turn gain energy tokens instead of cards
- [ ] **Shared energy pool**: Energy attached to a Pokemon can be used by bench
- [ ] **No energy cards**: Attacks cost action points instead

### Energy Types in Use

| Type | Symbol | Description |
|------|--------|-------------|
| [TBD] | | |
| [TBD] | | |
| Colorless | | Any energy satisfies colorless requirements |

### Special Energy

| Name | Effect |
|------|--------|
| [TBD] | |
| [TBD] | |

---

## Deck Building Rules

> **Home Rule Focus Area**: Card limits and restrictions

### Deck Size

| Rule | Value |
|------|-------|
| Minimum deck size | [TBD] cards |
| Maximum deck size | [TBD] cards |
| Exact size required? | [TBD] Yes/No |

### Card Limits

| Card Type | Max Copies | Notes |
|-----------|------------|-------|
| Pokemon (same name) | [TBD] | |
| Trainer cards (same name) | [TBD] | |
| Energy cards (basic, same type) | [TBD] | |
| Energy cards (special, same name) | [TBD] | |

### Required Cards

| Requirement | Value |
|-------------|-------|
| Minimum Basic Pokemon | [TBD] |
| Minimum Energy cards | [TBD] |
| Other requirements | [TBD] |

### Banned/Restricted Cards

| Card Name | Status | Reason |
|-----------|--------|--------|
| [TBD] | Banned | |
| [TBD] | Limited to 1 | |

### Format Rotations

[TBD] - Which card sets are legal? Do sets rotate out?

| Set Name | Set Code | Status |
|----------|----------|--------|
| [TBD] | | Legal |
| [TBD] | | Banned |

---

## Win Conditions

> **Home Rule Focus Area**: Victory conditions

### Standard Win Conditions (for reference)

1. Take all 6 prize cards
2. Knock out opponent's last Pokemon in play
3. Opponent cannot draw at start of turn

### Modified Win Conditions

[TBD] - Describe your win condition changes. Examples:

- [ ] **Prize count change**: Take [X] prizes instead of 6
- [ ] **Alternative victory**: Win by [condition]
- [ ] **Removed condition**: [Which standard condition is removed?]
- [ ] **Sudden death**: [Special rules for tiebreakers]

### Prize Card Rules

| Rule | Value |
|------|-------|
| Number of prizes | [TBD] |
| Prizes taken per knockout | [TBD] - (Standard: 1 for basic, 2 for EX/V) |
| Prize card selection | [TBD] - Random or chosen? |

---

## Turn Structure

### Turn Overview

```
1. DRAW PHASE
   - Draw 1 card from deck
   
2. MAIN PHASE (any order, as many times as allowed)
   - Attach energy (once per turn) [TBD if modified]
   - Play Basic Pokemon to bench
   - Evolve Pokemon
   - Play Trainer cards
   - Use Abilities
   - Retreat Active Pokemon (once per turn)
   
3. ATTACK PHASE
   - Declare attack (ends turn)
   - OR pass without attacking
   
4. END PHASE
   - Apply end-of-turn effects
   - Check for knockouts
   - Take prize cards if applicable
```

### Turn Modifications

[TBD] - Any changes to the turn structure?

| Modification | Description |
|--------------|-------------|
| [TBD] | |

### First Turn Rules

| Rule | Value |
|------|-------|
| First player draws on turn 1? | [TBD] Yes/No |
| First player can attack turn 1? | [TBD] Yes/No |
| First player can play Supporters turn 1? | [TBD] Yes/No |

---

## Card Types

### Pokemon Cards

| Term | Definition |
|------|------------|
| Basic Pokemon | Can be played directly from hand to bench |
| Stage 1 | Evolves from a Basic Pokemon |
| Stage 2 | Evolves from a Stage 1 Pokemon |
| [TBD] | [Any special Pokemon types like EX, V, etc.?] |

### Evolution Rules

| Rule | Value |
|------|-------|
| Can evolve same turn played? | No (unless card effect allows) |
| Can evolve same turn as previous evolution? | [TBD] |
| Evolution on first turn of game? | [TBD] |

### Trainer Cards

[TBD] - Which trainer card subtypes are in use?

| Type | Rules |
|------|-------|
| Item | [TBD] - Unlimited per turn? |
| Supporter | [TBD] - One per turn? |
| Stadium | [TBD] - Stays in play? |
| Tool | [TBD] - Attach to Pokemon? |

### Energy Cards

| Type | Description |
|------|-------------|
| Basic Energy | Provides 1 energy of its type |
| Special Energy | [TBD] - Custom effects? |

---

## Status Conditions

### Active Status Conditions

| Condition | Effect | Removal |
|-----------|--------|---------|
| Poisoned | [TBD] damage between turns | [TBD] |
| Burned | [TBD] damage + flip to continue | [TBD] |
| Asleep | Cannot attack or retreat, flip to wake | [TBD] |
| Paralyzed | Cannot attack or retreat for 1 turn | End of next turn |
| Confused | Flip to attack, damage self on tails | [TBD] |

### Condition Stacking

[TBD] - Can multiple conditions be active? Which override others?

---

## Glossary

| Term | Definition |
|------|------------|
| Active Pokemon | The Pokemon currently in the battle position |
| Bench | Area for up to 5 Pokemon not currently active |
| Discard Pile | Where knocked out Pokemon and used cards go |
| Prize Cards | Cards set aside at game start, taken on knockouts |
| Retreat | Switching active Pokemon with a benched Pokemon |
| [TBD] | [Add game-specific terms] |

---

## Changelog

Track rule changes over time:

| Date | Change | Reason |
|------|--------|--------|
| [Date] | Initial rules document created | Project start |
| | | |

---

## Notes for Implementation

This section is for developer reference when implementing rules in code.

### Rule Configuration Schema

Rules should be configurable via a JSON/YAML file for easy iteration:

```json
{
  "deck": {
    "min_size": 60,
    "max_size": 60,
    "max_copies_per_card": 4,
    "min_basic_pokemon": 1
  },
  "prizes": {
    "count": 6,
    "per_knockout_basic": 1,
    "per_knockout_ex": 2
  },
  "energy": {
    "attachments_per_turn": 1
  },
  "first_turn": {
    "can_draw": true,
    "can_attack": false,
    "can_play_supporter": false
  },
  "win_conditions": {
    "all_prizes_taken": true,
    "no_pokemon_in_play": true,
    "cannot_draw": true
  }
}
```

### Validation Hooks

When implementing rules engine, create validation hooks for:

- `validate_deck(deck) -> ValidationResult`
- `validate_action(game_state, action) -> ValidationResult`
- `check_win_conditions(game_state) -> Optional[WinResult]`
- `calculate_prizes_for_knockout(pokemon) -> int`