Many system/instrument doc updates.

doc/4-instrument/game-boy.md

@@ -5,7 +5,7 @@ the Game Boy instrument editor consists of three tabs: one controlling envelope
 ## Game Boy
 
 - **Use software envelope**: switch to volume macro instead of envelope.
-  - this exploits a bug in the Game Boy sound hardware in order to have software envelopes ("zombie mode").
+  - this exploits a bug in the Game Boy sound hardware in order to have software envelopes ("zombie mode", explained more in the [Game Boy system documentation](../7-systems/game-boy.md)).
   - only a couple emulators have accurate reproduction of this bug.
 - **Initialize envelope on every note**: forces a volume reset on each new note.
 - **Volume**: initial channel volume (0 to 15).

doc/4-instrument/pet.md

@@ -4,5 +4,5 @@ the PET instrument editor consists of these macros:
 
 - **Volume**: volume sequence (on/off).
 - **Arpeggio**: pitch sequence.
-- **Waveform**: an 8×1 waveform.
+- **Waveform**: an 8×1 waveform, entered as a bitmask representing on-off pulses. this has nothing to do with wavetable assets, which cannot be used with the PET.
 - **Pitch**: fine pitch sequence.

doc/7-systems/fds.md

@@ -1,7 +1,6 @@
 # Famicom Disk System
 
-the Famicom Disk System is an expansion device for the Famicom (known as NES outside Japan), a popular console from the '80s.
+the Famicom Disk System is an expansion device for the Famicom (known as NES outside Japan), a popular console from the '80s. as its name implies, it allowed people to play games on specialized floppy disks that could be rewritten on vending machines, therefore reducing the cost of ownership and manufacturing.
-as it name implies, it allowed people to play games on specialized floppy disks that could be rewritten on vending machines, therefore reducing the cost of ownership and manufacturing.
 
 it also offers an additional 6-bit, 64-byte wavetable sound channel with (somewhat limited) FM capabilities, which is what Furnace supports.
 
@@ -35,3 +34,9 @@ this chip uses the [FDS](../4-instrument/fds.md) instrument editor.
 the following options are available in the Chip Manager window:
 
 - **Clock rate**: sets the rate at which the chip will run.
+
+## frequency modulation (FM)
+
+the FDS features a method of FM that changes the frequency of the playing note using a short looping table of 32 values. the modulation table is similar to DPCM in that it isn't a series of direct values, but deltas that determine the amount of change from the previous value.
+- deltas range from -3 to 3. in the instrument editor, -4 resets the modulation value to 0, meaning the note plays at its base frequency.
+- modulation values are 7-bit, ranging from -64 to 63; moving past those bounds will overflow to the other side (63 + 1 = -64).

doc/7-systems/game-boy.md

@@ -25,6 +25,10 @@ it has stereo sound, two pulse channels, a wave channel and a noise channel.
 
 this chip uses the [Game Boy](../4-instrument/game-boy.md) instrument editor.
 
+### "zombie mode"
+
+the game boy's envelope hardware has a bug that can be triggered to cause the volume to step up or down only on software command. Furnace uses the same method to trigger it as [LSDJ](https://www.littlesounddj.com/). without this technique, changing the volume directly on a note (such as volume macros do) would cause a phase reset each time, causing significant popping sounds. unfortunately, only a few emulators emulate the "zombie mode" bug properly.
+
 ## chip config
 
 the following options are available in the Chip Manager window:

doc/7-systems/nes.md

@@ -9,7 +9,7 @@ the console is powered by the Ricoh 2A03, a CPU with sound generator built-in. i
 ## effects
 
 - `11xx`: **write to delta modulation counter.** range is `00` to `7F`.
-  - this may be used to attenuate the triangle and noise channels; at `7F`, they will be at about 57% volume.
+  - this may be used to attenuate the triangle and noise channels; see "non-linear mixing" below.
   - will not work if a sample is playing.
 - `12xx`: **set duty cycle or noise mode of channel.**
   - may be `0` to `3` for the pulse channels:
@@ -72,12 +72,28 @@ the following options are available in the Chip Manager window:
   - DPCM: the default mode, playing 1-bit DPCM samples as supported by the hardware.
   - PCM: this mode provides crisper 7-bit samples by writing to the delta counter directly. uses a lot of CPU time in console.
 
+## non-linear mixing
+
+the triangle, noise, and PCM channels are mixed together non-linearly such that the level of the DMC (the "delta modulation counter", representing the PCM channel's amplitude) inversely affects the volume of the others. this can be intentionally used with effect `11xx` to hold the DMC at a level that lowers the volume of the triangle channel in a controlled fashion; at maximum DMC level (`117F`) the triangle plays at about 57% of full volume.
+
 ## DPCM samples
 
 due to hardware limitations, a loop in a DPCM sample must start on a multiple of 512 samples (512, 1024, 1536...) and have a length that is a multiple of 128 plus 8 samples (136, 264, 392...)
 
 NES DPCM only has 16 preset sample rates, shown in a table below. for help adapting samples to work with this, see the [limited samples guide](../9-guides/limited-samples.md).
 
+## envelope mode
+
+both pulse channels and the noise channel have a simple hardware envelope generator with two modes: one that holds the volume at whatever the software sets, and one that creates a downward ramp of volume starting from maximum and counting down to 0. the volume range of the ramp can't be controlled (similar to the triangle wave, for the same reason). the envelope can be set to loop each time it reaches 0.
+
+## frame counter
+
+the frame counter is a global counter that controls the speed of hardware envelopes and sweeps. the resulting speed depends on both the chip's clock rate and whether it's set to 4-step or 5-step mode.
+
+## length counter
+
+setting the length counter will automatically stop a note after the specified amount of time. note that the effect values aren't arranged in a convenient way for their lengths; for convenience, they are shown in a table below.
+
 ## short noise frequencies (NTSC)
 
 note  | arpeggio | fundamental | MIDI note | pitch

doc/7-systems/pet.md

@@ -4,12 +4,12 @@ a computer from 1977 which was leader on US schools back then. subsequently the
 
 maybe no better than a computer terminal, but somebody discovered a way to update the screen at turbo rate - and eventually its sound "chip" (it was nothing more than an 8-bit shift register) was abused as well.
 
-some of these didn't even have sound...
+some of these didn't even have sound output, leaving the user to solder in a speaker on their own...
 
 ## effects
 
 - `10xx`: **set waveform.**
-  - `xx` is a bitmask.
+  - `xx` is a bitmask representing a pattern of on-off pulses. it has nothing to do with wavetable assets, which can't be used by the PET.
 
 ## info