🌌 Lore Creator

Build fictional universes inside Obsidian

Branching timelines · versioned drafts · your own time system

English  ·  Türkçe

✨ Features  ·  🧩 Concepts  ·  🚀 Getting started  ·  🏷️ Frontmatter  ·  ⌨️ Commands  ·  🛠️ Development

_{🕒 The timeline canvas — flows as lanes, time across the axis, branches drawn as curves}

Status — 0.11.0, feature complete. Every feature below works and is covered by unit tests where it can be. The frontmatter schema may still shift before 1.0.

💡 Why

Worldbuilding notes rarely get written in order. You write part 1, leave it half finished, jump to part 4, then go back to part 0. Later you decide the war started twenty years earlier than you first wrote, and eight notes have to change together — but you want to keep the old draft, because you are not sure yet.

Most tooling assumes you write forwards and never change your mind. This plugin assumes the opposite:

Everything lives in ordinary Markdown with ordinary frontmatter. Uninstall the plugin and your universe is still a readable set of notes.

🧩 Concepts

Four ideas, kept deliberately separate:

flowchart TD
    U["🌌 Universe<br/><i>one vault</i>"] --> T1["🕒 Timeline<br/><i>a reality</i>"]
    U --> T2["🕒 Timeline<br/><i>a parallel reality</i>"]
    T1 --> F1["🧵 Flow<br/><i>a character's lane</i>"]
    T1 --> F2["🧵 Flow<br/><i>another lane</i>"]
    F1 --> N["📄 Note<br/><i>a story fragment</i>"]
    F2 --> N
    N --> V1["📝 v3 · active<br/><i>lives at the note's path</i>"]
    N --> V2["🗄️ v2 · archived"]
    N --> V3["🗄️ v1 · archived"]

    classDef universe fill:#4f46e5,stroke:#3730a3,color:#fff
    classDef timeline fill:#7c3aed,stroke:#5b21b6,color:#fff
    classDef flow fill:#0ea5e9,stroke:#0369a1,color:#fff
    classDef note fill:#22c55e,stroke:#15803d,color:#062e11
    classDef active fill:#f59e0b,stroke:#b45309,color:#3b1d00
    classDef archived fill:#94a3b8,stroke:#475569,color:#0f172a

    class U universe
    class T1,T2 timeline
    class F1,F2 flow
    class N note
    class V1 active
    class V2,V3 archived

[!IMPORTANT] A parallel universe is a timeline; a second attempt at the same scene is a version. Confusing the two is the fastest way to make a vault incoherent.

✨ Features

🌿 Branching timeline canvas

Notes carrying a timeline id are laid out with time across the x axis and flows as lanes. Connections come from next and prev, drawn as curves so converging threads stay readable.

flowchart LR
    subgraph EXPLORER["🧵 Explorer"]
        direction LR
        A["First Signal"] --> B["Second Signal"] --> C["Silence"]
    end
    subgraph COLONY["🧵 Colony"]
        direction LR
        D["Founding"] --> E["Divergence"] --> F["Convergence"] --> G["Dissolution"]
        D --> H["Long Road"] --> F
    end
    C -.-> I["Ascent"]
    F --> I

    classDef done fill:#22c55e,stroke:#15803d,color:#062e11
    classDef partial fill:#f59e0b,stroke:#b45309,color:#3b1d00
    classDef draft fill:#94a3b8,stroke:#475569,color:#0f172a

    class A,B,D,E,F done
    class C,H,G partial
    class I draft

• Boxes widen to show duration (time-end) and go dashed when approximate (time-uncertain).
• Notes with no time yet get their own lane instead of vanishing.
• Border colour reflects status; a dot marks fragments that have other versions.
• Pan, zoom, click through to any note. Lane names and dates stay pinned at the edges while you pan.
• Filter by status, flow or type, or search the canvas: what does not match dims, nothing moves. Enter steps through the hits.
• Show the open note jumps to the note you are writing, on whichever timeline it sits.
• Keyboard: Tab reaches the notes, arrows walk between them, Enter opens, + − zoom, 0 fits, / searches. On touch, pinch to zoom.
• A parallel timeline shows where it split from its parent, with a marker at that moment.
• Lucide icons work on the canvas as well as emoji.

_{🔍 Searching for “Mira” — hits are outlined, the current one glows, the rest dims; nothing moves}

📝 Versions that reshape the story

Each version of a note carries its prose and its time, flow and connections. In one draft a scene leads to a battle; in another it leads somewhere else. Switch versions and the timeline redraws.

flowchart LR
    subgraph BEFORE["Draft A · v2 active"]
        direction LR
        A1["Second Signal"] --> A2["Silence"]
    end
    subgraph AFTER["Draft B · v3 active"]
        direction LR
        B1["Second Signal"] --> B2["Ascent"]
        B1 --> B3["Long Road"]
    end
    BEFORE -->|"switch version"| AFTER

    classDef old fill:#94a3b8,stroke:#475569,color:#0f172a
    classDef new fill:#7c3aed,stroke:#5b21b6,color:#fff
    class A1,A2 old
    class B1,B2,B3 new

