WFS自建模角色装载系统设计文档-夜雨聆风

WFS自建模角色装载系统设计文档

WFS ENGINE / FIRM PLATFORM

玩家注册 · 人体自建模 · 角色文件系统

完整系统设计文档

System Architecture & Format Specification v1.0

文档版本	v1.0
适用系统	WFS Engine / FIRM Platform
密级	机密 · 仅限内部使用
文档日期	2025-03-19
关联规范	WFSM格式规范文档 v2.0

第一章系统概述与设计哲学

1.1核心命题

本系统的根本目标是：将玩家注册行为重新定义为”角色资产生产行为”。玩家在注册时不再只是填写表单、选择头像，而是通过参数化人体生成器，创作属于自己的、可运行的3D角色资产。该资产自生成起便与玩家账号永久绑定，成为驱动游戏中所有系统——战斗、服装、动画、赛事观战——的底层基础。

设计核心原则：

玩家注册 = 角色资产生产

角色文件 = 游戏最核心的可运行资产

文件格式 = WFSM专属格式（.wfsm / .firmchar）

服务器权威 = 所有合法角色文件由服务器签发

1.2系统定位与边界

本文档涵盖以下四个强耦合子系统的完整设计：

•玩家注册系统（Account Registration System）

•人体自建模系统（Human Character Creation System）

•专属角色文件格式（FIRMCHAR File Format，基于WFSM v2扩展）

•游戏运行时角色装载系统（Runtime Character Loading System）

四个系统共享同一角色资产数据流，缺少任意一环均无法形成完整闭环。

1.3为什么四个系统必须绑死在一起

传统游戏注册系统将角色视为“数据库记录”（用户名、头像URL、等级整数），这在角色外观固定时足够用。但一旦引入玩家自建模，角色就变成了“可运行的3D资产”——它有拓扑结构、骨架、UV、碰撞体、材质生成逻辑，这些都不能用一条数据库行来表达。

因此必须从底层将角色当作“系统级文件资产”来设计，注册系统负责生产它，文件格式负责描述它，装载系统负责运行它，三者围绕同一个核心文件格式形成闭环。

第二章整体架构分层

2.1五层架构模型

整个系统按功能职责划分为五个垂直层级，每层有明确的输入输出契约：

层级	层名	核心职责	关键模块
L1	账号层	注册、登录、UID、权限、角色槽位管理	auth_service, uid_generator
L2	角色定义层	性别模板、骨架、面部参数、体型参数、纹理参数	wfs_human_schema.js, wfs_human_templates.js
L3	模型生成层	参数→网格、骨骼绑定、UV生成、材质生成、LOD	wfs_human_generator.js, wfs_human_rig.js
L4	文件格式层	序列化、加密、签名、版本管理、防篡改	wfs_character_serializer.js, wfs_character_signer.js
L5	运行时装载层	文件验证、网格构建、动画绑定、场景集成、联机同步	runtime_character_loader.js

2.2数据流向

数据在五层之间的流向严格单向，不允许跨层直接访问：

玩家输入参数（L2）

↓wfs_human_generator执行参数化建模

生成角色数据对象（L3）

↓wfs_character_serializer序列化

编辑格式文件 .fcharproj（L4草稿）

↓服务器复核→ wfs_character_signer 签名

运行格式文件 .firmchar（L4正式）

↓runtime_character_loader解析验证

运行时角色对象 RuntimeCharacter（L5）

↓注入场景、战斗、服装、赛事等子系统

2.3服务器权威原则

所有合法角色文件必须由服务器生成或服务器签发，客户端无权自行生成最终角色文件。

方案	流程	安全级别	适用场景
方案A（推荐）	客户端发参数 → 服务端生成 .firmchar → 签名后返回客户端	最高	正式注册、角色定型
方案B	客户端生成预览文件 → 上传参数摘要 → 服务端验证后签发正式版	高	快速预览迭代

第三章玩家注册系统设计

3.1注册流程重定义

注册流程不再是”填表单+选头像”，而是六阶段角色资产生产流程：

阶段1：基础账号创建

玩家填写账号信息，系统创建临时UID（未激活状态），此UID在角色定型前不进入正式账号表。

字段	类型	说明
username	string	3-20位，唯一，全局索引
password	string	Bcrypt哈希，服务端处理
email / phone	string	用于验证码验证
captcha_token	string	验证码令牌
temp_uid	UUID v4	临时UID，角色完成后升级为正式UID

阶段2：进入角色创建器

验证码通过后，自动跳转进入人物建模器界面（character_creator.html），此界面是注册主流程的一部分，而非可跳过的附加步骤。玩家必须完成角色创建才能激活账号。

阶段3：参数化角色定义

玩家通过滑块、选项、颜色选择器完成角色参数设置，实时预览生成结果：

