[Auto] [Improve] Enhanced audio docs with fade, pitch, seek features and improved linked objects docs (#459)

Co-authored-by: 4ian <1280130+4ian@users.noreply.github.com>

Author: github-actions[bot]

automated_updates_data.json

@@ -40,6 +40,10 @@
     {
       "date": "2026-02-18",
       "summary": "Improved sprite and video object docs: added blend modes, color/tint, flip operations, animation speed scale, and fixed video typos and playback speed range"
+    },
+    {
+      "date": "2026-02-18",
+      "summary": "Improved audio docs with fade, pitch/rate, seeking, unload, and spatial sound; improved linked objects docs with bidirectional links, auto-cleanup, and use cases"
     }
   ]
 }

docs/gdevelop5/all-features/audio/index.md

@@ -66,16 +66,36 @@ When a new scene starts, by default, sounds and music are stopped. If you want t
 
 ## Using channels
 
-When using the "Play a sound" or "Play a music file" action, audio files are played immediately. On completion, they are removed from memory. Looping is an exception. When you set the action to loop the audio file, it will be played forever (its' an "endless loop"). You must use the action to stop all sounds or music to stop them.
+When using the "Play a sound" or "Play a music file" action, audio files are played immediately. On completion, they are removed from memory. Looping is an exception. When you set the action to loop the audio file, it will be played forever (it's an "endless loop"). You must use the action to stop all sounds or music to stop them.
 
 If you want more control over sounds, use the action "**Play a sound on a channel**" or "**Play a music file on a channel.**" The action is used in the same way, except that you have to enter a channel number. This channel number can then be reused in other actions or conditions. A "channel number" can be used to check to see if a sound is being played on a channel, or it can be used to modify some properties of the music being played. For example, you could use a "channel number" to update the music volume dynamically according to the presence of enemies around the player.
 
+Channel numbers are arbitrary integers you choose — you can use any number you like. If you play a new sound or music on a channel that is already in use, the previous audio on that channel is stopped and replaced.
+
 ## Volume
 
 Sounds and music are by default played with a volume of 100%, which is the maximum. When starting a new sound/music, you can enter a different value (between 0 and 100).
 
 You can also use the action "Game global volume" to change the entire game's audio volume. A value of 0 means that no sounds and or music can be heard. This action is convenient when allowing the player to mute or change the game's volume. For instance, you might have a settings screen in your game that accesses the game's volume control. Mobile games usually have a button to mute the sounds of the game too.
 
+### Fading volume
+
+You can smoothly fade the volume of a sound or music on a channel from one level to another using the "**Fade the volume**" actions. Provide the starting volume, target volume, and duration in seconds. This is useful for fading in background music at the start of a scene, or fading out a sound before stopping it.
+
+## Playback rate (pitch)
+
+You can change the playback speed of a sound or music on a channel using the "**Set the playback speed**" actions (sometimes called pitch). A value of `1` is normal speed. Values below `1` slow the audio down (and lower the pitch), and values above `1` speed it up (and raise the pitch). The valid range is `0.5` to `4.0`.
+
+This is useful for effects like a slowed-down time feeling, or varying the pitch of repeated sound effects to make them sound less repetitive.
+
+## Seeking (playback position)
+
+You can jump to a specific position within a sound or music on a channel using the "**Set the playback position**" actions, with the position given in seconds. You can also read the current playback position using the corresponding expressions. This is useful for synchronising music to game events or resuming audio from a saved position.
+
+## Unloading audio
+
+You can explicitly unload a sound or music file from memory using the "**Unload a sound**" / "**Unload a music**" actions. This also stops any currently playing instance of that file. Use "**Unload all audio**" to stop and unload everything at once. Unloading audio you no longer need can free up memory, which is particularly useful on mobile devices.
+
 ## Pre-loading: improve the latency and loading times
 
 The first time music or sound is played, there can be a lag while the audio file is being prepared if you do not preload the audio. This is because the device must:
@@ -107,6 +127,10 @@ The sound will be stopped when:
 * There is **an error during the loading** (in which case it will be considered as playing for a few milliseconds, then will be deemed to be stopped as it was unable to load). 
 * Or you used **the action** to stop a sound or music on the channel.
 
+## Spatial sound
+
+For games where audio should feel positioned in a 2D or 3D space, the **Spatial Sound** extension provides actions to set the position of a sound on a channel and the position of the listener. Sounds played as *music* do not support spatialization — use *sounds on channels* instead. Volume naturally attenuates with distance: at double the reference distance, the volume is halved.
+
 ## Finding audio or making your own sounds
 
 You can use the in-built sound effect creator tool called Jfxr for making sound effects: [learn how to use Jfxr here](/gdevelop5/all-features/audio/using-jfxr).

docs/gdevelop5/all-features/linked-objects/index.md

@@ -3,39 +3,47 @@ title: Linked Objects
 ---
 # Linked Objects
 
-Actions and conditions of "Linked Objects" category allow us to make virtual connections between objects. We can later reference them by their links to each other. Typically, you can only link two objects when creating them.
+Actions and conditions of the "Linked Objects" category allow you to create virtual connections between object instances. You can later retrieve those connected instances by their link, without needing to store object references in variables. Links are **bidirectional**: linking object A to object B also makes B linked to A.
 
 !!! tip
 
-    You can also use a “For each object” event to take each instance of an object individually, and create links to other objects. Learn more about the "For each object" event by visiting [this page about For each event](/gdevelop5/events/foreach).
+    You can also use a "For each object" event to iterate over each instance of an object individually and create links to other objects. Learn more about the "For each object" event by visiting [this page about For each event](/gdevelop5/events/foreach).
 
 !!! tip
 
+    Some of the linked object operations are available as both a condition and an action. The condition variant is false if no linked object was found (useful to branch logic), while the action variant always succeeds even if nothing is picked.
 
-    Some of the conditions of Linked Objects are available as both, conditions as well as actions. Conditions will be considered as false if no object is picked. If you don't want this behavior, use their action counterparts.
+## Linking objects
 
+Use the **Link two objects** action to create a connection between instances. Links are set up once — typically when an object is created — and then used repeatedly throughout the game. A single object can be linked to many others, and there is no hard limit on the number of links.
 
-#### Link two objects
+## Picking linked objects
 
-This action creates links between the object(s) in the first parameter and the object(s) in the second parameter.
+Use **Take into account linked objects** to narrow the current object selection to only instances that are linked to another specific set of objects. The picked instances then carry forward into the next actions and sub-events. This is the core mechanism for acting on relationships, for example: "for each enemy, deal damage to the health bar linked to that enemy."
 
-#### Take into account linked objects
+When used as a **condition**, it also returns false if nothing was picked — useful for checking whether a link exists at all before acting on it.
 
-There is both an action and a condition called "Take into account linked objects".
+## Removing links
 
-This action scans through the objects in the first parameters and for each one, if there is a link registered from it to any of the objects in the second parameter, they will be picked for the next actions. After executing this action, the actions that are executed next (as well as the subevents) will only execute on the objects that were picked.
+- **Unlink two objects** removes the connection between a specific pair of instances.
+- **Unlink all objects from an object** removes every link associated with the given instance(s).
 
-The condition works the same in all cases, except if no object was picked (i.e: no object in the first parameter had a link to any object in the second parameter). In such a case, the condition will be false.
+When an object is **deleted from the scene**, all its links are automatically cleaned up so that other objects no longer point to the removed instance.
 
-#### Unlink all objects from an object
+## Use cases
 
-This action removes all links to the specified object(s). They won't be virtually linked to any other objects.
+Linked objects are well suited for **permanent one-to-one or one-to-many relationships** that would be cumbersome to track with variables:
 
-#### Unlink two objects
+- Attach a health bar object to a character and always update the correct bar.
+- Link equipment items to the character currently holding them.
+- Connect terrain tiles to the pathfinder or enemy that "owns" them, so the terrain follows when the owner moves.
+- Build graph structures for AI, where each node object is linked to its neighbours.
 
-This action removes the links between the given pair of objects.
+!!! tip
+
+    For grid-based linking (rectangular, hexagonal, or isometric grids) and graph traversal, see the [Linked Objects Tools extension](/gdevelop5/all-features/extensions/linked-objects-tools).
 
-### Examples
+## Examples
 
 In this example, for every existing "Pathfinder" object, a new "Terrain" object is created.  This creation and linking step only needs to be performed one time.  The bottom event is run every frame and will cause the "Terrain" objects to always follow the "Pathfinder" object they are linked to.