Address Definition Generator

Docs (English, 日本語)

The Address Definition Generator is a tool for generating code with string constants representing the addresses of Unity's Addressables. It also allows you to set formatting rules to generate functions that can construct addresses by accepting arbitrary arguments.

For example, suppose you have the following groups and addresses.

<p align="center"> <img src="./Documentation~/Images/groups_01.png" alt="Groups"> </p>

Using this tool, you can generate the following C# code.

public partial class AddressDefinition
{
    public partial class BuiltInData
    {
        public const string Resources = "Resources";
        public const string EditorSceneList = "EditorSceneList";
    }
    public partial class Group0
    {
        /// This is test comment.
        public static string GetImage(long n)
        {
            return $"img_{n:D3}";
        }
    }
    public partial class Group1
    {
        public const string black = "black";
        public static string GetCard(long id)
        {
            return $"card{id:D3}";
        }
    }
    public partial class Group2
    {
        public const string sp_red_32 = "sp_red_32";
        public const string sp_blue_32 = "sp_blue_32";
    }
}

Table of Contents

<details> <summary>Details</summary>

• Setup
  • Requirements
  • Installation
• Usage
  • Create a settings asset
  • Set the save folder, namespace, and class name
  • Set the custom address type
    • Implementation Requirements
    • Why use const vs static readonly?
  • Use ZString.Format
  • Choose whether to create a class for each group
  • Set the group provider
  • Set the rule provider
    • Formatting Rules
  • Generate C# code
  • Command Line Interface (CLI)
    • CLI Options
    • Exit Codes
    • Error Handling Behavior
    • CI/CD Integration Example

</details>

Setup

Requirements

• Unity 2022.3 or higher
• Addressables 1.23.1 or higher

Installation

Follow these steps to install:

1. Open the Package Manager from Window > Package Manager
2. "+" button > Add package from git URL
3. Enter the following
   • https://github.com/CyberAgentGameEntertainment/AddressDefinitionGenerator.git?path=/Packages/AddressDefinitionGenerator

Or, open Packages/manifest.json and add the following to the dependencies block.

{
    "dependencies": {
        "jp.co.cyberagent.address-definition-generator": "https://github.com/CyberAgentGameEntertainment/AddressDefinitionGenerator.git?path=/Packages/AddressDefinitionGenerator"
    }
}

If you want to set the target version, write as follows.

• https://github.com/CyberAgentGameEntertainment/AddressDefinitionGenerator.git?path=/Packages/AddressDefinitionGenerator#v1.0.0

To update the version, rewrite the version as described above.
If you don't want to specify a version, you can also update the version by editing the hash of this library in the package-lock.json file.

{
    "dependencies": {
        "jp.co.cyberagent.address-definition-generator": {
            "version": "https://github.com/CyberAgentGameEntertainment/AddressDefinitionGenerator.git?path=/Packages/AddressDefinitionGenerator",
            "depth": 0,
            "source": "git",
            "dependencies": {},
            "hash": "..."
        }
    }
}

Usage

Create a settings asset

Create assets from Assets > Create > Address Definition Generator > Settings. This menu can also be opened from the context menu of the project view.

<p align="center"> <img src="./Documentation~/Images/create_assets_01.png" alt="Create Settings"> </p>

You can create multiple assets in the same project.

Set the save folder, namespace, and class name

Set the save folder, namespace, and class name in the inspector of the settings asset.

<p align="center"> <img src="./Documentation~/Images/properties_01.png" alt="Properties"> </p>

| Property | Description | |----------------|---------------------------------------------| | Save Folder | The folder where the C# file will be saved. | | Namespace Name | The namespace of the generated class. | | Class Name | The name of the generated class. |

For example, if you set the save folder to Assets/Scripts, the namespace name to Generated, and the class name to Address, the following code will be generated as Assets/Scripts/Address.cs.

namespace Generated
{
    public partial class Address
    {
        // ...
    }
}

Set the custom address type

Can represent an address with a non-string type that implements the IAddress interface. This type must have a constructor that takes a string type argument.
If no type is specified, the string type is used.

<p align="center"> <img src="./Documentation~/Images/custom_address_type_01.png" alt="Custom Address Type"> </p>

The following is an example of the code generated when a custom address type SampleAddress is set.

public partial class Group1
{
    public static readonly AddressDefinitionGenerator.SampleAddress black = new AddressDefinitionGenerator.SampleAddress("black");
    public static AddressDefinitionGenerator.SampleAddress GetCard(long id)
    {
        return new AddressDefinitionGenerator.SampleAddress($"card{id:D3}");
    }
}

Implementation Requirements

The IAddress interface itself is empty and serves as a marker interface. When implementing a custom address type:

1. Constructor: Your class must have a public constructor that accepts a single string parameter
2. Marker interface: Implement the IAddress interface to indicate this type can be used as an address

Address instances should be immutable for safety.

Reference implementation:

See SampleAddress in Packages/AddressDefinitionGenerator/Runtime/Scripts/SampleAddress.cs for an example implementation.

Why use const vs static readonly?

When using custom address types, generated constants change from const to static readonly:

• With string type: public const string black = "black";
• With custom type: public static readonly SampleAddress black = new SampleAddress("black");

This is because C# language specifications only allow primitive types and strings to be declared as const. Custom class instances must use static readonly instead.

Use ZString.Format

If you have imported a ZString into your project, you can use ZString.Format for address construction.
If not imported, this parameter is deactivated and behaves as disabled.

<p align="center"> <img src="./Documentation~/Images/zstring_format_01.png" alt="ZString Format"> </p>

The following is an example of the code generated when using ZString.Format.

public partial class Group1
{
    public const string black = "black";
    public static string GetCard(long id)
    {
        return ZString.Format("card{0:D3}", id);
    }
}

Choose whether to create a class for each group

Default setting is true.

<p align="center"> <img src="./Documentation~/Images/group_class_01.png" alt="Group Class"> </p>

If true, and there are three groups, GroupA, GroupB and GroupC, class is generated for each group.

public partial class AddressDefinition
{
    public partial class GroupA
    {
        public const string XXX = "XXX";
    }
    public partial class GroupB
    {
        public static string GetCard(long id)
        {
            // ...
        }
    }
    public partial class GroupC
    {
        public const string ZZZ = "ZZZ";
    }
}

If false, and there are three groups, GroupA, GroupB and GroupC, they are created as members of the top-level class without creating a class.

public partial class AddressDefinition
{
    public const string XXX = "XXX";
    public static string GetCard(long id)
    {
        // ...
    }
    public const string ZZZ = "ZZZ";
}

Set the group provider

The group provider is a class that provides a list of groups to be referenced during code generation.
Default setting is DefaultGroupProvider. DefaultGroupProvider provides a list of groups selected on the inspector from the list of groups in AddressableAssetSettings.
You can also switch to your own group provider by implementing IGroupProvider.

<p align="center"> <img src="./Documentation~/Images/group_provider_01.png" alt="Group Provider"> </p>

Set the rule provider

The rule provider is a class that provides formatting rules for addresses. Addresses matching the formatting rules are generated as functions that construct addresses, not as string constants. Default setting is DefaultRuleProvider. DefaultRuleProvider provides a list of formatting rules registered on the inspector. You can also switch to your own rule provider by implementing IRuleProvider.

For example, the formatting rule icon_{type}_chr[characterId:5] matches the following addresses.

• icon_small_chr00001
• icon_medium_chr01001
• icon_large_chr20100

If the name of this rule is CharacterIcon and t