Files

T

Antone Barbaud 4efaa5bbde feat: moderation feature skeleton (/core admin + mod mode + tools)

New feature fr.luc.crcore.features.moderation, opt-in via
CRCoreConfig.setupModeration() (also enabled by setupAll()).

Core abstractions:
- ModerationState: full player snapshot (inv + armor + offhand, XP,
  health, food, location, gamemode, allowFlight/flying, walk/fly speed).
  Immutable, restoreTo(player) restores everything.
- ModerationService interface + ModerationServiceImpl (with
  protected onAfterEnter/onAfterExit hooks) +
  BukkitEventFiringModerationServiceImpl (fires ModerationEnterEvent /
  ModerationExitEvent).
- ModerationRepository interface + InMemoryModerationRepository
  (skeleton — SQLite impl with BukkitObjectOutputStream serialization
  planned).
- ModeratorTool interface: getKey/getSlot(0..8)/buildIcon +
  onLeftClick/onRightClick/onInteractEntity. ModeratorToolRegistry
  preserves registration order, slot collision = replace.
- Exceptions: ModerationException base + AlreadyActive + NotActive.
- Events: ModerationEvent base + Enter + Exit.

5 skeleton tools in the hotbar:
- slot 0: TeleportRandomPlayerTool (compass, right-click → tp random)
- slot 1: InventorySpyTool (chest, right-click on player → open inv)
- slot 2: FreezeTool (ice, right-click on player → toggle freeze)
- slot 7: VanishToggleTool (ender eye, click → toggle vanish)
- slot 8: ExitTool (barrier, click → exit mod mode)
Slots 3-6 free for custom tools.

ModerationListener routes interactions and locks hotbar:
- PlayerInteractEvent → tool.onLeftClick / onRightClick (with cancel).
- PlayerInteractEntityEvent → tool.onInteractEntity (with cancel).
- PlayerDropItemEvent / PlayerSwapHandItemsEvent: cancel for mods.
- InventoryClickEvent: cancel only when top inv is the mod's own inv
  (preserves InventorySpyTool's ability to manipulate target's inv).
- PlayerJoinEvent: re-applies vanish for already-vanished mods.
- PlayerQuitEvent: cleanup freeze state.
- PlayerMoveEvent: cancel block-position changes for frozen players,
  keeping head rotation free.

Mod mode lifecycle:
- enter: snapshot + clear inv + populate hotbar + CREATIVE +
  allowFlight + vanish + ModerationEnterEvent.
- exit: state.restoreTo(player) + unvanish + unfreeze + repo delete +
  ModerationExitEvent.

/core admin (perm crcore.admin, player-only): toggle on/off.
Messages moderation.enter.success / moderation.exit.success added
to crcore-messages.yml.

CRCoreConfig.setupModeration() + isModerationEnabled() flag.
CRCore: buildModerationService() and registerDefaultModeratorTools()
override points, moderation() / getModerationService() getters with
IllegalStateException guard. Builds + registers ModerationListener at
enable() when feature on. CoreCommand extended to take ModerationService;
registers AdminToggleSubCommand only when service non-null.

Skeleton limitations documented in features.md:
- In-memory repo only (server crash = lost inv) — SQLite planned.
- InventorySpyTool opens real inv (no read-only wrapping yet).
- TeleportRandomPlayerTool is a placeholder for a future player-picker
  GUI.
- No moderation.*.broadcast keys yet.
- No /core admin <player> (self-toggle only).

Docs: section 11 in features.md, decision logged in decisions.md
(skeleton scope + rationale), setup.md snippet updated,
new moderation-class-diagram.puml, README.md updated.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-06-10 12:19:21 +02:00

diagrams

feat: moderation feature skeleton (/core admin + mod mode + tools)

2026-06-10 12:19:21 +02:00

decisions.md

feat: moderation feature skeleton (/core admin + mod mode + tools)

2026-06-10 12:19:21 +02:00

features.md

feat: moderation feature skeleton (/core admin + mod mode + tools)

2026-06-10 12:19:21 +02:00

README.md

feat: moderation feature skeleton (/core admin + mod mode + tools)

2026-06-10 12:19:21 +02:00

setup.md

feat: moderation feature skeleton (/core admin + mod mode + tools)

2026-06-10 12:19:21 +02:00

README.md

Documentation CR-Core

Ce dossier est la source de vérité du projet. Toutes les décisions, idées, mécaniques, règles et spécifications du noyau sont consignées ici.

Objectif du projet

CR-Core est une librairie Maven réutilisable pour construire des plugins Minecraft Paper 1.16.5. Elle fournit, prêt à l'emploi en une ligne d'initialisation côté plugin de jeu :

