# Veilborn Chronicles Card Creation Guide

> _"Every card is a story waiting to be told, an echo of power waiting to
> resonate."_ -- Archivist of the Deck of Echoes

This guide explains how to create custom cards for Veilborn Chronicles.

---

## Understanding the Card System

### The Deck of Echoes

Veilborn uses a unique dual-purpose card system called the **Deck of Echoes**:

- **Face-Up Play**: Active abilities with immediate effects
- **Face-Down Play**: Reactive traps and defensive responses

Every card has both an active and reactive mode, making deck-building
strategically rich.

### Card Types

| Type      | Purpose               | Color  | Primary Use                 |
| --------- | --------------------- | ------ | --------------------------- |
| **Echo**  | Character abilities   | Blue   | Active powers and attacks   |
| **Realm** | Environmental effects | Green  | Battlefield modifications   |
| **Fate**  | Random events         | Purple | Chaos and luck manipulation |
| **Bond**  | Connections           | Gold   | Party synergies and links   |

### Rarity Levels

| Rarity    | Symbol  | Deck Limits  | Power Level |
| --------- | ------- | ------------ | ----------- |
| Common    | Circle  | No limit     | Low         |
| Uncommon  | Diamond | No limit     | Medium      |
| Rare      | Star    | Max 3 copies | High        |
| Mythic    | Crown   | Max 3 total  | Very High   |
| Legendary | Dragon  | Max 1 total  | Extreme     |

---

## Card Definition Structure

### Basic Template

```typescript
const myCard: CardDefinition = {
  id: 'unique-card-id',
  cardId: 'CARD-001',
  name: 'Card Name',
  description: 'What the card does.',
  cardType: 'echo',
  rarity: 'common',
  cost: {
    resonance: 2,
  },
  effects: [
    // Face-up effects
  ],
  faceDownEffects: [
    // Face-down effects (optional)
  ],
  keywords: ['keyword1', 'keyword2'],
  flavorText: 'Atmospheric text that adds lore.',
  isActive: true,
};
```

### Complete Card Example

```typescript
const probabilityShift: EchoCard = {
  id: 'echo-weaver-probability-shift',
  cardId: 'ECH-WEA-001',
  name: 'Probability Shift',
  description: 'Manipulate the threads of chance to alter an outcome.',
  cardType: 'echo',
  rarity: 'uncommon',
  setId: 'core-set',

  // Cost to play
  cost: {
    resonance: 2,
    veilPoints: 0,
  },

  // Face-up (active) effects
  effects: [
    {
      id: 'prob-shift-main',
      type: 'stat_modify',
      trigger: 'on_play',
      target: 'ally',
      stat: 'next_roll',
      modifier: 'add',
      value: 3,
      description: 'Target ally gains +3 to their next roll.',
    },
  ],

  // Face-down (reactive) effects
  faceDownEffects: [
    {
      id: 'prob-shift-react',
      type: 'redirect',
      trigger: 'on_reveal',
      target: 'enemy',
      description: 'Force an enemy to reroll their last result.',
      conditions: [
        {
          type: 'stat_check',
          stat: 'last_enemy_roll',
          operator: '>=',
          value: 15,
          source: 'global',
        },
      ],
    },
  ],

  // Deck requirements
  requirements: {
    requiredPath: 'weaver',
  },

  keywords: ['probability', 'manipulation', 'reroll'],
  flavorText: 'The Weave does not care what "should" happen.',
  artUrl: '/cards/echo/probability-shift.png',
  isActive: true,

  // Echo-specific fields
  echoStrength: 2,
  echoElement: 'flow',
  resonanceAffinity: 'flow',
};
```

---

## Card Types Deep Dive

### Echo Cards

Echo cards represent character abilities - direct actions that affect the game
state.

```typescript
interface EchoCard extends CardDefinition {
  cardType: 'echo';
  echoStrength: number; // 1-5, power level
  echoElement?: string; // Element affinity
  resonanceAffinity?: string; // Resonance type bonus
}
```

**Design Guidelines:**

