UnityAssetDB

🗄️ Every asset reference in your Unity project, in one queryable database

🌐 中文

Why UnityAssetDB?

Unity projects grow into tangled webs of asset dependencies. "Who references this material?" "Is this texture safe to delete?" "Which scenes use this prefab?" — answering these questions by hand means grepping through thousands of YAML files.

UnityAssetDB indexes your entire Unity project into a SQLite database and answers these questions in under 1 millisecond.

$ unityassetdb refs Assets/Materials/Enemy.mat

📂 Assets/Materials/Enemy.mat (2 referenced by)
────────────────────────────────────────────────────────────────
  ← Assets/Scenes/Game.unity [scene] via depends_on (guid-file)
  ← Assets/Scenes/Game.unity [scene] via instance_of
2 reference(s) total

✨ Key Features

Quick Start

Install

# Download pre-built binary (macOS / Linux / Windows)
# → https://github.com/song-chaoyang/UnityAssetDB/releases

# Or build from source
cargo install --git https://github.com/song-chaoyang/UnityAssetDB

3 Steps to Go

# 1️⃣  Index your Unity project
unityassetdb index build /path/to/your/unity/project

# 2️⃣  Query references
unityassetdb refs Assets/Materials/Enemy.mat -p /path/to/project

# 3️⃣  Launch the Web UI
unityassetdb serve /path/to/project --port 8089

Live Progress Feedback

The 8-phase pipeline renders a live multi-bar display — weighted overall percentage + ETA, a phase bar with throughput and live extraction stats, and the file currently being processed:

⠸ [00:00:12] ████████████░░░░░░░░  48% 3/8 extract · ETA 08s
⠹ ████████████████░░░░░  extract 31,422/54,120 · 2,615/s · 892K objs · 1.2M refs · 2.3 GB
  📄 Assets/Scenes/MainMenu.unity

When it finishes, you get a per-phase timing breakdown so you always know where the time went:

  phase breakdown:
    scan          1.8s  ████████████████████
    register      0.6s  ██████
    extract      14.2s  ████████████████████████████
    assets        0.9s  ██
    graph         2.7s  █████
    bind          0.4s  █
    vfs           1.1s  ██
    publish       0.2s
✅ Index built in 21.4s: .unityassetdb/index.db (54,120 files, 12,830 assets, 8,221 scripts bound, 2,529 files/s)

Demo: Reference Query

CLI Reference

unityassetdb <COMMAND>

Commands:
  index   Index management (build / sync / status)
  refs    Query the reference graph for a VFS path
  ls      List VFS entries under a path
  glob    Find VFS entries matching a glob pattern
  grep    Search content within VFS entries
  read    Read content of a VFS entry
  serve   Start web server with interactive graph UI
  mcp     Start MCP server (JSON-RPC over stdio)
  help    Print this message

Common Queries

# Who references this material? (incoming)
unityassetdb refs Assets/Materials/Enemy.mat -p /project

# What does this scene depend on? (outgoing)
unityassetdb refs Assets/Scenes/Game.unity -p /project --direction out

# Filter to file-level results only
unityassetdb refs Assets/Materials/Enemy.mat -p /project --filter File

# Browse the asset tree
unityassetdb ls Assets -p /project --depth 2

# Find all prefabs
unityassetdb glob "*.prefab" -p /project

# Search for a class name in indexed content
unityassetdb grep "PlayerController" -p /project

# View index statistics
unityassetdb index status /project

Architecture

How It Works

UnityAssetDB runs a 7-stage indexing pipeline:

SQLite Schema — 19 Tables

VFS Edge Types

REST API

When running serve, these endpoints are available:

MCP Server

UnityAssetDB can run as an MCP (Model Context Protocol) server, exposing 7 tools via JSON-RPC over stdio.

unityassetdb mcp

Configuration

Add to your MCP client config file (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "unityassetdb": {
      "command": "/path/to/unityassetdb",
      "args": ["mcp"]
    }
  }
}

Available Tools

Supported File Types

Tech Stack

Benchmarks

Measured on a real Unity project (URP + TextMeshPro, Apple Silicon MacBook):

Indexing covers Assets/, Packages/, ProjectSettings/ and Library/PackageCache/ (built-in package scripts resolve too). Includes indexing file bodies for grep/read.

Development

cargo test      # Run all 32 tests
cargo clippy    # Lint
cargo fmt       # Format
cargo bench    # Benchmarks

Project Structure

src/
├── model/          # Data types (FileKind, AssetKind, EntityKind, EdgeKind)
├── discovery/      # File system scanning + .meta parsing
├── extract/         # Unity YAML + C# tree-sitter parsers
├── resolve/        # Entity graph construction + script binding
├── materialize/    # VFS projection
├── db/              # SQLite schema + connection management
├── query/           # refs, ls, glob, grep, read
├── cli/             # CLI + MCP command handlers
├── server/          # axum REST API
└── web/             # Embedded HTML/JS/CSS

tests/
├── fixtures/        # Minimal Unity test project
└── integration_test # 32 tests: unit + integration

Download

Pre-built binaries available on the Releases page:

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Star History

License

MIT © 2026