Unity - AS

User’s Guide
Famic Technologies Inc. All rights reserved.©

Automation Studio™ - Unity manual

Document Reference: DASUNENFTZ63U_ 001

REPRODUCTION

Reproduction or re-transmission of this manual or software, in whole or in part, by any means is

strictly prohibited without the express written consent of Famic Technologies Inc.

Windows is a registered trademark of Microsoft Corporation.

Automation Studio™ is a registered trademark of Famic Technologies®
 Table of Contents

1 Introduction....................................................................................................................

2 Unity Configuration.......................................................................................................

2.1 Installation..............................................................................................................

2.1.1 Sample Project Installation.......................................................................

2.2 Server Configuration..............................................................................................

2.2.1 Server Configuration Menu......................................................................

2.2.2 Server Launch...........................................................................................

2.3 Unity Game Object Configuration..........................................................................

2.3.1 Script Inclusion.........................................................................................

2.3.2 Method requirements................................................................................

2.4 (Example) Creating a New Unity Project...............................................................

2.4.1 Create the Project......................................................................................

2.4.2 Launch Menu............................................................................................

2.4.3 Feedback Menu.........................................................................................

2.4.4 Object Creation.........................................................................................

2.4.5 Object Movement.....................................................................................

3 Automation Studio™ Configuration..........................................................................

3.1 Installation............................................................................................................

3.2 Client Configuration.............................................................................................

© Famic Technologies inc. i

 3.2.1 Unity Path...............................................................................................

3.2.2 Ribbon Implementation..........................................................................

3.2.3 Connection to Server..............................................................................

3.2.4 Variables.................................................................................................

3.2.5 Feedback Variables Client-side..............................................................

3.2.6 Alternative Developer Ribbon................................................................

4 Troubleshooting............................................................................................................

4.1 Unity Troubleshooting..........................................................................................

4.1.1 User Interface.........................................................................................

4.1.2 Object Movement...................................................................................

4.1.3 Errors......................................................................................................

4.2 Automation Studio™ Troubleshooting................................................................

4.2.1 User Interface.........................................................................................

4.2.2 Variables.................................................................................................

4.2.3 Connectivity............................................................................................

A Glossary..............................................................................................................................

B Index....................................................................................................................................

1 Introduction......................................................................................................................

2 Unity Configuration..........................................................................................................

2.1 Installation..............................................................................................................

2.2 Server Configuration..............................................................................................

© Famic Technologies inc. ii

 Table of Contents

2.2.1 Server Configuration Menu......................................................................

2.2.2 Server Launch...........................................................................................

2.3 Unity Game Object Configuration..........................................................................

2.3.1 Script Inclusion.........................................................................................

2.3.2 Method requirements................................................................................

2.4 (Example) Unity Project.........................................................................................

2.4.1 Create the Project......................................................................................

2.4.2 Launch Menu............................................................................................

2.4.3 Feedback Menu.........................................................................................

2.4.4 Object Creation.........................................................................................

2.4.5 Object Movement.....................................................................................

3 Automation Studio™ Configuration..............................................................................

3.1 Installation............................................................................................................

3.2 Client Configuration.............................................................................................

3.2.1 Unity Path...............................................................................................

3.2.2 Ribbon Implementation..........................................................................

3.2.3 Connection to Server..............................................................................

3.2.4 Variables.................................................................................................

3.2.5 Feedback Variables Client-side..............................................................

3.2.6 Alternative Developer Ribbon................................................................

4 Troubleshooting..............................................................................................................

© Famic Technologies inc. iii

Automation Studio™ – Unity

4.1 Unity Troubleshooting..........................................................................................

4.1.1 User Interface.........................................................................................

4.1.2 Object Movement...................................................................................

4.1.3 Errors......................................................................................................

4.2 Automation Studio™ Troubleshooting................................................................

4.2.1 User Interface.........................................................................................

4.2.2 Variables.................................................................................................

4.2.3 Connectivity............................................................................................

A Glossary...............................................................................................................................

B Index....................................................................................................................................

1 Introduction......................................................................................................................

2 Unity Configuration..........................................................................................................

2.1 Installation..............................................................................................................

2.2 Server Configuration..............................................................................................

2.2.1 Server Configuration Menu......................................................................

