Connecting server and clients

Netcode for Entities 1.5.0v

https://docs.unity3d.com/Packages/com.unity.netcode@1.5/manual/creating-multiplayer-gameplay.html

서버와 클라이언트 연결

https://docs.unity3d.com/Packages/com.unity.netcode@1.5/manual/network-connection.html

Netcode for Entities는 연결을 관리하기 위해 Unity Transport 패키지를 사용하며, 각 연결을 하나의 엔티티로 저장합니다.

이 엔티티는 NetworkStreamConnection 컴포넌트를 가지며, 연결에 사용된 Transport 핸들을 포함합니다.

연결이 종료되면(서버가 유저 연결을 끊거나 클라이언트가 요청한 경우) 이 엔티티는 삭제됩니다.

명령 수신 대상 설정

[AutoCommandTarget feature]를 사용하지 않거나 더 세밀한 제어가 필요한 경우, CommandTarget을 설정해야 합니다.

이 설정은 클라이언트에서 받은 명령을 저장할 엔티티를 지정합니다.

이 엔티티 참조를 최신 상태로 유지하는 것은 게임 개발자의 책임입니다.

게임 상태 진입

게임은 NetworkStreamInGame 컴포넌트를 연결 엔티티에 수동으로 추가해야 합니다. 이 작업은 자동으로 이루어지지 않습니다.

이 컴포넌트가 추가되기 전에는 클라이언트가 명령을 전송하지 않으며, 서버도 스냅샷을 전송하지 않습니다.

연결 해제 요청

연결을 해제하려면 해당 엔티티에 NetworkStreamRequestDisconnect 컴포넌트를 추가하세요.

Transport 드라이버를 통한 직접적인 연결 해제는 지원되지 않습니다.

수신 버퍼 (Incoming Buffers)

각 연결은 최대 3개의 수신 버퍼를 가질 수 있습니다:

• 명령: IncomingRpcDataStreamBuffer
• RPC: IncomingCommandDataStreamBuffer
• 스냅샷 (클라이언트 전용): IncomingSnapshotDataStreamBuffer

서버에서 클라이언트로 스냅샷이 전송되면 버퍼에 저장되고 나중에 GhostReceiveSystem에 의해 처리됩니다.

RPC 및 명령도 동일한 방식으로 NetworkStreamReceiveSystem이 수집하고, 이후 각각의 시스템이 처리합니다.

서버는 IncomingSnapshotDataStreamBuffer를 가지지 않습니다.

송신 버퍼 (Outgoing Buffers)

각 연결은 최대 2개의 송신 버퍼를 가질 수 있습니다:

• 명령 (클라이언트 전용): OutgoingRpcDataStreamBuffer
• RPC: OutgoingRpcDataStreamBuffer

생성된 명령은 먼저 송신 버퍼에 저장되고, 클라이언트가 매 틱마다 이 버퍼를 전송합니다.

RPC도 마찬가지로 해당 송신 시스템이 버퍼에 인코딩하고, RpcSystem이 이를 묶어 MTU 단위로 전송합니다.

연결 흐름 (Connection flow)

Netcode는 게임 시작 시 자동으로 서버 또는 클라이언트 연결을 설정하지 않습니다.

기본적으로 ClientServerBootstrap는 클라이언트와 서버 월드만 생성합니다.

연결 채널을 여는 방식은 개발자가 결정합니다.

선택 가능한 방법:

• 1⃣ NetworkStreamDriver를 사용하여 직접 Connect 또는 Listen 호출
• 2⃣ AutoConnectPort 및 DefaultConnectAddress 설정
• NetworkStreamRequestConnect 및 NetworkStreamRequestListen 요청 엔티티 생성

주의

연결 중에는 반드시 Application.runInBackground = true로 설정해야 하며, 그렇지 않으면 포커스를 잃었을 때 연결이 끊길 수 있습니다.

1⃣ 수동 연결 / 리스닝 (Manually listen or connect )

NetworkStreamDriver 싱글톤을 사용해 Connect 또는 Listen 메서드를 호출합니다.

코드 예시는 DOTS samples repository 참고

        public void StartClientServer(string sceneName)
        {
            Debug.Log($"[StartClientServer] Called with '{sceneName}'.");
            if (ClientServerBootstrap.RequestedPlayType != ClientServerBootstrap.PlayType.ClientAndServer)
            {
                Debug.LogError($"Creating client/server worlds is not allowed if playmode is set to {ClientServerBootstrap.RequestedPlayType}");
                return;
            }

            var server = ClientServerBootstrap.CreateServerWorld("ServerWorld");
            var client = ClientServerBootstrap.CreateClientWorld("ClientWorld");

            SceneManager.LoadScene("FrontendHUD");

            //Destroy the local simulation world to avoid the game scene to be loaded into it
            //This prevent rendering (rendering from multiple world with presentation is not greatly supported)
            //and other issues.
            DestroyLocalSimulationWorld();
            if (World.DefaultGameObjectInjectionWorld == null)
                World.DefaultGameObjectInjectionWorld = server;
            SceneManager.LoadSceneAsync(sceneName, LoadSceneMode.Additive);

            var port = ParsePortOrDefault(Port.text);

            NetworkEndpoint ep = NetworkEndpoint.AnyIpv4.WithPort(port);
            {
                using var drvQuery = server.EntityManager.CreateEntityQuery(ComponentType.ReadWrite<NetworkStreamDriver>());
                drvQuery.GetSingletonRW<NetworkStreamDriver>().ValueRW.RequireConnectionApproval = sceneName.Contains("ConnectionApproval", StringComparison.OrdinalIgnoreCase);
                drvQuery.GetSingletonRW<NetworkStreamDriver>().ValueRW.Listen(ep);
            }

            ep = NetworkEndpoint.LoopbackIpv4.WithPort(port);
            {
                using var drvQuery = client.EntityManager.CreateEntityQuery(ComponentType.ReadWrite<NetworkStreamDriver>());
                drvQuery.GetSingletonRW<NetworkStreamDriver>().ValueRW.Connect(client.EntityManager, ep);
            }
        }

2⃣ AutoConnectPort 사용 (Using the AutoConnectPort)

ClientServerBootstrap AutoConnectPort필드에는 서버와 클라이언트가 처음 설정될 때 각각 자동으로 수신하고 연결하도록 지시하는 데 사용할 수 있는 두 가지 특수 속성이 포함되어 있습니다.

• DefaultConnectAddress
• DefaultListenAddress

public class AutoConnectBootstrap : ClientServerBootstrap
{
    public override bool Initialize(string defaultWorldName)
    {
        AutoConnectPort = 7979;
        CreateDefaultClientServerWorlds();
        return true;
    }
}

서버는 와일드카드 주소(DefaultListenAddress:AutoConnectPort)에서 리슨을 시작합니다.

DefaultConnectAddress는 기본적으로 NetworkEndpoint.AnyIpv4로 설정되어 있습니다.

클라이언트는 서버 주소(DefaultConnectAddress:AutoConnectPort)로 연결을 시작하며, 이 DefaultConnectAddress는 기본적으로 NetworkEndpoint.Loopback으로 설정되어 있습니다.

참고:

에디터에서는 PlayMode 도구를 사용해 AutoConnectAddress와 AutoConnectPort 값을 오버라이드할 수 있습니다.

그러나 AutoConnectPort를 0으로 설정한 경우에는 PlayMode 도구의 오버라이드 기능이 작동하지 않으며, 이 경우 수동으로 연결을 트리거해야 합니다.

3⃣ NetworkStreamRequest로 연결 흐름 제어

NetworkStreamDriver에서 직접 메서드를 호출하는 대신, 다음과 같은 싱글톤을 생성하여 연결 흐름을 제어할 수 있습니다:

• NetworkStreamRequestConnect singleton : 원하는 서버 주소/포트로 연결을 요청할 때 사용합니다.
• NetworkStreamRequestListen singleton : 서버가 원하는 주소/포트에서 리슨을 시작하도록 요청할 때 사용합니다.

// 클라이언트 월드에서, NetworkStreamRequestConnect가 있는 새 엔티티 생성
// 이 엔티티는 이후 NetworkStreamReceiveSystem에 의해 처리됩니다.
var connectRequest = clientWorld.EntityManager.CreateEntity(typeof(NetworkStreamRequestConnect));
EntityManager.SetComponentData(connectRequest, new NetworkStreamRequestConnect { Endpoint = serverEndPoint });

// 서버 월드에서, NetworkStreamRequestListen이 있는 새 엔티티 생성
// 이 엔티티도 마찬가지로 NetworkStreamReceiveSystem에 의해 처리됩니다.
var listenRequest = serverWorld.EntityManager.CreateEntity(typeof(NetworkStreamRequestListen));
EntityManager.SetComponentData(listenRequest, new NetworkStreamRequestListen { Endpoint = serverEndPoint });

이러한 요청은 런타임에 NetworkStreamReceiveSystem에 의해 소비되어 실제 연결 동작을 수행합니다.

참고 :

실행 중 오류가 발생하면 PlayMode Tools 창을 열고 다시 Play Mode로 진입해 보세요.

만약 월드가 이미 존재한다면, 부트스트랩 코드(위 설명 참조)에 의해 자동으로 월드가 생성되고 있을 가능성이 큽니다.

서버가 이미 리슨 중이거나 클라이언트가 이미 연결 중이라면, 자동 연결 기능이 이미 활성화되어 있는 것입니다.

이 경우 수동 연결 방식을 사용하려면 부트스트랩 코드에서 자동 연결을 비활성화해야 합니다.

4⃣ Network simulator

Unity Transport는 SimulatorUtility를 제공합니다.

이 도구는 Netcode for Entities 패키지에 포함되어 있으며, 에디터 내에서 다음 경로를 통해 접근하고 설정할 수 있습니다:

Multiplayer > PlayMode Tools

실제 네트워크 상황을 보다 현실적으로 반영하기 위해, 시뮬레이터를 활성화한 상태로 자주 게임플레이를 테스트해보는 것이 좋습니다.

클라이언트 연결 이벤트 수신

NetworkStreamDriver 싱글톤을 통해 제공되는 ConnectionEventsForTick (형식: NativeArray<NetCodeConnectionEvent>.ReadOnly) 컬렉션을 사용하여,

클라이언트 및 서버에서 클라이언트 연결 이벤트를 반복(iterate)하면서 반응할 수 있습니다.

이 이벤트는 오직 단일 SimulationSystemGroup 틱 동안만 존재하며, 각각 NetworkStreamConnectSystem과 NetworkStreamListenSystem에서 초기화됩니다.

시스템이 위 시스템들의 job 이후에 실행되면, 같은 틱에서 발생한 이벤트를 수신하게 됩니다.

반면, 그 이전에 컬렉션을 조회하면 이전 틱의 값들을 반복하게 됩니다.

// 예제 시스템
[UpdateAfter(typeof(NetworkReceiveSystemGroup))]
[BurstCompile]
public partial struct NetCodeConnectionEventListener : ISystem
{
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        var connectionEventsForClient = SystemAPI.GetSingleton<NetworkStreamDriver>().ConnectionEventsForTick;
        foreach (var evt in connectionEventsForClient)
        {
            UnityEngine.Debug.Log($"[{state.WorldUnmanaged.Name}] {evt.ToFixedString()}!");
        }
    }
}

주의 :

서버는 고정된 델타 타임으로 실행되기 때문에, SimulationSystemGroup은 각 렌더 프레임마다 0번 이상 실행될 수 있습니다.

따라서 ConnectionEventsForTick은 반드시 SimulationSystemGroup 내에서 실행되는 시스템 안에서만 읽어야 합니다.

예를 들어 InitializationSystemGroup, PresentationSystemGroup, 또는 어떤 MonoBehaviour 메서드 내에서 접근하면 다음과 같은 문제가 발생할 수 있습니다:

b) 시뮬레이션이 이 프레임에서 실행되지 않을 경우, 이벤트를 중복 수신

a) 이전 틱 이벤트를 놓치고 현재 틱만 받음

1⃣ NetCodeConnectionEvents on the client

주의 :

클라이언트는 다른 클라이언트의 이벤트를 수신하지 않습니다. 클라이언트 월드에서 발생한 이벤트는 자신의 클라이언트에 대한 이벤트뿐입니다.

Handshake 및 Approval 단계는 실패할 수 있으며, ClientServerTickRate.HandshakeApprovalTimeoutMS (기본값: 5000ms)의 타임아웃을 가집니다.

2⃣ NetCodeConnectionEvents on the server

주의 :

서버는 바인딩 성공이나 리스닝 시작에 대한 이벤트는 발생시키지 않습니다. 기존 API를 통해 상태를 확인해야 합니다.

Connection approval

서버에서 각 클라이언트 연결에 대해 승인을 요구하도록 설정할 수 있습니다.

연결 승인은 다음과 같은 목적으로 사용됩니다:

• 플레이어 편의성: 화이트리스트 / 블랙리스트, 비밀번호 보호된 서버 등
• 보안 검증: 매치메이킹 응답으로 받은 시크릿 토큰을 사용하여, 매치메이킹된 플레이어만 서버에 입장하도록 제한

연결 승인이 활성화되면 다음과 같은 변경이 발생 :

1. 클라이언트는 Handshake 및 Approval 단계에서만 IApprovalRpcCommand 형식의 RPC를 서버에 전송할 수 있습니다.
2. 모든 클라이언트는 Handshake 상태에서 곧바로 Connected로 넘어가는 것이 아니라 Approval 상태로 이동합니다.
3. 서버는 연결된 각 클라이언트의 엔티티에 ConnectionApproved 컴포넌트를 직접 추가해야만 승인됩니다.
4. NetworkId는 승인 성공 이후에만 할당됩니다. 승인에 실패하면 클라이언트는 연결이 끊어집니다.
5. 승인 과정에는 타임아웃이 존재합니다 (ClientServerTickRate.HandshakeApprovalTimeoutMS 참조, 기본값: 5000ms)

다시 강조하면:

• Handshake 및 Approval 단계 동안, 클라이언트는 여러 개의 RPC 메시지를 보낼 수 있습니다.
• 단, 이들 모두 IApprovalRpcCommand 타입이어야 합니다.
• 이 RPC의 payload에는 인증 토큰, 플레이어 정보 등 클라이언트의 유효성을 검증하기 위한 모든 정보를 담을 수 있습니다.
• 서버는 ConnectionApproved 컴포넌트를 클라이언트의 연결 엔티티에 추가함으로써 연결을 승인합니다. 이후 연결 흐름이 계속 진행됩니다.

NetworkStreamDriver에는 RequireConnectionApproval 필드가 있으며, 클라이언트와 서버 모두에서 true로 설정해야 연결 승인 흐름이 올바르게 작동합니다.

if (isServer)
{
    using var drvQuery = server.EntityManager.CreateEntityQuery(ComponentType.ReadWrite<NetworkStreamDriver>());
    drvQuery.GetSingletonRW<NetworkStreamDriver>().ValueRW.RequireConnectionApproval = true;
    drvQuery.GetSingletonRW<NetworkStreamDriver>().ValueRW.Listen(ep);
}
else
{
    using var drvQuery = client.EntityManager.CreateEntityQuery(ComponentType.ReadWrite<NetworkStreamDriver>());
    drvQuery.GetSingletonRW<NetworkStreamDriver>().ValueRW.RequireConnectionApproval = true;
    drvQuery.GetSingletonRW<NetworkStreamDriver>().ValueRW.Connect(client.EntityManager, ep);
}

연결 승인 처리도 다음과 같이 설정할 수 있습니다 :

// The approval RPC, here it contains a hypothetical payload the server will validate
public struct ApprovalFlow : IApprovalRpcCommand
{
    public FixedString512Bytes Payload;
}

// This is used to indicate we've already sent an approval RPC and don't need to do so again
public struct ApprovalStarted : IComponentData
{
}

[WorldSystemFilter(WorldSystemFilterFlags.ClientSimulation | WorldSystemFilterFlags.ThinClientSimulation)]
public partial struct ClientConnectionApprovalSystem : ISystem
{
    public void OnCreate(ref SystemState state)
    {
        state.RequireForUpdate<RpcCollection>();
    }

    public void OnUpdate(ref SystemState state)
    {
        var ecb = new EntityCommandBuffer(Allocator.Temp);
        // Check connections which have not yet fully connected and send connection approval message
        foreach (var (connection, entity) in SystemAPI.Query<RefRW<NetworkStreamConnection>>().WithNone<NetworkId>().WithNone<ApprovalStarted>().WithEntityAccess())
        {
            var sendApprovalMsg = ecb.CreateEntity();
            ecb.AddComponent(sendApprovalMsg, new ApprovalFlow { Payload = "ABC" });
            ecb.AddComponent<SendRpcCommandRequest>(sendApprovalMsg);

            ecb.AddComponent<ApprovalStarted>(entity);
        }
        ecb.Playback(state.EntityManager);
    }
}

[WorldSystemFilter(WorldSystemFilterFlags.ServerSimulation)]
public partial struct ServerConnectionApprovalSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        var ecb = new EntityCommandBuffer(Allocator.Temp);
        // Check connections which have not yet fully connected and send connection approval message
        foreach (var (receiveRpc, approvalMsg, entity) in SystemAPI.Query<RefRO<ReceiveRpcCommandRequest>,RefRW<ApprovalFlow>>().WithEntityAccess())
        {
            var connectionEntity = receiveRpc.ValueRO.SourceConnection;
            if (approvalMsg.ValueRO.Payload.Equals("ABC"))
            {
                ecb.AddComponent<ConnectionApproved>(connectionEntity);

                // Destroy RPC message
                ecb.DestroyEntity(entity);
            }
            else
            {
                // Failed approval messages should be disconnected
                ecb.AddComponent<NetworkStreamRequestDisconnect>(connectionEntity);
            }
        }
        ecb.Playback(state.EntityManager);
    }
}

연결 확인 Sample 코드

https://discussions.unity.com/t/lobby-relay-and-netcode-for-entities/1538817/8

WorldManager.cs

using System.Diagnostics.CodeAnalysis;
using Unity.Entities;

namespace Managers 
{
    public static class WorldManager 
    {
        private static World _clientWorld, _serverWorld;
		
        [SuppressMessage("ReSharper", "ForeachCanBePartlyConvertedToQueryUsingAnotherGetEnumerator")]
        public static void DestroyLocalSimulationWorld() {
            foreach (var world in World.All) {
                if (world.Flags != WorldFlags.Game) continue;
                world.Dispose();
                break;
            }
        }
		
        public static void RegisterServerWorld(World world) => _serverWorld = world;
        public static void RegisterClientWorld(World world) => _clientWorld = world;

        public static World GetServerWorld() => _serverWorld;
        public static World GetClientWorld() => _clientWorld;
    }
}

RelayServerDataHelper.cs

using System;
using System.Collections.Generic;
using System.Linq;
using Unity.Networking.Transport;
using Unity.Networking.Transport.Relay;
using Unity.Services.Relay.Models;

namespace Extension 
{
    public static class RelayServerDataHelper 
    {
        private static RelayServerData GetRelayData(List<RelayServerEndpoint> endpoints, byte[] allocationIdBytes, byte[] connectionDataBytes, byte[] hostConnectionDataBytes, byte[] keyBytes) 
        {
            
            var endpoint = endpoints.FirstOrDefault(e => e.ConnectionType == "dtls") ?? throw new InvalidOperationException($"Endpoint for connectionType dtls not found");
            
            var server = NetworkEndpoint.Parse(endpoint.Host, (ushort)endpoint.Port);
    
            var allocationId = RelayAllocationId.FromByteArray(allocationIdBytes);
            var connData = RelayConnectionData.FromByteArray(connectionDataBytes);
            var hostData = RelayConnectionData.FromByteArray(hostConnectionDataBytes);
            var key = RelayHMACKey.FromByteArray(keyBytes);

            return new RelayServerData(ref server, 0, ref allocationId, ref connData, ref hostData, ref key, true); 
        }

        public static RelayServerData RelayData(JoinAllocation a) => GetRelayData(a.ServerEndpoints, a.AllocationIdBytes, a.ConnectionData, a.HostConnectionData, a.Key);

        public static RelayServerData RelayData(Allocation a) => GetRelayData(a.ServerEndpoints, a.AllocationIdBytes, a.ConnectionData, a.ConnectionData, a.Key);
    }
}

RelayInitializer.cs

