CardBoard SharkMI Fork

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

Steps

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

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.