SarTron-NorthBlueandClaude Sonnet 5
520ca1c80b
Optionnel (rewards.broadcast, desactive par defaut), declenche sur vote direct et sur /claim, avec %player% et %amount%. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
175 lines
8.0 KiB
Markdown
175 lines
8.0 KiB
Markdown
# VoteNetwork
|
||
|
||
Systeme de vote reseau en deux modules, pour une architecture **proxy Velocity + serveurs Spigot/Paper** (modes A, B, C, ...).
|
||
|
||
- `velocity/` — module proxy. Recoit `votenetwork vote <pseudo>` (console uniquement) et route le vote en direct ou le met en attente.
|
||
- `spigot/` — module serveur. Recoit le signal en direct via Plugin Messaging, gere `/claim`, le VoteParty local et le mode maintenance.
|
||
|
||
Compatible **Java 17**, compile contre l'API Spigot **1.18.2** (additive, donc compatible en avant vers 1.19 → 1.21.x et versions futures).
|
||
|
||
---
|
||
|
||
## Sommaire
|
||
|
||
- [Installation](#installation)
|
||
- [Build depuis les sources](#build-depuis-les-sources)
|
||
- [Configuration](#configuration)
|
||
- [Stockage : MySQL ou YAML](#stockage--mysql-ou-yaml)
|
||
- [Fonctionnement du vote](#fonctionnement-du-vote)
|
||
- [Commandes & permissions](#commandes--permissions)
|
||
- [VoteParty](#voteparty)
|
||
- [API publique (scoreboard / GUI)](#api-publique-scoreboard--gui)
|
||
- [Structure de la base de données](#structure-de-la-base-de-données)
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
1. `velocity/target/VoteNetwork-Velocity.jar` → `plugins/` du proxy Velocity.
|
||
2. `spigot/target/VoteNetwork-Spigot.jar` → `plugins/` de **chaque** serveur Spigot/Paper (A, B, C, ...).
|
||
3. Démarrer une fois pour générer les fichiers de config, puis les éditer :
|
||
- Proxy : `plugins/votenetwork/config.properties`
|
||
- Serveur : `plugins/votenetwork/config.yml`
|
||
4. Redémarrer.
|
||
|
||
## Build depuis les sources
|
||
|
||
```
|
||
mvn clean package
|
||
```
|
||
|
||
Jars produits dans `velocity/target/` et `spigot/target/`.
|
||
|
||
## Configuration
|
||
|
||
Chaque composant a son propre fichier, tous deux dans un dossier **`votenetwork`** :
|
||
|
||
| Composant | Fichier | Dossier |
|
||
|---|---|---|
|
||
| Velocity | `config.properties` | `plugins/votenetwork/` (racine du proxy) |
|
||
| Spigot | `config.yml` | `plugins/votenetwork/` (sur chaque serveur) |
|
||
|
||
Le `config.yml` Spigot regroupe tout ce qui est personnalisable :
|
||
|
||
```yaml
|
||
storage:
|
||
type: mysql # mysql ou yaml
|
||
|
||
mysql:
|
||
host: 127.0.0.1
|
||
port: 3306
|
||
database: votenetwork
|
||
user: root
|
||
password: changeme
|
||
pool-size: 5
|
||
|
||
rewards:
|
||
vote-commands: # executees pour CHAQUE vote (direct ou via /claim, une fois par vote)
|
||
- "goldencrates give %player% vote_key 1"
|
||
broadcast: # message annonce a tout le serveur a chaque vote / claim
|
||
enabled: false
|
||
message: "&a[Vote] &e%player% &fvient de voter, merci a lui !"
|
||
|
||
voteparty:
|
||
votes-requis: 100 # déclenche le VoteParty à ce cumul (par serveur)
|
||
commands: # executees UNE fois quand le VoteParty se déclenche
|
||
- "goldencrates broadcast_give vote_key 1"
|
||
broadcast:
|
||
enabled: true
|
||
progress-message: "&b[Vote] &f%current%&7/&f%required% &fvotes avant le prochain VoteParty !"
|
||
triggered-message: "&a[Vote] &fVoteParty declenche ! Profitez des recompenses !"
|
||
|
||
messages:
|
||
direct-vote: "&a[Vote] &fMerci pour ton vote !"
|
||
claim-success: "&a[Vote] &fVous avez recupere &e%amount% &fvote(s) en attente !"
|
||
claim-empty: "&c[Vote] &fVous n'avez aucun vote en attente."
|
||
maintenance: "&c[Vote] &fLe systeme de vote est actuellement en maintenance."
|
||
maintenance-enabled: "&c[Vote] &fMode maintenance active."
|
||
maintenance-disabled: "&a[Vote] &fMode maintenance desactive."
|
||
no-permission: "&cVous n'avez pas la permission d'utiliser cette commande."
|
||
```
|
||
|
||
- `%player%` dans `rewards.vote-commands` est remplacé par le pseudo du joueur.
|
||
- `%current%` / `%required%` dans les messages de progression VoteParty.
|
||
- `%amount%` dans le message de succès `/claim` et dans `rewards.broadcast.message`.
|
||
- Codes couleur `&` supportés partout.
|
||
- `rewards.broadcast` (désactivé par défaut) : annonce publique à chaque vote direct ou à chaque `/claim` (avec le nombre de votes récupérés).
|
||
|
||
## Stockage : MySQL ou YAML
|
||
|
||
Chaque composant choisit indépendamment son stockage via `storage.type` :
|
||
|
||
- **`mysql`** (recommandé pour un vrai réseau) : partagé entre le proxy et tous les serveurs. La table `nb_votes_attente` est créée automatiquement au démarrage si absente.
|
||
- **`yaml`** : fichier local `pending-votes.yml` dans le dossier du plugin. Pratique en solo/test, **mais pas synchronisé automatiquement** entre le fichier du proxy et celui d'un serveur — chacun a sa propre copie locale. N'utilisez ce mode en réseau multi-machines que si les dossiers de plugins sont partagés sur le même disque (montage réseau, symlink). Sinon, un vote stocké côté proxy en YAML ne sera jamais vu par `/claim` sur un serveur Spigot séparé.
|
||
|
||
Testez la connexion/l'accès au stockage configuré côté Spigot avec :
|
||
|
||
```
|
||
/vote testdb
|
||
```
|
||
|
||
## Fonctionnement du vote
|
||
|
||
1. Un site de vote appelle la console du proxy : `votenetwork vote <pseudo>`.
|
||
2. **Joueur connecté** : le proxy détecte son serveur actuel et envoie un paquet sur le canal `votenetwork:vote`. Le serveur Spigot donne la récompense immédiatement et incrémente son VoteParty local de +1. **Rien n'est écrit en base.**
|
||
3. **Joueur déconnecté** : le proxy résout son UUID (API Mojang, avec repli si indisponible) et incrémente son compteur de votes en attente (MySQL ou YAML selon la config), de façon asynchrone.
|
||
4. Le joueur tape `/claim` sur un serveur Spigot : lecture asynchrone du compteur en attente, distribution des récompenses × N, VoteParty local +N, remise à 0.
|
||
5. `/vote stop` bloque `/claim` (mode maintenance, message personnalisable) ; `/vote start` le réactive.
|
||
|
||
## Commandes & permissions
|
||
|
||
| Commande | Où | Qui | Description |
|
||
|---|---|---|---|
|
||
| `votenetwork vote <pseudo>` | Velocity | Console uniquement | Enregistre un vote pour le joueur |
|
||
| `/claim` | Spigot | Joueurs | Récupère les votes en attente |
|
||
| `/vote stop\|start` | Spigot | `votenetwork.admin` (op par défaut) | Bascule le mode maintenance |
|
||
| `/vote testdb` | Spigot | `votenetwork.admin` (op par défaut) | Teste le stockage configuré (MySQL ou YAML) |
|
||
|
||
## VoteParty
|
||
|
||
- Compteur indépendant **par serveur**, persistant localement (`plugins/votenetwork/voteparty.yml`), survit aux redémarrages.
|
||
- `voteparty.votes-requis` définit le seuil de déclenchement.
|
||
- `voteparty.commands` s'exécutent une fois le seuil atteint, puis le compteur repart à 0 (avec report de l'excédent si plusieurs votes arrivent d'un coup, ex. via `/claim` de N votes).
|
||
- Messages de progression et de déclenchement personnalisables (`voteparty.broadcast`).
|
||
|
||
## API publique (scoreboard / GUI)
|
||
|
||
Un autre plugin sur le même serveur Spigot peut lire l'état du vote via `fr.votenetwork.spigot.api.VoteNetworkAPI` :
|
||
|
||
```java
|
||
VoteNetworkAPI api = VoteNetworkAPI.get();
|
||
// ou : Bukkit.getServicesManager().getRegistration(VoteNetworkAPI.class).getProvider();
|
||
|
||
int current = api.getVotePartyCurrentVotes();
|
||
int required = api.getVotePartyRequiredVotes();
|
||
boolean maintenance = api.isMaintenanceEnabled();
|
||
|
||
api.getPendingVotes(player.getUniqueId(), pending -> {
|
||
// callback rappelé sur le thread principal — safe pour un scoreboard/GUI
|
||
scoreboardLine.setText("Votes en attente: " + pending);
|
||
});
|
||
```
|
||
|
||
- `getVotePartyCurrentVotes()` / `getVotePartyRequiredVotes()` : lecture directe en mémoire, thread principal uniquement.
|
||
- `getPendingVotes(...)` : lecture asynchrone du stockage configuré (MySQL ou YAML), ne consomme pas les votes contrairement à `/claim`.
|
||
|
||
## Structure de la base de données
|
||
|
||
Créée automatiquement si absente (mode `mysql`) :
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS nb_votes_attente (
|
||
player_uuid VARCHAR(36) NOT NULL PRIMARY KEY,
|
||
player_name VARCHAR(16) NOT NULL,
|
||
nombre_votes INT DEFAULT 0
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## Notes techniques
|
||
|
||
- HikariCP + MySQL Connector/J sont shadés et relocalisés dans les deux jars (rien à installer manuellement sur le serveur). Le driver JDBC est chargé explicitement par son nom de classe relocalisé pour rester fiable après le shading.
|
||
- Toutes les requêtes SQL et I/O fichier sont asynchrones — aucun accès réseau ou disque ne bloque le thread principal du serveur ni celui du proxy.
|
||
- Si la connexion MySQL échoue au démarrage, le plugin reste actif (pas de crash) : corrigez `config.yml`/`config.properties` puis utilisez `/vote testdb`, ou redémarrez.
|