PanoShard Documentation

Quick Start

After importing PanoShard from the Unity Asset Store, the Home Window opens automatically. These six steps take you from a raw 360° image to a playable tour.

1. 1
   Download the splitter

   Open Tools → PanoShard → Split → 360 Images. On first run, accept the one-time download of the platform-native splitter executable — it is required for panorama processing and is verified with a SHA-256 integrity check.

2. 2
   Verify dependencies

   In the Home Window's Package Check tab, install com.unity.nuget.newtonsoft-json if it is missing. PanoShard tracks this for you.

3. 3
   Split your first panorama

   Convert a single equirectangular (2:1) image into a streamed tile set written under StreamingAssets/.

4. 4
   Create a Tour Graph

   Right-click in the Project window → Create → PanoShard → Tour Graph. This ScriptableObject is the central data structure for your tour.

5. 5
   Add a start location

   Open the graph, add a Location node, tick Is Start Location, and assign the tiles folder you created in step 3.

6. 6
   Auto-setup the scene

   Run Tools → PanoShard → Scene → Automatic Setup, assign your Tour Graph to the TourManager, and press Play.

Splitting 360° Images

The Splitter converts an equirectangular panorama into a hierarchical tile grid. At runtime, only the tiles inside the camera frustum at the current zoom level are streamed — this is the core performance strategy behind PanoShard.

1. 1
   Pick a mode

   Use External Process (native executable) for large 16K+ images and production. Use Native (in-editor C#) for quick iterations on smaller panoramas.

2. 2
   Set input & output

   Drag in the source image and name the output sub-folder under StreamingAssets/. Leave the output blank to derive it from the file name.

3. 3
   Choose tile size & max level

   Keep Tile Size 512. Set Max Level to match how deep you want to zoom — each level doubles the grid (L1 = 2×1, L2 = 4×2, L3 = 8×4…).

4. 4
   Pick a format

   KTX is recommended (GPU-compressed, low VRAM). Use JPEG for the widest platform compatibility.

5. 5
   Run the split

   Process a single image or queue several with + Add Source Image for a sequential batch sharing the same settings.

StreamingAssets/{OutputFolder}/
  metadata.json
  ktx2/ level_0/0/0.ktx2  level_1/...  level_N/...
  jpg/  level_0/0/0.jpg   ...

Building the Tour Graph

The Tour Graph Editor is a UI Toolkit node editor (like Shader Graph) for laying out your tour visually. Locations are nodes; navigation paths are connections between them.

1. 1
   Open the editor

   Double-click the Tour Graph .asset, or select it and click Open in the Inspector.

2. 2
   Add location nodes

   Add one node per 360° location via the toolbar or right-click menu. Use the Pick… button next to Tiles Folder to auto-fill the folder and extension from your tiles.

3. 3
   Configure each location

   Set the Title, opening camera angles, FOV/pitch limits, and detail-level range. Match Max Detail Level to the splitter's max level.

4. 4
   Connect locations

   Drag from one node's output port to another's input. Choose a direction — AtoB, BtoA, or Both — to control which transition hotspots appear where.

Placing Hotspots

Open the Hotspot Editor from any node's [Hotspots] button. It shows the actual panorama so you place interactive elements by clicking directly on the image.

1. 1
   Open the panorama viewer

   Click [Hotspots] on a location node. Pan and zoom the equirectangular image (JPG, PNG, or KTX2 supported).

2. 2
   Choose a type and click to place

   Pick a hotspot type from the selector, then click on the panorama to drop it at that 3D world direction. Drag to reposition.

3. 3
   Configure per hotspot

   Use the per-hotspot inspector to set targets, text, URLs, icon, and scale.

Guided Tours

Layer a curated, step-by-step narrative on top of your free-roam graph. Users follow a predetermined path with custom camera angles, restricted movement, and on-screen instructions.

1. 1
   Create the data asset

   Right-click → Create → PanoShard → Guided Tour and assign your Tour Graph to its baseTourGraph field.

2. 2
   Add steps

   Open the Guided Tour Editor and add a Guided Location Step for each stop, linked to a location in the graph.

3. 3
   Override per step

   Force camera angle, restrict FOV/pitch, lock the camera, disable zoom, and show instruction text for that step.

4. 4
   Set progression rules

   Enable Auto Advance (after required hotspots are interacted with), add a delay, and allow skipping or backtracking at the tour level.

Floor Plans & Minimap

Position location markers on 2D floor-plan images to give viewers their bearings. At runtime the FloorPlanUI renders the map and the RadarHandler shows the current viewing direction.

1. 1
   Create the floor plan data

   Open Tools → PanoShard → Utils → Floor Plan, select the related Tour Graph, and click Create New Floor Plan Data.

2. 2
   Add floors and markers

   Add one or more floor layers (each with its own map image) and drag location markers onto the map. Switch floors via tabs.

3. 3
   Wire it to the tour

   The FloorPlanData asset is referenced by the Tour Graph's floorPlan field. Spawn the FloorPlan prefab for the in-game minimap.

Scene Setup & Generation

PanoShard offers a one-click scene setup for tile streaming, plus a graph-driven generator for additive scene streaming.

1. 1
   Automatic setup

   Tools → PanoShard → Scene → Automatic Setup spawns the TourManager, TransitionManager, CameraController, and a Sphere — plus an EventSystem if missing.

2. 2
   Assign and play

   Drop your Tour Graph onto the TourManager, confirm the TileLoader and SphereSegmentGenerator settings, and press Play.

3. 3
   Or generate from graph

   Scene → Generate From Graph creates one Unity scene per location plus a bootstrapper and manifest — for additive scene streaming instead of tile streaming.

Runtime Components

The scene that Automatic Setup builds wires together a handful of core MonoBehaviours. Here's what each one does.

Panoshard.LoadLocation(locationInfo);
var loader = Panoshard.GetTileLoader();
var tour = Panoshard.GetTourManager();
Panoshard.SetTilesFolderUrl("http://example.com/tiles/");

Performance, VR & Quality

Dial in fidelity per device with Quality Presets, and enable VR with a single support component.

1. 1
   Create a Quality Preset

   Create → PanoShard → Quality Preset, then assign it to the TileLoader's qualityPreset field to control filtering, aniso level, mip bias, and VSync.

2. 2
   Enable VR

   Import the XRInteractionToolkit_VR_Support package, add PanoShardVRSupport to your camera rig, and assign the stereo InvertNormalsURPShaderVR material.

Platform Support

PanoShard targets Unity 6+ with URP across desktop, mobile, WebGL, and VR.