Valis II enhancement patch v3.0
-------------------------------
(c) 2018, 2023 by FRS

This patch enhances and bugfixes the game Valis II for the MSX2

==============================
Overview of the enhancements/fixes (TL;DR)

This is a summary of the changes. If you're interested in the fine-grain
details, check the changelog ahead.

- Full support for the MSX turbo R, with a proper turbofix of the game,
  cutscenes and music replayer
- 3rd version of the enhanced drumkit, improving its quality yet even more
- Better multiplexing of the PSG between the SFX and BGM, including on the
  cutscenes
- The PSG volume has been adjusted to match the FM volume
- *Lots* of optimizations. All blitting and keyboard/joystick routines
  have been rewritten. The MSX2 with Z80A now runs the areas with
  scroll as fast as the R800 did on the original game, beats the PC-88 version
  running at 4MHz, coming very close to the PC-88 turbo at 8MHz. And with much
  less noticeable tearing than the PC-88/8MHz too. A 7.14MHz turbo MSX2 runs
  the game with almost no slowdown (tested on a CIEL Expert3)
- In a nutshell, the game now runs ~53% faster on the Z80, and ~88% faster on
  the R800
- Replaced the game barely functional dynamicVsync routine with my own, that
  keeps a much steadier frame rate, fixing the issues of the original that went
  from sluggish to peaks of enemy speed frenzy when Yuko wasn't moving
- Greatly improved the keyboard/joystick responsiveness. Fixed the constant
  missing of button presses and key combination misses
- The compatibility with the NEOS MA-20 "version up adapter" was restored
- The opening cutscene was almost entirely rewritten from scratch. All of its 
  takes now run smooth, and it was entirely synchronized with its respective
  BGM. 
- The cropping of the ominous moon was also fixed, so the MSX version now also
  has a truly ominous moon like the versions of the game for other platforms
- The Reno and Title screen animations have been fixed and all their animations
  run smooth now and can be skipped at any time.
- The title screen now loops back to the opening cutscene after the title music
  has ended, like the majority of native MSX games do.
- The other cutscenes received a turbofix. But they still need a lot of work
  in terms of optimizations (all cutscenes are horribly coded)
- Lots of bugfixes on the game and its cutscenes.
- Some keyboard keys were changed:
  - The pause key was changed to the STOP key instead of ESC/CAPS LOCK
  - ESC can now be used to escape menu selections
  - Z/X were remapped to SPACE/GRAPH to avoid key ghosting
- The "Engrish" messages were all rewritten
- This patch enables the turbo on any machine that has the CHGCPU BIOS function
  on its BIOS, granting an even much smoother experience and shorter loading
  times.


==============================
Detailed changelog

- BGM/SFX
  - Enhanced drumkit v3. All the improvements from v2, plus:
    - All pieces of the drumkit were tweaked sound more natural and to be
      pleasant when listening with headphones, or even when listening it at
      louder volumes on loudspeakers. Be sure to try them on a sound equipment
      that has good bass levels
    - The two snare drums of the set (one with a flatter sound, and other more
      acoustic) have been enhanced and now can be clearly differentiated. Some
      songs made great use of this in their composition, but sadly the
      instruments until now were not able to express it very well
    - The cymbal, ride cymbal and HiHat all have been finely tweaked to sound
      more metallic and have a more perceivable hiss at the end
    - Small tweak to the bass drum to make it more punchy than on v1/v2, and
      have that lovely perceivable membrane hit vibration noise
  - Better multiplexing of the PSG between the SFX and BGM. It's a simple
    workaround and not yet the definitive solution, but at least it allows the
    drums to be heard most of the time now. A different priority from the
    v2 of the patch is now used when the cutscenes are running, trying to
    balance the SFX, drumkit and beep voices the best way possible
  - The PSG volume has been adjusted to match the FM volume, finally fixing
    the obnoxiously loud PSG volume that this game originally had.
  - Implements a workaround for the SFX bug in the OPLL driver, that happens
    at the 2nd part of the cutscene at the end of act 5.
  - Implements a workaround for the bug that caused the music of the equipment
    menu to be corrupted after items that required disk access were selected.
    The music is now restarted in such cases
  - Some of the sound effects were also enhanced. Like the bug character voice
    now sounds like a buzz, and some weapon sound effects
  - Optimized the music replayer for the Z80, and when the system timer is
    present (i.e.: TR, OCM), it will be used on the OPLL write routines
