Music Box is an advanced musicsystem, soundeffect system and music editor for the Nintendo GameBoy Color, Nintendo GameBoy, Nintendo GameBoy Pocket, Nintendo Super GameBoy, Nintendo Super GameBoy 2, Nintendo GameBoy EL Blacklight, Nintendo Wide Boy and all the compatibles and software and hardware emulators. Hereafter referred as the GameBoy family.

It is balanced on the middle. Music Box isn't that simple system as most of the musicsystems used in most of the games available on this system (needs almost no CPU time), but also isn't the most superior one crunching out absolutely everything from the GameBoy family soundchip. We can do a less advanced system and a really superior system too, however a too simple system sounds bad and a really superior system needs too much CPU time and you cannot make really advanced games with it. So we think it is a quite good (able to play great music with small CPU usage) system, great for games and demos, but if you think you need a more special one, just contact us and we will make it for you.

Music Box is a bit strange in a way. The editor is also running on the destination system what isn't a common thing on the consoles. We have tried out many-many GameBoy software emulators and tested a lot the best ones, but none of them sounds similiar to the real GameBoy family soundchip. Maybe the emulator programmers thought the accurate sound isn't that important or nobody was able to make a proper soundchip emulator to the software emulators. That's why we thought we better let the composers work on the real destination machine and hear totally the same what the gamers will hear. This decision made the composer's life a bit less comfortable, you know you have to edit music on that small and limited display and edit the music with those small and limited input buttons, but it is still better than a bad soundchip emulator or what most of the official developers do, to compose the music with a midi system and type everything into the musicplayer sourcecode by hand and pray it will sound good enough or at least not terrible. So sorry for this miscomfort, we tried to design the editor as easy to use as it is possible and I think we succeeded with it.

So with the Music Box editor running on the real GameBoy family you can edit your music on the real system hearing exactly the same the gamer will hear. Also it is funny to compose music on this small gaming system, even you can modify your music on the bus when you travel to the office or something. It even can be fun, there are many commercial music composer games and disc jockey games out there on the consoles too (just to mention Music from Codemasters on the Sony PlayStation, but there are many of them on the GameBoy family too in Japan). If your company want to publish something like that, we can make this system even more userfriendly and cute and easy to use even for the kids and functions to share musics and other things with the serial and/or infrared port or even share on the internet (with the sooncoming cell phone connection). We are open for everything, contact us and we can talk about your needs and ideas. Maybe even your kids will like this tool when you are not composing for you game company on it. :)

And of course if you want, you can use this system with emulators too, however we REALLY DON'T recommend it. None of them has a 100% soundchip emulator (even the best ones are less accurate than 50% I think) and many of them are even more crippled, has no sound at all or can't save the music, etc. But anyway it is another (really lame) possibility if you don't have a real machine or flash card, EPROM emulator or other.

Music Box has another interesting feature. However we first wanted to make it only for ourselves and because this it is well coded and well designed but for a commercial project we can make million times better things. Anyway we thought it would be fun to use the GameBoy Color extra possibilities like the extra colors on the GameBoy Color and also keep it backwards compatible with the old GameBoy family. So this is a socalled Dual-Mode (Compatible) GameBoy Color and GameBoy family program. Just for fun.

Well, I think we have to share some quick statistics too if anybody is interested. I think the following infos are interesting stats:

CPU time needed by the player: around 2% depends on the system and CPU speed mode and instrument and music complexity and channel usage of course. Nobody can give exact numbers of course, but you can see from this, Music Box doesn't need too much CPU time and you can use it in really advanced "CPU killer" games too. We can reduce the CPU usage even more on request for special games.

The player can be called in every frame as most of the players to update the music, but multispeed is also possible with this system, you can call it two times in a frame (double speed) or four times in a frame (quattro speed) too to make the sound quality even better and the timings more accurate. Of course it is also possible to call the player even more times a frame or hook it to the timer interrupt. Contact us for special versions.

Minimum music size: 1152 bytes (a bit more than 1 kilobyte). Of course some advanced composers can make music in this small size too, but the average music is larger.

Maximum music size: 8192 bytes (8 kilobytes). Of course nobody will make this large music only when really long music is needed. The average music will be far smaller. And of course with coding tricks even larger musics can be composed, but we though it will be far more than enough. However if you need special modifications, just tell us.

Longest music playing time: around 4 and half hours, at least theorically. Of course with larger music (if you need some special modifications) longer music can be done. Anyway we think it is FAR more than enough.

As you can see in the What is Music Box section our editor is running on the real GameBoy Color and GameBoy family. This system is mainly designed for pro official GameBoy Color and GameBoy family developers and pro hobby GameBoy Color and GameBoy family programmers and composers. And if you are one of these you sure have the hardware and the knowledge to start the system. And if you are not one of these check out the Support, Frequently Asked Questions and How to Buy Music Box sections. We cannot teach everybody to read the ABC or something. If you are a beginner and have really beginner questions, first read all the GameBoy Color and GameBoy family FAQs, chat with your team members and fellow composers and programmers, try to figure out things on your own (works in most of the cases, we learned EVERYTHING this way) and ask stupid beginner questions from us only when nobody else helps you. But as you've got this package for free, we cannot give support with it, only the customers get support. Of course I'll answer all the important questions, that's why we have a Frequently Asked Questions section, but I'll answer stupid questions like "what is a flash card" or "what is RGBDS" only to the customers who will get ABSOLUTELY full support. We are a small team and we are really poor so we don't have time to answer stupid questions for free, sorry. (Sounds a bit egoistic but sure you earn monthly more than we both in a whole year.)

