fivefury 0.1.0__tar.gz

fivefury-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include native/*.h

fivefury-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: fivefury
+Version: 0.1.0
+Summary: Partial Python port of CodeWalker.GameFiles for YMAP, YTYP and RPF workflows.
+Author: Codex
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# FiveFury
+
+FiveFury is a Python library for GTA V asset workflows.
+
+It provides practical support for:
+
+- `YMAP` read/write
+- `YTYP` read/write
+- `RPF7 OPEN` archives and nested `.rpf`
+- `ZIP -> RPF` and `RPF -> ZIP`
+- fast asset indexing with `GameFileCache`
+
+## Installation
+
+```bash
+pip install fivefury
+```
+
+For local development from a checkout:
+
+```bash
+pip install -e .
+```
+
+Python `3.11+` is required.
+
+## Quick Start
+
+### Create a YMAP
+
+```python
+from fivefury import Entity, Ymap
+
+ymap = Ymap(name="example_map")
+ymap.add_entity(
+    Entity(
+        archetype_name="prop_tree_pine_01",
+        guid=1,
+        position=(0.0, 0.0, 0.0),
+        rotation=(0.0, 0.0, 0.0, 1.0),
+        lod_dist=150.0,
+    )
+)
+ymap.recalculate_extents()
+ymap.recalculate_flags()
+ymap.save("example_map.ymap")
+```
+
+If you want an internal resource path, set `ymap.resource_name` before saving.
+
+### Load a YMAP
+
+```python
+from pathlib import Path
+
+from fivefury import Ymap
+
+ymap = Ymap.from_bytes(Path("example_map.ymap").read_bytes())
+
+print(len(ymap.entities))
+print(ymap.flags, ymap.content_flags)
+```
+
+### Create a YTYP
+
+```python
+from fivefury import Archetype, ParticleEffectExtension, Ytyp
+
+ytyp = Ytyp(name="example_types")
+
+archetype = Archetype(
+    name="prop_tree_pine_01",
+    lod_dist=150.0,
+    asset_type=0,
+    bb_min=(-1.5, -1.5, -0.5),
+    bb_max=(1.5, 1.5, 8.0),
+    bs_centre=(0.0, 0.0, 3.5),
+    bs_radius=5.0,
+)
+archetype.add_extension(
+    ParticleEffectExtension(
+        name="fx_tree",
+        fx_name="scr_wheel_burnout",
+        fx_type=2,
+        scale=0.8,
+    )
+)
+
+ytyp.add_archetype(archetype)
+ytyp.save("example_types.ytyp")
+```
+
+### Pack Assets into an RPF
+
+```python
+from fivefury import Entity, Ymap, create_rpf
+
+ymap = Ymap(name="packed_map")
+ymap.add_entity(Entity(archetype_name="prop_tree_pine_01", position=(0.0, 0.0, 0.0), lod_dist=120.0))
+ymap.recalculate_extents()
+ymap.recalculate_flags()
+
+archive = create_rpf("mods.rpf")
+archive.add("stream/packed_map.ymap", ymap)
+archive.add("docs/readme.txt", b"hello from fivefury")
+archive.save("mods.rpf")
+```
+
+### Convert between ZIP and RPF
+
+```python
+from fivefury import rpf_to_zip, zip_to_rpf
+
+zip_to_rpf("unpacked_mod_folder", "packed_mod.rpf")
+rpf_to_zip("packed_mod.rpf", "packed_mod.zip")
+```
+
+Directories ending in `.rpf` are packed as nested archives.
+
+## GameFileCache
+
+### Scan a Game Installation
+
+```python
+from fivefury import GameFileCache
+
+cache = GameFileCache(
+    r"C:\Program Files (x86)\Steam\steamapps\common\Grand Theft Auto V",
+    scan_workers=8,
+    max_loaded_files=16,
+)
+cache.scan_game(use_index_cache=True)
+
+print(cache.asset_count)
+print(cache.stats_by_kind())
+```
+
+`GameFileCache` indexes loose files and archive contents, then loads supported formats lazily.
+
+### Control DLC and Scan Scope
+
+```python
+from fivefury import GameFileCache
+
+cache = GameFileCache(
+    r"C:\Program Files (x86)\Steam\steamapps\common\Grand Theft Auto V",
+    dlc_level="mpbattle",
+    exclude_folders="mods;scratch",
+    load_audio=False,
+    load_vehicles=True,
+    load_peds=True,
+)
+cache.scan_game(use_index_cache=True)
+```
+
+Useful scan options:
+
+- `dlc_level`: limit active DLCs
+- `exclude_folders`: ignore folders by prefix
+- `load_audio`: skip audio-related assets during scan
+- `load_vehicles`: skip vehicle-related assets during scan
+- `load_peds`: skip ped-related assets during scan
+- `use_index_cache`: reuse the persisted scan index for faster startup
+
+### Look Up Assets by Name and Type
+
+```python
+asset = cache.get_asset("prop_tree_pine_01", kind=".ydr")
+print(asset.path)
+print(asset.short_name_hash)
+```
+
+You can iterate the cache directly:
+
+```python
+for asset in cache:
+    print(asset.path, asset.kind)
+```
+
+Or iterate a specific kind:
+
+```python
+for ydr in cache.iter_kind(".ydr"):
+    print(ydr.path)
+```
+
+### Read and Extract Assets
+
+```python
+from pathlib import Path
+
+asset = cache.get_asset("prop_tree_pine_01", kind=".ydr")
+data = cache.read_bytes(asset, logical=True)
+out_path = cache.extract_asset(asset, Path("prop_tree_pine_01.ydr"))
+
+print(len(data))
+print(out_path)
+```
+
+Common access patterns:
+
+- `get_asset(...)`: resolve one asset by path, name or hash
+- `read_bytes(...)`: get bytes directly
+- `get_file(...)`: build a lazy `GameFile` wrapper
+- `extract_asset(...)`: write the asset to disk
+
+Extraction defaults to standalone file output.
+For resource assets such as `YDR`, `YDD`, `YFT`, `YTD`, `YMAP` and `YTYP`, this produces a valid standalone `RSC7` file.
+
+If you want the logical payload instead:
+
+```python
+cache.extract_asset("prop_tree_pine_01", "prop_tree_pine_01_payload.ydr", logical=True)
+```
+
+### Type Dictionaries
+
+`GameFileCache` exposes lazy type dictionaries keyed by `shortNameHash`.
+
+```python
+from fivefury import jenk_hash
+
+ydr = cache.YdrDict[jenk_hash("prop_tree_pine_01")]
+ytd = cache.YtdDict[jenk_hash("vehshare")]
+ybn = cache.YbnDict[jenk_hash("v_carshowroom")]
+```
+
+Available dictionaries include `YdrDict`, `YddDict`, `YtdDict`, `YmapDict`, `YtypDict`, `YftDict`, `YbnDict`, `YcdDict`, `YptDict`, `YndDict`, `YnvDict`, `YedDict`, `YwrDict`, `YvrDict`, `RelDict` and `Gxt2Dict`.
+
+### Archetype Lookup
+
+`GameFileCache` also builds a lazy global archetype lookup from indexed `YTYP` files.
+
+```python
+archetype = cache.get_archetype("prop_tree_pine_01")
+print(archetype.name)
+
+for archetype in cache.iter_archetypes():
+    print(archetype.name)
+```
+
+## Global Hash Resolver
+
+```python
+from fivefury import register_name, register_names_file, resolve_hash, jenk_hash
+
+register_name("prop_tree_pine_01")
+register_names_file("common_names.txt")
+
+print(resolve_hash(jenk_hash("prop_tree_pine_01")))
+```
+
+The resolver is shared and optional. It is useful for display, lookups and tooling.

fivefury-0.1.0/README.md

@@ -0,0 +1,253 @@
+# FiveFury
+
+FiveFury is a Python library for GTA V asset workflows.
+
+It provides practical support for:
+
+- `YMAP` read/write
+- `YTYP` read/write
+- `RPF7 OPEN` archives and nested `.rpf`
+- `ZIP -> RPF` and `RPF -> ZIP`
+- fast asset indexing with `GameFileCache`
+
+## Installation
+
+```bash
+pip install fivefury
+```
+
+For local development from a checkout:
+
+```bash
+pip install -e .
+```
+
+Python `3.11+` is required.
+
+## Quick Start
+
+### Create a YMAP
+
+```python
+from fivefury import Entity, Ymap
+
+ymap = Ymap(name="example_map")
+ymap.add_entity(
+    Entity(
+        archetype_name="prop_tree_pine_01",
+        guid=1,
+        position=(0.0, 0.0, 0.0),
+        rotation=(0.0, 0.0, 0.0, 1.0),
+        lod_dist=150.0,
+    )
+)
+ymap.recalculate_extents()
+ymap.recalculate_flags()
+ymap.save("example_map.ymap")
+```
+
+If you want an internal resource path, set `ymap.resource_name` before saving.
+
+### Load a YMAP
+
+```python
+from pathlib import Path
+
+from fivefury import Ymap
+
+ymap = Ymap.from_bytes(Path("example_map.ymap").read_bytes())
+
+print(len(ymap.entities))
+print(ymap.flags, ymap.content_flags)
+```
+
+### Create a YTYP
+
+```python
+from fivefury import Archetype, ParticleEffectExtension, Ytyp
+
+ytyp = Ytyp(name="example_types")
+
+archetype = Archetype(
+    name="prop_tree_pine_01",
+    lod_dist=150.0,
+    asset_type=0,
+    bb_min=(-1.5, -1.5, -0.5),
+    bb_max=(1.5, 1.5, 8.0),
+    bs_centre=(0.0, 0.0, 3.5),
+    bs_radius=5.0,
+)
+archetype.add_extension(
+    ParticleEffectExtension(
+        name="fx_tree",
+        fx_name="scr_wheel_burnout",
+        fx_type=2,
+        scale=0.8,
+    )
+)
+
+ytyp.add_archetype(archetype)
+ytyp.save("example_types.ytyp")
+```
+
+### Pack Assets into an RPF
+
+```python
+from fivefury import Entity, Ymap, create_rpf
+
+ymap = Ymap(name="packed_map")
+ymap.add_entity(Entity(archetype_name="prop_tree_pine_01", position=(0.0, 0.0, 0.0), lod_dist=120.0))
+ymap.recalculate_extents()
+ymap.recalculate_flags()
+
+archive = create_rpf("mods.rpf")
+archive.add("stream/packed_map.ymap", ymap)
+archive.add("docs/readme.txt", b"hello from fivefury")
+archive.save("mods.rpf")
+```
+
+### Convert between ZIP and RPF
+
+```python
+from fivefury import rpf_to_zip, zip_to_rpf
+
+zip_to_rpf("unpacked_mod_folder", "packed_mod.rpf")
+rpf_to_zip("packed_mod.rpf", "packed_mod.zip")
+```
+
+Directories ending in `.rpf` are packed as nested archives.
+
+## GameFileCache
+
+### Scan a Game Installation
+
+```python
+from fivefury import GameFileCache
+
+cache = GameFileCache(
+    r"C:\Program Files (x86)\Steam\steamapps\common\Grand Theft Auto V",
+    scan_workers=8,
+    max_loaded_files=16,
+)
+cache.scan_game(use_index_cache=True)
+
+print(cache.asset_count)
+print(cache.stats_by_kind())
+```
+
+`GameFileCache` indexes loose files and archive contents, then loads supported formats lazily.
+
+### Control DLC and Scan Scope
+
+```python
+from fivefury import GameFileCache
+
+cache = GameFileCache(
+    r"C:\Program Files (x86)\Steam\steamapps\common\Grand Theft Auto V",
+    dlc_level="mpbattle",
+    exclude_folders="mods;scratch",
+    load_audio=False,
+    load_vehicles=True,
+    load_peds=True,
+)
+cache.scan_game(use_index_cache=True)
+```
+
+Useful scan options:
+
+- `dlc_level`: limit active DLCs
+- `exclude_folders`: ignore folders by prefix
+- `load_audio`: skip audio-related assets during scan
+- `load_vehicles`: skip vehicle-related assets during scan
+- `load_peds`: skip ped-related assets during scan
+- `use_index_cache`: reuse the persisted scan index for faster startup
+
+### Look Up Assets by Name and Type
+
+```python
+asset = cache.get_asset("prop_tree_pine_01", kind=".ydr")
+print(asset.path)
+print(asset.short_name_hash)
+```
+
+You can iterate the cache directly:
+
+```python
+for asset in cache:
+    print(asset.path, asset.kind)
+```
+
+Or iterate a specific kind:
+
+```python
+for ydr in cache.iter_kind(".ydr"):
+    print(ydr.path)
+```
+
+### Read and Extract Assets
+
+```python
+from pathlib import Path
+
+asset = cache.get_asset("prop_tree_pine_01", kind=".ydr")
+data = cache.read_bytes(asset, logical=True)
+out_path = cache.extract_asset(asset, Path("prop_tree_pine_01.ydr"))
+
+print(len(data))
+print(out_path)
+```
+
+Common access patterns:
+
+- `get_asset(...)`: resolve one asset by path, name or hash
+- `read_bytes(...)`: get bytes directly
+- `get_file(...)`: build a lazy `GameFile` wrapper
+- `extract_asset(...)`: write the asset to disk
+
+Extraction defaults to standalone file output.
+For resource assets such as `YDR`, `YDD`, `YFT`, `YTD`, `YMAP` and `YTYP`, this produces a valid standalone `RSC7` file.
+
+If you want the logical payload instead:
+
+```python
+cache.extract_asset("prop_tree_pine_01", "prop_tree_pine_01_payload.ydr", logical=True)
+```
+
+### Type Dictionaries
+
+`GameFileCache` exposes lazy type dictionaries keyed by `shortNameHash`.
+
+```python
+from fivefury import jenk_hash
+
+ydr = cache.YdrDict[jenk_hash("prop_tree_pine_01")]
+ytd = cache.YtdDict[jenk_hash("vehshare")]
+ybn = cache.YbnDict[jenk_hash("v_carshowroom")]
+```
+
+Available dictionaries include `YdrDict`, `YddDict`, `YtdDict`, `YmapDict`, `YtypDict`, `YftDict`, `YbnDict`, `YcdDict`, `YptDict`, `YndDict`, `YnvDict`, `YedDict`, `YwrDict`, `YvrDict`, `RelDict` and `Gxt2Dict`.
+
+### Archetype Lookup
+
+`GameFileCache` also builds a lazy global archetype lookup from indexed `YTYP` files.
+
+```python
+archetype = cache.get_archetype("prop_tree_pine_01")
+print(archetype.name)
+
+for archetype in cache.iter_archetypes():
+    print(archetype.name)
+```
+
+## Global Hash Resolver
+
+```python
+from fivefury import register_name, register_names_file, resolve_hash, jenk_hash
+
+register_name("prop_tree_pine_01")
+register_names_file("common_names.txt")
+
+print(resolve_hash(jenk_hash("prop_tree_pine_01")))
+```
+
+The resolver is shared and optional. It is useful for display, lookups and tooling.

fivefury-0.1.0/fivefury/__init__.py

@@ -0,0 +1,185 @@
+from .cache import AssetRecord, GameFileCache, ScanStats
+from .crypto import (
+    AES_ENCRYPTION,
+    NG_ENCRYPTION,
+    OPEN_ENCRYPTION,
+    GameCrypto,
+    clear_game_crypto,
+    get_game_crypto,
+    load_game_keys,
+)
+from .extensions import (
+    AudioCollisionSettingsExtension,
+    AudioEmitterExtension,
+    BuoyancyExtension,
+    CapsuleBoundDef,
+    DoorExtension,
+    ExpressionExtension,
+    ExplosionEffectExtension,
+    LadderExtension,
+    LightAttrDef,
+    LightEffectExtension,
+    LightShaftExtension,
+    ParticleEffectExtension,
+    ProcObjectExtension,
+    SpawnPointExtension,
+    SpawnPointOverrideExtension,
+    VerletClothCustomBoundsExtension,
+    WindDisturbanceExtension,
+)
+from .gamefile import GameFile, GameFileType
+from .hashing import jenk_hash
+from .metahash import HashString, MetaHash
+from .meta import Meta, read_meta
+from .resolver import (
+    HashResolver,
+    clear_hash_resolver,
+    get_hash_resolver,
+    hash_matches,
+    register_name,
+    register_names,
+    register_names_file,
+    register_path_name,
+    register_path_names,
+    resolve_hash,
+    resolve_name,
+)
+from .resource import RSC7_MAGIC, ResourceHeader, build_rsc7, parse_rsc7
+from .rpf import RpfArchive, create_rpf, load_rpf, rpf_to_zip, zip_to_rpf
+from .ymap import (
+    Block,
+    CarGen,
+    CarGenerator,
+    Entity,
+    EntityDef,
+    MloInstance,
+    MloInstanceDef,
+    TimeCycleModifier,
+    Ymap,
+    read_ymap,
+    save_ymap,
+)
+from .ymap_surfaces import (
+    Aabb,
+    BoxOccluder,
+    DistantLodLights,
+    DistantLodLightsSoa,
+    GrassBatch,
+    GrassInstance,
+    GrassInstanceBatch,
+    InstancedData,
+    InstancedMapData,
+    LodLight,
+    LodLights,
+    LodLightsSoa,
+    OccludeModel,
+)
+from .ytyp import (
+    Archetype,
+    BaseArchetypeDef,
+    EntitySet,
+    MloArchetype,
+    MloArchetypeDef,
+    MloTimeModifier,
+    Portal,
+    Room,
+    TimeArchetype,
+    TimeArchetypeDef,
+    Ytyp,
+    read_ytyp,
+    save_ytyp,
+)
+
+__all__ = [
+    "Aabb",
+    "Archetype",
+    "AudioCollisionSettingsExtension",
+    "AudioEmitterExtension",
+    "AES_ENCRYPTION",
+    "AssetRecord",
+    "BaseArchetypeDef",
+    "Block",
+    "BoxOccluder",
+    "BuoyancyExtension",
+    "CapsuleBoundDef",
+    "CarGen",
+    "CarGenerator",
+    "DistantLodLights",
+    "DistantLodLightsSoa",
+    "DoorExtension",
+    "Entity",
+    "EntityDef",
+    "EntitySet",
+    "ExpressionExtension",
+    "ExplosionEffectExtension",
+    "GameFile",
+    "GameFileCache",
+    "GameCrypto",
+    "GameFileType",
+    "ScanStats",
+    "GrassBatch",
+    "GrassInstance",
+    "GrassInstanceBatch",
+    "InstancedData",
+    "InstancedMapData",
+    "HashResolver",
+    "HashString",
+    "LadderExtension",
+    "LightAttrDef",
+    "LightEffectExtension",
+    "LightShaftExtension",
+    "LodLight",
+    "LodLights",
+    "LodLightsSoa",
+    "Meta",
+    "MetaHash",
+    "MloArchetype",
+    "MloArchetypeDef",
+    "MloInstance",
+    "MloInstanceDef",
+    "MloTimeModifier",
+    "NG_ENCRYPTION",
+    "OccludeModel",
+    "OPEN_ENCRYPTION",
+    "ParticleEffectExtension",
+    "Portal",
+    "ProcObjectExtension",
+    "ResourceHeader",
+    "Room",
+    "RpfArchive",
+    "RSC7_MAGIC",
+    "SpawnPointExtension",
+    "SpawnPointOverrideExtension",
+    "TimeArchetype",
+    "TimeArchetypeDef",
+    "TimeCycleModifier",
+    "VerletClothCustomBoundsExtension",
+    "WindDisturbanceExtension",
+    "Ymap",
+    "Ytyp",
+    "build_rsc7",
+    "clear_hash_resolver",
+    "clear_game_crypto",
+    "create_rpf",
+    "get_game_crypto",
+    "get_hash_resolver",
+    "hash_matches",
+    "jenk_hash",
+    "load_game_keys",
+    "load_rpf",
+    "parse_rsc7",
+    "read_meta",
+    "read_ymap",
+    "read_ytyp",
+    "register_name",
+    "register_names",
+    "register_names_file",
+    "register_path_name",
+    "register_path_names",
+    "resolve_hash",
+    "resolve_name",
+    "rpf_to_zip",
+    "save_ymap",
+    "save_ytyp",
+    "zip_to_rpf",
+]