Documentation API
Système de vérification des votes Metin2
Des récompenses de vote simples, gratuites et fiables pour votre serveur privé Metin2
Notre système de vérification des votes est une solution moderne et innovante pensée spécialement pour les serveurs privés Metin2. Il offre aux joueurs un moyen attrayant de voter pour leurs serveurs préférés tout en recevant des avantages en jeu.
Le système est à la fois simple à implémenter et hautement fiable, ce qui en fait un excellent choix pour les administrateurs souhaitant augmenter l’engagement des joueurs et la visibilité de leur serveur.
Notre objectif est de créer une situation gagnant-gagnant pour les joueurs comme pour les propriétaires. Les joueurs sont récompensés pour leur loyauté et les serveurs gagnent en visibilité et en activité.
Système Vote4Buff (recommandé)
Solution complète de vote et de récompenses en jeu avec interface personnalisée
Vote4Buff est notre solution premium tout-en-un qui inclut une interface en jeu élégante, une communication WebSocket et une intégration serveur complète. Les joueurs peuvent voter, choisir parmi plusieurs pools de bonus et recevoir des récompenses instantanément sans quitter le jeu !
Architecture du système
Le système Vote4Buff se compose de trois éléments principaux :
Client
- Système d’interface Python (uivote4buff.py)
- Ressources graphiques personnalisées
- Intégration WebSocket en C++
- Support pour 11 langues
Serveur
- Intégration API en C++
- Gestion des pools de bonus
- Système de récompenses par objets
- Suivi des effets en temps réel
Notre plateforme
- API de vérification des votes
- Suivi basé sur les comptes
- Protection anti-triche
- Statut des votes en temps réel
Fonctionnalités clés
Idéal pour : Les administrateurs qui souhaitent une solution professionnelle clé en main sans investir des semaines de développement personnalisé. Configurez les pools, intégrez les fichiers et profitez-en !
Télécharger les fichiers Vote4Buff
Récupérez tous les fichiers nécessaires pour l’intégration client et serveur
Vote4Buff est conçu pour la base martysama0134 v5.8. Si vous utilisez une autre base, quelques ajustements peuvent être nécessaires.
Contenu du package
Fichiers client
- Fichiers d’interface Python (uivote4buff.py)
- Modifications des fichiers client
- Ressources graphiques d’interface
- Fichiers de langue (11 langues)
- Implémentation WebSocket C++
- Scripts d’interface
Inclut libcurl.dll (32 bits inclus, version 64 bits disponible)
Fichiers serveur
- Configuration de char.h
- Modifications du système d’effets
- Intégration des commandes de discussion
- Couche de communication avec l’API
- Système de gestion des bonus
Toutes les modifications C++ nécessaires sont fournies
Veuillez vous connecter pour télécharger les fichiers Vote4Buff.
Guide de configuration
Configurez les pools de bonus, les récompenses et les paramètres API
Toute la configuration de Vote4Buff s’effectue dans le fichier char.h de votre serveur. Voici des exemples détaillés pour chaque option.
Étape 1 : Identifiants API
Commencez par renseigner votre ID serveur et votre token API (disponibles dans votre tableau de bord) :
// API SETTINGS from Metin2 Server List
static const std::string s_VOTE4BUFF_SERVER_ID = "YOUR_SERVER_ID"; // From dashboard
static const std::string s_VOTE4BUFF_API_TOKEN = "YOUR_API_TOKEN"; // From dashboard
static const int s_VOTE4BUFF_DURATION = 86400; // seconds (1 day) DO NOT MODIFY THIS !!!
Étape 2 : Configurer les pools de bonus
Vous pouvez définir jusqu’à 3 pools de bonus parmi lesquels les joueurs choisiront. Chaque pool peut contenir plusieurs bonus :
// Bonuses must be set with its APPLY_ declaration.
// You can add as many bonuses as you want per slot.
static std::vector<std::vector<std::pair<int, int>>> s_VOTE4BUFF_BONUSES =
{
{ // Bonus Pool 1: PvP Focused
{ APPLY_ATTBONUS_HUMAN, 5 }, // +5% vs Players
{ APPLY_DEF_GRADE_BONUS, 50 }, // +50 Defense
},
{ // Bonus Pool 2: PvE Focused
{ APPLY_ATTBONUS_MONSTER, 5 }, // +5% vs Monsters
{ APPLY_ATTBONUS_INSECT, 5 }, // +5% vs Insects
{ APPLY_HP_REGEN, 10 }, // +10 HP Regen
},
{ // Bonus Pool 3: Farm Focused
{ APPLY_ITEM_DROP_BONUS, 10 }, // +10% Drop Rate
{ APPLY_EXP_DOUBLE_BONUS, 10 }, // +10% EXP
{ APPLY_GOLD_FIND, 15 }, // +15% Gold
},
};
Bonus courants : APPLY_ATTBONUS_HUMAN, APPLY_ATTBONUS_MONSTER, APPLY_DEF_GRADE_BONUS, APPLY_ITEM_DROP_BONUS, APPLY_EXP_DOUBLE_BONUS, APPLY_GOLD_FIND, APPLY_MAX_HP, APPLY_MAX_SP, APPLY_HP_REGEN, APPLY_SP_REGEN, APPLY_CRITICAL_PCT, APPLY_PENETRATE_PCT et bien d’autres.
Étape 3 : Récompenses d’objets (optionnel)
Définissez les objets que les joueurs recevront automatiquement après avoir voté :
static std::vector<std::pair<DWORD, int>> s_VOTE4BUFF_ITEM_REWARDS =
{
// Leave empty if you don't want to give any items as rewards
// Format: { vnum, count }
{ 27007, 5 }, // 5x Red Potion (XXL)
{ 50084, 1 }, // 1x Gold Bar
{ 71027, 10 }, // 10x Dragon Coin
};
Étape 4 : Paramètres de changement de bonus
Contrôlez le temps de recharge et le coût lorsque les joueurs souhaitent changer de pool sans revoter :
// Cooldown when changing bonus (does not apply when choosing right after voting)
static const int s_VOTE4BUFF_CHANGE_BONUS_COOLDOWN = 300; // seconds (5 minutes)
// Price when changing bonus (does not apply when choosing right after voting)
static const int s_VOTE4BUFF_CHANGE_BONUS_PRICE = 15000; // yang (0 = free)
Remarque : Après avoir voté, les joueurs peuvent choisir un pool gratuitement. Le délai et le prix ne s’appliquent que s’ils souhaitent changer sans revoter.
Guide d’installation
Instructions pas à pas pour intégrer Vote4Buff
Sauvegardez vos fichiers client et serveur ! Convention : les fichiers avec le préfixe __ nécessitent une fusion, les autres peuvent être copiés directement.
Installation côté serveur
Configurer char.h
Ouvrez Source/Server/__char.h depuis le package téléchargé.
- Trouvez
class CBuffOnAttributes;et ajoutez le code de configuration juste avant (voir section Configuration) - Définissez vos valeurs
s_VOTE4BUFF_SERVER_IDets_VOTE4BUFF_API_TOKEN - Configurez vos pools de bonus et vos récompenses d’objets
- Recherchez
bool DragonSoul_RefineWindow_CanRefine();et ajoutez les déclarations publiques nécessaires
Appliquer les modifications serveur
Intégrez les fichiers serveur fournis :
__affect.h- Fusionnez les changements avec votre affect.h existant__chat_affect.cpp- Ajoutez la gestion des effets Vote4Buff__cmd_general.cpp- Ajoutez le traitement des commandes__desc_client.cpp- Ajustez le descripteur client
Les fichiers préfixés par __ nécessitent une fusion avec vos propres fichiers.
Recompiler le core
Compilez votre serveur de jeu avec les nouvelles modifications.
make clean && make Installation côté client
Fichiers UI Python
Dans le dossier Client/root/ :
- Copiez
uivote4buff.pydans le dossierroot/de votre client - Modifiez les fichiers suivants selon les instructions :
__constInfo.py__game.py__interfaceModule.py__uiAffectShower.py
Graphismes et scripts UI
- Copiez
Client/ui/game/vote4buff/vers le répertoireui/game/de vos packs - Copiez
Client/uiscript/vote4buffwindow.pydans votre dossier uiscript
Fichiers de langue
Ajoutez les chaînes de langue depuis Client/locale/ :
- Ajoutez le contenu de
__locale_game.txtà votrelocale_game.txt - Ajoutez le contenu de
__locale_interface.txtà votrelocale_interface.txt
Langues disponibles : EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ
Modifications client en C++
Dans Source/Client/UserInterface/ :
- Copiez
M2WebSocket.cppetM2WebSocket.hdans le dossier UserInterface - Intégrez les changements des fichiers préfixés
__à vos fichiers existants - Verifiez que
libcurl.dllest présent dans votre dossier client (32 bits fourni, version 64 bits à télécharger si besoin)
Ajouter un bouton UI (optionnel)
Vote4Buff n’ajoute pas de bouton par défaut. Vous devez appeler ToggleVote4Buff() depuis votre interface, par exemple :
- Ajouter un bouton dans votre SystemDialog
- Lier à un raccourci clavier
- L’ajouter à votre menu de raccourcis
Vous pouvez aussi utiliser la classe Vote4BuffButton fournie pour créer une icône déplaçable.
Recompiler le client
Recompilez votre exécutable client avec les nouvelles modifications.
Tests
Testez l’intégration :
- Connectez-vous à votre serveur
- Ouvrez la fenêtre Vote4Buff
- Votez sur notre plateforme : https://metin2-toplist.net/vote/en/YOUR_SERVER_ID-server-name/YOUR_ACCOUNT_ID
- Retournez en jeu et vérifiez la prise en compte du vote
- Choisissez un pool de bonus et vérifiez l’application des effets
- Contrôlez la réception des récompenses d’objets
Vos joueurs peuvent maintenant voter et recevoir automatiquement leurs récompenses. L’interface Vote4Buff leur indique quand voter, permet de choisir les pools de bonus et affiche les compteurs pour les effets actifs.
Avantages pour les administrateurs
Promotion gratuite
La plupart des joueurs découvrent de nouveaux serveurs via les toplists : un outil marketing indispensable
Configuration simple
Documentation détaillée et guides pas à pas
Aucune programmation requise
Processus d’intégration REST clair et direct
Performance optimisée
La vérification côté client réduit la charge sur votre serveur
Fiabilité élevée
Système éprouvé avec protection anti-fraude intégrée
Vérification des votes
Assurez-vous que les joueurs ont bien voté avant de distribuer les récompenses
Avantages pour les joueurs
Comment fonctionne le système ?
Le flux est clair et intuitif pour les joueurs. La vérification des votes s’effectue via notre API afin de garantir que seuls les votes légitimes sont validés.
Premiers pas - Guide rapide
Choisissez la méthode d’intégration la mieux adaptée à vos besoins :
Système Vote4Buff
Solution complète avec UI personnalisée, communication WebSocket et récompenses automatiques.
- Interface complète en jeu
- Multiples pools de bonus
- Récompenses automatiques par objets
- Compteurs en temps réel
- Support de 11 langues
Intégration API personnalisée
Créez votre propre implémentation avec notre API REST pour un contrôle total.
- Personnalisation complète
- Conception UI sur mesure
- Logique de récompense personnalisée
- Basé sur IP ou sur compte
Étapes générales
Enregistrez votre serveur
Créez un compte et ajoutez votre serveur à notre toplist via https://metin2-toplist.net/servers/create
Récupérez vos identifiants API
Retrouvez votre ID serveur et votre token API dans votre tableau de bord. Ils sont nécessaires pour l’authentification.
Choisissez la méthode d’intégration
Téléchargez Vote4Buff pour une solution clé en main ou utilisez notre API pour une implémentation personnalisée.
Testez et déployez
Testez soigneusement le système de vote avant de le déployer sur votre serveur live.
Endpoint API (pour implémentations personnalisées)
Si vous utilisez le système Vote4Buff (recommandé), cette API est déjà intégrée ! Cette section s’adresse aux administrateurs souhaitant créer leur propre intégration.
https://metin2-toplist.net/api/check-vote
Paramètres requis
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
api_token |
string | Oui | Votre token API unique |
ip |
string | Optionnel* | Adresse IP du joueur (IPv4 ou IPv6) |
account_id |
string | Optionnel* | ID de compte ou pseudo du joueur pour un suivi précis |
Pour des résultats optimaux, utilisez <code>account_id</code> afin d’identifier précisément les joueurs. La méthode <code>ip</code> peut être moins fiable si les joueurs utilisent un VPN ou changent de localisation.
Format de l’URL de vote
Redirigez les joueurs vers le vote avec cette structure d’URL :
https://metin2-toplist.net/vote.{lang}/{server_id}-{server_slug}/{account_id}
Exemples :
https://metin2-toplist.net/vote.en/123-awesome-server/PlayerName
https://metin2-toplist.net/vote.de/123-awesome-server/PlayerName
https://metin2-toplist.net/vote.tr/123-awesome-server/PlayerName
Langues prises en charge : en, de, es, pl, tr, ro, it, pt, hu, gr, cz
Format de réponse
L’API renvoie une réponse JSON avec la structure suivante :
{
"success": true,
"voted": true,
"last_vote": "2025-11-11T14:30:00Z",
"next_vote_in": 0,
"message": "Vote verified successfully"
}
{
"success": true,
"voted": false,
"message": "No recent vote found"
}
{
"success": false,
"message": "Invalid API token"
}
Champs de la réponse
| Champ | Type | Description |
|---|---|---|
success |
boolean | Indique si la requête API a réussi |
voted |
boolean | Indique si un vote valide a été trouvé (présent uniquement si success=true) |
last_vote |
string | Horodatage ISO 8601 du dernier vote (présent uniquement si voted=true) |
next_vote_in |
integer | Secondes restantes avant le prochain vote autorisé (uniquement si voted=true) |
message |
string | Message décrivant le résultat |
Exemples de code
Exemple PHP
<?php
function checkVote($apiToken, $playerIP) {
$url = "https://metin2-toplist.net/api/check-vote";
$params = http_build_query([
'api_token' => $apiToken,
'ip' => $playerIP
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . '?' . $params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode !== 200) {
return ['success' => false, 'message' => 'API request failed'];
}
return json_decode($response, true);
}
$result = checkVote('YOUR_API_TOKEN', $_SERVER['REMOTE_ADDR']);
if ($result['success'] && $result['voted']) {
echo "Vote verified! Rewarding player...";
}
?>
Exemple Python
import requests
def check_vote(api_token, player_ip):
url = "https://metin2-toplist.net/api/check-vote"
params = {'api_token': api_token, 'ip': player_ip}
try:
response = requests.get(url, params=params, timeout=10)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
return {'success': False, 'message': f'API request failed: {str(e)}'}
result = check_vote('YOUR_API_TOKEN', '123.456.789.012')
if result.get('success') and result.get('voted'):
print("Vote verified! Rewarding player...")
Exemple C++ (serveurs de jeu)
#include <curl/curl.h>
#include <string>
#include <sstream>
static size_t WriteCallback(void* contents, size_t size, size_t nmemb, void* userp) {
((std::string*)userp)->append((char*)contents, size * nmemb);
return size * nmemb;
}
bool CheckVote(const std::string& apiToken, const std::string& playerIP) {
CURL* curl = curl_easy_init();
if (!curl) return false;
std::string readBuffer;
std::ostringstream url;
url << "https://metin2-toplist.net/api/check-vote"
<< "?api_token=" << apiToken
<< "&ip=" << playerIP;
curl_easy_setopt(curl, CURLOPT_URL, url.str().c_str());
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &readBuffer);
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L);
curl_easy_setopt(curl, CURLOPT_TIMEOUT, 10L);
CURLcode res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
return (res == CURLE_OK) && (readBuffer.find("\"voted\":true") != std::string::npos);
}
void OnPlayerRequestReward(const std::string& playerName, const std::string& playerIP) {
if (CheckVote("YOUR_API_TOKEN", playerIP)) {
GiveItemToPlayer(playerName, REWARD_ITEM_VNUM, REWARD_COUNT);
SendNotice("Vote verified! You received your reward!");
} else {
SendNotice("No valid vote found. Please vote first!");
}
}
Exemple JavaScript/Node.js
async function checkVote(apiToken, playerIP) {
const url = new URL('https://metin2-toplist.net/api/check-vote');
url.searchParams.append('api_token', apiToken);
url.searchParams.append('ip', playerIP);
try {
const response = await fetch(url, {
method: 'GET',
headers: { 'Accept': 'application/json' }
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return await response.json();
} catch (error) {
return { success: false, message: error.message };
}
}
checkVote('YOUR_API_TOKEN', '123.456.789.012').then(result => {
if (result.success && result.voted) {
console.log('Vote verified! Rewarding player...');
}
});
Guide d’intégration
Conservez toujours votre token API de manière sécurisée et ne l’exposez jamais côté client. Les requêtes doivent être effectuées depuis votre backend.
Étape 1 : Créer un bouton/commande de vote
Ajoutez un bouton sur votre site ou une commande en jeu qui redirige les joueurs vers la page de vote de votre serveur : https://metin2-toplist.net/servers/YOUR-SERVER-SLUG.
Étape 2 : Implémenter la vérification
Lorsque le joueur réclame sa récompense (via le site ou en jeu), vérifiez qu’il a voté :
- Récupérez l’adresse IP du joueur
- Effectuez une requête vers notre endpoint de vérification
- Analysez la réponse JSON
- Si
votedvaut true, accordez la récompense - Enregistrez la distribution pour éviter les doublons
Étape 3 : Gérer les récompenses
Bonnes pratiques recommandées :
- Suivi des récompenses : Enregistrez dans votre base les votes déjà récompensés pour éviter les doublons
- Respect du cooldown : Respectez l’intervalle de 24 heures entre deux votes
- Gestion des erreurs : Gérez les erreurs API et informez les joueurs en conséquence
- Journalisation : Conservez des logs des vérifications pour le debug et l’analyse
Flux d’exemple
Dépannage
Erreur « Invalid API token »
Solution : Vérifiez que vous utilisez le token API fourni dans votre tableau de bord et qu’il ne contient pas d’espaces ou caractères en trop.
Vote non détecté après le vote du joueur
Causes possibles :
- Le joueur utilise un VPN ou un proxy (les IP ne correspondent pas)
- Le vote n’a pas encore été traité (attendez 30 secondes et réessayez)
- Mauvaise adresse IP envoyée à l’API
- Le joueur a voté pour un autre serveur
Timeout ou erreurs de connexion API
Solution : Assurez-vous que votre serveur peut effectuer des requêtes HTTPS sortantes. Vérifiez votre pare-feu et implémentez une logique de nouvelle tentative avec backoff exponentiel.
Les joueurs reçoivent plusieurs fois la même récompense
Solution : Conservez un suivi local des votes récompensés et ne distribuez chaque vote qu’une seule fois.
Problèmes avec les adresses IPv6
Solution : Envoyez l’adresse IPv6 complète. Notre API accepte IPv4 et IPv6.
Public Server Listing API (v1)
List, submit, and claim Metin2 servers programmatically. Perfect for other toplists, server management tools, or custom integrations.
https://metin2-toplist.net/api/v1
Rate Limits
| Endpoint | Method | Limit | Auth |
|---|---|---|---|
/api/v1/servers | GET | 60/min | — |
/api/v1/servers/{slug} | GET | 60/min | — |
/api/v1/servers | POST | 3/hour | — |
/api/v1/servers/claim | POST | 10/hour | ✅ |
List Servers
Retrieve a paginated list of active, launched servers. Supports filtering by category and language.
| Parameter | Type | Default | Description |
|---|---|---|---|
category | string | — | Filter by category: oldschool, newschool, fun, pvp, pvm, pve |
language | string | — | Filter by language code: EN, DE, TR, etc. |
sort | string | votes | Sort order: votes, newest, name |
page | integer | 1 | Page number |
per_page | integer | 25 | Results per page (max 50) |
curl -H "Accept: application/json" \
"https://metin2-toplist.net/api/v1/servers?category=pvp&language=EN&per_page=10"
Submit a New Server
Submit a new server listing via the API. The server enters a moderation queue and must be approved before it appears publicly.
All API-submitted servers start as inactive and require manual approval. This prevents spam and ensures listing quality.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | ✅ | Server name (max 255 chars, must be unique) |
description | string | ✅ | Server description (min 20, max 5000 chars) |
website_url | string | — | Server website URL |
discord_url | string | — | Discord invite URL |
languages | array | ✅ | Language codes, e.g. ["EN", "DE"] (min 1, max 5) |
category | string | — | One of: oldschool, newschool, fun, pvp, pvm, pve |
launch_date | string | — | Future launch date (YYYY-MM-DD) |
owner_email | string | — | Contact email (optional, not shown publicly) |
curl -X POST "https://metin2-toplist.net/api/v1/servers" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"name": "Dragon Kingdom",
"description": "A classic PvP experience with custom dungeons and weekly events.",
"languages": ["EN", "DE"],
"category": "pvp",
"website_url": "https://dragon-kingdom.com",
"discord_url": "https://discord.gg/example"
}'
{
"success": true,
"message": "Server submitted successfully!",
"data": {
"id": 42,
"slug": "dragon-kingdom",
"status": "pending_review"
},
"claim_token": "a1b2c3d4...80 characters",
"note": "Save this token! Use it to claim your listing."
}
Claim Token System
When you submit a server, you receive a unique 80-character claim token. This token lets you link the listing to your account later.
The claim token is shown only once in the API response. Save it immediately — we store only the hash.
Submit
POST your server to /api/v1/servers and save the claim_token from the response.
Register
Create an account and paste the token in the optional "Claim Token" field.
Manage
Your server is now linked to your account with full dashboard access.
Error Codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Server created (pending review) |
401 | Authentication required (claim endpoint) |
404 | Server not found / invalid claim token |
409 | Server already claimed |
410 | Claim token expired |
422 | Validation error / spam rejected |
429 | Rate limit exceeded |
Integration Examples
$response = file_get_contents('https://metin2-toplist.net/api/v1/servers?per_page=10');
$data = json_decode($response, true);
foreach ($data['data'] as $server) {
echo $server['name'] . ' — ' . $server['vote_count'] . ' votes' . PHP_EOL;
}
const res = await fetch('https://metin2-toplist.net/api/v1/servers?category=pvp');
const { data, meta } = await res.json();
data.forEach(server => {
console.log(`${server.name}: ${server.vote_count} votes`);
});
import requests
resp = requests.get('https://metin2-toplist.net/api/v1/servers', params={
'language': 'DE',
'sort': 'newest',
'per_page': 20
})
servers = resp.json()['data']
for s in servers:
print(f"{s['name']} — {s['vote_count']} votes")
Support & ressources
Testez votre intégration en profondeur avec un compte de test avant de la déployer en production. Gérez tous les cas limites et scénarios d’erreur.