1. 定位

Python 是"编辑器侧的批处理与管线自动化"语言，不是游戏逻辑语言。

官方原话：Python 环境只在编辑器里可用，在 PIE / Standalone / cooked 可执行文件中都不可用。所以它不能当 gameplay 脚本语言用。

一句话定位：跨 DCC 工具链的资产管线、批量资产处理、程序化摆关卡——这些是 Python 的主场；运行时逻辑一律不归它管。

2. 启用

步骤	内容
插件	Python Editor Script Plugin（`Scripting` 分类）
建议同开	Editor Scripting Utilities（提供简化 API）
生效	需重启编辑器
范围	按项目分别启用，不是全局

内置 Python 3.11.8，不必单独安装。要换版本需设 UE_PYTHON_DIR 并从源码重编引擎——这是很重的动作，一般不做。

3. 六种运行方式

方式	场景	备注
Output Log 的 Python 控制台	交互式、逐行	唯一能逐行执行的方式；`Shift+Enter` 多行
`py` 控制台命令	Cmd 模式下跑一行/文件	官方不建议放在 `ExecCmd` 里——会早于编辑器就绪
File 菜单（Execute Python Script）	手动跑文件	有 Recent 列表
命令行 `-ExecutePythonScript=`	完整编辑器 + CI	编辑器跑完即关闭
Commandlet `-run=pythonscript -script=`	快、可 headless	跑完即关；不会自动加载关卡，要手动 `load_level`
`init_unreal.py`	团队统一初始化	放在 Project/Plugin 的 `Content/Python`

启动脚本（Project Settings → Plugins → Python → Startup scripts）在默认启动关卡加载完成后运行——这是"编辑器已就绪"的可靠时机，比 py 放 ExecCmd 安全。

4. 路径

自动加入 sys.path 的目录：项目 Content/Python、引擎 Content/Python、各启用插件的 Content/Python、用户 Documents/UnrealEngine/Python。

自定义路径三种方式：项目设置 Additional Paths、UE_PYTHONPATH 环境变量、脚本里直接改 sys.path。

默认以 isolated 模式运行（可在项目设置关掉）。UE_PYTHONPATH 无论隔离与否都会被解析——它不该被第三方软件改动，这是它区别于 PYTHONPATH 的地方。

5. API 要点

import unreal

# 编辑器子系统
unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).load_level("/Game/maps/M.M")

# 编辑器属性（走 pre/post-edit，等价手改 Details 面板）
obj.set_editor_property("play_on_open", True)
obj.get_editor_property("play_on_open")

# 撤销事务
with unreal.ScopedEditorTransaction("My Tx") as tx:
    obj.set_editor_property("v", 1)

# 慢操作进度条
with unreal.ScopedSlowTask(100, "Working") as st:
    st.make_dialog(True)
    for i in range(100):
        if st.should_cancel(): break
        st.enter_progress_frame(1)

规则	说明
`unreal` 模块不是预生成的	它自动反射编辑器里 Blueprints 暴露的一切——开新插件、写 C++ 暴露给蓝图，都会自动出现在 Python 里
命名	类名同蓝图（去前缀）；函数/属性转 lower_snake_case；枚举 UPPER_SNAKE_CASE
容器	Python list/set/dict 与 UE 容器自动互转
参数	支持顺序或命名参数（任意顺序）
继承	保持原生继承层次，`isinstance` 可用
日志	`unreal.log` / `log_warning` / `log_error`；`print` 内部走 `unreal.log`

6. 四条官方最佳实践

实践	说明	违反的后果
绝不用 Python 的文件模块直接动资产	不要用 `os.rename` / `shutil.move`	破坏资产内部引用。要用 `EditorAssetLibrary` 或 `AssetTools`
设属性优先 `set_editor_property`	而非直接赋值	直接改不会触发 pre/post-edit，编辑器 UI 与状态不同步
优先用 Unreal 类型	如 `unreal.Vector` 而非自己实现	引擎版是优化过的
大批量用 `ScopedSlowTask`	跑脚本时编辑器 UI 会被阻塞	看起来像卡死

set_editor_property vs 直接赋值是最容易踩的一条：直接改属性在多数情况下"看起来成功"，但编辑器不会跑前/后处理，UI 不刷新。

不是所有编辑器操作都可撤销——例如导入模型不可撤销，把它放进 ScopedEditorTransaction 也不会如预期工作。

7. 从蓝图调 Python

仅在 Editor-only 蓝图类（Editor Utility Widget / Editor Utility Blueprint）中可用：

节点	用途
Execute Python Script	执行字面量代码，官方推荐，支持自定义输入输出引脚
Execute Python Command	代码或文件（自动判定）
Execute Python Command (Advanced)	可选 `Execute File` / `Execute Script` / `Evaluate Script`，以及 `Public`/`Private` 作用域

重要：官方明确说 BPFL（BlueprintFunctionLibrary）方式已不再受官方支持——因为 Python 生成的类型是 transient 的，资产保存/加载时会出问题。

Execute Python Script 只能跑代码，不能跑文件；要跑文件用 Execute Python Command。

8. 代价与权衡

设计	收益	代价	什么时候不该用
Python	跨 DCC 管线、无需编译、PySide 可做复杂 UI	不能用于运行时；标记为 Experimental	涉及运行时逻辑 → 用 C++/蓝图
Commandlet 方式	快、可 headless	不会自动加载关卡	需要关卡内容时改用 `-ExecutePythonScript`
EUW + Python	有 UI、策划可改	仍是编辑器专用	—
`init_unreal.py`	团队一致	改了会影响所有人	个人实验不要放
直接改 `sys.path`	灵活	不可移植	优先用项目设置/环境变量

9. 踩坑与排查

坑	现象	怎么验证
用 `os.rename` 动资产	引用断裂	一律用 `EditorAssetLibrary`
直接赋值而非 `set_editor_property`	值改了但 UI/状态不同步	改用 `set_editor_property`
把 `py` 放进 `ExecCmd`	脚本早于编辑器就绪就跑	改用启动脚本
Commandlet 里没加载关卡	找不到内容	手动 `load_level`
以为 Python 能在 PIE 里用	不可用	只在编辑器
用 BPFL 方式	保存/加载出问题	改用 `Execute Python Script` 节点
大批量无进度条	编辑器像卡死	`ScopedSlowTask`
把不可撤销操作放进事务	撤销不像预期	检查该操作在 UI 里是否可撤销

10. 排查顺序

1. 脚本报错？ → Output Log（print 走 unreal.log）
2. 属性改了没生效？ → 是否用了 set_editor_property
3. 资产引用断了？ → 是否用 Python 文件模块直接动过资产
4. Commandlet 找不到内容？ → 是否手动 load_level
5. 编辑器卡住？ → 加 ScopedSlowTask
6. 想用于运行时？ → 不可能，换 C++/蓝图

参考

Editor 工具与 Utility · Slate 编辑器界面 · Editor Extension
资产注册表与编辑器查询 · 模块与 Subsystem · 反射与 UHT
官方：Unreal Editor Python API Reference