Godot Starter Workflow: Build 2D Games with VS Code and the Codex Extension

If you already use VS Code every day, learning Godot does not have to mean adopting a separate coding workflow. A smoother setup is: Godot handles scenes and nodes, VS Code handles GDScript, and the Codex extension helps analyze the project, generate scripts, debug errors, and make small refactors.

This approach does not ask AI to generate a complete game on day one. A steadier method is to build the real node tree in Godot first, then let Codex write scripts around the actual scene structure. That gives it the project layout and reduces wrong guesses about node names and paths.

Recommended split

For VS Code users, the cleanest split is:

Godot: create scenes, nodes, collision shapes, animations, and UI layout.
VS Code: write and manage GDScript.
Codex: analyze the project, generate scripts, debug errors, and make small scoped refactors.
Git: commit after each runnable feature.

In other words, Godot remains the main project editor, VS Code becomes the code workspace, and Codex acts as a collaborative coding assistant.

Install VS Code extensions

Install two extensions in VS Code:

Codex

The official OpenAI extension can read, modify, and run files in the current project. Sign in with your ChatGPT account.

godot-tools

This extension is built for Godot GDScript development. It provides syntax highlighting, completion, go-to-definition, LSP diagnostics, and the ability to launch and debug Godot from VS Code.

Do not rely only on a basic GDScript highlighting extension. Prefer godot-tools.

Make Godot open VS Code

In Godot, open:

1
2
3
4


Editor
→ Editor Settings
→ Text Editor
→ External

Enable:

1

Use External Editor

On Windows, the executable path should point to code.cmd. You can check it in a terminal:

1

where code.cmd

A common result looks like this:

1

C:\Users\your-user-name\AppData\Local\Programs\Microsoft VS Code\bin\code.cmd

Set the execution arguments to:

1

{project} --goto {file}:{line}:{col}

Godot 4.5 and later can usually detect these arguments automatically, but filling them in manually is fine.

Then open:

1
2
3
4
5


Editor Settings
→ Text Editor
→ Behavior
→ Files
→ Auto Reload Scripts on External Change

Enable automatic reload after scripts are modified externally. After that, double-clicking a script in Godot should jump to the matching file and line in VS Code.

Open the project root in VS Code

Do not open only the scripts folder. VS Code should open the project root that contains project.godot.

Recommended structure:

1
2
3
4
5
6
7


my_game/
├─ project.godot
├─ AGENTS.md
├─ scenes/
├─ scripts/
├─ assets/
└─ .vscode/

Open it like this:

1
2


cd D:\GodotProjects\my_game
code .

Then open the same project in Godot.

Godot’s language server usually expects the project to be open in the Godot editor. The default LSP port is 6005, and the DAP debug port is 6006. During normal development, keep Godot open and let VS Code handle code editing.

Configure VS Code debugging

Create this file in the project:

1

.vscode/launch.json

Add:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Run Godot Project",
            "type": "godot",
            "request": "launch",
            "project": "${workspaceFolder}",
            "debugServer": 6006
        }
    ]
}

You can then press F5 in VS Code to launch and debug the game.

If F5 cannot find Godot, search VS Code settings for:

1

godotTools.editorPath.godot4

Set it to your Godot executable path, for example:

1

D:\Programs\Godot\Godot_v4.7-stable_win64.exe

godot-tools supports this setting for the Godot 4 editor path.

Create AGENTS.md

Create AGENTS.md in the project root. Treat it as the project rulebook that Codex reads before making changes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


# Godot Project Instructions

This is a Godot 4.x project using GDScript.

## Coding Rules

- Use only Godot 4.x APIs.
- Do not use old Godot 3.x syntax.
- Prefer static typing in GDScript.
- Use snake_case for variables and functions.
- Use PascalCase for class_name.
- Prefer @onready for node references.
- Use @export for configurable parameters.
- Do not rename existing nodes casually.
- Do not create an overly complex Manager architecture.
- Implement only one independently testable feature at a time.

## File Responsibilities

- scenes/ stores .tscn scenes.
- scripts/ stores .gd scripts.
- assets/ stores images, fonts, and sounds.
- ui/ stores UI scenes and UI scripts.

## Scene Modification Rules

