@vulfram/gltf-loader 0.22.5-alpha → 0.23.0-beta

package/README.md

@@ -3,4 +3,25 @@
 Loads `.gltf` and `.glb` content into `@vulfram/engine` 3D worlds.
 
 The loader follows the engine host-side math convention and exposes transforms as
-`gl-matrix` `vec3` / `quat`.
+`@vulfram/engine/math` `vec3` / `quat`.
+
+## Example
+
+```ts
+import { loadGltfAsset } from '@vulfram/gltf-loader';
+
+const asset = await loadGltfAsset({
+  worldId,
+  data: glbBytes
+});
+
+const instance = asset.instantiate({
+  rootTransform: {
+    position: [0, 0, 0]
+  }
+});
+
+// Later:
+instance.disposeEntities();
+asset.disposeAll();
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vulfram/gltf-loader",
-  "version": "0.22.5-alpha",
+  "version": "0.23.0-beta",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,12 +19,11 @@
   },
   "devDependencies": {
     "@types/bun": "^1.3.11",
-    "@vulfram/engine": "^0.22.5-alpha"
+    "@vulfram/engine": "^0.23.0-beta"
   },
   "dependencies": {
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
-    "@gltf-transform/functions": "^4.3.0",
-    "gl-matrix": "^3.4.4"
+    "@gltf-transform/functions": "^4.3.0"
   }
 }

package/src/convert.ts

@@ -1,12 +1,5 @@
 import { Accessor, TextureInfo } from '@gltf-transform/core';
-import {
-  quat,
-  vec3,
-  vec4,
-  type quat as Quat,
-  type vec3 as Vec3,
-  type vec4 as Vec4
-} from 'gl-matrix';
+import { quat, vec3, vec4, type Quat, type Vec3, type Vec4 } from '@vulfram/engine/math';
 import type { GeometryPrimitiveEntry, SamplerMode } from '@vulfram/engine/types';
 import { U16_MAX } from './constants';
 import { GltfLoaderError } from './errors';

package/src/errors.ts

@@ -1,6 +1,21 @@
 import type { GltfLoaderErrorCode } from './types';
 
-/** Loader error with stable error code for callers. */
+/**
+ * Loader error with a stable error code for caller handling.
+ *
+ * @example
+ * ```ts
+ * import { GltfLoaderError, loadGltfAsset } from '@vulfram/gltf-loader';
+ *
+ * try {
+ *   await loadGltfAsset({ worldId, data });
+ * } catch (error) {
+ *   if (error instanceof GltfLoaderError) {
+ *     console.error(error.code, error.message);
+ *   }
+ * }
+ * ```
+ */
 export class GltfLoaderError extends Error {
   constructor(
     public readonly code: GltfLoaderErrorCode,

package/src/index.ts

@@ -32,6 +32,22 @@ export { GltfLoaderError } from './errors';
  *
  * The returned asset can instantiate entity graphs multiple times, reusing
  * uploaded textures/materials/geometries across instances.
+ *
+ * @example
+ * ```ts
+ * import { loadGltfAsset } from '@vulfram/gltf-loader';
+ *
+ * const asset = await loadGltfAsset({
+ *   worldId,
+ *   data: glbBytes
+ * });
+ *
+ * const instance = asset.instantiate({
+ *   rootTransform: {
+ *     position: [0, 0, 0]
+ *   }
+ * });
+ * ```
  */
 export async function loadGltfAsset(input: GltfLoadInput): Promise<LoadedGltfAsset> {
   const document = await readDocument(input);
@@ -107,6 +123,19 @@ export async function loadGltfAsset(input: GltfLoadInput): Promise<LoadedGltfAss
  * Legacy one-shot API.
  *
  * Loads resources and immediately instantiates one entity graph.
+ *
+ * Use this when you only need one scene instance and do not need to keep the
+ * reusable asset template around.
+ *
+ * @example
+ * ```ts
+ * import { loadGltfScene } from '@vulfram/gltf-loader';
+ *
+ * const result = await loadGltfScene({
+ *   worldId,
+ *   data: glbBytes
+ * });
+ * ```
  */
 export async function loadGltfScene(input: GltfLoadInput): Promise<GltfLoadResult> {
   const asset = await loadGltfAsset(input);

package/src/resources.ts

@@ -7,7 +7,7 @@ import {
   type MaterialId,
   type TextureId
 } from '@vulfram/engine/world3d';
-import { vec4 } from 'gl-matrix';
+import { vec4 } from '@vulfram/engine/math';
 import type { GeometryPrimitiveEntry } from '@vulfram/engine/types';
 import { uploadBytes } from './context';
 import {

package/src/scene.ts

@@ -1,5 +1,5 @@
 import type { Node, Scene } from '@gltf-transform/core';
-import type { quat as Quat, vec3 as Vec3 } from 'gl-matrix';
+import type { Quat, Vec3 } from '@vulfram/engine/math';
 import {
   create3DEntity,
   create3DModel,

package/src/types.ts

@@ -1,5 +1,5 @@
 import type { Accessor, Material, Node, Primitive, Texture } from '@gltf-transform/core';
-import type { quat, vec3 } from 'gl-matrix';
+import type { Quat as quat, Vec3 as vec3 } from '@vulfram/engine/math';
 import type {
   EntityId,
   GeometryId,
@@ -26,7 +26,12 @@ export interface GltfInstantiateOptions {
   rootTransform?: RootTransform;
 }
 
-/** One instantiated scene graph from a loaded glTF asset. */
+/**
+ * One instantiated scene graph from a loaded glTF asset.
+ *
+ * The instance owns only its created entities. Shared resources remain owned by
+ * the parent `LoadedGltfAsset` until `disposeAll()` is called there.
+ */
 export interface GltfInstance {
   rootEntityId: EntityId;
   entityIds: EntityId[];
@@ -59,7 +64,13 @@ export interface LoadedResourceIds {
   textures: TextureId[];
 }
 
-/** Loaded glTF asset with reusable resources and instantiation API. */
+/**
+ * Loaded glTF asset with reusable resources and instantiation API.
+ *
+ * Use `instantiate()` to create one or more entity graphs, `disposeEntities()`
+ * to remove only active instances, and `disposeAll()` to also release the shared
+ * textures, materials, and geometries created for this asset.
+ */
 export interface LoadedGltfAsset {
   worldId: World3DId;
   warnings: string[];
@@ -70,7 +81,13 @@ export interface LoadedGltfAsset {
   disposeAll(): void;
 }
 
-/** Input descriptor for glTF/GLB loading. */
+/**
+ * Input descriptor for glTF/GLB loading.
+ *
+ * `data` is the main `.glb` or `.gltf` payload. When loading external-buffer or
+ * external-texture `.gltf` files, provide the extra file contents in `resources`
+ * keyed by their URI.
+ */
 export interface GltfLoadInput {
   worldId: World3DId;
   data: BinaryLike;
@@ -81,7 +98,7 @@ export interface GltfLoadInput {
   labelPrefix?: string;
 }
 
-/** Result summary for a loaded glTF scene. */
+/** Result summary for the legacy one-shot `loadGltfScene()` API. */
 export interface GltfLoadResult {
   rootEntityId: EntityId;
   entityCount: number;