개념 정리

World

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

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

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

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

SubScene

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

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

SubScene의 로드 과정

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

World와 SubScene의 관계

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

일반적인 SubScene의 World 포함 방식

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

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

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

SceneSystem.LoadSceneAsync(world, subSceneEntity, loadParameters);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

EntityQuery 정리

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

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

1. EntityQuery의 기본 개념

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

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

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

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

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

2. EntityQuery의 주요 조건

– 특정 조건의 엔티티 찾기

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

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

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

(1) SystemAPI.Query() 사용

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

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

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

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

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

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

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

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

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

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

4. IJobChunk과 함께 사용하기

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

(3) ComponentTypeHandle<T> 방식

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

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

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

2> MoveJob.Schedule() 실행

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

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

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

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

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

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

(4) NativeArray Job 방식

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

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

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

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

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

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

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

5. EntityQuery의 추가 기능

(1) CalculateEntityCount()로 개수 확인

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

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

query.SetChangedVersionFilter<PositionComponent>();

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

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

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

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

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

using System;
using Unity.Burst;
using Unity.Collections;
using Unity.Entities;
using Unity.Jobs;
using Unity.Mathematics;
using Unity.Physics.GraphicsIntegration;
using Unity.Rendering;
using Unity.Transforms;
using UnityEngine;
using static Unity.Physics.Extensions.PhysicsSamplesExtensions;

namespace Unity.Physics.Extensions
{
    public class MouseHover : IComponentData
    {
        public bool IgnoreTriggers;
        public bool IgnoreStatic;
        public Entity PreviousEntity;
        public Entity CurrentEntity;
        public Entity HoverEntity;
        public MaterialMeshInfo OriginalMeshInfo;
        public RenderMeshArray OriginalRenderMeshes;
    }

    [DisallowMultipleComponent]
    public class MouseHoverAuthoring : MonoBehaviour
    {
        public GameObject HoverPrefab;
        public bool IgnoreTriggers = true;
        public bool IgnoreStatic = true;

        // Note: override OnEnable to be able to disable the component in the editor
        protected void OnEnable() {}
    }

    class MouseHoverBaker : Baker<MouseHoverAuthoring>
    {
        public override void Bake(MouseHoverAuthoring authoring)
        {
            var entity = GetEntity(TransformUsageFlags.None);
            AddComponentObject(entity, new MouseHover()
            {
                PreviousEntity = Entity.Null,
                CurrentEntity = Entity.Null,
                IgnoreTriggers = authoring.IgnoreTriggers,
                IgnoreStatic = authoring.IgnoreStatic,
                HoverEntity = GetEntity(authoring.HoverPrefab, TransformUsageFlags.Dynamic),
            });
        }
    }

    // Applies any mouse spring as a change in velocity on the entity's motion component
    // Limitations: works only if the physics objects in the scene come from the same subscene as MouseHoverAuthoring
    // Will be fixable if there is a Unity.Rendering API that lets you get the UnityEngine.Mesh that an entity is using for renderin.

    [UpdateInGroup(typeof(InitializationSystemGroup))]
    public partial class MouseHoverSystem : SystemBase
    {
        [BurstCompile]
        public struct WorldRaycastJob : IJob
        {
            public RaycastInput RayInput;
            [ReadOnly] public CollisionWorld CollisionWorld;
            [ReadOnly] public bool IgnoreTriggers;
            [ReadOnly] public bool IgnoreStatic;

            public NativeReference<RaycastHit> RaycastHitRef;

            public void Execute()
            {
                var mousePickCollector = new MousePickCollector(CollisionWorld.NumDynamicBodies)
                {
                    IgnoreTriggers = IgnoreTriggers,
                    IgnoreStatic = IgnoreStatic
                };

                if (CollisionWorld.CastRay(RayInput, ref mousePickCollector))
                {
                    RaycastHitRef.Value = mousePickCollector.Hit;
                }
            }
        }

        protected override void OnCreate()
        {
            base.OnCreate();
            RequireForUpdate<MouseHover>();
        }

