API-Dokumentation

Metin2 Vote-Verification-System

Einfach, kostenlos & zuverlässig – Belohnungen für Stimmen auf deinem Metin2-Privatserver

Was ist das Vote-Verification-System?

Unser Vote-Verification-System ist eine moderne, speziell für Metin2-Privatserver entwickelte Lösung. Spieler können für ihren Lieblingsserver abstimmen und erhalten gleichzeitig Ingame-Vorteile.

Das System ist sowohl leicht zu implementieren als auch äußerst zuverlässig – ideal für Serverbetreiber, die Spielerbindung und Sichtbarkeit erhöhen möchten.

Unser Ziel ist ein Win-win für Spieler und Serverbetreiber. Spieler werden für ihre Treue belohnt, während Server mehr Sichtbarkeit und Aktivität erhalten.

Vote4Buff-System (empfohlen)

Komplettes Ingame-Voting- und Belohnungssystem mit individueller UI

Was ist Vote4Buff?

Vote4Buff ist unsere Premium All-in-One Voting-Lösung mit moderner Ingame-UI, WebSocket-Kommunikation und vollständiger Serverintegration. Spieler stimmen ab, wählen Bonus-Pools und erhalten sofort Belohnungen – ohne das Spiel zu verlassen!

Systemarchitektur

Das Vote4Buff-System besteht aus drei Hauptkomponenten:

Client-Seite

Python-UI-System (uivote4buff.py)
Individuelle UI-Grafiken & Assets
C++ WebSocket-Integration
Unterstützung für 11 Sprachen

Server-Seite

C++ API-Integration
Management der Bonus-Pools
Item-Belohnungssystem
Echtzeit-Tracking der Effekte

Unsere Plattform

Vote-Verification-API
Accountbasierte Nachverfolgung
Anti-Cheat-Schutz
Echtzeit-Stimmenstatus

Schlüssel-Features

Mehrere Bonus-Pools: Bis zu 3 konfigurierbare Bonus-Pools, aus denen Spieler wählen können

Item-Belohnungen: Automatische Items nach erfolgreicher Stimme

Echtzeit-UI: Countdown-Timer und Effekt-Tracking direkt im Spiel

WebSocket-Kommunikation: Sofortige Verifizierung ohne Seitenreload

Mehrsprachig: Unterstützt 11 Sprachen (EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ)

Anpassbare Belohnungen: Definiere Boni, Laufzeiten und Preise flexibel

Perfekt für: Serverbetreiber, die eine professionelle Plug-and-Play-Lösung wünschen, ohne Wochen in Eigenentwicklung zu investieren. Bonus-Pools konfigurieren, Dateien integrieren – fertig!

Vote4Buff-Dateien herunterladen

Alle Dateien für die Client- und Serverintegration

Voraussetzungen

Vote4Buff wurde für die Source-Basis martysama0134 v5.8 entwickelt. Bei anderen Quellen können Anpassungen erforderlich sein.

Paketinhalt

Client-Dateien

Python-UI-Dateien (uivote4buff.py)
Modifizierte Game-Dateien
UI-Grafiken & Assets
11 Sprachdateien
C++ WebSocket-Implementierung
UI-Skripte

Enthält libcurl.dll (32-Bit enthalten, 64-Bit verfügbar)

Server-Dateien

char.h-Konfiguration
Anpassungen am Affect-System
Chat-Befehlsintegration
API-Kommunikationsschicht
Bonus-Management-System

Alle notwendigen C++-Quellcodeanpassungen inklusive

Anmeldung erforderlich

Bitte anmelden, um Vote4Buff-Dateien herunterzuladen.

Konfigurationsleitfaden

Bonus-Pools, Item-Belohnungen und API-Einstellungen konfigurieren

Die komplette Vote4Buff-Konfiguration erfolgt in der Datei char.h auf deinem Server. Nachfolgend findest du Beispiele für alle Optionen.

Schritt 1: API-Zugangsdaten

Trage deine Server-ID und deinen API-Token (im Dashboard zu finden) ein:

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

Schritt 2: Bonus-Pools konfigurieren

Definiere bis zu 3 Bonus-Pools, aus denen Spieler auswählen können. Jeder Pool kann mehrere Boni enthalten:

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
    },
};

Verfügbare APPLY-Typen

Beliebte Bonus-Typen: 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 und viele mehr!

Schritt 3: Item-Belohnungen (optional)

