문제 상황

Unity 에디터의 Package Manager에서 Services Core 패키지가 빨간색 경고와 함께 “Invalid Signature” 표시

광고 초기화 실패(Gateway communication failure) 등의 문제가 발생

이는 패키지 자체의 손상이 아니라 Package Manager의 서명 검증 시스템 오류

오류의 의미와 영향

Package Manager의 서명 검증 실패

Unity Package Manager는 모든 패키지의 디지털 서명을 확인하는 검증 메커니즘을 가지고 있

“Invalid Signature”는 Package Manager의 서명 검증 로직이 정상적인 패키지를 잘못 거부하는 버그

실제 패키지는 정상이지만, Package Manager가 잘못된 판단을 내리고 있는 상태로 생각됨

Unity Ads 초기화 실패와의 연결

Services Core는 단순한 라이브러리가 아니라 Unity Ads를 포함한 모든 유니티 서비스의 핵심 패키지입니다.

이 패키지가 손상되면:

• Unity Ads 초기화 실패 Gateway communication failure 오류 발생 광고 로드 및 표시 불가 기타 Unity Services(Analytics, Crash Reporting 등) 동작 불능

해결 방법 (개인적인)

Package Manager 캐시 삭제

로컬에 저장된 손상된 패키지 캐시를 강제로 삭제

Unity 에디터를 완전히 종료합니다 다음 폴더로 이동:

• Windows: %AppData%/Local/Unity/cache/upm
• Mac: ~/Library/Caches/Unity/upm
• Linux: ~/.cache/unity/upm

upm 폴더 전체를 삭제합니다

Unity 에디터를 다시 열면 Package Manager가 서버에서 패키지를 새로 다운로드하고 서명을 다시 검증

주의: 이 작업은 안전하며, 폴더를 다시 열면 필요한 캐시가 자동으로 재생성됩니다.

Reset Packages to Defaults (마지막 수단)

프로젝트의 패키지 설정이 꼬인 경우 초기화가 필요합니다.

Unity 상단 메뉴: Help > Reset Packages to defaults 선택

확인 대화상자에서 “Yes” 클릭

프로젝트의 manifest.json이 기본값으로 되돌려집니다

주의: 이 작업은 프로젝트의 패키지 설정을 초기화하므로:

수동으로 추가했던 다른 패키지가 있다면 다시 설치해야 합니다

Packages/manifest.json 파일이 변경됩니다

The post Unity Package Manager “Invalid Signature” appeared first on 어제와 내일의 나 그 사이의 이야기.

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 어제와 내일의 나 그 사이의 이야기.

Serialization (직렬화) 개요

Serialization이란 객체 데이터를 바이트 스트림으로 변환하여 저장하거나 전송할 수 있도록 하는 과정

주 목적은 필요할 때 다시 개체로 만들 수 있도록 개체의 상태를 저장하는 것

반대로 Deserialization은 저장된 바이트 데이터를 다시 객체로 변환하는 과정입니다.

JSON, XML, YAML

일반적으로 많이 사용하는 데이터 직렬화 포맷들

1⃣ JSON (JavaScript Object Notation)

특징

