JDA

JDA (API de discordia de Java)

Esta biblioteca de código abierto está destinada a implementar bots en Discord utilizando la puerta de enlace en tiempo real y la API REST. Proporciona funcionalidad basada en eventos para implementar bots de cualquier tipo, lo que permite aplicaciones efectivas y escalables.

Descripción general

Los conceptos básicos de JDA se han desarrollado para facilitar la creación de aplicaciones escalables:

1. Sistema de eventos
   Proporciona eventos simplificados desde la API de la puerta de enlace para responder a cualquier evento de la plataforma en tiempo real sin muchos problemas.
2. Acciones de descanso
   Implementación escalable y fácil de usar de la funcionalidad API REST, que le permite elegir entre devoluciones de llamada con combinadores, futuros y bloqueo. La biblioteca también maneja los límites de velocidad impuestos por Discord automáticamente, al tiempo que ofrece formas de reemplazar la implementación predeterminada.
3. Caché personalizable
   Cambie el uso de la memoria para obtener un mejor rendimiento cuando sea necesario, con ajustes preestablecidos predeterminados sensatos para elegir y personalizar.

Puede obtener más información visitando nuestra wiki o consultando nuestros Javadocs.

? Instalación

Esta biblioteca está disponible en maven central. La última versión siempre se muestra en la versión de GitHub.

La versión mínima de Java admitida por JDA es Java SE 8 . JDA también utiliza JSR 305 para respaldar una interoperabilidad sólida con Kotlin lista para usar.

Gradle

 repositories {
    mavenCentral()
}

dependencies {
    implementation( " net.dv8tion:JDA: $v ersion " ) { // replace $version with the latest version
      // Optionally disable audio natives to reduce jar size by excluding `opus-java`
      // Gradle DSL:
      // exclude module: 'opus-java'
      // Kotlin DSL:
      // exclude(module="opus-java")
    }
}

experto

< dependency >
    < groupId >net.dv8tiongroupId >
    < artifactId >JDAartifactId >
    < version >$versionversion > 
    
dependency >

? Creando un bot

Para usar esta biblioteca, debe crear una aplicación en el Panel de aplicaciones de Discord y obtener su token de bot. Puede encontrar una guía paso a paso para esto en nuestra página wiki Cómo crear un bot de Discord.

?‍♂️ Empezando

Proporcionamos una serie de ejemplos para presentarle JDA. También puede consultar nuestra Wiki oficial, Documentación y Preguntas frecuentes.

Cada bot implementado por JDA comienza usando JDABuilder o DefaultShardManagerBuilder. Ambos constructores proporcionan un conjunto de ajustes preestablecidos predeterminados para el uso de la caché y los eventos que desea recibir:

• createDefault : habilita el caché para los usuarios que están activos en canales de voz y todos los indicadores de caché
• createLight : desactiva todos los cachés de usuario y los indicadores de caché
• create : habilita la fragmentación de miembros, almacena en caché a todos los usuarios y habilita todos los indicadores de caché

Recomendamos leer la guía sobre almacenamiento en caché e intentos para tener una idea de cómo configurar su bot correctamente. A continuación se muestran algunos posibles casos de uso:

Ejemplo: registro de mensajes

Nota

El siguiente ejemplo utiliza la intención privilegiada GatewayIntent.MESSAGE_CONTENT , que debe habilitarse explícitamente en el panel de su aplicación. Puede obtener más información sobre las intenciones en nuestra guía wiki.

Simplemente registrando mensajes en la consola. Haciendo uso de JDABuilder, el punto de entrada previsto para bots más pequeños que no pretenden crecer hasta llegar a miles de gremios.

Iniciar su bot y adjuntar un detector de eventos, utilizando las intenciones correctas:

 public static void main ( String [] args ) {
  JDABuilder . createLight ( token , EnumSet . of ( GatewayIntent . GUILD_MESSAGES , GatewayIntent . MESSAGE_CONTENT ))
      . addEventListeners ( new MessageReceiveListener ())
      . build ();
}

Su detector de eventos podría verse así:

 public class MessageReceiveListener extends ListenerAdapter {
  @ Override
  public void onMessageReceived ( MessageReceivedEvent event ) {
    System . out . printf ( "[%s] %#s: %s n " ,
      event . getChannel (),
      event . getAuthor (),
      event . getMessage (). getContentDisplay ());
  }
}

