DOCSEARCHbyAlgolia
Submit Docs

Smart Addresser

repository·main·Indexed 20 days ago

https://github.com/cyberagentgameentertainment/smartaddresser

A Unity tool for automating the management of addresses, labels, and versioning within the Addressable Asset System. It replaces manual asset registration with a rule-based system manageable via GUI or CLI, featuring rule-based addressing, label automation, semantic version management, and CI/CD integration for automated validation and application in build pipelines.

Tokens
14.3K
Snippets
17
Records
46
Agent score
63%

What's inside Smart Addresser

  1. What is Smart Addresser?

    main

    Smart Addresser is a tool designed to automate the assignment of addresses and labels within Unity's Addressable Asset System. Instead of manually dragging and dropping assets into the Addressables Groups window, you can define rules using a GUI to automatically assign addresses based on criteria such as:

    • All Prefabs within a specific folder.
    • All assets placed inside a folder named "Addressables".
    • All assets whose paths match a specific regular expression.

    Additionally, it includes a version control feature that allows you to exclude assets from builds by specifying a version during the build process. The tool also provides validation utilities and a CLI for integration into CI/CD pipelines.

  2. What is Smart Addresser and how does it work?

    main

    Smart Addresser is an automation tool for Unity's Addressable Asset System. It allows developers to automate the assignment of addresses and labels to assets using rule-based logic instead of manual drag-and-drop.

    Key features include:

    • Rule-based Addressing: Assign addresses based on folder paths, file names, or regular expressions.
    • Label Automation: Automatically apply labels to assets based on specific criteria.
    • Version Management: Assign version numbers to assets to exclude pre-release content from builds.
    • Validation: A built-in tool to detect rule conflicts, such as multiple addresses for one asset or multiple assets sharing one address.
    • CI/CD Integration: A Command Line Interface (CLI) for automated validation and application in build pipelines.

  3. Manage multiple rules with CompositeLayoutRuleData

    main

    CompositeLayoutRuleData allows you to manage and apply multiple LayoutRuleData assets transparently as a single unit. When applied, all configured LayoutRuleData rules are executed together.

    Usage:

    1. Create the Asset: In the Unity Editor, go to Assets > Create > Smart Addresser > Composite Layout Rule Data.
    2. Configure Rules: In the Inspector, add the LayoutRuleData assets you wish to group into the Layout Rules list.
    3. Apply Rules: Click the Apply button at the top of the Inspector to apply all rules in the list.
    4. Nesting: You can assign a CompositeLayoutRuleData to the PrimaryData field of another LayoutRuleData.

    Validation Notes:

    • Validation is performed on individual LayoutRuleData units only.
    • CompositeLayoutRuleData does not detect contradictions between the different LayoutRuleData assets it contains.
    • Validation result files are named using the index of the LayoutRuleData within the composite asset, e.g., [filename]_0.json, [filename]_1.json, etc.

  4. How versioning works in Smart Addresser

    main

    Smart Addresser allows you to assign versions to individual assets. When applying layout rules to the Addressable system, you can specify a version range (using a Version Expression) to ensure only assets within that specific version range are registered as Addressable entries. This is primarily intended to exclude assets intended for future releases from the current build.

    Versioning Specifications

    • Format: Follows Semantic Versioning (e.g., 1.2.3, 2.1.0-preview.7).
    • Range Syntax: Uses Unity's Version Define expressions syntax:
      • [1.3,3.4.1] means 1.3.0 <= x <= 3.4.1
      • (1.3.0,3.4) means 1.3.0 < x < 3.4.0
      • [1.1,3.4) means 1.1.0 <= x < 3.4.0
      • (0.2.4,5.6.2-preview.2] means 0.2.4 < x <= 5.6.2-preview.2
      • [2.4.5] means x = 2.4.5
      • 2.1.0-preview.7 means x >= 2.1.0-preview.7
    • Constraints: Do not use spaces in expressions; wildcards are not supported.

    Dependency Warning

    Avoid having low-version assets reference high-version assets. For example, if Asset A (v1.2.0) references Asset B (v1.3.0), and you build with a range of [1.0.0, 1.2.0], Asset B might be pulled into the build along with Asset A, potentially causing unintended updates.

  5. How CompositeLayoutRuleData works

    main

    A CompositeLayoutRuleData asset allows you to manage multiple LayoutRuleData assets as a single unit. It integrates and applies all rules from its configured children simultaneously.

    Usage:

    1. Creation: Select Assets > Create > Smart Addresser > Composite Layout Rule Data in the Unity Editor.
    2. Configuration: In the Inspector, add multiple LayoutRuleData assets to the Layout Rules list.
    3. Application: Click the Apply button at the top of the Inspector to apply all integrated rules. You can also set a CompositeLayoutRuleData as the PrimaryData.

    Important Limitations:

    • Validation: Validation can only be performed on individual LayoutRuleData assets. CompositeLayoutRuleData does not detect conflicts or contradictions between the rules it contains.
    • Output Files: When validating a composite asset, the resulting validation files are suffixed by the index of the child LayoutRuleData (e.g., [filename]_0.json, [filename]_1.json).

  6. Manage Asset Versioning with Version Rules

    main

    Smart Addresser allows you to assign versions to assets using Semantic Versioning (e.g., 1.2.3 or 2.1.0-preview.7). This is useful for excluding pre-released assets from builds.

    Creating Version Rules

    1. Open the Layout Rule Editor and click the + button in the top left to add a new Version Rule.
    2. In the Asset Groups tab, specify which assets to target (using the same logic as Address Rules).
    3. In the Version Provider tab, specify the version to be assigned (e.g., 1.2.0).

    Applying Version Ranges

    In the Settings tab of the Layout Rule Editor, you can set a Version Expression to filter which assets are registered to the Addressable Asset System.

    • Use Version Define expressions for ranges (e.g., [1.3, 3.4.1] for 1.3.0 <= x <= 3.4.1).
    • Check Exclude Unversioned to ignore assets without a version.

    Important: Versioning and Dependencies

    Be cautious when a lower-version asset references a higher-version asset. For example, if version 1.2.0 of Asset A references version 1.3.0 of Asset B, building 1.3.0 will cause Asset A to be updated as well.

    Custom Version Parsing

    To use a custom version range expression, implement the IVersionExpressionParser interface and assign the script in Project Settings > Smart Addresser > Version Expression Parser.

  7. Configure version rules for assets

    main

    You can manage asset versions via the Version Rules tab in the Layout Rule Editor.

    1. Add Rules: Click the + button in the top-left to create a new version rule. You can rename these items by clicking them.
    2. Assign Assets: Use the Asset Groups tab to specify which assets the rule applies to (similar to Address Rules).
    3. Set Version: Use the Version Provider tab to define the version name (e.g., 1.2.0). You can use the Change Provider button to select different version providers.
    4. Apply to Addressables: In the Layout Rule Editor > Settings tab, set the Version Expression property to define the range of versions to include.
      • Check Exclude Unversioned to ignore assets that have no version assigned.

  8. Create a Layout Rule Data asset

    main

    Smart Addresser stores all addressing and labeling rules in a Layout Rule Data asset. You must create this asset to begin configuring rules.

    1. In the Unity Project window, go to Assets > Create > Smart Addresser > Layout Rule Data.
    2. You can create multiple such assets and store them in any folder under the Editor folder.
    3. To edit the rules, double-click the asset or click the Open Editor button in the Inspector to launch the Layout Rule Editor.
    Assets > Create > Smart Addresser > Layout Rule Data

  10. Validate rules using Layout Viewer

    main

    To prevent issues like one asset having multiple addresses or one address mapping to multiple assets, use the Layout Viewer.

    1. Open the tool via Window > Smart Addresser > Layout Viewer.
    2. The tool automatically validates your rules and displays a list of Addressable Groups and their addresses along with validation results.
    3. Select any row with warnings or errors to see details in the bottom pane.

    Configuration: You can control whether rule violations are treated as errors or warnings in Project Settings > Smart Addresser > Validation Settings.

  11. Install Smart Addresser via Unity Package Manager

    main

    To install Smart Addresser, use the Unity Package Manager:

    1. Open Window > Package Manager.
    2. Click the "+" button and select Add package from git URL.
    3. Enter the following URL: https://github.com/CyberAgentGameEntertainment/SmartAddresser.git?path=/Assets/SmartAddresser

    To target a specific version, append the version number to the URL: https://github.com/CyberAgentGameEntertainment/SmartAddresser.git?path=/Assets/SmartAddresser#1.0.0

    https://github.com/CyberAgentGameEntertainment/SmartAddresser.git?path=/Assets/SmartAddresser

  12. Configure Address Rules in Layout Rule Editor

    main

    In the Address Rules tab of the Layout Rule Editor, you define how assets are assigned to Addressable Groups.

    1. Select Group: In the Groups column, check the Control checkbox for the Addressable Asset Groups you want Smart Addresser to manage.
    2. Define Asset Groups: In the Asset Groups tab (right panel), specify which assets to target.
      • Use an Object Filter to target specific folders (e.g., a folder named "Characters").
      • Multiple filters within one Asset Group are combined with AND logic.
      • To use OR logic, click Add Asset Group to create a separate group.
    3. Define Address Provider: In the Address Provider tab, specify how the address is generated. For example, setting the Source to File Name Without Extensions will use the filename as the address.