دليل سطر الأوامر في محرك جودو

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

ملاحظة: يمكنك تشغيل ملف جودو ثنائي في سطر الأوامر بتحديد مساره المطلق أو النسبي على نظامَي ويندوز ولينكس.

أما في نظام ماك أو إس فالعملية مختلفة نظرًا إلى أن جودو محتوى بداخل حزمة .app (يمثل مجلد وليس ملف). لتشغيل ملف جودو ثنائي من سطر الأوامر على ماك إو إس ستحتاج للانتقال إلى مسار مجلد حزمة تطبيق جودو باستخدام الأمر cd ومن ثم تنفيذ Godot.app/Contents/MacOS/Godot متبوعًا بأي وسطاء. إذا أعدت تسمية حزمة التطبيق من Godot إلى اسم آخر فيجب عليك التأكد من تعديل الأمر السابق بشكل موافق.

مرجع سطر الأوامر

دليل الرموز

✓ متاح في إصدارات المحرر وقوالب تصدير الأخطاء debug export templates وقوالب تصدير الإطلاق release export templates.
☼ متاح في إصدارات المحرر وقوالب تصدير الأخطاء فقط.
🔧متاح فقط في إصدارات المحرر.

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

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

الأمر	الوصف
`‎-h`, `--help`	✓ يعرض لائحة من خيارات سطر الأوامر
`‎--version`	✓ يعرض السلسلة النصية التي تمثل رقم الإصدار
`‎-v`, `--verbose`	✓ استخدام نمط الطباعة stdout المسهب
`‎-q`, `--quiet`	✓ النمط الهادئ، يتجاوز رسائل الطباعة stdout، مع المحافظة على عرض رسائل الأخطاء

خيارات التنفيذ

الأمر	الوصف
‎`--`, `++`	✓ فاصل لوسطاء سطر الأوامر التي يكتبها المستخدم، ولا يستخدم المحرك الوسطاء المذكورة بعدها وإنما يمكن قراءتها من `OS.get_cmdline_user_args()`‎
‎`-e`, `--editor`	🔧يشغّل المحرر بدلًا من تشغيل المشهد
‎`-p`, `--project-manager`	🔧يشغّل مدير المشروع حتى لو تم اكتشاف المشروع تلقائيًا
`‎--debug-server<uri‎>‎`	🔧يشغّل خادم تنقيح أخطاء المحرر (`‎<protocol>://<host/IP>[:<port>]` مثل `tcp://127.0.0.1:6007`)
`‎--quit`	✓ الخروج بعد التكرار الأول
`‎--quit-after`	✓ الخروج بعد عدد تكرارات معين، يمكنك ضبط القيمة إلى 0 لتعطيلها
`‎-l`, `--language <locale>`‎	✓ استخدم الأمر مع لغة ما، تتبع القيمة `<locale>` التنسيق `language_script_COUNTRY_VARIANT` حيث أن اللغة تتألف من حرفين إلى ثلاث كرمز لها بأحرف صغيرة والخيارات المتبقية هي اختيارية، انظر إلى رموز اللغات للمزيد من التفاصيل.
`‎--path <directory>‎`	✓ مسار المشروع ( يجب أن يحتوي `<directory>` على ملف project.godot)
`‎-u`, `--upwards`	✓ يفحص المجلدات تصاعديًا للبحث عن `project.godot`
`‎--main-pack <file>‎`	✓ مسار الملف `‎.pck` الذي تريد تحميله
`‎--render-thread <mode>‎`	✓ نمط تصيير الخيط render thread (آمن، غير آمن، منفصل). أنظر إلى نموذج الخيط لمزيد من التفاصيل.
`‎--remote-fs <address>‎`	✓ نظام ملفات غير محلي (بعيد) باستخدام عنوان ‎`<host/IP>[:<port>]`
`‎--remote-fs-password <password>‎`	✓ كلمة مرور نظام الملفات البعيد
`‎--audio-driver <driver>‎`	✓ محرك الصوت. استخدم ‎`--help` أولًا للحصول على قائمة من المحركات المتاحة
`‎--display-driver <driver>‎`	✓ محرك العرض (ومحرك التصيير render)، استخدم‎ `--help` أولًا للحصول على قائمة من المحركات المتاحة
`‎--rendering-method <renderer>‎`	✓ اسم المُصيّر، ويتطلب دعمًا من محرك التصيير
`‎--rendering-drive <driver>‎`	✓ محرك التصيير (يعتمد على محرك العرض)، استخدم ‎`--help` أولًا للحصول على لائحة من المحركات المتاحة
`‎--gpu-index <device_index>‎`	✓ استخدام محرك رسوميات GPU معين (نفذ الأمر مع `‎--verbose` للحصول على لائحة الأجهزة المتاحة).
`‎--text-driver <driver>‎`	✓ محرك النص (بما في ذلك الخطوط، وBiDi، والأشكال)
`‎--tablet-driver <driver>‎`	✓ محرك الإدخال باستخدام القلم اللوحي
`‎--headless`	✓ تمكين وضع headless (`--display-driver headless --audio-driver Dummy`)، وهو مفيد للاستخدام مع الخوادم ومع `‎--script`
`‎--write-movie <file>‎`	✓ تشغيل المحرك بطريقة كتابة فيلم (عادةً بامتداد ملفات .avi أو .png)، يُجبر الخيار ‎`--fixed-fps` عندما يتم تمكينه، لكن يمكنك استخدامه أيضًا لتعديل معدل إطارات الفيلم بالثانية. يمكن أن يُسرّع ‎`--disable-vsync` كتابة الفيلم إلا أنه يجعل من التفاعل معه عملية أصعب، كما يمكن استخدام ‎`--quit-after`

