[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CBC4XRN6WVVFYVV2BDHBKP":3,"skill-same:01M6CBC4XRN6WVVFYVV2BDHBKP":44},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":13,"repositoryHtmlUrl":26,"repositoryHomepageUrl":6,"ownerHtmlUrl":27,"ownerBlogUrl":6,"ownerDescription":28,"updatedAt":29,"install":30,"resources":43},"01M6CBC4XRN6WVVFYVV2BDHBKP","32-unity-utils",null,"devwinsoft\u002Fdevian","devwinsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F22570160?v=4","01M6C6RR8W05NH8NPKQNCE3Q72","maoshy","01M6C6RRDJ5TJJCZXRTY801YDH",0,"MIT","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian-unity\u002F20-common-package\u002F32-unity-utils\u002FSKILL.md",[],[18],"32 unity utils","2026-11-10 10:12:30",false,"# 32-unity-utils\n\nStatus: ACTIVE\nAppliesTo: v11\n\n## SSOT\n\n이 문서는 `com.devian.foundation\u002FRuntime\u002FUnity\u002F_Shared\u002F`에 위치한 Unity 공용 유틸리티들의 규약을 정의한다.\n\n---\n\n## 목표\n\n- Unity 메인 스레드 강제 보장 유틸리티 제공\n- 백그라운드 스레드에서 메인 스레드로 작업을 디스패치하는 큐 시스템 제공\n- Coroutine → async\u002Fawait 브릿지 제공 (UnityCoroutineRunner)\n- Unity `void` 진입점에서 fire-and-forget `Task` 예외를 관측하는 유틸 제공 (UnityTaskRunner)\n\n---\n\n## 파일 위치 및 소유권\n\n### 소스 파일\n\n| 파일 | 설명 |\n|------|------|\n| `com.devian.foundation\u002FRuntime\u002FUnity\u002F_Shared\u002FUnityMainThread.cs` | 메인 스레드 감지 헬퍼 |\n| `com.devian.foundation\u002FRuntime\u002FUnity\u002F_Shared\u002FUnityMainThreadDispatcher.cs` | 백그라운드→메인 스레드 디스패처 |\n| `com.devian.foundation\u002FRuntime\u002FUnity\u002F_Shared\u002FUnityCoroutineRunner.cs` | Coroutine→Task 브릿지 |\n| `com.devian.foundation\u002FRuntime\u002FUnity\u002F_Shared\u002FUnityTaskRunner.cs` | Unity `void` entry point용 fire-and-forget Task 관측기 |\n\n### 소유권 정책 (Hard Rule)\n\n**`Runtime\u002F_Shared`는 고정 유틸(수기 코드) 영역이다.**\n\n| 항목 | 정책 |\n|------|------|\n| 정본 | `framework-cs\u002Fupm\u002Fcom.devian.foundation\u002FRuntime\u002FUnity\u002F_Shared\u002F` |\n| 복사본 | `framework-cs\u002Fapps\u002FUnityExample\u002FPackages\u002Fcom.devian.foundation\u002FRuntime\u002FUnity\u002F_Shared\u002F` |\n| 생성기 | `Runtime\u002FGenerated\u002F**`만 다룸 — `_Shared`는 건드리지 않음 |\n\n> **Note:** 생성기는 `Runtime\u002F_Shared`를 clean\u002Fgenerate 하지 않는다. 이 파일들은 수기 유지되며, 빌더가 upm → Packages로 패키지 레벨 복사(sync)를 수행한다.\n>\n> **Reference:** `skills\u002Fdevian-unity\u002F03-ssot\u002FSKILL.md`\n\n---\n\n## 규약\n\n### UnityMainThread\n\n- `internal static class`\n- **초기화 타이밍 (Hard Rule):**\n  - `[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]`로 메인 스레드 ID 캡처\n  - SubsystemRegistration은 BeforeSceneLoad보다 **더 이른 시점**에 실행됨\n  - 초기값: `s_mainThreadId = 0` (미초기화 상태)\n\n- **메서드:**\n  - `InitIfNeeded()`: 미초기화 상태(`s_mainThreadId == 0`)면 현재 스레드 ID로 초기화. 여러 번 호출해도 안전.\n  - `IsMainThread` 속성: 현재 스레드가 메인 스레드인지 반환. 자동으로 `InitIfNeeded()` 호출.\n  - `EnsureOrThrow(string context)`: 메인 스레드가 아니면 예외 발생. 자동으로 `InitIfNeeded()` 호출.\n\n- **초기화 전 EnsureOrThrow 호출 (Hard Rule):**\n  - `EnsureOrThrow` 내부에서 `InitIfNeeded()`를 먼저 호출하여 초기화 전 오판 방지\n\n```csharp\n\u002F\u002F 현재 구현\npublic static void EnsureOrThrow(string context)\n{\n    InitIfNeeded();  \u002F\u002F 미초기화면 현재 스레드로 초기화\n\n    if (s_mainThreadId != Thread.CurrentThread.ManagedThreadId)\n    {\n        throw new InvalidOperationException(...);\n    }\n}\n```\n\n### UnityMainThreadDispatcher\n\n- `internal sealed class : MonoBehaviour`\n- `[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]`로 자동 생성\n- 숨김 GameObject + `DontDestroyOnLoad` + 중복 생성 방지\n- `ConcurrentQueue\u003CLogItem>` 사용 (스레드 안전)\n- `Enqueue(LogItem)`: 백그라운드 스레드에서 호출 가능\n- `Update()`에서 큐 소비 → `Debug.Log*` 호출\n- **maxPerFrame 제한 (500)**: 프레임당 최대 처리량 제한으로 폭주 방지\n\n### LogItem\n\n- `internal readonly struct`\n- 필드: `Level`, `Message`\n\n### UnityCoroutineRunner\n\n- `public static class`\n- Coroutine을 `Task`로 변환하여 async 메서드에서 `await` 가능하게 하는 브릿지\n\n- **메서드:**\n  - `RunAsync(MonoBehaviour host, IEnumerator routine, CancellationToken ct = default)`: Coroutine 실행 후 완료 시 Task resolve\n    - `TaskCompletionSource\u003Cbool>`로 Coroutine 완료를 Task로 변환\n    - `CancellationToken` 지원: 취소 시 `StopCoroutine` + `TrySetCanceled`\n    - `host`는 `StartCoroutine` 호출에 필요한 MonoBehaviour 인스턴스\n\n- **사용 패턴:**\n```csharp\nawait UnityCoroutineRunner.RunAsync(this, FadeOut(canvasGroup, 0.5f), ct);\n```\n\n### UnityTaskRunner\n\n- `public static class`\n- Unity `Start()`, UI 버튼 `OnClick()` 같은 `void` 진입점에서 `Task`를 fire-and-forget로 실행할 때 사용\n- `async void` 본문 대신 `Task` 메서드로 분리하고, 예외 관측\u002F로그를 공용화한다\n\n- **메서드:**\n  - `Run(Task task, string operation)`: 이미 생성된 `Task`를 관측하고 실패 시 `Debug.LogError` 출력\n  - `Run(Func\u003CTask> taskFactory, string operation)`: `Task` 생성 전 동기 예외까지 포함해 관측\n  - `Run\u003CTArg>(Func\u003CTArg, Task> taskFactory, TArg arg, string operation)`: 1개 인자를 전달하여 `Task` 생성 + 관측\n  - `Run\u003CTArg1, TArg2>(Func\u003CTArg1, TArg2, Task> taskFactory, TArg1 arg1, TArg2 arg2, string operation)`: 2개 인자를 전달하여 `Task` 생성 + 관측\n  - 일반적으로는 `Run(Func\u003CTask>, ...)` 또는 `Run\u003CTArg>(...)` 오버로드를 우선 사용한다\n\n- **사용 패턴:**\n```csharp\n\u002F\u002F 인자 없음\npublic void OnClick_Login()\n{\n    UnityTaskRunner.Run(OnClickLoginAsync, \"UICanvasLoading.OnClick_Login\");\n}\n\nprivate async Task OnClickLoginAsync()\n{\n    await LoginAsync();\n}\n\n\u002F\u002F 1-arg\npublic void OnClick_GoogleLogin()\n{\n    UnityTaskRunner.Run(OnClickLoginAsync, \"google\", \"UICanvasLoading.OnClick_GoogleLogin\");\n}\n\nprivate async Task OnClickLoginAsync(string provider)\n{\n    await LoginAsync(provider);\n}\n\n\u002F\u002F 2-arg\npublic void OnClick_Send()\n{\n    UnityTaskRunner.Run(OnClickSendAsync, userId, message, \"UIBaseCanvas.OnClick_Send\");\n}\n\nprivate async Task OnClickSendAsync(string userId, string message)\n{\n    await SendAsync(userId, message);\n}\n```\n\n- **의도 (Hard Rule):**\n  - Unity `void` entry point에서 `async void`를 직접 구현하지 않는다\n  - 내부 로직은 `Task` 메서드로 분리하고, wrapper는 `UnityTaskRunner`로 연결한다\n\n---\n\n## 의존 관계\n\n```\nUnityMainThread           ← Singleton, Pool, PoolManager (EnsureOrThrow 사용)\nUnityMainThreadDispatcher ← UnityLogSink (백그라운드 로그 디스패치)\nUnityCoroutineRunner      ← SceneTransManager 등 Coroutine→Task 브릿지\nUnityTaskRunner           ← UIBaseCanvas, SceneBase, SceneTransManager 의 void entry point\n```\n\n---\n\n## DoD (완료 정의) — Hard Gate\n\n- [ ] `com.devian.foundation\u002FRuntime\u002FUnity\u002F_Shared\u002FUnityMainThread.cs` 존재\n- [ ] `com.devian.foundation\u002FRuntime\u002FUnity\u002F_Shared\u002FUnityMainThreadDispatcher.cs` 존재\n- [ ] `com.devian.foundation\u002FRuntime\u002FUnity\u002F_Shared\u002FUnityCoroutineRunner.cs` 존재\n- [ ] `com.devian.foundation\u002FRuntime\u002FUnity\u002F_Shared\u002FUnityTaskRunner.cs` 존재\n- [ ] UPM 경로와 UnityExample\u002FPackages 경로의 파일 내용이 동일함\n- [ ] Dispatcher는 `maxPerFrame` 제한(500)을 가짐\n- [ ] Unity API 호출(`Debug.Log*`)은 메인 스레드에서만 수행됨\n- [ ] UnityMainThread 캡처 타이밍이 `SubsystemRegistration`임\n- [ ] `EnsureOrThrow`가 `InitIfNeeded()`를 먼저 호출하여 초기화 전 오판 방지\n- [ ] UnityCoroutineRunner가 CancellationToken 지원\n- [ ] Unity `void` entry point의 fire-and-forget `Task`가 `UnityTaskRunner`로 예외 관측됨\n\n**FAIL 조건:**\n\n- `_Shared` 파일이 UPM과 Packages에서 불일치\n- `_Shared` 밖에 유틸 파일이 위치함\n- 초기화 전 `EnsureOrThrow` 호출 시 false negative 발생\n\n---\n\n## 금지\n\n- `_Shared` 파일을 Packages에서 직접 수정 금지 (정본은 upm)\n- Dispatcher를 별도 패키지로 분리 금지\n- `_Shared` 유틸을 `_Shared` 밖으로 이동 금지\n\n---\n\n## Reference\n\n- Related: `skills\u002Fdevian\u002F10-module\u002F03-ssot\u002FSKILL.md` (Foundation Package SSOT)\n- Related: `skills\u002Fdevian\u002F10-module\u002F20-core\u002F12-logger\u002FSKILL.md`\n- Related: `skills\u002Fdevian-unity\u002F03-ssot\u002FSKILL.md` (소유권 정책)\n",{},"main","8cb5bd877a3a7004867d2f55697cb9e4ff2f1734","skills\u002Fdevian-unity\u002F20-common-package\u002F32-unity-utils","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian","https:\u002F\u002Fgithub.com\u002Fdevwinsoft","Kim Hyong Joon","2026-04-12 18:44:10",{"source":7,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add devwinsoft\u002Fdevian --skill 32-unity-utils",{"tool":36,"command":37},"bunx","bunx skills add devwinsoft\u002Fdevian --skill 32-unity-utils",{"tool":39,"command":40},"pnpm","pnpm dlx skills add devwinsoft\u002Fdevian --skill 32-unity-utils","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian-unity\u002F20-common-package\u002F32-unity-utils\u002FSKILL.md",true,[],[45,51,59,67,76,83],{"skillNo":46,"name":47,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":48,"categories":49,"keywords":50,"publishedAt":19},"01M6CBX3K2JJV38ANHVGCAT8A0","devian","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002FSKILL.md",[],[47],{"skillNo":52,"name":53,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":19},"01M6CBX210BFMM8AMN770J9WY8","90-project-archive","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F90-project-archive\u002FSKILL.md",[],[57,58],"archive","90 project archive",{"skillNo":60,"name":61,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":19},"01M6CBWZSGRR9R3YJZB3177667","30-env-management","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F30-env-management\u002FSKILL.md",[],[65,66],"management","30 env management",{"skillNo":68,"name":69,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M6CBWYD3TGWBQV7V35551THF","19-page-push-send","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F19-page-push-send\u002FSKILL.md",[],[73,74,75],"push","page","19 page push send",{"skillNo":77,"name":78,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M6CBWWRQ05A7604GHJKTPJTF","18-page-savedata","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F18-page-savedata\u002FSKILL.md",[],[74,82],"18 page savedata",{"skillNo":84,"name":85,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M6CBWVH4S2VF1V7B2GBTESCT","17-page-deobfuscate","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F17-page-deobfuscate\u002FSKILL.md",[],[74,89],"17 page deobfuscate"]