mcdreforged / plugincatalogue

The official MCDReforged plugin catalogue

MCDReforged

English | 中文

This is a python based Minecraft server control tool

MCDReforged (abbreviated as MCDR) is a tool which provides the management ability of the Minecraft server using custom plugin system. It doesn't need to modify or mod the original Minecraft server at all

From in-game calculator, player high-light, to manipulate scoreboard, manage structure file and backup / load backup, you can implement these by using MCDR and related plugins

Great thanks to chino_desu and his MCDaemon 1.0 for the idea of such a cool Minecraft control tool

Contact me on discord: Fallen_Breath#1215

Advantage

• It's running above the server. It doesn't need to modify the server at all which keep everything vanilla
• Hot-reloadable plugin system. You don't need to shut down the server to update the plugins
• Multi platform / server compatibility. Supports vanilla, paper, bungeecord etc. on Linux / Windows

How it works?

MCDR uses Popen to start the server as a sub-process, then it has the ability to control the standard input / out stream of the server

Since the console output of a Minecraft server has a stable format and contains a large amount of useful information about the server, e.g. player chat messages, MCDR is able to parse and analyze the server output, abstract them into different events and dispatch them towards plugins for responding

With the help of Minecraft command system, MCDR can send Minecraft commands via the standard input stream to affect the actual Minecraft server

That's it, you can even think of MCDR as a robot that stares at the server console and can quickly respond to server output and input related commands if you like

Plugin

Here is a MCDR plugin collection repository

Document

Check https://mcdreforged.readthedocs.io/ for more details of MCDR

plugincatalogue's Issues

[讨论]：插件接收标准

!!bot list is not working

I had a server on 1.17.1 and I update to 1.18.3 but I create a new MCDR server and when I try to use the options !!bot list give, that worked on my 1.17 server, I cant use them but I can use other commands as !!bot spawn it works so the problem is with the buttons on the !!bot list. What could be the problem?

插件库AdvancedWhiteList的Github仓库被删除

插件仓库中，高级白名单插件被删除，Github页面显示404

[讨论]：检查插件分支是否存在

例如 ToDoList，分支与实际不匹配。

github api似乎在分支不存在的时候会跳转默认分支，因此可以正常抓取，但这样是不是合理？

添加 “是否支持 MCDR 1.x” 表头

现在有一大摞插件不支持 MCDR 1.x 以及一大堆只支持MCDR 1.x
设想如下：

类型	兼容性	意义
双向支持	A	All
只支持 MCDR 1.x	O	Only 1.x
只支持 MCDR 0.x	-	No

兼容性应位于插件名表头之前。
例：

1.x	Name	Maintainer	Function
O	daycount-NBT	Alex3236	An easy-use daycount
-	seed	ChunkAsgore	A plugin for querying server map seeds for MCDReforged.
A	Here	Fallen_Breath	Broadcast your position and high light yourself

是否可能向 Catalogue 信息有问题的 Repo 发出提醒？

参见 最近的运行，目前有 1 个 repo 没了的插件，1 个找不到简介的插件，4 个版本 tag 有问题的插件。

是否有可能通过自动向对应 repo 提交 issue，告知这些问题？

sava的列表，不能用类别名称（如custom，mined..)做标题

保存快速计分项!!stats save custom xp xp，再进行普通的stats查询就会报错

[Issue] Readme Text Indecipherable on Dark Mode

Description

The dark blue text in the readme file is barely readable on Github dark mode

一个可以一键安装想要的MCDR插件应用

GUI web界面，逻辑清晰，脚本一键安装。

教程视频：http://www.bilibili.com/video/BV18a4y1E7T5
应用站点：https://www.cyf-cloud.cn/#/util/mcdrPlg

如果觉得可以的话麻烦收录一下。

插件meta应当分版本提供依赖和依赖版本

插件仓库的 Web 页面

表头选择排序方式
需要html？

希望插件列表包含更详细的简介

希望插件列表点进去以后可以不仅仅是列表里面的简单介绍，而是有更多的关于插件的信息（例如主要功能描述等等）

