Événements

Les événements font réagir votre scène aux visiteurs, sans écrire de code. Quand quelque chose se produit, l'objet fait ce que vous avez prévu dans la liste.

QUAND  quelqu'un touche la porte
ALORS  l'ouvrir en 600 ms
       désactiver le panneau « verrouillé »
       envoyer le signal « door-open »

Le quand est un déclencheur. Le alors est une liste d'étapes. Un objet peut avoir autant d'événements que vous le souhaitez, et chacun fonctionne indépendamment des autres.

Ajouter un événement

1. Sélectionnez l'objet.
2. Dans l'inspecteur, cliquez sur + new component et choisissez Events. Le composant commence avec un événement, réglé sur Press on the object.
3. Cliquez sur l'événement. Le panneau Event settings s'ouvre. Pour ajouter un autre événement, cliquez sur + add event.
4. Choisissez un déclencheur, ou gardez Press on the object.
5. Cliquez sur + add action et choisissez une étape. La liste a un champ de recherche, et les étapes sont rangées dans Actions, Animations, States et Logic.
6. Ajoutez d'autres étapes de la même façon. Elles s'exécutent dans l'ordre.

Deux listes à garder sous la main

La référence des déclencheurs liste tous les déclencheurs. La référence des étapes liste toutes les étapes. Les deux sont toujours à jour. À côté du nom affiché dans l'éditeur, elles donnent le nom dans le code pour les scripts : Send signal correspond à emit_signal, et Signal à on-signal.

Déclencheurs

Un déclencheur est le moment où un événement démarre. Les références ci-dessus donnent les réglages de chaque déclencheur. Les tableaux ci-dessous indiquent à quoi sert chacun.

Pointeur et touches

Dans l'éditeur	Se déclenche quand
Press on the object	quelqu'un touche l'objet ou clique dessus ; branches pour le clic, l'appui et le relâchement
Hover	le curseur arrive sur l'objet ou le quitte
Double click	deux clics sur le même objet en moins de 300 ms
Long press	l'objet est maintenu 450 ms sans bouger
Key	une touche est enfoncée ou relâchée
Scroll	la molette tourne ; vous pouvez choisir un sens
Drag	quelqu'un fait glisser le contenu AR qu'il a placé
Pinch	quelqu'un pince le contenu AR placé pour changer sa taille
Rotate	quelqu'un fait pivoter le contenu AR placé

Drag, Pinch et Rotate fonctionnent uniquement dans les scènes de type surface, car ils agissent sur du contenu que le visiteur a placé. Ils se déclenchent en continu tant que le doigt bouge, et pas une seule fois.

Cycle de vie

Dans l'éditeur	Se déclenche quand
Launch	la scène démarre ; tous les objets le reçoivent
Resize	la fenêtre ou l'écran change de taille
Pause	l'application ou l'onglet passe en arrière-plan
Resume	l'application ou l'onglet revient au premier plan
Visibility	l'objet est affiché ou masqué

Coupez le son sur Pause

Les sons continuent quand un visiteur change d'application, sauf si vous les arrêtez. Arrêtez-les sur Pause, par exemple en passant à un état dans lequel le son est coupé, et relancez-les sur Resume.

Suivi AR

Dans l'éditeur	Se déclenche quand
Detect	le marqueur ou la surface est trouvé
Tracking lost	le suivi est perdu
Placed	le visiteur a placé le contenu
VPS ready	le positionnement a démarré
VPS localized	la position réelle du visiteur a été trouvée
VPS localization failed	la position n'a pas encore été trouvée
VPS error	le positionnement n'a pas pu démarrer du tout

L'éditeur ne propose que les déclencheurs que l'ancre de votre scène peut produire. Detect se déclenche une seule fois, au début du suivi, et non à chaque image.

Un échec de localisation VPS est normal

VPS localization failed se déclenche souvent pendant que le visiteur se déplace à la recherche d'un endroit que la carte connaît. Voyez-le comme un « on continue de chercher », pas comme une erreur à afficher.

Temps et distance

Dans l'éditeur	Se déclenche quand
Delay	une fois, après un délai
Every N seconds	encore et encore ; un nombre de répétitions de 0 veut dire sans fin
Distance	quelque chose s'approche à moins d'une certaine distance, ou s'éloigne
Variable change	une variable prend une nouvelle valeur

Distance a une option At start. Activez-la si un objet risque d'être déjà proche à l'ouverture de la scène. Sans elle, l'événement attend que quelque chose bouge.

États, collisions et signaux

Dans l'éditeur	Se déclenche quand
State active	cet objet entre dans l'état que vous avez choisi
State inactive	cet objet quitte cet état
Collision	cet objet en touche un autre ; Collide with limite les objets concernés
UI action	quelqu'un a appuyé sur un bouton d'une carte d'interface
Signal	un autre événement a envoyé un signal
Game controls	le personnage s'arrête, se déplace, court ou saute

