@docyrus/animaguru 0.6.0

package/vendor/pixijs-skills/skills/pixijs-scene-mesh/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: pixijs-scene-mesh
+description: "Use this skill when rendering custom geometry in PixiJS v8. Covers Mesh with MeshGeometry (positions, uvs, indices, topology), MeshSimple for per-frame vertex animation, MeshPlane for subdivided deformation, MeshRope for path-following textures, PerspectiveMesh for 2.5D corners. Triggers on: Mesh, MeshGeometry, MeshSimple, MeshPlane, MeshRope, PerspectiveMesh, positions, uvs, indices, topology, setCorners, constructor options, MeshOptions, MeshPlaneOptions, MeshRopeOptions, SimpleMeshOptions, PerspectivePlaneOptions."
+license: MIT
+---
+
+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)

package/vendor/pixijs-skills/skills/pixijs-scene-mesh/references/mesh-perspective.md

@@ -0,0 +1,189 @@
+# 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
+
+```ts
+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`.
+
+| Option      | Type      | Default         | Description                                                                                                           |
+| ----------- | --------- | --------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `texture`   | `Texture` | `Texture.WHITE` | Texture warped onto the quad. Inherited from `MeshPlaneOptions`; also drives the geometry's initial `width`/`height`. |
+| `verticesX` | `number`  | `10`            | Grid columns. More vertices yield smoother perspective at higher draw cost.                                           |
+| `verticesY` | `number`  | `10`            | Grid rows. More vertices yield smoother perspective at higher draw cost.                                              |
+| `x0`        | `number`  | `0`             | Top-left corner x.                                                                                                    |
+| `y0`        | `number`  | `0`             | Top-left corner y.                                                                                                    |
+| `x1`        | `number`  | `100`           | Top-right corner x.                                                                                                   |
+| `y1`        | `number`  | `0`             | Top-right corner y.                                                                                                   |
+| `x2`        | `number`  | `100`           | Bottom-right corner x.                                                                                                |
+| `y2`        | `number`  | `100`           | Bottom-right corner y.                                                                                                |
+| `x3`        | `number`  | `0`             | Bottom-left corner x.                                                                                                 |
+| `y3`        | `number`  | `100`           | Bottom-left corner y.                                                                                                 |
+
+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
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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](https://pixijs.download/release/docs/scene.PerspectiveMesh.html.md)
+- [PerspectivePlaneOptions](https://pixijs.download/release/docs/scene.PerspectivePlaneOptions.html.md)
+- [MeshPlane](https://pixijs.download/release/docs/scene.MeshPlane.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-mesh/references/mesh-plane.md

@@ -0,0 +1,159 @@
+# 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
+
+```ts
+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)`
+
+| Option      | Type      | Default | Description                                                                        |
+| ----------- | --------- | ------- | ---------------------------------------------------------------------------------- |
+| `texture`   | `Texture` | —       | Texture mapped onto the plane. Required; also drives the initial `width`/`height`. |
+| `verticesX` | `number`  | `10`    | Grid columns. Higher values yield smoother deformation at higher draw cost.        |
+| `verticesY` | `number`  | `10`    | Grid rows. Higher values yield smoother deformation at higher draw cost.           |
+
+`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
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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:
+
+```ts
+import { SimplePlane } from "pixi.js";
+const plane = new SimplePlane(texture, 10, 10);
+```
+
+Correct:
+
+```ts
+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:
+
+```ts
+buffer.data[1] = 50;
+```
+
+Correct:
+
+```ts
+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](https://pixijs.download/release/docs/scene.MeshPlane.html.md)
+- [MeshPlaneOptions](https://pixijs.download/release/docs/scene.MeshPlaneOptions.html.md)
+- [PlaneGeometry](https://pixijs.download/release/docs/scene.PlaneGeometry.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-mesh/references/mesh-rope.md

@@ -0,0 +1,176 @@
+# 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
+
+```ts
+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)`
+
+| Option         | Type          | Default          | Description                                                                                                                                                                                                                       |
+| -------------- | ------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `texture`      | `Texture`     | —                | Texture sampled along the rope. Required.                                                                                                                                                                                         |
+| `points`       | `PointData[]` | —                | Ordered path the rope follows. Required. Each entry bends the texture; more points yield smoother curves.                                                                                                                         |
+| `textureScale` | `number`      | `0`              | `0` stretches the texture across the full length. Positive values repeat the texture while preserving aspect ratio and switch the source's `addressMode` to `'repeat'`. Values `< 1` with a larger source reduce alpha artifacts. |
+| `width`        | `number`      | `texture.height` | Rope thickness. Defaults to the texture height when omitted.                                                                                                                                                                      |
+
+`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
+
+```ts
+// 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
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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:
+
+```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 });
+```
+
+`SimpleRope` was renamed to `MeshRope` in v8 and switched to an options-object constructor.
+
+
+### [HIGH] Too few points for a smooth curve
+
+Wrong:
+
+```ts
+const rope = new MeshRope({
+  texture,
+  points: [new Point(0, 0), new Point(400, 0)],
+});
+```
+
+Correct:
+
+```ts
+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](https://pixijs.download/release/docs/scene.MeshRope.html.md)
+- [MeshRopeOptions](https://pixijs.download/release/docs/scene.MeshRopeOptions.html.md)
+- [RopeGeometry](https://pixijs.download/release/docs/scene.RopeGeometry.html.md)