# Veilborn Chronicles Realm Building Guide

> _"Each realm dreams itself into being. We merely visit those dreams."_ --
> Wanderer Kelis, Explorer of Boundaries

This guide explains how to create custom realms, regions, and locations for
Veilborn Chronicles.

---

## Understanding the Realm System

### The Three Circles

Veilborn's cosmology organizes realms into three circles based on their
relationship to the Veil:

| Circle            | Proximity to Material | Characteristics                | Examples                 |
| ----------------- | --------------------- | ------------------------------ | ------------------------ |
| **Inner Circle**  | Closest               | Stable, physical laws work     | Aethoria, Irondeep       |
| **Middle Circle** | Moderate              | Laws bend, concepts manifest   | The Dreaming, Echo Halls |
| **Outer Circle**  | Most distant          | Pure concept, reality optional | Ideosphere, Deep Void    |

### Resonance Balance

Every realm has a dominant Resonance that shapes its nature:

| Resonance    | Realm Characteristics          | Example Realms              |
| ------------ | ------------------------------ | --------------------------- |
| **Clarity**  | Memory, perception, knowledge  | Echo Halls, Ideosphere      |
| **Flow**     | Change, motion, transition     | Shorelands, Threshold       |
| **Presence** | Emotion, will, identity        | Verdance, Dreaming          |
| **Root**     | Matter, stability, endurance   | Irondeep, Aethoria          |
| **Void**     | Emptiness, boundaries, entropy | Deep Void, Twilight Marches |

---

## Realm Definition Structure

### Basic Template

```typescript
import {
  Realm,
  Biome,
  Climate,
  VeilIntensity,
  RealmProperties,
} from '@veilborn/core';

const myRealm: Realm = {
  id: 'realm-my-custom-realm',
  name: 'Realm Name',
  description: 'What makes this realm unique.',
  dominantBiome: 'forest',
  secondaryBiomes: ['mountain', 'swamp'],
  climate: 'temperate',
  properties: {
    gravity: 1.0,
    timeFlow: 1.0,
    magicAffinity: 50,
    veilIntensity: 'moderate',
    elementalBalance: {
      fire: 50,
      water: 50,
      earth: 50,
      air: 50,
      spirit: 50,
    },
  },
  portals: [],
  regionIds: [],
  dangerLevel: 5,
  secrets: ['A hidden truth about this realm'],
};
```

### Complete Realm Example

```typescript
const mirrorDeep: Realm = {
  id: 'realm-mirror-deep',
  name: 'Mirrordeep',
  description: `A realm of reflected possibilities where every surface shows
what could have been. Travelers must be careful not to become lost in
the infinite reflections of alternate selves.`,

  dominantBiome: 'crystalline',
  secondaryBiomes: ['ethereal', 'shadow'],
  climate: 'mystical',

  properties: {
    gravity: 0.9, // Slightly lighter
    timeFlow: 1.2, // Time passes faster
    magicAffinity: 85, // High magic
    veilIntensity: 'strong',
    elementalBalance: {
      fire: 30,
      water: 80, // Dominant - reflection
      earth: 20,
      air: 50,
      spirit: 90, // High spirit - identity
    },
  },

  portals: [
    {
      id: 'portal-mirror-gate',
      name: 'The Looking Glass',
      fromRealmId: 'realm-aethoria',
      toRealmId: 'realm-mirror-deep',
      stability: 'unstable',
      requirements: ['moonlit night', 'speak true name'],
      description: 'A mirror that reflects not your face, but your fate.',
    },
  ],

  regionIds: [
    'region-hall-of-selves',
    'region-fractured-gardens',
    'region-echo-shore',
  ],

  dangerLevel: 7,

  secrets: [
    'The first mirror was a tear in the Veil itself',
    'One reflection has learned to step through',
    'The realm remembers every face that has looked upon it',
  ],
};
```

---

## Biomes

### Available Biome Types

```typescript
type Biome =
  // Physical biomes
  | 'forest' // Dense woodland
  | 'mountain' // Rocky highlands
  | 'desert' // Arid wastelands
  | 'swamp' // Wetlands and marshes
  | 'plains' // Open grasslands
  | 'tundra' // Frozen landscapes
  | 'jungle' // Dense tropical growth
  | 'coastal' // Shores and islands
  | 'volcanic' // Fire and lava

  // Mystical biomes
  | 'crystalline' // Crystal formations, high magic
  | 'ethereal' // Dream-like, unstable
  | 'shadow' // Darkness-dominant
  | 'void'; // Edge of existence
```

### Biome Characteristics

