mirror of
https://github.com/saphid/frame-control.git
synced 2026-10-25 11:01:42 +01:00
64 lines
4.1 KiB
Markdown
64 lines
4.1 KiB
Markdown
# Import an Android game backup
|
|
|
|
A SideQuest backup can contain a small APK and much larger `main.…obb` and
|
|
`patch.…obb` files. All of them belong to the same game. Installing only the APK
|
|
can leave the game unable to start because its assets are missing.
|
|
|
|
In **Add / Install → Import Android game** (or **Apps → Browse → Import Android game**), choose the base APK, any supported splits, and its OBB files together.
|
|
You can also drop them anywhere in the window. In the desktop app, dropping the
|
|
APK alone finds matching OBB files beside it; dropping a folder containing the
|
|
APK and OBBs also works. Browsers can read only the files you explicitly choose.
|
|
|
|
The import screen shows the game app and its game-data files together. **Import
|
|
game & data** installs the APK, starts its own Steam library instance, waits for
|
|
Android and the installed package, copies the OBBs, and closes the game. Open it
|
|
again from the Steam library to play. The screen explains this before import;
|
|
choosing files alone never starts a game.
|
|
|
|
Files are matched using the package inside the APK and the standard
|
|
`main|patch.<version>.<package>.obb` name, not the APK's filename. Both main and
|
|
patch files are preserved. OBB version numbers need not equal the APK's current
|
|
version code: updates can reuse older expansion files. The copy uses the existing
|
|
SHA-256 transfer check inside Android and writes to that game's own
|
|
`/sdcard/Android/obb/<package>` folder.
|
|
|
|
If no data files are selected, the screen reminds you to include any OBBs in the
|
|
backup before offering **Install game app**. An APK cannot reliably tell Frame
|
|
Control whether separate expansion files are required. Game-data files are never
|
|
silently sent to Downloads by this flow.
|
|
|
|
If setup fails, the import screen keeps the error and retry instructions visible.
|
|
The APK may already be installed, but the game is not reported ready. Import the
|
|
same backup again, or choose just its OBB files to add data to an existing install.
|
|
The importer checks the installed package and version before writing data and
|
|
closes the instance after a failed copy. Unrelated or duplicate files, running
|
|
games that would be replaced, and downgrades are rejected. Uploaded staging files
|
|
are discarded after use or cancellation; abandoned imports expire after an hour
|
|
when the importer is next used, and dead-server staging folders are swept at
|
|
startup.
|
|
|
|
This flow handles one base APK, supported native-library or asset splits, and
|
|
standard OBB files for one game at a time. It checks the package and version in
|
|
each split manifest before touching the headset. The existing Quest merger
|
|
rejects resource, code and feature splits and sets with multiple device
|
|
variants. A merged APK is re-signed; that can affect a game's licence or login.
|
|
XAPK/APKS/APKM archives use the same checks. Nested Android/data folders and
|
|
private save archives remain unsupported. PC ZIP/folder/EXE imports keep their
|
|
existing route. Quest USB and Meta library imports keep their existing workflow.
|
|
|
|
Validation covers actual APK parsing, the three-file backup layout, package
|
|
matching, sibling discovery, browser upload staging and cleanup, instance/version
|
|
guards and failure recovery with mocked headset operations. Browser verification
|
|
uses the real page and upload/inspection endpoints with simulated installation.
|
|
**Verified 2026-10-20 on a real Steam Frame**, BUILD_ID `20260925.6191901`:
|
|
F-Droid Basic 2.0.2 with two synthetic main/patch OBBs completed the automatic
|
|
install/start/copy/close sequence. Reopening its persistent instance confirmed
|
|
both SHA-256 hashes in `/sdcard/Android/obb/org.fdroid.basic`. The test app,
|
|
shortcut and instance were removed afterward, the shared device lock was
|
|
released, and the battery remained at 99%. See [device evidence](evidence/android-import/device.json).
|
|
The headset was unworn; this checks transfer and persistence, not rendering,
|
|
Resident Evil 4 gameplay, or a game that exits before data can be copied. This
|
|
flow does not change APK compatibility or remove licence checks.
|
|
The supported-split backup route was checked with generated local fixtures and
|
|
existing merger tests, not a real split game on the Frame.
|