🏗️ Lesson 7.4: Mini-Project — A Level-Layout Tool with Addressable Loading

The Plan & Architecture

The tool has three pieces that pass data down a chain. The Editor window writes into a layout asset; the runtime loader reads that asset and drives Addressables. The layout asset is the hinge — it's authored in the Editor but consumed at runtime, so it must store only serializable, runtime-safe data (an AssetReference, a position, a rotation), never Editor types.

Step 1 — The Layout ScriptableObject

Start with the data. A LevelLayout holds a list of markers, and each marker is an AssetReference (which Addressable to spawn) plus a position and rotation. Marking the marker [System.Serializable] lets Unity save it inside the asset; [CreateAssetMenu] lets you make one from the Project window's Create menu.

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.AddressableAssets;   // AssetReferenceGameObject

// One placed object: which Addressable, and where.
[System.Serializable]
public class LayoutMarker
{
    public AssetReferenceGameObject prefab;   // stored as an Addressables key
    public Vector3 position;
    public Vector3 eulerRotation;
}

// The saved level: just a list of markers. Runtime-safe, serializable data.
[CreateAssetMenu(fileName = "LevelLayout", menuName = "Level Tools/Level Layout")]
public class LevelLayout : ScriptableObject
{
    public List<LayoutMarker> markers = new();
}

That's the entire persistence layer. Because it's a ScriptableObject, it's a real project asset you can select, inspect, version-control, and hand to a designer. Because every field is a plain serializable type, it loads at runtime with no Editor dependency. The AssetReferenceGameObject is doing the heavy lifting from Lesson 7.3 — it remembers which Addressable without hard-loading it.

Step 2 — The EditorWindow Tool

Now the authoring window. It needs a field to point at the active LevelLayout asset, a ListView of the Addressable prefabs you can place, and buttons to stamp and save. We build the shell in CreateGUI exactly as in Lesson 7.2. To discover which prefabs are Addressable, we read the Addressables settings in the Editor:

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UIElements;
using UnityEditor;
using UnityEditor.AddressableAssets;              // AddressableAssetSettingsDefaultObject
using UnityEditor.AddressableAssets.Settings;     // AddressableAssetEntry

public class LevelLayoutWindow : EditorWindow
{
    LevelLayout activeLayout;                      // the asset we're editing
    readonly List<string> addressableKeys = new(); // addresses we can stamp
    ListView prefabList;
    Label statusLabel;

    [MenuItem("Tools/Level Layout Tool")]
    public static void ShowWindow()
    {
        var w = GetWindow<LevelLayoutWindow>();
        w.titleContent = new GUIContent("Level Layout");
        w.minSize = new Vector2(340, 320);
    }

    public void CreateGUI()
    {
        var root = rootVisualElement;
        root.style.paddingTop = root.style.paddingLeft =
            root.style.paddingRight = root.style.paddingBottom = 8;

        var title = new Label("Level Layout Tool");
        title.style.fontSize = 16;
        title.style.unityFontStyleAndWeight = FontStyle.Bold;
        title.style.marginBottom = 8;
        root.Add(title);

        // Field to assign the LevelLayout asset we're authoring into.
        var layoutField = new ObjectField("Layout Asset")
            { objectType = typeof(LevelLayout), allowSceneObjects = false };
        layoutField.RegisterValueChangedCallback(evt =>
            activeLayout = evt.newValue as LevelLayout);
        root.Add(layoutField);

        RefreshAddressableKeys();

        prefabList = new ListView(addressableKeys, 20,
            makeItem: () => new Label(),
            bindItem: (e, i) => ((Label)e).text = "🧩 " + addressableKeys[i]);
        prefabList.selectionType = SelectionType.Single;
        prefabList.style.flexGrow = 1;
        prefabList.style.marginTop = 6;
        root.Add(prefabList);

        // Button row.
        var row = new VisualElement();
        row.style.flexDirection = FlexDirection.Row;
        row.style.marginTop = 6;

        var stampBtn = new Button(StampSelected) { text = "Stamp Marker at Scene View" };
        stampBtn.style.flexGrow = 1;
        var saveBtn = new Button(SaveLayout) { text = "Save" };
        saveBtn.style.flexGrow = 1;
        row.Add(stampBtn);
        row.Add(saveBtn);
        root.Add(row);

        statusLabel = new Label("Assign a Layout Asset, pick a prefab, then Stamp.");
        statusLabel.style.marginTop = 6;
        statusLabel.style.color = new Color(0.6f, 0.66f, 0.72f);
        root.Add(statusLabel);
    }

