bgK/myst3-hd-modding.md Secret

## myst3-hd-modding.md

      
    Raw
  

              myst3-hd-modding.md
            
          
    Introduction

ResidualVM is gaining the ability to create mods for Myst III. It is possible to replace the original game assets with hi-resolution versions. This combined with the emergence of machine learning image upscaling tools enables the creation of a hi-resolution mod for Myst III.
I am releasing here a version of ResidualVM usable to create and play such a mod. However, graphics processing is not my forte. I need help from the community to figure out how to upscale the original assets to produce the best visuals and to put together a mod.
A HD mod has already been successfully completed for The Longuest Journey, another game supported by ResidualVM: https://tljhd.github.io/. Hopefully the the same feat can be replicated with the same quality for Myst III.
Example mod

I am providing here a proof of concept mod I've used to test the programming changes. This example mod is not meant to be pretty, nor to be used by regular players. It is not representative of the visual quality the final mod might have. It contains an upscaled version of most of the exterior of the J'nanin age and the English journals. It is meant to be used with the DVD version of the game.
Screenshots:

http://www.framecompare.com/image-compare/screenshotcomparison/7YWW7NNX
http://www.framecompare.com/image-compare/screenshotcomparison/9100JNNU#

Downloads:

ResidualVM HD v5 (built from this branch https://github.com/bgK/residualvm/tree/stable):

Windows (i686): residualvm-myst3-hd-mod-windows-v6.zip
macOS (x86_64 + arm64): residualvm-myst3-hd-mod-macos-v6.zip
Linux (x86_64): residualvm-myst3-hd-mod-linux-v6.tar.xz


Example mod: https://drive.google.com/uc?export=download&id=1RcxCRz8isJF-Lh3HVTlKzKxwX-64Xl_2

To try the mod, set ResidualVM up to play Myst III (https://github.com/residualvm/residualvm#4-running-myst-iii). Then uncompress the mod archive in the game folder, so the mods directory is at the same level as the Data and M3Data directories. Then run the game using the ResidualVM version from this post.
Modding guide

In this section I will succinctly explain how to create a simple mod. You can contact me for more details (by private message here or on the #myst IRC channel on libera.chat).
The first step is to configure ResidualVM for modding. Open the residualvm.ini file and perform the following changes (https://github.com/residualvm/residualvm#61-location-of-configuration-file):

Add enable_external_assets=true in your existing myst3 target section. This will cause ResidualVM to prefer loading files outside of the game archives.
Add debugflags=modding in the [residualvm] section. This will make ResidualVM to print the names of the external files it tries to open.

Next, extract the game archives to access the assets. To do so, open Myst III in ResidualVM, open the debug console using the ctrl-d keyboard shortcut and enter the dumpArchive LEISnodes.m3a command. This will create a dump folder containing the assets for the J'nanin exterior in the ResidualVM folder.
There are a lot of files. You can use the log output of ResidualVM to match the files to their in-game use.
ResidualVM will now load the files from the dump directory instead of from the game archives if it can find them. It will look for files with the following extension in that order: .dds, .png, .jpg. This means it's possible to experiment very quickly. Modify the extracted files, go to the corresponding location in game and observe the changes.
Next the modded assets need to be prepared for packing. PNG files are fine to experiment with but are not suitable for distribution as they are bulky and slow to load. ResidualVM expects the images to be in DDS format to prepare the mod for distribution. It accepts uncompressed, BC1, BC2, BC3 and BC7 compressed DDS files.
For the example mod, I've used the following process:

JPEG artifact removal using https://github.com/ilyakurdyukov/jpeg-quantsmooth
Upscaling using ESRGAN with the 4xBox model (https://drive.google.com/file/d/1KToK9mOz05wgxeMaWj9XFLOE4cnvo40D/view?usp=sharing)
Downscaling to 2048px using ImageMagick so the files are not too large
DDS BC1 conversion using https://github.com/richgel999/bc7enc

Next the prepared assets can be packed into a mod archive. Open Myst III in ResidualVM and enter the modArchive LEISnodes.m3a command. This will pack the modified files from the dump directory into a LEISnodes.m3a.patch file created in the ResidualVM folder. This command takes a long time to run as it compresses some of the files. You can disable the compression to experiment quickly using the modArchive LEISnodes.m3a false command.
Finally, the mod is ready to be tested and distributed. Place the mod archive in a directory corresponding to the mod name in the mods directory in the game directory. Set enable_external_assets to false in residualvm.ini so the files are loaded from the mod archive instead of the dump folder.
The same process can be used to mod the following asset types:

Bink videos (The example mod replaces two of the Squee videos)
Cursors (Bitmap files in RSRC.m3r)
Inventory and font used in the load and save menus (.data files in RSRC.m3r, open as raw with The Gimp)

Note that there are some limitations:

The mod archives are limited to 4 GB. Generate multiple archives to work around the limitation.
Some of the videos will not display at the correct scale when they are loaded from the dump directory. They should play correctly once packed.
I have probably left behind a number of bugs :) Report them to me so I can fix them.