soonspacejs 2.16.8 → 3.0.0-alpha.1

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "soonspacejs",
-  "version": "2.16.8",
+  "version": "3.0.0-alpha.1",
   "homepage": "https://www.xwbuilders.com/soonspacejs/",
-  "description": "soonspacejs 2.x",
+  "description": "SoonSpace.js 3.0 alpha",
   "module": "./dist/index.esm.js",
   "main": "./dist/index.esm.js",
   "types": "./types/index.d.ts",
@@ -25,11 +25,15 @@
   ],
   "author": "xunwei",
   "license": "UNLICENSED",
+  "dependencies": {
+    "@robotlegsjs/signals": "^2.1.0",
+    "localforage": "1.10.0"
+  },
   "peerDependencies": {
-    "@types/three": ">=0.185.4",
+    "@types/three": ">=0.186.0",
     "camera-controls": ">=3.1.2",
-    "postprocessing": ">=6.39.4",
-    "three": ">=0.185.1",
+    "postprocessing": ">=6.39.5",
+    "three": ">=0.186.1",
     "three-mesh-bvh": ">=0.9.9"
   },
   "gitHead": "4a87dd85050651088e11c3da777c49fab3db7e5d"

package/types/Entity/CachedBatchedMesh.d.ts

@@ -0,0 +1,38 @@
+import { BatchedMesh, Matrix4, BufferGeometry } from 'three';
+/** Entity-owned batches reuse only the commands left by the immediately preceding pass. */
+export declare class CachedBatchedMesh extends BatchedMesh {
+    private commandRevision;
+    private cachedRevision;
+    private cachedCamera?;
+    private cachedGeometry?;
+    private cachedPosition?;
+    private cachedPositionVersion;
+    private cachedIndex?;
+    private cachedIndexVersion;
+    private cachedIndexArray?;
+    private cachedCoordinateSystem?;
+    private cachedReversedDepth?;
+    private cachedSort?;
+    private cachedCull?;
+    private cachedTransparent?;
+    private cachedWireframe?;
+    private readonly cachedWorld;
+    private readonly cachedCameraWorld;
+    private readonly cachedView;
+    private readonly cachedProjection;
+    invalidateDrawCommands(): void;
+    onBeforeRender(...args: Parameters<BatchedMesh['onBeforeRender']>): void;
+    private rebuildDrawCommands;
+    setMatrixAt(instanceId: number, matrix: Matrix4): this;
+    setVisibleAt(instanceId: number, visible: boolean): this;
+    setGeometryIdAt(instanceId: number, geometryId: number): this;
+    addInstance(geometryId: number): number;
+    deleteInstance(instanceId: number): this;
+    addGeometry(geometry: BufferGeometry, reservedVertices?: number, reservedIndices?: number): number;
+    setGeometryAt(geometryId: number, geometry: BufferGeometry): number;
+    deleteGeometry(geometryId: number): this;
+    optimize(): this;
+    setGeometrySize(maxVertices: number, maxIndices: number): void;
+    setInstanceCount(maxInstances: number): void;
+    copy(source: this): this;
+}

package/types/Entity/Entity.d.ts

@@ -0,0 +1,41 @@
+import { Matrix4, Object3D, Quaternion, Vector3 } from 'three';
+import { ModelLease, ModelLoadOptions } from './ModelResources';
+import { EntityCollection } from './EntityCollection';
+export type EntityChange = 'transform' | 'visibility';
+export interface EntityOptions {
+    id: string;
+    model?: ModelLease;
+    parent?: Entity | null;
+    owner?: string;
+    name?: string;
+    position?: readonly [number, number, number];
+    quaternion?: readonly [number, number, number, number];
+    scale?: readonly [number, number, number];
+    visible?: boolean;
+    /** Own model and native attachments only; descendants keep their hierarchical visibility. */
+    contentVisible?: boolean;
+}
+/** Logical identity. Editable fields are drafts; notifications capture snapshots. */
+export declare class Entity {
+    private collection;
+    readonly position: Vector3;
+    readonly quaternion: Quaternion;
+    readonly scale: Vector3;
+    visible: boolean;
+    /** Draft value committed together with visible by notifyChange( 'visibility' ). */
+    contentVisible: boolean;
+    name: string;
+    readonly id: string;
+    readonly owner: string;
+    constructor(collection: EntityCollection, options: EntityOptions);
+    get parent(): Entity | null;
+    get children(): readonly Entity[];
+    get isShowing(): boolean;
+    get loadState(): "error" | "idle" | "loading" | "ready";
+    get loadError(): unknown;
+    replaceModel(source: ModelLease | string | null, options?: ModelLoadOptions): Promise<void>;
+    notifyChange(type: EntityChange): void;
+    getWorldMatrix(): Matrix4;
+    attachObject3D(object: Object3D): void;
+    detachObject3D(object: Object3D): void;
+}

