## Please read first > [!IMPORTANT] > Our repositories on GitHub are primarily for development of the project and tracking active issues. Most of the information you will find here pertains to setting up the project for development purposes and is not relevant to the end-user. For a setup guide on how to install and play the game there is the following video that you can check out: https://youtu.be/K84UUMnkJc4 For questions or additional information pertaining to the project, we have a Discord for discussion here: https://discord.gg/VZbXMHXzWv Additionally, you can find further documentation and answers to **frequently asked questions** on the project's main website: https://opengoal.dev > [!WARNING] > **Do not use this decompilation project without providing your own legally purchased copy of the game.** We do not distribute any assets from the game - you must use your own legitimately obtained PS2 copy of the game. We support every retail PAL, NTSC, and NTSC-J build, including Greatest Hits copies. - [Project Description](#project-description) - [Current Status](#current-status) - [Methodology](#methodology) - [Setting up a Development Environment](#setting-up-a-development-environment) - [Docker](#docker) - [Linux](#linux) - [Ubuntu (20.04)](#ubuntu-2004) - [Arch](#arch) - [Fedora](#fedora) - [Windows](#windows) - [Required Software](#required-software) - [Using Visual Studio](#using-visual-studio) - [MacOS](#macos) - [Intel Based](#intel-based) - [Apple Silicon](#apple-silicon) - [VSCode](#vscode) - [Building and Debugging](#building-and-debugging) - [Building and Running the Game](#building-and-running-the-game) - [Extract Assets](#extract-assets) - [Build the Game](#build-the-game) - [Run the Game](#run-the-game) - [Connecting the REPL to the Game](#connecting-the-repl-to-the-game) - [Running the Game Without Auto-Booting](#running-the-game-without-auto-booting) - [Interacting with the Game](#interacting-with-the-game) - [Technical Project Overview](#technical-project-overview) - [`goalc`](#goalc) - [Running the compiler](#running-the-compiler) - [`decompiler`](#decompiler) - [Running the decompiler](#running-the-decompiler) - [`goal_src/`](#goal_src) - [`game` runtime](#game-runtime) ## Project Description This project is to port the original Jak and Daxter and Jak II to PC. Over 98% of the games are written in GOAL, a custom Lisp language developed by Naughty Dog. Our strategy is: - decompile the original game code into human-readable GOAL code - develop our own compiler for GOAL and recompile game code for x86-64 - create a tool to extract game assets into formats that can be easily viewed or modified - create tools to repack game assets into a format that our port uses. Our objectives are: - make the port a "native application" on x86-64, with high performance. It shouldn't be emulated, interpreted, or transpiled. - Our GOAL compiler's performance should be around the same as unoptimized C. - try to match things from the original game and development as possible. For example, the original GOAL compiler supported live modification of code while the game is running, so we do the same, even though it's not required for just porting the game. - support modifications. It should be possible to make edits to the code without everything else breaking. We support both Linux and Windows on x86-64. > We do not support, or plan to support the ARM architecture. This means that this will not run on devices such as an M1 Mac or a mobile device. ### Current Status Jak 1 is largely playable from start to finish with a handful of bugs that are continually being ironed out. Jak 2 is in development. ![](./docs/img/promosmall1.png) ![](./docs/img/promosmall2.png) YouTube playlist: https://www.youtube.com/playlist?list=PLWx9T30aAT50cLnCTY1SAbt2TtWQzKfXX ### Methodology To help with decompiling, we've built a decompiler that can process GOAL code and unpack game assets. We manually specify function types and locations where we believe the original code had type casts (or where they feel appropriate) until the decompiler succeeds, then we clean up the output of the decompiled code by adding comments and adjusting formatting, then save it in `goal_src`. Our decompiler is designed specifically for processing the output of the original GOAL compiler. As a result, when given correct casts, it often produces code that can be directly fed into a compiler and works perfectly. This is continually tested as part of our unit tests. ## Setting up a Development Environment The remainder of this README is catered towards people interested in building the project from source, typically with the intention on contributing as a developer. If this does not sound like you and you just want to play the game, refer to the above section [Quick Start](#quick-start) ### Docker All three Linux systems are supported using Docker. Pick your supported prefered flavour of linux and build your chosen image ``` docker build -f docker/(Arch|Fedora|Ubuntu)/Dockerfile -t jak . ``` This will create an image with all required dependencies and already built. ``` docker run -v "$(pwd)"/build:/home/jak/jak-project/build -it jak bash ``` Note: If you change the content of the `build/` directory you'll need to rerun the `build` command. Alternatively you can get the build via `docker cp`. This will link your `build/` folder to the images so can validate your build or test it on an external device. Docker images can be linked into your IDE (e.g. CLion) to help with codesniffing, static analysis, run tests and continuous build. Unfortunately you'll still need task runner on your local machine to run the game or instead, manually run the game via the commands found in `Taskfile.yml`. ### Linux #### Ubuntu (20.04) Install packages and init repository: ```sh sudo apt install gcc make cmake 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 ``` Compile: ```sh cmake -B build && cmake --build build -j 8 ``` Run tests: ```sh ./test.sh ``` Note: we have found that `clang` and `lld` are significantly faster to compile and link than `gcc`, generate faster code, and have better warning messages. To install these: ```sh sudo apt install lld clang ``` and run `cmake` (in a fresh build directory) with: ```sh cmake -DCMAKE_SHARED_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .. ``` #### Arch Install packages and init repository: ```sh sudo pacman -S cmake libpulse base-devel nasm python libx11 libxrandr libxinerama libxcursor libxi yay -S go-task ``` For Arch only, replace `task` with `go-task` in the rest of the instructions. Compile: ```sh cmake -B build && cmake --build build -j 8 ``` Run tests: ```sh ./test.sh ``` #### Fedora Install packages and init repository: ```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 ``` Compile with `clang`: ```sh 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) ``` Run tests: ```sh ./test.sh ``` ### Windows #### Required Software We primarily use Visual Studio on Windows for C++ development. Download the latest community edition from [here](https://visualstudio.microsoft.com/vs/). At the time of writing this is Visual Studio 2022. You will require the `Desktop development with C++` workload. This can be selected during the installation, or after via the `Visual Studio Installer`, modifying the Visual Studio Installation. On Windows, it's recommended to use a package manager, we use Scoop. Follow the steps on the bottom of the homepage [here](https://scoop.sh/) to get it. Once Scoop is installed, run the following commands: ```sh scoop install git llvm nasm python task ``` #### Using Visual Studio Clone the repository by running the following command in your folder of choice. ```sh git clone https://github.com/open-goal/jak-project.git ``` This will create a `jak-project` folder, open the project as a CMake project via Visual Studio. ![](./docs/img/windows/open-project.png) Then build the entire project as `Windows Release (clang)`. You can also press Ctrl+Shift+B as a hotkey for Build All. We currently prefer `clang` on Windows as opposed to `msvc`, though it should work as well! ![](./docs/img/windows/release-build.png) ![](./docs/img/windows/build-all.png) ### MacOS > NOTE: At this time you can only run the game on macOS if you have an Intel processor. Ensure that you have Xcode command line tools installed (this installs things like Apple Clang). If you don't, you can run the following command: ```bash xcode-select --install ``` #### Intel Based ```bash brew install go-task/tap/go-task brew install cmake nasm ninja go-task clang-format cmake -B build --preset=Release-macos-clang cmake --build build --parallel $((`sysctl -n hw.logicalcpu`)) ``` #### Apple Silicon **Not Supported at This Time** ```bash brew install go-task/tap/go-task brew install cmake ninja go-task clang-format cmake -B build --preset=Release-macos-clang cmake --build build --parallel $((`sysctl -n hw.logicalcpu`)) ``` You may have to add the MacOS SDK to your `LIBRARY_PATH`: - `export LIBRARY_PATH="$LIBRARY_PATH:/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib"` ### VSCode If you either don't want to or cannot use Visual Studio for working with the C++ project, VSCode is a good alternatively. The `clangd` extension is [recommended](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) and requires `clangd` to be on your `$PATH`. If you can run `clangd` in a terminal successfully then you should be good to go. Once you generate your CMake for the first time the clangd LSP should be able to index the project and give you intellisense. #### Building and Debugging TODO - Consider Contributing Documentation :) ### Building and Running the Game Getting a running game involves 4 steps: 1. Build C++ tools (follow Getting Started steps above for your platform) 2. Extract assets from the game 3. Build the game 4. Run the game #### Extract Assets First, setup your settings so the following scripts know which game you are using, and which version. For the black label version of the game, run the following in a terminal: ```sh task set-game-jak1 task set-decomp-ntscv1 ``` For other versions of the game, you will need to use a different `-set-decomp-