---
name: ue57-python-api
description: UE5.7 Python API 实测差异记录——set_actor_rotation、new_level、CWD 问题
metadata:
  type: project
---

# UE5.7 Python API 实测差异

## 2026-06-07 实测（UE 5.7, PythonScriptPlugin）

### `set_actor_rotation()` 需要 `teleport_physics` 参数
```python
# UE5.6 文档写法（会报错）:
actor.set_actor_rotation(unreal.Rotator(pitch, yaw, roll))

# UE5.7 正确写法:
actor.set_actor_rotation(unreal.Rotator(pitch, yaw, roll), False)
```
**Why:** UE5.7 改了 API 签名，positional argument `teleport_physics` 变为必需
**How to apply:** 所有 `set_actor_rotation()` 调用都加第二个参数 `False`

### `unreal.Rotator` 位置参数顺序不是 (Pitch, Yaw, Roll)
```python
# ❌ 错误：位置参数顺序非 P,Y,R，Yaw=90 会落到 Pitch(Y显示)
actor.set_actor_rotation(unreal.Rotator(0, 90, 0), False)

# ✅ 正确：用关键字参数避免歧义
actor.set_actor_rotation(unreal.Rotator(pitch=0, yaw=90, roll=0), False)
```
**Why:** UE5.7 Python `unreal.Rotator` 的位置参数顺序与关键字参数名不一致，第二个位置参数映射到 Pitch 而非 Yaw
**How to apply:** 所有 `unreal.Rotator()` 调用必须使用关键字参数 `pitch=, yaw=, roll=`

### `-ExecutePythonScript` 模式下 CWD 不是项目目录
```python
# ❌ 错误：CWD 是引擎 Binaries 目录
PROJECT_ROOT = Path(os.getcwd())
# → E:\...\UE_5.7\Engine\Binaries\Win64

# ✅ 正确：通过环境变量传入
PROJECT_ROOT = Path(os.environ.get("LB_PROJECT_ROOT", ""))
```
**Why:** UE5 引擎启动时将 CWD 设为引擎二进制目录
**How to apply:** 由 bat 脚本设置 `LB_PROJECT_ROOT` 环境变量，Python 脚本从中读取

### `new_level()` 需要 `asset_path` 参数
```python
# ❌ 错误：
unreal.EditorLevelLibrary.new_level()

# ✅ 正确：
unreal.EditorLevelLibrary.new_level("/Game/Maps/LVL_SuburbanV01")
```

### `AssetToolsSubsystem` 在 UE5.7 Python 中不可用
`unreal.get_editor_subsystem(unreal.AssetToolsSubsystem)` 报 `no attribute 'AssetToolsSubsystem'`
改用 `unreal.EditorLevelLibrary.new_level(asset_path)` 创建关卡

### 目录名含连字符导致 Python import 失败
```
tools/level-builder/  ← 连字符
from tools.level_builder.config...  ← 下划线，Python import 不支持连字符
```
修复：将 level-builder 根目录加入 sys.path，使用 `from config.asset_mapping import ...` 代替完整路径

## 相关文件
- `tools/level-builder/builder/scene_builder.py`
- `tools/level-builder/build_cmdline.py`
- `tools/level-builder/build_level.bat`