🎵 Discore

A Modern, Lightning-Fast Discord API Wrapper for Dart

    ┌─────────────────────────────────────────┐
    │  🎵  DISCORE - Discord Made Simple  🎵  │
    └─────────────────────────────────────────┘

Your gateway to building powerful Discord bots with Dart ⚡

Getting Started • Documentation • Examples • Discord Server

---

┌─────────────────────────────────────────────────────────────────────┐
│  ✅  Discord API v10          │  ✅  Gateway WebSocket             │
│  ✅  Voice State Management   │  ✅  Complete REST API             │
│  ✅  Type-Safe Snowflakes     │  ✅  Strongly-Typed Events         │
│  ✅  Gateway Intents          │  ✅  Automatic Reconnection        │
│  ✅  Music Bot Support        │  ✅  Zero External Dependencies    │
└─────────────────────────────────────────────────────────────────────┘

dependencies:
  discore:
    path: ../discore  # Path to discore directory

dependencies:
  discore:
    git:
      url: https://github.com/your-org/discore.git
      ref: main

dependencies:
  discore: ^1.0.0

🤖 Your First Bot

import 'package:discore/discore.dart';

void main() async {
  // Create Discord client
  final client = DiscoreClient(
    token: 'YOUR_BOT_TOKEN',
    intents: GatewayIntents.guilds |
             GatewayIntents.guildMessages |
             GatewayIntents.messageContent,
  );
  
  // Listen for ready event
  client.on<ReadyEvent>((event) {
    print('Bot is ready: ${event.user?.username}');
  });
  
  // Listen for messages
  client.on<MessageCreateEvent>((event) {
    final message = event.message;
    
    if (message.content == '!ping') {
      client.rest.sendMessage(
        message.channelId,
        content: 'Pong!',
      );
    }
  });
  
  // Connect to Discord
  await client.connect();
}

    ♪ ♫ ♪ ♫ ♪ ♫ ♪ ♫ ♪ ♫ ♪ ♫
    🎤  Voice-Ready   🎧  Lavalink   🎵  Music Bots
    ♪ ♫ ♪ ♫ ♪ ♫ ♪ ♫ ♪ ♫ ♪ ♫

Discore includes comprehensive voice support for building music bots:

import 'package:discore/discore.dart';

void main() async {
  final client = DiscoreClient(
    token: 'YOUR_BOT_TOKEN',
    intents: GatewayIntents.guilds |
             GatewayIntents.guildVoiceStates |  // Required for voice!
             GatewayIntents.guildMessages |
             GatewayIntents.messageContent,
  );
  
  // Listen for voice state updates
  client.on<VoiceStateUpdateEvent>((event) {
    print('Voice state changed: ${event.voiceState.sessionId}');
  });
  
  // Listen for voice server updates
  client.on<VoiceServerUpdateEvent>((event) {
    print('Voice server: ${event.endpoint}');
  });
  
  // Join voice channel
  client.gateway.updateVoiceState(
    guildId: guildId,
    channelId: voiceChannelId,
    selfMute: false,
    selfDeaf: false,
  );
  
  await client.connect();
}

🎶 Perfect Integration with Lavalink (Auric)

Discore is designed to work seamlessly with Auric, a powerful Lavalink v4 client:

import 'package:discore/discore.dart' hide VoiceState;
import 'package:auric/auric.dart' hide ReadyEvent;

void main() async {
  final discord = DiscoreClient(token: token, intents: ...);
  final lavalink = LavalinkClient(host: 'localhost', port: 2333, ...);
  
  // Create integration - handles voice automatically!
  final integration = AuricDiscordIntegration(
    discord: discord,
    lavalink: lavalink,
  );
  
  // Join and play music with 2 lines!
  await integration.joinVoiceChannel(guildId: guildId, channelId: channelId);
  final player = integration.getPlayer(guildId.toString());
  await player.playTrack(track);
}

See Auric Integration Guide for more details.

1. Client Initialization

final client = DiscoreClient(
  token: 'YOUR_BOT_TOKEN',
  intents: GatewayIntents.guilds | GatewayIntents.guildMessages,
);

