User Manual

File Format

Generally speaking, you do not need to know the structure of the file format used to serialize your models. However, this section describes the format for those who are interested in writing their own file converters.

To get models into PlayCanvas, you have to upload an FBX (or OBJ, DAE, DXJ, 3DS) file. On the server, this file is converted to a JSON format. This format is textual. Let's take a look at a very simple example of a plane consisting of two triangles:

{
  "model": {
    "version": 2,
    "nodes": [
      {
        "name": "RootNode",
        "position": [ 0, 0, 0 ],
        "rotation": [ 0, 0, 0 ],
        "scale": [ 1, 1, 1 ]
      },
      {
        "name": "Plane",
        "position": [ 0, 0, 0 ],
        "rotation": [ 0, 0, 0 ],
        "scale": [ 1, 1, 1 ]
      }
    ],
    "parents": [ -1, 0 ],
    "skins": [],
    "vertices": [
      {
        "position": {
          "type": "float32",
          "components": 3,
          "data": [ 1, 1, 0, -1, 1, 0, -1, -1, 0, 1, -1, 0 ]
        },
        "normal": {
          "type": "float32",
          "components": 3,
          "data": [ 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1 ]
        }
      }
    ],
    "meshes": [
      {
        "aabb": {
          "min": [ -1, -1, 0 ],
          "max": [ 1, 1, 0 ]
        },
        "vertices": 0,
        "indices": [ 0, 1, 2, 0, 2, 3 ],
        "type": "triangles",
        "base": 0,
        "count": 6
      }
    ],
    "meshInstances": [
      {
        "node": 1,
        "mesh": 0
      }
    ]
  }
}

Here is a reference for the different properties that appear in the JSON object above:

PropertyDescription
modelDenotes that this JSON object is a PlayCanvas model.
versionThe version of the JSON object. Current head version is 2.
nodesAn array of nodes that constitute the scene hierarchy. The array is flat but the 'parents' array specifies the parent-child relationships between scene nodes.
nameThe node's name (usually assigned by an artist).
position3-component position (XYZ) relative to the node's parent.
rotation3-component Euler angle rotation (XYZ) relative to the node's parent. Units are degrees.
scale3-component scale (XYZ) relative to the node's parent.
parentsArray of parent node indices. The root node has a parent of -1. In the example above, the node 'Plane' has 'RootNode' for a parent.
skinsSkinning data is left undocumented for now.
vertices An array of objects containing vertex information. Each object has a number of vertex properties. These can be:
  • position: vertex positions
  • normal: vertex normals
  • texCoord0: first texture coordinate set
  • texCoord1: second texture coordinate set
  • skinWeights: vertex skin weights
  • skinIndices: vertex skin indices
  • color: vertex colors
Each property has a type (float32, uint8, uint16, uint64) and a number of components (1-4).
meshesAn array of mesh objects. Mesh are used to interpret how vertex information is rendered.
aabbThe axis-aligned local space bounding box of a mesh.
minThe minimum coordinate of the mesh's axis-aligned bounding box.
maxThe maximum coordinate of the mesh's axis-aligned bounding box.
verticesThe index of the vertex information object referenced by this mesh.
indicesAn array of indices that defines the points of the primitive represented by the mesh.
type The type of the primitive of this mesh. Can be:
  • points
  • lines
  • lineloop
  • linestrip
  • triangles
  • trianglestrip
  • trianglefan
baseThe first index used by this mesh.
countThe number of indices used by this mesh.
meshInstancesAn array of objects representing instances of meshes. A single mesh can be shared between multiple mesh instances. This is an optimization that saves memory at runtime.
nodeThe index of the node referenced by this mesh instance.
meshThe index of the mesh referenced by this mesh instance.