grokbot_widget 0.1.0

Pure Flutter animated GrokBot avatar with expressions, shapes, states, gaze, head turn, blink, and CustomPaint rendering.

grokbot_widget

纯 Flutter 的 GrokBot 动画头像控件：用 CustomPaint 绘制身体与双眼，无 WebView、无原生 SVG 依赖。

内置 25 种表情、18 种形态、39 种状态（表情池 + 节奏）、视线、转头球面投影、弹簧形变与眨眼。

项	说明
包名	grokbot_widget
版本	0.1.0
SDK	Dart >=3.4.0 <4.0.0 · Flutter >=3.22.0
依赖	仅 flutter SDK

---

快速开始

依赖

dependencies:
  grokbot_widget:
    path: ../GrokBot   # 按实际路径调整

最小示例

import 'package:flutter/widgets.dart';
import 'package:grokbot_widget/grokbot_widget.dart';

class Avatar extends StatelessWidget {
  const Avatar({super.key});

  @override
  Widget build(BuildContext context) {
    return const GrokBot(
      size: 160,
      state: GrokBotState.thinking,
      shape: GrokBotShape.blob,
      autoExpression: true,
    );
  }
}

带控制器（眨眼 / 旋转 / 重置）

final controller = GrokBotController();

GrokBot(
  controller: controller,
  size: 200,
  state: GrokBotState.idle,
  shape: GrokBotShape.capsule,
  gaze: const Offset(0.3, -0.1),
  turn: 0.2, // 弧度
  autoBlink: true,
  autoExpression: true,
  theme: GrokBotThemeData.dark,
)

// 任意时刻：
await controller.blink();
await controller.spin(turns: 1, duration: const Duration(milliseconds: 1200));
await controller.reset();

运行 example 与测试

flutter test
flutter analyze
cd example && flutter run

---

公开 API

import 'package:grokbot_widget/grokbot_widget.dart';

导出：GrokBot、GrokBotController、GrokBotState / GrokBotShape / GrokBotExpression、GrokBotThemeData。

GrokBot 属性

属性	类型	默认	说明
state	GrokBotState	idle	选表情池与自动眨眼 / 换表情节奏
shape	GrokBotShape	blob	身体轮廓 + 面部几何校正
expression	GrokBotExpression?	null	非空时锁定表情；为 null 时由状态 / 自动切换决定
gaze	Offset	Offset.zero	归一化视线，每轴 [-1, 1]，内部映射约 ±13.2 / ±8.4
turn	double	0	基础转头角，弧度；会与 spin 叠加
eyeScale	double	1	眼睛缩放倍率（须 > 0）
springFrequency	double	7	表情切换弹簧自然频率 ω（须 > 0）
autoBlink	bool	true	是否按状态节奏自动眨眼
autoExpression	bool	false	expression == null 时是否按状态池自动换表情
flipX	bool	false	水平镜像
emphasis	bool	false	眼睛再放大约 18%
showGuides	bool	false	绘制球面参考与眼睛质心
size	double?	null	正方形边长；null 时取父约束最短边
theme	GrokBotThemeData	浅色默认	身体 / 眼睛等颜色
controller	GrokBotController?	null	命令式眨眼、旋转、重置
semanticLabel	String	'GrokBot'	无障碍标签

持久配置用 widget 属性；controller 只驱动短暂动画，不改写父组件传入的属性。

GrokBotController

一个 controller 同时只能挂到一个 GrokBot。

方法	说明
blink()	触发一次 320ms 眨眼（42% 闭合 + 58% 睁开，最小高度 4%）
spin({turns, duration})	转 turns 圈，默认 1 圈 / 1200ms；新 spin 会接替未完成的
reset()	取消短暂动画，表情回到当前状态池第一项（或锁定的 expression）
isAttached	是否已挂到已挂载的 GrokBot

GrokBotThemeData

字段	用途
bodyColor	身体填充
eyeColor	眼睛填充
guideColor	辅助球面线
centroidColor	质心标记
badgeColor / particleColor	预留（当前不绘制）

预设：const GrokBotThemeData()、GrokBotThemeData.dark。支持 copyWith / lerp。

---

状态 · 形态 · 表情

状态 GrokBotState（39）

每个状态绑定：表情池、表情节奏、眨眼节奏（可为「不自动眨眼」）。

分组	状态
生命周期	sleeping waking idle listening thinking searching working
反应	excited surprised suspicious angry drowsy happy curious confused bored proud shy sad laughing scared playful celebrate
代理形态	orbit radar progress
产品周期	spawning humming loading dictating writing sending receiving uploading notifying alerting dragging bouncing poweringDown

poweringDown 的展示名（sourceName）为 powering-down。

示例：idle → 表情 [0, 8]，换表情 9–16s，眨眼 6–14s；sleeping → 不自动眨眼。

形态 GrokBotShape（18）

blob pebble bean egg squircle tablet capsule cylinder hex gem crystal wedge shield dome arch cloud teardrop leaf

每种包含：圆角轮廓、宽高比、面部校正（偏移 / 缩放 / 眼睛倍率）、转头是否压扁身体。

表情 GrokBotExpression（25）

expression00 … expression24。每个为双眼各 48 点的闭合轮廓；切换时用阻尼弹簧插值。

---

渲染与动画

state / timers  →  弹簧 morph (≈120Hz 步进)
                →  48 点环插值
                →  视线 + 球面投影 (turn)
                →  CustomPaint 绘制身体与双眼

• 视线：归一化 gaze → 画布偏移（约 ±13.2 × ±8.4）
• 转头：眼睛质心映射到球面经度，宽度随 cos 压缩，转到脑后隐藏
• 眨眼：320ms，闭快于开
• Ticker：仅在 morph / blink / spin 活跃时运行

---

目录结构

grokbot_widget/
├── lib/
│   ├── grokbot_widget.dart      # 库入口
│   └── src/
│       ├── grokbot.dart           # GrokBot + Controller
│       ├── grokbot_painter.dart
│       ├── geometry.dart
│       ├── models.dart
│       ├── theme.dart
│       └── data/
│           ├── expression_data.dart
│           ├── shape_data.dart
│           └── state_data.dart
├── example/                       # 演示 App
└── test/                          # 单元 / Widget / Golden

---

设计约定

1. 声明式配置 + 命令式瞬间 — 状态/形态/视线用属性；眨眼/转圈用 GrokBotController。
2. 一个 Controller 对应一个 GrokBot — 重复 attach 会抛 StateError。
3. expression 优先于自动切换 — 锁定表情时不跑自动换表情。
4. 零第三方绘制依赖 — 便于多端一致与 golden 回归。

---

版本

见 CHANGELOG.md。当前 0.1.0：表情、视线、转头、眨眼、状态、形态、主题，以及 blink / spin / reset。