RezeのBlog
← 返回文章列表

从模型文件到右下角

2026.11.16技术7128 字视频 2 · 参考 13

本站右下角那个会动的角色,没上任何构建工具,就是一堆静态文件加一段原生脚本。桌面宽屏才加载,窄屏和触屏连脚本都不请求。真要做的事是四件:资源放哪、引擎按什么顺序装、画布那一大圈透明边怎么裁、鼠标事件和声音怎么接进去。

下面按依赖顺序写。先放文件,再装引擎,然后裁盒子、写参数、接事件。代码里的常量和函数名都来自线上版本,只删掉了与本站文稿、音乐播放器耦合的部分。

资源目录与授权边界

角色资源全部自托管,放在仓库的 assets/live2d 目录下。三个脚本各有分工:PixiJS 负责渲染与时钟,live2dcubismcore 是官方网页运行时,cubism4 这一层把运行时模型包装成 Pixi 的显示对象。模型目录里只有一份网格、一张贴图、一份描述文件和一份物理配置。

assets/live2d/
├── pixi.min.js
├── live2dcubismcore.min.js
├── cubism4.min.js
├── ump45-icon.webp
└── ump45-v1/
    ├── ump45_child_fuku_ver1.model3.json
    ├── ump45_child_fuku_ver1.moc3
    ├── texture_00.webp
    └── ump45_child_fuku_ver1.physics3.json
