에디터 unfocused 시 dispatch tick이 ~3초로 떨어져 짧은 timeout 호출이 실패함

unity-cli connector — 에디터 unfocused 시 요청 처리 지연 이슈

저장소: youngwoocho02/unity-cli
버전: com.youngwoocho02.unity-cli-connector v0.3.15 (unity-connector path)
보고일: 2026-04-30

---

1. 한 줄 요약

Unity 에디터가 OS 포커스를 잃으면 HTTP 요청 처리 tick 간격이 약 16 ms → 약 3,000 ms 로 떨어져, 짧은 timeout 으로 호출하는 클라이언트가 자주 실패합니다. 포트는 정상 listening, listener 스레드도 살아있지만 dispatch 가 EditorApplication.update 에만 의존하기 때문입니다.

---

2. 환경

항목	값
Unity Editor	6000.4.3f1 (URP, HDRP 동시 설치)
Plugin	com.youngwoocho02.unity-cli-connector v0.3.15 (Git URL 의존성)
OS	Windows 10 Pro 19045
호출 클라이언트	PowerShell 5.1 Invoke-RestMethod (Go HTTP client 도 동일 증상으로 추정)
동시 실행 인스턴스	Unity 에디터 3개 (포트 8090 / 8091 / 8092 자동 할당)

---

3. 사용자가 관찰한 문제

"시간이 지나면 unity-cli connector 연결을 찾지 못하는건지 실행을 못한다."

• 호출 직후에는 응답이 잘 오는데, 잠시 다른 창으로 작업하다 돌아오면 같은 호출이 timeout.
• 재시도하면 또 한참 뒤에 응답 오거나 연속 timeout.
• 에디터를 클릭해 포커스를 줘 두면 한동안 정상.
• Claude Code 의 PreToolUse 훅(check-unity-port.ps1, dataPath 검증) 도 위와 같이 connector 가 응답을 안 줄 때 dataPath 매칭을 건너뛰고 fail-open 됨 → 검증 누락.

---

4. 재현 절차

1. Unity 6000.4.3f1 에디터 1개 실행 → 콘솔에 [UnityCliConnector] HTTP server started on port 8090 확인.

2. 에디터 창을 다른 창 뒤로 보내거나 minimize → OS 포커스 상실.

3. 외부에서 다음 호출을 timeout 2~3 초로 실행:

   $body = '{"command":"exec","params":{"code":"return UnityEngine.Application.dataPath;"}}'
   Invoke-RestMethod -Uri "http://127.0.0.1:8090/command" `
     -Method Post -ContentType "application/json" `
     -Body $body -TimeoutSec 3

   → The operation has timed out.

4. 같은 호출을 -TimeoutSec 30 으로 재시도 → 성공.

---

5. 측정 결과

5번 연속 호출하여 응답에 담긴 Time.realtimeSinceStartup 의 차이를 측정 (에디터 unfocused 상태):

Call	응답 timestamp (s)	Δ (직전 호출 대비)
1	478.140	—
2	481.170	+3.030 s
3	484.230	+3.060 s
4	487.270	+3.040 s
5	490.490	+3.220 s

→ EditorApplication.update 가 평균 3 초마다 1회만 호출됨 (≈ 0.3 Hz).
포커스가 있을 때는 같은 측정이 ms 단위(≈ 60 Hz) 로 나옵니다.

동시에 조회한 에디터 상태 (8090, exec 으로 직접 질의)

isApplicationActive   = False        ← OS 포커스 상실
EditorApplication.isFocused = False
isPlaying / isPaused  = False
isCompiling           = False        ← 도메인 리로드 무관
isUpdating            = False        ← Asset Import 무관
interactionMode       = 1 (NoThrottling)   ← 이미 최적값
runInBackground       = False        ← Player 설정, 에디터엔 무영향

즉 컴파일·Asset Import·Throttling 설정 모두 정상인데도 unfocused 만으로 tick 이 떨어집니다.

