[Auto] [Improve] Enhanced UI and visual objects documentation with detailed properties and usage guidance (#444)

Author: github-actions[bot]

automated_updates_data.json

@@ -4,6 +4,7 @@
     { "date": "2026-02-16", "summary": "Enhanced 3D model documentation with animation controls, material types, origin/center points, and shadow configuration" },
     { "date": "2026-02-16", "summary": "Improved core behavior documentation: added Window Center anchor option, draggable collision mask and Z-order details, destroy outside parameters" },
     { "date": "2026-02-16", "summary": "Enhanced pathfinding documentation with grid offset properties, path smoothing, obstacle cost clarification, and activation behavior" },
+    { "date": "2026-02-16", "summary": "Improved UI and visual object documentation: enhanced light, button, slider, text, panel sprite, and particle emitter pages with detailed properties and usage tips" }
     { "date": "2026-02-16", "summary": "Enhanced tween behavior documentation with scale center options, color modes, exponential interpolation, and effect properties" }
   ]
 }

docs/gdevelop5/objects/button/index.md

@@ -36,4 +36,20 @@ Button clicks/taps can be checked with a condition in events:
 
 ![](button-clicked-condition.png)
 
-Other conditions can be used to check the button state. For instance, it allows to apply [an effect](/gdevelop5/objects/effects) to make a button appear brighter when it's pressed.
+Other conditions can be used to check the button state. For instance, it allows to apply [an effect](/gdevelop5/objects/effects) to make a button appear brighter when it's pressed.
+
+### Button states
+
+Buttons have three distinct states that determine which image is displayed:
+
+- **Idle**: The default state when the button is not being interacted with
+- **Hovered**: When the mouse cursor is over the button (on desktop/web) or when a touch is held on the button (on mobile)
+- **Pressed**: When the button is actively being clicked or tapped
+
+You can check these states in events to create visual feedback or trigger different behaviors.
+
+### Tips for button design
+
+- Use consistent button sizes across your UI for a professional look
+- Make sure button images have enough contrast so text on them is readable
+- Add sound effects when buttons are clicked to improve user experience

docs/gdevelop5/objects/light/index.md

@@ -3,25 +3,36 @@ title: Light
 ---
 # Light
 
-Light objects simulate light sources in 2D and cast shadows on other objects.
+Light objects simulate light sources in 2D and cast shadows on other objects. They create atmospheric and realistic lighting effects by simulating how light spreads and is blocked by obstacles.
+
 Light objects can be customized with several properties:
 
-- a light color
-- a light radius
-- a texture to give a shape to the light
+- **Light color**: Set the color of the light using RGB values (for example, warm orange for fire, cool blue for moonlight)
+- **Light radius**: Control how far the light spreads from its source (in pixels)
+- **Light texture**: An optional image to give a specific shape to the light (such as a cone for flashlights or spotlights)
+- **Debug mode**: An advanced option that displays the lines used to render the light, useful for understanding the rendering
 
 ## How does it work?
 
-By default, light rays are cast from light objects and are blocked by other objects edges using the Light Obstacle behavior.
+By default, light rays are cast from light objects and are blocked by other object edges using the **Light Obstacle behavior**.
 
-Light rays will take into account the custom collisions masks on the objects with the Light Obstacle behavior.
+To make an object block light:
 
-### Using the light texture
+1. Select the object that should cast a shadow
+2. Add the "Light Obstacle Behavior" to it
+3. The light will now be stopped by this object's edges
+
+Light rays will take into account the custom collision masks on objects with the Light Obstacle behavior. This means you can control exactly which parts of an object block the light by editing its collision mask.
 
-The light texture property allows to create a custom shape for the light.
+!!! note
+
+    Light objects only work in 2D games. They do not affect 3D objects. For 3D lighting, use the built-in 3D lighting features.
+
+### Using the light texture
 
+The light texture property allows you to create a custom shape for the light. Without a texture, light is rendered as a circular gradient that fades from bright at the center to dark at the edges.
 
-For instance, a flashlight effect can be achieved by using a cone-shaped texture.
+By providing a texture image, you can control the shape and pattern of the light. For instance, a flashlight effect can be achieved by using a cone-shaped texture.
 
 | ![The light texture used in the object.](Cone_Light.png) | ![The result of a light texture in game](result_light_texture.png) |
 |---|---|

docs/gdevelop5/objects/panel_sprite/index.md

@@ -3,7 +3,7 @@ title: Panel Sprite ("9 patch")
 ---
 # Panel Sprite ("9 patch")
 
-Panel sprite is an [object](/gdevelop5/objects) where its image is split into 9 pieces or slices and each slice is scaled separately. This can be helpful where you would need the object to keep it's proportions even after it is scaled. It can be useful for making the frames of a menu interface, as tiles (land, water, etc..) in top down games, as platforms in platformer games, used in health bars, etc.
+Panel sprite is an [object](/gdevelop5/objects) where its image is split into 9 pieces or slices and each slice is scaled separately. This can be helpful where you would need the object to keep its proportions even after it is scaled. It can be useful for making the frames of a menu interface, as tiles (land, water, etc.) in top down games, as platforms in platformer games, used in health bars, dialog boxes, and more.
 
 !!! note
 
@@ -43,6 +43,21 @@ If "repeat borders and center texture" is enabled, segments 2, 4, 5, 6, 8 will b
 
 ![](9panel6.png)
 
