feat: configurable broadcasts + /core reload
New fr.luc.crcore.broadcast module: - BroadcastAudience enum (NONE, LEADER, TEAM, ADMIN, ALL). - BroadcastContext (fluent: team + involvedPlayerId + placeholders). - BroadcastService interface + YamlBroadcastService impl. - CRCoreBroadcastListener (Bukkit listener) wires the 12 native events (9 team + 3 player) to broadcasts.broadcast(eventKey, ctx). Same single-per-plugin file pattern as messages: <plugin-dataFolder>/<plugin-name-lowercase>-broadcasts.yml. Defaults bundled at resources/crcore-broadcasts.yml, copied on first boot (game plugin's own resource of the same name takes priority as the template). In-memory fallback so new CR-Core keys work without admin edit. Routes (who) vs templates (what) are separated: broadcasts.yml lists audiences per eventKey, messages.yml contains the templates under keys <eventKey>.broadcast. Admin can change either independently. 12 new *.broadcast keys added to crcore-messages.yml with sensible French defaults and color codes. Listener injects standard placeholders (name, team_name, tag, color, visibility, player, new_leader, old/new_value, etc.). ADMIN audience resolved via crcore.broadcast.admin permission. Multi- audiences via YAML list (e.g., [TEAM, ADMIN]); union of resolved players, no duplicate. New /core reload subcommand (permission crcore.reload) hot-reloads both messages and broadcasts from disk without restart. CRCore: protected buildBroadcastService() override point, getter broadcasts(), wire of CRCoreBroadcastListener at enable(). CoreCommand constructor extended to take BroadcastService, registers the reload subcommand. Docs/features.md: new section 9 "Service de broadcasts". docs/setup.md: updated to mention both YAML files. decisions.md logs the routes-vs- templates split, the audience model, and the reload semantics. New diagram broadcasts-class-diagram.puml. README updated. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Antone Barbaud
+124
-1
@@ -684,7 +684,130 @@ placeholders documentés en commentaire.
|
||||
|
||||
---
|
||||
|
||||
## 9. Bootstrap `CRCore`
|
||||
## 9. Service de broadcasts (`fr.luc.crcore.broadcast`)
|
||||
|
||||
**Statut** : implémenté. Un seul listener Bukkit interne route les 12
|
||||
événements CR-Core vers le {@code BroadcastService} qui décide à qui
|
||||
envoyer le message selon la config YAML.
|
||||
|
||||
### Séparation routes / templates
|
||||
|
||||
- **Routes** (« qui reçoit quoi ») → `<plugin>-broadcasts.yml`
|
||||
- **Templates** (« quel texte ») → `<plugin>-messages.yml`, clés
|
||||
`<eventKey>.broadcast` (ex. `team.create.broadcast`)
|
||||
|
||||
Les deux fichiers sont modifiables indépendamment. L'admin peut couper
|
||||
tous les broadcasts en passant tout en `[NONE]` sans toucher aux templates,
|
||||
ou inversement changer la formulation sans toucher aux routes.
|
||||
|
||||
### `BroadcastAudience` — qui reçoit
|
||||
|
||||
| Audience | Résolution |
|
||||
|---|---|
|
||||
| `NONE` | Personne (équivalent à liste vide). |
|
||||
| `LEADER` | Le chef de l'équipe concernée (s'il est en ligne). |
|
||||
| `TEAM` | Tous les membres en ligne de l'équipe concernée. |
|
||||
| `ADMIN` | Joueurs en ligne ayant la perm `crcore.broadcast.admin`. |
|
||||
| `ALL` | Tous les joueurs en ligne sur le serveur. |
|
||||
|
||||
Multi-cibles : une clé d'event mappe sur une **liste** d'audiences. Union
|
||||
(pas de doublon : un joueur dans deux audiences reçoit un seul message).
|
||||
|
||||
### Le fichier `<plugin>-broadcasts.yml` — exemple
|
||||
|
||||
```yaml
|
||||
team:
|
||||
create: [ADMIN] # admins voient les créations
|
||||
dissolve: [TEAM, ADMIN]
|
||||
member:
|
||||
add: [TEAM]
|
||||
remove: [TEAM]
|
||||
player:
|
||||
join: [TEAM]
|
||||
leadership:
|
||||
transfer: [TEAM, ADMIN]
|
||||
visibility:
|
||||
change: [LEADER]
|
||||
score:
|
||||
change: [NONE] # noisy par défaut
|
||||
spawn:
|
||||
change: [LEADER]
|
||||
|
||||
player:
|
||||
profile:
|
||||
create: [NONE]
|
||||
delete: [ADMIN]
|
||||
score:
|
||||
change: [NONE]
|
||||
```
|
||||
|
||||
### Liste des `eventKey` (= mapping listener)
|
||||
|
||||
| Bukkit event | Clé broadcasts.yml | Clé messages.yml |
|
||||
|---|---|---|
|
||||
| `TeamCreateEvent` | `team.create` | `team.create.broadcast` |
|
||||
| `TeamDissolveEvent` | `team.dissolve` | `team.dissolve.broadcast` |
|
||||
| `TeamMemberAddEvent` | `team.member.add` | `team.member.add.broadcast` |
|
||||
| `TeamMemberRemoveEvent` | `team.member.remove` | `team.member.remove.broadcast` |
|
||||
| `PlayerJoinTeamEvent` | `team.player.join` | `team.player.join.broadcast` |
|
||||
| `TeamLeadershipTransferEvent` | `team.leadership.transfer` | `team.leadership.transfer.broadcast` |
|
||||
| `TeamVisibilityChangeEvent` | `team.visibility.change` | `team.visibility.change.broadcast` |
|
||||
| `TeamScoreChangeEvent` | `team.score.change` | `team.score.change.broadcast` |
|
||||
| `TeamSpawnPointChangeEvent` | `team.spawn.change` | `team.spawn.change.broadcast` |
|
||||
| `PlayerProfileCreateEvent` | `player.profile.create` | `player.profile.create.broadcast` |
|
||||
| `PlayerProfileDeleteEvent` | `player.profile.delete` | `player.profile.delete.broadcast` |
|
||||
| `PlayerScoreChangeEvent` | `player.score.change` | `player.score.change.broadcast` |
|
||||
|
||||
### Placeholders injectés par le listener
|
||||
|
||||
Pour les events team, le contexte inclut toujours : `{name}`, `{team_name}`
|
||||
(alias), `{tag}`, `{color}` (code couleur ChatColor), `{visibility}`.
|
||||
Quand pertinent, en plus : `{player}` (nom du joueur impliqué),
|
||||
`{new_leader}`, `{old_leader}`, `{old_visibility}`, `{new_visibility}`,
|
||||
`{score_name}`, `{old_value}`, `{new_value}`, `{delta}`.
|
||||
|
||||
### API pour les game plugins
|
||||
|
||||
```java
|
||||
// Broadcast custom depuis un game plugin
|
||||
core.broadcasts().broadcast("mygame.round.start",
|
||||
BroadcastContext.empty()
|
||||
.with("round", String.valueOf(currentRound))
|
||||
.with("map", mapName));
|
||||
|
||||
// Lecture des audiences configurées (debug)
|
||||
List<BroadcastAudience> who = core.broadcasts().getAudiences("team.create");
|
||||
|
||||
// Hot reload
|
||||
core.broadcasts().reload();
|
||||
```
|
||||
|
||||
Pour ajouter ses propres events broadcast, le game plugin :
|
||||
1. Ajoute la clé dans son `<plugin>-broadcasts.yml` (ex.
|
||||
`mygame.round.start: [ALL]`)
|
||||
2. Ajoute le template dans `<plugin>-messages.yml` (clé
|
||||
`mygame.round.start.broadcast`)
|
||||
3. Appelle `core.broadcasts().broadcast(...)` quand l'event survient
|
||||
|
||||
### Override de l'impl
|
||||
|
||||
`CRCore.buildBroadcastService(messages)` est `protected`. Sous-classe
|
||||
{@code CRCore} pour fournir une impl alternative (base de données, queue
|
||||
externe, etc.).
|
||||
|
||||
### Commande `/core reload`
|
||||
|
||||
Permission : `crcore.reload`. Recharge à la fois `messages` et `broadcasts`
|
||||
depuis les fichiers user du dataFolder. Les defaults en jar ne bougent pas
|
||||
(pas re-chargés).
|
||||
|
||||
### Diagramme
|
||||
|
||||
- Classes : [broadcasts-class-diagram.puml](diagrams/broadcasts-class-diagram.puml)
|
||||
|
||||
---
|
||||
|
||||
## 10. Bootstrap `CRCore`
|
||||
|
||||
**Statut** : implémenté. Point d'entrée unique pour les plugins de jeu.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user