Skip to content

Commit

Permalink
Update Ascension placeholder documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@Vankka
Vankka committed Aug 3, 2024
1 parent a9cc5ae commit 2b53a6e
Showing 1 changed file with 113 additions and 35 deletions.
148 changes: 113 additions & 35 deletions docs/ascension/placeholders.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,25 @@ DiscordSRV contains many placeholders which allows you to customise messages ent
Information about which placeholders can be used where can be found in the config.

---
# Formatting
## Formatting

:::info General Formatting Help
Information on formatting Minecraft messages can be found [here](https://github.com/Vankka/EnhancedLegacyText/wiki/Format).

Information on Discord markdown can be found [here](https://support.discord.com/hc/en-us/articles/210298617)
:::

## Checking for empty placeholders
### Checking for empty placeholders
You can take empty placeholders into account and use an alternate placeholder instead.

For example `%player_meta_prefix|player_prefix%`. This first looks for `%player_meta_prefix%` if that is empty, than `%player_prefix%` is used instead.

## Placeholder Suffixes
### Placeholder Suffixes
Placeholders which provide a list of items can have a suffix set between each item to separate them.

For example `%user_roles:', '%`, lists the users roles seperated by a comma and a space (`', '`).

## Recursive Placeholders
### Recursive Placeholders
Recursive placeholders are a special type of placeholder which allow you to specify what information you want from it.

In this example we will be using `%user_highest_role_<role>%`. The `%user_highest_role_` part returns the highest role of the user and turns it into a [role placeholder](#role).
Expand All @@ -36,8 +36,12 @@ You can then use any [role](#role) related placeholders. For example `%user_high
This same premise is used for all the re lookup placeholders.

---
# Discord
## User
## Discord
### User
#### `%user_id%`
The ID for the Discord user
Example value: `185828288466255874`

#### `%user_name%`
The username of the Discord user
Example value: `myusername1`
Expand All @@ -62,7 +66,7 @@ Example value: `https://cdn.discordapp.com/avatars/827880927199494164/bdde9008a6
The Discord user's avatar that is currently active (if they do not have one set, this will provide the default Discord avatar)
Example value: `https://cdn.discordapp.com/avatars/827880927199494164/bdde9008a644ecc62d97c6f9153462c7.webp?size=64`

## Member
### User (Server Member)
#### `%user_effective_server_name%`
The nickname name of this Discord server member
Example value: `My cool nickname`
Expand All @@ -72,13 +76,21 @@ The avatar url that that is active for this server member
Example value: `https://cdn.discordapp.com/avatars/827880927199494164/bdde9008a644ecc62d97c6f9153462c7.webp?size=64`

#### `%user_color%`
The color of the user's highest role that has a color. May be used with [color](#color) subplaceholders.
The color of the user's highest role that has a color. May be used with [color](#color) subplaceholders.
Example usages: `%user_color%`, `%user_color_hex%`

#### `%user_isboosting%`
Whether this member is currently boosting the server
Example values: `false`, `true`

#### `%user_time_boosted%`
The time the user started boosting, use with [date formatting](#date-formatting)
Example usage: `%user_time_boosted:'dd-MM-yyyy'%`

#### `%user_time_joined%`
The time the user started joined, use with [date formatting](#date-formatting)
Example usage: `%user_time_joined:'dd-MM-yyyy%`

#### `%user_highest_role_<subplaceholder>%`
The highest role of the member. Replace `<subplaceholder>` with any of the [role](#role) placeholders. More information about recursive placeholders [here](#recursive-placeholders)
Example usages: `%user_highest_role_name%`, `%user_highest_role_color%`
Expand All @@ -91,7 +103,19 @@ Example usages: `%user_hoisted_role_name%`, `%user_hoisted_role_color%`
The roles of the member. You can specify the separator for multiple roles as a suffix, more information can be found [here](#placeholder-suffixes)
Example usages: `%user_roles%`, `%user_roles:', '%`

## Message
#### `%user_server%`
The server for user membership, for using [Server](#server) placeholders
Example usage: `%user_server_name%`

### Message
#### `%message_id%`
The id of message
Example value: `135796844314886144`

#### `%message_content%`
The content of the message
Example value: `Hello`

#### `%message_jump_url%`
The URL to jump to this message
Example value: `https://discord.com/channels/135634590575493120/137421286501646336/1228806460172140616`
Expand All @@ -103,7 +127,23 @@ The format for messages which contain a reply. The format for the content of thi
The attachments in the message sent. The format for the content of this placeholder can be edited in the config (`channels.*.discord-to-minecraft.attachment-format`). You can specify the separator for multiple attachments as a suffix, more information can be found [here](#placeholder-suffixes)
Example usages: `%message_attachments%`, `%message_attachments:', '%`

## Role
#### `%message_server%`
The server this message was sent in, if any, for using [Server](#server) placeholders
Example usage: `%message_server_name%`

#### `%message_user%`
The user that sent this message, for using [User](#user) placeholders
Example usage: `%message_user_name%`

#### `%message_channel%`
The channel this message was sent in, for using [Channel](#channel) placeholders
Example usage: `%message_channel_name%`

### Role
#### `%role_id%`
The id of the role
Example value: `135634730535092224`

#### `%role_name%`
The name of the Discord role
Example value: `Moderator`
Expand All @@ -112,7 +152,15 @@ Example value: `Moderator`
The color of the Discord role. May be used with [color](#color) subplaceholders.
Example usages: `%role_color%`, `%role_color_hex%`

## Channel
#### `%role_server%`
The server of the role, for using [Server](#server) placeholders
Example usage: `%role_server_name%`

### Channel
#### `%channel_id%`
The id of the channel
Example value: `137421286501646336`

#### `%channel_name%`
The name of the channel
Example value: `discordsrv-test-chat`
Expand All @@ -121,37 +169,34 @@ Example value: `discordsrv-test-chat`
The jump url of the channel
Example value: `https://discord.com/channels/135634590575493120/137421286501646336`

## Server
### Server
#### `%server_id%`
The id of the Discord server
Example value: `135634590575493120`

#### `%server_name%`
The name of the Discord guild
The name of the Discord server
Example value: `My Awesome Server`

#### `%server_member_count%`
The member count of the guild
The member count of the Discord server
Example value: `107`

## Global
#### `%discord_invite%`
The invite of your Discord server (this is either provided by you in the config, or DiscordSRV auto generates it for you)
Example value: `https://discord.gg/HGAdJEumxC`

---
# Minecraft
## Player
## Minecraft
### Player
#### `%player_name%`
The username of the Minecraft player
Example value: `Notch`

#### `%player_uuid%`
The UUID of the Minecraft player
The UUID of the Minecraft player, may also use [UUID](#uuid) placeholders
Example usages: `%player_uuid%`, `%player_uuid_short%`
Example value: `069a79f4-44e9-4726-a5be-fca90e38aaf5`

#### `%player_uuid_nodashes%`
The UUID of the Minecraft player without any dashes
Example value: `069a79f444e94726a5befca90e38aaf5`

#### `%player_texture%`
The texture of the Minecraft player (not implemented yet)
#### `%player_skin%`
The skin information of the Minecraft player for use with [Skin](#skin)
Example usages: `%player_skin_texture_id%`, `%player_skin_model%`

#### `%player_avatar_url%`
The avatar url of the Minecraft player (the API used for this can be changed in the config (`avatar-provider.avatar-url-template`))
Expand All @@ -161,7 +206,7 @@ The meta prefix of the Minecraft player (set using the [LuckPerms meta] key `dis
Example value: `Mod `

#### `%player_meta_suffix%`
The meta suffix of the Minecraft player (set using the [LuckPerms meta] key `discordsrv_suffix`)
The meta suffix of the Minecraft player (set using the [LuckPerms meta] key `discordsrv_suffix`)
Example value: ` Staff Member`

#### `%player_prefix%`
Expand All @@ -172,6 +217,15 @@ Example value: `[Mod] `
The suffix of the Minecraft player
Example value: ` (Staff Member)`

### Skin
#### `%skin_texture_id%`
The texture id for the skin
Example value: `5183d47698a28e20b6c3c6d9b8a8a33449c866cff50d725a53260bd6a5ae0b64`

#### `%skin_model%`
The model of the skin
Example value: `slim`

---

## Color
Expand All @@ -195,15 +249,39 @@ Example value: `105`
The blue value for the color
Example value: `180`

## UUID
#### `%uuid_short%`
The UUID without any dashes
Example value: `069a79f444e94726a5befca90e38aaf5`

#### `%uuid_version%`
The version of the UUID
Example value: `4`

#### `%uuid_isgeyser%`
If the UUID is from a [Geyser](https://geysermc.org/wiki/geyser/) player using [Floodgate authentication](https://geysermc.org/wiki/floodgate/setup/)
Values: `true`, `false`

#### `%uuid_isoffline%`
If this UUID is for a cracked Minecraft player based on its version
Values: `true`, `false`

---

# Global placeholders
#### `%text:'<text>'"` - Returns arbitrary text. An example of a use case would be changing the placeholder to custom text if it is empty. For example `%player_prefix|text:'No Prefix'%`
## Global placeholders

#### `%discord_invite%`
The invite of your Discord server (this is either provided by you in the config, or DiscordSRV auto generates it for you)
Example value: `https://discord.gg/HGAdJEumxC`

#### `%text:'<text>'"`
Returns arbitrary text. An example of a use case would be changing the placeholder to custom text if it is empty.
Example usage: `%player_prefix|text:'No Prefix'%`

# Date formatting
## Date formatting
Some placeholders such as `log_time` for console lines take a time formatting string, for example: `ccc HH:mm:ss zzz` in `%log_time:'ccc HH:mm:ss zzz'%`

### (Useful) Formatting characters
#### (Useful) Formatting characters
Use multiple of the same character back-to-back for a longer output, for example `uu` -> `04`, `uuuu` -> `2004`

| Symbol | Meaning | Examples |
Expand Down Expand Up @@ -234,10 +312,10 @@ Use multiple of the same character back-to-back for a longer output, for example

[Source](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html)

## Discord timestamp formatting
### Discord timestamp formatting
Example usages: `%log_time:'timestamp'%` or `%log_time:'timestamp:t'%`

### Styles
#### Styles
| Style | Meaning | Example |
|-------------|-----------------|------------------------------|
| t | Short Time | 16:20 |
Expand Down

0 comments on commit 2b53a6e

Please sign in to comment.