参数分组	参数项	范围/类型
基础体型	性别模板	male / female / neutral
基础体型	身高比例	0.0–1.0（对应虚拟150–195cm）
基础体型	头身比	0.0–1.0
基础体型	肩宽、腿长、臂长、胸腰臀	各0.0–1.0
面部	脸型、眼型、鼻型、嘴型、耳型	预设ID + 微调float
面部	五官位置微调	±0.15偏移量
外观	发型ID、发色RGBA	预设库选择
外观	肤色tone、妆面ID	调色盘 + 预设库

阶段4：实时预览与确认

•正视 / 侧视 / 背视三视图旋转

•基础表情测试（基于Blendshape）

•待机动画 / 跑步动画 / 攻击动画预览

•确认后参数锁定，进入生成阶段

阶段5：服务器生成角色文件

客户端提交参数JSON至 /api/character/create，服务端执行模型生成流水线，生成并签名 .firmchar 文件，返回文件地址与校验信息。

阶段6：账号激活与数据库写入

数据库表	字段	说明
users	uid, username, password_hash, register_time	核心账号信息
player_character	id, uid, active_character_file, character_version, body_profile, file_hash, sign_token, created_at	角色资产索引
character_presets	preset_id, base_template, allowed_ranges, default_materials	合法参数范围定义

第四章人体自建模系统设计

4.1设计路线：参数化生成（非自由拓扑）

本系统采用参数化可控人体生成路线，而非开放式拓扑编辑（如Blender风格）。原因如下：

路线	优点	缺点	是否采用
参数化生成	可控、可验证、易保存、易联机同步、易做动画适配	创作自由度较低	✓ 采用
自由拓扑编辑	创作自由度极高	难约束、难验证、难保证骨架统一、开发成本极高	✗ 不采用

三阶段开放策略：第一阶段（上线版）仅参数化；第二阶段开放局部微调（下颌/鼻梁/眼角/嘴唇）；第三阶段开放控制点/样条轮廓高级模式。

4.2参数约束规则

所有参数必须在预设范围内，超出范围的请求服务端直接拒绝：

约束规则：

• 身高：虚拟150–195cm区间，对应参数0.0–1.0

• 腿长比例：0.20–0.60

• 肩宽比例：0.25–0.55

• 头部尺寸：0.30–0.55（相对身高）

• 骨骼数量、层级、命名：不允许修改，全局统一

• 碰撞体：由服务端根据体型参数计算，不跟随模型自由变化

• 面数上限：身体网格≤15,000三角面；面部网格≤8,000三角面

• 纹理分辨率：最大2048×2048，移动端降至1024×1024

4.3人体生成器核心模块

模块文件	职责	关键输入	关键输出
wfs_human_schema.js	参数定义与范围校验	玩家原始参数JSON	合法参数对象
wfs_human_templates.js	基础体型模板库	性别/体型枚举	基础拓扑模板、骨架映射
wfs_human_generator.js	网格生成	合法参数对象 + 模板	身体网格、面部网格、UV、蒙皮权重
wfs_human_rig.js	骨架绑定	网格数据	标准人形骨架、自动蒙皮结果、IK点
wfs_character_serializer.js	文件序列化/反序列化	角色完整数据对象	.fcharproj / .firmchar 二进制文件
wfs_character_signer.js	安全签名	序列化文件 + 私钥	含SecurityFooter的已签名文件

4.4骨架规范（统一人形骨架）

所有角色必须使用以下标准骨架，确保动画系统、战斗系统、IK系统的统一性：

骨骼组	骨骼列表	说明
脊柱	Root, Hips, Spine, Spine1, Chest, Neck, Head	主链，不可修改
左臂	LeftShoulder, LeftUpperArm, LeftForeArm, LeftHand	标准人形，对称右臂
右臂	RightShoulder, RightUpperArm, RightForeArm, RightHand
左腿	LeftUpLeg, LeftLeg, LeftFoot, LeftToeBase	标准人形，对称右腿
右腿	RightUpLeg, RightLeg, RightFoot, RightToeBase
辅助骨骼	WeaponAttach_R, WeaponAttach_L, BackAttach	武器/装备挂点
面部骨骼	Jaw, EyeLeft, EyeRight, + 表情Blendshape控制器	可选，表情系统用

第五章专属角色文件格式（.firmchar）

5.1格式定位

.firmchar 是基于 WFSM v2 规范扩展的角色专属格式，继承WFSM的分块式结构、安全机制和版本兼容策略，在此基础上增加角色专用数据块（身份区、体型参数区、物理碰撞区等）。

格式	全称	用途	是否含签名
.fcharproj	Character Project	编辑器内部工程格式，含完整编辑历史、未压缩数据、草稿状态	否（开发态）
.firmchar	FIRM Character	运行时正式格式，烘焙网格、精简参数、资源引用、压缩加密	是（服务端签发）

5.2文件整体布局

┌─────────────────────────────────────────────────────┐

│HEADER固定64字节，魔数FCHR，永不压缩│

├─────────────────────────────────────────────────────┤

│IDENTITY身份区：UID绑定、角色ID、创建时间│

│PARAMS体型参数区：所有捏人参数（可重建用）│

│SKELETON骨架区：标准人形骨架+逆绑定矩阵│