- Keyboard/joystick:
  - The original keyboard routines were very bad, and the Z/X keys were a poor
    choice, because they cause too much key ghosting. The game tried to
    workaround this by software and only made things worse, causing many key
    combinations to be missed. I changed the keyboard mapping to one of the
    defaults used on the MSX standard (SPACE and GRAPH for the 2 action
    buttons), since they were designed to not produce ghosting in combination
    the arrow keys.
  - Control responsiveness has been immensely improved. The original game took
    a lot frames to react of key/button presses making its responsivity very
    poor. The worse the frame rate, even worse it reacted. This was very
    noticeable when trying to use autofire. It was an art to try to fine tune
    an autofire speed that the game was able to react. The keyboard and
    joystick are now read at a higher priority using interrupts
  - ESC can now be used to escape menu selections
- Reno Logo:
  - Fixed: Spurious pixels at the top left of the Reno logo screen
  - Fixed: Falling Reno logo animation sometimes was not shown due to a race
    condition
  - Fixed: the rising animation was sluggish
  - Fixed: the rising animation cropped the right part of the logo
- Valis title screen:
  - Turbofix all animations
  - Corrected the position of all animations
  - The animations that compose the title screen now can be aborted
  - Fixed the "Mugen Senshi" part of the trail animation that wasn't erased
    correctly
  - Smoothed the rising animation of the title screen
- Game Engine:
  - Optimized all blitter routines and many other processing routines:
    - Much faster blitter routines
    - The faster HMMV blitter command is now used to draw solid color tiles,
      instead of HMMM
    - Much faster interrupt handling routine
    - Faster memory buffer cleaning routines
    - Faster high-priority interrupt driven keyboard/joystick reading routines,
      with caching and a quick reaction algorithm not affected by eventual game
      frame rate slowdowns
    - Better VDP register handling routines
  - Replaced the game barely functional dynamicVsync routine with my own, that
    keeps a much steadier frame rate, fixing the issues of the original that
    went from sluggish to peaks of enemy speed frenzy when Yuko wasn't moving
  - Fixed two bugs that caused tiles to somewhat frequently be blitted with
    LMMM instead of HMMM, causing slowdowns
  - The "ACT xx" message shown at the beginning of each stage while loading the
    data from floppy will now remain enough time on screen for quicker media.
    This delay can be skipped by pressing an action button
  - Turbofixed the flashing of the change disk message
  - The "Engrish" messages were all rewritten, including:
    - "ACT X" messages at the beginning of each stage
    - Message that presents a boss before its fight
    - Message shown after you beat the boss
    - "Disk CLASHED" message
    - The equipment menu categories and NONE selection
    - The message shown when the Equipment menu is being loaded
  
- Cutscenes:
  - Turbofixed all timings
  - Fixed the Megas awakening eyes animation bug on the 1st cutscene (his right
    eye remained almost closed)
  - Fixed the frames with glitched palettes on take changes of the opening
    cutscene
  - Fixed the chopped bottom of the ominous moon in the opening cutscene
  - Fixed the size of the ominous moon. The graphic was entirely present on
    the VRAM, but only part of it was shown. Now the MSX version has a truly
    ominous moon like the versions of the game for other platforms
  - Remade all the horribly coded animations of the opening cutscene
  - Synchronized the opening cutscene with its respective BGM. This gives it
    a much deeper experience, since the BGM tenser parts now reflect what's
    happening on the screen
  - Fixed the Yuko hair animation timing when a credit text is printed
  - Optimized the low-res big chars printing routine
  - Optimize the palette set routine
  - Optimize the color fade routine
  - Enhancement: The title screen now loops back to the opening cutscene after
    the title music has ended, like the majority of native (non-ports) MSX
    games do. This reduces the risk of CRT/OLED burn-in.

