How iCity fits with Blender

Two programs, not one

Installing iCity 2 gives you a Blender addon and a second program that ships inside it: bin/windows/iCity2App.exe, called the engine. The engine owns your city — the road graph, the regions, the lots, the buildings and every parameter behind them. Blender draws what the engine sends back and hosts the interface.

That split is the single fact this manual is built on. Your city is not your .blend. The objects in your scene are a picture of the city the engine is holding, and they are only editable while that engine is running.

While the engine is stopped, in the Draft module:

• —Every mode except Graph shows The iCity engine is not running. Start it to edit your city.
• —The selection gizmos are gone, so clicking a road or a lot picks nothing.
• —D, G, Del and the status-bar hints do nothing.
• —A draw tool that does get a stroke through reports engine busy or not running — nothing generated, and the stroke is lost rather than queued.

The Design module is deliberately not gated on the engine. Dressing acts on geometry that is already in the scene, so a dressed city outlives the engine session that produced it: materials, props and details stay editable with the engine stopped.

Starting and stopping the engine

1. In the Draft module, Graph mode puts the start button along the bottom of the iCity Editor. Every other Draft mode puts the same button in the middle of the panel, under the message.

   how-it-fits-blender-start-button-graph.png

   Crop of the iCity Editor footer in Draft, Graph mode, with the engine stopped and a mesh assigned as the graph, so the full-width button reads 'Start Engine'.

   /docs-shots/blender/

2. The button reads Start Engine when a mesh is assigned as the graph, and Start with default scene when none is — that second one builds a default city so the engine comes up with something in it.
3. Once it is running, an engine button appears in the iCity Editor header, beside the sync controls. Its tooltip reads Stop the iCity Core engine. It is hidden while the engine is stopped.

   how-it-fits-blender-engine-header-button.png

   Crop of the iCity Editor header with the engine running, hovering the engine button beside the sync controls so its tooltip 'Stop the iCity Core engine' is shown. The header's project name and sync controls should stay in frame for context.

   /docs-shots/blender/

Opening a project starts the engine for you, on that project's saved city. Closing a project stops it and clears the city from the scene. Quitting Blender, disabling the addon and reinstalling all stop it too — the addon makes sure the engine never outlives Blender, because a stray iCity2App.exe holds its own files open and breaks the next install.

If the engine dies unexpectedly it restarts itself and reloads your saved city, up to three times. The iCity Logs editor records Engine crashed — restart attempt 1/3 each time. After the third it gives up with Restart budget exhausted (3 attempts) — engine stopped and leaves itself off; pressing Start again is what brings it back. If it will not start at all, see Troubleshooting.

What is saved where

There are two places your work can land, and two different buttons that put it there. Neither one covers the other.

The project folder is the one that matters, and it sits under your Documents:

Documents/iCity 2/<project name>/
  README.md           the project's name and description
  city_state.v1.txt   the editable city — what the engine reloads
  project.json        the project's id on Parametra
  assets.json         the theme's material and prop picks
  outputs.csv         the dressed city's point data
  outputs.usd         the dressed city's geometry
  send/               what was sent to the cloud to produce them

The header S button can only write a city the engine has already flushed. Press it before the engine has produced one and nothing is written; the addon says so in the console and in the log, not in a dialog, with Nothing to save yet — the engine has not written a city state. The close dialog refuses to close on that message rather than discarding the work.

What happens when you reopen a .blend

Nothing opens by itself. On file load the addon tries to restore your sign-in from the saved token and stops there — no project is created and no city state is restored. The header shows Untitled until you start the engine or open a project.

The objects saved in the file are still in the scene, so the editor shows the workspace rather than the launch screen; it will not hide existing work behind a start page. What you are looking at is geometry, not a city. Draft has nothing to edit, because the engine has nothing loaded.

If the file you opened holds no initialised project, the addon also drops its cached city state. That is on purpose: without it, starting the engine in a fresh file would rebuild the last city from a different file entirely.

Open Project is what brings a city back. With no project open the header shows a + and an O pair; O is Open a project folder — restores its saved city state. Opening copies city_state.v1.txt back into place, restarts the engine so it loads it, re-applies the project's assets.json onto the Design cards, and links outputs.csv if the project has been dressed. See What a project is.

Undo does not cross the line

Ctrl+Z rewinds the engine's city only when your most recent action was an iCity edit. After any plain Blender action — a transform, a delete, a material tweak — the key goes back to Blender's own undo stack. It also falls through while a drag or a draw stroke is still open, and while a mesh is in Edit Mode.

An iCity edit never pushes a Blender undo step. Blender's undo therefore cannot bring back a road you deleted, and a Blender undo that rewinds past engine-emitted objects makes the engine re-send them rather than restoring them from the file. Deletion is meant to be permanent: the confirmation says a regenerate will not bring it back.

Dressing is different again. The linker suspends Blender's global undo while it imports a dress and restores it afterwards, because each snapshot of a several-hundred-megabyte file costs close to a second and a single dress makes dozens of them. A dress is derived data: you re-dress rather than undo. See Re-dressing after a change and What survives a re-dress.

The habit to build

1. Start the engine before you expect any Draft tool to respond. If the rail is empty, that is the answer.
2. Press header S whenever you would press Ctrl+S. S saves the city; Ctrl+S saves the file. Do both when the city is dressed and you want the meshes in the .blend.
3. Press the footer Sync button, with a message, when you want the project on Parametra. Nothing uploads on its own.
4. Next session, use Open Project. Reopening the .blend on its own gives you the meshes and no city.