JDA

JDA (API Perselisihan Java)

Pustaka sumber terbuka ini ditujukan untuk mengimplementasikan bot di Discord menggunakan gateway waktu nyata dan REST API. Ini menyediakan fungsionalitas berbasis peristiwa untuk mengimplementasikan bot apa pun, memungkinkan aplikasi yang efektif dan terukur.

Ringkasan

Konsep inti JDA telah dikembangkan untuk memudahkan pembuatan aplikasi yang skalabel:

1. Sistem Acara
   Menyediakan kejadian yang disederhanakan dari API gateway, untuk merespons kejadian platform apa pun secara real-time tanpa banyak kerumitan.
2. Tindakan Istirahat
   Implementasi fungsionalitas REST API yang mudah digunakan dan terukur, memungkinkan Anda memilih antara callback dengan kombinator, futures, dan pemblokiran. Perpustakaan juga menangani batasan kecepatan yang diberlakukan oleh Discord secara otomatis, sambil tetap menawarkan cara untuk menggantikan implementasi default.
3. Tembolok yang Dapat Disesuaikan
   Memperdagangkan penggunaan memori untuk kinerja yang lebih baik jika diperlukan, dengan preset default yang dapat dipilih dan disesuaikan.

Anda dapat mempelajari lebih lanjut dengan mengunjungi wiki kami atau merujuk pada Javadocs kami.

? Instalasi

Perpustakaan ini tersedia di maven central. Versi terbaru selalu ditampilkan di Rilis GitHub.

Versi Java minimum yang didukung oleh JDA adalah Java SE 8 . JDA juga menggunakan JSR 305 untuk mendukung interoperabilitas yang solid dengan Kotlin.

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")
    }
}

Maven

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

? Membuat Bot

Untuk menggunakan perpustakaan ini, Anda harus membuat Aplikasi di Dasbor Aplikasi Discord dan mengambil token bot Anda. Anda dapat menemukan panduan langkah demi langkah untuk ini di halaman wiki kami Membuat Bot Perselisihan.

?‍♂️ Memulai

Kami memberikan sejumlah contoh untuk memperkenalkan Anda pada JDA. Anda juga dapat melihat Wiki resmi kami, Dokumentasi, dan FAQ.

Setiap bot yang diterapkan oleh JDA dimulai menggunakan JDABuilder atau DefaultShardManagerBuilder. Kedua pembuatnya menyediakan serangkaian preset default untuk penggunaan cache dan peristiwa yang ingin diterimanya:

• createDefault - Mengaktifkan cache untuk pengguna yang aktif di saluran suara dan semua tanda cache
• createLight - Menonaktifkan semua cache pengguna dan tanda cache
• create - Mengaktifkan pengelompokan anggota, menyimpan cache semua pengguna, dan mengaktifkan semua tanda cache

Kami merekomendasikan untuk membaca panduan tentang caching dan maksud untuk memahami cara mengonfigurasi bot Anda dengan benar. Berikut beberapa kemungkinan kasus penggunaan:

Contoh: Pencatatan Pesan

Catatan

Contoh berikut menggunakan maksud istimewa GatewayIntent.MESSAGE_CONTENT , yang harus diaktifkan secara eksplisit di dasbor aplikasi Anda. Anda dapat mengetahui lebih lanjut tentang maksud di panduan wiki kami.

Cukup mencatat pesan ke konsol. Memanfaatkan JDABuilder, titik masuk yang dimaksudkan untuk bot kecil yang tidak ingin berkembang menjadi ribuan guild.

Memulai bot Anda dan melampirkan pendengar acara, menggunakan maksud yang tepat:

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

Pendengar acara Anda akan terlihat seperti ini:

 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 ());
  }
}

Anda dapat menemukan contoh yang lebih menyeluruh dengan kelas MessageLoggerExample.

Contoh: Bot Perintah Slash

Ini adalah bot yang memanfaatkan interaksi untuk merespons perintah pengguna. Berbeda dengan bot pencatatan pesan, bot ini dapat bekerja tanpa maksud apa pun yang diaktifkan, karena interaksi selalu tersedia.

 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 ();
}

Pemroses acara yang merespons perintah akan terlihat seperti ini:

{ 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 ;
    }
  }
}

Anda dapat menemukan contoh yang lebih menyeluruh dengan kelas SlashBotExample.

Tindakan Istirahat

Di perpustakaan ini, antarmuka RestAction digunakan sebagai pembuat permintaan untuk semua titik akhir API. Antarmuka ini mewakili pembuat permintaan yang lambat, seperti yang ditunjukkan dalam contoh sederhana ini:

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

Penting

Panggilan terakhir ke queue() mengirimkan permintaan. Anda juga dapat mengirim permintaan secara sinkron atau menggunakan masa depan, lihat panduan lengkap kami di RestAction Wiki.

Antarmuka RestAction juga mendukung sejumlah operator untuk menghindari panggilan balik:

