hz-unity-tmp-resources

TextMesh Pro リソースのインポート

このスキルを使用するタイミング

次のいずれかが検出された場合、このスキルを自動的に使用します。

• シーン内の TMP テキストがピンク／マゼンタで表示される
• LiberationSans SDF、TMP Settings、または TMP マテリアルの欠落に関するコンソールエラーがある
• プロジェクトで初めて TMP テキスト要素を作成する
• ユーザーが TextMesh Pro のセットアップまたは UI テキストの作成を依頼する
• Assets/TextMesh Pro/Resources/ フォルダーが存在しない

エディターの操作

以下の各手順はすべて、開いているエディターに対して unity-cli を使って実行します。まず接続可能であることを確認し、複数のエディターが起動している可能性がある場合は --project-path <proj> を指定してください。

unity status --format json          # look for state "ready"

接続方法、--project-path、Safe Mode からの復旧については、unity-cli スキルを参照してください。代わりに Unity MCP サーバーを使う場合は、references/unity-mcp-fallback.md を参照してください。

ステップ 1：TMP リソースがすでにインポートされているか確認する

unity command find_assets --type TMP_Settings --format json
unity command find_assets --name "LiberationSans SDF" --format json

find_assets では --type／--name／--label のうち少なくとも 1 つが必要です。どれも指定しないと、"At least one of type, name, or label is required." というエラーで失敗します。いずれか 1 つだけで十分です。--search_in は検索範囲を絞り込むだけの任意の指定です。

data.result.count を確認してください。両方が 0 の場合、リソースはインポートされていません。見つかった場合は、ここで終了します。対応は不要です。

count: 0 がエラーではないケースが 2 つあるため、必ず success ではなく count を基準に判断してください。

• 解決できない --type（TMP がインポートされていないため、TMP_Settings が読み込み済みの型ではない）の場合、success と count: 0 が返されます。これは、ここでは「未インポート」を示す値です。
• 存在しない --search_in フォルダーを指定した場合も、success と count: 0 が返されます。

ステップ 2：TMP Essential Resources をインポートする

重要：TMP のインポート時には、手動操作が必要なモーダルの Unity ダイアログが開きます。完全に自動化することはできません。

unity command menu --path "Window/TextMeshPro/Import TMP Essential Resources"

実行後、必ず次の操作を行ってください。

1. ユーザーに次のように伝えます。「Unity で Import Unity Package ダイアログが開きました。Import ボタンをクリックして、完了したらお知らせください。」
2. 先に進む前に、ユーザーの確認を待ちます。
3. 確認なしにインポートが成功したと判断してはいけません。

モーダルによってエディターがブロックされるため、このリクエストがタイムアウトしたり、応答が遅れたりすることがあります。これは失敗ではなく、ダイアログでユーザーの操作を待っている状態です。

ステップ 3：インポートが成功したことを確認する

ユーザーの確認後、チェックを再実行し、両方のアセットが存在することを確認してください。

unity command find_assets --name "LiberationSans SDF" --format json
unity command find_assets --type TMP_Settings --format json

両方の count が 0 以外であることが必要です。いずれかが 0 の場合、インポートは完了していません。UI 作業に進まないでください。エディターでのインポートは作業の半分にすぎません。デプロイ後に metavr capture screenshot を使って、テキストが実際に表示されることを確認してください。テキストがピンク／マゼンタの場合は、TMP シェーダーの再インポートが必要です（「トラブルシューティング」を参照）。

トラブルシューティング

インポート後もテキストがピンク／マゼンタで表示される

TMP シェーダーを強制的に再インポートしてください。再インポート用のコマンドはないため、これには C# が必要です。Assets/ の外に置いたファイルを使い、run_script で実行してください。

// AgentScripts/ReimportTmpShaders.cs
using UnityEditor;

public static class ReimportTmpShaders
{
    public static string Run()
    {
        var guids = AssetDatabase.FindAssets("t:Shader TextMeshPro");
        foreach (var guid in guids)
            AssetDatabase.ImportAsset(AssetDatabase.GUIDToAssetPath(guid), ImportAssetOptions.ForceUpdate);
        return $"Reimported {guids.Length} TMP shaders.";
    }
}

unity command run_script --file AgentScripts/ReimportTmpShaders.cs --entry ReimportTmpShaders.Run --format json

--file はプロジェクトルートを基準に解決されます。また、スクリプトを Assets/ の外に置くことで、書き込みによるアセットのインポートやドメインの再読み込みが発生しません。

メニュー項目がグレー表示または見つからない

Window/TextMeshPro/Import TMP Essential Resources が利用できない場合：

• リソースはすでにインポートされている可能性があります。ステップ 1 を実行して確認してください。

• TMP パッケージがインストールされていない可能性があります。

  unity command package_add --identifier com.unity.textmeshpro --confirm true --wait true --format json
  unity command package_list --scope installed --format json          # verify
  

  --wait true を指定すると、パッケージの解決が完了するまで処理がブロックされます。追加に成功すると再コンパイルとドメインの再読み込みが発生するため、その後の処理は 1 つのスクリプトに連結せず、別のコマンドとして実行してください。

meta-quest-ui スキルとの連携

このスキルでは、TMP リソースのインポートを扱います。VR 固有の UI 設定（キャンバスのセットアップ、テキストのサイズ、視距離）には、TMP リソースのインポート後に meta-quest-ui スキルを使用してください。