- `echoStrength` should match the cost and impact
- Strength 1: Minor utility (cost 1)
- Strength 3: Solid ability (cost 2-3)
- Strength 5: Powerful effect (cost 4+)

**Example - Attack Echo:**

```typescript
const voidStrike: EchoCard = {
  id: 'echo-shadow-void-strike',
  cardId: 'ECH-SHA-015',
  name: 'Void Strike',
  description: 'Strike from the emptiness between spaces.',
  cardType: 'echo',
  rarity: 'rare',
  cost: { resonance: 3 },
  effects: [
    {
      id: 'void-strike-damage',
      type: 'damage',
      trigger: 'on_play',
      target: 'enemy',
      value: 4,
      description: 'Deal 4 damage to target enemy.',
    },
    {
      id: 'void-strike-bypass',
      type: 'condition_apply',
      trigger: 'on_play',
      target: 'enemy',
      description: 'This damage ignores 2 points of defense.',
      conditions: [],
    },
  ],
  keywords: ['attack', 'void', 'piercing'],
  echoStrength: 4,
  echoElement: 'void',
  resonanceAffinity: 'void',
  isActive: true,
};
```

### Realm Cards

Realm cards create environmental effects that persist on the battlefield.

```typescript
interface RealmCard extends CardDefinition {
  cardType: 'realm';
  realmDuration: number; // Turns the realm lasts
  realmRadius?: number; // Area of effect in hexes
  environmentalEffects: CardEffect[];
}
```

**Design Guidelines:**

- Duration should balance power
- Short duration (1-2 turns): Strong effects
- Long duration (4+ turns): Moderate effects
- Global realms: Weak but universal effects

**Example - Area Realm:**

```typescript
const veilThinning: RealmCard = {
  id: 'realm-void-veil-thinning',
  cardId: 'RLM-VOI-003',
  name: 'Veil Thinning',
  description: 'Create a zone where the Veil grows weak.',
  cardType: 'realm',
  rarity: 'rare',
  cost: { resonance: 3, veilPoints: 1 },
  effects: [
    {
      id: 'veil-thin-place',
      type: 'summon',
      trigger: 'on_play',
      target: 'self',
      description: 'Create Veil Thinning zone at target location.',
    },
  ],
  environmentalEffects: [
    {
      id: 'veil-thin-buff',
      type: 'buff',
      trigger: 'continuous',
      target: 'all_characters',
      stat: 'void_abilities',
      modifier: 'add',
      value: 2,
      description: 'All characters in zone gain +2 to Void abilities.',
    },
    {
      id: 'veil-thin-danger',
      type: 'damage',
      trigger: 'on_turn_end',
      target: 'all_characters',
      value: 1,
      description: 'Characters in zone take 1 Void damage at end of turn.',
    },
  ],
  keywords: ['zone', 'void', 'environmental'],
  realmDuration: 3,
  realmRadius: 2,
  isActive: true,
};
```

### Fate Cards

Fate cards introduce controlled randomness and fortune manipulation.

```typescript
interface FateCard extends CardDefinition {
  cardType: 'fate';
  fortuneValue: number; // Positive outcome strength
  misfortuneValue: number; // Negative outcome strength
  chaosWeight: number; // Randomness factor (0-100)
}
```

**Design Guidelines:**

- `chaosWeight` determines predictability
- Low chaos (0-30): Mostly reliable
- High chaos (70-100): Wild variance
- Balance fortune/misfortune for fairness

**Example - Fortune Card:**

```typescript
const wheelOfFate: FateCard = {
  id: 'fate-oracle-wheel',
  cardId: 'FTE-ORA-007',
  name: 'Wheel of Fate',
  description: 'Spin the wheel and accept what comes.',
  cardType: 'fate',
  rarity: 'mythic',
  cost: { resonance: 2 },
  effects: [
    {
      id: 'wheel-spin',
      type: 'buff',
      trigger: 'on_play',
      target: 'self',
      description: 'Roll 1d6: 1-2 = misfortune, 3-4 = nothing, 5-6 = fortune.',
      conditions: [
        { type: 'random', operator: '>=', value: 5, source: 'global' },
      ],
    },
  ],
  keywords: ['fortune', 'random', 'oracle'],
  fortuneValue: 5,
  misfortuneValue: 3,
  chaosWeight: 66,
  isActive: true,
};
```

