KOKOTO WebChat (Fabric, Forge, NeoForge)

# KOKOTO WebChat

KOKOTO WebChat 5.3.3 is a compatibility-preserving maintenance update to the finalized 5.3.2 baseline. Relay remains protocol 2.2 and the configuration schema remains 5.3.0. This release focuses on notification lifecycle/visibility correctness, server-hosted offline Help, upload-retention semantics, desktop private-window presentation fixes, version/reporting consistency, and Forge 26.3 activation.

KOKOTO WebChat is a server-side Minecraft web chat for **Bukkit/Paper/Spigot 1.18–26.3 (Java 17), Fabric exact targets 1.18.2–26.3, NeoForge exact targets 1.20.2–26.3, and Forge exact targets 1.18.2–26.3; mod-loader targets select Java 17/21/25 by Minecraft version**. It can run as a standalone web chat or embed into supported map frontends including BlueMap, squaremap, Dynmap, Pl3xMap, LiveAtlas, uNmINeD, and Minecraft Overviewer. No client mod is required for the core chat features.

## What's new in 5.3.3

- **Exact-message notification acknowledgement**: Public, DM, and Group notifications are read or removed as soon as their exact target message is actually visible. The same guarded check runs after canonical inbox sync, post-render retries, foreground/focus changes, mobile `visualViewport` changes, resize, and orientation changes.
- **Deleted-message notification cleanup**: deleting a Public, DM, or Group message removes the notification-inbox row targeting that exact message, including cross-server DM deletion and stale persisted rows.
- **Offline/local Help**: User settings → Help opens bundled en/ko/ja/zh-CN documentation directly from the KWC server. Unsupported locales fall back to English, and administrators may install custom `docs/<locale>/` Markdown translations. Real local screenshot assets are supported without remote image hotlinking.
- **Notification settings clarification**: signed-in notification categories and keywords are account-wide, while browser Notification permission and Web Push registration remain browser/device specific.
- **Upload-retention correctness**: `upload.retention-days` is an actual age limit; public and Group pinned-message snapshots can preserve referenced uploads when `pinned.preserve-uploads` is enabled; periodic cleanup also runs on long-lived servers.
- **Desktop DM/Group presentation fixes**: touch-capable desktop systems are no longer misclassified as mobile only because they expose multiple touch points. Standalone desktop multi-window behavior remains available, and DM/Group sender/body typography matches public chat without changing timestamp/status sizing.
- **Presence count correctness**: the online count uses the UUID-deduplicated union of Game and Web presence.
- **Pin/unpin confirmation and Filter Save placement**: public/Group pin and unpin mutations ask for confirmation; Filter settings use the shared admin-header Save action.
- **Product/config version separation**: `release-version: "5.3.3"` is the managed product display, while `config-version: "5.3.0"` remains the independent configuration-schema/migration marker. Loader runtime/version reporting is synchronized to 5.3.3.
- **Forge 26.3 support**: Forge 26.3 is an active exact target pinned to Forge `66.0.3` with Java 25. The release matrix is **48 artifacts**: Bukkit 1 + Fabric 17 + NeoForge 13 + Forge 17.
- **Build/release polish**: Windows target progress counts match the 48-artifact matrix, Gradle/JDK bootstrap downloads report progress with bounded timeouts, and current release documentation/metadata are synchronized.

## Main features

