CardBoard Shark MI Fork

CardBoard Shark MI Fork

在Fabric服务器上运行Bukkit/Spigot/Paper插件 - SharkMI分支，具有增强的mixin兼容性

基础库

Cardboard (SharkMI Fork)

在 Fabric 服务器上运行 Bukkit / Spigot / Paper 插件

许可证 Fabric 星标

这是一个社区分支，由 SharkMI 维护，基于 CardboardPowered/cardboard 开发。

它包含一些尚未合并到上游的额外兼容性修复。

🐛 问题和反馈

  • 特定于分支的错误或建议 → 请在此仓库中提交 Issue。
  • 一般性讨论或问题 → 欢迎加入 Cardboard Discord（上游社区）。

分支差异

这是官方 Cardboard 项目的一个分支，包含以下变更：

  • 增强的 Mixin 兼容性：使用精确的注入方法（@Inject、@ModifyArg、@Redirect）替换了 @Overwrite 注解，以避免与其他 Fabric 模组冲突
  • MiniMOTD 兼容性：修复了与 MiniMOTD 模组的服务器状态 ping 冲突
  • carpet-tis-addition 兼容性：修复了船物品放置冲突
  • Fabric API NPE 修复：解决了由 Fabric API 字段注入时机导致的崩溃问题
  • OWASP 安全扫描：在构建流程中集成了 OWASP Dependency-Check
  • Mixin 冲突检测工具：内置运行时扫描器，可在启动时检测所有已加载模组中的 mixin 冲突（6 种检测规则，FATAL/HIGH/MEDIUM/LOW 严重级别，控制台 + JSON 报告输出，可选自动禁用致命冲突）

概览

Cardboard 是 FabricMC 的 Bukkit/Spigot/Paper API 实现。它允许你在 Fabric 模组服务器上运行 Bukkit 生态系统的插件，兼得模组和插件的优势。

功能特性

  • 支持 Bukkit/Spigot/Paper 插件
  • 完整的 Bukkit API 实现（进行中）
  • 支持 NMS（net.minecraft.server）并带有自动重映射
  • 与 Fabric API 兼容
  • 使用 Mojang 官方映射

安装

前置要求

软件 版本
Java 21+
Fabric Loader 0.16+
Minecraft 1.21.11

步骤

  1. 安装 Fabric 服务器

  2. 下载 Cardboard

  3. 放入 mods 文件夹

    server/
├── mods/
│   ├── cardboard-xxx.jar    <-- 放在这里
│   └── fabric-api-xxx.jar   <-- Fabric API（必需）
├── eula.txt
└── server.properties

  4. 启动服务器

    • 首次启动时，配置文件将自动生成
    • 将插件放置在 plugins/ 文件夹中

使用

加载插件

只需将 .jar 插件文件放入 plugins/ 目录，然后重启服务器即可。

配置

配置文件位于 config/cardboard/cardboard-config.yml：

# 启用自动冲突解决
auto-conflict-resolution: true

# 强制禁用的 mixin（用于解决冲突）
mixin-force-disable: []

# Mixin 冲突检测
runtime-conflict-scan: true
conflict-scan-json-output: false
auto-disable-fatal-conflicts: false

# 调试选项
debug-print-event-call: false
debug-print-all-calls: false

有关冲突检测配置的详细信息，请参阅 docs/mixin-conflict-detection/user-guide.md。

构建

要求

  • Java 21+
  • Gradle（包含包装器，无需额外安装）

构建命令

# Windows
.\gradlew.bat build

# Linux/Mac
./gradlew build

# 跳过测试（更快）
.\gradlew.bat build -x test

构建产物位于 build/libs/ 目录。

版本支持

Minecraft 版本 Fabric 版本 分支 状态
1.21.11 0.16+ ver/1.21.11 活跃
<= 1.21.8 - - 不再支持

此分支仅专注于最新的 Minecraft 版本。旧版本不予维护。有关上游详细信息，请参阅支持的版本。

插件兼容性

已验证可用的

插件 状态 备注
EssentialsX 部分 核心功能可用
WorldEdit 部分 基本操作可用
Vault 实验性 经济系统集成
LuckPerms 实验性 权限系统

已知不兼容的

插件/模组 原因 临时解决方案
使用 Mixin 的部分模组 注入点冲突 在配置中禁用冲突的 mixin

已知问题

  • Mixin 冲突：某些使用 @Overwrite 的 Fabric 模组可能与 Cardboard 发生冲突
    • 解决方案：在 cardboard-config.yml 中配置 mixin-force-disable
  • NMS 插件：某些深度依赖 NMS 的插件可能无法工作
    • Cardboard 支持自动 NMS 重映射，但覆盖率并非 100%
  • 缺少事件：少数 Bukkit 事件尚未实现

贡献

我们欢迎各种形式的贡献。

报告 Bug

  1. 搜索 Issues 以查找是否已有相同问题的报告
  2. 如果未找到，请创建一个新 Issue，其中包含：
    • 服务器日志（latest.log）
    • Cardboard 版本
    • 重现步骤

提交代码

  1. Fork 此仓库
  2. 创建一个功能分支（git checkout -b feature/amazing-feature）
  3. 提交你的更改（git commit -m 'feat: add amazing feature'）
  4. 推送到分支（git push origin feature/amazing-feature）
  5. 创建一个 Pull Request

开发指南

  • 遵循约定式提交规范
  • 代码注释使用英文
  • 新的 mixin 使用 @Inject 代替 @Overwrite

文档

注意：此分支的全面文档仍在编写中。以下资源可供参考：

鸣谢

许可证

本项目继承了 Paper 的许可证。有关完整详情，请参阅 Paper 的许可证。 SrgLib 采用 MIT 许可证。

本项目采用 GPL-3.0 许可证。详情请参阅 LICENSE。