Files
| Type | Filename | Size |
|---|---|---|
| DIR | extras | — |
| DIR | lib | — |
| DIR | source | — |
| FILE | .gitignore | 66 B |
| FILE | .gitmodules | 115 B |
| FILE | CMakeLists.txt | 8681 B |
| FILE | LICENSE | 1167 B |
| FILE | README.md | 11430 B |
README
What is this • Prerequisites • Getting Started • Project Structure • Notes on Internals • Build • Credits • License
solobop (so-loader boilerplate) – a starter kit for Android-to-PSVita ports based on TheFloW's so_util.
How it works
The Vita runs on an ARMv7 CPU which is also the primary architecture of Android devices from around 2012 to 2019. This means native Android game binaries (.so files) can, with the right scaffolding, be executed directly on the Vita. This project provides such scaffolding.
The core idea is similar to that of WINE: instead of emulating Android, we intercept the game's OS-facing calls and redirect them to native equivalents and/or reimplementations. The .so itself runs as-is at the CPU level.
In practice this means:
- Loading the .so into memory, applying relocations, and resolving its imports against Vita-native implementations (via so_util)
- Providing a fake JVM/JNI environment so the game can do its Java-side initialization (via FalsoJNI)
- Reimplementing Android-specific interfaces (mostly NDK-adjacent things) in ways that work on the Vita
Projects built on top of Solobop
- Baldur's Gate: Dark Alliance Port by Nevak
- Modern Combat 3 Port by gl33ntwine
- SoulCalibur Port by Rinnegatamante
- Geometry Dash Port by hatoving
- Lego Star Wars: The Complete Saga Port by gm666q
- Hill Climb Racing Port by MemoryHunter
- NBA Jam Port by elliencode
- And more.
Prerequisites
- VitaSDK-softfp installed and
VITASDKenv var pointing to it. - kubridge - kernel plugin required for RWX memory; must be installed on the target Vita.
- Familiarity with C and basic reverse engineering (you'll need to figure out what the
.soexpects). - The target game's
.soextracted from its APK.
If you're new to Vita homebrew development in general, start with Getting Started with PSVita Homebrew Development first.
Getting Started
0. Use the template (optional)
Press the big green button "Use this template" to create your own repository, if you wish. In that case, replace the repo URL with yours in the steps below.
1. Clone with submodules
git clone --recurse-submodules https://github.com/v-atamanenko/soloader-boilerplate
Or if you already cloned without them:
git submodule update --init --recursive
2. Configure CMakeLists.txt
At the top of the file, set the basics for your port:
set(VITA_APP_NAME "My Game Port")
set(VITA_TITLEID "MYGM00001") # Must be unique on the device
set(VITA_VPKNAME "my_game")
set(DATA_PATH "ux0:data/mygame/" CACHE STRING "Path to data (with trailing /)")
set(SO_PATH "${DATA_PATH}libmain.so" CACHE STRING "Path to .so")
DATA_PATH is where users place the game's data files; SO_PATH is the Android .so within that folder.
There are also a few toggleable options:
| Option | Default | Description |
|---|---|---|
USE_SCELIBC_IO |
ON | Use SceLibcBridge for IO. Recommended for most ports. |
SHADER_FORMAT |
GLSL | Shader format: GLSL, CG, or GXP. |
DUMP_COMPILED_SHADERS |
ON | Cache compiled shaders on disk (GLSL/CG only). |
3. Fill in dynlib.c
This is the heart of the port - a symbol table that maps the .so's imported symbols to their Vita-native equivalents. The boilerplate already includes a large set of common libc, math, OpenGL and other symbols. Your job is to handle whatever the specific game needs on top of that.
Run the loader, watch the logs for unresolved symbol warnings, and add them. The pattern is simple:
// in the dynlib array:
{ "someFunction", (uintptr_t)someFunction_impl },
Watch out for Bionic/newlib struct size mismatches. The most common ones (pthread, stat, dirent, etc.) are already handled in source/reimpl/ but there can be more.
4. Fill in java.c
This is the FalsoJNI implementation file - the fake JVM that the game talks to at startup (and sometimes during runtime). Start with empty arrays as they are now, run the loader, and look for [GetMethodID] / [GetFieldID] errors in the logs. For each one, implement the corresponding method or field.
See FalsoJNI's README for the full details on how to implement methods and fields.
5. Fill in patch.c
Game-specific patches go here, if needed. These typically include: - Skipping license or DRM checks - Working around code that uses unsupported Android APIs - Fixing crashes caused by platform differences
Use hook_addr() with either a named export or a raw address offset. See so_util's README for the hooking API.
6. Wire up controls in main.c
The boilerplate sets up a controls loop that polls buttons, touch, and analog sticks and calls three handler stubs:
void controls_handler_key(int32_t keycode, ControlsAction action);
void controls_handler_touch(int32_t id, float x, float y, ControlsAction action);
void controls_handler_analog(ControlsStickId which, float x, float y, ControlsAction action);
Implement these to call whatever input API the game exposes. keycode uses Android's AKEYCODE_* constants (defined in controls.h) so the game doesn't know the difference.
Also add your main rendering loop:
int (* JNI_OnLoad)(void *jvm) = (void *)so_symbol(&so_mod, "JNI_OnLoad");
JNI_OnLoad(&jvm);
gl_init();
// ... any other init the game needs
while (1) {
controls_poll();
// ... call into the .so to render a frame
gl_swap();
}
Project Structure
source/
├── main.c Entry point, main loop, controls handlers
├── dynlib.c Symbol resolution table
├── java.c FalsoJNI implementation (JNI methods and fields)
├── patch.c Game-specific hooks and patches
├── reimpl/ Android-compat reimplementations
│ ├── controls.c/h Input handling (buttons, touch, analog)
│ ├── egl.c/h EGL surface/context stubs
│ ├── errno.c/h Bionic errno translation
│ ├── io.c/h File I/O wrappers
│ ├── log.c/h Android log to Vita log bridge
│ ├── mem.c/h Memory-related wrappers
│ ├── pthr.c/h pthread struct size compatibility wrappers
│ ├── sys.c/h Misc syscall wrappers
│ ├── time64.c/h 64-bit time functions
│ └── asset_manager Android AssetManager reimplementation
└── utils/
├── dialog.c/h Fatal error dialog (SceCommonDialog)
├── glutil.c/h vitaGL init, gl_swap, shader compilation hooks
├── init.c/h soloader_init_all() / the full init sequence
├── logger.c/h Logging macros
├── settings.c/h Persistent settings (load/save/reset)
└── utils.c/h A bunch of useful helpers
lib/
├── falso_jni/ Fake JVM/JNI interface (submodule)
├── so_util/ ELF loader and hooking (submodule)
├── libc_bridge/ SceLibcBridge stubs for IO compatibility
├── fios/ FIOS2 file I/O overlay
├── kubridge/ kubridge headers (submodule)
└── sha1/ SHA-1 implementation
Notes on Internals
soloader_init_all()
Everything before main() calls into the game is handled by soloader_init_all() in source/utils/init.c. In order, it:
- Checks for a
-configlaunch parameter and redirects to a separate configurator binary if present - Sets CPU/GPU/bus clock frequencies to max (444/222/222/166 MHz)
- Initializes FIOS if
USE_SCELIBC_IOis set - Checks that kubridge is loaded
- Checks that the
.sofile exists - Loads and relocates the
.so - Loads settings
- Resolves imports (
dynlib.c) - Applies patches (
patch.c) - Flushes caches
- Runs init arrays
- Pre-initializes vitaGL
- Initializes FalsoJNI
- Starts the controls thread
Shader support
The boilerplate hooks glShaderSource and glCompileShader to intercept GLSL shaders from the game. Depending on SHADER_FORMAT:
- GLSL - passed directly to VitaGL for runtime GLSL translation (or dumping).
- CG - loaded from disk as
.cgsources if you wish to translate them manually. - GXP - loaded from disk as pre-compiled binary
.gxpfiles.
When DUMP_COMPILED_SHADERS is enabled (GLSL/CG), compiled shader binaries are written to DATA_PATH on first run and reused on subsequent launches, saving startup time.
Settings
source/utils/settings.c provides a simple persistent settings system backed by a binary file at DATA_PATH/settings.bin. The boilerplate includes two sample settings (setting_sampleSetting, setting_sampleSetting2); replace these with whatever your port actually needs.
Settings are meant to be exposed through a separate configurator app launched from the Vita's LiveArea. The boilerplate handles the launch redirect automatically but does not provide the configurator app. You can see an example of such in Mass Effect Infiltartor or BackStab HD ports.
Build
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
This produces build/VpkNameYouChose.vpk. Install it on the Vita like any other homebrew, then copy the game data to DATA_PATH.
Useful CMake targets
| Target | What it does |
|---|---|
send |
Upload eboot.bin to the Vita over FTP and relaunch |
send_kvdb |
Same, but launches with KVDB debug enabled |
dump |
Pull a crash dump from the Vita and run through vita-parse-core |
reboot |
Reboot the Vita over network |
Set PSVITAIP to your Vita's IP for these to work.
Debug build
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
Debug builds enable DEBUG_SOLOADER logging throughout the loader. You can also uncomment lines in CMakeLists.txt to enable verbose FalsoJNI logging (FALSOJNI_DEBUGLEVEL=0) or OpenGL call logging (DEBUG_OPENGL).
Credits
- TheFloW - original so-loader, gtasa_vita
- Rinnegatamante - VitaGL, numerous ports and contributions
- fgsfds - various contributions
License
This software may be modified and distributed under the terms of the MIT license. See the LICENSE file for details.