For an even more pleasant music experience, you can check if your MSX computer
needs a hardware sound fix at the following page:
http://frs.badcoffee.info/hardware/MSXfixes.html


==============================
Known issues
- The 1st boss has lost its right horn. This is a side effect of the HMMV
  optimization. The index for the solid color tile is different only on that
  boss fight. The two tiles will need be swapped in the future for a definite
  fix
- The drumkit is frequently interrupted by the sound effects. A permanent fix
  for this will require a new queue to be added specifically for the SFX, to
  use one of the 2 PSG channels that are free
- On the cutscenes that run on SCREEN5, the chars of the subtitles are being
  shown slightly chopped at the left side
- MA-20 specific:
  - When the MA-20 is detected, the game forgets to detect the MSX-Music
  - Yuko's transformation images on the 1st boss cutscene are mostly skipped
  Note to all Brazilian users that have MA-20 clones or an Expert Plus series
  with a 2/2+ upgrade kit: I'm sorry, I could not debug this further because
  the openMSX-debugger has bugs on the MA-20 support


==============================
How to apply the patch

There's one patch that must be applied to the respective disk of the game.
The recipient DSKs images must have the following SHA1 checksums:

SHA1(VALIS2A.DSK)= f9523acb436548cb28816975f4420d79348e6085
SHA1(VALIS2B.DSK)= ff6c49ba7431459ec46db240470b1bad6fec889b
SHA1(VALIS2C.DSK)= 92aa30bbbc96ed7a742a07f963c0be04b0c4cf6b
SHA1(VALIS2D.DSK)= 9da06782e01dba621d131e1c874e886ad559680f

After successfully patched, the checksums will be:

SHA1(VALIS2A.DSK)= 46532bd8696ea629acb107ac9327e466cced383b
SHA1(VALIS2B.DSK)= d4828d6f0855ebc5065be571e8829dd22c59c5bb
SHA1(VALIS2C.DSK)= 445eb9ddb7e910ba612d69bf00fb97dd5dd14f3a
SHA1(VALIS2D.DSK)= 39177968dfb10b09df2d1eae63daa4d6206a95b5

- You can use the following tools to verify the SHA1 checksum:
  - Windows:
    -MD5 & SHA-1 Checksum Utility 1.1
    - HashTab
  - Mac OS-X:
    - DropHash
    - HashTab
    - (or use the same command as show below for the Linux)
  - Linux:
    - Just type on a shell: openssl dgst -sha1 MYGAME.ROM

- To apply the patch, get an IPS patcher like UIPS, LunarIPS or IPSWin, and
  follow the instructions contained in the manual of that tool.


==============================
Curiosities

1) This game has a much more advanced drum kit engine than it originally seems.
   But, for some weird reason, many of the drum kit pieces had very similar 
   settings, making them nearly undistinguishable from one another. Also,
   the noise generator had some really awkward settings.

2) The music tracks used inside the game are slightly different than the ones
   used in the music test. The boss fight track is the most noticeable.

3) The game has two unexposed variables that enable hidden features:
- 9015h: Sets the max vsize (0~8) for the blitted sprite tiles. Creates a
  venetian sunblind effect on them. Seems to be have been used for debugging,
  reducing the size of the sprite tiles to make them faster. This effect was
  affected by the new faster blitter routines, and now both the vsize and hsize
  are changed
- 9016h: Sets the level (0~8) of a checkerboard dithering "transparency" effect
  applied to the blitted sprites


==============================
Special Thanks & Credits

- OpenMSX team, for their excellent emulator and debugger
- MSX.org crew, for the place where MSX hobbyists can meet and exchange ideas
- Sjoerd Mastijn and Aprisobal, for the SjASMPlus assembler
- Martos, for his original crack of the IPL89 file
- Victor Martinez, for the original turbofix of the cutscenes and integrating
  the English and enhancement / fixes patches
