Import and export

A whole world — its story, cast, places and all its games — can be saved as a single file, and loaded again later: on the same Mac, on another one, or in another app built on Roller. This is also a good way to keep a backup of a world you care about.

Export a world#

  1. In the left column, right-click the world's name.
  2. Choose Export legacy….
  3. Choose where to save the file and click Save.

The menu has two export items:

  • Export legacy… saves the world in the common baseline format that every version of Roller can import (see Worlds from other apps). It is always there, in every version of Roller.
  • Export… is reserved for versions of Roller that add features of their own: it would save the world together with those extras, in that version's own format. In this version of Roller there are no such extras, so Export would write exactly the same file as Export legacy: it is shown greyed out.

The file is called after the world, for example Harbour.roller.json. It contains everything in the world: its name, author and background, the Story, every character with their name and description and whether they're on stage, the places and which one is active, and every game in order, with its backstory, its turns (including your edits and patches) and what you had typed but not sent yet. It also notes the Protocol and Patcher the world was played with.

Export doesn't change anything in Roller: the world stays as it is.

Import a world#

  1. Make sure Roller is unlocked.
  2. Click Import world, just above the first world in the left column.
  3. Choose a world file (.roller.json) and click Open.

The world appears as a new world at the top of the list (the others move down), with all its games, and its first game opens. Nothing you already have is changed or replaced. If you already have a world with the same name, the new one gets a number added, for example Harbour 2.

Export a world, delete it, import the file again — and you get the same world back, exactly as it was. Only its place in the list may differ: an imported world goes to the top (drag it where you want it).

If the world was played with a different Protocol or Patcher than yours, Roller asks whether to use the file's. They are shared by all your worlds, so choose Cancel to keep yours.

Worlds from other apps#

Roller is shared freely, and other people make their own versions of it with new features. All of them can read each other's world files, because they share a common ground: the baseline. It's the part every version understands — the story, the cast, places, games, turns, backstories and patches.

When you import a world that was made by another version of Roller, a small message tells you so:

  • which app made the file;
  • that it was read as a baseline file, so everything the baseline describes is there;
  • that not all functions of that app might be supported here — for example, if that app keeps extra information about the characters' moods, Roller doesn't know what to do with it;
  • and which parts of the file were left out.

The world itself is complete and playable. Only the extras of the other app are missing. If you export the world again, those extras aren't in the new file either.

The same works the other way round: worlds you export can be imported by other versions of Roller.

What's in the file#

You don't need to know this to use Import and Export, but in case you're curious: the world file is a plain text file (JSON) that you could open in any text editor. At the top it says that it's a Roller world (format), which version of the file format it uses (version), which baseline it follows (baseline: 1), and which app made it, with that app's unique ID (app). Then comes the world itself.

For people who change Roller#

If you develop Roller further — on your own or with the help of an AI assistant — please keep the baseline working, so worlds can keep moving between all versions of Roller:

  • Give your version its own app ID and name (in the file exchange.js).
  • Keep Export legacy as it is: it must always write a pure baseline file. Your own format goes into Export…, which you switch on (in exchange.js) once your version has extras to save.
  • Keep reading baseline files from other apps, including the little message after the import.
  • Put your new features' data in your own extension area of the file, instead of changing what's already there.
  • Keep the documentation up to date.

The details are in the files BASELINE.md (the exact description of the baseline) and AGENTS.md (the rules, written so that an AI assistant finds and follows them) in the Acopa folder.