GoatTracker v1.0
----------------

Editor by Lasse rni (loorni@student.oulu.fi)
reSID engine by Dag Lem.

Distributed under GNU General Public License
(see the file COPYING for details)


General information
-------------------

This program is a C64 music editor running as a 32-bit Windows application
(should work on W9x/NT4/W2K etc.) Familiarity with tracker programs in general,
hexadecimal notation, and the C64's audio chip (consult the C64 Programmer's
Reference Guide, it's available on the net too) are required to successfully
utilize this program.

How to use
----------

One word of warning:
Always save your songs in the .SNG-format with F11 key if you plan to continue
editing! Packed & relocated songs (.PRG/.BIN/.SID) can't be loaded back into
the editor.

Run the program with the option /? to see the list of command line options.
For example, if you experience choppy audio you can increase audio buffering.
There's also screenmode options and the possibility to file-write all audio
output.

There's also HardSID support available with the /H option. (use first
HardSID = /H1, second = /H2 etc., return to emulated output = /H0)
You must have the HardSID drivers installed to use this feature.

This program is entirely operated on keyboard. For a list of keyboard commands
press F12 in the tracker. Next follows a description of the song, pattern &
instrument data.


Song data
---------

A song can consist of up to 32 sub-tunes. Each sub-tune has pattern-orderlists
for all 3 channels. The pattern-orderlist is a list of patterns to be played
(max. 255 columns long) plus the endmark, which can be either RST (restart;
repeat orderlist from beginning) or STP (stop; repeat last pattern infinitely)


Pattern data
------------

Patterns are single-channel as there's a pattern-order list for each channel.
A pattern can have variable length, however 80 rows is the maximum. There can
be 254 different patterns in a song.

The explanation of a pattern row:

 Note name
 |
 | Octave
 | |
 | | Instrument number (01 - 1F, or 00 for no change)
 | | |
 | | |  Command (0 - 7)
 | | |  |
 | | |  | Databyte
 | | |  | |
 C-1 00 0 00

Commands 0,1 & 3 and 4 bear some resemblance to Soundtracker/Protracker/
Fasttracker effects. However, they are different in some ways, so read their
descriptions!!! Note that there is no "databyte 00 uses the last databyte"-
action in the commands.

The "continuous" commands 0, 1, 3 and 4, are executed only on ticks 1-N, where
N is tempo - 1, and commands 2, 5, 6 and 7 are executed on tick 0 (when a new
pattern row is also read)

Command 0XY: Arpeggio. Arpeggiates with the root note, then root note + X
             halftones and then root note + Y halftones. If the X value
             is 8 or higher, the arpeggio will be at half speed (8 will
             be subtracted from the value of X to get the amount of halftones)

Command 1XY: Portamento. Raises the pitch with (XY and 7F) * 2 each tick.
             Highest bit of XY decides direction: 0 is up and 1 is down.

Command 2XY: Set filter cutoff speed. The cutoff speed will be added to the
             cutoff frequency each tick, until stopped with a 200 command.

Command 3XY: Toneportamento. Raises or lowers pitch until target note has been
             reached. Highest bit of XY decides direction of toneportamento
             (this is an optimization for the C64 playroutine, to keep it fast:
             you must know the direction yourself) and the actual speed used
             is (XY and 7F) * 2. By specifying the "wrong" direction you can
             get infinitely fast toneportamentos that go to the target note
             right away, for the "tie note" effect.