        // Find the Entity holding the Graphical representation of a Physics Shape.
        // It may be that the Physics and Graphics representation are on the same Entity.
        public Entity FindGraphicsEntityFromPhysics(Entity bodyEntity) => FindGraphicsEntityFromPhysics(bodyEntity, ColliderKey.Empty);
        public Entity FindGraphicsEntityFromPhysics(Entity bodyEntity, ColliderKey leafColliderKey)
        {
            if (bodyEntity.Equals(Entity.Null))
            {
                // No Physics so no Graphics
                return Entity.Null;
            }

            // Set the Graphics Entity to the supplied Physics Entity
            var renderEntity = bodyEntity;

            // Check if we have hit a leaf node
            if (!leafColliderKey.Equals(ColliderKey.Empty))
            {
                // Get the Physics Collider
                var rootCollider = EntityManager.GetComponentData<PhysicsCollider>(bodyEntity).Value;

                // If we hit a CompoundCollider we need to find the original Entity associated
                // the actual leaf Collider that was hit.
                if (rootCollider.Value.Type == ColliderType.Compound)
                {
                    #region Find a Leaf Entity and ColliderKey
                    var leafEntity = Entity.Null;
                    unsafe
                    {
                        var rootColliderPtr = rootCollider.AsPtr();

                        // Get the leaf Collider and check if we hit was a PolygonCollider (i.e. a Triangle or a Quad)
                        rootColliderPtr->GetLeaf(leafColliderKey, out var childCollider);
                        leafEntity = childCollider.Entity;

                        // PolygonColliders are likely to not have an original Entity associated with them
                        // So if we have a Polygon and it has no Entity then we really need to check for
                        // the higher level Mesh or Terrain Collider instead.
                        var childColliderType = childCollider.Collider->Type;
                        var childColliderIsPolygon = childColliderType == ColliderType.Triangle || childColliderType == ColliderType.Quad;
                        if (childColliderIsPolygon && childCollider.Entity.Equals(Entity.Null))
                        {
                            // Get the ColliderKey of the Polygon's parent
                            if (TryGetParentColliderKey(rootColliderPtr, leafColliderKey, out leafColliderKey))
                            {
                                // Get the Mesh or Terrain Collider of the Polygon
                                TryGetChildInHierarchy(rootColliderPtr, leafColliderKey, out childCollider);
                                leafEntity = childCollider.Entity;
                            }
                        }
                    }
                    #endregion

                    // The Entities recorded in the leaves of a CompoundCollider may have been correct
                    // at the time of conversion. However, if the Collider blob is shared, or came up
                    // through a sub scene, we cannot assume that the baked Entities in the
                    // CompoundCollider are still valid.

                    // On conversion Entities using a CompoundCollider have an extra dynamic buffer added
                    // which holds a list of Entity/ColliderKey pairs. This buffer should be patched up
                    // automatically and be valid with each instance, at least until you start messing
                    // with the Entity hierarchy yourself e.g. by deleting Entities.

                    #region Check the Leaf Entity is valid
                    // If the leafEntity was never assigned in the first place
                    // there is no point in looking up any Buffers.
                    if (!leafEntity.Equals(Entity.Null))
                    {
                        // Check for an Key/Entity pair buffer first.
                        // This should exist if the Physics conversion pipeline was invoked.
                        var colliderKeyEntityPairBuffers = GetBufferLookup<PhysicsColliderKeyEntityPair>(true);
                        if (colliderKeyEntityPairBuffers.HasBuffer(bodyEntity))
                        {
                            var colliderKeyEntityBuffer = colliderKeyEntityPairBuffers[bodyEntity];
                            for (int i = 0; i < colliderKeyEntityBuffer.Length; i++)
                            {
                                var bufferColliderKey = colliderKeyEntityBuffer[i].Key;
                                if (leafColliderKey.Equals(bufferColliderKey))
                                {
                                    renderEntity = colliderKeyEntityBuffer[i].Entity;
                                    break;
                                }
                            }
                        }
                        else
                        {
                            // We haven't found a Key/Entity pair buffer so the compound collider
                            // may have been created in code.

                            // We'll assume the Entity in the CompoundCollider is valid
                            renderEntity = leafEntity;

                            // If this CompoundCollider was instanced from a prefab then the entities
                            // in the compound children would actually reference the original prefab hierarchy.
                            var rootEntityFromLeaf = leafEntity;
                            while (SystemAPI.HasComponent<Parent>(rootEntityFromLeaf))
                            {
                                rootEntityFromLeaf = SystemAPI.GetComponent<Parent>(rootEntityFromLeaf).Value;
                            }

                            // If the root Entity found from the leaf does not match the body Entity
                            // then we have hit an instance using the same CompoundCollider.
                            // This means we can try and remap the leaf Entity to the new hierarchy.
                            if (!rootEntityFromLeaf.Equals(bodyEntity))
                            {
                                // This assumes there is a LinkedEntityGroup Buffer on original and instance Entity.
                                // No doubt there is a more optimal way of doing this remap with more specific
                                // knowledge of the final application.
                                var linkedEntityGroupBuffers = GetBufferLookup<LinkedEntityGroup>(true);

                                // Only remap if the buffers exist, have been created and are of equal length.
                                bool hasBufferRootEntity = linkedEntityGroupBuffers.HasBuffer(rootEntityFromLeaf);
                                bool hasBufferBodyEntity = linkedEntityGroupBuffers.HasBuffer(bodyEntity);
                                if (hasBufferRootEntity && hasBufferBodyEntity)
                                {
                                    var prefabEntityGroupBuffer = linkedEntityGroupBuffers[rootEntityFromLeaf];
                                    var instanceEntityGroupBuffer = linkedEntityGroupBuffers[bodyEntity];

                                    if (prefabEntityGroupBuffer.IsCreated && instanceEntityGroupBuffer.IsCreated
                                        && (prefabEntityGroupBuffer.Length == instanceEntityGroupBuffer.Length))
                                    {
                                        var prefabEntityGroup = prefabEntityGroupBuffer.AsNativeArray();
                                        var instanceEntityGroup = instanceEntityGroupBuffer.AsNativeArray();

                                        for (int i = 0; i < prefabEntityGroup.Length; i++)
                                        {
                                            // If we've found the renderEntity index in the prefab hierarchy,
                                            // set the renderEntity to the equivalent Entity in the instance
                                            if (prefabEntityGroup[i].Value.Equals(renderEntity))
                                            {
                                                renderEntity = instanceEntityGroup[i].Value;
                                                break;
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                    #endregion
                }
            }

            // Finally check to see if we have a graphics redirection on the shape Entity.
            if (SystemAPI.HasComponent<PhysicsRenderEntity>(renderEntity))
            {
                renderEntity = SystemAPI.GetComponent<PhysicsRenderEntity>(renderEntity).Entity;
            }

            // If no render info is found on the located render entity, we try to find any child which has render info
            if (renderEntity != Entity.Null && !EntityManager.HasComponent<MaterialMeshInfo>(renderEntity))
            {
                // No render information on this entity. Try to find the actual render entity in the hierarchy.
                if (EntityManager.HasBuffer<Child>(renderEntity))
                {
                    var children = EntityManager.GetBuffer<Child>(renderEntity);
                    foreach (var childElement in children)
                    {
                        // find the first child with render info
                        if (EntityManager.HasComponent<MaterialMeshInfo>(childElement.Value))
                        {
                            renderEntity = childElement.Value;
                        }
                    }
                }
            }

            return renderEntity;
        }

        protected override void OnUpdate()
        {
            var collisionWorld = SystemAPI.GetSingleton<PhysicsWorldSingleton>().CollisionWorld;
            Vector2 mousePosition = Input.mousePosition;
            UnityEngine.Ray unityRay = Camera.main.ScreenPointToRay(mousePosition);
            var rayInput = new RaycastInput
            {
                Start = unityRay.origin,
                End = unityRay.origin + unityRay.direction * MousePickSystem.k_MaxDistance,
                Filter = CollisionFilter.Default,
            };

            var mouseHover = SystemAPI.ManagedAPI.GetSingleton<MouseHover>();

            RaycastHit hit;
            using (var raycastHitRef = new NativeReference<RaycastHit>(Allocator.TempJob))
            {
                var rcj = new WorldRaycastJob()
                {
                    CollisionWorld = collisionWorld,
                    RayInput = rayInput,
                    IgnoreTriggers = mouseHover.IgnoreTriggers,
                    IgnoreStatic = mouseHover.IgnoreStatic,
                    RaycastHitRef = raycastHitRef
                };
                rcj.Run();
                hit = raycastHitRef.Value;
            }

            var graphicsEntity = FindGraphicsEntityFromPhysics(hit.Entity, hit.ColliderKey);

            // If still hovering over the same entity then do nothing.
            if (mouseHover.CurrentEntity.Equals(graphicsEntity)) return;

            mouseHover.PreviousEntity = mouseHover.CurrentEntity;
            mouseHover.CurrentEntity = graphicsEntity;

            bool hasPreviousEntity = !mouseHover.PreviousEntity.Equals(Entity.Null);
            bool hasCurrentEntity = !mouseHover.CurrentEntity.Equals(Entity.Null);

            if (hasPreviousEntity && EntityManager.HasComponent<MaterialMeshInfo>(mouseHover.PreviousEntity))
            {
                // restore render info to original in the last entity we were hovering over
                EntityManager.SetComponentData(mouseHover.PreviousEntity, mouseHover.OriginalMeshInfo);
                EntityManager.SetSharedComponentManaged(mouseHover.PreviousEntity, mouseHover.OriginalRenderMeshes);
            }

            if (hasCurrentEntity && EntityManager.HasComponent<MaterialMeshInfo>(mouseHover.CurrentEntity) && EntityManager.HasComponent<RenderMeshArray>(mouseHover.CurrentEntity))
            {
                mouseHover.PreviousEntity = mouseHover.CurrentEntity;
                mouseHover.CurrentEntity = graphicsEntity;
                mouseHover.OriginalMeshInfo = EntityManager.GetComponentData<MaterialMeshInfo>(mouseHover.CurrentEntity);
                mouseHover.OriginalRenderMeshes = EntityManager.GetSharedComponentManaged<RenderMeshArray>(mouseHover.CurrentEntity);

                // get render info from the hover entity
                var hoverMeshInfo = EntityManager.GetComponentData<MaterialMeshInfo>(mouseHover.HoverEntity);
                var hoverRenderMeshes = EntityManager.GetSharedComponentManaged<RenderMeshArray>(mouseHover.HoverEntity);

                // create new render info for the current entity that we hover over:

                // use the materials from the hover entity, but the meshes from the current entity
                var newRenderMeshes = new RenderMeshArray(hoverRenderMeshes.MaterialReferences, mouseHover.OriginalRenderMeshes.MeshReferences);

                // use the material id from the hover entity, but the mesh id from the current entity
                var newMeshInfo = MaterialMeshInfo.FromRenderMeshArrayIndices(hoverMeshInfo.Material, mouseHover.OriginalMeshInfo.Mesh);

                // apply the new render info to the current entity
                EntityManager.SetComponentData(mouseHover.CurrentEntity, newMeshInfo);
                EntityManager.SetSharedComponentManaged(mouseHover.CurrentEntity, newRenderMeshes);
            }
        }
    }
}

1. MouseHover (IComponentData)

// 관리되는 객체이므로 Class를 사용 
public class MouseHover : IComponentData
{
    public bool IgnoreTriggers;
    public bool IgnoreStatic;
    public Entity PreviousEntity; // 이전 프레임에서 Hover 상태의 Entity
    public Entity CurrentEntity; // 현재 프레임에서 Hover 상태의 Entity
    public Entity HoverEntity; // Hover 상태일 때 적용할 메쉬/머터리얼이 있는 Entity
    public MaterialMeshInfo OriginalMeshInfo; // 원래의 렌더링 정보를 저장
    public RenderMeshArray OriginalRenderMeshes; //   "
}

2. MouseHoverBaker (Baker)

[DisallowMultipleComponent]
public class MouseHoverAuthoring : MonoBehaviour
{
    public GameObject HoverPrefab;
    public bool IgnoreTriggers = true;
    public bool IgnoreStatic = true;

    // 참고: 편집기에서 구성 요소를 비활성화하려면 OnEnable을 재정의합니다
    protected void OnEnable() { }
}

// MouseHover 컴포넌트를 Entity에 추가
class MouseHoverBaker : Baker<MouseHoverAuthoring>
{
    public override void Bake(MouseHoverAuthoring authoring)
    {
        var entity = GetEntity(TransformUsageFlags.None);

        AddComponentObject(entity, new MouseHover()
        {
            PreviousEntity = Entity.Null,
            CurrentEntity = Entity.Null,
            IgnoreTriggers = authoring.IgnoreTriggers,
            IgnoreStatic = authoring.IgnoreStatic,
            HoverEntity = GetEntity(authoring.HoverPrefab, TransformUsageFlags.Dynamic), // HoverPrefab을 HoverEntity로 변환하여 저장
        });
    }
}

3. MouseHoverSystem (SystemBase)

    // Applies any mouse spring as a change in velocity on the entity's motion component
    // Limitations: works only if the physics objects in the scene come from the same subscene as MouseHoverAuthoring
    // Will be fixable if there is a Unity.Rendering API that lets you get the UnityEngine.Mesh that an entity is using for renderin.
    
    [UpdateInGroup(typeof(InitializationSystemGroup))]
    public partial class MouseHoverSystem : SystemBase
    {
        [BurstCompile]
        public struct WorldRaycastJob : IJob
        {
            public RaycastInput RayInput;
            [ReadOnly] public CollisionWorld CollisionWorld;
            [ReadOnly] public bool IgnoreTriggers;
            [ReadOnly] public bool IgnoreStatic;

            public NativeReference<RaycastHit> RaycastHitRef;

            public void Execute()
            {
                var mousePickCollector = new MousePickCollector(CollisionWorld.NumDynamicBodies)
                {
                    IgnoreTriggers = IgnoreTriggers,
                    IgnoreStatic = IgnoreStatic
                };

                if (CollisionWorld.CastRay(RayInput, ref mousePickCollector))
                {
                    RaycastHitRef.Value = mousePickCollector.Hit;
                }
            }
        }

        protected override void OnCreate()
        {
            base.OnCreate();
            RequireForUpdate<MouseHover>();
        }

        // Find the Entity holding the Graphical representation of a Physics Shape.
        // It may be that the Physics and Graphics representation are on the same Entity.
        public Entity FindGraphicsEntityFromPhysics(Entity bodyEntity) => FindGraphicsEntityFromPhysics(bodyEntity, ColliderKey.Empty);
        public Entity FindGraphicsEntityFromPhysics(Entity bodyEntity, ColliderKey leafColliderKey)
        {
            if (bodyEntity.Equals(Entity.Null))
            {
                // No Physics so no Graphics
                return Entity.Null;
            }

            // Set the Graphics Entity to the supplied Physics Entity
            var renderEntity = bodyEntity;

            // Check if we have hit a leaf node
            if (!leafColliderKey.Equals(ColliderKey.Empty))
            {
                // Get the Physics Collider
                var rootCollider = EntityManager.GetComponentData<PhysicsCollider>(bodyEntity).Value;

                // If we hit a CompoundCollider we need to find the original Entity associated
                // the actual leaf Collider that was hit.
                if (rootCollider.Value.Type == ColliderType.Compound)
                {
                    #region Find a Leaf Entity and ColliderKey
                    var leafEntity = Entity.Null;
                    unsafe
                    {
                        var rootColliderPtr = rootCollider.AsPtr();

                        // Get the leaf Collider and check if we hit was a PolygonCollider (i.e. a Triangle or a Quad)
                        rootColliderPtr->GetLeaf(leafColliderKey, out var childCollider);
                        leafEntity = childCollider.Entity;

                        // PolygonColliders are likely to not have an original Entity associated with them
                        // So if we have a Polygon and it has no Entity then we really need to check for
                        // the higher level Mesh or Terrain Collider instead.
                        var childColliderType = childCollider.Collider->Type;
                        var childColliderIsPolygon = childColliderType == ColliderType.Triangle || childColliderType == ColliderType.Quad;
                        if (childColliderIsPolygon && childCollider.Entity.Equals(Entity.Null))
                        {
                            // Get the ColliderKey of the Polygon's parent
                            if (TryGetParentColliderKey(rootColliderPtr, leafColliderKey, out leafColliderKey))
                            {
                                // Get the Mesh or Terrain Collider of the Polygon
                                TryGetChildInHierarchy(rootColliderPtr, leafColliderKey, out childCollider);
                                leafEntity = childCollider.Entity;
                            }
                        }
                    }
                    #endregion

                    // The Entities recorded in the leaves of a CompoundCollider may have been correct
                    // at the time of conversion. However, if the Collider blob is shared, or came up
                    // through a sub scene, we cannot assume that the baked Entities in the
                    // CompoundCollider are still valid.

                    // On conversion Entities using a CompoundCollider have an extra dynamic buffer added
                    // which holds a list of Entity/ColliderKey pairs. This buffer should be patched up
                    // automatically and be valid with each instance, at least until you start messing
                    // with the Entity hierarchy yourself e.g. by deleting Entities.

                    #region Check the Leaf Entity is valid
                    // If the leafEntity was never assigned in the first place
                    // there is no point in looking up any Buffers.
                    if (!leafEntity.Equals(Entity.Null))
                    {
                        // Check for an Key/Entity pair buffer first.
                        // This should exist if the Physics conversion pipeline was invoked.
                        var colliderKeyEntityPairBuffers = GetBufferLookup<PhysicsColliderKeyEntityPair>(true);
                        if (colliderKeyEntityPairBuffers.HasBuffer(bodyEntity))
                        {
                            var colliderKeyEntityBuffer = colliderKeyEntityPairBuffers[bodyEntity];
                            for (int i = 0; i < colliderKeyEntityBuffer.Length; i++)
                            {
                                var bufferColliderKey = colliderKeyEntityBuffer[i].Key;
                                if (leafColliderKey.Equals(bufferColliderKey))
                                {
                                    renderEntity = colliderKeyEntityBuffer[i].Entity;
                                    break;
                                }
                            }
                        }
                        else
                        {
                            // We haven't found a Key/Entity pair buffer so the compound collider
                            // may have been created in code.

                            // We'll assume the Entity in the CompoundCollider is valid
                            renderEntity = leafEntity;

                            // If this CompoundCollider was instanced from a prefab then the entities
                            // in the compound children would actually reference the original prefab hierarchy.
                            var rootEntityFromLeaf = leafEntity;
                            while (SystemAPI.HasComponent<Parent>(rootEntityFromLeaf))
                            {
                                rootEntityFromLeaf = SystemAPI.GetComponent<Parent>(rootEntityFromLeaf).Value;
                            }

                            // If the root Entity found from the leaf does not match the body Entity
                            // then we have hit an instance using the same CompoundCollider.
                            // This means we can try and remap the leaf Entity to the new hierarchy.
                            if (!rootEntityFromLeaf.Equals(bodyEntity))
                            {
                                // This assumes there is a LinkedEntityGroup Buffer on original and instance Entity.
                                // No doubt there is a more optimal way of doing this remap with more specific
                                // knowledge of the final application.
                                var linkedEntityGroupBuffers = GetBufferLookup<LinkedEntityGroup>(true);

                                // Only remap if the buffers exist, have been created and are of equal length.
                                bool hasBufferRootEntity = linkedEntityGroupBuffers.HasBuffer(rootEntityFromLeaf);
                                bool hasBufferBodyEntity = linkedEntityGroupBuffers.HasBuffer(bodyEntity);
                                if (hasBufferRootEntity && hasBufferBodyEntity)
                                {
                                    var prefabEntityGroupBuffer = linkedEntityGroupBuffers[rootEntityFromLeaf];
                                    var instanceEntityGroupBuffer = linkedEntityGroupBuffers[bodyEntity];

                                    if (prefabEntityGroupBuffer.IsCreated && instanceEntityGroupBuffer.IsCreated
                                        && (prefabEntityGroupBuffer.Length == instanceEntityGroupBuffer.Length))
                                    {
                                        var prefabEntityGroup = prefabEntityGroupBuffer.AsNativeArray();
                                        var instanceEntityGroup = instanceEntityGroupBuffer.AsNativeArray();

                                        for (int i = 0; i < prefabEntityGroup.Length; i++)
                                        {
                                            // If we've found the renderEntity index in the prefab hierarchy,
                                            // set the renderEntity to the equivalent Entity in the instance
                                            if (prefabEntityGroup[i].Value.Equals(renderEntity))
                                            {
                                                renderEntity = instanceEntityGroup[i].Value;
                                                break;
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                    #endregion
                }
            }

            // Finally check to see if we have a graphics redirection on the shape Entity.
            if (SystemAPI.HasComponent<PhysicsRenderEntity>(renderEntity))
            {
                renderEntity = SystemAPI.GetComponent<PhysicsRenderEntity>(renderEntity).Entity;
            }

            // If no render info is found on the located render entity, we try to find any child which has render info
            if (renderEntity != Entity.Null && !EntityManager.HasComponent<MaterialMeshInfo>(renderEntity))
            {
                // No render information on this entity. Try to find the actual render entity in the hierarchy.
                if (EntityManager.HasBuffer<Child>(renderEntity))
                {
                    var children = EntityManager.GetBuffer<Child>(renderEntity);
                    foreach (var childElement in children)
                    {
                        // find the first child with render info
                        if (EntityManager.HasComponent<MaterialMeshInfo>(childElement.Value))
                        {
                            renderEntity = childElement.Value;
                        }
                    }
                }
            }

            return renderEntity;
        }

        protected override void OnUpdate()
        {
            var collisionWorld = SystemAPI.GetSingleton<PhysicsWorldSingleton>().CollisionWorld;
            Vector2 mousePosition = Input.mousePosition;
            UnityEngine.Ray unityRay = Camera.main.ScreenPointToRay(mousePosition);
            var rayInput = new RaycastInput
            {
                Start = unityRay.origin,
                End = unityRay.origin + unityRay.direction * MousePickSystem.k_MaxDistance,
                Filter = CollisionFilter.Default,
            };

            var mouseHover = SystemAPI.ManagedAPI.GetSingleton<MouseHover>();

            RaycastHit hit;
            using (var raycastHitRef = new NativeReference<RaycastHit>(Allocator.TempJob))
            {
                var rcj = new WorldRaycastJob()
                {
                    CollisionWorld = collisionWorld,
                    RayInput = rayInput,
                    IgnoreTriggers = mouseHover.IgnoreTriggers,
                    IgnoreStatic = mouseHover.IgnoreStatic,
                    RaycastHitRef = raycastHitRef
                };
                rcj.Run();
                hit = raycastHitRef.Value;
            }

            var graphicsEntity = FindGraphicsEntityFromPhysics(hit.Entity, hit.ColliderKey);

            // If still hovering over the same entity then do nothing.
            if (mouseHover.CurrentEntity.Equals(graphicsEntity)) return;

            mouseHover.PreviousEntity = mouseHover.CurrentEntity;
            mouseHover.CurrentEntity = graphicsEntity;

            bool hasPreviousEntity = !mouseHover.PreviousEntity.Equals(Entity.Null);
            bool hasCurrentEntity = !mouseHover.CurrentEntity.Equals(Entity.Null);

            if (hasPreviousEntity && EntityManager.HasComponent<MaterialMeshInfo>(mouseHover.PreviousEntity))
            {
                // restore render info to original in the last entity we were hovering over
                EntityManager.SetComponentData(mouseHover.PreviousEntity, mouseHover.OriginalMeshInfo);
                EntityManager.SetSharedComponentManaged(mouseHover.PreviousEntity, mouseHover.OriginalRenderMeshes);
            }

            if (hasCurrentEntity && EntityManager.HasComponent<MaterialMeshInfo>(mouseHover.CurrentEntity) && EntityManager.HasComponent<RenderMeshArray>(mouseHover.CurrentEntity))
            {
                mouseHover.PreviousEntity = mouseHover.CurrentEntity;
                mouseHover.CurrentEntity = graphicsEntity;
                mouseHover.OriginalMeshInfo = EntityManager.GetComponentData<MaterialMeshInfo>(mouseHover.CurrentEntity);
                mouseHover.OriginalRenderMeshes = EntityManager.GetSharedComponentManaged<RenderMeshArray>(mouseHover.CurrentEntity);

                // get render info from the hover entity
                var hoverMeshInfo = EntityManager.GetComponentData<MaterialMeshInfo>(mouseHover.HoverEntity);
                var hoverRenderMeshes = EntityManager.GetSharedComponentManaged<RenderMeshArray>(mouseHover.HoverEntity);

                // create new render info for the current entity that we hover over:

                // use the materials from the hover entity, but the meshes from the current entity
                var newRenderMeshes = new RenderMeshArray(hoverRenderMeshes.MaterialReferences, mouseHover.OriginalRenderMeshes.MeshReferences);

                // use the material id from the hover entity, but the mesh id from the current entity
                var newMeshInfo = MaterialMeshInfo.FromRenderMeshArrayIndices(hoverMeshInfo.Material, mouseHover.OriginalMeshInfo.Mesh);

                // apply the new render info to the current entity
                EntityManager.SetComponentData(mouseHover.CurrentEntity, newMeshInfo);
                EntityManager.SetSharedComponentManaged(mouseHover.CurrentEntity, newRenderMeshes);
            }
        }
    }

1) InitializationSystemGroup

초기화 단계에서 실행됨

2) WorldRaycastJob (IJob)

마우스 위치에서 Raycast를 실행하는 IJob

• CollisionWorld.CastRay()를 사용하여 마우스가 클릭한 지점의 물리 객체를 찾음
• mousePickCollector를 사용하여 필터링 (IgnoreTriggers, IgnoreStatic)

3) OnUpdate()

1> CollisionWorld 가져오기

• PhysicsWorldSingleton은 Unity Physics 시스템에서 현재의 물리 월드(CollisionWorld)를 관리하는 싱글톤
• CollisionWorld는 물리적인 충돌을 검사하는 데 사용

2> 마우스 위치에서 레이(Ray) 생성

• Input.mousePosition을 사용하여 현재 마우스 커서의 화면 좌표를 가져오기
• Camera.main.ScreenPointToRay(mousePosition)을 통해 이 화면 좌표를 기준으로 3D 월드에서의 Ray를 생성

3> RaycastInput 설정

RaycastInput은 Unity Physics에서 사용되는 구조체로, 물리 엔진이 사용할 레이캐스트 정보를 포함

• Start: 레이의 시작점 (unityRay.origin)
• End: 레이의 끝점 (unityRay.origin + unityRay.direction * MousePickSystem.k_MaxDistance)
  • MousePickSystem.k_MaxDistance는 레이의 최대 탐색 거리로, 너무 멀리까지 체크하지 않도록 제한
• Filter: CollisionFilter.Default는 기본적인 충돌 필터로, 충돌 검사를 수행할 물리 레이어를 정의

4> MouseHover 컴포넌트 가져오기

• MouseHover는 마우스 오버 이벤트를 관리하는 IComponentData
• SystemAPI.ManagedAPI.GetSingleton<MouseHover>()을 사용하여 현재 씬에 존재하는 MouseHover 컴포넌트를 가져옴

5> 레이캐스트 실행

NativeReference<RaycastHit>을 사용하여 레이캐스트 결과(RaycastHit)를 저장할 공간을 확보

WorldRaycastJob을 생성하여 레이캐스트를 수행

• CollisionWorld을 사용하여 실제 물리 충돌을 검사합니다.
• IgnoreTriggers, IgnoreStatic 값을 기반으로 충돌 조건을 설정합니다.

rcj.Run();을 실행하여 Job을 즉시 수행한 후 결과를 hit에 저장합니다.

5> 물리 Entity에서 그래픽 Entity 찾기

hit.Entity는 RaycastHit 결과에서 얻은 충돌한 물리 Entity

FindGraphicsEntityFromPhysics(hit.Entity, hit.ColliderKey)를 호출하여 실제 렌더링을 담당하는 Entity를 찾습니다.

• 물리 Entity 와 그래픽 Entity 는 다를 수 있기 때문에 이 과정을 거칩니다.

6> 동일한 엔터티를 계속 가리키면 무시

현재 마우스가 가리키는 graphicsEntity가 이전 프레임과 동일하면 추가 작업을 하지 않고 바로 반환합니다.

7> 이전 및 현재 마우스 오버 Entity 업데이트

• PreviousEntity에 이전 프레임에서 마우스가 가리키던 Entity를 저장합니다.
• CurrentEntity에 이번 프레임에서 새롭게 감지된 Entity를 저장합니다.

8> 이전 Entity의 원래 상태 복구

hasPreviousEntity: 이전 프레임에서 마우스가 가리키던 Entity가 존재하는지 확인

EntityManager.HasComponent<MaterialMeshInfo>(mouseHover.PreviousEntity): 이전 Entity가 MaterialMeshInfo 컴포넌트를 가지고 있는지 확인

이전 Entity의 렌더링 데이터를 원래 값으로 복원:

• MaterialMeshInfo: 이전에 저장해 둔 원래의 메쉬 정보를 복원
• RenderMeshArray: 이전에 저장해 둔 원래의 Material 배열을 복원

9> 새로운 Entity의 마우스 Hover 효과 적용

현재 프레임에서 감지된 CurrentEntity가 존재하는지 확인

MaterialMeshInfo 및 RenderMeshArray 컴포넌트가 있는 경우, 원래 상태를 저장:

• OriginalMeshInfo: 원래 MaterialMeshInfo 값을 저장
• OriginalRenderMeshes: 원래 RenderMeshArray 값을 저장

10> 마우스 Hover 머티리얼 적용

mouseHover.HoverEntity는 마우스 Hover 효과를 표시하는 데 사용할 프리팹(Material 정보 포함)

hoverMeshInfo와 hoverRenderMeshes를 가져와서 현재 마우스가 가리키는 Entity에 적용

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

ECS – BufferTypeHandle

ECS에서 DynamicBuffer<T>를 처리하려면 BufferTypeHandle<T>를 사용해야 한다.

즉, “IComponentData가 아닌 버퍼 데이터를 읽고/쓰는 Handle“

1. BufferTypeHandle<T>란?

• ECS에서 DynamicBuffer<T>를 읽고/쓰기 위한 Handle
• IJobChunk 내부에서 사용됨
• GetBufferAccessor(ref BufferTypeHandle<T>)를 이용해 버퍼 데이터 접근
• 쓰기 여부에 따라 읽기 전용(true) / 읽기+쓰기(false) 로 설정 가능

2. 사용 예제

1) OnCreate()에서 초기화

_BufferTypeHandle = state.GetBufferTypeHandle<GridCellBufferComponent>(isReadOnly: false);

• isReadOnly: true → 읽기 전용
• isReadOnly: false → 읽기 & 쓰기 가능

2) OnUpdate()에서 매 프레임 업데이트

_BufferTypeHandle.Update(ref state);

• Update(ref state)를 호출해야 최신 데이터를 가져올 수 있다.

3. BufferTypeHandle 상세 사용법

1) 기본 사용법 (IJobChunk에서 사용)

[BurstCompile]
public struct CountJob : IJobChunk
{
    public BufferTypeHandle<GridCellBufferComponent> BufferTypeHandle;

    public void Execute(in ArchetypeChunk chunk, int chunkIndex, bool useEnabledMask, in v128 chunkEnabledMask)
    {
        var buffers = chunk.GetBufferAccessor(ref BufferTypeHandle);

        for (int i = 0; i < chunk.Count; i++)
        {
            DynamicBuffer<GridCellBufferComponent> buffer = buffers[i];

            for (int j = 0; j < buffer.Length; j++)
            {
                buffer[j] = new GridCellBufferComponent
                {
                    Position = buffer[j].Position,
                    IsOccupied = buffer[j].IsOccupied,
                    Count = buffer[j].Count + 1 // Count 증가
                };
            }
        }
    }
}

• chunk.GetBufferAccessor(ref BufferTypeHandle)을 사용하여 DynamicBuffer에 접근
• 각 chunk에 속한 모든 DynamicBuffer<GridCellBufferComponent>에 대해 반복문 실행

2) OnUpdate()에서 ScheduleParallel 실행

public void OnUpdate(ref SystemState state)
{
    _BufferTypeHandle.Update(ref state);

    var job = new CountJob
    {
        BufferTypeHandle = _BufferTypeHandle
    };

    state.Dependency = job.ScheduleParallel(_GridQuery, state.Dependency);
}

• _BufferTypeHandle.Update(ref state); → 최신 상태 반영
• ScheduleParallel() → 여러 개의 chunk를 병렬 실행

3) IJobParallelFor에서 BufferTypeHandle를 사용할 때

일반적으로 IJobParallelFor에서는 직접 사용할 수 없고, AsNativeArray() 를 사용해야 함.

[BurstCompile]
public struct CountJobParallelFor : IJobParallelFor
{
    public NativeArray<GridCellBufferComponent> BufferNativeArray;

    public void Execute(int index)
    {
        BufferNativeArray[index] = new GridCellBufferComponent
        {
            Position = BufferNativeArray[index].Position,
            IsOccupied = BufferNativeArray[index].IsOccupied,
            Count = BufferNativeArray[index].Count + 1
        };
    }
}

OnUpdate()에서 실행:

public void OnUpdate(ref SystemState state)
{
    _BufferTypeHandle.Update(ref state);
    var chunks = _GridQuery.ToArchetypeChunkArray(Allocator.TempJob);

    for (int i = 0; i < chunks.Length; i++)
    {
        BufferAccessor<GridCellBufferComponent> bufferAccessor = chunks[i].GetBufferAccessor(ref _BufferTypeHandle);
        for (int j = 0; j < bufferAccessor.Length; j++)
        {
            DynamicBuffer<GridCellBufferComponent> buffer = bufferAccessor[j];

            var job = new CountJobParallelFor
            {
                BufferNativeArray = buffer.AsNativeArray()
            };

            job.Schedule(buffer.Length, 1).Complete(); // 즉시 실행
        }
    }
    chunks.Dispose();
}

주의할 점

• DynamicBuffer<T>에서 AsNativeArray() 를 호출하여 IJobParallelFor에서 사용
• .Complete() 없이 state.Dependency = job.Schedule();을 하면 Write Conflict 에러 발생
• buffer.AsNativeArray()는 해당 프레임에서만 유효

4. BufferTypeHandle 요약

BufferTypeHandle<T>는 언제 사용?

• 많은 데이터가 DynamicBuffer에 저장될 때
• ECS에서 IJobChunk 또는 IJobParallelFor을 활용할 때
• 최대 성능을 끌어내기 위해 ScheduleParallel을 사용할 때

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

ECS – System concepts

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/concepts-systems.html

System concepts

System의 역할

• System은 컴포넌트 데이터를 읽고, 수정하여 프레임마다 업데이트하는 역할을 수행
• OnUpdate()가 매 프레임 호출되며, Entity 데이터를 갱신함
• SystemBase(관리형 시스템)와 ISystem(비관리형 시스템) 두 가지 유형이 있음

System의 유형

System 실행 순서 (System Groups)

• ECS는 시스템을 Auto Bootstrap하며, 기본적으로 3가지 그룹으로 실행됨.
  (Auto Bootstrap – 시스템을 자동으로 생성하고 실행하는 과정)

• 특정 그룹에서 실행되도록 하려면 [UpdateInGroup(typeof(그룹))] 속성을 사용.

SystemBase 예제 (관리형 시스템)

using Unity.Burst;
using Unity.Entities;
using Unity.Transforms;
using Unity.Mathematics;
using UnityEngine;

// [UpdateInGroup(typeof(SimulationSystemGroup))]  // 특정 그룹에서 실행 가능
public partial class MoveSystem : SystemBase
{
    protected override void OnUpdate()
    {
        float deltaTime = SystemAPI.Time.DeltaTime; // 현재 프레임의 Delta Time

        Entities.ForEach((ref LocalTransform transform) =>
        {
            transform.Position += new float3(1, 0, 0) * deltaTime; // X축 이동
        }).ScheduleParallel();
    }
}

ISystem 예제 (비관리형 시스템)

using Unity.Burst;
using Unity.Entities;
using Unity.Transforms;
using Unity.Mathematics;

// 성능 최적화를 위해 [BurstCompile] 적용
[BurstCompile]
public partial struct MoveSystem_ISystem : ISystem
{
    public void OnCreate(ref SystemState state) { }  // 초기화

    public void OnDestroy(ref SystemState state) { } // 시스템 종료 시 실행

    public void OnUpdate(ref SystemState state)
    {
        float deltaTime = SystemAPI.Time.DeltaTime;

        foreach (var transform in SystemAPI.Query<RefRW<LocalTransform>>())
        {
            transform.ValueRW.Position += new float3(1, 0, 0) * deltaTime;
        }
    }
}

System 실행 순서 제어 (System Group 활용)

using Unity.Entities;

[UpdateInGroup(typeof(InitializationSystemGroup))] // 초기화 단계에서 실행
public partial class InitSystem : SystemBase
{
    protected override void OnUpdate()
    {
        UnityEngine.Debug.Log("초기화 시스템 실행됨!");
    }
}

Inspecting systems

시스템 창을 사용하여 각 세계의 시스템 업데이트 순서를 검사하고 시스템 그룹의 전체 계층을 볼 수 있습니다.

자세한 내용은 Systems window reference를 참조하세요.

에디터에서 Systems

편집기에서 다음 아이콘은 다양한 유형의 시스템을 나타냅니다.

 Entities windows와 Inspectors를 사용하면 이를 확인할 수 있습니다.

Icon	Represents
	A system group
	A system
	OrderFirst 인수를 사용하여 시스템 그룹의 시작 시 실행되도록 설정된 Entity 명령 버퍼 시스템
	OrderLast 인수를 사용하여 시스템 그룹의 끝에서 실행되도록 설정된 엔티티 명령 버퍼 시스템입니다.

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

4. 여러 종류의 Component

(6) Chunk components

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-chunk.html

Chunk Component는 개별 엔터티(Entity)가 아닌 Chunk 단위로 데이터를 저장하는 컴포넌트

즉, Chunk 전체에 대한 공통 데이터를 저장하는 데 사용됨

1) Chunk Component의 주요 특징

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-chunk-introducing.html

• Chunk에 데이터를 저장 → 개별 Entity가 아닌 Chunk 자체에 속하는 데이터
• 빠른 처리 가능 → Chunk 단위로 한 번만 검사하여 성능 최적화
• 구조적 변경(Structural Change)이 발생하지 않음
• Shared Component와 비슷하지만, 중복 제거(Deduplication) 없음
• Unmanaged 타입만 사용 가능

2) Shared Component와 차이점

Chunk Component는 구조적 변경 없이 특정 Chunk의 데이터를 조작할 때 유용

3) Chunk Component의 사용 예시

Chunk 단위로 바운딩 박스 저장

• 각 Chunk의 AABB(바운딩 박스)를 저장하여 카메라 시야 안에 있는 Chunk만 처리 가능
• 최적화 가능:각 Entity를 검사하는 대신 Chunk 단위로 필터링 가능

using Unity.Entities;
using Unity.Mathematics;

// Chunk 단위로 AABB (Axis-Aligned Bounding Box) 저장
public struct ChunkBounds : IComponentData
{
    public float3 Min;
    public float3 Max;
}

Chunk Component를 추가하는 시스템

• Chunk 내의 모든 엔터티가 공유하는 바운딩 박스 업데이트 가능
• Chunk가 카메라 안에 있는 경우만 Entity를 처리하도록 최적화 가능

using Unity.Entities;
using Unity.Mathematics;

public partial struct ChunkBoundsSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        foreach (var chunk in SystemAPI.QueryBuilder().WithAll<ChunkBounds>().Build().GetChunks(ref state))
        {
            // 예제: 바운딩 박스를 업데이트하는 로직
            chunk.SetChunkComponentData(new ChunkBounds { Min = new float3(-1, -1, -1), Max = new float3(1, 1, 1) });
        }
    }
}

특정 Chunk만 처리하는 시스템

• Chunk 단위로 화면에 보이는지 확인 후, 보이는 Chunk 만 처리
• Chunk 내부의 모든 Entity를 개별 검사하지 않고 빠르게 필터링 가능

using Unity.Entities;
using UnityEngine;

public partial struct ChunkCullingSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        foreach (var (chunkBounds, chunk) in SystemAPI.Query<ChunkBounds>().WithChunkAccess())
        {
            if (IsChunkVisible(chunkBounds))
            {
                Debug.Log("Processing entities in visible chunk");
                // Chunk 안의 Entity 처리 로직
            }
        }
    }

    private bool IsChunkVisible(ChunkBounds bounds)
    {
        // 간단한 AABB 검사 로직 (예제)
        return bounds.Min.x < 10 && bounds.Max.x > -10;
    }
}