가벼운 텍스트 기반 포맷
사람이 읽고 쓰기 쉬우며, 기계가 빠르게 처리 가능
대부분의 프로그래밍 언어에서 지원 (C#, Python, JavaScript 등)
키-값 쌍의 구조 (Dictionary, Object와 유사)

예제

{
  "name": "John",
  "age": 30,
  "skills": ["C#", "Unity", "Python"],
  "isDeveloper": true
}

장점

가볍고 속도가 빠름
대부분의 언어에서 지원
API 및 데이터 전송에 적합 (REST API, WebSockets 등)

단점

주석 지원이 안됨
XML이나 YAML보다 덜 유연함

2⃣ XML (eXtensible Markup Language)

특징

데이터 구조를 계층적으로 표현 (HTML과 유사)
사람이 읽을 수 있지만, JSON보다 길이가 김
다양한 도메인에서 사용 (문서 저장, 설정 파일, 웹 서비스 등)
<태그>를 이용한 구조화된 데이터 표현

예제

<Person>
    <Name>John</Name>
    <Age>30</Age>
    <Skills>
        <Skill>C#</Skill>
        <Skill>Unity</Skill>
        <Skill>Python</Skill>
    </Skills>
    <IsDeveloper>true</IsDeveloper>
</Person>

장점

데이터 구조가 명확함
주석 사용 가능 (<!– 주석 –>)
다양한 데이터 타입을 표현하기 적합

단점

JSON보다 크기가 크고, 가독성이 떨어짐
파싱 속도가 느림

3⃣ YAML (YAML Ain’t Markup Language)

특징

JSON과 유사하지만 더 간결한 문법을 가짐
들여쓰기를 이용한 계층 구조 (Python과 유사)
설정 파일에서 많이 사용 (Docker, Kubernetes, Unity Config 등)

예제

name: John
age: 30
skills:
  - C#
  - Unity
  - Python
isDeveloper: true

장점

사람이 읽기 쉬운 직관적인 문법
JSON보다 간결하여 가독성이 좋음
주석 (#) 사용 가능

단점

들여쓰기 실수로 인한 오류 발생 가능
파싱 속도가 JSON보다 느림

비교 정리

Unity에서는 JSON (JsonUtility, Newtonsoft.Json)이 가장 많이 사용되며, YAML은 Unity의 설정 파일 (.yml)에서 많이 활용됩니다.

형식	문법	가독성	속도	사용 사례
JSON	{ "key": "value" }	좋음	빠름	API, 데이터 저장
XML	<tag>value</tag>	중간	느림	문서 저장, 설정 파일
YAML	key: value (들여쓰기)	매우 좋음	중간	설정 파일, DevOps

Unity에서의 스크립트 직렬화 (Serialization in Unity)

1⃣ Unity에서 직렬화가 중요한 이유

Unity는 Inspector 창에서 데이터를 유지하거나 저장 시스템(예: PlayerPrefs, JSON, Binary 파일 등)에 데이터를 저장하기 위해 직렬화를 활용합니다.

씬(Scene) 저장 및 로드: Inspector에 입력한 값이 유지됨
ScriptableObject: 게임 데이터 관리
Save/Load 시스템: JSON 또는 Binary 직렬화를 활용하여 파일 저장

2⃣ Unity에서 직렬화 가능한 타입

https://docs.unity3d.com/6000.0/Documentation/Manual/script-serialization-rules.html

Unity는 특정 데이터 타입만 직렬화할 수 있도록 제한하고 있습니다.

직렬화 가능한 타입 (Serializable)

기본 데이터 타입: int, float, bool, string 등
Unity 기본 타입: 배열 & 리스트: int[], List<float> 등 (단, public 또는 [SerializeField] 필요)
사용자 정의 클래스 ([System.Serializable] 필요)
ScriptableObject

직렬화 불가능한 타입 (Non-Serializable)

딕셔너리(Dictionary)
다차원 배열 (int[,])
속성(Property) (getter/setter)
Static 변수 (static)
추상 클래스 & 인터페이스
델리게이트(Delegate), 이벤트(Event)

3⃣ Unity 직렬화 적용 방법

[SerializeField]

private 변수도 Inspector에서 보이도록 만들고, 직렬화 가능하게 합니다.

using UnityEngine;

public class Player : MonoBehaviour
{
    [SerializeField] private int health = 100;  // 직렬화됨 (Inspector에서 수정 가능)
    private int score = 0;  // 직렬화되지 않음 (Inspector에서 보이지 않음)
}

[SerializeField]를 사용하면 private 변수도 직렬화됨
하지만 static, const, readonly 변수는 직렬화되지 않음

[System.Serializable]

사용자 정의 클래스를 직렬화하려면 [System.Serializable]을 붙여야 합니다.

using UnityEngine;

[System.Serializable]  
public class Weapon
{
    public string name;
    public int damage;
}

public class Player : MonoBehaviour
{
    public Weapon myWeapon;  // Weapon 클래스가 직렬화되므로 Inspector에서 수정 가능
}

클래스를 System.Serializable로 만들면 Unity Inspector에서 확인 가능
하지만 Dictionary, Properties, Static 변수 등은 여전히 직렬화되지 않음

ScriptableObject

게임 데이터를 저장 및 관리하는 특수한 직렬화 객체

using UnityEngine;

[CreateAssetMenu(fileName = "New Weapon", menuName = "Weapon")]
public class WeaponData : ScriptableObject
{
    public string weaponName;
    public int damage;
}

씬(Scene)과 독립적으로 데이터 관리 가능
메모리 효율적 관리 가능 (오브젝트 풀링, 설정 저장 등)
런타임에서 수정된 값은 저장되지 않음 (Play 모드가 끝나면 초기화됨)

4⃣ Unity 직렬화와 JSON 활용

Unity에서 JSON 직렬화를 활용하면 데이터 저장 & 로드가 가능해집니다.

JsonUtility (빠르지만 제한적)

using UnityEngine;

[System.Serializable]
public class PlayerData
{
    public string name;
    public int level;
}

public class SaveLoadSystem : MonoBehaviour
{
    void Start()
    {
        PlayerData player = new PlayerData { name = "John", level = 10 };
        string json = JsonUtility.ToJson(player);
        Debug.Log(json);  // {"name":"John","level":10}

        PlayerData loadedPlayer = JsonUtility.FromJson<PlayerData>(json);
        Debug.Log(loadedPlayer.name);  // John
    }
}

빠름 & Unity 기본 지원
Dictionary, List<T> 같은 복잡한 자료형 지원 X

Newtonsoft.Json (더 강력한 JSON 직렬화)

Newtonsoft.Json 라이브러리를 사용하면 Dictionary, List, Interface 등도 직렬화 가능

using UnityEngine;
using Newtonsoft.Json;
using System.Collections.Generic;

public class PlayerData
{
    public string name;
    public int level;
    public Dictionary<string, int> inventory = new Dictionary<string, int>();
}

public class SaveLoadSystem : MonoBehaviour
{
    void Start()
    {
        PlayerData player = new PlayerData { name = "John", level = 10 };
        player.inventory.Add("Sword", 1);
        player.inventory.Add("Potion", 5);

        string json = JsonConvert.SerializeObject(player, Formatting.Indented);
        Debug.Log(json);

        PlayerData loadedPlayer = JsonConvert.DeserializeObject<PlayerData>(json);
        Debug.Log(loadedPlayer.inventory["Sword"]);  // 1
    }
}

Dictionary, List<T> 등 복잡한 자료형 지원
JsonUtility보다 속도가 느림
추가 라이브러리 설치 필요 (Newtonsoft.Json.dll)

The post Unity Serialization (직렬화) appeared first on 어제와 내일의 나 그 사이의 이야기.

Unity 6 - 6000.0.32f1
Visual Effect Graph - 17.0.3

URP_VFX_Learning_Templates (2)

11. TexIndex Attribute

VFX 아티스트들은 스프라이트 시트(Sprite Sheet) 를 자주 사용합니다.

이 VFX 예제는 출력(Output) 에서 UV 옵션 을 사용하여 스프라이트 시트 를 활용하는 방법을 보여줍니다.

또한 Flipbook 설정 을 구성하는 방법과 texIndex 속성 과의 관계를 설명합니다.

Covered Aspects:

• TexIndex Attribute
• UVs Mode
• Flipbook

12. Flipbook Mode

이 VFX는 Output(출력)의 UV 모드를 Flipbook으로 설정하여 스프라이트 시트를 사용하는 방법을 보여줍니다.

또한 Flipbook Blend Frames 사용법과 Flipbook Player Block의 기본적인 활용 방법을 설명합니다.

Flipbook Blend Frames 설정을 사용하면 프레임 간 보간(Interpolation)이 적용되어 부드러운 애니메이션 효과를 얻을 수 있습니다.

Covered Aspects:

• Flipbook Player
• UVs Mode
• TexIndex Attribute

13. Flipbook Blending

이 VFX는 일반적인 프레임 블렌딩(Frame Blending)과 모션 벡터(Motion Vectors)를 이용한 프레임 블렌딩의 차이를 보여줍니다.

모션 벡터 블렌딩(Motion Vector Blending)은 프레임 간 픽셀 이동 정보를 포함한 텍스처를 활용하여 프레임 간 부드러운 전환을 구현합니다.

이 방식은 플립북의 프레임 수를 줄이거나, 슬로우 모션(Slow Motion) 애니메이션을 구현할 때 유용합니다.

Covered Aspects:

• Flipbook Player
• UVs Mode
• TexIndex Attribute

일반적인 Blend Frame은 단순한 알파 블렌딩(Alpha Blending) 방식으로, 프레임 수가 부족할 경우 끊김 현상이 발생할 수 있음.

Flipbook Player를 사용하면 자동으로 TexIndex가 증가하며 애니메이션이 진행됨.

Motion Vector Blending을 사용하면 픽셀 이동 정보를 활용하여 더욱 부드러운 전환을 구현할 수 있음.

• 이 방법은 플립북 애니메이션의 프레임 수를 줄이면서도 부드러운 모션을 유지하는 데 유용함.

14. TexIndex Advanced

이 고급 VFX는 texIndex 속성을 창의적으로 활용하는 여러 시스템으로 구성되어 있습니다.

시간(Time), 노이즈(Noise), 심지어 파티클의 위치(Position)까지 사용하여

texIndex 속성을 제어하며, 이를 통해 생동감 있는 VFX를 만듭니다.

Covered Aspects:

• Flipbook UVs
• TexIndex Attribute
• Flipbook Player

15. Pivot Attribute

피벗 속성(Pivot Attribute) 은 출력 렌더(output render) 가 파티클 위치를 기준으로 어디에서 생성되는지 를 제어합니다.

기본적으로 피벗은 파티클의 중심(Position)에 위치하지만, X, Y, Z 축을 따라 이동(offset) 시킬 수 있습니다.

피벗을 오프셋하면 스케일(크기) 조정 및 회전(rotation) 시 보다 매력적인 움직임을 만들 수 있습니다.

Covered Aspects:

• Pivot Attribute
• Angle Attribute

16. Pivot Advanced

파티클의 피벗(Pivot) 을 제어하는 것은 자연스럽고 흥미로운 움직임을 구현하는 핵심 요소입니다.

이 VFX에서는 피벗을 조작하여 꽃잎, 잎사귀, 가시 등이 자연스럽게 배치 및 애니메이션되는 과정을 보여줍니다.

또한, Shader Graph와 VFX Graph의 연동을 통해 셰이더를 제어하는 방법도 시연합니다.

Covered Aspects:

• Pivot Attribute
• Shader Graph integration
• Activation Port

17. Sample Mesh

이 VFX는 메시 샘플링(Sample Mesh) 을 활용하여 파티클을 메시 표면에 생성 하고, 메시의 버텍스 색상(Vertex Color) 을 상속 하는 방법을 보여줍니다.

또한, 메시의 버텍스 색상에 앰비언트 오클루전(Ambient Occlusion, AO) 값을 미리 베이크(Bake) 해두었으며, 이를 이용해 파티클의 색상을 설정 합니다.

Covered Aspects:

• Mesh Sampling
• Sample Mesh Operator

The post URP VFX Learning Templates (2) appeared first on 어제와 내일의 나 그 사이의 이야기.

개념 정리

World

ECS에서 World는 Entity와 System 등을 관리하는 Container 역할

World는 특정 씬(Scene)에 종속되지 않고, 모든 ECS 데이터를 포함하여 관리한다.

World가 관리하는 핵심 구성 요소 4가지

• EntityManager → Entity와 Component관리
• Systems → ECS 시스템 실행 및 업데이트
• Archetypes → Entity 구조 저장 및 관리
• Queries → 특정 조건을 만족하는 Entity 검색

SubScene

SubScene은 씬(Scene) 내부에서 특정 ECS 데이터(Entity)를 포함하는 컨테이너 역할을 한다.

SubScene이 로드되면, 그 안의 GameObject들이 자동으로 Entity로 변환(Entity Conversion)되어 World에 등록

SubScene의 로드 과정

1. SubScene 로드 → SceneSystem이 SubScene을 World에 추가
2. GameObject → Entity 변환
3. EntityManager가 모든 Entity 관리
4. ECS 시스템이 해당 Entity 를 처리

World와 SubScene의 관계

World는 MainScene과 SubScene을 구분하지 않고, 모든 ECS 데이터를 포함하여 관리

SubScene이 로드되면 해당 오브젝트들이 ECS Entity로 변환되어 World에 등록됨

World 자체는 씬(Scene)을 직접적으로 관리하지 않지만, World가 관리하는 SceneSystem을 사용해 SubScene을 동적으로 로드/언로드할 수는 있음

즉, World 는 씬(Scene) 개념과 독립적이지만, SubScene과는 밀접한 관계를 가짐

World는 SubScene을 포함하는 상위 컨테이너인가?

Yes, 하지만 직접적인 포함 관계는 아님

World는 ECS 데이터를 관리하는 컨테이너이므로, SubScene에서 생성된 ECS 데이터(Entity, Component, System 등)는 결국 World에 포함됨.

하지만, Unity의 SubScene자체가 World의 일부는 아니다. (SubScene은 씬(Scene)의 일부, World는 ECS의 컨테이너)

서로 다른 World에서 같은 SubScene을 공유할 수 있을까?

일반적으로 Unity ECS에서는 SubScene은 하나의 World에 속하는 것이 원칙

특정한 방식으로 다른 World에서 동일한 SubScene을 공유하는 것도 가능할 수 있음

서로 다른 World에서 같은 SubScene을 공유하는 방법

1. 각 World에서 같은 SubScene을 개별적으로 로드

• 각 World가 동일한 SubScene을 독립적으로 로드하여 각각의 ECS 데이터를 가질 수 있음
• 서로 다른 World에 있지만, 동일한 형태의 ECS 데이터가 생성

2. Persistent Scene을 활용해 한 World에서 로드한 데이터를 다른 World가 참조

• 한 World에서 SubScene을 로드하고, 다른 World는 해당 데이터를 복사하거나 참조하도록 설계
• 예를 들어, 멀티플레이어 게임에서 서버 World와 클라이언트 World가 동일한 맵 데이터(SubScene)를 참조하는 방식
• 하지만, Unity ECS가 기본적으로 제공하는 기능은 아니므로 별도의 데이터 동기화 로직이 필요함.

3. Bake 시점에 SubScene의 ECS 데이터를 여러 World로 복사

• SubScene이 변환될 때(Bake), ECS 데이터를 특정 World가 아니라 여러 World에 분산해서 배치하는 방식도 가능
• EntityManager.CopyEntitiesFrom() 등을 사용하여 SubScene의 데이터를 한 World에서 다른 World로 복사 가능.
• Unity ECS가 기본적으로 지원하는 기능이 아니므로, 수동으로 구현해야 할 수도 있음.

SubScene 내의 Entity들이 서로 다른 World에 포함될 수 있을까?

Yes, 하지만 Unity ECS에서 기본적으로 지원하는 방식은 아님

특정한 방법을 사용하면 일부 Entity를 다른 World로 이동시키는 것은 가능함

일반적인 SubScene의 World 포함 방식

기본적으로 SubScene이 로드되면, 그 안의 모든 GameObject가 동일한 World로 변환(Bake)됨

즉, SubScene 내의 모든 Entity들은 한 개의 World에 속하는 것이 원칙

예제: 일반적인 SubScene 로드 과정

SceneSystem.LoadSceneAsync(world, subSceneEntity, loadParameters);

특정 World에서 SubScene을 로드함 → SubScene 내부의 Entity들이 해당 World에 포함됨

결과적으로 SubScene의 모든 Entity들은 동일한 World에 속하게 됨

특정 Entity만 다른 World에 포함시키는 방법

하지만, 특정한 방식으로 SubScene 내부의 Entity를 다른 World로 이동시키는 것도 가능

방법 1: 특정 Entity를 다른 World로 복사하기

SubScene이 로드된 후, 특정 Entity를 다른 World로 복사하는 방식

// 현재 World에서 Entity 가져오기
EntityManager entityManager = sourceWorld.EntityManager;
EntityQuery query = entityManager.CreateEntityQuery(ComponentType.ReadOnly<MyComponent>());

// 대상 World로 Entity 복사
EntityManager destinationManager = targetWorld.EntityManager;
NativeArray<Entity> entities = query.ToEntityArray(Allocator.Temp);
foreach (var entity in entities)
{
    Entity newEntity = destinationManager.Instantiate(entity);
}
entities.Dispose();

• 원본 Entity를 삭제하지 않으면 동일한 Entity가 두 개의 World에 존재할 수도 있음! → 원본을 삭제할지 여부를 잘 결정해야 함

방법 2: SubScene을 특정 World에서 로드한 후 일부 Entity만 다른 World에서 활용

• SubScene을 World A에서 로드
• 특정 Entity를 World B에서 참조할 수 있도록 설계
• EntityCommandBuffer 또는 CopyEntitiesFrom을 활용하여 데이터 이동 가능

targetWorld.EntityManager.CopyEntitiesFrom(sourceWorld.EntityManager, query);

• 하지만, 시스템(System)과 동작 방식이 달라질 수 있으므로 주의해야 함

The post ECS의 World와 SubScene의 관계 appeared first on 어제와 내일의 나 그 사이의 이야기.

Unity 6 - 6000.0.32f1
Visual Effect Graph - 17.0.3

URP_VFX_Learning_Templates

https://docs.unity3d.com/Packages/com.unity.visualeffectgraph@17.0/manual/index.html

1. Context&Flow

컨텍스트 및 데이터 흐름

VFX Graph에서 데이터 흐름이 어떻게 구성되는지 설명하고, 자주 사용되는 컨텍스트 블록을 개요로 제공

Covered Aspects:

• Data Flow (데이터 흐름)
• Context Block (컨텍스트 블록)

2. Spawn Context

이 VFX는 스폰 컨텍스트(Spawn Context) 와 관련된 정보를 제공하기 위한 것입니다.

스폰 컨텍스트란 무엇이며, Inspector에서 어떤 옵션을 설정할 수 있는지, 그리고 추가적으로 다음과 같은 정보를 포함합니다:

• 스폰 이벤트 속성(Spawn Event Attributes)이란 무엇인가?
• 스폰 이벤트 속성을 어떻게 설정하는가?
• 스폰 상태 연산자(Spawn State Operator)란 무엇인가?

Covered Aspects:

• Spawn Context
• Spawn Event Attributes
• Spawn State

3. Capacity Count

Capacity Count는 시스템의 파티클 메모리 할당(Memory allocation)에 사용됩니다.

이 값을 증가시키면 할당되는 메모리 양도 증가합니다.

이 용량은 최대 활성 입자 수(Max active particles) 로 볼 수 있습니다.

최대 살아있는 파티클 수에 최대한 가깝게 이 값을 설정하는 것이 좋은 방법입니다.

이 VFX는 Capacity가 무엇인지, 그리고 VFX Control을 사용하여 Capacity를 설정하는 방법을 설명합니다.

Covered Aspects:

• Capacity
• Memory allocation
• VFX Control

4. Multiple Outputs

• 출력(Context)에서 파티클을 렌더링하는 방식을 정의.
• 하나의 파티클 시스템에서 여러 개의 출력(Renderer)을 추가하여 다양한 표현 가능.
• 예: 빌보드 쿼드, 메시, 포인트, 데칼 등을 활용해 입자를 여러 방식으로 렌더링 가능.

Covered Aspects:

• Composition Mode (속성 조합 모드)
• Output Context (출력 컨텍스트)

5. Bounds

• Bounds(바운딩 박스)는 VFX가 카메라의 프러스텀(FOV) 안에 있을 때만 렌더링되도록 함.
• 바운드는 수동(Manual), 기록(Recorded), 자동(Automatic)으로 설정 가능.
• 컬링(Culling)을 활용하여 불필요한 연산을 줄여 성능 최적화 가능.

Covered Aspects:

• Bounds (바운드, 바운딩 박스 설정)
• Culling (컬링, 최적화 기법)

6. Orient Face Camera

출력이 쿼드(Quad), 메시(Mesh), 스트립(Strip) 등으로 설정된 경우, 우리는 종종 파티클의 기하학적 형태(Geometry)가 어떻게 배치되는지 제어해야 합니다.

파티클이 카메라를 바라보아야 할까요? 파티클의 전방(Forward) 방향과 위쪽(Up) 방향은 무엇일까요?

Orient 블록을 사용하면 다양한 모드를 통해 파티클의 방향을 쉽게 제어할 수 있습니다.

해당 예제는 “Face Camera Position” 모드를 사용하여 입자가 항상 카메라의 위치를 바라보도록 설정하였습니다.

Covered Aspects:

• Orient (정렬)
• AxisX, AxisY, AxisZ (축 설정)

7. Orient Fixed Axis

파티클의 출력(Quads, Meshes, Strips) 방식과 관계없이, 우리는 종종 파티클이 배치될 방향을 제어하고 싶습니다.

파티클가 카메라를 향해야 할까요?

파티클의 전방(Forward) 방향과 상향(Up-Axis)은 무엇인가요?

이때 Orient(정렬) 블록을 사용하면 쉽게 파티클의 방향을 설정할 수 있습니다.

이 예제에서는 “Fixed Axis(고정 축)” 모드를 사용하는 방법을 설명합니다.

Covered Aspects:

• Orient
• AxisX AxisY AxisZ
• Custom Attribute

8. Orient Advanced

파티클의 출력(Quads, Meshes, Strips) 방식과 관계없이, 우리는 파티클의 지오메트리 방향을 제어하고 싶을 때가 많습니다.

파티클이 카메라를 향해야 할까요?

파티클의 전방(Forward) 방향과 상향(Up-Axis)은 무엇인가요?

Orient(정렬) 블록을 사용하면 쉽게 파티클의 방향을 설정할 수 있으며, 다양한 모드를 제공합니다.

이번에는 “Advanced Mode(고급 모드)” 를 사용하는 방법을 설명합니다.

Covered Aspects:

• Orient
• AxisX AxisY AxisZ

9. Rotation & Angle

VFX Graph에서 파티클의 회전은 Angle 속성을 조정하여 컨트롤할 수 있습니다.

하지만 보다 현실적인 회전 효과를 구현하려면 Angular Velocity(각속도)를 활용하는 것이 좋습니다.

이 속성은 일반적을 Initialize Context에서 설정되며, Update Context에서 이를 통합하여 회전을 업데이트합니다.

Covered Aspects:

• Rotation
• Angle attribute
• Pivot attribute

10. Falling Coins

해당 내용은 Unity VFX Graph에서 파티클의 회전 및 물리적 움직임을 설정하는 방법을 설명합니다.

파티클의 각속도(Angular Velocity), 충돌, 위치 변화(Position Offset), 랜덤한 회전 효과 등을 적용하는 방식에 대해 다룹니다.

Covered Aspects:

• Angular Velocity
• Angle
• Update Rotation

The post URP VFX Learning Templates (1) appeared first on 어제와 내일의 나 그 사이의 이야기.

CancellationToken, CancellationTokenSource

https://learn.microsoft.com/ko-kr/dotnet/api/system.threading.cancellationtokensource?view=net-9.0

개념 정리

CancellationToken과 CancellationTokenSource는 C#에서 비동기 작업(Task)이나 스레드를 안전하게 취소할 수 있도록 제공되는 기능합니다.

이를 활용하면 비동기 작업을 중단하거나, 긴 루프를 중지할 수 있도록 관리할 수 있습니다.

CancellationTokenSource

• 취소 요청을 생성하고 관리하는 역할을 합니다.
• CancellationToken을 생성할 수 있으며, Cancel() 메서드를 호출하면 해당 토큰을 통해 작업을 중단할 수 있습니다.

CancellationToken

• CancellationTokenSource에서 생성한 취소 토큰을 비동기 작업이나 스레드에 전달하여, 취소 여부를 확인하는 데 사용됩니다.

기본적인 사용법

CancellationToken 사용 예제

using System;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        CancellationTokenSource cts = new CancellationTokenSource();
        CancellationToken token = cts.Token;

        Task task = DoWorkAsync(token);

        // 3초 후에 작업 취소 요청
        await Task.Delay(3000);
        cts.Cancel();

        await task;
    }

    static async Task DoWorkAsync(CancellationToken token)
    {
        for (int i = 0; i < 10; i++)
        {
            // 작업이 취소되었는지 확인
            if (token.IsCancellationRequested)
            {
                Console.WriteLine("작업이 취소되었습니다.");
                return;
            }

            Console.WriteLine($"작업 진행 중... {i}");
            await Task.Delay(1000); // 1초 대기
        }
    }
}