using System;
using System.Collections;
using System.Threading.Tasks;
using Unity.Entities;
using Unity.NetCode;
using Unity.Networking.Transport;
using Unity.Networking.Transport.Relay;
using Unity.Services.Authentication;
using Unity.Services.Core;
using Unity.Services.Relay;
using UnityEngine;
using Extension;

namespace Managers 
{
    public class RelayInitializer : MonoBehaviour 
    {
        private static RelayServerData? _relayServerData, _relayClientData;
        private static Action OnConnectionComplete;
        public static string _joinCode;
    
        // Singleton (without duplicate destroy logic) for access to the class instance from within the static methods
        private static RelayInitializer Instance { get; set; }
        protected void Awake() => Instance = this;
        
        // HOSTING

        public static void StartHost() => Instance.StartCoroutine(InitializeHost());

        private static IEnumerator InitializeHost() 
        {
            var initializeTask = UnityServices.InitializeAsync();
            while (!initializeTask.IsCompleted)
                yield return null;
            if (ProcessTaskFail(initializeTask, nameof(initializeTask)))
                yield break;

            var signInTask = Task.CompletedTask;
            if (!AuthenticationService.Instance.IsSignedIn) {
                signInTask = AuthenticationService.Instance.SignInAnonymouslyAsync();
                while (!signInTask.IsCompleted)
                    yield return null; 
            }
            
            if (ProcessTaskFail(signInTask, nameof(signInTask)))
                yield break;

            var allocationTask = RelayService.Instance.CreateAllocationAsync(5);
            
            while (!allocationTask.IsCompleted)
                yield return null;
            
            if (ProcessTaskFail(allocationTask, nameof(allocationTask)))
                yield break;

            var joinCodeTask = RelayService.Instance.GetJoinCodeAsync(allocationTask.Result.AllocationId);
            
            while (!joinCodeTask.IsCompleted)
                yield return null;
            
            if (ProcessTaskFail(joinCodeTask, nameof(joinCodeTask)))
                yield break;

            _joinCode = joinCodeTask.Result;

            try 
            {
                Debug.Log("Hosting relay data");
                _relayServerData = RelayServerDataHelper.RelayData(allocationTask.Result);
            } catch (Exception e) {
                Debug.LogException(e);
                _relayServerData = null;
                yield break;
            }

            Debug.Log("Success, players may now connect");
            while (_relayServerData == null || (!_relayServerData?.Endpoint.IsValid ?? false))
                yield return null;
                
            yield return JoinUsingCode(_joinCode);
            yield return WaitRelayConnection();
            SetupRelayHostedServerAndConnect();
        }

        private static void SetupRelayHostedServerAndConnect() 
        {
            if (ClientServerBootstrap.RequestedPlayType != ClientServerBootstrap.PlayType.ClientAndServer) 
            {
                UnityEngine.Debug.LogError($"Creating client/server worlds is not allowed if playmode is set to {ClientServerBootstrap.RequestedPlayType}");
                return;
            }

            var relayServerData = _relayServerData.GetValueOrDefault();
            var relayClientData = _relayClientData.GetValueOrDefault();

            var oldConstructor = NetworkStreamReceiveSystem.DriverConstructor;
            NetworkStreamReceiveSystem.DriverConstructor = new RelayDriverConstructor(relayServerData, relayClientData);
            var server = ClientServerBootstrap.CreateServerWorld("ServerWorld");
            WorldManager.RegisterServerWorld(server);
            var client = ClientServerBootstrap.CreateClientWorld("ClientWorld");
            WorldManager.RegisterClientWorld(client);
            NetworkStreamReceiveSystem.DriverConstructor = oldConstructor;

            

            WorldManager.DestroyLocalSimulationWorld();
            World.DefaultGameObjectInjectionWorld ??= server;

            // Load scene here if you want to.
            
            Debug.Log(_joinCode);

            var networkStreamEntity = server.EntityManager.CreateEntity(ComponentType.ReadWrite<NetworkStreamRequestListen>());
            server.EntityManager.SetName(networkStreamEntity, "NetworkStreamRequestListen");
            server.EntityManager.SetComponentData(networkStreamEntity,
                new NetworkStreamRequestListen { Endpoint = NetworkEndpoint.AnyIpv4 });

            networkStreamEntity =
                client.EntityManager.CreateEntity(ComponentType.ReadWrite<NetworkStreamRequestConnect>());
            client.EntityManager.SetName(networkStreamEntity, "NetworkStreamRequestConnect");
            client.EntityManager.SetComponentData(networkStreamEntity,
                new NetworkStreamRequestConnect { Endpoint = relayClientData.Endpoint });
            
            ProcessConnectionComplete();
        }

        // CONNECTING
    
        public static void ConnectByCode(string joinCode) => Instance.StartCoroutine(ProcessCodeConnection(joinCode));
    
        private static IEnumerator ProcessCodeConnection(string joinCode) 
        {
            Instance.StartCoroutine(JoinExternalServer(joinCode));
            yield return WaitRelayConnection();
            ConnectToRelayServer();
        }

        private static IEnumerator WaitRelayConnection() {
            while (_relayClientData == null || (!_relayClientData?.Endpoint.IsValid ?? false))
                yield return null;
        }
        
        private static IEnumerator JoinExternalServer(string joinCode) {
            Debug.Log("Waiting for relay response");
            var setupTask = UnityServices.InitializeAsync();

            while (!setupTask.IsCompleted)
                yield return null;
            
            var signInTask = Task.CompletedTask;
            if (!AuthenticationService.Instance.IsSignedIn) {
                signInTask = AuthenticationService.Instance.SignInAnonymouslyAsync();
                while (!signInTask.IsCompleted)
                    yield return null;
            }
            if (ProcessTaskFail(signInTask, nameof(signInTask)))
                yield break;

            yield return JoinUsingCode(joinCode);
        }

        private static IEnumerator JoinUsingCode(string joinCode) 
        {
            // Send the join request to the Relay service
            var joinTask = RelayService.Instance.JoinAllocationAsync(joinCode);
            while (!joinTask.IsCompleted)
                yield return null;
            
            if (ProcessTaskFail(joinTask, nameof(joinTask)))
                yield break;
            
            // Format the server data, based on desired connectionType
            try {
                _relayClientData = RelayServerDataHelper.RelayData(joinTask.Result);
            } catch (Exception e) 
            {
                Debug.LogException(e);
                _relayClientData = null;
            }

            _joinCode = joinCode;
        }
    
        private static void ConnectToRelayServer() 
        {
            var relayClientData = _relayClientData.GetValueOrDefault();
            
            var oldConstructor = NetworkStreamReceiveSystem.DriverConstructor;
            NetworkStreamReceiveSystem.DriverConstructor = new RelayDriverConstructor(new RelayServerData(), relayClientData);
            var client = ClientServerBootstrap.CreateClientWorld("ClientWorld");
            WorldManager.RegisterClientWorld(client);
            NetworkStreamReceiveSystem.DriverConstructor = oldConstructor;

            WorldManager.DestroyLocalSimulationWorld();
            World.DefaultGameObjectInjectionWorld ??= client;
        
            var networkStreamEntity =
                client.EntityManager.CreateEntity(ComponentType.ReadWrite<NetworkStreamRequestConnect>());
            client.EntityManager.SetName(networkStreamEntity, "NetworkStreamRequestConnect");
            client.EntityManager.SetComponentData(networkStreamEntity,
                new NetworkStreamRequestConnect { Endpoint = relayClientData.Endpoint });
            ProcessConnectionComplete();
        }

        // COMMON
    
        private static bool ProcessTaskFail(Task task, string taskName) {
            if (!task.IsFaulted) return false;
            Debug.LogError($"Task {taskName} failed.");
            Debug.LogException(task.Exception);
            return true;
        }

        public static void SubscribeToConnectionComplete(Action handler) => OnConnectionComplete += handler;

        public static void ProcessConnectionComplete() {
            if (OnConnectionComplete == null)
                return;
            OnConnectionComplete?.Invoke();
            foreach (var handler in OnConnectionComplete?.GetInvocationList()!)
                OnConnectionComplete -= (Action)handler;
        }
    }

    public class RelayDriverConstructor : INetworkStreamDriverConstructor 
    {
        private RelayServerData _relayServerData, _relayClientData;
    
        public RelayDriverConstructor(RelayServerData serverData, RelayServerData clientData) {
            _relayServerData = serverData;
            _relayClientData = clientData;
        }

        public void CreateClientDriver(World world, ref NetworkDriverStore driverStore, NetDebug netDebug) {
            var settings = DefaultDriverBuilder.GetNetworkSettings();
            settings.WithRelayParameters(ref _relayClientData);
            DefaultDriverBuilder.RegisterClientDriver(world, ref driverStore, netDebug, settings);
        }

        public void CreateServerDriver(World world, ref NetworkDriverStore driverStore, NetDebug netDebug) =>
            DefaultDriverBuilder.RegisterServerDriver(world, ref driverStore, netDebug, ref _relayServerData);
    }
}

The post Unity Netcode for Entities – Connecting server and clients appeared first on 어제와 내일의 나 그 사이의 이야기.

Client / Server worlds Setting

Netcode for Entities 1.5.0v

https://docs.unity3d.com/Packages/com.unity.netcode@1.5/manual/set-up-client-server-worlds.html

Netcode for Entities의 네트워킹 모델을 사용하여client 와 server를 설정합니다.

클라이언트 / 서버 World 네트워크 모델

https://docs.unity3d.com/Packages/com.unity.netcode@1.5/manual/client-server-worlds.html

Netcode for Entities는 Client와 Server의 로직을 각각 Client world와 Server world로 분리하여 처리합니다.

월드(World)는 Unity의 ECS(Entity Component System) 개념으로, 엔티티와 시스템을 시스템 그룹(SystemGroup)으로 구성한 단위입니다.

기본적인 Client / Server 월드 외에도, 개발 중에 게임을 테스트할 수 있도록 씬 클라이언트(Thin Client) 기능도 지원합니다.

시스템 생성 및 업데이트 구성

기본적으로, 모든 시스템은 클라이언트/서버 월드의 SimulationSystemGroup에서 생성되고 업데이트됩니다.

하지만 특정 시스템을 클라이언트에만, 또는 서버에만 작동하게 만들고 싶을 때는 다음 두 가지 방법을 사용할 수 있습니다

1⃣ 특정 시스템 그룹에 할당하기

시스템이 속할 시스템 그룹을 지정하면, 그 시스템 그룹이 존재하지 않는 월드에서는 자동으로 필터링됩니다.

[UpdateInGroup(typeof(GhostInputSystemGroup))]
public class MyInputSystem : SystemBase
{
  ...
}

참고:

PresentationSystemGroup에 속한 시스템은 클라이언트 월드에서만 작동합니다.

Server / Thin client worlds에는 이 시스템 그룹이 생성되지 않기 때문입니다.

2⃣ WorldSystemFilter 사용

시스템이 어떤 월드에서 작동할지 더 세부적으로 설정하고 싶다면 WorldSystemFilter 속성을 사용하세요.

// WorldSystemFilterFlags 옵션 
// - LocalSimulation: 오프라인 로컬 시뮬레이션 (Netcode 시스템 없음)
// - ServerSimulation: 서버 시뮬레이션
// - ClientSimulation: 클라이언트 시뮬레이션
// - ThinClientSimulation: 씬 클라이언트
// 속성을 지정하지 않으면, 기본적으로 시스템은 상위 그룹의 필터링 규칙을 따릅니다 (WorldSystemFilterFlags.Default)

[WorldSystemFilter(WorldSystemFilterFlags.ClientSimulation)]
public class MySystem : SystemBase
{
  ...
}

Client / Server worlds with bootstrapping

Netcode for Entities를 프로젝트에 추가하면, 기본 ClientServerBootstrap 클래스가 제공됩니다.

이 클래스는 게임 시작 시 클라이언트 및 서버 월드를 자동 생성합니다

public virtual bool Initialize(string defaultWorldName)
{
    CreateDefaultClientServerWorlds();
    return true;
}

자동 부트스트래핑은 에디터에서 Play 모드 진입 시 매우 유용합니다.

하지만, 실제 게임에서는 메인 메뉴와 같은 전처리 과정이 필요하므로 월드 생성을 지연시키거나 수동 제어할 필요가 있습니다.

예를 들어

• “클라이언트-호스트 서버 실행” → 서버와 클라이언트 모두 생성
• “전용 서버에 접속” → 클라이언트만 생성

0⃣ Bootstrapping 커스터 마이징

기본 ClientServerBootstrap을 상속하여 원하는 방식으로 월드 생성을 제어할 수 있습니다

public class MyGameSpecificBootstrap : ClientServerBootstrap
{
    public override bool Initialize(string defaultWorldName)
    {
        // Netcode 없이 로컬 시뮬레이션 월드만 생성
        CreateLocalWorld(defaultWorldName);
        return true;
    }
}

버튼 클릭 등의 타이밍에 다음을 호출하여 월드 생성:

var clientWorld = ClientServerBootstrap.CreateClientWorld();
var serverWorld = ClientServerBootstrap.CreateServerWorld();

AutomaticThinClientWorldsUtility.NumThinClientsRequested = 10;
AutomaticThinClientWorldsUtility.BootstrapThinClientWorlds();

ClientServerBootstrap.CreateDefaultClientServerWorlds();

Netcode Sample https://github.com/Unity-Technologies/EntityComponentSystemSamples/blob/master/NetcodeSamples/README.md

Client / Server 업데이트 주기

Netcode for Entities를 사용할 때, 서버는 항상 Fixed Timestep으로 업데이트됩니다.

이는 클라이언트 예측을 위한 기본적인 결정론 수준을 보장하고(엄격한 결정론은 아니지만), 물리 시스템의 안정성과 프레임 레이트 독립성을 보장하기 위함입니다.

또한 이 패키지는 프레임당 최대 Fixed Step 반복 횟수를 제한하여 서버가 단일 프레임을 시뮬레이션하는 데 몇 초가 걸리는 상태에 빠지지 않도록 합니다.

중요한 점은 서버의 고정 업데이트가 표준 Unity 업데이트 빈도 또 Unity 물리 시스템의 Fixed Timestep를 사용하지 않는다는 것입니다.

대신 자체적인 ClientServerTickRate.SimulationTickRate 를 사용합니다. – 고정된 틱(tick) 간격

(이것은 Unity.Physics가 사용 중이라면 정수 배수여야 합니다. ClientServerTickRate.PredictedFixedStepSimulationTickRatio를 참조하세요)

그러나 클라이언트는 동적 타임스텝으로 업데이트됩니다.

예측 코드만 예외로, 이는 항상 서버와 동일한 고정 타임스텝으로 실행되어 두 시뮬레이션 간의 결정론적 관계를 유지하려고 합니다.

전체 틱과 동기화되지 않은 리프레시 레이트에 대한 예측 처리 방법을 이해하려면 부분 틱을 참조하세요.

설정 예시:

https://docs.unity3d.com/Packages/com.unity.netcode@1.5/api/Unity.NetCode.ClientServerTickRate.html

class MyCustomClientServerBootstrap : ClientServerBootstrap
{
   override public void Initialize(string defaultWorld)
   {
       base.Initialise(defaultWorld);
       var customTickRate = new ClientServerTickRate();
       //run at 30hz
       customTickRate.simulationTickRate = 30;
       customTickRate.ResolveDefault();
       foreach(var world in World.All)
       {
           if(world.IsServer())
           {
              // 이 경우 서버에서만 생성되지만 클라이언트 세계에서도 동일한 작업을 수행할 수 있습니다
              var tickRateEntity = world.EntityManager.CreateSingleton(new ClientServerTickRate
              {
                  SimulationTickRate = 30;
              });
           }
       }
   }
}


// SimulationTickRate = 초당 몇 번의 시뮬레이션 틱을 실행할지 설정합니다. 기본값은 초당 60 틱입니다.
// NetworkTickRate = 서버가 클라이언트에게 스냅샷(snapshot)을 전송하는 빈도를 설정합니다. 기본값은 SimulationTickRate와 동일합니다.

성능 문제 방지

서버가 설정된 시뮬레이션 틱 레이트보다 느린 속도로 업데이트될 경우, 한 프레임에서 여러 개의 시뮬레이션 틱을 처리하려고 시도합니다.

예를 들어, 서버의 마지막 업데이트가 16ms가 아닌 50ms가 걸렸다면, 서버는 다음 프레임에서 이를 따라잡기 위해 약 3번의 시뮬레이션 스텝을 실행합니다 (16ms × 3 ≈ 50ms).

이러한 동작은 성능 저하를 악화시키는 악순환을 유발할 수 있습니다:

서버는 더 많은 시뮬레이션 스텝을 처리해야 하므로 점점 더 느려지고, 그 결과 틱 간격을 더 많이 놓치게 됩니다.

위와 같은 상황을 방지하기 위해 ClientServerTickRate에서는 다음과 같은 설정을 제공합니다

• MaxSimulationStepsPerFrame
  서버가 한 프레임 내에 수행할 수 있는 최대 시뮬레이션 스텝 수를 제한합니다.
• MaxSimulationStepBatchSize
  여러 틱을 하나의 배치(batch) 로 묶어 처리하도록 지시합니다.
  이때는 델타 타임(delta time)을 곱한 값으로 단일 스텝을 실행합니다.
  예: 2개의 스텝을 실행하는 대신, 1개의 스텝만 실행하되 델타 타임을 2배로 설정하여 처리합니다.

주의:
MaxSimulationStepBatchSize 에 의한 배칭 처리는 특정 조건에서만 작동하며, 자체적인 제한 사항이 있습니다.
게임 로직에서 “한 시뮬레이션 스텝 = 하나의 틱“이라고 가정하지 않도록 하며, TimeData.DeltaTime 값을 하드코딩하지 마십시오.
배칭이 발생하면 서버와 클라이언트 간의 시뮬레이션 정밀도가 달라져 예측 오류가 발생할 수 있습니다.

프레임 속도 유지 방식 설정

서버가 유휴 상태일 때 프레임 속도를 어떻게 유지할지도 설정할 수 있습니다.

TargetFrameRateMode는 서버가 틱 레이트를 유지하기 위한 유휴 시간 소비 방식을 제어합니다.

• BusyWait
  가능한 한 빠른 속도로 계속 실행 (CPU 사용량 높음)
• Sleep
Application.targetFrameRate에 맞춰 대기하여 CPU 부하를 줄임
• Auto
  헤드리스(콘솔 없는) 서버에서는 Sleep을 사용하고, 그 외에는 BusyWait을 사용

월드 마이그레이션 (World Migration)

현재 사용 중인 월드를 파괴(destroy) 하고, 연결 상태를 유지한 채로 새로운 월드로 전환하고자 할 경우, DriverMigrationSystem을 사용할 수 있습니다.

이 시스템은 네트워크 전송(transport) 관련 정보를 저장 및 불러올 수 있게 해주며, 매끄러운 월드 전환을 가능하게 합니다.

public World MigrateWorld(World sourceWorld)
{
    DriverMigrationSystem migrationSystem = default;
    foreach (var world in World.All)
    {
        if ((migrationSystem = world.GetExistingSystem<DriverMigrationSystem>()) != null)
            break;
    }

    var ticket = migrationSystem.StoreWorld(sourceWorld);
    sourceWorld.Dispose();

    var newWorld = migrationSystem.LoadWorld(ticket);

    // NOTE: LoadWorld는 반드시 새 월드에 필요한 시스템을 추가하기 전에 호출해야 합니다!
    // 이유: LoadWorld는 NetworkStreamReceiveSystem이 올바른 드라이버를 불러오기 위해 필요한 
    // `MigrationTicket` 컴포넌트를 생성하기 때문입니다.

    return ClientServerBootstrap.CreateServerWorld(DefaultWorld, newWorld.Name, newWorld);
}

이 기능은 예를 들어 로비에서 인게임으로 넘어가거나, 씬을 바꾸면서도 연결을 유지해야 하는 경우에 매우 유용합니다.

Additional resources

• Entities overview
• Thin clients
• Introduction to prediction

네트워크 프로토콜 검사

https://docs.unity3d.com/Packages/com.unity.netcode@1.5/manual/network-protocol-checks.html

클라이언트가 서버에 연결할 때, Netcode 프로토콜 버전(NetworkProtocolVersion) 을 주고받습니다.

이 프로토콜에는 다음과 같은 정보가 포함되어 있습니다:

• Netcode 버전 (netcode version)
• 게임 버전 (game version)
• RPC 컬렉션 (RPC collection)
• 직렬화된 컴포넌트 컬렉션 (erialized component collections)

서로 호환되지 않는 게임 버전 간의 연결을 사전에 차단하여 예측할 수 없는 동작을 방지합니다.

RPC 컬렉션은 모든 로드된 어셈블리에서 컴파일된 RPC들의 타입과 멤버를 기반으로 해시를 계산합니다.

Serialized Component 컬렉션 역시 Netcode for Entities가 수집한 고스트(Ghost) 컴포넌트를 기반으로 해시를 계산합니다.

이러한 타입 정보와 멤버들을 기반으로 계산된 해시값이 프로토콜의 일부로 사용됩니다.

Netcode for Entities는 기본적으로 이 해시값이 완전히 동일해야 통신이 가능하도록 설정되어 있습니다.

이렇게 하면 중간에 예외가 발생하는 것을 방지하고, 대역폭 최적화가 가능합니다.

개발 중 발생할 수 있는 문제

개발 중에는 호환 가능한 빌드조차도 이 검사 때문에 부적합한 버전으로 잘못 판단되는 경우가 있습니다.

예를 들어:

• 독립 실행형 빌드와 Unity Editor에서 실행 중인 월드를 연결하려는 경우
• Editor는 테스트용 어셈블리를 포함하고 있는데, 빌드에는 포함되어 있지 않을 경우
• 이로 인해 해시가 일치하지 않아 연결이 끊어짐

이러한 엄격한 프로토콜 검사는 개발 중 테스트에 방해가 될 수 있으므로, 비활성화할 수 있습니다.

이 프로토콜 버전 오류가 발생하면 각 피어는 사용자 코드가 읽을 수 있는 를 통해 원격 피어와의 연결을 끊고 

NetworkStreamDisconnectReason.BadProtocolVersion, 이를 사용하여 플레이어에게 해당 빌드가 대상 원격 피어와 호환되지 않음을 알립니다.

개발 빌드에서는 패키지가 로컬 피어에 로드된 RPC 및 고스트 유형의 전체 목록과 정렬된 목록을 나타내는 오류 로그도 출력합니다.

유형 불일치 문제를 해결하려면 이러한 로그를 원격 피어에서 발생한 로그와 상호 참조하세요.

프로토콜 검사 해제

검사를 비활성화하려면, 다음과 같이 RpcCollection.DynamicAssemblyList를 true로 설정합니다:

[BurstCompile] // 선택 사항
[WorldSystemFilter(WorldSystemFilterFlags.ClientSimulation | WorldSystemFilterFlags.ServerSimulation | WorldSystemFilterFlags.ThinClientSimulation)]
[UpdateInGroup(typeof(InitializationSystemGroup))]
[CreateAfter(typeof(RpcSystem))]
public partial struct SetRpcSystemDynamicAssemblyListSystem : ISystem
{
    public void OnCreate(ref SystemState state)
    {
        SystemAPI.GetSingletonRW<RpcCollection>().ValueRW.DynamicAssemblyList = true;
        state.Enabled = false;
    }
}

주의:

이 설정은 RpcSystem.OnUpdate가 실행되기 전에 적용되어야 하며,

RpcSystem.OnCreate 이후에 설정되어야 합니다.

클라이언트와 서버 모두 이 플래그 값을 동일하게 설정해야 연결이 가능합니다. (값이 다르면 프로토콜 해석 방식이 달라지기 때문)

이 기능을 활성화하면 다음과 같은 단점이 있습니다:

• 각 RPC마다 6바이트의 오버헤드가 발생합니다 (ushort 인덱스 대신 해시값 전체를 전송)
• 게임 도중, 클라이언트가 알 수 없는 RPC나 고스트 타입을 수신하게 되면
  → 런타임 오류 발생 후 즉시 연결이 끊어짐
  → 즉, 연결 시점이 아닌 게임 중간에 강제 종료될 수 있습니다

따라서 이 설정은 개발 중 테스트 목적으로 사용하는 것이 좋으며, 출시용 빌드에서는 권장되지 않습니다.

Additional resources

• NetworkProtocolVersion API

The post Unity Netcode for Entities – Client / Server worlds appeared first on 어제와 내일의 나 그 사이의 이야기.

IInputComponentData

https://docs.unity3d.com/Packages/com.unity.netcode@1.5/api/Unity.NetCode.IInputComponentData.html

Netcode for Entities (NFE)에서 클라이언트의 입력을 서버로 전송하기 위해 특별히 설계된 인터페이스

IInputComponentData의 핵심 역할

1⃣ 입력 데이터의 네트워크 동기화

• 클라이언트 → 서버로의 입력 전송을 최적화합니다.
• NFE는 이 인터페이스가 붙은 컴포넌트를 자동으로 직렬화/역직렬화합니다.

2⃣ 예측(Prediction) 시스템 지원

• 클라이언트 측 예측과 서버 측 보정을 가능하게 합니다.
• GhostPredictionSystemGroup에서 특별 처리됩니다.

3⃣ 입력 버퍼링

• 틱(tick) 기반으로 입력을 저장해 네트워크 지연 보정에 사용됩니다.

예시 코드

using Unity.Entities;
using Unity.NetCode;

// 반드시 IInputComponentData를 상속해야 함
public struct NetcodePlayerInput : IInputComponentData
{
    // 필드에 [GhostField] 속성을 추가해 직렬화 옵션 지정
    [GhostField(Quantization = 100)] // 값 범위: -1.0 ~ 1.0 → -100 ~ 100으로 압축
    public float MoveX; // 좌우 이동 입력 (-1: 왼쪽, 1: 오른쪽)

    [GhostField]
    public float MoveY; // 전후 이동 입력

    [GhostField]
    public InputEvent Jump; // 점프 입력 (버튼 상태)

    // 현재 틱 정보 (NFE가 자동으로 주입)
    public uint Tick { get; set; }
}

[GhostField(Quantization = 100)] 양자화를 사용하는 이유

Netcode for Entities (NFE)에서 네트워크 대역폭을 최적화하기 위해 사용되는 핵심 기능

1⃣ 데이터 압축으로 대역폭 절감

• 원본 데이터: float (32비트)
• 양자화 후: short (16비트) 등 작은 타입으로 변환

[GhostField(Quantization = 100)] 
public float MoveX; // -1.0 ~ 1.0 → -100 ~ 100 정수로 압축
// 1.75f → 175 (전송) : 수신 측에서 1.75f로 복원

2⃣ 네트워크 지연 감소

작은 데이터 패킷으로 통신하여 전송 시간 단축하여 실시간 반응성 향상 (지연 시간 감소)

3⃣ 작동 원리

• 적정 범위: -1.0 ~ 1.0 (조이스틱 입력 등)
  • Quantization = 100 → -100 ~ +100 (총 201단계)
  • 필요 비트: ⌈log₂(201)⌉ = 8비트 (1바이트)
• 정밀도 vs 효율 트레이드오프:
  • 100: 0.01 단위 정밀도 (대부분의 게임 입력에 충분)
  • 1000: 0.001 단위 (고정밀 필요 시) → 대역폭 2배 소모

4⃣ 간단 적용 예시

// 캐릭터 이동
[GhostField(Quantization = 100)]
public float Horizontal; // 좌우 이동 (-1.0 ~ 1.0)

[GhostField(Quantization = 100)]
public float Vertical;   // 전후 이동

// 캐릭터 회전
[GhostField(Quantization = 32767)] // short.MaxValue
public float RotationY; // 0 ~ 360도 → -32767 ~ 32767

5⃣ 최적화 가이드

6⃣ 주의사항

• 오버플로우 방지
  Quantization 값을 너무 크게 설정하면 정수 변환 시 오버플로우 발생 가능:

// 위험 예시 (float.MaxValue → 양자화 시 오류)
[GhostField(Quantization = 1000000)] 
public float DangerValue;

• 정밀도 한계
  0.005f 같은 미세한 값은 Quantization=100에서 반올림 오차 발생:

0.005f * 100 = 0.5f → 반올림 → 1 → 복원 시 0.01f (100% 오차)

• 에디터 디버깅
  NetworkProtocol 로그에서 실제 전송 크기 확인:

// Unity 콘솔에 패킷 크기 출력
Debug.Log($"패킷 크기: {System.Runtime.InteropServices.Marshal.SizeOf(packet)}바이트");

7⃣ 성능비교

// 양자화 미적용 (32비트 float)
[GhostField] 
public float Uncompressed; // 4바이트

// 양자화 적용 (8비트 압축)
[GhostField(Quantization = 100)] 
public float Compressed; // 1바이트

절감 효과: 75% 대역폭 감소 (4배 효율)
초당 60프레임 기준:
미적용: 60fps * 4B = 240B/s
적용: 60fps * 1B = 60B/s

IInputComponentData 와 IComponentData의 차이점

특징	IInputComponentData	IComponentData
자동 직렬화	네트워크 전송 최적화	직접 구현 필요
예측 지원	PredictedGhost와 연동	별도 시스템 필요
틱 동기화	Tick 프로퍼티 자동 관리	수동 처리
버퍼링	입력 히스토리 유지	직접 구현

The post IInputComponentData [Netcode for Entities] appeared first on 어제와 내일의 나 그 사이의 이야기.

Canvas Scaler (캔버스 스케일러)

https://docs.unity3d.com/Packages/com.unity.ugui@2.0/manual/script-CanvasScaler.html

캔버스 내 모든 UI 요소의 전체적인 스케일(크기)과 픽셀 밀도를 제어하는 데 사용하는 컴포넌트

이 스케일링은 폰트 크기와 이미지 테두리(Borders)를 포함하여 캔버스 아래에 있는 모든 요소에 영향을 미친다.

1. 주요 속성 (Properties)

(1) Scale With Screen Size

특정 기준 해상도(Reference Resolution)를 설정하고, 현재 화면에 맞춰 UI를 키우거나 줄입니다.

Reference Resolution: UI 레이아웃을 설계할 때 기준이 되는 해상도입니다.

Screen Match Mode: 현재 화면 비율이 기준 해상도와 다를 때 캔버스 영역을 맞추는 방식입니다.

• Match Width or Height: 가로 폭이나 세로 높이 중 하나를 기준으로(또는 그 사이 값으로) 스케일을 조절합니다.
• Expand: 캔버스 크기가 기준 해상도보다 작아지지 않도록 가로나 세로 방향으로 확장합니다.
• Shrink: 캔버스 크기가 기준 해상도보다 커지지 않도록 가로나 세로 방향으로 자릅니다(Crop).

Match: 가로(0)와 세로(1) 중 어느 쪽을 스케일링 기준으로 삼을지 결정합니다.

(2) Constant Pixel Size

UI 요소의 위치와 크기가 화면의 픽셀 단위로 지정됩니다.

• Scale Factor: 캔버스 내 모든 UI 요소에 일괄적으로 적용되는 스케일 값입니다.
• Reference Pixels Per Unit: 스프라이트의 ‘Pixels Per Unit’ 설정이 이 값과 같다면, 스프라이트의 1픽셀은 UI상의 1유닛(픽셀)과 대응합니다.

(3) Constant Physical Size

UI 요소의 크기를 밀리미터(mm), 포인트(points), 파이카(picas) 등 물리적 단위로 지정합니다.

• Physical Unit: 위치와 크기를 지정할 물리적 단위입니다.
• Fallback Screen DPI: 기기의 DPI를 알 수 없을 때 가정할 기본 DPI 값입니다.
• Default Sprite DPI: 스프라이트의 픽셀 밀도 기준입니다.
• Reference Pixels Per Unit: 스프라이트의 ‘Pixels Per Unit’ 설정이 이 값과 같다면, 스프라이트의 1픽셀은 UI상의 1유닛(픽셀)과 대응합니다.

2. 언제 사용하나요?

(1) 모바일 게임 – Scale With Screen Size

가장 많이 사용하며, 모바일 게임 개발의 표준입니다.

• 언제 사용하나?
  • 대부분의 모바일 게임, PC 게임을 만들 때.
  • 화면이 커지면 UI도 그에 비례해서 커지길 원할 때.
  • 다양한 해상도(아이폰, 갤럭시, 태블릿 등)에 대응해야 할 때.
• 특징: 기준 해상도(예: 1440×2560)를 정해두면 유니티가 알아서 기기 화면에 맞춰 UI를 키우거나 줄여줍니다. 개발자는 한 가지 사이즈만 고민하면 됩니다.

(2) 도구 모음, 정교한 그래픽 툴 – Constant Pixel Size

픽셀 숫자를 그대로 유지합니다.

• 언제 사용하나?
  • 웹 브라우저의 도구 모음이나 정교한 그래픽 툴 같은 앱을 만들 때.
  • 해상도가 높아져도 아이콘이 커지지 않고, 대신 더 넓은 작업 공간을 보여주고 싶을 때.
  • 저해상도와 고해상도에서 UI의 “선명도”를 1:1 픽셀 매칭으로 유지하고 싶을 때.
• 특징: 100×100 픽셀 버튼은 4K 모니터에서도 100×100 픽셀입니다. 따라서 고해상도 기기일수록 UI가 매우 작게 보입니다.

(3) 실제 크기가 중요 – Constant Physical Size

실제 자(Ruler)로 쟀을 때의 물리적 크기를 유지합니다.

• 언제 사용하나?
  • 실제 크기가 중요한 앱: 예를 들어 화면에 대고 길이를 재는 ‘자(Ruler) 앱’이나, 사람의 손가락 크기에 맞춰 버튼 크기가 물리적으로 일정해야 하는 특수 장비용 앱.
  • 화면의 밀도(DPI)와 상관없이 버튼이 항상 1cm가 되어야 할 때.
• 특징: 기기가 5인치든 10인치든 상관없이 버튼의 실제 길이를 유지하려 노력합니다. 기기가 화면의 DPI 정보를 정확히 전달해줘야 정상 작동합니다.

The post Unity Canvas Scaler appeared first on 어제와 내일의 나 그 사이의 이야기.

https://docs.unity3d.com/Packages/com.unity.shadergraph@17.0/manual/Create-Node-Menu.html

Description

Shader Graph에서 nodes를 생성하기 위해 Create Node Menu를 사용합니다.
Use the Create Node Menu to create nodes in Shader Graph.

노드 생성 메뉴를 열려면 Shader Graph 창의 작업 공간을 마우스 오른쪽 버튼으로 클릭하고 “Create Node”을 선택하거나, 스페이스바를 누릅니다.
To open the Create Node Menu, either right-click on the workspace in the Shader Graph Window and select Create Node, or press the spacebar.

Create Node Menu의 맨 위에는 검색 창이 있습니다.
At the top of the Create Node Menu is a search bar.

node를 검색하려면 검색 필드에 이름의 일부를 입력하십시오.
To search for a node, type any part of its name in the search field.

검색 상자는 자동 완성 옵션을 제공하며, 예측 텍스트를 수락하려면 Tab을 누르십시오.
The search box gives you autocomplete options, and you can press Tab to accept the predictive text.

일치하는 텍스트를 노란색으로 강조합니다.
It highlights matching text in yellow.

Create Node Menu lists에는 기능별로 분류된 Shader Graph에서 사용 가능한 모든 노드가 나열됩니다.
The Create Node Menu lists all nodes that are available in Shader Graph, categorized by their function.

사용자가 작성한 Sub Graphs는 서브 그래프 에셋 하위의 Create Node Menu에서 사용할 수 있으며, Sub Graph Assets에서 정의한 사용자 지정 카테고리에도 사용할 수 있습니다.
User-created Sub Graphs are also available in the Create Node Menu under Sub Graph Assets, or in a custom category that you define in the Sub Graph Asset.

작업 공간에 노드를 추가하려면 Create Node Menu에서 해당 노드를 두 번 클릭하십시오.
To add a node to the workspace, double-click it in the Create Node Menu.

Contextual Create Node Menu

컨텍스트에 맞는 Create Node Menu는 사용 가능한 노드를 필터링하고 선택한 엣지의 Data Type을 사용하는 노드만 표시합니다.
A contextual Create Node Menu filters the available nodes, and only shows those that use the Data Type of a selected edge.

해당 Data Type과 일치하는 노드의 모든 사용 가능한 Port를 나열합니다.
It lists every available Port on nodes that match that Data Type.

컨텍스트에 맞는  Create Node Menu를 열려면 포트에서 Edge를 클릭하고 드래그한 다음 작업 공간의 빈 영역에 놓으면 됩니다.
To open a contextual Create Node Menu, click and drag an Edge from a Port, and then release it in an empty area of the workspace.

Master Stack Create Node Menu

새로운 Block Node를 Master Stack에 추가하려면 마우스 오른쪽 버튼을 클릭하고 “Create Node“을 선택하거나 스택을 선택한 상태에서 스페이스바를 누르세요.
To add a new Block Node to the Master Stack, either right click and select Create Node or press spacebar with the stack selected.

“Create Node Menu“는 프로젝트의 렌더 파이프라인을 기반으로 마스터 스택에 사용 가능한 모든 블록을 표시합니다.
The Create Node Menu will display all available blocks for the master stack based on the render pipelines in your project.

“Create Node Menu“를 통해 마스터 스택에 어떤 블록이든 추가할 수 있습니다.
Any block can be added to the master stack via the Create Node Menu.

추가된 block이 현재 Graph settings과 호환되지 않는 경우, 해당 block은 설정이 지원될 때까지 비활성화됩니다.
If the block added is not compatible with the current Graph settings, the block will be disabled until the settings are configured to support it.

The post Getting started with Shader Graph – Create Node Menu appeared first on 어제와 내일의 나 그 사이의 이야기.

https://docs.unity3d.com/2023.3/Documentation/Manual/JobSystem.html

Job system

job system을 사용하면 간단하고 안전한 멀티 스레드 코드를 작성할 수 있으므로 응용 프로그램이 사용 가능한 모든 CPU 코어를 사용하여 코드를 실행할 수 있습니다.
The job system lets you write simple and safe multithreaded code so that your application can use all available CPU cores to execute your code.

이것은 응용 프로그램의 성능을 향상시키는 데 도움이 될 수 있습니다
This can help improve the performance of your application.

using UnityEngine;
using Unity.Collections;
using Unity.Jobs;

class ApplyVelocitySample : MonoBehaviour
{
    // 작업 구조체 정의
    struct VelocityJob : IJob
    {
        // 작업에서 액세스할 모든 데이터를 선언
        // 읽기 전용으로 선언함으로써 여러 작업이 데이터에 병렬로 액세스할 수 있게 함
        [ReadOnly]
        public NativeArray<Vector3> velocity;

        // 기본적으로 컨테이너는 읽기 및 쓰기로 가정됨
        public NativeArray<Vector3> position;

        // 델타 타임은 일반적으로 작업이 프레임 개념을 가지지 않기 때문에 작업에 복사되어야 함
        // 메인 스레드는 동일한 프레임 또는 다음 프레임에 작업을 기다리지만, 작업은 워커 스레드에서 실행될 때 결정적이고 독립적인 방식으로 작업을 수행해야 함
        public float deltaTime;
         
        // 작업에서 실행되는 코드
        public void Execute()
        {
            // 델타 타임과 속도에 기반하여 위치 이동
            for (var i = 0; i < position.Length; i++)
                position[i] = position[i] + velocity[i] * deltaTime;
        }
    }

    public void Update()
    {
        var position = new NativeArray<Vector3>(500, Allocator.Persistent);

        var velocity = new NativeArray<Vector3>(500, Allocator.Persistent);

        int _l = velocity.Length;
        for (var i = 0; i < _l; i++)
            velocity[i] = new Vector3(0, 10, 0);

        // 작업 데이터 초기화
        var job = new VelocityJob()
        {
            deltaTime = Time.deltaTime,
            position = position,
            velocity = velocity
        };

        // 작업 예약, 나중에 대기할 수 있는 JobHandle 반환
        JobHandle jobHandle = job.Schedule();

        // 작업이 완료될 때까지 대기
        // 작업을 즉시 완료하는 것은 권장되지 않으며,
        // 실제로 병렬성을 제공하지 않음
        // 작업을 프레임 초기에 예약하고 나중에 프레임 중에 대기하는 것이 최적임
        jobHandle.Complete();

        Debug.Log(job.position[0]);

        // Native 배열은 수동으로 Dispose해야 함
        position.Dispose();
        velocity.Dispose();
    }
}

