डॉक्स

अवलोकन

स्क्रिप्ट छोटे Lua प्रोग्राम हैं जो आपके सर्वर की क्षमताएँ बढ़ाते हैं। ये एक अलग-थलग Lua 5.5 सैंडबॉक्स प्रोसेस में चलते हैं, जो बॉट से पूरी तरह अलग है। स्क्रिप्ट कभी डेटाबेस, फ़ाइलसिस्टम या दूसरे सर्वरों को नहीं छूती। हर क्षमता एक व्हाइटलिस्टेड होस्ट API से होकर गुज़रती है जो IPC के ज़रिए बॉट को नियंत्रण लौटा देती है।

शुरुआत करें

1. 1

   लोकल में .lua फ़ाइल लिखें

   VS Code, Neovim या कोई भी एडिटर।
2. 2

   लोकल में जाँचें (वैकल्पिक)

   script_runner --check file.lua check: ok प्रिंट करता है।
3. 3

   अपलोड करें

   अपने सर्वर का स्क्रिप्ट पेज खोलें और कोड पेस्ट करें या .lua फ़ाइल अपलोड करें (64 KiB तक)।
4. 4

   ड्राई-रन

   कुछ भी चलाए बिना आकार, एन्कोडिंग, बाइटकोड और प्रतिबंधित API की जाँच करता है।
5. 5

   सक्रिय करें

   वर्शन की स्टाफ़ मंज़ूरी का इंतज़ार करें, फिर सक्रिय करें दबाएँ। बॉट इसे कुछ सेकंड में लोड कर लेता है।
6. 6

   लॉग चैनल सेट करें

   bot:log आउटपुट और त्रुटि सूचनाएँ वहीं पाएँ।

जीवनचक्र और समीक्षा

स्क्रिप्ट वर्शन वाली होती हैं। वर्शन जमा करते ही फ़्रीज़ हो जाता है और उसकी पहचान उसके SHA-256 से होती है। केवल मंज़ूर वर्शन सक्रिय किए जा सकते हैं, और बॉट केवल सक्रिय वर्शन लोड करता है।

1. 1

   लिखें

   VS Code, Neovim या किसी भी एडिटर में लोकल .lua फ़ाइल बनाएँ। ब्राउज़र में एडिटर डिज़ाइन के अनुसार नहीं है।
2. 2

   ड्राई-रन / अपलोड

   सर्वर के स्क्रिप्ट पेज पर कोड पेस्ट करें या .lua फ़ाइल अपलोड करें (≤ 64 KiB, बाइनरी नहीं)। ड्राई-रन कुछ भी चलाए बिना आकार, एन्कोडिंग, बाइटकोड और प्रतिबंधित API की जाँच करता है।
3. 3

   समीक्षा

   हर नई स्क्रिप्ट और हर नया वर्शन लंबित के रूप में शुरू होता है। चलने से पहले स्टाफ़ उस सटीक कोड संशोधन को मंज़ूर या अस्वीकार करता है।
4. 4

   सक्रिय करें

   आप मंज़ूर वर्शन सक्रिय करते हैं। लंबित या अस्वीकृत वर्शन का सक्रियण नकार दिया जाता है। बॉट केवल सक्रिय वर्शन लोड करता है।
5. 5

   चलाएँ

   बॉट वर्शन (कोड + SHA-256, रनर द्वारा सत्यापित) को अलग-थलग Lua 5.5 सैंडबॉक्स में लोड करता है। इवेंट केवल bot:on से पंजीकृत हैंडलर तक पहुँचते हैं।
6. 6

   अपडेट / रोलबैक

   नया वर्शन अपलोड करें (फिर लंबित) या रोलबैक के लिए पुराना मंज़ूर वर्शन सक्रिय करें। KV स्टोरेज बना रहता है।
7. 7

   बंद / हटाएँ

   बंद करने से लोड होना तुरंत रुकता है, 'सब बंद करें' सर्वर की हर सक्रिय स्क्रिप्ट पर लागू होता है। हटाने से स्क्रिप्ट, उसके वर्शन, KV और त्रुटियाँ हट जाती हैं।

हैंडलर और इवेंट

bot:on(event, fn) से हैंडलर पंजीकृत करें। स्क्रिप्ट लोड होते समय अपने पंजीकृत इवेंट बताती है, और केवल वही इवेंट उसे भेजे जाते हैं। अज्ञात इवेंट नाम से लोड विफल हो जाता है, और एक स्क्रिप्ट प्रति इवेंट अधिकतम 8 हैंडलर पंजीकृत कर सकती है।

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

