The config serializer writes a map key that contains a dot as a nested path, so the key is renamed on reload

[wisdommen]

What happens

A Map-typed @ConfigEntry whose key contains a dot is saved as a dotted path. Measured in UltiKits/UltiChat#25: the in-memory map held [my.rule, server-ip, rules-info]; after a save and a fresh init it held [my, server-ip, rules-info], with my -> {rule={...}}. The entry no longer matches its own name. YAML itself splits the dotted key on read, so the renamed form cannot be read back as written.

UltiChat now refuses a dotted rule name on its side (merged in UltiChat #40); this issue is the framework half, which every module with a Map entry keyed by operator input can still hit.

Relation

One of three symptoms of the same cause in the binding layer (the layer does not respect the declared shape of a field): #523 (collection elements stringified) and #526 (a wrongly shaped value takes the module down). The maintainer decided (2026-09-29) that all three are fixed before the 6.3.0 release, and that a value that cannot be converted to the declared type is skipped (or the field falls back to its default) with a warning naming the key and the value, while the rest of the configuration loads.

---

中文摘要： 配置序列化时把映射里带点的键写成路径，重载后键被改名（UltiChat#25 实测）。这是 UltiChat 那条的框架一半；与 #523、#526 同一根因。维护者 2026-09-29 决定三条都在 6.3.0 发布前修。

🤖 Generated with Claude Code

[wisdommen]

Maintainer decision (2026-09-30): no check, documentation only.

A map key that contains a dot is a documented limitation in 6.3.0. The framework does not reject these keys and does not log a warning about them.

Why: Plan 17-41 tried three designs, one after another: keeping the key whole, refusing it, and a read-only warning. Every review round of each design found new defects in that design's own code. The warning was then narrowed to maps declared as Map, and after that it no longer covered all the cases. For example, a map inside a Map<String, Object> value or inside an object (UltiRecipe's recipe definitions have this shape) would still have been split without any warning. The maintainer decided to remove the check and document the limitation instead.

The limitation, stated plainly:

• Bukkit's configuration uses . as its path separator.
• Some maps are stored in the file as a section. That includes a map-typed @ConfigEntry, a map nested in one, and a map inside an object stored in one. In those maps, a key such as my.rule is split into nested levels (my -> rule), both when it is written and when the file is loaded.
• Quoting the key in YAML ("my.rule":) does not help.
• The write path stays exactly as in 6.2.
• Module authors must not use . in these keys, whether in declared defaults or in keys the module builds at run time. Operators must not type one into such a map. Use - or _.
• A map that is a list element is plain data, and a dotted key in it is kept whole.

Where it is documented:

• COMPATIBILITY.md on fix/p17-fu-config, in its own bullet (English, then Chinese).
• The developer guide page Configuration file, docs(config): typed binding, shape mismatches, dotted map keys and language-key comments, as of v6.3.0 UltiTools-Dev-Doc#105 (English and Chinese).
• The inventory row ultitools.config.bind-dotted-map-key: its real-server check expects the split and no warning.
• Tests: ConfigDottedMapKeyTest#saveSplitsWithoutWarning and #operatorDottedKeyLoadsSplitQuotedOrNot. ConfigAlphaWriterEquivalenceTest checks that saving writes exactly what dfe71e01 writes.

This issue will be closed by the phase pull request as resolved by documentation.

---

中文：维护者 2026-09-30 决定「不做检查，只写文档」。含点的映射键在 6.3.0 是写进文档的限制，框架既不拒绝也不警告。

原因：17-41 先后试了三种做法：保留整个键、拒绝、只读警告。每一种在每一轮评审里都被查出它自己代码的新问题。警告收窄到只检查声明为 Map 的配置项之后，又只能覆盖一部分情况。例如 Map<String, Object> 值里的映射、对象里的映射（UltiRecipe 的配方定义就是这种结构）仍会被悄悄拆开。所以维护者决定不做检查，改为写进文档。

限制本身：

• 配置文件用 . 作路径分隔符。
• 文件里存成小节的映射，包括声明为 Map 的配置项、嵌套在其中的映射、存在其中的对象里的映射。在这些映射里，my.rule 这样的键写入和读取时都会被拆成嵌套的几层。
• 在 YAML 里给键加引号也没用。
• 写入方式与 6.2 完全相同。
• 模块作者不要在这类键里用点（声明的默认值和运行时生成的键都一样），服主也不要在这类映射里写带点的键，改用 - 或 _。
• 列表元素里的映射是普通数据，键里的点会保留。

文档位置：

• COMPATIBILITY.md
• 开发文档 docs(config): typed binding, shape mismatches, dotted map keys and language-key comments, as of v6.3.0 UltiTools-Dev-Doc#105
• 清单行 ultitools.config.bind-dotted-map-key

本 issue 将由本阶段的 PR 以「文档解决」关闭。

[wisdommen]

The fix moves into the config-layer refactor within 6.3.0 (maintainer decision, 2026-09-30).

We asked the maintainer whether the configuration layer needs a better design. The answer was to refactor it, including the storage layer, inside 6.3.0. The refactor brings:

• a converter registry, one converter per type, each with round-trip tests;
• a plain-data boundary: only strings, numbers, booleans, lists and maps reach the file, and an unknown type fails clearly when the module loads;
• module customisation by registering a converter, instead of subclassing DefaultConfigParser;
• a storage model where a path is an array of keys (the Configurate approach).

What this means for this issue:

• The fix on fix/p17-fu-config (head a2ce5f72, plans 17-41 and 17-42) will not be merged as its own pull request.
• The refactor plan inherits that branch's tests and the maintainer's decisions as its behaviour contract. The contract lists each test class and marks which behaviour must be kept and which 6.2-compatibility write behaviour must be decided again.
• The issue stays open and In progress until the refactor delivers it.

---

中文：本 issue 的修复移入 6.3.0 内的配置层重构（维护者 2026-09-30 决定「连存储层一起重构」）。重构包括：

• 按类型的转换器注册表，每种类型都有往返测试；
• 纯数据边界：只有字符串、数字、布尔、列表和映射进入文件，未知类型在模块加载时明确报错；
• 模块通过注册转换器定制，不再继承 DefaultConfigParser；
• 路径作为键数组的存储模型（参照 Configurate）。

分支 fix/p17-fu-config（a2ce5f72）不再单独合并。重构计划把这个分支的测试和维护者的决定作为行为约定继承下来。本 issue 保持打开、进行中，直到重构交付。

[wisdommen]

The configuration-refactor work moved here is now available in #581 at e89b0b0. Local verification passes; real-machine integration acceptance is not claimed.