Code: Select all
FamiTracker NSF to GBS converter
Usage: lua ft_nsf2gbs.lua [filename]
The following builds are supported:
- FamiTracker 0.4.5 stable
- FamiTracker 0.4.6 stable
- 0CC-FamiTracker 0.3.13 (last revision build)
See http://gist.github.com/HertzDevil/d204524485d3a37a1829 for details.
(C) HertzDevil 2016
Notes / caveats:
- The only argument is the NSF filename and there are no other options at all.
- Your NSF must use exactly one N163 channel, and no other expansions, otherwise the script should throw an error. Bankswitched NSFs are supported.
- Do not modify any file within the "inc/" directory, as these are precompiled headers containing the GB-Z80 port of the FamiTracker NSF driver. The source assembly files of the port, complete with all the GB-specific effects as listed in the gist notes shown above, will be posted later at the Source board.
- The script patches an appropriate timer value depending on the refresh rate and the default region of the NSF. The closest rate to 60 Hz is 60.015 Hz; the source code allows using the vertical blank instead of the timer to generate interrupts, which corresponds to 59.726 Hz, but this is unavailable in ths script here.
- The GB ROM image cannot switch tracks.
- The triangle and DPCM channels do not output anything, but global effects (Bxx, Cxx, Dxx, Fxx, 0CC-FT Oxx) on these channels will still work.
- The driver does not perform any calculation whatsoever that converts N163 frequencies to GB wave channel periods. If your FTM uses any pitch effect at all, do not expect that they will work right away in the converted files.
- However, like the 2A03 triangle channel, the Game Boy wave channel is exactly one octave lower than the pulse channels given the same period register; to see if your pitch effects work as intended on the N163, simply put the same pattern data on the triangle channel.
- Hardware sweeps are a bit unstable right now. Also they do not work in Pulse 2, and Ixx commands do not silence the channel on period overflow (actually underflow on the Game Boy).
- Any update in the Game Boy noise channel's volume will reset its LFSR state, so volume sequences that change on every tick will effectively perform a hard sync.
- Some older GB emulators or GBS players have trouble changing between the long and short periodic noises in the middle of a note.
- The Game Boy's hardware volume envelopes are supported, but you have to manually locate the volume sequences in the exported file and modify the upper nibbles for it to work. (In the same volume sequence, the same value will not be written to the volume register for multiple consecutive times.)
- The old vibrato style is not supported right now.
- The script patches the 2A03's period table rather than that of the N163. This is not an issue for 0.5.0 if and once its stable version is out, but 0CC-FT modules should not use different detune tables for 2A03 and N163.
- In 0CC-FamiTracker NSFs, 2A03 duty sequences will apply to the wave channel's current wave table. This is an as-of-yet undecided implementation detail in 0CC-FT's tracker side.
Using 0CC-FamiTracker you could also convert any 2A03-only module quickly by following these steps:
- Ensure that all instruments used on the triangle channel do not contain DPCM assignments. You may need the find / replace dialog to swap instrument indices on the triangle channel only.
- Replace the first instruments used on the triangle channel of all tracks by N163 equivalents, with the same instrument indices or new ones. Instrument sequences may be directly copied to the N163 instruments.
- Swap the triangle channel (2A03, channel 3) and the N163 channel for all tracks.
- Now ensure that all 2A03 instruments used on the N163 channel do not contain duty sequences, so that they will not overwrite the wave buffer in both the tracker and the GBS / GB files.