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.
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.
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.
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).
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.
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).
- 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.
- 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.
- The install tutorial (app screen and card) shows curl -fsS <your-PC-address>:8765/<one-time-code> | bash, so
nobody takes the example for their own command; the card says FramePort fills them in.
- Videos: opening the Monitor tab no longer replays two minutes of samples (its charts raced to catch up); the
charts start there and grow live, as in the app. The pretend frame rate holds ~72 fps with a short, shallow dip
now and then (it sat at 55-61 fps for seconds). Both videos re-recorded.
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.
- record_video.py replaces record_tour.py: one storyboard per video with its output, a start state (demo or
fresh profile, Frame connected or not, start page, live or frozen stream), setup steps before filming, filmed
scenes and instruction cards (eyebrow, heading, numbered steps, a command, a note) for what happens outside
FramePort. --changed-since records the videos whose storyboard (or the recorder) changed; several videos record
in separate processes.
- videos/install.yaml: download, first start, the welcome screen's tool download, the setup command, the command
on the Frame (card), connected, scanning a folder, installing and playing a game (81 s).
- demo_home profile "fresh": FramePort's first start (empty library, welcome screen, nothing on the Frame); its
games wait for the pretend folder scan. Fakes for a first start: no Frame discovery on the real network, the setup
command shows the docs' example address, a pretend tool download, steps hooks first_run and pairing_done.
- CI records changed (or named) videos; releases attach every docs/media/frameport-<name>.mp4 as
FramePort-<name>.mp4. INSTALL.md and README link the tutorial; SHOWCASE.md documents the storyboard format.
- Cards are opened by their title in both videos (a card's middle is its Install button).
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.
- Library: an "All games" label and a 2 px rule (blue→orange in Portal themes) between the shelf and the grid,
hidden with the shelf.
- The pretend Frame's screenshots are the games' own in-game store screenshots (never cover art), installed games
first; the running demo game is BONELAB (it has screenshots, so Take screenshot adds a real one).
- render_docs: a shot whose steps fail is retried in a fresh window and never written (a window that didn't connect
had produced an empty Library); every shot is rendered twice in fresh windows and kept only when both agree (a
misdrawn glyph, "7.θ W", slipped through once); changes from 0.04 % of the pixels count (the sidebar card
showing another game is 0.12 %, run-to-run noise under 0.007 %). --fast renders once.
- record_tour: SHOWCASE_DEBUG=1 prints each step's start time. Docs images and the tour re-rendered.
Flet packs a patch by iterating each control's _values dict; Prop.__set__ adds/removes keys there without a lock.
A property set on a background thread (the live Frame card's sample, job progress, the library loader) while the
event loop packed a patch raised "dictionary changed size during iteration" and the update was lost (seen in CI:
a sidebar click left the old page showing). serialize_flet_updates() now makes property writes take the same
re-entrant lock as patches (app.FLET_LOCK). Reproduced with Flet's own encoder: 16 failures in 4 s before, none
after; test_property_writes_wait_for_a_patch_being_packed. The showcase server and ui_smoke serialize like the app.
Tour re-recorded with the fix (clean, no fallback clicks).
spoopyghosty0