技术控制台｜《江格尔》十二英雄——基于手写 WebGL 管线的史诗数字展陈交互系统

处理结果

原始资产 → 产出资产的全量对比。所有数值由 assetctl 直接解析 GLB 容器得出。

原始资产合计

930.22MiB

12 尊，单尊 73–88 MB

精细版合计

53.74MiB

压缩至原始 5.8%

精细版 gzip 传输

36.01MiB

再降 67.0%

轻量版单尊均值

619KiB

首屏即可旋转

三角面保留

7.0%

产出 2,532,157 / 原始 35,994,240

每顶点字节

13B

位置 6 + 法线 3 + UV 4

外部运行时依赖

无 Three.js / 无 Draco / 无 CDN

平均 ACMR

1.159

32 槽顶点缓存（u16 预检 1.365）

预算断言

全部通过

含 manifest 与实际资产一致性

软件架构

四层分离：构建期管线只读解析容器、产出双级资产与清单；运行时引擎只负责解压与绘制；应用层承载展馆、图谱与 AI 叙述；数据层用单一数据源保证双端一致。层与层之间以文件契约（manifest / 数据集 JSON）耦合，因此管线可脱离本项目复用。

PREVIEW

轻量版

首屏即可旋转的版本。移动端/弱网/2G 模式默认只加载这一级，用户可手动请求精细版。

资产数：12
传输上限：750 KiB/个，实测均 gzip 542 KiB
索引类型：u16

DETAIL

精细版

完整精度版本。轻量版就绪后后台流式替换，替换过程保持用户当前角度/缩放/自动旋转状态。

资产数：12
传输上限：6 MiB/个，实测均 gzip 3073 KiB
原始体积上限：10 MiB/个，实测均 4586 KiB
索引类型：u32

CONTRACT

级间契约

管线不直接调用渲染代码，只产出文件：双级 GLB + manifest.json。渲染引擎不关心资产怎么来的，只读清单。

替换资产来源：改 assetctl.config.json
替换渲染目标：实现同一清单读取契约
契约变更可被预算断言与校验脚本拦截

资产清单

24 个产出资产。几何与贴图字节数分开统计——这个拆分决定了优化该往哪使劲：本批资产几何占比 80.6%，因此减面与顶点紧凑化是主要收益来源，而不是一味压贴图。

资产	原始	gzip	几何	贴图	顶点	三角面	索引	字节/顶点	量化
alatancheji轻量版	738 KiB	647 KiB	525 KiB	211 KiB	27,726	29,543	u16	13	是
guzangongbu轻量版	659 KiB	580 KiB	484 KiB	173 KiB	25,263	27,937	u16	13	是
harijilagen轻量版	561 KiB	494 KiB	421 KiB	138 KiB	21,880	24,509	u16	13	是
harinidun轻量版	639 KiB	554 KiB	492 KiB	145 KiB	26,397	26,828	u16	13	是
hejilagen轻量版	635 KiB	559 KiB	497 KiB	137 KiB	24,764	31,111	u16	13	是
hongguer轻量版	761 KiB	662 KiB	606 KiB	154 KiB	31,443	35,248	u16	13	是
jiangger轻量版	580 KiB	519 KiB	383 KiB	195 KiB	19,714	22,617	u16	13	是
mingyan轻量版	579 KiB	511 KiB	414 KiB	163 KiB	21,420	24,224	u16	13	是
naqinshanghuer轻量版	571 KiB	504 KiB	387 KiB	183 KiB	20,271	22,129	u16	13	是
saber轻量版	633 KiB	546 KiB	517 KiB	114 KiB	27,280	29,123	u16	13	是
sailihantabage轻量版	516 KiB	450 KiB	415 KiB	100 KiB	21,141	24,958	u16	13	是
sanala轻量版	557 KiB	485 KiB	429 KiB	127 KiB	22,663	24,051	u16	13	是
alatancheji精细版	5020 KiB	3409 KiB	3982 KiB	1036 KiB	135,248	193,270	u32	13	是
guzangongbu精细版	4564 KiB	3071 KiB	3708 KiB	854 KiB	123,440	182,718	u32	13	是
harijilagen精细版	3936 KiB	2615 KiB	3259 KiB	675 KiB	107,787	161,366	u32	13	是
harinidun精细版	4378 KiB	2918 KiB	3668 KiB	708 KiB	125,537	177,026	u32	13	是
hejilagen精细版	4655 KiB	3012 KiB	3980 KiB	673 KiB	126,827	202,248	u32	13	是
hongguer精细版	5348 KiB	3502 KiB	4541 KiB	806 KiB	149,678	225,313	u32	13	是
jiangger精细版	7000 KiB	4943 KiB	4996 KiB	2002 KiB	160,256	252,732	u32	13	是
mingyan精细版	4069 KiB	2758 KiB	3240 KiB	827 KiB	108,307	159,137	u32	13	是
naqinshanghuer精细版	3920 KiB	2701 KiB	3014 KiB	905 KiB	102,226	146,452	u32	13	是
saber精细版	4437 KiB	2877 KiB	3863 KiB	573 KiB	129,978	188,805	u32	13	是
sailihantabage精细版	3771 KiB	2436 KiB	3277 KiB	492 KiB	107,032	163,706	u32	13	是
sanala精细版	3934 KiB	2629 KiB	3244 KiB	689 KiB	110,469	157,106	u32	13	是

合计 24 个资产：原始 61.00 MiB → gzip 42.36 MiB （压缩 30.5%）；几何 49.16 MiB / 贴图 11.80 MiB；GPU 贴图常驻（含 mipmap）290.00 MiB。

