Skip to content

README_JA.md

Latest commit

 

History

History
416 lines (313 loc) · 16.3 KB

README_JA.md

File metadata and controls

416 lines (313 loc) · 16.3 KB

Address Definition Generator

ドキュメント (English, 日本語)

Address Definition Generatorは、UnityのAddressablesのアドレスを文字列定数として表現するコードを生成するツールです。
書式ルールを設定することで、任意の引数を受け取ってアドレスを構築する関数を生成することもできます。

例えば下図のようなグループとアドレスがあるとします。

Groups

このツールを使用すると以下のようなC#コードを生成できます。

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";
    }
}

目次

詳細

セットアップ

要件

  • Unity 2022.3 以降
  • Addressables 1.23.1 以降

インストール

インストールは以下の手順で行います。

  1. Window > Package Manager を選択
  2. 「+」ボタン > Add package from git URL を選択
  3. 以下を入力

あるいは Packages/manifest.json を開き、dependencies ブロックに以下を追記します。

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

バージョンを指定したい場合には以下のように記述します（バージョンは適宜書き換えてください）。

バージョンを更新するには上述の手順でバージョンを書き換えてください。
バージョンを指定しない場合には、Packages/package-lock.json ファイルを開いて本ライブラリの箇所のハッシュを書き換えることで更新できます。

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

使い方

設定アセットの作成

Assets > Create > Address Definition Generator > Settings を選択して設定アセットを作成します。
このメニューはプロジェクトビューのコンテキストメニューからも開くことができます。

Create Settings

設定アセットはプロジェクト内に複数作成できます。

保存フォルダ、名前空間、クラス名を設定する

作成した設定アセットのインスペクタにて保存フォルダ、名前空間、クラス名を設定します。

Properties

項目 説明
Save Folder C#ファイルを保存するフォルダ
Namespace Name 生成するC#コードの名前空間
Class Name 生成するC#コードのクラス名

例えば Save Folder を Assets/Scripts 、 Namespace Name を Generated 、 Class Name を Address とすると以下のような内容で Assets/Scripts/Address.cs というファイルが生成されます。

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

カスタムアドレス型を設定する

IAddress インターフェースを実装した任意の型でアドレスを表現できます。この型は string 型の引数を取るコンストラクタを持つ必要があります。
型を指定しない場合は string 型が使用されます。

Custom Address Type

以下は SampleAddress というカスタムアドレス型を設定した場合に生成されるコード例です。

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}");
    }
}

実装要件

IAddress インターフェースは空のマーカーインターフェースとして設計されています。カスタムアドレス型を実装する際は以下を満たす必要があります。

  1. コンストラクタ: string 型の引数を 1 つ受け取る public コンストラクタを持つこと
  2. マーカーインターフェース: IAddress インターフェースを実装し、この型がアドレスとして使用可能であることを示す

安全性のため、アドレスインスタンスは不変（immutable）であることが推奨です

参考実装:

実装例については Packages/AddressDefinitionGenerator/Runtime/Scripts/SampleAddress.cs の SampleAddress を参照してください。

constとstatic readonlyの違いについて

カスタムアドレス型を使用すると、生成される定数が const から static readonly に変わります。

  • string 型の場合: public const string black = "black";
  • カスタム型の場合: public static readonly SampleAddress black = new SampleAddress("black");

これはC#言語仕様により、const として宣言できるのはプリミティブ型と文字列のみであるためです。カスタムクラスのインスタンスは static readonly を使用する必要があります。

ZString.Formatを使用する

ZStringをプロジェクトに導入している場合、アドレスの構築に ZString.Format を使用できます。
導入していない場合、このパラメータは非アクティブとなり、無効と同等の動作をします。

ZString Format

以下は ZString.Format を使用した場合に生成されるコード例です。

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

グループごとにクラスを作成するか選ぶ

デフォルト設定は true です。

Group Class

true の場合、GroupA, GroupB, GroupCの3つのグループがあるとすると、それぞれのグループに対してクラスが生成されます。

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";
    }
}

false の場合、GroupA, GroupB, GroupCの3つのグループがあってもクラスを作らずに、最上位クラスのメンバとして生成されます。

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

