referencegrowing

BoardFace アバター仕様

ボードゲームプラットフォーム向けアバター生成ツール BoardFace の仕様。決定論的 seed 生成、tier2 gem カラー、blob 形状、目・口パターン、mood 連動、React 組み込み方針を定義する。

BoardFace アバター仕様

ボードゲームプラットフォームで使用するアイコン生成ツール。dicebear ライクに seed から決定論的にアバターを生成し、遠くから見ても判別可能なシンプルな図形で構成する。観戦者・未登録ユーザーは特別色に固定し、登録ユーザーは tier2 gem カラーで識別する。

目的と制約

  • 遠視認性: 一辺 24px でも「笑顔・驚き・眠たげ」が判別できること
  • 決定論: 同一 seed + role からは常に同一 SVG が生成される(サーバ保存不要)
  • シンプル: 背景 + blob + 顔(目・口・頬)の 3 層に限定
  • 移植性: DOM 非依存の純関数で SVG 文字列を返す(React 側は dangerouslySetInnerHTML で流すだけ)

カラーパレット

Champagne Silk デザイントークン(theme.mjs CHAMPAGNE_SILK と parity)に準拠。純黒 #000 / 純白 #FFF は使わず、--cs-ink: #3d3323 / --cs-paper: #faf9f6 で代替する。

ロール別カラー

Rolefacebackground用途
usertier2 gem から 1 色別の gem から 1 色(face より明度高)登録ユーザー
guest#c9a961(champagne)#f1e2b6未登録ユーザー
spectator#78848e(platinum)#edeff0観戦者
ai#b77068(rose-gold)#f0cfcbAI の席