Abstractions communes — Identifiable, Named, ScoreHolder, AbstractEntity, Repository<T>.
Domaine Team — équipes (nom, tag, couleur, chef, membres, visibilité PUBLIC/PRIVATE, scores nommés, classements, point de spawn), service overridable, exceptions dédiées.
Domaine Player — profils joueurs (scores nommés, classements individuels), service auto-créant les profils à la demande.
Framework de commandes — BaseCommand / SubCommand imbriqués, arguments typés, tab-complétion, permissions, player-only.
Commandes par défaut — /core team [create|delete|add|remove|join| leave|info|list|transfer|visibility|score|top|setspawn] fonctionnelles out-of-the-box, chacune substituable par sous-classe.
Évènements Bukkit — 9 events team + 3 events player, à écouter avec @EventHandler côté plugin de jeu.
Persistance SQLite — wrapper Database + TableBuilder fluide, repositories SQLite write-through, table custom en 2 lignes pour les plugins downstream.
Messages externalisés — MessagesService charge un seul fichier YAML <plugin>-messages.yml dans le dataFolder du plugin de jeu, avec defaults CR-Core en fallback. L'admin édite un seul fichier, placeholders nommés, codes couleur & natifs.
Broadcasts configurables — BroadcastService route chaque event CR-Core vers une liste d'audiences (NONE, LEADER, TEAM, ADMIN, ALL) définie dans <plugin>-broadcasts.yml. Séparation routes / templates. Un listener interne wire les 12 events natifs ; les game plugins peuvent broadcast leurs propres events. /core reload recharge les deux fichiers à chaud.
Paramètres d'équipe — TeamConfigService typé avec cascade per-team → global → default. 8 settings standards (FRIENDLY_FIRE, MAX_SIZE, etc.), étendable. Globaux dans <plugin>-team-config.yml, per-team en SQLite. GUI in-game via /core team settings [team].
Framework GUI — AbstractInventoryGui + GuiListener réutilisable pour tout GUI custom. Détection par holder, clic toujours annulé, GuiItems builder fluide avec codes couleur &.
Modération (skeleton) — /core admin toggle pour passer en mod mode : snapshot complet du joueur (inv, XP, location, gamemode), vanish, hotbar dotée d'outils (tp joueur, inv spy, freeze, vanish toggle, exit). ModeratorTool + registry extensibles. Persistance SQLite à venir.
Bootstrap unique — new CRCore(this, new CRCoreConfig().setupAll()).enable() dans le onEnable() du plugin de jeu, et tout est branché.

Structure de la documentation

README.md — Ce fichier. Vue d'ensemble et index.
setup.md — Build, intégration dans un plugin de jeu, exemple d'usage.
features.md — Domaines fonctionnels détaillés.
decisions.md — Journal des décisions importantes (ADR léger).
diagrams/ — Diagrammes PlantUML (.puml).

Diagrammes

Fichier	Type	Sujet
team-class-diagram.puml	Classe	Domaine Team + abstractions communes
team-create-sequence.puml	Séquence	Création d'une équipe via la commande
team-join-sequence.puml	Séquence	Auto-join sur une équipe publique
team-create-activity.puml	Activité	Flux de validation à la création
player-class-diagram.puml	Classe	Domaine Player + scores joueur
command-class-diagram.puml	Classe	Framework de commandes (nested)
builtin-commands-diagram.puml	Classe	Arbre des commandes `/core team ...`
events-diagram.puml	Classe	Évènements Bukkit team + player
database-diagram.puml	Classe	Wrapper SQLite + table builder
messages-class-diagram.puml	Classe	Service de messages YAML
broadcasts-class-diagram.puml	Classe	Service de broadcasts YAML + listener
team-config-class-diagram.puml	Classe	Paramètres d'équipe (cascade + GUI)
gui-class-diagram.puml	Classe	Framework GUI réutilisable
moderation-class-diagram.puml	Classe	Feature modération (skeleton)
bootstrap-sequence.puml	Séquence	`CRCore.enable()` côté plugin de jeu

Conventions

Code : anglais standard, séparation stricte interfaces / enums / classes abstraites / classes concrètes / exceptions.
Doc & messages joueur : français.
JavaDoc en français sur les classes publiques et méthodes non triviales.
Package racine : fr.luc.crcore.
Classes du noyau non-final, méthodes-clés protected, hooks onBefore…/onAfter… et factories new… pour l'override.

Contribuer à la doc

Chaque nouvelle idée, règle, commande ou contrainte discutée doit être ajoutée au fichier approprié, avant ou pendant l'implémentation. La doc précède le code.