docs: README pass, add alternative editor documentation (Zed) (#4137)

I'm switching away from visual studio (because its broken) so figured
I'd document / commit the minimum to get a working environment with the
editor I chose (Zed).

Also cleaned up the main README so it's not so verbose, link out to
secondary pages, etc.

I also deleted the Arch and Fedora dockerfiles, they were broken. The
ubuntu one still works, so i left it.

docs/project-overview.md

@@ -0,0 +1,80 @@
+# Project Overview
+
+- [Project Overview](#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)
+
+There are four main components to the project.
+
+1. `goalc` - the GOAL compiler for x86-64
+2. `decompiler` - our decompiler
+3. `goal_src/` - the folder containing all OpenGOAL / GOOS code
+4. `game` - aka the runtime written in C++
+
+Let's break down each component.
+
+## `goalc`
+
+Our implementation of GOAL is called OpenGOAL.
+
+All of the compiler source code is in `goalc/`. The compiler is controlled through a prompt which can be used to enter commands to compile, connect to a running GOAL program for interaction, run the OpenGOAL debugger, or, if you are connected to a running GOAL program, can be used as a REPL to run code interactively. In addition to compiling code files, the compiler has features to pack and build data files.
+
+### Running the compiler
+
+**Environment Agnostic**
+
+If you have installed `task` as recommended above, you can run the compiler with `task repl`
+
+**Linux**
+
+To run the compiler on Linux, there is a script `scripts/shell/gc.sh`.
+
+**Windows**
+
+On Windows, there is a `scripts/batch/gc.bat` scripts and a `scripts/batch/gc-no-lt.bat` script, the latter of which will not attempt to automatically attach to a running target.
+
+## `decompiler`
+
+The second component to the project is the decompiler.
+
+The decompiler will output code and other data intended to be inspected by humans in the `decompiler_out` folder. Files in this folder will not be used by the compiler.
+
+### Running the decompiler
+
+You must have a copy of the PS2 game and place all files from the DVD inside a folder corresponding to the game within `iso_data` folder (`jak1` for Jak 1 Black Label, etc.), as seen in this picture:
+
+![](./docs/img/iso_data-help.png)
+
+The decompiler will extract assets to the `assets` folder. These assets will be used by the compiler when building the port, and you may want to turn asset extraction off after running it once.
+
+**Environment Agnostic**
+
+If you have installed `task` as recommended above, you can run the compiler with `task decomp`
+
+**Linux**
+
+To run, you can use `scripts/shell/decomp.sh` to run the decompiler
+
+**Windows**
+
+To run, you can use `scripts/shell/decomp-jak1.bat` to run the decompiler
+
+## `goal_src/`
+
+The game source code, written in OpenGOAL, is located in `goal_src`. All GOAL and GOOS code should be in this folder.
+
+## `game` runtime
+
+The final component is the "runtime", located in `game`. This is the part of the game that's written in C++.
+
+In the port, that includes:
+- The "C Kernel", which contains the GOAL linker and some low-level GOAL language features. GOAL has a completely custom dynamically linked object file format so in order to load the first GOAL code, you need a linker written in C++. Some low-level functions for memory allocation, communicating with the I/O Processor, symbol table, strings, and the type system are also implemented in C, as these are required for the linker. It also listens for incoming messages from the compiler and passes them to the running game. This also initializes the game, by initializing the PS2 hardware, allocating the GOAL heaps, loading the GOAL kernel off of the DVD, and executing the kernel dispatcher function. This is in the `game/kernel` folder. This should be as close as possible to the game, and all differences should be noted with a comment.
+- Implementation of Sony's standard library. GOAL code can call C library functions, and Naughty Dog used some Sony library functions to access files, memory cards, controllers, and communicate with the separate I/O Processor. The library functions are in `game/sce`. Implementations of library features specific to the PC port are located in `game/system`.
+- The I/O Processor driver, OVERLORD. The PS2 had a separate CPU called the I/O Processor (IOP) that was directly connected to the DVD drive hardware and the sound hardware. Naughty Dog created a custom driver for the IOP that handled streaming data off of the DVD. It is much more complicated than I first expected. It's located in `game/overlord`. Like the C kernel, we try to keep this as close as possible to the actual game.
+- Sound code. Naughty Dog used a third party library for sound called `989SND`. Code for the library and an interface for it is located in `game/sound`.
+- PC specific graphics code. We have a functional OpenGL renderer and context that can create a game window and display graphics on it. The specific renderers used by the game however are mostly implemented. Aside from post-processing effects, everything in the game is rendered. This is located in `game/graphics`. While many liberties will be taken to make this work, the end result should very closely match the actual game.
+- Extra assets used by the port in some fashion, located in `game/assets`. These include extra text files, icons, etc.

docs/setup/dev/vs.md

@@ -0,0 +1,18 @@
+# Visual Studio
+
+## Known Issues
+
+- Later versions of 2022 have issues with intellisense when using clang
+- Recent versions of 2026 have issues with CMake where the project will endlessly build:
+  - https://developercommunity.visualstudio.com/t/Switching-git-branches-seemingly-causes-/11025316?viewtype=all
+
+## Steps
+
+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)

docs/setup/dev/vscode.md

@@ -0,0 +1,11 @@
+# VSCode
+
+If you either don't want to or cannot use Visual Studio for working with the C++ project, VSCode is a good alternative.
+
+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 :)

