pmx20.md

PMX (Polygon Model eXtended) 2.0

This is an English description of the .PMX file format used in Miku Miku Dance (MMD).

PMX is the successor to the .PMD format (Polygon Model Data).

PMX files must be read in binary mode as EOF markers may appear in the middle of the file.

Types

Basic Types

Type name	Size (bytes)	Range	Notes	C/C++ type
byte	1	0..255	Usually used for UTF8 strings	uint8_t
short	2	-2^15..( 2^15 - 1 )	Integer, whole numbers	int16_t
int	4	-2^31..( 2^31 - 1 )	Integer, whole numbers	int32_t
float	4	variable	Uses IEEE 754 format	float

PMX Types

N indicates a variable number. The "text" type bytes are either UTF8 or UTF16 encoded depending on the text encoding value in the file entries definition. The "index" type is either a byte, short or int depending on what the header says for that particular field.

Type name	Size (bytes)	Structure	Notes
string	N	byte[N]	Character list, not null-terminated
text	4 + N	int, byte[N]	First int defines "N"
vec2	8	float[2]	2 floating point numbers
vec3	12	float[3]	3 floating point numbers
vec4	16	float[4]	4 floating point numbers
index	1/2/4	byte/short/int	Indexing number, decided by header

The text type can be defined in C++ as such:

typedef struct text_s {
	int32_t    size;
	
	union encoding_u {
		uint8_t *    utf8;  // sizeof( uint8_t ) * size
		int16_t *    utf16; // sizeof( int16_t ) * ( size / 2 )
	};
} text_t;

File Format

- Header

8 bytes

Field	Size (bytes)	Type	Value	Notes
Signature	4	string	"PMX "	Notice the upper case and space
Version	4	float	2.0	PMX version this document describes

- Info

3 bytes

Field	Size (bytes)	Type	Value	Notes
Data Count	1	byte	8	How many "datas" there are
Text type encoding	1	byte	0/1	0 for UTF16, 1 for UTF8
Additional UV count	1	byte	0..4	Number of additional vertex UVs

The data count can be used to extend the file format with additional data, however this is beyond the 2.0 standard specification.

• Data[0] = Vertex
• Data[1] = Face
• Data[2] = Texture
• Data[3] = Material
• Data[4] = Bone
• Data[5] = Morph
• Data[6] = Frame
• Data[7] = Rigid body
• Data[8] = Joint

Signed vs Unsigned values

