Dokumentace API
Systém ověřování hlasů pro Metin2
Snadné, bezplatné a spolehlivé hlasování s odměnami pro váš Metin2 privátní server
Náš systém ověřování hlasů je moderní a inovativní řešení navržené speciálně pro Metin2 privátní servery. Nabízí atraktivní způsob, jak mohou hráči hlasovat pro svůj oblíbený server a zároveň získat odměny ve hře.
Systém je zároveň snadno implementovatelný a velmi spolehlivý, takže je ideální volbou pro administrátory, kteří chtějí zvýšit zapojení hráčů a viditelnost serveru.
Naším cílem je vytvořit win-win situaci pro hráče i provozovatele serveru. Hráči jsou za svou věrnost odměněni bonusy ve hře a servery získávají vyšší viditelnost i aktivitu.
Systém Vote4Buff (doporučeno)
Kompletní systém hlasování a odměn přímo ve hře s vlastním UI
Vote4Buff je naše prémiové komplexní řešení, které obsahuje propracované herní UI, komunikaci přes WebSockety a plnou integraci na straně serveru. Hráči mohou hlasovat, vybírat z více balíčků bonusů a získat odměny okamžitě bez opuštění hry!
Architektura systému
Systém Vote4Buff se skládá ze tří hlavních částí:
Klientská část
- Python UI systém (uivote4buff.py)
- Vlastní grafické podklady a assety
- Integrace C++ WebSocketu
- Podpora 11 jazyků
Serverová část
- Implementace API v C++
- Správa balíčků bonusů
- Systém odměn předmětů
- Sledování aktivních efektů v reálném čase
Naše platforma
- API pro ověřování hlasů
- Sledování podle účtů
- Ochrana proti podvodům
- Stav hlasování v reálném čase
Klíčové vlastnosti
Ideální pro: Administrátory, kteří chtějí profesionální hotové řešení bez týdnů vlastního vývoje. Stačí nakonfigurovat balíčky, nahrát soubory a můžete spustit!
Stažení souborů Vote4Buff
Získejte všechny soubory potřebné pro integraci na klientovi i serveru
Vote4Buff je navržen pro zdrojovou bázi martysama0134 v5.8. Používáte-li jiný základ, může být nutné provést úpravy.
Obsah balíčku
Klientské soubory
- Python UI soubory (uivote4buff.py)
- Úpravy herních souborů
- Grafika a assety UI
- Locale soubory pro 11 jazyků
- Implementace C++ WebSocketu
- Skriptové soubory UI
Součástí je libcurl.dll (32bit verze, 64bit lze stáhnout samostatně)
Serverové soubory
- Konfigurace pro char.h
- Úpravy systému affectů
- Integrace chatovacích příkazů
- Komunikace s klientem v desc_client.cpp
- Vrstva pro komunikaci s API
Obsahuje všechny potřebné úpravy zdrojových souborů v C++
Pro stažení souborů se prosím přihlaste.
Průvodce konfigurací
Nastavte balíčky bonusů, předměty a API připojení
Veškerá konfigurace Vote4Buff probíhá v souboru char.h na vašem serveru. Níže najdete detailní příklady každé možnosti.
Krok 1: API údaje
Nejprve nakonfigurujte ID serveru a API token (najdete v panelu serveru):
// 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 !!!
Krok 2: Nastavte balíčky bonusů
Můžete definovat až 3 balíčky bonusů, ze kterých si hráči vybírají. Každý balíček může obsahovat více 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
},
};
Běžné typy bonusů: 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 a mnoho dalších!
Krok 3: Předměty jako odměna (volitelné)
Nastavte předměty, které hráč obdrží automaticky po hlasování:
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
};
Krok 4: Změna balíčku bonusů
Řiďte cooldown a cenu, když chce hráč přepnout na jiný balíček bez dalšího hlasu:
// 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)
Poznámka: Po hlasování si hráč může vybrat balíček ZDARMA. Cooldown a cena platí pouze tehdy, když chce balíček změnit bez dalšího hlasu.
Instalační průvodce
Krok za krokem k integraci Vote4Buff
Udělejte si zálohy klientských i serverových souborů! Konvence názvů: soubory s prefixem __ vyžadují sloučení s vašimi existujícími soubory, ostatní lze zkopírovat přímo.
Instalace na serveru
Konfigurace char.h
Otevřete soubor Source/Server/__char.h z balíčku.
- Vyhledejte
class CBuffOnAttributes;a vložte konfigurační kód nad něj (viz sekce Konfigurace) - Nastavte
s_VOTE4BUFF_SERVER_IDas_VOTE4BUFF_API_TOKEN - Nakonfigurujte balíčky bonusů a odměny za hlasování
- Najděte
bool DragonSoul_RefineWindow_CanRefine();a přidejte veřejné deklarace metod
Aplikujte serverové úpravy
Integrujte serverové soubory z balíčku:
__affect.h– upravte svůj existující affect.h dle dodaných změn__chat_affect.cpp– přidejte zpracování efektů Vote4Buff__cmd_general.cpp– doplňte zpracování příkazů__desc_client.cpp– úpravy klientských deskriptorů
Poznámka: soubory s prefixem __ znamenají, že musíte změny sloučit se svými existujícími soubory.
Překompilujte game core
Znovu zkompilujte herní server s novými úpravami.
make clean && make Instalace na klientu
Python UI soubory
Ve složce Client/root/:
- Zkopírujte
uivote4buff.pydo složkyroot/vašeho klienta - Upravte následující soubory dle instrukcí:
__constInfo.py__game.py__interfaceModule.py__uiAffectShower.py
Grafika a skripty UI
- Zkopírujte složku
Client/ui/game/vote4buff/doui/game/vašeho balíčku - Zkopírujte
Client/uiscript/vote4buffwindow.pydo složky uiscript
Jazykové soubory
Přidejte texty pro podporované jazyky ze složky Client/locale/:
- Připojte obsah
__locale_game.txtke svémulocale_game.txt - Připojte obsah
__locale_interface.txtke svémulocale_interface.txt
Dostupné jazyky: EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ
Úpravy klienta v C++
Ze složky Source/Client/UserInterface/:
- Zkopírujte
M2WebSocket.cppaM2WebSocket.hdo UserInterface - Aplikujte úpravy ze souborů s prefixem
__do svých existujících souborů - Ujistěte se, že
libcurl.dllje v klientském adresáři (32bit verze je součástí, 64bit stáhněte zvlášť)
Přidání tlačítka (volitelné)
Vote4Buff nepřidává výchozí tlačítko. Funkci ToggleVote4Buff() musíte zavolat z některé části UI. Například:
- Přidejte tlačítko do SystemDialogu
- Navážte jej na klávesovou zkratku
- Umístěte ho do menu rychlých voleb
Můžete využít i dodanou třídu Vote4BuffButton, která vytvoří přetáhnutelné ikonové tlačítko
Znovu zkompilujte klienta
Přeložte klientskou aplikaci s novými úpravami.
Testování
Ověřte integraci:
- Přihlaste se na server
- Otevřete okno Vote4Buff
- Hlasujte na naší platformě: https://metin2-toplist.net/vote/en/YOUR_SERVER_ID-server-name/YOUR_ACCOUNT_ID
- Vraťte se do hry a ověřte hlas
- Vyberte balíček bonusu a zkontrolujte aplikované efekty
- Ověřte, že byly připsány odměny předměty
Hráči nyní mohou hlasovat a automaticky získávat odměny. UI Vote4Buff jim ukáže, kdy mohou hlasovat, umožní výběr bonusů a zobrazí odpočty aktivních efektů.
Výhody pro administrátory
Bezplatná propagace
Většina nových hráčů nachází servery přes toplisty, proto je to klíčový marketingový kanál
Jednoduchá konfigurace
Detailní dokumentace a postupy krok za krokem
Bez nutnosti programovat
Jednoduché REST API s jasným postupem integrace
Optimalizovaný výkon
Ověřování hlasů na klientovi minimalizuje zátěž serveru
Vysoká spolehlivost
Ověřený systém s ochranou proti podvodům
Ověření hlasů
Máte jistotu, že hráči opravdu hlasovali před udělením odměny
Výhody pro hráče
Jak systém funguje?
Systém nabízí jasný a přívětivý proces, který hráči snadno pochopí. Ověřování hlasů probíhá přes naše API, takže vždy ověříte pravost hlasu.
Začínáme – rychlý průvodce
Vyberte si způsob integrace podle svých potřeb:
Systém Vote4Buff
Kompletní řešení s vlastním UI, komunikací přes WebSocket a automatickými odměnami.
- Plnohodnotné UI přímo ve hře
- Více balíčků bonusů
- Automatické předávání itemů
- Odpočty v reálném čase
- Podpora 11 jazyků
Vlastní integrace API
Postavte si vlastní řešení pomocí našeho REST API pro maximální flexibilitu.
- Plná přizpůsobitelnost
- Vlastní design UI
- Odměny podle vlastního logiky
- Sledování podle IP nebo účtu
Obecné kroky
Zaregistrujte server
Vytvořte si účet a přidejte server do našeho toplistu na adrese https://metin2-toplist.net/servers/create
Získejte API údaje
V panelu serveru najdete jedinečné ID serveru a API token. Bez nich se nelze k API připojit.
Vyberte metodu integrace
Stáhněte Vote4Buff pro hotové řešení, nebo využijte API pro vlastní implementaci.
Testujte a nasazujte
Důkladně otestujte hlasovací systém a poté jej nasaďte na produkci.
API endpoint (pro vlastní integrace)
Pokud používáte systém Vote4Buff (doporučeno), je toto API již součástí! Tato sekce je určena pro administrátory, kteří chtějí vytvořit vlastní implementaci.
https://metin2-toplist.net/api/check-vote
Povinné parametry
| Parametr | Typ | Povinné | Popis |
|---|---|---|---|
api_token |
string | Ano | Jedinečný API klíč vašeho serveru |
ip |
string | Volitelné* | IP adresa hráče (IPv4 nebo IPv6) |
account_id |
string | Volitelné* | ID účtu / uživatelské jméno pro přesnější sledování |
Pro nejlepší výsledky používejte <code>account_id</code>, které zajišťuje přesné spárování hráčů. Parametr <code>ip</code> může být méně spolehlivý při použití VPN nebo změně sítě.
Formát hlasovací URL
Hráče přesměrujte na hlasování pomocí této struktury URL:
https://metin2-toplist.net/vote.{lang}/{server_id}-{server_slug}/{account_id}
Příklady:
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
Podporované jazyky: en, de, es, pl, tr, ro, it, pt, hu, gr, cz
Formát odpovědi
API vrací JSON odpověď v následující struktuře:
{
"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"
}
Pole odpovědi
| Pole | Typ | Popis |
|---|---|---|
success |
boolean | Zda byl požadavek na API zpracován úspěšně |
voted |
boolean | Zda byl nalezen platný hlas (pouze pokud success=true) |
last_vote |
string | Časové razítko posledního hlasu ve formátu ISO 8601 (pouze pokud voted=true) |
next_vote_in |
integer | Počet sekund do dalšího hlasu (pouze pokud voted=true) |
message |
string | Srozumitelná zpráva popisující výsledek |
Ukázky kódu
Příklad v 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...";
}
?>
Příklad v Pythonu
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...")
Příklad v C++ (pro herní servery)
#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!");
}
}
Příklad v JavaScriptu/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...');
}
});
Průvodce integrací
API token ukládejte vždy bezpečně a nikdy jej nezveřejňujte v kódu na straně klienta. Požadavky na API odesílejte výhradně z backendu vašeho serveru.
Krok 1: Vytvořte tlačítko / příkaz pro hlasování
Přidejte na web nebo do hry tlačítko, které hráče nasměruje na hlasovací stránku vašeho serveru na adrese https://metin2-toplist.net/servers/YOUR-SERVER-SLUG.
Krok 2: Implementujte kontrolu hlasu
Když hráč požádá o odměnu (na webu nebo ve hře), postupujte následovně:
- Získejte IP adresu hráče
- Odešlete požadavek na náš endpoint check-vote
- Zpracujte JSON odpověď
- Pokud je
votedtrue, udělte odměnu - Uložte informaci, že odměna byla udělena, abyste předešli duplicitním nárokům
Krok 3: Práce s odměnami
Doporučené postupy pro práci s odměnami:
- Evidujte udělené odměny: V databázi ukládejte, které hlasy už byly odměněny, aby nedocházelo k duplicitám
- Respektujte cooldown hlasování: Dodržujte 24hodinový interval mezi hlasy
- Ošetřete chyby: API chyby zpracujte elegantně a informujte hráče
- Logování: Logujte všechna ověření hlasů pro audit a analytiku
Ukázkový postup
Řešení problémů
Chyba „Invalid API token"
Řešení: Ověřte, že používáte správný API token z panelu serveru. Zkontrolujte, zda v něm nejsou mezery nebo jiné znaky navíc.
Hlas nebyl detekován, přestože hráč hlasoval
Možné příčiny:
- Hráč používá VPN/proxy (IP adresy se neshodují)
- Hlas ještě nebyl zpracován (počkejte 30 sekund a zkuste to znovu)
- Na API posíláte nesprávnou IP adresu
- Hráč hlasoval pro jiný server
API vrací timeout nebo chybu připojení
Řešení: Ujistěte se, že váš server může odesílat odchozí HTTPS požadavky. Zkontrolujte nastavení firewallu a implementujte opakované pokusy s exponenciálním zpožděním.
Hráči získávají odměny vícekrát
Řešení: Veďte lokální evidenci odměněných hlasů. Ukládejte čas hlasu a každou odměnu udělte jen jednou.
Nepracují IPv6 adresy
Řešení: Ujistěte se, že posíláte kompletní IPv6 adresu. Naše API podporuje IPv4 i 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")
Podpora a zdroje
Důkladně otestujte integraci na testovacím účtu před nasazením do produkce. Ujistěte se, že pokrýváte všechny okrajové i chybové scénáře.