[讨论] 插件接收工作

#219 的扩展讨论。目前的两个问题如下：

Checklist 不工作

应该是权限问题，需要仓库所有者调整；Checklist 是否必要？

插件“审核”与“通过”没有特定标准

• 更完善的标准？
• 也许可以学习其他类似项目，调整权限和工作流，例如 PR 仅在两位 CatalogueMaintainer Approve 后自动合并。

`link` is not available in `MetaInfo`

I suppose this could be added in MetaInfo.
https://mcdreforged.readthedocs.io/zh_CN/latest/plugin_dev/metadata.html#link

How do I specify the java path in "start_command:"?

在 meta 中储存 `plugin_info.json` 中的 `related_path` 和 `branch` 信息

在 meta 中没有相对路径信息，用户打开仓库后还需要再找路径才能看到插件和文档
如果直接在文档超链接直接点击打开到相对路径，可能会更加方便

文档同理

[插件反馈]qq_chat群内使用/list时返回的信息有误

在群聊内使用/list，返回的在线玩家列表中列出的是开服以来所有登录过的玩家名称，而不是实际在线的玩家名称

[讨论] 关于插件仓库的网页

背景

• 当前我个人制作了一个网页版的插件仓库，实现了插件的搜索和筛选功能，及更美观和符合直觉的信息展示。网址为：https://mcdr.zhanganzhi.com
• 仓库链接
• 该网站部署在 Vercel，使用我个人的账号；投票/点赞 功能数据库位于国内服务器
• #150

建议

现征求 MCDR 核心开发者及社区关于以下想法的意愿和建议：

1. 该项目的任何改进建议
2. 将该项目仓库移到 MCDReforged 组织中
3. 在插件库文档加入该网页，并作为用于查找插件首选建议
4. 修改项目的版权声明，当前在网站和文档声明并非官方或社区项目，为个人项目
5. 项目预留了 MCDR 官方网站功能的空间，可用于展示文档、信息、教程或提供相应链接
6. Vercel 部署的相关问题
7. 域名费用我可以个人继续承担，无需担心

[问题] 插件Meta中作者信息与Catalogue不一致的处理方式

例如 AdvancedWhitelistR，其插件 mcdreforged.plugin.json 列出的作者 GamerNoTItle 并未提交到插件仓库 plugin info 的作者列表，这会导致生成的目录和元数据无法包含该作者。

请问该类情况的预期是如何处理的？

由于未启用 RCON，没有返回结果

请问我应该在哪里启用相关的rcon
服务端的rcon已经开启了
qq执行命令有效果
但是不能返回结果

PR check 处理 introduction 问题

PR check 时，应当注意 introduction 是否存在，作为参考。可以：

• 在 check 时以某种方式输出最终效果；或
• 在 check 时 raise 相关问题

貌似如果开了tw的发言时间显示就会同时出现两条一样的对话

handle external markdown files links with relative path

Currently, external markdown files' links are written by scripts, but relative path used in links are not handled. However, github can handle these links with relative path, but it would be better to add handling for it to improve simplicity and stability.

Example:

PluginCatalogue/plugins/bot/readme.md

Line 256 in ca4f659

