Bible Strong Avatar Lab 是一款运行在浏览器中的免费程序化头像创作工坊，无需账号、无需后端、无需绘图基础。用它你可以搭建身体、绘制表情、编排可复用的动画，最后导出 SVG / PNG 图片或可直接接入 React 与 JavaScript 项目的.avatar.json定义文件。本指南面向新手，带你从零开始掌握这款浏览器头像创作工具的完整工作流。

为什么选择 Bible Strong Avatar Lab？

一句话：在浏览器里"捏"出会动的程序化头像。它把 3D 风格的几何体与 SVG 矢量渲染结合在一起：

• 🎨程序化造型：用圆面 + 基础几何体搭建身体，调整尺寸、圆角、位置、旋转、透视和配色，全程无需绘图软件；
• 😄表情 + 动画：保存命名表情预设，把多个表情编排成带过渡效果的动画，还能配置自动眨眼；
• 📦轻量可移植：头像、表情、动画打包成单个.avatar.json，React 与纯 JavaScript 用同一份定义，行为完全一致；
• 🔒隐私友好：所有作品自动保存在浏览器本地存储中，项目以 JSON 导出/导入，随时可以在不同设备间迁移。

本地启动：3 步跑起头像创作工作室

想深度折腾，可以把仓库跑在本地。环境要求：

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

启动后打开http://localhost:5173即可进入工作室。仓库还提供了一组常用命令，见 README.md：

创作流程：四大工作区详解

工作区采用"左侧实时画布 + 右侧检查器"布局。选中一个头像后，按以下四个区域逐步推进：

1. Pose 工作区：搭建身体与中性外观

头像（Avatar）拥有自己的身体几何、颜色与中性眼睛外观。你可以调整尺寸、圆角度、位置、局部旋转、透视、颜色，还能开启线框参考辅助对齐。主面部表面承载面部坐标系和眼睛，其他几何体可独立定位与旋转——身体构造的相关逻辑见 body.ts，几何模型定义在 geometry.ts。

2. Expressions 工作区：给头像"存表情"

表情（Expression）是保存下来的视觉预设。关键点在于：表情的眼睛数值相对于头像的中性外观，因此同一个表情换到不同身体表面上依然兼容。每个表情还可以临时附加身体与眼睛的颜色覆盖。表情编辑界面实现在 ExpressionWorkspace.tsx。

3. Animations 工作区：编排会动的头像

动画（Animation）把同一行为库中的多个表情按时间线排好，每一步都能自定义停留时长与过渡风格（弹性 spring、平滑 smooth、干脆 snappy），播放模式支持loop 循环、once 播放一次、pingPong 往返，还能配置自动眨眼。这些类型定义清晰可见于 sequences.ts 与 sequences.ts。

4. 行为库的"写时复制"机制

所有头像默认共享一套内置的基础行为库。当你第一次修改某个头像的表情或动画时，Studio 会把整组表情和动画复制到该头像私有的行为库中，此后的改动只影响这个头像，不会波及其他角色。复制头像也会连同它的自定义行为一起复制。这套"写时复制"（copy-on-write）模型让多个头像共享默认值的同时保持彼此独立，背后的架构决策记录在 0022-model-avatar-studio-as-a-versioned-document.md，术语统一（统一称为 Animation）则见 0023-name-avatar-sequences-animations.md。

导出成果：4 种格式总有一款适合你

接入 React 项目只需三步：

1. 安装@bible-strong/avatar-react，导入导出的 JSON 并传给createAvatar；
2. 组件挂载后自动播放defaultAnimation（如idle）；
3. 用控制器的play('happy')等方法切换动画或表情。

纯 JavaScript（ESM）项目则安装@bible-strong/avatar-web，同样只依赖一份 JSON 定义。React 与 JavaScript 使用的是同一份定义文件，视觉行为不会分叉。完整 API 参考分别见 packages/avatar-react/README.md 与 packages/avatar-web/README.md，可运行的消费示例放在 examples/react-vite-consumer/ 和 examples/web-vite-consumer/ 两个目录中。

隐私与备份：数据完全归你所有

整个应用没有远程后端：完整 Studio 文档和界面语言偏好都存放在浏览器本地存储（localStorage），自动保存，编辑器内的未保存修改仍可撤销。因此强烈建议：在清除浏览器数据或迁移设备前，先通过Export → Studio project导出一份 JSON 备份。项目文档目前是预发布 schema，导入项目文件会在确认后替换当前本地文档，解析逻辑见 studioDocument.ts。

技术底座：程序化引擎如何做到"跨框架"

• React 19负责编辑器 UI 与持久化状态；Vite 8负责开发与构建；
• SVG渲染程序化几何，Motion负责逐帧高频渲染值，避免触发 React 重渲染；
• TypeScript 严格模式 + Tailwind CSS 4构成工程与界面基础。

几何、播放与文档操作全部写在不依赖任何框架的 TypeScript 模块中（见 packages/avatar-core/），通过 scripts/generate-standalone-engine.mjs 生成可独立分发的引擎，这就是导出的头像包"不依赖 Studio UI"的原因。术语、不变量与架构边界完整记录在 CONTEXT.md，界面支持英文、法语与简体中文（src/i18n/zh.ts）。

常见问题（FAQ）

• 需要付费或注册账号吗？不需要。项目基于 GNU AGPL v3.0 开源许可（LICENSE），创作与导出全程在本地完成。
• 作品存在哪里？浏览器本地存储，自动保存；记得用 Studio 项目 JSON 导出做备份。
• 导出的头像能用在其他网站吗？可以。一份.avatar.json同时服务 React 与纯 JavaScript 渲染器，直接安装对应 npm 包即可。
• 没有图形基础能做吗？可以。一切都是参数化调节——圆角、比例、颜色——不需要任何手绘能力。

下一步：深入资料与参与

• 项目总览：README.md
• 架构决策（ADR）：docs/adr/
• 领域词汇与不变量：CONTEXT.md
• 文档与发布流程：docs/PUBLISHING.md

打开浏览器，挑一个头像，从 Pose 开始捏起——你的第一个会眨眼的程序化头像，也许只需要 10 分钟。