深湾创新
Unity SDK

Unity SDK 集成指南

SDK接入示意图

SDK接入示意图

系统要求

Unity版本:Unity 2020.3 LTS 及以上

平台支持:Windows, macOS, Android, iOS

脚本后端:Mono 或 IL2CPP

API兼容性:.NET Standard 2.1

依赖项:Newtonsoft.Json, Unity Bluetooth Plugin

SDK集成

1. Unity Package Manager安装

在Unity编辑器中,打开Package Manager,添加Git URL:

https://github.com/shenwan/unity-brainwave-sdk.git

2. 手动导入UnityPackage

下载SDK包,在Unity中导入:

Assets → Import Package → Custom Package
选择 ShenWan-BrainwaveSDK-Unity.unitypackage

3. 配置权限(Android)

在AndroidManifest.xml中添加蓝牙权限:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

C# 基本使用

1. 初始化SDK

using ShenWan.BrainwaveSDK;
using UnityEngine;
using System.Collections;

public class BrainwaveManager : MonoBehaviour
{
    [Header("SDK配置")]
    public bool autoConnect = true;
    public float dataUpdateInterval = 0.1f;
    
    private BrainwaveSDK sdk;
    private DeviceManager deviceManager;
    private DataManager dataManager;
    
    // 事件
    public System.Action<BrainwaveDevice> OnDeviceConnected;
    public System.Action OnDeviceDisconnected;
    public System.Action<ProcessedData> OnDataReceived;
    
    void Start()
    {
        InitializeSDK();
    }
    
    private void InitializeSDK()
    {
        // 初始化SDK
        sdk = BrainwaveSDK.Instance;
        sdk.Initialize();
        
        // 获取管理器
        deviceManager = sdk.DeviceManager;
        dataManager = sdk.DataManager;
        
        // 注册事件
        RegisterEvents();
        
        // 自动连接
        if (autoConnect)
        {
            StartCoroutine(AutoConnectRoutine());
        }
    }
}

2. 设备连接和管理

private void RegisterEvents()
{
    deviceManager.OnDeviceDiscovered += OnDeviceDiscovered;
    deviceManager.OnDeviceConnected += OnDeviceConnectedHandler;
    deviceManager.OnDeviceDisconnected += OnDeviceDisconnectedHandler;
    
    dataManager.OnProcessedDataReceived += OnProcessedDataReceived;
}

private IEnumerator AutoConnectRoutine()
{
    Debug.Log("开始扫描脑电设备...");
    
    yield return StartCoroutine(ScanForDevices());
    
    if (deviceManager.DiscoveredDevices.Count > 0)
    {
        var device = deviceManager.DiscoveredDevices[0];
        yield return StartCoroutine(ConnectToDevice(device));
    }
    else
    {
        Debug.LogWarning("未发现可用设备");
    }
}

public IEnumerator ScanForDevices()
{
    yield return deviceManager.StartScanAsync();
    
    // 等待扫描完成
    float timeout = 10f;
    while (deviceManager.IsScanning && timeout > 0)
    {
        yield return new WaitForSeconds(0.1f);
        timeout -= 0.1f;
    }
}

public IEnumerator ConnectToDevice(BrainwaveDevice device)
{
    Debug.Log($"连接设备: {device.Name}");
    
    yield return deviceManager.ConnectAsync(device);
    
    if (deviceManager.IsConnected)
    {
        Debug.Log("设备连接成功");
        StartDataCollection();
    }
    else
    {
        Debug.LogError("设备连接失败");
    }
}

private void OnDeviceConnectedHandler(BrainwaveDevice device)
{
    Debug.Log($"设备已连接: {device.Name}");
    OnDeviceConnected?.Invoke(device);
}

private void OnDeviceDisconnectedHandler()
{
    Debug.Log("设备已断开连接");
    OnDeviceDisconnected?.Invoke();
}

3. 数据采集和处理

private void StartDataCollection()
{
    var config = new DataCollectionConfig
    {
        SamplingRate = 250,
        EnableRealTimeProcessing = true,
        ProcessingInterval = dataUpdateInterval,
        Algorithms = new string[] { "attention", "relaxation", "stress" }
    };
    
    dataManager.StartCollection(config);
    Debug.Log("开始数据采集");
}

