
INSTRUCTIONS for JCH NewPlayer v14.G0


Typed by JCH, 18/5-1990 - updated again 29/11-1990.

These instructions will tell you exactly how to create instruments in the
editor. Said differently, it will enable you to make full use of all tables
you find inside the editor. However, it will not explain how to access the
editor itself as this is beyond the scope of these instructions. Note that
these instructions will be used as a "base" for future instructions typed for
updated player versions, as for example player v15 and v17. I therefore
advise you to always keep these instructions in a safe place, in case some of
these "later" instructions refers to these instructions. Right, let's get on
with it!

As you see when you study the key-guide, you enter and exit the 8-byte table
with the 'Z' key and play with the keyboard with 'F2' (while the commodore
key locks the keyboard), and you turn off the playmode with 'F4'. Right, now
that you've entered the 'Z' key table let me try to explain what does what to
clear up your mind.

    04      48      26      42      01      0C      04      07
    --      --      --      --      --      --      --      --
    A       B       C       D       E       F       G       H

I'll refer to the eight bytes using letters A-H.

Byte A & B are simply the ADSR and needs no introduction.

Byte C & D controls both Vibrato and Hard restart. You know what vibrato is,
but I don't think you know what 'hard restart' is but I'll get to this later,
first I'll show you how the bytes work. In the example you see 26 - 42. If
you split it up into nibbles (half-bytes!) you then get:

    2  -  Controls vibrato width, values 0-F.
    6  -  Controls vibrato trigger (delay), values 0-F.

    4  -  Controls vibrato speed, values 0-F.
    2  -  Controls hard restart timer, 0=off, min. 2, max. is gamespeed.

Hard restart. What is that precisely? Well, it's something all good hitech
players with respect for themselves has. Imagine, you have a note that is,
say, 7 frames long (you know, 1/50 sec. is a frame!) and you set a hard
restart time in the instrument it uses, to value 2. What happens when this
note is played then? Yes, when 5 of the 7 frames have been played, the LAST 2
FRAMES of the note will be cut completely in ADSR, in other words, $00 will
be stored into these registers in the SID-chip. The effect you get out of
this is precision and funky-like notes, cause the idea is not only to put in
some sort of a 'rest' between notes - no, the idea is based upon a BUG IN THE
SID-CHIP! If you have ever read the diary in "Zzap! 64" some time ago, with
Martin Walker coding a "Citadel" game, you might have encountered his quibble
with the ADSR in his music-player, which he wrote quite a lot about. He found
out, using an oscilloscope, that every 5-12'th note or so the ADSR wobbles
or "fails" a little bit, causing normal music-routines to, f.ex, take a noise
in the start of a note differently, as was the ADSR changed for a second.
Well, the hard restart method, with storing $00 in the ADSR registers
before the next note, makes sure that the ADSR on the next note never fails.
But only if you enter a hard restart value of minumum 2, because the
SID-chip needs at least 2 frames to make sure it won't fail! Also, in my
routine, the hard restart value must never exceed the game speed. If you
compose in speed 4, use values from 2-4 or 0 if you don't want hard restart
on an instrument (drums and the like). Notice that when using hard restart
cleverly you can make your intruments sound like they are stroke 'harder',
more tough... hence, the name 'hard restart'. To get the best effect you
should use ADSR values like 04 - 48 or 03 - 3A etc... if you have a decay
value on your ADSR along with a low sustain, your hard restart sounds will
sound real good. If you type a value in the hard restart timer higher than
the actual game speed your notes might 'disappear' or play out of synchro, so
keep beneath, or at the same level as the game speed. You can type '1' as a
timer too, but it won't work 100% - the notes won't get out of synchro
though.  Also, the first 4 bytes in the filter-table (accessed with the ';'
key) are reserved for defining - amongst other things - some hard restart
finetuning constants. But more about that later when I reach the filter-table
in these instructions. Just keep in mind that when using the filter-table,
ALWAYS start your filters from position $04! The first 4 bytes usually says
0F-00-09-01 and should stay so.

