# vita3k/vita3k-android architecture

> Architecture diagram of the GitHub repository vita3k/vita3k-android, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vita3k/vita3k-android
- Repository: https://github.com/vita3k/vita3k-android

## Overview

##### Project type and purpose
- Vita3K is an **emulator** for the PlayStation Vita, targeting Windows, Linux, macOS, and Android.
- It loads Vita homebrew and commercial games by emulating the Vita’s hardware (CPU, GPU, audio, memory, I/O, kernel), and provides a host‐side frontend (GUI) for launching and controlling games.

##### File structure
- **Top‐level directories**
- `vita3k/` – the **emulator core**, subdivided into dozens of modules (cpu, gpu, audio, net, io, kernel, modules implementations, etc.).
- `android/` – the Android‐specific launcher, input overlay, SDL glue, and Gradle project.
- `_readme/` – assets and screenshots for the repo.
- `external/` – bundled third‐party libraries (SDL2, Vulkan headers, Dynarmic, Unicorn, ffmpeg, ImGui, etc.).
- `cmake/`, `CMakeLists.txt`, `gradle/` – build and configuration scripts for desktop and Android.
- **Patterns**
- Core is organized by **subsystems** (cpu, mem, io, net, audio, gxm/gl/vk renderer, modules, gui).
- Uses **layering**:
– Emulation core (hardware abstraction)
– Vita modules implementations (Sce* services)
– Host environment abstraction (`emuenv`, `compat`, `host/dialog`)
– Frontend GUI (`gui` + SDL/ImGui)
- **Deployment files**
- Android Gradle build files, native AndroidManifest, ProGuard rules.
- AppImage scripts for Linux.

##### README for additional insights
- Emphasizes that the **core** is experimental, supports homebrew/commercial titles, and depends on many external libraries (Unicorn, Dynarmic, SDL2, Vulkan, ffmpeg).

##### Core components and relationships
a. **Frontend Layers**
- **Desktop GUI**: SDL2 + ImGui – user menu, settings, content manager.
- **Android UI**: SDL Activity + overlays (touch controls).
b. **Host Abstraction Layer** (`emuenv`, `host/dialog`, `compat`)
- Wraps OS file dialogs, window creation, threads, timers, and platform‐specific quirks.
c. **Emulator Core Subsystems**
- **CPU**: multiple implementations (Dynarmic JIT, Unicorn interpreter).
- **Memory Management**: allocator, mempool, VFS for Vita memory card and storage.
- **I/O**: controllers, touchscreen, HID, filesystem via Vita IoDevice and host FS.
- **Kernel**: threads, synchronization primitives, object store, load_self, callbacks.
- **Modules Implementation**: `vita3k/modules/Sce*` (system services reimplemented in C++).
- **Codec & Audio**: Atrac9, AAC, MP3, FFmpeg wrapper, cubeb/SDL audio backends.
- **Graphics**:
- **GXM** (native Vita GPU calls) recompiled to either OpenGL or Vulkan via `renderer`, `glutil`, `vkutil`.
- **Shader Translator** (`shader/` – GXP→SPIRV or GLSL).
d. **External Libraries** – linked into core or build system (SDL2, Vulkan SDK, Dynarmic, Unicorn, ffmpeg, ImGui, spdlog, yaml‐cpp, etc.).
e. **Storage & Packaging** – local Vita “memory card” files, AppImage/uninstaller scripts, Android assets.