---

6. 코드 분석 — Editor/HttpServer.cs

// L47
EditorApplication.update += ProcessQueue;

// L120-124
static void ProcessQueue()
{
    while (s_Queue.TryDequeue(out var item))
        ProcessItem(item);
}

// L210-218 (HandleRequest 내부)
var tcs = new TaskCompletionSource<object>();
s_Queue.Enqueue(new WorkItem { Command = command, Parameters = parameters, Tcs = tcs });
ForceEditorUpdate();              // = InternalEditorUtility.RepaintAllViews()
result = await tcs.Task;          // ← main thread 가 tick 할 때까지 대기

핵심 흐름:

1. HTTP listener (ListenLoop) 는 백그라운드 스레드 — 포트는 항상 listening, OS focus 와 무관.
2. 요청 도착 시 ConcurrentQueue 에 enqueue → main thread 의 EditorApplication.update 콜백에서 dequeue 후 dispatch.
3. ForceEditorUpdate() 가 RepaintAllViews() 를 호출해 update 를 깨우려 시도하지만, 에디터 창이 모두 unfocused / occluded 인 상황에선 OS 가 paint message 를 거의 보내지 않아 효과가 없음.
4. → 결과적으로 응답은 다음 update tick (≈ 3 s 후) 까지 대기.

---

7. 근본 원인

Windows 가 background process 의 timer message resolution 을 강하게 throttle 하고, Unity 에디터의 main loop tick 도 이와 함께 늦춰집니다. Edit > Preferences → General → Interaction Mode = No Throttling 으로 두어도 background 상태에서는 ~3 s 간격이 관찰됩니다 (위 측정 결과).

Connector 의 dispatch 가 main-thread tick 에만 결합되어 있기 때문에, 이 OS-레벨 throttling 이 그대로 응답 latency 로 노출됩니다.

훅(Claude Code PreToolUse) 자체는 정상 동작이며 본 이슈와 무관 — connector 가 응답을 안 줄 때 fail-open 으로 통과하므로 timeout 을 만들지 않음.

---

8. 제안 (수정 후보)

다음 중 하나 또는 조합:

A. delayCall 병행 등록 (가장 작은 변경)

EditorApplication.update    += ProcessQueue;
EditorApplication.delayCall += ProcessQueue;  // 큐에 들어오자마자 즉시 한 번 더 dispatch 시도

delayCall 은 다음 editor message pump 시 한 번 호출되며, 호출 후 자동 해제되므로 enqueue 시마다 다시 등록해야 합니다.

B. enqueue 직후 main-thread tick 강제

ForceEditorUpdate() 를 다음으로 교체 또는 추가:

static void ForceEditorUpdate()
{
    try { EditorApplication.QueuePlayerLoopUpdate(); } catch { }
    try { UnityEditorInternal.InternalEditorUtility.RepaintAllViews(); } catch { }
}

QueuePlayerLoopUpdate() 는 다음 frame 의 PlayerLoop 실행을 강제 예약하여 EditorApplication.update 호출 가능성을 높입니다. (단 background 에선 Windows timer 자체가 늦어 100% 보장은 안 됨.)

C. Background-safe 명령은 main-thread 우회

exec 의 C# 컴파일은 어차피 main thread 가 필요하지만, 상태 조회성 명령 (/version, /ping, dataPath 같은 read-only) 은 main thread 마샬링 없이 listener 스레드에서 직접 응답하면 unfocused 시에도 ms 단위로 응답 가능. → dataPath 검증 훅 같은 정적 query 케이스의 timeout 가능성을 0 으로 만듦.

D. 별도 timer 로 main-thread tick 펌프

System.Threading.Timer 를 listener 활성 동안 가동하여 50–100 ms 간격으로 EditorApplication.QueuePlayerLoopUpdate() 를 호출. 단 idle 시 CPU 비용 증가 → 큐가 비어있을 때 일시 정지하는 분기 필요.