This plugin supports [FastAPI MCDR](https://github.com/AnzhiZhang/MCDReforgedPlugins/tree/master/src/bot/../fastapi_mcdr) plugin, please refer to the source code for detailed API, or run and view the FastAPI document via `http://127.0.0.1:8080/docs`.

See Also:

c426edc

插件管理器实现思路

续 #89

就目前讨论的方案记录

---

目前的打算是让作者在插件仓库注册一个LTS版本的plugin_info,json(或yml)
然后插件管理器透过读取plugin_info.json获取插件的大约资讯和连接
以供给用户暂时性观看。

如果需要详细资讯在透过plugin_info.json内的连接前往作者的仓库
再在作者的仓库里面读取作者自己维护的data.json(或yml)
然后从data.json里面的文件决定具体操作流程

---

插件仓库内的文件结构大概如下

• /plugin_info.json(有可能变成yml)

id: [str]
author: list[str] or [str]
link: [str]
name: [str]
info: {
    en_us: desc[str]
    zh_cn: desc[str]
}
---

作者仓库的文件结构

作者仓库目前还没有大约的共识，故指留下大约的文件结构，内容暂时没有。

• my_plugin.py: 插件/插件入口
• readme.md: 自述文件
• plugin/mcdreforged.plugin .yml/.json: 名称未定，作者需要维护的插件信息
• my_plugin/: 非必选，插件所需其他文件
• ...

Preserve `author`with link and `introduction` in `MetaInfo`?

I suppose that all origin data of plugin_info.json will be copied to meta, and merged with plugin meta.

PluginCatalogue/scripts/plugin.py

Line 55 in b076a4c

meta_info.authors = list(map(lambda a: a.name, plugin.authors))

---

For introduction in code, maybe parse introduction url first, and provide to meta branch, and use this url to get Text introduction. Or at least it should be a dict or null, instead of be removed.

e.g.

• QBM:

"introduction": {
    "en_us": "https://raw.githubusercontent.com/MCDReforged/PluginCatalogue/master/plugins/quick_backup_multi/introduction-zh_cn.md",
    "zh_cn": "https://raw.githubusercontent.com/MCDReforged/PluginCatalogue/master/plugins/quick_backup_multi/introduction.md"
}

• Bot:

PluginCatalogue/plugins/bot/plugin_info.json

Lines 13 to 16 in b076a4c

	"introduction": {
	"en_us": "readme.md",
	"zh_cn": "readme.md"
	}

"introduction": {
    "en_us": "https://raw.githubusercontent.com/AnzhiZhang/MCDReforgedPlugins/master/bot/readme.md",
    "zh_cn": "https://raw.githubusercontent.com/AnzhiZhang/MCDReforgedPlugins/master/bot/readme.md"
}

PluginCatalogue/scripts/plugin.py

Line 313 in b076a4c

introduction: Text

插件仓库下载列表未准确识别

插件 StartStopHelperR 的下载列表未识别到 release
https://github.com/MCDReforged/PluginCatalogue/blob/catalogue/plugins/start_stop_helper_r/readme.md
https://github.com/AnzhiZhang/MCDReforgedPlugins/releases/tag/start_stop_helper_r-v0.1.0

原因未知
9e71dc7#diff-a2f8344b51630c0fbfc8bb902f079e56afa0076cdae77db97be7b7c6970fce0c

PR 未创建有效文件时，Actions 检查结果为通过

#307 未上传有效的插件文件，但两个检查结果均为通过。是否可能更新 actions 以检查是否是是新增插件的 PR 且文件有效？
https://github.com/MCDReforged/PluginCatalogue/actions/runs/7328987096/job/19958141432
https://github.com/MCDReforged/PluginCatalogue/actions/runs/7328987097/job/19958141587

[Bug] PR check 问题

PR Check 应仅检查 PR 的插件

update timed_quick_backup_multi

TISUnion/TimedQBM code has been updated to 1.2.0 but not released.
I packaged this plugin here https://github.com/NanamiNakano/TimedQBM/releases/tag/v1.2.0
Please update plugin info and create a release in the main repo.

基于Json格式数据存储的插件管理器实现思路

需求

目前插件较多，且大量重复，有大量插件不兼容最新版MCDR
需要一个新的插件库和插件管理器来提供更加便捷的插件选择与管理

结构

在此仓库中存储 插件库
制作一个MCDR插件作为 插件管理器

插件库

存储格式

插件库使用Json格式存储，方便插件管理器读取数据

信息内容

每个插件以 object 的形式存储在不同分类的 array 中， 每个插件包括以下内容，对比当前插件库内容，多了最后的4项内容：

• 插件名
• 作者
• 中文描述
• 英文描述
• 插件id
• 作者
• 地址
• 原始文件地址
  示例：

{
        "id": "my_plugin",
        "name": "MyPlugin",
        "description_cn": "这是一个例子",
        "description_en": "This is a example",
        "author": "myself",
        "link": "https://github.com",
        "raw_link": "https://raw.github.com/MyPlugin.py",
        "dependencies": {
            "package": [
                "requests",
                "json5"
            ],
            "plugin": [
                "an_api",
                "minecraft_data_api"
            ]
}

当前已完成的部分Json数据示例

期望行为

假设插件管理器已开发完成，通过读取该插件库提供插件选择、搜索、自动下载、分析依赖并下载的功能
插件作者将会在这个插件库文件添加他的插件信息，一次性添加
服主组服务端时，安装好MCDR和mc服务端，安装插件管理器。随后通过指令查看插件列表和分类、信息等内容，或通过搜索选择插件。最后进行选择，点击安装某个插件。插件管理器自动下载该插件，并自动下载该插件的依赖python包或其他插件

现在的插件安装流程

1.在插件库的markdown文档中选择
2.下载所需的插件
3.安装插件的依赖
4.安装完成

使用插件管理器的插件安装流程

1.在MCDR内选择插件
2.选择好后自动下载
3.安装完成

插件库和插件管理器规范简述

插件仓库

概览

向本仓库添加插件, 需要作者长期维护 mcdreforged.plugin.yml,
一次性提交 plugin_id.yml

plugin_id.yml 中提供插件基本信息, 提供指向 mcdreforged.plugin.yml 的链接

mcdreforged.plugin.yml 包括版本历史、下载地址、依赖包、依赖插件等信息, 插件管理器依据本文件安装插件

一个例子

小明开发了一个新插件 pl, 在 GitHub开源, 想要加入插件库

小明需要 fork 本仓库, 向本仓库的 meta 文件夹中添加 pl.yml, 内容如下:

id: pl
name: Pl
author: xiaoming
describe:
  en_us: My plugin
  zh_cn: 我的插件
link: https://github.com/xiaoming/pl
info_link: https://raw.githubusercontent.com/xiaoming/pl/master/mcdreforged.plugin.yml

小明在他的开源仓库增加一个 mcdreforged.plugin.yml 文件, 同时给 0.0.1 版本的提交打一个名为 0.0.1 的 tag, 内容如下:

id: pl
name: Pl
author: xiaoming
describe:
  en_us: My plugin
  zh_cn: 我的插件
link: https://github.com/xiaoming/pl
version:
  0.0.1:
    files:
      pl.py: https://raw.githubusercontent.com/xiaoming/pl/0.0.1/pl.py

当小明更新插件时, 同步给 mcdreforged.plugin.yml 的 version 添加以下内容:

0.0.2:
    files:
      pl.py: https://raw.githubusercontent.com/xiaoming/pl/0.0.2/pl.py

更新后的 mcdreforged.plugin.yml 是这样的:

id: pl
name: Pl
author: xiaoming
describe:
  en_us: My plugin
  zh_cn: 我的插件
link: https://github.com/xiaoming/pl
version:
  0.0.1:
    files:
      pl.py: https://raw.githubusercontent.com/xiaoming/pl/0.0.1/pl.py
  0.0.2:
    files:
      pl.py: https://raw.githubusercontent.com/xiaoming/pl/0.0.2/pl.py

更新 commit 之后, 给这次提交打一个tag 0.0.2

如果小明的插件有依赖或安装脚本, 详见 mcdreforged.plugin.yml

本仓库简介

本仓库有以下文件, 除 plugin_id.yml 手动添加外均由 github actions 自动生成：

文件名	位置	作用
plugin_id.yml	meta/	增加新插件时作者提供的插件信息
plugin_id.md	docs/lang/catalogue/	单个插件描述
index.md	docs/lang/	完整插件目录
full.md	docs/lang/	完整插件描述
plugin_list.json	/	插件列表

本仓库文件结构：

meta/
    plugin_id.yml
    ...
docs/
    en_us/
        catalogue/
            plugin_id.md
            ...
        index.md
        full.md
    zh_cn/
        ...
scripts/
    ...
plugin_list.json
readme.md

plugin_id.yml

id: str（插件id）
name: str（插件名)
author: str/array（作者）
describe:
  en_us: str（英文介绍）
  zh_cn: str（中文介绍）
link: str（展示地址，可以是repo）
info_link: str（指向插件信息mcdreforged.plugin.yml的链接）

plugin_id.md

# name

> describe

ID: id
Authors: authors
Link: [name](link)

plugin_list.json

由 GitHub actions 自动生成的完整插件列表

{
  "data": [
    {
      "id": "",
      "name": "",
      "author": "",
      "describe": {
        "en_us": "",
        "zh_cn": ""
      },
      "link": "",
      "info_link": ""
    }
  ],
  "update_at": 0
}

添加插件到本仓库

作者需维护一个名为 mcdreforged.plugin.yml 的文件, 存储位置任意, 获取到该文件的链接

向本仓库添加 plugin_id.yml, 参考 plugin_id.yml

mcdreforged.plugin.yml

id: str（插件id）
name: str（插件名)
author: str/array（作者）
describe:
  en_us: str（英文介绍）
  zh_cn: str（中文介绍）
