Discord4J

Discord4J 是一个快速、强大、无偏见、响应式的库，可以使用官方 Discord Bot API 在 Java、Kotlin 和其他 JVM 语言中快速轻松地开发 Discord 机器人。

🏃 快速示例

在这个 v3.2 版本的示例中，每当用户发送 !ping 消息时，机器人将立即回复 Pong!。

确保在开发者门户中启用了机器人的 消息内容 意图。

public class ExampleBot {

  public static void main(String[] args) {
    String token = args[0];
    DiscordClient client = DiscordClient.create(token);
    GatewayDiscordClient gateway = client.login().block();

    gateway.on(MessageCreateEvent.class).subscribe(event -> {
      Message message = event.getMessage();
      if ("!ping".equals(message.getContent())) {
        MessageChannel channel = message.getChannel().block();
        channel.createMessage("Pong!").block();
      }
    });

    gateway.onDisconnect().block();
  }
}

完整的项目示例，请查看我们的示例项目仓库这里。

🔗 快速链接

💎 优势

🚀 响应式 - Discord4J 遵循 reactive-streams 协议，确保 Discord 机器人无论规模大小都能平稳高效地运行。
📜 官方 - 自动限速、自动重连策略和一致的命名约定是 Discord4J 提供的众多功能之一，确保您的 Discord 机器人符合 Discord 的规范，并在与我们的库交互时提供最少的意外。
🛠️ 模块化 - Discord4J 将自身分解为模块，允许高级用户在较低级别与我们的 API 交互，以构建最小且快速的运行时，甚至添加自己的抽象。
⚔️ 强大 - Discord4J 可用于开发任何规模的机器人。我们提供了许多工具来开发大规模机器人，包括自定义分布式框架、堆外缓存，以及与 Reactor 的交互，允许与 Spring 和 Micronaut 等框架完全集成。
🏫 社区 - 我们以包容性的社区为荣，并愿意在遇到挑战时提供帮助；或者如果您只是想聊天！我们提供从 Discord4J 特定问题、一般编程和 Web 开发帮助，甚至 Reactor 特定问题的帮助。请务必访问我们的 Discord 服务器！

📦 安装

Gradle

repositories {
  mavenCentral()
}

dependencies {
  implementation 'com.discord4j:discord4j-core:3.2.5'
}

Gradle Kotlin DSL

repositories {
  mavenCentral()
}

dependencies {
  implementation("com.discord4j:discord4j-core:3.2.5")
}

Maven

<dependencies>
  <dependency>
    <groupId>com.discord4j</groupId>
    <artifactId>discord4j-core</artifactId>
    <version>3.2.5</version>
  </dependency>
</dependencies>

SBT

libraryDependencies ++= Seq(
  "com.discord4j" % "discord4j-core" % "3.2.5"
)

🔀 Discord4J 版本

Discord4J 3.2.x 包括更简单且更强大的 API 来构建请求、新的实体缓存和依赖项升级带来的性能改进。查看我们的迁移指南了解更多详情。

Discord4J	支持状态	网关/API	意图	交互
v3.3.x	开发中	v9	强制，非特权默认	完全支持
v3.2.x	当前	v8	强制，非特权默认	完全支持
v3.1.x	仅维护	v6	可选，无意图默认	仅维护

有关兼容性的更多详情，请参阅我们的文档。

🎉 赞助商

我们要特别感谢所有赞助商为我们提供资金,使我们能够继续开发和托管仓库资源以及推动社区项目。特别要感谢以下这些杰出的个人:

⛰️ 大型机器人

以下是一些使用Discord4J的真实大型机器人示例:

Groovy - 曾是Discord上第二大机器人,在2021年8月关闭前为超过400万个服务器提供音乐服务。
ZeroTwo - 一个动漫多功能机器人,被100多万个服务器使用。
DisCal - 将Google日历无缝且全面地集成到Discord中;服务超过2.1万个服务器。
Shadbot - 一个可配置的多功能机器人,具有音乐、赌博小游戏、视频游戏统计等功能;在2021年8月关闭前服务近1.2万个服务器。

你是否拥有使用Discord4J的大型机器人?请在我们的Discord中询问管理员或提交拉取请求,将你的机器人添加到列表中!

⚛️ 响应式

Discord4J使用Project Reactor作为我们异步框架的基础。Reactor提供了一个简单而强大的API,使用户能够减少资源并提高性能。

public class ExampleBot {

  public static void main(String[] args) {
    String token = args[0];
    DiscordClient client = DiscordClient.create(token);

    client.login().flatMapMany(gateway -> gateway.on(MessageCreateEvent.class))
      .map(MessageCreateEvent::getMessage)
      .filter(message -> "!ping".equals(message.getContent()))
      .flatMap(Message::getChannel)
      .flatMap(channel -> channel.createMessage("Pong!"))
      .blockLast();
  }
}

Discord4J还提供了几种方法来帮助更好地组合响应式链,例如GatewayDiscordClient#withGateway和带有错误处理重载的EventDispatcher#on。

public class ExampleBot {