- Pedro de Medeiros, AKA pvmm, for the many improvements he has been making
  on the openMSX debugger. My productivity have become much higher because of
  this
- Sandro Sebastião Singer, for betatesting
- Pablo Bravo-Villalba (aka Parn), for betatesting and proofreading the README
  file

==============================
FAQ
---

Q: Will the patched game run on non-turbo machines?
A: Yes, just as usual. It runs fine on any MSX2 or higher. The NEOS MA-20 is
   also supported.

Q: I applied the patch and the resulting DSKs don't work! What is wrong?
A: Valis II originally had two releases. This patch requires the unpatched
   newer release. Don't apply it on previously patched DSKs, nor on the earlier
   release of Valis II. Please verify the SHA1 checksums to ensure you have
   the correct unpatched DSKs.

Q: Why did you change this or that <specific characteristic>? This is an
   unacceptable heresy, and shouldn't have been done!!!
A: I changed what I needed for my personal use and for some close friends, and
   am also sharing for those who might enjoy what took way too many hours of my
   effort to cook. Nobody has any obligation to use if they don't like it.

Q: Could you do a custom version just for me, tuned to the way I want?
A: No. Whatever I choose to share is for the benefit of most MSX users as
   possible.
   When a single person wants something custom tailored just for them, it is not
   a hobby anymore and should not be expected to made for free.

Q: Why can't the MSX2 @ 3.57MHz run this game any faster? <This> or <that> game
   was able to do it.
A: Valis II was designed for the PC-88. It uses 16x8 tiles there, that were
   translated to 8x8 tiles in the MSX2 screen5 mode. This is a sub-optimal size,
   resulting in a poor ratio of pixels drawn per Z80 I/O write. Ideally, the
   V99x8 blitter would work better with at least 16x16 tiles. It's the classic
   problem with game ports: the developers end up trying to fit a square peg on
   a round hole.
   The only way to compensate for this is to have a CPU that can do faster I/O.
   This is why a 7.14MHz Z80 runs the game so much better.

Q: Why so many versions for an enhancement patch? Can't it be done all at once?
A: Consider this a work in progress. This is a huge game, and it's not possible
   for a single person that has a RealLife(TM) to all the enhancements and
   fixes at once. 
   Also some aspects, like the drumkit, required to be done in incremental
   steps, since it's very hard to tweak it the way you want given the
   constraints of the replayer, and also it's done via reverse engineering, so
   on each increment, more about the replayer was learned.
   But do not wait for more improvements so soon, as I need to take a
   break from this game for a while.   :)

===========================================================================
	                     License
                           Terms of use
---------------------------------------------------------------------------

1) This patch is gratis for non-commercial purposes, and the author retains
   its copyright. You only can run, make backup copies or distribute the patch
   while observing the non-commercial restriction.

2) You are only allowed redistribute the patch files (online or on a removable
   media) under the following conditions:
   2.1) No commercial transaction of any kind is involved
   2.2) All the included files are distributed together inside the same
   compressed file.
   2.3) This README must be included unmodified inside the same compressed file.

3) If you want to use this patch for commercial purposes you MUST contact me
   first to negotiate the terms and conditions. Send an e-mail to
   sdsnatcheralpha@gmail.com to contact me.

4) You cannot distribute games with this patch pre-applied.

5) This patch is provided ‘as-is’, without any express or implied warranty.
   In no event will the author be held liable for any damages resulting from the
   use of this patch or the software patched with it.

6) USE THIS SOFTWARE SOLELY AT YOUR OWN RISK.


===========================================================================
                          Donations
---------------------------------------------------------------------------
 If you like the enhancements and fixes here presented and want to show your
 appreciation by donating any amount, or MSX hardware, it will be very welcome
 and will help future developments.
 Donations can be done via PayPal to sdsnatcheralpha@gmail.com, and for MSX
 hardware, try contacting me on this e-mail address too.

 Pixel Art for the MSX1/2/2+ is very welcome too!   :)

 Have a look at my wishlist in the following link:
 http://frs.badcoffee.info/wishlist.html

