Load terrain heightmap images once they are loaded, and show Edits in advanced properties

- When the heightmap image is not loaded yet (for example just chosen in
  the scene editor), the relief is used and the image is checked again
  about every half second, instead of never.
- The Edits property is with the sculpt data, in the advanced properties.
- A gameplay test changes the relief like the scene editor, paints with
  the editor tools and reloads the saved data.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0156q1ijXegCexbGspqriikR

Author: claude

extensions/community/Terrain3D.json

@@ -514,6 +514,18 @@
             "};",
             "",
             "/**",
+            " * @param {gdjs.RuntimeGame} game",
+            " * @param {string} imageResourceName",
+            " * @returns {CanvasImageSource | null} The image, or null if it's not loaded (yet).",
+            " */",
+            "const getLoadedImage = (game, imageResourceName) => {",
+            "    const texture = game.getImageManager().getPIXITexture(imageResourceName);",
+            "    const source = texture && texture.baseTexture && texture.baseTexture.getDrawableSource();",
+            "    // An 8 x 8 placeholder is given for images that are not loaded.",
+            "    return source && source.width > 8 && source.height > 8 ? source : null;",
+            "};",
+            "",
+            "/**",
             " * Loads heights from an image: black is the lowest, white the highest.",
             " * Heights have 16 bits of precision when the red channel holds the most",
             " * significant byte and the green one the least significant (a gray image",
@@ -524,10 +536,8 @@
             " * @returns {boolean} true if the image could be read.",
             " */",
             "const loadHeightsFromImage = (data, game, imageResourceName) => {",
-            "    const texture = game.getImageManager().getPIXITexture(imageResourceName);",
-            "    const source = texture && texture.baseTexture && texture.baseTexture.getDrawableSource();",
-            "    // An 8 x 8 placeholder is given for images that are not loaded.",
-            "    if (!source || source.width <= 8 || source.height <= 8) return false;",
+            "    const source = getLoadedImage(game, imageResourceName);",
+            "    if (!source) return false;",
             "",
             "    const canvas = document.createElement('canvas');",
             "    canvas.width = source.width;",
@@ -1522,6 +1532,9 @@
             "        this._strokeChangedSamples = new SampleRectangle();",
             "        /** The properties the data was loaded from, to reload it only if they change. */",
             "        this.loadedFrom = '';",
+            "        /** True when the heightmap image was not loaded yet: the relief is used until it is. */",
+            "        this.isWaitingForHeightmap = false;",
+            "        this._framesWaitingForHeightmap = 0;",
             "        /** The last value of the sculpt data property read or saved. */",
             "        this.sculptData = '';",
             "        /**",
@@ -1566,6 +1579,7 @@
             "        const validResolution = RESOLUTIONS.indexOf(resolution) !== -1 ? resolution : DEFAULT_RESOLUTION;",
             "        this.sculptData = object._getSculptData();",
             "        this.loadedFrom = this._getSourceProperties();",
+            "        this.isWaitingForHeightmap = false;",
             "",
             "        this.baseData = this._getBaseData(validResolution);",
             "        let data = codec.decode(this.sculptData, (resolution) => copyTerrainData(this._getBaseData(resolution)));",
@@ -1591,6 +1605,8 @@
             "            !!heightmapImage && loadHeightsFromImage(data, object.getRuntimeScene().getGame(), heightmapImage);",
             "        if (!isHeightmapLoaded) {",
             "            relief.generate(data, object._getRelief(), object._getSeed());",
+            "            // The image can still be loading: it's checked again later (see `update`).",
+            "            if (heightmapImage) this.isWaitingForHeightmap = true;",
             "        }",
             "        edits.apply(data, object._getEdits());",
             "        // Not kept if the image is missing: it may be loaded later.",
@@ -1871,6 +1887,10 @@
             "    }",
             "",
             "    update() {",
+            "        if (this.isWaitingForHeightmap && ++this._framesWaitingForHeightmap % 30 === 0) {",
+            "            const game = this.object.getRuntimeScene().getGame();",
+            "            if (getLoadedImage(game, this.object._getHeightmapImage())) this.loadFromProperties();",
+            "        }",
             "        const transform = this._getTransform();",
             "        if (transform !== this._transform) {",
             "            this._transform = transform;",
@@ -3448,6 +3468,7 @@
           "label": "Edits",
           "description": "Changes of the relief or heightmap, as a JSON list, for example [{\"tool\": \"raise\", \"x\": 0.3, \"y\": 0.4, \"radius\": 0.15, \"height\": 0.4}, {\"tool\": \"paint\", \"x\": 0.1, \"y\": 0.9, \"toX\": 0.8, \"toY\": 0.2, \"radius\": 0.02, \"layer\": 2}]. Tools: raise (height, negative to lower), flatten (z), smooth (strength) and paint (layer, from 1 to 4, and strength). x, y and radius are fractions (0 to 1) of the terrain size, height and z fractions of its depth. Add toX and toY to change the ground along a line (paths, rivers, ridges). Shown in the scene editor.",
           "group": "Shape",
+          "advanced": true,
           "name": "Edits"
         },
         {

sources/3d-world/Terrain3D/build.py

@@ -204,7 +204,7 @@ def args(*names):
          description="Each seed gives a different terrain with the same relief."),
     prop("HeightmapImage", "Resource", "", "Heightmap image", group="Shape", extra=["image"],
          description="Optional. Replaces the relief: black is the lowest, white the highest (the object depth)."),
-    prop("Edits", "MultilineString", "", "Edits", group="Shape",
+    prop("Edits", "MultilineString", "", "Edits", group="Shape", advanced=True,
          description="Changes of the relief or heightmap, as a JSON list, for example "
                      '[{"tool": "raise", "x": 0.3, "y": 0.4, "radius": 0.15, "height": 0.4}, '
                      '{"tool": "paint", "x": 0.1, "y": 0.9, "toX": 0.8, "toY": 0.2, "radius": 0.02, "layer": 2}]. '

sources/3d-world/Terrain3D/helper.js

@@ -459,6 +459,18 @@ const edits = {
     },
 };
 
+/**
+ * @param {gdjs.RuntimeGame} game
+ * @param {string} imageResourceName
+ * @returns {CanvasImageSource | null} The image, or null if it's not loaded (yet).
+ */
+const getLoadedImage = (game, imageResourceName) => {
+    const texture = game.getImageManager().getPIXITexture(imageResourceName);
+    const source = texture && texture.baseTexture && texture.baseTexture.getDrawableSource();
+    // An 8 x 8 placeholder is given for images that are not loaded.
+    return source && source.width > 8 && source.height > 8 ? source : null;
+};
+
 /**
  * Loads heights from an image: black is the lowest, white the highest.
  * Heights have 16 bits of precision when the red channel holds the most
@@ -470,10 +482,8 @@ const edits = {
  * @returns {boolean} true if the image could be read.
  */
 const loadHeightsFromImage = (data, game, imageResourceName) => {
-    const texture = game.getImageManager().getPIXITexture(imageResourceName);
-    const source = texture && texture.baseTexture && texture.baseTexture.getDrawableSource();
-    // An 8 x 8 placeholder is given for images that are not loaded.
-    if (!source || source.width <= 8 || source.height <= 8) return false;
+    const source = getLoadedImage(game, imageResourceName);
+    if (!source) return false;
 
     const canvas = document.createElement('canvas');
     canvas.width = source.width;
@@ -1468,6 +1478,9 @@ class Terrain {
         this._strokeChangedSamples = new SampleRectangle();
         /** The properties the data was loaded from, to reload it only if they change. */
         this.loadedFrom = '';
+        /** True when the heightmap image was not loaded yet: the relief is used until it is. */
+        this.isWaitingForHeightmap = false;
+        this._framesWaitingForHeightmap = 0;
         /** The last value of the sculpt data property read or saved. */
         this.sculptData = '';
         /**
@@ -1512,6 +1525,7 @@ class Terrain {
         const validResolution = RESOLUTIONS.indexOf(resolution) !== -1 ? resolution : DEFAULT_RESOLUTION;
         this.sculptData = object._getSculptData();
         this.loadedFrom = this._getSourceProperties();
+        this.isWaitingForHeightmap = false;
 
         this.baseData = this._getBaseData(validResolution);
         let data = codec.decode(this.sculptData, (resolution) => copyTerrainData(this._getBaseData(resolution)));
@@ -1537,6 +1551,8 @@ class Terrain {
             !!heightmapImage && loadHeightsFromImage(data, object.getRuntimeScene().getGame(), heightmapImage);
         if (!isHeightmapLoaded) {
             relief.generate(data, object._getRelief(), object._getSeed());
+            // The image can still be loading: it's checked again later (see `update`).
+            if (heightmapImage) this.isWaitingForHeightmap = true;
         }
         edits.apply(data, object._getEdits());
         // Not kept if the image is missing: it may be loaded later.
@@ -1817,6 +1833,10 @@ class Terrain {
     }
 
     update() {
+        if (this.isWaitingForHeightmap && ++this._framesWaitingForHeightmap % 30 === 0) {
+            const game = this.object.getRuntimeScene().getGame();
+            if (getLoadedImage(game, this.object._getHeightmapImage())) this.loadFromProperties();
+        }
         const transform = this._getTransform();
         if (transform !== this._transform) {
             this._transform = transform;

sources/3d-world/gameplay-tests/02-raise.js

@@ -16,7 +16,7 @@ terrain.raise(hillX, hillY, hillX, hillY, 300, 150);
 const hillZ = terrain.getHeightAt(hillX, hillY);
 harness.assert(Math.abs(hillZ - groundBefore - 150) < 1, 'The ground is raised by 150 at the center.');
 await harness.stepFrames(2);
-harness.setObjectPosition(start.id, hillX - 15, hillY - 15, hillZ + 80);
+harness.setObjectPosition(start.id, hillX - 15, hillY - 15, hillZ + 40);
 await harness.stepUntil(() => getPlayer().behaviors.PhysicsCharacter3D.state.IsOnFloor === false, { maxFrames: 5 });
 const landed = await harness.stepUntil(
   () => getPlayer().behaviors.PhysicsCharacter3D.state.IsOnFloor === true,

sources/3d-world/gameplay-tests/11-relief-change.js

@@ -0,0 +1,80 @@
+// Painting after the relief was changed in the scene editor
+await harness.goToScene('Game Scene');
+// Faster in the software renderer used to run tests.
+harness.setGameResolutionSize(160, 90);
+await harness.stepFrames(2);
+const game = harness.getRuntimeGame();
+const scene = harness.getCurrentRuntimeScene();
+scene.getObjects('Player')[0].getBehavior('ThirdPersonCamera').activate(false);
+scene.getObjects('Grass')[0].hide(true);
+const terrainObject = scene.getObjects('Terrain')[0];
+const terrain = terrainObject.__terrain3D;
+const targetX = 640, targetY = 1100;
+
+// The scene editor changes the relief like this (hot-reload of the object).
+const oldObjectData = scene._objects.get('Terrain');
+const newObjectData = JSON.parse(JSON.stringify(oldObjectData));
+newObjectData.content.Relief = 'Mountains';
+const heightBefore = terrain.getHeightAt(targetX, targetY);
+terrainObject.updateFromObjectData(oldObjectData, newObjectData);
+harness.assert(terrainObject._getRelief() === 'Mountains', 'The relief is changed.');
+harness.assert(Math.abs(terrain.getHeightAt(targetX, targetY) - heightBefore) > 1, 'The ground is changed right away.');
+
+gdjs.evtTools.camera.setCameraX(scene, targetX, '', 0);
+gdjs.evtTools.camera.setCameraY(scene, targetY, '', 0);
+gdjs.scene3d.camera.setCameraZ(scene, terrain.getHeightAt(targetX, targetY) + 800, '', 0);
+gdjs.scene3d.camera.setCameraRotationX(scene, 0, '', 0);
+await harness.stepFrames(1);
+
+const savedProperties = [];
+let toolbarItems = null;
+const editor = {
+  getRuntimeGame: () => game,
+  getSelectedObjects: () => [terrainObject],
+  captureLeftMouseButton: () => {},
+  updateObjectProperties: (objectName, properties) => savedProperties.push(properties),
+  showToolbar: (toolbarId, items) => (toolbarItems = items),
+};
+const updateTools = () => gdjs.callbacksInGameEditorPostStep.forEach((callback) => callback(editor));
+updateTools();
+toolbarItems.find((item) => item.id === 'Paint2').onClick();
+updateTools();
+const layerWeight = () => terrain.getLayerWeightAt(targetX, targetY, 2);
+const weightBefore = layerWeight();
+harness.setMousePositionScreen(game.getGameResolutionWidth() / 2, game.getGameResolutionHeight() / 2);
+harness.setMouseButtonPressed(true);
+for (let frame = 0; frame < 20 && layerWeight() < 0.8; frame++) {
+  await harness.stepFrames(1);
+  updateTools();
+  await new Promise((resolve) => setTimeout(resolve, 30));
+}
+harness.setMouseButtonPressed(false);
+await harness.stepFrames(1, { onFrame: updateTools });
+const weightAfter = layerWeight();
+console.log('layer 2 weight before=' + weightBefore.toFixed(2) + ' after=' + weightAfter.toFixed(2) + ' saves=' + savedProperties.length);
+harness.assert(weightAfter > weightBefore + 0.3, 'The layer is painted on the mountains.');
+harness.assert(savedProperties.length === 1, 'The stroke is saved.');
+
+// The saved data gives back the painted mountains.
+terrainObject._objectData.SculptData = savedProperties[0].SculptData;
+terrain.loadFromProperties();
+harness.assert(Math.abs(layerWeight() - weightAfter) < 0.02, 'The saved data gives back the paint on the mountains.');
+
+// A heightmap image still loading: the relief is used until the image is there.
+const imageManager = game.getImageManager();
+const getPIXITexture = imageManager.getPIXITexture;
+imageManager.getPIXITexture = () => null;
+const objectDataWithMountains = scene._objects.get('Terrain');
+const objectDataWithHeightmap = JSON.parse(JSON.stringify(objectDataWithMountains));
+objectDataWithHeightmap.content.HeightmapImage = 'assets/TerrainRock.jpg';
+objectDataWithHeightmap.content.SculptData = '';
+const mountainsHeight = terrain.getHeightAt(targetX, targetY);
+try {
+  terrainObject.updateFromObjectData(objectDataWithMountains, objectDataWithHeightmap);
+} finally {
+  imageManager.getPIXITexture = getPIXITexture;
+}
+harness.assert(terrain.isWaitingForHeightmap, 'The terrain waits for the heightmap image.');
+await harness.stepFrames(31);
+harness.assert(!terrain.isWaitingForHeightmap, 'The heightmap image is used once loaded.');
+harness.assert(Math.abs(terrain.getHeightAt(targetX, targetY) - mountainsHeight) > 1, 'The ground follows the heightmap.');