The program needed Windows. The library underneath it needed a runtime.

The Situation

FiveM servers hand out animation packs as .ycd files. On Windows you open them with CodeWalker, export XML, and import that into Blender through Sollumz — five minutes with a GUI on a well-worn path.

Move to Linux and the path disappears at the first step. CodeWalker is a WinForms application, and the standard advice is Wine, a Windows VM, or giving up on the pack — none of which is a pipeline you want to run 556 times.

We had a folder of animations and weapon models from a FiveM server, no Windows machine, and a Blender install. The expectation was a fight. The reality was that the window was the only Windows part.

Act I: The Tool Is a Library With a Window Attached

.ycd is a RAGE resource: a 16-byte RSC7 header followed by a deflate stream. CodeWalker parses it, and CodeWalker’s parser is not in the GUI. It is in CodeWalker.Core, which targets netstandard2.0 and therefore runs on Linux under the modern .NET runtime.

Two calls do the whole job:

var ycd = RpfFile.GetResourceFile<YcdFile>(File.ReadAllBytes(path));
File.WriteAllText(outXml, YcdXml.GetXml(ycd));

That is the same XML the GUI’s export button produces, built by dotnet, with no Wine.

The second half had its own problem. Sollumz, the Blender add-on for GTA assets, imports a clip — but only from that XML. Point it at a binary .ycd and it declines, and its parser library has no binary reader either. So the pipeline is two steps: binary to XML, XML to Blender.

One 40-line C# tool and one headless Blender script, and the Windows dependency is gone.

Act II: 556 Files, 380 Animations

The resource tree held 556 .ycd files. Hashing turned 556 into 380: the same emote ships twice, once under the roleplay emote menu and once under a standalone animation menu. Dedupe by content, never by filename.

stage count
.ycd files found 556
unique by SHA-1 380
decoded to XML 380
GLB produced 379
animation clips 858
total size 134 MB

The one file without a GLB is a 90-byte stub with no clip data. The rest become a rig plus one named action per clip.

Act III: Sixteen Files That Were Not Resources

Sixteen files came back with a decompression failure. The message was short and unhelpful:

unsupported compression method

They had the right size and the right extension, but no RSC7 magic at all, and a first block of:

00 00 00 00 01 00 00 00 00 40 00 50

That is a resource whose header and deflate stream were already stripped, leaving the raw system stream the game would have inflated at load. The fix is a fallback, not a repair: when the magic is absent, read the block straight out of the buffer.

var reader = new ResourceDataReader(data.Length, 0, data);
var ycd = reader.ReadBlock<ClipDictionary>();
ycd.InitDictionaries();

A magic-number check that only accepts the happy path turned sixteen valid files into “corrupt” ones. Check for the format, not for the four bytes you like.

Act IV: The Quaternion That Was Not a Conjugation

The Blender side was slow: 48 clips took 165 seconds, every keyframe going through Python objects. Replacing that loop with numpy is straightforward — sample the channels, transform them all at once, write with foreach_set.

Straightforward and wrong. The replacement put the head at 2.09 m in a standing pose where the reference implementation put it at 1.58 m.

The transform re-bases rotations from RAGE channel space into pose space, and Sollumz does it with quat.rotate(transform_matrix) per keyframe. All three obvious readings are “equivalent” rotations, so each passes an identity test. On real data they diverge:

form first quaternion
reference output 0.99928, -0.03636, 0.00971, -0.00445
r q r⁻¹ (conjugation) 0.99157, -0.03725, 0.00529, -0.124
Matrix(M3 @ q.to_matrix()) 0.99928, -0.03636, 0.00971, -0.00445

Quaternion.rotate(matrix) is not a conjugation. It left-multiplies the rotation matrix, which in quaternion form is the Hamilton product r ⊗ q. One line, no sandwiches.

The lesson is not about quaternions. It is that a re-implementation which “must be mathematically equivalent” has to be diffed against the reference on real channel values before it is trusted. Identity inputs are invariant under every wrong version of a rotation transform, so they prove nothing.

Act V: The File That Was 16.7 MB

With the math fixed, export became the problem: an 89-second dance clip produced a 16.7 MB GLB, against 3.09 MB the slow way.

