---
title: "Astra.PhysicsAccess"
version: snapshot-2026-10-07
engineGeneration: astra-current
language: C#
status: semantic-reference
reviewedAt: 2026-10-07
appRelease: "0.2.3-preview.20261007"
runtimeVerified: false
platformEvidence: []
url: https://astraengine.com.br/pt-br/snapshot-2026-10-07/api/astra-physicsaccess/
---

# Astra.PhysicsAccess

As consultas físicas vistas pelo projeto. Resolvidas contra o mundo de execução: um objeto destruído nunca aparece em um resultado, e a identidade devolvida já carrega geração.

**Namespace:** `Astra` · **Assembly:** `Astra.Scripting` · **Tipo:** Struct

:::note[Sobre esta referência]
Assinaturas extraídas semanticamente com Roslyn/MSBuild. Isso confirma a superfície do código deste snapshot; não comprova execução no Android. As descrições vêm dos comentários da API. Membros sem explicação ainda exigem revisão editorial.
:::

## Declaração

```csharp
readonly struct Astra.PhysicsAccess
```

As consultas físicas vistas pelo projeto. Resolvidas contra o mundo de execução: um objeto destruído nunca aparece em um resultado, e a identidade devolvida já carrega geração.

## Onde acessar este tipo

No Behavior, use **Physics**, Object.PhysicsBody(), Object.DynamicMotor() ou callbacks Collision/Trigger. Crie corpo/colisor antes; resultados de consulta não adicionam um corpo.

## Roadmap e uso

[Física 3D e motores](/pt-br/snapshot-2026-10-06/roadmap/fisica-3d/): o membro presente nesta referência pertence ao contrato atual. O roadmap registra a família; não há promessa/data individual de evolução para cada membro. Membros ainda sem explicação especializada são indicados como revisão editorial pendente.

Para ler os campos e recursos pelo caminho do editor, use [mapa de acesso](/pt-br/snapshot-2026-10-06/editor/mapa-de-acesso/).

## Membros

