anthropic-skills/unity3d-enhanced/examples/quick-fixes.md

Unity Quick Fixes Reference

This guide provides quick, copy-paste solutions for common Unity problems. For detailed explanations, see the reference files.

---

Input System Issues

Fix: Input System Exception

Error: InvalidOperationException: You are trying to read Input using the UnityEngine.Input class...

One-line fix: Change in ProjectSettings/ProjectSettings.asset:

activeInputHandler: 2  # Enable both input systems

Via Editor: Edit → Project Settings → Player → Active Input Handling → Both → Restart Unity

→ Details: reference/input-systems.md

---

GUID Errors

Fix: Invalid GUID in Prefab

Error: Could not extract GUID in text file Assets/Prefabs/MyPrefab.prefab

Quick fix:

# 1. Find correct GUID
grep "^guid:" Assets/Scripts/MyScript.cs.meta

# 2. Replace in prefab file
# Old: guid: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
# New: guid: 6004172616168c346951d6f4cddd83da (from step 1)

→ Details: reference/guid-system.md

Fix: Orphaned Meta Files

Error: Broken PPtr [guid]...

Quick fix:

# Find and remove orphaned .meta files
for meta in Assets/**/*.meta; do
    [ -f "${meta%.meta}" ] || git rm "$meta"
done

→ Details: reference/guid-system.md

---

URP Issues

Fix: Camera Data is Null

Error: Camera data is null. Please ensure the render pipeline is correctly initialized...

Quick fix: Change in .unity scene file (search for camera):

m_RendererIndex: 0  # Changed from -1

Or create new camera: GameObject → Camera (Unity handles setup automatically)

→ Details: reference/urp-setup.md

Fix: Pink Materials

Symptom: Materials appear bright pink/magenta

Quick fix: Edit → Render Pipeline → URP → Upgrade Project Materials to URP Materials

Or manually: Change shader from Standard to Universal Render Pipeline/Lit

→ Details: reference/urp-setup.md

---

Physics Issues

Fix: Bullets Missing Targets

Problem: Fast bullets pass through colliders

Quick fix: Use triggers on targets:

// Target script
private void OnTriggerEnter(Collider other)
{
    if (other.gameObject.layer == bulletLayer)
    {
        Explode();
    }
}

Setup:

• Target: IsTrigger = true, needs Rigidbody
• Bullet: Solid collider, Rigidbody with velocity

→ Details: reference/physics-system.md

Fix: Triggers Not Detecting

Problem: OnTriggerEnter never called

Quick fix checklist:

• At least one object has Rigidbody
• Collider has IsTrigger = true
• Layer collision matrix enabled (Edit → Project Settings → Physics)
• Method signature exact: void OnTriggerEnter(Collider other)

→ Details: reference/physics-system.md

Fix: Rigidbody Velocity (Unity 2023.1+)

Warning: 'Rigidbody.velocity' is obsolete...

Quick fix: Find & Replace

// Find:    rb.velocity
// Replace: rb.linearVelocity

→ Details: reference/physics-system.md

---

NullReferenceException Fixes

Fix: Unassigned SerializeField

Error: NullReferenceException at line using SerializeField

Quick fix: Add null check

[SerializeField] private Transform target;

void Start()
{
    if (target == null)
    {
        Debug.LogError($"{name}: Target not assigned!");
        return;
    }
    // Use target safely
}

Better: Use OnValidate to catch at edit-time

private void OnValidate()
{
    if (target == null)
        Debug.LogWarning($"{name}: Target not assigned!");
}

→ Details: reference/common-errors.md

Fix: GetComponent Returns Null

Quick fix: Use TryGetComponent

// ❌ Unsafe
Rigidbody rb = GetComponent<Rigidbody>();
rb.linearVelocity = Vector3.zero;  // Crash if no Rigidbody!

// ✓ Safe
if (TryGetComponent<Rigidbody>(out var rb))
{
    rb.linearVelocity = Vector3.zero;
}

→ Details: reference/common-errors.md

---

Resources Loading

Fix: Resources.Load Returns Null

Problem: File exists but Resources.Load returns null

Quick fix: Move file to Resources folder

Assets/
  Resources/  ← Must be named exactly "Resources"
    Data/
      config.json  ← Your file here

Load without extension:

// File at: Assets/Resources/Data/config.json
TextAsset data = Resources.Load<TextAsset>("Data/config");

→ Details: reference/common-errors.md

---

Compiler Warnings

Fix: CS0414 (Field Never Used)

Warning: Field 'MyClass.field' is assigned but its value is never used

Quick fix: Actually use the field

[SerializeField] private float speed = 5f;

void Update()
{
    // Use it!
    transform.position += transform.forward * speed * Time.deltaTime;
}

→ Details: reference/common-errors.md

---

Git and Meta Files

Quick Commands

# Check for orphaned .meta files
for meta in Assets/**/*.meta; do
    [ -f "${meta%.meta}" ] || echo "Orphaned: $meta"
done

# Find assets missing .meta files
find Assets -type f ! -name "*.meta" ! -path "*/.*" | while read file; do
    [ -f "$file.meta" ] || echo "Missing .meta: $file"
done

# Stage asset and meta together
git add Assets/NewScript.cs Assets/NewScript.cs.meta

