İlk SA-MP C++ Pluginini Yazma ve Sunucuya Yükleme
Bu bölümde SA-MP’nin tanıyacağı en küçük kullanışlı plugini yazacağız. Plugin açılış ve kapanışını log’a yazacak, her Pawn script’e Plugin_GetVersion adlı bir native kaydedecek.
Plugin yaşam döngüsünü tanı
Bölüm başlığı “Plugin yaşam döngüsünü tanı”Sunucu plugin ile sabit giriş noktaları üzerinden konuşur:
| Fonksiyon | Ne zaman çağrılır? | Dönüş değerinin anlamı |
|---|---|---|
Supports |
Plugin incelenirken | Pluginin desteklediği özellikleri bit maskesi olarak bildirir. |
Load |
Plugin sunucuya yüklenirken | true yüklemeyi kabul eder, false yüklemeyi iptal eder. |
Unload |
Plugin kaldırılırken veya sunucu kapanırken | Dönüş değeri yoktur; kaynaklar burada serbest bırakılır. |
AmxLoad |
Her gamemode veya filterscript AMX’i yüklenirken | AMX_ERR_NONE yani 0 başarıdır; native kayıt hatası aynen döndürülür. |
AmxUnload |
Bir AMX kaldırılırken | Başarı için AMX_ERR_NONE döndürülür. |
Load bir kez, AmxLoad ise gamemode ve her filterscript için ayrı ayrı çağrılabilir. Bu ayrım ileride AMX pointer’larını saklarken kritik olacak.
main.cpp dosyasını yaz
Bölüm başlığı “main.cpp dosyasını yaz”#include "SDK/amx/amx.h"#include "SDK/plugincommon.h"
using Logprintf = void (*)(const char* format, ...);
void* pAMXFunctions = nullptr;Logprintf logprintf = nullptr;
cell AMX_NATIVE_CALL Plugin_GetVersion(AMX*, cell*){ return 100;}
AMX_NATIVE_INFO pluginNatives[] ={ {"Plugin_GetVersion", Plugin_GetVersion}, {nullptr, nullptr}};
PLUGIN_EXPORT unsigned int PLUGIN_CALL Supports(){ return SUPPORTS_VERSION | SUPPORTS_AMX_NATIVES;}
PLUGIN_EXPORT bool PLUGIN_CALL Load(void** data){ pAMXFunctions = data[PLUGIN_DATA_AMX_EXPORTS]; logprintf = reinterpret_cast<Logprintf>(data[PLUGIN_DATA_LOGPRINTF]);
logprintf("[starter] Plugin loaded"); return true;}
PLUGIN_EXPORT void PLUGIN_CALL Unload(){ logprintf("[starter] Plugin unloaded");}
PLUGIN_EXPORT int PLUGIN_CALL AmxLoad(AMX* amx){ return amx_Register(amx, pluginNatives, -1);}
PLUGIN_EXPORT int PLUGIN_CALL AmxUnload(AMX*){ return AMX_ERR_NONE;}Kodda ne oluyor?
Bölüm başlığı “Kodda ne oluyor?”pAMXFunctions, SDK makrolarının AMX fonksiyonlarına ulaşmak için kullandığı tablodur. Load içinde atanmazsa ilk amx_Register çağrısında plugin çökebilir.
logprintf, çıktıyı SA-MP konsoluna ve server_log.txt dosyasına gönderir. std::cout yerine bunu kullanmak, production sunucusunda kayıtların tek yerde kalmasını sağlar.
pluginNatives dizisi Pawn’da görünen ad ile C++ fonksiyon adresini eşler. Son {nullptr, nullptr} kaydı listenin bittiğini belirtir; bu nedenle amx_Register üçüncü parametresinde -1 kullanabiliyoruz.
Plugini derle
Bölüm başlığı “Plugini derle”Windows
Bölüm başlığı “Windows”Proje kökünde Developer PowerShell aç:
cmake -S . -B build/windows -A Win32cmake --build build/windows --config ReleaseÇıktı kullanılan generator’a göre build/windows/Release/starter.dll altında oluşur.
cmake -S . -B build/linux -DCMAKE_BUILD_TYPE=Releasecmake --build build/linux --parallelÇıktı build/linux/starter.so olur. -m32 ile ilgili başlık veya linker hatası alırsan sistemindeki 32 bit geliştirme paketleri eksiktir.
server.cfg ile yükle
Bölüm başlığı “server.cfg ile yükle”Üretilen dosyayı test sunucusunun plugins/ klasörüne kopyala. Ardından işletim sistemine uygun satırı kullan:
plugins starterplugins starter.soBaşka pluginler varsa aynı satırda boşlukla ayır. Sunucuyu başlattığında log’da şu satırı görmelisin:
[starter] Plugin loadedPawn tarafından doğrula
Bölüm başlığı “Pawn tarafından doğrula”Şimdilik gamemode’un üst bölümüne native bildirimi ekle:
#include <a_samp>
native Plugin_GetVersion();
public OnGameModeInit(){ printf("Starter plugin version: %d", Plugin_GetVersion()); return 1;}Pawn kodunu yeniden derle ve sunucuyu başlat. Log’da 100 görüyorsan zincirin tamamı çalışıyor:
server.cfg -> starter.dll/.so -> AmxLoad -> amx_Register -> Pawn native100, 1.0.0 sürümünü tek cell içinde ifade eden örnek bir sözleşmedir. Gerçek projede sürüm biçimini .inc dosyasında açıkça belgelemelisin.
Dönüş değerlerinde sık yapılan hata
Bölüm başlığı “Dönüş değerlerinde sık yapılan hata”Load ve AmxLoad aynı başarı kuralını kullanmaz:
Load: başarıtrue, hatafalse.AmxLoad: başarıAMX_ERR_NONE, yani sayısal olarak0.Plugin_GetVersion: değer doğrudan Pawn’a döner; burada100bir hata kodu değildir.
Her fonksiyona otomatik olarak return 1 yazmak plugin geliştirmede doğru değildir. Dönüş sözleşmesini fonksiyonun rolü belirler.
Bölüm kontrolü
Bölüm başlığı “Bölüm kontrolü”- Sunucu açılırken plugin log satırı görünüyor.
Plugin_GetVersion()Pawn’da runtime error vermeden çalışıyor.- Windows’ta
.defdosyası build hedefinin parçası. AmxLoad,amx_Registersonucunu değiştirmeden döndürüyor.
Sıradaki adım: Pawn native fonksiyonlarını doğru sözleşmeyle tasarla.