[Auto] [Improve] Enhanced 3D box docs with face textures, tiling, tint color, and material types

automated_updates_data.json

@@ -88,6 +88,10 @@
     {
       "date": "2026-04-02",
       "summary": "Improved multiplayer docs: added Quick Join section, documented player username/ping/last-joined/last-left expressions, lobby ID expression, custom message variable variant, and synchronization rate action"
+    },
+    {
+      "date": "2026-04-10",
+      "summary": "Improved 3D box object docs: added face textures section (6 faces, per-face tiling, tint color, face orientation), clarified material types, documented Face visibility and runtime actions, and fixed grammar"
     }
   ]
 }

docs/gdevelop5/objects/3d-box/index.md

@@ -5,16 +5,37 @@ title: 3D box
 
 A 3D box displays a box in 3D, with up to 6 faces each showing an image.
 
-If you need to show more detail 3D objects, check the [3D model object](../3d-model).
+If you need to show more detailed 3D objects, check the [3D model object](../3d-model).
+
+## Face textures
+
+Each of the six faces of the box (front, back, left, right, top, bottom) can display a different image. Leave a face's image empty to make that face show no texture (it will still be rendered, just without an image). You can change any face's image at runtime using the **Change the image of a face** action.
+
+### Tiling
+
+Each face has a **Tile** checkbox in the object properties. When enabled, the texture repeats across the face instead of being stretched to fit, which is useful for walls, floors, and ceilings where you want to keep the texture at its natural scale as the box is resized.
+
+### Tint color
+
+A **Tint** color can be applied to the entire box to colorize all faces uniformly. This is useful for indicating states (damage flash, selection highlight, etc.) without needing separate textures. Use the **Change the tint** action to modify it at runtime.
+
+### Face orientation
+
+The **Faces orientation** property (Y or Z) controls how images are oriented on the faces:
+
+- **Y** – the top of each texture image touches the top face of the box.
+- **Z** – the top of each texture image touches the front face of the box.
+
+The **Back face orientation** advanced property controls the orientation of the back face image specifically: whether the top of the image touches the top face or the bottom face of the box.
 
 ## Lighting
 
-Lighting can be set up through [layers effects](../../interface/scene-editor/layer-effects). Ambient and directional light effects allow to configure basic lighting for 3D layers.
+Lighting can be set up through [layer effects](../../interface/scene-editor/layer-effects). Ambient and directional light effects allow configuring basic lighting for 3D layers.
 
-3D boxes can be set up to react to lighting in different ways:
+The **material type** property controls whether the box reacts to lighting:
 
-- Either it does not react to light, meaning that it's always shown with the colors of the texture that was set (like a 2D object)
-- Or it does react to light. In this case, don't forget to set up a light in the layer effects.
+- **Standard** (default) – the box reacts to ambient and directional lights in the layer, and can cast and receive shadows.
+- **Basic** – the box is always shown with the full colors of its textures, unaffected by any lighting. Use this for objects that should never be darkened (UI elements, glowing items, etc.).
 
 ## Shadows
 
@@ -30,12 +51,12 @@ Shadows are rendered around the camera. You can tweak their range, quality and t
 
 Support for transparency (faces with transparent or semi opaque colors) can be enabled by checking the checkbox **"Enable texture transparency"** when editing a 3D box object.
 
-This can be produce strange results if you expect other faces of the box to be shown behind. This is due to how 3D rendering works. It's also more costly to render for the 3D engine.
+This can produce strange results if you expect other faces of the box to be shown behind. This is due to how 3D rendering works. It's also more costly to render for the 3D engine.
 
 ## Performance considerations
 
 A lot of 3D boxes can impact your game as they require multiple faces to be rendered, even if these faces are partially or totally hidden behind other 3D or 2D objects.
 
-If your object is only shown from a certain point of view, you can disable the visibility of certain faces of the cube.
+Each face's visibility can be toggled independently — both in the object properties and at runtime using the **Face visibility** action. If your box is only ever seen from one side (e.g., a floor tile), hiding the unseen faces reduces the number of triangles the GPU must process each frame.
 
-Be sure to reduce the number of 3D objects you use as much as you can, especially for good performance on low-end devices. Rather than using multiple objects, you can also enable tiling and resize the object (like you would do with a [tiled sprite](../tiled_sprite) instead of using multiple [sprites](../sprite)).
+Be sure to reduce the number of 3D objects you use as much as you can, especially for good performance on low-end devices. Rather than placing many individual boxes side by side, enable **tiling** and resize a single box (the same principle as using a [tiled sprite](../tiled_sprite) instead of many [sprites](../sprite)).