GitHub

A .net library for reading and modifying unity assets and bundles based off of the AssetsTools library from UABE.

Rework progress is ongoing on the upd21-with-inst branch. If you're trying to use AT2 and having issues on newer engine games, you might want to try AT3.

Jump to a tool:

This is a library for reading and writing unity assets files and bundle files. The original api design and file formats (class package) comes from UABE's C++ AssetsTools library, but it has been rewritten in C# with many added helper functions. Because of that, there are usually two ways to do something.

The library is very low-level, and even with helper functions, some features still take a bit of boilerplate. However, you can pretty much edit anything and everything you want. Any asset type is supported, both in assets files and bundles, but making sense of it is up to you. For example, there is no code to "extract sprites", but you can see the fields that store that information.

To help write code, you'll want to open the file you want to read/write in a tool like AssetsView.NET (in this repo) so you can see what assets have what fields.

Here's a full example to read all name strings from all GameObjects from resources.assets.

Below will go into more about what each part does.

To load an assets file, use the LoadAssetsFile method with an AssetsManager.

LoadAssetsFile returns an AssetsFileInstance which is a wrapper for two classes.

You can think of Standard classes like AssetsFile and AssetsFileTable as structs directly representing the file format and AssetsManager classes like AssetsFileInstance as classes that help linking files together.

Before going any further, type information needs to be loaded. This only applies to assets files and not bundles, which usually have type trees. The classdata.tpk file, which you can get from the releases page, contains type info that isn't included assets files. For more information about this file, see the classdata info section below.

Before we starting reading an asset, we need to look through the asset info table. Asset infos contain information such as the size of the asset, the position in the file, and the type of asset it is. There are many ways to get asset infos depending on what you're doing.

If you want to load a single asset by asset id or name, you can use inst.table.GetAssetInfo().

If you want to load all asset infos, loop over inst.table.assetFileInfo.

Or if you want to load assets of a certain type, use inst.table.GetAssetsOfType().

You can get an asset's type id from the Type field in UABE or right click -> Properties menu in AssetsView.

Once you've done that, you will probably want to deserialize the asset. To do this, use AssetManager's GetTypeInstance method, then call GetBaseField on that.

Now you can browse the fields in this asset as if it were json. Use Get to get children fields and GetValue to get the actual value of field if it has one.

If you prefer the syntax, [] is supported as well.

Arrays (or regular fields) can be iterated by field.GetChildrenList().

You'll probably come across a PPtr field, a pointer to another asset that you might want to follow. Because assets can sometimes be in different files, it is best to use am.GetExtAsset() rather than table.GetAssetInfo() and am.GetTypeInstance() . GetExtAsset also returns the file it came from and the info of the asset in case you don't know the file or the type of the asset you're reading.

For example, if you wanted to get the Transform attached to a GameObject, you could use GetExtAsset.

Writing assets files is a bit tricky. Instead of just saving the modified assets file, you must pass in changes you make when you write.

First, make the changes to fields you want to fields with field.GetValue().Set(). Then, call WriteToByteArray() on the base field to get the new raw bytes of the asset. To save the new changes back to an assets file, create an AssetsReplacer and pass it to the assets file's Write method.

The constructor for AssetsReplacers take a monoScriptIndex parameter. If you won't be touching MonoBehaviour assets, leave this as 0xffff like in this example (no script id) as a shortcut. If you are editing MonoBehaviours, use AssetHelper.GetScriptIndex() to get the correct script index. More information about this in the MonoBehaviour reading/writing section.

With the above examples, you can change the value of existing fields, but you can't add new fields (like to add to an array or create an asset from scratch.) To do that, you can use the ValueBuilder which lets you create blank AssetTypeValueFields from AssetTypeTemplateFields.

If you need to add items instead of set, you'll have to use array concat (I know, a little annoying)

Use am.LoadBundleFile() to load bundles and am.LoadAssetsFileFromBundle() to load assets files.

If you want data files in the bundle like .resS or .resource, use BundleHelper.LoadAssetDataFromBundle() to get a byte array of that file.

If you want to read the files listing in a bundle but don't want to decompress the entire file yet, use BundleHelper.UnpackInfoOnly() to decompress only the file listing info block. Make sure to call am.LoadBundleFile() with unpackIfPacked set to false.

Bundle writing works similar to assets files where you use replacers to replace files in the bundle.

Note that when you create a BundleReplacer, you have the option of renaming the asset in the bundle, or you can use the same name (or make newName null) to not rename the asset at all.

You can also compress a bundle with LZMA or LZ4.

The packers are using managed implementations so they may be slow (especially LZMA, whose c# implementation hasn't been updated in years). You may want to find a way to use native libraries instead.

You can create a new assets file or bundle file with BundleCreator.

To figure out the unity version string and format number for your game, open an assets file or bundle in AssetsView and open the Info->View Current Assets File Info menu item. You can find this programmatically with typeTreeVer = AssetsFile.typeTree.version and formatVer = AssetsFile.header.format.

The process for bundles is pretty much the same, just use BundleCreator.CreateBundleFile. Note that since the type tree is empty, you will have to add types from the class database to the bundle.

If you are reading a bundle file, most likely you can use the normal methods to read MonoBehaviours and skip this section. However, if you are reading an assets file or bundle with no type info, AssetsTools.NET needs to use the game's assemblies to deserialize MonoBehaviours. Only managed mono assemblies are read, so if your game uses il2cpp, you will need to dump the game's assemblies with il2cppdumper.

If you are using a bundle with type info, GetTypeInstance() or GetExtAsset() will work fine without this.

If you are adding a MonoBehaviour to a replacer, you'll need to give the replacer a mono id. Each unique script gets a unique mono id per file. For example, all MonoBehaviours using Script1.cs will be mono id 0 and all MonoBehaviours using Script2.cs will be mono id 1. To figure out which mono id your asset is, use AssetHelper.GetScriptIndex().