jak project
v0.2.18
重要的
我们在 GitHub 上的存储库主要用于项目开发和跟踪活跃问题。您在这里找到的大部分信息都与出于开发目的而设置项目有关，与最终用户无关。
有关如何安装和玩游戏的设置指南，您可以观看以下视频：https://youtu.be/K84UUMnkJc4
对于与该项目有关的问题或其他信息，我们在这里有一个 Discord 可供讨论：https://discord.gg/VZbXMHXzWv
此外，您可以在项目的主网站上找到更多文档和常见问题解答：https://opengoal.dev
警告
在未提供您自己合法购买的游戏副本的情况下，请勿使用此反编译项目。我们不会分发游戏中的任何资产 - 您必须使用自己合法获得的游戏 PS2 副本。我们支持每个零售 PAL、NTSC 和 NTSC-J 版本，包括 Greatest Hits 副本。
goalcdecompilergoal_src/game运行时间该项目是将原始的 Jak 和 Daxter 以及 Jak II 移植到 PC 上。超过 98% 的游戏都是用 GOAL 编写的，GOAL 是 Naughty Dog 开发的一种定制 Lisp 语言。我们的策略是：
我们的目标是：
我们在 x86-64 上支持 Linux 和 Windows。
我们不支持、也不计划支持 ARM 架构。这意味着这不会在移动设备等设备上运行。
《Jak 1》从头到尾基本上都可以玩，但有一些错误正在不断得到解决。 Jak 2 正在开发中。
YouTube 播放列表：https://www.youtube.com/playlist?list=PLWx9T30aAT50cLnCTY1SAbt2TtWQzKfXX
为了帮助反编译，我们构建了一个反编译器，可以处理 GOAL 代码并解压游戏资源。我们手动指定函数类型和我们认为原始代码进行类型转换的位置（或者他们认为合适的位置），直到反编译器成功，然后我们通过添加注释和调整格式来清理反编译代码的输出，然后将其保存在goal_src中。
我们的反编译器是专门为处理原始 GOAL 编译器的输出而设计的。因此，当给出正确的转换时，它通常会生成可以直接输入编译器并完美运行的代码。这是我们单元测试的一部分，不断进行测试。
本自述文件的其余部分面向有兴趣从源代码构建项目的人们，通常旨在作为开发人员做出贡献。
如果这听起来不像您，而您只是想玩游戏，请参阅上面的“快速入门”部分
所有三个 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中的命令手动运行游戏。
安装软件包和初始化存储库：
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++ ..安装软件包和初始化存储库：
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安装软件包和初始化存储库：
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我们主要使用 Windows 上的 Visual Studio 进行 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文件夹，通过 Visual Studio 将项目作为 CMake 项目打开。
然后将整个项目构建为Windows Release (clang) 。您还可以按 Ctrl+Shift+B 作为“全部构建”的热键。目前我们更喜欢 Windows 上的clang而不是msvc ，尽管它应该也能工作！
注意：运行游戏需要运行 macOS Sequoia 的 Apple Silicon Mac 或 Intel Mac。
确保您安装了 Xcode 命令行工具（这会安装 Apple Clang 等工具）。如果没有，您可以运行以下命令：
xcode-select --install在 Apple Silicon 上，还必须安装 Rosetta 2：
softwareupdate --install-rosettabrew 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` )) 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"如果您不想或不能使用 Visual Studio 处理 C++ 项目，VSCode 是一个不错的选择。
建议使用clangd扩展，并要求clangd位于您的$PATH上。如果您可以在终端中成功运行clangd那么您应该可以开始了。
第一次生成 CMake 后，clangd LSP 应该能够索引项目并为您提供智能感知。
TODO - 考虑贡献文档:)
获得一款正在运行的游戏需要 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.这是因为反编译器使用反编译器配置中的
gameNameJSON 字段进行输入/输出。例如，如果您使用 Jak 1 PAL，它将假定iso_data/jak1_pal和decompiler_out/jak1_pal。因此，您可以通过此处描述的gameVersionFolder配置字段将此信息告知 REPL/编译器
最后就可以运行游戏了。从jak-project目录打开第二个终端并运行以下命令：
task boot-game如果一切都正确完成，游戏应该会自动启动。
将 REPL 连接到游戏允许您在游戏运行时检查和修改代码或数据。
为此，在成功(mi)后的 REPL 中，运行以下命令：
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 > 在图形窗口中，您可以使用句点键调出调试菜单。控制器也可以使用与原始游戏相同的映射。
查看goal_src下的pc_debug 、 examples和pc文件夹，了解我们编写的 GOAL 代码的一些示例。引擎不会自动加载的调试文件包含有关如何运行它们的说明。
该项目有四个主要组成部分。
goalc - x86-64 的 GOAL 编译器decompiler - 我们的反编译器goal_src/ - 包含所有 OpenGOAL / GOOS 代码的文件夹game - 又名用 C++ 编写的运行时让我们分解每个组件。
goalc我们的 GOAL 实现称为 OpenGOAL。
所有编译器源代码都位于goalc/中。编译器通过提示符进行控制，提示符可用于输入编译命令、连接到正在运行的 GOAL 程序进行交互、运行 OpenGOAL 调试器，或者，如果您连接到正在运行的 GOAL 程序，则可以用作 REPL交互式运行代码。除了编译代码文件之外，编译器还具有打包和构建数据文件的功能。
环境无关
如果您按照上面的建议安装了task ，则可以使用task repl运行编译器
Linux
要在Linux上运行编译器，有一个脚本scripts/shell/gc.sh 。
视窗
在Windows上，有一个scripts/batch/gc.bat脚本和一个scripts/batch/gc-no-lt.bat脚本，后者不会尝试自动附加到正在运行的目标。
decompiler该项目的第二个组件是反编译器。
反编译器将在decompiler_out文件夹中输出供人类检查的代码和其他数据。编译器不会使用此文件夹中的文件。
您必须拥有 PS2 游戏的副本，并将 DVD 中的所有文件放入iso_data文件夹中与游戏对应的文件夹中（ jak1表示 Jak 1 Black Label 等），如下图所示：
反编译器会将资源提取到assets文件夹中。编译器在构建端口时将使用这些资产，您可能希望在运行一次后关闭资产提取。
环境无关
如果您按照上面的建议安装了task ，则可以使用task decomp运行编译器
Linux
运行时可以使用scripts/shell/decomp.sh来运行反编译器
视窗
运行时可以使用scripts/shell/decomp-jak1.bat来运行反编译器
goal_src/游戏源代码是用 OpenGOAL 编写的，位于goal_src 。所有 GOAL 和 GOOS 代码都应位于此文件夹中。
game运行时间最后一个组件是“运行时”，位于game中。这是用 C++ 编写的游戏部分。
在端口中，包括：
game/kernel文件夹中。这应该尽可能接近游戏，并且所有差异都应该用注释指出。game/sce中。特定于 PC 端口的库功能的实现位于game/system中。game/overlord中。与 C 内核一样，我们尝试使其尽可能接近实际游戏。989SND第三方声音库。该库的代码及其接口位于game/sound中。game/graphics中。虽然要完成这项工作需要采取许多自由措施，但最终结果应该与实际游戏非常接近。game/assets中。其中包括额外的文本文件、图标等。
