# needle-mirror/com.unity.addressables architecture

> Architecture diagram of the GitHub repository needle-mirror/com.unity.addressables, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/needle-mirror/com.unity.addressables
- Repository: https://github.com/needle-mirror/com.unity.addressables

## Overview

##### Project Type and Purpose
- This is an open-source Unity package (Unity Addressables) that provides a framework for managing, building, and loading asset bundles in Unity projects.
- Key features:
- Editor extension (under “Editor/…”) that integrates into the Unity build pipeline and UI.
- Runtime library (under “Runtime/…”) that implements asynchronous loading, caching, and resource‐provider abstractions.
- Documentation (under “Documentation~/…”) and extensive automated tests.

##### High-Level Components
a. Editor Module
– Build scripts and hooks (Editor/Build/…, AddressablesBuildScriptHooks)
– Asset-group and profile inspectors and windows (Editor/GUI/…, Editor/Settings/…)
– Analyze and reporting tools (Editor/AnalyzeRules, BuildReportVisualizer, Diagnostics/Profiler)
b. Runtime Module
– Public API façade (Runtime/Addressables.cs)
– Internal implementation (Runtime/AddressablesImpl, ResourceManager)
– Initialization pipeline (Runtime/Initialization/…)
– Resource locators (Runtime/ResourceLocators/…)
– Async operation system (Runtime/ResourceManager/AsyncOperations/…)
– Resource providers (Runtime/ResourceManager/ResourceProviders/…)
– Utility classes (Runtime/Utility/SerializationUtilities, AssetReferenceUtilities, etc.)
c. Tests
– Editor tests (Tests/Editor/…) and Runtime tests (Tests/Runtime/…)
– Sample projects (Samples~/…)

##### Component Relationships & Data Flow
- Editor time:
1. User configures Addressable Groups & Profiles in the Unity Editor UI
2. Build pipeline scripts (AddressablesDataBuilders) run, invoking BuildPipelineTasks to produce AssetBundles and ContentCatalogs
3. AnalyzeRules modules generate build reports and diagnostics
- Runtime:
1. Game code calls Addressables.LoadAssetAsync or Other API
2. AddressablesImpl forwards request to ResourceManager
3. ResourceManager queries IResourceLocator instances to find asset locations in the ContentCatalog
4. ResourceManager dispatches AsyncOperations and delegates to the appropriate IResourceProvider (e.g., AssetBundleProvider, JSONAssetProvider, SceneProvider, WebRequestOperation)
5. AsyncOperationHandle completes, asset is returned to game code
6. CcdManager handles remote catalog management if enabled