---

9. 클라이언트측 회피책 (참고)

수정 전까지 사용 가능한 우회:

• timeout 을 10 초 이상으로 설정 (-TimeoutSec 30 권장).
• 작업 중 Unity 에디터 창을 다른 모니터에 보이게 두기 (포커스 없어도 visible 이면 paint 가 발생해 tick 빨라짐).
• 동시 실행 에디터 인스턴스 최소화.

---

10. 첨부 가능한 추가 자료

요청 시 제공 가능:

• 8090 / 8091 / 8092 인스턴스의 Editor.log 발췌 (connector start/stop 라인 정상)
• focused 상태에서의 동일 측정 (Δ 가 ms 단위로 떨어지는지 비교)
• [InitializeOnLoad] 도메인 리로드 시 stop/start 동작 로그

---

11. 결론

이슈의 본질은 dispatch 가 EditorApplication.update 단일 경로에만 묶여 있다는 점입니다. Listener 와 큐는 정상 동작하므로 dispatch 트리거를 강화하면 (제안 A + C 권장) unfocused 환경에서도 안정적으로 ms 단위 응답이 가능합니다.

이슈 검토 부탁드립니다 🙏

보고일(2026-04-30)로부터 3일 경과한 오늘(2026-05-03) 동일 환경에서 재측정했습니다.

환경 (오늘 직접 확인)

• com.youngwoocho02.unity-cli-connector v0.3.15 (Packages/manifest.json)
• Unity 6000.4.3f1 / Windows 10
• 측정 시점 상태: InternalEditorUtility.isApplicationActive = False, EditorApplication.isFocused = False

측정 1 — -TimeoutSec 30 으로 5회 연속 호출 (exec 으로 Time.realtimeSinceStartup 반환)

Call	Server t (s)	Δ (직전 대비)	Client latency (ms)
1	881.862	—	2866
2	884.781	+2.92 s	2899
3	887.677	+2.90 s	2895
4	890.602	+2.92 s	2924
5	893.478	+2.88 s	2876

→ unfocused 상태 dispatch 간격이 평균 ≈ 2.9 s 로, 4월 30일 보고 시점(평균 ≈ 3.07 s)과 동일 수준입니다.

측정 2 — -TimeoutSec 2 로 동일 호출 3회

→ 3/3 timeout 실패. (-TimeoutSec 30 은 5/5 성공)

본문 §8 의 제안 A (delayCall 병행 등록) 또는 §8-C (read-only 명령은 listener 스레드 직접 응답) 중 검토 가능성·우선순위가 어떤지 짧게 알려주시면 감사하겠습니다 🙏 추가 로그·재현 스크립트 필요 시 첨부 가능합니다.

[youngwoocho02]

재측정 공유 감사합니다.

우선 v0.3.17에서 가장 작은 변경으로 QueuePlayerLoopUpdate()를 추가해 dispatch wake-up을 보강했습니다. 다만 이 방식은 별도 background 실행 경로가 아니라 Unity Editor main thread가 다시 돌도록 요청하는 수준이라, unfocused 상태의 OS/Editor throttling 영향을 완전히 없애지는 못합니다.

README에도 적어둔 것처럼 Edit → Preferences → General → Interaction Mode → No Throttling 설정을 권장합니다. 이 설정이 background 상태에서 가장 안정적인 응답성을 주지만, 환경에 따라 여전히 지연이 남을 수 있습니다.

delayCall도 결국 editor main thread의 다음 loop에서 실행되는 구조라 같은 throttling 영향을 받을 수 있다고 보고 있습니다.

