Avertissement

This document is outdated. FIXME: Uses HiFi hosted resources, potentially more.

Applications sur Tablet

CE GUIDE N'EST PLUS À JOUR. LE CODE PEUT NE PAS FONCTIONNER EXACTEMENT COMME INDIQUÉ, À UTILISER UNIQUEMENT À TITRE DE RÉFÉRENCE JUSQU'À SA MISE À JOUR. VOIR API DOCS<https://apidocs.vircadia.dev/> POUR EN SAVOIR PLUS.

Les applications pour tablet (ou simplement "apps") dans Vircadia sont des programmes personnalisables qui exposent les fonctionnalités dans une interface utilisateur facile à utiliser. Les applications vous permettent de prendre du code complexe de notre JavaScript API et de le simplifier dans une fenêtre avec des contrôles pour que d'autres puissent l'utiliser.

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 :

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

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

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

  4. É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.

../_images/app-icons.png

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.

../_images/app-ui.png

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

La dernière étape consiste à coder le comportement de votre fichier JavaScript. Dans ce cas, nous allons créer des pierres précieuses en utilisant l'API JavaScript de Vircadia. Chaque pierre sera créée comme une entité, et nous pouvons modifier les propriétés de la pierre en utilisant l'espace de noms "Entity".

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);
        }
    }
}

Félicitations, vous avez réussi à créer une application dans Vircadia ! Pour utiliser votre application, téléchargez-la sur une plateforme de cloud computing, comme Amazon S3, Google Cloud Storage, Microsoft Azure, etc. Une fois hébergée, vous pouvez l'installer et l'utiliser :

  1. Dans l'interface, allez à Edit > Running Scripts.

  2. Sous "Load Scripts", cliquez sur "From URL" et entrez l'URL de votre fichier JavaScript hébergé.

  3. Cliquez sur l'icône de l'application sur le tablet ou sur le HUD pour ouvrir l'application.

Voir Aussi