jak project

يرجى القراءة أولا

مهم

مستودعاتنا على GitHub مخصصة في المقام الأول لتطوير المشروع وتتبع المشكلات النشطة. تتعلق معظم المعلومات التي ستجدها هنا بإعداد المشروع لأغراض التطوير وليست ذات صلة بالمستخدم النهائي.

للحصول على دليل الإعداد حول كيفية تثبيت اللعبة وتشغيلها، يوجد الفيديو التالي الذي يمكنك مشاهدته: https://youtu.be/K84UUMnkJc4

للأسئلة أو المعلومات الإضافية المتعلقة بالمشروع، لدينا ديسكورد للمناقشة هنا: https://discord.gg/VZbXMHXzWv

بالإضافة إلى ذلك، يمكنك العثور على مزيد من الوثائق والإجابات على الأسئلة المتداولة على الموقع الرئيسي للمشروع: https://opengoal.dev

تحذير

لا تستخدم مشروع التفكيك هذا دون تقديم نسختك القانونية من اللعبة. نحن لا نقوم بتوزيع أي أصول من اللعبة - يجب عليك استخدام نسخة PS2 الخاصة بك والتي تم الحصول عليها بشكل قانوني من اللعبة. نحن ندعم جميع إصدارات PAL وNTSC وNTSC-J للبيع بالتجزئة، بما في ذلك نسخ Greatest Hits.

• وصف المشروع
  • الوضع الحالي
  • المنهجية
• تهيئة بيئة التطوير
  • عامل ميناء
  • لينكس
    • أوبونتو (20.04)
    • قوس
    • فيدورا
  • ويندوز
    • البرامج المطلوبة
    • باستخدام فيجوال ستوديو
  • ماك
    • إنتل على أساس
    • أبل السيليكون
  • VSCode
    • البناء والتصحيح
  • بناء وتشغيل اللعبة
    • استخراج الأصول
    • بناء اللعبة
    • قم بتشغيل اللعبة
      • توصيل REPL باللعبة
      • تشغيل اللعبة بدون التشغيل التلقائي
    • التفاعل مع اللعبة
• نظرة عامة على المشروع الفني
  • goalc
    • تشغيل المترجم
  • decompiler
    • تشغيل برنامج فك التشفير
  • goal_src/
  • وقت تشغيل game

وصف المشروع

يهدف هذا المشروع إلى نقل النسخة الأصلية من Jak وDaxter وJak II إلى جهاز الكمبيوتر. أكثر من 98% من الألعاب مكتوبة بلغة GOAL، وهي لغة Lisp مخصصة تم تطويرها بواسطة Naughty Dog. استراتيجيتنا هي:

• قم بفك كود اللعبة الأصلي إلى كود GOAL يمكن قراءته بواسطة الإنسان
• تطوير المترجم الخاص بنا لـ GOAL وإعادة ترجمة كود اللعبة لـ x86-64
• إنشاء أداة لاستخراج أصول اللعبة إلى تنسيقات يمكن عرضها أو تعديلها بسهولة
• إنشاء أدوات لإعادة تجميع أصول اللعبة بتنسيق يستخدمه المنفذ الخاص بنا.

أهدافنا هي:

• جعل المنفذ "تطبيقًا أصليًا" على نظام التشغيل x86-64، بأداء عالٍ. ولا ينبغي تقليده أو تفسيره أو نقله.
• يجب أن يكون أداء برنامج التحويل البرمجي GOAL الخاص بنا مشابهًا تقريبًا لأداء C.
• حاول مطابقة الأشياء من اللعبة الأصلية والتطوير قدر الإمكان. على سبيل المثال، دعم مترجم GOAL الأصلي التعديل المباشر للتعليمات البرمجية أثناء تشغيل اللعبة، لذلك نحن نفعل الشيء نفسه، على الرغم من أنه ليس مطلوبًا فقط لنقل اللعبة.
• تعديلات الدعم. يجب أن يكون من الممكن إجراء تعديلات على الكود دون كسر أي شيء آخر.