│GEOMETRY网格区：身体/面部/可替换部件│

│TOPOLOGY拓扑区（编辑版）：半边数据结构│

│MATERIALS材质区：PBR参数+程序化生成逻辑│

│RESOURCES资源引用区：发型/纹理/服装预设引用│

│PHYSICS物理区：碰撞胶囊/命中盒/挂载点│

│EXTENSIONS扩展区（可选）│

├─────────────────────────────────────────────────────┤

│CHUNK TABLE块索引表│

├─────────────────────────────────────────────────────┤

│SECURITY FOOTER96字节：SHA-256+Ed25519签名+权限位│

└─────────────────────────────────────────────────────┘

5.3HEADER 字段定义

字段名	类型	值/说明
magic	char[4]	固定值 ‘FCHR’（0x46 0x43 0x48 0x52），不匹配立即拒绝
version_major	uint16_le	当前值 1，主版本不同拒绝加载
version_minor	uint16_le	当前值 0，次版本变更向后兼容
endian	uint8	0=little-endian（推荐），1=big-endian
compression	uint8	0=不压缩，1=zstd（推荐），2=lz4
encryption_flag	uint8	0=未加密，1=AES-256-GCM分块加密
file_type	uint8	0=.firmchar运行格式，1=.fcharproj编辑格式
generator	char[32]	生成工具标识，如 ‘WFS CharGen v1.0’
chunk_count	uint32_le	文件块总数
chunk_table_offset	uint64_le	块索引表字节偏移，O(1)跳转基础

5.4IDENTITY 身份区

字段名	类型	说明
uid	UUID v4	绑定玩家账号UID，服务端校验绑定关系
character_id	UUID v4	角色唯一ID，全局不重复，永久不变
creator_account	string	创建账号标识，用于来源追踪
create_time	ISO 8601	角色创建时间，UTC，由服务端填充
last_modified	ISO 8601	最后修改时间，换装/改造时更新
template_base	string	基础体型模板ID，如’human_male_v1′
body_type	enum	male / female / neutral
character_version	uint32	角色文件版本号，每次合法修改自增

5.5PARAMS 体型参数区

参数区保存玩家所有捏人参数，这是角色文件最重要的可重建基础——服务端可随时根据参数重新生成网格，无需保存全量顶点数据。

参数分组	字段名	类型	范围
身体比例	height, leg_ratio, arm_ratio, shoulder_width	float32	各0.0–1.0
身体比例	chest, waist, hip, neck_length	float32	各0.0–1.0
面部	face_width, jaw_width, eye_size, eye_spacing	float32	各0.0–1.0
面部	nose_height, lip_thickness, ear_scale	float32	各0.0–1.0
外观	skin_tone[4]	float32[4]	RGBA各0.0–1.0
外观	hair_style_id, eyebrow_id	uint32	预设库索引
外观	hair_color[4]	float32[4]	RGBA各0.0–1.0
外观	makeup_preset_id	uint32	妆面预设库索引

5.6PHYSICS 物理与碰撞区

碰撞区数据由服务端根据体型参数计算，不允许客户端自行修改，确保战斗系统判定公平：

字段名	类型	说明
body_capsule	Capsule{center,radius,height}	整体胶囊体，用于移动碰撞检测
head_hitbox	AABB{min,max}	头部命中区域
chest_hitbox	AABB{min,max}	胸部命中区域
abdomen_hitbox	AABB{min,max}	腹部命中区域
limb_hitboxes[4]	Capsule[4]	四肢命中胶囊，顺序：左臂/右臂/左腿/右腿
cloth_anchor_points	vec3[]	布料物理锚点，用于服装模拟
mount_points	MountPoint[]	装备挂载点：武器/背包/头盔等

5.7RESOURCES 资源引用区

不将所有资产塞入单一文件，改用引用ID指向主资源库，减少文件体积，便于资产热更新：

字段名	类型	说明
hair_mesh_id	UUID	引用发型网格资源库
face_decal_id	UUID	引用面部贴花资源库
eye_texture_id	UUID	引用眼睛纹理资源库
body_material_preset_id	UUID	引用身体材质预设库
starter_clothes_id	UUID	初始服装配置引用
lod_mesh_ids[3]	UUID[3]	LOD0/LOD1/LOD2的精简网格引用

5.8SECURITY FOOTER 安全尾部（继承WFSM v2）

字段名	类型	说明
contentHash	bytes[32]	SHA-256，覆盖Header至Footer之前的全部内容
signature	bytes[64]	Ed25519签名，由服务端私钥签发
permissions	uint8	bit0=查看 bit1=编辑 bit2=导出 bit3=分发 bit7=管理员
expireAt	uint64_le	到期Unix时间戳，0=永久有效
originId	UUID	签发系统实例ID，用于来源追踪
uid_binding	UUID	冗余存储UID绑定，双重校验

第六章游戏运行时角色装载系统

6.1装载流程

客户端登录成功后，执行以下装载流程，严格按阶段顺序执行，任一阶段失败均不得进入下一阶段：

