three-instance-batch 0.1.0

package/README.md

@@ -0,0 +1,177 @@
+# three-instance-batch
+
+`InstancedMesh` management layer for Three.js. Handles dirty tracking, group batching, and dynamic add/remove — so you don't have to.
+
+## Installation
+
+```bash
+npm install three-instance-batch
+```
+
+## Quick Start
+
+```ts
+import * as THREE from 'three'
+import { Instance, InstanceBatcher } from 'three-instance-batch'
+
+const batcher = new InstanceBatcher()
+scene.add(batcher)
+
+const geo = new THREE.BoxGeometry(1, 1, 1)
+const mat = new THREE.MeshStandardMaterial({ color: '#ff6b6b' })
+
+const inst = new Instance(geo, mat)
+inst.position.set(3, 0, 0)
+inst.color.set('#00ffcc')
+inst.castShadow = true
+
+batcher.addInstance(inst)
+
+function animate() {
+  inst.position.x = Math.sin(Date.now() * 0.001) * 5
+  batcher.update(camera)
+  renderer.render(scene, camera)
+  requestAnimationFrame(animate)
+}
+```
+
+No `setMatrixAt`. No `needsUpdate`. Just change properties and call `update()`.
+
+## How It Works
+
+`Instance` wraps `Vector3`, `Quaternion`, and `Color` setter methods at construction time. Any mutation — `position.set()`, `quaternion.setFromEuler()`, `color.setHSL()`, etc. — automatically marks that instance dirty. On `batcher.update()`, only the changed matrix rows and color rows are written to the GPU buffer.
+
+Instances are grouped into `InstancedMesh` objects by a **group key** derived from geometry UUID, material properties, and shadow flags. Instances sharing the same key share one draw call.
+
+## Multiple Geometries and Materials
+
+The batcher handles mixed types automatically:
+
+```ts
+const meshes = [
+  new Instance(boxGeo, redMat),
+  new Instance(sphereGeo, blueMat),
+  new Instance(boxGeo, redMat),   // same key as first → same InstancedMesh
+]
+batcher.addInstance(meshes)
+```
+
+Reusing the same geometry and material object is enough to share a batch.
+
+## Shadow Changes Trigger Remigration
+
+`castShadow` and `receiveShadow` are part of the group key. Changing them at runtime causes the instance to be moved to the correct group automatically on the next `update()`.
+
+```ts
+inst.castShadow = true  // migrates to the shadow-casting group on next update()
+```
+
+## Parent-Child Hierarchy
+
+Instances support parent-child nesting. A child's world matrix is computed from its parent's transform chain.
+
+```ts
+const parent = new Instance(geo, mat)
+const child = new Instance(geo, mat)
+child.parent = parent  // child follows parent's transform
+
+parent.position.set(0, 5, 0)
+batcher.update()  // child world matrix recalculated automatically
+```
+
+Circular references are detected and rejected at runtime. Disposing a parent detaches all children but does not dispose them.
+
+## Raycasting
+
+```ts
+const raycaster = new THREE.Raycaster()
+raycaster.setFromCamera(mouse, camera)
+const hits = raycaster.intersectObjects(batcher.children)
+
+for (const hit of hits) {
+  const inst = batcher.getInstanceFromIntersect(hit)
+  if (inst) console.log('hit', inst.id)
+}
+```
+
+## API
+
+### `Instance`
+
+```ts
+new Instance(geometry: BufferGeometry, material: Material)
+```
+
+| Member | Type | Notes |
+|---|---|---|
+| `id` | `number` | Auto-incremented, readonly |
+| `geometry` | `BufferGeometry` | Readonly |
+| `material` | `Material` | Readonly |
+| `position` | `Vector3` | Auto-tracked |
+| `scale` | `Vector3` | Default `(1,1,1)`, auto-tracked |
+| `quaternion` | `Quaternion` | Auto-tracked |
+| `color` | `Color` | Default white, auto-tracked |
+| `visible` | `boolean` | Hidden instances write a zero matrix |
+| `castShadow` | `boolean` | Change triggers group remigration |
+| `receiveShadow` | `boolean` | Change triggers group remigration |
+| `parent` | `Instance \| null` | Setter validates against cycles |
+| `children` | `Instance[]` | Readonly array |
+| `disposed` | `boolean` | Readonly |
+| `groupKey` | `string` | Derived from geometry, material, shadow flags |
+| `localMatrix` | `Matrix4` | Readonly, computed from transform components |
+| `worldMatrix` | `Matrix4` | Readonly, local × ancestor chain |
+| `isAncestorOf(other)` | `boolean` | |
+| `dispose()` | `void` | Detaches from parent, detaches children, unsubscribes from all batchers |
+
+> **Note:** `rotation` (Euler) mutates are tracked and auto-sync to `quaternion`.
+
+### `InstanceBatcher`
+
+Extends `THREE.Group`. Add it to the scene and call `update()` every frame.
+
+```ts
+new InstanceBatcher(options?: BatcherOptions)
+```
+
+| Member | Type | Notes |
+|---|---|---|
+| `count` | `number` | Total managed instances |
+| `groupCount` | `number` | Number of internal `InstancedMesh` groups |
+| `hasDirty` | `boolean` | Whether any data needs flushing to GPU |
+| `addInstance(inst \| inst[])` | `this` | Duplicates are ignored |
+| `removeInstance(inst \| inst[])` | `this` | Missing instances are ignored |
+| `has(inst)` | `boolean` | |
+| `getMatrixAt(inst, target)` | `Matrix4` | Reads back from GPU buffer |
+| `getColorAt(inst, target)` | `Color` | Reads back from GPU buffer |
+| `getInstanceFromIntersect(hit)` | `Instance \| null` | Resolves a raycaster hit to an instance |
+| `update(camera?)` | `void` | Flushes dirty matrices and colors; pass camera to enable frustum culling |
+| `disposeBatcher()` | `void` | Disposes all internal meshes and clears all subscriptions |
+
+### `BatcherOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `initialCapacity` | `number` | `16` | Initial slot count per `InstancedMesh` group |
+| `overAllocation` | `number` | `0.2` | Extra capacity fraction when a group grows (0.2 = 20%) |
+| `frustumCulling` | `boolean` | `false` | Skip instances outside the camera frustum |
+| `customDepthMaterial` | `Material` | — | Custom depth material for shadow passes |
+| `customDistanceMaterial` | `Material` | — | Custom distance material for shadow passes |
+
+## Memory Overhead
+
+| Overhead | Per 1,000 instances |
+|---|---|
+| 35 wrapped setter closures | ~1.1 MB |
+| Three.js transform objects | ~0.8 MB |
+| GPU buffer (matrix 64B + color 12B) | ~76 KB |
+| **Total** | **~2.0 MB / 1k** |
+
+The real bottleneck at scale is GPU draw calls and vertex throughput, not JS-side dirty tracking.
+
+## Known Limitations
+
+- Frustum culling is JS-side only; it does not write zero matrices for culled instances.
+
+## License
+
+MIT