private void OnProcessedDataReceived(ProcessedData data)
{
    // 在主线程中处理数据
    UnityMainThreadDispatcher.Instance().Enqueue(() =>
    {
        ProcessBrainwaveData(data);
        OnDataReceived?.Invoke(data);
    });
}

private void ProcessBrainwaveData(ProcessedData data)
{
    // 更新游戏状态
    UpdateGameState(data);
    
    // 触发游戏事件
    TriggerGameEvents(data);
    
    // 记录数据
    LogDataToFile(data);
}

private void UpdateGameState(ProcessedData data)
{
    // 根据专注度调整游戏难度
    if (data.Attention > 0.8f)
    {
        // 高专注度 - 增加难度
        GameManager.Instance.IncreaseDifficulty();
    }
    else if (data.Attention < 0.3f)
    {
        // 低专注度 - 降低难度
        GameManager.Instance.DecreaseDifficulty();
    }
    
    // 根据放松度调整音效
    AudioManager.Instance.SetRelaxationLevel(data.Relaxation);
    
    // 根据压力值调整视觉效果
    VisualEffectManager.Instance.SetStressLevel(data.Stress);
}

游戏集成示例

1. 专注度训练游戏

public class AttentionTrainingGame : MonoBehaviour
{
    [Header("游戏配置")]
    public float targetAttention = 0.7f;
    public float toleranceRange = 0.1f;
    
    [Header("UI组件")]
    public Slider attentionSlider;
    public Text scoreText;
    public ParticleSystem successEffect;
    
    private float currentScore = 0;
    private bool isTraining = false;
    
    void Start()
    {
        // 订阅脑电数据事件
        BrainwaveManager.Instance.OnDataReceived += OnBrainwaveDataReceived;
    }
    
    private void OnBrainwaveDataReceived(ProcessedData data)
    {
        if (!isTraining) return;
        
        // 更新专注度显示
        attentionSlider.value = data.Attention;
        
        // 检查是否达到目标专注度
        if (Mathf.Abs(data.Attention - targetAttention) <= toleranceRange)
        {
            // 专注度达标,增加分数
            currentScore += Time.deltaTime * 10;
            successEffect.Play();
        }
        else
        {
            // 专注度不达标,减少分数
            currentScore = Mathf.Max(0, currentScore - Time.deltaTime * 5);
        }
        
        // 更新分数显示
        scoreText.text = $"Score: {currentScore:F0}";
    }
    
    public void StartTraining()
    {
        isTraining = true;
        currentScore = 0;
        Debug.Log("开始专注度训练");
    }
    
    public void StopTraining()
    {
        isTraining = false;
        Debug.Log($"训练结束,最终分数: {currentScore:F0}");
    }
}

2. 冥想引导应用

public class MeditationGuide : MonoBehaviour
{
    [Header("冥想配置")]
    public AudioClip[] guidanceAudios;
    public float sessionDuration = 600f; // 10分钟
    
    [Header("反馈设置")]
    public Light ambientLight;
    public AudioSource backgroundMusic;
    
    private float sessionTimer;
    private bool isMeditating = false;
    private ProcessedData lastData;
    
    void Start()
    {
        BrainwaveManager.Instance.OnDataReceived += OnBrainwaveDataReceived;
    }
    
    private void OnBrainwaveDataReceived(ProcessedData data)
    {
        lastData = data;
        
        if (isMeditating)
        {
            UpdateMeditationFeedback(data);
        }
    }
    
    private void UpdateMeditationFeedback(ProcessedData data)
    {
        // 根据放松度调整环境光
        Color lightColor = Color.Lerp(Color.red, Color.blue, data.Relaxation);
        ambientLight.color = lightColor;
        
        // 根据专注度调整音乐音量
        float musicVolume = Mathf.Lerp(0.3f, 0.8f, data.Attention);
        backgroundMusic.volume = musicVolume;
        
        // 记录冥想数据
        MeditationDataLogger.Instance.LogData(data, sessionTimer);
    }
    
