دوال Luau: المعاملات وreturn وفحص النتائج

حدّد السؤال قبل كتابة الدالة #

تخيّل مساراً تعليمياً من عشر محطات. نعرف العدد الكلي وعدد المحطات التي زُورت، ونريد معرفة المتبقي. تجيب الدالة عن سؤال حسابي فقط: طرح visited من total. لا تحرّك شخصية ولا تقرأ تقدماً محفوظاً ولا تؤكد زيارة اللاعب لمحطات حقيقية.

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

عرّف الدالة ثم استدعها #

يعرّف المثال الأول local function remainingStops(total, visited). يقع جسم الدالة بين التعريف وend، وتعيد return الفرق المحسوب إلى الشيفرة المستدعية. التعريف وحده لا ينفّذ الحساب. يبدأ التنفيذ عند استدعاء remainingStops(10, 3) بالقيمتين داخل القوسين.

يحفظ استدعاءان نتيجتين في متغيرين منفصلين. عشر محطات مع ثلاث زيارات تعطي 7، ومع ست زيارات تعطي 4. تعرض print بعد ذلك القيم المحفوظة. شغّل الكتلة كاملة في Script تعليمي منفصل وقارن سطري Output بالتوقع. نُفّذت الأمثلة الأصلية أيضاً بمفسّر Luau مستقل؛ وهذا يختبر اللغة والحساب، لا مساراً فعلياً قابلاً للعب داخل Studio.

افتح الصورة بالحجم الكامل ↗

local function remainingStops(total, visited)
    return total - visited
end
local firstRemaining = remainingStops(10, 3)
local secondRemaining = remainingStops(10, 6)
print(firstRemaining)
print(secondRemaining)

ميّز أسماء المعاملات عن قيم الاستدعاء #

total وvisited اسمان للمعاملات داخل الدالة، بينما 10 و3 قيم يمرّرها استدعاء محدد. يمكن لاستدعاء لاحق إعطاء قيم مختلفة للمعاملات نفسها. يجوز أن يسمى المتغير الخارجي routeLength؛ المهم أن تتوافق قيمته مع المعنى المتفق عليه للمعامل total.

الترتيب مهم: remainingStops(10, 3) يختلف عن remainingStops(3, 10). لا تتحقق الدالة البسيطة الأولى من المعنى، لذلك ينتج الاستدعاء الثاني عدداً سالباً. تغيير نص الرسالة لا يصلح المدخل. قارن ترتيب القيم ومعناها بالقواعد أولاً، ثم أضف التحقق من الصلاحية.

راقب print من دون return #

تطبع showRemaining في المثال الثاني الفرق داخل جسمها. عند استدعائها بالقيمتين 10 و3 يظهر العدد 7 فعلاً في Output. لكنها لا تعيد قيمة صراحةً، ولذلك يحصل المتغير result لدى المستدعي على nil. تعرض print(result) بعد ذلك nil بدلاً من سبعة أخرى.

ظهور رسالة صحيحة لا يثبت أن المستدعي تلقّى العدد المطلوب. إذا احتاجت الشيفرة التالية إلى النتيجة، فعلى الدالة إعادتها. أبقِ استدعاءي print في التمرين وراقب العدد من جسم الدالة ثم nil من المستدعي. وضع سبعة ثابتة يخفي المشكلة ولا يعمل عندما تتغير المدخلات.

افتح الصورة بالحجم الكامل ↗

local function showRemaining(total, visited)
    print(total - visited)
end
local result = showRemaining(10, 3)
print(result)

احفظ النتيجة حيث تحتاجها #

يحمل firstRemaining وsecondRemaining في المثال الأول عددين أعادتهما الدالة. يستطيع المستدعي مقارنتهما بالتوقع أو تمريرهما أو عرضهما. يصبح الحساب والعرض خطوتين منفصلتين. يكفي متغير محلي وفحص النتيجة لفهم return، ولا تحتاج إلى بناء واجهة لهذا التمرين.

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

افحص المدخلات قبل الطرح #