خيارات العرض

الأمر	الوصف
‎`-f` ,`--fullscreen`	✓ طلب نمط النافذة الممتلئة
`‎-m`, `--maximized`	✓ طلب نمط نافذة كبيرة
`‎-w`, `--windowed`	✓ طلب نمط نافذة مؤطرة
‎`-t`, `--always-on-top`	✓ طلب نمط النافذة دائمًا على الأعلى
`‎--resolution <W>x<H>‎`	✓ طلب دقة النافذة
`‎--position <X>, <Y>‎`	✓ طلب احداثيات النافذة
`‎--screen <N>‎`	✓ طلب نافذة الشاشة
`‎--single-window`	✓ استخدام نافذة واحدة (دون استخدام نوافذ مفصولة)
`‎--xr-mode <mode>‎`	✓ تحديد نمط XR (الافتراضي default أو معطّل off أو مفعّل on)

خيارات تنقيح الأخطاء

الأمر	الوصف
`‎-d`, `--debug`	✓ تنقيح الأخطاء (منقّح الأخطاء stdout المحلي).
`‎-b`, `--breakpoints`	✓ لائحة بنقاط التوقف breakpoint بتنسيق المصدر::السطر مفصولين بفاصلة دون مسافات (استخدم 20% بدلًا من ذلك).
`‎--profiling`	✓ تمكين التشخيص في منقح أخطاء السكربت.
`‎--gpu-profile`	✓ عرض ملف وحدة المعالجة الرسومية الخاصة يحتوي على المهام التي استغرقت الوقت الأطول خلال تصيير الإطارات.
`‎--gpu-validation`	✓ تمكين واجهة طبقات التحقق البرمجية الرسومية.
`‎--gpu-abort`	☼ الإيقاف القسري عند حدوث أخطاء متعلقة بوحدة المعالجة الرسومية (غالبًا ما تكون الأخطاء متعلقة بطبقة التحقق validation layer) ويساعد ذلك في العثور على المشكلة إذا توقف النظام على العمل.
`‎--remote-debug <uri>‎`	✓ تحقق بعيد من الأخطاء (‎`<protocol>://<host/IP>[:<port>]` مثل `tcp://127.0.0.1:6007`).
`‎--single-threaded-scene`	✓ تنفيذ شجرة المَشاهد بنمط الخيط الواحد، مع تعطيل المجموعات متعدد الخيوط وتنفيذها على الخيط الأساسي.
`‎--debug-collisions`	☼ عرض أشكال الاصطدام collision shapes عند تشغيل المشهد.
`‎--debug-paths`	☼ عرض مسار الخطوط عند تشغيل المشهد.
`‎--debug-navigation`	☼ عرض مضلعات التنقل عند تشغيل المشهد.
`‎--debug-avoidance`	☼ عرض عناصر تنقيح الأخطاء البصرية لتجنب التنقل عند تشغيل المشهد.
`‎--debug-stringnames`	☼ طباعة جميع مواضع الذاكرة الخاصة بـ StringName إلى stdout عندما يتوقف المحرك.
`‎--frame-delay <ms>‎`	✓ محاكاة حمل عالي على وحدة المعالجة المركزية CPU (تأخير كل إطار بمقدار `<ms>` ميلي ثانية).
`‎--time-scale <scale>‎`	✓ تمكين تسريع الوقت قسريًا (القيم الأكبر تجعل من الوقت أسرع، القيمة 1.0 هي السرعة الاعتيادية).
`‎--disable-vsync`	✓ يوقف المزامنة الأفقية قسريًا، حتى لو كانت مفعلة في إعدادات المشروع، ولا يتجاوز هذا الفعل إجبار V-Sync على مستوى المحرك.
`‎--disable-render-loop`	✓ تعطيل حلقة التصيير بحيث تعمل فقط عندما تُستدعى بشكل صريح من سكربت.
`‎--disable-crash-handler`	✓ تعطيل معالج الأخطاء عندما تدعم شيفرة المنصة البرمجية ذلك الأمر.
`‎--fixed-fps <fps>‎`	✓ إجبار عرض عدد معين من الإطارات في الثانية، وهذا الإعداد يعطّل المزامنة في الوقت الحقيقي.
`‎--delta-smoothing <enable>‎`	✓ تعطيل أو تمكين تنعيم إطار دلتا (تمكين enable أو تعطيل disable).
`‎--print-fps`	✓ طباعة عدد الإطارات في الثانية إلى stdout.