4) Chunk Component의 장점과 단점

장점

• Chunk 단위로 데이터 저장 → 빠른 필터링 가능
• 구조적 변경이 발생하지 않음 → 성능 최적화
• 엔터티 개별 검사 없이 Chunk 레벨에서 빠른 판단 가능

단점

• 각 Chunk마다 별도로 값을 저장하므로 메모리 사용 증가 가능
• 같은 값이라도 공유되지 않음 (Shared Component처럼 Deduplication 없음)
• Managed 타입 사용 불가 (Unmanaged 타입만 가능)

5) Chunk Component 활용법

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-type.html

Chunk Component는 일반적인 IComponentData와는 다른 방식의 API를 사용하여 추가, 제거, 가져오기 및 설정을 수행해야함

특히 EntityManager의 API를 사용할 때 주의

1> Chunk Component 추가 방법

특정 Entity의 Chunk에 Chunk Component 추가

EntityManager.AddChunkComponentData<ExampleChunkComp>(entity);

• 특정 Entity가 속한 Chunk에 Chunk Component 추가
• 이때, Chunk Component는 해당 Chunk의 모든 Entity가 공유하게 됨

2> Chunk Component 조회(Query) 방법

Chunk Component를 포함하는 Chunk를 찾을 때 ComponentType.ChunkComponent<T> 사용

EntityQuery query = GetEntityQuery(
    typeof(ExampleComponent), 
    ComponentType.ChunkComponent<ExampleChunkComp>() // Chunk Component 쿼리
);
NativeArray<ArchetypeChunk> chunks = query.ToArchetypeChunkArray(Allocator.Temp);

• ExampleComponent가 포함된 Chunk 중에서 ExampleChunkComp도 있는 Chunk를 찾음

3> Chunk Component 데이터 가져오기 & 설정하기

특정 Chunk의 Chunk Component 값 설정

EntityManager.SetChunkComponentData<ExampleChunkComp>(
    chunks[0], 
    new ExampleChunkComp { Value = 6 }
);

• 첫 번째 Chunk에 대해 ExampleChunkComp 값을 6으로 설정

특정 Chunk의 Chunk Component 값 가져오기

ExampleChunkComp exampleChunkComp = EntityManager.GetChunkComponentData<ExampleChunkComp>(chunks[0]);
Debug.Log(exampleChunkComp.Value); // 6 출력

• 첫 번째 Chunk의 ExampleChunkComp 값을 가져옴

4> Entity를 통해 Chunk Component 값 가져오기 & 설정하기

특정 Entity가 속한Chunk의 Chunk Component 값을 변경

EntityManager.SetChunkComponentData<MyChunkComp>(
    entity, 
    new MyChunkComp { Value = 6 }
);

• 특정 Entity가 속한 Chunk의 MyChunkComp 값을 6으로 설정

특정 Entity가 속한 Chunk의 Chunk Component 값을 가져오기

MyChunkComp myChunkComp = EntityManager.GetChunkComponentData<MyChunkComp>(entity);
Debug.Log(myChunkComp.Value); // 6 출력

• 해당 Entity가 속한 Chunk의 MyChunkComp 값을 가져옴

5> Job에서 Chunk Component 사용하기

EntityManager는 Job 내부에서 사용할 수 없으므로 ComponentTypeHandle<T>을 활용해야 한다!

IJobChunk에서 Chunk Component 접근하기

struct MyJob : IJobChunk
{
    public ComponentTypeHandle<ExampleChunkComponent> ExampleChunkCompHandle;

    public void Execute(ArchetypeChunk chunk, int chunkIndex, int firstEntityIndex)
    {
        // 청크의 Chunk Component 데이터 가져오기
        ExampleChunkComponent myChunkComp = chunk.GetChunkComponentData(ExampleChunkCompHandle);

        // 청크의 Chunk Component 데이터 설정
        chunk.SetChunkComponentData(ExampleChunkCompHandle, new ExampleChunkComponent { Value = 7 });
    }
}

• IJobChunk 내부에서는 chunk.GetChunkComponentData()와 chunk.SetChunkComponentData()를 사용
• EntityManager 없이 직접 Chunk 데이터를 조작 가능

6> Chunk Component 관련 주의사항

• Chunk Component는 Chunk에 속하지만, 추가/제거 시 Entity의 아키타입이 변경되어 구조적 변경(Structural Change)이 발생
• 새로 생성된 Chunk Component는 기본값(Default)으로 초기화됨
• 읽기 전용으로 사용할 경우 ComponentType.ChunkComponentReadOnly<T>를 사용하면 Job 스케줄링 최적화 가능

정리

• Chunk Component는 특정 Chunk 자체의 상태를 저장하는데 유용
• EntityManager의 AddChunkComponentData(), SetChunkComponentData(), GetChunkComponentData()를 사용하여 접근
• Job에서는 ComponentTypeHandle<T>을 사용하여 접근해야 함
• 구조적 변경이 발생하지만, 개별 Entity가 아닌 Chunk 단위의 데이터를 관리하는 데 최적

Chunk 단위 데이터 최적화 및 효율적인 필터링에 적합

(7) Enableable Component

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-enableable-use.html

Enableable Component은 Entity의 특정 컴포넌트를 활성화/비활성화할 수 있도록 하는 기능

이는 구조적 변경(Structural Change) 없이 컴포넌트의 상태를 빠르게 변경할 수 있어, 자주 변하는 상태(State)를 다룰 때 유용

1) Enableable Component의 특징

• IEnableableComponent을 구현한 IComponentData 또는 IBufferElementData만 사용 가능
• 활성화/비활성화해도 아키타입(Archetype)이 변경되지 않음 → 구조적 변경 없음
• 값을 그대로 유지한 채 비활성화 가능
• 비활성화된 컴포넌트는 EntityQuery에서 존재하지 않는 것처럼 동작
• 멀티스레드(Job System)에서 안전하게 활성화/비활성화 가능
• 기본적으로 모든 Enableable Component는 활성화된 상태로 생성됨

2) Enableable Component 생성 방법

Enableable Component를 만들려면 IEnableableComponent 인터페이스를 구현해야 한다.

using Unity.Entities;

public struct Health : IComponentData, IEnableableComponent
{
    public int Value;
}

• IEnableableComponent을 추가하면 해당 컴포넌트는 활성화/비활성화 가능
• 일반적인 IComponentData와 동일하게 사용 가능

3) Enableable Component 활성화/비활성화 방법

특정 Entity의 Enableable Component 상태 확인

bool isEnabled = EntityManager.IsComponentEnabled<Health>(entity);
Debug.Log(isEnabled);  // true (기본적으로 활성화됨)

• IsComponentEnabled<T>(Entity)을 사용하여 현재 컴포넌트 상태 확인 가능

특정 Entity의 Enableable Component 비활성화

EntityManager.SetComponentEnabled<Health>(entity, false);

• SetComponentEnabled<T>(Entity, bool)을 사용하여 컴포넌트 활성화/비활성화
• 컴포넌트를 비활성화해도 값은 그대로 유지됨

비활성화된 컴포넌트의 값 가져오기

Health h = EntityManager.GetComponentData<Health>(entity);
Debug.Log(h.Value);  // 비활성화 상태여도 값은 유지됨

• 비활성화 상태에서도 값은 유지됨
• 단, EntityQuery에서는 존재하지 않는 것처럼 동작

4) Enableable Component와 EntityQuery

Enableable Component가 비활성화된 경우, 기본적으로 Query에서 제외된다.

EntityQuery query = GetEntityQuery(typeof(Health), typeof(Translation));

• Health가 비활성화된 Entity는 이 쿼리에 포함되지 않음
• Health가 활성화된 Entity만 결과에 포함됨

Enableable Component가 비활성화된 상태에서도 포함시키는 방법

EntityQuery queryIgnoreEnableable = GetEntityQuery(new EntityQueryDesc
{
    All = new ComponentType[] { typeof(Health), typeof(Translation) },
    Options = EntityQueryOptions.IgnoreComponentEnabledState
});

• EntityQueryOptions.IgnoreComponentEnabledState를 사용하면 비활성화된 컴포넌트도 포함
• 구조적 변경이 발생한 경우에만 동작이 변경되므로 더 효율적

5) Job System에서 Enableable Component 사용하기

Enableable Component는 멀티스레드(Job System)에서 안전하게 활성화/비활성화 가능하다.

Job 내부에서 Enableable Component 사용하기

struct EnableableJob : IJobEntity
{
    public ComponentLookup<Health> HealthLookup;

    public void Execute(Entity entity)
    {
        if (HealthLookup.IsComponentEnabled(entity))
        {
            // Health가 활성화된 경우
            Health h = HealthLookup[entity];
            h.Value += 10;
            HealthLookup[entity] = h;
        }
    }
}

• ComponentLookup<T>를 사용하여 Job 내부에서 안전하게 활성화/비활성화 확인 가능
• IsComponentEnabled<T>(Entity)를 활용하여 조건부 실행 가능

6) Enableable Component 관련 주의사항

• 비활성화된 컴포넌트는 EntityQuery에서 기본적으로 존재하지 않는 것으로 간주됨
• 멀티스레드 환경에서 다른 Job이 같은 컴포넌트를 변경할 경우, Race Condition 발생 가능 (경쟁)
• EntityQueryOptions.IgnoreComponentEnabledState를 사용하면 비활성화 상태도 포함 가능
• 구조적 변경을 피하기 위해 자주 변경되는 상태(State)는 Enableable Component를 활용하는 것이 유리

정리

• Enableable Component는 IEnableableComponent을 구현한 IComponentData 또는 IBufferElementData만 사용 가능
• 비활성화해도 값은 유지되지만, 기본적으로 EntityQuery에서 제외됨
• IsComponentEnabled<T>(Entity)와 SetComponentEnabled<T>(Entity, bool)을 사용하여 활성화/비활성화 가능
• 구조적 변경 없이 상태(State)를 관리할 수 있어 성능 최적화에 유리
• Job System에서도 ComponentLookup<T>를 사용하여 안전하게 활용 가능

상태 변화가 자주 발생하는 경우 Enableable Component를 사용하면 최적화에 도움

(8) Singleton Component

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-singleton.html

Singleton Component는 특정 월드(World)에서 오직 하나의 인스턴스만 존재하는 컴포넌트를 의미한다.

즉, 한 개의 Entity만 특정 컴포넌트를 가지고 있으면 Singleton Component로 간주된다.

1) Singleton Component의 특징

• 특정 월드에서 단 하나의 인스턴스만 존재
• 다른 Entity에 같은 컴포넌트를 추가하면 더 이상 Singleton이 아님
• 다른 월드에 존재하는 동일한 컴포넌트는 별도로 관리됨 (다른 월드의 Singleton 상태에 영향 없음)
• System에서 쉽게 접근할 수 있도록 Singleton 전용 API 제공
• 서버 기반 아키텍처에서 특정 클라이언트 데이터를 관리할 때 유용

2) Singleton Component 생성 방법

Singleton Component는 일반적인 IComponentData와 동일하게 생성하지만, 오직 하나의 Entity만 해당 컴포넌트를 가지도록 관리해야 한다.

using Unity.Entities;

public struct GameSettings : IComponentData
{
    public float Gravity;
}

• 일반적인 IComponentData처럼 정의 가능

Singleton Component 추가

EntityManager.CreateSingleton<GameSettings>();

• CreateSingleton<T>()을 사용하면 자동으로 단 하나의 Entity에만 추가

3) Singleton Component 접근 방법

Singleton API를 사용하면 특정 Entity를 직접 찾지 않아도 단일 인스턴스를 가져올 수 있음.

Singleton Entity 가져오기

Entity singletonEntity = EntityManager.GetSingletonEntity<GameSettings>();

• GetSingletonEntity<T>()을 사용하면 Singleton을 가진 엔터티 직접 가져오기 가능

Singleton 값 가져오기

GameSettings settings = EntityManager.GetSingleton<GameSettings>();
Debug.Log(settings.Gravity);

• GetSingleton<T>()을 사용하면 컴포넌트 데이터 직접 가져오기 가능

Singleton 값 변경하기

GameSettings settings = EntityManager.GetSingleton<GameSettings>();
settings.Gravity = 9.8f;
EntityManager.SetSingleton(settings);

• SetSingleton<T>()을 사용하여 값 수정 가능

Singleton 여부 확인

bool exists = EntityManager.HasSingleton<GameSettings>();
Debug.Log(exists);  // true or false

• HasSingleton<T>()을 사용하여 Singleton이 존재하는지 확인 가능

4) Singleton API 비교

5) Singleton Component와 SystemAPI

Singleton Component는 SystemAPI에서도 편리하게 접근 가능

SystemAPI를 이용한 Singleton 접근

public partial struct GameSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        GameSettings settings = SystemAPI.GetSingleton<GameSettings>();
        Debug.Log(settings.Gravity);
    }
}

• SystemAPI.GetSingleton<T>()을 사용하면 더 간결한 코드 가능

6) Singleton 사용 시 주의점

Singleton API는 자동으로 Job Dependency를 해결하지 않음

• EntityManager.GetComponentData<T>()는 자동으로 Job을 완료하지만, EntityManager.GetSingleton<T>()은 자동으로 Job을 완료하지 않음
• Job이 실행 중일 때 Singleton에 접근하면 오류 발생 가능
• 해결 방법: EntityManager.CompleteDependencyBeforeRO() 또는 CompleteDependencyBeforeRW() 사용

EntityManager.CompleteDependencyBeforeRO<GameSettings>();  
GameSettings settings = EntityManager.GetSingleton<GameSettings>();

GetSingletonRW<T>() 사용 시 주의

• GetSingletonRW<T>()은 참조(Reference)를 반환하므로,
  Job과 동시에 접근하면 Race Condition 발생 가능
• 안전한 사용 방법
  • 네이티브 컨테이너(NativeContainer) 내부 데이터만 수정
  • Jobs Debugger에서 오류가 없는지 반드시 확인

정리

• Singleton Component는 특정 월드에서 단 하나만 존재하는 컴포넌트
• SystemAPI 및 EntityManager를 통해 쉽게 접근 가능
• 구조적 변경 없이 특정 데이터를 쉽게 관리할 수 있음
• Job System과 함께 사용할 때는 Dependency 관리 필요
• 서버 기반 시스템이나 특정 설정 값을 관리할 때 매우 유용

GameSettings, PlayerController, ServerTimestamp 등의 전역 설정을 관리할 때 Singleton을 사용하면 편리

The post ECS – Component concepts (3) appeared first on 어제와 내일의 나 그 사이의 이야기.

4. 여러 종류의 Component

(5) Dynamic buffer components

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-buffer.html

1) Dynamic buffer 구성 요소 소개

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-buffer-introducing.html

Dynamic buffer components는 관리되지 않는 구조체들의 크기 조절이 가능한 배열처럼 작동하는 컴포넌트

예를 들어 Entity가 이동할 경로점(waypoint) 위치들과 같은 배열 데이터를 저장하는 데 사용할 수 있음

Dynamic buffer의 구성 요소

Dynamic buffer는 데이터와 함께 길이(Length), 용량(Capacity), 내부 포인터(pointer)를 저장

1. 길이 (Length):
   buffer 에 저장된 요소의 개수, 처음에는 0이며, 값을 추가할 때마다 증가
2. 용량 (Capacity):
   buffer 에 저장할 수 있는 요소의 최대 개수
   처음에는 내부 버퍼 용량과 동일하게 시작하고, 용량을 설정하여 버퍼 크기를 조정
3. 포인터 (Pointer):
   Dynamic buffer 데이터의 위치를 나타냄
   처음에는 데이터가 Entity의 Chunk 내에 있을 때 null로 설정되며,
   Unity가 데이터를 Chunk 밖으로 이동시키면 포인터가 새 배열을 가리키도록 설정됩니다.

Dynamic buffer 용량

Dynamic buffer의 초기 용량은 버퍼가 저장하는 타입에 의해 정의됩니다.

기본적으로 용량은 128바이트에 맞게 설정됩니다.

만약 더 큰 용량이 필요하면 InternalBufferCapacity 속성을 사용하여 커스터마이즈할 수 있습니다.

구조적 변경(Structural Changes)

구조적 변경(Structural Changes) : Entity의 생성, 삭제, 또는 컴포넌트 추가/제거와 같은 작업이 수행될 때 Unity의 ECS 시스템 내부에서 구조적 변화가 발생함