### Bond Cards

Bond cards create connections between characters and enhance teamwork.

```typescript
interface BondCard extends CardDefinition {
  cardType: 'bond';
  bondStrength: number; // 1-5, connection power
  bondTargets: number; // How many can be bonded
  bondType: 'ally' | 'weave' | 'realm' | 'universal';
}
```

**Design Guidelines:**

- Party synergy is the primary goal
- Single-target bonds: Stronger effects
- Multi-target bonds: Weaker per-target
- Universal bonds: Weakest but most flexible

**Example - Party Bond:**

```typescript
const sharedFate: BondCard = {
  id: 'bond-weaver-shared-fate',
  cardId: 'BND-WEA-002',
  name: 'Shared Fate',
  description: 'Link the destinies of allies together.',
  cardType: 'bond',
  rarity: 'rare',
  cost: { resonance: 3 },
  effects: [
    {
      id: 'shared-fate-link',
      type: 'weave_connect',
      trigger: 'on_play',
      target: 'all_allies',
      connectionType: 'fate_link',
      connectionStrength: 3,
      description: 'Create fate links between all allies.',
    },
    {
      id: 'shared-fate-benefit',
      type: 'heal',
      trigger: 'on_damage_taken',
      target: 'all_allies',
      value: 1,
      description: 'When a bonded ally takes damage, all others heal 1.',
      conditions: [],
    },
  ],
  keywords: ['bond', 'fate', 'party'],
  bondStrength: 3,
  bondTargets: 4,
  bondType: 'ally',
  isActive: true,
};
```

---

## Card Effects System

### Trigger Types

| Trigger           | When It Fires           |
| ----------------- | ----------------------- |
| `on_play`         | Card played face-up     |
| `on_reveal`       | Face-down card revealed |
| `on_discard`      | Card discarded          |
| `on_draw`         | Card drawn              |
| `on_turn_start`   | Owner's turn begins     |
| `on_turn_end`     | Owner's turn ends       |
| `on_attack`       | Owner attacks           |
| `on_defend`       | Owner defends           |
| `on_damage_taken` | Owner takes damage      |
| `on_damage_dealt` | Owner deals damage      |
| `continuous`      | Always active in play   |
| `activated`       | Manually triggered      |

### Effect Types

```typescript
type EffectType =
  // Damage/Healing
  | 'damage' // Deal damage
  | 'heal' // Restore health

  // Buffs/Debuffs
  | 'buff' // Positive modifier
  | 'debuff' // Negative modifier
  | 'stat_modify' // Change a stat
  | 'condition_apply' // Apply status effect
  | 'condition_remove' // Remove status effect

  // Card Manipulation
  | 'draw' // Draw cards
  | 'discard' // Force discard
  | 'exile' // Remove from game
  | 'return_to_hand' // Return card to hand
  | 'summon' // Create token/effect
  | 'transform' // Change card type
  | 'copy' // Duplicate effect
  | 'steal' // Take control
  | 'counter' // Cancel effect
  | 'redirect' // Change target

  // Resources
  | 'resonance_gain' // Gain resonance
  | 'resonance_drain' // Remove resonance
  | 'veil_points_gain' // Gain VP
  | 'veil_points_drain' // Remove VP

  // Weave
  | 'weave_connect' // Create connection
  | 'weave_strengthen' // Boost connection
  | 'weave_sever'; // Break connection
```

### Target Types

| Target            | Description     |
| ----------------- | --------------- |
| `self`            | The card owner  |
| `ally`            | Single ally     |
| `enemy`           | Single enemy    |
| `all_allies`      | All allies      |
| `all_enemies`     | All enemies     |
| `all_characters`  | Everyone        |
| `random_ally`     | Random ally     |
| `random_enemy`    | Random enemy    |
| `card_in_hand`    | Card in hand    |
| `card_in_play`    | Card in play    |
| `card_in_discard` | Card in discard |

