> 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-pt/scenes-sdk7/interatividade/raycasting.md).

# Raycasting

Use raycasting para traçar uma linha no espaço e consultar colisões com entities na scene.

O raycasting é uma ferramenta fundamental no desenvolvimento de jogos. Com o raycasting, pode traçar uma linha imaginária no espaço e verificar se alguma Entity é intersectada por essa linha. Isto é útil para calcular linhas de visão, trajetórias de balas, algoritmos de localização de caminhos e muitas outras aplicações.

Quando um jogador prime o botão do ponteiro, ou o botão primário ou secundário, é traçado um raio a partir da posição do jogador, na direção para a qual está virado. Consulte [eventos de botão](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md) para obter mais detalhes. Este documento explica como traçar um raio invisível a partir de qualquer posição e direção, independentemente das ações do jogador, para o utilizar em muitos outros cenários.

Tenha em atenção que os raycasts só atingem objetos com Colliders. Por isso, se quiser detetar impactos de raios num modelo 3D, deve fazer uma das seguintes coisas:

* O modelo tem de conter [Meshes de Collider](https://docs.decentraland.org/creator/content-creator-pt/modelacao-3d-e-animacoes/colliders.md).
* O `GLTFContainer` tem de estar configurado para usar a [geometria visível com máscaras de colisão](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md#colliders-on-3d-models).
* Adicione um componente [MeshCollider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md).

Também é uma boa prática atribuir [Collision Layers](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md#collision-layers) personalizadas aos modelos 3D, para que os raios só tenham de calcular colisões com as Entity relevantes, em vez de com tudo o que tenha um Collider.

## Criar um raio

Todos os raios têm um ponto de origem e uma direção. O ponto de origem baseia-se na posição de uma Entity, considerando os valores do componente Transform da Entity. A direção de um raio pode ser definida de 4 formas diferentes:

* **local**: uma direção relativa à direção para a qual a Entity está virada, também afetada pela transformação de quaisquer Entity parent. Isto é útil para detetar obstáculos à frente de veículos, respeitando a direção em que se deslocam.
* **global**: ignora a rotação da Entity e aponta numa direção como se a rotação da Entity fosse 0. Isto é útil, por exemplo, para apontar sempre para baixo.
* **alvo global**: traça uma linha entre a posição da Entity e a posição global de um alvo na cena. Ignora a rotação da Entity. É útil, por exemplo, para criar jogos de tower defense, em que a torre de cada torre pode apontar para uma coordenada exata no espaço.
* **Entity alvo**: traça uma linha entre a posição da Entity e a posição de uma segunda Entity alvo. Ignora a rotação de ambas as Entity.

O código seguinte cria um raycast com uma direção local:

```ts
const myEntity = engine.addEntity()
Transform.create(myEntity, {
  position: Vector3.create(4, 1, 4),
})

raycastSystem.registerLocalDirectionRaycast(
  {
    entity: myEntity,
    opts: { direction: Vector3.Forward() },
  },
  function (raycastResult) {
    // callback function
  }
)
```

Use as seguintes funções para criar raycasts, indicando a direção de diferentes formas:

* `raycastSystem.registerLocalDirectionRaycast()`: cria um raycast com uma direção **local** . O campo `direction` espera um `Vector3` que descreve um vetor relativo à Entity e à sua rotação (por exemplo, `Vector3.Forward()` acabaria por usar o vetor forward do Transform da Entity)
* `raycastSystem.registerGlobalDirectionRaycast()`: cria um raycast com uma direção **global** . O campo `direction` O campo espera um `Vector3` que descreva a direção global.
* `raycastSystem.registerGlobalTargetRaycast()`: cria um raycast com uma direção definida por uma **posição de destino global** . O campo `target` espera um `Vector3` que descreva uma posição global na cena.
* `raycastSystem.registerTargetEntityRaycast()`: cria um raycast com uma direção definida em direção à **posição da entidade de destino** . O campo `targetEntity` espera uma referência a uma entidade; a posição dessa entidade será usada como destino do raio.

Os seguintes campos opcionais estão disponíveis ao criar um raio com qualquer um dos métodos acima:

* `maxDistance`: *número* para definir o comprimento do traçado deste raio. Se não for definido, o valor predefinido é 16 metros.
* `queryType`: *valor da enumeração RaycastQueryType* para definir se o raio devolverá todas as entidades atingidas ou apenas a primeira. Estão disponíveis as seguintes opções:
  * `RaycastQueryType.RQT_HIT_FIRST`: *(predefinição)* devolve apenas a primeira entidade atingida, a partir do ponto de origem.
  * `RaycastQueryType.RQT_QUERY_ALL`: devolve todas as entidades atingidas, desde a origem até à distância máxima do raio.
* `originOffset`: Em vez de iniciar o raycast na posição de origem da entidade, adicione um desvio para iniciar a consulta numa posição relativa. Por exemplo, pode usar um pequeno desvio para impedir que o raio colida com o collider da própria entidade. Se não for definido, o valor predefinido é `Vector3.Zero()`.
* `collisionMask`: deteta colisões apenas com determinadas camadas de colisão. Use esta opção em conjunto com uma camada de colisão personalizada ou para detetar apenas a camada de física ou de Pointer Events. Consulte [camadas de colisão](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md#collision-layers). Se não for definido, a camada usada por predefinição é `ColliderLayer.CL_PHYSICS`.
* `continuous`: se for true, executa continuamente uma consulta de raycast em cada frame. Se for false, o raio será usado apenas no frame atual. Se não for definido, o valor predefinido é false.
* Ao definir a direção com uma direção local ou global, o campo `direction` tem como valor predefinido `Vector3.Forward()`.
* Ao definir a direção com um destino global, o campo `target` tem como valor predefinido `Vector3.Zero()`.
* Ao definir a direção com uma entidade de destino, o campo `targetEntity` tem como valor predefinido a entidade raiz da cena, localizada em `Vector3.Zero()`.

{% hint style="warning" %}
**📔 Nota**: A `continuous` deve ser utilizada com cautela, uma vez que executar uma consulta de raycast em cada frame pode ter um custo de desempenho muito elevado. Sempre que possível, utilize um sistema (ou a função `interval` da biblioteca Utils) para executar consultas de raycast em intervalos regulares e mais espaçados. Consulte [raycasting recorrente](#recurrent-raycasting).
{% endhint %}

Abaixo estão exemplos que utilizam cada um dos quatro métodos para determinar a direção do raio:

```ts
// RAYCAST COM DIREÇÃO LOCAL
raycastSystem.registerLocalDirectionRaycast(
  {
    entity: myEntity,
    opts: {
      queryType: RaycastQueryType.RQT_QUERY_ALL,
      direction: Vector3.Forward(),
      maxDistance: 30,
    },
  },
  function (raycastResult) {
    console.log(raycastResult.hits)
  }
)
// RAYCAST COM DIREÇÃO GLOBAL
raycastSystem.registerGlobalDirectionRaycast(
  {
    entity: myEntity,
    opts: {
      queryType: RaycastQueryType.RQT_QUERY_ALL,
      direction: Vector3.Forward(),
      maxDistance: 30,
    },
  },
  function (raycastResult) {
    console.log(raycastResult.hits)
  }
)
// RAYCAST COM POSIÇÃO-ALVO GLOBAL
raycastSystem.registerGlobalTargetRaycast(
  {
    entity: myEntity,
    opts: {
      queryType: RaycastQueryType.RQT_QUERY_ALL,
      target: Vector3.Zero(),
    },
  },
  (raycastResult) => {
    console.log(raycastResult.hits)
  }
)
// RAYCAST COM ENTIDADE-ALVO
const targetEntity = engine.addEntity()
Transform.create(targetEntity, { position: Vector3.create(8, 1, 10) })

raycastSystem.registerTargetEntityRaycast(
  {
    entity: myEntity,
    opts: {
      queryType: RaycastQueryType.RQT_QUERY_ALL,
      targetEntity: targetEntity,
    },
  },
  (raycastResult) => {
    console.log(raycastResult.hits)
  }
)
```

{% hint style="warning" %}
**📔 Nota**: `raycastSystem`, `RaycastQueryType` e `ColliderLayer` têm de ser importados através de

> `import { raycastSystem, RaycastQueryType, ColliderLayer } from "@dcl/sdk/ecs"`

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

## Resultado do raycast

A função de callback que processa o raycast recebe um objeto que contém dados sobre o próprio raio e sobre quaisquer entidades atingidas.

* `globalOrigin`: A posição de origem do raio, relativa à cena.
* `direction`: A direção global para a qual o raio apontava, como um `Vector3`.
* `hits`: Uma matriz com um objeto para cada entidade atingida. Se nenhuma entidade tiver sido atingida, a matriz fica vazia. Se o raycast tiver utilizado `RaycastQueryType.RQT_HIT_FIRST`, esta matriz conterá apenas um objeto.

Cada objeto na matriz `hits` inclui:

* `entityId`: O número de ID da entidade atingida pelo raio.
* `meshName`: *String* com o nome interno da malha específica do modelo 3D atingida. Isto é útil quando um modelo 3D é composto por várias malhas.
* `position`: *Vector3* para a posição em que o raio intersectou a entidade atingida (em relação à cena)
* `length`: Comprimento do raio desde a sua origem até à posição em que ocorreu a colisão com a entidade.
* `normalHit`: *Vector3* para a normal da superfície atingida no espaço global.
* `globalOrigin`: *Vector3* para a posição de origem do raio (em relação à cena)
* `direction`: A direção global para a qual o raio apontava, como um `Vector3`.

O exemplo seguinte percorre as entidades atingidas:

```ts
const myEntity = engine.addEntity()
Transform.create(myEntity, {
  position: Vector3.create(4, 1, 4),
})

raycastSystem.registerLocalDirectionRaycast(
  {
    entity: myEntity,
    opts: {
      queryType: RaycastQueryType.RQT_QUERY_ALL,
      direction: Vector3.Forward(),
      maxDistance: 30,
    },
  },
  function (raycastResult) {
    if (raycastResult.hits.length > 0) {
      for (const hit of raycastResult.hits) {
        if (hit.entityId) {
          console.log('hit entity ', hit.entityId)
        }
      }
    } else {
      console.log('no entities hit')
    }
  }
)
```

{% hint style="warning" %}
**📔 Nota**: Pode obter um resultado de raycast ao atingir uma entidade noutra cena.
{% endhint %}

## Processar entidades atingidas

Quando obtém um resultado de raycast que atingiu uma entidade, pode usar o `entityId` para interagir com a entidade e os respetivos componentes. Uma entidade não é [nada mais do que um número](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md#overview), pelo que o `entityId` próprio valor pode ser interpretado como um tipo `Entity` .

```ts
const hitEntity = hit.entityId as Entity
const transform = Transform.get(hitEntity)
console.log(transform.position)
```

## Camadas de colisão

É uma boa prática verificar apenas colisões com entidades relevantes, para melhorar o desempenho da cena. O campo `collisionMask` permite listar apenas camadas de colisão específicas — a camada de física (paredes e pisos da cena), a camada de ponteiros (eventos de ponteiro), as camadas de jogadores (Avatars) ou 8 camadas personalizadas que pode atribuir livremente. Consulte [camadas de colisão](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md#collision-layers).

Por predefinição, o campo `collisionMask` está definido como `ColliderLayer.CL_PHYSICS`. Pode alterar este valor para listar outras camadas ou combinar várias usando o separador `|` .

```ts
raycastSystem.registerLocalDirectionRaycast(
  {
    entity: myEntity,
    opts: {
      queryType: RaycastQueryType.RQT_QUERY_ALL,
      direction: Vector3.Forward(),
      maxDistance: 30,
      collisionMask:
        ColliderLayer.CL_CUSTOM1 |
        ColliderLayer.CL_CUSTOM3 |
        ColliderLayer.CL_POINTER,
    },
  },
  (raycastResult) => {
    log(raycastResult.hits)
  }
)
```

## Raycasting recorrente

Ao usar as funções de `raycastSystem`, o comportamento predefinido é criar um único raio, que verifica colisões uma vez. Como alternativa, pode definir o `continuous` campo para *true* executar uma consulta e a função de callback em cada tick do loop do jogo.

O exemplo a seguir continuará executando a consulta de raycast a partir deste ponto

```ts
raycastSystem.registerLocalDirectionRaycast(
  {
    entity: myEntity,
    opts: {
      queryType: RaycastQueryType.RQT_QUERY_ALL,
      direction: Vector3.Forward(),
      maxDistance: 30,
      continuous: true,
    },
  },
  function (raycastResult) {
    log(raycastResult.hits)
  }
)
```

{% hint style="warning" %}
**📔 Nota**: A propriedade `continuous` deve ser usada com cautela, pois executar uma consulta de raycast em cada frame pode afetar muito o desempenho.
{% endhint %}

Quando não forem mais necessárias, remova as raycasts recorrentes. Para isso, use `raycastSystem.removeRaycasterEntity`.

```ts
raycastSystem.removeRaycasterEntity(myEntity)
```

Quando possível, use um sistema (ou a função `interval` da biblioteca Utils) para executar consultas de raycast em intervalos regulares e mais espaçados, por exemplo, uma vez por segundo ou a cada quinto de segundo.

```typescript
// componentes personalizados
const CubeOscilator = engine.defineComponent('CubeOscilator', {
  t: Schemas.Float,
})

const TimerComponent = engine.defineComponent('TimerComponent', {
  t: Schemas.Float,
})

const RAY_INTERVAL = 0.1

// verificar raycasts
engine.addSystem((dt) => {
  for (const [entity] of engine.getEntitiesWith(TimerComponent)) {
    const timer = TimerComponent.getMutable(entity)
    timer.t += dt

    if (timer.t > RAY_INTERVAL) {
      timer.t = 0
      raycastSystem.registerGlobalDirectionRaycast(
        {
          entity: myEntity,
          opts: {
            queryType: RaycastQueryType.RQT_HIT_FIRST,
            direction: Vector3.Forward(),
            maxDistance: 16,
          },
        },
        function (raycastResult) {
          log(raycastResult.hits)
        }
      )
    }
  }
})

TimerComponent.create(engine.addEntity())

// sistema do cubo oscilante
engine.addSystem((dt) => {
  for (const [entity, cube] of engine.getEntitiesWith(
    CubeOscilator,
    Transform
  )) {
    CubeOscilator.getMutable(entity).t += dt
    Transform.getMutable(entity).position.y = 2 + Math.cos(cube.t)
  }
})

// criar cubo
const cubeEntity = engine.addEntity()
Transform.create(cubeEntity, { position: { x: 8, y: 1, z: 8 } })
CubeOscilator.create(cubeEntity)
MeshRenderer.setBox(cubeEntity)
MeshCollider.setBox(cubeEntity)
```

O exemplo acima executa um raycast recorrente a cada 0,1 segundos. Ele usa um componente de timer e a propriedade `dt` de um sistema para cronometrar esses intervalos uniformemente. Também inclui um cubo que oscila para cima e para baixo, controlado por outro sistema, para movê-lo para dentro e para fora do caminho do raio.

{% hint style="info" %}
**💡 Dica**: Use a função `interval` da [Biblioteca SDK Utils](https://github.com/decentraland/sdk7-utils) para uma forma mais simples de executar uma função num intervalo fixo.
{% endhint %}

## Raycasts através de um sistema

Outra forma de realizar raycasts recorrentes é executá-los na função recorrente de um sistema. Isto permite-lhe ter muito mais controlo sobre quando e como são executados. Em vez de registar uma função de callback, pode executar uma consulta de raycast com `raycastSystem.registerRaycast` e, em seguida, verificar os dados devolvidos por esta operação, tudo dentro da função do sistema.

Tenha em atenção que, como o raycast é executado num sistema, o resultado só estará disponível no tick seguinte, sendo necessárias duas execuções do sistema. Na primeira, o raycast é registado para o frame seguinte; no frame seguinte, o resultado é processado.

```ts
engine.addSystem((deltaTime) => {
		const result = raycastSystem.registerRaycast(
			myEntity,
			raycastSystem.localDirectionOptions({
				collisionMask: ColliderLayer.CL_CUSTOM1 | ColliderLayer.CL_CUSTOM3 | ColliderLayer.CL_POINTER,
				originOffset: Vector3.create(0, 0.4, 0),
				maxDistance: 16,
				queryType: RaycastQueryType.RQT_HIT_FIRST,
				direction: Vector3.Forward(),
				continuous: true // don't overuse the 'continuous' property as raycasting is expensive on performance
			})
		)
		if (result) {
			// fazer algo
		}
	})
```

## Colidir com o jogador

Pode detetar Avatars diretamente com raycasts, incluindo uma das camadas de colisão de Avatar na máscara:

* `ColliderLayer.CL_PLAYER`: corresponde a qualquer Avatar — o jogador local E qualquer outro jogador apresentado na cena.
* `ColliderLayer.CL_MAIN_PLAYER`: corresponde apenas ao jogador local (principal).

Ambas as camadas podem ser combinadas ou utilizadas de forma independente. O valor predefinido de `collisionMask` para um raycast é `CL_PHYSICS`, que NÃO atinge Avatars — tem de ativar esta opção explicitamente.

```ts
// Atingir apenas o jogador local (ignorar os outros Avatars)
raycastSystem.registerLocalDirectionRaycast(
  {
    entity: myEntity,
    opts: {
      direction: Vector3.Forward(),
      collisionMask: ColliderLayer.CL_MAIN_PLAYER,
    },
  },
  (raycastResult) => {
    if (raycastResult.hits.length > 0) {
      console.log('Hit the local player')
    }
  }
)

// Atingir qualquer Avatar (local + remoto)
raycastSystem.registerLocalDirectionRaycast(
  {
    entity: myEntity,
    opts: {
      direction: Vector3.Forward(),
      collisionMask: ColliderLayer.CL_PLAYER,
    },
  },
  (raycastResult) => {
    // raycastResult.hits[i].entityId é 0 para hits em Avatars remotos (sem ID de entidade local à cena)
    console.log(raycastResult.hits)
  }
)
```

Quando um raycast atinge o jogador local, o `hit.entityId` é `engine.PlayerEntity`. Os hits em Avatars remotos não incluem um ID de entidade local à cena (o campo é `0`) porque o jogador remoto não é uma entidade no mundo da sua cena — mas o hit continua a ser comunicado com a sua `position`, `length`, `normalHit`, e outros dados geométricos.

{% hint style="info" %}
**💡 Dica**: Para detetar apenas **outros** jogadores (excluindo o jogador local), use `CL_PLAYER` e filtre `hit.entityId !== engine.PlayerEntity` no callback.
{% endhint %}

## Raycasts a partir do jogador

Para traçar um raio a partir da posição do jogador na direção para a qual a câmara está virada, pode traçá-lo usando a câmara ou o Avatar [Entidades reservadas](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md#reserved-entities).

{% hint style="info" %}
**💡 Sugestão**: Na maioria dos casos, poderá ser melhor utilizar [Pointer events](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md) em vez de raycasts.
{% endhint %}

O exemplo seguinte traça um raio para a frente a partir da posição da câmara do jogador, utilizando a `engine.CameraEntity` entidade.

```ts
raycastSystem.registerGlobalDirectionRaycast(
  {
    entity: engine.CameraEntity,
    opts: {
      queryType: RaycastQueryType.RQT_HIT_FIRST,
      direction: Vector3.rotate(
        Vector3.Forward(),
        Transform.get(engine.CameraEntity).rotation
      ),
    },
  },
  function (raycastResult) {
    console.log(raycastResult)
  }
)
```

{% hint style="warning" %}
**📔 Nota**: Tenha em conta que, no modo de terceira pessoa, o cursor poderá vir a comportar-se de forma diferente do que no modo de primeira pessoa. Recomenda-se utilizar esta funcionalidade apenas quando o jogador estiver no modo de primeira pessoa.
{% endhint %}

## Traçar um raio a partir da posição do cursor

Também pode traçar um raio desde a posição do cursor do jogador até ao mundo 3D. Isto pode ser utilizado para arrastar objetos, em jogos de tiro, etc.

Neste exemplo, detetamos quando o jogador prime a tecla E e, em seguida, traçamos um raio desde a posição do cursor até ao mundo 3D. Depois verificamos se o raio atingiu alguma entidade e, em caso afirmativo, fazemos algo com ela.

```ts
import { engine, Entity, InputAction, inputSystem, PointerEventType, RaycastQueryType, raycastSystem, TextShape, Transform } from '@dcl/sdk/ecs'
import { PrimaryPointerInfo } from '@dcl/sdk/ecs'

let cooldown = 1
let rayFrequency = 0.1
let mousePressed = false

export function main() {
   engine.addSystem(rayCastSystem)
}

const rayCastSystem = (t: number) => {

    if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN)) {
      mousePressed = true
    }

    if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_UP)) {
      mousePressed = false
    }

    if (!mousePressed) {
      cooldown = 0
      raycastSystem.removeRaycasterEntity(engine.CameraEntity)
      return
    }

    cooldown += t
    if (cooldown < rayFrequency) return
    cooldown = 0

    const pointerInfo = PrimaryPointerInfo.getOrCreateMutable(engine.RootEntity)
    let dir = pointerInfo.worldRayDirection

    raycastSystem.registerGlobalDirectionRaycast(
      {
        entity: engine.CameraEntity,
        opts: {
          queryType: RaycastQueryType.RQT_HIT_FIRST,
          direction: dir,
        },
      },
      function (raycastResult) {
        let result = raycastResult.hits[0]

        // do something in the hit position
        if (result && result.position) {
          console.log("x:", result.position.x, ", y:", result.position.y, ", z:", result.position.z)
        }

        // do something with the hit entity
        const entity = result.entityId as Entity
        if (entity) {
          console.log("entity: ", entity)
        }
      }
    )
}

```

{% hint style="info" %}
**💡 Sugestão**: Neste exemplo, utilizamos o botão principal (E) para acionar o raycast. Não utilizamos o botão do ponteiro (clique esquerdo), porque, por predefinição, clicar e arrastar também altera o ângulo da câmara. Se quiser impedir que a câmara rode enquanto arrasta, pode utilizar uma [Virtual Camera](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/camera.md) para definir o ângulo da câmara como fixo.
{% endhint %}

## Sintaxe avançada

### Criar um componente Raycast

Um componente Raycast descreve o raio invisível utilizado para consultar as entidades que interceta. O raio é traçado a partir da posição da entidade, conforme definido pelo componente Transform e afetado pela transformação de quaisquer entidades-pai. A direção pode ser definida de várias formas,

Os raios são definidos com os seguintes dados:

* `direction`: um objeto que contém um campo `$case` para selecionar o tipo de direção e um campo adicional, que depende desse tipo e determina a direção. Os valores aceites são `$case`:
  * `'localDirection'`: uma direção relativa ao sentido para a frente da entidade, também afetada pela transformação de quaisquer entidades-pai. É útil para detetar obstáculos à frente de veículos, respeitando a orientação destes. A rotação é definida pelo campo `localDirection` como um `Vector3` que descreve uma rotação.
  * `'globalDirection'`: ignora a rotação da entidade e aponta numa direção como se a rotação da entidade fosse 0. É útil, por exemplo, para apontar sempre para baixo. A rotação é definida pelo campo `globalDirection` como um `Vector3` que descreve uma rotação.
  * `'globalTarget'`: traça uma linha entre a posição da entidade e uma posição-alvo global na cena. Ignora a rotação da entidade. É útil para criar jogos de defesa de torres, em que a torre de cada torre pode apontar para uma coordenada precisa no espaço. O alvo é definido pelo campo `globalTarget` como um `Vector3` que descreve a posição global.
  * `'targetEntity'`: traça uma linha entre a posição da entidade e a posição de uma segunda entidade-alvo. Ignora a rotação de ambas as entidades. O alvo é definido pelo campo `targetEntity` que contém uma referência à entidade.
* `maxDistance`: *número* para definir o comprimento do raio a traçar.
* `queryType`: *valor da enumeração RaycastQueryType* para definir se o raio devolverá todas as entidades atingidas ou apenas a primeira. Estão disponíveis as seguintes opções:
  * `RaycastQueryType.RQT_HIT_FIRST`: devolve apenas a primeira entidade atingida, a partir do ponto de origem.
  * `RaycastQueryType.RQT_QUERY_ALL`: devolve todas as entidades atingidas, desde a origem até à distância máxima do raio.
* `collisionMask`: deteta colisões apenas com determinadas camadas de colisão. Utilize esta opção com uma camada de colisão personalizada ou para detetar apenas a camada de física ou de eventos do ponteiro. Consulte [camadas de colisão](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md#collision-layers). Por predefinição, o valor é `ColliderLayer.CL_POINTER | ColliderLayer.CL_PHYSICS`.
* `originOffset`: em vez de iniciar o raycast na posição de origem da entidade, adicione um deslocamento para iniciar a consulta numa posição relativa. Por exemplo, pode utilizar um pequeno deslocamento para evitar que o raio colida com o próprio modelo 3D da entidade.
* `continuous`: se for true, executa continuamente uma consulta raycast em cada frame. Se for false, o raio será utilizado apenas no frame atual. Por predefinição, este valor é false.

{% hint style="warning" %}
**📔 Nota**: A `continuous` deve ser utilizada com cautela, uma vez que executar uma consulta de raycast em cada frame pode ter um custo de desempenho muito elevado. Sempre que possível, utilize um sistema (ou a função `interval` da biblioteca Utils) para executar consultas de raycast em intervalos regulares e mais espaçados. Consulte [raycasting recorrente](#recurrent-raycasting).
{% endhint %}

O exemplo seguinte utiliza uma rotação global para determinar a direção e devolve apenas a primeira entidade atingida no frame em que o raio é enviado.

```typescript
const entity1 = engine.addEntity()

Transform.create(entity1, {
  position: Vector3.create(8, 1, 0)
})

Raycast.createOrReplace(entity1, {
  direction: {
    $case: "globalDirection",
    globalDirection: Vector3.create(0, 0, 1)
  },
  maxDistance: 16,
  queryType: RaycastQueryType.RQT_HIT_FIRST
})
```

O exemplo abaixo lança um raio na direção para a qual a entidade está virada, devolvendo apenas o primeiro elemento atingido. Isto acontece continuamente. Também inclui um pequeno desvio de 0.5 para impedir que o raio atinja o collider da própria entidade.

```typescript
const entity1 = engine.addEntity()

Transform.create(entity1, {
  position: Vector3.create(8, 1, 0)
})

Raycast.createOrReplace(entity1, {
  direction: {
    $case: "localDirection",
    localDirection: Vector3.Forward()
  },
  maxDistance: 16,
  queryType: RaycastQueryType.RQT_HIT_FIRST,
  originOffset: Vector3.create(0.5, 0, 0),
  continuous: true
})
```

Este exemplo traça um raio entre duas entidades. Devolve todas as entidades atingidas ao longo do percurso.

```ts
const entity1 = engine.addEntity()

Transform.create(entity1, {
  position: Vector3.create(8, 1, 0)
})

const entity2 = engine.addEntity()

Transform.create(entity2, {
  position: Vector3.create(0, 1, 8)
})

Raycast.createOrReplace(entity1, {
  direction: {
    $case: "targetEntity",
    targetEntity: entity2
  },
  maxDistance: 16,
  queryType: RaycastQueryType.RQT_QUERY_ALL
})
```

### Componente de resultados do Raycast

{% hint style="warning" %}
**📔 Nota**: A forma mais fácil de lidar com os resultados de raycast é usar `raycastSystem`, e registar uma função de callback como parte da mesma instrução que cria o raio. O componente`RaycastResult` é utilizado internamente por essa interface, mas também está disponível para permitir uma lógica personalizada mais avançada.
{% endhint %}

Depois de criar um componente Raycast, a entidade à qual este componente é adicionado terá um componente `RaycastResult` . Este componente inclui informações sobre quaisquer impactos do raio. Configure um sistema para verificar estes dados.

O componente `RaycastResult` contém os seguintes dados:

* `globalOrigin`: A posição de origem do raio, relativa à cena.
* `direction`: A direção global para a qual o raio apontava, como um `Vector3`.
* `hits`: Uma matriz com um objeto para cada entidade atingida. Se nenhuma entidade tiver sido atingida, a matriz fica vazia. Se o raycast tiver utilizado `RaycastQueryType.RQT_HIT_FIRST`, esta matriz conterá apenas um objeto.

Cada objeto na matriz `hits` inclui:

* `entityId`: O número de ID da entidade atingida pelo raio.
* `meshName`: *String* com o nome interno da malha específica do modelo 3D atingida. Isto é útil quando um modelo 3D é composto por várias malhas.
* `position`: *Vector3* para a posição em que o raio intersectou a entidade atingida (em relação à cena)
* `length`: Comprimento do raio desde a sua origem até à posição em que ocorreu a colisão com a entidade.
* `normalHit`: *Vector3* para a normal da superfície atingida no espaço global.
* `globalOrigin`: *Vector3* para a posição de origem do raio (em relação à cena)
* `direction`: A direção global para a qual o raio apontava, como um `Vector3`.

O exemplo abaixo mostra como pode aceder aos resultados de uma entidade individual usando um sistema:

```typescript

const rayEntity = engine.addEntity()

Transform.create(rayEntity, {
  position: Vector3.create(8, 1, 0)
})

// devolver todas as entidades
Raycast.createOrReplace(rayEntity, {
  direction: {
    $case: "globalDirection",
    globalDirection: Vector3.create(0, 0, 1)
  },
  maxDistance: 16,
  queryType: RaycastQueryType.RQT_QUERY_ALL
})

engine.addSystem(() => {
  const rayResult = RaycastResult.get(rayEntity)
  console.log(rayResult.hits)
})
```

O exemplo seguinte mostra como pode aceder aos componentes `RaycastResult` de todas as entidades da cena, usando uma [consulta de componentes](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md).

```typescript
engine.addSystem(() => {
  for (const [_, result] of engine.getEntitiesWith(RaycastResult)) {
    console.log(result.hits)
  }
})
```

{% hint style="warning" %}
**📔 Nota**: Os resultados de um raycast não chegam no mesmo tick do ciclo de jogo em que criou o raycast. Os resultados podem demorar um ou vários ticks a chegar.
{% endhint %}

Numa cena em que utiliza vários tipos de raios para diferentes fins (como procura de caminhos, verificação da linha de visão, trajetória de projéteis, etc.), poderá querer utilizar diferentes [camadas de colisão](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md#collision-layers), para evitar calcular colisões irrelevantes.

{% hint style="info" %}
**💡 Sugestão**: Para ver um exemplo funcional de raycasting, consulte [`77,-1-raycast-unit-tests`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/77,-1-raycast-unit-tests) cena de teste que verifica o comportamento do raycast através de `@dcl/sdk/testing` testes unitários nas formas `localDirection`, `globalDirection`, `globalTarget` e `targetEntity` de direção, incluindo raios lançados a partir de pais transformados. Para ver como se comportam as camadas de Collider que um raio pode atingir, consulte [`5,5-collider-layers`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/5,5-collider-layers).
{% endhint %}


---

# 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-pt/scenes-sdk7/interatividade/raycasting.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.