    // Read every Addressable entry's address from the project's settings.
    void RefreshAddressableKeys()
    {
        addressableKeys.Clear();
        var settings = AddressableAssetSettingsDefaultObject.Settings;
        if (settings == null) return;
        foreach (var group in settings.groups)
            foreach (AddressableAssetEntry entry in group.entries)
                addressableKeys.Add(entry.address);
    }
}

The ObjectField restricts its picker to LevelLayout assets, so you can only aim the tool at the right kind of asset. RefreshAddressableKeys walks the Addressables settings — every group, every entry — and collects each entry's address into the list the ListView displays. Selecting a row selects the prefab you're about to stamp.

Step 3 — Stamping & Saving Markers

Stamping adds a marker for the selected prefab at the Scene view camera's pivot, so you place things where you're looking. Because the layout is a serialized asset, we edit it through the Undo system and mark it dirty so the change persists — the same discipline as Lesson 7.1's Inspector edits. Add these methods to the window:

    void StampSelected()
    {
        if (activeLayout == null)
        {
            statusLabel.text = "⚠ Assign a Layout Asset first.";
            return;
        }
        int i = prefabList.selectedIndex;
        if (i < 0)
        {
            statusLabel.text = "⚠ Select a prefab in the list first.";
            return;
        }

        string address = addressableKeys[i];

        // Place at the Scene view's pivot (where the camera is looking).
        Vector3 pos = SceneView.lastActiveSceneView != null
            ? SceneView.lastActiveSceneView.pivot
            : Vector3.zero;

        // Record Undo on the asset BEFORE mutating it.
        Undo.RecordObject(activeLayout, "Stamp Marker");

        activeLayout.markers.Add(new LayoutMarker
        {
            // Build an AssetReference from the Addressable's GUID.
            prefab = new AssetReferenceGameObject(AddressToGuid(address)),
            position = pos,
            eulerRotation = Vector3.zero
        });

        EditorUtility.SetDirty(activeLayout);   // mark for save
        statusLabel.text = $"Stamped '{address}' — {activeLayout.markers.Count} marker(s).";
    }

    void SaveLayout()
    {
        if (activeLayout == null) return;
        AssetDatabase.SaveAssets();             // write the .asset to disk
        statusLabel.text = $"Saved {activeLayout.markers.Count} marker(s).";
    }

    // Look up an Addressable entry's asset GUID from its address.
    static string AddressToGuid(string address)
    {
        var settings = AddressableAssetSettingsDefaultObject.Settings;
        foreach (var group in settings.groups)
            foreach (var entry in group.entries)
                if (entry.address == address)
                    return entry.guid;
        return null;
    }

That completes the Editor half: point the tool at a LevelLayout, select an Addressable prefab, frame the Scene view where you want it, and Stamp. Each stamp appends a fully runtime-safe marker to the asset. Now for the half that ships.

Step 4 — The Runtime LevelLoader

The loader is a plain MonoBehaviour — no Editor code — that takes a LevelLayout and brings it to life. For each marker it calls InstantiateAsync, awaits the handle, and keeps the handle so it can release the instance later. This is the "clear owner for every handle" pattern from Lesson 7.3, made concrete: the loader owns every instance it spawns and releases them all on unload.

