Skip to content

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

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

ltsammy wants to merge 6 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.

Builds on #1591 and #1608 (GMA packing), so their commits show up here too. Only the last two commits are new: read Source engine models (MDL) with their VTF textures and read and write studiomdl data (SMD). Best reviewed after those; I'll rebase as they're merged.

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.
  • VMT include only follows .vmt files inside the materials root.
  • Own code; Crowbar and SourceIO were only used to learn the layouts.

Settings

  • mdl (read-only) and smd are in the 3D model category, Games field.
  • Schema step 97 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;
    • 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)

GMA versions 1 to 3 unpack to a folder or any archive. Every name is checked
before anything is written, the entries are capped and each size must fit in
what is left of the addon; every file's CRC is checked (0 from gmad -nocrc is
not). An addon.json with the title, description, type and tags is written
beside the files, as gmad reads it to pack the folder again.

GMA is read-only here and in the Games field; .gma files learn the archives
donut (schema 95). Part of KnifeLemon#1526.
The directory file of a Valve pak (versions 1 and 2) unpacks to a folder or
any archive: the files' preload bytes and their data, in the directory file or
in the _000.vpk ... parts next to it, every CRC checked. A data part dropped on
its own is refused with the name of its directory file; a missing part names
the part. A PS Vita package, a ZIP under the same extension, goes to 7-Zip.

Every name is checked before anything is written; the tree is capped at 256 MB
and the entries at the archive limit, preload bytes must lie inside the tree
and parts are _000 to _999.

VPK is read-only and in the Games field; .vpk files learn the archives donut
(schema 95). Part of KnifeLemon#1526.
The custom textures, models and sounds packed into a Source engine map are a
ZIP in its pakfile lump (lump 40). Filee finds it, Left 4 Dead 2's lump order
included, copies it out and 7-Zip unpacks it, so a map extracts or converts to
any archive. A map without packed files, a compressed pakfile lump and a
Quake or GoldSrc map are refused with a message saying so.

BSP is in the Games field; .bsp files learn the archives donut (schema 95).
Part of KnifeLemon#1526.
A folder, a ZIP of one or the files dropped onto Compress into one archive
pack into a GMA as gmad does: addon.json for the title, type, tags and
ignores, only the files on gmad's whitelist, lower-case names, a CRC per file
and over the whole addon. A folder with nothing Garry's Mod loads is refused.

GMA becomes writable; the GMA preset joins the game packs in the palette after
MRPACK, not a donut (schema 96). Part of KnifeLemon#1526.
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.

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

An MDL becomes a reference SMD as Crowbar decompiles it: 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 97). Part of KnifeLemon#1526.
@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.

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