Expose setup container UUID

docs/API.md

@@ -42,7 +42,7 @@ Main methods:
 
 Represents JSON setup/update messages.
 
-A setup message exposes a root `Container`, which can recursively contain scenes, zones and generic containers. Common fields include name, address, position, rotation, color and children.
+A setup message exposes a root `Container`, which can recursively contain scenes, zones and generic containers. Common fields include name, address, UUID, position, rotation, color and children. `getUUID()` exposes the stable server-side container UUID when provided.
 
 Scene containers expose scene size. Zone containers expose the shape information currently provided by Pleiades: Box, Cylinder, Sphere, Path, Grid, Polygon and Segment.
 

src/control.ts

@@ -36,6 +36,7 @@ function parseContainer(value: unknown): Container {
   const position = vec3(value.position);
   const rotation = vec3(value.rotation);
   const color = vec4(value.color);
+  const uuid = typeof value.uuid === 'string' ? value.uuid : '';
   const rawChildren = Array.isArray(value.children)
     ? value.children
     : isRecord(value.children)
@@ -52,6 +53,7 @@ function parseContainer(value: unknown): Container {
       position,
       rotation,
       color,
+      uuid,
       {},
       children
     );
@@ -93,6 +95,7 @@ function parseContainer(value: unknown): Container {
       position,
       rotation,
       color,
+      uuid,
       new ZoneParameters(shapeType, shapeParameters, localSliderAxis),
       children
     );
@@ -106,13 +109,14 @@ function parseContainer(value: unknown): Container {
       position,
       rotation,
       color,
+      uuid,
       { size: vec3(value.size) },
       children
     );
   }
 
   const type = rawType ? ContainerType.Container : ContainerType.Unknown;
-  return new Container(type, name, address, position, rotation, color, {}, children);
+  return new Container(type, name, address, position, rotation, color, uuid, {}, children);
 }
 
 function parseContainerPayload(value: unknown): Container {

src/data.ts

@@ -252,6 +252,8 @@ export class Container {
     public readonly position: Vector3 = [0, 0, 0],
     public readonly rotation: Vector3 = [0, 0, 0],
     public readonly color: Vector4 = [0, 0, 0, 0],
+    /** Stable UUID supplied by the server for setup/update containers. */
+    public readonly uuid = '',
     public readonly parameters?: ContainerSpecificParameters,
     public readonly children: readonly Container[] = []
   ) {}
@@ -268,6 +270,7 @@ export class Container {
   getPosition(): Vector3 { return this.position; }
   getRotation(): Vector3 { return this.rotation; }
   getColor(): Vector4 { return this.color; }
+  getUUID(): string { return this.uuid; }
   getSceneParameters(): SceneParameters {
     if (!this.isScene()) throw new Error('Container is not a scene.');
     return this.parameters as SceneParameters;

tests/sdk.test.mjs

@@ -186,6 +186,7 @@ test('Control setup messages expose scene and zone hierarchy', () => {
                 name: 'Zone',
                 type: 'Zone',
                 address: '/world/scene/zone',
+                uuid: 'zone-uuid-123',
                 position: [1, 2, 3],
                 rotation: [0, 45, 0],
                 localSliderAxis: 'z',
@@ -207,6 +208,7 @@ test('Control setup messages expose scene and zone hierarchy', () => {
   assert.deepEqual(scene.getSceneParameters().size, [10, 3, 8]);
   const zone = scene.getChildren()[0];
   assert.equal(zone.getType(), ContainerType.Zone);
+  assert.equal(zone.getUUID(), 'zone-uuid-123');
   assert.equal(zone.getZoneParameters().getShapeType(), ShapeType.Box);
   assert.equal(zone.getZoneParameters().getLocalSliderAxis(), 'z');
   assert.deepEqual(zone.getZoneParameters().getBoxShapeParameters().size, [2, 1, 4]);