Skip to content

Feat/handheld UI #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Producdevity merged 12 commits into from
Aug 31, 2026
Merged

Feat/handheld UI #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
62e8f74
feat: add handheld UI and H700 ROCKNIX support
Producdevity Aug 30, 2026
5df64fd
docs: update controls and supported devices
Producdevity Aug 30, 2026
701e294
fix: harden handheld runtime behavior
Producdevity Aug 30, 2026
ac6fbef
fix(portmaster): handle CFW compatibility edge cases
Producdevity Aug 30, 2026
fd7c497
fix(build): make release tooling repeatable
Producdevity Aug 30, 2026
35d32ec
docs(session): clarify Xbox protocol access key
Producdevity Aug 30, 2026
e4a3a2a
fix(input): respect system face-button mapping
Producdevity Aug 31, 2026
31c2fb7
fix(ui): fix swapped button labels
Producdevity Aug 31, 2026
0a8489d
fix(build): stop on failed ROCKNIX patches
Producdevity Aug 31, 2026
2c070a7
refactor(port): remove credential migration
Producdevity Aug 31, 2026
dcdc296
docs: record AmberELEC validation
Producdevity Aug 31, 2026
abb3a6c
test(build): cover ROCKNIX module assembly
Producdevity Aug 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 40 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,8 @@
<img width="640" height="480" alt="screenshot" src="https://github.com/user-attachments/assets/4ec93eeb-8795-44e5-9ba8-c6065adf4660" />

GreenOvercast is a native Xbox Cloud Gaming client for small ARM64 Linux
handhelds. It streams at 720p and uses hardware video decoding on supported
H700 and Rockchip firmware.

Built for the Anbernic RG35XX-H (muOS) and validated on the RG40XX-H (Knulli).
handhelds. It requests a stream matching the device display and uses hardware
video decoding on supported H700 and Rockchip firmware.

This independent project is not affiliated with or endorsed by Microsoft.

Expand All @@ -23,41 +21,43 @@ GreenOvercast from Ports.

