GitHub Vita Lite - Wolff's Store
Code / README | Releases | Issues
WolffsRoom/DeltaruneVita / src / legacy / soloader

Files

TypeFilenameSize
DIRextras—
DIRlib—
DIRsource—
FILE.gitignore66 B
FILE.gitmodules115 B
FILECMakeLists.txt8681 B
FILELICENSE1167 B
FILEREADME.md11430 B

README

SoLoBoP

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

Prerequisites

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:

  1. Checks for a -config launch parameter and redirects to a separate configurator binary if present
  2. Sets CPU/GPU/bus clock frequencies to max (444/222/222/166 MHz)
  3. Initializes FIOS if USE_SCELIBC_IO is set
  4. Checks that kubridge is loaded
  5. Checks that the .so file exists
  6. Loads and relocates the .so
  7. Loads settings
  8. Resolves imports (dynlib.c)
  9. Applies patches (patch.c)
  10. Flushes caches
  11. Runs init arrays
  12. Pre-initializes vitaGL
  13. Initializes FalsoJNI
  14. Starts the controls thread

Shader support

The boilerplate hooks glShaderSource and glCompileShader to intercept GLSL shaders from the game. Depending on SHADER_FORMAT:

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

License

This software may be modified and distributed under the terms of the MIT license. See the LICENSE file for details.