Update README.md

1 files changed, 95 insertions, 73 deletions

diff --git a/README.md b/README.md
index bcaf7f4..d011744 100644
--- a/README.md
+++ b/README.md
@@ -1,82 +1,23 @@
 # COOLBOY Multirom Builder
-
-This is a toolset that allows you to create multirom images for cheap COOLBOY/MINDKIDS (and clones) Famicom cartridges (mappers 268.0 and 268.1). This ROM can be run on emulator or written to a real hardware.
+This is a toolset that allows you to create multirom images for the AA6023 ASICs mapper which used into cheap COOLBOY/MINDKIDS (and clones) Famicom cartridges (mappers 268.0 and 268.1). This ROM can be run on a emulator or written to a real hardware.
 
 It can:
-* Automatically combine up to 1536 games into single binary which can be written to cheap COOLBOY cartridge
+* Automatically combine up to 1536 games into single binary which can be written to a cheap COOLBOY cartridge
 * Create nice menu where you can easily select a game
 * Alphabetically sort games if you need it
 * Use your own image for the menu header and other customizations
-* Remember last played game and keep up to 15 game saves into flash memory on a self-writable cartridges with PRG-RAM
-* Run built-in hardware tests
+* Remember last played game and keep up to 15 saves for "battery-backed" games into flash memory on a self-writable cartridges with PRG-RAM
+* Run a built-in hardware tests
 * Show build and hardware info
 * Add up to three hidden ROMs
+* Run on Windows (x64), Linux (x64, ARM, ARM64) and macOS (x64)
 
