From 602df8ab476b968b21f0b86a59a622cfb86de083 Mon Sep 17 00:00:00 2001 From: Colin Loretz Date: Tue, 17 Jun 2025 19:52:01 +0000 Subject: [PATCH 1/4] Added Social SDK How To categry --- docs/discord-social-sdk/how-to.mdx | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 docs/discord-social-sdk/how-to.mdx diff --git a/docs/discord-social-sdk/how-to.mdx b/docs/discord-social-sdk/how-to.mdx new file mode 100644 index 0000000000..59600f4476 --- /dev/null +++ b/docs/discord-social-sdk/how-to.mdx @@ -0,0 +1,19 @@ +--- +sidebar_label: How To +showTOC: false +subpages: +--- + +[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > How To + +# Discord Social SDK How To Guides + +These how-to guides offer common solutions for integrating Discord Social SDK features into your game. + +--- + +## Change Log + +| Date | Changes | +|---------------|-----------------------| +| June 17, 2025 | added How To category | \ No newline at end of file From 90e75a29eb1a11882595990cc8977221a51eadc5 Mon Sep 17 00:00:00 2001 From: Colin Loretz Date: Tue, 17 Jun 2025 19:52:31 +0000 Subject: [PATCH 2/4] Add handling special characters --- docs/discord-social-sdk/how-to.mdx | 7 +++ ...andle-special-characters-display-names.mdx | 49 +++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 docs/discord-social-sdk/how-to/handle-special-characters-display-names.mdx diff --git a/docs/discord-social-sdk/how-to.mdx b/docs/discord-social-sdk/how-to.mdx index 59600f4476..803de097ba 100644 --- a/docs/discord-social-sdk/how-to.mdx +++ b/docs/discord-social-sdk/how-to.mdx @@ -2,6 +2,7 @@ sidebar_label: How To showTOC: false subpages: + - how-to/handle-special-characters-display-names.mdx --- [Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > How To @@ -10,6 +11,12 @@ subpages: These how-to guides offer common solutions for integrating Discord Social SDK features into your game. + + + Handling Unicode characters in Discord Display Names for your game's chat and friend lists. + + + --- ## Change Log diff --git a/docs/discord-social-sdk/how-to/handle-special-characters-display-names.mdx b/docs/discord-social-sdk/how-to/handle-special-characters-display-names.mdx new file mode 100644 index 0000000000..ca7331c147 --- /dev/null +++ b/docs/discord-social-sdk/how-to/handle-special-characters-display-names.mdx @@ -0,0 +1,49 @@ +--- +sidebar_label: Handle Special Characters in Display Names +--- + +[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [How To](/docs/discord-social-sdk/how-to) > {sidebar_label} + +# How To {sidebar_label} + +The Social SDK [recommends](https://discord.com/developers/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list#step-1-fetch-relationships) using an account's [Display Name](https://discord.com/developers/docs/slayer-sdk/classdiscordpp_1_1UserHandle.html#af6447fa2011bfa4fcd7e55bc56847f5c) in the Unified Friends List. However, Display Names support a large set of characters across the Unicode spec, and some of these characters may not be supported in a game's specified font. + +There are several options to address this: + +## 1. Map the Unicode characters to ASCII + +A library such as [Unidecode](https://metacpan.org/pod/Text::Unidecode) (which has been ported to many different languages) can map many Unicode characters to an ASCII equivalent. If you detect that a Display Name has characters that cannot be rendered, consider passing it through a library to transliterate the Display Name to ASCII. + +**Tradeoffs:** + +- This may result in unintended transliterations. It is impossible to create a perfect mapping between Unicode and ASCII in every situation. Libraries try their best, but this approach may unintentionally create an inaccurate or even offensive display name in some instances. +- Libraries will not have 100% coverage. Some Unicode characters may not have a map to an ASCII character. If someone's Display Name is `ʕ•͡-•ʔ` what would it map to? +- Similarly, most libraries assume English is the target language. +- Users may not appreciate their display names being changed without their knowledge or consent. + +## 2. Use a font family that supports Unicode + +A family such as [Noto](https://notofonts.github.io/) aims to have broad Unicode support. If a font cannot render a Display Name, consider rendering it with a fallback font, or in the extreme case, choose a font with broad Unicode support for the Friends List. + +**Tradeoffs:** + +- One font family may not include 100% overlap with what Discord supports. +- A font that supports Unicode may not mesh with your game's aesthetics. +- Engine support is limited, especially for characters that rely on UTF surrogate pairs. + +## 3. Use the Discord Username as a Fallback + +If a Display Name is not renderable at all, consider falling back to the user's [`Username`](https://discord.com/developers/docs/slayer-sdk/classdiscordpp_1_1UserHandle.html#a0eda41fe18b50bce373fb5a1b88cb411). + +**Tradeoffs:** + +- This can break immersion in a game if a friend had expected to rely on their Display Name from within the game. +- Some users consider their Username to be more private information and do not expect it to be shared by others (such as when someone is streaming and their friends list is visible). + +--- + +## Change Log + +| Date | Changes | +|---------------|---------------------------------| +| June 17, 2025 | special characters how-to added | \ No newline at end of file From 42f61c249c1606e2fa7010d042309fcc23c9639e Mon Sep 17 00:00:00 2001 From: Colin Loretz Date: Tue, 17 Jun 2025 19:53:03 +0000 Subject: [PATCH 3/4] refer to character handling in UFL design guide --- .../design-guidelines/unified-friends-list.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/discord-social-sdk/design-guidelines/unified-friends-list.mdx b/docs/discord-social-sdk/design-guidelines/unified-friends-list.mdx index cae326ccc5..c72b2a4a09 100644 --- a/docs/discord-social-sdk/design-guidelines/unified-friends-list.mdx +++ b/docs/discord-social-sdk/design-guidelines/unified-friends-list.mdx @@ -65,6 +65,10 @@ It's also **scalable** and **inclusive** of provisional accounts who do not have When referring to a player's Discord Identity, please use their **Discord Display Name**, and not their username. +:::info +See [How to Manage Special Characters in Discord Display Names](/docs/discord-social-sdk/how-to/handle-special-characters-display-names) for guidance on handling special characters in text chat and friend lists. +::: + ![Discord display names](images/social-sdk/design-guidelines/UFL-07.png) ## Scaling to Multiple Platforms From 22486b681b5eb9360c4385db5335d68a7043c9d1 Mon Sep 17 00:00:00 2001 From: Colin Loretz Date: Wed, 18 Jun 2025 00:16:48 +0000 Subject: [PATCH 4/4] Reorder and drop numbers. Not in ranked order --- ...andle-special-characters-display-names.mdx | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/discord-social-sdk/how-to/handle-special-characters-display-names.mdx b/docs/discord-social-sdk/how-to/handle-special-characters-display-names.mdx index ca7331c147..5d1bce7a45 100644 --- a/docs/discord-social-sdk/how-to/handle-special-characters-display-names.mdx +++ b/docs/discord-social-sdk/how-to/handle-special-characters-display-names.mdx @@ -10,7 +10,17 @@ The Social SDK [recommends](https://discord.com/developers/docs/discord-social-s There are several options to address this: -## 1. Map the Unicode characters to ASCII +## Use a font family that supports Unicode + +A family such as [Noto](https://notofonts.github.io/) aims to have broad Unicode support. If a font cannot render a Display Name, consider rendering it with a fallback font, or in the extreme case, choose a font with broad Unicode support for the Friends List. + +**Tradeoffs:** + +- One font family may not include 100% overlap with what Discord supports. +- A font that supports Unicode may not mesh with your game's aesthetics. +- Engine support is limited, especially for characters that rely on UTF surrogate pairs. + +## Map the Unicode characters to ASCII A library such as [Unidecode](https://metacpan.org/pod/Text::Unidecode) (which has been ported to many different languages) can map many Unicode characters to an ASCII equivalent. If you detect that a Display Name has characters that cannot be rendered, consider passing it through a library to transliterate the Display Name to ASCII. @@ -21,17 +31,8 @@ A library such as [Unidecode](https://metacpan.org/pod/Text::Unidecode) (which h - Similarly, most libraries assume English is the target language. - Users may not appreciate their display names being changed without their knowledge or consent. -## 2. Use a font family that supports Unicode - -A family such as [Noto](https://notofonts.github.io/) aims to have broad Unicode support. If a font cannot render a Display Name, consider rendering it with a fallback font, or in the extreme case, choose a font with broad Unicode support for the Friends List. - -**Tradeoffs:** - -- One font family may not include 100% overlap with what Discord supports. -- A font that supports Unicode may not mesh with your game's aesthetics. -- Engine support is limited, especially for characters that rely on UTF surrogate pairs. -## 3. Use the Discord Username as a Fallback +## Use the Discord Username as a Fallback If a Display Name is not renderable at all, consider falling back to the user's [`Username`](https://discord.com/developers/docs/slayer-sdk/classdiscordpp_1_1UserHandle.html#a0eda41fe18b50bce373fb5a1b88cb411).