| Biome       | Resources                        | Hazards                        | Resonance     |
| ----------- | -------------------------------- | ------------------------------ | ------------- |
| Forest      | lumber, herbs, game              | wild beasts, poisonous plants  | Root/Presence |
| Mountain    | ore, gems, stone                 | avalanches, altitude, cave-ins | Root          |
| Desert      | glass sand, sun crystals         | dehydration, sandstorms        | Flow/Clarity  |
| Swamp       | rare plants, peat                | disease, toxic gases           | Void/Flow     |
| Plains      | grain, clay                      | wildfires, stampedes           | Flow          |
| Tundra      | ice, furs                        | frostbite, blizzards           | Root/Void     |
| Jungle      | exotic fruits, venom             | predators, disease             | Presence/Root |
| Coastal     | fish, pearls                     | storms, sea monsters           | Flow          |
| Volcanic    | obsidian, fire gems              | lava flows, eruptions          | Root/Presence |
| Crystalline | veil crystals, resonance stones  | resonance sickness             | Clarity       |
| Ethereal    | dream essence, thought fragments | identity loss                  | Void/Flow     |
| Shadow      | shadow silk, dark essence        | shadow corruption              | Void          |
| Void        | null matter, entropy fragments   | existence erosion              | Pure Void     |

---

## Realm Properties

### Physical Properties

```typescript
interface RealmProperties {
  // Gravity relative to normal (1.0)
  // 0.5 = half gravity, 2.0 = double gravity
  gravity: number;

  // Time flow relative to normal (1.0)
  // 0.5 = time passes half as fast
  // 2.0 = time passes twice as fast
  timeFlow: number;

  // Magic affinity (0-100)
  // Higher = magic is stronger and more unpredictable
  magicAffinity: number;

  // Veil intensity
  veilIntensity: VeilIntensity;

  // Elemental balance (each 0-100)
  elementalBalance: {
    fire: number;
    water: number;
    earth: number;
    air: number;
    spirit: number;
  };
}
```

### Veil Intensity Levels

| Level          | Gameplay Effects                | Typical Realms          |
| -------------- | ------------------------------- | ----------------------- |
| `dormant`      | No supernatural activity        | Mundane regions         |
| `weak`         | Occasional Veil phenomena       | Most settlements        |
| `moderate`     | Regular supernatural encounters | Wilderness, thin places |
| `strong`       | Constant Veil activity          | Liminal realms          |
| `overwhelming` | Reality is unstable             | Outer Circle realms     |

### Property Guidelines by Circle

| Circle | Gravity | Time Flow | Magic  | Veil                |
| ------ | ------- | --------- | ------ | ------------------- |
| Inner  | 0.8-1.2 | 0.8-1.2   | 20-60  | dormant-moderate    |
| Middle | 0.5-1.5 | 0.5-2.0   | 50-80  | moderate-strong     |
| Outer  | 0.1-2.0 | 0.1-10+   | 80-100 | strong-overwhelming |

---

## Regions

### Region Structure

Regions divide realms into explorable areas:

```typescript
interface Region {
  id: string;
  realmId: string;
  name: string;
  biome: Biome;
  description: string;
  locationIds: string[]; // Locations within this region
  resources: string[]; // Available resources
  hazards: string[]; // Environmental dangers
  controllingFaction?: string;
}
```

### Region Example

```typescript
const hallOfSelves: Region = {
  id: 'region-hall-of-selves',
  realmId: 'realm-mirror-deep',
  name: 'The Hall of Selves',
  biome: 'crystalline',
  description: `An infinite corridor of mirrors, each showing a different
version of the viewer. Some reflections are kinder, some crueler, and
some have noticed they are being watched.`,
  locationIds: [
    'location-first-mirror',
    'location-identity-crossroads',
    'location-broken-gallery',
  ],
  resources: ['reflection crystals', 'identity shards', 'memory glass'],
  hazards: ['identity confusion', 'hostile reflections', 'reality loops'],
  controllingFaction: 'mirror-watchers',
};
```

### Resource Generation by Biome

