The-Homebrew-Cloud/N64FlashcartMenu
2
0
Fork 0
mirror of https://github.com/Polprzewodnikowy/N64FlashcartMenu.git synced 2025-01-22 23:01:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

[main] Improve documentation (#179)

Browse Source 
## Description
Documentaion has been rewritten/improved/expanded in certain areas
including typo and formatting fixes.

## Motivation and Context
Tidier documentation, to make things a bit more dumb-proof for end
users.

## How Has This Been Tested?
Not applicable.

## Types of changes
- [ ] Improvement (non-breaking change that adds a new feature)
- [ ] Bug fix (fixes an issue)
- [ ] Breaking change (breaking change)
- [x] Documentation Improvement
- [ ] Config and build (change in the configuration and build system,
has no impact on code or features)

## Checklist:
- [ ] My code follows the code style of this project.
- [ ] My change requires a change to the documentation.
- [x] I have updated the documentation accordingly.
- [ ] I have added tests to cover my changes.
- [ ] All new and existing tests passed.

Signed-off-by: IlDucci

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Summary by CodeRabbit

- **Documentation**
- Updated documentation for initial SD card setup, menu controls, and
menu customization.
	- Improved clarity and readability of instructions.
- Refined section headings and formatting across multiple documentation
files.
- Added new sections explaining menu settings, ROM information, and
control details.
- Emphasized warnings regarding filename compatibility and save file
issues.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
Víctor "IlDucci 2024-12-31 21:33:30 +00:00 committed by GitHub
parent 9113d1c949
commit 75b14b6c20
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 70 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
docs/00_getting_started_sd.md
View File

@ -1,40 +1,41 @@
## First time setup of SD card
## Initial Setup of SD Card
### Flashcarts
Using your PC, insert the SD card and ensure it is formatted for compatibility with your flashcart.
**warning** Filenames are expected to be part of the ASCII character set. Unicode characters are not fully supported and may cause a crash screen.
### First Steps
Connect the SD card to your PC and ensure it is properly formatted to be compatible with your flashcart.
**WARNING:** Filenames are expected to be written in ASCII, with Western Europe characters fully compatible. Other Unicode characters, such as those from Eastern Europe, Russia, Asia or Middle East regions (to name just a few examples) are not fully supported and may not be displayed.
#### SC64
#### Preparations for SC64
- FAT32 and EXFAT are fully supported.
- An SD formatted with 128 kiB cluster size is recommended.
- 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.
- 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 ROMs on the SD Card, in any folder (**except for `menu`**).
- Place your ROM files on the SD card, **in any folder except `menu`**.
#### Other supported flashcarts
#### Preparations for other supported flashcarts
- FAT32 recommended.
- An SD formatted with default cluster size is recommended.
- An SD formatted with the default cluster size is recommended.
(TBW)
### Emulator support
### 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:
N64FlashcartMenu 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)
- **SMS** / **GG**: [smsPlus64](https://github.com/fhoedemakers/smsplus64/releases) by *fhoedmakers* - `smsPlus64.z64`
- **Game Boy**/**GB Color**: [gb64](https://lambertjamesd.github.io/gb64/romwrapper/romwrapper.html) by *lambertjamesd* - `gb.v64`/`gbc.v64` ("Download Emulator" button)
- **SMS**/**GG**: [smsPlus64](https://github.com/fhoedemakers/smsplus64/releases) by *fhoedmakers* - `smsPlus64.z64`
- **Fairchild Channel F**: [Press-F-Ultra](https://github.com/celerizer/Press-F-Ultra/releases) by *celerizer* - `Press-F.z64`
### 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.
### 64DD Disk Support
To load and run 64DD disk images, 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?
#### So what would the layout of the SD card look like?
```plaintext
SD:\
│
@ -61,37 +62,36 @@ SD:\
├── (a rom).n64
├── (some folder with roms)\
│ └── (some folder with roms)\
| └── (Some supported ROM files)
| └── (some supported ROM files)
│
├── (Some supported ROM files)
├── (some supported ROM files)
|
└── (Some folder with 64DD disk images)\
└── (Some 64DD disk images)
└── (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.
All save files (whether `FlashRam`, `SRAM` or `EEPROM`) will be read from a `/saves` folder located **in the same directory as the ROM**
and they must share the same file name, but use the `.sav` extension. `.sav` files will be created and modified whenever a ROM file saves to
the "cartridge save memory".
```plaintext
├── (some folder with roms)\
├── a_rom.z64
├── b_rom.n64
├── b_rom_whatever.n64
└── saves\
├── a_rom.sav
└── b_rom.sav
└── b_rom_whatever.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`
### Transfering Saves From An ED64
If you are transferring a file from a different flashcart, such as the ED64, you must change the file extension to `sav`.
For example, a save file called `Glover (USA).eep` should have its extension changed to `Glover (USA).sav` to work with N64FlashcartMenu.
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.
- For others, use a tool such as [Ninjiteu's N64SaveConverter](https://github.com/Ninjiteu/N64SaveConverter).
**NOTE:** certain emulator saves or saves created for a different ROM version or region may be incompatible.
**WARNING:** Saves created with certain emulators, or created for a different ROM version (as in revisions of the same game)
or region (as in between NTSC and PAL versions of a same game) may be incompatible.

27
docs/01_menu_controls.md
View File

@ -1,14 +1,27 @@
## Menu Controls
### Fast scroll
Use the C-Up and C-Down buttons
### Additional Control Information
#### Fast scroll
Press either the `C-Up` or `C-Down` buttons to scroll by pages, rather than by elements.
### DD ROMs
#### 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.
#### 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.
#### 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
where N64FlashcartMenu's browser will start in future boots.
#### Additional ROM information
Press either the `L` or `Z` button on the ROM information screen to open an additional window that will show additional information about the currently
selected ROM file, such as its endianess, regional variant, set clock rate, and much more.
### 64DD ROM
#### Expansion disks
To load an expansion disk (such as F-Zero X), first browse to the N64 ROM and load it (**but not start it!**), then browse to the 64DD expansion file and press either the `L` or `Z` button.
#### Disk swapping
This feature is not currently available in the menu.
This feature is not currently available in N64FlashcartMenu.

7
docs/07_menu_customization.md
View File

@ -1,5 +1,4 @@
# Menu customization
## Menu Customization
## Using a custom font
Add a `font64` file to the root directory called "custom.font64"
This can be build using `libdragon` tools.
### Customizing the font
Add a `font64` file to the root directory called "custom.font64". You can build a font64 file with the `libdragon` tools.

30
docs/99_developer_guide.md
View File

@ -2,35 +2,34 @@
You can use a dev container in VSCode to ease development.
### A quickstart video tutorial on how to set up your environment
### 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:
### How to deploy
#### SC64
* Download the deployer [here](https://github.com/Polprzewodnikowy/SummerCart64/releases/download/v2.20.0/sc64-deployer-windows-v2.20.0.zip)
* Download the deployer [here](https://github.com/Polprzewodnikowy/SummerCart64/releases/download/v2.20.0/sc64-deployer-windows-v2.20.0.zip).
* Extract and place `sc64deployer.exe` in the `tools/sc64` directory.
Make sure that your firmware is compatible (currently v2.20.0+)
Make sure that your firmware is compatible (currently v2.20.0+).
See: [here](https://github.com/Polprzewodnikowy/SummerCart64/blob/v2.20.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`
It is not currently possible to directly communicate with USB devices. BUT, you can use a proxy TCP/IP connection as a workaround.
To 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`
Then, in the dev container, use `make run` or `make run-debug`.
##### From your host (Windows) OS
* Run `./localdeploy.bat` from the terminal
* Run `./localdeploy.bat` from the terminal.
Toggle the N64 power switch to load the ROM.
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`
`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`.
@ -53,11 +52,10 @@ This repo currently uses the `preview` branch as a submodule at a specific commi
* To ensure your local instance is building against it, use `cd ./libdragon && make clobber -j && make libdragon tools -j && make install tools-install -j && cd ..`
## Generate documentation
Run `doxygen` from the dev container terminal.
Make sure you fix the warnings before creating a PR!
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/)
Once merged, they can be viewed [here](https://polprzewodnikowy.github.io/N64FlashcartMenu/).
### Test generated docs in the dev-container
Testing the documentation locally allows you to preview changes and ensure everything renders correctly before submitting your changes.