# Veilborn Chronicles Creature Creation Guide

> _"Every realm births its own children. Some are beautiful, some are terrible,
> and some are both."_ -- The Naturalist's Guide to Beyond

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

---

## Understanding the Creature System

### Design Philosophy

Creatures in Veilborn are more than stat blocks - they're expressions of the
world's fundamental Resonances. Every creature embodies one or more Resonances
that define not just their abilities, but their behavior, habitat, and role in
the ecosystem of the Veiled Realms.

### Core Classifications

#### Creature Types

| Type           | Description                              | Typical Habitats               |
| -------------- | ---------------------------------------- | ------------------------------ |
| **Beast**      | Natural animals, enhanced by Veil energy | Wilderness, forests, plains    |
| **Humanoid**   | Intelligent bipedal creatures            | Settlements, dungeons          |
| **Undead**     | Beings animated by death energy          | Necropolises, battlefields     |
| **Demon**      | Entities from corrupted realms           | Veil tears, dark places        |
| **Elemental**  | Pure manifestations of elements          | Elemental regions              |
| **Construct**  | Artificial beings, golems                | Ancient ruins, workshops       |
| **Aberration** | Beings from beyond normal reality        | Deep Void, thin places         |
| **Celestial**  | Beings of divine/pure energy             | Sacred sites, Outer Circle     |
| **Dragon**     | Ancient scaled creatures                 | Mountain lairs, hoards         |
| **Fey**        | Creatures of the Dreaming                | The Dreaming, enchanted groves |

#### Creature Sizes

| Size         | Hex Occupation     | Health Modifier | Speed Modifier |
| ------------ | ------------------ | --------------- | -------------- |
| `tiny`       | 0 (shares hex)     | x0.25           | +2             |
| `small`      | 1                  | x0.5            | +1             |
| `medium`     | 1                  | x1.0            | +0             |
| `large`      | 2 (adjacent)       | x1.5            | -1             |
| `huge`       | 7 (hex cluster)    | x2.0            | -2             |
| `gargantuan` | 19 (large cluster) | x3.0            | -3             |

#### Behaviors

| Behavior      | Combat Style            | AI Priority            |
| ------------- | ----------------------- | ---------------------- |
| `aggressive`  | Attacks on sight        | Closest target         |
| `defensive`   | Attacks when threatened | Protect territory      |
| `territorial` | Warns, then attacks     | Drive away intruders   |
| `predator`    | Stalks and ambushes     | Weakest target         |
| `passive`     | Flees unless cornered   | Escape                 |
| `pack`        | Coordinates with allies | Surround and overwhelm |

---

## Creature Definition Structure

### Basic Template

```typescript
import {
  Creature,
  CreatureType,
  CreatureSize,
  CreatureBehavior,
} from '@veilborn/core';

const myCreature: Creature = {
  id: 'unique-creature-id',
  name: 'Creature Name',
  description: 'What this creature is and does.',
  type: 'beast',
  size: 'medium',
  behavior: 'predator',
  challengeRating: 5,
  stats: {
    health: 50,
    attack: 10,
    defense: 15,
    speed: 4,
  },
  abilities: [],
  loot: [],
  habitat: ['forest', 'mountains'],
  lore: 'Optional background information.',
};
```

### Complete Creature Example

```typescript
const veilStalker: Creature = {
  id: 'creature-veil-stalker-001',
  name: 'Veil Stalker',
  description:
    'A six-legged predator that phases between realities while hunting.',
  type: 'aberration',
  size: 'large',
  behavior: 'predator',
  challengeRating: 7,

  stats: {
    health: 75,
    attack: 12,
    defense: 14,
    speed: 5,
  },

  abilities: [
    {
      name: 'Phase Strike',
      description: 'Teleport up to 3 hexes and attack in one action.',
      damage: 4,
      cooldown: 2,
      range: '3 hexes',
    },
    {
      name: 'Veil Camouflage',
      description: 'Become invisible until attacking or taking damage.',
      cooldown: 4,
    },
    {
      name: 'Reality Tear',
      description:
        'Create a difficult terrain zone that damages creatures entering it.',
      damage: 2,
      cooldown: 5,
      range: '2 hex radius',
    },
  ],

  loot: [
    'Veil Stalker Hide (rare crafting material)',
    'Phase Gland (uncommon component)',
    '2d10 gold pieces',
  ],

  habitat: ['boundary_zones', 'thin_places', 'void_touched'],

  lore: `Veil Stalkers are apex predators of the Boundary Zones. They evolved
