المرجع — دليل لغة أقلامنا الكامل

هذا المرجع يغطي كلّ كلمة مفتاحية وكلّ تركيب في لغة أقلامنا (.qalam). كلّ معلومة مصحوبة بمثال قصير يعمل.

لست مضطرًّا إلى قراءة هذا لتكتب قصة. المحرر يفتح على بطاقات وحقول، ويكتب هذه اللغة نيابةً عنك. ابدأ من البداية — دليل يبني قصة كاملة دون رمز واحد. اقرأ هذا المرجع إذا أردت الوضع المتقدّم (⚙️ الإعدادات ← وضع المحرر ← متقدّم)، أو أردت شيئًا لا تجد له حقلًا: خيارات متداخلة، أنفاقًا، قوائم، أو إدراج قيمة متغيّر في وسط جملة.

ما يقابل ماذا

كلّ ما لا يظهر في هذا الجدول لا حقل له في المحرر المرئي. ويمكنك استعماله في الوضع المتقدّم، لكنّ المحرر المرئي لن يرسم القصة بعدها: يقول لك ما الذي لا يستطيع عرضه، ويعرض عليك المحرّر النصّي، ولا يحذف حرفًا.

محتويات الملف

يمكن أن يبدأ الملف ببيانات اختيارية تُكتب قبل أول ===:

عنوان: "لص القصر"
مؤلف: "سارة أحمد"
لغة: "ar"

الأسماء الإنجليزية: TITLE:, AUTHOR:, LANGUAGE:

إذا لم تُكتب، فالعنوان الافتراضي هو اسم الملف.

العنوان والمؤلف يظهران للقارئ: العنوان في أعلى كلّ شاشة، وتحته بقلم واسم المؤلف. ويُكتب اسم المؤلف كذلك في ترويسة الملفّ المصدَّر (<meta name="author">)، فيقرؤه المتصفّح ومدير المفضّلة ومحرّك البحث. وإن لم تكتب مؤلفًا فلا يظهر السطر ولا تُكتب الترويسة.

المقاطع

المقطع هو الوحدة الأساسية — ما يراه القارئ دفعة واحدة.

=== اسم_المقطع ===

كل ما يلي العنوان حتى المقطع التالي هو محتوى هذا المقطع.

المقطع الأول في الملف هو مقطع البداية (أول ما يراه القارئ).

المقاطع الفرعية

داخل المقطع، يمكن تعريف مقاطع فرعية بعلامة =:

=== المنزل ===

= غرفة_النوم
تستيقظ في غرفة مظلمة.

= المطبخ
رائحة القهوة تملأ المكان.

للإشارة إلى مقطع فرعي: المنزل.غرفة_النوم — اسم المقطع متبوعًا بنقطة ثم اسم المقطع الفرعي.

الخيارات

خيار عادي *

يختفي بعد أن يختاره القارئ مرة واحدة:

=== مقطع ===

* [نص الزر]
  النص الذي يظهر بعد الاختيار.
  -> تابع

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

خيار دائم +

يبقى متاحًا مهما استخدمه القارئ:

=== البداية ===

+ [عد للخلف]
  تعود أدراجك.
  -> البداية

القوسان [ ] واجبان

نصّ الزرّ يُكتب بين قوسين معقوفين دائمًا. سطر مثل * افتح الباب دون قوسين لا يُقبَل.

هذا المرجع كان يذكر "خيارًا دون نصّ منفصل" ويقول إنّ السطر كلّه يصير نصّ الزرّ. لم يكن ذلك صحيحًا يومًا: المحلّل يرفض السطر. حُذف في ١ آب ٢٠٢٦ بعد أن صار كلّ مثال في هذه الملفّات يُجمَّع في كلّ بناء.

خيارات متداخلة

داخل الخيار يمكن أن يكون هناك خيارات فرعية بالعلامة **:

=== البداية ===

* [افتح الباب]
  الباب مقفل.
  ** [ابحث عن المفتاح]
     وجدت المفتاح تحت السجادة.
     -> الممر
  ** [حاول كسر الباب]
     الباب متين جدًا.
     -> البداية

=== الممر ===

الممر مظلم.

ملاحظة: النص بعد [ ] في الخيار الأساسي يظهر كله قبل الخيارات المتداخلة.

الانتقالات

-> اذهب إلى مقطع

-> اسم_المقطع

