# TTRPG Campaign Vault Patterns

Campaign vaults (D&D, Pathfinder, etc.) often follow a structured folder layout and include automation scripts. This reference documents common patterns for working with them, including the Pirate Campaign vault conventions previously captured in `ttrpg-campaign-workflow`.

## Folder Structure

Typical top-level folders:

| Folder | Contents |
|--------|----------|
| `Monsters/` | Stat blocks, lore, encounter notes |
| `Items/` | Magic items, equipment, loot tables |
| `Spells/` | Spell references, house rules |
| `Locations/` | Cities, dungeons, regions |
| `Adventures/` | Session plans, adventure hooks |
| `Factions/` | Organizations, NPC groups |
| `NPCs/` | Named characters, shopkeepers, villains |
| `Systems/` | Homebrew rules, combat systems |
| `Ships/` | Ship stats, deck plans, and HTML session tools |
| `Worldbuilding/` | Lore, cosmology, player handouts |
| `Templates/` | Reusable note templates |

## Campaign Vault Workflow

When a user asks for help with a TTRPG campaign vault:

1. **Locate the vault.** Resolve `OBSIDIAN_VAULT_PATH` or ask for the path. If the vault is iCloud-backed, use `references/icloud-vault-access.md` to sync or copy it locally first.
2. **Read `_Index.md` and existing templates.** Understand the current structure before adding new content.
3. **Favor existing conventions.** If the vault already has a crew model, stat-block format, or naming convention, reuse it.
4. **Keep a small named-crew roster** with trait + vibe + secret; treat extras as atmosphere.
5. **Track supplies in buckets** (Plenty / Low / Out) rather than exact counts unless the user explicitly wants simulation.
6. **Prefer 2d6 flavor-first tables** over d20 bookkeeping tables.
7. **Update indices** after creating notes or folders.
8. **Confirm sync** after edits if the vault is cloud-backed.

## Navigation Pattern

Each folder contains an `_Index.md` that links to its entries. The root `_Index.md` links to folder indices. This keeps Obsidian's graph view and quick-open navigable at scale.

## Templates

Templates live in `Templates/` and follow a naming convention (e.g., `Monster.md`, `NPC.md`). They include YAML frontmatter and section headers. New entries are created by copying the template and filling in content.

## Automation Scripts

Vault-local `scripts/` folders often contain:

- **Scaffolding scripts** (`scaffold.py`) — Query external APIs (e.g., 5e.tools) and generate templated markdown files in the correct folder, then update `_Index.md`.
- **Sync scripts** (`sync_to_icloud.py`) — Push local changes to iCloud Drive using pyicloud, handling delete-then-upload for overwrites.

Before creating new automation, check if the vault already provides these.

## Design Preferences (Pirate Campaign Example)

If the campaign is fiction-first (like the Pirate Campaign vault):

- **Crew / morale:** use a single 1-6 "ship mood" rather than per-person loyalty scores, wages, and daily ledgers.
- **Random tables:** prefer 2d6 tables with flavor-first results over d20 bookkeeping tables.
- **NPCs:** keep a small "named crew" roster with trait + vibe + secret; treat the rest as atmosphere.
- **Supplies:** track in buckets (Plenty / Low / Out) rather than exact counts.
- **Inspiration:** Black Flag shanty energy and One Piece found-family/nakama energy.

When revising systems, strip math and hidden percentile checks. Replace them with dramatic scenes and narrative prompts.

## Wikilink Conventions

Campaign vaults use wikilinks heavily:
- `[[Monster Name]]` for cross-referencing stat blocks
- `[[Location Name]]` for places
- `[[Session N — Title]]` for session notes
- Tag pages with `#campaign` or `#worldbuilding` for filtered searches

## Integration with 5e.tools