package/dist/three-instance-batch.js

@@ -0,0 +1 @@
+import*as n from"three";const _=["type","map","alphaMap","normalMap","roughnessMap","metalnessMap","transparent","alphaTest","side","depthWrite","depthTest","wireframe","flatShading","blending","blendSrc","blendDst"];function m(a){const t=[];for(const s of _){const e=a[s];e==null?t.push(`${s}=_`):e instanceof n.Texture?t.push(`${s}=tex:${e.uuid}`):t.push(`${s}=${String(e)}`)}return t.join(";")}function y(a,t,s,e){const i=a.uuid??String(a.id),r=m(t);return`${i}|${r}|${`${s?1:0}${e?1:0}`}`}let f=0,u=0;function g(){return++u}function M(){return u}function c(a,t,s){const e=a[t];typeof e=="function"&&(a[t]=function(...i){const r=e.apply(this,i);return s(),r})}const d=["set","copy","setScalar","setX","setY","setZ","setComponent"],w=["set","setX","setY","setZ","copy","setFromVector3","setFromQuaternion"],S=["set","copy","identity","setFromEuler","setFromAxisAngle","setFromRotationMatrix","multiply","premultiply"],x=["set","setScalar","setHex","setRGB","setHSL","copy"];class b{constructor(t,s){this._visible=!0,this._castShadow=!1,this._receiveShadow=!1,this._parent=null,this.children=[],this._localDirty=!0,this._worldDirty=!0,this._dirtyColor=!0,this._dirtyShadow=!1,this._frameVersion=0,this._disposed=!1,this._subscribers=new Set,this.id=++f,this.geometry=t,this.material=s,this.position=new n.Vector3,this.quaternion=new n.Quaternion,this.rotation=new n.Euler,this.scale=new n.Vector3(1,1,1),this.color=new n.Color(1,1,1),this.localMatrix=new n.Matrix4,this.worldMatrix=new n.Matrix4;const e=()=>{this._localDirty=!0,this._markWorldDirty()},i=()=>{this.quaternion.setFromEuler(this.rotation),e()},r=()=>{this._dirtyColor=!0,this._notifyDirty("color")};for(const o of d)c(this.position,o,e);for(const o of d)c(this.scale,o,e);for(const o of w)c(this.rotation,o,i);for(const o of S)c(this.quaternion,o,e);for(const o of x)c(this.color,o,r)}get visible(){return this._visible}set visible(t){this._visible!==t&&(this._visible=t,this._notifyDirty("matrix"))}get castShadow(){return this._castShadow}set castShadow(t){this._castShadow!==t&&(this._castShadow=t,this._dirtyShadow=!0,this._notifyShadowChange())}get receiveShadow(){return this._receiveShadow}set receiveShadow(t){this._receiveShadow!==t&&(this._receiveShadow=t,this._dirtyShadow=!0,this._notifyShadowChange())}get groupKey(){return y(this.geometry,this.material,this._castShadow,this._receiveShadow)}get parent(){return this._parent}set parent(t){if(t!==this._parent){if(t&&this._wouldCreateCycle(t))throw new Error("Instance: setting parent would create a cycle");if(this._parent){const s=this._parent.children.indexOf(this);s!==-1&&this._parent.children.splice(s,1)}this._parent=t,t&&t.children.push(this),this._markWorldDirty()}}isAncestorOf(t){let s=t.parent;for(;s;){if(s===this)return!0;s=s.parent}return!1}get disposed(){return this._disposed}dispose(){if(this._disposed)return;if(this._disposed=!0,this._parent){const s=this._parent.children.indexOf(this);s!==-1&&this._parent.children.splice(s,1),this._parent=null}for(const s of this.children)s._parent=null,s._markWorldDirty();this.children.length=0;const t=[...this._subscribers];this._subscribers.clear();for(const s of t)s.removeInstance(this)}recomputeLocalMatrix(){this._localDirty&&(this.localMatrix.compose(this.position,this.quaternion,this.scale),this._localDirty=!1,this._markWorldDirty())}recomputeWorldMatrix(){const t=M();this._frameVersion!==t&&(this._frameVersion=t,this._parent?(this._parent.recomputeWorldMatrix(),this.recomputeLocalMatrix(),this.worldMatrix.multiplyMatrices(this._parent.worldMatrix,this.localMatrix)):(this.recomputeLocalMatrix(),this.worldMatrix.copy(this.localMatrix)),this._worldDirty=!1)}_subscribe(t){this._subscribers.add(t)}_unsubscribe(t){this._subscribers.delete(t)}_markWorldDirty(){if(!this._worldDirty){this._worldDirty=!0,this._notifyDirty("matrix");for(const t of this.children)t._markWorldDirty()}}_markDirtyForBatcher(t){t.markDirty(this,"matrix"),t.markDirty(this,"color")}_notifyDirty(t){for(const s of this._subscribers)s.markDirty(this,t)}_notifyShadowChange(){for(const t of this._subscribers)t.markShadowChange(this)}_wouldCreateCycle(t){return this.isAncestorOf(t)||t===this}}function p(a,t,s,e,i){const r=new n.InstancedMesh(a,t,s);r.castShadow=!1,r.receiveShadow=!1,r.frustumCulled=!1,r.count=0,e&&(r.customDepthMaterial=e),i&&(r.customDistanceMaterial=i),r.instanceColor=new n.InstancedBufferAttribute(new Float32Array(s*3),3);const o=r.instanceMatrix.array;for(let h=0;h<s;h++){const l=h*16;o[l]=1,o[l+5]=1,o[l+10]=1,o[l+15]=1}return r}const D=new n.Matrix4().identity().multiplyScalar(0);class C extends n.Group{constructor(t={}){super(),this._groups=new Map,this._meshToGroup=new Map,this._allInstances=new Set,this._instanceMeta=new Map,this._needsGroupRebuild=new Set,this._hasDirty=!0,this._frustum=new n.Frustum,this._projScreenMatrix=new n.Matrix4,this._tempVec=new n.Vector3,this._tempSphere=new n.Sphere,this._opts={overAllocation:t.overAllocation??.2,initialCapacity:t.initialCapacity??16,frustumCulling:t.frustumCulling??!1,customDepthMaterial:t.customDepthMaterial,customDistanceMaterial:t.customDistanceMaterial}}get count(){return this._allInstances.size}get groupCount(){return this._groups.size}get hasDirty(){return this._hasDirty||this._needsGroupRebuild.size>0}addInstance(t){const s=Array.isArray(t)?t:[t];for(const e of s)this._allInstances.has(e)||(this._addToGroup(e),e._subscribe(this),this._allInstances.add(e));return this}removeInstance(t){const s=Array.isArray(t)?t:[t];for(const e of s)this._allInstances.has(e)&&(this._removeFromGroup(e),e._unsubscribe(this),this._allInstances.delete(e),this._needsGroupRebuild.delete(e));return this}has(t){return this._allInstances.has(t)}getInstanceFromIntersect(t){if(t.instanceId===void 0)return null;const s=this._meshToGroup.get(t.object);return s&&t.instanceId<s.instances.length?s.instances[t.instanceId]:null}getMatrixAt(t,s){const e=this._instanceMeta.get(t);if(!e)return s.identity();const i=this._groups.get(e.groupKey);return i?(i.mesh.getMatrixAt(e.idx,s),s):s.identity()}getColorAt(t,s){const e=this._instanceMeta.get(t);if(!e)return s.set(1,1,1);const i=this._groups.get(e.groupKey);return!i||!i.mesh.instanceColor?s.set(1,1,1):(i.mesh.getColorAt(e.idx,s),s)}update(t){if(!(!this._hasDirty&&this._needsGroupRebuild.size===0)){if(g(),this._needsGroupRebuild.size>0){for(const s of this._needsGroupRebuild)this._removeFromGroup(s),this._addToGroup(s);this._needsGroupRebuild.clear()}this._opts.frustumCulling&&t&&this._updateFrustumCulling(t);for(const s of this._groups.values())s.hasDirty&&this._processGroup(s);this._hasDirty=!1}}disposeBatcher(){for(const t of this._allInstances)t._unsubscribe(this);for(const t of this._groups.values())t.mesh.dispose();this._groups.clear(),this._meshToGroup.clear(),this._allInstances.clear(),this._instanceMeta.clear(),this._needsGroupRebuild.clear(),this._hasDirty=!1,this.clear()}markDirty(t,s){const e=this._instanceMeta.get(t);if(!e)return;const i=this._groups.get(e.groupKey);i&&(this._hasDirty=!0,i.hasDirty=!0,s==="matrix"&&i.dirtyIndices.add(e.idx),s==="color"&&i.dirtyColors.add(e.idx))}markShadowChange(t){this._allInstances.has(t)&&(this._hasDirty=!0,this._needsGroupRebuild.add(t))}_addMeshToScene(t){super.add(t)}_removeMeshFromScene(t){super.remove(t)}_addToGroup(t){const s=t.groupKey;let e=this._groups.get(s);if(!e){const r=this._opts.initialCapacity;e={key:s,mesh:null,instances:new Array(r).fill(null),indexMap:new Map,dirtyIndices:new Set,dirtyColors:new Set,emptySlots:[],frustumVisible:new Set,hasDirty:!0,capacity:r,count:0};const o=p(t.geometry,t.material,r,this._opts.customDepthMaterial,this._opts.customDistanceMaterial);o.castShadow=t.castShadow,o.receiveShadow=t.receiveShadow,e.mesh=o,this._addMeshToScene(o),this._groups.set(s,e),this._meshToGroup.set(o,e)}e.count>=e.capacity&&this._growGroup(e);let i;e.emptySlots.length>0?i=e.emptySlots.pop():i=e.count,e.instances[i]=t,e.indexMap.set(t,i),this._instanceMeta.set(t,{groupKey:s,idx:i}),e.count++,e.mesh.count=e.count,this._hasDirty=!0,e.hasDirty=!0,e.dirtyIndices.add(i),e.dirtyColors.add(i)}_removeFromGroup(t){const s=t.groupKey,e=this._groups.get(s);if(!e)return;const i=e.indexMap.get(t);if(i===void 0)return;const r=e.count-1;if(i===r)e.instances[i]=null,e.count--;else{const o=e.instances[r];e.instances[i]=o,e.instances[r]=null,e.indexMap.set(o,i),this._instanceMeta.set(o,{groupKey:s,idx:i}),e.dirtyIndices.add(i),e.count--}e.indexMap.delete(t),this._instanceMeta.delete(t),e.emptySlots.push(r),e.dirtyIndices.delete(i),e.dirtyColors.delete(i),e.mesh.count=e.count,e.count===0&&(this._meshToGroup.delete(e.mesh),e.mesh.dispose(),this._removeMeshFromScene(e.mesh),this._groups.delete(s))}_processGroup(t){const s=t.mesh,e=s.instanceMatrix.array;for(const i of t.dirtyIndices){const r=t.instances[i];r&&(r.recomputeWorldMatrix(),r.visible?r.worldMatrix.toArray(e,i*16):D.toArray(e,i*16))}if(t.dirtyIndices.size>0&&(s.instanceMatrix.needsUpdate=!0,t.dirtyIndices.clear()),t.hasDirty=!1,t.dirtyColors.size>0&&s.instanceColor){const i=s.instanceColor.array;for(const r of t.dirtyColors){const o=t.instances[r];if(o){const h=o.color;i[r*3]=h.r,i[r*3+1]=h.g,i[r*3+2]=h.b}}s.instanceColor.needsUpdate=!0,t.dirtyColors.clear()}s.computeBoundingSphere(),s.computeBoundingBox()}_updateFrustumCulling(t){this._projScreenMatrix.multiplyMatrices(t.projectionMatrix,t.matrixWorldInverse),this._frustum.setFromProjectionMatrix(this._projScreenMatrix);for(const s of this._groups.values()){const e=s.mesh.geometry;e.boundingSphere||e.computeBoundingSphere();const i=e.boundingSphere;s.frustumVisible.clear();for(let r=0;r<s.count;r++){const o=s.instances[r];if(!o)continue;o.recomputeWorldMatrix();const h=o.scale;this._tempVec.copy(i.center).applyMatrix4(o.worldMatrix),this._tempSphere.set(this._tempVec,i.radius*Math.max(h.x,h.y,h.z)),this._frustum.intersectsSphere(this._tempSphere)&&s.frustumVisible.add(r)}}}_growGroup(t){const s=t.capacity+Math.max(1,Math.ceil(t.capacity*this._opts.overAllocation)),e=t.mesh,i=p(e.geometry,e.material,s,this._opts.customDepthMaterial,this._opts.customDistanceMaterial);i.castShadow=e.castShadow,i.receiveShadow=e.receiveShadow;const r=e.instanceMatrix.array;if(i.instanceMatrix.array.set(r.subarray(0,t.count*16)),e.instanceColor&&i.instanceColor){const o=e.instanceColor.array;i.instanceColor.array.set(o.subarray(0,t.count*3))}i.count=t.count,this._meshToGroup.delete(e),this._removeMeshFromScene(e),e.dispose(),this._addMeshToScene(i),this._meshToGroup.set(i,t),t.mesh=i,t.capacity=s,t.instances.length=s}}export{b as Instance,C as InstanceBatcher};

