Merge pull request #277 from nwesterhausen/nw-discord-api-changes

changes relating to Discord API
nwesterhausen · Jun 12, 2024 · c8b32e4 · c8b32e4
2 parents 141e308 + 178cbb2
commit c8b32e4
Show file tree

Hide file tree

Showing 30 changed files with 1,271 additions and 275 deletions.
diff --git a/DiscordConnector.csproj b/DiscordConnector.csproj
@@ -13,7 +13,7 @@
 
   <PropertyGroup>
     <!-- Set the path to the game folder. This is used when including references below -->
-    <GamePath Condition="$(GamePath) == ''">/Users/nwesterhausen/Downloads/valheim_0.218.15</GamePath>
+    <GamePath Condition="$(GamePath) == ''">G:\Valheim\0.218.15</GamePath>
     <!-- Make the references to folders used in the build process a lot simpler -->
     <BinDir>$(ProjectDir)bin/</BinDir>
     <DiscordConnectorDir>$(BinDir)DiscordConnector/</DiscordConnectorDir>

diff --git a/Metadata/DiscordConnector-Nexus.readme b/Metadata/DiscordConnector-Nexus.readme
@@ -1,4 +1,4 @@
-DISCORD CONNECTOR - 2.2.2
+DISCORD CONNECTOR - 2.3.0
 Connect your Valheim server to a Discord Webhook. Works for both dedicated and client-hosted servers. (Visit the github repo for a how-to guide.)
 
 :: REQUIREMENTS ::

diff --git a/Metadata/README.md b/Metadata/README.md
@@ -1,7 +1,7 @@
 # Discord Connector
 
 Connect your Valheim server (dedicated or served from the game itself) to a Discord Webhook.
