NeoGF/afstool/README.md

# afstool.py
Python3 script for unpack/pack/rebuild AFS file format. Rebuild of Table of content (TOC) and Filename directory (FD) is possible with full controll of every parameters. MIT License.

## User manual
Unpack **source_afs.afs** in the default new folder _source_afs_.
If optional_dest_folder is specified we unpack in _optional_dest_folder_.
If the FD is present we use OS mtime to store the date of the file.
```
afstool.py --unpack source_afs.afs optional_dest_folder
```
Pack **source_folder** in the default new file _source_folder.afs_. If optional_dest_file.afs is specified we pack in _optional_dest_file.afs_. If the FD is present we use OS mtime to retrieve and update the date of the file. Pack handle max file size using next file (or sys file) offset. Without FD the last file has no max length constraint. FD Names stay inchanged by the pack command.
```
afstool.py --pack source_folder optional_dest_file.afs
```
Rebuild the AFS file system of an unpacked AFS using afs_rebuild.conf and afs_rebuild.csv. See afs_rebuild.conf below for more informations.
```
afstool.py --rebuild source_folder
```
Print stats about the AFS file or the unpacked AFS folder. Get full informations about header, TOC, FD, full memory mapping sorted by offsets (files and sys files), addresses space informations, and duplicated filenames grouped by filenames.
```
afstool.py --stats path
```

## Extracted file tree
**root** folder contains all files of the unpacked AFS

**sys** folder contains AFS system files and generated files needed for AFS operations:
* tableofcontent.bin - TOC sys file: You can edit this file it will be handled by the --pack command.
* filenamedirectory.bin - FD sys file: This file is created only if there is a FD in the AFS.
* filename_resolver.csv - Created when multiple files have the same name in the FD.
* afs_rebuild.conf - Edit this file for rebuilding the AFS.
* afs_rebuild.csv - Edit this file according to the configuration used in afs_rebuild.conf for rebuilding the AFS.

## filename_resolver.csv
Pack doesn't update the original FD names. This file is used during pack to auto detect unpacked renamed files in the '''root''' folder keeping their original index in the TOC (and FD) . This file is autogenerated when:
* there is a FD with duplicated filenames, extracted files with duplicated names use "filename **(N)**.ext" with N:Integer,
* there is no FD, files are named with their index, for instance: "00000000" for the first file.

Each lines of this csv contains a couple of "index/unpacked_filename". You can use it to rename unpacked files, for instance: "0/my_new_filename.ext".

## afs_rebuild.conf
All offsets and indexes are stored in hexadecimal with **0x** prefix: 0xabcdef. Use **auto** value when it's possible.

### \[Default\] section
**AFS_MAGIC**: 0x41465300 or 0x41465320

**files_rebuild_strategy**: auto, index, offset or mixed

**files_rebuild_strategy** is used to organise files (indexes, offsets, packed name if there is a FD) in the AFS. The strategy use informations in **afs_rebuild.csv** autogenerated during unpack. If the **root** file is not present in the **afs_rebuild.csv** then all value will be auto set. 4 strategies are available:
* **auto**: Auto-rebuild of all files indexes and offsets (using packed packed_filename if there is a FD). Indexes and offsets will be ignored.
* **index**: Keep the specified index for designated files (using packed packed_filename if there is a FD). afs_rebuild.csv offsets will be ignored.
* **offset**: Keep the specified offset for designated files (using packed packed_filename if there is a FD). afs_rebuild.csv indexes will be ignored.
* **mixed**: Keep the specified offsets and indexes (using packed packed_filename if there is a FD).

**filename_directory**: True when there is a FD and False when there is none. If set to True then it must have a \[FilenameDirectory\] section.

### \[FilenameDirectory\] section
**toc_offset_of_fd_offset**: The TOC offset of the FD offset is at the end of the TOC. Some AFS use pad after the offsets/lengths serie. Use auto when it's possible.

**fd_offset**: The FD is at the end of the AFS. Use auto when it's possible.

**fd_last_attribute_type**: The type of the last 4 bytes of each FD entries. 4 values are available:
* **length**: Use file length.
* **offset-length**: Use offset length series.
* **0xabcdef**: Use a custom hexadecimal constant.
* **unknown**: Don't know yet what it represent. Null value will be used.

## afs_rebuild.csv
**afs_rebuild.csv** contains entries describing how to pack '''root''' files in the AFS. All offsets and indexes values are stored in hexadecimal with **0x** prefix: 0xabcdef. Use **auto** value for offsets or indexes when it's possible. Offsets have to be aligned to 0x800 (2048). Put one line per selected file that you wan't to constraint using the format: "unpacked_filename/index/offset/packed_filename", for instance: "dummy (5).bin/0x12/0x80000/dummy.bin". You can put auto to index or offset: "dummy (5).bin/auto/auto/dummy.bin". For an empty block add only offset/length couple with values aligned to 0x800, for instance: "0x80000/0x5000".

When rebuilding, remove all files without constraints from '''afs_rebuild.csv'''. Then put '''auto''' value in indexes and offsets that doesn't have constraints. While rebuilding the AFS filename_resolver.csv will be removed but you can keep changes about filenames by adding entries with unpacked_filename+index (and packed_filename when there is a FD) into this file.