link: str（展示地址，可以是repo）
setup: str（安装脚本链接，可选）
dependencies（依赖，可选）:
  python（python依赖）:
    requests: '*'
    PyYAML: '5.4.1'
  plugin（插件依赖）:
    minecraft_data_api: '*'
    vault: '>=0.0.1'
version:
  0.0.1:
    files（所有文件按此结构下载到plugins中）:
      plugin.py: str（链接）
      plugin（文件夹名）:
        tool.py: str（链接）
    setup: str（安装脚本链接，python可执行文件，可选）
    dependencies（依赖，可选）:
      python: object（python依赖）
      plugin: object（插件依赖）
  0.0.2:
    ...
  ...

setup

插件的安装脚本链接, 为 .py 文件, 插件管理器直接执行一遍该脚本

脚本执行路径: MCDR 工作路径

可以为每个版本单独指定

dependencies

插件的依赖, 分为 python 包依赖和插件依赖

可以为每个版本单独指定

插件管理器安装插件步骤

• 读取 plugin_list.json 并找到插件
• 根据 info_link 找到并读取 mcdreforged.plugin.yml
• 根据指定版本将 files 中的文件下载到 plugins 文件夹中
• 下载并执行 setup 指定的安装脚本
• 安装 dependencies 中的 python 包
• 重复以上步骤直到 dependencies 中的 plugin 安装完成

