Custom Items for Oculus Home

You can reward your users with custom items when they acquire entitlements (app purchases) or in-game achievements. Custom items are 3D objects that display in the user’s Oculus Home and can help provide additional engagement and awareness for your apps and games.

Design an appropriate custom item

The first step to offering a successful custom item is to design something that renders correctly in Oculus Home, adheres to Oculus content guidelines, and is popular with your users. For tips to create an item that displays correctly, see Custom Item Design Tips. The next section provides detailed specifications for your custom item.

Detailed specs for a custom item

Oculus Home supports glTF 2.0 binary files, you can find the full specification here. A file must have no validation errors for it to be supported in Oculus Home.

File Type and Size

• Each asset must be a single GLB file (a packed, binary version of a the glTF 2.0 file). Other formats, such as FBX, OBJ, DAE, etc. are not supported.
• Each GLB file must be less than 15MB.

Textures Make sure your item textures adhere to the following:

• JPEG and PNG format
• Height and width dimensions of 2,048 pixels or less.
• One set of texture coordinates per mesh

Animations Use the following guidelines when adding animations. Note that the first animation will begin looping when the object is loaded in Oculus Home. The following animation types are supported:

• Simple transform animations including translation, rotation, and scale
• Linear, step, and cubicspline interpolation strategies
• Skinned animations Note that morph target animations are currently not supported.

Rendering Oculus home supports the rendering for the following:

• Double sided material
• PBR Metallic Roughness material (glTF 2.0)
• Normal, occlusion, and emissive textures
• Alpha-mode blend, however transparent polys are not sorted
• Textured and vertex color models

Model Positioning We respect the glTF 2.0 specification for Coordinate System and Units. In addition:

• Linear distance units are in meters.
• glTF defines +Y as up.
• The front of a glTF asset faces +Z.
• A bounding box is automatically created for your object.

Add a custom item to your app

To make a custom item available to users you will upload it to the developer dashboard, get it approved, and then associate it with an achievement or entitlement.

Prerequisites

Before you upload an item to the developer dashboard make sure:

• Item(s) are in GLB format, and meet all of the requirements in the specs section.
• You have imported the item to your Oculus Home and tested it thoroughly. See the How do I import 3D objects into my Home in the Oculus Apps and Features guide. Note that if you see validation errors in the import menu point at the object in the menu, click Y or B on one of your controllers for an error message with more details.

Upload your item for review

Items and all of their descriptive content should adhere to the Oculus Content Guidelines. You will upload your item to the developer dashboard to start the review process.

To upload an item for review:

1. Navigate to Manage > app name > Platform Services > Custom Items
2. Click Create New Item
3. Fill in a Name for the item.
4. Optionally, you can provide names for your items that are localized for other regions. To do so, click the Choose Languages button and enter a name for each language you choose.
5. In the File section, click the Upload File item to upload the GLB item.
6. Choose to Save or Save and Submit for Review. You must have the item approved before you can make it available to users. You can also return and Edit your item.

Note: Make sure you can access the item in your Oculus Home experience before you submit for review

Associate your item with an achievement or entitlement

You must associate a custom item with an achievement or entitlement to make it available to your users.

To associate a custom item with an achievement:

• If you haven’t already, create an achievement following the guidance in the information in the Achievements topic.

  Then:

1. Make sure your item is approved. If approved, it will say Available in the Status column for the item. View the item at Manage > app name > Platform Services > Custom Items.
2. Navigate to your achievement under Manage > app name > Platform Services > Achievements or if your app is in an app grouping, navigate to Manage > Settings > App Groupings > app name > Custom Items
3. In the Add Custom Item dropdown, choose the custom item you want to associate with the achievement, and click Save.

To associate a custom item with an entitlement:

The system associates a valid app purchase with an entitlement, so you do not need to explicitly create or manage them. An app entitlement has the same name as the purchased app.

1. Make sure your custom item is approved. If approved, it will say Available in the Status column for the item. View the item at Manage > app name > Platform Services > Custom Items.
2. Once you find the item, open the ellipses (...) dropdown next to it. Select View/Edit Assignments to open the assignment dialog.
3. Under the Entitlements section of the dialog, check the box next to each app for which your item will be rewarded at purchase time.
4. Click the Save button.
5. Verify your selected apps appear in the Assignments column of the item table.

Note: After you associate the custom item and save, the item is distributed to all users who have previously unlocked that achievement or entitlement, and in future to any users who unlock the achievement or entitlement.

Related topics

• Custom Item Design Tips and Resources
• Achievements
• Entitlements