package/types/Entity/EntityCollection.d.ts

@@ -0,0 +1,62 @@
+import { Box3, Matrix4, Object3D, Raycaster, Scene } from 'three';
+import { Entity, EntityChange, EntityOptions } from './Entity';
+import { EntityHit } from './EntityRenderer';
+import { ModelResources, ModelLease, ModelLoadOptions } from './ModelResources';
+import { TransparentSideVariants } from './TransparentSideVariants';
+export declare class EntityCollection {
+    private scene;
+    private requestRender;
+    private models;
+    private nodes;
+    private ids;
+    private pending;
+    private structureDirty;
+    private attachmentOwners;
+    private renderer;
+    private disposed;
+    private batchDepth;
+    private updatedEntities;
+    private pendingModels;
+    private selected;
+    private selectionDirty;
+    constructor(scene: Scene, requestRender: () => void, models: ModelResources, sideVariants?: Pick<TransparentSideVariants, 'register' | 'unregister'>);
+    get roots(): readonly Entity[];
+    getById(id: string): Entity | undefined;
+    parentOf(entity: Entity): Entity | null;
+    childrenOf(entity: Entity): readonly Entity[];
+    showing(entity: Entity): boolean;
+    worldOf(entity: Entity): Matrix4;
+    private node;
+    add(options: EntityOptions): Entity;
+    notify(entity: Entity, type: EntityChange): void;
+    private schedule;
+    getLoadState(entity: Entity): "error" | "idle" | "loading" | "ready";
+    getLoadError(entity: Entity): unknown;
+    /** Resolve a candidate without releasing or modifying the currently drawn model. */
+    replaceModel(entity: Entity, source: ModelLease | string | null, options?: ModelLoadOptions): Promise<void>;
+    setParent(entity: Entity, parent: Entity | null): void;
+    remove(entity: Entity): void;
+    private deferredReleases;
+    batch(callback: () => void): void;
+    flushUpdates(): void;
+    attach(entity: Entity, object: Object3D): void;
+    detach(entity: Entity, object: Object3D): void;
+    pick(raycaster: Raycaster): EntityHit[];
+    /** Fresh world bounds from committed transforms, including hidden content. */
+    getBounds(entity: Entity, options?: {
+        includeDescendants?: boolean;
+    }): Box3;
+    getStats(): {
+        updatedEntities: number;
+        entities: number;
+        instancedBatches: number;
+        batchedBatches: number;
+        independentObjects: number;
+        rebuilds: number;
+    };
+    setSelection(entities: readonly Entity[]): void;
+    getSelection(): readonly Entity[];
+    setInstancingEnabled(enabled: boolean): void;
+    setBatchedEnabled(enabled: boolean): void;
+    dispose(): void;
+}

package/types/Entity/EntityRenderer.d.ts

@@ -0,0 +1,58 @@
+import { Box3, Group, Matrix4, Raycaster, Intersection } from 'three';
+import { Entity } from './Entity';
+import { RegisteredPart } from './ModelResources';
+import { TransparentSideVariants } from './TransparentSideVariants';
+export interface EntityRenderInput {
+    entity: Entity;
+    parts: readonly RegisteredPart[];
+    world: Matrix4;
+    visible: boolean;
+    contentVisible: boolean;
+}
+export interface EntityHit extends Intersection {
+    entity: Entity;
+    partIndex?: number;
+    attachment?: boolean;
+}
+export declare class EntityRenderer {
+    private readonly sideVariants?;
+    readonly root: Group<import('three').Object3DEventMap>;
+    private entries;
+    private batches;
+    private mappings;
+    private groups;
+    private groupBatches;
+    private dirtyGroups;
+    private policyDirty;
+    private bounds;
+    private enabled;
+    private batchedEnabled;
+    private rebuilds;
+    private selection;
+    private selectionDirty;
+    private highlights;
+    private highlightMaterial;
+    constructor(sideVariants?: Pick<TransparentSideVariants, "register" | "unregister"> | undefined);
+    add(input: EntityRenderInput): void;
+    remove(entity: Entity): void;
+    setEnabled(enabled: boolean): void;
+    setBatchedEnabled(enabled: boolean): void;
+    setSelection(selection: ReadonlySet<Entity>): void;
+    private removeHighlight;
+    private updateHighlight;
+    update(changed: readonly Entity[]): void;
+    private assignGroup;
+    private rebuildGroup;
+    private createBatch;
+    private updateBatch;
+    pick(raycaster: Raycaster): EntityHit[];
+    getBounds(entity: Entity): Box3;
+    getStats(): {
+        instancedBatches: number;
+        batchedBatches: number;
+        independentObjects: number;
+        rebuilds: number;
+    };
+    private clearBatches;
+    dispose(): void;
+}