작업 진행 중... 0
작업 진행 중... 1
작업 진행 중... 2
작업이 취소되었습니다.

설명

1. CancellationTokenSource를 생성하여 CancellationToken을 가져옴
2. DoWorkAsync() 메서드에서 token.IsCancellationRequested를 통해 취소 여부 확인
3. Task.Delay(3000) 후 cts.Cancel()을 호출하여 비동기 작업을 취소

알아두면 유용한 기능

ThrowIfCancellationRequested()

이전의 예제에서는 IsCancellationRequested로 확인 후 return 했지만, ThrowIfCancellationRequested()를 사용하면 예외(Exception) 형태로 중단할 수도 있습니다.

static async Task DoWorkAsync(CancellationToken token)
{
    for (int i = 0; i < 10; i++)
    {
        token.ThrowIfCancellationRequested(); // 취소 요청 시 예외 발생

        Console.WriteLine($"작업 진행 중... {i}");
        await Task.Delay(1000);
    }
}

예외 처리 추가 (try-catch로 OperationCanceledException을 catch가 가능)

try
{
    await DoWorkAsync(token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("작업이 취소되었습니다. (예외 발생)");
}

Task.Run()에서 CancellationToken

비동기 작업을 Task.Run()을 사용하여 실행하는 경우, CancellationToken을 직접 전달할 수 있습니다.

Task.Run()과 함께 사용할 경우, CancellationToken을 직접 전달하면 자동으로 OperationCanceledException이 발생하여 처리하기 편리합니다.

CancellationTokenSource cts = new CancellationTokenSource();

Task task = Task.Run(() => 
{
    for (int i = 0; i < 10; i++)
    {
        cts.Token.ThrowIfCancellationRequested();
        Console.WriteLine($"작업 진행 중... {i}");
        Thread.Sleep(1000);
    }
}, cts.Token); // CancellationToken을 직접 전달

await Task.Delay(3000);
cts.Cancel(); // 3초 후 취소

Register()를 활용한 CallBack 함수

CancellationToken.Register()를 사용하면, 취소될 때 특정 작업을 실행할 수 있습니다.

cts.Token.Register(() => Console.WriteLine("취소 요청이 감지되었습니다!"));

사용 예제

using System;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        CancellationTokenSource cts = new CancellationTokenSource();
        CancellationToken token = cts.Token;

        // 취소 요청 시 실행될 콜백 등록
        token.Register(() => Console.WriteLine("취소 요청이 감지되었습니다!"));

        Task task = DoWorkAsync(token);

        await Task.Delay(3000);
        cts.Cancel(); // 3초 후 취소 요청

        await task;
    }

    static async Task DoWorkAsync(CancellationToken token)
    {
        for (int i = 0; i < 10; i++)
        {
            if (token.IsCancellationRequested)
            {
                Console.WriteLine("작업이 취소되었습니다.");
                return;
            }

            Console.WriteLine($"작업 진행 중... {i}");
            await Task.Delay(1000);
        }
    }
}

