LovelyLink - Linking system

# LovelyLink Resource Description

LovelyLink is a Minecraft plugin built for servers that want reliable Discord account linking without a messy setup flow. It gives players a clear process: join the server, go to the configured Discord channel, run `/link`, receive a private temporary code, and finish linking in Minecraft.

When force-link mode is enabled, unlinked players can be frozen and protected while they complete the process. This helps prevent bypassing account verification while still keeping new players safe from damage and mob targeting.

LovelyLink also includes Discord whitelist request handling. Players can submit `IGN: PlayerName` in a dedicated Discord channel, invalid messages are automatically removed, and an admin receives approval buttons in DM. When the admin approves or rejects, LovelyLink reacts to both the admin DM and the original request message instead of posting extra channel messages.

## Key Features

- Discord-first account linking flow.
- Private Discord `/link` code replies.
- Link codes expire after 30 seconds.
- Minecraft `/link code <code>` completion.
- Admin and console `/link force <player> <code>` support.
- Force-link mode for unlinked players.
- Freeze unlinked players until they link.
- Optional protection from damage and mob targeting while unlinked.
- Optional particle effect for unlinked protected players.
- Block chat, movement, interaction, block breaking, block placing, commands, and damage until linked.
- First-link reward commands from console.
- Discord `/lookup` command for staff account checks.
- Minecraft `/ilookup` command for linked account lookup.
- Player unlink flow with in-game unlink codes.
- Staff force-unlink command.
- Discord whitelist request channel.
- Automatically deletes invalid whitelist channel messages.
- Admin DM approval and rejection buttons.
- Adds check or cross reactions to both whitelist request messages and admin DM messages.
- Optional Discord nickname update after linking.
- Optional DiscordSRV integration through soft dependency.
- JSON-based link storage.
- bStats metrics support.

## Account Linking Flow

1. A player joins the Minecraft server.
2. If force-link is enabled and the player is not linked, LovelyLink freezes and protects them.
3. The player goes to the configured Discord link channel.
4. The player runs `/link` in Discord.
5. The bot privately replies with a code and tells them to use `/link code <code>` in Minecraft.
6. The player enters the code in Minecraft within 30 seconds.
7. LovelyLink links the Minecraft UUID to the Discord account.
8. Protection is removed and first-link rewards can be executed.
9. If DiscordSRV is installed, the link can also be synced there.

## Whitelist Flow

LovelyLink can manage whitelist requests directly from Discord.

Players submit:

```text
IGN: PlayerName
```

The bot sends an admin DM containing:

```text
Whitelist Request
Player PlayerName is requesting whitelist access.
Message ID: <message id>
```

The admin can approve or reject with buttons. LovelyLink then reacts to both the admin message and the original request message, keeping the whitelist channel clean.

## DiscordSRV Support

DiscordSRV is supported as a soft dependency. LovelyLink can run without DiscordSRV, but when DiscordSRV is installed, LovelyLink can query and sync linked account information through DiscordSRV's account link manager.

This is useful for servers that already rely on DiscordSRV or want other plugins and DiscordSRV features to share the same linked-account data.

## Commands

### Minecraft Commands

```text
/link
/link code <code>
/link force <player> <code>
/unlink
/unlink force <player>
/ilookup <player-or-discord-id>
/ihelp
```

### Discord Slash Commands

```text
/link
/unlink code:<code>
/lookup ephemeral:<true/false> user:<member>
/lookup ephemeral:<true/false> nickname:<minecraft_name>
```

## Permissions

```text
lovelylink.force-link
lovelylink.force-unlink
lovelylink.lookup
```

## Requirements

- Java 21.
- Paper or compatible server software.
- Built against Paper API 1.21.1.
- Discord bot token.
- Discord bot with required intents enabled.
- DiscordSRV optional.

## Required Discord Bot Intents

- Server Members Intent.
- Message Content Intent.

## Recommended Discord Bot Permissions

- View Channels.
- Send Messages.
- Embed Links.
- Read Message History.
- Add Reactions.
- Manage Messages, for invalid whitelist message deletion.
- Manage Nicknames, only if nickname updating is enabled.

## Configuration Highlights

LovelyLink includes configuration for:

- Discord bot token.
- Discord guild ID.
- Link channel restriction.
- Force-link mode.
- Unlinked player protection.
- First-link reward commands.
- Discord whitelist request channel.
- Whitelist approver user ID.
- Lookup command role requirement.
- Discord nickname updates.
- Custom in-game messages.

## Best For

LovelyLink is a good fit for servers that want:

- Required Discord verification before playing.
- Cleaner account-linking with private temporary codes.
- Staff-friendly whitelist handling from Discord.
- Discord and Minecraft account lookup tools.
- Optional DiscordSRV compatibility.
- Reward commands for first-time account linking.

## Notes

LovelyLink uses Discord slash commands, so the bot must be invited with the `applications.commands` scope. If whitelist approvals are enabled, the configured approver must be able to receive DMs from the bot.

Invalid whitelist messages are deleted automatically, so the bot needs `Manage Messages` in the whitelist channel.