| name | reference-cache |
| description | Use when you need authoritative Paper or Folia API/behavior for a specific Minecraft version — points to the local cache of per-version server jars (for javap) and the cached Paper/Folia developer docs, instead of guessing or going to the network. |
Local Paper/Folia reference cache
A local, gitignored cache so version-specific facts are looked up, not guessed.
reference/
├── servers/
│ ├── paper/<version>/ paperclip jar + extracted versions/<v>/*.jar (javap)
│ └── folia/<version>/ same, for Folia
└── docs/
├── paper/*.md cached Paper developer guides
└── folia/*.md cached Folia developer guides + threading model
Cached versions: Paper 1.17.1, 1.18.2, 1.19.4, 1.20.6, 1.21.4, 1.21.11,
26.1.1, 26.1.2; Folia 1.19.4, 1.20.6, 1.21.4, 1.21.11, 26.1.2. The current
ceiling is the 26.1 line (26.2 is still RC). Newer versions (26.x) live in the
PaperMC Fill v3 API (fill.papermc.io/v3); the legacy v2 API caps at 1.21.11
— fetch-reference.sh uses v3 with a v2 fallback.
Populate / refresh
scripts/fetch-reference.sh
The docs markdown is cached separately under reference/docs/ and is committed
(small, and handy to have the static references always available). The server jars
under reference/servers/ stay gitignored (large + third-party — never committed);
re-fetch them locally with the script above.
Using it
Per-version API surface (javap) — the extracted server jar is the truth:
jar=$(find reference/servers/paper/1.21.4 \( -path '*/versions/*.jar' -o -name 'patched_*.jar' \) | head -1)
javap -p -classpath "$jar" net.minecraft.world.item.ItemStack | grep -i <term>
Paper jars are mojang-mapped from 1.20.5+ (javap names are real); spigot-mapped
before (1.17.1/1.18.2/1.19.4 → route names through a remapper, don't trust the
obfuscated names). See nms-archaeology for the disassembly procedure and
cross-version-item-api for the API rename/registry breaks.
Conceptual how-to (PDC, scheduler, Folia regions, commands, components, data
components) — grep the cached docs:
grep -rl "PersistentDataContainer" reference/docs/paper/
grep -rl "EntityScheduler" reference/docs/folia/
Each cached doc has its source URL + fetch date at the top. The docs are the
prose guides (mostly version-agnostic); for the exact API of a given version use
javap on that version's jar.
When to reach for this
A version behaves unexpectedly, you need to confirm a method/field exists on a
specific version, you're choosing an API across the range, or you need the
authoritative Folia threading rules. Confirm against the cache before changing
code; encode findings as resolvers/capability probes (paper-cross-version),
never version-string branches.
