@mochiya/avatar-composition 0.1.1 → 0.1.2
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/LICENSE +21 -21
- package/README.md +262 -258
- package/dist/index.d.ts +3 -0
- package/dist/index.js +95 -6
- package/dist/specification/README.md +152 -152
- package/package.json +74 -74
package/dist/index.js
CHANGED
|
@@ -214,6 +214,7 @@ var MochiyaAvatarCompositionLoaderPlugin = class {
|
|
|
214
214
|
if (value) gltf.userData.mochiyaAvatarComposition = parseManifest(value);
|
|
215
215
|
}
|
|
216
216
|
};
|
|
217
|
+
var imageOwners = /* @__PURE__ */ new WeakMap();
|
|
217
218
|
var AvatarAsset = class {
|
|
218
219
|
constructor(scene, options = {}) {
|
|
219
220
|
this.scene = scene;
|
|
@@ -255,6 +256,7 @@ var AvatarAsset = class {
|
|
|
255
256
|
...resources.materials ?? [],
|
|
256
257
|
...resources.textures ?? []
|
|
257
258
|
]);
|
|
259
|
+
this.imageBitmaps = new Set(resources.imageBitmaps ?? []);
|
|
258
260
|
if (options.nodes)
|
|
259
261
|
for (const [index2, node] of options.nodes) this.nodes.set(index2, node);
|
|
260
262
|
for (const [index2, node] of this.nodes) this.indices.set(node, index2);
|
|
@@ -267,9 +269,12 @@ var AvatarAsset = class {
|
|
|
267
269
|
this.authoredActive.set(node, entry.active);
|
|
268
270
|
node.visible = entry.active;
|
|
269
271
|
}
|
|
272
|
+
for (const image of this.imageBitmaps)
|
|
273
|
+
imageOwners.set(image, (imageOwners.get(image) ?? 0) + 1);
|
|
270
274
|
}
|
|
271
275
|
scene;
|
|
272
276
|
resources;
|
|
277
|
+
imageBitmaps;
|
|
273
278
|
disposed = false;
|
|
274
279
|
meshes = [];
|
|
275
280
|
bones = [];
|
|
@@ -309,7 +314,9 @@ async function prepareAvatarAsset(gltf) {
|
|
|
309
314
|
aliases.set(node, [parser.json.nodes?.[index2]?.name ?? ""]);
|
|
310
315
|
});
|
|
311
316
|
const materials = await parser.getDependencies("material");
|
|
312
|
-
const textures = new Set(
|
|
317
|
+
const textures = /* @__PURE__ */ new Set();
|
|
318
|
+
for (const resource of parser.associations.keys())
|
|
319
|
+
if (resource.isTexture) textures.add(resource);
|
|
313
320
|
const authoredObjects = /* @__PURE__ */ new Set([gltf.scene, ...nodes.values()]);
|
|
314
321
|
const meshes = [];
|
|
315
322
|
gltf.scene.traverse((node) => {
|
|
@@ -341,7 +348,10 @@ async function prepareAvatarAsset(gltf) {
|
|
|
341
348
|
geometries: meshes.map((m) => m.geometry),
|
|
342
349
|
skeletons: meshes.filter((m) => !!m.isSkinnedMesh).map((m) => m.skeleton),
|
|
343
350
|
materials: ownedMaterials,
|
|
344
|
-
textures
|
|
351
|
+
textures,
|
|
352
|
+
imageBitmaps: typeof ImageBitmap === "undefined" ? [] : [...textures].map((texture) => texture.image).filter(
|
|
353
|
+
(image) => image instanceof ImageBitmap
|
|
354
|
+
)
|
|
345
355
|
}
|
|
346
356
|
});
|
|
347
357
|
for (const mesh of asset.meshes) {
|
|
@@ -355,9 +365,35 @@ function disposeAvatarAsset(asset) {
|
|
|
355
365
|
if (asset.disposed) return;
|
|
356
366
|
asset.disposed = true;
|
|
357
367
|
asset.scene.removeFromParent();
|
|
358
|
-
|
|
359
|
-
|
|
368
|
+
const errors = [];
|
|
369
|
+
try {
|
|
370
|
+
asset.vrm?.springBoneManager?.reset();
|
|
371
|
+
} catch (error) {
|
|
372
|
+
errors.push(error);
|
|
373
|
+
}
|
|
374
|
+
asset.resources.forEach((resource) => {
|
|
375
|
+
try {
|
|
376
|
+
resource.dispose();
|
|
377
|
+
} catch (error) {
|
|
378
|
+
errors.push(error);
|
|
379
|
+
}
|
|
380
|
+
});
|
|
360
381
|
asset.resources.clear();
|
|
382
|
+
for (const image of asset.imageBitmaps) {
|
|
383
|
+
const remaining = (imageOwners.get(image) ?? 1) - 1;
|
|
384
|
+
if (remaining > 0) imageOwners.set(image, remaining);
|
|
385
|
+
else {
|
|
386
|
+
imageOwners.delete(image);
|
|
387
|
+
try {
|
|
388
|
+
image.close();
|
|
389
|
+
} catch (error) {
|
|
390
|
+
errors.push(error);
|
|
391
|
+
}
|
|
392
|
+
}
|
|
393
|
+
}
|
|
394
|
+
asset.imageBitmaps.clear();
|
|
395
|
+
if (errors.length)
|
|
396
|
+
throw new AggregateError(errors, "Asset resource cleanup failed");
|
|
361
397
|
}
|
|
362
398
|
|
|
363
399
|
// src/matching.ts
|
|
@@ -617,7 +653,12 @@ function operations(component, sourceOrder) {
|
|
|
617
653
|
}
|
|
618
654
|
|
|
619
655
|
// src/deletion.ts
|
|
620
|
-
import {
|
|
656
|
+
import {
|
|
657
|
+
BufferAttribute,
|
|
658
|
+
BufferGeometry,
|
|
659
|
+
InterleavedBuffer,
|
|
660
|
+
InterleavedBufferAttribute
|
|
661
|
+
} from "three";
|
|
621
662
|
var ShapeDeletion = class {
|
|
622
663
|
states = /* @__PURE__ */ new Map();
|
|
623
664
|
apply(requests, registered) {
|
|
@@ -703,7 +744,7 @@ var ShapeDeletion = class {
|
|
|
703
744
|
continue;
|
|
704
745
|
}
|
|
705
746
|
const selection = [...new Set(keys)].sort().join(";");
|
|
706
|
-
if (!state.copy) state.copy = source
|
|
747
|
+
if (!state.copy) state.copy = createIndexView(source);
|
|
707
748
|
if (selection !== state.selection) {
|
|
708
749
|
filterIndices(source, state.copy, masks);
|
|
709
750
|
state.selection = selection;
|
|
@@ -730,6 +771,54 @@ var ShapeDeletion = class {
|
|
|
730
771
|
this.states.clear();
|
|
731
772
|
}
|
|
732
773
|
};
|
|
774
|
+
function createIndexView(source) {
|
|
775
|
+
const view = new BufferGeometry();
|
|
776
|
+
const attributes = /* @__PURE__ */ new Map();
|
|
777
|
+
const interleaved = /* @__PURE__ */ new Map();
|
|
778
|
+
const share = (attribute) => {
|
|
779
|
+
const previous = attributes.get(attribute);
|
|
780
|
+
if (previous) return previous;
|
|
781
|
+
let result;
|
|
782
|
+
if ("data" in attribute) {
|
|
783
|
+
let data = interleaved.get(attribute.data);
|
|
784
|
+
if (!data) {
|
|
785
|
+
data = new InterleavedBuffer(
|
|
786
|
+
attribute.data.array,
|
|
787
|
+
attribute.data.stride
|
|
788
|
+
);
|
|
789
|
+
data.setUsage(attribute.data.usage);
|
|
790
|
+
interleaved.set(attribute.data, data);
|
|
791
|
+
}
|
|
792
|
+
result = new InterleavedBufferAttribute(
|
|
793
|
+
data,
|
|
794
|
+
attribute.itemSize,
|
|
795
|
+
attribute.offset,
|
|
796
|
+
attribute.normalized
|
|
797
|
+
);
|
|
798
|
+
} else {
|
|
799
|
+
result = new BufferAttribute(
|
|
800
|
+
attribute.array,
|
|
801
|
+
attribute.itemSize,
|
|
802
|
+
attribute.normalized
|
|
803
|
+
);
|
|
804
|
+
result.setUsage(attribute.usage);
|
|
805
|
+
result.gpuType = attribute.gpuType;
|
|
806
|
+
}
|
|
807
|
+
result.name = attribute.name;
|
|
808
|
+
attributes.set(attribute, result);
|
|
809
|
+
return result;
|
|
810
|
+
};
|
|
811
|
+
for (const [name, attribute] of Object.entries(source.attributes))
|
|
812
|
+
view.setAttribute(name, share(attribute));
|
|
813
|
+
for (const name of Object.keys(
|
|
814
|
+
source.morphAttributes
|
|
815
|
+
))
|
|
816
|
+
view.morphAttributes[name] = source.morphAttributes[name]?.map(share);
|
|
817
|
+
view.morphTargetsRelative = source.morphTargetsRelative;
|
|
818
|
+
view.boundingBox = source.boundingBox?.clone() ?? null;
|
|
819
|
+
view.boundingSphere = source.boundingSphere?.clone() ?? null;
|
|
820
|
+
return view;
|
|
821
|
+
}
|
|
733
822
|
function geometryStamp(g) {
|
|
734
823
|
const attributes = [
|
|
735
824
|
g.index,
|
|
@@ -1,152 +1,152 @@
|
|
|
1
|
-
# MOCHIYA_avatar_composition 0.1
|
|
2
|
-
|
|
3
|
-
Draft glTF 2.0 extension for composing an avatar with attachments. This document defines behavior; the [JSON Schema](../schema/MOCHIYA_avatar_composition.schema.json) defines JSON structure. The runtime's TypeScript schema generates that JSON Schema. Consumers also validate references and execution graphs.
|
|
4
|
-
|
|
5
|
-
The current draft replaces the earlier action/joint-mapping draft. Re-export older files. There is no legacy reader.
|
|
6
|
-
|
|
7
|
-
## Scope and placement
|
|
8
|
-
|
|
9
|
-
Put the extension on the glTF document root and list its name in `extensionsUsed`. A consumer without support can display the ordinary model. Do not depend on this extension for standard skinning, VRM expressions, physics or materials: those remain glTF/VRM data. Cross-asset collider linking is outside this specification.
|
|
10
|
-
|
|
11
|
-
```json
|
|
12
|
-
{
|
|
13
|
-
"extensionsUsed": ["MOCHIYA_avatar_composition"],
|
|
14
|
-
"extensions": {
|
|
15
|
-
"MOCHIYA_avatar_composition": {
|
|
16
|
-
"specVersion": "0.1",
|
|
17
|
-
"assetKind": "attachment",
|
|
18
|
-
"requiredCapabilities": ["mergeArmature", "shapeChanger"],
|
|
19
|
-
"components": [
|
|
20
|
-
{
|
|
21
|
-
"id": "coat-rig",
|
|
22
|
-
"type": "mergeArmature",
|
|
23
|
-
"sourceNode": 12,
|
|
24
|
-
"origin": "modularAvatar",
|
|
25
|
-
"target": {
|
|
26
|
-
"asset": "base",
|
|
27
|
-
"path": ["Armature"],
|
|
28
|
-
"boneKeywords": ["Armature"]
|
|
29
|
-
},
|
|
30
|
-
"prefix": "Coat_",
|
|
31
|
-
"lockMode": "unidirectional"
|
|
32
|
-
},
|
|
33
|
-
{
|
|
34
|
-
"id": "fit",
|
|
35
|
-
"type": "shapeChanger",
|
|
36
|
-
"sourceNode": 4,
|
|
37
|
-
"condition": { "type": "nodeActive", "node": 4 },
|
|
38
|
-
"shapes": [
|
|
39
|
-
{
|
|
40
|
-
"target": {
|
|
41
|
-
"asset": "base",
|
|
42
|
-
"meshKeywords": ["Body"],
|
|
43
|
-
"blendshapeKeywords": ["HideTorso"]
|
|
44
|
-
},
|
|
45
|
-
"changeType": "set",
|
|
46
|
-
"value": 1
|
|
47
|
-
}
|
|
48
|
-
]
|
|
49
|
-
}
|
|
50
|
-
]
|
|
51
|
-
}
|
|
52
|
-
}
|
|
53
|
-
}
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
The example assumes local nodes 4 and 12 exist in the containing glTF.
|
|
57
|
-
|
|
58
|
-
## Root and references
|
|
59
|
-
|
|
60
|
-
| Field | Meaning |
|
|
61
|
-
| ---------------------- | ------------------------------------------------------------------------------------------------ |
|
|
62
|
-
| `specVersion` | Required literal `"0.1"`. |
|
|
63
|
-
| `assetKind` | Required `avatar` or `attachment`. A reference humanoid does not change an attachment's role. |
|
|
64
|
-
| `rig.role` | Optional role hint: `avatar` or `attachmentReference`. Contains no bone-pair table. |
|
|
65
|
-
| `requiredCapabilities` | Component types a consumer must support. An unknown required capability is an error. |
|
|
66
|
-
| `matching` | Optional `mode: "keywordBestEffort"`, `onUnresolved: "warnAndContinue"`, and `armatureKeywords`. |
|
|
67
|
-
| `nodes` | Optional local node indices with `aliases` and initial `active` state (default true). |
|
|
68
|
-
| `components` | Ordered component records (default empty). Every `id` must be unique within the file. |
|
|
69
|
-
|
|
70
|
-
| Selector | Reference semantics |
|
|
71
|
-
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
72
|
-
| `asset: "self"` | Requires a file-local glTF `node` index. Morph references also require a final mesh `morphIndex`. Material indices address this file's `materials`. |
|
|
73
|
-
| `asset: "base"` | Never contains another file's node/morph index. Uses `path`, bone/mesh/node/blendshape keywords, optional `parentKeywords`, and optional `humanBone`/`humanBonePath`. |
|
|
74
|
-
| `path` | Array of ancestor names relative to the authored avatar root; an empty array explicitly means the root. It is a structural hint, not an identity requirement. |
|
|
75
|
-
| `humanBone`, `humanBonePath` | VRM humanoid bone name and optional path below it; retained from MA Bone Proxy for fallback. |
|
|
76
|
-
|
|
77
|
-
All node indices must survive export. A serializer whose glTF writer omits the scene container must materialize a node when a component references that container. Preserve source aliases and initial active states; inactive option geometry must remain available. Alternate materials/textures used only by components must also be exported.
|
|
78
|
-
|
|
79
|
-
Resolve external targets by hierarchy and names, with Unicode/case/separator normalization and left/right distinctions. Prefer an exact hierarchy path; otherwise rank exact, normalized, token and substring names. Mesh hints refine blendshape matches; a uniquely named shape may match another mesh with a warning. Split primitives belonging to one authored glTF node form one mesh target. Remaining ties or missing targets warn and skip only the unresolved entry. There is no checksum, base identity, minimum match count, topology or body-shape gate.
|
|
80
|
-
|
|
81
|
-
## Component records
|
|
82
|
-
|
|
83
|
-
Every record has `id`, `type`, and file-local `sourceNode` identifying the GameObject on which the instruction was authored. Optional `origin` is `authored` (default), `modularAvatar`, `referenceRig` or `colliderAnchor`; origin records provenance and does not alter execution.
|
|
84
|
-
|
|
85
|
-
| Type / MA source | Fields and defaults | Execution |
|
|
86
|
-
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
87
|
-
| `mergeArmature` / Merge Armature | `target`; `prefix`, `suffix` (empty); `lockMode` (`unidirectional`); `mangleNames` (true) | Resolve the source root and target root, then discover descendant pairs. No exported per-bone mapping. |
|
|
88
|
-
| `boneProxy` / Bone Proxy | `target`; `attachmentMode` (`keepWorldPose`); `matchScale` (false) | Attach the source root to the resolved base target. `atRoot` matches target position/rotation and preserves source world scale. |
|
|
89
|
-
| `shapeChanger` / Shape Changer | `shapes: [{target, changeType, value}]`; `changeType` is `set` or `delete`, value defaults to 0; `threshold` defaults to `0.01` | Set writes a normalized weight. Delete removes affected triangles reversibly, using the rules below. |
|
|
90
|
-
| `blendshapeSync` / Blendshape Sync | `bindings: [{driver, driven, curve?}]` | Read the driver after expression/fit updates and copy/remap to the driven shape. |
|
|
91
|
-
| `objectToggle` / Object Toggle | `objects: [{target, value}]` with Boolean value | Apply logical object visibility, including original ancestor visibility after bones move. |
|
|
92
|
-
| `materialSetter` / Material Setter | `objects: [{target, slot, material}]` | Replace the specified material slot using a file-local alternative. No shader-specific interpretation. |
|
|
93
|
-
| `menuItem` / Menu Item | `label`, `controlType` (`toggle` or `button`); optional `parameter`; `value` (1), `defaultValue` (0), `automatic` (true) | Expose an asset-local input keyed by parameter or component ID. Automatic items drive their source node's activation when the input equals `value`. |
|
|
94
|
-
|
|
95
|
-
### Armatures and physics
|
|
96
|
-
|
|
97
|
-
Automatic descendant matching uses exact, case-sensitive names and exported aliases. A name must contain the configured case-sensitive prefix and suffix; strip them before comparison. Search only authored direct children of the matched target parent. Never broaden the search to other branches, deeper descendants or the global base. An unmatched bone preserves its entire branch and ends that traversal. A missing root target does not trigger descendant recovery. Another component's source root is handled independently; mesh subtrees are not bone chains. Explicit root selectors and Bone Proxy selectors retain their existing resolution rules.
|
|
98
|
-
|
|
99
|
-
The runtime implements **unidirectional base-to-attachment following**. `bidirectional` and `notLocked` retain the MA setting but MUST warn and fall back to unidirectional behavior. These values describe MA's authoring position-lock setting; this runtime does not reproduce MA's build-time skeleton collapse. It retains the source bones, skin weights, inverse-bind matrices and rest offsets. `mangleNames` is retained as intent; independent instance ownership avoids name mutation. Local-to-local merges are preserved as records but warn and remain unapplied.
|
|
100
|
-
|
|
101
|
-
Bone Proxy `keepPosition`, `keepRotation` or `matchScale: true` are currently compatibility fallbacks: warn and keep world pose. Singular transforms warn and keep the source rig. Remove generated offset helpers and restore parent, sibling order and transforms on detach.
|
|
102
|
-
|
|
103
|
-
Generated `referenceRig` records let a copied parent skeleton follow the base without exporting a pair table. Generated `colliderAnchor` proxies follow external collider roots copied into the attachment. Springs and collider groups still belong to their own VRM; composition never links one file's colliders to another file's joints.
|
|
104
|
-
|
|
105
|
-
### Shape Changer deletion
|
|
106
|
-
|
|
107
|
-
`threshold` is a finite, non-negative position distance in the **matched mesh's exported local coordinates**, independent of its current morph weight, pose or world scale. The extension stores names and settings, not vertex masks or a required base identity. Missing `threshold` means `0.01`; re-export older assets to retain a custom MA threshold.
|
|
108
|
-
|
|
109
|
-
| Rule | Required behavior |
|
|
110
|
-
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
111
|
-
| Vertex selection | Use the matched morph's position displacement from rest. For relative morphs, read the delta directly; for absolute morphs, subtract the base position. Select when `dx² + dy² + dz² > threshold²`. A zero threshold selects any nonzero displacement. |
|
|
112
|
-
| Triangle selection | Remove a triangle if **any** vertex is selected. Decode sparse/normalized attributes before comparison. Apply to each matched primitive of the authored mesh. The result is independent of material type. |
|
|
113
|
-
| Precedence | Process Set/Delete in the usual asset, component and entry order. Set writes its weight and cancels an earlier Delete on that shape. Delete activates filtering without changing any preceding Set weight. Later entries win the deletion state for that shape. |
|
|
114
|
-
| Competing deletions | For each matched mesh and shape, use the minimum threshold of all registered Delete entries, including inactive entries, as MA does. Union the winning masks for different shapes; do not count an overlapping triangle twice in the final geometry. |
|
|
115
|
-
| Synchronization | Successful Delete does not modify morph weights or propagate deletion through Blendshape Sync. Set values still synchronize normally. The Delete entry's `value` is retained metadata and has no effect on selection. |
|
|
116
|
-
| Restoration | Withdraw filtering when conditions become false or the attachment is hidden/removed. Recompute the union of remaining masks and restore original geometry when none remain. Preserve skinning, morph indices, material slots and source buffers. |
|
|
117
|
-
| Compatibility | Missing names warn and skip only that entry. If a matched morph lacks usable position/topology data, MUST warn and use reversible weight **0** for that entry. Continue supported deletions on other targets. |
|
|
118
|
-
|
|
119
|
-
The reference runtime uses session-owned index overlays with adjusted material groups and draw ranges; it retains vertex buffers and conservative bounds. Normal rendering, shadows and ordinary Three.js raycasting use the filtered geometry. Masks are cached until source attribute/index versions, layout or ranges change. Host code must flag buffer edits with `needsUpdate`; replacing `mesh.geometry` during an overlay warns and uses the fallback without overwriting the replacement. Detach and reattach to compile that replacement. Session disposal releases copies, never source assets.
|
|
120
|
-
|
|
121
|
-
MA checks all Unity frames in a blendshape. glTF morphs contain one displacement per vertex, so lost frames, quantization, and baking scale/current weights can change selection. The Unity exporter preserves the authored threshold and warns about multi-frame morphs and metric-changing Freeze Mesh settings. General Mesh Cutter filters, vertex compaction, sealed cut boundaries and smaller downloads are outside this feature.
|
|
122
|
-
|
|
123
|
-
### Conditions, remaps and controls
|
|
124
|
-
|
|
125
|
-
| Rule | Behavior |
|
|
126
|
-
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
127
|
-
| Conditions | Shape Changer, Blendshape Sync, Object Toggle and Material Setter accept an optional `condition`. Without it, the component is active whenever the asset is visible. |
|
|
128
|
-
| `nodeActive` | Test the indicated node and its authored ancestors. Local `node` defaults to `asset: "self"`; base targets use paths/keywords. Optional `inverse` negates the resolved state. An unresolved external condition disables its entries, even when inverted. |
|
|
129
|
-
| `control` | Test an input keyed by a menu ID or parameter. Optional `value` compares numerically; otherwise test truthiness. Optional `inverse` negates it. |
|
|
130
|
-
| Remaps | `curve` contains `interpolation: "linear"` or `"step"` and increasing `[input, output]` points. No curve means identity. Linear end segments extrapolate; steps clamp at endpoints. MA uses linear control points; Unity weights/coordinates are divided by 100. |
|
|
131
|
-
| Toggle | Write the authored `value` when on and 0 when off. Items sharing a parameter share state within the asset instance; a nonzero authored default initializes that group. |
|
|
132
|
-
| Button | The host writes `value` while held and **0 on release/cancel**. Buttons are momentary and should start at 0. |
|
|
133
|
-
| Named parameters | Retained as local state/metadata; no automatic object activation when `automatic` is false. Warn that arbitrary Animator effects, networking and saving are not executed. |
|
|
134
|
-
|
|
135
|
-
For a local `nodeActive` condition, also test the nearest `menuItem` on that node or an authored ancestor: its local input must equal the menu's value. Inversion applies to the combined node/menu condition. This lets named menu parameters gate reactive descendants without an Animator or an automatic visibility change. The Unity adapter exports reactive source-node activation and inversion, including components on the asset root; Blendshape Sync is unconditional, matching MA's source behavior. Menu hierarchy, parameter renaming and arbitrary Animator graphs are outside this profile.
|
|
136
|
-
|
|
137
|
-
## Evaluation and diagnostics
|
|
138
|
-
|
|
139
|
-
1. Parse structural data and validate local references.
|
|
140
|
-
2. Resolve component targets and compile private runtime operations without rewriting the manifest.
|
|
141
|
-
3. Resolve and apply base-to-attachment links transactionally.
|
|
142
|
-
4. Before the base VRM update, restore previous overlays and evaluate visibility/material changes. The host advances the base animation and VRM once.
|
|
143
|
-
5. Advance attachment expressions, constraints and springs, then evaluate Set/Delete states, geometry overlays and blendshape synchronization. Do not advance the attachment humanoid as another base animation driver.
|
|
144
|
-
6. Hiding/removing an attachment withdraws its writes. Detach restores its hierarchy and spring initialization; disposal belongs to the host.
|
|
145
|
-
|
|
146
|
-
Within each phase, process the base first, then attachments in ascending layer order and stable instance ID. Component and entry array order determines order within an asset. Fit overrides run before synchronization. Later writers win, with overlap warnings. Chained/cyclic sync and cyclic visibility conditions are execution errors; malformed data and invalid local indices are also errors. Missing external names remain noncritical warnings.
|
|
147
|
-
|
|
148
|
-
Expose authored records separately from resolved operations: component ID, matched source/target, skipped status and warning. Delete diagnostics include whether the entry won the active deletion state, its selected vertex/removed triangle counts, and any fallback reason. Counts describe each entry across its matched primitives, before union with other shapes. Do not write resolved pairs back into the extension. The current runtime exposes `session.resolved` for base components and `attachment.resolved` for attachment components.
|
|
149
|
-
|
|
150
|
-
## Source references
|
|
151
|
-
|
|
152
|
-
The mappings follow MA's public components, within the limits above: [Merge Armature](https://modular-avatar.nadena.dev/docs/reference/merge-armature), [Bone Proxy](https://modular-avatar.nadena.dev/docs/reference/bone-proxy), [Blendshape Sync](https://modular-avatar.nadena.dev/docs/reference/blendshape-sync), [reactive components](https://modular-avatar.nadena.dev/docs/reference/reaction), and [Menu Item](https://modular-avatar.nadena.dev/docs/reference/menu-item).
|
|
1
|
+
# MOCHIYA_avatar_composition 0.1
|
|
2
|
+
|
|
3
|
+
Draft glTF 2.0 extension for composing an avatar with attachments. This document defines behavior; the [JSON Schema](../schema/MOCHIYA_avatar_composition.schema.json) defines JSON structure. The runtime's TypeScript schema generates that JSON Schema. Consumers also validate references and execution graphs.
|
|
4
|
+
|
|
5
|
+
The current draft replaces the earlier action/joint-mapping draft. Re-export older files. There is no legacy reader.
|
|
6
|
+
|
|
7
|
+
## Scope and placement
|
|
8
|
+
|
|
9
|
+
Put the extension on the glTF document root and list its name in `extensionsUsed`. A consumer without support can display the ordinary model. Do not depend on this extension for standard skinning, VRM expressions, physics or materials: those remain glTF/VRM data. Cross-asset collider linking is outside this specification.
|
|
10
|
+
|
|
11
|
+
```json
|
|
12
|
+
{
|
|
13
|
+
"extensionsUsed": ["MOCHIYA_avatar_composition"],
|
|
14
|
+
"extensions": {
|
|
15
|
+
"MOCHIYA_avatar_composition": {
|
|
16
|
+
"specVersion": "0.1",
|
|
17
|
+
"assetKind": "attachment",
|
|
18
|
+
"requiredCapabilities": ["mergeArmature", "shapeChanger"],
|
|
19
|
+
"components": [
|
|
20
|
+
{
|
|
21
|
+
"id": "coat-rig",
|
|
22
|
+
"type": "mergeArmature",
|
|
23
|
+
"sourceNode": 12,
|
|
24
|
+
"origin": "modularAvatar",
|
|
25
|
+
"target": {
|
|
26
|
+
"asset": "base",
|
|
27
|
+
"path": ["Armature"],
|
|
28
|
+
"boneKeywords": ["Armature"]
|
|
29
|
+
},
|
|
30
|
+
"prefix": "Coat_",
|
|
31
|
+
"lockMode": "unidirectional"
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
"id": "fit",
|
|
35
|
+
"type": "shapeChanger",
|
|
36
|
+
"sourceNode": 4,
|
|
37
|
+
"condition": { "type": "nodeActive", "node": 4 },
|
|
38
|
+
"shapes": [
|
|
39
|
+
{
|
|
40
|
+
"target": {
|
|
41
|
+
"asset": "base",
|
|
42
|
+
"meshKeywords": ["Body"],
|
|
43
|
+
"blendshapeKeywords": ["HideTorso"]
|
|
44
|
+
},
|
|
45
|
+
"changeType": "set",
|
|
46
|
+
"value": 1
|
|
47
|
+
}
|
|
48
|
+
]
|
|
49
|
+
}
|
|
50
|
+
]
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The example assumes local nodes 4 and 12 exist in the containing glTF.
|
|
57
|
+
|
|
58
|
+
## Root and references
|
|
59
|
+
|
|
60
|
+
| Field | Meaning |
|
|
61
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------ |
|
|
62
|
+
| `specVersion` | Required literal `"0.1"`. |
|
|
63
|
+
| `assetKind` | Required `avatar` or `attachment`. A reference humanoid does not change an attachment's role. |
|
|
64
|
+
| `rig.role` | Optional role hint: `avatar` or `attachmentReference`. Contains no bone-pair table. |
|
|
65
|
+
| `requiredCapabilities` | Component types a consumer must support. An unknown required capability is an error. |
|
|
66
|
+
| `matching` | Optional `mode: "keywordBestEffort"`, `onUnresolved: "warnAndContinue"`, and `armatureKeywords`. |
|
|
67
|
+
| `nodes` | Optional local node indices with `aliases` and initial `active` state (default true). |
|
|
68
|
+
| `components` | Ordered component records (default empty). Every `id` must be unique within the file. |
|
|
69
|
+
|
|
70
|
+
| Selector | Reference semantics |
|
|
71
|
+
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
72
|
+
| `asset: "self"` | Requires a file-local glTF `node` index. Morph references also require a final mesh `morphIndex`. Material indices address this file's `materials`. |
|
|
73
|
+
| `asset: "base"` | Never contains another file's node/morph index. Uses `path`, bone/mesh/node/blendshape keywords, optional `parentKeywords`, and optional `humanBone`/`humanBonePath`. |
|
|
74
|
+
| `path` | Array of ancestor names relative to the authored avatar root; an empty array explicitly means the root. It is a structural hint, not an identity requirement. |
|
|
75
|
+
| `humanBone`, `humanBonePath` | VRM humanoid bone name and optional path below it; retained from MA Bone Proxy for fallback. |
|
|
76
|
+
|
|
77
|
+
All node indices must survive export. A serializer whose glTF writer omits the scene container must materialize a node when a component references that container. Preserve source aliases and initial active states; inactive option geometry must remain available. Alternate materials/textures used only by components must also be exported.
|
|
78
|
+
|
|
79
|
+
Resolve external targets by hierarchy and names, with Unicode/case/separator normalization and left/right distinctions. Prefer an exact hierarchy path; otherwise rank exact, normalized, token and substring names. Mesh hints refine blendshape matches; a uniquely named shape may match another mesh with a warning. Split primitives belonging to one authored glTF node form one mesh target. Remaining ties or missing targets warn and skip only the unresolved entry. There is no checksum, base identity, minimum match count, topology or body-shape gate.
|
|
80
|
+
|
|
81
|
+
## Component records
|
|
82
|
+
|
|
83
|
+
Every record has `id`, `type`, and file-local `sourceNode` identifying the GameObject on which the instruction was authored. Optional `origin` is `authored` (default), `modularAvatar`, `referenceRig` or `colliderAnchor`; origin records provenance and does not alter execution.
|
|
84
|
+
|
|
85
|
+
| Type / MA source | Fields and defaults | Execution |
|
|
86
|
+
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
87
|
+
| `mergeArmature` / Merge Armature | `target`; `prefix`, `suffix` (empty); `lockMode` (`unidirectional`); `mangleNames` (true) | Resolve the source root and target root, then discover descendant pairs. No exported per-bone mapping. |
|
|
88
|
+
| `boneProxy` / Bone Proxy | `target`; `attachmentMode` (`keepWorldPose`); `matchScale` (false) | Attach the source root to the resolved base target. `atRoot` matches target position/rotation and preserves source world scale. |
|
|
89
|
+
| `shapeChanger` / Shape Changer | `shapes: [{target, changeType, value}]`; `changeType` is `set` or `delete`, value defaults to 0; `threshold` defaults to `0.01` | Set writes a normalized weight. Delete removes affected triangles reversibly, using the rules below. |
|
|
90
|
+
| `blendshapeSync` / Blendshape Sync | `bindings: [{driver, driven, curve?}]` | Read the driver after expression/fit updates and copy/remap to the driven shape. |
|
|
91
|
+
| `objectToggle` / Object Toggle | `objects: [{target, value}]` with Boolean value | Apply logical object visibility, including original ancestor visibility after bones move. |
|
|
92
|
+
| `materialSetter` / Material Setter | `objects: [{target, slot, material}]` | Replace the specified material slot using a file-local alternative. No shader-specific interpretation. |
|
|
93
|
+
| `menuItem` / Menu Item | `label`, `controlType` (`toggle` or `button`); optional `parameter`; `value` (1), `defaultValue` (0), `automatic` (true) | Expose an asset-local input keyed by parameter or component ID. Automatic items drive their source node's activation when the input equals `value`. |
|
|
94
|
+
|
|
95
|
+
### Armatures and physics
|
|
96
|
+
|
|
97
|
+
Automatic descendant matching uses exact, case-sensitive names and exported aliases. A name must contain the configured case-sensitive prefix and suffix; strip them before comparison. Search only authored direct children of the matched target parent. Never broaden the search to other branches, deeper descendants or the global base. An unmatched bone preserves its entire branch and ends that traversal. A missing root target does not trigger descendant recovery. Another component's source root is handled independently; mesh subtrees are not bone chains. Explicit root selectors and Bone Proxy selectors retain their existing resolution rules.
|
|
98
|
+
|
|
99
|
+
The runtime implements **unidirectional base-to-attachment following**. `bidirectional` and `notLocked` retain the MA setting but MUST warn and fall back to unidirectional behavior. These values describe MA's authoring position-lock setting; this runtime does not reproduce MA's build-time skeleton collapse. It retains the source bones, skin weights, inverse-bind matrices and rest offsets. `mangleNames` is retained as intent; independent instance ownership avoids name mutation. Local-to-local merges are preserved as records but warn and remain unapplied.
|
|
100
|
+
|
|
101
|
+
Bone Proxy `keepPosition`, `keepRotation` or `matchScale: true` are currently compatibility fallbacks: warn and keep world pose. Singular transforms warn and keep the source rig. Remove generated offset helpers and restore parent, sibling order and transforms on detach.
|
|
102
|
+
|
|
103
|
+
Generated `referenceRig` records let a copied parent skeleton follow the base without exporting a pair table. Generated `colliderAnchor` proxies follow external collider roots copied into the attachment. Springs and collider groups still belong to their own VRM; composition never links one file's colliders to another file's joints.
|
|
104
|
+
|
|
105
|
+
### Shape Changer deletion
|
|
106
|
+
|
|
107
|
+
`threshold` is a finite, non-negative position distance in the **matched mesh's exported local coordinates**, independent of its current morph weight, pose or world scale. The extension stores names and settings, not vertex masks or a required base identity. Missing `threshold` means `0.01`; re-export older assets to retain a custom MA threshold.
|
|
108
|
+
|
|
109
|
+
| Rule | Required behavior |
|
|
110
|
+
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
111
|
+
| Vertex selection | Use the matched morph's position displacement from rest. For relative morphs, read the delta directly; for absolute morphs, subtract the base position. Select when `dx² + dy² + dz² > threshold²`. A zero threshold selects any nonzero displacement. |
|
|
112
|
+
| Triangle selection | Remove a triangle if **any** vertex is selected. Decode sparse/normalized attributes before comparison. Apply to each matched primitive of the authored mesh. The result is independent of material type. |
|
|
113
|
+
| Precedence | Process Set/Delete in the usual asset, component and entry order. Set writes its weight and cancels an earlier Delete on that shape. Delete activates filtering without changing any preceding Set weight. Later entries win the deletion state for that shape. |
|
|
114
|
+
| Competing deletions | For each matched mesh and shape, use the minimum threshold of all registered Delete entries, including inactive entries, as MA does. Union the winning masks for different shapes; do not count an overlapping triangle twice in the final geometry. |
|
|
115
|
+
| Synchronization | Successful Delete does not modify morph weights or propagate deletion through Blendshape Sync. Set values still synchronize normally. The Delete entry's `value` is retained metadata and has no effect on selection. |
|
|
116
|
+
| Restoration | Withdraw filtering when conditions become false or the attachment is hidden/removed. Recompute the union of remaining masks and restore original geometry when none remain. Preserve skinning, morph indices, material slots and source buffers. |
|
|
117
|
+
| Compatibility | Missing names warn and skip only that entry. If a matched morph lacks usable position/topology data, MUST warn and use reversible weight **0** for that entry. Continue supported deletions on other targets. |
|
|
118
|
+
|
|
119
|
+
The reference runtime uses session-owned index overlays with adjusted material groups and draw ranges; it retains vertex buffers and conservative bounds. Normal rendering, shadows and ordinary Three.js raycasting use the filtered geometry. Masks are cached until source attribute/index versions, layout or ranges change. Host code must flag buffer edits with `needsUpdate`; replacing `mesh.geometry` during an overlay warns and uses the fallback without overwriting the replacement. Detach and reattach to compile that replacement. Session disposal releases copies, never source assets.
|
|
120
|
+
|
|
121
|
+
MA checks all Unity frames in a blendshape. glTF morphs contain one displacement per vertex, so lost frames, quantization, and baking scale/current weights can change selection. The Unity exporter preserves the authored threshold and warns about multi-frame morphs and metric-changing Freeze Mesh settings. General Mesh Cutter filters, vertex compaction, sealed cut boundaries and smaller downloads are outside this feature.
|
|
122
|
+
|
|
123
|
+
### Conditions, remaps and controls
|
|
124
|
+
|
|
125
|
+
| Rule | Behavior |
|
|
126
|
+
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
127
|
+
| Conditions | Shape Changer, Blendshape Sync, Object Toggle and Material Setter accept an optional `condition`. Without it, the component is active whenever the asset is visible. |
|
|
128
|
+
| `nodeActive` | Test the indicated node and its authored ancestors. Local `node` defaults to `asset: "self"`; base targets use paths/keywords. Optional `inverse` negates the resolved state. An unresolved external condition disables its entries, even when inverted. |
|
|
129
|
+
| `control` | Test an input keyed by a menu ID or parameter. Optional `value` compares numerically; otherwise test truthiness. Optional `inverse` negates it. |
|
|
130
|
+
| Remaps | `curve` contains `interpolation: "linear"` or `"step"` and increasing `[input, output]` points. No curve means identity. Linear end segments extrapolate; steps clamp at endpoints. MA uses linear control points; Unity weights/coordinates are divided by 100. |
|
|
131
|
+
| Toggle | Write the authored `value` when on and 0 when off. Items sharing a parameter share state within the asset instance; a nonzero authored default initializes that group. |
|
|
132
|
+
| Button | The host writes `value` while held and **0 on release/cancel**. Buttons are momentary and should start at 0. |
|
|
133
|
+
| Named parameters | Retained as local state/metadata; no automatic object activation when `automatic` is false. Warn that arbitrary Animator effects, networking and saving are not executed. |
|
|
134
|
+
|
|
135
|
+
For a local `nodeActive` condition, also test the nearest `menuItem` on that node or an authored ancestor: its local input must equal the menu's value. Inversion applies to the combined node/menu condition. This lets named menu parameters gate reactive descendants without an Animator or an automatic visibility change. The Unity adapter exports reactive source-node activation and inversion, including components on the asset root; Blendshape Sync is unconditional, matching MA's source behavior. Menu hierarchy, parameter renaming and arbitrary Animator graphs are outside this profile.
|
|
136
|
+
|
|
137
|
+
## Evaluation and diagnostics
|
|
138
|
+
|
|
139
|
+
1. Parse structural data and validate local references.
|
|
140
|
+
2. Resolve component targets and compile private runtime operations without rewriting the manifest.
|
|
141
|
+
3. Resolve and apply base-to-attachment links transactionally.
|
|
142
|
+
4. Before the base VRM update, restore previous overlays and evaluate visibility/material changes. The host advances the base animation and VRM once.
|
|
143
|
+
5. Advance attachment expressions, constraints and springs, then evaluate Set/Delete states, geometry overlays and blendshape synchronization. Do not advance the attachment humanoid as another base animation driver.
|
|
144
|
+
6. Hiding/removing an attachment withdraws its writes. Detach restores its hierarchy and spring initialization; disposal belongs to the host.
|
|
145
|
+
|
|
146
|
+
Within each phase, process the base first, then attachments in ascending layer order and stable instance ID. Component and entry array order determines order within an asset. Fit overrides run before synchronization. Later writers win, with overlap warnings. Chained/cyclic sync and cyclic visibility conditions are execution errors; malformed data and invalid local indices are also errors. Missing external names remain noncritical warnings.
|
|
147
|
+
|
|
148
|
+
Expose authored records separately from resolved operations: component ID, matched source/target, skipped status and warning. Delete diagnostics include whether the entry won the active deletion state, its selected vertex/removed triangle counts, and any fallback reason. Counts describe each entry across its matched primitives, before union with other shapes. Do not write resolved pairs back into the extension. The current runtime exposes `session.resolved` for base components and `attachment.resolved` for attachment components.
|
|
149
|
+
|
|
150
|
+
## Source references
|
|
151
|
+
|
|
152
|
+
The mappings follow MA's public components, within the limits above: [Merge Armature](https://modular-avatar.nadena.dev/docs/reference/merge-armature), [Bone Proxy](https://modular-avatar.nadena.dev/docs/reference/bone-proxy), [Blendshape Sync](https://modular-avatar.nadena.dev/docs/reference/blendshape-sync), [reactive components](https://modular-avatar.nadena.dev/docs/reference/reaction), and [Menu Item](https://modular-avatar.nadena.dev/docs/reference/menu-item).
|