优点

1. 插件版本历史等信息在作者可以随时维护的 mcdreforged.plugin.yml 中, 便于作者更新
2. 插件下载考虑到单文件和多文件情况, 可以在 files 中填写多个文件来进行下载
3. 提供 setup 字段, 作者可以利用按照脚本进行个性化配置; 也可以用于在 files 中填写一个压缩包链接, 由安装脚本处理
4. 可以针对不同版本指定 setup 和 dependencies
5. 该方案在涉及其他链接和文件的地方选择使用 文件直链 的方式, 所以稳定性十分优秀, 而且可以去与 git 的耦合
6. 可以由社区来帮助一些作者维护 mcdreforged.plugin.yml

缺点

1. 插件库可以镜像, 但是下载插件无法镜像, 只能依靠作者在 mcdreforged.plugin.yml 给的链接

PlayTime插件未遵循开源规范，申请暂时移除对该插件的收录

pt插件作者未经本人同意擅自修改并分发playerLastPlay插件仓库，未遵循开源规范。期间沟通未果，申请移除pt插件的收录

Plp仓库: https://github.com/Aimerny/playerLastPlay
PlayTime仓库issue: A350xt/playtime#1

为 meta 分支的 `plugins.json` API 提供更多信息

为人类展示的插件目录显示了最后更新时间信息

若模仿 Modrinth 制作插件库网页（#150），还需要展示下载量信息

为节约目录网页的API请求数量，避免遍历请求每一个插件的 release API，建议将相关统计后的信息整理到 plugins.json 中，例如总下载量和最后更新时间