##### Architectural Patterns & Principles
- Modularity: separate Editor vs. Runtime assemblies via asmdef files
- Provider pattern: pluggable IResourceProvider implementations
- Chain of responsibility / pipeline for AsyncOperations
- Data‐driven: ContentCatalogs generated at build time drive runtime behavior
- Dependency inversion: high‐level ResourceManager uses abstractions (IResourceLocator, IResourceProvider)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-Time (Editor)
    subgraph "Build-Time (Editor)"
        UnityEditor["Unity Editor UI"]:::external
        AddressableGroupsWindow["AddressableAssetsWindow"]:::editor
        Settings["AddressableAssetSettingsInspector"]:::editor
        BuildScripts["AddressablesBuildScriptHooks"]:::editor
        DataBuilders["DataBuilders"]:::editor
        BuildTasks["BuildPipelineTasks"]:::editor
        AnalyzeRules["AnalyzeRule"]:::editor
        ReportVisualizer["BuildReportWindow"]:::editor
        Profiler["AddressablesProfilerModule"]:::editor
    end

    %% Runtime
    subgraph "Runtime"
        GameCode["Game Code"]:::external
        API["Addressables.cs"]:::runtime
        Impl["AddressablesImpl"]:::runtime
        ResourceManager["ResourceManager"]:::runtime
        Init["InitializationOperation"]:::runtime
        Locators["ContentCatalogData"]:::runtime
        AsyncOps["AsyncOperationBase"]:::runtime
        Providers["AssetBundleProvider"]:::runtime
        Ccd["CcdManager"]:::runtime
        Utils["SerializationUtilities"]:::runtime
    end

    %% Artifacts & External
    subgraph "Artifacts & External"
        Catalog["ContentCatalog + AssetBundles"]:::artifact
        CDN["External CDN"]:::external
    end

    %% Tests & Samples
    subgraph "Tests & Samples"
        EditorTests["Tests/Editor"]:::test
        RuntimeTests["Tests/Runtime"]:::test
        Samples["Samples~"]:::test
    end

    %% Build-Time Flow
    UnityEditor -->|configures| AddressableGroupsWindow
    AddressableGroupsWindow -->|opens| Settings
    AddressableGroupsWindow -->|invokes| BuildScripts
    Settings -->|used by| BuildScripts
    BuildScripts -->|calls| DataBuilders
    DataBuilders -->|runs| BuildTasks
    BuildTasks -->|generates| Catalog
    BuildTasks -->|evaluates| AnalyzeRules
    AnalyzeRules -->|reports to| ReportVisualizer
    ReportVisualizer -->|profiles with| Profiler

    %% Runtime Flow
    GameCode -->|LoadAssetAsync| API
    API -->|forwards request| Impl
    Impl -->|uses| ResourceManager
    ResourceManager -->|initializes via| Init
    ResourceManager -->|queries| Locators
    ResourceManager -->|dispatches| AsyncOps
    AsyncOps -->|delegates to| Providers
    Providers -->|fetches from| Catalog
    Ccd -->|fetches remote| CDN
    ResourceManager -->|manages remote| Ccd

    %% Tests & Samples Connections
    EditorTests -->|covers| AddressableGroupsWindow
    RuntimeTests -->|covers| Impl
    Samples -->|includes custom rules| AnalyzeRules

    %% Click Events
    click BuildScripts "https://github.com/needle-mirror/com.unity.addressables/blob/master/Editor/Build/AddressablesBuildScriptHooks.cs"
    click DataBuilders "https://github.com/needle-mirror/com.unity.addressables/blob/master/Editor/Build/DataBuilders/AddressableAssetsBuildContext.cs"
    click BuildTasks "https://github.com/needle-mirror/com.unity.addressables/blob/master/Editor/Build/BuildPipelineTasks/BuildLayoutGenerationTask.cs"
    click AnalyzeRules "https://github.com/needle-mirror/com.unity.addressables/blob/master/Editor/Build/AnalyzeRules/AnalyzeRule.cs"
    click ReportVisualizer "https://github.com/needle-mirror/com.unity.addressables/blob/master/Editor/BuildReportVisualizer/BuildReportWindow.cs"
    click Profiler "https://github.com/needle-mirror/com.unity.addressables/blob/master/Editor/Diagnostics/Profiler/AddressablesProfilerModule.cs"
    click AddressableGroupsWindow "https://github.com/needle-mirror/com.unity.addressables/blob/master/Editor/GUI/AddressableAssetsWindow.cs"
    click Settings "https://github.com/needle-mirror/com.unity.addressables/blob/master/Editor/Settings/AddressableAssetSettingsInspector.cs"
    click API "https://github.com/needle-mirror/com.unity.addressables/blob/master/Runtime/Addressables.cs"
    click Impl "https://github.com/needle-mirror/com.unity.addressables/blob/master/Runtime/AddressablesImpl.cs"
    click ResourceManager "https://github.com/needle-mirror/com.unity.addressables/blob/master/Runtime/ResourceManager/ResourceManager.cs"
    click Init "https://github.com/needle-mirror/com.unity.addressables/blob/master/Runtime/Initialization/InitializationOperation.cs"
    click Locators "https://github.com/needle-mirror/com.unity.addressables/blob/master/Runtime/ResourceLocators/ContentCatalogData.cs"
    click AsyncOps "https://github.com/needle-mirror/com.unity.addressables/blob/master/Runtime/ResourceManager/AsyncOperations/AsyncOperationBase.cs"
    click Providers "https://github.com/needle-mirror/com.unity.addressables/blob/master/Runtime/ResourceManager/ResourceProviders/AssetBundleProvider.cs"
    click Ccd "https://github.com/needle-mirror/com.unity.addressables/blob/master/Runtime/ResourceManager/CcdManager.cs"
    click Utils "https://github.com/needle-mirror/com.unity.addressables/blob/master/Runtime/Utility/SerializationUtilities.cs"
    click EditorTests "https://github.com/needle-mirror/com.unity.addressables/tree/master/Tests/Editor"
    click RuntimeTests "https://github.com/needle-mirror/com.unity.addressables/tree/master/Tests/Runtime"
    click Samples "https://github.com/needle-mirror/com.unity.addressables/tree/master/Samples~/"

    %% Styles
    classDef editor fill:lightblue,stroke:#333,stroke-width:1px
    classDef runtime fill:lightgreen,stroke:#333,stroke-width:1px
    classDef artifact fill:lightyellow,stroke:#333,stroke-width:1px
    classDef test fill:#f9f,stroke:#333,stroke-width:1px
    classDef external fill:#fff,stroke:#999,stroke-dasharray:5 5,stroke-width:1px
```
