"Yawara": General Game Music and Sound Effect Player

Current Version: Bianca-1-0 (2nd Version, 1st Release, No Revision).

Copyright and Legal Notices

"Yawara: General Game Music Player" is composed of several files, all of them `freeware', which means nothing can be charged for them. Parts and/or modified versions of files cannot be distributed without express permission of the author, because it is not `public domain'. It also cannot be either incorporated or distributed with any commercial product or used for any commercial purpose without express permission of the author. Permissions are valid only for one release, not including previous or future releases. When joined to any commercial product, this file MUST be included within the pack and customers explicitly notified about its existence and contents. The program needs segments of copyrighted material to work. Anyone that uses them must have legal copies of them. The author cannot be responsibilized for any damage or illegal act related to them or the program itself. If you use the program, part of it or any information from it, in any way, you are automatically agreeing with all these statements, independently of your social, cultural, legal, religious or theological status. Thank you all for reading this really long notice.

Programmer's notice: legal notice is a real pain, isn't it? "C'est la vie". What the previous statements say is, in other words, that no one should make money out of others' works or take credit in something they haven't really sweat upon to make. It also says that you should purchase legal copies of software, if not to enlighten your soul (if you have one, of course), at least to keep the makers alive time enough to make another enjoyable program (remember that good program makers are hard to find these days). And, yes, I know that most (probably all) softwares supported by this program are not anymore available. My opinion is that we cannot let them fall into oblivion, isn't it yours, too? So, play that music and may the Unicorns be with you!

What Is "Yawara"?