```typescript
const biomeResources: Record<Biome, string[]> = {
  forest: ['lumber', 'herbs', 'game', 'mushrooms', 'veilwood'],
  mountain: ['ore', 'gems', 'stone', 'ice crystals', 'cave moss'],
  desert: ['glass sand', 'sun crystals', 'cactus water', 'buried relics'],
  swamp: ['marsh gas', 'rare plants', 'peat', 'swamp iron'],
  plains: ['grain', 'clay', 'wild horses', 'windstone'],
  tundra: ['ice', 'furs', 'frozen herbs', 'mammoth ivory'],
  jungle: ['exotic fruits', 'venom', 'rare woods', 'healing sap'],
  coastal: ['fish', 'pearls', 'sea salt', 'driftwood', 'kelp'],
  volcanic: ['obsidian', 'sulfur', 'fire gems', 'ash fertilizer'],
  crystalline: [
    'veil crystals',
    'resonance stones',
    'pure water',
    'light essence',
  ],
  ethereal: [
    'dream essence',
    'thought fragments',
    'memory mist',
    'soul echoes',
  ],
  shadow: ['shadow silk', 'dark essence', 'fear distillate', 'nightmare dust'],
  void: ['null matter', 'void essence', 'entropy fragments', 'nothing-stone'],
};
```

---

## Locations

### Location Types

```typescript
type LocationType =
  | 'settlement' // Towns, cities, villages
  | 'dungeon' // Underground complexes
  | 'ruin' // Fallen civilizations
  | 'wilderness' // Untamed nature
  | 'landmark' // Notable natural features
  | 'lair' // Creature homes
  | 'temple' // Religious sites
  | 'tower' // Magical structures
  | 'cavern'; // Natural caves
```

### Settlement Creation

```typescript
interface Location {
  id: string;
  regionId?: string;
  name: string;
  type: LocationType;
  description: string;
  size?: SettlementSize;
  population?: number;
  pointsOfInterest: PointOfInterest[];
  rooms?: Room[]; // For dungeons
  controllingFaction?: string;
  dangerLevel: number; // 1-10
  resources?: string[];
  features: string[];
}

// Settlement sizes and populations
type SettlementSize = 'hamlet' | 'village' | 'town' | 'city' | 'metropolis';

const populationRanges: Record<SettlementSize, [number, number]> = {
  hamlet: [10, 50],
  village: [50, 500],
  town: [500, 5000],
  city: [5000, 50000],
  metropolis: [50000, 500000],
};
```

### Settlement Example

```typescript
const reflectionCity: Location = {
  id: 'location-reflection-city',
  regionId: 'region-hall-of-selves',
  name: 'Mirroria',
  type: 'settlement',
  description: `A city built entirely of mirrors, where the population
includes both real beings and reflections that have gained independence.
Residents must carry identity tokens to prove they are originals.`,
  size: 'city',
  population: 15000,
  pointsOfInterest: [
    {
      id: 'poi-identity-registry',
      name: 'The Identity Registry',
      type: 'government',
      description: 'Where beings prove they are originals, not reflections.',
      isDiscovered: true,
    },
    {
      id: 'poi-glass-market',
      name: 'The Glass Market',
      type: 'commercial',
      description: 'Trade in mirrors, reflections, and captured possibilities.',
      isDiscovered: true,
      secrets: ['One merchant sells glimpses of alternate futures'],
    },
  ],
  controllingFaction: 'mirror-council',
  dangerLevel: 4,
  features: [
    'mirror-paved streets',
    'reflection guardians',
    'identity checkpoints',
    'possibility merchants',
  ],
};
```

### Dungeon Creation

```typescript
interface Room {
  id: string;
  type: RoomType;
  name: string;
  description: string;
  connections: string[]; // Connected room IDs
  features: string[];
  encounters?: string[];
  loot?: string[];
}

type RoomType =
  | 'entrance'
  | 'corridor'
  | 'chamber'
  | 'treasury'
  | 'shrine'
  | 'trap_room'
  | 'boss_room'
  | 'prison'
  | 'library'
  | 'laboratory';
```

### Dungeon Example

```typescript
const brokenGallery: Location = {
  id: 'location-broken-gallery',
  regionId: 'region-hall-of-selves',
  name: 'The Broken Gallery',
  type: 'dungeon',
  description: `A museum of shattered mirrors, each fragment showing a
