MM3D File Format

Contents

• Overview
• File Header
• Data Offsets
• Data Offset Types
• Data Blocks
• Data Block Types
• Example Hex Dump

Overview

This document describes version 1.6 of the MM3D file format. Data that is available only in specific versions will be noted below. All other data is common to every version of the file format. Previous releases of Misfit Model 3D that do not read all data segments should still be able to load model files, though some information may be lost.

The MM3D file format was designed to be easy to extend and easy to read to extract just the information you want. The header will tell you what information is included in the file and give you offsets to the location where the information is in the file.

Data sections have their own header before the data. Each data type is either a fixed size or a variable size. If the data size is fixed (constant, Type B) the data size immediatley preceeds the data block of the data section. If the data size is variable (Type A) the data size preceeds each data element.

MM3D uses Intel byte order (least significant byte first). Bytes are 8 bits. The types specified in the Type fields below are ints (signed integers) or uints (unsigned integers). The type designation is followed by a number which designates the number of bits in that integer. The type may be multiplied by a constant or variable number to get the full length of the field. Variables are generally data fields from earlier sections in the file. In the data chunks there is also a float32 which is a 32-bit floating point number and an ASCIIZ which is every byte up to and including the next null byte. ASCIIZ strings are truncated to 1024 bytes (including the terminating null) if necessary.

As of MM3D version 1.4 (and later 1.3 versions) all text strings are encoded as UTF-8. Versions 1.2 and earlier (as well as early 1.3 versions) used extended ASCII encoding. If you want your MM3D models to be usable in new and older versions of MM3D you should use only standard ASCII characters (0-127) for model object names and texture filenames.

NOTE: Items marked in red are still under development. They will not be finalized until the next revision of the file format is complete. They are provided for reference in the interim and are subject to change without notice.

File Header

The file header is 12 bytes.

Data Offsets

Data offsets are 6 bytes each. The value of [OFFSET_COUNT] in the header specifies how many data offsets are in this section.

The data offsets section is [OFFSET_COUNT] instances of:

Data Offset Types

The following is a list of known data segment types. Types are 16 bits. Bit 15 (0x8000) is a "uniform" flag, meaning data of that type is a fixed (constant) size.

Bit 14 (0x4000) is the dirty flag. If Mifit Model 3D encounters a data segment it does not understand it will keep a copy of the raw data and write that data to a file if the model is saved again. It will add the dirty bit to indicate to other model readers that this data was written by a version of the program that did not understand the data. It is therefore "dirty" and may be inconsistent with the model. Under these circumstances the reader may chose to discard the data or attempt to verify and use it.

The end of file offset is a special offset and indicates the file size. You should always check this value against the file size to be certain that the file is complete. There is no data at the end of file offset.

Type A (variable)

Type B (fixed)

User Defined Blocks

Types 0x0000 through 0x1fff are reserved for Misfit Model 3D defined types. 0x4000 through 0xffff are reserved for the uniform and dirty bit versions of each type. If you want to add a type for your own use it is recommended that you use a value in the 0x2000 through 0x2fff range. Suggestions for types which may be useful to other uses are welcome and may be incorporated into future versions.

Data Blocks

Data Blocks have a header and a data chunk. The data blocks are similar between types A and B. The only difference is how the size of each data element is handled. In Type A the size is included before each data element in the data chunk. In Type B the size is included at the end of the header and before the data chunk itself.

The size of a data element may change. When reading data from an MM3D file it is important to note if the size of the element is different from the expected size. If it is smaller, data at the end of the element has been omitted. If larger, data has been appended to the end of the element's data type and must be skipped over during data parsing. These situations may happen if your filter is reading a file written by a newer or older version of Misfit Model 3D. Data size changes will be rare but should be accounted for.

Type A

Data header:

Data chunk:

Type B

Data header:

Data chunk:

Data Block Types

Meta Data

Version 1.4 and later.

The meta data section contains key/values pairs of ASCIIZ strings. These key/value pairs do not affect model display in any way. These are purely information strings for things like copyright, contact, urls, etc.

Keys are case-sensitive and do not have to be unique (though having two identical keys is bad form).

Vertices

Vertex flags:

Triangles

The triangles section describes the triangular faces of the model. The vertex indices are 0-based indices into the vertex array from the vertices section.

Triangle flags:

Triangle Normals

Version 1.4 and later.

The triangle normals section describes the normals for each face of the model. Each block is composed of a triangle index that indicates to which triangle the normals apply to, followed by three sets (one for each triangle vertex) of three floating point numbers (one for each dimension).

Joints

The joint section describes joints used for skeletal animations. Their orientation information is relative to their parent joint's orientation.

Joint flags:

Joint Vertices

The joint vertices section associates vertices with joints.

NOTE: As of version 1.6 this data is deprecated. Use the Weighted Influences data instead. This data section is maintained for backwards compatibility. Newer files should have this data and the Weighted Influences data. If the Weighted Influences section is present it takes precedence over this data. When writing this data, only one joint per vertex is allowed. The joint with the most influence (highest weight) on the vertex is the joint index that should be used.

