إذا قرأت مقال محركات الألعاب ثم نزلت Godot وفتحته لأول مرة، فغالب الظن أنك وقفت أمام شاشة فارغة فيها لوحة على اليسار مكتوب فيها Scene، وأزرار تقول 2D Scene وUser Interface وOther Node، ولم تعرف من أين تبدأ. والسبب أن Godot لا يبدأ من الكود كما اعتدت في أي مشروع آخر، وإنما يبدأ من فكرتين: العقدة Node والمشهد Scene، وكل شيء بعدهما، من الحركة إلى النقاط إلى نهاية اللعبة، مبني فوقهما. فإذا فهمت هاتين الفكرتين وكيف تتكلم العقد مع بعضها، أصبح المحرر واضحاً، وأصبحت أي لعبة ثنائية الأبعاد مسألة وقت وصبر.
وفي هذا المقال لن نشرح كل زر في المحرر، وإنما سوف نبني لعبة صغيرة كاملة من البداية إلى شاشة النهاية، ونشرح كل فكرة في اللحظة التي نحتاجها فيها. واللعبة من تصميمنا، اسمها «حصاد التمر»: سلة تحت نخلة، يسقط عليها التمر فتلتقطه، وتسقط معه حجارة يجب أن تتجنبها، ولك ثلاث محاولات. وهي لعبة بسيطة عن قصد، ثلاثة مشاهد وأربعة سكربتات قصيرة، والسبب أن أول لعبة تبنيها هدفها أن تنتهي، وليس أن تبهر أحداً.
وسوف نتناول في هذا المقال ما يلي:
- فكرة اللعبة وقواعدها، ولماذا نبدأ بلعبة صغيرة.
- العقدة Node: الوحدة الصغيرة التي يتكون منها كل شيء.
- المشهد Scene: شجرة من العقد في ملف، والنسخ Instancing.
- لغة GDScript: ما تحتاجه منها لأول لعبة.
- متى يستدعي Godot دوالك:
_readyو_processو_physics_process. - التحكم بالأفعال Input Map بدل المفاتيح.
- الإشارات Signals: كيف تخبر العقدة غيرها بما حدث.
- مختبر يشغل اللعبة دون شاشة ويلعبها فيه روبوت، ثم يلتقط صوراً حقيقية منها.
- الأخطاء التي تتكرر في أول لعبة، وكيف تقرأ أعراضها.
اللعبة: حصاد التمر
قبل أن نفتح المحرر نكتب القواعد في سطور، لأن كل سطر منها سوف يصبح عقدة أو دالة بعد قليل:
- السلة: في أسفل الشاشة، يحركها اللاعب يميناً ويساراً بالأسهم أو بالحرفين A وD، ولا تخرج من حدود الشاشة.
- ما يسقط: كل 0.9 ثانية يسقط شيء من أعلى الشاشة في مكان عشوائي، تمرة في ثلاث مرات من أربع، وحجر في المرة الرابعة تقريباً.
- النقاط: كل تمرة في السلة نقطة، ومع كل نقطة يصبح السقوط أسرع قليلاً.
- المحاولات: ثلاث، تخسر واحدة إذا وقعت تمرة على الأرض أو إذا دخل حجر السلة، وعند الصفر تنتهي اللعبة وتظهر رسالة GAME OVER.
والصورة التالية من اللعبة نفسها وهي تعمل، بعد خمس ثوان من بدايتها، وقد التقطها المحرك بنفسه في المختبر كما سيأتي:

لاحظ أن الرسوم كلها أشكال بسيطة: مضلعات ملونة للنخلة والسلة والتمر، دون صور أو رسومات من أي مصدر. وهذا اختيار مقصود في أول لعبة، فالرسوم يمكن أن تستبدل لاحقاً دون أن يتغير سطر واحد من الكود، كما سترى عندما نفصل شكل العقدة عن سلوكها. ولاحظ أيضاً أن النص في الواجهة باللغة الإنجليزية، والسبب أن النص العربي في الألعاب له تفاصيله من الخطوط واتجاه الكتابة، وله مقال مستقل في هذه المرحلة.
وقد يتساءل البعض: لماذا لا نبدأ بلعبة أكبر، مثل لعبة منصات Platformer فيها قفز ومراحل؟ والإجابة على ذلك أن أكثر ما يوقف المبتدئ في تطوير الألعاب ليس صعوبة الكود، وإنما حجم الفكرة: يبدأ بلعبة فيها عشر مراحل وقصة وشخصيات، ثم يتوقف في الأسبوع الثالث عند مشكلة في القفز، ولا يرى لعبته منتهية أبداً. أما اللعبة الصغيرة المنتهية فتعلمك الدورة الكاملة، من الفكرة إلى شاشة النهاية، ثم تكبرها خطوة خطوة.
العقدة Node: الوحدة الصغيرة
العقدة Node في Godot هي أصغر وحدة في اللعبة، وكل عقدة لها نوع يحدد ما تعرف أن تفعله، ولها خصائص تعدلها، ويمكن أن يكون لها أبناء من العقد. ويصفها توثيق Godot للعقد والمشاهد بأنها لبنات البناء الأساسية للعبة. وأقرب تشبيه لها في عالمك كمطور هو عناصر صفحة الويب: كما أن الصفحة شجرة من العناصر، div فيها صورة وفقرة وزر، ولكل عنصر خصائصه، فاللعبة في Godot شجرة من العقد، ولكل عقدة نوعها وخصائصها.
والفرق المهم أن نوع العقدة في Godot يعطيها سلوكاً جاهزاً، فلا تكتبه بنفسك. وهذه الأنواع التي استخدمناها في اللعبة كلها:
- Node2D: عقدة لها موضع ودوران وحجم في عالم ثنائي الأبعاد، ولا ترسم شيئاً بنفسها، ونستخدمها لتجميع غيرها، مثل النخلة التي تجمع الجذع والسعف.
- Polygon2D وLine2D: ترسم مضلعاً ملوناً أو خطاً، ومنها بنينا النخلة والسلة والتمر والحجر.
- ColorRect: مستطيل بلون واحد، ومنه الخلفية والأرض.
- Area2D: منطقة في العالم تعرف متى دخلها جسم آخر أو خرج منها، كما يقول توثيق Area2D، وهي قلب اللعبة: السلة منطقة، وكل تمرة منطقة، وعندما تتداخل المنطقتان نعرف أن التمرة دخلت السلة.
- CollisionShape2D: تعطي المنطقة شكلها، مستطيلاً للسلة ودائرة للتمرة، والمنطقة دون شكل لا تكشف شيئاً.
- Timer: مؤقت يرسل إشارة كل فترة، ومنه يأتي إيقاع السقوط.
- CanvasLayer وLabel: طبقة للواجهة لا تتحرك مع العالم، وفيها النصوص: النقاط والمحاولات ورسالة النهاية.
ولاحظ هنا فصل الشكل عن السلوك: السلة عقدة Area2D، والشكل الذي تراه هو عقدة Polygon2D تحتها، والشكل الذي يستخدمه المحرك في التصادم هو CollisionShape2D تحتها أيضاً. فإذا أردت غداً أن تستبدل المضلع البني بصورة سلة مرسومة، تحذف Polygon2D وتضع مكانها Sprite2D، ويبقى كل شيء آخر كما هو.
وقد يتساءل البعض: لماذا Area2D وليس CharacterBody2D أو RigidBody2D التي يسمع عنها في كل درس؟ والإجابة على ذلك أن هذه الأنواع أجسام فيزيائية يدفع بعضها بعضاً ويرتد عنه، ولعبتنا لا تحتاج شيئاً من ذلك: التمرة لا ترتد عن السلة ولا تدفعها، وإنما يكفينا أن نعرف أنها دخلتها. فاختر دائماً أبسط عقدة تؤدي المطلوب، وسوف نعود إلى الأجسام الفيزيائية في مقال الفيزياء والتصادم في هذه المرحلة.
المشهد Scene: شجرة من العقد في ملف
المشهد Scene هو شجرة من العقد تحفظها في ملف بالامتداد .tscn، وله دائماً عقدة رئيسية واحدة Root Node في أعلى الشجرة. واللعبة في Godot، بحسب التوثيق، شجرة من المشاهد، وكل مشهد شجرة من العقد. والسؤال الذي يطرحه كل مبتدئ هنا: متى أجعل الشيء مشهداً مستقلاً، ومتى أضعه عقدة داخل مشهد آخر؟ والقاعدة العملية بسيطة: إذا كان الشيء يتكرر، أو له سلوك خاص به تريد أن تختبره وحده، فاجعله مشهداً مستقلاً.
وبهذه القاعدة قسمنا اللعبة إلى ثلاثة مشاهد، والشكل التالي يبينها:

