@mochiya/avatar-composition 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -73,6 +73,30 @@ Delete uses the loaded base mesh's position deltas and restores polygons when di
73
73
 
74
74
  This record belongs in `components` and assumes node 12 exists in the file. Bone pairs are computed at runtime. See the [behavior specification](https://github.com/mochiya-labs/avatar-composition/blob/main/specification/README.md) for defaults, conditions, matching and evaluation order, and the [JSON Schema](https://github.com/mochiya-labs/avatar-composition/blob/main/schema/MOCHIYA_avatar_composition.schema.json) for structure. The JSON Schema is included in `dist/`.
75
75
 
76
+ ## Custom runtime loaders
77
+
78
+ Custom loaders can construct an editable asset from initialized Three.js objects without a GLTFParser:
79
+
80
+ ```ts
81
+ import {
82
+ createAvatarAsset,
83
+ AvatarComposition,
84
+ } from "@mochiya/avatar-composition";
85
+
86
+ const asset = createAvatarAsset(scene, {
87
+ vrm,
88
+ nodes: authoredNodes,
89
+ materials,
90
+ primitiveSlots,
91
+ resources: { geometries, materials, textures, skeletons, imageBitmaps },
92
+ });
93
+ const composition = new AvatarComposition(asset);
94
+ ```
95
+
96
+ `nodes` maps stable authored indices to runtime objects. `primitiveSlots` maps primitive meshes to their material-slot indices. Optional `manifest`, `aliases`, `sourceNames` and `authoredObjects` preserve creator controls, names and logical object grouping. Complete hierarchy, skin, material and VRM initialization before constructing the asset; this entry point does not parse source files or initialize those libraries.
97
+
98
+ Explicit `resources` transfers disposal responsibility for the listed resources to the asset. Omit shared resources owned by another host. Without an explicit resource list, geometry, skeleton and material ownership is inferred from the scene; textures and decoded images must be supplied when asset-owned. Composition borrows the asset: dispose the composition or remove the attachment before calling `asset.dispose()`.
99
+
76
100
  ## Install
77
101
 
78
102
  Install the published package in your application with compatible peer dependencies:
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { Object3D, Mesh, AnimationClip } from 'three';
1
+ import { BufferGeometry, Skeleton, Material, Texture, Object3D, Mesh, AnimationClip } from 'three';
2
2
  import { VRM } from '@pixiv/three-vrm';
3
3
  import { GLTFLoaderPlugin, GLTFParser, GLTF } from 'three/addons/loaders/GLTFLoader.js';
4
4
 
@@ -153,6 +153,16 @@ interface CompositionWarning {
153
153
  candidates?: string[];
154
154
  }
155
155
 
156
+ /** Explicit ownership; shared resources can be omitted and disposed by their host. */
157
+ interface AvatarAssetResources {
158
+ geometries?: Iterable<BufferGeometry>;
159
+ skeletons?: Iterable<Skeleton>;
160
+ materials?: Iterable<Material>;
161
+ textures?: Iterable<Texture>;
162
+ /** Decoded images owned by the asset; shared images close after their last asset. */
163
+ imageBitmaps?: Iterable<ImageBitmap>;
164
+ }
165
+
156
166
  interface ResolvedOperation {
157
167
  componentId: string;
158
168
  operation: string;
@@ -233,6 +243,20 @@ interface AvatarGLTF extends GLTF {
233
243
  avatar: AvatarAsset;
234
244
  };
235
245
  }
246
+ /** Runtime inputs for custom asset loaders; no GLTFParser is required. */
247
+ interface AvatarAssetInput {
248
+ vrm?: VRM;
249
+ manifest?: ManifestInput;
250
+ nodes?: Map<number, Object3D>;
251
+ materials?: Material[];
252
+ aliases?: Map<Object3D, string[]>;
253
+ authoredObjects?: Set<Object3D>;
254
+ primitiveSlots?: Map<Mesh, number>;
255
+ sourceNames?: Map<Object3D, string>;
256
+ resources?: AvatarAssetResources;
257
+ }
258
+ /** Construct an editable asset from fully initialized runtime objects. */
259
+ declare function createAvatarAsset(scene: Object3D, input?: AvatarAssetInput): AvatarAsset;
236
260
  /** Register with GLTFLoader. Read userData.avatar only after loading completes. */
237
261
  declare class AvatarCompositionLoaderPlugin implements GLTFLoaderPlugin {
238
262
  readonly parser: GLTFParser;
@@ -259,4 +283,4 @@ declare class AvatarComposition {
259
283
  dispose(): void;
260
284
  }
261
285
 
262
- export { ASSET_KINDS, type AvatarAsset, AvatarComposition, AvatarCompositionLoaderPlugin, type AvatarCompositionManifest, type AvatarControl, type AvatarGLTF, type AvatarInspection, type AvatarItem, type AvatarMorph, type BlendshapeSync, type BoneProxy, CAPABILITIES, type CompositionComponent, CompositionError, type CompositionWarning, type Condition, EXTENSION_NAME, type ManifestInput, type MaterialSetter, type MenuItem, type MergeArmature, type MorphEditResult, type ObjectToggle, type RemapCurve, type ResolvedOperation, SPEC_VERSION, type Selector, type ShapeChanger, parseManifest };
286
+ export { ASSET_KINDS, type AvatarAsset, type AvatarAssetInput, type AvatarAssetResources, AvatarComposition, AvatarCompositionLoaderPlugin, type AvatarCompositionManifest, type AvatarControl, type AvatarGLTF, type AvatarInspection, type AvatarItem, type AvatarMorph, type BlendshapeSync, type BoneProxy, CAPABILITIES, type CompositionComponent, CompositionError, type CompositionWarning, type Condition, EXTENSION_NAME, type ManifestInput, type MaterialSetter, type MenuItem, type MergeArmature, type MorphEditResult, type ObjectToggle, type RemapCurve, type ResolvedOperation, SPEC_VERSION, type Selector, type ShapeChanger, createAvatarAsset, parseManifest };
package/dist/index.js CHANGED
@@ -1,5 +1,7 @@
1
1
  // src/api.ts
2
- import { MathUtils } from "three";
2
+ import {
3
+ MathUtils
4
+ } from "three";
3
5
 
4
6
  // src/schema.ts
5
7
  import { z } from "zod";
@@ -1910,6 +1912,14 @@ var AvatarCompositionSession = class {
1910
1912
  };
1911
1913
 
1912
1914
  // src/api.ts
1915
+ function createAvatarAsset(scene, input = {}) {
1916
+ const asset = new AvatarAsset(scene, input);
1917
+ for (const [mesh, slot] of input.primitiveSlots ?? [])
1918
+ asset.primitiveSlots.set(mesh, slot);
1919
+ for (const [object, name] of input.sourceNames ?? [])
1920
+ asset.sourceNames.set(object, name);
1921
+ return new Asset(asset);
1922
+ }
1913
1923
  var data = /* @__PURE__ */ new WeakMap();
1914
1924
  var sessions = /* @__PURE__ */ new WeakMap();
1915
1925
  var controls = /* @__PURE__ */ new WeakMap();
@@ -2207,5 +2217,6 @@ export {
2207
2217
  CompositionError,
2208
2218
  EXTENSION_NAME,
2209
2219
  SPEC_VERSION,
2220
+ createAvatarAsset,
2210
2221
  parseManifest
2211
2222
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mochiya/avatar-composition",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Avatar and attachment composition for Three.js and the MOCHIYA_avatar_composition glTF extension",
5
5
  "type": "module",
6
6
  "license": "MIT",