Pixijs Scene Mesh

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

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

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:

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.

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

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

API Reference

• Mesh
• MeshGeometry
• MeshSimple
• MeshPlane
• MeshRope
• PerspectiveMesh

PerspectiveMesh

A mesh that renders a textured plane with perspective projection via four corner points. The UV interpolation is computed per vertex in a subdivided grid, so the more vertices you allocate, the smoother the projection. Use PerspectiveMesh for 2D billboards, floor planes, angled cards, fake 3D layouts, or anywhere you want a texture to appear tilted into the scene.

Quick Start

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

const mesh = new PerspectiveMesh({
  texture,
  verticesX: 20,
  verticesY: 20,
  x0: 0,
  y0: 0, // top-left
  x1: 300,
  y1: 30, // top-right (raised)
  x2: 280,
  y2: 300, // bottom-right
  x3: 20,
  y3: 280, // bottom-left
});

app.stage.addChild(mesh);

The four corner coordinates define a quadrilateral in local space; the mesh warps the texture to fit it with perspective-correct UVs.

Constructor options

new PerspectiveMesh(options: PerspectivePlaneOptions)

Note: the interface is PerspectivePlaneOptions, not PerspectiveMeshOptions. It extends MeshPlaneOptions.

Corners must be listed clockwise from the top-left. Defaults form a 100x100 square with Texture.WHITE; PerspectiveMesh.defaultOptions overrides them globally. The constructor omits geometry (it builds its own PerspectivePlaneGeometry). Other MeshOptions fields (shader, state, roundPixels) are inherited from mesh.md.

All Container options (position, scale, tint, label, filters, zIndex, etc.) are also valid here — see skills/pixijs-scene-core-concepts/references/constructor-options.md.

Call mesh.setCorners(x0, y0, x1, y1, x2, y2, x3, y3) at runtime to animate the warp.

Core Patterns

Corner order

mesh.setCorners(
  0,
  0, // top-left    (x0, y0)
  200,
  0, // top-right   (x1, y1)
  200,
  200, // bottom-right(x2, y2)
  0,
  200, // bottom-left (x3, y3)
);

Corners must be specified clockwise starting from the top-left. setCorners updates the geometry in place; use it for animation.

Animated perspective

const mesh = new PerspectiveMesh({
  texture,
  verticesX: 20,
  verticesY: 20,
});

app.ticker.add(() => {
  const t = performance.now() / 1000;
  const wave = Math.sin(t) * 30;

  mesh.setCorners(0, wave, 200, -wave, 200, 200, 0, 200);
});

Call setCorners each frame to animate the warp. The geometry recalculates perspective-correct UVs automatically.

Vertex density vs quality

const coarse = new PerspectiveMesh({ texture, verticesX: 5, verticesY: 5 });
const smooth = new PerspectiveMesh({ texture, verticesX: 30, verticesY: 30 });

The number of vertices controls how smooth the perspective projection looks. A 5×5 grid shows obvious triangular stretching; 20×20 is a good default; 30×30+ is smooth but adds draw overhead. Each axis defaults to 10.

Fake floor

const floor = new PerspectiveMesh({
  texture: floorTex,
  verticesX: 20,
  verticesY: 20,
  x0: 200,
  y0: 300, // near left on screen
  x1: 600,
  y1: 300, // near right
  x2: 800,
  y2: 200, // far right
  x3: 0,
  y3: 200, // far left
});

app.stage.addChild(floor);

Put the "far" corners higher on the screen and closer together than the "near" corners to create a floor-extending-into-the-distance effect. Use with a scrolling TilingSprite above for a stylized 2D driving game.

Updating the texture

mesh.texture = await Assets.load("new-card.png");

Changing the texture rebuilds the geometry to match the new dimensions while keeping the current corner positions. The perspective projection persists through texture swaps.

Common Mistakes

[HIGH] Expecting true 3D

PerspectiveMesh is a 2D mesh with UV correction to simulate perspective. There is no Z axis, no depth buffer, and no camera. For real 3D, use a full WebGL/WebGPU library on top of PixiJS, or drive vertex positions through a manual transform.

[MEDIUM] Too few vertices for a noticeable tilt

Wrong:

const mesh = new PerspectiveMesh({
  texture,
  verticesX: 2,
  verticesY: 2,
  x0: 0,
  y0: 0,
  x1: 300,
  y1: 50,
  x2: 280,
  y2: 250,
  x3: 20,
  y3: 200,
});

Correct:

const mesh = new PerspectiveMesh({
  texture,
  verticesX: 20,
  verticesY: 20,
  x0: 0,
  y0: 0,
  x1: 300,
  y1: 50,
  x2: 280,
  y2: 250,
  x3: 20,
  y3: 200,
});

A 2×2 grid has only two triangles; the texture stretches linearly with no perspective correction. Bump density above 10×10 for any visible tilt.

[MEDIUM] Non-convex corners

If your four corners form a non-convex (self-intersecting or bow-tie) quadrilateral, the UV interpolation produces visual artifacts. Keep the corners in consistent clockwise order and check that the quad is convex.

API Reference

• PerspectiveMesh
• PerspectivePlaneOptions
• MeshPlane

MeshPlane

A mesh that maps a texture onto a subdivided plane with configurable vertex density. Use MeshPlane for distortion effects, wave simulations, cloth, heat haze, or any effect that needs per-vertex deformation of a flat textured rectangle.

Quick Start

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

const plane = new MeshPlane({
  texture,
  verticesX: 10,
  verticesY: 10,
});

app.stage.addChild(plane);

verticesX / verticesY control the grid density (each defaults to 10). More vertices give smoother deformation at higher draw overhead. The plane sizes itself to the texture by default.

Constructor options

new MeshPlane(options: MeshPlaneOptions)

MeshPlane builds its own PlaneGeometry, so you cannot pass geometry — it is omitted from the options type. Other MeshOptions fields (shader, state, roundPixels) are inherited from mesh.md and behave identically.

All Container options (position, scale, tint, label, filters, zIndex, etc.) are also valid here — see skills/pixijs-scene-core-concepts/references/constructor-options.md.

autoResize is a runtime property set to true by the constructor, not a constructor option. Toggle it after construction to control whether texture changes rebuild the plane geometry.

Core Patterns

Deforming the vertex grid

const { buffer } = plane.geometry.getAttribute("aPosition");

app.ticker.add(() => {
  for (let i = 0; i < buffer.data.length; i++) {
    buffer.data[i] += Math.sin(performance.now() / 1000 + i) * 0.3;
  }
  buffer.update();
});

Grab the position buffer via getAttribute('aPosition'), mutate the data array, then call buffer.update() to push changes to the GPU. The texture UVs are fixed once the plane is built, so as long as you only move vertices (not change the grid topology), the texture stretches to follow.

Auto-resize on texture change

plane.texture = await Assets.load("new-background.png");

autoResize defaults to true. When the plane's texture changes (or emits an 'update' event), the geometry rebuilds to match the new texture dimensions. Set autoResize = false to keep the original size regardless of the new texture.

Fixed-size plane

const fixedPlane = new MeshPlane({
  texture,
  verticesX: 20,
  verticesY: 20,
});
fixedPlane.autoResize = false;

const geometry = fixedPlane.geometry;
geometry.width = 500;
geometry.height = 300;
geometry.build({});

For a plane whose size is decoupled from the texture, disable autoResize and set the geometry's width / height explicitly. Call build({}) to regenerate vertex positions at the new size.

Higher vertex density for smooth distortion

const smooth = new MeshPlane({
  texture,
  verticesX: 40,
  verticesY: 40,
});

Vertex density directly controls how smoothly the plane can deform. A 10×10 grid is fine for coarse ripples; for waves, cloth, or fine distortion, bump density to 20×20 or higher. Density above ~50×50 starts to affect draw overhead on lower-end devices.

Wave animation

const plane = new MeshPlane({ texture, verticesX: 30, verticesY: 30 });
const { buffer } = plane.geometry.getAttribute("aPosition");
const original = new Float32Array(buffer.data);

app.ticker.add((ticker) => {
  const t = performance.now() / 500;
  for (let i = 0; i < buffer.data.length; i += 2) {
    buffer.data[i] = original[i];
    buffer.data[i + 1] = original[i + 1] + Math.sin(t + original[i] * 0.1) * 5;
  }
  buffer.update();
});

Cache the original positions once, then offset from them each frame. Resetting to the base positions each frame avoids cumulative drift.

Common Mistakes

[HIGH] Using the old SimplePlane name

Wrong:

import { SimplePlane } from "pixi.js";
const plane = new SimplePlane(texture, 10, 10);

Correct:

import { MeshPlane } from "pixi.js";
const plane = new MeshPlane({ texture, verticesX: 10, verticesY: 10 });

SimplePlane was renamed to MeshPlane in v8 and switched to an options-object constructor.

[MEDIUM] Mutating positions without calling buffer.update()

Wrong:

buffer.data[1] = 50;

Correct:

buffer.data[1] = 50;
buffer.update();

The buffer does not observe its own data array. Without update(), the changes stay on the CPU and the next render draws stale vertex data.

[MEDIUM] High vertex density on pixel-art textures

A dense grid on a small pixel-art texture can cause visible UV interpolation artifacts. Use fewer vertices (10×10 or less) for pixel art, or set roundPixels: true on the mesh.

API Reference

• MeshPlane
• MeshPlaneOptions
• PlaneGeometry

MeshRope

A mesh that renders a texture along a path defined by points. Each segment bends the texture to follow the curve. Use MeshRope for ropes, chains, snakes, trails, whip effects, tentacles, and any effect where you want a textured ribbon that follows a moving polyline.

Quick Start

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

const points = [];
for (let i = 0; i < 20; i++) {
  points.push(new Point(i * 50, 0));
}

const rope = new MeshRope({
  texture,
  points,
  textureScale: 0,
  width: texture.height,
});
app.stage.addChild(rope);

app.ticker.add(() => {
  const t = performance.now() / 500;
  for (let i = 0; i < points.length; i++) {
    points[i].y = Math.sin(i * 0.5 + t) * 30;
  }
});

The rope uses the y-axis of the texture as its thickness and stretches the x-axis along the path. Move points each frame; with autoUpdate enabled (default), the geometry updates automatically.

Constructor options

new MeshRope(options: MeshRopeOptions)

MeshRope builds its own RopeGeometry, so geometry is omitted from the options type. Other MeshOptions fields (shader, state, roundPixels) are inherited from mesh.md and behave identically.

All Container options (position, scale, tint, label, filters, zIndex, etc.) are also valid here — see skills/pixijs-scene-core-concepts/references/constructor-options.md.

autoUpdate is a runtime property (defaults to true), not a constructor option. Set rope.autoUpdate = false after construction to control when the geometry recomputes from the points. MeshRope.defaultOptions overrides the textureScale default globally.

Core Patterns

textureScale: stretch vs repeat

// stretch (default); entire texture maps across the rope
const stretched = new MeshRope({ texture, points, textureScale: 0 });

// repeat; texture tiles along the rope, preserving aspect ratio
const repeated = new MeshRope({ texture, points, textureScale: 1 });

// higher resolution; downsample an HD texture for better quality
const sharp = new MeshRope({ texture: hdRope, points, textureScale: 0.5 });

• textureScale: 0 (default): stretches the texture across the full rope length.
• textureScale > 0: repeats the texture while preserving its aspect ratio. The underlying texture source has its addressMode set to 'repeat'. Power-of-two textures are recommended for WebGL compatibility.
• textureScale < 1 with a larger source texture reduces alpha-channel artifacts.

Rope width

const thick = new MeshRope({
  texture,
  points,
  width: 60,
});

width (thickness) defaults to texture.height. Override it for a rope narrower or wider than the source art.

Manual update mode

const rope = new MeshRope({ texture, points });
rope.autoUpdate = false;

app.ticker.add(() => {
  for (let i = 0; i < points.length; i++) {
    points[i].y = Math.sin(i + performance.now() / 1000) * 30;
  }
  (rope.geometry as RopeGeometry).update();
});

Set autoUpdate = false to control when the geometry recomputes from the points. Useful when your point array only changes occasionally, or when you want to update once per multiple frames for performance.

Trail effect

const trailPoints: Point[] = [];
for (let i = 0; i < 30; i++) {
  trailPoints.push(new Point(0, 0));
}

const trail = new MeshRope({
  texture: trailTex,
  points: trailPoints,
  textureScale: 0,
});
app.stage.addChild(trail);

app.ticker.add(() => {
  for (let i = trailPoints.length - 1; i > 0; i--) {
    trailPoints[i].x = trailPoints[i - 1].x;
    trailPoints[i].y = trailPoints[i - 1].y;
  }
  trailPoints[0].x = mouseX;
  trailPoints[0].y = mouseY;
});

A simple tail effect: shift all points one slot down each frame, then write the new head. Stretch texture mode (textureScale: 0) makes the full texture visible along the trail regardless of length.

Common Mistakes

[HIGH] Using the old SimpleRope or Rope name

Wrong:

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

Correct:

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

SimpleRope was renamed to MeshRope in v8 and switched to an options-object constructor.

[HIGH] Too few points for a smooth curve

Wrong:

const rope = new MeshRope({
  texture,
  points: [new Point(0, 0), new Point(400, 0)],
});

Correct:

const points = [];
for (let i = 0; i < 20; i++) points.push(new Point(i * 20, 0));
const rope = new MeshRope({ texture, points });

The rope only bends at point boundaries. Two points produce a straight segment; a curved rope needs many closely-spaced points (typically 15–30 for a visible bend).

