probe-filters 1.0.0 → 1.0.1

package/README.md

@@ -285,6 +285,47 @@ temporal.queryWithinLast('sensor:42', 60_000);        // true — seen in last m
 temporal.queryBetweenAges('sensor:42', 30_000, 90_000); // true — seen 30-90s ago
 ```
 
+### Game engine — spatial interest management
+
+Avoid O(n²) entity distance checks. Insert positions into a SpatialFilter; query a box around the player to find candidate entities before running expensive exact checks. Remove despawned entities and adapt stale keepsake boxes to keep false positives low as entities move.
+
+```js
+const world = new SpatialFilter({ bitsPerCoordinate: 14, coordinateSystem: 'integer' });
+
+// Server tick: insert entity positions
+world.insert([1523, 871]);
+world.insert([1600, 900]);
+
+// Entity teleports — remove old, insert new
+world.delete([1523, 871]);
+world.insert([1530, 875]);
+
+// Interest query: any entity near player?
+const range = 100;
+if (world.queryBox([1525 - range, 870 - range],
+                   [1525 + range, 870 + range])) {
+    // Candidate found — run exact distance checks
+}
+
+// Entity despawns — unconditionally remove
+world.delete([1530, 875]);
+
+// Stale keepsake boxes may leave false positives behind
+world.adaptFalsePositiveBox([1525 - range, 870 - range],
+                            [1525 + range, 870 + range]);
+
+// Anti-cheat: has this player jumped in the last 500ms?
+const actions = new TemporalFilter({
+    bucketDurationMs: 100, retentionDurationMs: 2_000,
+});
+actions.insertAt('player:42:jump', Date.now());
+actions.queryWithinLast('player:42:jump', 500);  // true → flag excessive input
+
+// Merge snapshot from another server shard
+const neighbor = MultiFilter.deserialize(wire);
+world.mergeFrom(neighbor, 'union');
+```
+
 ## SEE ALSO
 
 **probe-maplets** — key-value maplet extensions providing value aggregation on top of probe-filters filters.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "probe-filters",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Dynamic approximate membership filters for point, range, spatial, and temporal queries (Aleph, Aeris, Zeno engines)",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -1,4 +1,4 @@
-export { PointFilter } from './pointFilter.js';
+export { PointFilter } from './v2/pointFilter.js';
 export { RangeFilter } from './rangeFilter.js';
 export { SpatialFilter } from './spatialFilter.js';
 export { TemporalFilter } from './temporalFilter.js';

package/src/multiFilter.js

@@ -24,7 +24,8 @@ function insertMotherHash(targetFilter, motherHash, state = 1) {
 }
 
 function mergeAlephFilters(targetFilter, sourceFilter) {
-    for (let i = 0; i < sourceFilter.currentCapacity; i++) {
+    const cap = sourceFilter.physicalCapacity ?? sourceFilter.currentCapacity;
+    for (let i = 0; i < cap; i++) {
         const state = sourceFilter.states[i];
         if (!isLiveAlephState(state)) continue;
         insertMotherHash(targetFilter, sourceFilter.motherHashes[i], state);