役の色は金属で揃える(guest=champagne gold・ai=rose gold・spectator=platinum)。spectator の platinum は parlourite の view role(#78848e)=theme.md §8.3 の platinum ramp の 3 shade(face=500・deep=700 #5c666e・background=100)。2026-10-28 に pearl から変えた。役の色は identity でなく役の印ゆえ version に凍結しない(全 version で同じ値=05-versions.ts の注記)。

tier2 gem(12 色)

ruby #c0223a / deep #8e1428
sapphire #1f4e9c / deep #163a75
citrine #e8b31c / deep #8c6a0e
emerald #1f7a45 / deep #145c33
amethyst #7a4fa3 / deep #593979
carnelian #cb6015 / deep #ad4c12
turquoise #2a8e9b / deep #0f5f6b
onyx #443e4a / deep #3e3846
rose-quartz #ce6a9a / deep #b04a7a
peridot #74932a / deep #5a7a1c
smoky-quartz #7a5537 / deep #573a24
pearl #ded5c3 / deep #726a5b

背景色の決定則

face と background は 別の gem から選ぶ。background は face の輝度より +0.28 以上明るくなるよう、gem の base 色を白と混合する。

targetBgLum = min(0.94, faceLum + 0.28)
t = clamp((targetBgLum - bgBaseLum) / (1 - bgBaseLum), 0.45, 0.92)
bg = mixHex(bgGem.base, "#ffffff", t)

インク色(目・口の色)

readableInk(faceColor) で face の輝度 < 0.36 なら CSS_PAPER、それ以外は CSS_INK を返す。

  • 単色図形: 上記の adaptive ink を使う
  • hollow 図形(ringHollow / ringDouble / ellipseHollow): 固定で CSS_INK の縁 + CSS_PAPER の地。face の色に依らず常に同じ「白地・黒縁・黒中心」で読める

パイプライン

seed + role
↓
faceParamsFromSeed(seed) — 形状・表情・tilt(role 非依存)
↓
resolvePalette(role, rng) — 色(role 依存)
↓
buildAvatarSVG(params) — 純関数、SVG 文字列を返す

重要: role は色のみに作用し、形状・表情パターンには一切影響しない。これにより「同じユーザーが観戦者になった時も顔は同じ」を保証する。

Blob 形状

100×100 viewBox 内で、中心 (50,50) 付近に半径 48〜62 のブロブを描く。周方向の sin 波を重ねて半径を揺らし、Catmull-Rom で滑らかに閉じる。

形状タイプ(10 種)

type説明
round2 周波の控えめな揺らぎ
smooth3 周波の滑らかな揺らぎ(既定)
wobbly4 周波の強い揺らぎ
droplet1 周波 + 2 周波で雫型
polygon6〜8 頂点の凸多角形(角丸)
flower5 周波で花形
star5 周波の強い尖り
diamond4 頂点の菱形(角丸)
hexagon6 頂点の正六角形(角丸)

制約

  • 周方向の振幅合計は baseR * 0.28 を上限とする(内側に沈み過ぎて顔がはみ出さないように)
  • 多角形は 凸 のみ(180° を超える角を含まない)。全頂点を二次ベジェで角丸(半径 edgeLen * 0.28、上限 7)

顔の構成

座標系

face center (cx, cy) は blob center の近傍(±6)。face tilt angle は seed 由来 ±14°(UI スライダーで ±20° 追加可)。

パラメータ範囲

パラメータ範囲
eyeSize10〜16
eyeSpacing24〜36
eyeOffsetY-12〜-4(負は上方向)
eyeAngle-4〜4
mouthWidth18〜30
mouthOffsetY10〜20
mouthAngle-4〜4
faceAngle-14〜14

頬

  • 出現率 45%
  • 半径 eyeSize * 0.42
  • 目の外側に配置: x = cx ± (spacing/2 + eyeSize*0.9 + blushR*1.0)
  • 目の下に配置: y = eyeY + eyeSize*0.5 + blushR*1.2
  • 色は mixHex(face.base, "#ffffff", 0.38)、透明度 0.60

目のパターン(31 種 + sunglasses + monocle)

単色ドット系

  • solidDot — 黒丸
  • highlight — 黒丸 + 白ハイライト

hollow 系(固定 CSS_INK / CSS_PAPER)

  • ringDouble — 白丸 + 黒縁 + 黒丸 + 白点(3 層)
  • ringHollow — 白丸 + 黒縁 + 黒中心(ドーナツ幅 0.28)
  • ellipseHollow — 極扁平な横長 hollow

リング系(adaptive ink)

  • ringThick — r=0.24, stroke=0.40(小さな極太)
  • ringThin — r=0.60, stroke=0.09(大きな細)

弧・笑顔系

  • arcUp — 浅く広い上向き弧
  • arcDown — 浅く広い下向き弧
  • smileClosed — 深く太い下向き弧(笑い目)
  • chevron — 尖った山型
  • chevronDown — 尖った谷型

閉じ目系

  • closedLine — 横一文字
  • closedLineTilt — 斜め一文字
  • closedLineLashes — 横線 + 上向きまつ毛 3 本
  • sleepy — 上まぶたカーブ + 下に細線(半目)

図形系

  • verticalEllipse — 縦長楕円 (rx 0.22, ry 0.60)
  • horizontalEllipse — 横長楕円 (rx 0.60, ry 0.22)
  • square — 角丸四角
  • diamond — 菱形
  • triangle — 上三角
  • halfCircle — 半円
  • plus — 十字
  • xMark — バツ
  • sparkle — 四芒星
  • star5 — 五芒星
  • flowerEye — 6 枚の花びら円 + 中央コントラスト円
  • heart — ハート
  • zigzag — ジグザグ

特殊(両目で 1 図形)

  • sunglasses — 左右のレンズ + ブリッジ + ガラス反射
  • monocle — 左目のみ丸縁(ステムなし)

口のパターン(24 種)

線・スマイル系

  • line — 横一文字
  • smallSmile — 極小弧 (0.20w)
  • smileU — 中庸弧 (0.42w)
  • smileD — D 字カーブ
  • smileWide — 極横長浅弧 (0.72w)
  • smile3 — 「3」型
  • doubleSmile — 二重弧
  • smirk — 片側上がり
  • frown — への字
  • tilde — 波線
  • zigzag — ジグザグ

点系

  • dot — 小円

開口系

  • openO — 縦長楕円開口
  • tinyO(削除)→ dot で代替
  • squareO — 角丸四角開口
  • openBig — 半円開口
  • openD — 台形開口(上フラット、下角丸)
  • openSmile — 上フラット + 下深カーブ
  • grinOpen — 浅い三日月開口
  • tongue — 舌付き(舌は face.deep 色)
  • pucker — 薄くて縦長のキス顔

ω 系

  • omega — 猫口
  • bigOmega → openSmile に統合

Mood システム

目と口を独立にランダム抽選すると「変な顔」になるため、先に気分(mood)を選び、その気分のプールから目・口を抽選する。

mood出現重み目のプール
happy3arcUp, chevron, smileClosed, ringDouble, highlight, sparkle, heart, star5, flowerEye
sleepy1sleepy, closedLine, arcDown, closedLineLashes, horizontalEllipse
surprised1ringDouble, ringHollow, highlight, sparkle, star5, verticalEllipse
mischievous2chevron, closedLineTilt, sparkle, diamond, xMark, sunglasses, plus
cute3highlight, ringDouble, sparkle, heart, smileClosed, ellipseHollow, flowerEye
cool2sunglasses, monocle, chevronDown, closedLineTilt, diamond, triangle, square
neutral2solidDot, ringDouble, verticalEllipse, ringHollow, horizontalEllipse, plus

パターン総数

要素数
目31 + sunglasses + monocle = 33
口24
形状10
色(user)face 12 × bg 12(≠ face)≒ 132 組合せ

離散組み合わせ総数: 33 × 33 × 24 × 10 × 132 ≒ 3.5 億通り。連続パラメータ(位置・サイズ・角度・tilt ±20°)を含めると事実上無限。

永続化

アバターは以下の 3 値のみ DB に保存する(色・形状は seed から再現可能なため保存不要)。

seed string 決定論的生成のキー
role enum user | guest | spectator
initials string 任意、1〜2 文字
name string 表示名(イニシャル抽出に使用)

URL 共有: ?seed=xxx&role=user で再現可能。

React + Vite への組み込み方針

  1. js/ 配下のコア(rng / palette / blob / eye-types / mouth-types / moods / core / generator)を src/avatar/core/ に ESM そのままコピー
  2. UI 層は React コンポーネントに置換(80-preview 以降)
  3. buildAvatarSVG(params) は純関数なので useMemo でキャッシュし、<span dangerouslySetInnerHTML={{__html: svg}} /> で描画
  4. tier2 カラーは本家の CSS 変数 --cs-gem-* と TS 定数の両方で保持(gate で parity を固定)
  5. SSR でも buildAvatarSVG が文字列を返すため、そのまま利用可

未確定事項

  • TBD: seed → パラメータ の重み付け(mood の出現率)は実運用で調整の余地あり
  • TBD: イニシャル表示時の目・口の自動縮小ロジック は本家移植時に検討
  • TBD: サングラスレンズの色 は現状 adaptive ink。ブランドカラーとの整合は要検討