"Yawara" is a Brazilian indigenous word that means `the one that kills with a single stroke', given to the biggest american feline, the Panthera (Jaguarius) onca. The Time and the european colonization of the american continent truncated the word to the well known "Jaguar". Strangely, in Brazil, the feline is wrongly called "Onça" (which also originated the scientific name), from a truncated form of an Italian word for an asiatic feline, "Lonza", but that's just academic. "And what does it all has to do with this program?" Well, Yawara is a Brazilian word for a Brazilian program and, like the big feline, it also "kills" with a single stroke a problem I had with many MSX games: to play their musics.

Yawara was designed to present not only a game music player, but also a good presentation and useful information for bold programmers, all nested in a user friendly environment. Beside the background musics (BGM), Yawara can also play the sound effects (SFX) of some games. The program is a development of a music player that I made for Penguin Adventure.

The program requires pieces of the games to execute, which contains the music routines and data. Small ROM games (8 KB, 16 KB and 32 KB) are used whole. The music routines and data of larger games must be extracted, using some file utility (see the trouble shooting section of this document for more information). The necessary game blocks are packed with each release of Yawara. If the blocks of an older package are not available and you cannot make them by yourself, write me an E-Mail.

Currently Supported Games

La Abadia del Crimen
Akumajou Dracula (Vampire Killer)
Ale Hop!
Amaurote
Antartic Adventure (original Japanese version)
Arkos
Army Moves
Astro Marine Corps
Athletic Land (Colecovision version)
Athletic Land
Avenger
Back to The Future
Cabbage Patch Kids
Camelot Warriors
Circus Charlie
Comando Tracer
Comic Bakery
Elite
The Flintstones
Freddy Hardest
Ganbare Goemon - Karakuri Doutchyuu
Ghostbusters
Gojira Kun (Godzilla)
The Goonies (updated on 2005-09-24, thanks to J.E.P.Mello)
Gradius (Nemesis)
Halloween!
Hinotori Houoohen
Hundra
Hyper Olympics
Hyper Olympics 2
Hyper Rally
Hyper Sports
Hyper Sports 2
Hyper Sports 3
Jagur - Golden Triangle
Jet Bomber
Jet Set Willy
Jet Set Willy II
King's Valley
Konami's Soccer
Mad Mix
Magical Kid Wiz
Magical Tree
Majou Densetsu - Knightmare (updated on 2005-09-23, thanks to J.E.P.Mello)
Majou Densetsu II - The Maze of Galious (Knightmare II)
Majou Densetsu III - Shalom (Knightmare III)
Mask III - Venom Strikes Back
Mon Mon Monster (PSG/FM)
Mopiranger
Mutant Zone 1
Mutant Zone 2
Navy Moves
Nonamed
Outrun
Phantis
Pippols
Power
Q-Bert (Konami)
Rally-X (with some SFX)
Road Fighter
Robocop
Rock'N Roller
Silent Shadow
Sol Negro
Stardust
Survivor
Terramex
Thexder
Time Curb
Titanic
Trail Blazer
Treasure of Usas
Twinbee
Warroid
Yie Ar Kung-Fu
Yie Ar Kung-Fu II
Yume Tairiku Adobentchya- (Penguin Adventure)
Zanac
Zanac - Second Release

System Requirements

MSX with 64 KBytes of "common" RAM (neither Memory Mapper nor MegaRAM will be recognized) and 16 KBytes of VRAM
MSX-Disk (disk driver) and an MSX compatible formatted disk with all "basic files"
MSX-DOS, M80.Com and L80.Com if recompilation is desired or required
MSX-Music (FM I.C. and BIOS) required for FM based modules
Konami Sound Creative Chip (SCC) required for SCC based modules

Basic Package Files

The "basic files" must be all placed in the same disk for the correct execution of Yawara. They are:

Yawara.Bin: this program loads the "shell". It shifts all memory pages to RAM, allowing the execution of any music module. If it crashes your system, try to run "Yawara.Saf", which will keep the BIOS ROM in page 0. Using "Yawara.Saf" means that some modules, marked in the lists with an asterisk "*", cannot be loaded. Don't try them, because the system will probably crash.
Yawara.Shl: this is the "shell program". It presents lists which can be "browsed" like directories. containing all available modules and the planned future releases. If "Yawara.Saf" was used to start-up, "Yawara.SSh" will be loaded instead of the former.
Yawara.xxx: these files are the music players. The extension "xxx" describes the base execution address. For example, "Yawara.C20" is loaded and executed at address &HC200. There are many files of this kind, each one loaded at a different address. A game that uses the area from &H4000 to &HD000, for example, must be accessed by a player out of that range ("Yawara.270" or something like that).
YGMPDCSF.xxx, YGMPDBGF.xxx: these files contain default character set fonts. They are loaded by the "shell". The music players also use them when they cannot find the "presentation screens" (used in the opening and playback screens).
YawaraML.000: the base list. It has the same function of a root directory.

Other Files

xxxxxxxx.GMM: game "xxxxxxxx" music module.
xxxxxxxx.SMM: game "xxxxxxxx" source music module.
YawaraML.xxx: module list "xxx".
YawaraLS.YLS: module list source file.
Yawara.Asm: Assembly source file of "Yawara.Bin".
YawaraSf.Asm: Assembly source file of "Yawara.Saf".
YawaraSh.Asm: Assembly source file of "Yawara.Shl".
YawaraSS.Asm: Assembly source file of "Yawara.SSh".
YawaraPS.270: Assembly source file of "Yawara.270". The other playback files are created upon this one, replacing all occurrences of "270" by the proper loading addresses.

Executing

Yawara may be executed by one of the following commands:

BLOAD"Yawara.Bin",R

BLOAD"Yawara.Saf",R

Try to run "Yawara.Bin". If the "shell" is correctly loaded and executed, you won't need "Yawara.Saf". If the system crashes, try the second loader. If none runs well, then you have a real problem and will probably have to use a simulator (wrongly called "emulator"). I know, it's not a solution, but it's better than nothing. See the next sections for troubleshooting.

Control Keys

The "shell" program uses the following control keys:

<Up Arrow>: move cursor one item up.
<Down Arrow>: move cursor one item down.
<Space>: select an item.
<Escape>: exit from Yawara and return to MSX-BASIC. This key may not work ever, depending on which kind of modules you had executed. If the systems hangs up, you must reset it.

The playback programs uses the following control keys:

<Up Arrow>: move to the next sound effect entry.
<Down Arrow>: move to the previous sound effect entry.
<Left Arrow>: move to the next music entry.
<Right Arrow>: move to the previous music entry.
<Space>: play the selected entry. Some sound effects may be played together with some musics or even other sound effects.
<Return>: silence. Some music modules have special entries to silence only the BGM or the SFX.
<Select>: change the type of bar graphic.
<Escape>: exit the playback program and returns to the "shell".

The following are special keys:

<F4> and <F5>: general control.
<Stop>: reset the game music routines. Works for all modules, but there's no guarantee that it won't crash the system.

I haven't time enough to test all modules for valid music code entries. If a music or effect crashes the music routine, then try to press <Stop>.

<F4> and <F5> controls a generic register, used by some modules to define some feature of the music module, like playback speed (`tempo', speed) and intensity (volume). "Survivor" and "Circus Charlie" have speed and `tempo' control. "Hinotori Houoohen" is the only, by now, with volume control. "Akumajou Dracula", "Treasure of Usas" and others have a sound effect entry that activates a `volume fader', so I didn't check them for manual volume control (maybe "Hinotori" also have a "fader", but I didn't check it). Finally, not all music modules have sound effects, mainly those that don't have specialized music activation routines. <F4>/<F5> may be used to find valid entries in music modules. An example is presented in "model.smm".

Technical Data

The frequency bar graphics are divided in fifteen zones, each one coverring a range:

from 27.3Hz till 46.2 Hz (F1+)
till 65.4 Hz (C2)
till 92.5 Hz (F2+)
till 130.8 Hz (C3)
till 185.2 Hz (F3+)
till 261.9 Hz (C4)
till 370.4 Hz (F4+)
till 525.1 Hz (C5)
till 740.8 Hz (F5+)
till 1055.3 Hz (C6)
till 1491.5 Hz (F6+)
till 2110.6 Hz (C7)
till 3023.3 Hz (F7+)
till 4302.3 Hz (C8)
above 4302.3 Hz (C8)

Trouble Shooting

"How do I do to get the ROMs and game blocks required by Yawara?"

By now, all released modules have the required blocks available. Most Japanese ROM games can also be found in FTP sites in the Internet. If you've got a good mirror copy (one that works and is not modified by some stupid pirate), them it will probably work with Yawara. ROMs that are used whole have the extension ".ROM" and don't require any kind of modification. Larger games, like MegaROM and disk games, must have their music routines and data blocks copied to separate files, which have numeric extensions (".000", ".001", ".002" and so on). You must use some kind of file utility that allows block extraction to create those blocks. You may try SJ. The position of the blocks to be extracted are presented in the respective module source file. To make it clear, by now, you don't have to extract any block or look for good ROM copies, because all required files are available for download in this Page.

"Why is Yawara resetting my system?"

Some modules don't like turbo R starting in R800 mode: if you format a disk in turbo R, the resulting disk will have a special bootstrap sector that will be recognized by the turbo R's start up BIOS routine, automatically activating the R800 mode. Yawara will turn the Z80 mode on in turbo R and any latter MSX (there are none by now, but we never know...) If it crashes anyway ("Zanac" uses to do it), restart turbo R with key <1> (on the main key set) pressed, forcing it to start in Z80 mode, then run the program. If you have a Brazilian disk driver interface, try to restart (the computer, not you) holding <Control> key down. If the interface has already started up with one logical driver, try the reverse: release the <Control> key during start up. The position of the logical driver "A" work area in the memory may be the "X factor" of the system crashing, because it defines the stack pointer address (it is set ever at the highest free address, at the border of the work area). The <Control> key trick does not work with most non-brazilian interfaces. turbo R starts with only one logical drive and allocates less memory for it than other systems (if there are only one physical drive, of course). Keeping <1> key pressed during start-up will create two logical drives in turbo R, what will modify the stack position.

The current version of the program doesn't use BIOS anymore, allowing a far better control of the system behaviour. During start up, it copies the BIOS ROM to RAM, so games that use the 0000H-3FFFH area (page 0) may be loaded and executed (Colecovision convertions, for example). Some systems may not "like the joke" (the idea of having BIOS on `volatile memory' is too much for them). If your MSX don't allow it, run "Yawara.Saf". It will keep BIOS in ROM, but you won't be able to run modules that use page 0 (don't try them, the system will crash, 'cause the program don't check if page 0 is ROM or RAM). Programs that require RAM in page 0 are marked with an asterisk "*" in the lists.