Puede encontrar un ejemplo más completo con la clase MessageLoggerExample.

Ejemplo: bot de comando de barra diagonal

Este es un bot que utiliza interacciones para responder a los comandos del usuario. A diferencia del bot de registro de mensajes, este bot puede funcionar sin ningún intent habilitado, ya que las interacciones siempre están disponibles.

 public static void main ( String [] args ) {
  JDA jda = JDABuilder . createLight ( token , Collections . emptyList ())
      . addEventListeners ( new SlashCommandListener ())
      . build ();

  // Register your commands to make them visible globally on Discord:

  CommandListUpdateAction commands = jda . updateCommands ();

  // Add all your commands on this action instance
  commands . addCommands (
    Commands . slash ( "say" , "Makes the bot say what you tell it to" )
      . addOption ( STRING , "content" , "What the bot should say" , true ), // Accepting a user input
    Commands . slash ( "leave" , "Makes the bot leave the server" )
      . setGuildOnly ( true ) // this doesn't make sense in DMs
      . setDefaultPermissions ( DefaultMemberPermissions . DISABLED ) // only admins should be able to use this command.
  );

  // Then finally send your commands to discord using the API
  commands . queue ();
}

Un detector de eventos que responde a comandos podría verse así:

{ String content = event.getOption("content", OptionMapping::getAsString); event.reply(content).queue(); }; case "leave" -> { event.reply("I'm leaving the server now!") .setEphemeral(true) // this message is only visible to the command user .flatMap(m -> event.getGuild().leave()) // append a follow-up action using flatMap .queue(); // enqueue both actions to run in sequence (send message -> leave guild) }; default -> return; } } }">

 public class SlashCommandListener extends ListenerAdapter {
  @ Override
  public void onSlashCommandInteraction ( SlashCommandInteractionEvent event ) {
    switch ( event . getName ()) {
      case "say" -> {
        String content = event . getOption ( "content" , OptionMapping :: getAsString );
        event . reply ( content ). queue ();
      };
      case "leave" -> {
        event . reply ( "I'm leaving the server now!" )
          . setEphemeral ( true ) // this message is only visible to the command user
          . flatMap ( m -> event . getGuild (). leave ()) // append a follow-up action using flatMap
          . queue (); // enqueue both actions to run in sequence (send message -> leave guild)
      };
      default -> return ;
    }
  }
}

Puede encontrar un ejemplo más completo con la clase SlashBotExample.

DescansoAcción

En esta biblioteca, la interfaz RestAction se utiliza como generador de solicitudes para todos los puntos finales de API. Esta interfaz representa un generador de solicitudes diferidas, como se muestra en este ejemplo sencillo:

 channel . sendMessage ( "Hello Friend!" )
  . addFiles ( FileUpload . fromData ( greetImage )) // Chain builder methods to configure the request
  . queue () // Send the request asynchronously 

Importante

La llamada final a queue() envía la solicitud. También puede enviar la solicitud de forma sincrónica o utilizando futuros; consulte nuestra guía ampliada en RestAction Wiki.

La interfaz RestAction también admite varios operadores para evitar el infierno de las devoluciones de llamadas:

• map
  Convierta el resultado de RestAction a un valor diferente
• flatMap
  Encadenar otra RestAction en el resultado
• delay
  Retrasar el elemento del paso anterior.

Además de combinadores como:

• and
  Requerir que otra RestAction se complete correctamente y se ejecute en paralelo
• allOf
  Acumule una lista de muchas acciones en una (ver también mapToResult )
• zip
  Similar a and , pero combina los resultados en una lista

Y configuradores como:

• timeout y deadline
  Configurar cuánto tiempo se permite que la acción esté en cola, cancelándola si tarda demasiado
• setCheck
  Realizar algunas comprobaciones justo antes de enviar la solicitud; esto puede resultar útil cuando está en cola por un tiempo.
• reason
  El motivo del registro de auditoría para una acción.

Ejemplo :

it.editMessage(content)) // then edit the message .delay(1, MINUTES, scheduler) // wait another minute .flatMap(Message::delete); // then delete }">

 public RestAction < Void > selfDestruct ( MessageChannel channel , String content ) {
    return channel . sendMessage ( "The following message will destroy itself in 1 minute!" )
        . addActionRow ( Button . danger ( "delete" , "Delete now" )) // further amend message before sending
        . delay ( 10 , SECONDS , scheduler ) // after sending, wait 10 seconds
        . flatMap (( it ) -> it . editMessage ( content )) // then edit the message
        . delay ( 1 , MINUTES , scheduler ) // wait another minute
        . flatMap ( Message :: delete ); // then delete
}

