Dokümanlar

Genel bakış

Scriptler, sunucunuzu genişleten küçük Lua programlarıdır. Bottan tamamen ayrılmış, yalıtılmış bir Lua 5.5 sandbox sürecinde çalışırlar. Bir script veritabanına, dosya sistemine veya diğer sunuculara asla dokunmaz. Her yetenek, IPC üzerinden bota geri dönen izin listeli bir host API'sinden geçer.

Başlarken

1. 1

   Yerelde bir .lua dosyası yazın

   VS Code, Neovim veya herhangi bir editör.
2. 2

   Yerelde kontrol edin (isteğe bağlı)

   script_runner --check file.lua komutu check: ok yazdırır.
3. 3

   Yükleyin

   Sunucunuzun Scriptler sayfasını açın, kodu yapıştırın veya .lua dosyasını yükleyin (en fazla 64 KiB).
4. 4

   Deneme çalıştırması

   Hiçbir şeyi çalıştırmadan boyutu, kodlamayı, bytecode'u ve yasaklı API'leri doğrular.
5. 5

   Etkinleştirin

   Sürümün yetkili onayını bekleyin, sonra Etkinleştir'e basın. Bot onu birkaç saniye içinde yükler.
6. 6

   Bir log kanalı belirleyin

   bot:log çıktısını ve hata bildirimlerini orada alın.

Yaşam döngüsü ve inceleme

Scriptler sürümlüdür. Bir sürüm gönderdiğiniz anda dondurulur ve SHA-256 ile tanımlanır. Yalnızca onaylı sürümler etkinleştirilebilir ve bot yalnızca etkin sürümleri yükler.

1. 1

   Yazın

   .lua dosyasını yerelde VS Code, Neovim veya herhangi bir editörde oluşturun. Tarayıcıda editör bilerek yoktur.
2. 2

   Deneme çalıştırması / yükleme

   Kodu yapıştırın veya .lua dosyasını sunucunun Scriptler sayfasında yükleyin (≤ 64 KiB, ikili değil). Deneme çalıştırması hiçbir şeyi çalıştırmadan boyutu, kodlamayı, bytecode'u ve yasaklı API'leri doğrular.
3. 3

   İnceleme

   Her yeni script ve her yeni sürüm beklemede başlar. Yetkili, kodun çalışabilmesi için önce o kod revizyonunu onaylar veya reddeder.
4. 4

   Etkinleştirme

   Onaylı bir sürümü siz etkinleştirirsiniz. Beklemedeki veya reddedilmiş bir sürümün etkinleştirilmesi reddedilir. Bot yalnızca etkin sürümleri yükler.
5. 5

   Çalıştırma

   Bot sürümü (kod + SHA-256, çalıştırıcı tarafından doğrulanır) yalıtılmış bir Lua 5.5 sandbox'ına yükler. Olaylar yalnızca bot:on ile kaydedilmiş handler'lara dağıtılır.
6. 6

   Güncelleme / geri alma

   Yeni bir sürüm yükleyin (yine beklemede) veya geri almak için daha eski onaylı bir sürümü etkinleştirin. KV depolaması kalır.
7. 7

   Devre dışı bırakma / silme

   Devre dışı bırakma yüklemeyi hemen durdurur, 'Tümünü devre dışı bırak' sunucunun tüm etkin scriptlerini etkiler. Silme; scripti, sürümlerini, KV'yi ve hataları kaldırır.

Handler'lar ve olaylar

Handler'ları bot:on(event, fn) ile kaydedin. Script, kayıtlı olaylarını yüklenirken bildirir ve ona yalnızca bu olaylar iletilir. Bilinmeyen olay adları yüklemeyi başarısız kılar ve bir script olay başına en fazla 8 handler kaydedebilir.

bot:on("message_create", function(msg)
  if msg.content == "!ping" then
    msg:reply("pong")
  end
end)

Mesaj benzeri olaylar (message_*, automod_check) yöntemleri olan bir mesaj nesnesi iletir, bkz. Mesaj nesnesi.

Host çağrıları yield eder: bir handler bot:kv_get ve benzeri çağrıları beklerken aynı scriptte ikinci bir olay çalışmaz. Yeni olaylar 32'lik bir kuyrukta bekler, taşma durumunda en eski olay düşer ve sürekli taşma scripti karantinaya alır.

Olay yükleri

Her yük guild_id taşır. Alanlar küçük harfli snake_case tablolardır.

