Skip to content

Version 0.1 (libgdx 0.9.9)

Jump to bottom Edit New page
Vincent edited this page Jul 18, 2014 · 8 revisions

The G3DB and G3DJ file format, version 0.1

<root>:
{
	"version": [<majorversion>, <minorversion>]
	(, "meshes": [(<mesh> (, <mesh>)*)?])?
	(, "materials": [(<material> (, <material>)*)?])?
	(, "nodes": [(<node> (, <node>)*)?])?
	(, "animations": [(<animation> (, <animation>)*)?])?
}

<majorversion>: integer // always 0

<minorversion>: integer // always 1

<mesh>:
{
	"attributes": [<atribute> (, <attribute>)*],
	"vertices": [(<vertex> (, <vertex>)*)?],	// amount = <vertexcount>
	"parts": [(<meshpart> (, <meshpart>)*)?]
}

<attribute>: "POSITION"	| "NORMAL" | "COLOR" | "COLORPACKED" | "TANGENT" | "BINORMAL" | "TEXCOORD" | "BLENDWEIGHT"

<vertex>: (<float> (, <float>)*) // amount = <vertexsize>

<meshpart>:
{
	"id":	<meshpartid>,
	"type":	<primitivetype>,
	"indices": [(<index> (, <index>)*)?]
}

<meshpartid>: string // unique for all meshparts within the file

<primitivetype>: "TRIANGLES" | "LINES" | "POINTS" | "TRIANGLE_STRIP" | "LINE_STRIP"

<index>: integer // 0 <= <index> < <vertexcount>

<material>:
{
	"id": <materialid>
	(, "diffuse": <rgb>)?
	(, "ambient": <rgb>)?
	(, "emissive": <rgb>)?
	(, "specular": <rgb>)?
	(, "reflection": <rgb>)?
	(, "shininess": <float>)?
	(, "opacity": <float>)?
	(, "textures": [(<texture> (, <texture>)*)?])?
}

<materialid>: string // unique for all materials within the file

<rgb>: [<float>, <float>, <float>]

<texture>:
{
	"id": <textureid>,
	"filename": <string>,
	"type": <texturetype>
	(, "uvTranslation": [<float>, <float>])?
	(, "uvScaling": [<float>, <float>])?
}

<textureid>: string // unique for each texture-file

<texturetype>: "AMBIENT" | "BUMP" | "DIFFUSE" | "EMISSIVE" | "NONE" | "NORMAL" | "REFLECTION" | "SHININESS" | "SPECULAR" | "TRANSPARENCY"

<node>:
{
	"id": <nodeid>
	(, "translation": <xyz>)?
	(, "rotation": <quaternion>)?
	(, "scale": <xyz>)?
	(, "mesh": <string>)? // DEPRECATED
	(, "parts": [(<nodepart> (, <nodepart>)*)?])?
	(, "children": [(<node> (, <node>)*)?])?
}

<nodeid>: string // unique for each node

<xyz>: [<float>, <float>, <float>]

<quaternion>: [<float>, <float>, <float>, <float>]

<nodepart>:
{
	"meshpartid": <meshpartid>,
	"materialid": <materialid>
	(, "bones": [(<bone> (, <bone>)*)?])?
	(, "uvMapping": [(<uvmapping> (, <uvmapping>)*)?])?
}

<bone>:
{
	"node": <nodeid>,
	(, "translation": <xyz>)?
	(, "rotation": <quaternion>)?
	(, "scale": <xyz>)?
}

<uvmapping>: [(<integer> (, <integer>)*)?])?

<animation>:
{
	"id": <animationid>
	(, "bones": [(<nodeanimation> (, <nodeanimation>)*)?])?
}

<nodeanimation>:
{
	"boneId": <nodeid>,
	"keyframes": [(<keyframe> (, <keyframe>)*)?]
}

<keyframe>:
{
	"keytime": <float>
	(, "translation": <xyz>)
	(, "rotation": <quaternion>)
	(, "scale": <xyz>)
}

References