- **Two-way game ↔ web chat** with linked Minecraft accounts and optional guest chat
- **BlueMap addon + standalone page** with dark/light/high-contrast UI, PIP, draggable/resizable windows, search, replies, pins, and virtual scrolling
- **1:1 direct messages** with local and cross-server recipients, exact server+UUID routing, retry-safe delivery, unread/read state, and shared game/web threads
- **Group chat rooms** with public/private visibility, invitations, passwords, retention limits, unread counts, delivery retry protection, and member management
- **Relay Protocol 2.2** for multi-server communities with explicit groups, reciprocal peers, independent per-peer send/receive policy, HKDF-SHA256/AES-256-GCM hop-by-hop protection, authenticated responses, replay/loop defenses, server badges and source filters
- **DiscordSRV integration** plus Discord media caching and optional emoji-link augmentation
- **Uploads and rich previews** for images, video, audio, YouTube/Shorts, with optional TikTok and X/Twitter embeds
- **Deterministic long-history virtual scrolling** across images, GIFs, video, audio, YouTube/iframes and link previews, with scroll-anchor correction as media sizes settle
- **Unicode-aware content filtering** for public/group chat and optional DM with Block/Mask/Replace, bulk word lists, custom rules, anti-evasion matching and Web Admin testing
- **Custom emoji management** with multi-file administrator upload, plus optional **ImageEmojis-Bero** Bukkit/Paper integration using the same `plugins/KOKOTO-WebChat/emojis` tree; its resource-pack HTTP port remains a separate client-facing service
- **SimpleNicks-Bero nickname integration** on Bukkit/Paper-family servers through `player-display.mode: "display-name"`, while KWC retains the real linked account identity
- **Configurable message tokens** such as `:enter:` / `:newline:` / `:tab:` with administrator-localizable aliases and printable custom substitutions
- **Web Push / keyword notifications** and administrator update notifications
- **Per-account visual UI profiles** plus account-synced keyword/notification preferences for signed-in users; device-local window state and Push endpoints stay local
- **Administrator Discord keyword alerts** with KWC-owned matching/deduplication and DiscordSRV logical-channel selection
- **Administration and moderation tools** for message deletion, pins, guest/IP mutes, session revocation, user restrictions, custom emoji management, and private-chat metadata
- **Optional read-only DM and group-chat body audit** for explicitly allowlisted super administrators; both are disabled by default and every audit page read is logged
- Built-in UI languages: **English, Korean, Japanese, Simplified Chinese**

## Private messaging and delivery reliability

Cross-server DM targets are identified by **server ID + player UUID**, so a local player cannot be confused with a same-name player on another server. Remote messages stay pending until the destination confirms storage. Failed or uncertain sends can be retried with persistent relay/client message IDs without duplicating sender or receiver records.

DM and group-chat message state is shown compactly beside the timestamp. Normal successful delivery is silent; pending or failed delivery is shown only when needed. DM messages use a short unread label until the recipient reads them, then show `✓`. Group messages show the number of recipients who have not read the message and change to `✓` when everyone has read it.

## Multi-server relay

Relay Protocol 2.2 carries public chat and cross-server DM/read/delete flows inside explicit trust groups and capability-gates public reactions/typing, chat-event routing, and remote public-profile lookup while keeping Protocol major 2 as the wire-compatibility boundary. Each group has one shared secret; peers have no individual secret and must be configured reciprocally in the same group. Every message request authenticates/encrypts itself independently. `/relay/v2/handshake` is a stateless diagnostic identity/health probe and does not control routing. Messages use directional HKDF-SHA256 keys and AES-256-GCM hop-by-hop authenticated encryption; responses are HMAC-authenticated and timestamp/nonce/relay-ID/hop defenses reject replay or loops.

Each peer keeps `enabled` as a master switch and may independently configure `send` and `receive` for `public-chat`, `event`, `dm`, and `profile`. Missing entries default to enabled for compatibility. KWC Chat Events use the distinct `event` source rather than ordinary `system`, so remote event announcements can be rejected without suppressing unrelated system notices. Public reaction/typing follow `public-chat`; DM reaction/typing/read/delete follow `dm`.

Direct one-hop HTTP can be used with an explicit warning because relay payloads remain encrypted/authenticated. Forwarding filtering is per peer: an HTTP peer is excluded only as that forwarding hop, while other HTTPS peers in the same group remain eligible. Relay Protocol 2.2 is not end-to-end encryption: forwarding servers decrypt and re-encrypt as trusted participants. Legacy Relay v1 endpoints return HTTP 426.

On the first upgrade from 5.0.0, old flat relay settings are not converted into guessed groups. Relay is reset disabled so the operator can explicitly define the v2 trust groups before re-enabling it.

## Administrator private-chat audit

Private message bodies are not automatically exposed to normal administrators. Optional audit access requires an exact Minecraft name/UUID in `private-chat-super-admins` **and** the corresponding feature switch:

```yaml
direct-message:
  admin-audit:
    enabled: false

group-chat:
  admin-audit:
    enabled: false
```

Audit views are read-only. Group audit does not join the room or affect read/unread state. Every audit page read records the actor and pagination metadata without copying message bodies into the audit log.

## Deployment