package/dist/types/core/Instance.d.ts

@@ -0,0 +1,50 @@
+import * as THREE from 'three';
+import type { BatcherSubscriber } from '../types';
+export declare function bumpFrameVersion(): number;
+export declare function getFrameVersion(): number;
+export declare class Instance {
+    readonly id: number;
+    readonly geometry: THREE.BufferGeometry;
+    readonly material: THREE.Material;
+    readonly position: THREE.Vector3;
+    readonly scale: THREE.Vector3;
+    readonly quaternion: THREE.Quaternion;
+    readonly rotation: THREE.Euler;
+    readonly color: THREE.Color;
+    readonly localMatrix: THREE.Matrix4;
+    readonly worldMatrix: THREE.Matrix4;
+    private _visible;
+    private _castShadow;
+    private _receiveShadow;
+    private _parent;
+    readonly children: Instance[];
+    _localDirty: boolean;
+    _worldDirty: boolean;
+    _dirtyColor: boolean;
+    _dirtyShadow: boolean;
+    _frameVersion: number;
+    private _disposed;
+    readonly _subscribers: Set<BatcherSubscriber>;
+    constructor(geometry: THREE.BufferGeometry, material: THREE.Material);
+    get visible(): boolean;
+    set visible(v: boolean);
+    get castShadow(): boolean;
+    set castShadow(v: boolean);
+    get receiveShadow(): boolean;
+    set receiveShadow(v: boolean);
+    get groupKey(): string;
+    get parent(): Instance | null;
+    set parent(p: Instance | null);
+    isAncestorOf(other: Instance): boolean;
+    get disposed(): boolean;
+    dispose(): void;
+    recomputeLocalMatrix(): void;
+    recomputeWorldMatrix(): void;
+    _subscribe(sub: BatcherSubscriber): void;
+    _unsubscribe(sub: BatcherSubscriber): void;
+    _markWorldDirty(): void;
+    _markDirtyForBatcher(batcher: BatcherSubscriber): void;
+    private _notifyDirty;
+    private _notifyShadowChange;
+    private _wouldCreateCycle;
+}