Structural Changes는 Dynamic buffer가 참조하는 배열을 파괴하거나 이동시킬 수 있기 때문에, 구조적 변화 후에는 Dynamic buffer에 대한 Handle이 무효화됩니다.

Structural Changes 후에는 Dynamic buffer를 다시 가져와야 합니다.

예를 들어:

public void DynamicBufferExample(Entity e)
{
    // MyElement 타입의 동적 버퍼를 가져옵니다.
    DynamicBuffer<MyElement> myBuff = EntityManager.GetBuffer<MyElement>(e);

    // 이 Structural Changes는 이전에 얻은 DynamicBuffer를 무효화시킵니다.
    EntityManager.CreateEntity();

    // 안전 검사로 인해 버퍼에 대한 읽기/쓰기 작업에서 예외가 발생합니다.
    var x = myBuff[0];

    // Structural Changes 후 동적 버퍼를 다시 가져옵니다.
    myBuff = EntityManager.GetBuffer<MyElement>(e);
    var y = myBuff[0];
}

네이티브 컨테이너와의 비교

Dynamic buffer는 네이티브 컨테이너가 컴포넌트에서 사용하는 작업 스케줄링 제한이 없으므로, 가능한 경우 코드에서 Dynamic buffer를 사용하는 것이 더 나은 선택입니다.

또한, Dynamic buffer는 Chunk 내에 인라인으로 저장될 수 있어 메모리 대역폭 사용을 줄이는 데 도움을 줍니다.

일반적으로, 여러 Entity가 동일한 컬렉션을 필요로 한다면 Dynamic buffer를 사용하는 것이 좋습니다.

만약 하나의 Entity만 필요하다면 네이티브 컨테이너를 가진 싱글톤 컴포넌트로 처리하는 것이 좋을 수 있습니다.

• Dynamic buffer는 작업 스케줄링 제한이 없고, 메모리 사용 측면에서도 효율적

비교 항목	동적 버퍼 (DynamicBuffer<T>)	NativeContainer (NativeArray<T>, NativeList<T>)
ECS와의 연동	Entity에 직접 부착 가능	ECS Entity와 직접 연결 불가
Job 시스템 사용	가능 (ReadOnly 또는 ParallelForEach 가능)	가능 ([NativeContainer] 필요)
메모리 위치	Chunk 내 저장 (최적화됨) → 크기 초과 시 자동 이동	Chunk 외부 할당
구조적 변화 영향	구조적 변화 시 무효화됨 → 재할당 필요	영향 없음

• 여러 개의 엔티티가 배열 데이터를 가질 필요가 있다면 DynamicBuffer<T>를 사용하는 것이 좋음
• 싱글톤 데이터처럼 전역적으로 관리할 경우 NativeContainer를 사용하는 것이 유리함

2) Dynamic buffer 컴포넌트 생성 및 사용 방법

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-buffer-create.html

IBufferElementData를 상속한 구조체 생성

Dynamic buffer의 개별 요소를 정의하는 구조체를 만들고, IBufferElementData를 상속받아야 합니다.

using Unity.Entities;

// Dynamic buffer의 요소가 되는 구조체 정의
// 기본적으로 16개의 요소를 저장할 수 있도록 설정
// 만약 16개를 초과하면 Unity가 자동으로 Chunk 외부 메모리로 확장
[InternalBufferCapacity(16)]
public struct ExampleBufferComponent : IBufferElementData
{
    public int Value; // 버퍼 요소 값
}

Entity에 Dynamic buffer 추가하기

DynamicBuffer<T>를 사용하여 엔티티에 동적 버퍼를 추가하고, 값을 삽입

Entity entity = EntityManager.CreateEntity();
DynamicBuffer<ExampleBufferComponent> buffer = EntityManager.AddBuffer<ExampleBufferComponent>(entity);

// 데이터 추가
buffer.Add(new ExampleBufferComponent { Value = 10 });
buffer.Add(new ExampleBufferComponent { Value = 20 });

// 현재 길이 확인 (2개 요소가 들어있음)
UnityEngine.Debug.Log("Buffer Length: " + buffer.Length);

Dynamic buffer 읽기

Dynamic buffer는 배열처럼 접근할 수 있습니다.

DynamicBuffer<ExampleBufferComponent> buffer = EntityManager.GetBuffer<ExampleBufferComponent>(entity);

for (int i = 0; i < buffer.Length; i++)
{
    UnityEngine.Debug.Log("Buffer Element " + i + ": " + buffer[i].Value);
}

동적 버퍼에서 요소 제거

요소를 제거할 때는 RemoveAt() 또는 Clear()를 사용할 수 있습니다.

buffer.RemoveAt(0); // 첫 번째 요소 제거
buffer.Clear(); // 모든 요소 제거

동적 버퍼의 사용 예시

• 웨이포인트(Waypoints) 저장하기

using Unity.Entities;
using Unity.Mathematics;

// 웨이포인트를 저장하는 동적 버퍼
[InternalBufferCapacity(4)]
public struct WaypointBuffer : IBufferElementData
{
    public float3 Position; // 좌표 정보
}

// 엔티티에 웨이포인트 버퍼 추가
Entity entity = EntityManager.CreateEntity();
DynamicBuffer<WaypointBuffer> waypoints = EntityManager.AddBuffer<WaypointBuffer>(entity);

// 웨이포인트 추가
waypoints.Add(new WaypointBuffer { Position = new float3(0, 0, 0) });
waypoints.Add(new WaypointBuffer { Position = new float3(1, 0, 0) });
waypoints.Add(new WaypointBuffer { Position = new float3(2, 0, 0) });

• 시스템에서 동적 버퍼 활용

ISystem을 활용하여 동적 버퍼를 검색하고 처리하는 시스템을 구현

using Unity.Entities;
using Unity.Burst;
using Unity.Collections;
using Unity.Mathematics;

[BurstCompile]
public partial struct WaypointSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        foreach (var (waypoints, entity) in SystemAPI.Query<DynamicBuffer<WaypointBuffer>>().WithEntityAccess())
        {
            foreach (var waypoint in waypoints)
            {
                UnityEngine.Debug.Log("Waypoint Position: " + waypoint.Position);
            }
        }
    }
}

3) Dynamic Buffer 용량 설정

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-buffer-set-capacity.html

Dynamic Buffer의 초기 용량 (Default Capacity)

• Dynamic Buffer는 초기 용량을 가지고 있으며, 기본적으로 128바이트 크기로 설정
• 128바이트는 TypeManager.DefaultBufferCapacityNumerator를 통해 결정
• 예를 들어, int(4바이트) 값을 저장하는 버퍼라면 기본적으로 32개의 요소를 저장할 수 있음

Dynamic Buffer의 메모리 저장 방식

초기 상태

• Entity의 아키타입 청크(Archetype Chunk) 내부에 저장됨.
• 일반적인 IComponentData처럼 빠르게 접근 가능.

버퍼 크기가 초기 용량을 초과할 경우

• Chunk 외부에 새로운 메모리 공간을 할당하고 데이터를 복사함.
• 이후 해당 버퍼는 항상 Chunk 외부 메모리를 사용하게 됨.
• 단점:
  • 메모리 할당 비용 증가
  • CPU 캐시 효율 저하 (Chunk 내부에 있던 데이터가 캐시에서 빠짐)
  • Chunk 내부에 빈 공간(fragmentation)이 생겨서 메모리 낭비 발생

Dynamic Buffer의 내부 용량 설정 (InternalBufferCapacity)

초기 용량을 커스텀 설정하려면 InternalBufferCapacity 속성을 사용

// 청크 내부에 최대 42개의 요소를 저장 가능
// 43개 이상 추가 시, 자동으로 청크 외부 메모리로 이동됨
[InternalBufferCapacity(42)]
public struct MyBufferElement : IBufferElementData
{
    public int Value;
}

초기 용량을 0으로 설정하면?

• 버퍼의 모든 데이터가 청크 외부 메모리에 저장됨.
• 버퍼 크기가 계속 변하는 경우 유리 (즉, 초기에 작은 용량을 두지 않음).

[InternalBufferCapacity(0)]
public struct MyBufferElement : IBufferElementData
{
    public int Value;
}

최적화

• 버퍼 크기를 예상할 수 있다면 InternalBufferCapacity를 적절히 설정
• 버퍼 크기가 자주 변경되면 InternalBufferCapacity(0)을 사용하여 메모리 재할당 비용을 줄임

동적으로 용량 조절 (EnsureCapacity & TrimExcess)

• 실행 중에 버퍼 용량을 설정하려면 EnsureCapacity() 사용

DynamicBuffer<MyBufferElement> buffer = entityManager.GetBuffer<MyBufferElement>(entity);
buffer.EnsureCapacity(100); // 100개 요소를 저장할 수 있도록 미리 용량 할당

• 불필요한 메모리를 줄이려면 TrimExcess() 사용

buffer.TrimExcess(); // 현재 길이에 맞게 불필요한 메모리 정리

최적화

• 자주 Add()로 데이터를 추가하는 경우 EnsureCapacity()를 미리 호출하면 성능 향상
• 더 이상 사용하지 않는 메모리를 줄이려면 TrimExcess() 사용

Dynamic Buffer보다 더 나은 대안?

• Dynamic Buffer의 용량 제한이 문제라면, 다음과 같은 대안 고려 가능
  1. Blob Assets
     • 불변(읽기 전용) 데이터를 저장하는 데 적합
     • 여러 엔티티가 공유 가능
     • 멀티스레딩 접근 가능
  2. NativeContainer + IComponentData 조합
     • NativeArray<T> 또는 NativeList<T> 등을 사용하여 별도로 관리 가능

4) Chunk 내 Dynamic Buffer 접근 방법

모든 동적 버퍼를 한 번에 가져오려면 ArchetypeChunk.GetBufferAccessor() 사용

GetBufferAccessor<T>()는 BufferAccessor<T>를 반환하며, 이를 통해 Chunk 내 모든 Entity의 버퍼에 접근 가능

필요한 요소

1. EntityQueryBuilder로 Entity 쿼리 생성
2. EntityQuery에서 Chunk 배열(NativeArray<ArchetypeChunk>) 가져오기
3. BufferTypeHandle<T>을 사용하여 Dynamic Buffer 핸들 생성
4. GetBufferAccessor<T>()로 Chunk 내 모든 버퍼 가져오기
5. 반복문을 통해 버퍼 데이터 처리

Dynamic Buffer 접근 시스템 (SystemBase 기반)

using Unity.Burst;
using Unity.Collections;
using Unity.Entities;

[InternalBufferCapacity(16)] // 내부 용량을 16개 요소로 설정 (초과 시 Chunk 외부 메모리로 이동)
public struct ExampleBufferComponent : IBufferElementData
{
    public int Value;
}


public partial class ExampleSystem : SystemBase
{
    protected override void OnUpdate()
    {
        // EntityQuery를 생성하여 ExampleBufferComponent를 가진 Entity 필터링
        var query = new EntityQueryBuilder(Allocator.Temp)
            .WithAllRW<ExampleBufferComponent>() // 읽기/쓰기 가능한 버퍼 포함
            .Build(EntityManager);

        // 쿼리를 통해 ArchetypeChunk 배열 가져오기
        NativeArray<ArchetypeChunk> chunks = query.ToArchetypeChunkArray(Allocator.Temp);

        // Chunk 순회하면서 처리
        for (int i = 0; i < chunks.Length; i++)
        {
            UpdateChunk(chunks[i]);
        }
        
        // 메모리 해제
        chunks.Dispose();
    }

    private void UpdateChunk(ArchetypeChunk chunk)
    {
        // ExampleBufferComponent에 대한 BufferTypeHandle 가져오기
        BufferTypeHandle<ExampleBufferComponent> bufferTypeHandle = GetBufferTypeHandle<ExampleBufferComponent>();

        // Chunk에서 BufferAccessor 가져오기
        BufferAccessor<ExampleBufferComponent> buffers = chunk.GetBufferAccessor(ref bufferTypeHandle);

        //  Chunk 내 모든 Entity 의 Dynamic Buffer 접근
        for (int i = 0, chunkEntityCount = chunk.Count; i < chunkEntityCount; i++)
        {
            DynamicBuffer<ExampleBufferComponent> buffer = buffers[i];

            // 각 Entity의 동적 버퍼 요소 접근
            for (int j = 0; j < buffer.Length; j++)
            {
                UnityEngine.Debug.Log($"Buffer Element {j}: {buffer[j].Value}");
            }
        }
    }
}

Dynamic Buffer 접근 시스템 (ISystem 기반)

using Unity.Burst;
using Unity.Collections;
using Unity.Entities;

[InternalBufferCapacity(16)]
public struct ExampleBufferComponent : IBufferElementData
{
    public int Value;
}

[BurstCompile] // 성능 최적화
public partial struct ExampleSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        // EntityQuery를 생성하여 ExampleBufferComponent를 가진 Entity 필터링
        EntityQuery query = SystemAPI.QueryBuilder()
            .WithAllRW<ExampleBufferComponent>() // 읽기/쓰기 가능한 버퍼 포함
            .Build();

        // 쿼리를 통해 ArchetypeChunk 배열 가져오기
        NativeArray<ArchetypeChunk> chunks = query.ToArchetypeChunkArray(Allocator.Temp);

        // BufferTypeHandle 가져오기
        BufferTypeHandle<ExampleBufferComponent> bufferTypeHandle = state.GetBufferTypeHandle<ExampleBufferComponent>();

        // 모든 Chunk 순회하면서 Dynamic Buffer 처리
        foreach (var chunk in chunks)
        {
            UpdateChunk(chunk, ref bufferTypeHandle);
        }

        // NativeArray 해제
        chunks.Dispose();
    }

    private void UpdateChunk(ArchetypeChunk chunk, ref BufferTypeHandle<ExampleBufferComponent> bufferTypeHandle)
    {
        // Chunk에서 BufferAccessor 가져오기
        BufferAccessor<ExampleBufferComponent> buffers = chunk.GetBufferAccessor(ref bufferTypeHandle);

        // Chunk 내 모든 Entity의 Dynamic Buffer 접근
        for (int i = 0; i < chunk.Count; i++)
        {
            DynamicBuffer<ExampleBufferComponent> buffer = buffers[i];

            // 각 Entity의 Dynamic Buffer 요소 접근
            for (int j = 0; j < buffer.Length; j++)
            {
                UnityEngine.Debug.Log($"Buffer Element {j}: {buffer[j].Value}");
            }
        }
    }
}

5) 여러 Entity에서 동일한 Dynamic Buffer 재사용

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-buffer-reuse.html

여러 Entity에서 동일한 동적 버퍼 사용하기

• IJobEntity 내에서 같은 DynamicBuffer를 공유하는 방법
• 동일한 동적 버퍼를 여러 엔티티에 적용하는 경우, 메인 스레드에서 먼저 버퍼를 가져온 후 Job에 전달

SystemBase 기반 예제

using Unity.Entities;
using Unity.Burst;
using Unity.Jobs;

public struct MyElement : IBufferElementData
{
    public int Value;
}

public struct OtherComponent : IComponentData {}

public partial class ExampleSystem : SystemBase
{
    protected override void OnUpdate()
    {
        // 특정 엔티티에서 DynamicBuffer 가져오기
        Entity e = GetSingletonEntity<MyElement>();
        DynamicBuffer<MyElement> myBuffer = SystemAPI.GetBuffer<MyElement>(e);

        // Job에 버퍼 전달하여 여러 엔티티에서 사용
        new MyJobEntity { MyBuffer = myBuffer }.Schedule();
    }

    [BurstCompile]
    public partial struct MyJobEntity : IJobEntity
    {
        public DynamicBuffer<MyElement> MyBuffer;

        public void Execute(in OtherComponent other)
        {
            // MyBuffer를 모든 엔티티에서 공유
            for (int i = 0; i < MyBuffer.Length; i++)
            {
                UnityEngine.Debug.Log($"Shared Buffer Element: {MyBuffer[i].Value}");
            }
        }
    }
}

ScheduleParallel을 사용할 때 주의할 점

• ScheduleParallel을 사용하면 다중 스레드 환경에서 DynamicBuffer를 직접 수정할 수 없음
• EntityCommandBuffer.ParallelWriter를 활용해야 함
• 그러나 구조적 변경(Structural Change)이 발생하면 버퍼가 무효화됨

ScheduleParallel을 사용할 때 EntityCommandBuffer 활용 예제

protected override void OnUpdate()
{
    Entity e = GetSingletonEntity<MyElement>();
    DynamicBuffer<MyElement> myBuffer = SystemAPI.GetBuffer<MyElement>(e);

    EntityCommandBuffer ecb = new EntityCommandBuffer(Allocator.TempJob);
    EntityCommandBuffer.ParallelWriter ecbParallel = ecb.AsParallelWriter();

    Entities
        .WithAll<OtherComponent>()
        .ForEach((Entity entity, int entityInQueryIndex) =>
        {
            // EntityCommandBuffer를 사용하여 동적 버퍼에 변경 적용
            var buffer = ecbParallel.AddBuffer<MyElement>(entityInQueryIndex, entity);
            buffer.CopyFrom(myBuffer);
        }).ScheduleParallel();

    Dependency.Complete();
    ecb.Playback(EntityManager);
    ecb.Dispose();
}

최적화

• 같은 버퍼를 여러 Entity에서 사용하면 메모리 절약 가능
• ScheduleParallel을 사용할 때는 EntityCommandBuffer.ParallelWriter 필요
• Dynamic Buffer 변경 시 구조적 변화(Structural Changes) 발생 가능 → 버퍼 재획득 필요
• 캐시 효율을 고려하여 버퍼 크기 최적화 (InternalBufferCapacity)

동일한 Dynamic Buffer를 재사용하면 성능과 메모리 사용량을 최적화

6) Job에서 DynamicBuffer 접근 및 활용

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-buffer-jobs.html

Job에서 DynamicBuffer 접근

• IJobEntity에서 여러 엔티티의 Dynamic Buffer를 조회하려면 BufferLookup<T>를 사용해야 함
• BufferLookup<T>는 EntityManager에서 Dynamic Buffer를 효율적으로 검색할 수 있도록 하는 Lookup Table

BufferLookup<T>를 활용한 Job 예제

using Unity.Entities;
using Unity.Burst;
using Unity.Collections;

[InternalBufferCapacity(16)]
public struct ExampleBufferComponent : IBufferElementData
{
    public int Value;
}

[BurstCompile]
public partial struct AccessDynamicBufferJob : IJobEntity
{
    // ReadOnly BufferLookup 멤버 변수를 추가
    [ReadOnly] public BufferLookup<ExampleBufferComponent> BufferLookup;

    public void Execute(Entity entity)
    {
        if (BufferLookup.HasBuffer(entity))
        {
            DynamicBuffer<ExampleBufferComponent> buffer = BufferLookup[entity];
            for (int i = 0; i < buffer.Length; i++)
            {
                UnityEngine.Debug.Log($"Entity {entity.Index} - Buffer[{i}] = {buffer[i].Value}");
            }
        }
    }
}

System에서 BufferLookup<T> 관리하기 (ISystem 버전)

public partial struct AccessDynamicBufferFromJobSystem : ISystem
{
    private BufferLookup<ExampleBufferComponent> _bufferLookup;

    public void OnCreate(ref SystemState state)
    {
        _bufferLookup = state.GetBufferLookup<ExampleBufferComponent>(true);
    }

    public void OnUpdate(ref SystemState state)
    {
        _bufferLookup.Update(ref state);

        var job = new AccessDynamicBufferJob { BufferLookup = _bufferLookup };
        job.ScheduleParallel();
    }
}

BufferLookup<T>는 매 프레임 Update()를 호출해야 최신 데이터를 유지할 수 있음
ScheduleParallel()을 사용하면 여러 Entity에서 병렬 처리 가능

7) EntityCommandBuffer(ECB)에서 DynamicBuffer 수정

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-buffer-command-buffer.html

ECB(EntityCommandBuffer) 는 미래에 실행될 변경 사항을 기록하는 역할을 하며, DynamicBuffer에 대한 특별한 API를 제공

• SetBuffer<T>() → 버퍼 내용을 덮어씀
• AppendToBuffer<T>() → 기존 버퍼에 요소 추가 (버퍼 없으면 예외 발생)
• AddBuffer<T>() → 버퍼가 없으면 추가 (버퍼가 있으면 SetBuffer처럼 동작)
• RemoveComponent<T>() → 버퍼 제거

