Bible Strong Avatar Lab 用户指南：用 3D 风格几何原语搭建你的角色身体

Bible Strong Avatar Lab 是一款基于浏览器的程序化头像创作工作室。本指南面向新手，教你用 3D 风格几何原语快速搭建角色身体：从选择主形状、放置次要形状，到调整位置与旋转，最终导出可嵌入网页的 React / JavaScript 头像。

为什么是"3D 风格几何原语"？

你可能以为做 3D 角色需要建模软件。其实 Bible Strong Avatar Lab 的思路是：用一组参数化的 3D 风格几何原语（球体、立方体、胶囊体等）拼出身体，再投影成 2D SVG 渲染。

• 每个形状只有 6 个基础参数：width/height/depth/roundness/position/rotation，新手也能秒懂；
• 透视、投影全部由引擎自动计算（源码见 geometry.ts），你不需要理解数学；
• 成品是一份.avatar.json定义，React 和无框架 JavaScript 共用同一份文件，视觉表现完全一致（参见 README.md 的 Export formats 章节）。

6 种基础形状清单

身体由两种角色构成：主形状（primary）承载眼睛、定义面部坐标系；次要形状（nodes）围绕主形状自由摆放，用来"堆叠"出耳朵、身体、装饰等部件。

可选的 6 种原语定义在 body.ts：

每种形状内置了一套默认尺寸预设，切换类型时自动套用（预设值见 surfaces.ts）。

打开 Studio：三步搭建你的第一个身体

1️⃣ 启动工作室

项目完全运行在浏览器里，无需账号和后端。本地运行（仓库为只读，clone 后执行）：

git clone https://gitcode.com/gh_mirrors/bib/bible-strong-avatar-lab cd bible-strong-avatar-lab pnpm install pnpm dev

打开 http://localhost:5173 即可进入。选择（或新建）一个头像后，左侧是实时画布，右侧是检查器。

2️⃣ 在"身体构建"面板选主形状

进入头像编辑器，找到右侧的身体构建（Construction du corps）面板——面板说明为"选择主形状，然后在其周围组合基础形状"，组件源码见 BodyConstructionAccordion.tsx。

展开最顶部的主形状条目（带"主要"徽标，标注"承载眼睛"），即可在 6 张形状卡片间点选切换，并调整：

• 缩放：等比调整（120–300 u，u 为内部单位）；
• 宽度 / 高度 / 深度：单独拉伸每个维度；
• 圆度类参数：仅对 cube / diamond / cylinder / cone 出现（边缘圆度、整体圆度、尖端圆度、底部圆度）。

3️⃣ 添加并摆放次要形状

点击面板底部的"+ 添加形状"，选择一种原语即可加入场景。新形状默认以约 1/3 的预设尺寸出现在主形状一侧，方便直接上手摆放。点击列表中的任意形状可选中它，此时可操作：

• 形状设置：缩放、宽度/高度/深度、圆度；
• 局部位置：X / Y / Z 三个数值；
• 局部旋转：X / Y / Z 三个角度（单位 °）；
• 复制 / 删除：快速堆叠对称部件（复制件会自动向右下偏移 14 u）。

每个次要形状拥有独立的局部尺寸、位置和旋转（见 CONTEXT.md 的 Invariants），互不影响。

局部操纵 Gizmo：拖一拖就懂了 🎯

选中次要形状后，画布上会出现一个局部控制器（Gizmo local）：三条轴代表 x/y/z 移动方向，三个圆环代表绕各轴旋转。

• 拖一个轴→ 沿该轴平移形状；
• 拖一个环→ 绕该轴旋转形状。

这比手输数字直观得多，底层由 geometry.ts 中的translateBodyNodeAlongLocalAxis与rotateBodyNodeAroundLocalAxis实现。偏好精确控制时，直接修改面板里的"局部位置 / 局部旋转"数值即可，两种方式等效。

💡 小提示：也可以不旋转头部，直接在画布面上拖动头像来整体调整朝向——透视和遮挡关系会自动算好。

常用参数速查表

默认文档里就有一个现成案例：蓝色球体头像 "Strobi"，以及用两个球体加圆柱堆出来的方块角色 "Freddy"，结构可直接参考 defaultStudioDocument.json。

搭完身体之后：表情、动画与导出 ⚡

身体只是角色的一半。得益于"主形状承载面部坐标系"的设计，表情与身体解耦——表情基于公共 facial frame 定义，所以换一种身体形状，已有表情依然兼容（见 CONTEXT.md）。

接下来按 Studio 的四个区域走即可（流程说明见 README.md）：

1. 姿势（Pose）：旋转头部、调整中性眼睛；
2. 表情（Expressions）：保存命名的视觉预设，如 sleepy、curious；
3. 动画（Animations）：把表情排上时间轴，设置时长、过渡与眨眼；
4. 导出（Export）：
   • 下载.avatar.json，配合@bible-strong/avatar-react或@bible-strong/avatar-web集成；
   • Photo Mode：把当前画面导出为 SVG / PNG，支持透明、纯色与渐变背景；
   • Studio project：整个项目打包成 JSON 备份，可跨浏览器导入。

常见问题

Q：最多能加多少个形状？A：主形状之外最多 16 个次要形状（MAX_BODY_NODES = 16，定义于 body.ts），达到上限后"添加形状"按钮会自动禁用。

Q：换了主形状类型，眼睛会错位吗？A：不会。眼睛绘制在公共面部坐标系上，会重新投影到新的表面，行为保持一致。

Q：我的作品存在哪里？A：整个 Studio 文档自动保存在浏览器 localStorage，没有远程后端。清空浏览器数据前，建议用Export → Studio project导出 JSON 备份。

从 6 种几何原语出发，你已经在 Bible Strong Avatar Lab 里搭出了第一个有身体、有表情、可导出的程序化角色。打开工作室，试着用两个胶囊加一个圆锥做只小企鹅吧 🐧