2. Gateway Intents

Required for receiving specific events:

// Common intents
GatewayIntents.guilds              // Guild events
GatewayIntents.guildMembers        // Member events (privileged)
GatewayIntents.guildVoiceStates    // Voice events (for music bots)
GatewayIntents.guildMessages       // Message events
GatewayIntents.messageContent      // Message content (privileged)

// Combine with bitwise OR
final intents = GatewayIntents.guilds |
                GatewayIntents.guildMessages |
                GatewayIntents.messageContent;

Note: Some intents are privileged and must be enabled in the Discord Developer Portal.

3. Event System

// Type-safe event listeners
client.on<ReadyEvent>((event) {
  print('Ready: ${event.user?.username}');
});

client.on<MessageCreateEvent>((event) {
  print('Message: ${event.message.content}');
});

client.on<GuildCreateEvent>((event) {
  print('Guild: ${event.guild.name}');
});

4. REST API

// Send message
await client.rest.sendMessage(
  channelId,
  content: 'Hello, Discord!',
);

// Get channel
final channel = await client.rest.getChannel(channelId);

// Create guild
final guild = await client.rest.createGuild(name: 'My Server');

// Get user
final user = await client.rest.getUser(userId);

5. Snowflake IDs

Discord uses Snowflake IDs - type-safe wrappers around strings:

final userId = Snowflake('123456789012345678');
final guildId = Snowflake('987654321098765432');

// Convert to string
print(userId.toString());  // '123456789012345678'

// Use in comparisons
if (message.author.id == userId) {
  print('Message from specific user');
}

DiscoreClient

Constructor

DiscoreClient({
  required String token,
  required int intents,
})

Methods

connect()

Future<void> connect()

Connects to Discord gateway.

disconnect()

Future<void> disconnect()

Disconnects from Discord gateway.

on<T>(Function(T) handler)

void on<T extends DiscoreEvent>(Function(T) handler)

Register an event handler for event type T.

Properties

gateway

GatewayClient gateway

Access to gateway operations (voice state updates, etc).

rest

RestClient rest

Access to REST API operations.

user

User? user

The bot's user object (available after ReadyEvent).

🏓 Ping Command

client.on<MessageCreateEvent>((event) {
  if (event.message.content == '!ping') {
    client.rest.sendMessage(
      event.message.channelId,
      content: 'Pong! 🏓',
    );
  }
});

👋 Welcome New Members

client.on<GuildMemberAddEvent>((event) {
  final welcomeChannelId = Snowflake('YOUR_CHANNEL_ID');
  
  client.rest.sendMessage(
    welcomeChannelId,
    content: 'Welcome ${event.member.user?.username}! 👋',
  );
});

🎤 Log Voice Activity

client.on<VoiceStateUpdateEvent>((event) {
  final user = event.voiceState.userId;
  final channel = event.voiceState.channelId;
  
  if (channel != null) {
    print('$user joined voice channel $channel');
  } else {
    print('$user left voice channel');
  }
});

👍 React to Messages

client.on<MessageCreateEvent>((event) {
  if (event.message.content.contains('awesome')) {
    client.rest.addReaction(
      event.message.channelId,
      event.message.id,
      '👍',
    );
  }
});

    ┌──────────────────────────────────────┐
    │     🎸  MUSIC BOT READY  🎹         │
    │                                      │
    │   Discore + Auric + Lavalink = 🔥   │
    └──────────────────────────────────────┘

Discore is perfect for building music bots when combined with Auric, a powerful Lavalink v4 client.

🎶 Why Discore + Auric?

Discore Discord Gateway & Voice

Auric Lavalink & Audio Streaming

Integration Automatic Bridge

🎼 Complete Music Bot Example

import 'package:discore/discore.dart' hide VoiceState;
import 'package:auric/auric.dart' hide ReadyEvent;

