Skip to content

feat(model3d): decompile Source engine models (MDL) into a QC and SMDs - #1610

Open
ltsammy wants to merge 3 commits into
KnifeLemon:mainfrom
ltsammy:feat/source-decompile
Open

ltsammy wants to merge 3 commits into
KnifeLemon:mainfrom
ltsammy:feat/source-decompile

Conversation

@ltsammy

@ltsammy ltsammy commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

What does this change?

Builds on #1609, so its two commits show up here too. Only the last commit, decompile Source engine models (MDL) into a QC and SMDs, is new. Best reviewed after #1609. Schema step 101.

Follow-up to #1609 for #1526: a Source engine model can now be decompiled into the folder studiomdl builds it from, the way Crowbar does. The "QC + SMD" preset turns a .mdl (with its .vvd, .vtx, .phy and .ani) into a folder named after the model:

File Holds
<model>.qc $modelname, model flags, $surfaceprop, $illumposition, $bbox/$cbox, $bodygroups, $lod/$shadowlod, $cdmaterials, $texturegroup, $attachments, $hboxset/$hboxes, $includemodels, $poseparameters, a $sequence per sequence (animations, blends, activity, fps, options, motion flags, fades, events), $collisionmodel or $collisionjoints (with $jointconstrain), $keyvalues
<body model>.smd one reference SMD per body group model (blank ones are blank)
<body model>_lod<n>.smd a model's triangles at a LOD, only when they differ from the LOD before; dropped models are removemodel
<model>_physics.smd the convex pieces of the .phy
<model>_anims/<animation>.smd every frame of every bone of each animation

How it reads them

  • LODs use the LOD 0 vertices with each LOD's own triangles from the .vtx. This was checked against a six-LOD Garry's Mod vehicle.

  • Animations come from the .mdl, or from the .ani beside it when they're in animation blocks, section by section. Each animated bone can have:

    • a raw rotation (Quaternion64 or Quaternion48) or run-length encoded rotation tracks,
    • a raw position (three half floats) or position tracks.

    Frames are decoded one at a time and written straight into their SMD, so an animation is never held in memory whole. Track values are scaled by the bone's scales and added to its bind pose (except in delta animations). The root motion studiomdl took out (movements) is added back.

  • Physics walks the .phy's IVP ledge trees and turns metres in IVP's axes into inches. Solids named after bones (a ragdoll) are moved from bone space into model space.

  • Not written: flexes (.vta), eyeballs, IK rules and chains, bone controllers and procedural bones. A model with them still compiles from the QC, just without them. Compiling back to .mdl still needs Valve's studiomdl.

Hostile files

  • Everything goes through a shared bounds-checked reader (SourceBytes).
  • These are capped:
    • frames per animation (100,000),
    • bone entries per frame, and track runs,
    • sequences and blend grids (4,096 animations),
    • events, LODs (8), attachments and hitboxes,
    • .phy solids (1,024), ledge-tree nodes (65,536) and points per piece (65,536).
  • The ledge tree is walked without recursion, so a looping tree stops at the node cap.
  • Records can point at the same bytes, so the model as a whole also has budgets. Past any of them the decompile is refused with error.document_too_large:
    • bone poses (frames × bones) over all animations: 50,000,000, checked before anything is written;
    • triangles over every body group model and LOD: 10,000,000, counted in the strip and the list paths;
    • triangles and points over all .phy pieces: 1,000,000 each;
    • hitboxes, animation events and blended animations: 262,144 each over the whole model.
  • File names never name a Windows device: con, prn, aux, nul, com1–com9 and lpt1–lpt9 (with any extension) get a _ in front.
  • A damaged file is refused and the half-written folder removed.
  • Own code throughout.

Settings

  • "QC + SMD" goes in the palette right after "SMD", not on a donut.
  • Schema step 101 adds it to existing libraries.
  • Its target is a folder, so only a .mdl can take it. The name is untranslated like "SMD" and "GMA", so there are no new UI strings.

