Hosted Projects on Desktop (Local-First Sync)

When you open one of your hosted projects in the desktop Studio (they are listed under Cloud Projects in the launcher), the editor no longer talks to the cloud database on every click. Instead, the project is copied once into a local working copy on your machine, everything you do runs against that copy at local speed, and a background sync keeps the cloud in step while you work.

You don't have to set anything up — this is how hosted projects open on desktop by default.

What You'll Notice#

How It Works#

1. First open — the Studio downloads your project into a local copy (you'll see a progress bar; time depends on project size and connection). This happens once per machine.
2. While you edit — a background sync pushes your changes to the cloud about every 30 seconds, and always once more when you close the project. You never trigger it manually.
3. Next open — the Studio quickly checks whether the cloud copy changed since your last session (for example, from edits made in the browser editor). If nothing changed elsewhere, the project opens immediately.

One Editor at a Time#

Local-first editing uses a writer lease: while your desktop session is syncing, it holds the lease on the project, and a second desktop opening the same project is told who currently holds it. This is a single-writer model — the sync never merges two people's simultaneous edits.

Editing in the browser editor while a desktop session is open is not coordinated yet. The website editor does not check the lease. If you edit the same project from both places at once, the next desktop open will detect the divergence and ask you to choose (see below) — but the answer is either/or, not a merge. Pick one editor per project per sitting.

When Both Sides Changed#

If the cloud copy changed while you also have unsynced local edits (usually: someone edited in the browser editor while your desktop was offline), the next desktop open stops and asks:

There is no silent merging — the Studio always asks before either side loses anything.

When the Sync Holds Back Deletions#

The sync deletes a row from the cloud copy when you delete it locally. If your local copy ever loses rows by accident — most often because a damaged local store was repaired automatically and came back empty or out of date — that rule would delete them from the cloud as well. To stop that, the sync refuses to delete from the cloud when:

Everything else keeps syncing: your new and changed rows still go up. Only the deletions wait.

The next time you open the project, Studio shows Cloud sync held back deletions, listing each table and how many rows it kept:

• Small deletes are never held. Removing a few quests or a handful of items syncs as normal.
• Approving applies once. If the same table later loses more than half its rows again, you'll be asked again.

Offline Work#

If you're offline (or the service is unreachable), an already-downloaded hosted project still opens and is fully editable. Your changes sync automatically the next time you open it with a connection. The log notes when a session runs offline.

Gotchas#

• The first open on a new machine needs a connection — there's no local copy yet to fall back to.
• Publish uses your local content. Publishing to your live server pushes what your editor sees — the local copy. If you just edited in the browser editor, open the project on desktop first so the check can pull those changes in.
• Playtest characters stay local. Playtesting a hosted project on desktop runs a local game server with its own store; test characters don't sync to the cloud database.
• Live collaboration and local-first are mutually exclusive. Real-time co-editing (browser editor collab rooms) needs everyone on the same database; desktop local-first trades that for speed and offline capability.
• Escape hatch: set cloudLocalFirst to false in the desktop Studio settings file to restore the old direct-to-cloud behavior for hosted projects.