# Uw Unity Debugging

> Systematic 4-phase debugging framework for Unity projects with GameDebug wrapper generation. Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. Triggers on requests like "this doesn't work", "there's a bug", "it crashes when", "fix this error", "why is this happening", "null reference exception", "test is failing", "unexpected behavior", "something broke"…

- **Type:** Skill
- **Install:** `agentstack add skill-devdavv-unity-ai-workflow-uw-unity-debugging`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [devdavv](https://agentstack.voostack.com/s/devdavv)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [devdavv](https://github.com/devdavv)
- **Source:** https://github.com/devdavv/unity-ai-workflow/tree/main/.claude/skills/uw-unity-debugging

## Install

```sh
agentstack add skill-devdavv-unity-ai-workflow-uw-unity-debugging
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Unity Debugging

4-phase debugging framework. Also generates the `GameDebug` wrapper class.

## Before You Start

1. Check if `GameDebug.cs` already exists in the project (search for `class GameDebug`). If not, generate it using the template below during project setup.
2. Read `docs/ProjectConfig.yaml -> mcp.unity_mcp` — if `true`, use `read_console` to read Unity console output.
3. Read `docs/CODING_STANDARDS.md` for async patterns — bugs in async code often involve missing `CancellationToken` or unhandled `OperationCanceledException`.

## 4 Phases

### Phase 1: Gather Evidence
1. Read Unity console (`read_console` via MCP or ask user for errors).
2. Reproduce — exact steps to trigger.
3. Scope — single script, system interaction, or timing?
4. Check `git log -5` for recent changes.

### Phase 2: Isolate
1. Comment out systems to narrow the culprit.
2. Add targeted `GameDebug.Log` at decision points.
3. Check common causes:
   - Execution order (`Awake` vs `Start` vs `OnEnable`)
   - Null reference (destroyed object, unassigned field)
   - Unity API called from background thread
   - State not reset in `OnDisable`/`OnDestroy`
   - Physics in `Update` instead of `FixedUpdate`

### Phase 3: Hypothesize & Test
1. State: *"I believe X happens because Y."*
2. Write a test proving/disproving the hypothesis.
3. If test fails -> back to Phase 2.

### Phase 4: Fix & Verify
1. Implement minimal fix.
2. Re-run the hypothesis test.
3. Run full test suite for regressions.
4. Clean up temp debug logs.
5. Commit: `fix({scope}): {root cause description}`

## GameDebug Wrapper

Generate during project setup. Uses `[Conditional("ENABLE_LOGS")]` so all calls are stripped in release builds. Includes `[CallerFilePath]`, `[CallerMemberName]`, and `[CallerLineNumber]` for automatic context — no need to manually describe where a log came from.

```csharp
using System.Diagnostics;
using System.Runtime.CompilerServices;

public enum LogTopic { General, Gameplay, Audio, UI, Network, Physics, AI }

public static class GameDebug
{
    [Conditional("ENABLE_LOGS")]
    public static void Log(
        string message,
        LogTopic topic = LogTopic.General,
        [CallerFilePath] string file = "",
        [CallerMemberName] string member = "",
        [CallerLineNumber] int line = 0) =>
        UnityEngine.Debug.Log(Format(topic, message, file, member, line));

    [Conditional("ENABLE_LOGS")]
    public static void LogWarning(
        string message,
        LogTopic topic = LogTopic.General,
        [CallerFilePath] string file = "",
        [CallerMemberName] string member = "",
        [CallerLineNumber] int line = 0) =>
        UnityEngine.Debug.LogWarning(Format(topic, message, file, member, line));

    [Conditional("ENABLE_LOGS")]
    public static void LogError(
        string message,
        LogTopic topic = LogTopic.General,
        [CallerFilePath] string file = "",
        [CallerMemberName] string member = "",
        [CallerLineNumber] int line = 0) =>
        UnityEngine.Debug.LogError(Format(topic, message, file, member, line));

    private static string Format(
        LogTopic topic, string msg, string file, string member, int line) {
        var fileName = System.IO.Path.GetFileNameWithoutExtension(file);
        return $"[{topic}] {fileName}.{member}:{line} — {msg}";
    }
}
```

**Usage:** `GameDebug.Log("Player spawned", LogTopic.Gameplay);`
**Output:** `[Gameplay] PlayerController.Start:42 — Player spawned`

Add `ENABLE_LOGS` to Scripting Define Symbols for Development builds only. Customize `LogTopic` enum per project.

## After Debugging

- **Write regression test:** Use `uw-unity-test-runner` to add a test that catches the bug if it reappears.
- **Code review:** Use `uw-code-review` to verify the fix doesn't introduce new issues.
- **Visualize debug data:** Use `uw-unity-editor-tools` to add Gizmos or Handles for spatial debugging (visualize raycast paths, trigger volumes, etc.).

## Rules

- Always follow the 4-phase framework — never jump to a fix before gathering evidence and forming a hypothesis.
- Use `GameDebug` wrapper, never raw `Debug.Log` / `Debug.LogWarning` / `Debug.LogError`.
- Clean up all temporary debug logs after the fix is verified.
- Write a regression test for every bug fix.
- If `ProjectConfig.yaml -> mcp.unity_mcp` is `true`, use `read_console` for console output and `run_tests` to verify fixes.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [devdavv](https://github.com/devdavv)
- **Source:** [devdavv/unity-ai-workflow](https://github.com/devdavv/unity-ai-workflow)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-devdavv-unity-ai-workflow-uw-unity-debugging
- Seller: https://agentstack.voostack.com/s/devdavv
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.