Bu rehber, özel entegrasyon eklerken bütün kategorilerde kullanacağın ortak kuralları anlatır.
Capability ve action mapping farkı
Capability, Panel’in bildiği sabit işlem adıdır. Action mapping ise bu işlemin senin resource’unda nasıl gerçekleştirileceğini söyler.
| Panel isteği | Capability örneği | Resource içindeki karşılığı |
|---|
| Marketleri listele | shops.list | Bir export veya SQL sorgusu |
| Oyuncuyu dirilt | ems.revive | Bir server/client event |
| Kapıyı aç veya kilitle | doorlock.toggle | Export veya event |
| Personel rütbesini değiştir | management.grade.set | Export, event veya desteklenen framework işlemi |
housing.list ister.
Erişim seviyeleri
| Seviye | Anlamı | Örnek |
|---|
| Okuma | Veri getirir, oyun durumunu değiştirmez | shops.list |
| Yazma | Oyun veya veritabanı durumunu değiştirir | character.job.set |
| Kritik | Para silme, ev devretme veya kayıt silme gibi yüksek riskli işlemdir | banking.money.remove |
Önce okuma capability’sini çalıştır. Listeleme başarısızken oluşturma, düzenleme veya silme işlemlerini aktif etme.
Action türleri
| Tür | Ne zaman kullanılır? | Öneri |
|---|
| Export | Paket dışarıya hazır bir fonksiyon sunuyorsa | Okuma ve doğrulama işlemlerinde tercih et |
| Event | Paket işlemleri event ile yapıyorsa | Özellikle oyuncuya uygulanan aksiyonlarda kullan |
| SQL | Veri yalnızca veritabanında bulunuyorsa | Öncelikle okuma için kullan |
| Custom | Standart yöntemler pakete yetmiyorsa | Destek ekibiyle birlikte doğrula |
Temel mapping alanları
| Alan | Açıklama |
|---|
type | export, event veya sql |
side | İşlemin server veya client tarafında çalışacağını belirtir |
resource | server.cfg içindeki resource adı |
name | Çağrılacak export veya event adı |
args | İşleme gönderilecek değerlerin sırası |
query | SQL action için kullanılacak sorgu |
result_path | Dönen cevabın hangi alanından veri okunacağını belirtir |
Export örneği
{
"shops.list": {
"type": "export",
"side": "server",
"resource": "my-shops",
"name": "GetPanelShops"
}
}
Event örneği
{
"notify.send": {
"type": "event",
"side": "server",
"resource": "my-notify",
"name": "my-notify:server:send",
"args": ["player_id", "payload.message", "payload.type"]
}
}
SQL okuma örneği
{
"doorlock.list": {
"type": "sql",
"query": "SELECT id, name, locked, job FROM doorlocks ORDER BY id ASC",
"result_path": "doors"
}
}
SQL action’larında önce salt okunur sorgular kullan. Yazma sorguları paket önbelleğini atlayabilir ve oyun içi durumla veritabanını farklı hale getirebilir.
Liste cevabı nasıl olmalı?
Liste capability’leri boş olsa bile geçerli bir liste döndürmelidir. Bir paketin cevap alanı farklıysa Sonuç yolu alanını kullan.
{
"ok": true,
"items": [
{
"id": "example-1",
"label": "Örnek kayıt"
}
]
}
items alanındaysa sonuç yolu items olarak ayarlanır.
Test sonucunu okuma
| Adım | Başarılı sonuç neyi gösterir? |
|---|
| Resource bulundu | Resource başlatılmış ve adı doğru |
| Capability eşleşti | Panel sayfası doğru işlem adını çağırabilir |
| Action bulundu | Export, event veya SQL ayarı kullanılabilir |
| Cevap alındı | İşlem zaman aşımına uğramadan döndü |
| Veri biçimi geçerli | Panel cevabı okuyabilir |
capability_not_synced görürsen plugin’in son bağlantısını kontrol et, health check çalıştır ve entegrasyonu tekrar test et.
Canlıya almadan önce kontrol listesi
- Doğru sunucu seçili.
- Resource adı
ensure adıyla birebir aynı.
- Okuma action’ları veri döndürüyor.
- Boş listeler hata yerine boş liste olarak dönüyor.
- Yazma işlemi oyun içinde de doğrulandı.
- Silme ve para işlemleri yalnızca yetkili rollere açık.
- Paket restartlandıktan sonra tekrar test edildi.
