@newkrok/three-particles 2.12.0 → 2.13.0

package/llms-full.txt

@@ -338,6 +338,8 @@ type Renderer = {
   depthTest: boolean;                   // Default: true
   depthWrite: boolean;                  // Default: false
   rendererType?: RendererType;          // Default: RendererType.POINTS
+  trail?: TrailConfig;                  // Only for RendererType.TRAIL
+  mesh?: MeshConfig;                    // Only for RendererType.MESH
 };
 
 enum RendererType {
@@ -348,11 +350,45 @@ enum RendererType {
   TRAIL = 'TRAIL',         // Ribbon trails behind particles. Each particle records a position
                             // history and the renderer builds a camera-facing triangle-strip
                             // ribbon through those samples.
+  MESH = 'MESH',           // 3D mesh particles via GPU instancing. Each particle is rendered
+                            // as a full 3D mesh with quaternion-based rotation, normals, and
+                            // directional lighting. Any THREE.BufferGeometry can be used.
 }
+
+type MeshConfig = {
+  geometry: THREE.BufferGeometry;  // The geometry to render for each particle
+};
 ```
 
 Common blending modes: `THREE.NormalBlending`, `THREE.AdditiveBlending`, `THREE.SubtractiveBlending`
 
+### Mesh Particle Configuration
+
+When using `RendererType.MESH`, configure mesh-specific properties via `renderer.mesh`:
+
+```typescript
+renderer: {
+  rendererType: RendererType.MESH,
+  blending: THREE.NormalBlending,
+  transparent: true,
+  depthTest: true,
+  depthWrite: true,
+  mesh: {
+    geometry: new THREE.BoxGeometry(1, 1, 1),
+  },
+}
+```
+
+Mesh particle features:
+- GPU instancing (`InstancedBufferGeometry`) — one draw call for all particles
+- Quaternion-based 3D rotation (particles rotate in all 3 axes)
+- Normals preserved from the source geometry, simple directional lighting from camera
+- Any `THREE.BufferGeometry` works: `BoxGeometry`, `SphereGeometry`, `IcosahedronGeometry`, custom meshes, etc.
+- All modifiers work: sizeOverLifetime, colorOverLifetime, opacityOverLifetime, rotationOverLifetime, noise, force fields, sub-emitters
+- Default texture: solid white 1×1 (preserves mesh shape); point/billboard renderers default to a circle texture
+- Sub-emitter note: sub-emitters do not inherit `RendererType.MESH` or `RendererType.TRAIL` from the parent because mesh geometry and trail config cannot be passed through; sub-emitters fall back to their own `rendererType` or `POINTS` by default
+- Note: `mesh.geometry` is a runtime object (not serializable to JSON); provide it programmatically
+
 ### Trail / Ribbon Configuration
 
 When using `RendererType.TRAIL`, configure trail-specific properties via `renderer.trail`:
@@ -484,7 +520,7 @@ const system = createParticleSystem({
 `BEZIER` | `EASING`
 
 ### RendererType
-`POINTS` (default — classic point sprites) | `INSTANCED` (GPU instanced quads, no gl_PointSize limit)
+`POINTS` (default — classic point sprites) | `INSTANCED` (GPU instanced quads, no gl_PointSize limit) | `TRAIL` (ribbon trails behind particles) | `MESH` (3D mesh particles via GPU instancing)
 
 ---
 

package/llms.txt

@@ -76,6 +76,26 @@ function animate() {
 - `RendererType.POINTS` (default) — Classic point sprites via `THREE.Points`
 - `RendererType.INSTANCED` — Camera-facing quads via `InstancedBufferGeometry`, removes `gl_PointSize` hardware limit
 - `RendererType.TRAIL` — Ribbon trails behind particles with configurable width, opacity, and color tapering
+- `RendererType.MESH` — Render each particle as a 3D mesh (cubes, spheres, custom geometry) via GPU instancing with quaternion-based 3D rotation and directional lighting. Uses solid white default texture (not circle) to preserve mesh shape. Sub-emitters do not inherit MESH or TRAIL rendererType from parent
+
+## Mesh Particle Renderer
+
+Configure via `renderer.mesh`:
+
+```typescript
+renderer: {
+  rendererType: RendererType.MESH,
+  blending: THREE.NormalBlending,
+  transparent: true,
+  depthTest: true,
+  depthWrite: true,
+  mesh: {
+    geometry: new THREE.BoxGeometry(1, 1, 1), // Any THREE.BufferGeometry
+  },
+}
+```
+
+Mesh particles use GPU instancing (`InstancedBufferGeometry`). Each particle is a full 3D mesh with quaternion rotation, normals, and UVs preserved. All modifiers (sizeOverLifetime, colorOverLifetime, noise, force fields, sub-emitters) work with mesh particles.
 
 ## Trail / Ribbon Renderer
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newkrok/three-particles",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "type": "module",
   "description": "Three.js-based high-performance particle system library designed for creating visually stunning particle effects with ease. Perfect for game developers and 3D applications.",
   "main": "./dist/index.js",