using Unity.Collections;
using Unity.Jobs;
using UnityEngine;

class ApplyVelocityParallelForSample : MonoBehaviour
{
    struct VelocityJob : IJobParallelFor
    {
        // 작업에서 액세스될 모든 데이터를 선언합니다.
        // 읽기 전용으로 선언함으로써 여러 작업이 데이터에 병렬로 액세스할 수 있습니다.
        [ReadOnly]
        public NativeArray<Vector3> velocity;

        // 기본적으로 컨테이너는 읽기 및 쓰기로 가정됩니다.
        public NativeArray<Vector3> position;

        // 작업은 일반적으로 프레임의 개념이 없기 때문에 델타 타임은 작업으로 복사되어야 합니다.
        // 주 스레드는 작업이 동일한 프레임이나 다음 프레임에 실행되기를 기다리지만,
        // 작업은 언제 워커 스레드에서 실행될지에 관계없이 결정론적으로 독립적으로 작업해야 합니다.
        public float deltaTime;

        // 실제로 작업에서 실행되는 코드
        public void Execute(int i)
        {
            // 델타 타임과 속도에 기반하여 위치를 이동합니다.
            position[i] = position[i] + velocity[i] * deltaTime;
        }
    }

    public void Update()
    {
        // 위치에 대한 네이티브 배열 초기화
        var position = new NativeArray<Vector3>(500, Allocator.Temp);

        // 속도에 대한 네이티브 배열 초기화
        var velocity = new NativeArray<Vector3>(500, Allocator.Temp);
        for (var i = 0; i < velocity.Length; i++)
            velocity[i] = new Vector3(0, 10, 0);

        // 작업 데이터 초기화
        var job = new VelocityJob()
        {
            deltaTime = Time.deltaTime,
            position = position,
            velocity = velocity
        };

        // 병렬 작업 예약. 첫 번째 매개변수는 각 반복(iteration)을 수행할 횟수이며,
        // 두 번째 매개변수는 배치 크기(batch size)로,
        // 내부 루프에서 Execute(i)를 불러오는 오버헤드가 없는 값입니다.
        // 각 반복에서 수행할 작업이 많은 경우에는 1의 값을 사용할 수 있습니다.
        // 작업이 매우 적은 경우에는 32 또는 64의 값이 적절합니다.
        JobHandle jobHandle = job.Schedule(position.Length, 64);

        // 작업이 완료될 때까지 대기합니다.
        // 작업을 즉시 완료하는 것은 권장되지 않습니다.
        // 왜냐하면 그렇게 되면 다른 작업이 병렬로 실행되는 기회가 줄어들기 때문입니다.
        // 작업을 프레임 초반에 예약하고, 프레임 후반에 완료되길 기다리는 것이 최적입니다.
        jobHandle.Complete();

        Debug.Log(job.position[0]);

        // 네이티브 배열은 수동으로 해제되어야 합니다.
        position.Dispose();
        velocity.Dispose();
    }
}

using UnityEngine;
using Unity.Collections;
using Unity.Jobs;
using UnityEngine.Jobs;

class ApplyVelocitySample : MonoBehaviour
{
    public struct VelocityJob : IJobParallelForTransform
    {
        // Jobs는 작업에서 액세스 될 모든 데이터를 선언합니다.
        // 읽기 전용으로 선언함으로써 여러 작업이 데이터에 병렬로 액세스할 수 있게 합니다.
        [ReadOnly]
        public NativeArray<Vector3> velocity;

        // 작업에서는 일반적으로 프레임의 개념이 없기 때문에 델타 타임은 작업으로 복사되어야 합니다.
        // 메인 스레드는 작업이 동작하는 동안 같은 프레임 또는 다음 프레임에 대기하지만,
        // 작업은 워커 스레드에서 실행될 때에도 작업이 실행되는 시기에 독립적으로 작업을 수행해야 합니다.
        public float deltaTime;

        // 실제로 작업에서 실행되는 코드
        public void Execute(int index, TransformAccess transform)
        {
            // 델타 타임과 속도를 기반으로 변환을 이동합니다.
            var pos = transform.position;
            pos += velocity[index] * deltaTime;
            transform.position = pos;
        }
    }

    // 인스펙터에서 작업할 변환을 할당합니다.
    [SerializeField] public Transform[] m_Transforms;
    TransformAccessArray m_AccessArray;

    void Awake()
    {
        // 변환을 TransformAccessArray 인스턴스에 저장하여
        // 작업에서 액세스할 수 있도록 합니다.
        m_AccessArray = new TransformAccessArray(m_Transforms);
    }

    void OnDestroy()
    {
        // TransformAccessArray는 수동으로 폐기해야 합니다.
        m_AccessArray.Dispose();
    }

    public void Update()
    {
        var velocity = new NativeArray<Vector3>(m_Transforms.Length, Allocator.Persistent);

        for (var i = 0; i < velocity.Length; ++i)
            velocity[i] = new Vector3(0f, 10f, 0f);

        // 작업 데이터를 초기화합니다.
        var job = new VelocityJob()
        {
            deltaTime = Time.deltaTime,
            velocity = velocity
        };

        // 병렬-for-변환 작업을 예약합니다.
        // 메서드는 작업에서 동작될 TransformAccessArray를 취합니다.
        JobHandle jobHandle = job.Schedule(m_AccessArray);

        // 작업이 완료될 때까지 대기합니다.
        // 작업을 즉시 완료하는 것은 권장되지 않습니다.
        // 왜냐하면 이렇게하면이 작업과 병렬로 다른 작업이 실행될 가능성이 줄어듭니다.
        // 최적으로는 프레임 초반에 작업을 예약한 다음 프레임 중후반에 대기해야 합니다.
        jobHandle.Complete();

        Debug.Log(m_Transforms[0].position);

        // Native 배열은 수동으로 폐기해야 합니다.
        velocity.Dispose();
    }
}

using UnityEngine;
using Unity.Collections;
using Unity.Jobs;

class ApplyVelocityParallelForSample : MonoBehaviour
{
    struct VelocityJob : IJobFor
    {
        // Jobs는 작업에서 액세스할 모든 데이터를 선언합니다.
        // 읽기 전용으로 선언함으로써 여러 작업이 데이터에 병렬로 액세스할 수 있습니다.
        [ReadOnly]
        public NativeArray<Vector3> velocity;

        // 기본적으로 컨테이너는 읽기 및 쓰기로 가정됩니다.
        public NativeArray<Vector3> position;

        // 델타 타임은 일반적으로 프레임의 개념이 없는 작업에서 작업이 수행됩니다.
        // 메인 스레드는 작업이 동일한 프레임 또는 다음 프레임에 실행되기를 기다립니다.
        // 그러나 작업은 워커 스레드에서 실행될 때에 프레임의 개념을 가지지 않아야 합니다.
        public float deltaTime;

        // 작업에서 실행되는 실제 코드
        public void Execute(int i)
        {
            // 델타 타임과 속도를 기반으로 위치를 이동시킵니다.
            position[i] = position[i] + velocity[i] * deltaTime;
        }
    }

    public void Update()
    {
        var position = new NativeArray<Vector3>(500, Allocator.Persistent);

        var velocity = new NativeArray<Vector3>(500, Allocator.Persistent);
        for (var i = 0; i < velocity.Length; i++)
            velocity[i] = new Vector3(0, 10, 0);

        // 작업 데이터 초기화
        var job = new VelocityJob()
        {
            deltaTime = Time.deltaTime,
            position = position,
            velocity = velocity
        };

        // 작업을 즉시 메인 스레드에서 실행하도록 예약합니다. 첫 번째 매개 변수는 각각의 반복 횟수입니다.
        job.Run(position.Length);

        // 나중에 단일 워커 스레드에서 작업을 예약합니다.
        // 첫 번째 매개 변수는 각각의 반복 횟수입니다.
        // 두 번째 매개 변수는 이 작업의 종속성에 사용할 JobHandle입니다.
        // 종속성은 작업이 종속성이 완료된 후에 워커 스레드에서 실행되도록 보장합니다.
        // 이 경우 작업이 어떤 것에도 의존하지 않기 때문에 기본 값을 사용할 수 있습니다.
        JobHandle scheduleJobDependency = new JobHandle();
        JobHandle scheduleJobHandle = job.Schedule(position.Length, scheduleJobDependency);

        // 병렬 워커 스레드에서 작업을 실행하도록 예약합니다.
        // 첫 번째 매개 변수는 각각의 반복 횟수입니다.
        // 두 번째 매개 변수는 배치 크기이며,
        // 본질적으로는 Execute(i)를 루프에서 호출하는 오버헤드가 없는 내부 루프입니다.
        // 각 반복에서 많은 작업이 있는 경우 값이 1이 합리적일 수 있습니다.
        // 매우 적은 작업이 있는 경우 32 또는 64의 값이 합리적일 수 있습니다.
        // 세 번째 매개 변수는 이 작업의 종속성에 사용할 JobHandle입니다.
        // 종속성은 작업이 종속성이 완료된 후에 워커 스레드에서 실행되도록 보장합니다.
        JobHandle scheduleParallelJobHandle = job.ScheduleParallel(position.Length, 64, scheduleJobHandle);

        // 작업이 완료될 때까지 기다립니다.
        // 작업을 즉시 완료하는 것은 권장되지 않습니다.
        // 왜냐하면 이렇게 하면이 작업과 병렬로 다른 작업이 실행되는 기회가 줄어들기 때문입니다.
        // 최적으로는 프레임 초반에 작업을 예약하고 나중에 프레임에서 기다리는 것이 좋습니다.
        scheduleParallelJobHandle.Complete();

        Debug.Log(job.position[0]);

        // Native 배열은 수동으로 해제되어야 합니다.
        position.Dispose();
        velocity.Dispose();
    }
}

https://docs.unity3d.com/2023.3/Documentation/Manual/JobSystemNativeContainer.html

스레드 세이프 타입 (Thread safe types)

---

작업 시스템은 Burst 컴파일러와 함께 사용될 때 가장 효과적으로 작동합니다.
The job system works best when you use it with the Burst compiler.

Burst는 관리되는 객체를 지원하지 않기 때문에 작업에서 데이터에 액세스하려면 관리되지 않는 타입을 사용해야 합니다.
Because Burst doesn’t support managed objects, you need to use unmanaged types to access the data in jobs.

이를 위해 blittable 타입을 사용하거나 Unity에서 기본으로 제공하는 스레드 안전 C# 래퍼 NativeContainer 객체를 사용할 수 있습니다.
You can do this with blittable types, or use Unity’s built-in NativeContainer objects, which are a thread-safe C# wrapper for native memory.

NativeContainer 객체는 작업에서 복사본으로 작업하는 대신 Main thread와 공유하는 데이터에 액세스할 수도 있습니다.
NativeContainer objects also allow a job to access data shared with the main thread rather than working with a copy.

NativeContainer 객체의 종류 (Types of NativeContainers)

Unity.Collections 네임스페이스에는 다음과 같은 기본 제공 NativeContainer 객체가 포함되어 있습니다:
The Unity.Collections namespace contains the following built-in NativeContainer objects:

• NativeArray :
  관리되지 않는 배열로, 관리 코드에 네이티브 메모리 버퍼를 노출시킵니다.
  An unmanaged array which exposes a buffer of native memory to managed code
• NativeSlice :
  특정 위치부터 특정 길이까지의 NativeArray의 하위 집합을 가져옵니다.
  Gets a subset of a NativeArray from a particular position to a certain length.

참고
Collections package에는 추가적인 NativeContainer가 포함되어 있습니다.
The Collections package contains additional NativeContainers.
추가 유형의 전체 목록은 Collection types에서 Collections 문서를 참조하세요.
For a full list of the additional types, see the Collections documentation on Collection types.

읽기 및 쓰기 액세스 (Read and Write Access)

기본적으로 작업이 NativeContainer  인스턴스에 액세스할 때 읽기 및 쓰기 액세스 권한이 모두 부여됩니다.
By default, when a job has access to a NativeContainer instance, it has both read and write access.

이 구성은 성능을 떨어뜨릴 수 있습니다.
This configuration can slow performance.

작업 시스템은 동시에 두 개 이상의 작업이 동일한 NativeContainer 인스턴스에 쓰기 액세스하는 것을 허용하지 않기 때문입니다.
This is because the job system doesn’t allow you to schedule a job that has write access to a NativeContainer instance at the same time as another job that’s writing to it.

그러나 작업이 NativeContainer 인스턴스에 기록할 필요가 없는 경우 다음과 같이 NativeContainer를 [ReadOnly] 속성으로 표시할 수 있습니다:
However, If a job doesn’t need to write to a NativeContainer instance, you can mark the NativeContainer with the [ReadOnly] attribute, like so:

[ReadOnly]
public NativeArray<int> input;

위의 예에서는 첫 번째 NativeArray에 대한 읽기 전용 액세스 권한이 있는 다른 작업과 동시에 작업을 실행할 수 있습니다.
In the above example, you can execute the job at the same time as other jobs that also have read-only access to the first NativeArray.

메모리 할당자 (Memory Allocators)

NativeContainer 인스턴스를 생성할 때는 필요한 메모리 할당 유형을 지정해야 합니다.
When you create a NativeContainer instance, you must specify the memory allocation type that you need.

사용하는 할당 유형은 해당 네이티브 컨테이너를 얼마 동안 유지하고 싶은지에 따라 다릅니다.
The allocation type you use depends on how long you would like to keep the native container available for.

이렇게 함으로써 각 상황에서 최상의 성능을 얻을 수 있습니다.
This way you can tailor the allocation to get the best performance possible in each situation.

NativeContainer 메모리 할당 및 해제에는 세 가지 Allocator 유형이 있습니다.
There are three Allocator types for NativeContainer memory allocation and release.

NativeContainer 인스턴스를 인스턴스화할 때 적절한 것을 지정해야 합니다:
You must specify the appropriate one when instantiating a NativeContainer instance:

1. Allocator.Temp:
   • 가장 빠른 할당 방식입니다.
     The fastest allocation.
   • 수명이 한 프레임 이하인 할당에 사용합니다.
     Use it for allocations with a lifespan of one frame or fewer.
   • Temp를 사용하여 작업의 멤버 필드에 저장된 NativeContainer instance로 할당을 전달할 수 없습니다.
     You can’t use Temp to pass allocations to NativeContainer instances stored in a job’s member field.
2. Allocator.TempJob:
   • Temp보다는 느린 할당 방식이지만 Persistent보다는 빠릅니다. (중간)
     A slower allocation than Temp but faster than Persistent.
   • 최대 4프레임 동안의 수명을 가진 스레드 안전한 할당에 사용합니다.
     Use it for thread-safe allocations within a lifespan of four frames.
   • 중요: 이 할당 유형은 4프레임 이내에 Dispose해야 하며, 그렇지 않으면 콘솔에 경고가 표시되며 네이티브 코드에서 생성됩니다.
     Important: You must Dispose of this allocation type within four frames, or the console prints a warning, generated from the native code.
     대부분의 작은 작업은 이 할당 유형을 사용합니다.
     Most small jobs use this allocation type.
3. Allocator.Persistent:
   • 가장 느린 할당 방식이지만 필요한 경우 응용 프로그램 수명 전체 또는 필요한 기간 동안 지속될 수 있습니다.
     The slowest allocation but can last as long as you need it to, and if necessary, throughout the application’s lifetime.
   • malloc에 직접 호출하는 래퍼입니다.
     It’s a wrapper for a direct call to malloc.
   • 긴 작업에는 이 NativeContainer 할당 유형을 사용할 수 있습니다.
     Longer jobs can use this NativeContainer allocation type.
     성능이 중요한 경우에는 Persistent를 사용하지 않는 것이 좋습니다.
     Don’t use Persistent where performance is essential.

예를 들어 :

NativeArray<float> result = new NativeArray<float>(1, Allocator.TempJob);

참고 : 위의 예제에서 숫자 1은 NativeArray의 크기를 나타냅니다. 이 경우 결과에 저장되는 데이터가 하나이므로 배열 요소가 하나만 있습니다.
Note: The number 1 in the example above indicates the size of the NativeArray. In this case, it has only one array element because it only stores one piece of data in its result.

NativeContainer 안전 시스템 (NativeContainer safety system)

안전 시스템은 모든 NativeContainer 인스턴스에 내장되어 있습니다.
The safety system is built into all NativeContainer instances.

이 시스템은 어떤 NativeContainer 인스턴스에 대한 읽기 또는 쓰기를 추적하고
It tracks what reads or writes to any NativeContainer instance,

이 정보를 사용하여 여러 작업 및 스레드에서 NativeContainer의 사용에 특정 규칙을 강제합니다.
이로써 NativeContainer는 다중 작업 및 스레드에서 결정론적으로 작동하도록 보장됩니다. (동일한 입력에 대해 동일한 출력을 생성)
and uses that information to enforce certain rules on the use of NativeContainers that makes them behave in a deterministic way across multiple jobs and threads.

예를 들어, 두 개의 독립적인 예약 작업이 동일한 NativeArray에 쓰기를 시도하면 예측할 수 없기 때문에 이는 안전하지 않습니다.
For example, if two independent scheduled jobs write to the same NativeArray, this is unsafe because you can’t predict which job executes first.

어떤 작업이 먼저 실행될지 예측할 수 없으므로 두 작업 중 어떤 것이 다른 작업에서의 데이터를 덮어쓸지 알 수 없습니다.
This means that you won’t know which of the jobs will overwrite data from the other.

두 번째 작업을 예약할 때, 안전 시스템은 문제를 설명하는 명확한 오류 메시지와 문제를 해결하는 방법을 제시하는 예외를 throw합니다.
The safety system throws an exception with a clear error message that explains why and how to solve the problem, when you schedule the second job.

만약 동일한 NativeContainer 인스턴스에 쓰기 작업을 하는 두 작업을 예약하려면, 작업을 종속성을 가지도록 예약할 수 있습니다.
If you want to schedule two jobs that write to the same NativeContainer instance, you can schedule the jobs with a dependency.

첫 번째 작업이 NativeContainer에 쓰기를 수행하고 나면 다음 작업이 동일한 NativeContainer에 안전하게 읽기 및 쓰기를 수행합니다.
The first job writes to the NativeContainer, and once it has finished executing, the next job safely reads and writes to that same NativeContainer.

종속성을 도입함으로써 작업이 항상 일관된 순서로 실행되고 NativeContainer의 결과 데이터가 결정론적으로 유지됩니다.
Introducing the dependency guarantees that the jobs always execute in a consistent order and that the resulting data in the NativeContainer is deterministic.

안전 시스템은 여러 작업이 동시에 동일한 데이터를 읽을 수 있도록 허용합니다.
The safety system allows multiple jobs to read from the same data in parallel.

이러한 읽기 및 쓰기 제한은 데이터에 메인 스레드에서 액세스할 때도 적용됩니다.
These read and write restrictions also apply when accessing data from the main thread.

예를 들어, NativeContainer에 쓰기를 완료하기 전에 해당 NativeContainer의 내용을 읽으려고 하면 안전 시스템에서 오류가 발생합니다.
For example, if you try to read the contents of a NativeContainer before the job that writes to it has completed, the safety system throws an error.

마찬가지로 해당 NativeContainer에 대해 아직 처리되지 않은 읽기 또는 쓰기 작업이 있는 동안 해당 NativeContainer에 쓰려고 하면 안전 시스템에서도 오류가 발생합니다.
Likewise, if you try to write to a NativeContainer while there are still pending jobs that read or write to it, then the safety system also throws an error.

또한 NativeContainers는 ref return을 구현하지 않기 때문에 NativeContainer의 내용을 직접 변경할 수 없습니다.
Also, because NativeContainers don’t implement ref return, you can’t directly change the contents of a NativeContainer.

예를 들어 nativeArray[0]++;는 var temp = nativeArray[0]; temp++;와 동일하며, 이는 nativeArray의 값이 업데이트되지 않습니다.
For example, nativeArray[0]++; is the same as writing var temp = nativeArray[0]; temp++; which doesn’t update the value in nativeArray.

대신, 해당 인덱스의 데이터를 지역 임시 복사본으로 복사하고 해당 복사본을 수정한 다음 다시 저장해야 합니다.
Instead, you must copy the data from the index into a local temporary copy, modify that copy, and save it back. For example:

예를 들면:

MyStruct temp = myNativeArray[i];
temp.memberVariable = 0;
myNativeArray[i] = temp;

추가 리소스 (Additional resources)

커스텀 NativeContainer 구현
Implement a custom NativeContainer

https://docs.unity3d.com/2023.3/Documentation/Manual/job-system-custom-nativecontainer.html

커스텀 네이티브 컨테이너 구현 (Implement a custom native container)

---

사용자 정의 네이티브 컨테이너를 구현하려면 해당 유형에 NativeContainer 속성을 부여해야 합니다.
To implement a custom native container, you must annotate your type with the the NativeContainer attribute.

또한 네이티브 컨테이너가 안전 시스템과 통합되는 방식을 이해해야 합니다.
You should also understand how native containers are integrated with the safety system.

구현해야 할 두 가지 주요 요소가 있습니다:
There are two major elements to implement:

• 사용 추적(Usage Tracking) :
  • Unity가 NativeContainer 인스턴스를 사용하는 예약된 작업을 추적하도록 허용하여
    두 작업이 동시에 동일한 네이티브 컨테이너에 쓰기를 시도하는 등의 충돌을 감지하고 방지합니다.
    Allows Unity to keep track of scheduled jobs that use a NativeContainer instance,
    so that it can detect and prevent potential conflicts, such as two jobs writing to the same native container at the same time.
• 누수 추적(Leak Tracking) :
  • NativeContainer 가 제대로 Dispose되지 않은 경우를 감지합니다.
    Detects when a NativeContainer isn’t disposed of properly.
    이러한 상황에서는 메모리 누수가 발생하여 NativeContainer 에 할당된 메모리가 프로그램의 나머지 수명 동안 사용할 수 없게 됩니다.
     In this situation, a memory leak happens, where the memory allocated to the NativeContainer becomes unavailable for the entire remaining lifetime of the program.

사용량 추적 구현 (Implement usage tracking)

사용 추적을 구현하려면 코드에서 AtomicSafetyHandle 클래스를 사용합니다.
To access usage tracking in your code, use the AtomicSafetyHandle class.

AtomicSafetyHandle은 주어진 NativeContainer에 대해 안전 시스템이 저장하는 중앙 정보에 대한 참조를 보유하며,
NativeContainer의 메서드가 안전 시스템과 상호 작용하는 주요 방법입니다.
AtomicSafetyHandle holds a reference to the central information that the safety system stores for a given NativeContainer,
and is the main way that the methods of a NativeContainer interact with the safety system.

따라서 모든 NativeContainer 인스턴스는 m_Safety라는 이름의 AtomicSafetyHandle 필드를 포함해야 합니다.
Because of this, every NativeContainer instance must contain an AtomicSafetyHandle field named m_Safety.

각 AtomicSafetyHandle은 현재 컨텍스트에서 NativeContainer에 수행할 수 있는 작업 유형을 나타내는 플래그 집합을 저장합니다.
Each AtomicSafetyHandle stores a set of flags that indicate what types of operation can be performed on the native container in the current context.

작업이 NativeContainer 인스턴스를 포함하는 경우 작업 시스템은 자동으로 AtomicSafetyHandle의 플래그를 구성하여
해당 작업에서 NativeContainer를 사용할 수 있는 방식을 반영합니다.
When a job contains a NativeContainer instance, the job system automatically configures
the flags in the AtomicSafetyHandle to reflect the way that the native container can be used in that job.

작업이 NativeContainer 인스턴스에서 읽기를 시도할 때 작업 시스템은 읽기 전에 CheckReadAndThrow 메서드를 호출하여
작업이 NativeContainer에 대한 읽기 액세스 권한이 있는지 확인합니다.
When a job tries to read from a NativeContainer instance, the job system calls the CheckReadAndThrow method before reading,
to confirm that the job has read access to the native container.

마찬가지로 작업이 NativeContainer에 쓰기를 시도할 때 작업 시스템은 쓰기 전에 CheckWriteAndThrow를 호출하여
작업이 NativeContainer에 대한 쓰기 액세스 권한이 있는지 확인합니다.
Similarly, when a job tries to write to a native container, the job system calls CheckWriteAndThrow before writing, to check that the job has write access to the native container. 

두 작업이 동일한 NativeContainer 인스턴스를 할당 받은 경우에도, 해당 네이티브 컨테이너에 대해 별도의 AtomicSafetyHandle 객체를 갖습니다.
Two jobs that have been assigned the same NativeContainer instance have separate AtomicSafetyHandle objects for that native container,

따라서 두 작업은 동일한 중앙 정보를 참조하더라도,
각각이 네이티브 컨테이너에 대한 읽기 및 쓰기 액세스를 나타내는 별도의 플래그를 유지할 수 있습니다.
so although they both reference the same set of central information,
they can each hold separate flags that indicate what read and write access each job has to the native container.

누출 추적 구현 (Implement leak tracking)

Unity’s native code는 주로 누수 추적을 구현합니다.
Unity’s native code primarily implements leak tracking.

UnsafeUtility.MallocTracked 메서드를 사용하여 NativeContainer 데이터를 저장하는 데 필요한 메모리를 할당하고,
이를 해제하기 위해 UnsafeUtility.FreeTracked를 사용합니다.
It uses the UnsafeUtility.MallocTracked method to allocate the memory needed to store NativeContainer data,
and then uses UnsafeUtility.FreeTracked to dispose of it.

이전 유니티 버전에서는 DisposeSentinel 클래스가 누수 추적을 제공했습니다.
In earlier versions of Unity the DisposeSentinel class provides leak tracking.

가비지 컬렉터가 DisposeSentinel 객체를 수집할 때 유니티는 메모리 누수를 보고합니다.
Unity reports a memory leak when the garbage collector collects the DisposeSentinel object.

DisposeSentinel을 만들려면 Create 메서드를 사용하며, 이 메서드를 사용하면 AtomicSafetyHandle을 동시에 초기화할 필요가 없습니다.
To create a DisposeSentinel, use the Create method, which also initializes the AtomicSafetyHandle at the same time.

ativeContainer가 Dispose될 때 Dispose 메서드는 DisposeSentinel과 AtomicSafetyHandle을 한 번에 처리합니다.
When the NativeContainer is disposed of, the Dispose method disposes of both the DisposeSentinel and the AtomicSafetyHandle in a single call.

누수가 발생한 NativeContainer가 생성된 위치를 식별하려면 메모리가 원래 할당된 위치의 스택 트레이스를 캡처할 수 있습니다.
To identify where the leaked NativeContainer was created, you can capture the stack trace of where the memory was originally allocated.

이를 위해 NativeLeakDetection.Mode 속성을 사용하고 에디터에서는
Preferences > Jobs > Leak Detection Level로 이동하여 필요한 누수 검출 수준을 선택할 수 있습니다.
To do this, use the NativeLeakDetection.Mode property. You can also access this property in the Editor.
To do this, go to Preferences > Jobs > Leak Detection Level and choose the leak detection level you need.

중첩된 네이티브 컨테이너 (Nested native containers)

안전 시스템은 작업에서 중첩된 NativeContainer를 지원하지 않습니다.
The safety system doesn’t support nested native containers in jobs,

To prevent scheduling jobs that use nested native containers, use SetNestedContainer, which flags a NativeContainer as nested when they contain other NativeContainer instances.

이는 작업 시스템이 큰 NativeContainer 인스턴스 내의 각 개별 NativeContainer에 대한 AtomicSafetyHandle을 올바르게 구성할 수 없기 때문입니다.
because the job system can’t correctly configure the AtomicSafetyHandle for each individual NativeContainer inside the larger NativeContainer instance.

중첩된 NativeContainer를 사용하는 작업을 예약하지 않도록 방지하려면 SetNestedContainer 플래그를 사용하십시오.
To prevent scheduling jobs that use nested native containers, use SetNestedContainer,

이 메서드는 다른 NativeContainer 인스턴스를 포함할 때 해당 NativeContainer를 중첩된 것으로 플래그 지정합니다.
which flags a NativeContainer as nested when they contain other NativeContainer instances.

안전 ID 및 오류 메시지 (Safety IDs and error messages)

Safety system은 코드가 안전성 제약을 준수하지 않을 때 발생하는 오류 메시지를 제공합니다.
The safety system provides error messages that indicate when your code doesn’t adhere to safety constraints.

오류 메시지를 더 명확하게 만들기 위해 NativeContainer 객체의 이름을 safety system에 등록할 수 있습니다.
To help make the error messages clearer, you can register a NativeContainer object’s name with the safety system.

이름을 등록하려면 NewStaticSafetyId를 사용하고, 이는 SetStaticSafetyId에 전달할 safety ID를 반환합니다.
To register a name, use NewStaticSafetyId, which returns a safety ID that you can pass to SetStaticSafetyId.

한 번 safety ID를 생성하면 NativeContainer의 모든 인스턴스에서 재사용할 수 있으므로
주로 컨테이너 클래스의 정적 멤버에 저장하는 것이 일반적인 패턴입니다.
Once you create a safety ID, you can reuse it for all instances of the NativeContainer,
so a common pattern is to store it in a static member of the container class.

또한 SetCustomErrorMessage를 사용하여 특정 안전성 제약 위반에 대한 사용자 지정 오류 메시지를 재정의할 수도 있습니다.
You can also override the error messages for specific safety constraint violations with SetCustomErrorMessage.

추가 리소스 (Additional resources)

• NativeContainer 구조 복사
  Copying NativeContainer structures
• 사용자 정의 NativeContainer 예
  Custom NativeContainer example

---

https://docs.unity3d.com/2023.3/Documentation/Manual/job-system-copy-nativecontainer.html

NativeContainer 구조 복사 (Copying NativeContainer structures)

---

Native containers는 값 타입이기 때문에 변수에 할당될 때 Unity는 NativeContainer 구조체를 복사합니다.
Native containers are value types, which means that when they’re assigned to a variable, Unity copies the NativeContainer structure,

이 구조체에는 네이티브 컨테이너의 데이터가 저장된 위치를 가리키는 포인터와 함께 해당 컨테이너의 AtomicSafetyHandle도 포함되어 있습니다.
which contains pointers to where the native container’s data is stored, including its AtomicSafetyHandle.

하지만 전체 NativeContainer 내용을 복사하지는 않습니다.
It doesn’t copy the entire contents of the NativeContainer.

이러한 시나리오는 동일한 메모리 영역을 참조하는 여러 NativeContainer 구조체 사본이 있을 수 있으며,
모두 동일한 중앙 레코드를 참조하는 AtomicSafetyHandle 객체를 포함하고 있을 수 있음을 의미합니다.
This scenario means that there might be multiple copies of a NativeContainer structure which all reference the same region of memory,
and all contain AtomicSafetyHandle objects which reference the same central record.

위 다이어그램은 실제로 동일한 컨테이너를 나타내는 NativeArray 구조체의 세 가지 다른 복사본을 보여줍니다.
The above diagram shows three different copies of a NativeArray structure that all represent the same actual container.

각 복사본은 동일한 저장된 데이터와 원래 NativeArray와 동일한 안전성 데이터를 가리킵니다.
Each copy points to the same stored data, and the same safety data as the original NativeArray. 

그러나 각  NativeArray  복사본은 해당 복사본에서 작업을 수행할 수 있는 지를 나타내는 다른 플래그를 갖습니다.
However, each copy of the NativeArray has different flags that indicate what a job is allowed to do with that copy.

안전성 데이터에 대한 포인터와 플래그는 AtomicSafetyHandle를 구성합니다.
The pointer to the safety data, combined with the flags, make up the AtomicSafetyHandle.

버전 번호 (Version numbers)

만약 NativeContainer가 dispose(해제)되면 NativeContainer구조체의 모든 복사본은 기존의 NativeContainer가 무효임을 인식해야 합니다.
If a NativeContainer is disposed of, all the copies of the NativeContainer structure must recognize that the original NativeContainer is invalid.

원래 NativeContainer를 dispose하는 것은 NativeContainer의 데이터를 저장하던 메모리 블록이 할당 해제되었음을 의미합니다.
Disposing of the original NativeContainer means that the block of memory that used to hold the data for the NativeContainer has been deallocated.

이 상황에서 각 NativeContainer 복사본에 저장된 데이터에 대한 포인터는 무효화되어 있으며 사용 시 액세스 위반을 일으킬 수 있습니다.
In this situation, the pointer to the data which is stored in each copy of the NativeContainer is invalid, and might cause access violations if you use it.

또한 AtomicSafetyHandle는 무효화된 NativeContainer 인스턴스를 가리키는 중앙 레코드를 가리킵니다.
The AtomicSafetyHandle also points at a central record which becomes invalid for the NativeContainer instances.

그러나 safety system은 중앙 레코드의 메모리를 해제하지 않으므로 액세스 위반의 위험을 피할 수 있습니다.
However, the safety system never deallocates the memory for the central record, so it avoids the risk of access violations.

대신, 각 레코드에는 버전 번호가 포함되어 있습니다.
Instead, each record contains a version number.

버전 번호의 복사본은 해당 기록을 참조하는 각 AtomicSafetyHandle 안에 저장됩니다.
A copy of the version number is stored inside each AtomicSafetyHandle that references that record.

NativeContainer가 dispose되면 Unity는 Release()를 호출하며 이는 중앙 레코드의 버전 번호를 증가시킵니다.
When a NativeContainer is disposed of, Unity calls Release(), which increments the version number on the central record.

그 후 해당 레코드는 다른 NativeContainer 인스턴스에 재사용될 수 있습니다.
After this, the record can be reused for other NativeContainer instances.

남아 있는 각 AtomicSafetyHandle는 저장된 버전 번호를 중앙 레코드의 버전 번호와 비교하여 NativeContainer가 dispose되었는지를 테스트합니다.
Each remaining AtomicSafetyHandle compares its stored version number against the version number in the central record to test whether the NativeContainer has been disposed of.

Unity는 이 테스트를 자동으로 수행하여 CheckReadAndThrow, CheckWriteAndThrow 등의 메서드 호출 일부의 일환으로 처리합니다.
Unity performs this test automatically as part of calls to methods such as CheckReadAndThrow, and CheckWriteAndThrow.

동적 네이티브 컨테이너의 정적 보기 (Static views of dynamic native containers)

동적 NativeContainer는 계속해서 요소를 추가할 수 있는 변수 크기를 가진 컨테이너로, Collections 패키지에서 제공되는 NativeList<T>와 같은 예시가 있습니다.
A dynamic native container is one which has a variable size that you can continue to add elements to, such as NativeList<T> (which is available in the Collections package).

이는 크기를 변경할 수 없는 고정 크기의 NativeArray<T>와 같은 정적 NativeContainer 대조적입니다.
This is in contrast to a static native container like NativeArray<T>, which has a fixed size that you can’t change.

동적 네이티브 컨테이너를 사용할 때 뷰(view)라 불리는 다른 인터페이스를 통해 데이터에 직접 액세스할 수도 있습니다.
When you use a dynamic native container, you can also directly access its data through another interface, called a view.

뷰는 NativeContainer 객체의 데이터에 복사하거나 소유권을 얻지 않고 별칭(alias)을 제공합니다.
A view allows you to alias a NativeContainer object’s data without copying or taking ownership of the data.

뷰의 예시로는 열거자(enumerator) 객체가 있습니다.
Examples of views include enumerator objects,

이를 사용하여 네이티브 컨테이너의 데이터에 요소별로 액세스할 수 있으며 NativeList<T>.AsArray와 같은 메서드를 사용하여 NativeList를 NativeArray처럼 처리할 수 있습니다.
which you can use to access the data in a native container element-by-element, and methods such as NativeList<T>.AsArray, which you can use to treat a NativeList as if it were a NativeArray.

그러나 동적 네이티브 컨테이너의 크기가 변경되면 뷰가 일반적으로 스레드 안전하지 않습니다.
Views aren’t typically thread safe if the size of the dynamic native container changes.

이는 NativeContainer 의 크기가 변경되면 Unity가 메모리에서 데이터를 재배치하고,
This is because when the size of the native container changes, Unity relocates where the data is stored in memory,

이로 인해 뷰가 저장하는 포인터가 무효화되기 때문입니다.
which causes any pointers that a view stores to become invalid.

보조 버전 번호 (Secondary version numbers)

동적 네이티브 컨테이너의 크기가 변경되는 상황을 지원하기 위해 안전성 시스템은 AtomicSafetyHandle 에 보조 버전 번호를 포함합니다.
To support situations when the size of the dynamic native container changes, the safety system includes a secondary version number in an AtomicSafetyHandle.

이 메커니즘은 버전 관리 메커니즘과 유사하지만 첫 번째 버전 번호와 독립적으로 증가시킬 수 있는 중앙 레코드에 저장된 두 번째 버전 번호를 사용합니다.
This mechanism is similar to the versioning mechanism, but uses a second version number stored in the central record which can be incremented independently of the first version number.

보조 버전 번호를 사용하려면 UseSecondaryVersion을 사용하여 NativeContainer에 저장된 데이터에 대한 뷰를 구성할 수 있습니다.
To use a secondary version number, you can use UseSecondaryVersion to configure the views into the data stored in a NativeContainer.

NativeContainer의 크기를 변경하거나 기존 뷰를 무효화하는 작업에 대해 CheckWriteAndThrow 대신 CheckWriteAndBumpSecondaryVersion을 사용합니다.
For operations that change the size of the native container, or otherwise make existing views invalid, use CheckWriteAndBumpSecondaryVersion instead of CheckWriteAndThrow.

또한 NativeContainer에 SetBumpSecondaryVersionOnScheduleWrite를 설정하여 NativeContainer에 쓰기 작업이 예약될 때마다 자동으로 뷰를 무효화해야 합니다.
You also need to set SetBumpSecondaryVersionOnScheduleWrite on the NativeContainer to automatically invalidate views whenever a job is scheduled that writes to the native container.

뷰를 만들고 AtomicSafetyHandle를 복사할 때는 CheckGetSecondaryDataPointerAndThrow 를 사용하여 NativeContainer의 메모리 포인터를 뷰로 안전하게 복사할 수 있는지 확인합니다.
When you create a view and copy the AtomicSafetyHandle to it, use CheckGetSecondaryDataPointerAndThrow to confirm that it’s safe to copy the pointer to the native container’s memory into the view.

특수 손잡이 (Special handles)

임시 네이티브 컨테이너를 사용할 때 두 가지 특수한 핸들이 있습니다 :
There are two special handles, which you can use when working with temporary native containers:

• GetTempMemoryHandle :
  Allocator.Temp 으로 할당된 NativeContainer에서 사용할 수 있는 AtomicSafetyHandle을 반환합니다.
  Returns an AtomicSafetyHandle which you can use in native containers which are allocated with Allocator.Temp.
  Unity는 현재 임시 메모리 범위가 종료될 때 이 핸들을 자동으로 무효화하므로 직접 해제할 필요가 없습니다.
  Unity automatically invalidates this handle when the current temporary memory scope exits, so you don’t need to release it yourself.
  특정 AtomicSafetyHandle이 GetTempMemoryHandle에서 반환된 핸들인지 테스트하려면 IsTempMemoryHandle을 사용합니다.
  To test whether a particular AtomicSafetyHandle is the handle returned by GetTempMemoryHandle, use IsTempMemoryHandle.
• GetTempUnsafePtrSliceHandle:
  안전하지 않은 메모리에서 지원되는 임시 네이티브 컨테이너에 사용할 수 있는 전역 핸들을 반환합니다.
  Returns a global handle you can use for temporary native containers which are backed by unsafe memory.
  예를 들어, 스택 메모리에서 생성된 NativeSlice 입니다.
  For example, a NativeSlice constructed from stack memory.
  이 핸들을 사용하는 컨테이너를 작업에 전달할 수 없습니다.
  You can’t pass containers that use this handle into jobs.

https://docs.unity3d.com/2023.3/Documentation/Manual/job-system-custom-nativecontainer-example.html

사용자 정의 NativeContainer 예제 (Custom NativeContainer example)

---

NativeContainer다음은 추가 전용 목록인 사용자 정의의 전체 예입니다 .
The following is a complete example of a custom NativeContainer as an append-only list.

읽기 및 쓰기 작업의 기본 보호는 물론 앨리어싱 뷰 생성 및 무효화를 보여줍니다.
It demonstrates basic protection of read and write operations, as well as creating and invalidating aliasing views.

