TEngine 内置 com.unity.pipeline：Unity 资产与文件命令（Asset File Commands）完整实战指南

游戏开发【免费下载链接】TEngineUnity 商用级别开发框架原生内置 AI 工作流支持集成 HybridCLR 高性能热更、Obfuz 代码混淆加固、YooAssets 企业级资源管理方案构建高效、安全、可扩展的工业化开发底座。项目地址https://gitcode.com/gh_mirrors/teng/TEngine点击查看免费下载TEngine 项目通过本地 Unity 包 com.unity.pipeline 让 CLI、CI 或 AI Agent 通过本地 HTTP API 驱动运行中的 Unity Editor 执行命令。本篇聚焦其中的资产与文件命令组覆盖create_asset、import_asset、move_asset、copy_asset、rename_asset、delete_asset、find_assets、导入设置读写、文件夹与文本文件操作共 12 条命令的完整参数说明并结合Editor/Commands/Assets/与Editor/Authoring/下的真实源码深入剖析路径沙箱、confirm/dry_run安全门与对象引用机制的底层实现读完即可安全地自动化 Unity 项目资产的生产线操作。一、命令组总览安全约定先行资产与文件命令的定位是为 Agent 提供项目内容的增删改查。所有命令共享三条核心约定见 Asset file commands 文档路径沙箱所有 Agent 提供的路径都会经过 authoring root 沙箱过滤拒绝../与项目外写入破坏性门控破坏性或覆盖类操作要求confirmtrue并普遍支持dry_run预览无 Undo 语义AssetDatabase的创建/移动/复制/重命名/删除不属于 Unity 的 Undo 系统CtrlZ 无法回滚因此这些操作刻意不包裹AuthoringUndoScope而是用显式confirm参数防止 Agent 无声丢失数据。这条注释在 AssetCommands.cs 的类文档中写得很直白/// NOTE: AssetDatabase create/move/copy/rename/delete are NOT part of Unitys Undo system, so /// AuthoringUndoScope would have no effect here — these operations are intentionally /// not wrapped in an undo scope, and destructive/overwriting operations instead require an explicit /// confirm argument (and support dry_run) so an agent cannot silently lose data.1.1 路径沙箱ProjectPaths.Resolve 如何工作沙箱的核心是 ProjectPaths.cs 中的Resolve方法其解析规则为裸路径如Gameplay/Enemies相对 authoring root 解析无需重复Assets/前缀显式Assets/...或Packages/...路径按项目相对路径直接使用绝对路径必须位于项目根目录下否则被拒绝路径中任何位置的..都会被拒绝最终结果必须落在AuthoringRoot之内默认Assets可通过set_authoring_root收窄到子目录实现 Agent 自我沙箱化。authoring root 通过EditorPrefs按项目持久化键含Application.dataPath不会跨项目泄漏。所有资产命令的第一步都是var normalized ProjectPaths.Resolve(path, out var error); if (normalized null) throw new ArgumentException(error);测试用例CreateAsset_OutOfProject_ThrowsAssetCommandsTests.cs验证了../Outside.asset和Assets/../Outside.asset两种越界写法都会被拒绝。1.2 对象引用ObjectRef 输入与 AuthoringResult 输出操作已存在资产的命令move/copy/rename/delete/导入设置不接收裸路径字符串而是接收ObjectRef结构path/guid/globalId等由 ObjectResolver.TryResolve 按globalId → path → guid(fileId) → instanceId → hierarchyPath的顺序解析为活对象。命令执行后统一返回AuthoringResultassetPath/guid/fileId/typeAgent 可将其直接作为下一次调用的ObjectRef输入形成输出喂输入的链式调用全程无需接触原始 Unity 对象。此外AssetCommands.cs 中的ResolveAssetPath还会把解析出的资产路径二次圈禁回 authoring root防止 GUID/globalId 句柄指向沙箱外的资产执行破坏性命令。二、资产创建与导入命令2.1create_asset创建 ScriptableObject 或其他 Object 资产在 authoring root 下按类型创建一个 ScriptableObject或其他UnityEngine.Object资产。参数必填默认值说明path是–相对 authoring root 的资产路径需含扩展名如Data/Config.asset或Materials/Wall.mat。Assets/前缀可选。type是–要实例化的全限定或短类型名如UnityEngine.Material、MyGame.GameConfig。必须派生自UnityEngine.Object且可创建。shader否–仅对 Material 有效其他类型被忽略要指定的 shader 名如Standard、Universal Render Pipeline/Lit。省略时若启用了 Scriptable Render Pipeline 则默认Universal Render Pipeline/Lit否则使用内置Standard若 URP/Lit 不可用则回退Standard。confirm否false仅当路径上已存在资产需要覆盖时必填true。路径为空时忽略。dry_run否false为 true 时仅校验输入并报告将要创建的内容不实际写入。返回AuthoringResult。注意覆盖已有资产需confirmtrue支持dry_run。源码纵深类型解析、Material 特判与 PhysicMaterial 兼容实现位于 AssetCommands.cs 的 CreateAsset几个值得注意的工程细节类型解析ResolveType先Type.GetType再遍历所有已加载程序集做全名匹配最后按短名匹配ResolveTypeL548-L602并显式兼容 Unity 6 与 Unity 2022 的PhysicsMaterial/PhysicMaterial拼写差异自动把.physicsMaterial扩展名改写为引擎对应的.physicMaterial。Material 不走Activator.CreateInstanceMaterial 没有公开无参构造器Activator会产出 shader 为 null 的无效 Material所以先通过ResolveShader前置解析并校验shader再new Material(materialShader)。shader 缺省策略见 ResolveShader显式指定 →Shader.Find缺省 → 检测GraphicsSettings.currentRenderPipeline决定 URP/Lit 还是 Standard两级回退失败则抛出可操作的错误。覆盖语义AssetDatabase.CreateAsset并不保证覆盖同路径已有资产源码在确认confirm后先显式DeleteAsset再CreateAssetL141-L148。父目录自动创建EnsureParentFolder递归创建缺失的中间文件夹因此pathGameplay/Enemies/Config.asset不需要先手动建目录。dry_run 也会校验 shader注释标明这是 CLI-221 的刻意设计——dry_run承诺校验输入未知 shader 必须提前失败。2.2import_asset导入外部文件把外部文件贴图、模型、音频等复制到 authoring root 下的目标路径然后导入到 AssetDatabase。参数必填默认值说明source是–外部源文件的绝对文件系统路径。path是–目标资产路径相对 authoring root需含扩展名。Assets/前缀可选。confirm否false仅当目标路径已存在资产时必填true。dry_run否false为 true 时仅校验输入并报告将要导入的内容不实际写入。返回AuthoringResult。注意覆盖需confirmtrue支持dry_run。实现见 ImportAsset先校验source文件存在再以File.Copy(overwrite: true)落盘最后AssetDatabase.ImportAsset(normalized, ImportAssetOptions.ForceUpdate)强制触发导入管线确保 Unity 识别新文件。2.3create_folder创建文件夹在 authoring root 下创建文件夹自动创建中间层级。参数必填默认值说明path是–相对 authoring root默认Assets/的文件夹路径Assets/前缀可选。例如Gameplay/Enemies或Assets/Gameplay/Enemies。返回AuthoringResult。实现见 FolderCommands.cs递归调用AssetDatabase.CreateFolder补齐层级随后AssetDatabase.Refresh()。该命令是纯增量、非破坏性的因此按安全约定不接收confirm/dry_run直接执行。三、资产移动、复制、重命名与删除3.1move_asset移动资产保留 GUID把资产移动或借助新路径重命名到 authoring root 下的新位置保留资产 GUID即引用关系不断链。参数必填默认值说明asset是–要移动的资产引用path / guid / globalId。destination是–目标路径相对 authoring root需含扩展名。Assets/前缀可选。dry_run否false为 true 时通过AssetDatabase.ValidateMoveAsset校验移动可行性但不执行。返回AuthoringResult。注意支持dry_run。MoveAsset 源码 有个容易踩坑的细节真实移动会先创建目标父目录再做ValidateMoveAsset校验因为 Unity 在目标文件夹不存在时会报告 move as a subdirectory 失败而 dry-run 不能创建文件夹只对当前项目状态做校验。3.2copy_asset复制资产新 GUID把资产复制到新路径副本获得全新 GUID原资产引用与副本引用从此独立。参数必填默认值说明asset是–要复制的资产引用path / guid / globalId。destination是–目标路径相对 authoring root需含扩展名。Assets/前缀可选。confirm否false仅当目标路径已存在资产时必填true。dry_run否false为 true 时仅校验输入并报告将要复制的内容不实际写入。返回AuthoringResult。注意覆盖需confirmtrue支持dry_run。源码CopyAsset中注释说明AssetDatabase.CopyAsset在目标已存在时会失败因此在confirm已放行覆盖的前提下先删除目标再复制。3.3rename_asset就地重命名在同一文件夹内重命名资产保留 GUID、保留扩展名。参数必填默认值说明asset是–要重命名的资产引用path / guid / globalId。new_name是–新文件名不带文件夹路径。省略扩展名时自动保留原扩展名。dry_run否false为 true 时仅校验重命名而不执行。返回AuthoringResult。注意支持dry_run。实现细节RenameAssetnew_name若包含/或\会被直接拒绝——跨文件夹移动请用move_asset省略扩展名时自动拼接原路径的扩展名AssetDatabase.RenameAsset本身只接受不带扩展名的新名称目标名冲突会立即抛错。3.4delete_asset删除资产破坏性从项目中删除资产。破坏性操作必须confirmtrue。参数必填默认值说明asset是–要删除的资产引用path / guid / globalId。confirm否false必须为 true 才会真正删除否则命令直接拒绝破坏性保护。dry_run否false为 true 时报告将被删除的资产但不删除。返回AuthoringResult。注意破坏性——需confirmtrue支持dry_run不能通过 Unity Undo 回滚。DeleteAsset 源码 有一个对 Agent 很友好的设计先捕获被删资产的完整身份信息再执行删除这样即使删除成功返回结果中仍有该资产的 path/GUID/type 记录可审计。3.5 测试佐证以上行为的正确性由 AssetCommandsTests.cs 覆盖包括MoveAsset_RelocatesAndPreservesGuid断言移动前后AssetDatabase.AssetPathToGUID一致CopyAsset_CreatesDistinctAsset断言副本 GUID 与源不同DeleteAsset_WithoutConfirm_Throws/DeleteAsset_ViaClient_WithoutConfirm_Fails分别验证直接调用与经由 HTTP 服务器两条路径下缺少confirm均被拒绝且资产存活AcceptanceFlow_CreateFindMoveDeleteL166-L188完整走通建目录树 → 建 ScriptableObject → 按类型查找 → 移动 → 确认删除的验收流程。四、资产查找find_assets按类型和/或名称和/或标签查找资产返回路径、GUID 与类型。至少提供一个过滤条件。参数必填默认值说明type否–类型名过滤如Material、GameObject、ScriptableObject、MyGame.GameConfig。会解析为System.Type并与每个资产的实际主类型匹配。name否–名称子串过滤AssetDatabase 名称过滤。label否–资产标签过滤AssetDatabase 的l:过滤。search_in否–限定搜索范围的文件夹相对 authoring root默认即 authoring root 本身。limit否200返回结果上限默认 200。返回FindAssetsResult含filter、count、truncated与assets列表每项为含 path/GUID/type 的AuthoringResult可直接作为后续命令的ObjectRef。注意type、name、label至少传一个。源码纵深为什么 type 过滤不走t:查询FindAssets 实现 揭示了一个重要的引擎坑AssetDatabase.FindAssets的t:类型 token对新建/自定义的 ScriptableObject 资产并不可靠连t:ScriptableObject都可能返回 0但对内置类型有效。因此源码策略是仅用name名称子串与l:label拼装 AssetDatabase 查询串type过滤改为逐条后过滤——先解析System.Type解析失败立即报清晰的错误再用typeFilter.IsAssignableFrom(mainType)精确判定搜索范围默认被圈在 authoring root 内而非整个项目保证 Agent 只能发现沙箱内的资产达到limit后截断并置truncatedtrue。结果模型定义在 FindAssetsResult.cs。五、导入设置读写set_import_settings与get_import_settings5.1set_import_settings写入导入设置并重导入设置资产AssetImporter上的导入参数例如贴图的isReadable并重新导入。参数必填默认值说明asset是–要编辑其 importer 的资产引用path / guid / globalId。settings是–importer 属性/字段名到值的 JSON 对象例如{isReadable: true, textureType: NormalMap}。dry_run否false为 true 时仅校验哪些设置会生效哪些是未知键不写入、不重导入。返回SetImportSettingsResult含assetPath、importerType、platform、applied列表、unknown列表。注意支持dry_run。导入设置保存在资产的.meta文件中不属于 Unity Undo 系统重导入不破坏源文件故无需confirm。源码纵深默认平台反射 平台覆盖专用通道AssetImportCommands.cs 的写入路径按平台分两条通道platformDefault通过反射Public | Instance | IgnoreCase对 importer 顶层公共属性/字段直接赋值适用于任意importer 类型枚举成员既可传枚举名大小写不敏感也可传整数值TryConvert真实平台Standalone/iOS/Android/WebGL/tvOS仅TextureImporter与AudioImporter支持。因为TextureImporterPlatformSettings/AudioImporterSampleSettings是结构体顶层反射够不到源码改为取出平台设置 struct → 在装箱副本上反射写入 → 用SetPlatformTextureSettings/SetOverrideSampleSettings写回。注意iOS在 Unity 内部平台名映射为iPhoneUnityPlatformName贴图平台写入时未显式传overridden会自动置overriddentrue音频传overridden:false则整体清除该平台的覆盖ClearSampleSettingOverrideModelImporter无平台覆盖传真实平台会返回结构化错误no_platform_overrides未知键不静默忽略每个 key 被分类进applied或unknown列表若全部未知则抛错让 Agent 获得可操作的反馈成功后调用importer.SaveAndReimport()落盘.meta并重导入。5.2get_import_settings读取导入设置读取资产的导入设置按 importer 类型texture/model/audio结构化组织含默认平台字段以及对贴图/音频一个平台覆盖块。参数必填默认值说明asset是–要读取其 importer 的资产引用path / guid / globalId。platform否Default要读取覆盖的平台Default|Standalone|iOS|Android|WebGL|tvOS。返回GetImportSettingsResultsettingsplatformOverride字典。可读字段集在源码中有明确清单贴图默认平台暴露textureType、sRGBTexture、isReadable、mipmapEnabled、wrapMode、filterMode、anisoLevel、spriteImportMode、maxTextureSize等 15 项ReadTextureDefaults音频暴露forceToMono、loadInBackground、compressionFormat、sampleRateSetting等模型暴露 mesh 压缩/法线/切线/动画导入等约 25 项ReadModelDefaults。非可导入资产如 ScriptableObject 的NativeFormatImporter返回最小的userData/assetBundleName块而非抛错。六、文本文件读写read_text_file与write_text_file6.1read_text_file读取 UTF-8 文本文件读取 authoring root 下的 UTF-8 文本文件并返回内容。参数必填默认值说明path是–文本文件路径相对 authoring root。Assets/前缀可选。max_bytes否1048576拒绝超过该字节数的文件默认 1048576 1 MiB避免超大负载。返回ReadTextFileResultassetPath、bytes、contents。注意MainThreadRequired true。实现见 TextFileCommands.cs先经沙箱解析文件不存在或超限分别抛出带路径与字节数的可操作错误。6.2write_text_file写入文本文件并导入把 UTF-8 文本写入 authoring root 下的文件随后导入进 AssetDatabase确保 Unity 感知变更。覆盖已有文件需confirmtrue。参数必填默认值说明path是–文本文件路径相对 authoring root需含扩展名。Assets/前缀可选。contents是–要写入的完整文本内容整体替换文件。confirm否false仅当目标路径已有文件时必填true。dry_run否false为 true 时仅校验输入并报告将要写入的内容不实际写入。返回AuthoringResult。注意覆盖需confirmtrue支持dry_run。文件系统写入不属于Unity Undo 系统。WriteTextFile 的实现流程与import_asset一致File.WriteAllText落盘 →AssetDatabase.ImportAsset(..., ForceUpdate)。这对编辑 JSON/CSV/.txt/.cs/.shader 等纯文本数据资产尤其有用——写完即被 Unity 导入管线拾取。七、典型工作流与调用方式结合 Testing 架构文档 与 Connectivity 文档客户端通过unityCLI 连接本机 Editorloopback-only 的 HTTP 服务器端口描述符固定位于Library/Pipeline/.unity-pipeline-port典型资产管线如下参数化调用与测试中的验收流一致# 1. 建立目录自动补中间层级 unity command create_folder --path Gameplay/Enemies # 2. 创建配置资产 unity command create_asset --path Gameplay/Enemies/EnemyConfig.asset --type MyGame.EnemyConfig # 3. 按类型查找结果中的 guid/path 可作为后续 ObjectRef unity command find_assets --type EnemyConfig --search_in Gameplay # 4. 移动保留 GUID复制产生新 GUID unity command move_asset --asset {path:Assets/Gameplay/Enemies/EnemyConfig.asset} --destination Gameplay/Allies/EnemyConfig.asset unity command copy_asset --asset {path:Assets/Gameplay/Enemies/EnemyConfig.asset} --destination Gameplay/Enemies/EnemyConfigV2.asset # 5. 破坏性操作先 dry_run 预览再 confirm 执行 unity command delete_asset --asset {path:Assets/Gameplay/Enemies/EnemyConfigV2.asset} --dry_run true unity command delete_asset --asset {path:Assets/Gameplay/Enemies/EnemyConfigV2.asset} --confirm true # 6. 外部素材导入 平台级贴图导入设置 unity command import_asset --source /abs/path/hero.png --path Art/hero.png unity command set_import_settings --asset {path:Assets/Art/hero.png} --settings {maxTextureSize:2048} --platform Android unity command get_import_settings --asset {path:Assets/Art/hero.png} --platform Default安全约定总结与 Safety mutations 文档 一致约定行为dry_runtrue仅校验并描述预期变更不产生任何写入即使同时传了confirm也优先走预览confirmfalse非 dry-run拒绝执行并报错不产生任何变更confirmtrue非 dry-run执行变更资产/文件/设置类写入不走 Undo命令描述中会注明纯增量命令如create_folder不提供confirm/dry_run直接执行八、参考文件索引文件内容命令参考文档本命令组的官方参数参考AssetCommands.cscreate/import/move/copy/rename/delete/find 的实现AssetImportCommands.cs导入设置读写与平台覆盖逻辑FolderCommands.cscreate_folder实现TextFileCommands.cs文本文件读写实现ProjectPaths.cs路径沙箱与 authoring root 解析ObjectResolver.csObjectRef解析与AuthoringResult生成AssetCommandsTests.cs沙箱、破坏性保护与完整流程的测试用例安全约定文档confirm/dry_run与 Undo 分组约定Authoring 命令编写指南扩展自定义 authoring 命令的模式适用前提以上命令均为 Editor-only运行在 Editor 端的 Pipeline 服务器内需要 Unity Editor 已启动 Pipeline 服务包当前版本为0.3.1-exp.1最低 Unity 2022.3。资产、文本文件与导入设置的写入均不可通过 CtrlZ 回滚自动化脚本应始终先dry_run、再confirm并在关键操作前用get_import_settings/find_assets留存目标状态。赞分享游戏开发【免费下载链接】TEngineUnity 商用级别开发框架原生内置 AI 工作流支持集成 HybridCLR 高性能热更、Obfuz 代码混淆加固、YooAssets 企业级资源管理方案构建高效、安全、可扩展的工业化开发底座。项目地址https://gitcode.com/gh_mirrors/teng/TEngine点击查看免费下载相关推荐Vitest Browser Mode Commands 完全指南内置文件命令、CDP 会话与自定义命令实战Vitest Browser Mode Commands 完全指南内置文件命令、CDP 会话与自定义命令实战 导读 本文围绕 Vitest 浏览器模式Br测试前端开发工具ZeroTermux 内置命令手册ls 命令完整实战指南ZeroTermux 内置命令手册ls 命令完整实战指南 导读 ls 是 Linux 系统中使用率最高的命令之一用于显示目录内容列表是任何终端用户的必修基移动开发开发工具VisiData 命令检索实战指南Command Palette 与 Commands Sheet 的完整用法VisiData 命令检索实战指南Command Palette 与 Commands Sheet 的完整用法 导读 VisiData 是一个键盘驱动的终端表数据分析CLI数据可视化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考