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)
