> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/architecture/querying-components.md).

# 컴포넌트 조회

공통 컴포넌트를 가진 엔티티 목록을 가져오는 방법을 알아보고, 이를 더 쉽게 확인하거나 업데이트하는 방법을 배웁니다.

할 수 있습니다 [컴포넌트 쿼리](/creator/content-creator-ko/sdk7/architecture/querying-components.md) 다음 메서드로 `engine.getEntitiesWith(...components)` 특정 컴포넌트를 가진 씬의 모든 엔티티를 추적할 수 있습니다.

[시스템](/creator/content-creator-ko/sdk7/architecture/systems.md) 시스템은 일반적으로 이러한 쿼리의 엔티티를 순회하면서 각 엔티티에 동일한 작업을 수행합니다. 미리 정의된 유효한 엔티티 그룹을 갖는 것은 리소스를 절약하는 좋은 방법이며, 특히 게임 루프의 모든 틱마다 실행되는 함수에 유용합니다. 매 틱마다 시스템이 필요한 엔티티를 찾기 위해 씬의 모든 엔티티를 전부 순회해야 한다면 매우 비효율적일 것입니다.

다음과 같이 쿼리의 엔티티에 접근할 수 있습니다.

```ts
for (const [entity] of engine.getEntitiesWith(Transform)) {
	//...
}
```

## 필수 컴포넌트

쿼리를 만들 때 그룹에 추가되는 각 엔티티에 어떤 컴포넌트가 반드시 있어야 하는지 지정하세요. 원하는 만큼 컴포넌트를 나열할 수 있으며, 쿼리는 다음을 가진 엔티티만 반환합니다 **모든** 나열된 컴포넌트의

```ts
for (const [entity] of engine.getEntitiesWith(
	Transform,
	Physics,
	NextPosition
)) {
	//...
}
```

{% hint style="info" %}
**💡 팁**: 쿼리가 처리할 필요가 없는 엔티티를 반환한다면, 사용자 정의 컴포넌트를 만들어 다음 역할을 하도록 고려해 보세요 [플래그](/creator/content-creator-ko/sdk7/architecture/entities-components.md#components-as-flags). 이 컴포넌트에는 어떤 속성도 필요 없지만, 다르게 처리하고 싶은 특정 엔티티 하위 그룹을 표시하는 데 사용할 수 있습니다.
{% endhint %}

## 시스템에서 쿼리 사용

```ts
// 시스템 정의
function PhysicsSystem(dt: number) {
	// Transform과 Physics 컴포넌트를 모두 포함하는 엔티티를 쿼리
	for (const [entity] of engine.getEntitiesWith(Transform, Physics)) {
		const transform = Transform.getMutable(entity)
		const vel = Physics.get(entity).velocity
		transform.position.x += vel.x
		transform.position.y += vel.y
		transform.position.z += vel.z
	}
}

// 시스템을 엔진에 추가
engine.addSystem(PhysicsSystem)
```

위 예제에서, `PhysicsSystem` 함수는 쿼리의 엔티티를 순회하며, 이는 게임 루프의 매 틱마다 실행됩니다.

* 씬에 여러 개의 *공* 엔티티가 있고, 각 엔티티에 `Transform` 와 하나의 `Physics` 컴포넌트가 있다면 처리되고, 매 틱마다 위치가 업데이트됩니다.
* 씬에 다른 엔티티도 있다면, 예를 들어 *골대* 와 하나의 *점수판* 오직 a만 가지고 있는 `Transform` 하지만 a는 없는 `Physics` 컴포넌트가 있다면, 다음의 영향을 받지 않습니다 `PhysicsSystem`.

## 엔티티와 컴포넌트 다루기

이 `getEntitiesWith` 함수는 엔티티 집합에 대한 참조를 포함하는 컬렉션을 반환하며, 선택적으로 나열된 컴포넌트에 대한 참조도 포함할 수 있습니다.

가장 간단한 문법을 사용하면 해당 엔티티에 대한 참조 목록만 가져옵니다.

```ts
for (const [entity] of engine.getEntitiesWith(myComponent, myOtherComponent)) {
	//...
}
```

이 엔티티 목록을 순회하는 동안, 다음을 사용하여 해당 컴포넌트의 읽기 전용 또는 수정 가능한 버전을 가져올 수 있습니다 `.get` 또는 `getMutable`.

```ts
for (const [entity] of engine.getEntitiesWith(Transform)) {
	// 읽기 전용 버전 가져오기
	const transformReadOnly = Transform.get(entity)

	// 수정 가능한 버전 가져오기
	const transformMutable = Transform.getMutable(entity)
}
```

쿼리가 반환하는 컬렉션의 일부로, 나열된 각 컴포넌트에 대한 참조도 직접 선택적으로 가져올 수 있습니다. 이렇게 하려면 가져오려는 각 컴포넌트에 대해 참조를 하나씩 함께 선언하기만 하면 됩니다. 이러한 참조를 추가하는 것은 선택 사항이며, 다음에 대한 참조를 선언할 필요도 없습니다 *모든* 쿼리의 컴포넌트에 대해서도 마찬가지입니다.

```ts
// 엔티티와 첫 번째로 나열된 컴포넌트에 대한 참조를 반환
for (const [entity, component1] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// 엔티티 목록을 순회
}

// 엔티티와 처음 두 개의 나열된 컴포넌트에 대한 참조를 반환
for (const [entity, component1, component2] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// 엔티티 목록을 순회
}
```

{% hint style="warning" %}
**📔 참고**: 이러한 참조는 읽기 전용입니다. 해당 컴포넌트의 수정 가능한 버전을 가져오려면 다음을 사용해야 합니다 `.getMutable` 엔티티를 참조하는 함수
{% endhint %}

그런 다음 결과 컬렉션을 순회하면서 이 참조들을 사용할 수 있으며, 각 항목에서 엔티티와 해당 컴포넌트 참조에 접근할 수 있습니다.

```ts
for (const [entity, transformReadOnly] of engine.getEntitiesWith(Transform)) {
	console.log('엔티티 ID: ', entity)
	console.log('위치 포함: ', transformReadOnly.position)
}
```

## 변경 사항 구독

흔한 사용 사례는 특정 컴포넌트의 데이터가 변경될 경우에만 함수를 실행하는 것입니다. 다음을 사용하세요 [OnChange](/creator/content-creator-ko/sdk7/architecture/subscribe-to-changes.md) 함수를 사용하면 시스템을 정의하고 이전 값과 새 값을 명시적으로 비교할 필요가 없습니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/architecture/querying-components.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.