Tests

  • Engines (SourceDecompileTests): the test model builder now also writes an attachment, a second LOD, a three-frame animation (Quaternion64, Vector48 and an RLE rotation track) with a sequence and an event, and a .phy with one convex piece. The tests cover:
    • the QC lines and the reference, LOD, physics and animation SMDs;
    • the Euler and quaternion round trip;
    • refusing an animation with a million frames, a bone entry that loops, and a collision tree that points at itself;
    • each model-wide budget (bone poses, LOD triangles, events, .phy triangles and points) refusing just past the test model's size, with nothing written;
    • device names getting their _.
  • Core (SourceFormatTests): the v100 → v101 migration (preset after "SMD", not on a donut).
  • Real models: checked separately on three Garry's Mod models (a wiremod gate, a vehicle with 6 LODs and physics, a viewmodel with 6 animated sequences). The decoded animation values match a separate prototype, and the LOD, physics and event output is as expected.

Type of change

  • Bug fix
  • New feature or improvement
  • New format or engine
  • Translation
  • Documentation
  • Build, CI or dependencies

How was it tested?

  • dotnet format --verify-no-changes
  • dotnet test
  • Tried it in the app (what you converted or clicked, and on which OS): decompiled the three models above through the engine on Windows x64; recompiling the QCs with studiomdl not tried yet