[MEDIUM] Non-power-of-two texture with textureScale > 0

When textureScale is positive, the rope sets the texture source's addressMode to 'repeat'. Some WebGL drivers clamp non-power-of-two textures instead of wrapping, causing the tile pattern to stretch. Resize the source to power-of-two dimensions (128, 256, 512, etc.) for reliable wrapping.

API Reference

• MeshRope
• MeshRopeOptions
• RopeGeometry

MeshSimple

A thin Mesh subclass that handles geometry construction for you. Pass vertices, optional uvs, and optional indices, and it builds the MeshGeometry internally and auto-updates the vertex buffer each frame. Use MeshSimple for quick textured quads, triangles, or any shape where you plan to animate vertex positions.

Quick Start

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

const triangle = new MeshSimple({
  texture,
  vertices: new Float32Array([0, 0, 100, 0, 50, 100]),
  uvs: new Float32Array([0, 0, 1, 0, 0.5, 1]),
  topology: "triangle-list",
});

app.stage.addChild(triangle);

MeshSimple wraps MeshGeometry creation, exposes vertices directly, and auto-updates the position buffer each frame via onRender.

Constructor options

new MeshSimple(options: SimpleMeshOptions)

MeshSimple builds its own MeshGeometry, so geometry is omitted from the options type. Note the option is named vertices here (converted to positions internally), matching the mesh.vertices getter. Other MeshOptions fields (shader, state, roundPixels) are inherited from mesh.md and behave identically.

All Container options (position, scale, tint, label, filters, zIndex, etc.) are also valid here — see skills/pixijs-scene-core-concepts/references/constructor-options.md.

autoUpdate is a runtime property (defaults to true), not a constructor option. Set mesh.autoUpdate = false after construction to suppress the per-frame position-buffer upload.

Core Patterns

Animated vertices

app.ticker.add(() => {
  const verts = triangle.vertices;
  verts[5] = 100 + Math.sin(performance.now() / 500) * 20;
  triangle.vertices = verts;
});

Because autoUpdate defaults to true, assigning to vertices or mutating the array in place is enough; the buffer is pushed to the GPU automatically during the next render pass.

Indexed quad

const quad = new MeshSimple({
  texture,
  vertices: 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]),
});

Indices are optional; omit them and the mesh uses unindexed vertex order. Useful for a small, simple shape where explicit indexing adds no value.

Manual update mode

triangle.autoUpdate = false;

app.ticker.add(() => {
  const verts = triangle.vertices;
  verts[1] = Math.sin(performance.now() / 1000) * 20;
  triangle.vertices = verts;
  triangle.geometry.getBuffer("aPosition").update();
});

Set autoUpdate = false when you want explicit control over when the GPU sees new vertex data; for example, when you only update once per several frames, or when you want to batch multiple vertex mutations before a single upload.

Alternative topologies

const lineStrip = new MeshSimple({
  texture,
  vertices: new Float32Array([0, 0, 50, 50, 100, 0, 150, 50]),
  topology: "line-strip",
});

MeshSimple accepts any topology supported by MeshGeometry ('triangle-list', 'triangle-strip', 'line-list', 'line-strip', 'point-list'). The default is 'triangle-list'.

Common Mistakes

[HIGH] Using the old SimpleMesh name

Wrong:

import { SimpleMesh } from "pixi.js";
const mesh = new SimpleMesh(texture, vertices, uvs, indices);

Correct:

import { MeshSimple } from "pixi.js";
const mesh = new MeshSimple({ texture, vertices, uvs, indices });

SimpleMesh was renamed to MeshSimple in v8. The old name is not exported; the class also switched to an options-object constructor.

[MEDIUM] Forgetting UVs on a textured mesh

Wrong:

const mesh = new MeshSimple({
  texture,
  vertices: new Float32Array([0, 0, 100, 0, 50, 100]),
});

Correct:

const mesh = new MeshSimple({
  texture,
  vertices: new Float32Array([0, 0, 100, 0, 50, 100]),
  uvs: new Float32Array([0, 0, 1, 0, 0.5, 1]),
});

Omitting uvs makes the underlying MeshGeometry fill a zero array, sampling only pixel (0, 0) of the texture. Always provide UVs when you want the texture to map across the geometry.

API Reference

• MeshSimple
• SimpleMeshOptions
• Mesh
• MeshGeometry

Mesh

The base mesh class. Combines a Geometry (vertex positions, UVs, indices, topology) with a Texture or custom Shader to render arbitrary 2D (or perspective-projected) graphics. Use Mesh when you need vertex-level control, custom shaders, or batched draw calls for geometry that doesn't fit the Sprite / Graphics / Particle model.

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