Fresh configurations start with the plugin master switch disabled so operators can review storage, authentication, uploads, retention, and web exposure before enabling it. The bundled `config.yml` is the sole migration template. On a real version migration, KOKOTO WebChat first starts from that latest bundled default and overlays the operator values read from the existing `config.yml`; old comments, ordering, blank-line layout, and indentation are not carried forward. A previously fixed older config (a marker without `_auto_migration`) is backed up before reconstruction. The migrated file is marked `<version>_auto_migration`; while that marker remains, startup/reload repeats the same bundled-default reconstruction with the current values overlaid, keeping newly added settings and bundled comments/layout current. An exact same-version marker stops same-version automatic setting reconstruction; changing `ui.language` may still rebuild only comments/layout while preserving parsed values. `config-reference-<version>.yml` is the administrator-readable current default rendered in the same built-in `ui.language` (English for custom/unsupported UI languages) and is not a migration input. Older generated reference/migration files are removed automatically. `/kchat reload` validates edited YAML before stopping live services; invalid YAML is rejected so the previous running configuration, UI language, and services remain active. Bundled UTF-8 starter filter-word lists for Korean, English, Japanese, and Simplified Chinese are initialized once when the starter-list marker is absent; existing or disabled files are preserved, and administrator deletions after initialization are not reversed.

For public deployments, placing BlueMap and KOKOTO WebChat behind HTTPS with Caddy or Nginx is recommended.

## Optional integrations

- BlueMap (Bukkit plus BlueMapAPI on Fabric/NeoForge 26.1.2/26.2/26.3 and Forge 26.1.2/26.2/26.3)
- squaremap and Dynmap filesystem web adapters
- Pl3xMap on Bukkit/Paper-family and Fabric
- LiveAtlas, uNmINeD, and Minecraft Overviewer static-web adapters
- DiscordSRV on Bukkit
- ImageEmojis-Bero on Bukkit/Paper-family servers (shared KWC emoji path + runtime glyph resolution); general ImageEmojis operation follows the upstream plugin documentation
- SimpleNicks-Bero on Bukkit/Paper-family servers through Bukkit display names; general SimpleNicks operation follows the upstream plugin documentation
- Web Push notifications

See the bundled README and `docs/` folder for full configuration, reverse-proxy, relay, security, migration, and troubleshooting guides.

## AI assistance disclosure

Generative AI was used as a development assistant for code review, implementation and patching, documentation drafting, and multilingual translation. Project requirements, architecture/design decisions, integration, testing, compatibility verification, release validation, and final acceptance are human-directed and reviewed. AI-assisted output is reviewed and validated before inclusion.

KOKOTO WebChat

KOKOTO WebChat 5.3.3 is a compatibility-preserving maintenance update to the finalized 5.3.2 baseline. Relay remains protocol 2.2 and the configuration schema remains 5.3.0. This release focuses on notification lifecycle/visibility correctness, server-hosted offline Help, upload-retention semantics, desktop private-window presentation fixes, version/reporting consistency, and Forge 26.3 activation.

KOKOTO WebChat is a server-side Minecraft web chat for Bukkit/Paper/Spigot 1.18–26.3 (Java 17), Fabric exact targets 1.18.2–26.3, NeoForge exact targets 1.20.2–26.3, and Forge exact targets 1.18.2–26.3; mod-loader targets select Java 17/21/25 by Minecraft version. It can run as a standalone web chat or embed into supported map frontends including BlueMap, squaremap, Dynmap, Pl3xMap, LiveAtlas, uNmINeD, and Minecraft Overviewer. No client mod is required for the core chat features.

What's new in 5.3.3

• Exact-message notification acknowledgement: Public, DM, and Group notifications are read or removed as soon as their exact target message is actually visible. The same guarded check runs after canonical inbox sync, post-render retries, foreground/focus changes, mobile visualViewport changes, resize, and orientation changes.
• Deleted-message notification cleanup: deleting a Public, DM, or Group message removes the notification-inbox row targeting that exact message, including cross-server DM deletion and stale persisted rows.
• Offline/local Help: User settings → Help opens bundled en/ko/ja/zh-CN documentation directly from the KWC server. Unsupported locales fall back to English, and administrators may install custom docs/<locale>/ Markdown translations. Real local screenshot assets are supported without remote image hotlinking.
• Notification settings clarification: signed-in notification categories and keywords are account-wide, while browser Notification permission and Web Push registration remain browser/device specific.
• Upload-retention correctness: upload.retention-days is an actual age limit; public and Group pinned-message snapshots can preserve referenced uploads when pinned.preserve-uploads is enabled; periodic cleanup also runs on long-lived servers.
• Desktop DM/Group presentation fixes: touch-capable desktop systems are no longer misclassified as mobile only because they expose multiple touch points. Standalone desktop multi-window behavior remains available, and DM/Group sender/body typography matches public chat without changing timestamp/status sizing.
• Presence count correctness: the online count uses the UUID-deduplicated union of Game and Web presence.
• Pin/unpin confirmation and Filter Save placement: public/Group pin and unpin mutations ask for confirmation; Filter settings use the shared admin-header Save action.
• Product/config version separation: release-version: "5.3.3" is the managed product display, while config-version: "5.3.0" remains the independent configuration-schema/migration marker. Loader runtime/version reporting is synchronized to 5.3.3.
• Forge 26.3 support: Forge 26.3 is an active exact target pinned to Forge 66.0.3 with Java 25. The release matrix is 48 artifacts: Bukkit 1 + Fabric 17 + NeoForge 13 + Forge 17.
• Build/release polish: Windows target progress counts match the 48-artifact matrix, Gradle/JDK bootstrap downloads report progress with bounded timeouts, and current release documentation/metadata are synchronized.

Highlights

• 5.0.0 multi-platform architecture: shared behavior lives in kwc-core; Bukkit, Fabric, NeoForge, and Forge provide loader-specific server integration while reusing the same core and frontend/adapters
• Two-way game ↔ web chat with linked Minecraft accounts and optional guest chat
• BlueMap addon + standalone page with dark/light/high-contrast UI, PIP, draggable/resizable windows, search, replies, pins, and virtual scrolling
• 1:1 direct messages with local and cross-server recipients, exact server+UUID routing, retry-safe delivery, unread/read state, and shared game/web threads
• Group chat rooms with public/private visibility, invitations, passwords, retention limits, unread counts, delivery retry protection, and member management
• Relay Protocol 2.2 for multi-server communities with explicit groups, reciprocal peers, independent per-peer send/receive policy, HKDF-SHA256/AES-256-GCM hop-by-hop protection, authenticated responses, replay/loop defenses, server badges and source filters
• DiscordSRV integration plus Discord media caching and optional emoji-link augmentation
• Uploads and rich previews for images, video, audio, YouTube/Shorts, with optional TikTok and X/Twitter embeds
• Deterministic long-history virtual scrolling across images, GIFs, video, audio, YouTube/iframes and link previews, with scroll-anchor correction as media sizes settle
• Unicode-aware content filtering for public/group chat and optional DM with Block/Mask/Replace, bulk word lists, custom rules, anti-evasion matching and Web Admin testing
• Custom emoji management with multi-file administrator upload, plus optional ImageEmojis-Bero Bukkit/Paper integration using the same plugins/KOKOTO-WebChat/emojis tree; its resource-pack HTTP port remains a separate client-facing service
• SimpleNicks-Bero nickname integration on Bukkit/Paper-family servers through player-display.mode: "display-name", while KWC retains the real linked account identity
• Configurable message tokens such as :enter: / :newline: / :tab: with administrator-localizable aliases and printable custom substitutions
• Web Push / keyword notifications and administrator update notifications
• Per-account visual UI profiles plus account-synced keyword/notification preferences for signed-in users; device-local window state and Push endpoints stay local
• Administrator Discord keyword alerts with KWC-owned matching/deduplication and DiscordSRV logical-channel selection
• Administration and moderation tools for message deletion, pins, guest/IP mutes, session revocation, user restrictions, custom emoji management, and private-chat metadata
• Optional read-only DM and group-chat body audit for explicitly allowlisted super administrators; both are disabled by default and every audit page read is logged
• Built-in UI languages: English, Korean, Japanese, Simplified Chinese

Private messaging and delivery reliability

Cross-server DM targets are identified by server ID + player UUID, so a local player cannot be confused with a same-name player on another server. Remote messages stay pending until the destination confirms storage. Failed or uncertain sends can be retried with persistent relay/client message IDs without duplicating sender or receiver records.

DM and group-chat message state is shown compactly beside the timestamp. Normal successful delivery is silent; pending or failed delivery is shown only when needed. DM messages use a short unread label until the recipient reads them, then show ✓. Group messages show the number of recipients who have not read the message and change to ✓ when everyone has read it.

Multi-server relay

Relay Protocol 2.2 carries public chat and cross-server DM/read/delete flows inside explicit trust groups and capability-gates public reactions/typing, chat-event routing, and remote public-profile lookup while keeping Protocol major 2 as the wire-compatibility boundary. Each group has one shared secret; peers have no individual secret and must be configured reciprocally in the same group. Every message request authenticates/encrypts itself independently. /relay/v2/handshake is a stateless diagnostic identity/health probe and does not control routing. Messages use directional HKDF-SHA256 keys and AES-256-GCM hop-by-hop authenticated encryption; responses are HMAC-authenticated and timestamp/nonce/relay-ID/hop defenses reject replay or loops.

Each peer keeps enabled as a master switch and may independently configure send and receive for public-chat, event, dm, and profile. Missing entries default to enabled for compatibility. KWC Chat Events use the distinct event source rather than ordinary system, so remote event announcements can be rejected without suppressing unrelated system notices. Public reaction/typing follow public-chat; DM reaction/typing/read/delete follow dm.

Direct one-hop HTTP can be used with an explicit warning because relay payloads remain encrypted/authenticated. Forwarding filtering is per peer: an HTTP peer is excluded only as that forwarding hop, while other HTTPS peers in the same group remain eligible. Relay Protocol 2.2 is not end-to-end encryption: forwarding servers decrypt and re-encrypt as trusted participants. Legacy Relay v1 endpoints return HTTP 426.

On the first upgrade from 5.0.0, old flat relay settings are not converted into guessed groups. Relay is reset disabled so the operator can explicitly define the v2 trust groups before re-enabling it.

Administrator private-chat audit

Private message bodies are not automatically exposed to normal administrators. Optional audit access requires an exact Minecraft name/UUID in private-chat-super-admins and the corresponding feature switch:

direct-message:
  admin-audit:
    enabled: false

group-chat:
  admin-audit:
    enabled: false

Audit views are read-only. Group audit does not join the room or affect read/unread state. Every audit page read records the actor and pagination metadata without copying message bodies into the audit log.

Deployment

Fresh configurations start with the plugin master switch disabled so operators can review storage, authentication, uploads, retention, and web exposure before enabling it. During migration, the bundled config.yml is the only template: KWC creates a fresh current default and overlays existing operator values, so old comments/layout are replaced by the current bundled comments/layout. A fixed older-version config is backed up before reconstruction. <version>_auto_migration repeats this rebuild on startup/reload; exact <version> fixes the current-version config and prevents same-version rewriting. config-reference-<version>.yml is an administrator-readable exact default copy, not the migration source, and obsolete generated reference/migration files are cleaned up automatically. /kchat reload validates edited YAML before stopping live services; invalid YAML is rejected so the previous running configuration, UI language, and services remain active. Bundled UTF-8 starter filter-word lists for Korean, English, Japanese, and Simplified Chinese are initialized once when the starter-list marker is absent; existing or disabled files are preserved, and administrator deletions after initialization are not reversed.

For public deployments, placing BlueMap and KOKOTO WebChat behind HTTPS with Caddy or Nginx is recommended.

Optional integrations

• BlueMap (Bukkit plus BlueMapAPI on Fabric/NeoForge 26.1.2/26.2/26.3 and Forge 26.1.2/26.2/26.3)
• squaremap and Dynmap filesystem web adapters
• Pl3xMap on Bukkit/Paper-family and Fabric
• LiveAtlas, uNmINeD, and Minecraft Overviewer static-web adapters
• DiscordSRV on Bukkit
• ImageEmojis-Bero on Bukkit/Paper-family servers (shared KWC emoji path + runtime glyph resolution); general ImageEmojis operation follows the upstream plugin documentation
• SimpleNicks-Bero on Bukkit/Paper-family servers through Bukkit display names; general SimpleNicks operation follows the upstream plugin documentation
• Web Push notifications

See the bundled README and docs/ directory for full configuration, reverse-proxy, relay, security, migration, and troubleshooting guides.

AI assistance disclosure

Generative AI was used as a development assistant for code review, implementation and patching, documentation drafting, and multilingual translation. Project requirements, architecture/design decisions, integration, testing, compatibility verification, release validation, and final acceptance are human-directed and reviewed. AI-assisted output is reviewed and validated before inclusion.