|
1 | | - |
2 | | - |
3 | | - |
4 | | - |
| 1 | +# Mineral - Discord Bot Framework for Dart |
5 | 2 |
|
6 | 3 |  |
7 | 4 |
|
8 | | -## The concepts |
9 | | -Mineral meets a need for scalability over time but also within a team of developers thanks to a modular and flexible software architecture. |
10 | | -modular and flexible software architecture. |
| 5 | +Mineral meets a need for scalability over time but also within a team of developers thanks to a modular and flexible software architecture. modular and flexible software architecture. |
11 | 6 |
|
12 | | -Don't reinvent the wheel, the framework facilitates the sharing and accessibility of your data across your entire |
13 | | -of your application. Design modules that can be reused in several of your projects. |
| 7 | +Don't reinvent the wheel, the framework facilitates the sharing and accessibility of your data across your entire of your application. Design modules that can be reused in several of your projects. |
14 | 8 |
|
15 | | -We want to make your life easier, Mineral provides you with dedicated classes for each of the following features of |
16 | | -Discord: events, commands, context menus, etc... |
| 9 | +We want to make your life easier, Mineral provides you with dedicated classes for each of the following features of Discord: events, commands, context menus, etc... |
17 | 10 |
|
18 | | -In order to improve your development experience, we wanted to integrate some features that do not exist in Discord but are very interesting |
19 | | -but very interesting features such as intra-application data sharing through the |
20 | | -Stores, a bunch of additional events around your discord servers or access in only one |
21 | | -and 2 lines of code to an API through official Dart packages delivering recurring features such as tickets |
22 | | -recurring features such as tickets, invitations or voice chancels on demand. |
| 11 | +In order to improve your development experience, we wanted to integrate some features that do not exist in Discord but are very interesting but very interesting features such as intra-application data sharing through the Stores, a bunch of additional events around your discord servers or access in only one and 2 lines of code to an API through official Dart packages delivering recurring features such as tickets recurring features such as tickets, invitations or voice chancels on demand. |
23 | 12 |
|
24 | | -## Mineral tour |
25 | | -### The events |
| 13 | +With Mineral, you can unleash the full potential of your bot and bring your Discord server to life. |
| 14 | + |
| 15 | +## Key Features |
| 16 | + |
| 17 | +### Command Handling |
| 18 | + |
| 19 | +Commands in Mineral serve the purpose of defining specific actions that your bot can perform in response to a given command. |
| 20 | +They allow users to communicate with your bot and interact with it in a structured way. |
26 | 21 |
|
27 | | -They are the heart of any Discord application, events allow you to act at a point in your application's lifecycle when an action is performed on the Discord server where your application is present. |
28 | 22 | ```dart |
29 | | -import 'package:mineral/framework.dart'; |
30 | | -import 'package:mineral/core/events'; |
31 | | -
|
32 | | -class MessageReceived extends MineralEvent<MessageCreate> { |
33 | | - Future<void> handle (Message message) async { |
34 | | - if (!message.author.isBot) { |
35 | | - await message.reply(content: 'Hello ${message.author} ! 👋'); |
36 | | - } |
| 23 | +class HelloWorldCommand extends MineralCommand<GuildCommandInteraction> { |
| 24 | + HelloWorldCommand(): super( |
| 25 | + label: Display('hello'), |
| 26 | + description: Display('Add new member to the ticket !'), |
| 27 | + options: [ |
| 28 | + CommandOption.user(Display('member'), Display('The member to add to the ticket !')) |
| 29 | + ] |
| 30 | + ); |
| 31 | +
|
| 32 | + Future<void> handle (interaction) async { |
| 33 | + final targetMember = interaction.getMember('member'); |
| 34 | +
|
| 35 | + await interaction.reply( |
| 36 | + content: 'Hello $targetMember', |
| 37 | + private: true |
| 38 | + ); |
37 | 39 | } |
38 | 40 | } |
39 | 41 | ``` |
40 | 42 |
|
41 | | -In order to simplify the association between a component (buttons, selection menus...) and its resulting action, you can define a customId key in order to execute your code only if the given interaction is the right one. |
| 43 | +### Event Listeners |
| 44 | +Commands in Mineral serve the purpose of defining specific actions that your bot can perform in response to a given command. |
| 45 | +They allow users to communicate with your bot and interact with it in a structured way. |
42 | 46 |
|
43 | | -Consider the component displaying buttons below : |
44 | | -```dart |
45 | | -final button = ButtonBuilder.fromButton( |
46 | | - label: 'My buttton', |
47 | | - customId: 'my-custom-id', |
48 | | - style: ButtonStyle.primary |
49 | | -); |
50 | | -``` |
51 | | - |
52 | | -### The slash commands |
53 | | -Since version 8 of the websocket, Discord have announced their willingness to migrate traditional commands designed with the MessageCreate event to dedicated components that we call clash commands. |
| 47 | +By utilizing events, you can create dynamic and interactive experiences within your Discord bot. |
| 48 | +Events allow you to capture and respond to various actions and changes happening in real-time, enabling your bot to adapt and provide relevant functionality based on the events occurring in the Discord environment. |
54 | 49 |
|
55 | | -To simplify their design, we provide you with dedicated classes, please consider the examples below. |
56 | 50 | ```dart |
57 | | -import 'package:mineral/framework.dart'; |
58 | | -import 'package:mineral/core/api.dart'; |
59 | | -
|
60 | | -class HelloCommand extends MineralCommand { |
61 | | - HelloCommand() { |
62 | | - register(CommandBuilder('hello', 'Say hello to everyone !', scope: Scope.guild)); |
63 | | - } |
64 | | - |
65 | | - Future<void> handle (CommandInteraction interaction) async { |
66 | | - final Role everyone = interaction.guild?.roles.everyone; |
67 | | - |
68 | | - await interaction.reply(content: 'Hello $everyone'); |
| 51 | +class Ready extends MineralEvent<ReadyEvent> with Console { |
| 52 | + Future<void> handle (event) async { |
| 53 | + console.info('${event.client.user.username} is ready to use !'); |
69 | 54 | } |
70 | 55 | } |
71 | 56 | ``` |
72 | 57 |
|
73 | | -### The menu context |
74 | | -Since the introduction of the new command management system, Discord has also introduced a very interesting feature that allows you to perform an action by taking as a source not a command to be written in the chat, but through a user or a message (very useful to postpone a user or a moved message). |
| 58 | +### Interactive Components |
| 59 | +By utilizing events, you can create dynamic and interactive experiences within your Discord bot. |
| 60 | +Events allow you to capture and respond to various actions and changes happening in real-time, enabling your bot to adapt and provide relevant functionality based on the events occurring in the Discord environment. |
| 61 | + |
| 62 | +By incorporating interactive components into your Discord bot, you can enhance user engagement and provide a more interactive and dynamic experience. They allow users to interact with your bot directly within messages, enabling them to perform actions, make choices, and receive real-time feedback. Interactive components add an extra layer of interactivity to your bot's functionality and can greatly enhance the user experience. |
| 63 | + |
| 64 | +Interactive components enhance the way buttons are used in Discord bots by introducing interactivity and real-time feedback. |
| 65 | + |
| 66 | +A single file allows you to design your composanbt and attach a dedicated handler when the user interacts with it. |
75 | 67 |
|
76 | | -In order to fully exploit this functionality, a specific class is created. |
77 | 68 | ```dart |
78 | | -import 'package:mineral/core/api.dart'; |
79 | | -import 'package:mineral/framework.dart'; |
| 69 | +class MyButton extends InteractiveButton { |
| 70 | + MyButton(): super('my-id'); |
80 | 71 |
|
81 | | -class ContextMenu extends MineralContextMenu { |
82 | | - ContextMenu () { |
83 | | - register('message-context', ContextMenuType.message); |
| 72 | + @override |
| 73 | + Future<void> handle (ButtonCreateEvent event) async { |
| 74 | + await event.interaction.reply( |
| 75 | + content: 'Hello Mineral !', |
| 76 | + private: true |
| 77 | + ); |
84 | 78 | } |
85 | 79 |
|
86 | 80 | @override |
87 | | - Future<void> handle(Message message) async { |
88 | | - await message.reply(content: message.content); |
89 | | - } |
| 81 | + ButtonBuilder build () => ButtonBuilder.button(customId) |
| 82 | + ..setLabel('Mineral') |
| 83 | + ..setStyle(ButtonStyle.primary); |
90 | 84 | } |
91 | 85 | ``` |
92 | 86 |
|
93 | | -### Data sharing |
94 | | - |
95 | | -The Discord.js documentation advocates in its examples the use of the very bad practice of only developing in a single file that contains your entire Discord application. |
96 | | - |
97 | | -Working with this principle allows each of your listeners to use variables defined within the same file, so it is very easy to share data across multiple listeners. |
98 | | - |
99 | | -The Mineral framework forces you to design your application following the S principle of the SOLID acronym in order to respect the principle of "single responsibility" (each class/function must perform only one action) which allows to obtain a better scalability in time and at the same time to limit to the maximum the repetition/duplication of code. |
100 | | - |
101 | | -The use of this architecture implies that it becomes difficult to share states across your different classes. |
102 | | - |
103 | | -In order to facilitate this sharing, the framework offers you the possibility to design classes dedicated to this need thanks to the @Store decorator. |
| 87 | +### State Management |
| 88 | +Share and manage data across your bot using shared states. |
104 | 89 |
|
105 | 90 | ```dart |
106 | | -import 'package:mineral/framework.dart'; |
| 91 | +class MyState extends MineralState<int> { |
| 92 | + MyState() : super(0); |
107 | 93 |
|
108 | | -class MyState extends MineralState<List<int>> { |
109 | | - MyState(): super('MyState', 'MyState description'); |
| 94 | + void increment() => state++; |
110 | 95 |
|
111 | | - // Add string to this |
112 | | - void addItem (int value) => state.add(value); |
113 | | - |
114 | | - // Verify if this contains given value |
115 | | - bool has (int value) => state.contains(value); |
| 96 | + void decrement() => state--; |
116 | 97 | } |
117 | 98 | ``` |
118 | 99 |
|
119 | | -When you register your class in your hand, your blind is accessible from any command, event or context menu file. |
| 100 | +- **HTTP API Integration:** Seamlessly interact with the Discord API to perform actions such as sending messages, updating user information, creating channels, and more. |
120 | 101 |
|
121 | | -`main.dart` |
122 | | -```dart |
123 | | -Future<void> main () async { |
124 | | - Kernel kernel = Kernel() |
125 | | - ..intents.defined(all: true) |
126 | | - ..events.register([MessageReceived()]) |
127 | | - ..stores.register([MyState()]); |
128 | | - |
129 | | - await kernel.init(); |
130 | | -} |
131 | | -``` |
| 102 | +- **Container and Dependency Injection:** Take advantage of the powerful dependency injection capabilities provided by Mineral's built-in container, making it easy to manage and access your services and dependencies. |
132 | 103 |
|
133 | | -Now that your store is registered within your application, you can now access your shared state using the code below, we will illustrate the operation on the MessageCreate event. |
134 | | -```dart |
135 | | -import 'package:mineral/framework.dart'; |
136 | | -import 'package:mineral/core/events'; |
137 | | -
|
138 | | -class MessageCreate extends MineralEvent<MessageCreate> with Console { |
139 | | - Future<void> handle (Message message) async { |
140 | | - final myState = states.use<MyStore>(); |
141 | | - myState.addItem(1); |
142 | | - |
143 | | - console.info(message: 'MyState contains ${store.state.length} items.'); |
144 | | - } |
145 | | -} |
146 | | -``` |
| 104 | +- **Error Handling and Logging:** Benefit from robust error handling and logging mechanisms to ensure smooth operation and easy debugging of your bot. |
| 105 | + |
| 106 | +- **Extensible Architecture:** Extend and customize Mineral to fit your specific needs with ease. The framework provides a modular and extensible architecture that allows for easy integration of custom modules and plugins. |
| 107 | + |
| 108 | +## Community and Support |
| 109 | +Join our vibrant community of Discord bot developers on Discord to get support, share your projects, and collaborate with other developers. |
| 110 | + |
| 111 | +We also encourage you to contribute to the Mineral project by reporting issues, suggesting new features, or submitting pull requests on GitHub. |
147 | 112 |
|
148 | | -Join our ranks and add your contribution to the best discord framework for Dart 💪 |
| 113 | +Start your journey with Mineral today and create extraordinary Discord bots that will elevate your server to new heights! |
149 | 114 |
|
150 | 115 | [](https://github.com/mineral-dart/core) |
151 | 116 | [](https://discord.gg/fH9UQDMZSn) |
|
0 commit comments