fourfury 0.2.1__tar.gz

fourfury-0.2.1/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to `fourfury` are documented in this file.
+
+The changelog is release-oriented and uses a small fixed set of categories:
+`Breaking Changes`, `Added`, `Changed`, `Fixed`, and `Performance`.
+
+## [Unreleased]
+
+## [0.2.1] - 2026-07-24
+
+### Added
+- Lossless GTA IV `water.dat` support with typed triangle and quad surfaces, runtime flags, spatial queries, validation, editing, and format-neutral mesh export.
+- Complete target-independent WFT fragment projection with common, undamaged, and damaged models, physical piece metadata, transforms, and primitive-data export.
+- Explicit WFT group hierarchy navigation, neutral group projection, and structured structural validation.
+
+### Changed
+- WFT fragment, group, and child flags now expose confidence metadata and preserve unnamed bits explicitly instead of presenting inferred meanings as verified GTA IV behavior.
+- WFT group flag bits now use canonical `UNKNOWN_BIT_*` names because their previous inferred meanings are not verified for GTA IV; the former names remain compatibility aliases.
+- WFT child flag bits now use canonical `UNKNOWN_BIT_*` names because neither CodeX nor the stock corpus establishes their semantics; the former speculative names remain compatibility aliases.
+- WFT fragment bit 2 now uses the canonical `UNKNOWN_BIT_2` name instead of the unverified `UNUSED` label.
+- WFT child drawables now inherit the common shader group when their serialized drawable omits one, while retaining the distinction in the public API.
+
+### Fixed
+- Windows native-extension builds no longer collide with the Win32 `max` macro.
+
+### Performance
+- WFT child drawables are decoded lazily, avoiding geometry and bound parsing when callers only inspect fragment physics.
+
+## [0.2.0] - 2026-07-24
+
+### Added
+- WAD animation-dictionary reading with animation names, hash lookup, flags, and track metadata.
+- Decoding for stock WAD channel encodings, with lossless inspection of unsupported encodings.
+- Frame evaluation, time-based sampling, and format-neutral targets, values, sparse frames, and interpolation.
+- Selected-track streaming and primitive-data export for format-independent animation consumers.
+- Semantic WAD track classification, structured validation, aggregate audits, and explicit custom track IDs.
+- Target-independent UV transforms, frames, clips, interpolation, and coordinate transformation.
+- UV-animation material-slot bindings and neutral WDR default UV transforms shared with the animation API.
+- Typed, editable IDE archetype views with named animation flags.
+- Target-independent skeletal transforms, poses, clips, and separately modeled mover/root-motion tracks.
+- Optional skeletal binding with hierarchy, skeleton signatures, bind-pose matrices, strict validation, and explicit unresolved targets.
+- Explicit MLO archetypes with typed entities, rooms, portals, bounds, time flags, cross-references, internal LOD parenting, and topology validation.
+- MLO hash registries, WPL placement resolution, and world-space entity, room, and portal projection.
+- Primitive-data export and lossless MLO editing through the original IDE records.
+- Lossless text IPL support with typed GTA IV occlusion boxes.
+- Named layered-terrain shader parameters and drawable-light flags.
+- Lightweight WBD dictionary-hash inspection.
+
+### Changed
+- Reorganized the monolithic WDR parser into the focused `fourfury.wdr` package while preserving its public API, type identities, pickle compatibility, and native-decoder patching.
+- WPL section 8 is now modeled explicitly as `WplMloPortal`, with `WplStrBig` retained as a compatibility alias.
+- WAD targets are modeled independently from their per-chunk encodings so converters can consume stable logical animation data.
+
+### Fixed
+- WAD track-group sampling respects the shared boundary frame between adjacent groups.
+- Stock UV-animation hashes and targets now follow their dictionary, material-slot, and UV-index conventions.
+- WAD skeletal targets remain stable across encoding changes, with normalized shortest-path quaternion interpolation.
+- WAD action-flags tracks are no longer misclassified as bone translations.
+- WAD packed integer sequences decode their unary prefix before the Rice remainder.
+
+### Performance
+- Bounded IMG resource scanning uses roughly 4× less peak memory, while cached logical sizes avoid repeated zlib scans.
+- Atomic streaming IMG and RPF writers use roughly 200× less peak memory when saving large archives.
+- Lazy WAD channel decoding makes large animation dictionaries roughly 40× faster to parse while using about 11× less peak memory.
+- Lazy WDR vertex decoding makes large drawables roughly 2.5× faster to parse while retaining about 1.5× less memory.
+- Indexed animation, skeleton, texture, and track lookups make repeated UV sampling up to 75× faster and texture lookup roughly 55× faster.
+
+## [0.1.0] - 2026-07-22
+
+### Added
+- Initial public release of FourFury for GTA IV asset workflows on Python 3.11 and newer.
+- RPF2, audio RPF3, and IMG3 archive reading and extraction, with creation and writing for RPF2 and IMG3.
+- IDE, WPL, GTXD, NOD, and WNV map-data APIs, including explicit LOD parenting and format-neutral path graphs.
+- RSC5 texture, drawable, fragment, and collision support through WTD, WDR, WDD, WFT, WBN, and WBD.
+- Format-neutral model projection, stock shader and collision-material catalogs, and optional native acceleration for common decoding paths.

