DLL Mod Loader + Extra music formats mod

DEPRECATION NOTICE
This project is no longer in active development! Users are recommended to switch to CSE2E Cave Story: Tweaked.

Ogg Music Mod Extra Music Formats Mod
It wasn't very long ago that I figured out how to make Freeware Cave Story run at 60FPS, only to find someone had beat me to the punch. Hopefully, that isn't the case this time.

Summary
So here's a mod that add support for extra music formats, including .ogg, .flac, .xm, .it, .mod, and pxtone, with drag-and-drop support for the WiiWare and Cave Story 3D soundtrack files from Cave Story+.

The mod supports two formats of Ogg/FLAC music:

1. The first is the version used by the WiiWare soundtrack, where each song gets one file that repeats in its entirety.
2. The second is the format used by the Cave Story 3D soundtrack - each song gets two files: 'songname_intro.ogg' and 'songname_loop.ogg'. As you can imagine, when a song starts playing, it plays the intro file first, then when it ends, it continues onto the loop file. When the loop file ends, it loops back to itself, meaning the intro never gets played again. This allows for more complex music.

Ogg music in the WiiWare format should go in a folder called 'Ogg', which you create in the 'mods/alternate_music/Cave Story WiiWare' folder. Music in the second format should go in a 'mods/alternate_music/Cave Story 3D/Ogg11' folder. Like I said, you can copy the soundtrack files from Cave Story+'s 'data/base/Ogg(11)' folders into your new folders, and they'll play in the original game!

Technicals
The mod currently relies on libvorbisfile, libFLAC, and libopenmpt to provide support for its various music formats. With some work, it could be possible to add support for even more formats, but right now it's only .ogg, .flac, pxtone's formats, and most of what's listed in here.

Installation
The alt. music mod comes with the DLL Mod Loader. See its section of the post below.

Remember, unless you're making your own soundtrack, you'll need to provide your own copy of the WiiWare/Cave Story 3D soundtracks to have them play in this mod. Cave Story+ is a legitimate way of obtaining them. You can extract the 'Ogg' and 'Ogg11' folders from its 'data/Base' folder, and paste them into your 'mods/alternate_music/Cave Story [WiiWare/3D]' folder.

You can also install the Famitracks soundtrack from Cave Story+ Switch, but retrieving the files from that version is a much more involved process that I don't want to go through the hassle of describing here.

DLL Mod Loader
This is a loader for mods stored in DLL files.

Usage
Mods are installed in a folder called 'mods' in your Cave Story directory. Inside that same folder is a 'mods.txt' file, which controls which mods will be loaded.

Each line in mods.txt contains the name of the mod you want to load. Here's a sample layout:

alternate_music
ikachan_cursor
wasd_input

If there's an error in your mods.txt, a file inside the mods folder called 'error.txt' will be made when you try to run the game, telling you what went wrong.

Inside the mods folder, each mod has its own folder, inside which the mod's DLL file and settings file are stored, leading to a file layout like this:

Cave Story folder
  Doukutsu.exe
--mods folder
    mod_loader.dll
    mods.txt
    settings.ini
----alternate_music folder
      alternate_music.dll
      settings.ini
      playlist.txt
----ikachan_cursor folder
      ikachan_cursor.dll

Sample mods
Included with the Mod Loader are some sample mods:

alternate_music

Spoiler

This is the mod described at the start of this post, read there for more information.

This mod has a settings file, with the following options:

1. playlist - Defines the filename of the playlist file

The playlist file is in a special format: each line represents a song, corresponding to the game's internal music order. Each line consists of a comma-separated list, with the first thing in the list being the path to the music file, and everything after that being a property of said music file. The following properties are currently available:

1. loop - When the song ends, it begins again
2. org - Ignore this, and just play the default Org file instead

wasd_input

Spoiler

A reimplementation of the WASD mod. This one allows the use of a greater range of keyboard keys than the old EXE mod.

Controls:

• W - Up
• A - Left
• S - Down
• D - Right
• O - Shoot
• P - Jump
• [ - Inventory
• ] - Map
• 9 - Previous weapon
• 0 - Next weapon

sdl_controller_input

Spoiler

A reimplementation of the controller system, aimed primarily at XInput devices. Unlike the original implementation, this allows you to control your character using the D-Pad.