using Unity.Entities;
using Unity.Collections;

public struct MyElement : IBufferElementData
{
    public int Value;
}

public partial struct ExampleECBSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        var ecb = new EntityCommandBuffer(Allocator.TempJob);
        
        Entity entity = SystemAPI.GetSingletonEntity<MyElement>(); 
        Entity otherEntity = SystemAPI.GetSingletonEntity<MyElement>();

        // 버퍼 삭제
        ecb.RemoveComponent<MyElement>(entity);

        // 새 버퍼 추가 및 초기화
        DynamicBuffer<MyElement> myBuff = ecb.AddBuffer<MyElement>(entity);
        myBuff.Add(new MyElement { Value = 5 });
        myBuff.Add(new MyElement { Value = -9 });

        // 기존 버퍼 덮어쓰기 (없으면 예외 발생)
        DynamicBuffer<MyElement> otherBuf = ecb.SetBuffer<MyElement>(otherEntity);
        otherBuf.Add(new MyElement { Value = 10 });

        // 버퍼에 요소 추가 (버퍼가 없으면 예외 발생)
        ecb.AppendToBuffer(otherEntity, new MyElement { Value = 12 });

        ecb.Playback(state.EntityManager);//  Playback()이 호출될 때 실제 변경이 적용됨
        ecb.Dispose();
    }
}

• ECB는 Playback()이 호출될 때 실제 변경이 적용됨
• SetBuffer<T>() → 기존 버퍼가 없으면 예외 발생
• AppendToBuffer<T>() → 버퍼가 없으면 예외 발생 (안전하게 사용하려면 AddComponent<T>() 선행)
• AddBuffer<T>() → 없으면 추가하고, 있으면 기존 내용을 덮어씀

8) Reinterpret()을 이용한 버퍼 변환

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-buffer-reinterpret.html

Reinterpret<T>()을 사용하면 같은 크기의 다른 타입으로 변환 가능

단, 메모리 크기가 같은 경우에만 가능 (int ↔ float, struct ↔ int 등)

public partial class ExampleSystem : SystemBase
{
    private void ReinterpretEntitysChunk(Entity e)
    {
        DynamicBuffer<MyElement> myBuff = EntityManager.GetBuffer<MyElement>(e);

        // MyElement의 Value 필드가 int이므로 int 버퍼로 변환 가능
        DynamicBuffer<int> intBuffer = myBuff.Reinterpret<int>();

        intBuffer[2] = 6;  // 동일한 메모리를 참조하므로 myBuff[2]도 변경됨

        MyElement myElement = myBuff[2];
        Debug.Log(myElement.Value);    // 6
    }
}

Reinterpret<T>()은 메모리를 공유하므로, 한쪽을 수정하면 다른 쪽도 변경됨
안전성 검토 필수 (struct 내부 메모리 크기를 고려해야 함)

Reinterpret<T>()를 사용하는 주요 이유

1. 데이터 변환 효율성

• 실제 메모리 복사 없이 같은 메모리를 다른 타입으로 해석할 수 있음
• 큰 데이터 셋을 다룰 때 성능상 이점이 큼
• 메모리 할당 오버헤드 방지

2. 데이터 호환성

// 예: 네트워크나 파일에서 받은 바이트 데이터를 직접 구조체로 해석
DynamicBuffer<byte> rawData = ...;
DynamicBuffer<MyStruct> structData = rawData.Reinterpret<MyStruct>();

3. 저수준 최적화

• 예를 들어 float 배열을 int 비트 패턴으로 직접 조작해야 할 때
• SIMD 연산이나 특수한 비트 연산을 수행할 때 유용

4. 다양한 데이터 뷰 제공

// 같은 메모리를 다른 관점에서 접근 가능
DynamicBuffer<Vector3> positions = ...;
DynamicBuffer<float> rawFloats = positions.Reinterpret<float>();

주의사항:

• 메모리 크기가 정확히 일치해야 함
• 타입 안전성이 깨질 수 있으므로 신중히 사용
• 데이터 정렬(alignment) 고려 필요

The post ECS – Component concepts (2) appeared first on 어제와 내일의 나 그 사이의 이야기.

1. Component란?

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/concepts-components.html

Unity의 DOTS (Data-Oriented Technology Stack)에서 ECS(Entity Component System)의 핵심 요소 중 하나

ComponentData는 ECS에서 “데이터”를 저장하는 구조체

위의 예시에서 Speed, Direction, Position, Renderer가 Component

특징

• 일반적으로 값 타입(struct) 선언
• OOP의 클래스 필드와 비슷한 역할을 하지만, GameObject나 MonoBehaviour 대신 Entity에 데이터를 부착하는 방식
• Unity의 ECS는 데이터와 로직을 분리하여 성능을 극대화하는 구조이므로, IComponentData는 순수 데이터만 포함하는 것이 좋음

사용 예시

• Entity의 위치를 저장하는 PositionComponent를 선언

using Unity.Entities;
using Unity.Mathematics;

// 위치 정보를 저장하는 컴포넌트
public struct PositionComponent : IComponentData
{
    public float3 Value;
}

2. IComponentData를 사용하여 Entity에 데이터 추가

IComponentData를 사용하려면 엔터티(Entity)에 추가해야 함

사용 예시

• MonoBehaviour에서 ECS Entity로 데이터를 변환하는 Baker를 사용하여 PositionComponent를 Entity에 추가

using Unity.Entities;
using UnityEngine;

public class PositionAuthoring : MonoBehaviour
{
    public Vector3 Position;

    // Baker 클래스는 이를 ECS의 PositionComponent로 변환하여 엔터티에 추가
    class Baker : Baker<PositionAuthoring>
    {
        public override void Bake(PositionAuthoring authoring)
        {
            var entity = GetEntity(TransformUsageFlags.Dynamic);
            AddComponent(entity, new PositionComponent { Value = authoring.Position });
        }
    }
}

3. IComponentData를 읽고 수정하는 방법

ECS에서는 시스템(System)을 이용하여 데이터를 처리

사용 예시

• IComponentData는 ComponentLookup<T> 또는 SystemAPI를 사용해 접근
• Entities.ForEach 또는 IJobEntity를 사용해 병렬 처리

using Unity.Burst;
using Unity.Entities;
using Unity.Jobs;
using Unity.Mathematics;

// BurstCompile을 사용하여 성능 최적화
[BurstCompile]
public partial struct MoveSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        // SystemAPI.Query<RefRW<T>>()를 사용하여 컴포넌트에 접근하고 데이터를 수정함
        foreach (var position in SystemAPI.Query<RefRW<PositionComponent>>())
        {
            position.ValueRW.Value += new float3(1, 0, 0); // X 방향으로 이동
        }
    }
}

4. 여러 종류의 Component

Component는 여러 다른 유형이 있음

프로젝트에서 데이터를 관리하는 방법에 따라 특정 Component를 사용하면 애플리케이션 성능을 보다 세밀하게 제어할 수 있음

Editor에서 Component types

에디터에서 다음 아이콘은 다양한 컴포넌트 유형을 나타냅니다. 이는 관련 Entities windows and Inspectors에 나타납니다.

Icon	Component type
	A managed component.
	A shared component.
	A tag component.
	A buffer component.
	A chunk component.

Unity는 목록에 없는 구성 요소 유형에 대해 일반적인 구성 요소 아이콘을 사용합니다.

(1) Unmanaged components

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-unmanaged.html

Unmanaged components는 일반적인 데이터 유형을 저장하는 데 사용하며 아래 유형의 필드를 저장할 수 있음

• Blittable types
• bool
true 또는 false 값을 가지는 논리형(Boolean) 타입
• char
  단일 문자(Character)를 저장, 일반적으로 UTF-16 코드 단위
• BlobAssetReference<T> 
  Blob 데이터 구조에 대한 참조, 대량의 불변(Immmutable) 데이터를 효율적으로 저장하고 공유하는 데 사용
• Collections.FixedString 
  고정 크기(Fixed-Size) 문자열 버퍼
  가변 크기 문자열인 string 대신 GC(가비지 컬렉션) 없이 문자열을 저장할 때 사용
• Collections.FixedList
  고정 크기 리스트(Fixed-Size List), 일반 List<T> 대신, 할당 없이 고정된 크기의 배열을 사용하는 리스트 구조.
• Fixed array (unsafe context에서만 사용 가능)
• 기타 Blittable 조건을 충족하는 구조체(Structs)
  Blittable 타입만 포함하는 다른 struct도 Blittable 타입이 될 수 있음
  즉, 모든 필드가 Blittable 타입으로 구성된 struct는 Blittable로 간주됨.

Blittable 타입

Blittable(블리터블)이란, 메모리에서 직접 복사(Copy)할 수 있는 데이터 타입을 의미

쉽게 말해, CPU가 메모리를 변환 없이 그대로 읽고 쓸 수 있는 데이터 타입

ECS(Entity Component System)에서 IComponentData는 Blittable 타입을 요구함

Blittable 타입은 관리되지 않는 네이티브 메모리에서 안전하게 사용할 수 있어 성능이 뛰어남

가비지 컬렉션(GC) 영향을 받지 않아 메모리 효율성이 높아짐

Blittable 타입	CPU가 변환 없이 직접 복사 가능
bool, char, int, float, double	기본적인 값 타입(Primitive Type)
float2, float3, float4 (Unity.Mathematics)	SIMD 연산 최적화 가능
BlobAssetReference<T>	Blob 데이터 구조체
FixedString, FixedList	고정 크기의 문자열 및 리스트

Non-Blittable 타입	직접 복사할 수 없고 변환이 필요함
string	가변 길이 문자열 (Heap 할당)
List<T> / Dictionary<K, V>	동적 크기 컨테이너 (Heap 할당)
class (참조 타입)	힙 메모리에 저장되며, 포인터를 가짐
object	박싱(Boxing) 필요

using Unity.Burst;
using Unity.Entities;
using Unity.Mathematics;

// Blittable한 IComponentData 구조체 정의
public struct MoveSpeed : IComponentData
{
    public float Value; // Blittable 타입(float) 사용
}

// 엔터티에 MoveSpeed 컴포넌트를 추가하는 Authoring 스크립트
using UnityEngine;

public class MoveSpeedAuthoring : MonoBehaviour
{
    public float speed;

    class Baker : Baker<MoveSpeedAuthoring>
    {
        public override void Bake(MoveSpeedAuthoring authoring)
        {
            var entity = GetEntity(TransformUsageFlags.Dynamic);
            AddComponent(entity, new MoveSpeed { Value = authoring.speed });
        }
    }
}

// MoveSpeed 값을 사용하여 Entity를 이동시키는 시스템
[BurstCompile] // 성능 최적화
public partial struct MoveSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        foreach (var moveSpeed in SystemAPI.Query<RefRW<MoveSpeed>>())
        {
            moveSpeed.ValueRW.Value += 0.1f; // X 방향으로 이동 속도 증가
        }
    }
}

(2) Managed Components

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-managed.html

Managed Components(관리되는 컴포넌트)는 어떤 타입의 필드라도 저장할 수 있는 IComponentData이지만, 성능상 단점이 있음.

• class 타입으로 선언하며, GC(가비지 컬렉션)의 영향을 받음
• Job System과 Burst 컴파일러에서 사용 불가
• 직렬화(Serialization)를 위해 매개변수가 없는 생성자 필수

특징	Managed Components	Unmanaged Components
저장 가능한 데이터	모든 타입 사용 가능	Blittable 타입만 가능
메모리 저장 방식	개별 배열(Array) 관리	ECS의 Chunk에 직접 저장
Burst 지원	지원되지 않음	지원됨
Job System 사용 가능 여부	불가능	가능
GC 영향	GC 발생	GC 없음
직렬화 필요 여부	매개변수 없는 생성자 필수	필요 없음

Managed Component 생성 예시

using Unity.Entities;

// 클래스(class) 타입으로 Managed Component 생성
public class ExampleManagedComponent : IComponentData
{
    public int Value; // 관리되는 타입(int) 저장 가능
}

Managed Component를 Entity에 추가하는 Authoring 스크립트 예시

using UnityEngine;
using Unity.Entities;

public class ExampleManagedComponentAuthoring : MonoBehaviour
{
    public int Value;

    class Baker : Baker<ExampleManagedComponentAuthoring>
    {
        public override void Bake(ExampleManagedComponentAuthoring authoring)
        {
            var entity = GetEntity(TransformUsageFlags.Dynamic);
            AddComponent(entity, new ExampleManagedComponent { Value = authoring.Value });
        }
    }
}

Managed Component를 조회하고 수정하는 시스템 예시

using Unity.Entities;
using Unity.Burst;

// Managed Component는 Burst를 사용할 수 없음
// [BurstCompile] 사용 불가능
public partial struct ExampleManagedComponentSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        
        foreach (var managedComponent in SystemAPI.Query<ExampleManagedComponent>())
        {
            // 주의:Managed Component는 RefRW<T>로 접근할 수 없으며, 직접 접근 방식을 사용해야 함.
            managedComponent.Value += 1; // 값 증가
        }
    }
}

외부 리소스를 관리하는 Managed Component (ICloneable & IDisposable)

• Managed Component가 외부(UnityEngine.Object) 리소스를 참조할 경우, 복제 및 제거 시 주의해야 함.

using UnityEngine;
using Unity.Entities;
using System;

// 외부 리소스의 수명 주기를 관리
public class ManagedComponentWithResource : IComponentData, IDisposable, ICloneable
{
    public ParticleSystem ParticleSystem; // Unity Object 참조

    // 엔터티가 삭제될 때 ParticleSystem도 파괴되도록 설정
    public void Dispose()
    {
        UnityEngine.Object.Destroy(ParticleSystem);
    }

    // 엔터티를 복제할 때 새로운 ParticleSystem을 생성하도록 설정
    public object Clone()
    {
        return new ManagedComponentWithResource
        {
            ParticleSystem = UnityEngine.Object.Instantiate(ParticleSystem)
        };
    }
}

Managed Component를 이용한 최적화

Managed Component는 성능이 낮기 때문에, 가능한 경우 Unmanaged Component를 사용해야 함

그러나, 아래와 같은 상황에서는 Managed Component를 사용할 수밖에 없음

• Unmanaged Component로 표현할 수 없는 데이터 저장 (string, List<T>, class)
• UnityEngine.Object를 직접 참조해야 하는 경우 (GameObject, ParticleSystem)
• GC 부하를 감수하고라도 가변 데이터 구조 필요할 때

(3) Shared Components

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-shared.html

Shared Components(공유 컴포넌트)는 같은 값을 가진 Entity들을 같은 Chunk로 그룹화하는 ISharedComponentData 타입

일반 IComponentData와 다르게, Chunk 단위로 저장되며, 동일한 값의 Entity들은 같은 Chunk에 배치됩니다.

항목	Shared Components	Unmanaged Components
저장 단위	Chunk 단위 저장	개별 Entity별 저장
Burst 지원	지원되지 않음	지원됨
Job System 사용 가능 여부	불가능	가능
GC 영향	GC 발생 가능	GC 없음
직렬화 필요 여부	필요함	필요 없음
데이터 변경 시 영향	값이 바뀌면 Chunk가 재배치됨	구조적 변경 없음

Shared Components는 같은 값을 가진 Entity들이 같은 Chunk에 배치되므로 메모리 캐시 적중률을 높이는 데 유용

그러나, 값을 변경할 경우 Entity가 다른 Chunk로 이동해야 하므로 빈번한 변경이 필요할 경우 적합하지 않음

Managed Components와 달리, struct 타입으로 선언하지만 내부적으로 class를 포함할 수 있음

Burst 및 Job System을 사용할 수 없으므로 성능이 중요한 곳에서는 Unmanaged Components를 사용하는 것이 좋음

Shared Component 생성 예시

using Unity.Entities;

// ISharedComponentData를 상속받아 Shared Component 생성
public struct ExampleSharedComponent : ISharedComponentData
{
    public int GroupId; // 같은 GroupId를 가진 엔터티들은 같은 Chunk에 저장됨
}

Shared Component를 Entity에 추가하는 Authoring 스크립트

using UnityEngine;
using Unity.Entities;

public class ExampleSharedComponentAuthoring : MonoBehaviour
{
    public int groupId;

    class Baker : Baker<ExampleSharedComponentAuthoring>
    {
        public override void Bake(ExampleSharedComponentAuthoring authoring)
        {
            var entity = GetEntity(TransformUsageFlags.Dynamic);
            // AddComponent가 아닌 AddSharedComponent()를 사용해야 함
            // 같은 groupId 값을 가진 엔터티들이 같은 Chunk에 배치됨
            AddSharedComponent(entity, new ExampleSharedComponent { GroupId = authoring.groupId });
        }
    }
}

Shared Component를 조회하는 시스템

using Unity.Entities;
using Unity.Burst;

// Shared Component는 Burst를 사용할 수 없음
// [BurstCompile] 사용 불가능
public partial struct ExampleSharedComponentSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        foreach (var (sharedComponent, entity) in SystemAPI.Query<ExampleSharedComponent>().WithEntityAccess())
        {
            UnityEngine.Debug.Log($"Entity {entity.Index} has GroupId {sharedComponent.GroupId}");
        }
    }
}

Shared Component는 일반적인 IComponentData처럼 RefRW<T>로 접근할 수 없음

대신 직접 값 복사 방식으로 접근해야 함

WithEntityAccess()를 사용하면 어떤 엔터티가 해당 Shared Component를 가지고 있는지 확인 가능

Shared Component 값 변경

• Shared Components는 값이 변경되면 새로운 Chunk가 생성되므로, 자주 변경되는 값에는 적합하지 않음.

public partial struct UpdateSharedComponentSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        foreach (var (entity, sharedComponent) in SystemAPI.Query<Entity, ExampleSharedComponent>())
        {
            if (sharedComponent.GroupId == 1)
            {
                state.EntityManager.SetSharedComponent(entity, new ExampleSharedComponent { GroupId = 2 });
            }
        }
    }
}

Shared Component를 활용하는 예제

• 렌더링 레이어 그룹화

// Layer 값이 같은 엔터티들을 같은 Chunk에 배치
// 같은 레이어의 엔터티들을 한 번에 처리하여 렌더링 최적화 가능
public struct RenderLayer : ISharedComponentData
{
    public int Layer;
}

• AI 행동 그룹화

// StateId 값이 같은 적(AI)들은 같은 Chunk에 배치됨
// 특정 AI 그룹을 한 번에 업데이트할 때 유용
public struct AIState : ISharedComponentData
{
    public int StateId;
}

• 팀 구분

using Unity.Entities;

// 팀 정보를 저장하는 Shared Component
public struct TeamComponent : ISharedComponentData
{
    public int TeamId; // 같은 TeamId를 가진 Entity들은 같은 Chunk에 저장됨
}

using UnityEngine;
using Unity.Entities;

// 팀을 설정하는 Authoring
public class TeamComponentAuthoring : MonoBehaviour
{
    public int teamId;

    class Baker : Baker<TeamComponentAuthoring>
    {
        public override void Bake(TeamComponentAuthoring authoring)
        {
            var entity = GetEntity(TransformUsageFlags.Dynamic);
            AddSharedComponent(entity, new TeamComponent { TeamId = authoring.teamId });
        }
    }
}

using Unity.Entities;
using Unity.Burst;
using UnityEngine;

// Burst 사용 불가능 (Shared Component는 Job System에서 직접 접근 불가)
public partial struct TeamSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        foreach (var (teamComponent, entity) in SystemAPI.Query<TeamComponent>().WithEntityAccess())
        {   
            // WithEntityAccess()를 사용하면 특정 엔터티가 어느 팀에 속해 있는지 확인 가능
            Debug.Log($"Entity {entity.Index} belongs to Team {teamComponent.TeamId}");
        }
    }
}

public partial struct TeamFilterSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        // 특정 팀 ID(예: TeamId == 1)를 가진 엔터티들만 가져오기
        var query = SystemAPI.QueryBuilder().WithAll<TeamComponent>().Build();
        state.EntityManager.SetSharedComponent(query, new TeamComponent { TeamId = 1 });

        foreach (var (teamComponent, entity) in SystemAPI.Query<TeamComponent>().WithEntityAccess())
        {
            if (teamComponent.TeamId == 1)
            {
                Debug.Log($"Entity {entity.Index} is in Team 1");
            }
        }
    }
}

정리

