Unity Archives - 어제와 내일의 나 그 사이의 이야기

Unity Package Manager “Invalid Signature”

lycos7560 — Tue, 10 Feb 2026 21:02:46 +0000

문제 상황
오류의 의미와 영향
해결 방법 (개인적인)

문제 상황

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

Unity 해상도 대응 코드

lycos7560 — Wed, 07 Jan 2026 09:47:17 +0000

using UnityEngine;
using UnityEngine.UI;
using GoogleMobileAds.Api;

[RequireComponent(typeof(CanvasScaler))]
public class CanvasResolutionController : MonoBehaviour
{
    private GoogleAdMobManager AdManager => GoogleAdMobManager.Instance;
    private CanvasScaler _CanvasScaler;

    private RectTransform safeAreaWrapper;
    private RectTransform uiContainer;
    private RectTransform adBannerSpace;
    private RectTransform contentArea;

    private const float TARGET_ASPECT = 1440f / 2560f; // 9:16

    // 캐싱
    private Rect lastSafeArea; 
    private Vector2 lastScreenSize;
    private bool lastAdStatus;
    // ------------------

    void Awake()
    {
        _CanvasScaler = GetComponent();
        _CanvasScaler.uiScaleMode = CanvasScaler.ScaleMode.ScaleWithScreenSize;
        _CanvasScaler.referenceResolution = new Vector2(1440, 2560);
        _CanvasScaler.screenMatchMode = CanvasScaler.ScreenMatchMode.MatchWidthOrHeight;

        CreateUIHierarchy();

        if (AdManager != null)
            AdManager.OnBannerAdLoaded += ApplySafeLayout;
    }

    void Start() => ApplySafeLayout();

    void LateUpdate()
    {
        if (CheckForChanges())
        {
            ApplySafeLayout();
        }
    }

    /// 
    /// 레이아웃 업데이트가 필요한 변화가 있는지 확인
    /// 
    private bool CheckForChanges()
    {
        bool isChanged = false;

        // 1. 화면 해상도 체크
        if (Screen.width != lastScreenSize.x || Screen.height != lastScreenSize.y)
        {
            lastScreenSize = new Vector2(Screen.width, Screen.height);
            isChanged = true;
        }

        // 2. Safe Area 체크
        if (Screen.safeArea != lastSafeArea)
        {
            lastSafeArea = Screen.safeArea;
            isChanged = true;
        }

        // 3. 광고 로드 상태 체크
        bool currentAdStatus = (AdManager != null && AdManager.IsBannerLoaded);
        if (currentAdStatus != lastAdStatus)
        {
            lastAdStatus = currentAdStatus;
            isChanged = true;
        }

        return isChanged;
    }

    void CreateUIHierarchy()
    {
        safeAreaWrapper = CreateRectElement("Safe_Area_Wrapper", transform);
        uiContainer = CreateRectElement("UI_Container", safeAreaWrapper);
        adBannerSpace = CreateRectElement("AdBannerSpace", uiContainer);
        contentArea = CreateRectElement("ContentArea", uiContainer);

        var fitter = contentArea.gameObject.AddComponent();
        fitter.aspectRatio = TARGET_ASPECT;
        fitter.aspectMode = AspectRatioFitter.AspectMode.FitInParent;
        fitter.enabled = true;
    }

    public void ApplySafeLayout()
    {
        if (safeAreaWrapper == null || contentArea == null) return;

        Rect safe = Screen.safeArea;
        float sw = Screen.width;
        float sh = Screen.height;

        // 1. Safe Area 적용
        safeAreaWrapper.anchorMin = new Vector2(safe.x / sw, safe.y / sh);
        safeAreaWrapper.anchorMax = new Vector2((safe.x + safe.width) / sw, (safe.y + safe.height) / sh);
        ResetOffsets(safeAreaWrapper);

        // 2. 광고 높이 계산
        float adHeightPx = lastAdStatus ? GetAdBannerHeightInPixels() : 0f;
        float adHeightNormalized = adHeightPx / safe.height;

        // 3. 광고 및 콘텐츠 영역 분할
        adBannerSpace.anchorMin = new Vector2(0, 1 - adHeightNormalized);
        adBannerSpace.anchorMax = new Vector2(1, 1);
        ResetOffsets(adBannerSpace);

        contentArea.anchorMin = Vector2.zero;
        contentArea.anchorMax = new Vector2(1, 1 - adHeightNormalized);
        ResetOffsets(contentArea);

        // 4. 동적 Match 수정
        UpdateCanvasMatch(safe.width, safe.height - adHeightPx);

        Debug.Log($"[LayoutUpdate] Match: {_CanvasScaler.matchWidthOrHeight}, AdHeight: {adHeightPx}");
    }

    private void UpdateCanvasMatch(float availableW, float availableH)
    {
        if (availableW <= 0 || availableH <= 0) return;

        float availableAspect = availableW / availableH;

        // 가로가 남는 환경(패드) -> 세로에 맞춤
        if (availableAspect > TARGET_ASPECT)
        {
            _CanvasScaler.matchWidthOrHeight = 1f;
        }
        else // 세로가 남는 환경(플립) -> 가로에 맞춤
        {
            _CanvasScaler.matchWidthOrHeight = 0f;
        }
    }

    private RectTransform CreateRectElement(string name, Transform parent)
    {
        GameObject obj = new GameObject(name, typeof(RectTransform));
        obj.transform.SetParent(parent, false);
        RectTransform rt = obj.GetComponent();
        rt.anchorMin = Vector2.zero;
        rt.anchorMax = Vector2.one;
        ResetOffsets(rt);
        return rt;
    }

    private void ResetOffsets(RectTransform rt) => rt.offsetMin = rt.offsetMax = Vector2.zero;

    private float GetAdBannerHeightInPixels()
    {
        int widthInDp = MobileAds.Utils.GetDeviceSafeWidth();
        AdSize adaptiveSize = AdSize.GetCurrentOrientationAnchoredAdaptiveBannerAdSizeWithWidth(widthInDp);
        return (float)adaptiveSize.Height * Screen.dpi / 160f;
    }

    void OnDestroy()
    {
        if (AdManager != null)
            AdManager.OnBannerAdLoaded -= ApplySafeLayout;
    }
}

The post Unity 해상도 대응 코드 appeared first on 어제와 내일의 나 그 사이의 이야기.

Unity Netcode for Entities – Synchronizing states and inputs (1)

lycos7560 — Sun, 04 May 2025 11:00:58 +0000

Synchronizing states and inputs
- 1⃣ Ghosts를 이용한 동기화

Synchronizing states and inputs

Netcode for Entities 1.5.0v

Ghosts, Commands, RPC를 사용해 서버와 클라이언트 간 상태 및 입력 동기화합니다.

주제	설명
1⃣ Ghosts를 이용한 동기화	유령(Ghost)을 사용하면 서버와 클라이언트 간 상태를 일관되면서도 유연하게 동기화하고 복제할 수 있습니다.
2⃣ RPC(Remote Procedure Call)를 통한 통신	원격 프로시저 호출(RPC)은 게임의 상위 흐름 이벤트를 전달하거나 클라이언트에서 서버로 예측되지 않은 단발성 명령을 보낼 때 사용됩니다.
3⃣ Commands Stream을 통한 입력 처리	클라이언트는 `NetworkStreamConnection`이 인게임 상태로 설정되면 서버로 연속적인 Commands Stream을 보냅니다. 이 Stream에는 모든 입력 정보와 마지막으로 수신한 스냅샷에 대한 확인 응답이 포함됩니다.

1⃣ Ghosts를 이용한 동기화

https://docs.unity3d.com/Packages/com.unity.netcode@1.5/manual/synchronization.html

Ghosts를 사용하여 서버와 클라이언트 간 상태를 일관되고 커스터마이징 가능하게 동기화 및 복제하는 방법입니다.

주제	설명
Ghosts and snapshots	Netcode for Entities에서 Ghost과 스냅샷(snapshot)이 무엇인지, 그리고 이를 멀티플레이어 프로젝트에서 상태 동기화에 어떻게 사용하는지를 이해합니다.
`GhostFieldAttribute`를 통한 Serialization and synchronization	`GhostFieldAttribute`를 사용하여 `Unity.Entities.IComponentData` 또는 `Unity.Entities.IBufferElementData`의 어떤 필드와 속성이 서버에서 클라이언트로 직렬화 및 복제되어야 하는지를 지정합니다.
`GhostComponentAttribute`를 통한 복제 커스터마이징	`GhostComponentAttribute`와 그 속성들을 사용하여 런타임에서 복제가 어떻게 처리되는지를 커스터마이징할 수 있습니다.
GhostComponentVariationAttribute로 복제 스키마 생성	`GhostComponentVariationAttribute`를 사용하면 원본 타입이나 필드를 수정하지 않고도 특정 타입에 대해 (컴파일 타임에) 복제 스키마를 정의할 수 있습니다.
Ghost 생성 및 미리 생성	Ghost을 게임의 일환으로 생성한 후, 이들이 어떻게 동기화되어야 하는지를 정의한 뒤 Spawn합니다.
Ghost type templates	Netcode for Entities는 고스트 컴포넌트 타입들이 베이킹(baking) 및 직렬화 과정에서 어떻게 처리될지를 정의하는 기본 템플릿을 제공합니다. 또한 사용자 정의 템플릿을 만들어 추가 타입을 등록할 수도 있습니다.
Ghost groups	고스트 그룹을 사용하여 여러 고스트 인스턴스 간의 복제 타이밍을 동기화하고, 일반적인 게임플레이 상태 오류를 방지할 수 있습니다.

Ghosts and snapshots

https://docs.unity3d.com/Packages/com.unity.netcode@1.5/manual/ghost-snapshots.html

Netcode for Entities에서 Ghosts와 Snapshots을 이해하고, 멀티플레이어 프로젝트에서 상태를 동기화하는 방법에 대한 내용입니다.

Netcode for Entities는 이벤트를 처리하기 위한 제한적인 형태의 원격 프로시저 호출(RPC) 기능도 지원합니다.

