diff --git a/README.md b/README.md index f787f54..a21d670 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - 中文 -- [English](https://github.com/Mooling0602/MatrixSync-MCDR/blob/2.3.0/README_en_us.md) +- [English](https://github.com/Mooling0602/MatrixSync-MCDR/blob/dev/README_en_us.md) # MatrixSync-MCDR 一个MCDR(全称[MCDReforged](https://mcdreforged.com/))插件,用于同步Matrix群组和《我的世界》服务器的线上游戏之间的消息。 @@ -8,12 +8,18 @@ 开发过程中用到的pypi项目:[matrix-nio](https://pypi.org/project/matrix-nio/)。 -当前分支版本:主分支@2.3.2 +当前分支版本:开发中@2.4.0 ## 用法 从release下载最新版本,在MCDReforged的启动环境中安装好需要的Python依赖,然后扔到plugins文件夹里面即可。 -### 使用 Git +在使用此插件之前,你必须知道什么是[Matrix](https://matrix.org/),然后准备一个账号作为matrix机器人用于消息同步,并认真阅读下面的内容以进行插件配置。 + +配置完毕并启用插件后,若有测试消息成功发送到matrix群组,则表示消息同步开始工作。 + +若消息同步的过程中有任意方向的消息转发出现问题,也请按配置文件部分的内容检查配置是否正确。 + +### 使用 Git 从源码打包插件 > This part doesn't support English yet, please use translate tools at present. > > 依赖软件包`zip` @@ -24,13 +30,7 @@ > > 懒人用命令:`git clone https://mirror.ghproxy.com/https://github.com/Mooling0602/MatrixSync-MCDR.git && cd MatrixSync-MCDR && chmod +x pack_plugin.sh && ./pack_plugin.sh` > -> 正常情况下,请不要修改脚本内容及所用配置(config.ini) - -在使用此插件之前,你必须知道什么是[Matrix](https://matrix.org/),然后准备一个账号作为matrix机器人用于消息同步,并认真阅读下面的内容以进行插件配置。 - -配置完毕并启用插件后,若有测试消息成功发送到matrix群组,则表示消息同步开始工作。 - -若消息同步的过程中有任意方向的消息转发出现问题,也请按下面的内容检查配置是否正确。 +> 打包脚本所用配置(config.ini)中的ci部分为主插件和配套子包的构建开关,设置为1即可打开,脚本运行后将生成打包好的插件,其中子包的构建在`subpack(rolling)/[MSync]*/内(如果开发完成),主插件的构建在主目录。 ### 配置文件 #### config.json @@ -39,121 +39,59 @@ | - | - | | **homeserver** | 机器人账号登录所使用的根服务器 | | **user_id** | 机器人的账号ID,格式为@<用户名>:<根服务器>,如@mcchatbot:example.com | -| **password** | 机器人账号的密码,一般仅在初次登录使用 | -| **room_id** | 需要接收游戏消息的房间的ID,目前只能设置一个 | -| **room_name** | 需要转发消息到游戏内的房间的显示名称(必须准确无误,若发生更新也需要同步修改,否则你将看不到任何消息),目前只能设置一个 | +| **password** | 机器人账号的密码,仅在初次登录使用 | +| **room_id** | 需要接收游戏消息的房间的ID | +| **room_name** | 需要转发消息到游戏内的房间的显示名称(必须准确无误,若发生更新也需要同步修改,否则你将看不到任何消息) | | **device_id** | 登录用的设备名,一般无需修改,可自定义 | +> 目前只支持单账号和单聊天房间(相当于QQ群),计划在v3版本以后开放多配置接口支持。 + #### settings.json | 配置项 | 配置内容 | | - | - | | plugin-enabled | 插件是否启用,请确保配置文件和所需设置修改无误后再开启 | | allow_all_rooms_msg | 是否允许来自所有房间的消息,若开启,则来自机器人账号所加入的房间的消息都会被转发到游戏中,并注明房间的显示名称,否则只转发已设置的房间的消息 | -| sync_old_msg | 是否同步旧的消息,默认开启,可在插件配置目录下的token.json文件中增加有效的`next_batch`项后关闭 | +| sync_old_msg | 是否同步旧的消息,默认关闭,开启以在插件启动同步时加载历史消息 | ## 接口(API) -插件提供了一个协程函数`sendMsg()`供其他开发者调用以实现向Matrix群组发送自定义内容,其回调参数为`message`,下面是代码参考: -```python -import asyncio -import ... - -from mcdreforged.api.all import * -from matrix_sync.reporter import sendMsg -from ... import ... - -def main(): - pass - asyncio.run(sendMsg(message)) -``` -如果要在协程内调用该接口: -```python -import asyncio -import ... - -from mcdreforged.api.all import * -from matrix_sync.reporter import sendMsg -from ... import ... - -async def main(): - pass - await sendMsg(message) -``` -将主插件(MatrixSync)添加到MCDR依赖中,并将其Python依赖一并添加到自己的插件中,然后在开发过程中把`message`替换成你想要发送的自定义内容即可。 +2.3.0以前的旧接口仍然有效,请到[docs](https://github.com/Mooling0602/MatrixSync-MCDR/blob/dev/docs.md)查看。 -请注意,该接口的支持是实验性的,若要调用此接口,请确保用户安装并配置好了主插件(MatrixSync)。 +> 2.3.x修改的接口将不再受到任何支持,原因为相关函数名和分发的插件事件中提供的参数发生冲突。 -2.2.0版本以后,机器人的初始化将直接在加载插件时进行,所以如果需要判断主插件的消息上报器是否能够正常工作,可以在调用函数前导入相关的全局变量并加入判断条件,下面是示例代码: -```python -import asyncio -import matrix_sync.client -import ... - -from mcdreforged.api.all import * -from matrix_sync.reporter import sendMsg - -def main(): - pass - clientStatus = matrix_sync.client.clientStatus - if clientStatus: - asyncio.run(sendMsg(message)) - else: - # 可以在此自定义报错的内容,也可以直接删除此部分忽略该接口 - server.logger.info("error") -``` -协程函数示例: -```python -import asyncio -import matrix_sync.client -import ... - -from mcdreforged.api.all import * -from matrix_sync.reporter import sendMsg - -async def main(): - pass - clientStatus = matrix_sync.client.clientStatus - if clientStatus: - await sendMsg(message) - else: - # 可以在此自定义报错的内容,也可以直接删除此部分忽略该接口 - server.logger.info("error") -``` - -由于2.3.0版本新增了Matrix房间消息的分发事件,且2.3.1版本重构了这部分接口,所以该部分内容已过时。 - -这些过时的内容仍然持续有效,但其做法不再推荐,请等待后续更详细的文档更新。 - -重构后接口的简单用法: +2.4.0版本重构后的新接口的简单用法: ```python import matrix_sync.client +from matrix_sync.reporter import send_matrix def main(): + message = "你要发送的消息" clientStatus = matrix_sync.client.clientStatus if clientStatus: - sender(message) + send_matrix(message) -# 消息将在独立线程中被发送到Matrix,不再可能会阻塞MCDR主线程 +# 消息将在独立线程MatrixReporter中被发送到Matrix,不再可能会阻塞MCDR主线程 ``` ## 热重载(reload)及消息互通控制 -插件默认在游戏服务端启动完成时才会自动启动房间消息接收进程,重新加载插件后,消息接收器并不会自动启动。 +插件默认在游戏服务端启动完成时自动启动房间消息接收进程,在游戏服务端关闭后自动关闭房间消息接收进程。 -要手动启动房间消息接收进程,请执行MCDR命令`!!msync start`,游戏内和控制台上都可以使用。 +要手动启动房间消息接收器(例如重载插件后的场景),请执行MCDR命令`!!msync start`,游戏内和控制台上都可以使用。 -要关闭房间消息接收进程,可以在控制台使用`!!msync stop`,直到下次服务器启动完成前消息接收器都必须手动重启。 +要提前关闭房间消息接收器,可以在控制台使用`!!msync stop`,直到下次服务器启动完成前消息接收器都必须手动使用`!!msync start`重新启动。 -要在详细阅读后关闭2.3.1版本新增的大量提示,可以使用`!!msync closetip`,目前想重新查看提示,只能在源码中查看语言文件,或自行修改token.json - -插件会自动在解析到游戏内的消息时尝试转发到配置好的Matrix房间内,暂时无法禁用。 +插件会自动在解析到游戏内的消息时尝试转发到配置好的Matrix房间内,暂时无法禁用,将于v2.4.0以后版本(v2.4.x)中通过和房间消息接收器同步开闭状态的方式解决。 该指令没有权限要求,但设置了进程锁(安全机制),重复执行会警告提示,不会影响插件功能的正常运行。 -请注意,该功能是实验性的,若发现任何错误请及时通过GitHub Issue向插件作者反馈! +请注意,该功能仍然是不稳定的,若发现任何错误请及时通过GitHub Issue向插件作者反馈。另外,重载插件前尽量先关闭房间消息接收器,否则可能无法清楚残留进程,导致只能重启整个MCDR解决! + +建议在运行环境稳定时,尽量不使用热重载。 ## 注意 -- 首次加载插件的时候,插件将自动初始化配置并卸载自己。你需要正确修改默认的配置文件,并在settings.json中启用plugin_enabled配置项以启用插件,然后重启服务器或着重载插件以正常使用。 +### 关于首次使用 +首次加载插件的时候,插件将自动初始化配置并卸载自己。你需要正确修改默认的配置文件,并在settings.json中启用plugin_enabled配置项以启用插件,然后重启服务器或着重载插件以正常使用。若选择后一个方案,在插件重载后如果服务器已启动完毕,你可以使用`!!msync start`启动房间消息接收器,使Matrix的消息转发到游戏内。另外,只要插件成功加载没有出现问题,游戏内的消息将始终自动转发到Matrix的房间,将在v2.4.0以上版本中改为和房间消息接收器同步。 - 不打算支持加密信息(EE2E),有需要可以二次开发修改插件,欢迎PR。 -- 多语言目前只支持中文(简体)和英语(用谷歌和ChatGPT从中文翻译),任何人都可以联系我帮助完善翻译,欢迎PR到/lang语言文件中。 +- 多语言目前只支持中文(简体)和英语(用谷歌和ChatGPT从中文翻译),任何人都可以联系我帮助完善翻译,欢迎PR到/lang语言文件和README中。 diff --git a/README_en_us.md b/README_en_us.md index b58f43f..1c8f590 100644 --- a/README_en_us.md +++ b/README_en_us.md @@ -1,4 +1,4 @@ -- [中文](https://github.com/Mooling0602/MatrixSync-MCDR/blob/2.3.0/README.md) +- [中文](https://github.com/Mooling0602/MatrixSync-MCDR/blob/dev/README.md) - English # MatrixSync-MCDR @@ -10,7 +10,7 @@ The following project is used in the development process: [matrix-nio](https://p Thanks for ChatGPT and Google Translate's help to translate the content from Chinese, if anything wrong, please issue to feedback or PR to `/lang`. -Present branch version: released@2.3.2 +Present branch version: dev@2.4.0 ## Usage Download the latest version from the release, install the necessary Python dependencies in the MCDReforged startup environment, and then throw it into the plugins folder. @@ -29,61 +29,39 @@ If there is any issue with message forwarding in any direction during the messag | **homeserver** | The home server used to log in to the bot account | | **user_id** | The bot account ID, formatted as @username:example.com | | **password** | The password of the bot account, generally only used for the initial login | -| **room_id** | The ID of the room to receive game messages, currently only one can be set | -| **room_name** | The display name of the room to forward messages to the game (must be accurate, if updated, it also needs to be modified synchronously, otherwise you will not see any messages), currently only one can be set | +| **room_id** | The ID of the room to receive game messages | +| **room_name** | The display name of the room to forward messages to the game (must be accurate, if updated, it also needs to be modified synchronously, otherwise you will not see any messages) | | **device_id** | The device name used for login, generally no need to modify, can be customized | +Multi-config is not supported, will add API support for developers from v3. #### settings.json | Configuration Item | Content | | - | - | | plugin-enabled | Whether the plugin is enabled, please ensure the configuration file and necessary settings are modified correctly before enabling | | allow_all_rooms_msg | Whether to allow messages from all rooms, if enabled, messages from rooms joined by the bot account will be forwarded to the game, with the room display name specified, otherwise only messages from the configured room will be forwarded | -| sync_old_msg | Whether to sync old messages, enabled on default, can turn it off after vaild `next_batch` appeared in token.json in config path of the plugin | +| sync_old_msg | Whether to sync old messages, enabled on default, disable to see old messages when plugin is just loaded | ## Interface (API) -The plugin provides a coroutine function `sendMsg()` for other developers to call to send custom content to the Matrix group. Its callback parameter is `message`. Here is the code reference: -```python -import asyncio -import matrix_sync.client -import ... - -from mcdreforged.api.all import * -from matrix_sync.reporter import sendMsg -from ... import ... - -def main(): - pass - clientStatus = matrix_sync.client.clientStatus - if clientStatus: - asyncio.run(sendMsg(message)) - -# async def main(): -# pass -# clientStatus = matrix_sync.client.clientStatus -# if clientStatus: -# await sendMsg(message) -``` -Add the main plugin (MatrixSync) to the dependencies of MCDR, and include its Python dependencies in your plugin as well. Then, during development, replace `message` with the custom content you want to send. - -Please note that support for this interface is experimental, and it cannot be guaranteed that the message forwarding functionality of the main plugin (MatrixSync) will work when calling this interface (there may be situations where the bot is not properly configured, or existing login information and tokens cannot be used). If you want to call this interface, please ensure that the user has installed and configured the main plugin (MatrixSync). - -Outdated after version 2.3.1, please wait new document finished. +See "接口(API)" [中文](https://github.com/Mooling0602/MatrixSync-MCDR/blob/dev/README.md) README. ## Hot Reload (reload) & message sync control +By default, the plugin automatically starts the room message reception process when the game server starts and automatically stops the process when the game server shuts down. -By default, the plugin will only start the room message receive process after the game server has finished starting up. After reloading the plugin, the MatrixReceiver sub thread will not start automatically. +To manually start the room message receiver (e.g., after reloading the plugin), execute the MCDR command !!msync start, which can be used both in-game and in the console. -To manually start the room message receive process, execute the MCDR command `!!msync start`, which can be used both in-game and in the console. +To stop the room message receiver in advance, you can use !!msync stop in the console. The message receiver must be manually restarted with !!msync start before the next server startup. -To stop the room message receive process, execute the command `!!msync stop`, which can be only used in the console and need manually restart until next time the server startup. +The plugin will automatically attempt to forward in-game messages to the configured Matrix room when parsing them. This feature cannot be disabled at the moment but will be resolved in version 2.4.0 (v2.4.x) by syncing the open/close status with the room message receiver. -Plugin will send game messages to the matrix room configured after parsed them, you can't disable this at present. +This command has no permission requirements but is protected by a process lock (security mechanism). Repeated execution will trigger a warning but will not affect the normal operation of the plugin. -This command does not require any permissions, but it sets up a process lock (a safety mechanism). Repeated execution will trigger a warning prompt, but it will not affect the normal operation of the plugin. +Please note that this feature is still unstable. If any errors occur, please report them promptly via GitHub Issues to the plugin author. Additionally, before reloading the plugin, it's recommended to close the room message receiver, as failing to do so may leave residual processes that could only be cleared by restarting the entire MCDR. -Please note that this feature is experimental. If you encounter any errors, please provide feedback to the plugin author through GitHub Issues! +It is advisable not to use hot reload in a stable environment. -## Notes -- When the plugin is first loaded, it will automatically initialize the configuration and then unload itself. You need to correctly modify the default configuration file and enable the `plugin_enabled` configuration item in `settings.json` to enable the plugin. After that, restart the server or reload the plugin to use it normally. -- End-to-end encryption (EE2E) is not supported. If needed, you can customize and modify the plugin yourself, or submit a pull request (PR) with your changes. +## Note +### First-time Use +When loading the plugin for the first time, the plugin will automatically initialize the configuration and then unload itself. You need to correctly modify the default configuration file and enable the plugin_enabled option in settings.json to activate the plugin. Then, restart the server or reload the plugin for proper use. If you choose the latter, after reloading the plugin, if the server has finished starting, you can use !!msync start to start the room message receiver, enabling Matrix message forwarding to the game. Furthermore, as long as the plugin is successfully loaded without issues, in-game messages will always be automatically forwarded to the Matrix room. This will be synchronized with the room message receiver in versions above 2.4.0. + +- The plugin does not support encrypted messages (EE2E). If needed, you can modify the plugin for secondary development, and PRs are welcome. \ No newline at end of file diff --git a/config.ini b/config.ini index 451c7b2..8411b32 100644 --- a/config.ini +++ b/config.ini @@ -8,4 +8,4 @@ ver=2.4.0 test=1 [ci] plugin=0 -subpack=1 \ No newline at end of file +subpack=0 \ No newline at end of file diff --git a/docs.md b/docs.md index 13cfd4f..87832af 100644 --- a/docs.md +++ b/docs.md @@ -9,16 +9,16 @@ ## 接口(API) 这里介绍插件提供的内部接口。 -### 新版接口(v2.3.2) -2.3版本以后,插件开始重构已有的消息上报器(MC -> Matrix)接口,至2.3.2完善。 +### 新版接口(v2.4.0) +2.4.0版本以后,插件完善了已有的消息上报器(MC -> Matrix)接口。 简单用法: ```python import ... -from matrix_sync.reporter import sender +from matrix_sync.reporter import send_matrix def main(): - sender(message) + send_matrix(message) ``` 目前仍无法获取发送结果,但如果主插件在加载时没有成功初始化客户端,你可以通过以下方式获取到相关报错: ```python @@ -26,11 +26,33 @@ import ... from matrix_sync.reporter import sender def main(): - response = sender(message) + response = send_matrix(message) if response is not None: print(response) ``` > 在MCDR中,常用`server.logger.info`或`psi.logger.info`代替`print`,以进行更标准化的日志格式输出。 -### 旧版接口(v2.3-) -旧版接口含有较大缺陷,且已不具备实用的应用场景,但仍然可用,后续有空再补充。 +### 旧版接口(v2.2-) +旧版接口含有较大缺陷(会阻塞MCDR主线程,消息发不出去等故障情况将导致MCDR卡死),且已不具备实用的应用场景,但仍然可用。 +```python +import ... +import asyncio +from matrix_sync.reporter import sendMsg + +def main(): + message = "你要发送的消息" + asyncio.run(sendMsg(message)) + +# 或者使用协程,如果你的插件会用到的话 +async def async_main(): + message = "你要发送的消息" + await sendMsg(message) +``` +如果你的插件会使用独立的线程运行相关任务,则旧版接口仍然稳定有效。 + +### 废弃接口(v2.3.x) +即新版接口中这一部分:`from matrix_sync.reporter import send_matrix`,v2.3.x时曾为`sender()`,后发现和派发的Matrix消息事件中的`sender`(Matrix消息发送者)冲突,因此无法兼容,故废弃。 + +任何情况下,都不要再尝试使用这个接口! + +另外,建议停止使用v2.3.x版本。 \ No newline at end of file diff --git a/docs_en_US.md b/docs_en_US.md index 8550856..bd5aa24 100644 --- a/docs_en_US.md +++ b/docs_en_US.md @@ -1 +1 @@ -to do. +to do. You can help translate it!