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.
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";
}
}Details
- Unity 2022.3 or higher
- Addressables 1.23.1 or higher
Follow these steps to install:
- Open the Package Manager from Window > Package Manager
- "+" button > Add package from git URL
- Enter the following
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.
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": "..."
}
}
}Create assets from Assets > Create > Address Definition Generator > Settings. This menu can also be opened from the context menu of the project view.
You can create multiple assets in the same project.
Set the save folder, namespace, and class name in the inspector of the settings asset.
| 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
{
// ...
}
}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.
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}");
}
}The IAddress interface itself is empty and serves as a marker interface. When implementing a custom address type:
- Constructor: Your class must have a public constructor that accepts a single
stringparameter - Marker interface: Implement the
IAddressinterface 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.
When using custom address types, generated constants change from const to static readonly:
- With
stringtype: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.
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.
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);
}
}Default setting is true.
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";
}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.
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 the comment is Create character icon address, the following function will be generated.
/// Create character icon address
public static string GetCharacterIcon(string type, long characterId)
{
return $"icon_{type}_chr{characterId:D5}";
}
Formatting rules are described in the following format.
| Syntax | Description |
|---|---|
| {xxx} | Any string. xxx is a string type argument of the function. |
| [xxx:N] | Any integer. xxx is an long type argument of the function. N is the number of digits. If xxx is less than N digits, it will be zero-padding. |
| [xxx] | Any integer. xxx is an long type argument of the function. No zero-padding. |
Identifier constraints
The identifier xxx in formatting rules must follow the pattern [a-zA-Z_][a-zA-Z0-9_]* (starts with a letter or underscore, followed by letters, digits, or underscores).
- Valid:
id,characterId,_type,item_001 - Invalid:
1st(starts with number),item-id(contains hyphen),type name(contains space)
Invalid syntax handling
When you define a rule with invalid syntax, code generation will be aborted and an error log will be displayed in the console. Examples:
{category:2}→ String arguments cannot use colon syntax[id:0]→ Digit count must be 1 or greater[id:]→ Missing digit count after colon
The error log will show the exact error description, the position where the error occurred, and the formatting rule that caused the error. This validation prevents syntax errors from resulting in broken code generation.
Press the Generate Address Definition Code button in the inspector of the settings asset to generate C# code.
You can also generate C# code by CLI.
| Option | Description |
|---|---|
-all |
Generate code for all settings assets found in the project |
-path |
Generate code for specific settings asset(s). Can specify multiple paths. |
| Code | Description |
|---|---|
| 0 | Success - All code generation completed successfully |
| 1 | Failure - An error occurred during code generation |
- Settings asset not found: If a specified path does not point to a valid settings asset, a warning is logged but execution continues with remaining assets
- Multiple assets: When using
-pathwith multiple assets, if one fails, the process exits immediately with code 1 - Generation failure: If code generation fails for any reason, an exception is logged and the process exits with code 1
macOS/Linux:
#!/bin/bash
# Example CI script for automated code generation
UNITY_PATH="/Applications/Unity/Hub/Editor/2022.3.62f1/Unity.app/Contents/MacOS/Unity"
PROJECT_PATH="$(pwd)"
SETTINGS_PATH="Assets/Settings/AddressDefinitionGeneratorSettings.asset"
$UNITY_PATH -quit -batchmode -projectPath "$PROJECT_PATH" \
-executeMethod AddressDefinitionGenerator.Editor.CLI.AddressDefinitionGeneratorCLI.Execute \
-path "$SETTINGS_PATH"
if [ $? -eq 0 ]; then
echo "Code generation succeeded"
else
echo "Code generation failed"
exit 1
fiWindows (PowerShell):
# Example CI script for automated code generation
$UNITY_PATH = "C:\Program Files\Unity\Hub\Editor\2022.3.62f1\Editor\Unity.exe"
$PROJECT_PATH = Get-Location
$SETTINGS_PATH = "Assets/Settings/AddressDefinitionGeneratorSettings.asset"
& $UNITY_PATH -quit -batchmode -projectPath "$PROJECT_PATH" `
-executeMethod AddressDefinitionGenerator.Editor.CLI.AddressDefinitionGeneratorCLI.Execute `
-path "$SETTINGS_PATH"
if ($LASTEXITCODE -eq 0) {
Write-Host "Code generation succeeded"
} else {
Write-Host "Code generation failed"
exit 1
}