WebSocket Protocol / WebSocketプロトコル定義
Overview / 概要
Backend → Frontend 間のリアルタイム通信プロトコル。全メッセージはJSON形式。
All messages between backend and frontend are JSON over WebSocket.
Connection Sequence / 接続シーケンス
Frontend Backend
│ │
│──── WebSocket Connect ─────────▶│
│ │
│◀─── game_state_init ───────────│ (full state on connect)
│ │
│◀─── heartbeat (every 30s) ─────│
│ │
│◀─── action_update ────────────│ (every 10-min cycle)
│◀─── dialogue ─────────────────│
│◀─── comment_response ─────────│
│◀─── status_change ────────────│
│ │
│◀─── tip_received ─────────────│ (immediate on tip)
│◀─── tip_reaction ─────────────│
│◀─── item_added ───────────────│
│◀─── effect_trigger ───────────│
│ │
│──── pong (response) ──────────▶│ (keep-alive)
│ │
Reconnect:
│──── WebSocket Connect ─────────▶│
│◀─── game_state_init ───────────│ (full state resync)Base Message Format / 基本メッセージフォーマット
json
{
"type": "message_type",
"payload": { ... },
"timestamp": "2026-03-10T18:30:00.000Z"
}Message Types / メッセージタイプ一覧
1. game_state_init
Sent on initial connection and reconnection. Full game state sync.
接続・再接続時に送信。ゲーム状態の完全同期。
json
{
"type": "game_state_init",
"payload": {
"game_day": 3,
"current_time": "18:30",
"characters": [
{
"name": "John",
"position": { "x": 5, "y": 3 },
"current_action": "rest",
"animation": "sit",
"direction": "down",
"stats": {
"hp": 80, "hunger": 45, "mood": 70,
"energy": 60, "stress": 35
},
"love_partner": 75,
"love_pet": 85
},
{
"name": "Sara",
"position": { "x": 7, "y": 4 },
"current_action": "cook",
"animation": "stand",
"direction": "up",
"stats": {
"hp": 85, "hunger": 50, "mood": 75,
"energy": 70, "stress": 25
},
"love_partner": 78,
"love_pet": 90
},
{
"name": "Eve",
"position": { "x": 6, "y": 5 },
"current_action": "idle",
"animation": "sit",
"direction": "right",
"stats": {
"hp": 90, "hunger": 55, "mood": 80, "energy": 70
},
"mischief": 50
}
],
"household": {
"balance": 1500,
"total_tips": 3000,
"room_type": "1K",
"room_cleanliness": 65,
"room_comfort": 40
},
"owned_items": ["Futon", "Small table", "Old fridge", "Kotatsu"],
"food_stock": { "rice": 2, "egg": 3, "instant_noodle": 1 }
},
"timestamp": "2026-03-10T18:30:00.000Z"
}2. action_update
Character action change (every 10-min cycle).
キャラの行動更新（10分サイクルごと）。
json
{
"type": "action_update",
"payload": {
"character": "John",
"action": "cook",
"target": "curry",
"location": "kitchen",
"destination": { "x": 3, "y": 2 },
"duration_minutes": 30,
"animation": "walk",
"direction": "left"
},
"timestamp": "2026-03-10T18:30:00.000Z"
}3. dialogue
Character-to-character or character-to-self speech.
キャラ同士の会話・独り言。
json
{
"type": "dialogue",
"payload": {
"character": "John",
"target_character": "Sara",
"text_ja": "今日はカレー作るよ！",
"text_en": "I'm making curry today!",
"emotion": "motivated",
"emotion_intensity": 0.7,
"display_duration_ms": 5000
},
"timestamp": "2026-03-10T18:30:05.000Z"
}4. tip_received
Tip notification (immediate). Triggers visual effect.
投げ銭受信通知（即時）。エフェクト発火。
json
{
"type": "tip_received",
"payload": {
"platform": "youtube",
"amount_raw": 500,
"currency": "JPY",
"amount_lc": 500,
"user_name": "yuki_chan",
"message": "こたつプレゼント！",
"item_name_ja": "こたつ",
"item_name_en": "Kotatsu",
"item_category": "furniture",
"effect_tier": "medium"
},
"timestamp": "2026-03-10T18:35:12.000Z"
}5. tip_reaction
Character reactions to a tip (immediate, follows tip_received).
投げ銭へのキャラリアクション（即時、tip_receivedの直後）。
json
{
"type": "tip_reaction",
"payload": {
"reactions": [
{
"character": "John",
"text_ja": "おっ、こたつ！やったー！yuki_chanさんありがとう！",
"text_en": "Oh, a kotatsu! Awesome! Thanks yuki_chan!",
"emotion": "excited",
"animation": "jump"
},
{
"character": "Sara",
"text_ja": "わー！嬉しい！これで冬もあったかいね♪",
"text_en": "Yay! So happy! Now we'll stay warm this winter!",
"emotion": "happy",
"animation": "jump"
}
],
"eve_reaction": {
"action": "sniff_item",
"sound": "Woof!",
"animation": "walk_to_item",
"target_position": { "x": 5, "y": 4 }
}
},
"timestamp": "2026-03-10T18:35:14.000Z"
}6. comment_response
Character responding to a viewer comment (10-min cycle batch).
視聴者コメントへの反応（10分バッチ）。
json
{
"type": "comment_response",
"payload": {
"character": "Sara",
"to_user": "cooking_fan_123",
"to_platform": "youtube",
"text_ja": "今日はカレーだよ！ジョンが作ってくれるの〜",
"text_en": "It's curry today! John's making it for us~",
"emotion": "happy",
"display_duration_ms": 6000
},
"timestamp": "2026-03-10T18:30:08.000Z"
}7. status_change
Status value change notification.
ステータス値変動通知。
json
{
"type": "status_change",
"payload": {
"character": "John",
"changes": [
{ "stat": "hunger", "old": 45, "new": 40 },
{ "stat": "stress", "old": 35, "new": 30 }
]
},
"timestamp": "2026-03-10T18:40:00.000Z"
}8. item_added
New item added to the room.
新アイテム追加。
json
{
"type": "item_added",
"payload": {
"item_id": "kotatsu",
"name_ja": "こたつ",
"name_en": "Kotatsu",
"category": "furniture",
"position": { "x": 5, "y": 4 },
"sprite_id": "furniture_kotatsu"
},
"timestamp": "2026-03-10T18:35:13.000Z"
}9. effect_trigger
Visual/audio effect trigger.
視覚・音声エフェクト発火。
json
{
"type": "effect_trigger",
"payload": {
"effect_type": "tip_banner",
"tier": "medium",
"data": {
"user_name": "yuki_chan",
"amount_lc": 500,
"platform": "youtube"
},
"duration_ms": 5000
},
"timestamp": "2026-03-10T18:35:12.000Z"
}10. milestone_reached
Cumulative tip milestone achievement.
累計投げ銭マイルストーン達成。
json
{
"type": "milestone_reached",
"payload": {
"milestone_name_ja": "応援ボード設置",
"milestone_name_en": "Support Board",
"total_tips": 5000,
"effect": "wall_names_display"
},
"timestamp": "2026-03-10T20:00:00.000Z"
}11. heartbeat
Server heartbeat (every 30 seconds).
サーバーハートビート（30秒ごと）。
json
{
"type": "heartbeat",
"payload": {
"server_time": "2026-03-10T18:30:30.000Z",
"game_day": 3,
"uptime_seconds": 86400,
"connected_clients": 1
},
"timestamp": "2026-03-10T18:30:30.000Z"
}12. error
Error notification.
エラー通知。
json
{
"type": "error",
"payload": {
"code": "LLM_TIMEOUT",
"message": "AI response timed out, using fallback action",
"severity": "warning"
},
"timestamp": "2026-03-10T18:30:00.000Z"
}Message Priority / メッセージ優先度
| Priority | Type | Description |
|---|---|---|
| 1 (Highest) | tip_received, tip_reaction, item_added, effect_trigger | Immediate tip processing |
| 2 | action_update, dialogue, comment_response | 10-min cycle results |
| 3 | status_change, milestone_reached | State updates |
| 4 (Lowest) | heartbeat, error | System messages |
Reconnection / 再接続
| Setting | Value |
|---|---|
| Heartbeat interval | 30 seconds |
| Missed heartbeats before disconnect | 3 (90 seconds) |
| Reconnect delay | 1s → 2s → 4s → 8s → 16s → 30s (exponential backoff, max 30s) |
| On reconnect | Server sends game_state_init (full resync) |
Frontend Buffer / フロントエンドバッファ
During reconnection, the frontend should:
- Show "Reconnecting..." overlay (semi-transparent)
- Keep the last known game state displayed
- On reconnect, apply
game_state_initto fully resync - Resume normal rendering
Rate Limits / レート制限
| Type | Limit |
|---|---|
| Tip reactions | Max 1 per 5 seconds (queue excess) |
| Action updates | 1 per 10-min cycle |
| Comment responses | Max 3 per 10-min cycle |
| Heartbeat | 1 per 30 seconds |