用户修改插件实际位置，未更新 `related_path`，action 运行失败，而不是发出警告

https://github.com/MCDReforged/PluginCatalogue/actions/runs/7762245788/job/21172312766#step:7:1795

下载量统计不准确

更新的插件下载量统计方式只计算一个附件，若插件发布多个变体（如 pyz 和 mcdr），只会统计部分的有效下载量。

相关代码：

PluginCatalogue/scripts/meta/release.py

Lines 186 to 190 in a5ade66

	def get_total_downloads(self) -> int:
	total = 0
	for release in self.releases:
	total += release.asset.download_count
	return total

`labels` is not available in `MetaInfo`

Currently there's no way to get plugin labels from https://raw.githubusercontent.com/MCDReforged/PluginCatalogue/meta/plugins.json

This breaks plugin managers based on this json file

另一种插件管理思路

基于 chino 的观点整理，并根据 #94 优化部分思路。

插件库格式

meta/
    master/ (Repo 1)
        plugin_id.json (以插件 ID 命名的插件信息文件，或参考 #94 的每个插件单独文件夹的格式)
    test/ (Repo 2)
        plugin_id.json
docs/ (Github Action 生成，供人阅读)
    master.md
    test.md
api/ (Github Action 生成，管理器读取)
    master.json
    test.json
scripts/ (Github Action 脚本)
    ...

插件信息，即作者需要填写的内容内容

{
    "Quick Backup Manager": {
        "author": "Fallen_Breath",
        "function":{
            "en": "Backup/Restore plugin, with muti backup slot.",
            "zh": "多槽位备份/回档插件。"
        },
        "storage": "https://github.com/Fallen-Breath/QuickBackupM"
    },
    "Another Plugin": {
        // ...
    }
}

API 信息，即插件管理器读到的，除了作者填写信息外的内容

{
    "latest": "2.0", // 最新版本
    "versions": {
        "1.1": {
            "file_path": "https://github.com/TISUnion/QuickBackupM/blob/873dc9fd1d873f62ec74c8c07a049c9bc558ce55/QuickBackupM.py", 
            "dependencies": { // 如果使用安装脚本则无需规定前置
                "mcdreforged": ">=1.0.0",
                "another_important_api": "*"
            }
        },
        "1.0": {
            "file_path": "https://github.com/TISUnion/QuickBackupM/blob/xxx/QuickBackupM.py", // 减少管理器的工作，可以直接给链接。给ID让管理器合成也不是不行
            "dependencies": {
                "an_important_api": "*"
            }
        }
        // ...
}

作者仓库

/src: 源码文件夹
    QuickBackupM.py
    some_important_files
    ...
version.yml: 版本列表，详见后文“版本列表问题”
    1.0.0: 873dc9fd1d873f62ec74c8c07a049c9bc558ce55 (Git commit ID)
    1.5.1: ...
setup.py*: 如果使用安装脚本，则使用插件管理器给的 API 完成安装前置等工作，无需另外定义前置
    def install():
        # ...
data.json*: 如果不使用安装脚本，则需要单独列出前置等信息
README.md: 自述文件
...

个人观点

目前的基本架构可以确定了：插件库作者填写一次后无需再进行维护，而在自己的仓库按照特定格式维护。
Chino 的这个作者仓库方案其实比 #94 更优（对于机器），但对于作者的格式限制更多。
个人认为插件库支持多 repo、安装旧版本和检查更新还是有必要的。

版本列表问题

Chino 这样的版本记录方案如果让作者手写，有点过于繁琐。
让 Github Action 自动获取 Commit 列表并根据规定的格式自动获取和添加版本，这样就可以将旧版本纳入API里，并且不需要作者每次在多个文件中修改版本号。
比如：Commit 时需发布的版本使用版本号作为标题
另外，若 不 使用安装脚本，这个方法也可以方便地把旧版本前置信息纳入 API。
如果使用 Chino 这个手写的方案，则插件管理器在安装旧版本时需要手动在 Github 获取旧版本前置信息。

另外...

这个方案只对 Github 设计 :)