    public void StartMeditation()
    {
        isMeditating = true;
        sessionTimer = 0;
        
        // 播放引导音频
        AudioSource.PlayClipAtPoint(guidanceAudios[0], Camera.main.transform.position);
        
        StartCoroutine(MeditationSession());
    }
    
    private IEnumerator MeditationSession()
    {
        while (sessionTimer < sessionDuration && isMeditating)
        {
            sessionTimer += Time.deltaTime;
            
            // 定期播放引导音频
            if (sessionTimer % 120f < Time.deltaTime) // 每2分钟
            {
                int audioIndex = Mathf.FloorToInt(sessionTimer / 120f) % guidanceAudios.Length;
                AudioSource.PlayClipAtPoint(guidanceAudios[audioIndex], Camera.main.transform.position);
            }
            
            yield return null;
        }
        
        EndMeditation();
    }
    
    private void EndMeditation()
    {
        isMeditating = false;
        
        // 生成冥想报告
        var report = MeditationDataLogger.Instance.GenerateReport();
        ShowMeditationReport(report);
    }
}

高级功能

1. 自定义数据处理

public class CustomBrainwaveProcessor : MonoBehaviour
{
    [Header("处理参数")]
    public int windowSize = 256;
    public float updateRate = 10f;
    
    private Queue<float[]> dataBuffer;
    private FFTProcessor fftProcessor;
    
    void Start()
    {
        dataBuffer = new Queue<float[]>();
        fftProcessor = new FFTProcessor(windowSize);
        
        // 订阅原始数据
        BrainwaveManager.Instance.dataManager.OnRawDataReceived += OnRawDataReceived;
        
        // 启动自定义处理协程
        StartCoroutine(ProcessDataRoutine());
    }
    
    private void OnRawDataReceived(float[] rawData)
    {
        dataBuffer.Enqueue(rawData);
        
        // 保持缓冲区大小
        while (dataBuffer.Count > 10)
        {
            dataBuffer.Dequeue();
        }
    }
    
    private IEnumerator ProcessDataRoutine()
    {
        while (true)
        {
            if (dataBuffer.Count >= windowSize / 64) // 足够的数据
            {
                var processedData = ProcessBufferedData();
                
                // 触发自定义事件
                OnCustomDataProcessed?.Invoke(processedData);
            }
            
            yield return new WaitForSeconds(1f / updateRate);
        }
    }
    
    private CustomProcessedData ProcessBufferedData()
    {
        // 合并缓冲区数据
        var combinedData = CombineBufferData();
        
        // 执行FFT
        var spectrum = fftProcessor.ProcessFFT(combinedData);
        
        // 计算自定义指标
        var customData = new CustomProcessedData
        {
            AlphaPower = CalculateAlphaPower(spectrum),
            BetaPower = CalculateBetaPower(spectrum),
            ThetaPower = CalculateThetaPower(spectrum),
            Coherence = CalculateCoherence(spectrum),
            Asymmetry = CalculateAsymmetry(spectrum)
        };
        
        return customData;
    }
    
    public System.Action<CustomProcessedData> OnCustomDataProcessed;
}

2. 多平台部署

public class PlatformSpecificManager : MonoBehaviour
{
    void Start()
    {
        ConfigureForPlatform();
    }
    
    private void ConfigureForPlatform()
    {
#if UNITY_ANDROID
        ConfigureAndroid();
#elif UNITY_IOS
        ConfigureIOS();
#elif UNITY_STANDALONE_WIN
        ConfigureWindows();
#elif UNITY_STANDALONE_OSX
        ConfigureMacOS();
#endif
    }
    
    private void ConfigureAndroid()
    {
        // Android特定配置
        var config = new AndroidConfig
        {
            UseBluetoothLE = true,
            RequestLocationPermission = true,
            ScanTimeout = 30f
        };
        
        BrainwaveSDK.Instance.SetPlatformConfig(config);
    }
    
    private void ConfigureIOS()
    {
        // iOS特定配置
        var config = new IOSConfig
        {
            BackgroundMode = true,
            CoreBluetoothUsage = "This app uses Bluetooth to connect to brainwave devices"
        };
        
        BrainwaveSDK.Instance.SetPlatformConfig(config);
    }
}