Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Propriedades exportadas em C#

No Godot, membros de classe podem ser exportados. Isso significa que seus valores são salvos juntamente com o recurso (como a cena) ao qual estão associados. Eles também ficarão disponíveis para edição no editor de propriedades. A exportação é realizada utilizando o atributo [Export].

using Godot;

public partial class ExportExample : Node3D
{
    [Export]
    public int Number { get; set; } = 5;
}

Nesse exemplo, o valor 5 será salvo e, após a compilação do projeto atual, ele ficará visível no editor de propriedades.

Um dos benefícios fundamentais de exportar variáveis membros é tê-las visíveis e editáveis no editor. Dessa forma, artistas e projetistas de jogos podem modificar valores que influenciam como o programa funciona. Para isso, há uma sintaxe especial para exportação.

A exportação só pode ser feita com Tipos compatíveis com Variant.

Nota

A exportação de propriedades também pode ser feita no GDScript; para informações sobre isso, veja Propriedades exportadas do GDScript.

Uso básico

A exportação funciona com campos (fields) e propriedades. Eles podem ter qualquer modificador de acesso.

[Export]
private int _number;

[Export]
public int Number { get; set; }

Membros exportados podem especificar um valor padrão; caso contrário, o valor padrão do tipo será utilizado em seu lugar.

Um int como Number tem como padrão 0. O campo Text tem como padrão null porque string é um tipo de referência.

[Export]
public int Number { get; set; }

[Export]
public string Text { get; set; }

Valores padrões podem ser especificados para campos (fields) e propriedades.

[Export]
private string _greeting = "Hello World";

[Export]
public string Greeting { get; set; } = "Hello World";

Propriedades com um campo de suporte (backing field) usam o valor padrão do campo de suporte.

private int _number = 2;

[Export]
public int NumberWithBackingField
{
    get => _number;
    set => _number = value;
}

Nota

O get de uma propriedade não é realmente executado para determinar o valor padrão. Em vez disso, o Godot analisa o código-fonte C#. Isso funciona bem na maioria dos casos, como nos exemplos desta página. No entanto, algumas propriedades são complexas demais para o analisador compreender.

Por exemplo, a propriedade a seguir tenta usar operações matemáticas para exibir o valor padrão como 5 no editor de propriedades, mas isso não funciona:

[Export]
public int NumberWithBackingField
{
    get => _number + 3;
    set => _number = value - 3;
}

private int _number = 2;

O analisador não entende este código e recorre ao valor padrão para int, que é 0. No entanto, ao executar a cena ou inspecionar um nó com um script de ferramenta (tool script) anexado, _number será 2, e NumberWithBackingField retornando 5. Essa diferença pode causar um comportamento confuso. Para evitar isso, não use propriedades complexas. Alternativamente, se o valor padrão puder ser especificado explicitamente, ele pode ser substituído com os métodos _PropertyCanRevert() e _PropertyGetRevert().

Qualquer tipo de Resource ou Node pode ser exportado. O editor de propriedades exibe uma caixa de diálogo de atribuição amigável para esses tipos. Isso pode ser usado em vez de GD.Load e GetNode. Veja Nodes and Resources.

[Export]
public PackedScene PackedScene { get; set; }

[Export]
public RigidBody2D RigidBody2D { get; set; }

Agrupando exportações

É possível agrupar suas propriedades exportadas dentro do Inspetor com o atributo [ExportGroup]. Cada propriedade exportada após esse atributo será adicionada ao grupo. Inicie um novo grupo ou use [ExportGroup("")] para sair do grupo atual.

[ExportGroup("My Properties")]
[Export]
public int Number { get; set; } = 3;

O segundo argumento do atributo pode ser usado para agrupar apenas propriedades com o prefixo especificado.

Os grupos não podem ser aninhados; use [ExportSubgroup] para criar subgrupos dentro de um grupo.

[ExportSubgroup("Extra Properties")]
[Export]
public string Text { get; set; } = "";
[Export]
public bool Flag { get; set; } = false;

Você também pode alterar o nome da sua categoria principal ou criar categorias adicionais na lista de propriedades com o atributo [ExportCategory].

[ExportCategory("Main Category")]
[Export]
public int Number { get; set; } = 3;
[Export]
public string Text { get; set; } = "";

[ExportCategory("Extra Category")]
[Export]
public bool Flag { get; set; } = false;

Nota

A lista de propriedades é organizada com base na herança das classes, e novas categorias quebram essa expectativa. Use-as com cuidado, especialmente ao criar projetos para uso público.