- Before editing .tscn files, read and understand the existing node structure.
- Do not guess node names or NodePath values.
- For complex scenes, prefer telling the user to create nodes manually in the Godot editor.
- Unless the task explicitly asks for it, do not rewrite .tscn files broadly.

## Verification Rules

After finishing a task:

1. Check GDScript syntax.
2. Check resource paths and node paths.
3. List modified files.
4. Explain how to test in Godot.
5. Do not claim it ran successfully unless you actually verified it.

This file is valuable because it defines project boundaries for Codex. It lowers the chance that Codex rewrites scenes, changes architecture, or uses outdated Godot APIs.

Initialize Git first

Run this in the VS Code terminal:

1

git init

Create .gitignore:

1
2
3
4
5


.godot/
.vscode/*.log
*.tmp
export/
build/

Make the first commit:

1
2


git add .
git commit -m "初始化 Godot 项目"

Before letting Codex modify the project, create a Git checkpoint. It makes experiments much easier to roll back.

Make the first project 2D

Even if you know VS Code well, the first Godot project should still start with 2D. Do not begin with a large 3D project, complex UI, or a full RPG system.

A good practice project is:

1

2D top-down shooter prototype

Minimal features:

Player movement
Mouse aiming
Bullet firing
Enemy chasing
Collision damage
Score
Restart

Recommended directory:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


my_game/
├─ project.godot
├─ AGENTS.md
├─ scenes/
│  ├─ main.tscn
│  ├─ player.tscn
│  ├─ bullet.tscn
│  └─ enemy.tscn
├─ scripts/
│  ├─ main.gd
│  ├─ player.gd
│  ├─ bullet.gd
│  └─ enemy.gd
├─ ui/
│  └─ hud.tscn
└─ assets/

First prompt for Codex

In the VS Code Codex panel, do not ask Codex to write code immediately. First ask it to read the project, split the work, and confirm the boundaries.

Use a prompt like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


This is a new Godot 4.x GDScript project.

I want to build a minimal 2D top-down shooter.

Do not modify files yet.

First complete the following:

1. Read project.godot and the current directory structure.
2. Check whether the project already has a main scene configured.
3. Design the minimum viable version.
4. Break the work into small tasks that can each be run and verified independently.
5. Clarify which nodes I should create manually in the Godot editor.
6. Clarify which scripts are suitable for you to write.
7. Use only Godot 4.x APIs.
8. Do not generate the whole game at once.
9. Do not directly write complex .tscn files.

After Codex finishes the analysis, ask it to do only the first feature: player movement.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


Now implement only player movement.

Scene structure:

Player: CharacterBody2D
├─ Sprite2D
└─ CollisionShape2D

Script path:
scripts/player.gd

Requirements:

- Use Input.get_vector
- Use move_and_slide
- Use static typing
- Use @export for movement speed
- Do not rename scene nodes
- Do not implement shooting, health, or animation
- After editing, tell me which Input Map actions I need to configure
- Provide test steps

The key is to do only one feature at a time. The earlier you limit the scope, the easier Codex changes are to verify.

Recommended development loop

Build one feature at a time:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Create nodes in Godot
        ↓
Ask Codex to write scripts in VS Code
        ↓
Review Git diff
        ↓
Press F5 to run
        ↓
Give the full error to Codex
        ↓
Ask for the smallest fix
        ↓
Commit after it runs successfully

For debugging, use this prompt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


The following runtime error occurred:

Paste the full error message

Please identify the root cause first.

Requirements:
- Check the actual node structure and NodePath values;
- Make only the smallest change;
- Do not refactor unrelated code;
- Do not modify features that already work;
- After editing, explain why the error happened.

Do not only say “it errored.” Give Codex the full error, scene structure, and relevant script paths so it can locate the issue.

Codex permission advice

When you first use the Codex extension, start with normal Agent mode.

Do not leave Agent Full Access enabled from the beginning. Normal Agent mode can already read files, modify the project, and run approved commands. Full Access is better used temporarily after you understand the task boundary.

A good starting stack is:

Godot 4.x
GDScript
VS Code
godot-tools
Codex
Git

You do not need to learn C# first, and you do not need Codex to generate an entire scene automatically. Build the node tree in Godot first, then let Codex write scripts around the real node structure. That gives you the highest success rate.