الأدوات الإضافية

الأمر	الوصف
`‎-s`, `--script <script>‎`	✓ تشغيل سكربت.
`‎--check-only`	✓ تحليل الأخطاء والمغادرة (تُستخدم مع ‎`--script`).
`‎--export-release <preset> <path>‎`	🔧 استيراد المشروع باستخدام إعداد مسبق وطبقًا لقالب الإصدار، ويجب أن يطابق اسم الإعداد المسبق اسم الإعداد المعرف في `export_presets_cfg`، ويجب على `<path>` أن يكون مسارًا مطلقًا أو نسبيًا لمسار المشروع، وأن يتضمن على اسم المشروع للملف الثنائي (مثل builds/game.exe)، ويجب على المسار الهدف أن يكون موجودًا.
`‎--export-debug <preset> <path>‎`	🔧 يشابه الأمر --export-release ولكنه يستخدم قالب منقح الأخطاء.
`‎--export-pack <preset> <path>‎`	🔧 يشابه `‎--export-release` ولكنه يستورد حزمة اللعبة فقط للإعداد المسبق الحالي، ويجب على <path> أن يحدد فيما إذا كان الملف بصيغة PCK أو ZIP.
`‎--convert-3to4 [<max_file_kb>] [<max_line_size>]`	🔧 تحويل المشروع من إصدار جودو 3‎.x إلى 4‎.x.
‎`--validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]`	🔧 عرض الاسم الجديد للعناصر التي سيُعاد تسميتها عند التحويل من إصدار جودو 3‎.x إلى 4‎.x.
`‎--doctool [<path>]`	🔧 عرض توثيق الواجهة البرمجية الخاصة بالمحرك إلى المسار المكتوب في `<path>` بتنسيق XML، ويدمج المحتوى إذا ما وُجد الملف مُسبقًا.
`‎--no-docbase`	🔧 عدم السماح بعرض الأنواع الأساس (تُستخدم مع `‎--doctool`).
`‎--gdscript-docs <path>‎`	🔧 توليد مرجع للواجهة البرمجية عوضًا عن عرض واجهة المحرك البرمجية، وذلك من التوثيق المضمن في ملفات جي دي سكربت الموجودة في `<path>` (تُستخدم مع ‎`--doctool`).
`‎--build-solutions`	🔧 بناء حلول السكربت (لمشاريع سي شارب)، تتضمن `‎--editor` وتتطلب مشروع صالح للتعديل.
`‎--dump-gdextension-interface`	🔧 توليد ملف ترويسة GDExtension اسمه `gdnative_interface.h` في المجلد الحالي، وهذا الملف هو الملف الأساس المطلوب لتطبيق GDExtension.
`‎--dump-extension-api`	🔧 توليد ملف JSON يحتوي على ارتباطات GDExtension من واجهة جودو البرمجية باسم `extension_api.json` في المجلد الحالي.
`‎--validate-extension-api <path>‎`	🔧 التأكد من ملف واجهة الإضافة البرمجية (مع الخيار السابق) من إصدار محرك سابق للتأكد من توافقية الواجهات البرمجية، وتكون القيمة المُعادة قيمة غير صفرية إذا عُثر على عدم توافق أو أخطاء.
`‎--benchmark`	🔧 فحص أداء وقت التنفيذ والطباعة إلى الطرفية.
`‎--benchmark-file <path>‎`	🔧 فحص أداء وقت التنفيذ وحفظ النتيجة إلى ملف JSON، ويجب أن يكون المسار مسارًا مطلقًا.

