AI 에이전트로 Unity BatchMode 점검 봇 만들기: 씬 품질 리포트를 매일 자동 생성하기

게임 프로젝트가 커질수록 문제는 코드보다 콘텐츠에서 먼저 터집니다. 씬에 비활성화된 테스트 오브젝트가 남아 있거나, 라이트가 누락되거나, 프리팹 이름 규칙이 깨진 상태로 머지되면 빌드 직전까지 아무도 모르는 경우가 많습니다.

이때 AI 보조 도구를 단순 코드 작성기가 아니라 반복 점검 봇 제작 도우미로 쓰면 효과가 큽니다. 사람이 “우리 팀 씬 규칙은 이렇다”고 설명하면, AI가 Unity BatchMode에서 돌릴 수 있는 Editor 스크립트 초안을 만들고, 우리는 그 결과를 팀 규칙에 맞게 다듬습니다.

핵심은 Unity Editor를 열지 않고도 명령줄에서 씬을 검사하고, JSON 리포트를 남기는 구조입니다. CI에 붙이기도 쉽고, 매일 아침 자동 실행해 콘텐츠 품질을 확인하기도 좋습니다.

1. AI에게 줄 규칙은 코드보다 먼저 정리한다

AI에게 바로 “씬 검사기 만들어줘”라고 하면 결과가 넓고 흐릿해집니다. 먼저 규칙을 짧게 나열하는 편이 좋습니다.

예를 들면 다음 정도면 충분합니다.

• 씬 안에 이름이 Temp_로 시작하는 오브젝트가 있으면 경고
• Main Camera가 없으면 오류
• Directional Light가 2개 이상이면 경고
• Missing Script가 있으면 오류
• 결과는 JSON으로 저장
• Unity BatchMode에서 실행 가능해야 함

이 규칙을 프롬프트로 넣고, “Editor 전용 코드로 작성해 달라”고 요청하면 초안 품질이 올라갑니다.

2. BatchMode 진입점 만들기

Unity에서 명령줄 실행용 코드는 static 메서드로 두는 것이 단순합니다. 아래 코드는 씬 하나를 열고 검사한 뒤 리포트를 저장하는 기본 구조입니다.

using System;
using System.Collections.Generic;
using System.IO;
using UnityEditor;
using UnityEditor.SceneManagement;
using UnityEngine;
using UnityEngine.SceneManagement;

public static class SceneAuditRunner
{
    [Serializable]
    public sealed class AuditReport
    {
        public string scenePath = "";
        public List<string> errors = new();
        public List<string> warnings = new();
    }

    public static void Run()
    {
        string scenePath = GetArg("-scene");
        string outputPath = GetArg("-out", "SceneAuditReport.json");

        var report = new AuditReport { scenePath = scenePath };

        EditorSceneManager.OpenScene(scenePath, OpenSceneMode.Single);
        Scene scene = SceneManager.GetActiveScene();

        AuditScene(scene, report);

        string json = JsonUtility.ToJson(report, true);
        File.WriteAllText(outputPath, json);

        if (report.errors.Count > 0)
            EditorApplication.Exit(1);

        EditorApplication.Exit(0);
    }

    static string GetArg(string key, string fallback = "")
    {
        string[] args = Environment.GetCommandLineArgs();

        for (int i = 0; i < args.Length - 1; i++)
        {
            if (args[i] == key)
                return args[i + 1];
        }

        return fallback;
    }
}

AI가 자주 놓치는 부분은 종료 코드입니다. 오류가 있으면 Exit(1)로 끝내야 CI에서 실패로 잡을 수 있습니다. 리포트만 만들고 항상 성공 처리하면 자동화 가치가 크게 떨어집니다.

3. 실제 씬 규칙 검사 넣기

검사 로직은 팀마다 다르지만, 처음에는 명확한 규칙부터 넣는 것이 좋습니다. 아래 예시는 카메라, 조명 개수, 임시 오브젝트, Missing Script를 확인합니다.

static void AuditScene(Scene scene, AuditReport report)
{
    var roots = scene.GetRootGameObjects();

    int cameraCount = 0;
    int directionalLightCount = 0;

    foreach (var root in roots)
    {
        foreach (var t in root.GetComponentsInChildren<Transform>(true))
        {
            GameObject go = t.gameObject;

            if (go.name.StartsWith("Temp_", StringComparison.Ordinal))
                report.warnings.Add($"Temp object remains: { GetPath(t) }");

            if (go.GetComponent<Camera>() != null)
                cameraCount++;

            var light = go.GetComponent<Light>();
            if (light != null && light.type == LightType.Directional)
                directionalLightCount++;

            var components = go.GetComponents<Component>();
            foreach (var component in components)
            {
                if (component == null)
                    report.errors.Add($"Missing script: { GetPath(t) }");
            }
        }
    }

    if (cameraCount == 0)
        report.errors.Add("Main scene has no Camera.");

    if (directionalLightCount > 1)
        report.warnings.Add($"Too many Directional Lights: {directionalLightCount}");
}

static string GetPath(Transform t)
{
    var names = new Stack<string>();

    while (t != null)
    {
        names.Push(t.name);
        t = t.parent;
    }

    return string.Join("/", names);
}

여기서 AI에게 맡기기 좋은 부분은 규칙 추가입니다. “NavMeshAgent가 있는데 NavMeshSurface가 없는 씬을 경고해줘”, “UI Canvas에 GraphicRaycaster가 빠졌는지 봐줘”처럼 한 규칙씩 추가시키면 안정적입니다.

반대로 프로젝트 전체 구조 판단, 예외 규칙, 실패 기준은 개발자가 결정해야 합니다. AI가 만든 자동화는 팀의 의도를 반영해야지, 팀 규칙을 대신 정하면 안 됩니다.

4. 명령줄 실행 형태 고정하기

CI나 로컬 자동화에서 중요한 것은 실행 명령이 항상 같아야 한다는 점입니다.

Unity \
  -batchmode \
  -quit \
  -projectPath . \
  -executeMethod SceneAuditRunner.Run \
  -scene Assets/Scenes/Main.unity \
  -out Reports/SceneAuditReport.json

이 명령을 스크립트로 고정해 두면 AI에게도 “이 명령으로 성공해야 한다”고 검증 조건을 줄 수 있습니다. 그러면 AI 보조 도구가 코드를 수정할 때 목표가 분명해집니다.

결론

AI 보조 게임 개발의 장점은 거대한 기능을 한 번에 만드는 데만 있지 않습니다. 사람이 매번 눈으로 확인하던 반복 점검을 작은 BatchMode 도구로 바꾸는 데서도 큰 효과가 납니다.

씬 품질 리포트 자동화는 구조가 단순하고 효과가 즉시 보입니다. 규칙을 문장으로 정리하고, AI에게 Editor 스크립트 초안을 만들게 한 뒤, 개발자가 실패 기준과 예외 처리를 다듬으면 실무에 바로 붙일 수 있습니다. 매일 같은 검사를 같은 방식으로 돌리는 것만으로도 빌드 직전의 불확실성을 꽤 줄일 수 있습니다.