gt2fork

• Editor by Lasse Öörni and Jan Wassermann.
• Music playroutines by Lasse Öörni.
• Uses reSID engine by Dag Lem and Leandro Nini.
• Uses reSIDfp distortion / nonlinearity by Antti Lankila and Leandro Nini.
• Uses 6510 crossassembler from Exomizer2 beta by Magnus Lind.
• Uses the SDL2 library.
• Uses the RtMidi library.
• Uses parts of the GoatTracker icon by Antonio Vera.
• Command quick reference by Simon Bennett.
• Patches and further development by Stefan A. Haubenthal, Valerio Cannone,
  Raine M. Ekman, Tero Lindeman, Henrik Paulini and Groepaz.
• Microtonal support by Birgit Jauernig.

Distributed under GNU General Public License 2.0 (see the file LICENSE for details).

Table of contents

• Command line options
• Keyboard commands
  • General Keys
  • Pattern edit mode
    • Entering notes
  • Song edit mode
  • Instrument edit mode
  • Table edit mode
  • Songname edit mode
• Mouse control
• Song data
  • Orderlist data
  • Pattern data
    • Commands
  • Instrument data
  • Table data
    • Wavetable
    • Pulsetable
    • Filtertable
    • Speedtable
• Playback details
• Miscellaneous tips
  • Limit-based modulation steps
  • Precalculated note-independent "hifi player" portamento/vibrato
• Multispeed tips
• Using the songs outside the editor
  • Playroutine options

Command line options

-Axx Set ADSR parameter for hardrestart in hex.
     DEFAULT=0F00

-Bxx Set sound buffer length in milliseconds
     DEFAULT=100

-Dxx Pattern row display
     (0 = decimal, 1 = hexadecimal)

-Exx Set emulated SID model
     (0 = 6581 1 = 8580)
     DEFAULT=8580

-Fxx Set custom SID clock cycles per second
     (0 = use PAL/NTSC default)

-Gxx Set pitch of A-4 in Hz
     (0 = use default frequencytable, close to 440Hz)

-Ixx Set reSID/-FP settings
     (0 = reSID Fast Resample,
      1 = reSID Resample,
      2 = reSID-FP Interpolate,
      3 = reSID-FP Interpolate Resample)
     DEFAULT = reSID Resample

-Jxx Set special note names
     (2 chars for every note in an octave/cycle, e.g. C-DbD-EbE-F-GbG-AbA-BbB-)

-Kxx Note-entry mode
     (0 = Protracker, 1 = DMC, 2 = Janko)
     DEFAULT=Protracker

-Lxx SID memory location in hex.
     DEFAULT=D400

-Mxx Set sound mixing rate
     DEFAULT=48000

-Oxx Set pulseoptimization/skipping
     (0 = off, 1 = on)
     DEFAULT=on

-Qxx Set equal divisions per octave
     (12 = default, 8.2019143 = Bohlen-Pierce)

-Rxx Set realtime-effect optimization/skipping
     (0 = off, 1 = on)
     DEFAULT=on

-Sxx Set speed multiplier
     (0 for 25Hz, 1 for 1x, 2 for 2x etc.)

-Vxx Set finevibrato conversion
     (0 = off, 1 = on)
     DEFAULT=on

-Xxx Set window type
     (0 = window, 1 = fullscreen)
     DEFAULT=window

-Yxx Path to a Scala tuning file .scl

-Zxx Set random reSID write delay in cycles
     (0 = off)
     DEFAULT=off

-N   Use NTSC timing

-P   Use PAL timing (DEFAULT)

-W   Write sound output to a file SIDAUDIO.RAW

-?   Show command line options info

-??  Standalone online help window

Keyboard commands

• General Keys
• Pattern edit mode
  • Entering notes
• Song edit mode
• Instrument edit mode
• Table edit mode
• Songname edit mode

General Keys

Pattern edit mode

