Compatibility
Minecraft: Java Edition
Platforms
Supported environments
Links
Tags
Creators
Details
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
@Overwriteannotations 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:
| Command | Description |
|---|---|
/cardboard help |
Show this help |
/cardboard version |
Show server version information |
/cardboard about |
Show Cardboard project information |
/cardboard tps |
Show TPS / MSPT / memory / uptime |
/cardboard worlds |
List all worlds and their player counts |
/cardboard mods |
List loaded Fabric mods |
/cardboard plugins [info|enable|disable <name>] |
Show plugins (optionally: info / enable / disable) |
/cardboard debug [list|<flag>|all on|off] |
Debug flags: list / toggle / all on|off |
/cardboard log <trace|debug|info|warn|error|fatal|all|off> |
Change the root log level at runtime |
/cardboard doctor |
One-shot health check with suggestions |
/cardboard dump |
Write a diagnostic snapshot (incl. thread dump) to a file |
/cardboard compat |
List known mod compatibility rules |
/cardboard reload |
Reload the Cardboard config |
/cardboard lang <zh|en> |
Switch language: zh | en (self only) |
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:
| Command | Description |
|---|---|
/plugins |
List plugins (shows "enabled N / total M" plus a colour legend: green = enabled, red = disabled) |
/plugins info <name> |
Show details for a single plugin |
/plugins enable <name> |
Enable a plugin at runtime |
/plugins disable <name> |
Disable a plugin at runtime |
/version (aliases ver, about) — requires permission bukkit.command.version:
| Command | Description |
|---|---|
/version |
Show the server (and Cardboard) version |
/version <plugin name> |
Show version information for a plugin |
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
@Overwritemay conflict with Cardboard- Solution: Configure
mixin-force-disableincardboard-config.yml
- Solution: Configure
- 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.