admin/Cites_Plugins
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: split util/ vs features/ + modular opt-in setupX() config

Browse Source 
Package restructure to prepare future modularization. Three layers now:

1. fr.luc.crcore.util.* (always active)
   - common, command framework, database, message, broadcast, gui,
     placeholder

2. fr.luc.crcore.features.* (opt-in)
   - team (entities, services, repos, events, exceptions, config + GUI,
     command/Team*SubCommand)
   - player (profile, ranking, services, repos, events, exceptions)

3. fr.luc.crcore.builtin.*
   - CoreCommand + CoreReloadSubCommand (top-level routing — not a
     feature, not an util)

FQN moves (game plugins importing these need their imports updated):
- fr.luc.crcore.common.*          → fr.luc.crcore.util.common.*
- fr.luc.crcore.command.*         → fr.luc.crcore.util.command.*
- fr.luc.crcore.command.builtin.team.*
                                  → fr.luc.crcore.features.team.command.*
- fr.luc.crcore.command.builtin.CoreCommand / CoreReloadSubCommand
                                  → fr.luc.crcore.builtin.*
- fr.luc.crcore.database.*        → fr.luc.crcore.util.database.*
- fr.luc.crcore.message.*         → fr.luc.crcore.util.message.*
- fr.luc.crcore.broadcast.*       → fr.luc.crcore.util.broadcast.*
- fr.luc.crcore.gui.*             → fr.luc.crcore.util.gui.*
- fr.luc.crcore.placeholder.*     → fr.luc.crcore.util.placeholder.*
- fr.luc.crcore.team.*            → fr.luc.crcore.features.team.*
- fr.luc.crcore.player.*          → fr.luc.crcore.features.player.*

CRCoreConfig — features opt-in via fluent setup:
- setupTeams()        enables team feature
- setupPlayers()      enables player feature
- setupPlaceholders() enables PAPI integration
- setupAll()          shortcut
By default no feature is active. Game plugin must opt-in.

CRCore.enable() now conditional:
- Util services always built (messages, broadcasts, gui listener).
- Team services + repos + config built only if setupTeams().
- Player services + repos built only if setupPlayers().
- Placeholder hook registered only if setupPlaceholders() (and PAPI
  installed at runtime).
- Getters of disabled features throw IllegalStateException with a clear
  message pointing to the missing setupX() call.
- CoreCommand only registers TeamGroupSubCommand if teamService and
  teamConfig are non-null. CoreReloadSubCommand handles teamConfig=null
  (just skips that reload). /core reload always available.

Docs:
- setup.md tree fully rewritten to reflect util/+features/+builtin
  layout (~70 lines of arborescence).
- setup.md code snippet shows the three opt-in patterns (setupAll /
  granular / with options).
