Documentație API

Sistemul de verificare a voturilor Metin2

Recompense pentru voturi, ușor de implementat și de încredere pentru serverul tău privat Metin2

Ce este Sistemul de Verificare a Voturilor?

Sistemul nostru de verificare a voturilor este o soluție modernă și inovatoare creată special pentru serverele private Metin2. Oferă o modalitate captivantă pentru jucători de a vota pentru serverele lor preferate și de a primi beneficii în joc.

Sistemul este atât ușor de implementat, cât și extrem de fiabil, ceea ce îl face o alegere excelentă pentru proprietarii de servere care doresc să crească implicarea jucătorilor și vizibilitatea serverului.

Scopul nostru este să creăm o situație în care toată lumea câștigă: jucătorii sunt recompensați pentru loialitate prin beneficii în joc, iar serverele se bucură de vizibilitate crescută și implicare mai mare.

Sistemul Vote4Buff (Recomandat)

Sistem complet de votare și recompense în joc cu interfață personalizată

Ce este Vote4Buff?

Vote4Buff este soluția noastră premium completă pentru votare, care include o interfață grafică atractivă în joc, comunicare WebSocket și integrare completă cu serverul. Jucătorii pot vota, pot alege din mai multe pachete de bonusuri și primesc instantaneu recompense fără să iasă din joc!

Arhitectura sistemului

Sistemul Vote4Buff este format din trei componente principale:

Partea client

Sistem de UI în Python (uivote4buff.py)
Resurse și elemente grafice UI personalizate
Integrare WebSocket în C++
Suport pentru 11 limbi

Partea server

Integrare API în C++
Gestionarea pachetelor de bonusuri
Sistem de recompense cu obiecte
Monitorizarea efectelor în timp real

Platforma noastră

API de verificare a voturilor
Monitorizare pe baza conturilor
Protecție anti-fraudă
Statusul votului în timp real

Caracteristici cheie

Multiple pachete de bonusuri: până la 3 pachete configurabile din care jucătorii pot alege

Recompense cu obiecte: oferă automat obiecte după un vot reușit

Interfață în timp real: cronometre și urmărirea efectelor direct în joc

Comunicare WebSocket: verificare instantanee fără reîmprospătarea paginii

Multilingv: Suportă 11 limbi (EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ)

Recompense personalizabile: configurează bonusurile, durata și costurile

Perfect pentru: Proprietarii de servere care vor o soluție profesionistă, gata de utilizare, fără să petreacă săptămâni întregi cu dezvoltare personalizată. Trebuie doar să configurezi pachetele de bonusuri, să integrezi fișierele și ești gata!

Descarcă fișierele Vote4Buff

Obține toate fișierele necesare pentru integrarea client și server

Cerințe

Vote4Buff este conceput pentru martysama0134 v5.8 ca bază de cod. Dacă folosești o altă sursă, pot fi necesare modificări suplimentare.

Conținutul pachetului

Fișiere client

Fișiere UI Python (uivote4buff.py)
Modificări ale fișierelor clientului de joc
Elemente grafice și resurse UI
Fișiere locale în 11 limbi
Implementare WebSocket în C++
Fișiere script pentru UI

Include libcurl.dll (versiunea 32-bit inclusă, 64-bit disponibilă)

Fișiere server

Configurare char.h
Modificări pentru sistemul de efecte
Integrarea comenzilor de chat
Strat de comunicare cu API-ul
Sistemul de gestionare a bonusurilor

Toate modificările necesare în sursele C++ sunt incluse

Autentificare necesară

Te rugăm să te autentifici pentru a descărca fișierele Vote4Buff.

Ghid de configurare

Configurează pachetele de bonusuri, recompensele și setările API

Toată configurarea Vote4Buff se face în fișierul char.h de pe serverul tău. Mai jos găsești exemple detaliate pentru fiecare opțiune.

Pasul 1: Credenziale API

Mai întâi configurează ID-ul serverului și token-ul API (le găsești în panoul tău):

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

Pasul 2: Configurează pachetele de bonusuri

Poți defini până la 3 pachete de bonusuri din care jucătorii pot alege. Fiecare pachet poate conține mai multe bonusuri:

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

Tipuri APPLY disponibile

Tipuri de bonus frecvente: 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 și multe altele!

Pasul 3: Recompense cu obiecte (opțional)

Configurează obiectele pe care jucătorii le primesc automat după vot:

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

