mirror of
https://github.com/mamoe/mirai.git
synced 2025-02-09 06:57:16 +08:00
Update docs
This commit is contained in:
Him188
parent
ed9a3a879b
commit
640aad8b23
@ -1,26 +0,0 @@
|
||||
# 插件结构
|
||||
|
||||
请注意, 如果你有IDEA，推荐使用idea插件, 可以全自动配置环境, 插件结构, debug运行<br>
|
||||
本文是为没有IDEA, 也想开发mirai-console插件的人准备的, 除去插件结构外, 您还需要自己配置运行环境<br>
|
||||
|
||||
|
||||
### Plugin.yml
|
||||
你应当有一个plugin.yml, 放置在resources文件夹下<br>
|
||||
```
|
||||
name: "插件名字"
|
||||
author: "作者名字"
|
||||
version: "0.1.0"
|
||||
main: "my_package_name.ExamplePluginBase"
|
||||
info: "插件介绍"
|
||||
depends: []
|
||||
```
|
||||
其中main指向 你的PluginBase
|
||||
|
||||
### PluginBase
|
||||
pluginBase为你插件的启动点, 生命管理周期, 他应该被放到src/main/java或src/main/kotlin下<br>
|
||||
一般来说, 他要被放到一个package下, 假如它叫MyPluginBase, 放到package为my.package下, 那么plugin.yml的main则要写my.package.MyPluginBase<br>
|
||||
你可以在下面的DEMO中找到PluginBase的一些简单例子
|
||||
|
||||
<br><br>
|
||||
## DEMO
|
||||
[插件结构例子](https://github.com/mamoe/mirai-console/tree/master/PluginDocs/demo)
|
||||
@ -1,166 +0,0 @@
|
||||
# 如何开发Mirai-console插件
|
||||
|
||||
|
||||
####
|
||||
首先, 你需要一些基础的编程知识<br>
|
||||
开发插件的下限很低, 仅仅了解开发用的语言即可<br>
|
||||
当然, 插件开发的上限也很高, Mirai-Console的插件的控制层下至简单的回复逻辑, 上至修改与QQ通讯的协议<br>
|
||||
目前, Java与Kotlin均可用来开发, 仅需了解任意一门语言, 都可以进行插件开发<br>
|
||||
|
||||
### 我没有学习过任何与编程相关的知识或我没有学过这两种语言
|
||||
你有两个选择，学习Java或者Kotlin<br>
|
||||
学习Java/Kotlin的好处: 学习速度相对较快, 学习资料多<br>
|
||||
学习Kotlin的好处: mirai源开发语言为kotlin, 学习了kotlin可以顺便读懂mirai及其分支项目, 更容易写出更高质量的插件<br>
|
||||
|
||||
方法1: 认真读书<br>
|
||||
[30分钟精通JAVA](https://www.runoob.com/java/java-tutorial.html) 最低只需要学完Java 教程, Java 面向对象两章<br>
|
||||
[30分钟精通Kotlin](https://www.kotlincn.net/docs/reference/) 最低只需要学完类与对象<br>
|
||||
|
||||
方法2: 通过例子边学插件边学语言<br>
|
||||
需要较高悟性, 不推荐完全没有接触编程的人尝试<br>
|
||||
## 我需要什么?
|
||||
### Java环境
|
||||
JDK是Java语言的软件开发工具包，开发Java软件时必须安装jdk。<br>
|
||||
推荐安装JDK 11, 最低推荐使用JDK 8来开发Mirai-Console插件。<br>
|
||||
|
||||
|
||||
打开控制台（windows按徽标键+R，在弹出的窗口输入cmd然后回车；linux直接打开控制台），输入以下代码并回车：
|
||||
```$xslt
|
||||
javac -version
|
||||
```
|
||||
返回的应该类似于以下的结果：
|
||||
```$xslt
|
||||
javac 1.8.0_60-ea
|
||||
```
|
||||
如果类似于以上的结果，恭喜你已经成功的安装了jdk 8并且不希望更新版本可以跳过这个步骤的教程。<br>
|
||||
如果返回的版本是1.7.0或者更旧的版本，或者返回的类似于“'javac' 不是内部或外部命令，也不是可运行的程序或批处理文件”，说明你还没有安装最新版本的jdk。<br>
|
||||
|
||||
#### 安装最新版JDK
|
||||
请打开以下链接下载JDK, 推荐使用稳定的11：https://www.oracle.com/java/technologies/javase-downloads.html<br>
|
||||
安装过程因系统而异，这里就不详细讲解了。<br>
|
||||
另外，jdk安装包也包含相应版本的jre，所以你无需在java官网上再下载安装一次jre。<br>
|
||||
在windows系统安装jdk后，你需要配置jdk来保证命令行正常使用。<br>
|
||||
#### windows系统中旧版JDK的配置
|
||||
大部分JDK在安装时已经可以自己配置, 请直接检查是否成功, 如不成功在阅读本块<br>
|
||||
检查是否配置成功: 点击windows徽标键+R，输入cmd并回车，在打开的控制台输入“javac -version”和“java -version”，如果都能正确的返回版本信息，说明配置环境变量成功了。至此，你的jdk已经安装并配置完成<br>
|
||||
如果没有, 以下只写了简单流程, 如需要图文帮助可以搜索"windows系统中JDK的配置"<br>
|
||||
- 右键“计算机”，点击“属性”，<br>
|
||||
- 在弹出的窗口中点击“高级系统设置”，“环境变量”，<br>
|
||||
- 点击“系统变量”下面的“新建”，在弹出的窗口的“变量名”输入“JAVA_HOME”（不带引号），“变量值”输入你之前安装jdk的安装路径，我的是“C:\Program Files\Java\jdk1.8.0_60”（不带引号），这里根据你安装jdk的路径来输入。然后点击确定<br>
|
||||
- 在“系统变量”中寻找“Path”（不带引号）变量，选中后点击“编辑”，在“变量值”的最后面（注意不是把整个替换，是添加在最后面）输入：
|
||||
```$xslt
|
||||
%JAVA_HOME%\bin;%JAVA_HOME%\jre\bin;
|
||||
```
|
||||
这里要注意原来Path的变量值末尾有没有;号，如果没有，先输入;号再输入上面的代码。<br>
|
||||
点击“系统变量”下面的“新建”，在弹出的窗口的“变量名”输入“CLASSPATH”（不带引号），“变量值”输入以下的字符串（注意，最前面有一个点“.”不要忘了）：
|
||||
```$xslt
|
||||
.;%JAVA_HOME%\lib;%JAVA_HOME%\lib\tools.jar
|
||||
```
|
||||
- 检查是否配置成功。
|
||||
#### IDE
|
||||
IDE，即集成开发环境，是辅助编程开发的软件。使用合适的IDE能有效地减少代码语法错误、编译麻烦等问题，加大开发效率。目前java开发者常用的IDE有Eclipse，NetBeans，IntelliJ IDEA等软件。我这里使用IntelliJ IDEA 14.1（以下简称“IDEA”）与windows 7系统为例子，来讲IDE的安装和配置。<br>
|
||||
强烈推荐IDEA， IDEA可以使用idea插件[mirai-console-intellij](https://github.com/mamoe/mirai-console-intellij)快速进行插件开发
|
||||
<br>
|
||||
打开[IntelliJ IDEA的官方网站]( http://www.jetbrains.com/idea/)，点击“Get IntelliJ IDEA now”
|
||||
<br>
|
||||
IDEA分付费的Ultimate版和免费的Community版，选择自己的系统后，根据自己的需求点击下载使用，一般的使用免费的Community版就足够了。
|
||||
<br>
|
||||
|
||||
### 我要如何开始
|
||||
**此处使用IDEA作为演示IDE**<br>
|
||||
新手只推荐使用IDEA, 如执着于不使用idea, 可以阅读[PluginStructure](PluginStructure.MD)手动构建插件环境<br>
|
||||
|
||||
#### IDE准备
|
||||
安装idea插件[mirai-console-intellij](https://github.com/mamoe/mirai-console-intellij), 这是一个用于快速创建Mirai Console插件的IDE插件 <br>
|
||||
1: 自动安装<br>
|
||||
打开IDEA, 点击Preferences或按[Ctrl+Alt+Shift+S]/[Cmd+Alt+Shift+S], 点击插件[Plugins], 市场[Market place], 搜索Mirai, 安装Mirai-Console<br>
|
||||
预计2020/3/11号后才可以在market里搜索到<br>
|
||||
<br>
|
||||
|
||||
2: 手动安装<br>
|
||||
前往[这里](https://github.com/mamoe/mirai-console-intellij/releases)下载最新的插件[.jar]<BR>
|
||||
打开IDEA, 点击Preferences或按[Ctrl+Alt+Shift+S]/[Cmd+Alt+Shift+S], 按下图操作, 选择下载的jar 然后重启IDE<br>
|
||||
|
||||
|
||||
<br>
|
||||
|
||||
#### 启动项目
|
||||
1： 点击New Project<br>
|
||||
2： 在左侧选择Mirai Console Plugin<br>
|
||||
3： 根据下图辅助填写信息<br>
|
||||
<br>
|
||||
4: 点击[next]<br>
|
||||
5: 根据下图辅助继续填写信息<br>
|
||||
<br>
|
||||
6: 点击[next]<br>
|
||||
7: 最后一页与本地储存位置有关, 如不懂使用默认即可<br>
|
||||
8: 点击[Finish]稍作等待<br>
|
||||
9: 等待这个页面加载出来<br>
|
||||
<br>
|
||||
10: 点击右下↘的Import gradle project或Import Maven Project<br>
|
||||
11: 等待进度条结束<br>
|
||||
<br>
|
||||
12: 等待这个页面加载出来(这是第一页选的Java语言, kotlin类似)<br>
|
||||
<br>
|
||||
13: 插件环境正式完成<br>
|
||||
|
||||
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
|
||||
#### 如何运行
|
||||
|
||||
1: 根据下图帮助打开gradle window 并双击对应task
|
||||
<br>
|
||||
2: 此时你应该能看到正在进行编译，编译完成之后将会自动启动console<br>
|
||||
3: 输入密码完成登录，开始测试
|
||||
|
||||
<br>
|
||||
<br>
|
||||
|
||||
#### 如何debug
|
||||
|
||||
在进行了上述配置之后，直接用debug模式运行task可能会无法成功断点，请按照以下方式配置<br>
|
||||
1: 点击这里打开运行配置<br>
|
||||
<br>
|
||||
2: 选择刚刚自带生成的配置并复制一份<br>
|
||||
<br>
|
||||
3: 修改复制的配置,按照下图添加 `--debug-jvm`<br>
|
||||
<br>
|
||||
4: 添加Remote Debug，一般来说不需要更改设置，直接确认即可<br>
|
||||
<br>
|
||||
5: 运行task<br>
|
||||
<br>
|
||||
6: 出现以下显示的时候切换到Remote并点击debug<br>
|
||||
<br>
|
||||
<br>
|
||||
7: 当调试器附加成功时程序才会开始运行，因此你可以在任何地方使用断点，当然也可能会出现一些问题导致某些地方断点失效<br>
|
||||
<br>
|
||||
|
||||
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
|
||||
|
||||
#### 如何打包插件
|
||||
1: 根据下图帮助打开gradle window[maven同理]<br>
|
||||
<br>
|
||||
2: 根据下图帮助点击JAR<br>
|
||||
<br>
|
||||
3: 在这里找到成品, 完成<br>
|
||||
<br>
|
||||
|
||||
PS: 如果要打包有依赖lib的插件, 请继续向后读<br>
|
||||
|
||||
|
||||
## 下一步
|
||||
|
||||
Java 玩家->[我的第一个插件](https://github.com/mamoe/mirai-console/blob/master/PluginDocs/java/)
|
||||
Kotlin玩家->[我的第一个插件](https://github.com/mamoe/mirai-console/blob/master/PluginDocs/kotlin/)
|
||||
|
||||
|
||||
<i>本章部分章节引用自[搭建环境 - Nukkit插件从0开始](https://www.cnblogs.com/xtypr/p/nukkit_plugin_start_from_0_build_environment.html),</i>
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 7.8 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 9.4 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 9.4 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 4.8 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 154 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 192 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 120 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 239 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 88 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 244 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 462 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 387 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 197 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 72 KiB |
@ -1,2 +0,0 @@
|
||||
这是一个demo, 请将这里当做你的项目根目录
|
||||
|
||||
@ -1,99 +0,0 @@
|
||||
//在这里创建你的PluginBase, 他应该是一个object
|
||||
/**
|
||||
kotlin example
|
||||
|
||||
|
||||
object ExamplePluginMain : PluginBase() {
|
||||
override fun onLoad() {
|
||||
super.onLoad()
|
||||
}
|
||||
|
||||
override fun onEnable() {
|
||||
super.onEnable()
|
||||
|
||||
logger.info("Plugin loaded!")
|
||||
|
||||
subscribeMessages {
|
||||
"greeting" reply { "Hello ${sender.nick}" }
|
||||
}
|
||||
|
||||
subscribeAlways<MessageRecallEvent> { event ->
|
||||
logger.info { "${event.authorId} 的消息被撤回了" }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
|
||||
java example
|
||||
|
||||
|
||||
class ExamplePluginBase extends PluginBase {
|
||||
|
||||
public void onLoad(){
|
||||
bot.getFriends().forEach(friend -> {
|
||||
System.out.println(friend.getId() + ":" + friend.getNick());
|
||||
return Unit.INSTANCE; // kotlin 的所有函数都有返回值. Unit 为最基本的返回值. 请在这里永远返回 Unit
|
||||
});
|
||||
|
||||
Events.subscribeAlways(GroupMessage.class, (GroupMessage event) -> {
|
||||
|
||||
if (event.getMessage().contains("reply")) {
|
||||
// 引用回复
|
||||
final QuoteReplyToSend quote = MessageUtils.quote(event.getMessage(), event.getSender());
|
||||
event.getGroup().sendMessage(quote.plus("引用回复"));
|
||||
|
||||
} else if (event.getMessage().contains("at")) {
|
||||
// at
|
||||
event.getGroup().sendMessage(new At(event.getSender()));
|
||||
|
||||
} else if (event.getMessage().contains("permission")) {
|
||||
// 成员权限
|
||||
event.getGroup().sendMessage(event.getPermission().toString());
|
||||
|
||||
} else if (event.getMessage().contains("mixed")) {
|
||||
// 复合消息, 通过 .plus 连接两个消息
|
||||
event.getGroup().sendMessage(
|
||||
MessageUtils.newImage("{01E9451B-70ED-EAE3-B37C-101F1EEBF5B5}.png") // 演示图片, 可能已过期
|
||||
.plus("Hello") // 文本消息
|
||||
.plus(new At(event.getSender())) // at 群成员
|
||||
.plus(AtAll.INSTANCE) // at 全体成员
|
||||
);
|
||||
|
||||
} else if (event.getMessage().contains("recall1")) {
|
||||
event.getGroup().sendMessage("你看不到这条消息").recall();
|
||||
// 发送消息马上就撤回. 因速度太快, 客户端将看不到这个消息.
|
||||
|
||||
} else if (event.getMessage().contains("recall2")) {
|
||||
final Job job = event.getGroup().sendMessage("3秒后撤回").recallIn(3000);
|
||||
|
||||
// job.cancel(new CancellationException()); // 可取消这个任务
|
||||
|
||||
} else if (event.getMessage().contains("上传图片")) {
|
||||
File file = new File("myImage.jpg");
|
||||
if (file.exists()) {
|
||||
final Image image = event.getGroup().uploadImage(new File("myImage.jpg"));
|
||||
// 上传一个图片并得到 Image 类型的 Message
|
||||
|
||||
final String imageId = image.getImageId(); // 可以拿到 ID
|
||||
final Image fromId = MessageUtils.newImage(imageId); // ID 转换得到 Image
|
||||
|
||||
event.getGroup().sendMessage(image); // 发送图片
|
||||
}
|
||||
|
||||
} else if (event.getMessage().contains("friend")) {
|
||||
final Future<MessageReceipt<? extends Contact>> future = event.getSender().sendMessageAsync("Async send"); // 异步发送
|
||||
try {
|
||||
future.get();
|
||||
} catch (InterruptedException | ExecutionException e) {
|
||||
e.printStackTrace();
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
public void onEnable(){
|
||||
logger.info("Plugin loaded!");
|
||||
}
|
||||
|
||||
}
|
||||
@ -1,6 +0,0 @@
|
||||
name: "Example"
|
||||
author: "你的名字"
|
||||
version: "0.1.0"
|
||||
main: "my_package_name.ExamplePluginBase"
|
||||
info: "My info"
|
||||
depends: []
|
||||
@ -1,3 +0,0 @@
|
||||
Java的插件教程
|
||||
|
||||
你可以下载source.java和MyFirstPluginJava.pdf 一起阅读
|
||||
Binary file not shown.
Binary file not shown.
@ -1,3 +0,0 @@
|
||||
Java的插件教程
|
||||
|
||||
你可以下载source.java和MyFirstPluginJava.pdf 一起阅读
|
||||
@ -1,3 +0,0 @@
|
||||
由于文件较大, 请选择上面的
|
||||
|
||||
pdf/docs/pages一种进行下载观看
|
||||
@ -1,3 +0,0 @@
|
||||
由于文件较大, 请选择上面的
|
||||
|
||||
pdf/docs/pages一种进行下载观看
|
||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
@ -34,35 +34,6 @@
|
||||
[`JavaPluginScheduler`]: src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JavaPluginScheduler.kt
|
||||
[`ResourceContainer`]: src/main/kotlin/net/mamoe/mirai/console/plugin/ResourceContainer.kt
|
||||
|
||||
## 准备工作
|
||||
|
||||
### 开发 mirai-console 插件的准备工作
|
||||
- 需使用 IDE: [IntelliJ IDEA](https://www.jetbrains.com/idea/)
|
||||
- IntelliJ 需装有 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge) 插件 (启动 IntelliJ, 点击 [一键安装](https://plugins.jetbrains.com/embeddable/install/14816))
|
||||
- 安装并配置 JDK 8
|
||||
|
||||
### 前置知识
|
||||
- 你需要掌握 Java 基础.
|
||||
- 你需要了解 Kotlin 基础语法:
|
||||
- [基本类型](https://www.kotlincn.net/docs/reference/basic-types.html)
|
||||
- [类与继承](https://www.kotlincn.net/docs/reference/classes.html)
|
||||
- [属性与字段](https://www.kotlincn.net/docs/reference/properties.html)
|
||||
- [接口](https://www.kotlincn.net/docs/reference/interfaces.html)
|
||||
- [扩展](https://www.kotlincn.net/docs/reference/extensions.html)
|
||||
- [数据类](https://www.kotlincn.net/docs/reference/data-classes.html)
|
||||
- [对象](https://www.kotlincn.net/docs/reference/object-declarations.html)
|
||||
- [密封类](https://www.kotlincn.net/docs/reference/sealed-classes.html)
|
||||
- **[Java 中调用 Kotlin](https://www.kotlincn.net/docs/reference/java-to-kotlin-interop.html)**
|
||||
|
||||
## 包结构
|
||||
- `net.mamoe.mirai.console.`
|
||||
- `command`：指令模块：[`Command`]
|
||||
- `data`：存储模块：[`PluginData`], [`PluginConfig`], [`PluginDataStorage`]
|
||||
- `event`：Console 实现的事件.
|
||||
- `plugin`：插件模块：[`Plugin`], [`PluginLoader`], [`JvmPlugin`]
|
||||
- `util`：工具类：[`Annotations`], [`BotManager`], [`ConsoleInput`], [`JavaPluginScheduler`]
|
||||
- `internal`：内部实现
|
||||
|
||||
|
||||
## 基础
|
||||
|
||||
|
||||
@ -35,7 +35,6 @@ import net.mamoe.mirai.utils.MiraiLogger
|
||||
* 实现为 [ClassLoader.getResourceAsStream]
|
||||
*
|
||||
* ## 实现 [JvmPlugin]
|
||||
* j
|
||||
*
|
||||
* @see AbstractJvmPlugin 默认实现
|
||||
*
|
||||
|
||||
0
docs/Commands.md
Normal file
0
docs/Commands.md
Normal file
0
docs/Extensions.md
Normal file
0
docs/Extensions.md
Normal file
1
docs/FrontEnd.md
Normal file
1
docs/FrontEnd.md
Normal file
@ -0,0 +1 @@
|
||||
#
|
||||
0
docs/PermissionService.md
Normal file
0
docs/PermissionService.md
Normal file
0
docs/Permissions.md
Normal file
0
docs/Permissions.md
Normal file
0
docs/PluginData.md
Normal file
0
docs/PluginData.md
Normal file
0
docs/PluginLoader.md
Normal file
0
docs/PluginLoader.md
Normal file
242
docs/Plugins.md
Normal file
242
docs/Plugins.md
Normal file
@ -0,0 +1,242 @@
|
||||
# Mirai Console Backend - Plugins
|
||||
|
||||
[`Plugin`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/Plugin.kt
|
||||
[`PluginDescription`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/description/PluginDescription.kt
|
||||
[`PluginLoader`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/PluginLoader.kt
|
||||
[`PluginManager`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/PluginManager.kt
|
||||
[`JarPluginLoader`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JarPluginLoader.kt
|
||||
[`JvmPlugin`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JvmPlugin.kt
|
||||
[`JvmPluginDescription`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JvmPluginDescription.kt
|
||||
[`AbstractJvmPlugin`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/AbstractJvmPlugin.kt
|
||||
[`KotlinPlugin`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/KotlinPlugin.kt
|
||||
[`JavaPlugin`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JavaPlugin.kt
|
||||
|
||||
|
||||
[`PluginData`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginData.kt
|
||||
[`PluginConfig`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginConfig.kt
|
||||
[`PluginDataStorage`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginDataStorage.kt
|
||||
|
||||
[`MiraiConsole`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/MiraiConsole.kt
|
||||
[`MiraiConsoleImplementation`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/MiraiConsoleImplementation.kt
|
||||
<!--[MiraiConsoleFrontEnd]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/MiraiConsoleFrontEnd.kt-->
|
||||
|
||||
[`Command`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/Command.kt
|
||||
[`CompositeCommand`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/CompositeCommand.kt
|
||||
[`SimpleCommand`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/SimpleCommand.kt
|
||||
[`RawCommand`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/RawCommand.kt
|
||||
[`CommandManager`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/CommandManager.kt
|
||||
|
||||
[`BotManager`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/BotManager.kt
|
||||
[`Annotations`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/Annotations.kt
|
||||
[`ConsoleInput`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/ConsoleInput.kt
|
||||
[`JavaPluginScheduler`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JavaPluginScheduler.kt
|
||||
[`ResourceContainer`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/ResourceContainer.kt
|
||||
[`PluginFileExtensions`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/PluginFileExtensions.kt
|
||||
[`AutoSavePluginDataHolder`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginDataHolder.kt#L45
|
||||
|
||||
[Kotlin]: https://www.kotlincn.net/
|
||||
[Java]: https://www.java.com/zh_CN/
|
||||
[JVM]: https://zh.wikipedia.org/zh-cn/Java%E8%99%9A%E6%8B%9F%E6%9C%BA
|
||||
[JAR]: https://zh.wikipedia.org/zh-cn/JAR_(%E6%96%87%E4%BB%B6%E6%A0%BC%E5%BC%8F)
|
||||
|
||||
[为什么不支持热加载和卸载插件？]: QA.md#为什么不支持热加载和卸载插件
|
||||
[使用 ServiceLoader 加载插件]: QA.md#使用-serviceloader-加载插件
|
||||
|
||||
Mirai Console 运行在 [JVM]，支持使用 [Kotlin] 或 [Java] 语言编写的插件。
|
||||
|
||||
## 通用的插件接口 - [`Plugin`]
|
||||
|
||||
所有 Console 插件都必须实现 [`Plugin`] 接口。
|
||||
|
||||
> **解释 *插件***：只要实现了 [`Plugin`] 接口的类和对象都可以叫做「Mirai Console 插件」，简称 「插件」。
|
||||
> 为了便捷，内含 [`Plugin`] 实现的一个 [JAR] 文件也可以被称为「插件」。
|
||||
|
||||
基础的 [`Plugin`] 很通用，它只拥有很少的成员：
|
||||
|
||||
```kotlin
|
||||
interface Plugin : CommandOwner { // CommandOwner 是空的 interface
|
||||
val isEnabled: Boolean
|
||||
val loader: PluginLoader<*, *> // 能处理这个 Plugin 的 PluginLoader
|
||||
}
|
||||
```
|
||||
|
||||
[`Plugin`] 接口拥有强扩展性，以支持 Mirai Console 统一管理使用其他编程语言编写的插件 （详见进阶章节 [实现 PluginLoader](PluginLoader.md)）。
|
||||
|
||||
## JVM 平台插件接口 - [`JvmPlugin`]
|
||||
|
||||
所有的 JVM 插件都必须实现 [`JvmPlugin`]（否则不会被 [`JarPluginLoader`] 加载）。
|
||||
Mirai Console 提供一些基础的实现，即 [`AbstractJvmPlugin`]，并将 [`JvmPlugin`] 分为 [`KotlinPlugin`] 和 [`JavaPlugin`]。
|
||||
|
||||
### 主类和描述
|
||||
|
||||
**Kotlin 使用者的插件主类应继承 [`KotlinPlugin`]。**
|
||||
**其他 JVM 语言（如 Java）使用者的插件主类应继承 [`JavaPlugin`]。**
|
||||
|
||||
#### 描述
|
||||
插件描述需要在主类构造器传递给 `super`。因此插件不需要 `plugin.yml`, `plugin.xml` 等配置文件来指示信息。
|
||||
|
||||
Mirai Console 使用 `ServiceLoader` 加载插件。推荐的做法是使用 `AutoService`（如何[使用 ServiceLoader 加载插件]）。
|
||||
|
||||
##### 插件名
|
||||
插件名仅取决于 `PluginDescription` 提供的 `name`，与主类类名等其他信息无关。
|
||||
|
||||
#### 实现 Kotlin 插件主类
|
||||
|
||||
一个 Kotlin 插件的主类通常需:
|
||||
- 继承 [`KotlinPlugin`]
|
||||
- 访问权限为 `public` 或默认 (不指定)
|
||||
|
||||
```kotlin
|
||||
@AutoService(JvmPlugin::class) // 让 Console 知道这个 object 是一个插件主类.
|
||||
object SchedulePlugin : KotlinPlugin(
|
||||
SimpleJvmPluginDescription( // 插件的描述, name 和 version 是必须的
|
||||
name = "Schedule",
|
||||
version = "1.0.0",
|
||||
// author, description, ...
|
||||
)
|
||||
) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### 实现 Java 插件
|
||||
|
||||
一个 Java 插件的主类通常需:
|
||||
- 继承 [`JavaPlugin`]
|
||||
- 访问权限为 `public`
|
||||
|
||||
(推荐) 静态初始化:
|
||||
```java
|
||||
@AutoService(JvmPlugin.class)
|
||||
public final class JExample extends JavaPlugin {
|
||||
public static final JExample INSTANCE = new JExample(); // 可以像 Kotlin 一样静态初始化单例
|
||||
private JExample() {
|
||||
super(new SimpleJvmPluginDescription(
|
||||
"JExample", // name
|
||||
"1.0.0" // version
|
||||
));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
由 Console 初始化（仅在某些静态初始化不可用的情况下使用）:
|
||||
```java
|
||||
@AutoService(JvmPlugin.class)
|
||||
public final class JExample extends JavaPlugin {
|
||||
private static final JExample instance;
|
||||
public static JExample getInstance() {
|
||||
return instance;
|
||||
}
|
||||
public JExample() { // 此时必须 public
|
||||
super(new SimpleJvmPluginDescription(
|
||||
"JExample", // name
|
||||
"1.0.0" // version
|
||||
));
|
||||
instance = this;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 依赖管理
|
||||
|
||||
一个插件被允许依赖于另一个插件。可在 `SimpleJvmPluginDescription` 构造时提供信息。
|
||||
|
||||
若插件拥有依赖，则会首先加载其依赖。但任何一个插件的 `onEnable()` 都会在所有插件的 `onLoad()` 都调用成功后再调用。
|
||||
|
||||
多个插件的加载是*顺序的*，意味着若一个插件的 `onLoad()` 等回调处理缓慢，后续插件的加载也会被延后，即使它们可能没有依赖关系。
|
||||
因此请尽量让 `onLoad()`，`onEnable()`，`onDisable()`快速返回。
|
||||
|
||||
### 插件生命周期
|
||||
|
||||
Mirai Console 不提供热加载和热卸载功能，所有插件只能在服务器启动前加载，在服务器结束时卸载。（[为什么不支持热加载和卸载插件？]）
|
||||
|
||||
插件仅可以通过如下三个回调知晓自身的加载情况。
|
||||
|
||||
较小概率情况：
|
||||
- 如果 `onLoad()` 被调用，`onEnable()` 不一定会调用。因为可能在调用后续插件的 `onLoad()` 或 `onEnable()` 时可能会出错而导致服务器被关闭。
|
||||
- 如果 `onLoad()` 或 `onEnable()` 调用时抛出异常，`onDisable()` 不会被调用。（注意：这是仍处于争议状态的行为，后续可能有修改）
|
||||
- 如果 `onEnable()` 被成功调用，`onDisable()` 一定会调用，无论其他插件是否发生错误。
|
||||
|
||||
#### 加载
|
||||
|
||||
[`JarPluginLoader`] 调用插件的 `onLoad()`，在 `onLoad()` 正常返回后插件被认为成功加载。
|
||||
|
||||
由于 `onLoad()` 只会被初始化一次，插件可以在该方法内进行一些*一次性*的*初始化*任务。
|
||||
|
||||
**在 `onLoad()` 时插件并未处于启用状态，此时插件不能进行监听事件，加载配置等操作。**
|
||||
|
||||
若在 Kotlin 使用 `object`，或在 Java 使用静态初始化方式定义插件主类, `onLoad()` 与 `init` 代码块作用几乎相同。
|
||||
|
||||
#### 启用
|
||||
|
||||
[`JarPluginLoader`] 调用插件的 `onEnable()`，意为启用一个插件。
|
||||
|
||||
此时插件可以启动所有协程，事件监听，和其他任务。**但这些任务都应该拥有生命周期管理，详见 [任务生命周期管理](#任务生命周期管理)。**
|
||||
|
||||
#### 禁用
|
||||
|
||||
[`JarPluginLoader`] 调用插件的 `onDisable()`，意为禁用一个插件。
|
||||
|
||||
插件的任何类和对象都不会被卸载。「禁用」仅表示停止关闭所有正在进行的任务，保存所有数据，停止处理将来的数据。
|
||||
|
||||
插件应正确实现「禁用」，以为用户提供完全的控制可能。
|
||||
|
||||
### 任务生命周期管理
|
||||
|
||||
#### 协程管理
|
||||
|
||||
[`JvmPlugin`] 实现 `CoroutineScope`，并由 Console 内部实现提供其 `coroutineContext`。
|
||||
|
||||
`JvmPlugin.coroutineContext` 包含元素 `CoroutineName`, `SupervisorJob`, `CoroutineExceptionHandler`。
|
||||
**所有插件启动的协程都应该受 `JvmPlugin` 作用域的管理**
|
||||
|
||||
如要启动一个协程，正确的做法是：
|
||||
```kotlin
|
||||
// object MyPluginMain : KotlinPlugin()
|
||||
|
||||
MyPluginMain.launch {
|
||||
// job
|
||||
}
|
||||
```
|
||||
|
||||
#### Java 线程管理
|
||||
|
||||
*TODO*：Mirai Console 暂未支持自动的线程管理。请手动在 `onDisable()` 时关闭启动的线程。
|
||||
|
||||
### 访问数据目录和配置目录
|
||||
|
||||
[`JvmPlugin`] 实现接口 [`PluginFileExtensions`]。插件可通过 `resolveDataFile`，`resolveConfigFile` 等方法取得数据目录或配置目录下的文件。
|
||||
|
||||
可以在任何时刻使用这些方法。
|
||||
|
||||
详见 [`PluginFileExtensions`]。
|
||||
|
||||
#### 物理目录路径
|
||||
用 `$root` 表示 Mirai Console 运行路径，`$name` 表示插件名
|
||||
插件数据目录一般在 `$root/plugins/`，
|
||||
|
||||
### 访问 [JAR] 包内资源文件
|
||||
|
||||
[`JvmPlugin`] 实现接口 [`ResourceContainer`]。插件可通过 `getResource`，`getResourceAsStream` 等取得 [JAR] 包内资源文件。
|
||||
|
||||
可以在任何时刻使用这些方法。
|
||||
|
||||
详见 [`ResourceContainer`]。
|
||||
|
||||
### 读取 [`PluginData`] 或 [`PluginConfig`]
|
||||
|
||||
> 本节基于章节 [PluginData](PluginData.md) 的内容。
|
||||
> 在阅读本节前建议先阅读上述基础章节。
|
||||
|
||||
[`JvmPlugin`] 实现接口 [`AutoSavePluginDataHolder`]，提供:
|
||||
|
||||
Kotlin：
|
||||
- `public fun <T : PluginData> T.reload()`
|
||||
- `public fun <T : PluginConfig> T.reload()`
|
||||
|
||||
Java：
|
||||
- `public fun reloadPluginData(PluginData)`
|
||||
- `public fun reloadPluginData(PluginConfig)`
|
||||
|
||||
**仅可在插件 onEnable() 时及其之后才能使用这些方法。**
|
||||
**在插件 onDisable() 之后不能使用这些方法。**
|
||||
36
docs/QA.md
Normal file
36
docs/QA.md
Normal file
@ -0,0 +1,36 @@
|
||||
# Q&A
|
||||
|
||||
## 插件
|
||||
|
||||
|
||||
### 使用 ServiceLoader 加载插件
|
||||
|
||||
- 方法 A. (推荐) 自动创建 service 文件 (使用 Google auto-service)
|
||||
在 `build.gradle.kts` 添加:
|
||||
```kotlin
|
||||
plugins {
|
||||
kotlin("kapt")
|
||||
}
|
||||
dependencies {
|
||||
val autoService = "1.0-rc7"
|
||||
kapt("com.google.auto.service", "auto-service", autoService)
|
||||
compileOnly("com.google.auto.service", "auto-service-annotations", autoService)
|
||||
}
|
||||
```
|
||||
*对于 `build.gradle` 用户, 请自行按照 Groovy DSL 语法翻译*
|
||||
|
||||
- 方法 B. 手动创建 service 文件
|
||||
在 `jar` 内 `META-INF/services/net.mamoe.mirai.console.plugin.jvm.JvmPlugin` 文件内存放插件主类全名.
|
||||
|
||||
|
||||
**注意**:
|
||||
- 插件自身的版本要求遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/) 规范, 合格的版本例如: `1.0.0`, `1.0`, `1.0-M1`, `1.0-pre-1`
|
||||
- 插件依赖的版本遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/) 规范, 同时支持 [Apache Ivy 风格表示方法](http://ant.apache.org/ivy/history/latest-milestone/settings/version-matchers.html).
|
||||
|
||||
|
||||
### 为什么不支持热加载和卸载插件？
|
||||
|
||||
在热加载过程容易产生冲突情况；
|
||||
卸载时不容易完全卸载所有静态对象。
|
||||
|
||||
为了避免这些麻烦，Mirai Console 认为没有支持热加载和热卸载的必要。
|
||||
66
docs/README.md
Normal file
66
docs/README.md
Normal file
@ -0,0 +1,66 @@
|
||||
# MiraiConsole
|
||||
|
||||
欢迎来到 mirai-console 开发文档!
|
||||
|
||||
## 准备工作
|
||||
|
||||
### 开发 mirai-console 插件的准备工作
|
||||
- 需使用 IDE: [IntelliJ IDEA](https://www.jetbrains.com/idea/)
|
||||
- IntelliJ 需装有 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge) 插件 (启动 IntelliJ, 点击 [一键安装](https://plugins.jetbrains.com/embeddable/install/14816))
|
||||
- 安装并配置 JDK 8
|
||||
|
||||
### 前置知识
|
||||
要学习为 mirai-console 开发原生支持的插件, 需要:
|
||||
|
||||
- 掌握 Java 基础.
|
||||
- 了解 Kotlin 基础语法:
|
||||
- [基本类型](https://www.kotlincn.net/docs/reference/basic-types.html)
|
||||
- [类与继承](https://www.kotlincn.net/docs/reference/classes.html)
|
||||
- [属性与字段](https://www.kotlincn.net/docs/reference/properties.html)
|
||||
- [接口](https://www.kotlincn.net/docs/reference/interfaces.html)
|
||||
- [扩展](https://www.kotlincn.net/docs/reference/extensions.html)
|
||||
- [数据类](https://www.kotlincn.net/docs/reference/data-classes.html)
|
||||
- [对象](https://www.kotlincn.net/docs/reference/object-declarations.html)
|
||||
- [密封类](https://www.kotlincn.net/docs/reference/sealed-classes.html)
|
||||
- **[Java 中调用 Kotlin](https://www.kotlincn.net/docs/reference/java-to-kotlin-interop.html)**
|
||||
- 至少能使用 Java 或 Kotlin 一种一门语言解决问题
|
||||
- 了解 JVM 和 Java 等同类编程语言的关系
|
||||
|
||||
## 目录
|
||||
|
||||
### 后端插件开发基础
|
||||
|
||||
- 包结构
|
||||
`net.mamoe.mirai.console.`
|
||||
- `command`：指令模块：[`Command`]
|
||||
- `data`：存储模块：[`PluginData`], [`PluginConfig`], [`PluginDataStorage`]
|
||||
- `event`：Console 实现的事件.
|
||||
- `plugin`：插件模块：[`Plugin`], [`PluginLoader`], [`JvmPlugin`]
|
||||
- `util`：工具类：[`Annotations`], [`BotManager`], [`ConsoleInput`], [`JavaPluginScheduler`]
|
||||
- `internal`：内部实现
|
||||
|
||||
- 插件 - [Plugin 模块](Plugins.md)
|
||||
- 指令 - [Command 模块](Commands.md)
|
||||
- 存储 - [PluginData 模块](PluginData.md)
|
||||
- 权限 - [Permission 模块](Permissions.md)
|
||||
|
||||
### 后端插件开发进阶
|
||||
|
||||
- 扩展 - [Extension 模块和扩展点](Extensions.md)
|
||||
- 扩展 - [实现 PluginLoader](PluginLoader.md)
|
||||
- 扩展 - [实现 PermissionService](PermissionService.md)
|
||||
|
||||
### 实现前端
|
||||
- [FrontEnd](FrontEnd.md)
|
||||
|
||||
[`Plugin`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/Plugin.kt
|
||||
[`Annotations`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/Annotations.kt
|
||||
[`PluginData`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginData.kt
|
||||
[`JavaPluginScheduler`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JavaPluginScheduler.kt
|
||||
[`JvmPlugin`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JvmPlugin.kt
|
||||
[`PluginConfig`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginConfig.kt
|
||||
[`PluginLoader`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/PluginLoader.kt
|
||||
[`ConsoleInput`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/ConsoleInput.kt
|
||||
[`PluginDataStorage`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginDataStorage.kt
|
||||
[`BotManager`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/BotManager.kt
|
||||
[`Command`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/Command.kt
|
||||
Loading…
Reference in New Issue
Block a user