OnlyWorlds Builder

An Obsidian plugin that keeps an OnlyWorlds world as notes in your vault, one note per element, and syncs it with onlyworlds.com if you want.

Each element is a plain Markdown note. Its number and link fields are Properties; its text fields are foldable sections in the body. Link fields are [[wikilinks]], so relationships show up in the graph view and backlinks. Works on desktop and mobile.

OnlyWorlds is an open standard for worldbuilding data: 22 element types (Character, Location, Institution, Event and the rest), each with defined fields and links.

Install

In Obsidian: Settings → Community plugins → Browse, search for OnlyWorlds Builder, install and enable it. Or open the plugin's listing.

Start a world

No account:

Run Create World from the command palette (Ctrl/Cmd+P) and choose Create local-only.
Run Create Element, pick a type and a name. The note opens with every field that type can carry.
Edit it like any note.

A local-only world's World.md reads API Key: local. Nothing is sent anywhere.

With an onlyworlds.com account:

Make an account at onlyworlds.com.
Run Create World and choose Create with account (your email and PIN). The plugin creates the world on onlyworlds.com and writes its API key into World.md.
Push edits with Save Element, Upload World, or auto-sync (below).

A world you already have online: run Download World and enter the world's API key (from your account page) and your PIN. A read-only key (ow_r_) needs no PIN, which suits a world someone shared with you. Classic 10-digit keys and ow_ keys both work.

Taking a local world online: run Create World, enter your email and PIN, pick the world under Or take a local world online, and press Take online. The plugin creates the world on your account, writes the key into World.md, and uploads the elements, keeping their ids and links. (By hand: replace local in World.md with the key of a world you made on the site, then run Upload World.)

A note

---
id: 069f869b-de7a-7466-8000-eeea6e0e5632
name: Maren Vell
supertype: pilot
height: 172
charisma: 62
species:
  - "[[Human]]"
location: "[[Gullwrack]]"
---

### Description

Harbour pilot of Gullwrack, forty years on the shoals.

### Physicality

Weathered, quick hands, a limp she never explains.

The body holds one ### section per text field, in schema order. Manage Fields adds or removes fields on a note; Add Custom Field adds one of your own (type Looks, get a ### Looks section, synced as x_looks). Empty fields are not uploaded.

Text fields round-trip byte for byte through the plugin, spaces, tabs and line endings included, with two exceptions: a line that starts with ### starts a new field, and a code fence (```) inside a value must be closed, or the sections after it are read as part of it.

The note's identity is the id in its Properties, so renaming a note does not break anything.

Sync

The plugin reads the world's key from that world's World.md. The API key setting is a fallback for a world whose World.md has no key (the plugin warns when it uses it). A local-only world never syncs.

Only notes inside a world's Elements folders are elements. Notes you already had elsewhere in the vault never sync; to bring one in, run Create Element and paste its text into the new note.

How	What it sends
Save Element	The active note. Reads the element on the server first and sends only the fields that changed; fields the note doesn't carry are left alone. No default hotkey: bind one in Settings → Hotkeys.
Auto-sync (off by default)	The note you edited, a few seconds after you stop typing (3000 ms by default, set in settings). Same as Save Element. It hears only edits typed in Obsidian: notes another tool writes (Atlas, a script, a sync client) are not pushed, so run Upload World after such a change.
Upload World	Every element in the active world. It creates new elements and updates existing ones. Elements that exist only on the server are counted in the summary, not deleted.

On both Save Element and Upload World, a link field holding a [[Name]] that matches no note in the vault is not sent at all, so the server keeps its copy of that field. Save Element names those links; upload the target element, then save again.

When Save Element changes an element's name, its note is renamed to match, through Obsidian, so links to it update as your Files and links setting says. A name another note already has gets a number, as on download: Vallaki (1). Auto-sync never renames. Turn it off in settings.

A link to a note that is in the vault but not on the server yet: Save Element lists those elements and asks first (Create or Cancel), then creates them together with the note, and says so ("Created Location "Vallaki" first."). The same goes for that element's own links to new notes. It creates at most 50 this way; past that it creates nothing and asks you to run Upload World. Auto-sync never creates them: the server refuses that save, and the notice says to run Save Element.

An element deleted on onlyworlds.com is never brought back without your word, even though Download keeps its note. Save Element asks "create it again?", auto-sync refuses, and Upload World asks once for all of them. A link to a deleted element is left out of the save, and the note keeps it.

Download World pulls the other way. The first run fetches the whole world; later runs fetch only what changed. For each element that changed on the server, it rewrites that note's fields and body from the server's copy, so unsaved local edits in that note are replaced. Properties the plugin doesn't manage are kept. Elements deleted on the server keep their notes; the plugin tells you how many.

