Games
To a game, a world on OnlyWorlds is content: characters, creatures, places, items, factions and events, with typed links between them. The world stays editable outside the game, on onlyworlds.com, in Atlas or in any tool built on the schema. So writers and designers can shape it without opening the engine, and the game picks up their work.
Three Ways to Use a World
Section titled “Three Ways to Use a World”Bake It In
Section titled “Bake It In”Fetch the world at build time and ship it inside the game. It works offline, needs no key at runtime, and changes only when you rebuild. This fits a world that is written first and then played.
- Unity: fill a cache asset in the Editor and reference it from your scripts.
- Any engine: read a world folder (one JSON file per element, the format Atlas and the Python package use), or take a full export from the API, and convert it into the engine’s own data.
Read It Live
Section titled “Read It Live”The game reads the world from the API while it runs, so a new character or a rewritten place reaches players without a patch. Fetch the world once, then ask the changes feed for what changed since your cursor, rather than fetching everything again.
A read key (ow_r_) is made for this: it reads, cannot write, and needs no PIN. A key inside a shipped game can be extracted, so assume your players can read the whole world. See Keys and PINs.
What a live read can count on:
- It’s free, with no fee and no account tiers.
- There is no request quota on reads per key.
- Under load the server answers
503server_busywith aRetry-Afterheader. Wait that long, then retry. - Image uploads have a daily cap per world.
- There is no uptime guarantee.
So a game that must never break should bake its world in, and read live only the content that may change.
Write Back
Section titled “Write Back”The game writes its outcomes into the world: who died, which town burned, what was found. The world becomes the record of play, and every other tool on it sees the result. Writing needs a write key and the PIN, so keep it on a server or in a tool you control, not in a game you ship to players.
Four rules keep a write from damaging work done elsewhere:
- Send only the fields that changed. A
PATCHreplaces every field it carries, so sending back an element fetched earlier undoes edits made since. - Change link lists with editLinks, which adds and removes ids on the server. A
PATCHwith a link list replaces the whole list. See Links. - Check every bulk response. A bulk write answers HTTP 200 even when some items failed. See Writes.
- Keep game-only state in extension fields (
x_yourgame_*), which the server stores and returns verbatim, up to 64 KB per element. A well-behaved client carries other tools’ extensions through untouched. See Extension Fields.
Engines
Section titled “Engines”| Engine | The path today |
|---|---|
| Unity | The Unity SDK: typed C# models, a v2 client, a world cache that ships as an asset, and a world browser in the Editor. |
| Browser games (JavaScript, TypeScript) | The TypeScript SDK. |
| Godot, Unreal and other engines | The REST API directly: HTTPS and JSON, with the key in a header (the call below). Generate a client from the OpenAPI document, and types for the 22 element types from schema-dist (its decoder, the walk, is Python today). |
| Build pipelines and tools | The Python package reads and writes world folders and talks to the API. |
Every path ends in the same call. This one reads three characters of Moppetopia, a public sample world, with its demo key, the same first run the SDKs start with:
curl -H "API-Key: 0000000001" \ "https://www.onlyworlds.com/api/v2/character/?fields=id,name&limit=3"Unity is the first engine with an SDK of its own. Until another engine has one, its path is the API.
Game Content in the Schema
Section titled “Game Content in the Schema”The 22 element types cover most of what a game holds. A starting point:
| In your game | Element type |
|---|---|
| Player characters, NPCs | Character |
| Races and peoples | Species |
| Monster and animal types (goblin, frost wyrm, the stat block) | Species |
| Individual monsters (the goblin chief, a named dragon) | Creature, linked to its Species |
| Items, gear, loot | Object |
| Skills, spells, actions | Ability |
| Passive perks, qualities | Trait |
| Guilds, kingdoms, orders | Institution (organized) or Collective (no formal structure) |
| Magic systems, currencies, crafting rules | Construct |
| Rules of a faction or realm | Law |
| Ranks and offices | Title |
| Languages, including those spoken in dialogue | Language |
| Quests and storylines | Narrative |
| Battles and happenings | Event |
| Weather, curses, magic storms | Phenomenon |
| Reputation, rivalries, alliances | Relation |
| Towns, dungeons, levels | Location |
| Territories and regions | Zone |
| Maps and what is placed on them | Map, Pin, Marker |
The line between Character and Creature is agency, not species: an intelligent monster with goals of its own can be a Character. supertype and subtype hold your game’s own categories (a Creature with supertype Boss), so you don’t need new element types for them. Where two types are close, Conventions draws the line between them. Each type’s fields are listed under Schema.
On OnlyWorlds Today
Section titled “On OnlyWorlds Today”Tactical Tangle is a hoplite battle game in which your OnlyWorlds characters fight in the ranks of a phalanx. Everything else built on OnlyWorlds is listed under Tools.