Please visit the GitHub repository and download the ZIP file to your desired location. We recommend using Unity version 6000.3.2f1 LTS and installing the framework on the D:\ drive or another hard drive. If you install it in a folder nested too deeply, you may see a warning that the file path is too long. Unzipping the project directly to the C: or D: drive will resolve this issue. You may see some errors, but they can be safely cleared as they won’t affect the project. 

🌟 Don't forget to STAR this repository on GitHub! 🌟

To create a clean repository, make a new folder, name it accordingly. Copy Assets, Packages, and User Settings folders into it.

Open the project in Unity, make sure to select Android as a platform.

If you don't have Git installed, you might have this warning. Fix it by installing Git for Windows here 

If the Project Validation window appears, select Fix All. Afterward, open the Console and clear any red error messages that are safe to resolve.

Move on to the next step: Setting up Ready Player Me (scroll back up.)

Head to the https://studio.readyplayer.me/ and click on "Add application"

Complete all required fields and choose Unity as your primary development environment.

Open the app and set up Full Body XR (Beta). Copy Subdomain, App ID.

If the Setup Guide appears, enter your subdomain and App ID. You can access this menu anytime via Tools → Ready Player Me → Setup Guide → Next → Finish Setup

Go to the app catalog and add the outfits you’d like to include in your app.

Once the project is open, navigate to Assets → Vertex Form 3D → Scenes → Vertex Form 3D Scenes and locate the example scene LoginScene.

We strongly encourage you to complete the full setup and successfully test your first build before making any changes or adding new assets.

Move on to the next step: Adding multiplayer tokens (scroll back up.)

1. To successfully test the project, you'll need a multiplayer token from Photon. You can obtain one by creating a free account at Photon Dashboard. Click on Create a New App.

2. Select FUSION from dropdown. Select Non-Gaming App if you plan to use the framework to create apps for education, training, medical simulation, collaboration, metaverse etc. For gaming apps select "Multiplayer game". Click "create".

Select Fusion in the "Select Fusion SDK" slot 

Select Fusion 2 (Recommended) in the Select SDK Version 

3. Create a new app again, this time select "voice"

Note the location of API ID's from FUSION and Voice and head back to Unity.

In the Vertex Form 3D SDK, open Project Setup → Open Fusion App Settings. Copy and paste your Fusion and Voice App IDs into the corresponding fields.

Move on to the next step: Testing

It is recommended to test often to catch any potential issues early. There are two ways to test without building an .apk file: via the LINK cable, and via the Unity editor using XR Device Simulator. 

ALWAYS START TESTING FROM THE LoginScene

TESTING USING XR DEVICE SIMULATOR 

This method is very useful for testing without access to a VR device or for multiplayer testing—when running on a headset while simultaneously joining from the editor using XR Device Simulator. 

Start the game. While the game is still in Play Mode, locate XR Device Simulator in the Vertex Form 3D SDK and click on it.

You can use the WASD keys to move around and press Tab to switch between controlling the hands and the head. Do not use the mouse to rotate, as it will cause you to lose sight of your hands, use your head instead.

Use the XR Device Simulator panel to better understand the controls.

We've also added a convenient keyboard shortcut feature for UI access:

• Press N to open the Main UI
• Press M to open the Settings UI

If your game pauses when switching scenes, go to the Console window and uncheck "Pause on Error." These are not actual errors but debug logs, and unchecking this option will prevent unnecessary interruptions while testing.

TESTING VIA THE LINK CABLE: 

The cable included with your Meta Quest device is a charging cord, not the Link cable. To use the Link feature, you’ll need to purchase a compatible cable separately—either from the official Meta website or a more affordable alternative. After purchasing the link, follow these instruction to set it up. You may also consider enabling Air Link, though it has been found to be unstable.

To test the app via Unity using the link, you will have to open Rift Home. Open your headset, go to System - Link - Launch Link. It will open Rift Home. Get back to Unity and hit "Play." The game will start in your headset.  

At this stage, you may be eager to start customizing your environment. Please be patient and complete a clean build before making any changes. A good practice is to duplicate the project after the clean setup is finished and use the copy for customization, so you can always return to a clean project if needed. Follow the instructions below to build and test a clean project. The goal is to ensure your app runs successfully on the headset as a standalone application.

Move on to the next step: Making first build and headset testing 

BUILDING ADDRESSABLES AND .APK FILE

Step 1: BUILDING ADDRESSABLES

Building addressable asset bundles and the .apk file early is recommended to ensure the app functions properly before investing significant time in customizing environments. Scenes and assets can always be updated and rebuilt as needed.

By default, Addressables are built into the local folder, and the final .apk file will include these environments. Steps for Remote Addressables (cloud delivery) will be explained later.

1. Open Vertex Form 3D SDK to start the build process. 
2. Click on "Build Addressables." The first build may take some time—take a break and stretch your legs. 
3. Once the build is complete, an Addressable Report Summary should appear.

Step 2: Building .apk file 

The .apk file is the standard format for Android apps, and since Meta Quest runs on the Android platform, building an .apk file is required for deployment.

Building the .apk File:

Open Build Settings:

• Go to File > Build Profiles and confirm that the platform is set to Android.

Build the .apk:

• Click Build and select a location to save the file.
• Create a new folder at the top level of the project directory and name it "Builds." You can access the folders by right clicking on "Assets" and then selecting "Show in Explorer".
• Name your first build using the following format: YourApp_Date
• Click Yes to all windows that will pop up. 
  

You can find your builds by right-clicking the asset folder and selecting Show in Explorer.

Upload your .apk to the headset. Install Meta Quest Developer Hub. Make sure your headset is connected via Link, then open File Manager → Apps and install your .apk using + Add Build.

