fivefury 0.2.7__tar.gz → 0.2.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fivefury
-Version: 0.2.7
+Version: 0.2.8
 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,7 @@ 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 |
+| `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 +116,30 @@ 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")
+```
+
 ### Convert audio to AWC
 
 ```python

fivefury-0.2.7/fivefury.egg-info/PKG-INFO → fivefury-0.2.8/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,7 @@ 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 |
+| `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 +103,30 @@ 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")
+```
+
 ### Convert audio to AWC
 
 ```python

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

@@ -459,6 +459,23 @@ from .rpf import (
     zip_to_rpf,
 )
 from .texture import BCFormat
+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,
@@ -1310,6 +1327,16 @@ __all__ = [
     "VehicleVariation",
     "VehicleWheelType",
     "VehicleWindow",
+    "WaterAlpha",
+    "WaterBounds",
+    "WaterCalmingQuad",
+    "WaterComponent",
+    "WaterCornerAlphas",
+    "WaterData",
+    "WaterQuad",
+    "WaterQuadType",
+    "WaterValidationError",
+    "WaterWaveQuad",
     "WalkDontWalkExtension",
     "WindDisturbanceExtension",
     "Ycd",
@@ -1568,6 +1595,7 @@ __all__ = [
     "mark_cutscene_prop_archetypes",
     "assimp_to_ydr",
     "build_rsc7",
+    "build_water_xml",
     "build_ynv_bytes",
     "build_ynv_system_layout",
     "build_bound_from_render_geometry",
@@ -1589,11 +1617,13 @@ __all__ = [
     "clear_hash_resolver",
     "clear_game_crypto",
     "create_rpf",
+    "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 +1700,7 @@ __all__ = [
     "read_ynv",
     "read_ymap",
     "read_vehicle_meta",
+    "read_water",
     "read_ymf",
     "read_ymf_xml",
     "read_ymt",
@@ -1699,6 +1730,7 @@ __all__ = [
     "save_ymt",
     "save_ytd",
     "save_ytyp",
+    "save_water",
     "set_ped_drawable_cloth",
     "time_flags",
     "save_cut",

{fivefury-0.2.7 → fivefury-0.2.8}/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,8 @@ _KIND_DICT_TYPES: dict[str, GameFileType] = {
     "GtxdDict": GameFileType.GTXD,
     "AwcDict": GameFileType.AWC,
     "YedDict": GameFileType.YED,
+    "WaterDict": GameFileType.WATER,
+    "WaterMapDict": GameFileType.WATER,
 }
 
 

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

@@ -22,6 +22,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 +66,8 @@ 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 == "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.8}/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 = 9
 _SCAN_GC_INTERVAL = 8
 
 _FLAG_LOOSE = 1

{fivefury-0.2.7 → fivefury-0.2.8}/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
@@ -88,6 +89,7 @@ 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())
     if named_type is not None:

fivefury-0.2.8/fivefury/water/__init__.py

@@ -0,0 +1,30 @@
+from .geometry import WaterAlpha, WaterBounds, WaterCornerAlphas
+from .io import build_water_xml, create_water, read_water, save_water
+from .model import (
+    WaterCalmingQuad,
+    WaterComponent,
+    WaterData,
+    WaterQuad,
+    WaterQuadType,
+    WaterValidationError,
+    WaterWaveQuad,
+    coerce_water_data,
+)
+
+__all__ = [
+    "WaterAlpha",
+    "WaterBounds",
+    "WaterCalmingQuad",
+    "WaterComponent",
+    "WaterCornerAlphas",
+    "WaterData",
+    "WaterQuad",
+    "WaterQuadType",
+    "WaterValidationError",
+    "WaterWaveQuad",
+    "build_water_xml",
+    "coerce_water_data",
+    "create_water",
+    "read_water",
+    "save_water",
+]

fivefury-0.2.8/fivefury/water/geometry.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import dataclasses
+import math
+
+WaterBounds = tuple[int, int, int, int]
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class WaterCornerAlphas:
+    southwest: int = 26
+    southeast: int = 26
+    northeast: int = 26
+    northwest: int = 26
+
+    def values(self) -> tuple[int, int, int, int]:
+        return (
+            int(self.southwest),
+            int(self.southeast),
+            int(self.northeast),
+            int(self.northwest),
+        )
+
+
+WaterAlpha = int | WaterCornerAlphas
+
+
+def _coerce_alphas(value: WaterAlpha) -> tuple[int, int, int, int]:
+    if isinstance(value, int):
+        return value, value, value, value
+    if isinstance(value, WaterCornerAlphas):
+        return value.values()
+    raise TypeError("alpha must be an integer or WaterCornerAlphas")
+
+
+def _grid_integer(value: float, *, label: str) -> int:
+    number = float(value)
+    rounded = round(number)
+    if not math.isfinite(number) or not math.isclose(
+        number,
+        rounded,
+        abs_tol=1e-9,
+    ):
+        raise ValueError(f"{label} must be an integer water coordinate")
+    return rounded
+
+
+def _centered_bounds(
+    center: tuple[float, float],
+    size: tuple[float, float],
+) -> WaterBounds:
+    center_x, center_y = (float(component) for component in center)
+    width, height = (float(component) for component in size)
+    if not all(math.isfinite(value) for value in (center_x, center_y, width, height)):
+        raise ValueError("center and size must be finite")
+    if width <= 0.0 or height <= 0.0:
+        raise ValueError("size components must be greater than zero")
+    raw_bounds = (
+        center_x - width * 0.5,
+        center_y - height * 0.5,
+        center_x + width * 0.5,
+        center_y + height * 0.5,
+    )
+    try:
+        return tuple(
+            _grid_integer(value, label="center and size result") for value in raw_bounds
+        )
+    except ValueError as exc:
+        raise ValueError("center and size must produce integer water bounds") from exc
+
+
+def _coerce_bounds(bounds: WaterBounds) -> WaterBounds:
+    if len(bounds) != 4:
+        raise ValueError("bounds must contain min_x, min_y, max_x, max_y")
+    return tuple(_grid_integer(value, label="bounds component") for value in bounds)
+
+
+def _contains_xy(
+    points: tuple[tuple[float, float, float], ...],
+    x: float,
+    y: float,
+) -> bool:
+    if not points:
+        return False
+    signs: list[float] = []
+    for index, (x1, y1, _) in enumerate(points):
+        x2, y2, _ = points[(index + 1) % len(points)]
+        signs.append((x2 - x1) * (y - y1) - (y2 - y1) * (x - x1))
+    tolerance = 1e-9
+    return all(sign >= -tolerance for sign in signs) or all(
+        sign <= tolerance for sign in signs
+    )
+
+
+__all__ = [
+    "WaterAlpha",
+    "WaterBounds",
+    "WaterCornerAlphas",
+]

fivefury-0.2.8/fivefury/water/io.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from ..xml import (
+    add_value,
+    child_by_name,
+    child_value,
+    children_by_name,
+    parse_bool,
+    parse_xml_root,
+    xml_bytes,
+)
+from .model import (
+    WaterCalmingQuad,
+    WaterComponent,
+    WaterData,
+    WaterQuad,
+    WaterWaveQuad,
+    coerce_water_data,
+)
+
+
+def _int_value(element: ET.Element, name: str, default: int = 0) -> int:
+    text = child_value(element, name, str(default))
+    try:
+        return int(text, 0)
+    except ValueError:
+        return default
+
+
+def _float_value(element: ET.Element, name: str, default: float = 0.0) -> float:
+    text = child_value(element, name, str(default))
+    try:
+        return float(text)
+    except ValueError:
+        return default
+
+
+def _float_text(value: float) -> str:
+    text = format(float(value), ".9g")
+    return text if "." in text or "e" in text.lower() else f"{text}.0"
+
+
+def _item_elements(root: ET.Element, section_name: str) -> list[ET.Element]:
+    section = child_by_name(root, section_name)
+    if section is None:
+        return []
+    return [item for item in children_by_name(section, "Item") if len(item)]
+
+
+def _read_water_quad(item: ET.Element) -> WaterQuad:
+    return WaterQuad(
+        min_x=_int_value(item, "minX"),
+        min_y=_int_value(item, "minY"),
+        max_x=_int_value(item, "maxX"),
+        max_y=_int_value(item, "maxY"),
+        type=_int_value(item, "Type"),
+        is_invisible=parse_bool(child_value(item, "IsInvisible")),
+        has_limited_depth=parse_bool(child_value(item, "HasLimitedDepth")),
+        z=_float_value(item, "z"),
+        alpha_sw=_int_value(item, "a1", 26),
+        alpha_se=_int_value(item, "a2", 26),
+        alpha_ne=_int_value(item, "a3", 26),
+        alpha_nw=_int_value(item, "a4", 26),
+        no_stencil=parse_bool(child_value(item, "NoStencil")),
+    )
+
+
+def _read_calming_quad(item: ET.Element) -> WaterCalmingQuad:
+    return WaterCalmingQuad(
+        min_x=_int_value(item, "minX"),
+        min_y=_int_value(item, "minY"),
+        max_x=_int_value(item, "maxX"),
+        max_y=_int_value(item, "maxY"),
+        dampening=_float_value(item, "fDampening"),
+    )
+
+
+def _read_wave_quad(item: ET.Element) -> WaterWaveQuad:
+    return WaterWaveQuad(
+        min_x=_int_value(item, "minX"),
+        min_y=_int_value(item, "minY"),
+        max_x=_int_value(item, "maxX"),
+        max_y=_int_value(item, "maxY"),
+        amplitude=_float_value(item, "Amplitude"),
+        direction_x=_float_value(item, "XDirection"),
+        direction_y=_float_value(item, "YDirection"),
+    )
+
+
+def read_water(source: bytes | str | Path) -> WaterData:
+    root = parse_xml_root(source)
+    if root.tag.lower() != "waterdata":
+        raise ValueError(f"Expected WaterData XML root, got {root.tag!r}")
+    return WaterData(
+        water_quads=[
+            _read_water_quad(item) for item in _item_elements(root, "WaterQuads")
+        ],
+        calming_quads=[
+            _read_calming_quad(item) for item in _item_elements(root, "CalmingQuads")
+        ],
+        wave_quads=[
+            _read_wave_quad(item) for item in _item_elements(root, "WaveQuads")
+        ],
+    )
+
+
+def _write_bounds(item: ET.Element, quad: WaterComponent) -> None:
+    add_value(item, "minX", quad.min_x)
+    add_value(item, "maxX", quad.max_x)
+    add_value(item, "minY", quad.min_y)
+    add_value(item, "maxY", quad.max_y)
+
+
+def _water_quad_element(quad: WaterQuad) -> ET.Element:
+    item = ET.Element("Item")
+    _write_bounds(item, quad)
+    add_value(item, "Type", int(quad.type))
+    add_value(item, "IsInvisible", quad.is_invisible)
+    add_value(item, "HasLimitedDepth", quad.has_limited_depth)
+    add_value(item, "z", _float_text(quad.z))
+    add_value(item, "a1", quad.alpha_sw)
+    add_value(item, "a2", quad.alpha_se)
+    add_value(item, "a3", quad.alpha_ne)
+    add_value(item, "a4", quad.alpha_nw)
+    add_value(item, "NoStencil", quad.no_stencil)
+    return item
+
+
+def _calming_quad_element(quad: WaterCalmingQuad) -> ET.Element:
+    item = ET.Element("Item")
+    _write_bounds(item, quad)
+    add_value(item, "fDampening", _float_text(quad.dampening))
+    return item
+
+
+def _wave_quad_element(quad: WaterWaveQuad) -> ET.Element:
+    item = ET.Element("Item")
+    _write_bounds(item, quad)
+    add_value(item, "Amplitude", _float_text(quad.amplitude))
+    add_value(item, "XDirection", _float_text(quad.direction_x))
+    add_value(item, "YDirection", _float_text(quad.direction_y))
+    return item
+
+
+def _append_section(
+    root: ET.Element,
+    name: str,
+    items: list[WaterComponent],
+    factory,
+) -> None:
+    if not items:
+        return
+    section = ET.SubElement(root, name)
+    for item in items:
+        section.append(factory(item))
+
+
+def build_water_xml(source: WaterData, *, validate: bool = True) -> bytes:
+    water = source.build()
+    if validate:
+        water.ensure_valid()
+    root = ET.Element("WaterData")
+    _append_section(root, "WaterQuads", water.water_quads, _water_quad_element)
+    _append_section(
+        root,
+        "CalmingQuads",
+        water.calming_quads,
+        _calming_quad_element,
+    )
+    _append_section(root, "WaveQuads", water.wave_quads, _wave_quad_element)
+    return xml_bytes(root)
+
+
+def create_water(*items: WaterComponent) -> WaterData:
+    return coerce_water_data(list(items))
+
+
+def save_water(
+    source: WaterData,
+    path: str | Path,
+    *,
+    validate: bool = True,
+) -> Path:
+    return source.save(path, validate=validate)
+
+
+__all__ = [
+    "build_water_xml",
+    "create_water",
+    "read_water",
+    "save_water",
+]