Lege Items fest, die Spieler automatisch beim Abstimmen erhalten:

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

Schritt 4: Wechsel-Einstellungen

Bestimme Abklingzeit und Preis, wenn Spieler zwischen Bonus-Pools wechseln möchten:

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)

Hinweis: Nach einer Stimme können Spieler kostenlos einen Bonus-Pool wählen. Cooldown und Preis gelten nur, wenn sie später ohne erneute Stimme wechseln möchten.

Installationsleitfaden

Schritt-für-Schritt-Anleitung zur Integration von Vote4Buff

Vorbereitung

Erstelle Backups deiner Client- und Serverdateien! Dateinamen mit __ müssen gemerged werden, Dateien ohne Präfix können direkt übernommen werden.

Installation auf dem Server

1

char.h konfigurieren

Öffne Source/Server/__char.h aus dem Download-Paket.

Suche nach class CBuffOnAttributes; und füge die Konfiguration darüber ein (siehe Konfigurationskapitel)
Setze s_VOTE4BUFF_SERVER_ID und s_VOTE4BUFF_API_TOKEN
Konfiguriere deine Bonus-Pools und Item-Belohnungen
Suche bool DragonSoul_RefineWindow_CanRefine(); und ergänze die öffentlichen Methodendeklarationen

2

Serveranpassungen übernehmen

Integriere die Serverdateien aus dem Paket:

__affect.h – übernimm die Änderungen in deine bestehende affect.h
__chat_affect.cpp – Vote4Buff-Affect-Logik hinzufügen
__cmd_general.cpp – Befehlsverarbeitung ergänzen
__desc_client.cpp – Client-Descriptor anpassen

Dateien mit __ im Namen müssen mit deinen vorhandenen Dateien zusammengeführt werden.

3

Game-Core neu kompilieren

Kompiliere deinen Game-Server mit den neuen Anpassungen.

make clean && make

Installation im Client

4

Python-UI-Dateien

Im Ordner Client/root/:

Kopiere uivote4buff.py in den root/-Ordner deines Clients
Passe folgende Dateien gemäß Anleitung an:
- __constInfo.py
- __game.py
- __interfaceModule.py
- __uiAffectShower.py

5

UI-Grafiken & Skripte

Kopiere den Ordner Client/ui/game/vote4buff/ in dein Pack-Verzeichnis ui/game/
Kopiere Client/uiscript/vote4buffwindow.py in den uiscript-Ordner

6

Sprachdateien

Füge die Sprachtexte aus Client/locale/ hinzu:

Hänge den Inhalt von __locale_game.txt an deine locale_game.txt an
Hänge den Inhalt von __locale_interface.txt an deine locale_interface.txt an

Verfügbare Sprachen: EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ

7

C++-Clientanpassungen

Im Ordner Source/Client/UserInterface/:

Kopiere M2WebSocket.cpp und M2WebSocket.h in den UserInterface-Ordner
Übernehme Änderungen aus Dateien mit __-Präfix in deine bestehenden Dateien
Stelle sicher, dass libcurl.dll im Client-Verzeichnis liegt (32-Bit enthalten, 64-Bit ggf. herunterladen)

8

UI-Button hinzufügen (optional)

Vote4Buff erstellt keinen Standardbutton. Du musst ToggleVote4Buff() an einer passenden Stelle aufrufen. Zum Beispiel:

Button im Systemdialog platzieren
Hotkey binden
Im QuickSlot-Menü hinterlegen

Oder verwende die enthaltene Vote4BuffButton-Klasse für ein verschiebbares Icon.

9

Client neu kompilieren

Kompiliere deinen Client mit den neuen Anpassungen.

10

Testen

Teste die Integration:

Melde dich auf deinem Server an
Öffne das Vote4Buff-Fenster
Stimme auf unserer Plattform ab: https://metin2-toplist.net/vote/en/YOUR_SERVER_ID-server-name/YOUR_ACCOUNT_ID
Kehre ins Spiel zurück und überprüfe die Stimme
Wähle einen Bonus-Pool und prüfe die Effekte
Kontrolliere, ob Item-Belohnungen angekommen sind

Installation abgeschlossen!

Deine Spieler können jetzt abstimmen und automatisch Belohnungen erhalten. Die Vote4Buff-UI zeigt verfügbare Stimmen, Bonus-Auswahl und Countdown-Timer für aktive Effekte an.