작업 진행 중... 0
작업 진행 중... 1
작업 진행 중... 2
취소 요청이 감지되었습니다!
작업이 취소되었습니다.

async와 CancellationToken을 활용한 HttpClient 요청 취소

HttpClient에서 CancellationToken을 사용하여 HTTP 요청을 중단할 수도 있습니다.

HttpClient 요청이 너무 오래 걸리면 CancellationToken을 이용해 요청을 취소할 수 있습니다.

using System;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using (HttpClient client = new HttpClient())
        using (CancellationTokenSource cts = new CancellationTokenSource(TimeSpan.FromSeconds(2))) // 2초 후 자동 취소
        {
            try
            {
                HttpResponseMessage response = await client.GetAsync("https://example.com", cts.Token);
                Console.WriteLine("응답 수신 완료!");
            }
            catch (TaskCanceledException)
            {
                Console.WriteLine("HTTP 요청이 취소되었습니다.");
            }
        }
    }
}

CancelAfter()를 활용한 자동 취소

일정 시간이 지나면 자동으로 취소되도록 설정 가능 (CancelAfter(milliseconds))

cts.Token.Register(() => Console.WriteLine("취소 요청이 감지되었습니다!"));

사용 예제 (5초 후 자동 취소되는 코드)

using System;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        CancellationTokenSource cts = new CancellationTokenSource();
        cts.CancelAfter(5000); // 5초 후 자동 취소

        try
        {
            await DoWorkAsync(cts.Token);
        }
        catch (OperationCanceledException)
        {
            Console.WriteLine("작업이 시간 초과로 취소되었습니다.");
        }
    }

    static async Task DoWorkAsync(CancellationToken token)
    {
        for (int i = 0; i < 10; i++)
        {
            token.ThrowIfCancellationRequested();
            Console.WriteLine($"작업 진행 중... {i}");
            await Task.Delay(1000);
        }
    }
}