Ghost와 RPC 중 언제 어떤 기능을 사용할지에 대해서는 [RPC 비교]를 참고하세요.

Ghosts

Ghost는 멀티플레이어 게임에서 네트워크를 통해 동기화되는 오브젝트입니다.
Ghost는 서버가 소유하고 시뮬레이션합니다. 즉, 서버가 Ghost에 대한 최종 권한(authority) 을 가지며, Ghost를 생성, 제거, 업데이트할 수 있습니다.

서버에 연결된 각 클라이언트는 해당 Ghost의 복사본을 가지며, 서버가 매 네트워크 틱마다 보내는 Snapshots을 통해 해당 복사본을 업데이트합니다.
이 Snapshots은 Ghost 상태의 일부를 포함합니다.

클라이언트는 Ghost의 상태를 두 가지 타임라인(보간 또는 예측) 중 하나를 통해 게임 시뮬레이션에 반영하며, 이를 통해 부드러운 렌더링이 가능합니다.

중요한 점은, 클라이언트는 Ghost를 직접 제어하거나 변경할 수 없습니다.
게임 시뮬레이션은 서버가 권한을 가지므로, 클라이언트가 Ghost를 수정하더라도 이는 클라이언트 예측(Client Prediction) 으로 간주되며, 서버에서 보내는 새로운 Snapshots에 의해 되돌려질 수 있습니다.

Ghost를 생성할 때는 클라이언트와 서버 간 동기화 방식을 정의해야 합니다. 생성 후 Ghost를 스폰하는 방법은 Ghost Spawning 페이지를 참고하세요.

Create a ghost

Unity 에디터에서 GhostAuthoringComponent가 포함된 프리팹을 생성하여 Ghost를 만들 수 있습니다.

GhostAuthoringComponent는 프리팹의 동기화 방식을 구성할 수 있는 에디터 UI를 제공합니다. 다음과 같은 속성들을 설정해야 합니다:

Name (이름)
Importance (중요도)
Supported Ghost Mode (지원되는 고스트 모드)
Default Ghost Mode (기본 고스트 모드)
Optimization Mode (최적화 모드)

GhostAuthoringComponent

또한 MaxSendRate 값을 설정하면 전체 대역폭 사용량을 줄일 수 있습니다.

Importance 값은 Snapshots에 포함시킬 Ghost를 선택할 때 우선 순위를 정하는 데 사용됩니다.

Snapshots 패킷의 크기는 설정으로 조정할 수 있습니다.

MaxSendRate (최대 전송 속도)는 해당 Ghost 프리팹 타입의 Ghost Chunk가 초당 몇 회 전송될 수 있는지를 나타냅니다 (단위: Hz)

이는 전송 가능 최대 빈도를 의미할 뿐, 다른 요인들에 의해 제한될 수 있습니다.

예를 들어 아래와 같은 상황이 있다면

MaxSendRate가 100Hz인 경우, 기본 NetworkTickRate(60Hz)에 의해 60Hz로 제한됩니다.

MaxSendRate가 60Hz인데 NetworkTickRate가 30Hz인 경우, 30Hz가 최대 전송 속도입니다.

30Hz NetworkTickRate에 45Hz MaxSendRate를 설정하면, 실제 전송 속도는 30Hz로 내림(round down)됩니다.

Supported Ghost Mode options (지원되는 고스트 모드)

All: 보간(Interpolated)과 예측(Predicted)을 모두 지원
Interpolated: 보간만 지원
Predicted: 예측만 지원

Default Ghost Mode (기본 고스트 모드)

Interpolated: 서버에서 받은 모든 Ghost를 보간 처리
Predicted: 서버에서 받은 모든 Ghost를 예측 처리
Owner Predicted: Ghost의 소유 클라이언트에게는 예측 처리, 그 외 클라이언트에게는 보간 처리
이 모드를 사용하려면 GhostOwner 컴포넌트를 추가하고, 코드에서 NetworkId 필드를 설정해야 합니다.

Optimization Mode (최적화 모드)

Dynamic: 상태가 변할 때와 변하지 않을 때 모두 작은 스냅샷 크기로 최적화
Static: 상태가 변하지 않을 때는 전송하지 않고, 상태가 변할 때는 최적화되지 않음

Synchronize ghost components and fields

Ghost에 어떤 컴포넌트와 필드를 동기화할지 지정하려면 C# 특성(Attribute)을 사용합니다.

속성 (Attribute)	사용법 (Usage)	추가 정보 (More information)
`GhostFieldAttribute`	구조체의 필드나 속성에 `GhostFieldAttribute`를 사용하여 어떤 컴포넌트(또는 버퍼) 필드를 직렬화할지 지정합니다. 어떤 컴포넌트든 하나 이상의 필드에 `[GhostField]`가 지정되면, 해당 컴포넌트는 복제되어 고스트 데이터의 일부로 전송됩니다.	GhostFieldAttribute를 사용한 직렬화 및 동기화
`GhostEnabledBitAttribute`	`IEnableableComponent` 구조체 정의에 `GhostEnabledBitAttribute`를 사용하여 이 컴포넌트의 “활성화 비트(enabled bit)”도 직렬화해야 함을 지정합니다. 이 속성이 지정되면 활성화 비트도 복제되어 고스트 데이터의 일부로 전송됩니다.	GhostComponentAttribute
`GhostComponentAttribute`	`ComponentType` 구조체 정의에 `GhostComponentAttribute`를 사용하여 다음을 선언합니다: – 어떤 프리팹 버전에 이 컴포넌트가 포함될지 – 자식 엔티티에 대해 이 컴포넌트를 직렬화할지 여부 – 어떤 클라이언트 하위 집합에 이 컴포넌트를 복제할지 주의: `GhostComponentAttribute`를 추가한다고 해서 컴포넌트의 필드가 자동으로 복제되지 않습니다. 각 필드에 `GhostFieldAttribute`를 개별적으로 지정해야 합니다.	GhostComponentAttribute

Snapshots

Snapshots은 특정 네트워크 틱에서 서버의 모든 Ghost 상태를 나타내는 표현입니다.

엔티티용 Netcode는 각 연결된 클라이언트에 틱당 한 번씩 Snapshots을 전송하며, 이는 NetworkTickRate에 의해 정의된 속도로 이루어집니다(SimulationTickRate와 다를 수 있음).

NetworkTickRate가 SimulationTickRate보다 낮을 경우, 엔티티용 Netcode는 연결의 하위 집합 그룹을 생성하고 하위 집합의 각 연결에 하나의 Snapshots을 전송합니다.

그 후 다음 틱에서 다음 하위 집합에 Snapshots을 전송하는 식으로 진행됩니다.

이는 GhostSendSystem 부하를 여러 SimulationTickRate 틱에 분산시키기 때문에 라운드 로빈 접근 방식이라고 합니다.

Snapshots 처리

Ghost 스냅샷 시스템은 서버에 존재하는 엔티티를 모든 클라이언트에 동기화합니다.

성능 향상을 위해 서버는 엔티티별이 아닌 Chunk별로 Ghost를 처리합니다.

그러나 수신 클라이언트 측에서는 엔티티별로 처리가 이루어집니다.

서버의 한 Chunk에 있는 일련의 엔티티가 클라이언트의 한 Chunk에 있는 동일한 엔티티 집합과 일치하지 않을 수 있기 때문에 양쪽에서 Chunk별로 처리하는 것은 불가능합니다.

또한 각각 고유한 엔티티-Chunk 레이아웃을 가진 여러 클라이언트가 있습니다.

부분 Snapshots

많은 Ghost(또는 Ghost 데이터)를 복제할 때, 틱당 Snapshots 데이터 크기는 최대 전송 단위(MTU) 상한으로 제한됩니다.

그 결과, Snapshots이 모든 Ghost의 하위 집합만 포함하는 것은 일반적이고 예상된 일입니다.

이러한 Snapshots을 부분 Snapshots이라고 합니다.

중요도 값이 가장 높은 Chunk의 Ghost가 먼저 추가되며, 엔티티용 Netcode는 거대한 패킷에 한 번에 모두 전송하는 대신 대규모 월드를 몇 개의 고스트 Chunk씩 스트리밍합니다.

이는 효과적으로 중요도 우선순위 큐입니다.

MaxSendRate를 사용하여 각 스냅샷의 중요도 우선순위 큐의 일부로 간주되는 고스트 Chunk의 수를 줄일 수도 있으며, 이는 총 대역폭 소비를 줄일 수 있습니다.

Snapshots의 최대 크기를 변경할 수 있습니다.

최대 크기를 줄이면 상대적인 헤더 오버헤드가 증가하고 사용 가능한 데이터가 줄어드는 대신 대역폭이 절약되며,

크기를 늘리면 Snapshots당 여러 UDP 패킷을 전송해야 할 수 있어 패킷 손실 가능성이 증가할 수 있습니다.

자세한 내용은 중요도 스케일링(importance scaling)에 관한 문서를 참조하세요.

Snapshots 시각화 도구

네트워크를 통해 전송되는 내용을 이해하기 위해 Network Debugger 스냅샷 시각화 도구를 사용할 수 있습니다.

도구를 열려면 Multiplayer > Open NetDbg로 이동하면 브라우저 창에서 도구가 열립니다.

이 도구는 수신된 각 스냅샷에 대한 세로 막대를 표시하며, 각 스냅샷에 대한 주요 정보 분석을 제공합니다.

GhostFieldAttribute를 활용한 필드 동기화 및 직렬

https://docs.unity3d.com/Packages/com.unity.netcode@1.5/manual/ghostfield-synchronize.html

Unity.Entities.IComponentData 또는 Unity.Entities.IBufferElementData의 어떤 필드와 속성이 서버에서 클라이언트로 직렬화되고 복제될지 지정하려면 GhostFieldAttribute를 사용하세요.

컴포넌트나 버퍼에 GhostFieldAttribute로 주석이 달린 필드가 하나 이상 포함되면, 컴포넌트 직렬화를 구현하는 구조체가 자동으로 코드 생성됩니다.