نحن ندعم كلاً من Linux وWindows على الإصدار x86-64.

نحن لا ندعم أو نخطط لدعم بنية ARM. وهذا يعني أن هذا لن يعمل على أجهزة مثل الجهاز المحمول.

الوضع الحالي

يمكن تشغيل Jak 1 إلى حد كبير من البداية إلى النهاية مع مجموعة من الأخطاء التي يتم حلها باستمرار. جاك 2 قيد التطوير.

قائمة التشغيل على اليوتيوب: https://www.youtube.com/playlist?list=PLWx9T30aAT50cLnCTY1SAbt2TtWQzKfXX

المنهجية

للمساعدة في عملية فك الترجمة، قمنا ببناء أداة فك ترجمة يمكنها معالجة كود GOAL وتفريغ أصول اللعبة. نحدد يدويًا أنواع الوظائف والمواقع التي نعتقد أن الكود الأصلي بها قوالب كتابة (أو حيث نشعر أنها مناسبة) حتى ينجح برنامج فك الترجمة، ثم نقوم بتنظيف مخرجات الكود الذي تم فك ترجمته عن طريق إضافة التعليقات وضبط التنسيق، ثم حفظه في goal_src .

تم تصميم برنامج فك التحويل البرمجي الخاص بنا خصيصًا لمعالجة مخرجات برنامج التحويل البرمجي الأصلي GOAL. ونتيجة لذلك، عندما يتم إرسالها بشكل صحيح، فإنها غالبًا ما تنتج تعليمات برمجية يمكن إدخالها مباشرة إلى المترجم وتعمل بشكل مثالي. ويتم اختبار ذلك باستمرار كجزء من اختبارات وحدتنا.

تهيئة بيئة التطوير

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

إذا كان هذا لا يناسبك وتريد فقط ممارسة اللعبة، فارجع إلى القسم "البدء السريع" أعلاه

عامل ميناء

يتم دعم جميع أنظمة Linux الثلاثة باستخدام Docker.

اختر نكهة Linux المفضلة لديك وقم ببناء الصورة التي اخترتها

 docker build -f docker/(Arch|Fedora|Ubuntu)/Dockerfile -t jak .

سيؤدي هذا إلى إنشاء صورة تحتوي على كافة التبعيات المطلوبة وتم إنشاؤها بالفعل.

 docker run -v "$(pwd)"/build:/home/jak/jak-project/build -it jak bash

ملاحظة: إذا قمت بتغيير محتوى دليل build/ فسوف تحتاج إلى إعادة تشغيل أمر build . وبدلاً من ذلك يمكنك الحصول على البناء عبر docker cp .

سيؤدي هذا إلى ربط build/ المجلد الخاص بك بالصور حتى تتمكن من التحقق من صحة الإصدار الخاص بك أو اختباره على جهاز خارجي.

يمكن ربط صور Docker بـ IDE الخاص بك (على سبيل المثال CLion) للمساعدة في التعرف على الرموز والتحليل الثابت وإجراء الاختبارات والبناء المستمر.

لسوء الحظ، ستظل بحاجة إلى برنامج تشغيل المهام على جهازك المحلي لتشغيل اللعبة أو بدلاً من ذلك، تشغيل اللعبة يدويًا عبر الأوامر الموجودة في Taskfile.yml .

لينكس

أوبونتو (20.04)

تثبيت الحزم ومستودع init:

sudo apt install gcc make cmake ninja-build build-essential g++ nasm clang-format libxrandr-dev libxinerama-dev libxcursor-dev libpulse-dev libxi-dev python libgl1-mesa-dev libssl-dev
sudo sh -c " $( curl --location https://taskfile.dev/install.sh ) " -- -d -b /usr/local/bin

تجميع:

cmake -B build && cmake --build build -j 8

تشغيل الاختبارات:

./test.sh

