---
title: "Astra.GuiAccess"
version: snapshot-2026-10-06
engineGeneration: astra-current
language: C#
status: semantic-reference
runtimeVerified: false
platformEvidence: []
url: https://astraengine.com.br/pt-br/snapshot-2026-10-06/api/astra-guiaccess/
---

# Astra.GuiAccess

UI in this Play session. Preview/Play owns a copy of the authored .aeui.

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

:::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
class Astra.GuiAccess
```

UI in this Play session. Preview/Play owns a copy of the authored .aeui.

## Onde acessar este tipo

Editor → **Interface** → documento .aeui; cena → objeto **Canvas UI**. Dentro de um Behavior, **Gui.ForCanvas(owner)** seleciona a instância, **Find/TryFind** localiza o elemento e **Poll** consome eventos. Gui é a propriedade protegida herdada de Behavior; use ForCanvas para escolher explicitamente o proprietário. [HUD completo](/pt-br/snapshot-2026-10-06/ui/hud-coracoes/).

## Roadmap e uso

[Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/): 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-8a32e6787d7f9f1d) | Method |
| [Create](#member-78d2fb7b33c01fab) | Method |
| [Find](#member-605984e11ec24da8) | Method |
| [ForCanvas](#member-9d610ce258bc3963) | Method |
| [Poll](#member-2f590c02865ae7ad) | Method |
| [TryFind](#member-0c31ca559ee40286) | Method |
| [Canvas](#member-ee60f115b1991dcd) | Property |
| [Diagnostic](#member-297acd0258c2478d) | Property |
| [Input](#member-a85de5e6fe1b7b80) | Property |
| [InstanceId](#member-856c198f848bef84) | Property |

<h3 id="member-8a32e6787d7f9f1d" class="astra-member">.ctor</h3>

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

UI in this Play session. Preview/Play owns a copy of the authored .aeui.

**Caminho:** Interface / Canvas UI → documento → elemento; use o contexto Gui.ForCanvas em Behavior.

**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:** [Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

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

<h3 id="member-78d2fb7b33c01fab" class="astra-member">Create</h3>

```csharp
public Astra.GuiElement Create(Astra.GuiKind kind, Astra.GuiElement parent = default(Astra.GuiElement), string name = "")
```

**Caminho:** Interface / Canvas UI → documento → elemento; use o contexto Gui.ForCanvas em Behavior.

**Uso:** Cria elemento na cópia runtime da instância. GuiKind define o tipo; parent precisa pertencer ao mesmo contexto. Não grava a autoria .aeui.

**Roadmap deste membro:** [Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `kind` | `Astra.GuiKind` |  |
| `parent` | `Astra.GuiElement` |  · Opcional: `` |
| `name` | `string` |  · Opcional: `` |

<h3 id="member-605984e11ec24da8" class="astra-member">Find</h3>

```csharp
public Astra.GuiElement Find(string name)
```

**Caminho:** Interface / Canvas UI → documento → elemento; use o contexto Gui.ForCanvas em Behavior.

**Uso:** Busca nome exato e entrega handle desta instância; lança erro se ausente. Resolva em Start e conserve enquanto a instância estiver viva.

**Roadmap deste membro:** [Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

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

<h3 id="member-9d610ce258bc3963" class="astra-member">ForCanvas</h3>

```csharp
public Astra.GuiAccess ForCanvas(Astra.GameObject owner, ulong componentInstance = 0)
```

**Caminho:** Interface / Canvas UI → documento → elemento; use o contexto Gui.ForCanvas em Behavior.

**Uso:** Escolhe a UI do objeto proprietário e, quando informado, a instância exata do componente. Não passa um GuiElement como proprietário.

**Roadmap deste membro:** [Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `owner` | `Astra.GameObject` |  |
| `componentInstance` | `ulong` |  · Opcional: `0` |

<h3 id="member-2f590c02865ae7ad" class="astra-member">Poll</h3>

```csharp
public bool Poll(out Astra.GuiEvent message)
```

**Caminho:** Interface / Canvas UI → documento → elemento; use o contexto Gui.ForCanvas em Behavior.

**Uso:** Retira um evento da fila. Use while, filtre Kind e identifique Element. Mantenha um consumidor da fila por Canvas.

**Roadmap deste membro:** [Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `message` | `Astra.GuiEvent` |  · Out |

<h3 id="member-0c31ca559ee40286" class="astra-member">TryFind</h3>

```csharp
public bool TryFind(string name, out Astra.GuiElement element)
```

**Caminho:** Interface / Canvas UI → documento → elemento; use o contexto Gui.ForCanvas em Behavior.

**Uso:** Busca sem presumir sucesso; teste o bool antes de usar o out element. Útil quando o elemento é opcional.

**Roadmap deste membro:** [Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

| Parâmetro | Tipo | Contrato |
|---|---|---|
| `name` | `string` |  |
| `element` | `Astra.GuiElement` |  · Out |

<h3 id="member-ee60f115b1991dcd" class="astra-member">Canvas</h3>

```csharp
public Astra.GuiCanvas Canvas { get; set; }
```

**Caminho:** Interface / Canvas UI → documento → elemento; use o contexto Gui.ForCanvas em Behavior.

**Uso:** Apresentação da instância GUI; em cena, o componente UiCanvas é a origem da configuração. Não grava a fonte.

**Roadmap deste membro:** [Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

<h3 id="member-297acd0258c2478d" class="astra-member">Diagnostic</h3>

```csharp
public string Diagnostic { get; }
```

**Caminho:** Interface / Canvas UI → documento → elemento; use o contexto Gui.ForCanvas em Behavior.

**Uso:** Mensagem de diagnóstico da instância, útil para ação/alvo/pose inválidos. Não é um status global de todas as UI.

**Roadmap deste membro:** [Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

<h3 id="member-a85de5e6fe1b7b80" class="astra-member">Input</h3>

```csharp
public Astra.GuiInputAccess Input { get; }
```

**Caminho:** Interface / Canvas UI → documento → elemento; use o contexto Gui.ForCanvas em Behavior.

**Uso:** Estado bruto de gesto do controle (Value, Pressed, Pointer, Device). Não substitui ação do receptor.

**Roadmap deste membro:** [Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.

<h3 id="member-856c198f848bef84" class="astra-member">InstanceId</h3>

```csharp
public ulong InstanceId { get; }
```

**Caminho:** Interface / Canvas UI → documento → elemento; use o contexto Gui.ForCanvas em Behavior.

**Uso:** Identidade da instância runtime; não salve uma lease como referência autoral.

**Roadmap deste membro:** [Canvas e UI de jogo](/pt-br/snapshot-2026-10-06/ui/roadmap/). Contrato existente neste snapshot; sem tarefa individual/datada registrada nesta referência.