• map
  Konversikan hasil RestAction ke nilai yang berbeda
• flatMap
  Hubungkan RestAction lain pada hasilnya
• delay
  Tunda elemen dari langkah sebelumnya

Serta kombinator seperti:

• and
  Memerlukan RestAction lain agar berhasil diselesaikan, berjalan secara paralel
• allOf
  Kumpulkan daftar banyak tindakan menjadi satu (lihat juga mapToResult )
• zip
  Mirip dengan and , tetapi menggabungkan hasilnya ke dalam daftar

Dan konfigurator seperti:

• timeout dan deadline
  Konfigurasikan berapa lama tindakan diperbolehkan berada dalam antrian, batalkan jika memakan waktu terlalu lama
• setCheck
  Menjalankan beberapa pemeriksaan tepat sebelum permintaan dikirim, ini dapat membantu ketika permintaan berada dalam antrian untuk sementara waktu
• reason
  Alasan log audit untuk suatu tindakan

Contoh :

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
}

Ini kemudian dapat digunakan dalam kode:

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

? Ekstensi

jda-ktx

Dibuat dan dikelola oleh MinnDevelopment.
Menyediakan ekstensi Kotlin untuk RestAction dan acara yang memberikan pengalaman Kotlin yang lebih idiomatis.

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()
    }
}

Ada sejumlah contoh yang tersedia di README.

pemain lava

Dibuat oleh sedmelluq dan sekarang dikelola oleh komunitas lavalink
Lavaplayer adalah perpustakaan paling populer yang digunakan oleh Bot Musik yang dibuat di Java. Ini sangat kompatibel dengan JDA dan Discord4J dan memungkinkan memutar audio dari YouTube, Soundcloud, Twitch, Bandcamp, dan penyedia lainnya.
Pustaka dapat dengan mudah diperluas ke lebih banyak layanan dengan mengimplementasikan AudioSourceManager Anda sendiri dan mendaftarkannya. Kami menyarankan untuk juga menggunakan udpqueue selain lavaplayer, untuk menghindari masalah stuttering yang disebabkan oleh jeda GC.

Disarankan untuk membaca bagian Penggunaan Lavaplayer untuk memahami implementasi yang tepat.
Sedmelluq menyediakan demo di repositorinya yang menyajikan contoh implementasi untuk JDA: https://github.com/lavalink-devs/lavaplayer/tree/master/demo-jda

udpqueue (perpanjangan dari jda-nas)

Dibuat dan dikelola oleh sedmelluq dan diperluas oleh MinnDevelopment
Menyediakan implementasi asli untuk Sistem Pengiriman Audio JDA untuk menghindari jeda GC yang berpotensi menyebabkan masalah pada pemutaran audio berkelanjutan.

Perhatikan bahwa sistem pengiriman ini membuat Klien UDP tambahan yang menyebabkan penerimaan audio tidak lagi berfungsi dengan baik, karena Discord mengidentifikasi Klien UDP pengirim sebagai penerima.

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

tautan lava

Dibuat oleh Freya Arbjerg dan sekarang dikelola oleh komunitas lavalink.

Lavalink adalah node pengirim audio mandiri yang populer berdasarkan Lavaplayer. Lavalink dibangun dengan mempertimbangkan skalabilitas, dan memungkinkan streaming musik melalui banyak server. Ini mendukung sebagian besar fitur Lavaplayer.

Lavalink digunakan oleh banyak bot besar, serta pengembang bot yang tidak bisa menggunakan perpustakaan Java seperti Lavaplayer. Jika Anda berencana menyajikan musik dalam skala yang lebih kecil dengan JDA, seringkali lebih baik menggunakan Lavaplayer secara langsung karena lebih mudah.

Lavalink-Client adalah klien Lavalink resmi untuk JDA.

Berkontribusi pada JDA

Jika Anda ingin berkontribusi pada JDA, pastikan untuk mendasarkan cabang Anda pada cabang master kami (atau cabang fitur) dan buat PR Anda ke dalam cabang yang sama .

Harap ikuti Pedoman Berkontribusi kami.

Jangan berharap pull request Anda langsung mendapat perhatian, terkadang butuh waktu lama untuk mendapat respon. Anda dapat bergabung dengan server perselisihan kami dan bertanya di #lib-dev sebelum mulai mengerjakan PR baru, untuk mendapatkan masukan lebih cepat dari anggota komunitas kami.

Perubahan yang Mengganggu

Karena sifat dari Discord API, perpustakaan akan secara teratur memperkenalkan perubahan-perubahan yang dapat mengganggu untuk memungkinkan adopsi fitur-fitur baru dengan cepat. Kami berusaha meminimalkan perubahan yang dapat menyebabkan gangguan ini, namun tidak dapat sepenuhnya menghindarinya.

Sebagian besar perubahan yang dapat menyebabkan gangguan akan mengakibatkan perubahan versi kecil ( 5.1.2 → 5.2.0 ).