3D Thumbnails

The Roblox avatar as downloaded from GET /v1/users/avatar-3d

The Roblox avatar as downloaded from GET /v1/users/avatar-3d, rendered in Blender.

Roblox supports generating 3D thumbnails for users and assets. This article explains how you can do that.

Endpoints

Roblox currently supports 3D thumbnails for users and some types of assets.
For more information on how thumbnails work, please see Thumbnails.

• For assets, use the endpoint https://thumbnails.roblox.com/v1/assets-thumbnail-3d?assetId=ASSETID
  • Alternatively, use the endpoint https://www.roblox.com/asset-thumbnail-3d/json?assetId=ASSETID.
• For users, use the endpoint https://thumbnails.roblox.com/v1/users/avatar-3d?userId=USERID
  • Alternatively, use the endpoint https://www.roblox.com/avatar-thumbnail-3d/json?userId=USERID.

Explaining the data

The imageUrl they return has data that looks like this:

{
  "camera": {
    "position": {
      "x": -2.1652,
      "y": 104.947,
      "z": -4.72907
    },
    "direction": {
      "x": -0.40558,
      "y": 0.40558,
      "z": -0.819152
    },
    "fov": 70
  },
  "aabb": {
    "min": {
      "x": -2.03532,
      "y": 100.003,
      "z": -1.16793
    },
    "max": {
      "x": 2.24066,
      "y": 105.39,
      "z": 0.622441
    }
  },
  "mtl": "f70734be44332e058a3270e4545e2943",
  "obj": "bbdb80c2b573bf222da3e92f5f148330",
  "textures": [
    "024f209b987e47c0f2a51d3f615ab806"
  ]
}

• The camera data contains information about where the camera should be positioned.
  
• The aabb data is used to calculate max render distance with this codeblock:

  THREE.Vector3(json.aabb.max.x, json.aabb.max.y, json.aabb.max.z).length() * 4;
  

• The mtl, obj and textures keys contain CDN hashes to their raw file data (example: https://t5.rbxcdn.com/bbdb80c2b573bf222da3e92f5f148330).

Data format

The obj contains OBJ data, the mtl contains MTL data, and the textures are all PNG data.

Potential issues

• The OBJ data does not contain a mtllib line, meaning it doesn't actually link to the MTL automatically. If you name the MTL and OBJ files the same thing, some 3D tools (like Blender) will automatically recognize this and link them, however not all tools will. To ensure that the MTL is linked properly to the OBJ, add this line to the beginning of the OBJ file:

  mtllib FILENAME.mtl

  where FILENAME is the name of the MTL you downloaded.
• The OBJ data is also offset by quite a few units in the Y axis, so you may need to center your geometry in your 3D tools before using it.