Antone Barbaud
4efaa5bbde
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>
98 lines
5.7 KiB
Markdown
98 lines
5.7 KiB
Markdown
# 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](diagrams/team-class-diagram.puml) | Classe | Domaine Team + abstractions communes |
|
|
| [team-create-sequence.puml](diagrams/team-create-sequence.puml) | Séquence | Création d'une équipe via la commande |
|
|
| [team-join-sequence.puml](diagrams/team-join-sequence.puml) | Séquence | Auto-join sur une équipe publique |
|
|
| [team-create-activity.puml](diagrams/team-create-activity.puml) | Activité | Flux de validation à la création |
|
|
| [player-class-diagram.puml](diagrams/player-class-diagram.puml) | Classe | Domaine Player + scores joueur |
|
|
| [command-class-diagram.puml](diagrams/command-class-diagram.puml) | Classe | Framework de commandes (nested) |
|
|
| [builtin-commands-diagram.puml](diagrams/builtin-commands-diagram.puml) | Classe | Arbre des commandes `/core team ...` |
|
|
| [events-diagram.puml](diagrams/events-diagram.puml) | Classe | Évènements Bukkit team + player |
|
|
| [database-diagram.puml](diagrams/database-diagram.puml) | Classe | Wrapper SQLite + table builder |
|
|
| [messages-class-diagram.puml](diagrams/messages-class-diagram.puml) | Classe | Service de messages YAML |
|
|
| [broadcasts-class-diagram.puml](diagrams/broadcasts-class-diagram.puml) | Classe | Service de broadcasts YAML + listener |
|
|
| [team-config-class-diagram.puml](diagrams/team-config-class-diagram.puml) | Classe | Paramètres d'équipe (cascade + GUI) |
|
|
| [gui-class-diagram.puml](diagrams/gui-class-diagram.puml) | Classe | Framework GUI réutilisable |
|
|
| [moderation-class-diagram.puml](diagrams/moderation-class-diagram.puml) | Classe | Feature modération (skeleton) |
|
|
| [bootstrap-sequence.puml](diagrams/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.
|