For pattern joining to work properly, select the pattern you want to join with the next from the orderlist first (by pressing RETURN on it). Both joining and splitting will rearrange pattern numbers (for example if you split pattern 00, pattern 01 will be created and old patterns 01-xx will be shifted forward in the pattern order).

SHIFT+SPACE will play from the pattern onwards if playback was previously stopped, but if it is pressed while in pattern play mode, it will stay in the current pattern.

Entering notes

There are two rows of a piano keyboard:

 23 567 90        Higher octave
QWERTYUIOP

 SD GHJ L          Lower octave
ZXCVBNM,.

Song edit mode

SHIFT+SPACE or SHIFT+BACKSPACE set the start/end mark on all channels to the same position. To clear the endmark, press BACKSPACE again on it or at/before the startmark.

Instrument edit mode

The test note will be played on the channel you last were on in the pattern editor. To hear filtering as intended, be sure to play it on a channel that has been selected for filtering in the filter parameters.

Note that cut,copy,paste instrument do not touch the tabledata, just for the case you need it in another instrument. If you want to completely get rid of an instrument + its associated tabledata, press SHIFT+DEL.

If wave/pulse/filter/vibrato param. is zero and you press RETURN over it, you will move to the first free location in the corresponding table. If you press SHIFT+RETURN, also the instrument parameter will be set accordingly.

If vibrato parameter is nonzero and you press SHIFT+RETURN over it, it will be interpreted as an old style vibrato parameter (left nybble speed, right nybble depth) and converted to a speedtable entry.

"Smart paste" will convert instrument numbers in all patterns if you "move" an instrument by cut/pasting it.

Table edit mode

If you need to insert rows in the beginning of an instrument's wave/pulse/ filtertable, press SHIFT+INS instead of just INS: this way table pointers pointing to the table first row will not move.

For easier programming of negative modulation speeds in pulse/filtertables, you can first enter a positive speed positive value ($00-$7F) and then press SHIFT+N to negate it.

Conversion between relative and absolute notes will use the basenote C-0 if octave is 0, C-1 if octave is 1 and so on.

When table scrolling is unlocked, each table maintains its separate view position. To indicate this mode, a "U" letter is visible in the bottom right part of the screen. By default table scrolling is locked.

Songname edit mode

Use CRSR UP/CRSR DOWN to move between song, author & copyright strings, and other keys to edit them.

Mouse control

By clicking with the left mouse button, you can select the data to edit.

By dragging with middle or right mouse button, you can mark orderlist/pattern/tabledata.

Some values like octave or subtune/pattern numbers can be incremented with the left mouse button and decremented with the right.

By holding the middle/right mouse button in the status bar, a menu becomes active. Continue to hold and click with left button to select options.

In the fileselector, confirm loading or entering a directory by double-clicking. Doubleclick outside the selector to cancel.

Song data

• Orderlist data
• Pattern data
  • Commands
• Instrument data
• Table data
  • Wavetable
  • Pulsetable
  • Filtertable
  • Speedtable

Orderlist data

A song can consist of up to 32 subtunes. For each subtune's each channel, there is an orderlist which determines in what order patterns are to be played. In addition to pattern numbers, there can be TRANSPOSE & REPEAT commands and finally there is a RST (RESTART) endmark followed by restart position. The maximum length of an orderlist is 254 pattern numbers/commands + the endmark.

TRANSPOSE is measured in halftones. Transpose up (shown as +X) can be 0-14 halftones and transpose down (shown as -X) can be 1-15. Transpose is automatically reset only when starting the song, not when looping.

A REPEAT command (shown as RX) will repeat the pattern following it 1-16 times. "Repeat 16 times" is displayed as R0.

There are some rules for orderlist command order:

• If there are both TRANSPOSE and REPEAT commands before a pattern number, TRANSPOSE must come first.
• The last thing before the RST-endmark must be a pattern number. If you need to reset transpose on song repeat, do it in the beginning of the repeat loop.

In case of wrong order, the editor will halt playback. This tells that the resulting packed/relocated song would play incorrectly.

