Merge pull request #26 from Mooling0602/dev

dev -> main

Author: Mooling0602

README.md

@@ -5,16 +5,20 @@
 # MatrixSync-MCDR
 一个MCDR（全称[MCDReforged](https://mcdreforged.com/)）插件，用于同步Matrix群组和《我的世界》服务器的线上游戏之间的消息。
 
+> 注意：不再支持`mcdreforged<2.14`
+
 关于[Matrix](https://matrix.org/): 一个开放的去中心化通讯协议，用于聊天软件。
 
 开发过程中用到的pypi项目：[matrix-nio](https://pypi.org/project/matrix-nio/)。
 
+版本进度：`v2.5.0`
+
 ## 用法
 从release下载最新版本，在MCDReforged的启动环境中安装好需要的Python依赖，然后扔到plugins文件夹里面即可。
 
 在使用此插件之前，你必须知道什么是[Matrix](https://matrix.org/)，然后准备一个账号作为matrix机器人用于消息同步，并认真阅读下面的内容以进行插件配置。
 
-配置完毕并启用插件后，若有测试消息成功发送到matrix群组，则表示消息同步开始工作。
+配置完毕并加载插件后，若有测试消息成功发送到matrix群组，则表示消息同步开始工作。
 
 若消息同步的过程中有任意方向的消息转发出现问题，也请按配置文件部分的内容检查配置是否正确。
 
@@ -31,46 +35,42 @@
 
 > 只支持单账号和单聊天房间（相当于QQ群），计划在v3版本以后开发多配置管理。
 > 
-> v2 LTS 即将推出，如果你不需要多账号、多房间管理，可以持续使用v2版本。
+> v2 LTS 开发中，如果你不需要多账号、多房间管理，可以持续使用v2版本。
 > 
-> v2 LTS 推送将于v2.5.x进行，届时会对当前的配置文件格式进行修改，可能和之前完全不兼容，请注意。
+> v2 LTS 推送正在进行，配置文件格式已大幅度修改，可能和之前完全不兼容，建议备份后删除旧配置并按照新的配置格式重新设置插件。
 
 #### settings.json
 
 | 配置项 | 配置内容 |
 | - | - |
-| plugin-enabled | 插件是否启用，请确保配置文件和所需设置修改无误后再开启 |
-| allow_all_rooms_msg | 是否允许来自所有房间的消息，若开启，则来自机器人账号所加入的房间的消息都会被转发到游戏中，并注明房间的显示名称，否则只转发已设置的房间的消息 |
-| sync_old_msg | 是否同步旧的消息，默认关闭，开启以在插件启动同步时加载历史消息 |
+| `listen.all_rooms` | 是否接收来自机器人加入的所有房间的消息，默认全部接收 |
+| `listen.old_messages` | 是否在启动接收器时加载历史消息，默认不加载 |
+| `message_format.single_room` | 只接收当前配置的房间的消息时，消息的显示格式 |
+| `message_format.all_room` | 接收机器人加入的所有房间的消息时，消息的显示格式 |
+| `log_style.mcdr` | 是否使用MCDR的日志样式，默认为否（使用插件自己的日志样式） |
+| `log_style.debug` | 是否显示调试日志，默认为否 |
+| `ver` | 配置文件版本，请不要进行修改 |
 
 ## 接口（API）
-2.3.0以前的旧接口仍然有效，请到[docs](https://github.com/Mooling0602/MatrixSync-MCDR/blob/dev/docs.md)查看。
-
-> 2.3.x修改的接口将不再受到任何支持，原因为相关函数名和分发的插件事件中提供的参数发生冲突。
-
-2.4.0版本重构后的新接口的简单用法：
-```python
-import matrix_sync.client
-from matrix_sync.reporter import send_matrix
+请前往[docs](https://github.com/Mooling0602/MatrixSync-MCDR/blob/dev/docs.md)查看。
 
-def main():
-    message = "你要发送的消息"
-    send_matrix(message)
-
-# 消息将在独立线程MatrixReporter中被发送到Matrix，不再可能会阻塞MCDR主线程
-# 如果消息没有发送到Matrix，启用MCDR配置中的`debug.plugin`，会显示详情
-```
+v2.5.0进行了一次彻底的代码重构，并且此版本开始进行长期支持，此前的所有API全部失效，并且此前的配置文件不再受支持。
 
 ## 热重载（reload）及消息互通控制
-始终建议在运行环境稳定时，尽量不使用热重载。
+始终建议在运行环境稳定时，尽量不使用热重载，减少出错概率
+
+插件加载时会自动启动消息接收器（转发Matrix消息到MCDR控制台，被动），游戏内的玩家聊天也会自动转发到Matrix（主动），目前前者可以手动进行开关。
 
-现在Matrix消息的收发已经实现同步，使用`!!msync`查看帮助。
+插件卸载时或停止消息接收器时，会自动关闭消息接收器，并关闭运行中的异步客户端。
 
-服务器启动完成后，插件会自动启动Minecraft游戏服务器和Matrix之间的消息互通，暂时不能对消息的收发方向进行配置。（将于2.5.x继续改善）
+若出现插件卸载后仍有残留线程运行的情况，请反馈到Issues页面。遇到这种情况，你只能完全退出甚至强制退出MCDR。
+> 目前这个问题基本不会发生，但不排除有没考虑到的情况。一般情况下，你可以随意热重载以刷新插件配置。
 
 ## 注意
 ### 关于首次使用
-首次加载插件的时候，插件将自动初始化配置并卸载自己。你需要正确修改默认的配置文件，并在settings.json中启用plugin_enabled配置项以启用插件，然后重载插件以正常使用。
+首次加载插件的时候，插件将自动初始化配置并卸载自己。你需要正确修改默认的配置文件，然后重载插件以正常使用。
+
+如果`/path/to/mcdr/config/matrix_sync/config.json`中的机器人账号信息有误，会出现报错，在反馈报错到Issues前，请确认你的信息准确无误，否则无助于解决问题。
 
 - 不打算支持加密信息（EE2E），有需要可以二次开发修改插件，欢迎PR。
 

README_en_us.md

@@ -3,53 +3,10 @@
 > To avoid incorrect links after merging into the main branch, all URLs should use the main branch's address. If you are accessing other branches, please make sure to manually adjust the link's target location.
 
 # MatrixSync-MCDR
-A MCDR (full name [MCDReforged](https://mcdreforged.com/)) plugin, use to sync messages between Matrix groups and online gaming in Minecraft servers.
+A MCDR (full name [MCDReforged](https://mcdreforged.com/)) plugin, can sync messages between Matrix groups and online gaming in Minecraft servers.
 
 About [Matrix](https://matrix.org/): an open decentralized network communication protocol for chat software.
 
-The following project is used in the development process: [matrix-nio](https://pypi.org/project/matrix-nio/)。
+The following project is used in the development process: [matrix-nio](https://pypi.org/project/matrix-nio/).
 
-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`.
-
-## 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.
-
-Before using this plugin, you must know what [Matrix](https://matrix.org/) is, then prepare an account as a matrix bot for message synchronization, and carefully read the following content to configure the plugin.
-
-After configuration and enabling the plugin, if the test message is successfully sent to the matrix group, it means that message synchronization has started to work.
-
-If there is any issue with message forwarding in any direction during the message synchronization process, please check the configuration according to the following content to ensure it is correct.
-
-### Configuration File
-#### config.json
-
-| Configuration Item | Content |
-| - | - |
-| **homeserver** | The homeserver address 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 sync game 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, disable to see old messages when plugin is just loaded |
-
-## Interface (API)
-See the docs in [中文文档](https://github.com/Mooling0602/MatrixSync-MCDR/blob/docs.md) at present.
-
-## Hot Reload (reload) & message sync control
-It is advisable not to use hot reload in a stable environment.
-
-Execute `!!msync` to see the usage.
-
-## 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.
+README v2.5.0+ need new translations, but not prepared yet, you can use translation tools to read "中文" README at present. I would be grateful if you could help translation by commit PRs.

config.ini

@@ -1,9 +1,8 @@
-# Do not edit this file!
-# 不要修改这个文件！
+# Ci configuration for GitHub Actions.
 [framework]
-ver=1
+ver=4
 [main]
-ver=2.4.2
+ver=2.5.0
 [release]
 test=0
 [ci]

docs.md

@@ -7,47 +7,8 @@
 插件配置部分仍保留在README。
 
 ## 接口（API）
-这里介绍插件提供的内部接口。
+这里介绍插件提供的接口。
 
-### 新版接口（v2.4.0）
-2.4.0版本以后，插件完善了已有的消息上报器（MC -> Matrix）接口。
+从v2.5.0起，插件重构了内部所有的API，并且不再支持MCDReforged未达到v2.14的版本。
 
-简单用法：
-```python
-import ...
-from matrix_sync.reporter import send_matrix
-
-def main():
-    # 若message为MCDR.ServerInterface.rtr()，你需要将其转换为str类型，或改用MCDR.ServerInterface.tr()，否则会发生错误。
-    # 该问题的产生原因未知，暂时无法解决。
-    message = "你要发送的消息"
-    send_matrix(message)
-```
-目前发送结果可以通过启用MCDR配置中的debug.plugin项获取。
-
-> 在MCDR中，常用`server.logger.info`或`psi.logger.info`代替`print`，以进行更标准化的日志格式输出。
-
-### 旧版接口（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版本，如果你正在使用！
+> 待插件进入LTS推送阶段后，将完善文档内容。目前尚处于开发阶段，暂停更新。

lang/en_us.yml

@@ -1,54 +1,31 @@
-matrix_sync:
-  debug:
-    send_command: Message you typed has sent to matrix.
-  init_tips:
-    config_path: Config path
-    need_edit_config: Please edit the default config.json to the correct configuration information, and then restart the plugin after enabling the plugin_enabled item in settings.json!
-    read_config: Applying precent config, please waiting...
-    token_invaild: Please manually delete the old version's token, then reload this plugin!
-    user_mismatch: Detected token cached mismatch present bot account (%user_id%), please delete token or use correct bot account!
-    do_unload: Plugin is unloading, please reload manually after you configured right.
-  on_console:
-    commands: Excute command
-  on_server_stop: Server stopped, stopping messages sync.
-  on_server_crash: Server crashed or not stopped normally, stopping messages sync, unknown errors may happen. 
-  on_unload: Unloading plugin, waiting for message sync process to exit...
-  unload_tips:
-    on_clean: Execute clean process.
-    start_clean: Preparing clean...
-  run_tips:
-    failed: Failed to login
-    first_time_login: First login, continuing with password...
-    login_success: Login successfully, caching token for later uses.
-    get_token: Token Cached!
-    error: Please check your account, password and network conditions, you can issue in GitHub for any help.
-  manual_sync: 
-    start_sync: Room message receiver (as sub thread 'MatrixReceiver') started!
-    stop_sync: Room message receiver stopped! Before next time server startup, it needs to be started manually.
-    start_error: Room message receiver is already running, do not restart it in cases not special such as non-reloading or after stopped!
-    stop_error: Unknown errors happened when stop room message receiver!
-    stop_denied: Please run in console!
-    not_running: Room message receiver is not running!
-  sync_tips:
-    server_stopping: MC Server is stopping now...
-    server_stopped: MC Server stopped.
-    server_started: MC Server started successfully!
-    server_crashed: MC Server crashed or not stopped normally!
-    reporter_status: Message sync has inited on MC Server!
-    msync_running: Message sync is running
-    msync_stopped: Message sync is stopped
-    start_report: Bot login successfully, sent a test message.
-    test: Player message detected, trying to send to Matrix group...
-  tr:
-    hs: Homeserver
-    ac: Account
-    cs: Console
-  help_tips:
-    message: "See command help page for §7!!msync§r "
-    title: "----- MatrixSync command help page -----"
-    root_command: "§7!!msync §rShow this help page"
-    start_command: "§7!!msync start §rStart message sync（Auto executes when server startup.）"
-    stop_command: "§7!!msync stop §rStop message sync（Auto stops when server exit.）"
-    send_command: "§7!!msync send §rSend a text message to the matrix room, can be quote by \"\" if spaces are included in the text."
-    status_command: "§7!!msync status §rSee the present status of message sync"
-    reload_command: "§7!!msync reload §rReload this plugin and apply config changes"
+matrix_sync: 
+  check_config: Please recheck your config, if you confirm it's correct, issue this in GitHub.
+  help:
+    message: "See the help page for §7!!msync§r commands."
+    title: "----- MatrixSync Command Help -----"
+    root: "§7!!msync§r Show this help page."
+    start: "§7!!msync start§r Start message sync(will automatically start when loaded plugin and server startup)."
+    stop: "§7!!msync stop§r Stop message sync."
+    send: "§7!!msync send <message>§r Send a specified message to matrix, can be quoted by \"\"."
+    status: "§7!!msync status§r Check the status of message sync."
+    reload: 
+      plugin: "§7!!msync reload§r Reload this plugin and refresh its config."
+      subpack: "§7!!msync reload <pack_name>§r Reload a subpack and refresh its config."
+  login:
+    failed: Failed to login your bot
+    success: Login by password successfully!
+    save_token: Saving token for the bot account...
+  on_receiver_cancelled: Receiver task was cancelled.
+  on_send_command: Message is sending to matrix...
+  on_sync_running: Already running message sync!
+  on_sync_start: Starting message sync...
+  on_unload: Unloading MatrixSync...
+  server_status:
+    starting: MC server is starting...
+    on_startup: MC server started!
+    on_stop: MC server stopped.
+    on_crash: MC server crashed!
+  sync_status:
+    running: MSync is running...
+    not_running: MSync is not running.
+  token_mismatch: The token mismatches present bot account! Sync tasks will not continue.