wgpu-kit 1.0.3 → 1.1.1

package/dist/packs/grid/index.js

@@ -0,0 +1,187 @@
+import { GpuContext } from "../../core/context.js";
+import { Buffer } from "../../core/buffer.js";
+import { CompileError } from "../../core/errors.js";
+const WG = 64;
+const SCAN = 256;
+const USIZE = 32;
+export async function createNeighborGrid(config) {
+    const { count, worldHalf, cellSize, workgroupSize = WG } = config;
+    if (!Number.isInteger(count) || count <= 0)
+        throw new Error(`count must be a positive integer, got ${String(count)}`);
+    if (!(cellSize > 0))
+        throw new Error(`cellSize must be positive, got ${String(cellSize)}`);
+    const gridSize = Math.max(1, Math.ceil((2 * worldHalf) / cellSize));
+    const cells = gridSize * gridSize;
+    const ctx = await GpuContext.get();
+    const device = ctx.device;
+    const uniform = device.createBuffer({ size: USIZE, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, label: 'ngrid-params' });
+    const writeUniform = () => {
+        const b = new ArrayBuffer(USIZE);
+        const v = new DataView(b);
+        v.setUint32(0, count, true);
+        v.setUint32(4, 0, true);
+        v.setFloat32(8, worldHalf, true);
+        v.setUint32(12, gridSize, true);
+        v.setUint32(16, cells, true);
+        v.setUint32(20, 0, true);
+        v.setUint32(24, 0, true);
+        v.setUint32(28, 0, true);
+        device.queue.writeBuffer(uniform, 0, b);
+    };
+    writeUniform();
+    const cellCount = await Buffer.create('u32', cells);
+    const cellStart = await Buffer.create('u32', cells);
+    const cellFill = await Buffer.create('u32', cells);
+    const order = await Buffer.create('u32', count);
+    cellCount.write(new Uint32Array(cells));
+    const module = device.createShaderModule({ code: gridWgsl(), label: 'ngrid' });
+    const info = await module.getCompilationInfo();
+    const errors = info.messages.filter((m) => m.type === 'error');
+    if (errors.length > 0)
+        throw new CompileError('ngrid', errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
+    const pCounts = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_counts' } });
+    const pScan = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_scan' } });
+    const pScatter = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_scatter' } });
+    const bgCounts = (pos) => device.createBindGroup({
+        layout: pCounts.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: uniform } },
+            { binding: 1, resource: { buffer: pos.gpuBuffer } },
+            { binding: 2, resource: { buffer: cellCount.gpuBuffer } },
+        ],
+    });
+    const bgScan = device.createBindGroup({
+        layout: pScan.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: uniform } },
+            { binding: 1, resource: { buffer: cellCount.gpuBuffer } },
+            { binding: 2, resource: { buffer: cellStart.gpuBuffer } },
+            { binding: 3, resource: { buffer: cellFill.gpuBuffer } },
+        ],
+    });
+    const bgScatter = (pos) => device.createBindGroup({
+        layout: pScatter.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: uniform } },
+            { binding: 1, resource: { buffer: pos.gpuBuffer } },
+            { binding: 2, resource: { buffer: cellFill.gpuBuffer } },
+            { binding: 3, resource: { buffer: order.gpuBuffer } },
+        ],
+    });
+    return {
+        gridSize,
+        cells,
+        cellStart,
+        cellFill,
+        order,
+        update(pos) {
+            writeUniform();
+            const enc = device.createCommandEncoder();
+            const pass = enc.beginComputePass();
+            // 独立 pass:实测同 pass 连续 dispatch 存在旧数据可见性问题(Dawn/Windows)
+            pass.setPipeline(pCounts);
+            pass.setBindGroup(0, bgCounts(pos));
+            pass.dispatchWorkgroups(Math.ceil(count / WG));
+            pass.end();
+            const pass2 = enc.beginComputePass();
+            pass2.setPipeline(pScan);
+            pass2.setBindGroup(0, bgScan);
+            pass2.dispatchWorkgroups(1);
+            pass2.end();
+            const pass3 = enc.beginComputePass();
+            pass3.setPipeline(pScatter);
+            pass3.setBindGroup(0, bgScatter(pos));
+            pass3.dispatchWorkgroups(Math.ceil(count / WG));
+            pass3.end();
+            device.queue.submit([enc.finish()]);
+        },
+        destroy() {
+            cellCount.destroy();
+            cellStart.destroy();
+            cellFill.destroy();
+            order.destroy();
+            uniform.destroy();
+        },
+    };
+}
+function gridWgsl() {
+    return /* wgsl */ `
+struct Params {
+  count: u32, _pad0: u32,
+  worldHalf: f32, gridSize: u32, cells: u32,
+  _p0: u32, _p1: u32, _p2: u32,
+};
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read> posIn: array<vec2f>;
+@group(0) @binding(2) var<storage, read_write> cellCount: array<atomic<u32>>;
+@group(0) @binding(3) var<storage, read_write> cellStart: array<u32>;
+@group(0) @binding(4) var<storage, read_write> cellFill: array<atomic<u32>>;
+@group(0) @binding(5) var<storage, read_write> order: array<u32>;
+
+fn cellOf(p: vec2f) -> u32 {
+  let g = i32(params.gridSize);
+  let span = params.worldHalf * 2.0;
+  let cx = clamp(i32(floor((p.x + params.worldHalf) / span * f32(g))), 0, g - 1);
+  let cy = clamp(i32(floor((p.y + params.worldHalf) / span * f32(g))), 0, g - 1);
+  return u32(cy) * u32(g) + u32(cx);
+}
+
+@compute @workgroup_size(${WG})
+fn main_counts(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= params.count) { return; }
+  atomicAdd(&cellCount[cellOf(posIn[i])], 1u);
+}
+
+var<workgroup> partial: array<u32, ${SCAN}>;
+@compute @workgroup_size(${SCAN})
+fn main_scan(@builtin(local_invocation_id) lid: vec3u, @builtin(workgroup_id) wid: vec3u) {
+  let tid = lid.x;
+  let cells = params.cells;
+  let wg = ${SCAN}u;
+  let chunks = (cells + wg - 1u) / wg;
+
+  // ① 本 workgroup 负责的 chunk 局部和
+  var local = 0u;
+  for (var c = 0u; c < chunks; c++) {
+    let idx = c * wg + tid;
+    if (idx < cells) { local = local + atomicLoad(&cellCount[idx]); }
+  }
+  partial[tid] = local;
+  workgroupBarrier();
+
+  // ② 局部和的含前缀扫描(Hillis-Steele)
+  var offset = 1u;
+  loop {
+    if (offset >= wg) { break; }
+    var v = 0u;
+    if (tid >= offset) { v = partial[tid - offset]; }
+    workgroupBarrier();
+    if (tid >= offset) { partial[tid] = partial[tid] + v; }
+    workgroupBarrier();
+    offset = offset << 1u;
+  }
+
+  // ③ chunk 基址 → start/fill,顺带把 count 归零给下一帧
+  var run = 0u;
+  if (tid > 0u) { run = partial[tid - 1u]; }
+  for (var c = 0u; c < chunks; c++) {
+    let idx = c * wg + tid;
+    if (idx < cells) {
+      cellStart[idx] = run;
+      atomicStore(&cellFill[idx], run);
+      run = run + atomicLoad(&cellCount[idx]);
+      atomicStore(&cellCount[idx], 0u);
+    }
+  }
+}
+
+@compute @workgroup_size(${WG})
+fn main_scatter(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= params.count) { return; }
+  let slot = atomicAdd(&cellFill[cellOf(posIn[i])], 1u);
+  order[slot] = i;
+}
+`;
+}

