Add Trail renderable with gradient support (#1368)

README.md

@@ -56,6 +56,7 @@ Graphics
 - Compressed texture support (DDS, KTX, KTX2, PVR, PKM) with automatic format detection and fallback
 - 3D mesh rendering with OBJ/MTL model loading, perspective projection and hardware depth testing
 - Built-in shader effects (Flash, Outline, Glow, Dissolve, CRT, Hologram, etc.) and custom shader support via `ShaderEffect` for per-sprite fragment effects (WebGL)
+- Trail renderable for fading, tapering ribbons behind moving objects (speed lines, sword slashes, magic trails)
 - System & Bitmap Text
 - Video sprite playback
 
@@ -158,6 +159,7 @@ Examples
 * [Compressed Textures](https://melonjs.github.io/melonJS/examples/#/compressed-textures) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/compressedTextures))
 * [3D Mesh](https://melonjs.github.io/melonJS/examples/#/mesh-3d) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/mesh3d))
 * [3D Mesh Material](https://melonjs.github.io/melonJS/examples/#/mesh-3d-material) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/mesh3dMaterial))
+* [Trail](https://melonjs.github.io/melonJS/examples/#/trail) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/trail))
 * [Shader Effects](https://melonjs.github.io/melonJS/examples/#/shader-effects) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/shaderEffects))
 * [Spine](https://melonjs.github.io/melonJS/examples/#/spine) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/spine))
 

package.json

@@ -29,13 +29,13 @@
 		"@vitest/browser-playwright": "^4.1.4",
 		"eslint": "^10.2.0",
 		"eslint-plugin-jsdoc": "^62.9.0",
-		"globals": "^17.4.0",
+		"globals": "^17.5.0",
 		"lefthook": "^2.1.5",
 		"tsconfig": "workspace:^",
 		"tsx": "^4.21.0",
 		"turbo": "^2.9.6",
 		"typescript": "^6.0.2",
-		"typescript-eslint": "^8.58.1",
+		"typescript-eslint": "^8.58.2",
 		"vitest": "^4.1.4"
 	},
 	"devDependencies": {
@@ -53,8 +53,8 @@
 			"minimatch@<4.0.0": "3.1.4",
 			"minimatch@>=9.0.0 <9.0.7": "9.0.7",
 			"ajv@<6.14.0": "6.14.0",
-			"vite": "8.0.3",
-			"esbuild": "0.27.4"
+			"vite": "8.0.8",
+			"esbuild": "0.28.0"
 		}
 	}
 }

packages/examples/package.json

@@ -17,11 +17,11 @@
 		"@vitejs/plugin-react": "^6.0.1",
 		"ace-builds": "^1.43.6",
 		"melonjs": "workspace:^",
-		"react": "^19.2.4",
-		"react-dom": "^19.2.4",
-		"react-router-dom": "^7.13.2",
+		"react": "^19.2.5",
+		"react-dom": "^19.2.5",
+		"react-router-dom": "^7.14.1",
 		"tsconfig": "workspace:^",
 		"typescript": "^6.0.2",
-		"vite": "8.0.0"
+		"vite": "8.0.8"
 	}
 }

packages/examples/src/examples/trail/ExampleTrail.tsx

@@ -0,0 +1,77 @@
+import {
+	Application,
+	ColorLayer,
+	loader,
+	Sprite,
+	Trail,
+	Vector2d,
+	video,
+} from "melonjs";
+import { createExampleComponent } from "../utils";
+import monsterImg from "./assets/monster.png";
+
+class Monster extends Sprite {
+	elapsed: number;
+	lastX: number;
+
+	constructor(x: number, y: number) {
+		super(x, y, {
+			image: "monster",
+			anchorPoint: new Vector2d(0.5, 0.5),
+		});
+		this.scale(0.25);
+		this.alwaysUpdate = true;
+		this.elapsed = 0;
+		this.lastX = x;
+	}
+
+	override update(dt: number): boolean {
+		this.elapsed += dt;
+		const t = this.elapsed / 2000;
+		this.pos.x = 609 + Math.sin(t) * 350;
+		this.pos.y = 281 + Math.sin(t * 2) * 150;
+		this.flipX(this.pos.x > this.lastX);
+		this.lastX = this.pos.x;
+		return super.update(dt);
+	}
+}
+
+const createGame = () => {
+	const app = new Application(1218, 562, {
+		parent: "screen",
+		scale: "auto",
+		renderer: video.AUTO,
+		backgroundColor: "#101020",
+	});
+
+	loader.preload([{ name: "monster", type: "image", src: monsterImg }], () => {
+		app.world.addChild(new ColorLayer("bg", "#101020"), 0);
+
+		const monster = new Monster(609, 281);
+
+		const trail = new Trail({
+			target: monster,
+			length: 60,
+			lifetime: 2000,
+			minDistance: 8,
+			width: 60,
+			widthCurve: [1, 0.95, 0.85, 0.7, 0.5, 0.25, 0],
+			gradient: [
+				"#ff0000",
+				"#ff8800",
+				"#ffff00",
+				"#00ff00",
+				"#0088ff",
+				"#8800ff",
+				"#8800ff00",
+			],
+			opacity: 0.8,
+			blendMode: "additive",
+		});
+
+		app.world.addChild(trail, 1);
+		app.world.addChild(monster, 2);
+	});
+};
+
+export const ExampleTrail = createExampleComponent(createGame);

packages/examples/src/main.tsx

@@ -118,6 +118,11 @@ const ExampleSprite = lazy(() =>
 		default: m.ExampleSprite,
 	})),
 );