package/dist/types/core/InstanceBatcher.d.ts

@@ -0,0 +1,40 @@
+import * as THREE from 'three';
+import { Instance } from './Instance';
+import type { BatcherSubscriber, DirtyType, BatcherOptions } from '../types';
+export declare class InstanceBatcher extends THREE.Group implements BatcherSubscriber {
+    private _groups;
+    private _meshToGroup;
+    private _allInstances;
+    private _instanceMeta;
+    private _needsGroupRebuild;
+    private _hasDirty;
+    private _opts;
+    private _frustum;
+    private _projScreenMatrix;
+    constructor(options?: BatcherOptions);
+    get count(): number;
+    get groupCount(): number;
+    get hasDirty(): boolean;
+    addInstance(instance: Instance | Instance[]): this;
+    removeInstance(instance: Instance | Instance[]): this;
+    has(instance: Instance): boolean;
+    getInstanceFromIntersect(hit: {
+        instanceId?: number;
+        object: THREE.Object3D;
+    }): Instance | null;
+    getMatrixAt(instance: Instance, target: THREE.Matrix4): THREE.Matrix4;
+    getColorAt(instance: Instance, target: THREE.Color): THREE.Color;
+    update(camera?: THREE.Camera): void;
+    disposeBatcher(): void;
+    markDirty(instance: Instance, type: DirtyType): void;
+    markShadowChange(instance: Instance): void;
+    private _addMeshToScene;
+    private _removeMeshFromScene;
+    private _addToGroup;
+    private _removeFromGroup;
+    private _processGroup;
+    private _tempVec;
+    private _tempSphere;
+    private _updateFrustumCulling;
+    private _growGroup;
+}