Byte E are split up into two nibbles too. The '01' you see controls two
widely different things: hi-freq mode and filter passband/on-off toggle.
Firstly the '0' you see can only state two conditions: 1 is 'hi-freq mode on'
and any other value is 'hi-freq off'. Hi-freq are used primary for drums.
Normally when you enter values in the Arpeggio-table (entered with 'L'), the
values added to the note refer to actual notes. This is fine when working
with chords etc, but the hertz table that defines the note values in the
music-player has it disadvantages when playing with drums - the higher the
note, the bigger the difference between hibytes in the SID-chip hertz
register is. At the highest octaves there are even up to $05-$10 values
between them (notes are made up by lo and hi bytes in a 192 byte long hertz
table containing 8 octaves). This is where the 'Hi freq mode' comes in handy,
just enter a '1' in the hi-nibble and the values in the arpeggio-table are
put DIRECTLY into the SID-chip hibyte register. Thus, you can get more
detailed drums, a kind of 'high resolution'-mode! But remember this, '1'
put's it on and any other value off (0 or 2-F). Okiedokie... the 2nd nibble,
the one that shows '1' in the example is simpler, it's a combined on - off
toggle for filtering while at the same time stating filter passband. So, a
'0' is "filter off" and any value from '1' to 'F' sets "filter on" AND puts
the chosen value into the hinibble of $D418 register, the one that sets the
passband of the filtering. '1' is mostly used, but try '2' for a change...
it's more "sharp", if I may say so. But I've added another feature into this
nibble too, which is extrememly rare used, as a matter of a fact I have only
used it once ever! If you set the value to '8' the filter is off but the
voice that uses this instrument will 'modulate' the other voice that USES
filter... in other words, it still activates the filter sweep pointer without
actually having filter on! A very rare used function... I might even remove
this soon!!

Byte F points to the filter-table. It can be any value from $00-$FF, but as
the table is divided into 4 bytes you should only point to it with
$00-$04-$08-$0C and so on. If the filtering is OFF nothing happens if you
point to this table, unless you put an '8' in the filternib (described
before). So, to give away a little trick of my own (actually it was invented
by SCARZIX, a good friend of mine that uses my editor too), I can tell you
that if the instrument is a chord and has filtering OFF anyway I usually put
a quick info-byte here to remind me of what chord this is. If it's a 0-3-7
chord, I write $37. The player won't use this when filtering is OFF anyway so
no harm is done by using it for this.

Byte G is similar to filter, it points to the pulsating table. Again $00-$FF
is allowed but only every fourth byte value should be used ($00-$04-$08
etc!). The trick with using it for 'reminders' can be used here too if you
don't use waveforms in the arpeggio table that uses puls (like $41 and $51,
and on new 64'ers, waveform $31, $61 and $71).

Byte H points to the arpeggio-table. Here all values from $00-$FF counts, be-
cause the two bytes you see in each step of the arpeggio-table is actually TWO
different tables, each 256 bytes long! (If you look through the memory with a
monitor you can verify this.) The reason for this is to reserve as much room
for complicated arpeggio instruments as possible. The puls and filter tables
both uses only 1 block, because they never get used up anyway. The highest
pointer I've been to here is $30 I think, where I've used over $80 in the ar-
peggio table! The only table that I have underestimated is the 8-byte table
containing the values I've just described. I've banged my head against it's
$1F roof (32!) many times, but never too seriously. DRAX has had his
complaints though, but that's because he always "props" his songs full of
different chords all the time.

Now that was the 8-byte table description - I hope you got all the details,
especially concerning the 'hard restart' thingy. If something remains unclear
go print the memo-text! Now, always keep in mind that these instructions are
exclusivly for NewPlayer v14.G0 only. Every player I've done follows the
rules more or less but there's always a byte here and there that means
something else in the other players. For example, 'hard restart' is only in
players 11, 13 and 14. Player 12 is a compromise-player taking approx. $12
scanlines, useful for huge demos containing 12734 sprites etc... The lowest
player my editor can take is NewPlayer v05.02! Player 05-09 are for demos
only, while player 10 and upwards can be used for games. Enough about
players for now! Let's get on with the instructions...


The Arpeggio table


This table is the one the last byte in the 'Z'-table points to. It is accessed
with the 'L', furthermore you can enter the start of pointer by pressing the
'G' key, to save time. The table is actually two tables, but my editor puts the
two tables up beside eachother for easy editing. The numbers to the left con-
tains note adds, and the endbyte $7F in the end, while the right numbers are
waveforms and a wrap pointer when ending an arpeggio. Let's have an example:

        3C: DF-81
        3D: 00-41
        3E: 03-41
        3F: 07-41
        40: 7F-3D