Esto luego podría usarse en el código:

 selfDestruct ( channel , "Hello friend, this is my secret message" ). queue ();

? Extensiones

jda-ktx

Creado y mantenido por MinnDevelopment.
Proporciona extensiones de Kotlin para RestAction y eventos que brindan una experiencia de Kotlin más idiomática.

val time = measureTime { event.reply("Pong!").await() // suspending }.inWholeMilliseconds event.hook.editOriginal("Pong: $time ms").queue() } }">

 fun main () {
    val jda = light( BOT_TOKEN )
    
    jda.onCommand( " ping " ) { event ->
        val time = measureTime {
            event.reply( " Pong! " ).await() // suspending
        }.inWholeMilliseconds

        event.hook.editOriginal( " Pong: $time ms " ).queue()
    }
}

Hay varios ejemplos disponibles en el archivo README.

Lavaplayer

Creado por sedmelluq y ahora mantenido por la comunidad lavalink
Lavaplayer es la biblioteca más popular utilizada por Music Bots creada en Java. Es altamente compatible con JDA y Discord4J y permite reproducir audio de YouTube, Soundcloud, Twitch, Bandcamp y más proveedores.
La biblioteca se puede ampliar fácilmente a más servicios implementando su propio AudioSourceManager y registrándolo. Recomendamos utilizar también udpqueue además de lavaplayer, para evitar problemas de tartamudeo causados ​​por las pausas de GC.

Se recomienda leer la sección Uso de Lavaplayer para comprender una implementación adecuada.
Sedmelluq proporcionó una demostración en su repositorio que presenta una implementación de ejemplo para JDA: https://github.com/lavalink-devs/lavaplayer/tree/master/demo-jda

udpqueue (una extensión de jda-nas)

Creado y mantenido por sedmelluq y ampliado por MinnDevelopment
Proporciona una implementación nativa para JDA Audio Send-System para evitar pausas de GC que puedan causar problemas con la reproducción continua de audio.

Tenga en cuenta que este sistema de envío crea un cliente UDP adicional que hace que la recepción de audio ya no funcione correctamente, ya que Discord identifica al cliente UDP emisor como el receptor.

 JDABuilder builder = JDABuilder . createDefault ( BOT_TOKEN )
    . setAudioSendFactory ( new NativeAudioSendFactory ());

Lavalink

Creado por Freya Arbjerg y ahora mantenido por la comunidad lavalink.

Lavalink es un popular nodo de envío de audio independiente basado en Lavaplayer. Lavalink se creó teniendo en cuenta la escalabilidad y permite transmitir música a través de muchos servidores. Es compatible con la mayoría de las funciones de Lavaplayer.

Lavalink es utilizado por muchos bots grandes, así como por desarrolladores de bots que no pueden usar una biblioteca Java como Lavaplayer. Si planea ofrecer música a menor escala con JDA, a menudo es preferible usar Lavaplayer directamente, ya que es más fácil.

Lavalink-Client es el cliente oficial de Lavalink para JDA.

Contribuyendo a JDA

Si desea contribuir a JDA, asegúrese de basar su rama en nuestra rama maestra (o una rama de funciones) y cree su PR en esa misma rama.

Siga nuestras pautas de contribución.

No espere que su solicitud de extracción reciba atención inmediata; a veces tomará mucho tiempo obtener una respuesta. Puedes unirte a nuestro servidor de Discord y preguntar en #lib-dev antes de comenzar a trabajar en un nuevo PR, para obtener comentarios más inmediatos de los miembros de nuestra comunidad.

Cambios importantes

Debido a la naturaleza de la API de Discord, la biblioteca introducirá periódicamente cambios importantes para permitir una rápida adopción de funciones más nuevas. Intentamos mantener estos cambios importantes al mínimo, pero no podemos evitarlos por completo.

La mayoría de los cambios importantes darán como resultado un aumento menor en la versión ( 5.1.2 → 5.2.0 ).