Pasul 4: Setări pentru schimbarea bonusurilor

Controlează perioada de așteptare și costurile atunci când jucătorii vor să schimbe pachetele de bonusuri:

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)

Notă: După ce jucătorii votează, pot alege gratuit un pachet de bonus. Perioada de așteptare și costul se aplică doar dacă vor să schimbe pachetul fără să voteze din nou.

Ghid de instalare

Instrucțiuni pas cu pas pentru integrarea Vote4Buff

Înainte să începi

Asigură-te că ai backup pentru fișierele clientului și serverului! Fișierele cu prefix __ necesită modificări, iar cele fără prefix pot fi copiate direct.

Instalarea pe server

1

Configurează char.h

Deschide Source/Server/__char.h din pachetul descărcat.

Găsește class CBuffOnAttributes; și adaugă codul de configurare deasupra (vezi secțiunea de Configurare)
Setează s_VOTE4BUFF_SERVER_ID și s_VOTE4BUFF_API_TOKEN
Configurează pachetele de bonusuri și recompensele cu obiecte
Găsește bool DragonSoul_RefineWindow_CanRefine(); și adaugă declarațiile metodelor publice

2

Aplică modificările pe server

Integrează fișierele din pachet pentru partea de server:

__affect.h - Modifică fișierul tău affect.h cu schimbările furnizate
__chat_affect.cpp - Adaugă gestionarea efectului Vote4Buff
__cmd_general.cpp - Adaugă procesarea comenzilor
__desc_client.cpp - Modificări pentru descriptorul clientului

Notă: Fișierele cu prefix __ indică faptul că trebuie să îmbini modificările cu fișierele existente.

3

Recompilează nucleul jocului

Compilează serverul de joc cu noile modificări.

make clean && make

Instalarea pe client

4

Fișiere UI Python

Din folderul Client/root/:

Copiază uivote4buff.py în folderul root/ al clientului tău
Modifică următoarele fișiere conform instrucțiunilor:
- __constInfo.py
- __game.py
- __interfaceModule.py
- __uiAffectShower.py

5

Grafica și scripturile UI

Copiază folderul Client/ui/game/vote4buff/ în directorul ui/game/ al pack-ului tău
Copiază Client/uiscript/vote4buffwindow.py în folderul uiscript

6

Fișiere de limbă

Adaugă șirurile locale pentru limbile suportate din Client/locale/:

Anexează conținutul __locale_game.txt în locale_game.txt
Anexează conținutul __locale_interface.txt în locale_interface.txt

Limbi disponibile: EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ

7

Modificări C++ pe client

Din Source/Client/UserInterface/:

Copiază M2WebSocket.cpp și M2WebSocket.h în folderul UserInterface
Aplică modificările din fișierele cu prefix __ în fișierele existente
Asigură-te că libcurl.dll este în directorul clientului (versiunea 32-bit inclusă, descarcă varianta 64-bit dacă este necesar)

8

Adaugă un buton în UI (opțional)

Vote4Buff nu adaugă un buton implicit. Trebuie să apelezi ToggleVote4Buff() dintr-un loc al interfeței tale. De exemplu:

Adaugă un buton în SystemDialog
Leagă-l de o tastă rapidă
Adaugă-l în meniul QuickSlot

Sau folosește clasa Vote4BuffButton inclusă, care creează un buton icon dragabil

9

Recompilează clientul

Reconstruiește executabilul clientului cu noile modificări.

10

Testare

Testează integrarea:

Conectează-te pe serverul tău
Deschide fereastra Vote4Buff
Votează pe platforma noastră: https://metin2.p42.studio/vote/en/YOUR_SERVER_ID-server-name/YOUR_ACCOUNT_ID
Revino în joc și verifică votul
Alege un pachet de bonusuri și verifică dacă efectele sunt aplicate
Verifică dacă recompensele cu obiecte au fost primite

Instalare completă!

Acum jucătorii tăi pot vota și primi recompense automat. Interfața Vote4Buff le arată când pot vota, le permite să aleagă pachete de bonusuri și afișează cronometre pentru efectele active.

Avantaje pentru administratorii de server

Promovare gratuită

Majoritatea jucătorilor noi descoperă servere prin toplisturi, ceea ce îl face un instrument de marketing esențial

Configurare simplă

Documentația detaliată și ghidurile pas cu pas fac configurarea foarte ușoară

