Skip to content

Latest commit

 

History

History
165 lines (112 loc) · 10.2 KB

AddressableImporter.md

File metadata and controls

165 lines (112 loc) · 10.2 KB
Raw

Addressable Importer Usage

Table of Contents

Setup the Importer

Make sure you have run the Unity Addressables's Create Addressables Settings command to create a folder called AddressableAssetsData, in which it stores settings files and other assets for the Addressables system.

Then go to Assets/AddressableAssetsData folder, right click in your project window and run the Create > Addressables > Import Settings command to create an AddressableImportSettings file at AddressableImportSettings.asset, and an AddressableImportSettingsList file at AddressableImportSettingsList.asset.

AddressableImportSettings Create

AddressableImportSettings is the place to add/edit import rules. You can have more than one AddressableImportSettings and get them organized in a single AddressableImportSettingsList. But for projects at a smaller scale, one AddressableImportSettings is good enough.

Once the settings file selected, you can edit rules in the inspector window. Then click the Save button to apply the changes.

AddressableImportSettings Inspector

Define Rules

  • Path, the path pattern.
  • Match Type
    • Wildcard, * matches any number of characters, ? matches a single character.
    • Regex.
  • Group Name, leaves blank for the default group. For dynamic group see Group Replacement.
  • Label Mode, defines if labels will be added or replaced.
  • Label Refs, The list static labels (already existing in your project) to be added to the Addressable Asset.
  • Dynamic Labels,The list of dynamic labels to be added to the Addressable Asset. If a label doesn't exist, then it will be create in your unity project.
  • Address Simplified, simplify address to filename without extension.
  • Address Replacement, leaves blank to use the asset path as address. For dynamic address see Address Replacement.

Rule Examples

Type Example
Wildcard Asset/Sprites/Icons/*
Wildcard Asset/Sprites/Level??/*.asset
Regex ^Assets/Models/.*\.fbx
Regex Assets/Weapons/(?<prefix>(?<category>[^/]+)/(.*/)*)(?<asset>.*_Data.*\.asset)

Because directory itself can be an address entry as well. You need to design your rules with caution to avoid including both folder and files at the same time.

For example,

Assets/
  t1/
    1.txt
Rule Path Rule Type Results Comments
Assets/t1 Wildcard t1 and t1/1.txt bad
Assets/t1/*.txt Wildcard t1/1.txt good
^Assets/t1$ Regex t1 good
^Assets/t1/.* Regex t1/1.txt good

Group Replacement

The dynamic group is supported by replacing ${name} with the extracted value from the asset path, via the use of regex capture groups. Named capture groups can be referred to in Group Name via ${group}. If groups are not named, they can be referred to numerically, via $1, $2, and so on. For more information, refer to Microsoft Docs - Substitutions in Regular Expressions. This only works for match type Regex.

For convenience, path elements can be referred via ${PATH[index]}. This works for all match types.

Asset Path Rule Path Group Name Result
Assets/Sprites/cat.png Assets/Sprites/*.png ${PATH[1]} Sprites
Assets/Sprites/cat.png Assets/Sprites/*.png ${PATH[-1]} Sprites
Assets/Sprites/cat.png Assets/Sprites/*.png ${PATH[1]}-Group Sprites-Group
Assets/Sprites/cat.png Assets/Sprites/*.png ${PATH[0]}-${PATH[1]} Assets-Sprites
Assets/cat/cat01.png Assets/(?<category>[^/]+)/(?<asset>.*)\.png ${PATH[0]}:${category} Assets:cat

Address Replacement

AddressableImportSettings Inspector Regex

Similar to Group Replacement, address replacement is also supported.

Asset Path Rule Path Address Replacement Result
Assets/cat/cat01.png Assets/(?<category>[^/]+)/(?<asset>.*)\.png ${category}-${asset} cat-cat01
Assets/cat/cat01.png Assets/(?<category>[^/]+)/(?<asset>.*)\.png ${PATH[0]}:${category}-${asset} Assets:cat-cat01

The importer always overrides existing address if

  • The address looks like a path (starts with Assets/).
  • Address Simplified is ticked.
  • Address Replacement is in use.

In another word, if you are intending to manually change the address later, leave Address Simplified unticked, Address Replacement blank, and do not use Assets/ prefix for the customized address name.

Label Replacement

You can add a label to your addressable asset.

You can choose between:

  • Label Refs: use a static label already created in Unity project
  • Dynamic Labels: you can automatically create label in your Unity project and add it to your addressable asset. You can use the same rules to create a dynamic name group explained in Group Replacement.
Asset Path Rule Path Label Replacement Result
Assets/cat/cat01.png Assets/(?<category>[^/]+)/(.*)\.png ${category} cat

For an interactive example you can watch this video: https://youtu.be/r5bCKY6TvP0

The importer always overrides existing labels if LabelMode = Replace.

Quick Assets Re-import

The importer should apply the rules whenever an asset being imported, moved, or deleted. However, if you modified rules or want to apply rules to existing assets, you need to manually apply the rules. To quickly apply the rules, select target folder(s) in the project view, right-click to open the context menu, and then click AddressableImporter: Check Folder(s). The action is more efficient than force reimport assets.

AddressableImport Context Menu

You can also use ReimportFolders API to process any folders in code. e.g. re-import all asset folders in a build script. The API requires an array of asset paths. An asset path is a string that starts with "Assets".

// Example: process the whole "Assets" folder
AddressableImporter.FolderImporter.ReimportFolders(new string[] { "Assets" });

About Prefab Mode

When both prefab mode (the preview scene for editing a prefab) and the autosave feature are enabled, every modification will cause the asset to be saved and trigger the importer, leads to slow response. For performance reasons, the importer will ignore the current editing asset.

Multiple AddressableImportSettings Support

Multiple AddressableImportSettings are supported to help projects at a larger scale get better organized. The ordering of multiple AddressableImportSettings is prioritized by a single AddressableImportSettingsList.

The newly created AddressableImportSettings will be added to the AddressableImportSettingsList automatically. The copied AddressableImportSettings requires to be linked manually, or click the Rebuild Settings List button to load all AddressableImportSettings files in the project.

Multiple Settings

An AddressableImportSettings can be toggled by its Rules Enabled field, a useful feature to help you test multiple AddressableImportSettings.

Odin Inspector Support

Since v0.9.0, the importer supports Odin inspector (affiliates) to optimize the user experience. Odin is a paid tool to boost editor plugin development. The integration allows filter or order importer rules easier. The Odin support is optional. To enable it, just install the Odin library.

Since v0.11.0, the importer only support Odin v3. Please make sure the Scripting Define Symbols of Player Settings contains ODIN_INSPECTOR and ODIN_INSPECTOR_3 flags.

image

If you no longer use Odin, please remove the flags above, otherwise Unity will report a compile error:

error CS0246: The type or namespace name 'ISearchFilterable' could not be found (are you missing a using directive or an assembly reference?)

Contributor Notice

To enable unit tests for this package, add the package name com.littlebigfun.addressable-importer into the testables fields of Packages/manifest.json.

"testables": ["com.littlebigfun.addressable-importer"]