Pattern data

Patterns are single-channel only for flexibility & low memory use. They contain the actual notes, instrument changes & sound commands. A pattern can have variable length, up to 128 rows. There can be 208 different patterns in a song.

The explanation of a pattern row:

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

The highest note available in a pattern is G#7. To reach the top three notes (A-7 to B-7), you can use transpose.

In place of a normal note, there can also be one of these special "notes":

     ... Rest
     --- Key off (clear gatebit mask)
     +++ Key on (set gatebit mask)

The actual state of the gatebit will be the gatebit mask ANDed with data from the wavetable. A key on cannot set the gatebit if it was explicitly cleared at the wavetable.

Commands:

Commands 1XY-4XY and FXY bear some resemblance to Soundtracker/Protracker/Fasttracker effect commands. 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.

0XY

1XY

2XY

3XY

4XY

5XY

6XY

7XY

8XY

9XY

AXY

BXY

CXY

DXY

EXY

FXY

Master volume is by default the maximum ($F), but it is only reset when loading a new song or clearing songdata in the editor, not every time playback starts. If you change mastervolume, you have to reset it manually in the beginning of your song.

If the command is not 1XY-4XY, instrument vibrato will be active.

Note that the one-shot commands 5XY-FXY allow the previous 1XY-4XY command or instrument vibrato to continue "underneath" them. In section 3.6 (hints & tips) there is an example of this.

Instrument data

You can use up to 63 different instruments in a song. Each instrument is defined by 9 parameters:

In case of illegal (too high) gateoff timer values, the song playback is stopped.

ADSR settings are crucial to getting any sound at all. If all of them are zero just a very short "click" will be heard. Here is a diagram to help you visualize the Attack, Decay, Sustain & Release phases:

     V      /\            |<- gatebit reset (key-off) at this point
     O     /  \           |
     L    /    \__________|
     U   /                |\
     M  /                 | \
     E /                  |  \
TIME ---------------------------->
         A   D      S       R

Some ADSR examples:

 A/D 09
 S/R 00 

 A/D 00
 S/R 8A 

 A/D CC
 S/R AF 

Instrument legato works as following: When HR/Gate Timer parameter has bit $40 set, no hard restart or gateoff will be performed. When 1st Frame Wave is also $00, no 1st frame waveform will be set and gate flag is untouched. However wave/pulse/filterpointers and ADSR are initialized normally. You can also use this in conjunction with command 8XY to set another wavetable pointer for the note.

Table data

Tables control the execution of instruments' waveform/arpeggio changes, pulse modulation, and filter modulation. All the tables are controlled by the left side bytes, while the right side byte specifies additional parameters.

Note that you should never jump directly onto a table jump command (FF) either with instrument parameters or pattern commands 8XY, 9XY, AXY. Otherwise, results are undefined.

Wavetable

00

00-5F

 01-0F 

 60-7F 

 10-DF 

80

 E0-EF 

 81-DF 

 F0-FE 

FF

Short explanation of waveform bitvalues:

 01 

 02 

 04 

 08 

 10 

 20 

 40 

 80 

All waveforms except noise can be combined (for example triangle + pulse), but the effect will be different on 6581 and 8580 SID chips, so use with caution.

On many 6581 SID chips only 50 (triangle + pulse) will be audible. On 8580 it is usually safe to use all of the mixed waveforms: 30 (triangle + saw), 50 (triangle + pulse), 60 (saw + pulse).

The way how the channels work with synchronize/ringmod:

• When used on channel 1, channel 3's output modulates the sound.
• When used on channel 2, channel 1's output modulates the sound.
• When used on channel 3, channel 2's output modulates the sound.

Wavetable delay or no wavechange should not be used in the first step of instrument wavetable. Otherwise, missing notes may be caused. On the other hand, if you use 8XY command to jump into a wavetable program, those are allowed.