1.登录成功：从服务端获取 uid、角色文件CDN地址、签名摘要、版本号

2.文件下载：从CDN下载 .firmchar 文件，本地缓存（版本号不变时跳过下载）

3.文件头验证：检查magic=’FCHR’、版本兼容性、endian/compression标志

4.安全校验：计算SHA-256与contentHash对比、验证Ed25519签名、检查uid_binding与登录UID是否一致、检查expireAt

5.权限检查：根据permissions字段确认当前操作权限（查看/编辑/导出）

6.块索引加载：通过chunk_table_offset建立O(1)块访问映射

7.按优先级解析：IDENTITY → PARAMS → SKELETON → GEOMETRY → MATERIALS → PHYSICS → RESOURCES

8.构建运行时对象：生成RuntimeCharacter（包含skeleton、mesh、materials、collider、animBinding）

9.注入场景系统：根据当前游戏状态（主城/战斗/观战）选择对应加载策略

6.2RuntimeCharacter 运行时对象结构

属性	类型	说明
uid	UUID	绑定账号UID
characterId	UUID	角色唯一ID
skeleton	Skeleton	已绑定的标准人形骨架实例
bodyMesh	SkinnedMesh	身体蒙皮网格
faceMesh	SkinnedMesh	面部细分网格
materials	Material[]	材质数组，已初始化PBR参数
collider	CapsuleCollider	主碰撞体
hitboxes	HitboxSet	命中盒集合，战斗判定用
mountPoints	MountPoint[]	装备挂载点列表
animController	AnimationController	动画控制器，已绑定标准动画集
lodLevel	int	当前LOD级别（0=最高，2=最低）

6.3不同场景的加载策略

游戏场景	加载策略	LOD级别	碰撞体	动画集
主城/大厅	完整加载，含高精度面部	LOD0	仅移动碰撞	完整动画集
战斗场景	完整加载，启用命中盒	LOD0-1	移动+命中盒	战斗动画集
赛事观战	精简加载，统一材质预算	LOD1-2	不启用	观战动画集
个人主页展示	高精度静态展示	LOD0	不启用	待机动画
排行榜/缩略图	超轻量加载，仅外轮廓	LOD2	不启用	无

6.4安全校验失败处理

错误码	错误类型	处理策略
FCHR_ERR_INVALID_MAGIC	魔数不匹配	拒绝加载，提示文件损坏，引导重新下载
FCHR_ERR_VERSION_MISMATCH	主版本不兼容	拒绝加载，提示需要更新客户端
FCHR_ERR_HASH_MISMATCH	哈希不一致（可能被篡改）	拒绝加载，上报安全事件，封号审查
FCHR_ERR_INVALID_SIGNATURE	签名验证失败	拒绝加载，上报安全事件，封号审查
FCHR_ERR_UID_MISMATCH	UID绑定不符	拒绝加载，禁止使用他人角色文件
FCHR_ERR_EXPIRED	授权已过期	拒绝加载，联系客服重新授权
FCHR_ERR_PERMISSION_DENIED	权限不足	拒绝对应操作，降级为只读模式

第七章后端接口设计

7.1角色相关API

接口	方法	请求体	响应
/api/character/create	POST	uid + 参数JSON + 临时会话Token	firmchar文件URL + hash + version
/api/character/preview	POST	uid + 参数JSON（草稿）	低精度预览glb URL（临时，5分钟有效）
/api/character/finalize	POST	uid + 参数JSON + 确认标志	正式 .firmchar URL + 签名摘要
/api/character/load	GET	uid（Header认证）	firmchar URL + hash + version + sign
/api/character/update	PATCH	uid + 局部修改参数 + 操作类型	新版本 firmchar URL + 新version号
/api/character/validate	POST	firmchar文件二进制	校验结果JSON（合法/违规/详细报告）

7.2数据库表结构

users 表

字段	类型	说明
uid	UUID PRIMARY KEY	全局唯一账号标识
username	VARCHAR(30) UNIQUE	用户名，全局唯一索引
password_hash	CHAR(60)	Bcrypt哈希
register_time	TIMESTAMP	注册时间，UTC
status	ENUM	active / suspended / pending

player_character 表

字段	类型	说明
id	UUID PRIMARY KEY	角色记录ID
uid	UUID FK→users	关联账号UID
active_character_file	TEXT	CDN路径或对象存储路径
character_version	INT	版本号，每次合法修改自增
body_profile	JSONB	体型参数快照（用于快速索引）
skeleton_profile	VARCHAR(64)	骨架模板标识
file_hash	CHAR(64)	SHA-256十六进制，双重校验
sign_token	CHAR(128)	Ed25519签名十六进制
created_at	TIMESTAMP	角色创建时间
updated_at	TIMESTAMP	最后修改时间

7.3文件存储方案