Vorteile für Serverbetreiber

Kostenlose Promotion

Die meisten neuen Spieler finden Server über Toplisten – ein unverzichtbares Marketing-Tool

Einfache Konfiguration

Ausführliche Dokumentation und Schritt-für-Schritt-Anleitungen

Keine Programmierung nötig

Einfacher REST-API-Workflow ohne tiefen Code-Eingriff

Optimierte Performance

Vote-Prüfung belastet deinen Server kaum

Hohe Zuverlässigkeit

Bewährtes System mit integriertem Betrugsschutz

Sichere Verifizierung

Belohnungen nur nach bestätigter Stimme

Vorteile für Spieler

Erhalten Ingame-Belohnungen für jede Stimme

Intuitive Voting-Oberfläche

Transparente Anzeige der Abklingzeit

Garantierte und nachvollziehbare Belohnungsausgabe

Wie funktioniert das System?

Der Ablauf ist für Spieler klar und einfach. Die Stimmenprüfung erfolgt über unsere API, damit nur echte Stimmen belohnt werden.

1

Spieler klickt auf Vote-Button

Auf deiner Webseite oder in der Ingame-Oberfläche

2

Weiterleitung zur Voting-Seite

Der Spieler landet auf deiner Server-Seite in unserer Topliste

3

Spieler stimmt ab

Captcha lösen und Stimme abschicken

4

API-Verifizierung

Dein Server prüft die Stimme über unsere API

5

Belohnung auszahlen

Dein Server vergibt die Ingame-Belohnung

Erste Schritte – Schnellstart

Wähle die Integrationsmethode, die zu dir passt:

Vote4Buff-System

Komplettlösung mit eigener UI, WebSocket-Kommunikation und automatischer Belohnung.

✅ Vollständige Ingame-Oberfläche
✅ Mehrere Bonus-Pools
✅ Automatische Item-Belohnungen
✅ Countdown-Timer in Echtzeit
✅ Unterstützung für 11 Sprachen

Mit Vote4Buff starten

Eigene API-Integration

Baue deine eigene Umsetzung mit unserer REST-API für maximale Flexibilität.

🔧 Volle Anpassbarkeit
🔧 Eigene UI-Gestaltung
🔧 Individuelle Belohnungslogik
🔧 IP- oder Account-basiert

Basis-API nutzen

Allgemeine Schritte

1

Server registrieren

Erstelle ein Konto und füge deinen Server in unserer Topliste hinzu: https://metin2-toplist.net/servers/create

2

API-Zugangsdaten abrufen

Im Server-Dashboard findest du deine Server-ID und deinen API-Token. Beide werden für die Authentifizierung benötigt.

3

Integrationsweg wählen

Lade Vote4Buff für eine fertige Lösung herunter oder nutze die API für eine eigene Umsetzung.

4

Testen & live schalten

Teste das Votingsystem gründlich und veröffentliche es anschließend auf deinem Liveserver.

API-Endpunkt (für eigene Implementierungen)

Hinweis

Wenn du das Vote4Buff-System verwendest (empfohlen), ist diese API bereits integriert! Dieser Abschnitt richtet sich an Serverbetreiber, die eine eigene Umsetzung bauen möchten.

GET

https://metin2-toplist.net/api/check-vote

Benötigte Parameter

Parameter	Typ	Pflicht	Beschreibung
`api_token`	string	Ja	Dein eindeutiger API-Token
`ip`	string	Optional*	IP-Adresse des Spielers (IPv4 oder IPv6)
`account_id`	string	Optional*	Account-ID/Username des Spielers für genaue Zuordnung

*Entweder ip oder account_id (oder beides) muss angegeben werden

Für bestmögliche Ergebnisse verwende <code>account_id</code>, um Spieler eindeutig zu erkennen. Die <code>ip</code>-Variante kann ungenauer sein, wenn Spieler VPNs nutzen oder an unterschiedlichen Orten spielen.

URL-Struktur zum Voten

Leite Spieler mit dieser URL-Struktur zur Voting-Seite weiter:

https://metin2-toplist.net/vote.{lang}/{server_id}-{server_slug}/{account_id}

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

Unterstützte Sprachen: en, de, es, pl, tr, ro, it, pt, hu, gr, cz

Antwortformat

Die API liefert eine JSON-Antwort mit folgendem Aufbau:

Erfolgsantwort

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