"Does Yawara run in emulators?"

As far as I know, no MSX emulator perfectly simulates a real machine. Some can (almost) render the graphic elements right, some can (almost) reproduce the sounds right and some can (almost) simulate the MSX CPU right, but no one can do them all at the same time. Yawara is supposed to run in emulators with good enough CPU and sound IC simulation.

"I have found a secret music...!"

People that want to try to create modules for other games must be careful. Most music routines are not prepared to receive invalid codes and produce "strange" results for them, some even sounding "good enough" to be valid or "secret" entries. "Akumajou Dracula", for example, has a lot of them, playing tracks from different musics, sounding like different or special arranges, but are actually invalid activation of the music routine, not "secret musics". If someone tries them or creates music modules for other games, be careful to not classify invalid entries as hidden musics, because they can lock up some systems (Compile games, for example) or even damage the computer, sending erroneous data to the PSG (or PPI) control ports ("Zanac", "Thexder" and so on). I recommend the use of an emulator during tests (I don't think emulators can burn down PC ICs and if they do, it won't be a so great loss...) Sound effects are harder to check due to its nature.

About Some Modules

"Yume Tairiku (Penguin) Adventure": this is the first game to which I created a music player. It is, so far, the most complete module and my favourite. Thanks to Konami...
"Hinotori Houoohen" ("compilation story of the legendary bird goddess of the fire" - wow! amazing what one can write with just five "kanji"): those people that have already seen the "anime" or listened to the original soundtrack will notice that I invented the titles, because the musics don't match the O.S.T., except for the refrain of "Hinotori", played on the opening screen and endlessly when you find a "houoozou" (Hinotori Statue).
"Akumajou Dracula" (`castle of the devil Dracula', "Vampire Killer"): the musics match the Famicom CD I have, though there are musics in MSX not available in the disk ("game over", "stage clear" etc.) and two musics available in the CD not present in MSX ("Underground", in the naming screen, unexistent in MSX, and "Voyager", from the ending demo, replaced by another music or an arrange so different I couldn't identify it). And I found a strange problem: music with code 83H in MSX is named "Out of Time" in the CD, assigned to the clock tower stage, and music 85H is named "Walking on the Edge" in the CD, assigned to an underground stage. "Walking on The Edge" comes before "Out of Time" in the CD. Are the music titles swapped or are the order wrong (in MSX or in the CD)?
"Zanac": the game known as "Zanac 2" seems to be a second release of "Zanac", not a sequel (what would explain the unchanged presentation screen). There are modules for both and I couldn't hear any difference (though I had no time to check it for new entries). Note: before starting a new music, press <Return> to silence the current one, or else the new music won't play correctly (or play anything at all).
"Survivor": it was the first Spectrum game convertion I scanned. The playback speed is not defined by the interruption, but by a loop! I'm using a "ratio counter" (similar of those used for integer line drawing) to simulate the loop delay via interruption. The module checks the system frame drawing frequency (60Hz/50Hz) to use the proper ratio value. You can change it in "real time" pressing <F4>/<F5> keys. This same problem appears in other games, like "Avenger", which also has, now, playback speed control.
"Jet Bomber": the program is so "nasty" that the normal execution flux sends invalid data to the PSG register 7. It sets both joystick control bits to 0, id est, for input, what won't probably damage the MSX circuitry. My music module uses its own PSG set-up routine, avoiding any risk. As far as I could check, the game, fortunately, never sets both bits for output, what would put the joystick control ICs in short-circuit, melting them down and digging a crater that would reach the center of Earth and start a "China Syndrome"...
"Majou Densetsu - Knightmare" (`legend of the supernatural/demonic castle'): there are two sound effects that sound very strange. Both play the same notes, but one with noise off and the other with it turned on. I don't know which one is the real entry.
"Antartic Adventure" and "Athletic Land": they are both Colecovision converted games. I remember someone saying that "Antartic Adventure" was `exactly the same ROM'. I think that guy didn't really checked it or he made some mistake and compared the same machine ROMs. "Antartic Adventure" was surely recompiled, for it starts at 8000H, not 0000H. It also uses the system interruption hook. "Athletic Land" was modified, too. The Colecovision version starts at 0000H, but it makes sure that the system hooks are disabled. The other version starts at 4000H and was completely modified (some musics are also slightly different in the second release version). All these games don't use any MSX BIOS routines, of course, and the PSG ports are correctly readjusted to A0H~A2H. The music routines are basically the same of all later Konami games.
"Rally-X": except for "Jet Bomber", the worst coding I have ever found. It seems the programmers used some kind of midle-level programming language (I'd found branches to the next instructions [JR +0]).
"Circus Charlie": this game has "tempo" control. Use values between 4 and 6. Anything else will make it sound strange...
"King's Valley": the game tries to modify itself. Of course, if it is an original ROM, nothing would happen to the code, but if it is loaded in RAM, with some "game loader", the game will not run the same way. A similar problem happens to other games, like "Twinbee".
"Treasure of Usas": I've found a different version of the game. At first, I thought it was just a scrambled mirror copy, but the differences are too extensive, as if it was recompiled. I think it was. I couldn't hear any difference in the musics. Similar problem appears with "Yie Ar Kung-Fu", part I and II, which have different versions.
"Mad Mix" and "Rock'N Roller": "Mad Mix" has a very interesting code. The game is probably the same of Spectrum version, but the interruption handler was rebuilt to allow it to play some music and sound effects. The coding style is a bit messy (the current module doesn't play correctly some effects just after others had been executed - playing a music corrects the problem). The activation routine has an interesting behaviour: if an effect is cast before another one is finished, a new PSG channel is requested to execute it, so up to three effects can be played at the same time (though sometimes the routine "shakes" itself a little and one or another effects are restarted). It also happens to "Rock'N Roller".
"Amaurote" and "Halloween": considerably well done music routines, though not optimized. I think both games have their music routines programmed by the same person (or one was copied from the other), because both use the same code structure, containing even the same "bugs". My mirror of the game was modified by some idiot pirate. The game locks up at a certain point and I don't know if the music routines are not damaged...
"Silent Shadow" and "Stardust": they have similar music routines, almost identical. The code is not very optimized, but does the job, and probably was not programmed by the same author of the games, at least, not of "Silent Shadow". The game code uses invalid instructions, which probably will work on most Z80 in the market, but will bring big trouble to some emulators (and some new version of MSX, who knows, with a different CPU). This same problem is present in many other Spectrum converted games.
"Ghostbusters": most Spectrum converted games present a hazardous bug, they set to wrong values the joystick control bits of PSG register 7 (bits 6 and 7). This bug can literally burn the computer, for it causes an internal short-circuit of the joystick coupling devices. Bit 6 must be always zero (input) and bit 7 must be always 1 (output). Setting both for input may not cause much problem, but some routines set both for output. That's what happens in "Ghostbusters". The silence routine sets both bits to 1. To fix the bug in this game, the following piece of code must be changed:
```
  85BAH:  3E 07  ld   a,07H
  85BCH:  D3 A0  out  (A0H),a
  85BEH:  3E F8  ld   a,F8H    <- change to -> 85BEH:  3E F8  ld   a,B8H
  85C0H:  D3 A1  out  (A1H),a
  
```
"Jet Set Willy": the same bug of "Ghostbusters" is present in this game, but in a far more dangerous form. The PSG joystick control bits are both set to 1, all the time. It means that while you are playing this game, the PSG, the joystick coupling circuits or all of them are melting down. This game seems to be released as a cartridge, which cannot be fixed except by a new ROM recording. Another solution is to use a mirror copy of the game, which is loaded into the computer memory and can be easily modified. The datum at address 7040H (F8H) must be changed to B8H.
"Jet Set Willy II": it seems the programmer of this sequel learned more about MSX, for it does not have the dangerous bug of the first game, but it learned nothing about programming at all. The game has two independent and very different music routines, both different of the first game, so one cannot argue it resulted due to adaptation. It seems two different programmers did the mess and then tried to join the pieces. A waste of time.
"Nonamed": the same kind of problem of "Jet Set Willy" affects "Nonamed": change byte at position EB14H (FFH) to BFH.
"Outrun": the music routines use invalid Z80 instructions. As far as I could check it, they are valid for turbo R's R800 CPU.
"Mutant Zone" (1 and 2): this games has something different of other Spectrum converted serial games, each have a different music. And just to make it not so good, both set the PSG control bits wrong. To fix "Mutant Zone 1", change datum at A0A0H (38H) to B8H. For "Mutant Zone 2", change datum at 99D3H (38H) to B8H.

Special Thanks

Special thanks go to all my friends (I won't name them because I would probably forget someone), my Family and people around the Net that really care for MSX. Special thanks to Adriano Cunha for being a very good friend.

Congratulations go to Ricardo Bittencourt for his BrMSX. It helped a lot in Yawara development and is responsible for the weekly tax of module releases.

I dedicate this program to Cassandra, a wonderful friend that is now flying on the wings of Hinotori. May the Unicorns guide her in the Dreamland...

The "Y" Files

Finaly, the Yawara files. The source files are not required, except in case you didn't get the game blocks of some release package. The source file of a module has information necessary to create the necessary blocks.

Yawara.zip: this file contains all basic files. Unpack and copy them all to a 720 KB disk.
Yawara1M.zip: this file contains all modules from "A" to "G". Updated on 2005-09-24.
Yawara1B.zip: this file contains all game blocks required by the modules from "A" to "G".
Yawara2M.zip: this file contains all modules from "H" to "L".
Yawara2B.zip: this file contains all game blocks required by the modules from "H" to "L".
Yawara3M.zip: this file contains all modules from "M" to "P". Updated on 2005-09-24.
Yawara3B.zip: this file contains all game blocks required by the modules from "M" to "P".
Yawara4M.zip: this file contains all modules from "Q" to "Z".
Yawara4B.zip: this file contains all game blocks required by the modules from "Q" to "Z".
YawaraSr.zip: this file contains the source files.
YawaraSM.zip: this file contains all module source files. Updated on 2005-09-24.

First of all, unpack the "Yawara.zip" file. You can do that using "Unzip", a freeware found at several sites (try ftp.unicamp.br). Copy all extracted files to an MSX formatted disk. Now, you will have to select what musics you would want to listen to. It happens that there are currently so many games with modules available that you won't be able to put them all in the same disk. I don't have hard disk for MSX, so I have no way to know if it will work with Yawara (it should, once no direct disk access is made). Unpack the modules and game blocks of the musics you want to listen to and copy them to the disk. Now, you just have to run the program, as already explained.

Page last modified on 2005-September-24 Saturday.

[!] UNDER CONSTRUCTION [!]