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 | Support for Stage 2, EX, V, GX | Campaign will have fixed ruleset, but engine is flexible |
| Trainer card types | Modern item/supporter/stadium split | |
| Energy types | Modern | 10 types: Colorless, Darkness, Dragon, Fighting, Fire, Grass, Lightning, Metal, Psychic, and Water |

### What's NOT Included

List of official mechanics that are explicitly excluded:

- No mechanics are explicitly unsupported because the game should be infinitely customizable

---

## 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

Default ruleset will be similar to Pokemon Pocket:

- **Energy deck**: Players build a deck of 20 energy cards to go with each deck; no energy cards are included in main deck
- **Energy generation**: At start of turn, flip top card of energy deck; may play it any time before attacking

### 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 | 40 cards |
| Maximum deck size | 40 cards |
| Exact size required? | Yes |
| Energy cards included? | No |
| Energy deck size | 20 cards |

### Card Limits

| Card Type | Max Copies | Notes |
|-----------|------------|-------|
| Pokemon (same name) | 40 | Configurable outside of defaults |
| Trainer cards (same name) | 4 | Configurable |

### Required Cards

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

### Banned/Restricted Cards

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

### Format Rotations

- No rotating format at launch, but should be configurable

| 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

All settings should be configurable, below are core game defaults

- **Prize count change**: Take 4 prizes instead of 6
- **Alternative win conditions**: 
  - field control, opponent runs out of pokemon on the board
  - deck depletion, players who cannot draw a card from their deck lose
  - multiplayer only: turn timer, after 90 seconds player forfeits; winning player may choose to allow extra time
- **Tiebreaker**: Player with most points after completion of game timer wins; draw if players are tied on points

### Prize Cards

> In core gameplay, prize cards are removed in favor of scoring points. Any time a prize card would be taken in standard rules, player instead scores a point

| Rule | Value |
|------|-------|
| Number of prizes/points | 4 |
| Prizes taken per knockout | Standard: 1 for basic, 2 for EX/V |
| Prize card selection | Configurable, not used in core rules |

---

## 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)
   - 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/score points if applicable
   - Flip top card of energy deck
```

### Turn Modifications

| Modification | Description |
|--------------|-------------|
| New step to flip top card of energy deck | |

### First Turn Rules

| Rule | Value |
|------|-------|
| First player draws on turn 1? | Yes |
| First player can attack turn 1? | Yes |
| First player can play Supporters turn 1? | Yes |
| First player can attach energy turn 1? | 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 |
| EX | Worth 2 knockout points, could be basic, stage 1, or stage 2 |
| V | Can be played directly from hand to bench |
| V-Max | Evolves from a V pokemon |

### Evolution Rules

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

### Trainer Cards

All trainer card subtypes are in use

| Type | Rules |
|------|-------|
| Item | Unlimited per turn |
| Supporter | One per turn |
| Stadium | Stays in play, can play one per turn |
| Tool | Attach to Pokemon, unlimited per turn |

### Energy Cards

| Type | Description |
|------|-------------|
| Basic Energy | Provides 1 energy of its type |
| Special Energy | Custom effects, no limits to enrgy deck by default |

---

## Status Conditions

### Active Status Conditions

Conditions stack unless otherwise boted

| Condition | Effect | Removal |
|-----------|--------|---------|
| Poisoned | 10 damage between turns | Specific card effect, evolution, retreat |
| Burned | 20 damage + flip to continue | Removed on heads flip |
| Asleep | Cannot attack or retreat; overrides paralysis and confusion | Removed on heads flip |
| Paralyzed | Cannot attack or retreat for 1 turn; overrides sleep and confusion | End of next turn |
| Confused | Flip to attack, 30 damage self on tails; overrides sleep and paralysis | Evolution, retreat |

---

## 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`