Your first game

This guide uses only the editor. Each step says what to click and what you should see.

1. Create the project

1. File > New project…, name it “My Game”, pick a folder and the Empty template to start from scratch (or Platformer to open a finished game and poke at it).
2. Wait for the project’s Python environment to be created (it takes a few seconds the first time). The Scene panel shows the game, Explorer shows the object tree and Properties shows the selected object’s properties.

2. Move things with the mouse

• Click an object in the Scene to select it; drag to move; drag the handles to resize or rotate.
• Cmd/Ctrl + mouse wheel zooms; the middle button or Space + drag pans the camera.
• The + button in Explorer inserts objects: Shape, Sprite, Text, TileMap, StaticBody…
• Cmd/Ctrl+Z undoes any edit, including the ones made with the mouse. F1 on a property explains what it does.

3. Add the floor and the player

1. Insert a StaticBody (the floor): position 480, 500, size 800, 40.
2. Insert a KinematicBody (the player): position 480, 100, size 28, 40. Put a Shape inside it so you can see the player.
3. The green (floor) and blue (player) outlines only show in the editor: they are the collision boxes.

4. Write the player script

1. Right-click the KinematicBody and choose Attach script. The file scripts/<name>.py is created and opened.
2. Replace its contents with:

from pgstudio import Behavior, KinematicBody, Vec2, export


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

    def on_ready(self) -> None:
        self.v = Vec2(0, 0)

    def on_update(self, dt: float) -> None:
        self.v.x = self.input.axis("esquerda", "direita") * self.velocidade
        if self.input.pressed("pular") and self.node.on_floor:
            self.v.y = -self.pulo
        self.v.y += 1500 * dt
        self.v = self.node.move_and_slide(self.v, dt)

When you type self.node. the editor suggests what the node has (position, on_floor, move_and_slide…). export fields show up in the node’s Properties and can be tuned without touching the code. (The names velocidade and pulo are Portuguese for speed and jump; the input actions below use the same names.)

5. Say which keys are which action

File > Input map…, then New action for esquerda, direita and pular (left, right, jump). For each one, Record key/button and press the key (or the mouse button, or the gamepad button). Click Save.

6. Play

Run (F5) saves everything and opens the game. If a script raises an error, the game pauses and the error shows in Output with the file and line: click it to jump to the code. Fix it, save (Cmd/Ctrl+S) and the game carries on by itself (hot reload).

7. Next steps

• TileMap: the Paint (B) tool with brush, eraser, bucket and rectangle. Import Tiled maps (.tmx with CSV layers) from the Files panel menu.
• Animation: New animation in the Files panel creates an .anim.json; use AnimatedSprite.
• UI: Canvas, then Panel, Label and Button; lists and grids with UIListLayout and UIGridLayout.
• Sound: drag a .wav or .ogg into the scene; per-group volumes live in [audio] of project.toml.
• Reference for every node: Nodes and properties. Script API: Scripting API.
• Distribute: export the game.