संदेश जैसे इवेंट (message_*, automod_check) मेथड वाला संदेश ऑब्जेक्ट देते हैं, देखें संदेश ऑब्जेक्ट।

होस्ट कॉल नियंत्रण लौटाती हैं: जब हैंडलर bot:kv_get जैसी कॉल का इंतज़ार करता है, उसी स्क्रिप्ट पर दूसरा इवेंट नहीं चलता। नए इवेंट 32 की कतार में रुकते हैं, भर जाने पर सबसे पुराना इवेंट गिरा दिया जाता है, और लगातार बाढ़ आने पर स्क्रिप्ट क्वारंटीन हो जाती है।

इवेंट पेलोड

हर पेलोड में guild_id होता है। फ़ील्ड छोटे अक्षरों वाली snake_case टेबल हैं।

• message_create

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

  टैग/ऑटोरिस्पॉन्डर से पहले चलता है। अटैचमेंट: 8 प्रविष्टियों तक { id, filename, size }। रिप्लाई संदर्भ न हो तो referenced_id 0 होता है।

• message_update

  same as message_create

• message_delete

  channel_id, id

• message_delete_bulk

  channel_id, ids

  ids हटाए गए संदेश IDs की सारणी है।

• guild_member_add

  user_id

  बॉट खाते छोड़ दिए जाते हैं।

• guild_member_remove

  user_id

• guild_member_update

  user_id

• reaction_add

  channel_id, id, author_id, user_id, emoji, emoji_id

  बॉट रिएक्शन छोड़ दिए जाते हैं। emoji नाम है, यूनिकोड इमोजी के लिए emoji_id 0 होता है।

• 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

  नेटिव वेलकम संदेश से पहले चलता है। केवल गैर-बॉट जॉइन।

• goodbye_before

  user_id

  नेटिव गुडबाय संदेश से पहले चलता है।

• ticket_created

  ticket_id, user_id, channel_id

• automod_check

  content, channel_id, author_id, id

  नेटिव ऑटोमॉड से पहले चलता है। msg:escalate() चल रहा संदेश हटाता है; नेटिव अस्वीकृति हमेशा जीतती है; msg:allow() कुछ नहीं करता।

• webhooks_update

  channel_id

• emoji_update

  count, ids

  ids अधिकतम 8।

• tick

  unix

  हर 60 सेकंड में, केवल उन स्क्रिप्ट को भेजा जाता है जिन्होंने bot:on("tick") पंजीकृत किया। unix यूनिक्स समय है।

होस्ट API

ये कॉल IPC के ज़रिए बॉट को नियंत्रण लौटाती हैं। प्रति स्क्रिप्ट दर सीमाएँ: 30 होस्ट कॉल / 10 से, साथ में 5 Discord भेजना / 10 से (reply, channel_send, react, edit, delete, pin, escalate, http_get)। member_get और guild_get जैसी कैश रीड सीधे Discord तक कभी नहीं पहुँचतीं।

• bot:log(msg)

  स्क्रिप्ट लॉग चैनल और त्रुटि लॉग में लिखता है। 30 कॉल / 10 से की सीमा में गिना जाता है।

• bot:kv_get(key)

  सहेजा हुआ JSON मान या nil लौटाता है। कुंजियाँ: 1–64 अक्षर [A-Za-z0-9_-]।

• bot:kv_set(key, value)

  8 KiB तक JSON सहेजता है। प्रति स्क्रिप्ट 256 कुंजियाँ, प्रति स्क्रिप्ट 1 MiB (प्रीमियम में 8 MiB), प्रति सर्वर 8 MiB।

• bot:kv_del(key)

  एक कुंजी हटाता है।

• bot:kv_keys()

  256 तक कुंजियाँ क्रमबद्ध लौटाता है।

• bot:kv_incr(key, delta?)

  सहेजी हुई JSON संख्या बढ़ाता है, डिफ़ॉल्ट डेल्टा 1, डेल्टा ±1,000,000,000 तक सीमित।