Fără cod suplimentar

Proces de integrare REST extrem de simplu

Performanță optimizată

Verificarea votului pe partea clientului asigură o încărcare minimă a serverului

Fiabilitate ridicată

Sistem testat în producție, cu protecție anti-fraudă integrată

Verificare vot

Asigură-te că jucătorii chiar au votat pentru serverul tău înainte de a acorda recompense

Avantaje pentru jucători

Primește recompense în joc pentru votare

Interfață de vot ușor de folosit

Afișarea clară a timpului rămas până la următorul vot

Sistem garantat de livrare a recompenselor

Cum funcționează sistemul?

Sistemul are un flux clar și intuitiv, ușor de înțeles de către jucători. Cel mai important, verificarea voturilor se face prin API-ul nostru, asigurând validarea voturilor reale!

1

Jucătorul apasă butonul de vot

De pe site-ul tău sau din interfața din joc

2

Redirecționare către pagina de vot

Jucătorul este redirecționat către pagina de vot a serverului tău în toplist

3

Jucătorul votează

Jucătorul completează CAPTCHA și trimite votul

4

Verificarea API

Serverul tău interoghează API-ul nostru pentru a verifica votul

5

Răsplătește jucătorul

Serverul tău acordă recompensa în joc

Ghid de start rapid

Alege metoda de integrare în funcție de nevoile tale:

RECOMANDAT

Sistemul Vote4Buff

Soluție completă cu interfață personalizată, comunicare WebSocket și sistem automat de recompense.

✅ Interfață completă în joc
✅ Pachete multiple de bonusuri
✅ Recompense automate cu obiecte
✅ Cronometre în timp real
✅ Suport pentru 11 limbi

Începe cu Vote4Buff

Integrare API personalizată

Construiește-ți propria implementare folosind API-ul nostru REST pentru flexibilitate maximă.

🔧 Personalizare completă
🔧 Interfață creată de tine
🔧 Logică de recompense personalizată
🔧 Pe bază de IP sau cont

Folosește API-ul de bază

Pași generali de configurare

1

Înregistrează-ți serverul

Creează un cont și adaugă-ți serverul în toplist la https://metin2.p42.studio/servers/create

2

Obține credențialele API

Găsește ID-ul unic al serverului și token-ul API în panoul serverului. Acestea sunt necesare pentru autentificare.

3

Alege metoda de integrare

Descarcă Vote4Buff pentru o soluție gata de folosit sau integrează API-ul pentru o implementare personalizată.

4

Testează și lansează

Testează sistemul de vot în detaliu, apoi lansează-l pe serverul live.

Endpoint API (pentru implementări personalizate)

Notă

Dacă folosești sistemul Vote4Buff (recomandat), acest API este deja integrat! Această secțiune este pentru proprietarii de servere care doresc să construiască implementări personalizate.

GET

https://metin2.p42.studio/api/check-vote

Parametri necesari

Parametru	Tip	Obligatoriu	Descriere
`api_token`	string	Da	Token-ul API unic al serverului tău
`ip`	string	Opțional*	Adresa IP a jucătorului (IPv4 sau IPv6)
`account_id`	string	Opțional*	ID-ul/username-ul contului jucătorului pentru o urmărire mai precisă

*Fie ip, fie account_id (sau ambele) trebuie furnizate

Pentru rezultate optime, folosește <code>account_id</code> pentru urmărirea exactă a jucătorilor. Metoda <code>ip</code> poate fi mai puțin fiabilă dacă jucătorii folosesc VPN-uri sau se conectează din locații diferite.

Formatul URL-ului de vot

Direcționează jucătorii să voteze folosind această structură de URL:

https://metin2.p42.studio/vote.{lang}/{server_id}-{server_slug}/{account_id}

Exemple:
https://metin2.p42.studio/vote.en/123-awesome-server/PlayerName
https://metin2.p42.studio/vote.de/123-awesome-server/PlayerName
https://metin2.p42.studio/vote.tr/123-awesome-server/PlayerName

Limbi suportate: en, de, es, pl, tr, ro, it, pt, hu, gr, cz

Formatul răspunsului

API-ul returnează un răspuns JSON cu următoarea structură:

Răspuns de succes

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

Răspuns fără vot găsit

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

Răspuns de eroare

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

Câmpuri ale răspunsului