to hunt prey that tried to escape between realms, developing the ability to
perceive and move through multiple reality layers simultaneously. Their
six legs allow them to maintain purchase on shifting ground, and their
faceted eyes see into adjacent dimensions.`,
};
```

---

## Challenge Rating System

### Understanding Challenge Rating (CR)

Challenge Rating represents how difficult a creature is to defeat. Use these
guidelines:

| CR    | Party Level | Role               | Approximate Health |
| ----- | ----------- | ------------------ | ------------------ |
| 1-2   | 1-2         | Trivial encounter  | 3-20               |
| 3-4   | 2-4         | Easy encounter     | 20-40              |
| 5-7   | 4-6         | Moderate encounter | 40-80              |
| 8-10  | 6-8         | Hard encounter     | 80-120             |
| 11-15 | 8-12        | Deadly/Boss        | 120-200            |
| 16-20 | 12+         | Legendary          | 200+               |

### Stat Calculation Formula

```typescript
function calculateCreatureStats(
  cr: number,
  size: CreatureSize
): { health: number; attack: number; defense: number; speed: number } {
  const sizeMultipliers: Record<CreatureSize, number> = {
    tiny: 0.25,
    small: 0.5,
    medium: 1,
    large: 1.5,
    huge: 2,
    gargantuan: 3,
  };

  const mult = sizeMultipliers[size];

  return {
    health: Math.floor((10 + cr * 8) * mult),
    attack: Math.floor(2 + cr * 1.5),
    defense: Math.floor((10 + cr * 0.8) * mult),
    speed: Math.max(1, Math.floor(5 - (mult - 1))),
  };
}
```

### Stat Guidelines by CR

| CR Range | Health  | Attack | Defense | Abilities |
| -------- | ------- | ------ | ------- | --------- |
| 1-2      | 3-15    | 3-5    | 2-10    | 0-1       |
| 3-4      | 15-40   | 6-8    | 10-13   | 1         |
| 5-7      | 40-70   | 9-12   | 13-16   | 1-2       |
| 8-10     | 70-100  | 13-17  | 16-18   | 2-3       |
| 11-15    | 100-150 | 18-24  | 18-22   | 3-4       |
| 16-20    | 150+    | 25+    | 22+     | 4+        |

---

## Resonance Classification

### Primary Resonance

Every creature should have 1-2 dominant Resonances that define its nature:

| Resonance    | Creature Traits                | Example Types                     |
| ------------ | ------------------------------ | --------------------------------- |
| **Clarity**  | Perception, memory, knowledge  | Memory Sprites, Echo Knights      |
| **Flow**     | Change, movement, adaptation   | Drift Jellyfish, Weave Spiders    |
| **Presence** | Emotion, willpower, charisma   | Emotion Elementals, Whisper Moths |
| **Root**     | Matter, stability, endurance   | Gravity Worms, Coral Lords        |
| **Void**     | Emptiness, boundaries, entropy | Shade Wisps, Void Tendrils        |

### Resonance Stat Block

For Veilborn's dice system, define Resonance values:

```typescript
interface CreatureResonance {
  clarity: number; // 1-10
  flow: number; // 1-10
  presence: number; // 1-10
  root: number; // 1-10
  void: number; // 1-10
}

// Example: Flow-dominant creature
const driftJellyfishResonance: CreatureResonance = {
  clarity: 2,
  flow: 4, // Dominant
  presence: 2,
  root: 2,
  void: 2,
};

// Example: Dual-resonance creature
const veilStalkerResonance: CreatureResonance = {
  clarity: 3,
  flow: 4, // Primary
  presence: 3,
  root: 2,
  void: 5, // Secondary
};
```

### Resonance Guidelines by CR

