# phaser4-wechat-adaptation

**Repository Path**: dudududududu/phaser4-wechat-adaptation

## Basic Information

- **Project Name**: phaser4-wechat-adaptation
- **Description**: phaser4 微信小游戏适配，没有定义所有微信接口（如有需要自行添加）。runtime-template 分支是基本的模板；demo-NeonArena 分支是 demo 小游戏。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Phaser 4 + 微信小游戏 Compatibility Test Suite v0.8.2

本版本基于 v0.8.1 将 Custom Font 测试收敛为“代码包本地 TTF”单一路径，暂时完全绕开远程域名、downloadFile 与持久缓存变量；同时保留 BitmapText、RenderTexture、HiDPI、Day5 等测试。

## 菜单测试项

启动顺序：

```text
AssetLoaderScene
  ↓
MenuScene
```

菜单可进入：

- **HiDPI / Render Scale**：1x / 1.5x / 2x / Device DPR。
- **Fill-rate / Overdraw**：5 / 10 / 20 / 40 层全屏 alpha overdraw。
- **Day 5 / Remote + Stress**：远程资源持久缓存 + 250 / 1000 / 3000 Sprite benchmark。
- **Day 3+4 / Physics + Audio**：Arcade Physics、hide/show、BGM / SFX。
- **System Font / Text**：Raw Canvas2D + Phaser Text 系统字体，iOS 已通过。
- **Custom Font**：`wx.loadFont()` / `FontFace` 自定义字体加载与 Phaser Text 动态更新。
- **BitmapText**：本地 PNG glyph atlas + `RetroFont.Parse` + BitmapText，中英文和动态更新。
- **RenderTexture**：离屏 RenderTexture、`saveTexture()`、clone、`snapshotPixel()` RGB 验证。

Day 2 packaged asset loader 仍作为启动预加载阶段自动执行。


## v0.8.2 / v0.8.1 修复

- `RetroFont.Parse` 使用 Phaser 4.2.1 类型要求的 `"offset.x" / "offset.y" / "spacing.x" / "spacing.y"`。
- WeChat RemoteAssetService 不再执行 `http://tmp -> fs.copyFile -> USER_DATA_PATH`；改为 `wx.downloadFile({ filePath })` 直接下载到持久缓存路径。
- `WechatDownloadFileResult` 兼容 `filePath` 与可选 `tempFilePath`。

## Custom Font 测试

v0.8.2 **不包含任何 TTF / OTF / WOFF 字体二进制**。构建前请放入一份你有权使用的 TTF：

```text
public/assets/custom-font/custom-font.ttf
```

然后执行：

```bash
npm run typecheck
npm run build:wechat:dev
```

构建脚本会先检查该文件是否存在；缺失时会直接给出明确错误。成功构建后必须能看到：

```text
dist-wechat/assets/custom-font/custom-font.ttf
```

`CustomFontTestScene` 现在只测试：

```text
package TTF
→ wx.loadFont("assets/custom-font/custom-font.ttf")
→ returned family
→ Phaser Text
→ dynamic setText()
```

不会再尝试远程字体，因此无需微信后台合法域名配置。

## BitmapText 测试

BitmapText 测试完全离线，不需要字体文件或 DOMParser：

```text
public/assets/bitmap-font/bitmap-font-test.png
  ↓
Phaser.GameObjects.RetroFont.Parse
  ↓
cache.bitmapFont
  ↓
BitmapText
```

覆盖：英文、数字、中文、多行、动态 `setText()`、HiDPI 下 bounds 诊断。

## RenderTexture 测试

这是 HiDPI 方案的重要边界测试。主 Canvas backing 可以按 renderScale 放大，但 Phaser 的离屏 framebuffer 不应被主 framebuffer viewport/scissor patch 误放大。

Scene 创建固定逻辑尺寸 RenderTexture，绘制三个色块，然后：

- 显示 live RenderTexture；
- `saveTexture()` 后再显示一个 clone；
- 对 green / blue / orange 三个逻辑像素位置执行 `snapshotPixel()`；
- 三点 RGB 都匹配才标记 PASS。

建议分别在 HiDPI Scene 切到 **1x / 2x / 3x** 后回菜单运行 RenderTexture。若 1x PASS 而 2x/3x FAIL，优先检查默认 framebuffer viewport/scissor scale patch 是否错误作用到了 offscreen framebuffer。

## iOS 真机兼容基础

v0.7.2 已修复 iOS Phaser bundle evaluation 时的 `getBoundingClientRect` 黑屏：运行时会补齐 `document.body`、`document.documentElement`、`document.head`、主 Canvas 和合成节点的基础 DOM geometry API。

菜单标签继续使用预渲染 PNG，因此即使字体测试失败，也不会影响导航入口。

## 运行

```bash
npm install
npm run typecheck
npm run build:wechat:dev
```

将 `dist-wechat/` 导入微信开发者工具后 Preview / 真机测试。

## v0.8.1 修复与测试文件

```text
src/game/fonts/custom-font-service.ts
src/platform/wechat/wechat-custom-font-service.ts
src/platform/web/browser-custom-font-service.ts
src/game/assets/advanced-test-assets.ts
src/game/scenes/CustomFontTestScene.ts
src/game/scenes/BitmapTextTestScene.ts
src/game/scenes/RenderTextureTestScene.ts
public/assets/custom-font/custom-font-config.json
public/assets/bitmap-font/bitmap-font-test.png
public/assets/menu/menu-custom-font.png
public/assets/menu/menu-bitmap-text.png
public/assets/menu/menu-render-texture.png
```