---
id: gh-pixijs-scene-mesh
name: "pixijs-scene-mesh"
url: https://skills.yangsir.net/skill/gh-pixijs-scene-mesh
author: pixijs
domain: game-dev
tags: ["pixijs", "mesh", "2d-graphics", "game-development", "geometry"]
install_count: 2400
rating: 4.30 (120 reviews)
github: https://github.com/pixijs/pixijs-skills/tree/main/skills/pixijs-scene-mesh
---

# pixijs-scene-mesh

> 此技能用于在 PixiJS v8 中渲染自定义几何体，涵盖了从基础网格到特殊形状（如平面、绳索、透视网格）的多种应用。它为开发者提供了灵活的图形渲染能力，以创建复杂的2D或2.5D视觉效果，无需依赖外部3D库。

**Stats**: 2,400 installs · 4.3/5 (120 reviews)

## Before / After 对比

### 复杂几何体渲染开发效率

**Before**:

在没有这个技能之前，开发者需要手动管理顶点数据、UV映射和索引，为不同的复杂几何体（如弯曲路径、变形平面）编写定制渲染逻辑，这导致开发周期长且容易出错。

**After**:

此技能通过提供预设的 Mesh 子类（如 MeshPlane、MeshRope、PerspectiveMesh），开发者可以快速定义和渲染各种复杂几何体，显著缩短了开发时间并减少了错误。

| Metric | Before | After | Change |
|---|---|---|---|
| 开发时间 | 120分钟 | 20分钟 | -83% |

## Readme

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.

## Quick Start

```ts
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.

## Variants

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

## Quick concepts

### MeshGeometry owns the vertex data

`MeshGeometry` holds the `positions`, `uvs`, `indices`, and `topology`. You can share one geometry across multiple `Mesh` instances; positions are reference-counted.

### 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.

### 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.

### 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.

## Common Mistakes

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

Wrong:

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

Correct:

```ts
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.


### [HIGH] Positional constructor args for `MeshGeometry`

Wrong:

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

Correct:

```ts
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`.


### [MEDIUM] Adding children to a mesh

Wrong:

```ts
mesh.addChild(otherMesh);
```

Correct:

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

`Mesh` sets `allowChildren = false`. Adding children logs a deprecation warning. Group meshes inside a plain `Container`.


## API Reference

- [Mesh](https://pixijs.download/release/docs/scene.Mesh.html.md)
- [MeshGeometry](https://pixijs.download/release/docs/scene.MeshGeometry.html.md)
- [MeshSimple](https://pixijs.download/release/docs/scene.MeshSimple.html.md)
- [MeshPlane](https://pixijs.download/release/docs/scene.MeshPlane.html.md)
- [MeshRope](https://pixijs.download/release/docs/scene.MeshRope.html.md)
- [PerspectiveMesh](https://pixijs.download/release/docs/scene.PerspectiveMesh.html.md)


---
*Source: https://skills.yangsir.net/skill/gh-pixijs-scene-mesh*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-pixijs-scene-mesh/markdown*