Projeto e arquivos

Um projeto é uma pasta de arquivos de texto. Você pode abri-la em qualquer editor e versioná-la com o git.

MeuJogo/
  project.toml              nome, cena inicial, resolução, áudio, ações de entrada
  scenes/main.scene.json    a cena (árvore de objetos)
  scripts/jogador.py        scripts em Python
  assets/blocos.png         imagens, sons e fontes
  assets/blocos.png.meta    UUID e opções de importação do asset
  .pgstudio/                estado do editor (layout, caches): fora do git
  .venv/                    ambiente Python do projeto: fora do git

project.toml

É o que o modelo Plataforma usa:

[project]
name = "Plataforma"
start_scene = "scenes/main.scene.json"

[display]
width = 960
height = 540
fps = 60

[audio]
master = 1.0
music = 0.8
sfx = 1.0

[input.actions]
esquerda = ["left", "a", "pad:dpleft", "pad:leftx-"]
direita = ["right", "d", "pad:dpright", "pad:leftx+"]
pular = ["space", "up", "w", "pad:a"]

• display é a resolução lógica do jogo; a janela pode ser maior e o jogo é escalado.
• audio define o volume de cada grupo (master, music, sfx, ui).
• input.actions lista, para cada ação, as teclas, botões do mouse e botões do gamepad que a disparam. O editor edita isso em Arquivo > Mapa de entrada….

Cenas

A cena é um arquivo JSON legível, com uma árvore de objetos. Cada objeto tem um id estável, type, name, props e children:

{
  "format": 1,
  "root": {
    "id": "6f1c…", "type": "Scene", "name": "Main",
    "props": {"background": "#1b1f2a"},
    "children": [
      {"id": "a92e…", "type": "Sprite", "name": "Hero",
       "props": {"position": [128, 320], "texture": "asset:5d0b…"},
       "behaviors": [{"script": "scripts/jogador.py", "class": "Jogador", "fields": {"velocidade": 240}}],
       "children": []}
    ]
  }
}

• Só as propriedades diferentes do padrão são salvas, com as chaves em ordem estável: o diff no git fica limpo.
• Um script preso a um objeto aparece em behaviors, com o valor dos campos export.

Assets

Imagens, sons e fontes ficam em assets/. Cada um ganha um arquivo .meta ao lado, com um UUID. As cenas apontam para o asset pelo UUID (asset:5d0b…), então renomear ou mover o arquivo pelo painel Arquivos não quebra as referências.

O que vai para o git

Versione project.toml, scenes/, scripts/ e assets/ (com os .meta). Deixe .venv/ e .pgstudio/ de fora. O editor já cria um .gitignore com isso.

Rodar sem o editor

O jogo é Python comum sobre o runtime pgstudio. Dentro do ambiente do projeto:

python -m pgstudio run .

Veja a referência da linha de comando.