package/types/Entity/ModelResources.d.ts

@@ -0,0 +1,83 @@
+import { BufferGeometry, Material, Matrix4, Texture } from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+export interface ModelPart {
+    geometry: BufferGeometry;
+    material: Material | MaterialLease;
+    matrix: Matrix4;
+    visible?: boolean;
+    name?: string;
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+    renderOrder?: number;
+    layersMask?: number;
+    frustumCulled?: boolean;
+    /** Explicitly accept batch-local transparent sorting; cross-batch order is not preserved. */
+    transparentBatch?: 'sorted';
+    /** Linear RGB multiplier, applied without modifying the shared material. */
+    color?: readonly [number, number, number];
+}
+export interface RegisteredPart extends Omit<ModelPart, 'material'> {
+    material: Material;
+}
+interface ResourceRecord<T> {
+    value: T;
+    refs: number;
+    dead: boolean;
+    gpu: Set<BufferGeometry | Material | Texture>;
+    dependencies: Set<ResourceRecord<Material>>;
+}
+export declare class ResourceLease<T> {
+    readonly registry: ModelResources;
+    private record;
+    private released;
+    constructor(registry: ModelResources, record: ResourceRecord<T>);
+    /** Internal ownership boundary; callers cannot retain a released lease. */
+    retain(): ResourceLease<T>;
+    get value(): T;
+    release(): void;
+    assertActive(): void;
+}
+export type ModelLease = ResourceLease<readonly RegisteredPart[]>;
+export type MaterialLease = ResourceLease<Material>;
+export interface ModelLoadOptions {
+    signal?: AbortSignal;
+}
+export type UnsupportedModelReason = 'animation-clips' | 'material-array' | 'skinning' | 'morph-targets' | 'instanced-mesh' | 'batched-mesh' | 'line-or-points';
+/** A decoded resource that cannot be faithfully represented by static model parts. */
+export declare class ModelResourceUnsupportedError extends Error {
+    readonly url: string;
+    readonly code = "MODEL_RESOURCE_UNSUPPORTED";
+    readonly reasons: readonly UnsupportedModelReason[];
+    constructor(url: string, reasons: readonly UnsupportedModelReason[]);
+}
+export declare function entityAbortError(): DOMException;
+/** Owns transferred GPU graphs. Does not add loaded source trees to the Scene. */
+export declare class ModelResources {
+    isDisposed: boolean;
+    private records;
+    private gpuRefs;
+    private transferred;
+    private pending;
+    private urls;
+    private gltfLoader;
+    /** Borrow a host-configured loader; its decoder workers remain host-owned. */
+    setGLTFLoader(loader: GLTFLoader): void;
+    readonly materials: {
+        register: (material: Material, options: {
+            ownership: "transfer";
+        }) => MaterialLease;
+    };
+    register(input: {
+        parts: readonly ModelPart[];
+    }, options: {
+        ownership: 'transfer';
+    }): ModelLease;
+    load(url: string, options?: ModelLoadOptions): Promise<ModelLease>;
+    private resolveLoad;
+    private create;
+    lease<T>(record: ResourceRecord<T>): ResourceLease<T>;
+    release(record: ResourceRecord<unknown>): void;
+    private assertLive;
+    dispose(): void;
+}
+export {};

package/types/Entity/TransparentSideVariants.d.ts

@@ -0,0 +1,27 @@
+import { Mesh, WebGLRenderer } from 'three';
+/** Reuse immutable side-specific programs for Entity-owned Standard materials.
+ * Only reuse materials with at least two registered supported users. Registration
+ * count is not visible draw count: a hidden/culled second user still enables reuse.
+ * Three still chooses each object's two passes and the complete render-list order.
+ */
+export declare class TransparentSideVariants {
+    private readonly renderer;
+    private readonly objects;
+    private readonly records;
+    private sequence;
+    private epoch;
+    private enabled;
+    private disposed;
+    private readonly render;
+    private readonly direct;
+    private readonly wrappedRender;
+    private readonly wrappedDirect;
+    constructor(renderer: WebGLRenderer);
+    private supported;
+    register(mesh: Mesh): void;
+    unregister(mesh: Mesh): void;
+    private sync;
+    setEnabled(enabled: boolean): void;
+    private release;
+    dispose(): void;
+}

