Device run (one OBB): the mount emulation works ("OBB DataSet0.obb mounted"), then
getOBBMountPoints crashed freeing the long path string libandroid_utils allocated
(Quest's short /mnt/obb path never hits the heap). NativeFix: two branches in libgrid
1.0.0.41, window SHA-256 checked.
Games that mount their OBBs with StorageManager.mountObb (jobb FAT images) fail in
Lepton (no loop devices / device-mapper: "Can't mount OBB ... (state=21)").
- frame.obb_mount_emul (experimental): in-place dex rewrite of Codemasters'
androidutils.OBBHandler: mountOBB reports MOUNTED at once, getMountedOBBFullPath
returns the OBB's own path (Dex.rewrite_start / invoke_static / shorty)
- agent v92 unpack_obb: stdlib FAT12/16/32 reader unpacks each image into a folder
with the image's name (marker keeps the image size so uploads and data checks
still see the image), removes the image; interrupted unpacks are finished/dropped;
encrypted (jobb -k) images refused
- installer: unpacks pending images after finalize/configure, one call per image;
space check counts one image twice
- analysis obb_mount (ANALYSIS_VERSION 20), triage obb-mount-failed, PLAYBOOK row
Follow-up to "Update with a newer APK…": Linux apps take their new AppImage/archive or folder (a file or a folder
picker, like the app was added), PC VR games their new game folder. pipeline.replace_linux_app / replace_rift_game
re-run the add path (add_linux_app(replace=) / add_rift_game(replace=)): the entry keeps its package (so the Steam
shortcut), name, artwork, tags, switches and the user's recipe; a folder keeps the program chosen before if it's still
there, else FramePort picks again (and asks, for ambiguous PC VR games). A name that looks like another app's is
allowed with a heads-up.
The entry gets a new source_id, recorded in the deployment's recipe at install (no agent change):
components.source_replaced shows the Frame copy (and a PC install, pc_outdated) as outdated until then. Such an
install also re-sends same-size files changed after the last install (installer.changed_since), since uploads
otherwise skip files the Frame has with the same size. The old PC VR folder is left out of later scans
(replaced_dirs). CLI: frameport new-version <game> <path> (APKs too). Docs: INSTALL.md.
A Frame that only authorizes the user's own key refused OpenSSH, which
offered FramePort's keys alone (IdentitiesOnly), so every upload fell back
to Paramiko. The connection now records which login worked (Frame.auth):
after a login with this PC's own keys/agent OpenSSH also offers private
copies of ~/.ssh/id_* (OpenSSH skips its defaults once -i is given) and the
agent; a refused strict login is retried that way once. FramePort doesn't
add its key to the Frame for this.
New: Settings > Installing > SSH keys (library ssh.extra_keys, CLI
frameport frame ssh-keys): extra private key files for the connection and
OpenSSH, checked with Paramiko (passphrase keys: use the agent). OpenSSH
runs with -v and a refused login's error lists the keys offered and its
warnings. whoami's SID is read from bytes (non-ASCII user names).
Checked with Windows ssh.exe/sftp.exe against the Frame.
sftp escapes * ? [ inside double quotes itself, so FramePort's extra
backslash became part of the path: a folder named "... [ENG] ..." failed
every OpenSSH upload (on Linux too) and fell back to Paramiko. On Windows
the local path now goes with forward slashes: Win32-OpenSSH turned every
backslash, escapes included, into '/' ("C://Users", "/[ENG]").
Checked with Windows sftp.exe and Linux sftp against the Frame (put and
reput, sha256 match).
Deadly Delivery 1.0.30 renders (72 fps), then its lobby's Meta entitlement check
fails four times and it quits. The oculus-entitlement signature is PC VR only,
so the Quest log had no finding. New Quest signature meta-entitlement (error:
offline games may log it and play on; an online game's exit fails the test).
FramePort doesn't get around entitlement checks. docs/GAMES.md regenerated
(it was also behind on other catalog entries).
Consolidates the reusable mechanics: issue templates/labels, the
working-recipe -> catalog path (scripts/catalog_from_issue.py), handling
diagnostics zips (and the attachment-vs-placeholder gotcha), how a change
reaches users (catalog ~6 h vs code needing a release/dev build, and not
bumping a shared revision for a narrow fix), and verifying a device fix
headless. Identity/credentials stay in CLAUDE.local.md.
Doom3Quest-based ports (PreyVR, #306) draw their menu on a curved
cylinder layer submitted once per eye. The Frame's runtime has no
cylinder layers, so FrameBridge shows each as ~7 flat quad strips; a
per-eye pair is ~14 quad layers in one frame, which the runtime rejects
whole (xrEndFrame -> XR_ERROR_LAYER_INVALID, -16). The menu then stays
black while the game runs at 72 fps.
Collapse the pair: drop the right-eye cylinder and show the left eye's
strips to both eyes (the runtime composites a quad to both eyes anyway).
That halves the layer count and drops the per-eye eyeVisibility, and the
runtime accepts the frame. Only frames with per-eye cylinders change --
exactly the ones that were being rejected; mono (BOTH) cylinder games
such as 4XVR are untouched.
Verified on the dev Frame (headless): PreyVR v1.2.4 rebuilt + installed,
the menu frame now submits (one transient -16 on the first frame before
the space is locatable, then clean), 72 fps. Visual confirmation of the
menu needs the headset. Triage signature cylinder-menu-layers-rejected.
No adapter revision bump (installed games are not marked outdated).
Diagnostics only (no behaviour change): the "new layer ... usable=0"
line prints a layer's swapchain pointer, but creation logged only the
result, so a dropped layer couldn't be matched to the xrCreateSwapchain
that made (or failed to make) its swapchain. Needed to pin why a quad
"screen layer" is dropped (#306 PreyVR: menu rendered to a quad whose
swapchain FrameBridge reports as not usable).
Headset-confirmed working configs shared through the issue form:
Tea For God (#295), Ghost Town (#299), Eye of the Temple (#302),
Ocean Rift (#304), Quantum Void (#307), AugmentedEmpire (#311),
Battlemarked (#312), Demeo (#313), Homeworld: Vast Reaches (#314),
Moss (#315), Maestro (#316), Mini Motor Racing X (#317),
Operation Wolf Returns (#318), Ragnarock (#319), Smash Drums (#320),
Vendetta Forever (#321).
Quantum Void, Homeworld: Vast Reaches and Ragnarock go in as status: issues.
Version 1.2.0; catalog min_app 1.1.2 -> 1.2.0 for the entries that need this release (Shadow Point, Medal of Honor, Assassin's Creed Nexus, Journey of the Gods).
Turns on frame.unreal_skip_obb_delivery (and keeps frame.hw_video_decode) so
the fix applies without the user finding the toggle. Not device-verified (the
game is ~41 GB); status unknown, min_app 1.1.2 so only builds that recognise
the obfuscated DownloaderActivity get it.
Medal of Honor (com.Virtuos.R6DLM) keeps Epic's DownloaderActivity and log text but renames the delivery predicates
and OBBData, so expansionFilesDelivered wasn't found and frame.unreal_skip_obb_delivery was never offered. Detection
now also matches a boolean method in the package's DownloaderActivity, called from onCreate, that carries Epic's
"Checking for file : " log and calls the expansion-downloader helpers; the patch rewrites those too. ANALYSIS_VERSION
18 -> 19. Heuristics eval unchanged (10/66); no existing recipe affected.
The GLES-only stand-in left Vulkan games (UNDERDOGS: VkFormat 43, faces=6) with the runtime's refusal, so OVRPlugin
crashed in ovrp_EndFrame4. When there's no GLES context, the adapter now makes a cube-compatible VkImage (6 layers,
the requested format/size/mips, usage from the XR flags) with the app's device/queue and a private transient pool,
transitions it to COLOR_ATTACHMENT_OPTIMAL, and enumerates it as a Vulkan image; its cube layers are still dropped.
GLES behaviour is unchanged. Adapter rebuilt deterministically (both ABIs).
Pre-#263 agents left shortcuts.vdf entries with both appname and AppName; vdf_decode then refused the file
("duplicate VDF key") and Add to Steam library failed. Duplicates are now merged into one key: Steam's capitalized
spelling kept, the last value taken. Clean files still round-trip unchanged.
Only big files (>=8 MiB) used OpenSSH; games made mostly of small files stayed on Paramiko and were slow on a fast
link. native_upload.put_tar streams the same tar batch through system ssh with the paired key and pinned host key;
on any failure the install falls back to Paramiko's put_tar and logs it, and doesn't retry OpenSSH for later batches.
The job log now names the transport for each part. upload_bench gains app-small / paramiko-small comparisons.
- unreal-obb-check-stuck names frame.unreal_skip_obb_check (CRC, needs bVerifyOBBOnStartUp) and
frame.unreal_skip_obb_delivery (the Java name/size gate), and says neither is a guaranteed fix.
- cube-swapchain-refused: the stand-in is GLES-only; a Vulkan game can't use it yet.
- A game that submitted projection frames but then logged no pacing summary for 20 s (process alive) is reported as
frames-stopped (info), so a hang like SKYBOX's signature check isn't a false pass. Headless no-tracking ends are
excluded.
Play on the Steam Frame tab for a game no longer in the library wrote last_played with upsert_game, which created an
entry with only that field: listed under its package name, "Update ready", and Update / Game settings failed with
KeyError 'recipe'. library.set_fields updates existing entries only (last played, test and session results, tags,
toggles); a one-time migration drops entries made of side notes alone.
After "Waiting for app", a failure line or 20 s without a logcat line start FramePort's own reader, from the
launcher's start (logcat -T <epoch>) when the mirror never wrote, else from just before its last line. The reader
restarts from where it ended, stops when Lepton's lines come back, the container's log buffer is 16 MiB, and every
decision goes to logcat-keeper.log.
Merged main (agent 90, ANALYSIS_VERSION 17/18 after main's 15/16) and rebuilt the bridge, foveation and a32
libraries from source (deterministic, no local paths).
Fixes on top:
- a32 loader: apply DT_ANDROID_RELR relocations (Journey of the Gods crashed at start)
- VrApi bridge: vrapi_Get/SetTrackingTransform (floor-level tracking; Shadow Point's player was below the floor)
- a32: never submit an untracked default head pose (hold up to 100 ms, repair or drop); pose consistency per display
time; submit/tracking counters
- VrApi bridge: wait again when xrWaitFrame gives a display time in the refresh just submitted (the runtime rejected
the second frame with AlreadySubmitted; Journey of the Gods ran at ~120 fps on a 90 Hz display and the scene slid
and snapped back); pacing counters
- VrApi bridge: GLES re-entry polls events before reusing the kept session (a lost or exiting session is replaced, a
stopped one waits for READY)
- VrApi bridge: STAGE is the runtime's STAGE space (play-area centre and orientation, unchanged by recentering);
LOCAL_FLOOR keeps the head-based origin
- signer certificate: pick the certificate the SignerInfo names, not the first in the PKCS#7 block
- flat 32-bit apps keep the bridge (it isn't a VR-only fix)
- Frida gadget loads are stripped before translation
- launcher restart test fixed; native/.cache is no longer committed
- catalog: Shadow Point and Journey of the Gods work (headset, 2026-10-14; min_app 1.1.2)
Rebuilt libvrapi.so and libvrapi_foveation.so without the local NDK paths a worktree build left in their debug info; a test checks that no artifact contains a local path.
On Frames whose Steam drops FramePort's shortcuts.vdf entries on every restart
(GitHub #41/#42), "Add to Steam library" restarted Steam twice and then failed
with "Steam removed the new library entry again after restarting". Play's
fallback (the devkit entry, the one Steam keeps) was never reached because
_add_then_play gave up first.
After the second loss the shortcuts worker now adds the devkit entry while
Steam runs, so the game ends up in the library as "Devkit Game: <title>" and
the job succeeds. Agent v89.
- Check the Steam shortcut on every update, also when nothing else changed: a connection lost during
"Add to Steam" or Steam putting its old shortcuts.vdf back left games without a library entry. The
agent restarts Steam only when the entry really changes.
- Artwork updates for installs without a recorded artwork manifest start from a clean folder again
(an old portrait.jpg next to a new portrait.png was picked at random for the Steam grid).
- OpenSSH uploads only rename .part files that are already complete (sftp's reput refuses them, which
sent every resume to the Paramiko fallback).
- frame.tbxr_vendor revision 2: GL4ES ports get "Update on Frame" for the #191 draw fix.
- Configuration-only updates send the library's current Steam tags.
- finalize drops fingerprints and the artwork record an older app didn't send.
- set_settings: malformed numbers are refused before anything is written; int settings keep a
fractional value.
- Display diagnostics use Windows PowerShell 5.1 without pwsh's PSModulePath; window diagnostics and
the instance owner file can't stop the GUI from starting.
Holding the Frame's menu button turned 32-bit (and other VrApi bridge)
games 90-120 degrees to the side. The bridge's app space is LOCAL plus
the head's yaw at the start; the runtime's recenter moves LOCAL to the
head, so that old yaw was applied again. On a LOCAL reference space
change (and on vrapi_RecenterPose, ignored before) the origin is taken
from the head again in the first frame after the change, and VrApi's
recenter count goes up. Owner-verified with Gunjack.
The upstream patches are regenerated against OVRPort 5e7df52 (they
were missing the FOV cache changes).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Moving the mouse over the Library right after its cards were rebuilt (e.g.
the library changed at start, or a view switch) could deliver a hover event
for a card that was already off the page. Its handler called tile.update(),
Flet 1.0 raised "Container(…) Control must be added to the page first", and
an error in an event handler takes the whole app down to Flet's error
screen.
- Library grid and shelf card hover handlers use the safe C.update(tile),
which skips controls that aren't on the page any more (the convention
everywhere else in ui/)
- Settings' index: scroll_to on a page that has already left the screen
(or a closed window: "Session closed") is ignored instead of raising in
the task callback
Seen on the desktop app (Linux) while testing the a32 branch; the code is
the same on main. No automated reproduction (needs a real hover during a
redraw).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Recipes the user edited (source "user") are never re-derived, so a 32-bit
game whose recipe was saved before the bridge existed kept OVRPort and the
64-bit fixes and no bridge. Since 95c5de9 such a recipe can't be built at
all (build.check_a32), so it needed fixing by hand.
The one-time migration a32_bridge_on (library._migrate, after
quest_binary_fixes_v2, which adds frame.vk_sanitize to every Quest recipe)
goes over every 32-bit-only game once:
- adds frame.a32_bridge with the patch's own reason, unless the game's
catalog entry removes it (frame_remove)
- then engine.a32_recipe as for a bridge just turned on: OVRPort and the
64-bit fixes off, device.text_input_window for Unity, a pre-bridge
"unsupported" becomes "unknown"; the recipe stays the user's
- recipes that already have the bridge only lose what it replaces
- skips 64-bit games, PC VR / Linux entries and "install unchanged" games
It runs once per library, so a bridge the user switches off afterwards
stays off.
Tests: a user recipe from before the bridge is migrated, a catalog
frame_remove and a 64-bit game are left alone, switching the bridge off
afterwards sticks; the game page switch test now starts from a migrated
library.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Two ways a 32-bit game ended up with a recipe that couldn't work:
- Catalog entries written before the bridge existed (Journey of the Gods,
Shadow Point: "unsupported: the Frame has no AArch32") dropped the
heuristic bridge suggestion like any other patch the entry didn't choose.
- Turning the bridge on by hand kept OVRPort and the 64-bit-only fixes
(e.g. frame.vk_sanitize) on; they then failed in the build.
Now:
- A catalog entry for a 32-bit game that neither names nor removes
frame.a32_bridge counts as older than the bridge: the bridge stays in,
"unsupported" becomes "unknown" and the note says it's untested with the
bridge (quoting the old verdict). Entries that name the bridge keep their
own verdict.
- engine.a32_recipe (was _a32) also runs in pipeline.set_recipe (game page,
CLI `recipe --enable`, Game settings dialog) and before every build. When
the bridge has just been turned on it also adds what it needs (Unity:
device.text_input_window) and lifts a pre-bridge "unsupported"; later
saves only remove, so a patch the user turns off stays off.
- Which patches work on the bridge is declared per patch instead of two
lists in the engine: Patch.a32 / base.works_on_a32. OVRPort and Frame
fixes are off unless they say a32 = True (the bridge, the adapter, the
launcher entry); FrameBridge settings work unless they need the xrshim
(settings.XRSHIM_SETTINGS, the same list frame.adapter's needs_xrshim
reads now, so a new xrshim setting is excluded by itself). Such patches
are hidden for 32-bit games, also in the Game settings dialog.
- build.check_a32 refuses a 32-bit build without the bridge, or with OVRPort
or a 64-bit fix on, with a plain message instead of failing inside a tool
or producing an APK the Frame rejects (INSTALL_FAILED_NO_MATCHING_ABIS).
engine.warnings(recipe, analysis) says the same on the game page.
- The game page redraws the patch list when the bridge switch changed other
patches; its save uses C.update (warn.update raised when not mounted).
- Parity: a bridge build whose known-good APK is from before the bridge gets
"new build (no baseline)" (no alt check either) and is listed apart from
the games at parity, instead of UNEXPLAINED.
Tests: catalog verdict old vs tested, bridge turned on by hand (incl. a
later switch-off staying off), the lifted status, works_on_a32 per category,
check_a32, warnings, parity baseline + report, and the game page's switch
driven headless (no browser). Not yet built for or run on the Frame with
Journey of the Gods / Shadow Point.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sports Scramble (a 32-bit Santa Cruz build: UE 4.21, OVRPlugin on VrApi 1.21)
now plays in the headset with both controllers.
a32 bridge:
- AAsset_getBuffer: the host buffer lies above 4 GiB, so the guest gets a
copy in its own memory, freed in AAsset_close (Unreal read its
UE4CommandLine.txt this way and aborted on the NULL it got before)
- AKeyEvent_getFlags and the remaining AConfiguration getters
- Touch controllers for Quest builds: apps that require 6DoF head tracking
(uses-feature android.hardware.vr.headtracking version 1) get
assets/fp_a32_headset.txt = "quest" at conversion; the bridge then passes
both Frame controllers through (input devices, caps, state, tracking,
vibration; struct tails per VrApi minor) and sends no synthetic touchpad
events. Gear VR / Go games keep the remote emulation. A32_TOUCH=1/0
overrides.
Analysis: detect.requires_6dof, headset "quest" for such 32-bit apps
(ANALYSIS_VERSION 13).
Agent 82: Unreal restarts the app once after its first-run shader precompile
(the "optimizing" screen): it starts its own launcher activity and exits, and
Lepton ends the container with the first process. Skipping the restart or
turning it off (r.ProgramBinaryCache.RestartAndroidAfterPrecompile=0) left
the game on that screen for good. launch.sh now starts Lepton once more when
the system log shows the app's own LAUNCHER start right before its
System.exit(0) (_restart_requested; first run kept as
launch-before-restart.log; FRAMEPORT_NO_RESTART=1 turns it off).
upgrade_launchers adds it to existing launchers. Crashes, quitting from the
game and Steam's Exit game don't match.
Catalog: Sports Scramble works (owner, headset, 2026-10-13).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Profiled Gunjack and Spunky Dungeon on the Frame with perf and a new
A32_PERFMAP option (a perf map of the translated code: block bodies, exit
stubs, FPCR writes). FPCR switches turned out negligible (8 of 86k samples,
none in Gunjack). The cost was elsewhere:
- The run loop took the translation mutex on every dispatch and walked a hash
chain under it (Gunjack: jit_run 23.6 % of all samples, pthread_mutex_*
about 7 %, plus futex time in the kernel).
- The inline lookup table for indirect branches was only written at
translation, so a hot return target lost its slot for good to any block
translated later into the same slot and went through the run loop ever after.
- Every dispatch did an atomic add/sub on a counter all threads share (4.7 %).
- jit_invalidate scanned every block on each cacheflush that touched a code
page: Unity's Mono JIT does that constantly (72 % of Spunky Dungeon's main
thread in one run).
Now:
- the run loop looks blocks up without the lock (inline table first, then
the hash chains, published with release stores); the lock is only taken to
translate or to chain the exit it came from
- it refills the inline table with every block it dispatches; the refill and
invalidate_block are fenced against each other, so an invalidated block
never stays reachable
- HASH_BITS / LTAB_BITS 16 -> 18 (Gunjack translates well over 100k blocks)
- a per-thread in_jit_section flag + fence instead of the shared counter;
flush_cache sets flush_pending and waits for the flags (threads_any_in_jit)
- per-guest-page block lists: an invalidation visits only the blocks on the
affected pages and drops invalid ones from the lists on the way
Results on the Frame (same build otherwise, same launch conditions):
- Gunjack, 25-45 s after start with OVP_HEADLESS_TEST: 100,462 -> about
45,000 samples in 20 s (about 55 % less CPU), jit_run 23.6 % -> 1.6 %,
pthread_mutex_lock about 7 % -> 0.4 %
- Gunjack, 12-27 s: 72 fps in both, 11,306 -> 9,801 samples, jit_run
10.4 % -> 1.0 %
- Spunky Dungeon, 12-27 s: 72 fps in both; translated code is only 2-3 %
there, so no change. The jit_invalidate phase wasn't reproducible headless
under identical conditions: not yet measured in a played session.
- bench.c (single thread, few dispatches): unchanged.
Tests: run_programs.py (jit + interp, and A32_CACHE_KB=300), bridge harness,
fuzz.py arm-dp / t32 / arm-vfp / arm-neon (0 mismatches), pytest. Both games
pass their launch tests at 72 fps with the final build.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Gunjack (CCP, Unreal Engine 4.10 NativeActivity, VrApi, GLES) runs on the
Frame through frame.a32_bridge, confirmed in the headset by the owner
(2026-10-12). The recipe needs only frame.a32_bridge: the engine adds the
adapter and the LAUNCHER fix and turns OVRPort off, the same patch set as
the build now on the dev Frame.
Notes give the controls (right controller): trigger = fire, A = tap, stick
down = reload (swipe back), stick up = special weapon (swipe forward),
B = back. GAMES.md and the patch docs regenerated.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Gunjack (UE 4.10, Gear VR) has no separate reload or special-weapon input on
the touchpad: every swipe goes to UE4's Gesture_Flick, and
ATDPlayerController::OnFlick reads the flick angle. Below 45 or above 315
degrees (+X, a swipe towards the back of the Gear VR touchpad) it reloads;
135 to 225 degrees (-X, a swipe forward) fires the special weapon. Up and down
swipes do nothing. The bridge sent the stick's up/down as Y swipes, so in
Gunjack those directions did nothing.
For games that read their AInputQueue (NativeActivity), the right stick's
up/down now swipe along the touchpad's own X axis: up = swipe forward
(special weapon), down = swipe back (reload). Left/right are unchanged.
Unity games (AFFECTED, Spunky Dungeon) keep their mapping.
Rebuilt liba32bridge.so. Gunjack was rebuilt and installed on the dev Frame;
the headless launch test passes. Not yet tried in the headset.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Gunjack (UE 4.10, Gear VR) imports no vrapi input functions: it reads the
Gear VR touchpad and back button as Android input events from its
AInputQueue (native_app_glue). The bridge delivered its controller events
through Activity.dispatchKeyEvent, which never reaches native code, so no
control worked at all.
input.c now queues synthetic events in front of the game's AInputQueue:
- AInputQueue_attachLooper (without a callback) registers the queue;
ALooper_pollAll/pollOnce return its ident while a synthetic event waits
(ALooper_wake ends a blocking poll), AInputQueue_getEvent hands it out,
finishEvent frees it.
- The AInputQueue/AInputEvent/AKeyEvent/AMotionEvent imports are written
by hand ("!" in imports.txt) and answer for synthetic events; real
events go to libandroid as before.
- Touch positions are scaled to the activity's window size
(native_activity.c records it).
Mapping (right controller, as for AFFECTED: The Manor): trigger = hold
the touchpad, A = tap, right stick = swipe, B / left menu = back. Unity
and other Java-delivered games are unchanged. A new input_start (VR
re-entry) ends the previous poll thread.
Also: the libandroid functions the host side calls directly are weak
references again, so the PC test harness links (it broke with the
AAsset calls of the signature loader); bridge/test/run.py passes.
Headless on the Frame: "controllers: the game reads its AInputQueue",
72 fps. Not yet verified in the headset.
Gunjack (CCP, UE 4.10, Gear VR) quit after loading because AndroidMain compares
GameActivity.AndroidThunkJava_GetSignature() with the original signing
certificate, and then crashed in the Frame's runtime when it entered VR again.
a32 bridge:
- frame.a32_bridge: original_signature() = Base64.DEFAULT(SHA-1(signing
certificate DER)) of the original APK (META-INF/*.RSA|DSA|EC), stored as
assets/fp_a32_signature.txt for libUE4.so games (convert(), shared with
bridge/convert.py)
- the bridge loads it at activity creation and answers guest calls on the
method ID of AndroidThunkJava_GetSignature()Ljava/lang/String; with it
(replaces the unused hex/OpenSSL prototype)
VrApi bridge: after loading, Unreal leaves VR mode and enters it again on the
same GL context; the first frame of a second OpenXR session there aborted in
vrclient (CSharedSemaphoreLinux::WaitFromGPU from the GL binding's
PreBeginFrame). vrapi_LeaveVrMode now keeps a running GLES session and
vrapi_EnterVrMode reuses it for the same context (another context still gets
a new session; Vulkan unchanged). upstream-patches/runtime.cpp.patch updated,
libvrapi.so and liba32bridge.so rebuilt.
Verified on the Frame: headless launch test passes (72 fps after re-entry);
owner-verified in the headset.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
32-bit-only APKs (Gear VR / Oculus Go games) are no longer "unsupported": the
recipe engine suggests frame.a32_bridge, which converts the APK with the
translator bridge (convert() shared with bridge/convert.py) and ships
liba32bridge.so / liba32rt.so / liba32stub.so (native/build.py --only a32).
FramePort:
- engine._a32: overport off (OVRPort is 64-bit only; the patch ships OVRPort's
loader chain + its 32-bit platform dispatcher, overport.ensure_runtime_lib),
only frame.a32_bridge/adapter/launcher of the frame patches, 64-bit-only
adapter settings dropped, device.text_input_window for Unity; such patches
are hidden in the UI
- analysis extra.headset (ANALYSIS_VERSION 9): quest / go / gearvr ->
"Gear VR" / "Oculus Go" platform + Steam tag; catalog `headset:` field
- expects_obb ignores Unreal's OBB-inside-the-APK (assets/main.obb.png)
- catalog: com.fallen.affected, net.mobilemischief.spunkydungeon
Bridge / translator:
- VrApi 1.31 + Unity 2019 (no-config EGL contexts, LOCAL_FLOOR/STAGE tracking
space), GL buffer mappings per buffer object (fixes a ~10 MB/s guest leak and
garbled vertices), Go controller mapped to the right Frame controller
- native_app_glue imports (ALooper/AInputQueue/AConfiguration/AAsset*) for
UE4 NativeActivity games (Gunjack: runs, then quits on its own APK signature
check, which FramePort doesn't defeat)
- debugging aids: A32_BREAK, A32_STRACE to logcat, lifecycle/LeaveVrMode logs
vrapi-bridge: honours LOCAL_FLOOR/STAGE, picks a window/RGBA8 ES3 config for
no-config contexts; upstream patch updated, libvrapi.so rebuilt.
Verified on the Frame: Spunky Dungeon (Unity 2019.2, OVRPlugin 1.46) plays at
72 fps; AFFECTED The Manor still runs.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
32-bit ARM (armeabi-v7a) libraries run inside a normal 64-bit Android app on the
Steam Frame, without Android's native-bridge mechanism (no Lepton changes): each
libX.so becomes libX.a32.so plus a 64-bit stub, next to liba32bridge.so (the
translator + host glue) and liba32rt.so (a 32-bit static-PIE runtime with bionic's
libc/libm/libz/libstdc++ and a loader for the game's libraries). Guest and host
talk through hypercalls (SVC 0, r7 = 0x0a32xxxx).
Bridge (native/a32translator/bridge):
- JNI both ways: generated + hand-written JNIEnv/JavaVM, RegisterNatives and
Java_* exports through AAPCS64 -> AAPCS32 trampolines, handles for references,
arrays/strings shared when below 4 GiB, else copied
- NativeActivity glue, libandroid imports (weak, generated from imports.txt)
- GLES 3.2 + extensions + EGL: 996 functions generated from the NDK headers
- OpenSL ES output implemented in the guest, played through AAudio
- VrApi 1.x (Gear VR era) translated to the 64-bit VrApi -> OpenXR bridge,
including OVRPlugin 1.12's frame layout and its wrapped (app texture) chains
- controller input as Gear VR touchpad/back/gamepad events (UnityPlayer.injectEvent)
- convert.py: prototype of the APK conversion (FramePort patch to follow)
- PC harness with a fake JVM (32 checks, qemu or native) and an on-device test APK
Translator fixes found on the way: guest signals during blocking system calls
and in host code (Boehm GC deadlock in Unity's Mono), static-PIE start files and
PT_TLS/PT_GNU_RELRO bias, host fault chaining, stderr to logcat in bridge mode.
vrapi-bridge: OVP_HEADLESS_TEST=1 skips the wait for a tracked head (automated
tests without a worn headset); upstream-patches/runtime.cpp.patch updated.
Verified on the Frame (2026-10-10): AFFECTED The Manor (Unity 5.6 + Mono,
OVRPlugin 1.12) runs in the headset with picture and sound; controls in progress.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Interpreter + JIT for ARM, Thumb-2, VFPv4 and NEON, ARM EABI syscall
translation, signals, threads and self-modifying code. Runs static bionic
programs on the Frame. Tests: A64 encoders vs llvm-mc, a differential
instruction fuzzer and program tests against qemu-arm. Not shipped; the
README lists the steps towards running 32-bit-only APKs.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Agent 85: the game's container gets the host's /dev/input at /dev/fp-input (Lepton's /dev/input holds its own Wayland
input pipes) and the launcher's _gamepad_links worker keeps /dev/input/eventN links to Steam Input's virtual pads in
step while the game runs: controllers switched off and on again (Steam makes a new pad) work without a restart.
Android's EventHub adds and removes the links through inotify (dev Frame, uinput stand-in pad created after boot:
New device, Device removed, added again). Older launchers get the new gamepad line through upgrade_launchers.
The key layout also maps BTN_DPAD_* (a Steam Input layout that sends the D-pad as buttons, e.g. a stick set to
D-pad; the Frame's controllers have no D-pad of their own).
Pick the new APK from the game's right-click or … menu: pipeline.replace_apk checks it's the same app (refuses
another package, warns when its versionCode is older), points the entry at it and analyses it again; title, art, tags
and the user's own recipe stay, the game data stays unless the new APK's folder has its own. The game page then
offers Update on Frame.
- HostKeyChanged (paramiko BadHostKeyException): not treated as "can't reach" (jobs don't pause and retry); the
Steam Frame page explains it and offers Trust the new key (forget_host_key + reconnect); CLI frameport frame trust-key.
- Uninstall from the running app: instance.release() drops gui.lock before the data folder goes, and files still in
use are reported as left over instead of stopping the uninstall (Windows).
Both from Reddit reports (2026-10-12).
bHaptics' vest SDK asks for BLUETOOTH_CONNECT at start; on Lepton's Android 11 the permission screen takes the
foreground for a moment and the game pauses (Yupitergrad froze on its loading screen in the reporter's session).
PermissionUtils.requestBluetoothPermission returns at once (Dex.return_early). Suggested by analysis
bhaptics_permission (ANALYSIS_VERSION 14) and triage bhaptics-permission-prompt. On the dev Frame the prompt is gone;
whether it was the whole cause of the freeze is for the reporter to confirm.
Opt-in game setting (Picture -> Draw fades over the picture). Batman: Arkham Shadow fades by dimming its projection
layer with XR_KHR_composition_layer_color_scale_bias; with fade_quad=1 FrameBridge adds a black, alpha-blended quad
right after the dimmed layer (VIEW space, 1 m ahead), opacity = 1 - scale in 16 steps. One 8x8 swapchain, refilled
only when the step changes (Vulkan clear on the app's queue / GLES clear in its context); one swapchain per step hit
XR_ERROR_LIMIT_REACHED. fade_quad=2 also removes the layer's own scale. Device (headless, Batman): swapchain created,
level 16/16 on the first frame, no xrEndFrame errors, 72 fps.
The game showed a canvas being painted as its own compositor layer, which the Frame draws in front of everything.
PaintableMesh.HasCompositorLayerAvailable and ShouldUseCompositorOverlay return false (Cpp2IL), so the game's own
fallback draws the canvas in the scene (Klownicle's finding). Catalog recipe, PLAYBOOK row, test.
No Cpp2IL release reads Unity 6.5's metadata yet ("We support 23-106, got 107"), so the text-field and MSAA
fixes were skipped for Wander 0.3570 (#198). When the release reports an unsupported metadata version, the
development branch's CI build (nightly.link, as Cpp2IL's README links it) is fetched into tools/cpp2il-nightly/
and used; cached errors of that kind get one retry with it. Checked with Wander 0.3570: it reads the v107
metadata and writes TMP_InputField, OVRDisplay and OculusLoader.
Bionic allows 128 pthread keys per process. Unity 6 takes about 40, and with Gecko, Firebase and the Frame's own
libraries Wander 0.3570 ran out: Firestore aborted at start ("cannot create thread specific key for
__cxa_get_globals()", #198, #202). Opt-in patch, suggested for Unity 6 with Firebase C++ or Gecko: libunity.so's
pthread_key_create/_delete and pthread_get/setspecific imports are renamed in place to fp_tkey_* (new
elf.rename_imports: undefined symbols only, shared names refused, versions set global) and libfp_tkeys.so
(native/tlskeys) is added to its DT_NEEDED; keys without a destructor become generation-tagged slots behind one
real key, everything else keeps real keys. Approach and the first helper by Klownicle (#198), reimplemented here.
Triage signature pthread-keys-exhausted, PLAYBOOK row, Wander's recipe updated to 0.3570.
Installs the new build and leaves the game data on the Frame as it is (the CLI's --apk-only): a normal update
re-sends every OBB whose size differs from the PC's copy, which replaced OBBs changed on the Frame (mods). Asks
first; Quest games on the Frame only. Resume after a failure keeps the kind of update.
New games are checked against the drive chosen on the Frame page, installed ones against their own drive, from
the drive list fetched at connect and after install jobs (app.frame_drives). Internal storage's free space only
counts when no drive list is known. drives.target_drive/space_shortfalls are pure helpers with tests.
Flet's Linux picker asks the XDG desktop portal; window managers without one (IceWM, bare X11) answer
NameHasNoOwner and every pick raised. C.pick_files / C.pick_dir now fall back to zenity or kdialog (kdialog
first on KDE; core/pickers.py, run off the UI loop), and without either to a "type the full path" box. All
twelve pickers go through them.
Agent 83: deployment.json desktop_icon (default on); refresh_desktop_entries only updates a desktop copy that is
there; desktop_entry takes icon=. Game page: "In the app menu" and "On the desktop" switches.
- Agent 83: Valve's Lepton pastes the game's paths unquoted into shell commands (liblepton mounting.sh), so a game on
a card named "Steam Frame 512g" never got its internal storage (no saves, no SharedPreferences). The Quest launcher
now links the game folder to ~/.local/share/frameport/lepton-paths/<pkg> at every start and gives Lepton that path;
upgrade_launchers converts existing launchers, move and uninstall handle the link (#213, #214, #215, #221).
- frame.eos_keychain_loop (opt-in, offered by triage): Epic Online Services' resetKeychain returns at once, so a
keychain it can't write no longer loops forever (Beyond Sandbox, #214).
- Triage lepton-data-link-failed and eos-keychain-loop.
- CryEngine also from libAndroidLauncher.so + a .cryproject (Climb 1, #238); ANALYSIS_VERSION 12.
- Plain words: patch titles lose bracketed internals unless Show technical details is on (C.patch_title); a passed launch test just says so, how far it got shows only when it fails (C.test_line); Frame page readiness says Quest games / PC VR games and storage drops the file system (reason in a tooltip); the failure pop-up says where it stopped, that Resume continues and that saves and signing keys are kept. Engine and VR API stay on the game page; the OpenXR runtime and game launch capacity checks stay; the first start still names its tools.
- Readable dim text: TEXT_3 is #868A96 (Portal, Portal OLED) and #868B9C (Original), at least 4.5:1 on the window, sidebar, cards and raised panels (was 3.6-4.4:1); a test keeps the built-in themes there.
- Quieter empty tabs: the not-connected Files, Screenshots, Live view, Type on Frame and Monitor tabs show one sentence and Connect above a faint sketch of the tab (C.ghost_preview) instead of three feature cards; the Live view shows one Start button and no feature cards.
- The connect page has one way in: "Set up your Frame" up front (no password, nothing changes until you allow it), "Already set up?" below, the address and password behind "Connect by address…"; no 1/2/3 numbers.
- Consistency: every switch is C.switch, with the portal gradient painted under a transparent track (the real Switch keeps keyboard, focus and semantics), a dark thumb with a check when on and a grey one with a cross when off (the same size); where a patch came from is blue information, not orange; the platform filter says "Quest/Android"; the welcome screen says "Set up your Frame".
- Showcase: the live-view shot waits for "Ready when you are"; the install video clicks "Set up your Frame".
- Section labels name what you do there ("See how it works", "See what runs", "Get started") instead of 01-07; plain headlines ("What happens when you click Install on Frame", "FramePort patches the games that don't run as they are"); the hero's eyebrow is gone; nav "Install" -> "Get started" (no clash with the /install/ link page)
- Phones and narrow windows (below 1120 px) get a Menu panel instead of a hidden or wrapping nav; on phones the download buttons say "Get it on your PC"; no three.js on data saver or 2G/3G; the install log drops its detail column under 600 px
- The download page says why Windows and macOS warn on first start (self-signed) and where the SHA-256 sums are; Get started step 3 says nothing changes on the Frame until you click Allow, with a link to the script
- The app tour's screenshots and videos sit behind one disclosure; the game-maker panel shows the demo button on its own stage with the HTML behind "Show the HTML"; Compare without icon tiles, Free and open source stays the emphasized card
- Quieter motion: no cursor light, pointer-lit heading gradient or film grain; sections settle in with a 10 px rise, heading words rise without the tilt, labels decode once, a faint click ripple, a gentler hero lean, a lighter spring (--ease-spring); the warp field, the contributor dock and the gradient changelog version stay
- Readability: dim text #868a96 (4.77:1+), themed placeholders, pending install-log stages stay readable, no labels under 11px, the walkthrough shows each platform's real file and program (was "?os=linux" and FramePort.exe)
- Impeccable design-tool files (PRODUCT.md, DESIGN.md, .impeccable/) are ignored: they stay local
The title's grid-column 2 / -1 from the wide layout added an implicit second column in the one-column layout,
squeezing FramePort's text to one word per line beside the other tool's.
The search and buttons sat in an auto column that took the width and left "Libr" and one word per line for the
title. Narrow (icon rail): title, full-width search, buttons and Add games each wrap below. Tablet widths: the title
keeps its own width.
Stacked (<= 900 px) the scene sits below the hero text, so --sp measured from the page's scroll had it blurred and
enlarged by the time it reached the middle of the screen. There it now follows its own position (0 until its middle
passes 40 % of the screen height). Wide layouts keep the old mapping. The empty-space click rings and the install
badge's press ripple skip touch pointers.
Epic's DownloaderActivity checks the OBB's name and size and, with the manifest's
bVerifyOBBOnStartUp=true, CRC-checks the whole file; its screens are invisible in Lepton,
so games like Contractors seem to hang at 'Displayed .../.DownloaderActivity'. The patch
flips that manifest boolean (axml.set_meta_data_bool, one 4-byte value); analysis
unreal_verify_obb (ANALYSIS_VERSION 11) suggests it. Triage unreal-obb-check-stuck (fatal)
fails such launch tests; triage keeps system_server's lines about the game's own activities.
Game menu (Library right-click, game page "Name and artwork") and CLI 'frameport rename <pkg> "<name>"|--reset'.
The title is locked (title_locked + auto_title for the reset); rescans, Rift store matches and install links only
update auto_title; a chosen name gets no Quest/Rift twin suffix. Installed copies: the Frame's deployment.json title
changes and the shortcut is rewritten with the same appid (matched by Exe), one Steam restart; PC VR installs on this
PC keep their appid too (reinstalls and library updates now record the shortcut's real appid). A Frame that isn't
connected shows "Update name on Frame" on the game page until then or the next install.
SteamVR's auto-launch flag (SetApplicationAutoLaunch) didn't persist on the dev
Frame and a registered watch didn't start by itself. The deployment's overlay
autostart flag is now the source of truth: ensure_host_fixes installs the user
service frameport-vr-overlays.service while an installed overlay app has
autostart on (removed when none has, on uninstall/purge, or with the kill switch
~/.local/share/frameport/vr-overlays.disabled / FRAMEPORT_NO_OVERLAY_AUTOSTART).
It polls every 5 s for a new vrserver (pid + start time, remembered across agent
updates), waits until SteamVR answers, gives SteamVR's own auto-launch 15 s and
starts each autostart overlay app that isn't running (process of its folder or
GetApplicationProcessId) through LaunchApplication, in a child process with a
timeout. Log: ~/.local/share/frameport/vr-overlays.log (capped).
Godot 4.2-4.4's Kotlin code casts getSystemService(CLIPBOARD_SERVICE) with a
non-null 'as ClipboardManager'; Lepton has no clipboard service, so the app
crashes with a NullPointerException in Godot.<init> (4.3/4.4) or on first use
(4.2's lazy property). In place in classes*.dex, matched exactly: the
Intrinsics.checkNotNull before that check-cast becomes nops (older kotlinc
branch forms: the branch is fixed), and Godot's getClipboard/hasClipboard/
setClipboard return at once (Dex.return_early gains String -> "").
Analysis field godot_clipboard (ANALYSIS_VERSION 10), triage
godot-no-clipboard, PLAYBOOK row, unit tests on synthetic dex. Checked against
godot-lib 4.1.4-4.7.2 from Maven Central and the 4.3/4.4.1 export templates:
4.2.2, 4.3.0, 4.4.1 patched (D8 re-reads the result), the others untouched.
Host OpenVR overlays are composited over Lepton (Quest) games on the Frame;
Windows overlay apps register through Proton's vrclient. Detect overlay apps
(bundled .vrmanifest with is_dashboard_overlay, or OpenVR + IVROverlay +
self-registration), patch pcvr.vr_overlay and the Linux entry fields
vr_overlay/vr_overlay_autostart, agent register/unregister/launch_vr_overlay
(IVRApplications through SteamVR's libopenvr_api.so; manifest with
binary_path_linux_arm, the only key the Frame's vrserver reads). Overlay apps
skip launch tests and the Linux Steam-parent watchdog and don't count as a
running game. Probe sources in native/vroverlay_probe.
Some browsers (Flatpak ones on Linux) opened the issue form with the
title but every field empty. The issue links now also come as the
Markdown body GitHub's forms write (### sections, the recipe as a yaml
block, which catalog_from_issue.py reads) and a plain issue link with
that body, trimmed to the same URL limit. The GUI copies the body to the
clipboard when it opens the form and offers "Form empty? Open a plain
issue"; the CLI prints the plain link. A shared recipe is marked shared
only after the link was opened.
The {"modules": …} message and take_screenshot reached main with agent 73 (the ui-refresh
branch's v63-v66 numbers collided with main's). MIN_AGENT_MODULES was 65, so agents 65-72
were sent a message they ignore.
Network scans for Valve's pairing port now leave out docker/bridge/veth/tun/tap/wg/tailscale/
zerotier/vEthernet/utun-style interfaces and loopback, link-local and 100.64/10 addresses
(discovery.local_subnets, also used by the Frame search). Each scan that finds nothing doubles
the wait (30 s up to 5 min); another set of networks or opening the Frame page starts over.
Architecture: the module overview and the self-update flow are SVG diagrams
(docs/images, shown on GitHub and the site); the update details the old drawing
carried are a short list under it. FAQ: the game-folder layout is a tree block
the site draws as a real file tree (scripts/filetree.ts). Diagrams scroll sideways
on phones instead of shrinking. Docs pages on phones: the sidebar no longer kept
its desktop offset, which pushed it over the page title.
Open requests whose /wait polling stopped for more than 2 x WAIT and decided ones older than
DECIDED_KEEP are dropped (on /hello and every few seconds); the Frame page shows only open,
unexpired requests and redraws when one expires. setup.sh tells a full queue apart from an
unreachable PC. The fallback Frame name in a request is translated.
Agent v74: with an index.txt, collect_diag sends every module named in the
newest session (after the last '# start'), deduplicated, last used first,
each up to 4 MB and up to 30 MB in all, plus that session's index lines.
A reporter's GPU hang came ~10 s after the last new module, so the newest
written modules missed the culprit. Without an index (fp_spirv) nothing
changes. The bundle drops the least recently used modules last when the
zip would pass its size limit.
Cloudflare Web Analytics (cookieless) runs when the CF_ANALYTICS_TOKEN repo
variable is set. Google Analytics (GA_MEASUREMENT_ID) loads only after the
visitor clicks Allow on a small card with equal Allow/Decline buttons; the choice
is remembered, Cookie settings in the footer asks again, Decline removes the
_ga cookies and Global Privacy Control counts as Decline. Downloads are counted
as file_download events. New privacy page. Without the variables the site has
no analytics.
Conflicts kept main's features with the site branch's wording: the uninstall
dialog's new delete-saves option, hardware video decoding and last-session help,
new Game settings (plain labels), agent 73 (main's 72 plus the Take screenshot
command from v66). Main's new texts follow docs/STYLE.md (for example, patch/setting
instead of fix). Pages rebuilds on docs changes and daily; the CNAME file is
gone (the domain is a Pages setting).
Sitemap and robots.txt, complete Open Graph and Twitter tags, JSON-LD
(the app as a free SoftwareApplication with its current version; docs as
articles with breadcrumbs), a written description for each docs page, a
releases Atom feed, a 404 page, and titles that say what people search for.
/changelog/ shows every release's What's new part (the same parts the app's
changelog shows): the dev build as Coming next, the latest release large,
then a timeline; the home page shows the latest changes. Release jobs
restart the pages workflow so a new release appears on the site.
Plain words on every page, one label per action, no jargon on the home
page. The site moves to the custom domain frameport.app (CNAME, no
/frameport base); the setup line is curl -sL frameport.app/s | bash.
README is a short overview that links to the install guide; repeated
sections are said once; Share working recipe everywhere; the setup
script names the real buttons; a shorter notice, the same as the site's.
Dialogs, help texts and tooltips cut to what the user does or gets, one
name per action (Start setup, Uninstall FramePort, Update art on Frame,
Rebuild only), plain launch-test results (C.test_result), plain summaries
for every Game setting. The setup line now points at frameport.app.
Lepton's Android only gets keyboard, pointer and touch from the Wayland seat. The opt-in patch (2D apps; suggested
when the manifest declares android.hardware.gamepad or LEANBACK_LAUNCHER, ANALYSIS_VERSION 9) makes the agent record
steam_gamepad in deployment.json and give the launcher a line that exports SDL's hint
(LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD) and puts FramePort's own Podman wrapper (agent/bin/podman,
written by ensure_host_fixes, independent of the video codec) first on PATH. For the game's podman run it bind-mounts
Steam's virtual pads (uinput, 28de, gamepad buttons) at /dev/input/eventN plus an Xbox 360 key layout, then hands on
to the next Podman after itself (the codec wrapper or Podman), so both wrappers chain in either order.
FRAMEPORT_NO_GAMEPAD=1 turns it off for one start; failures keep the arguments unchanged. Verified headless on the
dev Frame with a uinput stand-in pad: Android's EventHub opens it with our layout and dispatches BUTTON_A.
Adapter setting vk_shader_dump=1: every distinct module once to files/fp_vk_shaders/<size>_<sha256>.spv, each
vkCreateShaderModule as one index.txt line (order, time), to find the shader behind a GPU hang for a vk_shader_fix.
Agent v72 collect_diag returns the newest dumped modules (Vulkan and OpenGL ES dumps); diagnostics bundle them.
Triage gpu-hang suggests the dump for the session's graphics API (FrameBridge's swapchain formats).
- Two more Frame-side worlds (envs-neon.ts): a rain-soaked neon megacity, and a Tron-like arena with light cycles.
- A game's world comes from a hash of its title (FNV-1a): with seven worlds the old palette mix gave every
title the same remainder, so one world never came up and another four times in ten.
- Download page: no round countdown ring; the countdown runs round the portal's own rim, a tunnel of rings
sinks away inside it (the rim is a masked band, so the way through stays dark).
- The trial's live view shows one eye, as the app's does.
- Headings reveal slower again.
The Steam Frame (or This PC) card gets a log button when the game's last launch test ran there: it opens the
saved log (last_test.log_path) in the launch log viewer. The showcase's demo library writes a short made-up log for
each passed test so the button shows in the docs pictures.
- Docs: search across every page (highlights where you land), definitions for jargon on hover, tables you can
filter and sort, step lists you can tick off, the tutorial video in place, zoomable pictures, section links that
copy, / [ ] keys, a reading path per goal on the overview and a mark on pages you've read.
- /download/: every Download button leads here; a countdown while the package goes through the portal, then the
download starts; a manual button stays, with version, size and SHA-256 from the release and the next steps.
- Two more Frame-side worlds: an aurora over a frozen lake, and a reef. Shared helpers moved to envkit.ts.
- Asteroids and floating islands no longer tear: corners shared by several faces move together (moveCorners).
- Built on: every project links to its page. Compare: no update row; Rift games not supported by the others.
- Headings reveal a little slower.
- The Frame side of the hero picks one of three worlds per game (grid, islands, space); the particles option is gone.
- The trial's Live view shows the same worlds through two lenses (vrscene.ts), one scene per stream, CSS fallback without WebGL.
- The trial looks more like the app: window bar, Library header/filters/shelf, game page, Frame card with now playing and power.
- The install log follows the game: package, conversion, its patches, version and note; the recipe opens under board rows.
- Calmer motion: no button drift, smaller click ring and cursor light; the gallery carousel shows the real screenshots again.
- Install tutorial video (docs/showcase/videos/install.yaml, re-recorded by record_video.py): Start setup, a card
for the setup line on the Frame (with the Developer Mode route in its note), the Frame asking and Allow clicked,
a card for what the Frame then does by itself. Showcase: the fake pairing server takes asks; hook `frame_asks`.
- Site: the Install section is a six-step walkthrough (download, Start setup, the line or Developer Mode on the
Frame, Allow, it sets itself up, add games and play), each step with a small live scene: the download unpacks,
Start setup shows the line, Konsole types it and finds FramePort, Allow moves on, the setup ticks off, a game
installs. The other ways link to /setup.
While no Frame is connected, FramePort watches for Frames in Developer Mode (Valve's devkit mDNS, else a scan every
30 s for Valve's pairing port, one entry per Frame by host key). One that already lets FramePort in is connected; one
that doesn't is offered FramePort's key through Valve's pairing every few seconds (refused at once until "Pair new
host" is open on the Frame, then the request shows in the headset; a 45 s pause after an unanswered one). So the user
only opens Pair new host and approves in the headset.
- frame/autopair.py (no Flet, callbacks), app._start_auto_pair, setting frame.auto_pair (switch on the Steam Frame
page, default on); never with FRAMEPORT_HOME or FRAMEPORT_NO_AUTO_PAIR (tests, screenshots).
- Checked on the dev Frame: found by the scan (this WSL PC doesn't hear its mDNS), FramePort's key recognized, no
pairing request sent. The headset approval path needs a Frame that doesn't know FramePort yet.
Iris returns an empty capture buffer (bytesused 0, no LAST flag, time 0) for every VP9 frame that isn't shown
(alt-ref frames split from superframes). FFmpeg's V4L2 wrapper takes any empty capture buffer during a drain
for the end of the stream, so the first hidden frame decoded after EOS ended it and the pictures still in the
driver were lost (two-pass VP9 4K: 573/600 and 617/640, always the last frames); outside a drain the empty
buffers were returned as pictures, which the component then guessed away by counting hidden frames.
build.py now patches v4l2_context.c to requeue empty capture buffers without LAST/ERROR; the drain ends at the
LAST buffer, or after a skipped empty buffer at one silent second, so it can't block. The component's
hidden-frame counting is removed. Dev Frame (Batman's container): two-pass VP9 4K 600/600 and 640/640 in
hardware with the same Y hashes as OMX.google.vp9.decoder (seek phase too), VP9 without hidden frames,
H.264 4K and HEVC 4K 600/600, VP9 surface output 600/600. Two builds (different dirs and NDK copies) give the
same libstagefrighthw.so 141de01f.
- Opt-in per game: only launchers of games whose recipe has frame.hw_video_decode (install stage, no APK change;
suggested from analysis media_codec, ANALYSIS_VERSION 8) get the codec line (deployment.json hw_video_decode,
finalize + upgrade_launchers). Games that had agent 70's per-game codec (Batman) keep it; their old
<base>/frameport-codec folders are removed afterwards. Batman: catalog + migration batman_video_patches
(frame.hw_video_decode + the hidden adapter setting surface_native, no more package check); 4XVR catalog.
- Off switch: Settings -> Installing "Hardware video decoding" (library video.hw_decode, default on) -> agent
video_codec_switch (video-codec/disabled, checked by the launcher line and the wrapper); FRAMEPORT_NO_HW_VIDEO=1
for one game.
- Connection: the codec is checked once per connection, also after a failed install; a Frame keeps the same or a
newer revision built elsewhere (logged) instead of flip-flopping between PCs.
- Wrapper: the merged media_codecs.xml goes to $XDG_RUNTIME_DIR/frameport-video, never into the version directory.
- Decoder: refused (busy) Iris sessions retry until 20 s after the plugin loaded (SteamVR's link holds a session
~12 s at game start), else 2 s, before the software fallback; VP9 capped at 4096x2304 (XML + component, larger
decodes in software); hidden VP9 frames' pictures dropped. Manifest revision 7.
- build.py builds from paths with spaces and from freshly extracted FFmpeg sources. Artifacts rebuilt here, identical
from two trees (ext4 and the NTFS repo path, two NDK copies); PR #128's own sources rebuild to its binary.
- AGENT_VERSION 71 (matches the connection's gate); triage hw-video-decoder-busy, PLAYBOOK row, docs.
INSTALL and FRAME_SETUP describe the setup line, the Allow step and the announcement; the setup command, USB cable
and Valve's pairing stay. FRAME_RUNTIME records what was checked on the dev Frame (Chromium via Steam's +, mDNS from
the Frame only on port 5353, avahi-browse not usable over SSH). README's quick start uses the line.
- /setup: the three steps (Start setup on the PC, the line on the Frame with Copy, Allow), a terminal that plays what
the script prints, what it changes, and every other way (setup command, USB cable, Valve's pairing, address).
- The site serves bootstrap/setup.sh as /s and /setup.sh (copied at build time; the workflow rebuilds when it changes).
- Install step 2 starts with a "Setup page" tab; the trial's Steam Frame page and guided tour use the same flow
(the Frame asks, matching code, Allow).
One line for every Frame and PC, served by the project page: curl -sL spoopyghosty0.github.io/frameport/s | bash.
- bootstrap/setup.sh finds FramePort (stdlib mDNS on 5353 for _frameport-pair._tcp; else the USB cable's address and
a /24 scan of /ping), asks with /hello, shows 4 digits, waits for Allow, then runs exactly the typed line's
`curl -fsS <pc>/<code> | bash`: bootstrap.sh is unchanged.
- PairingServer (no second server): /ping, /hello (max 3 open asks), /wait (long poll; code only once allowed),
decide(); announces itself over zeroconf while running (name, port, two words for this PC's key; never the code).
- Connect page: "Start setup" shows the static line, incoming asks as Allow / Deny cards (a toast elsewhere);
"Use the setup command" keeps the address + code line; USB setup unchanged.
- The app key is created under a lock (the announcement and the page asked for it at once on a first start).
- Tests: approval/deny/limits/timeouts, the code never in the announcement, setup.sh end to end against a real server
with a stub bootstrap (allowed and denied), digits match. ui_smoke --setup-url drives the page.
Checked on the dev Frame with a stub bootstrap: found by mDNS and by the scan fallback, allowed, code handed over.
- Hero, Frame side: the card is gone; the game opens into an abstract VR world (three.js, look around by dragging or
tilting the phone) or into particles that gather into a shape for the game. A TEMPORARY toggle under the scene
switches between the two for comparison. three.js loads only when the hero is on screen.
- A Steam Frame you can turn (the logo's visor, extruded) next to "Connect the Frame".
- No pictures of the app on the page: the carousel's slides are live copies of its screens (type, drop a file, end a
process, switch themes), the video tiles play short silent loops (made at build time with ffmpeg), the install
button is a live control.
- Scroll story: the hero flies toward its portal, the install log completes line by line, section lines draw in.
- Everything reacts: a portal light follows the pointer, clicks on empty space ripple blue then orange, headings rise
in word by word and light up under the pointer, labels unscramble, numbers count up, each icon moves its own way.
- Hero: the Frame-side card is the game running in the headset (one view per eye, the scene moving), switching on
as it lands while its frame rate climbs to 72 and the pacing line draws.
- App demo: working search, right-click menu, select several and install them (queued), install from a link (the
app's link rules), Screenshots tab with a viewer, Settings with the real themes switching live, Files that take
real files from the desktop (they never leave the tab), process table with End, Live view quality, launch-test
result, technical patch ids, toasts; Wi-Fi or USB cable when connecting. Progress ticks no longer rebuild the page.
- Screenshots: a carousel (arrows, keys, swipe, thumbnails, autoplay that pauses for the reader, full screen).
- Compared: four headline differences (free and open source first), every difference as user questions behind
"Show all differences"; the README says the same.
- Wi-Fi or USB cable said everywhere; the setup command explains itself part by part; first-start steps per system.
- Field notes removed, the notice kept in its own band.
- Built on: contributors wall (code, pull requests, issues; scripts/contributors.mjs, saved list as fallback).
- Docs: user-facing docs/*.md as pages (links rewritten, GitHub heading ids, contents with scroll position, copy
buttons).
- Games board rows open to show the recipe; the install log replays with another tested game.
- "Meta Quest" only as a description (headline about the Steam Frame), trademark line in the footer.
- Hero cards: generated covers in the style of the app's placeholder art (hue from the title), the same app icon on
both sides of the portal, a one-line APK name, stage ticker and progress, Play ripple, sparks; titles sized so
words never break. Click the portal for the next game; the scene leans toward the pointer.
- "The app": a clickable, simplified FramePort window (Library, game page with patch switches, Steam Frame, Files,
Live view, Type on Frame, Monitor with live sparklines) and a guided tour from a fresh start: connect the Frame,
scan a folder, install, play. The showcase videos play in a lightbox.
- Compared: FramePort, FrameDrop and Valve's own tools, from their own pages (checked 2026-10-09); the same table in
the README.
- record_video.py --size WxH (e.g. 2560x1440): films at that many device pixels; postprod reads the size at call
time and draws cards at the 1920 layout scaled up. Default output unchanged.
site/ (Astro 7, static, served at spoopyghosty0.github.io/frameport/) takes the Portal look of the UI refresh:
- Hero: a catalog game crosses the logo's tilted portal, from an APK on the PC's (blue) side to a game in the
Steam library on the Frame's (orange) side; reduced motion holds it halfway, like the logo.
- How it works as one real recipe's install log (PC stages blue, Frame stages orange), the showcase tour and
screenshots (synced from docs/ at build time, never by hand), field notes on what doesn't work, install steps,
credits.
- Games board from catalog/games: prebuilt at build time, then refreshed in the browser from main (one contents
API call, only changed files fetched, 6 h localStorage cache); any failure keeps the built list.
- /install/?manifest=…|?url=…: where an "Install with FramePort" button lands; opens frameport://install, and if
FramePort didn't take it, says how to get it (download for this OS, try again, copy the link). Link rules mirror
deeplink.check_url; node tests cover them and the board's rows.
.github/workflows/pages.yml builds and deploys on main (Settings → Pages → Source: GitHub Actions, once).
Adapter rebuilt here; the codec plugin rebuilt here with native/hevc/build.py (NDK r27c, Lepton SoftOMX fingerprint 456e912c) is byte-identical to the contributed one (c1c2a73e). Agent version 70 -> 69 (main was at 68).
Mesa enforces OVR_multiview's rule that a draw's program declares as many views as the draw framebuffer has and drops the draw silently; Doom3Quest compiles every vertex shader with layout(num_views=2) and draws its HUD/PDA into 2D-texture FBOs, which stay black on the Frame.
native/glmv (libfpglmv.so, same length as libGLESv3.so): the engine library's dlopen string is rewritten to it and it becomes the first DT_NEEDED. It records stage sources at link time and, when a multiview program draws into a framebuffer without views, draws with a lazily built single-view twin (num_views layout blanked, gl_ViewID_OVR -> 0u; attribute locations, block bindings and uniform values copied), then rebinds the original. Opt-in and experimental (analysis gl_multiview_libs, ANALYSIS_VERSION 6), setting gl_mv_debug, triage gl-multiview-twin-failed.
Host tests: the rewriter on Doom3Quest's 19 shaders (GPL-3.0 fixtures) and glmv.c against a stand-in GL that applies Mesa's rule. Untested on the device.
Klownicle's five fixes for Vader Immortal: Episode I, reimplemented as FramePort patches (found by Klownicle,
GitHub #49; their prebuilt APK is not used):
- frame.unreal_quest_precompile: UVRUtils::GetQuestShaderPrecompilePercent returned 0.0 on its non-Quest branch, so
the menu waited forever on the loading card; that branch now returns 1.0. Located by symbol, every instruction
around it checked (bl IsRunningOnSantaCruz; tbz w0,#0; fmov s0,wzr; ldp; ret); other builds stay untouched.
- frame.unreal_quest_keymap: the RPOC key selector (shared by AddAxisMapping and AddActionMapping, so both mapping
kinds were affected) picked the empty Gear VR key set for an Oculus HMD; the tbz to it becomes a nop. Located as
the common callee of both functions, pattern-checked.
- frame.zink_shader_fix + native/zinkfix (libVkLayer_fp_shaderfix.so): a Vulkan layer under Zink for GLES games
that applies zink_shader_fix entries (vk_shader_fix format) to the SPIR-V Zink generates; it adds itself to
GraphicsEnv's debug layer list from a constructor (the engine library loads it first). zink_shader_dump=1
captures modules. Vader's recipe carries the two lightspeed-shader fixes (12 OpStores each).
- adapter proximity_emul (FrameBridge): OVRPlugin's thumb/index proximity actions get bindings to the capacitive
touch inputs when the runtime lacks XR_FB_touch_controller_proximity (OVRPort offers the extension anyway):
generic replacement for the libUE4 ThumbUp patch.
- Vader's recipe: pose_time_fix + proximity_emul, status unknown (to test in the headset), min_app 0.12.1.
Analysis records unreal_quest_gates (ANALYSIS_VERSION 4). Star Wars: Tales from the Galaxy's Edge (same studio)
has neither gate (different engine build) and gets a catalog entry with pose_time_fix + proximity_emul.
Headless on the dev Frame (Lepton 3.0.5): the layer loads into Zink's instances, the proximity bindings are
accepted, and the game passes the loading card to the "guardian smaller than recommended, press any button" screen.
Newer Vivox builds (Green Hell VR) call AudioManager communication-device methods (API 31) from com.vivox.sdk.AudioChangeListener without a version check; Lepton is Android 11 -> NoSuchMethodError. The methods that call them now return at once (in-place dex edit, Dex.return_early). Detected by analysis vivox_api31 (ANALYSIS_VERSION 4), triage vivox-api31. Verified headless: Green Hell starts, Vivox initialises, ~65-70 fps.
Budget Cuts Ultimate asks for a 2048x2048 cube swapchain (faces=6); the Frame's runtime has no cube layers and refuses it (-2), OVRPlugin carries on with no images and crashes in ovrp_EndFrame4 (memset). cube_standin (default on, GLES) serves it as a GL cube map in the game's context and drops its layers. Triage cube-swapchain-refused (supersedes unity-render-crash/native-crash). Verified headless: the game runs on at ~70 fps.
BattleSisters' hands lagged behind the controllers (also with ovrp_hold_physics on or off). pose_debug=1 (new,
FrameBridge: per 5 s and per located space, the requested time minus the predicted display time) showed on the dev
Frame (SteamOS 0.4.5): XrTime runs 2.56 s ahead of CLOCK_MONOTONIC, the hand spaces were located at -2564 ms (the
monotonic "now" passed on as an XrTime: OVRPort's dispatcher converts XR_KHR_convert_timespec_time 1:1 and
FrameBridge's emulation is never asked) and the head at XrTime 0.1 s (~1450 xrLocateViews/xrLocateSpace per 5 s).
pose_time_fix (default off; suggested for Unity built-in OVRPlugin games): in xrLocateSpace(s)/xrLocateViews a time
nearer the monotonic clock than XrTime's "now" is moved by the offset measured at xrWaitFrame, one more than 0.5 s
before the display time goes to "now". Headless with it on: every far-past request moved, located times -9.8..0 ms
from the display time. Host unit test for the time rules; PLAYBOOK row.
games + battery every 5 s, paused while a job's stage is "Upload…", only while connected and setting
@@ -154,7 +158,11 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
doesn't do). `VD.bat` is Virtual Desktop's launcher: ignore it except as an exe-location hint. Library migration
`rift_run_direct` resets existing recipes.
Auto launch-test is skipped on PC installs (it would start the game on the user's desktop). Launch tests collect the Unreal
game log + crash summaries from the Proton prefix; triage `unreal-crash`. Lies Beneath via Proton without Revive
game log + crash summaries from the Proton prefix; triage `unreal-crash`. Agent v67 adds Unity's logs (LocalLow/<Company>/<Product>/Player(-prev).log via `<Name>_Data/app.info`,
`output_log.txt`, Temp/…/Crashes/*/error.log; `unity_logs`) to launch tests and diagnostics; triage `unity-vr-init` /
`unity-crash`. A catalog recipe verified with another build (catalog `xr` ≠ the build's) keeps the build's own
`catalog-from-issue.yml` workflow (`scripts/catalog_from_issue.py` validates) opens a catalog PR. App log:
chars; `*_links` = `IssueLinks(form, plain, body)`: body = the Markdown the form writes (`### <label>`, recipe in
a ```yaml block; labels checked against the templates), plain = `?title=&body=` link. GitHub #167: some (Flatpak)
browsers opened the form with empty fields → `app.open_issue` copies the body to the clipboard and offers "Form
empty? Open a plain issue"; keep the templates valid YAML, quote `: ` in descriptions). "Share working config" →
`working-config.yml` issue → maintainer label `catalog-accepted` (a plain issue needs `working-config` added by
hand) → `catalog-from-issue.yml` workflow (`scripts/catalog_from_issue.py` validates) opens a catalog PR. App log:
`core/applog.py` (`<data>/logs/app.log`, finished GUI jobs in `<data>/logs/jobs/`).
- Self-update (docs/ARCHITECTURE.md "Self-update", docs/INSTALL.md "Updating"): `_version.py` = the only version
(`frameport.__version__`; pyproject reads it via hatch `dynamic`; app log, diagnostics, User-Agent, Settings use
@@ -277,12 +303,82 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
by hand: the "Update now" button path (same apply(), called from the running app). macOS: CI smoke only.
- `agent/frameport_agent.py` — runs **on the Frame** (python3 stdlib only), JSON over SSH. Owns the install layout,
launch.sh template, Steam shortcuts (binary VDF), launch tests. Bump `AGENT_VERSION` when changing it.
- `bootstrap/bootstrap.sh` — one-time Frame setup served by the pairing server (sshd, app key, avahi service, Lepton).
- `bootstrap/bootstrap.sh` — one-time Frame setup served by the pairing server (app key, podman fix, Developer Mode, Lepton).
`bootstrap/setup.sh` — the setup URL (`curl -fsSL https://frameport.app/s | bash`, copied to the site by
`site/scripts/sync-media.mjs`): finds the PC (stdlib mDNS on 5353 for `_frameport-pair._tcp`, which the pairing
server announces while open; else the USB address and a /24 scan of `/ping`), `/hello` → the user clicks Allow (4
digits on both sides, `ask_digits`) → `/wait` hands over the code → runs bootstrap.sh exactly like the typed line.
Checked on the dev Frame 2026-10-10 (mDNS and scan paths) with a stub bootstrap; tests/test_setup_url.py.
Auto-pairing (`frame/autopair.py`, `app._start_auto_pair`, setting `frame.auto_pair`, default on; off with
FRAMEPORT_HOME/FRAMEPORT_NO_AUTO_PAIR): while no Frame is connected, Frames in Developer Mode (devkit mDNS, else a
30 s scan of the /24s for :32000/login-name, deduped by host key) are connected if FramePort's key works, else
offered the key via devkit.register every 4 s (refused at once until Pair new host is open; 45 s back-off after an
unanswered request). This WSL dev PC never hears the Frame's mDNS (Hyper-V firewall): the scan finds it.
- `catalog/games/<package>.yaml` (installed apps also fetch these from GitHub `main`, see "Catalog updates") — 38 recipes (34 verified 2026-09-28; Deadpool VR, 4XVR, NEX Player and AC Nexus's
90 Hz default confirmed later by the owner); `catalog/triage.yaml` — log signatures → fixes.
- `native/` — sources of the prebuilt binaries in `artifacts/` (adapter, VrApi bridge patches, GL shim, stubs).
`native/build.py` rebuilds them with NDK r27c (downloaded on demand into `native/.cache`, git-ignored; uses
`-ffile-prefix-map` so no local paths get embedded; zip symlinks are restored as copies). Users never need the NDK.
`native/a32translator/` (not an artifact, not shipped) = `a32run`, an AArch32 → AArch64 user-mode translator
(interpreter + JIT, ARM/Thumb-2/VFP/NEON) for running 32-bit ARM Linux programs on the Frame; its README has the
design, the qemu-arm differential fuzzer and program tests. `native/a32translator/bridge/` = the in-APK Android
bridge (32-bit JNI/NativeActivity libraries in a 64-bit app: stub + liba32bridge.so + guest runtime liba32rt.so;
harness with a fake JVM; test APK org.frameport.a32test passes in Lepton; GLES/EGL, OpenSL ES via AAudio, VrApi 1.x
-> the 64-bit VrApi bridge, controller input as Gear VR touchpad/back events; `bridge/convert.py` converts an APK).
First game: AFFECTED The Manor (Gear VR, Unity 5.6 + Mono) runs in the headset with picture and sound
(2026-10-10); Spunky Dungeon (Unity 2019.2, OVRPlugin 1.46 on VrApi 1.31, Platform SDK) plays at 72 fps.
In FramePort: patch `frame.a32_bridge` (`patches/frame/a32_bridge.py`: `convert()` is shared with the dev script
`bridge/convert.py`; artifacts `liba32bridge.so`/`liba32rt.so`/`liba32stub.so` from `native/build.py --only a32`)
is suggested for every 32-bit-only APK; the recipe then has `overport: False` (OVRPort is 64-bit only; the patch
ships OVRPort's loader chain + its 32-bit platform dispatcher itself, `overport.ensure_runtime_lib`), only
frame.a32_bridge/adapter/launcher of the frame patches, and `device.text_input_window` for Unity (`engine.a32_recipe`,
also run by `pipeline.set_recipe` + builds, so a bridge turned on by hand drops OVRPort & the 64-bit fixes; which
patches work there = `base.works_on_a32` (`Patch.a32`; overport/frame off unless `a32 = True`, adapter settings in
2026-10-10): needed the native_app_glue imports (ALooper/AInputQueue/AConfiguration/AAsset*, imports.txt), an arm64
libvrapi.so for Java's System.loadLibrary("vrapi") and MOUNTED under OVP_HEADLESS_TEST; it then loads its map and
quit on purpose: AndroidMain compares AndroidThunkCpp_GetSignature() with an obfuscated copy. **Works since
2026-10-11 (owner-verified in the headset):** GameActivity.AndroidThunkJava_GetSignature() = Base64.DEFAULT(SHA-1(
signing certificate DER)) (jadx); `a32_bridge.original_signature` computes it from the original APK's
META-INF/*.RSA|DSA|EC, `convert()` stores it as `assets/fp_a32_signature.txt` for libUE4.so games, the bridge loads
it at activity creation (native_activity.c) and jni.c answers Call*Method on the method ID of
`AndroidThunkJava_GetSignature()Ljava/lang/String;` with it. After loading, Unreal leaves VR mode and enters it again on
the same GL context; a second OpenXR session there aborted in vrclient (CSharedSemaphoreLinux::WaitFromGPU from the GL
binding's PreBeginFrame, also with OVP_HEADLESS_TEST) → the VrApi bridge keeps a running GLES session across
LeaveVrMode and reuses it for an EnterVrMode with the same context (upstream-patches/runtime.cpp.patch).
Debugging aids added: A32_BREAK=<guest addr>[,..] (stack of the first hits; guest libs load at fixed addresses, e.g.
libUE4 0xf25d5000), A32_STRACE in bridge mode = path/exit calls to logcat, activity lifecycle + LeaveVrMode caller
logs. Lepton's logcat mirror often dies for these games: read `podman exec <container> logcat` instead. Gunjack input
(2026-10-11): it imports no vrapi input functions and reads the Gear VR touchpad/back as AInputEvents from its
AInputQueue (native_app_glue), so dispatchKeyEvent never reached it (no control at all) → input.c queues synthetic
events there (ALooper_poll* return the queue's ident while one waits; AInputQueue_getEvent/finishEvent and the
AInputEvent/AKeyEvent/AMotionEvent getters are hand-written "!" imports that know them; touch positions scaled to the
window size). Same mapping as AFFECTED: trigger = hold touchpad, A = tap, right stick = swipe, B = back; for NativeActivity games the stick's up/down = swipe forward/back (touchpad X: Gunjack's OnFlick = reload at ~0°, special weapon at ~180°). Not yet
headset-verified. Quest builds on the bridge (2026-10-13, Sports Scramble = a 32-bit Santa Cruz build,
UE 4.21 + OVRPlugin on VrApi 1.21): manifest requires `android.hardware.vr.headtracking` version 1
= "quest" → vrapi.c `quest_touch` (read in vrapi_Initialize via the activity's AssetManager; A32_TOUCH=1/0
overrides) passes the 64-bit bridge's Touch controllers through (enumerate/caps/state/tracking/haptics, struct
tails per VrApi minor) and starts no synthetic input. It also needed AAsset_getBuffer (guest copy, freed in
AAsset_close), AKeyEvent_getFlags and the other AConfiguration getters. Headset (owner, 2026-10-13): plays,
both controllers work. Recenter (holding the Frame's menu button) turned VrApi games ~90-120 degrees aside: the bridge's app space is LOCAL + the start yaw and the runtime moves LOCAL to the head → the bridge now takes the origin from the head again on XR_TYPE_EVENT_DATA_REFERENCE_SPACE_CHANGE_PENDING (LOCAL) and on vrapi_RecenterPose (owner-verified with Gunjack, 2026-10-13). Next: the other 32-bit catalog games (Journey of the Gods, Shadow Point: still "unsupported" until
tested), translator speed. Profiled on the Frame
(2026-10-12, `A32_PERFMAP` + perf): FPCR switches are negligible (8 of 86k samples); the cost was the run loop
(a mutex + hash-chain walk on every dispatch, a contended counter, inline-lookup slots never refilled: Gunjack
~45 % of its CPU) and `jit_invalidate` scanning every block on each Mono `cacheflush` (72 % of Spunky Dungeon's
main thread). Now lock-free lookups, ltab refill, per-thread flags, per-page block lists: Gunjack's dispatcher
23.6 % -> 1.6 %, CPU in the same phase about -55 %, still 72 fps.
- No AArch32: 32-bit-only APKs fail with `INSTALL_FAILED_NO_MATCHING_ABIS`. Unfixable; point to Rift + Revive.
- No AArch32: 32-bit-only APKs fail with `INSTALL_FAILED_NO_MATCHING_ABIS` → `frame.a32_bridge` (the a32 translator inside the app, see native/a32translator below).
- GLES swapchains: only `GL_SRGB8_ALPHA8`/`GL_SRGB8` (35907/35905), no MSAA. Vulkan: format 43 (sRGB) but not 37 (UNORM).
- Missing: XR_FB_passthrough (emulate via ALPHA_BLEND), XR_FB_scene/spatial entities (emulated room from STAGE bounds),
XR_KHR_composition_layer_equirect2/cylinder, XR_FB_composition_layer_image_layout (flip emulated by Vulkan blit).
@@ -600,11 +710,16 @@ reaches its OVRInput cleanly (probe: both Touch connected 0x63, individual butto
"outside of frame bounds" warnings stay (~2/frame) and are harmless.
Steam library (GitHub #4/#21/#27, agent v38): shortcuts go to every Steam account (signed-in first; MostRecent isn't
always the account on the Frame); stop_steam also waits for Steam's helpers; after the restart the agent re-reads
shortcuts.vdf and writes once more if Steam put its old copy back (`shortcuts_lost`), else reports it. 0.6.3's Play
shortcuts.vdf and writes once more if Steam put its old copy back (`shortcuts_lost`); lost again (agent v89): Steam
ignores FramePort's entries on that Frame, so `add_devkit_entry` adds the devkit entry instead (`added` gets `via:
devkit`) and only reports an error if that fails too. 0.6.3's Play
auto-repair (`_add_then_play`) crashed (its job got a Job, not a reporter). Uploads resume on a transient OSError.
Lepton's Android 11 has no clipboard service (134 services; checked with `podman exec … service check clipboard`):
SDL/LÖVE apps crashed at start → `frame.sdl_clipboard` (`apk/dex.py`: in-place dex edit, nops one invoke, fixes
the header checksum/signature; verified with LÖVE for Android 11.5, GitHub #24 Dramatic Shape). 2D apps (vr_kind none)
the header checksum/signature; verified with LÖVE for Android 11.5, GitHub #24 Dramatic Shape). Godot 4.2-4.4 (Kotlin `as ClipboardManager`,
GitHub #134 EndoparasiticVR) → `frame.godot_clipboard` (nops the `Intrinsics.checkNotNull` before that check-cast; Godot's
clipboard methods return at once; analysis `godot_clipboard`, ANALYSIS_VERSION 10; checked on real godot-lib/templates
4.2.2-4.4.1, not on the device; 4.1 and 4.5+ don't throw). 2D apps (vr_kind none)
keep every suggested patch that isn't about VR (`needs_vr = False`), not a fixed list. FramePort on the Frame:
`frame/local.py` (127.0.0.1, own key authorized; "This Frame (experimental)"; app data in
~/.local/share/frameport-app because ~/.local/share/frameport is the agent's) and Steam library changes wait while
@@ -694,6 +809,24 @@ FrameBridge `snapshot=N` (`snapshot_gl.c`, GLES): every N s the left-eye image t
own context and saved as `files/fb_snap_0-7.ppm` (quarter size) — headless launches show a black headset view, this
shows what the game draws. Vader: Lucasfilm logo (an OBB mp4: video works), then its loading card (portrait + segmented
bar) that never advances; the async loader thread sleeps and OBB reads stop (~168 MB of a 2.7 GB pak).
**SteamVR overlay apps (agent v75, 2026-10-10):** host OpenVR overlays (VRApplication_Overlay) are composited over Lepton (Quest) games on the Frame (probe checker seen over 4XVR in the headset view, `native/vroverlay_probe`); Windows ones register through Proton's vrclient too (Temporal Reality's Windows build created its overlays; fpsVR never reaches OpenVR under Proton). Detection `analysis/vroverlay.py` (bundled `.vrmanifest` with `is_dashboard_overlay`, else OpenVR + IVROverlay + self-registration markers, engine Other; Rift fingerprint `RIFT_ANALYSIS`), patch `pcvr.vr_overlay` (param autostart), Linux entry fields `vr_overlay`/`vr_overlay_autostart` (game page switch); agent `register_vr_overlay`/`unregister_vr_overlay`/`launch_vr_overlay` (IVRApplications via ctypes, live; manifest `<anchor>/frameport-overlay.vrmanifest`, the app's own key, binary = launch.sh). **SteamVR on the Frame reads only `binary_path_linux_arm`** (binary_path_linux alone is skipped). Overlay apps: no launch test, no Linux Steam-parent watchdog (`FRAMEPORT_OVERLAY`), not a "running game". A Steam overlay-app shortcut and a game shortcut run together. SteamVR's SetApplicationAutoLaunch didn't persist on the dev Frame (the watch never started by itself) → **agent v76: FramePort's own autostart**: the deployment's `overlay.autostart` is the source of truth; `ensure_host_fixes` (`ensure_overlay_service`) keeps the user service `frameport-vr-overlays.service` (`_vr_overlay_watch`, 5 s polls of the known vrserver's /proc stat) only while an overlay app has autostart on (register/unregister, uninstall, purge and the kill switch `~/.local/share/frameport/vr-overlays.disabled` / `FRAMEPORT_NO_OVERLAY_AUTOSTART` update it); a new vrserver (pid + start time, kept in `~/.cache/frameport-vr-overlays.json` across agent updates) → child `_vr_overlay_round`: wait for IVRApplications, 15 s grace, `launch_vr_overlay` for apps not running (folder process or GetApplicationProcessId); log `~/.local/share/frameport/vr-overlays.log`. Dev Frame: adopted the running vrserver, skipped the already running watch; a start after a real SteamVR start/boot is not yet seen. Details: docs/FRAME_RUNTIME.md "Overlay apps".
**Vader's leak solved / AC Nexus flips (2026-10-14):** Vader Immortal leaves GL errors pending on its context; SteamVR's GL interop (`openxr_graphics_gl_openvr.cpp`, `xrclient_<pkg>.txt` in Steam's logs: `SXR_GL_CHECK: error:0x502 ... glGenTextures`) takes the stale error as its own failure once, and from then on `CVRCompositorSharedTextures::BeginCommandBuffer` allocates a command buffer every frame (perf page-fault stacks; ~430 renderD128 mappings + 22 MB/s). Adapter `gl_error_clear` (GLES, catalog on for Vader ep1-3) clears them before xrCreateSwapchain/xrBeginFrame/xrEndFrame: flat memory, no SXR_GL_CHECK (headless). The per-game `xrclient_<pkg>.txt` logs are worth reading for runtime errors. The Frame's runtime caps swapchains per session (XR_ERROR_LIMIT_REACHED from ~15; AC Nexus asks for more): flip emulation now turns quads upright in place (scratch VkImage, once per acquire; transfer usage added to single-layer colour swapchains) instead of a shadow swapchain per quad, which ran into the cap (#138). Headless sessions don't draw AC Nexus's panels (adapter `flip_dump` saves before/after images of flipped quads, for headset runs).
**Unreal's self-restart (agent v90, 2026-10-13):** UE 4.21+ restarts the app once after its first-run shader
precompile ("optimizing" screen; `r.ProgramBinaryCache.RestartAndroidAfterPrecompile`): it starts its own LAUNCHER
activity and calls System.exit(0); Lepton ends the container with the first process (the restarted one with it).
Skipping `AndroidThunkJava_RestartApplication` or the cvar = 0 (accepted via UE4CommandLine.txt `-ini:`) left Sports
Scramble on that level for good. launch.sh (RESTART_BLOCK, `upgrade_launchers` adds it) starts Lepton once more when
`_restart_requested` sees the app's own LAUNCHER start (system log, uid >= 10000) <= 5 s before its exit; first run
kept as `launch-before-restart.log`; `FRAMEPORT_NO_RESTART=1` off. Owner-verified with Sports Scramble's first start (2026-10-13).
**xrWaitFrame runs ahead (Journey of the Gods, 2026-10-14, owner-verified):** with real frames (headset on) the
Frame's runtime sometimes returns from xrWaitFrame at once with a display time less than one refresh after the frame
just submitted, and then rejects the second submission for that refresh (`VRCompositorError_AlreadySubmitted` in
Steam's `logs/xrclient_<pkg>.txt`; FrameBridge pacing above the display rate). VrApi games that render faster than
the display ran ahead (~120 submits/s at 90 Hz) and the scene slid and snapped back. The VrApi bridge re-waits when
the new display time is under half a period after the last submitted one (`pacing 2s:` counters). Headless runs only
submit empty frames and never show it. Lepton's logcat mirror also missed the whole verifying session (launch.log =
Lepton's own lines only): the keeper now catches a silent mirror too (agent v91).
**Lepton's logcat mirror dies (agent v67, 2026-10-09; v91 2026-10-14):** Lepton's mirror (`podman exec -it <container> logcat -v threadtime,color`) fails three ways: `logcat: Unexpected EOF!` right after the game starts, `Logcat read failure`, or running and writing nothing at all (Lepton 3.0.5: seen twice on 2026-10-14, once in the owner's session, once headless). launch.sh's `_logcat_keeper` reads `podman exec <container> logcat -v threadtime -T <epoch>` itself into launch.log after a failure line or 20 s without a logcat line (from the launcher's start when the mirror never wrote, else from just before its last line), restarts it from where it ended (≤5), stops it when Lepton's coloured lines come back, sets the container's log buffer to 16 MiB (`logcat -G`), and logs every decision to `<base>/logcat-keeper.log`. Checked on the dev Frame: a mirror killed mid-game (hand-over without a gap) and a silent mirror (the whole session recovered).
**Double launch (agent v57, 2026-10-06):** a second Play while Lepton still boots (~10 s with nothing to see) made
the second Lepton stop the first one's container ("Waiting for steamlaunch-<appid> (PID …) to exit", exit 137
"(starting)", "Clearing baked app data due to early exit") and both died (Vader, BattleSisters). launch.sh now takes
@@ -721,6 +854,124 @@ head-pose deadline ends VR mode without a worn headset (not a game bug).
**Language packs (merged from PR #20, 2026-10-04):** overport's `libovrplatformloader.so` is a dispatcher that `dlopen`s Meta's own loader (`libovrplatformloader_meta.so` / `_meta_q1.so`, also `libpxrplatformloader.so`) and keeps its own message queue; `ovr_LanguagePack_GetCurrent/SetCurrent` are 8-byte `return 0` stubs in it, `ovr_AssetFile_GetList` forwards to Meta's loader. `frame.langpacks` (opt-in, `native/langpack`) serves `<tag>.lang` files from the game's data; `elf.hide_exports` marks the loader's exports STB_LOCAL (bionic and glibc only match GLOBAL/WEAK; verified for glibc, bionic's `is_symbol_global_and_defined` is from memory). `libfp_langpack.so` is built here (`python native/build.py --only langpack`) and committed. Owner-verified 2026-10-04: Deadpool VR with only `en.lang` and the patch on plays English dialogue and runs normally (headless launch tests show 2-6 fps while it loads: not a regression sign). A dispatcher answer that arrives after we answered the timed-out GetList is dropped (one answer per request); games already in a library get `lang_packs` filled after an app update (`library._refresh_data_fields`). The library logs to logcat under the tag `fp_langpack` (dirs looked in, packs found, every language-pack call), so it shows up in the game's `launch.log`; an `ovr_AssetFile_GetList` the dispatcher leaves unanswered for 1.5 s is answered with our packs alone. Deadpool VR (Unreal) accepts a pack only when its `Metadata` equals the game's own version string (`ULanguagePacksSubsystem` compares it with `%s.%s.%s.%s.%s` built from the build info, e.g. `1.0.40.356975.Quest` = versionName; found by disassembling `libUE4.so`): the patch writes the APK's versionName into the library (`@FPMETA@` slot, `with_metadata`), `FRAMEPORT_LANGPACK_META` overrides it. Deadpool VR (2026-10-04, headset): German became selectable with that Metadata, but dialogue stayed silent (even English once reported as a pack) while the path was spelled `/sdcard/Android/obb/<pkg>/x.lang`; with the `/storage/emulated/0/Android/obb/<pkg>/x.lang` spelling (Unreal's own, now listed first in `scan_dirs`) German dialogue plays. `FRAMEPORT_LANGPACK_SKIP=<tags>` or a file `fp_langpack_skip` in the obb folder leaves packs out of the list (experiments).
`games/<pkg>/target/shaders/`. Triage `gpu-hang` suggests both dumps; `triage.graphics_api` (FrameBridge's
xrCreateSwapchain formats: <0x1000 Vulkan, else GL) keeps only the session's API's (`API_ONLY`). Host-tested only.
Agent v74: a reporter's hang came ~10 s after the last new module, so the culprit wasn't among the newest written →
with an index naming modules, `shader_dumps` sends every module of the index's **newest session** (after the last
`# start`), deduplicated, last used first, each ≤4 MB, ≤30 MB in all (`session` = how many it names) + that session's
index lines; no index (fp_spirv) = the old newest-by-mtime 4 MB. One JSON line (~40 MB base64) over the SSH channel
is read whole by `Frame.agent` (fine at that size); `_Writer.fit` drops the least recently used modules last, after
cutting logs, to stay under the 24 MB zip limit.
**Unreal OBB check (GitHub #159, 2026-10-10):** Epic's DownloaderActivity checks OBB name+size (OBBData), then with `bVerifyOBBOnStartUp=true` CRCs the whole OBB; its screens are invisible in Lepton (stuck at `Displayed …/.DownloaderActivity`, triage `unreal-obb-check-stuck`) → `frame.unreal_skip_obb_check` (analysis `unreal_verify_obb`, ANALYSIS_VERSION 11) flips the manifest boolean (`axml.set_meta_data_bool`); skips only the CRC pass. Host-tested only.
communication-device methods from `com.vivox.sdk.AudioChangeListener` with no SDK check → NoSuchMethodError on Lepton's
Android 11. `frame.vivox_audio_route` (analysis `vivox_api31`, ANALYSIS_VERSION 4) makes every such method return at
once (`Dex.return_early`: return-void / `const/4 v0,0; return v0`; nopping the invoke would leave a move-result the
verifier rejects). Older Vivox (Eleven Table Tennis, BattleSisters) lacks that code and isn't matched. Verified
headless: Vivox initialises, 150 s at ~65-70 fps.
**Steam Input gamepad for 2D apps (GitHub #162, agent v72, 2026-10-10):** Lepton's Android only has the Wayland seat's `wayland_touch/keyboard/pointer`. Steam makes its virtual pad (uinput, `/devices/virtual/input`, 28de:11ff, "Microsoft X-Box 360 pad N", ACL for steamos) only while the Frame's controllers are on (controller.txt "Steam Controller reserving XInput slot 0"; gone when they sleep), also with no game running; steamos-manager's 28de:0000 keys device isn't a pad (no BTN_SOUTH). Lepton's container root (system_server too) = steamos (`keep-id:uid=0`), so a bind-mounted `/dev/input/eventN` opens. Opt-in `device.steam_gamepad` (vr_kind none; suggested for `android.hardware.gamepad`/`LEANBACK_LAUNCHER`, analysis `gamepad`, ANALYSIS_VERSION 9): deployment.json `steam_gamepad` → launcher `GAMEPAD_LINE` (after the codec line: exports FRAMEPORT_GAMEPAD + LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD, puts `agent/bin` first on PATH) → `PODMAN_WRAPPER` (written by ensure_host_fixes; non-`run` calls go straight on; `run` imports the agent's `podman_run_args`; hands on to the next Podman after its own PATH entry with itself removed from PATH, so it chains to the codec wrapper either way round) adds the pads + `Vendor_28de_Product_<pid>.kl` (Xbox 360 layout). Verified headless with a uinput stand-in pad (Stremio's container: EventHub `classes=0x80000141`, our key layout, KeyEvent BUTTON_A dispatched); with Steam's real pad and a game: not yet. Pads made after the start aren't seen until the next one.
Install games that target the Meta Quest, Android, or general PCVR onto your**Valve Steam Frame**. FramePort handles everything from uploading game files, setting up your Frame, injecting compatibility patches, and adding shortcuts to your Steam library. FramePort aims to be as simple as possible by taking advantage of the fact that the Steam Frame runs on Linux.
Install Quest games, Android apps, Linux apps and PCVR games on the**Valve Steam Frame**. FramePort sets up the
Frame, patches each game so it runs there, uploads it and adds it to your Steam library with artwork.
▶ [Watch the full tour](docs/media/frameport-tour.mp4) · New to FramePort? [Watch the install tutorial](docs/media/frameport-install.mp4)
(about 90 seconds each, MP4; also attached to every release)
(about 90 seconds each)
> **Notice:** FramePort explicitly does NOT download, share, or unlock games. You must provide legally obtained game
> executables. Core features of FramePort simply download and wrap other published tools (see [Built on](#built-on))
> with patches provided by FramePort adding a hardware compatibility layer. This enables users to use games/apps legally
>purchased on sites like [SideQuest](https://sidequestvr.com/).
> **Notice:** FramePort doesn't download, share or unlock games. Use games you got legally, for example from
> [SideQuest](https://sidequestvr.com/). FramePort downloads published open-source tools (see [Built on](#built-on))
> and adds its own patches so games run on the Frame.
>
> Not every game runs on the Frame: recipes are tested by the community, and some games need Meta's services or
> hardware the Frame lacks.
## Features
- **Painless setup:** one short command on the Frame. No root, no `sudo`, no password.
[What it changes](docs/FRAME_SETUP.md).
- **Type on Frame:** use your computer's keyboard on the Frame: in VR apps, Android apps, Steam and the desktop.
[More](#type-on-frame).
- **One click per game:** convert, patch, sign, upload, add to Steam with artwork, launch test. Artwork that can't be found automatically can be picked from the stores or replaced with your own images.
- **Per-game recipes:** a tested catalog plus detection rules; every patch explained in plain words.
- **FrameBridge:** FramePort's OpenXR adapter emulates what the Frame natively lacks (passthrough, room, controller models,
curved and 360° layers); game settings as simple switches.
- **Beyond Quest:** Android apps as windows, PC VR via Proton or Revive, Windows (non-VR) games via Proton, a Files
tab with drag and drop.
- **Linux apps:** install Linux apps (AppImage, a folder, or a zip/tar archive) on the Frame with a Steam
shortcut; arm64 builds run natively on SteamOS, x86_64 builds through Valve's FEX translator.
- **Install links:** "Install with FrameDrop" buttons on web pages (the one-click protocol of the FrameDrop
sideloader) and pasted links open in FramePort, which asks, downloads, adds and installs the build.
- **Screenshots tab:** the screenshots you took in the headset, sorted by game (matched by play time) and day;
view them and download them to your computer.
- **Live view tab:** watch what the headset shows, with sound, in a browser window on your computer.
- **Monitor tab:** the running game's frame rate, the Frame's load, temperatures, power and battery live, and its
processes, which you can end. [More](#monitor).
- **Self-updating** releases, redacted diagnostics, one-click problem reports and working-config sharing.
- **Easy setup:** one line in the Frame's terminal. No root, no password. [What it changes](docs/FRAME_SETUP.md).
- **One click per game:** patch, upload, add to Steam with artwork and test that it starts.
- **Recipes:** tested patches and settings for 120+ games; other games get suggested patches, each explained in
plain words.
- **Game settings:** sharpness, refresh rate, controllers, 360° video and mixed reality as simple switches.
- **More than Quest games:** Android apps in a window, Linux apps, PC VR games and Windows programs.
- **Install links:** "Install with FramePort" buttons on websites ([frameport.app](https://frameport.app) links) open
in FramePort.
- **Your Frame from your PC:** Type on Frame (your keyboard on the Frame), Files, Screenshots, Live view (what the
headset shows, in your browser) and Monitor (frame rate, temperatures, battery, processes).
- **Updates itself**, and reports problems without personal data.
## Quick start
1. [Download](https://github.com/spoopyghosty0/frameport/releases/latest) and unzip the build for Windows, macOS
(Apple Silicon) or Linux, then start FramePort.
2.**Connect the Frame** (once):
1. In FramePort click **Steam Frame → Show setup command**. Keep FramePort open; the Frame and your computer must
be on the same Wi-Fi.
2. On the Frame open the **SteamVR dashboard → Launch a program → Desktop**: the Linux desktop opens on a virtual
screen.
3. Open the app menu (bottom-left corner of that desktop) → **System → Konsole** (or search for Konsole).
4. Type the command FramePort shows exactly as shown (on-screen keyboard or any USB/Bluetooth keyboard) and press
**Enter**. This will run the following [bash setup script](bootstrap/bootstrap.sh).
5. After a few seconds the desktop closes by itself (Steam restarts once); that's expected. If
Steam asks to install **Lepton**, confirm it. FramePort shows the Frame as connected within a minute. No
password needed.
3.**Add games → Scan a folder** with your game backups (APK + OBB, or PC VR game folders).
4. Open a game → **Install on Frame**, then play it from the Frame's Steam library.
Full guide, firewalls and troubleshooting: [docs/INSTALL.md](docs/INSTALL.md). Questions (e.g. how to lay out games
with OBB files): [docs/FAQ.md](docs/FAQ.md).
## Type on Frame
Typing in VR is painful, so FramePort turns your computer's keyboard into a keyboard for the Frame. Open **Type on
Frame** (its own tab in the sidebar), select a text field in the headset and type: searches, logins, chat, in any
app, in Steam or on the desktop. Paste longer text to type it in one go. Nothing to install: FramePort adds a virtual
keyboard on the Frame while the tab is open, without root.
Unity apps whose text fields close the moment you select them on the Frame (no system keyboard there) get a per-game
fix, so Steam's on-screen keyboard and Type on Frame work in them too.
[Details](docs/INSTALL.md#typing-on-the-frame).
## Screenshots
Screenshots you take in the headset show up in FramePort's **Screenshots** tab, grouped by day and matched to the game
you were playing. Open one full size, step through them, and download single shots, a selection or all of them to
**Tested something? Share it.** In FramePort open the game → **…** → **Share working recipe…** (it fills in the
recipe for you) or **Report a problem…** (attaches a diagnostics zip with personal data removed). Without the app:
[share a working config](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml) · [report a problem](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml). Shared configs become built-in recipes for everyone.
FrameDrop and Valve's own tools install an app as it is. FramePort differs in four ways:
- **Free and open source** (GPL-3.0). FrameDrop is free (donationware) without published source.
- **Quest games that don't run on the Frame as they are** get converted and patched, with a tested recipe for 120+
games. The others install the game unchanged.
- **Windows, macOS and Linux.** FrameDrop is for Windows.
- **Wi-Fi or a USB cable**, and no **Pair new host** step.
<details>
<summary>All differences</summary>
| | **FramePort** | **FrameDrop** | **By hand with Valve's tools** |
|---|---|---|---|
| Cost and source code | Free, open source (GPL-3.0) | Free (donationware), source not published | Free, from Valve |
| Runs on | Windows, macOS, Linux | Windows | Depends on the tool |
| First connection | One line in the Frame's terminal; it turns on Developer Mode itself. No password | Turn on Developer Mode, then **Pair new host** | Turn on Developer Mode and pair, or use Android's debug tool (adb) |
| Wireless or cable | Wi-Fi, the Frame's hotspot or a USB cable | Same Wi-Fi network | Wi-Fi, or adb |
| Quest games that don't run as they are | Converted and patched for the Frame | Installed as they are | Installed as they are |
| Knows which patches a game needs | Tested recipes for 120+ games, updated without an app update | Not stated | No |
| In the Steam library | Yes, with artwork and tags | As a "Devkit Game" shortcut | As "Devkit Game: <title>"; not with adb |
| Android apps, Linux apps, Windows programs | All three; Proton (runs Windows programs) is installed for you | All three; install Proton first | Yes; 2D Android apps need an extra file |
| PC VR games | On your PC; some also on the Frame | Not supported | Not supported |
| "Install with …" buttons on websites | Yes ([frameport.app](https://frameport.app) links) | Its own | No |
| A game doesn't start | A launch test reads the logs and suggests a patch | A log viewer | No help |
| Use the Frame from your PC | Live view, Monitor, Files, Screenshots, Type on Frame | Not stated | No |
</details>
Other tools as described on their own pages, checked 2026-10-09:
@@ -148,8 +138,9 @@ uv run frameport --help # command line
uv run pytest # tests
```
## AI Usage Notice
While I would like to program everything manually, I no longer have much free time for personal projects. As a result I make use of AI tools to make it significantly quicker to debug compatibility issues.
## AI usage
I don't have much free time for this project, so I use AI tools to debug compatibility problems faster.
@@ -5,12 +5,15 @@ FramePort is GPL-3.0-only (see `LICENSE`). It includes or downloads the followin
## Included in this repository / the release bundles
| Component | Where | License |
|---|---|---|
| LuaJIT (Lua engine for verified xLua pointer compatibility, github.com/LuaJIT/LuaJIT) | `artifacts/arm64-v8a/libfp_luajit.so`; pinned build in `native/luajit/build.py` | MIT (`native/luajit/COPYRIGHT`, included in bundles as `artifacts/licenses/LuaJIT.txt`) |
notes:Audio on the file select screen sounds crunchy. Controls may need rebinding in the game. Quest build from https://github.com/fulldivegames/Majoras-Mask-VR.
Loaded 100 of 777 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
spoopyghosty0