Command 4XY: Vibrato. X determines how fast the direction will change (E
             is slowest and the lowest bit doesn't matter) and Y*16+X is the
             amount of pitch change on each tick. (That weird formula is just c
             aused by playroutine optimizations)

Command 5XY: Set filter parameters. X is the filter resonance and Y is the
             bitmask of channels to be filtered.

               Bitvalue 01 = Channel 1
               Bitvalue 02 = Channel 2
               Bitvalue 04 = Channel 3

Command 6XY: Set sustain/release. Sets the channel's sustain/release register
             to XY.

Command 7XY: Set tempo. If highest bit is 1 (values 80-FF) the tempo
             (XY and 7F) will be set to current channel only, otherwise on
             all channels. A tempo lower than 3 can't be used.

             If there's both a "current channel" and "all channels" tempo
             change on a same row, the "all channels" tempo change must be
             on the lesser channel number or else the "current channel" tempo
             setting will be overrided.


Instrument data
---------------

If a description for a parameter is separated in two by a slash it means it
contains two different parameters: leftmost hexadecimal nybble is the first
parameter and rightmost is the second.

Attack/Decay          0 is fastest attack or decay, F is slowest

Sustain/Release       Sustain level 0 is silent and F is the loudest. Release
                      is a speed like attack & decay.

Pulse                 The starting value of pulsewidth (00-FF)

Pulse Speed           The value that will be added to pulsewidth each tick
                      (0-F)

Pulse Limit Low       The pulsewidths where pulsewidth modulation will change
Pulse Limit High      its direction. The low nybble will be always 0 because of
                      optimizations.

Filter Freq/Type      Frequency is the highest 8 bits of cutoff frequency.
                      Filter type is a bitmask consisting of:

                        Bitvalue 01 = Lowpass filter
                        Bitvalue 02 = Bandpass filter
                        Bitvalue 04 = Highpass filter

                      This byte comes into effect when a new note is played.
                      If its value is 0 then filter cutoff & type will be
                      unchanged. Because there's only one filter, it's a good
                      idea to have filter-controlling instruments only on one
                      channel at a time :-)

                      NOTE: From V0.93 Beta onwards the low 4 bits (type)
                      also affect cutoff frequency. This is a playroutine
                      optimization.

In addition to these parameters, each instrument has a wave/note table that
determines the waveforms and pitches to be used when a note starts. With
this table you can make either a simple sound that just has one waveform and
the note's base pitch, or a complex sound that has many waveform changes
(to make good-sounding drums), or anything in between.

The wave/note table consists of byte pairs. The leftmost byte is always the
waveform and the rightmost is the note. A pair that has FF in the waveform
ends wavetable execution (if note number is 00) or loops to position n (if note
number n > 0) NOTE: before the table ends, no portamento, vibrato or arpeggio
will be executed! Pulsemodulation will be executed, as of V0.94 onwards.

A waveform of 00 tells not to change the waveform, this is useful if you use
keyoffs (gatebit off) during wavetable execution.