다른 예는 NativeContainerAttribute API 설명서를 참조하세요.
For another example, see the NativeContainerAttribute API documentation.

using System;
using System.Runtime.InteropServices;
using Unity.Collections.LowLevel.Unsafe;
using Unity.Collections;

// NativeContainer로 구조체를 표시합니다. 이는 job 시스템에 AtomicSafetyHandle이 포함되어 있음을 나타냅니다.
[NativeContainer]
public unsafe struct NativeAppendOnlyList<T> : IDisposable where T : unmanaged
{
    // 원시 포인터는 일반적으로 job에 전달되는 구조체 내에서 허용되지 않지만, 안전 시스템으로 보호되므로 이 제한을 해제할 수 있습니다.
    [NativeDisableUnsafePtrRestriction]
    internal void* m_Buffer;
    internal int m_Length;
    internal Allocator m_AllocatorLabel;

    // ENABLE_UNITY_COLLECTIONS_CHECKS 정의로만 안전 시스템 멤버를 선언하고 사용해야 합니다.
    // 프로젝트의 최종 빌드에서는 성능상의 이유로 안전 시스템이 비활성화되므로 이러한 API는 해당 빌드에서 사용할 수 없습니다.
#if ENABLE_UNITY_COLLECTIONS_CHECKS

    // AtomicSafetyHandle 필드는 'm_Safety'로 정확히 명명되어야 합니다.
    internal AtomicSafetyHandle m_Safety;

    // 이 유형을 해당 유형에서 파생된 이름을 사용하여 정적으로 안전 시스템에 등록합니다.
    internal static readonly int s_staticSafetyId = AtomicSafetyHandle.NewStaticSafetyId<NativeAppendOnlyList<T>>();
#endif

    public NativeAppendOnlyList(Allocator allocator, params T[] initialItems)
    {
        m_Length = initialItems.Length;
        m_AllocatorLabel = allocator;

        // 초기 버퍼의 크기(바이트)를 계산하고 할당합니다.
        int totalSize = UnsafeUtility.SizeOf<T>() * m_Length;
        m_Buffer = UnsafeUtility.MallocTracked(totalSize, UnsafeUtility.AlignOf<T>(), m_AllocatorLabel, 1);

        // 배열에서 데이터를 버퍼로 복사합니다.
        var handle = GCHandle.Alloc(initialItems, GCHandleType.Pinned);
        try
        {
            UnsafeUtility.MemCpy(m_Buffer, handle.AddrOfPinnedObject().ToPointer(), totalSize);
        }
        finally
        {
            handle.Free();
        }

#if ENABLE_UNITY_COLLECTIONS_CHECKS
        // AtomicSafetyHandle 및 DisposeSentinel 생성
        m_Safety = AtomicSafetyHandle.Create();

        // AtomicSafetyHandle에 안전 ID 설정하여 오류 메시지가 이 컨테이너 유형을 올바르게 설명하도록 함
        AtomicSafetyHandle.SetStaticSafetyId(ref m_Safety, s_staticSafetyId);

        // 이 컨테이너가 중첩 컨테이너인지 확인하고 중첩 컨테이너 플래그 설정
        if (UnsafeUtility.IsNativeContainerType<T>())
            AtomicSafetyHandle.SetNestedContainer(m_Safety, true);
#endif
    }

    public int Length
    {
        get
        {
#if ENABLE_UNITY_COLLECTIONS_CHECKS
            // 컨테이너에 대한 정보를 읽을 수 있는지 확인합니다.
            // 이는 원시 컨테이너에서 읽을 수 없거나 네이티브 컨테이너가 해제된 경우 InvalidOperationException을 throw합니다.
            AtomicSafetyHandle.CheckReadAndThrow(m_Safety);
#endif
            return m_Length;
        }
    }

    public T this[int index]
    {
        get
        {
#if ENABLE_UNITY_COLLECTIONS_CHECKS
            // 현재 네이티브 컨테이너에서 읽을 수 있는지 확인합니다.
            AtomicSafetyHandle.CheckReadAndThrow(m_Safety);
#endif

            // 버퍼에서 값을 읽어 반환합니다.
            return UnsafeUtility.ReadArrayElement<T>(m_Buffer, index);
        }

        set
        {
#if ENABLE_UNITY_COLLECTIONS_CHECKS
            // 현재 네이티브 컨테이너에 쓸 수 있는지 확인합니다.
            AtomicSafetyHandle.CheckWriteAndThrow(m_Safety);
#endif
            // 값을 버퍼에 씁니다.
            UnsafeUtility.WriteArrayElement(m_Buffer, index, value);
        }
    }

    public void Add(T value)
    {
#if ENABLE_UNITY_COLLECTIONS_CHECKS
        // 현재 네이티브 컨테이너를 수정(쓰기)할 수 있는지 확인하고 그렇다면 보조 버전을 증가시켜서
        // 뷰가 무효화되도록 합니다. 왜냐하면 크기와 버퍼에 대한 포인터를 변경할 것이기 때문입니다.
        AtomicSafetyHandle.CheckWriteAndBumpSecondaryVersion(m_Safety);
#endif

        // 현재 버퍼를 원소 하나를 추가할 공간이 있는 새로운 버퍼로 교체합니다.
        int newTotalSize = (m_Length + 1) * UnsafeUtility.SizeOf<T>();
        void* newBuffer = UnsafeUtility.MallocTracked(newTotalSize, UnsafeUtility.AlignOf<T>(), m_AllocatorLabel, 1);
        UnsafeUtility.MemCpy(newBuffer, m_Buffer, m_Length * UnsafeUtility.SizeOf<T>());
        UnsafeUtility.FreeTracked(m_Buffer, m_AllocatorLabel);
        m_Buffer = newBuffer;

        // 새 원소를 버퍼 끝에 넣고 길이를 증가시킵니다.
        UnsafeUtility.WriteArrayElement(m_Buffer, m_Length++, value);
    }

    public NativeArray<T> AsArray()
    {
#if ENABLE_UNITY_COLLECTIONS_CHECKS
        // 현재 버퍼 포인터를 사용하여 뷰를 만들 수 있는지 안전하게 확인합니다.
        AtomicSafetyHandle.CheckGetSecondaryDataPointerAndThrow(m_Safety);

        // AtomicSafetyHandle의 복사본을 만들고 해당 복사본을 기본 대신 보조 버전을 사용하도록 표시합니다.
        AtomicSafetyHandle handleForArray = m_Safety;
        AtomicSafetyHandle.UseSecondaryVersion(ref handleForArray);
#endif

        // 현재 크기를 사용하여 버퍼에 별칭을 설정하는 새 NativeArray를 만듭니다.
        // 이 작업은 데이터를 할당하거나 복사하지 않고 현재 버퍼를 가리키는 NativeArray<T>를 설정합니다.
        var array = NativeArrayUnsafeUtility.ConvertExistingDataToNativeArray<T>(m_Buffer, m_Length, Allocator.None);

#if ENABLE_UNITY_COLLECTIONS_CHECKS
        // 새로 만든 NativeArray에 AtomicSafetyHandle을 설정합니다. 설정한 핸들은 앞서 복사한 핸들을 사용합니다.
        NativeArrayUnsafeUtility.SetAtomicSafetyHandle(ref array, handleForArray);
#endif

        return array;
    }

    public void Dispose()
    {
#if ENABLE_UNITY_COLLECTIONS_CHECKS
        AtomicSafetyHandle.CheckDeallocateAndThrow(m_Safety);
        AtomicSafetyHandle.Release(m_Safety);
#endif

        // 버퍼를 해제합니다.
        UnsafeUtility.FreeTracked(m_Buffer, m_AllocatorLabel);
        m_Buffer = null;
        m_Length = 0;
    }
}

using UnityEngine;
using Unity.Collections;
using Unity.Jobs;

// Job adding two floating point values together
public struct MyJob : IJob
{
    public float a;
    public float b;
    public NativeArray<float> result;

    public void Execute()
    {
        result[0] = a + b;
    }
}

using UnityEngine;
using Unity.Collections;
using Unity.Jobs;

public class MyScheduledJob : MonoBehaviour
{
    // 결과를 저장할 단일 float의 NativeArray 를 생성합니다.
    // NativeArray만이 작업 결과를 얻을 수 있는 유일한 방법입니다 
    // 하나의 값 또는 일련의 값을 얻게 됩니다.
    NativeArray<float> result;
    // Create a JobHandle for the job
    JobHandle handle;

    // Set up the job
    public struct MyJob : IJob
    {
        public float a;
        public float b;
        public NativeArray<float> result;

        public void Execute()
        {
            result[0] = a + b;
        }
    }

    // 업데이트는 프레임당 1회 호출
    void Update()
    {
        // Set up the job data
        result = new NativeArray<float>(1, Allocator.TempJob);

        MyJob jobData = new MyJob
        {
            a = 10,
            b = 10,
            result = result
        };

        // Schedule the job
        handle = jobData.Schedule();
    }

    private void LateUpdate()
    {
        // 나중에 프레임에서 작업이 완료될 때까지 기다렸다가 결과에 액세스합니다.
        handle.Complete();

        // NativeArray의 모든 복사본은 동일한 메모리를 가리키며, 
        // NativeArray의 "당신의" 복사본에서 결과에 액세스할 수 있습니다
        // float aPlusB = result[0];

        // 할당된 메모리를 해제합니다.
        result.Dispose();
    }
}

MyParallelJob jobData = new MyParallelJob();
jobData.Data = someData;  
jobData.Result = someArray;  

/ 사용 가능한 워커 쓰레드의 절반을 사용하되, 최소 1개의 워커 쓰레드로 제한합니다
const int numBatches = Math.Max(1, JobsUtility.JobWorkerCount / 2); 
const int totalItems = someArray.Length;
const int batchSize = totalItems / numBatches;

// 작업을 예약하고 결과 배열의 각 인덱스에 대해 하나의 Execute 및 batchSize 항목을 처리합니다
JobHandle handle = jobData.Schedule(result.Length, totalItems, batchSize);

JobHandle firstJobHandle = firstJob.Schedule();
secondJob.Schedule(firstJobHandle);

NativeArray<JobHandle> handles = new NativeArray<JobHandle>(numJobs, Allocator.TempJob);

// Populate `handles` with `JobHandles` from multiple scheduled jobs...

JobHandle jh = JobHandle.CombineDependencies(handles);

using UnityEngine;
using Unity.Collections;
using Unity.Jobs;

public class MyDependentJob : MonoBehaviour
{
    // 결과를 저장할 하나의 float를 담는 NativeArray 생성. 이 예제는 작업이 완료될 때까지 기다립니다.
    NativeArray<float> result;
    // 결과에 액세스하기 위한 JobHandle 생성
    JobHandle secondHandle;

    // 첫 번째 작업 설정
    public struct MyJob : IJob
    {
        public float a;
        public float b;
        public NativeArray<float> result;

        public void Execute()
        {
            result[0] = a + b;
        }
    }

    // 값에 1을 더하는 두 번째 작업 설정
    public struct AddOneJob : IJob
    {
        public NativeArray<float> result;

        public void Execute()
        {
            result[0] = result[0] + 1;
        }
    }

    // 매 프레임마다 호출되는 업데이트 메서드
    void Update()
    {
        // 첫 번째 작업에 대한 작업 데이터 설정
        result = new NativeArray<float>(1, Allocator.TempJob);

        MyJob jobData = new MyJob
        {
            a = 10,
            b = 10,
            result = result
        };

        // 첫 번째 작업 예약
        JobHandle firstHandle = jobData.Schedule();

        // 두 번째 작업에 대한 데이터 설정
        AddOneJob incJobData = new AddOneJob
        {
            result = result
        };

        // 두 번째 작업 예약
        secondHandle = incJobData.Schedule(firstHandle);
    }

    private void LateUpdate()
    {
        // 프레임 내 나중에 작업이 완료될 때까지 대기
        secondHandle.Complete();

        // NativeArray의 모든 복사본이 동일한 메모리를 가리키므로 "당신의" NativeArray 복사본에서 결과에 액세스할 수 있습니다.
        // float aPlusBPlusOne = result[0];

        // 결과 배열이 할당한 메모리 해제
        result.Dispose();
    }
}

https://docs.unity3d.com/2023.3/Documentation/Manual/JobSystemParallelForJobs.html

병렬 작업 (Parallel jobs)

---

schedule a job 할 때는 한 번에 하나의 작업만이 특정 작업을 수행할 수 있습니다.
When you schedule a job there can only be one job doing one task.

그러나 많은 객체에서 동일한 작업을 수행해야 하는 경우가 있습니다.
However, there will be times where you need to perform the same operation on a lot of objects.

이런 경우에는 IJobParallelFor에서 파생된 ParallelFor 작업 유형을 사용합니다.
To do this, use a ParallelFor job type, which inherits from IJobParallelFor.

ParallelFor 작업은 데이터 원본으로 NativeArray를 사용합니다. ParallelFor 작업은 여러 CPU 코어에서 실행됩니다.
A ParallelFor job uses a NativeArray of data to act on as its data source. ParallelFor jobs run across multiple CPU cores.

각 코어 당 하나의 작업이 있으며 각 작업은 작업 부하의 일부를 처리합니다.
There’s one job per core, with each handling a subset of the workload.

IJobParallelFor는 IJob과 유사하지만 단일 Execute 메서드 대신 데이터 원본의 각 항목당 한 번씩 Execute 메서드를 호출합니다.
IJobParallelFor behaves like IJob, but instead of a single Execute method, it invokes the Execute method once per item in the data source.

Execute 메서드에는 데이터 소스 내의 단일 요소에 액세스하고 작업을 수행할 수 있는 정수 매개변수 index도 있습니다.
There’s also an integer parameter index in the Execute method, which you can use to access and operate on a single element of the data source within the job implementation.

다음은 ParallelFor 작업 정의의 예시입니다 :
The following is an example of a ParallelFor job definition:

struct IncrementByDeltaTimeJob: IJobParallelFor
{
    public NativeArray<float> values;
    public float deltaTime;

    public void Execute (int index)
    {
        float temp = values[index];
        temp += deltaTime;
        values[index] = temp;
    }
}

ParallelFor 작업 예약 (Schedule a ParallelFor job)

ParallelFor 작업을 예약하려면 사용할 NativeArray 데이터 소스의 길이를 지정해야 합니다.
To schedule a ParallelFor job, you must specify the length of the NativeArray data source that you want to split.

구조체에 여러 개가 있을 경우 데이터 소스로 사용할 NativeArray를 작업 시스템이 알 수 없습니다..
The job system doesn’t know which NativeArray you want to use as the data source if there are several in the struct.

길이는 또한 작업 시스템에게 기대할 Execute 메서드의 수를 알려줍니다.
The length also tells the job system how many Execute methods to expect.

In Unity’s native code, the scheduling of ParallelFor jobs is more complicated.
유니티의 네이티브 코드에서 ParallelFor 작업을 예약하는 것은 더 복잡합니다.

유니티가 ParallelFor 작업을 예약하면 작업 시스템은 작업을 코어 간에 분배하기 위해 작업을 일련의 배치로 나눕니다.
When Unity schedules a ParallelFor job, the job system divides the work into batches to distribute between cores.

각 배치에는 Execute 메서드의 하위 집합이 포함되어 있습니다.
Each batch contains a subset of Execute methods.

그런 다음 job system은 유니티의 네이티브 작업 시스템에서 CPU 코어 당 하나의 작업을 예약하고 해당 네이티브 작업을 배치에 전달하여 완료합니다.
The job system then schedules one job in Unity’s native job system per CPU core and passes that native job to the batches to complete.

다른 Native 작업보다 네이티브 작업이 일부 배치를 먼저 완료하면 남은 배치를 다른 네이티브 작업에서 빼앗아 갑니다.
When a native job completes its batches before others, it steals remaining batches from the other native jobs.

이 때 캐시 지역성을 보장하기 위해 네이티브 작업의 남은 배치의 절반만을 한 번에 빼앗습니다.
It only steals half of a native job’s remaining batches at a time, to ensure cache locality.

이 프로세스를 최적화하려면 배치 카운트를 지정해야 합니다.
To optimize the process, you need to specify a batch count.

배치 카운트는 얼마나 많은 작업을 얻을지 및 스레드 간 작업 재분배가 얼마나 미세한지를 제어합니다.
The batch count controls how many jobs you get, and how fine-grained the redistribution of work between threads is.

낮은 배치 카운트(예: 1)는 스레드 간 작업을 균등하게 분배합니다.
Having a low batch count, such as 1, gives you an even distribution of work between threads.

그러나 이에는 어느 정도의 오버헤드가 따르므로 때로는 배치 수를 늘리는 것이 더 나을 수 있습니다.
However, it comes with some overhead, so sometimes it’s better to increase the batch count.

1에서 시작하여 성능 향상이 미미할 때까지 배치 수를 늘리는 것이 좋은 전략입니다.
Starting at 1 and increasing the batch count until there are negligible performance gains is a good strategy.

다음은 ParallelFor 작업을 예약하는 예시입니다.
The following is an example of scheduling a ParallelFor job

Job code:

// Job adding two floating point values together
public struct MyParallelJob : IJobParallelFor
{
    [ReadOnly]
    public NativeArray<float> a;
    [ReadOnly]
    public NativeArray<float> b;
    public NativeArray<float> result;

    public void Execute(int i)
    {
        result[i] = a[i] + b[i];
    }
}

Main thread code:

NativeArray<float> a = new NativeArray<float>(2, Allocator.TempJob);

NativeArray<float> b = new NativeArray<float>(2, Allocator.TempJob);

NativeArray<float> result = new NativeArray<float>(2, Allocator.TempJob);

a[0] = 1.1;
b[0] = 2.2;
a[1] = 3.3;
b[1] = 4.4;

MyParallelJob jobData = new MyParallelJob();
jobData.a = a;
jobData.b = b;
jobData.result = result;

// 결과 배열의 각 인덱스에 대해 하나의 Execute로 작업을 예약하고 각 처리 배치당 항목은 1개
JobHandle handle = jobData.Schedule(result.Length, 1);

// 작업이 완료될 때까지 기다립니다.
handle.Complete();

// 배열에 할당된 메모리를 해제합니다.
a.Dispose();
b.Dispose();
result.Dispose();

ParallelForTransform jobs

ParallelForTransform 작업은 Transforms에 특화된 또 다른 ParallelFor 작업 유형입니다.
A ParallelForTransform job is another type of ParallelFor job designed specifically for operating on Transforms.

이는 작업에서 Transform 작업을 효율적으로 수행하는 데 유용합니다.
It’s useful for working on Transform operations from jobs efficiently.

더 많은 정보는 ParallelForTransform API 문서를 참조하세요.
For more information, see the ParallelForTransform API documentation.

https://docs.unity3d.com/2023.3/Documentation/ScriptReference/Jobs.IJobParallelForTransform.html

IJobParallelForTransform

interface in UnityEngine.Jobs

Job에 전달된 모든 변환의 위치, 회전 및 크기에 대해 동일한 독립적인 작업을 수행할 수 있도록 하는 인터페이스입니다.
An interface that allows you to perform the same independent operation for each position, rotation and scale of all the transforms passed into a job.

using UnityEngine;
using Unity.Collections;
using Unity.Jobs;
using UnityEngine.Jobs;

class ApplyVelocitySample : MonoBehaviour
{
    public struct VelocityJob : IJobParallelForTransform
    {
        // 작업에서 액세스될 모든 데이터를 선언합니다.
        // 읽기 전용으로 선언함으로써 여러 작업에서 데이터에 병렬로 액세스할 수 있습니다.
        [ReadOnly]
        public NativeArray<Vector3> velocity;

        // 작업에서 프레임 개념이 일반적으로 없기 때문에 델타 타임을 작업으로 복사해야 합니다.
        // 메인 스레드는 동일한 프레임이나 다음 프레임에 작업을 기다리지만,
        // 작업은 작업자 스레드에서 실행되는 시점에 상관없이 작업을 결정적으로 수행해야 합니다.
        public float deltaTime;

        // 작업에서 실제로 실행되는 코드
        public void Execute(int index, TransformAccess transform)
        {
            // 델타 타임과 속도를 기반으로 변환을 이동시킵니다.
            var pos = transform.position;
            pos += velocity[index] * deltaTime;
            transform.position = pos;
        }
    }

