Documentazione API
Sistema di verifica voti Metin2
Ricompense di voto facili, gratuite e affidabili per il tuo server privato Metin2
Il nostro sistema di verifica dei voti è una soluzione moderna e innovativa progettata specificamente per i server privati Metin2. Offre ai giocatori un modo coinvolgente per votare il loro server preferito ricevendo allo stesso tempo vantaggi in game.
Il sistema è sia semplice da implementare sia estremamente affidabile, rendendolo la scelta ideale per gli amministratori che vogliono aumentare il coinvolgimento dei giocatori e la visibilità del proprio server.
Il nostro obiettivo è creare una situazione win-win per giocatori e proprietari. I giocatori vengono ricompensati per la loro fedeltà, mentre i server ottengono maggiore visibilità e attività.
Sistema Vote4Buff (consigliato)
Sistema completo di voto e ricompense in game con interfaccia personalizzata
Vote4Buff è la nostra soluzione premium tutto-in-uno che include una splendida interfaccia in game, comunicazione WebSocket e integrazione completa lato server. I giocatori possono votare, scegliere tra più pool di bonus e ricevere ricompense istantanee senza uscire dal gioco!
Architettura del sistema
Il sistema Vote4Buff è composto da tre elementi principali:
Lato client
- Sistema UI Python (uivote4buff.py)
- Risorse grafiche personalizzate
- Integrazione WebSocket in C++
- Supporto per 11 lingue
Lato server
- Integrazione API in C++
- Gestione dei pool di bonus
- Sistema di ricompense tramite oggetti
- Monitoraggio degli effetti in tempo reale
La nostra piattaforma
- API di verifica dei voti
- Tracciamento basato sull’account
- Protezione anti-cheat
- Stato dei voti in tempo reale
Funzionalità principali
Ideale per: Gli amministratori che desiderano una soluzione professionale pronta all’uso senza trascorrere settimane nello sviluppo personalizzato. Configura i pool, integra i file e sei pronto!
Scarica i file Vote4Buff
Ottieni tutti i file necessari per l’integrazione client e server
Vote4Buff è progettato per la base sorgente martysama0134 v5.8. Se utilizzi un’altra base, potrebbero essere necessarie alcune modifiche.
Contenuto del pacchetto
File client
- File UI Python (uivote4buff.py)
- Modifiche ai file di gioco
- Risorse e grafica dell’interfaccia
- File lingua per 11 lingue
- Implementazione WebSocket in C++
- Script UI
Include libcurl.dll (32 bit incluso, versione 64 bit disponibile)
File server
- Configurazione di char.h
- Modifiche al sistema degli effetti
- Integrazione dei comandi chat
- Strato di comunicazione con l’API
- Sistema di gestione dei bonus
Tutte le modifiche sorgente C++ necessarie sono incluse
Per favore, accedi per scaricare i file Vote4Buff.
Guida alla configurazione
Configura pool di bonus, ricompense e impostazioni API
Tutta la configurazione di Vote4Buff avviene nel file char.h del tuo server. Qui trovi esempi dettagliati per ogni opzione.
Passo 1: Credenziali API
Per prima cosa configura ID server e token API (disponibili nella tua dashboard):
// 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 !!!
Passo 2: Configura i pool di bonus
Puoi definire fino a 3 pool di bonus tra cui i giocatori possono scegliere. Ogni pool può contenere più 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
},
};
Tipi di bonus comuni: 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 e molti altri.
Passo 3: Ricompense oggetti (opzionale)
Configura gli oggetti che i giocatori riceveranno automaticamente al termine del voto:
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
};
Passo 4: Impostazioni cambio bonus
Gestisci cooldown e costo quando i giocatori vogliono cambiare pool senza rivotare:
// 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)
Nota: Dopo aver votato i giocatori possono scegliere un pool gratuitamente. Il cooldown e il prezzo si applicano solo se desiderano cambiarlo senza rivotare.
Guida all’installazione
Istruzioni passo passo per integrare Vote4Buff
Assicurati di avere backup dei tuoi file client e server! Convenzione: i file con prefisso __ richiedono una fusione, gli altri possono essere copiati direttamente.
Installazione lato server
Configura char.h
Apri Source/Server/__char.h dal pacchetto scaricato.
- Trova
class CBuffOnAttributes;e aggiungi il codice di configurazione sopra (vedi sezione Configurazione) - Imposta
s_VOTE4BUFF_SERVER_IDes_VOTE4BUFF_API_TOKEN - Configura pool di bonus e ricompense oggetti
- Trova
bool DragonSoul_RefineWindow_CanRefine();e aggiungi le dichiarazioni pubbliche richieste
Applica le modifiche server
Integra i file lato server del pacchetto:
__affect.h- Unisci le modifiche al tuo affect.h__chat_affect.cpp- Aggiungi la gestione degli effetti Vote4Buff__cmd_general.cpp- Inserisci la gestione dei comandi__desc_client.cpp- Aggiorna il descrittore client
I file con prefisso __ indicano che devi fondere le modifiche con i tuoi file.
Ricompila il core
Compila il tuo game server con le nuove modifiche.
make clean && make Installazione lato client
File UI Python
Dal folder Client/root/:
- Copia
uivote4buff.pynella cartellaroot/del client - Modifica i seguenti file come indicato:
__constInfo.py__game.py__interfaceModule.py__uiAffectShower.py
Grafica e script UI
- Copia
Client/ui/game/vote4buff/nella directoryui/game/ - Copia
Client/uiscript/vote4buffwindow.pynella tua cartella uiscript
File di lingua
Aggiungi le stringhe di lingua da Client/locale/:
- Aggiungi il contenuto di
__locale_game.txtal tuolocale_game.txt - Aggiungi il contenuto di
__locale_interface.txtal tuolocale_interface.txt
Lingue disponibili: EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ
Modifiche client in C++
Da Source/Client/UserInterface/:
- Copia
M2WebSocket.cppeM2WebSocket.hnella cartella UserInterface - Integra le modifiche dei file con prefisso
__ - Assicurati che
libcurl.dllsia presente nella directory del client (32 bit incluso, scarica la versione 64 bit se necessario)
Aggiungi un pulsante UI (opzionale)
Vote4Buff non aggiunge un pulsante di default. Devi chiamare ToggleVote4Buff() da qualche parte nella tua UI. Per esempio:
- Aggiungi un pulsante al SystemDialog
- Associalo a un tasto rapido
- Aggiungilo al menu delle scorciatoie
Oppure usa la classe Vote4BuffButton inclusa per creare un pulsante trascinabile.
Ricompila il client
Ricompila l’eseguibile client con le nuove modifiche.
Test
Metti alla prova l’integrazione:
- Accedi al tuo server
- Apri la finestra Vote4Buff
- Vota sulla nostra piattaforma: https://metin2-toplist.net/vote/en/YOUR_SERVER_ID-server-name/YOUR_ACCOUNT_ID
- Torna in game e verifica il voto
- Scegli un pool di bonus e controlla gli effetti applicati
- Controlla la ricezione delle ricompense oggetto
I tuoi giocatori ora possono votare e ricevere automaticamente le ricompense. L’interfaccia Vote4Buff indicherà quando possono votare, permetterà di scegliere i pool di bonus e mostrerà i timer degli effetti attivi.
Vantaggi per gli amministratori
Promozione gratuita
La maggior parte dei giocatori scopre nuovi server tramite le toplist: uno strumento di marketing essenziale
Configurazione semplice
Documentazione dettagliata e guide passo passo
Zero codice richiesto
Processo di integrazione REST chiaro e diretto
Prestazioni ottimizzate
La verifica lato client riduce il carico sul tuo server
Alta affidabilità
Sistema collaudato con protezione anti frode integrata
Verifica dei voti
Assicurati che i giocatori abbiano davvero votato prima di dare ricompense
Vantaggi per i giocatori
Come funziona il sistema?
Il flusso è semplice e intuitivo per i giocatori. La verifica dei voti avviene tramite la nostra API per garantire che solo i voti legittimi vengano convalidati.
Primi passi - Guida rapida
Scegli il metodo di integrazione più adatto alle tue esigenze:
Sistema Vote4Buff
Soluzione completa con UI personalizzata, comunicazione WebSocket e ricompense automatiche.
- Interfaccia completa in game
- Pool di bonus multipli
- Ricompense automatiche tramite oggetti
- Timer in tempo reale
- Supporto a 11 lingue
Integrazione API personalizzata
Crea la tua implementazione usando la nostra API REST per il massimo controllo.
- Personalizzazione completa
- Design dell’interfaccia proprietario
- Logica ricompense personalizzata
- Basato su IP o account
Passaggi generali
Registra il tuo server
Crea un account e aggiungi il tuo server alla nostra toplist su https://metin2-toplist.net/servers/create
Recupera le credenziali API
Trova ID server e token API univoci nella dashboard del server. Sono necessari per l’autenticazione.
Scegli il metodo di integrazione
Scarica Vote4Buff per una soluzione pronta o integra la nostra API per un’implementazione personalizzata.
Testa e distribuisci
Testa accuratamente il sistema di voto e poi pubblicalo sul tuo server live.
Endpoint API (per implementazioni personalizzate)
Se utilizzi il sistema Vote4Buff (consigliato), questa API è già integrata! Questa sezione è pensata per gli amministratori che desiderano creare integrazioni personalizzate.
https://metin2-toplist.net/api/check-vote
Parametri richiesti
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
api_token |
string | Sì | Il tuo token API univoco |
ip |
string | Opzionale* | Indirizzo IP del giocatore (IPv4 o IPv6) |
account_id |
string | Opzionale* | ID account o nickname del giocatore per un tracciamento preciso |
Per risultati ottimali utilizza <code>account_id</code> per identificare con precisione i giocatori. Il metodo basato su <code>ip</code> può essere meno affidabile se usano VPN o cambiano posizione.
Formato URL di voto
Reindirizza i giocatori al voto usando questa struttura URL:
https://metin2-toplist.net/vote.{lang}/{server_id}-{server_slug}/{account_id}
Esempi:
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
Lingue supportate: en, de, es, pl, tr, ro, it, pt, hu, gr, cz
Formato di risposta
L’API restituisce una risposta JSON con la seguente struttura:
{
"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"
}
Campi della risposta
| Campo | Tipo | Descrizione |
|---|---|---|
success |
boolean | Indica se la richiesta API è andata a buon fine |
voted |
boolean | Indica se è stato trovato un voto valido (presente solo se success=true) |
last_vote |
string | Timestamp ISO 8601 dell’ultimo voto (presente solo se voted=true) |
next_vote_in |
integer | Secondi rimanenti prima del prossimo voto consentito (solo se voted=true) |
message |
string | Messaggio descrittivo del risultato |
Esempi di codice
Esempio 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...";
}
?>
Esempio 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...")
Esempio C++ (server di gioco)
#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!");
}
}
Esempio 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...');
}
});
Guida all’integrazione
Conserva sempre in modo sicuro il tuo token API e non esporlo mai lato client. Effettua le richieste dal tuo backend.
Passo 1: Crea un pulsante/comando di voto
Aggiungi un pulsante sul tuo sito o un comando in game che reindirizzi i giocatori alla pagina di voto del tuo server: https://metin2-toplist.net/servers/YOUR-SERVER-SLUG.
Passo 2: Implementa la verifica
Quando il giocatore richiede la ricompensa (dal sito o in game), verifica che abbia votato:
- Ottieni l’indirizzo IP del giocatore
- Effettua una richiesta al nostro endpoint di verifica
- Analizza la risposta JSON
- Se
votedè true, assegna la ricompensa - Registra la distribuzione per evitare duplicati
Passo 3: Gestisci le ricompense
Buone pratiche consigliate:
- Tracciamento ricompense: Memorizza i voti già ricompensati per evitare duplicati
- Rispetta il cooldown: Rispetta l’intervallo di 24 ore tra un voto e l’altro
- Gestione errori: Gestisci gli errori API e informa i giocatori di conseguenza
- Log: Conserva i log delle verifiche per debug e analisi
Flusso di esempio
Risoluzione problemi
Errore "Invalid API token"
Soluzione: Verifica di usare il token API fornito nella dashboard e che non contenga spazi o caratteri extra.
Il voto non viene rilevato dopo che il giocatore ha votato
Possibili cause:
- Il giocatore utilizza un VPN o proxy (gli IP non combaciano)
- Il voto non è stato ancora processato (attendi 30 secondi e riprova)
- Indirizzo IP inviato all’API errato
- Il giocatore ha votato per un altro server
Timeout o errori di connessione all’API
Soluzione: Assicurati che il tuo server possa effettuare richieste HTTPS in uscita. Controlla il firewall e implementa tentativi con backoff esponenziale.
I giocatori ricevono più volte la stessa ricompensa
Soluzione: Tieni traccia localmente dei voti già ricompensati ed eroga ogni voto una sola volta.
Problemi con gli indirizzi IPv6
Soluzione: Invia l’indirizzo IPv6 completo. La nostra API accetta sia IPv4 che 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")
Supporto e risorse
Testa a fondo la tua integrazione con un account di prova prima della produzione. Gestisci tutti i casi limite e gli scenari d’errore.