[main] Readme improvements

CHANGELOG.md

@@ -1,16 +1,17 @@
-Rolling release built from latest commit on main branch.  
+# Rolling release
+built from latest commit on main branch.  
 **Note**: the attached source code files may be out of date.
 
-For the SummerCart64, use the `sc64menu.n64` file in the root of your SD card.
-For the 64Drive, use the `menu.bin` file in the root of your SD card.
-For the ares emulator, use the `N64FlashcartMenu.n64` file.
+- For the SummerCart64, use the `sc64menu.n64` file in the root of your SD card.
+- For the 64Drive, use the `menu.bin` file in the root of your SD card.
+- For the ares emulator, use the `N64FlashcartMenu.n64` file.
 
-# Release Notes 2025-01-10
+## Release Notes 2025-01-10
 
 - **Bug Fixes**
 	- Fixed menu display (PAL60) by reverted libdragon to a known working point and re-applying old hacks.
 
-## Current known Issues
+### Current known Issues
 * The RTC UI requires improvement (awaiting UI developer).
 * Menu sound FX may not work properly when a 64 Disk Drive is also attached (work around: turn sound FX off).
 [Pre-release menu]:
@@ -19,7 +20,7 @@ For the ares emulator, use the `N64FlashcartMenu.n64` file.
 * ALPHA_FEATURE: ED64 V Series only supports loading ROMs (however this is not a problem as not tag released asset).
 
 
-# Release Notes 2024-12-30
+## Release Notes 2024-12-30
 
 - **New Features**
 	- Introduced menu sound effects for enhanced user experience (the default is off).
@@ -51,12 +52,12 @@ For the ares emulator, use the `N64FlashcartMenu.n64` file.
 	- Streamlined the loading state management for ROMs and disks within the menu system.
 	- Improved clarity and usability of the developer guide and other documentation files.
 
-## Current known Issues
+### Current known Issues
 * BETA_SETTING: PAL60 when using HDMI mods has regressed (awaiting libdragon fix).
 * The RTC UI requires improvement (awaiting UI developer).
 * Menu sound FX may not work properly when a 64 Disk Drive is also attached (work around: turn sound FX off).
 * ALPHA_FEATURE: ED64 X Series detection does not occur properly (however this is not a problem as not tag released asset).
 * ALPHA_FEATURE: ED64 V Series only supports loading ROMs (however this is not a problem as not tag released asset).
 
-## Breaking changes
+### Breaking changes
 * Disk drive expansion ROMs are now loaded with `Z|L` instead of `R` to align with ROM info context menu (and future functionality).

CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing to N64FlashcartMenu
+
+This document is for people wanting to contribute to the implementation of N64FlashcartMenu.
+This involves interacting with implementation changes that are proposed using [GitHub](https://github.com/) [pull requests](https://docs.github.com/pull-requests) to the [N64FlashcartMenu](https://github.com/Polprzewodnikowy/N64FlashcartMenu/) repository (which you're in right now).
+
+As such, a GitHub account is recommended, which you can sign up for [here](https://github.com/signup).
+
+Additionally this document assumes that you already know how to use GitHub and Git.
+If that's not the case, we recommend learning about it first [here](https://docs.github.com/en/get-started/quickstart/hello-world).
+
+**Help us by creating a PR.**

Doxyfile

@@ -1002,7 +1002,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = ./docs/images
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program

README.md

@@ -1,25 +1,35 @@
 ![Build](https://github.com/polprzewodnikowy/N64FlashcartMenu/actions/workflows/build.yml/badge.svg)
+![GitHub Org's stars](https://img.shields.io/github/stars/Polprzewodnikowy/N64FlashcartMenu)
+[![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/Polprzewodnikowy/N64FlashcartMenu.svg)](http://isitmaintained.com/project/Polprzewodnikowy/N64FlashcartMenu "Average time to resolve an issue")
+[![Percentage of issues still open](http://isitmaintained.com/badge/open/Polprzewodnikowy/N64FlashcartMenu.svg)](http://isitmaintained.com/project/Polprzewodnikowy/N64FlashcartMenu "Percentage of issues still open")
+[![#yourfirstpr](https://img.shields.io/badge/first--timers--only-friendly-blue.svg)](https://github.com/Polprzewodnikowy/N64FlashcartMenu/CONTRIBUTING.md)
 
 # N64 Flashcart Menu
-An open source menu for N64 flashcarts.
+An open source menu for N64 flashcarts and aims to support as many as possible.  
+The menu is not affiliated with any partuclar flashcart and does not necessarily expose all capable firmware features. It MUST be updated independently of any (current) flashcart frmware.  
+
+**This project considers flashcart sellers that include this menu or copyrighted ROM's as part of their product offering as licence offenders which may result in future action.**  
+
+![example menu information](./docs/images/menu-information.png "example menu information") 
 
 ## Supported Flashcarts
+This menu aims to support as many N64 flashcarts as possible.
 
-### Fully supported
+### Supported
 * SummerCart64
 * 64Drive
 
-### Work in Progress
+### Work in Progress (pre-release only)
 * ED64
 * ED64P
 
 
 ## Current (notable) menu features
 * Fully Open Source.
-* Loads all known N64 games (including iQue and Aleck64 ROMs), even if they are byteswapped.
+* Loads all known N64 games, even if they are byteswapped.
 * Fully emulates the 64DD and loads 64DD disks (SummerCart64 only).
 * Emulator support (NES, SNES, GB, GBC, SMS, GG, CHF) ROMs.
-* N64 ROM box image support.
+* N64 ROM box art image support.
 * Background image (PNG) support.
 * Comprehensive ROM save database (including homebrew headers).
 * Comprehensive ROM information display.
@@ -36,14 +46,13 @@ An open source menu for N64 flashcarts.
 * [Developer guide](./docs/99_developer_guide.md)
 
 ## Video showcase (as of Oct 12 2023)
-
 [![N64FlashcartMenu Showcase](http://img.youtube.com/vi/6CKImHTifDA/0.jpg)](http://www.youtube.com/watch?v=6CKImHTifDA "N64FlashcartMenu Showcase (Oct 12 2023)")
 
 
 ## Aims
 * Support as many N64 FlashCarts as possible.
 * Be open source, using permissively licensed third-party libraries.
-* Be testable, using unit and smoke tests in ares emulated environment.
+* Be testable in an emulated environment (Ares).
 * Encourage active development from community members and N64 FlashCart owners.
 * Support as many common mods and features as possible.
 
@@ -52,9 +61,8 @@ An open source menu for N64 flashcarts.
 These features are subject to change:
 
 ### N64 ROM autoload
-To use the autoload function, while on the `N64 ROM information` display, press the `R` button on your joypad and select the `Set ROM to autoload` option. When you restart the console, it will now only load the selected ROM rather than the menu.
-The autoload setting is stored in `config.ini` and persists until changed. This feature may slightly increase boot time as the menu needs to check for the Start button state.
-NOTE: To return to the menu, hold the joypad `Start` button while powering on the console.
+To use the autoload function, while on the `N64 ROM information` display, press the `R` button on your joypad and select the `Set ROM to autoload` option. When you restart the console, it will now only load the selected ROM rather than the menu.  
+**NOTE:** To return to the menu, hold the joypad `Start` button while powering on the console.
 
 ### GamePak sprites
 To use N64 GamePak sprites, place PNG files within the `sd:/menu/boxart/` folder.
@@ -65,15 +73,11 @@ These must be `PNG` files that use the following dimensions:
 * Japanese N64 GamePak boxart sprites: 112x158
 * 64DD boxart sprites: 129x112
 
-Supported PNG formats:
-* RGB/RGBA color formats
-* 8-bit color depth
+They will be loaded by directories using each character (case-sensitive) of the full 4 character Game Code (as identified in the menu ROM information).  
+i.e. for GoldenEye NTSC USA (NGEE), this would be `sd:/menu/boxart/N/G/E/E/boxart_front.png`.  
+i.e. for GoldenEye PAL (NGEP), this would be `sd:/menu/boxart/N/G/E/P/boxart_front.png`.  
 
-They will be loaded by directories using each character (case-sensitive) of the full 4 character Game Code (as identified in the menu ROM information).
-i.e. for GoldenEye NTSC USA (NGEE), this would be `sd:/menu/boxart/N/G/E/E/boxart_front.png`.
-i.e. for GoldenEye PAL (NGEP), this would be `sd:/menu/boxart/N/G/E/P/boxart_front.png`.
-
-To improve compatibility between regions (as a fallback), you may exclude the region ID (last matched directory) for GamePaks to match with 3 letter IDs instead:
+To improve compatibility between regions (as a fallback), you may exclude the region ID (last matched directory) for GamePaks to match with 3 letter IDs instead:  
 i.e. for GoldenEye, this would be `sd:/menu/boxart/N/G/E/boxart_front.png`.
 
 **Warning**: Excluding the region ID may show the wrong boxart.
@@ -85,7 +89,7 @@ i.e. for GoldenEye, this would be `sd:/menu/boxart/N/G/E/boxart_front.png`.
 * `boxart_right.png`
 
 As a starting point, here is a link to a boxart pack following the new structure, including `boxart_front.png` and fallback images:
-* [Link](https://drive.google.com/file/d/1IpCmFqmGgGwKKmlRBxYObfFR9XywaC6n/view?usp=drive_link)
+* [Recommended Boxart](https://drive.google.com/file/d/1IpCmFqmGgGwKKmlRBxYObfFR9XywaC6n/view?usp=drive_link)
 
 
 #### Compatibility mode
@@ -100,7 +104,7 @@ i.e.
 * for GoldenEye 2 letters, this would be `sd:/menu/boxart/GE.png`.
 
 
-As a starting point, here are some links to boxart packs:
+As a starting point, here are some links to boxart image packs:
 * [Japan Boxart](https://mega.nz/file/KyJR0B6B#ERabLautAVPaqJTIdBSv4ghbudNhK7hnEr2ZS1Q6ub0)
 * [American Boxart](https://mega.nz/file/rugAFYSQ#JHfgCU2amzNVpC4S6enP3vg--wtAAwsziKa7cej6QCc)
 * [European Boxart](https://mega.nz/file/OmIV3aAK#kOWdutK1_41ffN64R6thbU7HEPR_M9qO0YM2mNG6RbQ)
@@ -109,7 +113,7 @@ As a starting point, here are some links to boxart packs:
 
 ### Menu Settings
 The Menu creates a `config.ini` file in `sd:/menu/` which contains various settings that are used by the menu.
-If required, you can manually adjust the file on the SD card using your computer.
+These can be updated using the settings editor, but if required, you can also manually adjust the file on the SD card using your computer.
 
 
 ## Flashcart specific
@@ -118,6 +122,8 @@ If required, you can manually adjust the file on the SD card using your computer
 * Ensure the cart has the latest [firmware](https://github.com/Polprzewodnikowy/SummerCart64/releases/latest) installed.
 * Download the latest `sc64menu.n64` file from the [releases](https://github.com/Polprzewodnikowy/N64FlashcartMenu/releases/) page, then put it in the root directory of your SD card.
 
+![SC64 flashcart information](./docs/images/sc64-flashcart-information.png "example SC64 flashcart information")  
+
 
 ### 64drive
 * Ensure the cart has the latest [firmware](https://64drive.retroactive.be/support.php) installed.

docs/00_getting_started_sd.md

@@ -10,7 +10,8 @@ Connect the SD card to your PC and ensure it is properly formatted to be compati
 
 - Download the latest `sc64menu.n64` file from the [releases](https://github.com/Polprzewodnikowy/N64FlashcartMenu/releases/) page, then put it in the root directory of your SD card.
 - Create a folder in the root of your SD card called `menu`.
-- Place your ROM files on the SD card, **in any folder except `menu`**.
+- Place your ROM files on the SD card, **in any folder except `menu`**.  
+**NOTE:** byteswapped ROM's will increase load times.
 
 #### Preparations for other supported flashcarts
 - FAT32 recommended.

docs/01_menu_controls.md

@@ -6,9 +6,10 @@
 Press either the `C-Up` or `C-Down` buttons to scroll by pages, rather than by elements.
 
 #### N64FlashcartMenu settings
-Press the `START` button on the browser screen to open the Settings window. From here you can edit some of the N64FlashcartMenu settings, 
-see information about either the console, the flashcart you are using or N64FlashcartMenu itself, and if your cart has Real-Time Clock (RTC) support, 
-you can also change its date and time.
+Press the `START` button on the browser screen to open the Settings window.  
+![Main context menu](./images/main-context-menu.png "Main context menu")  
+From here you can edit some of the N64FlashcartMenu settings, 
+see information about either the console, the flashcart you are using or N64FlashcartMenu itself, and if your cart has Real-Time Clock (RTC) support, you can also change its date and time.
 
 #### Browser options
 Press the `R` button to open the Browser Options window. Here you can see a ROM's properties, delete it from your SD card or establish the default folder 

docs/07_menu_customization.md

@@ -2,3 +2,6 @@
 
 ### Customizing the font
 Add a `font64` file to the root directory called "custom.font64". You can build a font64 file with the `libdragon` tools.
+
+### Adding a background image
+Add an image to the SD card. When browsing the menu, select and load the image and then respond to the dialogue message.