# python工具

**Repository Path**: kcat11/python-tools

## Basic Information

- **Project Name**: python工具
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PythonUE — UEpak 工具需求说明

基于 Python GUI 的 Unreal Engine 资源打包辅助工具，用于简化 **Cook → Pak** 工作流，支持自动定位引擎工具、配置 Cook 目录、执行 Cook，以及手动 Pak 打包。

---

## 1. 项目目标

| 目标 | 说明 |
|------|------|
| 降低操作门槛 | 用图形界面替代手写 UAT / UnrealPak 命令行 |
| 路径可配置 | 支持多套 UE 引擎、多个项目并存 |
| 流程可追溯 | 输出日志、保存历史配置，便于排查打包失败 |
| 灵活打包 | 支持全自动 Cook + Pak，也支持跳过 Cook、仅手动 Pak |

---

## 2. 功能需求

### 2.1 浏览并定位 Pak 编译器（UnrealPak）

**需求描述：** 用户可通过文件浏览器选择或自动扫描 Unreal Engine 安装目录，定位 `UnrealPak.exe` 及关联工具。

**需支持的工具路径：**

| 工具 | 典型路径 | 用途 |
|------|----------|------|
| `UnrealPak.exe` | `{Engine}/Engine/Binaries/Win64/UnrealPak.exe` | 创建 / 解包 `.pak` |
| `UnrealEditor-Cmd.exe` | `{Engine}/Engine/Binaries/Win64/UnrealEditor-Cmd.exe` | Cook、命令行编辑操作 |
| `RunUAT.bat` | `{Engine}/Engine/Build/BatchFiles/RunUAT.bat` | 完整 Build / Cook / Stage / Pak 流水线 |

**交互要求：**

- [ ] 提供「浏览…」按钮，手动选择 `UnrealPak.exe`
- [ ] 提供「自动检测」：扫描常见安装路径（Epic Launcher 默认目录、自定义 Engine 目录）
- [ ] 选择引擎根目录后，自动推导上述工具路径并展示，允许逐项覆盖
- [ ] 路径校验：文件存在性检查，版本信息展示（可选，读取引擎 `Build.version`）
- [ ] 配置持久化：保存到本地 JSON / 配置文件，下次启动自动加载

**验收标准：**

- 用户选定路径后，界面显示绿色「已就绪」状态
- 路径无效时给出明确错误提示，禁止进入后续 Cook / Pak 步骤

---

### 2.2 配置 Cook 相关目录

**需求描述：** 用户指定 UE 项目及 Cook 输入/输出目录，明确哪些内容需要被 Cook。

**需配置的目录/参数：**

| 配置项 | 说明 | 示例 |
|--------|------|------|
| 项目文件 `.uproject` | Cook 的目标项目 | `D:/Game/MyGame.uproject` |
| 项目 Content 目录 | 需 Cook 的内容根目录 | `{Project}/Content` |
| Cook 输出目录 | Cook 结果存放位置 | `{Project}/Saved/Cooked/WindowsNoEditor` |
| Staging 目录 | Pak 打包前的暂存目录 | `{Project}/Saved/StagedBuilds/WindowsNoEditor` |
| 目标平台 | Cook 与 Pak 的平台 | `WindowsNoEditor` / `Android_ASTC` 等 |
| 配置名（Config） | 开发 / 发布配置 | `Development` / `Shipping` |

**Content 筛选（可选增强）：**

- [ ] 树形或列表展示 `Content/` 下目录，勾选需要 Cook 的子目录
- [ ] 支持排除规则（如 `Content/Editor`、`Content/Developers`）
- [ ] 支持 `-CookDir` / `-Map` 等参数的可视化配置

**交互要求：**

- [ ] 「浏览项目」：选择 `.uproject` 后自动填充 Content、Saved 等默认路径
- [ ] 所有路径支持手动修改与浏览选择
- [ ] 显示目录是否存在、是否可写
- [ ] 支持保存多套「项目配置方案」，快速切换

**验收标准：**

- 选定项目后，Cook 输出目录与 Staging 目录按 UE 惯例自动建议，用户可改
- 缺少 `.uproject` 或 Content 目录不存在时，界面阻止 Cook 并提示原因

---

### 2.3 Cook 执行

**需求描述：** 根据上述配置，调用 UE 命令行完成资源 Cook，并在 GUI 中实时展示进度与日志。

**Cook 方式（至少支持一种，建议两种）：**

1. **RunUAT BuildCookRun**（推荐，适合完整流水线）
   ```bat
   RunUAT.bat BuildCookRun ^
     -project="MyGame.uproject" ^
     -noP4 -platform=Win64 -clientconfig=Development ^
     -cook -skipstage -skippak -skippackage
   ```

2. **UnrealEditor-Cmd 单独 Cook**
   ```bat
   UnrealEditor-Cmd.exe "MyGame.uproject" -run=cook -targetplatform=WindowsNoEditor
   ```

**功能要求：**

- [ ] 「开始 Cook」按钮，Cook 过程中可「取消」（终止子进程）
- [ ] 实时输出 stdout / stderr 到日志面板，支持滚动、复制、导出
- [ ] Cook 完成后展示结果：成功 / 失败、耗时、输出目录文件数量（可选）
- [ ] Cook 失败时高亮错误行，给出常见原因提示（路径错误、Shader 编译失败等）
- [ ] 可选参数：`-iterate`、`-Unversioned`、指定 Map 列表