After reading the above lines you sure know how to start the editor. You can use it easily with emulators, however WE REALLY DON'T recommend it as I stated before in the What is Music Box section and none of the emulators will give the same sound quality as the real soundchip and many of the emulators will not make it possible to use the editor perfectly (can't save the music, no sound emulation at all, etc). So use it with emulators on your own risk really and if it is possible don't use them for composing. We REALLY recommend to use Music Box on the real machine. You can do it many ways and as you are a professional you sure know how. Anyway some hints for the beginners. Music Box can be flashed to flash cards (there are more and more available for the hobby GameBoy developers too, just ask some or the official ones available from Nintendo for the licensed developers). Also if you are a licensed developer (or a hardware guru) you can use EPROM emulators too officially available from Intelligent Systems through Nintendo (called the hardware debugger) or made your own. And even if you are a hardware guru you can make your own EPROM or EEPROM card with Music Box on it, you decide. Some hints about the card what you need (flash or anything other, doesn't matter). The Music Box ROM image is really small as you can see. It is only 32 kilobytes small and therefore using only the two basic ROM pages, doesn't need any Memory Bank Controllers (MBCs) at all. So it can be used with any cards with any MBC chips inside, MBC1, MBC2, MBC3, MBC5, HuC-1, HuC-3, etc and with cards with no MBC chips at all. Even you can make at home a custom EPROM card without MBC chip inside for the editor if you want. However it needs some RAM too and battery to backup the RAM otherwise your music will be lost. Only 8 kilobytes of RAM needed on the card with battery, keep this in mind if you make your own card or use an official or unofficial flash card or EPROM emulator, I'm not sure all of them support RAM in this size with battery backup. And also keep in mind: when your battery dies, your music will be lost. (Don't use weak battery and save your work to the PC often.)

And also if it is possible use the editor exactly on the same machine your game is targeted for. As I stated before, don't use software emulators. But also I think neither unofficial hardware emulators aren't good enough for this. (Like the one available for the Sony PlayStation, however I never tested it.) And neither the official hardware emulators like Nintendo Super GameBoy and Nintendo Super GameBoy 2. The clock crystal is running on a bit different frequency than on the handheld machines. This difference cause some small non-noticeable problems, even the perfect note frequencies are different on those systems. But as I stated before this difference is really-really small, non-noticeable. However it is the best to edit music EXACTLY on the target system to hear EXACTLY the same the gamer will hear. I don't know if the Nintendo Wide Boy has similiar problem or not. I'm sure it would be better to edit the music on the TV screen, but I really recommend to use only the handheld machines like Nintendo GameBoy Color, Nintendo GameBoy, Nintendo GameBoy Pocket and Nintendo GameBoy EL Blacklight.

First you have to read the previous How to Start the Editor section. And that will answer most of your questions.

If you are using a software emulator which support the battery backed SRAM then the emulator will simply save your music in the MUSICBOX.SAV file or something similiar. If not, try another emulator. However as I stated before we REALLY DON'T recommend using an emulator.

If you are using a flash card or EPROM emulator or EPROM card or anything else you are sure familiar with its use. You sure know how to upload programs to it and surely know how to manage the SRAM on it. If not, ask somebody in the office or elsewhere, again read the previous How to Start the Editor section. You can use many-many different systems, your EEPROM programmer or EPROM emulator or other system can read/write the SRAM too for sure. If not, try another one compatible with your hardware. Your hardware manufacturer surely can give you the software to do this or try out some universal ones.

You will get a 8 kilobytes large file in these cases. If your software will make a larger file, you sure can crop your file with a tool to the first 8 kilobytes. And this 8 kilobytes large file you can use simply with the player to play it in your games or play the soundeffects in it. Of course if your music is smaller and you know what you are doing, you simply can crop the file to a smaller size, but only do it if you really know what you are doing. I'm lazy to write a section about this and I think the 8 kilobytes music size isn't too large if you can't crop it yourself. However if you are a customer, we will crop all your musics for free to the smallest size. And if we get enough support (some companies and rich hobby programmers will buy the system and we will get some donations) we plan additional tools, for example a musicfile optimizer tool to do this job for you or even optimize the music to an even smaller size.

When you start the Music Box editor, the following intro screen will show up on the GameBoy Color as pictured (in dark blue) and on the other GameBoys with the standard four yellow colors.

You can skip this small introscreen by pressing any button on the controller. After this the following screen will show up, what is the Main Tracker Window.

At least without the red marks of course. As the GameBoy Color and GameBoy family screen is really small and limited we weren't able to make online helps and descriptions about the menus, that's why I'm mainly writing this manual and showing these marked pictures.

I marked with the number 1 the pattern order editor. In this area you can edit the pattern orders, which pattern follows which one. Just like in the usual tracker programs. However you can see four columns here instead the usual one column. This is because in Music Box every channel has its own pattern order and the patterns only have one column, not four ones or more as usual. With this the music is smaller in size, can be displayed more easily on the small screen and more and more variable for the composer. You can use any pattern in any column. The first column is the pattern order of the first channel, the second one is the pattern order of the second channel, the third one is the pattern order of the third channel and the fourth one is the pattern order of the fourth channel. You can move the cursor between the four columns easily with the direction buttons. And at the top and bottom of the screen you can scroll the whole pattern order as one block up and down. (Makes it possible to use larger pattern orders than the one can be displayed.) At the moment you can use 56 patterns in the pattern order, $00 is the first one and $37 is the last possible. We think this is enough, but we can expand it on request. Out of the pattern numbers you can use two global commands in the first column. $fe is the stop command, when it is used, the music will totally stop and the MBStop function will be executed. After this MBInit is needed to restart the music. And $ff is the restart command. When the $ff command is executed the music will restart at the pattern position was given in the B register when MBInit function was called. (Usually this is the same $00 as the one in the A register usually, but this makes the music even more flexible and even the Digital Illusions Pinball style changing submusic effect can be reached with this.) Don't forget, these commands can be used in the first column and when the first command is reached, $fe or $ff it is executed and will be active for all the four pattern orders, because these are global commands.

When you move the cursor in the pattern order editor, the left number in the upper right corner marked with 4 will change. This hexadecimal number shows the actual row number where the cursor is in the pattern order editor. Not on the screen, but in the whole pattern order table. $00 is the first row and $3f is the last one, so 64 rows of pattern orders can be used at the moment. We think it is enough even for multiple musics, but we can expand this on request.

When you move the cursor in the pattern order editor, also the actual number under the cursor will be showed in the upper right corner. The number on the right marked with 5. This is the number of the actual pattern can be edited. To edit a pattern, first you have to move the cursor to the number of the pattern in the pattern order editor (or input it if it is not already there) and the pattern number will be showed in the area marked with 5.

Also at the same time the content of the pattern will be showed in the pattern editor window too. This is the area marked with 2 and 3.

The A button will switch these two windows. When you are in the pattern order editor 1 on a legal pattern (between $00 and $37, not a command or illegal pattern) you can move to the pattern editor 2 and 3 by pressing the A button. And the window will be scrolled to the last used position and the cursor also will be placed to the last used position. And by pressing the A button again you can move back to the pattern order editor 1 to the same screen and cursor position where you were.

On the pattern editor screen you can easily navigate too with the direction buttons. Up and down and left and right between the note column 2 and the instrument column 3. When you are in the pattern editor window 2 and 3 the left number in the top right corner marked with 4 will have a new meaning. In this window it will show you the actual row in the pattern editor. Of course as in the case of the usual trackers and in the case of the pattern order editor 1 you can use 64 rows between $00 and $3f. The other number in the right corner 5 will have the same function, will show the number of the actual pattern what is in the pattern editor at the moment.

In both windows, in the pattern order editor window 1 and the pattern editor window 2 and 3 you can scroll the screen back from the first $00 row too to the last $3f row. As the GameBoy family controller is really limited, we had no buttons for the page up/page down/home/end/etc. This small wraparound can speed up the navigation radically.

Now about the input.

When you press the B button in the pattern order editor, you can input numbers. A small input window will show up as shown above marked with 1 and 2. We call the one on the left marked with 1 the input window and the one on the right marked with 2 the small input window. You can cancel immediately your input and do nothing when you press the A button when the input window is active. And you can get back to the main editor. Navigating in the input window 1 is a bit tricky. We wanted a better input but were lazy to do it and we think this is also really useful only needs some practice. You can move the cursor up and down as usual with the direction buttons. At the upper left and lower right corners of the input window 1 you can scroll the whole screen by one position. You can find the wraparound for the faster navigation here too. And when you press the direction button left or right the cursor will not move, but the screen will move by one column to the left or right and a new column will come in and of course the wraparound works here too. When you press the B button, the value below the cursor will be entered in the editor to the position where the cursor was when you have pressed the B input button. (Easier as it sounds.)

You can input all the hexadecimal values, however in the pattern order editor use only numbers between $00 and $37 as these are the valid pattern numbers and also the $fe and $ff commands in the first column.

When you are in the pattern editor's second instrument row and you press the B input button, the same input window will come in. You can input numbers on the same way, however number $00 will be showed as "--" because that is the empty instrument command. And use only numbers between $00 (the empty one), $01 (the first instrument) and $20 (the last one). The other instruments are illegal. Only 32 instruments are used between $01 and $20. However we can expand it on request of course.

When you are in the input window 1 you can move to the small input window 2 too by pressing the SELECT. This small input window is even more crippled, we were lazy to make it more comfortable and we think nobody will use this menu too many times. In this menu you can move the cursor up and down with the direction buttons and there are only two menus, the INS and DEL. When you press the B button on a "---" line, you can get back to the input window 1 and when you press the B button on the INS, a zero ($00, "--" or "---" depends on the window) will be inserted and everything will be moved down in the column and when you press the B button on the DEL, the actual value below the cursor will be deleted and the whole column will be moved up.

The screen above as you guessed right is the input window of the note column in the pattern editor marked with 1. It is nothing special, works totally the same way as the other input window and the small input window also works the same way. So you can use it and navigate in it totally the same way as in the other input menu, only this time the valid notes can be chosen. "---" is the empty command and no note will be played, C-3 is the first note available on the GameBoy family soundchip and B-8 is the last one, so you can input all the notes and halfnotes between these.

I think this is everything interesting about the Main Tracker Window.

When you press SELECT on the Main Tracker Window you will switch to the Instrument Editor Window. And you can switch back by pressing the SELECT again. You can find the Instrument Editor Window below.

I marked the menu we call the ABC menu with 1. Because we call the first byte A, the second one B, the third one C, the fourth one D and the fifth one E. These bytes have different meanings on different channels. These are the main instrument description bytes, every row descibes an instrument. And there are 32 rows between $01 and $20. You can move in this menu as usual with the direction buttons and scroll the wraparound screen up and down. The left byte in the upper right corner marked with 5 will show the cursor position row and at the same time the active instrument number to edit. As I mentioned before these bytes have different meanings for every channel. Long description follows here.

Channel 1:

A - register NR10 ($ff10)

              Sound Mode 1 register, Sweep register (R/W)

              Bit 6-4 - Sweep Time
              Bit 3   - Sweep Increase/Decrease
                         0: Addition    (frequency increases)
                         1: Subtraction (frequency decreases)
              Bit 2-0 - Number of sweep shift (n: 0-7)

              Sweep Time: 000: sweep off - no freq change
                          001: 7.8 ms  (1/128Hz)
                          010: 15.6 ms (2/128Hz)
                          011: 23.4 ms (3/128Hz)
                          100: 31.3 ms (4/128Hz)
                          101: 39.1 ms (5/128Hz)
                          110: 46.9 ms (6/128Hz)
                          111: 54.7 ms (7/128Hz)

              The change of frequency (NR13,NR14) at each shift
              is calculated by the following formula where
              X(0) is initial freq & X(t-1) is last freq:

               X(t) = X(t-1) +/- X(t-1)/2^n

              (from the Pan documentation, refer to your official docs for
              better infos)

B - register NR11 ($ff11)

              Sound Mode 1 register, Sound length/Wave pattern duty (R/W)

              Only Bits 7-6 can be read.

              Bit 7-6 - Wave Pattern Duty
              Bit 5-0 - Sound length data (t1: 0-63)

              Wave Duty: 00: 12.5% ( _--------_--------_-------- )
                         01: 25%   ( __-------__-------__------- )
                         10: 50%   ( ____-----____-----____----- ) (def)
                         11: 75%   ( ______---______---______--- )

              Sound Length = (64-t1)*(1/256) seconds

              (from the Pan documentation, refer to your official docs for
              better infos)

C - register NR12 ($ff12)

              Sound Mode 1 register, Envelope (R/W)

              Bit 7-4 - Initial volume of envelope
              Bit 3 -   Envelope UP/DOWN
                         0: Attenuate
                         1: Amplify
              Bit 2-0 - Number of envelope sweep (n: 0-7)
                        (If zero, stop envelope operation.)

              Initial volume of envelope is from 0 to $F.
              Zero being no sound.

              Length of 1 step = n*(1/64) seconds

              (from the Pan documentation, refer to your official docs for
              better infos)

D - counter/consecutive selection bit (bit 6 of NR14 ($ff14))

              Counter/consecutive selection bit

              Bit 7   - Unused
              Bit 6   - Counter/consecutive selection
              Bit 5-0 - Unused

              Counter/consecutive Selection
               0 = Regardless of the length data in NR11
                   sound can be produced consecutively.
               1 = Sound is generated during the time period
                   set by the length data in NR11. After this
                   period the sound 1 ON flag (bit 0 of NR52)
                   is reset.

              (from the Pan documentation, refer to your official docs for
              better infos)

E - arpeggio pointer

              The hexadecimal number stored here will point to a position
              in the arpeggio table and from that position the arpeggio
              will be used for this channel for this instrument.

Channel 2:

A - unused (can be anything, ignored)

B - register NR21 ($ff16)

              Sound Mode 2 register, Sound Length; Wave Pattern Duty (R/W)

              Only bits 7-6 can be read.

              Bit 7-6 - Wave pattern duty
              Bit 5-0 - Sound length data (t1: 0-63)

              Wave Duty: 00: 12.5% ( _--------_--------_-------- )
                         01: 25%   ( __-------__-------__------- )
                         10: 50%   ( ____-----____-----____----- ) (def)
                         11: 75%   ( ______---______---______--- )

              Sound Length = (64-t1)*(1/256) seconds

              (from the Pan documentation, refer to your official docs for
              better infos)

C - register NR22 ($ff17)

              Sound Mode 2 register, envelope (R/W)

              Bit 7-4 - Initial volume of envelope
              Bit 3 -   Envelope UP/DOWN
                         0: Attenuate
                         1: Amplify
              Bit 2-0 - Number of envelope sweep (n: 0-7)
                        (If zero, stop envelope operation.)

              Initial volume of envelope is from 0 to $F.
              Zero being no sound.

              Length of 1 step = n*(1/64) seconds

              (from the Pan documentation, refer to your official docs for
              better infos)

D - counter/consecutive selection bit (bit 6 of NR24 ($ff19))

              Counter/consecutive selection bit

              Bit 7   - Unused
              Bit 6   - Counter/consecutive selection
              Bit 5-0 - Unused

              Counter/consecutive Selection
               0 = Regardless of the length data in NR21
                   sound can be produced consecutively.
               1 = Sound is generated during the time period
                   set by the length data in NR21. After this
                   period the sound 2 ON flag (bit 1 of NR52)
                   is reset.

              (from the Pan documentation, refer to your official docs for
              better infos)

E - arpeggio pointer

              The hexadecimal number stored here will point to a position
              in the arpeggio table and from that position the arpeggio
              will be used for this channel for this instrument.

Channel 3:

A - waveform pointer

              The hexadecimal number stored here will point to a waveform
              in the waveform table and the waveform will be uploaded to
              the channel 3 waveform memory. As the waveform memory is 16
              bytes (32 nibbles) large every waveform has this fixed size.
              $00 is the first waveform in the table from $00 to $0f, $01
              is the second one from $10 to $1f and so on. Only 15
              waveforms can be used from $00 to $0e because the size limit
              and because this is just a final bonus in the player and
              editor. We think this is enough, not too many waveforms are
              needed, however we can expand this limit on request. Also the
              command $ff can be used too what is the channel 3 mute
              command. (NR30 ($ff1a) bit 7 = 0)

B - register NR31 ($ff1b)

              Sound Mode 3 register, sound length (R/W)

              Bit 7-0 - Sound length (t1: 0 - 255)

              Sound Length = (256-t1)*(1/2) seconds

              (from the Pan documentation, refer to your official docs for
              better infos)

C - register NR31 ($ff1c)

              Sound Mode 3 register, Select output level (R/W)

              Only bits 6-5 can be read

              Bit 6-5 - Select output level
                        00: Mute
                        01: Produce Wave Pattern RAM Data as it is
                            (4 bit length)
                        10: Produce Wave Pattern RAM data shifted once
                            to the RIGHT (1/2)  (4 bit length)
                        11: Produce Wave Pattern RAM data shifted twice
                            to the RIGHT (1/4)  (4 bit length)

              (from the Pan documentation, refer to your official docs for
              better infos)

D - counter/consecutive selection bit (bit 6 of NR34 ($ff1e))

              Counter/consecutive Selection
               0 = Regardless of the length data in NR31
                   sound can be produced consecutively.
               1 = Sound is generated during the time period
                   set by the length data in NR31. After this
                   period the sound 3 ON flag (bit 2 of NR52)
                   is reset.

              (from the Pan documentation, refer to your official docs for
              better infos)

E - arpeggio pointer

              The hexadecimal number stored here will point to a position
              in the arpeggio table and from that position the arpeggio
              will be used for this channel for this instrument.

Channel 4:

A - register NR43 ($ff22)

              Sound Mode 4 register, polynomial counter (R/W)

              Bit 7-4 - Selection of the shift clock frequency of the
                        polynomial counter
              Bit 3   - Selection of the polynomial counter's step
              Bit 2-0 - Selection of the dividing ratio of frequencies

              Selection of the dividing ratio of frequencies:
              000: f * 1/2^3 * 2
              001: f * 1/2^3 * 1
              010: f * 1/2^3 * 1/2
              011: f * 1/2^3 * 1/3
              100: f * 1/2^3 * 1/4
              101: f * 1/2^3 * 1/5
              110: f * 1/2^3 * 1/6
              111: f * 1/2^3 * 1/7           f = 4.194304 Mhz

              Selection of the polynomial counter step:
              0: 15 steps
              1: 7 steps

              Selection of the shift clock frequency of the polynomial
              counter:

              0000: dividing ratio of frequencies * 1/2
              0001: dividing ratio of frequencies * 1/2^2
              0010: dividing ratio of frequencies * 1/2^3
              0011: dividing ratio of frequencies * 1/2^4
                    :                          :
                    :                          :
                    :                          :
              0101: dividing ratio of frequencies * 1/2^14
              1110: prohibited code
              1111: prohibited code

              (from the Pan documentation, refer to your official docs for
              better infos)

B - register NR41 ($ff20)

              Sound Mode 4 register, sound length (R/W)

              Bit 5-0 - Sound length data (t1: 0-63)

              Sound Length = (64-t1)*(1/256) seconds

              (from the Pan documentation, refer to your official docs for
              better infos)

C - register NR42 ($ff21)

              Sound Mode 4 register, envelope (R/W)

              Bit 7-4 - Initial volume of envelope
              Bit 3 -   Envelope UP/DOWN
                         0: Attenuate
                         1: Amplify
              Bit 2-0 - Number of envelope sweep (n: 0-7)
                        (If zero, stop envelope operation.)

              Initial volume of envelope is from 0 to $F.
              Zero being no sound.

              Length of 1 step = n*(1/64) seconds

              (from the Pan documentation, refer to your official docs for
              better infos)

D - counter/consecutive selection bit (bit 6 of NR44 ($ff23))

              Counter/consecutive Selection
               0 = Regardless of the length data in NR41
                   sound can be produced consecutively.
               1 = Sound is generated during the time period
                   set by the length data in NR41. After this
                   period the sound 4 ON flag (bit 3 of NR52)
                   is reset.

              (from the Pan documentation, refer to your official docs for
              better infos)

E - unused (can be anything, ignored)

Well, if you are a composer you have to learn really the above lines to fill the ABC window 1 with the best instruments. You know, most of the FM, SID and similiar soundchip composers are musicprogrammers at the same time. I just copy/pasted these lines quickly from the Pan documentation (Recommended Literature), I think these register descriptions are correct, however as I remember there were some minor register naming problems in some versions of this documentation, so check out your other docs too if you have some. However once you have created some great sounding instruments (what is not that difficult in a few bytes, in my example, Chiphop I just tried out some random numbers and it still sounds quite good) you can reuse them in you other musics.

Also some small tips you can find in the Tips section too. As you can see in the musicfile, in the editor and in the memory the different instruments look the same and use the same 5 bytes, etc. But when you create an instrument for the channel 1 it will surely sound really bad on channel 4 or not sound at all, but you can be sure it will not sound good or similiar to the channel 1. So it is ONLY your choise which instruments you are using on which channels. However you can set up some rules for yourself. For example to use instruments $01-$08 for channel 1 instruments (and use these only in the patterns you are playing in the first pattern order column, channel 1), use instruments $09-$10 for channel 2 instruments, use instruments $11-18 for channel 3 instruments and use instruments $19-$20 for channel 4 instruments or something. And when you see you need more instruments on a channel and less on another, you can change the rules a little bit, etc. It is easy and we think it is better to let you choose these than lock instruments to different channels. Another good tip is to leave the first instrument totally empty and that will be an empty instrument on all channels wherever you play it. It can be useful when you want to stop an instrument and even more useful when you want to stop a soundeffect with an empty soundeffect.

You can change window as usual with the A button. When you press it once in the ABC menu 1 the the cursor will move to the waveform editor window 2. When you press it again it will move to the arpeggio table editor window 3. And when you press it again the cursor will move to the three bytes on the bottom of the screen we call the 3 bytes editor window 4. And if you press it again it will jump again to the ABC menu 1 and you can start the circle again.

In the waveform editor window 2 you can input the waveforms. You can move here as usual with wraparound too. As I mentioned above in the waveform editor 15 16 bytes (32 nibbles) large waveforms can be stored what will be uploaded to the waveform memory when channel 3 instruments are used on the channel 3 without mute. So in this window you can use the positions between $00 and $ef and every number is valid here. Consult your docs or the Pan documentation (Recommended Literature) how the channel 3 waveform memory works. It can store 32 nibbles (4 bit digital values) what can be played on the channel 3. So you have to think in nibbles when you input and waveform $00 is between the positions $00 and $0f, waveform $01 is between the positions $10 and $1f, etc. When you are in the waveform editor window 2 the number marked with 6 on the upper right corner will show your position in the window.

In the arpeggio editor window 3 you can program small arpeggio sequences. Or longer ones if you want. You can move in this window as you move in the waveform editor window 2. The only difference is that the arpeggio editor window 3 is $ff bytes large and can be used between $00 and $ff positions. Also when you are in the arpeggio editor window 3 the number marked with 6 on the upper right corner will show your position in the arpeggio editor window 3. In this window you can input to any position you just want to. Depends on you where you start your arpeggio and point there in the instrument(s) you want to use that arpeggio. You can share arpeggios or some areas of some arpeggios between different instruments if you want, you can program here some tricks. The actual arpeggio value will always be added to the actual note (you can see the notes in the note input, "---" is $00, C-3 is $01, C#3 is $02 and you can calculate all of them, I can insert a table here on request) every time when the MBPlay function is called. So when $00 is in the arpeggio table, it will do nothing, when $01 is the value it can add a note or halfnote to the actual note depends on the base note and so on. Above $00 the command is addition, below $00 the command is subtraction and on the middle there is another command $80 is the jump. The jump command has an additional parameter in the following byte what is the jump destination position. For example when you have the following in the arpeggio table at the position $10 and an instrument's arpeggio pointer will point to $10 in its E byte (out of channel 4 what doesn't have arpeggio because doesn't have note and frequency) "$00 $01 $02 $03 $04 $05 $06 $07 $80 $11" than it will play the base note at the first MBPlay call then the next note after the base note, then the third note after the base note (note that the arpeggio value will always added or subtracted to/from the base note) and after it played the seventh note after the base note at the next MBPlay call it will read the jump command and the next byte will tell the player to jump to the $11th position in the arpeggio table and will read $01 at that position and play the second note after the base note, etc. (Of course there are notes and halfnotes too as I mentioned before.) When you are programming the arpeggio, forget everything what you have learned about not to use the GOTO or JUMP command, you will absolutely need it. Another Tip, I think you usually don't need arpeggio or at least not for all channels. It is a good idea to use the following three bytes at the top of the arpeggio table and leave it there: "$00 $80 $00". And when you don't want to use the arpeggio (this one does nothing and loops forever) than use $00 in the E byte.

The 3 bytes editor window 4 is the last one on this screen on the bottom. (Out of the bonus MUSIC BOX text.) You can move left and right with the direction buttons. Those are the main global numbers for the music. The first one is the tempo. The music will be updated every nth frame where n is the tempo and this value. Of course you have to call the MBPlay function in every frame to reach this. And when you are using double or quattro player then the MBPlay function will be called two times or four times a frame so you can easily calculate the tempo. When you are using double player, double the tempo and when you are using quattro player, multiply the tempo by four. The second byte is the NR50 ($ff24) register:

              Channel control / ON-OFF / Volume (R/W)

              Bit 7 - Vin->SO2 ON/OFF
              Bit 6-4 - SO2 output level (volume) (# 0-7)
              Bit 3 - Vin->SO1 ON/OFF
              Bit 2-0 - SO1 output level (volume) (# 0-7)

              Vin->SO1 (Vin->SO2)

              By synthesizing the sound from sound 1
              through 4, the voice input from Vin
              terminal is put out.
              0: no output
              1: output OK

              (from the Pan documentation, refer to your official docs for
              better infos)

I think the most optimal is the $77 value. What is the max volume on both channels (if it is too loud there is a volume potmeter on the machine and loud is better than nothing and I think most games use this volume so the gamer already moved the potmeter to his/her favourite position) and Vin is disabled on both channels. It is the best to disable the Vin on the GBC always especially when MBC5 and Rumble Pak is used and Vin needs battery power and only a special designed hardware can use it so it is really optimal to turn it off. And the third number is the NR51 ($ff25) register:

               Selection of Sound output terminal (R/W)

               Bit 7 - Output sound 4 to SO2 terminal
               Bit 6 - Output sound 3 to SO2 terminal
               Bit 5 - Output sound 2 to SO2 terminal
               Bit 4 - Output sound 1 to SO2 terminal
               Bit 3 - Output sound 4 to SO1 terminal
               Bit 2 - Output sound 3 to SO1 terminal
               Bit 1 - Output sound 2 to SO1 terminal
               Bit 0 - Output sound 1 to SO1 terminal

              (from the Pan documentation, refer to your official docs for
              better infos)

In the different windows you can input with the B button as usual. In the ABC window an input window will come in as shown in the picture above 1 without small input window. We think insert and delete is not needed in this window, because there are no rows and columns of bytesequences, every byte is a unique command for a different instrument. In the waveform editor window the same input window 1 will come in without small input window. In the arpeggio editor window the old input window will come in as seen on the main tracker window with small menu and insert and delete. Also notice that when you insert and delete in the arpeggio editor, the arpeggio pointers will always be corrected in the ABC editor window's E bytes. You don't have to correct them manually. And in the 3 bytes editor window the above shown input window 1 will come in again. As there are only three bytes and all of them has different functions there was no reason to make insert and delete functions there.

After the previous windows this window is quite easy. You can access the player window from all the major windows (directly from the main windows in both pages) by pressing the START button.

When you are in this menu shown above, you can change the starting pattern position with the direction button's left and right directions. This is the hexadecimal number marked with 1 above. Usually when you are composing only one simple music this is $00 as you start your music at the first pattern position. However with our system it is possible to make as many subsongs and jingles in one music as you want. We haven't limited this (as many similiar SID and AdLib trackers). So you can arrange your subsongs and jingles as you want. For example you can make a song between the $00 and $10 pattern order positions, close that song with $ff byte in the first column (loop command) or with $fe byte (stop command) and you can start another one at the $11th position or anywhere you want. But keep in mind this number is never stored. If you make many subsongs and jingles it is the best to write the beginning positions to a piece of paper and use that when you are coding your game to remember where to start the different songs. People do this for many years now in the welknown MOD format musics too, but there are some bytes for the instrument names where usually people note these numbers. So you have to remember and use these numbers when you program your game and call the MBInit function, you have to store this number in the A register and recall the MBInit when you want to play another subsong or jingle.

The number marked with 2 is even less important in most of the cases. This is the pattern position where to loop to after the $ff (loop) command in the pattern order editor's first column. Almost in every cases this is the same number as the one marked with 1. I mean usually composers make music to loop after the end and loop to the beginning again. If these numbers are the same, the music will loop to the beginning again. However we have done this to expand the possibilities. Maybe some composers want to stop totally the music at the end and they put $fe (stop) in the first column in the pattern order editor where they want to stop. In this case the music will be totally stopped and only MBInit can restart in, so in this case this number has absolutely no meaning as there is no $ff (loop). When there is a $ff (loop) command, the music will restart after it to this pattern position given here. You can change this number at the same time as the above number with the direction button's up and down directions. And the same rules apply here too, if you want to use this in your subsongs and jingles and use many of these numbers and differs from the above, the best thing you can do to write these numbers to a piece of paper and use the numbers when you code your game. This loop to number have to be stored in the B register also when MBInit is called and absolutely the same rules apply here too. However I think most composers will not use this function. We only had two reasons to make this function. Maybe some composers want to make similiar musics as the ones used in the Digital Illusions Pinball games. You know the music start somewhere and when the ball is in different areas or different things are lighting, always different subsongs will be started and always with different loops. Sometimes a normal music is started and at a position it start to loop not back to the beginning but to another position, etc. Out of those games I haven't heard similiar programmed music tricks yet. And also these numbers can be useful when you have a really long music (too long to reach different positions fast with the fast forward) and you want to hear your music in a later position.

Out of the direction buttons you can use some more buttons. With START you can leave the player window again. With SELECT you can open the Extra Window, you can read about it in the next section. And with the A button you can start the music at the given position with the given loop to number.

When the music is playing every button will cancel it again out of the B button what will fast forward the music. When you hold it, it will play faster, when you release it, it will play on the standard speed again.

When the music is playing or fast playing you can follow it with the other numbers. The hexadecimal number marked with 3 shows the actual pattern position (you know the actual row in the pattern order editor). The hexadecimal number marked with 4 will show you the actual position in the pattern (between $00 and $3f). And the four numbers marked with 5 are showing the actual row in the pattern order editor. The four pattern numbers where the actual pattern position 3 points to. This is quite easy and help you to follow your music. Also there is a small bonus, a small scroller marked with 6 with the credits, website and e-mail adresses, etc.

When you press the SELECT button in the player window the following screen will show up.

This is the extra window marked with 1. You can see nine menus and I think you can guess the menu functions. You can navigate between them with the direction button's up and down directions and you can activate the menu where the cursor is moving (with Knight Rider effect) by pressing the B button. The function "clear wavetable" will clear the waveform tables in the music, initialize it with zeroes. The "clear patterns" will clear and initialize with zeroes all the pattern order and pattern tables in the music. The "clear arpeggio" will clear and initialize with zeroes the arpeggio tables in the music. The "clear samples" will clear and initialize with zeroes the instrument tables (ABC window) in the music. The "clear all" will initialize with zeroes and clear the whole music, all the above ones and also will write in our opinion optional bytes to the 3 bytes editor window and also will initialize the music header. I don't write more about these, you can guess when you need them. For example when you want to start a new music with your old instruments, waveforms and arpeggios you choose the "clear patterns" and off you go. When you want to start a brand new music or you haven't written any music into the card's SRAM then first you have to initialize the SRAM with the "clear all" function here. However you can do the same when you upload the EMPTY.1X file into the card's SRAM stored in the editor directory.

The "copy pattern" will bring up the window shown on the picture above. With the direction button's left and right directions you can change the source pattern number 1 and with the direction button's up and down directions you can change the destination pattern number 2. With this "copy pattern" function you can save many hours of boring typing with the direction button in the pattern editor. When you want to use similiar but not exactly the same patterns (two drum or bass patterns, similiar solo patterns, etc), you can copy a pattern to another one and modify one of them. Be sure you are copying the right pattern to the right place, this function also can destroy many hours of work when you enter the wrong numbers. There's no comfirmation and no undo. After you have the desired source and destination numbers you can make the copy with the B button or cancel the copy with the A button.

In the "player: x" line you can change the player type by pressing the B button. You can cycle all the possibilities in the actual build. The X1 stands for the single player, the X2 for the double player and the X4 for the quattro player. In the single player version the MBPlay function is called once in a frame, in the double player version two times and in the quattro player version four times. We can build different versions too, music called even more often, hooked to the timer interrupt or even more strange MBPlay function calling methods. Note also that when you replay a multispeed (double or quattro) music, you have to call the MBPlay always at the same raster positions and you have to divide all the available CPU time between these calls. So you have 153 lines (not all visible), you can call a double player music to play back on the right way at the 000th and 077th (153/2) positions and you can call a quattro player music to play back on the right way at the 000th, 039th (153/4*1), 077th (153/4*2) and 115th (153/4*3) positions. Also note that this multispeed function was a really after the final version addition. This speed is not stored in the music and the editor starts in single speed always, so you have to keep in mind your replay speed (or write to a paper or store 1 or 2 or 4 somewhere in the filename as we do in the extension) and set the replay speed every time you start the editor.

With the "back" function you can go back to the player window and leave the extra window.

And finally some words about the "shut down" function. When you choose it the window shown below will be displayed and the machine will be stopped.

So you can see the small screen above marked with 1. This is the same as the Windows 95/98 shutdown screen for example. You know it is safe to turn off your machine (because the cache, swap file, etc are written back to the HD, everything is deinitialized, etc). Maybe you also know that when you turn off your GameBoy Color or GameBoy family, strange things can happen and get some electric shock for example the SRAM. (Or something, I'm not a hardware person and also my english is terrible, sorry.) So things are a bit uncontrollable at the turnoff time. And as I heard nobody got this result (neither we), but anyway it can happen that some random bytes will be written to the SRAM or even it can be destroyed by the machine's turnoff electric shock at the turnoff time. That's why the MBC chip can protect the SRAM and when the SRAM is protected this can't happen. So if you want to be sure you don't loose any data, be sure to enter this menu and choose the shutdown and wait for this window 1 every time before you turn off your GameBoy. And when you see it is safe to turn off your machine you can turn it off and be sure your music is in safe. However we haven't lost any data when we turned off the machine when the SRAM was enabled, theorically it can really cause data loss or corruption, so use this method if it is possible.

There is an assembler called RGBDS (Rednex GameBoy Development System), the last version can be downloaded from here: http://hjem.get2net.dk/surfsmurf/. This is a really great assembler for the GameBoy Color and GameBoy family, many official developers also use it and say that it is better than the official expensive Intelligent Systems ASsembler. And it is totally freeware, so you sure get more for your money when you use this instead of the ISAS system. (Neither the official developers aren't forced to use the ISAS system, they can use RGBDS, GBDK or TASM (Table driven ASseMbler) or anything they want, so the free and great RGBDS is really recommended, we use it as many official and hobby developers.)

You can find three different player versions in the EXAMPLES and PLAYER directories in the full purchased version and one in the freely available version. In the RGBDSLIB directory you can find the RGBDS library version of the player with a header file. This directory is available in both packages. In the full version you can find the RGBDSSRC and ISASSRC directories too. In the RGBDSSRC directory you can find the assembly source of the player can be compiled with the RGBDS assembler and in the ISASSRC directory you can find the assembly source of the player can be compiled with the official Intelligent Systems ASsembler (ISAS). And don't afraid if you are using another assembler or C compiler. You can easily switch to RGBDS from everything (and you can easily download RGBDS from the mentioned URL). It is really easy to convert ISAS sources to RGBDS sources for example, the main difference is that where "(" and ")" is used in the ISAS you have to use "[" and "]" in RGBDS. (And there are some more minor differences, I saw a documentation about it somewhere but I don't have it anymore. Maybe one day I'll write a how to guide about it. Anyway it is quite easy to convert ISAS sources to RGBDS sources.) And if you are using GBDK, there is a tool here: http://members.xoom.com/SamNova/ to convert GBDK object files (compiled C or assembly files) to RGBDS object files, so you can easily link your GBDK work with the RGBDS linker and use our musicsystem.

So the players incuded with the full version are the ISAS assembly source player and RGBDS library and assembly source players and the examples are the ISAS assembly source player example and RGBDS library and assembly source player examples. And of course customers will get many more. On request we will convert the player for the customers directly to GBDK, TASM or anything else, also we will give them the sources and other examples for RGBDS and ISAS and everything. Even we will do many modifications on request for them. So customers will get a lot of support, just check out the Support section.

Now back to the examples available in this package. You can find the examples in the EXAMPLE dir with everything: libs with header files or assembly sources, example sources, compiled examples, linker scripts and batch files to compile the examples with RGBDS or ISAS. And also example musics. The example musics are the same in these dirs in the current package. As we know this music never had a title and was used in the Crest Avantgarde/Crest demo's The Fly part and was composed by Giuseppe "Xayne" Musardo, converted to the Music Box singleplayer format by Jukka-Pekka "Fusion" Luukkonen. The filename is XAYNE.SAV and is a 8192 bytes large singleplayer file. This is an exact file taken from my GameBoy Color's SRAM, so you can see how easy is to play a music directly from the SRAM. So if you are a programmer you have to know how to compile and use the system, study the examples, headers, linker and compiler scripts, really well documented sources and you will find out how easy to use this system. The RGBDS library player version has a small limitation the others (RGBDS player source and ISAS player source) doesn't have. Because this is a compiled player it is stored in a fix bank, in this version in the first (home) bank what I mainly call zero bank. It is around hexadecimal $400 bytes large (with tables) so you will need some free space in your zero bank for the player. Of course customers can use the player in the other banks too, they can compile the player everywhere they want to. MUSBOXEX.GB is the low end compiled player example available in all EXAMPLE directories. Does absolutely nothing just plays the XAYNE.SAV music.

I think you can find everything in the MUSBOXEX.ASM, MUSBOXEX.S and PLAYER.INC files. However some additional words. MUSBOXEX.ASM and MUSBOXEX.S are really-really-really minimal players. (Don't learn the GB code from these as the system isn't initialized on the best way, everything is cut down and also it is not optimized to the low power consumtion your commercial games have to.) Only the following lines are important. The lines "include "player.inc"" or ""include "player.asm"" or "include player.s" depending the system you are using, where I include the header file needed for the lib or the assembly source of the player. The lines "music: incbin "xayne.sav"" or "music: libbin xayne.sav" again depending the system you are using are the lines where I include the musicfile as binary data. As I mentioned somewhere else you don't have to include the whole 8192 bytes large music if you don't use the whole file. You can crop it to a smaller size if you really know how to do it and what you are doing. And we will do this for the customers of course on request. And also as you can read somewhere else the music can be everywhere in the memory even in the lib version, doesn't need to be in the zero bank. You can use it in the other ROM banks, RAM banks, etc, but you have to activate its bank and make it accessable when you call the player functions, this is the only thing you have to keep in mind. You can see how to initialize the music with the MBInit function. You have to load the music address to the HL register "ld hl,music", you have to load the starting pattern position to the A register "xor a" (the same as "ld a,$00"), you have to load the loop to pattern position to the B register "ld b,a" (the same as "ld b,$00" in this case) and finally call the MBInit function "call MBInit". Also keep in mind you have to switch in and enable the music bank if it is on a different ROM or RAM bank before you call this. And you can see the "call MBPlay" several times. You have to call MBPlay without parameters in every frame at the same raster position to update the music to play a single player music. (The position doesn't matter, in this example I wait for the 000th raster position and when the raster reach that position I call the MBPlay routine to play the music.) To play a multispeed music you have to modify the example a bit (and you have to play the music on a bit different way in your game). To play a double speed music you have to call MBPlay two times in a frame and to play a quattro speed music you have to call MBPlay four times in a frame, so you have to divide all the available CPU time between these two or four calls. So you have 153 lines (not all visible), you can
call a double player music to play back on the right way at the 000th and 077th (153/2) positions
for example and you can call a quattro player music to play back on the right way at the 000th, 039th (153/4*1), 077th (153/4*2) and 115th (153/4*3) positions for example. I hope it is clear now for even the beginner hobby programmers. You have to uncomment the marked lines, the area with the third MBPlay call for double player musics and all the areas with the MBPlay calls for quattro player musics. You can read more about this in the middle of The Extra Window section.

Also there is an MBStop function to stop the music totally. But refer to the PLAYER.INC, PLAYER.ASM and PLAYER.S files (the ones available with your package) for a better and more detailed description about the four functions. And you can read about the soundeffect player in the following How to Use the Soundeffect Player section.

First read the previous How to Use the Player section totally, everything stated there is apply here too. And read the PLAYER.INC, PLAYER.ASM and PLAYER.S files (the ones available with your package) too as I mentioned in that section too. Now you know how to edit music, how to code the player, how to compile, what to use, how to initialize, play and stop the music. And you need soundeffects.

You can make soundeffects in the editor on the same way as instruments. Soundeffects are instruments. And can be played on all the channels, the first, second, third or fourth one. And you can use them as usual, use channel 1 instruments and play them on channel 1 for channel 1 soundeffects, use channel 2 instruments and play them on channel 2 for channel 2 soundeffects. You can make channel 3 instruments too and play them on channel 3 as channel 3 soundeffects and in this case you can use waveforms too just as usual. And you can use arpeggios too on the standard way on these three channels too. However you still have to call MBPlay in every frame (or more times a frame) to use the arpeggios. And if you don't use music in your game only soundeffects and don't use arpeggios neither, you can leave out the MBPlay too and you will not use arpeggios, only the very first value will be used in the arpeggio table for every channel where their arpeggio pointers point to. And you can of course use channel 4 instruments on the channel 4 for channel 4 soundeffects. But there is no arpeggio and note on channel 4 so you don't have to care about arpeggios in the case of channel 4. Neither about MBPlay when you don't use music and only use channel 4 instruments.

You can play soundeffects any time you want by calling the MBPlaySFX function. It has some parameters and many things to keep in mind, refer to the PLAYER.INC, PLAYER.ASM and PLAYER.S files (the ones available with your package). You have to load the instrument number into the A register. But remember in the editor the instrument numbers are increased by one, check out the ABC editor window. (It has the reason and I think it is not that hard to keep in mind.) So when you want to play the first instrument, it will be the instrument $01 in the editor and you have to load $00 into the A register in this case. So subtract the instruments in the editor by one to get the real instrument number to load to A. You have to load the note number to the B register. This works similiar to the A register, because you have to subtract the numbers used in the editor by one. (At least theroically, because as you can't see the editor sources, you don't know the real numbers.) So check out the note input, C-3 is $00 in this case, C#3 is $01 and so on. You can calculate the number easily you need and you can load it into the B register. (Customers will get a table to calculate this on request.) And you have to load the channel number to the C register, load $00 for channel 1, $01 for channel 2, $02 for channel 3, $03 for channel 4. (Also you have to subtract this time too as you can see.) And after these you have to call the MBPlaySFX function and the soundeffect will be played. (Of course you have to activate the music bank if that is on a different ROM or RAM bank and initialize the music as always.)

As you can see in the Tips section there are some more tips for the soundeffects. For example when you are using looping instruments (check the counter/consecutive bit in the docs) it is a good idea to make a null instrument and play that on the same channel to stop your last soundeffect when you want to stop itt. For example when a bee comes in to the screen, it will have a looping sound and you have to stop it when it goes out from the screen.

Well, I will not recommend many books from Amazon or something because the following reasons. First we are really poor people without credit cards, so we can't earn money or discount from Amazon by doing it (I guess everybody recommends Amazon books these days everywhere because this). Second as we don't have credit cards and neither we don't have too much money to spend on books we don't have too much experience with the Amazon or other books and we don't have anything to recommend from Amazon or the shops. And third Amazon and the shops doesn't have any books about Nintendo GameBoy development I think. :)

At this moment I only can recommend the official GameBoy development manuals you already have if you are an official developer and maybe even if you are just a hobby programmer. In those books you can find everything you need. However I recommend a small and a bit outdated not official textfile too about the GameBoy known as "Pan/Anthrox documentation" or "Everything You Always Wanted To Know About GAMEBOY". This is not GBC specific, but we are talking about the GameBoy soundchip programming in this manual, so that can be really handy. You can find it here. Remember even if you are just a composer you have to know EVERYTHING about the GameBoy soundchip, so learn the soundchip section in your manual or in this textfile.

At the moment when I'm writing this the system wasn't released to the public, only a limited number of betatesters used it. So not too much questions were asked frequently, only a few. I list the ones I remember and also answer them here.

Q: What's wrong with the emulators? Can I use them to compose music? I have no other choises.

A: Well, GameBoy is the most frequently emulated system. I think I know around 30+ emulators and when I'm writing this surely another 5 people plan to make one. Anyway the sound in emulators is always a low priority thing I think. (I'm not an emulator programmer.) People making emulators usually leave the sound emulation to the time everything else is working and they don't spend too much time with it. I haven't tested too much GameBoy emulators to find out how good their sound emulation is, only the most wellknown ones. Mainly tested the following ones with the following results. And I think in sound and other ways these are the best emulators, most of the other ones has no sound emulation at all or only AdLib or really-really low quality:

SMYGB: Known as the emulator with the best sound. And it is discontinued as I know. The sound sounds great in my opinion too but sounds totally different than the real thing. And can't load and save the SRAM (.sav files) therefore it totally cannot be used with Music Box. (At least I wasn't able to force to do this some mins ago and also other people say it cannot do it.)

DBoy: This one was my favourite, it is a really improved VGB with a really improved sound. Can load and save .sav files too. Theorically can be used with Music Box. However its sound emulation has many problems and not only its sound emulation. It doesn't update dinamically many of its registers (including the palettes and the sound registers) so it totally cannot be used with double and quattro musics. The third digital channel emulation is almost equal to zero, totally ignores the waveram, plays only some scratch sound and always the same. And the fourth percussion channel emulation is also really bad. So I really don't recommend this, only a music with single speed and only the first two channels sounds similiar to the real GB. And this emulator is also discontinued so nobody will fix these bugs.

NO$GMB: The best emulation in all the aspects. I think its only problem is the limited palette and out of this almost 100% real GB emulator. It is always in development and also the development and debugger tool of many official developers, so it is really useful. Its sound is also quite well emulated, I think theorically the sound emulation is also 100%. It emulates all the four channels, plays the wavetables, etc. However its sound is also sounds quite strange. (At least on SB cards, I didn't tested it with my Gravis Ultrasound yet.) The sources aren't available so I don't know what exactly the problem is, but it sounds really different compared to the real machine. However if you make a music with it and it sounds like a good music, usually it sounds like a good music on the real machine aswell (sounds different, but sounds good). So neither NO$GMB isn't a good choise to compose music as the result will sound totally different on the real machine, but if you don't have any other possibility really, then use NO$GMB and the latest one.

So I really-really don't recommend to use the emulators, but if you really have no other choises, use NO$GMB. If it is possible, use the real machine.

Q: It is totally impossible to use this system, I will never learn it. What can I do?

A: I heard this from a betatester using NO$GMB and I also think it is too hard to control the system with the default keyboard layout of most of the emulators. The Music Box control was designed to the original machine and it is really useful on that system. OK, it takes at least two days of practice, GBC isn't a Palmtop with a QWERTY keyboard unfortunately (you can read more about this in the Future Versions section) but after some days of practice on the real machine you will find it quite useful and the most comfortable control we were able to make for a tracker with this limited controller. And if you are using emulators (however we really don't recommend it), use a 4 buttons gamepad. It is the closest to the real GameBoy controller and it is far easier to use that with Music Box or any other GameBoy program than the PC keyboard. You can configure a 4 buttons gamepad exactly the same way in DBoy and NO$GMB as the real GameBoy's keypad works. And a 4 buttons gamepad is really cheap, at least here you can buy one for 4 USD.

There were some more important questions, but I already answered them somewhere else in this documentation. I hate writing large documentations so I don't want to write the whole documentation again to this section. If you seriously want to use the system, PLEASE, read the whole documentation totally at least once before you ask. And if you can't find the answer to the question you have then feel free to ask.

I wrote about almost any trick and tip in the other sections of this documentation I wanted to write about. So read the whole documentation to get the tips. Anyway you can find some quick important tips here again.

So as I mentioned before you have to choose which instruments to play on which channels. It is your choise, but it is a good idea to make some rules for yourself. For example to use instruments $01-$08 on channel 1, instruments $09-$10 on channel 2, instruments $11-$18 on channel 3 and instruments $19-$20 on channel 4 or something.

Also it is good to have a null instrument, the most recommended is the instrument $01 or $20 to remember easily. You can use this null instrument to stop a looping instrument or soundeffect.

And also it is a good idea to have a null arpeggio too, to use with the non-arpeggio instruments. The best is to have the null arpeggio at the beginning of the arpeggio table at the position $00. The null arpeggio table can be for example $00, $80, $00. This will not change the actual note and loop back to the begginning of this arpeggio sequence always. So you don't have to change the original zero initialized E (arpeggio pointer) bytes in the ABC editor for the instruments where you don't want to use arpeggio. With this those instruments will automatically use the null arpeggio.

At the moment we aren't sure we will make future versions. We have many-many great ideas to make a much more better system (format, player, editor), what sounds even better and is more flexible and compressable (the player and format) and what looks better and even more usable (editor). A complete rewrite, a V2.0 version. However we have to live from something so we better try to get a job in the industry and make some games instead of wasting our times on a better system. We think this one is also quite good and will serve us well in our products and will serve the customers too because it is really good compared to most other GameBoy musicsystems (and they will get some personal modifications on request). So we don't think there ever will be a Music Box V2.0 but mainly depends on you. If many companies and people will use it, we will see it worth to us to make a better one and we will do it and you will get it. However you have to buy it and give us donations and give us a job in the industry if you can and if you want a V2.0.

Some quick ideas to the V2.0 out of the mentioned ones. (Better sounding, more flexible and more compressable player and format, nicer and more usable editor, etc.) We think if we will have some money and time (time is money and money is time), we can ship the V2.0 version with a better written (not this buggy english) and more professional and printed manual. And hardware together with the system. For example a card with the editor on it, a cable to connect the system to the PC directly and transfer music with it runtime, etc. We only have some light ideas, but we also like the idea to connect a keyboard to the GameBoy Color to control the editor even more easily or use the IR port with IR keyboards and connect two machines with a serial cable to transfer music and transfer music with the IR port too. Also a cable as I mentioned before to transfer the music from and to a PC. So we need money to make hardware to make the new system better and easier to use and more comfortable. Depends on you if you need it and if you want to help us to make it (by buying the current version, giving us donations or jobs in your GameBoy company).

As I mentioned many times in many sections, we cannot give support to the non-customers. Neither answer many stupid questions, etc. (Anyway just ask, smart questions will be answered.) We really sorry, but we are only two persons doing all these things and we are really poor.

However custmers will get FULL support. They will get absolutely every help they can get. We will answer every question they ask, we will make more examples if they want. We will convert the player to be compiled with different compilers on request with full commented examples and detailed extra descriptions. Also they will get the sources and they will be able to use the player in other banks. We will crop their musics to a smaller size on request. And we will even modify the player and editor to their needs. Even we will code parts of their games on request if they cannot use the system in their games. So if you think you can use our system in serious commercial projects it worth buying it.

As I mentioned before Music Box can be used freely by the hobby programmers in their nonprofit public domain productions. And only in those. However if you are a hobby programmer and use it in a nonprofit public domain game or demo, please credit us in your production and if you are rich (or at least richer than us) and like our stuff, please support us with donations. After donations we will see that our system is popular and after donations we can give some support and we will get some motivation to make similiar things and make Music Box V2.0 one day. And if you are really rich and like our stuff, please buy it even if you are just a hobby programmer. You will get full support, sources, help, everything and you will help us a lot to survive.

Also if you are a professional developer and like our work, you can hire us for games and similiar systems. We would like to work in the GameBoy game industry. We are looking for a good job. (We can bring our musicsystem too into the project and many other things we have done on the GameBoy.)

And of course if you are a professional developer want to use our system, you can buy it. And remember you can try our system out and decide if you like it or not. (This is the only GameBoy musicsystem with this policy.)

Anyway if you want to give us bugreports, donations, your PD products with our system (please send those too, we want to see all your products with our system), your musics done with the system (and send those too please) or want to give us a job or want to buy the system, don't hesitage to contact us. The easiest way to contact us is to contact us in e-mail.

If you want to contact us, please contact Ray if it is possible. His e-mail address is credo@scs-trc.net. Contact him with questions, for business, with donations, with musics and PD stuff, with bugreports and anything else.

And also you can contact Zsolt too, but he is really busy nowadays, contact him only with the editor bugreports. His e-mail addres is merlin_pi@stones.com.

Music Box Editor, Music Box Music and Soundeffect Player, Music Box Fileformat and Music Box Documentation, examples and others in this zip file were done by and copyrighted by and propherty of Zsolt Minier and Ray Nemes. You don't have the right to modify, disassemble or sell the archive or its contents without a written agreement from the authors. You can use the musics created with the editor and the player lib in your productions freely only in the case your production is public domain (not commercial, shareware, freeware but public domain), you credit us (Zsolt Minier and Ray Nemes) as the musicsystem's creators and you send us your musics and public domain products.

Of course it is possible to use the system in commercial games and other things, that's why we have created this for ourself and other developers. But in this case the system is not free, contact us for more details at the e-mail address credo@scs-trc.net. Don't afraid, it is cheap. And even if you want to use the system in only public domain productions, you can buy the system or give us donations if you want support or to help us. (You know we will give our customers FULL support, just check out the Support section. Different well documented and commented player versions to use the system with other compilers or in other banks, player sources, we will modify the system on request, answer ALL the questions, etc.)