---
slug: "worldbuilding-system"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/hopeoverture/worldbuilding-system@master/README.md"
repo: "https://github.com/hopeoverture/worldbuilding-system"
source_file: "README.md"
branch: "master"
---
# Worldbuilding System

An AI-powered worldbuilding toolkit for **D&D 5e (2024)** fantasy settings, built as an Obsidian vault with 97 structured templates, 24 AI-assisted skills, and comprehensive rules reference.

## Features

- **97 Reusable Templates** across 12 categories with structured YAML frontmatter, AI generation prompts, and image prompt fields
- **24 AI Skills (Slash Commands)** for world generation, entity creation, auditing, and session prep
- **Complete D&D 5e 2024 Rules Reference** - 65 files covering core rules, classes, spells, equipment, and monsters
- **Bidirectional Wikilinks** - Obsidian-native `[[Entity Name]]` cross-references with validation
- **Image Prompt Integration** - Built-in prompts for AI image generation (OpenAI gpt-image-1)
- **MCP Server Integration** - Obsidian, Memory, and Fetch servers for enhanced AI capabilities

## Quick Start

### Prerequisites

- [Obsidian](https://obsidian.md/) (recommended for viewing/editing)
- [Claude Code](https://claude.ai/code) or compatible AI assistant for skill commands
- Node.js (for MCP servers)
- Python 3.8+ (optional, for batch scripts)

### Installation

1. Clone this repository:
   ```bash
   git clone https://github.com/your-username/worldbuilding-system.git
   ```

2. Open the folder as an Obsidian vault:
   - Launch Obsidian
   - Click "Open folder as vault"
   - Select the cloned directory

3. (Optional) Install MCP dependencies for AI integration:
   ```bash
   npm install -g obsidian-mcp @modelcontextprotocol/server-memory @modelcontextprotocol/server-fetch
   ```

## Project Structure

```
Worldbuilding System/
├── Templates/                    # 92 reusable templates
│   ├── Characters/               # Protagonist, Antagonist, Support, Background, Familiar, Divine Servant
│   ├── Character Options/        # Background, Class, Subclass
│   ├── Settlements/              # Village, Town, City, Stronghold, Tavern, Shop, Temple, Library
│   ├── Items/                    # Weapon, Armor, Artifact, Wondrous Item, Potion, Food, etc.
│   ├── Creatures/                # Monster, Animal, Insect, Plant, Species
│   ├── Organizations/            # Guild, Government, Military, Cult, Academy, Business, etc.
│   ├── Concepts/                 # Deity, Pantheon, Magic System, Calendar, Currency, Language, etc.
│   ├── History/                  # Age, Event, War, Battle, Dynasty, Adventure, Tragedy, Treaty
│   ├── Geography/                # Continent, Region, Mountain Range, Forest, Dungeon, Cave, etc.
│   ├── Encounters/               # Combat, Social, Exploration, Trap
│   ├── Maps/                     # World, Continent, Region, Settlement
│   └── Reference/                # Naming conventions, validation guides, connection matrix
│
├── Worlds/                       # Your worldbuilding projects
│   └── [World Name]/
│       ├── World Overview.md     # Central world document
│       ├── Characters/           # NPCs and PCs
│       ├── Settlements/          # Cities, towns, villages
│       ├── Organizations/        # Factions, guilds, governments
│       ├── Geography/            # Regions, landmarks
│       ├── History/              # Timeline events
│       ├── Concepts/             # Magic, religion, culture
│       ├── Items/                # Notable objects
│       └── Encounters/           # Prepared encounters
│
├── D&D 5e 2024 Rules/            # Complete rules reference
│   ├── Core Rules/               # Ability Scores, Combat, Conditions, Actions
│   ├── Character Creation/       # Species, Backgrounds
│   ├── Classes/                  # All 12 classes with features
│   ├── Feats/                    # Origin, General, Fighting Style, Epic Boon
│   ├── Equipment/                # Weapons, Armor, Adventuring Gear, Tools
│   ├── Spells/                   # Cantrips through 9th level
│   ├── Monsters/                 # CR and XP reference
│   └── Appendices/               # Creature Types, Damage Types, Abbreviations
│
├── scripts/                      # Utility scripts
│   └── linkify_world.py          # Batch wikilink generator
│
├── .claude/                      # Claude Code configuration
│   ├── settings.json             # Permissions and attribution
│   └── skills/                   # 24 slash command definitions
│
├── CLAUDE.md                     # AI assistant instructions
├── GEMINI.md                     # Gemini-specific instructions
└── .mcp.json                     # MCP server configuration
```

## Skills (Slash Commands)

Use these commands with Claude Code or compatible AI assistants:

### World Creation
| Command | Description |
|---------|-------------|
| `/create-world [name]` | Create a new world with full folder structure |
| `/generate-world [name]` | Auto-generate 80-120 interconnected entities across 13 phases |
| `/worldbuild [name]` | Interactive guided worldbuilding with Q&A workflow |

### Entity Management
| Command | Description |
|---------|-------------|
| `/create-entity [description]` | Generate entity from template (e.g., "dwarven city called Ironhold for Eldoria") |
| `/create-template [type]` | Create a new template type |
| `/expand-entity [entity]` | Add detail, create sub-entities, deepen connections |
| `/populate-entity [entity]` | Scan for mentions, create linked entities, add wikilinks |

### Linking & Validation
| Command | Description |
|---------|-------------|
| `/link-entities [entity1] [entity2]` | Create bidirectional wikilinks between entities |
| `/linkify [entity]` | Auto-add `[[wikilinks]]` to all entity mentions in a file |
| `/audit-world [name] [--fix]` | Audit for broken links, D&D 5e stat errors, orphaned entities |

### Validation & Templates
| Command | Description |
|---------|-------------|
| `/validate-template [path]` | Validate a template or entity has required sections and YAML fields |
| `/campaign-arc [world]` | Track multi-session story arcs, plot threads, and campaign progression |

### Game Prep
| Command | Description |
|---------|-------------|
| `/random-encounter [location] [level]` | Generate combat, social, or exploration encounters |
| `/session-prep [world] [focus]` | Create DM session notes, NPC cheat sheets, location briefs |
| `/generate-image [entity]` | Generate AI image using OpenAI gpt-image-1 |

### Deep Expansion
| Command | Description |
|---------|-------------|
| `/expand-settlement [settlement]` | Deep-dive into settlements: generate NPCs, shops, taverns, districts, rumors |
| `/expand-faction [org]` | Build out organizations: hierarchy, internal politics, plots, rivals |
| `/expand-region [region]` | Fill regions with villages, landmarks, encounters, legends, hazards |
| `/generate-culture [people]` | Create cultural depth: festivals, customs, taboos, cuisine, ceremonies |
| `/map-relationships [entity]` | Visualize/expand relationship networks, power dynamics, secrets |
| `/expand-history [era/event]` | Detail historical periods: timelines, key figures, artifacts, witnesses |

### World Systems
| Command | Description |
|---------|-------------|
| `/generate-economy [world]` | Create trade routes, resource nodes, merchant guilds, black markets |
| `/generate-politics [world]` | Map alliances, conflicts, treaties, succession crises, power brokers |
| `/generate-quests [scope]` | Generate adventure hooks: bounties, mysteries, faction missions, dungeons |

## Template Format

All templates follow a consistent structure:

```markdown
---
tags: [template-type]
name: "{{title}}"
aliases: []
status: draft
image: ""
# ... entity-specific fields
---

# {{title}}

> [!info] Generation Instructions
> AI guidance for content creation...

## Section Name
Content with directive language ("Write 2-3 sentences...", "List 3-4...")

## Connections
- [[Related Entity 1]]
- [[Related Entity 2]]

## Image Prompts
**Art Style:** Description of visual style

### Scene 1
**Prompt:** [AI will fill this with entity-specific image prompt]
```

### Key Conventions

- **Wikilinks:** Always use `[[Entity Name]]` for cross-references
- **Status field:** `draft` → `in-progress` → `complete`
- **Image field:** `"[[Entity Name.png]]"` after image generation
- **Naming:** Title Case with spaces for files (e.g., `Mountain Range.md`)
- **Bidirectional links:** If A links to B, B must link back to A

## D&D 5e 2024 Integration

### Stat Block Modes

| Mode | When to Use | Fill | Leave Blank |
|------|-------------|------|-------------|
| **Level-based** | PC-style with class features | `level:` | `challenge_rating:` |
| **CR-based** | NPC/monster style | `challenge_rating:` | `level:` |

### Validation Formulas

```
Ability modifier     = floor((score - 10) / 2)
Proficiency (level)  = +2 (1-4), +3 (5-8), +4 (9-12), +5 (13-16), +6 (17-20)
Proficiency (CR)     = +2 (0-4), +3 (5-8), +4 (9-12), +5 (13-16), +6 (17-20), +7 (21-24), +8 (25-28), +9 (29-30)
Attack bonus         = proficiency + ability modifier
Spell Save DC        = 8 + proficiency + spellcasting ability modifier
HP (PC)              = hit_die_max + CON_mod + ((level - 1) × (hit_die_avg + CON_mod))
```

## Example World: Eldermyr

The repository includes **Eldermyr**, a complete example world with 54+ interconnected entities:

- **Setting:** Post-war succession crisis in a medieval fantasy realm
- **Tone:** Low/High Fantasy + Political Fantasy (inspired by Game of Thrones, LOTR, Octopath Traveler)
- **Content:** 16 characters, 12 settlements, 7 organizations, 6 geographic regions, 5 items, and more

Explore `Worlds/Eldermyr/` to see how templates are filled and entities interconnect.

## Scripts

### linkify_world.py

Batch add `[[wikilinks]]` to all entity files in a world:

```bash
python scripts/linkify_world.py Eldermyr           # Apply changes
python scripts/linkify_world.py Eldermyr --dry-run # Preview changes
python scripts/linkify_world.py Eldermyr --verbose # Detailed output
```

## MCP Integration

This vault includes Model Context Protocol (MCP) server configuration for enhanced AI capabilities:

| Server | Purpose |
|--------|---------|
| `obsidian-mcp` | Read/write vault files, search, manage notes |
| `server-memory` | Persistent knowledge graph for context retention |
| `server-fetch` | Web fetching for external references |

Configure in `.mcp.json`:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp", "/path/to/vault"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}
```

## Contributing

1. **Templates:** Follow the existing format in `Templates/`. Include YAML frontmatter, generation instructions, and image prompts.
2. **Skills:** Add new `.md` files to `.claude/skills/` following the skill definition format.
3. **Rules Reference:** Maintain accuracy with official D&D 5e 2024 materials.

## Template Categories

| Category | Templates | Examples |
|----------|-----------|----------|
| Characters | 6 | Protagonist, Antagonist, Support Character, Familiar |
| Character Options | 3 | Background, Class, Subclass |
| Settlements | 9 | Village, Town, City, Stronghold, Tavern, Shop, Bastion |
| Items | 11 | Weapon, Armor, Artifact, Potion, Book, Vehicle |
| Creatures | 5 | Monster, Animal, Insect, Plant, Species |
| Organizations | 9 | Guild, Government, Military, Cult, Academy |
| Concepts | 10 | Deity, Pantheon, Magic System, Calendar, Currency |
| History | 9 | Age, Event, War, Battle, Dynasty, Adventure |
| Geography | 18 | Continent, Region, Mountain Range, Forest, Dungeon |
| Encounters | 4 | Combat, Social, Exploration, Trap |
| Maps | 4 | World, Continent, Region, Settlement |
| Reference | 7 | Naming conventions, validation, YAML reference, formatting standards |

## License

This project is intended for personal use with tabletop roleplaying games. D&D 5e rules reference is derived from the 2024 System Reference Document (SRD) under the Creative Commons license.

---

*Built for dungeon masters, worldbuilders, and storytellers who want AI-assisted creative tools with the precision of structured data.*