The cause is a flag that does less than its name. export_optimize_animation_size collapses redundant keyframes, but only on baked data. Export with export_force_sampling=False and Blender writes every fcurve key verbatim, optimization or not. That clip carried 1.23 million keys — 3,340 frames across 369 animated channels — and every one of them shipped.

Sampling everything is the known fix, and roughly ten times slower on a 549-bone skeleton. Better at the source: drop keys that repeat the previous value, and skip bones that never leave rest.

export size
direct, unpruned 16.7 MB
baked with sampling 3.087 MB
direct, pruned 3.086 MB

Pruning is lossless with linear interpolation: maximum bone-position delta against the unpruned export was 0.08 mm. The pack went from 352 MB to 134 MB without changing what the animations do.

Worth admitting: an earlier 48-clip measurement said direct export was smaller than baked, 19.6 MB to 10.4 MB, and I generalised it. True for short clips, reversed on an 89-second one. Measure the longest file, not the average.

Act VI: The Meshes Came Along

Weapon models are .ydr drawables, and their XML is the same family as the clips, so the second half cost one parser instead of a second toolchain: 71 weapons, 148 meshes, 363,502 polygons, rebuilt with the real skeleton from each file and weights lifted from the vertex buffer.

One trap repeated Act III. Two drawables write their vertex stream as <Data2>, so a <Data> regex grabbed the index buffer — silently, because those files had equal vertex and index token counts. The tell: two weapons importing as empty rigs.

Skinning hides an indirection: BlendIndices indexes that geometry’s own <BoneIDs> list, not the skeleton, and BlendWeights are 0-255 — resolve and normalise or every model collapses onto its root bone. Blender adds two more: UVs are per loop, not per vertex, and GTA textures need V flipped.

The animation side was the interesting half: across 108 bone tags in the weapon clips only 33 belong to a gun, the rest are ped bones. Those clips animate the character holding the weapon, so they belong on a 549-bone rig, not a per-weapon skeleton — which is how 103 clip files produced 1,068 actions.

Receipts

check result
parser runtime CodeWalker.Core, netstandard2.0, .NET SDK 10.0.404 on Linux
Sollumz against binary .ycd refuses; XML only
szio 1.4.0 no binary .ycd reader
556 sources 380 unique after SHA-1 dedupe
16 headerless files no RSC7 magic, raw stream, fixed with ResourceDataReader fallback
wrong quaternion form head at 2.09 m where reference gives 1.58 m
right form max delta 1e-5 against reference
mj_thriller unpruned / pruned / baked 16,697,452 / 3,086,308 / 3,086,464 bytes
pose delta after pruning 0.08 mm
pack size 352 MB to 134 MB
library 386 GLB files, 990 clips, 154 MB
drawables 71 weapons, 148 meshes, 363,502 polys, 319,981 verts
<Data2> trap 2 drawables parsed their index buffer as vertices
weapon clips 33 of 108 bone tags are gun bones; the rest are ped
weapon blend 1,068 actions, all 148 meshes skinned
unresolved full rebuild 1,219 s vs 199 s for the same set; output verified, so a perf anomaly not a correctness one

Takeaway

A Windows-only tool is usually a portable library with a Windows shell around it. Before installing Wine, check what the GUI calls — a netstandard assembly runs anywhere.

When you replace a reference implementation with a vectorised one, diff it on real values from a real file: every wrong rotation transform passes an identity test. And when a glTF export is enormous, check whether the optimizer applies to the mode you chose — deduplicating keys before export beat both the bloated direct path and the slow baked one, at a tenth of the runtime.

What to Run

# binary .ycd -> CodeWalker XML, then XML -> Blender actions + GLB
ycd2xml pack/emote_01.ycd out/emote_01.xml
ycd2blend pack/emote_01.ycd --out ~/blends --glb

# a whole resource tree: hash-dedupe, N headless Blender workers
pack_convert.py "<server>/resources" ~/pack --workers 6 --glb-only
# the flags that matter on long clips: no sampling, then prune keys yourself
bpy.ops.export_scene.gltf(filepath=path, export_format="GLB",
    export_animations=True, export_animation_mode="ACTIONS",
    export_force_sampling=False, export_optimize_animation_size=True)