• bot:db_exec(sql, binds?)

  सर्वर स्क्रिप्ट डेटाबेस पर एक राइट या स्कीमा स्टेटमेंट (CREATE TABLE/INDEX, INSERT, UPDATE, DELETE, DROP) चलाता है। वैकल्पिक बाइंड: nil, boolean, number या string की सारणी, 8 तक। { changes, last_insert_rowid } लौटाता है। कोटा, व्यस्त या सीमा की समस्याएँ त्रुटि उठाने की बजाय { error, kind } लौटाती हैं; प्रतिबंधित स्टेटमेंट पॉलिसी त्रुटि उठाते हैं।

• bot:db_query(sql, binds?)

  वैकल्पिक बाइंड के साथ एक SELECT चलाता है और 50 पंक्तियों तक लौटाता है, हर एक कॉलम नाम से कुंजीबद्ध टेबल। हमेशा LIMIT का उपयोग करें। विफल होने पर { error, kind } लौटाता है, इसलिए rows.error जाँचें।

• bot:http_get(url)

  केवल HTTPS GET। होस्ट सर्वर अलाउलिस्ट में होना चाहिए। { status, body, truncated } लौटाता है; body 16 KiB तक सीमित। प्रतीक्षा 100 ms Lua वॉल क्लॉक में नहीं गिनी जाती।

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

  अपने सर्वर के किसी भी चैनल पर भेजें जहाँ बॉट लिख सकता है। सामग्री के नियम msg:reply जैसे ही हैं।

• bot:channel_get(channel_id)

  कैश रीड: { id, name, type, parent_id }। केवल अपना सर्वर।

• bot:member_get(user_id)

  कैश रीड: { id, nick, bot, roles (20 तक) }।

• bot:role_get(role_id)

  कैश रीड: { id, name, position, color }।

• bot:guild_get()

  अपने सर्वर का कैश: { id, name, owner_id, member_count }।

• bot:self()

  बॉट उपयोगकर्ता: { id, username, bot }।

• bot:has_role(user_id, role_id)

  कैश रीड, { has: true|false } लौटाता है।

• bot:channels()

  सर्वर के चैनलों की कैश सूची (अधिकतम 50)।

• bot:roles()

  सर्वर के रोल की कैश सूची (अधिकतम 50)।

• bot:now()

  सेकंड में यूनिक्स समय।

• bot:id()

  इस स्क्रिप्ट का UUID। नियंत्रण नहीं लौटाता, दर सीमाओं में नहीं गिना जाता।

• bot:message_get(channel_id, message_id)

  बॉट के संदेश कैश की रीड (नेटवर्क फ़ेच नहीं)।

• bot:can_send(channel_id)

  { ok: true|false } लौटाता है कि बॉट उस चैनल में भेज सकता है या नहीं।

संदेश ऑब्जेक्ट

संदेश इवेंट एक msg टेबल और पेलोड फ़ील्ड देते हैं। मेथड केवल चल रहे इवेंट के संदेश पर काम करते हैं, आप किसी भी संदेश को फ़ेच करके एडिट नहीं कर सकते।

• msg:reply(text, embed?)

  इवेंट चैनल में जवाब देता है। मेंशन केवल इवेंट के लेखक के लिए हल होते हैं; @everyone / @here हटा दिए जाते हैं। टेक्स्ट 1–2000 बाइट, अधिकतम एक एम्बेड।

• msg:react(emoji)

  इवेंट के संदेश पर रिएक्शन जोड़ता है।

• msg:unreact(emoji)

  स्क्रिप्ट का अपना रिएक्शन हटाता है।

• msg:edit(text, embed?)

  चल रहे संदेश को एडिट करता है। सामग्री के नियम reply जैसे ही हैं।

• msg:delete()

  चल रहा संदेश हटाता है।

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

  चल रहे संदेश को पिन/अनपिन करता है।

• msg:escalate()

  केवल automod_check: चल रहा संदेश हटाता है (अतिरिक्त कार्रवाई, दर-सीमित)। नेटिव ऑटोमॉड के फ़ैसले हमेशा जीतते हैं।

• msg:allow()

  केवल automod_check: संदेश को अनुमत चिह्नित करता है। यह नेटिव अस्वीकृति को पलट नहीं सकता — यह असल में बिना असर वाला मार्कर है।

सीमाएँ और कोटा

सभी सीमाएँ एक ही कॉन्फ़िग फ़ाइल में हैं जिसे बॉट और रनर साझा करते हैं। ये केवल यहाँ दर्ज नहीं हैं, रनटाइम पर लागू होती हैं। संख्याएँ वर्तमान डिफ़ॉल्ट हैं।

