Assets and packs tools

list_asset_categories

List asset categories, with how many assets each actually holds.

Read populated — a category can exist and be empty. "Patterns" ships empty in a vanilla Dungeondraft and fills from asset packs, so choosing it by name gets you nothing and no explanation. counts gives the full picture.

Counts depend on which packs THIS MAP includes, not on what is installed. On a map that includes none, every category is core-only. See list_asset_packs.

No parameters.

list_asset_packs

Which asset packs are installed, and which this map can actually use.

Dungeondraft scopes packs per MAP: a map includes a set of packs, chosen when it was created, and list_assets only ever offers assets from those. A map that includes none sees roughly 1800 core assets however large the user's library is — which is easy to miss, because nothing fails. It just quietly builds everything from vanilla.

Check installed_but_not_in_this_map at preflight. If it is non-empty, say so before building: those assets are unreachable here, and anything placed from one would not survive a reload. get_status.asset_packs carries the same signal as two numbers.

To choose between them by what they contain, not by name, use search_pack_contents. To USE them, the map has to include them — see prepare_map_with_packs, which writes a copy of the open map that includes the packs and opens it.

No parameters.

list_assets

List asset paths in a category, optionally filtered by a case-insensitive substring.

category: e.g. 'Objects', 'Walls', 'Paths', 'Terrain', 'Lights', 'Portals', 'Roofs'.

search: substring matched against the asset path ('chair', 'door', 'grass'). Pass a returned path, verbatim, as the 'asset' of the create tools.

searches: up to 8 terms in one call instead of search — tables AND chairs AND barrels. More than 8 is refused; split the call. Results come back under results, keyed by term. Terms SHARE a budget of 80 paths, reported as per_term_limit, so this is for choosing a handful, not reading the catalogue. Pass searches or search, not both.

Results depend on the packs THIS MAP includes: none gives the ~1800 core assets, a full library over a hundred thousand. If a search comes up thin, search_pack_contents before concluding an asset does not exist.

colorable lists INDEXES into assets of assets with a colour mask: they take color at placement, and the mask shows red without one. Colour cannot be changed afterwards — check before choosing. colorable_scanned false means the result was too large to scan: narrow the search.

match_mode: 'substring' (default, contiguous); 'tokens' (every word appears anywhere, any order: "table round" finds round_table_01); 'fuzzy' (tokens plus resemblance, so "barrle" lands; ranked, with scores). min_score is the 0..1 cutoff for 'fuzzy'. None of these understand meaning — "mug" will not find a tankard — so widen a term or list the category before concluding something is absent.

vanilla_only: exclude optional packs, when native assets would otherwise be crowded out of the result page.

search_pack_contents

Search INSIDE every installed asset pack, including packs this map lacks.

list_assets sees only the packs this map includes, and list_asset_packs only names the rest. Use this at preflight, or when list_assets comes up thin, to choose packs by what they contain. Read-only; Dungeondraft need not be running.

Terms match asset paths and the pack's own tags. match_mode: 'tokens' (every word, any order) or 'substring'. Not synonyms: "mug" will not find a tankard.

Per term, matched_by_pack counts every match in each pack, and best holds the top paths (limit per term, 80 shared), grouped by pack. packs_found says, for each pack with a match, whether this map includes it and whether the running Dungeondraft has it loaded.

Packs whose authors opted out of third-party tools reading them are not searched; they are listed under not_searched.

A path from a pack the map does not include cannot be placed here. To use it: preview_assets to look, then prepare_map_with_packs(filename, packs=[ids]), which keeps the map's current packs and adds these. A pack Dungeondraft has not loaded cannot be included until it is.

packs: limit the search to these pack ids.

preview_assets

LOOK at candidate assets before committing to one. Read-only.

Asset names are not reliable descriptions: bench_01 is a stone bench, and that is easy to miss until it is placed in a timber tavern.

Returns ONE contact sheet, so comparing N candidates costs one image. Cells are laid out row-major **in the order you passed them**, so you already know which is which — pass the candidates in a deliberate order.

Assets drawn on a BLUE-GREY ground are colourable: what you are seeing is the unpainted red mask, not the asset's real colour. It will render in whatever color you pass at placement, and flat red if you pass none. Everything else sits on neutral grey and is showing its actual art.

Use this when CHOOSING a material family — the structural, supporting and accent families a map commits to — not before every placement. A map uses few distinct assets and repeats each many times, so the decisions worth looking at are a handful per map.

A thumbnail on a plain ground will not tell you how something reads against your floor under your lighting. It catches the gross mistake (stone where you wanted wood); the map render still settles the subtle one.

assets: paths from list_assets or search_pack_contents, at most 32. category must match them.

columns: 1-8. cell_px: 32-256, the size each asset is fitted into.

prepare_map_with_packs

Copy the open map into one that INCLUDES asset packs, and open it.

Dungeondraft scopes packs per map and a map's set is fixed when it is created, so a map made without packs can never reach them — list_assets on it returns only the ~1800 core assets. This writes a copy whose header includes the packs and opens that copy, which is how a map gets a library.

Do this BEFORE building. The copy carries the open map across untouched, so running it on an empty scratch map costs nothing, while running it on a finished map means continuing in the copy from here on.

filename: bare name for the new map, in the configured save directory.

packs: pack ids to include, from list_asset_packs or search_pack_contents. REQUIRED — choose them. The copy keeps the open map's packs and adds these. Including every installed pack is costly on a large library, and one pack can dominate the catalogue. Pick by what the brief needs; adding more later means preparing another copy.

The open map is saved first so the copy is current. Assets from a pack the map does not include are not merely hidden: placing one produces an object Dungeondraft erases on load, so include the packs rather than reaching past them.

list_prefabs

List Dungeondraft's pre-composed prefabs — furnished groups, ready to place.

Prefabs are whole assemblies rather than single objects: a market stall, a set of tavern tables, a stack of crates, a well. Placing one is usually far better than composing the same thing from a dozen place_object calls, and it looks composed because a human composed it.

Returns the available sets, the current_set, and the prefabs in it.

set: switch to this set before listing (see sets in the response).