What a theme contains

Three kinds of asset

A theme is a set of picks in three families. Materials dress surfaces, props are objects placed on the city, and elements are the facade modules that buildings are assembled from. Everything the Design module lets you change is one of the three, or a rule about where they go.

The Design column is not tabbed. Under the selection header it stacks collapsible sections, in a fixed order: the per-mode dressing parameters, then Materials, then Props, then Surface details. Two of the three families have a section of their own; elements do not — they are chosen by the theme and placed by the dress, not picked one at a time.

Where a theme lives on disk

A theme is not stored in your .blend. It is four things in the project folder under Documents/iCity 2, and they travel together: the three ways of getting a theme all move exactly this set.

Documents/iCity 2/<project>/
    assets.json          the theme's picks
    outputs.csv          the point data - required
    outputs.usd          the dressed geometry
    send/                what was sent to produce them
    dress/               legacy, from builds before 2026-08-15; nothing reads it
    city_state.v1.txt    the city itself (Draft)
    project.json         the server id, nothing else
    README.md            the project name and description

Append from a project copies those four into the active project, overwriting what is there. It is a copy, never a link, so the source project can later be deleted or re-generated without breaking this one; and send/ is replaced whole, so a textures folder from the previous theme cannot survive under the new assets.json.

The picks are not the files

assets.json names assets; it does not contain them. The model and texture files live in your Library Folder, and a pick is a category, an asset id and a seed id that point into it. The theme bundled with the addon, for instance, names 54 materials in 10 categories, 21 props in 20 categories and 73 elements in 11 size categories — in a file of about 130 KB.

"props": {
  "bench": {
    "count": 1,
    "assets": [
      {
        "name": "Limestone plinth bench with timber slats",
        "asset_id": "6c29193c-737b-51ed-b123-d1cdac2f4043",
        "seed_id": "d8559910-92a2-5e61-99e2-8735d35dbc89",
        "s3_path": "props/bench/6c29193c-.../d8559910-...",
        "file_format": "glb"
      }
    ]
  }
}

The library on disk is filed the same way, by category then asset then seed: materials/<category>/<asset id>/<seed id>/ for a material's maps, elements/<CATEGORY>/<asset id>/<seed id>/model.glb for a facade module. The s3_path above is the server's own key and does not always spell the same thing — it can carry an extra level and lowercase the category — so the linker tries it first and falls back to the layout the downloader actually writes. The Library Folder preference decides where that tree sits; left empty, iCity uses its default location. See Where assets live.

How a theme covers a surface

Nothing in a theme is addressed to one object. Everything is addressed to a category, and the dress joins categories to the city.

Materials go through a slot table in assets.json. A slot is a surface the baked city carries — Asphalt, Sidewalk, Roof, element:Primary_Wall — and each slot names the library category it draws from and how it picks within it.

Elements are addressed by a category name that is a size: <TYPE>_<width>_<height>, where the type is BASE, MID, TOP, CROWN or COLUMN and the numbers are metres — a module 3 m wide and 3.5 m tall is MID_3_3.5. Some categories carry a y where a height would be, for a module whose height is not fixed. The facade system fills a building's cells from the categories the theme covers, so a theme that has no module of a given size leaves those cells to whatever else fits.

Props are addressed by category too, and where a category may go is a separate question. The addon's placement taxonomy carries 27 entries — Road surface, Sidewalk path, Roof edge, Walls, Courtyard, Park path, Block boundary and so on — each scoped to the kind of element it sits on: a road, a building, a lot or yard, a park, a block. A prop system binds one category to one placement, and every asset in that category rides the same binding; there is no per-asset placement setting. Not every entry has a producer yet, so the picker offers only the placements the linker actually built a group for. Placements are covered on Props and placements.

What dressed means

Dressing is two operations, and they fail separately on purpose. First the outputs are imported: outputs.usd becomes geometry in the scene and outputs.csv becomes one point cloud per source, with every column kept as a point attribute. Then the linker runs its ladder over what landed.

Dressed objects are not left in a bin of their own. Each one carries the collection path the engine gave it and is filed into the city tree beside the draft it dresses — for example iCity2/Blocks/Block_0/Buildings_0, which resolves to the iCity 2 root collection. A draft object is hidden only once a dressed replacement for that same object exists; nothing is deleted, and hiding is reversible.

Whether those assets become real data in your .blend or stay as links into a local bank is the linker's decision, not yours. An element family the bank does not yet hold is appended — real meshes and materials in the file — and the file grows accordingly: 457 MB was measured against a 456 MB element cache. Once the bank covers every family the city needs, the next session links them instead and the same file measures about 1 MB, keeping saves and autosaves off half a gigabyte of assets that never change. A fully dressed city has been measured near 1 GB.

One theme at a time

A project holds one theme. There is no list of themes to switch between inside a project: taking a new one — the default, a generated one, or another project's — overwrites assets.json, outputs.csv, outputs.usd and send/ together, because a half-old, half-new pair would not link.

• —Start with default theme copies the theme bundled inside the addon into the project and dresses from it. No cloud job.
• —Generate theme runs the cloud pipeline: roughly 220–275 credits and about 20 minutes. The composer's own on-screen estimate of ~219 credits runs low.
• —Append from a project takes the four files from another project on this machine. Only projects that already have an outputs.csv are offered.

Within a theme you can still change individual picks — pin a different material to a category, add a prop system, regenerate one asset — and those choices stick for later dresses. See Themes, Materials and Generating a theme.

Editing the draft afterwards does not change the theme; it re-dresses the city with the theme you already have. That is a different, much smaller cloud job, described on Re-dressing after a change, and what you get back is described on After a dress.