LinkedTokenSource를 사용하여 여러 토큰을 결합

여러 CancellationTokenSource를 결합하여 하나의 토큰으로 관리 가능

어느 하나라도 취소되면 전체 작업이 취소됨

using System;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        CancellationTokenSource cts1 = new CancellationTokenSource();
        CancellationTokenSource cts2 = new CancellationTokenSource();

        // 두 개의 토큰을 하나로 결합
        using (CancellationTokenSource linkedCts = CancellationTokenSource.CreateLinkedTokenSource(cts1.Token, cts2.Token))
        {
            Task task = DoWorkAsync(linkedCts.Token);

            await Task.Delay(3000);
            cts1.Cancel(); // 하나의 토큰만 취소해도 작업 전체가 중단됨

            await task;
        }
    }

    static async Task DoWorkAsync(CancellationToken token)
    {
        for (int i = 0; i < 10; i++)
        {
            token.ThrowIfCancellationRequested();
            Console.WriteLine($"작업 진행 중... {i}");
            await Task.Delay(1000);
        }
    }
}

결과적으로 cts1.Cancel(); 호출 시 linkedCts도 취소됨

Parallel.ForEach()에서 CancellationToken 적용

Parallel.ForEach()에서 CancellationToken을 사용하여 병렬 처리 도중 특정 조건에서 중단할 수도 있습니다.

