@woosh/meep-engine 2.43.9 → 2.43.12

package/engine/graphics/ecs/path/tube/build/makeTubeGeometry.js

@@ -1,10 +1,10 @@
 import { BufferGeometry, Vector3 } from "three";
-import { GeometryOutput } from "./GeometryOutput.js";
+import { StreamGeometryBuilder } from "./StreamGeometryBuilder.js";
 import { CapType } from "../CapType.js";
 import { make_ring_vertices } from "./make_ring_vertices.js";
 import { assert } from "../../../../../../core/assert.js";
 import { make_ring_faces } from "./make_ring_faces.js";
-import { compute_cap_geometry_size, make_cap } from "./make_cap.js";
+import { append_compute_cap_geometry_size, make_cap } from "./make_cap.js";
 import { v3_angle_cos_between } from "../../../../../../core/geom/v3_angle_between.js";
 
 
@@ -12,6 +12,7 @@ const v4_array = new Float32Array(4);
 
 /**
  * @see https://github.com/mrdoob/three.js/blob/master/src/geometries/TubeGeometry.js
+ * @see https://github.com/hofk/THREEg.js/blob/488f1128a25321a76888aa1fa19db64750318444/THREEg.js#L3483
  * @param {Float32Array|number[]} in_positions
  * @param {Vector3[]} in_normals
  * @param {Vector3[]} in_binormals
@@ -34,7 +35,7 @@ export function makeTubeGeometry(
     assert.isNumber(shape_length, 'shape_length');
     assert.isArrayLike(shape, 'shape');
 
-    const out = new GeometryOutput();
+    const out = new StreamGeometryBuilder();
 
     // helper variables
 
@@ -48,7 +49,7 @@ export function makeTubeGeometry(
     };
 
     if (!closed) {
-        compute_cap_geometry_size(2, geometry_size, shape_length, cap_type);
+        append_compute_cap_geometry_size(2, geometry_size, shape_length, cap_type);
     }
 
     out.allocate(
@@ -57,6 +58,7 @@ export function makeTubeGeometry(
     );
 
     // create buffer data
+
     if (!closed) {
         // start cap
         make_cap(

package/engine/graphics/ecs/path/tube/build/make_cap.js

@@ -50,7 +50,7 @@ function compute_shape_radius(shape, shape_length, cx = 0, cy = 0) {
  * @param {Vector3[]} in_normals
  * @param {Vector3[]} in_binormals
  * @param {Vector3[]} in_tangents
- * @param {GeometryOutput} out
+ * @param {StreamGeometryBuilder} out
  * @param {number[]} shape
  * @param {number[]|Float32Array} shape_normal
  * @param {number} shape_length
@@ -106,9 +106,9 @@ function make_cap_round(
 
     for (i = 0; i <= cap_segment_count; i++) {
 
-        const j = direction>0? i:cap_segment_count-i;
+        const j = direction > 0 ? i : cap_segment_count - i;
 
-        const angle_b = j * angular_step_i ;
+        const angle_b = j * angular_step_i;
 
 
         const cos_b = Math.cos(angle_b);
@@ -151,9 +151,9 @@ const v4_no_bend = new Float32Array([0, 1, 0, 0]);
  * @param {Vector3[]} in_normals
  * @param {Vector3[]} in_binormals
  * @param {Vector3[]} in_tangents
- * @param {GeometryOutput} out
+ * @param {StreamGeometryBuilder} out
  * @param {number[]} shape
- * @param {number[]|Float32Array} shape_normals
+ * @param {number[]|Float32Array} shape_normal
  * @param {number} shape_length
  * @param {number[]} shape_transform
  * @param {number} direction
@@ -211,7 +211,7 @@ function make_cap_flat(
  * @param {Float32Array|number[]} in_positions
  * @param {Vector3[]} in_normals
  * @param {Vector3[]} in_binormals
- * @param {GeometryOutput} out
+ * @param {StreamGeometryBuilder} out
  * @param {Vector3[]} in_tangents
  * @param {number[]} shape
  * @param {number[]|Float32Array} shape_normal
@@ -250,13 +250,13 @@ export function make_cap(
 }
 
 /**
- *
+ * Increases target geometry buffers to accommodate a given number of caps
  * @param {number} count how many caps
- * @param {{polygon_count:number, vertex_count:number}} out
- * @param {number} radial_segments
+ * @param {{polygon_count:number, vertex_count:number}} out where to increment
+ * @param {number} radial_segments number of lines that make up profile of the extruded shape
  * @param {CapType} type
  */
