Skip to content

t1k:unity:base:asset-atlas

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: asset atlas, asset browser, asset placement, AssetRipper, browse assets, download assets, force text, list meshes, list sounds, list textures, obj export, SoundId, text-serialized, where is this mesh used

/t1k:unity:base:asset-atlas
build --project <UnityProjectDir> [--out <dir>] | serve --site <dir> --project <dir> [--port N]

Builds a local, searchable website over a Unity project’s Assets/: every assembled object (a whole prefab or scene group rendered with all its parts, already positioned), every 3D model part (a rendered mesh with its placements), every sound, and every texture — each with its file location and every place it’s referenced (scene/prefab hierarchy path, material, and, when the project defines a SoundId-style enum, the code line that plays it). Items can be ticked and downloaded as a zip (.obj+.mtl+texture for models, .ogg for sounds, .png for textures).

Scope limit — read before running: only text-serialized Mesh .asset files are decoded and rendered (an AssetRipper export, or a project built with Force Text asset serialization). A binary/imported FBX mesh has no YAML vertex data and will not appear at all — this tool is a project-asset browser for a ripped/text-serialized tree, not a general Unity asset browser. If most meshes are missing from the output, the project is not text-serialized.

IntentPath
“Build/rebuild the atlas for a project”Build
“Browse without downloads”open <out>/index.html directly (file://) — selecting works, downloading is disabled
“I need to download selected assets”Serve
“A mesh renders wrong / textures are missing / classification looks off”references/hard-rules.md
  • Python 3 with numpy and Pillow (pip install numpy pillow).
  • Optional: Blender (or any .obj viewer) to sanity-check a downloaded export.
Terminal window
python "<skill-dir>/scripts/build.py" --project <UnityProjectDir> [--out <OutDir>]

<skill-dir> is this skill’s base directory (“Base directory for this skill”). <UnityProjectDir> must contain Assets/ (point it at the AssetRipper export root, or the ripped project’s root). --out defaults to ./AssetAtlas under the current directory — pick a stable location if you’ll re-run serve.py against it later. A trailing mesh name (or several) restricts the run to just those meshes for a quick render test, skipping audio/textures/assembled objects.

Each run: copies the static site shell (index.html/app.js/style.css) into --out, decodes every Assets/Mesh/*.asset, composes every prefab and every scene “object” (assemble.py’s size-heuristic grouping — see the reference doc), classifies every audio clip and texture, writes <out>/data.js + <out>/thumbs/*.webp + <out>/export/** (per-part .obj/.mtl), and prints a meshes N audio N textures N summary line. Re-run after any asset change — everything under --out is fully regenerated each time.

Opening <out>/index.html straight from disk (file://) works for browsing and selecting, but the browser cannot zip a selection itself — downloads need the server:

Terminal window
python "<skill-dir>/scripts/serve.py" --site <OutDir> --project <UnityProjectDir> [--port 8765] [--no-browser] [--host 127.0.0.1]

--site is the --out a prior build wrote; --project must be the same project root build used (sound players and full-size texture links are served live from it under /project/...). Binds to 127.0.0.1 by default; --host 0.0.0.0 serves on the LAN. POST /download accepts a JSON list of {"src","dst"} entries (the download arrays already embedded per item in data.js) and returns a zip; both the /project/ route and the zip path-resolver reject anything outside --site / --project/Assets (path traversal guard).

Four tabs: Assembled objects (whole prefabs and scene groups), 3D model parts (individual meshes), Sounds, Textures. Each item card shows a render/thumbnail, size/tri counts, every scene-or-prefab hierarchy path it’s placed at, and (for audio, when applicable) the SoundId.X call sites. A selection bar at the bottom lets you tick items across tabs and download them together as one zip; an assembled object’s zip entry is one .obj per part, already positioned, so importing the whole set rebuilds the object.

Runs inline in the main session (or an inline sub-agent Bash call) — it is a deterministic script invocation, not a reasoning or orchestration task. No sub-agent fan-out.

  • Only text-serialized meshes render. A binary/imported FBX has no m_VertexData YAML block and is silently absent from the mesh list — not an error, just nothing to decode. Confirm the project is an AssetRipper export or Force-Text before assuming a “missing mesh” is a tool bug.
  • Newer .mat files drop the - list-item prefix on texture map entries (_MainTex:\n m_Texture: ... instead of - _MainTex:\n m_Texture: ...). The build’s regex accepts both forms — if you ever touch it, keep the (?:- )? optional group or textures vanish silently.
  • Material m_Scale/m_Offset are real UV transforms, applied to both the render and the .obj export. Palette/atlas-style textures rely on the offset to select the right region; skip it and the render looks textured-but-wrong (constant top-left swatch).
  • Vertex streams are 16-byte aligned. Decoding without the stream-padding step reads every channel after the first at the wrong byte offset. Full channel-format table: references/hard-rules.md.
  • A MeshCollider with m_Mesh fileID 0 is not a missing visual — it’s a legitimate collider shape reference the mesh-lookup path never even reaches (renderers only, classes 33/137).
  • file:// pages cannot zip a selection. Browsing and ticking items works straight from disk; downloading requires serve.py — the UI disables the download button and says so under file:.
  • Scene “objects” are a size heuristic, not a structural fact. AssetRipper-flattened scenes carry no PrefabInstance, so assemble.py groups a scene subtree into one object once its bounding box fits under SCENE_OBJECT_MAX_SIZE (metres, default 2.6) — tune that constant per project; a value too large merges real objects, too small fragments them (a wall side, the floor).
  • Unity is left-handed; OBJ is right-handed. export.py mirrors X and flips triangle winding on every export — expected, not a bug, when comparing a downloaded .obj against the in-Unity orientation.
  • Renders are approximate. One triangle-center UV sample against a downsampled 128×128 texture, single fixed light — a placement-recognition thumbnail, not a lighting preview. A mesh whose material is assigned at runtime (never referenced by an authored .mat) renders flat gray; that’s expected, not a decode failure.
  • The SoundId code-linkage feature is optional and auto-detected. The build scans every .cs under Assets/ for enum SoundId { ... }; if found, clips under a case-insensitive resources+audioclip folder path are matched to a member by filename prefix (before the first _) and linked to every SoundId.<Member> call site. No such enum → every clip still lists and classifies fine, just without the code-call-site linkage (HAS_SOUND_ENUM = False).

references/hard-rules.md — vertex-channel format table, the scene-object heuristic in full, and the material-map regex detail.