World units. World.md has a Units section: Length Unit, Mass Unit and Distance Unit, free text such as cm, kg or leagues. They are labels only; nothing converts. Properties shows the unit beside the nine numbers that use one: height and weight on Characters and Creatures, Creature speed, weight on Objects and Species, Ability range and Location elevation. Download World writes the server's units into World.md. Upload World sends them when you changed them; only the world's owner can.

The ribbon icon and the desktop status bar show the sync state: idle, dirty, syncing, synced or error.

Bases

Download World and Create World write <World name>.base beside World.md: a table and a card view for each element type in Obsidian's core Bases plugin (Obsidian 1.9 or later). Turn it off with the Write a Bases file per world setting.

The plugin rewrites only its own file, unchanged since it wrote it. Once you change the base (a view, a sort, a column), Download leaves it as is and says so once; delete it, or run Write Bases file, which rebuilds it and keeps your version beside it as <World name> (your copy).base. Rename World moves the plugin's file to the new name.

With Obsidian Sync or another sync tool, Download rebuilds the base from your world on each device. A stale copy from another device then replaces the base, unless it carries your edits: a base with your edits is kept as is, and Write Bases file saves it as <World name> (your copy).base before it rebuilds. Let an edited base sync to every device before you download on another.

Commands

Command	What it does
Create World	Create a world: with an account, local-only, or take a local world online.
Download World	Pull a world from onlyworlds.com into the vault. Later runs fetch only changes.
Create Element	New note with a fresh id and the type's full field set.
Save Element	Push the active note (see Sync).
Upload World	Push every element in the active world: create and update, never delete.
Delete Element (server + note)	Delete the element from onlyworlds.com and move the note to the trash, after you type its name. In a local-only world it only trashes the note.
Link Elements	Pick a link field, then a target element; writes a `[[wikilink]]`. You can also type in the Property directly.
Manage Fields	Tick which fields the note carries. A field with content can't be removed here: clear it first.
Add Custom Field	Add your own text field (stored as `x_<name>`).
Rename World	Rename the world folder, and the world on onlyworlds.com if it has a key.
Write Bases file	Write the active world's `.base` file (see Bases); rebuilds one you changed, keeping your version beside it.
Draw relationships on a canvas	Draw the active element, what it links to and what links to it as an Obsidian canvas beside its note, each arrow labelled with its field. A Relation keeps its own card. Running it again redraws the canvas; one you changed is first saved as `(your copy)`. File names stop at 255 characters, so an element whose name is longer than about 230 gets no canvas.
Export as OnlyWorlds folder	Write the world as an OnlyWorlds folder (`world.json` plus one JSON file per element). Into the vault, or on desktop into any folder, such as your Atlas folder. Never overwrites an existing folder.
Import OnlyWorlds folder	Read an OnlyWorlds folder placed in the vault into notes. Skips elements that already have a note; refuses to merge into a different world of the same name.
Copy World to Clipboard / Paste World from Clipboard	The world as JSON, out and back in.
Update World to Latest Format	Bring older notes to the current layout: adds missing fields, moves text fields into body sections. Shows the changes and writes nothing until you confirm.
Migrate world notes to frontmatter	Convert notes from the old `<span>` format. Backs every note up first, to `OW-backup-<world>-<timestamp>/`.
Validate World	Check old `<span>`-format notes for malformed fields. Notes in the current format are skipped.

Updating the plugin does not change your notes, and it reads every format it has written. Run either format command on a copy of the vault the first time.

Settings

Setting	Default	What it does
API key	empty	Fallback key for a world whose `World.md` has none. Stored in the vault's plugin data.
API PIN	empty	Your 4-digit PIN, stored in the vault's plugin data. Leave empty to be asked once per session.
Default world	empty	The world commands act on. Empty: the first world alphabetically.
Default email	empty	Pre-fills the email in Create World.
Default new element category	Character	Pre-selected in Create Element.
Individual element creation commands	off	Adds a `Create new <Type>` command per element type. Reload Obsidian after changing it.
Auto-sync to OnlyWorlds	off	Push edits automatically.
Auto-sync debounce (ms)	3000	Wait after the last edit before pushing (250 to 30000).
Show status bar indicator	on	Sync state in the desktop status bar.
Rename note when the element's name changes	on	After Save Element changes an element's name, rename its note to match. Auto-sync never renames.
Write a Bases file per world	on	Download World and Create World write the world's `.base` file (see Bases).
Relationship canvas: links to the element	on	Draw relationships on a canvas also draws the elements that link to the active one.

Files

OnlyWorlds/
├── README.md
├── Settings.md
└── Worlds/<World name>/
    ├── World.md
    ├── <World name>.base
    └── Elements/<Type> (<count>)/<Element name>.md

The plugin talks to the OnlyWorlds API at https://www.onlyworlds.com/api/v2/, sending the world's key and your PIN as headers.

Licence

MIT. See LICENSE.

OnlyWorlds Builder

Description

Reviews

Stats

Latest Version

Changelog

README file from