The first launch shows a Microsoft device code. Open
[microsoft.com/link](https://www.microsoft.com/link) on another device and enter
the code to sign in. Knulli asks you to sign in again after a reboot.
the code to sign in.

GreenOvercast is experimental.

## Controls

| Button | Action |
| ------------------ | ------------------------------------------- |
| D-pad / Left Stick | Navigate |
| A | Select |
| B | Back |
| X | Open search / delete a letter |
| Y | Change aspect ratio / clear search |
| L1 / R1 | Xbox LB / RB |
| L2 / R2 | Xbox LT / RT |
| Start | Apply search / Xbox Menu |
| Select | Xbox View |
| L3 + R3 | Xbox Guide |
| Select + Start | Exit GreenOvercast after holding one second |

In-game controls use the standard Xbox controller layout.

The aspect-ratio setting applies to the next game you start. Most games only
support 16:9.
| Button | Library / menus | In game |
| ------------------ | --------------------------------- | --------------------------------- |
| D-pad / Left Stick | Navigate; hold to scroll faster | Movement |
| A | Select, play, or type | Xbox A |
| B | Back or cancel | Xbox B |
| X | Search or delete a letter | Xbox X |
| Y | Favorite a game or clear search | Xbox Y |
| L1 / R1 | Switch All / Favorites | Xbox LB / RB |
| L2 / R2 | Jump by first letter | Xbox LT / RT |
| Start | Settings or apply search | Xbox Menu |
| Select | — | Xbox View |
| L3 + R3 | — | Xbox Guide |
| Select + Start | Exit after holding for one second | Exit after holding for one second |

Settings include Xbox/Nintendo face-button layouts, game artwork, and Sign
out. Games that return a 16:9 stream remain letterboxed on 4:3 displays.

## Supported devices

| Device | OS | Status |
| -------- | -------------------- | ------ |
| RG35XX-H | muOS 2508.4 | Tested |
| RG40XX-H | Knulli (Batocera 42) | Tested |
| Device | OS | Status |
| ---------- | ------------------------------- | ------ |
| RG35XX-H | muOS 2508.4 | Tested |
| RG40XX-H | Knulli (Batocera 42) | Tested |
| RG40XX-H | ROCKNIX 20260801 | Tested |
| Miyoo Flip | SpruceOS 4.2.0 | Tested |
| R36S | AmberELEC prerelease-20250515 | Tested |

Rockchip MPP decoding also works on ROCKNIX, but support depends on the device
and firmware. Other devices fall back to software decoding, which is too slow
for normal gameplay.
Hardware decoding is verified on the H700 systems above. muOS and Knulli use
CedarX; ROCKNIX 20260801 uses the bundled Cedrus modules. Tested Rockchip builds
use Rockchip MPP on RK3566 with SpruceOS and RK3326 with AmberELEC. Other
devices fall back to software decoding, which is too slow for normal gameplay.

The release requires glibc 2.38 or newer. ArkOS ships glibc 2.30 and is not
supported.
Expand All @@ -68,26 +68,23 @@ You need a Linux or macOS host with `cmake`, `curl`, `git`, `make`, `patch`,
`perl`, and `python3`.

```sh
tools/bootstrap.sh # fetch Zig 0.14.1
tools/zig.sh build smoke # cross-build the aarch64 smoke binary
tools/zig.sh build product-check # compile the Zig product modules
tools/zig.sh build test # host unit tests
tools/zig.sh build fmt-check # format check
tools/bootstrap.sh
tools/zig.sh build
tools/zig.sh build test
tools/zig.sh build fmt-check
```

Build the release and PortMaster package with:
Build the PortMaster package with:

```sh
tools/build-release.sh
PORTMASTER_NEW=/path/to/PortMaster-New tools/package-portmaster.sh
PORTMASTER_NEW=/path/to/PortMaster-New tools/zig.sh build package
```

I would recommend using a sparse checkout of [PortMaster-New](https://github.com/PortsMaster/PortMaster-New) because
she's a big one. [Here is a great guide made by JeodC to help you with that](https://gist.github.com/JeodC/7a51211ad94ad6084d14042d80a62549).
PortMaster-New is large. [JeodC's sparse-checkout guide](https://gist.github.com/JeodC/7a51211ad94ad6084d14042d80a62549)
shows how to fetch only the files needed for packaging.

`package-portmaster.sh` runs the current PortMaster-New checks and archive
builder. To queue the finished archive for PortMaster's supported autoinstall
flow:
The package build runs the current PortMaster checks and archive builder. To
queue the finished archive for PortMaster's supported autoinstall flow:

```sh
tools/deploy.sh <ssh-host> zig-out/greenovercast.zip
Expand Down
6 changes: 4 additions & 2 deletions THIRDPARTY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Third-party licenses

GreenOvercast is MPL-2.0. The libraries below are linked or bundled into the
GreenOvercast is MPL-2.0. The components below are linked or bundled into the
release. Full license texts for the bundled libraries ship alongside the port in
`packaging/portmaster/greenovercast/greenovercast/licenses/`.

Expand All @@ -13,8 +13,10 @@ release. Full license texts for the bundled libraries ship alongside the port in
| [nlohmann/json](https://github.com/nlohmann/json) | MIT | JSON support used by libdatachannel (header-only) |
| [plog](https://github.com/SergiusTheBest/plog) | MIT | Logging used by libdatachannel (header-only) |
| [CedarX](https://github.com/allwinner-zh/media-codec) (Allwinner H.264 decoder) | LGPLv2.1-or-later | Hardware H.264 decode (shared) |
| [Linux Cedrus](https://www.kernel.org/) (7.0.11) | GPL-2.0-only | ROCKNIX H700 V4L2 Request decoder modules |
| [Rockchip MPP](https://github.com/rockchip-linux/mpp) (v1.1.0) | Apache-2.0/MIT | Optional Rockchip H.264 decode (shared) |
| [FFmpeg](https://ffmpeg.org/) (libavcodec, libavutil, libswscale) | LGPLv2.1-or-later | Software H.264 fallback and color conversion (shared) |
| [FFmpeg](https://ffmpeg.org/) (libavcodec, libavutil, libswscale) | LGPLv2.1-or-later | H.264 decode, JPEG artwork, and color conversion |
| [libudev-zero](https://github.com/illiliti/libudev-zero) | ISC | V4L2 media-device discovery (static) |
| [SDL2](https://www.libsdl.org/) | Zlib | Window, renderer, audio, and controller input (device) |
| [OpenSSL](https://www.openssl.org/) | Apache-2.0 | TLS, WebRTC DTLS, and credential encryption (static) |
| [libcurl](https://curl.se/) | curl (MIT-style) | HTTP for Xbox services (static) |
Expand Down
Loading
Loading