初始化 VRMify 增强版(VRMify Enhanced)
Tests / test (push) Has been cancelled

导入上游源码,为所有面向用户的品牌显示处添加「增强版 / Enhanced」标识;包含 unitypackage→VRM 的纯色 Toon 材质、兽耳 SpringBone、Unity 描边、UV 接缝白边补偿修复,以及默认不强制 T-pose。146 个单元测试通过。
This commit is contained in:
2026-11-15 23:21:59 +08:00
commit 60cce66993
114 changed files with 56114 additions and 0 deletions
+358
View File
@@ -0,0 +1,358 @@
# -*- coding: utf-8 -*-
"""VRM 文件静态检查:结构、SpringBone、官方 JSON Schema、导入器会踩的坑。
python tools/qa/check_vrm.py 文件或目录 [...] [--no-schema] [-v]
逐个文件检查(目录会递归找 .vrm),有问题的打印出来,最后汇总;有错误时退出码为 1。
* humanoid:骨位名合法、必需骨位齐全、每根骨的 VRM 父骨位确实是它的祖先、
用占位骨(vrm_*)补的骨位(道具 / 非人形模型会有,记为提示)。
* 网格:JOINTS_0 不越界;同一网格里 morph target 不重名(Unity 遇到重名的
BlendShape 会抛异常,UniVRM 导入直接中断)。
* 表情:materialColorBinds 的材质号、morphTargetBinds 的 node / index 在范围内。
* SpringBone(VRM 1.0):相邻关节是祖先关系、关节不落在 humanoid 骨上、参数有限、
碰撞组号合法、同一节点不重复当关节。
* SpringBone(VRM 0.x):硬度键名是 stiffiness、参数有限、碰撞组号合法、组根子树不含
humanoid 骨、同一节点不落在两个组的子树里(0.x 组根下面整棵子树都会摆动)。
* Schema:用 vrm-c/vrm-specification 的官方 JSON Schema 校验 VRMC_vrm、
VRMC_springBone、VRMC_materials_mtoon,以及 VRM 0.x 的 VRM 扩展。需要 jsonschema 包;第一次运行时从 GitHub
下载固定版本的 schema,缓存在 tools/qa/.schema-cache/。UniVRM 对不合规的数据很少
容错(例如 targetValue 少一个分量就 IndexOutOfRange),所以这一项很有用。
"""
import argparse
import json
import math
import os
import sys
import urllib.request
from collections import Counter
HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(os.path.dirname(HERE))
sys.path[:0] = [os.path.join(ROOT, "formats"), os.path.join(ROOT, "convert")]
import vrmio # noqa: E402
from vrmconv.humanoid import _vrm_anchor # noqa: E402
# ---------------------------------------------------------------- humanoid --
_B10 = set("hips spine chest upperChest neck head leftEye rightEye jaw leftUpperLeg leftLowerLeg "
"leftFoot leftToes rightUpperLeg rightLowerLeg rightFoot rightToes leftShoulder "
"leftUpperArm leftLowerArm leftHand rightShoulder rightUpperArm rightLowerArm "
"rightHand".split())
_B0 = set(_B10)
for _s in ("left", "right"):
_B10 |= {_s + "ThumbMetacarpal", _s + "ThumbProximal", _s + "ThumbDistal"}
_B0 |= {_s + "ThumbProximal", _s + "ThumbIntermediate", _s + "ThumbDistal"}
for _f in ("Index", "Middle", "Ring", "Little"):
for _j in ("Proximal", "Intermediate", "Distal"):
_B10.add(_s + _f + _j)
_B0.add(_s + _f + _j)
_REQ = ("hips spine head leftUpperArm leftLowerArm leftHand rightUpperArm rightLowerArm "
"rightHand leftUpperLeg leftLowerLeg leftFoot rightUpperLeg rightLowerLeg "
"rightFoot").split()
# ------------------------------------------------------------------ schema --
SPEC_COMMIT = "94e82dd346fa6cf0337c4421728640e5252dd38e" # vrm-c/vrm-specification
SPEC_URL = "https://raw.githubusercontent.com/vrm-c/vrm-specification/%s/specification/%s/schema/%s"
SPEC_FILES = {
"VRMC_vrm-1.0": [
"VRMC_vrm.schema.json", "VRMC_vrm.meta.schema.json", "VRMC_vrm.humanoid.schema.json",
"VRMC_vrm.humanoid.humanBones.schema.json",
"VRMC_vrm.humanoid.humanBones.humanBone.schema.json",
"VRMC_vrm.firstPerson.schema.json", "VRMC_vrm.firstPerson.meshAnnotation.schema.json",
"VRMC_vrm.lookAt.schema.json", "VRMC_vrm.lookAt.rangeMap.schema.json",
"VRMC_vrm.expressions.schema.json", "VRMC_vrm.expressions.expression.schema.json",
"VRMC_vrm.expressions.expression.materialColorBind.schema.json",
"VRMC_vrm.expressions.expression.morphTargetBind.schema.json",
"VRMC_vrm.expressions.expression.textureTransformBind.schema.json"],
"VRMC_springBone-1.0": [
"VRMC_springBone.schema.json", "VRMC_springBone.collider.schema.json",
"VRMC_springBone.colliderGroup.schema.json", "VRMC_springBone.joint.schema.json",
"VRMC_springBone.shape.schema.json", "VRMC_springBone.spring.schema.json"],
"VRMC_materials_mtoon-1.0": [
"VRMC_materials_mtoon.schema.json", "mtoon.shadingShiftTexture.schema.json"],
"0.0": [
"vrm.schema.json", "vrm.meta.schema.json", "vrm.humanoid.schema.json", "vrm.humanoid.bone.schema.json",
"vrm.firstperson.schema.json", "vrm.firstperson.degreemap.schema.json",
"vrm.firstperson.meshannotation.schema.json", "vrm.blendshape.schema.json",
"vrm.blendshape.group.schema.json", "vrm.blendshape.bind.schema.json",
"vrm.blendshape.materialbind.schema.json", "vrm.secondaryanimation.schema.json",
"vrm.secondaryanimation.spring.schema.json", "vrm.secondaryanimation.collidergroup.schema.json",
"vrm.material.schema.json"],
}
# glTF 本体的几个 schema 只被引用、不需要逐项校验,用最小定义代替
_GLTF_STUBS = {
"glTFProperty.schema.json": {"type": "object"},
"glTFid.schema.json": {"type": "integer", "minimum": 0},
"textureInfo.schema.json": {"type": "object", "required": ["index"],
"properties": {"index": {"type": "integer", "minimum": 0},
"texCoord": {"type": "integer", "minimum": 0}}},
}
_BASE = "https://vrm-spec.invalid/"
def load_validators():
"""→ {扩展名: validator};缺 jsonschema 或下载失败时返回 (None, 原因)。"""
try:
import jsonschema
from referencing import Registry, Resource
from referencing.jsonschema import DRAFT4
except ImportError:
return None, "未安装 jsonschema(pip install jsonschema),跳过 Schema 校验"
cache = os.path.join(HERE, ".schema-cache", SPEC_COMMIT[:12])
docs = dict(_GLTF_STUBS)
for d, files in SPEC_FILES.items():
for fn in files:
path = os.path.join(cache, fn)
if not os.path.isfile(path):
os.makedirs(cache, exist_ok=True)
try:
with urllib.request.urlopen(SPEC_URL % (SPEC_COMMIT, d, fn), timeout=30) as r:
data = r.read()
except OSError as e:
return None, "下载 schema 失败(%s),跳过 Schema 校验" % e
with open(path, "wb") as f:
f.write(data)
with open(path, encoding="utf-8") as f:
docs[fn] = json.load(f)
resources = []
for fn, doc in docs.items():
# draft-04 用 id(不是 $id)定基准 URI,相对的 $ref 才解析得到
doc = dict({k: v for k, v in doc.items() if k not in ("$schema", "$id")}, id=_BASE + fn)
resources.append((_BASE + fn, Resource.from_contents(doc, default_specification=DRAFT4)))
registry = Registry().with_resources(resources)
out = {}
for ext, fn in (("VRMC_vrm", "VRMC_vrm"), ("VRMC_springBone", "VRMC_springBone"),
("VRMC_materials_mtoon", "VRMC_materials_mtoon"), ("VRM", "vrm")):
schema = registry.contents(_BASE + fn + ".schema.json")
out[ext] = jsonschema.Draft4Validator(schema, registry=registry)
return out, None
def schema_errors(g, validators):
errs = []
def run(ext, obj, where):
for e in validators[ext].iter_errors(obj):
path = "/".join(str(p) for p in e.absolute_path)
errs.append("schema %s/%s: %s" % (where, path, e.message[:120]))
ext = g.get("extensions", {})
if "VRMC_vrm" in ext:
run("VRMC_vrm", ext["VRMC_vrm"], "VRMC_vrm")
if "VRMC_springBone" in ext:
run("VRMC_springBone", ext["VRMC_springBone"], "VRMC_springBone")
if "VRM" in ext:
run("VRM", ext["VRM"], "VRM")
for i, m in enumerate(g.get("materials", [])):
mt = m.get("extensions", {}).get("VRMC_materials_mtoon")
if mt is not None:
run("VRMC_materials_mtoon", mt, "materials/%d/mtoon" % i)
return errs
# ------------------------------------------------------------------ checks --
def check(path, validators=None):
"""→ (错误列表, 提示列表, 摘要 dict)"""
errs, notes = [], []
g, b = vrmio.read_glb(path)
ext = g.get("extensions", {})
nodes = g["nodes"]
par = {c: i for i, n in enumerate(nodes) for c in n.get("children", [])}
is1 = "VRMC_vrm" in ext
if not is1 and "VRM" not in ext:
return ["不是 VRM(没有 VRMC_vrm / VRM 扩展)"], [], {}
# humanoid
if is1:
hb = {k: v["node"] for k, v in ext["VRMC_vrm"]["humanoid"]["humanBones"].items()}
valid, req = _B10, _REQ
else:
hb = {x["bone"]: x["node"] for x in ext["VRM"]["humanoid"]["humanBones"]}
valid, req = _B0, _REQ + ["chest", "neck"]
for k in sorted(set(hb) - valid):
errs.append("humanoid:非法骨位 %s" % k)
for k in req:
if k not in hb:
errs.append("humanoid:缺少必需骨位 %s" % k)
for h, n in hb.items():
a = _vrm_anchor(h, hb)
if a is None:
continue
p = par.get(n)
while p is not None and p != hb[a]:
p = par.get(p)
if p is None:
errs.append("humanoid:%s 不在 %s 之下" % (h, a))
placeholders = sorted(h for h, n in hb.items() if nodes[n].get("name", "").startswith("vrm_"))
if placeholders:
notes.append("humanoid:%d 根占位骨(%s)" % (len(placeholders), ", ".join(placeholders[:6])
+ (" …" if len(placeholders) > 6 else "")))
# mesh
njoints = len(g["skins"][0]["joints"]) if g.get("skins") else 0
for mi, m in enumerate(g.get("meshes", [])):
for pr in m["primitives"]:
if "JOINTS_0" in pr["attributes"]:
if max(vrmio.read_accessor(g, b, pr["attributes"]["JOINTS_0"])) >= njoints:
errs.append("mesh %d:JOINTS_0 超出 skin.joints" % mi)
break
names = (m.get("extras") or {}).get("targetNames") or []
for k, v in Counter(names).items():
if v > 1:
errs.append("mesh %d:morph target 重名「%s」×%d(Unity 导入会中断)" % (mi, k, v))
# expressions
nm = len(g.get("materials", []))
if is1:
groups = ext["VRMC_vrm"].get("expressions", {})
for grp in ("preset", "custom"):
for name, e in (groups.get(grp) or {}).items():
for bnd in e.get("materialColorBinds", []):
if not 0 <= bnd["material"] < nm:
errs.append("表情 %s:材质号 %d 越界" % (name, bnd["material"]))
for bnd in e.get("morphTargetBinds", []):
node = nodes[bnd["node"]] if 0 <= bnd["node"] < len(nodes) else {}
if "mesh" not in node:
errs.append("表情 %s:node %d 没有网格" % (name, bnd["node"]))
continue
nt = len(g["meshes"][node["mesh"]]["primitives"][0].get("targets", []))
if not 0 <= bnd["index"] < nt:
errs.append("表情 %s:morph 索引 %d 越界(共 %d)" % (name, bnd["index"], nt))
# SpringBone
summary = {"spec": "1.0" if is1 else "0.x", "humanBones": len(hb),
"placeholders": len(placeholders)}
sb = ext.get("VRMC_springBone")
if sb:
hum = set(hb.values())
seen = Counter()
ncg = len(sb.get("colliderGroups", []))
for sp in sb["springs"]:
js = sp["joints"]
for a, c in zip(js, js[1:]):
q = par.get(c["node"])
while q is not None and q != a["node"]:
q = par.get(q)
if q is None:
errs.append("SpringBone %s:%s 不是 %s 的后代" % (
sp.get("name"), nodes[c["node"]]["name"], nodes[a["node"]]["name"]))
for j in js:
seen[j["node"]] += 1
if j["node"] in hum:
errs.append("SpringBone %s:关节落在 humanoid 骨 %s 上"
% (sp.get("name"), nodes[j["node"]]["name"]))
for k in ("hitRadius", "stiffness", "gravityPower", "dragForce"):
if k in j and not math.isfinite(j[k]):
errs.append("SpringBone %s:%s 不是有限值" % (sp.get("name"), k))
for cg in sp.get("colliderGroups", []):
if not 0 <= cg < ncg:
errs.append("SpringBone %s:碰撞组号 %d 越界" % (sp.get("name"), cg))
for n, c in seen.items():
if c > 1:
errs.append("SpringBone:节点 %s 在 %d 条链里当关节" % (nodes[n]["name"], c))
summary.update(springs=len(sb["springs"]),
joints=sum(len(sp["joints"]) for sp in sb["springs"]),
colliders=len(sb.get("colliders", [])))
sa = None if is1 else ext["VRM"].get("secondaryAnimation")
if sa and sa.get("boneGroups"):
errs += _check_secondary(sa, nodes, par, set(hb.values()))
summary.update(springs=len(sa["boneGroups"]),
colliders=sum(len(c.get("colliders", [])) for c in sa.get("colliderGroups", [])))
if validators:
errs += schema_errors(g, validators)
return errs, notes, summary
def _check_secondary(sa, nodes, par, hum):
"""VRM 0.x 的 secondaryAnimation:组根子树整棵都会摆动,同一节点在两个组里会被模拟两次。"""
errs = []
kids = {i: n.get("children", []) for i, n in enumerate(nodes)}
ncg = len(sa.get("colliderGroups", []))
owner = {}
for gi, grp in enumerate(sa["boneGroups"]):
name = grp.get("comment") or "#%d" % gi
if "stiffness" in grp and "stiffiness" not in grp:
errs.append("secondaryAnimation %s:硬度要写成 stiffiness(规范里的拼写),stiffness 不会被读取" % name)
for k in ("stiffiness", "gravityPower", "dragForce", "hitRadius"):
if k in grp and not math.isfinite(grp[k]):
errs.append("secondaryAnimation %s:%s 不是有限值" % (name, k))
for cg in grp.get("colliderGroups", []):
if not 0 <= cg < ncg:
errs.append("secondaryAnimation %s:碰撞组号 %d 越界" % (name, cg))
for r in grp.get("bones", []):
if not 0 <= r < len(nodes):
errs.append("secondaryAnimation %s:根节点 %d 越界" % (name, r))
continue
stack = [r]
while stack:
n = stack.pop()
if n in hum:
errs.append("secondaryAnimation %s:humanoid 骨 %s 在摆动子树里" % (name, nodes[n]["name"]))
if n in owner:
errs.append("secondaryAnimation:节点 %s 同时在组 %s 和 %s 的子树里(会被模拟两次)"
% (nodes[n]["name"], owner[n], name))
continue
owner[n] = name
stack.extend(kids[n])
for ci, cg in enumerate(sa.get("colliderGroups", [])):
if not 0 <= cg.get("node", -1) < len(nodes):
errs.append("secondaryAnimation:碰撞组 %d 的节点越界" % ci)
return errs
def iter_files(paths):
for p in paths:
if os.path.isdir(p):
for d, _, fs in os.walk(p):
for f in sorted(fs):
if f.lower().endswith(".vrm"):
yield os.path.join(d, f)
else:
yield p
def main(argv=None):
ap = argparse.ArgumentParser(description="VRM 文件静态检查")
ap.add_argument("paths", nargs="+", help=".vrm 文件或目录")
ap.add_argument("--no-schema", action="store_true", help="不做官方 JSON Schema 校验")
ap.add_argument("-v", "--verbose", action="store_true", help="通过的文件也打印摘要和提示")
a = ap.parse_args(argv)
try:
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
except Exception:
pass
validators = None
if not a.no_schema:
validators, why = load_validators()
if why:
print("提示:" + why)
n = bad = 0
for path in iter_files(a.paths):
n += 1
try:
errs, notes, summ = check(path, validators)
except Exception as e: # noqa: BLE001 坏文件也要继续往下查
errs, notes, summ = ["读取失败:%s: %s" % (type(e).__name__, e)], [], {}
if errs:
bad += 1
print("✗ %s" % path)
shown = Counter()
for e in errs: # 同类错误只列前几条
key = e.split(":")[0] if ":" in e else e[:40]
shown[key] += 1
if shown[key] <= 5:
print(" " + e)
for k, c in shown.items():
if c > 5:
print(" …… %s 还有 %d 条" % (k, c - 5))
elif a.verbose:
print("✓ %s %s" % (path, " ".join("%s=%s" % kv for kv in summ.items())))
for t in notes:
print(" 提示:" + t)
print("检查 %d 个文件,%d 个有错误" % (n, bad))
return 1 if bad else 0
if __name__ == "__main__":
sys.exit(main())