Using wavetable delay or a wavetable step with no frequency change allows realtime commands & instrument vibrato to be executed together with wave-table. Be warned that this has the potential for large rastertime usage!

You can execute pattern commands from the wavetable. Right side is the command parameter. Note that commands 0XY (do nothing), 8XY (set wavetable pointer) and EXY (funktempo) are illegal and should not be used. When executing a command, no wave/note will be changed on the same frame.

Some examples of wave tables (all examples start on table step 1):

  01: 21 00
  02: FF 00  

  01: 41 00
  02: 11 00
  03: FF 00  

  01: 41 01
  02: 40 00
  03: FF 00  

  01: 81 D0
  02: 41 AA
  03: 41 A4
  04: 80 D4
  05: 80 D1
  06: FF 00  

  01: 81 DF
  02: 41 00
  03: FF 00  

  01: 41 00
  02: 00 04
  03: 00 07
  04: 00 0C
  05: 00 00
  06: FF 02  

  01: 21 00
  02: 02 03
  03: 02 07
  04: 02 00
  05: FF 02  

  01: 41 00
  02: 03 80
  03: 11 80
  04: 03 80
  05: 41 80
  06: FF 02  

  01: 81 CF
  02: 21 00
  03: 08 00
  04: F6 2A
  05: FF 00  

Pulsetable

Pulsetable left side:

 01-7F 

 8X-FX 

 FF 

Some examples of pulse tables (all examples start on table step 1):

01: 88 00
02: FF 00

01: 80 10
02: 20 40
03: 40 E0
04: 40 20
05: FF 03

Filtertable

Filtertable left side:

 00 

 01-7F 

 80-F0 

 FF 

If "Set filter parameters" is followed by "Set cutoff" directly below, both will be executed on the same frame.

Some examples of filter tables (all examples start on table step 1):

01: 90 F1
02: 00 40
03: FF 00

01: 80 00
02: FF 00

01: A0 87
02: 00 00
03: 7F 01
04: 7F 01
05: 7F FF
06: 7F FF
07: FF 03

01: C0 F2
02: 00 F0
03: 90 F2
04: 00 50
05: FF 00

Note that the second example could also be achieved simply with pattern command B00 (set filter control, and stop filter execution, because parameter was $00).

Speedtable

The speedtable is shared by vibrato, portamento and funktempo. No jump commands exist.

 XX YY 

 XX YY 

 XX YY 

For both vibrato and portamento, if XX has the high bit ($80) set, note independent vibrato depth / portamento speed calculation is enabled, and YY specifies the divisor (higher value -> lower result and more rastertime taken).

Vibrato examples:

 01: 03 40 

 01: 05 04 

 01: 83 04 

Portamento examples:

 01: 00 20 

 01: 01 00 

 01: 4F FF 

 01: 80 01 

Funktempo examples:

 01: 09 06 

 01: 24 18 

Note that you can enter old style vibrato parameters, portamento speeds and funktempo to patterns & instruments, and when cursor is over the parameter, press SHIFT+RETURN to create a new speedtable entry corresponding to that parameter. The parameter will now be overwritten by a speedtable pointer.

Playback details

Each pattern row is divided into as many 50Hz/60Hz "ticks" as the tempo indicates. Some ticks are reserved for special actions, and to conserve rastertime, certain realtime effects/commands (pulse, vibrato, portamento) are skipped at the same time. Let's assume a tempo of 6 and gateoff timer value 2 and look at what happens on each tick:

 0 

 1 

 2,3 

 4 

 5 

Filtertable is executed on each tick regardless of what the channels are doing. Wavetable is never skipped, so arpeggios/drumsounds should always play OK.

With the commandline parameter /O0 (or by clicking the "PO" text on the statusbar) you can disable pulse skipping. This leads to increased rastertime use but can be good for example with tempo 3 tunes.

Likewise, with the commandline parameter /R0 (or by clicking the "RO" text on the status bar) you can disable realtime pattern command skipping on tick 0.

Miscellaneous tips

