Editing Custom files

A new mechanism for implementing custom textures was introduced with the May 12th, 2022 DLL update. 

==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 <code>ItemTextureEP4.afs</code> or <code>ItemModelEP4.afs</code> 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. 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 <code>C:\EphineaPSO</code>. The folder structure is then
<pre>
C:\EphineaPSO\data\ephinea
C:\EphineaPSO\data\ephinea\custom\model
C:\EphineaPSO\data\ephinea\custom\texture
C:\EphineaPSO\data\ephinea\default\model
C:\EphineaPSO\data\ephinea\default\texture
</pre>

The folder structure under <code>C:\EphineaPSO\data\ephinea\default</code> 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.
<pre>
# 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\texture\File 393.prs
C:\EphineaPSO\data\ephinea\default\texture\File 393.prs
C:\EphineaPSO\data\ItemTextureEP4.afs   # and then retrieves File 393.prs
</pre>

There is a caveat that the files that '''can''' be loaded are cached during the login process for performance. 

==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 <code>ItemTextureEP4.afs</code> that is being overridden by a file in <code>C:\EphineaPSO\data\ephinea\default\texture</code>, then you have two options. 
# Using the default texture as a base, recreate your custom texture. This will maintain the correct cache ID.
# Open the .afs using TextureManager and export the images as .xvr. You can then hex edit the PSO ID in the .xvr files to match the ones from the default texture file to maintain the ID collision fixes. The PSO ID is 4 bytes long at offset 0x10 in the .xvr file.

==Provided default files==
Currently, the Ephinea launcher provides these files in the default folder.
<pre>
data\ephinea\default\bullets.xvm
data\ephinea\default\texture\File 232.prs
data\ephinea\default\texture\File 351.prs
data\ephinea\default\texture\File 393.prs
data\ephinea\default\texture\File 445.prs
</pre>

The <code>bullets.xvm</code> 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.

<code>File 232.prs</code> is the Tyrell's Parasol weapon texture to fix the collision with its tekker image in ItemKTEP4.afs. 

<code>File 351.prs</code> is Devil's Tail's item texture.

<code>File 393.prs</code> is the texture used by Purple Ring and Red Ring* with Purple Paint applied.

<code>File 445.prs</code> is the texture used by Dark Flow* for the Heart of Daisy Chain skin. This texture removes the yellow from the photon blade which allows the photon coloring to work.

==Other supported files==
Some custom HUDs modify the texturejapanese.xvm file because this file has the images for the numbers and letters used by the HUD. However, this file is a localized asset and the Ephinea launcher will download it when the launcher is set to English or Japanese in the top right corner. 

If texturejapanese.xvm is the reason a player is using Custom as their selected launcher language, the file can be placed in the custom folder and the client will load it. The launcher language can be reverted back to English or Japanese in this case.
<pre>
data\ephinea\custom\texturejapanese.xvm
</pre>