[#68] Generalize AssetBundle to Archive in analyze schema and code#89
Merged
Conversation
Unity Archives back AssetBundles, Player builds, Content Archives and
ContentDirectory builds, so names that said "AssetBundle" where the concept
is really "any Unity Archive" were misleading (notably for ContentDirectory
builds). Rename those to "Archive", leaving genuinely AssetBundle-object-
specific names (assetbundle_assets, AssetBundleHandler, etc.) untouched.
Schema (user_version 2 -> 3):
- Table asset_bundles -> archives; serialized_files.asset_bundle -> archive.
- The asset_bundle view alias -> archive across object_view and the views
that build on it (material/shader/texture/dep aliases, monoscript views,
in_bundles -> in_archives).
- build_report_archive_contents.assetbundle/assetbundle_content ->
archive/archive_content.
Code:
- AddAssetBundle -> AddArchive; Begin/EndAssetBundle -> Begin/EndArchive;
Context.AssetBundleId -> ArchiveId; ExtractAssetBundle/ListAssetBundle ->
ExtractArchive/ListArchive; FileListAssetBundleHelper -> FileListArchiveHelper.
- ReferenceFinder query column and output labels ("Archive:").
- Stripped the stale auto-generated SQL snapshot comments from
Resources.Designer.cs (they drift; the .sql files are the source of truth).
Tests, compare scripts and documentation updated to match; test key
asset_bundles_count -> archives_count.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates UnityDataTools’ analyze schema and related code/docs to use the more general term “archive” (Unity Archive container) instead of “asset bundle” where the concept is not AssetBundle-object-specific, and bumps the SQLite schema user_version from 2 → 3.
Changes:
- Schema rename:
asset_bundles→archives, andserialized_files.asset_bundle/object_view.asset_bundle→archive(plus downstream views/columns likein_bundles→in_archives). - Code rename: writers/parsers/ReferenceFinder/Archive command paths updated to use
Archive*naming and updated SQL queries/labels. - Tests, scripts, and documentation updated to reflect the renamed tables/columns and new schema version.
Reviewed changes
Copilot reviewed 34 out of 35 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| UnityDataTool.Tests/UnityDataToolPlayerDataTests.cs | Updates test query to count rows from archives. |
| UnityDataTool.Tests/UnityDataToolAssetBundleTests.cs | Updates validation query + expected-data key to archives_count. |
| UnityDataTool.Tests/ExpectedDataGenerator.cs | Updates generator query + emitted key to archives_count. |
| UnityDataTool.Tests/ExpectedData/2023.1.0a16/ExpectedValues.json | Renames expected key to archives_count. |
| UnityDataTool.Tests/ExpectedData/2022.1.20f1/ExpectedValues.json | Renames expected key to archives_count. |
| UnityDataTool.Tests/ExpectedData/2021.3.0f1/ExpectedValues.json | Renames expected key to archives_count. |
| UnityDataTool.Tests/ExpectedData/2020.3.0f1/ExpectedValues.json | Renames expected key to archives_count. |
| UnityDataTool.Tests/ExpectedData/2019.4.0f1/ExpectedValues.json | Renames expected key to archives_count. |
| UnityDataTool.Tests/BuildReportTests.cs | Updates BuildReport schema expectations and queries to use archive / archive_content. |
| UnityDataTool.Tests/AddressablesBuildLayoutTests.cs | Updates table name in assertion to archives. |
| Scripts/comparebundles.ps1 | Updates joins/aliases from asset_bundles/asset_bundle to archives/archive. |
| Scripts/comparebuilds.ps1 | Updates joins/aliases from asset_bundles/asset_bundle to archives/archive. |
| ReferenceFinder/ReferenceFinderTool.cs | Updates object_view/assetbundle_asset_view queries and printed labels to archive. |
| Documentation/referencefinder.md | Updates example output labels to Archive. |
| Documentation/comparing-builds.md | Updates example column header from asset_bundle to archive. |
| Documentation/command-find-refs.md | Updates example output labels to Archive. |
| Documentation/buildreport.md | Updates example queries and schema text to use archive naming. |
| Documentation/assetbundle-format.md | Documents how AssetBundles are represented via generic archives + serialized_files.archive. |
| Documentation/analyzer.md | Updates schema reference language; adds archives table description; renames asset_bundle → archive. |
| Documentation/analyze-examples.md | Updates example SQL queries to use archive and archives. |
| Archive/ArchiveTool.cs | Renames extract/list helpers from AssetBundle-specific to Archive terminology. |
| Analyzer/SQLite/Writers/SerializedFileSQLiteWriter.cs | Renames writer state/commands to Archive terminology; writes serialized_files.archive. |
| Analyzer/SQLite/Parsers/SerializedFileParser.cs | Renames per-archive writer calls and logging to Archive terminology. |
| Analyzer/SQLite/Handlers/ISQLiteHandler.cs | Renames context field from AssetBundleId to ArchiveId. |
| Analyzer/SQLite/Handlers/BuildReportHandler.cs | Updates insert command and mapping usage to archive/archive_content. |
| Analyzer/SQLite/Commands/SerializedFile/AddSerializedFile.cs | Renames serialized_files FK column from asset_bundle to archive. |
| Analyzer/SQLite/Commands/SerializedFile/AddArchive.cs | Renames insert command from AssetBundle table to archives. |
| Analyzer/SerializedObjects/BuildReport.cs | Renames helper to FileListArchiveHelper and extends roles to include ContentArchive. |
| Analyzer/Resources/Shader.sql | Renames aggregated column alias to in_archives and uses archive. |
| Analyzer/Resources/PackedAssets.sql | Renames BuildReport view columns from assetbundle* to archive*. |
| Analyzer/Resources/MonoScript.sql | Renames asset_bundle columns to archive in views. |
| Analyzer/Resources/Init.sql | Renames core tables/columns/views and bumps PRAGMA user_version to 3. |
| Analyzer/Resources/BuildReport.sql | Renames build_report_archive_contents columns to archive / archive_content. |
| Analyzer/Resources/AssetBundle.sql | Updates comments + view columns to use archive where sourced from object_view. |
| Analyzer/Properties/Resources.Designer.cs | Removes large auto-generated SQL snapshot comments (resource accessors remain). |
Files not reviewed (1)
- Analyzer/Properties/Resources.Designer.cs: Generated file
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
229
to
232
| m_AddSerializedFileCommand.SetTransaction(transaction); | ||
| m_AddSerializedFileCommand.SetValue("id", serializedFileId); | ||
| m_AddSerializedFileCommand.SetValue("asset_bundle", m_CurrentAssetBundleId == -1 ? "" : m_CurrentAssetBundleId); | ||
| m_AddSerializedFileCommand.SetValue("archive", m_CurrentArchiveId == -1 ? "" : m_CurrentArchiveId); | ||
| m_AddSerializedFileCommand.SetValue("name", relativePath); |
Collaborator
Author
There was a problem hiding this comment.
See comment below
Comment on lines
+27
to
28
| -- archive references the row from archives table of the unity archive containing this file, | ||
| -- or is '' when the file is not inside an unity archive; object_view turns that '' into NULL. |
Collaborator
Author
There was a problem hiding this comment.
See comment below
The FileListArchiveHelper example mapped a ContentFile to its role (ContentFile) instead of to the containing archive filename. It maps the internal file name to the archive file name, matching the AssetBundle example above it.
Collaborator
Author
|
Addressed Copilot's review:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #68.
Several names in UnityDataTools said "AssetBundle" where the underlying concept is really "any Unity Archive". Unity uses the archive file format for AssetBundles, but also for Player builds, Content Archives and ContentDirectory builds, so the AssetBundle-centric naming was misleading — most obviously the
asset_bundlesanalyze table when inspecting a ContentDirectory build. This generalizes those names to "Archive" while deliberately leaving the names that are genuinely specific to the AssetBundle object (e.g.assetbundle_assets,AssetBundleHandler) unchanged.IMPORTANT: This is a breaking schema change that may cause some migration work for existing users as they upgrade to UnityDataTool v2. However it will help the long term relevancy and clarity of this tool because UnityDataTool scope has grown beyond its original focus on AssetBundles. It will still retrains all its AssetBundle support, but also represent content from other builds is a more accurate way.
The database
user_versiongoes from 2 to 3. The tool is already at 2.0.0 (bumped in the earlier #82 rename), so this ships in the same major version. The rename map below is provided so downstream tools can search/replace their queries.Changes
Schema (
user_version2 → 3)asset_bundles→archives; columnserialized_files.asset_bundle→archive.asset_bundleview alias →archiveacrossobject_viewand everything built on it (thematerial_/shader_/texture_/dep_aliases, the monoscript views, andin_bundles→in_archives).build_report_archive_contents.assetbundle/assetbundle_content→archive/archive_content.Code
AddAssetBundle→AddArchive;Begin/EndAssetBundle→Begin/EndArchive;Context.AssetBundleId→ArchiveId;ExtractAssetBundle/ListAssetBundle→ExtractArchive/ListArchive;FileListAssetBundleHelper→FileListArchiveHelper.Archive:/(Archive = …)).Resources.Designer.cs— they drift from the.sqlfiles, which are the real source of truth (embedded viaResXFileRef).Tests / scripts / docs
asset_bundles_count→archives_countexpected-data key updated.Scripts/comparebuilds.ps1,Scripts/comparebundles.ps1and the affected Documentation pages updated, including a new note inassetbundle-format.mdand anarchivestable entry inanalyzer.mdexplaining how AssetBundles are represented generically.Migration (for v2.0 release notes)
Testing
dotnet build -c Releaseclean, anddotnet testfully green (62 Analyzer.Tests + 425 UnityFileSystem.Tests + 238 UnityDataTool.Tests). The build-report and find-refs tests exercise the renamed schema end-to-end.Manual smoke test: analyzed
TestCommon/Data/contentdirectory-zstdand confirmedPRAGMA user_version= 3, thearchivestable holdscontent0.archive,object_view.archiveis populated, and the oldasset_bundlestable is gone.