AegisPunish Docs

Visão Geral #

O AegisPunish foi projetado a partir do zero para suprir as demandas críticas de servidores modernos e grandes redes de Minecraft. Ao contrário de soluções legadas e pesadas, o AegisPunish conta com um motor de cache em memória thread-safe e I/O assíncrono para garantir impacto zero no TPS do servidor.

Instalação & Requisitos #

Para utilizar o AegisPunish em sua rede ou servidor, verifique os requisitos mínimos:

• Java Runtime: Java 17 ou superior (testado e otimizado para Java 21 LTS).
• Plataforma: Paper, Folia, Purpur (1.16 até 1.21+), Velocity 3.3+, ou BungeeCord / Waterfall.
• Banco de Dados: SQLite local (nativo, sem configuração) ou MySQL / MariaDB (para redes).

Passo a Passo de Instalação

1. Baixe o .jar correspondente à sua plataforma no Modrinth, SpigotMC ou GitHub Releases.
2. Coloque o arquivo dentro da pasta plugins/ do servidor ou proxy.
3. Inicie o servidor para gerar os arquivos padrão em plugins/AegisPunish/.
4. Ajuste o config.yml (adicione seu webhook do Discord ou credenciais MySQL se aplicável).
5. Execute /aegispunish reload ou reinicie o servidor.

Plataformas & Integrações #

Punições Completas #

O AegisPunish suporta múltiplos tipos de sanções disciplinares, todas com suporte a motivos customizados e especificações de tempo simplificadas:

s = segundos (ex: 30s)
m = minutos  (ex: 15m)
h = horas    (ex: 2h)
d = dias     (ex: 7d)
w = semanas  (ex: 2w)
mo = meses   (ex: 1mo)
y = anos     (ex: 1y)

Exemplo: /tempban Steve 3d12h Uso de Trapaças

Tipos de Ação

• /ban & /tempban: Impede a entrada no servidor ou rede permanentemente ou por tempo determinado.
• /ipban & /tempipban: Pune tanto o UUID do jogador quanto o endereço de IP associado, impedindo a criação de contas alternativas.
• /mute & /tempmute: Bloqueia mensagens no chat global, local e comandos restritos configuráveis.
• /kick: Desconecta imediatamente o jogador com aviso sonoro e tela de punição.
• /warn: Registra avisos formais. Configuração para acionar banimento automático após atingir N avisos acumulados.

Histórico & Rollbacks #

Nenhuma punição é perdida ou deletada permanentemente sem rastreio. Quando uma punição é revogada com /unban ou /unmute, seu estado no banco de dados é alterado para inativo e o operador que realizou a anulação fica registrado.

# Anula todas as punições aplicadas por StaffAbusivo nas últimas 2 horas
/rollbackstaff StaffAbusivo 2h

Hierarquia de Staff (Anti-Abuse) #

O sistema de hierarquia baseado em peso protege os cargos mais altos contra punições aplicadas por cargos inferiores ou disputas internas.

staff-hierarchy:
  enabled: true
  weights:
    owner: 100
    admin: 80
    mod: 50
    helper: 20

# Regras de negócio:
# 1. Um membro com peso 50 (Mod) NÃO pode punir quem possui peso 80 (Admin).
# 2. Um membro da staff NÃO pode punir a si mesmo.
# 3. Punições ignoram restrições se o emissor for o Console (peso infinito).

Discord Webhooks #

Integração nativa com canais de auditoria do Discord. Quando uma punição ocorre ou é revogada, um embed profissional é enviado instantaneamente através de requisições HTTP assíncronas.

discord:
  webhook-url: "https://discord.com/api/webhooks/SEU_WEBHOOK_AQUI"
  embed:
    title: "🛡️ Nova Punição Aplicada"
    color: "#00D2FF"
    fields:
      - name: "Alvo"
        value: "{player} ({uuid})"
      - name: "Autor"
        value: "{staff}"
      - name: "Tipo"
        value: "{type}"
      - name: "Duração"
        value: "{duration}"
      - name: "Motivo"
        value: "{reason}"

Auto-Updater Modrinth #

O AegisPunish consulta periodicamente a API oficial do Modrinth buscando novas versões lançadas. Ao detectar uma versão mais recente, o arquivo é baixado em segundo plano e salvo como substituto para entrar em ação no próximo restart, sem interrupção de gameplay.

Arquivo config.yml #

# Idioma padrão das mensagens (pt_BR, en, es)
language: pt_BR

# Verificação e download automático de atualizações via Modrinth
auto-update:
  enabled: true
  auto-download: true

# Configurações de Banco de Dados
database:
  type: SQLITE # Opções: SQLITE ou MYSQL
  mysql:
    host: "127.0.0.1"
    port: 3306
    database: "aegispunish"
    username: "root"
    password: ""
    pool:
      maximum-pool-size: 10
      minimum-idle: 5

Banco de Dados (SQLite & MySQL) #

Por padrão, o AegisPunish utiliza SQLite local com o arquivo aegispunish.db, não necessitando de nenhuma configuração externa. Para sincronização entre servidores via Velocity/BungeeCord, configure o tipo MYSQL. Todas as consultas utilizam pools HikariCP e índices para velocidade ultrarrápida.

PlaceholderAPI #

Integração automática para uso em scoreboards, TAB, chat e menus gráficos:

Comandos & Permissões #

Lista de todos os comandos registrados pelo AegisPunish:

Developer API & Eventos #

O AegisPunish oferece uma API moderna em Java para desenvolvedores externos criarem integrações, bots ou painéis web:

// Obter instância do serviço
AegisPunishAPI api = AegisPunishAPIProvider.get();

// Verificar se um jogador está banido
UUID playerUuid = player.getUniqueId();
if (api.isBanned(playerUuid)) {
    Punishment ban = api.getActiveBan(playerUuid);
    player.sendMessage("Banido por: " + ban.getReason());
}

// Escutar eventos de punição
@EventHandler
public void onPunish(PlayerPunishEvent event) {
    if (event.getType() == PunishmentType.BAN) {
        getLogger().info(event.getTargetName() + " foi banido por " + event.getStaffName());
    }
}