    // 작업에서 조작할 변환을 인스펙터에서 할당합니다.
    [SerializeField] public Transform[] m_Transforms;
    TransformAccessArray m_AccessArray;

    void Awake()
    {
        // 변환을 TransformAccessArray 인스턴스에 저장하여 작업에서 액세스할 수 있도록 합니다.
        m_AccessArray = new TransformAccessArray(m_Transforms);
    }

    void OnDestroy()
    {
        // TransformAccessArrays는 수동으로 Dispose해야 합니다.
        m_AccessArray.Dispose();
    }

    public void Update()
    {
        var velocity = new NativeArray<Vector3>(m_Transforms.Length, Allocator.Persistent);

        for (var i = 0; i < velocity.Length; ++i)
            velocity[i] = new Vector3(0f, 10f, 0f);

        // 작업 데이터 초기화
        var job = new VelocityJob()
        {
            deltaTime = Time.deltaTime,
            velocity = velocity
        };

        // 병렬로 변환 작업을 예약합니다.
        // 이 메서드는 작업에서 조작할 변환을 포함하는 TransformAccessArray를 취합니다.
        JobHandle jobHandle = job.Schedule(m_AccessArray);

        // 작업이 완료되었는지 확인합니다.
        // 작업을 즉시 완료하면 이와 병렬로 다른 작업이 실행될 가능성이 감소합니다.
        // 작업을 프레임 초반에 예약하고 나중에 프레임에서 기다리는 것이 좋습니다.
        jobHandle.Complete();

        Debug.Log(m_Transforms[0].position);

        // Native 배열은 수동으로 Dispose해야 합니다.
        velocity.Dispose();
    }
}

The post Unity Manual / Job system (2023.3) 번역 appeared first on 어제와 내일의 나 그 사이의 이야기.

A failure occurred while executing com.android.build.gradle.internal.tasks.workers$actionfacade

유니티로 빌드할 때 발생하는 오류입니다.

원인은 Keystore의 비밀번호가 올바르지 않은 경우에 발생합니다.

The post Error) A failure occurred while executing com.android.build.gradle.internal.tasks.workers$actionfacade appeared first on 어제와 내일의 나 그 사이의 이야기.

Snap Interactions

https://developer.oculus.com/documentation/unity/unity-isdk-snap-interaction/

Snap interactions allow items to automatically snap to poses in the environment.
스냅 상호 작용을 사용하면 항목이 환경의 포즈에 자동으로 스냅될 수 있습니다.

The DistanceGrabExample scene uses them to simply have the items snap back to their original position when not in use,
but it is possible to create custom behaviors so the objects snap to inventories, cells in a board game, slots around the user body, etc.
DistanceGrabExample 씬은 사용하지 않을 때 단순히 아이템을 원래 위치로 되돌리기 위해 이를 사용하지만,
오브젝트가 인벤토리, 보드 게임의 셀, 사용자 몸 주위의 슬롯 등에 스냅되도록 커스텀 동작을 만들 수 있습니다.

SnapInteractor

The SnapInteractor is the Interactor class for this interaction.
SnapInteractor는 이 상호 작용에 대한 Interactor 클래스입니다.

This component is placed in the item that we want to be able to snap, e.g. a chess piece,
and will take care of detecting nearby SnapInteractables and move the item towards the best available pose provided by them.
이 컴포넌트는 스냅할 수 있는 아이템(예: 체스 말)에 배치되며,
근처의 SnapInteractables를 감지하고 아이템이 제공하는 최상의 포즈로 아이템을 이동합니다.

When the Optional TimeOutInteractable and TimeOut are provided,
the Interactor will automatically move to said interactable after TimeOut seconds
if the Grabbable is not being Selected or Hovered by any other interactor.

선택적 TimeOutInteractable 및 TimeOut이 제공되면 다른 인터랙터가
Grabbable을 선택하거나 가리키지 않는 경우 인터랙터는 TimeOut(초) 후에 자동으로 해당 인터랙터로 이동합니다.

SnapInteractable

The SnapInteractable component is the Interactable class for this interaction.
SnapInteractable 구성 요소는 이 상호 작용에 대한 Interactable 클래스입니다.

When used as-is it provides a single pose in space to which the interactors can snap too, but optionally it can be enhanced in several ways.
있는 그대로 사용하면 상호 작용자가 스냅할 수 있는 공간에서 단일 포즈를 제공하지만 선택적으로 여러 가지 방법으로 향상시킬 수 있습니다.

Trigger collider

when a Trigger volume is present in the same gameobject,
Interactors entering the volume will be tracked and automatically snap to the interactable pos as soon as their state becomes equal to Normal.
트리거 볼륨이 동일한 게임 오브젝트에 있는 경우 볼륨에 진입하는 인터랙터가 추적되고
상태가 Normal이 되는 즉시 상호 작용 가능한 위치에 자동으로 스냅됩니다.

MovementProvider

by referencing a MovementProvider the method for snapping can be fully customized.
MovementProvider를 참조하여 스냅 메서드를 완전히 사용자 지정할 수 있습니다.

By default the interactor will follow the slot at a fixed speed, but following the different MovementProvider it could trace a curve, add easing, etc.
기본적으로 인터랙터는 고정된 속도로 슬롯을 따라가지만 다른 MovementProvider를 따라 커브를 추적하고 부드럽게를 추가하는 등의 작업을 수행할 수 있습니다.

SnapPosesProvider

the ISnapPoseProvider interface allows creating multiple poses within a SnapInteractable.
ISnapPoseProvider 인터페이스를 사용하면 SnapInteractable 내에서 여러 포즈를 만들 수 있습니다. 

Implementing and providing this interface is useful for using a single SnapInteractable for all the cells within a board in a board game,
or to define all the different slots in an inventory system, allowing to even move snapped items when hovering new interactors to make room.
이 인터페이스를 구현하고 제공하면 보드 게임의 보드 내의 모든 셀에 대해 단일 SnapInteractable을 사용하거나 인벤토리 시스템에서 모든 다른 슬롯을 정의하는 데 유용하며,
공간을 만들기 위해 새 상호 작용기를 마우스로 가리킬 때 스냅된 항목을 이동할 수도 있습니다.

using UnityEngine;

namespace Oculus.Interaction
{
    /// <summary>
    /// SnapPoseDelegate는 맞춤형 SnapPose 로직을 제공하는 데 사용할 수 있습니다
    /// 추적되거나 스냅되는 요소 집합이 주어집니다.
    /// </summary>
    public interface ISnapPoseDelegate
    {
        /// <summary>
        /// 새 요소가 추적 중임을 나타냅니다.
        /// </summary>
        /// <param name="id">추적할 요소 ID입니다.</param>
        /// <param name="params">요소의 포즈입니다.</param>
        void TrackElement(int id, Pose p);
        /// <summary>
        /// 요소가 더 이상 추적되지 않음을 나타냅니다.
        /// </summary>
        /// <param name="id">추적을 중지할 요소 ID입니다.</param>
        void UntrackElement(int id);
        /// <summary>
        /// 추적된 요소가 스냅되어야 함을 나타냅니다.
        /// </summary>
        /// <param name="id">스냅할 요소 ID입니다.</param>
        /// <param name="params">요소의 포즈입니다.</param>
        void SnapElement(int id, Pose pose);
        /// <summary>
        /// 요소가 더 이상 스냅되지 않아야 함을 나타냅니다.
        /// </summary>
        /// <param name="id">스냅을 중지할 요소 ID입니다.</param>
        void UnsnapElement(int id);
        /// <summary>
        /// 추적된 요소 포즈가 업데이트되었음을 나타냅니다.
        /// </summary>
        /// <param name="id">요소 ID.</param>
        /// <param name="params">새로운 요소 포즈.</param>
        void MoveTrackedElement(int id, Pose p);
        /// <summary>
        /// 쿼리된 요소 ID에 대한 대상 스냅 포즈입니다.
        /// </summary>
        /// <param name="id">요소 ID.</param>
        /// <param name="params">타깃 포즈.</param>
        /// <returns>요소에 스냅할 포즈가 있으면 참입니다.</returns>
        bool SnapPoseForElement(int id, Pose pose, out Pose result);
    }
}

The post Oculus Unity-Integration – Snap Interactions appeared first on 어제와 내일의 나 그 사이의 이야기.

이론이 필요없고 적용하는 과정이 궁금하다면 아래글로

Oculus Hand Pose Detection

https://developer.oculus.com/documentation/unity/unity-isdk-hand-pose-detection/?ref=blog.immersive-insiders.com

Hand Pose Detection uses multiple components and configurators to detect hand poses.
손 포즈 감지는 여러 컴포넌트와 구성 요소를 사용하여 손의 동작을 감지하는 기술입니다.

A hand pose is defined by shapes and transforms.
이를 판단하기 위해 형태(shape)와 변환(transform)이라는 두 가지 요소를 사용합니다.

Shapes are boolean conditions about the required position of the hand’s finger joints.
형태는 손가락 관절의 위치에 대한 부울 조건을 나타냅니다.

Transforms are boolean conditions about the required orientation of the hand in the world space.
Transform은 세계 공간에서 손의 요구되는 방향에 대한 bool 조건입니다.

A pose is detected when the tracked hand matches that pose’s required shapes and transforms.
추적된 손이 해당 포즈의 요구 형태와 Transform이 일치할 때 포즈가 감지됩니다.

This topic explains poses, shape and transform recognition, and the criteria used to determine if a pose is detected.
이 글에서는 포즈, 형태 및 Transform 인식, 그리고 포즈가 감지되는지 여부를 결정하는 기준에 대해 설명합니다.

It also describes debug components you can use to visually debug poses.
시각적으로 포즈를 디버깅하기 위해 사용할 수 있는 debug components에 대해서도 설명합니다.

To learn how to detect a hand pose, see Build a Hand Pose Recognizer. (나중에 링크)
손 포즈를 감지하는 방법을 알아보려면 “손 포즈 인식기 만들기”를 참조하세요.

Pose Prefabs

Interaction SDK includes 6 ready to use example pose prefabs.
Interaction SDK에는 6개의 준비된 예제 포즈 프리팹이 포함되어 있습니다.

You can define your own poses using the patterns defined in these prefabs.
이러한 프리팹에서 정의된 패턴을 사용하여 직접 포즈를 정의할 수 있습니다.

You can experiment with pose detection using these pose prefabs in the PoseExamples sample scene.
PoseExamples 샘플 씬에서 이러한 포즈 prefab을 사용하여 포즈 감지를 실험해 볼 수 있습니다.

• RockPose
• PaperPose
• ScissorsPose
• ThumbsUpPose
• ThumbsDownPose
• StopPose

Each pose prefab has these components:
각 pose prefab에는 다음과 같은 구성 요소가 있습니다

A HandRef is a component that takes an IHand as input.
이 HandRef는 IHand를 입력 값으로 받는 component입니다.

The other components on this prefab will read hand state via this reference.
이 프리팹의 다른 컴포넌트들은 이 참조를 통해 손의 상태를 읽습니다.

ShapeRecognizerActiveState is a component that becomes active when the criteria of a specified Shape is met.
ShapeRecognizerActiveState는 지정된 형태의 조건이 충족되면 활성화되는 component입니다.

TransformRecognizerActive is a component that becomes active when a transform feature, such as a particular wrist orientation, is detected.
TransformRecognizerActive은 특정 손목 방향과 같은 변환 기능이 감지되었을 때 활성화되는 component입니다.

ActiveStateGroup is a component that returns true when all dependent ActiveStates are true.
ActiveStateGroup은 종속적인 ActiveState가 모두 true일 때 true를 반환하는 컴포넌트입니다.

ActiveStateSelector and SelectorUnityEventWrapper are components that can invoke events when a pose is detected.
ActiveStateSelector와 SelectorUnityEventWrapper는 포즈가 감지되었을 때 이벤트를 호출할 수 있는 component입니다.

A pose includes required transforms (which are bundled in TransformRecognizerActiveState) and shapes (which are bundled in ShapeRecognizerActiveState).
한 pose에는 필요한 transforms(이는 TransformRecognizerActiveState에서 묶여 있음)와 shapes(이는 ShapeRecognizerActiveState에서 묶여 있음)가 포함됩니다.

These are combined using ActiveStateGroup to define the pose.
이들은 ActiveStateGroup을 사용하여 결합되어 pose를 정의합니다.

wrist up => 손목을 위로 향하게

ShapeRecognizer

Poses include one or more shapes.
포즈에는 하나 이상의 형태가 포함됩니다.

A shape is a set of boolean conditions about the position of one or more fingers.
형태는 하나 이상의 손가락 위치에 대한 boolean 조건의 집합입니다.

The conditions are defined using Finger Features states.
이러한 조건은 Finger Features 상태를 사용하여 정의됩니다.

If a tracked hand meets these conditions, then the shape becomes active.
추적된 손이 이러한 조건을 충족하면 형태가 활성화됩니다.

If all the shapes in the pose are active and the transform is also active, the pose is detected.
포즈의 모든 형태가 활성화되고 변형도 활성화된 경우, 포즈가 감지됩니다.

A pose’s shapes are stored as ShapeRecognizer assets in the pose’s ShapeRecognizerActiveState component.
포즈의 형태는 포즈의 ShapeRecognizerActiveState component에 저장되는 ShapeRecognizer 자산으로 저장됩니다.

ShapeRecognizerActiveState

ShapeRecognizerActiveState takes a hand, the current state of the hand’s fingers, and a list of shape configs.
ShapeRecognizerActiveState 는 손, 손 손가락의 현재 상태 및 셰이프 구성 목록을 사용합니다.

To get the current state of the fingers, it uses the method to retrieve the FingerFeatureStateProvider component from the hand.
손가락의 현재 상태를 가져오기 위해 이 메서드를 사용하여 손에서 FingerFeatureStateProvider 구성 요소를 검색합니다.

If the state of every finger matches the states in the listed shapes, ShapeRecognizerActiveState becomes active. 
모든 손가락의 상태가 나열된 도형의 상태와 일치하면 ShapeRecognizerActiveState가 활성화됩니다.

ShapeRecognizerActiveState implements the IActiveState interface.GetHandAspect
Shape RecognizerActiveState는 the IActiveState interface.GetHandAspect를 구현합니다

ShapeRecognizer

ShapeRecognizer is a that defines a shape.
ShapeRecognizer는 도형을 정의하는 것입니다.

To define a shape, it uses a set of rules called Feature Configs.
 shape를 정의하기 위해 Feature Configs라는 rules을 사용합니다.

Feature Configs specify a required position (state) for each of the five fingers.
기능 구성은 다섯 손가락 각각에 필요한 위치(상태)를 지정합니다.

Feature Configs define state using at least one of the Finger Features: Curl, Flexion, Abduction, and Opposition. 
기능 구성은 손가락 기능(Curl, Flexion, Abduction, Opposition) 중 하나 이상을 사용하여 상태를 정의합니다.

ShapeRecognizer is referenced by the ShapeRecognizerActiveState component to determine if a pose is active.ScriptableObject
ShapeRecognizer는 ShapeRecognizerActiveState 구성 요소에서 참조하여 포즈가 활성 상태인지 확인합니다.ScriptableObject

FingerFeatureStateProvider

Finger Feature State Provider provides the finger states of the tracked hands and contains the state transition thresholds for each finger.
손가락 기능 상태 공급자는 추적된 손의 손가락 상태를 제공하고 각 손가락에 대한 상태 전환 임계값을 포함합니다.

It’s referenced by the ShapeRecognizerActiveState component.
ShapeRecognizerActiveState 구성 요소에서 참조합니다.

FingerFeatureStateThresholds

FingerFeatureStateThresholds is a that defines the state thresholds for each Finger Feature.
FingerFeatureStateThresholds는 각 손가락 특징에 대한 상태 임계값을 정의하는 것입니다.

A state threshold is a set of boundaries that determine when a finger has transitioned between states.
 state threshold 는 손가락이 상태 간에 전환된 시기를 결정하는 경계 집합입니다. 

For example, the curl feature has 3 states: Open, Neutral, and Closed.
예를 들어 curl 기능에는 3가지 상태(Open, Neutral 및 Closed)가 있습니다.

So the state thresholds for curl use an angle in degrees to define when the finger’s state has changed from Open to Neutral, Neutral to Closed, or vice-versa.ScriptableObject
따라서 curl의 상태 임계값은 각도(도)를 사용하여 손가락의 상태가 열림에서 보통으로, 보통에서 닫힘으로 또는 그 반대로 변경된 시기를 정의합니다.ScriptableObject

Interaction SDK provides four sets of default state thresholds, which are under :DefaultSettings/PoseDetection
Interaction SDK는 아래에 있는 4개의 기본 상태 임계값 집합을 제공합니다.DefaultSettings/PoseDetection

• DefaultThumbFeatureStateThresholds (for the thumb)(엄지 손가락의 경우)
• IndexFingerFeatureStateThresholds (for the Index finger)(집게 손가락의 경우)
• MiddleFingerFeatureStateThresholds (for the Middle finger)(가운데 손가락의 경우)
• DefaultFingerFeatureStateThresholds (for the Ring & Pinky fingers)(약지 및 새끼손가락용)

The thumb’s curl state threshold.
엄지 손가락의 curl 상태 임계값입니다.

For curl, the value is an angle in degrees.
curl의 경우 값은 각도(도)입니다.

FingerFeatureStateThresholds Example

Given the transition between two states, A <> B:
두 상태 간의 전환할 때 A<> B는 다음과 같습니다.

If the current state is “A”, to transition up to “B” then the angle must rise above the midpoint for that pairing by at least (width / 2.0) for “Min Time In State” seconds.
현재 상태가 “A”인 경우 “B”로 전환하려면 각도가 “Min Time In State” 초 동안 해당 페어링의 중간점 이상으로 최소(너비/2.0) 상승해야 합니다.

If the current state is “B”, to transition down to “A” then the angle must drop below the midpoint for that pairing by at least (width / 2.0) for “Min Time In State” seconds.
현재 상태가 “B”인 경우 “A”로 전환하려면 각도가 “Min Time In State” 초 동안 해당 페어링의 중간점 아래로 최소(너비 / 2.0) 떨어져야 합니다.

So for Curl, to transition:
따라서 Curl의 경우 전환하려면 다음을 수행하십시오:

• From Open > Neutral: value must be above 195 for 0.0222 seconds
• From Neutral > Open: value must be below 185 for 0.0222 seconds
• From Neutral > Closed: value must be above 210 for 0.0222 seconds
• From Closed > Neutral: value must be below 200 for 0.0222 seconds

• 개방에서 중립>: 값은 195.0초 동안 0222보다 커야 합니다.
• 중립에서 시>까지: 값은 185.0초 동안 0222 미만이어야 합니다.
• 중립에서 닫힘으로>: 값은 210.0초 동안 0222보다 커야 합니다.
• 닫힘에서 중립>: 값은 200.0초 동안 0222 미만이어야 합니다.

Finger Features

Finger Features are specific finger positions that let you define a shape. There are four features:
손가락 기능은 모양을 정의할 수 있는 특정 손가락 위치입니다. 네 가지 기능이 있습니다.

• Curl
• Flexion
• Abduction
• Opposition

Curl

Represents how bent the top two joints of the finger or thumb are.
손가락 또는 엄지손가락의 위쪽 두 관절이 얼마나 구부러졌는지를 나타냅니다.

This feature doesn’t take the Proximal (knuckle) joint into consideration.
이 기능은 근위부(너클) 조인트를 고려하지 않습니다.

States:

• Open: Fingers are fully extended straight.
• Neutral: Fingers are slightly curled inwards, as if they were wrapped around a coffee mug.
• Closed (pictured): Fingers are tightly curled inwards such that the tips are almost touching the palm.

• 열림: 손가락을 완전히 똑바로 뻗습니다.
• 중립: 손가락이 마치 커피 머그잔을 감싼 것처럼 안쪽으로 약간 말려 있습니다.
• 닫힘 (사진) : 손가락이 안쪽으로 단단히 말려서 끝이 손바닥에 거의 닿을 정도입니다.

The joints used to measure the curl feature.
컬 형상을 측정하는 데 사용되는 조인트.

Flexion

The extent that the Proximal (knuckle) joint is bent.
근위부(너클) 관절이 구부러진 정도. 

Flexion is only reliable on the 4 fingers.
굴곡은 4개의 손가락에서만 신뢰할 수 있습니다.  (엄지 X )

