# ryzellx/godhand-port architecture

> Architecture diagram of the GitHub repository ryzellx/godhand-port, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryzellx/godhand-port
- Repository: https://github.com/ryzellx/godhand-port

## Overview

God Hand is a work-in-progress native x86-64 reimplementation of a PS2 game, not an emulator; the documented goal is to run game code through EE/kernel shims and render intercepted GS traffic with Vulkan. The clearest runtime slice is GIF packets → GS state → Vulkan output, while the asset tools unpack and convert disc data. The README also documents EE CPU, DMA/VIF and RPC subsystems, but full game-runtime integration remains in progress. Relationships for unsampled code are included only where the README or source index supports them.

Main entry points: [`src/shim/sif_rpc.cpp`](https://github.com/ryzellx/godhand-port/blob/main/src/shim/sif_rpc.cpp) (SIF RPC), [`src/shim/ee_cpu.cpp`](https://github.com/ryzellx/godhand-port/blob/main/src/shim/ee_cpu.cpp) (EE CPU), [`src/shim/ee_bus.cpp`](https://github.com/ryzellx/godhand-port/blob/main/src/shim/ee_bus.cpp) (EE bus), [`src/gif/gif.cpp`](https://github.com/ryzellx/godhand-port/blob/main/src/gif/gif.cpp) (GIF parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ee["EE Runtime"]
  node_ee_cpu["EE CPU<br/>[ee_cpu.cpp]"]
  node_ee_mmi["EE MMI<br/>[ee_mmi.h]"]
  node_ee_bus["EE bus<br/>[ee_bus.cpp]"]
  node_ee_kernel["EE kernel shim<br/>[ee_kernel.cpp]"]
  node_sif_dma["SIF DMA<br/>[sif_dma.cpp]"]
  node_vif["VIF<br/>[vif.cpp]"]
end

subgraph group_graphics["Graphics Pipeline"]
  node_gif_parser["GIF parser<br/>[gif.cpp]"]
  node_gs_state["GS state<br/>[gs_state.cpp]"]
  node_slice_runner["Render slice<br/>[main.cpp]"]
  node_capture_renderer["Capture renderer<br/>[render_capture.cpp]"]
  node_vk_backend["Vulkan backend<br/>[vk_backend.cpp]"]
end

subgraph group_assets["Disc Asset Tools"]
  node_afs_tools["AFS unpacker<br/>[afs_batch.py]"]
  node_tim2_tool["TIM2 converter<br/>[tim2_to_png.py]"]
  node_adx_tool["ADX decoder<br/>[adx_decode.py]"]
  node_dat_tool["DAT parser<br/>[dat_parse.py]"]
  node_other_parser["Other parser<br/>[other_parse.py]"]
end

subgraph group_services["I/O Services"]
  node_sif_rpc["SIF RPC<br/>[sif_rpc.cpp]"]
  node_host_io["Host I/O<br/>[host_io.cpp]"]
  node_iso9660["ISO9660 reader<br/>[iso9660.cpp]"]
  node_memcard[("Memory card<br/>[memcard.cpp]")]
  node_adx_shim["ADX shim<br/>[adx.cpp]"]
end

node_game_user(("Game user"))
node_disc["God Hand disc ISO"]

node_game_user -.->|"runs game code"| node_ee_cpu
node_ee_cpu -->|"reads and writes"| node_ee_bus
node_ee_cpu -->|"uses instructions"| node_ee_mmi
node_ee_bus -->|"dispatches VIF"| node_vif
node_ee_bus -.->|"forwards GIF DMA"| node_gif_parser
node_sif_dma -->|"accesses memory"| node_ee_bus
node_sif_dma -->|"uses CPU state"| node_ee_cpu
node_sif_dma -->|"dispatches RPC"| node_sif_rpc
node_ee_kernel -->|"uses host I/O"| node_host_io
node_sif_rpc -->|"calls host services"| node_host_io
node_sif_rpc -->|"calls card service"| node_memcard
node_sif_rpc -->|"calls disc reader"| node_iso9660
node_disc -->|"unpacks assets"| node_afs_tools
node_disc -->|"provides textures"| node_tim2_tool
node_disc -->|"provides audio"| node_adx_tool
node_disc -.->|"provides containers"| node_dat_tool
node_other_parser -->|"uses parser"| node_dat_tool
node_adx_shim -.->|"shares ADX domain"| node_adx_tool
node_slice_runner -->|"parses packets"| node_gif_parser
node_slice_runner -->|"updates state"| node_gs_state
node_slice_runner -->|"renders vertices"| node_vk_backend
node_capture_renderer -->|"parses capture"| node_gif_parser
node_capture_renderer -->|"updates state"| node_gs_state
node_capture_renderer -->|"renders frame"| node_vk_backend
node_gif_parser -->|"emits actions"| node_gs_state
node_gs_state -->|"feeds render state"| node_vk_backend

click node_ee_cpu "https://github.com/ryzellx/godhand-port/blob/main/src/shim/ee_cpu.cpp"
click node_ee_mmi "https://github.com/ryzellx/godhand-port/blob/main/src/shim/ee_mmi.h"
click node_ee_bus "https://github.com/ryzellx/godhand-port/blob/main/src/shim/ee_bus.cpp"
click node_ee_kernel "https://github.com/ryzellx/godhand-port/blob/main/src/shim/ee_kernel.cpp"
click node_sif_dma "https://github.com/ryzellx/godhand-port/blob/main/src/shim/sif_dma.cpp"
click node_vif "https://github.com/ryzellx/godhand-port/blob/main/src/shim/vif.cpp"
click node_sif_rpc "https://github.com/ryzellx/godhand-port/blob/main/src/shim/sif_rpc.cpp"
click node_host_io "https://github.com/ryzellx/godhand-port/blob/main/src/shim/host_io.cpp"
click node_iso9660 "https://github.com/ryzellx/godhand-port/blob/main/src/shim/iso9660.cpp"
click node_memcard "https://github.com/ryzellx/godhand-port/blob/main/src/shim/memcard.cpp"
click node_adx_shim "https://github.com/ryzellx/godhand-port/blob/main/src/shim/adx.cpp"
click node_gif_parser "https://github.com/ryzellx/godhand-port/blob/main/src/gif/gif.cpp"
click node_gs_state "https://github.com/ryzellx/godhand-port/blob/main/src/gs/gs_state.cpp"
click node_slice_runner "https://github.com/ryzellx/godhand-port/blob/main/src/slice/main.cpp"
click node_capture_renderer "https://github.com/ryzellx/godhand-port/blob/main/src/slice/render_capture.cpp"
click node_vk_backend "https://github.com/ryzellx/godhand-port/blob/main/src/vk/vk_backend.cpp"
click node_afs_tools "https://github.com/ryzellx/godhand-port/blob/main/tools/afs_batch.py"
click node_tim2_tool "https://github.com/ryzellx/godhand-port/blob/main/tools/tim2_to_png.py"
click node_adx_tool "https://github.com/ryzellx/godhand-port/blob/main/tools/adx_decode.py"
click node_dat_tool "https://github.com/ryzellx/godhand-port/blob/main/tools/dat_parse.py"
click node_other_parser "https://github.com/ryzellx/godhand-port/blob/main/tools/other_parse.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ee_cpu,node_ee_mmi,node_ee_bus,node_ee_kernel,node_sif_dma,node_vif,node_game_user toneBlue
class node_gif_parser,node_gs_state,node_slice_runner,node_capture_renderer,node_vk_backend toneAmber
class node_afs_tools,node_tim2_tool,node_adx_tool,node_dat_tool,node_other_parser toneMint
class node_sif_rpc,node_host_io,node_iso9660,node_memcard,node_adx_shim toneRose
class node_disc toneIndigo
```

## Components

### EE Runtime

- [EE CPU](https://github.com/ryzellx/godhand-port/blob/main/src/shim/ee_cpu.cpp): `src/shim/ee_cpu.cpp`
- [EE MMI](https://github.com/ryzellx/godhand-port/blob/main/src/shim/ee_mmi.h): `src/shim/ee_mmi.h`
- [EE bus](https://github.com/ryzellx/godhand-port/blob/main/src/shim/ee_bus.cpp): `src/shim/ee_bus.cpp`
- [EE kernel shim](https://github.com/ryzellx/godhand-port/blob/main/src/shim/ee_kernel.cpp): `src/shim/ee_kernel.cpp`
- [SIF DMA](https://github.com/ryzellx/godhand-port/blob/main/src/shim/sif_dma.cpp): `src/shim/sif_dma.cpp`
- [VIF](https://github.com/ryzellx/godhand-port/blob/main/src/shim/vif.cpp): `src/shim/vif.cpp`

### Graphics Pipeline

- [GIF parser](https://github.com/ryzellx/godhand-port/blob/main/src/gif/gif.cpp): `src/gif/gif.cpp`
- [GS state](https://github.com/ryzellx/godhand-port/blob/main/src/gs/gs_state.cpp): `src/gs/gs_state.cpp`
- [Render slice](https://github.com/ryzellx/godhand-port/blob/main/src/slice/main.cpp): `src/slice/main.cpp`
- [Capture renderer](https://github.com/ryzellx/godhand-port/blob/main/src/slice/render_capture.cpp): `src/slice/render_capture.cpp`
- [Vulkan backend](https://github.com/ryzellx/godhand-port/blob/main/src/vk/vk_backend.cpp): `src/vk/vk_backend.cpp`

### Disc Asset Tools

- [AFS unpacker](https://github.com/ryzellx/godhand-port/blob/main/tools/afs_batch.py): `tools/afs_batch.py`
- [TIM2 converter](https://github.com/ryzellx/godhand-port/blob/main/tools/tim2_to_png.py): `tools/tim2_to_png.py`
- [ADX decoder](https://github.com/ryzellx/godhand-port/blob/main/tools/adx_decode.py): `tools/adx_decode.py`
- [DAT parser](https://github.com/ryzellx/godhand-port/blob/main/tools/dat_parse.py): `tools/dat_parse.py`
- [Other parser](https://github.com/ryzellx/godhand-port/blob/main/tools/other_parse.py): `tools/other_parse.py`

### I/O Services

- [SIF RPC](https://github.com/ryzellx/godhand-port/blob/main/src/shim/sif_rpc.cpp): `src/shim/sif_rpc.cpp`
- [Host I/O](https://github.com/ryzellx/godhand-port/blob/main/src/shim/host_io.cpp): `src/shim/host_io.cpp`
- [ISO9660 reader](https://github.com/ryzellx/godhand-port/blob/main/src/shim/iso9660.cpp): `src/shim/iso9660.cpp`
- [Memory card](https://github.com/ryzellx/godhand-port/blob/main/src/shim/memcard.cpp): `src/shim/memcard.cpp`
- [ADX shim](https://github.com/ryzellx/godhand-port/blob/main/src/shim/adx.cpp): `src/shim/adx.cpp`

### Other components

- **Game user**
- **God Hand disc ISO**

## Connections

- Game user → EE CPU: runs game code
- EE CPU → EE bus: reads and writes
- EE CPU → EE MMI: uses instructions (evidence: `src/shim/ee_cpu.cpp`)
- EE bus → VIF: dispatches VIF (evidence: `src/shim/ee_bus.cpp`)
- EE bus → GIF parser: forwards GIF DMA
- SIF DMA → EE bus: accesses memory (evidence: `src/shim/sif_dma.cpp`)
- SIF DMA → EE CPU: uses CPU state (evidence: `src/shim/sif_dma.cpp`)
- SIF DMA → SIF RPC: dispatches RPC (evidence: `src/shim/sif_dma.cpp`)
- EE kernel shim → Host I/O: uses host I/O (evidence: `src/shim/ee_kernel.cpp`)
- SIF RPC → Host I/O: calls host services (evidence: `src/shim/sif_rpc.cpp`)
- SIF RPC → Memory card: calls card service (evidence: `src/shim/sif_rpc.cpp`)
- SIF RPC → ISO9660 reader: calls disc reader (evidence: `src/shim/sif_rpc.cpp`)
- God Hand disc ISO → AFS unpacker: unpacks assets
- God Hand disc ISO → TIM2 converter: provides textures
- God Hand disc ISO → ADX decoder: provides audio
- God Hand disc ISO → DAT parser: provides containers
- Other parser → DAT parser: uses parser (evidence: `tools/other_parse.py`)
- ADX shim → ADX decoder: shares ADX domain
- Render slice → GIF parser: parses packets (evidence: `src/slice/main.cpp`)
- Render slice → GS state: updates state (evidence: `src/slice/main.cpp`)
- Render slice → Vulkan backend: renders vertices
- Capture renderer → GIF parser: parses capture (evidence: `src/slice/render_capture.cpp`)
- Capture renderer → GS state: updates state
- Capture renderer → Vulkan backend: renders frame
- GIF parser → GS state: emits actions
- GS state → Vulkan backend: feeds render state