Developer UnityAPI

Project YALLAH - Developers Manual: Unity API (Controlling the Behavior of Characters)

In this document, we list and comment the methods of the YALLAH High-level Unity API.

When you use YALLAH to deploy a character in Unity, the character will have several scripts attached to both the Avatar and the Mesh. Every YALLAH script exposes several methods. This set of methods defines the high-level API. We call it high in contrast with the low level API, which provides control for low-level structures (bones rotations, blendshape weights, and the like).

The high-level API methods can be used to pilot the character from your own scripts.

As an example, you can attach this script to wathever object, drag the character reference to the component panel of this scripts, and the character will tell you which mouse button you pressed:

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class SpeechTest : MonoBehaviour {

    [Tooltip("Please, drag here the character you want to control")]
    public GameObject avatar;

    private MaryTTSController ttsController;

  // Use this for initialization
  void Start () {
        this.ttsController = avatar.GetComponentInChildren<MaryTTSController>();
        Debug.Assert(this.ttsController != null);
  }

  // Update is called once per frame
  void Update () {
        if (Input.GetMouseButtonDown(0))
            this.ttsController.MaryTTSspeak("Pressed primary button.");

        if (Input.GetMouseButtonDown(1))
            this.ttsController.MaryTTSspeak("Pressed secondary button.");

        if (Input.GetMouseButtonDown(2))
            this.ttsController.MaryTTSspeak("Pressed middle click.");
  }

}

The methods are grouped by functionality.

MaryTTS Text-to-speech

• C# script component: Scripts/tts/MaryTTSController.cs
• Attached to: Mesh

Methods:

• void MaryTTSspeak(string) gets a text as input and converts it to speech using Mary TTS platform.
• void MaryTTSstopSpeaking() stops speech sound and lips movement.
• bool IsMaryTTSspeaking() returns true if the character is currently speaking, false otherwise.

Facial Expressions

• C# script component: Scripts/facial_expressions/FacialExpressionsController.cs
• Attached to: Mesh

Methods:

• String[] ListFacialExpressions() lists all the available facial expressions (All Blend shapes starting with fe_)
• string GetCurrentFacialExpression() returns the current facial expression, or Normal if no expression is active.
• void SetCurrentFacialExpression(string expression_name) set the facial expression, by name. If the provided string is not in the list of expressions, nothign happens.
• void ClearFacialExpression() resets the character facial expression to Normal.
• void SetExpressionTransitionTime(float transition_time_secs) set the time needed for a transition between facial expressions.
• float GetExpressionTransitionTime() returns the time, in seconds, needed for the transition between facial expressions.

Eye Blink

• C# script component: Scripts/eyeblink/EyeBlinkController.cs
• Attached to: Mesh

Notes:

This functionality let the character blink its eyes at irregular intervals.

Methods:

No public methods available for this functionality.

Eye Gaze

• C# script component: Scripts/eyegaze/EyeHeadGazeController.cs
• Attached to: Mesh

Notes:

This functionality takes control of the movement of the neck bone and updates it through the LateUpdate(). If you want to leave the control of the neck to other animations, you must disable the neck rotation for this script.

Methods:

• void LookAtPoint(Vector3 point) start moving the eyes to a new target (saccade+fixation).
• void LookAtPoint(float x, float y, float z). Same as before, but using primitive float types.
• void LookAtObject(string target_object_name) starts watching the specified object and keeps on following it as it moves (tracking). If an object with that name doesn't exist, nothing happens.
• public void StopLooking() remove the reference to the trackid object (if any) and resets the head and eyes to the resting position.
• public void SetEnableNeckRotation(bool enable) enable/disable the movement of the neck.
• public bool IsNeckRotationEnabled() returns true if the neck is involved in the gazing motion, false otherwise.

Animation playback

• C# script component: Scripts/animation/AnimationController.cs
• Attached to: Avatar

Methods:

• string[] ListAnimationClips() returns the list of the animations that you can play.
• void PlayAnimationClip(string clip_name) plays the animation with the name provided as input. If an animation with that name is not available, nothing is played. If another animation is already playing, it is not interrupted.
• void PlayAnimationClip(string clip_name). As above, but uses the animation index instead of its name.
• bool IsAnimationClipPlaying() returns true if an animation clip is already playing, false otherwise.
• string GetPlayingAnimationClipName() returns the name of the currently playing animation.
• void EnableAmbientAnimation() enables the ambient animation. When an animation clip is NOT playing, the character loops on a slow idle animation instead of standing straight.
• void DisableAmbientAnimation() disable the ambient motion. When an animation clip is NOT playing, the character will go back to a static pose.
• void IsAmbientAnimationEnabled() returns true if the characters goes back to the ambient motion when the current animation clip is stopped.

Locomotion

• C# script component: Scripts/animation/LocomotionController.cs
• Attached to: Mesh

Notes:

• This locomotion controller doesn't support elevation, yet. The locomotion animations can shift the elevation by themself, of course, but no terrain if followed.
• No collision detection or prevention is supported, yet.
• No path planning is implemented, yet.
• When you start a walking phase, please, be sure you provide a reachable point (e.g., on the floor), or the character will walk forever.

Methods:

• public void WalkTo (Vector3 target_position) starts the locomotion procedure until the character reaches the specified position.
• public void StopWalking() stops the locomotion.
• public bool IsWalking() returns true if the character is currently walking, false otherwise.