Skip to content
Back to search

pbz-unpack

SkillWorks with Claude CodeGitHub

Inspect and export assets from a locally installed Phantom Blade Zero UE5.7 game with bundled AES and usmap profile data. Use for PBZ Pak or IoStore discovery, package inspection, and glTF or ActorX extraction; not for Blender character assembly or mod installation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lkun24247-cpu--pbz-unpack/badge.svg)](/listings/lkun24247-cpu--pbz-unpack)

HTML

<a href="/listings/lkun24247-cpu--pbz-unpack"><img src="/api/listings/lkun24247-cpu--pbz-unpack/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 78 lines
  1. ---
  2. name: pbz-unpack
  3. description: Inspect and export assets from a locally installed Phantom Blade Zero UE5.7 game with bundled AES and usmap profile data. Use for PBZ Pak or IoStore discovery, package inspection, and glTF or ActorX extraction; not for Blender character assembly or mod installation.
  4. ---
  5. # PBZ Unpack
  6. Find, inspect, and export Phantom Blade Zero assets without requiring FModel or
  7. temporary tool directories. The repository supplies the CLI source, build
  8. scripts, game profile, AES key, and UE5.7 mappings. The user must supply a local
  9. copy of the game.
  10. ## Setup And Verification
  11. Run from the skill root:
  12. ```powershell
  13. .\scripts\install.ps1
  14. .\scripts\check-environment.ps1 -Deep
  15. ```
  16. The installer uses an existing .NET 10 SDK or downloads a repository-local SDK.
  17. The published CLI is self-contained; later commands do not require a global
  18. .NET installation. Steam libraries are detected automatically. Set
  19. `PBZ_PAK_DIR` for a non-Steam layout.
  20. For an end-to-end inspect-and-export check, run `scripts/smoke-test.ps1`.
  21. Its default sample exports a small weapon PSK into `output/smoke-test`.
  22. ## Asset Workflow
  23. List candidate package paths before exporting:
  24. ```powershell
  25. .\scripts\pbz.ps1 list --contains "/Characters/EliteBoss/Yuu/" --limit 100
  26. ```
  27. Inspect the selected asset and retain its material JSON for provenance:
  28. ```powershell
  29. .\scripts\pbz.ps1 inspect `
  30. --path "Characters/EliteBoss/Yuu/SkinParts/Yuu_Body" `
  31. --json-dir ".\output\json"
  32. ```
  33. Export glTF with materials, or ActorX for PSK/PSA:
  34. ```powershell
  35. .\scripts\pbz.ps1 export `
  36. --path "Characters/EliteBoss/Yuu/SkinParts/Yuu_Body" `
  37. --out ".\output\Yuu_Body" --format gltf --materials
  38. ```
  39. Use ActorX when the native skeleton or animation matters:
  40. ```powershell
  41. .\scripts\pbz.ps1 export `
  42. --path "Characters/EliteBoss/Yuu/SkinParts/Yuu_Body" `
  43. --out ".\output\Yuu_Body" --format actorx
  44. ```
  45. Keep exports outside the repository unless they are intentional test fixtures.
  46. Do not commit extracted game assets. Preserve source package paths in task
  47. notes or generated manifests.
  48. ## Profiles And Overrides
  49. `config/pbz.json` supplies the shipped AES key and mapping filename. Override
  50. them for a newer game build with `PBZ_AES_KEY` and `PBZ_USMAP`, or pass
  51. `--aes-key` and `--usmap` directly to the CLI. Do not change the global profile
  52. merely to test another game build.
  53. If package indexing fails after a game update, first verify the exact engine
  54. version, mapping file, and AES key together. A valid AES key cannot compensate
  55. for stale mappings, and correct mappings cannot decrypt with a stale key.
  56. Read [references/troubleshooting.md](references/troubleshooting.md) when path
  57. discovery, native compression, export, or game-version checks fail.
