Create, open, close

The launch screen

With no project open and nothing in the scene, the iCity Editor shows the launch screen instead of the workspace. It is a single bar of three controls over a card of recent projects, and every way into a project starts here.

The wide button is New Project. The cloud icon beside it opens a project from Parametra, including ones shared with you. The last button, the ellipsis, opens a folder browser so you can point Blender at a project folder that is already on this machine.

The card under the bar lists up to four recent projects, newest first, by the time the folder was last touched. Each row shows the project name on the left and the time and date on the right; clicking a row opens it. With nothing on disk yet the card is replaced by the line “No projects yet — your work will live here.”

Create a project

New Project replaces the launch screen with a form. Its own subtitle states the rule the rest of the manual depends on: the project is the container of your work, and every generated resource belongs to it.

1. Type a Project name. This is the only required field. Press Create with it empty and the form answers “Give the project a name first.” in red and does nothing else.
2. Optionally fill in Description — what the city is about, style, mood, references. It is written into the project’s README.md and read back the next time you open the folder.
3. If you are an admin or owner of an organization, tick Organization project to make it one: everyone in your organization sees it, and its admins choose who can open it. The checkbox is not drawn for anyone else. See Organizations.
4. Click Create. Cancel goes back to the launch screen without creating anything.

The screen closes onto the guided start screen and the project name appears in the header. The Logs editor records the line Project '<name>' created with the folder path, and a second line saying whether the project was registered on Parametra.

What Create writes

Two things happen. A folder is made under your projects root, and the project is registered on Parametra so it has an id.

Documents/iCity 2/<name>/
  README.md      the name as a heading, your description, the creation date
  project.json   the server id, and nothing else

Characters Windows forbids in a folder name are stripped out of the folder name. If a folder of that name already exists on disk, the new one is given a (2) suffix, then (3), and so on — an existing project is never written into.

project.json is written only when the server issues an id. Create a project while signed out, or with a name your account has already used, and you get the folder and the README and nothing more. That is a state the footer shows you rather than hides: a red ! appears at the right-hand end, beside the version flag, and clicking it opens the dialog that finishes the registration. Nothing is silently adopted. Signed out, the footer also replaces its green sync button with a second red ! at the left end — that one says “sync is paused. Click to sign in.” and starts the sign-in.

The default theme checkbox

The form ends with Start with the default theme, ticked by default. The checkbox records your answer and nothing in the addon reads it back yet. Whether you leave it ticked or untick it, a project created here comes up undressed.

The button that does the work has the same name and lives in the Design module: on the Theme tab, press Start with default theme and the addon copies its bundled theme files into your project and dresses the city from them. That is the working path, and it is one click away once you have a city. See Themes.

Open a project

There are three ways in, and they all end in the same code.

• —A row in the recent projects card on the launch screen.
• —The ellipsis button, which opens Blender’s folder browser already pointed at Documents/iCity 2. Pick the project’s folder, not a file inside it.
• —The cloud button, which lists what is on Parametra, downloads the folder, and then opens it exactly like a local one. See Opening from Parametra.

Opening runs a fixed sequence, most of which you see rather than trigger:

1. The work session on the project you are leaving is closed, and a new one is opened on this project as soon as its id is known.
2. The name comes from the folder, the description from README.md, the id from project.json, and the version number from the server.
3. The previous project’s design state is cleared — material and prop picks, scatter systems, presets — and this project’s assets.json is applied to the Design cards in its place.
4. The saved city state is copied back out of the folder, and the engine is restarted so that it loads it. The engine only reads a city state when it starts, which is why opening a project restarts it. A folder with no saved city in it skips this step entirely — the log says so and the engine is left alone.
5. About two and a half seconds later, if the project holds an outputs.csv, the dress is linked on top: you get the city as it was dressed, not a grey shell of it.

A project you have just opened is marked clean even though the engine has run, because what is on screen is what was saved.

With a project open, the header pair reads S (save) and X (close), and the label beside them shows the project name and version. A trailing asterisk means the city has changes that have not been written into the folder. With no project open the same pair reads + (new) and O (open).

Close a project

The footer X opens the CLOSE PROJECT dialog. It asks “Close '<name>'?” and then states what closing does: the city is cleared from the scene, and the project folder stays where it is. If there are unsaved changes it says so first.

The checkbox above the row, Open another project after closing, brings up the folder browser the moment this project lets go.

Whichever of the two closing buttons you press, the same things happen:

• —The engine is stopped.
• —Every object and collection the addon owns is freed — the city is gone from the scene.
• —The cached city state is dropped, so restarting the engine cannot bring the city back on its own.
• —The project folder is untouched. Nothing on disk is deleted, ever, by closing.

Save & close can decline to close. If the engine has not written a city state yet there is nothing to save, and closing anyway would be the data loss the button exists to prevent — so the project stays open and the Logs editor gets the line “Nothing to save yet — the engine has not written a city state. The project stays open.” Watch the log rather than the dialog, because the dialog itself says nothing.

One project per Blender session

The active project belongs to the Blender session that holds it, not to the machine. Two copies of Blender running side by side each hold their own project, and opening a second project in one of them does not disturb the other.

Quitting Blender banks the live city into the active project folder automatically and closes the work session on the server. You do not have to press S first, though nothing stops you.

What Create, Open and Close do not touch is the upload. Sending the folder to Parametra is a separate, manual act with a message attached — see Save, sync, version.