Final Fantasy Addon Packs

NB! This is a document written for the members of the project.  If nothing here makes sense to you then just don't care about it.

Updated July 8, 2003.

Final Fantasy Addon Packs is my homegrown file format for distributing (surprise!) addons for Final Fantasy. The purpose of such packages is that it makes it much easier to patch/update the soundfonts and install the SGT files. The keyword here is "user friendliness".

The addon packs is stored in "*.FFAddon" files. They are little more than RAR archives with a different extension and some special setup files inside. Note that at this time, RAR files created with new versions of WinRAR cannot be used. Here is an older version of WinRAR that creates RAR files compatible with this utility. Upon installation, all the files in the archive is extracted to a folder on the users harddisk created for this purpose during the installation of Final Fantasy Configurator 2.

package.ini

This is the file that describes the package. It can (and should in most cases) reside in the RAR archive. When extracted, the file is simply merged into packages.ini and deleted.

Example of package.ini:

[Soundfonts]
Jared_SF=Jared Bernal's soundfont v 1.0

[Musicsets]
Jared_SGT=Jared's SF-compatible SGTs

[Jared_SF]
Path=Jared\FF8Custom.SF2

[Jared_SGT]
023s-Parade.sgt=Jared\023s-Parade.sgt

In the "Soundfonts" and "Musicsets" sections all the soundfonts and SGT collections in the package is listed up. You can see that the names used ("Jared_SF" and "Jared_SGT") is used as section names later on.

Currently, the only valid key in the soundfonts sections is "Path", where you specify the name of the soundfont. All path names in this ini-file is relative to the addon pack dedicated folder, unless a full path is specified (like "C:\Prog..."). The SGT sections on the other hand have no pre-defined keys, but instead is a mapping table. The left side contains the song that FF8PC tries to load, and the right side specifies the substitute. Paths on the right side is again relative to the addon pack folder, which means that in the example above Final Fantasy VIII\data\music\dmusic\023s-Parade.sgt is substituted with (addon path)\023s-Parade.sgt. Note that no actual replacing is happening, instead the configurator program replaces some pieces of DirectX to change SGTs. Final Fantasy just loads the SGT directly from the addon path.

setup.ini

This file is for the options only used during the installation process. This is a piece I'm still working on, so expect the format to change. Here's an example of an update package:

[Options]
Readme=Jared\ReadMe.txt
[Diff]
1.1_to_1.21=Update from 1.1 to 1.21
[1.1_to_1.21]
SourceFile=Jared\FF8Custom_11.SF2
DestFile=Jared\FF8Custom_121.SF2
DiffFile=Jared\Jared_11to121.DIF
BufSize=16000
DeleteOld=1

In this case one could supply a package.ini containing references to FF8Custom_121.SF2, which would allow the user to switch between the two versions (Jari should go with this solution). One could write DestFile=FF8Custom.SF2 instead and don't supply a package.ini, which would result in a transparent update.

BufSize is the buffer needed for the DIF file in kB, which is specified when creating the DIF file with PatchMaker. The default value is 8 MB (= 8192 kB), so buffers smaller than or equal to 8 MB don't need that parameter. NB! The buffer does not have to be the same size as used in PatchMaker, it can be larger too. I don't see any practical uses for this though.

DeleteOld specifies if the old file should be deleted after patching. 1 means delete the old file, 0 or omitted means leave it. If SourceFile and DestFile is equal, specifying 0 will cause a backup to be made (FF8Custom.SF2 -> FF8Custom_backup0.SF2).

Since any other files than package.ini, setup.ini and the DIF files is left on disk, you can supply as many information files you want, though only the one in the Readme parameter will be shown during package inSince any other files than package.ini, setup.ini and the DIF files is left on disk, you can supply as many information files you want, though only the one in the Readme parameter will be shown during package installation. The Readme parameter is optional.

Guidelines

To prevent making a mess of the user's addon-package folder I suggest everyone create a dedicated sub-folder for their soundfonts as done in the example. Just remember that the paths must be stored in the RAR file, whereas the ini-files must be located in the root of the RAR archive. If you don't create your own directory for your soundfont then remember to rename Readme.txt to something more descriptive and give the SGTs other names (for instance 023s-Parade.sgt=023j-Parade.sgt) to avoid different packages conflicting.

On the question whether or not to keep multiple versions when patching just take Jari and Jared's soundfonts as an example. Since Jari's two different versions serves different purposes and should not delete older versions when patching, while Jared's versions only serves as improvements over older versions and should delete the old version when patching. 

Do not ever start a path with \ (example: 023s-Parade.sgt=\Jared\023s-Parade.sgt) in the ini-files. It would result in "\\" in the path used by the program, which is not a good thing. Absolute paths is also not allowed (example: 023s-Parade.sgt=C:\Jared\023s-Parade.sgt) in packages even if it is allowed in the ini-files. I wouldn't let you patch files in C:\Windows, would I? ;-)

Other stuff

In the examples above I have used a SF2 as an example. DLS and SFPack is also possible. In fact I recommend you to use SFPack instead of SF2, as both downloads and patches becomes smaller then. FF Configurator automatically uncompress SFPacks as needed, so there is really no need to think about SF2s (The whole SF2 loading thing actually proved impossible, Creative only allow it's own product to load to bank 000. Which means users have to manually uncompress and load SFPacks...) 

This is the final format used for FFConfigurator version 2. To make patches you need version 1.2 of PatchMaker, which is able to create non-executable DIF files.