Worlds & Files

A world is a self-contained project: its own characters, places, chapters, maps and timeline. Each world is a folder of plain files on your Mac.

Creating and switching worlds

To create a world:

1. Click Add World in the sidebar.
2. Under Create new, type a name and click Create World.

Realm Lore switches to the new world straight away. World names can use letters, numbers, hyphens and underscores. Any other character, including a space, becomes an underscore, so "The Shattered Realms" is saved as The_Shattered_Realms.

To switch worlds, pick one from the world selector at the top of the sidebar. Realm Lore remembers the last world you had open.

Importing a world

From a folder

1. Click Import World in the sidebar, or Add World > Choose World Folder….
2. Choose a world folder, for example one exported from another Mac or copied from a backup.
3. Click Open as World.

Realm Lore copies the folder into your Worlds folder and switches to it. The original folder isn't changed. If a world with the same name already exists, Realm Lore asks whether to Overwrite it.

From a ZIP archive

1. Open Settings > Data.
2. Under Import World Folder, click Import ZIP Archive….
3. Choose a ZIP made with Export ZIP Archive.

The world is named after the ZIP file. Switch to it from the world selector.

Deleting a world

1. Switch to the world you want to delete.
2. Open Settings > Data and scroll to Delete World.
3. Click Delete World…, then Confirm Delete.

WARNING

Deleting a world removes its folder and everything in it from your Mac. It doesn't go to the Trash and can't be undone. Export a ZIP first if you might want it back. See Backups & Export.

Where your worlds are stored

Each world is a folder inside:

~/Library/Application Support/realm-lore/Worlds/

To open it, choose Go > Go to Folder in Finder and paste the path. Settings > Data > Storage also shows the full path for your Mac.

Inside each world folder:

Folder	Contains
characters, creatures, races, factions, locations, things, lore	One file per wiki entry. Timeline events are stored in lore.
stories	One file per chapter or loose page.
books	One file per book.
relationships	One file per connection between two entries.
maps	One .md file per map, plus an .img file holding its background image.
assets	Images you've imported in the Asset Gallery.
trash	Entries you've deleted, until you restore or purge them.

The file format

Every entry is a Markdown file named with the entry's unique ID, such as 3f2a…c41.md. The top of the file is a frontmatter block between --- lines, with one field per line. Values are written in JSON format, for example:

---
id: "3f2a…c41"
name: "Lady Veyra Ashcombe"
role: "Villain"
status: "Alive"
tags: ["court","northern-reaches"]
---

Chapter text is stored below the frontmatter. You can read and edit these files in any text editor, or open the Worlds folder as a vault in Obsidian.

Each time Realm Lore saves a file, it keeps the previous version alongside it with .bak added to the name, for example 3f2a…c41.md.bak.

TIP

Realm Lore reads your files when a world loads. If you edit files in another app while Realm Lore is open, switch to another world and back, or reopen Realm Lore, to see the changes. Don't edit the same entry in two places at once.

Trash

When you delete an entry, chapter or map, Realm Lore moves its file into the world's trash folder instead of erasing it.

To manage deleted items, click Trash at the bottom of the sidebar. Each row shows the item's type, the start of its ID and its file path.

• Restore to library puts the file back where it was. If something new is already at that path, the restore fails.
• Delete forever permanently removes the file from the trash.

Trash is kept per world. Deleted images in the Asset Gallery don't go to the Trash.