pixijs-scene-mesh

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Meshes render arbitrary 2D (or perspective-projected) geometry with a texture or custom shader. PixiJS ships the base

Mesh

class plus four specialized subclasses for common shapes:

MeshSimple

MeshPlane

MeshRope

, and

PerspectiveMesh

. Pick the subclass that matches your shape; drop to the base

Mesh

when you need full vertex-level control or a custom shader.

Assumes familiarity with

pixijs-scene-core-concepts

. Meshes are leaf nodes; they cannot have children. Wrap multiple meshes in a

Container

to group them.

网格（Mesh）可使用纹理或自定义着色器渲染任意2D（或透视投影）几何图形。PixiJS 提供基础的

Mesh

类以及四个针对常见形状的专用子类：

MeshSimple

、

MeshPlane

、

MeshRope

和

PerspectiveMesh

。根据你的形状选择对应的子类；当你需要完全的顶点级控制或自定义着色器时，使用基础的

Mesh

类。

假设你已熟悉

pixijs-scene-core-concepts

。网格是叶子节点，不能拥有子元素。可将多个网格包裹在

Container

中进行分组。

Quick Start

快速开始

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);

Every

Mesh

subclass takes a single options object. The base

Mesh

requires a

geometry

; subclasses (

MeshSimple

MeshPlane

MeshRope

PerspectiveMesh

) build the geometry internally and require a

texture

instead. See each variant's reference for the full field list.

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

参数。请查看各变体的参考文档获取完整字段列表。

Variants

变体对比

Variant	Use when	Trade-offs	Reference
`Mesh`	Full control, custom geometry, custom shaders	You build the `MeshGeometry` yourself	references/mesh.md
`MeshSimple`	Quick textured shapes with per-frame vertex animation	Thin wrapper; auto-updates the vertex buffer	references/mesh-simple.md
`MeshPlane`	Subdivided textured rectangle for distortion effects	Fixed topology; `verticesX` / `verticesY` control density	references/mesh-plane.md
`MeshRope`	Texture following a polyline path	Bent at each point; needs many points for smooth curves	references/mesh-rope.md
`PerspectiveMesh`	2D plane with perspective corners	Not true 3D; UV-level perspective correction only	references/mesh-perspective.md

变体类型	使用场景	优缺点对比	参考文档链接
`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

When to use what

场景选型指南

"I need a textured quad" →
```
Sprite
```
(see
```
pixijs-scene-sprite
```
), not a mesh. Meshes are for cases Sprite can't express.
"I need to deform a textured rectangle" →
```
MeshPlane
```
. Set
```
verticesX
```
/
```
verticesY
```
for the desired smoothness.
"I need a rope or trail that follows points" →
```
MeshRope
```
. Control thickness with
```
width
```
; use
```
textureScale: 0
```
to stretch or
```
> 0
```
to repeat.
"I need a tilted 2D card or floor" →
```
PerspectiveMesh
```
. Pass four corner positions; not real 3D but good enough for 2.5D effects.
"I need per-frame animated vertices with a simple shape" →
```
MeshSimple
```
. It handles the buffer-update dance for you.
"I need a custom shader or unusual geometry" → Base
```
Mesh
```
with a hand-built
```
MeshGeometry
```
. See
```
pixijs-custom-rendering
```
for shader authoring.
"I need true 3D rendering" → Use a dedicated 3D library.
```
PerspectiveMesh
```
simulates perspective at the UV level but has no depth buffer.

「我需要一个带纹理的四边形」 → 使用
```
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层面模拟透视效果，没有深度缓冲区。

Quick concepts

核心概念

MeshGeometry owns the vertex data

MeshGeometry管理顶点数据

MeshGeometry

holds the

positions

uvs

indices

, and

topology

. You can share one geometry across multiple

Mesh

instances; positions are reference-counted.

MeshGeometry

存储

positions

、

uvs

、

indices

和

topology

数据。你可以在多个

Mesh

实例间共享同一个几何图形；位置数据采用引用计数管理。

Batching

批处理

A mesh batches (combines with other draw calls) only if it uses

MeshGeometry

, has no custom shader, no depth or culling state, and the

'auto'

rule (

batchMode = 'auto'

and ≤100 vertices). Custom shaders always render independently.

只有当网格使用

MeshGeometry

、无自定义着色器、无深度或剔除状态，且符合

'auto'

规则（

batchMode = 'auto'

且顶点数≤100）时，才会进行批处理（与其他绘制调用合并）。自定义着色器始终会独立渲染。

Topology is on the geometry, not the mesh

拓扑属性属于几何图形，而非网格

new MeshGeometry({ topology: 'triangle-strip' })

; topology is a geometry property. The default is

'triangle-list'

; set it explicitly if your data is organized differently.

拓扑是几何图形的属性，例如

new MeshGeometry({ topology: 'triangle-strip' })

；默认值为

'triangle-list'

，如果你的数据组织方式不同，请显式设置该属性。

Extra knobs

额外配置项

```
new MeshGeometry({ shrinkBuffersToFit: true })
```
— trims GPU buffer storage to the actual vertex count on creation. Use it when feeding large, one-shot geometries.
```
Mesh.containsPoint(point)
```
— topology-aware hit test that walks the triangles. Works with any
```
MeshGeometry
```
, including custom layouts.
```
new Mesh({ geometry, state })
```
— pass a
```
State
```
object to control blend, depth, and culling. Batching is disabled automatically if depth or culling flags are set. Defaults to
```
State.for2d()
```
when omitted.

```
new MeshGeometry({ shrinkBuffersToFit: true })
```
—— 在创建时将GPU缓冲区存储裁剪至实际顶点数量。当传入大型一次性几何图形时可使用此配置。
```
Mesh.containsPoint(point)
```
—— 支持拓扑感知的命中检测，会遍历所有三角形。适用于任何
```
MeshGeometry
```
，包括自定义布局。
```
new Mesh({ geometry, state })
```
—— 传入
```
State
```
对象来控制混合、深度和剔除设置。如果设置了深度或剔除标志，批处理会自动禁用。如果省略该参数，默认使用
```
State.for2d()
```
。

Common Mistakes

常见错误

[HIGH] Using old

SimpleMesh

SimplePlane

SimpleRope

names

[高风险] 使用旧版

SimpleMesh

SimplePlane

SimpleRope

类名

Wrong:

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

Correct:

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

Renamed in v8:

SimpleMesh

→

MeshSimple

SimplePlane

→

MeshPlane

SimpleRope

→

MeshRope

. All switched to options-object constructors.

错误示例：

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] Positional constructor args for

MeshGeometry

[高风险] 使用位置参数构造

MeshGeometry

Wrong:

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

Correct:

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

v8 uses an options object. Note the property is

positions

, not

vertices

; the

vertices

name is only used by

MeshSimple

错误示例：

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

正确示例：

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

v8版本使用选项对象。注意属性名为

positions

而非

vertices

；

vertices

仅在

MeshSimple

中使用。

[MEDIUM] Adding children to a mesh

[中风险] 为网格添加子元素

Wrong:

mesh.addChild(otherMesh);

Correct:

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

Mesh

sets

allowChildren = false

. Adding children logs a deprecation warning. Group meshes inside a plain

Container

错误示例：

mesh.addChild(otherMesh);

正确示例：

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

Mesh

设置了

allowChildren = false

。添加子元素会记录弃用警告。请将网格分组到普通的

Container

中。

pixijs-scene-mesh

Original

Translation

Quick Start

快速开始

Variants

变体对比

When to use what

场景选型指南

Quick concepts

核心概念

MeshGeometry owns the vertex data

MeshGeometry管理顶点数据

Batching

批处理

Topology is on the geometry, not the mesh

拓扑属性属于几何图形，而非网格

Extra knobs

额外配置项

Common Mistakes

常见错误

[HIGH] Using old
`SimpleMesh`
/
`SimplePlane`
/
`SimpleRope`
names

[高风险] 使用旧版
`SimpleMesh`
/
`SimplePlane`
/
`SimpleRope`
类名

[HIGH] Positional constructor args for
`MeshGeometry`

[高风险] 使用位置参数构造
`MeshGeometry`

[MEDIUM] Adding children to a mesh

[中风险] 为网格添加子元素

API Reference

API参考

pixijs-scene-mesh

Original

Translation

Quick Start

快速开始

Variants

变体对比

When to use what

场景选型指南

Quick concepts

核心概念

MeshGeometry owns the vertex data

MeshGeometry管理顶点数据

Batching

批处理

Topology is on the geometry, not the mesh

拓扑属性属于几何图形，而非网格

Extra knobs

额外配置项

Common Mistakes

常见错误

[HIGH] Using old SimpleMesh / SimplePlane / SimpleRope names

[高风险] 使用旧版SimpleMesh / SimplePlane / SimpleRope类名

[HIGH] Positional constructor args for MeshGeometry

[高风险] 使用位置参数构造MeshGeometry

[MEDIUM] Adding children to a mesh

[中风险] 为网格添加子元素

API Reference

API参考

[HIGH] Using old
`SimpleMesh`
/
`SimplePlane`
/
`SimpleRope`
names

[高风险] 使用旧版
`SimpleMesh`
/
`SimplePlane`
/
`SimpleRope`
类名

[HIGH] Positional constructor args for
`MeshGeometry`

[高风险] 使用位置参数构造
`MeshGeometry`