数据类型	存储位置	说明
.firmchar 正式运行文件	对象存储（S3兼容）	路径: /characters/{uid}/{char_id}/v{version}.firmchar
.fcharproj 编辑工程文件	对象存储（私有桶）	路径: /editor/{uid}/{char_id}/draft.fcharproj
预览图/缩略图	CDN公共桶	路径: /avatars/{uid}/thumb.jpg
数据库	PostgreSQL	仅存路径索引和校验信息，不存二进制大文件

第八章与其他游戏子系统的衔接

8.1服装系统

.firmchar 文件是服装系统的基础依赖。服装挂载时必须读取以下角色信息：

•body_profile 体型参数：用于动态适配服装网格，避免穿模

•skeleton：确定骨骼挂点位置，驱动布料物理模拟

•mount_points：明确服装挂载锚点（腰带/领口/袖口等）

•body_capsule：计算服装外轮廓碰撞体

8.2动画系统

动画系统要求所有角色使用统一骨架，.firmchar 的 SKELETON 块保证：

•标准人形骨架（Human Format Compatible）

•表情骨骼 / Blendshape 控制器统一命名

•Root骨位置固定，IK点标准化

•动作重定向（Animation Retargeting）可在任意角色间复用

8.3战斗判定系统

战斗系统从 .firmchar 的 PHYSICS 块读取命中盒数据：

•所有命中盒由服务端根据体型参数计算，客户端只读，不可篡改

•命中区分组：头/胸/腹/四肢，各组独立伤害系数

•近战格挡面、技能发动点均从 mount_points 获取

8.4赛事观战系统

需求	解决方案
快速装载（转播机性能约束）	LOD2模式，仅加载GEOMETRY/SKELETON/MATERIALS基础块
模型合法性保证	装载前强制执行完整安全校验（hash+signature）
统一渲染质量	忽略 PARAMS 中的高精度面部参数，使用赛事预设材质
联机同步	传输 character_id + version 而非完整文件，由各端本地缓存加载

第九章核心模块开发规范

9.1模块清单与开发顺序

优先级	模块文件	开发阶段	依赖
P0	wfs_human_schema.js	第一阶段	无
P0	wfs_human_templates.js	第一阶段	schema
P0	wfs_human_generator.js	第一阶段	schema, templates
P0	wfs_human_rig.js	第一阶段	generator
P0	wfs_character_serializer.js	第一阶段	generator, rig
P0	wfs_character_signer.js	第一阶段	serializer
P1	character_creator.html/.js	第一阶段（前端）	schema, generator
P1	/api/character/create	第一阶段（后端）	generator, serializer, signer
P1	runtime_character_loader.js	第一阶段（运行时）	serializer, signer
P2	wfs_cloth_adapter.js	第二阶段	serializer, physics
P2	/api/character/update	第二阶段	serializer, signer

9.2安全编码要求

•所有参数在服务端进行二次校验，不信任客户端提交值

•私钥仅存在于服务端密钥管理服务（KMS），不落地于应用服务器磁盘

•角色文件传输全程使用HTTPS，CDN启用签名URL（限时访问）

•敏感参数（如UID绑定）在SecurityFooter中双重存储，任一不一致均拒绝

•所有校验失败事件写入安全审计日志，异常模式触发自动封号审查

9.3性能要求

指标	目标值	说明
参数化模型生成时间（服务端）	≤ 3秒	含网格生成+骨骼绑定+序列化
文件签名时间	≤ 50ms	Ed25519签名极快
客户端文件装载时间（LOD0）	≤ 800ms	含下载（CDN）+校验+网格构建
客户端文件装载时间（LOD2）	≤ 200ms	观战模式轻量装载
.firmchar 文件大小	≤ 2MB（压缩后）	zstd压缩，资源引用模式
最大面数（LOD0）	≤ 23,000三角面	身体15k+面部8k

第十章版本兼容与未来扩展

10.1版本兼容策略

继承WFSM v2的语义化版本策略：主版本变更代表破坏性更改（旧解析器拒绝），次版本变更向后兼容（旧解析器跳过未知块）。

变更类型	版本策略	示例
新增可选数据块	次版本+1	新增EXT_ANIM动画块
修改现有块末尾新增字段	次版本+1	PARAMS新增face_asym参数
修改HEADER结构	主版本+1	重构块索引表格式
修改签名算法	主版本+1	从Ed25519迁移至更新算法
核心块格式重构	主版本+1	GEOMETRY改用不同坐标系

10.2预规划扩展模块（基于WFSM EXT机制）

Chunk ID	模块名称	用途
EXT_SKEL	骨骼绑定扩展	高级骨骼动画、次级骨骼（头发/布料）物理
EXT_ANIM	动画片段扩展	角色专属动作序列（特技/感情动作/胜利姿势）
EXT_PHYS	物理碰撞扩展	凸包精确碰撞体、高精度格挡面定义
EXT_TAIL	服装裁缝结构	腰围半径/裙长/褶皱频率，服装参数化构建基础
EXT_DMGE	战斗损伤扩展	可损伤区域、损伤贴图集、破损状态过渡
EXT_FACE	高级面部扩展	更多Blendshape、口型同步数据、情绪状态机

第十一章角色创建器使用说明（玩家视角）

本章面向游戏玩家，说明注册时角色创建器的使用方式、可操作范围以及常见问题。角色创建器是注册流程的内嵌环节，玩家无需下载任何额外软件，直接在游戏客户端或注册页面内完成操作。

11.1进入方式：无需额外安装

重要说明：角色创建器完全内嵌于游戏客户端 / 网页注册流程中。

玩家不需要安装任何第三方建模软件（如Blender、3ds Max等）。

不需要了解三维建模知识。

不需要处理任何模型文件，所有文件由系统自动生成和管理。

整个创建过程只需操作滑块、按钮和颜色选择器即可完成。

玩家在完成基础账号信息填写（用户名/密码/邮箱）并通过验证码后，系统自动跳转至角色创建界面。此界面是注册流程的必经环节，不可跳过。

11.2创建器界面布局

区域	位置	功能说明
3D预览窗口	界面中央大区域	实时显示角色外观，支持拖动旋转（左键）、捏合缩放，可切换正视/侧视/背视
体型调节面板	左侧竖排	滑块组：身高、头身比、肩宽、腿长、臂长、胸腰臀六项比例参数
面部调节面板	右侧竖排	滑块组：脸型、眼睛、鼻子、嘴型、耳朵；下方为位置微调滑块
外观选择面板	底部横排	发型预设库、发色选择器、肤色调色盘、妆面预设库
动作预览按钮	预览窗口下方	切换：待机 / 走路 / 跑步 / 攻击，验证动画适配效果
重置与随机按钮	面板右上角	重置：恢复默认参数；随机：系统随机生成一套参数组合
确认完成按钮	界面右下角	提交参数至服务器生成正式角色文件，完成注册

11.3各参数含义与操作说明

体型参数

参数名	滑块范围说明	效果	注意事项
身高	左端矮（约150cm），右端高（约195cm）	影响整体高度比例	不影响碰撞体，游戏内碰撞体按区间统一计算
头身比	左端大头（Q版），右端小头（写实）	调整头与身体的相对尺寸	极端值视觉突出，建议居中附近
肩宽	左端窄肩，右端宽肩	影响上半身宽度视觉感	不影响服装挂点，服装系统自适应
腿长	左端短腿，右端长腿	调整腿部占全身高度比例	与身高联动，总比例保持平衡
胸腰臀	三条独立滑块，各自0.0–1.0	调整身体曲线比例	仅影响外观网格，不影响战斗碰撞体

面部参数

参数名	操作方式	效果说明
脸型	从6种基础脸型中选择，再用滑块微调宽窄	影响下颌线和脸部整体轮廓
眼睛	从预设眼型库选择（含12种基础型），滑块调整大小和间距	面部辨识度最高的特征
鼻子	从预设库选择，滑块调整高度和宽度	调整鼻梁高低和鼻翼宽度
嘴型	从预设库选择，滑块调整嘴唇厚薄和嘴角弧度
耳朵	滑块调整大小，默认跟随脸型自动适配	调整空间较小，不影响整体辨识度
五官位置微调	每个五官有水平/垂直偏移滑块，范围±15%	精细调整五官在脸上的相对位置

外观参数

参数名	操作方式	说明
发型	从预设发型库选择（滚动图标列表），初始提供30+种基础发型	注册后可通过游戏内换装系统随时更换
发色	RGBA调色盘 + 预设色票（含渐变发色选项）	支持自定义颜色，不限于预设
肤色	调色盘选择底色 + 明暗滑块	影响全身皮肤材质的基础色调
妆面	从预设妆面库选择（含无妆选项）	叠加于肤色之上，注册后可随时更换

11.4玩家可以改与不能改的边界

为保证游戏内所有角色的战斗公平性和系统稳定性，部分参数由系统固定，玩家无法修改：

类型	玩家可以自由调整	系统固定（玩家不可修改）
骨骼结构	——	骨骼数量、层级、命名、关键关节位置完全固定，所有角色共享同一标准骨架
碰撞体	——	碰撞胶囊和命中盒由服务端根据体型参数统一计算，显示模型与碰撞体独立
网格/贴图规格	——	面数上限（23,000三角面）和纹理分辨率（最大2048）由系统控制
身材极限	在允许范围内自由拖动	身高范围、头部尺寸、各比例参数均有上下限，防止极端体型
外观装扮	发型/发色/肤色/妆面完全自由	——
五官外形	预设库选择 + 滑块微调	不支持任意拓扑变形，无法像专业建模软件一样随意拉点改形

11.5注册完成后还能改外观吗

修改类型	是否支持	操作入口	限制说明
发型更换	支持	游戏内「外观」→「发型」	随时可换，不影响其他数据
发色修改	支持	游戏内「外观」→「发色」
妆面更换	支持	游戏内「外观」→「妆面」
服装更换	支持	游戏内「衣橱」系统	由服装系统管理，独立于角色基础文件
五官/体型修改	有限支持	游戏内「角色重塑」（需消耗道具）	可再次进入创建器调整，有冷却时间或道具消耗
骨架/碰撞体	不支持	——	系统级固定参数，不开放修改