If the last byte in the 8-byte table says '3C', just enter the arpeggio-table
with 'L' and press 'G' to go to position $3C. Here you see these 5 steps in
my little example - well, you've almost found out most of it now, but anyway,
the left values is note adds. They're added to the actual notes in the seq
that uses the instrument with a pointer to this arpeggio block. The values
possible in left column is precisely:

        $00-$5F - note values, added to the note in the sequence.
        $80-$DF - note values taken directly from the hertz table in the
                  player. Neither notes, transposes nor a slide can change this
                  notestep in the arpeggio. So, the $DF in the example will al-
                  ways sound the same. The fact that even slide can't change
                  can, with a little thought, be used effectivily to copy the
                  old, famous, Rob Hubbard slide where parts of the slide stay
                  at the same level while something else slides...
        $7F     - This ends the arpeggio. When the player recognizes this byte
                  it'll load the byte beside the $7F (right column) and LOOP
                  immediatly to this arpeggio pointer. In the example, it will
                  wrap to $3D, where the $00-$41 is. So, the sample above will
                  sound like a 0-3-7 chord with a stuck noise in the start.

The right column can only be waveform values, until a $7F is put into the
left column, then the byte at the same level in this column will state the
wrap value.  Concerning the wrap-pointer: It's true you can use insert and
delete in the arpeggio-table with ease, using 'INST' and 'F6', but all wrap
values after the spot where you inserted/deleted must be adjusted after this.
On the other hand, when you exit the arpeggio-table you'll notice that the
8-byte table's pointers will be updated automatically! Great, but why won't
the values in the arpeggio table be adjusted automatically too? Because the
player v14 is the first player to feature direct pointer wrapping. All
previous players has indirect pointers, that is, f.ex the pointer value $3C
is $00 to the wrap pointer. So, in all other players the $3D wrap value would
have been $01 instead. The reason why I changed this into direct pointing in
v14 is because it is irritating when making long arpeggios, scrolling up to
the start and counting down in your head. In player v14, you can just look at
the pointer values before the colons and just use these numbers when
wrapping. Needless to say, I didn't think of this when coding my editor, but
I HAVE fixed this detail in a future version of my editor which however still
needs a little dusting off -  Until then, you must fix all wrap pointers in
the arpeggio table yourself...

* ADDENDUM 20/8-1995: In ED v3.04, the arpeggio pointers are all automatically
* adjusted whenever you insert or delete in this table - no worries! :)


The Pulsating table


Now we're moving onto two tables that works almost identical, the pulsate and
filter-sweep tables, starting with the puls table. Unlike the filter-table,
this one starts directly off from position $00 where the filter twin starts
at $04 because the first 4 bytes has been reserved. Anyway when you're
pointing to this table with byte 7 in the instrument you can access a very
complicated set of command bytes. Like in real hi-tech players, both puls and
filter can be step-programmed to give very weird and complicated sounds...
James, fetch me another example, please...

        08: 48 20 88 04
        0C: 48 20 4F 00

Here you see a two-step pulsating. Three of the bytes is easy to explain but
the real pain in the a** is byte 3, because of its different bit
functions...  Anyway let's have the first one, saying $48. This is split up
into two nibbles again, '4' and '8' and they simply set the widths of the
pulsating, the boundaries. In byte 4 you set the start puls - this byte is
actually upside down as the hinibble sets the hinibble of the lobyte puls
while the lonibble sets the hibyte which is actually only a nibble. Got that?
Ha, I didn't expect you did!  But let's try it this way: Inside the chip you
can set a puls up to $FFF in value. If you choose a puls at $4A0 you set byte
4 to $A4. See it now? You wont need the last nibble of the three digit puls
in start. So, the first nibble in byte 4 is lo and last nibble is hi. Notice
that the widths in byte 1 only looks at the 'hi' part of byte 4, the last
nibble. Let's say you want to start at a puls at $580 and travel between $200
and $A00, Then set byte 1 and 4 to:

        XX: 2A XX XX 85    - I hope you see it now!

Internally the music-player walks in one direction until it meets a width
check and then travels between the checks, so you can set the startpuls
outside the widths to start your puls a little differently. The speed of the
travelling is set in byte 2. Any speed between $00 and $FF is possible, $20
is "normal".

Now let's look closer at byte 3... This byte works exactly the same in the
filter-table, so when you know how this works you can step-program the
filtersweeps too. This byte allows you to specify three things: 1. How many
frames will this puls-set run, 2. Shall I read byte 4 or just go on from last
sets last values, and 3. Is this the last set, thus shall I run here forever.