When a vault includes a `scaffold.py` that queries 5e.tools, the typical flow is:
1. Parse the vault's template files to learn the expected frontmatter and sections
2. Query the local 5e.tools instance (or self-hosted data) for the official stat block
3. Generate a new markdown file in the correct folder (e.g., `Monsters/Monster Name.md`)
4. Update the folder's `_Index.md` to link the new entry
5. Sync to iCloud if the vault is cloud-backed

See the `5etools-query` skill for querying official D&D data.

## Complementary Web Tools (Session Aids)

In addition to Obsidian markdown files, build lightweight HTML/JS tools stored in the vault for table use. These are ephemeral, interactive, and complement the persistent markdown reference material.

**Respect user preference:** If the user says "pause web tools," "no more HTML," or similar, stop building `.html` files and switch to Obsidian-native markdown. Build interactive tables, fillable forms, and dice-roll reference tables in markdown instead.

### Markdown Session Trackers (No-JS Alternative)

When the user prefers markdown over web tools, use these patterns:

**Crew / roster tracker:** A markdown table with columns for Name, Role, Wage, Skill, Loyalty, HP, Condition, Personality, Secret. Include a "Quick Actions" checklist section below the table for common actions (pay wages, issue rum, flog, etc.).

**Daily log template:** A session-by-session markdown template with sections for supplies consumed, morale modifiers, captain's orders checklist, daily event roller table (d20), crew changes log, and notes. Create one copy per voyage.

**Generator tables:** Port names, island features, NPCs, etc. as rollable markdown tables. Include a "Quick Sheet" section at the bottom with blank fields the DM fills in during play.

### Web Tool Patterns

Typical patterns:
- **Interactive grid viewers** — Color-coded deck plans with hover tooltips, deck toggling, and stat panels. Data sourced from 5e.tools `vehicles.json`.
- **Combat trackers** — HP bars with +/- buttons, crew action calculators, wind direction roses, initiative lists, and round counters.
- **Generators** — Random encounter, weather, hazard, and loot tables with one-click rolls and session history.
- **Campaign hub** — A single `index.html` linking all tools, vault indices, and 5e.resources.

Tool storage: place HTML files in a vault subfolder (e.g., `Ships/` or `Tools/`). They are markdown-ignored but accessible via `file://` or a local HTTP server. For a reusable starter, see `5etools-query/templates/tool-starter.html`. For the story-first crew/morale model used in the Pirate Campaign, see `5etools-query/references/loose-crew-morale-pattern.md`.

Serving tools for remote devices:
```bash
cd ~/obsidian-vault/Campaign-Vault/Tools
python3 -m http.server 8765
# Access via Tailscale: http://<tailscale-ip>:8765/
```

This lets players or the DM open tools on a phone, tablet, or second monitor during play without needing Obsidian installed.

Data flow for a complete ship reference:
1. Query 5e.tools `vehicles.json` directly for exact ship stats (the query script is fuzzy and may mismatch on vehicle names)
2. Write ASCII grid layouts as markdown in `Ships/Ship-Tier-N-Name.md`
3. Build an interactive `ship-grid-viewer.html` with color-coded CSS grids, stat panels, and deck toggles. Use `5etools-query/templates/tool-starter.html` as the starting scaffold.
4. Write `Current-Ship.md` for editable session state (crew roster, cargo, HP)
5. Serve the HTML tools via local HTTP and access across the Tailnet

## Auto-Sync for Cloud-Backed Vaults

If the vault is backed by iCloud Drive on a headless Linux host, automatic bidirectional sync is possible only when pyicloud can authenticate. A cron job can run a sync wrapper every 10 minutes (see `scripts/icloud-vault-sync.py`), but if 2FA expires the job will fail until the user re-authenticates. Always confirm whether the configured sync script can authenticate before promising automatic sync.

## Related Skills

- `5etools-query` — query self-hosted 5e.tools data for monsters, spells, items, vehicles.
- `ttrpg-campaign-workflow` — archived; this reference now owns the workflow conventions.