@starcried/starlite-vrm 0.1.0-alpha.1 → 0.1.0-alpha.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -1
- package/dist/adjustments.d.ts +14 -0
- package/dist/adjustments.js +106 -0
- package/dist/character.d.ts +1 -1
- package/dist/character.js +16 -5
- package/dist/config.cjs +30 -0
- package/dist/config.d.ts +2 -1
- package/dist/config.js +25 -1
- package/dist/gaze.d.ts +2 -1
- package/dist/gaze.js +17 -6
- package/dist/index.d.ts +2 -1
- package/dist/index.js +240 -197
- package/dist/inspect.cjs +215 -68
- package/dist/inspect.d.ts +56 -9
- package/dist/inspect.js +262 -73
- package/dist/playback.js +25 -3
- package/dist/prepare.cjs +213 -68
- package/dist/types.d.ts +20 -1
- package/package.json +2 -2
package/dist/inspect.js
CHANGED
|
@@ -1,155 +1,306 @@
|
|
|
1
|
+
/** Controlled diagnostic text only: never include input paths, URIs or JSON text. */
|
|
2
|
+
export class VrmInspectionError extends Error {
|
|
3
|
+
code;
|
|
4
|
+
details;
|
|
5
|
+
constructor(code, message, details = {}) {
|
|
6
|
+
super(message);
|
|
7
|
+
this.name = "VrmInspectionError";
|
|
8
|
+
this.code = code;
|
|
9
|
+
this.details = details;
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
const requiredBones = ["hips", "spine", "head", ...["left", "right"].flatMap(side => ["UpperLeg", "LowerLeg", "Foot", "UpperArm", "LowerArm", "Hand"].map(part => side + part))];
|
|
13
|
+
const optionalBones = ["chest", "upperChest", "neck", "jaw", ...["left", "right"].flatMap(side => ["Eye", "Shoulder", "Toes", ...["ThumbMetacarpal", "ThumbProximal", "ThumbIntermediate", "ThumbDistal", ...["Index", "Middle", "Ring", "Little"].flatMap(finger => ["Proximal", "Intermediate", "Distal"].map(part => finger + part))]].map(part => side + part))];
|
|
1
14
|
export const MAX_MODEL_BYTES = 64 * 1024 * 1024;
|
|
2
15
|
export const MAX_ANIMATION_BYTES = 16 * 1024 * 1024;
|
|
3
16
|
export function parseGlb(bytes, kind) {
|
|
17
|
+
try {
|
|
18
|
+
return parseGlbContents(bytes, kind);
|
|
19
|
+
}
|
|
20
|
+
catch (error) {
|
|
21
|
+
if (error instanceof VrmInspectionError)
|
|
22
|
+
throw error;
|
|
23
|
+
// Type errors from malformed object shapes must not expose raw input.
|
|
24
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF structure; re-export a self-contained VRM/VRMA file");
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
function parseGlbContents(bytes, kind) {
|
|
4
28
|
const limit = kind === "vrm" ? MAX_MODEL_BYTES : MAX_ANIMATION_BYTES;
|
|
5
29
|
if (bytes.byteLength < 20 || bytes.byteLength > limit)
|
|
6
|
-
throw new
|
|
30
|
+
throw new VrmInspectionError("INVALID_GLB", `invalid GLB size; ${kind.toUpperCase()} must be a binary glTF 2.0 file no larger than ${limit / 1024 / 1024} MiB`);
|
|
7
31
|
const view = new DataView(bytes);
|
|
8
32
|
if (view.getUint32(0, true) !== 0x46546c67 || view.getUint32(4, true) !== 2 || view.getUint32(8, true) !== bytes.byteLength)
|
|
9
|
-
throw new
|
|
33
|
+
throw new VrmInspectionError("INVALID_GLB", "invalid GLB header; export binary glTF 2.0 VRM/VRMA, not FBX or JSON glTF");
|
|
10
34
|
let json;
|
|
11
35
|
let binSize = 0;
|
|
12
36
|
let binStart = 0;
|
|
13
37
|
let chunkCount = 0;
|
|
14
38
|
for (let offset = 12; offset < bytes.byteLength;) {
|
|
15
39
|
if (offset + 8 > bytes.byteLength)
|
|
16
|
-
throw new
|
|
40
|
+
throw new VrmInspectionError("INVALID_GLB", "truncated GLB chunk; download or export the complete file again");
|
|
17
41
|
const size = view.getUint32(offset, true), type = view.getUint32(offset + 4, true);
|
|
18
42
|
offset += 8;
|
|
19
43
|
if (size % 4 || size > bytes.byteLength - offset)
|
|
20
|
-
throw new
|
|
44
|
+
throw new VrmInspectionError("INVALID_GLB", "invalid GLB chunk length; download or export the complete file again");
|
|
21
45
|
if (chunkCount === 0 && type === 0x4e4f534a) {
|
|
22
|
-
|
|
46
|
+
try {
|
|
47
|
+
json = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(new Uint8Array(bytes, offset, size)));
|
|
48
|
+
}
|
|
49
|
+
catch {
|
|
50
|
+
throw new VrmInspectionError("INVALID_GLB", "invalid GLB JSON; re-export the file with a VRM exporter");
|
|
51
|
+
}
|
|
23
52
|
}
|
|
24
53
|
else if (chunkCount === 1 && type === 0x004e4942) {
|
|
25
54
|
binSize = size;
|
|
26
55
|
binStart = offset;
|
|
27
56
|
}
|
|
28
57
|
else
|
|
29
|
-
throw new
|
|
58
|
+
throw new VrmInspectionError("INVALID_GLB", "unexpected GLB chunk; export a self-contained VRM/VRMA file");
|
|
30
59
|
offset += size;
|
|
31
60
|
chunkCount++;
|
|
32
61
|
}
|
|
33
|
-
if (!json || json.asset?.version !== "2.0")
|
|
34
|
-
throw new
|
|
62
|
+
if (!json || typeof json !== "object" || Array.isArray(json) || json.asset?.version !== "2.0")
|
|
63
|
+
throw new VrmInspectionError("UNSUPPORTED_FORMAT", "glTF 2.0 is required; use a VRM/VRMA exporter");
|
|
35
64
|
const expected = kind === "vrm" ? (json.extensions?.VRM ?? json.extensions?.VRMC_vrm) : json.extensions?.VRMC_vrm_animation;
|
|
36
65
|
if (!expected)
|
|
37
|
-
throw new
|
|
66
|
+
throw new VrmInspectionError("UNSUPPORTED_FORMAT", `missing ${kind} extension; export ${kind === "vrm" ? "VRM 0.0 or 1.0" : "VRMA 1.0"}, not a plain GLB`);
|
|
38
67
|
if (kind === "vrm" && json.extensions?.VRM && json.extensions.VRM.specVersion !== "0.0")
|
|
39
|
-
throw new
|
|
68
|
+
throw new VrmInspectionError("UNSUPPORTED_VERSION", "unsupported VRM version; export VRM 0.0 or 1.0");
|
|
40
69
|
if (kind === "vrm" && json.extensions?.VRMC_vrm && json.extensions.VRMC_vrm.specVersion !== "1.0")
|
|
41
|
-
throw new
|
|
70
|
+
throw new VrmInspectionError("UNSUPPORTED_VERSION", "unsupported VRM version; export VRM 0.0 or 1.0");
|
|
42
71
|
if (kind === "vrma" && expected.specVersion !== "1.0")
|
|
43
|
-
throw new
|
|
72
|
+
throw new VrmInspectionError("UNSUPPORTED_VERSION", "VRMA 1.0 is required");
|
|
44
73
|
const allowed = new Set(["VRM", "VRMC_vrm", "VRMC_vrm_animation", "VRMC_materials_mtoon", "VRMC_springBone", "VRMC_node_constraint", "VRMC_materials_hdr_emissiveMultiplier", "KHR_materials_unlit", "KHR_texture_transform", "KHR_materials_emissive_strength"]);
|
|
45
74
|
if ((json.extensionsRequired ?? []).some((name) => !allowed.has(name)))
|
|
46
|
-
throw new
|
|
75
|
+
throw new VrmInspectionError("UNSUPPORTED_EXTENSION", "unsupported required glTF extension; re-export without geometry or texture compression extensions");
|
|
47
76
|
// No externally resolved buffers, images or extension URIs. The loader only
|
|
48
77
|
// receives self-contained GLB; model import cannot access the network or disk.
|
|
49
78
|
const visit = (value, depth = 0) => {
|
|
50
79
|
if (depth > 64)
|
|
51
|
-
throw new
|
|
80
|
+
throw new VrmInspectionError("RESOURCE_LIMIT", "glTF nesting limit exceeded");
|
|
52
81
|
if (!value || typeof value !== "object")
|
|
53
82
|
return;
|
|
54
83
|
for (const [key, child] of Object.entries(value)) {
|
|
55
84
|
if (key === "uri")
|
|
56
|
-
throw new
|
|
85
|
+
throw new VrmInspectionError("EXTERNAL_RESOURCE", "external glTF resources are not supported; embed all textures and buffers in one VRM/VRMA file");
|
|
57
86
|
if (typeof child === "number" && !Number.isFinite(child))
|
|
58
|
-
throw new
|
|
87
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "non-finite glTF value");
|
|
59
88
|
visit(child, depth + 1);
|
|
60
89
|
}
|
|
61
90
|
};
|
|
62
91
|
visit(json);
|
|
63
92
|
if ((json.buffers?.length ?? 0) > 1 || (json.buffers?.[0]?.byteLength ?? 0) > binSize)
|
|
64
|
-
throw new
|
|
93
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid GLB buffer");
|
|
65
94
|
for (const buffer of json.bufferViews ?? []) {
|
|
66
95
|
const start = buffer.byteOffset ?? 0, length = buffer.byteLength;
|
|
67
96
|
if (buffer.buffer !== 0 || !Number.isSafeInteger(start) || !Number.isSafeInteger(length) || start < 0 || length < 0 || start + length > (json.buffers?.[0]?.byteLength ?? 0))
|
|
68
|
-
throw new
|
|
97
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF buffer view");
|
|
69
98
|
}
|
|
70
99
|
if ((json.nodes?.length ?? 0) > 4096 || (json.accessors?.length ?? 0) > 32768)
|
|
71
|
-
throw new
|
|
100
|
+
throw new VrmInspectionError("RESOURCE_LIMIT", "glTF resource count exceeded");
|
|
72
101
|
validateStructure(json, new DataView(bytes, binStart, binSize));
|
|
73
102
|
return json;
|
|
74
103
|
}
|
|
75
104
|
export function embeddedAnimationCatalog(json) {
|
|
76
105
|
const animations = json.animations ?? [];
|
|
77
106
|
if (!Array.isArray(animations) || animations.length > 64)
|
|
78
|
-
throw new
|
|
107
|
+
throw new VrmInspectionError("INVALID_ANIMATION", "at most 64 embedded animations are supported");
|
|
79
108
|
const names = new Set();
|
|
80
109
|
return animations.map((animation, index) => {
|
|
81
110
|
const name = animation.name ?? "Animation_" + (index + 1);
|
|
82
111
|
if (typeof name !== "string" || !name.trim() || new TextEncoder().encode(name).length > 128 || /[\u0000-\u001f\u007f]/.test(name) || name === "StarLiteIdle" || names.has(name))
|
|
83
|
-
throw new
|
|
112
|
+
throw new VrmInspectionError("INVALID_ANIMATION", "invalid or duplicate embedded animation name; use unique names of at most 128 UTF-8 bytes, excluding StarLiteIdle");
|
|
84
113
|
names.add(name);
|
|
85
114
|
let duration = 0;
|
|
86
115
|
for (const sampler of animation.samplers ?? []) {
|
|
87
116
|
const accessor = json.accessors?.[sampler.input];
|
|
88
117
|
if (!accessor || accessor.type !== "SCALAR" || accessor.componentType !== 5126 || !Number.isFinite(accessor.max?.[0]))
|
|
89
|
-
throw new
|
|
118
|
+
throw new VrmInspectionError("INVALID_ANIMATION", "embedded animation has invalid animation times");
|
|
90
119
|
duration = Math.max(duration, accessor.max[0]);
|
|
91
120
|
}
|
|
92
121
|
if (!(duration > 0) || duration > 600)
|
|
93
|
-
throw new
|
|
122
|
+
throw new VrmInspectionError("INVALID_ANIMATION", "embedded animation duration must be between 0 and 600 seconds");
|
|
94
123
|
return { name, durationMs: duration * 1000 };
|
|
95
124
|
});
|
|
96
125
|
}
|
|
97
126
|
export function inspectVrm(bytes) {
|
|
98
127
|
const json = parseGlb(bytes, "vrm");
|
|
99
128
|
const v0 = json.extensions.VRM;
|
|
100
|
-
const
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
const
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
129
|
+
const extension = v0 ?? json.extensions.VRMC_vrm;
|
|
130
|
+
if (Array.isArray(json.extensionsUsed) && !json.extensionsUsed.includes(v0 ? "VRM" : "VRMC_vrm"))
|
|
131
|
+
throw new VrmInspectionError("UNSUPPORTED_FORMAT", "missing VRM extension declaration; re-export with the VRM exporter");
|
|
132
|
+
const bones = inspectHumanBones(json, extension.humanoid?.humanBones, Boolean(v0));
|
|
133
|
+
// Blink is an optional capability. Declared bindings must still be valid;
|
|
134
|
+
// missing, empty or zero-weight presets simply provide no automatic blink.
|
|
135
|
+
const blinkNames = v0 ? ["blink", "blink_l", "blink_r"] : ["blink", "blinkLeft", "blinkRight"];
|
|
136
|
+
const groups = v0?.blendShapeMaster?.blendShapeGroups;
|
|
137
|
+
if (groups !== undefined && !Array.isArray(groups))
|
|
138
|
+
throw new VrmInspectionError("INVALID_BLINK", "invalid VRM blink expressions; re-export the blink presets");
|
|
139
|
+
const aliases = { a: "aa", e: "ee", i: "ih", o: "oh", u: "ou", joy: "happy", angry: "angry", sorrow: "sad", fun: "relaxed", neutral: "neutral", blink: "blink", blink_l: "blinkLeft", blink_r: "blinkRight", lookup: "lookUp", lookdown: "lookDown", lookleft: "lookLeft", lookright: "lookRight" };
|
|
140
|
+
// VRM0 also allows custom expressions with a canonical preset name. Match
|
|
141
|
+
// the loader's first-registration rule instead of inventing capabilities
|
|
142
|
+
// from a later duplicate preset that will be ignored.
|
|
143
|
+
const registeredName = (item) => aliases[item?.presetName] ?? item?.name;
|
|
144
|
+
const expression = (name) => v0 ? (groups ?? []).find((item) => registeredName(item) === (aliases[name] ?? name)) : extension.expressions?.preset?.[name];
|
|
145
|
+
// Validate every declared preset, even a duplicate that the loader ignores.
|
|
146
|
+
for (const preset of blinkNames) {
|
|
147
|
+
const presets = v0 ? (groups ?? []).filter((item) => registeredName(item) === aliases[preset]) : expression(preset) === undefined ? [] : [expression(preset)];
|
|
148
|
+
for (const item of presets)
|
|
149
|
+
inspectMorphExpression(json, item, Boolean(v0), "INVALID_BLINK", preset);
|
|
109
150
|
}
|
|
110
|
-
const
|
|
111
|
-
|
|
112
|
-
const binds = v0 ? expressions?.find((item) => item.presetName === name)?.binds
|
|
113
|
-
: json.extensions.VRMC_vrm.expressions?.preset?.[name]?.morphTargetBinds;
|
|
114
|
-
return Array.isArray(binds) && binds.some((bind) => {
|
|
115
|
-
const mesh = v0 ? bind.mesh : json.nodes?.[bind.node]?.mesh;
|
|
116
|
-
const primitives = json.meshes?.[mesh]?.primitives;
|
|
117
|
-
return Number.isSafeInteger(mesh) && Number.isSafeInteger(bind.index) && bind.index >= 0
|
|
118
|
-
&& Number.isFinite(bind.weight) && bind.weight > 0 && bind.weight <= (v0 ? 100 : 1)
|
|
119
|
-
&& Array.isArray(primitives) && primitives.some((primitive) => primitive.targets?.[bind.index] !== undefined);
|
|
120
|
-
});
|
|
121
|
-
};
|
|
122
|
-
if (!usableBlink("blink") && !(v0 ? usableBlink("blink_l") && usableBlink("blink_r") : usableBlink("blinkLeft") && usableBlink("blinkRight"))) {
|
|
123
|
-
throw new Error("VRM needs usable blink morph bindings, or both left and right blink presets");
|
|
124
|
-
}
|
|
125
|
-
const meta = (v0 ?? json.extensions.VRMC_vrm).meta ?? {};
|
|
151
|
+
const [combined, left, right] = blinkNames.map(preset => inspectMorphExpression(json, expression(preset), Boolean(v0), "INVALID_BLINK", preset));
|
|
152
|
+
const meta = extension.meta ?? {};
|
|
126
153
|
const name = v0 ? meta.title : meta.name;
|
|
127
154
|
return {
|
|
128
155
|
version: v0 ? "0" : "1",
|
|
129
|
-
...(typeof name === "string" ? { name } : {}),
|
|
156
|
+
...(typeof name === "string" ? { name: safeLabel(name) } : {}),
|
|
130
157
|
animations: embeddedAnimationCatalog(json),
|
|
131
|
-
expressions: v0 ? (
|
|
158
|
+
expressions: (v0 ? (groups ?? []).map((group) => group?.name) : Object.keys({ ...extension.expressions?.preset, ...extension.expressions?.custom })).filter((value) => typeof value === "string").map(safeLabel),
|
|
159
|
+
capabilities: {
|
|
160
|
+
humanoid: { requiredBones: [...requiredBones], optionalBones: optionalBones.filter(name => bones.has(name)) },
|
|
161
|
+
blink: { automatic: Boolean(combined || (left && right)), combined: Boolean(combined), left: Boolean(left), right: Boolean(right) },
|
|
162
|
+
lookAt: inspectLookAt(json, extension, Boolean(v0), bones, expression),
|
|
163
|
+
},
|
|
164
|
+
metrics: inspectMetrics(json, bytes.byteLength),
|
|
165
|
+
};
|
|
166
|
+
}
|
|
167
|
+
function safeLabel(value) { return value.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 128); }
|
|
168
|
+
function inspectHumanBones(json, humanoid, v0) {
|
|
169
|
+
const known = new Set([...requiredBones, ...optionalBones]), result = new Map();
|
|
170
|
+
const invalid = [], duplicates = [], used = new Map();
|
|
171
|
+
const entries = v0 ? (Array.isArray(humanoid) ? humanoid.filter(item => item && known.has(item.bone)).map(item => [item.bone, item]) : [])
|
|
172
|
+
: humanoid && typeof humanoid === "object" && !Array.isArray(humanoid) ? Object.entries(humanoid).filter(([name]) => known.has(name)) : [];
|
|
173
|
+
for (const [name, value] of entries) {
|
|
174
|
+
const node = value?.node;
|
|
175
|
+
if (result.has(name))
|
|
176
|
+
duplicates.push(name);
|
|
177
|
+
if (!Number.isSafeInteger(node) || node < 0 || !json.nodes?.[node]) {
|
|
178
|
+
invalid.push(name);
|
|
179
|
+
continue;
|
|
180
|
+
}
|
|
181
|
+
const previous = used.get(node);
|
|
182
|
+
if (previous && previous !== name)
|
|
183
|
+
duplicates.push(previous, name);
|
|
184
|
+
used.set(node, name);
|
|
185
|
+
result.set(name, node);
|
|
186
|
+
}
|
|
187
|
+
const missing = requiredBones.filter(name => !result.has(name) && !invalid.includes(name));
|
|
188
|
+
if (missing.length || invalid.length || duplicates.length) {
|
|
189
|
+
const details = { missingBones: missing, invalidBones: [...new Set(invalid)], duplicateBones: [...new Set(duplicates)] };
|
|
190
|
+
const summary = [missing.length ? `missing ${missing.join(", ")}` : "", invalid.length ? `invalid node for ${details.invalidBones.join(", ")}` : "", duplicates.length ? `duplicate mapping for ${details.duplicateBones.join(", ")}` : ""].filter(Boolean).join("; ");
|
|
191
|
+
throw new VrmInspectionError("HUMANOID_BONES", `invalid required humanoid bone: ${summary}; assign separate human bones in the VRM exporter and export again`, details);
|
|
192
|
+
}
|
|
193
|
+
return result;
|
|
194
|
+
}
|
|
195
|
+
function inspectMorphExpression(json, expression, v0, code, preset) {
|
|
196
|
+
if (expression === undefined)
|
|
197
|
+
return false;
|
|
198
|
+
const label = code === "INVALID_BLINK" ? "blink" : "look-at";
|
|
199
|
+
if (!expression || typeof expression !== "object" || Array.isArray(expression))
|
|
200
|
+
throw new VrmInspectionError(code, `invalid VRM ${label} expression; re-export the ${preset} preset`, { preset });
|
|
201
|
+
const binds = v0 ? expression.binds : expression.morphTargetBinds;
|
|
202
|
+
if (binds === undefined)
|
|
203
|
+
return false;
|
|
204
|
+
if (!Array.isArray(binds))
|
|
205
|
+
throw new VrmInspectionError(code, `invalid VRM ${label} bindings; re-export the ${preset} preset`, { preset });
|
|
206
|
+
let usable = false;
|
|
207
|
+
for (const bind of binds) {
|
|
208
|
+
const mesh = v0 ? bind?.mesh : json.nodes?.[bind?.node]?.mesh;
|
|
209
|
+
const primitives = json.meshes?.[mesh]?.primitives;
|
|
210
|
+
if (!bind || !Number.isSafeInteger(mesh) || mesh < 0
|
|
211
|
+
|| (!v0 && (!Number.isSafeInteger(bind.node) || bind.node < 0))
|
|
212
|
+
|| !Number.isSafeInteger(bind.index) || bind.index < 0
|
|
213
|
+
|| !Number.isFinite(bind.weight) || bind.weight < 0 || bind.weight > (v0 ? 100 : 1)
|
|
214
|
+
|| !Array.isArray(primitives) || !primitives.length || !primitives.every((primitive) => primitive?.targets?.[bind.index] !== undefined)) {
|
|
215
|
+
throw new VrmInspectionError(code, `invalid VRM ${label} morph binding: ${preset}; check its mesh/node, morph target index and weight in the VRM exporter`, { preset });
|
|
216
|
+
}
|
|
217
|
+
// The loader drops a bind if any primitive lacks morph influences. A mesh
|
|
218
|
+
// not referenced by a node also cannot provide a working eyelid.
|
|
219
|
+
const instantiated = !v0 || (json.nodes ?? []).some((node) => node?.mesh === mesh);
|
|
220
|
+
const morphs = primitives.every((primitive) => primitive.targets.some((target) => ["POSITION", "NORMAL", "COLOR_0"].some(semantic => Number.isSafeInteger(target?.[semantic]) && json.accessors?.[target[semantic]])));
|
|
221
|
+
usable ||= bind.weight > 0 && instantiated && morphs;
|
|
222
|
+
}
|
|
223
|
+
return usable;
|
|
224
|
+
}
|
|
225
|
+
function inspectLookAt(json, extension, v0, bones, expression) {
|
|
226
|
+
const lookAt = v0 ? extension.firstPerson : extension.lookAt;
|
|
227
|
+
const empty = { mode: "none", head: true, eyes: false, horizontal: false, vertical: false };
|
|
228
|
+
if (lookAt === undefined)
|
|
229
|
+
return empty;
|
|
230
|
+
if (!lookAt || typeof lookAt !== "object" || Array.isArray(lookAt))
|
|
231
|
+
throw new VrmInspectionError("INVALID_LOOK_AT", "invalid VRM look-at configuration; re-export eye tracking");
|
|
232
|
+
// three-vrm imports lookAt only when an expression manager exists, including
|
|
233
|
+
// bone-driven lookAt. An absent expression section must not promise eye motion.
|
|
234
|
+
const expressionManager = v0 ? extension.blendShapeMaster : extension.expressions;
|
|
235
|
+
if (!expressionManager)
|
|
236
|
+
return empty;
|
|
237
|
+
const type = v0 ? lookAt.lookAtTypeName : lookAt.type;
|
|
238
|
+
if (type !== undefined && !(v0 ? ["Bone", "BlendShape"] : ["bone", "expression"]).includes(type))
|
|
239
|
+
throw new VrmInspectionError("INVALID_LOOK_AT", "invalid VRM look-at type; use bone or expression eye tracking in the VRM exporter");
|
|
240
|
+
const mode = type === (v0 ? "BlendShape" : "expression") ? "expression" : "bone";
|
|
241
|
+
const scale = (name) => {
|
|
242
|
+
const range = lookAt[name], value = range?.[v0 ? "yRange" : "outputScale"] ?? (mode === "expression" ? 1 : 10);
|
|
243
|
+
const input = range?.[v0 ? "xRange" : "inputMaxValue"] ?? 90;
|
|
244
|
+
if ((range !== undefined && (!range || typeof range !== "object" || Array.isArray(range))) || !Number.isFinite(value) || value < 0 || !Number.isFinite(input) || input < 0)
|
|
245
|
+
throw new VrmInspectionError("INVALID_LOOK_AT", "invalid VRM look-at range; use finite, non-negative input and output ranges");
|
|
246
|
+
return value;
|
|
132
247
|
};
|
|
248
|
+
const horizontalRange = scale(v0 ? "lookAtHorizontalOuter" : "rangeMapHorizontalOuter");
|
|
249
|
+
const innerRange = scale(v0 ? "lookAtHorizontalInner" : "rangeMapHorizontalInner");
|
|
250
|
+
const upRange = scale(v0 ? "lookAtVerticalUp" : "rangeMapVerticalUp"), downRange = scale(v0 ? "lookAtVerticalDown" : "rangeMapVerticalDown");
|
|
251
|
+
let horizontal, vertical;
|
|
252
|
+
if (mode === "bone") {
|
|
253
|
+
const eyes = bones.has("leftEye") || bones.has("rightEye");
|
|
254
|
+
horizontal = eyes && (horizontalRange > 0 || innerRange > 0);
|
|
255
|
+
vertical = eyes && (upRange > 0 || downRange > 0);
|
|
256
|
+
}
|
|
257
|
+
else {
|
|
258
|
+
const usable = (name) => inspectMorphExpression(json, expression(name), v0, "INVALID_LOOK_AT", name);
|
|
259
|
+
const left = usable(v0 ? "lookleft" : "lookLeft"), right = usable(v0 ? "lookright" : "lookRight"), up = usable(v0 ? "lookup" : "lookUp"), down = usable(v0 ? "lookdown" : "lookDown");
|
|
260
|
+
horizontal = horizontalRange > 0 && left && right;
|
|
261
|
+
vertical = upRange > 0 && downRange > 0 && up && down;
|
|
262
|
+
}
|
|
263
|
+
return { mode, head: true, eyes: horizontal || vertical, horizontal, vertical };
|
|
264
|
+
}
|
|
265
|
+
function inspectMetrics(json, fileBytes) {
|
|
266
|
+
const primitives = (json.meshes ?? []).flatMap((mesh) => Array.isArray(mesh?.primitives) ? mesh.primitives : []);
|
|
267
|
+
let vertexCount = 0, triangleCount = 0, morphTargetCount = 0;
|
|
268
|
+
for (const primitive of primitives) {
|
|
269
|
+
const vertices = json.accessors?.[primitive?.attributes?.POSITION]?.count ?? 0;
|
|
270
|
+
const indices = primitive?.indices === undefined ? vertices : json.accessors?.[primitive.indices]?.count ?? 0;
|
|
271
|
+
vertexCount += vertices;
|
|
272
|
+
if (primitive?.mode === undefined || primitive.mode === 4)
|
|
273
|
+
triangleCount += Math.floor(indices / 3);
|
|
274
|
+
else if (primitive.mode === 5 || primitive.mode === 6)
|
|
275
|
+
triangleCount += Math.max(0, indices - 2);
|
|
276
|
+
morphTargetCount += Array.isArray(primitive?.targets) ? primitive.targets.length : 0;
|
|
277
|
+
}
|
|
278
|
+
const widths = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 }, components = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 };
|
|
279
|
+
const decodedAccessorBytes = (json.accessors ?? []).reduce((sum, accessor) => {
|
|
280
|
+
const width = widths[accessor.componentType], dimension = accessor.type === "MAT2" ? 2 : accessor.type === "MAT3" ? 3 : accessor.type === "MAT4" ? 4 : 0;
|
|
281
|
+
return sum + accessor.count * (dimension ? Math.ceil(dimension * width / 4) * 4 * dimension : width * components[accessor.type]);
|
|
282
|
+
}, 0);
|
|
283
|
+
return { fileBytes, nodeCount: json.nodes?.length ?? 0, meshCount: json.meshes?.length ?? 0, primitiveCount: primitives.length, materialCount: json.materials?.length ?? 0, textureCount: json.textures?.length ?? 0, imageCount: json.images?.length ?? 0, vertexCount, triangleCount, morphTargetCount, decodedAccessorBytes };
|
|
133
284
|
}
|
|
134
285
|
export function inspectVrma(bytes) {
|
|
135
286
|
const json = parseGlb(bytes, "vrma");
|
|
136
287
|
if (json.animations?.length !== 1)
|
|
137
|
-
throw new
|
|
288
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "each VRMA file must contain exactly one animation");
|
|
138
289
|
let duration = 0;
|
|
139
290
|
for (const sampler of json.animations[0].samplers ?? []) {
|
|
140
291
|
const accessor = json.accessors?.[sampler.input];
|
|
141
292
|
if (!accessor || accessor.type !== "SCALAR" || accessor.componentType !== 5126 || !Number.isFinite(accessor.max?.[0]))
|
|
142
|
-
throw new
|
|
293
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "VRMA has invalid animation times");
|
|
143
294
|
duration = Math.max(duration, accessor.max[0]);
|
|
144
295
|
}
|
|
145
296
|
if (!(duration > 0) || duration > 600)
|
|
146
|
-
throw new
|
|
297
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "VRMA duration must be between 0 and 600 seconds");
|
|
147
298
|
return { durationMs: duration * 1000 };
|
|
148
299
|
}
|
|
149
300
|
function validateStructure(json, binary) {
|
|
150
|
-
for (const key of ["nodes", "accessors", "bufferViews", "buffers", "meshes", "images", "animations", "skins", "scenes"]) {
|
|
301
|
+
for (const key of ["nodes", "accessors", "bufferViews", "buffers", "meshes", "materials", "textures", "images", "animations", "skins", "scenes", "extensionsUsed", "extensionsRequired"]) {
|
|
151
302
|
if (json[key] !== undefined && !Array.isArray(json[key]))
|
|
152
|
-
throw new
|
|
303
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", `invalid glTF ${key}`);
|
|
153
304
|
}
|
|
154
305
|
const views = json.bufferViews ?? [], nodes = json.nodes ?? [], accessors = json.accessors ?? [];
|
|
155
306
|
const integer = (n, min, max) => Number.isSafeInteger(n) && n >= min && n <= max;
|
|
@@ -157,19 +308,19 @@ function validateStructure(json, binary) {
|
|
|
157
308
|
const seen = new Set(), active = new Set(), parents = new Set();
|
|
158
309
|
const walk = (i, depth) => {
|
|
159
310
|
if (!index(i, nodes) || active.has(i) || depth > 128)
|
|
160
|
-
throw new
|
|
311
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF node hierarchy");
|
|
161
312
|
if (seen.has(i))
|
|
162
313
|
return;
|
|
163
314
|
const node = nodes[i];
|
|
164
315
|
if (!node || typeof node !== "object")
|
|
165
|
-
throw new
|
|
316
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF node");
|
|
166
317
|
seen.add(i);
|
|
167
318
|
active.add(i);
|
|
168
319
|
if (node.children !== undefined && !Array.isArray(node.children))
|
|
169
|
-
throw new
|
|
320
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid node children");
|
|
170
321
|
for (const child of node.children ?? []) {
|
|
171
322
|
if (parents.has(child))
|
|
172
|
-
throw new
|
|
323
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "node has multiple parents");
|
|
173
324
|
parents.add(child);
|
|
174
325
|
walk(child, depth + 1);
|
|
175
326
|
}
|
|
@@ -182,28 +333,28 @@ function validateStructure(json, binary) {
|
|
|
182
333
|
let decoded = 0;
|
|
183
334
|
const span = (viewIndex, offset, count, element, alignment, strided = false) => {
|
|
184
335
|
if (!index(viewIndex, views))
|
|
185
|
-
throw new
|
|
336
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid accessor buffer view");
|
|
186
337
|
const v = views[viewIndex], stride = strided ? (v.byteStride ?? element) : element;
|
|
187
338
|
if (!integer(offset, 0, v.byteLength) || offset % alignment || !integer(stride, element, 256) || stride % alignment || offset + (count - 1) * stride + element > v.byteLength)
|
|
188
|
-
throw new
|
|
339
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "accessor exceeds buffer view");
|
|
189
340
|
return (v.byteOffset ?? 0) + offset;
|
|
190
341
|
};
|
|
191
342
|
for (const a of accessors) {
|
|
192
343
|
const width = sizes[a?.componentType], count = a?.count, componentsCount = components[a?.type];
|
|
193
344
|
if (!width || !componentsCount || !integer(count, 1, 2000000))
|
|
194
|
-
throw new
|
|
345
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid accessor allocation");
|
|
195
346
|
const dimension = a.type === "MAT2" ? 2 : a.type === "MAT3" ? 3 : a.type === "MAT4" ? 4 : 0;
|
|
196
347
|
const element = dimension ? Math.ceil(dimension * width / 4) * 4 * dimension : width * componentsCount;
|
|
197
348
|
decoded += element * count;
|
|
198
349
|
if (decoded > 256 * 1024 * 1024)
|
|
199
|
-
throw new
|
|
350
|
+
throw new VrmInspectionError("RESOURCE_LIMIT", "decoded geometry exceeds 256 MiB");
|
|
200
351
|
const checkFloats = (at, n, stride) => {
|
|
201
352
|
if (a.componentType !== 5126)
|
|
202
353
|
return;
|
|
203
354
|
for (let k = 0; k < n; k++)
|
|
204
355
|
for (let c = 0; c < componentsCount; c++)
|
|
205
356
|
if (!Number.isFinite(binary.getFloat32(at + k * stride + c * 4, true)))
|
|
206
|
-
throw new
|
|
357
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "non-finite accessor value");
|
|
207
358
|
};
|
|
208
359
|
if (a.bufferView !== undefined) {
|
|
209
360
|
const at = span(a.bufferView, a.byteOffset ?? 0, count, element, width, true);
|
|
@@ -212,7 +363,7 @@ function validateStructure(json, binary) {
|
|
|
212
363
|
if (a.sparse) {
|
|
213
364
|
const sparse = a.sparse, n = sparse.count, iw = sizes[sparse.indices?.componentType];
|
|
214
365
|
if (!integer(n, 1, count) || ![5121, 5123, 5125].includes(sparse.indices?.componentType))
|
|
215
|
-
throw new
|
|
366
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid sparse accessor");
|
|
216
367
|
const at = span(sparse.indices.bufferView, sparse.indices.byteOffset ?? 0, n, iw, iw);
|
|
217
368
|
const valuesAt = span(sparse.values?.bufferView, sparse.values?.byteOffset ?? 0, n, element, width);
|
|
218
369
|
checkFloats(valuesAt, n, element);
|
|
@@ -221,36 +372,74 @@ function validateStructure(json, binary) {
|
|
|
221
372
|
const offset = at + k * iw;
|
|
222
373
|
const next = iw === 1 ? binary.getUint8(offset) : iw === 2 ? binary.getUint16(offset, true) : binary.getUint32(offset, true);
|
|
223
374
|
if (next <= previous || next >= count)
|
|
224
|
-
throw new
|
|
375
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid sparse index");
|
|
225
376
|
previous = next;
|
|
226
377
|
}
|
|
227
378
|
}
|
|
228
379
|
}
|
|
380
|
+
// Validate the references used by capability and size reporting as well as
|
|
381
|
+
// the loader. Never infer a working morph from an arbitrary target object.
|
|
382
|
+
let primitiveCount = 0;
|
|
383
|
+
for (const mesh of json.meshes ?? []) {
|
|
384
|
+
if (!mesh || !Array.isArray(mesh.primitives) || !mesh.primitives.length)
|
|
385
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF mesh primitives");
|
|
386
|
+
primitiveCount += mesh.primitives.length;
|
|
387
|
+
if (primitiveCount > 32768)
|
|
388
|
+
throw new VrmInspectionError("RESOURCE_LIMIT", "glTF primitive count exceeded");
|
|
389
|
+
for (const primitive of mesh.primitives) {
|
|
390
|
+
const position = accessors[primitive?.attributes?.POSITION];
|
|
391
|
+
if (!primitive || !position || position.type !== "VEC3" || position.componentType !== 5126)
|
|
392
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF primitive POSITION accessor");
|
|
393
|
+
if (primitive.indices !== undefined) {
|
|
394
|
+
const indices = accessors[primitive.indices];
|
|
395
|
+
if (!index(primitive.indices, accessors) || indices.type !== "SCALAR" || ![5121, 5123, 5125].includes(indices.componentType))
|
|
396
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF primitive index accessor");
|
|
397
|
+
}
|
|
398
|
+
if (primitive.mode !== undefined && !integer(primitive.mode, 0, 6))
|
|
399
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF primitive mode");
|
|
400
|
+
if (primitive.targets !== undefined && (!Array.isArray(primitive.targets) || primitive.targets.length > 1024))
|
|
401
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF morph target list");
|
|
402
|
+
for (const target of primitive.targets ?? []) {
|
|
403
|
+
if (!target || typeof target !== "object" || Array.isArray(target))
|
|
404
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF morph target");
|
|
405
|
+
for (const semantic of ["POSITION", "NORMAL", "COLOR_0"]) {
|
|
406
|
+
if (target[semantic] === undefined)
|
|
407
|
+
continue;
|
|
408
|
+
const accessor = accessors[target[semantic]];
|
|
409
|
+
if (!index(target[semantic], accessors) || accessor.componentType !== 5126 || !(semantic === "COLOR_0" ? ["VEC3", "VEC4"] : ["VEC3"]).includes(accessor.type) || accessor.count !== position.count)
|
|
410
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF morph target accessor");
|
|
411
|
+
}
|
|
412
|
+
}
|
|
413
|
+
}
|
|
414
|
+
}
|
|
415
|
+
for (const node of nodes)
|
|
416
|
+
if (node.mesh !== undefined && !index(node.mesh, json.meshes ?? []))
|
|
417
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid glTF node mesh reference");
|
|
229
418
|
for (const animation of json.animations ?? []) {
|
|
230
419
|
if (!Array.isArray(animation.samplers) || !Array.isArray(animation.channels))
|
|
231
|
-
throw new
|
|
420
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid animation");
|
|
232
421
|
for (const channel of animation.channels) {
|
|
233
422
|
if (!index(channel.sampler, animation.samplers) || !index(channel.target?.node, nodes) || !["translation", "rotation", "scale", "weights"].includes(channel.target?.path))
|
|
234
|
-
throw new
|
|
423
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid animation channel");
|
|
235
424
|
}
|
|
236
425
|
for (const sampler of animation.samplers) {
|
|
237
426
|
if (!index(sampler.input, accessors) || !index(sampler.output, accessors))
|
|
238
|
-
throw new
|
|
427
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid animation accessor");
|
|
239
428
|
const a = accessors[sampler.input];
|
|
240
429
|
if (a.type !== "SCALAR" || a.componentType !== 5126 || a.sparse || a.bufferView === undefined)
|
|
241
|
-
throw new
|
|
430
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid animation timeline");
|
|
242
431
|
const start = span(a.bufferView, a.byteOffset ?? 0, a.count, 4, 4);
|
|
243
432
|
let previous = -1;
|
|
244
433
|
for (let i = 0; i < a.count; i++) {
|
|
245
434
|
const time = binary.getFloat32(start + i * 4, true);
|
|
246
435
|
if (!Number.isFinite(time) || time <= previous || time < 0 || time > 600)
|
|
247
|
-
throw new
|
|
436
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "invalid animation times");
|
|
248
437
|
previous = time;
|
|
249
438
|
}
|
|
250
439
|
if (!Array.isArray(a.max) || Math.abs(a.max[0] - previous) > .001)
|
|
251
|
-
throw new
|
|
440
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "animation duration does not match timeline");
|
|
252
441
|
if (sampler.interpolation !== undefined && !["LINEAR", "STEP", "CUBICSPLINE"].includes(sampler.interpolation))
|
|
253
|
-
throw new
|
|
442
|
+
throw new VrmInspectionError("INVALID_STRUCTURE", "unsupported animation interpolation");
|
|
254
443
|
}
|
|
255
444
|
}
|
|
256
445
|
}
|
package/dist/playback.js
CHANGED
|
@@ -6,6 +6,8 @@ export class VrmAnimationPlayer {
|
|
|
6
6
|
#clips;
|
|
7
7
|
#restore;
|
|
8
8
|
#returnTo;
|
|
9
|
+
#lookAtClips = new Set();
|
|
10
|
+
#blinkClips = new Set();
|
|
9
11
|
#active;
|
|
10
12
|
#finished = false;
|
|
11
13
|
#transition;
|
|
@@ -14,16 +16,36 @@ export class VrmAnimationPlayer {
|
|
|
14
16
|
if (returnTo && !clips.has(returnTo))
|
|
15
17
|
throw new Error(`return animation does not exist: ${returnTo}`);
|
|
16
18
|
this.mixer = new AnimationMixer(root);
|
|
17
|
-
this.#clips = clips;
|
|
18
19
|
this.#restore = restore;
|
|
19
20
|
this.#returnTo = returnTo;
|
|
21
|
+
this.#clips = new Map([...clips].map(([name, clip]) => {
|
|
22
|
+
if (clip.tracks.some(track => track.name.includes("LookAt")))
|
|
23
|
+
this.#lookAtClips.add(name);
|
|
24
|
+
if (clip.tracks.some(track => /VRMExpression_blink(?:Left|Right)?\.weight$/.test(track.name)))
|
|
25
|
+
this.#blinkClips.add(name);
|
|
26
|
+
// Embedded glTF uses UUIDs while VRMA uses names for the same rig nodes.
|
|
27
|
+
// Both actions and snapshots must share a binding key; otherwise two
|
|
28
|
+
// PropertyMixers overwrite each other and restore a stale pose on exit.
|
|
29
|
+
const tracks = clip.tracks.map(track => {
|
|
30
|
+
const parsed = PropertyBinding.parseTrackName(track.name);
|
|
31
|
+
const node = PropertyBinding.findNode(root, parsed.nodeName);
|
|
32
|
+
if (!node)
|
|
33
|
+
return track;
|
|
34
|
+
const object = parsed.objectName ? "." + parsed.objectName + (parsed.objectIndex !== undefined ? "[" + parsed.objectIndex + "]" : "") : "";
|
|
35
|
+
const canonical = node.uuid + object + "." + parsed.propertyName + (parsed.propertyIndex !== undefined ? "[" + parsed.propertyIndex + "]" : "");
|
|
36
|
+
// A shallow track wrapper retains cubic interpolants and shares the
|
|
37
|
+
// potentially large immutable time/value arrays with the source clip.
|
|
38
|
+
return canonical === track.name ? track : Object.assign(Object.create(Object.getPrototypeOf(track)), track, { name: canonical });
|
|
39
|
+
});
|
|
40
|
+
return [name, new AnimationClip(clip.name, clip.duration, tracks, clip.blendMode)];
|
|
41
|
+
}));
|
|
20
42
|
this.mixer.addEventListener("finished", (event) => { if (event.action === this.#active?.action)
|
|
21
43
|
this.#finished = true; });
|
|
22
44
|
}
|
|
23
45
|
get activeName() { return this.#active?.name; }
|
|
24
46
|
get isOneShot() { return this.#active?.action.loop === LoopOnce; }
|
|
25
|
-
get hasLookAtTrack() { return this.#
|
|
26
|
-
get hasBlinkTrack() { return this.#
|
|
47
|
+
get hasLookAtTrack() { return this.#lookAtClips.has(this.#active?.name ?? ""); }
|
|
48
|
+
get hasBlinkTrack() { return this.#blinkClips.has(this.#active?.name ?? ""); }
|
|
27
49
|
play(name, options = {}) {
|
|
28
50
|
const clip = this.#clips.get(name);
|
|
29
51
|
if (!clip)
|