グループプロバイダを設定する

グループプロバイダとはコード生成の際に参照するグループ一覧を提供するクラスです。
初期状態では DefaultGroupProvider が設定されています。DefaultGroupProvider は AddressableAssetSettings のグループからインスペクタ上で選択されたグループ一覧を提供します。
IGroupProvider を実装することで独自のグループプロバイダに切り替えることもできます。

Group Provider

ルールプロバイダを設定する

ルールプロバイダとはアドレスの書式ルールを提供するクラスです。
提供された書式ルールにマッチしたアドレスは文字列定数ではなくアドレスを構築する関数として生成されます。
初期状態では DefaultRuleProvider が設定されています。DefaultRuleProvider は インスペクタ上でリストに登録された書式ルールを提供します。
IRuleProvider を実装することで独自のルールプロバイダに切り替えることもできます。

例えば icon_{type}_chr[characterId:5] という書式ルールは以下のようなアドレスにマッチします。

  • icon_small_chr00001
  • icon_medium_chr01001
  • icon_large_chr20100

このルールの名前が CharacterIcon 、コメントが Create character icon address とすると以下のような関数として生成されます。

/// Create character icon address
public static string GetCharacterIcon(string type, long characterId)
{
    return $"icon_{type}_chr{characterId:D5}";
}

Rule Provider

書式ルール

書式ルールは以下のような形式で記述します。

構文 説明
{xxx} 任意の文字列。xxxは関数の文字列型引数
[xxx:N] 任意の整数。xxxは関数の整数型引数。Nは桁数。xxxがN桁に満たなければ0埋め。
[xxx] 任意の整数。xxxは関数の整数型引数。0埋めなし

識別子の制約

書式ルール内の識別子 xxx は [a-zA-Z_][a-zA-Z0-9_]* のパターンに従う必要があります（英字またはアンダースコアで開始し、その後は英字、数字、アンダースコア）。

  • 有効: id, characterId, _type, item_001
  • 無効: 1st（数字で始まる）、item-id（ハイフンを含む）、type name（スペースを含む）

無効な書式の処理

無効な書式を含むルールを定義した場合、コード生成は中断されコンソールにエラーログが表示されます。

  • {category:2} → 文字列引数にはコロン構文は使用できません
  • [id:0] → 桁数は 1 以上である必要があります
  • [id:] → コロンの後の桁数が不足しています

エラーログには、エラーの正確な説明、エラーが発生した位置、エラーの原因となった書式ルールが表示されます。この検証により、書式ミスが壊れたコード生成につながることを防ぎます。

C#コードを生成する

設定アセットのインスペクタにある Generate Address Definition Code ボタンを押すとC#コードが生成されます。

Generate Code

コマンドラインインターフェース (CLI)

コマンドラインインターフェース (CLI) でC#コードを生成することもできます。

CLIオプション

オプション 説明
-all プロジェクト内で見つかったすべての設定アセットに対してコード生成を実行します
-path 特定の設定アセットに対してコード生成を実行します。複数のパスを指定することも可能です。

終了コード

コード 説明
0 成功 - すべてのコード生成が正常に完了しました
1 失敗 - コード生成中にエラーが発生しました

エラーハンドリングの動作

  • 設定アセットが見つからない場合: 指定されたパスが有効な設定アセットを指していない場合、警告ログが出力されますが、残りのアセットの処理は継続されます
  • 複数のアセットを指定した場合: -path で複数のアセットを指定した際、いずれか1つが失敗するとプロセスは終了コード1で即座に終了します
  • 生成失敗: コード生成が何らかの理由で失敗した場合、例外がログに記録され、プロセスは終了コード1で終了します

CI/CD統合の例

macOS/Linux:

#!/bin/bash
# 自動コード生成のためのCIスクリプト例

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 "コード生成が成功しました"
else
  echo "コード生成が失敗しました"
  exit 1
fi

Windows (PowerShell):

# 自動コード生成のためのCIスクリプト例

$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 "コード生成が成功しました"
} else {
    Write-Host "コード生成が失敗しました"
    exit 1
}