Danro-Jump/GUIDES/applied_usage/Unity.md

Специфичные возможности Unity и железа

В разработке проекта Danro Jump используются продвинутые интеграции, не типичные для мобильных или ПК-игр, так как игра предназначена для специализированного оборудования (аркадного автомата).

1. Взаимодействие с внешним оборудованием (COM-порты)

Движок Unity не имеет встроенных средств для общения с внешними платами (кроме геймпадов). Поэтому используется стандартная библиотека .NET System.IO.Ports.

Проблема Потоков (Thread Safety)

Главная проблема при работе с SerialPort — события приема данных происходят в фоновом потоке Windows. Если вы попытаетесь вызвать Debug.Log, изменить UI или заспавнить GameObject прямо из события DataReceived, Unity выдаст ошибку (или тихо упадет), потому что её API не потокобезопасен (not thread-safe).

Решение: Очередь (ConcurrentQueue)

Все данные из фонового потока складываются в потокобезопасную очередь, а главный поток (в методе Update) читает эту очередь и применяет изменения к игре.

using System.IO.Ports;
using System.Collections.Concurrent;
using UnityEngine;

public class ComPortManager : MonoBehaviour
{
    private SerialPort serialPort;
    
    // Потокобезопасная очередь для связи фонового и главного потоков
    private ConcurrentQueue<byte> incomingDataQueue = new ConcurrentQueue<byte>();

    public void StartConnection(string port)
    {
        serialPort = new SerialPort(port, 9600);
        serialPort.DataReceived += OnDataReceived;
        serialPort.Open();
    }

    // ВНИМАНИЕ: Вызывается в фоновом потоке!
    private void OnDataReceived(object sender, SerialDataReceivedEventArgs e)
    {
        int bytesToRead = serialPort.BytesToRead;
        for (int i = 0; i < bytesToRead; i++)
        {
            // Просто складываем байты в очередь, Unity API не трогаем!
            incomingDataQueue.Enqueue((byte)serialPort.ReadByte());
        }
    }

    // ВНИМАНИЕ: Вызывается в главном потоке Unity
    private void Update()
    {
        // Читаем очередь
        while (incomingDataQueue.TryDequeue(out byte data))
        {
            ProcessData(data); // Здесь уже можно менять UI или двигать персонажа
        }
    }
}

2. Захват фокуса Windows (user32.dll)

Аркадный автомат работает без клавиатуры и мыши (для игрока). Если во время игры всплывет уведомление Windows или антивирус, игра потеряет фокус, и аппаратный ввод (или клавиатура) перестанет работать.

Для защиты от этого используется DllImport — прямой вызов нативных библиотек Windows из C#.

using System;
using System.Diagnostics;
using System.Runtime.InteropServices;
using Cysharp.Threading.Tasks;

public class FocusEnforcer
{
    // Импорт системной функции WinAPI
    [DllImport("user32.dll")]
    private static extern bool SetForegroundWindow(IntPtr hWnd);

    public void EnforceFocus()
    {
        // Получаем дескриптор (Handle) окна нашей игры
        Process currentProcess = Process.GetCurrentProcess();
        IntPtr mainWindowHandle = currentProcess.MainWindowHandle;

        if (mainWindowHandle != IntPtr.Zero)
        {
            // Говорим Windows "Сделай это окно главным и активным!"
            SetForegroundWindow(mainWindowHandle);
        }
    }
}

3. Object Pooling (Пул объектов)

Для аркадной игры с постоянным движением (прыжки, платформы, враги) критически важно избегать вызовов Instantiate и Destroy во время геймплея. Это вызывает "сборку мусора" (Garbage Collection) и фризы на пару кадров.

Вместо уничтожения объектов, их нужно "выключать" и возвращать в пул, а когда нужен новый — доставать из пула и включать.

В Unity есть встроенный класс UnityEngine.Pool.ObjectPool<T> (начиная с Unity 2021).

using UnityEngine;
using UnityEngine.Pool;

public class PlatformSpawner : MonoBehaviour
{
    public GameObject platformPrefab;
    private ObjectPool<GameObject> platformPool;

    private void Awake()
    {
        platformPool = new ObjectPool<GameObject>(
            createFunc: () => Instantiate(platformPrefab), // Как создать новый
            actionOnGet: (obj) => obj.SetActive(true),     // Как достать из пула
            actionOnRelease: (obj) => obj.SetActive(false),// Как вернуть в пул
            actionOnDestroy: (obj) => Destroy(obj),        // Как уничтожить, если пул переполнен
            defaultCapacity: 20,
            maxSize: 100
        );
    }

    public void SpawnPlatform(Vector3 position)
    {
        // Берем готовую платформу из пула, не вызывая Instantiate!
        GameObject platform = platformPool.Get();
        platform.transform.position = position;
    }

    public void ReturnPlatform(GameObject platform)
    {
        // Возвращаем в пул (она выключится)
        platformPool.Release(platform);
    }
}