void main() async {
  // Setup Discord
  final discord = DiscoreClient(
    token: token,
    intents: GatewayIntents.guilds |
             GatewayIntents.guildVoiceStates |
             GatewayIntents.guildMessages |
             GatewayIntents.messageContent,
  );
  
  // Setup Lavalink
  final lavalink = LavalinkClient(
    host: 'localhost',
    port: 2333,
    password: 'youshallnotpass',
    userId: '',
  );
  
  // Create integration
  AuricDiscordIntegration? integration;
  
  discord.on<ReadyEvent>((event) async {
    await lavalink.connect();
    integration = AuricDiscordIntegration(
      discord: discord,
      lavalink: lavalink,
    );
    print('Music bot ready!');
  });
  
  // Handle play command
  discord.on<MessageCreateEvent>((event) async {
    if (event.message.content.startsWith('!play ')) {
      final query = event.message.content.substring(6);
      
      // Join voice
      await integration!.joinVoiceChannel(
        guildId: event.message.guildId!,
        channelId: voiceChannelId,
      );
      
      // Search and play
      final result = await lavalink.rest.loadTracks('ytsearch:$query');
      final player = integration!.getPlayer(event.message.guildId!.toString());
      await player.playTrack(result.tracks!.first);
      
      await discord.rest.sendMessage(
        event.message.channelId,
        content: '▶️ Playing: ${result.tracks!.first.info.title}',
      );
    }
  });
  
  await discord.connect();
}

Required Discord Intents

Enable in Discord Developer Portal:

1. Go to https://discord.com/developers/applications
2. Select your application
3. Go to "Bot" tab
4. Enable required privileged intents:
   • SERVER MEMBERS INTENT (for member events)
   • MESSAGE CONTENT INTENT (for reading message content)

Bot Permissions

For voice bots, your bot needs these permissions:

• View Channels (1024)
• Connect (1048576)
• Speak (2097152)
• Use Voice Activity (33554432)

Permission value: 36700160

Use this when generating your bot invite URL:

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=36700160&scope=bot

Bot doesn't receive messages

Solution: Enable the MESSAGE CONTENT INTENT in the Discord Developer Portal and use the messageContent intent flag.

Voice events not received

Solution: Enable the GUILD_VOICE_STATES intent in your code and ensure your bot has voice permissions in the server.

Gateway connection fails

Solution: Check your bot token is correct and your bot isn't rate limited.

"Privileged intent provided" error

Solution: Enable the required privileged intents in the Discord Developer Portal.

Models

All Discord API models are available in lib/src/models/:

• User - Discord user
• Guild - Discord guild (server)
• Channel - Discord channel
• Message - Discord message
• Member - Guild member
• Role - Guild role
• VoiceState - User voice state
• And more...

REST API

All REST endpoints are available via client.rest:

• Guild operations
• Channel operations
• Message operations
• User operations
• Role operations
• Webhook operations
• And more...

Gateway

Gateway operations via client.gateway:

• updateVoiceState() - Join/leave voice channels
• updatePresence() - Update bot status (coming soon)
• requestGuildMembers() - Request guild members (coming soon)

Discore is designed to work seamlessly with Auric for building music bots. The integration is automatic and requires minimal setup.

Benefits of Discore + Auric

• ✅ Automatic voice event handling
• ✅ Type-safe integration
• ✅ Simple 2-line API to join voice and play music
• ✅ Local dependency testing without publishing
• ✅ Production-ready error handling

See the Auric Integration Guide for complete details.

dart test

dart analyze

dart format .

📄 License

MIT License - see LICENSE file for details

---

🙏 Acknowledgments

Discord Excellent API docs

Dart Team Amazing language

Contributors Community support

---

📞 Support & Community

---

🔗 Quick Links

---

Made with ❤️ and ☕ by developers, for developers

    ╔═══════════════════════════════════════╗
    ║                                       ║
    ║    💻  Code  •  Learn  •  Build  🚀  ║
    ║                                       ║
    ║      Thank you for using Discore!     ║
    ║                                       ║
    ╚═══════════════════════════════════════╝

Star ⭐ this repo if you find it useful!

---

🎉 Happy Coding! 🎉

Build something amazing with Discore today!

---

© 2024 Discore. All rights reserved.