**验收标准：**

- Cook 成功后，`Cook 输出目录` 下生成对应平台的 cooked 资源
- 重复 Cook 同一配置时不覆盖用户未保存的其他项目配置

---

### 2.4 手动 Pak 打包

**需求描述：** 在 Cook 完成（或直接指定已有 Cook/Staged 目录）后，用户可手动配置 Pak 列表并执行打包，不强制依赖自动流水线。

**手动 Pak 需支持的配置：**

| 配置项 | 说明 |
|--------|------|
| Pak 输出路径 | 生成的 `.pak` 文件路径，如 `{Project}/Paks/MyGame.pak` |
| 挂载点（Mount Point） | 通常 `../../../{ProjectName}/` |
| 输入目录 | Cook 或 Staged 后的目录，作为 Pak 内容来源 |
| 压缩 | 是否启用 `-compress`、压缩算法（如 Oodle，视引擎版本） |
| 加密（可选） | AES Key、是否启用 `-encrypt` |
| Response File | 支持导入 / 编辑 `.txt` 响应文件（UnrealPak 标准格式） |

**UnrealPak 命令示例：**

```bat
UnrealPak.exe "D:/Output/MyGame.pak" ^
  -Create="D:/Output/FileList.txt" ^
  -compress
```

Response File 示例（`FileList.txt`）：

```text
"../../../MyGame/Content/Maps/Main.umap" "D:/Game/Saved/Cooked/WindowsNoEditor/MyGame/Content/Maps/Main.umap"
"../../../MyGame/Content/..." "D:/Game/Saved/Cooked/WindowsNoEditor/MyGame/Content/..."
```

**交互要求：**

- [ ] 「生成 Response File」：根据选中的 Cook 输出目录自动生成文件列表
- [ ] 「浏览 Response File」：加载已有列表进行编辑（表格：虚拟路径 / 物理路径）
- [ ] 「开始 Pak」：调用 `UnrealPak.exe` 执行打包
- [ ] 支持「仅 Pak、不 Cook」模式：跳过 Cook，直接对已有目录打包
- [ ] Pak 完成后校验：文件大小、可选 `-List` 预览 Pak 内容
- [ ] 支持批量生成多个 Pak（如按 Content 子目录拆分，可选）

**验收标准：**

- 生成的 `.pak` 可被 UE 正常挂载加载（与手动命令行打包结果一致）
- Response File 可保存、复用，便于版本管理与差异对比

---

## 3. 界面结构建议

```
┌─────────────────────────────────────────────────────────┐
│  [引擎与工具]  UnrealPak / RunUAT / Editor-Cmd  [浏览]   │
├─────────────────────────────────────────────────────────┤
│  [项目配置]  .uproject | 平台 | Config | Content 目录    │
│              Cook 输出 | Staging | Pak 输出              │
├─────────────────────────────────────────────────────────┤
│  [Cook]      [开始 Cook]  [取消]     状态: 就绪/进行中    │
├─────────────────────────────────────────────────────────┤
│  [手动 Pak]  Response File [生成] [编辑] [开始 Pak]      │
├─────────────────────────────────────────────────────────┤
│  [日志输出]  ..........................................  │
└─────────────────────────────────────────────────────────┘
```

---

## 4. 非功能需求

| 类别 | 要求 |
|------|------|
| 平台 | Windows 10+（与 UE Windows 工具链一致） |
| 技术栈 | Python 3.8+、CustomTkinter（或现有 GUI 框架） |
| 进程管理 | 子进程异步执行，避免界面卡死 |
| 配置存储 | `%USERPROFILE%/.pythonue/` 或项目内 `config.json` |
| 日志 | 每次 Cook / Pak 写入带时间戳的日志文件 |
| 错误处理 | 命令非零退出码、路径缺失、引擎版本不匹配均需友好提示 |

---

## 5. 开发阶段建议

| 阶段 | 内容 | 优先级 |
|------|------|--------|
| P0 | 工具路径浏览与校验、项目路径配置、手动 Pak + Response File | 高 |
| P1 | Cook 执行与日志面板、配置持久化 | 高 |
| P2 | 自动检测引擎、Content 目录树勾选 | 中 |
| P3 | Pak 加密、批量 Pak、历史记录与一键重跑 | 低 |

---

## 6. 依赖与环境

- 本机已安装 Unreal Engine（版本由用户项目决定，工具需兼容 UE 4.x / 5.x 路径差异）
- 无需将 UE 源码纳入本仓库；仅调用已安装引擎中的二进制工具
- Python 依赖见 `requirements.txt`
目前用于UE5.1.1
---

## 7. 术语说明

| 术语 | 含义 |
|------|------|
| Cook | 将 UE 资产转换为目标平台可运行的格式 |
| Stage | 将 Cook 结果与可执行文件整理到发布目录 |
| Pak | UE 使用的压缩资源包格式 |
| UnrealPak | Epic 提供的 Pak 创建与解包命令行工具 |
| Response File | UnrealPak 的文件列表参数文件，映射挂载路径与磁盘路径 |
| Mount Point | Pak 内资源在虚拟文件系统中的根路径 |