• Limit-based modulation steps
• Precalculated note-independent "hifi player" portamento/vibrato

• Patterns will take less memory the less there are command changes. When the song is packed/relocated, for example a long vibrato or portamento command needs to be stored only once as long as the parameter stays the same on subsequent pattern rows.
• Using instrument vibrato can make 4XY commands unnecessary and save even more memory. Use realtime calculated note-independent speed (see speedtable section) if you want the vibrato to have the same magnitude regardless of the note.
• In the instrument parameters, there is no option to stop pulse execution directly. So if you have for example a sawtooth instrument, there might be an "unnecessary" pulsemodulation going on underneath and wasting rastertime.

  There are two ways you can stop this:

  1. Make a short pulseprogram like this and use it in the instrument:

      01: 80 00 

     Set pulse $000

      02: FF 00 

     Stop pulse execution
  2. Use pattern command 900 to stop pulse execution
• If you have a realtime command (vibrato/portamento), you can put "one-shot" commands 5XY-FXY inbetween and the realtime command will be unaffected.

  An example:

    C-4 01000
    --- 00401 Begin vibrato with speedtable index $01
    --- 00401
    --- 00401
    --- 0065A Set sustain/release to $5A. Vibrato executes also on this step!
    --- 00401 Continue vibrato normally
    --- 00401
  

  However, the vibrato would stop immediately if command 0 was encountered.
• Normally tempo 3 is the fastest you can use. However, by using the funktempo command you can get tempo 2. To do this, create a following speedtable entry: 02 02, and point your funktempo command to it. You also need to use gateoff timer 1 in all instruments and disable the pulse-optimization skipping.
• For very optimized songdata & player you can refrain from using any pattern commands and rely on the instruments' step-programming. Even in this case, you can set song startup default tempo with the Attack/Decay parameter of the last instrument (63), if you otherwise leave this instrument unused.

Limit-based modulation steps

You can enter pulse/filter modulation steps in limit-based format, and convert them to time-based with SHIFT+L. For example, you could enter the following in the pulsetable:

  01: 84 00 Set initial pulse to $400
  02: C0 10 Modulate pulse to $C00 with speed $0010
  03: 40 10 Modulate pulse back to $400 with speed $0010

Now position the cursor on step 02 and press SHIFT+L twice, to convert both of the modulation steps to usual time-based steps. If necessary, the steps will be expanded to several (if the resulting time parameter is over $7F).

Remember that the player only understands time-based steps and you always have to convert limit-based steps before they play correctly!

Precalculated note-independent "hifi player" portamento/vibrato

From v2.62 onwards, GoatTracker actually supports realtime calculated note independent portamento and vibrato speeds, see speedtable section for this. However, this makes the player bigger and much slower. You can still also use the old method of manually precalculating needed note-independent speeds with the SHIFT+H function, which this section is about.

The idea is to take the frequency difference between 2 adjacent notes in the frequency table and manipulate it by bit shifting left (multiply) or right (divide).

To use, you need a portamento or vibrato command in the pattern, and the note you wish to base the calculation on on the current pattern step or before it (before it only for toneportamento) The amount of shift is determined by the command parameter. A number in the left nybble means shift left and right nybble right shift. When you press Shift+H while the cursor is on the command, a speedtable entry is created, and the parameter is replaced with a speedtable index.

Some examples:

 C-3 00110 

 E-4 00000 
 ... 00000 
 G-4 00302 

Multispeed tips

• When making multispeed songs, remember to multiply your tempos and also the gateoff timer values! For example, gateoff timer is normally 2, but in a 2X- speed tune the same gateoff length would be achieved with value 4.
• If you want to keep vibrato the same compared to 1X-speed, you must multiply vibrato speed by the speed multiplier, and divide vibrato depth by the multiplier. Remember also to divide portamento and pulse/filter modulation speeds as necessary.
• When importing a v1.xx multispeed song, you also need to multiply the gateoff timers.
• In the instruments, using Attack 0 might result in a very silent first row of the wavetable. You could try increasing the attack, or adding one or more rows of E9 00 (testbit+gate) to the beginning of the wavetable.

