Run any Skill in Manus with one click

paper-cross-version

Stars0

Forks0

UpdatedJuly 2, 2026 at 04:25

Use when writing or changing code that must run across StarEnchants' whole Paper range (1.17.1 → 26.1.x) — API selection, version-gated features, reflection, the 1.20.5 mapping flip, enum→registry breaks, or Java toolchains.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

owengregson

owengregson/StarEnchants

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	paper-cross-version
description	Use when writing or changing code that must run across StarEnchants' whole Paper range (1.17.1 → 26.1.x) — API selection, version-gated features, reflection, the 1.20.5 mapping flip, enum→registry breaks, or Java toolchains.

Cross-version Paper development (1.17.1 → 26.1.x)

This skill covers the modern range (1.17.1 floor → 26.1.x ceiling). For the 1.8.9 tree — the -Pse.target=legacy overlay, JvmDowngrader, the mega-jar, and its live gates — see the legacy-1.8.9 skill; it is a separately-compiled tree, not a point in this range.

The compilation model

core compiles against the floor API (paper-api 1.17.1) so the common path is binary-safe everywhere. Anything needing a newer API lives in a compat-* module loaded behind runtime feature detection (a Capabilities probe), e.g. compat-folia, compat-brigadier.
One universal shaded jar serves the whole range. api-version: '1.17' in plugin.yml.
Class-file target: Java 17 — a deliberate choice (1.17.1 itself only required Java 16, but Java 17 runs everything ≤ 1.20.4). 1.20.5+ requires Java 21 (CI runs 25). The integration build provisions per-version toolchains.

Rules of thumb

Feature-detect at runtime; never branch behavior on a parsed version string when a capability probe works.
Decide version-dependent behavior ONCE at load/enable, not per event or per item. Cache the resolved choice.
Reflection helpers try the Mojang name through the remapper FIRST, then the raw/legacy name, and degrade gracefully when a member genuinely doesn't exist on a version.
Treat "constant/field stopped existing" as a candidate rename or relocation, not a deletion — confirm with nms-archaeology, never guess.

Known binary breaks in the range (absorbed by resolvers)

1.20.5 — the mapping flip. Runtimes are Mojang-mapped from 1.20.5, spigot-mapped before. Any reflection must route names through a reflection-remapper (identity on modern, reobf data parsed ONCE per JVM — expensive). See nms-archaeology.
1.20.5 — registry renames of Enchantment / PotionEffectType / Particle / many enums to match vanilla (e.g. DAMAGE_ALL→sharpness, PROTECTION_ENVIRONMENTAL→protection, CONFUSION→nausea, FAST_DIGGING→haste, VILLAGER_HAPPY→happy_villager). EE/EA configs use the OLD names — resolve by name with legacy aliases. See cross-version-item-api.
1.21.3 — Attribute changed from an enum with GENERIC_* constants to a registry-backed interface with unprefixed constants — a break in BOTH directions. Resolve constants by name once at class load (modern spelling first, then legacy).
Type-shape changes (exact versions). Enchantment became an abstract class (registry-backed) at 1.20.5; Attribute and Sound became interfaces at 1.21.3 (Attribute also dropped its GENERIC_ prefix). Particle was RENAMED at 1.20.5 but is still a plain enum. Never store any of these as a compile-time constant in a field — resolve by name through the platform resolver (cross-version-item-api).
PDC (PersistentDataContainer) has existed since 1.14 — present across our entire 1.17.1+ range and the item-state storage of record. Avoid the ItemMeta enchant helpers whose signatures shifted at the 1.20.5 flip; go through PDC + the Enchantment resolver.

When adding a matrix version

Update integrationTestVersions in gradle.properties, check the Java boundary in core/build.gradle.kts, and expect the gradle task to download/cache the paperclip jar the integration matrix reuses. See matrix-gate.

More from this repository

same repository

matrix-gate

owengregson/StarEnchants

Use when running or verifying StarEnchants' test gate — which commands to run, the Paper+Folia version matrix, concurrency rules for booting many servers, and how to read results honestly instead of trusting a success banner.

2026-07-190

effect-engine

owengregson/StarEnchants