顶点缓存效率（ACMR）

ACMR（Average Cache Miss Ratio）是 GPU 后变换缓存命中率的行业指标，1.0 为理想值。本项检查用于回答一个具体工程问题：轻量版能退回 16 位索引吗？ 16 位索引可再省一半索引字节，但顶点复用率不足时反而拖慢绘制。实测 u16 预检值整体升高至 1.365，因此轻量版保留 u16（体积优先，因该级受 750 KiB 硬约束），精细版保留 u32（绘制效率优先）。

级别	模型	顶点	三角面	索引复用比	ACMR32	ACMR16
preview	alatancheji	27,726	29,543	3.2	1.206	1.367
preview	guzangongbu	25,263	27,937	3.32	1.173	1.354
preview	harijilagen	21,880	24,509	3.36	1.156	1.33
preview	harinidun	26,397	26,828	3.05	1.256	1.434
preview	hejilagen	24,764	31,111	3.77	1.079	1.232
preview	hongguer	31,443	35,248	3.36	1.183	1.386
preview	jiangger	19,714	22,617	3.44	1.133	1.29
preview	mingyan	21,420	24,224	3.39	1.148	1.308
preview	naqinshanghuer	20,271	22,129	3.27	1.174	1.343
preview	saber	27,280	29,123	3.2	1.201	1.368
preview	sailihantabage	21,141	24,958	3.54	1.101	1.268
preview	sanala	22,663	24,051	3.18	1.193	1.354
detail	alatancheji	135,248	193,270	4.29	1.171	1.408
detail	guzangongbu	123,440	182,718	4.44	1.162	1.404
detail	harijilagen	107,787	161,366	4.49	1.13	1.381
detail	harinidun	125,537	177,026	4.23	1.22	1.493
detail	hejilagen	126,827	202,248	4.78	1.073	1.302
detail	hongguer	149,678	225,313	4.52	1.168	1.43
detail	jiangger	160,256	252,732	4.73	1.149	1.383
detail	mingyan	108,307	159,137	4.41	1.136	1.365
detail	naqinshanghuer	102,226	146,452	4.3	1.184	1.425
detail	saber	129,978	188,805	4.36	1.153	1.393
detail	sailihantabage	107,032	163,706	4.59	1.119	1.364
detail	sanala	110,469	157,106	4.27	1.149	1.386

平均 ACMR32 1.159 / ACMR16 1.365。以 FIFO 顶点缓存简化模型估算，仅用于同一批资产内部横向比较，不代表真实驱动绝对值。

命令行接口

一条命令复现本页全部数字。管线是独立的命令行工具，不依赖本项目其余代码。

# 全量：解析资产 → 校验预算 → 顶点缓存分析 → 写出 JSON/Markdown 报告
  node scripts/assetctl.mjs all

  # 单独跑某一项
  node scripts/assetctl.mjs verify      # 仅校验预算与完整性（CI 门禁用，失败退出码 1）
  node scripts/assetctl.mjs report      # 仅生成逐资产量化报告
  node scripts/assetctl.mjs cache       # 仅做顶点缓存效率分析

  # 限定级别 / 指定输出目录
  node scripts/assetctl.mjs report --tier=preview --out=reports/preview

  # 产物
  #   reports/asset-report.json   机器可读，供 CI 与页面消费
  #   reports/asset-report.md     人可读，可直接附入参赛材料
  #   public/console.html          本页（由 gen-console.mjs 读报告生成）

DESIGN CHOICE

为什么自己解析 GLB 而不用现成库

不是重复造轮子，是约束条件决定的。

微信小程序主包上限 1.5 MB，不允许下载外部解码器
图形管线自研；网页动效使用本地 Anime.js，无 CDN 依赖
自研换来的是：完全可控的加载策略、体积预算与失败降级路径

DESIGN CHOICE

为什么不用 Draco 而用量化

Draco 压缩率更高，但需要附带第三方解码器代码（体积与许可双重成本）。

改用 glTF 官方扩展 KHR_mesh_quantization
顶点属性紧凑存储：位置 6 B / 法线 3 B / UV 4 B，合计 13 B/顶点
解压由自研运行时完成，零第三方代码

REUSABILITY

换一批资产怎么用

管线与"江格尔"这一具体内容解耦，只依赖配置文件。

改 assetctl.config.json 的 tiers 与预算
指向新的资产目录，重新运行 assetctl all
预算断言与报告自动适配新资产

运行时约束与预算断言

作品运行环境的硬约束在这里逐条列出，并由 assetctl verify 在构建期断言。约束不是描述，是门禁：违反即构建失败。

RUNTIME

零外部依赖

外部库：无
Draco 解码器：不需要
Three.js：不使用
CDN 依赖：无

BUDGETS

体积预算（两个指标，不能混用）

传输体积（gzip）决定用户实际下载量与缓存占用：轻量 ≤ 750 KiB/个、精细 ≤ 6 MiB/个、精细合计 ≤ 80 MiB
原始体积（GLB）只受部署平台单文件上限约束：精细 ≤ 10 MiB/个、平台硬限 25 MiB
小程序主包 ≤ 1.5 MB
拿 gzip 当磁盘体积会低估，拿原始体积当传输体积会高估

PERFORMANCE

性能预算

首次可交互 ≤ 2000 ms
精细版就绪 ≤ 8000 ms
测试条件：5 Mbps 下行 / 100 ms 延迟 / 冷缓存
离屏或静止时减少渲染，降低移动端耗电

构建期断言结果

✓全部预算断言通过 — 单文件体积、总量、索引类型、量化扩展四项逐资产检查