İçeriğe geç

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.

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 var
params[1] = birinci parametre
params[2] = ikinci parametre

Bu ayrıntıyı atlamak, eksik parametreyle çağrılan bir native’in dizi sınırı dışından veri okumasına yol açar.

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.

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.

Gamemode içine tek tek native satırı eklemek yerine plugin API’sini starter.inc dosyasında topla:

pawn/include/starter.inc
#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.

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.

Her fonksiyon için şu dört soruyu cevapla:

  1. Başarıda ne döner?
  2. Hangi girdiler geçersizdir?
  3. Hata nasıl anlaşılır?
  4. 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.

  • params[0] değerini byte cinsinden kontrol ediyorsun.
  • Pawn API adlarında tutarlı bir prefix var.
  • Kayıt dizisi {nullptr, nullptr} ile bitiyor.
  • .inc bildirimi 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.