技術參考

完整 Locus Package v2 製作指南

狀態：正式的發佈、存儲、組合及完整功能導入契約。Locus 1.2.1 及以上版本可通過文件或公開 HTTPS URL 導入此歸檔，用於 View 和 Room。舊的扁平格式見 locus-asset-format.md 仍可作為兼容輸入。

一個 .zip 或 .locusplace 文件是一個普通 ZIP 歸檔，包含一個或多個 Package v2 Destination（產品名稱為 View）、Space（Room）及 Experience。Locus 自身和支持完整功能的可移植包均使用這一安全發佈與完整性封裝。ZIP 根目錄包含 locusplace.json 和 catalog/ 直接放置，不要再套一層父目錄。

校驗基于歸檔字節與 manifest，而非文件擴展名。完整包會保留其 packageID、內容 ID、 contentVersion 更新流及受支持的 Experience；導入相同內容哈希時為冪等操作，不產生變化。維護中的打包器和校驗器會生成並檢查這一確切格式。

此外層封裝只承載數據，不承載可執行擴展。對於同一個 Locus 二進制文件，運行時使用的每項 Package v2 能力，無論歸檔是內置、從 Library 下載，還是從文件或 URL 導入，內容語義都相同。來源可能影響使用權、自定義導入額度、更新權限、存儲、移除及 UI 標籤，但不會啓用另一套 Room/View schema 或渲染功能。腳本、插件、動態庫及可執行成員不屬於此格式。所有來源均遵守相同的路徑隔離、完整性、資源預算、結構解碼、引用閉合及最低版本檢查。

本指南介紹完整外層封裝及基礎 manifest。 字段參考 介紹可選的 View 與 Room 能力、相關資產、取值範圍及最低 app 版本。 外層封裝 schema 和 來源信息 schema 描述 JSON 的結構；打包器與校驗器還會檢查文件字節和跨字段規則。單憑 JSON Schema 無法校驗歸檔，也無法證明它在 Apple Vision Pro 上的體驗舒適。

從可用的完整包開始

克隆或下載 公開工具倉庫。在 macOS 上從該倉庫根目錄運行以下命令，需要 Python 3.9 或更高版本，以及安裝有 Xcode 並提供以下工具： xcrun usdchecker 和 xcrun usdcat。基礎校驗使用 Python 標準庫、 /usr/bin/sips 完成完整圖像解碼，並使用 Xcode 的 usdchecker 和 usdcat 處理模型。高級雲層、水體反射與接觸、無太陽天空檢查還需要 NumPy 和 Pillow： python3 -m pip install numpy pillow.

python3 examples/locusplace/build_examples.py /absolute/path/to/locusplace-examples
python3 tools/validate_locusplace.py --current-app-version 1.4.4 /absolute/path/to/locusplace-examples/view-only.locusplace
python3 tools/validate_locusplace.py --current-app-version 1.4.4 /absolute/path/to/locusplace-examples/room-only.locusplace
python3 tools/validate_locusplace.py --current-app-version 1.4.4 /absolute/path/to/locusplace-examples/combined.locusplace

目標目錄必須不存在或為空。這些小型合成示例用於驗證格式；漸變圖和立方體並非生產級場景或成品 Room。其源碼與生成內容採用 Apache-2.0 許可。參見 示例說明.

--current-app-version 指定本次校驗的目標 Locus 版本，校驗將以此 為準；它不會升級已安裝的 App，也不會賦予 App 新能力。工具保守地默認為 1.0.0；請明確指定目標版本。完整包導入要求 Locus 1.2.1 或更高版本，新字段還受各自最低版本限制。Room 的地面和中景控制要求支持這些字段的 1.4.4 或更新構建；本指南不表示該構建已經在 App Store 上架。

製作自己的包時，可將示例解壓到可編輯文件夾，或按下方結構創建目錄。替換資產與來源信息，使用自己的穩定 ID，並將輸出歸檔保存到 該文件夾之外的 路徑：

python3 tools/pack_locusplace.py --current-app-version 1.4.4 MyEditablePlace MyPlace.zip
python3 tools/validate_locusplace.py --current-app-version 1.4.4 --json MyPlace.zip

打包器會重新計算 files 和 contentHash，校驗歸檔後才生成輸出文件。它拒絕覆蓋已有輸出，並保持可編輯源文件不變。通過以下入口導入結果： Places → 導入 → 導入 View 或 導入 Room → 文件，選擇與包內內容類型相符的導入入口。組合包會一起安裝其中的內容，也可通過直接指向 ZIP 的公開 HTTPS URL 導入。分享成品前，請在 Apple Vision Pro 上檢查每個座位、效果、燈光和聲音。

歸檔結構

example.locusplace
├── locusplace.json
└── catalog/
    ├── destinations/<destination-id>/
    │   ├── destination.json
    │   ├── provenance.json
    │   └── ...
    ├── spaces/<space-id>/
    │   ├── space.json
    │   ├── provenance.json
    │   └── ...
    └── experiences/<experience-id>/
        └── experience.json

除根目錄的 locusplace.json 以外，所有非目錄項都必須列入 files中。每個已聲明文件都必須存在。歸檔只能包含規定的三個目錄集合，每個文件都必須位於 contents中聲明的包 ID 對應目錄內。Package-v2 清單可向前兼容未知字段；但未知的封裝清單字段、不支持的格式版本、集合及內容模式會被安全拒絕。來源信息遵循其已公開的格式規範。

僅含 View 或僅含 Room 的歸檔會安裝可復用的目錄內容。目錄解析後，Locus 會生成默認配對：每個 View 與“你的房間”配對，也與每個聲明 View 開口的 Room 配對。顯式 Experience 僅替換其指定配對，可引用同一歸檔內的內容，或內置／已導入目錄中已有的穩定 ID。

locusplace.json

{
  "formatVersion": 1,
  "packageID": "place.example-combined",
  "contentVersion": "1.0.0",
  "minimumAppVersion": "1.0.0",
  "contents": {
    "destinationIDs": ["destination.example-view"],
    "spaceIDs": ["space.example-room"],
    "experienceIDs": ["experience.example-combined"]
  },
  "files": [
    {
      "path": "catalog/destinations/destination.example-view/destination.json",
      "byteCount": 214,
      "sha256": "<64 lowercase hex characters>"
    }
  ],
  "contentHash": "<64 lowercase hex characters>"
}

packageID 以及所有內容 ID 都是最長 128 字節的穩定 ASCII 標識符。必須以字母或數字開頭，之後只能使用字母、數字、 ., _，以及 -。版本號恰好由三個數字分量組成。若更新改變了字節內容，必須保留原先聲明的內容 ID，並提高 contentVersion。再次導入相同的 contentHash 為冪等操作，不產生變化。

contentHash 對按 Unicode 路徑排序的所有文件記錄計算 SHA-256。每條記錄貢獻以下 UTF-8 字節：

path NUL decimal-byteCount NUL lowercase-sha256 NUL

此哈希不受 JSON 空白及 ZIP 成員順序影響。校驗器還會流式覈實每個聲明文件的實際字節數、ZIP CRC 和 SHA-256。

封裝清單字段參考

ZIP 內的 Package v2 元數據

完整外層封裝使用 formatVersion: 1；每個 destination.json, space.json 和 experience.json 使用 formatVersion: 2。以下參考中的 Room v1–v10 編號 扁平兼容格式參考 屬於獨立的扁平格式 space.json 輸入。不要修改完整包的 space.json 設為版本 10 來使用烘焙光照層。在完整包中，可選能力由其有類型定義的字段啓用，最低版本要求則由以下字段限定： minimumAppVersion.

包內資源路徑均相對於清單所在目錄，而非 ZIP 根目錄。每個引用都必須解析為該包內的普通文件。基礎 Package-v2 清單允許向前兼容的元數據，但單個能力配置可能採用封閉字段集。不要假設未知字段會被渲染。外層封裝清單拒絕未知字段，來源信息須遵循已公開的格式規範。

坐標採用右手系，單位為米，+Y 向上、−Z 向前。四元數順序為 [x, y, z, w]。變換可包含 translationMeters （三個有限數值）、 orientationXYZW （四個有限數值組成的非零長度四元數），以及 scale （三個有限正數）。

View： destination.json

{
  "formatVersion": 2,
  "id": "destination.example-view",
  "title": "Example View",
  "panorama": {
    "path": "panorama.jpg",
    "projection": "equirectangular",
    "width": 8192,
    "height": 4096,
    "initialYawDegrees": 0
  },
  "provenance": "provenance.json"
}

完整 ZIP 接受該 App 版本實際使用的字段，以及明確保留的元數據，例如 sourceImage；前提是能驗證資源類型及其是否符合資源預算。 midground 屬於公共運行時契約，要求 minimumAppVersion >= 1.2.1. depthLayers, splat，以及舊版 audio 塊仍為預留或已停用，當前沒有運行時使用方。因此當前二進制文件會對所有來源拒絕這些內容，而不會接受未經類型校驗的路徑。後續二進制文件實現某項能力時，必須將該字段的資產引用、類型與預算檢查、運行時使用方及最低 app 版本一並加入公共契約，不得另設公開導入開關。

推薦 12,288×6,144（12K），但這不是強制要求。 較低的分辨率，例如 8,192×4,096、6,144×3,072 或 4,096×2,048，只要嚴格為 2:1 並聲明真實解碼尺寸，也都是有效的。不要僅為標稱 12K 而放大小尺寸源圖：這不會增加細節，只會浪費內存。

全景坐標固定如下： u = 0.5 對應 yaw 0，即初始正前方／世界 −Z； u 向東、即 +X 方向遞增；接縫位於 u = 0/1，對應 yaw ±180°；圖像最上方一行是天頂。 initialYawDegrees 在此坐標系內旋轉圖像，不會重新定義坐標系。

可選 View 光照：

{
  "environment": {
    "imageBasedLight": "thumbnail.jpg",
    "skyGainEV": 0,
    "exposureEV": 0,
    "horizonPitchDegrees": 0,
    "colorGrade": {"contrast": 1.15, "saturation": 1.2},
    "directSun": {"enabled": false, "illuminanceLux": 5000}
  }
}

調色只影響顯示的 SDR 全景圖。它復用原圖紋理，不會把 View 轉換成 HDR，也不會補回源圖缺失的高光細節。關閉的太陽仍可保存 5000 lux，使得 添加陽光 從 app 默認值開始，不改變包中作者設定的關閉狀態。

visibleSkyHDR 和 hdrManifest 已停用，會被拒絕。外層包中的 EXR 不可作為可見 View 或 Room 光照圖。OpenEXR 仍可作為 Room 資產的 USDZ 紋理格式，並在模型內部校驗。

Room： space.json

{
  "formatVersion": 2,
  "id": "space.example-room",
  "title": "Example Room",
  "scene": "scene.usdz",
  "thumbnail": "thumbnail.jpg",
  "caption": "A quiet house arranged around a sunlit courtyard.",
  "previewCamera": {
    "yawDegrees": -28,
    "pitchDegrees": -10,
    "zoom": 1.0
  },
  "seatedOrigin": {
    "translationMeters": [0, 0, 0],
    "orientationXYZW": [0, 0, 0, 1]
  },
  "safeHeadVolume": {
    "centerMeters": [0, 1.2, 0],
    "sizeMeters": [1.2, 0.6, 1.2]
  },
  "destinationOpenings": [
    {
      "id": "front",
      "transform": {
        "translationMeters": [0, 1.2, -2],
        "orientationXYZW": [0, 0, 0, 1]
      },
      "widthMeters": 4,
      "heightMeters": 2.5
    }
  ],
  "collision": {"mode": "embedded"},
  "teleportCatalog": {"path": "teleport-points.json", "houseID": "example-room"},
  "quality": {
    "status": "unverified",
    "triangleCount": 0,
    "materialCount": 0,
    "entityCount": 0,
    "maxTextureDimension": 0
  },
  "provenance": "provenance.json"
}

USDZ 使用米制、右手坐標系、+Y 朝上，且僅包含受支持的運行時 USD、紋理與音頻成員。USDZ 成員必須以存儲方式寫入，不得壓縮。校驗器會加載並展平真實 stage，統計幾何體；即使 quality 值很小或為零，也無法掩蓋超預算模型。

必填傳送點 JSON（選中的房屋必須至少有一個點）：

{
  "houses": {
    "example-room": [
      {
        "id": "work-desk",
        "title": "Work desk",
        "anchorXZ": [0.5, 0.5],
        "sourceFloorOffset": 0,
        "eyeHeight": 1.15,
        "yawRadians": 0
      }
    ]
  }
}

anchorXZ 是兩個有限的歸一化數值，範圍為 0...1; sourceFloorOffset 以作者模型單位計量，必須有限且非負； eyeHeight 以米計量，必須有限且為正； yawRadians 是在世界坐標系中繞 +Y 的有限模型旋轉角。點 ID 必須唯一，標題不得為空。

Experience： experience.json

{
  "formatVersion": 2,
  "id": "experience.example-combined",
  "title": "Example Room · Example View",
  "destinationID": "destination.example-view",
  "spaceID": "space.example-room",
  "supportedModes": ["virtual-space"],
  "composition": {
    "destinationOpeningID": "front",
    "destinationYawDegrees": 0,
    "destinationPitchDegrees": 0,
    "destinationExposureOffsetEV": 0
  },
  "compatibility": {
    "minimumViewerVersion": "1.0.0",
    "requiredCapabilities": ["world-tracking"]
  }
}

純 View 和純 Room ZIP 會安裝可復用內容，並加入默認組合矩陣。只有需要覆蓋某個組合的開口、朝向、曝光、標題、模式或兼容性時，才需要顯式 Experience。引用可指向同一歸檔內的內容，或內置及已安裝的穩定 ID；任何無法解析的引用都會使整個導入失敗。

可選能力與翻譯標籤

將可選字段寫入其所屬 View 或 Room 的清單，並把每個引用資源放在相應清單旁。 字段參考 涵蓋媒體與蒙版、聲音及 Room 音樂、中景與風、水體、天空、雲層、太陽路徑、天體、近軌道、黑洞、點光源、GPU 輔助紋理、座位與分組、燈光、動畫、視頻表面、粒子及烘焙光照層。它也定義了 localizations, provenanceDetail，以及 Room 的 viewGroundFloorOffsetMeters, viewGroundKeepOut，以及 viewMidgroundVisibility 控制項。

例如，以下可選字段應放入其他內容已完整的 Room manifest 中，並要求外層封裝的 minimumAppVersion: "1.4.4" 或更高版本：

{
  "viewGroundFloorOffsetMeters": 0.2,
  "viewGroundKeepOut": false,
  "viewMidgroundVisibility": "terrainOnly"
}

這些字段在導入、內置和 Library 內容中含義相同。字段參考中的 Library 能力名稱屬於 Library offer；不要將自行編造的 requiredCapabilities 字段添加到 locusplace.json。完整包導入流程會檢查最低 App 版本和實際的類型化內容。

必填來源信息

每個導入的 Destination 和 Space 都指向來源 JSON 文檔，記錄作者或機構、許可或保留所有權利聲明（二選一）、要求的署名、修改說明、是否使用 AI，以及適用時的 AI 提供方。來源頁面／原始資源 URL 可選，但必須為 HTTPS，且不含憑據或片段。來源信息缺失、超出大小限制或格式錯誤都會使整個導入失敗。參閱 來源信息參考.

{
  "formatVersion": 1,
  "creatorOrAgency": "Your name or studio",
  "sourcePageURL": "https://example.com/project",
  "originalAssetURL": "https://example.com/original",
  "license": {
    "identifier": "YOUR-LICENSE-ID",
    "name": "Your license name",
    "url": "https://example.com/license"
  },
  "requestedCredit": "Credit line requested by the creator",
  "modificationNotes": "Converted and packaged for Locus.",
  "aiGenerated": false
}

該文檔限 64 KiB。替換資產後，不要繼續使用入門示例的來源信息。倉庫許可與用戶資產許可是兩項獨立聲明。

ZIP 用於運行時交付，不是製作源文件備份。每個載荷文件都必須能從已識別的 Package v2 資產字段引用到；無引用文件一律拒絕，即使它們已列在 locusplace.json.files. .blend, .blend1, .blend2, .fbx, .obj, .mtl, .gltf，以及 .glb 文件即使已聲明也會被拒絕。這些源文件應保留在 ZIP 之外。Room 交付最終 USDZ；打包 View 交付最終 2:1 全景，以及可選的一張小型 2:1 JPEG/PNG Room 光照圖。

安全與資源預算