2.2.2 Server Launch...........................................................................................

2.3 Unity Game Object Configuration..........................................................................

2.3.1 Script Inclusion.........................................................................................

2.3.2 Method requirements................................................................................

2.4 (Example) Unity Project.........................................................................................

2.4.1 Create the Project......................................................................................

iv
 Table of Contents

2.4.2 Launch Menu............................................................................................

2.4.3 Feedback Menu.........................................................................................

2.4.4 Object Creation.........................................................................................

2.4.5 Object Movement...................................................................................

3 Automation Studio™ Configuration..............................................................................

3.1 Installation............................................................................................................

3.2 Client Configuration.............................................................................................

3.2.1 Unity Path...............................................................................................

3.2.2 Ribbon Implementation..........................................................................

3.2.3 Connection to Server..............................................................................

3.2.4 Variables.................................................................................................

3.2.5 Feedback Variables Client-side..............................................................

3.2.6 Alternative Developer Ribbon................................................................

4 Troubleshooting..............................................................................................................

4.1 Unity Troubleshooting..........................................................................................

4.1.1 User Interface.........................................................................................

4.1.2 Object Movement...................................................................................

4.1.3 Errors......................................................................................................

4.2 Automation Studio™ Troubleshooting................................................................

4.2.1 User Interface.........................................................................................

4.2.2 Variables.................................................................................................

© Famic Technologies inc. v

Automation Studio™ – Unity

4.2.3 Connectivity............................................................................................

A Glossary...............................................................................................................................

B Index....................................................................................................................................

vi
1 Introduction
This guide is intended for users with a basic knowledge of Unity.

This guide presents the means of communication between Unity and Automation Studio™. We
present concrete examples of how to use both the URC and URS dynamic link libraries.

The acronym URC stands for UnityRemoteClient and the acronym URS stands for
UnityRemoteServer. The Automation Studio™ project acts as the client and the Unity project
acts as the server.

The URC – URS are optional modules of Automation Studio™. They:

 Allow configuration of data exchange

 Allow consistency of operation with other modules of Automation Studio™

 Provide components that enable data exchange

The URC – URS allow the exchange of information between Automation Studio™ and Unity and
form a connection between local Variables using External Variables in a JSON file.

Each External Variable essentially connects a Variable on the client side to a Variable on the
server side. Each External Variable is given a Role of either Import or Export that defines
whether their values are managed by the Client or Server.

Figure 1-1: Overview of the architecture between Unity and Automation Studio™

© Famic Technologies inc. 1

2 Unity Configuration

2.1 Installation

 Copy the AS.API.UnityRemoteServer.dll into the Unity project’s Assets folder

 Open the project in Visual Studio and add AS.API.UnityRemoteServer.dll to the

project as a reference

 Make sure the Newtonsoft.Json.dll can be found is added toin the directory: C:\
ProgramData\Famic Technologies\Automation Studiodd-ons P6.X\Scriptsbin\(x64 or
x32)

2.1.1 Sample Project Installation

 Navigate into the “Unity Build” folder to find the ‘SampleProject’. This is the built
sample Unity project that must be placed into the Apps folder found at : C:\
ProgramData\Famic Technologies\3D Systems\Apps

 The Sample.prx can be run from anywhere. Once the project is loaded, navigate to the
‘3D Link’ tab at the top and select ‘Show’. This will open the Unity build associated
with this project.

 Press ‘Start’ in the 3D Link tab to begin the simulation and create the connection
between AS and Unity. The connection indicator in the Unity build should turn green at
this point to show that the connection was successful.

2.2 Server Configuration

The server used for communication between Automation Studio™ and Unity is an asynchronous
TCP socket server that requires an IP address and a Port to create a connection.

If Automation Studio and the corresponding Unity build are being run on the same machine, the
IP address should remain the default ‘127.0.0.1’. If separate machines are being used, the target

© Famic Technologies inc. 2

 Troubleshooting

ip address and port can be configured in the extcom.config file found at C:\ProgramData\Famic
Technologies\3D Systems\Apps on both machines.

2.2.1 Server Configuration Menu

Create a folder called “Prefabs” in the Assets folder of the Unity project. Import the “Menu
Canvas.prefab” file and drag it into your scene. Add the proper scripts to the game objects in the
prefab (see project example). The prefab contains a game object for the AsyncTCPSocketServer
which holds two InputField type variables whose values are used as the IP address and Port for
the TCP connection.

