Saving, syncing, versioning
Save writes your city to disk. Sync uploads the project folder to Parametra with a message. A version cuts a numbered branch the project then continues on. They are three different buttons, and none of the three happens by itself.
Three verbs, three buttons
Save, Sync and Version sound like the same act. They are three separate buttons doing three separate things, and only one of them puts your work somewhere other than this machine.
There is a fourth control wearing the same refresh glyph: City sync, up in the header beside the Draft/Design toggle. That one re-dresses the city and has nothing to do with the project folder. It is the only one of the four that spends credits, and the only one that is genuinely automatic.
The whole iCity Editor area with a project open and signed in, framed so the header and the footer are both in shot: in the header, the paired [sync | ▾] City sync control beside the Draft/Design toggle and, at the right end, the S and X buttons with the label 'Project: <name> v1.0'; in the footer, the refresh/sync icon and project name at the left end and the flag and X buttons at the right end. Nothing hovered, no dialog open.
Your city is not your .blend. It lives in the engine process and is written to Documents/iCity 2/<project> by the header S button; Blender's own save and undo do not reach it. See How iCity fits with Blender.
Save — the header S button
With a project open, the header's top-right cluster shows S and X. S writes the current city state into the project folder as city_state.v1.txt. Nothing is uploaded and no credits are spent.
The project name carries an asterisk while there is something to save. It appears as soon as the engine runs over an open project, and it is cleared by Save, by a Sync, by Close, and by a theme generation (which force-saves the project before it submits).
Project: Harbour v1.0 *
Close crop of the right-hand end of the iCity Editor header with a project open and the engine running, captured after an edit but before pressing S, so the label reads 'Project: Harbour v1.0 *' with the trailing asterisk clearly visible next to the S and X icon buttons. Hover S so its tooltip shows.
The Close dialog's Save & close runs exactly the same save, then clears the city from the scene. Quitting Blender banks the live city into the active project folder on its own, so a normal exit does not lose the city.
If the engine has not written a city state yet, Save writes nothing. The header button says so only in the system console. Save & close reports it in the Logs editor — “Nothing to save yet — the engine has not written a city state. The project stays open” — and refuses to close.
Sync — the footer refresh button
A sync is a commit. It uploads the project folder to Parametra and records what moved under the version you are on, so the version is the branch and the syncs are its history. It costs no credits.
- Click the refresh button in the bottom-left of the footer. The SYNC dialog opens, titled with the project name.
- Type into What did you do? The label names the version the entry lands in, for example “(goes into v1.0's history)”.save-sync-version-sync-dialog.png
The SYNC popup over the 3D viewport on a signed-in project that can sync: the title bar reading 'SYNC — <project name>', the 'What did you do?' label with '(goes into v1.0's history)' beside it, one sentence typed into the message box, and the Cancel / Sync button pair. No red error text.
/docs-shots/blender/The SYNC dialog, with a message typed and the version it lands in named above the box. - Press Sync. If the sync cannot start, the reason appears in red in the dialog and the dialog stays open.
The sync first copies the live city into the folder, so you do not have to press S before syncing. It then sends a list of every file with its size and checksum; the server compares that against what it already holds and hands back an upload slot only for what is new or changed. A sync where nothing changed uploads nothing.
Some files are never uploaded:
- —
project.json— the server owns the project id, so it is never sent back. - —The checkout marker that records which version this folder is standing on.
- —
.blend1,.blend2,.tmpand.partfiles. - —Any single file over 200 MB. That one is reported in the system console only.
The Logs editor names what moved when it is done, counting files and listing the first few by name.
Synced (from you asked) — 1 new (assets.json); 2 changed (city_state.v1.txt, outputs.csv) Synced — nothing had changed.
The asterisk clears and the last-synced time is stamped only when every upload landed. If some failed, the log says Sync incomplete with the counts and the project stays marked.
Nothing uploads on its own. There is no timer and no automatic project sync; the internal request path that other parts of the addon once used to arm one is a deliberate no-op, and there is no Auto/Manual arrow beside the footer sync button. The Sync button is the only thing that ever uploads a project.
Closing Blender banks the city into the folder on your disk. It does not upload it. If this machine is lost between one Sync and the next, so is everything since.
The other sync, in the header
City sync is the paired [sync | ▾] control in the header, left of the Draft/Design toggle. It re-dresses the city from the current draft using the theme you already have — it does not touch the project folder and it does not upload anything for safekeeping.
It is set to Auto by default. With Auto on, changing the draft and returning to Design fires a re-dress about two seconds after things settle. It refuses when nothing has changed and when no dress exists yet, and it spends credits every time it runs. The ▾ beside it switches to Manual, where it only runs when you press the button.
Close crop of the iCity Editor header, left of the Draft/Design toggle, in Design with a dressed city: the paired [sync | ▾] City sync control with the ▾ menu dropped open showing the Auto and Manual entries and Auto ticked. Frame wide enough that the Draft/Design toggle is visible beside it, so the reader can tell this is the header pair and not the footer button.
Two switches, the same glyph, opposite truths: City sync runs by itself, Project sync never does. Re-dressing is covered in Re-dressing after a change.
Versions — the footer flag button
A version is a numbered branch: major.minor, cut on the server, starting from where you are now. The project keeps going on the new number, and the syncs you make from then on land in its history.
- Click the flag button in the footer, left of the X. The dialog opens titled <PROJECT> VERSIONS and lists the versions the server holds.
- Fill in Name this version — a short name for this line of work, such as “Harbour redesign” — and, if you want, a Description.
- Check the two number boxes. The dialog offers the next number the server will accept; the + and − steppers change it, and the − disappears when a number is already as low as it can go.save-sync-version-versions-dialog.png
The '<PROJECT> VERSIONS' popup over the 3D viewport on a project that already has at least three versions: the list of version rows at the top, the 'Name this version' box with 'Harbour redesign' typed in, the Description box, the two number boxes with their + and − steppers showing the next number the server will accept, and the Create version button. Capture while standing on the latest version.
/docs-shots/blender/The versions dialog: the list the server holds above, the new version being named below. - Press Create version. The header and footer switch to the new number straight away.
Creating a version uploads nothing and reloads nothing. The server forks the new version from the files already under the current one, and the city on screen is already the city the new version starts from. Sync afterwards to put newer work on it.
A new version can never be numbered below the current one. Type a lower number and the dialog corrects it and says so: “A new version cannot be lower than 2.0.”
Opening an older version
Each row in the versions list carries its number, its date and its message. The one you are on reads v1.0 · you are here; every other row has an Open button that replaces this folder with that version.
Close crop of the list at the top of the '<PROJECT> VERSIONS' popup on a project with at least four versions, standing on v1.0 rather than the newest: each row showing its number, date and message, the v1.0 row reading 'v1.0 · you are here' with no button, and every other row carrying an Open button.
There is one folder per project, whichever version it holds — nothing is copied aside. The files come down, the folder's contents are replaced, and the project reopens on them, so the city on screen is the one on disk.
A folder standing on anything but the latest version is marked read-only, and Sync refuses it outright:
this folder is showing version 1.0, so it is read-only — open the latest version to make changes
That is deliberate: syncing an old checkout would push older files over the newest work. To get back, open the versions dialog and press Open on the latest row.
Sync before you open an older version. The folder's contents are replaced, and anything that was only on this machine is gone with them.
When Sync refuses
The reason is shown in red inside the SYNC dialog, and the footer says what it can from across the room.
Close crop of the left end of the iCity Editor footer with a project open while signed out, so the sync button is replaced by a red '!'. Hover it so the tooltip 'This project needs server access and you are not signed in — sync is paused. Click to sign in.' is showing in the same frame.
A working rhythm
Nothing here is automatic, so pick a habit and keep it.
- —Press S whenever you would press Ctrl+S in Blender. It is cheap and local.
- —Sync at the end of a working session, and before you switch versions, hand the project to someone else, or move to another machine. Write what you did — that line is the only description the history will ever have.
- —Cut a version when the work changes direction, not on a schedule. Between versions, the syncs are the history.
What each of those files in the folder actually holds is covered in What a project is.
The Discord is fastest for anything scene-specific. Email suits licensing, billing and anything needing a file attached.
Contact support →