ملاحظة: لقد وجدنا أن clang و lld أسرع بكثير في التجميع والربط من gcc ، كما أنهما ينشئان تعليمات برمجية أسرع، ويمتلكان رسائل تحذير أفضل. لتثبيت هذه:

sudo apt install lld clang

وقم بتشغيل cmake (في دليل بناء جديد) باستخدام:

cmake -DCMAKE_SHARED_LINKER_FLAGS= " -fuse-ld=lld " -DCMAKE_EXE_LINKER_FLAGS= " -fuse-ld=lld " -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ..

قوس

تثبيت الحزم ومستودع init:

sudo pacman -S cmake libpulse base-devel nasm python libx11 libxrandr libxinerama libxcursor libxi
yay -S go-task

بالنسبة إلى Arch فقط، استبدل task بـ go-task في بقية التعليمات.

تجميع:

cmake -B build && cmake --build build -j 8

تشغيل الاختبارات:

./test.sh

فيدورا

تثبيت الحزم ومستودع init:

sudo dnf install cmake python lld clang nasm libX11-devel libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel pulseaudio-libs-devel mesa-libGL-devel
sudo sh -c " $( curl --location https://taskfile.dev/install.sh ) " -- -d -b /usr/local/bin

تجميع مع clang :

cmake -DCMAKE_SHARED_LINKER_FLAGS= " -fuse-ld=lld " -DCMAKE_EXE_LINKER_FLAGS= " -fuse-ld=lld " -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -B build
cmake --build build -j $( nproc )

تشغيل الاختبارات:

./test.sh

ويندوز

البرامج المطلوبة

نحن نستخدم في المقام الأول Visual Studio على نظام التشغيل Windows لتطوير لغة C++. قم بتنزيل أحدث إصدار للمجتمع من هنا. في وقت كتابة هذا التقرير، كان Visual Studio 2022.

سوف تحتاج إلى Desktop development with C++ . يمكن تحديد هذا أثناء التثبيت، أو بعده عبر Visual Studio Installer ، وتعديل تثبيت Visual Studio.

في نظام التشغيل Windows، يوصى باستخدام مدير الحزم، ونستخدم Scoop. اتبع الخطوات الموجودة أسفل الصفحة الرئيسية هنا للحصول عليه.

بمجرد تثبيت Scoop، قم بتشغيل الأوامر التالية:

scoop install git llvm nasm python task

باستخدام فيجوال ستوديو

قم باستنساخ المستودع عن طريق تشغيل الأمر التالي في المجلد الذي تختاره.

git clone https://github.com/open-goal/jak-project.git

سيؤدي هذا إلى إنشاء مجلد jak-project ، وفتح المشروع كمشروع CMake عبر Visual Studio.

ثم قم ببناء المشروع بأكمله كـ Windows Release (clang) . يمكنك أيضًا الضغط على Ctrl+Shift+B كمفتاح تشغيل سريع لـ Build All. نحن نفضل حاليًا clang على نظام التشغيل Windows بدلاً من msvc ، على الرغم من أنه يجب أن يعمل أيضًا!

ماك

ملاحظة: يتطلب تشغيل اللعبة جهاز Apple Silicon Mac يعمل بنظام macOS Sequoia أو Intel Mac.

تأكد من تثبيت أدوات سطر أوامر Xcode (يؤدي ذلك إلى تثبيت أشياء مثل Apple Clang). إذا لم تقم بذلك، يمكنك تشغيل الأمر التالي:

xcode-select --install

على Apple Silicon، يجب أيضًا تثبيت Rosetta 2:

softwareupdate --install-rosetta

بناء لx86_64

brew install cmake nasm ninja go-task clang-format
cmake -B build --preset=Release-macos-x86_64-clang
cmake --build build --parallel $(( `sysctl - n hw.logicalcpu` )) 

تصميم لـ ARM64 (تجريبي، غير مدعوم)

brew install cmake ninja go-task clang-format
cmake -B build --preset=Release-macos-arm64-clang
cmake --build build --parallel $(( `sysctl - n hw.logicalcpu` ))