In addition, enabling gamepads in DoConfig no longer disables keyboard controls.

Controls:

• D-Pad/Left Stick - Movement
• A / Cross - Jump
• X / Square - Shoot
• Y / Triangle - Jump
• B / Circle - Shoot
• LB / LT / L1 / L2 - Previous weapon
• RB / RT / R1 / R2 - Next weapon
• Start - Inventory
• Back / Select - Map

ikachan_cursor

Spoiler

Restores the unused Ikachan cursor.

debug_save

Spoiler

Restores the Debug Save menu.

disable_image_protection

Spoiler

Disables the '(C)Pixel' requirement in .pbm (bmp) files.

3ds_hud

Spoiler

An attempt at recreating the 3DS eShop port's HUD, which is less screen-invasive.

graphics_enhancement

Spoiler

Adds 60fps, widescreen, higher sprite sheet resolutions, larger window sizes, borderless fullscreen, and V-Sync in exclusive fullscreen. More information can be found in its thread here.

title_background

Spoiler

A customisable mod that gives the title screen a background.

Settings:

; This is the filename of the bitmap to use. Typical options are
; bkBlue, bkFog, bkGard, bkGray, bkGreen, bkMaze, bkMoon, bkRed
filename = bkMoon

; This defines what type of background this is.
; 0 - Tiled, static
; 1 - Tiled, moving
; 2 - Scrolling clouds - bkMoon-style
; 3 - Scrolling clouds - bkFog-style
type = 2

Compatibility
The loader and its mods are designed for Version 1.0.0.6 of Cave Story (2004 Windows version). This includes the original Japanese version, the English-translated version, and the WASD hack. I cannot guarantee its compatibility with mods and older versions of the game. If you're making a mod that uses this, be aware that it may conflict with some of the more exotic EXE hacks, like <IMG.

Installation

Spoiler

Download the mod loader and its sample mods from the link below. Inside the zip file is a folder called 'mods' and a file called 'dsound.dll'. Extract those two to your Cave Story directory (so mods and dsound.dll are in the same folder as Doukutsu.exe).

And you're done! Be sure to configure mods.txt in the mods folder!

Download
Source code and binaries

 

It wasn't very long ago that I figured out how to make Freeware Cave Story run at 60FPS, only to find someone had beat me to the punch. Hopefully, that isn't the case this time.

buddy, i've got some bad news for you..

 

Seriously? So much for Google being helpful.

 

Seriously? So much for Google being helpful.

well to be fair the fellow who made it is a tad uh.. unorthodox... and even I don't fully know where to find the most recent version of it. But someone made like, a program to inject LUA and hijack TSC/NPC behaviour and one of the submissions from the 2016 modding contest uses it to play Vorbis files for voice acting.

yours is probably easier to apply and configure i'd imagine.

 

I tried this, and edited the exe as instructed. It works and can hear the OGG music in place of the original music.

HOWEVER, when I exit Cave Story, my computer got the BLUE SCREEN OF DEATH.

ATTEMPTED_EXECUTE_OF_NOEXECUTE_MEMORY (0x000000FC) Parameters vary.

This is detrimental to the kernel. I suggest you NOT try this mod at all.

Confirmed: It BSOD'd TWICE on me.
OS Name Microsoft Windows 10 Pro
Version 10.0.14393 Build 14393
ntoskrnl.exe

1/27: FIXED using a replacement hex found in the tenth post. The SYSTEM_SERVICE_EXCEPTION was to be resolved on my end by rolling back the NVIDIA driver.

 

Strange. The only noexecute code I used was the DLL loader, and that got relocated to the text segment before I released it anyway. I know it'd be a pain to test, but does that occur if the a.dll file is removed? Sorry to have to ask, but it doesn't look like any of my PCs support NoExecute. That or I can't reproduce the crash.

 

Everything was in place. The a.dll was in the same folder where doukutsu.exe is executed. I have followed all instructions from your first post.

 

Yes, but if the error occurs even with the a.dll file removed, that means the crash could have only been caused by the loader, which would really help narrow-down the search for the cause.

 

Right.

I removed a.dll and... it functions like plain old Cave Story, original music. No system crash on exit.

Without a.dll, it will not play OGGs in its place. With it, it will play OGGs but will cause a system crash on exit.

Looks like the culprit is a.dll.

 

