Using Asset Injection

Pro Only: Weaver Lite allows you to try out this feature in the Unity Editor, but it will not be available in a runtime build unless you purchase Weaver Pro.

When you make a public field or use the [SerializeField] attribute in Unity, you are making use of a concept known as Dependency Injection. Instead of finding a reference itself, your script just says “I need X” and relies on Unity to give it what it needs. This makes your code quite flexible because it isn’t locked into any particular hierarchy configuration and is easy to debug because you can clearly see which object is assigned to the field using the inspector.

Unfortunately, Unity’s serialization system doesn’t support static fields, so that’s where Weaver’s Asset Injection system comes in. Here’s an overview of how to use it:

  1. Create a static field (or property) of any asset type such as GameObject, AudioClip, Texture, or any Component or ScriptableObject type.
  2. Add a [Weaver.AssetReference] attribute to the field to indicate that it expects to be given a value by Weaver. There are various different Injection Attribute Types which each have different behaviour.
  3. Weaver will automatically try to find a target asset using the Asset Naming rules when the attribute is first added. Otherwise you will need to assign an asset manually and Weaver will show a [?] icon on any assets of appropriate types in the Project Window to indicate that they could be injected into the field. Right Click on the icon and select Open Weaver Window then drag the asset into the highlighted field in the Injectors Panel to assign it.

With that done, Weaver will automatically assign the chosen asset to the attributed field, both in the Unity Editor and in runtime builds. This is very similar to having a regular serialized instance field that shows up in the inspector.

Usage Conditions

  • You can use injection attributes on both fields and properties.
  • They must be static.
  • They do not need to be public. You can use any access modifiers you like.
  • Fields can be readonly so you don't accidentally reassign their value. However, this opens up the potential for certain issues if used incorrectly. Getter-only auto-properties can also be used in the .NET 4.x scripting runtime.

System Overview

The following table shows what happens once you add an injection attribute to a field.

Event What Weaver Does
Attribute first added Search the project for an asset of the appropriate type according to the Asset Naming rules and log a notification if one is found. You can always assign the asset manually in the Injectors Panel.
Editor startup Assign the chosen asset to the field (except for [AssetInstance] and [ObjectPool] injectors).
Enter play mode Assign the chosen asset to the field. If no asset has been set and the attribute hasn't been marked as Optional it will log a warning.
Compile runtime build [Pro-Only] Procedurally generate the Runtime Injection script, attach it to an object in the first scene being built so it can run immediately on startup, and give it serialized references to the assets associated with every injection attribute. A warning will also be logged for any missing assets as above.
Startup in a runtime build [Pro-Only] As soon as the first scene is loaded the Runtime Injection script assigns each of its serialized references to their respective fields.

Injectors Panel

The Injectors panel in the Weaver Window shows a field for each injection attribute in your project except for Procedural Assets which are shown in the Procedural Assets Panel instead. The fields are grouped according to their namespace.

It also shows the following options:

Option Description
Show Project Window Overlays If enabled: an extra icon will be shown in the Project Window on each asset targeted by an asset injection attribute.
Auto Find Assets Indicates whether the system should automatically search for appropriate assets for any asset injection attributes when they are first added.
Log Asset Found Indicates whether a message should be logged when a new asset is found for an asset injection attribute.
Enable Runtime Injection [Pro-Only] Indicates whether the Runtime Injector Script should be generated so that injection attributes can be used in runtime code (for builds, not play mode in the editor).
Catch Injector Exceptions [Pro-Only] Indicates whether the Runtime Injector Script should have try/catch blocks around the code for each injection attribute so that an exception caused by one won't prevent others from initialising.
Time Injector Code [Pro-Only] Indicates whether the Runtime Injector Script should time its execution and log a message.
Log Injector Code [Pro-Only] Indicates whether the Runtime Injector Script should log a message whenever it interacts with user code to aid in debugging.
InjectorScriptBuilder.Script [Pro-Only] The actual injector for the procedural Runtime Injector Script.