Awesome

platformize

一个支持把 js 库中浏览器 api 改用定制 polyfill 的构建插件, 并提供特定库的定制适配, 如:

• three@0.133.0
• oasis-engine@0.8.3 | oasis-engine@0.6.3
• galacean@1.0.0-beta.14
• playcanvas@1.50.0
• pixi@6.2.1

欢迎各位提 PR, 分享小程序的适配经验, 把这些经验集中起来, 让小程序的 3D 开发更便利, 当然适配到 ReactNative, 快应用, Lynx 等其他 Hybrid 也是同理, 编写 Web API 对应的 polyfill+library 的一些 patch 即可

适配情况

真机[✅/❌] 模拟器[✅/❌]

• platformize 通用适配
• platformize-three 专门适配
• platformize-galacean 专门适配
• platformize-oasis 专门适配
• platformize-playcanvas 专门适配
• platformize-pixi 专门适配

特点

0. 使用方式与 web 完全一致, 更方便跨端代码复用
1. 支持运行时反馈式 treeshaking, oasis-wechat-game小程序包大小从545kb > 290kb

• 小程序均不支持动态加载 JS, 所以Scrpit或WasmModule 均不支持网络加载

微信小程序限制

• 纹理图片分辨率不能大于 2048, 下载 ArrayBuffer 大小不能大于 10MB
• WebGL 扩展 OES_vertex_array_object 有问题, 需手动禁用
• 基础库版本2.24.1以上有texSubImage2Dapi 报错问题, 会导致 oasis 加载图片为黑色(已 patch 修复) #10

淘宝小程序限制

• 网络资源有严格的限制, 白名单需工单要内部的申请地址, 最长 3 个月, 过期失效, 建议走云存储
• WebGL 扩展 EXT_blend_minmax 返回 undefined, 需手动禁用

字节小程序限制

• WebGL 不开放给个人开发者

截图

构建特性

1. 定制版 plugin-inject 实现全局 API 的替换或者局部 所引入 module 的 overwrite
2. plugin 需自带 manualChunks 配置, 用于缓解淘宝小程序几分钟的构建耗时
3. 提供两种使用方式, 一种是便捷版, 少配置, 一种是骨头版, 允许用户自行组装
4. 可 overwrite polyfill platformzie 进行扩展

运行例子/开发贡献

使用 rush 管理 monorepo

pnpm i -g @microsoft/rush concurrently @swc/cli @swc/core typescript
rush update

# dev all
rush build:watch

# dev three wechat example
rush build:watch --to-except platformize-three-wechat
cd examples/three-wechat
pnpm dev

# dev oasis example
rush build:watch --to-except platformize-oasis-wechat
cd examples/oasis-wechat
pnpm dev

# dev playcanvas wechat example
rush build:watch --to-except platformize-playcanvas-wechat
cd examples/playcanvas-wechat
pnpm dev

# dev pixi wechat example
rush build:watch --to-except platformize-pixi-wechat
cd examples/pixi-wechat
pnpm dev

# dev pixi byte example
rush build:watch --to-except platformize-pixi-wechat
cd examples/pixi-byte
pnpm dev

# prod
rush build
rush rebuild

目录设计

examples
  # 测试用例基类
  - tests-three                # three测试用例
  - tests-oasis                # oasis测试用例
  - tests-playcanvas           # playcanvas测试用例
  - tests-pixi                 # pixi测试用例

  - three-wechat-simple        # 微信小程序three基础用例
  - three-wechat               # 微信小程序three测试用例
  - three-wechat-game          # 微信小游戏three测试用例
  - three-taobao               # 淘宝小程序three测试用例
  - three-byte                 # 字节小程序three测试用例

  - oasis-wechat-simple        # 微信小程序oasis基础用例
  - oasis-wechat               # 微信小程序oasis测试用例
  - oasis-wechat-game          # 微信小游戏oasis测试用例
  - oasis-taobao               # 淘宝小程序oasis测试用例
  - oasis-byte                 # 字节小程序oasis测试用例

  - playcanvas-wechat-simple   # 微信小程序playcanvas基础用例
  - playcanvas-wechat          # 微信小程序playcanvas测试用例
  - playcanvas-wechat-game     # 微信小游戏playcanvas测试用例
  - playcanvas-taobao          # 淘宝小程序playcanvas测试用例
  - playcanvas-byte            # 字节小程序playcanvas测试用例

  - pixi-wechat-simple         # 微信小程序pixi基础用例
  - pixi-wechat                # 微信小程序pixi测试用例
  - pixi-wechat-game           # 微信小游戏pixi测试用例
  - pixi-taobao                # 淘宝小程序pixi测试用例
  - pixi-byte                  # 字节小程序pixi测试用例