GhostFieldAttribute 외에도 GhostComponentAttribute를 사용하여 런타임에서 복제가 처리되는 방식을 추가로 사용자 지정할 수 있습니다.

GhostFieldAttribute 직렬화 사용자 지정

GhostFieldAttribute를 사용하여 컴포넌트와 버퍼의 직렬화를 사용자 지정하려면 다음 속성을 사용하세요.

자세한 내용은 GhostFieldAttribute API documentation를 참조하세요.

속성 (Property)	기본값 (Default value)	설명 (Description)
`Quantization`	float 타입은 기본적으로 비활성화됨, int 타입에서는 사용 불가	`Quantization` 속성은 부동 소수점 숫자(및 다른 지원되는 타입, 예: 고스트 타입 템플릿)에 대해 정밀도를 제한하기 위한 quantization를 설정합니다. 부동 소수점 숫자는 지정된 양자화 값으로 곱해진 후 정수로 변환되어 대역폭을 절약합니다.
`Composite`	기본적으로 비활성화됨	`Composite` 속성은 delta compression 시 비원시 타입(예: 구조체)의 변경 비트 마스크를 어떻게 계산할지를 제어합니다. `true`로 설정하면, 구조체 전체에 변경 사항이 있을 경우 단 하나의 변경 비트만 생성됩니다. `false`일 경우 각 필드마다 변경 비트를 가집니다. 예를 들어 `GUID`와 같이 필드들이 함께 수정되는 경우에는 `Composite=true`를 사용하는 것이 좋습니다.
`SendData`	기본적으로 활성화됨	`SendData` 속성은 코드 생성 시 특정 필드를 직렬화 데이터에서 제외하도록 지정합니다. 구조체처럼 모든 필드가 기본적으로 직렬화되는 비원시 멤버에 유용합니다.
`Smoothing`	기본값은 `Clamp`	`Smoothing` 속성은 고스트가 `GhostMode.Interpolated` 모드일 때 필드가 어떻게 갱신될지를 제어합니다. 옵션은 다음과 같습니다: – `Clamp`: 스냅샷이 수신될 때마다 클라이언트 값을 최신 스냅샷 값으로 고정 – `Interpolate`: 두 스냅샷 값 사이를 프레임마다 보간 – `InterpolateAndExtrapolate`: 다음 틱에 대한 데이터가 없을 경우 이전 두 스냅샷 값을 기반으로 외삽
`MaxSmoothingDistance`	–	`MaxSmoothingDistance` 속성은 스냅샷 간 값 차이가 지정된 한계를 초과할 경우 보간을 비활성화합니다. 주로 텔레포트와 같은 상황에서 유용합니다.
`SubType`	–	`SubType` 속성은 `GhostFieldSubType` API를 사용하여 필드에 대해 사용자 지정 직렬화기를 지정할 때 사용합니다.

외삽(Extrapolation) – 수학적인 개념으로, 알려진 데이터 지점들을 기반으로 하여 알려지지 않은 값을 예측하는 방법

참고
정적 최적화와 보간이 모두 표시된 고스트는 절대 외삽되지 않습니다.
정적 최적화된 고스트는 변경되지 않은 경우 스냅샷 업데이트를 전송하지 않기 때문에 ‘이 지속적으로 변화하는 값이 변화를 멈췄다’와 ‘아직 다음 연속 값을 받지 못했다’를 구별할 수 없습니다.

GhostField 상속

기본 타입이 아닌 필드 타입에 [GhostField]가 지정된 경우, 해당 속성(및 일부 속성)은 [GhostField]속성을 직접 구현하지 않는 모든 하위 필드에 자동으로 상속됩니다.

public struct Vector2
{
    public float x;
    [GhostField(Quantization=100)] public float y;
}

public struct MyComponent : IComponentData
{
    //Value.x는 상위 정의에서 지정한 양자화 값(1000)을 상속합니다.
    //Value.y는 원래 양자화 값(100)을 유지합니다.
    [GhostField(Quantized=1000)] public Vector2 Value;
}

참고- SubType 속성은 항상 기본값으로 재설정됩니다.

Component serialization

Component serialization 및 복제용으로 표시하려면 전송하려는 값에 [GhostField] 속성을 추가하세요.

public struct MySerializedComponent : IComponentData
{
    [GhostField]public int MyIntField;
    [GhostField(Quantization=1000)]public float MyFloatField;
    [GhostField(Quantization=1000, Smoothing=SmoothingAction.Interpolate)]public float2 Position;
    public float2 NonSerializedField;
    ...
}

컴포넌트가 직렬화되려면 컴포넌트 자체가 public으로 선언되어야 합니다.

컴포넌트의 public 멤버만 직렬화될 수 있습니다. private 멤버에 [GhostField]를 추가해도 효과가 없습니다.

Dynamic buffer serialization

버퍼를 직렬화 및 복제용으로 표시하려면 모든 public 필드에 [GhostField] 속성으로 주석을 달아야 합니다.

public struct SerialisedBuffer : IBufferElementData
{
    [GhostField]public int Field0;
    [GhostField(Quantization=1000)]public float Field1;
    [GhostField(Quantization=1000)]public float2 Position;
    public float2 NonSerialisedField; // public 필드에 [GhostField]가 없으면 오류가 발생 // 명시적인 오류
    private float2 NonSerialisedField; // 이것은 허용됩니다. 읽기 전에 클라이언트에서 이것을 설정해야 합니다. private이므로 직렬화 대상이 아닙니다.
    [GhostField(SendData=false)]public int NotSentAndUninitialised; // 이것은 허용됩니다. 읽기 전에 클라이언트에서 이것을 설정해야 합니다.
    ...
}

버퍼가 직렬화되려면 버퍼 자체가 public으로 선언되어야 합니다.

버퍼의 public 멤버만 직렬화될 수 있습니다. private 멤버에 [GhostField]를 추가해도 효과가 없습니다.

필드의 직렬화 및 복제를 건너뛰려면 SendData property을 사용할 수 있습니다.

이는 다음을 의미합니다:

복제되지 않는 필드의 값은 절대 변경되지 않습니다.
새 버퍼 요소의 경우 그 내용이 기본값으로 설정되지 않으며 내용은 정의되지 않습니다(어떤 값이든 될 수 있음).
동적 버퍼 필드는 SmoothingAction을 지원하지 않으므로 버퍼에서는 GhostFieldAttribute.Smoothing 및 GhostFieldAttribute.MaxSmoothingDistance 속성이 무시됩니다.

ICommandData 및 IInputComponentData 직렬화

입력 필드에 [GhostField]를 주석으로 달아 서버에서 클라이언트로 복제할 수 있습니다.

이는 예를 들어 로컬 머신에서 다른 플레이어의 캐릭터 컨트롤러에 대한 클라이언트 측 예측을 활성화하는 데 유용할 수 있습니다.

IInputComponentData를 사용한 자동화된 입력 동기화 시:

public struct MyCommand : IInputComponentData
{
    [GhostField] public int Value;
}

ICommandData는 IBufferElementData의 하위 클래스이며 서버에서 클라이언트로의 복제를 위해 직렬화될 수 있습니다.

따라서 버퍼와 동일한 규칙이 적용됩니다: 명령 버퍼가 직렬화되려면 모든 필드에 주석이 달려 있어야 합니다.

ICommandData 사용 시:

[GhostComponent()]
public struct MyCommand : ICommandData
{
    [GhostField] public NetworkTick Tick {get; set;}
    [GhostField] public int Value;
}

명령 데이터 직렬화는 원격 플레이어 예측을 구현하는 데 특히 유용합니다.

사용자 지정 타입에 대한 직렬화 지원 추가

GhostFieldAttribute로 직렬화할 수 있는 타입은 템플릿을 통해 지정됩니다.

기본적으로 지원되는 타입 목록은 Ghost 타입 템플릿 페이지를 참조하세요.

기본 지원 타입 외에도 다음을 수행할 수 있습니다:

새 타입에 대한 자체 템플릿 추가
타입에 대한 사용자 지정 직렬화 템플릿을 제공하고 GhostFieldAttribute의 SubType 속성을 사용하여 대상 지정

템플릿 작성 및 사용 방법에 대한 자세한 내용은 템플릿 사용 및 작성 방법을 참조하세요.

추가 리소스

GhostFieldAttribute로 직렬화할 수 있는 타입은 템플릿을 통해 지정됩니다.

GhostComponentAttribute를 사용한 복제 사용자 지정

https://docs.unity3d.com/Packages/com.unity.netcode@1.5/manual/ghostcomponentattribute.html

GhostComponentAttribute와 그 속성을 사용하여 런타임에서 복제가 처리되는 방식을 사용자 지정할 수 있습니다.

GhostComponentAttribute를 사용하기 전에 먼저 GhostComponentAttribute로 컴포넌트에 주석을 달아 직렬화 및 복제 대상으로 표시해야 합니다.

GhostComponentAttribute 속성

GhostComponentAttribute를 사용하여 복제를 수정하는 방법을 사용자 지정하려면 다음 속성을 사용하세요. 자세한 내용은 GhostComponentAttribute API 문서를 참조하세요.

속성 (Property)	기본값 (Default value)	설명 (Description)
`OwnerSendType`	`All`	`OwnerSendType` 속성은 ( `SendToOwnerType` 사용) 어떤 클라이언트 그룹에 구성 요소를 복제할지를 지정합니다. 예를 들어, 입력 명령을 자신의 플레이어에게만 복제하도록 설정할 수 있습니다.
`PrefabType`	`All`	`PrefabType` 속성은 ( `GhostPrefabType` 사용) 구성 요소가 어떤 프리팹 버전에서 사용 가능한지를 지정합니다. 예를 들어, 렌더링 관련 구성 요소를 서버 월드의 고스트 버전에서는 제거하는 데 사용할 수 있습니다.
`SendDataForChildEntity`	`false`	`SendDataForChildEntity` 속성은 고스트 엔티티의 자식에 붙은 구성 요소를 복제할지를 지정합니다. 고스트 자식 엔티티의 복제는 부모보다 훨씬 느리므로 주의가 필요합니다. 이 속성은 [GhostEnabledBit]에도 적용됩니다.
`SendTypeOptimization`	`AllClients`	`SendTypeOptimization` 속성은 ( `GhostSendType` 사용) 고스트가 예측(predicted)인지 보간(interpolated)인지에 따라 구성 요소 복제를 제어합니다. 예를 들어, 실제로 고스트의 물리 상태를 예측할 때만 `PhysicsVelocity`를 복제하도록 설정할 수 있습니다.

