Documentazione API

Sistema di verifica voti Metin2

Ricompense di voto facili, gratuite e affidabili per il tuo server privato Metin2

Che cos’è il sistema di verifica dei voti?

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

Che cos’è Vote4Buff?

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

Pool di bonus multipli: Fino a 3 pool configurabili tra cui i giocatori possono scegliere

Ricompense oggetti: Distribuzione automatica di oggetti dopo un voto valido

Interfaccia in tempo reale: Timer e monitoraggio effetti direttamente in game

Comunicazione WebSocket: Verifica istantanea senza ricaricare la pagina

Multilingue: Supporto per 11 lingue (EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ)

Ricompense personalizzabili: Configura bonus, durata e prezzi

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

Requisiti

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

Accesso richiesto

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):

C++

// 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:

C++

// 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
        // Add more bonuses if wanted
    },

    { // 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 APPLY disponibili

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:

C++

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:

C++

// 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

Prima di iniziare

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

1

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_ID e s_VOTE4BUFF_API_TOKEN
Configura pool di bonus e ricompense oggetti
Trova bool DragonSoul_RefineWindow_CanRefine(); e aggiungi le dichiarazioni pubbliche richieste

2

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.

3

Ricompila il core

Compila il tuo game server con le nuove modifiche.

make clean && make

Installazione lato client

4

File UI Python

Dal folder Client/root/:

Copia uivote4buff.py nella cartella root/ del client
Modifica i seguenti file come indicato:
- __constInfo.py
- __game.py
- __interfaceModule.py
- __uiAffectShower.py

5

Grafica e script UI

Copia Client/ui/game/vote4buff/ nella directory ui/game/
Copia Client/uiscript/vote4buffwindow.py nella tua cartella uiscript

6

File di lingua

Aggiungi le stringhe di lingua da Client/locale/:

Aggiungi il contenuto di __locale_game.txt al tuo locale_game.txt
Aggiungi il contenuto di __locale_interface.txt al tuo locale_interface.txt

Lingue disponibili: EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ

7

Modifiche client in C++

Da Source/Client/UserInterface/:

Copia M2WebSocket.cpp e M2WebSocket.h nella cartella UserInterface
Integra le modifiche dei file con prefisso __
Assicurati che libcurl.dll sia presente nella directory del client (32 bit incluso, scarica la versione 64 bit se necessario)

8

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.

9

Ricompila il client

Ricompila l’eseguibile client con le nuove modifiche.

10

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

Installazione completata!

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

Ricevono ricompense in game ad ogni voto

Interfaccia di voto intuitiva

Visualizzazione chiara del tempo di attesa tra i voti

Sistema affidabile per l’erogazione delle ricompense

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.

1

Il giocatore clicca sul pulsante di voto

Dal tuo sito web o dall’interfaccia in game

2

Redirect alla pagina di voto

Il giocatore viene reindirizzato alla pagina di voto del tuo server sulla nostra toplist

3

Il giocatore vota

Completa il CAPTCHA e invia il voto

4

Verifica API

Il tuo server interroga la nostra API per verificare il voto

5

Ricompensa il giocatore

Il tuo server assegna la ricompensa in game

Primi passi - Guida rapida

Scegli il metodo di integrazione più adatto alle tue esigenze:

CONSIGLIATO

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

Inizia con Vote4Buff

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

Usa l’API di base

Passaggi generali

1

Registra il tuo server

Crea un account e aggiungi il tuo server alla nostra toplist su https://metin2-toplist.net/servers/create

2

Recupera le credenziali API

Trova ID server e token API univoci nella dashboard del server. Sono necessari per l’autenticazione.

3

Scegli il metodo di integrazione

Scarica Vote4Buff per una soluzione pronta o integra la nostra API per un’implementazione personalizzata.

4

Testa e distribuisci

Testa accuratamente il sistema di voto e poi pubblicalo sul tuo server live.

Endpoint API (per implementazioni personalizzate)

Nota

Se utilizzi il sistema Vote4Buff (consigliato), questa API è già integrata! Questa sezione è pensata per gli amministratori che desiderano creare integrazioni personalizzate.

GET

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

*Devi fornire ip o account_id (o entrambi)

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:

Risposta di successo

{
    "success": true,
    "voted": true,
    "last_vote": "2025-11-11T14:30:00Z",
    "next_vote_in": 0,
    "message": "Vote verified successfully"
}

Risposta senza voto trovato

{
    "success": true,
    "voted": false,
    "message": "No recent vote found"
}

Risposta di errore

{
    "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

Implementazione PHP con cURL

<?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);
}