packages
  - platformize
  - - plugin                   # rollup插件
  - - src
  - - - base                   # 平台无关的适配
  - - - wechat                 # 微信小程序通用适配
  - - - wechat-game            # 微信小游戏通用适配
  - - - taobao                 # 淘宝小程序通用适配
  - - - byte                   # 字节小程序通用适配

  - platformize-three
  - - plugin                   # rollup插件
  - - src
  - - - base                   # 平台无关three相关的适配
  - - - wechat                 # 微信小程序three相关适配
  - - - wechat-game            # 微信小游戏three相关适配
  - - - taobao                 # 淘宝小程序three相关适配
  - - - byte                   # 字节小程序three相关适配

  - platformize-oasis
  - - plugin                   # rollup插件
  - - src
  - - - base                   # 平台无关oasis相关的适配
  - - - wechat                 # 微信小程序oasis相关适配
  - - - wechat-game            # 微信小游戏oasis相关适配
  - - - taobao                 # 淘宝小程序oasis相关适配
  - - - byte                   # 字节小程序oasis相关适配

  - platformize-playcanvas
  - - plugin                   # rollup插件
  - - cli                      # 转换编辑器导出项目到小程序cli
  - - src
  - - - base                   # 平台无关playcanvas相关的适配
  - - - wechat                 # 微信小程序playcanvas相关适配
  - - - wechat-game            # 微信小游戏playcanvas相关适配
  - - - taobao                 # 淘宝小程序playcanvas相关适配
  - - - byte                   # 字节小程序playcanvas相关适配

  - platformize-pixi
  - - plugin                   # rollup插件
  - - src
  - - - base                   # 平台无关pixi相关的适配
  - - - wechat                 # 微信小程序pixi相关适配
  - - - wechat-game            # 微信小游戏pixi相关适配
  - - - taobao                 # 淘宝小程序pixi相关适配
  - - - byte                   # 字节小程序pixi相关适配

适配器的版本号与threejs/oasis/playcanvas/pixi主版本号一一对应, adapter 除外

TODO

0. 了解 rollup plugin 调用机制(TODO) 以及 inject 的实现 ✅
1. 统一使用 TS 作为源码, plugin 测试方法与 rollup/plugins 一致 (仅 platformize) ✅
2. 增加方便 rollup 配置 (mergeRollupOptions) 和自行组装 (platformize) 两种方式 ✅
3. 初步实现 platform 等 overwrite 机制 可能 不是最好的办法 ✅
4. fix window support ✅
5. playcanvas 初始版本适配 ✅
6. oasis 初始版本适配 (跑通 cube, glb, FlappyBrid) (模拟器 ✅, 真机 ✅)
7. 小程序一般不支持动态加载 js, 所以 playcanvas 的 Script 的动态加载将不会被支持, 需构建方式引入 (可见 tween/obj 例子) ✅
8. 构建迁移到 rush + swc (esbuild 不支持像 tsc 那样 transpile 目录) ✅
9. TextDecoder 支持更多格式 (TBD)
10. 支持 playcanvas 导出项目转换到小程序 ✅
11. 运行时反馈式 tree shaking (类似 tfjs custom module 的方式tfjs-treeshaking-test) prototype ✅
12. 新增 prebuild 包, 允许无需额外构建使用方式即 three-platformize 的方式(一想到还需要 prebuild 生态就算了比如单独 prebuild three 还不够, 还得 exampls jsm, 其他渲染引擎也类似)

适配经验

0. new Blob(parts, options) 的 options 非可选, 需要填写 mimeType

讨论

可通过飞书群里 DeepKolos 联系我, QQ群广告太多了

赞助

如果项目对您有帮助或者有适配需求，欢迎打赏

感谢各位支持~~