The engine

What the engine is

The engine is a separate Windows program that ships inside the addon. It is iCity2App.exe, with iCity2Client.dll beside it, in Addon/bin/windows/. Blender launches it, hands it a shared-memory channel, and reads back the meshes it produces. It runs headless — no console window opens.

The engine owns the structure of the city. The road graph, the regions, the lots, the building masses and the undo history behind them live in that process. Blender holds the geometry the engine last sent, and nothing more.

Your city is not your .blend — it lives in this process, Blender's own save and undo do not reach it, and reopening a .blend does not bring it back. See How it fits into Blender for what is saved where.

Starting it

The start button moves depending on where you are, but it is always the same operator and always says what it will do.

• —On the Start screen of an empty project, Start with default starts the engine and has it build a default city. Of the two buttons beside it, Draw road only arms the drawing tool, while an OSM import starts the engine itself when it runs.
• —In Draft, Graph mode pins the button to a bar at the foot of the editor column, because Graph is the surface you set up before starting.
• —In every other Draft mode the button sits in the middle of the column, under the words “The iCity engine is not running. Start it to edit your city.”

The label follows the graph. It reads Start Engine once a mesh is assigned as the base graph, and Start with default scene when none is — in that case the engine builds a city rather than coming up empty.

Pressing it does the following, in this order:

• —Writes your Library Folder and Custom Assets Folder preferences into the engine's own config, so the new process resolves them from its first frame.
• —Opens a fresh log session folder and attaches the log reader before the process spawns, so the startup lines are captured.
• —Passes Blender's Undo Steps preference to the engine. The engine reads it once, at start: changing the preference mid-session needs a Stop and a Start to take effect.
• —Loads the saved city state if one is in the cache — after a crash, or after Open Project restored one — whatever the preferences say.
• —With no saved state, the Build Default Graph on Start preference decides whether Start builds a default city or comes up empty. “Start with default scene” switches that preference on before it starts.

Two other actions start the engine without you asking. Open Project stops a running engine, then starts a fresh one on the city state it just restored. An OSM import starts it too, deliberately without building a default city, so the import does not land next to one you never asked for.

What needs it running

All of Draft. Every Draft affordance dispatches work to the engine, so with the engine stopped the interface does not offer them at all rather than offering handles onto nothing.

• —The tool rail is not built. Draw Road, Draw Region, Draw Lot, Draw Footprint and the rest have no buttons.
• —The selection gizmos are gone. City objects are not selectable by Blender's own click either, so the viewport is plain Blender.
• —The status bar hands its hints back to Blender — no D, G or Del prompts.
• —Every Draft mode except Graph shows “The iCity engine is not running. Start it to edit your city.” instead of its parameters.
• —A draw tool that does get a stroke through reports “engine busy or not running — nothing generated”. The stroke is lost, not queued.

Two things do not need it. Graph mode works with the engine stopped by design — assigning a mesh as the base graph, importing OSM and the References card are all setup you do first. Design is not gated on the engine either: the module toggle asks for a sign-in and a graph in the scene, and nothing else. A dressed city outlives the engine session that produced it.

Stopping it

The Stop button lives in the header's right cluster, beside the sync pair. It carries the engine glyph, its tooltip reads “Stop the iCity Core engine”, and it is only visible while the engine is running.

Stopping does not clear the scene. The meshes stay exactly where they are; what you lose is the ability to edit them procedurally. Start again and the engine reloads the saved city state and rebuilds from it.

Closing the project also stops the engine, and that one does clear the city from the scene.

When it crashes

The engine can die under you. The addon watches for it two ways — the process exiting, and the heartbeat going unanswered. An engine that misses a heartbeat while it still reports itself busy is given more checks rather than being killed on the first miss; three misses in a row is what counts as dead. What follows is automatic, and finite.

1. The addon restarts the engine and logs “Engine crashed — restart attempt 1/3”.
2. A successful restart re-loads the saved city state and regenerates the scene from it, logging “Engine restarted (attempt 1/3) — scene intact”. Your city is not lost.
3. This happens at most three times. On the next crash there is no restart: the log reads “Restart budget exhausted (3 attempts) — engine stopped” and the engine is left stopped.

   the-engine-crash-restart-log.png

   The iCity Logs editor after three failed restarts, scrolled so the whole episode is on screen: the 'Engine crashed — restart attempt 1/3' line, an 'Engine restarted (attempt 1/3) — scene intact' line, and the final red 'Restart budget exhausted (3 attempts) — engine stopped' line. The status strip at the top reading 'inactive' with restarts 3/3.

   /docs-shots/blender/

4. Draft is now inert, exactly as if you had pressed Stop. Press Start Engine again. Nothing else brings it back.

If a restart comes up but the city does not, the console says so plainly: “the engine is running but EMPTY. Stop/Start the server to reload the city.” Do that — Stop, then Start.

The Logs editor

The Logs editor is where the engine tells you what it is doing, and it is worth keeping open. In the iCity 2 workspace it sits at the bottom of the left column, under the iCity Editor. If it is not there, pick iCity Logs from any editor area's editor-type selector.

The strip along its top is the engine's state:

ENGINE  ● monitoring · restarts 0/3
Engine process — Memory 412 MB · CPU 3%

The word is the heartbeat state and the count is how much of the restart budget the current crash episode has spent — a clean start puts it back to zero. While the engine is busy on a long command the word is replaced by a cycling working… and the dot pulses, so the strip visibly lives through a long wait. The second line appears while Show system info is on, which it is by default.

Three buttons sit in the editor's own Blender header. Report opens the report form with the session log attached automatically. Settings — “Choose what the log shows” — toggles the system-info row, the Engine and Addon entry types, and Errors only / Warnings only. Clear empties the session log.

Every engine run also writes its own folder on disk, under the logs zone, holding engine.log, heartbeat.log and addon.log. The newest ten runs are kept and older ones are pruned, so a crash never destroys the run before it.

%LOCALAPPDATA%\iCity 2\logs\sessions\<timestamp>\

Antivirus, ports and second copies

The engine is an executable launched by Blender from inside the addon folder, which is a shape security software takes an interest in. If it has been quarantined or blocked, Start reports “Binary not found:” and the full path it looked at. If the process launches and exits immediately, Start reports “Core failed to start.” with whatever the process printed. Both are about the executable, not about your city — exclude iCity2App.exe and iCity2Client.dll in your security software and try again.

Signing in fails in the same shape for a different reason. The addon opens your browser and listens on http://127.0.0.1:9876/callback for the answer. If the port cannot be opened you get: “Could not open port 9876 to receive the sign-in (…). Another program may be using it, or a firewall or antivirus may be blocking Blender from listening. Close other copies of Blender and try again.” — with the operating system's own reason in the brackets. If the browser cannot reach it, you get a “page can't be reached” after your password was already accepted, which reads like a login failure and is not one.

On running two Blender windows side by side: each session tracks its own active project, and the engine serialises every command on a single city mutex — one command at a time, one city. Whether two engines can run at once on one machine is not stated anywhere in the product, so this manual does not claim it either way.