ParallelOptions을 통해 취소 토큰을 설정하면 병렬 처리에서도 취소를 손쉽게 관리할 수 있습니다.

ParallelOptions options = new ParallelOptions
{
    CancellationToken = cts.Token,
    MaxDegreeOfParallelism = 4 // 최대 4개의 스레드 사용
};

try
{
    Parallel.ForEach(Enumerable.Range(1, 100), options, (num, state) =>
    {
        options.CancellationToken.ThrowIfCancellationRequested();
        Console.WriteLine($"Processing {num}");
        Thread.Sleep(500); // 가상의 작업
    });
}
catch (OperationCanceledException)
{
    Console.WriteLine("병렬 작업이 취소되었습니다.");
}

주의 사항

리소스 정리의 중요성

취소된 작업에서도 적절한 리소스 정리가 필요합니다.

try/finally 블록이나 using 문을 적절이 활용하는 것이 좋습니다.

static async Task ProcessFileAsync(string path, CancellationToken token)
{
    FileStream file = null;
    try
    {
        file = new FileStream(path, FileMode.Open);
        // 파일 처리 작업
        token.ThrowIfCancellationRequested();
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine("파일 처리가 취소되었습니다.");
        throw;
    }
    finally
    {
        // 취소 여부와 상관없이 항상 실행됨
        file?.Dispose();
    }
}

CancellationToken 확인 빈도

장시간 실행되는 작업에서는 적절한 간격으로 취소 토큰을 확인하는 것이 중요합니다.

취소 토큰 확인은 가벼운 연산이지만, 매우 빈번하게 호출되는 코드에서는 성능에 영향을 줄 수 있습니다.

static void ProcessLargeData(IEnumerable<int> items, CancellationToken token)
{
    int count = 0;
    foreach (var item in items)
    {
        // 100개 항목마다 취소 여부 확인 (너무 자주 확인하면 성능 저하)
        if (count++ % 100 == 0 && token.IsCancellationRequested)
        {
            Console.WriteLine("작업이 취소되었습니다.");
            return;
        }
        
        // 항목 처리...
    }
}

CancellationTokenSource.Dispose() 중요성

CancellationTokenSource는 사용 후 수명이 끝나면 반드시 Dispose()를 호출해야 합니다. (메모리 누수)

using 문을 사용하는 것을 추천합니다.

using (var cts = new CancellationTokenSource())
{
    // 작업 수행
}
// 여기서 자동으로 cts.Dispose() 호출됨

공식 문서 사용 예제

// https://learn.microsoft.com/ko-kr/dotnet/api/system.threading.cancellationtokensource?view=net-9.0
using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