ينهي المقطع الحالي وينتقل فورًا.

->-> العودة من نفق

يُستخدم داخل مقطع نفق للعودة إلى المكان الذي استُدعي منه:

=== وصف_الغرفة ===
الغرفة واسعة. الجدران مزينة بنقوش عربية.
->->

نهاية و END

ينهي القصة:

-> نهاية
-> END

تابع و DONE

لا يغير المقطع — يُبقي القارئ في نفس المكان (مفيد مع الخيارات التي لا تنتقل):

=== الغرفة ===

* [انظر حولك]
  لا ترى شيئًا جديدًا.
  -> تابع

المتغيرات

تعريف متغير

متغير نقاط = ٠
متغير اسم_البطل = "سيف"
متغير وجد_الكنز = خطأ

الأسماء الإنجليزية: VAR

الأنواع المدعومة: أعداد، نصوص، قيم منطقية (صح/خطأ)

تغيير قيمة متغير

~ نقاط = نقاط + ٥
~ اسم_البطل = "ليلى"
~ وجد_الكنز = صح

إدراج قيمة متغير في النص

الأقواس دون نقطتين تطبع قيمة المتغير:

لديك {نقاط} نقطة.
اسمك {اسم_البطل}.

مهم: النقطتان : تفرقان بين الإدراج والشرط. {س} إدراج، {س:} شرط.

الشروط

شرط بسيط

{وجد_المفتاح: المفتاح في جيبك.}

إذا كان المتغير صح (أو قيمته لا تساوي صفرًا)، فيظهر النص.

شرط بمقارنة

{نقاط > ٥: أحسنت! لقد جمعت نقاطًا كثيرة.}

عمليات المقارنة: ==, != (أو ≠), <, >, <= (أو ≤), >= (أو ≥)

شرط متعدد الفروع

{الشجاعة:
  - الشجاعة < ٣: ترتجف من الخوف.
  - الشجاعة < ٧: تتردد قليلًا.
  - غير_ذلك: تتقدم بثبات.
}

غير_ذلك هي الفرع الافتراضي. يمكن استخدام ELSE كبديل إنجليزي.

نفي

{لا وجد_المفتاح: ليس معك مفتاح.}

الأسماء الإنجليزية: not

روابط منطقية

{نقاط > ٠ و نقاط < ١٠: في منتصف الطريق.}
{س > ٥ أو ص < ٣: الشرط متحقق.}

الأسماء الإنجليزية: and, or

القوائم

لتتبع حالات متعددة (مثل العتاد):

قائمة حالة_الباب = (مغلق)، مفتوح، مكسور
قائمة المخزون = (لا_شيء)، مفتاح، مصباح

القيمة الأولى بين قوسين ( ) هي القيمة الابتدائية.

الأسماء الإنجليزية: LIST

استخدام القوائم:

قائمة حالة_الباب = (مغلق)، مفتوح، مكسور

=== الغرفة ===

~ حالة_الباب = مفتوح

{حالة_الباب == مفتوح: الباب مفتوح.}

الأنفاق

مقطع يُستدعى ثم يعود تلقائيًا:

-> وصف_الغرفة ->

=== وصف_الغرفة ===
الغرفة واسعة. السقف مرتفع.
->->

الاستدعاء: -> اسم_النفق -> (السهم مزدوج) العودة: ->-> داخل النفق

الخيوط

دمج محتوى من مقاطع متعددة في مقطع واحد:

=== السوق ===

الأصوات تملأ المكان.

<- بائع_الفاكهة
<- بائع_التوابل

=== بائع_الفاكهة ===

كومة رمّان أمام رجل عجوز.

=== بائع_التوابل ===

أكياس مفتوحة، كل واحدة بلون.

العلامة <- تسحب محتوى مقطع آخر إلى هذا الموضع.

حدّ معروف — اقرأه قبل أن تستعمل الخيوط. الدمج يتوقّف عند أوّل مقطع مسحوب فيه خيارات. كل ما بعده يختفي في صمت: بقيّة أسطر <-، ونصّ المقطع المضيف نفسه إن كان مكتوبًا بعدها.

في المثال أعلاه، إذا كان في بائع_الفاكهة خيار واحد، فالقارئ يرى نصّ السوق ثم نصّ بائع الفاكهة وخياره — ولا يرى بائع_التوابل إطلاقًا. وإذا كان في المقطعين المسحوبين خيارات معًا، فخيارات الثاني لا تظهر ولا يمكن الوصول إليها، لأن ترقيم الخيارات يبدأ من جديد في كل مقطع فيتصادم الرقمان.