| Membro | Categoria |
|---|---|
| [.ctor](#member-5ccc1a314575d17a) | Method |
| [LayerByName](#member-3169ee1f77b51f0c) | Method |
| [LayerMask](#member-d4fd36fde986bdb8) | Method |
| [LayerName](#member-5b4e71a256d3fc0e) | Method |
| [Overlap](#member-6bc99104ec726482) | Method |
| [RayCast](#member-541b9f05853f498d) | Method |
| [RayCastAll](#member-4b701be1b9b461c7) | Method |
| [ShapeCast](#member-5d5fa04d28b36906) | Method |

<h3 id="member-5ccc1a314575d17a" class="astra-member">.ctor</h3>

```csharp
public PhysicsAccess(Astra.ISceneAccess scene)
```

As consultas físicas vistas pelo projeto. Resolvidas contra o mundo de execução: um objeto destruído nunca aparece em um resultado, e a identidade devolvida já carrega geração.

**Caminho:** Área de código → Behavior compilado/anexado → acesso descrito em “Onde acessar este tipo”.

**Uso:** Constrói o tipo pela assinatura declarada. Um construtor de fachada envolve um componente existente; um record de configuração só tem efeito quando atribuído ao consumidor.

**Roadmap deste membro:** [Física 3D e motores](/pt-br/snapshot-2026-10-06/roadmap/fisica-3d/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `scene` | `Astra.ISceneAccess` |  |

<h3 id="member-3169ee1f77b51f0c" class="astra-member">LayerByName</h3>

```csharp
public int LayerByName(string name)
```

Índice da camada de gameplay com esse nome, ou -1.

**Caminho:** Área de código → Behavior compilado/anexado → acesso descrito em “Onde acessar este tipo”.

**Uso:** Índice da camada de gameplay com esse nome, ou -1.

**Roadmap deste membro:** [Física 3D e motores](/pt-br/snapshot-2026-10-06/roadmap/fisica-3d/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `name` | `string` |  |

<h3 id="member-d4fd36fde986bdb8" class="astra-member">LayerMask</h3>

```csharp
public uint LayerMask(params string[] names)
```

Máscara com apenas as camadas nomeadas informadas.

**Caminho:** Área de código → Behavior compilado/anexado → acesso descrito em “Onde acessar este tipo”.

**Uso:** Máscara com apenas as camadas nomeadas informadas.

**Roadmap deste membro:** [Física 3D e motores](/pt-br/snapshot-2026-10-06/roadmap/fisica-3d/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `names` | `string[]` |  |

<h3 id="member-5b4e71a256d3fc0e" class="astra-member">LayerName</h3>

```csharp
public string LayerName(int layer)
```

**Caminho:** Área de código → Behavior compilado/anexado → acesso descrito em “Onde acessar este tipo”.

**Uso:** Chame pelo acesso deste tipo indicado acima, com argumentos da assinatura. O efeito especializado deste membro ainda precisa de revisão editorial individual; não deduza equivalência com Unity/Godot pelo nome.

**Roadmap deste membro:** [Física 3D e motores](/pt-br/snapshot-2026-10-06/roadmap/fisica-3d/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `layer` | `int` |  |

<h3 id="member-6bc99104ec726482" class="astra-member">Overlap</h3>

```csharp
public System.Collections.Generic.IReadOnlyList<Astra.RayHit> Overlap(Astra.ShapeQuery shape, System.Numerics.Vector3 origin, out bool truncated, Astra.QueryFilter? filter = null, int capacity = 32)
```

**Caminho:** Área de código → Behavior compilado/anexado → acesso descrito em “Onde acessar este tipo”.

**Uso:** Chame pelo acesso deste tipo indicado acima, com argumentos da assinatura. O efeito especializado deste membro ainda precisa de revisão editorial individual; não deduza equivalência com Unity/Godot pelo nome.

**Roadmap deste membro:** [Física 3D e motores](/pt-br/snapshot-2026-10-06/roadmap/fisica-3d/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `shape` | `Astra.ShapeQuery` |  |
| `origin` | `System.Numerics.Vector3` |  |
| `truncated` | `bool` |  · Out |
| `filter` | `Astra.QueryFilter?` |  · Opcional: `` |
| `capacity` | `int` |  · Opcional: `32` |

<h3 id="member-541b9f05853f498d" class="astra-member">RayCast</h3>

```csharp
public Astra.RayHit? RayCast(System.Numerics.Vector3 origin, System.Numerics.Vector3 direction, Astra.QueryFilter? filter = null)
```

O acerto mais próximo ao longo de direction, cujo comprimento é o alcance. Nulo quando nada foi acertado.

**Caminho:** Área de código → Behavior compilado/anexado → acesso descrito em “Onde acessar este tipo”.

**Uso:** O acerto mais próximo ao longo de direction, cujo comprimento é o alcance. Nulo quando nada foi acertado.

**Roadmap deste membro:** [Física 3D e motores](/pt-br/snapshot-2026-10-06/roadmap/fisica-3d/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `origin` | `System.Numerics.Vector3` |  |
| `direction` | `System.Numerics.Vector3` |  |
| `filter` | `Astra.QueryFilter?` |  · Opcional: `` |

<h3 id="member-4b701be1b9b461c7" class="astra-member">RayCastAll</h3>

```csharp
public System.Collections.Generic.IReadOnlyList<Astra.RayHit> RayCastAll(System.Numerics.Vector3 origin, System.Numerics.Vector3 direction, out bool truncated, Astra.QueryFilter? filter = null, int capacity = 32)
```

Todos os acertos, do mais próximo ao mais distante. Devolve a lista efetivamente copiada; truncated diz se havia mais acertos do que o buffer comportava.

**Caminho:** Área de código → Behavior compilado/anexado → acesso descrito em “Onde acessar este tipo”.

**Uso:** Todos os acertos, do mais próximo ao mais distante. Devolve a lista efetivamente copiada; truncated diz se havia mais acertos do que o buffer comportava.

**Roadmap deste membro:** [Física 3D e motores](/pt-br/snapshot-2026-10-06/roadmap/fisica-3d/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `origin` | `System.Numerics.Vector3` |  |
| `direction` | `System.Numerics.Vector3` |  |
| `truncated` | `bool` |  · Out |
| `filter` | `Astra.QueryFilter?` |  · Opcional: `` |
| `capacity` | `int` |  · Opcional: `32` |

<h3 id="member-5d5fa04d28b36906" class="astra-member">ShapeCast</h3>

```csharp
public Astra.RayHit? ShapeCast(Astra.ShapeQuery shape, System.Numerics.Vector3 origin, System.Numerics.Vector3 direction, Astra.QueryFilter? filter = null)
```

**Caminho:** Área de código → Behavior compilado/anexado → acesso descrito em “Onde acessar este tipo”.

**Uso:** Chame pelo acesso deste tipo indicado acima, com argumentos da assinatura. O efeito especializado deste membro ainda precisa de revisão editorial individual; não deduza equivalência com Unity/Godot pelo nome.

**Roadmap deste membro:** [Física 3D e motores](/pt-br/snapshot-2026-10-06/roadmap/fisica-3d/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `shape` | `Astra.ShapeQuery` |  |
| `origin` | `System.Numerics.Vector3` |  |
| `direction` | `System.Numerics.Vector3` |  |
| `filter` | `Astra.QueryFilter?` |  · Opcional: `` |