public class Example
{
   public static void Main()
   {
      // Define the cancellation token.
      CancellationTokenSource source = new CancellationTokenSource();
      CancellationToken token = source.Token;

      Random rnd = new Random();
      Object lockObj = new Object();
      
      List<Task<int[]>> tasks = new List<Task<int[]>>();
      TaskFactory factory = new TaskFactory(token);
      for (int taskCtr = 0; taskCtr <= 10; taskCtr++) {
         int iteration = taskCtr + 1;
         tasks.Add(factory.StartNew( () => {
           int value;
           int[] values = new int[10];
           for (int ctr = 1; ctr <= 10; ctr++) {
              lock (lockObj) {
                 value = rnd.Next(0,101);
              }
              if (value == 0) { 
                 source.Cancel();
                 Console.WriteLine("Cancelling at task {0}", iteration);
                 break;
              }   
              values[ctr-1] = value; 
           }
           return values;
        }, token));   
      }
      try {
         Task<double> fTask = factory.ContinueWhenAll(tasks.ToArray(), 
         (results) => {
            Console.WriteLine("Calculating overall mean...");
            long sum = 0;
            int n = 0; 
            foreach (var t in results) {
               foreach (var r in t.Result) {
                  sum += r;
                  n++;
               }
            }
            return sum/(double) n;
         } , token);
         Console.WriteLine("The mean is {0}.", fTask.Result);
      }   
      catch (AggregateException ae) {
         foreach (Exception e in ae.InnerExceptions) {
            if (e is TaskCanceledException)
               Console.WriteLine("Unable to compute mean: {0}", 
                  ((TaskCanceledException) e).Message);
            else
               Console.WriteLine("Exception: " + e.GetType().Name);
         }
      }
      finally {
         source.Dispose();
      }
   }
}
// Repeated execution of the example produces output like the following:
//       Cancelling at task 5
//       Unable to compute mean: A task was canceled.
//       
//       Cancelling at task 10
//       Unable to compute mean: A task was canceled.
//       
//       Calculating overall mean...
//       The mean is 5.29545454545455.
//       
//       Cancelling at task 4
//       Unable to compute mean: A task was canceled.
//       
//       Cancelling at task 5
//       Unable to compute mean: A task was canceled.
//       
//       Cancelling at task 6
//       Unable to compute mean: A task was canceled.
//       
//       Calculating overall mean...
//       The mean is 4.97363636363636.
//       
//       Cancelling at task 4
//       Unable to compute mean: A task was canceled.
//       
//       Cancelling at task 5
//       Unable to compute mean: A task was canceled.
//       
//       Cancelling at task 4
//       Unable to compute mean: A task was canceled.
//       
//       Calculating overall mean...
//       The mean is 4.86545454545455.

The post C#의 CancellationToken, CancellationTokenSource appeared first on 어제와 내일의 나 그 사이의 이야기.

EntityQuery 정리

ECS(Entity Component System)에서 특정 조건을 만족하는 Entity들을 효율적으로 검색하는 도구

Entity가 가진 컴포넌트 조합을 기준으로 검색하며, 이를 통해 메모리 캐시 효율을 극대화

1. EntityQuery의 기본 개념

• Entity 필터링: 특정한 컴포넌트를 포함하거나 제외하는 기준을 정할 수 있다.
• Chunk 단위 검색: EntityQuery는 Entity 개별 조회가 아닌 Chunk 단위(Archetype Chunk)로 데이터를 가져옴
• 즉시 검색 or Job 시스템과 병렬 처리 가능

– 특정 컴포넌트를 가진 Entity 찾기

public partial struct FindEntitiesSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        // PositionComponent와 VelocityComponent를 가진 Entity 찾기
        EntityQuery query = SystemAPI.QueryBuilder()
            .WithAll<PositionComponent, VelocityComponent>()
            .Build();

        foreach (var (position, velocity) in SystemAPI.Query<RefRW<PositionComponent>, RefRO<VelocityComponent>>())
        {
            position.ValueRW.Value += velocity.ValueRO.Value * SystemAPI.Time.DeltaTime;
        }
    }
}

• WithAll() → 모든 엔티티 중 PositionComponent와 VelocityComponent를 가진 것만 검색
• RefRW → 읽기/쓰기 가능
• RefRO → 읽기 전용

2. EntityQuery의 주요 조건

– 특정 조건의 엔티티 찾기

EntityQuery query = SystemAPI.QueryBuilder()
    .WithAll<PositionComponent>()   // PositionComponent가 있어야 함
    .WithAny<VelocityComponent, AccelerationComponent>()  // 둘 중 하나만 있으면 됨
    .WithNone<DestroyedTag>()        // DestroyedTag가 있으면 제외
    .Build();

• WithAll() → 반드시 포함
• WithAny() → 하나라도 포함
• WithNone() → 포함하면 안 됨

3. EntityQuery를 사용한 데이터 접근 방법

(1) SystemAPI.Query() 사용

• EntityQuery를 생성하고 foreach 루프에서 엔티티 데이터를 순회 가능

foreach (var (position, velocity) in SystemAPI.Query<RefRW<PositionComponent>, RefRO<VelocityComponent>>())
{
    position.ValueRW.Value += velocity.ValueRO.Value * SystemAPI.Time.DeltaTime;
}

(2) ToEntityArray()로 Entity 리스트 가져오기

• ToEntityArray()를 사용하면 해당 EntityQuery에 해당하는 Entity 리스트를 가져옴

var entities = query.ToEntityArray(Allocator.Temp);
foreach (var entity in entities)
{
    Debug.Log($"찾은 Entity: {entity}");
}
entities.Dispose();

• ToEntityArray(Allocator.Temp) → NativeArray로 Entity를 가져옴
• Dispose() 필수! 메모리 해제 안 하면 메모리 누수 발생

(3) ToComponentDataArray()로 특정 컴포넌트 리스트 가져오기

• 특정 컴포넌트의 값만 가져올 수도 있음.

var positions = query.ToComponentDataArray<PositionComponent>(Allocator.Temp);
foreach (var position in positions)
{
    Debug.Log($"Position: {position.Value}");
}
positions.Dispose();

• 데이터만 필요한 경우 성능 최적화 가능

4. IJobChunk과 함께 사용하기

• IJobChunk를 사용하면 EntityQuery를 멀티스레드로 병렬 처리 가능
• ArchetypeChunk을 사용하여 Chunk 단위 데이터 접근 가능

[BurstCompile]
public struct MoveJob : IJobChunk
{
    public ComponentTypeHandle<PositionComponent> PositionHandle;
    [ReadOnly] public ComponentTypeHandle<VelocityComponent> VelocityHandle;
    public float DeltaTime;