There isn't a general contract about whether to use signed or unsigned values for indexes. Therefore, the interpretation and processing of those values is implementation-dependant. However, the Root bone in an MMD model, which is the first bone in the hierarchy, it doesn't have a parent (obviously). So, and index of -1 is used to indicate that the bone has no parent (it's like a null reference), if you interpret it as an unsigned value it may produce an unexpected behaviour.

Also, it's incoherent to have a reference to a non-existent vertex. Furthermore, among all the sections this is usually the one with the highest amount of elements. So, it's best to use an unsigned value (for disk usage).

For the rest of sections it doesn't really matter, but signed values should be enough.

Taking into account these considerations I have specified the sign to the table below. (It's a suggestion not an enforcement)

Update: I've noticed that the size of each data section is indicated with an int and it is assumed to be a signed value, therefore it's not possible to index more than 2147483647 elements. However, since each vertex data entry will have an average size 43 bytes. Values near the limit will account to more than 80 Gigabytes. However, using unsigned values for indexes may help to decrease the filesize. For example, using an unsigned short may save up to 2 bytes per each element.

- Index sizes

6 bytes

Field	Size (bytes)	Type	Value	Signed?	Notes
Vertex index size	1	byte	1/2/4	No	Size of vertex index
Texture index size	1	byte	1/2/4	Yes	Size of texture index
Material index size	1	byte	1/2/4	Yes	Size of material index
Bone index size	1	byte	1/2/4	Yes	Size of bone index
Morph index size	1	byte	1/2/4	Yes	Size of morph index
Rigid index size	1	byte	1/2/4	Yes	Size of rigid body index

- Model Info

16 bytes minimum

Field	Size (bytes)	Type
Local character name	4 + N	text
Global character name	4 + N	text
Local comment	4 + N	text
Global comment	4 + N	text

- Vertex Data

4 bytes minimum

Field	Size (bytes)	Type	Notes
Vertex count	4	int	Defines how many "Each Vertex" there are
Each Vertex	N **	-	See "Each Vertex" below

+ Each Vertex

38 bytes minimum

Field	Size (bytes)	Type	Notes
Position	12	vec3	XYZ position
Normal	12	vec3	XYZ normal, should be normalised
UV	8	vec2	XY texture coordinate
Additional UV	16 * N	vec4[N]	XYZW UVs. N is in Entries Definition
Weight type	1	bytes	0 = BDEF1, 1 = BDEF2, 2 = BDEF4, 3 = SDEF
Weight Definition	N	-	See "Weight Definition" below
Edge scale	4	float	Scale of the "pencil" outline on model

Weight Definition

Which weight definition to use is decided by each vertex "Weight Type".

BDEF1

1 byte minimum

Field	Size (bytes)	Type	Notes
Bone index	N	index	The weight of the bone will be 1.0

BDEF2

6 bytes minimum

Field	Size (bytes)	Type	Notes
Bone index 1	N	index	Uses Weight 1
Bone index 2	N	index	Uses calculated Weight 2
Weight 1	4	float	Weight 2 = ( 1.0 - Weight 1 )

BDEF4

36 bytes minimum

Field	Size (bytes)	Type	Notes
Bone index 1	N	index	Uses Weight 1
Bone index 2	N	index	Uses Weight 2
Bone index 3	N	index	Uses Weight 3
Bone index 4	N	index	Uses Weight 4
Weight 1	4	float
Weight 2	4	float
Weight 3	4	float
Weight 4	4	float

SDEF

42 bytes minimum

Field	Size (bytes)	Type	Notes
Bone index 1	N	index	Uses Weight 1
Bone index 2	N	index	Uses calculated Weight 2
Weight 1	4	float	Weight 2 = ( 1.0 - Weight 1 )
C	12	vec3
R0	12	vec3
R1	12	vec3

- Face Data

4 bytes minimum

Field	Size (bytes)	Type	Notes
Face count	4	int	Defines how many "Each Face" there are
Each Face	N **	-	See "Each Face" below

+ Each Face

1 byte minimum

Field	Size (bytes)	Type	Notes
Vertex index	N	index	Acts as indices for vertices

When 3 faces are collected a triangle is made.

- Texture Data

4 bytes minimum

Field	Size (bytes)	Type	Notes
Texture count	4	int	Defines how many "Each Texture" there are
Each Texture	N **	-	See "Each Texture" below

+ Each Texture

4 bytes minimum

Field	Size (bytes)	Type	Notes
File Name	4 + N	text	Image file name for the texture

- Material Data

4 bytes minimum

Field	Size (bytes)	Type	Notes
Material count	4	int	Defines how many "Each Material" there are
Each Material	N **	-	See "Each Material" below

+ Each Material

86 bytes minimum

Field	Size (bytes)	Type	Notes
Local name	4 + N	text	Used as a high-level reference
Global name	4 + N	text	Used as a high-level reference
Diffuse colour	16	vec4	RGBA base colour
Specular colour	12	vec3	RGB specular reflection colour
Specularity	4	float	Specular strength
Ambient colour	12	vec3	RGB ambient shadow colour
Drawing mode	1	byte	Bit mask, see "Drawing Modes" below
Edge colour	16	vec4	RGBA pencil line colour
Edge size	4	float	How thick the pencil line is
Texture index	N	index	Material texture index
Sphere map index	N	index	Sphere map texture index
Sphere map mode	1	byte	See "Shere Map Modes" below
Toon flag	1	byte	0 = texture, 1 = inbuilt
Toon index	N/1	index/byte	See "Toon Index" below
Memo	4 + N	text	Extra information
Face count	4	int	How many faces this material affects

The faces that this material renders is calculated using the face counts of previous materials as a starting offset with the face count of our current material being the ending offset of the face list.

Drawing Modes

Mode	Bit	Notes
Disable culling	0000 0001	Disables back-face culling
Casts shadow	0000 0010	Casts shadow on ground
Casts shadow map	0000 0100	Writes to shadow map
Receives shadow map	0000 1000	Reads from shadow map
Enable edge	0001 0000	Draws pencil outline

Sphere Map Modes

Mode	Value	Notes
None	0	No sphere map
Multiply	1	Multiply blend sphere map
Additive	2	Additive blend sphere map
Subtract	3	Subtraction blend sphere map

Toon Index

Toon Flag	Mode Name	Type	Notes
0	Texture	index	Texture index for toon shading image
1	Inbuilt	byte	Index for inbuilt toon texture

- Bone Data

4 bytes minimum

Field	Size (bytes)	Type	Notes
Bone count	4	int	Defines how many "Each Bone" there are
Each Bone	N **	-	See "Each Bone" below

+ Each Bone

4 bytes minimum

Field	Size (bytes)	Type	Notes
Local name	4 + N	text	Used as a high-level reference
Global name	4 + N	text	Used as a high-level reference
Position	12	vec3	XYZ origin position
Parent bone index	N	index	Index this bone's parent
Transform level	4	int
Bone flag	2	short	Bit mask, see "Bone Flags" below
Bone definition	N	-	See "Bone Definition" below

Bone Flags

Mode	Bit	Notes
Connection	0000 0000 0000 0001
Rotatable	0000 0000 0000 0010
Movable	0000 0000 0000 0100
Display flag	0000 0000 0000 1000
Can operate	0000 0000 0001 0000
Inverse kinematics	0000 0000 0010 0000
-	0000 0000 0100 0000
Add local deform	0000 0000 1000 0000
Add rotation	0000 0001 0000 0000
Add movement	0000 0010 0000 0000
Fixed axis	0000 0100 0000 0000
Local axis	0000 1000 0000 0000
Physical transform	0001 0000 0000 0000
External parent transform	0010 0000 0000 0000

Bone Definition

Each definition depends on if the corresponding flag is set or not.

Connection

Flag Set

1 byte minimum

Field	Size (bytes)	Type	Notes
Connection index	N	index

Flag Unset

12 bytes

Field	Size (bytes)	Type	Notes
Position offset	12	vec3

Add Rotation | Add Move

Flag Set

5 bytes minimum

Field	Size (bytes)	Type	Notes
Additional parent index	N	index
Additional rate	4	float

Fixed Axis

Flag Set

12 bytes

Field	Size (bytes)	Type	Notes
Axis vector	12	vec3

Local Axis

Flag Set

24 bytes

Field	Size (bytes)	Type	Notes
X axis vector	12	vec3
Z axis vector	12	vec3

External Parent Transform

Flag Set

4 bytes

Field	Size (bytes)	Type	Notes
Key value	4	int

Inverse Kinematics

Flag Set

13 bytes minimum

Field	Size (bytes)	Type	Notes
IK bone index	N	index
Iterations	4	int
Limit angle	4	float
Link count	4	int
Each Link	N **	-	See "Each Link" below

+ Each Link

2 bytes minimum

Field	Size (bytes)	Type	Notes
IK bone index	N	index
Do angle limit	1	byte	Boolean flag
Angle limits	N	-	Used when angle limit is 1, see "Angle Limits"

++ Angle Limits

24 bytes

Field	Size (bytes)	Type	Notes
Lower limit	12	vec3
Upper limit	12	vec3

- Morph Data

4 bytes minimum

Field	Size (bytes)	Type	Notes
Morph count	4	int	Defines how many "Each Morph" there are
Each Morph	N **	-	See "Each Morph" below

+ Each Morph

Field	Size (bytes)	Type	Notes
Local name	4 + N	text	Used as a high-level reference
Global name	4 + N	text	Used as a high-level reference
Handle panel	1	byte
Morph type	1	byte	See "Morph Type" below
Morph offset count	4	int	Defines how many "Each Morph Offset" there are
Each Morph Offset	N	-	Depends on "morph type", see "Each Morph Offset"

Morph Type

Mode	Value	Notes
Group	0
Vertex	1
Bone	2
UV	3
Additional UV 1	4
Additional UV 2	5
Additional UV 3	6
Additional UV 4	7
Material	8
Flip	9
Impulse	10

++ Each Morph Offset

Field	Size (bytes)	Type	Notes
Morph offset definition	N	-	See "Morph Offset Definition" below

Morph Offset Definition

These are chosen based on the morph type for the morph offset list.

Group/Flip

5 bytes minimum

Field	Size (bytes)	Type	Notes
Morph index	N	index
Rate	4	float

Vertex

13 bytes minimum

Field	Size (bytes)	Type	Notes
Vertex index	N	index
Position offset	12	vec3

Bone

19 bytes minimum

Field	Size (bytes)	Type	Notes
Bone index	N	index
Move value	12	vec3
Rotation value	16	vec4

UV/Additional UV 1/Additional UV 2/Additional UV 3/Additional UV 4

17 bytes minimum

Field	Size (bytes)	Type	Notes
Vertex index	N	index
UV offset	16	vec4

Material

114 bytes minimum

Field	Size (bytes)	Type	Notes
Material index	N	index
Offset method	1	byte	0 = Multiply, 1 = Additive
Diffuse colour	16	vec4	RGBA base colour
Specular colour	12	vec3	RGB specular reflection colour
Specularity	4	float	Specular strength
Ambient colour	12	vec3	RGB ambient shadow colour
Edge colour	16	vec4	RGBA pencil line colour
Edge size	4	float	How thick the pencil line is
Texture tint	16	vec4	RGBA tint colour for texture
Environment tint	16	vec4	RGBA tint colour for environment map
Toon tint	16	vec4	RGBA tint colour for toon map

Impulse

26 bytes minimum

Field	Size (bytes)	Type	Notes
Rigid body index	N	index
Local flag	1	byte
Move velocity	12	vec3
Rotation torque	12	vec3

- Frame Data

4 bytes minimum

Field	Size (bytes)	Type	Notes
Frame count	4	int	Defines how many "Each Frame" there are
Each Frame	N **	-	See "Each Frame" below

+ Each Frame

13 bytes minimum

Field	Size (bytes)	Type	Notes
Local name	4 + N	text	Used as a high-level reference
Global name	4 + N	text	Used as a high-level reference
Special frame	1	byte
Element count	4	int	Defines how many "Each Element" there are
Each Element	N **	-	See "Each Element" below

++ Each Element

5 bytes minimum

Field	Size (bytes)	Type	Notes
Target type	1	byte	0 = Target Bone, 1 = Target Morph
Target index	N	index	Depends on target type

- Rigid Body Data

4 bytes minimum

Field	Size (bytes)	Type	Notes
Rigid Body count	4	int	Defines how many "Each Rigid Body" there are
Each Rigid Body	N **	-	See "Each Rigid Body" below

+ Each Rigid Body

50 bytes minimum

Field	Size (bytes)	Type	Notes
Local name	4 + N	text	Used as a high-level reference
Global name	4 + N	text	Used as a high-level reference
Related bone index	N	index
Group index	1	byte
Ignore collision group	2	short
Shape type	1	byte	See "Shape Type" below
Shape size	12	vec3
Collider position	12	vec3
Collider rotation	12	vec3
Weight	4	float
Position attenuation	4	float
Rotation attenuation	4	float
Recoil	4	float
Friction	4	float
Operation type	1	byte	See "Operation Type" below

Shape Type

Mode	Value	Notes
Sphere	0	Sphere collider
Box	1	Box collider
Capsule	2	Capsule collider

Operation Type

Mode	Value	Notes
Static	0	"Jelly" style bone follow
Dynamic	1	Real physics
Dynamic and position adjust	2	Real physics affecting bone

- Joint Data

4 bytes minimum

Field	Size (bytes)	Type	Notes
Joint count	4	int	Defines how many "Each Joint" there are
Each Joint	N **	-	See "Each Joint" below

+ Each Joint

9 bytes minimum

Field	Size (bytes)	Type	Notes
Local name	4 + N	text	Used as a high-level reference
Global name	4 + N	text	Used as a high-level reference
Operation type	1	byte	0 = Springy, everything else is null
Operation definition	N	-	See "Operation Definition" below

Operation Definition

How joints move.

Springy

Field	Size (bytes)	Type	Notes
Rigid body index 1	N	index	Index of the first rigid body
Rigid body index 2	N	index	Index of the second rigid body
Position	12	vec3
Rotation	12	vec3
Position constraint lower	12	vec3
Position constraint upper	12	vec3
Rotation constraint lower	12	vec3
Rotation constraint upper	12	vec3
Spring position	12	vec3
Spring rotation	12	vec3