Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

C# 컬렉션

.NET 기본 클래스 라이브러리에는 데이터를 저장하고 조작하는 데 사용할 수 있는 여러 컬렉션 유형이 포함되어 있습니다. Godot는 또한 엔진의 나머지 부분과 긴밀하게 통합된 일부 컬렉션 유형을 제공합니다.

포트 그리고 연결

`.NET 컬렉션 <https://learn.microsoft.com/en-us/dotnet/standard/collections/>`_과 Godot 컬렉션의 주요 차이점은 .NET 컬렉션은 C#으로 구현되는 반면 Godot 컬렉션은 C++로 구현되고 Godot C# API는 이에 대한 래퍼라는 점입니다. 이는 Godot 컬렉션의 모든 작업에 특히 루프 내에서 비용이 많이 들 수 있는 마샬링이 필요하다는 의미이므로 중요한 차이점입니다.

성능에 미치는 영향으로 인해 Godot 컬렉션을 사용하는 것은 꼭 필요한 경우에만 권장됩니다(예: Godot API와의 상호작용). Godot는 자신의 컬렉션 유형만 이해하므로 엔진과 대화할 때 이를 사용해야 합니다.

Godot API에 전달할 필요가 없는 요소 컬렉션이 있는 경우 .NET 컬렉션을 사용하는 것이 더 성능이 좋습니다.

팁

.NET 컬렉션과 Godot 컬렉션 간 변환도 가능합니다. Godot 컬렉션에는 해당 요소를 복사하는 일반 .NET 컬렉션 인터페이스의 생성자가 포함되어 있으며 Godot 컬렉션은 LINQ ToList, ToArray 및 ToDictionary 메서드와 함께 사용할 수 있습니다. 하지만 이 변환을 위해서는 컬렉션의 모든 요소를 마샬링하고 새 컬렉션에 복사해야 하므로 비용이 많이 들 수 있다는 점을 명심하세요.

그럼에도 불구하고 Godot 컬렉션은 불필요한 마샬링을 피하도록 최적화되어 있으므로 Sort 또는 ``Reverse``와 같은 메서드는 단일 interop 호출로 구현되며 모든 요소를 마샬링할 필요가 없습니다. `LINQ <https://learn.microsoft.com/en-us/dotnet/standard/linq>`_와 같은 컬렉션 인터페이스를 사용하는 일반 API를 주의 깊게 살펴보세요. 모든 메서드에는 컬렉션을 반복해야 하므로 모든 요소를 마샬링해야 하기 때문입니다. 가능하다면 Godot 컬렉션의 인스턴스 메소드를 사용하는 것을 선호하세요.

각 상황에 사용할 컬렉션 유형을 선택하려면 다음 질문을 고려하세요.

당신의 컬렉션이 Godot 엔진과 상호 작용해야 합니까? (예: Godot 메소드를 호출하는 내보낸 속성의 유형)
- 그렇다면 Godot는 :ref:`c_sharp_variant_compatible_types`만 지원하므로 Godot 컬렉션을 사용하세요.
- 그렇지 않은 경우 `적절한 .NET 컬렉션 선택 <https://learn.microsoft.com/en-us/dotnet/standard/collections/selecting-a-collection-class>`_을 고려하세요.
데이터의 목록이나 순차적 세트를 나타내는 Godot 컬렉션이 필요합니까?
- Godot :ref:`arrays <doc_c_sharp_collections_array>`는 C# 컬렉션 ``List<T>``와 유사합니다.
- Godot packed arrays <doc_c_sharp_collections_packedarray>`는 메모리 효율성이 더 높은 배열입니다. C#에서는 지원되는 ``System.Array` 유형 중 하나를 사용합니다.
키 세트를 값 세트에 매핑하는 Godot 컬렉션이 필요합니까?
- Godot dictionaries 키와 값의 쌍을 저장하고 관련 키를 통해 값에 쉽게 액세스할 수 있도록 합니다.

알림(Notifications)

배열

Godot 패킹된 배열은 특정 유형의 배열로 구현되어 각 요소가 ``Variant``가 아닌 특정 유형의 크기를 갖기 때문에 더 촘촘하게 패킹될 수 있습니다.

C#에서는 압축형 배열이 ``System.Array``로 대체됩니다.

GDScript	C#
`PoolByteArray`	`byte[]`
`PoolIntArray`	`int[]`
`PoolIntArray`	`float[]`
`PoolFloatArray`	`float[]`
`PoolFloatArray`	`byte[]`
`PoolStringArray`	`String[]`
`PoolVector2Array`	`Vector2[]`
`PoolVector3Array`	`Vector3[]`
`PoolVector2Array`	`Vector2[]`
`PoolColorArray`	`Color[]`

