From 4be5de05aba2f5fa65f6c1ce20269107e6bcffbb Mon Sep 17 00:00:00 2001
From: Joyless <65855333+Joy-less@users.noreply.github.com>
Date: Fri, 27 Jun 2025 01:01:19 +0100
Subject: [PATCH] Clarify `visible_characters`

Includes updates by @AThousandShips.

Co-Authored-By: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com>
---
 doc/classes/Label.xml         | 1 +
 doc/classes/RichTextLabel.xml | 1 +
 2 files changed, 2 insertions(+)

diff --git a/doc/classes/Label.xml b/doc/classes/Label.xml
index bb4581c1ca5..e0bae5cfeb7 100644
--- a/doc/classes/Label.xml
+++ b/doc/classes/Label.xml
@@ -108,6 +108,7 @@
 		<member name="visible_characters" type="int" setter="set_visible_characters" getter="get_visible_characters" default="-1">
 			The number of characters to display. If set to [code]-1[/code], all characters are displayed. This can be useful when animating the text appearing in a dialog box.
 			[b]Note:[/b] Setting this property updates [member visible_ratio] accordingly.
+			[b]Note:[/b] Characters are counted as Unicode codepoints. A single visible grapheme may contain multiple codepoints (e.g. certain emoji use three codepoints). A single codepoint may contain two UTF-16 characters, which are used in C# strings.
 		</member>
 		<member name="visible_characters_behavior" type="int" setter="set_visible_characters_behavior" getter="get_visible_characters_behavior" enum="TextServer.VisibleCharactersBehavior" default="0">
 			The clipping behavior when [member visible_characters] or [member visible_ratio] is set.
diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml
index c79880a5ceb..1ebddf384f2 100644
--- a/doc/classes/RichTextLabel.xml
+++ b/doc/classes/RichTextLabel.xml
@@ -763,6 +763,7 @@
 		<member name="visible_characters" type="int" setter="set_visible_characters" getter="get_visible_characters" default="-1">
 			The number of characters to display. If set to [code]-1[/code], all characters are displayed. This can be useful when animating the text appearing in a dialog box.
 			[b]Note:[/b] Setting this property updates [member visible_ratio] accordingly.
+			[b]Note:[/b] Characters are counted as Unicode codepoints. A single visible grapheme may contain multiple codepoints (e.g. certain emoji use three codepoints). A single codepoint may contain two UTF-16 characters, which are used in C# strings.
 		</member>
 		<member name="visible_characters_behavior" type="int" setter="set_visible_characters_behavior" getter="get_visible_characters_behavior" enum="TextServer.VisibleCharactersBehavior" default="0">
 			The clipping behavior when [member visible_characters] or [member visible_ratio] is set.