Sunasty SDK

Sunasty SDK, sunucundaki herhangi bir script'in panele bağlanmasını sağlar. Script birkaç satırla kendini tanıtır; panel Eklentiler sayfasında onun için otomatik olarak şunları oluşturur:

• Ayarlar formu: metin, sayı, açık/kapalı, seçim, renk, liste…
• İşlem butonları: "Şimdi ödül dağıt" gibi, parametreli ve onaylı.
• Tablolar: script'in verisini sayfalı ve aranabilir gösterir.
• İstatistik kutuları: anlık sayılar.

Ayarları panelden değiştirdiğinde script yeniden başlatmadan yeni değerleri alır. Ayarlar panelde saklanır; script ya da sunucu yeniden başlasa da korunur.

Kurulum sırası#

Script'in, köprüden sonra başlamalı. server.cfg içinde:

ensure oxmysql
ensure sunasty-bridge
ensure benim-scriptim

Script'inin fxmanifest.lua dosyasına bağımlılığı ekle:

dependency 'sunasty-bridge'

En kısa örnek#

local SDK = exports['sunasty-bridge']

CreateThread(function()
    SDK:registerModule({
        name = 'Günlük Ödül',
        version = '1.0.0',
        author = 'Sunucum',
        icon = 'gift',
        settings = {
            { key = 'amount', type = 'number', label = 'Ödül tutarı', min = 0, max = 100000, default = 500 },
            { key = 'enabled', type = 'boolean', label = 'Aktif', default = true },
        },
    })
end)

-- Ayarı okumak
local amount = SDK:getConfig('amount')

-- Panelden kaydedilince anında haber al
AddEventHandler('sunasty:configChanged:' .. GetCurrentResourceName(), function(cfg)
    print('Yeni tutar: ' .. cfg.amount)
end)

Script başladıktan birkaç saniye sonra panelde Eklentiler sayfasında belirir.

Manifest#

registerModule bir manifest tablosu alır.

Ayar alanları#

Her ayar bir tablodur:

Tipler:

options düz metin ya da { value, label } olabilir:

{ key = 'account', type = 'select', label = 'Hesap',
  options = { { value = 'cash', label = 'Nakit' }, { value = 'bank', label = 'Banka' } },
  default = 'bank' }

İşlemler#

Panelde buton olarak görünür; basınca script'indeki işleyici çalışır.

actions = {
    {
        key = 'give_now',
        label = 'Şimdi ödül dağıt',
        description = 'Çevrimiçi herkese ödül verir',
        params = { { key = 'multiplier', type = 'number', label = 'Çarpan', min = 1, max = 10, default = 1 } },
    },
    { key = 'reset', label = 'Geçmişi sil', confirm = true, danger = true },
}

Tablolar#

tables = {
    {
        key = 'history',
        label = 'Dağıtım geçmişi',
        columns = {
            { key = 'player', label = 'Oyuncu' },
            { key = 'amount', label = 'Tutar', type = 'money' },
            { key = 'at', label = 'Zaman', type = 'date' },
        },
    },
}

Kolon tipleri: text, number, money, boolean, date (unix saniye ya da tarih metni). Sadece tanımlı kolonlar panele gönderilir; satırdaki diğer alanlar gizli kalır.

İstatistikler#

stats = { { key = 'total_given', label = 'Toplam dağıtılan', unit = '$' } }

Export'lar#

Hepsi exports['sunasty-bridge'] üzerinden çağrılır. Modül kimliği her zaman çağıran resource'un adıdır; bir script başka bir script'in ayarlarını okuyamaz veya değiştiremez.

registerModule(manifest)#

Modülü kaydeder. true ya da false, hata döner. Manifest hatalıysa sunucu konsoluna nedenini yazar.

local ok, err = SDK:registerModule(manifest)
if not ok then print('Sunasty kaydı başarısız: ' .. err) end

Aynı script tekrar çağırırsa (örn. manifest güncellendi) kayıt güncellenir, ayarlar korunur.

