Applications sur Tablet

THIS GUIDE IS OUT OF DATE. THE CODE MAY NOT WORK EXACTLY AS OUTLINED, USE FOR REFERENCE ONLY UNTIL UPDATED. SEE API DOCS<https://apidocs.overte.org/> FOR MORE.

Tablet apps (or simply "apps") in Overte are customizable programs that expose functionality in an easy-to-use user interface. Apps let you take complex code from our JavaScript API and simplify it into a window with controls for others to use.

Note

Pour créer des applications personnalisées, vous devez avoir une connaissance de base du développement web (HTML, CSS et JavaScript) et être capable de naviguer dans notre API.

Les étapes de la création d'une application pour tablet sont les suivantes :

Créer des icônes à afficher sur le tablet et le HUD
Concevez l'interface utilisateur de votre application en HTML et CSS
Ajoutez des gestionnaires d'événements à votre fichier HTML
Écrivez un fichier JavaScript qui :
- Ajoute un bouton sur le tablet et le HUD
- Charge votre application
- Ferme votre application
- Écoute des événements
- Exécute votre code (dans ce cas, créer des pierres précieuses)

Tutoriel : Créer une Application de Tablet de Commutation de Pierres Précieuses

Dans ce tutoriel, nous allons parcourir les étapes ci-dessus pour créer une application appelée "Gemstone Magic Maker". Cette simple application vous permet de créer des petites pierres précieuses colorées en VR que vous pouvez partager avec vos amis.

Créer des icônes à afficher sur le tablet et le HUD

Vous avez besoin de deux icônes pour apparaître sur le tablet et le HUD : une image SVG ou PNG à afficher sur le bouton de l'application lorsque celle-ci est active, généralement nommée <appName>-a.svg et une autre à afficher lorsque l'application est inactive, généralement nommée <appName>-i.svg.

Nous vous recommandons les spécifications suivantes pour vos icônes :

Taille : 50px par 50px
Couleur : Blanc sur fond transparent (pour les icônes inactives) et noir sur fond transparent (pour les icônes actives)
Format de fichier : SVG ou PNG

Vous pouvez créer votre propre icône à l'aide d'un logiciel de conception graphique ou de toute autre ressource en ligne.

Concevez l'interface utilisateur de votre application en HTML et CSS

L'interface utilisateur de votre application doit fournir du texte sur le fonctionnement de l'application et utiliser des éléments familiers de l'interface utilisateur avec lesquels l'utilisateur sait interagir (tels que les boutons, les barres de défilement et les liens). N'oubliez pas que les dimensions de l'écran du tablet sont de 480 x 720, donc toute votre interface utilisateur doit être limitée à cet espace.

Pour vous aider à démarrer, nous avons mis au point un modèle HTML de démarrage rapide que vous pouvez réutiliser. Il contient la même mise en page, le même style et la même police que l'écran du menu principal, et comporte une barre d'en-tête pour le titre de votre application. Avec quelques modifications simples, vous pouvez créer une interface utilisateur d'application simple en quelques minutes.

Ajoutez des gestionnaires d'événements à votre fichier HTML

Le cadre de la Tablet UI fournit un canal de communication appelé EventBridge. Il vous permet d'envoyer et de recevoir des événements entre le script client (gemstoneApp.js) et le JavaScript de votre application web (gemstoneMagicMaker.html). Utilisez le code EventBridge suivant à l'intérieur des balises <script> </script> dans le corps de votre fichier HTML pour gérer les clics des boutons : :

function main() {
    // Send an event to gemstoneApp.js when the page loads
    // and is ready to get things rolling
    console.log("document ready");
    var readyEvent = {
        "type": "ready",
    };

    // The event bridge handles events represented as a string the best.
    // So we first create a JavaScript object, then convert to string
    EventBridge.emitWebEvent(JSON.stringify(readyEvent));

    // Send an event when user click on each of the gemstone buttons
    $(".gemstone-button").click(function(){
        console.log(this.value + " button click");
        var clickEvent = {
            "type": "click",
            "data": this.value
        };
        EventBridge.emitWebEvent(JSON.stringify(clickEvent));
    });
}
$(document).ready(main);

Ecrire un fichier JavaScript

Votre fichier JavaScript contiendra toutes les fonctionnalités de base de votre application. Au minimum, nous vous demandons de disposer d'un code qui ajoute un bouton au tablet et au HUD, charge votre application, la ferme avec élégance et écoute les événements. Vous trouverez ci-dessous des exemples de code pour chacune de ces fonctions.

Ajouter des boutons au tablet et HUD

Utilisez le module AppUI pour ajouter automatiquement le bouton de votre application au tablet et HUD, et pour câbler les gestionnaires de clic de bouton : :

(function () { // BEGIN LOCAL_SCOPE
var AppUi = Script.require('appUi');

var ui;
function startup() {
    ui = new AppUi({
        buttonName: "APP-NAME", // The name of your app
        home: Script.resolvePath("app.html"), // The path to your app's UI
        graphicsDirectory: Script.resolvePath("./") // The path to your button icons
    });
}
startup();
}()); // END LOCAL_SCOPE

Déterminer le comportement de démarrage de l'application

Si vous souhaitez que votre application fasse quelque chose de spécifique lorsqu'elle est ouverte, utilisez la fonctionnalité onOpen du module AppUI. Par exemple, vous pourriez :