The active version always stays at the note's own path, so [[links]] elsewhere in the vault never break. Older versions wait in an archive folder and are found by following version-of rather than by a list that could drift out of date.

📚 Version sets name a snapshot of which version of each note is active. One story revision usually touches many notes; without this, going back to the earlier draft means remembering and flipping every one of them by hand.

[!NOTE] Every file move is preceded by a dialog naming the exact paths, ordered so the current content reaches its new home before anything overwrites it. Records the plugin writes (version-of, version sets, promotions) use link text that names only one note, so two notes sharing a name in different folders never get mixed up.

📅 Your own time system

A universe does not have to run on Earth years.

time: 134923.4521          # always a single sortable number
time-precision: date       # year · date · datetime
time-label: "Xen Year 134923, day 165"
earth-time: 2050           # optional reference for readers

Define the time system once — unit name, days per unit, and, if you want, how it maps to Earth years — and the time picker fills in the number and the label for you. Or leave the mapping out and write the label yourself.

Edit time system (a command, also in settings) changes it later, with a live example and a warning before anything invalid is saved. If you change the number of days in a unit while notes already carry a date, it asks first: move those notes so each keeps the same day, or leave the numbers as they are. The move touches every dated note or none of them.

_{📅 The time system editor — the example line shows how a date is stored and read}

🗂️ Types and entities

Characters, species, places, factions, objects, events, laws, drafts. Each type brings its own fields, its own template and its own default icon.

The registry lives in a note's frontmatter, so adding a type is editing a note, not editing this plugin — and any AI assistant reading your vault can see what your types mean.

🕸️ Relations

The timeline shows what happens when; the relations view shows who belongs together. The open note sits in the middle, and every note its link fields (members, location, inhabitants, enemies…) and laws connect it with sits around it, in both directions, each line named after its field. Click a note to move to it, press 2 to look one step further out, and lock the view to keep one note in the middle while you read others.

_{🕸️ The Lighthouse in the middle — what happens there and who lives there}

Any link or links field you add to a type in the registry shows up here.

⚖️ Laws that know who breaks them

Universe-wide physics and entity-specific rules, kept as two layers. Entities declare which laws they are subject to and which they break; the laws view inverts those links so a law shows both. Laws can be scoped to particular timelines, for when a parallel reality runs on different physics.

flowchart LR
    L["⚖️ No faster-than-light travel<br/><i>scope: universe</i>"]
    C1["👤 Kyle"] -->|"laws"| L
    C2["👽 Xen envoy"] -->|"breaks-law"| L
    L -->|"the laws view inverts both"| VIEW["📋 Subject to · Breaks"]

    classDef law fill:#7c3aed,stroke:#5b21b6,color:#fff
    classDef entity fill:#0ea5e9,stroke:#0369a1,color:#fff
    classDef view fill:#22c55e,stroke:#15803d,color:#062e11
    class L law
    class C1,C2 entity
    class VIEW view

_{⚖️ Each law shows who is bound by it and who breaks it}

💡 Drafts you can promote

A shelf for ideas that have no home yet. Open one beside whatever you are writing without losing your place. When an idea earns a place in the story, promote it: pick the type and the folder, and choose whether the draft keeps its text or hands it over. Either way the draft survives and the two notes reference each other.

🧭 Banner and navigation

Every lore note gets a banner on top — its icon, type, status (click to cycle), version and its place in time (click to change it) — and a bar underneath showing where it leads. Fragments often lead to more than one place, so every destination gets its own button. Hover to preview the destination on a map that can show the whole timeline or just what is one step away — and can be pinned open.

_{🧭 Banner on top, map in the corner, the way back and forward at the bottom}

An empty next means the thread ends there. Nothing is invented to fill it. An archived version shows a slim bar instead, with a button back to the active one.

📊 Dashboard, search and export

What the consistency report checks Links: broken next/prev, broken links in any other field, one-sided next/prev, a note that leads to itself Story: links that go backwards in time, next loops, two periods overlapping in one flow, notes on a timeline with no time Structure: unknown timeline, flow or type, notes nothing links to, old records that name a note several notes share Laws: a law target that is not a law, a law broken outside the timelines it holds in Each kind has a chip; switched-off kinds leave the count too. While Obsidian is still reading the vault's links, the orphan check waits and says so.

📖 Built-in guide

A tour written so that anyone can follow it, opened once by itself the first time the plugin starts. One chapter per screen, in four groups — Getting started, While writing, Keeping track, Help — with small diagrams, a progress bar and read marks. Chapters carry buttons that do the step they describe: set up the universe, set up time, make a note, open the timeline.

The last chapter is a searchable FAQ. Field names appear only in the For the curious boxes, so the main text stays plain.

Example story. The Lantern Keepers is a 13-page universe with two flows, three characters, a broken law, a draft idea and a note with two versions. It is written to its own folder in the language you choose, every page is marked with an example badge in the views, and one button removes it again (to the trash, never deleted outright). Pages you copied from it stay yours.