assets/audio/ump45/*.mp3

目录先定下来。描述文件列出网格、贴图和物理配置的路径,physics3 管头发、围巾与挂绳的摆动。这只模型没有动作文件,表情和角度由脚本每帧写进参数。引擎与模型合计约一点四兆,三十一段语音约九百六十千字节。

外链也能加载,仓库体积更小。自托管换来的是确定的加载时序和确定的缓存策略;外链多一个域名,就多一次连接和一处失效点。官方运行时可以下载,再分发要按它的许可走,换角色之前先把授权查清楚,这件事排在写代码前面。

入口处挡一道设备判断。宽度不足一千零二十四像素,或者指针不精确,函数直接返回,脚本不注入,模型不请求。

if (mq("(max-width: 1024px)").matches ||
    mq("(hover: none), (pointer: coarse)").matches) return;

这个视频两分钟,讲的是博客场景里文件怎么摆、脚本按什么顺序引,可以和本节对照。展示的目录比本站简单,胜在把依赖关系摆在明面上。

按依赖顺序装载引擎

顺序不能换。三个脚本有先后依赖,后一个要用前一个挂到全局的对象,只能排队插入。async 设为 false,插入顺序就是执行顺序。装载函数把延迟对象存下来,切视图再调用时直接复用,避免重复往页面里塞同一批脚本。

function loadScript(src) {
  return new Promise(function (res, rej) {
    var s = document.createElement("script");
    s.src = src;
    s.async = false;
    s.onload = res;
    s.onerror = function () { rej(new Error("加载失败: " + src)); };
    document.head.appendChild(s);
  });
}
function ensureEngine() {
  if (enginePromise) return enginePromise;
  enginePromise = loadScript(BASE + "pixi.min.js")
    .then(function () { return loadScript(BASE + "live2dcubismcore.min.js"); })
    .then(function () { return loadScript(BASE + "cubism4.min.js"); })
    .then(function () {
      window.PIXI.live2d.Live2DModel.registerTicker(window.PIXI.Ticker);
    });
  return enginePromise;
}

最后那行注册不能省。运行时自己没有时钟,注册之后 Pixi 的时钟才会按帧驱动模型。引擎出错时页面其余部分照常工作,角色容器保持空,控制台留一条失败地址,排查时不必检查正文渲染路径。

画布与参数索引

画布用页面里现成的绘图标签,透明底,抗锯齿开,像素比最多取二。模型从描述文件读入,自动交互关掉。适配层自带的交互和用户写的参数会抢同几个通道,眼睛出现一帧睁一帧闭;关掉之后,所有参数只由本站的帧函数写。

app = new window.PIXI.Application({
  view: canvas, backgroundAlpha: 0, autoStart: true, antialias: true,
  resolution: Math.min(window.devicePixelRatio || 1, 2), autoDensity: true,
  width: 200, height: Math.round(FULL_H * zoom)
});
return window.PIXI.live2d.Live2DModel.from(MODEL, { autoInteract: false });

参数索引只取一次。模型载入时把要用到的编号收进一张表,之后按序号写值;每帧用字符串查索引会多出几千次哈希查找,开销直接计入每帧耗时。头发、围巾、挂绳的参数不收进这张表,交给物理配置自己摆。

var FACE_DEFAULTS = {
  PARAM_EYE_L_SMILE: 0, PARAM_EYE_R_SMILE: 0, PARAM_MOUTH_FORM: 0,
  PARAM_MOUTH_OPEN_Y: 0, PARAM_CHEEK: 0,
  PARAM_BROW_L_Y: 0, PARAM_BROW_R_Y: 0
};
function setP(id, v) {
  if (P[id] !== undefined) core.setParameterValueByIndex(P[id], v);
}
function buildP(coreModel) {
  Object.keys(FACE_DEFAULTS)
    .concat(["PARAM_ANGLE_X", "PARAM_ANGLE_Y", "PARAM_ANGLE_Z",
             "PARAM_EYE_BALL_X", "PARAM_EYE_BALL_Y", "PARAM_BREATH"])
    .forEach(function (id) {
      var i = coreModel.getParameterIndex(id);
      if (i >= 0) P[id] = i;
    });
}

透明边与固定包围盒

模型的画布比人大一圈,靴子还画到下沿之外。量包围盒时要把画布临时放大到一点六倍,用像素读取把下沿之外的部分一起读进来。不透明区域横向从一百六十五点三到一千五百九十四点六,纵向从一千零五十点七到四千一百六十五点四。

盒子只量一次。早先那版在每台设备上读像素、量盒子、写进本地存储,读不到像素的浏览器、留着旧值的缓存、纵坐标量成零的情况都出现过,结果分别是头顶留出大片空白和靴底被裁掉一层。现在把量好的数写成常量,不再量,也不再读缓存;历次用过的缓存键在启动时清掉。模型载入后九百毫秒再铺一次,兜住首帧尺寸未就绪的情形。

var BODY_BOX = { x: 165.3, y: 1050.7, w: 1429.3, h: 3114.7 };
var FULL_H = 476, HALF_K = .67, pad = 8;
function fit() {
  var cap = Math.max(300, Math.round(window.innerHeight * .62));
  var fullH = Math.round(Math.min(FULL_H * zoom, cap));
  var k = (fullH - pad) / BODY_BOX.h;
  app.renderer.resize(Math.round(BODY_BOX.w * k), fullH);
  model.anchor.set(0, 0);
  model.scale.set(k);
  model.position.set(-BODY_BOX.x * k, -BODY_BOX.y * k + pad / 2);
  stage.style.height = (view === "full" ? fullH
    : Math.round(fullH * HALF_K)) + "px";
}

八像素留给靴底。包围盒下沿正好贴着画布末行,按满高铺上去描边会被裁掉一层;高度扣八像素,模型下移四像素,靴底才完整。半身只改容器高度,画布和模型保持原样,切回全身不重新加载。渐变遮罩试过,裙边会发灰,改成容器直接裁切。

这个视频走官方原生接口,能把模型文件、画布和参数三者的关系看清楚。本站多包了一层适配层,底下的东西相同。

每帧写入的参数

每帧只做四件事。把常驻参数写回默认值,写呼吸与视线,处理眨眼计时,再叠加表情和动作。常驻参数不归零,上一轮的表情会留在脸上;表情叠加在默认值之上,包络按剩余时长算,淡入二十二帧、淡出四十五帧,动作结束前不会突然跳回原样。

function tick() {
  var delta = Math.min(app.ticker.deltaMS / 16.67, 3);
  var dt = delta / 60;
  t += dt;
  mx += (tx - mx) * .07 * delta;
  my += (ty - my) * .07 * delta;
  Object.keys(FACE_DEFAULTS).forEach(function (k) {
    setP(k, FACE_DEFAULTS[k]);
  });
  setP("PARAM_BREATH", (Math.sin(t * 1.5) + 1) * .5);
  setP("PARAM_ANGLE_X", mx * 20);
  setP("PARAM_ANGLE_Y", my * 12);
  setP("PARAM_EYE_BALL_X", mx * .8);
  if (blinkT < 0 && t > nextBlink) blinkT = 0;
  if (blinkT >= 0) {
    var ev = blinkT < .08 ? 1 - blinkT / .08
           : blinkT < .16 ? (blinkT - .08) / .08 : 1;
    setP("PARAM_EYE_L_OPEN", ev);
    setP("PARAM_EYE_R_OPEN", ev);
    if (blinkT > .16) {
      blinkT = -1;
      nextBlink = t + 2.4 + Math.random() * 3.2;
    }
    blinkT += dt;
  }
}

鼠标坐标先做插值再乘系数,转头带一点延迟。眨眼间隔两点四到五点六秒,闭眼零点一六秒,偶尔连眨两下。表情按剩余时长算包络淡入淡出;摇头和点头是衰减振荡,直接写进角度参数。页面切到后台或角色关掉时停掉时钟,再打开续上。

事件层与宿主页面

事件层单独铺。容器固定在右下角,自身不接鼠标事件;接事件的是叠在画布上的透明层,以及气泡、轮盘和圆钮。这样角色周围的透明区域仍把点击交给正文。三个圆钮平时透明,鼠标进入角色外扩八十像素的范围才浮出。

#g-reze-mascot {
  position: fixed; right: 34px; bottom: 26px;
  z-index: 8800; pointer-events: none; user-select: none;
}
.g-reze-hit { position: absolute; inset: 0; pointer-events: auto; }
.g-reze-tools { position: absolute; top: 1px; right: 2px; gap: 4px;
  opacity: 0; pointer-events: none; }
#g-reze-mascot.is-near:not(.is-ring) .g-reze-tools {
  opacity: 1; pointer-events: auto;
}

轮盘分两层。主盘六格:动作、说话、问答、用法、更多、收起。更多盘八格:推荐一篇、全身、半身、音量、静音、放大、缩小、回顶。右键在角色身上开轮盘,按住 Shift 放行浏览器原生菜单。位置、缩放、身形、音量、静音各存一个键,刷新后读回来。

拖动结束会连带派发一次点击,代码里用一次延时把那次点击吃掉,免得挪完角色就触发一次说话。问答面板不随正文点击关闭,只有关闭键、退出键和开轮盘会收起。

语音支路

声音走另一条线。原声压成六十四码率单声道,三十一段放在语音目录,正文配了二十七句。点一下随机抽一句,抽到同一句重抽;表情先播,音频后播,同一个播放器里上一段先停。台词不出字幕,字幕会盖住模型下半张脸,也和原声重复。

function playVoice(name) {
  if (!voiceOn || !name) return;
  if (player) player.pause();
  player = new Audio(VOICE_BASE + name + ".mp3");
  player.volume = vol;
  player.play();
}

音量默认零点五五,和静音开关一起存进本地。浏览器要求音频由用户手势触发,点击角色和点轮盘都满足这个条件;页面自动发声不被允许,也不该尝试。

问答支路

问答走函数。打字问发到站内函数,函数读数据库里的文章,按汉字二元组打分。标题命中权重三,标签二,正文乘零点五。问句里的高频二元组先停掉,否则「问六个是哪六个」会撞上「四十六个字」这类句子。

for (const g of qGrams) {
  const w = gramWeight(g, idx.df);
  if (d.tg.has(g)) s += 3 * w;
  if (d.kg.has(g)) s += 2 * w;
  if (d.bg.has(g)) s += .5 * w;
}

取前四篇,各截一千六百字拼进提示词,要求每句末尾标编号,名字和数字照抄,资料里未收录就回答未收录。主用模型失败再试备用,两处都失败只把检索到的篇目送回。前端把编号换成文章链接,接口超时和断线分开提示。同一地址每分钟十二次,超了等一分钟。固定问题写在前端,不进模型。

开销、验收与留痕

资源开销算得出来:全量约二点四兆,引擎和模型一点四兆,语音九百六十千字节。窄屏设备不请求这些文件。渲染循环跟着页面走,标签页隐藏后由浏览器降频;切后台停时钟能省下这一段。静态目录设一年不可变,改过脚本不换版本号,浏览器照旧读旧的,页面上看不出任何变化。

验收看两张截图。整身那张检查靴底两行像素,半身那张检查裙摆下沿是否露出袜口。用法卡底部留一行页面版本号,截图里能直接确认是不是旧缓存。每次改完脚本升号、提交、双推,再回根页查一次版本字符串。本机跑无头浏览器要关掉代理,本地地址否则会变成错误页;静态服务得作为常驻任务起,作为一次性命令的前台进程会随命令退出终止。本机调试记录只写版本号与截图路径。

参考