Where your assets live

One store per machine

Everything iCity generates or downloads for you lands in one folder, the Library Folder. It is a single store for the whole machine, not a per-project one: every project you open reads the same library, and an asset generated for one city is available to the next.

The library is not part of your project and not part of your .blend. Project folders hold the city, the theme picks and the dress output; the library holds the asset files those picks point at. Your city itself lives in the engine rather than in the .blend — see How iCity fits with Blender.

You reach the setting in Edit → Preferences → Add-ons, expand iCity 2, and look for the Paths box. It holds two folder settings that pull in opposite directions, and they are the thing people mix up.

If you are looking for the folder you point at your own materials and props, it is the second one — see Using your own assets. Nothing on this page moves or touches your own folders.

Where the library actually is

Library Folder is empty out of the box, and its help text says only “Leave empty for the default location”. It does not print the path, because the addon does not resolve it: the default location is worked out by the engine binaries, which the addon and the engine process both call so the two can never disagree.

In the shipped Windows build that resolver puts the library under your local application data, beside the folders iCity uses for logs, cache and scratch space. The library is kept out of the cache folder deliberately — it is durable data, and cleanup tools treat anything called a cache as disposable.

%LOCALAPPDATA%\iCity2\
  library\      the Library Folder - durable, this page
  cache\        engine state
  logs\         addon and engine logs
  tmp\          job scratch
  run\          lock markers

Two places in the interface tell you the resolved path rather than a convention. The greyed Logs: line at the bottom of the same Paths box prints the log folder, and the library sits beside it. The asset browser prints the library path outright when it has nothing to offer: its hint line names the folder layout to add assets under, then library: and the folder itself.

If the engine binaries cannot load, the resolver has nothing to answer with: the Logs line reads “Logs: unavailable (engine binaries missing?)” and the asset browser says the library folder is unavailable. That is an installation problem rather than a paths problem — see Installing iCity 2.

What lands in it, and when

A cloud job writes into the library when it completes. Every asset the job produced is downloaded into its own folder and appears in the asset browser from there. That is true of a whole theme, of a single material or prop, and of a model or PBR pass that finishes an existing asset — see What runs in the cloud.

The layout mirrors the server's, so an asset's folder can be worked out from its type, category and identity alone. Materials, props and elements each get a subtree; the category is the next level, then the asset, then the seed.

library\
  materials\<category>\<asset id>\<seed id>\
      config.json      the generation config, verbatim
      seed.json        identity: asset, seed, type, name, category, themes
      basecolor.png  normal.png  roughness.png  ...
  props\<category>\<asset id>\<seed id>\
      config.json  seed.json  preview.png  model.glb
  elements\<SLOT CODE>\<asset id>\<seed id>\
      config.json  seed.json  model.glb
  themes\<theme id>\<seed id>\

The category level is spelled the way the cloud registers it, not the way it is displayed: lowercase, spaces turned into underscores, so Market Signs is the folder market_signs. Elements are the exception — their category is the facade slot code, and it is written on disk exactly as the slot is named. A material seed carries no preview.png: its basecolor.png is the card image.

Two consequences of that layout are worth knowing before the folder gets large.

• —A seed is a folder, and new seeds sit beside old ones. Regenerating an asset does not replace it; the new seed lands as a sibling and the browser shows “more · N” on the card. Re-downloading the same seed overwrites its own folder in place, so nothing accumulates twice.
• —What you already hold is not fetched again. When a job assigns an asset your library already has, no files are shipped for it, and the log says how many assets were assigned from the local library rather than downloaded.

So the library grows with every job you run, and it grows fastest with materials, which carry full texture sets. Nothing prunes it: no part of the addon deletes from the library except the one-time move described below.

Telling library assets from your own

Both stores feed the same asset browser, and the library is read first. When you select an asset, the footer names it, its category, and whether it came from Library or Custom.

The difference is not cosmetic. A library asset was generated in the cloud and carries a cloud identity; an asset read from your own folder has none. Starring, grouping and regenerating all need that identity, so they work on library assets only — the browser answers “This is a local asset” when there is no cloud identity to act on. See Browsing, starring and groups.

Moving the library

Point Library Folder at a new location when the default drive is filling up. Changing the field does not move a single file on its own; it changes where the next download lands. Bringing the existing assets across is a separate, deliberate press.

1. In Edit → Preferences → Add-ons → iCity 2, in the Paths box, set Library Folder to the new folder.
2. A Sync button appears beside the field. It is shown only while a previous location is recorded and still exists on disk, so it doubles as your confirmation that iCity knows where the old assets are.

   where-assets-live-sync-button.png

   Close crop of the Library Folder row in the addon preferences immediately after the field has been pointed at a new folder, with the Sync button and its refresh icon visible at the right-hand end of the row.

   /docs-shots/blender/

3. Press Sync. The status line reads “Syncing the library in the background…” and the work starts on a background thread.
4. Wait for the console line [iCity2] library moved: with the old and new paths. That is the only completion signal.

Pressing Sync with nothing recorded reports “Nothing to sync.”, and pressing it when the two locations are the same reports “The library is already at this location.” Clearing the field drops the override and puts the library back at the default location — which again moves nothing, so clear it and press Sync if you want the files to follow.

The relocation is recorded outside Blender as well, in %APPDATA%\iCity2\library.json, because the download and scan work runs off the main thread where Blender preferences cannot be read. You do not need to edit that file: the preference field is the authority in a live session and rewrites it.

When the library points at the wrong place

A dress resolves every asset a theme names against this machine's library. If the folder it resolves is empty, or is not the one holding that theme's assets, the dress still runs: the sockets bind, the collections come up empty, and the city stays undressed. The report for that step is where you see it — it counts the assets it resolved and then how many are present on this machine, and a count of zero present is the symptom.

Three things to check, in this order.

• —The theme has actually been downloaded on this machine. A project opened from Parametra carries its picks, not the asset files; the library is per machine and is not uploaded with the project.
• —Library Folder is either empty or points at a folder that really holds materials, props and elements. The dress does not take a path on trust: it collects every candidate root it can see and picks the first that looks like a library — an assets.json beside it, or a props subtree inside it. A folder you pointed at that holds neither is passed over for one that does.
• —You did not change the folder and skip the Sync press, leaving the assets at the old location.

If the theme is short of a few assets rather than missing entirely, that is a different problem with its own page — see Filling the gaps. For anything else, Troubleshooting.