@mochiya/avatar-composition 0.1.2 → 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.
@@ -1,8 +1,8 @@
1
- # MOCHIYA_avatar_composition 0.1
1
+ # MOCHIYA_avatar_composition
2
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.
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
4
 
5
- The current draft replaces the earlier action/joint-mapping draft. Re-export older files. There is no legacy reader.
5
+ The schema defines the current authoring contract. Producing tools write the current format marker.
6
6
 
7
7
  ## Scope and placement
8
8
 
@@ -13,7 +13,6 @@ Put the extension on the glTF document root and list its name in `extensionsUsed
13
13
  "extensionsUsed": ["MOCHIYA_avatar_composition"],
14
14
  "extensions": {
15
15
  "MOCHIYA_avatar_composition": {
16
- "specVersion": "0.1",
17
16
  "assetKind": "attachment",
18
17
  "requiredCapabilities": ["mergeArmature", "shapeChanger"],
19
18
  "components": [
@@ -55,11 +54,13 @@ Put the extension on the glTF document root and list its name in `extensionsUsed
55
54
 
56
55
  The example assumes local nodes 4 and 12 exist in the containing glTF.
57
56
 
57
+ The example omits the generated `specVersion` value for readability; serialized files must include the marker required by the current schema.
58
+
58
59
  ## Root and references
59
60
 
60
61
  | Field | Meaning |
61
62
  | ---------------------- | ------------------------------------------------------------------------------------------------ |
62
- | `specVersion` | Required literal `"0.1"`. |
63
+ | `specVersion` | Required extension marker validated by the current schema. |
63
64
  | `assetKind` | Required `avatar` or `attachment`. A reference humanoid does not change an attachment's role. |
64
65
  | `rig.role` | Optional role hint: `avatar` or `attachmentReference`. Contains no bone-pair table. |
65
66
  | `requiredCapabilities` | Component types a consumer must support. An unknown required capability is an error. |
@@ -124,7 +125,7 @@ MA checks all Unity frames in a blendshape. glTF morphs contain one displacement
124
125
 
125
126
  | Rule | Behavior |
126
127
  | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
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
+ | 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. |
128
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. |
129
130
  | `control` | Test an input keyed by a menu ID or parameter. Optional `value` compares numerically; otherwise test truthiness. Optional `inverse` negates it. |
130
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,7 +133,7 @@ MA checks all Unity frames in a blendshape. glTF morphs contain one displacement
132
133
  | Button | The host writes `value` while held and **0 on release/cancel**. Buttons are momentary and should start at 0. |
133
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. |
134
135
 
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
+ 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.
136
137
 
137
138
  ## Evaluation and diagnostics
138
139
 
@@ -143,10 +144,18 @@ For a local `nodeActive` condition, also test the nearest `menuItem` on that nod
143
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.
144
145
  6. Hiding/removing an attachment withdraws its writes. Detach restores its hierarchy and spring initialization; disposal belongs to the host.
145
146
 
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
+ 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.
147
148
 
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
+ 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.
149
150
 
150
151
  ## Source references
151
152
 
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,6 +1,6 @@
1
1
  {
2
2
  "name": "@mochiya/avatar-composition",
3
- "version": "0.1.2",
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",
@@ -27,8 +27,7 @@
27
27
  ".": {
28
28
  "types": "./dist/index.d.ts",
29
29
  "import": "./dist/index.js"
30
- },
31
- "./schema": "./dist/schema/MOCHIYA_avatar_composition.schema.json"
30
+ }
32
31
  },
33
32
  "files": [
34
33
  "dist"
@@ -64,6 +63,7 @@
64
63
  "@types/node": "^24.3.0",
65
64
  "@types/three": "^0.185.4",
66
65
  "agent-browser": "^0.36.0",
66
+ "esbuild": "^0.27.7",
67
67
  "prettier": "3.9.6",
68
68
  "three": "^0.185.1",
69
69
  "tsup": "^8.5.0",