# ue5-python-hot-update

**Repository Path**: Mu-L/ue5-python-hot-update

## Basic Information

- **Project Name**: ue5-python-hot-update
- **Description**: ue5利用cpython进行热更新
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# python_hot_update — UE5 Python 热更新框架

UE5.7 + 嵌入式 CPython 热重载项目。修改 Python 游戏逻辑 → Ctrl+S → 立即生效，无需重启编辑器。

## 快速开始

```bash
# 1. 一键环境部署（双击或命令行）
setup.bat

# 2. 编译 C++ 插件（关闭 UE 编辑器后）
.\build.bat

# 3. 打开项目
python_hot_update.uproject  → 双击或用 UE5 打开

# 4. 运行
点击 Play (Alt+P) — 能量球收集游戏启动！
```

## 项目结构

```
python_hot_update/
├── setup.bat                  # 一键部署向导（双击运行）
├── build.bat                  # C++ 编译脚本
├── python_hot_update.uproject # UE5 项目文件
├── PythonScripts/             # 🔥 Python 热重载脚本（不在 Content 下）
│   ├── core/                  # 🔒 框架层（架构师维护，业务勿动）
│   │   ├── __init__.py
│   │   ├── core_audio.py      # 音频管理
│   │   ├── core_config.py     # 配置系统
│   │   ├── core_data.py       # 游戏数据表
│   │   ├── core_debug.py      # 调试控制台
│   │   ├── core_event.py      # 事件总线 / 委托
│   │   ├── core_hotupdate.py  # 资源热更新
│   │   ├── core_input.py      # 输入管理
│   │   ├── core_module.py     # 模块生命周期
│   │   ├── core_network.py    # 网络复制 / RPC
│   │   ├── core_platform.py   # 平台检测
│   │   ├── core_pool.py       # 对象池
│   │   ├── core_save.py       # 存档系统
│   │   ├── core_state.py      # 状态机
│   │   ├── core_task.py       # 协程调度
│   │   ├── core_ui.py         # UI 管理
│   │   └── core_watchdog.py   # 性能监控
│   ├── framework.py           # 框架入口（懒加载所有 core 模块）
│   ├── game_utils.py          # UE API 封装工具
│   ├── game_logic.py          # ✏️ 主游戏逻辑（业务开发者改这里）
│   ├── demo_showcase.py       # ✏️ 功能演示
│   ├── main_menu.py           # ✏️ 主菜单
│   ├── main_menu_handlers.py  # ✏️ 主菜单事件
│   ├── ui_example.py          # ✏️ UI 示例
│   ├── ui_handlers.py         # ✏️ UI 事件处理
│   ├── ue_types.py            # UE 类型封装
│   ├── ue_ui.py               # UE UI 封装
│   ├── ue_3d.py               # UE 3D 工具
│   ├── pypy_bridge.py         # PyPy 高性能桥接
│   └── pypy_worker.py         # PyPy 工作进程
├── Plugins/PythonHotReload/   # C++ 热重载插件
│   └── Source/PythonHotReload/
│       ├── Private/
│       │   ├── PythonBridge.cpp     # CPython 嵌入 / sys.path / ue.* API
│       │   ├── PythonGameInstance.cpp # 自动发现 / MD5 / on_tick 分发
│       │   └── PythonHotReloadManager.cpp # 目录监控 / 文件变更检测
│       └── Public/
├── Myself_Tools/              # 开发工具集
│   ├── setup.py               # 安装向导本体
│   ├── build.py               # 打包/构建脚本
│   ├── setup_vscode.py        # VS Code IntelliSense 配置
│   ├── setup_android_sdk.py   # Android SDK 安装
│   └── psd/                   # PSD → UE UI 工具链
└── Source/                    # C++ 源码
```

## 环境要求

| 组件 | 要求 | 说明 |
|------|------|------|
| UE5 | 5.7 | 引擎根目录需包含 `Engine/Source/Runtime/Core` |
| Python | 3.10+ | 嵌入式 CPython 3.12 推荐 |
| VS Build Tools | 2022 | C++ 编译工具链（无需完整 IDE） |
| Git | 任意 | 版本管理 |

> 运行 `setup.bat` 可自动检测所有依赖。

## 常用命令

| 命令 | 用途 |
|------|------|
| `setup.bat` | 一键部署开发环境（交互式） |
| `setup.bat --check` | 仅检查环境状态 |
| `.\build.bat` | 编译 C++ 插件（自动刷新 IntelliSense） |
| `python Myself_Tools\setup.py --intellisense` | 刷新 VS Code 智能提示 |
| `python Myself_Tools\build.py setup` | 安装依赖 + VS Code 配置 |
| `python Myself_Tools\build.py package` | 打包项目 |

## 热重载开发流程

```
修改 game_logic.py → Ctrl+S 保存
    ↓
PythonHotReload 插件检测文件变更（MD5）
    ↓
自动重新 import → 新代码立即生效
    ↓
UE 编辑器中直接看到效果（无需重启）
```

## 核心特性

- **热重载** — Python 代码修改后立即生效，秒级迭代
- **框架层** — 14+ 核心模块：存档、输入、UI、网络、3D、平台检测、资源热更新
- **跨平台** — PC / Android 双平台支持
- **PSD → UI** — Photoshop 设计稿直接生成 UE UMG 界面
- **PyPy 桥接** — 高性能计算任务卸载到 PyPy JIT 运行时
- **一键部署** — `setup.bat` 自动检测引擎、配置环境变量、生成 IntelliSense

## 文件修改决策

| 改什么 | 改哪里 | 需编译？ | 谁维护 |
|--------|--------|:------:|:------:|
| 游戏玩法/逻辑 | `game_logic.py` 等业务文件 | 否 | ✏️ 业务开发者 |
| UI/3D 工具 | `ue_ui.py` / `ue_3d.py` | 否 | ✏️ 业务开发者 |
| 框架核心 | `core/*.py` | 否 | 🔒 架构师 |
| 框架入口/桥接 | `framework.py` / `game_utils.py` | 否 | 🔒 架构师 |
| 新增 ue.* C++ 函数 | `PythonBridge.cpp` | **是** | 🔒 架构师 |
| 热重载引擎 | `PythonGameInstance.cpp` 等 | **是** | 🔒 架构师 |

> ⚠ `core/` 目录由架构师维护，业务开发者不应修改。

## 环境变量

`setup.bat` 会自动设置以下永久环境变量：

| 变量 | 值 | 用途 |
|------|-----|------|
| `UE_ROOT` | 引擎根路径 | build.bat 使用 |
| `UE5_ROOT` | 同上 | VS Code 配置使用 |
| `ANDROID_SDK_ROOT` | Android SDK 路径 | 移动端打包 |
| `ANDROID_NDK_ROOT` | Android NDK 路径 | 移动端打包 |

配置保存在 `Myself_Tools/config/env.json`（已加入 .gitignore）。

## License

Internal project — commercial use.