// Usage Example
$apiToken = 'YOUR_API_TOKEN_HERE';
$playerIP = $_SERVER['REMOTE_ADDR']; // Or get from your game server

$result = checkVote($apiToken, $playerIP);

if ($result['success'] && $result['voted']) {
    // Player has voted! Give reward
    echo "Vote verified! Rewarding player...";
    giveReward($playerName); // Your reward function
} else {
    echo "No valid vote found. Please vote first!";
}
?>

Esempio Python

Implementazione Python con Requests

import requests
import json

def check_vote(api_token, player_ip):
    """
    Check if a player has voted for the server
    """
    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)}'}

# Usage Example
api_token = 'YOUR_API_TOKEN_HERE'
player_ip = '123.456.789.012'

result = check_vote(api_token, player_ip)

if result.get('success') and result.get('voted'):
    print("Vote verified! Rewarding player...")
    # Give reward to player
else:
    print("No valid vote found. Please vote first!")

Esempio C++ (server di gioco)

Implementazione C++ con libcurl

#include <curl/curl.h>
#include <string>
#include <sstream>

// Callback function for cURL
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;
    CURLcode res;
    std::string readBuffer;

    curl = curl_easy_init();
    if(curl) {
        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);

        res = curl_easy_perform(curl);
        curl_easy_cleanup(curl);

        if(res == CURLE_OK) {
            // Parse JSON response (you'll need a JSON library like nlohmann/json)
            // Check if readBuffer contains "\"voted\":true"
            return readBuffer.find("\"voted\":true") != std::string::npos;
        }
    }
    return false;
}

// Usage in your game server
void OnPlayerRequestReward(const std::string& playerName, const std::string& playerIP) {
    std::string apiToken = "YOUR_API_TOKEN_HERE";

    if(CheckVote(apiToken, playerIP)) {
        // Give reward to player
        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

Implementazione Node.js con Fetch

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 error! status: ${response.status}`);
        }

        return await response.json();
    } catch (error) {
        console.error('API request failed:', error);
        return { success: false, message: error.message };
    }
}

const apiToken = 'YOUR_API_TOKEN_HERE';
const playerIP = '123.456.789.012';

checkVote(apiToken, playerIP).then(result => {
    if (result.success && result.voted) {
        console.log('Vote verified! Rewarding player...');
        // Give reward to player
    } else {
        console.log('No valid vote found. Please vote first!');
    }
});

Guida all’integrazione

Buone pratiche di sicurezza

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

Giocatore: digita il comando /vote in game

↓

Server: apre il browser sulla pagina di voto

↓

Giocatore: vota sulla toplist

↓

Giocatore: digita /claim o clicca "Ricevi ricompensa"

↓

Server: chiama l’API con l’IP del giocatore

↓

API: restituisce voted=true

↓

Server: assegna la ricompensa al giocatore

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.

Supporto e risorse

Supporto email

Richiedi assistenza via email

Contatta il supporto

Community Discord

Unisciti alla nostra community

Entra su Discord

Suggerimento pro

Testa a fondo la tua integrazione con un account di prova prima della produzione. Gestisci tutti i casi limite e gli scenari d’errore.

Link rapidi

Navigazione rapida