moment frozen in time. Something terrible happened here, and the
reflections remember.`,
  dangerLevel: 7,
  features: [
    'shattered mirrors everywhere',
    'time loops in certain rooms',
    'hostile reflection fragments',
  ],
  rooms: [
    {
      id: 'room-gallery-entrance',
      type: 'entrance',
      name: 'The Cracked Foyer',
      description: 'A grand entrance hall with a massive cracked mirror.',
      connections: ['room-west-wing', 'room-east-wing'],
      features: ['crack in reality', 'warning inscriptions'],
      encounters: ['reflection scout'],
    },
    {
      id: 'room-west-wing',
      type: 'corridor',
      name: 'West Gallery',
      description: 'Portraits that watch visitors with too-aware eyes.',
      connections: ['room-gallery-entrance', 'room-memory-vault'],
      features: ['animate portraits', 'whispering walls'],
      encounters: ['portrait guardians'],
    },
    {
      id: 'room-memory-vault',
      type: 'treasury',
      name: 'The Memory Vault',
      description: 'Where captured memories are stored in crystal containers.',
      connections: ['room-west-wing'],
      features: ['memory crystals', 'preservation magic'],
      loot: ['Memory Crystal of the First Mirror', '500 gold'],
    },
    {
      id: 'room-east-wing',
      type: 'trap_room',
      name: 'East Gallery',
      description: "A hall where your reflection doesn't move with you.",
      connections: ['room-gallery-entrance', 'room-reflection-chamber'],
      features: ['delayed reflections', 'mirror traps'],
      encounters: ['trap - hostile reflection'],
    },
    {
      id: 'room-reflection-chamber',
      type: 'boss_room',
      name: 'The True Mirror',
      description:
        'A chamber containing the only mirror that shows true reality.',
      connections: ['room-east-wing'],
      features: ['reality anchor', 'truth magic'],
      encounters: ['The Broken Reflection (boss)'],
      loot: ['Shard of True Seeing', 'Mirror Walker Cloak'],
    },
  ],
};
```

---

## Portals and Travel

### Portal Definition

```typescript
interface Portal {
  id: string;
  name: string;
  fromRealmId: string;
  toRealmId: string;
  stability: 'stable' | 'unstable' | 'collapsing';
  requirements: string[];
  description: string;
}
```

### Portal Examples

```typescript
const portals: Portal[] = [
  {
    id: 'portal-veil-tear',
    name: 'The Whispering Tear',
    fromRealmId: 'realm-aethoria',
    toRealmId: 'realm-dreaming',
    stability: 'stable',
    requirements: ['sleep within 10 feet', 'dreamcatcher artifact'],
    description:
      'A shimmer in the air that appears only to those about to sleep.',
  },
  {
    id: 'portal-blood-gate',
    name: 'The Crimson Gate',
    fromRealmId: 'realm-irondeep',
    toRealmId: 'realm-crucible',
    stability: 'unstable',
    requirements: ['blood of a Veilborn', 'speak the true name'],
    description: 'An archway that only opens when fed with awakened blood.',
  },
  {
    id: 'portal-void-rift',
    name: 'The Hungry Rift',
    fromRealmId: 'realm-twilight-marches',
    toRealmId: 'realm-deep-void',
    stability: 'collapsing',
    requirements: ['sacrifice something precious', 'entropy ritual'],
    description: 'A wound in reality that grows larger with each use.',
  },
];
```

### Portal Stability Effects

| Stability    | Effects                          | Travel Risk |
| ------------ | -------------------------------- | ----------- |
| `stable`     | Reliable, consistent destination | Low         |
| `unstable`   | May deposit travelers off-target | Medium      |
| `collapsing` | Dangerous, may strand travelers  | High        |

---

## Procedural Generation

### Using the RealmGenerator

```typescript
import { WorldGenerator, RealmGenerator } from '@veilborn/core';

// Create generator with seed for reproducibility
const generator = new WorldGenerator(12345);

// Generate a complete realm
const realm = generator.realm.generateRealm({
  name: 'Shadowmere',
  biome: 'shadow',
  regionCount: 5,
  dangerLevel: 8,
});

// Generate regions
const region = generator.realm.generateRegion(realm.id, 'shadow');

// Generate portal
const portal = generator.realm.generatePortal(realm.id, 'realm-aethoria');
```

### Using the LocationGenerator

```typescript
// Generate settlement
const village = generator.location.generateSettlement({
  name: 'Darkhollow',
  size: 'village',
  regionId: region.id,
});

// Generate dungeon
const dungeon = generator.location.generateDungeon({
  name: 'The Shadow Crypts',
  roomCount: 10,
  dangerLevel: 7,
  regionId: region.id,
});

// Generate wilderness
const wilderness = generator.location.generateWilderness('shadow', {
  name: 'The Lightless Forest',
  regionId: region.id,
});

// Generate ruin
const ruin = generator.location.generateRuin({
  name: 'The Fallen Tower of Shadows',
  regionId: region.id,
});
```

### Custom Generation Seeds

```typescript
// Same seed = same results
const gen1 = new WorldGenerator(42);
const gen2 = new WorldGenerator(42);

const realm1 = gen1.realm.generateRealm();
const realm2 = gen2.realm.generateRealm();
// realm1 and realm2 will be identical

// Change seed for new results
gen1.setSeed(999);
const differentRealm = gen1.realm.generateRealm();
```

---

## Design Guidelines

### Realm Coherence

A well-designed realm should have:

1. **Consistent Theme**: All regions should feel like they belong together
2. **Clear Resonance**: The dominant Resonance should be evident
3. **Internal Logic**: Even strange rules should be consistent
4. **Connections**: Logical paths between regions and to other realms

### Region Balance

| Element              | Recommendation                                      |
| -------------------- | --------------------------------------------------- |
| Regions per Realm    | 3-7                                                 |
| Locations per Region | 3-10                                                |
| Danger Level         | Scale from edges (safer) to center (more dangerous) |
| Resources            | Balance rare and common                             |

### Location Design

**Settlements should have:**

- Clear purpose (trade, defense, religion)
- 2-5 points of interest
- At least one secret
- Connection to faction politics

**Dungeons should have:**

- 5-15 rooms for standard adventures
- Logical layout (entrance → challenges → boss/treasure)
- Mix of combat, puzzle, and roleplay encounters
- Loot appropriate to danger level

### Danger Level Guidelines

| Level | Description     | Appropriate For |
| ----- | --------------- | --------------- |
| 1-2   | Safe, civilized | New characters  |
| 3-4   | Moderate risk   | Level 2-4       |
| 5-6   | Serious danger  | Level 4-6       |
| 7-8   | High danger     | Level 6-8       |
| 9-10  | Extreme danger  | Level 8+        |

---

## Secrets and Discovery

### Adding Secrets

Every realm should have hidden elements:

```typescript
const secrets: string[] = [
  // Historical secrets
  'An ancient artifact lies buried beneath the surface',
  'The spirits here remember a great betrayal',
  'A lost civilization left behind powerful relics',

  // Cosmic secrets
  'The Veil is thin here, allowing passage to other worlds',
  'A sleeping entity awaits awakening',
  'The true name of this place grants power over it',

  // Tactical secrets
  'A hidden passage leads to a forgotten realm',
  'The local faction is secretly controlled by outsiders',
];
```

### Discovery Mechanics

```typescript
interface PointOfInterest {
  id: string;
  name: string;
  type: string;
  description: string;
  isDiscovered: boolean; // Has player found this?
  secrets?: string[]; // Hidden information
  discoveryRequirement?: string; // How to find it
}

// Example discoverable POI
const hiddenShrine: PointOfInterest = {
  id: 'poi-hidden-shrine',
  name: 'The Forgotten Shrine',
  type: 'shrine',
  description: 'An ancient altar to a god whose name is lost.',
  isDiscovered: false,
  secrets: [
    "Speaking the god's name restores their power",
    "The altar conceals a passage to the god's prison",
  ],
  discoveryRequirement: 'Clarity check DC 4 in the Sunless Grove',
};
```

---

## Testing Your Realms

### Validation

```typescript
import { validateRealm, RealmValidation } from '@veilborn/core';

const validation: RealmValidation = validateRealm(myRealm);

if (!validation.valid) {
  console.error('Realm issues:', validation.errors);
  // Example errors:
  // - "Veil intensity incompatible with biome"
  // - "Missing required regions"
  // - "Portal references non-existent realm"
}

console.log('Coherence score:', validation.coherenceScore);
```

### Playtesting Checklist

- [ ] Navigation between regions is clear
- [ ] Danger levels scale appropriately
- [ ] Resources and hazards match biome
- [ ] Portals work as expected
- [ ] Secrets are discoverable but not obvious
- [ ] Factions have clear presence and goals
- [ ] Theme is consistent throughout

---

## Quick Reference

### Realm Properties by Circle

```
Inner Circle:
  gravity: 0.8-1.2
  timeFlow: 0.8-1.2
  magicAffinity: 20-60
  veilIntensity: dormant-moderate

Middle Circle:
  gravity: 0.5-1.5
  timeFlow: 0.5-2.0
  magicAffinity: 50-80
  veilIntensity: moderate-strong

Outer Circle:
  gravity: 0.1-2.0
  timeFlow: 0.1-10+
  magicAffinity: 80-100
  veilIntensity: strong-overwhelming
```

### Biome Quick Reference

```
Physical:    forest, mountain, desert, swamp, plains, tundra, jungle, coastal, volcanic
Mystical:    crystalline, ethereal, shadow, void
```

### Location Sizes

```
Settlement: hamlet (10-50), village (50-500), town (500-5k), city (5k-50k), metropolis (50k+)
Dungeon:    small (5 rooms), medium (10 rooms), large (15+ rooms)
```

---

_For card creation, see [Card Creation Guide](01-card-creation-guide.md)_ _For
creature creation, see [Creature Creation Guide](02-creature-creation-guide.md)_