    public static void main(String[] args) {
        String token = args[0];
        DiscordClient client = DiscordClient.create(token);

        client.withGateway(gateway -> {
            Publisher<?> pingPong = gateway.on(MessageCreateEvent.class, event ->
                    Mono.just(event.getMessage())
                            .filter(message -> "!ping".equals(message.getContent()))
                            .flatMap(Message::getChannel)
                            .flatMap(channel -> channel.createMessage("Pong!")));

            Publisher<?> onDisconnect = gateway.onDisconnect()
                    .doOnTerminate(() -> System.out.println("已断开连接!"));

            return Mono.when(pingPong, onDisconnect);
        }).block();
    }
}

🧵 Kotlin

通过使用Reactor,Discord4J在与kotlinx-coroutines-reactor库配对时与Kotlin协程有原生集成。

val token = args[0]
val client = DiscordClient.create(token)

client.withGateway {
  mono {
    it.on(MessageCreateEvent::class.java)
      .asFlow()
      .collect {
        val message = it.message
        if (message.content == "!ping") {
          val channel = message.channel.awaitSingle()
          channel.createMessage("Pong!").awaitSingle()
        }
      }
  }
}
.block()

🐛 常见错误

在未启用消息内容意图的情况下调用Message#getContent

从2022年9月1日起,Discord要求机器人启用"MESSAGE_CONTENT"意图才能访问消息内容。要启用该意图,请前往Discord开发者门户并选择你的机器人。然后,转到"Bot"选项卡并启用"Message Content"意图。然后,在创建DiscordClient时将该意图添加到你的机器人中:

GatewayDiscordClient client = DiscordClient.create(token)
  .gateway()
  .setEnabledIntents(IntentSet.nonPrivileged().and(IntentSet.of(Intent.MESSAGE_CONTENT)))
  .login()
  .block();

📚 示例

📑 消息嵌入

// IMAGE_URL = https://cdn.betterttv.net/emote/55028cd2135896936880fdd7/3x
// ANY_URL = https://www.youtube.com/watch?v=5zwY50-necw
MessageChannel channel = ...
EmbedCreateSpec.Builder builder = EmbedCreateSpec.builder();
builder.author("setAuthor", ANY_URL, IMAGE_URL);
builder.image(IMAGE_URL);
builder.title("setTitle/setUrl");
builder.url(ANY_URL);
builder.description("setDescription\n" +
      "大D:是setImage\n" +
      "小D:是setThumbnail\n" +
      "<-- setColor");
builder.addField("addField", "inline = true", true);
builder.addField("addFIeld", "inline = true", true);
builder.addField("addFile", "inline = false", false);
builder.thumbnail(IMAGE_URL);
builder.footer("setFooter --> setTimestamp", IMAGE_URL);
builder.timestamp(Instant.now());
channel.createMessage(builder.build()).block();

🏷️ 通过角色名称查找成员

用户通常更喜欢使用名称而不是ID。这个例子将演示如何搜索所有具有特定名称角色的成员。

Guild guild = ...
Set<Member> roleMembers = new HashSet<>();

for (Member member : guild.getMembers().toIterable()) {
  for (Role role : member.getRoles().toIterable()) {
    if ("Developers".equalsIgnoreCase(role.getName())) {
      roleMembers.add(member);
      break;
    }
  }
}

return roleMembers;

或者,使用Reactor:

Guild guild = ...
return guild.getMembers()
  .filterWhen(member -> member.getRoles()
    .map(Role::getName)
    .any("Developers"::equalsIgnoreCase));

🎵 语音和音乐

Discord4J为语音连接提供全面支持,并能够向连接到同一频道的其他用户发送音频。Discord4J可以接受任何Opus音频源,LavaPlayer是从YouTube、SoundCloud和其他提供商下载和编码音频的首选解决方案。

[!警告]
原始的LavaPlayer不再维护。可以在这里找到一个新的维护版本。如果你需要Java 8支持,可以使用Walkyst的LavaPlayer分支,但它也不再维护!

首先,你需要实例化和配置一个通常是全局的AudioPlayerManager。

public static final AudioPlayerManager PLAYER_MANAGER;
static {
  PLAYER_MANAGER = new DefaultAudioPlayerManager();
  // 这是Discord4J可以利用的优化策略，以最小化内存分配
  PLAYER_MANAGER.getConfiguration().setFrameBufferFactory(NonAllocatingAudioFrameBuffer::new);
  AudioSourceManagers.registerRemoteSources(PLAYER_MANAGER);
  AudioSourceManagers.registerLocalSource(PLAYER_MANAGER);
}

接下来，我们需要允许Discord4J从AudioPlayer读取到AudioProvider。

public class LavaPlayerAudioProvider extends AudioProvider {

  private final AudioPlayer player;
  private final MutableAudioFrame frame;

  public LavaPlayerAudioProvider(AudioPlayer player) {
    // 为Discord4J的AudioProvider分配一个ByteBuffer来存储Discord的音频数据
    super(ByteBuffer.allocate(StandardAudioDataFormats.DISCORD_OPUS.maximumChunkSize()));
    // 设置LavaPlayer的AudioFrame使用与Discord4J相同的缓冲区
    frame = new MutableAudioFrame();
    frame.setBuffer(getBuffer());
    this.player = player;
  }

