Game Model Format

From Leadwerks Developer Wiki

Jump to: navigation, search

The Game Model Format (GMF) is a 3D model format created by Leadwerks Software in order to provide a simple-to-load binary model format with support for skinned animated meshes.

Contents

Introduction

The GMF (Game Model format) format is Leadwerks' file format for 3D game models. The GMF format has been designed to store animated skinned models in an easy-to-load format that is close to the data format uploaded to the graphics card. Limb hierarchies, matrices, mesh data, animation, and bone weighting are considered common data all applications will treat more or less the same. Other data such as limb names, material names, or physics data can either be stored in a properties block or in an extended block structure designed by the programmer.

The official GMF converters provide functionality to export skinned animated hierarchal models. The gmf format stores (up to) two uv channels/sets.

Converters

Converters are provided to turn .dae, .fbx, .3dw and .obj files into the .gmf format.

  • .dae: The COLLADA open standard XML schema for exchanging digital assets among various graphics software applications.
  • .fbx: "FBX is technology and a file format (.fbx) owned and developed by Autodesk. It is used to provide interoperability between digital content creation applications." It is exportable by: Autodesk® MotionBuilder®, Autodesk® Maya®, Autodesk® 3ds Max®, Autodesk® Softimage® (Autodesk® Crosswalk software initiative) and Autodesk® Mudbox™ 2010
  • .obj: Most modeling packages support the Wavefront Object format. This format doesn't support animation and/or skinning data, only static meshes and materials.
  • .3dw: The file format of 3D World Studio. Static mesh data and materials only.

There's also an UU3D export plugin available. Ultimate Unwrap 3D reads nearly every 3D model format and is also an advanced uv unwrapping program.

Pipeline

Some pipelines explained:

Note: The converters (...2gmf.exe) found in the "<LE install folder>\Tools\" directory are used by dragging the file that should be converted onto them. The converted file will have the same file name with the new extension.

Unwrap3D Export

There's a UU3D gmf export plugin provided. See Unwrap3D GMF Exporter.

FBX to GMF

Use fbx2gmf.exe.

3DW to GMF

Use 3dw2gmf.exe.

Collada to GMF

Use the provided dae2fbx.exe converter first, then convert the fbx file to gmf using fbx2gmf.exe.

3D Studio Max Export

  • 3D Studio Max can export .gmf files directly with the .gmf export max script (which actually exports fbx and then converts this straight away).
The script is found under "<LE install folder>\Plugins\3dsmax" and is called "savegmf.ms". For installation, it should be copied to "<3dsmax root>\Scripts\Startup".
It can then be used by clicking the "MAXScript" button found under the "Utilities" tab. Choose the "Export Leadwerks GMF" utility from the list:
Image:3dsmaxexportgmfscript.jpg
And finally, press the export button.
  • There's also a 3dsmax to gmf exporter being developed by ArBuZ from the community.
It can be found here.

OBJ to GMF

Use obj2gmf.exe.

GMF SDK

The GMF SDK provides a programming API with which GMF files can be constructed and saved. It is not necessary to even know what the actual GMF format looks like.

gmfsdk1.01.zip, containing the gmfsdk.dll, a BMX API, a C/C++ API and some samples can be found in the dev. area to write custom converters/exporters.

Classes

  • TGMFNode
    • TGMFSurface
    • TGMFEntity
      • TGMFMesh
      • TGMFBone

Commands

GMFNodeSetProperty

BlitzMax: GMFNodeSetProperty(node:TGMFNode,key:Byte Ptr,value:Byte Ptr)

GMFEntityFree

BlitzMax: GMFEntityFree(entity:TGMFEntity)

GMFEntitySetPositionRotationScale

BlitzMax: GMFEntitySetPositionRotationScale(entity:TGMFEntity,x:Float,y:Float,z:Float,pitch:Float=0.0,yaw:Float=0.0,roll:Float=0.0,sx:Float=1.0,sy:Float=1.0,sz:Float=1.0)

GMFEntitySetMatrix

BlitzMax: GMFEntitySetMatrix(entity:TGMFEntity,mat:TMat4)

