bullyfury 0.1.2

Python I/O toolkit for Bully: Scholarship Edition PC assets

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
• GRIDS.DAT pedestrian/vehicle route networks
• 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

from bullyfury import BullyColFile, GridsDat, 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.
• GridsDat.read(...) parses GRIDS.DAT pedestrian and car navigation graphs and can serialize them back to text.
• grids_to_dict(...), grids_to_json(...), and write_grids_json(...) export a normalized node/link document with explicit node_id and link_id values for downstream tools.
• 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.
• NifFile.material_bindings exposes geometry-to-material bindings with base_texture, normal_texture, gloss_texture, specular_color, and glossiness when present in NiTexturingProperty / NiMaterialProperty / NiSpecularProperty.
• 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.

GRIDS Export

from bullyfury import GridsDat, grids_to_json

grids = GridsDat.read(r"C:\Program Files (x86)\Steam\steamapps\common\Bully Scholarship Edition\Config\GRIDS.DAT")
json_text = grids_to_json(grids)

The normalized export includes:

• top-level header counts
• every section (PEDGRID, CARGRID)
• every node with explicit node_id
• every link with explicit link_id
• node flags, width, speed, density, and attached link_ids
• link src, dest, dist, lanes, and width