Skip to content

feat(model3d): Source engine models (MDL) to 3D formats, and studiomdl data (SMD) - #1609

Open
ltsammy wants to merge 2 commits into
KnifeLemon:mainfrom
ltsammy:feat/source-models
Open

ltsammy wants to merge 2 commits into
KnifeLemon:mainfrom
ltsammy:feat/source-models

Conversation

@ltsammy

@ltsammy ltsammy commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

What does this change?

Third of the three PRs agreed in #1526: Source engine models (MDL) to the 3D formats, and studiomdl data (SMD) both ways.

Rebased onto main now that #1591 and #1608 are in, so it's just the two commits: read Source engine models (MDL) with their VTF textures and read and write studiomdl data (SMD).

What it does

  • MDL (versions 44–49) is read together with its .vvd and .dx90.vtx (or .vtx / .dx80.vtx / .sw.vtx), whose checksums must match. Vertex fixups are applied. The result is a static mesh in its bind pose: default body groups, first skin, LOD 0.
    • It converts to GLB, glTF, OBJ, STL, 3MF and PLY, and to a PNG preview.
    • Textures: when the model sits in a models/ folder with a materials/ folder beside it (as in an addon), each material's .vmt gives $basetexture, which is read with the VTF reader from feat(image): read and write Valve textures (VTF) for Garry's Mod and … #1483 and embedded. $nocull makes the material double-sided.
    • Units and axes: Source is Z-up, inches, clockwise triangles and top-left UVs. These become Filee's conventions.
  • SMD:
    • read: the triangles section, one mesh part per material;
    • written from any model as a static prop (one root bone);
    • MDL → SMD is a reference mesh with the full skeleton, bind pose and bone weights, ready for studiomdl or Blender Source Tools.

Hostile files

  • .mdl, .vvd and .vtx are each capped at 256 MB.
  • Every count is checked against a limit (bones, body parts, meshes, vertices, strip groups, strips, indices).
  • Every offset is checked against the file length before it is read.
  • The vertex and fixup tables are checked before a single vertex is added.
  • Every triangle is counted against one budget for the whole model (10,000,000, as many as an SMD may have), in the strip and the list paths, so strip groups or strips that point at the same table can't multiply it. Past it the model is refused with error.document_too_large.
  • A .vmt over 1 MB is not read; the material stays plain.
  • VMT include only follows .vmt files inside the materials root.
  • Own code.

Settings

  • mdl (read-only) and smd are in the 3D model category, Games field.
  • Schema step 100 lets .mdl and .smd learn the 3D models donut and adds an "SMD" preset to the palette after glTF.
  • No donut slots.

Tests

  • Engines (SourceModelTests, SmdTests, built byte by byte by SourceModelBuilder):
    • MDL is read in Filee's axes, units and winding, with and without vertex fixups;
    • textures are found through VMT/VTF, and VMT key values are parsed;
    • MDL → OBJ (with its texture) and GLB;
    • a missing .vvd or one from another build is refused with a clear message;
    • a model whose first mesh claims two strip groups (its own and the next mesh's) counts 4 triangles from a file of 3, and is refused with a limit of 3;
    • a VMT over the cap leaves the material plain;
    • MDL → reference SMD with bones and weights;
    • SMD → model facing the same way as its MDL;
    • other models → static prop SMD and back;
    • a broken SMD is refused with its line number.
  • Core: detection, donut, grade and field, and the migration.

Note: in a new install the 3D model targets sit in the 3D field, which is off by default, so for an .mdl both the Games and 3D fields need to be on to see GLB/OBJ/STL.

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): a Windows x64 build of the PRs, converting Garry's Mod models from an addon

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)

@ltsammy
ltsammy requested a review from KnifeLemon as a code owner November 16, 2026 19:06
@ltsammy ltsammy changed the title Feat/source models feat(model3d): Source engine models (MDL) to 3D formats, and studiomdl data (SMD) Nov 16, 2026

@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. I read the two new commits (MDL and SMD) on top of #1591 and #1608. The reader is careful: every count has a cap, every offset goes through the bounds-checked Bytes, the vertex and fixup tables are checked before a vertex is added, and VMT include can't leave materials/. CI is green. There's one thing to fix before it goes in, plus two small ones.

1. The triangles have no limit across the model

src/Filee.Engines/Models3D/SourceModel.cs, ReadMeshes (lines 215–309): each count is capped on its own (meshes and strip groups at 16,384, strips at 16,384, indices at 12,000,000 per strip group), but the tables are reached through offsets, so many records can point at the same bytes. Nothing limits the product:

  • 16,384 strip-group records (about 400 KB) that all point at one 12M-index table (24 MB) give about 2 × 10¹¹ triangle indices from one mesh.
  • Or, inside one strip group, 16,384 strips (first 0, count = indexCount) that each walk the whole table.

triangles (a List<int>) grows until the process runs out of memory, from a .vtx of a few dozen MB. Other readers stop this kind of input with one budget for the whole file. Could you add a model-wide cap on the triangles read (for example the same 10,000,000 triangles SmdFormat allows), counted as they are added in both the strip and the list paths? When it's exceeded, throw ConversionRefusedException("error.document_too_large", "…"), as OdsReader (line 345) and Ebooks/Book.cs (line 98) do. A test with two strip groups pointing at the same table and a small limit would cover it.

2. VMT files are read without a size limit

SourceModel.cs, Vmt.Read (lines 514–526): File.ReadAllText reads the material and the one it includes, whatever their size. Real VMTs are a few hundred bytes. A small cap (say 1 MB, otherwise the material stays plain, like a VTF that can't be read) keeps a huge file in an addon's materials/ folder from being loaded whole.

3. Comments that credit reference tools

We keep code comments to what the format is, not where the layout was learned, and we don't credit projects that were only read for reference. Could you drop these from the comments (keep the ones that describe compatibility, such as "as gmad writes it" or "as studiomdl reads it"):

  • SourceModel.cs:3–4: "and the readers of SourceIO and Crowbar"
  • src/Filee.Engines/Archives/Vpk.cs:2–3 (from #1591): "as in Valve's vpklib and srctools". Please make this change in this branch, so #1591 can go in as it is.

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 once those two are in. When you rebase this branch for the points above, take the next free number on main for the SMD step. 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.
@ltsammy

ltsammy commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the careful review! All three points are in, and the branch is rebased onto main (#1591 and #1608 are in, so it's just the two commits now).

  1. Triangle budget: SourceModel.Load counts every triangle against one budget for the whole model (10,000,000, the SMD limit), in both the strip and the list path, as each one is added. Past it, it throws ConversionRefusedException("error.document_too_large", …). If the first .vtx layout runs over the budget and the second layout doesn't fit at all, the size refusal is what's reported, not "damaged". The limit is a parameter, and Triangles_are_counted_against_one_budget_even_where_meshes_share_a_table makes the first mesh claim two strip groups (its own and the next mesh's), so 4 triangles come out of a file of 3. It's refused with a limit of 3.
  2. VMT cap: a .vmt (or the one it includes) over 1 MB isn't read, and the material stays plain. There's a test for that too.
  3. Credits: dropped from SourceModel.cs and Vpk.cs (in this branch). I also removed the tool names from the SMD comments, docs and commit messages and kept them about studiomdl.

Schema: MDL and SMD now share step 100 (99 was taken by cxlog), and the grade count is updated. The decompile preset in #1610 takes 101.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants