Updates Migration

Updates Migration

BlueMapWebChat 4.7.0 · Minecraft 1.18–26.2 · Java 17 baseline

4. Configuration Upgrade and Migration Fragment

BlueMapWebChat never overwrites existing setting values during an update. It may reorder known top-level config blocks to match the bundled layout while preserving each block's current text, values, and custom comments.

For every existing config check, the plugin creates or refreshes the complete current default reference:

plugins/BlueMapWebChat/config-reference-4.7.0.yml

On startup/reload, known top-level config.yml blocks are reordered to the bundled 4.7.0 layout while each block's current text, values, and custom comments are preserved; unknown top-level blocks remain last in their original order.

This file is an exact copy of the bundled 4.7.0 config.yml, including comments, and is generated regardless of the old config version. When config-version is missing or differs from the running plugin version, the plugin additionally creates:

plugins/BlueMapWebChat/config-migration-4.7.0.yml

Decision rules:

Physical config.yml state	Behavior
config-version is missing	Create the migration file with the target version marker even when there are zero other differences
config-version differs from the plugin version	Create or refresh the migration file with missing/changed settings and the target version marker
config-version matches the plugin version	Treat the configuration as reviewed, skip migration comparison, remove stale same-version migration guidance, and keep the full reference current

The file contains copy-ready YAML for:

• New settings missing from the installed configuration
• Defaults that changed while the installed value still matches the old default
• The target config-version review marker

Even when no other settings differ, the file is created with config-version so configuration version management remains explicit.

Counts and old/new value explanations are comments beginning with #. Migration does not change setting values. Startup/reload may separately reorder known top-level config blocks to the bundled layout while preserving each block's text, values, and custom comments.

The bottom of config-migration-4.7.0.yml contains a comment-only full-text comparison against config-reference-4.7.0.yml. Comments, blank lines, indentation, ordering, quoting, and setting text all participate in comparison, but unchanged lines are omitted from the report. For each actual difference, the file name is printed first, Line or Lines is printed on a separate line, and the differing text appears below it. Each differing source line is prefixed directly with #, so its original YAML indentation remains unchanged. Reference-only blocks also show the insertion position in the current config.

Upgrade procedure:

1. Open the migration fragment.
2. Merge the required blocks into the matching locations in config.yml.
3. Adjust server-specific and custom values.
4. After review, set:

config-version: "4.7.0"

When the version matches, future comparisons are skipped.

4.7.0 upgrade

4.7.0 expands the conservative Bukkit/Spigot compatibility baseline to Minecraft 1.18, adds administrator custom-emoji multi-file upload, and adds configurable colon-delimited message tokens.

Compatibility

• Conservative supported Minecraft range: 1.18 through 26.2
• Java requirement: Java 17
• plugin.yml: api-version: '1.18'
• Maven compile API: spigot-api:1.18.2-R0.1-SNAPSHOT
• Paper AsyncChatEvent remains reflection-detected; Bukkit AsyncPlayerChatEvent remains the hard-linked fallback.
• Minecraft 1.17 and older are not claimed by this release.

Custom emoji multi-upload

Emoji upload now follows the same picker flow as normal chat file upload. The visible Upload button opens a hidden multi-file input. As soon as the picker returns a selection, BlueMapWebChat copies the selected files, clears the native input, and immediately starts sequential uploads. There is no second Upload confirmation step and no file-picker focus/visibility workaround. Progress and active-transfer cancel remain available. The existing server endpoint still performs per-file validation, storage accounting, unique-name allocation, audit logging, and PNG-sidecar generation.

Message tokens

The default aliases are English-only and can be replaced or extended in any language. :enter:, :newline:, :nextline:, :linebreak:, and :br: insert a newline; :blankline:, :emptyline:, and :paragraphbreak: insert an empty line; :tab: and :indent: insert configurable spaces. Printable custom substitutions such as :separator: are also configurable. Unknown tokens are left unchanged so custom/image emoji tokens continue to work.

Configuration

4.7.0 adds the message-tokens section. Existing setting defaults outside this new section are unchanged. The review marker changes to:

config-version: "4.7.0"

A reviewed 4.6.3 configuration therefore receives the new message-tokens section plus the 4.7.0 review marker in config-migration-4.7.0.yml. Older and unversioned configs are also compared against the current defaults rather than being restricted to a 4.6.3-only upgrade path. Use config-reference-4.7.0.yml when you need the complete current configuration and comments. Empty maps such as message-tokens.custom: {} are retained as real missing settings.