Metadata-Version: 2.4
Name: bullyfury
Version: 0.1.0
Summary: Python I/O toolkit for Bully: Scholarship Edition PC assets
Author: Codex
License: MIT
License-File: LICENSE
Keywords: bully,gamebryo,idb,img,ipb,nft,nif
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# bullyfury

`bullyfury` is a Python toolkit for reading and rebuilding Bully: Scholarship Edition
PC asset formats.

Current scope:

- `IMG` v1 archives (`.img` + `.dir`)
- `IDB` binary tables with lossless roundtrip support
- `IPB` binary map chunks with lossless roundtrip support
- `NFT`/`NIF` parsing with Bully texture extraction to `DDS`

The package is intentionally modular so each file format can evolve on its own.

## Current API

```python
from bullyfury import BullyColFile, IdbFile, ImgArchive, IpbFile, NifFile, NFTFile
from bullyfury import load_bully_collectibles, load_bully_text_keys
```

- `ImgArchive.read(...)` reads `.img` / `.dir` pairs and can rebuild archives.
- `IdbFile.read(...)` parses `IDB` headers and keeps binary roundtrip stable.
- `IpbFile.read(...)` parses `IPB` chunk layout and keeps binary roundtrip stable.
- `BullyColFile.read(...)` enumerates Bully `.col` submodels, exposes stable
  `object_id`, bounds, box collisions, compressed mesh geometry, and preserves
  the remaining payload losslessly.
- `NifFile.read(...)` parses the Gamebryo header, block table, Bully
  `NiSourceTexture` / `NiPixelData` blocks, and extracts supported textures to
  `DDS`.
- `NFTFile.read(...)` is the texture-oriented Bully alias/subtype over `NifFile`.
- `load_bully_collectibles()` and `load_bully_text_keys()` expose bundled
  Bully text resources copied from `fastman92_processor`.

## Notes

- `IMG v1` stores sizes in sectors, so exact unpadded file size is not always
  recoverable from existing archives.
- `IDB` and `IPB` parsing currently focuses on stable binary roundtrip and
  conservative structure discovery.
- Bully `.col` entries use `COL3` magic but do not match the stock GTA SA
  header layout exactly; `BullyColFile` handles the Bully-specific container
  shape while the copied generic `Col` parser remains available for classic
  GTA-era files.
- The Bully `.col` parser currently covers:
  - per-submodel `object_id`
  - local bounds
  - AABB box blocks
  - compressed mesh vertices and triangle faces
  - material IDs mapped to readable names for parsed face and box surfaces
  - `LIMK` face adjacency when present
  - unparsed tail records as raw bytes for future reverse engineering
- `NFT` extraction now supports Bully/Gamebryo `NiPixelData` textures in
  `RGB8`, `RGBA8`, `DXT1`, `DXT3`, and `DXT5_ALT` form.
- Palettised `NiPixelData` (`PX_FMT_PAL8`) is parsed, but `DDS` export is still
  pending for that variant.
