What a project is

Two things at once

Press New Project on the launch screen, type a name and a description, then click Create. Two things happen at once.

A folder appears at Documents/iCity 2/<name> with a README.md in it, holding the name as a heading, your description, and the date. And, if you are signed in, the project is registered on Parametra, which issues an id. That id is written into project.json inside the folder, and it is the only thing that file ever holds.

Create a project while signed out and you get the first half only: a folder and a README, and nothing else. That is a normal state, not a broken one — the footer shows you it happened, and the red flag below is how you finish the job later.

The folder is named after the project, with the characters Windows forbids in a folder name removed. If a folder of that name already exists, the new one gets a (2) suffix.

Inside the folder

A project that has been saved and dressed at least once looks like this on disk.

Documents/
  iCity 2/
    Harbour District/
      README.md
      project.json
      city_state.v1.txt
      assets.json
      outputs.csv
      outputs.usd
      send/
      dress/

Each of those is written by a different part of the addon.

A brand-new project holds README.md, plus project.json if the server issued an id while you were creating it. The rest appear as they are produced: city_state.v1.txt the first time you save, assets.json and the outputs the first time a theme finishes.

The id, and the red flag in the footer

project.json is written only when the server issues an id. If it is missing, empty or unreadable, the project has no identity: it cannot be synced and it cannot be versioned.

The editor checks this at most every five seconds. If the current session still knows the id — you registered the project in this session, so it is mirrored in the scene — the file is rebuilt silently and a line goes to the log. If there is nothing to rebuild from, a red ! appears on the right of the footer, with the tooltip “This project cannot identify itself — click to fix it”.

Clicking it opens IDENTIFY PROJECT, which lists the projects on your account and offers two answers. They are opposites, and the addon will not guess between them.

• —Upload as new — create this project on the server under its current name. This is the answer for a project you made while signed out, which has never existed on the server.
• —Use this project — pick a project from the list and write its identity back into project.json. This is the answer for a folder whose project.json was lost, or whose name is already taken on your account.

Picking the wrong one either burns a duplicate name or commits versions into another project’s history, which is why the server refuses to resolve a name clash on its own: creating a project whose name is already on your account is refused, and the folder is left unregistered until you answer here. If your account has no projects yet, the dialog says so and points at Upload as new.

One project per Blender session

The active project belongs to the Blender session, not to the machine. Open two copies of Blender and each holds its own — what you create or open in one does not become active in the other.

The active project is stored on the scene, so it is saved inside the .blend. That does not make reopening the .blend reopen the project. Nothing opens on startup: no project is created and no city is restored, and the header reads Untitled until you start the engine or open a project. Loading a file that holds no project also clears the engine’s cached city, so a fresh file cannot start onto the last file’s city.

Getting your city back is Open Project — the O button in the header, which restores the saved city state from the folder before the engine starts. Your city is not your .blend; how iCity fits with Blender explains why in full.

The folder is yours

Nothing in the project folder is locked, hidden or held open. It is ordinary files in an ordinary folder under Documents, so copying it somewhere else is a backup, and you can put your own files in it.

A sync uploads everything in the folder except for a fixed list: project.json (the identity is the server’s and must not be pushed back), .icity2-checkout.json, Blender’s own .blend1 and .blend2 backups along with .tmp and .part files, any sub-folder whose name starts with a dot or a double underscore, and any single file over 200 MB, which is skipped with a line in Blender’s system console.

Closing a project clears the city from the scene and stops the engine. It does not touch the folder. The footer X asks first — Save & close writes the city into the folder and then clears it from the scene, Close without saving discards changes since the last save. The header X closes without saving. In every case the folder, and everything you had already saved into it, stays exactly where it was.

Where saving fits

Three separate verbs act on a project, and they are easy to conflate. Saving writes the live city into the folder. Syncing uploads the folder to Parametra with a message. Versioning starts a numbered branch the project then continues on.

Blender’s own Ctrl+S is none of the three. It saves the .blend, which is a different file with different contents. Saving, syncing, versioning takes the three apart one at a time.