package/dist/types/core/groupKey.d.ts

@@ -0,0 +1,3 @@
+import * as THREE from 'three';
+export declare function materialSignature(mat: THREE.Material): string;
+export declare function groupKey(geometry: THREE.BufferGeometry, material: THREE.Material, castShadow: boolean, receiveShadow: boolean): string;

package/dist/types/core/index.d.ts

@@ -0,0 +1,2 @@
+export { Instance } from './Instance';
+export { InstanceBatcher } from './InstanceBatcher';

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './core';
+export * from './types';

package/dist/types/types.d.ts

@@ -0,0 +1,28 @@
+import type * as THREE from 'three';
+import type { Instance } from './core/Instance';
+export type DirtyType = 'matrix' | 'color';
+export interface BatcherSubscriber {
+    markDirty(instance: Instance, type: DirtyType): void;
+    markShadowChange(instance: Instance): void;
+    removeInstance(instance: Instance): void;
+}
+export interface BatcherOptions {
+    overAllocation?: number;
+    initialCapacity?: number;
+    frustumCulling?: boolean;
+    customDepthMaterial?: THREE.Material;
+    customDistanceMaterial?: THREE.Material;
+}
+export interface BatchGroup {
+    key: string;
+    mesh: THREE.InstancedMesh;
+    instances: (Instance | null)[];
+    indexMap: Map<Instance, number>;
+    dirtyIndices: Set<number>;
+    dirtyColors: Set<number>;
+    emptySlots: number[];
+    frustumVisible: Set<number>;
+    hasDirty: boolean;
+    capacity: number;
+    count: number;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "three-instance-batch",
+  "version": "0.1.0",
+  "description": "Declarative instanced rendering for Three.js — Instance describes what, InstanceBatcher decides how to draw",
+  "type": "module",
+  "main": "./dist/three-instance-batch.js",
+  "module": "./dist/three-instance-batch.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/three-instance-batch.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && esbuild dist/three-instance-batch.js --minify --format=esm --outfile=dist/three-instance-batch.js --allow-overwrite && tsc --emitDeclarationOnly",
+    "prepublishOnly": "npm run test:run && npm run build",
+    "preview": "vite preview",
+    "test": "vitest --config vitest.config.ts",
+    "test:run": "vitest run --config vitest.config.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xier123456/three-instance-batch"
+  },
+  "author": "xier123456",
+  "bugs": {
+    "url": "https://github.com/xier123456/three-instance-batch/issues"
+  },
+  "peerDependencies": {
+    "three": ">=0.152.0"
+  },
+  "devDependencies": {
+    "@types/three": "^0.183.0",
+    "esbuild": "^0.28.0",
+    "three": "^0.183.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "three.js",
+    "instanced-mesh",
+    "batching",
+    "rendering"
+  ],
+  "license": "MIT"
+}