using System.Collections.Generic;
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class LevelLoader : MonoBehaviour
{
    public LevelLayout layout;

    // We keep a handle per spawned instance so we can release every one.
    readonly List<AsyncOperationHandle<GameObject>> spawned = new();

    async void Start()
    {
        if (layout != null)
            await LoadAsync();
    }

    public async Task LoadAsync()
    {
        foreach (LayoutMarker marker in layout.markers)
        {
            if (marker.prefab == null || !marker.prefab.RuntimeKeyIsValid())
                continue;

            // Load-and-spawn this marker's Addressable at its saved transform.
            AsyncOperationHandle<GameObject> handle = marker.prefab.InstantiateAsync(
                marker.position, Quaternion.Euler(marker.eulerRotation));

            await handle.Task;   // wait for this one before the next (or fire them all)

            if (handle.Status == AsyncOperationStatus.Succeeded)
                spawned.Add(handle);          // track it for release
            else
                Debug.LogError($"Failed to spawn a marker in {layout.name}");
        }
        Debug.Log($"Level loaded: {spawned.Count} objects.");
    }

    public void Unload()
    {
        // THE GOLDEN RULE: release everything we instantiated.
        foreach (var handle in spawned)
            if (handle.IsValid())
                Addressables.ReleaseInstance(handle);   // destroys instance + drops ref count
        spawned.Clear();
    }

    void OnDestroy() => Unload();   // safety net — never leak on scene teardown
}

Two design choices are worth calling out. First, the loop awaits each spawn in turn for clarity; in production you'd often start all the loads and await them together (Task.WhenAll) so they overlap. Second, Unload and the OnDestroy safety net guarantee that no matter how the level ends — manual unload, scene change, object destruction — every InstantiateAsync gets its matching ReleaseInstance. That symmetry is the entire memory-safety story of the tool.

Step 5 — Run It

Wire the whole thing together with these numbered steps:

1. Make prefabs Addressable. Select a few prefabs, tick Addressable in their Inspector, and give them readable addresses (e.g. Props/Barrel) in the Window ▸ Asset Management ▸ Addressables ▸ Groups window.
2. Create a layout asset. In the Project window, Create ▸ Level Tools ▸ Level Layout. This is the LevelLayout ScriptableObject you'll author into.
3. Open the tool. Tools ▸ Level Layout Tool. Drag your new layout asset into the Layout Asset field.
4. Stamp markers. Select a prefab in the list, move the Scene view so its pivot is where you want the object, and click Stamp Marker at Scene View. Repeat for several prefabs and positions, then click Save.
5. Add the loader. Create an empty GameObject in a scene, add the LevelLoader component, and assign your layout asset to its Layout field.
6. Play. On enter Play mode, LevelLoader.Start runs LoadAsync, and each marker's Addressable instantiates at its saved transform. On exit Play mode, OnDestroy releases every instance.

💡 Verify the release. Open the Addressables Event Viewer (Window ▸ Asset Management ▸ Addressables ▸ Event Viewer) while you enter and exit Play mode. You'll watch the reference counts rise as markers spawn and fall back to zero on unload — visible proof the golden rule from Lesson 7.3 is holding.

What You Built & Extend It

You've shipped a complete little content pipeline. An Editor tool that reads your Addressables catalog and lets a designer compose a level as data; a serializable asset that carries that composition from edit time to runtime with no Editor dependency; and a runtime loader that streams the content in asynchronously and — critically — releases all of it cleanly. Every idea from Module 7 shows up: the assembly boundary, the serialization/Undo discipline, UI Toolkit windows, Addressable loading, and the release rule.

Hands-on Challenge

var clearBtn = new Button(() =>
{
    if (activeLayout == null) return;
    Undo.RecordObject(activeLayout, "Clear Markers");  // record BEFORE mutating
    activeLayout.markers.Clear();
    EditorUtility.SetDirty(activeLayout);
    statusLabel.text = "Cleared all markers.";
}) { text = "Clear All Markers" };
root.Add(clearBtn);

Summary

🚀 What's Next?

Module 7 gave you the tools of a professional Unity engineer — a customizable Editor and disciplined content management. The final module makes sure what you build actually works and ships. In Lesson 8.1: The Unity Test Framework — Edit & Play Mode Tests, you'll write automated tests for your game logic, the first step toward continuous integration and a confident release.