### Conditions

Effects can have conditions that must be met:

```typescript
interface EffectCondition {
  type:
    | 'stat_check'
    | 'card_count'
    | 'resonance_check'
    | 'health_check'
    | 'weave_check'
    | 'random';
  operator: '>' | '<' | '>=' | '<=' | '==' | '!=';
  value: number | string;
  stat?: string;
  source?: 'self' | 'target' | 'global';
}
```

**Example Conditions:**

```typescript
// Only if target has low health
{ type: 'health_check', operator: '<=', value: 5, source: 'target' }

// Only if you have 3+ cards in hand
{ type: 'card_count', operator: '>=', value: 3, source: 'self' }

// 50% chance
{ type: 'random', operator: '>=', value: 50, source: 'global' }
```

---

## Cost and Balance

### Cost Guidelines

| Resource     | Typical Value | Effect Level              |
| ------------ | ------------- | ------------------------- |
| Resonance 1  | Minor         | Draw 1, +1 to roll        |
| Resonance 2  | Standard      | Deal 2 damage, heal 2     |
| Resonance 3  | Strong        | Deal 4 damage, AoE effect |
| Resonance 4+ | Powerful      | Major impact              |
| Veil Points  | Premium       | Path-specific or powerful |
| Discard      | Alternative   | Flexible but costly       |

### Balance Checklist

Before finalizing a card, verify:

- [ ] Cost matches power level
- [ ] Face-down mode is situationally useful but not better than face-up
- [ ] Keywords are accurate
- [ ] Description clearly explains all effects
- [ ] Conditions are achievable but not trivial
- [ ] Doesn't create infinite loops or soft-locks
- [ ] Synergizes with Path without being required

---

## Deck Requirements

### Path-Specific Cards

```typescript
requirements: {
  requiredPath: 'seer',      // Only Seers can use
  minLevel: 3,               // Requires level 3+
  requiredAwakening: 'truth_sight' // Specific awakening
}
```

### Deck Building Rules

Standard deck rules:

- Minimum 40 cards
- Maximum 60 cards
- Max 3 copies of any card
- Max 1 Legendary
- Max 3 Mythic total

---

## Keywords Reference

Common keywords and their meanings:

| Keyword      | Meaning                         |
| ------------ | ------------------------------- |
| `quick`      | Can be played as reaction       |
| `ritual`     | Requires setup time             |
| `persistent` | Stays in play                   |
| `fleeting`   | Discards after use              |
| `piercing`   | Ignores some defense            |
| `splash`     | Affects adjacent targets        |
| `channeled`  | Requires concentration          |
| `exhausting` | Can only use once per encounter |

---

## Testing Your Cards

### Validation

Use the deck validation system:

```typescript
import { validateDeck, validateCard } from '@veilborn/core';

// Validate single card
const cardValidation = validateCard(myCard);
if (!cardValidation.valid) {
  console.error('Card issues:', cardValidation.errors);
}

// Validate deck with card
const deckValidation = validateDeck(myDeck);
console.log('Card distribution:', deckValidation.typeDistribution);
console.log('Average cost:', deckValidation.averageCost);
```

### Playtesting Recommendations

1. Test face-up and face-down modes separately
2. Check interaction with Path abilities
3. Verify conditions trigger appropriately
4. Balance against similar-cost cards
5. Test in different party compositions

---

## Card Art Guidelines

### Image Specifications

- Resolution: 750x1050 pixels (standard card ratio)
- Format: PNG with transparency
- File naming: `{type}-{path}-{name}.png`

### Art Style

- Consistent with Veilborn aesthetic
- Clear focal point
- Visible at card size
- Color palette matching card type

---

_For creature creation, see
[Creature Creation Guide](02-creature-creation-guide.md)_ _For realm building,
see [Realm Building Guide](03-realm-building-guide.md)_