README.md · README · 164 lines
  1. # PBZ Unpack
  2. 面向《影之刃零》(Phantom Blade Zero)本地游戏文件的 UE5.7 资产检索、检查与导出工具,同时提供可直接安装的 Codex skill。
  3. 项目包含:
  4. - 基于 CUE4Parse 的命令行工具源码;
  5. - 对应游戏版本的 **AES 密钥**与 **完整 `.usmap` 映射文件**;
  6. - Steam 多盘符游戏目录自动发现;
  7. - 一键构建、环境检查和真实 Pak 索引测试;
  8. - `list`、`inspect`、`export` 三种工作流,支持 glTF、GLB、PSK、PSA 与材质 JSON;
  9. - 从源码复现的构建方式,不依赖个人电脑路径或临时工作目录。
  10. > **版本范围**:内置配置对应 `5.7.4-301524`,详见 [`config/pbz.json`](config/pbz.json)。游戏更新后,AES、映射和引擎版本可能需要一起更新。
  11. ## 环境要求
  12. - Windows 10/11 x64;
  13. - PowerShell 5.1 或 PowerShell 7;
  14. - 已安装的《影之刃零》,或该游戏的 `ProjectPBZ\Content\Paks` 目录;
  15. - 首次构建时可访问 NuGet 和 Microsoft 官方 .NET 下载站点。
  16. 不需要预先安装 Blender、FModel、Visual Studio 或全局 .NET SDK。安装脚本会优先使用已有 .NET 10 SDK,缺少时下载到仓库内的 `.tools` 目录。最终 CLI 为自包含应用,日常运行不需要全局 .NET。
  17. ## 快速开始
  18. ```powershell
  19. git clone https://github.com/lkun24247-cpu/pbz-unpack.git
  20. cd pbz-unpack
  21. .\scripts\install.ps1
  22. .\scripts\check-environment.ps1 -Deep
  23. ```
  24. 如果 PowerShell 禁止运行本地脚本,可在当前进程临时放宽策略:
  25. ```powershell
  26. Set-ExecutionPolicy -Scope Process Bypass
  27. ```
  28. `-Deep` 会实际挂载游戏 Pak、使用 AES 解密并读取资产索引,不只是检查文件是否存在。
  29. 还要验证 JSON 检查和 ActorX 导出时,可运行:
  30. ```powershell
  31. .\scripts\smoke-test.ps1
  32. ```
  33. 默认样本会导出 `ZuoShang_Sword.psk` 到被 Git 忽略的 `output\smoke-test`,可用 `-AssetPath` 和 `-OutDir` 更换测试目标。
  34. ### 1. 搜索资产
  35. ```powershell
  36. .\scripts\pbz.ps1 list --contains "/Characters/EliteBoss/Yuu/" --limit 100
  37. ```
  38. 正则搜索:
  39. ```powershell
  40. .\scripts\pbz.ps1 list --regex "Yuu/.*(SkinParts|Material|Texture|Anim)/" --limit 500
  41. ```
  42. ### 2. 检查资产
  43. ```powershell
  44. .\scripts\pbz.ps1 inspect `
  45. --path "Characters/EliteBoss/Yuu/SkinParts/Yuu_Body" `
  46. --json-dir ".\output\json"
  47. ```
  48. `inspect` 会列出包内导出对象;指定 `--json-dir` 后,还会保存材质、网格等对象的 JSON,便于后续审计材质参数。
  49. ### 3. 导出资产
  50. 导出 glTF 网格、材质和纹理:
  51. ```powershell
  52. .\scripts\pbz.ps1 export `
  53. --path "Characters/EliteBoss/Yuu/SkinParts/Yuu_Body" `
  54. --out ".\output\Yuu_Body" --format gltf --materials
  55. ```
  56. 导出 ActorX(PSK/PSA):
  57. ```powershell
  58. .\scripts\pbz.ps1 export `
  59. --path "Characters/EliteBoss/Yuu/SkinParts/Yuu_Body" `
  60. --out ".\output\Yuu_Body" --format actorx
  61. ```
  62. `--format psk` 与 `--format psa` 是 `actorx` 的别名。网格默认使用 glTF,动画默认使用 ActorX;也可以显式使用 `--format auto`。
  63. ## 游戏路径与配置
  64. 工具会读取 Steam 注册表及 `libraryfolders.vdf`,自动检测常见 Steam 库目录。其他安装方式可设置:
  65. ```powershell
  66. $env:PBZ_PAK_DIR = "X:\path\to\PBZ\ProjectPBZ\Content\Paks"
  67. ```
  68. 支持以下覆盖项:
  69. | 环境变量 | 用途 |
  70. | --- | --- |
  71. | `PBZ_PAK_DIR` | 游戏 Pak 目录 |
  72. | `PBZ_USMAP` | 自定义 `.usmap` 映射文件 |
  73. | `PBZ_AES_KEY` | 自定义 AES 密钥 |
  74. | `PBZ_CUE4_CLI` | 自定义已构建 CLI 路径 |
  75. | `PBZ_ASSET_PATH` | CLI 默认资产路径 |
  76. | `PBZ_EXPORT_DIR` | CLI 默认导出目录 |
  77. 命令行参数 `--paks`、`--usmap`、`--aes-key`、`--path`、`--out` 优先于同名环境变量。AES 密钥属于游戏版本配置,不是 GitHub 或个人账号凭据;请不要把个人访问令牌写入此项目。
  78. ## 安装为 Codex Skill
  79. 在 Codex 中,可直接把仓库指定为 skill 来源进行安装,或手动克隆到:
  80. ```text
  81. %USERPROFILE%\.codex\skills\pbz-unpack
  82. ```
  83. 然后完成一次 `scripts\install.ps1` 构建。之后可这样提问:
  84. ```text
  85. 使用 $pbz-unpack 查找并导出 Yuu_Body,保留材质 JSON。
  86. ```
  87. skill 入口为 [`SKILL.md`](SKILL.md),不依赖你机器上已有的其他 PBZ skill。
  88. ## 仓库结构
  89. ```text
  90. pbz-unpack/
  91. ├─ config/pbz.json # 游戏版本、AES 与映射校验值
  92. ├─ mappings/ # 完整 UE 类型映射
  93. ├─ src/PbzUnpack.Cli/ # CLI 源码与 NuGet 依赖锁定版本
  94. ├─ scripts/ # 安装、发现、检查和统一命令入口
  95. ├─ agents/openai.yaml # Codex 调用元数据
  96. ├─ references/troubleshooting.md # 故障排查
  97. └─ SKILL.md # Codex skill 入口
  98. ```
  99. `.build`、`.tools`、`output`、游戏导出物和缓存均已排除在 Git 跟踪之外。
  100. ## 更新游戏配置
  101. 1. 将新映射放入 `mappings`,或用 `PBZ_USMAP` 临时测试。
  102. 2. 在 `config/pbz.json` 更新 `gameBuild`、`aesKey`、`mappings` 与 `mappingSha256`。
  103. 3. 如果引擎小版本变化,更新 CLI 的 `VersionContainer` 并确认 CUE4Parse 支持。
  104. 4. 运行 `check-environment.ps1 -Deep`,再执行一次小规模 `inspect` 与 `export`。
  105. ## 常见问题
  106. - **提示找不到游戏**:设置 `PBZ_PAK_DIR`,或先用 `find-pbz-game.ps1 -SteamRoots` 检查 Steam 库发现。
  107. - **提示 ASSET_AMBIGUOUS**:从输出中选择更完整的 `--path`;确认需要导出全部匹配项时才加 `--all`。
  108. - **解密或映射失败**:不要只更换 AES。确认密钥、映射和实际游戏版本相匹配。
  109. - **原生压缩库错误**:使用 `scripts\install.ps1 -Force` 重新发布,并始终通过 `scripts\pbz.ps1` 运行。
  110. 更多排查见 [`references/troubleshooting.md`](references/troubleshooting.md)。
  111. ## 许可与边界
  112. 本仓库不包含游戏 Pak、模型、纹理或其他提取后的商业游戏资源,仅提供互操作所需的配置、类型映射与工具源码。请仅处理你合法持有的游戏副本,并遵守游戏条款及当地法律。
  113. 原创脚本与 CLI 源码采用 [MIT License](LICENSE)。CUE4Parse 及其依赖归各自作者所有,详见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。游戏相关的 AES、映射数据及《影之刃零》名称不归本仓库作者所有,MIT 许可证不授予这些第三方内容的额外权利。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.