Use when implementing or modifying the runtime engine — stateless systems, the activation pipeline and gate order, effect/condition/trigger/selector kinds, the Ability record, the Sink, declared Affinity, the dispatch plan, or how one activation executes.

2026-07-110

item-data-model

owengregson/StarEnchants

Use when working on item state, the PDC codec, the ItemView content-hash cache, the stable-key to dense-id map, component stores, the WornState resolver, lore/name rendering, or legacy item migration.

2026-07-110

starenchants-conventions

owengregson/StarEnchants

Use when writing or reviewing ANY code in the StarEnchants repo — the design principles, engine boundaries, threading/Folia rules, config snapshot pattern, extensibility pattern, and the invariants every change must preserve.

2026-07-030

performance-hot-paths

owengregson/StarEnchants

Use when writing or reviewing code on the combat or item hot path, declaring an effect Affinity, touching the Sink/Dispatcher, the ItemView cache, interning, or anything the ArchUnit/CI lint or the JMH bench guards.

2026-07-030

config-and-migration

owengregson/StarEnchants

Use when working on the config schema/YAML, the DSL and ParamSpec, the compiler (resolve/typecheck/lower/erase/snapshot), diagnostics, transactional reload, catalog validation, or the EE/EA/AE and legacy-config migrator.

2026-07-030

name	paper-cross-version
description	Use when writing or changing code that must run across StarEnchants' whole Paper range (1.17.1 → 26.1.x) — API selection, version-gated features, reflection, the 1.20.5 mapping flip, enum→registry breaks, or Java toolchains.

Cross-version Paper development (1.17.1 → 26.1.x)

The compilation model

core compiles against the floor API (paper-api 1.17.1) so the common path is binary-safe everywhere. Anything needing a newer API lives in a compat-* module loaded behind runtime feature detection (a Capabilities probe), e.g. compat-folia, compat-brigadier.
One universal shaded jar serves the whole range. api-version: '1.17' in plugin.yml.
Class-file target: Java 17 — a deliberate choice (1.17.1 itself only required Java 16, but Java 17 runs everything ≤ 1.20.4). 1.20.5+ requires Java 21 (CI runs 25). The integration build provisions per-version toolchains.

Rules of thumb

Feature-detect at runtime; never branch behavior on a parsed version string when a capability probe works.
Decide version-dependent behavior ONCE at load/enable, not per event or per item. Cache the resolved choice.
Reflection helpers try the Mojang name through the remapper FIRST, then the raw/legacy name, and degrade gracefully when a member genuinely doesn't exist on a version.
Treat "constant/field stopped existing" as a candidate rename or relocation, not a deletion — confirm with nms-archaeology, never guess.

Known binary breaks in the range (absorbed by resolvers)

1.20.5 — the mapping flip. Runtimes are Mojang-mapped from 1.20.5, spigot-mapped before. Any reflection must route names through a reflection-remapper (identity on modern, reobf data parsed ONCE per JVM — expensive). See nms-archaeology.
1.20.5 — registry renames of Enchantment / PotionEffectType / Particle / many enums to match vanilla (e.g. DAMAGE_ALL→sharpness, PROTECTION_ENVIRONMENTAL→protection, CONFUSION→nausea, FAST_DIGGING→haste, VILLAGER_HAPPY→happy_villager). EE/EA configs use the OLD names — resolve by name with legacy aliases. See cross-version-item-api.
1.21.3 — Attribute changed from an enum with GENERIC_* constants to a registry-backed interface with unprefixed constants — a break in BOTH directions. Resolve constants by name once at class load (modern spelling first, then legacy).
Type-shape changes (exact versions). Enchantment became an abstract class (registry-backed) at 1.20.5; Attribute and Sound became interfaces at 1.21.3 (Attribute also dropped its GENERIC_ prefix). Particle was RENAMED at 1.20.5 but is still a plain enum. Never store any of these as a compile-time constant in a field — resolve by name through the platform resolver (cross-version-item-api).
PDC (PersistentDataContainer) has existed since 1.14 — present across our entire 1.17.1+ range and the item-state storage of record. Avoid the ItemMeta enchant helpers whose signatures shifted at the 1.20.5 flip; go through PDC + the Enchantment resolver.