Strings como caminhos (paths)

Dicas de propriedade (property hints) podem ser usadas para exportar strings como caminhos

String como um caminho para um arquivo.

[Export(PropertyHint.File)]
public string GameFile { get; set; }

String como um caminho para um diretório.

[Export(PropertyHint.Dir)]
public string GameDirectory { get; set; }

String como um caminho para um arquivo, com filtro personalizado fornecido como dica.

[Export(PropertyHint.File, "*.txt,")]
public string GameFile { get; set; }

O uso de caminhos no sistema de arquivos global também é possível, mas apenas em scripts no modo ferramenta (tool mode).

String como um caminho para um arquivo PNG no sistema de arquivos global.

[Export(PropertyHint.GlobalFile, "*.png")]
public string ToolImage { get; set; }

String como um caminho para um diretório no sistema de arquivos global.

[Export(PropertyHint.GlobalDir)]
public string ToolDir { get; set; }

A anotação multiline informa ao editor para exibir um campo de entrada grande para edição em várias linhas.

[Export(PropertyHint.MultilineText)]
public string Text { get; set; }

Limitando intervalos de entrada do editor

O uso da dica de propriedade range permite limitar o que pode ser inserido como um valor usando o editor.

Permitir valores inteiros de 0 a 20.

[Export(PropertyHint.Range, "0,20,")]
public int Number { get; set; }

Permitir valores inteiros de -10 a 20.

[Export(PropertyHint.Range, "-10,20,")]
public int Number { get; set; }

Permitir floats de -10 a 20 e ajustar (snap) o valor para múltiplos de 0.2.

[Export(PropertyHint.Range, "-10,20,0.2")]
public float Number { get; set; }

Se você adicionar as dicas "or_greater" e/ou "or_less", poderá ir além ou abaixo dos limites ao ajustar o valor digitando-o, em vez de usar o controle deslizante (slider).

[Export(PropertyHint.Range, "0,100,1,or_greater,or_less")]
public int Number { get; set; }

Floats com dica de suavização (easing hint)

Exibe uma representação visual da função ease durante a edição.

[Export(PropertyHint.ExpEasing)]
public float TransitionSpeed { get; set; }

Exportar com dica de sufixo

Exibe um sufixo de dica de unidade para variáveis exportadas. Funciona com tipos numéricos, como floats ou vetores:

[Export(PropertyHint.None, "suffix:m/s\u00b2")]
public float Gravity { get; set; } = 9.8f;
[Export(PropertyHint.None, "suffix:m/s")]
public Vector3 Velocity { get; set; }

No exemplo acima, \u00b2 é usado para escrever o caractere "ao quadrado" (²).

Cores

Cor regular fornecida como valor vermelho-verde-azul-alfa.

[Export]
public Color Color { get; set; }

Cor fornecida como um valor vermelho-verde-azul (o alfa sempre será 1).

[Export(PropertyHint.ColorNoAlpha)]
public Color Color { get; set; }

Nós

Os nós também podem ser exportados diretamente sem a necessidade de usar NodePaths.

[Export]
public Node Node { get; set; }

Um tipo específico de nó também pode ser exportado diretamente. A lista de nós exibida após pressionar "Assign" (Atribuir) no inspetor é filtrada para o tipo especificado, e apenas um nó correto pode ser atribuído.

[Export]
public Sprite2D Sprite2D { get; set; }

Classes de nós personalizadas também podem ser exportadas diretamente. O comportamento de filtragem depende se a classe personalizada é uma classe global.

Exportar NodePaths como no Godot 3.x ainda é possível, caso você precise:

[Export]
public NodePath NodePath { get; set; }

public override void _Ready()
{
    var node = GetNode(NodePath);
}

Recursos

[Export]
public Resource Resource { get; set; }

No Inspetor, você pode então arrastar e soltar um arquivo de recurso da janela FileSystem para o espaço da variável.

Abrir o menu suspenso (dropdown) do inspetor pode, no entanto, resultar em uma lista extremamente longa de classes possíveis para criar. Portanto, se você especificar um tipo derivado de Resource, como por exemplo:

[Export]
public AnimationNode AnimationNode { get; set; }

O menu suspenso será limitado a AnimationNode e todas as suas classes derivadas. Classes de recursos personalizadas também podem ser usadas, veja Classes globais do C#.

Perceba que mesmo se o script não estiver em execução enquanto estiver no editor, as propriedades exportadas ainda são editáveis. Isso pode ser usado em conjunto com um script em modo "tool".