Checklist

  • New UI strings are in all src/Filee.App/Assets/i18n/*.json files (none added)
  • New third-party code or binaries are listed in THIRD-PARTY-NOTICES.md (none added)
  • The PR does one thing (unrelated changes go in a separate PR)

@KnifeLemon KnifeLemon left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @ltsammy, this is a big piece of work. The shared SourceBytes reader, the frame, track and ledge-tree caps and the non-recursive tree walk are what we want. I read the new commit on top of #1609. CI's one red job (WebDropJobTests on Linux x64) is a Core test for code this PR doesn't touch; I re-ran it.

Every count has its own cap, but as in #1609, many records can point at the same bytes, so the caps multiply. A .mdl of a few KB can still ask for terabytes of output or all the memory. A decompile needs one budget for the whole model. Could you add one, counted as things are read or written, that refuses with ConversionRefusedException("error.document_too_large", "…") (as OdsReader line 345 and Ebooks/Book.cs line 98 do) when it's exceeded? These are the places:

1. Animations (the biggest one)

src/Filee.Engines/Models3D/SourceAnimation.cs, Decode (lines 51–89) keeps every frame of every bone in a List<Pose[]> before anything is written.

  • An animation needs no data at all to be long: with block 0 and index 0, Locate returns −1 and every frame is the bind pose.
  • So one 100-byte animation record with 100,000 frames on a 1,024-bone skeleton is about 2.4 GB of poses in memory and about 6 GB of SMD text.
  • ReadAnimations (SourceModelDetails.cs) allows 16,384 such records.

Please cap the bone-frames (frames × bones) across all animations; tens of millions is far above any real model. If you can, also write each frame as it is decoded instead of holding them all.

2. Triangles over every body group model and LOD

The point from #1609 applies here across the whole decompile. SourceModelDetails.ReadBodyParts (lines 164–192) calls SourceModel.ReadLodMeshes (SourceModel.cs, from line 240) for up to 512 parts × 512 models × 8 LODs. Strip groups and strips inside each LOD can share one index table. One triangle budget for all of them covers it.

3. Physics

src/Filee.Engines/Models3D/SourcePhysics.cs, ReadSolid (lines 69–96): every leaf of the ledge tree can point at the same ledge (node + I32(node + 4)). So each of the 1,024 solids can hold about 32,000 copies of a piece with up to 32,767 triangles. A cap on the triangles (or points) of the whole .phy covers it.

4. QC entries

These end up in memory and in the QC's StringBuilder:

  • ReadSequences (SourceModelDetails.cs:267): 16,384 sequences × 4,096 events.
  • ReadHitboxes (SourceModelDetails.cs:212): 4,096 sets × 16,384 hitboxes.

Each is up to 67 million entries, and their tables can overlap too. Caps on the totals (all events, all hitboxes) would close this.

5. Small: Windows device names

SourceDecompiler.SafeName (SourceDecompiler.cs:472) keeps a name such as con, nul, aux or com1. Windows treats those as devices, and on Windows 10 even with an extension, so an animation or body model with that name can't be written as nul.smd and the like. Prefixing them with _, as ArchiveSafety.SanitizeSegment does, avoids it.

6. Reference credits in comments

As in #1609, please keep comments to the format and to compatibility ("as studiomdl reads it", "the layout Crowbar writes" is fine). Drop where the layout was learned, for example SourcePhysics.cs:3 ("and SourceIO's reader").

Main has moved

#1585 took schema step 95 on main, so I merged main into #1591 and #1608 and moved their steps to 96 and 97. The VTF preset (#1611) gets 98. SMD and "QC + SMD" take the next two free numbers when #1609 and this PR land. If the renumbering gets in your way, push your fixes as they are and we'll do it before merging.

A Source engine model (versions 44 to 49, with the .vvd and .dx90.vtx beside
it, all three of the same build) becomes a 3D model in its bind pose with its
default body groups, first skin and LOD 0, turned to Filee's Y up,
millimetres, counter-clockwise and bottom-left UVs, so it converts to OBJ,
GLB, STL and the other 3D formats and to a picture. Its textures are found as
Garry's Mod finds them: the .vmt in the materials folder beside the models
folder, its $basetexture decoded from VTF.

Every triangle is counted against one budget for the whole model (10 million),
in strips and lists alike, so strip groups that point at the same table can't
multiply it; a larger model is refused as too large. A material file over
1 MB is not read (the material stays plain).

MDL is in the Games field; .mdl files learn the models donut (schema 100).
Part of KnifeLemon#1526.
… skeleton

An MDL becomes a reference SMD studiomdl can compile again: its bones with
their bind pose, its triangles counter-clockwise with up to three bone weights
per vertex, UVs from the bottom left, in inches, Z up. Any other 3D model
becomes a static prop with one root bone, ready for studiomdl; a reference
SMD's triangles become a model again, so SMD converts to GLB, OBJ, STL and the
rest.

SMD is in the Games field; .smd files learn the models donut and the SMD
preset joins the 3D models in the palette (schema 100, with MDL).
Part of KnifeLemon#1526.
The "QC + SMD" preset turns a .mdl with its .vvd, .vtx, .phy and .ani into the
folder studiomdl builds it from: the QC (body groups, LODs, materials and
skins, attachments, hitboxes, pose parameters, sequences with their events,
collision model or joints, key values), a reference SMD per body group model,
an SMD per LOD that differs, the physics SMD and an animation SMD per
animation.

Animations are decoded from the .mdl or its .ani (raw and run-length encoded
rotations and positions, sections, root motion) and streamed into their SMDs a
frame at a time; the .phy's convex pieces are walked through their ledge
trees. Every count is capped and every offset checked before it is used, and
the model as a whole has budgets: bone poses over all animations (50 million,
checked before anything is written), triangles over all body groups and LODs,
triangles and points over all collision pieces, and hitboxes, events and
blended animations in all. A damaged file is refused and the folder removed;
an oversized one is refused as too large. File names never name a Windows
device (con, nul, com1 ... get a "_" in front).

The preset is in the palette after "SMD", not on a donut (schema 101).
Part of KnifeLemon#1526.
@ltsammy

ltsammy commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Thanks! Everything from the review is in, rebased on the updated #1609:

  1. Animations: SourceAnimation.Decode now yields one frame at a time, and SmdFormat.WriteAnimation writes each frame as it comes, so no animation is held in memory whole. Before anything is written, the bone poses (frames × bones) over all animations are checked against 50,000,000.
  2. Triangles: ReadBodyParts passes one TriangleBudget (10,000,000) through every body group model and LOD. ReadLodMeshes counts against it in the strip and the list path.
  3. Physics: SourcePhysics.Read counts the triangles and points of every piece over the whole .phy (1,000,000 each), so leaves that share a ledge add up.
  4. QC entries: hitboxes over all sets, events over all sequences, and blended animations over all blend grids are each capped at 262,144 for the whole model. I added the blends because they had the same 16,384 × 4,096 shape.
  5. Device names: SafeName puts _ in front of con, prn, aux, nul, com1–com9 and lpt1–lpt9, with or without an extension, the same rule as ArchiveSafety.SanitizeSegment.
  6. Credits: removed from SourcePhysics.cs, SourceModelDetails.cs, the decompiler, the tests and the docs.

All of them refuse with ConversionRefusedException("error.document_too_large", …). Each limit is a parameter, and Animations_lods_physics_and_entries_are_counted_against_model_wide_budgets checks each one just past the test model's size. The three real Garry's Mod models still decompile the same.

Schema: "QC + SMD" is step 101, after #1609's 100.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature New features

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants