# Spaces360 Scene Authoring Guide This guide supersedes the Spaces360 quick start in SETUP.md and the hotspot sections in README.md. The Dialogue system is separate and unchanged. ## Installing an update Exit Play mode and back up your project. Extract the package, then overwrite the matching scripts in `Assets/DialogueAndSpaces`; also copy any new scripts. Do not delete your scenes, graph assets, media, or existing `.meta` files. Retaining `.meta` files preserves Unity's references to the scripts. Wait for compilation to finish, then reopen the graph window if it was already open. ## Concepts - **Space:** a GameObject with a `SpaceAnchor`, placed under a `SpacesJourney` root. It is paired by ID with a node in the journey's graph asset. - **Position:** the anchor's position is where the 360 media was captured. - **Panorama alignment:** the anchor's Y rotation aligns the panorama to the physical space. Pitch, roll and scale have no effect. - **Media:** drag a 360 image or video directly onto the anchor. If both are set, the video is used. - **Graph canvas:** node positions in the graph window are layout only. They never move the physical location. - **Connections:** explicit and directed. Nearby spaces are never connected automatically, so walls are respected by not connecting across them. - **Arrival heading:** the player faces the direction of travel (destination minus source, flattened to the ground plane). A to B to C faces one way and C to B to A faces the opposite way. The first entry uses the entry space's starting yaw. If two spaces share a location, the current heading is kept. Pitch resets to level. - **Markers:** in Play mode, a clickable marker appears for each connected space, in the direction of that space. ## Setup 1. In the Hierarchy, choose GameObject > Dialogue and Spaces > Create Spatial Journey. Pick a location for its graph asset. 2. Optional: on the SpatialJourney, press Create Reference Map Quad, assign your floor plan as an Unlit material, and size it to real dimensions. It is hidden in Play mode. 3. With the journey selected, choose GameObject > Dialogue and Spaces > Create Space Anchor. You can also use Create Space Here on the journey, or Add Space in the graph window. Anchors must be children of the journey. 4. On each anchor, drag a 360 image or video onto the 360 Image or 360 Video field. 5. In a top-down Scene view, move each anchor to its capture location. Rotate it on Y to align the panorama. 6. To connect spaces, select an anchor and set "Connect both ways" as desired. Drop another anchor into **Add destination** under **Add Connection**. This immediately saves the link; there is no Connect button. The destination then appears under **Saved Connections**, with an outgoing-connection count. The add field stays empty so you can add more destinations. Directed links draw as yellow lines with arrows in the Scene view; the graph window also shows connecting lines. 7. On the anchor you want to start from, press Set as Entry Space. Set its Starting yaw for the first view. 8. Select the Main Camera and add `SpacesLookController`. 9. Create an empty object, add `Spaces360Host`, and assign **Journey** and **Player Camera**. The read-only **Journey Graph** field confirms the graph used. Do not assign a separate Graph or Catalog; older data-only options are hidden under an Advanced foldout. 10. Press Play. Left-drag to look around and click markers to travel. ## Editing - **Graph and scene stay paired:** creating a space in one creates its pair in the other. Moving or rotating an anchor updates the graph. - **Duplicating an anchor** creates a new space with no connections. - **Saved connections:** deselecting and reselecting an anchor rebuilds the connection list from the graph asset. Save the scene and graph assets with File > Save / Save Project before closing Unity. Adding the same destination twice does not create duplicate links. - **Removing links:** Remove deletes only the current anchor's outgoing link. For a two-way link, remove the reverse link on the destination too. - **Deleting:** use Delete Space and Paired Node in the anchor inspector. This removes the node, the GameObject and all incoming connections. - **Validate:** the graph window's Validate button reports missing media, missing destinations and unreachable spaces. - **Self tests:** the journey inspector's Run Navigation Self Tests button checks the arrival and connection rules. - **Connection persistence test:** Window > Dialogue and Spaces > Run Connection Persistence Self Tests checks that links survive graph serialization, create graph edges, avoid duplicates, and can be removed without removing other destinations. This is a graph-data test, not an automated inspector-selection test. - **JSON:** export and import are in the graph window. Media is stored as a name label only. The images and videos stay on the anchors. ## Optional media catalog A media catalog is no longer required. It is only a fallback for spaces whose anchor has no image or video, looked up by media key. The host and journey hide catalog controls under Advanced foldouts, and the graph window has no catalog input box. Existing catalog assignments are retained for compatibility. ## Checking a connection 1. Select anchor A, enable Connect both ways, and drop anchor B into Add destination. 2. B should appear under A's Saved Connections and the outgoing count should increase. 3. Select B. A should appear in B's Saved Connections. 4. Select A again. B should still be listed. The empty Add destination field is for the next link, not the one already saved. 5. Open the paired graph window. Connecting lines should appear. Turn on Scene-view Gizmos to inspect the scene markers as well. 6. Save the scene and project, then reopen the scene to check the saved setup. ## Known limits - Schema 1 graphs still load but have no physical positions. Their anchors appear at the origin until you place them. - Use one journey root per graph asset in the open scenes. - The direction a panorama turns when you rotate an anchor has not been verified in Unity. If it turns the wrong way, report it. - The current patch has been syntax-checked outside Unity, but it has not been compiled or play-tested here. Run the included self-tests in your Unity project. - For sharp Insta360 images, set the texture's Max Size to 8192 in the import settings.