pixijs-scene-mesh

网格可以使用纹理或自定义着色器来渲染任意 2D 几何形状（或经透视投影的几何形状）。PixiJS 提供了基础 Mesh 类，以及四个适用于常见形状的专用子类：MeshSimple、MeshPlane、MeshRope 和 PerspectiveMesh。选择与形状匹配的子类；需要完全控制顶点或使用自定义着色器时，则使用基础 Mesh。

假设你已熟悉 pixijs-scene-core-concepts。网格是叶节点，不能包含子项。要将多个网格编组，请将它们放入 Container。

快速入门

const texture = await Assets.load("pattern.png");

const geometry = new MeshGeometry({
  positions: new Float32Array([0, 0, 100, 0, 100, 100, 0, 100]),
  uvs: new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]),
  indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
  topology: "triangle-list",
});

const mesh = new Mesh({
  geometry,
  texture,
  roundPixels: false,
});
app.stage.addChild(mesh);

每个 Mesh 子类都接受一个选项对象。基础 Mesh 需要 geometry；子类（MeshSimple、MeshPlane、MeshRope、PerspectiveMesh）会在内部构建几何体，因此需要 texture。完整字段列表请参阅各变体的参考文档。

变体

变体	适用场景	权衡	参考文档
Mesh	完全控制、自定义几何体、自定义着色器	需要自行构建 MeshGeometry	references/mesh.md
MeshSimple	快速创建纹理形状并逐帧为顶点添加动画	轻量封装；自动更新顶点缓冲区	references/mesh-simple.md
MeshPlane	用于扭曲效果的细分纹理矩形	拓扑固定；通过 verticesX/verticesY 控制密度	references/mesh-plane.md
MeshRope	纹理沿折线轨迹延伸	在每个点处弯折；平滑曲线需要较多点	references/mesh-rope.md
PerspectiveMesh	带透视角点的 2D 平面	不是真正的 3D；仅在 UV 层级进行透视校正	references/mesh-perspective.md

如何选择

• “我需要一个带纹理的四边形” → 使用 Sprite（参见 pixijs-scene-sprite），而不是网格。只有 Sprite 无法实现时才使用网格。
• “我需要变形带纹理的矩形” → 使用 MeshPlane。设置 verticesX/verticesY 来调整平滑度。
• “我需要沿点的轨迹延伸的绳索或轨迹效果” → 使用 MeshRope。通过 width 控制粗细；使用 textureScale: 0 拉伸纹理，使用 > 0 重复纹理。
• “我需要倾斜的 2D 卡片或地面” → 使用 PerspectiveMesh。传入四个角的位置；它不是真正的 3D，但足以实现 2.5D 效果。
• “我需要为简单形状的顶点添加逐帧动画” → 使用 MeshSimple。它会代你处理缓冲区更新。
• “我需要自定义着色器或特殊几何体” → 使用基础 Mesh，并手动构建 MeshGeometry。有关着色器编写，请参阅 pixijs-custom-rendering。
• “我需要真正的 3D 渲染” → 使用专用的 3D 库。PerspectiveMesh 会在 UV 层级模拟透视，但没有深度缓冲区。

核心概念

MeshGeometry 管理顶点数据

MeshGeometry 保存 positions、uvs、indices 和 topology。多个 Mesh 实例可以共享同一个几何体；位置数据采用引用计数。

批处理

只有在使用 MeshGeometry、没有自定义着色器、没有深度或剔除状态，并且符合 'auto' 规则（batchMode = 'auto' 且顶点数 ≤100）时，网格才会进行批处理（与其他绘制调用合并）。自定义着色器始终独立渲染。

拓扑属于几何体，而非网格

new MeshGeometry({ topology: 'triangle-strip' })；拓扑是几何体的属性。默认值为 'triangle-list'；如果你的数据采用其他组织方式，请显式设置。

额外选项

• new MeshGeometry({ shrinkBuffersToFit: true }) — 创建时将 GPU 缓冲区存储空间缩减到实际顶点数量。用于输入大型的一次性几何体。
• Mesh.containsPoint(point) — 感知拓扑的命中测试，会遍历三角形。适用于任何 MeshGeometry，包括自定义布局。
• new Mesh({ geometry, state }) — 传入 State 对象以控制混合、深度和剔除。设置深度或剔除标志时会自动禁用批处理。省略时默认为 State.for2d()。

常见错误

[HIGH] 使用旧名称 SimpleMesh / SimplePlane / SimpleRope

错误：

import { SimpleRope } from "pixi.js";
const rope = new SimpleRope(texture, points);

正确：

import { MeshRope } from "pixi.js";
const rope = new MeshRope({ texture, points });

在 v8 中重命名：SimpleMesh → MeshSimple，SimplePlane → MeshPlane，SimpleRope → MeshRope。它们现在都改用选项对象构造函数。

[HIGH] 使用位置参数调用 MeshGeometry 构造函数

错误：

const geom = new MeshGeometry(vertices, uvs, indices);

正确：

const geom = new MeshGeometry({
  positions: vertices,
  uvs,
  indices,
  topology: "triangle-list",
});

v8 使用选项对象。请注意，属性名是 positions，而不是 vertices；vertices 仅用于 MeshSimple。

[MEDIUM] 向网格添加子项

错误：

mesh.addChild(otherMesh);

正确：

const group = new Container();
group.addChild(mesh, otherMesh);

Mesh 将 allowChildren 设为 false。添加子项会记录弃用警告。请将网格放在普通 Container 中进行分组。

API 参考

• 网格
• 网格几何体
• 简单网格
• 平面网格
• 绳索网格
• 透视网格