Scripting API

Behavior, Node, Scene, InputMap and the methods of each node that game scripts can call.

This page is still in Portuguese: the English translation is in progress.

Generated from the Pygame Studio runtime. Not edited by hand.

Um script é um arquivo .py do projeto com uma classe que herda de Behavior. Campos export(...) viram propriedades do nó.

from pgstudio import Behavior, KinematicBody, Vec2, export


class Jogador(Behavior[KinematicBody]):
    velocidade: float = export(240.0, min=0)

    def on_update(self, dt: float) -> None:
        self.node.move_and_slide(Vec2(self.input.axis("esquerda", "direita") * self.velocidade, 0), dt)

Para as propriedades de cada nó veja nos.md.

Behavior

Todo script do jogo é uma classe que herda de Behavior[TipoDoNó] e fica ligada a um nó (self.node).

Membro	O que faz
`node`	atributo: o nó a que o script está ligado (tipado pelo argumento: `Behavior[KinematicBody]`)
`scene`	atributo: a cena (raiz); tem `input`, `tween`, `change_scene`, `set_volume`, `find`, `attributes`
`input`	atributo: o mapa de entrada (`pressed`, `held`, `released`, `axis`)
`on_ready() -> None`	chamado uma vez, quando o jogo começa (ou a cena troca)
`on_update(dt: float) -> None`	todo quadro, com `dt` em segundos
`on_draw(surface) -> None`	todo quadro, depois do desenho: dá a superfície para desenhar por cima
`on_input(event) -> None`	para cada evento do pygame (teclado, mouse…)

Node

Todo objeto da cena. Propriedades do tipo (position, color…) são atributos; attributes guarda dados livres.

Membro	O que faz
`find(path: str) -> Node \| None`	acha um nó por caminho de nomes a partir deste: `'Interface/Placar'`, `'..'` sobe um nível
`get(name: str) -> Any`	lê uma propriedade pelo nome: `node.get('color')`
`set(name: str, value: Any) -> None`	grava uma propriedade pelo nome (erro se não existir): `node.set('color', '#ff0000')`
`by_tag(tag: str) -> list[Node]`	todos os nós, deste para baixo, com essa etiqueta
`add_child(child: Node, index: int \| None = None) -> Node`	põe um nó dentro deste (em `index`, se der)
`remove_child(child: Node) -> None`	tira um filho
`reparent(new_parent: Node, index: int \| None = None) -> None`	muda o pai deste nó
`walk() -> Iterator[Node]`	percorre este nó e todos os descendentes, em pré-ordem
`is_visible_in_tree() -> bool`	False se este nó ou algum ancestral estiver oculto

Scene

A cena é a raiz; os scripts a acessam por self.scene.

Membro	O que faz
`tween(node: Node, prop: str, to, duration: float, ease: str = linear)`	anima uma propriedade (número ou par) até um valor: `scene.tween(nó, 'position', Vec2(100, 0), 0.5, ease='out_cubic')`
`change_scene(path: str) -> None`	troca para outra cena do projeto no fim do quadro: `scene.change_scene('scenes/fase2.scene.json')`
`set_volume(bus: str, value: float) -> None`	volume (0 a 1) de um grupo de áudio: `'master'`, `'music'`, `'sfx'` ou `'ui'`

InputMap

Acessado por self.input. As ações vêm de [input.actions] no project.toml (editor: Arquivo → Mapa de entrada).

Membro	O que faz
`pressed(action: str) -> bool`	True só no quadro em que a ação começou (tecla, botão do mouse ou do gamepad)
`held(action: str) -> bool`	True enquanto a ação estiver segurada
`released(action: str) -> bool`	True só no quadro em que a ação foi solta
`axis(negative: str, positive: str) -> float`	-1, 0 ou +1 a partir de duas ações: `input.axis('esquerda', 'direita')`
`mouse_pos`	atributo: posição do mouse na tela do jogo (x, y)

KinematicBody

Corpo movido pelo script, que para e desliza nos obstáculos (StaticBody, outros corpos da máscara, blocos sólidos de TileMap).

Membro	O que faz
`move_and_slide(velocity: pygame.Vector2 \| tuple[float, float], dt: float) -> pygame.Vector2`	anda `velocidade × dt` deslizando; devolve a velocidade com o eixo barrado zerado e atualiza `on_floor`/`on_wall`
`move_and_collide(delta: pygame.Vector2 \| tuple[float, float]) -> Collision \| None`	anda `delta` e para ao encostar; devolve a colisão (colisor, normal, resto) ou None
`on_floor`	atributo: encostou embaixo no último `move_and_slide` (y cresce para baixo)
`on_ceiling`	atributo: encostou em cima
`on_wall`	atributo: encostou do lado

Area

Sensor: não bloqueia, só avisa quem entra e sai.

Membro	O que faz
`body_entered`	sinal: `area.body_entered.connect(fn)`; `fn(corpo)` roda quando um corpo da máscara entra
`body_exited`	sinal: quando sai
`overlapping_bodies() -> list[StaticBody]`	os corpos dentro da área agora

Button

Botão de UI.

Membro	O que faz
`clicked`	sinal: `button.clicked.connect(fn)`; roda ao soltar o clique (ou Enter/Espaço/A com o botão focado)
`focused`	atributo: o botão tem o foco de teclado/gamepad
`hovered`	atributo: o mouse está em cima

AnimatedSprite

Sprite com animações de um arquivo .anim.json.

Membro	O que faz
`play(name: str \| None = None, restart: bool = False) -> None`	toca uma animação (`restart=True` recomeça mesmo se já tocava)
`stop() -> None`	para no quadro atual
`current_frame() -> int`	o número do quadro da spritesheet que está na tela
`current_animation() -> Animation \| None`	a animação ativa (nome, quadros, fps, loop) ou None
`animation_finished`	sinal: nome da animação que acabou (só as sem loop)
`animation_changed`	sinal: nome da nova animação

Timer

Contador com sinal.

Membro	O que faz
`start(wait_time: float \| None = None) -> None`	começa a contar (`wait_time` opcional)
`stop() -> None`	para
`timeout`	sinal: quando o tempo acaba

AudioPlayer

Toca um arquivo de áudio.

Membro	O que faz
`play() -> bool`	toca do começo; False se não deu (sem arquivo ou sem áudio)
`stop() -> None`	para
`is_playing`	atributo: está tocando
`effective_volume() -> float`	volume final: `volume × grupo × master`

Camera2D

Câmera do jogo.

Membro	O que faz
`shake(amount: float = 8.0, duration: float = 0.3) -> None`	treme a vista: `camera.shake(amount_px, duration_s)`