GMFBoneCreate

BlitzMax: GMFBoneCreate(parent:TGMFEntity)

GMFMeshCreate

BlitzMax: GMFMeshCreate(parent:TGMFEntity)

GMFMeshAddSurface

BlitzMax: GMFMeshAddSurface(mesh:TGMFMesh)

GMFSurfaceAddVertex

BlitzMax: GMFSurfaceAddVertex:Int(surface:TGMFSurface,x#,y#,z#,nx#=0.0,ny#=0.0,nz#=0.0,u0#=0.0,v0#=0.0,u1#=0.0,v1#=0.0,r:Int=255,g:Int=255,b:Int=255)

GMFSurfaceFindVertex

BlitzMax: GMFSurfaceFindVertex:Int(surface:TGMFSurface,x#,y#,z#,nx#=0.0,ny#=0.0,nz#=0.0,u0#=0.0,v0#=0.0,u1#=0.0,v1#=0.0,r:Int=255,g:Int=255,b:Int=255)

This command will first search for a vertex with the specified values and return it if found. If no matching vertex is found, a new vertex will be created and returned. This function is slower than AddVertex but can result in more optimized meshes.

GMFSurfaceAddTriangle

BlitzMax: GMFSurfaceAddTriangle(surface:TGMFSurface,a:Int,b:Int,c:Int)

GMFMeshSaveFile

BlitzMax: GMFMeshSaveFile(mesh:TGMFMesh,path$)

GMFSurfaceCalculateBinormalsAndTangents

BlitzMax: GMFSurfaceCalculateBinormalsAndTangents(surface:TGMFSurface)

GMFSurfaceCalculateNormals

BlitzMax: GMFSurfaceCalculateNormals(surface:TGMFSurface,mode:Int=0)

GMFEntityAddPositionKey

BlitzMax: GMFEntityAddPositionKey(entity:TGMFEntity,x:Float,y:Float,z:Float,time:Int)

GMFEntityAddQuaternionKey

BlitzMax: GMFEntityAddQuaternionKey(entity:TGMFEntity,x:Float,y:Float,z:Float,w:Float,time:Int)

GMFEntityAddRotationKey

BlitzMax: GMFEntityAddRotationKey(entity:TGMFEntity,x:Float,y:Float,z:Float,time:Int)

GMFSurfaceAttachVertex

BlitzMax: GMFSurfaceAttachVertex(surface:TGMFSurface,v:Int,bone:TGMFBone,weight:Float)

Specification

The file is split up into a sequence of 'blocks', each of which can contain data and/or other chunks. Each chunk is preceded by a 12 byte header: 

int	tag		constant block id
int	subnodes	number of subnodes
int	length		4 byte block length (not including this header or subnodes data)

If a chunk contains both data and other blocks, the data always appears first and is of a fixed length. A file parser should skip unrecognized blocks’ data.

Blocks

Node			Data			Description				
GMF_FILE		int			version (should be 1)

GMF_NODE		float[16]		4x4 matrix

GMF_MESH		float[16]		4x4 matrix

GMF_BONE		float[16]		4x4 matrix
			int			bone ID
 
GMF_SURFACE

GMF_PROPERTIES		int			number of keys
			string[n*2]		keyname / keyvalue pairs

GMF_ANIMATIONKEYS	int			number of frames
			float[16]		4x4 matrix	

GMF_VERTEXARRAY		int			number of vertices
			int			data type (GMF_POSITION, GMF_NORMAL, GMF_TEXTURE_COORD, 
						GMF_COLOR, GMF_TANGENT, GMF_BITANGENT, GMF_BONEINDICE, 
						or  GMF_BONEWEIGHT)
			int			type (GMF_BYTE, GMF_UNSIGNED_BYTE, GMF_SHORT, 
						GMF_UNSIGNED_SHORT, GMF_HALF, GMF_INT, GMF_UNSIGNED_INT, 
						or GMF_DOUBLE)
			int			number of elements
			data[n]			vertex data.

GMF_INDICEARRAY 	int			number of indices
 	 	 	int	 	 	mode (GMF_POINTS, GMF_LINE_STRIP, GMF_LINE_LOOP, GMF_LINES,
						GMF_TRIANGLE_STRIP, GMF_TRIANGLE_FAN, GMF_TRIANGLES, GMF_QUAD_STRIP,
						GMF_QUADS, or GMF_POLYGON)
 	 	 	int 	 		type (GMF_BYTE, GMF_UNSIGNED_BYTE, GMF_SHORT, GMF_UNSIGNED_SHORT,
						GMF_UNSIGNED_SHORT, GMF_HALF, GMF_INT, GMF_UNSIGNED_INT, or GMF_DOUBLE)
			data[n]			indice data

Tips

Although the vertex array format is flexible enough to suit many data format schemes, the following table describes the suggested data format for .gmf exporters: 

Data Type			Type			Elements
GMF_POSITION			float			3 (xyz)
GMF_NORMAL			float			3 (xyz)
GMF_TEXTURE_COORD		float			2 (uv)
GMF_TANGENT			float			3 (xyz)
GMF_BINORMAL			float			3 (xyz)
GMF_COLOR			byte			4 (rgba)
GMF_BONEINDICE			byte			4 (bone[4])
GMF_BONEWEIGHT			byte			4 (weight[4])
  • Bone indices refer to GMF_BONE nodes only in the order in which the appear in the file, from 0 to the number of bones minus one.
  • Bones should be listed in the order of relative strengths; the bone with the strongest weight should come first, followed by the second-highest, etc. This allows a renderer to use from 1 to up to 4 bones per vertex.
  • If fewer than four bones are needed, add any valid bone to the remaining slots, with a weight of 0. Bones IDs reference the entity in the model, in the order it appears in the file, beginning with 0. The root node is always 0, the first child is 1, and so on.
  • It is recommended that color arrays use 4-element RGBA values, as some graphics cards may attempt to emulate RGB mode in software.
  • For most purposes, it is recommended that the GMF_TRIANGLES mode be used together with GMF_UNSIGNED_SHORT.

Sample File Structure

Below is a diagram of the data layout of an animated skinned mesh. 

Byte		Value			Meaning
0		GMF_FILE		file start
4		1			number of kids
8		4			block size
12		1			version

16			GMF_MESH		mesh block
20			4			number of kids
24			64			block size
28			[1.0,0.0,0.0,0.0,	4x4 matrix
			0.0,1.0,0.0,0.0,
			0.0,0.0,1.0,0.0,
			0.0,0.0,0.0,1.0]
 
92				GMF_PROPERTIES		properties block
				0			number of kids
				36			block size
				1			number of properties
				"name"			property 1 name
				"mesh01"		property 1 value
 
?				GMF_SURFACE		surface block
?				7			number of kids
?				0			block size

92					GMF_PROPERTIES		properties block
					0			number of kids
					36			block size
					1			number of properties
					"material"		property 1 name
					"concrete01"		property 1 value

?					GMF_VERTEXARRAY		vertex array block
?					0			number of kids
?					48			block size
?					3			number of vertices
?					GMF_POSITION		vertex data type
?					GMF_FLOAT		variable type
?					3			elements
?					[1.0,0.0,0.0,		vertex data
					0.0,1.0,0.0,
					1.0,1.0,0.0]

?					GMF_VERTEXARRAY		vertex array block
?					0			number of kids
?					48			block size
?					3			number of vertices
?					GMF_NORMAL		vertex data type
?					GMF_FLOAT		variable type
?					3			elements
?					[0.0,0.0,1.0,		vertex data
					0.0,0.0,1.0,
					0.0,0.0,1.0]

?					GMF_VERTEXARRAY		vertex array block
?					0			number of kids
?					36			block size
?					3			number of vertices
?					GMF_TEXTURE_COORD	vertex data type
?					GMF_FLOAT		variable type
?					2			elements
?					[0.0,1.0,		vertex data
					0.0,0.0,
					1.0,0.0]

?					GMF_VERTEXARRAY		vertex array block
?					0			number of kids
?					36			block size
?					3			number of vertices
?					GMF_BONEINDICES		vertex data type
?					GMF_UNSIGNED_BYTE	variable type
?					4			elements
?					[0,0,0,0		vertex data
					1,0,0,0,
					0,1,0,0]

?					GMF_VERTEXARRAY		vertex array block
?					0			number of kids
?					36			block size
?					3			number of vertices
?					GMF_BONEWEIGHTS		vertex data type
?					GMF_UNSIGNED_BYTE	variable type
?					4			elements
?					[255,0,0,0		vertex data
					255,0,0,0,
					192,64,0,0]

?					GMF_INDICEARRAY	indice array block
?					0			number of kids
?					18			block size
?					3			number of indices
?					GMF_TRIANGELES		primitive type
?					GMF_UNSIGNED_SHORT	variable type
?					[0,1,2]			indice data

16				GMF_BONE		mbone block
24				2			number of kids
20				64			block size
28				[1.0,0.0,0.0,0.0,	4x4 matrix
				0.0,1.0,0.0,0.0,
				0.0,0.0,1.0,0.0,
				0.0,0.0,0.0,1.0]
32				0			bone id

92					GMF_PROPERTIES		properties block
					0			number of kids
					36			block size
					1			number of properties
					"name"			property 1 name
					"bone01"		property 1 value

92					GMF_ANIMATIONKEYS		animation block
					0			number of kids
					36			block size
					2			number of frames
					[1.0,0.0,0.0,0.0,	frame 1 4x4 matrix
					0.0,1.0,0.0,0.0,
					0.0,0.0,1.0,0.0,
					0.0,0.0,0.0,1.0]
					[1.0,0.0,0.0,0.0,	frame 2 4x4 matrix
					0.0,1.0,0.0,0.0,
					0.0,0.0,1.0,0.0,
					0.0,0.0,1.0,1.0]

16				GMF_BONE		mbone block
24				2			number of kids
20				64			block size
28				[1.0,0.0,0.0,0.0,	4x4 matrix
				0.0,1.0,0.0,0.0,
				0.0,0.0,1.0,0.0,
				0.0,0.0,0.0,1.0]

92					GMF_PROPERTIES		properties block
					0			number of kids
					36			block size
					1			number of properties
					"name"			property 1 name
					"bone02"		property 1 value

92					GMF_ANIMATIONKEYS	animation block
					0			number of kids
					36			block size
					2			number of frames
					[1.0,0.0,0.0,0.0,	frame 1 4x4 matrix
					0.0,1.0,0.0,0.0,
					0.0,0.0,1.0,0.0,
					2.0,-3.0,0.0,1.0]
					[1.0,0.0,0.0,0.0,	frame 2 4x4 matrix
					0.0,1.0,0.0,0.0,
					0.0,0.0,1.0,0.0,
					2.0,-3.0,5.0,1.0]

Constants

GMF_BYTE			1
GMF_UNSIGNED_BYTE		2
GMF_SHORT			3
GMF_UNSIGNED_SHORT		4
GMF_HALF			5
GMF_INT			6
GMF_UNSIGNED_INT		7
GMF_FLOAT			8
GMF_DOUBLE			9

GMF_FILE			1
GMF_NODE			2
GMF_MESH			3
GMF_BONE			4
GMF_VERTEXARRAY		5
GMF_INDICEARRAY		6
GMF_PROPERTIES			7
GMF_ANIMATIONKEYS		8
GMF_AABB			9
GMF_SURFACE			10

GMF_POSITION			1
GMF_NORMAL			2
GMF_TEXTURE_COORD		3
GMF_COLOR			4
GMF_TANGENT			5
GMF_BINORMAL			6
GMF_BONEINDICE			7
GMF_BONEWEIGHT			8

GMF_POINTS			1
GMF_LINE_STRIP			2
GMF_LINE_LOOP			3
GMF_LINES			4
GMF_TRIANGLE_STRIP		5
GMF_TRIANGLE_FAN		6
GMF_TRIANGLES			7
GMF_QUAD_STRIP			8
GMF_QUADS			9
GMF_POLYGON			10

Tools

Retrieved from "http://www.leadwerks.com/wiki/index.php?title=Game_Model_Format"