Metadata-Version: 2.4
Name: valvemdl
Version: 0.0.2
Summary: A library to parse .MDL files (model files for the Source engine).
Home-page: https://pysourcesdk.github.io/ValveMDL/
Author: Maxime Dupuis
Author-email: mdupuis@hotmail.ca
License: gpl-3.0
Project-URL: Documentation, https://pysourcesdk.github.io/ValveMDL/
Project-URL: Github, https://github.com/pySourceSDK/ValveMDL
Keywords: mdl,vvd,vtx,studiomdl,source,sourcesdk,valve
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: construct
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ValveMDL

[![License](https://img.shields.io/github/license/pySourceSDK/ValveMDL.svg)](https://github.com/pySourceSDK/ValveMDL/blob/main/LICENSE)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/valvemdl.svg)](https://pypi.org/project/valvemdl/)
[![Platform](https://img.shields.io/badge/platform-windows%20%7C%20linux%20%7C%20macos-lightgrey.svg)](https://pypi.org/project/valvemdl/)
[![PyPI version](https://img.shields.io/pypi/v/valvemdl.svg)](https://pypi.org/project/valvemdl/)
[![CI](https://github.com/pySourceSDK/ValveMDL/actions/workflows/CI.yml/badge.svg)](https://github.com/pySourceSDK/ValveMDL/actions/workflows/CI.yml)

A python library to read and write `.mdl` files, the model format of the Source
engine, along with their `.vvd` and `.vtx` companions.

ValveMDL is about serialization and nothing else. It will read a model apart and
put it back together; it will not transform meshes, render anything, or convert
to other formats.

ValveMDL reads and writes all three files. Across a stock Team Fortress 2
install -- 9,858 models spanning format versions 44 to 48 -- a model read apart
and written back is byte-for-byte identical to what studiomdl produced, with a
single exception caused by orphaned data in one shipped file. See the
[documentation](https://pysourcesdk.github.io/ValveMDL/) for the structure by
structure detail.



## Installation

```bash
pip install valvemdl
```

## Usage

```python
from valvemdl import Mdl

mdl = Mdl('models/props_farm/ambulance.mdl')

mdl.version         # 48
mdl.name            # 'ambulance.mdl'
mdl.header.numbones # 3
```

A model is really a set of files. An mdl contains no vertices and no triangles;
those live in the `.vvd` and `.vtx` next to it, tied together by a checksum.
Opening an mdl notices which of them are present but does not read them until
you ask:

```python
mdl.sidecar_paths   # {'.vvd': '...', '.dx90.vtx': '...', ...}
mdl.vvd             # parsed now, cached after
mdl.get_vtx('.sw.vtx')
```

## On versions

Team Fortress 2 ships mdl versions 44, 45, 46, 47 and 48 -- five variants of the
same format, in the same game. Version 48 accounts for about 91% of them.
`studiohdr_t` is unchanged across that whole range.

ValveMDL is evidence driven: a structure is supported once it has been read out
of real files and cross-checked against the Source SDK, and not before. Gaps are
left as gaps rather than guessed at.

## Contributing

Issues and pull requests are welcome. Be pythonic, document and test your code.
That's all.

One extra rule applies here, because ValveMDL is as much a format reference as it
is a library: **do not guess.** Every field, flag and version rule should trace
back either to the Source SDK or to bytes observed in real model files. If
something is unknown, say that it is unknown.

## License

[GPLv3](LICENSE)