Branches

Certains déclencheurs ont des branches : un seul événement peut alors gérer chaque cas. Par exemple, un seul événement Distance peut répondre à la fois à « s'est approché » et à « s'est éloigné ».

Déclencheur	Branches
Distance	On coming closer, On moving away
Key	On press, On release
Hover	On enter, On leave
Press on the object	On click or tap, On press, On release
Visibility	On show, On hide
Game controls	On idle, On move, On run, On jump

Chaque branche a sa propre liste d'étapes. Un déclencheur sans branches a une seule liste, On activation.

Choisir les objets visés par une étape

Chaque étape a un champ Target object.

• Laissez-le vide : l'étape agit sur l'objet qui porte l'événement. C'est le cas le plus courant.
• Choisissez des objets : l'étape agit sur eux à la place. C'est ainsi qu'un seul bouton ouvre trois portes.

Les appuis remontent aux objets parents

Un appui, un survol ou une action de carte atteint l'objet et tous ses parents.

Vous pouvez donc placer un seul événement sur un groupe : il capte les appuis sur tout ce que le groupe contient. Inutile de copier le même événement sur quarante objets.

Cela veut aussi dire que :

• « appuyer n'importe où sur ce panneau » se règle avec un seul événement sur le panneau ;
• passer le curseur d'un enfant à un autre du même parent ne déclenche ni l'entrée ni la sortie du survol sur le parent, car le curseur ne l'a jamais quitté.

Certains déclencheurs fonctionnent autrement :

• Collision se déclenche uniquement sur les objets qui se sont touchés.
• Key, Scroll, Resize et Launch ne concernent pas un objet en particulier : tous les objets les reçoivent.

Les événements, les patchs et les scripts reçoivent les mêmes touchers, touches et collisions. Quelques déclencheurs arrivent dans les scripts sous d'autres noms. Voir L'API ctx.

Gérez chaque déclencheur à un seul endroit

Si le même objet réagit au même déclencheur dans un événement et dans un script, l'action s'exécute deux fois. Quand quelque chose se déclenche deux fois, c'est presque toujours la raison.

Plusieurs touches pour un même événement

« Sauter avec Espace ou W » est un seul événement, pas deux. Cliquez sur le champ Key et appuyez sur la première touche. Cliquez ensuite sur or et appuyez sur la suivante. Ajoutez-en autant qu'il vous faut.

• Chaque touche de la liste compte à elle seule. Un modificateur comme Ctrl ne s'applique qu'à la touche avec laquelle il a été enfoncé.
• Les autres réglages du déclencheur, comme Auto-repeat, s'appliquent à toutes les touches de la liste.
• Un bouton de la souris fonctionne dans le même champ. La liste ne contient alors que des boutons de la souris.

L'événement enregistre ces touches sous forme de texte. Un assistant ou un script les écrit ainsi :

ArrowUp        ctrl+KeyW        KeyA+KeyS        Space+double        mouse:middle

Au lieu d'une touche, vous pouvez aussi utiliser une affectation de touches (key binding). Créez vos affectations dans Project settings → Key bindings. Changez-y une seule fois la touche de « jump », et tous les événements qui utilisent « jump » suivent. C'est pratique quand quelqu'un demande des commandes pour gaucher.

Étapes

La référence des étapes donne les réglages de chaque étape.

Liens, appels et changements de scène

Dans l'éditeur	Effet
Scene transition	passe à une autre scène
Space transition	passe à un autre espace, et à une scène précise si vous en choisissez une
Open URL	ouvre un lien, dans cet onglet ou dans un nouvel onglet
Open messenger	ouvre Facebook, VK, OK, Instagram, Telegram, WhatsApp ou Viber
Call phone number	lance un appel téléphonique
Compose email	commence un e-mail
File download	télécharge un fichier de votre projet
Contact download	propose une fiche contact créée à partir des champs que vous remplissez

Open messenger demande des informations différentes selon l'application :

• un identifiant de page pour Facebook, VK et OK ;
• un nom d'utilisateur pour Instagram et Telegram ;
• un numéro de téléphone pour WhatsApp et Viber.

Afficher, masquer et modifier des objets

Dans l'éditeur	Effet
Show / hide object	affiche ou masque les cibles ; sur une scène, rend cette scène active
Set state	passe à un état enregistré, en douceur si vous réglez une durée
Override properties	applique quelques valeurs une seule fois, comme un état temporaire

Animation

Dans l'éditeur	Effet
Play animation	lance une animation de la timeline, avec mode de boucle, répétitions, vitesse et délai
Stop animation	en arrête une

Play animation peut lancer une animation qui appartient à n'importe quel objet. Un seul bouton peut donc lancer une séquence qui fait bouger plusieurs éléments à la fois.