• message_create

  id, guild_id, channel_id, author_id, author, content, attachments, referenced_id

  Etiketlerden/otomatik yanıttan önce tetiklenir. Ekler: en fazla 8 kayıt { id, filename, size }. Yanıt referansı yoksa referenced_id 0'dır.

• message_update

  same as message_create

• message_delete

  channel_id, id

• message_delete_bulk

  channel_id, ids

  ids, silinen mesaj ID'lerinin bir dizisidir.

• guild_member_add

  user_id

  Bot hesapları atlanır.

• guild_member_remove

  user_id

• guild_member_update

  user_id

• reaction_add

  channel_id, id, author_id, user_id, emoji, emoji_id

  Bot tepkileri atlanır. emoji addır, unicode emojiler için emoji_id 0'dır.

• reaction_remove

  channel_id, id, author_id, user_id, emoji, emoji_id

• channel_create

  id, name, type

• channel_update

  id, name, type

• channel_delete

  id, name

• role_create

  id, name

• role_update

  id, name

• role_delete

  id, name

• thread_create

  id, name

• thread_update

  id, name

• thread_delete

  id

• invite_create

  code, uses

• invite_delete

  code

• guild_ban_add

  user_id

• guild_ban_remove

  user_id

• welcome_before

  user_id, username

  Yerel karşılama mesajından önce tetiklenir. Yalnızca bot olmayan katılımlar.

• goodbye_before

  user_id

  Yerel veda mesajından önce tetiklenir.

• ticket_created

  ticket_id, user_id, channel_id

• automod_check

  content, channel_id, author_id, id

  Yerel AutoMod'dan önce tetiklenir. msg:escalate() süren mesajı siler; yerel ret her zaman kazanır; msg:allow() etkisizdir.

• webhooks_update

  channel_id

• emoji_update

  count, ids

  ids en fazla 8 ile sınırlıdır.

• tick

  unix

  Her 60 saniyede bir, yalnızca bot:on("tick") kaydeden scriptlere iletilir. unix, unix zamanıdır.

Host API'leri

Bu çağrılar IPC üzerinden bota yield eder. Script başına hız sınırları: 30 host çağrısı / 10 sn ve ayrıca 5 Discord gönderimi / 10 sn (reply, channel_send, react, edit, delete, pin, escalate, http_get). member_get ve guild_get gibi önbellek okumaları Discord'a doğrudan gitmez.

• bot:log(msg)

  Script log kanalına ve hata loguna yazar. 30 çağrı / 10 sn limitine sayılır.

• bot:kv_get(key)

  Saklanan JSON değerini veya nil döndürür. Anahtarlar: 1–64 karakter [A-Za-z0-9_-].

• bot:kv_set(key, value)

  En fazla 8 KiB JSON saklar. Script başına 256 anahtar, script başına 1 MiB (premium 8 MiB), sunucu başına 8 MiB.

• bot:kv_del(key)

  Bir anahtarı siler.

• bot:kv_keys()

  En fazla 256 anahtarı sıralı döndürür.

• bot:kv_incr(key, delta?)

  Saklanan bir JSON sayısını artırır, varsayılan delta 1, delta ±1.000.000.000 ile sınırlıdır.

• bot:db_exec(sql, binds?)

  Sunucu script veritabanında tek bir yazma veya şema ifadesi çalıştırır (CREATE TABLE/INDEX, INSERT, UPDATE, DELETE, DROP). İsteğe bağlı bind'ler: nil, boolean, number veya string dizisi, en fazla 8. { changes, last_insert_rowid } döndürür. Kota, meşgul veya limit sorunları hata fırlatmak yerine { error, kind } döndürür; yasaklı ifadeler policy hatası fırlatır.

• bot:db_query(sql, binds?)

  İsteğe bağlı bind'lerle tek bir SELECT çalıştırır ve her biri sütun adlarıyla anahtarlanmış bir tablo olan en fazla 50 satır döndürür. Her zaman LIMIT kullanın. Hata durumunda { error, kind } döndürür, bu yüzden rows.error değerini kontrol edin.

• bot:http_get(url)

  Yalnızca HTTPS GET. Host, sunucu izin listesinde olmalıdır. { status, body, truncated } döndürür; body en fazla 16 KiB. Bekleme, 100 ms'lik Lua duvar saatine sayılmaz.

• bot:channel_send(channel_id, text, embed?)

  Kendi sunucunuzda botun yazabildiği herhangi bir kanala gönderir. msg:reply ile aynı içerik kuralları.

