Moving to GM Harness 2
A world built for the original GM moves to GM Harness 2 in a few steps. Nothing changes for players until a version on GM Harness 2 is published, and games already in progress keep the original GM until their owner moves them.
The steps
- Save a version on the original GM. It is the way back.
- Translate the old instruction files into GM instructions.
- Switch the world's draft to GM Harness 2, with the translation.
- Clean up the files GM Harness 2 doesn't need: hide old memory and tracker files, make trackers, remove memory fields, move game start openings.
- Test the new rules.
- Publish a version. Only then do new games start on GM Harness 2.
Press Upgrade on the banner at the top of your world's workspace (it's also in Settings › Game Master).
The upgrade runs as a small panel over your workspace: What's changing, Save a version, Translate, Clean up and Review and create a version. You can keep editing while it's open, or fold it to a pill.
You can also upgrade with a coding agent such as Claude Code, in a copy of the world cloned with the Craft CLI (see The Craft CLI). Every cloned world carries this guide, and the agent can also do the parts the app leaves to you: trackers, memory fields and game starts. Orbit, the assistant in your workspace, can talk the upgrade through, start the translation once you've saved a version, and explain its report.
Saving a version
Before anything changes, save a version of the world as it is. The upgrade's Save a version step opens Create Version for it (only the world's owner can save one). Restoring it later brings back the original GM with that version's files and settings. The upgrade in the app waits until the world has no changes a version doesn't hold.
Translating the instruction files
The translation reads every old instruction file with its trigger, the GM's personality, the file types' fields and the rule files the instructions lean on (the core roll, combat, conditions). It writes them as GM instructions and player options, and reports what became of each file: kept, rewritten, merged, moved into a player option, or dropped, with the reason.
- Rule files win. Where an old instruction disagrees with a rule file (one said Help gives +1, the combat rules +2), the translation follows the rule file and reports the disagreement.
- Everything else carries over. It cuts what GM Harness 2 does itself and copies of Craft's defaults, and rewrites every other rule about the world, its mechanics and its tone for its moment.
- Read it as a first draft. Check the report, then the instructions.
- Nothing to translate (no instruction file with any text, and no GM personality) skips this step: the world switches on Craft's default GM instructions. A GM personality alone is translated.
In the app the translation is free, takes a few minutes (up to about ten for a big world) and changes nothing until it is applied. Applying it replaces the world's GM instructions whole and switches the draft to GM Harness 2.
Where each old instruction file goes
| Old file | Becomes |
|---|---|
| Always in context (often pinned) | An always-on instruction, only if the GM needs it on almost every turn; otherwise a situational instruction for each moment it covers |
| Triggered by a story moment | A situational instruction whose trigger names that moment |
| Triggered when the GM read, created or updated a kind of file | A situational instruction about that moment in the story ("When a new character joins the party"), or nothing when it was only about the file or the tool |
| The steps for running a longer moment (a fight's rounds, a negotiation), whatever its trigger | A procedure, or a script when the steps are exact math and bookkeeping |
| Several files about one moment | One situational instruction, or one procedure |
| A rule that switches between ways of playing ("in hard mode…") | A player option, with a default that plays as the world always has |
Two more things often need an always-on instruction of their own:
- The dice. Put the core roll and its dice in an always-on instruction, and never mention a d20 the world doesn't use (see Dice).
- An unusual calendar. Describe its months, weeks and holidays, and how a date is written, in the rules of Craft's Time tracker, so the date shows the world's way (see Craft's defaults). The app's translation doesn't change trackers, so it writes the calendar as an always-on instruction named "Calendar" instead.
How to write the instructions themselves is in GM instructions.
What to leave out
GM Harness 2 does these itself, so the translation drops them and they shouldn't come back:
- memory systems: logs, state files, archives, "re-read X before every reply", memory fields;
- tracker upkeep: "update the Heat tracker after every job";
- bookkeeping: "subtract the gold after every purchase", lists of fields to update;
- moving tokens, pinning new places, removing the dead;
- roll procedure: "wait for the player to roll";
- output formats: beats, JSON blocks, headings, lists of choices, dialogue formatting;
- tool and shell steps, file paths, "read every file before you reply";
- pinning and partial visibility;
- copies of Craft's defaults (player agency, reply length, pacing, travel, combat, objectives and time; see Craft's defaults).
A file the player is meant to read, like a ship's log the GM keeps up, can stay. Just don't use files as the GM's memory.
Cleaning up files
Many V1 worlds built files to do the GM's own bookkeeping. Left visible, they make GM Harness 2 worse: it has written changes into tracker files instead of the sheets they belonged on. The upgrade lists them by kind:
| Kind | Why it isn't needed |
|---|---|
| Memory | GM Harness V2 keeps its own memory of every game. |
| Combat tracker | GM Harness V2 keeps turn order and the fight in its current state. |
| Quest tracker | GM Harness V2 keeps the party's objectives in its current state. |
| Scene tracker | GM Harness V2 keeps the scene in its current state. |
| Tracker | GM Harness V2 keeps clocks, time and the party's state itself. |
- Hide, don't delete. A hidden file stays in the world and can be shown again, and games still on the original GM keep reading it. To hide one, click the visibility button at the end of its row in the file tree, or in the file editor's toolbar; each click flips it, and a hidden file's button stays red. Hide files one by one, not their whole type. The upgrade's list can also move files to the trash, or skip the step.
- Judge by system names. The list matches a file type's name ("Campaign State", "Quest Tracker") or a folder's ("World Memory", "Archive"), never one file's name: "Modify Memory" is a spell.
- Check large groups. Only a type with 5 files or fewer starts selected. A bigger type is often content in a tracker's shape: one world's 195 "Quest Tracker" files were real quests the GM still needs.
- Keep relationship, bond and reputation files, and designated files (characters, locations, game starts, scripts).
- Move lasting knowledge in a file you hide (history, secrets, who knows what) into lore, character or location files first.
Trackers, memory fields, game starts and examples
The translation doesn't do these, so they are left to you after it:
- Tracker files become trackers. Make a tracker for what each one counted, from a template if one fits, check Craft's own first (combat, objectives, party, time), and hide the old file. A Heat Tracker file and "After every job, update Heat" become one tracker: Heat, a 6-slice clock, updated when the crew draws attention, "At 6, the Watch raids the hideout".
- Memory fields go. Remove fields like "Memory" or "Notes on the party" from the file types (see Changing a type).
- Game starts move off the opening instruction file. Who is there, the time, what the opening scene is for and the first objectives go in the opening current state; what the GM needs for its first reply goes in the opening notes. See Game starts.
- Keep one good example of each type. When the GM creates a character, place or item, it models it on the world's closest file.
Testing before you publish
- See what the GM gets with the System prompt and Instruction tester in the world's GM instructions (see Testing a change).
- Play on GM Harness 2. Test games start from the latest published version, like players' games, so they stay on the original GM until a version on GM Harness 2 is published. A world never published is the exception: its games start from the live world, so they switch at once.
Publishing
Publish a version once the new rules play well. To publish, click Create Version at the top right of the workspace. Players' new games start on GM Harness 2 from then on. On a public world every published version reaches players at once; if a V2 version ships broken, promote your last version on the original GM to point new games back at it (see Releases).
Going back
There is no switch back. Restoring the version saved before the upgrade brings back the original GM with that version's files and settings. Open the world's version history and restore the version you saved before the upgrade.
- Restoring changes the draft only. New games keep starting from the published version until you publish again, or promote the version on the original GM (see Releases).
- Games that moved stay on GM Harness 2. A game never moves back.
Games in progress
- They stay on the original GM. It still reads the world's old instruction, tracker and memory files, so leave them in place. On a world on GM Harness 2 the old instruction files are marked Deprecated and stay editable.
- A game moves when its owner takes the V2 update. Once the world's published version is on GM Harness 2, syncing it into a V1 game offers "GM Harness, V1 → V2". Taking it brings the world's GM instructions with it. Left unticked, the game stays on V1 and is offered the move again at its next sync.
- Before its first V2 turn, the GM reads back through the story and writes the V1 turns into its memory as chapters ("Getting your story ready"). Most games wait about a minute, very long ones a few. The game then carries on from where the original GM left off. The original GM's messages stay in the game. A move can't be undone.
- Reading the chapters. Open Inspect turn from a reply's ⋯ menu: the GM's memory, with the latest chapter in full, is among the messages the turn opened with. Orbit, in the game's chat, can read every chapter.
- Rewinding into the old turns with Delete from here deletes the chapters it reaches. The GM writes what is left again before the next turn.
- An owner who can't wait can upgrade the game with AI: it translates the game's own copy of the instruction files and moves the game. It runs on the game alone, with no clean-up step, and may play less well than instructions the world's author wrote for GM Harness 2.
- A fresh game plays best. A game moved from the original GM doesn't play as well on GM Harness 2 as one started there.
Where a game is offered the move: the game screen, by its owner. Once the world has a V2 version, it's Get the update on the V1 banner or Get Updates; before that, it's the AI upgrade behind the banner's See options or the V2 button in the game's left rail.