Cardboard (SharkMI Fork)

Run Bukkit / Spigot / Paper plugins on Fabric servers

中文

A personal maintenance fork.

Based on CardboardPowered/cardboard, kept by

SharkMI for personal use on a private server and published

as-is. It targets Minecraft 1.21.11 and contains compatibility fixes that have not been

merged upstream.

Updates follow my own server’s needs and are made on a best-effort basis — no commitment to

long-term maintenance, no guarantee that a specific plugin or mod will work, and no promise to

track upstream. It is a hobby project, not a supported product.

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).

Scope & Expectations

This fork exists for a plain reason: I hit problems on my own server that upstream had not
fixed yet, so I fixed them. What is published here is that work, shared in case someone else
runs into the same thing.

Personal project first. Changes follow what my own server needs; broader compatibility work happens on a best-effort basis.
Compatibility is not guaranteed. A given plugin or mod may or may not work.
Feedback is welcome. Open an issue if something breaks — just don’t expect fast turnaround. A PR with a clear reproduction, and something I can verify, has the best chance of being merged.
The upstream project comes first. For general Cardboard questions, use the upstream project.

This is not meant to be “a more complete Cardboard”. The upstream project is the real one;
this is a patch set that happens to be public.

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 reports mixin conflicts across all loaded mods at startup (console output, optional JSON report, optional auto-disable for fatal conflicts)

How compatibility fixes are made

Fixes target the root cause, not the symptom. When a specific plugin or mod triggers a failure,
the goal is to fix the underlying mechanism so that the same class of failure no longer occurs —
not to silence that one error and leave the next one waiting. A fix that only covers the case at
hand is noted as such in the commit and release notes, so it is not mistaken for a general
solution.

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
CodeBuddy — AI coding assistant
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, so mods and plugins can run side by side.

Features

Support for Bukkit/Spigot/Paper plugins
Broad Bukkit API coverage (work in progress)
NMS (net.minecraft.server) support with automatic remapping
Compatible with Fabric API
Runtime mapping: intermediary (class_xxx)

Installation

Prerequisites

| Software | Version |
|———-|———|
| Java | 21+ |
| Fabric Loader | 0.18+ |
| Minecraft | 1.21.11 |

Steps

Install Fabric Server

Download the Fabric Installer
Or use the Fabric Server Installer

Download Cardboard

Get the latest jar from GitHub Releases or Modrinth

Place in mods folder

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

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 (developer diagnostic, off by default)
runtime_conflict_scan: false
conflict_scan_json_output: false
auto_disable_fatal_conflicts: false

# Debug options
debug_mode: false
debug_print_event_call: false
debug_print_all_calls: false
debug_player: false
debug_other: false
debug_print_remaputil: false

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

Commands

Cardboard provides a /cardboard command (alias /cb) as the single entry point for its
own subcommands, plus replacements for the vanilla /plugins and /version commands.
Command output is bilingual (Chinese / English) — chosen automatically from the player’s
client locale, or set per-player with /cardboard lang <zh|en>.

/cardboard (alias /cb) — requires permission cardboard.command.admin:

Debug flags accepted by debug: verbose, events, player, other, remap, worldedit
(each maps to a config key; list shows the current state and the key).

/plugins (alias /pl) — listing requires permission bukkit.command.plugins;
enable / disable additionally require cardboard.command.admin:

/version (aliases ver, about) — requires permission bukkit.command.version:

Console colours can be controlled with colored-console (default true) and
console-color-pattern in cardboard-config.yml.

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/.

Build Dashboard

Every push to main triggers a CI build (build.yml) that
produces a jar named with the CI run number, e.g.
CardBoard-Fork-SharkMI-1.21.11-2026.10.1+b82.jar — the +b82 is the build number
(bN), the same idea as Citizens’ Jenkins build numbers.

The latest successful jar is published to the ci-build release, and a small dashboard
shows build history, per-day build counts, and a one-tap download:

Dashboard: https://sharkmi-0x7e.github.io/CardBoard/
Latest jar: ci-build release

The dashboard reads the GitHub Actions API directly from the browser. It is unauthenticated,
so it is subject to GitHub’s public rate limit (60 requests/hour per IP) — if it shows a
rate-limit error, just wait a bit and refresh.

Version Support

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

| Minecraft Version | Fabric Version | Branch | Status |
|——————-|—————-|——–|——–|
| 1.21.11 | 0.18+ | main | Active |

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

This is a personal project with limited time behind it, so contributions are appreciated but
are not always quick to be handled.

Bug reports and pull requests are welcome — see CONTRIBUTING.md for build
commands, commit conventions, Mixin rules, and the PR checklist.

Reporting bugs: open an Issue with your server log (latest.log), the Cardboard version, and steps to reproduce.
Submitting code: fork, branch, commit using Conventional Commits, then open a PR.

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, CodeBuddy, OpenCode, and DeepSeek Harness for AI-assisted development

License

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

CardBoard SharkMI Fork

介绍