Skip to content

Commit be4846c

Browse files
DA-344AlmostSuspenseanthonydiscord
authored
Document role gradient colors (#7549)
* feat: document role gradient colors * object * comma * features and more clear docs * tables * typo on permissions.md Co-authored-by: Suspense <64612795+AlmostSuspense@users.noreply.github.com> * add note about holographic style * Reword info block on RoleColors Co-authored-by: Anthony <anthony.tesija@discordapp.com> * 's Co-authored-by: Anthony <anthony.tesija@discordapp.com> * Update based on the review * 's Co-authored-by: Anthony <anthony.tesija@discordapp.com> * apply suggestions and fix tables --------- Co-authored-by: Suspense <64612795+AlmostSuspense@users.noreply.github.com> Co-authored-by: Anthony <anthony.tesija@discordapp.com>
1 parent 2b0ba97 commit be4846c

File tree

2 files changed

+77
-32
lines changed

2 files changed

+77
-32
lines changed

‎docs/resources/guild.mdx‎

Lines changed: 30 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,7 @@ Fields specific to the `GUILD_CREATE` event are listed in the [Gateway Events do
159159
| VERIFIED | guild is verified |
160160
| VIP_REGIONS | guild has access to set 384kbps bitrate in voice (previously VIP voice servers) |
161161
| WELCOME_SCREEN_ENABLED | guild has enabled the welcome screen |
162+
| ENHANCED_ROLE_COLORS | guild is able to set gradient colors to roles |
162163

163164
###### Mutable Guild Features
164165

@@ -824,6 +825,11 @@ Returns the [guild](/docs/resources/guild#guild-object) object for the given id.
824825
"permissions": "49794752",
825826
"position": 0,
826827
"color": 0,
828+
"colors": {
829+
"primary_color": 0,
830+
"secondary_color": null,
831+
"tertiary_color": null
832+
},
827833
"hoist": false,
828834
"managed": false,
829835
"mentionable": false
@@ -1225,15 +1231,18 @@ This endpoint supports the `X-Audit-Log-Reason` header.
12251231

12261232
###### JSON Params
12271233

1228-
| Field | Type | Description | Default |
1229-
|---------------|-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------|
1230-
| name | string | name of the role, max 100 characters | "new role" |
1231-
| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild |
1232-
| color | integer | RGB color value | 0 |
1233-
| hoist | boolean | whether the role should be displayed separately in the sidebar | false |
1234-
| icon | ?[image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) | null |
1235-
| unicode_emoji | ?string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) | null |
1236-
| mentionable | boolean | whether the role should be mentionable | false |
1234+
| Field | Type | Description | Default |
1235+
|---------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
1236+
| name | string | name of the role, max 100 characters | "new role" |
1237+
| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild |
1238+
| color* | integer | RGB color value | 0 |
1239+
| colors | [role colors](/docs/topics/permissions#role-object-role-colors-object) object | the role's colors | [default role colors object](/docs/topics/permissions#role-object-default-role-colors-object) |
1240+
| hoist | boolean | whether the role should be displayed separately in the sidebar | false |
1241+
| icon | ?[image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) | null |
1242+
| unicode_emoji | ?string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) | null |
1243+
| mentionable | boolean | whether the role should be mentionable | false |
1244+
1245+
\* `color` will still be returned by the API, but using the `colors` field is recommended when doing requests.
12371246

12381247
## Modify Guild Role Positions
12391248
<Route method="PATCH">/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/roles</Route>
@@ -1268,15 +1277,18 @@ This endpoint supports the `X-Audit-Log-Reason` header.
12681277

12691278
###### JSON Params
12701279

1271-
| Field | Type | Description |
1272-
|---------------|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
1273-
| name | string | name of the role, max 100 characters |
1274-
| permissions | string | bitwise value of the enabled/disabled permissions |
1275-
| color | integer | RGB color value |
1276-
| hoist | boolean | whether the role should be displayed separately in the sidebar |
1277-
| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
1278-
| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
1279-
| mentionable | boolean | whether the role should be mentionable |
1280+
| Field | Type | Description |
1281+
|---------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
1282+
| name | string | name of the role, max 100 characters |
1283+
| permissions | string | bitwise value of the enabled/disabled permissions |
1284+
| color* | integer | RGB color value |
1285+
| colors | [role colors](/docs/topics/permissions#role-object-role-colors-object) object | the role's colors |
1286+
| hoist | boolean | whether the role should be displayed separately in the sidebar |
1287+
| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
1288+
| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
1289+
| mentionable | boolean | whether the role should be mentionable |
1290+
1291+
\* `color` will still be returned by the API, but using the `colors` field is recommended when doing requests.
12801292

12811293
## Modify Guild MFA Level
12821294
<Route method="POST">/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/mfa</Route>

‎docs/topics/permissions.md‎

Lines changed: 47 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -203,23 +203,26 @@ Roles represent a set of permissions attached to a group of users. Roles have na
203203

204204
###### Role Structure
205205

206-
| Field | Type | Description |
207-
|----------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
208-
| id | snowflake | role id |
209-
| name | string | role name |
210-
| color | integer | integer representation of hexadecimal color code |
211-
| hoist | boolean | if this role is pinned in the user listing |
212-
| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
213-
| unicode_emoji? | ?string | role unicode emoji |
214-
| position | integer | position of this role (roles with the same position are sorted by id) |
215-
| permissions | string | permission bit set |
216-
| managed | boolean | whether this role is managed by an integration |
217-
| mentionable | boolean | whether this role is mentionable |
218-
| tags? | [role tags](/docs/topics/permissions#role-object-role-tags-structure) object | the tags this role has |
219-
| flags | integer | [role flags](/docs/topics/permissions#role-object-role-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
206+
| Field | Type | Description |
207+
|----------------|-------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
208+
| id | snowflake | role id |
209+
| name | string | role name |
210+
| color* | integer | integer representation of hexadecimal color code |
211+
| colors | [role colors](/docs/topics/permissions#role-object-role-colors-object) object | the role's colors |
212+
| hoist | boolean | if this role is pinned in the user listing |
213+
| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
214+
| unicode_emoji? | ?string | role unicode emoji |
215+
| position | integer | position of this role (roles with the same position are sorted by id) |
216+
| permissions | string | permission bit set |
217+
| managed | boolean | whether this role is managed by an integration |
218+
| mentionable | boolean | whether this role is mentionable |
219+
| tags? | [role tags](/docs/topics/permissions#role-object-role-tags-structure) object | the tags this role has |
220+
| flags | integer | [role flags](/docs/topics/permissions#role-object-role-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
220221

221222
Roles without colors (`color == 0`) do not count towards the final computed color in the user list.
222223

224+
\* `color` will still be returned by the API, but using the `colors` field is recommended when doing requests.
225+
223226
###### Role Tags Structure
224227

225228
Tags with type `null` represent booleans. They will be present and set to `null` if they are "true", and will be not present if they are "false".
@@ -233,13 +236,43 @@ Tags with type `null` represent booleans. They will be present and set to `null`
233236
| available_for_purchase? | null | whether this role is available for purchase |
234237
| guild_connections? | null | whether this role is a guild's linked role |
235238

239+
###### Role Colors Object
240+
241+
This object will always be filled with `primary_color` being the role's `color`. Other fields can only be set to a non-null value if the guild has the `ENHANCED_ROLE_COLORS` [guild feature](/docs/resources/guild#guild-object-guild-features).
242+
243+
| Field | Type | Description |
244+
|-----------------|----------|--------------------------------------------------------------------------------------------------------|
245+
| primary_color | integer | the primary color for the role |
246+
| secondary_color | ?integer | the secondary color for the role, this will make the role a gradient between the other provided colors |
247+
| tertiary_color | ?integer | the tertiary color for the role, this will turn the gradient into a holographic style |
248+
249+
:::info
250+
When sending `tertiary_color` the API enforces the role color to be a holographic style with values of:
251+
`primary_color = 11127295`, `secondary_color = 16759788`, and `tertiary_color = 16761760`.
252+
:::
253+
254+
###### Default Role Colors Object
255+
256+
```json
257+
"colors": {
258+
"primary_color": 0,
259+
"secondary_color": null,
260+
"tertiary_color": null
261+
}
262+
```
263+
236264
###### Example Role
237265

238266
```json
239267
{
240268
"id": "41771983423143936",
241269
"name": "WE DEM BOYZZ!!!!!!",
242270
"color": 3447003,
271+
"colors": {
272+
"primary_color": 3447003,
273+
"secondary_color": null,
274+
"tertiary_color": null
275+
},
243276
"hoist": true,
244277
"icon": "cf3ced8600b777c9486c6d8d84fb4327",
245278
"unicode_emoji": null,

0 commit comments

Comments
 (0)