الاستعمال الآمن اليوم: اسحب مقاطع نصّية فقط، واكتب خيارات المقطع المضيف فيه مباشرة. مقاطع النصّ تُدمج واحدًا بعد الآخر بلا مشكلة.

الحساب في الإسناد

الحساب مدعوم في صورة واحدة فقط: زيادة المتغيّر على نفسه. تكتب اسم المتغيّر، ثم =، ثم الاسم نفسه، ثم العملية، ثم قيمة صريحة:

~ نقاط = نقاط + ٥
~ نقاط = نقاط - ٣
~ نقاط = نقاط * ٢
~ نقاط = نقاط / ٢
~ نقاط = نقاط % ٣

العمليات: +, -, *, /, %

الطرف الأيمن لا بد أن يكون قيمة صريحة — رقمًا أو نصًّا بين علامتَي اقتباس أو صح/خطأ أو قيمة من قائمة معلنة. لا يمكن أن يكون متغيّرًا آخر.

هذه الأشكال غير مدعومة وكلٌّ منها يعطي الخطأ E201:

لجمع متغيّرين، اجعل الحساب على خطوتين:

متغير س = ٣
متغير المجموع = ٠

=== الحساب ===

~ المجموع = المجموع + ٣
النتيجة {المجموع}.

لا توجد دوال مدمجة في اللغة، ولا أي استدعاء دالة من أي نوع. لا يوجد في اللغة ما يعطيك رقمًا بالصدفة، ولا ما يخبرك إن كان القارئ قد مرّ بمقطع من قبل أو كم مرّة، ولا ما يحسب عدد حروف نصّ. المُصرّف لا يعرف الأقواس المستديرة في الإسناد ويرفضها بالخطأ E201.

الصور

الصورة تُعلَن مرّة في أعلى الملف، ثم تُستعمل في أي مقطع — أو في عدّة مقاطع. تُخزَّن مرّة واحدة مهما تكرّر استعمالها.

أسلوب_الصور: "رسم كتب أطفال، ألوان ترابية"
أوصاف_الشخصيات: "سليم: صبيّ في العاشرة، شعر أسود قصير، قميص أزرق"
صورة بوابة_المدينة = "بوابة حجرية عند غروب الشمس"

=== البداية ===

صورة: بوابة_المدينة

وقفت أمام البوابة.

علامات الترقيم مختلفة بين الثلاثة، وهذا أكثر ما يُخطئ فيه الكاتب:

الأسماء الإنجليزية: image للتصريح والاستعمال، image_style للأسلوب، characters لأوصاف الشخصيات.

التصريح

اسم الصورة يتبع قواعد أسماء المتغيرات (يُنزع التشكيل). النصّ بين علامتَي الاقتباس هو الوصف العربي: هو ما يُرسَل ليُرسَم، وهو نصّ alt للقارئ الذي يستعمل قارئ شاشة، وهو ما يظهر داخل إطار مكان الصورة إن لم تُولَّد بعد.

التصريح وحده لا يرسم شيئًا. التوليد فعل صريح تضغطه في المحرر: في المحرّر المرئي سطر صورة المقطع في أعلى كلّ بطاقة، وفيه زرّ ارسم الصورة، وبجانب حقل الوصف زرّ ✨ اقترح من النصّ يقرأ نصّ المقطع ويكتب لك الوصف.

صورة مُعلَنة ولم تُستعمل ليست خطأ. وصورة مُعلَنة ولم تُولَّد ليست خطأ أيضًا — تُصدَّر كإطار يحمل وصفها العربي، فالقصة تظلّ تُقرأ وتُلعب.

الاستعمال داخل المقطع

صورة: الاسم على سطر مستقل تضع الصورة في ذلك الموضع بالضبط. ترتيبها بين النصّ والخيارات هو ترتيب كتابتها — ليست ترويسة للمقطع ولا خاصيّة له.

الأسلوب

أسلوب_الصور اختياري، وواحد للقصة كلها. اكتبه إن أردت أن تتشابه صور القصة.

