fivefury 0.1.0

Partial Python port of CodeWalker.GameFiles for YMAP, YTYP and RPF workflows.

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

pip install fivefury

For local development from a checkout:

pip install -e .

Python 3.11+ is required.

Quick Start

Create a YMAP

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

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

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

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

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

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

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

asset = cache.get_asset("prop_tree_pine_01", kind=".ydr")
print(asset.path)
print(asset.short_name_hash)

You can iterate the cache directly:

for asset in cache:
    print(asset.path, asset.kind)

Or iterate a specific kind:

for ydr in cache.iter_kind(".ydr"):
    print(ydr.path)

Read and Extract Assets

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:

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.

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.

archetype = cache.get_archetype("prop_tree_pine_01")
print(archetype.name)

for archetype in cache.iter_archetypes():
    print(archetype.name)

Global Hash Resolver

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.