The-Homebrew-Cloud/N64FlashcartMenu
2
0
Fork 0
mirror of https://github.com/Polprzewodnikowy/N64FlashcartMenu.git synced 2024-11-28 13:34:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'develop' into ed64-basic

Browse Source
This commit is contained in:
Robin Jones 2024-08-04 23:34:15 +01:00 committed by GitHub
commit fd5bea76df
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 198 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@ -21,6 +21,7 @@
- [ ] Improvement (non-breaking change that adds a new feature) - [ ] Improvement (non-breaking change that adds a new feature)
- [ ] Bug fix (fixes an issue) - [ ] Bug fix (fixes an issue)
- [ ] Breaking change (breaking change) - [ ] Breaking change (breaking change)
- [ ] Documentation Improvement
- [ ] Config and build (change in the configuration and build system, has no impact on code or features) - [ ] Config and build (change in the configuration and build system, has no impact on code or features)
## Checklist: ## Checklist:

4
.github/workflows/build.yml vendored
View File

@ -81,8 +81,8 @@ jobs:
files: | files: |
./output/N64FlashcartMenu.n64 ./output/N64FlashcartMenu.n64
./output/menu.bin ./output/menu.bin
./output/OS64.v64 # ./output/OS64.v64
./output/OS64P.v64 # ./output/OS64P.v64
./output/sc64menu.n64 ./output/sc64menu.n64
continue-on-error: true continue-on-error: true

2
.gitignore vendored
View File

@ -15,4 +15,4 @@
# Ignore any N64 ROM # Ignore any N64 ROM
**/*.n64 **/*.n64
**/*.v64 **/*.v64
**/*.z64 **/*.z64

2
Doxyfile
View File

@ -905,7 +905,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched. # Note: If this tag is empty the current directory is searched.
INPUT = README.md ./src INPUT = README.md ./src ./docs
# This tag can be used to specify the character encoding of the source files # This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

141
README.md
View File

