"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:
- Consistent Theme: All regions should feel like they belong together
- Clear Resonance: The dominant Resonance should be evident
- Internal Logic: Even strange rules should be consistent
- 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#
text
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#
text
Physical: forest, mountain, desert, swamp, plains, tundra, jungle, coastal, volcanic
Mystical: crystalline, ethereal, shadow, void
Location Sizes#
text
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 For creature creation, see Creature Creation Guide