    public void Execute(ArchetypeChunk chunk, int chunkIndex, int firstEntityIndex)
    {
        var positions = chunk.GetNativeArray(PositionHandle);
        var velocities = chunk.GetNativeArray(VelocityHandle);

        for (int i = 0; i < chunk.Count; i++)
        {
            positions[i] = new PositionComponent
            {
                Value = positions[i].Value + velocities[i].Value * DeltaTime
            };
        }
    }
}

public partial struct MoveSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        var query = SystemAPI.QueryBuilder()
            .WithAll<PositionComponent, VelocityComponent>()
            .Build();

        var positionHandle = SystemAPI.GetComponentTypeHandle<PositionComponent>();
        var velocityHandle = SystemAPI.GetComponentTypeHandle<VelocityComponent>(isReadOnly: true);

        var job = new MoveJob
        {
            PositionHandle = positionHandle,
            VelocityHandle = velocityHandle,
            DeltaTime = SystemAPI.Time.DeltaTime
        };
        // query를 기반으로 Schedule()을 호출
        state.Dependency = job.Schedule(query, state.Dependency);
    }
}

• GetComponentTypeHandle<T>() 사용 → 컴포넌트 데이터를 가져올 때 캐시 최적화
  GetComponentTypeHandle<T>()은 ECS(Worlds)의 청크 단위 데이터 접근을 최적화하기 위한 API
• IJobChunk으로 멀티스레드 병렬 처리 가능

job.Schedule(query, state.Dependency)의 실행 과정

query를 사용하여 IJobChunk가 처리할 청크들을 찾음

• query는 PositionComponent와 VelocityComponent를 포함하는 엔티티들의 청크 목록을 가져옴.
• IJobChunk는 이 청크 목록을 기반으로 실행됨.

job.Schedule()을 호출하여 MoveJob을 실행

• query에서 반환된 청크를 MoveJob에서 병렬적으로 처리.
• 내부적으로 각 청크별로 MoveJob.Execute()가 실행됨.

state.Dependency를 업데이트하여 잡 실행을 관리

• state.Dependency는 현재 시스템의 의존성 체인을 관리.
• 이전 프레임에서 실행된 다른 잡들과의 의존 관계를 고려하여 동기화함.
• 병렬 처리를 안전하게 실행하기 위해 필요함.

(Q) ComponentTypeHandle을 사용하여 NativeArray를 생성하는 것과 미리 NativeArray를 넘겨주는 것의 차이점

(1) ComponentTypeHandle<T>을 사용하는 이유

GetComponentTypeHandle<T>()을 사용하여 IJobChunk 내부에서 NativeArray를 가져오는 이유는 Chunk 단위 접근 최적화 때문이다.

• ComponentTypeHandle<T>을 사용하면 각 Chunk에 맞는 NativeArray를 개별적으로 가져올 수 있음
• 만약 NativeArray를 미리 만들어서 넘겨준다면, Chunk별로 나눠진 데이터가 하나의 배열에 병합되어야 하므로 메모리 효율이 떨어지고 캐시 활용도가 낮아짐

(2) ComponentTypeHandle<T>과 NativeArray<T> 차이점 비교

(3) ComponentTypeHandle<T> 방식

1> SystemAPI.GetComponentTypeHandle<T>() 실행

var positionHandle = SystemAPI.GetComponentTypeHandle<PositionComponent>();
var velocityHandle = SystemAPI.GetComponentTypeHandle<VelocityComponent>(isReadOnly: true);

• ComponentTypeHandle<T>을 가져옴
• Chunk별로 데이터가 분산되어 있기 때문에 NativeArray<T>로 직접 변환하지 않음

2> MoveJob.Schedule() 실행

var job = new MoveJob
{
    PositionHandle = positionHandle,
    VelocityHandle = velocityHandle,
    DeltaTime = SystemAPI.Time.DeltaTime
};

state.Dependency = job.Schedule(query, state.Dependency);

• MoveJob을 스케줄할 때 ComponentTypeHandle<T>을 넘김

3> MoveJob.Execute() 내부에서 GetNativeArray() 실행

var positions = chunk.GetNativeArray(PositionHandle);
var velocities = chunk.GetNativeArray(VelocityHandle);

• 각 Chunk에서 NativeArray<T>를 가져와서 사용함.
• 이렇게 하면 각 Chunk가 독립적으로 자신의 데이터에 접근할 수 있으며, 캐시 최적화 및 멀티스레딩 효율 증가

(4) NativeArray Job 방식

만약 NativeArray<T>를 미리 만들어서 Job에 넘기면, 멀티스레딩 최적화가 어렵고 성능 저하 가능성 증가.

전체 데이터를 하나의 NativeArray로 병합하는 과정이 필요, Chunk별 데이터 레이아웃이 깨질 수 있음 → CPU 캐시 효율 저하.

NativeArray<PositionComponent> positions = new NativeArray<PositionComponent>(entityCount, Allocator.TempJob);
NativeArray<VelocityComponent> velocities = new NativeArray<VelocityComponent>(entityCount, Allocator.TempJob);

// Job에 NativeArray를 직접 넘김
var job = new MoveJob
{
    Positions = positions,
    Velocities = velocities,
    DeltaTime = SystemAPI.Time.DeltaTime
};

state.Dependency = job.Schedule(state.Dependency);

이 경우, positions와 velocities를 Chunk별로 나누지 않고 전체 데이터를 하나의 배열로 만듦.

Chunk별 데이터가 섞일 가능성이 높아져 캐시 미스(Cache Miss)가 증가할 수 있음

5. EntityQuery의 추가 기능

(1) CalculateEntityCount()로 개수 확인

int entityCount = query.CalculateEntityCount();
Debug.Log($"현재 쿼리 결과 개수: {entityCount}");

(2) SetChangedVersionFilter()로 변경된 컴포넌트만 검색

query.SetChangedVersionFilter<PositionComponent>();

최근 변경된 PositionComponent를 가진 엔티티만 검색

(3) Enable/Disable로 쿼리 활성화/비활성화

query.SetEnabled(false);  // 쿼리 비활성화
query.SetEnabled(true);   // 다시 활성화

쿼리를 특정 조건에서만 사용하고 싶을 때 활용

The post ECS – EntityQuery 정리 appeared first on 어제와 내일의 나 그 사이의 이야기.