-(Find mod documentation on [the official website](https://discordconnector.valheim.nwest.games/).)
+(Find mod documentation on [the official website](https://discord-connector.valheim.games.nwest.one/).)
 
 ## Features
 
@@ -34,20 +34,17 @@ See the [current roadmap](https://github.com/nwesterhausen/valheim-discordconnec
 
 ## Abridged Changelog
 
-### Version 2.2.2
+### Version 2.3.0
 
 Features
 
-- add `%JOIN_CODE%` variable which will show the join code if crossplay is enabled
-- add `%NUM_PLAYERS%` variable which will show the number of online players
+- support up to 16 additional webhooks (adds a new config file, `discordconnector-extraWebhooks.cfg`)
+- support restricting/allowing Discord mentions in messages (`@here` and `@everyone` are disabled by default -- possibly a breaking change)
+- custom variables are now evaluated again for any embedded variables in the message
+- added new configuration values to allow specifying a custom username and avatar for each webhook (to override the Discord webhook settings)
+- added a configuration value that sets a default username for all webhooks (if not overridden)
 
 Fixes
 
-- updated the documentation to reflect how `%WORLD_NAME%`, `%PUBLIC_IP%`, and `%DAY_NUMBER%` can be
-in any messages and be replaced.
-
-Note: At server startup, some variables may not be available. They all should be available when server
-is launched, but the join code may take a bit longer to display -- more testing is needed to know exactly
-how much extra time it needs on average. If it is consistently unavailable, please file an issue and we
-can come up with either a delayed startup message or another event that fires when the code becomes not
-empty or changes.
+- no longer relies on the `ZNet.GetPublicIP()` method and instead gets the public IP on its own at server start.
+- `%NUM_PLAYERS%` proactively subtracts 1 if the event is a player leaving
diff --git a/Metadata/manifest.json b/Metadata/manifest.json
@@ -1,7 +1,7 @@
 {
   "name": "DiscordConnector",
-  "version_number": "2.2.2",
-  "website_url": "https://discordconnector.valheim.nwest.games/",
+  "version_number": "2.3.0",
+  "website_url": "https://discord-connector.valheim.games.nwest.one/",
   "description": "Connects your Valheim server to a Discord webhook. Works for both dedicated and client-hosted servers.",
   "dependencies": [
     "denikson-BepInExPack_Valheim-5.4.2201"

diff --git a/Metadata/thunderstore.toml b/Metadata/thunderstore.toml
@@ -4,9 +4,9 @@ schemaVersion = "0.0.1"
 [package]
 namespace = "nwesterhausen"
 name = "DiscordConnector"
-versionNumber = "2.2.2"
+versionNumber = "2.3.0"
 description = "Connects your Valheim server to a Discord webhook. Works for both dedicated and client-hosted servers."
-websiteUrl = "https://discordconnector.valheim.nwest.games/"
+websiteUrl = "https://discord-connector.valheim.games.nwest.one/"
 containsNsfwContent = false
 
 [package.dependencies]
@@ -24,9 +24,3 @@ target = "./"
 [publish]
 repository = "https://thunderstore.io"
 communities = ["valheim"]
-categories = [
-  "hildirs-request-update",
-  "utility",
-  "server-side",
-  "ashlands-update",
-]
diff --git a/README.md b/README.md
@@ -3,11 +3,11 @@
 [![CodeQL](https://github.com/nwesterhausen/valheim-discordconnector/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/nwesterhausen/valheim-discordconnector/actions/workflows/codeql-analysis.yml)
 [![Build](https://github.com/nwesterhausen/valheim-discordconnector/actions/workflows/dotnet.yml/badge.svg)](https://github.com/nwesterhausen/valheim-discordconnector/actions/workflows/dotnet.yml)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/nwesterhausen/valheim-discordconnector?label=Github%20Release&style=flat&labelColor=%2332393F)](https://github.com/nwesterhausen/valheim-discordconnector/releases/latest)
-[![Thunderstore.io](https://img.shields.io/badge/Thunderstore.io-2.2.2-%23375a7f?style=flat&labelColor=%2332393F)](https://valheim.thunderstore.io/package/nwesterhausen/DiscordConnector/)
+[![Thunderstore.io](https://img.shields.io/badge/Thunderstore.io-2.3.0-%23375a7f?style=flat&labelColor=%2332393F)](https://valheim.thunderstore.io/package/nwesterhausen/DiscordConnector/)
 [![NexusMods](https://img.shields.io/badge/NexusMods-2.1.14-%23D98F40?style=flat&labelColor=%2332393F)](https://www.nexusmods.com/valheim/mods/1551/)
 ![Built against Valheim version](https://img.shields.io/badge/Built_against_Valheim-0.218.15-purple?style=flat&labelColor=%2332393F)
 
-Connect your Valheim server to Discord. ([See website for installation or configuration instructions](https://discordconnector.valheim.nwest.games/)). This plugin is largely based on [valheim-discord-notifier](https://github.com/aequasi/valheim-discord-notifier), but this plugin supports randomized messages, muting players, and Discord message embeds.
+Connect your Valheim server to Discord. ([See website for installation or configuration instructions](https://discord-connector.valheim.games.nwest.one/)). This plugin is largely based on [valheim-discord-notifier](https://github.com/aequasi/valheim-discord-notifier), but this plugin supports randomized messages, muting players, and Discord message embeds.
 
 ## Plugin Details
 

diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -73,6 +73,9 @@ export default {
                                 { text: 'Player Activity', link: '/config/leaderboards.playerstats' },
                                 { text: 'Custom Leaderboards', link: '/config/leaderboards.custom' },
                             ]
+                        },
+                        {
+                            text: "Extra Webhooks", link: '/config/extra-webhooks',
                         }
                     ]
                 },
@@ -88,4 +91,4 @@ export default {
         },
         lastUpdatedText: 'Updated Date'
     }
-}
+}
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -2,6 +2,21 @@
 
 A full changelog of changes, dating all the way back to the first release.
 
+## Version 2.3.0
+
+Features
+
+- support up to 16 additional webhooks (adds a new config file, `discordconnector-extraWebhooks.cfg`)
+- support restricting/allowing Discord mentions in messages (`@here` and `@everyone` are disabled by default -- possibly a breaking change)
+- custom variables are now evaluated again for any embedded variables in the message
+- added new configuration values to allow specifying a custom username and avatar for each webhook (to override the Discord webhook settings)
+- added a configuration value that sets a default username for all webhooks (if not overridden)
+
+Fixes
+
+- no longer relies on the `ZNet.GetPublicIP()` method and instead gets the public IP on its own at server start.
+- `%NUM_PLAYERS%` proactively subtracts 1 if the event is a player leaving
+
 ## Version 2.2.2
 
 Features
@@ -101,7 +116,7 @@ Adds a requested feature for a second webhook. Both webhooks can be configured t
 Connector sends, and by default (to be non-breaking) they will send all messages (which is the behavior of 2.1.8 and previous).
 Some plugins which may make use of Discord Connector's webhook to send messages can use the same method for sending and will
 be tagged as 'other' webhook events. For a full list of what webhook events can be configured, see the
-[documentation](https://discordconnector.valheim.nwest.games/config/main.html#webhook-events).
+[documentation](https://discord-connector.valheim.games.nwest.one/config/main.html#webhook-events).
 
 Features:
 

diff --git a/docs/config/extra-webhooks.md b/docs/config/extra-webhooks.md
@@ -0,0 +1,42 @@
+# Extra Webhooks
+
+Filename `discordconnector.cfg`
+
+This file provides configuration for 16 additional webhooks.
+
+Each one supports the same settings as the primary and secondary that are in the [main config](./main).
+
+## Webhook 1 - 16
+
+What can be configured for each webhook
+
+### Webhook URL
+
+Type: `String`, default value: ``
+
+Discord channel webhook URL. For instructions, reference the 'MAKING A WEBHOOK' section of [Discord's documentation](https://support.Discord.com/hc/en-us/articles/228383668-Intro-to-Webhook).
+
+### Webhook Events
+
+Type: `String`, default value: `ALL`
+
+Specify a subset of possible events to send to this webhook. Format should be the keyword 'ALL' or a semi-colon separated list, e.g. `serverLifecycle;playerAll;playerFirstAll;leaderboardsAll;`
+
+A full list of valid options for this are [here](https://discord-connector.valheim.games.nwest.one/config/webhook.events.html).
+
+### Webhook Username Override
+
+Type: `String`, default value: ``
+
+Override the username of this webhook. If left blank, the webhook will first try to use the default username from the main configuration, then will rely on the name provided by Discord.
+
+:::tip Default Username
+A fallback default username to enforce can be set in the [main config](./main#default-webhook-username-override)
+
+:::
+
+### Webhook Avatar Override
+
+Type: `String`, default value: ``
+
+Override the avatar of this webhook. This should be a URL to an image. If left blank, the webhook will use the default avatar set in your Discord channel's "Integration" menu.
diff --git a/docs/config/main.md b/docs/config/main.md
@@ -2,6 +2,14 @@
 
 Filename `discordconnector.cfg`
 
+## Default Webhook Username Override
+
+Type: `String`, default value: ``
+
+Override the username of all webhooks for this instance of Discord Connector. If left blank, the webhook will use the default name (assigned by Discord in the Integration menu).
+
+This setting will be used for all webhooks unless overridden by a specific webhook username override setting.
+
 ## Webhook URL
 
 Type: `String`, default value: ``
@@ -14,7 +22,19 @@ Type: `String`, default value: `ALL`
 
 Specify a subset of possible events to send to the primary webhook. Format should be the keyword 'ALL' or a semi-colon separated list, e.g. `serverLifecycle;playerAll;playerFirstAll;leaderboardsAll;`
 
-A full list of valid options for this are [here](https://discordconnector.valheim.nwest.games/config/webhook.events.html).
+A full list of valid options for this are [here](https://discord-connector.valheim.games.nwest.one/config/webhook.events.html).
+
+## Webhook Username Override
+
+Type: `String`, default value: ``
+
+Override the username of this webhook. If left blank, the webhook will use the default username set in your Discord channel's "Integration" menu.
+
+## Webhook Avatar Override
+
+Type: `String`, default value: ``
+
+Override the avatar of this webhook. This should be a URL to an image. If left blank, the webhook will use the default avatar set in your Discord channel's "Integration" menu.
 
 ## Secondary Webhook URL
 
@@ -28,7 +48,19 @@ Type: `String`, default value: `ALL`
 
 Specify a subset of possible events to send to the secondary webhook. Format should be the keyword 'ALL' or a semi-colon separated list, e.g. `serverLifecycle;playerAll;playerFirstAll;leaderboardsAll;`
 
-A full list of valid options for this are [here](https://discordconnector.valheim.nwest.games/config/webhook.events.html).
+A full list of valid options for this are [here](https://discord-connector.valheim.games.nwest.one/config/webhook.events.html).
+
+## Secondary Webhook Username Override
+
+Type: `String`, default value: ``
+
+Override the username of this webhook. If left blank, the webhook will use the default username set in your Discord channel's "Integration" menu.
+
+## Secondary Webhook Avatar Override
+
+Type: `String`, default value: ``
+
+Override the avatar of this webhook. This should be a URL to an image. If left blank, the webhook will use the default avatar set in your Discord channel's "Integration" menu.
 
 ## Log Debug Messages
 
@@ -100,6 +132,7 @@ Choose a method for how players will be separated from the results of a record q
 | Name            | Treat each CharacterName as a separate player                  |
 | PlayerId        | Treat each PlayerId as a separate player                       |
 | NameAndPlayerId | Treat each [PlayerId:CharacterName] combo as a separate player |
+
 :::
 
 :::warning What is the PlayerID?
@@ -117,3 +150,63 @@ Enable this setting to have shouts which are performed by other mods/the server/
 :::warning Muted Players
 These are still subject to censure by the muted player regex and list.
 :::
+
+## Allow Mentions for @here and @everyone
+
+Type: `Boolean`, default value: `false`
+
+Enable this setting to allow the use of @here and @everyone in messages sent to Discord.
+
+:::warning
+This setting is disabled by default to prevent accidental mentions of everyone in the Discord channel. There is no filtering to prevent players from using these mentions in their shouts or names.
+:::
+
+## Allow Role Mentions
+
+Type: `Boolean`, default value: `true`
+
+Enable this setting to allow the use of role mentions in messages sent to Discord. Role mentions are in the format `<@&role_id>`, where `role_id` is the ID of the role you want to mention.
+
+:::warning
+There is no filtering to prevent players from using these mentions in their shouts or names.
+:::
+
+## Allow User Mentions
+
+Type: `Boolean`, default value: `true`
+
+Enable this setting to allow the use of user mentions in messages sent to Discord. User mentions are in the format `<@user_id>`, where `user_id` is the ID of the user you want to mention.
+
+:::warning
+There is no filtering to prevent players from using these mentions in their shouts or names.
+:::
+
+## Specifically Allowed Role Mentions
+
+Type: `String`, default value: ``
+
+Example value: `123452834;123452835`
+
+If you want to allow only certain roles to be mentioned, you can specify them here. This is a semicolon-separated list of role IDs where `role_id` is the ID of the role you want to allow mentions for.
+
+This setting will take precedence over the `Allow Role Mentions` setting (of course if all roles are allowed, this setting is redundant).
+
+:::tip How to get a Role ID
+Send a message in Discord with a backslash before the role mention, e.g. `\@role_name`. This will display the role mention in the format `<@&role_id>`, where `role_id` is the ID of the role you want to mention.
+
+:::
+
+## Specifically Allowed User Mentions
+
+Type: `String`, default value: ``
+
+Example value: `123452834;123452835`
+
+If you want to allow only certain users to be mentioned, you can specify them here. This is a semicolon-separated list of user IDs where `user_id` is the ID of the user you want to allow mentions for.
+
+This setting will take precedence over the `Allow User Mentions` setting (of course if all users are allowed, this setting is redundant).
+
+:::tip How to get a User ID
+Send a message in Discord with a backslash before the user mention, e.g. `\@user_name`. This will display the user mention in the format `<@user_id>`, where `user_id` is the ID of the user you want to mention.
+
+:::
diff --git a/docs/config/messages.events.md b/docs/config/messages.events.md
@@ -12,11 +12,11 @@ In the event messages, anywhere in the message you can use the string vars `%EVE
 
 ::: tip Available Dynamic Variables
 
-| Variable            | Replaced with..                                                                           | Can be used in..    |
-| ------------------- | ----------------------------------------------------------------------------------------- | ------------------- |
-| `%VAR1%` - `VAR10%` | Custom variable value (defined in [Custom Variables](/config/variables.html) config file) | Any messages        |
-| `%PUBLICIP%`        | Server's public IP (according to the server)                                              | Any server messages |
-| `%DAY_NUMBER%`      | Current day number on server                                                              | Any messages        |
+| Variable            | Replaced with..                                                                          | Can be used in..    |
+| ------------------- | ---------------------------------------------------------------------------------------- | ------------------- |
+| `%VAR1%` - `VAR10%` | Custom variable value (defined in [Custom Variables](./variables.custom.md) config file) | Any messages        |
+| `%PUBLICIP%`        | Server's public IP (according to the server)                                             | Any server messages |
+| `%DAY_NUMBER%`      | Current day number on server                                                             | Any messages        |
 :::
 
 :::details Random Messages
@@ -31,7 +31,7 @@ Player Death Message = %PLAYER_NAME% has died a beautiful death!;%PLAYER_NAME% w
 :::
 
 ::: details Available Custom Variables
-These are defined in the [Custom Variables](/config/variables.html) config file.
+These are defined in the [Custom Variables](./variables.custom.md) config file.
 
 `%VAR1%`, `%VAR2%`, `%VAR3%`, `%VAR4%`, `%VAR5%`, `%VAR6%`, `%VAR7%`, `%VAR8%`, `%VAR9%`, `%VAR10%`
 :::

diff --git a/docs/config/messages.leaderboards.md b/docs/config/messages.leaderboards.md
@@ -1,12 +1,27 @@
 # Messages.LeaderBoards
 
-::: tip Available Dynamic Variables
+:::details Always Available Variables
+
+| Variable            | Replaced with..                                                                          | Can be used in..    |
+| ------------------- | ---------------------------------------------------------------------------------------- | ------------------- |
+| `%VAR1%` - `VAR10%` | Custom variable value (defined in [Custom Variables](./variables.custom.md) config file) | Any messages        |
+| `%PUBLICIP%`        | Server's public IP (according to the server)                                             | Any server messages |
+| `%DAY_NUMBER%`      | Current day number on server                                                             | Any messages        |
+| `%WORLD_NAME%`      | World name of the world used on the server                                               | Any messages        |
+| `%NUM_PLAYERS%`     | Number of currently online players                                                       | Any messages        |
+| `%JOIN_CODE%`       | Server's join code (only if a join code exists, blank otherwise)                         | Any messages        |
+
+:::
+
+:::details Random Messages
+All of the message options support having multiple messages defined in a semicolon (`;`) separated list. If you have multiple messages defined for these settings, one gets chosen at random when DiscordConnector decides to send the corresponding message.
+
+If you wanted to have a couple different messages for when a player dies (always chosen at random), you could simply set the config value like this:
+
+```toml
+Player Death Message = %PLAYER_NAME% has died a beautiful death!;%PLAYER_NAME% went to their end with honor!;%PLAYER_NAME% died.
+```
 
-| Variable            | Replaced with..                                                                           | Can be used in..    |
-| ------------------- | ----------------------------------------------------------------------------------------- | ------------------- |
-| `%VAR1%` - `VAR10%` | Custom variable value (defined in [Custom Variables](/config/variables.html) config file) | Any messages        |
-| `%PUBLICIP%`        | Server's public IP (according to the server)                                              | Any server messages |
-| `%DAY_NUMBER%`      | Current day number on server                                                              | Any messages        |
 :::
 
 ## Leader Board Heading for Top N Players