docs/setup/dev/zed.md

@@ -0,0 +1,25 @@
+# Zed
+
+Zed comes with out of the box C++ support via `clangd`.  The project comes with a bunch of already setup task and debug configurations.  Note that many of them depend on the usage of `task` to make them cross-OS compatible (Zed at this time doesn't allow for OS-conditional logic within the task definitions).
+
+## Recommended Extensions:
+
+- NeoCMake
+
+## Building the Project
+
+We are going to build a debug version of the project because that is most useful for development.
+
+Run the `task: spawn` command (default shortcut is `Alt-Shift-T`) and run `Generate CMake: Debug`
+
+![](/docs/img/editors/zed/zed-gen-cmake.png)
+
+Then do the same thing to run `Build Project: Debug`
+
+![](/docs/img/editors/zed/zed-build-proj.png)
+
+The project is now fully built, you can now for example -- launch the REPL (`goalc`), or the game (`gk`) and attach breakpoints.
+
+![](/docs/img/editors/zed/zed-run-example.png)
+
+![](/docs/img/editors/zed/zed-debugger.png)

docs/setup/system/docker.md

@@ -0,0 +1,21 @@
+# Docker
+
+You can use docker to compile the project as well.  Note that the Dockerfiles in the project often fall out of maitenance because no one on the main development team uses them, when this is noticed, they are deleted.
+
+```sh
+docker build -f docker/Ubuntu-20.04.Dockerfile -t jak .
+```
+
+This will create an image with all required dependencies and already built.
+
+```sh
+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 `docker 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`.

docs/setup/system/linux.md

@@ -0,0 +1,60 @@
+# Linux Environment Setup
+
+- [Linux Environment Setup](#linux-environment-setup)
+  - [Packages](#packages)
+    - [Ubuntu (20.04)](#ubuntu-2004)
+  - [Arch](#arch)
+  - [Fedora](#fedora)
+  - [Compiling and Building](#compiling-and-building)
+
+
+## Packages
+
+### Ubuntu (20.04)
+
+```sh
+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
+```
+
+## Arch
+
+```sh
+sudo pacman -S cmake libpulse base-devel nasm python libx11 libxrandr libxinerama libxcursor libxi
+yay -S go-task
+```
+
+> Note: Any later documentation that shows a `task ...` command, would instead be a `go-task ...` command.
+
+## Fedora
+
+```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
+```
+
+## Compiling and Building
+
+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++ ..
+```

docs/setup/system/macos.md

@@ -0,0 +1,34 @@
+# MacOS Environment Setup
+
+Running the game requires an Apple Silicon Mac running macOS Sequoia, or an Intel Mac.  Additionally, we currently build on macOS 15 (Sequoia) at this time.
+
+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
+```
+
+On Apple Silicon, Rosetta 2 also must be installed:
+
+```bash
+softwareupdate --install-rosetta
+```
+
+## Building for x86_64
+
+```bash
+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`))
+```
+
+## Building for ARM64 (experimental, unsupported)
+
+```bash
+brew install cmake ninja go-task clang-format
+cmake -B build --preset=Release-macos-arm64-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"`

docs/setup/system/windows.md

@@ -0,0 +1,13 @@
+# Windows Environment Setup
+
+Even if you do not intend to use Visual Studio as your IDE of choice, it is the only officially supported way of downloading the various Windows SDKs to build the C++ project.
+
+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` program and modifying the Visual Studio Installation.
+
+We recommend getting the rest of the project's dependencies via a package manager, and for that we use Scoop. Follow the steps on the bottom of the homepage [here](https://scoop.sh/) to get it installed.
+
+```sh
+scoop install git llvm nasm python task ninja cmake
+```