fourfury-0.2.1/MANIFEST.in

@@ -0,0 +1 @@
+include CHANGELOG.md

fourfury-0.2.1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: fourfury
+Version: 0.2.1
+Summary: Python library for Grand Theft Auto IV archive formats.
+Author: fourfury contributors
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# FourFury
+
+FourFury is a Python library for reading, inspecting, extracting, and editing
+Grand Theft Auto IV data files. It provides typed APIs for the game's archives,
+world placements, collision resources, drawables, textures, navigation graphs,
+animation dictionaries, and related metadata.
+
+> [!IMPORTANT]
+> FourFury is under active development. Read support is broader than write support,
+> and some resource types intentionally permit only fixed-size edits.
+
+## Format support
+
+| Format | Read | Write | Notes |
+| --- | :---: | :---: | --- |
+| RPF2 | Yes | Yes | Search, extraction, creation, and unencrypted output |
+| RPF3 | Yes | No | Audio archives; hash-only names remain hexadecimal |
+| IMG3 | Yes | Yes | Search, extraction, creation, and resource padding handling |
+| IDE | Yes | Yes | Lossless definitions with explicit MLO entities, rooms, portals, and validation |
+| IPL | Yes | Yes | Lossless sectioned text with typed GTA IV OCCL boxes |
+| water.dat | Yes | Yes | Lossless water triangles and quads, runtime flags, geometry queries, and neutral mesh export |
+| WPL | Yes | Yes | Placements, MLO resolution, explicit LOD hierarchies, world portals, and instance flags |
+| GTXD | Yes | Yes | Texture-parent chains and cycle detection |
+| NOD | Yes | Yes | Navigation nodes, links, costs, and topology validation |
+| WNV | Yes | Limited | Navigation meshes, edges, cover points, and quadtrees |
+| WBN | Yes | Limited | Collision bounds and fixed-size edits |
+| WBD | Yes | Limited | Collision dictionaries and fixed-size edits |
+| WAD | Yes | No | Animation dictionaries, tracks, chunks, and decoded channels |
+| WDD | Yes | No | Hash-addressed drawable dictionaries and neutral model projection |
+| WDR | Yes | No | Drawables plus neutral model projection |
+| WFT | Yes | No | Fragment drawables, physics hierarchy, collision bounds, and complete neutral fragment projection |
+| WTD | Yes | No | Texture dictionaries and DDS export |
+
+See [DOCUMENTATION.md](DOCUMENTATION.md) for examples, field behavior, writer
+constraints, and current limitations.
+
+## Installation
+
+FourFury requires Python 3.11 or newer. Install it directly from GitHub:
+
+```powershell
+python -m pip install "fourfury @ git+https://github.com/Hancapo/fourfury.git"
+```
+
+For an editable installation:
+
+```powershell
+git clone https://github.com/Hancapo/fourfury.git
+cd fourfury
+python -m pip install -e .
+```
+
+## Quick start
+
+Open an archive and read one of its entries:
+
+```python
+from pathlib import Path
+
+from fourfury import RpfArchive
+
+game = Path(r"D:\Program Files (x86)\Steam\steamapps\common\Grand Theft Auto IV\GTAIV")
+
+with RpfArchive.from_path(game / "pc/data/game.rpf") as archive:
+    entry = archive.find_entry("data/taskparams.txt")
+    if entry is not None:
+        print(entry.read().decode("utf-8"))
+```
+
+## Documentation
+
+The [complete documentation](DOCUMENTATION.md) covers every supported format,
+resource APIs, neutral WDR models, editing constraints, and known limitations.
+
+Release notes live in [CHANGELOG.md](CHANGELOG.md).