[GhostComponent(PrefabType=GhostPrefabType.All, SendTypeOptimization=GhostSendType.OnlyInterpolatedClients, SendDataForChildEntity=false)]
public struct MyComponent : IComponentData
{
    [GhostField(Quantized=1000)] public float3 Value;
}

OwnerSendType 세부 정보

소유권에 기반하여 컴포넌트가 복제되는 클라이언트를 지정하려면 GhostComponentAttribute의 OwnerSendType 속성을 사용하세요.

OwnerSendType은 SendToOwnerType에 정의된 대로 다음 중 하나일 수 있습니다.

None: 컴포넌트가 어떤 클라이언트에도 복제되지 않습니다.
All: 컴포넌트가 모든 클라이언트에 복제됩니다.
SendToOwner: 컴포넌트는 고스트를 소유한 클라이언트에만 복제됩니다.
SendToNonOwner: 컴포넌트는 고스트를 소유한 클라이언트를 제외한 모든 클라이언트에 복제됩니다.

PrefabType 세부 정보

컴포넌트가 사용 가능한 고스트 프리팹 버전을 지정하려면 GhostComponentAttribute의 PrefabType 속성을 사용하세요.

PrefabType은 GhostPrefabType에 정의된 대로 다음 중 하나일 수 있습니다.

None: 컴포넌트가 어떤 고스트 프리팹 유형에서도 사용할 수 없습니다.
All: 컴포넌트가 서버와 모든 클라이언트에서 사용 가능합니다.
Server: 컴포넌트는 서버에서만 사용 가능합니다.
Client: 고스트가 예측되든 보간되든 관계없이 컴포넌트는 클라이언트에서만 사용 가능합니다.
AllPredicted: 컴포넌트는 서버와 고스트가 예측되는 클라이언트에서 사용 가능합니다.
PredictedClient: 컴포넌트는 고스트가 예측되는 클라이언트에서만 사용 가능합니다.
InterpolatedClient: 컴포넌트는 고스트가 보간되는 클라이언트에서만 사용 가능합니다.

예를 들어, RenderMesh에 [GhostComponent(PrefabType=GhostPrefabType.Client)]를 추가하면 고스트는 서버 월드에 인스턴스화될 때 RenderMesh를 가지지 않지만 클라이언트 월드에 인스턴스화될 때는 가지게 됩니다.

참고
따라서 런타임 예측 전환은 예측 모드가 변경됨에 따라 고스트에서 라이브로 컴포넌트를 추가하고 제거할 수 있는 가능성이 있습니다.

SendDataForChildEntity 세부 정보

컴포넌트가 고스트 엔터티의 자식에 연결된 경우 복제할지 여부를 지정하려면 GhostComponentAttribute의 SendDataForChildEntity 속성을 사용하세요.

자식 엔터티를 직렬화하고 복제하는 것은 계산 비용이 많이 드므로 이 속성의 기본값은 false입니다.

SendTypeOptimization 세부 정보

고스트가 해당 클라이언트에서 보간되거나 예측되는지에 따라 컴포넌트가 복제되는 클라이언트를 지정하려면 GhostComponentAttribute의 SendTypeOptimization 속성을 사용하세요.

SendTypeOptimization은 GhostSendType에 정의된 대로 다음 중 하나일 수 있습니다.

DontSend: 컴포넌트가 어떤 클라이언트에도 복제되지 않습니다. 엔티티용 Netcode는 데이터를 수신하지 않는 클라이언트에서 컴포넌트를 수정하지 않습니다.
AllClients: 컴포넌트가 모든 클라이언트에 복제됩니다.
OnlyPredictedClients: 컴포넌트는 고스트를 예측하는 클라이언트에만 복제됩니다.
OnlyInterpolatedClients: 컴포넌트는 고스트를 보간하는 클라이언트에만 복제됩니다.

참고
SendTypeOptimization 및/또는 OwnerSendType을 설정하여 컴포넌트를 복제해야 하는 클라이언트 유형을 지정해도 프리팹의 컴포넌트 존재에는 영향을 미치지 않으며, 데이터를 수신하지 않은 클라이언트의 컴포넌트를 수정하지도 않습니다.

추가 리소스

The post Unity Netcode for Entities – Synchronizing states and inputs (1) appeared first on 어제와 내일의 나 그 사이의 이야기.

Unity Netcode for Entities – Connecting server and clients

lycos7560 — Thu, 01 May 2025 06:21:00 +0000

Connecting server and clients
연결 확인 Sample 코드

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

주제	설명
서버와 클라이언트 연결 Connecting server and clients	Netcode for Entities는 Unity Transport 패키지를 사용하여 연결을 관리합니다. 각 연결은 하나의 엔티티로 저장되며, 해당 엔티티는 `NetworkStreamConnection` 컴포넌트를 포함하고 있어, 연결에 사용되는 Transport 핸들을 참조합니다. 이 엔티티의 이름은 일반적으로 `'NetworkConnection [nid]'` 형식입니다.
상태 및 입력 동기화 Synchronizing states and inputs	Netcode는 고스트(ghost) 상태와 입력/명령을 동기화합니다. 이 항목에서는 지원되는 타입 목록과, 어떤 필드와 컴포넌트를 eventual consistency 모델을 통해 복제할지 표시하는 방법(마크업)을 설명합니다.
시간 동기화 Time synchronization	Netcode는 서버 권한 모델(server authoritative model) 을 사용합니다. 서버는 고정된 시간 간격으로 시뮬레이션을 실행하며, 이 간격은 마지막 업데이트 이후 경과한 시간에 따라 결정됩니다. 따라서 클라이언트는 항상 서버 시간과 동기화되어야 이 모델이 제대로 작동합니다.
보간 및 예측보간 Interpolation and extrapolation	게임에서 보간(interpolation) 및 예측보간(extrapolation) 을 사용하여, 불안정한 네트워크 환경에서도 부드러운 게임플레이 경험을 제공할 수 있습니다.
예측 Prediction	게임의 지연(latency)을 보완하기 위해 예측 로직을 사용할 수 있습니다. 예측은 클라이언트가 로컬에서 먼저 행동을 시뮬레이션하고, 이후 서버로부터 확정된 결과를 받는 방식입니다.
물리 Physics	Netcode 패키지는 Unity Physics와의 일부 통합 기능을 제공합니다. 이를 통해 네트워크 환경에서도 물리 기반 오브젝트를 보다 쉽게 사용할 수 있습니다. 이 통합 기능은 predicted ghosts와 interpolated ghosts 양쪽 모두에 대한 물리 처리를 지원합니다.

서버와 클라이언트 연결

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());
                drvQuery.GetSingletonRW().ValueRW.RequireConnectionApproval = sceneName.Contains("ConnectionApproval", StringComparison.OrdinalIgnoreCase);
                drvQuery.GetSingletonRW().ValueRW.Listen(ep);
            }

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

2⃣ AutoConnectPort 사용 (Using the AutoConnectPort)

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

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

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

PlayMode Tools

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