Antwort ohne gültige Stimme

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

Fehlerantwort

{
    "success": false,
    "message": "Invalid API token"
}

Felder der Antwort

Feld	Typ	Beschreibung
`success`	boolean	Gibt an, ob die Anfrage erfolgreich war
`voted`	boolean	Gibt an, ob eine gültige Stimme gefunden wurde (nur bei success=true)
`last_vote`	string	ISO-8601-Zeitstempel der letzten Stimme (nur bei voted=true)
`next_vote_in`	integer	Sekunden bis zur nächsten möglichen Stimme (nur bei voted=true)
`message`	string	Beschreibung des Ergebnisses in Klartext

Code-Beispiele

PHP-Beispiel

PHP cURL-Implementierung

<?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!";
}
?>

Python-Beispiel

Python-Requests-Implementierung

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!")

C++-Beispiel (Game-Server)

C++ libcurl-Implementierung

#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!");
    }
}

JavaScript/Node.js-Beispiel

Node.js Fetch-Implementierung

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!');
    }
});

Integrations-Leitfaden

Security Best Practice

Bewahre deinen API-Token sicher auf und veröffentliche ihn niemals im Client. API-Aufrufe sollten immer über deinen Server erfolgen.

Schritt 1: Vote-Button/Befehl erstellen

Füge auf deiner Webseite oder im Spiel einen Button bzw. Befehl hinzu, der Spieler auf deine Voting-Seite unter https://metin2-toplist.net/servers/YOUR-SERVER-SLUG führt.

Schritt 2: Stimme prüfen

Wenn ein Spieler seine Belohnung anfordert, prüfe, ob er bereits abgestimmt hat:

IP-Adresse des Spielers ermitteln
API-Anfrage an den Check-Vote-Endpunkt senden
JSON-Antwort auswerten
Bei voted = true Belohnung vergeben
Belohnung lokal protokollieren, um Doppelvergaben zu vermeiden

Schritt 3: Belohnungen verwalten

Best Practices für die Belohnungsvergabe:

Belohnungen nachverfolgen: Speichere, welche Stimmen du bereits belohnt hast
Cooldown respektieren: Halte die 24-Stunden-Abklingzeit ein
Fehlerbehandlung: Gehe mit API-Fehlern sauber um und informiere Spieler
Logging: Protokolliere alle Prüfungen zur Analyse

Beispiel-Workflow

Spieler: Gibt im Spiel den Befehl /vote ein

↓

Server: Öffnet den Browser mit der Voting-Seite

↓

Spieler: Stimmt auf der Topliste ab

↓

Spieler: Gibt /claim ein oder klickt auf "Belohnung abholen"

↓

Server: Ruft die API mit der IP des Spielers auf

↓

API: Liefert voted=true zurück

↓

Server: Gewährt die Belohnung

Fehlerbehebung

Fehler "Invalid API token"

Lösung: Stelle sicher, dass du den korrekten API-Token aus deinem Dashboard verwendest. Achte auf Leerzeichen oder zusätzliche Zeichen.

Stimme wird nicht erkannt, obwohl der Spieler abgestimmt hat

Mögliche Ursachen:

Spieler nutzt VPN/Proxy (IP stimmt nicht überein)
Stimme wurde noch nicht verarbeitet (bis zu 30 Sekunden warten)
Falsche IP wird an die API gesendet
Spieler hat für einen anderen Server abgestimmt

API-Timeout oder Verbindungsfehler

Lösung: Stelle sicher, dass dein Server ausgehende HTTPS-Anfragen senden kann. Firewall prüfen und Retry-Logik mit Backoff implementieren.

Spieler erhalten Belohnungen mehrfach

Lösung: Verwalte lokal, welche Stimmen bereits belohnt wurden, damit jede Stimme nur einmal vergütet wird.

IPv6-Adressen funktionieren nicht

Lösung: Stelle sicher, dass die vollständige IPv6-Adresse übertragen wird. Unsere API unterstützt IPv4 und IPv6.

Support & Ressourcen

E-Mail-Support

Hilfe direkt per E-Mail erhalten

Support kontaktieren

Discord-Community

Tritt unserer Community bei

Discord beitreten

Profi-Tipp

Teste deine Integration ausführlich mit einem Testaccount, bevor du live gehst. Berücksichtige alle Sonderfälle und Fehlerzustände.

Schnellzugriffe

Schnellnavigation