本文内容

移动/重命名资产

通过实验性元数据功能，可以在不破坏现有引用的情况下自由移动/重命名文件，该功能将 UUID 保存在侧载文件（.meta）中。有关系统工作原理的技术细节，请参阅资产元数据重定位 RFC 。

默认情况下，元数据系统是禁用的，因为目前并非所有文件类型都能顺利重新定位。必须在设置中单独启用每种资产文件类型。资产文件类型启用后，资产处理器会在启动时为每个指定类型的文件生成一个元数据文件。任何与元数据关联的文件都可以移动或重命名。在移动或重命名文件时，资产处理器无需运行，也不需要使用特殊工具。

元数据文件示例：

{
    "FileVersion": 1,
    "UUID": {
        "uuid": "{931ADFA6-0578-4932-9C39-EA4A921A30DE}",
        "legacyUuids": [
            "{2336F175-E6FD-5A11-87B4-04B00088CADD}",
            "{45F2B574-8C8B-5D2B-8833-E99CEBD18F14}"
        ],
        "originalPath": "ScriptCanvas/ForceDebug.scriptcanvas",
        "creationUnixEpochMS": 1679507888552,
        "__version": 0
    }
}

源代码目录中的元数据文件示例：

Metadata files in directory

如何启用

要为一组文件类型启用元数据生成，请创建一个 .setreg 文件（建议使用<project or gem directory>/Registry），并进行以下设置：

{
    "O3DE":
    {
        "AssetProcessor":
        {
            "Settings":
            {
                "Metadata":
                {
                    "EnabledTypes": [
                    ]
                }
            }
        }
    }
}

EnabledTypes 是一个由要启用的文件扩展名字符串组成的数组。例如 ".txt", ".png"

强烈建议将此 setreg 文件放在一个中心位置，与项目的其他用户共享，以确保每个人都生成相同的元数据文件。对于游戏项目，应将其放在项目目录下；对于 gem 开发，应将其放在 gem 目录下。请记住，这是一个资产处理器（AP）范围的设置，它将适用于资产处理器处理的所有文件，而不仅仅是存在该设置的项目或 gem 中的文件。

一旦为资产生成了元数据文件，资产被重新定位或使用新生成的 UUID 保存了任何引用，元数据文件必须与资产一起保存。否则可能会破坏对该文件的引用。

AssetProcessor will continue to use existing metadata files for assets which have them, regardless of the above settings.

如何使用

移动或重命名资产既可以在编辑器中通过资产浏览器完成，也可以使用您选择的任何文件管理工具，如 Windows 中的文件资源管理器。

移动或重命名资产时只有一个要求，那就是元数据文件也必须移动或重命名。

文件夹可以移动或重命名，而无需移动元数据文件，但文件夹内的所有文件必须有一个元数据文件，以确保现有引用不会中断。

例如

如果 blue.png 重命名为 red.png，元数据文件 blue.png.meta 必须重命名为 red.png.meta。
如果将 textures/hat.png 移至 character/hat.png，元数据文件必须移至 character/hat.png.meta。

如果使用源控制，元数据文件必须与源资产一起签入，并根据对这些资产的任何移动或重命名更改进行更新。

上述规定有一个例外，那就是中间资产元数据文件。这些元数据文件遵循与 “中间资产 ”相同的规则：它们不应被修改或检查到版本控制中。

重新定位资产时，资产的 ID 将保持稳定，因此现有的引用将继续有效。资产通常使用 Asset<T> 类型进行引用，该类型包含一个资产提示，这是一个人类可读字符串，包含引用文件的最后已知位置。如果文件被移动或重命名，下一次保存引用文件时，可能会显示为非预期的更改。例如 File1.ext 引用 File2.ext，并将资产引用存储到 File2.ext。这既包含资产 ID，也包含文件名 File2.ext 的人可读资产提示。当 File2.ext 重命名为 FileB.ext 时，资产 ID 将保持不变。下次保存 File1.ext 时，数据将发生变化，因为资产提示已更改。

资产处理器运行时重命名

默认情况下，在资产处理器运行时手动重命名资产会很困难，因为 AP 会尝试立即为重命名的资产创建一个新的元数据文件。为避免这种情况，可将资产处理器配置为等待指定时间后再尝试处理 “新 ”资产，从而避免自动创建不必要的新元数据文件。

此延迟将影响所有启用元数据类型的新创建资产，默认为关闭。延迟时间越长，AP 开始处理任何新创建的启用元数据的文件类型所需的时间就越长。

在 .setreg 文件中，添加以下设置：

{
    "O3DE":
    {
        "AssetProcessor":
        {
            "Settings":
            {
                "Metadata":
                {
                    "MetaCreationDelayMs": 5000
                }
            }
        }
    }
}

指定的值是等待的毫秒数。上述配置示例在处理资产前将等待 5 秒。

该设置可针对特定用户，如果不需要，也无需在用户间共享。

此设置主要用于手动重命名资产，但在某些磁盘文件更新缓慢的情况下也有帮助，例如复制大量文件或从源代码控制中获取最新文件。这些操作的顺序有时需要很高的延迟设置，例如 Git LFS 抓取，可能会按类型分组获取文件，可能导致元数据文件在源资产创建很长时间后才在磁盘上创建。在这种情况下，建议先关闭 AP，以避免 AP 创建的元数据文件与源代码控制中已经存在的元数据文件发生冲突。

Asset Processor Batch

由于 Asset Processor Batch 用于自动流程，因此无论配置了什么设置，它都不会创建元数据文件，也不会使用元数据创建延迟。不过，它会使用任何现有的元数据文件。

限制

元数据重定位目前只支持基于 UUID 的引用。这意味着当文件被移动或重命名时，代码（C++、Lua、AZSL 等）中通常通过路径引用文件的引用会中断，需要通过其他方式更新。这也适用于文件类型被启用，但仍有其他文件可能通过路径引用该文件的情况。

由于该功能仍处于试验阶段，有关文件类型支持的更多信息，请参阅引擎贡献者文档。