docs: document MessagesService — single per-plugin YAML, defaults in jar

features.md: new section 8 "Service de messages" with the single-file model, two-layer in-memory (jar defaults + user file), API examples, template-override mechanism, and override-the-impl extension point. Bootstrap section renumbered to 9. decisions.md: new decision logging the choice of MessagesService design (YAML, single per-plugin file, in-jar fallback for new keys, template priority from the game plugin's own resource, programmatic set() for dynamic cases). README.md: feature list mentions externalized messages; diagrams index adds messages-class-diagram.puml. setup.md: new "Fichier messages" section explaining the file location, how to seed it from a game plugin's bundled template, and the API for hot reload / extras / programmatic set(). New diagram: docs/diagrams/messages-class-diagram.puml — MessagesService interface, YamlMessagesService impl, link to CRCore, with explanatory note on the two-source merge and template fallback at first boot. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-09 16:06:19 +02:00
parent f92f22f6c8
commit 4651ccbe69
5 changed files with 242 additions and 1 deletions
@@ -0,0 +1,63 @@
+@startuml messages-class-diagram
+title CR-Core — Messages service (class diagram)
+
+skinparam classAttributeIconSize 0
+hide empty members
+
+package "fr.luc.crcore.message" {
+
+  interface MessagesService {
+    + get(key, placeholderPairs...): String
+    + raw(key): String
+    + has(key): boolean
+    + set(key, template): void
+    + reload(): void
+    + loadAdditional(resourceName): void
+    + setApplyColorCodes(enabled): void
+    + isApplyColorCodes(): boolean
+    + getUserFile(): File
+  }
+
+  class YamlMessagesService {
+    - plugin: JavaPlugin
+    - defaults: Map<String, String>             ' in-memory (jar resource)
+    - messages: Map<String, String>             ' effective (defaults + user file)
+    - userFileName: String                      ' <plugin>-messages.yml
+    - userFile: File
+    - applyColorCodes: boolean
+    --
+    + YamlMessagesService(plugin: JavaPlugin)
+    --
+    - loadDefaultsFromResource(): void          ' charge crcore-messages.yml (jar)
+    - ensureUserFile(): void                    ' copie template si absent
+    - rebuildEffectiveMessages(): void          ' defaults + user file
+    - {static} flatten(section, prefix, out): void
+  }
+
+  YamlMessagesService ..|> MessagesService
+}
+
+package "fr.luc.crcore" {
+  class CRCore {
+    + messages(): MessagesService
+    # buildMessagesService(): MessagesService    ' override point
+  }
+  CRCore "1" *-- "1" MessagesService : owns
+}
+
+note bottom of YamlMessagesService
+  Modèle "un seul fichier par plugin" :
+
+  Sources en mémoire (la 2e écrase la 1ère sur clés communes) :
+    1. crcore-messages.yml          ← jar (toujours présent, fallback)
+    2. <plugin>-messages.yml        ← dataFolder (édité par l'admin)
+
+  Création du fichier user au 1er boot :
+    Priorité 1 : ressource du plugin de jeu sous le même nom
+    Priorité 2 : copie des defaults CR-Core
+
+  Placeholders : {name} via varargs key/value
+  Codes couleur : &a → §a (toggle)
+end note
+
+@enduml