11.6常见问题

Q：我需要会3D建模才能用吗？

不需要。本系统刻意回避了所有专业建模操作，所有调整均通过滑块和预设库完成，只要能拖动鼠标滑块即可创建角色。

Q：角色文件存在哪里？我能导出吗？

角色文件（.firmchar格式）由系统自动生成并存储于服务端，绑定玩家账号UID。玩家不需要也无法直接接触原始角色文件。游戏客户端在需要时自动从服务端获取并加载，整个过程对玩家透明无感。

Q：能用朋友的角色文件吗？

不能。每个角色文件通过Ed25519签名与特定玩家UID绑定，客户端加载时校验UID匹配，绑定不符的文件将被系统拒绝并上报安全日志。

Q：捏人结果不满意怎么办？

注册阶段：可以点击「随机」重新生成参数组合，或手动调整任意滑块，在点击「确认完成」前均可无限次修改。注册完成后：通过游戏内「角色重塑」功能可再次进入创建器，修改幅度较大时需消耗道具或等待冷却。

Q：为什么战斗中碰撞体和角色外形不完全一样？

这是有意为之的设计。游戏内碰撞体（决定能否被击中的判定区域）并非完全跟随角色外形，而是由系统根据体型参数统一计算的标准化胶囊体。目的是保证所有玩家的战斗命中判定公平一致，防止通过极端体型制造不公平优势。

第十二章系统部署与集成说明（开发者视角）

本章面向游戏开发团队，说明系统的部署方式、客户端集成要求、服务端环境配置，以及接入各子系统时的注意事项。

12.1系统架构部署概览