getConfig(key?)#

Panelde kaydedilmiş değerleri, yoksa varsayılanları döner. key verilirse tek değer, verilmezse tüm tablo.

local cfg = SDK:getConfig()
if cfg.enabled then ... end

sunasty:configChanged:<resource>#

Panelden ayar kaydedildiğinde tetiklenir. Yeni değerlerin tamamı gelir.

AddEventHandler('sunasty:configChanged:' .. GetCurrentResourceName(), function(cfg)
    config = cfg
end)

onAction(key, fn(params, actor))#

Manifest'te tanımlı bir işlemin işleyicisi.

• params: formdaki doğrulanmış değerler.
• actor: işlemi yapan panel kullanıcısı ({ id, name }).
• Dönüş değeri:
  • metin → panelde başarı mesajı olarak gösterilir;
  • tablo → message alanı mesaj olur, tablonun tamamı sonuç penceresinde görünür;
  • { ok = false, message = '...' } ya da error('...') → panelde hata olarak gösterilir.

SDK:onAction('give_now', function(params, actor)
    local count = giveAll(params.multiplier)
    return { message = count .. ' oyuncuya ödül verildi', players = count }
end)

onTable(key, fn(query))#

Tablo verisini sağlar. query = { page, pageSize, search }. { rows = {...}, total = n } dönmelisin; en fazla 100 satır gönderilir.

SDK:onTable('history', function(q)
    local from = (q.page - 1) * q.pageSize + 1
    local page = {}
    for i = from, math.min(from + q.pageSize - 1, #history) do page[#page + 1] = history[i] end
    return { rows = page, total = #history }
end)

setStat(key, value)#

İstatistik kutusunun değerini günceller (sayı, metin ya da true/false).

SDK:setStat('total_given', totalGiven)

log(kategori, mesaj?, veri?)#

Panelin Loglar sayfasına kayıt düşer (custom kategorisi). Resource başına dakikada en fazla 30 kayıt; fazlası sessizce atlanır.

SDK:log('odul', 'Ali günlük ödülünü aldı', { amount = 500 })

Güvenlik#

• Sadece sunucu tarafı: SDK export'ları client'tan çağrılamaz; oyuncular ayarlara ya da işlemlere erişemez.
• Çift doğrulama: manifest ve ayar değerleri hem köprüde hem panelde doğrulanır. Geçersiz değerler panelde reddedilir; köprü tarafında varsayılana döner.
• İzinler: ayarları sadece Ayarları yönet iznine sahip ekip üyeleri değiştirebilir (2FA açıksa yeniden doğrulama istenir). İşlemler manifest'te belirttiğin panel iznine bağlıdır.
• Loglar: her ayar değişikliği ve işlem kimin yaptığıyla birlikte panel loglarına yazılır.
• Kapatma: panelde eklentiyi kapatırsan işlemler ve tablolar devre dışı kalır; script çalışmaya devam eder ama panelden yönetilemez.

Sınırlar#

Sorun giderme#

Eklenti panelde görünmüyor

• server.cfg sırasını kontrol et: sunasty-bridge script'inden önce başlamalı.
• Sunucu konsolunda [SDK] ... modülü reddedildi yazıyorsa manifest'te hata vardır; mesaj hangi alan olduğunu söyler.
• Köprü panele bağlı mı? Konsolda sunasty:status yaz.

"Eklenti çalışmıyor" hatası

• Script durmuş ya da hata verip kapanmış. Sunucu konsolunu kontrol et, ensure benim-scriptim ile yeniden başlat.

"Script bu işlem için onAction işleyicisi tanımlamamış"

• Manifest'te tanımlı her işlem için onAction çağrılmalı. onAction, registerModule'den sonra çağrılmalı.

Ayar kaydediliyor ama script eski değeri kullanıyor

• sunasty:configChanged:<resource> olayını dinlediğinden ya da değeri her kullanımda getConfig ile okuduğundan emin ol.