Pour déplacer un objet, le faire disparaître en fondu ou changer sa couleur, créez une animation dans le panneau Animation, puis lancez-la avec cette étape. Pour un seul changement, Set state avec une durée suffit.

Les projets créés plus tôt peuvent aussi contenir les étapes Transformation, Opacity, Material, Bone transform et Built-in animation. Elles fonctionnent toujours dans ces projets, mais l'éditeur ne les propose plus. Material, par exemple, fait évoluer la couleur, l'opacité, la lueur et les réglages de surface des cibles vers un matériau enregistré, en gardant le type et les textures de chaque emplacement.

Mouvement

Dans l'éditeur	Effet
Follow object	suit un autre objet en continu ; vous réglez la distance, le décalage, le lissage et la vitesse
Look at object	se tourne vers quelque chose sans se déplacer
Stop following	arrête de suivre et de regarder
Fly along path	se déplace le long d'un chemin
Stop path flight	arrête le déplacement le long du chemin

Logique

Dans l'éditeur	Effet
If — otherwise	vérifie une condition, puis exécute l'une de deux listes d'étapes
Set variable	donne une valeur à une variable, lui ajoute une valeur ou l'inverse
Send signal	envoie un signal aux objets choisis ou à toute la scène
Wait, then	attend, puis exécute les étapes qu'elle contient

Pointeur

Lock pointer masque le curseur de la souris et laisse la scène utiliser ses mouvements. Les jeux à la première personne en ont besoin, pour que le curseur ne sorte pas de la fenêtre. Release pointer rend le curseur.

Déclencheurs et étapes des plugins

Un plugin ajouté à votre projet peut apporter ses propres déclencheurs et ses propres étapes. Ils apparaissent dans les listes sous le nom du plugin, et vous les utilisez comme ceux qui sont intégrés.

• Ils ne sont là que dans les projets auxquels le plugin a été ajouté.
• Le déclencheur d'un plugin peut avoir des réglages. L'événement ne s'exécute alors que lorsqu'ils correspondent. Laissez un réglage vide pour réagir à chaque fois.
• Si le plugin est retiré du projet, ses déclencheurs ne s'activent plus jamais et ses étapes sont ignorées.

Pour créer les vôtres, voir Code d'exécution.

Ajouter une condition

Une condition est une étape : If — otherwise. Vous pouvez en placer une dans une autre pour obtenir plus de deux issues.

Choisissez ce que l'étape vérifie dans le champ Condition :

Dans l'éditeur	Vérifie	Champs à remplir
Always	rien ; la condition est toujours vraie	—
Variable	la valeur d'une variable	Variable, Compare, Value
Distance	la distance entre l'objet de cet événement et un autre objet	Object, Compare, Threshold
State	l'état dans lequel se trouve un autre objet	Object, State
Visibility	si quelque chose est visible	Object, Expected
Chance	un tirage au hasard	Threshold, en pourcentage

Comment les valeurs sont comparées :

• 3 est lu comme un nombre, true comme oui/non, et tout le reste comme du texte.
• == et != vérifient que les valeurs sont exactement identiques.
• >, >=, < et <= comparent des nombres.

Variables, signaux et minuteurs

Les variables durent le temps d'une visite. Elles sont vides chaque fois que quelqu'un ouvre votre projet. Pour leur donner une valeur de départ, réglez-les dans un événement avec le déclencheur Launch. Un script voit ces mêmes variables comme variables globales.

Les signaux permettent à un événement d'en lancer d'autres sans copier d'étapes. Par exemple, plusieurs événements peuvent attendre level-complete, et n'importe quel événement peut l'envoyer. Si un signal se renvoie sans cesse à lui-même, il s'arrête après huit tours, pour que la scène ne se fige pas.

Les minuteurs (Delay et Every N seconds) démarrent quand leur objet s'active et se remettent à zéro quand il se désactive. Quand l'objet se réactive, le décompte repart du début. Les déclenchements manqués ne sont pas rattrapés d'un coup.

États

Un état est une apparence enregistrée d'un objet : sa position, sa couleur, sa visibilité, etc. L'étape Set state permet d'y passer. Avec une durée, le changement se fait en douceur.

Utilisez les états pour un interrupteur, une mise en surbrillance, ou une porte ouverte ou fermée.

Quand un état est sélectionné, vos modifications vont dedans

Si l'un des états de l'objet est sélectionné, modifier l'objet modifie cet état. C'est ce que vous voulez quand vous créez des états. C'est déroutant si vous avez oublié qu'un état était sélectionné.

Pour en savoir plus, voir États.

Reprise du suivi

Dans les scènes AR, chaque événement a un mode de reprise du suivi. Il définit ce qui se passe quand le marqueur est perdu puis retrouvé :

• relancer les étapes tout de suite ;
• ne jamais les relancer ;
• les relancer une fois que les étapes en cours sont terminées.

---

Suivant : Animation — faire bouger les objets.