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 do GDScript
Na Godot, membros de classe podem ser exportados. Isso significa que seu valor é salvo junto com o recurso (como o cena) eles estão ligados e são transferidos ao usar RPCs. Eles também estarão disponíveis para edição no editor de propriedades. A exportação é feita usando a anotação @export`.
@export var number: int = 5
Nesse exemplo, o valor 5 será salvo e ficará visível no editor de propriedades.
Uma variável exportada deve ser inicializada com uma expressão constante ou ter um especificador de tipo na variável. Algumas das anotações de exportação têm um tipo específico e não precisam que a variável seja tipada (veja a seção de Exemplos abaixo).
Um dos benefícios fundamentais de exportar variáveis de membro é tê-las visíveis e editáveis no editor. Dessa forma, artistas e designers de jogos podem modificar valores que mais tarde influenciam como o programa funciona. Para isso, uma sintaxe especial de exportação é fornecida. Adicionalmente, comentários de documentação podem ser usados para descrições de dicas de ferramentas (tooltips), visíveis ao passar o mouse.
Nota
A exportação de propriedades também pode ser feita em outras linguagens, como C#. A sintaxe varia dependendo da linguagem. Veja Propriedades exportadas em C# para informações sobre exportações em C#.
Uso básico
Se o valor exportado atribuir uma constante ou expressão constante, o tipo será inferido e usado no editor.
@export var number = 5
Se não houver um valor padrão, você pode adicionar um tipo à variável.
@export var number: int
Recursos (Resources) e nós (nodes) podem ser exportados.
@export var resource: Resource
@export var node: Node
Mesmo que um script não seja executado no editor, as propriedades exportadas ainda podem ser editadas. No entanto, os getters e setters só serão usados se o script estiver em Modo de Ferramenta.
Agrupando exportações
É possível agrupar suas propriedades exportadas dentro do Inspetor com a anotação @export_group. Cada propriedade exportada após esta anotação será adicionada ao grupo. Inicie um novo grupo ou use @export_group(\"\") para sair dele.
@export_group("My Properties")
@export var number = 3
O segundo argumento da anotação pode ser usado para agrupar apenas propriedades com o prefixo especificado.
Grupos não podem ser aninhados; use @export_subgroup para criar subgrupos dentro de um grupo.
@export_subgroup("Extra Properties")
@export var string = ""
@export var flag = false
Você também pode alterar o nome da sua categoria principal ou criar categorias adicionais na lista de propriedades com a anotação @export_category.
@export_category("Main Category")
@export var number = 3
@export var string = ""
@export_category("Extra Category")
@export var flag = false
Nota
A lista de propriedades é organizada com base na herança da classe e novas categorias quebram essa expectativa. Use-as com cuidado, especialmente ao criar projetos para uso público.
Strings como caminhos (paths)
String como um caminho para um arquivo. Veja @export_file.
@export_file var f
String como um caminho para um diretório. Veja @export_dir.
@export_dir var f
String como um caminho para um arquivo, filtro personalizado fornecido como dica. Veja novamente @export_file.
@export_file("*.txt") var f
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. Veja @export_global_file.
@export_global_file("*.png") var tool_image
String como um caminho para um diretório no sistema de arquivos global. Veja @export_global_dir.
@export_global_dir var tool_dir
A anotação multiline diz ao editor para exibir um campo de entrada grande para edição em várias linhas. Veja @export_multiline.
@export_multiline var text
Strings como ações de entrada (input actions)
String como uma ação de entrada definida no mapa de entrada (input map) do projeto.
@export_custom(PROPERTY_HINT_INPUT_NAME) var my_input
String como uma ação de entrada definida no mapa de entrada do projeto, mais valores integrados padrão, como ui_accept e ui_cancel.
@export_custom(PROPERTY_HINT_INPUT_NAME, "show_builtin") var my_input
String como uma ação de entrada definida no mapa de entrada do projeto, mais valores arbitrários que podem ser inseridos manualmente.
@export_custom(PROPERTY_HINT_INPUT_NAME, "loose_mode") var my_input
String como uma ação de entrada definida no mapa de entrada do projeto, mais valores integrados padrão como ui_accept e ui_cancel e valores arbitrários que podem ser inseridos manualmente.
@export_custom(PROPERTY_HINT_INPUT_NAME, "show_builtin,loose_mode") var my_input
Limitando intervalos de entrada do editor
Veja @export_range para todos os itens a seguir.
Permitir valores inteiros de 0 a 20.
@export_range(0, 20) var i
Permitir valores inteiros de -10 a 20.
@export_range(-10, 20) var j
Permitir floats de -10 a 20 e ajustar (snap) o valor para múltiplos de 0.2.
@export_range(-10, 20, 0.2) var k: float
Os limites podem ser configurados para afetar apenas o controle deslizante (slider) se você adicionar as dicas \"or_less\" e/ou \"or_greater\". Se qualquer uma dessas dicas for usada, será possível para o usuário inserir qualquer valor ou arrastar o valor com o mouse quando não estiver usando o slider, mesmo se estiver fora da faixa especificada.
@export_range(0, 100, 1, "or_less", "or_greater") var l: int
A dica \"exp\" pode ser usada para fazer com que um valor tenha um slider exponencial em vez de um slider linear. Isso significa que, ao arrastar o slider para a direita, as mudanças se tornarão progressivamente mais rápidas ao arrastar o mouse. Isso é útil para facilitar a edição de valores que podem ser muito pequenos ou muito grandes, ao custo de ser menos intuitivo.
@export_range(0, 100000, 0.01, "exp") var exponential: float
Para valores que se destinam a representar um fator de atenuação/suavização (easing factor), use Floats com dica de suavização (easing hint) em seu lugar.
A dica \"hide_slider\" pode ser usada para ocultar a barra horizontal que aparece abaixo das propriedades float, ou as setas para cima/para baixo que aparecem ao lado de propriedades int:
@export_range(0, 1000, 0.01, "hide_slider") var no_slider: float
Por outro lado, a dica \"prefer_slider\" pode ser usada para exibir uma barra horizontal abaixo de propriedades int em vez de setas para cima/para baixo:
@export_range(0, 100, 1, "prefer_slider") var with_slider: int
Adicionando sufixos e tratando graus/radianos
Um sufixo também pode ser definido para tornar o valor mais autoexplicativo no inspetor. Por exemplo, para definir um valor que deve ser configurado como "metros" (m) pelo usuário:
@export_range(0, 100, 1, "suffix:m") var m: int
For angles that are stored in radians but displayed as degrees to the user, use
the "radians_as_degrees" hint:
@export_range(0, 360, 0.1, "radians_as_degrees") var angle: float
This performs automatic conversion when the value is displayed or modified in
the inspector and also displays a degree (°) suffix. This approach is used
by Godot's own rotation properties throughout the editor.
If the angle is stored in degrees instead, use the "degrees" hint to display
the degree symbol while disabling the automatic degrees-to-radians conversion
when the value is modified from the inspector.
Vinculando valores de vetores entre si
É possível vincular valores de vetores entre si. Quando o usuário ajusta um dos componentes do vetor, os outros componentes são ajustados automaticamente de forma proporcional. Por exemplo, isso é útil para manter a proporção (aspect ratio) de um sprite 2D ao ajustar sua escala. Esse recurso pode ser desativado temporariamente pelo usuário clicando no ícone de vínculo à direita da propriedade.
# Leave the hint string empty if you don't want to add a suffix.
@export_custom(PROPERTY_HINT_LINK, "suffix:px") var vector2_linked: Vector2 = Vector2(16, 16)
Resultados em:
Propriedade Vector2i vinculada com o sufixo "px"
Esta dica é eficaz em Vector2, Vector2i, Vector3, Vector3i, Vector4 e Vector4i. Ela pode ser usada ao mesmo tempo que um sufixo de propriedade, como visto no exemplo acima.
Floats com dica de suavização (easing hint)
Exibe uma representação visual da função ease() ao editar. Veja @export_exp_easing.
@export_exp_easing var transition_speed
Cores
Cor regular fornecida como valor vermelho-verde-azul-alfa.
@export var col: Color
Cor fornecida como um valor vermelho-verde-azul (RGB - o alfa sempre será 1). Veja @export_color_no_alpha.
@export_color_no_alpha var col: Color
Nós
Nós também podem ser exportados diretamente como propriedades em um script, sem a necessidade de usar NodePaths:
# Allows any node.
@export var node: Node
# Allows any node that inherits from BaseButton.
# Custom classes declared with `class_name` can also be used.
@export var some_button: BaseButton
Exportar NodePaths como no Godot 3.x ainda é possível, caso você precise:
@export var node_path: NodePath
var node = get_node(node_path)
Se você quiser limitar os tipos de nós para NodePaths, pode usar a anotação @export_node_path:
@export_node_path("Button", "TouchScreenButton") var some_button
Recursos
@export var resource: Resource
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 uma extensão de Resource como:
@export var resource: AnimationNode
O menu suspenso será limitado a AnimationNode e a todas as suas classes derivadas.
Nota
O uso de variáveis @export para objetos Resource faz com que eles se tornem uma dependência da instância, o que significa que todos os recursos referenciados por variáveis @export são carregados quando a cena que contém o script é carregada. Se você deseja referenciar um objeto Resource, mas carregá-lo manualmente quando precisar (o que, por exemplo, costuma ser o caso de PackedScenes que contêm uma fase inteira), use @export_file ou @export_file_path em seu lugar.
Exportando sinalizadores de bits
Veja @export_flags.
Números inteiros usados como bit flags podem armazenar múltiplos valores true/false (booleanos) em uma única propriedade. Ao utilizar a anotação @export_flags, eles podem ser configurados a partir do editor:
# Set any of the given flags from the editor.
@export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0
Você deve fornecer uma descrição em string para cada sinalizador. Neste exemplo, Fire tem valor 1, Water tem valor 2, Earth tem valor 4 e Wind corresponde ao valor 8. Normalmente, constantes deveriam ser definidas em conformidade (por exemplo, const ELEMENT_WIND = 8 e assim por diante).
Você pode adicionar valores explícitos usando dois-pontos:
@export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 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_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")
var spell_targets = 0
Também são fornecidas anotações de exportação para as camadas de física, renderização e navegação definidas nas configurações do projeto:
@export_flags_2d_physics var layers_2d_physics
@export_flags_2d_render var layers_2d_render
@export_flags_2d_navigation var layers_2d_navigation
@export_flags_3d_physics var layers_3d_physics
@export_flags_3d_render var layers_3d_render
@export_flags_3d_navigation var layers_3d_navigation
O uso de sinalizadores de bit exige certo conhecimento de operações bit a bit. Na dúvida, exporte variáveis booleanas.
Exportando enums
Veja @export_enum.
Propriedades podem ser exportadas com uma dica de tipo referenciando um enum para limitar seus valores aos valores da enumeração. O editor criará um widget no Inspetor, listando as opções como "Thing 1", "Thing 2", "Another Thing". O valor será armazenado como um número inteiro.
enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
@export var x: NamedEnum
Propriedades de tipo inteiro e string também podem ser limitadas a uma lista específica de valores usando a anotação @export_enum. O editor criará um widget no Inspetor, listando as opções 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_enum("Warrior", "Magician", "Thief") var character_class: int
Você pode adicionar valores explícitos usando dois-pontos:
@export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int
Se o tipo for String, o valor será armazenado como uma string.
@export_enum("Rebecca", "Mary", "Leah") var character_name: String
Se você quiser definir um valor inicial, deve especificá-lo explicitamente:
@export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca"
Exportando arrays
Arrays exportados podem ter inicializadores, mas devem ser expressões constantes.
Se o array exportado especificar um tipo que herda de Resource, os valores do array podem ser definidos no inspetor arrastando e soltando vários arquivos da dock Arquivos de uma vez.
O valor padrão deve ser uma expressão constante.
@export var a = [1, 2, 3]
Arrays exportados podem especificar o tipo (usando as mesmas dicas de antes).
@export var ints: Array[int] = [1, 2, 3]
# Nested typed arrays such as `Array[Array[float]]` are not supported yet.
@export var two_dimensional: Array[Array] = [[1.0, 2.0], [3.0, 4.0]]
Você pode omitir o valor padrão, mas ele seria null se não fosse atribuído.
@export var b: Array
@export var scenes: Array[PackedScene]
Arrays com tipos especificados que herdam de resource podem ser definidos arrastando e soltando múltiplos arquivos a partir da aba FileSystem.
@export var textures: Array[Texture] = []
@export var scenes: Array[PackedScene] = []
Packed arrays also work, but only if initialized empty:
@export var vector3s = PackedVector3Array()
@export var strings = PackedStringArray()
Outras variantes de exportação também podem ser usadas ao exportar arrays:
@export_range(-360, 360, 0.001, "degrees") var laser_angles: Array[float] = []
@export_file("*.json") var skill_trees: Array[String] = []
@export_color_no_alpha var hair_colors = PackedColorArray()
@export_enum("Espresso", "Mocha", "Latte", "Capuccino") var barista_suggestions: Array[String] = []
@export_storage
Veja @export_storage.
Por padrão, exportar uma propriedade tem dois efeitos:
faz com que a propriedade seja armazenada no arquivo de cena/recurso (PROPERTY_USAGE_STORAGE);
adiciona um campo ao Inspetor (PROPERTY_USAGE_EDITOR).
No entanto, às vezes você pode querer tornar uma propriedade serializável, mas não exibi-la no editor para evitar alterações não intencionais e poluição na interface.
Para fazer isso, você pode usar @export_storage. Isso pode ser útil para scripts @tool. Além disso, o valor da propriedade é copiado quando Resource.duplicate() ou Node.duplicate() é chamado, ao contrário de variáveis não exportadas.
var a # Not stored in the file, not displayed in the editor.
@export_storage var b # Stored in the file, not displayed in the editor.
@export var c: int # Stored in the file, displayed in the editor.
@export_custom
Se você precisar de mais controle do que o exposto pelas anotações @export integradas, pode usar @export_custom em seu lugar. Isso permite definir qualquer dica de propriedade, string de dica e sinalizadores de uso (usage flags), com uma sintaxe semelhante à usada pelo editor para nós integrados.
Por exemplo, isto expõe a propriedade altitude sem limites de alcance, mas com um sufixo m (metro) definido:
@export_custom(PROPERTY_HINT_NONE, "suffix:m") var altitude: float
O caso acima normalmente não é viável com a sintaxe padrão de @export_range, já que ela exige a definição de um alcance (range).
Veja a referência de classe para uma lista de parâmetros e seus valores permitidos.
Aviso
Ao usar @export_custom, o GDScript não realiza nenhuma validação na sintaxe. Uma sintaxe inválida pode causar comportamentos inesperados no inspetor.
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 em Modo de Ferramenta, o valor no inspetor não será atualizado automaticamente. Para atualizá-lo, chame notify_property_list_changed() após definir o valor da variável exportada.
Lendo o valor de uma variável exportada antecipadamente
Se você ler o valor de uma variável exportada em _init(), ela retornará o valor padrão especificado na anotação de exportação em vez do valor que foi definido no inspetor. Isso ocorre porque a atribuição de valores a partir do arquivo de cena/recurso salvo acontece após a inicialização do objeto; até lá, o valor padrão é usado.
Para obter o valor que foi definido no inspetor (e, portanto, salvo no arquivo de cena/recurso), você precisa lê-lo após o objeto ser construído, como em Node._ready(). Você também pode ler o valor em um setter definido na propriedade exportada, o que é útil em recursos personalizados onde _ready() não está disponível:
# Set this property to 3 in the inspector.
@export var exported_variable = 2:
set(value):
exported_variable = value
print("Inspector-set value: ", exported_variable)
func _init():
print("Initial value: ", exported_variable)
Resultados em:
Initial value: 2
Inspector-set value: 3
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 elas podem ser personalizadas com os métodos _set(), _get() e _get_property_list(), 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 @tool para que os métodos acima possam funcionar de dentro do editor.