From 73481ce29e73ab53c10bfb5715c73eb7c8600f31 Mon Sep 17 00:00:00 2001
From: 4ian <1280130+4ian@users.noreply.github.com>
Date: Fri, 3 Jul 2026 11:01:39 +0000
Subject: [PATCH] [Auto] [Improve] Keyboard docs: touchscreen caveat, Key just
 pressed vs held, and key-name guidance

---
 automated_updates_data.json                   |  4 +++
 docs/gdevelop5/all-features/keyboard/index.md | 25 +++++++++++++++++--
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/automated_updates_data.json b/automated_updates_data.json
index 2e22d59783d..9f9d835f526 100644
--- a/automated_updates_data.json
+++ b/automated_updates_data.json
@@ -96,6 +96,10 @@
     {
       "date": "2026-06-24",
       "summary": "Improved window docs: distinguished game resolution from window size, documented resize mode and auto-adapt, added center window and window icon actions, and listed scene/screen size expressions"
+    },
+    {
+      "date": "2026-07-03",
+      "summary": "Improved keyboard docs: added touchscreen caveat, documented 'Key just pressed' vs held 'Key pressed', 'Any key released', and key-name spelling guidance"
     }
   ]
 }
diff --git a/docs/gdevelop5/all-features/keyboard/index.md b/docs/gdevelop5/all-features/keyboard/index.md
index a939ed6bcbe..55889af0aed 100644
--- a/docs/gdevelop5/all-features/keyboard/index.md
+++ b/docs/gdevelop5/all-features/keyboard/index.md
@@ -5,13 +5,25 @@ title: Keyboard
 
 GDevelop gives access to all inputs made on the keyboard. This includes conditions to check if a key was pressed or released.
 
+!!! warning
+
+    Keyboard conditions do **not** work with the on-screen keyboard shown on touchscreen devices. When making a game for mobile or touchscreen, use the [mouse/touch conditions](/gdevelop5/all-features/mouse-touch) instead, or add on-screen buttons.
+
 ## Any key pressed
 
 For this condition, the corresponding action/s will be performed if any key on the keyboard is pressed.
 
+## Any key released
+
+The corresponding actions are performed on the frame any key on the keyboard is released.
+
 ## Key pressed
 
-Whenever the key selected while setting this condition is pressed, the corresponding actions are performed.
+Whenever the key selected while setting this condition is pressed, the corresponding actions are performed. This condition stays true for as long as the key is held down, so its actions run on every frame while the key remains pressed.
+
+## Key just pressed
+
+This condition is true only on the single frame the key goes down, no matter how long the key is then held. Use it for one-shot actions — opening a menu, firing a shot, jumping — where "Key pressed" would otherwise repeat the action every frame.
 
 ## Key released
 
@@ -19,12 +31,21 @@ Whenever the key selected while setting this condition is released, the correspo
 
 ## Key pressed (text expression)
 
-To test a key press using this condition, you need to enter the key name in the form of text expression. For example, if you want to check condition for left arrow key press, you need to enter "Left" in the field.
+To test a key press using this condition, you need to enter the key name in the form of text expression. For example, if you want to check condition for left arrow key press, you need to enter "Left" in the field. This is useful when the key to check is not fixed but comes from a variable (for example a rebindable control stored in a variable).
 
 !!! danger
 
     Make sure that the key name is surrounded by quotes.
 
+Key names follow GDevelop's own spelling, which is not always the label printed on the key. Some common examples:
+
+* Letters are lowercase: `"a"`, `"b"`, … `"z"`.
+* Arrow keys: `"Left"`, `"Right"`, `"Up"`, `"Down"`.
+* `"Space"`, `"Return"` (Enter), `"Escape"`, `"Tab"`, `"Back"` (Backspace), `"Delete"`, `"Shift"` modifiers are `"LShift"`/`"RShift"`, control is `"LControl"`/`"RControl"`, and alt is `"LAlt"`/`"RAlt"`.
+* Number row keys are `"Num0"` … `"Num9"`, while the numeric keypad uses `"Numpad0"` … `"Numpad9"`.
+
+When picking a key from the dropdown of the standard "Key pressed" condition, GDevelop fills in the right name for you.
+
 ![](/gdevelop5/all-features/annotation_2019-06-20_191229.png)
 
 ## Key released (text expression)