Choose your approach

Day-and-night Views build on environment.sunPath inside a complete Package v2 archive (the flat compatibility view.json ZIP does not support these fields). The manifest below follows Chalk Dune Dawn (destination.chalk-dune-dawn 1.4.0), a 12K gypsum-dunes View pairing full-frame day and night panoramas, procedural clear sky, stars/Milky Way, and sun-lit 3D midground dunes.

Study the Chalk Dune Dawn example. Download destination.chalk-dune-dawn-1.4.0.locusplace (123.9 MB ZIP under the Locus Example License; also listed in place-examples.json). Needs Locus 1.4.10 / 1.5.0 or later and joins the public Gallery once Locus 1.5.0 is live on the App Store.
ApproachMinimum AppWhat you author
Atmosphere + graded land (daySky, panoramaGrade, light)1.4.9One sun-free daytime panorama, a sky.mask separating sky from foreground, plus elevation stops that tint the painted land and drive Room sunlight.
Full-frame day/night panorama pair (+ panoramaBlend)1.4.10Adds an aligned full-frame night panorama and astc-6x6-srgb KTX1 gpuTextures v2 sidecars for both panoramas so mountains, snow, or distant shorelines shift to real night lighting.
With computed shore or media.dayNight1.4.11Lets a computed surf beach or video region maps follow the same day/night blend.
Why sky and daySky are part of the contract. In the current Package v2 specification, panoramaBlend requires both environment.sunPath.daySky and root sky (with sky.mask and stars or moon). White pixels in sky.mask show the rendered day atmosphere and night stars/Milky Way; black pixels show your blended day and night panorama images.

1 · Prepare

Prepare the images and masks

Using your own painted sky instead of Locus’s procedural sky. Paint sky.mask completely black (0) while keeping root sky and daySky declared as required. Because black in sky.mask keeps your panoramas opaque, Locus hides the rendered blue sky, stars, and Moon while preserving the 24-hour clock, Edit View Sun Position scrubbing, panoramaBlend transitions, panoramaGrade, and dynamic Room/midground lighting. Omit environment.sunPath.disc (or pass the all-black mask to disc.skyMask) to hide the solar disc and glare as well, or supply a separate white-sky disc.skyMask if you still want the moving sun disc.

2 · Manifest

Write destination.json and provenance

Set minimumAppVersion in locusplace.json to "1.4.9" (without panoramaBlend), "1.4.10" (with panoramaBlend), or "1.4.11" (when pairing panoramaBlend with shore or media.dayNight).

In destination.json, every sunPath View must set "sunFreeSky": true and include a "sun-free-sky" component in provenanceDetail:

{
  "formatVersion": 2,
  "id": "destination.chalk-dune-dawn",
  "title": "Chalk Dune Dawn",
  "panorama": {
    "path": "panorama.jpg",
    "projection": "equirectangular",
    "width": 12288,
    "height": 6144,
    "initialYawDegrees": -50
  },
  "thumbnail": "thumbnail.jpg",
  "provenance": "provenance.json",
  "provenanceDetail": {
    "formatVersion": 1,
    "components": [
      {
        "component": "picture",
        "aiGenerated": true,
        "providers": ["Google Gemini", "OpenAI"],
        "credit": "Locus",
        "notes": "Procedural terrain with silhouette-locked horizon detail and night relighting."
      },
      {
        "component": "sun-free-sky",
        "aiGenerated": false,
        "notes": "Azimuth-symmetric clear sky and IBL with no painted sun disc or glare."
      }
    ]
  },
  "sky": {
    "mask": "sky-mask.png",
    "stars": {
      "twilight": {"strength": 0},
      "milkyWay": {"style": "realistic"}
    }
  },
  "midground": {
    "path": "midground.usdz",
    "terrainEntities": ["Terrain_Dunes", "Terrain_Pan"]
  },
  "gpuTextures": [
    {
      "source": "panorama.jpg",
      "path": "panorama.ktx",
      "format": "astc-6x6-srgb",
      "width": 12288,
      "height": 6144,
      "mipmapLevels": 14,
      "sourceSHA256": "e938e8f8c88f868ed39ec39a3c67c60da2e11281b09f59d79a0953cf8e91154d"
    },
    {
      "source": "panorama-night.jpg",
      "path": "panorama-night.ktx",
      "format": "astc-6x6-srgb",
      "width": 12288,
      "height": 6144,
      "mipmapLevels": 14,
      "sourceSHA256": "efc8fda539be7d867b2181cb8a891f61316ba84d9120d31c62bbad5f96a95e57"
    }
  ],
  "environment": {
    "imageBasedLight": "lighting-ibl.jpg",
    "sunPath": {
      "sunFreeSky": true,
      "startHour": 6.35,
      "dayDurationSeconds": 7200,
      "maxElevationDegrees": 55,
      "peakIlluminanceLux": 2900,
      "nightIlluminanceLux": 0,
      "disc": {
        "skyMask": "sun-sky-mask.png",
        "angularSizeDegrees": 0.53,
        "intensity": 1
      },
      "daySky": {"haze": 0.3, "exposure": 1},
      "panoramaGrade": {
        "stops": [
          {"elevationDegrees": -18, "color": [0.015, 0.014, 0.011]},
          {"elevationDegrees": 0,   "color": [0.245, 0.198, 0.145]},
          {"elevationDegrees": 14,  "color": [0.785, 0.588, 0.36]},
          {"elevationDegrees": 55,  "color": [1.225, 1.108, 0.932]}
        ]
      },
      "light": {
        "stops": [
          {"elevationDegrees": -18, "color": [0, 0, 0],        "ambientEV": -2.75},
          {"elevationDegrees": 0,   "color": [1.25, 0.6, 0.18], "ambientEV": 0.2},
          {"elevationDegrees": 14,  "color": [1.38, 0.97, 0.56], "ambientEV": 0.16},
          {"elevationDegrees": 55,  "color": [0.96, 0.92, 0.85], "ambientEV": -0.35}
        ],
        "midground": true
      },
      "panoramaBlend": {
        "path": "panorama-night.jpg",
        "dayElevationDegrees": -1,
        "nightElevationDegrees": -12,
        "nightGrade": [1, 1, 1]
      }
    }
  }
}

3 · Calibrate

Tune elevation stops and blend thresholds

4 · Verify

Pack, validate, and inspect across hours

python3 tools/pack_locusplace.py --current-app-version 1.4.11 \
  /absolute/path/to/MyDayNightView /absolute/path/to/MyDayNightView.locusplace

python3 tools/validate_locusplace.py --current-app-version 1.4.11 \
  /absolute/path/to/MyDayNightView.locusplace

The validator checks every manifest constraint, verifies both gpuTextures v2 KTX1 headers and SHA-256 digests, and runs sun_free_sky_check to catch bright solar discs left in the day panorama or IBL.

  1. Import on Apple Vision Pro via Places → Import → Import a View → Files and pair the View with a Room.
  2. Scrub Sun Position in Edit View through morning, noon, golden hour, twilight, and midnight to check horizon silhouettes, Room glass reflections, and painted-to-sky edge masks.
  3. Check Motion Off / Reduce Motion: confirm the View freezes cleanly at startHour.

Coexistence rules and limits