##### Architectural patterns and design principles
- **Modularization**: each Vita service lives in its own folder under `vita3k/modules`.
- **Abstraction layers**: separate host OS calls from emulated environment.
- **Strategy pattern** for CPU backends (select Unicorn vs Dynarmic).
- **Factory/bridge** for renderer backends (OpenGL vs Vulkan).
- **Plugin‐style** Vita module loader (scan library_init_list, instantiate modules at runtime).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend/UI Layer
    subgraph "Frontend / UI" 
        direction TB
        DesktopGUI["Desktop GUI<br/>(SDL2 + ImGui)"]:::frontend
        AndroidUI["Android UI<br/>(SDLActivity + Overlays)"]:::frontend
    end

    %% Host Abstraction Layer
    subgraph "Host Abstraction" 
        direction TB
        EMUENV["emuenv<br/>(Windowing, Threads, Timers)"]:::host
        COMPAT["compat<br/>(Compatibility Shims)"]:::host
        HOSTDIALOG["host/dialog<br/>(File & Dialog APIs)"]:::host
    end

    %% Emulator Core Subsystems
    subgraph "Emulator Core" 
        direction TB
        CPU["CPU Subsystem<br/>(Dynarmic JIT & Unicorn)"]:::core
        MEM["Memory Management<br/>(Allocator & Mempool)"]:::core
        IO["I/O Subsystem<br/>(Controllers, VFS)"]:::core
        KERNEL["Kernel Subsystem<br/>(Threads, Sync, Object Store)"]:::core
        MODULES["Vita Modules<br/>(Sce* Services)"]:::core
        CODEC["Codec Subsystem<br/>(Atrac9, AAC, MP3, H264)"]:::core
        AUDIO_BACKEND["Audio Backends<br/>(cubeb, SDL)"]:::core
        AUDIO_GRAPH["Audio Graph (NGS)"]:::core
        GXM["GXM GPU Emulation"]:::core
        SHADER["Shader Translator<br/>(GXP→SPIR-V/GLSL)"]:::core
        RENDERER["Renderer<br/>(OpenGL & Vulkan)"]:::core
        GLUTIL["GL Utilities"]:::core
        VKUTIL["Vulkan Utilities"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies" 
        direction TB
        SDL2["SDL2"]:::external
        DYNARMIC["Dynarmic"]:::external
        UNICORN["Unicorn"]:::external
        VULKAN["Vulkan SDK"]:::external
        FFMPEG["FFmpeg"]:::external
        IMGUI["ImGui"]:::external
        SPDLOG["spdlog"]:::external
        YAMLCPP["yaml-cpp"]:::external
    end

    %% Connections: Frontend -> Host Abstraction -> Core -> External
    DesktopGUI -->|Uses| EMUENV
    DesktopGUI -->|Uses| COMPAT
    AndroidUI -->|Uses| EMUENV
    AndroidUI -->|Uses| HOSTDIALOG

    EMUENV -->|Provides| CPU
    EMUENV -->|Provides| MEM
    COMPAT -->|Provides| IO
    HOSTDIALOG -->|Provides| MODULES

    CPU -->|Fetch/Execute| MEM
    CPU -->|Syscalls| KERNEL
    IO -->|Input Events| CPU
    IO -->|File I/O| MEM
    KERNEL -->|Dispatch| MODULES
    MODULES -->|Calls| CPU

    CODEC -->|Decoded Audio| AUDIO_GRAPH
    AUDIO_GRAPH -->|Audio Samples| AUDIO_BACKEND
    GXM -->|Framebuffer| RENDERER
    SHADER -->|Translated Shaders| RENDERER
    RENDERER -->|Render Calls| EMUENV

    CPU -->|JIT| DYNARMIC
    CPU -->|Interpret| UNICORN
    CODEC -->|Demux/Decode| FFMPEG
    DesktopGUI -->|UI| IMGUI
    GXM -->|Vulkan Calls| VULKAN

    %% Click Events for component mapping
    click DesktopGUI "https://github.com/vita3k/vita3k-android/tree/android/vita3k/gui/"
    click AndroidUI "https://github.com/vita3k/vita3k-android/tree/android/android/src/main/java/org/vita3k/emulator/"
    click EMUENV "https://github.com/vita3k/vita3k-android/tree/android/vita3k/emuenv/"
    click COMPAT "https://github.com/vita3k/vita3k-android/tree/android/vita3k/compat/"
    click HOSTDIALOG "https://github.com/vita3k/vita3k-android/tree/android/vita3k/host/dialog/"
    click CPU "https://github.com/vita3k/vita3k-android/tree/android/vita3k/cpu/"
    click MEM "https://github.com/vita3k/vita3k-android/tree/android/vita3k/mem/"
    click IO "https://github.com/vita3k/vita3k-android/tree/android/vita3k/io/"
    click KERNEL "https://github.com/vita3k/vita3k-android/tree/android/vita3k/kernel/"
    click MODULES "https://github.com/vita3k/vita3k-android/tree/android/vita3k/modules/"
    click CODEC "https://github.com/vita3k/vita3k-android/tree/android/vita3k/codec/"
    click AUDIO_BACKEND "https://github.com/vita3k/vita3k-android/tree/android/vita3k/audio/"
    click AUDIO_GRAPH "https://github.com/vita3k/vita3k-android/tree/android/vita3k/ngs/"
    click GXM "https://github.com/vita3k/vita3k-android/tree/android/vita3k/gxm/"
    click RENDERER "https://github.com/vita3k/vita3k-android/tree/android/vita3k/renderer/"
    click GLUTIL "https://github.com/vita3k/vita3k-android/tree/android/vita3k/glutil/"
    click VKUTIL "https://github.com/vita3k/vita3k-android/tree/android/vita3k/vkutil/"
    click SHADER "https://github.com/vita3k/vita3k-android/tree/android/vita3k/shader/"
    click SDL2 "https://github.com/vita3k/vita3k-android/tree/android/external/"
    click DYNARMIC "https://github.com/vita3k/vita3k-android/tree/android/external/"
    click UNICORN "https://github.com/vita3k/vita3k-android/tree/android/external/"
    click VULKAN "https://github.com/vita3k/vita3k-android/tree/android/external/"
    click FFMPEG "https://github.com/vita3k/vita3k-android/tree/android/external/"
    click IMGUI "https://github.com/vita3k/vita3k-android/tree/android/external/"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px,color:#000;
    classDef host fill:#bbf,stroke:#333,stroke-width:1px,color:#000;
    classDef core fill:#bfb,stroke:#333,stroke-width:1px,color:#000;
    classDef external fill:#fbb,stroke:#333,stroke-width:1px,color:#000;
```