Figure 2-2: Game Object with AsyncTCPSocketServer script added

2.2.2 Server Launch

The server must be launched from the Unity project before the client, Automation Studio™, can
connect to it. This is achieved by calling the LaunchServer() method from the
ASyncTCPSocketServer script. This is handled automatically when a build is started or the Unity
Window is opened from within Automation Studio.

For manual control of server launch, To do this attach the LaunchServer() method to the
LaunchServerButton’s OnClick event, found within the Menu Canvas prefab.

© Famic Technologies inc. 3

Automation Studio™ – Unity

Figure 2-3: Unity UI button OnClick event calling LaunchServer

Once the server is launched, it begins listening for an incoming connection. The server safely
quits and closes the TCP connection on application close.

2.3 Unity Game Object Configuration

2.3.1 Script Inclusion

Each Game Object within Unity that includes at least one Variable to be controlled by a
corresponding Variable in Automation Studio™ must include a script, which inherits from the
Item script in the dll. The script can be from anywhere in the inheritance hierarchy under Item
and does not need to be an immediate child.

Figure 2-4: Script inclusion to Unity Game Object with Item script inheritance

4
 Troubleshooting

2.3.2 Method requirements

The Item script inherits from UnityEngine.MonoBehaviour, which exposes the methods Awake,
Start and Update to be overridden.

 Awake() is called before Start() and after all game objects have been initialized. It is
called exactly once in the lifetime of the script. Its requirements for this module are as
follows:

1. A new External Variable should be created for each value to be exchanged

between a Variable in Unity and its corresponding Variable in Automation
Studio™.

2. External Variables must be created using the following constructor:

ExternalVariable(string name, Role _role, Type _type)
 Name(string): name of the variable. A matching variable will be
created in Automation Studio™ if it does not exist.
 Role(enum)
 Import: a variable whose value can be manipulatedis altered
in Automation Studio™ and sent to Unity.
 Export: a feedback variable whose value is alteredaltered in
Unity and sent to Automation Studio™.
 Type(enum)
 Float: a variable with a REAL typing in Automation Studio™
 Bool: a variable with a BOOL typing in Automation Studio™

[3.] Each External Variable must be added to the inherited list of External Variables
from the Item script called variables. (see Figure 23-43)

[4.] The variable Model inherited from the Item script should be set to the Game
Object that the current script is attached to. (see Figure 3-3)

[5.] The static method call VariableBinder.SendItemToBinder(this); should

follow the addition of all External Variables for a given script. This call ensures
that each External Variable is written to the JSON file shared between Unity
and Automation Studio™.

© Famic Technologies inc. 5

Automation Studio™ – Unity

Figure 2-5: Example Awake method withand required contents for communication

 Start() is called on the frame when a script is enabled and right before any of the
Update() methods are called for the first time. It is called exactly once in the lifetime of
the script. It has no specific requirements related to the communication between Unity
and Automation Studio™.

 Update() is called once per frame once the game has started. The requirements for this
method are as follows:

 Role.Export: Variables with the Role “Export” are updated locally every frame
and shared with Automation Studio™.

Figure 2-6: Update method for Export variable

 Role.Import: Variables with the Role “Import” are updated every frame with
the changes made by Automation Studio™.

Figure 2-7: Update method for Import variable

6
 Troubleshooting

 Note: LateUpdate() may be used instead of Update().

2.4 (Example) Creating a New Unity Project

2.4.1 Create the Project

1. Open the Unity application and create a new 3D project.

2. Right click on the “Assets” folder in the Project tab, select “Import New Asset…” and
import the “AS.API.UnityRemoteServer.dll”.

2.4.2 Launch Menu

3. Create a new folder called “Prefabs” and import the asset “Menu Canvas.prefab”.

4. Create a new folder called “Scripts” and import the script “ButtonManager.cs”.

5. Drag the new prefab into the Hierarchy tab. It should now look like the image below:

Figure 2-8: UI prefab with server information

© Famic Technologies inc. 7

Automation Studio™ – Unity

6. Navigate to the AsyncTCPSocketServer game object, press the button to the right of the
missing script, and select “AsyncTCPSocketServer”.