• भाषा

  Lua 5.5, केवल टेक्स्ट चंक (बाइटकोड अस्वीकार)। io/os.file/require/load/debug/coroutine नहीं।

• कंप्यूट

  प्रति हैंडलर ~100 ms वॉल क्लॉक, 10,000,000 इंस्ट्रक्शन (काउंट हुक)।

• मेमोरी

  प्रति स्क्रिप्ट फ़्री में 2 MB, प्रीमियम में 8 MB।

• कोड आकार

  64 KiB UTF-8 .lua, कोई NUL बाइट नहीं, कोई बाइटकोड नहीं।

• होस्ट कॉल

  प्रति स्क्रिप्ट 10 से में 30 (bot:log सहित)।

• Discord भेजना

  प्रति स्क्रिप्ट 10 से में 5 (reply, channel_send, react/unreact, edit, delete, pin/unpin, escalate, http_get)। 10 से में 8 अस्वीकृतियाँ → क्वारंटीन।

• हैंडलर

  प्रति स्क्रिप्ट प्रति इवेंट अधिकतम 8। अज्ञात इवेंट नाम लोड पर अस्वीकार किए जाते हैं।

• इवेंट कतार

  प्रति स्क्रिप्ट गहराई 32, भरने पर सबसे पुराना गिराया जाता है। 10 से में 8+ ड्रॉप → क्वारंटीन।

• HTTP

  HTTPS + सर्वर अलाउलिस्ट, टाइमआउट 3 से, body 16 KiB, कोई IP/localhost/आंतरिक होस्ट नहीं, कोई userinfo नहीं।

• KV

  कुंजियाँ 1–64 [A-Za-z0-9_-], मान ≤ 8 KiB JSON, 256 कुंजियाँ/स्क्रिप्ट, 1 MiB/स्क्रिप्ट (प्रीमियम में 8 MiB), 8 MiB/सर्वर।

• डेटाबेस

  प्रति सर्वर एक SQLite फ़ाइल, उसकी सभी स्क्रिप्ट द्वारा साझा: 1 MiB (प्रीमियम में 8 MiB), प्रति कॉल एक स्टेटमेंट, SQL ≤ 2 KiB, ≤ 8 बाइंड, ≤ 50 पंक्तियाँ, प्रति स्टेटमेंट 20 ms, 64 टेबल और इंडेक्स। ATTACH, PRAGMA, ट्रांज़ैक्शन, ट्रिगर, व्यू या WITH नहीं। सर्वर की हर स्क्रिप्ट हर टेबल पढ़ और हटा सकती है।

• सक्रिय स्क्रिप्ट

  प्रति सर्वर फ़्री में 2, प्रीमियम में 10। अधिक होने पर सबसे पुरानी सक्रिय स्क्रिप्ट अपने आप बंद हो जाती हैं।

• वर्शन

  प्रति स्क्रिप्ट संख्या असीमित; हर नया वर्शन स्टाफ़ के मंज़ूर करने तक लंबित रहता है।

• मेंशन

  केवल इवेंट का लेखक। @everyone / @here हटाए जाते हैं। कोई फ़ाइल या स्टिकर नहीं।

• आइसोलेशन

  3 गड़बड़ियाँ (टाइमआउट/मेमोरी/पॉलिसी/रनटाइम) → अपना अलग वर्कर (अधिकतम 4), वरना क्वारंटीन + अनलोड।

• त्रुटि लॉग

  डैशबोर्ड में पिछले 24 घंटे दिखते हैं, प्रविष्टियाँ 7 दिन बाद हटा दी जाती हैं।

• प्रतिबंधित

  voice_state नहीं, mod_* API (ban/kick/timeout) नहीं, क्रॉस-सर्वर एक्सेस नहीं, डेटाबेस/फ़ाइलसिस्टम नहीं, मुद्रीकरण नहीं।

• ऑटोमॉड

  नेटिव ऑटोमॉड पहले चलता है और स्क्रिप्ट पर हमेशा भारी पड़ता है।

सत्यापन

वर्शन सहेजे जाने से पहले बैकएंड स्टैटिक जाँच चलाता है। ड्राई-रन सहेजे बिना वही काम करता है। सैंडबॉक्स खुद दूसरी रक्षा-पंक्ति है: प्रतिबंधित ग्लोबल रनटाइम पर मौजूद ही नहीं होते।

• आकार / एन्कोडिंग

  खाली नहीं, ≤ 64 KiB, बिना NUL बाइट का UTF-8।

• बाइटकोड

  Lua बाइटकोड सिग्नेचर से शुरू होने वाली कोई भी चीज़ अस्वीकार होती है।

• प्रतिबंधित API

  स्टैटिक स्कैन इन्हें अस्वीकार करता है: load(, loadfile, dofile, require(, os.execute, io.open, debug., string.dump, loadstring, getfenv, setfenv, package., coroutine., ffi., jit.

• रनटाइम सैंडबॉक्स

  स्टैटिक स्कैन से कुछ निकल भी जाए तो सैंडबॉक्स ये ग्लोबल उपलब्ध ही नहीं कराता — कॉल पॉलिसी त्रुटि के साथ विफल होती है।

त्रुटियाँ और क्वारंटीन

हर हैंडलर त्रुटि प्रकार के साथ दर्ज होती है और स्क्रिप्ट विवरण पेज पर दिखती है (पिछले 24 घंटे)। प्रविष्टियाँ 7 दिन बाद हटा दी जाती हैं।

• runtime

  आपके हैंडलर में Lua त्रुटि (nil एक्सेस, गलत आर्ग्युमेंट, …)। संदेश में Lua त्रुटि का टेक्स्ट शामिल होता है।

• timeout

  हैंडलर 100 ms वॉल क्लॉक से आगे निकल गया या IPC कॉल का टाइमआउट हो गया (1 से)।

• memory

  स्क्रिप्ट अपनी मेमोरी सीमा से आगे निकल गई।

• policy

  स्क्रिप्ट ने कुछ अनुमति-रहित करने की कोशिश की: अज्ञात इवेंट, बहुत ज़्यादा हैंडलर, अनुमति-रहित API, बहुत बड़ा पेलोड।

स्टोर

स्टोर से आप स्क्रिप्ट सार्वजनिक रूप से साझा कर सकते हैं और दूसरे सर्वरों की स्क्रिप्ट इंस्टॉल कर सकते हैं। प्रकाशित करना और इंस्टॉल करना दोनों प्रतियाँ बनाते हैं। लिस्टिंग इंस्टॉल करने से आपके सर्वर में एक स्वतंत्र स्क्रिप्ट बनती है, वह लेखक के कोड से जुड़ी नहीं रहती।

• प्रकाशित करें

  मंज़ूर वर्शन वाली सक्रिय स्क्रिप्ट, एक विवरण (10–512 अक्षर) और 1–8 टैग ([a-z0-9-], 1–24 अक्षर) चाहिए। पहले प्रकाशन से पहले आपको स्टोर ToS एक बार स्वीकार करना होगा।

• इंस्टॉल करें

  इंस्टॉल करने से लिस्टिंग आपके सर्वर में अपनी स्क्रिप्ट के रूप में कॉपी होती है (ड्राफ़्ट, पहले से मंज़ूर वर्शन, नाम लिया हुआ हो तो प्रत्यय के साथ अपना नाम)। KV कॉपी नहीं होता। लिस्टिंग का इंस्टॉल काउंटर बढ़ता है।

• अप्रकाशित करें

  लिस्टिंग को स्टोर से हटाता है। मौजूदा प्रतियाँ बनी रहती हैं और चलती रहती हैं; बस उन्हें और अपडेट नहीं मिलते।

• पैसे नहीं

  विवरण या कोड में बिक्री, पेवॉल, दान/क्रिप्टो लिंक और ऐसा मुद्रीकरण प्रकाशन पर अस्वीकार होता है और स्क्रिप्ट पर प्रतिबंध लग सकता है।

• रिपोर्ट

  सर्वर एक्सेस वाला कोई भी कारण के साथ लिस्टिंग की रिपोर्ट कर सकता है। स्टाफ़ को खुली रिपोर्ट की कतार दिखती है और समीक्षा के बाद रिपोर्ट बंद करता है।

• सीमाएँ

  स्टोर सूची प्रति क्वेरी 50 लिस्टिंग तक दिखाती है (खोज, टैग, इंस्टॉल या नए के अनुसार क्रम)। इंस्टॉल पर सामान्य सर्वर स्क्रिप्ट कोटा लागू होता है।

उदाहरण

कोड देखने के लिए कोई उदाहरण चुनें।