Here's how the byte looks like in bits:

        1 1 0 0 0 0 0 0
        ^ ^ -----------=frames the set should last.
         
         on=stay at the set forever.
        
       on=read and set the startpuls.

Maximum frames a set can last before an action has to be taken is $3F. So
what you do is: 1. Define startpuls and widths, along with speed in byte 4, 1
and 2.  2. Choose lenght of set in frames (1/50th of a second is 1 frame).
Example: $08 frames chosen. 3. Choose to read byte 4, because this is the
first set, set bit number 7 (add with $80). Result: $88... 4. Set bit 6 if
you want to stay at this set forever (add with $40). If added, it would be
$C8, but it is never wise to use only 1 set unless your instrument is always
staccato (short, may be used in funk!) because then your instrument restarts
in puls when the frame counter resets. In other words, if you plan a puls
like this: 48 20 FF 04 (must start at $400 and travel between $400 and $800
at speed 20, and I want it to read byte 4 and just go on forever) then notice
that the highest frame here is $3F (because $3F + $80 + $40 is $FF!) and when
that time expires the pulsstart will be read again. Now that wouldn't sound
professional right? So here is what I would do instead:

        XX: 48 20 88 04
        XX: 48 20 4F 00

But what happens now? I put it into two steps, and this one will never
re-read the puls once started. You see, byte 3 in the first set READS byte 4
and runs for 8 frames - but bit 6 ($40) wasn't set, so when 8 frames has gone
the next set will be activated. Here byte 3 says $4F, which is "stay here
forever (bit 6 or $40) but don't read byte 4 (bit 7 is not set - $80!)" and
the set will therefore carry on using the values it had when it left the
previous set.

When you have experimented a lot with the powers of step-programming using
the  3rd byte you can make your steps as long as you wish, the 256 byte limit
is much too big for you to fill out, I garuantee that! Hey, try out the
following step program, emulating Maniacs of Noise's puls which runs in their
basses:

        00: 3D A0 82 03
        04: 3D 80 02 00
        08: 3D 60 02 00
        0C: 3D 40 4F 00

Step 00: Read byte 4 saying startpuls $300, travel between $300 and $D00 at a
speed of $A0 for '2' frames, then take the next set.  Step 04: Travel between
$300 and $D00 for '2' frames at speed $80, then take the next set.  Step 08:
Travel between $300 and $D00 for '2' frames at speed $60, then take the next
set.  Step 0C: Travel between $300 and $D00 for 'F' frames at speed $40, then
reloop this last set again. Without reading byte 4, it seems as it runs here
forever, but you know that is only until a new note is stroke in the
sequence.

Take this puls, put a good deep filtering on it and you have a good M.O.N.
like bass - well at least I think so. OK, I think this should do it for the
pulsating.


The Filter-sweep table


Where the pulsating table was the middle one activated with the ':' key, you
can reach the filter-sweep table with the ';' key. Okay, let's get into
details with this table too.

To begin with, let's put away the first 4 (reserved) bytes, I'll get to them
after discussing the filtering effects... This table is pointed at from the
6th byte in the 'Z'-table, and works much like the pulsating one. Concerning
the 3rd byte (the step controller), it's EXACTLY the same, so I won't discuss
this one at all. Isn't it just great to be able to step-program it? I LOVE
it!

        04: 2A 03 88 8F
        08: 2A 00 4F 8F

Let's redo byte 1, 2 and 4 here. Byte 1 is again widths, much like pulsating,
but this time the 4th byte is much different. I DOES set start-filtering, but
it sets the "resonance" too - so, you can step-program "resonance" in my
player as well! (Maybe this is the only player which does that?). Okay, back to
business again! Byte 4 here says $8F. Once again split it up in two - the '8'
is the hi-nibble of the filter frequency, so it's actually $80. The reason
why I don't bother too much about the lo-nibble is because there is so much
difference between 64's filtering, so the difference would be insignificant
anyway! The 2nd nibble in the byte is 'F', which is put directly into $D417's
hi-nibble, which controls the resonance of the filtering. I must admit that
I've almost NEVER used any other value than 'F' as resonance. Again the
difference in filtering on the 64's also shows in the resonance, on some the
different values here gives no apparant difference, while on others (mostly
new, 64 C) there is a huge difference (the bass gets "poppy" with resonance
'F'). Never mind, as you see in the above example the start filter-freq at
$80 swings between $20 and $A0 frequencies at speed 3 for '8' frames, and
then goes to the next set without reading byte 4 - and since the speed here
is '00', the filter will stop where the music-routine had it last. Don't
bother about values in byte 4 in sets where the 4th byte won't be read. If
the 4th byte is unread, the byte will be totally ignored so you can use this
as a 'reminder' if you want, much like you could with 'chords in
filterpointers' before.

