|
|
| (9 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| ==Synopsis== | | ==Synopsis== |
| UnityBCI2000 is a tool for integration of Unity applications with BCI2000. | | UnityBCI2000 is an extension for the Unity game/3D application development platform that enables control of and communication with the BCI2000 brain-computer interface research platform. It consists of a .NET library for communication with the BCI2000 operator and a Unity package which provides integration with Unity itself. |
|
| |
|
| ==Tutorial== | | ==Prerequisites== |
| For information on how to use Unity itself, see the Unity [https://docs.unity3d.com/Manual/index.html manual]. This tutorial assumes knowledge of how to use Unity. It is recommended to know how GameObjects and Components work.
| | Alongside UnityBCI2000, install Unity per the instructions at [https://unity.com/download the Unity website], and the [[Programming_Howto:Building_and_Customizing_BCI2000|BCI2000 setup tutorial]]. |
| More in-depth detail on how UnityBCI2000 works is provided in the README.md file.
| |
|
| |
|
| | ==Adding UnityBCI2000 to a Unity Project== |
| | Download the latest release of UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. Place the <code>UnityBCI2000.cs</code> and <code>BCI2000RemoteNETStandard.dll</code> files in the <code>Assets</code> folder of the Unity project. |
|
| |
|
| | Add the <code>UnityBCI2000.cs</code> script to a Unity object as a component. |
|
| |
|
| First, download UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. As of now, UnityBCI2000 is not a full Unity package, but it works the same. Place the C# files from the Runtime folder, as well as BCI2000RemoteNET.dll, within the Assets directory of your Unity project.
| | For a comprehensive tutorial of integrating BCI2000 with a Unity project, see [[User Tutorial:UnityBCI2000]]. |
|
| |
|
| Create an empty GameObject and add the script UnityBCI2000 as a Component. This will serve as the central connection to the BCI2000 Operator. As of now, it is not possible to use multiple scenes with one BCI2000 connection.
| | For a minimal tutorial on using BCI2000 as a logging service for Unity, see [[User Tutorial:UnityBCI2000 Barebones]]. |
|
| |
|
| 1. Add a UnityBCI2000.cs to the GameObject as a Script Component.
| |
|
| |
|
| 2.Specify the path to the operator using the Operator Path field, as well as the names of the modules to start up alongside it.
| |
|
| |
|
| If you have an instance of the operator already running, specify the IP and port it is listening on using the Telnet Ip and Telnet Port fields instead.
| | ==Documentation== |
| | | [https://bci2000.org/BCI2000Unity/classUnityBCI2000.html Interface documentation] |
| You can also set a custom log file location, as well as tell the program to log sent states and received prompts. '''NOTE: There is a known issue with writing to the log file, this is remedied by changing the name of the file to write to. This is an issue with BCI2000RemoteNET, and will be fixed in upcoming updates.'''
| |
| | |
| 3. Now, add a Script component of the script BCI2000StateSender to the object which you want to take data from.
| |
| | |
| 4. Drag the BCI2000 GameObject from step 1 into the UnityBCI2000Object field of the BCI2000StateSender.
| |
| | |
| BCI2000StateSender comes with some predefined states to send, as well as values to scale them by. These are the global and screen coordinates, as well as whether the object is on screen.
| |
| | |
| ===Adding Custom Variables=== | |
| Due to the way Unity works, adding custom variables must be done from a custom script, unique to each GameObject, if the GameObjects are not identical. Unfortunately, this means that some knowledge of C# programming is required, but templates for a CustomVariableSupplier script are provided within the README.md file.
| |
| | |
| There are two types of custom variables: custom send variables, which set a state in BCI2000 to some value, and custom get variables, which retrieve the value of a state variable from BCI2000.
| |
| | |
| Custom send variables contain the name of the state to write to, a Func<int> delegate(a piece of code represented by a method or lambda expression which returns the value to send to BCI2000), a scale factor to scale the variable by, in order to avoid truncation due to the fact that BCI2000 state variables are only unsigned integers, and a type.
| |
| Types are defined by the enum UnityBCI2000.StateType, which currently holds 5 values, which are signed integers of bit widths 16 and 32, as well as boolean, which is an unsigned integer of bit width 1. Signed numbers will be represented in BCI2000 by two state variables: The magnitude of the number and its sign, which is 0 for positive and 1 for negative.
| |
| | |
| Custom get variables contain the name of the state to read from, as well as an Action<int> delegate(a piece of code which takes an int as a parameter), which will receive the value from BCI2000.
| |
| For reference on delegates see the [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/delegates/ C# Programming Guide].
| |
| Note: UnityBCI2000 uses reflection in order to reduce the amount of boilerplate code needed to implement a custom state variable, as well as simplify the process of adding and indexing of custom state variables.
| |
| | |
| Template for adding custom variables:
| |
| | |
| <tt>
| |
| public class <ClassName> : CustomVariableBase
| |
| {
| |
| public override void AddCustomVariables()
| |
| {
| |
| customVariables.Add(new CustomSendVariable( //Copy this for more send variables
| |
| "[Name]",
| |
| new Func<float>(() => [Code which returns variable to send]),
| |
| [Scale],
| |
| UnityBCI2000.StateType.[Type]
| |
| ));
| |
|
| |
| customVariables.Add(new CustomGetVariable( //Copy this for more get variables
| |
| "[Name]",
| |
| new Action<int> ((int i) => [Code which uses i])
| |
| ));
| |
| | |
| }
| |
| }
| |
| </tt>
| |
| | |
| Example of a custom variable provider script:
| |
| | |
| <tt>
| |
| public class CustomVariableSupplier1 : CustomVariableBase
| |
| {
| |
| public override void AddCustomVariables()
| |
| {
| |
| customVariables.Add(new CustomSendVariable(
| |
| "Custom variable 1",
| |
| new Func<float>(() => {return 65 / 5;}),
| |
| 100,
| |
| UnityBCI2000.StateType.SignedInt16
| |
| ));
| |
| | |
| customVariables.Add(new CustomSendVariable(
| |
| "Custom variable 2: Frame count",
| |
| new Func<float>(() => Time.frameCount),
| |
| 1,
| |
| UnityBCI2000.StateType.UnsignedInt32
| |
| ));
| |
| | |
| customVariables.Add(new CustomGetVariable(
| |
| "StateName",
| |
| new Action<int> ((int i) => {score = i})
| |
| ));
| |
| }
| |
| }
| |
| </tt>
| |
| | |
| | |
| 1. Add a new C# script to the object which you want to take data from.
| |
| | |
| 2. Edit the script to change the inherited class to be CustomVariableBase instead of MonoBehavior.
| |
| | |
| 3. Implement the AddCustomVariables method, and have it add Custom Variables to the customVariables List, by calling customVariables.Add.
| |
| | |
| 4. Drag this new script into the Custom Variable Supplier field of the BCI2000StateSender Component.
| |
Synopsis
UnityBCI2000 is an extension for the Unity game/3D application development platform that enables control of and communication with the BCI2000 brain-computer interface research platform. It consists of a .NET library for communication with the BCI2000 operator and a Unity package which provides integration with Unity itself.
Prerequisites
Alongside UnityBCI2000, install Unity per the instructions at the Unity website, and the BCI2000 setup tutorial.
Adding UnityBCI2000 to a Unity Project
Download the latest release of UnityBCI2000 from GitHub. Place the UnityBCI2000.cs and BCI2000RemoteNETStandard.dll files in the Assets folder of the Unity project.
Add the UnityBCI2000.cs script to a Unity object as a component.
For a comprehensive tutorial of integrating BCI2000 with a Unity project, see User Tutorial:UnityBCI2000.
For a minimal tutorial on using BCI2000 as a logging service for Unity, see User Tutorial:UnityBCI2000 Barebones.
Documentation
Interface documentation