diff --git a/.github/workflows/fork-windows-release.yml b/.github/workflows/fork-windows-release.yml index f93b4bb10d..d8adc2cc6e 100644 --- a/.github/workflows/fork-windows-release.yml +++ b/.github/workflows/fork-windows-release.yml @@ -90,6 +90,6 @@ jobs: kind: stable tag: ${{ needs.prepare.outputs.tag }} title: Frameropia ${{ needs.prepare.outputs.tag }} (test build) - prerelease: true + prerelease: false sha: ${{ needs.prepare.outputs.sha }} branch: nx2 diff --git a/CHANGELOG.md b/CHANGELOG.md index 45f71fc461..b398b961f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,14 +2,18 @@ All notable changes to Frameropia are documented here. Each release's notes are taken from its `## [X.Y.Z]` section (release candidates use the section of the version they are a candidate for). -New entries go under `## [Unreleased] - -- Added OOT Compatibility (inherited) -- Improved MKW Performances (inherited) -- Added StarFox Compatibility (inherited) -- Less shader rebuilds (inherited) -- Changed dir from eden to eglantine (inherited) -- Overall better performances and fixes (inherited) +New entries go under `## [Unreleased]`. + +## [Unreleased] + +## [0.0.3] + +- **Pokémon Pokopia:** flush accelerated Switch 2 image-to-buffer DMA destinations to guest memory before completing the copy, greatly reducing photo corruption. Adapted from notsapinho/Eglantine commit `7dde4f15`. +- **Verified user testing:** 48/50 photos correct in the initial 50-photo series; sporadic corruption, especially the first photo after startup, remains a known issue. +- **New Frameropia logo:** add an orange-gradient F logo with transparent background for the README, Qt resources, and the Windows application icon. +- **README and documentation:** improve presentation, navigation, testing guidance and transparent patch notes. +- **Safer release scope:** exclude rejected experiments #16, #18, #19 and #20, which did not pass gameplay testing. +- **Compatibility:** preserve existing executable names and user-data/save directories. No claim of achieving the 60 FPS performance seen in notsapinho build 24. ## [0.0.2] diff --git a/README.md b/README.md index 2ad8bb28ba..722d81a210 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,58 @@ -# Frameropia +
+ Frameropia orange F logo +

Frameropia

+

An experimental Nintendo Switch 2 emulator fork with a focus on Pokémon Pokopia.

+

+ Latest release + GitHub issues + GPL-3.0-or-later +

+

+ Download · + v0.0.3 patch notes · + Testing guide · + Report an issue +