package/types/Entity/index.d.ts

@@ -0,0 +1,6 @@
+export { Entity, } from './Entity';
+export type { EntityOptions, EntityChange, } from './Entity';
+export { EntityCollection, } from './EntityCollection';
+export { ModelResources, ResourceLease, ModelResourceUnsupportedError, } from './ModelResources';
+export type { ModelLease, MaterialLease, ModelPart, ModelLoadOptions, UnsupportedModelReason, } from './ModelResources';
+export type { EntityHit, } from './EntityRenderer';

package/types/Entity/pick-clipping.d.ts

@@ -0,0 +1,3 @@
+import { Intersection, Plane } from 'three';
+/** Test world-space hit points using the submitted material's clipping policy. */
+export declare function isEntityHitUnclipped(hit: Intersection, worldPlanes?: readonly Plane[]): boolean;

package/types/Loader/scoped-gltf.d.ts

@@ -0,0 +1,12 @@
+import { GLTF, GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+interface RequestScope {
+    rootURL: string;
+    headers: HeadersInit;
+    signal?: AbortSignal;
+}
+/** Each standard GLTFLoader parse constructs its parser synchronously, before any await. */
+export declare function parseScopedGLTF(loader: GLTFLoader, data: ArrayBuffer, path: string, scope: RequestScope): Promise<{
+    gltf: GLTF;
+    dependencyError?: unknown;
+}>;
+export {};

package/types/Shared/viewport.d.ts

@@ -7,7 +7,7 @@ declare function IVector3ToEuler(val: IVector3 | Euler): Euler;
  * @param object
  * @returns
  */
-declare function getBoundingBox(object: Object3D, precise?: boolean, cachedBounds?: Box3 | null): Box3;
+declare function getBoundingBox(object: Object3D, precise?: boolean): Box3;
 declare function rotationAxisFix(axis: AxisType, source: Euler, target: Euler): Euler;
 declare function rotationAFix(source: Euler, target: Euler): Euler;
 declare function deg2Euler(deg: number): number;

package/types/Viewport/Scener.d.ts

@@ -25,7 +25,9 @@ declare class Scener {
     constructor(signals: SignalsState, viewportState: ViewportState);
     addObject(object: Object3D, parent?: Object3D | null): void;
     attachObject(object: Object3D, parent?: Object3D | null): void;
-    removeObject(object: Object3D): void;
+    removeObject(object: Object3D, options?: {
+        dispose?: boolean;
+    }): void;
     openSceneFog(options?: FogOptions): void;
     closeSceneFog(): void;
     edgeShow(object: Object3D | Object3D[], options?: EdgeSelectOptions): Promise<void>;

package/types/Viewport/index.d.ts

@@ -16,7 +16,7 @@ import { default as EventHandler } from './EventHandler';
 import { default as Info } from './Info';
 import { ViewHelper } from './ViewHelper';
 import { ObjectsCache } from '../Cache';
-import { default as AutoInstancingManager, AutoInstancingOptions, AutoInstancingStats } from './AutoInstancingManager';
+import { EntityCollection, ModelResources } from '../Entity';
 export declare const innerRenderState: {
     needsUpdate: boolean;
 };
@@ -36,7 +36,9 @@ declare class Viewport {
     renderer: WebGLRenderer;
     rendererCSS2D: CSS2DRenderer;
     rendererCSS3D: CSS3DRenderer;
-    autoInstancingManager: AutoInstancingManager;
+    readonly models: ModelResources;
+    readonly entities: EntityCollection;
+    private readonly transparentSideVariants;
     pmremGenerator: PMREMGenerator;
     info: Info;
     stats: Stats;
@@ -59,14 +61,11 @@ declare class Viewport {
      */
     postRender: Map<string | number, () => void>;
     private _loop;
-    private outlineSelection;
     private pendingRenderResolvers;
     resizeObserver: ResizeObserver;
     constructor(options: ViewportOptions, signals: SignalsState, cache: ObjectsCache);
     _initInfo(): void;
     _initStats(): void;
-    setAutoInstancing(enabled: boolean, root?: Object3D, options?: AutoInstancingOptions): void;
-    getAutoInstancingStats(root?: Object3D): AutoInstancingStats | AutoInstancingStats[] | null;
     /**
      ***************************** post-processing ***************************
      */
@@ -116,7 +115,6 @@ declare class Viewport {
      * effect passes
      */
     _passesObserver(): void;
-    private _syncAutoInstancingOutlineSelection;
     /**
      * 每帧都会被执行
      * @param time