v5 Adventure and Server Versions

Adventure and Server Versions

KamiCommon renders text through Adventure on every supported server, from 1.8.8 to 26.2, including versions that predate Adventure by years. You do not have to think about which one you are on. If you want to use Adventure in your own plugin, you do.

Which Adventure your server uses

There is one dispatch decision, made once from the server version.

Server version	Adventure used	Extracts the bundled copy?
below 1.8	not supported	throws at startup
1.8 to 1.11.x	KamiCommon's bundled copy	yes
1.12 to 1.15.x	KamiCommon's bundled copy	yes
1.16.x	KamiCommon's bundled copy	yes
1.17 to 1.18.1	KamiCommon's bundled copy	yes
1.18.2 to 1.21.3	the server's own	no
1.21.4 and up	the server's own	no

The boundary is 1.18.2. From there upward KamiCommon uses Paper's own Adventure, never unpacks anything and never builds a second classloader. 1.18.2 is where Paper's Adventure gained MiniMessage; 1.16.5 through 1.18.1 have an Adventure API but no MiniMessage, which is why they are still on the bundled copy.

Item display names on 1.18.2 through 1.21.3 are written as legacy section-coded strings, because ItemMeta.customName() only exists from Paper 1.21.4. This costs nothing in practice: item names cannot carry hover or click events anyway.

1.17 and above officially support Paper only. The 1.18.2+ tiers call CommandSender.sendMessage(Component), which is Paper API. Dispatch is on version alone, with no Spigot-versus-Paper guard.

The bundled copy is sealed

On servers below 1.18.2, KamiCommon ships its own relocated Adventure inside a nested jar at internal-libs/adventure.jar, loaded through a child classloader whose parent is the plugin classloader.

Java cannot read a jar nested inside a jar, so the copy is extracted before it is loaded. It lands at plugins/<plugin>/internal/adventure.jar, in the data folder of the plugin that owns the KamiCommon copy in use, which is where a server owner will find it. Nothing is extracted on 1.18.2 and above.

You cannot import it. com.kamikazejam.kamicommon.nms.text.kyori.* will not compile, will not appear in autocomplete, and cannot be reached by reflection from your plugin's classloader. Java's classpath has no nested-jar support, so those bytes are not classpath entries at all.

Nesting enforces this. Declaring a dependency runtime-only does not hide it, because scope metadata cannot conceal bytes that are physically present in a jar. Nesting also survives you shading KamiCommon into your own uber jar, which a scope declaration would not.

Instances cross the boundary as VersionedComponent, which names nothing relocated.

So how do I use Adventure in my own plugin?

You can. Just never KamiCommon's copy.

On 1.18.2 and above

Use the server's own Adventure at net.kyori.adventure.*, compiled against paper-api. To move between your Component and KamiCommon's VersionedComponent, either round-trip through JSON:

VersionedComponent vc = NmsAPI.getVersionedComponentSerializer().fromJson(myComponentAsJson);
String json = vc.serializeJson();

or take the native component directly, behind an instanceof check:

VersionedComponent vc = NmsAPI.getVersionedComponentSerializer().fromMiniMessage("<green>hi");
if (vc instanceof ModernVersionedComponent modern) {
    net.kyori.adventure.text.Component component = modern.asNativeComponent();
}

instanceof ModernVersionedComponent succeeds on 1.18.2 and up. Check it; never cast on a version assumption.

Below 1.18.2

The server has no Adventure and KamiCommon's is sealed, so shade and relocate your own, exactly as you would if KamiCommon were not installed. There is no conflict: KamiCommon's copy is relocated to a different package and is not on any classpath your code can reach.

If you do not need Adventure specifically

Then do not shade anything. VersionedComponent already covers building, styling, clicking, hovering and sending, on every version from 1.8.8 up. See Text and Components.

Shading rules

If you shade KamiCommon into your own jar, two things must survive:

1. internal-libs/adventure.jar must be copied through unmodified. Unpacking nested jars, or excluding internal-libs/**, produces IllegalStateException: internal-libs/adventure.jar is missing from this jar on any pre-1.18.2 server. Shadow copies it through correctly by default.
2. Do not relocate com.kamikazejam.kamicommon.nms.text.* or ...nms.bundle.*. Implementations are resolved by string name; rewriting those packages breaks the lookup.

Diagnostics

• /kc nmsversion reports what the server said and what KamiCommon parsed it as
• /kc nmsproviders reports which implementations resolved
• /kc texttest asserts on what this server's tier actually emits for every VersionedComponent operation, and prints a pass or fail line per case. See NmsAPI
• ShimLoader.leakedToParent() must return false. true means the nested jar has been unpacked into loose classes somewhere in your build chain.