Waveform byte consists of these bits:

  Bitvalue 01 = Gate bit. THIS IS IMPORTANT TO GET AN AUDIBLE SOUND! Gate bit
                initiates the attack/decay/sustain phase of a sound. When it
                goes zero, the release phase begins.
  Bitvalue 02 = Synchronize bit. Will synchronize with an another channel
                (Consult C64 Programmer's Reference Guide for details)
  Bitvalue 04 = Ring-modulation bit. Will ring-modulate with an another channel
                (Consult C64 Programmer's Reference Guide for details)
  Bitvalue 08 = Test bit. Will silence the channel and reset the random-seed
                of a channel if the noise random generator has "locked up"
                because of using noise waveform in combination with another
                waveform. This value is automatically used when a song starts
                playing!
  Bitvalue 10 = Triangle waveform
  Bitvalue 20 = Sawtooth waveform
  Bitvalue 40 = Pulse waveform. There must be nonzero pulsewidth on the
                instrument or else this waveform will be silent!
  Bitvalue 80 = Noise waveform. Don't combine with other waveforms!

Note byte consists of these values:

  00-5F       = Relative notes. Will be added to the current note playing
                on that channel to get the final pitch
  80-DF       = Absolute notes C-0 - B-7.

Values outside of this range will result in a pitch that isn't any correct
note.

Some examples of wave tables:

  21/00 Sawtooth waveform on note's original pitch
  FF/00

  81/C8 A snaredrum sound, using all absolute notes so it doesn't depend on
  41/A8 which note it's played. Use pulsewidth 80 for best result.
  41/A0
  80/C8
  80/C4
  FF/00

  81/C8 A pulse sound on original pitch, preceded with a short noise (like
  41/00 a hi-hat or something) that has always an absolute pitch of G#6
  FF/00

  41/00 A 4-note arpeggio sound with pulse waveform. (Arpeggio command itself
  00/04 uses only 3-note arpeggios) Note that waveform will not be changed
  00/07 after the initial setting of pulse waveform.
  00/0C
  00/00
  FF/02


Using the songs in your own program
-----------------------------------

Press F9 in the editor to enter the packer/relocator. Choose startaddress
and file format (PRG or BIN), and then type the filename.

Music playing will take 12 rasterlines max. The player uses zeropage locations
$FB, $FC and $FD as temporary variables.

To init music:

        LDA #tunenumber (starting from 1)
        STA startaddress+$01

To play music:

        JSR startaddress

To change volume: (0-F, default is F)

        LDA #volume
        STA startaddress+$5D

To tweak instrument data: Instruments reside as 8-byte structures starting
from startaddress+$044e:

        Instr. 1 AD              startaddress+$044E
        Instr. 1 SR              startaddress+$044F
        Instr. 1 Pulse           startaddress+$0450 *
        Instr. 1 Pulsespeed      startaddress+$0451 *
        Instr. 1 Pulselimit Low  startaddress+$0452 *
        Instr. 1 Pulselimit High startaddress+$0453 *
        Instr. 1 Filt. Freq/Type startaddress+$0454
        Instr. 1 Wavetbl. Index  startaddress+$0455
        Instr. 2 AD              startaddress+$0456 etc.

Observe that parameters marked with (*) have actually the nybbles reversed
from what they look like in the editor.


Version history
---------------

0.9 Beta  - Original public release

0.91 Beta - Corrected a crash caused by an uninitialized pointer when executing
            wavetable on the last row of a pattern. This same bug also caused
            sounds being cropped one tick too early on the last row.
          - Corrected the description of ringmodulation in the docs
          - A drum test song added (when making it the crash was discovered)

0.92 Beta - Orderlist editing simplified (one cursor position for all channels)
          - SPACE in orderlist sets now play position for F2 key
          - Pattern wrap also when trying to enter notes on the last pattern
            row

0.93 Beta - Vibrato was practically useless on odd speeds (3, 5 etc.) because
            it went a bit out of tune. Now the whole vibrato routine has been
            rewritten and the meaning of the speed parameter has changed.
          - Playroutine optimizations in filter cutoff setting & vibrato pitch
            change: the second parameter will also affect them, however it's
            the 4 lowest bits so it doesn't matter much.

0.94 Beta - Reworked wavetable system making wavetable loops possible. Also,
            now pulsemodulation is executed during wavetable. Still the player
            takes only 12 lines!
          - Note that you have to change the wavetable end byte manually from
            00 to FF if you load songs or instruments made with old versions.
          - Command 6 (set sustain/release) is no longer overridden by
            wavetable execution.
          - Wavetable maximum length (for packed & relocated songs) is now
            510 bytes.
          - Added musicdata clear option (SHIFT+ESC).

0.95 Beta - Some reordering in the playroutine, however retaining the same
            size as in 0.94. Init music & Set volume subroutines added to the
            playroutine.
          - Wavetable maximum length is now 512 bytes.

0.96 Beta - $d404 must come before $d405 & $d406 in note initialization to get
            sharper attack.
          - Had to remove the Init & Set volume subroutines. (no room for them)
          - Instruments with looped wavetables didn't always play correctly
            when entering notes in the editor - fixed.
          - The playroutine startaddress is now remembered when packing/
            relocating multiple songs during one session.

0.97 Beta - Added screenmode options.

0.98 Beta - Added Follow Play option (SHIFT+F1/F2)
          - Added fast scrolling with PAGE UP & PAGE DOWN keys.
          - SHIFT+RETURN in orderlist editor updates pattern numbers of all
            channels.

0.99 Beta - Added HardSID support. Use /H1 option to utilize first HardSID, /H2
            for second etc. and /H0 to return to emulated output.

1.0       - Added HOME/END to go to the beginning/end of an orderlist or a
            pattern.
          - Note and hexvalue entry work now also with SHIFT or CAPS-LOCK down.