NetworkStreamDriver 싱글톤을 통해 제공되는 ConnectionEventsForTick (형식: NativeArray.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().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

상태	호출 규칙
Unknown	절대 발생하지 않음
Connecting	자신의 클라이언트에서 한 번 발생. `NetworkStreamReceiveSystem`이 `Connect` 호출을 인식한 시점 (호출 프레임 다음일 수 있음)
Handshake	내부 transport 드라이버가 `Connected` 상태에 진입하면 한 번 발생
Approval	연결 승인 기능이 활성화된 경우에만 발생. Handshake 이후
Connected	서버가 `NetworkId`를 보내면 발생
Disconnected	연결 종료 또는 타임아웃 또는 서버에 의해 연결 해제 시 발생. `DisconnectReason`이 설정됨

주의 :

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

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

2⃣ NetCodeConnectionEvents on the server

상태	호출 규칙
Unknown	절대 발생하지 않음
Connecting	클라이언트가 연결을 시작하는 순간을 서버는 알 수 없으므로 발생하지 않음
Handshake	모든 클라이언트에 대해 발생. transport 연결이 수락되면 진입
Approval	승인 기능이 활성화된 경우에만 발생. Handshake 성공 후
Connected	클라이언트가 `NetworkId`를 부여받는 순간 발생
Disconnected	클라이언트가 연결 해제되거나 타임아웃되면 발생. `DisconnectReason` 설정됨

주의 :

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

Connection approval

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

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

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

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

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

다시 강조하면:

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

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

if (isServer)
{
    using var drvQuery = server.EntityManager.CreateEntityQuery(ComponentType.ReadWrite());
    drvQuery.GetSingletonRW().ValueRW.RequireConnectionApproval = true;
    drvQuery.GetSingletonRW().ValueRW.Listen(ep);
}
else
{
    using var drvQuery = client.EntityManager.CreateEntityQuery(ComponentType.ReadWrite());
    drvQuery.GetSingletonRW().ValueRW.RequireConnectionApproval = true;
    drvQuery.GetSingletonRW().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();
    }

    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>().WithNone().WithNone().WithEntityAccess())
        {
            var sendApprovalMsg = ecb.CreateEntity();
            ecb.AddComponent(sendApprovalMsg, new ApprovalFlow { Payload = "ABC" });
            ecb.AddComponent(sendApprovalMsg);

            ecb.AddComponent(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,RefRW>().WithEntityAccess())
        {
            var connectionEntity = receiveRpc.ValueRO.SourceConnection;
            if (approvalMsg.ValueRO.Payload.Equals("ABC"))
            {
                ecb.AddComponent(connectionEntity);

                // Destroy RPC message
                ecb.DestroyEntity(entity);
            }
            else
            {
                // Failed approval messages should be disconnected
                ecb.AddComponent(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 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());
            server.EntityManager.SetName(networkStreamEntity, "NetworkStreamRequestListen");
            server.EntityManager.SetComponentData(networkStreamEntity,
                new NetworkStreamRequestListen { Endpoint = NetworkEndpoint.AnyIpv4 });

            networkStreamEntity =
                client.EntityManager.CreateEntity(ComponentType.ReadWrite());
            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());
            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 어제와 내일의 나 그 사이의 이야기.

Unity Netcode for Entities – Client / Server worlds

lycos7560 — Thu, 01 May 2025 00:50:19 +0000

Client / Server worlds Setting
- 클라이언트 / 서버 World 네트워크 모델
- 네트워크 프로토콜 검사
  - 개발 중 발생할 수 있는 문제
    - 프로토콜 검사 해제
  - Additional resources

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()) != 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

네트워크 프로토콜 검사

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

Unity Transport 2.5.1 Docs

lycos7560 — Wed, 30 Apr 2025 21:19:50 +0000

목차 테이블

API

https://docs.unity3d.com/Packages/com.unity.transport@2.5/api/index.html

Unity Transport?

Unity Transport 2.5.1

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/index.html

Unity Transport는 멀티플레이어 게임 개발을 위한 저수준 네트워킹 라이브러리입니다.

Unity의 두 가지 Netcode 솔루션인 Netcode for GameObjects(NFG)와 Netcode for Entities(NFE)의 기반으로 사용됩니다.

또한 사용자가 직접 만든 커스텀 네트워크 솔루션과 함께 사용할 수 있습니다.

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/index.html

Unity 엔진에서 지원하는 모든 플랫폼은 UDP 소켓 또는 WebSocket을 통해 제공되는 연결 기반 추상화 계층(내장 네트워크 드라이버) 덕분에 Unity Transport에서 원활하게 지원됩니다.

둘 다 암호화 유무에 따라 설정할 수 있으며, 위 블록 다이어그램에서 닫힌 자물쇠와 열린 자물쇠로 표시됩니다.

특히 파이프라인은 안정성, 패킷 순서 지정 및 패킷 조각화와 같은 추가적인 선택적 기능들을 제공합니다.

요구 사항

Unity Transport는 Unity 엔진이 지원하는 모든 플랫폼을 지원합니다.

WebGL의 경우, 클라이언트 모드에서 WebSocket 연결만 지원되며, Unity Relay를 사용하는 경우에는 호스팅도 가능합니다.

현재 문서는 Unity Transport 2.X 버전에 대한 설명이며, 이는 Unity Editor 2022.3 이상에서만 호환됩니다.

구 버전의 에디터는 Transport 1.X에서 지원됩니다. 아래는 호환성 표를 참고하세요.

Editor Version	2021 LTS	2022 LTS	2023.1 and later
Transport 1.X	Yes	Yes	No
Transport 2.X	No	Yes	Yes

참고사항

이 패키지는 Netcode for GameObjects의 NetworkTransport 추상화 계층과 혼동하면 안됩니다.

더 자세한 내용은 해당 transports section of its documentation을 참고하세요.

Sample Project

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/samples-usage.html

Unity Transport 패키지에는 Samples 폴더가 포함되어 있으며, 이 폴더에는 라이브러리의 기본적인 개념을 설명하는 간단한 어셈블리 정의와 관련된 씬들이 들어 있습니다.

이 샘플들은 패키지 매니저 창에서 Unity Transport 패키지를 선택했을 때 가져올 수 있습니다.

Unity Transport Sample

Cross-play Example : MultiNetworkDriver를 사용하여 UDP와 WebSocket 연결을 모두 허용하는 서버를 만드는 방법의 예입니다.
Jobified Client and Server : 작업을 사용하는 매우 간단한 클라이언트 및 서버 구현. 패키지 문서와 연계되도록 설계되었습니다.
Ping Sample : 클라이언트와 서버 간 왕복 시간(핑)을 계산하는 소규모 애플리케이션입니다.
Relay Sample(with Relay) : 유니티 릴레이를 사용하여 클라이언트와 호스트 간의 왕복 시간(핑)을 계산하는 작은 애플리케이션
SimpleClientServer : 가장 간단한 클라이언트 및 서버 구현. 패키지 문서와 연계되도록 설계되었습니다.

간단한 클라이언트 서버

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/client-server-simple.html

이 예제는 Unity Transport 패키지의 모든 주요 기능을 다루며, 다음과 같은 API 사용법을 보여주는 샘플 프로젝트를 만드는 데 도움을 줍니다:

전송 구성 (Configure the transport)
연결 수립 (Establish a connection)
데이터 전송 (Send data)
데이터 수신 (Receive data)
연결 종료 (Close a connection)

원격 “덧셈(add)” 기능을 구현

1⃣ 서버 생성

서버는 들어오는 연결 요청을 듣고 메시지를 주고받는 엔드포인트를 생성합니다.

ServerBehaviour.cs

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class ServerBehaviour : MonoBehaviour {

    // Use this for initialization
    void Start () {

    }

    // Update is called once per frame
    void Update () {

    }
}

2⃣ 보일러플레이트 코드 (Boilerplate Code)

반복되는 작업이나 패턴에 대한 일종의 표준화된 코드인 Boilerplate를 생성합니다.

이 패키지는 완전한 제어권을 가지도록 선택한 아키텍처 설계로 저수준 API만 제공합니다.

따라서 약간의 Boilerplate 코드를 설정해야합니다.

1. NetworkDriver 선언 – Server

ServerBehaviour.cs

using UnityEngine;
using Unity.Collections;
using Unity.Networking.Transport;

public class ServerBehaviour : MonoBehaviour 
{
    NetworkDriver m_Driver;
    NativeList m_Connections;
}

NetworkDriver: Unity Transport 패키지의 핵심 API로, 네트워크 통신을 제어합니다.
NativeList: 서버에 연결된 클라이언트들의 연결 정보를 저장하는 컨테이너 (Unmanaged Memory 사용).

2. 서버 초기화 (Start) – Server

void Start()
{
    m_Driver = NetworkDriver.Create();
    m_Connections = new NativeList(16, Allocator.Persistent);

    var endpoint = NetworkEndpoint.AnyIpv4.WithPort(7777);
    if (m_Driver.Bind(endpoint) != 0)
    {
        Debug.LogError("Failed to bind to port 7777.");
        return;
    }
    m_Driver.Listen();
}

드라이버 생성 → 연결 리스트 초기화 (최대 16개 연결 수용)
모든 IPv4 주소(AnyIpv4)에서 7777 포트로 바인딩 시도
성공 시 Listen()으로 클라이언트 연결 대기 시작.

3. 리소스 정리 (OnDestroy) – Server

void OnDestroy() 
{
    if (m_Driver.IsCreated) {
        m_Driver.Dispose();
        m_Connections.Dispose();
    }
}

Unmanaged Memory를 직접 해제해야 메모리 누수 방지
IsCreated로 할당 여부 확인 후 해제

4. 서버 업데이트 루프 (Update) – Server

void Update() 
{
    m_Driver.ScheduleUpdate().Complete();

    // 1. 오래된 연결 정리
    for (int i = 0; i < m_Connections.Length; i++) {
        if (!m_Connections[i].IsCreated) {
            m_Connections.RemoveAtSwapBack(i);
            i--;
        }
    }

    // 2. 새 연결 수락
    NetworkConnection c;
    while ((c = m_Driver.Accept()) != default) {
        m_Connections.Add(c);
        Debug.Log("클라이언트 연결 수락");
    }

    // 3. 연결별 이벤트 처리
    for (int i = 0; i < m_Connections.Length; i++) {
        DataStreamReader stream;
        NetworkEvent.Type cmd;
        while ((cmd = m_Driver.PopEventForConnection(m_Connections[i], out stream)) 
               != NetworkEvent.Type.Empty) {
            
            if (cmd == NetworkEvent.Type.Data) {
                uint number = stream.ReadUInt();
                Debug.Log($"클라이언트로부터 {number} 수신, +2 처리");

                number += 2;
                m_Driver.BeginSend(NetworkPipeline.Null, m_Connections[i], out var writer);
                writer.WriteUInt(number);
                m_Driver.EndSend(writer);
            }
            else if (cmd == NetworkEvent.Type.Disconnect) {
                Debug.Log("클라이언트 연결 종료");
                m_Connections[i] = default;
            }
        }
    }
}

데이터 수신: 클라이언트가 보낸 숫자를 읽어 +2 후 재전송.
연결 종료: Disconnect 이벤트 시 연결 리셋.

3⃣ 클라이언트 구현 (차이점 중심) – Client

ClientBehaviour.cs

public class ClientBehaviour : MonoBehaviour {
    NetworkDriver m_Driver;
    NetworkConnection m_Connection; // 단일 연결만 관리

    void Start() {
        m_Driver = NetworkDriver.Create();
        m_Connection = m_Driver.Connect(NetworkEndpoint.LoopbackIpv4.WithPort(7777));
    }

    void Update() {
        m_Driver.ScheduleUpdate().Complete();

        if (!m_Connection.IsCreated) return;

        DataStreamReader stream;
        NetworkEvent.Type cmd;
        while ((cmd = m_Connection.PopEvent(m_Driver, out stream)) 
               != NetworkEvent.Type.Empty) {
            
            if (cmd == NetworkEvent.Type.Connect) {
                Debug.Log("서버 연결 성공");
                uint value = 1;
                m_Driver.BeginSend(m_Connection, out var writer);
                writer.WriteUInt(value);
                m_Driver.EndSend(writer);
            }
            else if (cmd == NetworkEvent.Type.Data) {
                uint value = stream.ReadUInt();
                Debug.Log($"서버로부터 값 수신: {value}");
                m_Connection.Disconnect(m_Driver);
                m_Connection = default;
            }
            else if (cmd == NetworkEvent.Type.Disconnect) {
                Debug.Log("서버와 연결 종료");
                m_Connection = default;
            }
        }
    }
}

클라이언트 특이사항:

단일 연결: NetworkConnection 하나만 관리.
Connect 이벤트: 연결 성공 시 서버로 숫자 1 전송.
데이터 처리: 서버 응답 후 즉시 연결 종료.

중요:

모든 네트워크 작업은 비동기 Job 시스템 기반으로 동작하지만, 이 예제에서는 Complete()로 강제 동기화하여 간단히 구현했습니다.

실제 프로젝트에서는 Job 체인을 활용한 최적화가 필요합니다.

ServerBehaviour.cs

using Unity.Collections;
using Unity.Networking.Transport;
using UnityEngine;

namespace UnityNetworkingTransportSimpleTest
{
    public class ServerBehaviour : MonoBehaviour
    {

        NetworkDriver m_Driver;
        NativeList m_Connections; // 연결된 클라이언트 목록

        private void Start()
        {
            m_Driver = NetworkDriver.Create(); // NetworkDriver 생성
            m_Connections = new NativeList(16, Allocator.Persistent); // 최대 16개의 연결을 허용하는 NativeList 생성 (영구 할당)

            var endpoint = NetworkEndpoint.AnyIpv4.WithPort(7777); // 모든 IPv4 주소의 7777 포트에서 수신 대기
            if (m_Driver.Bind(endpoint) != 0)
            {
                Debug.LogError("포트 7777 바인딩 실패"); // 포트 바인딩 실패 시 에러 로그 출력
                return;
            }
            m_Driver.Listen(); // 들어오는 연결 요청 수신 시작
        }

        private void Update()
        {
            m_Driver.ScheduleUpdate().Complete(); // 네트워크 업데이트 스케줄링 및 완료

            // 1. 오래된 연결 정리
            for (int i = 0; i < m_Connections.Length; i++)
            {
                if (!m_Connections[i].IsCreated) { // 연결이 끊어진 클라이언트 정리
                    m_Connections.RemoveAtSwapBack(i); // 연결 리스트에서 제거
                    i--; // 인덱스 조정
                }
            }

            // 2. 새 연결 수락
            NetworkConnection newNetworkConnection;
            while ((newNetworkConnection = m_Driver.Accept()) != default)
            {
                m_Connections.Add(newNetworkConnection); // 새로운 연결을 연결 리스트에 추가
                Debug.Log("클라이언트 연결 수락"); // 클라이언트 연결 수락 시 로그 출력
            }

            // 3. 연결별 이벤트 처리
            for (int i = 0; i < m_Connections.Length; i++)
            {
                DataStreamReader stream;
                NetworkEvent.Type cmd;
                while ((cmd = m_Driver.PopEventForConnection(m_Connections[i], out stream)) != NetworkEvent.Type.Empty)
                {

                    if (cmd == NetworkEvent.Type.Data)
                    {
                        uint number = stream.ReadUInt(); // 수신된 데이터에서 unsigned integer 값 읽기
                        Debug.Log($"클라이언트로부터 {number} 수신, +2 처리"); // 클라이언트로부터 받은 값 로그 출력 및 처리 내용 설명

                        number += 2; // 받은 값에 2를 더함
                        m_Driver.BeginSend(NetworkPipeline.Null, m_Connections[i], out var writer); // 클라이언트에게 메시지 전송 시작 (신뢰성 없는 파이프라인 사용)
                        writer.WriteUInt(number); // 처리된 unsigned integer 값 쓰기
                        m_Driver.EndSend(writer); // 메시지 전송 완료
                    }
                    else if (cmd == NetworkEvent.Type.Disconnect)
                    {
                        Debug.Log("클라이언트 연결 종료"); // 클라이언트 연결이 종료되었을 때 로그 출력
                        m_Connections[i] = default; // 연결 상태 초기화
                    }
                }
            }
        }

        private void OnDestroy()
        {
            if (m_Driver.IsCreated)
            {
                m_Driver.Dispose(); // NetworkDriver 자원 해제
                m_Connections.Dispose(); // 연결 리스트 자원 해제
            }
        }
    }
}

ClientBehaviour.cs

using Unity.Collections;
using Unity.Networking.Transport;
using UnityEngine;

namespace UnityNetworkingTransportSimpleTest
{
    public class ClientBehaviour : MonoBehaviour
    {
        NetworkDriver m_Driver;
        NetworkConnection m_Connection; // 클라이언트는 단일 연결만 관리

        private void Start()
        {
            m_Driver = NetworkDriver.Create(); // NetworkDriver 생성
            m_Connection = m_Driver.Connect(NetworkEndpoint.LoopbackIpv4.WithPort(7777)); // 루프백 주소의 7777 포트로 서버에 연결 시도
        }

        private void Update()
        {
            m_Driver.ScheduleUpdate().Complete(); // 네트워크 업데이트 스케줄링 및 완료

            if (!m_Connection.IsCreated) return; // 연결이 생성되지 않았으면 더 이상 진행하지 않음

            DataStreamReader stream;
            NetworkEvent.Type cmd;
            while ((cmd = m_Connection.PopEvent(m_Driver, out stream)) != NetworkEvent.Type.Empty) { // 연결에서 발생한 네트워크 이벤트 처리

                if (cmd == NetworkEvent.Type.Connect)
                {
                    Debug.Log("서버 연결 성공"); // 서버 연결 성공 시 로그 출력
                    uint value = 1;
                    m_Driver.BeginSend(m_Connection, out var writer); // 메시지 전송 시작
                    writer.WriteUInt(value); // unsigned integer 값 쓰기
                    m_Driver.EndSend(writer); // 메시지 전송 완료
                }
                else if (cmd == NetworkEvent.Type.Data)
                {
                    uint value = stream.ReadUInt(); // 수신된 데이터에서 unsigned integer 값 읽기
                    Debug.Log($"서버로부터 값 수신: {value}"); // 서버로부터 받은 값 로그 출력
                    m_Connection.Disconnect(m_Driver); // 서버와 연결 종료
                    m_Connection = default; // 연결 상태 초기화
                }
                else if (cmd == NetworkEvent.Type.Disconnect)
                {
                    Debug.Log("서버와 연결 종료"); // 서버와 연결이 종료되었을 때 로그 출력
                    m_Connection = default; // 연결 상태 초기화
                }
            }
        }
    }
}

사용 모범 사례

1⃣ 파이프라인 사용 (Using pipelines)

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/pipelines-usage.html

파이프라인(Pipelines)은 Unity Transport의 핵심 기능으로, 기본 제공되는 비신뢰성 데이터그램(unreliable datagrams) 위에 선택적 기능 계층을 추가할 수 있게 해줍니다.

주요 적용 기능: 순서 보장(sequencing), 신뢰성(reliability), 패킷 분할(fragmentation) 등.

작동 원리 (How it Works)

파이프라인은 하나 이상의 스테이지로 구성된 순서로 정의됩니다.

메시지가 파이프라인을 통해 전송되면 스테이지를 순서대로 거치며, 첫 번째 스테이지의 출력이 두 번째 스테이지로 파이프됩니다.

따라서 첫 번째 스테이지에서 패킷에 헤더를 추가하면 두 번째 스테이지는 이 헤더를 포함한 전체 패킷을 처리합니다.

메시지가 수신되면 스테이지 체인을 역순으로 거칩니다.

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/pipelines-usage.html

예를 들어 FragmentationPipelineStage는 큰 메시지를 더 작은 조각으로 나누는 것을 가능하게 하고,

ReliableSequencedPipelineStage는 메시지를 순서와 전달을 보장하며 전송하는 것을 가능하게 합니다.

두 기능 모두를 제공하는 파이프라인을 만들고 싶다면 다음과 같이 만들 수 있습니다.

// In initialization code, before any connections are made.
var myPipeline = driver.CreatePipeline(typeof(FragmentationPipelineStage), typeof(ReliableSequencedPipelineStage));

이렇게 하면 메시지를 먼저 패킷에 맞게 더 작은 조각으로 분할한 다음, 각 조각이 신뢰성 있게 그리고 올바른 순서대로 전달되는 파이프라인이 생성됩니다.

이 과정은 아래 그림과 같이 설명됩니다. 조각에 있는 작은 주황색 부분은 순서 번호와 신뢰성 단계에서 추가된 기타 정보를 나타냅니다.

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/pipelines-usage.html

단계의 순서가 중요하다는 점에 유의하세요.

만약 단계를 거꾸로 구성했다면, 신뢰성 정보는 분할되지 않은 큰 메시지에만 추가되었을 것입니다.

이 경우, 조각 중 하나라도 손실되면 전체 메시지를 다시 전송해야 하므로 대역폭 효율이 떨어집니다.

하지만 신뢰성 단계(reliable stage)를 분할 단계(fragmentation) 이후에 배치하면, 조각 하나가 손실되더라도 그 조각만 다시 전송하면 되므로 더 효율적입니다.

새로운 파이프라인에서 메시지를 전송하려면

BeginSend를 사용할 수 있습니다:

driver.BeginSend(myPipeline, connection, out var writer);

메시지를 어느 파이프라인으로 받았는지 확인하려면

PopEvent 또는 PopEventForConnection의 마지막 인자를 사용하세요:

var eventType = driver.PopEvent(out _, out _, out var receivePipeline);
if (eventType == NetworkEvent.Type.Data)
{
    // 데이터 메시지는 receivePipeline 파이프라인에서 수신되었습니다.
}

주의

파이프라인은 서버와 클라이언트에서 항상 같은 방식으로 구성되어야 합니다.

즉, CreatePipeline 호출과 그 순서는 양쪽에서 동일해야 합니다.

Unity Transport는 이러한 불일치를 자동으로 막아주지 않으므로, 파이프라인 생성 코드는 서버와 클라이언트 간에 공유하는 것을 권장합니다.

Fragmentation 파이프라인 단계

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/pipelines-usage.html

기본적으로 Unity Transport는 MTU(약 1400바이트) 안에 들어가는 크기의 메시지만 전송할 수 있습니다.

더 큰 메시지를 보내기 위해서는 이를 더 작은 조각으로 분할해야 하며, 이를 메시지 분할(Fragmentation) 이라고 합니다.

FragmentationPipelineStage가 포함된 파이프라인을 구성하면, 메시지를 자동으로 분할해 줍니다.

분할 전 최대 페이로드 크기는 NetworkDriver를 생성할 때 설정할 수 있습니다:

var settings = new NetworkSettings();
settings.WithFragmentationStageParameters(payloadCapacity: 10000);

var driver = NetworkDriver.Create(settings);
var fragmentedPipeline = driver.CreatePipeline(typeof(FragmentationPipelineStage));

설정 가능한 최대 값은 약 20MB이지만, 이 파이프라인 단계는 수 킬로바이트 크기의 페이로드에 최적화되어 있습니다.

기본값은 4096바이트이며, 이보다 훨씬 큰 메시지는 초기화 시점에 한 번 보내는 정도로만 사용하는 것을 권장합니다.

참고:

여러 파이프라인 단계를 조합할 경우, FragmentationPipelineStage는 일반적으로 가장 먼저 배치되어야 합니다.

대부분의 파이프라인 단계는 MTU보다 큰 패킷을 지원하지 않기 때문입니다.

The reliable 파이프라인 단계

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/pipelines-usage.html

ReliableSequencedPipelineStage를 사용한 파이프라인은 TCP처럼 패킷의 순서 보장과 안정적인 전송을 보장합니다.

패킷은 시퀀스 번호로 태그되며, 상대는 이 번호의 수신을 확인합니다.
수신 확인이 되지 않으면 패킷은 재전송됩니다.
순서가 어긋난 패킷은 버퍼에 저장되고, 이전 패킷이 도착할 때까지 대기합니다.

이 기능은 유용하지만, 멀티플레이어 게임에서는 과도하게 사용하면 성능에 악영향을 줄 수 있습니다.

신뢰성 있는 데이터 스트림은 헤드 오브 라인 블로킹(Head-of-line blocking) 으로 인해 지연이 발생할 수 있습니다.

따라서 정말 중요한 데이터 (예: RPC 호출, 캐릭터 동작 등)에만 이 단계를 사용하는 것을 권장합니다.

동시 전송 가능한 패킷 수 제한

Reliable 단계는 동시에 전송 가능한 패킷 수가 제한됩니다.

기본값은 32개, 최대 64개까지 늘릴 수 있습니다.

이 제한은 연결별, 파이프라인별로 적용되며, 공유되지 않습니다.

팁: 가능한 한 신뢰성 있는 메시지를 배치(Batching) 하세요. 예: 20바이트짜리 메시지 2개를 따로 보내는 대신 40바이트로 묶어 한 번에 전송.

만약 이미 32개의 패킷이 전송 대기 중인 상황에서 또 보내려고 하면, EndSend는 NetworkSendQueueFull (값: -5)을 반환합니다.

이 경우 메시지를 큐에 저장하고 나중에 재전송하세요:

driver.BeginSend(myReliablePipeline, connection, out var writer);
// 메시지 작성
if (driver.EndSend(writer) == (int)Error.StatusCode.NetworkSendQueueFull)
{
    // 메시지를 큐에 저장 후 나중에 재전송
}

// 제한 늘리기

var settings = new NetworkSettings();
settings.WithReliableStageParameters(windowSize: 64);


var driver = NetworkDriver.Create(settings);
var reliablePipeline = driver.CreatePipeline(typeof(ReliableSequencedPipelineStage));

// 기본값은 32, 최대는 64입니다.
// 32보다 큰 값을 사용할 경우 헤더 크기가 약간 증가(4바이트) 하며, 실제 데이터 공간은 그만큼 줄어듭니다.

The reliable 파이프라인 단계

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/pipelines-usage.html

SimulatorPipelineStage는 앱 테스트용으로 사용되며, 패킷 손실, 지연, 지터 등의 다양한 네트워크 조건을 시뮬레이션할 수 있습니다.

var settings = new NetworkSettings();
settings.WithSimulatorStageParameters(
    maxPacketCount: 100,
    mode: ApplyMode.AllPackets,
    packetDelayMs: 50);

var driver = NetworkDriver.Create(settings);
var simulatorPipeline = driver.CreatePipeline(typeof(SimulatorPipelineStage));


// maxPacketCount: 지연 가능한 최대 패킷 수. 이 수를 초과하면 지연 없이 전달됩니다.
// mode: 어떤 방향에 시뮬레이션을 적용할지 설정 (보내기, 받기, 또는 모두).
// packetDelayMs: 적용할 지연 시간 (ms). 일반 브로드밴드는 20ms, 열악한 모바일은 최대 200ms.
// packetJitterMs: 지연의 편차. 일반적으로 지연의 절반 이하가 적당합니다.
// packetDropPercentage: 손실할 패킷의 비율 (%). 나쁜 모바일 환경에서도 보통 3%를 넘지 않습니다.

참고:

여러 단계로 구성된 파이프라인에서 SimulatorPipelineStage는 가장 마지막에 배치해야 합니다.

그렇지 않으면 다른 단계에서 처리되기 전에 패킷이 손실되어 의미가 없어질 수 있습니다 (예: Reliable 단계와 함께 사용할 경우).

2⃣ Jobified 클라이언트 및 서버

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/client-server-jobs.html

Client 코드 (JobifiedClientBehaviour.cs)

using UnityEngine;
using Unity.Jobs;
using Unity.Collections;
using Unity.Networking.Transport;

namespace Unity.Networking.Transport.Samples
{
    public class JobifiedClientBehaviour : MonoBehaviour
    {
        NetworkDriver m_Driver;
        NativeArray m_Connection;

        JobHandle m_ClientJobHandle;

        void Start()
        {
            // 네트워크 드라이버 생성 및 초기화
            m_Driver = NetworkDriver.Create();
            m_Connection = new NativeArray(1, Allocator.Persistent);

            // 로컬 호스트(127.0.0.1)의 포트 7777에 연결 시도
            var endpoint = NetworkEndpoint.LoopbackIpv4.WithPort(7777);
            m_Connection[0] = m_Driver.Connect(endpoint);
        }

        void OnDestroy()
        {
            // 이전 프레임의 잡이 모두 완료되도록 대기 후, 네이티브 리소스 해제
            m_ClientJobHandle.Complete();
            m_Driver.Dispose();
            m_Connection.Dispose();
        }

        void Update()
        {
            // 이전 프레임에서 스케줄된 작업 완료 대기
            m_ClientJobHandle.Complete();

            // 클라이언트 업데이트 작업 생성 및 설정
            var job = new ClientUpdateJob
            {
                Driver = m_Driver,
                Connection = m_Connection,
            };

            // 네트워크 드라이버 업데이트 스케줄링
            m_ClientJobHandle = m_Driver.ScheduleUpdate();

            // 클라이언트 작업 스케줄링 (드라이버 업데이트 이후 실행되도록 설정)
            m_ClientJobHandle = job.Schedule(m_ClientJobHandle);
        }

        // 클라이언트 상태를 업데이트하는 IJob 기반 작업
        struct ClientUpdateJob : IJob
        {
            public NetworkDriver Driver;
            public NativeArray Connection;

            public void Execute()
            {
                // 연결이 유효하지 않으면 조기 종료
                if (!Connection[0].IsCreated)
                {
                    return;
                }

                DataStreamReader stream;
                NetworkEvent.Type cmd;

                // 이벤트 루프를 통해 네트워크 이벤트 처리
                while ((cmd = Connection[0].PopEvent(Driver, out stream)) != NetworkEvent.Type.Empty)
                {
                    if (cmd == NetworkEvent.Type.Connect)
                    {
                        Debug.Log("서버에 연결됨.");

                        // 서버에 uint 값 1을 전송
                        uint value = 1;
                        Driver.BeginSend(Connection[0], out var writer);
                        writer.WriteUInt(value);
                        Driver.EndSend(writer);
                    }
                    else if (cmd == NetworkEvent.Type.Data)
                    {
                        // 서버로부터 데이터를 수신하고 출력
                        uint value = stream.ReadUInt();
                        Debug.Log($"서버로부터 받은 값: {value}");

                        // 데이터 수신 후 연결 종료
                        Driver.Disconnect(Connection[0]);
                        Connection[0] = default;
                    }
                    else if (cmd == NetworkEvent.Type.Disconnect)
                    {
                        // 서버에서 연결이 종료되었음을 로그에 기록하고 상태 초기화
                        Debug.Log("서버와의 연결이 종료됨.");
                        Connection[0] = default;
                    }
                }
            }
        }
    }
}

Server 코드 (JobifiedServerBehaviour.cs)

using UnityEngine;
using Unity.Jobs;
using Unity.Collections;
using Unity.Networking.Transport;

namespace Unity.Networking.Transport.Samples
{
    public class JobifiedServerBehaviour : MonoBehaviour
    {
        NetworkDriver m_Driver;
        NativeList m_Connections;

        JobHandle m_ServerJobHandle;

        void Start()
        {
            // 네트워크 드라이버 생성 및 초기화
            m_Driver = NetworkDriver.Create();
            m_Connections = new NativeList(16, Allocator.Persistent);

            // 포트 7777에 바인딩 시도
            var endpoint = NetworkEndpoint.AnyIpv4.WithPort(7777);
            if (m_Driver.Bind(endpoint) != 0)
            {
                Debug.LogError("포트 7777 바인딩 실패.");
                return;
            }

            // 클라이언트 연결 대기 시작
            m_Driver.Listen();
        }

        void OnDestroy()
        {
            if (m_Driver.IsCreated)
            {
                // 모든 잡 완료 후 리소스 해제
                m_ServerJobHandle.Complete();
                m_Driver.Dispose();
                m_Connections.Dispose();
            }
        }

        void Update()
        {
            // 이전 프레임의 잡 완료 대기
            m_ServerJobHandle.Complete();

            // 끊긴 연결 제거 및 새 연결 수락을 처리하는 잡 생성
            var connectionJob = new ServerUpdateConnectionsJob
            {
                Driver = m_Driver,
                Connections = m_Connections
            };

            // 클라이언트별로 데이터 수신 및 응답을 처리하는 병렬 잡 생성
            var serverUpdateJob = new ServerUpdateJob
            {
                Driver = m_Driver.ToConcurrent(),
                Connections = m_Connections.AsDeferredJobArray()
            };

            // 드라이버 업데이트 → 연결 처리 → 데이터 처리 순으로 잡 체인 스케줄링
            m_ServerJobHandle = m_Driver.ScheduleUpdate();
            m_ServerJobHandle = connectionJob.Schedule(m_ServerJobHandle);
            m_ServerJobHandle = serverUpdateJob.Schedule(m_Connections, 1, m_ServerJobHandle);
        }

        // 끊긴 연결을 정리하고 새 연결을 수락하는 작업
        struct ServerUpdateConnectionsJob : IJob
        {
            public NetworkDriver Driver;
            public NativeList Connections;

            public void Execute()
            {
                // 유효하지 않은 연결 제거
                for (int i = 0; i < Connections.Length; i++)
                {
                    if (!Connections[i].IsCreated)
                    {
                        Connections.RemoveAtSwapBack(i);
                        i--;
                    }
                }

                // 새 클라이언트 연결 수락
                NetworkConnection c;
                while ((c = Driver.Accept()) != default)
                {
                    Connections.Add(c);
                    Debug.Log("클라이언트 연결 수락됨.");
                }
            }
        }

        // 각 연결로부터 데이터를 수신하고 처리하는 병렬 작업
        struct ServerUpdateJob : IJobParallelForDefer
        {
            public NetworkDriver.Concurrent Driver;
            public NativeArray Connections;

            public void Execute(int i)
            {
                DataStreamReader stream;
                NetworkEvent.Type cmd;

                // 클라이언트 이벤트 루프
                while ((cmd = Driver.PopEventForConnection(Connections[i], out stream)) != NetworkEvent.Type.Empty)
                {
                    if (cmd == NetworkEvent.Type.Data)
                    {
                        // 숫자 수신 후 2를 더해 응답
                        uint number = stream.ReadUInt();
                        Debug.Log($"클라이언트로부터 {number} 수신. 2를 더해 전송.");

                        number += 2;

                        Driver.BeginSend(Connections[i], out var writer);
                        writer.WriteUInt(number);
                        Driver.EndSend(writer);
                    }
                    else if (cmd == NetworkEvent.Type.Disconnect)
                    {
                        // 연결 해제 처리
                        Debug.Log("클라이언트 연결 해제됨.");
                        Connections[i] = default;
                    }
                }
            }
        }
    }
}

3⃣ 암호화된 통신 Encrypted communications

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/client-server-secure.html

Unity Transport 패키지는 서버/클라이언트의 신뢰성을 보장하는 동시에 서버와 클라이언트 간의 연결을 암호화하도록 구성할 수 있습니다.

4⃣ Unity.Logging와 통합

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/logging.html

Unity Transport는 Unity Logging 패키지( )와의 선택적 통합을 제공합니다.

com.unity.logging package. 이 패키지는 기존 Unity 로깅 메커니즘에 대한 유연한 대안으로, 특히 프로덕션 서버에 유용합니다.

일반적으로 로그 메시지는 모두 를 거쳐 전송되지만 UnityEngine.Debug.Log, 로깅 패키지가 프로젝트에 포함되면 Unity Transport는 자동으로 Unity.Logging기본 로거 설정을 사용합니다.

특정 로그 설정을 조정하는 방법에 대한 자세한 내용은 로깅 패키지 설명서 사이트를 확인하세요.

Cross-play support

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/cross-play.html

WebGL support

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/websockets.html

FAQ

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/faq.html

Cross-play support

https://docs.unity3d.com/Packages/com.unity.transport@2.5/manual/migration.html

The post Unity Transport 2.5.1 Docs appeared first on 어제와 내일의 나 그 사이의 이야기.

IInputComponentData [Netcode for Entities]

lycos7560 — Sun, 27 Apr 2025 06:33:37 +0000

IInputComponentData

`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⃣ 작동 원리

원본 값	양자화 계수	송신 값	복원 값	오차
0.73f	100	73	0.73f	0%
1.28f	100	128	1.28f	0%
0.123f	100	12	0.12f	2.4%

적정 범위: -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⃣ 최적화 가이드

값 범위	권장 양자화 계수	비트 사용량
-1.0 ~ 1.0	100	8비트
-10.0 ~ 10.0	10	8비트
0 ~ 360 (각도)	32767	16비트
고정밀 물리 파라미터	10000+	16~32비트

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

Unity Serialization (직렬화)

lycos7560 — Tue, 25 Feb 2025 09:24:30 +0000

Serialization (직렬화) 개요
JSON, XML, YAML
Unity에서의 스크립트 직렬화 (Serialization in Unity)

Serialization (직렬화) 개요

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

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

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

https://learn.microsoft.com/ko-kr/dotnet/visual-basic/programming-guide/concepts/serialization/

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보다 길이가 김
다양한 도메인에서 사용 (문서 저장, 설정 파일, 웹 서비스 등)
<태그>를 이용한 구조화된 데이터 표현

예제


    John
    30
    
        C#
        Unity
        Python
    
    true

장점

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

단점

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의 YAML
https://unity.com/kr/blog/engine-platform/understanding-unitys-serialization-language-yaml

비교 정리

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

형식	문법	가독성	속도	사용 사례
JSON	`{ "key": "value" }`	좋음	빠름	API, 데이터 저장
XML	`value`	중간	느림	문서 저장, 설정 파일
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 등 (단, 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(json);
        Debug.Log(loadedPlayer.name);  // John
    }
}

빠름 & Unity 기본 지원
Dictionary, List 같은 복잡한 자료형 지원 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 inventory = new Dictionary();
}

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(json);
        Debug.Log(loadedPlayer.inventory["Sword"]);  // 1
    }
}

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

공부 참고 영상

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

URP VFX Learning Templates (2)

lycos7560 — Sun, 23 Feb 2025 00:40:02 +0000

URP VFX Learning Templates (1)

URP_VFX_Learning_Templates (2)

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

TexIndex Attribute Video (1)

TexIndex Attribute Graph Entire

Sprite Debug Graph

Leaf Fliebook Graph

SpriteSheet Debug (1)

SpriteSheet Debug (2)

SpriteSheet Debug (3)

Leaf Flipbook (1)

Leaf Flipbook (2)

TexIndex Attribute Video (2)

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

Flipbook Mode Video

CandleMesh Entire

CandleMesh Graph

CandleMesh (1)

CandleMesh (2)

SG Candle Shader Graph

SG_Candle 다운로드

Flipbook Flame Graph

Flipbook Flame (1)

Flipbook Flame (2)

Flipbook Flame Video

TX_Flipbook_CandleFlame 다운로드

FlipBook Mode Debug Graph

FlipBook Mode Debug

TX_Flipbook_example 다운로드

13. Flipbook Blending

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

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

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

Covered Aspects:

Flipbook Player
UVs Mode
TexIndex Attribute

Flipbook Blending Video

Flipbook Blending Graph Entire

Flipbook Blending (1)

Flipbook Blending (2)

TX_Flipbook_Smoke 다운로드

일반적인 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

TexIndex Advanced Graph Entire

TexIndex Advanced Video

Brush Strokes Graph

Brush Strokes (1)

Brush Strokes (2)

Brush Strokes (3)

Brush Strokes (4)

TX_Brush 다운로드

Brush Strokes Video

Background Pattern Graph

Background Pattern (1)

Background Pattern (2)

Background Pattern (3)

TX_Flipbook_Cross / TX_UnityLogo_Pack

TX_Flipbook_Cross&TX_UnityLogo_Pack 다운로드

Background Pattern Video

Unity Font Graph

Unity Font (1)

Unity Font (2)

Unity Font (3)

TX_Flipbook_Unity

TX_Flipbook_Unity_Text 다운로드

Unity Font Viedo

Cubes Graph

Cubes (1)

Cubes (2)

Cubes (3)

ST_Unity_Cube

ST_Unity_Cube 다운로드

SG_Unity_Sketch

SG_Unity_Sketch 다운로드

Cubes Video

Lightning Graph

Lightning (1)

Lightning (2)

TX_Lighting 다운로드

Lightning Video

I Dot Graph

I Dot (1)

I Dot (2)

I Dot Video

Floating Shapes Graph

Floating Shapes (1)

Floating Shapes (2)

Floating Shapes (3)

15. Pivot Attribute

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

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

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

Covered Aspects:

Pivot Attribute
Angle Attribute

Pivot Attribute Graph Entire

Pivot Attribute (1)

Pivot Attribute (2)

Pivot Leaf 다운로드

16. Pivot Advanced

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

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

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

Covered Aspects:

Pivot Attribute
Shader Graph integration
Activation Port

Pivot Advanced Graph Entire

Flower Blossom Graph

Flower Blossom (1)

Flower Blossom (2)

Flower Blossom (3)

Flower Blossom (4)

SG_PetalBend

SG_PetalBend 다운로드

Green Leaf Graph

Green Leaf (1)

Green Leaf (2)

Spines Graph

Spines (1)

Spines (2)

17. Sample Mesh

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

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

Covered Aspects:

Mesh Sampling
Sample Mesh Operator

Sample Mesh Video

Sample Mesh Graph Entire

Sample Mesh (1)

Sample Mesh Plane

Sample Mesh (2)

Lion Mesh

Lion 다운로드

Sample Mesh (3)

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

ECS의 World와 SubScene의 관계

lycos7560 — Wed, 19 Feb 2025 04:52:42 +0000

ECS의 World와 SubScene의 관계

개념 정리

개념 정리

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의 로드 과정

SubScene 로드 → SceneSystem이 SubScene을 World에 추가
GameObject → Entity 변환
EntityManager가 모든 Entity 관리
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());

// 대상 World로 Entity 복사
EntityManager destinationManager = targetWorld.EntityManager;
NativeArray 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 어제와 내일의 나 그 사이의 이야기.