# givethesourceplox/bully-nx architecture

> Architecture diagram of the GitHub repository givethesourceplox/bully-nx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/givethesourceplox/bully-nx
- Repository: https://github.com/givethesourceplox/bully-nx

## Overview

1. **What this repository is**
   - This is a Nintendo Switch homebrew wrapper/port for the **Android ARM64** release of *Bully: Anniversary Edition*.
   - It does **not** reimplement the game logic. Instead, it loads the original native game library (`libBully.so` renamed from `libGame.so`) and runs it inside a Switch-side compatibility layer.

2. **Top-level runtime boundary**
   - There are two major halves:
     - the **Switch host application** built as `bully_nx.nro`
     - the **Android game binary** loaded at runtime
   - The host process is responsible for filesystem setup, config, patching, imports, and platform emulation; the game library remains the original proprietary code.

3. **Startup and orchestration**
   - `source/main.c` and `source/main.h` appear to be the entry point and bootstrapping layer.
   - This is where the wrapper likely:
     - verifies the expected SD card layout
     - creates missing `config.txt` / `savegames/`
     - loads assets and shared libraries
     - initializes platform hooks before transferring control to the game library

4. **Game binary loading and ELF/so support**
   - `source/so_util.c` / `so_util.h`, `source/cpplib_loader.c` / `cpplib_loader.h`, and `source/imports.c` / `imports.h` form the dynamic-loading subsystem.
   - Their role is to load an Android `.so` into the Switch process, resolve symbols, and satisfy runtime dependencies that the original binary expects from Android/Linux-style environments.

5. **Android runtime patch layer**
   - `source/jni_patch.c` / `jni_patch.h` provide JNI/environment shims.
   - `source/movie_patch.c` / `movie_patch.h` and likely parts of `source/jni_patch.c` adapt behavior that the Android game expects but the Switch port cannot provide directly.
   - This layer is the key compatibility boundary between the original game library and the Switch host runtime.

6. **Platform hooks**
   - The `source/hooks/` directory contains subsystem-specific interception code:
     - `game.c` for game-side behavioral hooks
     - `opengl.c` for graphics API adaptation
     - `openal.c` for audio API adaptation
   - `source/hooks.h` likely coordinates registration of these hooks.
   - These hooks redirect or replace native calls so the Android game can run against Switch-native services and libraries.

7. **Graphics and audio adaptation**
   - OpenGL is handled as a compatibility surface rather than a direct Android graphics stack.
   - OpenAL is likewise used as the audio abstraction layer.
   - The repository expects Switch-side userspace graphics/audio support from the build environment, which is why the README calls out **SDL2**, **OpenAL**, and **Switch Mesa/Nouveau userspace libraries** as dependencies.

8. **Asset and archive handling**
   - `source/asset_archive.c` / `asset_archive.h` and `source/zip_fs.c` / `zip_fs.h` implement the game-content filesystem layer.
   - The README’s `assets/data_0.zip`, `data_1.zip`, etc. are the packaged game assets consumed by this subsystem.
   - This is a major boundary: the wrapper provides a filesystem view over archive-based Android assets instead of a normal Android APK/runtime asset manager.

9. **Configuration and persistence**
   - `source/config.c` / `config.h` manage `sdmc:/switch/bully/config.txt`.
   - The config controls runtime behavior such as screen size, clarity, shadows, filtering, and timing workaround settings.
   - `savegames/` is runtime-generated persistent storage, separating user save data from the shipped game assets.

10. **Stability, diagnostics, and error handling**
   - `source/error.c` / `error.h`, `source/util.c` / `util.h`, `source/cxx_diag.cpp`, and `source/thread_guard.cpp` support robustness and debugging.
   - `source/thread_guard.cpp` suggests thread-safety or lifecycle enforcement around the loaded game/runtime.
   - `source/cxx_diag.cpp` likely exists to surface C++ exceptions or diagnostics from the loaded library, which is important when hosting an Android C++ binary in a non-Android environment.

11. **Game-specific compatibility work**
   - `source/movie_patch.c` indicates custom handling for video/movie playback, which is often a separate compatibility problem in game ports.
   - `source/hooks/game.c` likely contains title-specific shims and workarounds for *Bully* rather than generic wrapper logic.
   - The README’s mention of temporary hacks and timing workarounds suggests this layer contains some of the most game-specific adaptation logic.

