@mochiya/avatar-composition 0.1.1 → 0.2.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.
@@ -6,7 +6,7 @@
6
6
  "properties": {
7
7
  "specVersion": {
8
8
  "type": "string",
9
- "const": "0.1"
9
+ "const": "0.2"
10
10
  },
11
11
  "assetKind": {
12
12
  "type": "string",
@@ -1,152 +1,161 @@
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
2
+
3
+ Current glTF 2.0 extension overview for composing an avatar with attachments. This document describes 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 schema defines the current authoring contract. Producing tools write the current format marker.
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
+ "assetKind": "attachment",
17
+ "requiredCapabilities": ["mergeArmature", "shapeChanger"],
18
+ "components": [
19
+ {
20
+ "id": "coat-rig",
21
+ "type": "mergeArmature",
22
+ "sourceNode": 12,
23
+ "origin": "modularAvatar",
24
+ "target": {
25
+ "asset": "base",
26
+ "path": ["Armature"],
27
+ "boneKeywords": ["Armature"]
28
+ },
29
+ "prefix": "Coat_",
30
+ "lockMode": "unidirectional"
31
+ },
32
+ {
33
+ "id": "fit",
34
+ "type": "shapeChanger",
35
+ "sourceNode": 4,
36
+ "condition": { "type": "nodeActive", "node": 4 },
37
+ "shapes": [
38
+ {
39
+ "target": {
40
+ "asset": "base",
41
+ "meshKeywords": ["Body"],
42
+ "blendshapeKeywords": ["HideTorso"]
43
+ },
44
+ "changeType": "set",
45
+ "value": 1
46
+ }
47
+ ]
48
+ }
49
+ ]
50
+ }
51
+ }
52
+ }
53
+ ```
54
+
55
+ The example assumes local nodes 4 and 12 exist in the containing glTF.
56
+
57
+ The example omits the generated `specVersion` value for readability; serialized files must include the marker required by the current schema.
58
+
59
+ ## Root and references
60
+
61
+ | Field | Meaning |
62
+ | ---------------------- | ------------------------------------------------------------------------------------------------ |
63
+ | `specVersion` | Required extension marker validated by the current schema. |
64
+ | `assetKind` | Required `avatar` or `attachment`. A reference humanoid does not change an attachment's role. |
65
+ | `rig.role` | Optional role hint: `avatar` or `attachmentReference`. Contains no bone-pair table. |
66
+ | `requiredCapabilities` | Component types a consumer must support. An unknown required capability is an error. |
67
+ | `matching` | Optional `mode: "keywordBestEffort"`, `onUnresolved: "warnAndContinue"`, and `armatureKeywords`. |
68
+ | `nodes` | Optional local node indices with `aliases` and initial `active` state (default true). |
69
+ | `components` | Ordered component records (default empty). Every `id` must be unique within the file. |
70
+
71
+ | Selector | Reference semantics |
72
+ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
73
+ | `asset: "self"` | Requires a file-local glTF `node` index. Morph references also require a final mesh `morphIndex`. Material indices address this file's `materials`. |
74
+ | `asset: "base"` | Never contains another file's node/morph index. Uses `path`, bone/mesh/node/blendshape keywords, optional `parentKeywords`, and optional `humanBone`/`humanBonePath`. |
75
+ | `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. |
76
+ | `humanBone`, `humanBonePath` | VRM humanoid bone name and optional path below it; retained from MA Bone Proxy for fallback. |
77
+
78
+ 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.
79
+
80
+ 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.
81
+
82
+ ## Component records
83
+
84
+ 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.
85
+
86
+ | Type / MA source | Fields and defaults | Execution |
87
+ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
88
+ | `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. |
89
+ | `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. |
90
+ | `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. |
91
+ | `blendshapeSync` / Blendshape Sync | `bindings: [{driver, driven, curve?}]` | Read the driver after expression/fit updates and copy/remap to the driven shape. |
92
+ | `objectToggle` / Object Toggle | `objects: [{target, value}]` with Boolean value | Apply logical object visibility, including original ancestor visibility after bones move. |
93
+ | `materialSetter` / Material Setter | `objects: [{target, slot, material}]` | Replace the specified material slot using a file-local alternative. No shader-specific interpretation. |
94
+ | `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`. |
95
+
96
+ ### Armatures and physics
97
+
98
+ 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.
99
+
100
+ 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.
101
+
102
+ 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.
103
+
104
+ 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.
105
+
106
+ ### Shape Changer deletion
107
+
108
+ `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.
109
+
110
+ | Rule | Required behavior |
111
+ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
112
+ | 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. |
113
+ | 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. |
114
+ | 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. |
115
+ | 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. |
116
+ | 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. |
117
+ | 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. |
118
+ | 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. |
119
+
120
+ 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.
121
+
122
+ 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.
123
+
124
+ ### Conditions, remaps and controls
125
+
126
+ | Rule | Behavior |
127
+ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
128
+ | Conditions | Shape Changer, Blendshape Sync, Object Toggle and Material Setter accept an optional `condition`. Ordinary components additionally require their source object and authored ancestors to be active. |
129
+ | `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. |
130
+ | `control` | Test an input keyed by a menu ID or parameter. Optional `value` compares numerically; otherwise test truthiness. Optional `inverse` negates it. |
131
+ | 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. |
132
+ | 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. |
133
+ | Button | The host writes `value` while held and **0 on release/cancel**. Buttons are momentary and should start at 0. |
134
+ | 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. |
135
+
136
+ 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 has no exported reactive condition, but the runtime suspends its contribution when its source item or ancestors are inactive. Menu hierarchy, parameter renaming and arbitrary Animator graphs are outside this profile.
137
+
138
+ ## Evaluation and diagnostics
139
+
140
+ 1. Parse structural data and validate local references.
141
+ 2. Resolve component targets and compile private runtime operations without rewriting the manifest.
142
+ 3. Resolve and apply base-to-attachment links transactionally.
143
+ 4. Before the base VRM update, restore previous overlays and evaluate visibility/material changes. The host advances the base animation and VRM once.
144
+ 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.
145
+ 6. Hiding/removing an attachment withdraws its writes. Detach restores its hierarchy and spring initialization; disposal belongs to the host.
146
+
147
+ Within each phase, process the base first, then attachments in ascending layer order and insertion order for ties. 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.
148
+
149
+ 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 `composition.inspect(asset).resolved` for either base or attachment components.
150
+
151
+ ## Source references
152
+
153
+ 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).
154
+
155
+ ## Authored item activation
156
+
157
+ Node `active` defaults to true: Unity captures `gameObject.activeSelf && (renderer == null || renderer.enabled)` before enabling the export clone. The selected Unity export root is exempt from this calculation: ignore its GameObject and renderer activation and always initialize it active. Materialize an omitted root only when component references need its identity. The Unity source root’s activation is not part of the exported activation contract. Explicit runtime root activation is a separate user input and still supported.
158
+
159
+ The runtime groups all primitives of a glTF node under one authored item and retains the original parent graph independently of rig reparenting. Local activation is distinct from evaluated hierarchy activity and final render visibility, but there is no independent renderer-enabled state. Explicit user deactivation vetoes positive object-toggle writes; authored inactive defaults can still be activated by a menu. Parent deactivation preserves child local settings.
160
+
161
+ An inactive asset root suspends all its ordinary fit, material, deletion, toggle and synchronization writes. An inactive child suspends ordinary writes owned by that child/subtree. Explicitly inverted reactive conditions remain an exception within the hard asset-root gate. Rig bindings remain established during activation changes. Withdrawal recomputes remaining writers and restores user baselines; removing one outfit must not erase another outfit's winning contribution.
package/package.json CHANGED
@@ -1,74 +1,74 @@
1
- {
2
- "name": "@mochiya/avatar-composition",
3
- "version": "0.1.1",
4
- "description": "Avatar and attachment composition for Three.js and the MOCHIYA_avatar_composition glTF extension",
5
- "type": "module",
6
- "license": "MIT",
7
- "author": {
8
- "name": "Mochiya",
9
- "url": "https://mochiya.org"
10
- },
11
- "homepage": "https://mochiya.org",
12
- "repository": {
13
- "type": "git",
14
- "url": "git+https://github.com/mochiya-labs/avatar-composition.git"
15
- },
16
- "bugs": {
17
- "url": "https://github.com/mochiya-labs/avatar-composition/issues"
18
- },
19
- "publishConfig": {
20
- "access": "public",
21
- "registry": "https://registry.npmjs.org/"
22
- },
23
- "sideEffects": false,
24
- "main": "./dist/index.js",
25
- "types": "./dist/index.d.ts",
26
- "exports": {
27
- ".": {
28
- "types": "./dist/index.d.ts",
29
- "import": "./dist/index.js"
30
- },
31
- "./schema": "./dist/schema/MOCHIYA_avatar_composition.schema.json"
32
- },
33
- "files": [
34
- "dist"
35
- ],
36
- "workspaces": [
37
- "examples/viewer"
38
- ],
39
- "scripts": {
40
- "format": "prettier --write .",
41
- "format:check": "prettier --check .",
42
- "build": "tsup && node scripts/generate-schema.mjs",
43
- "prepublishOnly": "npm run format:check && npm run typecheck && npm run build && npm test",
44
- "typecheck": "tsc --noEmit",
45
- "test": "vitest run",
46
- "viewer:dev": "npm run dev --workspace @mochiya/avatar-composition-viewer",
47
- "viewer:build": "npm run build --workspace @mochiya/avatar-composition-viewer",
48
- "viewer:use-local-liltoon": "npm install --no-save --package-lock=false ../three-liltoon",
49
- "test:browser": "playwright test"
50
- },
51
- "engines": {
52
- "node": ">=20.19"
53
- },
54
- "dependencies": {
55
- "zod": "^3.25.0"
56
- },
57
- "peerDependencies": {
58
- "@pixiv/three-vrm": ">=3.4.0 <4",
59
- "three": ">=0.180.0 <0.190.0"
60
- },
61
- "devDependencies": {
62
- "@pixiv/three-vrm": "^3.5.5",
63
- "@playwright/test": "^1.62.1",
64
- "@types/node": "^24.3.0",
65
- "@types/three": "^0.185.4",
66
- "agent-browser": "^0.36.0",
67
- "prettier": "3.9.6",
68
- "three": "^0.185.1",
69
- "tsup": "^8.5.0",
70
- "typescript": "^5.9.2",
71
- "vitest": "^3.2.4",
72
- "zod-to-json-schema": "^3.25.2"
73
- }
74
- }
1
+ {
2
+ "name": "@mochiya/avatar-composition",
3
+ "version": "0.2.0",
4
+ "description": "Avatar and attachment composition for Three.js and the MOCHIYA_avatar_composition glTF extension",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "author": {
8
+ "name": "Mochiya",
9
+ "url": "https://mochiya.org"
10
+ },
11
+ "homepage": "https://mochiya.org",
12
+ "repository": {
13
+ "type": "git",
14
+ "url": "git+https://github.com/mochiya-labs/avatar-composition.git"
15
+ },
16
+ "bugs": {
17
+ "url": "https://github.com/mochiya-labs/avatar-composition/issues"
18
+ },
19
+ "publishConfig": {
20
+ "access": "public",
21
+ "registry": "https://registry.npmjs.org/"
22
+ },
23
+ "sideEffects": false,
24
+ "main": "./dist/index.js",
25
+ "types": "./dist/index.d.ts",
26
+ "exports": {
27
+ ".": {
28
+ "types": "./dist/index.d.ts",
29
+ "import": "./dist/index.js"
30
+ }
31
+ },
32
+ "files": [
33
+ "dist"
34
+ ],
35
+ "workspaces": [
36
+ "examples/viewer"
37
+ ],
38
+ "scripts": {
39
+ "format": "prettier --write .",
40
+ "format:check": "prettier --check .",
41
+ "build": "tsup && node scripts/generate-schema.mjs",
42
+ "prepublishOnly": "npm run format:check && npm run typecheck && npm run build && npm test",
43
+ "typecheck": "tsc --noEmit",
44
+ "test": "vitest run",
45
+ "viewer:dev": "npm run dev --workspace @mochiya/avatar-composition-viewer",
46
+ "viewer:build": "npm run build --workspace @mochiya/avatar-composition-viewer",
47
+ "viewer:use-local-liltoon": "npm install --no-save --package-lock=false ../three-liltoon",
48
+ "test:browser": "playwright test"
49
+ },
50
+ "engines": {
51
+ "node": ">=20.19"
52
+ },
53
+ "dependencies": {
54
+ "zod": "^3.25.0"
55
+ },
56
+ "peerDependencies": {
57
+ "@pixiv/three-vrm": ">=3.4.0 <4",
58
+ "three": ">=0.180.0 <0.190.0"
59
+ },
60
+ "devDependencies": {
61
+ "@pixiv/three-vrm": "^3.5.5",
62
+ "@playwright/test": "^1.62.1",
63
+ "@types/node": "^24.3.0",
64
+ "@types/three": "^0.185.4",
65
+ "agent-browser": "^0.36.0",
66
+ "esbuild": "^0.27.7",
67
+ "prettier": "3.9.6",
68
+ "three": "^0.185.1",
69
+ "tsup": "^8.5.0",
70
+ "typescript": "^5.9.2",
71
+ "vitest": "^3.2.4",
72
+ "zod-to-json-schema": "^3.25.2"
73
+ }
74
+ }