The G3DJ format uses ID's (strings) to reference objects within the file. ID's are case sensitive and must be unique within it's context. Referenced ID's must exist in the relevant context. For example a node part might reference a material with the ID "black", in which case there must exist a material object with the same (case sensitive) ID "black". In this example, it is allowed to also have a node with the ID "black", but it's advised to keep ID's unique throughout the file. (for another example, see below).

The root object

The root of the G3DJ file format is an object ({...}) containing the following keys:

  • "version" [required]: array of exactly two (2) numbers (integer)
  • "meshes" [optional]: array of objects
  • "materials" [optional]: array of objects
  • "nodes" [optional]: array of objects
  • "animations" [optional]: array of objects

Version

The version key consists of two integer value. The first value being the major version, the second being the minor version. For example:

{
	"version": [0, 1]
}

Which identifies major version 0 and minor version 1, also known as version "0.1". This is used by the reader/parser to identify the file version and decide whether and how to parse the file.

Meshes

An array of objects, where each object at least contains the following keys:

  • "attributes" [required]: array of strings
  • "vertices" [required]: array of floats
  • "parts" [required]: array of objects

For example (individual keys described below):

{
	"version": [0, 1],
	"meshes": [
		{
			"attributes": ["POSITION", "COLOR"],
			"vertices": [
				-1.000000, 1.000000, 0.000000, 1.000000, 0.000000, 0.000000, 1.000000,
				 0.000000, 1.500000, 0.000000, 0.000000, 1.000000, 0.000000, 1.000000,
				 1.000000, 2.000000, 0.000000, 0.000000, 0.000000, 1.000000, 1.000000
			],
			"parts": [
				{
					"id": "meshpart1",
					"type": "TRIANGLES",
					"indices": [
						0, 1, 2
					]
				}
			]
		}
	]
}

Attributes

An array of strings (enums, case-sensitive) where each string describes a vertex attribute used in the vertices array. Can be one of the following values:

  • "POSITION" : 3 floats position vertex attribute
  • "NORMAL" : 3 floats normal vertex attribute
  • "COLOR" : 4 floats color vertex attribute
  • "COLORPACKED" : 1 float color vertex attribute (packed)
  • "TANGENT" : 3 floats tangent vertex attribute
  • "BINORMAL" : 3 floats tangent vertex attribute
  • "TEXCOORD" : 2 floats texture coordinate vertex attribute
  • "BLENDWEIGHT" : 2 floats bone weight vertex attribute

As per spec, each value can be present zero or more times within the array. However the LibGDX reader restricts the POSITION, NORMAL, TANGENT and BINORMAL values to at most once and the COLOR and COLORPACKED values at most one of both (so either none, COLOR or COLORPACKED, but not both). The TEXCOORD and BLENDWEIGHT might be present up to a maximum of 8 times, optionally followed by a suffix which is ignored.

Attributes are zero based referenced. For example texture coordinate 0 is the first TEXCOORD attribute, bone weight 2 is the third BLENDWEIGHT attribute.

The order in which the attributes are specified must match the order of the vertices values (see the next section).

Vertices

An array of floating point values, where the amount of the values must be a multiply of the number of floats defined by the attributes. For example if the attributes specified are "POSITION" (3 floats) and "COLOR" (4 floats), then the number of vertices must be a multiply of seven (can be zero). Each sequence of that number of floats (e.g. 7) is called a vertex. The values within each vertex must match the same order as in which the attributes are specified. For example if the attributes are specified as: ["POSITION", "COLOR"], then the first three values must represent the position and last four values the color.

Parts

An array of objects, where each object specifies a part (or the whole) mesh, using the following form:

  • "id" [required]: string
  • "type" [required]: string
  • "indices" [required]: array of numbers (integer)

The ID value is used to reference the mesh part and must be unique along all mesh parts (including any other meshes within the same file). Typically auto numbering is used, e.g. "meshpart1", "meshpart2", etc. as this value has no practical meaning outside the file.