| CR   | Weak Resonances | Strong Resonances | Total Points |
| ---- | --------------- | ----------------- | ------------ |
| 1-2  | 2               | 3-4               | 10-12        |
| 3-4  | 2-3             | 4-5               | 12-16        |
| 5-7  | 3               | 5-6               | 16-20        |
| 8-10 | 3-4             | 5-6               | 20-25        |
| 11+  | 4-5             | 6+                | 25+          |

---

## Creature Abilities

### Ability Structure

```typescript
interface CreatureAbility {
  name: string; // Display name
  description: string; // What it does
  damage?: number; // Damage dealt (if applicable)
  cooldown?: number; // Turns before can use again
  range?: string; // Range description
}
```

### Ability Categories

#### Offensive Abilities

```typescript
// Basic attack enhancement
const clawRend: CreatureAbility = {
  name: 'Rend',
  description: 'Attack that causes bleeding (2 damage per turn for 3 turns).',
  damage: 3,
  range: 'melee',
};

// Ranged attack
const acidSpit: CreatureAbility = {
  name: 'Acid Spit',
  description: 'Ranged attack that reduces target defense by 2.',
  damage: 4,
  cooldown: 2,
  range: '4 hexes',
};

// Area attack
const thunderStomp: CreatureAbility = {
  name: 'Thunder Stomp',
  description:
    'All creatures within 2 hexes take damage and are knocked prone.',
  damage: 3,
  cooldown: 3,
  range: '2 hex radius',
};
```

#### Defensive Abilities

```typescript
// Damage reduction
const stoneShell: CreatureAbility = {
  name: 'Stone Shell',
  description: 'Gain +4 defense but cannot move for 2 turns.',
  cooldown: 4,
};

// Evasion
const mistForm: CreatureAbility = {
  name: 'Mist Form',
  description: 'Become incorporeal. Take half damage from physical attacks.',
  cooldown: 3,
};

// Regeneration
const trollRegeneration: CreatureAbility = {
  name: 'Regeneration',
  description: 'Heal 3 health at start of turn. Disabled by fire damage.',
  cooldown: 0, // Passive
};
```

#### Utility Abilities

```typescript
// Movement
const phaseStep: CreatureAbility = {
  name: 'Phase Step',
  description: 'Teleport up to 3 hexes. Does not provoke reactions.',
  cooldown: 2,
  range: '3 hexes',
};

// Summoning
const callPack: CreatureAbility = {
  name: 'Call Pack',
  description: 'Summon 1d4 wolf allies (CR 1 each).',
  cooldown: 5,
};

// Terrain manipulation
const earthRise: CreatureAbility = {
  name: 'Earth Rise',
  description: 'Create blocking terrain in up to 3 adjacent hexes.',
  cooldown: 4,
  range: '3 hexes',
};
```

### Ability Count by CR

| CR    | Basic Abilities | Advanced Abilities | Total |
| ----- | --------------- | ------------------ | ----- |
| 1-2   | 0-1             | 0                  | 0-1   |
| 3-4   | 1               | 0                  | 1     |
| 5-7   | 1-2             | 0-1                | 1-2   |
| 8-10  | 2               | 1                  | 2-3   |
| 11-15 | 2-3             | 1-2                | 3-4   |
| 16+   | 3+              | 2+                 | 4+    |

---

## Type-Specific Guidelines

### Beasts

Natural creatures enhanced by Veil energy.

```typescript
const direFrostWolf: Creature = {
  id: 'creature-dire-frost-wolf',
  name: 'Dire Frost Wolf',
  description: 'A massive wolf with frost-rimed fur and icy breath.',
  type: 'beast',
  size: 'large',
  behavior: 'pack',
  challengeRating: 4,
  stats: { health: 45, attack: 8, defense: 12, speed: 6 },
  abilities: [
    {
      name: 'Frost Breath',
      description:
        'Cone attack that slows targets (half movement) for 2 turns.',
      damage: 3,
      cooldown: 3,
      range: '3 hex cone',
    },
    {
      name: 'Pack Tactics',
      description: 'Gain +2 attack when adjacent to an ally.',
    },
  ],
  loot: ['Frost Wolf Pelt', 'Dire Wolf Fangs', '1d10 gold'],
  habitat: ['tundra', 'mountains'],
};
```