  @Override
  public boolean provide() {
    // AudioPlayer将音频数据写入AudioFrame
    boolean didProvide = player.provide(frame);

    if (didProvide) {
      getBuffer().flip();
    }

    return didProvide;
  }
}

通常，音频播放器会有队列或内部播放列表，让用户能够在歌曲播放完毕或要求跳过时自动循环播放歌曲。我们可以通过创建AudioTrackScheduler来外部管理这个队列，并将其传递给代码的其他部分，以允许查看、排队或跳过音轨。

public class AudioTrackScheduler extends AudioEventAdapter {

  private final List<AudioTrack> queue;
  private final AudioPlayer player;

  public AudioTrackScheduler(AudioPlayer player) {
    // 队列可能被不同的线程修改，所以要保证内存安全
    // 但这并不能消除目前存在的几个竞态条件
    queue = Collections.synchronizedList(new LinkedList<>());
    this.player = player;
  }

  public List<AudioTrack> getQueue() {
    return queue;
  }

  public boolean play(AudioTrack track) {
    return play(track, false);
  }

  public boolean play(AudioTrack track, boolean force) {
    boolean playing = player.startTrack(track, !force);

    if (!playing) {
      queue.add(track);
    }

    return playing;
  }

  public boolean skip() {
    return !queue.isEmpty() && play(queue.remove(0), true);
  }

  @Override
  public void onTrackEnd(AudioPlayer player, AudioTrack track, AudioTrackEndReason endReason) {
    // 如果音轨自然完成（FINISHED）或无法播放（LOAD_FAILED），则推进播放器
    if (endReason.mayStartNext) {
      skip();
    }
  }
}

目前，Discord每个服务器只允许一个语音连接。在这个限制下，将我们目前处理的三个组件（AudioPlayer、LavaPlayerAudioProvider和AudioTrackScheduler）与特定的Guild关联起来是合乎逻辑的，它们自然由某个Snowflake唯一标识。从逻辑上讲，将这些对象组合成一个对象是有意义的，这样可以将它们放入Map中，在连接到语音频道或处理命令时更容易检索。

public class GuildAudioManager {

  private static final Map<Snowflake, GuildAudioManager> MANAGERS = new ConcurrentHashMap<>();

  public static GuildAudioManager of(Snowflake id) {
    return MANAGERS.computeIfAbsent(id, ignored -> new GuildAudioManager());
  }

  private final AudioPlayer player;
  private final AudioTrackScheduler scheduler;
  private final LavaPlayerAudioProvider provider;

  private GuildAudioManager() {
    player = PLAYER_MANAGER.createPlayer();
    scheduler = new AudioTrackScheduler(player);
    provider = new LavaPlayerAudioProvider(player);

    player.addListener(scheduler);
  }

  // getter方法
}

最后，我们需要连接到语音频道。连接后，你会得到一个VoiceConnection对象，之后可以通过调用VoiceConnection#disconnect来断开与语音频道的连接。

VoiceChannel channel = ...
AudioProvider provider = GuildAudioManager.of(channel.getGuildId()).getProvider();
VoiceConnection connection = channel.join(spec -> spec.setProvider(provider)).block();

// 在AudioLoadResultHandler中，将AudioTrack实例添加到AudioTrackScheduler（并向用户发送通知）
PLAYER_MANAGER.loadItem("https://www.youtube.com/watch?v=dQw4w9WgXcQ", new AudioLoadResultHandler() { /* 重写方法 */ })

### ❌ 自动断开语音频道连接

通常，在所有人都离开语音频道后，机器人应该自动断开连接，因为用户经常忘记手动断开机器人。下面的示例展示了如何使用反应式方法而不是命令式方法来优雅地解决这个问题。

VoiceChannel channel = ...
Mono<Void> onDisconnect = channel.join(spec -> { /* TODO 初始化 */ })
  .flatMap(connection -> {
    // 机器人本身有一个VoiceState；1个VoiceState表示机器人独自一人
    Publisher<Boolean> voiceStateCounter = channel.getVoiceStates()
      .count()
      .map(count -> 1L == count);

    // 10秒后，检查机器人是否独自一人。这在机器人独自加入，
    // 但连接后没有其他人加入的情况下很有用
    Mono<Void> onDelay = Mono.delay(Duration.ofSeconds(10L))
      .filterWhen(ignored -> voiceStateCounter)
      .switchIfEmpty(Mono.never())
      .then();

    // 当人们加入和离开`channel`时，检查机器人是否独自一人。
    // 注意，第一个过滤器并非严格必要，但它可以防止许多不必要的缓存调用
    Mono<Void> onEvent = channel.getClient().getEventDispatcher().on(VoiceStateUpdateEvent.class)
      .filter(event -> event.getOld().flatMap(VoiceState::getChannelId).map(channel.getId()::equals).orElse(false))
      .filterWhen(ignored -> voiceStateCounter)
      .next()
      .then();

    // 如果onDelay或onEvent完成，则断开机器人连接！
    return Mono.first(onDelay, onEvent).then(connection.disconnect());
  });