Live Client for Unreal Engine (Functions and Variables)

Brian Genna -

Live Client for Unreal Engine

The main purpose of Live Client for Unreal is to provide a tool for users of the Faceware Live Server to control animation assets in real time within Unreal Engine 4 by Epic Games. This is achieved by creating a custom implementation of the animation blueprint class used by the Unreal Engine animation system. The additional features built into this class allow the user to configure animations to use the data being streamed by a target Faceware Live Server.

 

Overview

This section outlines how data streamed from the Faceware Live Server moves through the logic of the plugin before it is exposed to users in their created animation blueprints. The general movement of data through the system is summarised visually in the diagram below. The sections of the diagram are colored to denote the following responsibilities:

  • Blue: The Faceware Live Server application external to Unreal Engine 4
  • Orange: The logic and systems built into the Live Client for Unreal plugin
  • Green: The blueprints built by users of the plugin using the Unreal Engine 4 editor

Streamed data from the Faceware Live Server (solid blue) is read from the socket by the networking singleton (clear orange) and then is processed by the json parsing singleton (clear orange). From there the data is passed to Live Anim Instance (solid orange) acting as the base class from which developers can inherit Faceware functionality into their own Blueprints (solid green), or to the Faceware Interface component (solid orange), which will allow developers to access data values within their own Blueprints (solid green) by including the component in those Blueprints.

 

Functions and Variables

 

Live Anim Instance

The Faceware Live Anim Instance class is a type of Anim Instance which allows for access to the data provided by the Faceware Live Server. It contains the configuration variables to enable access to the server, an array that automatically links data point changes to skeletal mesh morph targets and functions allowing for direct access to the data to support custom implementations.

Faceware Interface Component

The Faceware Interface Component is an Unreal Blueprint component which allows access to all data streamed from the Faceware Live Server. By including this component within an Unreal Blueprint developers can imbue classes with the ability to use data from the the Faceware Live server as an input.

The component contains the configuration variables to enable access to a Faceware Live server, getter functions which allow for access to each of the facial data values as well as the head rotation, and functions which detect the status of the connection to the live server.

 

Variables List

 

  • [Property] Address

    - Type: String
    - Description: This property determines the IP address that will be used in conjunction with the configured port when the plugin attempts to retrieve the data streamed by the Faceware Live Server. It conforms to the standard IPv4 format - #.#.#.#   For example, if you are running a Faceware Live Server on a PC on your local network (including if that PC is also running the Unreal Application), and that PC had the IP address 192.168.1.123, you'd set this property to 192.168.1.123.
    - Default Value: Address = None. IP Address is empty by default as the IP address that a given Faceware Live Server will stream from will be specific to an individual user's machine.
  • [Property] Port

    - Type: Integer
    - Description: This property on the Faceware Objects determines the port that will be used in conjunction with the configured address when the plugin attempts to retrieve the data streamed by the Faceware Live Server. This property should be set to the same value as was configured within the Faceware live server application as shown here:  

    - Default Value: Port = 0. This value defaults to zero but should be changed to match the port number configured in the Faceware Live Server application.

  • [Property] Autoconnect

    - Type: Boolean
    - Description: This property on the Faceware Objects determines whether to automatically connect on creation/begin play. Set this to true if you'd like the Faceware object in question to attempt to connect to the specified server as the 'Begin Play' event is triggered.
    - Default Value: Autoconnect = true
  • [Property] Morph Target Pairing

    - Type: Array of Morph Target Pairs
    - Description: This property on the Live Anim Instance contains a name of a morph target and an associated data point that will be retrieved from the stream broadcast by the Faceware Live Server. The Live Anim Instance blueprint will use this property to update the appropriate morph targets each time the animation updates. This property can have its values set up in the editor or configured selectively at runtime to achieve the desired results.
    - Default Value: Morph Target Pairing = Empty array. The array defaults to empty as the names of the morph targets in each element within the array will be specific and unique to the morph targets of the skeletal mesh asset associated with the animation blueprint.

 

Function list

  • Connect

    - Description: This function causes the underlying networking systems to attempt to connect to the Faceware Live Server (if not already connected). This will use the currently set Port and Address.

  • Disconnect

    - Description: This function causes the underlying networking systems to disconnect from the Faceware Live Server. All objects which share the same Port and Address will also be Disconnected.

  • Is Connected

    - Description: This function is used to check whether or not the Faceware Object is currently connected to a Faceware Live Server at the configured ip address and port. It can be used to ensure that logic controlling animation using information streamed by the live server is only executed when the connection has been successfully established.
    - Outputs: Return Value [Boolean]: True if the connection to the server has been established. False if there is no longer any connection to the configured Faceware Live Server.

  • Get Data Value

    - Description: This function allows for the retrieval of specific Faceware Data Points that are streamed from the Faceware Live Server. This function aims to support the building of custom animation behaviors within the animation blueprint system in Unreal Engine 4. For example, selecting 'Jaw Open' as the Data Point will cause this function to return a float value between 0 and 1, representing how open the jaw of the currently observed face within the connected Faceware Live Server is. The resulting float can be plugged into any of the animation or blueprint systems of UE4. The output is identical to calling one of the Getter Functions which are each named for the particular Data Point they expose.
    - Inputs: Data Point [EFacewareDataPoints]: The data point whose current value will be retrieved by the function.
    - Outputs: Return Value [Boolean]: True if the connection to the server has been established. False if there is no longer any connection to the configured Faceware Live Server.

  • Get Head Rotation

    - Description: This function converts the available data from the Faceware Live Server to a FRotator that can be used in the animation blueprint for custom animation behaviors relating to head rotation.
    - Outputs: Return Value [Boolean]: True if the connection to the server has been established. False if there is no longer any connection to the configured Faceware Live Server.

  • Set Seconds Before Disconnect

    - Description: This function will set the time (in seconds) which every Faceware connection on the client machine will wait between valid data from the Live Server. If the time is exceeded, the Disconnect event will be called, allowing for developers to create logic to handle connection failures gracefully.
    - Inputs: SecondsBeforeDisconnect [Float]: The number of seconds the system should wait between valid input from the Faceware Live Server before firing the Disconnect event.

 

Interface Component Event List

  • Event: Connected

    - Description: This event is called whenever the Interface Component's underlying networking code establishes a connection with the Faceware Live Server. Every object with the same Port and Address will receive the event at the same time (sequentially).
  • Event: Disconnected

    - Description: This event is called whenever the Interface Component's underlying networking code loses the connection with the Faceware Live Server. Every object with the same Port and Address will receive the event at the same time (sequentially).
Have more questions? Submit a request

Comments

this.location="http://support.facewaretech.com"
Powered by Zendesk