Installation

Installation

KOKOTO WebChat 5.0.0 · Minecraft 1.18–26.2 · Java 17 baseline

2. Requirements and Recommended Environment

Required:

• A supported server platform: Bukkit/Paper/Spigot 1.18–26.2, Fabric exact-target 1.18.2–26.2, NeoForge exact-target 1.20.2–26.2, or a documented Forge exact target 1.18.2–26.2
• Java 17 or newer as required by the selected Minecraft server version; KOKOTO WebChat itself is compiled for Java 17
• Permission to install plugin JAR files

KOKOTO WebChat 5.0.0 declares api-version: '1.18' and compiles against spigot-api:1.18.2-R0.1-SNAPSHOT. Minecraft 1.17 and older are not claimed by this release.

Optional integrations:

• BlueMap for an embedded map chat panel
• DiscordSRV for Discord integration
• ImageEmojis-Bero 1.9.x on Bukkit/Paper-family servers for in-game rendering of KWC emoji tokens
• SimpleNicks-Bero on Bukkit/Paper-family servers for nickname display through player-display.mode: "display-name"
• Caddy or Nginx for a public HTTPS deployment

For public servers, do not expose KWC port 8899 directly to the Internet. Bind KOKOTO WebChat to 127.0.0.1:8899 and publish it through an HTTPS reverse proxy. If ImageEmojis-Bero is used, its separate resource-pack webServerPort (commonly TCP 5000) must still be reachable by Minecraft clients according to the ImageEmojis deployment model; see docs/IMAGEEMOJIS_BERO_1_9_0_EN.md.

3. Installation and First Enable

1. Put the built JAR in the server plugins/ directory.
2. Start the server once.
3. Confirm that plugins/KOKOTO-WebChat/config.yml was created.
4. A newly generated configuration uses enabled: false.
5. Review URLs, storage, retention, authentication, and upload limits.
6. Enable the features you need and set enabled: true.
7. Restart the server or run /kchat reload.

Safe initial state:

config-version: "5.0.0"
enabled: false

While disabled, the web service, chat forwarding, and cleanup tasks do not start. Administrators can still use /kchat reload.

4. Configuration Upgrade and Migration Fragment

KOKOTO WebChat preserves existing configured values by rebuilding an active-migration config from the current bundled config.yml and overlaying those values. Old comments/order/whitespace/indentation are discarded; current bundled comments and layout are authoritative.

The complete current reference is always written as:

plugins/KOKOTO-WebChat/config-reference-5.0.0.yml

It is an exact administrator-readable copy of the bundled config.yml, including comments and canonical double-quoted string scalars. It is not the migration template. /kchat reload validates YAML before any live service is stopped; invalid YAML leaves the previous running configuration active.

When config-version is missing or differs from the running plugin version, KWC performs one migration pass on the real config.yml:

• The current bundled config.yml is copied as a fresh template.
• Existing configured values are overlaid onto that template; removed settings are not copied back.
• Old comments, ordering, whitespace, indentation, and duplicate textual copies are not carried forward.
• If the old version marker is not *_auto_migration, the original config.yml is backed up before a real version upgrade.
• Existing defaults that changed in the new version are not silently replaced; they stay review items.
• The real file is marked config-version: "5.0.0_auto_migration".

KWC then writes:

plugins/KOKOTO-WebChat/config-migration-5.0.0.yml

This is a review report, not a copy/paste file for missing settings. It records the automatic insertion count, changed defaults that still need an operator decision, the exact final confirmation marker, and a comment-only current-vs-reference text diff. Because missing settings and their bundled comments are already inserted into the real config, they no longer appear as a large reference-only block at the top of the diff.

Decision rules:

Physical config.yml state	Behavior
config-version missing or older/different	Perform the migration, write 5.0.0_auto_migration, and generate/update the migration report
config-version: "5.0.0_auto_migration"	Automatic migration enabled; rebuild from the latest same-version bundled config.yml, overlay current values, and refresh the migration report/diff
config-version: "5.0.0"	Automatic migration disabled for the current version; skip same-version migration/backfill and remove stale same-version migration guidance

The marker controls migration behavior rather than review status:

# Keep same-version automatic migration enabled, even after you have reviewed the config
config-version: "5.0.0_auto_migration"

# Disable same-version automatic migration
config-version: "5.0.0"

A later real plugin-version upgrade enters the new version's _auto_migration state again.