Scene Authoring
A Graffity map is split into places (for example a mall) and sections (for example one floor). In Unity, each section you author content for gets one GraffityARMapRoot. You place content relative to the section’s point cloud in the Editor. At runtime the SDK aligns the root to the real world when the device localizes in that section.
Graffity AR Cloud Session ← GraffityARCloudSession (outside all map roots)
AR Session
XR Origin (Mobile AR)
└─ Camera Offset
└─ Main Camera
Graffity section <id> ← GraffityARMapRoot (place ID + section ID)
└─ Authored content ← content gate: the SDK shows/hides this
├─ Your prefab
└─ ...Download a section’s point cloud
Step 1 - Open the browser
Open Window > Graffity AR Cloud > Point Cloud Browser, or click Browse public places / authorized section PLY in the session Inspector. The browser uses the access token from Project Settings > Graffity AR Cloud. Set Scene session to the session whose scene should receive new map roots.
Step 2 - Pick a place and section
- Click Load / refresh public places and select a place to load its sections. Use Local name filter to narrow the list.
- For a private map in your organization, paste its place or section UUID into Known UUID and click Load known place or Load known section.
Step 3 - Download and preview
- Deselect any existing map root in the Hierarchy so that the browser creates a new one.
- Click Download / refresh and preview selected section. The browser shows download progress and offers a cancel button.
- On success, a
Graffity section <id>root with an Authored content child is created and added to the session’s Map Roots list. The point cloud appears in the Scene view.
Creating the root supports Undo. If a download fails or is cancelled, the existing preview and your content stay unchanged.
You can also create an empty root with GameObject > XR > Graffity Map Root. It creates the root and its Authored content gate and registers it with the scene’s session; enter the place and section IDs in its Inspector.
Author content
- Put your prefabs, models and scripts under Authored content. Their local positions are section coordinates in metres.
- Don’t scale the map root or its parents. Keep the session, AR Session, XR Origin and camera outside all map roots.
- Use one root per section. Duplicate sections and nested roots are rejected.
At runtime, Authored content stays inactive before localization and while the device is in another section. Because the gate is inactive, scripts under it don’t run until their section is localized. When the device localizes in the section, the SDK activates the gate and moves the map root. Your child objects keep their own local transforms, active states and component settings. Pause, reset and shutdown hide the content again and restore the root’s authored transform.
The SDK owns the content gate’s active state and the map root’s transform while the session runs. Don’t drive them from your own scripts at the same time. Animate and enable your content below the gate instead.
To see your content appear without a device, press Play and localize in the section from the session Inspector. See Test in the Editor.
Coordinates
Map data uses a right-handed coordinate system (the iOS and VPS convention). Unity is left-handed, so the preview and the runtime both flip Z. Content placed on the previewed point cloud lands in the matching real-world spot. There’s no need to scale the point cloud as you did in 3.x.
To place objects from map coordinates in code, such as the MapPosition of a POI from session.AvailableDestinations, let the SDK convert them:
// Under the map root, in its local space:
marker.transform.SetParent(mapRoot.transform, false);
marker.transform.localPosition = mapRoot.MapToLocalPosition(poi.MapPosition);
// Or in world space, once the POI's section root is aligned:
if (session.TryGetWorldPosition(poi, out var world))
marker.transform.position = world;Reopen and refresh previews
- The preview isn’t saved in your scene. After reopening a scene, select the root and click Preview selected root from offline cache.
- To update a section’s preview, select its root and download again. The root keeps its identity and your content.
- Preview point budget (1,000 to 250,000 points, default 25,000) controls how many points are drawn.
- Remove selected preview hides the preview without touching the root or its content.
Downloaded point clouds are cached in Library/GraffityARCloudCache/. You can delete this folder at any time. The cache doesn’t store tokens or download URLs.
Builds
The point cloud is only for authoring in the Editor. Builds never include previews or cached point clouds. Build validation checks only what the SDK creates: a build fails if it would include an asset from the SDK’s Editor folder or, outside a Development Build, runtime debug point-cloud data. Your own .ply files and other assets are not inspected, and builds without a Graffity session get no SDK log lines.
Additive scenes
Roots in the session’s Map Roots list are bound when the session initializes. For a map root in a scene loaded additively later, register it with the session after initialization. Unregister it before you unload that scene:
session.RegisterMapRoot(root); // after the scene loads
session.UnregisterMapRoot(root); // before the scene unloadsA destroyed root is removed automatically.
Runtime debug point cloud (optional)
To check alignment on a device, select a map root and click Import local PLY as optional runtime debug data. This adds a GraffityARDebugPointCloud to the root. Assign it a vertex-color unlit material and enable Runtime Debug Preview. The debug cloud shows up to 10,000 points once the root is aligned.
Debug point clouds require a Development Build. Normal builds strip disabled debug components and fail if one is enabled.
Checking the binding at runtime
session.SceneBinding.Status reports whether the localized section has a matching root:
Status | Meaning |
|---|---|
Uninitialized | The session isn’t initialized |
AwaitingAlignment | No localization result yet |
Aligned | The localized section’s root is aligned |
NoMatchingRoot | The device localized in a section that has no registered root. Add a root for that section. |
root.IsAligned tells whether a specific root currently has an accepted alignment.