Open the guide from the book icon in the ribbon, the Open guide command, or Settings → Help.

_{📖 One chapter per screen, with a diagram and a button that does the step}

🚀 Getting started

📥 Install

Lore Creator is in Obsidian's community plugins: community.obsidian.md/plugins/lore-creator.

1. In Obsidian: Settings → Community plugins, turn off Restricted Mode if it is on, then Browse and search for Lore Creator.
2. Install, then Enable.

[!TIP] On first start the guide opens by itself. Its Set up your universe chapter walks through the next two steps, and you can make the example story to see every view filled in before writing your own.

🪄 Set up a vault

Run Set up this vault from the command palette. It creates the folders, templates and type registry the views read from — previewing the exact tree first, and never overwriting a file that already exists. One step asks for your time system: a unit name, days per unit, and an optional link to Earth years. Files are written first and settings last, so a setup that stops halfway changes nothing; running it again only fills in what is missing.

📁 <vault>
├── 📄 Universe.md            ← time system, timelines, universe-wide laws
├── 📁 System/
│   ├── 📄 Types.md           ← the type registry: edit a note, not the plugin
│   └── 📄 Version sets.md
├── 📁 Templates/
├── 📁 Versions/              ← archived versions, found via version-of
└── 📁 Exports/

Folder names are chosen separately from the interface language: a universe is written in whatever language its story is, which is not necessarily the language of your menus.

✍️ Write something

flowchart LR
    S1["1️⃣ New lore note<br/>→ Timeline<br/><i>timeline-id: main</i>"]
    S2["2️⃣ New lore note<br/>→ Story<br/><i>set time, timeline, flow</i>"]
    S3["3️⃣ Link notes<br/><i>next / prev</i>"]
    S4["4️⃣ Open the timeline<br/><i>from the ribbon</i>"]
    S1 --> S2 --> S3 --> S4
    S3 -.->|"repeat"| S2

    classDef step fill:#4f46e5,stroke:#3730a3,color:#fff
    classDef last fill:#22c55e,stroke:#15803d,color:#062e11
    class S1,S2,S3 step
    class S4 last

1. New lore note → pick Timeline, name it, give it a timeline-id such as main, and list its flows.
2. New lore note → pick Story. In the banner at the top, click the time to place it, and set timeline and flow in the properties.
3. Repeat, linking notes with next.
4. Open the timeline from the ribbon.

🏷️ How notes are described

⌨️ Commands

On the timeline: Tab reaches the notes, arrow keys walk between them, Enter opens one, + − zoom, 0 fits, / jumps to search. In dialogs: Enter in a text field presses the main button.

⚙️ Settings

Every path is configurable; these are the defaults:

The time system is written into the universe note's frontmatter rather than plugin data, so a vault stays self-describing even without the plugin installed. The type registry lives in a note for the same reason. Settings also has an Edit time system button and a Help group that opens the guide.

Notes inside the templates folder are never counted as lore: they stay out of the timeline, dashboard, search, export and consistency report.

Interface language follows Obsidian's own, or can be set explicitly. 🇬🇧 English and 🇹🇷 Turkish are included. Frontmatter field names are English in every language — they are data, not interface.

🛠️ Development

npm install
npm run dev     # esbuild watch — rebuilds dist/ on save
npm run lint    # eslint with eslint-plugin-obsidianmd
npm test        # vitest unit tests (time, links, audit, settings…)
npm run build   # type-check, lint, then a minified dist/main.js

Every build writes main.js, manifest.json and styles.css into dist/ — exactly the three files a vault's plugin folder needs.

The sources live outside any vault. To work on the plugin, point a vault's plugin folder at dist/ — a junction or symlink keeps it to one copy:

# Windows (cmd), no administrator rights needed
mklink /J "<vault>\.obsidian\plugins\lore-creator" "<path to this repo>\dist"

# Windows (PowerShell)
New-Item -ItemType Junction -Path "<vault>\.obsidian\plugins\lore-creator" -Target "<path to this repo>\dist"

# macOS and Linux
ln -s "<path to this repo>/dist" "<vault>/.obsidian/plugins/lore-creator"

Obsidian does not reload plugins by itself. Hot Reload picks up rebuilds automatically; without it, run Reload app without saving after each change.

Every push and pull request runs npm ci, npm run build and npm test in CI.

Releases are tagged with the version number exactly, with no v prefix. Pushing the tag builds the plugin and publishes main.js, manifest.json and styles.css from dist/ as individual assets, which is what Obsidian expects.

There are no runtime dependencies — nothing third-party is bundled into main.js.

🤝 Contributing

Issues and pull requests are welcome. Two things worth knowing before you start:

• 🗄️ The vault is the source of truth. Anything the plugin knows should be readable from the notes themselves, so a universe survives without it.
• 🛡️ Nothing destructive happens without a dialog naming the exact files, and file moves are ordered so a failure leaves a duplicate rather than a hole.

💖 Lore Creator is free. If it helps your writing, you can support its development on GitHub Sponsors.