# Remove deleted asset's meta
git rm Assets/DeletedScript.cs.meta

→ Details: reference/guid-system.md

---

Code Snippets

Null-Safe GetComponent

// Safe component access pattern
if (TryGetComponent<T>(out var component))
{
    // Use component
}
else
{
    Debug.LogError($"{name} missing {typeof(T)} component!");
}

Input System Device Check

// New Input System - always null-check devices
using UnityEngine.InputSystem;

private Keyboard keyboard;

void Update()
{
    if (keyboard == null)
    {
        keyboard = Keyboard.current;
        if (keyboard == null) return;
    }

    if (keyboard.spaceKey.wasPressedThisFrame)
    {
        Jump();
    }
}

Object Pooling Pattern

public class ObjectPool : MonoBehaviour
{
    [SerializeField] private GameObject prefab;
    private Queue<GameObject> pool = new Queue<GameObject>();

    public GameObject Get()
    {
        if (pool.Count > 0)
        {
            GameObject obj = pool.Dequeue();
            obj.SetActive(true);
            return obj;
        }
        return Instantiate(prefab);
    }

    public void Return(GameObject obj)
    {
        obj.SetActive(false);
        pool.Enqueue(obj);
    }
}

Trigger Detection with Layers

[SerializeField] private LayerMask targetLayers;

private void OnTriggerEnter(Collider other)
{
    // Check if other object is in target layers
    if (((1 << other.gameObject.layer) & targetLayers) != 0)
    {
        // Handle trigger
    }
}

URP Camera Creation

using UnityEngine;
using UnityEngine.Rendering.Universal;

void CreateCamera()
{
    GameObject camObj = new GameObject("Main Camera");
    Camera cam = camObj.AddComponent<Camera>();

    // Required for URP
    UniversalAdditionalCameraData cameraData =
        camObj.AddComponent<UniversalAdditionalCameraData>();

    camObj.tag = "MainCamera";
}

---

Project Settings Quick Checks

Input System Configuration

# Check current setting
grep "activeInputHandler:" ProjectSettings/ProjectSettings.asset

# Should be:
# activeInputHandler: 0  (Legacy only)
# activeInputHandler: 1  (New only)
# activeInputHandler: 2  (Both - recommended)

URP Verification

# Check if URP asset assigned
grep "m_CustomRenderPipeline:" ProjectSettings/GraphicsSettings.asset

# Should reference URP asset, not "m_CustomRenderPipeline: {fileID: 0}"

Meta Files Validation

# Check project configured for text serialization
grep "m_ExternalVersionControlSupport:" ProjectSettings/EditorSettings.asset

# Should be: m_ExternalVersionControlSupport: Visible Meta Files

---

Emergency Troubleshooting

Nuclear Options (Use with Caution!)

Clear Library (forces reimport of all assets):

# Close Unity first!
rm -rf Library/
# Reopen Unity - will regenerate Library/

Reimport All Assets:

• Assets → Reimport All
• Use when: Meta files corrupted, import settings broken

Reset Project Settings:

• Manually delete ProjectSettings/ (backup first!)
• Unity regenerates default settings

Note: Always backup before using these!

---

Platform-Specific Quick Fixes

Android

Fix: Missing SDK/NDK

• Edit → Preferences → External Tools → Browse to Android SDK/NDK paths

Fix: API Level Too Low

• Player Settings → Android → Minimum API Level → 24 (Android 7.0)

iOS

Fix: Bundle Identifier Invalid

• Player Settings → iOS → Bundle Identifier → com.company.appname

Fix: Missing Camera Permission

• Player Settings → iOS → Camera Usage Description → "Required for AR features"

---

Performance Quick Wins

// Cache transforms
private Transform myTransform;
void Awake() { myTransform = transform; }

// Use CompareTag instead of ==
if (other.CompareTag("Player"))  // Faster

// Disable cameras you're not using
camera.enabled = false;

// Use object pooling for frequently spawned objects
// (see Object Pooling Pattern above)

// Set Rigidbodies to sleep when idle
rb.Sleep();

// Use layer collision matrix
// Edit → Project Settings → Physics → Layer Collision Matrix

---

Diagnostic Commands

# Find all invalid GUIDs
grep -Ern "guid: [^0-9a-f]" Assets/

# List all cameras in scenes
grep -n "m_Name: Main Camera" Assets/Scenes/*.unity

# Find all Resources folders
find Assets -type d -name "Resources"

# Check Unity version
grep "m_EditorVersion:" ProjectSettings/ProjectVersion.txt

---

When All Else Fails

1. Read the error carefully - the answer is often in the message
2. Check the line number - exact location of the problem
3. Google the exact error - others have likely solved it
4. Unity Forums / Stack Overflow - active communities
5. Check Unity documentation - official API reference
6. Review recent changes - git diff to see what changed
7. Start fresh - create minimal reproduction case

---

Reference File Index

Issue Category	Reference File
GUIDs, meta files, asset references	reference/guid-system.md
Input System, API migration	reference/input-systems.md
Rigidbody, triggers, collisions	reference/physics-system.md
URP, cameras, rendering	reference/urp-setup.md
Common error catalog	reference/common-errors.md
Project setup, workflows	reference/project-setup.md