| Next revision | Previous revision |
| wswan:guide:wfconfig [2024/02/17 11:10] – created asie | wswan:guide:wfconfig [2025/08/31 19:28] (current) – asie |
|---|
| ====== wfconfig.toml ====== | ====== Project configuration ====== |
| | |
| | ===== wfconfig.toml ===== |
| |
| wfconfig.toml serves as a project-wide configuration file. | wfconfig.toml serves as a project-wide configuration file. |
| |
| ===== cartridge ===== | ==== [cartridge] ==== |
| |
| * ''rom_banks'' - The number of 64KB ROM banks used by your project; normally, this value is calculated automatically as your project grows in scope. | This section describes the [[https://ws.nesdev.org/wiki/ROM_header|cartridge header]] of the output ''.ws''/''.wsc'' file. |
| * ''save_type'' - The save type of your cartridge. The following values are supported: | |
| | The following fields can affect cartridge loaders and/or the boot ROM, and thus should be configured correctly: |
| | |
| | * **save_type** - The save type of your cartridge. The following values are supported: |
| * ''"NONE"'' - no save memory, | * ''"NONE"'' - no save memory, |
| * ''"SRAM_8KB"'' - 8 kilobytes of SRAM, | * ''"SRAM_8KB"'' - 8 kilobytes of SRAM, |
| * ''"EEPROM_2KB"'' - 2048 bytes of EEPROM, | * ''"EEPROM_2KB"'' - 2048 bytes of EEPROM, |
| * ''"EEPROM_1KB"'' - 1024 bytes of EEPROM. | * ''"EEPROM_1KB"'' - 1024 bytes of EEPROM. |
| * ''vertical'' - Set to ''true'' if your program starts out in the vertical orientation; this adjusts the boot ROM's splash screen appropriately. | * **vertical** - Set to ''true'' if your program starts out in the vertical orientation; this adjusts the boot ROM's splash screen appropriately. |
| | * **mapper** - The mapper used by your cartridge. The following values are supported: |
| ==== Metadata only ==== | * ''"2001"'' - Bandai 2001 mapper. Supports EEPROM communication. |
| | * ''"2003"'' - Bandai 2003 mapper. Supports RTC communication, GPIO pins. |
| | * **rom_banks** - The number of 64KB ROM banks used by your project. By default, this value is calculated automatically as your project grows in scope. |
| |
| The following fields have no effect on execution and exist solely as metadata: | The following fields have no effect on execution and exist solely as metadata: |
| |
| * ''publisher_id'', ''game_id'', ''game_version'' - Numeric fields describing the game's unique ID. | * **publisher_id**, **game_id**, **game_version** - Numeric fields describing the game's unique ID. |
| * ''color'' - Set to ''true'' if your program uses Color modes (regardless of whether it's mandatory or optional). | * **color** - Set to ''true'' if your program uses Color modes (regardless of whether it's mandatory or optional). |
| * ''rtc'' - Set to ''true'' if your program uses the Bandai 2003 mapper's real-time clock functionality. | |
| | The following fields are meant for advanced users only. Don't touch these unless you're building custom hardware. |
| | |
| | * **rom_bus_width** - Can be set to ''8'' or ''16''. |
| | * **rom_speed** - Set to ''2'' to enable an extra waitstate, slowing ROM reads down. |
| | * **unlock_internal_eeprom** - Set to ''true'' if your program intends to read to the normally locked area of internal EEPROM. **Note that, if used irresponsibly, this can lead to a brick on Color consoles!** |
| | * **disable_custom_boot_splash** - Set to ''true'' to force using the default boot splash on Color consoles, as opposed to the one stored in the internal EEPROM. May be used to unbrick consoles in some cases. |
| | * **rom_reserve_bootrom_area** - Set to ''true'' to exclude the last 8 KiB of each linear ROM block (memory addresses ''0xFE000'' - ''0xFFFFF'') from allocation. Note that this still allows using this area for ROM0/ROM1 allocations, as accessing them does not overlap the boot ROM. |
| | |
| | ===== Defines ===== |
| |
| ==== Advanced ==== | ==== libws ==== |
| |
| Don't touch these unless you're building custom hardware. | libws comes with some configuration options of its own, using defines: |
| |
| * ''rom_bus_width'' - Can be set to ''8'' or ''16''. | * ''-DLIBWS_USE_EXTBANK'' - if defined, the ''ws_bank'' ROM memory wrappers/functions in ''<ws/memory.h>'' will use the 16-bit bank I/O ports exclusive to the 2003 mapper, as opposed to the default 8-bit bank I/O ports. |
| * ''rom_speed'' - Set to ''2'' to enable an extra waitstate, slowing ROM reads down. | |
| * ''unlock_internal_eeprom'' - Set to ''true'' if your program intends to read to the normally locked area of internal EEPROM. **Note that, if used irresponsibly, this can lead to a brick on Color consoles!** | |
| * ''disable_custom_boot_splash'' - Set to ''true'' to force using the default boot splash on Color consoles, as opposed to the one stored in the internal EEPROM. May be used to unbrick consoles in some cases. | |
