minigame-tuanjie-transform-sdk/Editor/PCHighPerformance

PC 高性能小游戏开发指南

目录

• 架构概览
• 两条接入路径
• 文件结构
• 宏开关机制
• 初始化机制
• 构建流程
• 通信协议
• 问题排查
• 调试工具
• 更新日志

---

架构概览

C# (Unity)  ←→  direct_applet_sdk.dll  ←→  微信内核  ←→  基础库

模块	职责
WXPCHPInitScript	MonoBehaviour，运行时核心——DLL P/Invoke、消息收发、回调调度
WXPCHighPerformanceManager	门面类，提供类似 wx.xxx() 的上层 API
PCHPBuildPreProcessor	构建预处理器，自动管理宏定义和场景注入（兜底）
WXPCHPBuildHelper	路径A 构建配置助手（转换工具链集成）
WXPCHPWindow	Editor 窗口 UI + 宏开关菜单
WXPCSettingHelper	路径B 构建设置管理（独立窗口）
WXApkgPacker	wxapkg 打包工具

---

两条接入路径

路径 A: "转换工具链"  ← 走 WX-WASM-SDK 转换面板，项目本身是小游戏工程
路径 B: "原生接入"    ← 项目本身就是 Standalone，只想接 PC 高性能能力

维度	路径 A（转换工具链）	路径 B（原生接入）
宏定义	转换工具/PreProcessor 自动添加 WX_PCHP_ENABLED	开发者通过菜单一键开启，或手动添加
Build Target	WebGL/WeixinMiniGame → 临时切 Standalone → 切回	始终 Standalone，不切换
初始化方式	RuntimeInitializeOnLoadMethod 自动 + PreProcessor 兜底注入	RuntimeInitializeOnLoadMethod 自动，或开发者手动挂载
Editor 入口	"微信小游戏 → 生成并转换" 面板	"微信小游戏 → 转换PC高性能模式" 独立窗口
构建后	RestoreToMiniGamePlatform() 恢复平台	不恢复，保持 Standalone
多平台兼容	WX_PCHP_ENABLED 不在 WebGL 下定义，无干扰	WX_PCHP_ENABLED 只在 Standalone 下定义，Android/iOS 不受影响

---

文件结构

WX-WASM-SDK-V2/
├── Editor/PCHighPerformance/
│   ├── PCHPBuildPreProcessor.cs   # 构建预处理器（宏管理 + 兜底注入）
│   ├── WXPCHPBuildHelper.cs       # 路径A 构建配置助手
│   ├── WXPCHPWindow.cs            # 编辑器窗口 + WX_PCHP_ENABLED 宏开关菜单
│   ├── WXPCSettingHelper.cs       # 路径B 构建设置管理
│   └── WXApkgPacker.cs            # wxapkg 打包
└── Runtime/
    └── WXPCHPInitScript.cs        # SDK 运行时脚本（整文件 #if WX_PCHP_ENABLED）

---

宏开关机制

WX_PCHP_ENABLED — 总开关

作用：控制 WXPCHPInitScript.cs 及 WXPCHighPerformanceManager 是否参与编译。

未定义时：Runtime 脚本整文件跳过编译，Android/iOS/WebGL 等平台完全无干扰。

定义方式（三选一）：

方式	适用场景
Editor 菜单：微信小游戏 → PC高性能模式宏开关	路径B，一键切换
PCHPBuildPreProcessor 自动添加	路径A/B，Standalone 构建时自动
手动：Player Settings → Scripting Define Symbols 添加 WX_PCHP_ENABLED	任何路径

UNITY_STANDALONE_WIN — 平台细分

user32.dll（GetActiveWindow、MessageBox）的 P/Invoke 声明被 #if UNITY_STANDALONE_WIN 包裹，macOS 构建时不会引入。

---

初始化机制

三级策略（优先级从高到低）

优先级	方式	说明
1	开发者手动挂载	场景中已存在 WXPCHPInitScript 组件 → AutoInitialize 检测到 Instance != null，跳过
2	RuntimeInitializeOnLoadMethod	场景加载后自动创建 GameObject 并挂载，零侵入不修改任何场景文件
3	构建时注入（兜底）	PCHPBuildPreProcessor 在路径A 转换工具链模式下注入首场景

运行时初始化流程

WXPCHPInitScript.Initialize() 在 Awake 时触发，5 步串行：

InitEmbeddedGameSDK()     → 加载 DLL，初始化底层 SDK
       ↓
RegisterAsyncMsgHandler() → 注册 C# 静态回调到 DLL（防 GC 回收）
       ↓
EstablishConnection()     → 建立 Mojo IPC 连接
       ↓
GetActiveWindow()         → Windows: 获取 HWND / macOS: IntPtr.Zero（DLL 内部处理）
       ↓
InitGameWindow(hwnd)      → 把窗口句柄传给内核，绑定渲染窗口

任何一步失败整个链路中断，Windows 平台会弹 MessageBox 提示具体步骤。

---

构建流程

PCHPBuildPreProcessor（构建预处理器）

触发条件：任何 Standalone (Windows/macOS) 构建

流程：

构建开始
  ↓
① 确保 WX_PCHP_ENABLED 宏已添加到 Standalone ScriptingDefineSymbols
  ↓
② 检查 WXPCHPInitScript 类型是否存在
  ├─ 未找到 → 跳过（可能需要宏生效后重新编译）
  └─ 找到 → 继续
  ↓
③ 检查首场景是否已有 WXPCHPInitScript 组件
  ├─ 已有 → 跳过注入（开发者手动挂载的）
  └─ 没有 → 检查是否为转换工具链模式
       ├─ 是 → 兜底注入到首场景
       └─ 否 → 依赖 RuntimeInitializeOnLoadMethod 自动初始化

