fivefury 0.2.3__tar.gz → 0.2.5__tar.gz

{fivefury-0.2.3/fivefury.egg-info → fivefury-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fivefury
-Version: 0.2.3
+Version: 0.2.5
 Summary: Python library for GTA V asset workflows including YMAP, YTYP, RPF, YTD and GameFileCache utilities.
 Author: Codex
 License-Expression: MIT
@@ -59,14 +59,14 @@ Support levels:
 
 | Format | Scope |
 | --- | --- |
-| `YDR` | Drawable resources: materials, shaders, samplers, numeric parameters, drawable models, LODs, render masks, lights, embedded textures, embedded bounds, skeletons, skinning, rigid bone bindings, shader inspection, and skeleton hash recalculation. |
-| `YDD` | Drawable dictionaries with multiple embedded drawables and high-level creation from named `YDR` drawables. |
+| `YDR` | Drawable resources: materials, shaders, samplers, numeric parameters, drawable models, LODs, render masks, lights, embedded textures, embedded bounds, skeletons, skinning, radial weight generation, rigid bone bindings, shader inspection, and skeleton hash recalculation. |
+| `YDD` | Drawable dictionaries with multiple embedded drawables, high-level creation from named `YDR` drawables, and external-skeleton radial rigging helpers for ped components. |
 | `YBN` | Bounds/collisions: primitive bounds, composite bounds, geometry bounds, BVH bounds, octants, material names, material colors, and generated collision chunks from triangle meshes. |
 | `YCD` | Clip dictionaries: parsed metadata, sequence rebuilds, known track types, UV clip bindings, object animation metadata, skeletal tracks, root motion, camera tracks, and facial samples. |
 | `YMAP` | Map metadata: entities, car generators, timecycle modifiers, occluders, content flags, entity flags, LOD lights, distant lights, and typed metadata. |
 | `YTYP` | Archetypes: base/time/MLO archetypes, extensions, rooms, portals, entity sets, typed asset metadata, flags, LOD distances, physics dictionaries, and cutscene prop helpers. |
 | `YTD` | Texture dictionaries: read/write, resource texture payload preservation, cache extraction, and embedded-asset helpers. |
-| `YND` | Path node resources: nodes, links, typed flags/enums, area helpers, automatic area ID calculation, and network partitioning. |
+| `YND` | Path node resources: nodes, links, typed flags/enums, area helpers, automatic area ID calculation, network partitioning, and game-aligned junction heightmap generation. |
 | `YNV` | Navmesh resources: sectors, polys, points, portals, typed metadata, validation, and basic Assimp/OBJ partitioning. |
 | `CUT` | Cutscene files: cameras, tracks, events, props, peds, vehicles, lights, high-level scene conversion, `.cuts` script authoring, and `.cut` to `.cuts` export. |
 | `GXT2` | Hashed UTF-8 text tables with binary read/write, CodeWalker-style text import/export, mapping-style helpers, and `GameFileCache` loading. |
@@ -77,18 +77,20 @@ Support levels:
 
 | Format | Current behavior |
 | --- | --- |
-| `YFT` | Resource texture dictionaries can be discovered/extracted from fragments, but full fragment authoring is not implemented. |
+| `YFT` | Fragment reading/writing for common, damaged, extra and cloth drawables, including geometry, materials, LOD meshes, bounding sphere metadata, fragment flags, physics LODs, physics groups, physics children, child entity drawables, per-child breaking/inertia data, damping constants, damping archetypes, articulated body metadata, link attachments, group and child event references, editable composite bounds, mass/inertia helpers, glass/cloth/vehicle semantic queries, corpus scanning, validation, declarative physics helpers, geometry summaries and embedded texture dictionaries. |
 | `YPT` | Resource texture dictionaries can be discovered/extracted from particle dictionaries, but full particle authoring is not implemented. |
 | `AWC` | Audio wave containers can be read/written structurally, opened through `GameFileCache`, exported back to WAV for PCM/ADPCM streams, and built from mono or multichannel 16-bit PCM inputs decoded through `miniaudio` (`.wav`, `.mp3`, `.ogg`, `.flac`). Playback metadata lives in `.rel` banks. |
 | `REL` | Audio metadata banks can be read/written structurally, opened through `GameFileCache`, and round-tripped with unknown entries preserved. `dat10.rel` modular synth presets/synths, `dat16.rel` curves, `dat22.rel` categories, and common `dat54.rel` sound graph entries have typed models, including simple AWC-backed sounds, wrappers, sequential/multitrack/streaming child lists, randomized variations, modular synth sounds, automation/MIDI sounds, note maps, variable-curve and conditional routing, directional/kinetic routing, variable blocks, math operations, parameter transforms, fluctuators, external streams, sound sets, sound-set lists, and sound-hash lists. Other REL item families currently stay as raw entries. |
-| `YMF`, `YMT`, `YWR`, `YVR`, `YED` | Recognized/indexed by `GameFileCache` and RPF tooling, but no complete dedicated high-level reader/writer is exposed. |
-| `GTXD` metadata | Used by cache texture lookup and parent-chain resolution, but it is not a standalone binary asset format like `.gxt2`. |
+| `YED` | Expression dictionaries can be detected, opened through `GameFileCache`, inspected for expressions/tracks/streams/springs/instruction opcodes, edited safely for spring-list cloning, built from scratch for spring dictionaries, and validated before writing. |
+| `YMT` | Generic META-backed read/write plus ped-variation helpers for component enumeration, drawable file stems, and cloth ownership flags. |
+| `YMF`, `YWR`, `YVR` | Recognized/indexed by `GameFileCache` and RPF tooling, but no complete dedicated high-level reader/writer is exposed. |
+| `GTXD` metadata | XML read/write for parent texture dictionary relationships, cache texture lookup, and parent-chain resolution. It is metadata rather than a standalone binary asset format like `.gxt2`. |
 
 ### Not Implemented Yet
 
 | Format family | Notes |
 | --- | --- |
-| `YLD`, `YFD`, `YPDB`, `MRF` | Known game file types, currently no dedicated high-level support. |
+| `YFD`, `YPDB`, `MRF` | Known game file types, currently no dedicated high-level support. |
 | Heightmap and watermap resources | Recognized as game concepts, but no complete public reader/writer yet. |
 | Vehicle/ped audio REL specializations | REL files can be loaded structurally, but specialized semantic authoring beyond the initial synth/curve/category/sound subset is not currently exposed. |
 
@@ -402,9 +404,44 @@ FiveFury exposes:
 - editable material shaders, samplers, and numeric parameters
 - embedded texture helpers through `add_embedded_texture(...)` and `remove_embedded_texture(...)`
 - embedded collision helpers through `set_bound(...)` and `clear_bound()`
-- skeleton helpers for bones, skinning, rigid bone bindings, and explicit skeleton hash recalculation
+- skeleton helpers for bones, skinning, radial weight generation, rigid bone bindings, and explicit skeleton hash recalculation
 - `build()` / `validate()` helpers for authoring flows
 
+### Generate radial skin weights
+
+```python
+from fivefury import RadialBoneRigRule, read_ydd, rig_ydd_to_bones_radially
+
+body = read_ydd("tdev_xyuls^lowr_000_u.ydd")
+skeleton_source = read_ydd("tdev_xyuls^head_000_u.ydd")
+
+report = rig_ydd_to_bones_radially(
+    body,
+    [
+        RadialBoneRigRule("SM_R_BackSkirtRoll", radius=0.16, strength=0.65),
+        RadialBoneRigRule("SM_L_BackSkirtRoll", radius=0.16, strength=0.65),
+    ],
+    skeleton_source=skeleton_source,
+)
+
+print(report.vertices)
+body.save("tdev_xyuls^lowr_000_u_rigged.ydd")
+```
+
+For body folders where `head_000_u.ydd` carries the skeleton and `uppr/lowr` carry the meshes, use the convenience pass:
+
+```python
+from fivefury import rig_body_folder_jiggle_bones
+
+report = rig_body_folder_jiggle_bones(
+    r"C:\mods\body",
+    output_folder=r"C:\mods\body_rigged",
+)
+print(report.saved_files)
+```
+
+The helper preserves existing skinning and reuses ped-component palettes that already store external skeleton indices. It only adds or adjusts vertex influences around the requested jiggle bones; it does not generate cloth simulation data by itself.
+
 ### Skin a YDR model declaratively
 
 ```python
@@ -661,6 +698,25 @@ for ynd in YndNetwork.from_nodes([node_a, node_b]).build_ynds():
 
 `YndNetwork` computes each node's `area_id` from its world position, assigns local node IDs per area, and resolves links by `target_key`. Use `Ynd.from_nodes(...)` directly when you already know all nodes belong to one area.
 
+### Generate a junction heightmap
+
+```python
+from fivefury import YndNode
+
+node = YndNode(position=(0.0, 0.0, 0.0))
+node.ensure_junction_heightmap(
+    triangles=[
+        ((-1.0, -1.0, 0.0), (1.0, -1.0, 0.25), (-1.0, 1.0, 0.25)),
+        ((1.0, -1.0, 0.25), (1.0, 1.0, 0.5), (-1.0, 1.0, 0.25)),
+    ],
+    bounds=((-1.0, -1.0), (1.0, 1.0)),
+    dim_x=2,
+    dim_y=2,
+)
+```
+
+YND junction heightmaps follow the runtime layout used by GTA V virtual junctions: `position` stores the minimum X/Y sample origin, samples are row-major, the default grid spacing is `2.0` world units, and byte values decode as `min_z + byte * ((max_z - min_z) / 256.0)`.
+
 ## YNV
 
 ### Read and validate a YNV
@@ -706,6 +762,66 @@ print(paths[0].name)
 
 This is intentionally a basic geometry partitioner, not a full navgen pipeline. It does not yet generate advanced navigation semantics such as cover, climb/drop adjacencies, portals, or point placement.
 
+## YED
+
+`YED` files are expression dictionaries used by peds through expression set metadata. FiveFury exposes expressions, typed tracks, streams, semantic instruction operands, variables, and spring blocks:
+
+```python
+from fivefury import YedTrackFormat, read_yed
+
+yed = read_yed("ambient.yed")
+breasts = yed.require_expression("breasts")
+
+print(breasts.spring_bone_ids)
+print([track.format for track in breasts.tracks])
+for stream in breasts.streams:
+    for instruction in stream.instructions:
+        print(instruction.name, instruction.operands)
+```
+
+Small spring dictionaries can be built declaratively:
+
+```python
+from fivefury import YedTrackFormat, create_yed, save_yed
+
+yed = create_yed("breasts")
+expr = yed.require_expression("breasts")
+expr.ensure_spring(0xFC8E)
+expr.ensure_spring(0x885F)
+expr.ensure_track(0xFC8E, format=YedTrackFormat.VECTOR3)
+
+yed.validate()
+save_yed(yed, "ambient_custom.yed")
+```
+
+Existing spring descriptions can be cloned when a custom skeleton keeps the same physics shape but adds new bone tags:
+
+```python
+yed.clone_breast_springs_to_glutes(
+    left_breast=0xFC8E,
+    right_breast=0x885F,
+    left_glute=0x40B2,
+    right_glute=0xC141,
+)
+```
+
+Complex expression streams are currently preserved and decoded at opcode level. Full semantic editing of every stream instruction is intentionally more conservative because those bytecode operands need to stay 1:1 with the game VM.
+Streams can also be authored with semantic instructions for the supported VM layouts:
+
+```python
+from fivefury import YedInstruction, YedInstructionType, YedStream
+
+expr = yed.ensure_expression("face")
+expr.streams.append(YedStream.raw_stream("main", depth=2, data3=b""))
+expr.streams[0].instructions = [
+    YedInstruction(YedInstructionType.PUSH_FLOAT, operands={"value": 1.0}),
+    YedInstruction(YedInstructionType.PUSH_VECTOR, operands={"value": (1.0, 0.0, 0.0, 0.0)}),
+    YedInstruction(YedInstructionType.END),
+]
+```
+
+The supported semantic layouts currently cover empty stack/vector ops, float/vector constants, bone track ops, variables, jumps, springs, look-at, and blend op payloads. Unknown or malformed bytecode is still preserved from existing files, but validation reports it before semantic rebuilds.
+
 ## GameFileCache
 
 ### Scan a Game Installation