Project and files

A project is a folder of text files. You can open it in any editor and keep it in git.

MyGame/
  project.toml              name, start scene, resolution, audio, input actions
  scenes/main.scene.json    the scene (object tree)
  scripts/player.py         Python scripts
  assets/tiles.png          images, sounds and fonts
  assets/tiles.png.meta     the asset's UUID and import options
  .pgstudio/                editor state (layout, caches): kept out of git
  .venv/                    the project's Python environment: kept out of git

project.toml

This is what the Platformer template uses:

[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 is the game’s logical resolution; the window can be larger and the game is scaled.
• audio sets the volume of each group (master, music, sfx, ui).
• input.actions lists, for each action, the keys, mouse buttons and gamepad buttons that trigger it. The editor edits this under File > Input map….

Scenes

A scene is a readable JSON file with an object tree. Each object has a stable id, type, name, props and 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/player.py", "class": "Player", "fields": {"speed": 240}}],
       "children": []}
    ]
  }
}

• Only properties that differ from the default are saved, with keys in a stable order, so git diffs stay clean.
• A script attached to an object shows up in behaviors, with the values of its export fields.

Assets

Images, sounds and fonts live in assets/. Each one gets a .meta file next to it with a UUID. Scenes point to an asset by UUID (asset:5d0b…), so renaming or moving the file through the Files panel doesn’t break references.

What goes in git

Keep project.toml, scenes/, scripts/ and assets/ (with the .meta files). Leave .venv/ and .pgstudio/ out. The editor already creates a .gitignore with that.

Run without the editor

The game is plain Python on the pgstudio runtime. Inside the project’s environment:

python -m pgstudio run .

See the command line reference.