fourfury-0.2.1/README.md

@@ -0,0 +1,75 @@
+# FourFury
+
+FourFury is a Python library for reading, inspecting, extracting, and editing
+Grand Theft Auto IV data files. It provides typed APIs for the game's archives,
+world placements, collision resources, drawables, textures, navigation graphs,
+animation dictionaries, and related metadata.
+
+> [!IMPORTANT]
+> FourFury is under active development. Read support is broader than write support,
+> and some resource types intentionally permit only fixed-size edits.
+
+## Format support
+
+| Format | Read | Write | Notes |
+| --- | :---: | :---: | --- |
+| RPF2 | Yes | Yes | Search, extraction, creation, and unencrypted output |
+| RPF3 | Yes | No | Audio archives; hash-only names remain hexadecimal |
+| IMG3 | Yes | Yes | Search, extraction, creation, and resource padding handling |
+| IDE | Yes | Yes | Lossless definitions with explicit MLO entities, rooms, portals, and validation |
+| IPL | Yes | Yes | Lossless sectioned text with typed GTA IV OCCL boxes |
+| water.dat | Yes | Yes | Lossless water triangles and quads, runtime flags, geometry queries, and neutral mesh export |
+| WPL | Yes | Yes | Placements, MLO resolution, explicit LOD hierarchies, world portals, and instance flags |
+| GTXD | Yes | Yes | Texture-parent chains and cycle detection |
+| NOD | Yes | Yes | Navigation nodes, links, costs, and topology validation |
+| WNV | Yes | Limited | Navigation meshes, edges, cover points, and quadtrees |
+| WBN | Yes | Limited | Collision bounds and fixed-size edits |
+| WBD | Yes | Limited | Collision dictionaries and fixed-size edits |
+| WAD | Yes | No | Animation dictionaries, tracks, chunks, and decoded channels |
+| WDD | Yes | No | Hash-addressed drawable dictionaries and neutral model projection |
+| WDR | Yes | No | Drawables plus neutral model projection |
+| WFT | Yes | No | Fragment drawables, physics hierarchy, collision bounds, and complete neutral fragment projection |
+| WTD | Yes | No | Texture dictionaries and DDS export |
+
+See [DOCUMENTATION.md](DOCUMENTATION.md) for examples, field behavior, writer
+constraints, and current limitations.
+
+## Installation
+
+FourFury requires Python 3.11 or newer. Install it directly from GitHub:
+
+```powershell
+python -m pip install "fourfury @ git+https://github.com/Hancapo/fourfury.git"
+```
+
+For an editable installation:
+
+```powershell
+git clone https://github.com/Hancapo/fourfury.git
+cd fourfury
+python -m pip install -e .
+```
+
+## Quick start
+
+Open an archive and read one of its entries:
+
+```python
+from pathlib import Path
+
+from fourfury import RpfArchive
+
+game = Path(r"D:\Program Files (x86)\Steam\steamapps\common\Grand Theft Auto IV\GTAIV")
+
+with RpfArchive.from_path(game / "pc/data/game.rpf") as archive:
+    entry = archive.find_entry("data/taskparams.txt")
+    if entry is not None:
+        print(entry.read().decode("utf-8"))
+```
+
+## Documentation
+
+The [complete documentation](DOCUMENTATION.md) covers every supported format,
+resource APIs, neutral WDR models, editing constraints, and known limitations.
+
+Release notes live in [CHANGELOG.md](CHANGELOG.md).