Cloud Project Sync

What cloud project sync is#

Every game on your Vastopia account can carry one cloud save of its project: a zip of the editable source, stored by the platform against the game's id. The editor uploads it when you ask (Project ▸ Save Project to Cloud) and automatically after every successful publish, and the project hub offers to download it on any machine where the project does not exist yet.

It is a continuity feature, not a backup history and not a collaboration tool:

• There is exactly one archive per game, and the latest save wins. Saving replaces the previous archive; there is no version list and no way to restore an older one.
• It is tied to the game's owner. Only the account that owns the game can save or download its source.
• It is separate from builds. A build (the PCK, server data and config you push to test or live) is what players run; the cloud save is the project folder you edit. Builds keep their own history, see Builds and versions.

When to use it#

• A second machine. Work at a desk, sign in on a laptop, download the game from the hub and continue. Save to the cloud before you leave the first machine.
• A fresh install. After reinstalling the editor or wiping a drive, your games reappear on the hub's Games tab with their cloud saves ready to download.
• A known-good checkpoint. Publishing saves the project automatically, so the cloud copy is always at least as recent as your last pushed build.

Save a project to the cloud#

Requirements: you are signed in to the editor, a project is open, and the project is linked to a platform game ([platform] game_id in project.vastopia, which every project created in the editor has). If the game only exists locally and has never been published, the save registers it on your account first, so the game then shows up on the hub's Games tab.

1. Save your work. The command flushes the open project to disk before packing, but it is worth having every map and data tab clean first.
2. Choose Project ▸ Save Project to Cloud.
3. Watch the progress text: "Packing project…", "Uploading N MB…", "Finalizing…".
4. A Save Project to Cloud dialog reports "Project saved to the cloud. Sign in on any machine and it will appear on the project menu, ready to download." or "Cloud save failed: ..." with the reason.

Common failure messages:

Automatic save after publishing#

Every successful publish ends with a cloud save of the project source. It is best-effort: if the save fails, the publish is still complete and the failure is only logged. See Push to Test for the publish flow itself.

What the archive contains#

The zip is built outside the project (in the editor's own user data), so it can never pack itself. It holds:

• Every top-level folder of the project except packs/ and anything dot-prefixed (.export_cache/, .vastopia_upload/, .godot/, .git/, ...).
• Every root file except: files starting with an underscore (the publish pipeline's scratch such as _upload.pck, _server_package.zip, _build_manifest.json, _upload_state.json), any .pck or .zip, and temp or backup files (.bak, .tmp, .old, .orig, .import, .uid, editor swap files and dotfiles).

So assets/, server/, project.vastopia, game_config.json, prop_library.json and interface_library.json are all in; build output and caches are out. This is the same shape as Project ▸ Export as Template..., which is what a download has to be able to restore.

Download a project on another machine#

Cloud saves surface in the project hub, the screen the editor opens before a project is loaded.

1. Sign in. The hub fetches the games on your account; while it does, the Home tab shows "Checking your account…".
2. Find the game:
   • On Home, games with no local folder are listed under From your account, below Continue where you left off.
   • On Games, every account game is grouped by state as Published, Archived or Development; local ones open, cloud-only ones download.
   • The card's status line tells you which you have: "Cloud save · 2026-08-15" (or "Cloud save available"), versus "No cloud save".
3. Click the card, or open its menu (the ••• button or right-click) and choose Download and Open. The Downloading Project overlay shows "Fetching cloud save for <name>…", then download progress, "Verifying…" and "Extracting…".
4. The project opens as soon as extraction finishes. From then on it is an ordinary local project and appears under Recents.

A game card whose status says "No cloud save" cannot be downloaded. Clicking it explains: "'<name>' has no cloud save yet. Open the project on the machine that has it and use Project > Save Project to Cloud (publishing also saves it automatically). It will then be downloadable here."

Where the download lands#

The project is extracted into your projects folder (Documents/VastopiaProjects/) in a fresh directory named after the game. The editor never extracts over an existing folder: if my-game/ already exists there, the download becomes my-game_2/, then my-game_3/, and so on. Any stale local copy is left untouched beside it.

After extraction the editor:

• Re-stamps [platform] game_id in the downloaded project.vastopia so the copy is linked to the same game.
• Re-stamps the machine-specific [server] project_path and [client] project_path with this machine's source checkouts (from Settings ▸ Editor ▸ Source Checkouts), since the paths from the other machine would be meaningless here.
• Records the game-to-folder link so the hub knows this game now lives on this device.

If the archive is missing its project.vastopia, the folder is removed again and you are told to re-save from the original machine.

What is not synced#

With AI (MCP)#

There is no MCP tool for cloud project saves; use Project ▸ Save Project to Cloud in the editor or let a publish do it. register_game links a project to a platform game, which is the prerequisite for a cloud save, and get_project_config shows the [platform] game_id the save is keyed on.