+
-**Frameropia** is an experimental, open-source Nintendo Switch 2 emulator fork focused on compatibility with **Pokémon Pokopia**. +--- -It is based on [Eglantine](https://github.com/Djihads80/Eglantine), which in turn builds on Eden, yuzu and other open-source work. Frameropia is independent and is not affiliated with Nintendo. +## About -> **Experimental software:** game compatibility, performance and graphical accuracy are not guaranteed. The original v0.0.1 test release predates the Frameropia branding changes; v0.0.2 introduces the new executable names. +Frameropia is an independent open-source fork of [Eglantine](https://github.com/Djihads80/Eglantine), building on the work of Eden, yuzu and their contributors. It currently prioritizes practical Pokémon Pokopia compatibility testing, while preserving the upstream project's broader functionality. -## Downloads and testing +> [!WARNING] +> **Experimental software.** Compatibility, image capture, frame rate and rendering are not guaranteed. The photo readback fix in v0.0.3 greatly improves reliability in user testing but **does not eliminate corruption**, especially on early captures after startup. -- [Releases](https://github.com/Framerr/Frameropia/releases) -- [Pokopia compatibility checklist](docs/POKOPIA_TESTING.md) -- [Report a Pokopia issue](https://github.com/Framerr/Frameropia/issues/new/choose) -- [Latest patch notes (v0.0.2)](docs/releases/v0.0.2.md) -- [Previous release notes (v0.0.1)](docs/releases/v0.0.1.md) -- [Repository rename and data compatibility](docs/FRAMEROPIA_RENAME.md) +## What's new in v0.0.3 -Only use game files and console data that you have legally obtained. Do not upload games, firmware or console keys to issues. +| Area | Change | +| :-- | :-- | +| 📸 **Pokopia photos** | Flush accelerated image-to-buffer DMA readbacks to guest memory before completing the transfer. | +| 🎨 **Branding** | New transparent orange **F** logo for this README and the Windows executable/Qt icon. | +| 🧪 **Testing** | Keep the validated readback change; exclude experimental patches that caused regressions. | +| 📝 **Documentation** | Clearer project overview and complete [technical and plain-English patch notes](docs/releases/v0.0.3.md). | -## Development +**Test evidence:** with the DMA fix, one initial set of 50 Pokopia photos yielded **48 correct and 2 corrupt**. Follow-up tests revealed remaining cold-start failures (the first photo failed in three independent startups) and occasional image displacement. These are **known issues**, not fixed in v0.0.3. See [issue #14](https://github.com/Framerr/Frameropia/issues/14). -See the [build guide](docs/Build.md), [CI/release guide](docs/CI.md) and [contribution guide](CONTRIBUTING.md). Please use English for issues, pull requests, code comments and documentation. +## Download and run -## Existing settings and saves +1. Get the Windows archive from [Releases](https://github.com/Framerr/Frameropia/releases). +2. Extract the **entire** ZIP to a folder. +3. Start `frameropia.exe`; `frameropia-cli.exe` is provided for command-line usage. -The fork currently retains Eden/Eglantine's internal data directories. This is intentional: renaming the GUI and binaries must not make existing configuration, installed content, or saves disappear. +Frameropia retains the existing Eden/Eglantine user-data locations so your settings and saves remain accessible. See the [rename and data compatibility guide](docs/FRAMEROPIA_RENAME.md). -## Credits and license +**Use only game and console files you have legally obtained.** Do not attach game files, firmware or console keys to issue reports. -Frameropia is derived from [Eglantine](https://github.com/Djihads80/Eglantine), with contributions originating in Eden, yuzu, Sudachi and other projects. +## Contribute and report bugs -Licensed under [GPL-3.0-or-later](LICENSE.txt), subject to the repository's existing license notices. +Use the [Pokopia testing checklist](docs/POKOPIA_TESTING.md) and [issue templates](https://github.com/Framerr/Frameropia/issues/new/choose) to report reproducible problems. Please provide steps, graphics hardware, settings, and logs where relevant. + +See the [build guide](docs/Build.md), [CI guide](docs/CI.md), and [contribution guide](CONTRIBUTING.md). Project contributions, bug reports and documentation should be in **English**. + +## Acknowledgements and license + +Frameropia is based on [Eglantine](https://github.com/Djihads80/Eglantine) with upstream contributions from Eden, yuzu, Sudachi and other open-source developers. The Pokémon Pokopia DMA readback correction was adapted from [notsapinho/Eglantine](https://github.com/notsapinho/Eglantine/commit/7dde4f158d4eedacf62172d619b4b2f8b5d48cdb). + +Distributed under [GPL-3.0-or-later](LICENSE.txt), alongside the existing source-level copyright and license notices. Frameropia is not affiliated with, sponsored by, or endorsed by Nintendo or The Pokémon Company. diff --git a/VERSION b/VERSION index 4e379d2bfe..bcab45af15 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.2 +0.0.3 diff --git a/dist/frameropia-logo.png b/dist/frameropia-logo.png new file mode 100644 index 0000000000..78a913d7bc Binary files /dev/null and b/dist/frameropia-logo.png differ diff --git a/dist/frameropia.ico b/dist/frameropia.ico new file mode 100644 index 0000000000..f9aac30704 Binary files /dev/null and b/dist/frameropia.ico differ diff --git a/docs/releases/v0.0.3.md b/docs/releases/v0.0.3.md new file mode 100644 index 0000000000..2a41c67ea1 --- /dev/null +++ b/docs/releases/v0.0.3.md @@ -0,0 +1,62 @@ +# Frameropia v0.0.3 — Patch Notes + +**Pokémon Pokopia photo reliability update and new Frameropia identity.** + +This release is based on v0.0.2 plus the **user-validated DMA readback flush** from draft PR #17 (merged as [777181dd](https://github.com/Framerr/Frameropia/commit/777181dd785549b026ae716538ef09be71d0ee19)). It does **not** include the experimental photo and performance patches rejected during testing. + +## Technical changes + +### Pokémon Pokopia: improved photo readback + +- After an accelerated Switch 2 DMA **image-to-buffer** copy succeeds, flush the destination buffer region to guest memory before the operation completes. +- This makes the photo data available to the game's CPU-side image encoding path, preventing many cases where stale pixels or rows were saved. +- Keep the behavior scoped to Switch 2, and retain an opt-out for diagnostic comparison: `EDEN_NX2_DMA_READBACK_FLUSH=0`. +- Credit: adaptation of [notsapinho/Eglantine commit 7dde4f15](https://github.com/notsapinho/Eglantine/commit/7dde4f158d4eedacf62172d619b4b2f8b5d48cdb). + +### New application branding + +- Add a transparent orange-gradient **F** logo, displayed in the README. +- Replace the Windows executable's embedded application icon and the Qt icon resource with the Frameropia logo. +- Keep the application and command-line executable names `frameropia.exe` and `frameropia-cli.exe`. + +### Documentation and testing + +- Redesign the README with clearer download, testing, compatibility and attribution sections. +- Document observed photo results and explicitly list outstanding first-capture issues. +- Preserve the artifact-only Windows CI workflow for isolated graphics experiments. + +## Validation + +The user tested a Windows build containing the DMA fix, with **48 correct pictures out of 50** in the initial series (96% correct). Subsequent testing showed that some photos still fail, especially immediately after starting the emulator. In three independent startup sessions, the first photograph was corrupt in **all three**; in one session the second photograph was corrupt too. A separate rapid-capture test saw an image shifted vertically with wraparound. + +**Interpretation:** photo reliability has improved greatly, but **the bug is not fully fixed**. These figures are observations from one tester and should not be treated as universal success rates. + +## Excluded changes + +The following experiments were **not merged** and are not part of v0.0.3: + +| Test / PR | Reason for exclusion | +| --- | --- | +| [#16](https://github.com/Framerr/Frameropia/pull/16) — generic buffer readback range clipping | All tested photos became corrupt. | +| [#18](https://github.com/Framerr/Frameropia/pull/18) — direct linear texture uploads | No noticeable performance gain in user testing; did not include the photo fix. | +| [#19](https://github.com/Framerr/Frameropia/pull/19) — deferred texture uploads | No noticeable performance gain and severe bright-pink sky rendering regression. | +| [#20](https://github.com/Framerr/Frameropia/pull/20) — initial photo DMA CPU fallback | All tested photos became corrupt. | + +No claim is made that this release independently achieves 60 FPS. The steady 60 FPS previously observed on **notsapinho's build 24** involved additional changes that have **not** been validated or integrated into Frameropia. + +## Known limitations + +- Pokémon Pokopia's **first photo after a fresh emulator start** can be corrupt; occasionally a second photo is affected. +- Rare photo corruption and vertical wraparound can still occur. +- Shader compilation as a contributor to the remaining photo failures is **unproven**. +- No guarantee of fixes for other game-specific graphical bugs or performance regressions. + +Track remaining photo issues in [#14](https://github.com/Framerr/Frameropia/issues/14). + +## Plain-English summary + +**Frameropia has a new orange F logo and takes Pokémon Pokopia photos far more reliably.** The most successful test produced **48 good photos out of 50**, compared with the much worse behavior seen before the correction. It's a real improvement, but the first photo after opening the game can still be broken. + +We've intentionally **left out** several attempted fixes that caused worse photos or graphical problems. Your old settings and saved games should remain in the same locations. + +Download the Windows ZIP from [Releases](https://github.com/Framerr/Frameropia/releases), extract the entire archive, and run `frameropia.exe`. diff --git a/src/yuzu/yuzu.qrc b/src/yuzu/yuzu.qrc index 3065d22f34..a08a18ad0c 100644 --- a/src/yuzu/yuzu.qrc +++ b/src/yuzu/yuzu.qrc @@ -5,6 +5,6 @@ SPDX-License-Identifier: GPL-2.0-or-later - ../../dist/eden.ico + ../../dist/frameropia.ico diff --git a/src/yuzu/yuzu.rc b/src/yuzu/yuzu.rc index a3dc62109f..2a5f0e99e3 100644 --- a/src/yuzu/yuzu.rc +++ b/src/yuzu/yuzu.rc @@ -11,7 +11,7 @@ // remains consistent on all systems. // QT requires that the default application icon is named IDI_ICON1 -IDI_ICON1 ICON "../../dist/eden.ico" +IDI_ICON1 ICON "../../dist/frameropia.ico" /////////////////////////////////////////////////////////////////////////////