DesktopPetStudio

CREATOR DOCUMENTATION

用 JSON 製作可分享的桌寵內容

這份指南說明怎麼把圖片、動畫、移動、音效、氣泡和 AI 素材提示整理成可掃描與匯入的工作坊內容。

開始前：選擇要分享的內容

姿勢包使用 "type": "pose"，適合分享一個右鍵呼叫姿勢與它的素材。完整桌寵包使用 "type": "pet"，以 pet_config.json 帶入基礎姿勢、提醒、快捷鍵與其他設定。養成內容則可使用 "type": "care"，提供商城物品、工作與日常事件。

1. 建立資料夾

讓入口 JSON 和所有圖片、音效留在同一個可攜資料夾內。其他玩家匯入時，程式會從 JSON 所在位置解析相對路徑。

MyWavePose/
  desktop_pet_studio_workshop.json
  assets/
    frame_01.png
    frame_02.png
    frame_03.png
    frame_04.png
    frame_05.png
    frame_06.png
    wave.wav

請使用 assets/frame_01.png 這類相對路徑，不要填入 C:\Users\... 等本機絕對路徑。素材建議使用透明背景 PNG；走動影格請面向右方，桌寵在往左移動時會自動鏡像。

2. 寫入單一姿勢 manifest

以下範例能建立一個揮手姿勢：使用六張獨立影格、播放音效、隨機氣泡，並以小跳躍方式移動。

{
  "schema_version": 1,
  "id": "my-wave-pose",
  "title": "揮手打招呼",
  "type": "pose",
  "content_kind": "single_pose",
  "assets_mode": "bundled",
  "pose": {
    "name": "揮手打招呼",
    "category": "custom",
    "animation_paths": [
      "assets/frame_01.png", "assets/frame_02.png", "assets/frame_03.png",
      "assets/frame_04.png", "assets/frame_05.png", "assets/frame_06.png"
    ],
    "playback_speed": 1.25,
    "sound_path": "assets/wave.wav",
    "bubble_texts": ["嗨，我在這裡！", "今天也一起加油"],
    "bubble_interval_sec": 20,
    "enabled": true,
    "movement": {
      "enabled": true,
      "mode": "hop",
      "speed": 1.2,
      "distance_px": 160,
      "vertical_px": 36,
      "duration_sec": 2.4,
      "loop": false,
      "gravity": false
    }
  }
}

3. 設計移動，而不是執行程式

movement 只接受白名單資料，JSON 不會執行任意程式碼。可用模式為 none、wander、patrol、hop、shake、drift 與 sequence。其中 sequence 可用多段 dx、dy、duration_ms 與 easing 組成演出。

playback_speed

動畫倍率，支援 0.25 到 4.0；多數姿勢建議 0.75 到 1.5。

distance_px

水平距離或抖動幅度，範圍 0 到 2400。

vertical_px

垂直距離或跳躍高度；負數可用於向上漂移。

gravity

設為 false 時，姿勢期間不會進入自然下墜流程。

4. 提供 AI 素材提示

可選用 ai_asset_prompts，引導玩家延伸同一角色的姿勢。至少提供一個語系文案；介面會優先顯示目前語言，沒有時回退為中文或英文。單一姿勢包會直接顯示提示；完整桌寵包則以整包標題建立可展開群組。

"ai_asset_prompts": [{
  "id": "wave_ai_prompt",
  "name": "揮手姿勢 AI 說明",
  "pose_id": "wave",
  "zh": "請用我上傳的角色圖，製作揮手動畫。輸出 6 張獨立透明背景 PNG，檔名 frame_01.png 到 frame_06.png；不要六宮格、不要 sprite sheet、不要文字、不要浮水印。",
  "zh_cn": "请用我上传的角色图，制作挥手动画。输出 6 张独立透明背景 PNG；不要六宫格、不要 sprite sheet、不要文字、不要水印。",
  "en": "Use my character reference to create a waving animation. Output six separate transparent-background PNG frames; no grid, sprite sheet, text, or watermark."
}]

分享前檢查

  • 每張影格的角色中心點盡量一致，避免播放時晃動。
  • 完整桌寵包以 config_path 指向 pet_config.json；不要包含 Google token、OAuth 設定、本機訂閱清單或其他私密資料。
  • 只放入你擁有或已取得授權的圖片、音效與文字；為素材來源與使用條件做清楚標記。
  • 先以工作坊頁的掃描與匯入流程在乾淨資料夾測試，再分享給其他玩家。