[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-95097":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":38,"readmeContent":39,"aiSummary":40,"trendingCount":15,"starSnapshotCount":15,"syncStatus":41,"lastSyncTime":42,"discoverSource":43},95097,"emotion-ball","sam70361\u002Femotion-ball","sam70361","Emotion Ball 是一套面向 AI 助手的表情引擎:32 种状态表情全部由纯 SVG 与原生 JavaScript 实时驱动,零框架、零图片资源。AI 侧只需输出一个 emotionId,小球即可切换到对应表情,可直接用作聊天机器人、桌面宠物、悬浮助手的情绪表达层。","https:\u002F\u002Femotion-balls.vercel.app\u002F",null,"JavaScript",242,26,149,0,12,77,101,91.99,"Other",false,"main",true,[25,26,27,28,29,30,31,32,33,34,35,36,37],"ai","ai-agent","animation","bot","chatbot","desktop-pet","emotion","grok","grok-bot","javascript","svg","svg-animation","vanilla-javascript","2026-08-24 04:01:23","\u003Cdiv align=\"center\">\n\n# Emotion Ball 表情馆\n\n**为 AI 助手打造的表情引擎 —— 32 种状态表情 · 3 种身体形态 · 纯 SVG + 原生 JavaScript · 零依赖**\n\n[![在线预览](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdemo-emotion--balls.vercel.app-8A63F4?logo=vercel&logoColor=white)](https:\u002F\u002Femotion-balls.vercel.app\u002F)\n[![许可](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-learning--only-orange)](LICENSE)\n[![零依赖](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdependencies-zero-brightgreen)](#)\n[![技术栈](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fmade%20with-vanilla%20JS%20%2B%20SVG-F7DF1E?logo=javascript&logoColor=black)](#)\n\n**中文** | [English](README.en.md)\n\n[在线预览](https:\u002F\u002Femotion-balls.vercel.app\u002F) · [特性](#特性) · [快速开始](#快速开始) · [集成指南](#集成指南) · [自定义与扩展](#自定义与扩展) · [许可](#许可)\n\n\u003C\u002Fdiv>\n\n---\n\n> **授权声明**:仓库内 [emotion-ball\u002F](emotion-ball\u002F) 目录的球形角色**视觉形象**(blob \u002F wedge \u002F gem 身体造型、配色与特效视觉)仅供个人技术学习与研究,**禁止任何商业用途**且永不提供商业授权;表情引擎源代码与表情配置数据(眼形 \u002F 嘴形参数、动画原语、关键帧序列)为独立编写,**双许可**——非商业免费,商业用途可获取授权。详见 [LICENSE](LICENSE)、[LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md) 与 [NOTICE.md](NOTICE.md)。\n>\n> [mood-mates\u002F](mood-mates\u002F) 目录为同源引擎的**原创角色子项目**(云宝 Nimbo \u002F 亮亮 Twinkle),独立原创设计,采用**双许可**(个人学习免费 + 可获取商业授权),不受上述限制约束。\n\n本仓库由「一座总馆 + 两个子项目」组成:\n\n- **总馆(根目录 `index.html`)**:云宝 × 亮亮 × 球球 三个角色**同台切换展示**——同一面 32 表情陈列墙,点击顶部角色卡即可整馆换角,由两套引擎(MoodMates + EmotionBall)共同驱动;\n- **[mood-mates\u002F](mood-mates\u002F)**:原创角色项目(云宝 \u002F 亮亮),多角色架构、双许可、可商用,自带独立展示站与集成文档;\n- **[emotion-ball\u002F](emotion-ball\u002F)**:球形角色项目(形象仅供学习,引擎与表情数据可商业授权),32 种状态表情、3 种身体形态,自带独立展示站。\n\nEmotion Ball 是一套面向 AI 助手的表情引擎:32 种状态表情全部由纯 SVG 与原生 JavaScript 实时驱动,零框架、零图片资源。AI 侧只需输出一个 `emotionId`,即可切换到对应表情,可直接用作聊天机器人、桌面宠物、悬浮助手的情绪表达层。\n\n它也不只是\"一颗球\":内置圆胖(blob)、三角(wedge)、菱形(gem)三种身体形态,支持主题色多实例与线稿模式;整套表情体系围绕纯数据配置设计——眼环池、动画原语、关键帧序列自由组合,基于现有设计即可自主扩展新表情与新玩法。\n\n仓库同时内置完整的「表情展示馆」站点:开屏线稿 Hero、陈列墙与画册双浏览模式、中英双语界面、明暗双主题。\n\n## 预览\n\n| 开屏 Hero(暗黑) | 明亮主题 · English |\n| :---: | :---: |\n| ![开屏 Hero](emotion-ball\u002Fassets\u002Fscreenshots\u002Feb-hero-dark.png) | ![明亮主题](emotion-ball\u002Fassets\u002Fscreenshots\u002Feb-hero-light-en.png) |\n\n| 陈列墙 | 大图弹窗 |\n| :---: | :---: |\n| ![陈列墙](emotion-ball\u002Fassets\u002Fscreenshots\u002Feb-wall-dark.png) | ![大图弹窗](emotion-ball\u002Fassets\u002Fscreenshots\u002Feb-stage-modal.png) |\n\n![画册模式 · 思考中环带](emotion-ball\u002Fassets\u002Fscreenshots\u002Feb-album-dark.png)\n\n## 特性\n\n- **32 种状态表情**:覆盖生命周期(睡眠 \u002F 唤醒 \u002F 待机…)、情绪反应(开心 \u002F 害羞 \u002F 生气 \u002F 惊讶…)与代理工作状态(思考中 \u002F 检索资料 \u002F 出错 \u002F 任务完成…)三大分组,全部由配置驱动\n- **3 种身体形态**:圆胖(blob)、三角(wedge)、菱形(gem),同一套眼睛与动画系统按轮廓自动适配;另支持主题色实例(团队小球)与线稿模式\n- **分段式 emotionId**:十位数字即分组前缀 —— `00-09` 生命周期、`10-29` 情绪、`30-49` 代理状态、`50+` 自定义;组间空号为新表情预留,已有编号永不重排,对接方可放心硬编码\n- **轮廓环眼睛系统**:25 组 48 点轮廓眼环,逐点弹簧插值形变,表情池随机轮换,眨眼带过冲关键帧\n- **球面投影**:眼睛按身体轮廓做经度换算与余弦压缩,自旋绕到背面时自动隐藏\n- **彩带与撒花**:自旋达速甩出 3D 轨道拖尾彩带(5-stop 色相渐变),思考状态头顶常驻环带,庆祝状态物理粒子撒花\n- **鼠标注视**:全页面注视跟随,帧率无关指数平滑,叠加常驻眼神微漂移\n- **配置驱动、可自主扩展**:每个表情都是「眼环池 + 动画原语 + 关键帧序列」的纯数据组合,支持运行时注册自定义表情、导入导出全部配置,详见[自定义与扩展](#自定义与扩展)\n- **AI 对接协议健壮**:`handleAIMessage` 接受对象或 JSON 字符串,未知 ID、解析失败、缺字段均自动回退待机并触发 `error` 事件,永不白屏\n- **零依赖**:HTML + SVG + 原生 JavaScript,无构建步骤,可直接迁移到 Electron 悬浮窗\n- **展示馆站点**:陈列墙(网格 + 点击弹窗大图)与画册(横向长廊 + 大舞台翻页)双模式,顶部工具行集中提供分组 \u002F 形状 \u002F 间隔下拉与线稿、自动播放开关,中英双语、明暗主题,全部偏好经 localStorage 持久化\n\n## 快速开始\n\n```bash\n# 任意静态服务器均可,例如:\npython -m http.server 8765\n# 总馆(三角色同台):  http:\u002F\u002Flocalhost:8765\u002F\n# Mood Mates 子站:    http:\u002F\u002Flocalhost:8765\u002Fmood-mates\u002F\n# Emotion Ball 子站:  http:\u002F\u002Flocalhost:8765\u002Femotion-ball\u002F\n```\n\n或直接双击 `index.html`(建议通过本地服务器访问,以正常加载 Google Fonts)。\n\n## 集成指南\n\n### 最小接入\n\n按顺序引入四个脚本(无构建、无依赖)即可创建实例;`i18n.js` 与 `app.js` 属于展示站,宿主接入不需要:\n\n```html\n\u003Cscript src=\"emotion-ball\u002Fjs\u002Frings.js\">\u003C\u002Fscript>\n\u003Cscript src=\"emotion-ball\u002Fjs\u002Femotions.js\">\u003C\u002Fscript>\n\u003Cscript src=\"emotion-ball\u002Fjs\u002Fball.js\">\u003C\u002Fscript>\n\u003Cscript src=\"emotion-ball\u002Fjs\u002Fengine.js\">\u003C\u002Fscript>\n\n\u003Cdiv id=\"bot\" style=\"width:200px;height:200px\">\u003C\u002Fdiv>\n\u003Cscript>\n  var ball = EmotionBall.create(document.getElementById('bot'), {\n    emotion: '02', idle: true\n  });\n\u003C\u002Fscript>\n```\n\n### AI 对接协议\n\nAI 只需输出一段 JSON,交给 `handleAIMessage`(接受对象或字符串):\n\n```js\nball.handleAIMessage('{\"emotionId\":\"30\",\"tips\":\"正在思考用户问题\"}');\n```\n\n- 未知 `emotionId`、JSON 解析失败、缺少字段 → 触发 `error` 事件并自动回退待机(`fallbackId`,默认 `'02'`);\n- `tips` 为可选展示文案,通过 `tips` 事件透出,由宿主决定如何呈现。\n\n### 创建选项\n\n| 选项 | 默认 | 说明 |\n| --- | --- | --- |\n| `emotion` | `'02'` | 初始表情 ID |\n| `shape` | `'blob'` | 身体形态:`blob` 圆胖 \u002F `wedge` 三角 \u002F `gem` 菱形 |\n| `color` \u002F `eyeColor` | — | 主题实例体色 \u002F 眼色,优先于表情配置的体色 |\n| `eyeScale` | `1` | 眼睛放大倍率;小于 80px 的实例建议 `1.5~1.8` 保证可读 |\n| `idle` | `false` | 待机策略,超时自动切换待机 \u002F 睡眠,可传对象自定义时长与目标表情 |\n| `autostart` | `true` | 设为 `false` 时只渲染静态帧,不进入动画循环(缩略图用) |\n| `lite` | 跟随 `autostart` | 精简模式:关闭彩带 \u002F 撒花特效 |\n| `fallbackId` | `'02'` | 未知 ID 的回退表情 |\n\n### 事件与方法\n\n```js\nball.on('change', e => {});         \u002F\u002F 表情已切换 { id, def, auto }\nball.on('tips',   e => {});         \u002F\u002F AI 附带文案 { text }\nball.on('error',  e => {});         \u002F\u002F 协议错误 { message, ... }\n\nball.setEmotion('21');              \u002F\u002F 直接切换表情\nball.setGaze(nx, ny);               \u002F\u002F 归一化目光 [-1, 1],宿主自行监听 pointermove\nball.setStyle({ sketch: 1 });       \u002F\u002F 线稿模式\nball.spin(3);                       \u002F\u002F 自旋甩彩带\nball.burst(24);                     \u002F\u002F 撒花\nball.bounce();                      \u002F\u002F 弹跳\nball.startTour(ids, 2500);          \u002F\u002F 自动巡演 \u002F ball.stopTour()\nball.setActive(false);              \u002F\u002F 视口外停帧省电,true 恢复\nball.renderStatic();                \u002F\u002F 停帧状态下渲染一张静态帧\nball.registerEmotion(raw);          \u002F\u002F 运行时注册自定义表情\nball.destroy();                     \u002F\u002F 销毁实例\n```\n\n### 多实例与性能\n\n- 所有实例共享同一个 rAF 心跳,实例数量不增加循环开销;\n- 缩略图墙场景:以 `autostart: false` 静态渲染,悬停时 `setActive(true)`、移出时 `setActive(false)`;\n- 配合 IntersectionObserver 在视口外调用 `setActive(false)` 停帧省电。\n\n### 桌面宠物 \u002F Electron 接入\n\n- 窗口参数:`transparent: true, frame: false, alwaysOnTop: true, skipTaskbar: true`,页面背景透明,只保留小球容器;\n- 鼠标穿透:`win.setIgnoreMouseEvents(true, { forwardMouseMove: true })`,穿透的同时仍可驱动 `setGaze` 注视;\n- AI 消息经主进程 IPC 转发:`ipcRenderer.on('emotion', (_, msg) => ball.handleAIMessage(msg))`;\n- 小尺寸悬浮窗(≤ 120px)建议 `eyeScale: 1.5` 并开启 `lite: true`。\n\n## 自定义与扩展\n\n表情引擎与渲染层是稳定基座,基于现有设计即可自主扩展新表情与新玩法——新增表情只需编写纯数据配置,不需要触碰引擎代码。\n\n### 表情配置格式\n\n```js\n{\n  id: '50', name: '自定义', group: 'custom',\n  desc: '中文描述', en: { name: 'Custom', desc: '...' },\n  transition: 380,            \u002F\u002F 切入过渡时长(ms)\n  gaze: true,                 \u002F\u002F false = 不注视鼠标(睡眠\u002F停止类)\n  pool: [2, 11, 17, 19],      \u002F\u002F 眼环索引池,poolMs 间隔内随机轮换\n  poolMs: [2500, 4500],       \u002F\u002F 轮换间隔;poolSpeed 控制形变速度\n  blinkMs: [2500, 5000],      \u002F\u002F 眨眼间隔(null 不眨)\n  openness: 1,                \u002F\u002F 常驻眼睛开合度(疲惫 0.55、睡眠 0.08)\n  antics: true,               \u002F\u002F 待机随机小动作(自旋\u002F弹跳)\n  body: { breathe: 0.014, color: '#F6EFE4', zzz: 0, orbit: 0 },\n  anims: [ { target: 'eyes', prop: 'lookY', type: 'glance', amp: 6, period: 3000 } ],\n  sequence: { ... }           \u002F\u002F 可选:进入表情时的关键帧序列\n}\n```\n\n### 动画原语\n\n每个表情最多叠加 3 条动画,由 6 种原语组合而成:\n\n| 类型 | 效果 | 关键参数 |\n| --- | --- | --- |\n| `sine` | 正弦漂移 \u002F 呼吸 \u002F 扫视 | `amp, period, phase` |\n| `glance` | 平滑方波,两端停留(左看看、右看看) | `amp, period` |\n| `pulse` | 0 → amp 节奏缩放 | `amp, period` |\n| `jitter` | 伪噪声抖动,可随时间衰减 | `amp, speed, decay` |\n| `scan` | 三角波快速扫动(检索 \u002F 扫读) | `amp, period` |\n| `blink` | 周期闭合(多实例自动错峰) | `interval, dur, phaseMs` |\n\n`target` 可选 `eyes \u002F body \u002F left \u002F right`;`prop` 可选 `lookX \u002F lookY \u002F x \u002F y \u002F scale \u002F open \u002F rotate`。\n\n### 关键帧序列\n\n`sequence` 定义进入表情时的一次性演出,播完后按 `settle` 语义收尾:`'base'` 回落基础姿态(惊讶),`'hold'` 定格末帧(害羞变粉、生气变红),`{ next: '02' }` 自动切换到下一个表情(唤醒 → 待机)。\n\n### 注册与导入导出\n\n```js\n\u002F\u002F 运行时注册新表情(50+ 为自定义编号段,带完整校验)\nEmotionBall.config.register({ id: '50', name: '自定义', group: 'custom', ... });\n\n\u002F\u002F 全量导出 \u002F 导入配置 JSON(Emotion Ball 子站的设置抽屉内也提供同款按钮)\nEmotionBall.config.exportConfig();\nEmotionBall.config.importConfig(json);\n```\n\n### AI 协作 Skills\n\n`.cursor\u002Fskills\u002F` 内置两份工程化规范文档,在 Cursor 等 AI 编辑器中打开本仓库时,AI 会自动遵循:\n\n- **emotion-design**:表情设计规范——眼环池速查表、动画参数取值范围、关键帧语义与双语文案要求,让 AI 按统一视觉语言帮你设计新表情;\n- **emotion-integration**:集成实践——SDK 选项、AI 协议、多实例性能与 Electron 接入要点,让 AI 帮你完成宿主接入。\n\n## 项目结构\n\n```\n(仓库根)\n├── index.html          # 总馆入口:云宝 × 亮亮 × 球球 同台切换\n├── site\u002F               # 总馆外壳:样式 \u002F 文案 \u002F 双引擎适配交互层\n├── mood-mates\u002F         # 原创角色子项目:云宝 \u002F 亮亮(双许可,自带展示站与文档)\n│   ├── index.html      #   Mood Mates 独立展示站\n│   ├── src\u002F            #   引擎:几何 \u002F 渲染 \u002F 五官 \u002F 特效 \u002F 驱动 \u002F 角色包\n│   ├── LICENSE         #   社区许可(个人学习免费)\n│   ├── LICENSE-COMMERCIAL.md  # 商业许可\n│   └── docs\u002F           #   角色设计规范 + 原创证据链\n├── emotion-ball\u002F       # 球形角色项目(形象仅供学习;引擎与表情数据可商业授权)\n│   ├── index.html      #   Emotion Ball 独立展示站\n│   ├── css\u002F js\u002F        #   双主题样式 + 引擎(rings \u002F emotions \u002F ball \u002F engine)\n│   ├── assets\u002F         #   站点图标与 README 截图\n│   └── docs\u002F           #   发布文案\n└── .cursor\u002Fskills\u002F     # AI 协作 Skills:表情设计规范 + 集成实践\n```\n\n## 许可\n\n本仓库包含三类授权不同的内容,请注意区分:\n\n- **表情引擎与表情数据(根目录及 [emotion-ball\u002F](emotion-ball\u002F) 目录)**:源代码(状态机、弹簧插值、球面投影、配置注册中心等)与表情配置数据(眼环 \u002F 眼形 \u002F 嘴形参数、动画原语、关键帧序列)为独立编写与设计,**双许可**——个人学习、研究免费([LICENSE](LICENSE));商业用途可获取商业授权([LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md)),商业集成须搭配自有或另行合法授权的角色形象。\n- **球形角色视觉形象(blob \u002F wedge \u002F gem 身体造型、配色与特效视觉)**:仅供**个人技术学习与研究**,禁止任何商业用途,**不提供、也永不提供商业授权**,详见 [NOTICE.md](NOTICE.md)。\n- **原创角色 云宝 \u002F 亮亮([mood-mates\u002F](mood-mates\u002F) 目录)**:独立原创设计,**双许可**——个人学习、研究免费使用([社区许可](mood-mates\u002FLICENSE));商业产品、SaaS、客户交付等商业场景可获取授权([商业许可](mood-mates\u002FLICENSE-COMMERCIAL.md))。原创证据链见 [mood-mates\u002Fdocs\u002FDESIGN-PROVENANCE.md](mood-mates\u002Fdocs\u002FDESIGN-PROVENANCE.md)。\n\n## 相关项目\n\n原创角色表情引擎 **Mood Mates**(云宝 \u002F 亮亮,双许可、可商用)位于本仓库的 [mood-mates\u002F](mood-mates\u002F) 目录:自带独立展示站(`mood-mates\u002Findex.html`)、集成指南与角色设计规范,与球形角色项目互不影响。\n","Emotion Ball 是一套轻量级 AI 助手表情引擎，通过纯 SVG 与原生 JavaScript 实现 32 种状态表情的实时渲染，支持 blob\u002Fwedge\u002Fgem 三种身体形态、主题色实例及线稿模式；核心采用配置驱动设计，AI 侧仅需传入标准化 emotionId（如 12 表示害羞）即可触发对应表情与动画，具备注视跟随、球面投影、彩带拖尾等视觉特性；适用于聊天机器人、桌面宠物、悬浮助手等需要轻量、零依赖、可嵌入式情绪表达的前端场景。",2,"2026-08-21 02:30:08","CREATED_QUERY"]