使用CodeBuddy为UE4项目合入HTML5能力
背景
开源的SpeculativeCoder的4.27-html5-es3分支是基于官方UE4.27.2来开发的HTML5功能
当前项目是基于UE4.26.1的，研发过程中做过大量修改
使用CodeBuddy AI能力为当前项目合入HTML5能力
模式选择Plan，大模型选Claude-Sonnet-4.5
交互1：如何把当前工程UE4.27.2的HTML5功能合到UE4.26.1引擎上
CodeBuddy answer
我来帮您理解如何将当前工程（UE4.27.2）的HTML5功能合并到UE4.26.1引擎上。让我先探索一下当前的HTML5相关代码结构。 Searched HTML5 Searched files Root Directory *HTML5* Listed e:/UE427H5/UnrealEngine/Engine/Platforms Read HTML5SDKInfo.cs L1-End Searched 4\.27-html5-es3
让我继续探索HTML5平台的关键目录结构和构建文件： Listed e:/UE427H5/UnrealEngine/Engine/Platforms/HTML5 Listed e:/UE427H5/UnrealEngine/Engine/Platforms/HTML5/Source Searched HTML5.*Platform Read README.md L1-End
现在我需要了解一下这是一个什么样的合并需求。让我查看一些关键的信息： Read README.md L1-End Searched HTML5 基于我对代码库的分析，我理解了您的需求。现在让我明确几个问题以便更好地制定计划： 我的理解： 1. 当前工程是 UE4.27.2 的一个分支，包含了 HTML5 ES3 (WebGL 2) 平台支持 2. 您需要将这些 HTML5 功能移植/合并到 UE4.26.1 引擎上 3. 这是一个第三方社区维护的 HTML5 平台扩展（Epic 官方在 UE4.24 后停止了 HTML5 支持）
需要确认的问题： 1. 目标 UE4.26.1 引擎状态：您的 UE4.26.1 引擎是官方原版吗？还是已经有其他修改？是否已经有任何 HTML5 相关代码？ 2. 合并范围：您需要完整的 HTML5 平台支持吗？包括： 构建工具链 (UnrealBuildTool 相关的 HTML5 支持) 运行时平台代码 (HTML5 Platform 模块) 第三方库 (Emscripten 编译的库) 插件支持 编辑器支持 (打包、部署等) 3. 期望的合并方式： 直接复制 HTML5 平台扩展文件夹？ 还是需要将修改过的引擎核心文件也一并合并？
您是否有访问 UE4.26.1 源码的路径？还是需要我先指导您获取？ 请回答这些问题，这样我才能为您制定更精确的合并计划。
交互2：1. UE4.26.1 引擎是官方原版的 2. 需要完整的 HTML5 平台支持 3. 合并方式：复制 HTML5 平台扩展文件夹，同时将修改过的引擎核心文件也一并合并
CodeBuddy answer
好的，我明白了。让我先快速探索一下当前 UE4.27.2 HTML5 版本中被修改的引擎核心文件，以便了解完整的修改范围。 Searched HTML5 Searched HTML5 Searched HTML5 Listed e:/UE427H5/UnrealEngine/Engine/Source/Runtime 让我再查看一些关键的修改文件，了解 HTML5 平台对引擎核心的具体影响： Read UEBuildTarget.cs L240-259 Searched HTML5 Listed e:/UE427H5/UnrealEngine/Engine/Source/Programs/UnrealBuildTool/Platform 好的，让我再检查一下是否有其他 HTML5 相关的平台代码： Searched files e:/UE427H5/UnrealEngine/Engine/Source/Programs/UnrealBuildTool *HTML5*.cs Searched files e:/UE427H5/UnrealEngine/Engine/Source *HTML5*.cpp Searched HTML5 现在让我最后确认一下需要合并的核心文件范围： Read BaseDeviceProfiles.ini L100-129 Read InstalledEngineBuild.xml L45-64 非常好！现在我已经充分了解了这个 HTML5 移植项目的结构。让我为您创建一个详细的合并计划。
会生成出UE427-HTML5-to-UE426-Migration.md文件，内容如下：
--- name: UE427-HTML5-to-UE426-Migration overview: 将 UE4.27.2 HTML5 ES3 (WebGL 2) 平台扩展完整移植到官方原版 UE4.26.1 引擎，包括平台扩展文件夹、引擎核心文件修改、构建系统配置和插件支持。 todos: - id: prepare-merge-environment content: 准备合并环境：验证 UE4.27.2 HTML5 源引擎和 UE4.26.1 目标引擎路径，创建备份和日志目录 status: completed - id: copy-html5-platform content: 复制完整的 HTML5 平台扩展目录（Engine/Platforms/HTML5/）到 UE4.26.1 引擎 status: completed dependencies: - prepare-merge-environment - id: explore-target-structure content: 使用 [subagent:code-explorer] 探索 UE4.26.1 目标引擎中待修改文件的准确结构和版本差异 status: completed dependencies: - prepare-merge-environment - id: merge-build-system content: 合并构建系统文件：修改 UEBuildTarget.cs 和 UEBuildModuleCPP.cs，添加 HTML5 平台定义和模块映射 status: completed dependencies: - copy-html5-platform - explore-target-structure - id: merge-engine-configs content: 合并引擎配置文件：更新 BaseDeviceProfiles.ini、BaseEngine.ini、BaseGame.ini、BaseScalability.ini 等配置 status: completed dependencies: - copy-html5-platform - explore-target-structure - id: merge-build-configs content: 合并构建配置：修改 InstalledEngineBuild.xml 和 InstalledEngineFilters.xml，添加 HTML5 构建目标和过滤规则 status: completed dependencies: - copy-html5-platform - explore-target-structure - id: merge-automation-tools content: 合并自动化工具：更新 BuildCommonTools.Automation.cs 和 DeploymentContext.cs，添加 HTML5 工具编译和部署逻辑 status: completed dependencies: - copy-html5-platform - explore-target-structure - id: adapt-plugins content: 适配 Oodle 压缩插件：修改 OodleData、OodleNetwork、TextureFormatOodle 的 .uplugin 和 .Build.cs 文件，跳过 HTML5 平台 status: completed dependencies: - copy-html5-platform - explore-target-structure - id: verify-merge content: 验证合并结果：生成合并报告，列出所有修改的文件和验证检查点 status: completed dependencies: - merge-build-system - merge-engine-configs - merge-build-configs - merge-automation-tools - adapt-plugins --- ## 用户需求 将当前 UE4.27.2 引擎（包含社区维护的 HTML5 ES3/WebGL 2 平台支持）的完整 HTML5 功能移植到 UE4.26.1 引擎上。 **目标引擎状态说明**： - UE4.26.1 引擎基于官方版本，但已包含其他业务修改 - **重要**：目标引擎中完全没有任何 HTML5 相关代码或配置 - 需要采用非破坏性合并策略，避免影响现有修改 ## 产品概述 这是一个引擎级别的平台扩展迁移任务。Epic Games 在 UE4.24 后停止了官方 HTML5 平台支持，但社区通过 SpeculativeCoder 项目为 UE4.27 维护了基于 Emscripten 3.1.50 的 HTML5 ES3 (WebGL 2) 平台支持。本任务需要将这套完整的平台扩展向下移植到 UE4.26.1 版本。 **目标引擎特点**： - 基于 UE4.26.1 官方版本 - 已包含其他业务相关的代码修改 - **无任何 HTML5 相关代码**（这简化了冲突检测，但需要谨慎插入） - 需要保证 HTML5 集成不影响现有功能 ## 核心功能 - **完整的 HTML5 平台扩展**：复制整个 Engine/Platforms/HTML5 目录，包含构建工具链、运行时代码、第三方库和平台插件 - **构建系统集成**：修改 UnrealBuildTool 以识别和支持 HTML5 作为目标平台 - **引擎配置更新**：添加 HTML5 设备配置、引擎设置、可扩展性配置等 - **构建流程配置**：更新 InstalledEngineBuild.xml 和 InstalledEngineFilters.xml 以支持 HTML5 平台编译和打包 - **自动化工具支持**：集成 HTML5LaunchHelper 和部署脚本 - **插件兼容性适配**：修改 Oodle 压缩相关插件以跳过 HTML5 平台（该平台不支持这些插件） - **版本兼容性处理**：处理 UE4.27.2 到 UE4.26.1 之间的 API 差异和结构变化 ## 技术栈 - **源引擎版本**：Unreal Engine 4.27.2（带 HTML5 ES3 扩展） - **目标引擎版本**：Unreal Engine 4.26.1（官方原版） - **HTML5 工具链**：Emscripten 3.1.50 SDK - **构建系统**：UnrealBuildTool (C#)、AutomationTool (C#) - **平台语言**：C++（运行时）、C#（构建工具） - **第三方库**：zlib、SDL2、PhysX3、Vorbis、Ogg、libPNG、libOpus、ICU 等（均为 Emscripten 编译版本） ## 实现方案 ### 高层策略 采用**分层合并策略**，将 HTML5 平台支持分为三个层次逐步集成： 1. **平台扩展层**：完整复制 HTML5 平台目录（自包含，无依赖） 2. **构建系统层**：修改核心构建工具以识别 HTML5 平台 3. **配置集成层**：更新引擎配置文件和自动化脚本 这种方式的优势是： - 最小化对目标引擎核心代码的侵入 - HTML5 相关代码高度模块化，易于维护 - 如果出现问题，可以快速回滚 - 符合 UE4 的平台扩展架构设计 ### 版本兼容性策略 UE4.27.2 到 4.26.1 的降级需要关注： - **构建工具 API 变化**：检查 UnrealBuildTool 在两个版本间的接口差异 - **配置文件格式**：验证 .ini 和 .xml 配置文件的兼容性 - **插件系统**：确保 .uplugin 描述符在 4.26.1 中有效 - **第三方库 ABI**：HTML5 编译的库可能需要针对 4.26.1 重新编译（如果引擎 ABI 有变化） ### 合并执行细节 **1. 文件复制操作** - 使用完整目录复制而非逐文件复制，保持目录结构完整性 - 保留所有文件权限和时间戳 - 特别注意 .sh 脚本文件的可执行权限 **2. 代码合并操作** - **读取优先**：在修改任何文件前，完整读取目标文件内容 - **冲突检测**：搜索是否存在 HTML5 相关关键字（应该不存在，但需验证） - **精确插入**：对于核心文件（UEBuildTarget.cs 等），使用精确的行级插入 - **智能定位**：在目标文件中查找合适的插入点（通常在同类平台定义附近，如 Android、iOS 等平台定义之后） - **标记清晰**：添加明确的注释标记（`// HTML5 Platform Support - Added for HTML5 ES3 integration`）便于后续维护和识别 - **风格一致**：保持代码风格与目标文件一致（缩进、命名等） - **非破坏性**：只添加新内容，不删除或修改现有代码行 **3. 配置合并操作** - INI 文件使用段落级合并（添加 `[HTML5 DeviceProfile]` 等段落） - XML 文件需要解析 DOM 树，在正确的节点位置插入 - 避免重复条目，合并前先检查是否已存在 **4. 验证和测试** - 合并后运行 `Setup.bat` 确保依赖正确 - 运行 `GenerateProjectFiles.bat` 验证项目生成 - 尝试编译 UnrealBuildTool 和 UnrealHeaderTool - 创建测试项目并尝试打包到 HTML5 平台 ## 架构设计 ### 系统架构 ```mermaid graph TB subgraph "UE4.26.1 引擎（目标）" A[Engine Core] --> B[UnrealBuildTool] A --> C[Config Files] A --> D[AutomationTool] B --> E[Platform Extensions] E --> F[HTML5 Platform<br/>NEW] end subgraph "HTML5 平台扩展" F --> G[Build Toolchain<br/>Emscripten 3.1.50] F --> H[Runtime Modules<br/>HTML5 RHI, Platform] F --> I[Third Party Libs<br/>PhysX, SDL2, etc.] F --> J[Platform Plugins] end subgraph "修改的核心文件" B --> K[UEBuildTarget.cs<br/>添加 HTML5 定义] B --> L[UEBuildModuleCPP.cs<br/>添加模块映射] C --> M[BaseDeviceProfiles.ini<br/>HTML5 配置] D --> N[BuildCommonTools.cs<br/>HTML5LaunchHelper] end style F fill:#90EE90 style K fill:#FFD700 style L fill:#FFD700 style M fill:#FFD700 style N fill:#FFD700 ``` ### 模块划分 **核心模块：** - **HTML5 Platform Extension**（Engine/Platforms/HTML5/）：完全自包含的平台代码 - **Build System Integration**：UnrealBuildTool 中的 HTML5 支持 - **Configuration Layer**：引擎配置文件中的 HTML5 设置 - **Automation Layer**：自动化构建和部署工具 **依赖关系：** - HTML5 Platform Extension 不依赖引擎核心修改（可独立存在） - Build System Integration 依赖 HTML5 Platform Extension 的存在 - Configuration Layer 依赖 Build System Integration - Automation Layer 依赖 Configuration Layer ### 数据流 ``` 用户请求打包 HTML5 项目 ↓ UnrealBuildTool 读取项目配置 ↓ 识别目标平台为 HTML5（通过 UEBuildTarget.cs） ↓ 加载 HTML5SDKInfo.cs 获取工具链信息 ↓ 调用 Emscripten 编译器编译 C++ 代码为 WASM ↓ 链接 HTML5 平台的第三方库 ↓ AutomationTool 打包资源和二进制文件 ↓ 生成 .html、.js、.wasm、.data 文件 ↓ HTML5LaunchHelper 可选地启动本地 Web 服务器测试 ``` ## 实施注意事项 ### 性能考虑 - 文件复制操作涉及约 30,000 个文件，使用批量复制 API 而非逐个文件操作 - 对于大型二进制文件（.a 库文件），使用流式复制避免内存占用过高 - XML 配置文件解析使用 XDocument 而非正则表达式，确保准确性 ### 日志记录 - 记录每个关键步骤的执行状态（复制、修改、验证） - 对于失败的操作，记录详细错误信息和上下文 - 生成合并报告，列出所有修改的文件清单 ### 风险控制 - **在修改任何文件前，先备份 UE4.26.1 引擎的相关文件** - 使用 Git 版本控制跟踪所有修改，便于审查和回滚 - **采用增量式合并**：只添加 HTML5 相关内容，绝不删除或修改现有代码 - **冲突检测**：在每个文件修改前，先读取目标文件，检查是否存在 HTML5 相关内容（应该不存在） - **审慎插入**：在代码/配置插入时，选择安全的插入点，遵循目标文件的现有格式和风格 - 如果遇到无法自动合并的情况（如文件结构差异过大），生成人工审查清单 - **保护现有修改**：不修改目标引擎中与 HTML5 无关的任何代码，确保业务修改不受影响 ### 兼容性检查点 1. **构建系统 API 检查**：验证 UEBuildTarget 和相关类在 4.26.1 中的接口 2. **配置文件格式检查**：确保 INI 和 XML 格式在 4.26.1 中有效 3. **插件描述符检查**：验证 .uplugin 文件的 EngineVersion 字段 4. **第三方库 ABI 检查**：如果需要，使用 4.26.1 的头文件重新编译 HTML5 库 ## 目录结构 ### 合并操作涉及的文件清单 这是一个引擎级别的大规模合并操作，涉及以下文件和目录的创建/修改： ``` UE4.26.1 引擎目录/ ├── Engine/ │ ├── Platforms/ │ │ └── HTML5/ # [NEW] 完整复制整个目录 │ │ ├── Build/ # HTML5 构建工具和 Emscripten SDK（约 28,879 个文件） │ │ │ └── emsdk/emsdk-3.1.50/ # Emscripten 3.1.50 工具链 │ │ ├── Config/ # HTML5 平台配置文件 │ │ │ ├── BaseHTML5DeviceProfiles.ini │ │ │ ├── BaseHTML5Engine.ini │ │ │ ├── BaseHTML5PakFileRules.ini │ │ │ └── HTML5Engine.ini │ │ ├── Source/ # HTML5 平台源代码（361 个文件） │ │ │ ├── Developer/ # HTML5 开发工具模块 │ │ │ │ ├── HTML5PlatformEditor/ # 编辑器集成 │ │ │ │ └── HTML5TargetPlatform/ # 目标平台支持 │ │ │ ├── Programs/ # HTML5 程序和工具 │ │ │ │ ├── UnrealBuildTool/ │ │ │ │ │ └── HTML5SDKInfo.cs # HTML5 SDK 配置和路径信息 │ │ │ │ └── HTML5/ │ │ │ │ └── HTML5LaunchHelper/ # HTML5 启动助手（本地 Web 服务器） │ │ │ ├── Runtime/ # HTML5 运行时模块 │ │ │ │ ├── HTML5/ # HTML5 平台层（ApplicationLifecycle, Platform API） │ │ │ │ ├── HTML5ApplicationCore/ # 应用程序核心（窗口、输入） │ │ │ │ ├── HTML5Audio/ # 音频实现 │ │ │ │ ├── HTML5JS/ # JavaScript 互操作 │ │ │ │ └── OpenGLDrv/ # OpenGL ES3/WebGL 2 渲染器 │ │ │ └── ThirdParty/ # HTML5 编译的第三方库（226 个文件，主要是 .a 静态库） │ │ │ ├── zlib/zlib_HTML5.Build.cs │ │ │ ├── SDL2/SDL2_HTML5.Build.cs │ │ │ ├── PhysX3/ # PhysX 物理引擎 │ │ │ ├── Vorbis/Vorbis_HTML5.Build.cs │ │ │ ├── Ogg/UEOgg_HTML5.Build.cs │ │ │ ├── libPNG/UElibPNG_HTML5.Build.cs │ │ │ ├── libOpus/libOpus_HTML5.build.cs │ │ │ └── ICU/ICU_HTML5.Build.cs # 国际化组件 │ │ ├── Plugins/ # HTML5 平台特定的插件覆盖（28 个 .uplugin 文件） │ │ │ ├── Runtime/ │ │ │ │ ├── ApexDestruction/ApexDestruction_HTML5.uplugin │ │ │ │ ├── HTTPChunkInstaller/HTTPChunkInstaller_HTML5.uplugin │ │ │ │ └── ... │ │ │ ├── Experimental/ │ │ │ │ ├── WebSocketNetworking/WebSocketNetworking_HTML5.uplugin │ │ │ │ └── ... │ │ │ └── VirtualProduction/ │ │ ├── HTML5Setup.sh # Linux/Mac HTML5 SDK 安装脚本 │ │ ├── HTML5Setup2.sh # 备用安装脚本 │ │ └── README.md # HTML5 平台文档 │ │ │ ├── Source/ │ │ └── Programs/ │ │ ├── UnrealBuildTool/ │ │ │ └── Configuration/ │ │ │ ├── UEBuildTarget.cs # [MODIFY] 添加 HTML5 平台定义 │ │ │ │ # 在 ~248 行添加：public static UnrealTargetPlatform HTML5 = FindOrAddByName("HTML5"); │ │ │ └── UEBuildModuleCPP.cs # [MODIFY] 添加 HTML5 模块映射 │ │ │ # 在 ~152 行添加：new KeyValuePair<string, string>("Core", "HTML5MapPakDownloader"), │ │ │ # new KeyValuePair<string, string>("ApplicationCore", "HTML5MapPakDownloader"), │ │ └── AutomationTool/ │ │ ├── Scripts/ │ │ │ └── BuildCommonTools.Automation.cs # [MODIFY] 添加 HTML5LaunchHelper 构建配置 │ │ │ # 在 ~148-159 行添加 HTML5LaunchHelper 编译逻辑（可选，默认注释） │ │ └── AutomationUtils/ │ │ └── DeploymentContext.cs # [MODIFY] 添加 HTML5 部署归档配置 │ │ # 在 ~415-418 行添加 HTML5 资源归档路径处理 │ │ │ ├── Config/ │ │ ├── BaseDeviceProfiles.ini # [MODIFY] 添加 HTML5 设备配置 │ │ │ # 在 ~107 行添加：+DeviceProfileNameAndTypes=HTML5,HTML5 │ │ │ # 在 ~980 行添加：[HTML5 DeviceProfile] 段落 │ │ ├── BaseEditorPerProjectUserSettings.ini # [MODIFY] 添加 HTML5 编辑器设置 │ │ │ # 在 ~216 行添加 HTML5 相关注释和配置 │ │ ├── BaseEngine.ini # [MODIFY] 添加 HTML5 引擎配置 │ │ │ # 添加 HTML5 渲染器、音频、网络等配置 │ │ ├── BaseGame.ini # [MODIFY] 添加 HTML5 游戏配置 │ │ │ # 添加 HTML5 游戏相关设置 │ │ └── BaseScalability.ini # [MODIFY] 添加 HTML5 可扩展性设置 │ │ # 添加 HTML5 性能分级配置 │ │ │ ├── Build/ │ │ ├── InstalledEngineBuild.xml # [MODIFY] 添加 HTML5 构建配置 │ │ │ # 第 49 行添加：<Option Name="WithHTML5" ... Description="Include the HTML5 target platform"/> │ │ │ # 第 408-418 行添加：<Agent Name="Target HTML5"> 编译代理配置 │ │ │ # 添加 HTML5 DDC、安装过滤、依赖等多处配置（约 15 处修改点） │ │ └── InstalledEngineFilters.xml # [MODIFY] 添加 HTML5 文件过滤规则 │ │ # 第 567-581 行添加：<Property Name="CopyHTML5Filter"> 和相关过滤规则 │ │ │ └── Plugins/ │ ├── Compression/ │ │ ├── OodleData/ │ │ │ ├── OodleData.uplugin # [MODIFY] 更新 WhitelistPlatforms，排除 HTML5 │ │ │ └── Source/ │ │ │ └── OodleDataCompressionFormat.Build.cs # [MODIFY] 添加 HTML5 平台跳过逻辑 │ │ │ # 第 53 行添加：bool bSkipLibrarySetup = (Target.Platform == UnrealTargetPlatform.HTML5); │ │ └── OodleNetwork/ │ │ ├── OodleNetwork.uplugin # [MODIFY] 更新 WhitelistPlatforms，排除 HTML5 │ │ └── Source/ │ │ └── OodleNetworkHandlerComponent.Build.cs # [MODIFY] 添加 HTML5 平台跳过逻辑 │ │ # 第 47 行添加：bool bSkipLibrarySetup = (Target.Platform == UnrealTargetPlatform.HTML5); │ └── Developer/ │ └── TextureFormatOodle/ │ ├── TextureFormatOodle.uplugin # [MODIFY] 更新 WhitelistPlatforms，排除 HTML5 │ └── Source/ │ └── TextureFormatOodle.Build.cs # [MODIFY] 添加 HTML5 平台跳过逻辑 │ # 第 59 行添加：bool bSkipLibrarySetup = (Target.Platform == UnrealTargetPlatform.HTML5); ``` ### 文件修改说明 **[NEW] 文件/目录**：完整复制自 UE4.27.2 HTML5 版本 - Engine/Platforms/HTML5/（整个目录，约 58,000 个文件） **[MODIFY] 文件**：需要进行精确的代码/配置合并 - **构建系统**（2 个文件）： - UEBuildTarget.cs：添加 1 行平台定义 - UEBuildModuleCPP.cs：添加 2 行模块映射 - **引擎配置**（5 个文件）： - BaseDeviceProfiles.ini：添加 2 行设备类型 + 1 个配置段落 - BaseEditorPerProjectUserSettings.ini：添加少量编辑器配置 - BaseEngine.ini：添加 HTML5 引擎配置段落 - BaseGame.ini：添加 HTML5 游戏配置 - BaseScalability.ini：添加 HTML5 可扩展性配置 - **构建配置**（2 个文件）： - InstalledEngineBuild.xml：添加约 15 处 HTML5 相关配置节点 - InstalledEngineFilters.xml：添加 HTML5 文件过滤规则 - **自动化工具**（2 个文件）： - BuildCommonTools.Automation.cs：添加 HTML5LaunchHelper 编译逻辑 - DeploymentContext.cs：添加 HTML5 部署路径处理 - **插件适配**（6 个文件）： - 3 个 .uplugin 文件：更新平台白名单 - 3 个 .Build.cs 文件：添加 HTML5 平台检测和跳过逻辑 **总计**：约 58,000 个新增文件 + 17 个修改的核心文件 ## 推荐的代理扩展 ### SubAgent - **code-explorer** - **目的**：在 UE4.26.1 目标引擎中探索和验证待修改文件的结构，确保合并点的准确性 - **预期结果**：获取目标引擎中 UEBuildTarget.cs、配置文件等的准确行号和上下文，生成精确的合并指令
交互3：上面的信息调整一下，UE4.26.1 引擎上已经有其他修改，但没有任何 HTML5 相关代码
CodeBuddy answer
明白了！我需要调整计划，考虑到 UE4.26.1 引擎已有其他修改的情况。让我更新计划以适应这种情况： 更新计划中关于目标引擎状态的描述，反映 UE4.26.1 已有其他修改但无 HTML5 代码的实际情况 plan.md (Modify) +6 -1 View File 更新实施注意事项，强调对现有修改的保护策略 plan.md (Modify) +7 -5 View File 更新产品概述，说明目标引擎的实际状态 plan.md (Modify) +6 -0 View File 更新代码合并操作策略，强调非破坏性插入 plan.md (Modify) +7 -4 View File 完成！我已经更新了计划，关键调整点： 更新的计划要点 1. 目标引擎状态说明 明确 UE4.26.1 基于官方版本但已有其他业务修改 强调目标引擎中完全没有 HTML5 相关代码 这意味着不会有 HTML5 相关的冲突，但需要更谨慎地插入代码 2. 增强的风险控制策略 增量式合并：只添加 HTML5 内容，不删除或修改现有代码 冲突检测：每次修改前先读取文件，验证不存在 HTML5 相关内容 保护现有修改：确保业务修改不受影响 3. 优化的代码合并流程 读取优先：修改前完整读取目标文件 智能定位：在合适的位置（如其他平台定义附近）插入代码 非破坏性：只添加，不删除或修改现有行 清晰标记：添加详细的注释说明 HTML5 相关修改 4. 实施优势 由于目标引擎没有 HTML5 代码，这实际上简化了合并过程： 不会有 HTML5 相关的代码冲突 可以直接插入，无需解决合并冲突 但需要更仔细地选择插入点，避免破坏现有逻辑
现在计划已更新完成。请您： 提供 UE4.26.1 引擎的完整路径（例如：e:/UE426/UnrealEngine） 确认是否要开始执行此计划 我会采用非常谨慎的策略，确保只添加 HTML5 支持，完全不影响您现有的业务修改。
重新得到Plan.md文件
## 用户需求 将当前 UE4.27.2 引擎（包含社区维护的 HTML5 ES3/WebGL 2 平台支持）的完整 HTML5 功能移植到 UE4.26.1 引擎上。 **目标引擎状态说明**： - UE4.26.1 引擎基于官方版本，但已包含其他业务修改 - **重要**：目标引擎中完全没有任何 HTML5 相关代码或配置 - 需要采用非破坏性合并策略，避免影响现有修改 ## 产品概述 这是一个引擎级别的平台扩展迁移任务。Epic Games 在 UE4.24 后停止了官方 HTML5 平台支持，但社区通过 SpeculativeCoder 项目为 UE4.27 维护了基于 Emscripten 3.1.50 的 HTML5 ES3 (WebGL 2) 平台支持。本任务需要将这套完整的平台扩展向下移植到 UE4.26.1 版本。 **目标引擎特点**： - 基于 UE4.26.1 官方版本 - 已包含其他业务相关的代码修改 - **无任何 HTML5 相关代码**（这简化了冲突检测，但需要谨慎插入） - 需要保证 HTML5 集成不影响现有功能 ## 核心功能 - **完整的 HTML5 平台扩展**：复制整个 Engine/Platforms/HTML5 目录，包含构建工具链、运行时代码、第三方库和平台插件 - **构建系统集成**：修改 UnrealBuildTool 以识别和支持 HTML5 作为目标平台 - **引擎配置更新**：添加 HTML5 设备配置、引擎设置、可扩展性配置等 - **构建流程配置**：更新 InstalledEngineBuild.xml 和 InstalledEngineFilters.xml 以支持 HTML5 平台编译和打包 - **自动化工具支持**：集成 HTML5LaunchHelper 和部署脚本 - **插件兼容性适配**：修改 Oodle 压缩相关插件以跳过 HTML5 平台（该平台不支持这些插件） - **版本兼容性处理**：处理 UE4.27.2 到 UE4.26.1 之间的 API 差异和结构变化 ## 技术栈 - **源引擎版本**：Unreal Engine 4.27.2（带 HTML5 ES3 扩展） - **目标引擎版本**：Unreal Engine 4.26.1（官方原版） - **HTML5 工具链**：Emscripten 3.1.50 SDK - **构建系统**：UnrealBuildTool (C#)、AutomationTool (C#) - **平台语言**：C++（运行时）、C#（构建工具） - **第三方库**：zlib、SDL2、PhysX3、Vorbis、Ogg、libPNG、libOpus、ICU 等（均为 Emscripten 编译版本） ## 实现方案 ### 高层策略 采用**分层合并策略**，将 HTML5 平台支持分为三个层次逐步集成： 1. **平台扩展层**：完整复制 HTML5 平台目录（自包含，无依赖） 2. **构建系统层**：修改核心构建工具以识别 HTML5 平台 3. **配置集成层**：更新引擎配置文件和自动化脚本 这种方式的优势是： - 最小化对目标引擎核心代码的侵入 - HTML5 相关代码高度模块化，易于维护 - 如果出现问题，可以快速回滚 - 符合 UE4 的平台扩展架构设计 ### 版本兼容性策略 UE4.27.2 到 4.26.1 的降级需要关注： - **构建工具 API 变化**：检查 UnrealBuildTool 在两个版本间的接口差异 - **配置文件格式**：验证 .ini 和 .xml 配置文件的兼容性 - **插件系统**：确保 .uplugin 描述符在 4.26.1 中有效 - **第三方库 ABI**：HTML5 编译的库可能需要针对 4.26.1 重新编译（如果引擎 ABI 有变化） ### 合并执行细节 **1. 文件复制操作** - 使用完整目录复制而非逐文件复制，保持目录结构完整性 - 保留所有文件权限和时间戳 - 特别注意 .sh 脚本文件的可执行权限 **2. 代码合并操作** - **读取优先**：在修改任何文件前，完整读取目标文件内容 - **冲突检测**：搜索是否存在 HTML5 相关关键字（应该不存在，但需验证） - **精确插入**：对于核心文件（UEBuildTarget.cs 等），使用精确的行级插入 - **智能定位**：在目标文件中查找合适的插入点（通常在同类平台定义附近，如 Android、iOS 等平台定义之后） - **标记清晰**：添加明确的注释标记（`// HTML5 Platform Support - Added for HTML5 ES3 integration`）便于后续维护和识别 - **风格一致**：保持代码风格与目标文件一致（缩进、命名等） - **非破坏性**：只添加新内容，不删除或修改现有代码行 **3. 配置合并操作** - INI 文件使用段落级合并（添加 `[HTML5 DeviceProfile]` 等段落） - XML 文件需要解析 DOM 树，在正确的节点位置插入 - 避免重复条目，合并前先检查是否已存在 **4. 验证和测试** - 合并后运行 `Setup.bat` 确保依赖正确 - 运行 `GenerateProjectFiles.bat` 验证项目生成 - 尝试编译 UnrealBuildTool 和 UnrealHeaderTool - 创建测试项目并尝试打包到 HTML5 平台 ## 架构设计 ### 系统架构 ```mermaid graph TB subgraph "UE4.26.1 引擎（目标）" A[Engine Core] --> B[UnrealBuildTool] A --> C[Config Files] A --> D[AutomationTool] B --> E[Platform Extensions] E --> F[HTML5 Platform<br/>NEW] end subgraph "HTML5 平台扩展" F --> G[Build Toolchain<br/>Emscripten 3.1.50] F --> H[Runtime Modules<br/>HTML5 RHI, Platform] F --> I[Third Party Libs<br/>PhysX, SDL2, etc.] F --> J[Platform Plugins] end subgraph "修改的核心文件" B --> K[UEBuildTarget.cs<br/>添加 HTML5 定义] B --> L[UEBuildModuleCPP.cs<br/>添加模块映射] C --> M[BaseDeviceProfiles.ini<br/>HTML5 配置] D --> N[BuildCommonTools.cs<br/>HTML5LaunchHelper] end style F fill:#90EE90 style K fill:#FFD700 style L fill:#FFD700 style M fill:#FFD700 style N fill:#FFD700 ``` ### 模块划分 **核心模块：** - **HTML5 Platform Extension**（Engine/Platforms/HTML5/）：完全自包含的平台代码 - **Build System Integration**：UnrealBuildTool 中的 HTML5 支持 - **Configuration Layer**：引擎配置文件中的 HTML5 设置 - **Automation Layer**：自动化构建和部署工具 **依赖关系：** - HTML5 Platform Extension 不依赖引擎核心修改（可独立存在） - Build System Integration 依赖 HTML5 Platform Extension 的存在 - Configuration Layer 依赖 Build System Integration - Automation Layer 依赖 Configuration Layer ### 数据流 ``` 用户请求打包 HTML5 项目 ↓ UnrealBuildTool 读取项目配置 ↓ 识别目标平台为 HTML5（通过 UEBuildTarget.cs） ↓ 加载 HTML5SDKInfo.cs 获取工具链信息 ↓ 调用 Emscripten 编译器编译 C++ 代码为 WASM ↓ 链接 HTML5 平台的第三方库 ↓ AutomationTool 打包资源和二进制文件 ↓ 生成 .html、.js、.wasm、.data 文件 ↓ HTML5LaunchHelper 可选地启动本地 Web 服务器测试 ``` ## 实施注意事项 ### 性能考虑 - 文件复制操作涉及约 30,000 个文件，使用批量复制 API 而非逐个文件操作 - 对于大型二进制文件（.a 库文件），使用流式复制避免内存占用过高 - XML 配置文件解析使用 XDocument 而非正则表达式，确保准确性 ### 日志记录 - 记录每个关键步骤的执行状态（复制、修改、验证） - 对于失败的操作，记录详细错误信息和上下文 - 生成合并报告，列出所有修改的文件清单 ### 风险控制 - **在修改任何文件前，先备份 UE4.26.1 引擎的相关文件** - 使用 Git 版本控制跟踪所有修改，便于审查和回滚 - **采用增量式合并**：只添加 HTML5 相关内容，绝不删除或修改现有代码 - **冲突检测**：在每个文件修改前，先读取目标文件，检查是否存在 HTML5 相关内容（应该不存在） - **审慎插入**：在代码/配置插入时，选择安全的插入点，遵循目标文件的现有格式和风格 - 如果遇到无法自动合并的情况（如文件结构差异过大），生成人工审查清单 - **保护现有修改**：不修改目标引擎中与 HTML5 无关的任何代码，确保业务修改不受影响 ### 兼容性检查点 1. **构建系统 API 检查**：验证 UEBuildTarget 和相关类在 4.26.1 中的接口 2. **配置文件格式检查**：确保 INI 和 XML 格式在 4.26.1 中有效 3. **插件描述符检查**：验证 .uplugin 文件的 EngineVersion 字段 4. **第三方库 ABI 检查**：如果需要，使用 4.26.1 的头文件重新编译 HTML5 库 ## 目录结构 ### 合并操作涉及的文件清单 这是一个引擎级别的大规模合并操作，涉及以下文件和目录的创建/修改： ``` UE4.26.1 引擎目录/ ├── Engine/ │ ├── Platforms/ │ │ └── HTML5/ # [NEW] 完整复制整个目录 │ │ ├── Build/ # HTML5 构建工具和 Emscripten SDK（约 28,879 个文件） │ │ │ └── emsdk/emsdk-3.1.50/ # Emscripten 3.1.50 工具链 │ │ ├── Config/ # HTML5 平台配置文件 │ │ │ ├── BaseHTML5DeviceProfiles.ini │ │ │ ├── BaseHTML5Engine.ini │ │ │ ├── BaseHTML5PakFileRules.ini │ │ │ └── HTML5Engine.ini │ │ ├── Source/ # HTML5 平台源代码（361 个文件） │ │ │ ├── Developer/ # HTML5 开发工具模块 │ │ │ │ ├── HTML5PlatformEditor/ # 编辑器集成 │ │ │ │ └── HTML5TargetPlatform/ # 目标平台支持 │ │ │ ├── Programs/ # HTML5 程序和工具 │ │ │ │ ├── UnrealBuildTool/ │ │ │ │ │ └── HTML5SDKInfo.cs # HTML5 SDK 配置和路径信息 │ │ │ │ └── HTML5/ │ │ │ │ └── HTML5LaunchHelper/ # HTML5 启动助手（本地 Web 服务器） │ │ │ ├── Runtime/ # HTML5 运行时模块 │ │ │ │ ├── HTML5/ # HTML5 平台层（ApplicationLifecycle, Platform API） │ │ │ │ ├── HTML5ApplicationCore/ # 应用程序核心（窗口、输入） │ │ │ │ ├── HTML5Audio/ # 音频实现 │ │ │ │ ├── HTML5JS/ # JavaScript 互操作 │ │ │ │ └── OpenGLDrv/ # OpenGL ES3/WebGL 2 渲染器 │ │ │ └── ThirdParty/ # HTML5 编译的第三方库（226 个文件，主要是 .a 静态库） │ │ │ ├── zlib/zlib_HTML5.Build.cs │ │ │ ├── SDL2/SDL2_HTML5.Build.cs │ │ │ ├── PhysX3/ # PhysX 物理引擎 │ │ │ ├── Vorbis/Vorbis_HTML5.Build.cs │ │ │ ├── Ogg/UEOgg_HTML5.Build.cs │ │ │ ├── libPNG/UElibPNG_HTML5.Build.cs │ │ │ ├── libOpus/libOpus_HTML5.build.cs │ │ │ └── ICU/ICU_HTML5.Build.cs # 国际化组件 │ │ ├── Plugins/ # HTML5 平台特定的插件覆盖（28 个 .uplugin 文件） │ │ │ ├── Runtime/ │ │ │ │ ├── ApexDestruction/ApexDestruction_HTML5.uplugin │ │ │ │ ├── HTTPChunkInstaller/HTTPChunkInstaller_HTML5.uplugin │ │ │ │ └── ... │ │ │ ├── Experimental/ │ │ │ │ ├── WebSocketNetworking/WebSocketNetworking_HTML5.uplugin │ │ │ │ └── ... │ │ │ └── VirtualProduction/ │ │ ├── HTML5Setup.sh # Linux/Mac HTML5 SDK 安装脚本 │ │ ├── HTML5Setup2.sh # 备用安装脚本 │ │ └── README.md # HTML5 平台文档 │ │ │ ├── Source/ │ │ └── Programs/ │ │ ├── UnrealBuildTool/ │ │ │ └── Configuration/ │ │ │ ├── UEBuildTarget.cs # [MODIFY] 添加 HTML5 平台定义 │ │ │ │ # 在 ~248 行添加：public static UnrealTargetPlatform HTML5 = FindOrAddByName("HTML5"); │ │ │ └── UEBuildModuleCPP.cs # [MODIFY] 添加 HTML5 模块映射 │ │ │ # 在 ~152 行添加：new KeyValuePair<string, string>("Core", "HTML5MapPakDownloader"), │ │ │ # new KeyValuePair<string, string>("ApplicationCore", "HTML5MapPakDownloader"), │ │ └── AutomationTool/ │ │ ├── Scripts/ │ │ │ └── BuildCommonTools.Automation.cs # [MODIFY] 添加 HTML5LaunchHelper 构建配置 │ │ │ # 在 ~148-159 行添加 HTML5LaunchHelper 编译逻辑（可选，默认注释） │ │ └── AutomationUtils/ │ │ └── DeploymentContext.cs # [MODIFY] 添加 HTML5 部署归档配置 │ │ # 在 ~415-418 行添加 HTML5 资源归档路径处理 │ │ │ ├── Config/ │ │ ├── BaseDeviceProfiles.ini # [MODIFY] 添加 HTML5 设备配置 │ │ │ # 在 ~107 行添加：+DeviceProfileNameAndTypes=HTML5,HTML5 │ │ │ # 在 ~980 行添加：[HTML5 DeviceProfile] 段落 │ │ ├── BaseEditorPerProjectUserSettings.ini # [MODIFY] 添加 HTML5 编辑器设置 │ │ │ # 在 ~216 行添加 HTML5 相关注释和配置 │ │ ├── BaseEngine.ini # [MODIFY] 添加 HTML5 引擎配置 │ │ │ # 添加 HTML5 渲染器、音频、网络等配置 │ │ ├── BaseGame.ini # [MODIFY] 添加 HTML5 游戏配置 │ │ │ # 添加 HTML5 游戏相关设置 │ │ └── BaseScalability.ini # [MODIFY] 添加 HTML5 可扩展性设置 │ │ # 添加 HTML5 性能分级配置 │ │ │ ├── Build/ │ │ ├── InstalledEngineBuild.xml # [MODIFY] 添加 HTML5 构建配置 │ │ │ # 第 49 行添加：<Option Name="WithHTML5" ... Description="Include the HTML5 target platform"/> │ │ │ # 第 408-418 行添加：<Agent Name="Target HTML5"> 编译代理配置 │ │ │ # 添加 HTML5 DDC、安装过滤、依赖等多处配置（约 15 处修改点） │ │ └── InstalledEngineFilters.xml # [MODIFY] 添加 HTML5 文件过滤规则 │ │ # 第 567-581 行添加：<Property Name="CopyHTML5Filter"> 和相关过滤规则 │ │ │ └── Plugins/ │ ├── Compression/ │ │ ├── OodleData/ │ │ │ ├── OodleData.uplugin # [MODIFY] 更新 WhitelistPlatforms，排除 HTML5 │ │ │ └── Source/ │ │ │ └── OodleDataCompressionFormat.Build.cs # [MODIFY] 添加 HTML5 平台跳过逻辑 │ │ │ # 第 53 行添加：bool bSkipLibrarySetup = (Target.Platform == UnrealTargetPlatform.HTML5); │ │ └── OodleNetwork/ │ │ ├── OodleNetwork.uplugin # [MODIFY] 更新 WhitelistPlatforms，排除 HTML5 │ │ └── Source/ │ │ └── OodleNetworkHandlerComponent.Build.cs # [MODIFY] 添加 HTML5 平台跳过逻辑 │ │ # 第 47 行添加：bool bSkipLibrarySetup = (Target.Platform == UnrealTargetPlatform.HTML5); │ └── Developer/ │ └── TextureFormatOodle/ │ ├── TextureFormatOodle.uplugin # [MODIFY] 更新 WhitelistPlatforms，排除 HTML5 │ └── Source/ │ └── TextureFormatOodle.Build.cs # [MODIFY] 添加 HTML5 平台跳过逻辑 │ # 第 59 行添加：bool bSkipLibrarySetup = (Target.Platform == UnrealTargetPlatform.HTML5); ``` ### 文件修改说明 **[NEW] 文件/目录**：完整复制自 UE4.27.2 HTML5 版本 - Engine/Platforms/HTML5/（整个目录，约 58,000 个文件） **[MODIFY] 文件**：需要进行精确的代码/配置合并 - **构建系统**（2 个文件）： - UEBuildTarget.cs：添加 1 行平台定义 - UEBuildModuleCPP.cs：添加 2 行模块映射 - **引擎配置**（5 个文件）： - BaseDeviceProfiles.ini：添加 2 行设备类型 + 1 个配置段落 - BaseEditorPerProjectUserSettings.ini：添加少量编辑器配置 - BaseEngine.ini：添加 HTML5 引擎配置段落 - BaseGame.ini：添加 HTML5 游戏配置 - BaseScalability.ini：添加 HTML5 可扩展性配置 - **构建配置**（2 个文件）： - InstalledEngineBuild.xml：添加约 15 处 HTML5 相关配置节点 - InstalledEngineFilters.xml：添加 HTML5 文件过滤规则 - **自动化工具**（2 个文件）： - BuildCommonTools.Automation.cs：添加 HTML5LaunchHelper 编译逻辑 - DeploymentContext.cs：添加 HTML5 部署路径处理 - **插件适配**（6 个文件）： - 3 个 .uplugin 文件：更新平台白名单 - 3 个 .Build.cs 文件：添加 HTML5 平台检测和跳过逻辑 **总计**：约 58,000 个新增文件 + 17 个修改的核心文件 ## 推荐的代理扩展 ### SubAgent - **code-explorer** - **目的**：在 UE4.26.1 目标引擎中探索和验证待修改文件的结构，确保合并点的准确性 - **预期结果**：获取目标引擎中 UEBuildTarget.cs、配置文件等的准确行号和上下文，生成精确的合并指令
交互4：引擎完整路径在H:\svn\UnrealEngine，开始执行此计划
CodeBuddy answer
显示执行的任务和修改的文件
浙公网安备 33010602011771号