Click on the three dots and press "Launch App" it should start playing in your headset.

After confirming that your app works as a standalone build, you can begin customization. Create a copy of the project or start a new branch in your own GitHub repository. If anything breaks during customization, you can always revert to the clean, working version.

Move on to the next step: Adding your own scenes

ADDING AND BUILDING THE SCENES

A two-step process is required to add custom scenes into the app. Start by duplicating an existing example Scene or creating a brand-new Scene in the Scenes folder inside Assets. Remove default Main Camera.

Step 1: Adding Scenes to the UI

This step is necessary for scenes to appear in the Main UI. Open Vertex Form 3D SDK and Click on Scene Database. Dock this window to the side of the Unity Editor so you can keep it open at all times.

By default, there are several categories: Hubs, Geospatial, and Other. You can rename existing categories or add your own. These categories are used in the UI, allowing users to sort and browse environments by category.

In the DataBase panel you can add a Category or a World withing the Category, by clicking on + to duplicate an entry. Rename it exactly as the new scene you just created. Replace the sprite (image) with a screenshot of the scene - this will show up in the Main UI as a scene preview. You can change the order of the scenes or remove the scenes from the Menu by clicking -.

•  Category – Used to group and organize your worlds by theme (e.g., Games, Geospatial, Hubs).
• Worlds – Individual scenes that belong to a category.

In the Main UI at Runtime, your users will be able to sort these worlds from the sorting panel on top of the UI.

NOTE: To convert your .png or .jpg image into a sprite, select the image, go to the Inspector, and change the Texture Type from "Default" to "Sprite (2D and UI)." Additionally, set Sprite Mode to "Single" (not "Multiple"). To optimize performance, it is recommended to reduce the Max Size to 512 to minimize image file size.

Step 2: Adding Scenes to Addressables Asset Group for local builds 

Adding scenes to the Addressables Asset Group is a crucial step, ensuring they are included in the build. By default, the framework is set up for local delivery, meaning all scenes will be built directly into your final .apk file.

If you don’t see the Addressable Asset Group, navigate to:
Vertex Form 3D SDK → Build Addressables → Addressable Groups.

Drag and drop the new scene into the Addressable Group Window. Select the scene and rename it, keeping only the scene name.

In order for your scene to be recognized and delivered at Runtime, you need to assign lable group.

Return to the Testing step to verify that everything functions correctly and that the scene appears in the UI. You can also create a new build to confirm the app is properly set up and works as a standalone experience on the headset.

Move on to the next step Obtaining A Geospatial Token

OBTAINING CESIUM GEOSPATIAL TOKEN

The framework includes a geospatial package from Cesium. To use geospatial scenes, create an account and obtain a token. Follow the instructions in the Cesium panel. Your scene will initially be empty. Once you have a token, click on 'Cesium World Terrain - Bing Maps Aerial' or the option below to populate your scene.

Changing geospatial coordinates. 

Select any location on Earth by adjusting the Latitude and Longitude coordinates in the Inspector.

FLY by pressing on Grip and Trigger button at the same time on the left controller when testing via the link cable.

Continue working and adding your own scene, test often. When you are ready, you can proceed to the next step to publish the app on Meta Quest.

Publishing settings and keystore key

Step 1: Change publishing settings 

To make your app unique, you need to update the publishing settings. Navigate to Edit > Project Settings > Player, then modify the Company Name and Product Name. Set your product version to 0.0.1.

Scroll down to Identification and fill in the Package Name, Bundle Version, and Package Version. Each time you upload a new .apk to Meta Quest, increment the version number. Following Semantic Versioning is recommended for naming your builds.

To successfully build your .apk file, you must either obtain a Keystore Manager key or UNCHECK "Custom Keystore" if you're only testing the .apk on your device.

You cannot upload an .apk to Meta Quest without this key.

Make sure to store the key in a secure location where you can always access it. Losing access to the key will prevent you from updating your app on Meta Quest. If you encounter the error "Unable to sign in", it's often due to an issue with the keystore.

If you need to create a key, follow the instructions in the "Custom Keystore" window.

Move on to the next step: Publishing on Meta quest

Publishing on Meta Quest. 

Publishing the alpha version of your app on Meta Quest is a simple and straightforward process that does not require approval. Your app will be accessible to others via an invite link.

Install Meta Quest Developer Hub on your desktop and sign in with your Meta account. Navigate to App Distribution, then click Create a New App. Enter a name for your app, return to the Developer Hub, refresh the page, and your new app will appear.

Uploading your .apk file to Meta Quest 

Click on your newly created app and use the Upload button to upload the .apk file you created earlier. The system will analyze your app and provide feedback on its status, including any suggestions for fixes. Fix any issues, and try again. 

Updating Media and Sharing Your App Link

After successfully uploading your .apk file, you can update media assets such as the header image, logo, and other photos.

1. Go to Oculus Developer Dashboard and select your app.
2. Navigate to App Metadata History and click Go to Metadata Assets to update your logo and other media.
3. The page will be in Read Only mode, in order to update your metadata, you have to click on "here"  

Granting Access to Your App via URL

1. Go to your app's Release Channel and select the version (Alpha).
2. Navigate to Channel Settings and set it to Public.
3. Click Grant Access to Users by URL and generate the link.
4. Enable Automatic Approval, then share the URL with others.

🎉 Huge congratulations on publishing your VR app! 🚀 You’ve turned your vision into reality—an incredible achievement. Keep pushing boundaries, inspiring others, and shaping the future of immersive experiences. The journey is just beginning! 🔥✨ 

Take a moment to celebrate and share your achievement with the community in the Community Showcase channel on Discord. 🎉