初始化 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
+522
View File
@@ -0,0 +1,522 @@
# -*- coding: utf-8 -*-
"""PSK / PSKX 读取器(纯 Python 标准库,不需要 Blender / UE / FBX SDK)。
格式来源:Unreal Engine 的 ActorX 交换格式(.psk)及其扩展(.pskx)。
二进制布局以 DarklightGames/io_scene_psk_psa 的 psk_psa_py 为准,
并由本项目实测的样本文件(含 FACE3200 / VERTEXCOLOR / MRPHINFO / MRPHDATA
等扩展块)逐字段复核过。
文件结构
--------
整份文件是「块(section)」的线性序列,每个块:
struct Section { char name[20]; int32 type_flags; int32 data_size;
int32 data_count; } // 共 32 字节
紧接 data_size * data_count 字节的数据
块名与记录布局(offset 都是相对记录开头):
PNTS0000 Vector3 12 x,y,z 顶点(绑定姿势,物体空间)
VTXW0000 Wedge16 / Wedge32 16 uint32 point_index; float u, v;
uint32 material_index
FACE0000 Face16 12 uint16 i[3]; uint8 mat; uint8 aux;
int32 smoothing
FACE3200 Face32 18 uint32 i[3]; uint8 mat; uint8 aux;
int32 smoothing(紧凑排列)
MATT0000 Material 88 char name[64]; int32 ×6
REFSKELT Bone 120 char name[64]; int32 flags;
int32 children_count; int32 parent_index;
Quat rotation(x,y,z,w); Vector3 location;
float length; Vector3 size
RAWWEIGHTS Weight 12 float weight; int32 point_index;
int32 bone_index
VTXNORMS Vector3 12 顶点法线
VERTEXCOLOR Color 4 r,g,b,a(各 1 字节)
EXTRAUVS* Vector2 8 附加 UV(pskx,可有多套)
MRPHINFO MorphInfo 68 char name[64]; int32 vertex_count
MRPHDATA MorphData 28 Vector3 position_delta;
Vector3 tangent_z_delta; int32 point_index
两个实测坑(都已处理):
1) 部分游戏导出的文件在真正的 PSK 数据前面多写了 32 字节外层头(又是一个
ACTRHEAD,type_flags 位置放的是版本号 20220723)。按块序列顺序读即可自然
跳过:外层 ACTRHEAD 的 data_count=0,读完就落到第二个 ACTRHEAD 上。
2) 四元数要取共轭((x,y,z,w) → 取 (x,y,z) 的负号)后才是引擎常用右手系下
的旋转;不共轭的话骨骼世界坐标会整条链歪出去(实测头骨能偏 30 多个单位)。
"""
import os
import struct
__all__ = ["Psk", "PskBone", "PskMaterial", "PskMorph", "read_psk",
"bone_world", "quat_to_matrix", "write_psk"]
# 写入时用的块头版本号:实测样本(二重螺旋 R2T1*)的两个 ACTRHEAD 都放的是
# 20220723,照抄以保证同一套文件能被同一批工具读。标准 ActorX 写的是 1999801
# 之类的日期串,但那只是个标记,读者一般不校验。
PSK_VERSION = 20220723
# ------------------------------------------------------------------ data ---
class PskBone(object):
__slots__ = ("name", "flags", "children_count", "parent_index",
"rotation", "location", "length", "size")
def __init__(self, name, flags, children_count, parent_index,
rotation, location, length, size):
self.name = name
self.flags = flags
self.children_count = children_count
self.parent_index = parent_index
self.rotation = rotation # (x, y, z, w)
self.location = location # (x, y, z)
self.length = length
self.size = size # (x, y, z)
class PskMaterial(object):
__slots__ = ("name", "texture_index", "poly_flags", "aux_material",
"aux_flags", "lod_bias", "lod_style")
def __init__(self, name, texture_index, poly_flags, aux_material,
aux_flags, lod_bias, lod_style):
self.name = name
self.texture_index = texture_index
self.poly_flags = poly_flags
self.aux_material = aux_material
self.aux_flags = aux_flags
self.lod_bias = lod_bias
self.lod_style = lod_style
class PskMorph(object):
"""一个表情目标:名字 + 顶点位移列表 [(point_index, (dx,dy,dz)), ...]。"""
__slots__ = ("name", "offsets")
def __init__(self, name, offsets):
self.name = name
self.offsets = offsets
class Psk(object):
def __init__(self):
self.points = [] # [(x,y,z), ...]
self.wedges = [] # [(point_index, u, v, material_index), ...]
self.faces = [] # [((i0,i1,i2), material_index), ...]
self.materials = [] # [PskMaterial, ...]
self.bones = [] # [PskBone, ...]
self.weights = [] # [(weight, point_index, bone_index), ...]
self.normals = [] # [(x,y,z), ...]
self.colors = [] # [(r,g,b,a), ...]
self.extra_uvs = [] # [[(u,v), ...], ...]
self.morphs = [] # [PskMorph, ...]
self.face32 = False # 索引用的是 FACE3200(32 位)还是 FACE0000
@property
def has_normals(self):
return bool(self.normals)
@property
def has_morphs(self):
return bool(self.morphs)
# ------------------------------------------------------------------ math ---
def quat_to_matrix(q):
"""(x, y, z, w) → 3×3 旋转矩阵。
列向量约定:v' = M · v(与 bone_world / _mvec / _mmul 一致,别写成转置)。
校验:绕 Z 轴 +90° 的四元数 (0,0,0.7071,0.7071) 应把 (1,0,0) 变成 (0,1,0)。
"""
x, y, z, w = q
return ((1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)),
(2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)),
(2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)))
def _mmul(a, b):
return tuple(tuple(sum(a[i][k] * b[k][j] for k in range(3))
for j in range(3)) for i in range(3))
def _mvec(m, v):
"""列向量:M · v。"""
return tuple(sum(m[i][k] * v[k] for k in range(3)) for i in range(3))
def bone_world(psk):
"""算每根骨骼的世界(物体空间)旋转矩阵与位置。
PSK 的 rotation/location 都是**相对父骨骼**的局部值,世界值沿父链累乘。
四元数先取共轭再转成矩阵(见文件头注释第 2 点)。
返回 (world_rot, world_pos),都是按骨骼下标索引的列表。
"""
bones = psk.bones
n = len(bones)
wrot = [None] * n
wpos = [None] * n
state = [0] * n # 0 未算 / 1 计算中 / 2 已完成
def calc(i, depth=0):
if state[i] == 2 or depth > 512:
return
if state[i] == 1: # 环:当成根,别死循环
x, y, z, w = bones[i].rotation
wrot[i] = quat_to_matrix((-x, -y, -z, w))
wpos[i] = tuple(bones[i].location)
state[i] = 2
return
state[i] = 1
b = bones[i]
x, y, z, w = b.rotation
r = quat_to_matrix((-x, -y, -z, w))
p = b.parent_index
if p < 0 or p >= n or p == i:
wrot[i] = r
wpos[i] = tuple(b.location)
else:
calc(p, depth + 1)
pr, pt = wrot[p], wpos[p]
if pr is None:
wrot[i] = r
wpos[i] = tuple(b.location)
else:
wrot[i] = _mmul(pr, r)
t = _mvec(pr, b.location)
wpos[i] = (pt[0] + t[0], pt[1] + t[1], pt[2] + t[2])
state[i] = 2
for i in range(n):
calc(i)
for i in range(n):
if wrot[i] is None:
x, y, z, w = bones[i].rotation
wrot[i] = quat_to_matrix((-x, -y, -z, w))
wpos[i] = tuple(bones[i].location)
return wrot, wpos
# ----------------------------------------------------------------- reader ---
def _cstr(raw):
return raw.split(b"\x00")[0].decode("ascii", "replace")
def read_psk(path):
"""读 .psk / .pskx,返回 Psk。"""
with open(path, "rb") as fp:
data = fp.read()
psk = Psk()
off = 0
total = len(data)
morph_infos = [] # [(name, vertex_count), ...]
morph_raw = [] # [(delta, tangent_z, point_index), ...]
while off + 32 <= total:
name = data[off:off + 20].split(b"\x00")[0]
if not name or not all(32 < c < 127 for c in name):
break # 不是块头了(尾部填充 / 未知数据)
try:
_flag, dsize, dcount = struct.unpack_from("<iii", data, off + 20)
except struct.error:
break
body = off + 32
nbytes = dsize * dcount
# 注意:ACTRHEAD 这类「空块」的 data_size/data_count 都是 0,不能因此
# 判为块头不可信就中断,否则一上来就什么都读不到。
if dsize < 0 or dcount < 0 or body + nbytes > total:
break # 块头不可信,停在这里
nm = name.decode("ascii")
if nm == "PNTS0000" and dsize >= 12:
psk.points = [struct.unpack_from("<3f", data, body + i * dsize)
for i in range(dcount)]
elif nm == "VTXW0000":
if dsize >= 16:
psk.wedges = [struct.unpack_from("<IffI", data, body + i * dsize)
for i in range(dcount)]
elif dsize >= 12: # 老式 16 位 point_index
for i in range(dcount):
pi = struct.unpack_from("<H", data, body + i * dsize)[0]
u, v = struct.unpack_from("<ff", data, body + i * dsize + 4)
psk.wedges.append((pi, u, v, 0))
elif nm == "FACE0000" and dsize >= 12:
for i in range(dcount):
o = body + i * dsize
a, b, c = struct.unpack_from("<3H", data, o)
psk.faces.append(((a, b, c), data[o + 6]))
psk.face32 = False
elif nm == "FACE3200" and dsize >= 18:
for i in range(dcount):
o = body + i * dsize
a, b, c = struct.unpack_from("<3I", data, o)
psk.faces.append(((a, b, c), data[o + 12]))
psk.face32 = True
elif nm == "MATT0000" and dsize >= 88:
for i in range(dcount):
o = body + i * dsize
psk.materials.append(PskMaterial(
_cstr(data[o:o + 64]),
*struct.unpack_from("<6i", data, o + 64)))
elif nm == "REFSKELT" and dsize >= 120:
for i in range(dcount):
o = body + i * dsize
psk.bones.append(PskBone(
_cstr(data[o:o + 64]),
*struct.unpack_from("<3i", data, o + 64),
rotation=struct.unpack_from("<4f", data, o + 76),
location=struct.unpack_from("<3f", data, o + 92),
length=struct.unpack_from("<f", data, o + 104)[0],
size=struct.unpack_from("<3f", data, o + 108)))
elif nm == "RAWWEIGHTS" and dsize >= 12:
psk.weights = [struct.unpack_from("<fii", data, body + i * dsize)
for i in range(dcount)]
elif nm == "VTXNORMS" and dsize >= 12:
psk.normals = [struct.unpack_from("<3f", data, body + i * dsize)
for i in range(dcount)]
elif nm == "VERTEXCOLOR" and dsize >= 4:
psk.colors = [tuple(data[body + i * dsize: body + i * dsize + 4])
for i in range(dcount)]
elif nm == "MRPHINFO" and dsize >= 68:
for i in range(dcount):
o = body + i * dsize
morph_infos.append((_cstr(data[o:o + 64]),
struct.unpack_from("<i", data, o + 64)[0]))
elif nm == "MRPHDATA" and dsize >= 28:
for i in range(dcount):
o = body + i * dsize
morph_raw.append((struct.unpack_from("<3f", data, o),
struct.unpack_from("<3f", data, o + 12),
struct.unpack_from("<i", data, o + 24)[0]))
elif nm.startswith("EXTRAUVS") and dsize >= 8:
psk.extra_uvs.append([struct.unpack_from("<2f", data,
body + i * dsize)
for i in range(dcount)])
# 其余块(含 ACTRHEAD)直接按大小跳过
off = body + nbytes
# 16 位 point_index 的老工具会把高 16 位写成垃圾;点数还装得下 16 位时
# 统一截掉高位(与 psk_psa_py 的 read_psk 同口径)。
if psk.points and len(psk.points) <= 65536:
psk.wedges = [(w[0] & 0xFFFF, w[1], w[2], w[3]) for w in psk.wedges]
# MRPHDATA 是按 MRPHINFO 的顺序连续排布的:第 i 个表情吃前 vertex_count 条。
if morph_infos and morph_raw:
pos = 0
for name, cnt in morph_infos:
chunk = morph_raw[pos:pos + max(0, cnt)]
pos += max(0, cnt)
offs = [(pi, d) for d, _tz, pi in chunk
if abs(d[0]) + abs(d[1]) + abs(d[2]) > 1e-9]
if offs:
psk.morphs.append(PskMorph(name, offs))
if pos < len(morph_raw): # 名字数和数据条数对不上,兜底塞成一个
rest = [(pi, d) for d, _tz, pi in morph_raw[pos:]
if abs(d[0]) + abs(d[1]) + abs(d[2]) > 1e-9]
if rest:
psk.morphs.append(PskMorph("morph_rest", rest))
return psk
# ----------------------------------------------------------------- writer ---
# 写入的块顺序照抄实测样本(读的一侧对顺序不敏感,但保持一致最省事):
# ACTRHEAD ×2 → PNTS0000 → VTXW0000 → FACE0000/FACE3200 → MATT0000
# → VTXNORMS → REFSKELT → RAWWEIGHTS → VERTEXCOLOR → EXTRAUVS*
# → MRPHINFO → MRPHDATA
# 其中 VTXNORMS / VERTEXCOLOR / EXTRAUVS* / MRPH* 都属于「非标准扩展块」
# (DarklightGames 插件把带这些块的文件叫 .pskx,且只导进不导出),
# 所以 pskx=False 时会整段跳过,写出的就是 Epic 那套标准 .psk。
def _chunk(name, dsize, dcount, payload, flag=0):
head = name.encode("ascii")[:20].ljust(20, b"\x00")
return head + struct.pack("<iii", flag, dsize, dcount) + payload
def _fix_bones(psk):
"""写之前把 children_count / length 补齐。
children_count = 直接子骨数;length = 到第一个子骨的距离。
PSK 骨骼只带平移(本项目写出的都是单位四元数),所以「到子骨的局部平移
长度」就等于世界距离,不用再累乘一条链。
"""
n = len(psk.bones)
kids = [[] for _ in range(n)]
for i, b in enumerate(psk.bones):
p = b.parent_index
if 0 <= p < n and p != i:
kids[p].append(i)
for i, b in enumerate(psk.bones):
b.children_count = len(kids[i])
if kids[i]:
c = psk.bones[kids[i][0]].location
b.length = (c[0] ** 2 + c[1] ** 2 + c[2] ** 2) ** 0.5
else:
b.length = 0.0
return psk
def _pad(seq, n, fill):
"""把 seq 补/截到长度 n(缺的用 fill 填,多出来的丢掉)。"""
seq = list(seq)
if len(seq) >= n:
return seq[:n]
return seq + [fill] * (n - len(seq))
def write_psk(psk, path, pskx=True, version=None, headers=2, face32=None,
log=None):
"""把 Psk 写成 .psk / .pskx 二进制,返回字节数。
pskx : True → 连 VTXNORMS / VERTEXCOLOR / EXTRAUVS* / MRPH* 一起写
(信息最全,与实测样本一致)
False → 只写标准块(PNTS/VTXW/FACE/MATT/REFSKELT/RAWWEIGHTS),
扩展内容会被丢弃并在日志里计数
face32 : None 自动(顶点数 > 65535 就用 FACE3200),也可强制 True/False
headers : 开头的 ACTRHEAD 个数,实测样本是 2(外层那个是游戏多写的)
"""
def _l(msg, tag=None):
if log:
log(msg, tag)
n_point = len(psk.points)
n_wedge = len(psk.wedges)
# ---- 索引合法性:越界的一律夹回范围内,别写出打不开的文件
bad_w = 0
wedges = []
for pi, u, v, mi in psk.wedges:
ip = int(pi)
if not (0 <= ip < n_point) and n_point:
ip = min(max(ip, 0), n_point - 1)
bad_w += 1
wedges.append((ip, float(u), float(v), int(mi or 0)))
if bad_w:
_l("提示:%d 个楔的点索引越界,已夹回合法范围" % bad_w, "warn")
max_idx = 0
for f in psk.faces:
try:
max_idx = max(max_idx, int(f[0][0]), int(f[0][1]), int(f[0][2]))
except (TypeError, IndexError, ValueError):
pass
if face32 is None:
face32 = bool(getattr(psk, "face32", False)) or max_idx > 0xFFFF or \
n_wedge > 0xFFFF
if not face32 and (max_idx > 0xFFFF or n_wedge > 0xFFFF):
_l("提示:顶点数 %d 超过 16 位索引上限,已改用 FACE3200" % n_wedge,
"warn")
face32 = True
bad_f = 0
faces = []
for tri, mi in psk.faces:
a, b, c = int(tri[0]), int(tri[1]), int(tri[2])
if n_wedge and not (0 <= a < n_wedge and 0 <= b < n_wedge
and 0 <= c < n_wedge):
bad_f += 1
faces.append(((a, b, c), int(mi or 0)))
if bad_f:
_l("提示:%d 个面的楔索引越界(文件可能显示为破面)" % bad_f, "warn")
out = []
ver = int(version if version is not None else PSK_VERSION)
for _ in range(int(headers)):
out.append(_chunk("ACTRHEAD", 0, 0, b"", ver))
out.append(_chunk("PNTS0000", 12, n_point,
b"".join(struct.pack("<3f", *p) for p in psk.points)))
out.append(_chunk("VTXW0000", 16, n_wedge,
b"".join(struct.pack("<IffI", *w) for w in wedges)))
if face32:
out.append(_chunk("FACE3200", 18, len(faces),
b"".join(struct.pack("<3IBBi", t[0], t[1], t[2],
m, 0, 0) for t, m in faces)))
else:
out.append(_chunk("FACE0000", 12, len(faces),
b"".join(struct.pack("<3HBBi", t[0], t[1], t[2],
m, 0, 0) for t, m in faces)))
nm = len(psk.materials)
out.append(_chunk("MATT0000", 88, nm,
b"".join(struct.pack("<64s6i",
(x.name or "").encode(
"ascii", "replace")[:63]
.ljust(64, b"\x00"),
int(x.texture_index or 0),
int(x.poly_flags or 0),
int(x.aux_material or 0),
int(x.aux_flags or 0),
int(x.lod_bias or 0),
int(x.lod_style or 0))
for x in psk.materials)))
if pskx:
nrm = _pad(psk.normals, n_wedge, (0.0, 0.0, 1.0))
# 法线按「楔」存(和 EXTRAUVS / VERTEXCOLOR 一样是一楔一条)
out.append(_chunk("VTXNORMS", 12, n_wedge,
b"".join(struct.pack("<3f", *n) for n in nrm)))
_fix_bones(psk)
nb = len(psk.bones)
bb = []
for b in psk.bones:
q = _pad(tuple(b.rotation or ()), 4, 0.0)
sz = _pad(tuple(b.size or ()), 3, 1.0)
bb.append(struct.pack(
"<64s3i4f3ff3f",
(b.name or "").encode("ascii", "replace")[:63].ljust(64, b"\x00"),
int(b.flags or 0), int(b.children_count or 0),
int(b.parent_index if b.parent_index is not None else -1),
float(q[0]), float(q[1]), float(q[2]), float(q[3]),
float(b.location[0]), float(b.location[1]), float(b.location[2]),
float(b.length or 0.0),
float(sz[0]), float(sz[1]), float(sz[2])))
out.append(_chunk("REFSKELT", 120, nb, b"".join(bb)))
nw = len(psk.weights)
out.append(_chunk("RAWWEIGHTS", 12, nw,
b"".join(struct.pack("<fii", float(w), int(pi), int(bi))
for w, pi, bi in psk.weights)))
if pskx:
col = _pad(psk.colors, n_wedge, (255, 255, 255, 255))
out.append(_chunk("VERTEXCOLOR", 4, n_wedge,
b"".join(struct.pack("<4B", *c[:4]) for c in col)))
for k, uv in enumerate(psk.extra_uvs[:8]):
seq = _pad(uv, n_wedge, (0.0, 0.0))
out.append(_chunk("EXTRAUVS%d" % k, 8, n_wedge,
b"".join(struct.pack("<2f", *t[:2])
for t in seq)))
infos = []
data = []
for mo in psk.morphs:
offs = [(int(pi), tuple(d)) for pi, d in mo.offsets
if 0 <= int(pi) < n_point]
if not offs:
continue
infos.append((mo.name, len(offs)))
for pi, d in offs:
data.append((d, pi))
if infos:
out.append(_chunk(
"MRPHINFO", 68, len(infos),
b"".join(struct.pack("<64si",
(nm_ or "").encode("ascii", "replace")
[:63].ljust(64, b"\x00"), c_)
for nm_, c_ in infos)))
out.append(_chunk(
"MRPHDATA", 28, len(data),
b"".join(struct.pack("<3f3fi", d[0], d[1], d[2], 0.0, 0.0,
0.0, pi) for d, pi in data)))
blob = b"".join(out)
d = os.path.dirname(os.path.abspath(path))
if d:
os.makedirs(d, exist_ok=True)
tmp = path + ".tmp"
with open(tmp, "wb") as fp:
fp.write(blob)
os.replace(tmp, path)
_l("PSK:顶点 %d · 楔 %d · 面 %d · 骨骼 %d · 材质 %d · 权重 %d%s"
% (n_point, n_wedge, len(faces), nb, nm, nw,
(" · 表情 %d" % len(psk.morphs)) if (pskx and psk.morphs) else ""),
"info")
return len(blob)