Skip to content

glTF Models

Cocos Creator supports glTF 2.0 and earlier file formats.

URI Parsing

Creator supports URIs in the following form specified in glTF:

  • Data URI

  • Relative URI path

  • File URL

  • File path

Conversion Relationships

When importing a glTF model into Creator, the assets in glTF will be converted to assets in Creator according to the following relationships:

glTF AssetCocos Creator Asset
glTF ScenePrefab
glTF MeshMesh
glTF SkinSkeleton
glTF MaterialMaterial
glTF TextureTexture
glTF ImageImage
glTF AnimationAnimation Clip

glTF Scene

After import, the glTF scene will be converted to a prefab asset in Creator, and the nodes recursively contained in the glTF scene will be converted to nodes in the prefab one by one according to the same hierarchical relationship.

Scene Root Node

The prefab will use a node without any spatial transformation information as the root node, and all root nodes of the glTF scene will be the children of this node.

Node Conversion

The properties in the glTF node will be converted to properties in the prefab node according to the texture relationships in the following table:

glTF Node PropertyPrefab Node Property
HierarchyHierarchy
DisplacementPosition
RotationRotation
ScalingScaling
MatrixDecompress and set the position, rotation, and scaling respectively
MeshMeshRenderer component
SkinSkinnedMeshRenderer component
Initial Weight(Skinned) MeshRenderer component weight

MeshRenderer

If the glTF node references a mesh, then the corresponding prefab node will also have a MeshRenderer component added to it after import. If the glTF node also references a skin, then the corresponding prefab node will also have a SkinnedMeshRenderer added to it.

The mesh, skeletons, and materials in the SkinnedMeshRenderer component correspond to the transformed glTF mesh, skin, and material assets.

If the glTF node specifies an initial weight, the converted (skinned) MeshRenderer will also carry this weight.

glTF Mesh

After import, the glTF mesh will be converted to a mesh asset in Cocos Creator.

All primitives in the glTF mesh will be converted to sub-meshes in the Creator one by one.

If weight is specified for the glTF mesh, the corresponding weights will be stored in the converted Creator mesh.

glTF Primitive

The index arrays of the glTF primitives will correspond to the index arrays of the converted Cocos Creator sub-meshes.

The glTF primitive schema will be converted to the Cocos Creator primitive schema according to the texture in the following table.

glTF Primitive SchemaCocos Creator Primitive Schema
POINTSgfx.PrimitiveMode.POINT_LIST
LINESgfx.PrimitiveMode.LINE_LIST
LINE_LOOPgfx.PrimitiveMode.LINE_LOOP
LINE_STRIPgfx.PrimitiveMode.LINE_STRIP
TRIANGLESgfx.PrimitiveMode.TRIANGLE_LIST
TRIANGLE_STRIPgfx.PrimitiveMode.TRIANGLE_STRIP
TRIANGLE_FANgfx.PrimitiveMode.TRIANGLE_FAN

glTF vertex attributes will be converted to Cocos Creator vertex attributes, and the attribute names will be converted as shown in the following table:

glTF Vertex Attribute NameCocos Creator Vertex Attribute Name
POSITIONgfx.AttributeName.ATTR_POSITION
NORMALgfx.AttributeName.ATTR_NORMAL
TANGENTgfx.AttributeName.ATTR_TANGENT
TEXCOORD_0gfx.AttributeName.ATTR_TEX_COORD
TEXCOORD_1..TEXCOORD_8gfx.AttributeName.ATTR_TEX_COORD1..gfx.AttributeName.ATTR_TEX_COORD8
COLOR_0gfx.AttributeName.ATTR_COLOR
COLOR_1..COLOR_2gfx.AttributeName.ATTR_COLOR1..gfx.AttributeName.ATTR_COLOR2
JOINTS_0gfx.AttributeName.ATTR_JOINTS
WEIGHTS_0gfx.AttributeName.ATTR_WEIGHTS

Note: if there are other JOINTS, WEIGHTS vertex attributes in the glTF primitive, such as JOINTS_1, WEIGHTS_1, it means that the vertices of this glTF mesh may be affected by more than 4 skeletons.

For each vertex, all the weight information determined by JOINTS_{}, WEIGHTS_{} will be sorted by weight value and the four skeletons with the highest influence weight will be taken as gfx.AttributeName.ATTR_JOINTS and gfx.AttributeName.ATTR_WEIGHTS.

glTF deformation targets will be converted to Cocos Creator sub-mesh deformation data.

glTF Skins

After import, glTF skins will be converted to skeletal assets in Cocos Creator.

glTF Material

After import, glTF materials will be converted to material assets in Cocos Creator.

glTF Texture

After import, glTF texture will be converted to a texture asset in Cocos Creator.

The glTF image referenced in the glTF texture will be converted to a reference to the corresponding converted Cocos Creator image.

glTF texture properties will be converted to Cocos Creator texture properties according to the texture in the following table:

glTF Texture PropertyCocos Creator Texture Property
Magnification FilterMagnification Filter
Minification FilterMinification Filter, Mip Map Filter
S Wrap ModeS Wrap Mode
T Wrap ModeWrap Mode

The glTF texture magnification filter will be converted to the Cocos Creator texture magnification filter according to the texture in the following table:

glTF Texture Magnification FilterCocos Creator Texture Magnification Filter
NEARESTTextureBase.Filter.NEAREST
LINEARTextureBase.Filter.LINEAR

The glTF Texture Minification Filter will be converted to Cocos Creator Texture Minification Filter and Cocos Creator Texture Mip Map Filter according to the texture relationships in the following table:

glTF Texture Minification FilterCocos Creator Texture Minification FilterCocos Creator Mip Map Filter
NEARESTTextureBase.Filter.NEARESTTextureBase.Filter.NONE
LINEAR_MIPMAP_LINEARTextureBase.Filter.LINEARTextureBase.Filter.NONE
LINEAR_MIPMAP_NEARESTTextureBase.Filter.NEARESTTextureBase.Filter.NEAREST
LINEARTextureBase.Filter.LINEARTextureBase.Filter.NEAREST
NEAREST_MIPMAP_LINEARTextureBase.Filter.NEARESTTextureBase.Filter.LINEAR
NEAREST_MIPMAP_NEARESTTextureBase.Filter.LINEARTextureBase.Filter.LINEAR

glTF Texture Wrap mode will be converted to Cocos Creator Texture Wrap mode according to the texture in the following table:

glTF Texture Wrap ModeCocos Creator Texture Wrap Mode
CLAMP_TO_EDGETextureBase.WrapMode.CLAMP_TO_EDGE
REPEATTextureBase.WrapMode.REPEAT
MIRRORED_REPEATTextureBase.WrapMode.MIRRORED_REPEAT

glTF Image

After import, the glTF image will be converted to an image asset in Cocos Creator.

When the URI of the glTF image is a Data URI, the image data will be fetched from the Data URI. Otherwise, the image data will be resolved from the Data URI according to the Cocos Creator Image Location Resolution Algorithm, where url is the URI of the glTF image and startDir is the directory where the glTF file is located.

glTF Animation

After import, glTF animations will be converted to Cocos Creator animation assets.