p_vincular - Minecraft ↔ Discord Account Linking Plugin

Version: 2.1.0

Author: Pedro

Compatibility: Minecraft 1.21 (api-version: 1.21)

Platform: Paper / Spigot

p_vincular is an advanced and complete plugin for linking Minecraft player accounts with Discord accounts, automatically syncing Discord roles to LuckPerms groups/permissions. Perfect for servers that want to fully integrate their in-game and Discord communities.

Main Features

• Secure linking via a unique 6-digit code (generated in Minecraft and entered in Discord, or via slash commands).

• Automatic synchronization of Discord roles → LuckPerms groups.

• Support for multiple mapped role groups (VIP, MVP, YouTuber, Staff, etc.).

• Customizable notifications: chat messages, titles in Minecraft, and embeds/ephemeral messages in Discord.

• Rewards on successful link (console commands executed once per UUID).

• In-game configuration menu (`/p

• vconfig) and reload command (

• /pvreload`).

• Manual sync command (/pvsync).

• Robust security system (code TTL, cooldown, attempt limits, unique Discord ID enforcement).

• Public link/unlink announcements in a Discord channel with rich embeds.

Commands

| Command | Description | Usage | Required Permission |

|----------------------|--------------------------------------------------------|--------------------------------|---------------------------|

| /vincular | Generates a code to link your account to Discord | /vincular | pvincular.use (default: everyone) |

| /desvincular | Removes the current link | /desvincular | pvincular.use |

| /pvsync [player] | Forces role sync for a player (or yourself) | /pvsync or /pvsync Name | pvincular.admin |

| /pvconfig | Opens the plugin's graphical configuration menu | /pvconfig | pvincular.admin |

| /pvreload | Reloads the config.yml without restarting the server | /pvreload | pvincular.admin |

Permissions

• pvincular.use → Allows use of /vincular and /desvincular (default: true → all players).

• pvincular.admin → Access to admin commands (/pvconfig, /pvreload, /pvsync) (default: op).

Dependencies

• LuckPerms (required) → For group synchronization and permission commands.

• JDA 6.2.0 → Shaded library for Discord bot functionality.

Installation

1. Download p_vincular-2.1.0.jar.

2. Place it in your server's plugins/ folder (Paper/Spigot 1.21+ recommended).

3. (Optional) Add a logo.png image inside plugins/p_vincular/ to use in Discord embeds.

4. Restart the server (the plugin will generate its folder and config.yml).

5. Edit config.yml with:

   • Discord bot token

   • Guild (server) ID

   • Role IDs

   • Notification channel ID

6. Run /pvreload or restart again to apply changes.

plugin.yml (for developer reference)

name: p_vincular

version: 2.1.0

main: br.com.pedro.p_vincular.PVincularPlugin

api-version: "1.21"

dependencies:

  server:

    LuckPerms:

      required: true

commands:

  pvconfig:

    description: Opens the p_vincular configuration menu.

    usage: /pvconfig

  pvreload:

    description: Reloads the p_vincular config.yml.

    usage: /pvreload

  vincular:

    description: Generates a code to link your account on Discord.

usage: /vincular

desvincular:

description: Removes your account link.

usage: /desvincular

pvsync:

description: Forces sync for a player (or yourself).

usage: /pvsync [player]

permissions:

pvincular.use:

default: true

pvincular.admin:

default: op

libraries:

• "net.dv8tion:JDA:6.2.0"

# p_vincular - Plugin de Vinculação Minecraft ↔ Discord

**Versão:** `2.1.0`  

**Autor:** Pedro

**Compatibilidade:** Minecraft 1.21 (api-version: 1.21)  

**Plataforma:** Paper / Spigot  

**p_vincular** é um plugin avançado e completo para vincular contas do Minecraft com o Discord, sincronizando cargos do Discord com grupos/permissões no servidor (integrado ao LuckPerms). Ideal para servidores que desejam unir a comunidade do jogo com o servidor Discord.

## Funcionalidades Principais

- Vinculação segura via código único de 6 dígitos (gerado no Minecraft e inserido no Discord ou vice-versa).

- Sincronização automática de cargos do Discord → grupos no LuckPerms.

- Suporte a múltiplos grupos mapeados (VIP, MVP, YouTuber, Staff etc.).

- Notificações personalizáveis: chat, títulos no Minecraft e embeds/mensagens no Discord.

- Recompensas ao vincular (comandos console executados apenas uma vez por UUID).

- Menu de configuração in-game (`/pvconfig`) e reload (`/pvreload`).

- Comando de sincronização manual (`/pvsync`).

- Sistema de segurança robusto (TTL do código, cooldown, limite de tentativas, bloqueio de IDs duplicados).

- Anúncios públicos de vínculo/desvínculo em canal do Discord.

## Comandos

| Comando          | Descrição                                              | Uso                          | Permissão necessária      |

|------------------|--------------------------------------------------------|------------------------------|---------------------------|

| `/vincular`      | Gera um código para vincular a conta ao Discord        | `/vincular`                  | `pvincular.use` (padrão: todos) |

| `/desvincular`   | Remove o vínculo atual                                 | `/desvincular`               | `pvincular.use`           |

| `/pvsync [jogador]` | Força a sincronização de cargos de um jogador (ou você mesmo) | `/pvsync` ou `/pvsync Nome` | `pvincular.admin`         |

| `/pvconfig`      | Abre o menu gráfico de configuração do plugin          | `/pvconfig`                  | `pvincular.admin`         |

| `/pvreload`      | Recarrega o arquivo config.yml sem reiniciar o servidor| `/pvreload`                  | `pvincular.admin`         |

## Permissões

- `pvincular.use` → Permite usar `/vincular` e `/desvincular` (default: true → todos os jogadores).

- `pvincular.admin` → Acesso aos comandos administrativos (`/pvconfig`, `/pvreload`, `/pvsync`) (default: op).

## Dependências

- **LuckPerms** (obrigatório) → Para sincronização de grupos e execução de comandos de permissão.

- **JDA 6.2.0** → Biblioteca incluída via repositories Maven (shade no plugin).

## Instalação

1. Baixe o arquivo `p_vincular-2.1.0.jar`.

2. Coloque-o na pasta `plugins/` do seu servidor Paper/Spigot 1.21+.

3. (Opcional) Adicione uma imagem `logo.png` na pasta `plugins/p_vincular/` para ser usada nos embeds do Discord.

4. Reinicie o servidor (o plugin gerará a pasta e o arquivo `config.yml`).

5. Edite o `config.yml` com:

   - Token do bot Discord

   - ID da guild (servidor Discord)

   - IDs dos cargos

   - ID do canal de notificações

6. Execute `/pvreload` ou reinicie novamente.

## Exemplo de plugin.yml (para referência do desenvolvedor)

```yaml

name: p_vincular

version: 2.1.0

main: br.com.pedro.p_vincular.PVincularPlugin

api-version: "1.21"

dependencies:

  server:

    LuckPerms:

      required: true

commands:

  pvconfig:

    description: Abre o menu de configuração do p_vincular.

    usage: /pvconfig

  pvreload:

    description: Recarrega config.yml do p_vincular.

    usage: /pvreload

  vincular:

    description: Gera um código para vincular sua conta no Discord.

    usage: /vincular

  desvincular:

    description: Remove o vínculo da sua conta.

    usage: /desvincular

  pvsync:

    description: Força sync de um jogador (ou você mesmo).

    usage: /pvsync [player]

permissions:

  pvincular.use:

    default: true

  pvincular.admin:

    default: op

libraries:

  - "net.dv8tion:JDA:6.2.0"