cspotcode/assetbundlerewriter

Rewrite path IDs in mods' assetbundles to match the bundles shipped with the base game.

NOTE: this is an advanced topic, will likely not make sense unless you understand the internals of Unity AssetBundles.

How AssetBundles Work

Objects within AssetBundles are referred to by a combo of FileID and PathID. This allows references across different assetbundles. For example, a prefab in a map's assetbundle can reference materials and meshes from a common_assets bundle.

PathID is computed using a proprietary algorithm, derived from the asset's GUID in Unity Editor.

NOTE: GUIDs are only used by Unity Editor. They live in the .meta file for each asset. But they do not exist in AssetBundles. They are replaced by FileID and PathID.

The Goal

When modding, we use Unity Editor to build our own assetbundles which reference assets from the game's vanilla bundles. For example, a custom scene for a new map may reference props and textures from the base game.

We can use AssetRipper to import all base game assets into a Unity Editor project. Then we can reference the assets in our scenes and prefabs, and build new assetbundles from them, which reference the base game's bundles. But our new assetbundles have a problem.

The Problem

AssetRipper only has access to PathIDs, it cannot know the original GUIDs. AssetRipper generates new GUIDs at random.

When we build assetbundles, Unity Editor generates PathIDs using these incorrect, randomly generated GUIDs. These PathIDs are wrong; they're different than the ones in the base game's bundles.

When Unity loads our assetbundles, it can't find the referenced assets, and our objects and prefabs are broken: missing textures, null references, etc.

The Solution

Rewrite the assetbundles generated by Unity Editor, replacing the incorrect PathIDs with the correct ones.

To postprocess assetbundles to fix their PathIDs, we need to:

1. rip everything from the game to generate a set of canonical "wrong" GUIDs.
2. Create a tool to impose those canonical GUIDs onto any future rips of the game. Assetripper generates new random GUIDs every time you run it. You run it, your GUIDs are different from mine. We need to fix this with a tool.
3. Bundle everything into AssetBundles. All the PathIDs will be wrong because they're generated from the wrong GUIDs.
4. Cross-reference our wrong PathIDs with the correct PathIDs from TeamReptile, build a one-to-one mapping.
5. Write a tool to post-process AssetBundles and replace PathIDs.

Resources

AT/Tools⁠ Discord
https://discord.gg/Z8bcChFx
https://discord.com/channels/862035581491478558/862035741202448424/1215357066059980840
https://github.com/cspotcode/unity-notes/blob/main/assetbundle_pathids.md (might be private)