İçeriğe geç

İ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.

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.

src/main.cpp
#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;
}

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.

Proje kökünde Developer PowerShell aç:

Terminal window
cmake -S . -B build/windows -A Win32
cmake --build build/windows --config Release

Çıktı kullanılan generator’a göre build/windows/Release/starter.dll altında oluşur.

Terminal window
cmake -S . -B build/linux -DCMAKE_BUILD_TYPE=Release
cmake --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.

Üretilen dosyayı test sunucusunun plugins/ klasörüne kopyala. Ardından işletim sistemine uygun satırı kullan:

Windows server.cfg
plugins starter
Linux server.cfg
plugins starter.so

Başka pluginler varsa aynı satırda boşlukla ayır. Sunucuyu başlattığında log’da şu satırı görmelisin:

[starter] Plugin loaded

Şimdilik gamemode’un üst bölümüne native bildirimi ekle:

gamemodes/academy.pwn
#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 native

100, 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.

Load ve AmxLoad aynı başarı kuralını kullanmaz:

  • Load: başarı true, hata false.
  • AmxLoad: başarı AMX_ERR_NONE, yani sayısal olarak 0.
  • Plugin_GetVersion: değer doğrudan Pawn’a döner; burada 100 bir 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.

  • Sunucu açılırken plugin log satırı görünüyor.
  • Plugin_GetVersion() Pawn’da runtime error vermeden çalışıyor.
  • Windows’ta .def dosyası build hedefinin parçası.
  • AmxLoad, amx_Register sonucunu değiştirmeden döndürüyor.

Sıradaki adım: Pawn native fonksiyonlarını doğru sözleşmeyle tasarla.