ChildHood/.claude/agent-memory/game-dev/ue57-python-api.md

name, description, metadata

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

UE5.7 Python API 实测差异

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

set_actor_rotation() 需要 teleport_physics 参数

# 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

-ExecutePythonScript 模式下 CWD 不是项目目录

# ❌ 错误：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 参数

# ❌ 错误：
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