シーン設定JSON詳細仕様

概要

3Dシーンとエンティティ（オブジェクト）を定義するThreedive AIにおけるJSON形式の仕様書です。

スペース設定の詳細設定タブ - JSONエディタで直接編集が可能

基本仕様

• 座標系: 右手座標系（Y軸が上方向）
• 位置単位: メートル
• 回転単位: ラジアン（Euler角）
• 文字エンコーディング: UTF-8

トップレベルフィールド

フィールド名	型	必須	説明
entities	array	✓	シーン内のエンティティ配列
name	string		シーン名（表示用）
sceneId	string		シーンの内部識別子
description	string		シーンの説明文
version	number		JSONフォーマットバージョン
scene	object		シーン全体の設定
sceneTitle	string		シーンの表示タイトル

sceneオブジェクト

フィールド名	型	デフォルト	説明
initialPosition	[number, number, number]	[0,0,0]	初期カメラ位置 [x,y,z]
initialRotation	[number, number, number]	[0,0,0]	初期カメラ回転 [x,y,z]
url	string		シーンファイル（GLB等）のパス

エンティティフィールド（entities配列内）

基本フィールド

フィールド名	型	必須	デフォルト	説明
id	string	✓		UUID形式推奨の一意識別子
type	string	✓		エンティティ種別（"model", "light", "audio"等）
name	string			エンティティの表示名
description	string		""	エンティティの説明文
url	string	△		リソースファイルパス（typeがmodelの場合必須）

変換フィールド

フィールド名	型	デフォルト	説明
position	[number, number, number]	[0,0,0]	位置 [x,y,z]（メートル）
rotation	[number, number, number]	[0,0,0]	回転 [x,y,z]（ラジアン）
scale	[number, number, number]	[1,1,1]	スケール [x,y,z]（倍率）

動作フィールド

フィールド名	型	デフォルト	説明
animationName	string		再生するアニメーション名
interactive	boolean	false	ゲストユーザー操作可能フラグ
chatRadius	number	0	会話可能範囲の半径（メートル）
aiConfigId	string		AI設定の参照ID

最小構成例

{
  "entities": [
    {
      "id": "09be23d0-e530-42d6-b797-22c294539ba6",
      "type": "model",
      "name": "ネコ",
      "url": "/avatars/animal01/Model_catw.glb",
      "position": [0, -0.5, -5]
    }
  ],
  "sceneId": "park",
  "name": "sample park"
}

完全記述例

{
  "entities": [
    {
      "id": "09be23d0-e530-42d6-b797-22c294539ba6",
      "type": "model",
      "name": "ネコ",
      "description": "パーク内のネコキャラクター",
      "url": "/avatars/animal01/Model_catw.glb",
      "position": [0, -0.5, -5],
      "rotation": [0, 0, 0],
      "scale": [1, 1, 1],
      "animationName": "CharacterArmature|Idle",
      "interactive": false,
      "chatRadius": 3,
      "aiConfigId": "J4cMw37Ywp"
    }
  ],
  "name": "sample park",
  "sceneId": "park",
  "description": "parkシーンの公開用サンプル",
  "version": 1,
  "scene": {
    "initialPosition": [0, 0, 0],
    "initialRotation": [0, -3.14, 0],
    "url": "/scenes/park/CYZYPark.glb"
  },
  "sceneTitle": "パーク"
}

注意事項

ID管理

• idフィールドにはUUID v4形式を使用（例: "09be23d0-e530-42d6-b797-22c294539ba6"）
• 重複を避けるため、新規作成時は必ず新しいUUIDを生成

パス指定

• urlフィールドは相対パス（"/"始まり）または絶対URLを使用
• CORS設定に注意（異なるドメインからのリソース読み込み時）

座標と回転

• position: モデルの原点位置によってはY軸調整が必要（地面との接地点）
• rotation: ラジアン単位（π = 180度、2π = 360度）
• 回転順序: Euler角 XYZ順（プロジェクトで統一）

タイプ別の必須フィールド

• type: "model" → urlフィールド必須
• type: "light" → 光源設定フィールドを追加
• type: "audio" → urlフィールドで音声ファイル指定

AI機能連携

• chatRadius: 0より大きい値で会話範囲を有効化
• aiConfigId: 存在するAI設定IDを指定（未定義IDは無視される）
• interactive: trueでゲストユーザーとのインタラクションを有効化