---
name: ue-python
description: 编写或修改 UE 进程内执行的 Python 脚本时使用，要求严格基于 UE 5.7 官方 Python API 文档写代码，禁止臆造 unreal API，约束时间戳写法、文件 I/O 与异常处理，避免 unreal.DateTime.now 等兼容性错误。
---

# ue-python

编写或修改在 UE 进程内执行的 Python 脚本时使用。

适用范围：`-ExecutePythonScript`、`worker_unified.py`、`render_engine.py`，以及所有 `ue_pipeline/python/` 下运行在 UE embedded Python 环境中的代码。

## 核心原则

### 0. 禁止幻觉式编写 Unreal API

**所有 `unreal.*` API 都必须以 UE 5.7 官方 Python API 文档为准。**

权威入口：

- `https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/index?application_version=5.7`

禁止行为：

- 按 Python/Blueprint/C++ 经验臆测 UE Python API 名称
- 看见某个 Unreal 概念就直接假设 Python 绑定一定存在
- 想当然地把其它版本 UE 文档中的 API 当成 5.7 可用
- 在没有验证的情况下写出 `unreal.SomeClass.some_method()`

如果官方文档中找不到，默认 **不可用**，不能硬写。

可接受的写法顺序：

1. 先查 UE 5.7 官方 Python API 文档
2. 再看仓库里是否已有已运行过的同类调用
3. 如仍不确定，在 UE Python Console 做最小验证
4. 仍无法确认时，不写该 API，改用已知可用方案

## 强制规则

### 1. 时间戳统一使用 Python 标准库

禁止使用 `unreal.DateTime.now()`。

原因：UE Python 中该 API 不存在，会报错：`AttributeError: type object 'DateTime' has no attribute 'now'`。

正确写法：

```python
from datetime import datetime as _dt

payload = {
	"time": _dt.now().isoformat(),
}
```

### 2. 文件/路径/进程操作使用标准库

- 文件 I/O 使用 `open`、`os`、`pathlib`、`json`、`shutil`
- 进程与子命令使用 `subprocess`
- 不使用 `unreal.Paths.*` 处理宿主机文件路径，除非明确是在处理 UE 资产路径

### 3. 新增 `unreal.*` API 调用前必须先验证

不要假设 `unreal.*` 上的方法存在。

可接受的验证方式：

- 查 **UE 5.7 官方 Python API 文档**
- 在 UE Python Console 中执行 `dir(unreal.SomeClass)` 或最小调用验证
- 参考仓库内已运行过的同类用法

不满足上述条件时：

- 不要生成该 API 调用
- 不要输出“应该可以”“通常有这个方法”这类不确定表述
- 明确改写为保守实现，或先在日志中暴露缺失信息

### 4. 顶层异常必须可回传到外部管线

UE 进程内 Python 异常默认只写 UE 日志，外部 `subprocess` 侧不一定能从 returncode 正确感知。

因此：

- 顶层必须有 `try/except`
- 失败时必须写 results 文件或其他外部可读状态
- 失败路径必须显式 `sys.exit(1)`

### 5. UE API 与逻辑代码必须分层

所有直接调用 `unreal.*`、直接访问 UE 子系统、蓝图类、组件模板、MRQ、地图加载的代码，统一放到 `ue_pipeline/python/ue_api/` 目录。

目录内脚本按功能命名，优先使用这类边界：

- `editor_subsystems.py`：编辑器子系统、世界、导航、MRQ
- `asset_loading.py`：地图、蓝图类、资产加载
- `camera_components.py`：相机组件解析、相机属性读取、组件修改

业务/逻辑模块（如 `rendering/`、`sequence/`、`export/`、`navmesh/`）不得重复实现 UE 直连细节，只能调用 `ue_pipeline.python.ue_api` 提供的公共入口。

允许的例外：

- 明确属于 CLI 或脚本启动胶水的极小量 `unreal` 接触，但不得承载可复用实现

禁止行为：

- 在业务模块中重复写 `load_blueprint_class` / `get_default_object` / `get_components_by_class`
- 在多个模块里各自维护一份相机组件查找逻辑
- 在业务模块中直接修改 `post_process_settings`、`weighted_blendables` 等组件底层属性

正确做法：

- 先在 `ue_api/` 中封装稳定的 UE 操作
- 再让逻辑模块调用该封装
- 公共能力优先提取为可复用函数，不在 `rendering/`、`export/` 中复制粘贴

### 6. 相机相关能力必须复用统一入口

相机组件的以下能力视为公共基础能力，必须集中在 `ue_pipeline/python/ue_api/camera_components.py` 或其后续拆分模块中维护：

- 从蓝图 CDO 解析相机组件
- 从 Sequence binding/template 解析相机组件
- 读取内参、相机本地 Transform 等组件属性
- 修改后处理材质权重等组件配置

后续新增 UE 相机能力时，先扩展 `ue_api`，再修改调用方；禁止在调用方直接散写新的 `unreal.*` 相机访问逻辑。

## 常见坑

- `unreal.DateTime.now()` 不存在
- 很多 Blueprint/C++ 能力在 Python 绑定中没有同名方法
- 同一个 API 在 UE 不同版本之间可能存在或缺失
- `sys.exit(1)` 不一定被 `-ExecutePythonScript` 透传成外部非零返回码
- 主进程注册的 UE 回调在子进程渲染模式下可能不会按预期触发

## 检查清单

- [ ] 新增 `unreal.*` API 已对照 UE 5.7 官方 Python API 文档
- [ ] 没有使用 `unreal.DateTime`
- [ ] 新增的 `unreal.*` API 已验证存在
- [ ] 文件 I/O、时间、路径操作优先使用 Python 标准库
- [ ] 顶层异常已写入外部可读结果并显式退出
- [ ] 可复用的 UE 直连代码已放入 `ue_pipeline/python/ue_api/`
- [ ] 业务模块没有重复实现 UE 直连逻辑
- [ ] 相机属性读取与组件修改已复用统一的 `ue_api` 入口