قد تضطر إلى إضافة MacOS SDK إلى LIBRARY_PATH الخاص بك:

• export LIBRARY_PATH="$LIBRARY_PATH:/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib"

VSCode

إذا كنت لا تريد أو لا تستطيع استخدام Visual Studio للعمل مع مشروع C++، فإن VSCode هو البديل الجيد.

يوصى بامتداد clangd ويتطلب وجود clangd على $PATH . إذا تمكنت من تشغيل clangd في محطة طرفية بنجاح، فيجب أن تكون جاهزًا للمضي قدمًا.

بمجرد إنشاء CMake الخاص بك لأول مرة، يجب أن يكون clangd LSP قادرًا على فهرسة المشروع وإعطائك التحسس.

البناء والتصحيح

المهام - فكر في المساهمة بالوثائق :)

بناء وتشغيل اللعبة

يتضمن الحصول على لعبة الجري 4 خطوات:

1. إنشاء أدوات C++ (اتبع خطوات البدء أعلاه لنظامك الأساسي)
2. استخراج الأصول من اللعبة
3. بناء اللعبة
4. قم بتشغيل اللعبة

استخراج الأصول

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

task set-game-jak1
task set-decomp-ntscv1

بالنسبة للإصدارات الأخرى من اللعبة، ستحتاج إلى استخدام أمر -set-decomp-<VERSION> مختلف. مثال لنسخة PAL:

task set-game-jak1
task set-decomp-pal

قم بتشغيل task --list لرؤية الخيارات الأخرى المتاحة

في وقت كتابة هذا التقرير، من المتوقع أن يعمل Jak 1 فقط بشكل كامل!

الخطوة الأولى هي استخراج محتويات ملف ISO الخاص بك إلى المجلد iso_data/<game-name> . في حالة Jak 1، هذا هو iso_data/jak1 .

بمجرد الانتهاء من ذلك، افتح الوحدة الطرفية في مجلد jak-project وقم بتشغيل ما يلي:

task extract

بناء اللعبة

والخطوة التالية هي بناء اللعبة نفسها. للقيام بذلك، في نفس المحطة قم بتشغيل ما يلي:

task repl

سيتم الترحيب بك بموجه مثل هذا:

 _____             _____ _____ _____ __
|     | ___ ___ ___ |   __ |     |  _  |  |
|  |  | . | -_ |   |  |  |  |  |     |  | __
| _____ |  _ | ___ | _ | _ | _____ | _____ | __ | __ | _____ |
      | _ |
Welcome to OpenGOAL 0.8 !
Run (repl-help) for help with common commands and REPL usage.
Run (lt) to connect to the local target.

g >

قم بتشغيل ما يلي لبناء اللعبة:

g > (mi)

ملاحظة هامة! إذا كنت لا تستخدم الإصدار غير الافتراضي من اللعبة، فقد تواجه مشكلات أثناء محاولة تشغيل (mi) في هذه الخطوة. قد يتضمن خطأ المثال شيئًا مثل:

Input file iso_data/jak1/MUS/TWEAKVAL.MUS does not exist.

وذلك لأن مدخلات/مخرجات برنامج فك التحويل البرمجي تستخدم حقل gameName JSON في تكوين برنامج فك التحويل البرمجي. على سبيل المثال، إذا كنت تستخدم Jak 1 PAL، فسوف يفترض iso_data/jak1_pal و decompiler_out/jak1_pal . لذلك، يمكنك إبلاغ REPL/المترجم بهذا عبر حقل التكوين gameVersionFolder الموضح هنا

قم بتشغيل اللعبة

وأخيرا يمكن تشغيل اللعبة. افتح محطة ثانية من دليل jak-project وقم بتشغيل ما يلي:

task boot-game

يجب أن يتم تشغيل اللعبة تلقائيًا إذا تم كل شيء بشكل صحيح.

توصيل REPL باللعبة

يتيح لك توصيل REPL باللعبة فحص وتعديل التعليمات البرمجية أو البيانات أثناء تشغيل اللعبة.