• 같은 값을 가진 Entity들을 같은 Chunk에 저장하여 메모리 접근 최적화 가능
• 자주 변경되지 않는 데이터에 적합 (예: 렌더링 그룹, AI 상태, 네트워크 동기화 등)
• 값이 변경될 경우 새로운 Chunk로 이동해야 하므로 변경이 잦다면 비효율적
• Burst 및 Job System을 사용할 수 없으므로 성능이 중요한 경우 Unmanaged Component 사용이 더 적합

“자주 변경되지 않는” 데이터를 기준으로 Entity를 그룹화할 때 Shared Component를 사용

(4) Cleanup components

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-cleanup.html

Cleanup Components는 일반 컴포넌트와 유사하지만, 특정 Entity가 삭제될 때 추가적인 정리 작업을 수행할 수 있도록 설계된 특수한 컴포넌트

이 컴포넌트는 Entity가 삭제될 때 모든 일반 컴포넌트를 제거하고, Entity 자체는 Cleanup Components가 모두 제거될 때까지 남아 있음

Entity가 삭제될 때 추가적인 정리 작업(예: 리소스 해제, 이벤트 처리 등)이 필요한 경우에 유용

• ICleanupComponentData : 각 Entity별로 독립적인 정리 작업을 수행하며, 엔티티가 삭제될 때 개별적으로 동작
• ICleanupSharedComponentData : 여러 Entity가 공유하는 데이터를 정리할 때 사용 (같은 리소스를 여러 Entity가 사용할 때, 리소스를 관리하고 정리하는 역할)

항목	설명
목적	엔티티가 삭제될 때 추가적인 정리 작업을 수행하기 위해 사용
동작 방식	엔티티가 삭제될 때 모든 일반 컴포넌트를 제거하고, Cleanup Components만 남깁니다. 엔티티는 Cleanup Components가 모두 제거될 때까지 존재합니다.
사용 사례	– 리소스 해제 – 이벤트 처리 – 네트워크 동기화 정리 – 엔티티 삭제 시 추가 로직 실행
Burst 지원	지원됨
Job System 사용 가능 여부	가능
GC 영향	GC 없음 (Unmanaged Components와 동일)
직렬화 필요 여부	필요 없음

Cleanup Components의 동작 원리

1. 엔티티 삭제 시 동작:
   • 엔티티가 삭제되면 모든 일반 컴포넌트가 제거
   • Cleanup Components는 남아 있으며, 엔티티는 여전히 존재
2. Cleanup Components 제거:
   • Cleanup Components가 모두 제거되면 엔티티가 완전히 삭제
3. 정리 작업 수행:
   • Cleanup Components를 사용하여 엔티티 삭제 시 필요한 추가 작업(예: 리소스 해제, 이벤트 처리 등)을 수행

Cleanup component 생명주기

// Cleanup 컴포넌트를 포함하는 엔티티를 생성합니다.
Entity e = EntityManager.CreateEntity(
    typeof(Translation), typeof(Rotation), typeof(ExampleCleanup));

// 엔티티를 삭제하려고 시도하지만, 엔티티가 Cleanup 컴포넌트를 가지고 있기 때문에 Unity는 실제로 엔티티를 삭제하지 않습니다.
// 대신, Unity는 Translation 및 Rotation 컴포넌트만 제거합니다.
EntityManager.DestroyEntity(e);

// 엔티티는 여전히 존재하므로, 엔티티를 정상적으로 사용할 수 있음을 보여줍니다.
EntityManager.AddComponent<Translation>(e);

// 엔티티에서 남아 있는 모든 컴포넌트를 제거합니다.
// 마지막 Cleanup 컴포넌트(ExampleCleanup)를 제거하면 엔티티가 자동으로 삭제됩니다.
EntityManager.RemoveComponent(e, new ComponentTypeSet(typeof(ExampleCleanup), typeof(Translation)));

// 엔티티가 더 이상 존재하지 않음을 보여줍니다. entityExists는 false입니다.
bool entityExists = EntityManager.Exists(e);

• Cleanup Components 생성 예시

using Unity.Entities;

// ICleanupComponentData를 상속받아 Cleanup Component를 정의
// 엔티티가 삭제될 때 추가적인 정리 작업을 수행하는 데 사용
public struct CleanupComponent : ICleanupComponentData
{
    public int ResourceId; // 정리할 리소스 ID
}

• Cleanup Components를 Entity에 추가하는 Authoring 스크립트

using UnityEngine;
using Unity.Entities;

public class CleanupComponentAuthoring : MonoBehaviour
{
    public int resourceId;

    class Baker : Baker<CleanupComponentAuthoring>
    {
        public override void Bake(CleanupComponentAuthoring authoring)
        {
            var entity = GetEntity(TransformUsageFlags.Dynamic);
            // AddComponent를 사용하여 Cleanup Component를 엔티티에 추가
            AddComponent(entity, new CleanupComponent { ResourceId = authoring.resourceId });
        }
    }
}

(5) Tag components

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/components-tag.html

Tag components는 특별한 컴포넌트 유형으로, 주로 Entity를 분류하거나 특정 상태를 나타내는 데 사용

Tag components는 데이터를 저장하지 않고, 그 자체로 “표식” 역할

이는 예를 들어 Entity가 특정 범주에 속하는지, 아니면 특정 조건을 만족하는지를 나타내는 데 유용

Tag components는 Entity의 동작에 대한 부가적인 의미를 제공하기 위해 사용

이 컴포넌트는 상태를 나타내는 단순한 “플래그”로, 해당 컴포넌트가 존재하는지 여부만 확인하면 됩니다.

예를 들어, Enemy나 Player와 같은 태그 컴포넌트를 사용하여 Entity가 어떤 종류의 객체인지를 표시할 수 있습니다.

using Unity.Entities;

// Tag Component 정의 (데이터를 가지지 않음)
public struct PlayerTag : IComponentData { }

public struct EnemyTag : IComponentData { }

using Unity.Entities;
using Unity.Transforms;
using UnityEngine;

public struct TagComponentSearchSystem : ISystem
{
    public void OnCreate(ref SystemState state) { }

    public void OnDestroy(ref SystemState state) { }

    public void OnUpdate(ref SystemState state)
    {
        // PlayerTag를 가진 엔티티를 찾아서 처리
        var playerQuery = SystemAPI.QueryBuilder().WithAll<PlayerTag, Translation>().Build();

        foreach (var (playerTag, translation) in playerQuery)
        {
            // 플레이어 엔티티가 있을 때 처리할 코드
            Debug.Log("Player found at position: " + translation.Value);
        }

        // EnemyTag를 가진 엔티티를 찾아서 처리
        var enemyQuery = SystemAPI.QueryBuilder().WithAll<EnemyTag, Translation>().Build();

        foreach (var (enemyTag, translation) in enemyQuery)
        {
            // 적 엔티티가 있을 때 처리할 코드
            Debug.Log("Enemy found at position: " + translation.Value);
        }
    }
}

using Unity.Entities;
using Unity.Transforms;

public class TagComponentSearchSystem : SystemBase
{
    protected override void OnUpdate()
    {
        // PlayerTag를 가진 엔티티를 찾아서 처리
        Entities.ForEach((in PlayerTag playerTag, in Translation translation) =>
        {
            // 플레이어 엔티티가 있을 때 처리할 코드
            UnityEngine.Debug.Log("Player found at position: " + translation.Value);
        }).Run();

        // EnemyTag를 가진 엔티티를 찾아서 처리
        Entities.ForEach((in EnemyTag enemyTag, in Translation translation) =>
        {
            // 적 엔티티가 있을 때 처리할 코드
            UnityEngine.Debug.Log("Enemy found at position: " + translation.Value);
        }).Run();
    }
}

The post ECS – Component concepts (1) appeared first on 어제와 내일의 나 그 사이의 이야기.

ECS – Entity concepts

https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/concepts-entities.html

1. Entity란?

• 프로그램 내에서 특정 개체(캐릭터, 이펙트, UI 요소 등)를 나타내는 단순한 ID 역할
• 기존 GameObject와 유사하지만, 코드나 데이터를 포함하지 않고 컴포넌트들의 조합을 통해 기능을 정의
• 개별 Entity는 World에 속하며, EntityManager가 이를 관리

2. EntityManager (Entity 관리)

EntityManager는 Entity를 생성, 삭제, 수정하는 다양한 메서드를 제공

Entity의 생성/삭제는 구조적 변경(Structural Change)을 일으켜 성능에 영향을 줄 수 있음

예시

• Entity 생성 & 삭제

using Unity.Entities;
using Unity.Collections;
using UnityEngine;

public class EntityManagerExample : MonoBehaviour
{
    private EntityManager entityManager;
    private Entity entity;

    private void Start()
    {
        // 현재 월드의 EntityManager 가져오기
        entityManager = World.DefaultGameObjectInjectionWorld.EntityManager;

        // 새로운 Entity 생성 (빈 상태)
        entity = entityManager.CreateEntity();
        Debug.Log($"Entity 생성됨: {entity.Index}");

        // Entity 삭제
        entityManager.DestroyEntity(entity);
        Debug.Log("Entity 삭제됨");
    }
}

• 컴포넌트 추가 & 제거

using Unity.Entities;
using UnityEngine;

// [IComponentData]를 상속받은 간단한 컴포넌트
public struct Health : IComponentData
{
    public int Value;
}

public class AddRemoveComponentExample : MonoBehaviour
{
    private EntityManager entityManager;
    private Entity entity;

    private void Start()
    {
        entityManager = World.DefaultGameObjectInjectionWorld.EntityManager;
        entity = entityManager.CreateEntity();

        // 컴포넌트 추가
        entityManager.AddComponentData(entity, new Health { Value = 100 });
        Debug.Log("Health 컴포넌트 추가됨");

        // 컴포넌트 제거
        entityManager.RemoveComponent<Health>(entity);
        Debug.Log("Health 컴포넌트 제거됨");
    }
}

• 컴포넌트 값 읽기(Get) & 수정(Set)

using Unity.Entities;
using UnityEngine;

public class GetSetComponentExample : MonoBehaviour
{
    private EntityManager entityManager;
    private Entity entity;

    private void Start()
    {
        entityManager = World.DefaultGameObjectInjectionWorld.EntityManager;
        entity = entityManager.CreateEntity();

        // Health 컴포넌트 추가 (초기 값 100)
        entityManager.AddComponentData(entity, new Health { Value = 100 });
        Debug.Log($"초기 체력: {entityManager.GetComponentData<Health>(entity).Value}");

        // Health 값 변경
        entityManager.SetComponentData(entity, new Health { Value = 50 });
        Debug.Log($"변경된 체력: {entityManager.GetComponentData<Health>(entity).Value}");
    }
}

3. Entity와 Archetype (아키타입)

• Entity 자체에는 타입이 없으며, Entity를 구성하는 컴포넌트 조합이 그 특성을 결정
• 같은 컴포넌트 조합을 가진 Entity들은 동일한 아키타입(Archetype)을 공유
• EntityManager는 현재 존재하는 Entity들의 고유한 컴포넌트 조합(Archetype)을 추적

Archetype을 활용하면 ECS 데이터 구조를 최적화하고 성능을 향상시킬 수 있음

4. Entity 관리 구조

• 모든 Entity는 World 내에서 관리됨
• EntityManager는 Entity의 생성, 삭제 및 컴포넌트 조작을 담당
• Entity는 컴포넌트들의 조합(Archetype)으로 정의됨

요약

• Entity는 단순한 ID 역할을 하며, 실제 기능은 컴포넌트(Component)를 통해 정의됨
• EntityManager를 사용하여 Entity를 생성(Create), 삭제(Destroy), 수정(Set, Get) 가능
• Entity는 컴포넌트 조합(Archetype) 단위로 그룹화되며, 동일한 Archetype을 가진 Entity 는 메모리에서 최적화됨
• Entity의 생성/삭제는 구조적 변경(Structural Change)을 일으켜 성능에 영향을 줄 수 있음

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

StatefulTriggerEventBufferAuthoring.cs

코드 설명

이 코드는 TriggerEvent를 StatefulTriggerEvent로 변환하여 Dynamic Buffer에 저장하는 역할을 합니다.

특정 엔티티에 StatefulTriggerEventBufferAuthoring 컴포넌트를 추가하면 Trigger 이벤트의 상태(Enter, Stay, Exit)를 추적할 수 있습니다.

using Unity.Assertions;
using Unity.Entities;
using UnityEngine;

namespace Unity.Physics.Stateful
{
    // StatefulTriggerEventBufferAuthoring 컴포넌트
    // GameObject에 추가하면 해당 오브젝트는 ECS Entity로 변환될 때 StatefulTriggerEvent 버퍼를 갖게 됨.
    public class StatefulTriggerEventBufferAuthoring : MonoBehaviour
    {
        // Baker 클래스: GameObject를 ECS Entity로 변환하는 역할
        class Baker : Baker<StatefulTriggerEventBufferAuthoring>
        {
            public override void Bake(StatefulTriggerEventBufferAuthoring authoring)
            {
                // 현재 GameObject를 ECS Entity로 변환 (Transform 사용 방식: 동적)
                var entity = GetEntity(TransformUsageFlags.Dynamic);

                // StatefulTriggerEvent를 저장할 Dynamic Buffer 추가
                AddBuffer<StatefulTriggerEvent>(entity);
            }
        }
    }

    // StatefulTriggerEvent 구조체
    // Trigger 이벤트를 저장할 수 있는 데이터 구조 (IStatefulSimulationEvent 인터페이스 구현)
    public struct StatefulTriggerEvent : IBufferElementData, IStatefulSimulationEvent<StatefulTriggerEvent>
    {
        // 트리거 이벤트에 연관된 두 개의 엔티티
        public Entity EntityA { get; set; }
        public Entity EntityB { get; set; }

        // 물리 본체(Body)의 인덱스
        public int BodyIndexA { get; set; }
        public int BodyIndexB { get; set; }

        // 충돌한 Collider의 키
        public ColliderKey ColliderKeyA { get; set; }
        public ColliderKey ColliderKeyB { get; set; }

        // 현재 이벤트 상태 (Enter, Stay, Exit)
        public StatefulEventState State { get; set; }

        // 생성자: 기존의 TriggerEvent 데이터를 StatefulTriggerEvent로 변환
        public StatefulTriggerEvent(TriggerEvent triggerEvent)
        {
            EntityA = triggerEvent.EntityA;
            EntityB = triggerEvent.EntityB;
            BodyIndexA = triggerEvent.BodyIndexA;
            BodyIndexB = triggerEvent.BodyIndexB;
            ColliderKeyA = triggerEvent.ColliderKeyA;
            ColliderKeyB = triggerEvent.ColliderKeyB;
            State = default; // 초기 상태 설정 (Enter, Stay, Exit 없음)
        }

        // 특정 엔티티에 대해, 이벤트에 연관된 '다른 엔티티'를 반환하는 메서드
        public Entity GetOtherEntity(Entity entity)
        {
            // 전달된 엔티티가 EntityA 또는 EntityB인지 검증 (디버그용)
            Assert.IsTrue((entity == EntityA) || (entity == EntityB));

            // EntityA가 입력되면 EntityB를 반환하고, 반대로 EntityB가 입력되면 EntityA 반환
            return (entity == EntityA) ? EntityB : EntityA;
        }

        // 이벤트 비교를 위한 메서드 (정렬, 검색 등에 사용 가능)
        public int CompareTo(StatefulTriggerEvent other)
        {
            return ISimulationEventUtilities.CompareEvents(this, other);
        }
    }

    // StatefulTriggerEvent를 제외하는 컴포넌트
    // 이 컴포넌트가 추가된 엔티티는 StatefulTriggerEventBufferSystem에서 이벤트를 수집하지 않음
    public struct StatefulTriggerEventExclude : IComponentData { }
}

Unity의 GameObject를 ECS(Entity-Component-System) 엔티티로 변환하는 역할

Baker 클래스에서 StatefulTriggerEvent를 저장할 Dynamic Buffer를 추가함

이를 통해 Trigger 이벤트를 저장하는 버퍼를 ECS 엔티티에 추가 가능

해당 엔티티는 StatefulTriggerEvent 버퍼를 가지게 됨.

• TriggerEvent 정보를 저장하는 Stateful 버전
• StatefulEventState를 추가하여 Trigger 이벤트의 상태(Enter, Stay, Exit)를 추적
• 기존 TriggerEvent는 한 프레임 동안만 존재 → 이를 StatefulTriggerEvent로 변환하여 지속적인 상태 추적 가능

• 특정 엔티티가 트리거 이벤트에 포함된 다른 엔티티를 가져옴
• EntityA를 전달하면 EntityB를 반환하고, 반대로 EntityB를 전달하면 EntityA를 반환

StatefulTriggerEventBufferSystem이 특정 엔티티의 트리거 이벤트를 저장하지 않도록 제외 처리 (쿼리에서 제외)

StatefulTriggerEventBufferSystem.cs

코드 설명

1. 트리거 이벤트를 StatefulTriggerEvent로 변환하여 Dynamic Buffer에 저장
2. Enter, Stay, Exit 이벤트를 추적하여 충돌 지속 여부를 확인 가능
3. OnCreate()
   • StatefulSimulationEventBuffers를 생성하고 이벤트 저장을 위한 버퍼를 할당
   • StatefulTriggerEvent를 포함하고 StatefulTriggerEventExclude가 없는 엔티티를 찾는 쿼리 설정
4. OnUpdate()
   • 기존 이벤트 버퍼 초기화
   • TriggerEvent 데이터를 수집하고, StatefulTriggerEvent로 변환하여 저장
5. OnDestroy()
   • 사용했던 메모리를 해제하여 최적화

using Unity.Entities;
using Unity.Jobs;
using Unity.Physics.Systems;
using Unity.Collections;
using Unity.Burst;

namespace Unity.Physics.Stateful
{
    // 이 시스템은 TriggerEvent의 스트림을 StatefulTriggerEvent로 변환하여 Dynamic Buffer에 저장할 수 있도록 합니다.
    // 이를 통해 충돌 상태(Enter, Stay, Exit)를 추적할 수 있습니다.
    [UpdateInGroup(typeof(PhysicsSystemGroup))] // PhysicsSystemGroup 내에서 실행됨
    [UpdateAfter(typeof(PhysicsSimulationGroup))] // PhysicsSimulationGroup 이후에 실행됨
    public partial struct StatefulTriggerEventBufferSystem : ISystem
    {
        // 현재 및 이전 프레임의 Trigger 이벤트를 저장하는 버퍼
        private StatefulSimulationEventBuffers<StatefulTriggerEvent> m_StateFulEventBuffers;
        // 이벤트 처리에 필요한 컴포넌트 조회 핸들
        private ComponentHandles m_ComponentHandles;
        // 트리거 이벤트를 처리할 엔티티 쿼리
        private EntityQuery m_TriggerEventQuery;

        // 이벤트를 저장할 컴포넌트 핸들 구조체
        struct ComponentHandles
        {
            // 특정 이벤트를 제외할 엔티티 조회
            public ComponentLookup<StatefulTriggerEventExclude> EventExcludes;
            // StatefulTriggerEvent를 저장할 Dynamic Buffer 조회
            public BufferLookup<StatefulTriggerEvent> EventBuffers;

            // 컴포넌트 핸들 초기화
            public ComponentHandles(ref SystemState systemState)
            {
                EventExcludes = systemState.GetComponentLookup<StatefulTriggerEventExclude>(true);
                EventBuffers = systemState.GetBufferLookup<StatefulTriggerEvent>();
            }

            // 최신 상태로 업데이트
            public void Update(ref SystemState systemState)
            {
                EventExcludes.Update(ref systemState);
                EventBuffers.Update(ref systemState);
            }
        }

        [BurstCompile]
        public void OnCreate(ref SystemState state)
        {
            // 트리거 이벤트를 처리할 엔티티 쿼리 생성
            // (StatefulTriggerEvent가 있으며, StatefulTriggerEventExclude가 없는 엔티티)
            EntityQueryBuilder builder = new EntityQueryBuilder(Allocator.Temp)
                .WithAllRW<StatefulTriggerEvent>() // StatefulTriggerEvent를 읽고 쓸 수 있는 엔티티 선택
                .WithNone<StatefulTriggerEventExclude>(); // StatefulTriggerEventExclude가 없는 엔티티만 선택

            // Stateful 이벤트 버퍼를 생성하고 할당
            m_StateFulEventBuffers = new StatefulSimulationEventBuffers<StatefulTriggerEvent>();
            m_StateFulEventBuffers.AllocateBuffers();

            // 쿼리 설정 및 시스템 업데이트 필요성 명시
            m_TriggerEventQuery = state.GetEntityQuery(builder);
            state.RequireForUpdate(m_TriggerEventQuery);

            // 컴포넌트 핸들 초기화
            m_ComponentHandles = new ComponentHandles(ref state);
        }