Mesh is a leaf; allowChildren is false. It owns a reference to its geometry (shareable across meshes) and either a texture or a custom shader.

Constructor options

new Mesh<GEOMETRY, SHADER>(options: MeshOptions<GEOMETRY, SHADER>)

All Container options (position, scale, tint, label, filters, zIndex, etc.) are also valid here — see skills/pixijs-scene-core-concepts/references/constructor-options.md.

The constructor assigns texture from shader.texture when a custom shader is passed without an explicit texture option. Passing null/undefined to the texture setter at runtime coerces it to Texture.EMPTY.

Core Patterns

MeshGeometry anatomy

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

• positions: flat x,y pairs in local space.
• uvs: flat u,v pairs in [0, 1] texture space. If omitted, defaults to zero-filled.
• indices: triangle indices. If omitted, defaults to a quad [0, 1, 2, 0, 2, 3].
• topology: how indices are interpreted (see below).

After construction, read or replace the typed arrays via the getters geometry.positions, geometry.uvs, geometry.indices. They return the underlying buffers' data directly; mutating in place is equivalent to mutating getBuffer('aPosition').data.

Topology

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

Five topology types:

Topology is set on the geometry, not the mesh. The default is 'triangle-list'; any other data layout needs an explicit topology or the mesh renders garbage.

Batching

geometry.batchMode = "auto"; // default
geometry.batchMode = "batch"; // always batched
geometry.batchMode = "no-batch"; // never batched

A mesh is batched (combined with other draw calls) only when:

• It uses MeshGeometry (not a custom geometry subclass).
• It has no custom shader.
• Its state has no depth test or culling.
• The 'auto' rule: geometry has 100 or fewer vertices.

Custom shaders always render independently. For large static meshes, set batchMode = 'no-batch' to skip the batch-eligibility check overhead.

Custom shader

import { Shader } from "pixi.js";

const shader = Shader.from({
  gl: { vertex: vertSrc, fragment: fragSrc },
  resources: { uTexture: texture.source, uSampler: texture.source.style },
});

const mesh = new Mesh({ geometry, shader });

When a shader is provided, texture is optional; the shader decides what to sample. Custom shaders bypass batching entirely. See the pixijs-custom-rendering skill for full shader authoring detail.

Shared geometry

const sharedGeom = new MeshGeometry({ positions, uvs, indices });

const mesh1 = new Mesh({ geometry: sharedGeom, texture: tex1 });
const mesh2 = new Mesh({ geometry: sharedGeom, texture: tex2 });

Geometry is reference-counted. Multiple meshes can share one geometry, saving memory for instances that share a shape but differ in transform or texture.

Updating vertices at runtime

mesh.geometry.positions[1] = Math.sin(performance.now() / 500) * 20;
mesh.geometry.getBuffer("aPosition").update();

MeshGeometry exposes positions, uvs, and indices getters that return the underlying Float32Array / Uint32Array directly; they point at the same data as getBuffer('aPosition').data / getBuffer('aUV').data / getIndex().data. Mutate in place for the common case, or assign a whole new array via the setter (the setters do buffer.data = value with no length check; the real invariant is uvs.length >= positions.length so every vertex has a UV).

Call update() on the buffer after mutating its data array to push changes to the GPU. For auto-update behavior, use MeshSimple which handles this for you.

Common Mistakes

[HIGH] Positional constructor args

Wrong:

const mesh = new Mesh(geometry, shader);

Correct:

const mesh = new Mesh({ geometry, shader });

v8 uses an options object. The positional form is deprecated and logs a warning. Note also that the drawMode argument was removed; use geometry.topology instead.

[HIGH] vertices instead of positions

Wrong:

const geometry = new MeshGeometry({
  vertices: new Float32Array([0, 0, 100, 0, 50, 100]),
});

Correct:

const geometry = new MeshGeometry({
  positions: new Float32Array([0, 0, 100, 0, 50, 100]),
});

The MeshGeometry option is positions. vertices is the convenience name used only by MeshSimple, where it's converted internally.

[MEDIUM] Forgetting to set topology

Wrong:

const geometry = new MeshGeometry({
  positions: stripPositions,
  indices: stripIndices,
});

Correct:

const geometry = new MeshGeometry({
  positions: stripPositions,
  indices: stripIndices,
  topology: "triangle-strip",
});

The default topology is 'triangle-list'. If your data is organized as a strip or line list, the mesh renders garbage without an explicit topology.

API Reference

• Mesh
• MeshOptions
• MeshGeometry
• MeshGeometryOptions