-export function compute_cap_geometry_size(count, out, radial_segments, type) {
+export function append_compute_cap_geometry_size(count, out, radial_segments, type) {
 
     if (type === CapType.None) {
         // do nothing

package/engine/graphics/ecs/path/tube/build/make_ring_faces.js

@@ -1,6 +1,6 @@
 /**
  *
- * @param {GeometryOutput} out
+ * @param {StreamGeometryBuilder} out
  * @param {number} index_offset
  * @param {number} path_segments
  * @param {number} profile_segments

package/engine/graphics/ecs/path/tube/build/make_ring_vertices.js

@@ -4,7 +4,7 @@ import { v3_dot } from "../../../../../../core/geom/v3_dot.js";
 
 /**
  *
- * @param {GeometryOutput} out
+ * @param {StreamGeometryBuilder} out
  * @param {number} Px
  * @param {number} Py
  * @param {number} Pz

package/engine/graphics/impostors/octahedral/shader/ImpostorShaderV0.js

@@ -27,13 +27,28 @@ const shader_vx = `
     out vec3 local_ray_far;
     
     flat out vec2 frame1;
+    flat out vec3 frame1_normal;
     out vec2 uv_frame1;
     out vec2 xy_frame1;
 
+    flat out vec2 frame2;
+    flat out vec3 frame2_normal;
+    out vec2 uv_frame2;
+    out vec2 xy_frame2;
+
+    flat out vec2 frame3;
+    flat out vec3 frame3_normal;
+    out vec2 uv_frame3;
+    out vec2 xy_frame3;
+    
+    out vec4 blend_weights;
+
     uniform mat4 modelViewMatrix;
     uniform mat4 projectionMatrix;
     uniform mat3 normalMatrix;
     uniform mat4 modelMatrix;
+    uniform mat4 viewMatrix;
+    uniform vec3 cameraPosition;
     
     uniform vec3 uOffset;
     uniform float uRadius;
@@ -143,6 +158,16 @@ const shader_vx = `
         return res;
     }
     
+    vec3 projectOnPlaneBasis(vec3 ray, vec3 plane_normal, vec3 plane_x, vec3 plane_y)
+    {
+        //reproject plane normal onto planeXY basos
+        return normalize(vec3(
+        dot(plane_x, ray),
+        dot(plane_y, ray),
+        dot(plane_normal, ray)
+        ));
+    }
+    
     void calcuateXYbasis(vec3 plane_normal, out vec3 plane_x, out vec3 plane_y)
     {
         vec3 up = vec3(0,1,0);
@@ -155,14 +180,56 @@ const shader_vx = `
         plane_y = normalize(cross(plane_x, plane_normal));
     }
    
+    //this function works well in orthogonal projection. It works okeyish with further distances of perspective projection
+    vec2 virtualPlaneUV(vec3 plane_normal, vec3  plane_x, vec3  plane_y, vec3 pivotToCameraRay, vec3 vertexToCameraRay, float size)
+    {
+        plane_normal = normalize(plane_normal);
+        plane_x = normalize(plane_x);
+        plane_y = normalize(plane_y);
+    
+        // plane_normal is normalized but pivotToCameraRay & vertexToCameraRay are NOT
+        // so what are we doing here ?
+        // We are calculating length of pivotToCameraRay projected onto plane_normal
+        // so pivotToCameraRay is vector to camera from CENTER OF object
+        // we are recalculting this distance taking into account new plane normal
+        float projectedNormalRayLength = dot(plane_normal, pivotToCameraRay);
+        // tihs is direction is almost the same as origin, but its to individual vertex
+        // not sure this is correct for perspective projection
+        float projectedVertexRayLength = dot(plane_normal, vertexToCameraRay);
+        // basically its length difference betwen center and vertex - "not precise"
+        // projectedVertexRayLength is bigger than projectedNormalRayLength when vertex is
+        // further than "main front facing billboard"
+        // so offsetLength is getting smaller, otherwise is getting bigger
+        float offsetLength = projectedNormalRayLength/projectedVertexRayLength;
+    
+        // ok so offsetLength is just a length
+        // we want a vector so we multiply it by vertexToCameraRay to get this offset
+        // now what are we REALY doing is calculuating distance difference
+        // se are SUBSTRACTING pivotToCameraRay vector
+        // we would get difference between center of plane and vertex rotated
+        vec3 offsetVector = vertexToCameraRay * offsetLength - pivotToCameraRay;
+    
+        // we got the offset of rotated vertex, but we need to offset it from correct plane axis
+        // so again we projecting length of intersection (offset of rotated vertex) onto plane_x
+        // and plane_y
+        vec2 duv = vec2(
+        dot(plane_x, offsetVector),
+        dot(plane_y, offsetVector)
+        );
+    
+        //we are in space -1 to 1
+        duv /= 2.0 * size;
+        duv += 0.5;
+        return duv;
+    }
     
     void main() {
         vUv = uv;
         
         vec2 framesMinusOne = uFrames - vec2(1.0);
         
-        vec3 cameraPos_WS = (projectionMatrix * vec4(vec3(0), 1.0)).xyz;
-        vec3 cameraPos_OS = (inverse(modelMatrix) * vec4(cameraPos_WS, 1.0)).xyz;
+        vec3 cameraPos_WS = cameraPosition;
+        vec3 cameraPos_OS = (inverse(viewMatrix) * vec4(cameraPos_WS, 1.0)).xyz;
         
         //TODO: check if this is correct. We are using orho projected images, so
         // camera far away
@@ -206,7 +273,7 @@ const shader_vx = `
         //get 2D projection of this vertex in normalized device coordinates
         vec2 pos = gl_Position.xy/gl_Position.w;
        
-        vec3 projected = position;
+        vec3 projected = object_scale*position;
         vec3 vertexToCameraRay = (pivotToCameraRay - (projected));
         vec3 vertexToCameraDir = normalize(vertexToCameraRay);
        
@@ -221,25 +288,44 @@ const shader_vx = `
         //
         vec3 view_direction = normalize(local_ray_near-local_ray_far);
         
-        vec2 octahedral_uv = clamp(VectorToGrid(view_direction)*0.5 + 0.5, 0.0, 1.0);
-        vec2 grid =  octahedral_uv * vec2(uFrames - 1.0);
+        vec2 grid = VectorToGrid(-view_direction);
+        //bias and scale to 0 to 1
+        grid = clamp((grid + 1.0) * 0.5, vec2(0, 0), vec2(1, 1));
+        grid *= framesMinusOne;
+        grid = clamp(grid, vec2(0), vec2(framesMinusOne));
+        vec2 gridFloor = min(floor(grid), framesMinusOne);
+        vec2 gridFract = fract(grid);
         
-        vec2 gridFrac = fract(grid);
-        vec2 gridFloor = floor(grid);
+        blend_weights = TriangleInterpolate( gridFract ); 
         
-        vec4 weights = TriangleInterpolate( gridFrac ); 
+        frame1 = gridFloor;  
+        frame2 = gridFloor + mix(vec2(0,1),vec2(1,0),blend_weights.w);
+        frame3 = gridFloor + vec2(1.0,1.0);
         
-        vec2 frame1 = gridFloor;  
-        vec2 frame2 = gridFloor + mix(vec2(0,1),vec2(1,0),weights.w);
-        vec2 frame3 = gridFloor + vec2(1.0,1.0);
+        vec3 projectedQuadADir = FrameXYToRay(frame1, framesMinusOne);
+        vec3 projectedQuadBDir = FrameXYToRay(frame2, framesMinusOne);
+        vec3 projectedQuadCDir = FrameXYToRay(frame3, framesMinusOne);
+        
+        frame1_normal = (modelViewMatrix *vec4(projectedQuadADir, 0)).xyz;
+        frame2_normal = (modelViewMatrix *vec4(projectedQuadBDir, 0)).xyz;
+        frame3_normal = (modelViewMatrix *vec4(projectedQuadCDir, 0)).xyz;
         
         vec3 plane_x1, plane_y1, plane_x2, plane_y2, plane_x3, plane_y3;
-        vec3 projectedQuadADir = FrameXYToRay(frame1, framesMinusOne);
+        
         calcuateXYbasis(projectedQuadADir, plane_x1, plane_y1);
         
-        uv_frame1 = virtualPlaneUV(projectedQuadADir, plane_x1, plane_y1, pivotToCameraRay, vertexToCameraRay, scale);
+        uv_frame1 = virtualPlaneUV(projectedQuadADir, plane_x1, plane_y1, pivotToCameraRay, vertexToCameraRay, uRadius);
 	    xy_frame1 = projectOnPlaneBasis(-vertexToCameraDir, projectedQuadADir, plane_x1, plane_y1).xy;
+
+        calcuateXYbasis(projectedQuadBDir, plane_x2, plane_y2);
+        uv_frame2 = virtualPlaneUV(projectedQuadBDir, plane_x2, plane_y2, pivotToCameraRay, vertexToCameraRay, uRadius);
+        xy_frame2 = projectOnPlaneBasis(-vertexToCameraDir, projectedQuadBDir, plane_x2, plane_y2).xy;
         
+        calcuateXYbasis(projectedQuadCDir, plane_x3, plane_y3);
+        uv_frame3 = virtualPlaneUV(projectedQuadCDir, plane_x3, plane_y3, pivotToCameraRay, vertexToCameraRay, uRadius);
+        xy_frame3 = projectOnPlaneBasis(-vertexToCameraDir, projectedQuadCDir, plane_x3, plane_y3).xy;
+
+
     }
 `;
 const shader_fg = `
@@ -269,6 +355,23 @@ const shader_fg = `
     in vec3 local_ray_near;
     in vec3 local_ray_far;
     
+    flat in vec2 frame1;
+    flat in vec3 frame1_normal;
+    in vec2 uv_frame1;
+    in vec2 xy_frame1;
+
+    flat in vec2 frame2;
+    flat in vec3 frame2_normal;
+    in vec2 uv_frame2;
+    in vec2 xy_frame2;
+
+    flat in vec2 frame3;
+    flat in vec3 frame3_normal;
+    in vec2 uv_frame3;
+    in vec2 xy_frame3;
+    
+    in vec4 blend_weights;
+    
     struct Material{
         vec3 diffuse;
         vec3 normal;
@@ -394,14 +497,14 @@ const shader_fg = `
         ));
     }
     
-    vec2 recompute_uv(vec2 frame, vec2 frame_uv, sampler2D gBuffer){
+    vec2 recompute_uv(vec2 frame, vec2 frame_uv, vec2 xy_f, sampler2D gBuffer){
         vec2 frame_size = vec2(1.0/ uFrames);
         
         vec2 source_uv = (frame + frame_uv)*frame_size;
         
         float n_depth = texture(gBuffer, source_uv).a;
             
-        vec2 offset = clamp(length(frame_uv*2.0 - 1.0) * vec2(0.5-n_depth ) * depth_scale,0.0, 1.0);
+        vec2 offset = clamp(xy_f * vec2(0.5-n_depth ) * depth_scale,0.0, 1.0);
         
         vec2 uv_f = clamp(frame_uv+offset, 0.0, 1.0);
         
@@ -411,6 +514,21 @@ const shader_fg = `
         // return source_uv;
     }
     
+    vec2 recalculateUV(vec2 uv_f,  vec2 frame, vec2 xy_f, vec2 frame_size, float d_scale, sampler2D depthTexture)
+    {
+        //clamp for parallax sampling
+        uv_f = clamp(uv_f, vec2(0.0), vec2(1.0));
+        vec2 uv_quad = frame_size * (frame + uv_f);
+        //paralax
+        vec4 n_depth = (texture( depthTexture, uv_quad));
+        uv_f = xy_f * (0.5-n_depth.a) * d_scale + uv_f;
+        //clamp parallax offset
+        uv_f = clamp(uv_f, vec2(0.0), vec2(1.0));
+        uv_f =  frame_size * (frame + uv_f);
+        //clamped full UV
+        return clamp(uv_f, vec2(0.0), vec2(1.0));
+    }
+    
     void main(){
         vec3 view_direction = normalize(local_ray_near-local_ray_far);
         
@@ -420,19 +538,17 @@ const shader_fg = `
         vec2 gridFrac = fract(grid);
         vec2 gridFloor = floor(grid);
                 
-        vec4 weights = TriangleInterpolate( gridFrac ); 
+        vec4 weights = blend_weights; 
         
         vec2 frame_uv = vUv;
         
         //3 nearest frames
-        vec2 frame0 = gridFloor;
-        vec2 frame1 = gridFloor + mix(vec2(0,1),vec2(1,0),weights.w);
-        vec2 frame2 = gridFloor + vec2(1.0,1.0);
-        
-        vec2 uv0 = recompute_uv(frame0, frame_uv, tGeometry);
-        vec2 uv1 = recompute_uv(frame1, frame_uv, tGeometry);
-        vec2 uv2 = recompute_uv(frame2, frame_uv, tGeometry);
-        
+        vec2 quad_size = vec2(1.0) / uFrames;
+        vec2 uv_f1 = recalculateUV(uv_frame1, frame1, xy_frame1, quad_size, depth_scale, tGeometry);
+        vec2 uv_f2 = recalculateUV(uv_frame2, frame2, xy_frame2, quad_size, depth_scale, tGeometry);
+        vec2 uv_f3 = recalculateUV(uv_frame3, frame3, xy_frame3, quad_size, depth_scale, tGeometry);
+    
+            
         vec4 ddxy = vec4( dFdx(vUv.xy), dFdy(vUv.xy) );
         
         vec2 frame_size = vec2(1.0/ uFrames);
@@ -440,9 +556,9 @@ const shader_fg = `
         vec4 texel_color = ImposterBlendWeights(
         // vec4 texel_color = ImposterBlendWeightsNearest(
             tBase,
-            uv0,
-            uv1,
-            uv2,
+            uv_f1,
+            uv_f2,
+            uv_f3,
             weights, ddxy
         );
         

package/engine/graphics/micron/plugin/shaded_geometry/MicronShadedGeometryRenderAdapter.js

@@ -139,6 +139,10 @@ export class MicronShadedGeometryRenderAdapter extends AbstractRenderAdapter {
 
         scratch_mvc.material = sg.material;
         scratch_mvc.spec = micron_geometry.vertex_spec;
+
+        // clear all flags
+        scratch_mvc.flags = 0;
+
         scratch_mvc.writeFlag(MaterialVertexSpecFlags.CastShadow, sg.getFlag(ShadedGeometryFlags.CastShadow));
         scratch_mvc.writeFlag(MaterialVertexSpecFlags.ReceiveShadow, sg.getFlag(ShadedGeometryFlags.ReceiveShadow));
 
@@ -175,6 +179,7 @@ export class MicronShadedGeometryRenderAdapter extends AbstractRenderAdapter {
         //  clear context
         const material_contexts = this.ctx.contexts_array;
         const contexts_count = material_contexts.length;
+
         for (let i = 0; i < contexts_count; i++) {
             const mc = material_contexts[i];
 

package/engine/graphics/particles/particular/engine/utils/volume/ParticleVolume.d.ts

@@ -1,13 +1,15 @@
 import EntityBuilder from "../../../../../../ecs/EntityBuilder";
 import {AbstractShape3D} from "../../../../../../../core/geom/3d/shape/AbstractShape3D";
 import {AttributeValue} from "./AttributeValue";
+import {SamplingFunctionKind} from "./SamplingFunctionKind";
 
 interface Args {
     density?: number
     particle_size?: number
     shape?: AbstractShape3D
     sort?: boolean
-    sprite?: string
+    sprite?: string,
+    sampling_function?: SamplingFunctionKind
 }
 
 interface Attributes {

package/engine/graphics/particles/particular/engine/utils/volume/ParticleVolume.js

@@ -12,6 +12,10 @@ import { PARTICULAR_PARTICLE_SPECIFICATION } from "../../emitter/PARTICULAR_PART
 import { SerializationMetadata } from "../../../../../../ecs/components/SerializationMetadata.js";
 import { UnitCubeShape3D } from "../../../../../../../core/geom/3d/shape/UnitCubeShape3D.js";
 import { shape_from_json } from "../../../../../../../core/geom/3d/shape/json/shape_from_json.js";
+import { min2 } from "../../../../../../../core/math/min2.js";
+import { max2 } from "../../../../../../../core/math/max2.js";
+import { SamplingFunctionKind } from "./SamplingFunctionKind.js";
+import { assert } from "../../../../../../../core/assert.js";
 
 const DEFAULT_ATTRIBUTE_VALUES = {
     color: [1, 1, 1, 1],
@@ -32,6 +36,12 @@ const EXPOSED_ATTRIBUTES = [
     "blending"
 ];
 
+/**
+ * Maximum allowed number of particles per emitter, used as a sanity constraint to prevent renderer from crashing
+ * @type {number}
+ */
+const LIMIT_PARTICLE_COUNT = 1000000;
+
 export class ParticleVolume {
 
     constructor() {
@@ -176,6 +186,13 @@ export class ParticleVolume {
          */
         this.__shape = new UnitCubeShape3D();
 
+        /**
+         *
+         * @type {SamplingFunctionKind|number}
+         * @private
+         */
+        this.__sampling_function = SamplingFunctionKind.Random;
+
         const eb = new EntityBuilder();
 
         eb.add(this.__emitter)
@@ -254,6 +271,7 @@ export class ParticleVolume {
      * @param {boolean} sort
      * @param {boolean} lighting
      * @param {string} [sprite]
+     * @param {SamplingFunctionKind|number} [sampling_function]
      */
     from({
              density = 1,
@@ -261,12 +279,17 @@ export class ParticleVolume {
              shape = new UnitCubeShape3D(),
              sort = false,
              lighting = true,
-             sprite = "data/textures/particle/smokeparticle.png"
+             sprite = "data/textures/particle/smokeparticle.png",
+             sampling_function = SamplingFunctionKind.Random
          } = {}) {
 
+        assert.enum(sampling_function, SamplingFunctionKind, 'sampling_function');
+
         this.__density = density;
         this.__shape = shape;
 
+        this.__sampling_function = sampling_function;
+
         const emitter = this.__emitter;
 
         emitter.writeFlag(ParticleEmitterFlag.DepthSorting, sort);
@@ -289,6 +312,7 @@ export class ParticleVolume {
      * @param {boolean} [is_lit]
      * @param {string} sprite
      * @param {Object<Object>} [attributes]
+     * @param {string} [sampling_function]
      */
     fromJSON({
                  density,
@@ -298,20 +322,28 @@ export class ParticleVolume {
                  is_sorted = true,
                  is_lit = true,
                  sprite,
-                 attributes = {}
+                 attributes = {},
+                 sampling_function = 'Random'
              }) {
 
         const shape_object = shape_from_json(shape);
 
         const actual_density = is_density_size_adjusted ? density / particle_size : density;
 
+        const sf_type = SamplingFunctionKind[sampling_function];
+
+        if (sf_type === undefined) {
+            throw new Error(`Unsupported sampling function type '${sampling_function}', valid values:[${Object.keys(SamplingFunctionKind).join(', ')}]`);
+        }
+
         this.from({
             density: actual_density,
             shape: shape_object,
             particle_size,
             sort: is_sorted,
             lighting: is_lit,
-            sprite
+            sprite,
+            sampling_function: sf_type
         });
 
         // parse attributes
@@ -347,12 +379,118 @@ export class ParticleVolume {
 
     }
 
+    __distribute_grid() {
+        const emitter = this.__emitter;
+        const particles = emitter.particles;
+
+        const layer = emitter.layers.get(0);
+
+        // build transform matrix
+        const m4_transform = new Matrix4();
+
+        const t = this.__transform;
+
+        composeMatrix4(m4_transform, t.position, t.rotation, t.scale);
+
+        const m4_layer = new Matrix4();
+
+        composeMatrix4(m4_layer, layer.position, new Quaternion(), layer.scale);
+
+        const v3_position = [];
+
+        const m4_final = new Matrix4();
+
+        m4_final.multiplyMatrices(m4_transform, m4_layer);
+
+
+        // cache variables to save a bit on de-referencing
+        const matrix_elements = m4_final.elements;
+        const shape = this.__shape;
+
+        const ts = shape;
+
+        const bounding_box = [];
+
+        ts.compute_bounding_box(bounding_box);
+
+        const density_step = 1 / Math.pow(this.__density, 1 / 3);
+
+        let particle_index = 0;
+
+        // apply margin to the space, this will shrink the grid spacing to align particles more evenly within the bounding volume
+        const density_margin = density_step * 0.5;
+
+        const mid_x = (bounding_box[3] + bounding_box[0]) * 0.5;
+        const mid_y = (bounding_box[4] + bounding_box[1]) * 0.5;
+        const mid_z = (bounding_box[5] + bounding_box[2]) * 0.5;
+
+        const x0 = min2(mid_x, bounding_box[0] + density_margin);
+        const x1 = max2(mid_x, bounding_box[3] - density_margin);
+
+        const y0 = min2(mid_y, bounding_box[1] + density_margin);
+        const y1 = max2(mid_y, bounding_box[4] - density_margin);
+
+        const z0 = min2(mid_z, bounding_box[2] + density_margin);
+        const z1 = max2(mid_z, bounding_box[5] - density_margin);
+
+        main_loop:for (let x = x0; x <= x1; x += density_step) {
+            for (let y = y0; y <= y1; y += density_step) {
+                for (let z = z0; z <= z1; z += density_step) {
+
+                    v3_position[0] = x;
+                    v3_position[1] = y;
+                    v3_position[2] = z;
+
+                    if (ts.contains_point(v3_position)) {
+
+                        vec3.transformMat4(v3_position, v3_position, matrix_elements);
+
+                        particles.writeAttributeVector3(particle_index, PARTICLE_ATTRIBUTE_POSITION, v3_position[0], v3_position[1], v3_position[2]);
+
+                        particle_index++;
+
+                        if (particle_index >= particles.capacity) {
+                            break main_loop;
+                        }
+                    }
+                }
+            }
+        }
+
+        if (particle_index < particles.capacity) {
+            // crop out remaining particles in the pool
+            particles.occupancy.clearRange(particle_index, particles.capacity);
+            particles.update();
+        }
+
+        // request bounds update
+        emitter.setFlag(ParticleEmitterFlag.ParticleBoundsNeedUpdate);
+        emitter.computeBoundingBox();
+    }
+
+    /**
+     *
+     * @param {function} random
+     * @private
+     */
+    __distribute(random) {
+        const sf = this.__sampling_function;
+
+        if (sf === SamplingFunctionKind.Random) {
+            this.__distribute_random(random);
+        } else if (sf === SamplingFunctionKind.Grid) {
+            this.__distribute_grid();
+        } else {
+            throw new Error(`Unsupported sampling function '${sf}'`);
+        }
+    }
+
     /**
      * Distribute particles in the volume
      * @param {function():number} random
      * @private
      */
-    __distribute(random) {
+    __distribute_random(random) {
         const emitter = this.__emitter;
         const particles = emitter.particles;
         const particle_count = particles.size();
@@ -436,8 +574,13 @@ export class ParticleVolume {
         const volume_value = this.__shape.volume;
 
         // total particle count
-        const particle_count = Math.max(1, Math.ceil(volume_value * this.__density));
+        let particle_count = Math.max(1, Math.ceil(volume_value * this.__density));
 
+        if (particle_count > LIMIT_PARTICLE_COUNT) {
+            console.warn(`ParticleVolume exceeds maximum allowed particle count (limit=${LIMIT_PARTICLE_COUNT}, requested=${particle_count}), clamping to limit. Consider reducing density (current = ${this.__density} particles per unit of volume)`);
+
+            particle_count = LIMIT_PARTICLE_COUNT;
+        }
 
         this.__ensure_initialized();
 

package/engine/graphics/particles/particular/engine/utils/volume/SamplingFunctionKind.d.ts

@@ -0,0 +1,4 @@
+export enum SamplingFunctionKind {
+    Random = 0,
+    Grid = 1
+}

package/engine/graphics/particles/particular/engine/utils/volume/SamplingFunctionKind.js

@@ -0,0 +1,8 @@
+/**
+ * @readonly
+ * @enum {number}
+ */
+export const SamplingFunctionKind = {
+    Random: 0,
+    Grid: 1
+};