المسار

يُنصح بوضع ملف جودو الثنائي في PATH كمتغير بيئة بحيث يمكنك تشغيله بسهولة من أي مكان بكتابة godot، يمكنك فعل ذلك على أجهزة لينكس بوضع ملف جودو الثنائي في ‎/usr/local/bin والتأكد من أن اسمه godot (انتبه لحالة الأحرف).

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

على ويندوز:

#المحرر الاعتيادي
scoop install godot

#المحرر الذي يدعم سي شارب (سيكون موجودًا باسم‫ godot-mono في PATH)
scoop install godot-mono

على ماك أو إس:

#المحرر الاعتيادي
brew install godot

#المحرر الذي يدعم سي شارب (سيكون موجودًا باسم‫ godot-mono في PATH)
brew install godot-mono

ضبط مسار المشروع

ستحتاج لضبط مسار مشروعك لأي من الأوامر لتعمل بشكلها الصحيح بحسب مكان وجود ملف جودو الثنائي ومسار العمل الحالي.

يمكن تحقيق ذلك بمنح المسار لملف project.godot في مشروعك كوسيط أول بهذا الشكل:

godot path_to_your_project/project.godot [other] [commands] [and] [args]

أو باستخدام وسيط ‎--path:

godot --path path_to_your_project [other] [commands] [and] [args]

على سبيل المثال، الأمر الكامل لتصدير لعبتك (كما سنشرح في الأسفل) قد يبدو بهذا الشكل:

godot --headless --path path_to_your_project --export-release my_export_preset_name game.exe

إنشاء مشروع

تستطيع إنشاء مشروع من سطر الأوامر عن طريق الذهاب إلى الصدفة shell والانتقال إلى المكان الذي تريده ومن ثم إنشاء ملف project.godot.

mkdir newgame
cd newgame
touch project.godot

يمكن فتح المشروع بعد ذلك باستخدام جودو

تشغيل المحرر

يمكنك تشغيل المحرر بتنفيذ جودو مع الراية ‎-e، ويجب فعل ذلك داخل مسار المشروع أو داخل المسارات الجزئية للمشروع، وإلا فإن الأمر سيُتجاهل وسيظهر مدير المشروع.

godot -e

يمكن تعديل مشهد تم إنشاؤه وحفظه سابقًا بتنفيذ الأمر ذاته وإضافة المشهد كوسيط ضمنه.

godot -e scene.tscn

مسح مشهد

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

rm scene.tscn

تشغيل اللعبة

يمكنك تنفيذ أمر جودو ببساطة لتشغيل اللعبة ضمن مسار المشروع أو المسار الجزئي.

godot

يمكنك تمرير اسم مشهد محدد إذا أردت تجربته كوسيط في سطر الأوامر.

godot scene.tscn

تنقيح الأخطاء

