Improve hints when inspecting or positioning an object in 3D (#8707)

Author: ClementPasteau

newIDE/app/src/EditorFunctions/EditorFunctions.spec.js

@@ -1685,7 +1685,7 @@ describe('editorFunctions', () => {
       expect(result.success).toBe(true);
       expect(result.message).toEqual(
         expect.stringContaining(
-          'Created 2 new instances of object "Player" using point brush at 50, 60 on layer "base" (size 64x64, rotation 45°, opacity 128/255, z-order 5).'
+          'Created 2 new instances of object "Player" using point brush at 50, 60 on layer "base" (size 64x64, rotation 45°, opacity 128/255, z-order 5, origin at this position, each occupies X 50 to 114, Y 60 to 124).'
         )
       );
     });
@@ -1724,12 +1724,59 @@ describe('editorFunctions', () => {
       expect(result.success).toBe(true);
       expect(result.message).toEqual(
         expect.stringContaining(
-          'Created 1 new instance of object "Player" using point brush at 10, 20, 30 on layer "base" (size 8x16x24, rotation (15°, 30°, 45°)).'
+          'Created 1 new instance of object "Player" using point brush at 10, 20, 30 on layer "base" (size 8x16x24, rotation (15°, 30°, 45°), origin at this position, each occupies X 10 to 18, Y 20 to 36, Z 30 to 54).'
         )
       );
     });
   });
 
+  describe('describe_instances (position semantics)', () => {
+    let project: gdProject;
+    let testScene: gdLayout;
+
+    beforeEach(() => {
+      // $FlowFixMe[invalid-constructor]
+      project = new gd.ProjectHelper.createNewGDJSProject();
+      testScene = project.insertNewLayout('TestScene', 0);
+      testScene.getObjects().insertNewObject(project, 'Sprite', 'Player', 0);
+    });
+
+    afterEach(() => {
+      project.delete();
+    });
+
+    it('exposes z (even when 0), object size info and position semantics', async () => {
+      const instance = testScene
+        .getInitialInstances()
+        .insertNewInitialInstance();
+      instance.setObjectName('Player');
+      instance.setX(100);
+      instance.setY(200);
+      instance.setHasCustomSize(true);
+      instance.setHasCustomDepth(true);
+      instance.setCustomWidth(32);
+      instance.setCustomHeight(48);
+      instance.setCustomDepth(64);
+
+      const result = await editorFunctions.describe_instances.launchFunction({
+        ...makeFakeLaunchFunctionOptionsWithProject(project),
+        args: { scene_name: 'TestScene' },
+      });
+
+      expect(result.success).toBe(true);
+      const instances = result.instances || [];
+      expect(instances).toHaveLength(1);
+      expect(instances[0].z).toBe(0);
+      expect(instances[0].width).toBe(32);
+      expect(instances[0].height).toBe(48);
+      expect(instances[0].depth).toBe(64);
+      expect(result.positionSemantics).toEqual(
+        expect.stringContaining('origin, NOT its center')
+      );
+      expect(result.objectSizeInfo).toEqual({ Player: null });
+    });
+  });
+
   describe('change_scene_properties_layers_effects_groups (echo new values)', () => {
     let project: gdProject;
     let testScene: gdLayout;

newIDE/app/src/EditorFunctions/index.js

@@ -137,6 +137,9 @@ export type EditorFunctionGenericOutput = {|
   // Default size, origin and center of the object(s) being operated on, keyed by object name:
   objectSizeInfo?: { [string]: ObjectSizeInfo | null },
 
+  // Explanation of the coordinate semantics of `instances` positions:
+  positionSemantics?: string,
+
   hints?: Array<HintEntry>,
 
   // Set to true when the function call was aborted mid-execution (e.g. the AI
@@ -381,6 +384,45 @@ const injectObjectSizeInfo = (
   return output;
 };
 
+const INSTANCE_POSITION_SEMANTICS_MESSAGE =
+  'Each instance x;y;z is its origin, NOT its center. Unless `objectSizeInfo` indicates a custom origin, the origin is the minimum corner: an instance occupies x to x+width, y to y+height and (in 3D) z to z+depth, so its center is at position + size/2. To center an instance A on top of an instance B: A.x = B.x + (B.width - A.width)/2, A.y = B.y + (B.height - A.height)/2, A.z = B.z + B.depth.';
+
+const getOccupiedSpaceDescription = (
+  position: $ReadOnlyArray<number>,
+  size: $ReadOnlyArray<number>,
+  objectSizeInfo: ObjectSizeInfo | null
+): string => {
+  const round = (value: number) => Math.round(value * 100) / 100;
+  const axes = ['X', 'Y', 'Z'];
+  const originOffsets = [0, 0, 0];
+  if (objectSizeInfo) {
+    const defaultSizes = [
+      objectSizeInfo.width,
+      objectSizeInfo.height,
+      objectSizeInfo.depth,
+    ];
+    const origins = [
+      objectSizeInfo.originX,
+      objectSizeInfo.originY,
+      objectSizeInfo.originZ,
+    ];
+    for (let i = 0; i < size.length; i++) {
+      const defaultSize = defaultSizes[i];
+      const origin = origins[i];
+      // Origin offsets are given for the default size - scale them to the actual size.
+      if (origin && defaultSize) {
+        originOffsets[i] = origin * (size[i] / defaultSize);
+      }
+    }
+  }
+  return size
+    .map((sizeOnAxis, i) => {
+      const min = position[i] - originOffsets[i];
+      return `${axes[i]} ${round(min)} to ${round(min + sizeOnAxis)}`;
+    })
+    .join(', ');
+};
+
 const makeGenericSuccess = (message: string): EditorFunctionGenericOutput => ({
   success: true,
   message,
@@ -2488,6 +2530,7 @@ const describeInstances: EditorFunction = {
     const initialInstances = layout.getInitialInstances();
 
     const instances = [];
+    const objectSizeInfoByName: { [string]: ObjectSizeInfo | null } = {};
 
     // For each layer
     mapFor(0, layout.getLayersCount(), i => {
@@ -2511,8 +2554,15 @@ const describeInstances: EditorFunction = {
             object = globalObjects.getObject(objectName);
           }
 
-          const defaultSize = object
+          const sizeInfo = object
             ? getObjectSizeInfo(object, project, PixiResourcesLoader)
+            : null;
+          if (object && !(objectName in objectSizeInfoByName)) {
+            objectSizeInfoByName[objectName] = sizeInfo;
+          }
+
+          const defaultSize = object
+            ? sizeInfo
             : { width: 0, height: 0, depth: 0 };
 
           const width = instance.hasCustomSize()
@@ -2537,6 +2587,8 @@ const describeInstances: EditorFunction = {
             // Replace persistentUuid by id:
             persistentUuid: undefined,
             id: instance.getPersistentUuid().slice(0, 10),
+            // The serializer omits z when it's 0 - always expose it for 3D objects:
+            z: depth !== null ? instance.getZ() : undefined,
             // Actual computed dimensions (accounting for default size when no custom size is set):
             width,
             height,
@@ -2550,20 +2602,16 @@ const describeInstances: EditorFunction = {
       );
     });
 
+    const result: EditorFunctionGenericOutput = {
+      success: true,
+      instances: instances,
+      instancesForSceneNamed: scene_name,
+      positionSemantics: INSTANCE_POSITION_SEMANTICS_MESSAGE,
+    };
     if (objectNames.size > 0) {
-      return {
-        success: true,
-        instances: instances,
-        instancesForSceneNamed: scene_name,
-        instancesOnlyForObjectsNamed: [...objectNames].sort().join(','),
-      };
-    } else {
-      return {
-        success: true,
-        instances: instances,
-        instancesForSceneNamed: scene_name,
-      };
+      result.instancesOnlyForObjectsNamed = [...objectNames].sort().join(',');
     }
+    return injectObjectSizeInfo(result, objectSizeInfoByName);
   },
   modifiesProject: false,
 };
@@ -3028,6 +3076,22 @@ const put2dInstances: EditorFunction = {
           attrs.push(`opacity ${instancesOpacity}/255`);
         if (instances_z_order !== null)
           attrs.push(`z-order ${instances_z_order}`);
+        const effectiveSize = instancesSize
+          ? instancesSize
+          : objectSizeInfo &&
+            objectSizeInfo.width !== null &&
+            objectSizeInfo.height !== null
+          ? [objectSizeInfo.width, objectSizeInfo.height]
+          : null;
+        if (brush_kind === 'point' && effectiveSize) {
+          attrs.push(
+            `origin at this position, each occupies ${getOccupiedSpaceDescription(
+              brushPosition,
+              effectiveSize,
+              objectSizeInfo
+            )}`
+          );
+        }
         changes.push(
           `Created ${newInstancesCount} new instance${
             newInstancesCount > 1 ? 's' : ''
@@ -3595,6 +3659,23 @@ const put3dInstances: EditorFunction = {
               instancesRotationArray[1]
             }°, ${instancesRotationArray[2]}°)`
           );
+        const effectiveSize = instancesSizeArray
+          ? instancesSizeArray
+          : objectSizeInfo &&
+            objectSizeInfo.width !== null &&
+            objectSizeInfo.height !== null &&
+            objectSizeInfo.depth !== null
+          ? [objectSizeInfo.width, objectSizeInfo.height, objectSizeInfo.depth]
+          : null;
+        if (brush_kind === 'point' && effectiveSize) {
+          attrs.push(
+            `origin at this position, each occupies ${getOccupiedSpaceDescription(
+              brushPosition,
+              effectiveSize,
+              objectSizeInfo
+            )}`
+          );
+        }
         changes.push(
           `Created ${newInstancesCount} new instance${
             newInstancesCount > 1 ? 's' : ''