Oh dear, that just raises more questions... There are three parts of the loader that could be wrong, and that only proved one of them was working. The other two would be getting the loader to not find the DLL's main function, and also making it load a function that doesn't do anything. Failing that, it could be that one of the DLL's patches are bad, but the only way to find out is through trial and error. If I can ask your help again, could you put a.dll back with the EXE, and then hex-edit the EXE so that the 0xB0 bytes at 0x112E0 are this:

31 C0 40 C3 55 8B EC 68 0F 13 41 00 FF 15 AC C0 48 00 85 C0 74 12 68 15 13 41 00 50 FF 15 34 C1 48 00 85 C0 74 02 FF D0 A1 20 8B 49 00 5D C3 61 2E 64 6C 6C 00 64 65 61 64 00 CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC

If that worked, could you try again with those bytes set to this?

31 C0 40 C3 55 8B EC 68 0F 13 41 00 FF 15 AC C0 48 00 85 C0 74 12 68 15 13 41 00 50 FF 15 34 C1 48 00 85 C0 74 02 FF D0 A1 20 8B 49 00 5D C3 61 2E 64 6C 6C 00 69 6E 69 74 00 CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC CC

Sorry about all this. If it's too much work, there's one last PC I haven't tried that might support NoEx, and I'm sure a few guys I know can help with this as well.

 

The first hex-edit: No effect, played like plain-old Cave Story. Original Music. No system crash on exit.

The second hex-edit: Plays OGG files. STILL caused BSOD. This time it is SYSTEM_SERVICE_EXCEPTION (0x0000003B) caused by ntoskrnl.exe.


And I don't know about this. Sometimes, it is bugging up the Audio Driver and it might be involved: nvhda64v.sys. I am using an NVIDIA audio driver to an Acer UT220HQL Monitor using HDMI. The latest driver.

 

Is a.dll maybe 64-bit instead of 32-bit? What about the other dlls?

 

Oh, seeming that this post from the admin was up, I forgot to tell @Clownacy that for the record my OS where I am tesing this mod is 64-bit.

However I do not know about the dll files yet, that's for @Clownacy to answer...

---

All right. I will post my findings here for the SYSTEM_SERVICE_EXCEPTION and yes, nvhda64v.sys is causing it this time.

It is the latest NVIDIA driver and the use of Full Screen on Cave Story is doing this. Somehow, running a vanilla Cave Story and closing it, it takes away a Playback Device "Acer UT220HQL-1" and switches to the other called "Speakers". I lose the monitor's HDMI speakers. I had to uninstall and reinstall devices via Device Manager.

The BSOD with SYSTEM_SERVICE_EXCEPTION occurs when I exit the modded Cave Story in Full Screen.

I may need to Roll Back my NVIDIA drivers to the December version and see if it does not happen again. (If it does, I hate doing this but I may need to Reset Windows 10.)

 

Oh, seeming that this post from the admin was up, I forgot to tell @Clownacy that for the record my OS where I am tesing this mod is 64-bit.

I have a name you know. -_-

I meant more the fact that these dll files are being loaded by a 32-bit executable.

 

I have a name you know. -_-

I meant more the fact that these dll files are being loaded by a 32-bit executable.

I apologize and understood, andwhy.

My response ends here at this line.

---

So, I rolled back to the December version of NVIDIA (376.33 December 14, 2016). It now does not take away my "Acer UT220HQL-1" HDMI device upon quitting Full-Screen Cave Story. (stresstested by running and exiting). The modded Cave Story for OGG playback now no longer causes anymore BSODs!

Seeing that it was actually a problem on my end, I am going to the NVIDIA website to take this issue of "Running games in Full-Screen" and see if there is a like-issue.

 

The DLL is 32-bit. MinGW-w64, despite its name, can produce 32-bit binaries. All the other DLLs are 32-bit too, otherwise they wouldn't run on my 32-bit Windows installations.

So it was a driver bug all along? I don't think I'd have ever guessed that... Thanks for putting up with this for the past who-knows-how-many hours. I can't imagine repeatedly blue-screening your PC for some mod was at all enjoyable.

 

Seeing that it was actually a problem on my end, I am going to the NVIDIA website to take this issue of "Running games in Full-Screen" and see if there is a like-issue.

