`Class.BillboardGui` é um contêiner para objetos de UI que aparecem no espaço 3D
mas sempre de frente para a câmera. A posição do contêiner é relativa ao pai
`Class.BasePart` ou `Class.Attachment` (ou ao
`Class.BillboardGui.Adornee|Adornee`). Para `Class.BasePart|BaseParts`, a
propriedade `Class.BasePart.Position|Position` é utilizada, enquanto para
`Class.Attachment|Attachments`, a propriedade
`Class.Attachment.WorldPosition|WorldPosition` é utilizada.

<img src="/assets/ui/in-experience/BillboardGui-Diagram.jpg" width="800" alt="BillboardGui com um TextLabel descrevendo o console de tela acima do qual flutua." />

A propriedade `Class.BillboardGui.Size|Size` de um outdoor funciona ligeiramente
diferente de `Class.GuiObject.Size`. Enquanto os componentes **offset** funcionam
da mesma forma, os componentes **scale** são usados como tamanhos de stud no
espaço 3D.

Ao criar um `Class.BillboardGui` escalado em tamanho que contém um
`Class.TextLabel`, é útil ativar a propriedade
`Class.TextLabel.TextScaled|TextScaled` do rótulo para que seu texto escale
junto com a tela do outdoor à medida que a distância da câmera muda.

Observe que elementos de UI interativos, como `Class.ImageButton|ImageButtons`
e `Class.TextButton|TextButtons` dentro de um `Class.BillboardGui` só
receberão entrada do usuário se estiverem agrupados ao `Class.PlayerGui`,
tipicamente colocando o `Class.BillboardGui` dentro do `Class.StarterGui`. A
propriedade `Class.BillboardGui.Adornee|Adornee` pode ser usada para direcionar
uma peça ou anexo no mundo 3D enquanto o próprio `Class.BillboardGui` permanece
no `Class.PlayerGui`.

