diff --git a/docs/user/AlterDateTime.md b/docs/user/AlterDateTime.md index 43bd3ed7b1..aeffa1a548 100644 --- a/docs/user/AlterDateTime.md +++ b/docs/user/AlterDateTime.md @@ -1,6 +1,6 @@ # Setting a Custom Date/Time in Eden -Use this guide whenever you want to modify the Date or Time that Eden reports to games. This can be useful for modifying RNG elements, skipping wait times in games, etc. +Use this guide whenever you want to modify the Date or Time that Eden reports to games. This can be useful for modifying RNG elements, skipping wait times in games, etc. **Click [Here](https://evilperson1337.notion.site/Setting-a-Custom-Date-Time-in-Eden-2b357c2edaf680acb8d4e63ccc126564) for a version of this guide with images & visual elements.** @@ -16,5 +16,5 @@ Use this guide whenever you want to modify the Date or Time that Eden reports to 1. Navigate to *Emulation → Configure*. 2. Click on the **System** item on the left-hand side navigation, then check the *Custom RTC Date* box. -3. The Date/Time option now becomes editable. Set it to the value you want and hit **OK**. -4. GREAT SCOTT! We have time traveled! You can of course go forward or backward in time (as long as it is not before the year 1970) and your game should update accordingly (e.g. certain *Super Mario Odyssey* moons that take time for flowers to grow will now be fully grown.). \ No newline at end of file +3. The Date/Time option now becomes editable. Set it to the value you want and hit **OK**. +4. GREAT SCOTT! We have time traveled! You can of course go forward or backward in time (as long as it is not before the year 1970) and your game should update accordingly (e.g. certain *Super Mario Odyssey* moons that take time for flowers to grow will now be fully grown.). \ No newline at end of file diff --git a/docs/user/Basics.md b/docs/user/Basics.md index 5101f4d9c3..794a0935d5 100644 --- a/docs/user/Basics.md +++ b/docs/user/Basics.md @@ -16,6 +16,15 @@ The CPU must support FMA for an optimal gameplay experience. The GPU needs to su If your GPU doesn't support or is just behind by a minor version, see Mesa environment variables below (*nix only). +## Releases and versions + +- Stable releases/Versioned releases: Has a version number and it's the versions we expect 3rd party repositories to host (package managers and such), these are, well, stable, have low amount of regressions (wrt. to master and nightlies) and generally focus on "keeping things without regressions", recommended for the average user. + - RC releases: Release candidate, generally "less stable but still stable" versions. + - Full release: "The stablest possible you could get". +- Nightly: Builds done around 2PM UTC (if there are any changes), generally stable, but not recommended for the average user. These contain daily updates and may contain critical fixes for some games. +- Master: Unstable builds, can lead from a game working exceptionally fine to absolute crashing in some systems because someone forgot to check if NixOS or Solaris worked. These contain straight from the oven fixes, please don't use them unless you plan to contribute something! They're very experimental! Still 95% of the time it will work just fine. +- PR builds: Highly experimental builds, testers may grab from these. The average user should treat them the same as master builds, except sometimes they straight up don't build/work. + ## User configuration ### Configuration directories diff --git a/docs/user/ControllerProfiles.md b/docs/user/ControllerProfiles.md deleted file mode 100644 index 3b4898f447..0000000000 --- a/docs/user/ControllerProfiles.md +++ /dev/null @@ -1,49 +0,0 @@ -# Configuring Controller Profiles - -Use this guide for when you want to configure specific controller settings to be reused. - -**Click [Here](https://evilperson1337.notion.site/Configuring-Controller-Profiles-2be57c2edaf680eabc3ac8c333ec75c4) for a version of this guide with images & visual elements.** - ---- - -### Pre-Requisites - -- Eden Set Up and Configured - ---- - -### Steps -1. Launch Eden and wait for it to load. -2. Navigate to *Emulation > Configure…* -3. Select **Controls** from the left-hand menu and configure your controller for the way you want it to be in game. -4. Select **New** and enter a name for the profile in the box that appears. Press **OK** to save the profile settings. -5. Select **OK** to close the settings menu. - -## Setting Controller Profiles By Game - -Use this guide when you want to set up specific controller profiles for specific games. This can be useful for certain games like *Captain Toad Treasure Tracker* where a blue dot appears in the middle of the screen when you have docked mode enabled, but not handheld mode. - -**Click [Here](https://evilperson1337.notion.site/Setting-Controller-Profiles-By-Game-2b057c2edaf681658a57f0c199cb6083) for a version of this guide with images & visual elements.** - ---- - -### Pre-Requisites - -- Eden Emulator set up and fully configured -- Controller Profile Created - - See [*Configuring Controller Profiles*](./ControllerProfiles.md) for instructions on how to do this if needed. - ---- - -### Steps - -1. *Right-Click* the game you want to apply the profile to in the main window and select **Properties.** -2. Navigate to the **Input Profiles** tab in the window that appears. Drop down on *Player 1 profile* (or whatever player profile you want to apply it to) and select the profile you want. - - -1. Click **OK** to apply the profile mapping. -2. Launch the game and confirm that the profile is applied, regardless of what the global configuration is. diff --git a/docs/user/Controllers.md b/docs/user/Controllers.md new file mode 100644 index 0000000000..6aac9056ff --- /dev/null +++ b/docs/user/Controllers.md @@ -0,0 +1,65 @@ +# User Handbook - Controllers + +Most of the controls should work out of the box. If not, please use a joystick calibrator to ensure it's not an issue with your own controller, for example: + +- https://github.com/dkosmari/calibrate-joystick + +## Using external controllers on the Steamdeck + +In desktop mode ignore your pro controller/xbox contoller external controller and use **Steam Virtual Gamepad 0 as Player 1**. If you have multiple external controllers set **Player 2 to Steam Virtual Gamepad 1**. Steam app must not be closed on desktop mode. + +Here's the annoying part of it. When waking up the steam deck from sleep try not to touch any button on the Steamdeck and turn on your external controller. Then open the Eden.AppImage. If you're lucky you can get your external controller to be position 0 and also Steam Virtual Gamepad 0 in desktop mode. If not that is ok too unless you need to configure player 1 to have gyro. You might need to repeat this to get your external controller as Steam Virtual Gamepad 0 so you can config Player 1 having gyro. You might be able to config player 1 to have gyro with the Steamdeck itself. Or you can also config player 1, 2, 3, etc, to have gyro somehow. Make sure they are all using Virtual Gamepads though. + +Turn off controller then go to gaming mode. Try not to touch any buttons on the physical Steamdeck. When in gaming mode turn on the external controller. If lucky it will be assigned as Steam Virtual Gamepad 0. If not just use steam Gamemode feature to rearrange controller positions order. + +Basically the Steamdeck or the external controller is fighting for position 0 and it depends on what is touched first after waking from sleep. + +## Configuring Controller Profiles + +Use this guide for when you want to configure specific controller settings to be reused. + +**Click [Here](https://evilperson1337.notion.site/Configuring-Controller-Profiles-2be57c2edaf680eabc3ac8c333ec75c4) for a version of this guide with images & visual elements.** + +--- + +#### Pre-Requisites + +- Eden Set Up and Configured + +--- + +#### Steps +1. Launch Eden and wait for it to load. +2. Navigate to *Emulation > Configure…* +3. Select **Controls** from the left-hand menu and configure your controller for the way you want it to be in game. +4. Select **New** and enter a name for the profile in the box that appears. Press **OK** to save the profile settings. +5. Select **OK** to close the settings menu. + +### Setting Controller Profiles By Game + +Use this guide when you want to set up specific controller profiles for specific games. This can be useful for certain games like *Captain Toad Treasure Tracker* where a blue dot appears in the middle of the screen when you have docked mode enabled, but not handheld mode. + +**Click [Here](https://evilperson1337.notion.site/Setting-Controller-Profiles-By-Game-2b057c2edaf681658a57f0c199cb6083) for a version of this guide with images & visual elements.** + +--- + +#### Pre-Requisites + +- Eden Emulator set up and fully configured +- Controller Profile Created + - See [*Configuring Controller Profiles*](./ControllerProfiles.md) for instructions on how to do this if needed. + +--- + +#### Steps + +1. *Right-Click* the game you want to apply the profile to in the main window and select **Properties.** +2. Navigate to the **Input Profiles** tab in the window that appears. Drop down on *Player 1 profile* (or whatever player profile you want to apply it to) and select the profile you want. + + +1. Click **OK** to apply the profile mapping. +2. Launch the game and confirm that the profile is applied, regardless of what the global configuration is. diff --git a/docs/user/README.md b/docs/user/README.md index 9804f4d62f..c1c4cd200a 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -11,10 +11,12 @@ A copy of this handbook is [available online](https://git.eden-emu.dev/eden-emu/ - **[The Basics](Basics.md)** - **[Quickstart](./QuickStart.md)** - **[Settings](./Settings.md)** -- **[Installing Mods](./Mods.md)** -- **[Run On macOS](./RunOnMacOS.md)** +- **[Controllers](./Controllers.md)** + - **[Controller profiles](./Controllers.md#configuring-controller-profiles)** - **[Audio](Audio.md)** - **[Graphics](Graphics.md)** +- **[Installing Mods](./Mods.md)** +- **[Run On macOS](./RunOnMacOS.md)** - **[Data, Savefiles and Storage](Storage.md)** - **[Orphaned Profiles](Orphaned.md)** - **[Troubleshooting](./Troubleshoot.md)** @@ -23,7 +25,6 @@ A copy of this handbook is [available online](https://git.eden-emu.dev/eden-emu/ - **[Importing Saves](./ImportingSaves.md)** - **[Installing Atmosphere Mods](./InstallingAtmosphereMods.md)** - **[Installing Updates & DLCs](./InstallingUpdatesDLC.md)** -- **[Controller Profiles](./ControllerProfiles.md)** - **[Alter Date & Time](./AlterDateTime.md)** ## 3rd-party Integration @@ -35,6 +36,7 @@ A copy of this handbook is [available online](https://git.eden-emu.dev/eden-emu/ - **[Obtainium](./ThirdParty.md#configuring-obtainium)** - **[ES-DE](./ThirdParty.md#configuring-es-de)** - **[Mirrors](./ThirdParty.md#mirrors)** + - **[GameMode](./ThirdParty.md#configuring-gamemode)** ## Advanced diff --git a/docs/user/RunOnMacOS.md b/docs/user/RunOnMacOS.md index e01bf0253d..2729e13ced 100644 --- a/docs/user/RunOnMacOS.md +++ b/docs/user/RunOnMacOS.md @@ -1,4 +1,12 @@ -# Allowing Eden to Run on MacOS +# User Handbook - Run on macOS + +Current macOS support is still experimental and very reliant on MoltenVK developments, plans have shifted to properly provide support for KosmicKrisp and similar new GPU endeavours, but macOS users still are bound to MoltenVK itself. + +Users of macOS may wish to use [Asahi Linux](https://wiki.gentoo.org/wiki/Project:Asahi/Guide) for the rising KosmicKrisp support. + +As of writing, neither macOS nor Asahi has support for NCE; additionally Asahi has extraneous paging bugs with fastmem. + +## Allowing Eden to Run on MacOS Use this guide when you need to allow Eden to run on a Mac system, but are being blocked by Apple Security policy. @@ -6,19 +14,19 @@ Use this guide when you need to allow Eden to run on a Mac system, but are being --- -### Pre-Requisites +#### Pre-Requisites - Permissions to modify settings in MacOS --- -## Why am I Seeing This? +### Why am I Seeing This? Recent versions of MacOS (Catalina & newer) introduced the **Gatekeeper** security functionality, requiring software to be signed by Apple or a trusted (aka - paying) developer. If the signature isn’t on the list of trusted ones, it will stop the program from executing and display the message above. --- -## Steps +### Steps 1. Open the *System Settings* panel. 2. Navigate to *Privacy & Security*. diff --git a/docs/user/Settings.md b/docs/user/Settings.md index 35fcd0c9ef..9153a27e4d 100644 --- a/docs/user/Settings.md +++ b/docs/user/Settings.md @@ -50,5 +50,4 @@ See also [an extended breakdown of some options](./Graphics.md). ## Controls -Most of the controls should work out of the box. If not, please use a joystick calibrator to ensure it's not an issue with your own controller, for example: -- https://github.com/dkosmari/calibrate-joystick +See [controllers](./Controllers.md). diff --git a/docs/user/Testing.md b/docs/user/Testing.md index 6c3b7d3e15..eb3beeb37c 100644 --- a/docs/user/Testing.md +++ b/docs/user/Testing.md @@ -1,39 +1,99 @@ -# User Handbook - Testing +# Testing -While this is mainly aimed for testers - normal users can benefit from these guidelines to make their life easier when trying to outline and/or report an issue. +When you're testing a pull request (PR) and encounter unexpected behavior, it's important to determine whether the issue was introduced by the PR or if it already exists in the base code. To do this, compare the behavior against the based master branch. -## Getting logs +Even before an issue occurs, it is best practice to keep the same settings and delete the shader cache. Using an already made shader cache can make the PR look like it is having a regression in some rare cases. -In order to get more information, you can find logs in the following location: +Try not to test PRs which are for documentation or extremely trivial changes (like a PR that changes the app icon), unless you really want to; generally avoid any PRs marked `[docs]`. +If a PR specifies it is for a given platform (i.e `linux`) then just test on Linux. If it says `NCE` then test on Android and Linux ARM64 (Raspberry Pi and such). macOS fixes may also affect Asahi, test that if you can too. -## How to Test a PR Against the Based Master When Issues Arise +You may also build artifacts yourself, be aware that the resulting builds are NOT the same as those from CI, because of package versioning and build environment differences. One famous example is FFmpeg randomly breaking on many Arch distros due to packaging differences. -When you're testing a pull request (PR) and encounter unexpected behavior, it's important to determine whether the issue was introduced by the PR or if it already exists in the base code. To do this, compare the behavior against the based master branch. +## Quickstart -Even before an issue occurs, it is best practice to keep the same settings and delete the shader cache. Using an already made shader cache can make the PR look like it is having a regression in some rare cases. +Think of the source code as a "tree", with the "trunk" of that tree being our `master` branch, any other branches are PRs or separate development branches, only our stable releases pull from `master` - all other branches are considered unstable and aren't recommended to pull from unless you're testing multiple branches at once. + +Here's some terminology you may want to familiarize yourself with: + +- PR: Pull request, a change in the codebase; from which the author of said change (the programmer) requests a pull of that branch into master (make it so the new code makes it into a release basically). +- Bisect: Bilinear method of searching regressions, some regressions may be sporadic and can't be bisected, but the overwhelming majority are. +- WIP: Work-in-progress. +- Regression: A new bug/glitch caused by new code, i.e "Zelda broke in android after commit xyz". +- Master: The "root" branch, this is where all merged code goes to, traditionally called `main`, `trunk` or just `master`, it contains all the code that eventually make it to stable releases. +- `HEAD`: Latest commit in a given branch, `HEAD` of `master` is the latest commit on branch `master`. +- `origin`: The default "remote", basically the URL from where git is located at, for most of the time that location is https://git.eden-emu.dev/eden-emu/eden. + +## Testing checklist + +For regressions/bugs from PRs or commits: + +- [ ] Occurs in master? + - If it occurs on master: + - [ ] Occurs on previous stable release? (before this particular PR). + - If it occurs on previous stable release: + - [ ] Occurs on previous-previous stable release? + - And so on and so forth... some bugs come from way before Eden was even conceived. + - Otherwise, try bisecting between the previous stable release AND the latest `HEAD` of master + - [ ] Occurs in given commit? +- [ ] Occurs in PR? + - If it occurs on PR: + - [ ] Bisected PR? (if it has commits) + - [ ] Found bisected commit? + +If an issue sporadically appears, try to do multiple runs, try if possible, to count the number of times it has failed and the number of times it has "worked just fine"; say it worked 3 times but failed 1. then there is a 1/4th chance every run that the issue is replicated - so every bisect step would require 4 runs to ensure there is atleast a chance of triggering the bug. + +## What to do when something seems off -### What to Do When Something Seems Off If you notice something odd during testing: + - Reproduce the issue using the based master branch. - Observe whether the same behavior occurs. -### Two Possible Outcomes +From there onwards there can be two possible outcomes: + - If the issue exists in the based master: This means the problem was already present before the PR. The PR most likely did not introduce the regression. - If the issue does not exist in the based master: This suggests the PR most likely introduced the regression and needs further investigation. -### Report your findings +## Reporting Your Findings + When you report your results: + - Clearly state whether the behavior was observed in the based master. -- Indicate whether the result is good (expected behavior) or bad (unexpected or broken behavior). Without mentioning if your post/report/log is good or bad it may confuse the Developer of the PR. -- Example: -``` -1. "Tested on based master — issue not present. Bad result for PR, likely regression introduced." -2. "Tested on based master — issue already present. Good result for PR, not a regression." -``` +- Indicate whether the result is good (expected behavior) or bad (unexpected or broken behavior). Without mentioning if your post/report/log is good or bad it may confuse the developer of the PR. + +For example: + +1. "Bad result for PR: Tested on based master - issue not present. Likely regression introduced." +2. "Good result for PR: Tested on based master - issue already present. Not a regression." + +This approach helps maintain clarity and accountability in the testing process and ensures regressions are caught and addressed efficiently. + +If the behavior seems normal for a certain game/feature then it may not be always required to check against the based master. This approach helps maintain clarity and accountability in the testing process and ensures regressions are caught and addressed efficiently. If the behavior seems normal for a certain game/feature then it may not be always required to check against the based master. If a master build for the PR' based master does not exist. It will be helpful to just test past and future builds nearby. That would help with gathering more information about the problem. -**Always include [debugging info](../Debug.md) as needed**. \ No newline at end of file +**Always include [debugging info](../Debug.md) as needed**. + +## Bisecting + +One happy reminder, when testing, *know how to bisect!* + +Say you're trying to find an issue between 1st of Jan and 8th of Jan, you can search by dividing "in half" the time between each commit: +- Check for 4th of Jan +- If 4th of Jan is "working" then the issue must be in the future +- So then check 6th of Jan +- If 6th of Jan isn't working then the issue must be in the past +- So then check 5th of Jan +- If 5th of Jan worked, then the issue starts at 6th of Jan + +The faulty commit then, is 6th of Jan. This is called bisection https://git-scm.com/docs/git-bisect + +## Notes + +- PR's marked with **WIP** do NOT need to be tested unless explicitly asked (check the git in case) +- Sometimes license checks may fail, hover over the build icon to see if builds did succeed, as the CI will push builds even if license checks fail. +- All open PRs can be viewed [here](https://git.eden-emu.dev/eden-emu/eden/pulls/). +- If site is down use one of the [mirrors](./user/ThirdParty.md#mirrors). diff --git a/docs/user/ThirdParty.md b/docs/user/ThirdParty.md index 083542cd3e..5bd72ebe72 100644 --- a/docs/user/ThirdParty.md +++ b/docs/user/ThirdParty.md @@ -4,7 +4,6 @@ The Eden emulator by itself lacks some functionality - or otherwise requires ext While most of the links mentioned in this guide are relatively "safe"; we urge users to use their due diligence and appropriatedly verify the integrity of all files downloaded and ensure they're not compromised. -- [Nightly Eden builds](https://github.com/pflyly/eden-nightly) - [NixOS Eden Flake](https://github.com/Grantimatter/eden-flake) - [ES-DE Frontend Support](https://github.com/GlazedBelmont/es-de-android-custom-systems) @@ -66,3 +65,9 @@ Note: Even though the site isn't Codeberg, it uses the same Forgejo/Gitea backen ```xml %EMULATOR_EDEN% %ACTION%=android.nfc.action.TECH_DISCOVERED %DATA%=%ROMPROVIDER% ``` + +## Configuring GameMode + +There is a checkbox to enable gamemode automatically. The `libgamemode.so` library must be findable on the standard `LD_LIBRARY_PATH` otherwise it will not properly be enabled. If for whatever reason it doesn't work, see [Arch wiki: GameMode](https://wiki.archlinux.org/title/GameMode) for more info. + +You may launch the emulator directly via the wrapper `gamemode `, and things should work out of the box.