SA-MP Plugin İçin Pawn Native Fonksiyonu Yazma
Native, pluginin dışarı açtığı Pawn API’sidir. C++ tarafında bir fonksiyon yazmak işin yarısıdır; parametre sayısı, veri türleri, hata davranışı ve dönüş değeri Pawn geliştiricisi için tutarlı bir sözleşme oluşturmalıdır.
Bu bölümde Plugin_Add ve Plugin_IsEven fonksiyonlarını ekleyeceğiz.
Native fonksiyon imzası
Bölüm başlığı “Native fonksiyon imzası”Plugin SDK bir native fonksiyonu şu biçimde bekler:
cell AMX_NATIVE_CALL FunctionName(AMX* amx, cell* params)amx, native’i çağıran gamemode veya filterscript örneğidir.params, Pawn’dan gelen parametrelerin tutulduğu dizidir.- dönüş türü
cell, Pawn’a gönderilen tek hücrelik sonuçtur.
İlk gerçek parametre params[1] konumundadır. params[0] parametre sayısını değil, parametrelerin kapladığı toplam byte miktarını tutar.
params[0] = 2 * sizeof(cell) // iki parametre varparams[1] = birinci parametreparams[2] = ikinci parametreBu ayrıntıyı atlamak, eksik parametreyle çağrılan bir native’in dizi sınırı dışından veri okumasına yol açar.
Parametre sayısını doğrula
Bölüm başlığı “Parametre sayısını doğrula”Tekrar kullanabileceğimiz küçük bir yardımcı fonksiyon yaz:
#include <cstddef>#include <cstdint>#include <limits>
bool HasParams(const cell* params, std::size_t expectedCount){ const auto expectedBytes = static_cast<cell>(expectedCount * sizeof(cell)); return params[0] >= expectedBytes;}Ardından iki native’i ekle:
cell AMX_NATIVE_CALL Plugin_Add(AMX*, cell* params){ if (!HasParams(params, 2)) { logprintf("[starter] Plugin_Add requires 2 parameters"); return 0; }
const auto result = static_cast<std::int64_t>(params[1]) + static_cast<std::int64_t>(params[2]);
if (result < std::numeric_limits<cell>::min() || result > std::numeric_limits<cell>::max()) { logprintf("[starter] Plugin_Add result is outside cell range"); return 0; }
return static_cast<cell>(result);}
cell AMX_NATIVE_CALL Plugin_IsEven(AMX*, cell* params){ if (!HasParams(params, 1)) { logprintf("[starter] Plugin_IsEven requires 1 parameter"); return 0; }
return (params[1] % 2 == 0) ? 1 : 0;}Toplama önce daha geniş bir türde yapıldığı için C++ signed integer taşmasına girmez. Plugin_Add için 0 yine hem geçerli toplam hem de hata sonucu olabilir. Üretim API’sinde hata ile geçerli sonucu ayırman gerekiyorsa output referansı veya ayrı bir hata sorgulama fonksiyonu tasarla.
Native kayıt listesine ekle
Bölüm başlığı “Native kayıt listesine ekle”Mevcut pluginNatives dizisini güncelle:
AMX_NATIVE_INFO pluginNatives[] ={ {"Plugin_GetVersion", Plugin_GetVersion}, {"Plugin_Add", Plugin_Add}, {"Plugin_IsEven", Plugin_IsEven}, {nullptr, nullptr}};Pawn’daki isim ile C++ kayıt dizisindeki metin birebir aynı olmalıdır. Büyük-küçük harf ya da prefix farkı, script yüklenirken Function not registered ve runtime error 19 benzeri hatalara neden olur.
Pawn include dosyasını hazırla
Bölüm başlığı “Pawn include dosyasını hazırla”Gamemode içine tek tek native satırı eklemek yerine plugin API’sini starter.inc dosyasında topla:
#if defined _starter_included #endinput#endif#define _starter_included
#define STARTER_VERSION (100)
native Plugin_GetVersion();native Plugin_Add(left, right);native bool:Plugin_IsEven(value);Include guard, aynı dosya iki farklı include üzerinden gelirse bildirimlerin tekrar işlenmesini engeller. Plugin fonksiyonlarında Plugin_ prefix’i kullanmak diğer include’larla isim çakışması riskini azaltır.
Dosyayı test sunucusundaki pawno/include/ klasörüne kopyala ve gamemode’da kullan:
#include <a_samp>#include <starter>
public OnGameModeInit(){ new total = Plugin_Add(18, 24);
printf("Total: %d", total); printf("Is total even: %d", Plugin_IsEven(total)); return 1;}Kod kimlikleri iki tarafta da İngilizce tutuluyor. Pawn API adlarının İngilizce olması, hata mesajlarında ve proje genelinde aynı terimi arayabilmeni sağlar.
cell ne anlama gelir?
Bölüm başlığı “cell ne anlama gelir?”Pawn temel verileri hücrelerde saklar. Klasik SA-MP ortamında bir hücre genellikle 32 bittir; ancak plugin kodunda kesin genişliği varsaymak yerine SDK’nin cell türünü kullan.
Şu dönüş türleri tek bir cell içinde taşınabilir:
| Pawn tarafı | C++ native dönüşü |
|---|---|
| Integer | Doğrudan cell değeri |
bool: |
Sözleşmeye göre 1 veya 0 |
Float: |
Normal cast değil, amx_ftoc ile bit dönüşümü |
| ID veya handle | Geçerli aralık ve hata sabiti belgelenmiş cell |
String ve dizi tek hücreye sığmaz. Pawn bunları adres olarak geçirir; AMX veri tipleri bölümünde güvenli biçimde okuyacağız.
Native dönüş sözleşmesi nasıl yazılır?
Bölüm başlığı “Native dönüş sözleşmesi nasıl yazılır?”Her fonksiyon için şu dört soruyu cevapla:
- Başarıda ne döner?
- Hangi girdiler geçersizdir?
- Hata nasıl anlaşılır?
- Fonksiyon Pawn’daki veriyi değiştirir mi?
Örneğin Plugin_IsEven için sözleşme nettir: tek integer alır, çiftse true, tekse false döner ve dışarıdaki veriyi değiştirmez. Plugin_Add ise taşma ve hata ayrımı açısından daha sınırlıdır; gerçek bir matematik API’sinde bu davranış ayrıca ele alınmalıdır.
Bölüm kontrolü
Bölüm başlığı “Bölüm kontrolü”params[0]değerini byte cinsinden kontrol ediyorsun.- Pawn API adlarında tutarlı bir prefix var.
- Kayıt dizisi
{nullptr, nullptr}ile bitiyor. .incbildirimi ile C++ uygulamasının parametre sırası aynı.- Her native’in başarı ve hata dönüşü tanımlı.
Sıradaki adım: Pawn string, Float, referans ve dizilerini C++ tarafında işle.