للقيام بذلك، في REPL بعد نجاح (mi) ، قم بتشغيل ما يلي:

g > (lt)

إذا نجحت، فيجب أن تتغير المطالبة إلى:

gc >

على سبيل المثال، سيؤدي تشغيل ما يلي إلى طباعة بعض المعلومات الأساسية حول Jak:

gc > * target * 

تشغيل اللعبة بدون التشغيل التلقائي

يمكنك أيضًا بدء اللعبة دون التشغيل. للقيام بذلك، قم بتشغيل ما يلي في محطة واحدة

task run-game

ثم في REPL الخاص بك، قم بتشغيل ما يلي (بعد نجاح (mi) ):

g > (lt)
[Listener] Socket connected established ! (took 0 tries). Waiting for version...
Got version 0.8 OK !
[Debugger] Context: valid = true, s7 = 0x147d24, base = 0x2123000000, tid = 2438049

gc > (lg)
10836466        # xa559f2              0.0000        ("game" "kernel")

gc > (test-play)
(play :use-vis # t :init-game #f) has been called!
0        # x0              0.0000        0

gc > 

التفاعل مع اللعبة

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

تحقق من pc_debug examples ومجلدات pc ضمن goal_src للحصول على بعض الأمثلة على كود GOAL الذي كتبناه. تحتوي ملفات التصحيح التي لم يتم تحميلها تلقائيًا بواسطة المحرك على إرشادات حول كيفية تشغيلها.

نظرة عامة على المشروع الفني

هناك أربعة مكونات رئيسية للمشروع.

1. goalc - مترجم GOAL لـ x86-64
2. decompiler - المنقح لدينا
3. goal_src/ - المجلد الذي يحتوي على جميع أكواد OpenGOAL / GOOS
4. game - ويعرف أيضًا باسم وقت التشغيل المكتوب بلغة C++

دعونا نحلل كل مكون.

goalc

يُطلق على تطبيقنا لـ GOAL اسم OpenGOAL.

كل كود مصدر المترجم موجود في goalc/ . يتم التحكم في المحول البرمجي من خلال موجه يمكن استخدامه لإدخال أوامر التجميع، أو الاتصال ببرنامج GOAL قيد التشغيل للتفاعل، أو تشغيل مصحح أخطاء OpenGOAL، أو، إذا كنت متصلاً ببرنامج GOAL قيد التشغيل، يمكن استخدامه كـ REPL لـ تشغيل التعليمات البرمجية بشكل تفاعلي. بالإضافة إلى تجميع ملفات التعليمات البرمجية، يتمتع المترجم بميزات لحزم ملفات البيانات وإنشائها.

تشغيل المترجم

ملحد البيئة

إذا قمت بتثبيت task كما هو موصى به أعلاه، فيمكنك تشغيل المترجم باستخدام task repl

لينكس

لتشغيل المترجم على Linux، يوجد برنامج نصي scripts/shell/gc.sh .

ويندوز

في نظام التشغيل Windows، يوجد نص scripts/batch/gc.bat ونص scripts/batch/gc-no-lt.bat ، ولن يحاول الأخير الارتباط تلقائيًا بهدف قيد التشغيل.

decompiler

المكون الثاني للمشروع هو المنقح.

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

تشغيل برنامج فك التشفير

يجب أن يكون لديك نسخة من لعبة PS2 وأن تضع جميع الملفات من DVD داخل مجلد مطابق للعبة داخل مجلد iso_data ( jak1 for Jak 1 Black Label، وما إلى ذلك)، كما هو موضح في هذه الصورة:

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

ملحد البيئة

إذا قمت بتثبيت task كما هو موصى به أعلاه، فيمكنك تشغيل المترجم باستخدام task decomp

لينكس

للتشغيل، يمكنك استخدام scripts/shell/decomp.sh لتشغيل برنامج فك التحويل البرمجي

ويندوز

للتشغيل، يمكنك استخدام scripts/shell/decomp-jak1.bat لتشغيل برنامج فك التحويل البرمجي

goal_src/

الكود المصدري للعبة، المكتوب بلغة OpenGOAL، موجود في goal_src . يجب أن تكون جميع أكواد GOAL وGOOS موجودة في هذا المجلد.

وقت تشغيل game

العنصر الأخير هو "وقت التشغيل"، الموجود في game . هذا هو الجزء من اللعبة المكتوب بلغة C++.

في الميناء، ويشمل:

• "C Kernel"، الذي يحتوي على رابط GOAL وبعض ميزات لغة GOAL ذات المستوى المنخفض. يحتوي GOAL على تنسيق ملف كائن مرتبط ديناميكيًا ومخصص تمامًا، لذا، لكي تتمكن من تحميل كود GOAL الأول، فإنك تحتاج إلى رابط مكتوب بلغة C++. يتم أيضًا تنفيذ بعض الوظائف ذات المستوى المنخفض لتخصيص الذاكرة، والتواصل مع معالج الإدخال / الإخراج، وجدول الرموز، والسلاسل، ونظام الكتابة في لغة C، حيث إنها مطلوبة للرابط. كما أنه يستمع إلى الرسائل الواردة من المترجم ويمررها إلى اللعبة الجاري تشغيلها. يؤدي هذا أيضًا إلى تهيئة اللعبة، عن طريق تهيئة جهاز PS2، وتخصيص أكوام GOAL، وتحميل نواة GOAL من قرص DVD، وتنفيذ وظيفة مرسل kernel. هذا موجود في مجلد game/kernel . يجب أن يكون هذا أقرب ما يكون إلى اللعبة، ويجب ملاحظة جميع الاختلافات بتعليق.
• تنفيذ مكتبة سوني القياسية. يمكن لرمز GOAL استدعاء وظائف مكتبة C، واستخدم Naughty Dog بعض وظائف مكتبة Sony للوصول إلى الملفات وبطاقات الذاكرة ووحدات التحكم والتواصل مع معالج الإدخال/الإخراج المنفصل. وظائف المكتبة موجودة في game/sce . توجد تطبيقات ميزات المكتبة الخاصة بمنفذ الكمبيوتر الشخصي في game/system .
• برنامج تشغيل معالج الإدخال/الإخراج، OVERLORD. كان لدى PS2 وحدة معالجة مركزية منفصلة تسمى معالج الإدخال/الإخراج (IOP) والتي كانت متصلة مباشرة بجهاز محرك أقراص DVD وأجهزة الصوت. أنشأ Naughty Dog برنامج تشغيل مخصصًا لـ IOP الذي يتعامل مع تدفق البيانات من قرص DVD. الأمر أكثر تعقيدًا مما توقعت في البداية. إنه موجود في game/overlord . مثل نواة C، نحاول أن نجعلها قريبة قدر الإمكان من اللعبة الفعلية.
• كود الصوت. استخدم Naughty Dog مكتبة خارجية للصوت تسمى 989SND . رمز المكتبة والواجهة الخاصة بها موجودان في game/sound .
• رمز رسومات خاص بالكمبيوتر. لدينا عارض وسياق OpenGL وظيفي يمكنه إنشاء نافذة لعبة وعرض الرسومات عليها. ومع ذلك، يتم تنفيذ العارضين المحددين الذين تستخدمهم اللعبة في الغالب. وبصرف النظر عن تأثيرات ما بعد المعالجة، يتم عرض كل شيء في اللعبة. هذا موجود في game/graphics . على الرغم من أنه سيتم اتخاذ العديد من الحريات لإنجاز هذا العمل، إلا أن النتيجة النهائية يجب أن تتطابق بشكل وثيق مع اللعبة الفعلية.
• الأصول الإضافية التي يستخدمها المنفذ بطريقة ما، موجودة في game/assets . يتضمن ذلك ملفات نصية إضافية وأيقونات وما إلى ذلك.