كيفية استخدام البرمجة النصية في Questsmith

تمنح البرمجة النصية المنشئين قدرة على تخصيص تجربة اللاعب بما يتجاوز ما يدعمه محرر السيناريو.

في Questsmith، تُربط النصوص البرمجية بالسيناريوهات وتُشاركها المغامرات التي تبدأ من ذلك السيناريو، بينما يحتفظ كل مغامرة بحالة لعب مستقلة خاصة بها.

دعم السيناريو ومستوى الظهور

• تتوفر النصوص البرمجية لسيناريوهات البدء البسيط ومنشئ الشخصيات.
• لا يمكن للسيناريو الأب متعدد الخيارات أن يحتوي على نص برمجي، لكن خياراته الفرعية يمكنها ذلك.
• فقط منشئ السيناريو يستطيع عرض النصوص البرمجية وتعديلها.
• قد تخضع النصوص البرمجية في السيناريوهات المنشورة لمراجعة الإشراف للتأكد من الالتزام بالإرشادات.

نظرة عامة على واجهة البرمجة النصية

افتح قسم البرمجة النصية من أسفل تبويب التفاصيل أثناء تعديل سيناريو مدعوم.

• المكتبة: دوال مساعدة وثوابت مشتركة متاحة لبقية النصوص البرمجية.
• الإدخال: يعمل أثناء خطاف دورة الحياة onInput.
• السياق: يعمل أثناء خطاف دورة الحياة onModelContext.
• الإخراج: يعمل أثناء خطاف دورة الحياة onOutput.

في النصوص غير التابعة للمكتبة، يجب أن يستدعي السطر الأخير modifier(text).

لوحة اختبار النص البرمجي

• الإدخال: حمولة اختبار قابلة للتحرير لمحاكاة سلوك النص البرمجي.
• إرسال: يرسل النص البرمجي + المكتبة + الإدخال إلى الخادم للتنفيذ.
• الإخراج: يعرض النص المُعاد، والقيمة stop، والسجلات، والحالة state، وstoryCards.

لوحة سجلات وحدة التحكم

• تعرض أحدث السجلات من مغامرات الاختبار الخاصة بك التي بدأت من هذا السيناريو.
• تتدفق آنيا، وهي مفيدة مع التبويبات المقسمة (المحرر + الاختبار).
• يتم الاحتفاظ بالسجلات لمدة 15 دقيقة.

خطافات دورة الحياة

توفر واجهة برمجة البرمجة النصية ثلاثة خطافات، يعمل كل واحد منها داخل بيئة معزولة.

• onInput
• onModelContext
• onOutput

حدود التشغيل: ذاكرة 16 ميغابايت ومهلة زمنية قدرها ثانيتان لكل خطاف.

المعاملات المتاحة

يمكنك استخدام هذه القيم مباشرة داخل نطاق النص البرمجي:

• text: إدخال اللاعب أو نص سياق النموذج أو نص الإخراج بحسب الخطاف.
• history: مصفوفة أحدث الأفعال وتتضمن text وrawText وtype.
• storyCards: مصفوفة بطاقات المغامرة (الاسم القديم worldInfo لا يزال مدعوما).
• state: كائن دائم لذاكرة نص برمجي مخصصة عبر الأدوار.
• info: بيانات مساعدة مثل actionCount وcharacterNames وmaxChars وmemoryLength.

ملاحظات حول كائن state

• عدّل state مباشرة دون الحاجة إلى دالة مساعدة.
• يدعم state.memory تجاوزات context وauthorsNote وfrontMemory.
• يخزن state.placeholders قيم أسئلة وأجوبة العناصر النائبة في السيناريو ويحتفظ بها عبر الأدوار.
• قد تظهر state.message للاعبين بحسب دعم العميل.

الدوال المتاحة

• log
• addStoryCard
• removeStoryCard
• updateStoryCard

صيغة الإرجاع

يفضل أن يعيد النص البرمجي كائنا، وغالبا يكون بالشكل التالي:

return { text: 'نص جديد' }
return { stop: true }

• text: يستبدل تدفق نص الخطاف (الإدخال أو سياق النموذج أو الإخراج).
• stop: يوقف تقدم الحلقة. استخدمه بحذر وبشكل مقصود.

سلوك الأخطاء المهم

• إرجاع نص فارغ في onInput يسبب خطأ نص برمجي يظهر للاعب.
• إرجاع نص فارغ في onModelContext يتصرف كما لو أن النص البرمجي لم يعمل.
• إرجاع نص فارغ في onOutput يسبب فشل نص برمجي مخصصا يظهر للاعب.
• لا يوصى بإرجاع stop داخل onOutput.

مثال أدنى لنص إدخال برمجي

const modifier = (text) => {
  let modifiedText = text

  if (text.includes('أمسك سيفا')) {
    state.items = ['sword']
    state.memory = { context: 'لديك سيف.' }
    state.message = 'لقد حصلت على سيف!'
    log('تمت إضافة سيف للاعب')
    modifiedText = text + '\nوالآن لديك سيف أيضا!'
  }

  return { text: modifiedText }
}

modifier(text)

حالات استخدام عملية

• محللات الأوامر (أوامر مخصصة للاعب).
• تتبع المخزون أو الحالة داخل state.
• تعديلات ديناميكية على memory وauthorsNote وfrontMemory.
• معالجة لاحقة للسياق وإضافة حدود أمان.
• إدراج بطاقات القصة أو حذفها تلقائيا بناء على الأحداث.

أفضل الممارسات

1. ابدأ بنصوص برمجية صغيرة واختبر كل خطاف على حدة.
2. حافظ على حتمية النصوص البرمجية وتجنب الحسابات الثقيلة.
3. استخدم المكتبة للمنطق القابل لإعادة الاستخدام والثوابت.
4. تحقق من القيم غير المعرفة مثل history وplaceholders وقيم info.
5. فضّل التعديلات الإضافية على إعادة كتابة النص بالكامل متى أمكن.
6. استخدم لوحة السجلات أثناء اختبارات اللعب الحية وكرر المشكلة بأبسط صورة ممكنة.

لمشكلات النصوص البرمجية أو طلبات الميزات، استخدم قناة الأخطاء/طلبات الميزات في Discord وأرفق خطوات قابلة لإعادة الإنتاج متى أمكن.