Custom files

A new mechanism for implementing custom models and textures was introduced with the May 12th, 2022 DLL update. Files from ItemModelEP4.afs and ItemTextureEP4.afs can be loaded directly using the new folder structure.

Overview

This new mechanism simplifies sharing custom textures and models with other players. The old method of implementing these files was to apply an AFP patch to ItemTextureEP4.afs or ItemModelEP4.afs using AFS Manager or another tool to open and modify AFS files.

The motivation for these changes was to provide fixes for some vanilla textures that have cache collisions without overwriting anyone's existing textures. A cache collision occurs when the "PSO ID" in the texture .dds or .xvr matches another texture. PSOBB considers these as the same texture and will use only the first one loaded.

Another motivation is to allow providing new files to extend existing functionality. For example, more photon bullet colors.

Folder structure

Suppose the client was installed at C:\EphineaPSO. The folder structure is then

C:\EphineaPSO\data\ephinea
C:\EphineaPSO\data\ephinea\custom\model
C:\EphineaPSO\data\ephinea\custom\custom
C:\EphineaPSO\data\ephinea\default\model
C:\EphineaPSO\data\ephinea\default\texture

The folder structure under C:\EphineaPSO\data\ephinea\default is for files provided by the launcher to fix cache ID issues with some textures.

Item loading

When an item is loaded by the client, the DLL will check for files in the above folders before opening the AFS files. The precedence is custom first, then default, and then the AFS files. Once a file is found, that file is loaded and no more files are tried for that model or texture.

For example, Guld Milla is defined as model 74 and texture 74 in the ItemPMT. These values match the files inside the AFS files. When someone in the party equips Guld Milla, the client will look for "File 74.prs" in the model folders, and then "File 74.prs" in the texture folders.

Another example is Purple Ring or Red Ring* with the Purple Paint applied. These items use model 369 and texture 393. When the item is equipped by a member of the party, the client will look for these files.

# Model file
C:\EphineaPSO\data\ephinea\custom\model\File 369.prs
C:\EphineaPSO\data\ephinea\default\model\File 369.prs
C:\EphineaPSO\data\ItemModelEP4.afs   # and then retrieves File 369.prs

# Texture file
C:\EphineaPSO\data\ephinea\custom\model\File 393.prs
C:\EphineaPSO\data\ephinea\default\model\File 393.prs
C:\EphineaPSO\data\ItemModelEP4.afs   # and then retrieves File 393.prs

There is a caveat that the files allowed for loading in the custom and default folders are cached during the login process. If a new file is added while already logged in, the client must go through the login process again to add that file to the cache of custom and default files.

Migrating custom files

Generally, your existing AFS files can stay as they are. Only a handful of texture files will be provided by the Ephinea launcher.

If you would like to separate some custom files out of the AFS file, then you should export the file as a PRS file using AFS Manager. The file should be named "File <x>.prs" where <x> is the number of the file.

If you have a custom file in your ItemTextureEP4.afs that is being overridden by a file in C:\EphineaPSO\data\ephinea\default\texture, then you have two options.

1. Using the default texture as a base, recreate your custom texture. This will maintain the correct cache ID.
2. Open the .afs using TextureManager and export the images as .dds. You can then hex edit the PSO ID in the .dds files to match the ones from the default texture file to maintain the ID collision fixes.

Provided default files

Currently, the Ephinea launcher provides these files in the default folder.

data\ephinea\default\bullets.xvm
data\ephinea\default\texture\File 351.prs
data\ephinea\default\texture\File 393.prs

The bullets.xvm file provides textures for photon bullets to match all photon colors in the ItemPMT. This file allows the nonrare ranged weapons specific to Ultimate Challenge Mode to have matching photon bullets.