Figure 2-9 : Missing script

7. Use the buttons to the right of each InputField to select the proper references as seen
below.

Figure 2-10: Async TCP Socket Server script configuration

8. Navigate to the VariableBinder game object and replace one of the missing scripts with
the “VariableBinder” script. Change the “Server” field to the “AsyncTCPSocketServer”
game object.

Figure 2-11: VariableBinder script configuration

8
 Troubleshooting

9. Replace the second missing script with the “ButtonManager” script. Set the fields as seen
below.

Figure 2-12: ButtonManager script configuration

[10.] Navigate to the LaunchServerButton in the Hierarchy tab: Menu Canvas/Server

Panel/Server Buttons/LaunchServerButton.

[11.] In the Inspector tab find the Button script and change the “On Click” details as seen
below.

Figure 2-13: ButtonManager On Click event

[2.4.3] Feedback Menu

10.[12.] In the “Scripts” folder, import the “FeedbackSlider” script.

11.[13.] Make sure an EventSystem game object exists somewhere in the hierarchy so the
slider will be interactable.

[14.] Navigate to the FeedbackSliderAA inside the Feedback Panel, attach the newly imported
script as a component, and configure it as seen below.

Figure 2-14: Feedback Slider script configuration

© Famic Technologies inc. 9

Automation Studio™ – Unity

[15.] Navigate to the Feedback Slider child object of FeedbackSliderAA. In the Inspector,
change the On Value Changed event in the Slider (Script) to call
FeedbackSlider.UpdateSliderValue.

Figure 2-15: Feedback Slider On Value Changed event

2.4.3[2.4.4] Object Creation

12.[16.] Right click in the Hierarchy tab and create a new sphere from the 3D Objects section.

13.[17.] Make sure the new sphere object can be seen by the main camera by setting its
position in the Transform section of the Inspector tab to (0,0,0).

2.4.4[2.4.5] Object Movement

14.[18.] In the “Scripts” folder, import the “MovementController” script and attach it as a new
component to the sphere.

15.[19.] Set both the Model and Model Transform fields to the Sphere object and Sphere
(Transform) respectively.

16.[20.] In the Movement Axis field, you can select the axis or axes you want the sphere to
move on. The scale of movement can be altered by the values given to each axis.

17.[21.] Min and Max values are used as limits to the movement of the object. The value that
is actually transferred between Automation Studio™ is the Clamped Value, which has a
range of 0 to 1. At a Clamped Value of 0, the object will be at the MinValue and at a
value of 1 it will reach the MaxValue.

10
 Troubleshooting

Figure 2-16: Movement Controller script configuration

[22.] The Old Coords and Target Coords will be managed by the external variable and do not
need to be manipulated.

[3] Automation Studio™ Configuration

2.5[3.1] Installation

 If using the installer, everything will be placed in the correct paths needed for the Unity
module to work. Unity builds must be placed in: C:\ProgramData\Famic Technologies\
3D Systems\Apps

 If installing manually,Copy place the directory UnityApps into: C:\ProgramData\

Famic Technologies\3D Systems\Automation Studio P6.X\Scripts\

o The built Unity project should be added into the UnityApps directory as its own
folder. This folder must include the “_Data” folder, “Mono” folder, the project
executable file (.exe), the CrashHandler, the “UnityPlayer.dll” and the
“WinPixEventRuntime.dll”.

© Famic Technologies inc. 11

Automation Studio™ – Unity

Figure 3-17: Example built Unity project in required directory

o Copy the AS.API.UnityRemoteClient.dll into: C:\ProgramData\Famic

Technologies\Add-ons\bin\(x64 or x32)Automation Studio P6.X\Scripts\

o Add icons into the directory: C:\ProgramData\Famic Technologies\3D Systems\

Icons. C:\ProgramData\Famic Technologies\Automation Studio P6.X\Scripts\Icons.
The icons should be named as follows:

o unity.ico for the Show button.

o start.ico for the Start button.

o stop.ico for the Stop button.

2.6[3.2] Client Configuration

2.6.1[3.2.1] Unity Path

The path to the built Unity executable file (.exe) must be set as a user-defined variablecan be
found in the project properties as a user-derfined variable “Unity_Path”. To create this variable:
The syntax is as follows:

Navigate to the “Project Properties” from the “View” tab, find the “Information” section, and
select the “Add variable” button.

12
 Troubleshooting

Figure 3-18: Adding a user defined variable in Project Properties

Set the name and alias of the new variable to “Unity_Path”. Set the type to “STRING”, and leave
the measurement type as “Without Unit”.

Find the new variable in the “User-Defined” category and change its value to: “.\\
Path_to_Unity_build_folder_in_UnityAPPApps\\Name_of_Unity_project.exe”

Figure 3-192: Unity_Path variable value

2.6.2[3.2.2] Ribbon Implementation

Automation Studio™ uses a ribbon accessible from the main toolbar to expose the functionality
required for Unity connection.

Figure 3-203: Ribbon exposing Unity connectivity options

To add this ribbon to the Automation Studio™ project, open the “Project Properties” from the
“View” tab and navigate to the “Parameters” section. Find the “Startup Script” parameter, and set
its value to: “METHOD:AS.API.UnityRemoteClientV2::ApplicationClientApi::InitFullRibbon”.

© Famic Technologies inc. 13

Automation Studio™ – Unity

Figure 3-214: Startup Script parameter found in the Project Properties

Note: The Automation Studio™ project will need to be saved, closed and reopened for the ribbon
to be displayed.

Note: An alternative ribbon with developer and debug options is available.

2.6.3[3.2.3] Connection to Server

From the new “3D Link” ribbon, the Unity window can be opened by selecting the “Show”
button. The Unity window will run the executable from the “Unity_Path” variable.

The server must be running and listening for a connection before the client can connect to it.
From the Unity window, select the button that calls the LaunchServer() method. This process is
done automatically in AS 6.4 and later versions.

2.6.4[3.2.4] Variables

“Component Variables” in Automation Studio™ to be shared with the Unity project must be
associated to the appropriate “Compatible Simulation Variables”. This association is managed
from the “Component Properties” in the “Variable Assignment” section.

 Variables with the type “FLOAT” on the Unity side should have a corresponding
simulation variable with type “REAL” and a component variable with type “LREAL”.

 Variables with the type “BOOL” on the Unity side should have a corresponding
simulation variable type “BOOL” and a component variable with type “BOOL”.

14
 Troubleshooting

When the project is run, the list of External Variables is parsed and if any External Variables do
not have a corresponding Component Variable, they are generated automatically. The simulation
will need to be run for the first time before the variable associations can be made.

Associations can be made between Simulation variables and Component variables from the
Component properties as seen below.

Figure 3-22: Association made between Component Variable and Simulation Variable

2.6.5[3.2.5] Feedback Variables Client-side

Feedback variables represent values that are managed by Unity and sent to Automation Studio™.
These variables are added to the External Variables JSON with the Role enumeration set to
“Export”. If they are not present in Automation Studio™, they will be generated automatically.
Feedback variable values may be observed from the “Variable Manager” in Automation
Studio™.

2.6.6[3.2.6] Alternative Developer Ribbon

To add the developer ribbon to the Automation Studio™ project, open the “Project Properties”
from the “View” tab and navigate to the “Parameters” section. Find the “Startup Script”
parameter, and set its value to:

© Famic Technologies inc. 15

Automation Studio™ – Unity

“METHOD:AS.API.UnityRemoteClient::ApplicationClientApi::InitFullRibbonWithDev”.

Figure 3-23: Developer ribbon implementation

The developer ribbon provides buttons to perform each of the steps taken in creating the
connection between Automation Studio™ and Unity.

 Inspector: A console attached to the current project where useful information can be
found about the connection status. Note: Quick Edit Mode will be disabled in the
console when using the Inspector.

 Show Unity Window: Displays the Unity Window and runs the Unity project
executable inside it. By default, the server is set to launch on startup. External variables
created by the Unity project (server) will be written to an external JSON file when it is
launched.

 Bind External Variables: Imports the external variables from the external JSON file,
creates a new variable in Automation Studio™ if it does not exist and adds them all to
the list of bindings.

 Initialize Bindings: Deserializes the bindings from JSON format and initializes each of
the variables in Automation Studio™. Read the connection configs from the
extcom.configs file.

 Connect to Server: Launches the client using the Ip address and port from the