package/dist/packs/image/index.js

@@ -4,7 +4,7 @@ const OPS = ['grayscale', 'invert', 'edge', 'blur', 'sharpen', 'brightness', 'co
 const OP_IDS = { grayscale: 0, invert: 1, edge: 2, blur: 3, sharpen: 4, brightness: 5, contrast: 6 };
 export async function applyImage(source, target, ops) {
     if (ops.length === 0)
-        throw new Error('applyImage 需要至少一个算子');
+        throw new Error('applyImage requires at least one operator');
     const width = 'naturalWidth' in source ? source.naturalWidth : source.width;
     const height = 'naturalHeight' in source ? source.naturalHeight : source.height;
     const ctx = await GpuContext.get();

package/dist/packs/life/boids.js

@@ -2,10 +2,11 @@ import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { PingPong } from "../../core/pingpong.js";
 import { CompileError } from "../../core/errors.js";
+import { createNeighborGrid } from "../grid/index.js";
 import { mulberry32 } from "../particles/presets.js";
 const WG = 64;
 export async function boids(config = {}) {
-    const { count: N = 3000, perception = 0.05, maxSpeed = 0.012, wSep = 1.6, wAli = 1.0, wCoh = 0.8, size = 0.009, seed = 'boids', } = config;
+    const { count: N = 1200, perception = 0.05, maxSpeed = 0.012, wSep = 1.6, wAli = 1.0, wCoh = 0.8, size = 0.009, seed = 'boids', } = config;
     const seedHash = typeof seed === 'string' ? hashStr(seed) : (seed ?? 3);
     const gridSize = Math.max(4, Math.ceil(2 / perception));
     const ctx = await GpuContext.get();
@@ -46,20 +47,12 @@ export async function boids(config = {}) {
         device.queue.writeBuffer(uniform, 0, b);
     };
     writeUniform();
-    const cells = gridSize * gridSize;
-    const cellCount = await Buffer.create('u32', cells);
-    const cellStart = await Buffer.create('u32', cells);
-    const cellFill = await Buffer.create('u32', cells);
-    const order = await Buffer.create('u32', N);
-    cellCount.write(new Uint32Array(cells));
     const module = device.createShaderModule({ code: boidsWgsl(size), label: 'boids' });
     const info = await module.getCompilationInfo();
     const errors = info.messages.filter((m) => m.type === 'error');
     if (errors.length > 0)
         throw new CompileError('boids', errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
-    const pCounts = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_counts' } });
-    const pScan = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_scan' } });
-    const pScatter = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_scatter' } });
+    const neighborGrid = await createNeighborGrid({ count: N, worldHalf: 1.0, cellSize: perception });
     const pForce = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_force' } });
     const pRender = device.createRenderPipeline({
         layout: 'auto',
@@ -67,32 +60,6 @@ export async function boids(config = {}) {
         fragment: { module, entryPoint: 'fs', targets: [{ format: navigator.gpu.getPreferredCanvasFormat() }] },
         primitive: { topology: 'triangle-list' },
     });
-    const bgCounts = (read) => device.createBindGroup({
-        layout: pCounts.getBindGroupLayout(0),
-        entries: [
-            { binding: 0, resource: { buffer: uniform } },
-            { binding: 1, resource: { buffer: read.pos.gpuBuffer } },
-            { binding: 2, resource: { buffer: cellCount.gpuBuffer } },
-        ],
-    });
-    const bgScan = device.createBindGroup({
-        layout: pScan.getBindGroupLayout(0),
-        entries: [
-            { binding: 0, resource: { buffer: uniform } },
-            { binding: 2, resource: { buffer: cellCount.gpuBuffer } },
-            { binding: 3, resource: { buffer: cellStart.gpuBuffer } },
-            { binding: 4, resource: { buffer: cellFill.gpuBuffer } },
-        ],
-    });
-    const bgScatter = (read) => device.createBindGroup({
-        layout: pScatter.getBindGroupLayout(0),
-        entries: [
-            { binding: 0, resource: { buffer: uniform } },
-            { binding: 1, resource: { buffer: read.pos.gpuBuffer } },
-            { binding: 4, resource: { buffer: cellFill.gpuBuffer } },
-            { binding: 5, resource: { buffer: order.gpuBuffer } },
-        ],
-    });
     const bgForce = (read, write) => device.createBindGroup({
         layout: pForce.getBindGroupLayout(0),
         entries: [
@@ -101,9 +68,9 @@ export async function boids(config = {}) {
             { binding: 6, resource: { buffer: read.vel.gpuBuffer } },
             { binding: 7, resource: { buffer: write.pos.gpuBuffer } },
             { binding: 8, resource: { buffer: write.vel.gpuBuffer } },
-            { binding: 3, resource: { buffer: cellStart.gpuBuffer } },
-            { binding: 4, resource: { buffer: cellFill.gpuBuffer } },
-            { binding: 5, resource: { buffer: order.gpuBuffer } },
+            { binding: 3, resource: { buffer: neighborGrid.cellStart.gpuBuffer } },
+            { binding: 4, resource: { buffer: neighborGrid.cellFill.gpuBuffer } },
+            { binding: 5, resource: { buffer: neighborGrid.order.gpuBuffer } },
         ],
     });
     const bgRender = (read) => device.createBindGroup({
@@ -137,15 +104,6 @@ export async function boids(config = {}) {
             const write = useAB ? sideB : sideA;
             const enc = device.createCommandEncoder();
             const pass = enc.beginComputePass();
-            pass.setPipeline(pCounts);
-            pass.setBindGroup(0, bgCounts(read));
-            pass.dispatchWorkgroups(Math.ceil(N / WG));
-            pass.setPipeline(pScan);
-            pass.setBindGroup(0, bgScan);
-            pass.dispatchWorkgroups(1);
-            pass.setPipeline(pScatter);
-            pass.setBindGroup(0, bgScatter(read));
-            pass.dispatchWorkgroups(Math.ceil(N / WG));
             pass.setPipeline(pForce);
             pass.setBindGroup(0, bgForce(read, write));
             pass.dispatchWorkgroups(Math.ceil(N / WG));
@@ -172,10 +130,7 @@ export async function boids(config = {}) {
         buffers() { return { pos: pp.current.pos, vel: pp.current.vel }; },
         destroy() {
             pp.destroy();
-            cellCount.destroy();
-            cellStart.destroy();
-            cellFill.destroy();
-            order.destroy();
+            neighborGrid.destroy();
             uniform.destroy();
         },
     };
@@ -223,57 +178,6 @@ fn cellOf(p: vec2f) -> u32 {
   return u32(cy) * u32(g) + u32(cx);
 }
 
-@compute @workgroup_size(${WG})
-fn main_counts(@builtin(global_invocation_id) gid: vec3u) {
-  let i = gid.x;
-  if (i >= params.count) { return; }
-  atomicAdd(&cellCount[cellOf(posIn[i])], 1u);
-}
-
-var<workgroup> partial: array<u32, 256>;
-@compute @workgroup_size(256)
-fn main_scan(@builtin(local_invocation_id) lid: vec3u) {
-  let tid = lid.x;
-  let cells = params.gridSize * params.gridSize;
-  let chunks = (cells + 255u) / 256u;
-  var local = 0u;
-  for (var c = 0u; c < chunks; c++) {
-    let idx = c * 256u + tid;
-    if (idx < cells) { local = local + atomicLoad(&cellCount[idx]); }
-  }
-  partial[tid] = local;
-  workgroupBarrier();
-  var offset = 1u;
-  loop {
-    if (offset >= 256u) { break; }
-    var v = 0u;
-    if (tid >= offset) { v = partial[tid - offset]; }
-    workgroupBarrier();
-    if (tid >= offset) { partial[tid] = partial[tid] + v; }
-    workgroupBarrier();
-    offset = offset << 1u;
-  }
-  var run = 0u;
-  if (tid > 0u) { run = partial[tid - 1u]; }
-  for (var c = 0u; c < chunks; c++) {
-    let idx = c * 256u + tid;
-    if (idx < cells) {
-      cellStart[idx] = run;
-      atomicStore(&cellFill[idx], run);
-      run = run + atomicLoad(&cellCount[idx]);
-      atomicStore(&cellCount[idx], 0u);
-    }
-  }
-}
-
-@compute @workgroup_size(${WG})
-fn main_scatter(@builtin(global_invocation_id) gid: vec3u) {
-  let i = gid.x;
-  if (i >= params.count) { return; }
-  let slot = atomicAdd(&cellFill[cellOf(posIn[i])], 1u);
-  order[slot] = i;
-}
-
 @compute @workgroup_size(${WG})
 fn main_force(@builtin(global_invocation_id) gid: vec3u) {
   let i = gid.x;

package/dist/packs/particles/config.d.ts

@@ -22,7 +22,8 @@ export interface ParticlesConfig {
     dt?: number;
     /** 点大小(canvas 像素单位的比例,默认 0.004;大规模下自动缩小) */
     pointSize?: number;
-    /** 每粒子邻域候选上限(grid 模式;仅作极端抱团的保险丝,默认 32768 在支持密度内不触发——按格子顺序截断会引入方向偏差伪影) */
+    /** 每粒子邻域候选总上限(grid 模式,均摊到 3×3=9 格)。默认 8100:正常密度永不触发,
+     *  极端抱团时以轻微方向偏差换取帧率稳定(实测 30ms → 7.5ms @ 200k 抱团态)。设 Infinity 可禁用。 */
     maxNeighbors?: number;
 }
 export interface ResolvedConfig {

package/dist/packs/particles/config.js

@@ -1,17 +1,17 @@
 import { resolveMatrix, hashSeed } from "./presets.js";
-import { UsageError } from "../../core/errors.js";
+import { ERR, UsageError } from "../../core/errors.js";
 const MODES = ['n2', 'tiled', 'grid'];
 export function resolveConfig(config = {}) {
     const { count = 8192, forces = 'cells', mode = 'grid', // 基准数据驱动:v0.4 起 grid 全面优于 tiled(0.54ms vs 3.62ms @16k),见 benchmarks.md
-    color = 'species', bounds = 'wrap', seed = 'wgpu-kit', rMax = 0.12, beta = 0.3, forceFactor = 10, frictionHalfLife = 0.04, dt = 0.02, pointSize = 0.004, maxNeighbors = 32768, } = config;
+    color = 'species', bounds = 'wrap', seed = 'wgpu-kit', rMax = 0.12, beta = 0.3, forceFactor = 10, frictionHalfLife = 0.04, dt = 0.02, pointSize = 0.004, maxNeighbors = 8100, } = config;
     if (!Number.isInteger(count) || count <= 0 || count > 1_000_000) {
-        throw new UsageError(`count 必须是 1..1_000_000 的整数,收到: ${String(count)}`);
+        throw new UsageError(ERR.USAGE, `count must be an integer in 1..1_000_000, got: ${String(count)}`);
     }
     if (!MODES.includes(mode)) {
-        throw new UsageError(`mode 必须是 ${MODES.join(' | ')},收到: "${String(mode)}"`);
+        throw new UsageError(ERR.USAGE, `mode must be one of ${MODES.join(" | ")}, got: "${String(mode)}"`);
     }
     if (mode === 'n2' && count > 32_000) {
-        throw new UsageError(`mode='n2' 建议 count ≤ 20000(当前 ${count});大规模请用 mode='tiled' 或 'grid'`);
+        throw new UsageError(ERR.USAGE, `mode='n2' is recommended for count <= 20000 (got ${count}); use 'tiled' or 'grid' for larger counts`);
     }
     const seedStr = String(seed);
     return {

package/dist/packs/particles/grid.js

@@ -40,9 +40,13 @@ fn main(@builtin(global_invocation_id) gid: vec3u) {
 `;
 }
 export function gridScanWgsl() {
-    // 两级扫描:① 各 workgroup 扫自己的 256-cell 块,块总和写入 blockSums;
-    // ② 单 workgroup 扫 blockSums(最多 SCAN_WORKGROUP 个块 = 65536 cell);
-    // ③ 各 workgroup 加上本块基址。256×256=65536 cell 内 O(1) 轮次,不再随规模线性退化。
+    // 单 workgroup 分块扫描:256-cell 块循环推进,块内 Hillis-Steele,块间用
+    // workgroup 级 carry 串接。此前版本按多 workgroup 分两级写,但 dispatch(1)
+    // 只有 block 0 在跑 —— 256 格之外 cellStart 永远是 0、cellCount 永不清零,
+    // 对应粒子受力恒零被摩擦冻住(屏幕上出现水平"冻结带")。改成单 workgroup
+    // 循环后 barrier 是合法同步,正确性不依赖任何跨 workgroup 时序;
+    // cell 上限 65536 = 256 块,每块一轮微秒级,性能无虞。顺带把 cellCount
+    // 归零给下一帧。
     return /* wgsl */ `
 struct Params {
   count: u32, _pad0: u32,
@@ -54,63 +58,48 @@ struct Params {
 @group(0) @binding(1) var<storage, read_write> cellCount: array<atomic<u32>>;
 @group(0) @binding(2) var<storage, read_write> cellStart: array<u32>;
 @group(0) @binding(3) var<storage, read_write> cellFill: array<u32>;
-@group(0) @binding(4) var<storage, read_write> blockSums: array<u32>;
 
 var<workgroup> partial: array<u32, ${SCAN_WORKGROUP}>;
+var<workgroup> carry: u32;
 
 @compute @workgroup_size(${SCAN_WORKGROUP})
-fn main(@builtin(local_invocation_id) lid: vec3u, @builtin(workgroup_id) wid: vec3u) {
+fn main(@builtin(local_invocation_id) lid: vec3u) {
   let tid = lid.x;
   let wg = ${SCAN_WORKGROUP}u;
-  let base = wid.x * wg;
   let cells = params.cells;
-
-  // ① 块内 Hillis-Steele(块不足时以 0 填充)
-  let v0 = select(0u, atomicLoad(&cellCount[base + tid]), base + tid < cells);
-  partial[tid] = v0;
+  let numChunks = (cells + wg - 1u) / wg;
+  if (tid == 0u) { carry = 0u; }
   workgroupBarrier();
-  var offset = 1u;
-  loop {
-    if (offset >= wg) { break; }
-    var v = 0u;
-    if (tid >= offset) { v = partial[tid - offset]; }
-    workgroupBarrier();
-    if (tid >= offset) { partial[tid] = partial[tid] + v; }
+  for (var ch = 0u; ch < numChunks; ch++) {
+    let idx = ch * wg + tid;
+    let inRange = idx < cells;
+    let v0 = select(0u, atomicLoad(&cellCount[idx]), inRange);
+    partial[tid] = v0;
     workgroupBarrier();
-    offset = offset << 1u;
-  }
-  // 含前缀 → 排他:start = 块内前缀(不含自身),fill = start + count
-  let myCount = v0;
-  let myPrefix = select(partial[tid - 1u], 0u, tid == 0u);
-  if (base + tid < cells) {
-    cellStart[base + tid] = myPrefix;
-    cellFill[base + tid] = myPrefix + myCount;
-  }
-  // 块总和 → blockSums(含)
-  if (tid == 0u) { blockSums[wid.x] = partial[wg - 1u]; }
-  workgroupBarrier();
-
-  // ② 块间扫描(单 workgroup;块数 = ceil(cells/wg) ≤ SCAN_WORKGROUP)
-  if (wid.x == 0u) {
-    var off = 1u;
+    // 块内含前缀(Hillis-Steele)
+    var offset = 1u;
     loop {
-      if (off >= wg) { break; }
+      if (offset >= wg) { break; }
       var v = 0u;
-      if (tid >= off) { v = blockSums[tid - off]; }
+      if (tid >= offset) { v = partial[tid - offset]; }
       workgroupBarrier();
-      if (tid >= off) { blockSums[tid] = blockSums[tid] + v; }
+      if (tid >= offset) { partial[tid] = partial[tid] + v; }
       workgroupBarrier();
-      off = off << 1u;
+      offset = offset << 1u;
     }
-  }
-  workgroupBarrier();
-
-  // ③ 加块基址;cellCount 归零供下一帧
-  let blockBase = select(0u, blockSums[wid.x - 1u], wid.x > 0u);
-  if (base + tid < cells) {
-    cellStart[base + tid] = cellStart[base + tid] + blockBase;
-    cellFill[base + tid] = cellFill[base + tid] + blockBase;
-    atomicStore(&cellCount[base + tid], 0u);
+    // 排他:start = carry + 块内前缀(不含自身);fill 是 scatter 的原子填充
+    // 游标,初始化为段起点(与通用包 NeighborGrid 同语义)——scatter 填完一格
+    // 后 fill 恰好 = start + count,力核读 [start, fill) 才不会多扫下一格的粒子。
+    if (inRange) {
+      let excl = partial[tid] - v0;
+      cellStart[idx] = carry + excl;
+      cellFill[idx] = carry + excl;
+      atomicStore(&cellCount[idx], 0u);
+    }
+    // 所有线程读完 partial/写完 carry 后才能进入下一块
+    workgroupBarrier();
+    if (tid == wg - 1u) { carry = carry + partial[wg - 1u]; }
+    workgroupBarrier();
   }
 }
 `;

package/dist/packs/particles/index.js

@@ -37,8 +37,9 @@ export async function particles(config = {}) {
     }
     const phys = { rMax: cfg.rMax, beta: cfg.beta, forceFactor: cfg.forceFactor, frictionHalfLife: cfg.frictionHalfLife, dt: cfg.dt };
     const uniform = device.createBuffer({ size: USIZE, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, label: 'particles-params' });
-    // grid 尺寸由 rMax 决定(格宽 ≈ rMax → 邻域恰好 3×3 格)
-    const gridSizeOf = (rMax, half = worldHalf) => Math.max(4, Math.ceil((2 * half) / Math.max(rMax, 1e-3)));
+    // grid 尺寸由 rMax 决定(floor 确保格宽 ≥ rMax → 3×3 邻域完整覆盖交互半径;
+    // ceil 会导致格宽 < rMax,3×3 不够覆盖,边界粒子漏配邻居)
+    const gridSizeOf = (rMax, half = worldHalf) => Math.max(4, Math.floor((2 * half) / Math.max(rMax, 1e-3)));
     let gridSize = gridSizeOf(phys.rMax, worldHalf);
     const writeUniform = (dt) => {
         const buf = new ArrayBuffer(USIZE);
@@ -83,7 +84,6 @@ export async function particles(config = {}) {
         g.partial.destroy();
         g.sortedPos.destroy();
         g.sortedSp.destroy();
-        g.blockSums.destroy();
     };
     const buildGrid = async (size) => {
         const cells = size * size;
@@ -102,7 +102,6 @@ export async function particles(config = {}) {
         const pForceCell = await makePipeline(mForce, 'main_force_cell', 'grid-force-cell');
         const pForceInt = await makePipeline(mForce, 'main_force_integrate', 'grid-force-integrate');
         const partial = await Buffer.create('vec2f', cfg.count * 9); // (粒子 × 3×3 格) 部分力
-        const blockSums = await Buffer.create('u32', Math.ceil(cells / 256)); // 二级扫描块和
         const sortedPos = await Buffer.create('vec2f', cfg.count); // 按格子序重排的副本(合并访问)
         const sortedSp = await Buffer.create('u32', cfg.count);
         const bgCounts = (readPos) => device.createBindGroup({
@@ -120,7 +119,6 @@ export async function particles(config = {}) {
                 { binding: 1, resource: { buffer: count.gpuBuffer } },
                 { binding: 2, resource: { buffer: start.gpuBuffer } },
                 { binding: 3, resource: { buffer: fill.gpuBuffer } },
-                { binding: 4, resource: { buffer: blockSums.gpuBuffer } },
             ],
         });
         const bgScatter = (readPos) => device.createBindGroup({
@@ -170,7 +168,7 @@ export async function particles(config = {}) {
         };
         const state = {
             size,
-            count, start, fill, order, partial, sortedPos, sortedSp, blockSums,
+            count, start, fill, order, partial, sortedPos, sortedSp,
             pCounts, pScan, pScatter, pForceCell, pForceInt,
             bgCountsA: bgCounts(sideA.pos), bgCountsB: bgCounts(sideB.pos),
             bgScan,
@@ -237,23 +235,25 @@ export async function particles(config = {}) {
                 gridBindGroupsDirty = false;
             }
             const enc = device.createCommandEncoder();
-            const pass = enc.beginComputePass();
             if (grid) {
-                // 实测:同一 compute pass 内连续 dispatch 之间,后续 kernel 读到的可能
-                // 是前一 kernel 的旧数据(Dawn/Windows,partial 竞态)——各段独立 pass
-                // 提交以保证可见性。
-                // 单 encoder、五个独立 pass:同一 encoder 内 pass 天然按序执行且可见,
-                // 免掉每帧 2 次额外 enc.finish()/submit(评审:提交间隔调度空隙)
-                pass.setPipeline(grid.pCounts);
-                pass.setBindGroup(0, useAB ? grid.bgCountsA : grid.bgCountsB);
-                pass.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));
-                pass.setPipeline(grid.pScan);
-                pass.setBindGroup(0, grid.bgScan);
-                pass.dispatchWorkgroups(1);
-                pass.setPipeline(grid.pScatter);
-                pass.setBindGroup(0, useAB ? grid.bgScatterA : grid.bgScatterB);
-                pass.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));
-                pass.end();
+                // 每个 build 阶段独立 pass:同 pass 内跨 dispatch 的存储可见性规范不保证
+                // (Dawn/Windows 实测出现过旧数据),counts→scan→scatter 是严格串行依赖。
+                // 单 encoder 内 pass 按序执行且天然可见,不增加 submit 次数。
+                const passCounts = enc.beginComputePass();
+                passCounts.setPipeline(grid.pCounts);
+                passCounts.setBindGroup(0, useAB ? grid.bgCountsA : grid.bgCountsB);
+                passCounts.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));
+                passCounts.end();
+                const passScan = enc.beginComputePass();
+                passScan.setPipeline(grid.pScan);
+                passScan.setBindGroup(0, grid.bgScan);
+                passScan.dispatchWorkgroups(1);
+                passScan.end();
+                const passScatter = enc.beginComputePass();
+                passScatter.setPipeline(grid.pScatter);
+                passScatter.setBindGroup(0, useAB ? grid.bgScatterA : grid.bgScatterB);
+                passScatter.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));
+                passScatter.end();
                 const passB = enc.beginComputePass();
                 passB.setPipeline(grid.pForceCell);
                 passB.setBindGroup(0, useAB ? grid.bgForceCellAB : grid.bgForceCellBA);
@@ -267,6 +267,7 @@ export async function particles(config = {}) {
                 device.queue.submit([enc.finish()]);
             }
             else {
+                const pass = enc.beginComputePass();
                 pass.setPipeline(simPipeline);
                 pass.setBindGroup(0, useAB ? bgAB : bgBA);
                 pass.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));

package/dist/packs/particles/presets.js

@@ -67,7 +67,7 @@ export function resolveMatrix(forces, seed) {
     if (typeof forces === 'string') {
         const preset = FORCE_PRESETS[forces];
         if (!preset) {
-            throw new Error(`未知力矩阵预设 "${forces}",可用: ${Object.keys(FORCE_PRESETS).join(', ')}, random`);
+            throw new Error(`Unknown force preset "${forces}". Available: ${Object.keys(FORCE_PRESETS).join(", ")}, random`);
         }
         return preset;
     }