路径A — 转换工具链构建（WXPCHPBuildHelper）

由 WXConvertCore 在小游戏构建完成后调用，额外步骤：

• 构建产物打包为 wxapkg 格式
• 构建完成后调用 RestoreToMiniGamePlatform() 恢复到 WebGL/WeixinMiniGame

路径B — 独立窗口构建（WXPCSettingHelper）

通过 微信小游戏 → 转换PC高性能模式 菜单打开，特点：

• 自动确保 WX_PCHP_ENABLED 宏已定义
• 不强制注入场景（依赖 RuntimeInitializeOnLoadMethod）
• 构建完成后 不恢复平台，保持 Standalone

---

通信协议

消息方向

type	方向	用途
"request"	C# → 内核	调用 wx API（showToast、login 等）
"event_register"	C# → 内核	订阅事件（onShow、onHide 等）
"event_unregister"	C# → 内核	取消事件订阅
"response"	内核 → C#	API 回调（success / fail / complete）
"event"	内核 → C#	事件推送

线程模型

DLL 回调在非主线程，通过 ConcurrentQueue 转到主线程 Update 中处理：

DLL 线程: HandleAsyncMessage → 反序列化 → _messageQueue.Enqueue()
主线程:   Update → ProcessMessageQueue → ProcessResponse → 触发回调

---

问题排查

快速检查清单

• Player Settings → Scripting Define Symbols 包含 WX_PCHP_ENABLED
• Build Settings 中有至少一个启用的场景
• 导出目录包含 .exe 和 direct_applet_sdk.dll（同级）
• 运行 .exe 后 Player.log 有 [WXPCHPInitScript] 日志

问题 1：Android/iOS 构建时报 DLL 相关编译错误

原因：WX_PCHP_ENABLED 宏被错误添加到了非 Standalone 平台

解决：在 Player Settings → Scripting Define Symbols 中，确保只有 Standalone 平台定义了 WX_PCHP_ENABLED。或通过菜单 微信小游戏 → PC高性能模式宏开关 关闭。

问题 2：DLL 加载失败（~90% 的运行时问题）

症状：运行 .exe 后没有弹窗，日志报 DllNotFoundException

验证导出目录结构：

导出路径/
├── YourGame.exe
├── direct_applet_sdk.dll  ← 必须存在
└── YourGame_Data/

解决：确保 direct_applet_sdk.dll 与 .exe 同级

问题 3：GetActiveWindow 返回空句柄

原因：窗口尚未创建时调用了初始化

解决：检查 Unity Player Settings，确保非后台启动；或考虑延迟初始化

注意：macOS 平台会传 IntPtr.Zero，由 DLL 内部获取窗口句柄，这是正常行为。

问题 4：宏添加后代码未生效

原因：修改 ScriptingDefineSymbols 后需要 Unity 重新编译脚本

解决：等待 Unity 编译完成（底部进度条），或手动 Assets → Reimport All

错误代码速查

错误信息	原因	解决
DllNotFoundException	DLL 不在 .exe 同级目录	复制 DLL 到 .exe 目录
EntryPointNotFoundException	DLL 版本不匹配	更新 direct_applet_sdk.dll
找不到 WXPCHPInitScript 类型	SDK 未安装或宏未生效	重新导入 SDK 或等待编译
GetActiveWindow 返回空句柄	窗口未创建（仅 Windows）	延迟初始化或检查 Player Settings
WXPCHPInitScript 必须在 Runtime 程序集	脚本放在了 Editor 目录	移到 Runtime 目录

---

调试工具

日志查看

Player.log 位置：

• Windows: %APPDATA%\..\LocalLow\<CompanyName>\<ProductName>\Player.log
• macOS: ~/Library/Logs/<CompanyName>/<ProductName>/Player.log

搜索关键字：[WXPCHPInitScript]、DllNotFoundException、InitEmbeddedGameSDK

正常日志示例：

[WXPCHPInitScript] 通过 RuntimeInitializeOnLoadMethod 自动创建
[WXPCHPInitScript] ========== Awake 被调用 ==========
[WXPCHPInitScript] ========== 开始初始化 ==========
[WXPCHPInitScript] Step 1: 调用 InitEmbeddedGameSDK
...
[WXPCHPInitScript] ========== 初始化完成 ==========

Editor 菜单

菜单项	功能
微信小游戏 → 转换PC高性能模式	打开路径B独立构建窗口
微信小游戏 → PC高性能模式宏开关	一键启用/禁用 WX_PCHP_ENABLED 宏

---

更新日志

v2.0.0 (2026-04-07)

• 双路径架构：支持"转换工具链"和"原生接入"两条路径
• WX_PCHP_ENABLED 宏：总开关，整文件条件编译，Android/iOS 零干扰
• RuntimeInitializeOnLoadMethod：零侵入自动初始化，不再强制修改场景
• user32.dll 平台隔离：#if UNITY_STANDALONE_WIN 包裹，macOS 兼容
• RestoreToMiniGamePlatform 解耦：从 BuildPCHighPerformance 的 finally 移到调用方
• Editor 宏开关菜单：微信小游戏 → PC高性能模式宏开关

v1.1.0 (2026-03-02)

• 重命名 EmbeddedAppletSDK → WXPCHPInitScript
• 迁移脚本到 Runtime 目录
• 添加 WeChatWASM 命名空间

v1.0.0 (2026-03-02)

• 实现自动注入 EmbeddedAppletSDK GameObject
• 智能检测并复制模板脚本
• 兼容 Windows 和 macOS 构建