في الشكل أعلاه لاحظ التالي:
- مشهد السلة player.tscn: لها سلوك خاص بها، الحركة والتقاط ما يدخلها، فجعلناها مشهداً مستقلاً، ثم وضعنا منه نسخة واحدة في المشهد الرئيسي.
- مشهد ما يسقط falling.tscn: يتكرر عشرات المرات في اللعبة، فهو المثال الأوضح على المشهد المستقل: نصممه مرة واحدة، ثم ينشئ منه المشهد الرئيسي نسخة جديدة كل 0.9 ثانية.
- المشهد الرئيسي main.tscn: فيه العالم الثابت، الخلفية والنخلة والأرض والواجهة، وفيه قواعد اللعبة في السكربت
main.gd.
والنسخة Instance هنا تشبه الكائن Object الذي تنشئه من الكلاس Class في أي لغة برمجة: المشهد هو التعريف، وكل نسخة منه تبدأ بالبنية نفسها والخصائص نفسها، ثم تعيش حياتها مستقلة، فكل تمرة لها موضعها وسرعتها، وإذا حذفت واحدة بقيت البقية. وإذا عدلت المشهد الأصلي، فغيرت لون التمرة مثلاً، تغيرت كل النسخ في المرة القادمة التي تنشئها، وهذا ما يشرحه توثيق النسخ Instancing.
كيف يبدو المشهد من الداخل؟
المحرر يحفظ المشهد في ملف نصي تستطيع أن تقرأه وتراجعه في Git، وهذا مشهد السلة كما هو في المختبر:
[gd_scene load_steps=3 format=3]
[ext_resource type="Script" path="res://player.gd" id="1"]
[sub_resource type="RectangleShape2D" id="basket_shape"]
size = Vector2(84, 20)
[node name="Player" type="Area2D"]
script = ExtResource("1")
[node name="Basket" type="Polygon2D" parent="."]
color = Color(0.72, 0.47, 0.2, 1)
polygon = PackedVector2Array(-42, -12, 42, -12, 32, 14, -32, 14)
[node name="Rim" type="Line2D" parent="."]
points = PackedVector2Array(-44, -12, 44, -12)
width = 4.0
default_color = Color(0.45, 0.28, 0.1, 1)
[node name="Shape" type="CollisionShape2D" parent="."]
shape = SubResource("basket_shape")في الملف أعلاه لاحظ التالي:
- السطر
ext_resourceيربط المشهد بالسكربتplayer.gd، والسطرsub_resourceيعرف شكل التصادم، مستطيلاً بعرض 84 بكسل وارتفاع 20. - كل قسم
[node]عقدة، والخاصيةparent="."تعني أنها ابن للعقدة الرئيسية، فالشجرة كلها مكتوبة في هذه الأسطر. - القيم التي تراها هي القيم التي غيرناها فقط، وكل خاصية لم تكتب هنا تأخذ قيمتها الافتراضية.
وفي العمل اليومي لن تكتب هذا الملف بيدك، وإنما تبنيه في المحرر بالسحب والإفلات وتعدل الخصائص من لوحة Inspector. ولكن معرفة شكله تفيدك في مراجعة التغييرات في Git، وفي فهم ما يحدث عندما يشتكي المحرر من ملف تالف بعد دمج فرعين.
لغة GDScript: ما تحتاجه منها لأول لعبة
GDScript هي لغة Godot الأساسية، ويصفها توثيق GDScript بأنها لغة عالية المستوى كائنية التوجه، بأنواع اختيارية Gradually Typed، وبصياغة تعتمد على المسافات البادئة Indentation تشبه Python. وإذا كنت تكتب Python أو JavaScript فسوف تقرأ أغلبها من النظرة الأولى. ويدعم Godot أيضاً لغة C# في نسخة .NET منه، ولكن الدروس والأمثلة في التوثيق والمجتمع أغلبها بلغة GDScript، فابدأ بها.
وكل سكربت في Godot يرتبط بعقدة، ويبدأ بالكلمة extends ونوع العقدة، فيصبح السكربت امتداداً لها: يرث خصائصها ودوالها ويضيف عليها. وهذا سكربت السلة كاملاً:
extends Area2D
## The basket. It moves left and right, and tells whoever listens what fell into it.
signal caught(item: Area2D)
@export var speed := 420.0 # pixels per second, editable in the Inspector
const WORLD_WIDTH := 720.0 # the same size as project.godot, not the window
var half_width := 42.0
func _ready() -> void:
area_entered.connect(_on_area_entered)
func _physics_process(delta: float) -> void:
var dir := Input.get_axis("move_left", "move_right") # -1, 0 or 1 (or between, on a stick)
position.x += dir * speed * delta
position.x = clamp(position.x, half_width, WORLD_WIDTH - half_width)
func _on_area_entered(area: Area2D) -> void:
caught.emit(area)في السكربت أعلاه لاحظ التالي:
- السطر
extends Area2D: السكربت امتداد لعقدة Area2D، فكل ما تعرفه المنطقة من كشف التداخل وإشاراتها أصبح متاحاً هنا دون كتابة. - السطر
signal caught(item: Area2D): يعرف إشارة جديدة خاصة بالسلة، وسوف نشرح الإشارات بعد قليل. - التعليق
@export: يجعل المتغيرspeedخاصية تظهر في لوحة Inspector، فيغير مصمم اللعبة سرعة السلة من المحرر دون أن يفتح الكود. - الصيغة
:=: تعرف المتغير ويستنتج المحرك نوعه من القيمة، فالمتغيرspeedمن نوع float لأن قيمته 420.0. وبعدها إذا حاولت أن تضع فيه نصاً سوف يرفض المحرك، وهذا يكشف لك أخطاء كثيرة قبل التشغيل. - الثابت
WORLD_WIDTH: عرض عالم اللعبة، 720 بكسل، وسوف نعرف في المختبر لماذا كتبناه ثابتاً بدل أن نسأل النافذة عن عرضها. - الدالة
Input.get_axis: تعطي -1 إذا ضغط اللاعب move_left، و1 إذا ضغط move_right، وصفراً إذا لم يضغط أو ضغط الاثنين، وقيمة بينهما مع عصا يد التحكم. - الدالة
clamp: تمنع السلة من الخروج من حدود العالم، فلا يقل موضعها عن نصف عرضها ولا يزيد عن العرض ناقص نصف عرضها.
وكلمة أخيرة عن الأنواع: GDScript لا يجبرك على كتابة النوع، ولكن كتابته في الدوال، مثل delta: float و-> void، تجعل المحرر يكمل لك الكود ويكشف الأخطاء وأنت تكتب، فاكتبه من أول يوم، والسبب أن إضافته لاحقاً على مشروع كبير أصعب بكثير من كتابته مع الكود.
متى يستدعي Godot دوالك؟
في السكربت أعلاه لم نستدع الدالة _physics_process في أي مكان، ومع ذلك تتحرك السلة. والسبب أن الدوال التي تبدأ بشرطة سفلية في Godot دوال افتراضية Virtual يستدعيها المحرك بنفسه في وقت محدد، وأنت تكتب ما يحدث فيها فقط. وهذه الدوال الثلاث هي ما تحتاجه في كل لعبة تقريباً، والشكل التالي يبين متى يستدعى كل منها:

- الدالة
_ready(): تستدعى مرة واحدة عندما تدخل العقدة وأبناؤها شجرة المشهد، وبحسب توثيق Node تستدعى للأبناء أولاً ثم للأب. ولذلك نضع فيها التهيئة، مثل ربط الإشارات وتشغيل المؤقت، ونحن مطمئنون أن الأبناء جاهزون. - الدالة
_physics_process(delta): تستدعى مع كل خطوة فيزياء، ستين مرة في الثانية افتراضياً، وdeltaفيها ثابت هو 1/60 ثانية. وفيها نضع الحركة وكل ما يجب أن يكون متطابقاً على كل جهاز. - الدالة
_process(delta): تستدعى مرة مع كل إطار يرسم، وdeltaفيها هو الزمن الحقيقي منذ الإطار السابق، فيتغير بسرعة الجهاز. وفيها نضع ما يتعلق بالعرض فقط، مثل حركة جمالية في الواجهة.
وقد شرحنا في مقال حلقة اللعبة Game Loop لماذا يفصل المحرك بين الساعتين، ولماذا تخترق الكرة السريعة الجدار على الجهاز البطيء إذا تحركت مع الإطار. وهنا يكفي أن تتذكر قاعدة واحدة: كل ما يؤثر في نتيجة اللعبة، الحركة والتصادم والنقاط، يكون في _physics_process أو يضرب في delta، والسبب أن اللعبة يجب أن تكون هي نفسها على جوال بطيء وحاسوب سريع. ولهذا تجد في سكربت السلة أن الحركة هي السرعة في الثانية مضروبة في delta، وليست عدداً ثابتاً من البكسلات في كل استدعاء، وتفاصيل هذه الحسبة في مقال رياضيات الألعاب.
التحكم بالأفعال Input Map بدل المفاتيح
في سكربت السلة لم نكتب «إذا ضغط اللاعب السهم الأيسر»، وإنما سألنا عن الفعلين move_left وmove_right. والفعل Action في Godot اسم تعرفه أنت، ثم تربطه في إعدادات المشروع بالمفاتيح والأزرار التي تعنيه، وهذا ما يسميه المحرر خريطة التحكم Input Map، وتجده في Project Settings ثم التبويب Input Map. وهذا ملف المشروع كاملاً، وفيه الفعلان:
; «حصاد التمر»: a small original 2D game for the article «أول لعبة مع Godot».
; A basket under a palm tree catches falling dates and avoids falling stones.
config_version=5
[application]
config/name="date-harvest"
run/main_scene="res://main.tscn"
config/features=PackedStringArray("4.7", "GL Compatibility")
[display]
window/size/viewport_width=720
window/size/viewport_height=480
window/stretch/mode="canvas_items"
[input]
; Actions, not keys: the code asks «move_left?», and here we say which keys mean it.
move_left={
"deadzone": 0.2,
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194319,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":65,"key_label":0,"unicode":97,"location":0,"echo":false,"script":null)
]
}
move_right={
"deadzone": 0.2,
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194321,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":68,"key_label":0,"unicode":100,"location":0,"echo":false,"script":null)
]
}
[rendering]
renderer/rendering_method="gl_compatibility"
renderer/rendering_method.mobile="gl_compatibility"في الملف أعلاه لاحظ التالي:
- القسم
[input]: فيه الفعلان، وكل فعل مربوط بمفتاحين، السهم والحرف، والرقمphysical_keycodeهو رمز المفتاح الذي يكتبه المحرر عندما تضغطه في نافذة الإعداد، فلا تحتاج إلى حفظه. - المفتاح الفيزيائي Physical Key: ربطنا الحرف A بموضعه على لوحة المفاتيح، وليس بالحرف المكتوب عليه، فيبقى في المكان نفسه على لوحة مفاتيح عربية أو فرنسية.
- القسم
[display]: حجم عالم اللعبة 720 في 480 بكسل، والخيارstretch/mode="canvas_items"يجعل المحرك يكبر العالم كله أو يصغره إذا تغير حجم النافذة، كما يشرح توثيق دقة الشاشات المتعددة. - القسم
[rendering]: اخترنا نمط الرسم Compatibility، وهو الأخف والأوسع دعماً للأجهزة القديمة والويب، ولعبة ثنائية الأبعاد بأشكال بسيطة لا تحتاج أكثر منه.
والسبب في الأفعال أن كودك لا يتغير مهما تغيرت طريقة التحكم: إذا أضفت غداً يد تحكم أو أزراراً على شاشة الجوال، تربطها بالفعلين نفسيهما في خريطة التحكم، ويبقى سكربت السلة كما هو. وفي المختبر سوف ترى فائدة أخرى غير متوقعة: الروبوت الذي يلعب اللعبة يضغط الفعلين نفسيهما، فلا تعرف السلة إن كان من يحركها إنساناً أم كوداً.
الإشارات Signals: كيف تخبر العقدة غيرها بما حدث
الآن عندنا سلة تتحرك، وتمر تسقط، والسؤال: من يحسب النقطة عندما تدخل التمرة السلة؟ والحل البسيط الذي يكتبه أغلب المبتدئين أن تفتح السلة المشهد الرئيسي وتزيد النقاط فيه مباشرة، فيكون في سكربت السلة سطر مثل get_parent().score += 1. وهذا يعمل في اليوم الأول، ثم تكتشف أن السلة أصبحت تعرف قواعد اللعبة، فلا تستطيع أن تضعها في مشهد آخر ليس فيه متغير اسمه score، ولا أن تختبرها وحدها، وكل تغيير في القواعد يجبرك على تعديل السلة والتمرة والمؤقت معاً.
والحل الأنسب هو الإشارة Signal. ويصفها توثيق الإشارات بأنها آلية تفويض في Godot تسمح لكائن أن يستجيب لتغير في كائن آخر دون أن يعرف أحدهما الآخر، وهي التطبيق المعروف لنمط المراقب Observer Pattern: العقدة تعلن ما حدث لها، «دخلني شيء» أو «وصلت إلى الأرض»، ومن يهمه الأمر يربط دالة من دواله بهذه الإشارة. والشكل التالي يبين من يخبر من في لعبتنا:

في الشكل أعلاه لاحظ التالي:
- السلة والتمرة والمؤقت لا تعرف شيئاً عن النقاط أو المحاولات، وكل منها يعلن حدثاً يخصه فقط.
- المشهد الرئيسي هو الوحيد الذي يعرف القواعد، فيستمع للإشارات الثلاث ويقرر: نقطة أو خسارة محاولة أو نهاية اللعبة.
- الاتجاه المعاكس، من الأب إلى أبنائه، استدعاء مباشر عادي: المشهد الرئيسي يعرف أبناءه، فيحدث نصوص الواجهة وينشئ التمر بنفسه.
وهذه القاعدة يلخصها مطورو Godot في عبارة قصيرة: الاستدعاء ينزل والإشارة تصعد Call Down, Signal Up. أي أن الأب يستدعي دوال أبنائه مباشرة لأنه يعرفهم، والابن لا يستدعي أباه، وإنما يرسل إشارة، والسبب أن الابن يجب أن يعمل في أي مشهد تضعه فيه.
وفي الكود ترى الإشارة في ثلاثة مواضع: تعريفها بالكلمة signal كما في سكربت السلة، وإرسالها بالدالة emit، وربطها بالدالة connect. ففي سكربت السلة ربطنا الإشارة الجاهزة area_entered، التي ترسلها كل Area2D عندما تدخلها منطقة أخرى، بدالة صغيرة ترسل بدورها إشارتنا caught. وقد تسأل: لماذا لا يستمع المشهد الرئيسي إلى area_entered مباشرة؟ والسبب أن caught تصف ما يعني اللعبة، «التقطت السلة شيئاً»، فإذا غيرنا غداً طريقة الكشف، من منطقة إلى شعاع RayCast مثلاً، تبقى الإشارة كما هي ولا يتغير شيء في المشهد الرئيسي.
ويمكن ربط الإشارات من المحرر أيضاً، من التبويب Node بجانب Inspector، فتختار الإشارة والدالة بالفأرة. وقد ربطناها في الكود في هذا المقال لأن الربط في الكود يظهر لك وأنت تقرأ السكربت، ولأن نسخ التمر تنشأ في أثناء اللعب فلا يمكن ربطها من المحرر أصلاً.
مشهد ما يسقط
وهذا سكربت ما يسقط، تمرة أو حجراً، وهو مرتبط بالعقدة الرئيسية في المشهد falling.tscn:
extends Area2D
## One falling thing: a date (good) or a stone (bad). The same scene, instanced many times.
signal landed(item: Area2D) # reached the ground without being caught
const GROUND_Y := 452.0 # the game world has its own size; never ask the window
var kind := "date"
var fall_speed := 160.0
func _ready() -> void:
var body: Polygon2D = $Body
if kind == "date":
body.polygon = _oval(9, 13)
body.color = Color(0.48, 0.22, 0.08)
else:
body.polygon = _oval(13, 11)
body.color = Color(0.5, 0.52, 0.56)
func _physics_process(delta: float) -> void:
position.y += fall_speed * delta
if position.y > GROUND_Y:
landed.emit(self)
queue_free()
func _oval(rx: float, ry: float) -> PackedVector2Array:
var pts := PackedVector2Array()
for i in 16:
var a := TAU * i / 16.0
pts.append(Vector2(cos(a) * rx, sin(a) * ry))
return ptsفي السكربت أعلاه لاحظ التالي:
- المشهد واحد للتمرة والحجر، والفرق في المتغير
kind، وفي_readyنرسم الشكل واللون بحسبه. فالتمرة مضلع بيضاوي بني طولي، والحجر مضلع رمادي عريض. - في
_physics_processينزل الشيء بسرعته في الثانية مضروبة فيdelta، فإذا تجاوز خط الأرضGROUND_Yأرسل الإشارةlandedومعها نفسه، ثم حذف نفسه. - الدالة
queue_freeلا تحذف العقدة فوراً، وإنما بحسب التوثيق تضعها في قائمة الحذف في نهاية الإطار الحالي، والسبب أن الحذف الفوري في منتصف الإطار قد يترك عقداً أخرى تشير إلى عقدة لم تعد موجودة. ولذلك نتحقق في المشهد الرئيسي منis_queued_for_deletionقبل أن نحسب أي شيء. - الدالة
_ovalدالة عادية منا، ترجع نقاط المضلع حول دائرة، ولا يستدعيها المحرك، وإنما نستدعيها نحن.
المشهد الرئيسي: قواعد اللعبة
وأخيراً السكربت الذي يجمع كل شيء، وهو مرتبط بالعقدة Main:
extends Node2D
## The game rules: spawn, score, lives, game over. The nodes do the rest.
const FallingScene := preload("res://falling.tscn") # the scene we instance again and again
var score := 0
var lives := 3
var ticks := 0
var playing := true
var rng := RandomNumberGenerator.new()
var stats := {"date": 0, "stone": 0, "caught": 0, "dodged": 0, "missed": 0, "hit": 0}
@onready var player: Area2D = $Player
@onready var timer: Timer = $SpawnTimer
@onready var score_label: Label = $HUD/Score
@onready var lives_label: Label = $HUD/Lives
@onready var message: Label = $HUD/Message
func _ready() -> void:
rng.seed = 2026 # the same «random» game every run, so the lab output is repeatable
print("Godot ", Engine.get_version_info().string, " | display: ", DisplayServer.get_name())
print_tree_pretty()
player.caught.connect(_on_player_caught) # signal -> function, in code
timer.timeout.connect(_on_spawn_timer_timeout)
timer.start()
var args := OS.get_cmdline_user_args()
if "--autoplay" in args:
var bot := preload("res://bot.gd").new()
bot.name = "Bot"
add_child(bot)
func _physics_process(_delta: float) -> void:
ticks += 1
func _on_spawn_timer_timeout() -> void:
var item: Area2D = FallingScene.instantiate()
item.kind = "stone" if rng.randf() < 0.25 else "date"
item.position = Vector2(rng.randf_range(30, 690), 60)
item.fall_speed = 160.0 + score * 8.0 # harder as you score
item.landed.connect(_on_item_landed)
item.add_to_group("falling")
add_child(item)
stats[item.kind] += 1
log_event("spawn %-5s x=%3.0f speed=%3.0f (on screen: %d)" % [item.kind, item.position.x, item.fall_speed, get_tree().get_nodes_in_group("falling").size()])
func _on_player_caught(item: Area2D) -> void:
if not playing or item.is_queued_for_deletion():
return
if item.kind == "date":
score += 1
stats.caught += 1
log_event("CAUGHT date -> score %d" % score)
else:
stats.hit += 1
lose_life("stone hit the basket")
item.queue_free()
update_hud()
func _on_item_landed(item: Area2D) -> void:
if not playing:
return
if item.kind == "date":
stats.missed += 1
lose_life("date fell on the ground")
else:
stats.dodged += 1
func lose_life(why: String) -> void:
lives -= 1
log_event("LOST a life (%s) -> lives %d" % [why, lives])
update_hud()
if lives <= 0:
game_over()
func game_over() -> void:
playing = false
timer.stop()
message.visible = true
log_event("GAME OVER score=%d spawned dates=%d stones=%d caught=%d missed=%d stones hit=%d dodged=%d" % [score, stats.date, stats.stone, stats.caught, stats.missed, stats.hit, stats.dodged])
get_tree().call_group("falling", "set_physics_process", false) # freeze what is still falling
func update_hud() -> void:
score_label.text = "Score: %d" % score
lives_label.text = "Lives: %d" % lives
func log_event(text: String) -> void:
print("t=%5.2fs %s" % [ticks / 60.0, text])في السكربت أعلاه لاحظ التالي:
- السطر
preload: يحمل مشهد ما يسقط مرة واحدة عند تحميل السكربت، فيصبح الثابتFallingSceneقالباً جاهزاً ننشئ منه النسخ دون قراءة الملف من القرص في كل مرة. - التعليق
@onready: يؤخر تعيين المتغيراتplayerوtimerوالنصوص إلى لحظة_ready، والسبب أن الأبناء غير موجودين في الشجرة قبلها، والصيغة$Playerاختصار للدالةget_node("Player")، و$HUD/Scoreمسار إلى عقدة داخل عقدة. - الربط في
_ready: نربط إشارة السلة وإشارة المؤقت بدالتين من المشهد الرئيسي، ثم نشغل المؤقت. والدالةprint_tree_prettyتطبع شجرة المشهد كاملة، وسوف تراها في مخرج المختبر. - النسخ في
_on_spawn_timer_timeout: ننشئ نسخة بالدالةinstantiate، ونحدد نوعها وموضعها وسرعتها، ونربط إشارتهاlanded، ثم نضيفها إلى الشجرة بالدالةadd_child، ولا تظهر النسخة في اللعبة ولا تتحرك قبل هذه الخطوة. - المجموعات Groups: كل نسخة تدخل المجموعة
falling، فنعدها بالدالةget_nodes_in_group، وعند نهاية اللعبة نوقفها كلها بسطر واحد هوcall_groupدون أن نحفظ قائمة بها. - العشوائية المضبوطة: نعطي مولد الأرقام العشوائية بذرة ثابتة Seed هي 2026، فتخرج اللعبة نفسها في كل تشغيل، وهذا ما يجعل مخرج المختبر قابلاً للتكرار. وفي لعبة حقيقية تحذف هذا السطر أو تجعل البذرة من الوقت، فتختلف كل جولة.
- الوسيط
--autoplay: إذا شغلنا اللعبة بهذا الوسيط بعد--في سطر الأوامر، يضيف المشهد الرئيسي عقدة الروبوت التي تلعب بدل الإنسان، والدالةOS.get_cmdline_user_argsبحسب توثيق OS ترجع الوسائط التي تأتي بعد--فقط، ويتركها المحرك للعبة.
ولاحظ أن الدوال في المشهد الرئيسي قصيرة، وأن كل واحدة منها جواب على حدث واحد: مؤقت دق، أو سلة التقطت، أو شيء وصل إلى الأرض. وهذا هو الشكل الطبيعي لكود الألعاب في Godot، فلا توجد حلقة كبيرة تكتبها أنت، وإنما المحرك يدير الحلقة ويستدعي دوالك الصغيرة في الوقت المناسب.
المختبر: روبوت يلعب اللعبة
الآن نشغل اللعبة كاملة، ولكن ليس أمام شاشة، وإنما من سطر الأوامر داخل Container، ويلعبها روبوت صغير بدل الإنسان، فنرى في المخرج كل ما حدث: كل تمرة سقطت، وكل نقطة، وكل محاولة خسرها، إلى أن تنتهي اللعبة. والسبب في هذه الطريقة أن المخرج النصي يبين لك ترتيب الأحداث بالضبط وزمن كل منها، وهذا ما لا تراه بعينك وأنت تلعب، ولأنها الطريقة نفسها التي تختبر بها لعبتك تلقائياً قبل كل إصدار.
ملفات المختبر
أولاً الملف Dockerfile، وهو ينزل نسخة Godot 4.7.2 الرسمية من صفحة الإصدار على GitHub ويتحقق منها بالبصمة SHA512 قبل استخدامها، ويضيف مكتبتي Xvfb وMesa لالتقاط الصور كما سيأتي:
# Godot 4.7.2 (official Linux build from GitHub, checked against the release's SHA512 sums) in a small image.
# xvfb + Mesa let the same binary draw real frames in software (for the screenshots); --headless needs neither.
FROM debian:bookworm-slim
ARG GODOT=4.7.2-stable
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl unzip libfontconfig1 \
xvfb xauth libgl1 libgl1-mesa-dri libxcursor1 libxinerama1 libxrandr2 libxi6 libasound2 libpulse0 \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /opt/godot
RUN curl -fsSLO https://github.com/godotengine/godot/releases/download/${GODOT}/Godot_v${GODOT}_linux.x86_64.zip \
&& curl -fsSLO https://github.com/godotengine/godot/releases/download/${GODOT}/SHA512-SUMS.txt \
&& grep " Godot_v${GODOT}_linux.x86_64.zip$" SHA512-SUMS.txt | sha512sum -c - \
&& unzip -q Godot_v${GODOT}_linux.x86_64.zip && rm Godot_v${GODOT}_linux.x86_64.zip \
&& mv Godot_v${GODOT}_linux.x86_64 /usr/local/bin/godot
COPY game /game
WORKDIR /gameثم الروبوت، وهو عقدة عادية بسكربت، يضيفها المشهد الرئيسي فقط مع الوسيط --autoplay:
extends Node
## Lab only: plays the game by pressing the same actions a player presses on the keyboard.
## Run with: godot --headless --path game -- --autoplay
var ticks := 0
var shots := [] # physics ticks at which to save a screenshot (only with --shot and a real renderer)
var shot_dir := ""
func _ready() -> void:
var args := OS.get_cmdline_user_args()
if "--shot" in args:
shots = [5 * 60, 870]
shot_dir = args[args.find("--shot") + 1]
func _physics_process(_delta: float) -> void:
ticks += 1
var main := get_parent()
var player: Area2D = main.player
var target := _best_target(player)
_press("move_left", target < player.position.x - 6)
_press("move_right", target > player.position.x + 6)
if ticks in shots:
var img := get_viewport().get_texture().get_image()
var path := "%s/shot-%03d.png" % [shot_dir, ticks]
img.save_png(path)
main.log_event("screenshot saved: %s" % path.get_file())
if not main.playing and ticks % 60 == 0:
get_tree().quit()
# The lowest date the basket can still reach in time; step aside if a stone is about to land there.
func _best_target(player: Area2D) -> float:
var best := player.position.x
var best_y := -1.0
for item in get_tree().get_nodes_in_group("falling"):
if item.kind != "date" or item.is_queued_for_deletion():
continue
var time_left: float = (player.position.y - item.position.y) / item.fall_speed
var need: float = abs(item.position.x - player.position.x) / player.speed
if need <= time_left and item.position.y > best_y:
best = item.position.x
best_y = item.position.y
for item in get_tree().get_nodes_in_group("falling"):
if item.kind == "stone" and item.position.y > 300 and abs(item.position.x - best) < 50:
best += 90 if best < item.position.x else -90
return best
func _press(action: String, on: bool) -> void:
if on and not Input.is_action_pressed(action):
Input.action_press(action)
elif not on and Input.is_action_pressed(action):
Input.action_release(action)في السكربت أعلاه لاحظ التالي:
- الروبوت لا يحرك السلة بنفسه، وإنما يضغط الفعلين
move_leftوmove_rightبالدالةInput.action_pressويرفعهما بالدالةInput.action_release، كما يفعل الإنسان بأصابعه، فالسلة تتحرك بالكود نفسه الذي يحركها في اللعب الحقيقي. - في كل خطوة فيزياء يختار أقرب تمرة إلى الأرض يستطيع أن يصل إليها قبل أن تسقط، بحسبة بسيطة: الزمن الباقي حتى تصل التمرة إلى السلة، مقابل الزمن الذي تحتاجه السلة لتصل إلى موضعها. وإذا كان حجر على وشك السقوط في المكان نفسه ابتعد عنه.
- الروبوت ليس لاعباً مثالياً، وهذا مقصود: نريد أن نرى اللعبة تنتهي.
- مع الوسيط
--shotيحفظ صورة من الشاشة في لحظتين، بعد خمس ثوان وبعد نهاية اللعبة بقليل.
وأخيراً run.sh الذي يبني الـ Image ويشغل اللعبة بعدة طرق:
#!/bin/bash
# «حصاد التمر», the game of the article, run three ways. From this folder: bash run.sh
# (out-01-first-try.txt came from the first version of falling.gd, which asked the window for the ground height;
# in --headless the window is not 720x480, so every date «landed» on its first physics step. The article shows the fix.)
set -e
docker build -q -t harvest-lab:1 . > /dev/null
echo "### 2. A bot plays at 60 frames per second (no screen)"
docker run --rm harvest-lab:1 godot --headless --fixed-fps 60 --path /game -- --autoplay 2>&1 | grep -v '^Godot Engine' | tee out-02-play.txt
echo "### 3. The same game on a slow machine: 20 frames per second"
docker run --rm harvest-lab:1 godot --headless --fixed-fps 20 --path /game -- --autoplay 2>&1 | grep -E '^t=' | tee out-03-fps20.txt
echo "### 4. Real frames drawn in software (Xvfb + Mesa llvmpipe), two screenshots"
mkdir -p shots
docker run --rm -v "$(pwd -W 2>/dev/null || pwd)/shots:/shots" harvest-lab:1 bash -c \
'xvfb-run -a -s "-screen 0 720x480x24" godot --rendering-driver opengl3 --fixed-fps 60 --path /game -- --autoplay --shot /shots 2>&1' \
| grep -E '^OpenGL|screenshot|GAME OVER' | tee out-04-shots.txt
echo "### 5. The Timer switched from drawn frames (Idle, the default) to physics steps, at 60 and 20 fps"
docker run --rm harvest-lab:1 bash -c \
'sed -i "s/^wait_time = 0.9/process_callback = 0\nwait_time = 0.9/" /game/main.tscn
for f in 60 20; do echo "--fixed-fps $f"; godot --headless --fixed-fps $f --path /game -- --autoplay 2>&1 | grep -E "^t=" | sed -n "1,3p;\$p"; done' \
| tee out-05-timer-physics.txtوالخيار --headless بحسب توثيق سطر الأوامر يشغل المحرك دون شاشة ودون صوت، والخيار --fixed-fps يجبره على عدد ثابت من الإطارات في الثانية ويوقف مزامنته مع الساعة الحقيقية. أي أن المحرك يحسب كل إطار كأنه أخذ 1/60 ثانية، مهما كانت سرعة الجهاز، فتنتهي اللعبة كلها في أقل من ثانية حقيقية، وتخرج النتيجة نفسها في كل تشغيل.
التشغيل: الروبوت يلعب
نشغل المختبر من مجلد lab بالأمر bash run.sh، وأول ما تطبعه اللعبة هو شجرة المشهد كما رآها المحرك:
Godot 4.7.2-stable (official) | display: headless
┖╴Main
┠╴Sky
┠╴Palm
┃ ┠╴Trunk
┃ ┠╴FrondL1
┃ ┠╴FrondR1
┃ ┠╴FrondL2
┃ ┠╴FrondR2
┃ ┖╴FrondTop
┠╴Ground
┠╴Player
┃ ┠╴Basket
┃ ┠╴Rim
┃ ┖╴Shape
┠╴SpawnTimer
┖╴HUD
┠╴Score
┠╴Lives
┖╴Message
┖╴Panelهذه هي الشجرة التي رسمناها في الشكل الثاني، ولكن من داخل المحرك وهو يعمل. لاحظ أن عقدة Player ظهرت بأبنائها Basket وRim وShape، مع أننا لم نكتبهم في المشهد الرئيسي، وإنما كتبنا فقط أن Player نسخة من player.tscn. ولاحظ أيضاً أنه لا توجد أي تمرة في الشجرة بعد، لأن الشجرة طبعت في _ready قبل أن يدق المؤقت أول مرة، وأن الروبوت نفسه لم يظهر لأنه أضيف بعد الطباعة.
ثم يبدأ اللعب، والمخرج التالي هو الجولة كاملة:
t= 0.90s spawn date x=483 speed=160 (on screen: 1)
t= 1.80s spawn date x=196 speed=160 (on screen: 2)
t= 2.70s spawn date x=373 speed=160 (on screen: 3)
t= 3.15s CAUGHT date -> score 1
t= 3.60s spawn date x= 57 speed=168 (on screen: 3)
t= 4.05s CAUGHT date -> score 2
t= 4.50s spawn stone x=157 speed=176 (on screen: 3)
t= 4.95s CAUGHT date -> score 3
t= 5.40s spawn stone x=387 speed=184 (on screen: 3)
t= 5.73s CAUGHT date -> score 4
t= 6.30s spawn date x=515 speed=192 (on screen: 3)
t= 6.55s LOST a life (stone hit the basket) -> lives 2
t= 7.20s spawn stone x=546 speed=192 (on screen: 3)
t= 8.10s spawn date x=351 speed=192 (on screen: 3)
t= 8.17s CAUGHT date -> score 5
t= 9.00s spawn date x=625 speed=200 (on screen: 3)
t= 9.90s spawn date x= 69 speed=200 (on screen: 3)
t= 9.97s CAUGHT date -> score 6
t=10.80s spawn date x=311 speed=208 (on screen: 3)
t=10.80s CAUGHT date -> score 7
t=11.70s spawn date x= 49 speed=216 (on screen: 3)
t=11.87s LOST a life (date fell on the ground) -> lives 1
t=12.53s CAUGHT date -> score 8
t=12.60s spawn date x=653 speed=224 (on screen: 2)
t=13.37s CAUGHT date -> score 9
t=13.50s spawn date x=226 speed=232 (on screen: 2)
t=14.35s LOST a life (date fell on the ground) -> lives 0
t=14.35s GAME OVER score=9 spawned dates=12 stones=3 caught=9 missed=2 stones hit=1 dodged=2في المخرج أعلاه لاحظ التالي:
- كل 0.9 ثانية بالضبط تظهر نسخة جديدة، وهذا هو المؤقت، وأول نقطة جاءت في الثانية 3.15 عندما وصلت أول تمرة إلى السلة.
- السرعة تزيد مع كل نقطة كما كتبنا في القواعد، من 160 بكسل في الثانية في البداية إلى 232 في آخر تمرة.
- عدد ما على الشاشة لا يزيد عن ثلاثة، والسبب أن كل تمرة تحذف نفسها بالدالة
queue_freeعندما تلتقط أو تصل إلى الأرض. ولو نسينا الحذف لزاد العدد بلا توقف، وهذا من أشهر أسباب بطء الألعاب بعد دقائق من اللعب. - في الثانية 6.55 دخل حجر السلة فخسر الروبوت أول محاولة، ثم فاتته تمرتان كانتا بعيدتين عن السلة، في الثانية 11.87 والثانية 14.35، فانتهت اللعبة بتسع نقاط.
- السطر الأخير ملخص الجولة: 15 شيئاً سقط، 12 تمرة و3 حجارة، التقط منها 9، وفاتته 2، ودخل السلة حجر واحد، وتجنب حجرين.
والشكل التالي يبين الجولة نفسها على خط الزمن:

خطأ شائع: عالم اللعبة يسأل النافذة عن حجمها
في أول نسخة من سكربت ما يسقط كتبنا شرط الوصول إلى الأرض هكذا، بأن نسأل العقدة عن حجم الشاشة التي تعرض اللعبة ونطرح منه عشرين بكسل:
func _physics_process(delta: float) -> void:
position.y += fall_speed * delta
if position.y > get_viewport_rect().size.y - 20:
landed.emit(self)
queue_free()وهذا الشرط يبدو صحيحاً، وعلى جهازك أمام المحرر يعمل فعلاً. ولكن عند تشغيل اللعبة في المختبر دون شاشة كان المخرج كما يلي:
t= 0.90s spawn date x=483 speed=160 (on screen: 1)
t= 0.92s LOST a life (date fell on the ground) -> lives 2
t= 1.80s spawn date x=196 speed=160 (on screen: 1)
t= 1.82s LOST a life (date fell on the ground) -> lives 1
t= 2.70s spawn date x=373 speed=160 (on screen: 1)
t= 2.72s LOST a life (date fell on the ground) -> lives 0
t= 2.72s GAME OVER score=0 spawned dates=3 stones=0 caught=0 missed=3 stones hit=0 dodged=0كل تمرة «وصلت إلى الأرض» بعد 0.02 ثانية من ظهورها، أي في أول خطوة فيزياء لها، وانتهت اللعبة في أقل من ثلاث ثوان دون أن تلتقط السلة شيئاً. والسبب أن الخيار --headless يشغل المحرك دون نافذة حقيقية، فلا يكون حجم ما يعرض اللعبة 720 في 480 كما في إعدادات المشروع، فأصبح خط الأرض المحسوب فوق المكان الذي تظهر فيه التمرة، وتحقق الشرط فوراً.
والدرس هنا أوسع من المختبر: النافذة يغير اللاعب حجمها، والجوال يدور، والشاشات تختلف في دقتها، وأي قاعدة في اللعبة تبنى على حجم النافذة سوف تتغير معها. ولذلك قمنا بإصلاحه بأن جعلنا للعالم حجماً ثابتاً خاصاً به، الثابت GROUND_Y في سكربت ما يسقط والثابت WORLD_WIDTH في سكربت السلة، وتركنا للمحرك مهمة تكبير هذا العالم أو تصغيره ليناسب النافذة بالخيار stretch/mode="canvas_items". فإذا رأيت في لعبتك أن أحداثاً تقع وحدها فور البداية، أو أن اللاعب يخرج من الشاشة بعد تكبير النافذة، فابحث أولاً عن أي سطر يسأل عن get_viewport_rect في منطق اللعبة.
اللعبة نفسها على جهاز بطيء
في التشغيل الثالث شغلنا اللعبة بالبذرة نفسها، ولكن بعشرين إطاراً في الثانية بدل ستين، كأنها على جهاز بطيء جداً. وهذا أول المخرج وآخره:
t= 0.93s spawn date x=483 speed=160 (on screen: 1)
t= 1.83s spawn date x=196 speed=160 (on screen: 2)
t= 2.73s spawn date x=373 speed=160 (on screen: 3)
t= 3.18s CAUGHT date -> score 1
...
t=13.40s CAUGHT date -> score 9
t=13.53s spawn date x=226 speed=232 (on screen: 2)
t=14.38s LOST a life (date fell on the ground) -> lives 0
t=14.38s GAME OVER score=9 spawned dates=12 stones=3 caught=9 missed=2 stones hit=1 dodged=2الجولة هي نفسها: الأحداث الثمانية والعشرون كلها، بالترتيب نفسه، وبالنتيجة نفسها، تسع نقاط ونهاية اللعبة بعد تمرة على الأرض. وهذا لأن كل حركة في اللعبة في _physics_process، وخطوات الفيزياء ستون في الثانية على الجهازين، فالجهاز البطيء يرسم إطاراً واحداً كل ثلاث خطوات، ولكن التمرة تسقط والسلة تتحرك بالسرعة نفسها.
ولكن لاحظ أن كل حدث جاء بعد 0.03 ثانية من موعده في التشغيل الأول، فأول تمرة ظهرت في 0.93 بدل 0.90. والسبب في المؤقت SpawnTimer: فبحسب توثيق Timer قيمته الافتراضية للخاصية process_callback هي Idle، أي أنه يعد الزمن مع كل إطار يرسم، وليس مع كل خطوة فيزياء. فعلى الجهاز البطيء لا يلاحظ المؤقت أن 0.9 ثانية مرت إلا عند الإطار التالي، وكل إطار هنا 0.05 ثانية. والتأخير في لعبتنا ثابت ولا يغير النتيجة، ولكن في لعبة يعتمد فيها توقيت الأعداء على المؤقت قد يصنع فرقاً بين جهازين.
وللتأكد من هذا التفسير غيرنا في التشغيل الخامس الخاصية process_callback إلى Physics، وشغلنا اللعبة مرة بستين إطاراً ومرة بعشرين:
--fixed-fps 60
t= 0.90s spawn date x=483 speed=160 (on screen: 1)
t= 1.80s spawn date x=196 speed=160 (on screen: 2)
t= 2.70s spawn date x=373 speed=160 (on screen: 3)
t=14.35s GAME OVER score=9 spawned dates=12 stones=3 caught=9 missed=2 stones hit=1 dodged=2
--fixed-fps 20
t= 0.90s spawn date x=483 speed=160 (on screen: 1)
t= 1.80s spawn date x=196 speed=160 (on screen: 2)
t= 2.70s spawn date x=373 speed=160 (on screen: 3)
t=14.35s GAME OVER score=9 spawned dates=12 stones=3 caught=9 missed=2 stones hit=1 dodged=2والآن التوقيت متطابق تماماً على الجهازين، 0.90 ثانية لأول تمرة و14.35 لنهاية اللعبة. والقاعدة التي تخرج بها: كل مؤقت يؤثر في منطق اللعبة اجعله على Physics، من الخاصية Process Callback في لوحة Inspector، واترك Idle للمؤقتات التي تخص العرض فقط، مثل وميض نص في القائمة.
--fixed-fps 20 أو أقل، وقارن ما يحدث. وهذا الاختبار يكشف كل حركة كتبتها في _process دون delta، وكل مؤقت يؤثر في اللعب وهو على Idle.صور حقيقية من اللعبة دون شاشة
في وضع --headless لا يرسم المحرك شيئاً، فلا يمكن التقاط صورة منه. ولذلك شغلنا في التشغيل الرابع النسخة نفسها من Godot مع شاشة وهمية من Xvfb، ومع مكتبة Mesa التي ترسم بالمعالج بدل بطاقة الرسوميات، فرسم المحرك كل إطار فعلاً، وحفظ الروبوت صورتين بالدالة get_image من الشاشة:
OpenGL API 4.5 (Core Profile) Mesa 22.3.6 - Compatibility - Using Device: Mesa/X.org - llvmpipe (LLVM 15.0.6, 256 bits)
t= 5.00s screenshot saved: shot-300.png
t=14.35s GAME OVER score=9 spawned dates=12 stones=3 caught=9 missed=2 stones hit=1 dodged=2
t=14.50s screenshot saved: shot-870.pngالسطر الأول يبين أن المحرك يرسم بنمط Compatibility عبر OpenGL على المعالج llvmpipe، والأسطر التالية تبين أن الجولة هي نفسها حتى مع الرسم الحقيقي، النهاية في 14.35 بتسع نقاط. والصورة الأولى في أول المقال هي الصورة الأولى من هذا التشغيل، وهذه الثانية بعد نهاية اللعبة:

لاحظ في الصورة التمرة المتوقفة في الهواء خلف رسالة النهاية: هذا هو السطر call_group("falling", "set_physics_process", false) في دالة game_over، فقد أوقف _physics_process في كل النسخ الباقية بسطر واحد، فتجمدت مكانها.
افتح المشروع في المحرر
المختبر يشغل اللعبة دون شاشة، ولكن الهدف أن تفتحها أنت في المحرر وتلعبها وتعدلها. والخطوات كما يلي:
- نزل Godot 4.7 من صفحة التنزيل الرسمية، وهو ملف تنفيذي واحد لا يحتاج إلى تثبيت.
- من نافذة مدير المشاريع Project Manager اختر Import، ثم اختر الملف
project.godotمن مجلدlab/game. - اضغط F5، أو زر التشغيل في أعلى المحرر، لتشغيل المشهد الرئيسي، وحرك السلة بالأسهم أو بالحرفين A وD.
- في أثناء التشغيل افتح التبويب Remote في لوحة Scene، وسوف ترى شجرة اللعبة الحية، والتمر يظهر فيها ويختفي، وتستطيع أن تختار أي عقدة وتغير خصائصها واللعبة تعمل.
- افتح المشهد
player.tscnواختر العقدةPlayer، وسوف تجد الخاصية Speed في لوحة Inspector، لأننا كتبنا قبلها@export. غيرها إلى 600 وشغل اللعبة لترى الفرق.
وإذا أردت درساً رسمياً مكملاً، ففي التوثيق درس لعبتك الأولى ثنائية الأبعاد، وهو يبني لعبة مختلفة بصور جاهزة ومشاهد للعدو والواجهة، والأفكار فيه هي نفسها التي شرحناها هنا: عقد ومشاهد ونسخ وإشارات.
أخطاء شائعة في أول لعبة
- الحركة دون
delta: سطر مثلposition.x += 5في_processيجعل اللعبة أسرع على الجهاز السريع وأبطأ على البطيء. اكتب السرعة في الثانية واضربها فيdelta، وضع الحركة في_physics_process. - مسار عقدة خاطئ: إذا كتبت
$Playrبدل$Player، أو نقلت العقدة في الشجرة، سوف يظهر خطأ Node not found عند التشغيل، ويصبح المتغير فارغاً null. وعندما ترى هذا الخطأ قارن المسار في الكود بالشجرة في لوحة Scene حرفاً حرفاً، فحالة الأحرف مهمة. - استخدام عقدة قبل
_ready: إذا كتبتvar player = $Playerدون@onready، يحاول السكربت أن يجد العقدة قبل أن تدخل الشجرة فلا يجدها. استخدم@onreadyلكل متغير يشير إلى عقدة. - ربط الإشارة مرتين: إذا ربطت الإشارة في المحرر ثم ربطتها في الكود أيضاً، سوف يظهر خطأ أن الإشارة مربوطة مسبقاً بالدالة نفسها، ويرفض المحرك الربط الثاني. والخطأ لا يوقف اللعبة، ولكنه يملأ السجل ويخفي عنك أخطاء أهم، والأسوأ أن تحذف الربط من الكود ظاناً أنه الوحيد، فتبقى الإشارة مربوطة من المحرر دون أن تعرف. اختر طريقة واحدة لكل إشارة.
- نسيان الحذف: كل نسخة تنشئها بالدالة
instantiateتبقى في الذاكرة وفي الشجرة حتى تحذفها بالدالةqueue_free، حتى لو خرجت من الشاشة. راقب عدد العقد في التبويب Remote أو في لوحة Debugger، فإذا زاد بلا توقف فهناك نسخ لا تحذف. - الحذف بالدالة
freeفي وسط الإشارة: الدالةfreeتحذف العقدة فوراً، فإذا كانت عقدة أخرى ما زالت تحتفظ بها في الإطار نفسه، مثل دالة تستقبل الإشارة بعد دالتك، فسوف تتعامل مع كائن محذوف وتظهر أخطاء Previously freed. استخدمqueue_freeدائماً في منطق اللعبة. - منطق اللعبة في كل مكان: إذا وجدت نفسك تكتب
get_parent()في سكربت ابن لتغير شيئاً في أبيه، فتوقف واستخدم إشارة. والسبب أن كلget_parentيربط العقدة بمكانها في الشجرة، فتنكسر عندما تنقلها.
تطبيق عملي
- أضف نوعاً ثالثاً يسقط: تمرة ذهبية نادرة، تظهر مرة من كل عشرين، وتعطي ثلاث نقاط. تحتاج إلى قيمة جديدة للمتغير
kindفي سكربت ما يسقط، وتعديل سطر في_on_spawn_timer_timeoutوآخر في_on_player_caught، ولا يتغير شيء في السلة. - أضف إشارة جديدة
game_ended(score)في المشهد الرئيسي ترسلها عند نهاية اللعبة، ثم أضف عقدة جديدة تستمع لها وتحفظ أعلى نتيجة في ملف بالدالةFileAccess. - غير الخاصية
process_callbackللمؤقت إلى Physics في المحرر، ثم شغل المختبر وتأكد أن مخرج التشغيل الثالث أصبح بالأزمان نفسها للتشغيل الثاني. - اكسرها عن قصد: احذف السطر
item.queue_free()من_on_player_caught، وشغل المختبر، وراقب النقاط والمحاولات معاً. ستجد أن كل تمرة تلتقطها تعطيك نقطة ثم تخسرك محاولة بعد لحظة، فانتهت اللعبة بسرعة مع أن السلة لم تفوت شيئاً. والسؤال لك: لماذا؟ تتبع ما تفعله التمرة بعد أن تدخل السلة، وأي إشارة ترسلها بعد ذلك.
حذف المختبر Cleanup
docker image rm harvest-lab:1
rm -rf shotsالخلاصة Summary
- اللعبة في Godot شجرة من المشاهد، وكل مشهد شجرة من العقد في ملف
.tscn، وكل عقدة لها نوع يعطيها سلوكاً جاهزاً. - اجعل الشيء مشهداً مستقلاً إذا كان يتكرر أو له سلوك خاص به، ثم أنشئ منه نسخاً بالدالة
instantiateوأضفها بالدالةadd_child، واحذفها بالدالةqueue_free. - الدالة
_readyللتهيئة، و_physics_processلكل ما يؤثر في نتيجة اللعبة، و_processللعرض فقط. - اسأل عن الأفعال وليس عن المفاتيح، فيتغير التحكم من خريطة التحكم دون أن يتغير الكود.
- الإشارة تصعد والاستدعاء ينزل: العقد تعلن ما حدث لها، والمشهد الرئيسي وحده يعرف القواعد.
- في المختبر أنهى الروبوت الجولة بتسع نقاط في 14.35 ثانية، وكانت الجولة نفسها على جهاز بعشرين إطاراً في الثانية، مع تأخير ثابت قدره 0.03 ثانية سببه المؤقت على Idle، واختفى عندما جعلناه على Physics.
- لا تبن قواعد اللعبة على حجم النافذة: أعط العالم حجماً ثابتاً، واترك التكبير للمحرك.
وفي المقالات القادمة من هذه المرحلة بإذن الله نكمل على هذه اللعبة نفسها: الفيزياء والتصادم والتحكم بالأجسام الفيزيائية، ثم الواجهة والنص العربي، ثم الصوت، ثم تصديرها إلى الويب والجوال وسطح المكتب. وإذا لم تقرأ مقالات المرحلة الأولى بعد، فهذه هي:
دليلمحركات الألعاب: Godot وUnity وUnreal وتراخيصهاما الذي يعطيك محرك الألعاب حتى لا تكتبه بنفسك، وكيف تعمل حلقة اللعبة في مختبر Godot حقيقي، وماذا تدفع لكل محرك ومتى.
دليلكيف تعمل اللعبة من الداخل؟ حلقة اللعبة Game Loopلماذا تتحرك الشخصية بالسرعة نفسها على شاشة 144 هرتز وحاسوب بطيء: نبني حلقة اللعبة من الصفر حتى الخطوة الثابتة والاستيفاء، ونقيس كل طريقة في مختبر.
دليلرياضيات الألعاب: المتجهات Vectors والحركة والتصادمالمتجهات والحركة وحاصل الضرب النقطي واختبارات التصادم والارتداد والنفق، بلعبة صغيرة ومختبر Python يصنع الأخطاء الشائعة ثم يصلحها.
دليلتصدير اللعبة من Godot إلى الويب والجوال وسطح المكتبماذا يحدث فعلاً عند تصدير لعبة Godot، ولماذا تحتاج نسخة الويب Headers خاصة أحياناً، وما تطلبه كل منصة ومتجر، مع مختبر يصدر لعبة واحدة إلى خمس منصات.سجل التحديثات Changelog
- نوفمبر 2026: كتابة المقال، وبناء لعبة «حصاد التمر» وتشغيلها على Godot 4.7.2 دون شاشة في Docker Engine 29.8.0، والتقاط الصور بالرسم البرمجي عبر Xvfb وMesa llvmpipe.