Find a bug without changing everything
Turn ‘it doesn’t work’ into a repeatable test, a small hypothesis, and an observed result.
First Play Studios · Edition 1 · Updated November 14, 2026
A short bug report and one tested experiment with a clear result.
Before you start- A project with a reproducible problem
- A working backup or version-control checkpoint
In this guide
Make the failure repeatable
Write down the exact starting scene and the shortest steps that produce the problem. ‘Open the delivery room, pick up the parcel, press Deliver twice’ is far more useful than ‘the score is broken.’ Record the expected result and the actual result separately.
Include the engine and version, the relevant error text, and whether the issue happens every time. If it happens only after a second restart, that is evidence. Keep unrelated personal details, credentials, and private files out of screenshots or copied logs. You need the smallest useful example, not your entire computer history.
Look at the first meaningful evidence
Check the debugger or output panel before adding more code. A missing object reference may explain why later steps never run. Godot provides a debugger, runtime inspection, profilers, and collision visualization; use the matching tools in your engine to inspect what the game is doing.
For the double-reward example, temporarily record the event name and score before and after the change. If one click logs two events, investigate duplicate connections. If there is one event but the score jumps by two, investigate the calculation. Remove noisy temporary logging after the problem is understood.
Change one cause and retest
State a hypothesis that could be wrong: ‘The delivery handler is connected twice.’ Make one small change that tests it. Run the same reproduction steps again, then check normal delivery and restart. A disappearance of one symptom is not proof that everything works.
Keep a record of the change, the observed result, and the next question. If an AI suggests several fixes, ask it to explain the evidence for the first one and how to undo it. Avoid piling speculative changes on top of each other; otherwise you cannot tell which one mattered.
Write a useful bug investigation
- Capture a checkpoint and reproduce the problem twice.
- Write three lines: steps, expected, actual. Add the precise version and first relevant error.
- Choose one hypothesis and one small test. Record the observation even if it disproves your idea.
- Retest the original case, a normal case, and restart. Keep or revert the change based on those results.
Check your result.
- Someone else could follow the reproduction steps.
- The result describes what happened, not only ‘fixed’ or ‘failed.’
- You can explain which evidence supports the change.
Common mistakes to watch for.
- Changing code, assets, and project settings in the same experiment.
- Ignoring an earlier error because the last error looks more dramatic.
Keep the conversation useful.
Help me investigate this bug one hypothesis at a time. Here are the engine/version, reproduction steps, expected result, actual result, and first error. Explain the evidence before proposing a change. Give me a small reversible experiment and the checks to run afterward.
Sources & version notes.
General investigation method. The linked Godot documentation describes its available tools; editor workflows have not been run for this guide.
Further reading from the original documentation:
Practice times are estimates. Software-specific exercises are documentation-based unless their version note says otherwise.A question or a small win?
Tell the workshop what happened when you tried this guide. Ask for a useful next step, or share something you got working.
See discussions about this guide We’ll include the guide link in your draft. Sign in to post, then add your own question or progress before sharing.