Apps (.app.json root file)
If your Marketplace item has an .app.JSON file as the root file, it is a considered an app, meaning it should work with the desktop toolbar or in-world tablet. This keeps apps in a common, manageable space. Like a real world application, it needs a launch button icon and UI that can pop up when you click the button. That UI can be as simple or complex as you like. We suggest you use it to add relevant functionality, like an on/off toggle, instructions, credits, or any other options your application needs. You can learn more about creating an app in our documentation.
The .app.json file is a basic JSON file which contains two key pieces of information: scriptURL and homeURL, for the application logic and UI in html, respectively. Here is an example .app.json root file, called hrtf.app.json:
Entities (.json root files)
If your Marketplace item has a .JSON root file, it will continue to be handled the way it always has, and does not need a tablet button or UI.
What if my Entity is created (rezzed) by a .JS root file?
You’ll need to decide if you want it to be a tablet app or an entity… Some developers have created entities which are not delivered as .JSON files, but instead are rezzed in-world using a .JS script as the root file. If you’ve created such an entity, you’ll need to decide if you want to control rezzing it as a tablet app, which would require the button and UI mentioned above, or convert the final product into an entity and export that as a JSON file. An example of an “entity” which might better be distributed as an app would be a virtual pet, with a UI that can rez the pet, show its health and statistics, manage food, and customize its attributes (like its name) with a tablet UI. If it doesn’t need UI functionality, it needs to be a .json root file instead.
If it is important that your entity be rezzed by a script, and you don’t want it to be a app, you can implement an intermediate “unopened box” entity, which contains a rezzing script that can be triggered by an event (like clicking on it).
My entity has a .JSON root file but uses entity scripts. Do I need a tablet UI?
No. As long as the root file is .json, you do not need to add a tablet UI. This policy only affects items with an .app.JSON root file. Entities with scripts attached are just fine.
What’s the motivation for this change?
We are hard at work on making High Fidelity the Social Virtual Reality platform of choice for people across the world. This includes people across diverse cultures, different levels of education and access to technology. One of the core pieces of High Fidelity is the “Tablet/App bar” and we are always looking for ways to make it simpler and easier to use for everyone. This involves making improvements to visual design, consistent interactive elements and improving the discoverability of information. Previously, in order to move fast, we had allowed App buttons to either open a separate UI or act as a toggle button to change the state of the app between ON and OFF. As we mature as a platform and focus on improving the quality of the user experience, we found this to be a constant source of confusion for new users unfamiliar with the platform and existing users when they installed a new app. In an effort to reduce this confusion we are making the change that all top-level app launch buttons should lead to a separate screen for the app. It also provides a place for developers to surface new functionality to existing users with a familiar screen. We understand that this may lead to developer discomfort for those who have apps with the older app guidelines on the Marketplace. We do believe that making the “Tablet/App bar” less confusing and easy to use will reap greater benefits to our community and help us move forward towards the goal of a public Metaverse.
Where can I learn more?
This new functionality will appear in the documentation shortly. In the meantime, we’ve made a Google Doc with additional information on the new design, and architecture details, that you may find helpful, below. Feel free to come to our Monday Maker Meetup with any questions.