قد تكون مهمة إيجاد الأخطاء من سطر الأوامر مهمة صعبة بسبب طباعتها بشكل سريع على الطرفية، ولذلك السبب توجد طرفية منقح الأخطاء التي يمكنك الحصول عليها باستخدام الراية ‎-d، وتعمل سواءً أكنت تستخدمها من أجل اللعبة كاملة أو من أجل مشهد واحد.

godot -d

godot -d scene.tscn

التصدير

يمكن تصدير المشروع من سطر الأوامر، وهذا الأمر مفيد في حالة ضبط بيئة تكامل مستمر continuous integration.

ملاحظة: استخدام الوسيط ‎--headless في المنصات التي لا تحتوي على وصول لوحدة المعالجة الرسومية أمر مطلب (مثل بيئات التكامل المستمر)، بينما يمنع الوسيط ‎--headless في المنصات التي تحتوي على وصول لوحدة المعالجة الرسومية ظهور نافذة عند تصدير المشروع.

# يجب أن تكون‫ godot محرر ثنائي وليس قالب تصدير
# كما أنه يجب لقالب التصدير أن يكون مثبتًا على المحرر
# أو على الأقل يجب أن يكون قالب التصدير الصالح معرفًا في ضبط التصدير المسبق
godot --headless --export-release "Linux/X11" /var/builds/project
godot --headless --export-release Android /var/builds/project.apk

يجب على اسم الضبط المسبق أن يطابق اسم الضبط المسبق المُصدّر والمعرف في ملف المشروع export_presets.cfg، إذا احتوى اسم الضبط المسبق على مسافات أو محارف مميزة (مثل "windows desktop") فيجب إحاطته بعلامات تنصيص.

استخدم الخيار ‎--export-debug بدلًا من ‎--export-release لتصدير إصدار تنقيح إخطاء للعبة، فاستخدام الخياران ومعاملاتهما متطابقة.

استخدم الخيار ‎--export-pack لتصدير ملف PCK فقط متبوعًا باسم الضبط المسبق ومسار الخرج مع لاحقة الملف بدلًا من ‎--export-release أو ‎--export-debug، وتحدد لاحقة مسار الخرج نوع ملف الحزمة فيما إذا كان PCK أو ZIP.

تحذير: سيكون المسار نسبيًا بالنسبة للمسار الذي يحتوي على الملف project.godot عند تحديد مسار لكل من الخيارات ‎--export-release أو ‎--export-debug أو ‎--export-pack وليس نسبيًا إلى مسار العمل الحالي.

تشغيل سكربت

من الممكن تشغيل سكربت ‎.gd من سطر الأوامر، وهذه الميزة مفيدة في المشروعات الكبيرة مثل تحويل موارد كثيرة العدد أو الاستيراد والتصدير المخصص.

يجب أن يرث السكربت من SceneTree أو MainLoop.

إليك مثال عن سكربت sayhello.gd يوضّح كيف يعمل الأمر:

#!/usr/bin/env -S godot -s
extends SceneTree

func _init():
    print("Hello!")
    quit()

لتشغيله:

# يطبع‫ "Hello!‫‎" إلى الخرج القياسي
godot -s sayhello.gd

إذا لم يكن هناك project.godot متاح في المسار، فسيُفترض أن المسار الحالي هو مسار العمل الحال (إلا إن استخدم الخيار ‎--path) يُشار إلى السطر الأول من sayhello.gd في الأعلى عادةً باسم شابانج shebang، وهو يسمح بتنفيذ السكربت إذا كان ملف جودو الثنائي موجودًا في PATH باسم godot في توزيعات لينكس الحديثة وماك أو إس:

# تعليم السكربت كسربت تنفيذي
chmod +x sayhello.gd
# طباعة إلى الخرج القياسي
./sayhello.gd

إذا لم يعمل ما سبق في الإصدار الحالي من نظام لينكس أو ماك إو إس الخاص بك، يمكنك جعل شابانج ينفذ جودو مباشرة من مساره كما يلي:

#!/usr/bin/godot -s

مصادر

صفحة Command Line Tutorial في توثيق جودو الرسمي.