Exportando sinalizadores de bits

Membros cujo tipo seja um enum com o atributo [Flags] podem ser exportados e seus valores são limitados aos membros do tipo enum. O editor criará um componente (widget) no Inspetor, permitindo selecionar nenhum, um ou múltiplos membros do enum. O valor será armazenado como um número inteiro.

Um enum de flags usa potências de 2 para os valores dos membros do enum. Membros que combinam múltiplas flags usando o OR lógico (|) também são possíveis.

[Flags]
public enum SpellElements
{
    Fire = 1 << 1,
    Water = 1 << 2,
    Earth = 1 << 3,
    Wind = 1 << 4,

    FireAndWater = Fire | Water,
}

[Export]
public SpellElements MySpellElements { get; set; }

Números inteiros usados como bit flags podem armazenar múltiplos valores true/false (booleanos) em uma única propriedade. Ao utilizar a dica de propriedade Flags, qualquer uma das flags definidas pode ser configurada a partir do editor.

[Export(PropertyHint.Flags, "Fire,Water,Earth,Wind")]
public int SpellElements { get; set; } = 0;

Você deve fornecer uma descrição em texto para cada flag. Neste exemplo, Fire tem o valor 1, Water tem o valor 2, Earth tem o valor 4 e Wind corresponde ao valor 8. Normalmente, as constantes devem ser definidas de acordo (por exemplo, private const int ElementWind = 8, e assim por diante).

Você pode adicionar valores explícitos usando dois-pontos:

[Export(PropertyHint.Flags, "Self:4,Allies:8,Foes:16")]
public int SpellTargets { get; set; } = 0;

Apenas valores que são potências de 2 são válidos como opções de sinalizadores de bits (bit flags). O menor valor permitido é 1, pois 0 significa que nada está selecionado. Você também pode adicionar opções que são uma combinação de outros sinalizadores:

[Export(PropertyHint.Flags, "Self:4,Allies:8,Self and Allies:12,Foes:16")]
public int SpellTargets { get; set; } = 0;

Também são fornecidas anotações de exportação para as camadas de física e de renderização definidas nas configurações do projeto.

[Export(PropertyHint.Layers2DPhysics)]
public uint Layers2DPhysics { get; set; }
[Export(PropertyHint.Layers2DRender)]
public uint Layers2DRender { get; set; }
[Export(PropertyHint.Layers3DPhysics)]
public uint Layers3DPhysics { get; set; }
[Export(PropertyHint.Layers3DRender)]
public uint Layers3DRender { get; set; }

O uso de sinalizadores de bit exige certo conhecimento de operações bit a bit. Na dúvida, exporte variáveis booleanas.

Exportando enums

Membros cujo tipo seja um enum podem ser exportados e seus valores são limitados aos membros do tipo enum. O editor criará um componente no Inspetor, enumerando as opções a seguir como "Thing 1", "Thing 2", "Another Thing". O valor será armazenado como um número inteiro.

public enum MyEnum
{
    Thing1,
    Thing2,
    AnotherThing = -1,
}

[Export]
public MyEnum MyEnumCurrent { get; set; }

Membros inteiros e de texto (string) também podem ser limitados a uma lista específica de valores usando a anotação [Export] com a dica PropertyHint.Enum. O editor criará um componente no Inspetor, enumerando as opções a seguir como Warrior, Magician, Thief. O valor será armazenado como um número inteiro, correspondente ao índice da opção selecionada (ou seja, 0, 1 ou 2).

[Export(PropertyHint.Enum, "Warrior,Magician,Thief")]
public int CharacterClass { get; set; }

Você pode adicionar valores explícitos usando dois-pontos:

[Export(PropertyHint.Enum, "Slow:30,Average:60,Very Fast:200")]
public int CharacterSpeed { get; set; }

Se o tipo for string, o valor será armazenado como uma string.

[Export(PropertyHint.Enum, "Rebecca,Mary,Leah")]
public string CharacterName { get; set; }

Se você quiser definir um valor inicial, deve especificá-lo explicitamente:

[Export(PropertyHint.Enum, "Rebecca,Mary,Leah")]
public string CharacterName { get; set; } = "Rebecca";

Exportando botões do inspetor com `[ExportToolButton]`

Se você deseja criar um botão clicável no inspetor, pode usar o atributo [ExportToolButton]. Isso exporta uma propriedade ou campo do tipo Callable como um botão clicável. Como isso roda no editor, o uso do atributo [Tool] é obrigatório. Quando o botão é pressionado, o callable é invocado:

[Tool]
public partial class MyNode : Node
{
    [ExportToolButton("Click me!")]
    public Callable ClickMeButton => Callable.From(ClickMe);

    public void ClickMe()
    {
        GD.Print("Hello world!");
    }
}

Você também pode definir um ícone para o botão com um segundo argumento. Se especificado, um ícone será buscado via GetThemeIcon(), a partir do tipo de tema "EditorIcons".

[ExportToolButton("Click me!", Icon = "CharacterBody2D")]
public Callable ClickMeButton => Callable.From(ClickMe);

Exportando coleções

Conforme explicado na documentação do C# Variant, apenas certos arrays do C# e os tipos de coleção definidos no namespace Godot.Collections são compatíveis com Variant; portanto, apenas esses tipos podem ser exportados.

Exportando arrays do Godot

[Export]
public Godot.Collections.Array Array { get; set; }

O uso do tipo genérico Godot.Collections.Array<T> permite especificar o tipo dos elementos do array, o que será usado como uma dica para o editor. O Inspetor restringirá os elementos ao tipo especificado.

[Export]
public Godot.Collections.Array<string> Array { get; set; }

O valor padrão dos arrays do Godot é null. Um valor padrão diferente pode ser especificado:

[Export]
public Godot.Collections.Array<string> CharacterNames { get; set; } =
[
    "Rebecca",
    "Mary",
    "Leah",
];

Arrays com tipos especificados que herdam de resource podem ser definidos arrastando e soltando múltiplos arquivos a partir da aba FileSystem.

[Export]
public Godot.Collections.Array<Texture> Textures { get; set; }

[Export]
public Godot.Collections.Array<PackedScene> Scenes { get; set; }

Exportando dicionários do Godot

[Export]
public Godot.Collections.Dictionary Dictionary { get; set; }

O uso do tipo genérico Godot.Collections.Dictionary<TKey, TValue> permite especificar os tipos dos elementos de chave e valor do dicionário.

[Export]
public Godot.Collections.Dictionary<string, int> Dictionary { get; set; }

O valor padrão dos dicionários do Godot é null. Um valor padrão diferente pode ser especificado:

[Export]
public Godot.Collections.Dictionary<string, int> CharacterLives { get; set; } = new Godot.Collections.Dictionary<string, int>
{
    ["Rebecca"] = 10,
    ["Mary"] = 42,
    ["Leah"] = 0,
};

Exportando arrays C#

Arrays do C# podem ser exportados desde que o tipo do elemento seja um tipo compatível com Variant.

[Export]
public Vector3[] Vectors { get; set; }

[Export]
public NodePath[] NodePaths { get; set; }

O valor padrão dos arrays do C# é null. Um valor padrão diferente pode ser especificado:

[Export]
public Vector3[] Vectors { get; set; } =
[
    new Vector3(1, 2, 3),
    new Vector3(3, 2, 1),
];

Definindo variáveis exportadas a partir de um script de ferramenta

Ao alterar o valor de uma variável exportada a partir de um script no Modo de Ferramenta, o valor no Inspetor não será atualizado automaticamente. Para atualizá-lo, chame NotifyPropertyListChanged() após definir o valor da variável exportada.

Exports avançados

Nem todo tipo de export pode ser fornecido no nível da própria linguagem para evitar complexidade de design desnecessária. O seguinte descreve mais ou menos alguns recursos de exportação comuns que podem ser implementados com uma API de baixo nível.

Antes de continuar a leitura, você deve se familiarizar com a maneira como as propriedades são tratadas e como podem ser personalizadas com os métodos _Set(), _Get() e _GetPropertyList() conforme descrito em Acessando dados ou lógica a partir de um objeto.

Ver também

Para propriedades de ligação usando os métodos acima em C++, veja Vinculando propriedades usando _set/_get/_get_property_list.

Aviso

O script deve operar no modo de ferramenta para que os métodos acima possam funcionar dentro do editor.

Propriedades exportadas em C#

Uso básico

Agrupando exportações

Strings como caminhos (paths)

Limitando intervalos de entrada do editor

Floats com dica de suavização (easing hint)

Exportar com dica de sufixo

Cores

Nós

Recursos

Exportando sinalizadores de bits

Exportando enums

Exportando botões do inspetor com [ExportToolButton]

Exportando coleções

Exportando arrays do Godot

Exportando dicionários do Godot

Exportando arrays C#

Definindo variáveis exportadas a partir de um script de ferramenta

Exports avançados

Exportando botões do inspetor com `[ExportToolButton]`