RoomForge 이동 메타데이터 1.0

GLB에 포함된 시작점, 무대 중심과 이동 가능 범위의 좌표 규격입니다.

GLB를 읽을 때 장면 루트 노드의 extras.roomforge_navigation을 확인합니다. Three.js GLTFLoader에서는 해당 루트 Object3D의 userData.roomforge_navigation으로 읽힙니다. 별도 navigation.json에도 동일한 값을 저장합니다. extras는 glTF의 사용자 정의 JSON 저장 공간입니다.

좌표와 방향

schema는 roomforge.navigation, version은 1.0입니다. 좌표는 장면 루트 로컬 좌표, 단위는 미터, 순서는 [x, y, z]입니다. 오른손 좌표계, +Y 위, 기본 정면 -Z입니다.

위치는 카메라 높이가 아닌 발바닥이 지지면에 닿는 위치입니다. GLB 루트를 이동·회전·스케일했다면 좌표에도 같은 루트 변환을 적용하세요.

yaw_deg는 +Y축 회전 각도입니다. 0°는 -Z, +90°는 -X, -90°는 +X입니다. Three.js에서는 rotation.y = yaw_deg * Math.PI / 180으로 사용합니다.

필드 규격

필드	의미
`status`	`ready`: AI 선택 및 지형 검사 완료. `unavailable`: 적합한 지점 없음. 이 경우 좌표를 임의로 만들지 않습니다.
`recommended_start`	시작 위치 `position_m`, 바라볼 방향 `yaw_deg`, 선정 이유 `reason`, AI 적합도 `confidence`
`stage_center`	주 무대의 중심에 가까운 이동 가능 지점. 콘서트가 아닌 장소에서는 주요 탐험·상호작용 지점입니다.
`walkable_points`	시작점과 연결된 영역의 추천 이동 지점 목록
`movement_bounds_m`	시작점에서 도달 가능한 표본 영역을 감싸는 `{min:[x,y,z], max:[x,y,z]}`. 내부 전체가 이동 가능하다는 뜻은 아닙니다.
`walkable_area`	`representation: sampled_grid`, `cell_size_m`, 시작 영역 `region_id`, 연결된 이동 가능 표본 `cells`
`walkable_area.cells[]`	각 셀의 지지면 중심 `center_m`, 지지 메시 `support_mesh`, 경사 `slope_deg`
`agent`	검사에 사용한 사람 크기: 높이 1.8m, 반지름 0.55m, 최대 경사 35°, 최대 단차 0.45m
`scene_bounds_m`	하늘을 제외한 전체 장면 메시의 경계
`generated_at`	생성 시각 ISO 8601 UTC
`notes`	검사 범위 및 제한 설명

각 추천 지점에는 support_mesh, region_id, slope_deg, clearance_radius_m, geometry_validated:true도 포함합니다. confidence는 0~1 AI 적합도 판단값이며 측정된 안전 확률이 아닙니다. 무대 중심이 시작점과 다른 영역에 있으면 걸어서 연결되어 있다고 간주하지 마세요.

이동 영역 사용

각 셀은 X/Z 평면에서 center_m을 중심으로 한 변 길이 cell_size_m의 정사각형입니다. Y는 중심점의 지지면 높이이며 셀 전체의 일정한 높이를 뜻하지 않습니다. 셀 중심, 모서리 지지면, 머리 공간, 주변 반지름, 연결 경로의 0.25m 간격 표본을 검사합니다. 연결된 영역만 walkable_area.cells에 저장합니다.

이 데이터는 표본 격자이며 완전한 내비메시가 아닙니다. 이동 후보를 셀 영역으로 제한한 뒤 실제 런타임 캡슐 충돌·바닥 레이캐스트로 이동을 확인하세요. 셀 사이의 작은 장애물이나 동적 물체는 런타임 검사가 필요합니다.

collision:false 장식·군중은 검사에서 제외됩니다. 형상이 수정되면 좌표를 다시 판정하며 재판정되지 않은 오래된 값은 GLB에 넣지 않습니다.

collision:true 군중 구역은 사람이 밀집한 경계 상자를 장애물로 취급합니다. 군중 머리 위를 바닥 후보로 선택하지 않습니다. 관객 사이의 개별 틈새는 이동 가능 범위에 포함하지 않는 보수적인 검사입니다.

Three.js 읽기 예

let navigation, navigationRoot;
gltf.scene.traverse(object => {
  if (object.userData.roomforge_navigation) {
    navigation = object.userData.roomforge_navigation;
    navigationRoot = object;
  }
});
if (navigation?.status === 'ready') {
  const local = new THREE.Vector3(...navigation.recommended_start.position_m);
  const worldFeet = navigationRoot.localToWorld(local);
  // 캐릭터 발 위치를 worldFeet에 배치합니다.
  // 루트 회전이 있으면 yaw에도 루트 월드 회전을 합성합니다.
}

기계 검증 규격은 shared/navigation.schema.json입니다. 이동 가능 지점을 AI가 새로 상상하는 대신 실제 지형 검사에서 얻은 후보 중 선택합니다.