It can provide false positives on the thumb.
이것은 엄지 손가락에 잘못된 긍정을 제공 할 수 있습니다.

States:

• Open: The first bone on the fingers is fully extended and is parallel to the palm.
• Neutral: Somewhat bent.
• Closed: Knuckle joint is fully bent (pictured).

• 열림: 손가락의 첫 번째 뼈가 완전히 확장되고 손바닥과 평행합니다.
• 중립: 약간 구부러져 있습니다.
• 닫힘: 너클 조인트가 완전히 구부러져 있습니다(사진).

Warning

Flexion is only reliable on the 4 fingers.
굴곡은 4개의 손가락에서만 신뢰할 수 있습니다.

It can provide false positives on the thumb.
엄지 손가락에 잘못된 긍정을 제공 할 수 있습니다.

An example of flexion where the knuckle joint is in the Closed state.
너클 관절이 닫힌 상태인 굴곡의 예.

Abduction

The angle between two adjacent fingers, measured at the base of those two fingers.
인접한 두 손가락 사이의 각도로, 두 손가락의 밑면에서 측정됩니다.

Abduction measures the angle between the given finger and the adjacent finger that’s closer to the pinky.
외전은 주어진 손가락과 새끼 손가락에 더 가까운 인접한 손가락 사이의 각도를 측정합니다.

For example, Abduction for the index finger is the angle between the index and middle finger.
예를 들어, 집게 손가락의 외전은 집게 손가락과 가운데 손가락 사이의 각도입니다.

States:

• Open The two fingers are spread apart (pictured for index).
• Closed: The two fingers are tightly compressed together (pictured for thumb, middle, ring).
• None: Not currently used.

• 열다 두 손가락이 벌어져 있습니다(인덱스 사진).
• 닫힘: 두 손가락이 함께 단단히 압축됩니다(엄지, 가운데, 반지 사진).
• 없음: 현재 사용되지 않습니다.

Note

Abduction on Pinkie is not supported.
핑키의 외전은 지원되지 않습니다. (새끼 손가락)

An example of abduction.
The index finger is in the Open state.
집게 손가락이 열린 상태입니다.

The thumb, middle, and ring fingers are in the Closed state.
엄지, 중지, 약지가 닫힌 상태입니다.

Opposition

How close a given fingertip is to the thumb tip.
주어진 손가락 끝이 엄지 손가락 끝에 얼마나 가까운지.

Can only be used on index, middle, ring, and pinky fingers.
검지, 중지, 약지, 새끼손가락에만 사용할 수 있습니다.

States:

• Touching: The fingertip joints are within ~1.5cm (pictured for index).
• Near: The fingertip joints are between ~1.5cm and ~15cm apart.
• None: The fingertip joints are greater than ~15cm apart.

• 만지기: 손가락 끝 관절은 ~1.5cm 이내입니다(인덱스 사진).
• 근거리: 손가락 끝 관절은 ~1.5cm에서 ~15cm 떨어져 있습니다.
• 없음: 손가락 끝 관절이 ~15cm 이상 떨어져 있습니다.

An example of opposition. The index finger is in the Touching state.
반대의 예. 집게 손가락이 Touching 상태입니다.

Transform Recognition

Poses consist of one or more transforms.
포즈는 하나 이상의 변환으로 구성됩니다.

The transform of the hand only represents the orientation and position.
손의 변형은 방향과 위치만 나타냅니다.

The orientation is only evaluated relative to the WristUp, WristDown, PalmDown, PalmUp, PalmTowardsFace, PalmsAwayFromFace, FingersUp, FingersDown, and PinchClear transforms.
방향은 WristUp, WristDown, PalmDown, PalmUp, PalmTowardsFace, PalmsAwayFromFace, FingersUp, FingersDown 및 PinchClear 변환을 기준으로만 평가됩니다.

A pose’s required transforms are listed in the pose’s TransformRecognizerActiveState component.
포즈의 필수 변환은 포즈의 TransformRecognizerActiveState 구성 요소에 나열됩니다. 

During hand tracking, the hand’s transforms are compared to the pose’s transforms.
핸드 트래킹 중에 손의 변형이 포즈의 변형과 비교됩니다.

If both sets of transforms match and all the shapes in the pose are active, then the pose is detected.
두 변환 집합이 모두 일치하고 포즈의 모든 shape가 활성 상태이면 포즈가 감지됩니다.

The axes that define the hand’s fingers, wrist, and palm.
손의 손가락, 손목 및 손바닥을 정의하는 축입니다.

TransformRecognizerActiveState

TransformRecognizerActiveState takes a hand, the current state of the hand’s transforms, and a list of transform feature configs, and a transform config.
TransformRecognizerActiveState 는 손 변환의 현재 상태, 변환 기능 구성 목록 및 변환 구성을 사용합니다.

To get the current state of the hand’s transforms, it uses the method to retrieve the TransformFeatureStateProvider component.
손 변환의 현재 상태를 가져오기 위해 method를 사용하여 TransformFeatureStateProvider 구성 요소를 검색합니다.

That component reads the raw feature values and quantizes them into TransformFeatureStates using the Transform Config you provide in this component.GetHandAspect
이 구성 요소는 raw 기능 값을 읽고 이 구성 요소에서 제공하는 변환 구성을 사용하여 TransformFeatureStates로 정량화 합니다.GetHandAspect

TransformFeatureStateProvider

TransformFeatureStateProvider provides the transform states of the tracked hand.
TransformFeatureStateProvider는 추적된 손의 변환 상태를 제공합니다.

It’s referenced by the TransformRecognizerActiveState component.
TransformRecognizerActiveState 구성 요소에서 참조합니다.

TransformConfig

Transform Config influences state transitions computed via TransformFeatureStateProvider.
변환 구성은 TransformFeatureStateProvider를 통해 계산된 상태 전환에 영향을 줍니다.

It implements the IActiveState interface and becomes active whenever all of the listed transform states are active.
IActiveState 인터페이스를 구현하고 나열된 모든 변환 상태가 활성화될 때마다 활성화됩니다.

Its Feature Thresholds property takes a , TransformFeatureStateThresholds, that defines the transform feature thresholds for each orientation.
해당 Feature Thresholds 속성은 각 방향에 대한 변환 기능 임계값을 정의하는 TransformFeatureStateThresholds를 사용합니다.

The transform feature thresholds use the same properties as the FingerFeatureStateThresholds.ScriptableObject
변환 기능 임계값은 FingerFeatureStateThresholds와 동일한 속성을 사용합니다.ScriptableObject

Note

Once you register a specific configuration, the method can then query the state of each state tracked for configuration.
특정 구성을 등록하면 메서드는 구성을 위해 추적된 각 상태의 상태를 쿼리할 수 있습니다.

It leverages FeatureStateProvider to drive state-changing logic.RegisterConfig
FeatureStateProvider를 활용하여 상태 변경 논리를 구동합니다.RegisterConfig

Velocity Recognition

Velocity recognition components detect motion, whereas shape recognition only detects static poses.
속도 인식 구성 요소는 동작을 감지하는 반면 모양 인식은 정적 포즈만 감지합니다.

For example, shape recognition can detect a hand in a thumbs-up pose,
예를 들어 모양 인식은 엄지손가락을 위로 올리는 포즈에서 손을 감지할 수 있지만

but cannot determine if the hand is moving upward while in that pose.
해당 포즈에서 손이 위로 움직이는지 여부는 확인할 수 없습니다.

There are two velocity recognition components.
속도 인식 구성 요소에는 두 가지가 있습니다. 

Both components get joint data from the JointDeltaProvider component.
두 구성 요소 모두 JointDeltaProvider 구성 요소에서 조인트 데이터를 가져옵니다.

• JointVelocityActiveState tracks velocities (position deltas over the last two frames) for a list of joints and compares them to a velocity target along the provided axes.
  JointVelocityActiveState는 조인트 목록에 대한 속도(마지막 두 프레임에 대한 위치 델타)를 추적하고 제공된 축을 따라 속도 목표와 비교합니다. 
  
  If the velocity target (units per second) is met for the minimum time threshold, the state becomes Active.
  속도 목표(초당 단위)가 최소 시간 임계값에 충족되면 상태가 활성이 됩니다.
• JointRotationActiveState tracks angular velocities (rotation deltas over the last two frames) for a list of joints and compares them to a rotation target around the provided axes.
  JointRotationActiveState는 조인트 목록에 대한 각속도(마지막 두 프레임의 회전 델타)를 추적하고 제공된 축 주위의 회전 대상과 비교합니다.
  
  If the rotation target (degrees per second) is met for the minimum time threshold, the state becomes Active.
  최소 시간 임계값에 대해 회전 목표(초당 도)가 충족되면 상태가 활성이 됩니다.

Sequences

IActiveState components can be chained together using the Sequence component.
IActiveState 구성 요소는 Sequence 구성 요소를 사용하여 함께 연결할 수 있습니다. 

Because Sequences can recognize a series of IActiveStates over time, they can be used to compose complex gestures.
시퀀스는 시간이 지남에 따라 일련의 IActiveStates를 인식할 수 있으므로 복잡한 제스처를 작성하는 데 사용할 수 있습니다.

For examples of complex gestures, see the GestureExamples sample scene.
복잡한 제스처의 예는 GestureExamples 샘플 장면을 참조하세요.

Sequence Classes

Sequence takes a list of ActivationSteps and iterates through them as they become active.
Sequence는 ActivationSteps의 목록을 가져와서 활성화될 때 반복합니다.

Each ActivationStep consists of an IActiveState, a minimum active time, and a maximum step time.
ActivationStep은 IActiveState, 최소 활성 시간 및 최대 단계 시간으로 구성됩니다.

These steps function as follows:

• The IActiveState must be active for at least the minimum active time before the Sequence proceeds to the next step.
• If an IActiveState is active for longer than the maximum step time, the step will fail and the Sequence will restart.

• IActiveState는 시퀀스가 다음 단계로 진행하기 전에 최소 활성 시간 이상 활성 상태여야 합니다.
• IActiveState가 최대 단계 시간보다 오래 활성 상태이면 단계가 실패하고 시퀀스가 다시 시작됩니다.

Once the final ActivationStep in the Sequence has completed, the Sequence becomes active.
시퀀스의 마지막 ActivationStep이 완료되면 시퀀스가 활성화됩니다.

If an optional KeepActiveWhile IActiveState has been provided, the Sequence will remain active as long as KeepActiveWhile is active.
선택적 KeepActiveWhile IActiveState가 제공된 경우 KeepActiveWhile이 활성화되어 있는 한 시퀀스는 활성 상태로 유지됩니다.

The last phase of a Sequence is the optional cooldown phase, the duration of which can be set in the RemainActiveCooldown field.
시퀀스의 마지막 단계는 선택적 휴지 단계이며, 지속 시간은 RemainActiveCooldown 필드에서 설정할 수 있습니다.

A Sequence that is deactivating will wait for this cooldown timer to elapse before finally becoming inactive.
비활성화 중인 시퀀스는 이 재사용 대기시간 타이머가 경과할 때까지 기다렸다가 최종적으로 비활성화됩니다.

SequenceActiveState is an IActiveState wrapper for a Sequence, and can either report active once the Sequence has started, once the Sequence steps have finished, or both.
SequenceActiveState는 시퀀스에 대한 IActiveState 래퍼이며, 시퀀스가 시작되거나, 시퀀스 단계가 완료되거나, 둘 다 활성으로 보고될 수 있습니다.

Debugging Pose Recognition (포즈 인식 디버깅)

The following classes let you visually debug elements of the pose recognition system.
다음 클래스를 사용하면 포즈 인식 시스템의 요소를 시각적으로 디버깅할 수 있습니다.

ActiveStateDebugTree

Builds a visual representation of an IActiveState tree on a UI canvas, based on a provided root IActiveState.
제공된 루트 IActiveState를 기반으로 UI 캔버스에서 IActiveState 트리의 시각적 표현을 빌드합니다.

Two different node layout types are provided, ActiveStateDebugTreeHorizontal (for a left-to-right representation) and **ActiveStateDebugTreeVertical **(for a more compact top to bottom tree view).
ActiveStateDebugTreeHorizontal(왼쪽에서 오른쪽 표현용) 및 ActiveStateDebugTreeVertical(보다 간결한 위에서 아래쪽 트리 보기)의 두 가지 노드 레이아웃 유형이 제공됩니다.

FingerFeatureSkeletalDebugVisual

Uses a line renderer to indicate if a finger feature is active on a specific finger (green) or not (red).
라인 렌더러를 사용하여 손가락 기능이 특정 손가락에서 활성화되어 있는지(녹색) 또는 활성화되지 않았는지(빨간색)를 나타냅니다.

HandShapeSkeletalDebugVisual

Creates a series of FingerFeatureSkeletalDebugVisuals for the features belonging to a ShapeRecognizerActiveState.
ShapeRecognizerActiveState에 속하는 기능에 대한 일련의 FingerFeatureSkeletalDebugVisuals를 만듭니다.

TransformFeatureDebugVisual

Changes the color of a target renderer to green if the specific TransformFeatureState is active; red if not.
특정 TransformFeatureState가 활성 상태인 경우 대상 렌더러의 색을 녹색으로 변경합니다. 그렇지 않은 경우 빨간색.

TransformFeatureVectorDebugParentVisual

Creates vector debug views for the FeatureStates belonging to a TransformRecognizerActiveState; one vector for the feature and another vector for the hand.
TransformRecognizerActiveState에 속하는 FeatureStates에 대한 벡터 디버그 뷰를 만듭니다. 하나의 벡터는 기능에 대한 것이고 다른 하나는 손에 대한 벡터입니다.

When both vectors are visualized, one can see how close the (blue) hand vector is to the (black) feature vector that it is being tested against in TransformFeatureValueProvider.
두 벡터를 모두 시각화하면 손 벡터(파란색)가 TransformFeatureValueProvider에서 테스트 중인 (검은색) 기능 벡터에 얼마나 가까운지 확인할 수 있습니다.

TransformFeatureVectorDebugVisual

Uses a line renderer to visualize a simple vector.
라인 렌더러를 사용하여 간단한 벡터를 시각화합니다.

TransformRecognizerDebugVisual

Creates a series of TransformFeatureDebugVisuas to visually debug the TransformFeatureStates belonging to a collection of TransformRecognizerActiveState.
TransformRecognizerActiveState 컬렉션에 속하는 TransformFeatureStates를 시각적으로 디버깅하기 위해 일련의 TransformFeatureDebugVisuas를 만듭니다.

This allows one to visually debug the active state of each transform feature via the created instances of TransformFeatureDebugVisual.
이렇게 하면 TransformFeatureDebugVisual의 생성된 인스턴스를 통해 각 변환 기능의 활성 상태를 시각적으로 디버그할 수 있습니다.

JointRotationDebugVisual

Renders lines along the rotation axes tracked by the JointRotationActiveState.
JointRotationActiveState에 의해 추적되는 회전 축을 따라 선을 렌더링합니다.

Lines are red while not rotating along that axis, and they fill up yellow as rotation amount increases toward the target, at which point they become green.
선은 해당 축을 따라 회전하지 않는 동안 빨간색으로 표시되며, 대상을 향해 회전량이 증가함에 따라 노란색으로 채워지며, 이때 녹색이 됩니다.

JointVelocityDebugVisual

Renders lines along the velocity axes tracked by the JointVelocityActiveState.
JointRotationActiveState에 의해 추적되는 회전 축을 따라 선을 렌더링합니다. 

Lines are red while not moving along that axis, and they fill up yellow as velocity increases toward the target, at which point they become green.
선은 해당 축을 따라 회전하지 않는 동안 빨간색으로 표시되며, 대상을 향해 회전량이 증가함에 따라 노란색으로 채워지며, 이때 녹색이 됩니다.

Internal Implementation Classes

The classes described here implement the underlying functionality, but will not need to be modified in order to use Pose Recognition.
여기에 설명된 클래스는 기본 기능을 구현하지만 포즈 인식을 사용하기 위해 수정할 필요는 없습니다.

FeatureStateProvider

A generic helper class that keeps track of the current state of features, and uses thresholds to determine state changes.
기능의 현재 상태를 추적하고 임계값을 사용하여 상태 변경을 확인하는 제네릭 도우미 클래스입니다.

The class uses buffers to state changes to ensure that features do not switch rapidly between states.
이 클래스는 버퍼를 사용하여 상태 변경이 상태 간에 빠르게 전환되지 않도록 합니다.

FeatureStateThresholdsEditor

A generic editor class that defines the look and feel of dependent editor classes such as FingerFeatureStateThresholdsEditor and TransformStatesThresholdsEditor.
FingerFeatureStateThresholdsEditor 및 TransformStatesThresholdsEditor와 같은 종속 편집기 클래스의 모양과 느낌을 정의하는 제네릭 편집기 클래스입니다.

FeatureDescriptionAttribute

Lets you define editor-visible descriptions and hints and values to aid users in setting thresholds for features.
사용자가 기능에 대한 임계값을 설정하는 데 도움이 되도록 편집기에서 볼 수 있는 설명과 힌트 및 값을 정의할 수 있습니다.

IFeatureStateThreshold

IFeatureStateThreshold is a generic interface that defines the functionality of all thresholds used in hand pose detection.
IFeatureStateThreshold는 손 자세 감지에 사용되는 모든 임계값의 기능을 정의하는 제네릭 인터페이스입니다.

IFeatureStateThresholds

Defines a collection of IFeatureStateThresholds, specific to a feature type, whether that is finger features or transform features.
손가락 기능이든 변환 기능이든 기능 형식과 관련된 IFeatureStateThresholds의 컬렉션을 정의합니다.

IFeature Thresholds

Provides an interface to a collection of IFeatureStateThresholds as well as MinTimeInState (i.e. a minimum threshold of time a feature can be in a certain state before transitioning to another state).
IFeatureStateThresholds 및 MinTimeInState 컬렉션에 대한 인터페이스를 제공합니다(즉, 다른 상태로 전환하기 전에 기능이 특정 상태에 있을 수 있는 최소 임계값).

ColliderContainsHandJointActiveState

An IActiveState that tests to see if a hand joint is inside a collider.
손 관절이 콜라이더 내부에 있는지 테스트하는 IActiveState입니다.

If a SphereCollider is specified then its radius is used for checking, otherwise the script relies on the collider’s bounds.
SphereCollider가 지정되면 해당 반경이 검사에 사용되고, 그렇지 않으면 스크립트가 콜라이더의 경계에 의존합니다. 

This class is useful in case a developer wishes to see if the hand joint exists within a certain volume when a pose is active.
이 클래스는 개발자가 포즈가 활성 상태일 때 손 관절이 특정 볼륨 내에 존재하는지 확인하려는 경우에 유용합니다.

HmdOffset

Can be attached to an object that needs to be anchored from the center eye.
중앙 눈에서 고정해야 하는 물체에 부착할 수 있습니다.

Position and rotation offsets can be specified, along with options to toggle the roll, pitch and yaw of the latter.
위치 및 회전 오프셋을 지정할 수 있으며, 후자의 롤, 피치 및 요를 토글하는 옵션도 지정할 수 있습니다.

One can combine this with a ColliderContainsHandJointActiveStateto position a collider relative to the center eye.
이를 ColliderContainsHandJointActiveState와 결합하여 중심 눈을 기준으로 콜라이더를 배치할 수 있습니다.

The post Oculus Unity-Integration – Hand Pose Detection appeared first on 어제와 내일의 나 그 사이의 이야기.

// Default
Debug.Log("Default");

Debug.Log("<color=white>White</color>");
Debug.Log("<color=grey>Grey</color>");
Debug.Log("<color=black>Black</color>");
Debug.Log("<color=red>Red</color>");
Debug.Log("<color=green>Green</color>");
Debug.Log("<color=blue>Blue</color>");
Debug.Log("<color=yellow>Yellow</color>");
Debug.Log("<color=cyan>Cyan</color>");
Debug.Log("<color=brown>Brown</color>");

// Hex Color
Debug.Log("<color=#fa56d6> Hex Color1 </color>");
Debug.Log("<color=#74fa56> Hex Color1 </color>");
Debug.LogFormat("<color=yellow> Yellow </color>" + "<color=black> Black </color>");

The post Unity – Debug.Log 색상 변경 appeared first on 어제와 내일의 나 그 사이의 이야기.