Câmp	Tip	Descriere
`success`	boolean	Indică dacă cererea API a fost procesată cu succes
`voted`	boolean	Indică dacă a fost găsit un vot valid (apare doar dacă success=true)
`last_vote`	string	Timestamp ISO 8601 al celui mai recent vot (numai dacă voted=true)
`next_vote_in`	integer	Numărul de secunde până la următorul vot permis (numai dacă voted=true)
`message`	string	Mesaj clar care descrie rezultatul

Exemple de cod

Exemplu PHP

Implementare cURL în PHP

<?php
function checkVote($apiToken, $playerIP) {
    $url = "https://metin2.p42.studio/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!";
}
?>

Exemplu Python

Implementare Requests în Python

import requests
import json

def check_vote(api_token, player_ip):
    """
    Check if a player has voted for the server
    """
    url = "https://metin2.p42.studio/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!")

Exemplu C++ (pentru servere de joc)

Implementare cURL în C++

#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.p42.studio/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!");
    }
}

Exemplu JavaScript/Node.js

Implementare Fetch în Node.js

async function checkVote(apiToken, playerIP) {
    const url = new URL('https://metin2.p42.studio/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!');
    }
});

Ghid de integrare

Bune practici de securitate

Păstrează token-ul API în siguranță și nu îl expune în codul de pe partea de client. Request-urile către API trebuie făcute întotdeauna din backend-ul serverului.

Pasul 1: Creează butonul/comanda de vot

Adaugă un buton de vot pe site-ul tău sau o comandă în joc care îi direcționează pe jucători către pagina ta de vot la https://metin2.p42.studio/servers/YOUR-SERVER-SLUG.

Pasul 2: Implementează verificarea votului

Când jucătorul solicită recompensa (prin site sau în joc), verifică dacă a votat:

Obține adresa IP a jucătorului
Trimite o cerere către endpoint-ul nostru check-vote
Procesează răspunsul JSON
Dacă voted este true, acordă recompensa
Stochează faptul că ai oferit această recompensă pentru a evita revendicările duble

Pasul 3: Gestionează recompensele

Cele mai bune practici pentru gestionarea recompenselor:

Monitorizează recompensele acordate: Stochează în baza de date ce voturi au fost deja răsplătite pentru a preveni dublarea
Interval între voturi: Respectă perioada de 24 de ore dintre voturi
Gestionarea erorilor: Procesează erorile API cu grijă și informează jucătorii
Jurnalizare: Înregistrează toate verificările de vot pentru analiză și depanare

Flux de lucru exemplu

Jucătorul: tastează comanda /vote în joc

↓

Serverul: deschide browserul către pagina de vot

↓

Jucătorul: votează pe toplist

↓

Jucătorul: tastează comanda /claim sau apasă „Claim Reward”

↓

Serverul: interoghează API-ul cu IP-ul jucătorului

↓

API-ul: returnează voted=true

↓

Serverul: acordă recompensa jucătorului

Depanare

Eroare „Invalid API token”

Soluție: Verifică dacă folosești token-ul API corect din panoul serverului. Asigură-te că nu există spații sau caractere suplimentare.

Votul nu este detectat după ce jucătorul a votat

Cauze posibile:

Jucătorul folosește un VPN/Proxy (adresele IP nu se potrivesc)
Votul nu a fost încă procesat (așteaptă 30 de secunde și încearcă din nou)
Se trimite o adresă IP greșită către API
Jucătorul a votat pentru un alt server

Timeout sau erori de conexiune ale API-ului

Soluție: Asigură-te că serverul tău poate face request-uri HTTPS. Verifică setările firewall. Implementează retry cu backoff exponențial.

Jucătorii revendică recompense de mai multe ori

Soluție: Implementează urmărirea locală a voturilor recompensate. Stochează timestamp-ul votului și acordă recompensa o singură dată.

Adresele IPv6 nu funcționează

Soluție: Asigură-te că trimiți adresa IPv6 completă. API-ul nostru suportă atât IPv4, cât și IPv6.

Asistență și resurse

Asistență prin e-mail

Primește ajutor prin e-mail

Contactează suportul

Comunitatea Discord

Alătură-te comunității noastre

Intră pe Discord

Sfat util

Testează integrarea temeinic cu un cont de test înainte de producție. Asigură-te că gestionezi toate scenariile limită și erorile.

Link-uri Rapide

Navigare rapidă