Veja [UI em Experiência](/ui/in-experience-containers#billboard-ui)
para um guia sobre como trabalhar com contêineres `Class.BillboardGui`.

##### Comportamento de Cache

Para ajudar a melhorar o desempenho, a aparência de um `Class.BillboardGui` é
armazenada em cache até que um dos seguintes ocorra, após o que sua
aparência será recalculada na próxima frame de renderização.

- Um descendente é adicionado ou removido do `Class.BillboardGui`.
- Uma propriedade de um descendente do `Class.BillboardGui` muda.
- Uma propriedade do `Class.BillboardGui` em si muda.


BillboardGui

Controla se os descendentes irão receber eventos de entrada. Se o
`Class.BillboardGui` contiver um `Class.GuiButton`, esse botão se tornará
clicável apenas se `Class.BillboardGui.Active|Active` estiver definido como
`true` em ambos, o `Class.BillboardGui` **e** o botão.

Observe que elementos de UI interativos, como `Class.ImageButton|ImageButtons`
e `Class.TextButton|TextButtons` dentro de um `Class.BillboardGui` só
receberão entrada do usuário se estiverem agrupados ao `Class.PlayerGui`,
tipicamente colocando o `Class.BillboardGui` dentro do `Class.StarterGui`.
A propriedade `Class.BillboardGui.Adornee|Adornee` pode ser usada para direcionar
uma peça ou anexo no mundo 3D enquanto o próprio `Class.BillboardGui` permanece
no `Class.PlayerGui`.


BillboardGui.Active

Controla se os descendentes irão receber eventos de entrada.


Define o `Class.BasePart` ou `Class.Attachment` alvo que o
`Class.BillboardGui` está posicionado em relação, sobrescrevendo a parte ou
anexo pai.


BillboardGui.Adornee

Define a parte ou anexo alvo que o `Class.BillboardGui` está
posicionado em relação.


Esta propriedade determina se o `Class.BillboardGui` sempre
renderiza acima de outros objetos 3D.

Quando definida como `false` (padrão), o `Class.BillboardGui` renderiza como
a outros conteúdos 3D e é ocultado por outros objetos 3D. Quando definida como
`true`, o `Class.BillboardGui` sempre renderiza acima do conteúdo 3D e a
aparência muda significativamente:

- As cores correspondem ao modo como aparecem dentro de um `Class.ScreenGui`.
- O texto pode aparecer mais nítido em dispositivos de alta DPI.
- `Class.BillboardGui.LightInfluence|LightInfluence` é tratado como se
  fosse `0`.
- `Class.BillboardGui.Brightness|Brightness` não tem efeito.


BillboardGui.AlwaysOnTop

Determina se o `Class.BillboardGui` será sempre renderizado acima
outros objetos 3D.


Esta propriedade determina o fator pelo qual a luz do contêiner `Class.BillboardGui`
é escalada quando
`Class.BillboardGui.LightInfluence|LightInfluence` é `0`. Por padrão,
esta propriedade é `1` e pode ser definida como qualquer número entre `0` e
`1000`. Ao modificar esta propriedade, o brilho aparente de um
`Class.BillboardGui` pode ser melhor correspondido ao seu ambiente. Por
exemplo, um outdoor de vídeo pode ser iluminado em uma sala escura aumentando
`Class.BillboardGui.Brightness|Brightness` para `10`.

Observe que `Class.BillboardGui.Brightness|Brightness` é inacessível em
Studio e não tem efeito quando `Class.BillboardGui.LightInfluence|LightInfluence` é
`1` ou `Class.BillboardGui.AlwaysOnTop|AlwaysOnTop` é `true`.


BillboardGui.Brightness

Determina o fator pelo qual a luz do contêiner `Class.BillboardGui`
é escalada quando `Class.BillboardGui.LightInfluence|LightInfluence` é `0`.


Quando definida como `true` (padrão), as porções de `Class.GuiObject|GuiObjects`
que estão fora das bordas do canvas do `Class.BillboardGui` não serão
desenhadas.

Mesmo quando esta propriedade é `false`, `Class.GuiObject|GuiObjects` que estão
**completamente** fora do canvas não serão renderizados.


BillboardGui.ClipsDescendants

Se as porções de `Class.GuiObject|GuiObjects` que estão fora das
bordas do canvas do `Class.BillboardGui` serão desenhadas.


A distância atual em studs que o `Class.BillboardGui` está da
câmera do jogador. Um evento de mudança não é disparado para esta propriedade
exceto se `Class.BillboardGui.DistanceStep|DistanceStep` for maior que `0`.


BillboardGui.CurrentDistance

A distância atual em studs que o `Class.BillboardGui` está da
câmera do jogador.


Determina a distância em studs na qual o `Class.BillboardGui` irá
parar de escalar maior em tamanho em relação à câmera atual do jogador, com
um padrão de `0`. Se a
`Class.BillboardGui.CurrentDistance|CurrentDistance` do
`Class.BillboardGui` estiver abaixo deste valor, ele não escalará maior do que
faria a essa distância.


BillboardGui.DistanceLowerLimit

Determina a distância em studs na qual o `Class.BillboardGui` irá
parar de escalar maior em tamanho.


Determina os incrementos e decrementos de tamanho `Class.BillboardGui.CurrentDistance|CurrentDistance`
em studs conforme a câmera do jogador se move mais perto e
mais longe do `Class.BillboardGui`. A propriedade tem como padrão `0`.


BillboardGui.DistanceStep

Determina os incrementos e decrementos de tamanho `Class.BillboardGui.CurrentDistance|CurrentDistance`
em studs conforme a câmera do jogador se move mais perto e
mais longe do `Class.BillboardGui`.


Determina a distância em studs na qual o `Class.BillboardGui` irá
parar de escalar menor em tamanho em relação à câmera atual do jogador. Se
a `Class.BillboardGui.CurrentDistance|CurrentDistance` do
`Class.BillboardGui` estiver acima deste valor, ele não escalará menor do que
faria a essa distância.

Esta propriedade é ignorada se o valor for menor que `0`. O valor padrão
é `-1`, o que significa que a propriedade é ignorada por padrão.


BillboardGui.DistanceUpperLimit

Determina a distância em studs na qual o `Class.BillboardGui` irá
parar de escalar menor em tamanho.


Esta propriedade determina como o `Class.BillboardGui` é deslocado de seu
`Class.BillboardGui.Adornee|Adornee`, em relação à orientação da
`Class.Camera`, em unidades pela metade das dimensões da caixa
limitadora alinhada à câmera do modelo.

Veja também `Class.BillboardGui.StudsOffset|StudsOffset` que funciona
similarmente, mas usa unidades de stud, ou
`Class.BillboardGui.ExtentsOffsetWorldSpace|ExtentsOffsetWorldSpace` que
funciona de forma semelhante exceto que a orientação de deslocamento é em relação
aos eixos globais.


BillboardGui.ExtentsOffset

Determina como o `Class.BillboardGui` é deslocado de seu
`Class.BillboardGui.Adornee|Adornee`, em relação à orientação da
`Class.Camera`, em unidades pela metade das dimensões da caixa
limitadora alinhada à câmera do modelo.


Esta propriedade determina como o `Class.BillboardGui` é deslocado de seu
`Class.BillboardGui.Adornee|Adornee`, em relação aos eixos globais, em
unidades pela metade das dimensões da caixa
limitadora alinhada ao modelo.

Veja também `Class.BillboardGui.StudsOffset|StudsOffset` que funciona
similarmente, mas usa unidades de stud, ou
`Class.BillboardGui.ExtentsOffset|ExtentsOffset` que funciona de forma semelhante
exceto que a orientação de deslocamento é em relação à `Class.Camera`.


BillboardGui.ExtentsOffsetWorldSpace

Determina como o `Class.BillboardGui` é deslocado de seu
`Class.BillboardGui.Adornee|Adornee`, em relação aos eixos globais, em
unidades pela metade das dimensões da caixa
limitadora alinhada ao modelo.


Controla quanto o `Class.BillboardGui` é influenciado pela iluminação
ambiental, em uma faixa de `0` a `1`. Definir isso como `1` significa que
a iluminação ao redor tem controle completo sobre a aparência, enquanto
definir como `0` significa que a iluminação não tem efeito.


BillboardGui.LightInfluence

Controla quanto o `Class.BillboardGui` é influenciado pela iluminação
ambiental.


Esta propriedade controla quão longe da câmera o `Class.BillboardGui`
será exibido antes que ele pare de renderizar. Um valor de `0` ou `inf`
(padrão) significa que não há limite e ele será renderizado infinitamente longe.

Para `Class.BillboardGui|BillboardGuis` que aparecem ao ar livre, é
recomendado que `Class.BillboardGui.MaxDistance|MaxDistance` seja
suficientemente alto para garantir que a UI do contêiner seja
suficientemente pequena na tela quando aparecer ou desaparecer,
minimizando o efeito repentino de pop-in/out.


BillboardGui.MaxDistance

Controla quão longe o `Class.BillboardGui` pode ser exibido antes que
ele pare de renderizar.


Usado por scripts para esconder o `Class.BillboardGui` de um jogador específico.

Para esconder um `Class.BillboardGui` de mais de um jogador, coloque-o no
`Class.StarterGui` e use um script para definir a propriedade
`Class.BillboardGui.Enabled|Enabled` de acordo com se o
`Class.Players.LocalPlayer|LocalPlayer` deve ser capaz de vê-lo. A
propriedade `Class.BillboardGui.Adornee|Adornee` pode ser usada para anexar o
`Class.BillboardGui` a um `Class.BasePart` ou `Class.Attachment` no
`Class.Workspace`, em vez de agrupá-lo.


BillboardGui.PlayerToHideFrom

Usado por scripts para esconder o `Class.BillboardGui` de um jogador específico.


Controla o tamanho que o `Class.BillboardGui` terá na tela.
Diferente de `Class.GuiObject.Size`, os componentes de
[scale](/ui/position-and-size#size) desta propriedade
definem o tamanho do outdoor em studs no espaço 3D.


BillboardGui.Size

Controla o tamanho que o `Class.BillboardGui` terá na tela.


Um deslocamento 2D em unidades relativas ao tamanho que age como um ponto de ânclagem. Isso
pode ser usado de forma semelhante à propriedade `Class.GuiObject.AnchorPoint`, mas
os valores são diferentes.

<table size="small">
<thead>
<th>Offset de Tamanho</th>
<th>Explicação</th>
</thead>
<tbody>
<tr>
<td><code>0, 0</code></td>
<td>O padrão no qual a UI será ancorada em seu centro.</td>
</tr>
<tr>
<td><code>0.5, 0.5</code></td>
<td>A UI será ancorada no canto inferior esquerdo.</td>
</tr>
<tr>
<td><code>0.5, -0.5</code></td>
<td>A UI será ancorada no canto superior esquerdo.</td>
</tr>
<tr>
<td><code>-0.5, 0.5</code></td>
<td>A UI será ancorada no canto superior direito.</td>
</tr>
<tr>
<td><code>-0.5, -0.5</code></td>
<td>A UI será ancorada no canto inferior direito.</td>
</tr>
</tbody>
</table>

Veja também `Class.BillboardGui.StudsOffset|StudsOffset`,
`Class.BillboardGui.StudsOffsetWorldSpace|StudsOffsetWorldSpace`,
`Class.BillboardGui.ExtentsOffset|ExtentsOffset`, e
`Class.BillboardGui.ExtentsOffsetWorldSpace|ExtentsOffsetWorldSpace` que
são propriedades de deslocamento que funcionam no espaço 3D.


BillboardGui.SizeOffset

Um deslocamento 2D em unidades relativas ao tamanho que age como um ponto de ânclagem.


Esta propriedade determina como o `Class.BillboardGui` é deslocado de seu
`Class.BillboardGui.Adornee|Adornee` em studs, em relação à
orientação da `Class.Camera`.

Veja também `Class.BillboardGui.StudsOffsetWorldSpace|StudsOffsetWorldSpace`
que funciona de forma semelhante, exceto que a orientação de deslocamento é em relação
aos eixos globais.


BillboardGui.StudsOffset

Determina como o `Class.BillboardGui` é deslocado de seu
`Class.BillboardGui.Adornee|Adornee` em studs, em relação à
orientação da `Class.Camera`.


Esta propriedade determina como o `Class.BillboardGui` é deslocado de seu
`Class.BillboardGui.Adornee|Adornee` em studs, em relação aos eixos
globais.

Veja também `Class.BillboardGui.StudsOffset|StudsOffset` que funciona
de forma semelhante, exceto que a orientação de deslocamento é em relação à `Class.Camera`.


BillboardGui.StudsOffsetWorldSpace

Determina como o `Class.BillboardGui` é deslocado de seu
`Class.BillboardGui.Adornee|Adornee` em studs, em relação aos eixos
globais.


Um contêiner para `Class.GuiObject|GuiObjects` que renderiza em um espaço 3D de frente
para a câmera.


**LayerCollector** é a classe base de contêineres de UI 2D que renderiza
`Class.GuiObject` descendentes, como `Class.ScreenGui`.

Para melhorias de desempenho, a aparência de um `Class.LayerCollector` é
cacheada até que um dos seguintes eventos ocorra:

- Um descendente é adicionado ou removido.
- Uma propriedade de um descendente muda.
- Uma propriedade do próprio `Class.LayerCollector` muda.

LayerCollector:GetLayoutNodeTree

LayerCollector

Alterna a visibilidade deste `Class.LayerCollector`. Quando `false`, o
conteúdo da UI não será renderizado, não processará entrada do usuário, ou
atualizará em resposta a alterações.

LayerCollector.Enabled

Alterna a visibilidade deste `Class.LayerCollector`.

Quando definido como `false` e este `Class.LayerCollector` é um filho direto de
`Class.StarterGui`, ele será clonado no `Class.PlayerGui` de cada jogador
apenas uma vez e não será deletado quando o personagem do jogador renascer.

Quando definido como `true` (padrão), ou se este `Class.LayerCollector` é um
descendente **indireto** de `Class.StarterGui`, ele será clonado no `Class.PlayerGui`
de cada jogador quando seu personagem renascer, e se deletará quando o
personagem do jogador renascer novamente.

LayerCollector.ResetOnSpawn

Determina se o `Class.LayerCollector` é redefinido (deletado e
re-clonado no `Class.PlayerGui` do jogador) toda vez que o personagem do jogador
renasce.

Controla como `Class.GuiObject.ZIndex` se comporta em todos os descendentes deste
`Class.LayerCollector`.

Com `Enum.ZIndexBehavior.Sibling` (padrão), os filhos sempre renderizam acima
de seus pais, e o `Class.GuiObject.ZIndex|ZIndex` é usado para decidir
a ordem na qual os filhos de um único objeto UI renderizarão uns sobre os
outros.

`Enum.ZIndexBehavior.Global` classifica todos os descendentes de acordo com o
`Class.GuiObject.ZIndex|ZIndex`, e depois quebra empates usando a
ordem hierárquica. Como resultado, os descendentes de um `Class.GuiObject` precisam ter um
valor de `Class.GuiObject.ZIndex|ZIndex` que seja pelo menos tão alto quanto o
e do pai, ou eles renderizarão abaixo do seu pai.


LayerCollector.ZIndexBehavior

Controla como `Class.GuiObject.ZIndex` se comporta em todos os descendentes deste
`Class.LayerCollector`.


A classe base de contêineres de UI 2D que renderiza `Class.GuiObject|GuiObjects`
 em camadas.

`Class.GuiBase2d` é uma classe abstrata herdada por 2D
`Class.GuiObject|GuiObjects`.


Este evento dispara quando a seleção do gamepad se move para, sai ou muda
dentro do `Class.GuiBase2d` conectado ou qualquer descendente
`Class.GuiObject|GuiObjects`. Quando o destaque da seleção se move para um
`Class.GuiObject`, o evento se propaga desse `Class.GuiObject` para todos os
seus ancestrais, informando-os que a seleção foi
mudada/entrou/saiu para um `Class.GuiObject` em sua árvore de descendentes.


GuiBase2d.SelectionChanged

amISelected

Verdadeiro se a nova seleção corresponder ao GuiBase2d anexado.


previousSelection

newSelection

Dispara quando a seleção do gamepad se move para, sai ou muda dentro do
`Class.GuiBase2d` conectado ou qualquer descendente
`Class.GuiObject|GuiObjects`.


GuiBase2d

`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` é uma propriedade somente de leitura
que fornece a posição na tela de um elemento `Class.GuiBase2d`
em pixels. Isso representa a posição real em pixels na qual um elemento
é renderizado como resultado dos tamanhos e posições de seus ancestrais. Note que
`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` sempre representa o
canto superior esquerdo do elemento `Class.GuiBase2d`.

Se o `Class.GuiBase2d` estiver em um `Class.ScreenGui`, a
propriedade `Class.GuiBase2d.AbsolutePosition|AbsolutePosition` usa o
sistema de coordenadas de viewport `Enum.ScreenInsets|CoreUISafeInsets`. A
origem deste sistema de coordenadas está localizada no canto inferior esquerdo da
barra superior do Roblox. Note que este é o mesmo sistema de coordenadas utilizado
pela propriedade `Class.InputObject.Position`.

<img src="/assets/engine-api/classes/GuiBase2d/AbsolutePositionCoordinateSystem.png" width="840" alt="Diagrama mostrando a origem do sistema de coordenadas AbsolutePosition." />

Veja também `Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation` e
`Class.GuiBase2d.AbsoluteSize|AbsoluteSize`.


GuiBase2d.AbsolutePosition

Descreve a posição real na tela de um elemento `Class.GuiBase2d`, em
pixels.


`Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation` é uma propriedade somente de leitura
que descreve a rotação real na tela de um elemento `Class.GuiBase2d`, em graus. Ela
**não** realiza verificações de limites, portanto seu valor
pode não estar na faixa de `0` a `360`.

Veja também `Class.GuiBase2d.AbsolutePosition|AbsolutePosition` e
`Class.GuiBase2d.AbsoluteSize|AbsoluteSize`.


GuiBase2d.AbsoluteRotation

Descreve a rotação real na tela de um elemento `Class.GuiBase2d`, em
graus.


`Class.GuiBase2d.AbsoluteSize|AbsoluteSize` é uma propriedade somente de leitura que
descreve o tamanho real na tela de um elemento `Class.GuiBase2d`, em
pixels.

Veja também `Class.GuiBase2d.AbsolutePosition|AbsolutePosition` e
`Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation`.


GuiBase2d.AbsoluteSize

Descreve o tamanho real na tela de um elemento `Class.GuiBase2d`, em
pixels.


Quando definido como `true`, a localização será aplicada a este `Class.GuiBase2d`
e seus descendentes. As entradas usadas para localização são o mesmo conjunto de
entradas retornadas por `Class.LocalizationService:GetTableEntries()`. Entradas
com `Class.GuiBase2d.AutoLocalize|AutoLocalize` ativado são automaticamente
re-traduzidas após o carregamento da tabela em nuvem, se necessário.

Veja também `Class.GuiBase2d.RootLocalizationTable|RootLocalizationTable`.


GuiBase2d.AutoLocalize

Quando definido como `true`, a localização será aplicada a este `Class.GuiBase2d`
e seus descendentes.


Esta propriedade é automaticamente definida como verdadeira quando a tabela de localização
`Class.LocalizationTable.Root` direciona para este objeto ou um ancestral deste
objeto. `Class.LocalizationTable|LocalizationTables` com sua propriedade
`Class.LocalizationTable.Root` apontando para uma instância irão
localizar todos os `Class.TextLabel.TextButton` que são descendentes da raiz
instância.


GuiBase2d.Localize

Definido automaticamente como verdadeiro quando a tabela de localização
`Class.LocalizationTable.Root` direciona para este objeto ou um ancestral deste
objeto.


Uma referência a uma `Class.LocalizationTable` a ser usada para aplicar
localização automatizada a este `Class.GuiBase2d` e seus descendentes.
`Class.GuiBase2d.AutoLocalize|AutoLocalize` deve ser definido como `true` no
`Class.GuiBase2d` e seus ancestrais para que a localização automatizada seja
aplicada.

Você pode definir isso para referenciar uma `Class.LocalizationTable` em qualquer lugar no
`Class.DataModel`. O objeto `Class.GuiBase2d` e todos os seus filhos
irão tentar usar essa tabela de localização específica e seus ancestrais
para substituição automática de texto antes de usar as tabelas sob
`Class.LocalizationService` em uma ordem indefinida e a tabela em nuvem.

Se não houver tradução disponível na tabela referenciada, ela procurará
por uma tradução no pai dessa tabela, se também for uma
`Class.LocalizationTable`, e assim por diante.

Veja também `Class.LocalizationService:GetTableEntries()` que explica como a
`Class.GuiBase2d.RootLocalizationTable|RootLocalizationTable` é usada
para localização automatizada.


GuiBase2d.RootLocalizationTable

Uma referência a uma `Class.LocalizationTable` a ser usada para aplicar
localização automatizada a este `Class.GuiBase2d` e seus descendentes.


Personaliza o comportamento de seleção do gamepad na direção para baixo.


GuiBase2d.SelectionBehaviorDown

Personaliza o comportamento de seleção do gamepad na direção para a esquerda.


GuiBase2d.SelectionBehaviorLeft

Personaliza o comportamento de seleção do gamepad na direção para a direita.


GuiBase2d.SelectionBehaviorRight

Personaliza o comportamento de seleção do gamepad na direção para cima.


GuiBase2d.SelectionBehaviorUp

Permite a personalização de como a seleção do gamepad pode se mover entre
os botões, que são descendentes do grupo de seleção, deixar o grupo,
e selecionar outros botões.

Definindo `Class.GuiBase2d.SelectionGroup|SelectionGroup` como `true` expõe
as propriedades `Class.GuiBase2d.SelectionBehaviorUp|SelectionBehaviorUp`,
`Class.GuiBase2d.SelectionBehaviorDown|SelectionBehaviorDown`,
`Class.GuiBase2d.SelectionBehaviorLeft|SelectionBehaviorLeft`, e
`Class.GuiBase2d.SelectionBehaviorRight|SelectionBehaviorRight`.
Para esses comportamentos de seleção, uma configuração de
`Enum.SelectionBehavior.Escape` (padrão) significa que a seleção do gamepad
tenta primeiro encontrar uma seleção dentro do grupo de seleção e só se desloca
ainda mais fora, se não encontrar um botão adequado. Alternativamente, uma configuração de
`Enum.SelectionBehavior.Stop` significa que a seleção do gamepad apenas
procura dentro do grupo de seleção e não se move para fora do grupo a partir da
direção do comportamento de seleção.


GuiBase2d.SelectionGroup

Permite a personalização do movimento de seleção do gamepad.


Uma classe abstrata herdada por 2D `Class.GuiObject|GuiObjects`.


GuiBase é uma classe abstrata da qual a maioria dos objetos de interface gráfica do usuário
herdam.


GuiBase

`Instance` é a classe base para todas as classes na hierarquia de classes do Roblox
que podem fazer parte da árvore `Class.DataModel`.

Não é possível criar diretamente objetos `Instance` raiz, mas o construtor especial
`Datatype.Instance.new()` cria objetos via código, recebendo o
nome da classe como um parâmetro e retornando o objeto criado.

Demonstra como detectar mudanças na ancestralidade de uma instância conectando-se ao
`Class.Instance.AncestryChanged` evento.

O Parent do ChangingPart é definido para valores diferentes ao longo do tempo. O pai da
peça é o ancestral da peça, então o evento `Class.Instance.AncestryChanged`
será acionado sempre que mudar.


Dispara quando esta instância é reparentada ou quando qualquer um de seus
ancestrais é reparentado.

Você pode usar este evento para rastrear a exclusão de uma instância no
Studio, como exclusão manual no Explorer ou por meio de um plugin. Se
você precisar detectar quando uma instância é destruída usando
`Class.Instance:Destroy()`, use o evento `Class.Instance.Destroying`
em vez disso.

Instance.AncestryChanged

child

A instância cuja propriedade `Class.Instance.Parent|Parent` foi alterada,
que pode ser esta instância ou um ancestral mais distante, **não**
necessariamente a instância à qual o manipulador está conectado.

parent

Dispara quando a propriedade `Class.Instance.Parent` deste objeto ou um de
seus ancestrais é alterada.

Este evento dispara sempre que qualquer atributo é alterado na instância,
 incluindo quando um atributo é definido como `nil`. O nome do atribuito que foi
alterado é passado para a função conectada.

Por exemplo, o seguinte trecho de código conecta a função
`attributeChanged()` para disparar sempre que um dos atributos do
objeto muda:

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part

local function attributeChanged(attributeName)
	print(attributeName, "mudou")
end

part.AttributeChanged:Connect(attributeChanged)
```
Veja também `Class.Instance:GetAttributeChangedSignal()` que retorna um
evento que dispara quando um atributo específico é alterado.

Instance.AttributeChanged

attribute

Dispara sempre que um atributo é alterado na `Class.Instance`.

Este trecho imprime os nomes dos objetos à medida que são adicionados ao Workspace:

Dispara após um objeto ser parentado a esta `Class.Instance`.

Observe que, ao usar este método em um cliente para detectar objetos
criados pelo servidor, é necessário usar `Class.Instance:WaitForChild()` ao
indexar os descendentes desses objetos. Isso ocorre porque o objeto e seus
descendentes não são garantidos a serem replicados do servidor para o cliente
simultaneamente. Por exemplo:

```
local Workspace = game:GetService("Workspace")

Workspace.ChildAdded:Connect(function(child)
	-- Use WaitForChild() já que os descendentes podem não ter sido replicados ainda
	local head = child:WaitForChild("Head")
end)
```
Observe que este evento opera apenas para filhos imediatos do
`Class.Instance`. Para um evento que captura todos os descendentes, use
`Class.Instance.DescendantAdded`.

Veja também `Class.Instance.ChildRemoved`.

Instance.ChildAdded

Dispara após um objeto ser parentado a esta `Class.Instance`.

Instance.childAdded

Este trecho imprime os nomes dos objetos à medida que são removidos do
Workspace:

Dispara após um filho ser removido deste `Class.Instance`.

Removido refere-se a quando o pai de um objeto é alterado de
este `Class.Instance` para algo diferente deste `Class.Instance`. Observe que,
este evento também disparará quando um filho for destruído (usando
`Class.Instance:Destroy()`), já que a função de destruição define o pai de um objeto como `nil`.

Este evento opera apenas para filhos imediatos do `Class.Instance`.
Para um evento que captura todos os descendentes, use
`Class.Instance.DescendantRemoving`.

Veja também `Class.Instance.ChildAdded`.

Instance.ChildRemoved

Dispara após um filho ser removido deste `Class.Instance`.

Este exemplo a seguir imprimirá o nome de qualquer objeto que for adicionado ao
Espaço de Trabalho:

Este evento dispara após um descendente ser adicionado à `Class.Instance`.

Como ele dispara para cada descendente, parentear um objeto à
`Class.Instance` fará com que o evento dispare para este objeto e todos os seus
descendentes individualmente.

Se você está apenas preocupado com os **filhos diretos** do
`Class.Instance`, use `Class.Instance.ChildAdded` em vez disso.

Veja também `Class.Instance.DescendantRemoving`.

Instance.DescendantAdded

descendant

Dispara após um descendente ser adicionado à `Class.Instance`.

O seguinte exemplo imprime o nome de qualquer descendente enquanto está sendo removido
do Workspace:

Este evento dispara **imediatamente antes** de o pai `Class.Instance`
ser alterado de forma que uma instância **descendente** não será mais um
descendente. `Class.Instance:Destroy()|Destroy()` altera o
`Class.Instance.Parent|Parent` de uma instância para `nil`, então chamar esse método em um
descendente do pai fará com que este evento dispare.

Como este evento dispara **antes** da remoção do descendente, o pai do
descendente permanecerá inalterado no momento da disparação deste evento. Se o
descendente também for um **filho direto** do pai, este evento disparará
antes de `Class.Instance.ChildRemoved`.

Se um descendente tiver filhos, este evento dispara primeiro com o descendente,
seguido por seus descendentes.

#### Aviso

Este evento dispara com o objeto descendente que está sendo removido.
Tentar definir o `Class.Instance.Parent|Parent` do descendente para
algo diferente falhará. Abaixo está um exemplo que demonstra isso:

```
local Workspace = game:GetService("Workspace")

Workspace.DescendantRemoving:Connect(function(descendant)
	-- Não manipule o pai do descendente nesta função!
	-- Este evento dispara POR CAUSA de a parentagem ter sido manipulada, e a alteração
	-- ainda não aconteceu
	-- Portanto, é problemático alterar o pai assim:
	descendant.Parent = game
end)

local part = Instance.new("Part")
part.Parent = Workspace
part.Parent = nil
```
Veja também `Class.Instance.DescendantAdded|DescendantAdded`.

Instance.DescendantRemoving

O `Class.Instance` que está sendo removido.

Dispara imediatamente antes de um descendente do `Class.Instance` ser removido.

Este exemplo demonstra como, ao usar o comportamento de sinal Imediato, uma
Instância sendo destruída permanece no lugar até que a função conectada faça yield.


Este exemplo demonstra como, ao usar o comportamento de sinal Deferred, uma Instância
é destruída antes que o sinal seja acionado.


O `Class.Instance` nunca será excluído da memória enquanto uma função conectada
estiver ainda usando-o. No entanto, se a função pausar em algum momento,
o `Class.Instance` e seus descendentes serão parentados para `nil`.

Se a propriedade `Class.Workspace.SignalBehavior` estiver definida como
`Enum.SignalBehavior.Immediate`, este evento dispara imediatamente antes do
`Class.Instance` ou um de seus ancestrais ser destruído com
`Class.Instance:Destroy()`.

Se a propriedade `Class.Workspace.SignalBehavior` estiver definida como
`Enum.SignalBehavior.Deferred`, este evento dispara no próximo
ponto de retomar, que será após o `Class.Instance` ou um de seus
ancestrais serem destruídos com `Class.Instance:Destroy()`.

Com o comportamento `Enum.SignalBehavior.Deferred|Deferred`, conectar um script
ao seu próprio evento `Class.Instance.Destroying` é problemático, já que o script
será destruído antes que o callback possa ser chamado (o que significa que não
será executado).

Ao excluir um `Class.Instance` no Studio, como excluir manualmente
por meio do [Explorer](/studio/explorer) ou por meio de um plugin,
o `Class.Instance` não é destruído. Em vez disso, o pai é definido como `nil`
que você pode rastrear com `Class.Instance.AncestryChanged`.

Instance.Destroying

Dispara imediatamente antes (ou é adiado até depois) da instância ser
 destruída através de `Class.Instance:Destroy()`.

Este evento dispara sempre que qualquer propriedade de estilo é alterada na instância,
incluindo quando uma propriedade é definida como `nil`.

```lua
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local playerGui = player.PlayerGui
local HUDContainer = playerGui:WaitForChild("HUDContainer")
local meterBar = HUDContainer.MeterBar

local function stylePropertyChanged()
	print("Propriedades de estilo alteradas")
end

meterBar:StyledPropertiesChanged():Connect(stylePropertyChanged)
```

Instance.StyledPropertiesChanged

Dispara sempre que qualquer propriedade de estilo é alterada na instância, incluindo
quando uma propriedade é definida como `nil`.

Este método aplica uma tag à instância, sem efeito se a tag já estiver
aplicada. Adicionar uma tag com sucesso acionará um sinal criado por
`Class.CollectionService:GetInstanceAddedSignal()` com a tag fornecida.

#### Avisos

- As tags de uma instância que foram adicionadas do lado do cliente serão
  descartadas se o servidor posteriormente adicionar ou remover uma tag nessa
  instância, porque o servidor replica todas as tags juntas e
  sobrepõe as tags anteriores.

- Ao marcar uma instância, é comum que alguns recursos sejam usados para
dar funcionalidade à tag, por exemplo, conexões de eventos ou tabelas.
  Para evitar vazamentos de memória, é uma boa ideia limpar esses recursos
enquanto não forem mais necessários para uma tag. Faça isso ao
  chamar `Class.Instance:RemoveTag()`, chamando
  `Class.Instance:Destroy()`, ou em uma função conectada a um sinal
  retornado por `Class.CollectionService:GetInstanceRemovedSignal()`.

Instance:AddTag

A função filhos retorna um array dos filhos do objeto.

Instance:children

Este método destrói todos os filhos e descendentes de uma instância.

```
local part = Instance.new("Part")

-- Adiciona alguns brilhos
for i = 1, 3 do
	local sparkles = Instance.new("Sparkles")
	sparkles.Parent = part

  local sc = Instance.new("Sparkles")
  sc.Parent = sparkles
end

print("Children:", #part:GetChildren())  --> Children: 3

part:ClearAllChildren()

print("Children:", #part:GetChildren())  --> Children: 0
```
Se você não desejar destruir **todos** os filhos e descendentes, use
`Class.Instance:GetChildren()` ou `Class.Instance:GetDescendants()` para
desloopar esses filhos/descendentes e selecionar o que deve ser destruído. Por
exemplo, o seguinte exemplo de código destruirá todos os`Class.BasePart|BaseParts`
descendentes de um `Class.Model`:

```
local Workspace = game:GetService("Workspace")

local model = Workspace:FindFirstChild("TestModel")

for _, descendant in model:GetDescendants() do
	if descendant:IsA("BasePart") then
		descendant:Destroy()
	end
end
```

Instance:ClearAllChildren

Este método destrói todos os filhos de uma instância.

Demonstra como clonar um modelo usando `Class.Instance:Clone()`.

`Clone()` cria uma cópia de uma instância e todos os seus descendentes,
ignorando todas as instâncias que não são
`Class.Instance.Archivable|Archivable`. A cópia da instância raiz é
retornada por este método e seu `Class.Instance.Parent|Parent` é definido como
`nil`. Observe que, se a própria instância tiver
`Class.Instance.Archivable|Archivable` definido como `false`, este método
retornará `nil`.

Se uma propriedade de referência, como `Class.ObjectValue.Value`, estiver definida em uma
instância clonada, o valor da propriedade da cópia depende do valor do
original:

- Se uma propriedade de referência se referir a uma instância que também foi
  clonada, a cópia se referirá à cópia.
- Se uma propriedade de referência se referir a uma instância que **não** foi clonada,
  o mesmo valor é mantido na cópia.

Instance:Clone

Cria uma cópia de uma instância e todos os seus descendentes, ignorando instâncias
que não são `Class.Instance.Archivable|Archivable`.

Instance:clone

Demonstra a destruição de uma Parte usando a função `Class.Instance:Destroy()`.

Esta função é a maneira correta de descartar objetos que não são mais
necessários.


Define a propriedade `Class.Instance.Parent` como `nil`, tranca a
propriedade `Class.Instance.Parent`, desconecta todas as conexões e chama
`Destroy()` em todos os filhos. Este método é a maneira correta de descartar
objetos que não são mais necessários.

Descartar objetos desnecessários é importante, uma vez que objetos e
conexões desnecessárias em um lugar ocupam memória que pode levar a sérios problemas de
desempenho ao longo do tempo.

Como uma boa prática, após chamar `Destroy()` em um objeto, defina qualquer
variável que referencia o objeto (ou seus descendentes) como `nil`. Isso
impede que seu código acesse qualquer coisa relacionada ao objeto.

```lua
local part = Instance.new("Part")
part.Name = "Hello, world"
part:Destroy()
-- Não faça isso:
print(part.Name)  --> "Hello, world"
-- Faça isso para evitar que a linha acima funcione:
part = nil
```
Uma vez que uma `Class.Instance` tenha sido destruída por este método, não pode ser
reutilizada porque a propriedade `Class.Instance.Parent` é trancada. Para
remover **temporariamente** um objeto em vez de destruí-lo, defina
`Class.Instance.Parent|Parent` como `nil`. Por exemplo:

```
local Workspace = game:GetService("Workspace")

object.Parent = nil
task.wait(2)
object.Parent = Workspace
```
Para destruir um objeto após um tempo determinado, use
`Class.Debris:AddItem()`.

Instance:Destroy

Define a propriedade `Class.Instance.Parent` como `nil`, tranca a
propriedade `Class.Instance.Parent`, desconecta todas as conexões e chama
`Destroy()` em todos os filhos.

Instance:destroy

Retorna o primeiro ancestral da `Class.Instance` cujo
`Class.Instance.Name` é igual ao nome fornecido.

Este método funciona para cima, o que significa que começa no
`Class.Instance.Parent` imediato da instância e sobe em direção ao
`Class.DataModel`. Se nenhum ancestral correspondente for encontrado, retorna
`nil`.

O seguinte trecho de código encontraria o primeiro ancestral do objeto
chamado `Car`.

```
local car = object:FindFirstAncestor("Car")
```
Para variantes deste método que encontram ancestrais de uma classe específica,
veja `Class.Instance:FindFirstAncestorOfClass()` e
`Class.Instance:FindFirstAncestorWhichIsA()`.

Instance:FindFirstAncestor

name

Retorna o primeiro ancestral da `Class.Instance` cujo
`Class.Instance.Name` é igual ao nome fornecido.

Retorna o primeiro ancestral da `Class.Instance` cujo
`Class.Object.ClassName` é igual ao nome da classe fornecida.

Este método funciona para cima, o que significa que começa no
`Class.Instance.Parent` imediato da instância e sobe em direção ao
`Class.DataModel`. Se nenhum ancestral correspondente for encontrado, retorna `nil`.

Um uso comum deste método é encontrar o `Class.Model` a que um
`Class.BasePart` pertence. Por exemplo:

```
local model = part:FindFirstAncestorOfClass("Model")
```
Este método é uma variante de `Class.Instance:FindFirstAncestor()` que
verifica a propriedade `Class.Object.ClassName` em vez de
`Class.Instance.Name`. `Class.Instance:FindFirstAncestorWhichIsA()` também
existe, usando o método `Class.Object:IsA()` em vez disso para respeitar a
herança de classe.

Instance:FindFirstAncestorOfClass

className

O `Class.Object.ClassName` a ser procurado.

Retorna o primeiro ancestral da `Class.Instance` cujo
`Class.Object.ClassName` é igual ao nome da classe fornecida.

Retorna o primeiro ancestral da `Class.Instance` para quem
`Class.Object:IsA()` retorna verdadeiro para o nome da classe fornecida.

Este método funciona para cima, o que significa que começa no
`Class.Instance.Parent` imediato da instância e sobe em direção ao
`Class.DataModel`. Se nenhum ancestral correspondente for encontrado, retorna
`nil`.

Diferente de `Class.Instance:FindFirstAncestorOfClass()`, este método usa
`Class.Object:IsA()` que respeita a herança de classe. Por exemplo:

```
print(part:IsA("Part"))  --> true
print(part:IsA("BasePart"))  --> true
print(part:IsA("Instance"))  --> true
```
Portanto, o seguinte exemplo de código retornará o primeiro
ancestral `Class.BasePart`, independentemente de ser um `Class.WedgePart`,
`Class.MeshPart` ou `Class.Part`.

```
local part = object:FindFirstAncestorWhichIsA("BasePart")
```
Veja também `Class.Instance:FindFirstAncestor()`.

Instance:FindFirstAncestorWhichIsA

Retorna o primeiro ancestral da `Class.Instance` para quem
`Class.Object:IsA()` retorna verdadeiro para o nome da classe fornecida.

O abaixo procurará no Workspace por um objeto chamado "Brick". Se encontrado, ele
mudará o nome do objeto para "Foo".

Retorna o primeiro filho da `Class.Instance` com o nome fornecido, ou
`nil` se não existir tal filho. Se o argumento opcional `recursive` for
`true`, este método busca todos os descendentes em vez de apenas os
filhos imediatos da `Class.Instance`.

#### Verificando a Existência de um Objeto

`FindFirstChild()` é necessário se você precisa verificar se um objeto existe
antes de continuar. Tentar indexar um filho pelo nome usando o operador de ponto
gera um erro se o filho não existir.

```lua
local Workspace = game:GetService("Workspace")

-- A linha a seguir gera um erro se a parte não existir no workspace
Workspace.Part.Transparency = 0.5
```
Uma abordagem melhor é usar `FindFirstChild()` para primeiro verificar o `Part`,
seguido de uma instrução `if` para executar o código que precisa dele.

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace:FindFirstChild("Part")
if part then
	part.Transparency = 0.5
end
```

#### Encontrando um Filho Cujo Nome Corresponde a uma Propriedade

Às vezes o `Class.Instance.Name|Name` de um objeto é o mesmo que o de uma
propriedade do seu `Class.Instance.Parent|Parent`. Ao usar o operador de ponto,
propriedades têm precedência sobre filhos se compartilharem um nome.

No exemplo a seguir, uma `Class.Folder` chamada `Color` é adicionada a um
`Class.Part`, que também tem a propriedade `Class.Part.Color`. Observe que
`part.Color` se refere ao valor da propriedade `Datatype.Color3`, não à instância do filho
`Class.Folder`. Uma vantagem de usar
`Class.Instance:FindFirstChild()|FindFirstChild()` é que a introdução de novas
propriedades não impõe risco ao seu código.

```lua
local part = Instance.new("Part")
local folder = Instance.new("Folder")
folder.Name = "Color"
folder.Parent = part
local c1 = part.Color  -- A propriedade
local c2 = part:FindFirstChild("Color")  -- A pasta filha
```

#### Notas de Desempenho

`Class.Instance:FindFirstChild()|FindFirstChild()` leva cerca de 20% mais
com tempo do que usar o operador de ponto e quase 8 vezes mais do que apenas armazenar
uma referência a um objeto. Portanto, você deve evitar chamá-lo em
código dependente de desempenho, como em loops apertados ou funções conectadas
a `Class.RunService.Heartbeat` e `Class.RunService.PreRender`. Em vez disso,
estocou o resultado em uma variável, ou considere usar
`Class.Instance.ChildAdded|ChildAdded` ou
`Class.Instance:WaitForChild()|WaitForChild()` para detectar quando um filho de um
dado nome se torna disponível.

Instance:FindFirstChild

recursive

Se a busca deve ser realizada recursivamente.

Retorna o primeiro filho da `Class.Instance` encontrado com o nome fornecido.

Instance:findFirstChild

Retorna o primeiro filho da `Class.Instance` cuja
`Class.Object.ClassName|ClassName` é igual ao `className` fornecido.
Diferente de `Class.Instance:FindFirstChildWhichIsA()`, este método só
retorna objetos cuja classe corresponde ao `className`, ignorando a herança
de classe. Se nenhum filho correspondente for encontrado, este método
retorna `nil`.

Instance:FindFirstChildOfClass

Retorna o primeiro filho da `Class.Instance` cuja
`Class.Object.ClassName|ClassName` é igual ao nome da classe fornecida.

Retorna o primeiro filho da `Class.Instance` para quem
`Class.Object:IsA()` retorna verdadeiro para o nome da classe fornecida.

Se nenhum filho correspondente for encontrado, este método retorna `nil`. Se o argumento
o opcional recursivo for `true`, este método busca todos os descendentes em vez
apenas dos filhos imediatos da `Class.Instance`.

Diferente de `Class.Instance:FindFirstChildOfClass()`, este método usa
`Class.Object:IsA()` que respeita a herança de classe. Por exemplo:

```lua
print(part:IsA("Part")) --> true
print(part:IsA("BasePart")) --> true
print(part:IsA("Instance")) --> true
```
Portanto, o seguinte exemplo de código retornará o primeiro
filho `Class.BasePart`, independentemente de ser um `Class.WedgePart`,
`Class.MeshPart` ou `Class.Part`.

```
local part = object:FindFirstChildWhichIsA("BasePart")
```
Desenvolvedores que procuram um filho pelo nome devem usar
`Class.Instance:FindFirstChild()` em vez disso.

Instance:FindFirstChildWhichIsA

Retorna o primeiro filho da `Class.Instance` para quem
`Class.Object:IsA()` retorna verdadeiro para o nome da classe fornecida.

Retorna o primeiro descendente encontrado com o dado `Class.Instance.Name`.

Este método está desabilitado e não pode ser usado. Para encontrar o primeiro descendente
 de uma instância, considere usar o parâmetro `recursive` em
 `Class.Instance:FindFirstChild()` em vez disso.

Instance:FindFirstDescendant

Retorna o primeiro descendente encontrado com o dado `Class.Instance.Name`.

Se a `Class.Instance` for um `Class.Actor`, o próprio `Class.Actor` é
retornado. Caso contrário, seu ancestral `Class.Actor` mais próximo é retornado. Se nenhum
ancestral for um `Class.Actor`, o resultado é `nil`.

Instance:GetActor

Retorna o `Class.Actor` associado à Instância, se houver.

Este método retorna o valor que foi atribuído ao nome do atributo fornecido. Se
nenhum atributo foi atribuído, `nil` é retornado.

Por exemplo, o seguinte trecho de código define e depois obtém o valor do
atributo `InitialPosition` da instância:

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local initialPosition = instance:GetAttribute("InitialPosition")
print(initialPosition)
```

#### Veja Também

- `Class.Instance:SetAttribute()` que define o atributo com o nome fornecido
  para o valor fornecido.
- `Class.Instance:GetAttributes()` que retorna um dicionário de pares chave-valor
  para cada um dos atributos da instância.

Instance:GetAttribute

O nome do atributo que está sendo recuperado.

Retorna o valor que foi atribuído ao nome do atributo fornecido.

Instance

`Instance` é a classe base para todas as classes na hierarquia de classes do Roblox
que podem fazer parte da árvore `Class.DataModel`.

/reference/engine/classes/BillboardGui.yaml