AFS Explorer v3.70 --- Documentation

http://dte-ng.issextreme.net http://www.issextreme.net/forums

AFS EXPLORER v3.70

1. DESCRIPTION
2. CHANGES
3. IMPORTANT NOTES
4. MENU DESCRIPTION
5. ACKNOWLEDGEMENTS

DESCRIPTION

This software allows managing the AFS files, which act as a container for multiple files (e.g. graphics, sounds, etc...) under its specific file-system structure.
With AFSExplorer you can manage those files, replacing or editing them with AFSExplorer's built-in functions or via independent external plug-ins.
There are plug-ins available for e.g. editing STR, SPF or ADX files. Plug-ins code is also available so anyone can customize them or even create their own plug-ins.

Appart from these basic functions for handling AFS files, the application includes some non-AFS related extensions:
- ZLIB-compressed files analysis and handling tool. You can (un)compress and (de)crypt files in the AFS.
- Renderware graphics support (as those found e.g in Grand Thieft Auto or Winning Eleven/Pro Evolution Soccer series). You can insert/extract graphics into any supported file in the AFS.
- SPF, ADX, CES and WAV sound player. You can play any sound file in the AFS.
This application also allows the creation and usage of AFP patches, which contain file content targeted to be applied on AFS file and replace its files.
These patches have a lesser dependence of AFS structure than PPF patches, having an optimal space usage, and thus are better suited to be used on AFS files.

You have at your disposal many other functions such as file name edition, support to ISO CD/DVD images, etc...

This application is designed to work under Win32 platforms, and has been tested to work under all avalaible 32-bit Windows OSs.

CHANGES

From version 3.6 to version 3.7 | - Added support to Winning Eleven 9 & Pro Evolution Soccer 5 (PSX2, PC and XBOX) graphic files.
- Added support to CD images (2048 sector size only).
- Some minor enhancements.

IMPORTANT NOTES