To end it all with filter-sweeps, take a look at this cool filter:

        04: 18 0D 84 8F
        08: 00 00 4F 00

It gives a typical "DJAOUUUUUU" filter, very useful. Notice that byte 1 in
set 2 is '00', that's because the speed (byte 2) is '00' too, so there is no
point in having to set the widths as well!

Now, as promised, I will talk about the 4 reserved bytes in the
filter-table's position $00. These four bytes mostly looks like this:

        00: 0F 00 09 01

And as you might guess these bytes can be controlled from my packer whenever
the tune have been packed. From player to player I can set 'flags' here after
packing to change conditions in the player. F.ex, in player v12, the
compromise like player taking approx $12 scanlines, you work in the editor
with a rastertime taking 4 characters - then after packing, a change in
byte 4 in the packer's control-bytes will put the rastertime down to the
$12 scanlines. This is because the player skips a 'frame' here and there in
the player to reduce the rastertime, but if that was done in the editor it
would sound horrible because here the notes are divided into a lot of small
durationsteps, very logically.

Yep! The first two bytes in player v14's 4 bytes are reserved for the hard re-
start and is just the ADSR in two different places in the players program.
You  should always keep these values as $0F - $00, otherwise your sounds
might 'fall out' or just trigger on badly.

The last two bytes are reserved for 'first-frame' choices. Normally, you
should set these two bytes to $09 - $01. But what do I mean 'first frame' !?
Yes, here you have to know a little bit of how music-players work. In most
players, you have a solid rastertime that's always the same and then there's
the flips upon it. The solid time is what I call the 'real-time routine' as
this is where the vibrato, pulsating, filtering and arpeggio keeps updated
all the time. And as you might have guessed by now the 'flips' is where it
sets the instruments and reads the note-tables. Most players however uses an
old trick to get the down the raster-time, you simply read the note-tables
and set the instruments in the very first frame of EVERY note AND SKIP THE
REAL-TIME ROUTINES! 99% of all the players you hear on the 64 uses this trick
as you can't hear the 'first frame' beeing skipped anyway. The result is that
the 'flips' get's "swallowed" by the solid raster-time, the real-time
routines, and that is why some routines looks so 'controlled'. The trick with
skipping the first frame is what you can control in byte 3 and 4, simply
set byte 4 to $00 if you DON'T want to skip the first frame (then you should
ignore byte 3), this takes maximum rastertime! If you do want to skip it
(both Link, Drax and I do!) then set it to $01 (byte 4) and now you have
control over the WAVEFORM you want to put into the first frame where the
'real-time' routines are skipped. As you see, waveform $09 is what is normal,
as this sets the testbit in the SID-chip, a function that resets the
noise-waveform if it should ever lock up. Have you ever encountered that? If
you ever do, then try running a Drax soundtrack and it'll get back again!
Anyway now you might set it to $09 $01 and then to $XX $00 and look at the
rastertimes and then say: But the difference is marginal! Well, you're
quite right. The 4.5 chars rastertime player v14 takes is too much I think,
but necessary because of the hard restart coding in the music-player. I won't
tell you all the technical stuff around this problem, only that I found a
solution to this problem in later players, especially v17. Until then, all I
want to say is that if you want to get the rastertime down to 4 chars max,
then only use hard restart in 1 of the voices. f.ex on the lead and then
bass and drums without it. If you put the same hard restart timer (ex. $2) on
all three voices at the same time the raster-time might gopple $2A scanlines
(Compared with the Hawkeye routine it is still very little though as THAT
is BIIIG!). Drax always uses hard restart fully because he loves it,
(actually it was him who made me code it) and that is why his tunes in player
v14 takes so much rastertime.

Well as your eyes are probably dripping of pain now I better stop this
text now - I really hope I explained everything so that you understood it
100%. Remember, you can always print out the memo-text and have that ready
at your side when experimenting.

Jens-Christian Huus.

* ADDENDUM 20/8-1995: Later I wrote an extra file concerning the slide commands
* in the slide-table. Be sure you read this textfile as well - it has been
* included in this package as "SLD-V14.TXT".

