t1k:unity:base:asset-atlas
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:base:asset-atlasbuild --project <UnityProjectDir> [--out <dir>] | serve --site <dir> --project <dir> [--port N]Unity Asset Atlas
Section titled “Unity Asset Atlas”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.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “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 |
Prerequisites
Section titled “Prerequisites”- Python 3 with
numpyandPillow(pip install numpy pillow). - Optional: Blender (or any
.objviewer) to sanity-check a downloaded export.
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:
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).
What the output contains
Section titled “What the output contains”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.
Executed by
Section titled “Executed by”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.
Hard rules
Section titled “Hard rules”- Only text-serialized meshes render. A binary/imported FBX has no
m_VertexDataYAML 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
.matfiles 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_Offsetare real UV transforms, applied to both the render and the.objexport. 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
MeshColliderwithm_MeshfileID0is 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 requiresserve.py— the UI disables the download button and says so underfile:.- Scene “objects” are a size heuristic, not a structural fact. AssetRipper-flattened scenes
carry no
PrefabInstance, soassemble.pygroups a scene subtree into one object once its bounding box fits underSCENE_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.pymirrors X and flips triangle winding on every export — expected, not a bug, when comparing a downloaded.objagainst 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
SoundIdcode-linkage feature is optional and auto-detected. The build scans every.csunderAssets/forenum SoundId { ... }; if found, clips under a case-insensitiveresources+audioclipfolder path are matched to a member by filename prefix (before the first_) and linked to everySoundId.<Member>call site. No such enum → every clip still lists and classifies fine, just without the code-call-site linkage (HAS_SOUND_ENUM = False).
Related
Section titled “Related”references/hard-rules.md — vertex-channel format table, the scene-object
heuristic in full, and the material-map regex detail.