Scripts e Behavior

Como escrever o comportamento de um objeto em Python: a classe Behavior, os campos export e o ciclo de vida de cada quadro.

Um script é um arquivo .py do projeto com uma classe que herda de Behavior. A classe fica presa a um objeto da cena e o objeto fica disponível em self.node.

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:
        mover = Vec2(self.input.axis("esquerda", "direita") * self.velocidade, 0)
        self.node.move_and_slide(mover, dt)

Behavior[KinematicBody] diz ao editor qual é o tipo de self.node, e o autocomplete passa a sugerir move_and_slide, on_floor e o resto. Sem o argumento, class Jogador(Behavior) tipa self.node como Node2D.

Anexar um script a um objeto

Clique com o botão direito no objeto no Explorer e escolha Anexar script, ou use o botão Anexar script da aba Código da ribbon. O arquivo é criado em scripts/ e aberto no editor de código.

Campos exportados

Um campo marcado com export(...) aparece no painel Properties do objeto, e o valor escolhido fica salvo na cena:

velocidade: float = export(240.0, min=0)

O primeiro argumento é o valor padrão. Os demais (como min) descrevem o campo para o editor. O editor lê esses campos olhando o código, sem executá-lo.

Ciclo de vida

Método	Quando roda
`on_ready()`	Uma vez, quando o jogo começa ou a cena troca. Pais antes dos filhos.
`on_update(dt)`	Todo quadro, com `dt` em segundos.
`on_draw(surface)`	Todo quadro, depois do desenho, com a superfície do pygame para desenhar por cima.
`on_input(event)`	Para cada evento do pygame (teclado, mouse…).

A ordem de cada quadro é: entrada, on_update, física, câmera e desenho (ordenado por camada, z e posição na árvore), com a UI por cima.

O que o script enxerga

self.node: o objeto a que o script está preso.
self.scene: a cena, com find, tween, change_scene e set_volume.
self.input: o mapa de entrada, com pressed, held, released e axis.

A lista completa de membros está na API de scripts.

Executar e recarregar

O jogo roda num processo separado: se ele travar, o editor continua de pé, e Parar só encerra esse processo, sem tocar na cena que você está editando. Quando um script dá erro, o jogo pausa e o erro aparece no Output com o arquivo e a linha. Ao salvar o script, o hot reload recarrega o módulo e o jogo continua.