archetype-ecs 1.5.1 → 1.5.2

package/README.md

@@ -256,7 +256,7 @@ Supports stripping components, skipping entities, and custom serializers.
 
 ### WASM SIMD
 
-archetype-ecs automatically detects WASM SIMD support and enables it when available. No configuration needed — `createEntityManager()` does the right thing.
+`fieldAdd` uses WASM SIMD to add fields in bulk — 4x faster than a JS loop for float data:
 
 ```ts
 em.forEach([Position, Velocity], (arch) => {
@@ -265,14 +265,22 @@ em.forEach([Position, Velocity], (arch) => {
 })
 ```
 
-#### How auto-detection works
+#### When does SIMD kick in?
 
-On first `createEntityManager()` call, the library tries to compile a small (500-byte) WebAssembly module that uses SIMD instructions. If compilation succeeds, the runtime supports SIMD and WASM mode is enabled. The compiled module is cached — subsequent calls reuse it with zero overhead. If compilation fails (e.g. older browser, restricted environment), it falls back to plain JS. You can check or override this:
+All three conditions must be true:
+
+| Condition | Check | Fallback |
+|---|---|---|
+| Runtime supports WASM SIMD | Tested once at startup by compiling a 500-byte SIMD module | All storage and iteration stays in plain JS |
+| WASM mode not disabled | `createEntityManager()` (default) or `{ wasm: true }` | `createEntityManager({ wasm: false })` forces JS-only |
+| Field type is `f32` | `fieldAdd` checks if both arrays are `Float32Array` | Scalar JS loop `dst[i] += src[i]` |
+
+WASM SIMD is supported in all modern browsers (Chrome 91+, Firefox 89+, Safari 16.4+) and Node.js 16+.
 
 ```ts
 import { isWasmSimdAvailable } from 'archetype-ecs'
 
-isWasmSimdAvailable()                      // true if SIMD is supported
+isWasmSimdAvailable()                      // true if runtime supports SIMD
 createEntityManager({ wasm: false })       // force JS-only mode
 ```
 
@@ -282,15 +290,11 @@ Regular JavaScript processes one float at a time. When you write `px[i] += vx[i]
 
 WASM SIMD uses `f32x4.add`: a single CPU instruction that adds **4 floats in parallel**, directly in 32-bit precision. For 1M entities, that's 250K instructions instead of 1M, with no conversion overhead.
 
-`fieldAdd(target, source)` dispatches to this SIMD kernel for `Float32Array` fields and falls back to a scalar loop for other types. Your code stays the same either way.
-
 #### Storage layout
 
-When WASM mode is active, all numeric TypedArrays (`Float32Array`, `Int32Array`, etc.) are allocated on a shared `WebAssembly.Memory` via a bump allocator. This means the SIMD kernel can operate directly on the data without copying. String fields always use regular JS arrays.
+When WASM mode is active, all numeric TypedArrays (`Float32Array`, `Int32Array`, etc.) are allocated on a shared `WebAssembly.Memory` via a bump allocator. This means the SIMD kernel operates directly on the data — no copying between JS and WASM. String fields always use regular JS arrays.
 
-**Details:**
 - The arena reserves 128 MB virtual address space (lazily committed — no physical RAM cost on most OSes)
-- `fieldAdd` uses SIMD for `Float32Array` fields; other types fall back to scalar
 - The bump allocator doesn't reclaim memory — frequent archetype churn may waste space
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archetype-ecs",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Lightweight archetype-based Entity Component System",
   "type": "module",
   "main": "dist/index.js",