룸 통합 가이드
Locus에 당신의 아키텍처를 가져오세요.
이미 알고 있는 전문 도구로 모델, 텍스처, 조명 및 내보내기를 수행합니다. Locus은 작성 워크플로우를 지정하지 않으며, USDZ 하나와 개방, 좌석, 표면 및 선택적 조명을 위한 작은 명확한 인터페이스를 사용합니다.
정적 스카이박스 튜토리얼로 아이디어에서 함께 쓸 View를 만들어 보세요.
Package v2로 시작하기
현재 룸 제작에는 완전한 Package v2를 사용하세요. 고정 ID와 업데이트, 현재 지원되는 기능을 사용할 수 있습니다. 일반적으로 룸과 함께 쓸 뷰는 별도로 패키징하여 각각 따로 배포하고 교체하고 제거할 수 있도록 합니다.
예제 다운로드
무료 Room과 일부 무료 View는 학습용 예제로 다운로드할 수 있으며, 일부는 Blender 소스도 함께 제공됩니다. 갤러리에서 예제 둘러보기.
코딩 에이전트는 place-examples.json 에서 각 다운로드의 URL, 크기, SHA-256, 기능, 라이선스를 읽을 수 있습니다.
룸 학습용 이전 패키지
이 평면 호환 ZIP은 완성된 USDZ와 비교해 재질 및 공개 메타데이터를 살펴볼 수 있도록 남겨 두었습니다. 현재 Package v2 기능을 설명하는 가이드는 아닙니다.
이전 다운로드 및 호환성 메모를 열어보세요.
Locus이 작성한 부품은 CC BY 4.0에서 재사용할 수 있습니다; 내장된 Poly Haven 텍스처는 CC0으로 유지됩니다. 참조하십시오 크레딧 및 라이선스 세부 사항.
배송 계약을 선택하세요
완전한 Package v2는 Locus 1.2.1 이상에서 모든 기능을 지원하는 권장 가져오기 형식입니다. ZIP 루트에는 다음이 직접 들어갑니다: locusplace.json 및 catalog/, 그리고 방은 아래에 산다 catalog/spaces/<space-id>/입니다. 안정적인 ID와 기존 설치 업데이트, 사운드, 애니메이션, 비디오 표면, 좌석 그룹, 현지화된 표시 텍스트, 출처, 지원되는 Room/View 조합 및 포함된 Experience에 사용하세요. 다음으로 빌드하세요: tools/pack_locusplace.py, 검증에는 다음을 사용하세요: tools/validate_locusplace.py, 그런 다음 대상 버전과 명시적으로 비어 있는 렌더 디렉터리를 지정하여 check_room.py 를 실행하고 좌석 렌더 연락처 시트를 검토합니다.
일반적인 제작에서는 룸과 함께 쓸 뷰를 따로 패키징하세요. 각각 자체 아카이브와 고정된 packageID. 이렇게 하면 각각 따로 배포하고 교체하고 제거할 수 있습니다. 함께 관리하려는 콘텐츠는 통합 Package v2 아카이브로 묶을 수도 있지만, 일반적인 룸 제작에서는 따로 패키징합니다.
기존 Room 빌드 도구와 골격 생성기는 아래의 레거시/단순 플랫 호환 형식을 의도적으로 생성합니다. 해당 패키징 및 검증 도구는 단순 가져오기에 여전히 유용하지만, 플랫 아카이브에는 완전한 패키지 전용 필드를 담을 수 없습니다. 플랫 가져오기마다 새 UUID가 부여됩니다.
legacy/simple 전달 계약
정확히 다섯 개의 루트 파일이 포함된 평평한 호환성 ZIP을 제공하십시오:
my-room.zip
├── space.json
├── provenance.json
├── teleport-points.json
├── scene.usdz
└── thumbnail.jpgscene.usdz자체적으로 독립적이며 미터 스케일이며, +Y 위로 올라가고, 세계 -Z를 전진으로 사용합니다.space.json룸을 설명합니다. 디스플레이 이름은 있지만 저작자 자산 ID는 없습니다; Locus은 모든 평면 임포트에서 새로운 UUID을 할당합니다.teleport-points.json적어도 하나의 사용 가능한 좌석을 선언합니다.provenance.json진실성 있는 기록 제작자, 권리, 크레딧, 변경 사항 및 AI 사용.thumbnail.jpgRoom과 공동 저작되었으며, Locus은 수입 시 이를 생성하지 않습니다.
수정 가능한 소스, 텍스처, 캐시 및 교환 파일을 ZIP 외부에 유지하십시오. 메타데이터에 참조된 모든 엔티티는 전달된 USDZ에 안정적이고 고유한 이름을 하나 가져야 합니다.
오픈 및 좌석
Locus 1.4.5 이전에는 모든 Room이 하나의 viewOpenings 항목을 하나 선언합니다. 1.4.5부터(플랫 ZIP에서는formatVersion: 11 또는 destinationOpenings , Package v2에서는 [x, y, z, w] 주문.
각 탈피트 포인트는 눈 위치와 방향을 정의합니다. anchorXZ 수출된 방 경계로 정규화됩니다; sourceFloorOffset 그 수준을 식별한다; eyeHeight 그 바닥에서 측정됩니다. 좌석 ID는 객실 인터페이스의 일부이므로 수정 사항에 따라 일관되게 유지해야 합니다.
옵션 공간 적응
spatialAdaptation USDZ의 의미 부분들을 Locus 기능과 연결합니다:
| 필드 | 계약 |
|---|---|
wallEntities | 검증된 벽 참조; 이들은 가상 벽을 숨기지 않거나 방 포털을 실행하지 않습니다. |
roofEntities | 유효한 지붕 또는 천장 참조; 이들은 가상 지붕을 숨기지 않습니다. |
deskEntitiesByTeleportID | 좌석 ID를 테이블톱 표면의 정확한 엔터티에 매핑합니다. 이 지도에서 제외된 좌석은 1급 라운지 좌석(소파, 데이베드, 벤치)입니다: 작성된 바닥과 눈높이에만 로딩되며 데스크 측정, 정렬 또는 패스스루를 받지 않습니다 — 근처의 커피 테이블을 데스크처럼 매핑하지 마세요. |
deskGroupEntitiesByTeleportID | 선택 사항, 1.1.5+. 이름, 이미 책상 뒷받침이 있는 좌석에 대해 deskEntitiesByTeleportID 입력, 전체 하위 구조가 해당 좌석의 숨겨진 책상인 유일한 엔티티이므로 Locus은 방문자에게 숨겨진 책상 제어를 제공할 수 있습니다. 명명된 엔티티는 고유하게 해제되어야 하며 책상 표면 엔티티의 조상이어야 합니다. 그렇지 않으면 방이 로드되지 않습니다. 이전 독자는 이 필드를 무시합니다. |
맵핑된 책상 엔티티는 책상 자체 또는 꽉 조여진 슬래브여야 합니다. 의자, 램프, 다리, 컴퓨터 또는 느슨한 소품을 아래에 포함하지 마십시오; Locus은 엔티티의 경계를 사용하여 표면 높이, 발자국 크기 및 방향을 도출합니다.
옵션 조명 인터페이스
조명 메타데이터는 Locus에게 수출된 발광 메시지와 경계된 실행 시간 소스가 각 방문자 대시보드 컨트롤에 속하는지 알려줍니다. 이는 방을 모델링, 조명 처리 또는 베이킹하는 방법을 규정하지 않습니다.
| 필드 | Locus 동작 |
|---|---|
luminaireGroups | 한 그룹은 하나의 논리 스위치와 하나의 밝기/색상 제어 세트입니다. |
entities | 발광 부착물 본체를 명명합니다. 활성화된 부착물은 모든 좌석에서 눈에 띄게 발광 상태로 유지됩니다. |
proxy / proxies | 경계된 점 또는 지점 소스를 선언합니다. 사용하다 proxies Room v3에서 하나의 스위치가 여러 개의 물리적 에미터를 구동할 때. |
nearTeleportIDs | 직접적인 프록시 소스를 선택한 좌석으로만 제한합니다; 다른 곳에서 피처 본체를 숨기거나 어둡게 하지 않습니다. |
bakedIndirect.entities | 저주파 간접 조명은 방 조명 마스터와 전반적인 방 EV에 의해 제어되는 Room v3 수신기 서브트리를 사용합니다. |
bakedIndirect.layers | 한 조명 그룹의 직접광과 반사광을 공유 수신 아틀라스에 기록하여 해당 그룹의 스위치, EV, 색상이 주변 표면에 반영되게 합니다. |
이전의 단순 평면 룸 형식은 다음을 사용합니다: formatVersion: 10. 권장하는 Package v2에서는, space.json 는 반드시 는 다음 값으로 유지하세요: formatVersion: 2. 다음을 설정하세요: lighting.bakedIndirect.layers 를 그곳에서 확인하고 이전 버전 번호를 복사하지 마세요.
독립적으로 제어하는 조명이 벽, 바닥, 테이블, 천장을 밝혀야 한다면 그룹별 베이크 레이어를 사용하세요. 각 그룹을 따로 베이크하고 기본 UV와 다음을 보존하세요: LocusIndirectUV 를 수신 아틀라스용으로 유지하고, 모든 그룹이 켜진 공유 아틀라스를 선형광 공간에서 합성하세요. 전환 가능한 조명의 빛을 항상 켜진 정적 공유 아틀라스에 넣거나 베이크된 조명 영역을 프록시로 중복 계산하지 마세요.
공유된 간접 레이어는 스케일링됩니다. 2^overallEV. 각 조명의 스위치, 색온도, 색상, 밝기는 해당 조명의 제어로 유지되며 기본 공유 반사광의 색은 바꾸지 않습니다. 유리, 물, 투과 재질, 조명 기구의 발광 메시, 특정 조명의 효과로 알아볼 수 있는 후광은 공유 간접광 수신 하위 트리에서 제외하세요. 국소적인 조명 영역은 직접광 프록시로 처리합니다.
Room v3는 최대 12개의 작성된 프록시, 모든 좌석에서 4개의 활성 프록시, 1개의 그림자 캐스팅 프록시, 프록시당 10,000루멘, 그리고 -4…+1 EV 범위의 밝기를 강제합니다. 이것들은 목표 값보다는 안전 제한입니다.
lighting 는 사용자가 제어하는 조명이 없는 룸에 사용합니다. 기본 조명 그룹은 Room v2, 룸 전체의 베이크된 간접광은 Room v3, 그룹별로 수신 표면을 바꿔야 할 때는 베이크 레이어를 사용하세요.옵션 TV
Locus 1.4.9 이상과 완전한 Package v2가 필요합니다. 플랫 호환 포맷에는 TV를 담을 수 없습니다.
룸은 TV를 최대 네 대까지 선언할 수 있습니다. 각 TV는 USDZ 안의 화면 하나를 가리킵니다. 화면은 독립된 평평한 16:9 사각형으로, 자체 UV를 가지며 이름으로 참조되는 다른 엔티티 아래에 중첩되지 않습니다. 그 머티리얼이 TV가 꺼졌을 때의 모습이며, 어두운 유리나 아트워크처럼 빛나지 않아야 합니다. 방문자가 TV를 켜면 Locus는 그 사각형 범위 안에 웹 페이지를 재생합니다.
당신의 소재 디자인을 보존하세요
Locus은 수출된 USDZ에서 지원되는 PBR 재료, 텍스처, UV 및 변환을 사용합니다. 이름과 같은 glass, 가구 크기 및 수입된 방 식별자는 재료 미리 설정을 선택하지 않습니다. 편집 가능한 소스에서 올바른 재료와 내보내기 문제를 해결한 후 Room ZIP을 다시 빌드합니다.
Room v5는 명시적인 것을 추가합니다. rendering.softenedReflectionEntities 및 rendering.uiFadeEntities. 수평 장면 디테일이 제거된 보기 반사 기능을 원할 때만 첫 번째를 사용하십시오; 이는 방 내부를 반영하지 않습니다. 두 번째를 사용하여 방문객 창문을 차단하는 동안 선택된 가구를 부드럽게 흐리게 할 수 있습니다. 생략된 역할은 이러한 동작을 모두 제공하지 않습니다.
모든 v5 스포트라이트가 유닛을 선언한다 direction 예를 들어 수출된 방 좌표에서 [0.6, -0.8, 0]. 고정점 공급 위치만 제공합니다. 이러한 필드는 v5 호환 Locus 빌드가 필요합니다. 사용하십시오 옵션 USD 모델 감사 수출된 참조 및 지원되는 셰이더를 확인하려면 읽어보세요. 지원 자료, 기본값 및 마이그레이션 규칙 내보내기 전에.
실험적인 주변 애니메이션
Room v4는 USDZ에 이미 내장된 애니메이션 클립을 명명된 방문자 컨트롤에 연결할 수 있습니다. 각각 ambientAnimations 진입은 하나의 엔터티와 하나의 애니메이션을 식별하고, 초기 스위치, 속도 범위 및 재생 간격 범위도 식별합니다.
방의 모든 실험 애니메이션을 방문자는 방의 움직임 Quick Controls의 타일. 안에 설정 → 모션 → 방 그들은 각 애니메이션을 전환하고, 실험 속도와 간격을 변경한 후, 현재 장치에서 해당 값을 이 방에 저장할 수 있습니다. 간격은 0–0 즉시 반복; 다른 최소 및 최대 값은 완료된 재생마다 새로운 무작위 정지를 선택합니다.
고급 Room 가이드
기본 USDZ, 개구부, 좌석이 동작하면 Package v2의 최신 Room 기능 가이드와 레퍼런스로 바로 이동하세요:
가장 작은 작동하는 방을 만드세요
그 최소한의 방 빌더 빈 Blender 장면에서 시작하여 책상 하나, 교정된 좌석 하나, 벽 두 개, 지붕 하나, 제어된 펜던트 하나를 생성합니다. macOS 에서 Blender 5.2와 Python 3이 필요합니다. 빌더가 번들된 메타데이터 스캐폴더를 사용할 수 있도록 이 리포지토리를 복제하거나 다운로드하세요. 외부 모델, 텍스처 또는 MCP 연결이 필요하지 않습니다.
- 저장소 루트에서 빌더를 실행하고 이미 존재하지 않는 출력 경로를 사용하십시오. 이는 편집 가능한 Blender 파일, 자체 포함된 USDZ 파일, 썸네일 및 여섯 개의 좌석 리뷰 이미지를 저장합니다.
- 각 이미지를 검사하십시오
review/. 스케일, 좌석 방향, 간격 또는 테이블톱 사용성이 잘못된 경우 출처를 수정하십시오. - 공개 패커와 검증기를 실행한 다음 정확한 ZIP을 통해 가져옵니다. 장소 → 가져오기 → 방 가져오기 → 파일.
- 선택 최소 독서실 Places에서 View와 함께 연결하고 가상 공간을 입력하세요. Reading Desk 좌석, Quick Controls의 방 조명 타일을 사용해 보세요, 그리고 조명 및 사진 → 방. 실제 테이블 정렬 및 편안함에는 Apple Vision Pro이 필요합니다.
blender --background --factory-startup --python-exit-code 1 \
--python tools/build_minimal_room.py -- \
--output /absolute/path/to/minimal-reading-room
python3 tools/pack_locus_asset.py \
/absolute/path/to/minimal-reading-room/room \
/absolute/path/to/minimal-reading-room.zip
python3 tools/validate_locus_asset.py /absolute/path/to/minimal-reading-room.zipBlender 실행 파일의 절대 경로를 사용하는 경우 blender PATH에 없습니다. 빌더와 패커는 기존 출력을 덮어쓰기를 거부합니다. 편집 가능한 소스를 유지하고 다섯 파일 ZIP 외부에서 이미지를 검토하십시오. 그 완전한 실행 시간 상호작용 참조 좌석, 안전성, 충돌 기록, 측정된 품질, 데스크 매핑 및 저자 권한이 앱과 어떻게 연결되는지 설명합니다.
패키지, 검증한 다음 호환성 ZIP을 수입합니다.
완전한 Package v2 Room에는 다음을 사용하세요: 완전한 패키지 가이드 및 도구를 사용하세요. 다섯 원본 파일을 한 디렉터리에 모으고 macOS 에서 기존 공개 플랫 형식 도구를 실행하세요:
python3 tools/pack_locus_asset.py /absolute/path/to/room /absolute/path/to/my-room.zip
python3 tools/validate_locus_asset.py /absolute/path/to/my-room.zip- USDZ 수출업체 및 공개 검증기에서 발생하는 모든 경고 또는 오류를 해결합니다.
- Locus에서 선택하십시오 룸 가져오기 그리고 정확하게 검증된 ZIP을 선택하십시오.
- Apple Vision Pro에서 방과 전망을 연결하고 들어가세요.
- 선언한 모든 좌석, 선택적인 데스크 매핑, 렌더링 역할 및 조명 제어를 시도해 보세요.
- 소스 코드를 수정하고 ZIP을 다시 빌드하십시오; 최종 아카이브를 직접 패치하지 마십시오.
AI 어시스턴트와 함께 빌드
ChatGPT, 다른 이미지 모델 또는 자신의 참고 자료로 만든 콘셉트 이미지에서 시작하세요. 에이전트에 평면도와 좌석 배치를 요청한 다음 이미지와 도면을 모두 바탕으로 모델링하고, 모든 좌석을 검토하고, 공개 도구로 정확한 Package v2 아카이브를 검증하게 하세요. Apple Vision Pro에서 가져오고 구체적인 피드백을 보내 반복하세요. 4단계 Room 튜토리얼 는 Locus 애플리케이션 소스 코드나 Simulator에 접근하지 않고 이 워크플로를 단계별로 설명합니다.
Blender와 Xcode 또는 해당 Command Line Tools가 설치된 Mac을 사용하세요. 에이전트는 내보낸 모델에서 좌석을 도출하고 수정본을 위해 안정적인 ID를 유지합니다. 모든 이미지 모델은 선택 사항이며 API 키가 필요하지 않습니다. 원한다면 다른 전문 3D 워크플로를 계속 사용해도 됩니다.
에이전트는 재현 가능한 스크립트와 렌더를 저장하고 이미지를 검사하며 Room을 수정합니다. 명시적인 렌더 디렉터리로 check_room.py 를 실행하고 연락처 시트를 검토하며 아카이브 SHA-256과 남은 기기 검사를 보고해야 합니다.
헤드리스 저작에도 시각 검토가 포함됩니다. 저장된 렌더는 에이전트가 모델링 및 재질 문제를 찾도록 돕지만, 최종 Apple Vision Pro 미리보기는 Locus에서 Room이 어떻게 보이고 느껴지는지 확인합니다. 정확히 검사한 아카이브를 가져와 Preview in 3D를 사용하고 View와 연결한 다음 모든 좌석, 조명 제어 및 Hide Desk를 시도합니다. 적절한 3D 도구를 조작하거나 이미지를 검사할 수 없다면 에이전트는 미완성 작업을 설명해야 합니다.