部署层	组成	部署位置	对外接口
客户端层	character_creator.html/.js、runtime_character_loader.js	游戏客户端安装包（随客户端发布）	无，直接调用后端API
应用服务层	character API服务、模型生成服务、签名服务	云服务器 / 容器集群	REST API（/api/character/*）
存储层	对象存储（.firmchar）、CDN（分发）、PostgreSQL（索引）、KMS（密钥）	托管云服务	内部调用，不对外暴露

12.2玩家端：完全无感知，无需任何安装

核心设计原则：对玩家完全透明。

角色创建器随游戏客户端一起安装，玩家不需要单独安装任何建模工具。

网格生成、骨骼绑定、文件签名等建模运算全部在服务端执行，玩家设备只负责UI交互和3D预览渲染。

生成后的 .firmchar 文件自动上传至对象存储，客户端按需从CDN拉取，无需玩家手动管理文件。

玩家从注册到进入游戏的整个流程中，不会接触到任何原始模型文件或格式名称。

12.3服务端环境要求

组件	最低配置	推荐配置	说明
模型生成服务	4核CPU / 8GB内存	8核CPU / 16GB内存	单次生成≤3秒，开服高峰需水平扩容
签名服务（KMS）	独立部署，2核/4GB	硬件安全模块（HSM）	私钥不落地应用服务器，通过KMS API调用
对象存储	S3兼容接口	阿里云OSS / AWS S3	存储 .firmchar 文件，按UID分桶管理
CDN	覆盖目标玩家地区	多节点加速	角色文件走CDN，目标首次加载 ≤ 800ms
数据库	PostgreSQL 14+	PostgreSQL 15+ 读写分离	存角色索引和校验信息，不存二进制大文件
应用服务	Node.js 18+ 或 Python 3.10+	容器化部署（Docker/K8s）	生成逻辑两种语言均可实现

12.4客户端集成要求

集成项	方式	说明
character_creator.js	打包进客户端安装包	注册时捏人UI，调用 /api/character/preview 实时预览，/api/character/finalize 提交
runtime_character_loader.js	打包进客户端安装包	游戏运行时角色装载，处理文件下载→校验→网格构建全流程
WFSM/FCHR解析器	随客户端内置	解析 .firmchar 分块结构，支持FCHR魔数和版本校验
Ed25519公钥	硬编码进客户端	验证服务端签发的角色文件签名，私钥仅在KMS中，公钥对外公开
本地缓存目录	操作系统写权限	缓存已下载的 .firmchar，版本号未变时跳过重新下载
3D渲染环境	支持WebGL2 或原生图形API	角色创建器预览和游戏内角色渲染均依赖图形环境

12.5开发环境搭建步骤

10.克隆仓库，安装依赖：npm install（前端）/ pip install -r requirements.txt（后端服务）

11.生成开发用密钥对：运行 scripts/gen_keypair.sh，私钥存入本地KMS模拟器，公钥写入 client/keys/public.pem

12.启动本地对象存储模拟：使用 MinIO 或 LocalStack 模拟S3接口，配置 .env 中的 STORAGE_ENDPOINT

13.启动数据库：docker-compose up postgres，运行 scripts/migrate.sql 初始化表结构

14.启动模型生成服务：node services/character_generator/index.js –port 3001

15.启动主API服务：node services/api/index.js –port 3000

16.访问 http://localhost:3000/register，验证注册+建模完整流程

17.运行测试套件：npm test / pytest，确认 wfs_character_serializer 和 wfs_character_signer 单元测试全部通过

12.6生产部署注意事项

密钥管理

•Ed25519私钥必须存入生产KMS（阿里云KMS / AWS KMS / HashiCorp Vault），严禁以文件形式落地于应用服务器

•公钥随客户端发布，版本升级时注意新老客户端的公钥兼容问题

•私钥轮换时，旧私钥签发的文件需在过渡期内保持有效（通过 expireAt 字段控制），新私钥同步至KMS后平滑切换

模型生成服务扩容

•正常运营期：单实例可支撑约每分钟200次角色生成（3秒/次 × 多线程）

•开服/活动高峰期：建议预先扩容至3–5个生成服务实例，通过负载均衡分发请求

•相同参数组合可缓存生成结果（参数hash → 网格缓存），对活动期间参数撞车情况有显著优化效果

CDN配置

•角色文件CDN URL必须使用签名URL（限时访问），防止未授权的直接文件获取

•缓存策略：按版本号设置不可变缓存（Cache-Control: immutable），角色更新时URL中版本号自增自动绕过缓存

监控与告警

•监控角色生成成功率（目标 ≥ 99.5%），失败率异常时告警

•监控安全事件日志（hash不匹配、签名失败、UID绑定违规），密集异常时触发自动封号审查

•监控对象存储容量：单玩家文件 ≤ 2MB，预估总量 = 活跃玩家数 × 2MB

12.7与游戏引擎的集成方式

引擎	集成方式	关键接入点
Unity	将 runtime_character_loader 编译为C# Native Plugin，或通过WebRequest下载+自定义解析	CharacterLoader.LoadFromFile(path) → RuntimeCharacter对象
Unreal Engine	通过C++ Plugin封装FCHR解析逻辑，或使用蓝图接口调用	UCharacterLoadSubsystem::LoadCharacter(UID) → USkeletalMeshComponent
Godot	GDExtension封装解析器，通过HTTP模块下载后自定义解析	CharacterLoader.load_character(uid) → CharacterNode3D
自研引擎	直接集成 runtime_character_loader.js（Web平台）或对应Native实现	参照第六章装载流程对接

附录A错误码参考

错误码	数值	含义	处理建议
FCHR_OK	0	成功	继续执行
FCHR_ERR_INVALID_MAGIC	1	魔数不匹配	拒绝，提示文件损坏
FCHR_ERR_VERSION_MISMATCH	2	主版本不兼容	拒绝，提示更新客户端
FCHR_ERR_HASH_MISMATCH	3	SHA-256不一致	拒绝，上报安全事件
FCHR_ERR_INVALID_SIGNATURE	4	Ed25519签名失败	拒绝，上报安全事件
FCHR_ERR_UID_MISMATCH	5	UID绑定不符	拒绝，禁止使用他人文件
FCHR_ERR_EXPIRED	6	授权过期	拒绝，联系客服重授权
FCHR_ERR_PERMISSION_DENIED	7	权限不足	降级或拒绝操作
FCHR_ERR_DECRYPT_FAILED	8	解密失败	拒绝，检查密钥
FCHR_ERR_CORRUPT_CHUNK	9	块数据损坏	拒绝，重新下载
FCHR_ERR_PARAM_OUT_OF_RANGE	10	参数超出合法范围	拒绝，返回具体违规参数
FCHR_ERR_SKELETON_INVALID	11	骨架不符合标准	拒绝，安全审查

附录B术语表

术语	定义
FIRMCHAR	本系统专属角色文件格式，基于WFSM v2扩展，扩展名 .firmchar
WFSM	WFS Model，WFS Engine专属3D模型格式，v2版本详见《WFSM格式规范文档v2》
参数化生成	将人体外观定义为一组数值参数（身高/比例/五官），由算法生成对应网格
服务器权威	所有合法角色文件由服务端生成并签名，客户端不具备自行生成最终文件的权力
SecurityFooter	文件末尾96字节安全尾部，含SHA-256哈希、Ed25519签名、权限位
Ed25519	基于椭圆曲线的数字签名算法，签名64字节，速度快，用于文件来源认证
半边结构(HalfEdge DS)	网格拓扑数据结构，支持O(1)邻域查询，是编辑器编辑态的基础
LOD	Level of Detail，多级细节，根据距离选择不同精度网格，优化渲染性能
RuntimeCharacter	角色文件解析后在游戏引擎中的运行时对象实例
角色槽位	账号下可持有的角色数量上限，不同账号等级对应不同槽位数

附录C文档修订记录

版本	日期	修订人	变更说明
v1.0	2025-03-19	WFS Team	初版，基于WFSM v2规范完整设计注册/建模/格式/运行时四系统

本文档为 WFS Engine / FIRM Platform 内部技术规范·机密等级：内部使用

WFS自建模角色装载系统设计文档

wang

猜你喜欢