From f0a656e8f78c017ea3623995aa221417fb4557e1 Mon Sep 17 00:00:00 2001
From: 4ian <1280130+4ian@users.noreply.github.com>
Date: Thu, 30 Jul 2026 10:50:11 +0000
Subject: [PATCH] [Auto] [Improve] Documented P2P readiness, connection
 detection, sending/receiving data, and error handling

---
 automated_updates_data.json              |  4 ++++
 docs/gdevelop5/all-features/p2p/index.md | 22 ++++++++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/automated_updates_data.json b/automated_updates_data.json
index 2fa8e494dbb..57e8260e224 100644
--- a/automated_updates_data.json
+++ b/automated_updates_data.json
@@ -104,6 +104,10 @@
     {
       "date": "2026-07-07",
       "summary": "Improved keyboard docs: added 'Key just pressed' (held vs one-frame) and 'Any key released' conditions, control-remapping note, and a reference list of valid key names"
+    },
+    {
+      "date": "2026-07-30",
+      "summary": "Improved P2P docs: documented waiting for 'Is P2P ready', detecting peer connect/disconnect, sending/receiving extra data via text and variables, and error handling"
     }
   ]
 }
diff --git a/docs/gdevelop5/all-features/p2p/index.md b/docs/gdevelop5/all-features/p2p/index.md
index c348c0774a8..096e47530ba 100644
--- a/docs/gdevelop5/all-features/p2p/index.md
+++ b/docs/gdevelop5/all-features/p2p/index.md
@@ -67,6 +67,14 @@ To use that server use the action "Use the default server".
 
 To connect instances, you need to enter their ID in the other instances. The ID can be found with the expression `P2P::GetID()`. To connect, use the "Connect to other instance" action and pass as a parameter the ID of another instance. Both instances will then connect automatically. You can then send an event from one instance to the other one to make sure that the connection is established.
 
+!!! tip
+
+    The extension needs a moment to initialize when the game starts. Use the **Is P2P ready** condition to wait until the client has been assigned an ID before reading `P2P::GetID()` or connecting to other clients.
+
+### Detecting when clients connect or disconnect
+
+Use the **Peer connected** and **Peer disconnected** conditions to react when another client joins or leaves. The `P2P::GetLastConnectedPeer()` and `P2P::GetLastDisconnectedPeer()` expressions return the ID of the client that just connected or disconnected, which is convenient to keep an up-to-date list of the currently connected players. To close connections yourself, use the **Disconnect from a peer**, **Disconnect from all peers** or **Disconnect from all** actions.
+
 ### Changing the ID generation
 
 The default P2P ID generation is very long to avoid conflicts, but if you want to have an easily shareable ID, it is not ideal. You can use a custom ID generation on your custom P2P broker by following [the instructions on the peerjs-server documentation](https://github.com/peers/peerjs-server#custom-client-id-generation).
@@ -75,6 +83,16 @@ The default P2P ID generation is very long to avoid conflicts, but if you want t
 
 Once you got connected, you can trigger actions remotely. You can select another specific game instance (using its id) or send an event to all connected instances.
 
+### Sending and receiving data
+
+When triggering an event on other clients, you can attach some **extra data** to it. This data can either be a piece of text passed directly in the action, or the content of a variable (using the "(variable)" variants of the actions, which lets you send structures and arrays).
+
+On the receiving client, use the **Event triggered by peer** condition to detect that an event was received, then read the data that came with it:
+
+  * `P2P::GetEventData(eventName)` returns the text that was sent.
+  * The **Get event data (variable)** action copies the received variable (including structures and arrays) into one of your own variables.
+  * `P2P::GetEventSender(eventName)` returns the ID of the client that sent the event, so you can reply to that specific client.
+
 ### Choosing if you want to activate data loss mode
 
 You might be wondering what the "data loss" parameter is for.
@@ -89,6 +107,10 @@ Here are two examples:
 * if you use a synchronized score counter, you don't want to lose any data, as missing only one point of the counter would *desynchronize* the counters, so the dataloss mode would be deactivated.
 * If you want to synchronize positions, only the last position sent is relevant, not older positions. In this case, you would activate the dataloss mode *to prevent delays/lags*.
 
+## Handling errors
+
+Use the **An error occurred** condition to detect connection problems, for example when the broker server is unreachable. The `P2P::GetLastError()` expression returns a description of the last error, which you can log or display to the player.
+
 ## Reference
 
 All actions, conditions and expressions are listed in [the peer-to-peer reference page](/gdevelop5/all-features/p2p/reference/).
\ No newline at end of file