It could also be a problem with the resolution change, since Cave Story temporarily forces the computer's resolution to 640x480 while it is active and in fullscreen mode. I don't think many fullscreen games these days force a resolution change, so you may need to look that up as well.

 

So here's an update. I expanded the Ogg mod's DLL system into a mod loader: what used to be a.dll is now mod_loader.dll, which loads various other DLLs placed in the new mods folder. The Ogg mod has been split into one such DLL file. In fact, there are now two of them: new to this mod is support for Cave Story 3D's soundtrack (which, like the WiiWare soundtrack, relies on the Ogg files from Cave Story+).

But before I go into that, I should probably explain the new layout. The goal with this new version is to keep the base Cave Story directory as clean as possible: no more dependency DLLs just floating around the place. Rather, your Doukutsu.exe is accompanied only by mod_loader.dll and the new mods folder. The mods folder is where all the fun stuff is.

The mod loader also supports user configuration: along with the usual mod DLLs is a mods.txt file. Inside this text file, you list the filenames of each mod you want to load. Supplied with the loader are three example mods, which are enabled by default: the aforementioned Ogg music mods, a 60FPS patch, and a WASD remap. Mods are loaded in order from top to bottom, meaning, if you list both Ogg music mods in mods.txt, then the one at the bottom will ultimately take effect, overwriting the one nearest the top.

DLLs the mods depend on, like SDL2 for the Ogg mod, go in a deps folder within the mods folder. Again, this helps to keep the place clean, and not get users confused over which DLLs are actually mods, or just files used by mods.

Now, I've lurked for a while, but I'm still the newcomer here. The way I see it, you guys typically program in ASM? I'm no stranger to the language myself - working with the Mega Drive for the past few years has made me learn two ASM languages, in fact - but this loader should provide a comfortable way to write large portions of your code in C, and even C++. If you look at the example mods, the process goes that when a mod initialises, it inserts hooks into the Cave Story EXE in memory by redirecting calls and jumps, pointing them to C functions. The WASD mod hijacks the keyboard input portions of the WindowProcedure function this way, as does the Ogg mod when it hijacks the music playback functions. Anyway, I probably shouldn't dwell on this too long, and it doesn't look like this is the first time this kind of thing's been brought up. Not trying to start a language war, here.

Back to the Ogg music mod - like in Cave Story+, the 3D soundtrack files go in data/Ogg11. In addition, if you do forget to include the appropriate music files, the mod now falls-back on the original Org music. No more silence.

The WASD mod doesn't map exactly to the original WASD mod. In fact, a goal of this mini-mod is to enable players to use keys that hex-editing the EXE would never allow: the keypress code at 0x12E5C limits the virtual-key codes to 0x10-0xAF, making the use of such keys as '[' virtually impossible, at least by the means the original WASD mod employs.

Anyway, quick reference for the WASD layout:

• O - Shoot
• P - Jump
• [ - Inventory
• ] - Map
• 9 - Previous weapon
• 0 - Next weapon

The 60FPS mod really isn't worth talking about. I suppose it's good as a straight-to-the-point example of how to use the mod loader to patch the EXE, since all it does is change two bytes.

In the event the mod loader encounters an error while trying to load another mod's DLL, an error.txt will be created in the mods folder, telling you what went wrong.

Anyway, I might look into improving the Ogg mod so event jingles don't restart the level music. Maybe make the music list configurable via a TXT file instead of requiring you edit the mod's source code. If you have any suggestions, feel free to let me know. The main post is updated with installation instructions.

 

Now all we need is a python modding system and then I'll be set.

 

I fixed a glaring bug in the Org fallback feature, and got Org11 lastbtl to work properly (that's what I get for not playtesting enough).

New mod: I decided to try out my PS3 controller (using SCPToolKit drivers), and was only able to control Quote with the analogue stick, not the D-Pad. In my outrage, I rewrote the controller system. Once again, this uses SDL2.

Controls:

• D-Pad - Movement
• A / Cross - Jump
• X / Square - Shoot
• Y / Triangle - Previous weapon
• B / Circle - Next weapon
• LB / L1 - Previous weapon
• RB / R1 - Next weapon
• Start - Inventory
• Back / Select - Map

You still need to enable gamepads in DoConfig to use this. Unlike the old system, this doesn't totally disable the keyboard controls.

EDIT: And now there're also mods for the unused Ikachan mouse cursor, and the Debug Save menu.