+const ExampleTrail = lazy(() =>
+	import("./examples/trail/ExampleTrail").then((m) => ({
+		default: m.ExampleTrail,
+	})),
+);
 const ExampleSVGShapes = lazy(() =>
 	import("./examples/svgShapes/ExampleSVGShapes").then((m) => ({
 		default: m.ExampleSVGShapes,
@@ -311,6 +316,14 @@ const examples: {
 		description:
 			"Displaying and transforming sprites with scaling, rotation, and alpha blending.",
 	},
+	{
+		component: <ExampleTrail />,
+		label: "Trail",
+		path: "trail",
+		sourceDir: "trail",
+		description:
+			"Trail renderable that draws a fading, tapering ribbon behind a moving sprite.",
+	},
 	{
 		component: <ExampleSpine />,
 		label: "Spine Animation",

packages/melonjs/CHANGELOG.md

@@ -18,6 +18,11 @@
 - WebGL: `IndexBuffer.addRaw(indices)` for adding pre-computed absolute indices without rebasing
 - Canvas: degenerate UV triangle support — solid color fill sampled from texture for color-palette models (e.g. Kenney)
 - WebGL: 15 built-in `ShaderEffect` presets for per-sprite visual effects — `FlashEffect`, `OutlineEffect`, `GlowEffect`, `DesaturateEffect`, `PixelateEffect`, `BlurEffect`, `ChromaticAberrationEffect`, `DissolveEffect`, `DropShadowEffect`, `ScanlineEffect` (with optional CRT curvature/vignette), `TintPulseEffect`, `WaveEffect`, `InvertEffect`, `SepiaEffect`, `HologramEffect`. All extend `ShaderEffect` and are disabled in Canvas mode.
+- Renderable: `Trail` class for drawing fading, tapering ribbons behind moving objects — auto-follow or manual point mode, configurable width/gradient/lifetime, works on both WebGL and Canvas
+- Gradient: `getColorAt(position, out)` — interpolate a color at any position along a gradient, useful for procedural effects
+- Gradient: `destroy()` — release pooled resources held by a gradient instance
+- Math: `lerpArray(values, position)` — linearly interpolate a value from an evenly spaced array at a given 0–1 position
+- Math: `computeVertexNormal(points, index, out)` — compute the averaged perpendicular normal at a vertex in a 2D polyline
 
 ### Changed
 - **BREAKING**: `Renderable.currentTransform` is now a `Matrix3d` (was `Matrix2d`) — enables 3D transforms on any renderable. Code that accesses `currentTransform.val` indices directly must update: translation is at `[12],[13]` (was `[6],[7]`)

packages/melonjs/package.json

@@ -60,18 +60,18 @@
 	},
 	"devDependencies": {
 		"@types/howler": "^2.2.12",
-		"@types/node": "^25.5.2",
+		"@types/node": "^25.6.0",
 		"concurrently": "^9.2.1",
 		"del-cli": "^7.0.0",
 		"esbuild": "^0.27.3",
 		"serve": "^14.2.6",
 		"tsconfig": "workspace:^",
 		"tsx": "^4.21.0",
 		"type-fest": "^5.5.0",
-		"typedoc": "^0.28.18",
+		"typedoc": "^0.28.19",
 		"typescript": "^6.0.2",
-		"vite": "8.0.3",
-		"vite-plugin-glsl": "^1.5.6"
+		"vite": "8.0.8",
+		"vite-plugin-glsl": "^1.6.0"
 	},
 	"scripts": {
 		"dev": "concurrently --raw \"pnpm build:watch\" \"pnpm tsc:watch\" \"pnpm doc:watch\"",