I’ve noticed a trend with Unity’s documentation in relation to how I actually have to work with the software.
Tutorials teach specifics in terms of using a command or feature in isolation but don’t consider the implications of incorporation of that feature into a commercial product. If you want us to adopt 2nd generation technology into our products, you have to be thorough.
As things are right now, you’re selling us a hamster without informing us that we’ll also need to get a cage, a water bottle, feed, wood chips and possible veterinary bills, and believe me, finding that out later on when it becomes an issue rather than letting us know what we’ve signed up for at the start is very unpleasant.
It’s not that I don’t want to be the proud owner of a hamster, but being a hamster owner requires planning that is no less intricate than getting involved with Addressables, the new Input System, UIToolkit, SRPs, Localization, Entities, Netcode for GameObjects and Netcode for Entities, and so on.
I am coming to you after three years of dealing with this as a solo dev and I’m kind of tired of going to the tutorials to learn something and receiving an experience like:
When I need something more like:
So, case in point, let’s look at the documentation for Addressables (and I’m only picking Addressables because it’s the first, alphabetically. All the rest of Gen2 docs have this problem):
This intro gives a really detailed syntactic examples of how to use Addressables, including loading and unloading of assets by AssetReference, Address, and Label, but it doesn’t explain how to USE the loaded asset itself!
Let’s look at one of the examples:
This example loads a prefab from Addressables, referenced via:
// Assign in Editor
public AssetReference reference;
Since we’re dealing with a prefab, it should actually use something more specific like:
// Assign in Editor
public AssetReferenceT<GameObject> reference;
You want to use the specific AssetReferenceT to limit the field so that the picker only allows for GameObject prefabs marked as Addressable because otherwise the editor will allow you to assign a TEXTURE or SOUND or MESH or ANYTHING marked as ADDRESSABLE to that reference.
And I would even go further by renaming the “reference” variable to “prefabReference”. Demonstrate good coding practices by using descriptive variable names! Do you have to? No! But newbs learn from your tutorials and then I have to deal with them using nondescriptive variable names that they learned from you guys!
Then this example runs into even further issues when it finishes loading the reference with:
if (obj.Status == AsyncOperationStatus.Succeeded)
{
Instantiate(reference.Asset, transform);
}
Great! We instantiated the gameobject and attached it to our transform, but didn’t retain any reference to it! So, we had better hope that there are no other children on this transform when it is time to clean this object up.
Because, let’s say that the prefab we just instantiated also has addressable references to things like, oh, I dunno, TEXTURES AND SOUNDS AND MODELS. How are those going to be handled? We have to preload those things as well!
And what if this prefab contains a hierarchy of things which also reference addressables? How will those be handled?
And when we go through OnDestroy(), what would the cleanup operation be like?
Once you get into real-life applications this sort of thing can rapidly spiral out of control. It does not just go all Todd Howard “It just works™”. This tutorial, needs to at the very least, hint at some of the pitfalls that you will encounter.
And remember, this is not just for Addressables. (I have a bone to pick with documentation for Entities and Scriptable Render Pipelines and every single Gen2 tech that has come out in the last 3-5 years. I never get to work on gameplay because I have to deal with all the mess that the tutorials never touched.) You have to explain what happens if you use Addressables for things like shaders and sound effects. Like, what happens if you unload an addressable currently being used by a sound that is playing? Does the sound effect just cut off? Will it throw an errorspam?
