{"id":51076900,"url":"https://github.com/cnbarrier404/unityassetspatcher","last_synced_at":"2026-06-23T15:01:44.062Z","repository":{"id":362503998,"uuid":"1257207351","full_name":"CnBarrier404/UnityAssetsPatcher","owner":"CnBarrier404","description":"Interactive CLI tool for installing and uninstalling Unity .assets mod packages.","archived":false,"fork":false,"pushed_at":"2026-06-22T15:33:09.000Z","size":11643,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T17:17:47.071Z","etag":null,"topics":["assets","cli","csharp","dotnet","modding-tool","tui","unity","windows"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CnBarrier404.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-02T13:14:16.000Z","updated_at":"2026-06-22T15:34:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CnBarrier404/UnityAssetsPatcher","commit_stats":null,"previous_names":["cnbarrier404/unityassetspatcher"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/CnBarrier404/UnityAssetsPatcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CnBarrier404%2FUnityAssetsPatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CnBarrier404%2FUnityAssetsPatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CnBarrier404%2FUnityAssetsPatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CnBarrier404%2FUnityAssetsPatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CnBarrier404","download_url":"https://codeload.github.com/CnBarrier404/UnityAssetsPatcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CnBarrier404%2FUnityAssetsPatcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34694786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assets","cli","csharp","dotnet","modding-tool","tui","unity","windows"],"created_at":"2026-06-23T15:01:41.499Z","updated_at":"2026-06-23T15:01:44.051Z","avatar_url":"https://github.com/CnBarrier404.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Unity Assets Patcher\n\n[English](README_EN.md)\n\nUnity Assets Patcher 是一个用于安装和卸载 Unity `.assets` 文件 Mod 的交互式命令行工具。它面向不适合接入 `BepInEx` 等运行时 Mod 框架的 Unity 游戏，通过 Mod 包中的 `manifest.json` 描述要复制的文件和要写入的 assets 变更。\n\n## 功能概览\n\n- 安装 zip 格式的 Mod 包，并在写入前显示预览。\n- 修改 Unity `.assets` 文件中的字段，或用 Mod 包内的 asset 替换目标 asset。\n- 复制 Mod 所需的 payload 文件，例如 `.resource` 文件。\n- 为被覆盖的 assets 文件创建备份，并记录安装信息。\n- 卸载已安装的 Mod，恢复安装备份并清理安装时复制的 payload 文件。\n- 支持英文和简体中文终端界面。\n- 内置路径安全检查、manifest 大小限制和 zip 解压大小限制。\n\n## 下载与运行\n\n从 [GitHub Releases](https://github.com/CnBarrier404/UnityAssetsPatcher/releases) 下载最新的 Windows 压缩包，解压到一个单独文件夹，然后运行 `UnityAssetsPatcher.exe`。\n\n当前发布包是 `win-x64` 自包含单文件程序，不需要预先安装 .NET 运行时。程序旁边会包含运行所需的 `resources.tpk`，安装记录和备份默认保存在程序目录下的 `backup` 文件夹。\n\n## 安装 Mod\n\n1. 启动 `UnityAssetsPatcher.exe`。\n2. 在主菜单选择 `Install Mod`。\n3. 输入 Mod zip 文件路径。\n4. 输入游戏目录，或留空让工具尝试通过 Steam 安装信息自动解析。\n5. 阅读安装预览，确认目标 assets 文件、将修改的 asset、payload 文件和备份信息。\n6. 只有在确认后，工具才会写入 assets 文件并复制 payload 文件。\n\n## 卸载 Mod\n\n1. 启动 `UnityAssetsPatcher.exe`。\n2. 在主菜单选择 `Uninstall Mod`。\n3. 从已安装 Mod 列表中选择要卸载的记录。\n4. 阅读卸载预览，确认要恢复的 assets 文件和要删除的 payload 文件。\n5. 确认后，工具会先保存当前 assets 文件到卸载备份，再恢复安装时创建的备份。\n\n卸载依赖安装记录和备份文件。如果 `backup` 文件夹被删除或移动，卸载可能无法继续。\n\n## 安全机制\n\n- 安装和卸载都会先预览，预览阶段不会写入 assets 文件、复制 payload 文件、删除 payload 文件或更新安装记录。\n- 覆盖原始 assets 文件前会先创建备份。\n- 写入使用临时文件，失败时会清理临时文件。\n- 写入字段前会校验 manifest 中声明的 `from` 值，避免在不匹配的游戏版本上继续修改。\n- 显式输出路径不能指向输入文件，也不能覆盖已有输出文件。\n- payload 文件不会覆盖已有文件。\n- Mod 包路径会被校验，拒绝绝对路径、路径遍历和不安全路径。\n- `manifest.json` 最大 10MB，Mod 包解压内容最大 10GB。\n\n## Mod 包基础\n\nMod 包是一个 zip 文件，里面必须包含且只能包含一个 `manifest.json`。如果 Mod 需要安装额外文件，例如 `.resource` 文件，必须在 manifest 的 `copyFiles` 中显式声明。\n\n```text\nMod.zip\n  manifest.json\n  resources/\n    modassets.assets\n    modassets.resource\n```\n\n最小概念：\n\n- `targets[].file` 按文件名定位目标 `.assets` 文件。\n- `patches[]` 用 Unity asset 类型和字段匹配目标 asset。\n- `set` 修改字段值，并要求当前值匹配 `from`。\n- `add` 向数组字段追加标量值。\n- `replaceAsset` 用 Mod 包中的源 asset 替换目标 asset。\n- `$pathId` 可用于把字段写成同一 assets 文件中另一个 asset 的 Path ID。\n\n完整 manifest 格式、字段路径、匹配规则和示例见 [Mod Manifest 编写指南](docs/mod-manifest-guide.md)。\n\n## 当前限制\n\n- 当前发布包只提供 Windows `win-x64`。\n- 这是交互式终端工具，目前没有图形界面和非交互式 CLI 参数。\n- 自动游戏目录解析主要依赖 Steam 安装信息；无法唯一解析时需要手动输入游戏目录。\n- `targets[].file` 只能写目标 assets 文件名，不能写目录路径；工具会在游戏目录下递归查找。\n- payload 文件会复制到目标 assets 文件所在目录，且要求目标文件不存在。\n- 同一个目标 assets 文件内不能混合整 asset 替换和字段级 `set` / `add` 修改。\n- Unity assets 字段结构会随游戏版本、Unity 版本和导出方式变化；manifest 作者应使用 UABEA 等工具确认字段路径和旧值。\n\n## 常见问题\n\n**找不到游戏目录**\n\n如果自动解析失败，请手动输入游戏安装目录。该目录应包含游戏数据文件夹，工具会在其中递归查找目标 `.assets` 文件。\n\n**预览显示 skipped**\n\n通常表示当前字段值与 manifest 中的 `from` 值不一致。请确认游戏版本、Mod 版本和 manifest 是否匹配。\n\n**卸载失败**\n\n卸载需要完整的安装记录、安装备份和当前目标文件。如果安装后的 `backup` 文件夹被删除，或游戏文件被手动移动，卸载可能被拒绝。\n\n**payload 文件已存在**\n\n安装不会覆盖已有 payload 文件。请先确认该文件是否来自旧 Mod 或手动安装内容，再决定是否清理。\n\n## 开发者入口\n\n开发环境需要安装 `.NET 10 SDK`。从仓库根目录运行：\n\n```powershell\ndotnet run --project src\\UnityAssetsPatcher\\UnityAssetsPatcher.csproj\n```\n\n```powershell\ndotnet test UnityAssetsPatcher.sln\n```\n\n项目结构：\n\n- `src/UnityAssetsPatcher`：可执行程序入口、依赖注入组合和 bundled resource 设置。\n- `src/UnityAssetsPatcher.TUI`：交互式终端界面、页面、提示和输出格式。\n- `src/UnityAssetsPatcher.Core`：共享 assets contracts、字段模型、字段路径匹配和通用工具。\n- `src/UnityAssetsPatcher.Application`：manifest 加载、安装/卸载工作流、patch 规划和业务流程。\n- `src/UnityAssetsPatcher.AssetsTools`：AssetsTools.NET 集成和真实 Unity assets 文件读写。\n- `tests/UnityAssetsPatcher.Tests`：xUnit v3 测试。\n\n发布构建配置在 [`.github/workflows/release.yml`](.github/workflows/release.yml)。工作流会通过 `dotnet publish` 传入 `-p:PublishAot=true`，将 `win-x64` 发布为自包含、单文件 NativeAOT 程序。\n\n## 相关文档\n\n- [Mod Manifest 编写指南](docs/mod-manifest-guide.md)\n- [变更记录](docs/changelog.md)\n\n## 许可证\n\n本项目使用 [MIT License](LICENSE)。\n\n## 致谢\n\n- [AssetsTools.NET](https://github.com/nesrak1/AssetsTools.NET)\n- [AssetsRipper TPK](https://github.com/AssetRipper/Tpk)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcnbarrier404%2Funityassetspatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcnbarrier404%2Funityassetspatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcnbarrier404%2Funityassetspatcher/lists"}