+### When to use Panel Sprite vs other objects
+
+Panel Sprite is ideal when you need:
+
+- **UI elements** that can resize without distortion (buttons, panels, frames)
+- **Borders and decorative frames** that must maintain corner detail
+- **Dialog boxes** that adjust to fit varying amounts of text
+- **Scalable platforms** in platformer games that keep edge details intact
+
+For other use cases:
+
+- Use regular [Sprite](/gdevelop5/objects/sprite) objects when you don't need to resize, or stretching is acceptable
+- Use [Tiled Sprite](/gdevelop5/objects/tiled_sprite) objects when you need a pattern that repeats uniformly in all directions
+- Panel Sprites work well as components in [custom objects](/gdevelop5/objects/custom-objects-prefab-template) for reusable UI elements
+
 ## Reference
 
 All actions, conditions and expressions are listed in [the panel sprite (9-patch) object reference page](/gdevelop5/all-features/panel-sprite-object/reference/).

docs/gdevelop5/objects/particles_emitter/index.md

@@ -59,4 +59,4 @@ You can also change the maximum number of particles rendered by the object on th
 ## Reference
 
 All actions, conditions and expressions for the 2D particle emitter are listed in [this reference page](/gdevelop5/all-features/particle-system/reference/).
-All actions, conditions and expressions for the 23 particle emitter are listed in [this reference page](/gdevelop5/extensions/particle-emitter3d).
+All actions, conditions and expressions for the 3D particle emitter are listed in [this reference page](/gdevelop5/extensions/particle-emitter3d).

docs/gdevelop5/objects/slider/index.md

@@ -41,8 +41,29 @@ When a slider is added into the scene, it takes the default size set for the sli
 
 A slider would be useless if the game can't react when its value is changed.
 
-Slider values can be read with the `Value()` expression. It's can be used to store this as a variable or use it to change a property of an object.
+Slider values can be read with the `Value()` expression. It can be used to store this as a variable or use it to change a property of an object.
 
 ![](slider-value-expression.png)
 
-Sliders and toggle switches can be useful to make a settings panel. As the settings panel and the game may be in different scene, the value can be stored in a global variable to use it in other game scenes.
+### Using slider values in your game
+
+Here are some common ways to use slider values:
+
+- **Volume control**: Use the slider value to set the volume of music or sound effects (typically 0-100)
+- **Difficulty settings**: Allow players to adjust game difficulty with a slider
+- **Graphics settings**: Control visual quality, brightness, or other rendering options
+- **Gameplay parameters**: Adjust speed, power, or other in-game values
+
+### Saving slider settings
+
+Sliders and toggle switches are useful for creating settings panels. Since the settings panel and the game may be in different scenes, store the value in a global variable to use it across all game scenes.
+
+You can also use the [Storage feature](/gdevelop5/all-features/storage) to save slider values between game sessions, so player preferences persist even after closing the game.
+
+### Slider range and step
+
+When creating a slider, you can configure:
+
+- **Minimum value**: The lowest value the slider can represent
+- **Maximum value**: The highest value the slider can represent
+- **Step size**: How much the value changes as the thumb moves (for example, a step of 1 means whole numbers only)

docs/gdevelop5/objects/text/index.md

@@ -25,7 +25,7 @@ The color of the text can be changed by clicking on the palette color square, lo
 
 ### Font and text style
 
-You can choose from bold and italic, as well as choosing a custom font for the text. A custom font will require a font file, for which the file format must be TTF or OFT.
+You can choose from bold and italic, as well as choosing a custom font for the text. A custom font will require a font file, for which the file format must be TTF or OTF.
  ![](change-style-of-text.png)
 
 ### Additional effects
@@ -52,14 +52,22 @@ You can choose from bold and italic, as well as choosing a custom font for the t
 
 Using events, you can modify all properties of the text object, such as:
 
-  * Text Displayed
-  * Bold
-  * Italic
-  * Padding
-  * Alignment
-  * Wrapping
-  * Wrapping Width
-  * Font Size
+  * **Text Displayed**: Change the actual text content
+  * **Bold**: Make text bold or remove bold styling
+  * **Italic**: Make text italic or remove italic styling
+  * **Padding**: Add space around the text (useful when using backgrounds or borders)
+  * **Alignment**: Align text to left, center, or right
+  * **Wrapping**: Enable or disable automatic line wrapping
+  * **Wrapping Width**: Set the maximum width before text wraps to a new line
+  * **Font Size**: Change the size of the text dynamically
+
+### Text object performance
+
+Text objects are efficient for displaying text, but keep these performance tips in mind:
+
+- Avoid changing text content every frame if the text doesn't actually change
+- When displaying many numbers that update frequently (like scores), consider using [Bitmap Text](/gdevelop5/objects/bitmap_text) objects for better performance
+- For styled text with multiple colors or fonts in one block, consider using [BBText](/gdevelop5/objects/bbtext) objects
 
 ## Examples
 
@@ -82,4 +90,4 @@ Typewriter effect from extension
 
 ## Reference
 
-All actions, conditions and expressions are listed in [the text object reference page](/gdevelop5/all-features/text-object/reference/).
+All actions, conditions and expressions are listed in [the text object reference page](/gdevelop5/all-features/text-object/reference/).