لماذا يوجد أصلًا: قبل أن يصل الوصف إلى نموذج الرسم، يترجمه المحرّر إلى الإنجليزية، ويترجم أسلوبك معه، ثمّ يُلحقه به. لولا هذا السطر لاخترع النموذج أسلوبًا مختلفًا لكلّ صورة، فتخرج عشر صور كأنّ عشرة رسّامين رسموها.

والترجمة هنا ليست تزيّدًا: نموذج الرسم لا يقرأ العربية، فأسلوب مكتوب بالعربية يصل إليه ولا يفهمه، فيتجاهله في صمت. قيس هذا على النموذج نفسه بالموضوع نفسه: مع الأسلوب بالعربية خرجت صورة فوتوغرافية، ومع الأسلوب نفسه بالإنجليزية خرج رسم كتب أطفال.

ولهذا: اكتب في الوصف الموضوع فقط — من في الصورة، وأين، ومتى. اترك الإضاءة والمزاج والألوان والتكوين لسطر أسلوب_الصور.

أوصاف الشخصيات

أوصاف_الشخصيات سطر لكلّ شخصية: الاسم، ثمّ نقطتان، ثمّ وصف هيئته. يتكرّر السطر بعدد الشخصيات.

أوصاف_الشخصيات: "سليم: صبيّ في العاشرة، شعر أسود قصير، قميص أزرق"
أوصاف_الشخصيات: "جدّته: امرأة في السبعين، ثوب مطرّز أخضر"

لماذا يوجد: كلّ صورة تُرسم من وصفها وحده، والمحرّر لا يعرف من سليم. فإن قال المقطع "وقف سليمٌ في الفناء" ولم يذكر عمره، اختار النموذج عمرًا من عنده — وقد اختار شيخًا في السبعين لصبيّ في العاشرة. هذه السطور تصف الشخصية مرّة واحدة، فتصل إلى كلّ صورة تظهر فيها.

الاسم قبل النقطتين هو المفتاح. المحرّر يقرأ الاسم، ثمّ يُلحق وصف الشخصية بالصورة إن ورد اسمها في وصفها. فلا تدخل الجدّة مشهدًا ليست فيه.

ووصف الشخصية يعبر الجسر مترجمًا مثل الأسلوب، للسبب نفسه: نموذج الرسم لا يقرأ العربية.

اكتب الهيئة وحدها — العمر والبنية والشعر واللباس. أمّا الطبع والمشاعر فلا يرسمهما النموذج.

نموذج الرسم لا يكتب العربية

نماذج توليد الصور لا تُحسن رسم الحرف العربي؛ ما تكتبه يخرج خربشة تشبه الحروف ولا تُقرأ. صِف المشهد، ولا تطلب لافتة ولا كتابًا مفتوحًا ولا نقشًا فيه كلام. إن احتجت كلامًا مكتوبًا في المشهد، فاكتبه نصًّا في المقطع لا داخل الصورة.

اختيار نموذج الرسم

يرسم المحرّر بنموذج واحد افتراضيًّا، ولك أن تختار غيره من ⚙️ الإعدادات ← نموذج الرسم. النموذج الافتراضي أسرعها، وما بعده أبطأ وأدقّ تفصيلًا.

ومتى تحتاج إلى هذا؟ المزوّدون يسحبون نماذجهم من الخدمة بلا إنذار. فإن جاءتك رسالة خطأ عند توليد صورة تقول إنّ النموذج غير متاح، فاختر نموذجًا آخر من القائمة نفسها — العطل عند المزوّد لا في المحرّر.

واختيارك محفوظ لكلّ مزوّد على حدة، في متصفّحك وحده.

أخطاء الصور

E106 اسم صورة غير مُعلَن · E107 اسم صورة مكرّر · E108 تصريح صورة بلا وصف بين علامتَي اقتباس. التفاصيل في دليل الأخطاء.

الكلمات المفتاحية — عربي وإنجليزي

ملاحظات مهمة

• التشكيل في أسماء المتغيرات: كَلْب و كلب يعاملان معاملة واحدة. يُنزع التشكيل تلقائيًا في أسماء المتغيرات والمقاطع. النص العادي يحتفظ بالتشكيل.
• الأرقام: تقبل العربية (٠١٢٣) والغربية (0123).
• المسافات: المسافة بعد ] في الخيارات فاصلة وليست جزءًا من النص. المسافات حول { } في النص محفوظة.
• الترميز: الملفات بصيغة UTF-8.