70 lines
2.5 KiB
Markdown
70 lines
2.5 KiB
Markdown
---
|
||
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`
|