Points

Version 1.6 and later.

Points are objects that have a position and orientation. They can be attached to bone joints for animation purposes. Points do not affect model geometry in any way. They are simply reference objects for specifying a location in the model. One potential use for this is bolt points for attaching one model to another (such as tags in MD3 models).

Note that the POINT_JOINT element is deprecated. It should still be set in MM3D files (or -1 if no bone joint assignment). If the point is assigned to multiple bone joints, the joint with the most influence (highest weight) should be used. When reading MM3D files, the POINT_JOINT element should usable, but any data in the Weighted Influences section takes precedence over this value.

Point flags:

Smoothness Angles

Version 1.4 and later.

The joint vertices section associates vertices with joints.

Groups

The groups section groups faces (triangles) for editing or texturing purposes. Textures are applied to groups, so faces must be grouped in order to have a texture applied.

Group flags:

Weighted Influences

Version 1.6 and later.

The weighted influences section describes how vertices and points are assigned to bone joints. Objects can be assigned to multiple bone joints. This is the preferred method to save and load bone joint assignments for vertices and points. New versions of Misfit Model 3D will use this data if it is present and the deprecated data sections if this data is not present.

The type of influence can be automatic (based on the position of the object relative to the bone joint), remainder (100 minus the sum of all other joint weights), or custom (manually entered by the user). If the type is "Remainder" and the sum of the influence of other joints is greater than 100, the remainder value is 0 (it is never negative).

The weight of each influence ranges from 0 to 100. The relative influence of each joint is the percentage of the total influence of all joints. The sum off all influence weights does not have to be 100. For example a single joint with a weight of 80 will have 100% influence. Two joints that each have a weight of 80 will each have 50% influence. One joint with a weight of 40 and another with a weight of 80 will have 33% and 67% influence respectively.

Position Types:

Influence Types:

Texture Projections

Version 1.6 and later.

The texture projection section describes objects that map triangle texture coordinates onto a texture as a cylinder or sphere. The "up" vector defines which direction is the U component of the texture projection. In some cases (such as cylinder) the magnitude of this vector determines the size of the projection area. The "seam" vector indicates where the V texture component starts and 0.0 and wraps back to 0.0 after reaching 1.0.

Projection flags:

None

Projection types:

Texture Coordinates

The texture coordinates section maps the vertices of a triangle onto a material's texture. Texture coordinates range from (0.0, 0.0) to (1.0, 1.0). The origin (0,0) of a texture is the lower-left corner, not the upper-left. Values outside of the 0.0 to 1.0 range are valid.

External textures

The external textures section describes the textures in the model. The textures are assigned to materials which describe the lighting properties. Groups reference materials. Currently there is a 1-to-1 relationship between materials and textures, but this is not required and should not be expected in the future. One texture may be referenced by many materials in later file versions.

Materials

The materials section describes the materials in the model. The materials reference textures and describe the lighting properties. Groups reference materials. Some materials do not have textures. For materials without textures, the MATERIAL_TEXTURE element is still present but the value is ignored. The MATERIAL_FLAGS element indicates if the material has a texture (see below).

Material flags:

The Clamp S and Clamp T values specify whether texture coordinates outside of the 0.0 to 1.0 range should wrap or not. If the bit is set, the texture wraps. If the bit is clear the colors at the edge of the texture are stretched.

Texture Projection Triangles

Version 1.6 and later.

The texture projection section describes objects that map triangle texture coordinates onto a texture as a cylinder or sphere. The "up" vector defines which direction is the U component of the texture projection. In some cases (such as cylinder) the magnitude of this vector determines the size of the projection area. The "seam" vector indicates where the V texture component starts and 0.0 and wraps back to 0.0 after reaching 1.0.

Canvas Background Images

Version 1.4 and later.

The Canvas Background Image section describes background images that appear in canvas views. There can be one background image for each of the six canvas views (Front, Back, Left, Right, Top, Bottom) and each can be scaled and positioned independently. Canvas background images are for editing purposes only and should not be rendered as part of the model itself.

Canvas Background Image View Directions

Skeletal Animations

The skeletal animations section describes the skeletal animations in the model. It includes all frames of all skeletal animations. This mostly consists of animation data and joint keyframes.

Skeletal frame data type:

Skeletal keyframe data type:

Frame Animations

The frame animations section describes the frame animations in the model. It includes all frames of all frame animations. This mostly consists of animation data and vertex positions for each animation frame (each frame is vertex positions for every vertex in the model).

Frame animation frame data type:

Frame animation vertex data type:

Frame Animation Points

Version 1.6 and later.

The frame animations points section describes the location and rotation of points in frame animations.

There is one of these data structures for each point for each animation frame. Frame animation point data type:

Example Hex Dump

This is an example hex dump of a cube with grouped faces. It is color-coded to highlight the different parts of the file.

Key:

• File header green
• Offsets blue
• Vertices dark red
• Faces magenta
• Groups light red