### Undead

Beings animated by death energy or trapped souls.

```typescript
const ancientWraith: Creature = {
  id: 'creature-ancient-wraith',
  name: 'Ancient Wraith',
  description:
    'The vengeful spirit of a betrayed noble, bound to its ancestral home.',
  type: 'undead',
  size: 'medium',
  behavior: 'territorial',
  challengeRating: 8,
  stats: { health: 65, attack: 14, defense: 12, speed: 5 },
  abilities: [
    {
      name: 'Life Drain',
      description: 'Melee attack that heals the wraith for damage dealt.',
      damage: 5,
      range: 'melee',
    },
    {
      name: 'Incorporeal',
      description: 'Take half damage from non-magical physical attacks.',
    },
    {
      name: 'Terrifying Presence',
      description:
        'All enemies within 3 hexes must pass Presence check or be frightened.',
      cooldown: 4,
      range: '3 hex radius',
    },
  ],
  loot: ['Wraith Essence', 'Cursed Noble Ring', '3d20 gold'],
  habitat: ['ruins', 'crypts', 'battlefields'],
  lore: 'Ancient Wraiths form when powerful individuals die with overwhelming regret or rage.',
};
```

### Aberrations

Beings from beyond normal reality.

```typescript
const mindRipper: Creature = {
  id: 'creature-mind-ripper',
  name: 'Mind Ripper',
  description: 'A floating mass of tentacles surrounding a single massive eye.',
  type: 'aberration',
  size: 'medium',
  behavior: 'predator',
  challengeRating: 10,
  stats: { health: 85, attack: 16, defense: 14, speed: 4 },
  abilities: [
    {
      name: 'Psychic Blast',
      description: 'Ranged attack targeting Clarity. Ignores physical defense.',
      damage: 6,
      cooldown: 2,
      range: '5 hexes',
    },
    {
      name: 'Mind Control',
      description:
        'Target must pass Presence check or act under creature control for 1 turn.',
      cooldown: 5,
      range: '3 hexes',
    },
    {
      name: 'Alien Mind',
      description: 'Immune to charm, fear, and mind-reading effects.',
    },
    {
      name: 'Tentacle Grapple',
      description:
        'Grab and immobilize a target. Grappled targets take 2 damage per turn.',
      damage: 3,
      range: '2 hexes',
    },
  ],
  loot: ['Aberrant Cortex', 'Mind Crystal', 'Void-touched Gold (5d20)'],
  habitat: ['deep_void', 'thin_places', 'aberrant_zones'],
  lore: 'Mind Rippers are scouts from realms that obey no natural laws.',
};
```

---

## Combat Integration

### Combatant Creation

Creatures become combatants when entering combat:

```typescript
import { createCombatant, Combatant, HexCoord } from '@veilborn/core';

function creatureToCombatant(
  creature: Creature,
  position: HexCoord,
  team: 'enemy' | 'neutral' = 'enemy'
): Combatant {
  return createCombatant(
    `combatant-${creature.id}-${Date.now()}`,
    creature.id,
    creature.name,
    team,
    position,
    {
      maxHealth: creature.stats.health,
      maxVeil: Math.floor(creature.stats.health / 4),
      movement: creature.stats.speed,
      attack: creature.stats.attack,
      defense: creature.stats.defense,
      initiative: Math.floor(creature.stats.speed * 2),
    }
  );
}
```

### AI Behavior Implementation

```typescript
interface CreatureAI {
  creature: Creature;
  selectTarget(combatants: Combatant[]): Combatant | null;
  selectAction(state: CombatState): CombatAction;
  selectMovement(state: CombatState): HexCoord | null;
}

// Behavior-based target selection
function selectTargetByBehavior(
  behavior: CreatureBehavior,
  self: Combatant,
  enemies: Combatant[]
): Combatant | null {
  switch (behavior) {
    case 'aggressive':
      // Closest enemy
      return enemies.reduce(
        (closest, enemy) => {
          const dist = hexDistance(self.position, enemy.position);
          const closestDist = closest
            ? hexDistance(self.position, closest.position)
            : Infinity;
          return dist < closestDist ? enemy : closest;
        },
        null as Combatant | null
      );

    case 'predator':
      // Lowest health enemy
      return enemies.reduce(
        (weakest, enemy) => {
          return !weakest || enemy.currentHealth < weakest.currentHealth
            ? enemy
            : weakest;
        },
        null as Combatant | null
      );

    case 'pack':
      // Enemy with most allies adjacent (surround)
      return enemies.reduce(
        (target, enemy) => {
          const adjacentAllies = enemies.filter(
            (e) => hexDistance(e.position, enemy.position) === 1
          ).length;
          const currentBest = target
            ? enemies.filter(
                (e) => hexDistance(e.position, target.position) === 1
              ).length
            : -1;
          return adjacentAllies > currentBest ? enemy : target;
        },
        null as Combatant | null
      );

    case 'passive':
      return null; // Don't attack

    default:
      return enemies[0] || null;
  }
}
```

---

## Loot System

### Loot Generation

```typescript
interface LootTable {
  creature: CreatureType;
  challengeRating: number;
  guaranteed: string[]; // Always drops
  common: LootEntry[]; // 50%+ chance
  uncommon: LootEntry[]; // 15-49% chance
  rare: LootEntry[]; // 1-14% chance
}

interface LootEntry {
  item: string;
  chance: number; // 0-100
  quantity?: string; // e.g., "1d4", "2d10"
}

// Example loot table
const veilStalkerLoot: LootTable = {
  creature: 'aberration',
  challengeRating: 7,
  guaranteed: ['Veil Stalker Carapace Fragment'],
  common: [
    { item: 'Phase Gland', chance: 60 },
    { item: 'Gold Pieces', chance: 80, quantity: '3d10' },
  ],
  uncommon: [
    { item: 'Veil Stalker Eye', chance: 30 },
    { item: 'Dimensional Resonance Shard', chance: 25 },
  ],
  rare: [
    { item: 'Phase Stalker Heart', chance: 10 },
    { item: 'Veil-Touched Weapon', chance: 5 },
  ],
};
```

### Loot Guidelines by Type

| Type       | Common Loot          | Rare Loot        |
| ---------- | -------------------- | ---------------- |
| Beast      | Hide, fangs, meat    | Magical organs   |
| Humanoid   | Weapons, armor, gold | Magic items      |
| Undead     | Essence, bone        | Soul fragments   |
| Demon      | Ichor, horns         | Demon cores      |
| Elemental  | Element shards       | Pure essence     |
| Construct  | Metal, gears         | Control cores    |
| Aberration | Strange organs       | Reality shards   |
| Celestial  | Feathers, light      | Divine fragments |
| Dragon     | Scales, bones        | Dragon heart     |
| Fey        | Dust, flowers        | Fey contracts    |

---

## Boss Creature Design

### Boss Template

Bosses should have:

- 2-3x standard health for CR
- Multiple phases or forms
- Legendary actions (extra actions per round)
- Lair actions (environmental effects)

```typescript
const voidTerror: Creature = {
  id: 'boss-void-terror',
  name: 'The Void Terror',
  description: 'An ancient aberration that has devoured entire realms.',
  type: 'aberration',
  size: 'huge',
  behavior: 'aggressive',
  challengeRating: 15,
  stats: {
    health: 250, // Boss health
    attack: 22,
    defense: 18,
    speed: 4,
  },
  abilities: [
    // Phase 1 abilities
    {
      name: 'Void Maw',
      description:
        'Massive bite attack. Swallowed targets take 10 damage per turn.',
      damage: 12,
      range: '2 hexes',
    },
    {
      name: 'Reality Fracture',
      description:
        'All creatures in area take damage and are teleported randomly.',
      damage: 8,
      cooldown: 3,
      range: '4 hex radius',
    },
    // Phase 2 (below 50% health)
    {
      name: 'Summon Void Spawn',
      description:
        'Summon 2d4 Void Spawn (CR 3). Can only use below 50% health.',
      cooldown: 5,
    },
    // Legendary actions
    {
      name: 'Legendary Action: Tendril Sweep',
      description:
        "At end of any creature's turn, sweep tendrils in 2 hex line.",
      damage: 6,
    },
  ],
  loot: [
    'Void Terror Heart (legendary)',
    'Essence of Annihilation',
    'Reality Shard x3',
    '10d100 gold pieces',
  ],
  habitat: ['deep_void', 'destroyed_realms'],
  lore: `The Void Terror is one of the oldest aberrations,
predating the Sundering. It has consumed at least three
known realms and countless civilizations.`,
};

// Boss-specific interface
interface BossCreature extends Creature {
  phases: BossPhase[];
  legendaryActions: CreatureAbility[];
  lairActions?: CreatureAbility[];
}

interface BossPhase {
  name: string;
  healthThreshold: number; // Activates below this % health
  additionalAbilities: CreatureAbility[];
  statModifiers?: Partial<Creature['stats']>;
}
```

---

## Testing Creatures

### Validation

```typescript
import { validateCreature, CreatureValidation } from '@veilborn/core';

const validation: CreatureValidation = validateCreature(myCreature);

if (!validation.valid) {
  console.error('Creature issues:', validation.errors);
  // Example errors:
  // - "Health too low for CR"
  // - "Missing required ability for type"
  // - "Loot value exceeds CR guideline"
}

console.log('Balance score:', validation.balanceScore);
console.log('Suggested CR:', validation.suggestedCR);
```

### Balance Testing

```typescript
// Simulate combat to test balance
import { simulateCombat, SimulationResult } from '@veilborn/core';

const result: SimulationResult = simulateCombat({
  creatures: [myCreature],
  partyLevel: myCreature.challengeRating,
  partySize: 4,
  iterations: 100,
});

console.log('Win rate:', result.partyWinRate);
// Target: 60-80% party win rate for appropriate CR

console.log('Average rounds:', result.averageRounds);
console.log('Average party damage taken:', result.averagePartyDamage);
```

### Playtesting Checklist

- [ ] Creature survives 2-3 rounds against appropriate party
- [ ] Creature deals meaningful but not overwhelming damage
- [ ] All abilities have been triggered in combat
- [ ] Behavior matches type expectations
- [ ] Loot feels appropriate for effort required
- [ ] Description and lore enhance the encounter

---

## Creature Art Guidelines

### Image Specifications

- Resolution: 512x512 pixels (token) or 1024x1024 (full art)
- Format: PNG with transparency
- File naming: `{type}-{name}-{variant}.png`

### Using Asset Generation

```typescript
import { AssetGenerator, CreatureAppearance } from '@veilborn/core';

const appearance: CreatureAppearance = {
  type: 'aberration',
  size: 'large',
  bodyForm: 'six-legged quadruped',
  color: 'shifting purple and black',
  features: ['multiple eyes', 'phase-shifting outline'],
  abilities: ['invisibility', 'teleportation'],
  mood: 'predatory',
};

const generator = new AssetGenerator();
const { prompt, negativePrompt, style } = generator.buildCreature(appearance);
```

---

## Quick Reference

### CR to Stats Cheat Sheet

```
CR 1:  HP 18, ATK 4, DEF 11, Abilities 0
CR 3:  HP 34, ATK 7, DEF 12, Abilities 1
CR 5:  HP 50, ATK 10, DEF 14, Abilities 1
CR 7:  HP 66, ATK 12, DEF 16, Abilities 2
CR 10: HP 90, ATK 17, DEF 18, Abilities 2
CR 15: HP 130, ATK 24, DEF 22, Abilities 3
CR 20: HP 170, ATK 32, DEF 26, Abilities 4
```

### Behavior Quick Guide

```
Aggressive → Closest target, direct assault
Defensive  → Protect area, counterattack
Territorial → Warn first, escalate if ignored
Predator   → Weakest target, ambush tactics
Passive    → Flee, fight only if cornered
Pack       → Coordinate, surround, focus fire
```

---

_For card creation, see [Card Creation Guide](01-card-creation-guide.md)_ _For
realm building, see [Realm Building Guide](03-realm-building-guide.md)_