Using the songs outside the editor

Press F9 in the editor to enter the packer/relocator. Choose playroutine options, startaddress, zeropage address (need 2 consecutive locations) and file format (PRG/BIN/SID), then type the filename.

If you use patterns longer than 64 rows, there is the possibility that relocation fails because of too complex patterns. Each pattern row can be 0-4 bytes packed, and the total amount of bytes per one pattern may not exceed 256.

If wave/pulse/filtertables overflow past row 255 without a jump command or there are other serious errors, you get a warning screen and have to fix the error.

Look at /examples/example1.prg - example4.prg to get an idea how much these playroutines take rastertime. No promises!

The basic functions independent of playroutine options are:

Init music:

        LDA #subtunenumber       ;Starting from 0
        JSR startaddress

Play one frame of music:

        JSR startaddress+3

Playroutine options

BUFFERED SID-WRITES - Instead of writing each SID value as soon as possible, waits for the end of the channel's execution on each frame and then writes the registers in one go. Improves sound stability but takes more memory & raster- time.

SOUND EFFECT SUPPORT - Adds a sound effect engine for use in games. Implies buffered writes. To use, call in the following way:

    LDA #<effect        ;Start address of sound effect data
    LDY #>effect
    LDX #channel        ;0, 7 or 14 for channels 1-3
    JSR startaddress+6

The sound effects have a hardcoded priority system based on their start addresses. A sound higher up in memory (bigger address) will never be interrupted with a sound lower in memory.

VOLUME CHANGE SUPPORT - Adds a routine in the player's jumptable to change the master volume level. To use, call in the following way:

    LDA #volume        ;0-15
    JSR startaddress+6 ;(startaddress+9 with sound effect support)

Note that the master volume command (DXY) also modifies this same location, so it will clash if you also change the volume manually.

STORE AUTHOR-INFO - Writes the "AUTHOR" string from songname editor to the location range (startaddress+$20 - startaddress+$3F). Also enables timing mark support. A timing mark is a mastervolume command (DXY) with parameter $10-$FF. This parameter will be copied into startaddress+$3F when the command is encountered in playback.

USE ZEROPAGE GHOSTREGS - Instead of writing to the SID, a memory range in the zeropage is used for holding the SID register data. This can then be copied in the main program to the SID, for example to enable the playroutine & music data to reside under the I/O area. Implies buffered writes. A reverse copy loop should be used after each call to the playroutine:

        LDX #$18
copy:   LDA ghostregs,x
        STA $D400,x
        DEX
        BPL copy

The copy loop can also be unrolled for more speed.

Note that when you use the alternative hardrestart method & playroutine (hard- restart attack parameter F) the copy loop should not be in reverse order but should be for each channel: wave, frequency, pulsewidth, and ADSR last.

If you are using both sound effect support and ghostregisters, there exists a possibility of sound errors in the case that a sound effect has finished, and the same channel starts a new pulse-waveform note without setting an initial pulsewidth value (for example, like in the beginning of Sanxion loader tune). This is because the ghostregisters are shared between music & sound effect playback, and the sound effect has already overwritten the previous pulse width.

DISABLE OPTIMIZATIONS - The relocator removes saved playroutine code based on what effects & commands the song uses, resulting in a smaller playroutine accordingly. If you encounter anomalies in the sound (such as ADSR bugs caused by unpredictable timing variation) you can try disabling the optimizations. Normally this is not necessary, but is included just in case.

FULL BUFFERING - in some cases, especially with multispeeds, the "standard" or per-channel buffering is not enough and will still produce ADSR errors. This enables a functionality similar to the ZP ghost regs, where the previous frame's SID data is copied to the SID at the beginning of the play call for maximum stability. Will use more rastertime and imply the same problems with sound effect playback as the ZP ghost regs, so use only when necessary.