Add CLAUDE.md
Project instructions for Claude Code sessions, loaded automatically at the
start of each one.
It carries the writing rules that every page here already follows, and two
things that are not visible from the pages themselves. A push is live with no
review and no undo. And this repository's source tags cannot be used to
establish history: they are dependency-bot artifacts and do not match their
names, which nearly produced a confident and wrong correction to a page that
was right.
Co-Authored-By: Claude Code <noreply@anthropic.com>
3bec7f3
hoverItem works on every supported version
Three pages still said it throws on 1.17 through 1.18.1. That gap closed when
ItemNbtProvider gained those two tiers, and VersionedComponent's javadoc now
reads "Supported on every version from 1.8".
The Damage limitation below 1.13 is unaffected and stays on both pages that
carry it.
Co-Authored-By: Claude Code <noreply@anthropic.com>
b1f6efa
Item text is written upright without a decoration call
KamiCommon suppresses the default italic on custom item names and lore, so the
guidance to turn it off by hand described work the library now does. The
example taught a call that has no effect.
Only the unset case is suppressed, so an explicit request for italics is
honoured, which the replacement says.
Co-Authored-By: Claude Code <noreply@anthropic.com>
5332077
State the pre-Java-8 declarations per module, from published metadata
Read org.gradle.jvm.version out of the published Gradle module files rather
than inferred from build scripts. spigot-jar and spigot-utils declared 21, not
17, which is what a Spigot plugin resolves, so every alpha before alpha.40
needed a JDK 21. Only shared-utils, shared-jar, standalone-utils and
standalone-jar declared 17.
The alpha.37 to alpha.39 jump to 25 is spigot-jar alone. spigot-utils stayed
at 21 across all three, which the previous wording got wrong.
Co-Authored-By: Claude Code <noreply@anthropic.com>
f0230f6
Give the pre-Java-8 declarations per module
The alpha.20 to 5.0.0 guide said every module previously declared 17. That is
true only of shared-utils, shared-jar, standalone-utils and standalone-jar,
which inherited the root toolchain. spigot-utils and spigot-jar apply
paper-toolchain-convention and declared 21, then 25 from alpha.37.
The claim contradicted the warning four lines below it, which names 25, and the
version table on the Java Versions page.
Co-Authored-By: Claude Code <noreply@anthropic.com>
8299c7d
Document hoverItem and texttest, and drop the immutable-prototype claim
Nine places said the ItemBuilder prototype is immutable. The reference is final
and the ItemStack is not: the constructor stores the stack it is given without
copying, and getPrototype() returns that same instance, so mutating it changes
every item the builder produces. Checked at pre-v5.0.0-alpha.18 as well, where
the constructor and getter are byte for byte the same, so the alpha.17 page was
not period-accurate either and is corrected rather than left alone.
VersionedComponent#hoverItem had no page at all. Two constraints decide whether
a plugin using it works, so both are stated where a reader meets the method:
it throws on 1.17 through 1.18.1, which have neither the pre-1.17 item NBT nor
an Adventure of their own, and on 1.8 through 1.12 the hover carries id, count
and tag alone, so a top-level Damage value has nowhere to go and red wool
hovers as white. Name, lore and enchantments are inside tag and survive. The
Text page also now says hovers and clicks arrive below 1.18.2, where the
component is handed to the server's own bungee-chat.
/kc texttest is documented beside the other diagnostics on the NmsAPI page,
both modes: the console assertions with their PASS, FAIL and RESULT lines, and
the player pass that answers the question a wire assertion cannot.
Four gaps that the code is now correct enough to describe: the glow methods
and what setGlow(false) does not do, the two drag toggles and their true
defaults, the space-to-underscore rule for modules.<name> and features.<name>,
and the plugins/<plugin>/internal/adventure.jar path a server owner sees below
1.18.2, on both pages that describe the nested jar without saying where it goes.
Co-Authored-By: Claude Code <noreply@anthropic.com>
2615495
Drop two v4 migration entries for private constructors
The v4 to v5 guide listed KamiConfig(JavaPlugin, File, boolean, Supplier) and
ItemBuilder() under removed APIs. Both were private at tag 4.0.0
(KamiConfig.java:60, and ItemBuilder.java:19, the latter marked "Private for
Clone"), so no consumer could have called either and neither removal is a
migration step. The public KamiConfig(JavaPlugin, File, Supplier<InputStream>)
is unchanged in v5, so the entry costs a reader time without telling them
anything.
These were the last two items outstanding from the v5 folder audit. The
alpha.17 page keeps its ItemBuilder() entry, which that page's own finding
asked to correct rather than drop.
Co-Authored-By: Claude Code <noreply@anthropic.com>
c83d27c
Fix 35 errors the v5 folder audit found
The audit was weighted toward the four migration pages, which had never had a
claim-by-claim check, and that is where 31 of the 35 were. The thirteen topic
pages, audited twice already, contributed three.
The largest cluster was a block copy-pasted from the alpha.17 page into the v4
guide without converting it to v4 coordinates. It named AbstractSubsystem and
FeatureManager, neither of which exists at tag 4.0.0, and the subsystem.integration
package, which was modules.integration in v4. I verified all three against the tag
before changing them.
One entry was stale rather than wrong: AbstractSubsystem stopped being a
LoggerService at alpha.26, so the suggested replacements for Module log, warn and
error no longer compile on a subsystem. They now route through getLogger, which
also resolves a contradiction with the Subsystems page.
Six accessors in New APIs lost their Mini suffix when alpha.26 converted the config
classes to MiniMessage. Several v4 signatures were wrong in arity or type:
getItemBuilder took one parameter not two, Txt getPage took six not five,
addEnchant not addEnchantment, and getUnbreakable returned a TriState rather than a
boolean, which the page presented as a rename alone.
Also corrected: the ICachedConfig section attributed two KamiConfig renames to the
wrong class, two handler sections named YamlHandler where the class is
YamlHandlerStandalone, StandaloneConfigExt was credited with constructors it does
not have on two pages, and the Java Versions page claimed nothing but HikariCP sits
above the floor while the build's own inventory pins 163 NMS classes there.
Co-Authored-By: Claude Code <noreply@anthropic.com>
c05fb1f
Fix seven errors the third verification pass found
The Database example did not compile. It called getLogger(), which Database does
not have: the class implements DatabaseListener and its whole surface is the
constructor, shutdown, getConnection, three final callbacks and the two abstract
log methods. shared-jar has no Bukkit either, so JavaPlugin's logger was not in
scope by any route. The example now brings its own java.util.logging.Logger and
the page says why.
The shading page omitted commons-lang3 from the list of transitives a spigot-utils
consumer must relocate. It arrives through commons-text, which declares it at
compile scope, and spigot-jar relocates it under its own spigot-utils heading. A
reader relocating exactly the seven listed would have shipped it unrelocated,
which is the collision that paragraph exists to prevent.
EntityMethodsPre_1_13 was listed as removed. It is in the published spigot-nms
1.2.32 jar at 6260 bytes and on every consumer's compile classpath; it left the
documented api surface and the aggregated javadoc, which is not the same thing.
MaterialData and EventManager really are absent, so those rows stand.
Four signatures named KMessageSingle where v5 takes VersionedComponent, on
CommandPaging.getPage and setHelpComments, which contradicted the KamiCommand page
getting it right. CommandPage should have been CommandPaging in two places. Txt
titleizedPageTitle lost its List args parameter in alpha.50 and the page had not
caught up. And the subsystem failure note quoted only the module log line, while
FeatureManager logs "Can not register the feature", so a reader whose feature was
silently absent would have grepped for a string that never appears.
Co-Authored-By: Claude Code <noreply@anthropic.com>
61c0d44
Track alpha.51 and alpha.52 in the docs
icons is no longer marked required in the menu configuration page, and the callout
saying a section without it throws is gone. alpha.51 reverted that: a menu section
without an icons block loads normally and has no icons beyond the filler, which is
a reasonable way to define a decorative menu. Verified against the published jar
rather than the release note, since alpha.50's loader carried the exception and
its message strings and alpha.51's does not.
The alpha.20 to 5.0.0 guide gains the two config changes from alpha.52. The
unbreakable and hide-attributes keys were read through a check that could never
return true, so both were silently ignored and now apply, which also means
hide-attributes false can finally suppress the global default on a menu icon. And
a subsystem config key now normalises spaces to underscores for features as well
as modules, which only moves a key for a subsystem whose name contains a space.
Co-Authored-By: Claude Code <noreply@anthropic.com>
f1cd777
Correct the topic pages against the source
A verification pass traced every claim on the seven topic pages back to code.
Twenty-eight corrections, grouped by what went wrong.
Four notes labelled "Migrating from v4" described changes that were actually v3 to
v4, so a v4 reader was told to fix code that already compiles: perform() gaining
its CommandContext parameter, the addParameter overloads collapsing into the
builder, the registration helpers becoming plural, and the menu package moving out
of gui. All four were already in place at tag 4.0.0. I wrote them from the v3
pages without checking which version introduced them.
Two claims were inverted. defaultCommentsOverwrite reads the other way round: true
lets the server-side comment win, not the bundled one. And sequences do not throw
on write; a read of a sequence whose entries are mappings throws, which also means
building a config with defaults over such a file throws from the constructor.
Three were stale, already fixed by earlier releases: data being ignored for
multi-material icons, an nbt block being skipped without warning, and a bad
material in a list vanishing silently.
The rest are ordinary errors of fact. SimpleMenu's extra constructor takes three
arguments rather than four and exists only in the MenuSize flavour. OneClickMenu's
used-click flag is reset by open() alone, not by reopenMenu. Nothing closes a
OneClickMenu automatically. The materials and types list keys are read by
MenuIconLoader only, so a plain ItemBuilder.load of a section defining materials
throws. An invalid inventory type is ignored silently rather than warned about.
getLabel drives the help title but not the page-flip arrows, which build from
aliases. CachedConfig is abstract. getFile and save moved on AbstractConfig and
MemorySectionMethods, not on the handler. amount is coerced from a quoted string
after all, and hideAttributes' flag rename is a no-op because XSeries maps both
names to one flag.
Two pages now say what actually happens when a subsystem cannot resolve its
config: the failure is caught and logged by the subsystem manager, so the plugin
enables and the subsystem simply never runs.
Co-Authored-By: Claude Code <noreply@anthropic.com>
ac5cc6a
Catch the last two instances of the same construction
My grep on the previous commit was too narrow and missed "Returning a value is
what lets you swap the prototype" and "The nesting is what makes this hold".
Co-Authored-By: Claude Code <noreply@anthropic.com>
489f7c1
Replace the "is what X uses" construction with direct statements
Six sentences built a fact as a relative clause hanging off another fact instead
of stating it. "getLabel() is new in v5 and is what the help title and page-flip
arrows use, so a command reached through two aliases produces the right text for
each" now reads "getLabel() is new in v5. It is used internally for the help title
and the page-flip arrows, so a command reached through two aliases renders
correctly under each one."
The same shape appeared on the Java Versions, Menus, Menu Configuration,
Subsystems and New APIs pages. All rewritten to name the subject and use a plain
verb.
Co-Authored-By: Claude Code <noreply@anthropic.com>
0333267
Stop narrating how the design was arrived at
Several pages reported on investigation rather than explaining behaviour. The
Adventure page said the nested jar "is not an oversight to work around", that
shading flat "made it importable by every consumer", and that "a consumer compiled
against it successfully even with the dependency declared runtime-only". That is a
description of an experiment. A reader needs the rule, which is that scope
metadata cannot conceal bytes physically present in a jar, and that nesting also
survives them shading KamiCommon themselves.
The Database page carried a post-mortem on a v4 property map that never took
effect. It now states what applies today, with the v4 correction moved into a
clearly marked migration note for anyone who believed SSL was disabled.
Also removed: "v4 hardcoded the relocated name, which failed for non-shaded
consumers", "v4 had no way to close it at all", "v4 threw on every 26.x server",
"this changed in v4 and catches people out", and a note in the migration guide
explaining what an earlier revision of that same page used to say.
Comparisons with v4 inside migration callouts are kept. That is what a migration
guide is for, and an upgrading reader needs them.
469837f
Drop the em dashes, and stop discouraging a supported shading path
Ninety-six em dashes across seventeen pages, plus four en dashes in version
ranges and a handful of filler words. All removed, rewritten as periods, commas
or restructured sentences rather than swapped for another dash. The formal,
informative tone and the existing page structure are unchanged.
The Spigot module guidance was also wrong in framing. It presented spigot-utils
and spigot-jar as two deployment models where one was recommended and the other
merely tolerated, and said outright that spigot-jar "can be shaded, but you
inherit all 19 MB". Shading spigot-jar is a supported path that works when wired
up correctly, and the page now says so.
There are three options, not two: shade spigot-utils for a smaller payload,
depend on spigot-jar when the plugin is already installed on the server, or shade
spigot-jar to take the whole toolkit in one dependency with no relocation work.
The third gets its own section with the PluginSource wiring, and the Getting
Started decision table gets a third row.
Co-Authored-By: Claude Code <noreply@anthropic.com>
ee0add3
Document v5: entry pages, topic pages, and the changes since alpha.20
The v5 section had no topic pages at all. Its only feature documentation was the
nine v3 pages, which teach APIs that v4 and v5 both replaced, so anyone following
the only documentation that existed wrote code that did not compile. Getting
Started was a placeholder reading "API documentation and getting started content
will be added here".
Fifteen new pages. Three cover setup: how to depend on the library, which of the
six modules to pick, what shading obliges you to do, and the Java 8 floor with its
one Java 11 exception. Seven replace the v3 topic pages for KamiPlugin,
KamiCommand, menus, menu configuration, ItemBuilder, configuration and subsystems.
Five cover ground the wiki has never had in any version: the VersionedComponent
text API, which Adventure a server actually uses and where the 1.18.2 boundary
falls, NmsAPI, Redis and Database.
The migration guide had three entries that were actively wrong rather than
missing. It told readers to update imports to three integration classes that a
later section of the same page said were removed. It presented MaterialData to
XMaterialData as a rename when five things differ, one of them silently because
XMaterialData has no equals or hashCode. And it named the EventManager removal
without saying that no replacement exists, so the seven lines of removed logic are
now published for reimplementation. Four omitted changes were added, of which
AbstractBlockUtil.setBlock is a hard compile break.
Everything after alpha.20 was documented nowhere. Readers coming from 4.0.0 are
routed to the topic pages, since for them it is new capability rather than
renames. Readers who tracked the pre-releases get a dedicated alpha.20 to 5.0.0
guide covering the whole window.
Written as though 5.0.0 is live, so no dated stamps outside the historical
alpha.17 page, version placeholders rather than hardcoded numbers, and the Home
status no longer says active development.
A review against the source caught nineteen defects before this landed, most of
them examples that would not compile: the shading bootstrap was wrong on three
pages, registerModule was documented taking a class when it takes an instance, and
ConfigObserver's package was wrong everywhere it appeared. All are corrected here.
Every internal link and cross-page anchor is verified, including three v3 links
that were missing their v3 prefix.
Co-Authored-By: Claude Code <noreply@anthropic.com>
8952b47
- update for new APIs
Took 2 minutes
e7c3e02
- update new-apis sidebar
Took 1 minute
392106a
- update last updated tracker
Took 1 minute
d7f21ed
- sidebar updates for alpha.17
Took 4 minutes
9941da2
- updates for alpha.17
Took 1 hour 19 minutes
bfae919
new-api updates
Took 12 minutes
f617e4a
- updates for alpha.16
Took 2 minutes
ede89c8
- mention nms changes
Took 4 minutes
20cba2b
- fix anchor
Took 3 minutes
013e5b8
- fix a few anchors
Took 4 minutes
5fbe599
- better v5 getting started landing page.
Took 3 minutes
6397ad2
- v5 migration guides sidebars
Took 12 minutes
4101ffe
- v5 Changes Summary complete
Took 11 minutes
f23700c
- v5 New APIs Formatting
Took 2 minutes
eb3ad44