用 PlayCanvas 构建浏览器 3D…

在浏览器中用 PlayCanvas（WebGL/WebGPU 引擎）搭建实体-组件架构的 3D 场景、加载模型材质、接入物理与输入、并做性能优化的可执行做法。

适用场景

解决思路

1. 初始化应用：用 document.createElement('canvas') 创建画布并挂到 body，new pc.Application(canvas)，调用 app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW) 与 app.setCanvasResolution(pc.RESOLUTION_AUTO)，监听 window resize 调用 app.resizeCanvas()，最后必须调用 app.start() 启动渲染循环。
2. 用 ECS 组织场景：new pc.Entity('name') 创建实体，app.root.addChild(entity) 挂到场景树，entity.addComponent('model'|'script'|...) 添加能力，用 setPosition/setEulerAngles/setLocalScale 设置变换，用 parent.addChild(child) 建立父子层级。
3. 注册更新循环：app.on('update', (dt) => {...}) 处理逐帧逻辑（dt 为秒），用 app.on('prerender') 和 app.on('postrender') 做渲染前后处理。
4. 配置 model 组件：addComponent('model', { type: 'box'|'sphere'|'cylinder'|'cone'|'capsule'|'asset', material, castShadows, receiveShadows })。
5. 配置 camera 组件：addComponent('camera', { clearColor, fov, nearClip, farClip, projection: pc.PROJECTION_PERSPECTIVE 或 pc.PROJECTION_ORTHOGRAPHIC })，配合 setPosition 与 lookAt 定位。
6. 配置 light 组件：addComponent('light', { type: pc.LIGHTTYPE_DIRECTIONAL|POINT|SPOT, color, intensity, castShadows, shadowDistance })。
7. 接入刚体与碰撞：成对使用 addComponent('rigidbody', { type: pc.BODYTYPE_DYNAMIC|STATIC|KINEMATIC, mass, friction, restitution }) 与 addComponent('collision', { type: 'box', halfExtents: new pc.Vec3(0.5,0.5,0.5) })。
8. 基础场景模板：按 camera（setPosition + lookAt）→ light（setEulerAngles 打光）→ ground（model type 'plane' + setLocalScale(10,1,10)）→ cube（model type 'box' + setPosition）的顺序创建实体并 app.root.addChild，在 app.on('update') 中用 cube.rotate(...) 驱动动画。
9. 加载 GLTF 模型：new pc.Asset(name, 'container', { url: '/models/character.glb' }) → app.assets.add(asset) → asset.ready(asset => { const e = asset.resource.instantiateRenderEntity(); app.root.addChild(e); }) 中做缩放与摆放 → app.assets.load(asset)，并注册 asset.on('error', err => ...) 处理加载失败。
10. 创建材质：new pc.StandardMaterial()，设置 material.diffuse（pc.Color）、material.metalness、material.gloss，每次修改后调用 material.update()，再赋给 entity.model.material。
11. 加载纹理：对每张图 new pc.Asset(key, 'texture', { url }) → app.assets.add(asset) → asset.ready(a => { 按用途把 a.resource 赋给 material.diffuseMap / normalMap / metalnessMap / glossMap / aoMap; material.update(); }) → app.assets.load(asset)，逐张映射。
12. 集成物理引擎：动态插入 ammo.js 脚本（src 为 https://cdn.jsdelivr.net/npm/ammo.js@0.0.10/ammo.js），在 onload 中 Ammo().then(AmmoLib => { window.Ammo = AmmoLib; ... }) 之后再创建 rigidbody/collision 组件并 app.start()，用 rigidbody.applyForce(x,y,z) 和 rigidbody.applyTorque(x,y,z) 施加力与力矩。
13. 定义自定义脚本：用 pc.createScript('rotate') 创建，通过 RotateScript.attributes.add('speed', { type: 'number', default: 10, title: 'Rotation Speed' }) 暴露可调参数，实现 prototype.initialize/update/destroy，再用 entity.addComponent('script') + entity.script.create('rotate', { attributes: { speed: 20, axis: new pc.Vec3(0,1,0) } }) 挂载。
14. 实现脚本生命周期钩子：initialize（资源加载完成后一次）、postInitialize（所有实体初始化后）、update(dt)（每帧渲染前）、postUpdate(dt)（每帧 update 后）、swap(old)（支持热重载）、destroy()（实体销毁时清理）。
15. 处理输入：键盘用 app.keyboard.isPressed(pc.KEY_W) 与 app.keyboard.wasPressed(pc.KEY_SPACE)；鼠标用 app.mouse.on(pc.EVENT_MOUSEDOWN|pc.EVENT_MOUSEMOVE) 读取 event.button/event.x/event.y/event.dx/event.dy；触摸用 app.touch.on(pc.EVENT_TOUCHSTART) 遍历 event.touches。
16. 做鼠标拾取：用 camera.camera.screenToWorld(event.x, event.y, nearClip) 和 (…, farClip) 得到 from/to 两点，调用 app.systems.rigidbody.raycastFirst(from, to)，对返回的 result.entity 做处理（如改材质 emissive）。
17. 播放骨骼动画：给模型实体 addComponent('animation', { assets: [asset], speed: 1.0, loop: true, activate: true })，用 entity.animation.play('Walk', 0.2) 指定动作名与混合时间，切换动作时改变 play 名称和过渡时长。
18. 做补间动画：entity.tween(entity.getLocalPosition()).to({ x: 5, y: 2, z: 0 }, 2.0, pc.SineInOut).start()，可链式调用 .loop(true).yoyo(true).delay(0.5).repeat(3)；也可对材质颜色用 app.tween(material.emissive).to(new pc.Color(1,0,0), 1.0, pc.SineInOut) 做渐变。
19. 与 React 集成：用 useRef 分别持有 canvasRef 和 appRef，在 useEffect 中初始化 app、搭建场景、app.start()，并在返回的清理函数中调用 app.destroy()。
20. 加载编辑器导出的项目：fetch('/config.json') 后调用 app.scenes.loadSceneHierarchy(config.scene_url, (err, parent) => {...})，用 app.root.findByName('Player') 定位实体，通过 entity.script.myScript.doSomething() 调用脚本方法，之后再 app.start()。
21. 使用对象池复用实体：构造时预建 N 个 entity、entity.enabled = false、app.root.addChild 后放入 pool；spawn(position) 从 pool pop 出来、enabled = true、setPosition；despawn(entity) 置 enabled = false 并放回 pool；池耗尽时再新建实体补充。
22. 做 LOD 与距离剔除：在 app.on('update') 中用 camera.getPosition().distance(entity.getPosition()) 判断距离，近距离赋高模、中距离赋中模、远距离赋低模到 entity.model.asset，或距离超阈值时直接 entity.enabled = false。
23. 做静态批处理：给多个实体的 entity.model.batchGroupId 赋同一个组 ID，再调用 app.batcher.generate([entity1, entity2, entity3]) 合并静态网格以减少 draw call。
24. 使用压缩纹理：new pc.Texture(app.graphicsDevice, { width, height, format: pc.PIXELFORMAT_DXT5, minFilter: pc.FILTER_LINEAR_MIPMAP_LINEAR, magFilter: pc.FILTER_LINEAR, mipmaps: true })。
25. 安全销毁实体：不要在遍历过程中直接 entity.destroy()，先把待删实体推入 toDestroy 数组，在 app.on('postUpdate') 中统一 entity.destroy() 并清空数组。
26. 及时释放资源避免内存泄漏：对不再使用的 asset 调用 app.assets.remove(asset) 与 asset.unload()，把清理逻辑作为函数返回以便后续调用。
27. 正确区分本地与世界变换：子实体相对父级定位用 setLocalPosition，需要世界坐标时用 setPosition(worldPos)，避免父子变换叠加导致位置错误。
28. 让画布自适应：不要写死 canvas.width/canvas.height，使用 fill mode + RESOLUTION_AUTO + resize 监听保证铺满容器并随窗口变化。

适用边界 · 注意事项

• 需要完全底层掌控 WebGL/着色器或已有大量 Three.js 定制代码时，改用 Three.js 更合适。
• 以声明式 HTML 方式快速做 VR 场景时，A-Frame 更贴合；在 React 生态中已有 react-three-fiber 项目时也应优先沿用。
• 需要大量开箱即用高级功能且不在意包体积时可考虑 Babylon.js，而非轻量优先的 PlayCanvas。