• bot:channel_get(channel_id)

  Önbellek okuması: { id, name, type, parent_id }. Yalnızca kendi sunucunuz.

• bot:member_get(user_id)

  Önbellek okuması: { id, nick, bot, roles (en fazla 20) }.

• bot:role_get(role_id)

  Önbellek okuması: { id, name, position, color }.

• bot:guild_get()

  Kendi sunucu önbelleği: { id, name, owner_id, member_count }.

• bot:self()

  Bot kullanıcısı: { id, username, bot }.

• bot:has_role(user_id, role_id)

  Önbellek okuması, { has: true|false } döndürür.

• bot:channels()

  Sunucunun kanallarının önbellek listesi (en fazla 50).

• bot:roles()

  Sunucunun rollerinin önbellek listesi (en fazla 50).

• bot:now()

  Saniye cinsinden unix zamanı.

• bot:id()

  Bu scriptin UUID'si. Yield etmez, hız sınırlarına sayılmaz.

• bot:message_get(channel_id, message_id)

  Botun mesaj önbelleğinden okuma (ağ üzerinden alma yok).

• bot:can_send(channel_id)

  Botun o kanalda gönderebilip gönderemeyeceğini { ok: true|false } olarak döndürür.

Mesaj nesnesi

Mesaj olayları bir msg tablosunu ve yük alanlarını iletir. Yöntemler yalnızca süren olayın mesajı üzerinde çalışır, rastgele mesajları alıp düzenleyemezsiniz.

• msg:reply(text, embed?)

  Olayın kanalında yanıt verir. Bahsetmeler yalnızca olayın yazarı için çözülür; @everyone / @here temizlenir. Metin 1–2000 bayt, en fazla bir embed.

• msg:react(emoji)

  Olay mesajına tepki ekler.

• msg:unreact(emoji)

  Scriptin kendi tepkisini kaldırır.

• msg:edit(text, embed?)

  Süren mesajı düzenler. Yanıtla aynı içerik kuralları.

• msg:delete()

  Süren mesajı siler.

• msg:pin() / msg:unpin()

  Süren mesajı sabitler/sabitlemeyi kaldırır.

• msg:escalate()

  Yalnızca automod_check: süren mesajı siler (ek işlem, hız sınırlı). Yerel AutoMod kararları her zaman kazanır.

• msg:allow()

  Yalnızca automod_check: mesajı izinli olarak işaretler. Yerel bir reddi geri alamaz, fiilen etkisiz bir işarettir.

Limitler ve kotalar

Tüm limitler, botun ve çalıştırıcının paylaştığı tek bir yapılandırma dosyasında yer alır. Burada yalnızca belgelenmekle kalmaz, çalışma zamanında da uygulanır. Sayılar güncel varsayılanlardır.

• Dil

  Lua 5.5, yalnızca metin parçaları (bytecode reddedilir). io/os.file/require/load/debug/coroutine yok.

• Hesaplama

  Handler başına ~100 ms duvar saati, 10.000.000 komut (count hook).

• Bellek

  Script başına ücretsiz 2 MB, premium 8 MB.

• Kod boyutu

  64 KiB UTF-8 .lua, NUL baytı yok, bytecode yok.

• Host çağrıları

  Script başına 10 sn'de 30 (bot:log dahil).

• Discord gönderimleri

  Script başına 10 sn'de 5 (reply, channel_send, react/unreact, edit, delete, pin/unpin, escalate, http_get). 10 sn'de 8 ret → karantina.

• Handler'lar

  Script başına olay başına en fazla 8. Bilinmeyen olay adları yüklenirken reddedilir.

• Olay kuyruğu

  Script başına derinlik 32, taşmada en eski düşer. 10 sn'de 8+ düşme → karantina.

• HTTP

  HTTPS + sunucu izin listesi, zaman aşımı 3 sn, body 16 KiB, IP/localhost/dahili host yok, userinfo yok.

• KV

  Anahtarlar 1–64 [A-Za-z0-9_-], değerler ≤ 8 KiB JSON, script başına 256 anahtar, script başına 1 MiB (premium 8 MiB), sunucu başına 8 MiB.

• Veritabanı

  Sunucu başına bir SQLite dosyası, tüm scriptleri tarafından paylaşılır: 1 MiB (premium 8 MiB), çağrı başına bir ifade, SQL ≤ 2 KiB, ≤ 8 bind, ≤ 50 satır, ifade başına 20 ms, 64 tablo ve indeks. ATTACH, PRAGMA, transaction, trigger, view veya WITH yok. Sunucudaki her script her tabloyu okuyabilir ve silebilir.