@ -28,7 +28,12 @@ An open source menu for N64 flashcarts.
* Menu sound effects. * Menu sound effects.
### Video showcase (as of Oct 12 2023) ## Documentation
* [Getting started guide](./docs/00_getting_started_sd.md)
* [Menu controls](./docs/01_menu_controls.md)
* [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)") [![N64FlashcartMenu Showcase](http://img.youtube.com/vi/6CKImHTifDA/0.jpg)](http://www.youtube.com/watch?v=6CKImHTifDA "N64FlashcartMenu Showcase (Oct 12 2023)")
@ -41,20 +46,8 @@ An open source menu for N64 flashcarts.
* Support as many common mods and features as possible. * Support as many common mods and features as possible.
## Getting started ## Experimental features
Using your PC, insert the SD card and ensure it is formatted for compatibility (We recommend FAT32 in most instances, though EXFAT is fully supported on the SummerCart64). These features are subject to change:
### Save files
By default, all save files (whether `FlashRam`, `SRAM` or `EEPROM`) use the `.sav` extension and match the filename of the ROM.
Each save file can be found in the `/saves` folder located in the same directory as the ROM and shares the same file name, apart from the extension.
If transfering a file from a different flashcart such as the ED64, it will be necessary to change the extension of the file to `sav`.
i.e. for `Glover (USA).eep` you would need to change the extension to `Glover (USA).sav`
**NOTE:** certain emulator saves or saves created for a different ROM version or region may be incompatible.
### ROM Boxart ### ROM Boxart
To use boxart, you need to place png files of size 158x112 in the folder `/menu/boxart` on the SD card. To use boxart, you need to place png files of size 158x112 in the folder `/menu/boxart` on the SD card.
@ -64,119 +57,41 @@ i.e. for GoldenEye 3 letters, this would be `NGE.png`.
A known set of PNG files using 2 letter ID's can be downloaded [here](https://mega.nz/file/6cNGwSqI#8X5ukb65n3YMlGaUtSOGXkKo9HxVnnMOgqn94Epcr7w). A known set of PNG files using 2 letter ID's can be downloaded [here](https://mega.nz/file/6cNGwSqI#8X5ukb65n3YMlGaUtSOGXkKo9HxVnnMOgqn94Epcr7w).
### Emulator support
Emulators should be added to the `/menu/emulators` directory on the SD card.
Menu currently supports the following emulators and associated ROM file names:
- **NES**: [neon64v2](https://github.com/hcs64/neon64v2/releases) by *hcs64* - `neon64bu.rom`
- **SNES**: [sodium64](https://github.com/Hydr8gon/sodium64/releases) by *Hydr8gon* - `sodium64.z64`
- **Game Boy** / **GB Color**: [gb64](https://lambertjamesd.github.io/gb64/romwrapper/romwrapper.html) by *lambertjamesd* - `gb.v64` / `gbc.v64` ("Download Emulator" button)
### Menu Settings ### Menu Settings
The Menu creates a `config.ini` file in `sd:/menu/` which contains various settings that are used by the menu. The Menu creates a `config.ini` file in `sd:/menu/` which contains various settings that are used by the menu.
Currently these are read-only (can be viewed in the menu by pressing `L` on the Joypad).
If required, you can manually adjust the file on the SD card using your computer. If required, you can manually adjust the file on the SD card using your computer.
### SC64 Specific
- Ensure the cart has the latest [firmware](https://github.com/Polprzewodnikowy/SummerCart64/releases/latest) installed.
- Download the latest `sc64menu.n64` file from the releases page, then put it in the root directory of your SD card.
##### 64DD disk support ## Flashcart specific
For the ability to load and run 64DD disk images, you need to place required 64DD IPL dumps in the `/menu/64ddipl` folder on the SD card.
For more details follow [this guide on the 64dd.org website](https://64dd.org/tutorial_sc64.html).
Note: to load an expansion disk (e.g. F-Zero X) browse to the N64 ROM and load it (but not start it) and then browse to the DD expansion file and press the `R` button.
### 64drive Specific
- Ensure the cart has the latest [firmware](https://64drive.retroactive.be/support.php) installed.
- Download the latest `menu.bin` file from the releases page, then put it in the root directory of your SD card.
### ED64 & ED64P Specific
#### ED64
Download the `ED64.v64` ROM from the latest action run assets and place it in the `/ED64` folder.
**Untested** The aim is to replace [ED64-UnofficialOS](https://github.com/n64-tools/ED64-UnofficialOS-binaries).
#### ED64P
Download the `ED64P.v64` ROM from the latest action run assets and place it in the `/ED64P` folder.
# Developer documentation
You can use a dev container in VSCode to ease development.
## To Build:
`ms-vscode.makefile-tools` will help (installed automatically in dev container).
TODO: it does not yet work with `F5`: see https://devblogs.microsoft.com/cppblog/now-announcing-makefile-support-in-visual-studio-code/
WORKAROUND: in the dev container terminal, use make directly, i.e.: `make all`
The ROMs can be found in the `output` directory.
## To deploy:
### SC64 ### SC64
* Download the deployer [here](https://github.com/Polprzewodnikowy/SummerCart64/releases/download/v2.18.0/sc64-deployer-windows-v2.18.0.zip) * Ensure the cart has the latest [firmware](https://github.com/Polprzewodnikowy/SummerCart64/releases/latest) installed.
* Extract and place `sc64deployer.exe` in the `tools/sc64` directory. * 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.
Make sure that your firmware is compatible (currently v2.18.0+)
See: [here](https://github.com/Polprzewodnikowy/SummerCart64/blob/v2.18.0/docs/00_quick_startup_guide.md#firmware-backupupdate)
#### From the devcontainer
It is not currently possible to directly communicate with USB devices.
BUT, as a work around you can use a proxy TCP/IP connection
Set up a proxy: open a terminal window, `cd ./tools/sc64` and then `./sc64deployer.exe server`
Then in the dev container, use `make run` or `make run-debug`
#### From your host (Windows) OS ### 64drive
* Ensure the cart has the latest [firmware](https://64drive.retroactive.be/support.php) installed.
* Run `./localdeploy.bat` from the terminal * Download the latest `menu.bin` file from the [releases](https://github.com/Polprzewodnikowy/N64FlashcartMenu/releases/) page, then put it in the root directory of your SD card.
Toggle the N64 power switch to load the ROM.
#### From the SD Card
A "release" version of the SC64 menu is called `sc64menu.n64` and can be created for when you want to add it directly to the root folder on the SDCard. This is generated by running `make all` or running `make sc64`.
### Ares Emulator
For ease of development and debugging, the menu ROM is able to run in the Ares emulator (without most flashcart features).
* Ensure you have the Ares emulator on you computer.
* Load the `N64FlashcartMenu.n64` ROM.
### ED64 V3 over USB from your host (Windows) OS
* Download the UNFLoader [here](https://github.com/buu342/N64-UNFLoader/releases/download/v2.11/UNFLoader-Windows-x86.zip)
* Extract and place `UNFLoader.exe` in the `tools` directory.
* Ensure the current "official menu" is `V3.06`.
* Run the appropriate command from windows cmd prompt to ensure your current directory is the root project directory.
* Upload the ROM (e.g. `./tools/UNFLoader.exe -r ./output/OS64.v64`)
### Others (non USB) ### ED64
* Add the required file to the correct folder on your SD card. #### ED64 (V or X series)
Download the `OS64.v64` ROM from the latest action run assets and place it in the `/ED64` folder.
#### ED64 (P clone)
Download the `OS64P.v64` ROM from the latest action run assets and place it in the `/ED64P` folder.
# Update Libdragon submodule
This repo currently uses the `preview` branch as a submodule at a specific commit.
To update to the latest version, use `git submodule update --remote ` from the terminal.
# Generate documentation
Run `doxygen` from the dev container terminal.
Make sure you fix the warnings before creating a PR!
Generated documentation is located in `output/docs` folder and auto published to the `gh-pages` branch when merged with `main`.
Once merged, they can be viewed [here](https://polprzewodnikowy.github.io/N64FlashcartMenu/)
# Open source software and licenses used # Open source software and licenses used
- [libdragon](https://github.com/DragonMinded/libdragon) (UNLICENSE License)
- [libspng](https://github.com/randy408/libspng) (BSD 2-Clause License) * [libdragon](https://github.com/DragonMinded/libdragon) (UNLICENSE License)
- [mini.c](https://github.com/univrsal/mini.c) (BSD 2-Clause License) * [libspng](https://github.com/randy408/libspng) (BSD 2-Clause License)
- [minimp3](https://github.com/lieff/minimp3) (CC0 1.0 Universal) * [mini.c](https://github.com/univrsal/mini.c) (BSD 2-Clause License)
- [miniz](https://github.com/richgel999/miniz) (MIT License) * [minimp3](https://github.com/lieff/minimp3) (CC0 1.0 Universal)
* [miniz](https://github.com/richgel999/miniz) (MIT License)
## Sounds ## Sounds
See [License](https://pixabay.com/en/service/license-summary/) for the following sounds: See [License](https://pixabay.com/en/service/license-summary/) for the following sounds:
- [Cursor sound](https://pixabay.com/en/sound-effects/click-buttons-ui-menu-sounds-effects-button-7-203601/) by Skyscraper_seven (Free to use) * [Cursor sound](https://pixabay.com/en/sound-effects/click-buttons-ui-menu-sounds-effects-button-7-203601/) by Skyscraper_seven (Free to use)
- [Actions (Enter, back) sound](https://pixabay.com/en/sound-effects/menu-button-user-interface-pack-190041/) by Liecio (Free to use) * [Actions (Enter, back) sound](https://pixabay.com/en/sound-effects/menu-button-user-interface-pack-190041/) by Liecio (Free to use)
- [Error sound](https://pixabay.com/en/sound-effects/error-call-to-attention-129258/) by Universfield (Free to use) * [Error sound](https://pixabay.com/en/sound-effects/error-call-to-attention-129258/) by Universfield (Free to use)

82
docs/00_getting_started_sd.md Normal file
View File

@ -0,0 +1,82 @@
## First time setup of SD card
Using your PC, insert the SD card and ensure it is formatted for compatibility with your flashcart (*FAT32 and EXFAT are fully supported on the SC64*).
- Download the latest `sc64menu.n64` (assuming you are using an *sc64*) 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 ROMs on the SD Card, in any folder (**except for `menu`**).
### Emulator support
Emulators should be added to the `/menu/emulators` directory on the SD card.
Menu currently supports the following emulators and associated ROM file names:
- **NES**: [neon64v2](https://github.com/hcs64/neon64v2/releases) by *hcs64* - `neon64bu.rom`
- **SNES**: [sodium64](https://github.com/Hydr8gon/sodium64/releases) by *Hydr8gon* - `sodium64.z64`
- **Game Boy** / **GB Color**: [gb64](https://lambertjamesd.github.io/gb64/romwrapper/romwrapper.html) by *lambertjamesd* - `gb.v64` / `gbc.v64` ("Download Emulator" button)
### 64DD disk support
For the ability to load and run 64DD disk images, you need to place the required 64DD IPL dumps in the `/menu/64ddipl` folder on the SD card.
For more details, follow [this guide on the 64dd.org website](https://64dd.org/tutorial_sc64.html).
#### So what would the layout of the SD Card look like?
```plaintext
SD:\
│
├── sc64menu.n64
│
│
├── menu\
│ │
│ │
│ ├── 64ddipl\
│ │ ├── NDDE0.n64
│ │ ├── NDDJ2.n64
│ │ └── NDXJ0.n64
│ │
│ └── emulators
│ ├── neon64bu.rom
│ ├── sodium64.z64
│ ├── gb.v64
│ └── gbc.v64
│
├── (a rom).z64
├── (a rom).n64
├── (some folder with roms)\
│ └── (some folder with roms)\
| └── (Some supported ROM files)
│
├── (Some supported ROM files)
|
└── (Some folder with 64DD disk images)\
└── (Some 64DD disk images)
```
## Save Files
All save files (whether `FlashRam`, `SRAM` or `EEPROM`) use the `.sav` extension and match the filename of a ROM.
Each save file can be found in the `/saves` folder located in the **same directory** as the ROM and shares the same file name, apart from the extension.
These files are created and modified when a "game" saves.
```plaintext
├── (some folder with roms)\
├── a_rom.z64
├── b_rom.n64
└── saves\
├── a_rom.sav
└── b_rom.sav
```
### Transfering saves from an ED64
If transferring a file from a different flashcart, such as the ED64, it will be necessary to change the extension of the file to `sav`.
i.e. for `Glover (USA).eep` you would need to change the extension to `Glover (USA).sav`
You may also need to pad/trim the files to their original size:
- For EEPROM 4Kbit games, remove the padding.
- For others, use a tool such as Ninjiteu's N64 Save converter.
**NOTE:** certain emulator saves or saves created for a different ROM version or region may be incompatible.

14
docs/01_menu_controls.md Normal file
View File

@ -0,0 +1,14 @@
## Menu Controls
### Fast scroll
Use the C-Up and C-Down buttons
### DD ROMs
#### Expansion Disks
To load an expansion disk (e.g. F-Zero X) browse to the N64 ROM and load it (but not start it) and then browse to the DD expansion file and press the `R` button.
#### Disk swapping
This feature is not currently available in the menu.

69
docs/99_developer_guide.md Normal file
View File

@ -0,0 +1,69 @@
## Developer documentation
You can use a dev container in VSCode to ease development.
### A quickstart video tutorial on how to set up your environment
[![Devcontainer quickstart guide](http://img.youtube.com/vi/h05ufOsRgZU/0.jpg)](http://www.youtube.com/watch?v=h05ufOsRgZU "Devcontainer quickstart guide").
### To deploy:
#### SC64
* Download the deployer [here](https://github.com/Polprzewodnikowy/SummerCart64/releases/download/v2.18.0/sc64-deployer-windows-v2.18.0.zip)
* Extract and place `sc64deployer.exe` in the `tools/sc64` directory.
Make sure that your firmware is compatible (currently v2.18.0+)
See: [here](https://github.com/Polprzewodnikowy/SummerCart64/blob/v2.18.0/docs/00_quick_startup_guide.md#firmware-backupupdate)
##### From the devcontainer
It is not currently possible to directly communicate with USB devices.
BUT, as a workaround you can use a proxy TCP/IP connection
Set up a proxy: open a terminal window, `cd ./tools/sc64` and then `./sc64deployer.exe server`
Then in the dev container, use `make run` or `make run-debug`
##### From your host (Windows) OS
* Run `./localdeploy.bat` from the terminal
Toggle the N64 power switch to load the ROM.
`ms-vscode.makefile-tools` will help (installed automatically in dev container).
NOTE: it does not yet work with `F5`: see [this blog post](https://devblogs.microsoft.com/cppblog/now-announcing-makefile-support-in-visual-studio-code/)
WORKAROUND: in the dev container terminal, use make directly, i.e.: `make`
The ROM can be found in the `output` directory.
NOTE: a "release" version of the SC64 menu is called `sc64menu.n64` and can be created for when you want to add it directly to the SDCard. This is generated by running `make all` or running `make sc64`.
#### Ares Emulator
For ease of development and debugging, the menu ROM can run in the [Ares emulator](https://ares-emu.net/) (without most flashcart features).
* Ensure you have the Ares emulator on your computer.
* Load the `N64FlashcartMenu.n64` ROM.
#### Others
* Add the required file to the correct folder on your SD card.
## Update Libdragon submodule
This repo currently uses the `preview` branch as a submodule at a specific commit.
To update to the latest version, use `git submodule update --remote` from the terminal.
## Generate documentation
Run `doxygen` from the dev container terminal.
Make sure you fix the warnings before creating a PR!
Generated documentation is located in the `output/docs` folder and auto-published to the `gh-pages` branch when merged with `main`.
Once merged, they can be viewed [here](https://polprzewodnikowy.github.io/N64FlashcartMenu/)
### Test generated docs in the dev-container
Install Prerequisites:
```bash
apt-get install ruby-full build-essential zlib1g-dev
gem install jekyll bundler
```
You can then serve the webpage:
```bash
cd output/docs && jekyll serve
```