- decisions.md logs both decisions (restructure + modular setup).
- All .puml diagrams auto-updated to new FQNs.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Antone Barbaud
2026-06-10 12:00:00 +02:00
parent 75d2fa866d
commit 84735221f1
113 changed files with 833 additions and 643 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/decisions.md
+64
View File
@@ -367,6 +367,70 @@ Format léger : une décision = un titre + contexte + choix + raison.
bases existantes, ALTER TABLE manuel ou suppression du fichier
(les bases d'event sont jetables).
## 2026-06-10 — Réorganisation : `util/` (toujours) vs `features/` (opt-in)
- **Choix** : séparation nette en deux couches :
- `fr.luc.crcore.util.*` — couche **utilitaire**, toujours active : common,
command framework, database, message, broadcast, gui, placeholder.
- `fr.luc.crcore.features.*` — couche **features**, opt-in : team, player.
- `fr.luc.crcore.builtin.*` — les commandes top-level CoreCommand +
CoreReloadSubCommand (pas un util, pas une feature, mais le routing
global).
- **Renames de FQN** (importer côté plugin de jeu si on les utilise) :
- `fr.luc.crcore.common.*` → `fr.luc.crcore.util.common.*`
- `fr.luc.crcore.command.*` → `fr.luc.crcore.util.command.*`
(le framework — Command, BaseCommand, SubCommand, ArgumentType…)
- `fr.luc.crcore.command.builtin.team.*`
→ `fr.luc.crcore.features.team.command.*`
(les 14+ Team*SubCommand)
- `fr.luc.crcore.command.builtin.CoreCommand` / `CoreReloadSubCommand`
→ `fr.luc.crcore.builtin.*`
- `fr.luc.crcore.database.*` → `fr.luc.crcore.util.database.*`
- `fr.luc.crcore.message.*` → `fr.luc.crcore.util.message.*`
- `fr.luc.crcore.broadcast.*` → `fr.luc.crcore.util.broadcast.*`
- `fr.luc.crcore.gui.*` → `fr.luc.crcore.util.gui.*`
- `fr.luc.crcore.placeholder.*` → `fr.luc.crcore.util.placeholder.*`
- `fr.luc.crcore.team.*` → `fr.luc.crcore.features.team.*`
(et sous-packages event/exception/impl/config)
- `fr.luc.crcore.player.*` → `fr.luc.crcore.features.player.*`
- **Raison** : prépare la modularisation à long terme. Chaque feature est
isolée dans son sous-package `features/<nom>/` et peut éventuellement
être extraite en module Maven séparé plus tard. Les utils sont
partagés. Le top-level reste minimal (CRCore, CRCoreConfig, builtin).
## 2026-06-10 — Setup modulaire via `CRCoreConfig.setupX()`
- **Choix** : les features sont désormais **opt-in**. Par défaut une
instance de `CRCoreConfig` n'active **aucune** feature ; le plugin de
jeu opt-in via :
- `setupTeams()` — active team service, repo, config + GUI, sous-cmds
- `setupPlayers()` — active player profile service + repo
- `setupPlaceholders()` — active la hook PAPI (no-op si PAPI absent)
- `setupAll()` — raccourci, active tout
- **Comportement quand off** : les getters de service (ex.
`core.getTeamService()`) lèvent `IllegalStateException` avec un
message explicite. Les commandes built-in correspondantes ne sont
simplement pas enregistrées (ex. `/core team` n'existe pas si teams
off).
- **Util toujours actif** : messages, broadcasts, GUI framework, command
framework, database sont systématiquement chargés. C'est la couche
infrastructure que les features et les game plugins consomment.
- **Listeners Bukkit toujours register** : `CRCoreBroadcastListener` et
`GuiListener` sont register unconditionnellement. Si aucune feature ne
tire d'event, ils sont idle — aucun coût.
- **Snippet d'usage** :
```java
this.core = new CRCore(this,
new CRCoreConfig().setupAll()).enable();
// ou granular :
this.core = new CRCore(this,
new CRCoreConfig().setupTeams()).enable();
```
- **Raison** : un game plugin qui n'a pas besoin des teams ne charge
pas le service ; pas de fichier `<plugin>-team-config.yml` créé, pas
de table `crcore_teams` créée, pas de sous-commande `/core team`. La
surface est minimale par défaut.
## 2026-06-10 — Settings d'équipe : cascade per-team → global → default + GUI
- **Choix** : nouveau module `fr.luc.crcore.team.config` avec :
docs/diagrams/broadcasts-class-diagram.puml
+3 -3
View File
@@ -4,7 +4,7 @@ title CR-Core — Broadcast service (class diagram)
skinparam classAttributeIconSize 0
hide empty members
package "fr.luc.crcore.broadcast" {
package "fr.luc.crcore.util.broadcast" {
enum BroadcastAudience {
NONE
@@ -54,7 +54,7 @@ package "fr.luc.crcore.broadcast" {
}
CRCoreBroadcastListener ..|> "org.bukkit.event.Listener"
package "fr.luc.crcore.broadcast.impl" {
package "fr.luc.crcore.util.broadcast.impl" {
class YamlBroadcastService {
- plugin: JavaPlugin
- messages: MessagesService
@@ -73,7 +73,7 @@ package "fr.luc.crcore.broadcast" {
BroadcastService ..> BroadcastContext : consumes
BroadcastContext --> BroadcastAudience
YamlBroadcastService --> "fr.luc.crcore.message.MessagesService" : reads templates
YamlBroadcastService --> "fr.luc.crcore.util.message.MessagesService" : reads templates
CRCoreBroadcastListener --> BroadcastService : delegates
CRCoreBroadcastListener ..> BroadcastContext : builds
}
docs/diagrams/builtin-commands-diagram.puml
+3 -3
View File
@@ -4,17 +4,17 @@ title CR-Core — Default /core team commands (admin / joueur)
skinparam classAttributeIconSize 0
hide empty members
package "fr.luc.crcore.command" {
package "fr.luc.crcore.util.command" {
abstract class BaseCommand
abstract class SubCommand
}
package "fr.luc.crcore.command.builtin" {
package "fr.luc.crcore.builtin" {
class CoreCommand
CoreCommand --|> BaseCommand
package "fr.luc.crcore.command.builtin.team" {
package "fr.luc.crcore.features.team.command" {
class TeamGroupSubCommand {
+ TeamGroupSubCommand(service)
docs/diagrams/command-class-diagram.puml
+1 -1
View File
@@ -4,7 +4,7 @@ title CR-Core — Command framework (class diagram, nested sub-commands)
skinparam classAttributeIconSize 0
hide empty members
package "fr.luc.crcore.command" {
package "fr.luc.crcore.util.command" {
interface Command {
+ getName(): String
docs/diagrams/database-diagram.puml
+1 -1
View File
@@ -4,7 +4,7 @@ title CR-Core — Database (SQLite wrapper)
skinparam classAttributeIconSize 0
hide empty members
package "fr.luc.crcore.database" {
package "fr.luc.crcore.util.database" {
class Database {
- connection: Connection
docs/diagrams/events-diagram.puml
+2 -2
View File
@@ -8,7 +8,7 @@ package "org.bukkit.event" {
abstract class Event
}
package "fr.luc.crcore.team.event" {
package "fr.luc.crcore.features.team.event" {
abstract class TeamEvent {
- team: Team
@@ -57,7 +57,7 @@ package "fr.luc.crcore.team.event" {
TeamSpawnPointChangeEvent --|> TeamEvent
}
package "fr.luc.crcore.player.event" {
package "fr.luc.crcore.features.player.event" {
abstract class PlayerProfileEvent {
- profile: PlayerProfile
docs/diagrams/gui-class-diagram.puml
+1 -1
View File
@@ -4,7 +4,7 @@ title CR-Core — GUI framework (class diagram, réutilisable)
skinparam classAttributeIconSize 0
hide empty members
package "fr.luc.crcore.gui" {
package "fr.luc.crcore.util.gui" {
abstract class AbstractInventoryGui {
- inventory: Inventory
docs/diagrams/messages-class-diagram.puml
+1 -1
View File
@@ -4,7 +4,7 @@ title CR-Core — Messages service (class diagram)
skinparam classAttributeIconSize 0
hide empty members
package "fr.luc.crcore.message" {
package "fr.luc.crcore.util.message" {
interface MessagesService {
+ get(key, placeholderPairs...): String
docs/diagrams/player-class-diagram.puml
+2 -2
View File
@@ -6,7 +6,7 @@ hide empty members
' === Common abstractions ===
package "fr.luc.crcore.common" {
package "fr.luc.crcore.util.common" {
interface Identifiable {
+ getId(): UUID
@@ -40,7 +40,7 @@ package "fr.luc.crcore.common" {
' === Player domain ===
package "fr.luc.crcore.player" {
package "fr.luc.crcore.features.player" {
class PlayerProfile {
- scores: Map<String, Integer>
docs/diagrams/team-class-diagram.puml
+2 -2
View File
@@ -6,7 +6,7 @@ hide empty members
' === Common abstractions ===
package "fr.luc.crcore.common" {
package "fr.luc.crcore.util.common" {
interface Identifiable {
+ getId(): UUID
@@ -47,7 +47,7 @@ package "fr.luc.crcore.common" {
' === Team domain ===
package "fr.luc.crcore.team" {
package "fr.luc.crcore.features.team" {
enum TeamRole {
LEADER
docs/diagrams/team-config-class-diagram.puml
+6 -6
View File
@@ -4,7 +4,7 @@ title CR-Core — Team config (class diagram, cascade per-team → global → de
skinparam classAttributeIconSize 0
hide empty members
package "fr.luc.crcore.team.config" {
package "fr.luc.crcore.features.team.config" {
class "TeamSetting<T>" as TeamSetting <<final>> {
- key: String
@@ -60,7 +60,7 @@ package "fr.luc.crcore.team.config" {
+ getGlobalFileName(): Optional<String>
}
package "fr.luc.crcore.team.config.impl" {
package "fr.luc.crcore.features.team.config.impl" {
class YamlTeamConfigService {
- plugin: JavaPlugin
- teamRepository: TeamRepository
@@ -77,14 +77,14 @@ package "fr.luc.crcore.team.config" {
TeamConfigService ..> TeamSetting : reads/writes
}
package "fr.luc.crcore.team" {
package "fr.luc.crcore.features.team" {
class Team {
- settings: Map<String, Object>
+ getSettings(): Map<String, Object>
}
}
package "fr.luc.crcore.team.config.gui" {
package "fr.luc.crcore.features.team.config.gui" {
abstract class AbstractSettingsGui {
- rebuild() : peint la grille
# {abstract} getCurrentValue(setting): T
@@ -96,14 +96,14 @@ package "fr.luc.crcore.team.config.gui" {
class TeamSettingsGui
GlobalSettingsGui --|> AbstractSettingsGui
TeamSettingsGui --|> AbstractSettingsGui
AbstractSettingsGui --|> "fr.luc.crcore.gui.AbstractInventoryGui"
AbstractSettingsGui --|> "fr.luc.crcore.util.gui.AbstractInventoryGui"
GlobalSettingsGui --> TeamConfigService
TeamSettingsGui --> TeamConfigService
TeamSettingsGui --> Team
}
YamlTeamConfigService --> "fr.luc.crcore.team.TeamRepository" : persists per-team via save()
YamlTeamConfigService --> "fr.luc.crcore.features.team.TeamRepository" : persists per-team via save()
TeamConfigService ..> Team : reads/writes settings map
note bottom of YamlTeamConfigService
docs/setup.md
+97 -99
View File
@@ -66,7 +66,12 @@ api-version: 1.16
> Dans ce cas, CR-Core détecte la commande déclarée et s'y branche
> normalement via `setExecutor` (pas d'enregistrement dynamique).
### Code minimal
### Code minimal — setup modulaire
> ⚠️ **Important** : depuis 2026-06-10, les features (teams, players,
> placeholders) sont **opt-in** via `CRCoreConfig.setupX()`. Une instance
> `new CRCoreConfig()` n'active rien par défaut — il faut appeler
> `setupAll()` ou les `setupX()` individuels.
```java
public class MyGamePlugin extends JavaPlugin {
@@ -75,13 +80,27 @@ public class MyGamePlugin extends JavaPlugin {
@Override
public void onEnable() {
// 1 ligne = SQLite + services + /core team ... opérationnels
this.core = new CRCore(this).enable();
// OPTION A — tout activer en une ligne (teams + players + placeholders)
this.core = new CRCore(this, new CRCoreConfig().setupAll()).enable();
// Listener custom sur les events team
// OPTION B — granularité, n'activer que ce qu'on veut
// this.core = new CRCore(this, new CRCoreConfig()
// .setupTeams()
// .setupPlaceholders()) // pas de players
// .enable();
// OPTION C — par défaut + options
// this.core = new CRCore(this, new CRCoreConfig()
// .withSqliteFile("mygame.db")
// .withCommandName("game")
// .setupTeams())
// .enable();
// Listener custom sur les events team (nécessite setupTeams)
getServer().getPluginManager().registerEvents(new MyTeamListener(), this);
// Table custom pour stocker des données spécifiques au jeu
// (database util est toujours disponible)
core.getDatabase().table("my_kills")
.ifNotExists()
.column("player_id", ColumnType.UUID).primaryKey()
@@ -168,101 +187,80 @@ CitesPlugin/ # dossier IntelliJ (renommer plus t
│ ├── decisions.md
│ └── diagrams/*.puml
└── src/main/java/fr/luc/crcore/
├── CRCore.java # bootstrap orchestrator
├── CRCoreConfig.java # config (sqlite, command name, …)
├── common/
│ ├── Identifiable.java
│ ├── Named.java
│ ├── ScoreHolder.java # contrat partagé Team + PlayerProfile
│ ├── AbstractEntity.java
│ └── Repository.java
├── database/ # wrapper SQLite
│ ├── Database.java
│ ├── TableBuilder.java
│ ├── ColumnType.java
│ ├── RowMapper.java
│ └── DatabaseException.java
├── command/ # framework
│ ├── Command.java (interface)
│ ├── AbstractCommand.java # base partagée, nested sub-commands
│ ├── BaseCommand.java # top-level Bukkit-aware
│ ├── SubCommand.java
│ ├── CommandContext.java
│ ├── CommandResult.java
│ ├── CommandException.java
│ ├── ArgumentType.java
│ ├── ArgumentTypes.java
│ ├── ArgumentDef.java # package-private
│ └── builtin/ # commandes prêtes à l'emploi
│ ├── CoreCommand.java # /core
│ └── team/
│ ├── TeamGroupSubCommand.java # /core team (container)
│ ├── TeamArgumentTypes.java # ArgumentType<Team> avec tab-complete
│ ├── TeamCreateSubCommand.java # /core team create
│ ├── TeamDeleteSubCommand.java # /core team delete
│ ├── TeamAddSubCommand.java # /core team add
│ ├── TeamRemoveSubCommand.java # /core team remove
│ ├── TeamJoinSubCommand.java # /core team join
│ ├── TeamLeaveSubCommand.java # /core team leave
│ ├── TeamInfoSubCommand.java # /core team info
│ ├── TeamListSubCommand.java # /core team list
│ ├── TeamTransferSubCommand.java # /core team transfer
│ ├── TeamVisibilitySubCommand.java # /core team visibility
│ ├── TeamScoreSubCommand.java # /core team score (admin)
│ ├── TeamTopSubCommand.java # /core team top
│ └── TeamSetSpawnSubCommand.java # /core team setspawn
├── message/ # service de messages YAML
│ ├── MessagesService.java # interface (contrat public)
│ └── impl/
│ └── YamlMessagesService.java # impl par défaut
├── team/ # contrats + entités au top
│ ├── Team.java # entité
│ ├── TeamMember.java # entité
│ ├── TeamRole.java # enum
│ ├── TeamColor.java # enum
│ ├── TeamVisibility.java # enum
│ ├── TeamRanking.java # value
│ ├── TeamService.java # interface
│ ├── TeamRepository.java # interface
│ ├── event/ # Bukkit events team
│ │ ├── TeamEvent.java # base
│ │ ├── TeamCreateEvent.java
│ │ ├── TeamDissolveEvent.java
│ │ ├── TeamMemberAddEvent.java
│ │ ├── TeamMemberRemoveEvent.java
│ │ ├── PlayerJoinTeamEvent.java
│ │ ├── TeamLeadershipTransferEvent.java
│ │ ├── TeamVisibilityChangeEvent.java
│ │ ├── TeamScoreChangeEvent.java
│ │ └── TeamSpawnPointChangeEvent.java
│ ├── exception/ # hiérarchie d'exceptions team
│ │ ├── TeamException.java # base
│ │ ├── TeamAlreadyExistsException.java
│ │ ├── TeamNotFoundException.java
│ │ └── TeamAccessException.java
│ └── impl/ # implémentations swappables
│ ├── TeamServiceImpl.java # service de base
│ ├── BukkitEventFiringTeamServiceImpl.java # impl par défaut
│ ├── InMemoryTeamRepository.java # repo en mémoire
│ └── SqliteTeamRepository.java # repo SQLite write-through
└── player/ # contrats + entités au top
├── PlayerProfile.java # entité
├── PlayerRanking.java # value
├── PlayerProfileService.java # interface
├── PlayerProfileRepository.java # interface
├── event/ # Bukkit events player
│ ├── PlayerProfileEvent.java
│ ├── PlayerProfileCreateEvent.java
│ ├── PlayerProfileDeleteEvent.java
│ └── PlayerScoreChangeEvent.java
├── exception/
│ ├── PlayerException.java
│ └── PlayerProfileNotFoundException.java
└── impl/
├── PlayerProfileServiceImpl.java
├── BukkitEventFiringPlayerProfileServiceImpl.java
├── InMemoryPlayerProfileRepository.java
└── SqlitePlayerProfileRepository.java
├── CRCore.java # bootstrap (setupAll/setupTeams/...)
├── CRCoreConfig.java # config builder + flags features
├── builtin/ # commandes top-level (toutes features)
│ ├── CoreCommand.java # /core
│ └── CoreReloadSubCommand.java # /core reload
├── util/ # ◆ couche util — toujours active ◆
│ ├── common/ # abstractions partagées
│ │ ├── Identifiable.java
│ │ ├── Named.java
│ │ ├── ScoreHolder.java
│ │ ├── AbstractEntity.java
│ │ └── Repository.java
│ ├── database/ # wrapper SQLite générique
│ │ ├── Database.java
│ │ ├── TableBuilder.java
│ │ ├── ColumnType.java
│ │ ├── RowMapper.java
│ │ └── DatabaseException.java
│ ├── command/ # framework de commandes
│ │ ├── Command.java (interface)
│ │ ├── AbstractCommand.java
│ │ ├── BaseCommand.java
│ │ ├── SubCommand.java
│ │ ├── CommandContext.java
│ │ ├── CommandResult.java
│ │ ├── CommandException.java
│ │ ├── ArgumentType.java
│ │ ├── ArgumentTypes.java
│ │ └── ArgumentDef.java (package-private)
│ ├── message/ # service messages YAML
│ │ ├── MessagesService.java
│ │ └── impl/YamlMessagesService.java
│ ├── broadcast/ # service broadcasts YAML + listener
│ │ ├── BroadcastService.java
│ │ ├── BroadcastAudience.java
│ │ ├── BroadcastContext.java
│ │ ├── CRCoreBroadcastListener.java
│ │ └── impl/YamlBroadcastService.java
│ ├── gui/ # framework GUI (InventoryHolder)
│ │ ├── AbstractInventoryGui.java
│ │ ├── GuiClickHandler.java
│ │ ├── GuiListener.java
│ │ └── GuiItems.java
│ └── placeholder/ # PAPI expansion (opt-in)
│ └── CRCorePlaceholderExpansion.java
└── features/ # ◆ features opt-in via setupX() ◆
├── team/ (setupTeams())
│ ├── Team.java, TeamMember, enums, TeamRanking
│ ├── TeamService.java (interface)
│ ├── TeamRepository.java (interface)
│ ├── event/ (9 events Bukkit)
│ ├── exception/ (4 exceptions)
│ ├── impl/ (TeamServiceImpl, BukkitEventFiring*, InMemory*, Sqlite*)
│ ├── config/ (settings typés)
│ │ ├── TeamSetting.java
│ │ ├── TeamSettings.java (registry)
│ │ ├── TeamConfigService.java
│ │ ├── impl/YamlTeamConfigService.java
│ │ └── gui/ (Global + TeamSettingsGui)
│ │ ├── AbstractSettingsGui.java
│ │ ├── GlobalSettingsGui.java
│ │ └── TeamSettingsGui.java
│ └── command/ (14 sous-commandes /core team)
│ ├── TeamGroupSubCommand.java
│ ├── TeamArgumentTypes.java
│ └── Team*SubCommand.java
└── player/ (setupPlayers())
├── PlayerProfile.java
├── PlayerRanking.java
├── PlayerProfileService.java (interface)
├── PlayerProfileRepository.java (interface)
├── event/ (3 events)
├── exception/ (2 exceptions)
└── impl/ (services + repositories)
```
## Fichiers de config générés au premier `enable()`