        [BurstCompile]
        public void OnDestroy(ref SystemState state)
        {
            // Stateful 이벤트 버퍼 해제
            m_StateFulEventBuffers.Dispose();
        }

        // 트리거 이벤트 버퍼를 초기화하는 Job
        [BurstCompile]
        public partial struct ClearTriggerEventDynamicBufferJob : IJobEntity
        {
            // 이벤트 버퍼 초기화
            public void Execute(ref DynamicBuffer<StatefulTriggerEvent> eventBuffer) => eventBuffer.Clear();
        }

        [BurstCompile]
        public void OnUpdate(ref SystemState state)
        {
            // 최신 상태로 컴포넌트 핸들 업데이트
            m_ComponentHandles.Update(ref state);

            // 기존 트리거 이벤트 버퍼 초기화 (병렬 실행)
            state.Dependency = new ClearTriggerEventDynamicBufferJob() .ScheduleParallel(m_TriggerEventQuery, state.Dependency);

            // 이전 프레임과 현재 프레임의 이벤트 버퍼를 교체
            m_StateFulEventBuffers.SwapBuffers();

            var currentEvents = m_StateFulEventBuffers.Current; // 현재 프레임의 이벤트
            var previousEvents = m_StateFulEventBuffers.Previous; // 이전 프레임의 이벤트

            // 새로운 Trigger 이벤트를 수집하는 Job 실행
            state.Dependency = new StatefulEventCollectionJobs.CollectTriggerEvents
            {
                TriggerEvents = currentEvents
            }.Schedule(SystemAPI.GetSingleton<SimulationSingleton>(), state.Dependency);

            // 트리거 이벤트를 StatefulTriggerEvent로 변환하여 Dynamic Buffer에 저장하는 Job 실행
            state.Dependency = new StatefulEventCollectionJobs.ConvertEventStreamToDynamicBufferJob<StatefulTriggerEvent, StatefulTriggerEventExclude>
            {
                CurrentEvents = currentEvents, // 현재 프레임의 이벤트
                PreviousEvents = previousEvents, // 이전 프레임의 이벤트
                EventLookup = m_ComponentHandles.EventBuffers, // 이벤트 버퍼 조회

                UseExcludeComponent = true, // 제외할 컴포넌트(StatefulTriggerEventExclude) 사용 여부
                EventExcludeLookup = m_ComponentHandles.EventExcludes // 제외할 이벤트 조회
            }.Schedule(state.Dependency);
        }
    }
}

ComponentHandles: StatefulTriggerEventExclude 및 StatefulTriggerEvent 버퍼를 조회하는 핸들을 보유하는 구조체

• EventExcludes: 트리거 이벤트가 수집되지 않도록 제외할 엔티티를 조회합니다.
• EventBuffers: StatefulTriggerEvent를 저장하는 Dynamic Buffer를 조회합니다.

트리거 이벤트를 처리할 쿼리 생성:

• StatefulTriggerEvent 컴포넌트를 읽고 쓸 수 있는 엔티티를 선택하고,
• StatefulTriggerEventExclude가 없는 엔티티만 선택하여 트리거 이벤트를 수집합니다.

m_StateFulEventBuffers를 초기화하고, 버퍼를 할당합니다.

m_TriggerEventQuery 쿼리를 설정하여 이 쿼리가 시스템 업데이트에 필요함을 명시합니다.

컴포넌트 핸들 업데이트: m_ComponentHandles를 최신 상태로 업데이트합니다.

버퍼 초기화: ClearTriggerEventDynamicBufferJob을 병렬로 실행하여 이전 트리거 이벤트 버퍼를 초기화합니다.

이벤트 버퍼 교체: SwapBuffers를 사용하여 현재 프레임과 이전 프레임의 버퍼를 교체합니다.

Trigger 이벤트 수집: StatefulEventCollectionJobs.CollectTriggerEvents를 통해 새로운 트리거 이벤트를 수집합니다.

StatefulTriggerEvent 변환: 수집한 트리거 이벤트를 StatefulTriggerEvent로 변환하고 Dynamic Buffer에 저장합니다.

IStatefulSimulationEvent.cs

충돌 상태 변화에 대한 추적을 가능하게 하여, 물체 간 상호작용의 상태를 세분화하고, 이를 이벤트 시스템을 통해 관리

using Unity.Entities;

namespace Unity.Physics.Stateful
{
    // 이벤트 상태를 설명합니다.
    // 이벤트 상태는 다음과 같이 설정됩니다:
    //    0) Undefined (정의되지 않음): 상태가 불명확하거나 필요하지 않을 때
    //    1) Enter (진입): 두 물체가 현재 프레임에서 상호작용하고 있지만, 이전 프레임에서는 상호작용하지 않았을 때
    //    2) Stay (유지): 두 물체가 현재 프레임에서 상호작용 중이고, 이전 프레임에서도 상호작용했을 때
    //    3) Exit (탈출): 두 물체가 현재 프레임에서 상호작용하지 않지만, 이전 프레임에서는 상호작용했을 때
    public enum StatefulEventState : byte
    {
        Undefined,  // 상태가 정의되지 않음
        Enter,      // 두 물체가 현재 프레임에서 상호작용 중이지만 이전 프레임에서는 상호작용하지 않았을 때
        Stay,       // 두 물체가 현재 프레임과 이전 프레임에서 모두 상호작용하고 있을 때
        Exit        // 두 물체가 현재 프레임에서 상호작용하지 않지만 이전 프레임에서는 상호작용했을 때
    }

    // 추가적인 StatefulEventState를 포함하여 ISimulationEvent를 확장합니다.
    public interface IStatefulSimulationEvent<T> : IBufferElementData, ISimulationEvent<T>
    {
        public StatefulEventState State { get; set; } // 이벤트 상태
    }
}

StatefulJobs.cs

Unity에서 물리 시뮬레이션의 충돌 이벤트를 상태 기반으로 추적하고, 이를 Dynamic Buffer에 저장하는 시스템을 구현하는 데 사용됩니다.

여기서는 StatefulEventCollectionJobs라는 이름의 클래스가 주요한 역할을 합니다.

여러 개의 Job을 정의하여 충돌 이벤트를 수집하고, 이를 상태 기반 이벤트로 변환하여 저장합니다.

using Unity.Burst;
using Unity.Collections;
using Unity.Entities;
using Unity.Jobs;

namespace Unity.Physics.Stateful
{
    public static class StatefulEventCollectionJobs
    {
        // Trigger 이벤트를 StatefulTriggerEvent로 변환하여 NativeList에 추가하는 Job
        [BurstCompile]
        public struct CollectTriggerEvents : ITriggerEventsJob
        {
            // 저장할 Trigger 이벤트를 담을 리스트
            public NativeList<StatefulTriggerEvent> TriggerEvents;

            // TriggerEvent를 StatefulTriggerEvent로 변환하여 리스트에 추가
            public void Execute(TriggerEvent triggerEvent) => TriggerEvents.Add(new StatefulTriggerEvent(triggerEvent));
        }

        // Collision 이벤트를 StatefulCollisionEvent로 변환하여 NativeList에 추가하는 Job
        [BurstCompile]
        public struct CollectCollisionEvents : ICollisionEventsJob
        {
            // 저장할 Collision 이벤트를 담을 리스트
            public NativeList<StatefulCollisionEvent> CollisionEvents;

            // CollisionEvent를 StatefulCollisionEvent로 변환하여 리스트에 추가
            public void Execute(CollisionEvent collisionEvent) => CollisionEvents.Add(new StatefulCollisionEvent(collisionEvent));
        }

        // Collision 이벤트와 함께 세부 정보를 계산하여 StatefulCollisionEvent로 변환하고 NativeList에 추가하는 Job
        [BurstCompile]
        public struct CollectCollisionEventsWithDetails : ICollisionEventsJob
        {
            // 저장할 Collision 이벤트를 담을 리스트
            public NativeList<StatefulCollisionEvent> CollisionEvents;

            // 물리 월드와 세부 사항 계산에 사용할 컴포넌트 조회
            [ReadOnly] public PhysicsWorld PhysicsWorld;
            [ReadOnly] public ComponentLookup<StatefulCollisionEventDetails> EventDetails;

            // 세부 사항 계산을 강제할지 여부
            public bool ForceCalculateDetails;

            // CollisionEvent를 처리하고 세부 사항을 계산하여 StatefulCollisionEvent로 변환
            public void Execute(CollisionEvent collisionEvent)
            {
                var statefulCollisionEvent = new StatefulCollisionEvent(collisionEvent);

                // 세부 사항 계산 여부 결정
                bool calculateDetails = ForceCalculateDetails;
                if (!calculateDetails && EventDetails.HasComponent(collisionEvent.EntityA))
                {
                    calculateDetails = EventDetails[collisionEvent.EntityA].CalculateDetails;
                }
                if (!calculateDetails && EventDetails.HasComponent(collisionEvent.EntityB))
                {
                    calculateDetails = EventDetails[collisionEvent.EntityB].CalculateDetails;
                }

                // 세부 사항을 계산하고 상태에 저장
                if (calculateDetails)
                {
                    var details = collisionEvent.CalculateDetails(ref PhysicsWorld);
                    statefulCollisionEvent.CollisionDetails = new StatefulCollisionEvent.Details(
                        details.EstimatedContactPointPositions.Length,
                        details.EstimatedImpulse,
                        details.AverageContactPointPosition);
                }

                // 계산된 CollisionEvent를 리스트에 추가
                CollisionEvents.Add(statefulCollisionEvent);
            }
        }

        // 이벤트 스트림을 Dynamic Buffer로 변환하는 Job
        // T: StatefulSimulationEvent 타입
        // C: 제외할 컴포넌트 타입
        [BurstCompile]
        public struct ConvertEventStreamToDynamicBufferJob<T, C> : IJob
            where T : unmanaged, IBufferElementData, IStatefulSimulationEvent<T>  // T는 IStatefulSimulationEvent를 구현해야 함
            where C : unmanaged, IComponentData  // C는 IComponentData를 구현해야 함
        {
            // 이전과 현재의 이벤트 리스트
            public NativeList<T> PreviousEvents;
            public NativeList<T> CurrentEvents;

            // 이벤트를 저장할 Dynamic Buffer 조회
            public BufferLookup<T> EventLookup;

            // 제외할 컴포넌트를 사용할지 여부
            public bool UseExcludeComponent;

            // 제외할 컴포넌트를 조회하는 컴포넌트 핸들
            [ReadOnly] public ComponentLookup<C> EventExcludeLookup;

            // 이벤트를 변환하고 Dynamic Buffer에 추가하는 작업
            public void Execute()
            {
                // 이벤트를 저장할 임시 리스트
                var statefulEvents = new NativeList<T>(CurrentEvents.Length, Allocator.Temp);

                // 이전 및 현재 이벤트에서 상태를 기반으로 상태 변경된 이벤트를 가져옴
                StatefulSimulationEventBuffers<T>.GetStatefulEvents(PreviousEvents, CurrentEvents, statefulEvents);

                // 상태가 변경된 이벤트를 처리
                for (int i = 0; i < statefulEvents.Length; i++)
                {
                    var statefulEvent = statefulEvents[i];

                    // 이벤트가 추가될 엔티티 A와 B가 동적으로 버퍼를 가지고 있는지 확인
                    var addToEntityA = EventLookup.HasBuffer(statefulEvent.EntityA) &&
                        (!UseExcludeComponent || !EventExcludeLookup.HasComponent(statefulEvent.EntityA));
                    var addToEntityB = EventLookup.HasBuffer(statefulEvent.EntityB) &&
                        (!UseExcludeComponent || !EventExcludeLookup.HasComponent(statefulEvent.EntityA));

                    // 엔티티 A와 B에 이벤트를 추가
                    if (addToEntityA)
                    {
                        EventLookup[statefulEvent.EntityA].Add(statefulEvent);
                    }

                    if (addToEntityB)
                    {
                        EventLookup[statefulEvent.EntityB].Add(statefulEvent);
                    }
                }
            }
        }
    }
}

TriggerEvent 객체를 받아 StatefulTriggerEvent로 변환한 후 TriggerEvents 리스트에 추가하는 작업을 수행합니다.

TriggerEvent: 두 개체 간의 충돌 여부를 나타내는 기본적인 이벤트입니다.

StatefulTriggerEvent: 이 구조체는 충돌 상태를 추적할 수 있도록 StatefulEventState (Enter, Stay, Exit, Undefined) 상태를 추가하여 TriggerEvent를 확장한 것입니다.

Execute 메서드는 주어진 TriggerEvent를 StatefulTriggerEvent로 변환하여 TriggerEvents 리스트에 추가합니다.

CollisionEvent를 받아 StatefulCollisionEvent로 변환한 후 CollisionEvents 리스트에 추가합니다.

CollisionEvent: 두 개체 간의 충돌을 나타내는 이벤트입니다.

StatefulCollisionEvent: 충돌 상태를 추적하기 위해 StatefulEventState를 추가한 CollisionEvent입니다.

Execute 메서드는 CollisionEvent를 StatefulCollisionEvent로 변환하여 CollisionEvents 리스트에 추가합니다.

충돌 이벤트와 함께 세부 정보를 계산하고 이를 StatefulCollisionEvent로 변환하여 CollisionEvents 리스트에 추가합니다.

ForceCalculateDetails: 세부 사항을 강제로 계산할지 여부를 나타내는 플래그입니다.

EventDetails: 각 개체에 대한 세부 사항을 계산할지 여부를 결정하는 StatefulCollisionEventDetails 컴포넌트의 조회입니다.

• Execute 메서드는 CollisionEvent를 StatefulCollisionEvent로 변환한 후, 해당 이벤트에 대해 세부 사항을 계산합니다.
• CalculateDetails 메서드는 충돌 세부 사항을 계산하고, 그 결과를 StatefulCollisionEvent의 CollisionDetails에 저장합니다.
• 세부 사항을 계산할 필요가 없다면 기본적으로 세부 사항을 계산하지 않습니다.

세부 사항 계산

Estimated Contact Point Positions (예상 접촉 지점 위치):

• 충돌이 발생했을 때 예상되는 접촉 지점의 위치들
• 이는 충돌이 발생한 표면에서 실제로 물리적으로 접촉한 지점들
• 예를 들어, 두 물체가 충돌하면서 여러 접촉 지점이 생길 수 있다.

Estimated Impulse (예상 충격량):

• 두 객체 간의 충돌로 발생하는 충격량입니다. 충돌 후 물체가 받을 힘을 측정하는 값
• 충돌 전후의 물리적 특성(속도 변화, 질량 등)을 바탕으로 계산
• 이는 두 객체 간의 충돌로 인해 변화하는 운동량

Average Contact Point Position (평균 접촉 지점 위치):

• 여러 접촉 지점이 있다면, 그 중에서 평균적인 접촉 지점 위치를 계산한 것
• 이는 충돌이 발생한 여러 지점들 중에서, 전체적인 충격을 대표할 수 있는 중간 지점을 제공하는 역할

상태 기반 이벤트 스트림을 Dynamic Buffer로 변환하는 작업을 수행합니다.

EventLookup: StatefulTriggerEvent와 StatefulCollisionEvent와 같은 상태 기반 이벤트를 저장할 Dynamic Buffer의 조회입니다.

UseExcludeComponent: 특정 컴포넌트를 제외할지 여부를 결정하는 플래그입니다.

• PreviousEvents와 CurrentEvents에서 상태 기반 이벤트를 비교하여 상태 변화가 있는 이벤트를 가져옵니다.
• 변환된 이벤트를 EventLookup에 해당하는 엔티티의 Dynamic Buffer에 추가합니다.
• EventExcludeLookup를 사용하여 제외할 컴포넌트가 있으면 해당 엔티티에 대한 이벤트 추가를 방지합니다.

StatefulSimulationEventBuffers.cs

StatefulSimulationEventBuffers라는 구조체로, 상태를 추적할 수 있는 이벤트 버퍼를 관리합니다.

정의된 함수들은 물리 시뮬레이션 이벤트의 상태를 추적하고 이를 처리하는데 필요한 버퍼 관리 및 이벤트 비교 기능을 제공합니다. (주로 충돌이나 상호작용 이벤트를 처리 )

각 이벤트가 이전 프레임과 비교하여 어떤 상태(Enter, Stay, Exit)에 해당하는지 판단하고, 이를 기반으로 상태를 변경하여 결과를 반환합니다.

using Unity.Collections;

namespace Unity.Physics.Stateful
{
    // StatefulSimulationEventBuffers는 이벤트의 상태를 추적하는 두 버퍼를 관리하는 구조체입니다.
    // 이 구조체는 지난 프레임과 현재 프레임의 이벤트를 저장하며, 충돌 이벤트에 대한 상태 변경을 추적합니다.
    public struct StatefulSimulationEventBuffers<T> where T : unmanaged, IStatefulSimulationEvent<T>
    {
        // 이전 프레임의 이벤트를 저장하는 리스트
        public NativeList<T> Previous;
        // 현재 프레임의 이벤트를 저장하는 리스트
        public NativeList<T> Current;

        // 이벤트 버퍼 할당
        public void AllocateBuffers()
        {
            // 이전 및 현재 프레임 이벤트를 저장할 버퍼를 할당
            Previous = new NativeList<T>(Allocator.Persistent);
            Current = new NativeList<T>(Allocator.Persistent);
        }

        // 이벤트 버퍼를 해제
        public void Dispose()
        {
            // 버퍼가 생성되었으면 해제
            if (Previous.IsCreated) Previous.Dispose();
            if (Current.IsCreated) Current.Dispose();
        }

        // 이전 프레임과 현재 프레임의 버퍼를 교환
        public void SwapBuffers()
        {
            // 이전과 현재 이벤트 버퍼를 교환
            var tmp = Previous;
            Previous = Current;
            Current = tmp;
            // 현재 버퍼를 비움 (새로운 이벤트로 덮어쓰기 위해)
            Current.Clear();
        }

        /// <summary>
        /// 이전 프레임과 현재 프레임의 이벤트를 결합하여 하나의 정렬된 리스트로 반환합니다.
        /// 반드시 SortBuffers를 먼저 호출하여 정렬된 상태로 만들어야 합니다.
        /// </summary>
        /// <param name="statefulEvents">결합된 이벤트 리스트</param>
        /// <param name="sortCurrent">현재 이벤트 리스트를 정렬해야 하는지 여부</param>
        public void GetStatefulEvents(NativeList<T> statefulEvents, bool sortCurrent = true) =>
            GetStatefulEvents(Previous, Current, statefulEvents, sortCurrent);

