Fantasy-Map-Generator/OBSIDIAN_INTEGRATION.md

Obsidian Vault Integration for Fantasy Map Generator

Overview

Fantasy Map Generator now supports deep integration with your Obsidian vault for managing map lore and notes! This allows you to:

• Store all your world lore in Markdown format
• Edit notes in a modern Markdown editor (no more Win95-style TinyMCE!)
• Automatically link map elements to Obsidian notes by coordinates
• Keep your notes in sync between FMG and Obsidian
• Use wikilinks to connect related notes
• Edit in either FMG or Obsidian - changes sync both ways

Setup

1. Install Obsidian Local REST API Plugin

1. Open Obsidian
2. Go to Settings → Community Plugins
3. Click Browse and search for "Local REST API"
4. Install and Enable the plugin
5. Go to Settings → Local REST API
6. Copy your API Key (you'll need this!)
7. Note the Server Port (default: 27123)

2. Configure in Fantasy Map Generator

1. Open Fantasy Map Generator
2. Go to Menu → Tools → ⚙ Obsidian
3. Enter your settings:
   • API URL: http://127.0.0.1:27123 (default)
   • API Key: Paste from Obsidian plugin settings
   • Vault Name: Name of your Obsidian vault
4. Click Test Connection to verify
5. Click Save Configuration

Usage

Linking Map Elements to Notes

When you click on a burg or marker in FMG:

1. FMG searches your Obsidian vault for notes with matching coordinates in YAML frontmatter
2. Shows you the top 5-8 closest matches
3. You select the note you want, or create a new one

Note Format

Notes in your vault should have YAML frontmatter like this:

---
fmg-id: burg123
fmg-type: burg
coordinates:
  x: 234.5
  y: 456.7
  lat: 45.23
  lon: -73.45
tags:
  - capital
  - settlement
  - ancient
aliases:
  - Eldoria
  - The Ancient City
---

# Eldoria

The ancient capital sits upon the [[River Mystral]], founded in year 1203.

## History

The city was established by [[King Aldric the First]]...

## Notable Locations

- [[The Grand Library]]
- [[Temple of the Seven Stars]]
- [[Market Square]]

Coordinate Matching

Since your burgs/markers may have been imported from PostgreSQL without FMG IDs, the system matches by X/Y coordinates:

• FMG extracts the coordinates from the clicked element
• Searches all .md files in your vault for matching x: and y: values
• Calculates distance and shows closest matches
• You pick the right one!

Supported Coordinate Formats

The system recognizes these formats in YAML frontmatter:

# Nested object (recommended)
coordinates:
  x: 123.4
  y: 567.8

# Or flat
x: 123.4
y: 567.8

# Case insensitive
X: 123.4
Y: 567.8

Creating New Notes

If no matches are found:

1. FMG offers to create a new note
2. Enter a name (e.g., "Eldoria")
3. Optionally specify a folder (e.g., "Locations/Cities")
4. FMG generates a template with coordinates
5. Opens in the Markdown editor
6. Saved directly to your Obsidian vault!

Editing Notes

The modern Markdown editor includes:

• Live preview: Toggle between edit/preview modes
• Wikilinks: Link to other notes in your vault
• Syntax highlighting: Clean monospace font
• Open in Obsidian: Button to jump to the note in Obsidian app
• Save to Vault: Changes sync immediately

Using Wikilinks

Create connections between notes:

The [[King Aldric the First]] ruled from [[Eldoria]].
The city controls access to [[River Mystral]].

When you save in FMG, these links work in Obsidian!

Migration from PostgreSQL

If you have existing lore in PostgreSQL with coordinates:

1. Export your data to Markdown files with YAML frontmatter
2. Include x, y, lat, lon in the frontmatter
3. Place files in your Obsidian vault
4. FMG will auto-match by coordinates!

Example export script template:

for location in locations:
    frontmatter = f"""---
fmg-type: {location.type}
coordinates:
  x: {location.x}
  y: {location.y}
  lat: {location.lat}
  lon: {location.lon}
tags: {location.tags}
---

# {location.name}

{location.description}
"""
    with open(f"vault/{location.name}.md", "w") as f:
        f.write(frontmatter)

Tips & Tricks

Organize Your Vault

Create folders for different types:

My Vault/
├── Locations/
│   ├── Cities/
│   ├── Landmarks/
│   └── Regions/
├── Characters/
├── History/
└── Lore/

Use Templates

Create Obsidian templates for different element types:

• Templates/City.md
• Templates/Landmark.md
• Templates/Character.md

Search and Graph

In Obsidian:

• Use Search (Ctrl+Shift+F) to find notes by coordinates
• Use Graph View to see connections between locations
• Use Tags to organize by type

Sync Across Devices

Use Obsidian Sync or Git to keep your vault synced across computers!

Troubleshooting

Connection Failed

• Make sure Obsidian is running
• Verify the Local REST API plugin is enabled
• Check the port number (default 27123)
• Try restarting Obsidian

No Matches Found

• Check that your notes have x: and y: fields in frontmatter
• Verify coordinates are numbers, not strings
• Try increasing the search radius

Changes Not Appearing in Obsidian

• Obsidian should auto-detect file changes
• If not, try switching to another note and back
• Or close/reopen the note

Advanced

Custom Coordinate Systems

If you use a different coordinate system:

1. Map your coordinates to FMG's system
2. Store both in frontmatter:

coordinates:
  x: 234.5        # FMG coordinates
  y: 456.7
  custom_x: 1000  # Your system
  custom_y: 2000

Database Bridge

For the future PostgreSQL migration:

1. Keep coordinates in both Obsidian and database
2. Use coordinates as the join key
3. Sync changes via API
4. Eventually replace file storage with DB

Future Features

Planned enhancements:

• Time slider - view notes across historical periods
• Automatic tagging by region/culture
• Bulk import from database
• Real-time collaboration
• Custom Markdown extensions

---

Enjoy your modern, Markdown-powered world-building! 🗺️✨