Interroger un serveur pour obtenir une réponse et déterminer ce qu'il faut afficher sur l'interface utilisateur
Commencer à afficher une interface 3D séparée du tablet
Déterminer le mode d'affichage (VR/Desktop) et modifier les éléments à afficher sur l'interface utilisateur

(function () { // BEGIN LOCAL_SCOPE
var AppUi = Script.require('appUi');

function onOpened() {
    console.log("hello world!");
}

var ui;
function startup() {
    ui = new AppUi({
        buttonName: "APP-NAME", // The name of your app
        home: Script.resolvePath("app.html"), // The home screen of your app that appears when clicking the app button
        graphicsDirectory: Script.resolvePath("./"), // Where your button icons are located
        onOpened: onOpened // See the simple function above
    });
}
startup();
}()); // END LOCAL_SCOPE

Fermer l'application avec élégance

Le module AppUI vous permet de fermer votre application avec élégance. Toutefois, si vous souhaitez faire autre chose lorsque vous fermez l'application, vous pouvez le faire grâce à la fonctionnalité "onClosed" intégrée au module AppUI. Par exemple, vous pouvez :

Supprimer les interfaces 3D
Arrêter les scripts secondaires

(function () { // BEGIN LOCAL_SCOPE
var AppUi = Script.require('appUi');

function onOpened() {
    console.log("hello world!");
}

function onClosed() {
    console.log("hello world!");
}

var ui;
function startup() {
    ui = new AppUi({
        buttonName: "APP-NAME", // The name of your app
        home: Script.resolvePath("app.html"), // The home screen of your app that appears when clicking the app button
        graphicsDirectory: Script.resolvePath("./"), // Where your button icons are located
        onOpened: onOpened // See the simple function above
        onClosed: onClosed // See the simple function above
    });
}
startup();
}()); // END LOCAL_SCOPE

Écouter les événements

Dans l'étape 3 ci-dessus, nous avons ajouté des gestionnaires d'événements à votre fichier HTML. Maintenant, vous devez ajouter du code à votre fichier JavaScript pour écouter les événements : :

function onWebEventReceived(event) {
   print("gemstoneApp.js received a web event: " + event);
}
tablet.webEventReceived.connect(onWebEventReceived);

Créez des pierres précieuses

The final step is to code the behavior of your JavaScript file. In this case, we'll create gemstones using Overte's JavaScript API. Each gemstone will be created as an entity, and we can change the gemstone's properties using the Entity namespace.

Calculez la position de chaque nouvelle pierre précieuse

Le code suivant nous donne une position juste devant l'utilisateur : :

// Helper function that gives us a position right in front of the user
function getPositionToCreateEntity() {
  var direction = Quat.getFront(MyAvatar.orientation);
  var distance = 0.3;
  var position = Vec3.sum(MyAvatar.position, Vec3.multiply(direction, distance));
  position.y += 0.5;
  return position;
}

Définissez les propriétés de la pierre précieuse et ajoutez-la

La pierre sera créée lorsque gemstoneApp.js recevra les événements de clic de chacun des boutons : :

// Handle the events we're receiving from the web UI
function onWebEventReceived(event) {
    print("gemstoneApp.js received a web event:" + event);

    // Converts the event to a JavasScript Object
    if (typeof event === "string") {
        event = JSON.parse(event);
    }

    if (event.type === "click") {
        // Define the entity properties of for each of the gemstone, then add it to the scene
        var properties = {
            "type": "Shape",
            "position": getPositionToCreateEntity(),
            "userData": "{\"grabbableKey\":{\"grabbable\":true}}"
        };
        if (event.data  === "Emerald") {
            properties.name = "Emerald";
            properties.shape = "Dodecahedron";
            properties.color = {
                "blue": 122,
                "green": 179,
                "red": 16
            };
            properties.dimensions = {
                "x": 0.20000000298023224,
                "y": 0.26258927583694458,
                "z": 0.20000000298023224
            };
            Entities.addEntity(properties);
        } else if (event.data  === "Ruby") {
            properties.name = "Ruby";
            properties.shape = "Octagon";
            properties.color = {
                "blue": 160,
                "green": 52,
                "red": 237
            };
            properties.dimensions = {
                "x": 0.20000000298023224,
                "y": 0.24431547522544861,
                "z": 0.12547987699508667
            };
            Entities.addEntity(properties);
        } else if (event.data  === "Sapphire") {
            properties.name = "Sapphire";
            properties.shape = "Icosahedron";
            properties.color = {
                "blue": 255,
                "green": 115,
                "red": 102
            };
            properties.dimensions = {
                "x": 0.160745769739151,
                "y": 0.20000000298023224,
                "z": 0.23340839147567749
            };
            Entities.addEntity(properties);
        } else if (event.data  === "Quartz") {
            properties.name = "Quartz";
            properties.shape = "Octahedron";
            properties.color = {
                "blue": 245,
                "green": 142,
                "red": 216
            };
            properties.dimensions = {
                "x": 0.20000000298023224,
                "y": 0.339866042137146,
                "z": 0.20000000298023224
            };
            Entities.addEntity(properties);
        }
    }
}

Congratulations, you have successfully created an app in Overte! To use your app, upload it to a cloud platform, such as Amazon S3, Google Cloud Storage, Microsoft Azure, etc. Once hosted, you can install it and use it:

Dans l'interface, allez à Edit > Running Scripts.
Sous "Load Scripts", cliquez sur "From URL" et entrez l'URL de votre fichier JavaScript hébergé.
Cliquez sur l'icône de l'application sur le tablet ou sur le HUD pour ouvrir l'application.

Voir Aussi