-How it works (first method):
-1. Convert images to a NES assets using the [NesTiler](https://github.com/ClusterM/NesTiler) tool.
-2. Create a text file with a list of files and/or directories with the ROMs, optionally you can specify game names for corresponding menu entries. 
-3. Run **coolboy-combiner** with "**prepare**" option, it will automatically use the best way to fit games data in the target ROM and create "**games.asm**" file and offsets file. First one contains game names and register values for game loader menu. Second file contains info with addresses of data for every game in the final ROM.
-4. Compile assembly files using [nesasm CE](https://github.com/ClusterM/nesasm). It will create .nes file with the loader menu. But it will not contain games data. You can tune loader menu using command line options and defines: header image, background stars behavior, sounds, etc.
-5. Combine loader menu and games into one file (.nes, .unf or .bin) using **coolboy-combiner** with "**combine**" option and offsets file generated by step 2. Done.
-
-Alternative method (easier and faster):
-1. Convert images to a NES assets using the [NesTiler](https://github.com/ClusterM/NesTiler) tool.
-2. Create a text file with a list of files and/or directories with the ROMs, optionally you can specify game names for corresponding menu entries.
-3. Run **coolboy-combiner** with "**build**" option, it will automaticaly fit games, compile assembly files using [nesasm CE](https://github.com/ClusterM/nesasm) and combine everything into one file (.nes, .unf or .bin).
-
-It sounds a bit complicated but this toolset contains all tools and bundled with scripts for automatic execution: Makefile and .bat file (for Windows users). Makefile can be used with [Make](https://www.gnu.org/software/make/) tool to automatize the whole process. Just run:
-
-`make nes GAMES=games.list`
-
-Where "games.list" is your config file with a game list. Also, you can tune some options. Enable saves using self-writable flash memory:
-
-`make nes GAMES=games.list SAVES=1`
-
-Or change header image:
-
-`make nes GAMES=games.list SAVES=1 MENU_HEADER=menu_example.png`
-
-Use $5xxx registers instead of $6xxx and write to output.nes:
-
-`make nes GAMES=games.list MINDKIDS=1 OUTPUT_NES20=output.nes`
-
-Save output ROM as UNIF file:
-
-`make unif GAMES=games.list OUTPUT_UNIF=output.unf`
-
-Check **Makefile** for all options. Windows users can install Make using [msys2](https://www.msys2.org/) or just use **build.bat** file but it's not very custimizable.
-
-Windows users can use "**build.bat**" batch file. Default game list file is "**configs/games.list**".
-
-Now let me talk you much more info.
-
-
-## Which cartridges are supported, how to select which cartridge to buy
-
-There are many versions of COOLBOY cartridges and clones. Actually most of them are not "COOLBOY", it's just a name of the first cartridges with this chip.
-
-You can find modifications:
-* **With a different CHR size**. Some cartridges has only 128KB of RAM for CHR data and some 256KB. So 128KB version can't run many cool games with CHR size >128KB. You can easily detect amount of CHR RAM after looking at games list. If it has at least one game with large CHR, cartridge has 256KB. Example games: Megaman/Rockman 5, Earthbound Zero, Kirby's Adventure
-* **With a different flash size**. Most cartridges has 32MBytes of flash memory but it's possible to find much more rare cartridges with less memory size. 32MBytes is maximum available size.
-* **With and without additional PRG RAM chip**. It's required by some games like The Legend of Zelda, Jurassic Park, etc. So if cartridge contains those games, it has PRG RAM chip. Also, it's possible to solder this chip manually usually.
-* **With and without battery**. Battery is used to keep data in PRG RAM chip even after console is turned off. It's used to save games progress. So if cartridge has battery, it also has PRG-RAM chip. There is no way to detect present of battery but usually seller can say it, also check product description in shop.
-* **With a directly writable and non-writable flash memory**. Some new cartridges can be rewrited directly without additional soldering and some not. Direct rewrite will allow you not only rewrite cartridge's flash memory using very simple way but it will also allow to keep many game saves in cartridge's memory (if PRG RAM chip exists). Originally game's progress will be erased if any other game started that uses PRG RAM even if battery present. There is no way to know which cartridge has this feature but seems like it's all cartridges produced by "MINDKIDS". So if you can look at cartridge's board, check it for "MINDKIDS" label.
-* **With a different register addresses**. Most cartridges has registers at $600x addresses but some cartridges has them at $500x. This toolset supports both versions, so you don't need to care about it.
-
-So it's recommended to search for MINDKIDS cartridges with battery.
-
+## How to build a ROM
+This package contains multiple tools which need to run sequentially. There is Makefile, so you can use [Make](https://www.gnu.org/software/make/) tool to automatize the whole process. This is the most simple way. Windows users can use [msys2](https://www.msys2.org/) to install and run Make or just run build.bat (not customizable, not recommended).
 
-## Which games are supported
-
-COOLBOY supports games with **NROM** (mapper #0) and **MMC3** (mapper #4) mappers only. NROM is used by games without any mapper and MMC3 is most popular mapper, so games support is good but not perfect. Also most non-MMC3 games can be patched to run on MMC3 without any problem. Also make sure that PRG RAM and CHR size requirements are met.
-
-And one more thing with some weird buggy games. COOLBOY always uses writable CHR RAM even original game uses CHR ROM and it has not 'read-only' mode. So if game with CHR ROM writes to ROM for some weird reason, CHR data will be corrupted. It can be fixed using patches for ROMs. Example game: Cowboy Kid.
-
-Also please note that PRG RAM is not working correctly on *original* Famicoms and AV Famicoms without additional hardware modification of cartridge.
-
-
-## Game list format
+But you need to create game list first.
 
+### Game list format
 It's just a text file. Lines started with semicolon are comments. Other lines has format:
 
     <path_to_filename> [| <menu name>]
@@ -104,7 +45,7 @@ All games are alphabetically sorted by default so you don't need to care about g
 
     roms/filename1.nes
     roms/filename2.nes
-    -
+    - | SOME TITLE
     roms/filename3.nes
     roms/filename4.nes
     
@@ -112,9 +53,68 @@ You can disable sorting and enable custom order using NOSORT=1 option when runni
 
 Check [configs/games.list](configs/games.list) for example.
 
+### How to use Make
+Just run:
+
+`make <targets> [options]`
+
+Possible targets:
+* **nes20** - build .nes file (NES 2.)
+* **unif** - build .unf file (UNIF)
+* **bin** - build raw binary file, can be used with flash memory programmer
+* **all** - build .nes, .unf and .bin files at once
+
+Possible options:
+* **GAMES** - use as `GAMES=games.list` to specify the file with game list, default is "games.list"
+* **MENU_IMAGE** - use as `MENU_IMAGE=menu_header.png` to specify image for menu header, default is "menu_header.png"
+* **LANGUAGE** - use as `LANGUAGE=eng` to specify loader messages (like some warnings) language - "eng" or "rus", default is "eng"
+* **SIZE** - use as `SIZE=32` - maximum ROM size in megabytes (flash chip size), builder will throw error in case of ROM overflow, default is 32
+* **MAXCHRSIZE** - use as `MAXCHRSIZE=256` - maximum CHR size in kilobytes (CHR RAM chip size), builder will throw error in case if there is game with more CHR size, default is 256
+* **OUTPUT_NES20** - use as `OUTPUT_NES20=output.nes` - output .nes file for **nes20** target
+* **OUTPUT_UNIF** - use as `OUTPUT_UNIF=output.unf` - output .unf file for **unif** target
+* **OUTPUT_BIN** - use as `OUTPUT_BIN=output.bin` - output .bin file for **bin** target
+* **CONFIGS_DIR** - use as `CONFIGS_DIR=configs` - directory with game list files, default is "configs"
+* **MINDKIDS** - use as `MINDKIDS=1` - use MINDKIDS mapper (mapper 268, submapper 1) instead of COOLBOY (mapper 268, submapper 0), e.g. use registers as $5xxx instead of $6xxx, default is `MINDKIDS=0`
+* **SAVES** - use as `SAVES=1` - use self-writable flash memory to store game saves and remember last selected game if supported, default is `SAVES=0`
+* **ENABLE_LAST_GAME_SAVING**  - use as `ENABLE_LAST_GAME_SAVING=1` - remember last played game, works only with `SAVES=1` and self-writable flash memory, default is `ENABLE_LAST_GAME_SAVING=1`
+* **NOSORT** - use as `NOSORT=1` - disable automatic alphabetically game sorting, default is `NOSORT=0`
+* **BADSECTORS** - use as `BADSECTORS=0,5,10` - specify list of bad sectors if you need to write cartridge with bad flash memory, default is none
+* **REPORT** - use as `REPORT=report.txt` - specify file for human-readable build report, default is none
+* **ENABLE_SOUND** - use as `ENABLE_SOUND=1` - enable or disable sound in the loader menu, default is `ENABLE_SOUND=1`
+* **STARS** - use as `STARS=30` - amount of background stars in the loader menu, default is `STARS=30`, maximum is `STARS=62`
+* **STARS_DIRECTION** - use as `STARS_DIRECTION=1` - direction of background stars in the loader menu, `STARS_DIRECTION=0` - down to up, `STARS_DIRECTION=1` - up to down, default is up to down
+* **STAR_SPAWN_INTERVAL** - use as `STAR_SPAWN_INTERVAL=90` - spawn interval of background stars in the loader menu, default is `STAR_SPAWN_INTERVAL=90`
+* **ENABLE_RIGHT_CURSOR** - use as `ENABLE_RIGHT_CURSOR=1` - show or hide right cursor in the loader menu, default is `ENABLE_RIGHT_CURSOR=1`
+* **ENABLE_DIM_IN** - use as `ENABLE_DIM_IN=1` - enable dim-in (on startup, etc), default is `ENABLE_DIM_IN=1`
+* **DIM_IN_DELAY** - use as `DIM_IN_DELAY=5` - dim-in speed (more - slower), default is `DIM_IN_DELAY=5`
+* **ENABLE_DIM_OUT** - use as `ENABLE_DIM_OUT=1` - enable dim-out (before game launch, etc), default is `ENABLE_DIM_OUT=1`
+* **DIM_OUT_DELAY** - use as `DIM_OUT_DELAY=1` - dim-out speed (more - slower), default is `DIM_OUT_DELAY=1`
+
+#### Examples
+Enable saves using self-writable flash memory:
+
+`make nes GAMES=games.list SAVES=1`
+
+Or change header image:
+
+`make nes GAMES=games.list SAVES=1 MENU_HEADER=menu_example.png`
+
+Use $5xxx registers instead of $6xxx and write to output.nes:
+
+`make nes GAMES=games.list MINDKIDS=1 OUTPUT_NES20=output.nes`
+
+Save output ROM as UNIF file:
+
+`make unif GAMES=games.list OUTPUT_UNIF=output.unf`
+
+## Which games are supported
+COOLBOY supports games with **NROM** (mapper #0) and **MMC3** (mapper #4) mappers only. NROM is used by simple games without any mapper and MMC3 is the most popular mapper, so games support is good but not perfect. Also most non-MMC3 games can be patched to run on MMC3 mapper without any problem. Also, make sure that PRG RAM and CHR size requirements are met ().
+
+And one more thing with some weird buggy games. COOLBOY always uses writable CHR RAM even original game uses CHR ROM and it has not 'read-only' mode. So if game with CHR ROM writes to ROM for some weird reason, CHR data will be corrupted. It can be fixed using ROM patches. Example game: Cowboy Kid.
 
-## Using menu
+Also, please note that PRG RAM is not working correctly on *original* Famicoms and AV Famicoms without additional cartridge hardware modification.
 
+## Using the loader menu
 Buttons:
 * **Up** - move to previous game
 * **Down** - move to next game
@@ -132,14 +132,36 @@ Special combinations:
 * Hold **Down**+**A**+**B** on start to start second hidden ROM
 * Press **Up**, **Up**, **Down**, **Down**, **Left**, **Right**, **Left**, **Right**, **B**, **A** (the Konami code) to start third hidden ROM
 
-
 ## About flash saving system
+When cartridge with a directly writable flash memory used (/WE and /OE pins are connected to the mapper), it's possible to use this memory as additional storage. If Make started with "SAVES=1" option, the last two sectors of flash memory (256KBytes) will be reserved for it. This memory will be used to store cursor position and progress of "battery-backed" games (even if cartridge has no battery, but you'll need to press reset to save the progress in this case). Please note that flash memory will not be rewritten every time. New data will be writed to free space on active sector marked by signature. When active sector is full, all actual data will be moved to the second one. User will be warned to keep power on.
 
-When cartridge with a directly writable flash memory used (/WE and /OE pins are connected to the mapper), it's possible to use this memory as additional storage. If Make started with "SAVES=1" option, the last two sectors of flash memory (256KBytes) will be reserved for it. This memory will be used to store cursor position and progress of "battery-backed" games (even if cartridge has no battery but you'll need to press reset to save the progress in this case). Please note that flash memory is not rewrited every time. New data will be writed to free space on active sector marked by signature. When active sector is full, all actual data will be moved to the second one. User will be warned to keep power on.
+## Which cartridges are supported, how to select which cartridge to buy
+There are many versions of COOLBOY cartridges and clones. Actually most of them are not "COOLBOY", it's just a name of the first cartridges with this chip.
 
+You can find modifications:
+* **With a different CHR size**. Some cartridges has only 128KB of RAM for CHR data and some 256KB. So 128KB version can't run many cool games with CHR size >128KB. You can easily detect amount of CHR RAM after looking at games list. If it has at least one game with large CHR, cartridge has 256KB. Example games: Megaman/Rockman 5, Earthbound Zero, Kirby's Adventure
+* **With a different flash size**. Most cartridges has 32MBytes of flash memory but it's possible to find much more rare cartridges with less memory size. 32MBytes is maximum available size.
+* **With and without additional PRG RAM chip**. It's required by some games like The Legend of Zelda, Jurassic Park, etc. So if cartridge contains those games, it has PRG RAM chip. Also, it's possible to solder this chip manually usually.
+* **With and without battery**. Battery is used to keep data in PRG RAM chip even after console is turned off. It's used to save games progress. So if cartridge has battery, it also has PRG-RAM chip. There is no way to detect present of battery but usually seller can say it, also check product description in shop.
+* **With a directly writable and non-writable flash memory**. Some new cartridges can be rewrited directly without additional soldering and some not. Direct rewrite will allow you not only rewrite cartridge's flash memory using very simple way but it will also allow to keep many game saves in cartridge's memory (if PRG RAM chip exists). Originally game's progress will be erased if any other game started that uses PRG RAM even if battery present. There is no way to know which cartridge has this feature but seems like it's all cartridges produced by "MINDKIDS". So if you can look at cartridge's board, check it for "MINDKIDS" label.
+* **With a different register addresses**. Most cartridges has registers at $600x addresses but some cartridges has them at $500x. This toolset supports both versions, so you don't need to care about it.
 
-## Donate
+So it's recommended to search for MINDKIDS cartridges with battery.
 
+## In-depth info - how it works
+First method:
+1. Convert images to a NES assets using the [NesTiler](https://github.com/ClusterM/NesTiler) tool.
+2. Create a text file with a list of files and/or directories with the ROMs, optionally you can specify game names for corresponding menu entries. 
+3. Run **coolboy-combiner** with "**prepare**" option, it will automatically use the best way to fit games data in the target ROM and create "**games.asm**" file and offsets file. First one contains game names and register values for game loader menu. Second file contains info with addresses of data for every game in the final ROM.
+4. Compile assembly files using [nesasm CE](https://github.com/ClusterM/nesasm). It will create .nes file with the loader menu. But it will not contain games data. You can tune loader menu using command line options and defines: header image, background stars behavior, sounds, etc.
+5. Combine loader menu and games into one file (.nes, .unf or .bin) using **coolboy-combiner** with "**combine**" option and offsets file generated by step 2. Done.
+
+Alternative method (easier and faster):
+1. Convert images to a NES assets using the [NesTiler](https://github.com/ClusterM/NesTiler) tool.
+2. Create a text file with a list of files and/or directories with the ROMs, optionally you can specify game names for corresponding menu entries.
+3. Run **coolboy-combiner** with "**build**" option, it will automaticaly fit games, compile assembly files using [nesasm CE](https://github.com/ClusterM/nesasm) and combine everything into one file (.nes, .unf or .bin).
+
+## Donate
 https://www.donationalerts.com/r/clustermeerkat
 
 https://boosty.to/cluster