TIPS
* In the main window:
- Reserved spaces displayed in green means the reserved space has been marked with a new value for rebuilding.
- File lengths displayed in green means file is using more reserved space than it really needs (unused space).
- File lengths displayed in yellow means that the length of the file given at the headers is not coherent with the length given at descriptors..
- Dragging a file from other app to the file list imports it.
(Just as in Windows Explorer:)
- Press right mouse button over a file or folder to open a contextual menu with appropiate options.
- Double-clicking a file opens the file with the appropriate program or plays a sound, depending on the file type. Pressing F11 allows selecting any application for opening a file.
- Slowly double-clicking over a file name allows editing its name.
* In the graphic preview window:
- Press left mouse button while you move the mouse to scroll the picture. If 'Stretch images' config option is set, this feature is not available (there's no need).
- Pressing right mouse button over an image opens a pop-up menu allowing to import/export BMP files.
- Double click over any entry in the list to open the image with pre-selected graphic editor.

* In the AFS rebuilding window:
- Press '+' and '-' keypad buttons to increase/decrease reserved space for a file.
- Press right mouse button over a file or folder to open a contextual menu with appropiate options. 'Adjust childs' sets the slots of the selected entry and his brothers (and also their sons) to the minimum value needed to store the files (minimizes space).

* In the AFP patch creation window:
- Pressing right mouse button toggles the selection/deselection of all children, in function of parent selection status.
- Use 'Compare AFS'->'Select different files' to quickly create a patch. This allows creating a patch that only holds those files that differ between the loaded AFS and any external AFS. Take care, as the content of the patch will be fetch from the currently loaded AFS file.
* In the ZLIB Manager window:
- Double-clicking a ZLIB section uncompresses the section and then processes it with ZLIB Manager.
- Double-clicking a data section opens it with the pre-configured hexadecimal editor.
- You can use 'Get from AFS' and 'Insert into AFS' to quickly exchange files within the AFS without the need of extracting them first.

FILE INSERTION AND REGENERATION OF AFS FILES

Important: When you first load an original AFS file, load it using "auto-detection" mode. If you are asked to do so (e.g. descriptors are missing), let AFSExplorer auto-regenerate the AFS file. Use that rebuilt AFS file afterwards.
Due to the nature of AFS files, where files are stored sequentally and in 2048-bytes-long blocks, there are some limitations when working with them:
Files have a reserved space within AFS files -called from hereafter "slots"- and its content is stored in sucessive blocks.
Replacing a file with new one whose length is greater than the allocated slot would imply overwriting content of next file in the AFS.

AFSExplorer allows over-passing this limitation using two approaches:
- modifying assigned slots for all files, so bigger files can be inserted or to save space wasted by any file. This process, called "regeneration" or "rebuilding" creates a new AFS file keeping files content of original AFS file.
- if there is enough free sectors in other files in the AFS, AFSExplorer offers the option of re-arranging the AFS structure so this unused space can be given to the inserted file. This could be seens as a partial regeneration of the file, with the advantage of working on the same file and thus not needing to create a new AFS file.
When importing folders (and patches), AFSExplorer will calculate changes needed in the AFS structure and ask for regenerating it if it can be optimized or if rebuilding is required to allocate more space for those files.

Regeneration of AFS files is a resource-consuming operation, so it can take long, specially when dealing with big AFS files in low-performance computers. Avoid working with AFS files from CD/DVD units as their access times are far greater than those of hard disk units.
AFS VARIANTS

There are basically two AFS types, whose difference mainly resides in the later (v2) missing of a proper information about file lengths in a zone called 'descriptors'.
AFSExplorer uses descriptors as the base where to get file info from, as this allows more flexibility and also meets the goal of keeping compatibility.
Some games/apps using AFSs do not tolerate small values in the other place where file length is told (in the 'headers'); so it's better using descriptors (which do not have the former restriction) to compute the real length of files, as this allows inserting small files
Best thing you can do when working the first time with an AFS file is loading it using the 'auto-detection' mode (have a look at the configurations options of AFSExplorer). The tool will do its best to load the file in the safest way, and prompt you with the actions you should take to correct it if any incoherency is found.
Updating an AFS file (write AFS structure info back to the AFS file) and regenerating it (write a new AFS file from the scratch) will be the most common operations you'll have to deal with.
Please note, some other AFS handling software do not handle descriptors in a correct way or they simply ignore it. Usage of 'manual' loading mode with 'ignore descriptor's length' option enabled will allow you to correctly load those files, which must be corrected afterwards by updating or rebuilding it.
Once corrected, this AFS file can (and should) be loaded with 'auto' mode again.
In the case of AFS files missing descriptors (they simply do not have them in the file), AFSExplorer will use the default names 'unnamed_XXX', guessing the file extension depending on the files first 4 bytes (file identifier).
If you set 'Advanced extension detection' not only the file identifier will be checked but also the content of the file, but at the cost of a slower AFS loading.
You should always rebuild files missing descriptors.
It can happen that an AFS file contains files that are also of the AFS format. By default, AFSExplorer will process those sub-AFS files and proccess their content. Use 'Custom detection' and deselect 'Sub-AFS processing' to avoid processing sub-AFS files content when loading.

TEMPORAL STORAGE

AFSExplorer makes use of temporal files for a wide variety of operations, such as graphic displaying, sound previewing or patch importing.

Those temporal files are created on default Window's temporal folder, which varies depending on the operating system.
To correctly operate, AFSExplorer needs the hard-disc partition where that temp folder is located to have enough free space.

This feature must be specially considered when importing a patch: as patch files are temporally extracted, it's very important you check there's at least enough free space at the operating system partition (or the place set as system's temporal storagement location) equal or greater than the patch size.
That's it: if a patch is 200MB long, at least 200MB of free space is needed so AFSExplorer can apply the patch.

AFP PATCHES
If you want to use AFP patches together with another PPF patches, apply first PPF patches then apply AFP patches.
Don't forget that a new AFS file is created when you apply a patch that modifies the reserved spaces of the patched AFS file, and the AFS file length changes.
Avoid including in AFP patches both a sub-AFS file and any of the files it contains. It's a waste of space.
AFP patches relies on AFS file names. You should provide AFL files containing the names of the files of the AFS file(s) you used to create the AFP patch file(s) from.
PLUG-INS

Plug-ins communicate with AFSExplorer using sockets (network resources) for optimal performance. Be sure you don't have any external software (such as firewalls or antivirus) blocking AFSExplorer attempts of using the network.

If you want to design a plug-in:
- download "PluginSupport" C++ class; this class includes not only all function calls to set-up and perform all communication (requests to and notifications from) notifiwith AFSExplorer but also other useful functions to create a plug-in (e.g. interface wrappers).
- have a look at the source of "PluginSupport" class as you'll find some basic info there. Also check the source of other available plug-ins to learn how most basic functions are used (you can use any of them as a base for a faster developing of your own plug-in too).
However, you can always ask at the forums in case of any doubt/trouble.
- avoid making a large number of plug-in support calls within a short lapse of time. TCP sockets are still alive for a given time (usually 2 minutes in Windows OSs) when they have been closed, thus system socket resources can starvate due to those 'ghost', previously-used sockets. In such an scenario, with hundreds of TCP sockets in TIME-WAIT state, AFSExplorer won't be able to communicate with plug-ins until those sockets have been really freed by the system.
Special functions have been designed to fetch large ammounts of data (e.g. all info about an AFS file) using a single request.
- requests to AFSExplorer requiring internal interface handling will make both the calling plug-in and AFSExplorer enter in a dead-lock state. Use separated threads when making those calls. Those dangerous calls are commented in the PluginSupport class; as a rule of thumb, if you find AFSExplorer hangs when making a call, use a thread because you'll probably be in this scenario ;)

If you design a plug-in please share it with the community! ;)

MENU DESCRIPTION

1. File
   1. Open File...
      Imports an AFS file.
   2. Update...
      Updates AFS structural data (headers and descriptors).
      Useful for fixing AFS v2 to behave as AFS v1 files.
   3. Import AFS file from CD image...
      Opens a CD/DVD image file and allows you to load any AFS file it contains.
      Note: only 2048-byte sector images are supported.
   4. Insert AFS file into CD image...
      Inserts currently loaded AFS file into any CD/DVD image file.
      IF THE FILE YOU ARE TRYING TO INSERT IS BIGGER THAN THE ONE YOU ARE TRYING TO REPLACE... YOU CAN REBUILD THE CD/DVD IMAGE! (experimental).
   5. Configuration...
      Options to configure the application.
   6. Recent files
      Here hangs a list of latest 10 files loaded in AFSExplorer.
   7. Exit
      Uhmm... what's this for? ;)
2. Action
   The options of this menu provide a way of modifying the files contained in the AFS file.
   1. Import file...
      Replaces the file selected (in "files" list).
      The imported file can't be greater than the currently selected file. In case the file is greater file won't be imported, but you'll be asked if you want to pre-adjust its reserved space, very useful to easier the regeneration of AFS files.
   2. Export file...
      Saves the file selected (in "files" list).
   3. Import folder...
      Replaces the files of the seleted directory (in "folders" tree) and its subdirectories.
      The files you import, and the subdirectories, must have the same name than the original ones.
      You'll only be notified when trying to import a file that is bigger than the original reserved space, or
      when you could save AFS space on case the file is smaller enough.
      It's NOT necessary to import all files, it will only import those matching the previous two requeriments.
   4. Export folder...
      Saves the files of the seleted directory (in "folders" tree) and its subdirectories.
   5. Search...
      Opens a dialog box that allows to search for next file whose name contains the introduced string.
      Only single words can be searched. There's no need to use character * as wildcard: a search for "general" is equivalent to "*general*".
   6. Find next
      Same than 'Search...', but looking for the last set search string.
   7. Open with...
      Opens the currently selected file with the choosen tool. You can set those tools at the configuration window.
3. Advanced
   Rooms some options that allow modifying the AFS structure.
   1. Modify reserved space...
      Opens a window that allows changing the reserved slot for each file.
   2. Import file name list...
      Updates name of files from a file list file.
      Don't forget to use "Update" function to physicaly update AFS file.
   3. Create file name list...
      Creates a file that contains all the file names in an AFS file.
      Note the exported file will only be applicable on AFS files having the same directory structure as the AFS the file was created from.
   4. Import patch...
      Loads an AFS patch.
      Don't forget that a NEW AFS file is created when you apply a patch and it modifies the reserved spaces of the patched AFS file.
   5. Create patch...
      Opens a window that allows selecting which files you want to include in the patch, and creates it.
      If you select a file being an AFS you should not select any of it sub-files, as those sub-files are already contained by that AFS file.
4. Advanced
   1. Graphic preview
      Toggles visibility of graphic preview window. If not visible, software won't try to load file selected in the file list, so it'll be faster.
   2. Sound player
      Toggles visibility of sound player window.
   3. ZLib manager
      Toggles visibility of zlib manager window.
5. Help
   Info about this software.
6. Plug-ins
   Allows showing/hidding plug-in windows

ACKNOWLEDGEMENTS

This software uses code from zlib v1.2.1 Copyright (c) 1995-2004 Jean-loup Gailly and Mark Adler This software uses AdxToWav() code Copyright (c) 2001 BERO Encryption algorithm (de)coding by RCE, WarpXavier and KsChoice The author would like to thank the following people: Alex, Antiz, Ataru-CrespoGol, Billy, Burgy, d4lton, El_Hacker, Eriol, Evilgab, Goku, Honome, Iori, JeffT, KOC2000, K0H, KsChoice, Mauras, Mephisto, MikeOM, RCE, Reefur, Rh4psody, ShinjiOno, Solidus J2k, TCrew, Txema7, Unreal & WarpXavier. And also to all the other people I've forgotten to mention (sorry if I've done so!)

------------ Tato

IMPORTANT: *** This software is designed for personal use *** *** You must own an original copy of the game to use this tool *** *** Use of copies is only allowed to those who own the original ***