read-only 명령을 listener thread에서 바로 응답하는 방식은 Unity API를 전혀 건드리지 않는 connector 자체 메타데이터에는 가능하지만, Application.dataPath 같은 Unity API 값은 읽기라도 main thread에서 처리하는 쪽이 맞다고 판단하고 있습니다. 이 범위를 넓히려면 별도 snapshot/cache 구조가 필요해져서 현재 프로젝트 방향상 우선순위는 낮게 보고 있습니다.

가능하시다면 v0.3.17과 No Throttling 설정 상태에서 동일 조건으로 재측정해 주시면 감사하겠습니다.

재측정해 보았습니다.

먼저 한 가지 명확히 하면, 처음 issue 측정 시점부터 Interaction Mode > No Throttling 은 unity-cli 최초 설치 직후 적용해둔 상태였습니다. 이전 측정값 (~3.0 ± 0.2 s) 도 No Throttling 켜진 상태에서 나온 값입니다.

v0.3.18 (QueuePlayerLoopUpdate 포함) + No Throttling 환경에서 8회 측정:

회차	RTT (ms)
1 (warmup)	3389
2 (warmup)	4270
3	3030
4	3022
5	3465
6	3728
7	2963
8	3028

Stable (warmup 2회 제외): avg = 3206 ms, min = 2963 ms, max = 3728 ms

측정 환경:

• Windows 10 Pro (10.0.19045)
• Unity 6000.4.3f1 (DX11)
• unity-cli v0.3.18
• Interaction Mode = No Throttling
• 시뮬레이션: Win32 ShowWindow(hwnd, SW_MINIMIZE) 로 에디터 창 minimize → 4 s 대기 → 8회 연속 exec 호출 → restore (자동화)

→ QueuePlayerLoopUpdate() 보강은 unfocused 상태의 ~3 s deterministic 지연에는 의미 있는 영향이 없는 것으로 보입니다 (이전 v0.3.13 측정과 분포 동일).

말씀하신 대로 main thread loop 만 깨우는 한 OS throttling 자체는 못 푸는 게 자연스러운 결과인 것 같습니다. 우선순위가 낮다는 점은 이해합니다 — 클라이언트 측은 `-TimeoutSec 30` 이상 유지로 회피하고 있습니다. 추가 변경 시 재측정 필요하면 알려주세요.

[youngwoocho02]

v0.4.0에서도 이 부분은 바뀌지 않았습니다.

이전에 말씀드린 대로 QueuePlayerLoopUpdate()는 메인 스레드를 깨우는 요청일 뿐이고, unfocused일 때 OS/Editor가 틱을 줄이는 한계는 그대로입니다. read-only를 listener 스레드에서 바로 응답하는 쪽은 Unity API를 건드리지 않는 커넥터 메타데이터 외에는 우선순위를 낮게 보고 있습니다.

클라이언트는 지금처럼 timeout을 충분히 두는 쪽으로 가주시면 됩니다. 이 이슈는 알려진 한계로 열어 두겠습니다.

[youngwoocho02]

v0.4.0 기준으로 이쪽 환경에서 다시 재봤습니다.

이미 요청이 들어오면 QueuePlayerLoopUpdate()와 RepaintAllViews()로 메인 루프를 깨우고 있습니다. Windows 11 + Unity 6000.3.22f1에서 exec 5회:

• focused: 평균 1002ms (964–1061)
• unfocused (앞에 다른 창, 최소화 아님): 평균 1325ms
• minimized: 평균 1347ms

최소화 중에도 heartbeat는 0.5초마다 갱신됐습니다. 보고하신 ~3초 간격은 재현되지 않았습니다.

이전에 말씀드린 판단은 그대로입니다. delayCall도 같은 메인 스레드 스로틀을 타고, Unity API를 listener 스레드에서 읽는 건 우선순위가 낮습니다. 보고하신 Windows 10 최소화 + EcoQoS 쪽 3초는 OS/Editor 한계로 보고, 클라이언트는 timeout을 충분히 두는 쪽으로 가주시면 됩니다. 이 이슈는 알려진 한계로 열어 두겠습니다.