12. **Repository deployment model**
   - The expected on-device layout is simple but important to the architecture:
     - `bully_nx.nro` = Switch launcher
     - `libc++_shared.so` = Android C++ runtime dependency
     - `libBully.so` = original game library
     - `assets/` = extracted game data archives
     - `config.txt` and `savegames/` = wrapper-managed state
   - This makes the port a packaged runtime container around original game binaries and assets, not a conventional source-built game.

13. **Build/tooling boundary**
   - The project is built with **devkitA64/libnx** and uses Switch homebrew tooling.
   - The Docker-based build command in the README reinforces that the deliverable is a Switch NRO plus native runtime support libraries, not an Android APK replacement.

14. **Architectural summary**
   - The clean architecture diagram should show:
     - **SD card content** feeding config, archives, and original game binaries into
     - a **Switch wrapper runtime**
     - which applies **JNI/ELF/import patches** and **OpenGL/OpenAL/game hooks**
     - then hands execution to the **original Android ARM64 game library**
   - The wrapper owns platform adaptation and persistence; the game library owns gameplay logic.

Main entry points: [`source/main.c`](https://github.com/givethesourceplox/bully-nx/blob/master/source/main.c) (Startup), [`source/hooks.h`](https://github.com/givethesourceplox/bully-nx/blob/master/source/hooks.h) (Hooks), [`source/asset_archive.c`](https://github.com/givethesourceplox/bully-nx/blob/master/source/asset_archive.c) (Asset FS), [`source/so_util.c`](https://github.com/givethesourceplox/bully-nx/blob/master/source/so_util.c) (SO Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_switch_host["Switch Host"]
  node_entry["Startup<br/>bootstrap<br/>[main.c]"]
  node_config["Config<br/>settings<br/>[config.c]"]
  node_asset_fs[("Asset FS<br/>archive fs<br/>[asset_archive.c]")]
  node_zip_fs[("Zip FS<br/>zip backend<br/>[zip_fs.c]")]
  node_loader["SO Loader<br/>shared lib loader<br/>[so_util.c]"]
  node_cpplib["C++ Runtime<br/>c++ loader<br/>[cpplib_loader.c]"]
  node_imports["Imports<br/>symbol bindings<br/>[imports.c]"]
  node_jni_patch["JNI Patch<br/>android shim<br/>[jni_patch.c]"]
  node_movie_patch["Movie Patch<br/>media shim<br/>[movie_patch.c]"]
  node_hooks{{"Hooks<br/>intercept layer<br/>[hooks.h]"}}
  node_game_hooks["Game Hooks<br/>title fixes<br/>[game.c]"]
  node_gl_hooks["OpenGL Hooks<br/>graphics adapter<br/>[opengl.c]"]
  node_al_hooks["OpenAL Hooks<br/>audio adapter<br/>[openal.c]"]
  node_diag(("Diagnostics<br/>guards and errors<br/>[cxx_diag.cpp]"))
end

subgraph group_content["Runtime Content"]
  node_game_bin["Game Binary<br/>android arm64 so"]
  node_game_assets[("Game Assets<br/>data archives")]
  node_runtime_state["Runtime State<br/>sd-card state<br/>[config.txt]"]
end

subgraph group_build["Build Tooling"]
  node_build_system["Build<br/>devkitA64 target"]
end

node_entry -->|"load/save"| node_config
node_entry -->|"mount"| node_asset_fs
node_asset_fs -->|"backed by"| node_zip_fs
node_entry -->|"init"| node_loader
node_loader -->|"deps"| node_cpplib
node_loader -->|"resolve"| node_imports
node_entry -->|"shim"| node_jni_patch
node_entry -->|"patch"| node_movie_patch
node_entry -->|"register"| node_hooks
node_hooks -->|"includes"| node_game_hooks
node_hooks -->|"includes"| node_gl_hooks
node_hooks -->|"includes"| node_al_hooks
node_entry -->|"protect"| node_diag
node_entry -->|"handoff"| node_game_bin
node_asset_fs -->|"reads"| node_game_assets
node_config -->|"persists"| node_runtime_state
node_game_hooks -->|"intercept"| node_game_bin
node_gl_hooks -->|"redirect"| node_game_bin
node_al_hooks -->|"redirect"| node_game_bin
node_jni_patch -->|"satisfy"| node_game_bin
node_imports -->|"satisfy"| node_game_bin
node_build_system -->|"builds"| node_entry

click node_entry "https://github.com/givethesourceplox/bully-nx/blob/master/source/main.c"
click node_config "https://github.com/givethesourceplox/bully-nx/blob/master/source/config.c"
click node_asset_fs "https://github.com/givethesourceplox/bully-nx/blob/master/source/asset_archive.c"
click node_zip_fs "https://github.com/givethesourceplox/bully-nx/blob/master/source/zip_fs.c"
click node_loader "https://github.com/givethesourceplox/bully-nx/blob/master/source/so_util.c"
click node_cpplib "https://github.com/givethesourceplox/bully-nx/blob/master/source/cpplib_loader.c"
click node_imports "https://github.com/givethesourceplox/bully-nx/blob/master/source/imports.c"
click node_jni_patch "https://github.com/givethesourceplox/bully-nx/blob/master/source/jni_patch.c"
click node_movie_patch "https://github.com/givethesourceplox/bully-nx/blob/master/source/movie_patch.c"
click node_hooks "https://github.com/givethesourceplox/bully-nx/blob/master/source/hooks.h"
click node_game_hooks "https://github.com/givethesourceplox/bully-nx/blob/master/source/hooks/game.c"
click node_gl_hooks "https://github.com/givethesourceplox/bully-nx/blob/master/source/hooks/opengl.c"
click node_al_hooks "https://github.com/givethesourceplox/bully-nx/blob/master/source/hooks/openal.c"
click node_diag "https://github.com/givethesourceplox/bully-nx/blob/master/source/cxx_diag.cpp"
click node_runtime_state "https://github.com/givethesourceplox/bully-nx/blob/master/config.txt"
click node_build_system "https://github.com/givethesourceplox/bully-nx/tree/master/Makefile"

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_entry,node_config,node_asset_fs,node_zip_fs,node_loader,node_cpplib,node_imports,node_jni_patch,node_movie_patch,node_hooks,node_game_hooks,node_gl_hooks,node_al_hooks,node_diag toneBlue
class node_game_bin,node_game_assets,node_runtime_state toneAmber
class node_build_system toneMint
```

## Components

### Switch Host

Homebrew launcher, runtime glue, hooks, and compatibility layers on the Switch side.

- [Startup](https://github.com/givethesourceplox/bully-nx/blob/master/source/main.c): bootstrap · Entry point that prepares the wrapper runtime and transfers control to the loaded game library. · `source/main.c`
- [Config](https://github.com/givethesourceplox/bully-nx/blob/master/source/config.c): settings · Loads and saves wrapper options such as display, filtering, and timing behavior. · `source/config.c`
- [Asset FS](https://github.com/givethesourceplox/bully-nx/blob/master/source/asset_archive.c): archive fs · Presents packaged game archives as a filesystem view for the Android binary. · `source/asset_archive.c`
- [Zip FS](https://github.com/givethesourceplox/bully-nx/blob/master/source/zip_fs.c): zip backend · Low-level zip-backed storage used by the asset filesystem layer. · `source/zip_fs.c`
- [SO Loader](https://github.com/givethesourceplox/bully-nx/blob/master/source/so_util.c): shared lib loader · Loads the Android shared library and resolves its runtime symbols. · `source/so_util.c`
- [C++ Runtime](https://github.com/givethesourceplox/bully-nx/blob/master/source/cpplib_loader.c): c++ loader · Provides support for the shared C++ runtime dependency expected by the game binary. · `source/cpplib_loader.c`
- [Imports](https://github.com/givethesourceplox/bully-nx/blob/master/source/imports.c): symbol bindings · Supplies Android/Linux-style imported functions expected by the original binary. · `source/imports.c`
- [JNI Patch](https://github.com/givethesourceplox/bully-nx/blob/master/source/jni_patch.c): android shim · Adapts JNI and Android runtime expectations to the Switch host process. · `source/jni_patch.c`
- [Movie Patch](https://github.com/givethesourceplox/bully-nx/blob/master/source/movie_patch.c): media shim · Handles platform-specific movie and playback behavior. · `source/movie_patch.c`
- [Hooks](https://github.com/givethesourceplox/bully-nx/blob/master/source/hooks.h): intercept layer · Coordinates hook registration for graphics, audio, and game-specific behavior. · `source/hooks.h`
- [Game Hooks](https://github.com/givethesourceplox/bully-nx/blob/master/source/hooks/game.c): title fixes · Bully-specific compatibility workarounds and runtime adjustments. · `source/hooks/game.c`
- [OpenGL Hooks](https://github.com/givethesourceplox/bully-nx/blob/master/source/hooks/opengl.c): graphics adapter · Redirects graphics calls toward the Switch rendering stack. · `source/hooks/opengl.c`
- [OpenAL Hooks](https://github.com/givethesourceplox/bully-nx/blob/master/source/hooks/openal.c): audio adapter · Redirects audio calls toward the Switch audio stack. · `source/hooks/openal.c`
- [Diagnostics](https://github.com/givethesourceplox/bully-nx/blob/master/source/cxx_diag.cpp): guards and errors · Error reporting, exception surfacing, utility helpers, and thread/lifecycle guards. · `source/cxx_diag.cpp`

### Runtime Content

Original game binary, packaged assets, and SD-card persisted state consumed at runtime.

- **Game Binary**: android arm64 so · Original proprietary Bully library loaded at runtime by the wrapper.
- **Game Assets**: data archives · Packaged game content archives consumed through the asset filesystem layer.
- [Runtime State](https://github.com/givethesourceplox/bully-nx/blob/master/config.txt): sd-card state · Wrapper-managed config and save data stored on the SD card. · `config.txt`

### Build Tooling

Project build and packaging boundary for the Switch target.

- [Build](https://github.com/givethesourceplox/bully-nx/tree/master/Makefile): devkitA64 target · Switch homebrew build target and packaging boundary for the NRO deliverable. · `Makefile`

## Connections

- Startup → Config: load/save · Startup reads settings and may create or update wrapper configuration.
- Startup → Asset FS: mount · Bootstraps the asset filesystem before game execution.
- Asset FS → Zip FS: backed by · Archive filesystem is implemented on top of zip mounting support.
- Startup → SO Loader: init · Entry point initializes the shared-library loader for the game binary.
- SO Loader → C++ Runtime: deps · C++ runtime support is prepared alongside the main shared-library loader.
- SO Loader → Imports: resolve · Loader binds the imported functions that the Android binary expects.
- Startup → JNI Patch: shim · Startup applies Android/JNI compatibility shims.
- Startup → Movie Patch: patch · Startup installs movie playback compatibility handling.
- Startup → Hooks: register · Registers hook subsystems before control transfers to the game.
- Hooks → Game Hooks: includes · Title-specific compatibility workarounds are part of the hook layer.
- Hooks → OpenGL Hooks: includes · Graphics adaptation is one of the hook domains.
- Hooks → OpenAL Hooks: includes · Audio adaptation is one of the hook domains.
- Startup → Diagnostics: protect · Diagnostics and guards support robust host-side execution.
- Startup → Game Binary: handoff · After setup, the wrapper transfers execution into the original game library.
- Asset FS → Game Assets: reads · Game content is consumed from packaged data archives.
- Config → Runtime State: persists · Settings and runtime state are stored on the SD card.
- Game Hooks → Game Binary: intercept · Title-specific hooks modify behavior observed by the game library.
- OpenGL Hooks → Game Binary: redirect · Graphics calls from the game are redirected through the hook layer.
- OpenAL Hooks → Game Binary: redirect · Audio calls from the game are redirected through the hook layer.
- JNI Patch → Game Binary: satisfy · JNI patching satisfies Android-side expectations of the binary.
- Imports → Game Binary: satisfy · Imported symbols are resolved so the game can run in the Switch process.
- Build → Startup: builds · The Makefile builds the Switch launcher and its wrapper runtime.