تتحقق checkedRemaining أولاً من الأنواع. إذا غاب visited يصبح nil، وتعيد الدالة nil, false قبل الحساب. ترفض أيضاً النص "10" لأن المثال يقبل أعداداً ولا يحوّل الإدخال النصي. ثم تستبعد NaN واللانهاية الموجبة؛ وتفشل القيم السالبة واللانهاية السالبة في فحص عدم السلبية.

يستبعد فحص باقي القسمة على 1 الأعداد الكسرية، ويرفض الشرط الأخير visited عندما يتجاوز total. المدخل الصحيح وحده يصل إلى return total - visited, true. يوضح هذا الترتيب القواعد ويحمي الحساب التعليمي من مدخلات غير مناسبة، لكنه لا يثبت أن العدد المرسل من العميل يعبّر عن تقدم حقيقي للاعب.

local function checkedRemaining(total, visited)
    if type(total) ~= "number" or type(visited) ~= "number" then
        return nil, false
    end
    if total ~= total or visited ~= visited then
        return nil, false
    end
    if total == math.huge or visited == math.huge then
        return nil, false
    end
    if total < 0 or visited < 0 or total % 1 ~= 0 or visited % 1 ~= 0 then
        return nil, false
    end
    if visited > total then
        return nil, false
    end
    return total - visited, true
end
print(checkedRemaining(10, 3))
print(checkedRemaining(10))
print(checkedRemaining(10, 12))

افحص المدخل الغائب والتقدم الزائد #

تحتوي الكتلة على ثلاثة استدعاءات. تعرض checkedRemaining(10, 3) القيمتين 7 وtrue. تعرض checkedRemaining(10) القيمتين nil وfalse لغياب المعامل الثاني. وتعطي checkedRemaining(10, 12) أيضاً nil وfalse لأن اثنتي عشرة زيارة لا تتوافق مع عشر محطات وفق القاعدة المختارة.

احفظ الزوج باستخدام local value, valid = checkedRemaining(total, visited). افحص valid == true قبل عرض العدد، وجهّز رسالة واضحة للبيانات غير الصحيحة عند false. تحويل nil تلقائياً إلى صفر يخفي الخطأ ويبدو كأن المسار اكتمل. أصلح المدخل في الموضع الذي يُنشأ فيه.

اعتبر الصفر نتيجة صحيحة #

تعيد checkedRemaining(10, 10) الزوج 0, true بعد زيارة المحطات العشر كلها. ويعيد المسار التعليمي الفارغ checkedRemaining(0, 0) الزوج نفسه. كلاهما حساب صحيح. نستخدم nil, false للمدخل المرفوض وغياب النتيجة، وهو معنى مختلف عن العدد صفر.

الصفر قيمة صادقة في شروط Luau، لكن الفحص الصريح valid == true يوضح اتفاق هذه الدالة بصورة أفضل. استخدام value > 0 وحده يستبعد الصفر الصحيح. يجب تصميم سلوك إكمال المسار الحقيقي بعد فحص الصلاحية، ضمن نظام لعبة يستخدم هذا النموذج فعلاً.

اختبر الحدود لا الاستدعاء الناجح فقط #

أنشئ جدولاً: 10 و3 تعطيان 7، و10 و0 تعطيان 10، و10 و10 تعطيان 0، و0 و0 تعطيان 0. توقع true في كل حالة. افصل المدخلات غير الصحيحة: معامل غائب، نص، عدد سالب، كسر، وvisited أكبر من total. توقع nil وfalse لهذه الحالات.

نُفّذت الحالات في ملف الفحص بواسطة assert، مع فحص إضافي لـNaN واللانهاية. اكتب التوقع قبل التشغيل ثم قارن الزوج الفعلي. عند الاختلاف سجّل المدخل المحدد والقيمتين المرصودتين. الحساب الصحيح لا يختبر حفظ التقدم أو الثقة بالعميل أو منح المكافآت.

سلّم اتفاق الدالة مع الشيفرة #

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

لا يحتوي التمرين على كائنات Roblox أو أحداث أو اتصال شبكي أو تخزين دائم، ولذلك ليس نظام تقدم مكتملًا. فائدته فهم الفرق بين رسالة Output والنتيجة المتاحة للمستدعي والتحقق منه بمدخلات واضحة. يمكن توسيع المهمة التالية مع الحفاظ على الاتفاق المفحوص.