Nodes and properties
Reference for every node class (Scene, 2D, UI, Physics, Timer, Audio): properties, types and default values.
This page is still in Portuguese: the English translation is in progress.
Generated from the Pygame Studio runtime. Not edited by hand.
Cada nó tem um tipo (classe), propriedades com tipo e padrão, e filhos. No editor, o inspetor mostra exatamente estas propriedades; no código, são atributos do nó (self.node.position, self.node.color = "#ff0000").
Tipos de propriedade: int, float, bool, str, enum (uma opção da lista), vec2 (par [x, y]), color ("#rrggbb" ou "#rrggbbaa"), asset (arquivo do projeto, por caminho ou asset:<uuid>), noderef (id de outro nó).
Índice
- Cena: Scene
- 2D: AnimatedSprite, Camera2D, Node2D, Shape, Sprite, Text, TileMap
- UI: Button, Canvas, Image, Label, Panel, Skinnable, UIAspectRatio, UIControl, UIGridLayout, UILayoutNode, UIListLayout, UIPadding, UISizeConstraint
- Física: Area, CollisionBody, KinematicBody, StaticBody
- Tempo: Timer
- Áudio: AudioPlayer
Cena
Scene
A cena: raiz de tudo o que existe no jogo (ou no nível). Define a cor de fundo; os nós ficam dentro dela.
- classe base · aceita filhos · base abstrata (não se insere direto)
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
background |
color | "#1b1f2a" |
2D
AnimatedSprite
Sprite que troca de quadro sozinho a partir de um arquivo .anim.json (quadros, fps e repetição). Use play("nome") e stop().
- herda de
Sprite· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position,rotation,scale,z,texture,flip_x,flip_y,modulate,frame
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
animations |
asset | — | Arquivo .anim.json com as animações deste spritesheet |
animation |
str | "" |
Animação que toca ao iniciar (vazia = a primeira do arquivo) |
playing |
bool | true |
Começa tocando |
speed |
float | 1 |
Multiplicador da velocidade · de 0.0 a 20.0 |
Camera2D
Câmera do jogo: define o que aparece. Pode seguir um nó, ter limites e tremer (shake). Vale a que tiver current ligado.
- herda de
Node2D· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position,rotation,scale,z
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
current |
bool | true |
Câmera usada no jogo |
zoom |
float | 1 |
de 0.05 a 64 |
follow |
noderef | — | Nó que a câmera acompanha no jogo |
smoothing |
float | 0 |
0 = cola no alvo; perto de 1 = acompanha devagar · de 0.0 a 0.99 |
use_limits |
bool | false |
A vista nunca mostra fora do retângulo abaixo |
limit_left |
int | 0 |
|
limit_top |
int | 0 |
|
limit_right |
int | 960 |
|
limit_bottom |
int | 540 |
Node2D
Nó com posição, rotação e escala no mundo 2D. Serve de pai para agrupar outros nós 2D: mover o pai move os filhos.
- classe base · aceita filhos · pode ser inserido pelo editor
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
position |
vec2 | [0, 0] |
|
rotation |
float | 0 |
Graus, horário |
scale |
vec2 | [1, 1] |
|
z |
int | 0 |
Ordem de desenho |
Shape
Forma simples desenhada na tela: retângulo, círculo ou linha, com cor e espessura.
- herda de
Node2D· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position,rotation,scale,z
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
kind |
enum | "rect" |
opções: rect, circle, line |
size |
vec2 | [64, 64] |
|
color |
color | "#4f8cff" |
|
width |
int | 0 |
0 = preenchido · de 0 a ∞ |
Sprite
Imagem do projeto desenhada no mundo. Com uma spritesheet fatiada na importação, frame escolhe o quadro.
- herda de
Node2D· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position,rotation,scale,z
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
texture |
asset | — | Imagem do projeto |
flip_x |
bool | false |
|
flip_y |
bool | false |
|
modulate |
color | "#ffffff" |
Multiplica a cor da imagem |
frame |
int | 0 |
Quadro da spritesheet (a grade é definida na importação do asset) · de 0 a ∞ |
Text
Texto desenhado no mundo, com tamanho e cor. Para texto fixo na tela use Label dentro de um Canvas.
- herda de
Node2D· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position,rotation,scale,z
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
text |
str | "Texto" |
|
font_size |
int | 24 |
de 1 a ∞ |
color |
color | "#ffffff" |
TileMap
Mapa de blocos feito com uma imagem (tileset). Pinte com a ferramenta Pintar; blocos de collision_tiles são sólidos.
- herda de
Node2D· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position,rotation,scale,z
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
texture |
asset | — | Imagem com os blocos, todos do mesmo tamanho |
tile_size |
vec2 | [16, 16] |
Tamanho de um bloco na imagem, em pixels |
map_size |
vec2 | [20, 12] |
Colunas e linhas do mapa |
data |
str | "" |
Blocos do mapa (use a ferramenta Pintar do viewport) |
collision_tiles |
str | "" |
Números dos blocos sólidos, ex.: 1, 4-6 |
collision_layer |
int | 1 |
Camadas em que os blocos sólidos estão (máscara de bits) · de 0 a 4294967295 |
UI
Button
Botão de UI: hover, pressionado, foco por Tab/setas/gamepad e o sinal clicked. Com texture vira um botão de imagem.
- herda de
Skinnable· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position_scale,position_offset,size_scale,size_offset,anchor,z,texture,modulate,slice_left,slice_top,slice_right,slice_bottom
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
text |
str | "Botão" |
|
font_size |
int | 24 |
de 1 a ∞ |
text_color |
color | "#ffffff" |
|
color |
color | "#3d5afe" |
|
hover_color |
color | "#5c7cff" |
|
pressed_color |
color | "#2a3fc1" |
|
corner_radius |
int | 8 |
de 0 a 256 |
hover_tint |
color | "#e6e6e6" |
Com imagem: multiplica a imagem quando o mouse está em cima |
pressed_tint |
color | "#b4b4b4" |
Com imagem: multiplica a imagem enquanto pressionado |
enabled |
bool | true |
Desligado: não reage ao mouse nem ao teclado |
focusable |
bool | true |
Pode receber o foco por Tab, setas ou direcional do gamepad (Enter/Espaço/A aciona) |
Canvas
Raiz da UI de jogo: cobre a tela. Os controles são filhos dele.
- classe base · aceita filhos · pode ser inserido pelo editor
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
enabled |
bool | true |
Desligado: a UI inteira some |
z |
int | 0 |
Canvas com z maior desenha por cima |
Image
Imagem de UI esticada no retângulo do controle (ou 9-slice com slice_*).
- herda de
Skinnable· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position_scale,position_offset,size_scale,size_offset,anchor,z,texture,modulate,slice_left,slice_top,slice_right,slice_bottom
Label
Texto de UI com tamanho, cor e alinhamento, posicionado pelo layout do pai.
- herda de
UIControl· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position_scale,position_offset,size_scale,size_offset,anchor,z
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
text |
str | "Texto" |
|
font_size |
int | 24 |
de 1 a ∞ |
color |
color | "#ffffff" |
|
align |
enum | "left" |
opções: left, center, right |
Panel
Retângulo de UI (cor, borda, cantos) ou, com texture e slice_*, uma imagem 9-slice. Serve de fundo e de pai.
- herda de
Skinnable· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position_scale,position_offset,size_scale,size_offset,anchor,z,texture,modulate,slice_left,slice_top,slice_right,slice_bottom
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
color |
color | "#2a2f3d" |
|
border_color |
color | "#ffffff33" |
|
border_width |
int | 0 |
de 0 a 32 |
corner_radius |
int | 0 |
de 0 a 256 |
Skinnable
Controle que pode ser desenhado com uma imagem; com slice_* > 0 vira 9-slice (cantos intactos, miolo esticado).
- herda de
UIControl· aceita filhos · base abstrata (não se insere direto) - propriedades herdadas:
position_scale,position_offset,size_scale,size_offset,anchor,z
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
texture |
asset | — | Imagem do projeto; sem ela o controle usa as cores |
modulate |
color | "#ffffff" |
Multiplica a cor da imagem |
slice_left |
int | 0 |
Borda esquerda da imagem que não estica, em pixels da imagem · de 0 a ∞ |
slice_top |
int | 0 |
de 0 a ∞ |
slice_right |
int | 0 |
de 0 a ∞ |
slice_bottom |
int | 0 |
de 0 a ∞ |
UIAspectRatio
Mantém a proporção largura/altura do pai (o eixo dominante manda).
- herda de
UILayoutNode· não aceita filhos · pode ser inserido pelo editor
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
ratio |
float | 1 |
largura ÷ altura · de 0.01 a 100 |
dominant |
enum | "width" |
Qual eixo manda; o outro é calculado · opções: width, height |
UIControl
Base dos controles de UI: posição e tamanho como proporção do pai mais pixels (*_scale + *_offset) e uma âncora.
- classe base · aceita filhos · base abstrata (não se insere direto)
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
position_scale |
vec2 | [0, 0] |
Parte proporcional da posição (0 a 1 do pai) |
position_offset |
vec2 | [0, 0] |
Parte em pixels da posição |
size_scale |
vec2 | [0, 0] |
Parte proporcional do tamanho (0 a 1 do pai) |
size_offset |
vec2 | [100, 40] |
Parte em pixels do tamanho |
anchor |
vec2 | [0, 0] |
Ponto do próprio controle que fica na posição (0,0 = canto superior esquerdo; 0.5,0.5 = centro) |
z |
int | 0 |
Ordem de desenho entre irmãos |
UIGridLayout
Distribui os filhos do pai em células de tamanho fixo, em linhas da esquerda para a direita (quebra quando não cabe).
- herda de
UILayoutNode· não aceita filhos · pode ser inserido pelo editor
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
cell_size |
vec2 | [64, 64] |
Tamanho de cada célula (substitui o tamanho do filho) |
spacing |
vec2 | [8, 8] |
UILayoutNode
Nó auxiliar de UI: age sobre o pai ou os irmãos, não desenha nada nem tem retângulo próprio.
- classe base · não aceita filhos · base abstrata (não se insere direto)
UIListLayout
Empilha os filhos do pai em coluna ou linha. A posição de cada um passa a vir daqui; o tamanho continua sendo o dele.
- herda de
UILayoutNode· não aceita filhos · pode ser inserido pelo editor
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
direction |
enum | "vertical" |
opções: vertical, horizontal |
spacing |
int | 8 |
Espaço entre os itens, em pixels · de 0 a ∞ |
main_align |
enum | "start" |
Alinhamento ao longo da lista · opções: start, center, end |
cross_align |
enum | "start" |
Alinhamento no outro eixo · opções: start, center, end |
UIPadding
Margem interna do pai: os filhos usam a área do pai menos estes valores.
- herda de
UILayoutNode· não aceita filhos · pode ser inserido pelo editor
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
top |
int | 8 |
de 0 a ∞ |
right |
int | 8 |
de 0 a ∞ |
bottom |
int | 8 |
de 0 a ∞ |
left |
int | 8 |
de 0 a ∞ |
UISizeConstraint
Limita o tamanho do pai, em pixels.
- herda de
UILayoutNode· não aceita filhos · pode ser inserido pelo editor
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
min_size |
vec2 | [0, 0] |
|
max_size |
vec2 | [100000, 100000] |
Física
Area
Sensor: não bloqueia ninguém; avisa quem entrou e saiu da sua caixa.
- herda de
CollisionBody· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position,rotation,scale,z,size,collision_layer,collision_mask
CollisionBody
Base dos corpos de colisão: uma caixa (size × scale) com camada e máscara de colisão. Rotação é ignorada.
- herda de
Node2D· aceita filhos · base abstrata (não se insere direto) - propriedades herdadas:
position,rotation,scale,z
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
size |
vec2 | [64, 64] |
Largura e altura da caixa de colisão (multiplicadas pela escala) |
collision_layer |
int | 1 |
Camadas em que este corpo está (máscara de bits; 1 = camada 1) · de 0 a 4294967295 |
collision_mask |
int | 1 |
Camadas contra as quais este corpo colide (máscara de bits) · de 0 a 4294967295 |
KinematicBody
Corpo que o script move com move_and_slide(velocidade, dt) ou move_and_collide(delta), parando e deslizando nos obstáculos.
- herda de
StaticBody· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position,rotation,scale,z,size,collision_layer,collision_mask
StaticBody
Obstáculo que não se move (chão, parede, plataforma). Outros corpos param nele.
- herda de
CollisionBody· aceita filhos · pode ser inserido pelo editor - propriedades herdadas:
position,rotation,scale,z,size,collision_layer,collision_mask
Tempo
Timer
Conta wait_time segundos e emite timeout. Com one_shot desligado repete sozinho.
- classe base · não aceita filhos · pode ser inserido pelo editor
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
wait_time |
float | 1 |
Segundos até o timeout · de 0.01 a ∞ |
one_shot |
bool | false |
Dispara uma vez e para |
autostart |
bool | true |
Começa a contar quando o jogo inicia |
Áudio
AudioPlayer
Toca um arquivo de áudio (efeito ou música) com volume por grupo (bus): play(), stop(), autoplay, loop.
- classe base · não aceita filhos · pode ser inserido pelo editor
| Propriedade | Tipo | Padrão | Detalhes |
|---|---|---|---|
stream |
asset | — | Arquivo .wav, .ogg ou .mp3 do projeto |
volume |
float | 1 |
de 0.0 a 1.0 |
bus |
enum | "sfx" |
Grupo de volume: música, efeitos ou interface · opções: sfx, music, ui |
loop |
bool | false |
|
autoplay |
bool | false |
Começa a tocar quando o jogo inicia |