connection configs and then starts the Automation Studio™ simulation.

 Disconnect: Stops the simulation and closes the connection between Automation
Studio™ and Unity. The server will need to be relaunched before the client can connect
to it again.

16
 Troubleshooting

3[4] Troubleshooting

3.1[4.1] Unity Troubleshooting

3.1.1[4.1.1] User Interface

 Launch button or Feedback slider are not interactable:

 Make sure an EventSystem game object has been added to the scene.
The EventSystem does not need to be altered in any way.

 My object can’t be seen in the Unity window:

 Make sure the Transform component of the object has the position
fields set to a spot that can be seen by the main camera. If the camera
was not altered, setting the objects position to (0,0,0) will bring it into
view.

 I cannot change the IP Address or Port:

 The IP Address and port can be changed by editing the extcom.config

file found in the AppsUnityApp folder.

3.1.2[4.1.2] Object Movement

 Object does not move in the Unity window:

 Ensure at least one axis of the Movement Axis field is set above 0 in
the MovementController script.

 Check that the Min Value and/or Max Value fields in the
MovementController script are set to something other than 0.

 Make sure the Model Transform field in the MovementController

script is set to the object that should be moving.

 Ensure that the name used for the External Variable created by the
MovementController script is the one bound to the correct variable in

© Famic Technologies inc. 17

Automation Studio™ – Unity

Automation Studio™.

 The object is moving more or faster than expected: The clamped value
by default is given a range between 0 and 1, the output of certain
components in Automation Studio™ have the range -10 to 10.
Matching these ranges, either in the MovementController script or the
component itself may fix the issue.

3.1.3[4.1.3] Errors

 Errors show in the inspector when closing the Unity window:

 If the simulation is still running when the Unity window is closed,

several methods trying to communicate between Automation Studio™
and Unity will fail as the connection is killed abruptly. These errors
are for acknowledgement and will not affect the project.

3.2[4.2] Automation Studio™ Troubleshooting

3.2.1[4.2.1] User Interface

 Ribbon does not appear:

 The project needs to be closed and reopened after setting the startup
script of the project for the first time.

3.2.2[4.2.2] Variables

 External Variables do not show up in the Compatible Simulation Variables list:

 The server needs to be launched and the simulation started one time
before the variables are created.

 The inspector console is not showing all External Variables when the bindings
are initialized:

 Ensure that the Awake method of each attached script ends by calling
“VariableBinder.SendItemToBinder(this);”.

18
 Troubleshooting

3.2.3[4.2.3] Connectivity

 Connection to server failed:

 The server must be launched before the client can connect to it. The
server is launched automatically when the Unity window is opened but
must be relaunched manually using the Launch button in the Unity
window for subsequent connections.

© Famic Technologies inc. 19

A Glossary
DLL

Acronym for dynamic link library. A library that contains data and code to be used by multiple
programs at a time. It may be modularized into separate components and encapsulates its contents
while exposing the necessary functionality for its use.

External Variable

An External Variable is an object representing a value shared between Automation Studio™ and
Unity.

JSON

JSON is a standard text file format that uses a name - value format that is highly human readable.

Script

A script is an asset comparable to a C# class. It makes its connection with the internal workings
of Unity by implementing a class, which is derived from the class MonoBehaviour.

URC

Acronym for UnityRemoteClient, the name of the dynamic link library (dll) supporting
communication between Automation Studio™ and Unity through a TCP connection. This dll
manages the TCP connection from the client side (Automation Studio™).

URS

Acronym for UnityRemoteServer, the name of the dynamic link library (dll) supporting
communication between Automation Studio™ and Unity through a TCP connection. This dll
creates and manages the TCP connection from the server side (Unity).

Variable

Object representing a value of an object in a project, a document, a component, a dynamic

© Famic Technologies inc. B-1

measuring instrument, etc.

B Index
Add Variable in Automation Studio™ 3-12 OnClick LaunchServer 2-3

Architecture Overview 1-1 Server Script 2-2

Awake Method 2-5 Startup Script 3-13

Export Variable Update Method 2-5 Unity Project DIrectory 3-11

Import Variable Update Method 2-6 Unity Ribbon 3-12

Item Script Inheritance 2-4 Variable Association 3-14

© Famic Technologies inc. B-2