CardBoard SharkMI Fork

Minecraft 版本： 1.21.11

平台： fabric

标签： library utility

# Cardboard (SharkMI Fork) **Run Bukkit / Spigot / Paper plugins on Fabric servers** [](LICENSE) [](https://fabricmc.net/) [](../../stargazers) [中文](README.zh_CN.md)

This is a community fork maintained by SharkMI, based on CardboardPowered/cardboard.

It includes additional compatibility fixes that have not yet been merged upstream.

Issues & Feedback

• Fork-specific bugs or suggestions → Please open an Issue in this repository.
• General discussion or questions → Feel free to join the Cardboard Discord (the upstream community).

Fork Differences

This is a fork of the official Cardboard project with the following changes:

• Enhanced mixin compatibility: Replaced @Overwrite annotations with precise injection methods (@Inject, @ModifyArg, @Redirect) to avoid conflicts with other Fabric mods
• MiniMOTD compatibility: Fixed server status ping conflicts with MiniMOTD mod
• carpet-tis-addition compatibility: Fixed boat item placement conflicts
• Fabric API NPE fix: Resolved crash caused by Fabric API field injection timing
• OWASP security scanning: Integrated OWASP Dependency-Check into the build pipeline
• Mixin conflict detection tool: Built-in runtime scanner that detects mixin conflicts across all loaded mods at startup (6 detection rules, FATAL/HIGH/MEDIUM/LOW severity levels, console + JSON report output, optional auto-disable for fatal conflicts)

AI-Assisted Development

This fork is heavily AI-assisted. Except for the original code inherited from
the upstream Cardboard project,
most of the additional code in this repository is written by AI. Code is
build-checked and smoke-tested before release, but is not fully manually reviewed.

Primary AI tools used:

• Trae SOLO — daily coding companion
• OpenCode — terminal-native AI coding agent
• DeepSeek Harness — automated development harness powered by DeepSeek models

A build and basic smoke tests are run before each release.

Overview

Cardboard is an implementation of the Bukkit/Spigot/Paper API for FabricMC. It allows you to run plugins from the Bukkit ecosystem on a Fabric modded server, giving you the best of both worlds: mods and plugins.

Features

• Support for Bukkit/Spigot/Paper plugins
• Full Bukkit API implementation (work in progress)
• NMS (net.minecraft.server) support with automatic remapping
• Compatible with Fabric API
• Mojang official mappings

Installation

Prerequisites

Steps

1. Install Fabric Server

   • Download the Fabric Installer
   • Or use the Fabric Server Installer

2. Download Cardboard

   • Get the latest jar from the official website, GitHub Releases, or Modrinth

3. Place in mods folder

   server/
   ├── mods/
   │   ├── cardboard-xxx.jar    <-- put here
   │   └── fabric-api-xxx.jar   <-- Fabric API (required)
   ├── eula.txt
   └── server.properties

4. Start the server

   • The config file will be generated automatically on first launch
   • Place plugins in the plugins/ folder

Usage

Loading Plugins

Simply drop .jar plugin files into the plugins/ directory and restart the server.

Configuration

Configuration file is located at config/cardboard/cardboard-config.yml:

# Enable automatic conflict resolution
auto-conflict-resolution: true

# Force-disabled mixins (for resolving conflicts)
mixin-force-disable: []

# Mixin conflict detection
runtime-conflict-scan: true
conflict-scan-json-output: false
auto-disable-fatal-conflicts: false

# Debug options
debug-print-event-call: false
debug-print-all-calls: false

For detailed conflict detection configuration, see docs/mixin-conflict-detection/user-guide.md.

Building

Requirements

• Java 21+
• Gradle (wrapper included, no extra installation needed)

Build Commands

# Windows
.\gradlew.bat build

# Linux/Mac
./gradlew build

# Skip tests (faster)
.\gradlew.bat build -x test

Build artifacts are located in build/libs/.

Version Support

This fork targets Minecraft 1.21.11 only — no older or newer versions are supported.

Java 21 Flags

This fork targets Minecraft 1.21.11 and requires Java 21. Java 21's
module system blocks runtime reflection into internal JDK APIs, which is used by
some plugins — e.g. the Libby dependency injection used by Citizens and similar
plugins. Paper-like launchers include these flags by default, but hand-written
start.sh scripts will fail without them.

Add the following to your server startup script:

JAVA_OPTS="--add-opens java.base/java.lang=ALL-UNNAMED \
  --add-opens java.base/java.lang.invoke=ALL-UNNAMED \
  --add-opens java.base/java.lang.reflect=ALL-UNNAMED \
  --add-opens java.base/java.io=ALL-UNNAMED \
  --add-opens java.base/java.net=ALL-UNNAMED \
  --add-opens java.base/java.nio=ALL-UNNAMED \
  --add-opens java.base/java.util=ALL-UNNAMED \
  --add-opens java.base/java.util.concurrent=ALL-UNNAMED \
  --add-opens java.base/java.util.jar=ALL-UNNAMED \
  --add-opens java.base/java.util.zip=ALL-UNNAMED \
  --add-opens java.base/java.text=ALL-UNNAMED \
  --add-opens java.base/sun.nio.ch=ALL-UNNAMED \
  --add-opens java.base/sun.security.x509=ALL-UNNAMED \
  --add-opens java.rmi/sun.rmi.transport=ALL-UNNAMED"

Example start.sh:

java $JAVA_OPTS -jar fabric-server-launch.jar nogui

Offline Dependency Directory (plugins/libraries)

plugins/libraries/ is Cardboard's external dependency directory for plugins.
Plugins such as Citizens use Libby to download their runtime dependencies
(adventure, mocha, ph-tree, etc.) over the network on the fly. If your server
has no internet access, or you would rather skip the download, drop the
required dependency jars into plugins/libraries/. Cardboard's plugin class
loader will fall back to loading classes from this directory when they are not
found in the plugin jar or the global class loader, so no online download is
needed.

Known Issues

• Mixin Conflicts: Some Fabric mods using @Overwrite may conflict with Cardboard
  • Solution: Configure mixin-force-disable in cardboard-config.yml
• NMS Plugins: Some plugins deeply dependent on NMS may not work
  • Cardboard supports automatic NMS remapping, but coverage is not 100%
• Missing Events: A few Bukkit events are not yet implemented

Contributing

We welcome contributions of all kinds.

Reporting Bugs

1. Search Issues for existing reports of the same problem
2. If not found, create a new issue with:
   • Server log (latest.log)
   • Cardboard version
   • Steps to reproduce

Submitting Code

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

Development Guidelines

• Follow Conventional Commits specification
• Use English for code comments
• Use @Inject instead of @Overwrite for new mixins

Documentation

Note: Comprehensive documentation for this fork is still being written. The following resources are available:

• Modrinth Page — Latest releases and version history
• GitHub Releases — Release notes and downloadable artifacts
• Upstream Wiki — General Cardboard documentation
• API Javadoc — Bukkit API reference
• Supported Bukkit Versions
• FAQ

Credits

• BukkitTeam, Spigot, and Paper for their work on the API
• Glowstone for the library loader
• md_5's SpecialSource, SrgLib by Techcable & Orion, MinecraftMapping by Phase
• All Cardboard contributors
• All SharkMI fork contributors
• Trae SOLO, OpenCode, and DeepSeek Harness for AI-assisted development

License

This project inherits the license from Paper. See Paper's License for full details.
SrgLib is licensed under MIT.

This project is licensed under the GPL-3.0 License. See LICENSE for details.