Using your own assets

An asset is a folder

iCity reads your own materials and props straight off disk. It never writes to your folders, never moves a file and never reorganises anything — the scanner is read-only by rule.

The single thing to get right is that an asset is a folder, not a file. One folder per asset, holding the asset's picture, its texture maps or its model file, and optionally a config.json. Four map files dropped straight into materials/ are not one material with four maps; they are read as four separate materials, filed under the category General.

The folder layout

Pick a folder anywhere on disk to be your asset root. Inside it, make a materials folder, a props folder, or both. Under each, category folders. Under those, one folder per asset.

My iCity Assets/
  materials/
    Asphalt/
      Worn Asphalt/
        preview.png
        albedo.png
        normal.png
        roughness.png
        config.json
      Fresh Asphalt/
        preview.png
        albedo.png
    Concrete/
      Precast Panel/
        preview.png
        albedo.png
  props/
    Street Furniture/
      Park Bench/
        preview.png
        bench.glb
      Bollard/
        preview.png
        bollard.blend

Here Worn Asphalt is one material in the category Asphalt, and Park Bench is one prop in the category Street Furniture. Category folders may be nested, up to five levels deep — materials/Stone/Marble/Carrara/ files the asset Carrara under the category path Stone/Marble. An asset folder placed directly under materials with no category folder above it gets the category General.

A root with neither a materials nor a props folder is not ignored: iCity scans it tolerantly instead and sorts what it finds by content — folders holding images become materials, folders holding a model file become props. That is the fallback, not the contract; the split above is what keeps a prop from being filed as a material.

Inside an asset folder, these are the file types the scanner recognises.

If no preview.* is present the scanner falls back to an image named basecolor or reference, and after that to the first image in the folder alphabetically. A prop folder containing only a model file and no image gets no picture at all, so give every asset a preview.png. Entries whose name begins with a dot are skipped.

Pointing iCity at it

1. Open Edit → Preferences → Add-ons and expand iCity 2.
2. Find the Paths box.
3. Set Custom Assets Folder to your asset root — the folder that contains materials and props, not either of them.
4. For a second or third root, press Add Asset Folder and fill in the row that appears. The X beside a row removes it.

   your-own-assets-paths-box.png

   The Paths box in Edit > Preferences > Add-ons > iCity 2 with Custom Assets Folder filled in with an asset root path, one extra row added underneath it by Add Asset Folder holding a second path, the X button at the end of that extra row visible, and the Library Folder field above left empty.

   /docs-shots/blender/

There is a difference between the two path settings above, and it is worth being deliberate about which folder goes where.

Because only the primary Custom Assets Folder is passed to the engine, put your main collection there and use Add Asset Folder for the extras.

Finding them in the browser

DESIGN stacks its sections down one column — the selection card, then Materials, Props and Surface details, each a collapsible panel. There are no category tabs and no separate Open Library button in this build; the asset browser is opened from inside a section:

• —Materials shows a three-up carousel of category tiles. Clicking a tile opens the browser for that tile's category.
• —Props and Surface details show scattering system cards. The + on a card opens the browser in multi-select, over the whole library of that kind.

Either way the browser reads every root — the managed Library Folder first, then your custom roots.

The view dropdown at the top of the sidebar carries a My custom folders filter, described as “Only assets from your own custom asset folders”. It is only listed once a custom folder is configured; with none set, the entry is absent rather than dead. Select any asset and the footer names it, its category, and whether it came from Library or Custom.

An imperfection is not a third top-level folder. It is a material or a prop whose category folder is named imperfections — materials/imperfections/Rust Streak/ reaches the Surface details section.

Naming material categories

Props and imperfections take any category name you like — their browser is never locked. Materials are the exception, and the rule is worth knowing before you name a folder: the Materials carousel only shows the categories the editing mode you are in dresses, filtered down to the ones your library actually contains, and clicking a tile locks the browser to that tile. Match one of these names and your material behaves exactly like a generated one. Matching ignores case.

A category the library does not hold is dropped from the set rather than shown as an empty tile, so a mode whose whole set is missing reads “No material categories for this mode.” A folder named outside the table gets no tile of its own, and there is no material entry point in this build that browses the whole library — so a custom material only reaches a city surface under one of the names above.

What custom assets cannot do

Everything the cloud offers is keyed to an asset id, which only assets generated or downloaded through Parametra carry. A folder you assembled yourself has none, so the cloud-side controls are simply not available on it.

• —Regenerate is refused. The log reads “has no cloud identity (local/custom asset) — only cloud-downloaded assets can be regenerated”.
• —Generate Model and Generate PBR are refused for the same reason. A custom prop with no model file stays without one; a custom material with no maps stays without them.
• —There is no star on a custom asset's card, so the Starred filter always shows an empty grid while My custom folders is on. Groups and reporting are cloud-side too.
• —A prop with no model file cannot be assigned. Its card carries a warning icon whose tooltip reads “No 3D model — press to select, then Generate Model builds one from the image”, the footer repeats No 3D model while it is selected, and Assign skips it rather than assigning a stand-in plane.

The way round all of it is to supply the missing file yourself: put a .glb or .blend in the prop's folder, or the maps in the material's, and press refresh.

When nothing appears

A wrong layout is silent. The scanner does not report a folder it failed to understand — it just contributes nothing, and the browser looks the same as it did before. Work down this list.

• —The path is set to the wrong level. Custom Assets Folder wants the folder that contains materials and props. Point it at materials itself and iCity falls back to the tolerant content-based scan, which finds some of your assets and silently misfiles or drops the rest.
• —The assets are loose files. Loose files at the top of materials or props do appear — one asset per file, under General — but a loose model file cannot actually be imported when you assign it. Give every asset its own folder.
• —There is no category level. materials/<Category>/<AssetName>/ is the shape; an asset folder sitting directly under materials still appears, filed under General.
• —The nesting is deeper than five category levels. At that depth the scanner stops treating a folder as a category and reads it as an asset, so everything inside it disappears into one entry.
• —The asset folder has sub-folders but no marker. Add a preview.png or a config.json so it reads as an asset rather than a category.
• —The file extension is not one iCity reads. Images: .png .jpg .jpeg .tga .bmp .webp. Models: .blend .glb .gltf .fbx .obj.
• —The browser is filtered. The dropdown label names every filter that is live. Turn off Starred and Match editing mode, uncheck the category boxes in the sidebar, then press refresh.
• —You opened it from a material tile. That view is locked to that tile's category and nothing else, however wide you set the filters. A material filed under any other name will not be in it.

If it still will not show, the empty grid itself prints the shape it wants and where it looked. More symptoms and their causes are in Troubleshooting.