# itsjokerzz/ps4-bo3-customs architecture

> Architecture diagram of the GitHub repository itsjokerzz/ps4-bo3-customs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itsjokerzz/ps4-bo3-customs
- Repository: https://github.com/itsjokerzz/ps4-bo3-customs

## Overview

FFPorter converts BO3 PC custom maps into PS4 fastfiles and companion assets, while a separate PS4 SPRX makes converted user maps discoverable and provides in-game selection and input support. The main workflow is desktop selection of a PC map, CLI conversion through native loading, asset rewriting and zone/stream output, then copying the result to console storage and loading it in BO3. The graph preserves the converter’s distinct processing stages and the SPRX’s runtime features. Edges are limited to README statements and relationships visible in the provided excerpts or SOURCE INDEX; unsampled implementation details are not asserted.

Main entry points: [`Tool/src/FFPorter.Cli.T7/T7Cli.cs`](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Cli.T7/T7Cli.cs) (T7 commands), [`SPRX/main.cpp`](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/main.cpp) (SPRX startup), [`Tool/src/FFPorter.Core.T7/Port/T7ZonePort.cs`](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Port/T7ZonePort.cs) (Zone conversion), [`SPRX/t7_maps.cpp`](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/t7_maps.cpp) (Map discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_gui["Desktop UI<br/>[MainWindow.xaml.cs]"]
  node_backend["Backend process<br/>[BackendProcess.cs]"]
end

subgraph group_conversion["Map conversion"]
  node_cli["CLI routing<br/>[Program.cs]"]
  node_t7cli["T7 commands<br/>[T7Cli.cs]"]
  node_loader["Native game loaders<br/>[T7NativeTasks.cs]"]
  node_walk["Asset traversal<br/>[T7Walk.cs]"]
  node_walkindex["Walk index<br/>[T7WalkIndex.cs]"]
  node_zonebuild["Zone linking<br/>[T7ZoneBuilder.cs]"]
  node_port["Zone conversion<br/>[T7ZonePort.cs]"]
  node_assettypes["Asset catalog<br/>[T7AssetTypes.cs]"]
  node_gfx["World conversion"]
  node_shader["Shader translation"]
  node_stream["Stream conversion<br/>[T7StreamConvert.cs]"]
  node_xpak["XPak format<br/>[XPak.cs]"]
  node_sound["Sound conversion<br/>[T7SoundConvert.cs]"]
  node_soundbank["Sound bank<br/>[T7SoundBank.cs]"]
  node_movie["Movie validation<br/>[T7Movie.cs]"]
  node_transcoder["Movie transcoder"]
  node_fastfile["Fastfile format<br/>[T7FastFile.cs]"]
  node_fidelity["Fidelity reporting<br/>[T7Fidelity.cs]"]
end

subgraph group_runtime["Console runtime"]
  node_sprx["SPRX startup<br/>[main.cpp]"]
  node_maps["Map discovery<br/>[t7_maps.cpp]"]
  node_lua["Lua integration<br/>[t7_lua.cpp]"]
  node_images["Map imagery<br/>[t7_mapimages.cpp]"]
  node_keyboard["Keyboard mouse<br/>[t7_kbm.cpp]"]
  node_logging["Runtime logging<br/>[t7_log.cpp]"]
end

subgraph group_support["Shared support"]
  node_workspace["Workspace paths<br/>[Workspace.cs]"]
  node_fidelity_tracker["Fidelity tracker<br/>[FidelityTracker.cs]"]
end

node_user(("Map porter"))
node_console(("BO3 on PS4"))

node_user -->|"selects maps"| node_gui
node_gui -->|"starts conversion"| node_backend
node_backend -.->|"launches"| node_cli
node_cli -->|"routes commands"| node_t7cli
node_t7cli -->|"invokes loaders"| node_loader
node_t7cli -->|"locates files"| node_workspace
node_loader -.->|"records traversal"| node_walk
node_walkindex -->|"reads records"| node_walk
node_zonebuild -->|"uses index"| node_walkindex
node_t7cli -->|"runs conversion"| node_port
node_gfx -->|"classifies assets"| node_assettypes
node_gfx -->|"rewrites streams"| node_stream
node_stream -->|"converts entries"| node_xpak
node_sound -->|"reads banks"| node_soundbank
node_transcoder -->|"parses video"| node_movie
node_t7cli -->|"checks compatibility"| node_movie
node_port -.->|"reports fidelity"| node_fidelity
node_fidelity -->|"updates grades"| node_fidelity_tracker
node_port -.->|"writes output"| node_fastfile
node_user -->|"copies map and launches"| node_console
node_console -->|"loads plugin"| node_sprx
node_sprx -.->|"installs map hooks"| node_maps
node_maps -->|"integrates scripts"| node_lua
node_maps -->|"uses map images"| node_images
node_sprx -.->|"installs input support"| node_keyboard
node_sprx -.->|"logs runtime"| node_logging

click node_gui "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Desktop.Shared/MainWindow.xaml.cs"
click node_backend "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Desktop.Shared/Services/BackendProcess.cs"
click node_cli "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Cli/Program.cs"
click node_t7cli "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Cli.T7/T7Cli.cs"
click node_workspace "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core/Workspace.cs"
click node_loader "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Harness/T7NativeTasks.cs"
click node_walk "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Harness/T7Walk.cs"
click node_walkindex "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Link/T7WalkIndex.cs"
click node_zonebuild "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Link/T7ZoneBuilder.cs"
click node_port "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Port/T7ZonePort.cs"
click node_assettypes "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/T7AssetTypes.cs"
click node_gfx "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Port/Converters/T7GfxWorldConverter.cs"
click node_shader "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Shaders/T7DxbcTranslator.cs"
click node_stream "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Streams/T7StreamConvert.cs"
click node_xpak "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Streams/XPak.cs"
click node_sound "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Sound/T7SoundConvert.cs"
click node_soundbank "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Sound/T7SoundBank.cs"
click node_movie "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Formats/T7Movie.cs"
click node_transcoder "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Formats/T7MovieTranscoder.cs"
click node_fastfile "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/T7FastFile.cs"
click node_fidelity "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Port/T7Fidelity.cs"
click node_sprx "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/main.cpp"
click node_maps "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/t7_maps.cpp"
click node_lua "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/t7_lua.cpp"
click node_images "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/t7_mapimages.cpp"
click node_keyboard "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/t7_kbm.cpp"
click node_logging "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/t7_log.cpp"
click node_fidelity_tracker "https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core/Common/Fidelity/FidelityTracker.cs"

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_gui,node_backend toneBlue
class node_cli,node_t7cli,node_loader,node_walk,node_walkindex,node_zonebuild,node_port,node_assettypes,node_gfx,node_shader,node_stream,node_xpak,node_sound,node_soundbank,node_movie,node_transcoder,node_fastfile,node_fidelity toneAmber
class node_sprx,node_maps,node_lua,node_images,node_keyboard,node_logging toneMint
class node_workspace,node_fidelity_tracker toneRose
class node_user,node_console toneIndigo
```

## Components

### Desktop experience

- [Desktop UI](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Desktop.Shared/MainWindow.xaml.cs): `Tool/src/FFPorter.Desktop.Shared/MainWindow.xaml.cs`
- [Backend process](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Desktop.Shared/Services/BackendProcess.cs): `Tool/src/FFPorter.Desktop.Shared/Services/BackendProcess.cs`

### Map conversion

- [CLI routing](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Cli/Program.cs): `Tool/src/FFPorter.Cli/Program.cs`
- [T7 commands](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Cli.T7/T7Cli.cs): `Tool/src/FFPorter.Cli.T7/T7Cli.cs`
- [Native game loaders](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Harness/T7NativeTasks.cs): `Tool/src/FFPorter.Core.T7/Harness/T7NativeTasks.cs`
- [Asset traversal](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Harness/T7Walk.cs): `Tool/src/FFPorter.Core.T7/Harness/T7Walk.cs`
- [Walk index](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Link/T7WalkIndex.cs): `Tool/src/FFPorter.Core.T7/Link/T7WalkIndex.cs`
- [Zone linking](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Link/T7ZoneBuilder.cs): `Tool/src/FFPorter.Core.T7/Link/T7ZoneBuilder.cs`
- [Zone conversion](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Port/T7ZonePort.cs): `Tool/src/FFPorter.Core.T7/Port/T7ZonePort.cs`
- [Asset catalog](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/T7AssetTypes.cs): `Tool/src/FFPorter.Core.T7/T7AssetTypes.cs`
- [World conversion](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Port/Converters/T7GfxWorldConverter.cs): `Tool/src/FFPorter.Core.T7/Port/Converters/T7GfxWorldConverter.cs`
- [Shader translation](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Shaders/T7DxbcTranslator.cs): `Tool/src/FFPorter.Core.T7/Shaders/T7DxbcTranslator.cs`
- [Stream conversion](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Streams/T7StreamConvert.cs): `Tool/src/FFPorter.Core.T7/Streams/T7StreamConvert.cs`
- [XPak format](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Streams/XPak.cs): `Tool/src/FFPorter.Core.T7/Streams/XPak.cs`
- [Sound conversion](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Sound/T7SoundConvert.cs): `Tool/src/FFPorter.Core.T7/Sound/T7SoundConvert.cs`
- [Sound bank](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Sound/T7SoundBank.cs): `Tool/src/FFPorter.Core.T7/Sound/T7SoundBank.cs`
- [Movie validation](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Formats/T7Movie.cs): `Tool/src/FFPorter.Core.T7/Formats/T7Movie.cs`
- [Movie transcoder](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Formats/T7MovieTranscoder.cs): `Tool/src/FFPorter.Core.T7/Formats/T7MovieTranscoder.cs`
- [Fastfile format](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/T7FastFile.cs): `Tool/src/FFPorter.Core.T7/T7FastFile.cs`
- [Fidelity reporting](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core.T7/Port/T7Fidelity.cs): `Tool/src/FFPorter.Core.T7/Port/T7Fidelity.cs`

### Console runtime

- [SPRX startup](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/main.cpp): `SPRX/main.cpp`
- [Map discovery](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/t7_maps.cpp): `SPRX/t7_maps.cpp`
- [Lua integration](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/t7_lua.cpp): `SPRX/t7_lua.cpp`
- [Map imagery](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/t7_mapimages.cpp): `SPRX/t7_mapimages.cpp`
- [Keyboard mouse](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/t7_kbm.cpp): `SPRX/t7_kbm.cpp`
- [Runtime logging](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/SPRX/t7_log.cpp): `SPRX/t7_log.cpp`

### Shared support

- [Workspace paths](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core/Workspace.cs): `Tool/src/FFPorter.Core/Workspace.cs`
- [Fidelity tracker](https://github.com/itsjokerzz/ps4-bo3-customs/blob/main/Tool/src/FFPorter.Core/Common/Fidelity/FidelityTracker.cs): `Tool/src/FFPorter.Core/Common/Fidelity/FidelityTracker.cs`

### Other components

- **Map porter**
- **BO3 on PS4**

## Connections

- Map porter → Desktop UI: selects maps (evidence: `Tool/src/FFPorter.Desktop.Shared/MainWindow.xaml.cs`)
- Desktop UI → Backend process: starts conversion (evidence: `Tool/src/FFPorter.Desktop.Shared/MainWindow.xaml.cs`)
- Backend process → CLI routing: launches
- CLI routing → T7 commands: routes commands (evidence: `Tool/src/FFPorter.Cli/Program.cs`)
- T7 commands → Native game loaders: invokes loaders (evidence: `Tool/src/FFPorter.Cli.T7/T7Cli.cs`)
- T7 commands → Workspace paths: locates files (evidence: `Tool/src/FFPorter.Cli.T7/T7Cli.cs`)
- Native game loaders → Asset traversal: records traversal
- Walk index → Asset traversal: reads records (evidence: `Tool/src/FFPorter.Core.T7/Link/T7WalkIndex.cs`)
- Zone linking → Walk index: uses index (evidence: `Tool/src/FFPorter.Core.T7/Link/T7ZoneBuilder.cs`)
- T7 commands → Zone conversion: runs conversion (evidence: `Tool/src/FFPorter.Cli.T7/T7Cli.cs`)
- World conversion → Asset catalog: classifies assets (evidence: `Tool/src/FFPorter.Core.T7/Port/Converters/T7GfxWorldConverter.cs`)
- World conversion → Stream conversion: rewrites streams (evidence: `Tool/src/FFPorter.Core.T7/Port/Converters/T7GfxWorldConverter.cs`)
- Stream conversion → XPak format: converts entries (evidence: `Tool/src/FFPorter.Core.T7/Streams/T7StreamConvert.cs`)
- Sound conversion → Sound bank: reads banks (evidence: `Tool/src/FFPorter.Core.T7/Sound/T7SoundConvert.cs`)
- Movie transcoder → Movie validation: parses video (evidence: `Tool/src/FFPorter.Core.T7/Formats/T7MovieTranscoder.cs`)
- T7 commands → Movie validation: checks compatibility (evidence: `Tool/src/FFPorter.Cli.T7/T7Cli.cs`)
- Zone conversion → Fidelity reporting: reports fidelity
- Fidelity reporting → Fidelity tracker: updates grades (evidence: `Tool/src/FFPorter.Core.T7/Port/T7Fidelity.cs`)
- Zone conversion → Fastfile format: writes output
- Map porter → BO3 on PS4: copies map and launches
- BO3 on PS4 → SPRX startup: loads plugin
- SPRX startup → Map discovery: installs map hooks
- Map discovery → Lua integration: integrates scripts (evidence: `SPRX/t7_maps.cpp`)
- Map discovery → Map imagery: uses map images (evidence: `SPRX/t7_maps.cpp`)
- SPRX startup → Keyboard mouse: installs input support
- SPRX startup → Runtime logging: logs runtime