校驗檢查實際字節，不靠擴展名。它會拒絕路徑穿越、絕對路徑或非規範路徑、反斜槓、控制字符、大小寫或 Unicode 衝突、符號鏈接、重復條目、加密內容、未聲明文件、哈希不匹配、不受支持的 manifest、損壞圖像、USDZ 內無效 EXR 紋理、損壞的 USDZ 結構、壓縮的 USDZ 成員及不受支持的 USDZ 資產類型。Room 預算基於系統加載器實際解析的 USD stage 檢查；作者自報的質量信息只是製作元數據，無法降低這些統計值。

字節級圖像允許清單是嚴格限定的：導入的全景、 sourceImage, thumbnail，以及 imageBasedLight 柵格圖像字段僅允許 JPEG 或 PNG；USDZ 紋理可用 JPEG、PNG 或 OpenEXR。不會隱式接受其他 ImageIO 可解碼格式。外層包中的 3D 製作格式也會被拒絕。USDZ 僅允許包含 USD/USDA/USDC、JPEG、PNG、OpenEXR、M4A、WAV 和 MP3 成員。

文件和 URL 導入

導入 View 時，可以從照片、文件或公開的直接 HTTPS URL 選擇一張 JPG、PNG 或 HEIC。Locus 會將圖像規範化為僅含 Destination 的 Package v2，並通過同一個校驗器和原子安裝流程處理這個臨時包。文件和 URL 也支持完整的 Package v2 ZIP，可用於 View、Room，以及包含訪客所選內容類型的組合包。現有扁平 View/Room ZIP 仍可作為兼容輸入。如果格式錯誤的歸檔包含 locusplace.json ，會被視為無效完整包而拒絕，絕不會回退到扁平解析器。URL 導入拒絕憑據、片段、localhost、 .local及非公網 DNS 解析結果。每次請求只解析一次主機名，所有返回地址都必須是公網地址。TLS 連接會連接到解析得到的確切數字 IP，同時驗證原始主機名。每次重定向都會在建立新連接前重新解析並固定地址，最多跟隨五次重定向；聲明大小和實際流式下載大小都受到限制。

校驗與目錄解析在同一卷的私有暫存目錄內完成。整個庫的咨詢鎖會串行處理清單、配額檢查及提交。首次安裝使用排他的原子重命名，更新使用原子目錄交換。任何失敗都會移除暫存內容，並保持已安裝包不變。

包校驗與示例

以下命令維護髮布及完整功能導入所用的完整 Package v2 外層封裝。舊扁平格式工具仍記錄在 locus-asset-format.md.

無需安裝即可校驗任意一種文件名：

python3 tools/validate_locusplace.py --current-app-version 1.4.4 MyPlace.locusplace
python3 tools/validate_locusplace.py --current-app-version 1.4.4 MyPlace.zip
python3 tools/validate_locusplace.py --current-app-version 1.4.4 --json MyPlace.locusplace

Python 代碼使用標準庫、通過以下方式調用的 macOS ImageIO： /usr/bin/sips，以及 USD 工具 usdchecker 和 usdcat （隨 Xcode／命令行工具安裝）。完成 JPEG 或 PNG 結構校驗後，ImageIO 會解碼全部像素；EXR 校驗僅用於 USDZ 內部的紋理。USD 工具會加載實際的房間 USD 場景、展開其圖層並測量幾何數據。任何校驗失敗都會返回非零退出碼。檢查範圍涵蓋歸檔、完整性、Package-v2、來源信息、圖像／EXR 和 USDZ。安裝及跨目錄引用解析仍以 visionOS 導入器為準。

將可編輯目錄打包為普通 ZIP，重新計算所有完整性記錄，並僅在校驗器接受結果後輸出：

python3 tools/pack_locusplace.py --current-app-version 1.4.4 MyEditablePlace MyPlace.zip

在臨時目錄或已忽略的目錄中生成真實的純 View、純 Room 和組合示例歸檔，然後校驗：

python3 examples/locusplace/build_examples.py /tmp/locusplace-examples
for package in /tmp/locusplace-examples/*.locusplace; do
  python3 tools/validate_locusplace.py --current-app-version 1.4.4 "$package"
done

示例從源代碼生成，無須下載私有資產或調用付費服務。構建器與預期目錄結構記錄在 示例 README.