hz-unity-tmp-resources

TextMesh Pro 资源导入

何时使用此技能

检测到以下任一情况时，自动使用此技能：

• 场景中的 TMP 文本显示为粉色／洋红色
• 控制台错误提及 LiberationSans SDF、TMP Settings 或缺失的 TMP 材质
• 在项目中创建第一个 TMP 文本元素
• 用户要求设置 TextMesh Pro 或创建 UI 文本
• Assets/TextMesh Pro/Resources/ 文件夹不存在

操作 Editor

以下每个步骤都通过 unity-cli 在已打开的 Editor 中执行——无需 C#。先确认有可连接的 Editor；如果可能有多个正在运行，请传入 --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 中的一个——如果都不提供，就会报错："At least one of type, name, or label is required." 单独提供其中任意一个即可；--search_in 仅用于缩小范围，可选。

读取 data.result.count；两项均为 0 表示资源尚未导入。如果已找到资源，就到此为止——无需执行任何操作。

count: 0 有两种情况并非错误，因此务必依据 count 而非 success 来判断：

• 无法解析的 --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. 未经确认，不要假定导入已成功。

模态对话框会阻塞 Editor，因此此请求可能超时或延迟返回——这是因为对话框正在等待用户操作，并非失败。

步骤 3：验证导入成功

用户确认后，重新运行检查，并确认两个资源都存在：

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

两项的 count 均非零才算通过。如果任一项为 0，说明导入未完成——不要继续 UI 工作。Editor 导入只是整个过程的一半：部署后，请使用 metavr capture screenshot 确认文本确实能够渲染（粉色／洋红色文本表示 TMP 着色器需要重新导入——参见“故障排除”）。

故障排除

导入后文本显示为粉色／洋红色

强制重新导入 TMP 着色器。此操作需要 C#（没有重新导入命令），因此请通过 run_script 执行，并将文件放在 Assets/ 之外：

// 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 会一直阻塞，直到包解析完成。成功添加包会触发重新编译和域重载，因此后续操作应作为单独的命令执行，不要在同一个脚本中串联。

与 meta-quest-ui 技能集成

此技能负责导入 TMP 资源。如需配置 VR 专用 UI（画布设置、文本大小、观看距离），请在导入 TMP 资源后使用 meta-quest-ui 技能。