The Type value is used to specify the primitive type of the mesh part, valid values are (case sensitive):

  • "TRIANGLES"
  • "LINES"
  • "POINTS"
  • "TRIANGLE_STRIP"
  • "LINE_STRIP"

Although in practice "TRIANGLES" is most commonly used.

The indices array specifies the indices used for this mesh part. The number of indices must match the type specified (e.g. a multiple of three when TRIANGLES is specified). Each index zero-based references a vertex and therefor is limited to the number of values within the vertices array of the mesh divided by the number of float specified by the attributes (see vertices for more information).

Materials

An array of objects, where each object can at least contain the following keys:

  • "id" [required]: string
  • "diffuse" [optional]: array of three (3) floating point values
  • "ambient" [optional]: array of three (3) floating point values
  • "emissive" [optional]: array of three (3) floating point values
  • "specular" [optional]: array of three (3) floating point values
  • "reflection" [optional]: array of three (3) floating point values
  • "shininess" [optional]: floating point value
  • "opacity" [optional]: floating point value
  • "textures" [optional]: array of objects

For example:

{
	"version": [0, 1],
	"materials": [
		{
			"id": "material1", 
			"diffuse": [ 1.000000,  1.000000,  1.000000], 
			"specular": [ 0.500000,  0.500000,  0.500000], 
			"textures": [
				{
					"id": "file1", 
					"filename": "file1.png", 
					"type": "DIFFUSE"
				}
			]
		}
	]
}

The id value is used to reference the material and must be unique within all materials within the file. Most commonly this value is provided in the modeling application and used by the user to reference the material in code.

The diffuse, ambient, emissive, specular and reflection values are arrays of at least (but not limited to) three floating point values. Specifying the red, green and blue values in that order and within the range between 0.0 and 1.0. For example: [0.000000, 0.000000, 0.000000] = black [1.000000, 1.000000, 1.000000] = white [1.000000, 0.000000, 0.000000] = red Note that the specification doesn't restrict the values between 0.0 and 1.0, negative values or values above 1.0 are allowed.

The textures array consists of zero or more objects, where each object can at least contain the following keys:

  • "id" [required]: string
  • "filename" [required]: string
  • "uvTranslation" [optional]: array of two (2) floating point values
  • "uvScaling" [optional]: array of two (2) floating point values
  • "type" [required]: string

The id value can be used to identify the same texture amongst multiple materials. The id might be used multiple times, in which case it must reference the same texture filename.

The filename value is used to identify the texture file, preferable a relative path to the g3dj file. LibGDX only allows relative filenames for textures.

The uvTranslation and uvScaling values are reserved and not used at the moment. But if they are present, they must be both an array of two floating point values.

The type value is used to describe the type of texture and can be one of the following: "AMBIENT" "BUMP" "DIFFUSE" "EMISSIVE" "NONE" "NORMAL" "REFLECTION" "SHININESS" "SPECULAR" "TRANSPARENCY"

Nodes

An array of objects, where each object can at least contain the following keys:

  • "id" [required]: string
  • "translation" [optional]: array of three (3) floating point values
  • "rotation" [optional]: array of four (4) floating point values
  • "scale" [optional]: array of three (3) floating point values
  • "mesh" [optional]: string DEPRECATED, do not use
  • "parts" [optional]: array of objects
  • "children" [optional]: array of objects

The id value must be unique amongst all nodes (including all child nodes) within the file and is used to reference the node. Typically this value is provided by the modeling application and used by the user to identify the node within code.

The translation value is specified by an array of exactly three floating point values, representing the x, y and z components of the untransformed location of the node in object space relative to its parent (if any, see "children"). If absent the location 0,0,0 is assumed.

The rotation value (quaternion) is specified by an array of exactly four floating point values, representing the x, y, z and w components of the rotation of the node in object space relative to its parent (if any, see "children"). The absent the identity quaternion is assumed.

The scale value is specified by an array of exactly three floating point values, representing the x, y and z components of the scaling of the node in object space relative to its parent (if any, see "children"). If absent the scaling 1,1,1 is assumed.

Add a custom footer

#Table Of Contents#

Clone this wiki locally