Blend2Bin - MTM2 BIN Import/Export for Blender (formerly Monvert)
=================================================================

#(11/08/26): v0.21.0: merged the upstream 13_1 add-on (Jpez1432 / OG_RuDeE) and checked everything against the game's own
tool contracts (engine 3D.H, TOOL_CONTRACT.md, ENGINE_LIMITS.md, the Monvert handover). What that means for you:

FACE TYPES (Object Data Properties > MTM2 Mesh Tools, or BIN Tools > Set Face Type). The list is every type the game's
GPU path draws: 0x18 standard, 0x29 shiny (tick Smooth normals or it lights flat), 0x0E unlit, 0x34 unlit Z, 0x11 and
0x33 cutouts, 0x38 camera-facing lit cutout (trees), 0x40 material facet, the legacy 0x1E and 0x22, and the flat colour
types 0x19 and 0x05 (one colour per material, from the material's Viewport Display colour). Anything else would send
the whole model to the old software renderer, so it is not offered. Faces are no longer written as BinEdit-only
groups: the face type you set is what the game gets.

MTM2 MATERIAL (Material Properties). Presets Glass, Mesh and Foliage, or Custom with every flag. A material with a
preset exports its faces as 0x40 with one MRGL_MATERIAL record, written once however many objects use it. The flags
are kept exactly through import and export, including bits this add-on does not know. Export refuses a Tint with a
zero channel (the face renders black) and warns about Tex Solid on an image without alpha, Reflect with no
reflectivity, and so on. Normal Map Strength other than 1.0 writes MRGL_MATERIAL2 (BinEdit cannot open that yet).

TEXTURE NAMES. Still the material name plus .RAW (Blender's .001 suffix is dropped). Names longer than 15 characters
are written as MRGL_TEXTURE64 instead of being cut off; that needs a game / BinEdit from 2026-08-12 or later. A stem
over 23 characters cannot fit a POD and the export refuses it, naming the material. Keep stems to 18 so the _N map
still fits. Names ending in _N or _AO are reserved for the maps below.

TEXTURES. Export Textures writes PNG (full colour, what the game loads first), RAW/ACT, or both. A .RAW is always 32,
64 or 256 square (the only sizes the game loads), with a Median Cut palette and optional dithering, or your existing
.ACT if there is one. Transparent pixels become palette black (the game's colour key) and no opaque pixel is allowed to
turn black. Import no longer writes PNG files into your ART folder - the game would load them ahead of the .RAW - the
converted texture is packed in the .blend instead, with black as transparent.

NORMAL MAPS. Import finds ART\<texture>_N.PNG / .TGA and wires it up (the game's maps are DirectX, green down; the
import adds the green flip Blender needs). Export Normal Maps writes <texture>_N.PNG from the material's Normal Map
node, flipping green if you painted it in Blender's convention, or generates one from the colour image.

ANIMATED BINs. Shape keys are keyframes: Export as Animated writes <NAME>_00.BIN, _01.BIN ... and the chosen file as
the keyframe control BIN in the game's exact layout (up to 16 frames with 15-character names; more uses the 64-frame
record, which needs a 2026-08-11 game). Import reads both back as shape keys; the MTM2 Keyframes tab in the 3D view
side bar scrubs through them.

PODs. Import reads every model in a .POD (extracted next to it). Export can also write <MODEL>.POD with MODELS\ (the BIN,
its frames and .SRF) and ART\ (each texture's PNG/TGA/RAW/ACT and its _N/_AO maps). Names over 31 characters stop the
POD rather than being cut.

ALSO: animated textures (MRGL_TEXTURECYCLE) and flat colours survive import/export, stored normals survive a round trip
(set Smooth normals), duplicate faces in stock models are kept, and anything the game itself would stop reading at is
reported on import instead of silently dropped.

#(11/08/26): v0.20.1: renamed Monvert -> Blend2Bin. The add-on installs as the folder 'blend2bin'. Disable and remove
the old 'monvert' add-on first - both register the same operators. The Fallback Art Directory preference is stored per
add-on, so set it again after switching. Nothing about the exported files changes.

#(8/4/26): (RuDeE) v3: Added new item "BIN Tools" to Blender menu bar allowing you to choose the face type of whatever mesh(es) is selected in the Scene Collection window in Blender. This makes / changes the Custom Object Property implemented for MTM2 face types implemented by Jpez in earlier versions.

#(7/29/26): (Jpez1432) v2: Moved options to export dialog, automatically scales texture 64/256, add default face type, manual face type entry.

#(7/29/26): (Jpez1432) v1: Added texture loading, selection export with optional texture repacking/resize and default art directory.

I implemented texture loading/conversion in blender with a resize option if importing from another model. I also included
the ability to repack the raw/acts and resize as necessary. I also added automatic art folder detection. Manual face type selection per mesh/texture
Included adding the ability to save only selected objects. Hopefully this makes it even easier, haven't tested thoroughly but seems to work on stock trucks. 
Loads MetalCr2 if needed as well, Keep on truckin'

-Jpez1432

#(7/27/26): Blender bin importer and exporter based on J. Pezold's open-source Monvert bin converter: https://github.com/jpez1432/Monvert

I hope this will help model making go much more smoothly. Enjoy!

-RuDeE

Installation and Use:

To install in Blender, go Edit >> Preferences >> Add-ons and drag and drop the zip file there. 

Importing:

The importer creates a model in blender with one "part" per texture and converts raw files from the ART/ directory to png for use in Blender.

Beware: Some junk faces may be created by the import. Inspect your parts and remove any unwanted extra faces. I have only seen this once so far, but something to look out for.

Exporting:

For truck models, make sure names are all caps, especially if you will be creating truck pods by hand. I learned this the hard way. :D

Face types must be set in BinEdit. After opening your bin there, select all faces and go Groups >> Set Group Face Type.

The exporter will create a bin for whatever the active piece is in Blender. I left it like this in case people want to work with multiple parts in blender, export one by one, use different face types for each part, and recombine in BinEdit. I don't know another way at the moment. 

If you just want to export the model as a whole (especially if all faces will be of the same type in your model), just select all the pieces of your model in Blender (press a), right click and choose Join. Export after this, and the entire model will be exported.

In BinEdit, if you want to save some verts you can always go Vertex >> Merge close vertices... and merge them. I have not found this necessary in my tests with MTM2 Beta 0.49.

Textures:

The texture name written in the bin is the material name (with .raw extension) from Blender (not the file name of the png, for example). If you are using pngs in Blender, you will need to convert them to raw, using e.g. dummiesman's Triraw tool (drag and drop). I left this functionality out, since I figure people making MTM2 mods are familiar with raw files, and I didn't want my tool to write over anyone's art files.

Possible glitch: 

In my most recent tests, I haven't run into this issue, but if Traxx or the game is complaining about textures, open your model in BinEdit, and do as follows:

For each texture, go to Textures >> Replace, replace the texture with something not in your list, click ok, then go and replace it back. Do this for each texture, then test. 

My only guess is the exporter may occasionally not write the texture name correctly in the bin. BinEdit doesn't seem to care, but Traxx and the game do. If you choose eight letter uppercase texture names, you should be fine.

#(10/31/26): v0.17: 3D cockpit export / import. File > Export > "MTM2 Cockpit (.cpt + .bin)", File > Import > "MTM2 Cockpit Layout (.cpt)".

Cockpit markers (empties, exact names; 1 Blender unit = 1 ft; positions are taken to the truck's body frame - x right, y up, z forward -
with the same mapping the BIN export uses on vertices):

  EYE                                        the driver's eye. Optional property: fov
  SPEEDO_PIVOT, TACH_PIVOT                   needle pivots.  Properties: zero, rate   (needle angle = zero + value * rate; today: 304.5 / 2.65 and 153.0 / 0.0261)
  WHEEL_PIVOT                                steering wheel pivot.  Property: ratio   (degrees of wheel per degree of steering; today's look: 7)
  SHIFTER_PIVOT                              gear lever pivot.  Property: gear_angles  (six numbers for P R N 1 2 3, e.g. -25,-15,-5,5,15,25)
  GEARLAMP_P GEARLAMP_R GEARLAMP_N GEARLAMP_1 GEARLAMP_2 GEARLAMP_3    lamp quads, the empty is the centre.  Properties: w, h
  SHIFTLIGHT                                 shift lamp.  Properties: w, h, rpm
  MIRROR                                     rear-view glass.  Properties: w, h, zoom (default 65536)

An empty's local +Z is the rotation axis (the four pivots) or the glass normal (MIRROR; point it at the driver's eye). The glass itself must be
a HOLE in the cab mesh - the game draws the rear view behind the cab. Positive angles turn CLOCKWISE seen from the tail of the axis looking
along it; a needle on the dash faces the driver with axis = body +z (away from the driver).

THE GEAR LEVER SWINGS TOWARD AND AWAY FROM THE DRIVER, not sideways: its rotation axis is body x. Orient SHIFTER_PIVOT so its +Z is body x
(Blender -X). Model the lever standing up from the pivot (angle 0 = straight up).

Moving parts are mesh objects PARENTED to their pivot empty (model them where they sit in the cab). Every mesh not under a pivot is the cab.
Each part is exported with its ORIGIN AT ITS PIVOT, in the cab's axes - tilting the empty does not tilt the geometry.

Export asks for a folder and the truck stem (92BF8 for 92BF8.TRK; at most 15 characters, because MODELS\<stem>_CPN1.BIN must fit a pod entry's 31
characters). It writes, all into that one folder:

  <STEM>_CP.BIN                              the cab                  -> pod folder MODELS\
  <STEM>_CPN1.BIN, _CPN2.BIN                 speedo / tach needle     -> MODELS\
  <STEM>_CPW.BIN                             steering wheel           -> MODELS\
  <STEM>_CPS.BIN                             gear lever               -> MODELS\
  <STEM>_CP.CPT                              the layout               -> DATA\

(11/01/26: the .CPT's presence no longer switches it on, see v0.20.0 below.) A missing marker (or a pivot with no mesh under it) is a warning, not an error: that
key is left out of the .CPT and the game uses the default cockpit's value. Textures export like any other BIN export (Export Textures).
Import reads a .CPT back into the marker empties (position, axis, properties) so a cockpit can be changed and exported again; the part models
are not imported - model them under the pivots.

#(10/31/26): v0.18: smooth shading. A mesh object with the custom property mtm2_smooth (any non-zero value) makes the BIN carry an ILIST, one normal per vertex. That is what turns a face of type 0x29 from flat into true Gouraud in the game (0x29 without normals is lit flat). Hard edges need their vertices split, because a vertex has one normal. One mtm2_smooth object is enough: the ILIST covers the whole BIN, so a 0x29 object WITHOUT the property in the same file turns Gouraud too (with this object's own vertex normals). Other face types ignore it, and a model with no mtm2_smooth object exports exactly as before.

#(10/31/26): v0.18.1: Export MTM2 Cockpit warns for each mesh object that has an untextured face: a face whose material slot is empty or whose material has no image texture node (any shader), or an object with face type 0x19 (flat colour). The export itself is unchanged; the warning is the only difference. An untextured face can send the whole model down the game's software draw path, which loses the cockpit's smooth float transform. Give every face a material with an image.

#(10/31/26): v0.19.0: lit lamps as models. A mesh named LAMP_P, LAMP_R, LAMP_N, LAMP_1, LAMP_2, LAMP_3 or LAMP_SHIFT is that lamp's lit piece: a copy of that bit of the cab with a lit texture, face type 0x0E, sitting about 0.01 ft off the surface. Export MTM2 Cockpit writes it as <STEM>_CPLP, _CPLR, _CPLN, _CPL1, _CPL2, _CPL3 or _CPLS.BIN in cab space (no pivot, no offset), leaves it out of the cab mesh, and the .CPT line names it (GEARLAMP_P = <model>, SHIFTLIGHT = <model>, rpm, the rpm coming from the SHIFTLIGHT empty when there is one). With no such mesh the GEARLAMP_x / SHIFTLIGHT empty gives the numeric quad, as before. Export warns for a lamp mesh that is not 0x0E. Import reads both forms; a model line gives an empty with the name in lamp_model, no mesh, and exporting again keeps that line as it was. Build the mesh under its exact name to replace it.

#(11/01/26): v0.20.0: the .TRK now names its .CPT, and that line is what switches a custom cockpit on. No line = the default cockpit, whatever .CPT files exist. Export MTM2 Cockpit cannot edit your .TRK, so it ends by reporting (and printing to the system console) the exact two lines to add to the end of it, each on its own line, for example:
Cockpit
92BF8_CP.CPT
The stem you type still names the exported files. Several trucks can name the same .CPT. An older game never reads these lines.

Credits
=======

Jpez1432 (J. Pezold) is the original author of Monvert, the open-source MTM2 BIN converter this add-on is built on:
https://github.com/jpez1432/Monvert

OG_RuDeE did further additional work on it up to the 13_1 release 
merged in v0.21.0.
