Let themes paint the 3D terrain: material and color slots for custom objects

[4ian]

Lets the starter themes reach the 3D terrain (and any custom object): its painted layers and the colors of its grass. Needed by the 3D starters "with a map" (#1081 and the ones coming next), whose ground is a Terrain3D object instead of 3D boxes.

Goes with GDevelopApp/GDevelop-assets#704 (ground materials and terrain slots in every theme). Merge and deploy this one first: the assets build checks the slots of the themes against the deployed themeSlots.json. #1083 then makes the GTA with a map themeable.

What changed

• New slot kinds in theme-slots.json:
  • material: a texture with its normal map, for terrain layers.
  • color: a color like 52;104;36.
• New slots: terrain.ground, terrain.dirt, terrain.road, terrain.rock, terrain.sand, terrain.pavement (materials), and terrain.grass.base, terrain.grass.tip (colors of the grass blades).
• A starter maps the properties of a custom object in its theme-slots.json:

  "scene:Game Scene/Terrain": {
    "Layer1Texture": { "slot": "terrain.ground", "normalMap": "Layer1NormalMap" },
    "Layer2Texture": { "slot": "terrain.road", "normalMap": "Layer2NormalMap" }
  },
  "scene:Game Scene/Grass": { "BaseColor": "terrain.grass.base", "TipColor": "terrain.grass.tip" }

  An image property maps to a texture slot, a color property to a color slot, and a layer texture to a material slot along with the property that takes its normal map.
• StarterThemer:
  • Gives the texture and the normal map of a material to the two properties.
  • When the theme gives a texture without a normal map (a plain 3D cube), it empties the normal map property: the bumps of the starter's texture would not match.
  • Fills a layer that had no texture, creating its image resources.
  • A cube face accepts the texture of a material, and a terrain layer accepts a plain texture.
• checkStarterThemeSlots: custom objects don't have to be mapped, but a mapping must name properties the object has, of the right type (resource or color), and slots of the right kind. Their 3D children (like the terrain's AreaPlaceholder) still have to be mapped or ignored, as before.
• README: documents the mapping of custom objects.

How it was tested

• Unit tests (scripts/lib/__tests__): 12 new tests for the mapping of custom objects, materials, missing normal maps, colors and the checks. npm test (44 tests) and npm run check-types pass.
• All 50 starters still pass checkStarterThemeSlots.
• End to end, with the themes built locally by the assets PR (file URLs pointed at the local build): the 3D GTA with a map (made themeable in Make the 3D GTA with a map a themeable starter #1083) with the pirate, winter, Halloween and city themes. Each run in GDevelop (gameplay test taking full resolution screenshots):

Pirate (lush grass, sandy roads, cobblestones), winter (snow, gravel, cobblestones), Halloween (dead leaves, gravel, mossy cobblestones) and city (grass, asphalt, concrete).

Not checked

• The full database build (npm run build) and the deployment to staging: I ran the slot checks and the themer directly on the starters.
• The screenshots come from the claude/awesome-knuth-vaoj1s-screenshots branch, which only hosts them and isn't meant to be merged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Wa8uKpYuQrYqGYnqGCsquj

[github-actions]

Preview the game(s) changed or added in this Pull Request

No games are changed in this Pull Request.

---

This is an automatic message displaying links to the games in this PR - double check the JSON in case of doubt.

[4ian]

Rebased on main (with the 3D GTA, island and scattered models merged), and added a commit for the "Scattered models" object of the 3D terrain extension:

• A custom object property holding a 3D model (like Model of scattered models) can now be mapped to a model slot, e.g. "scene:Game Scene/PineForest": { "Model": "nature.tree" }. The theme model replaces it and the other properties (like the size of the copies) are kept. All the nature models of the themes stand up the same way (rotation X 90°), like scattered models expect.
• A custom object drawing a 3D model must be mapped or listed in ignoredObjects, like 3D model objects (the build names it otherwise). Custom objects can now be listed in ignoredObjects.
• New unit tests in ThemeSlots.spec.js and StarterThemer.spec.js (48 pass), README updated. Formatting and type checks pass.

The starters PRs (#1086, #1087, #1088) and the themeable GTA (#1083) are being rebuilt on top of this, with scattered models for their vegetation.

---

Generated by Claude Code