다른 C# 배열은 압축된 배열이 존재하지 않기 때문에 Godot C# API에서 지원되지 않습니다. 커스텀 변수 타입 목록을 참조하세요.

배열

Godot 배열은 Variant 배열로 구현되며 모든 유형의 여러 요소를 포함할 수 있습니다. C#에서 동등한 유형은 ``Godot.Collections.Array``입니다.

일반 Godot.Collections.Array<T> 유형을 사용하면 요소 유형을 :ref:`Variant 호환 유형 <c_sharp_variant_ Compatible_types>`으로 제한할 수 있습니다.

Godot.Collections.Array<T> 는 Godot.Collections.Array 를 둘러싸는 type-safe wrapper 입니다. Godot.Collections.Array<T>(Godot.Collections.Array) 생성자를 사용해 만들 수 있습니다.

참고

이름에도 불구하고 Godot 배열은 ``System.Array``보다 C# 컬렉션 ``List<T>``와 더 유사합니다. 크기는 고정되어 있지 않으며 컬렉션에 요소가 추가/제거됨에 따라 늘어나거나 줄어들 수 있습니다.

Godot의 배열 메소드 목록과 C#에서 이에 상응하는 메소드:

GDScript	C#
Call(호출)	System.Linq.Enumerable.All
그리고	System.Linq.Enumerable.Any
추가	Android
append_array	범위 추가
signal	지우기 및 AddRange
단점	`Array[^1]` 또는 System.Linq.Enumerable.Last 또는 System.Linq.Enumerable.LastOrDefault
b검색	바이너리서치
bsearch_custom	NAN
명확한	클리어코트
양	System.Linq.Enumerable.Count
복제	복제
카메라	제거
채우다	채우기
필터	System.Linq.Enumerable.Where 사용
찾기	인덱스
앞	`Array[0]` 또는 System.Linq.Enumerable.First 또는 System.Linq.Enumerable.FirstOrDefault
벡터 내장 타입	NAN
class_name	NAN
get_typed_script	NAN
as	내용 테스트
hash	GD.Hash
assert	키 삽입
is_empty	`Count == 0` 사용
is_read_only	읽기 전용
is_same_typed	NAN
타입	NAN
make_read_only	읽기 전용으로 만들기
맵	System.Linq.Enumerable.Select
최대	맵
믹스	최소
pick_random	PickRandom(System.Random 사용을 고려하세요)
pop_at	`Array[i]` 및 `RemoveAt(i)`
pop_back	`Array[^1]` 및 `RemoveAt(Count - 1)`
pop_front	`Array[0]` 및 `RemoveAt(0)`
push_back	`Insert(Count, item)`
push_front	`Insert(0, item)`
감소시키다	System.Linq.Enumerable.Aggregate
remote	제거 위치
크기 조정	크기 조정
Server	Server
찾기	인덱스
shuffle	셔플
크기	양
slice	썰기
정렬	정렬
sort_custom	System.Linq.Enumerable.OrderBy
연산자	!재귀동등
연산자	연산자
연산자	NAN
연산자	NAN
연산자	재귀동등
연산자	NAN
연산자	NAN
연산자	어레이[int] 인덱서

딕셔너리

Godot 사전은 Variant 키와 값을 가진 사전으로 구현됩니다. C#에서 동등한 유형은 ``Godot.Collections.Dictionary``입니다.

일반 Godot.Collections.Dictionary<TKey, TValue> 유형을 사용하면 키 및 값 유형을 :ref:`Variant 호환 유형 <c_sharp_variant_ Compatible_types>`으로 제한할 수 있습니다.

Godot.Collections.Dictionary<T> 는 Godot.Collections.Dictionary 를 둘러싸는 type-safe wrapper입니다. Godot.Collections.Dictionary<T>(Godot.Collections.Dictionary) 생성자를 사용해 만들 수 있습니다.

팁

키가 입력되었지만 값이 아닌 사전이 필요한 경우 Variant``를 입력된 사전의 ``TValue 일반 매개변수로 사용하세요.

// The keys must be string, but the values can be any Variant-compatible type.
var dictionary = new Godot.Collections.Dictionary<string, Variant>();

Godot의 사전 메소드 목록 및 C#의 해당 메소드 목록:

GDScript	C#
명확한	클리어코트
복제	복제
카메라	제거
find_key	NAN
설정	Dictionary[Variant] 인덱서 또는 TryGetValue
as	계속
has_all	NAN
hash	GD.Hash
is_empty	`Count == 0` 사용
is_read_only	읽기 전용
키	열쇠
make_read_only	읽기 전용으로 만들기
병합	병합
크기	양
값	값
연산자	!재귀동등
연산자	재귀동등
연산자	Dictionary[Variant] 인덱서, 추가 또는 TryGetValue