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                      ← 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

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.

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.

If you place objects from map coordinates in code, such as the position of a destination from sdk.availableDestinations, convert them before using them as a local position under the map root:

var p = destination.position;                                   // map coordinates
var local = new Vector3((float)p.x, (float)p.y, -(float)p.z);   // Unity map-root space
marker.transform.SetParent(mapRoot.transform, false);
marker.transform.localPosition = local;

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, cached point clouds or point-cloud files, and a build fails if a .ply ends up in Resources, StreamingAssets or the packed assets. You don’t need to hide or delete point clouds before building.

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 unloads

A 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 reports whether the localized section has a matching root:

root.isAligned tells whether a specific root currently has an accepted alignment.