fivefury 0.2.7__tar.gz → 0.2.9__tar.gz

{fivefury-0.2.7 → fivefury-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fivefury
-Version: 0.2.7
+Version: 0.2.9
 Summary: Python library for GTA V asset workflows including YMAP, YTYP, RPF, YTD and GameFileCache utilities.
 Author: Codex
 License-Expression: CC0-1.0
@@ -8,6 +8,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: miniaudio>=1.71
+Requires-Dist: numpy>=1.26
 Dynamic: license-file
 
 # FiveFury
@@ -41,6 +42,8 @@ The Assimp-backed import helpers (`assimp_to_ydr`, `obj_to_ydr`, `fbx_to_ydr`, `
 | `YTD` | Full | Texture dictionaries: read/write, extraction, embedded-asset helpers |
 | `YND` | Full | Path nodes, links, area partitioning, junction heightmaps |
 | `YNV` | Full | Navmeshes: sectors, polys, portals, validation, basic OBJ partitioning |
+| `heightmap.dat` | Full | World-height grids, native quantization, row RLE, water masks, spatial queries |
+| `water.xml` | Full | Water surfaces, triangle corners, calming regions, wave amplitude and direction |
 | `CUT` | Full | Cutscenes, plus the readable `.cuts` script format for round-trip authoring |
 | `GXT2` | Full | Hashed text tables with binary read/write and text import/export |
 | `AWC` | Full | Audio containers: PCM/WAV extraction, authoring from WAV/MP3/OGG/FLAC |
@@ -114,6 +117,45 @@ save_ybn(bound, "floor_collision.ybn")
 
 Generated geometry is chunked as needed and gets BVH and octant data. The same bounds model backs standalone `YBN` files, embedded `YDR` collisions, and `YFT` physics — a drawable's render mesh can also be converted directly with `ydr.ensure_bound_from_render_geometry()`.
 
+### Author water
+
+```python
+from fivefury import WaterData, WaterQuad, WaterWaveQuad
+
+water = WaterData()
+water.add(
+    WaterQuad.rectangle(
+        center=(100.0, 200.0, 12.5),
+        size=(80.0, 40.0),
+        alpha=26,
+        limited_depth=True,
+    )
+)
+water.add(
+    WaterWaveQuad.from_angle(
+        bounds=(60, 180, 140, 220),
+        amplitude=1.2,
+        degrees=90.0,
+    )
+)
+water.translate(x=500, y=-200, z=20.0).save("water.xml")
+```
+
+### Author a world height map
+
+```python
+from fivefury import HeightMap, HeightMapBounds
+
+heightmap = HeightMap.empty(
+    columns=10,
+    rows=10,
+    bounds=HeightMapBounds(0.0, 0.0, 0.0, 500.0, 500.0, 800.0),
+)
+heightmap.set_height(4, 6, minimum=32.0, maximum=78.0)
+heightmap.set_water(4, 6)
+heightmap.save("heightmap.dat")
+```
+
 ### Convert audio to AWC
 
 ```python

fivefury-0.2.7/fivefury.egg-info/PKG-INFO → fivefury-0.2.9/README.md

@@ -1,15 +1,3 @@
-Metadata-Version: 2.4
-Name: fivefury
-Version: 0.2.7
-Summary: Python library for GTA V asset workflows including YMAP, YTYP, RPF, YTD and GameFileCache utilities.
-Author: Codex
-License-Expression: CC0-1.0
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: miniaudio>=1.71
-Dynamic: license-file
-
 # FiveFury
 
 FiveFury is a Python library for reading, writing, and packaging GTA V asset files: drawables, collisions, map metadata, animations, navigation data, texture dictionaries, text tables, audio containers, cutscenes, DLC metadata, and RPF archives.
@@ -41,6 +29,8 @@ The Assimp-backed import helpers (`assimp_to_ydr`, `obj_to_ydr`, `fbx_to_ydr`, `
 | `YTD` | Full | Texture dictionaries: read/write, extraction, embedded-asset helpers |
 | `YND` | Full | Path nodes, links, area partitioning, junction heightmaps |
 | `YNV` | Full | Navmeshes: sectors, polys, portals, validation, basic OBJ partitioning |
+| `heightmap.dat` | Full | World-height grids, native quantization, row RLE, water masks, spatial queries |
+| `water.xml` | Full | Water surfaces, triangle corners, calming regions, wave amplitude and direction |
 | `CUT` | Full | Cutscenes, plus the readable `.cuts` script format for round-trip authoring |
 | `GXT2` | Full | Hashed text tables with binary read/write and text import/export |
 | `AWC` | Full | Audio containers: PCM/WAV extraction, authoring from WAV/MP3/OGG/FLAC |
@@ -114,6 +104,45 @@ save_ybn(bound, "floor_collision.ybn")
 
 Generated geometry is chunked as needed and gets BVH and octant data. The same bounds model backs standalone `YBN` files, embedded `YDR` collisions, and `YFT` physics — a drawable's render mesh can also be converted directly with `ydr.ensure_bound_from_render_geometry()`.
 
+### Author water
+
+```python
+from fivefury import WaterData, WaterQuad, WaterWaveQuad
+
+water = WaterData()
+water.add(
+    WaterQuad.rectangle(
+        center=(100.0, 200.0, 12.5),
+        size=(80.0, 40.0),
+        alpha=26,
+        limited_depth=True,
+    )
+)
+water.add(
+    WaterWaveQuad.from_angle(
+        bounds=(60, 180, 140, 220),
+        amplitude=1.2,
+        degrees=90.0,
+    )
+)
+water.translate(x=500, y=-200, z=20.0).save("water.xml")
+```
+
+### Author a world height map
+
+```python
+from fivefury import HeightMap, HeightMapBounds
+
+heightmap = HeightMap.empty(
+    columns=10,
+    rows=10,
+    bounds=HeightMapBounds(0.0, 0.0, 0.0, 500.0, 500.0, 800.0),
+)
+heightmap.set_height(4, 6, minimum=32.0, maximum=78.0)
+heightmap.set_water(4, 6)
+heightmap.save("heightmap.dat")
+```
+
 ### Convert audio to AWC
 
 ```python

{fivefury-0.2.7 → fivefury-0.2.9}/fivefury/__init__.py

@@ -459,6 +459,37 @@ from .rpf import (
     zip_to_rpf,
 )
 from .texture import BCFormat
+from .heightmap import (
+    HeightCell,
+    HeightGrid,
+    HeightMap,
+    HeightMapBounds,
+    HeightMapByteOrder,
+    HeightMapCellFormat,
+    HeightMapFlags,
+    HeightMapValidationError,
+    build_heightmap_bytes,
+    create_heightmap,
+    read_heightmap,
+    save_heightmap,
+)
+from .water import (
+    WaterAlpha,
+    WaterBounds,
+    WaterCalmingQuad,
+    WaterComponent,
+    WaterCornerAlphas,
+    WaterData,
+    WaterQuad,
+    WaterQuadType,
+    WaterValidationError,
+    WaterWaveQuad,
+    build_water_xml,
+    coerce_water_data,
+    create_water,
+    read_water,
+    save_water,
+)
 from .ydr import (
     AssimpMaterial,
     AssimpScene,
@@ -1201,6 +1232,14 @@ __all__ = [
     "GameTarget",
     "GameCrypto",
     "GameFileType",
+    "HeightCell",
+    "HeightGrid",
+    "HeightMap",
+    "HeightMapBounds",
+    "HeightMapByteOrder",
+    "HeightMapCellFormat",
+    "HeightMapFlags",
+    "HeightMapValidationError",
     "GXT2_MAGIC",
     "GXT2_MAGIC_BYTES",
     "Gxt2",
@@ -1310,6 +1349,16 @@ __all__ = [
     "VehicleVariation",
     "VehicleWheelType",
     "VehicleWindow",
+    "WaterAlpha",
+    "WaterBounds",
+    "WaterCalmingQuad",
+    "WaterComponent",
+    "WaterCornerAlphas",
+    "WaterData",
+    "WaterQuad",
+    "WaterQuadType",
+    "WaterValidationError",
+    "WaterWaveQuad",
     "WalkDontWalkExtension",
     "WindDisturbanceExtension",
     "Ycd",
@@ -1567,7 +1616,9 @@ __all__ = [
     "infer_archetype_radius",
     "mark_cutscene_prop_archetypes",
     "assimp_to_ydr",
+    "build_heightmap_bytes",
     "build_rsc7",
+    "build_water_xml",
     "build_ynv_bytes",
     "build_ynv_system_layout",
     "build_bound_from_render_geometry",
@@ -1589,11 +1640,14 @@ __all__ = [
     "clear_hash_resolver",
     "clear_game_crypto",
     "create_rpf",
+    "create_heightmap",
+    "create_water",
     "create_ymf_for_ymaps",
     "create_ydd",
     "create_ydr",
     "convert_audio_to_awc",
     "coerce_ped_component",
+    "coerce_water_data",
     "ensure_game_crypto",
     "get_game_crypto",
     "get_hash_resolver",
@@ -1670,6 +1724,8 @@ __all__ = [
     "read_ynv",
     "read_ymap",
     "read_vehicle_meta",
+    "read_water",
+    "read_heightmap",
     "read_ymf",
     "read_ymf_xml",
     "read_ymt",
@@ -1699,6 +1755,8 @@ __all__ = [
     "save_ymt",
     "save_ytd",
     "save_ytyp",
+    "save_water",
+    "save_heightmap",
     "set_ped_drawable_cloth",
     "time_flags",
     "save_cut",

{fivefury-0.2.7 → fivefury-0.2.9}/fivefury/bounds/model.py

@@ -1054,7 +1054,7 @@ class BoundGeometry(Bound):
         return material
 
     def build(self) -> "BoundGeometry":
-        super().build()
+        Bound.build(self)
         for index, polygon in enumerate(self.polygons):
             polygon.index = index
             if isinstance(polygon, BoundPolygonTriangle):
@@ -1079,7 +1079,7 @@ class BoundGeometry(Bound):
         return self
 
     def validate(self) -> list[str]:
-        issues = super().validate()
+        issues = Bound.validate(self)
         if len(self.polygon_material_indices) != len(self.polygons):
             issues.append("polygon_material_indices length does not match polygon count")
         for polygon_index, polygon in enumerate(self.polygons):
@@ -1164,7 +1164,7 @@ class BoundComposite(Bound):
     def compute_volume(self) -> float:
         if self.children:
             return sum(child.bound.compute_volume() for child in self.children)
-        return super().compute_volume()
+        return Bound.compute_volume(self)
 
     def compute_center_of_gravity(
         self,
@@ -1226,7 +1226,7 @@ class BoundComposite(Bound):
         return self.compute_composite_angular_inertia(mass)
 
     def build(self) -> "BoundComposite":
-        super().build()
+        Bound.build(self)
         for child in self.children:
             child.bound.build()
             if child.bounds is None or not _aabb_is_valid(child.bounds):
@@ -1252,7 +1252,7 @@ class BoundComposite(Bound):
         return self
 
     def validate(self) -> list[str]:
-        issues = super().validate()
+        issues = Bound.validate(self)
         if not self.children:
             issues.append("Composite bound has no children")
         for index, child in enumerate(self.children):

{fivefury-0.2.7 → fivefury-0.2.9}/fivefury/cache/core.py

@@ -4,7 +4,7 @@ from collections import OrderedDict
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Iterator
+from typing import Any, Iterator, Self
 
 from .assets import GameFileCacheAssetMixin, TextureRef
 from .io import GameFileCacheIOMixin
@@ -100,6 +100,12 @@ class GameFileCache(GameFileCacheScanMixin, GameFileCacheAssetMixin, GameFileCac
     def __iter__(self) -> Iterator[AssetRecord]:
         return self.iter_assets()
 
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
     @property
     def scan_complete(self) -> bool:
         return self.last_scan is not None
@@ -139,7 +145,30 @@ class GameFileCache(GameFileCacheScanMixin, GameFileCacheAssetMixin, GameFileCac
         self._texture_parent_view = None
         self._kind_counts_view = None
 
+    def _close_runtime_archives(self) -> None:
+        seen: set[int] = set()
+        candidates = [
+            *self.archives,
+            *self._archive_lookup.values(),
+            *self._live_archives.values(),
+        ]
+        for game_file in self.files.values():
+            if game_file.archive is not None:
+                candidates.append(game_file.archive)
+            if isinstance(game_file.parsed, RpfArchive):
+                candidates.append(game_file.parsed)
+        for archive in candidates:
+            identity = id(archive)
+            if identity in seen:
+                continue
+            seen.add(identity)
+            archive.close()
+
+    def close(self) -> None:
+        self.clear_runtime_cache(loaded_files=True)
+
     def clear(self) -> None:
+        self._close_runtime_archives()
         self.archives.clear()
         self.files.clear()
         self.entries.clear()
@@ -155,6 +184,7 @@ class GameFileCache(GameFileCacheScanMixin, GameFileCacheAssetMixin, GameFileCac
         self._invalidate_views()
 
     def clear_runtime_cache(self, *, loaded_files: bool = False) -> None:
+        self._close_runtime_archives()
         self.archives.clear()
         self.entries.clear()
         self._archive_lookup.clear()
@@ -300,12 +330,18 @@ class GameFileCache(GameFileCacheScanMixin, GameFileCacheAssetMixin, GameFileCac
         normalized = _normalize_key(key)
         limit = max(0, int(self.max_open_archives))
         if limit <= 0:
+            for cached in self._archive_lookup.values():
+                cached.close()
             self._archive_lookup.clear()
             return
-        self._archive_lookup.pop(normalized, None)
+        previous = self._archive_lookup.pop(normalized, None)
+        if previous is not None and previous is not archive:
+            previous.close()
         self._archive_lookup[normalized] = archive
         while len(self._archive_lookup) > limit:
-            self._archive_lookup.popitem(last=False)
+            _, evicted = self._archive_lookup.popitem(last=False)
+            if all(cached is not evicted for cached in self._archive_lookup.values()):
+                evicted.close()
 
     def _register_asset(
         self,
@@ -518,6 +554,9 @@ _KIND_DICT_TYPES: dict[str, GameFileType] = {
     "GtxdDict": GameFileType.GTXD,
     "AwcDict": GameFileType.AWC,
     "YedDict": GameFileType.YED,
+    "HeightMapDict": GameFileType.HEIGHTMAP,
+    "WaterDict": GameFileType.WATER,
+    "WaterMapDict": GameFileType.WATER,
 }
 
 

{fivefury-0.2.7 → fivefury-0.2.9}/fivefury/cache/io.py

@@ -10,6 +10,7 @@ from ..cut import read_cut
 from ..gamefile import GameFile, GameFileType, guess_game_file_type
 from ..gtxd import read_gtxd
 from ..gxt2 import read_gxt2
+from ..heightmap import read_heightmap
 from ..hashing import _get_lut
 from ..metahash import MetaHash
 from ..rel import read_rel
@@ -22,6 +23,7 @@ from ..rpf import (
     _normalize_key,
 )
 from ..vehiclemeta import read_vehicle_meta
+from ..water import read_water
 from ..ybn import read_ybn
 from ..ycd import read_ycd
 from ..ydd import read_ydd
@@ -65,6 +67,10 @@ def _decode_dynamic(data: bytes, *, module_name: str, attribute: str, kind: Game
 def _decode_payload(path: str, data: bytes, *, raw: bytes | None = None) -> tuple[Any, GameFileType]:
     ext = Path(path).suffix.lower()
     name = Path(path).name.lower()
+    if name.startswith("heightmap") and name.endswith(".dat"):
+        return _decode_or_fallback(GameFileType.HEIGHTMAP, data, data, read_heightmap)
+    if name == "water.xml":
+        return _decode_or_fallback(GameFileType.WATER, data, data, read_water)
     if name == "gtxd.meta":
         return _decode_or_fallback(GameFileType.GTXD, data, data, read_gtxd)
     vehicle_meta_type = guess_game_file_type(path)

{fivefury-0.2.7 → fivefury-0.2.9}/fivefury/cache/scan.py

@@ -15,7 +15,7 @@ from ..gamefile import GameFileType, guess_game_file_type
 from ..hashing import _get_lut
 from ..rpf import RpfArchive, RpfFileEntry, _normalize_key
 
-_SCAN_INDEX_VERSION = 8
+_SCAN_INDEX_VERSION = 10
 _SCAN_GC_INTERVAL = 8
 
 _FLAG_LOOSE = 1

{fivefury-0.2.7 → fivefury-0.2.9}/fivefury/cdr/model.py

@@ -284,7 +284,7 @@ class Cdr(DrawableAsset[CdrMaterial, CdrModel, CdrMesh]):
     graphics_data: bytes = dataclasses.field(default=b"", repr=False)
 
     def __post_init__(self) -> None:
-        super().__post_init__()
+        DrawableAsset.__post_init__(self)
         self.render_bucket_masks = {
             DrawableLod(lod): int(mask)
             for lod, mask in self.render_bucket_masks.items()

{fivefury-0.2.7 → fivefury-0.2.9}/fivefury/gamefile.py

@@ -40,6 +40,7 @@ class GameFileType(IntEnum):
     YED = 25
     YFD = 27
     HEIGHTMAP = 28
+    WATER = 29
     WATERMAP = 29
     MRF = 30
     DISTANT_LIGHTS = 31
@@ -79,6 +80,9 @@ _FILE_TYPE_MAP: dict[str, GameFileType] = {
 
 def guess_game_file_type(path: str | Path, default: GameFileType = GameFileType.UNKNOWN) -> GameFileType:
     parsed = Path(str(path))
+    normalized_name = parsed.name.lower()
+    if normalized_name.startswith("heightmap") and normalized_name.endswith(".dat"):
+        return GameFileType.HEIGHTMAP
     named_meta_types = {
         "gtxd.meta": GameFileType.GTXD,
         "vehicles.meta": GameFileType.VEHICLES,
@@ -88,8 +92,9 @@ def guess_game_file_type(path: str | Path, default: GameFileType = GameFileType.
         "carvariations.meta": GameFileType.CAR_VARIATIONS,
         "vehiclelayouts.meta": GameFileType.VEHICLE_LAYOUTS,
         "peds.meta": GameFileType.PEDS,
+        "water.xml": GameFileType.WATER,
     }
-    named_type = named_meta_types.get(parsed.name.lower())
+    named_type = named_meta_types.get(normalized_name)
     if named_type is not None:
         return named_type
     return _FILE_TYPE_MAP.get(parsed.suffix.lower(), default)

fivefury-0.2.9/fivefury/heightmap/__init__.py

@@ -0,0 +1,31 @@
+from .io import (
+    build_heightmap_bytes,
+    create_heightmap,
+    read_heightmap,
+    save_heightmap,
+)
+from .model import (
+    HeightCell,
+    HeightGrid,
+    HeightMap,
+    HeightMapBounds,
+    HeightMapByteOrder,
+    HeightMapCellFormat,
+    HeightMapFlags,
+    HeightMapValidationError,
+)
+
+__all__ = [
+    "HeightCell",
+    "HeightGrid",
+    "HeightMap",
+    "HeightMapBounds",
+    "HeightMapByteOrder",
+    "HeightMapCellFormat",
+    "HeightMapFlags",
+    "HeightMapValidationError",
+    "build_heightmap_bytes",
+    "create_heightmap",
+    "read_heightmap",
+    "save_heightmap",
+]