• Etkin scriptler

  Sunucu başına ücretsiz 2, premium 10. Fazla olan en eski etkin scriptler otomatik olarak devre dışı bırakılır.

• Sürümler

  Script başına sınırsız sayıda; her yeni sürüm, yetkili onaylayana kadar beklemededir.

• Bahsetmeler

  Yalnızca olayın yazarı. @everyone / @here temizlenir. Dosya yok, çıkartma yok.

• Yalıtım

  3 hata (timeout/memory/policy/runtime) → kendi yalıtılmış worker'ı (en fazla 4), aksi halde karantina + devre dışı bırakma.

• Hata logu

  Panelde son 24 saat görünür, kayıtlar 7 gün sonra temizlenir.

• Yasaklı

  voice_state yok, mod_* API'leri yok (ban/kick/timeout), sunucular arası erişim yok, veritabanı/dosya sistemi yok, gelir elde etme yok.

• AutoMod

  Yerel AutoMod önce çalışır ve scriptlere karşı her zaman kazanır.

Doğrulama

Bir sürüm saklanmadan önce arka uç statik kontroller çalıştırır. Deneme çalıştırması aynısını kaydetmeden yapar. Sandbox'ın kendisi ikinci savunma hattıdır: yasaklı globaller çalışma zamanında hiç yoktur.

• Boyut / kodlama

  Boş değil, ≤ 64 KiB, NUL baytı olmayan UTF-8.

• Bytecode

  Lua bytecode imzasıyla başlayan her şey reddedilir.

• Yasaklı API'ler

  Statik tarama şunları reddeder: load(, loadfile, dofile, require(, os.execute, io.open, debug., string.dump, loadstring, getfenv, setfenv, package., coroutine., ffi., jit.

• Çalışma zamanı sandbox'ı

  Statik taramadan bir şey kaçsa bile sandbox bu globalleri hiç sunmaz, çağrı policy hatasıyla başarısız olur.

Hatalar ve karantina

Her handler hatası bir türle kaydedilir ve script ayrıntı sayfasında gösterilir (son 24 saat). Kayıtlar 7 gün sonra temizlenir.

• runtime

  Handler'ınızda bir Lua hatası (nil erişimi, hatalı argümanlar, …). Mesaj, Lua hata metnini içerir.

• timeout

  Handler 100 ms duvar saatini aştı veya bir IPC çağrısı zaman aşımına uğradı (1 sn).

• memory

  Script bellek üst sınırını aştı.

• policy

  Script izin verilmeyen bir şey denedi: bilinmeyen olay, çok fazla handler, izin verilmeyen API, aşırı büyük yük.

Mağaza

Mağaza, scriptleri herkese açık paylaşmanızı ve diğer sunuculardan script yüklemenizi sağlar. Yayınlama ve yükleme ikisi de kopya oluşturur. Bir ilanı yüklemek sunucunuzda bağımsız bir script oluşturur, yazarın koduna bağlı kalmaz.

• Yayınlama

  Onaylı sürümü olan etkin bir script, bir açıklama (10–512 karakter) ve 1–8 etiket ([a-z0-9-], 1–24 karakter) gerekir. İlk yayından önce mağaza kullanım koşullarını bir kez kabul etmelisiniz.

• Yükleme

  Yükleme, ilanı sunucunuza kendi scripti olarak kopyalar (taslak, önceden onaylı sürüm, ad alınmışsa sonekli kendi adı). KV kopyalanmaz. İlandaki yükleme sayacı artar.

• Yayından kaldırma

  İlanı mağazadan kaldırır. Mevcut kopyalar kalır ve çalışmaya devam eder; yalnızca artık güncelleme almazlar.

• Para yok

  Açıklamada veya kodda satış, ödeme duvarı, bağış/kripto bağlantıları ve benzeri gelir elde etme yayınlama sırasında reddedilir ve scriptin yasaklanmasına yol açabilir.

• Şikayetler

  Sunucuya erişimi olan herkes bir ilanı nedenle birlikte şikayet edebilir. Yetkililer açık şikayet kuyruğunu görür ve şikayetleri inceledikten sonra kapatır.

• Limitler

  Mağaza listesi sorgu başına en fazla 50 ilan gösterir (arama, etiket, yüklemeye veya en yeniye göre sıralama). Yüklemeler için normal sunucu script kotası geçerlidir.

Örnekler

Kodunu görmek için bir örnek seçin.