        /// <summary>
        /// 두 개의 정렬된 이벤트 버퍼를 결합하여 하나의 리스트로 반환합니다.
        /// 각 이벤트에는 적절한 StatefulEventState가 설정됩니다.
        /// </summary>
        /// <param name="previousEvents">이전 프레임의 이벤트 버퍼</param>
        /// <param name="currentEvents">현재 프레임의 이벤트 버퍼</param>
        /// <param name="statefulEvents">결합된 이벤트 리스트</param>
        /// <param name="sortCurrent">현재 이벤트 리스트를 정렬해야 하는지 여부</param>
        public static void GetStatefulEvents(NativeList<T> previousEvents, NativeList<T> currentEvents, NativeList<T> statefulEvents, bool sortCurrent = true)
        {
            // 현재 이벤트 리스트가 정렬되지 않았다면 정렬
            if (sortCurrent) currentEvents.Sort();

            // 새로운 리스트를 비움
            statefulEvents.Clear();

            int c = 0; // 현재 이벤트 리스트의 인덱스
            int p = 0; // 이전 이벤트 리스트의 인덱스

            // 현재 이벤트와 이전 이벤트를 비교하며 상태 변경
            while (c < currentEvents.Length && p < previousEvents.Length)
            {
                // 두 이벤트를 비교
                int r = previousEvents[p].CompareTo(currentEvents[c]);
                if (r == 0)
                {
                    // 현재 이벤트가 이전 이벤트와 동일하다면 'Stay' 상태로 추가
                    var currentEvent = currentEvents[c];
                    currentEvent.State = StatefulEventState.Stay;
                    statefulEvents.Add(currentEvent);
                    c++;
                    p++;
                }
                else if (r < 0)
                {
                    // 이전 이벤트가 현재 이벤트보다 먼저 왔다면 'Exit' 상태로 추가
                    var previousEvent = previousEvents[p];
                    previousEvent.State = StatefulEventState.Exit;
                    statefulEvents.Add(previousEvent);
                    p++;
                }
                else //(r > 0)
                {
                    // 현재 이벤트가 이전 이벤트보다 먼저 왔다면 'Enter' 상태로 추가
                    var currentEvent = currentEvents[c];
                    currentEvent.State = StatefulEventState.Enter;
                    statefulEvents.Add(currentEvent);
                    c++;
                }
            }

            // 현재 이벤트가 다 처리되었고, 이전 이벤트가 남았다면 'Exit' 상태로 추가
            if (c == currentEvents.Length)
            {
                while (p < previousEvents.Length)
                {
                    var previousEvent = previousEvents[p];
                    previousEvent.State = StatefulEventState.Exit;
                    statefulEvents.Add(previousEvent);
                    p++;
                }
            }
            // 이전 이벤트가 다 처리되었고, 현재 이벤트가 남았다면 'Enter' 상태로 추가
            else if (p == previousEvents.Length)
            {
                while (c < currentEvents.Length)
                {
                    var currentEvent = currentEvents[c];
                    currentEvent.State = StatefulEventState.Enter;
                    statefulEvents.Add(currentEvent);
                    c++;
                }
            }
        }
    }
}

AllocateBuffers()

Previous와 Current 두 개의 이벤트 버퍼를 할당합니다.

이 함수는 NativeList<T> 타입의 Previous와 Current 버퍼를 할당합니다.

이 버퍼들은 각 프레임의 이벤트들을 저장하는 데 사용됩니다.

Allocator.Persistent는 이 메모리가 여러 프레임에 걸쳐 유지될 수 있도록 해줍니다.

Dispose()

할당된 Previous와 Current 이벤트 버퍼를 해제합니다.

Dispose()는 AllocateBuffers()에서 할당한 Previous와 Current 버퍼를 메모리에서 해제하는 역할을 합니다.

IsCreated를 통해 버퍼가 생성되었는지 확인한 후, 생성된 버퍼에 대해 Dispose()를 호출하여 메모리 관리를 수행합니다.

SwapBuffers()

Previous와 Current 버퍼를 교환하고, Current 버퍼를 비웁니다.

이 함수는 이전 프레임의 이벤트(Previous)와 현재 프레임의 이벤트(Current)를 교환합니다.

그 후, Current 버퍼를 비워서 다음 프레임의 데이터를 받을 준비를 합니다.

교환하는 이유는 이벤트가 프레임 간에 이동하면서 상태를 추적하고 업데이트하는 방식 때문입니다.

Previous와 Current 이벤트 리스트를 결합하여 상태별 이벤트 리스트를 반환합니다.

이 함수는 두 개의 이벤트 리스트인 Previous와 Current를 결합하는 작업을 수행하는 GetStatefulEvents()의 래퍼(wrapper) 함수입니다.

sortCurrent 파라미터를 사용하여 Current 리스트가 정렬되어야 하는지를 결정합니다.

기본적으로 sortCurrent는 true로 설정되어 있어 Current 리스트가 정렬됩니다.

두 개의 정렬된 이벤트 리스트를 결합하여 하나의 상태별 이벤트 리스트로 반환합니다.

주어진 두 개의 이벤트 리스트(previousEvents와 currentEvents)를 비교하고, 각 이벤트에 적절한 StatefulEventState를 설정합니다.

각 상태는 Enter, Stay, Exit으로 나뉩니다.

• Enter: 현재 프레임에 새롭게 등장한 이벤트.
• Stay: 이전과 현재 프레임 모두에서 존재하는 이벤트.
• Exit: 이전 프레임에는 존재했지만 현재 프레임에는 없는 이벤트.

이 함수는 각 이벤트를 비교하여 상태를 설정하고, statefulEvents에 추가합니다.

StatefulCollisionEventBufferAuthoring.cs

using System.Runtime.InteropServices;
using Unity.Assertions;
using Unity.Entities;
using Unity.Mathematics;
using UnityEngine;

namespace Unity.Physics.Stateful
{
    // StatefulCollisionEventBufferAuthoring은 Unity의 MonoBehaviour로, 
    // 물리 충돌 이벤트가 포함된 버퍼를 정의하고, 해당 엔티티에 대해 세부 사항을 계산할지 여부를 결정합니다.
    public class StatefulCollisionEventBufferAuthoring : MonoBehaviour
    {
        [Tooltip("선택하면 이 엔티티의 충돌 이벤트 동적 버퍼에서 세부 정보가 계산됩니다")]
        public bool CalculateDetails = false; // 충돌 이벤트에 세부 사항을 계산할지 여부를 결정하는 변수

        // Baker 클래스는 Authoring 컴포넌트에서 데이터를 추출하고 Entity로 변환하는 역할을 합니다.
        class StatefulCollisionEventBufferBaker : Baker<StatefulCollisionEventBufferAuthoring>
        {
            public override void Bake(StatefulCollisionEventBufferAuthoring authoring)
            {
                // TransformUsageFlags.Dynamic 플래그를 사용하여 해당 엔티티를 생성합니다.
                var entity = GetEntity(TransformUsageFlags.Dynamic);

                // CalculateDetails가 true일 경우, StatefulCollisionEventDetails를 엔티티에 추가합니다.
                if (authoring.CalculateDetails)
                {
                    var dynamicBufferTag = new StatefulCollisionEventDetails
                    {
                        CalculateDetails = authoring.CalculateDetails
                    };

                    AddComponent(entity, dynamicBufferTag); // StatefulCollisionEventDetails 컴포넌트 추가
                }

                // 충돌 이벤트를 저장할 버퍼 추가
                AddBuffer<StatefulCollisionEvent>(entity);
            }
        }
    }

    // StatefulCollisionEventDetails 컴포넌트는 엔티티가 세부 사항을 계산할지를 설정하는 플래그입니다.
    public struct StatefulCollisionEventDetails : IComponentData
    {
        public bool CalculateDetails; // 세부 사항을 계산할지 여부를 설정하는 변수
    }

    // StatefulCollisionEvent는 DynamicBuffer에 저장할 수 있는 충돌 이벤트 구조체입니다.
    public struct StatefulCollisionEvent : IBufferElementData, IStatefulSimulationEvent<StatefulCollisionEvent>
    {
        public Entity EntityA { get; set; } // 첫 번째 엔티티
        public Entity EntityB { get; set; } // 두 번째 엔티티
        public int BodyIndexA { get; set; } // 첫 번째 엔티티의 바디 인덱스
        public int BodyIndexB { get; set; } // 두 번째 엔티티의 바디 인덱스
        public ColliderKey ColliderKeyA { get; set; } // 첫 번째 엔티티의 충돌체 키
        public ColliderKey ColliderKeyB { get; set; } // 두 번째 엔티티의 충돌체 키
        public StatefulEventState State { get; set; } // 이벤트 상태 (Enter, Stay, Exit 등)
        public float3 Normal; // 충돌 법선 벡터

        // CalculateDetails가 체크된 경우, 이 필드는 유효한 값이 있으며 그렇지 않으면 기본값으로 초기화됩니다.
        internal Details CollisionDetails;

        // 생성자: CollisionEvent를 StatefulCollisionEvent로 변환합니다.
        public StatefulCollisionEvent(CollisionEvent collisionEvent)
        {
            EntityA = collisionEvent.EntityA;
            EntityB = collisionEvent.EntityB;
            BodyIndexA = collisionEvent.BodyIndexA;
            BodyIndexB = collisionEvent.BodyIndexB;
            ColliderKeyA = collisionEvent.ColliderKeyA;
            ColliderKeyB = collisionEvent.ColliderKeyB;
            State = default;
            Normal = collisionEvent.Normal;
            CollisionDetails = default;
        }

        // 충돌 세부 사항을 설명하는 구조체
        public struct Details
        {
            internal bool IsValid; // 세부 사항이 유효한지 여부

            // 1이면 정점 충돌, 2이면 모서리 충돌, 3 이상이면 면 충돌
            public int NumberOfContactPoints;

            // 추정된 임펄스
            public float EstimatedImpulse;
            // 평균 접촉 지점 위치
            public float3 AverageContactPointPosition;

            // 생성자: 세부 사항을 초기화합니다.
            public Details(int numContactPoints, float estimatedImpulse, float3 averageContactPosition)
            {
                IsValid = (0 < numContactPoints); // 유효한 접촉점이 있을 경우에만 세부 사항이 유효함
                NumberOfContactPoints = numContactPoints;
                EstimatedImpulse = estimatedImpulse;
                AverageContactPointPosition = averageContactPosition;
            }
        }

        // 주어진 엔티티와 다른 엔티티를 반환하는 함수
        public Entity GetOtherEntity(Entity entity)
        {
            Assert.IsTrue((entity == EntityA) || (entity == EntityB)); // 엔티티 A 또는 B만 유효함
            return entity == EntityA ? EntityB : EntityA;
        }

        // 주어진 엔티티에서 다른 엔티티로 향하는 법선 벡터를 반환합니다.
        public float3 GetNormalFrom(Entity entity)
        {
            Assert.IsTrue((entity == EntityA) || (entity == EntityB)); // 엔티티 A 또는 B만 유효함
            return math.select(-Normal, Normal, entity == EntityB); // EntityB에 대해서는 반대 방향 법선을 반환
        }

        // 충돌 세부 사항이 유효한지 확인하고, 유효한 경우 세부 사항을 반환합니다.
        public bool TryGetDetails(out Details details)
        {
            details = CollisionDetails;
            return CollisionDetails.IsValid; // 세부 사항이 유효한지 여부를 반환
        }

        // 이벤트를 비교하는 함수
        public int CompareTo(StatefulCollisionEvent other) => ISimulationEventUtilities.CompareEvents(this, other);
    }
}

StatefulCollisionEventBufferAuthoring은 MonoBehaviour를 상속받는 클래스

이 클래스는 CalculateDetails라는 변수를 통해 세부 사항 계산 여부를 설정할 수 있도록 합니다.

StatefulCollisionEventBufferBaker는 Baker 클래스로, StatefulCollisionEventBufferAuthoring의 값을 기반으로 Entity를 생성합니다.

이 클래스에서 CalculateDetails 값이 true일 경우, StatefulCollisionEventDetails 컴포넌트를 해당 엔티티에 추가합니다.

StatefulCollisionEventDetails는 IComponentData를 구현한 구조체로,

충돌 이벤트에 대해 세부 사항을 계산할지 여부를 설정하는 CalculateDetails 변수만을 포함하고 있습니다.

StatefulCollisionEvent는 충돌 이벤트를 나타내는 구조체로, EntityA와 EntityB를 비롯한 충돌 관련 정보를 포함합니다.

State는 충돌 상태를 추적하며, CollisionDetails는 선택적으로 세부 충돌 정보를 포함합니다.

Details 구조체는 충돌의 세부 사항을 설명하며, 접촉 지점 수, 추정 임펄스 및 평균 접촉 지점 위치를 저장합니다.

StatefulCollisionEventBufferSystem.cs

CollisionEvent를 StatefulCollisionEvent로 변환하여 동적 버퍼에 저장하는 역할

using Unity.Burst;
using Unity.Entities;
using Unity.Jobs;
using Unity.Physics.Stateful;
using Unity.Physics;
using Unity.Physics.Systems;

// 이 시스템은 CollisionEvent 스트림을 StatefulCollisionEvent로 변환하여 Dynamic Buffer에 저장할 수 있도록 합니다.
// 변환을 위해서는 아래의 조건을 만족해야 합니다:
//    1) PhysicsShapeAuthoring 컴포넌트의 'Collision Response' 속성에서 'Collide Raise Collision Events' 옵션을 활성화하고,
//    2) StatefulCollisionEventBufferAuthoring 컴포넌트를 엔티티에 추가하여 (세부 사항 계산 여부도 선택),
//    또는, 만약 Character Controller에서 이를 원한다면:
//    1) CharacterControllerAuthoring 컴포넌트에서 'Raise Collision Events' 플래그를 활성화합니다.
[UpdateInGroup(typeof(PhysicsSystemGroup))] // 물리 시스템 그룹에 포함
[UpdateAfter(typeof(PhysicsSimulationGroup))] // 물리 시뮬레이션 그룹 후에 실행
public partial struct StatefulCollisionEventBufferSystem : ISystem
{
    private StatefulSimulationEventBuffers<StatefulCollisionEvent> m_StateFulEventBuffers; // StatefulCollisionEvent 버퍼
    private ComponentHandles m_Handles; // 컴포넌트 핸들

    // 아무런 작업을 하지 않는 컴포넌트. 일반적인 job을 사용하기 위해 만들어졌습니다. OnUpdate() 메서드에서 설명
    internal struct DummyExcludeComponent : IComponentData { };

    // 컴포넌트 핸들 구조체
    struct ComponentHandles
    {
        public ComponentLookup<DummyExcludeComponent> EventExcludes; // 이벤트 제외를 위한 컴포넌트 조회
        public ComponentLookup<StatefulCollisionEventDetails> EventDetails; // 이벤트 세부 사항을 위한 컴포넌트 조회
        public BufferLookup<StatefulCollisionEvent> EventBuffers; // 이벤트 버퍼 조회

        // 시스템 상태에 맞는 컴포넌트 핸들을 초기화합니다.
        public ComponentHandles(ref SystemState systemState)
        {
            EventExcludes = systemState.GetComponentLookup<DummyExcludeComponent>(true);
            EventDetails = systemState.GetComponentLookup<StatefulCollisionEventDetails>(true);
            EventBuffers = systemState.GetBufferLookup<StatefulCollisionEvent>(false);
        }

        // 시스템 상태에 맞는 컴포넌트 핸들을 업데이트합니다.
        public void Update(ref SystemState systemState)
        {
            EventExcludes.Update(ref systemState);
            EventBuffers.Update(ref systemState);
            EventDetails.Update(ref systemState);
        }
    }

    // 시스템 초기화
    [BurstCompile]
    public void OnCreate(ref SystemState state)
    {
        m_StateFulEventBuffers = new StatefulSimulationEventBuffers<StatefulCollisionEvent>(); // StatefulCollisionEvent 버퍼 할당
        m_StateFulEventBuffers.AllocateBuffers(); // 버퍼 할당
        state.RequireForUpdate<StatefulCollisionEvent>(); // 시스템이 업데이트 되도록 설정

        m_Handles = new ComponentHandles(ref state); // 컴포넌트 핸들 초기화
    }

    // 시스템 종료
    [BurstCompile]
    public void OnDestroy(ref SystemState state)
    {
        m_StateFulEventBuffers.Dispose(); // 버퍼 해제
    }

    // 충돌 이벤트 동적 버퍼를 지우는 작업을 수행하는 Job
    [BurstCompile]
    public partial struct ClearCollisionEventDynamicBufferJob : IJobEntity
    {
        public void Execute(ref DynamicBuffer<StatefulCollisionEvent> eventBuffer) => eventBuffer.Clear(); // 버퍼 초기화
    }

    // 시스템 업데이트 메서드
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        m_Handles.Update(ref state); // 컴포넌트 핸들 업데이트

        // 충돌 이벤트 동적 버퍼를 지우는 작업을 병렬로 스케줄
        state.Dependency = new ClearCollisionEventDynamicBufferJob()
            .ScheduleParallel(state.Dependency);

        // 이전/현재 버퍼를 교환
        m_StateFulEventBuffers.SwapBuffers();

        var currentEvents = m_StateFulEventBuffers.Current; // 현재 이벤트
        var previousEvents = m_StateFulEventBuffers.Previous; // 이전 이벤트

        // 충돌 이벤트와 세부 사항을 수집하는 작업을 스케줄
        state.Dependency = new StatefulEventCollectionJobs.
            CollectCollisionEventsWithDetails
        {
            CollisionEvents = currentEvents,
            PhysicsWorld = SystemAPI.GetSingleton<PhysicsWorldSingleton>().PhysicsWorld, // 물리 월드
            EventDetails = m_Handles.EventDetails // 이벤트 세부 사항
        }.Schedule(SystemAPI.GetSingleton<SimulationSingleton>(), state.Dependency);

        // 이벤트 스트림을 동적 버퍼로 변환하는 작업을 스케줄
        state.Dependency = new StatefulEventCollectionJobs.
            ConvertEventStreamToDynamicBufferJob<StatefulCollisionEvent, DummyExcludeComponent>
        {
            CurrentEvents = currentEvents,
            PreviousEvents = previousEvents,
            EventLookup = m_Handles.EventBuffers, // 이벤트 버퍼 조회
            UseExcludeComponent = false, // 제외 컴포넌트 사용 안함
            EventExcludeLookup = m_Handles.EventExcludes // 이벤트 제외 조회
        }.Schedule(state.Dependency);
    }
}

세부 작업:

1. 컴포넌트 핸들 업데이트:
   m_Handles.Update(ref state)를 호출하여 컴포넌트 핸들을 최신 상태로 업데이트합니다.
2. 충돌 이벤트 버퍼 초기화:
   ClearCollisionEventDynamicBufferJob을 병렬로 스케줄하여 충돌 이벤트 버퍼를 지웁니다.
3. 이벤트 버퍼 교환:
   SwapBuffers()를 호출하여 현재와 이전 프레임의 이벤트 버퍼를 교환합니다.
   이후 새로운 이벤트를 currentEvents에 기록하고, 이전 이벤트는 previousEvents로 저장됩니다.
4. 충돌 이벤트와 세부 사항 수집:
   StatefulEventCollectionJobs.CollectCollisionEventsWithDetails를 스케줄하여 충돌 이벤트와 관련된 세부 사항을 수집합니다.
   물리 월드 및 이벤트 세부 사항도 이 작업에서 처리됩니다.
5. 이벤트 스트림을 동적 버퍼로 변환:
   StatefulEventCollectionJobs.ConvertEventStreamToDynamicBufferJob을 호출하여 충돌 이벤트를 동적 버퍼로 변환하고, StatefulCollisionEvent 버퍼에 기록합니다.

충돌 위치 쿼리

1. 충돌 이벤트에서 충돌 위치(World Position) 가져오기

public partial struct CollisionPositionLoggerSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        foreach (var (collisionEvents, entity) in SystemAPI.Query<DynamicBuffer<StatefulCollisionEvent>>()
                     .WithEntityAccess())
        {
            foreach (var collisionEvent in collisionEvents)
            {
                if (collisionEvent.TryGetDetails(out var details))
                {
                    float3 worldPosition = details.AverageContactPointPosition;
                    Debug.Log($"Collision at {worldPosition} between {collisionEvent.EntityA} and {collisionEvent.EntityB}");
                }
            }
        }
    }
}

Query로 StatefulCollisionEvent 버퍼를 가져옴

• SystemAPI.Query<DynamicBuffer<StatefulCollisionEvent>>()를 사용해 현재 프레임의 충돌 이벤트를 가져옴.

각 충돌 이벤트의 세부 사항 가져오기

• collisionEvent.TryGetDetails(out var details)를 호출하여 충돌 세부 정보를 가져올 수 있는지 확인.
• details.AverageContactPointPosition은 충돌 지점들의 평균 좌표로, 월드 좌표계에서의 위치를 제공.

디버그 로그 출력

• Debug.Log()를 이용해 충돌 위치와 관련된 엔티티 정보를 출력.

2. 여러 개의 접촉점(Contact Points) 활용하기

만약 여러 개의 접촉점을 각각 확인하려면, CalculateDetails를 활성화하고 details.NumberOfContactPoints 값을 사용해야 합니다.

하지만, 현재 StatefulCollisionEvent는 AverageContactPointPosition만을 제공하므로, 개별 접촉점의 좌표를 얻으려면 PhysicsWorld를 직접 사용해야 합니다.

이 경우, collisionEvent.CalculateDetails(ref PhysicsWorld)를 호출하여 접촉점 데이터를 직접 가져올 수 있습니다.

if (collisionEvent.TryGetDetails(out var details))
{
    Debug.Log($"Collision has {details.NumberOfContactPoints} contact points.");
}

The post ECS – Unity Physics Stateful Event Study appeared first on 어제와 내일의 나 그 사이의 이야기.