[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CBD12H62C365BYD1XDJRGP":3,"skill-same:01M6CBD12H62C365BYD1XDJRGP":46},{"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":21,"linkOnly":22,"markdownContent":23,"markdownBody":23,"frontMatter":24,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":13,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M6CBD12H62C365BYD1XDJRGP","18-voice-table-resolve",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\u002F22-sound-package\u002F18-voice-table-resolve\u002FSKILL.md",[],[18,19,20],"voice","table","18 voice table resolve","2026-11-10 10:12:30",false,"# 18-voice-table-resolve\n\nStatus: ACTIVE\nAppliesTo: v10\nType: Component\n\n## Purpose\n\nVoice는 TB_VOICE 단일 테이블을 **로딩 시점에 \"현재 언어용 맵\"으로 Resolve 캐시**하고, 재생 시점에는 캐시 조회만 한다.\n\n---\n\n## Domain Ownership\n\n- VoiceManager는 **Sound 도메인 소유**이다.\n- TB_VOICE 테이블은 Sound 도메인에 귀속된다.\n- SoundVoiceTableRegistry를 통해 VoiceManager와 TB_VOICE가 연결된다.\n- 자세한 도메인 구조는 `19-sound-domain\u002FSKILL.md` 참조.\n\n---\n\n## Hard Rules\n\n### SystemLanguage 사용 제한 (가장 중요)\n\n- **SystemLanguage는 로딩\u002F초기화(Resolve) 단계에서만 사용한다.**\n- **재생 시점에 SystemLanguage로 분기하는 메서드는 금지.**\n  - 금지 예: `GetClipPath(SystemLanguage lang)`\n- Voice 재생은 **voice_id → IVoiceRow 캐시 맵을 통해서만** 수행한다.\n\n### 언어 변경 시 처리\n\n- 언어 변경 시에는 **캐시를 재구성**한다.\n- 필요하다면 관련 사운드 로딩 정책도 갱신한다.\n\n### 테이블 분리 금지\n\n- TB_VOICE는 단일 테이블을 유지한다.\n- `VOICE_ko`, `VOICE_en` 같은 언어별 테이블 분리 금지.\n\n### VOICE 독립 운용 (SOUND 미참조, Hard Rule)\n\n- **VOICE는 SOUND 테이블을 참조하지 않는다.**\n- **Resolve 결과는 sound_id가 아니라 clipPath(AudioClip 에셋 경로\u002F키)**이다.\n- clip 경로는 IVoiceRow.TryGetClipColumn()으로 직접 조회한다.\n- sound_id 매핑 방식은 더 이상 사용하지 않는다.\n- 언어 fallback 대상도 sound_id가 아니라 **clipPath**이다.\n- VOICE 테이블의 key_bundle로 직접 번들 로드.\n\n### VOICE 독립 로딩 규약 (Hard Rule)\n\n- VoiceManager는 SOUND 테이블\u002Frow_id\u002Fsound_id에 의존하지 않는다.\n- **로드\u002F언로드는 `key_bundle` 단위로만 수행**한다 (key_group 제거됨).\n- voice_id → clipPath 캐시\u002F해결 흐름:\n  1. ResolveForLanguage()에서 voice_id → IVoiceRow 캐시 구성\n  2. IVoiceRow.TryGetClipColumn()으로 clipPath 조회\n  3. clipPath로 AudioClip 로드\n\n### Voice 로딩 책임 (Hard Rule)\n\n- **VoiceManager가 Voice clip 로딩을 담당한다.**\n- SoundManager는 Voice 채널을 로드하지 않는다.\n- `LoadByBundleKeyAsync(bundleKey, language, fallbackLanguage)`로 key_bundle 단위 로드.\n- Resolve 결과로 나온 IVoiceRow들만 로드한다.\n- 언로드는 `UnloadByBundleKey(bundleKey)`로 수행.\n\n### runtime_id 기반 재생 (Hard Rule)\n\n- **PlayVoice()는 SoundRuntimeId를 반환한다.**\n- 모든 재생 제어(Stop\u002FPause\u002FResume)는 runtime_id로 수행한다.\n- SoundPlay\u002FAudioSource를 외부에 노출하지 않는다.\n\n### 3D Voice Play (Hard Rule)\n\n- **PlayVoice3D(voiceId, position)** API를 제공한다.\n- 3D 파라미터는 IVoiceRow의 distance_near\u002Fdistance_far에서 가져온다.\n- BaseAudioManager를 통해 재생한다.\n- Linear rolloff, doppler=0 적용.\n- **3D 적용 조건**: `effective3d = row.is3d && position.HasValue`\n\n### VOICE 테이블 상수 (Hard Rule)\n\nVOICE는 아래 값을 테이블 컬럼 없이 코드에서 상수로 반환한다:\n- `isBundle = true` (항상 Bundle)\n- `channel = SoundChannelType.Voice` (항상 Voice)\n- `loop = false` (항상 비루프)\n- `volume_scale = 1f`\n- `pitch_min = 1f`, `pitch_max = 1f`\n\n> VOICE는 isBundle\u002Fchannel\u002Floop 컬럼을 테이블에 두지 않고 코드에서 상수로 간주한다.\n\n---\n\n## Resolve Policy\n\n### 로딩 단계 수행 내용\n\n```csharp\n\u002F\u002F 1. 현재 언어에 해당하는 컬럼명 결정\nstring col = \"clip_\" + currentLanguage.ToString();  \u002F\u002F 예: \"clip_Korean\"\n\n\u002F\u002F 2. 모든 TB_VOICE row 순회\nforeach (var row in TB_VOICE.All())\n{\n    \u002F\u002F 3. 해당 언어 컬럼에서 clip 경로 읽기\n    if (!row.TryGetClipColumn(col, out var clipPath))\n    {\n        \u002F\u002F 4. 비어있으면 fallback 적용\n        if (!row.TryGetClipColumn(\"clip_English\", out clipPath))\n        {\n            \u002F\u002F 5. 둘 다 없으면 경고 후 스킵\n            continue;\n        }\n    }\n\n    \u002F\u002F 6. 캐시 생성 (voice_id → IVoiceRow)\n    _resolvedVoiceRows[row.voice_id] = row;\n}\n```\n\n### 테이블 컨테이너 접근 방식\n\n- **Reflection 금지** (성능\u002FGC 문제)\n- 컬럼명 → 값 해석은 `TryGetClipColumn()` switch문으로 수행\n- 지원 언어 컬럼만 switch로 매칭 (Korean, English, Japanese, Chinese)\n- **중국어 통합**: `SystemLanguage.Chinese` → `clip_Chinese` (간체\u002F번체 구분 없음)\n\n---\n\n## Loading Policy\n\n### LoadByBundleKeyAsync \u002F UnloadByBundleKey (Hard Rule)\n\n```csharp\n\u002F\u002F Voice 로드 (key_bundle 기반)\nawait VoiceManager.Instance.LoadByBundleKeyAsync(\n    \"voice_battle\",              \u002F\u002F TB_VOICE.key_bundle\n    SystemLanguage.Korean,       \u002F\u002F 언어\n    SystemLanguage.English       \u002F\u002F fallback 언어\n);\n\n\u002F\u002F Voice 언로드\nVoiceManager.Instance.UnloadByBundleKey(\"voice_battle\");\n```\n\n- **로드\u002F언로드는 `key_bundle` 단위로만 수행**한다 (key_group 제거됨).\n- 반드시 **ResolveForLanguage() 호출 후**에 사용한다.\n- key_bundle에 해당하는 voice rows에서 Resolve된 IVoiceRow만 로드.\n- 내부적으로 `SoundManager._loadVoiceClipsAsync()` 호출.\n- 언로드 시 `AssetManager.UnloadBundleAssets(bundleKey)` 호출.\n\n### LoadByBundleKeysAsync \u002F UnloadByBundleKeys (벌크)\n\n```csharp\nawait VoiceManager.Instance.LoadByBundleKeysAsync(\n    new[] { \"voice_battle\", \"voice_ui\" },\n    SystemLanguage.Korean,\n    SystemLanguage.English\n);\nVoiceManager.Instance.UnloadByBundleKeys(new[] { \"voice_battle\", \"voice_ui\" });\n```\n\n### 로드 순서 (중요)\n\n1. `ResolveForLanguage(language)` - 전체 TB_VOICE Resolve\n2. `LoadByBundleKeyAsync(bundleKey, language, fallback)` - 필요한 voice clip 로드\n3. `PlayVoice(voiceId)` - 재생 (캐시 조회만)\n\n---\n\n## Playback API\n\n### PlayVoice\n\n```csharp\n\u002F\u002F 반환: runtime_id (재생 실패 시 Invalid)\nSoundRuntimeId PlayVoice(\n    string voiceId,\n    float volume = 1f,\n    float pitch = 0f,   \u002F\u002F 0이면 row 기반 (VOICE는 항상 1f)\n    int groupId = 0\n)\n```\n\n- voice_id → IVoiceRow 캐시 조회\n- SoundManager._playVoiceInternal(voiceRow, ...) 호출\n- **반환값**: SoundRuntimeId (재생 실패 시 `SoundRuntimeId.Invalid`)\n\n### 재생 제어 (runtime_id 기반)\n\n```csharp\nbool StopVoice(SoundRuntimeId runtimeId)\nbool PauseVoice(SoundRuntimeId runtimeId)\nbool ResumeVoice(SoundRuntimeId runtimeId)\nbool IsVoicePlaying(SoundRuntimeId runtimeId)\n```\n\n- 모든 제어는 runtime_id로 수행\n- 내부적으로 SoundManager의 해당 메서드 호출\n\n### 자막 처리\n\n```csharp\npublic string? GetCaptionKey(string voiceId)\n{\n    \u002F\u002F voice_id 자체를 자막 키로 사용\n    return voiceId;\n}\n```\n\n- 자막 키는 voice_id 자체를 사용한다 (별도 컬럼 불필요).\n- 자막 표시 시스템 자체는 이 스킬 범위 외.\n\n### 3D Play API\n\n```csharp\n\u002F\u002F 3D Voice 재생\nSoundRuntimeId PlayVoice3D(\n    string voiceId,\n    Vector3 position,\n    float volume = 1f,\n    float pitch = 0f,\n    int groupId = 0\n)\n```\n\n- voice_id → IVoiceRow 캐시 조회\n- SoundManager._playVoiceInternal(voiceRow, ..., position) 호출\n- 3D 파라미터는 IVoiceRow.distance_near\u002Fdistance_far 사용\n- Linear rolloff, doppler=0\n\n---\n\n## Failure Policy\n\n### voice_id 없음 또는 clip resolve 실패 시\n\n**기본 정책 (개발 중 생산성 우선):**\n- 경고 로그 출력\n- 재생 스킵 (SoundRuntimeId.Invalid 반환)\n\n**프로젝트 선택 옵션:**\n- 빌드 실패 정책으로 전환 가능 (릴리즈 빌드용)\n\n---\n\n## Usage Examples\n\n```csharp\n\u002F\u002F 1. 초기화 시점 (언어 Resolve)\nVoiceManager.I.ResolveForLanguage(SystemLanguage.Korean);\n\n\u002F\u002F 2. Voice clip 로드 (key_bundle 기반)\nawait VoiceManager.I.LoadByBundleKeyAsync(\n    \"voice_battle\",\n    SystemLanguage.Korean,\n    SystemLanguage.English\n);\n\n\u002F\u002F 벌크 로드\nawait VoiceManager.I.LoadByBundleKeysAsync(\n    new[] { \"voice_battle\", \"voice_ui\" },\n    SystemLanguage.Korean,\n    SystemLanguage.English\n);\n\n\u002F\u002F 3. 재생 시점 (runtime_id 반환)\nvar runtimeId = VoiceManager.I.PlayVoice(\"VO_TUTORIAL_001\");\n\n\u002F\u002F 4. runtime_id로 제어\nVoiceManager.I.PauseVoice(runtimeId);\nVoiceManager.I.ResumeVoice(runtimeId);\nVoiceManager.I.StopVoice(runtimeId);\n\n\u002F\u002F 5. 재생 상태 확인\nif (VoiceManager.I.IsVoicePlaying(runtimeId))\n{\n    \u002F\u002F 재생 중...\n}\n\n\u002F\u002F 6. 자막 키 조회 (voice_id 자체가 키)\nstring captionKey = VoiceManager.I.GetCaptionKey(\"VO_TUTORIAL_001\");\nstring subtitle = StringTable.Get(captionKey);\n\n\u002F\u002F 7. 3D Voice 재생 (Linear rolloff)\nvar runtimeId3D = VoiceManager.I.PlayVoice3D(\"VO_TUTORIAL_001\", transform.position);\n\n\u002F\u002F 8. 언로드 (key_bundle 기반)\nVoiceManager.I.UnloadByBundleKey(\"voice_battle\");\nVoiceManager.I.UnloadByBundleKeys(new[] { \"voice_battle\", \"voice_ui\" });\n\n\u002F\u002F 9. 언어 변경 시 (Resolve 재수행 필요)\nVoiceManager.I.ResolveForLanguage(SystemLanguage.English);\n\u002F\u002F + 필요한 bundle들 다시 로드\n```\n\n---\n\n## Non-goals\n\n- TB_SOUND\u002FTB_VOICE 테이블 컬럼 규약은 `16-sound-tables` 스킬에서 다룬다.\n- SoundManager 자체의 채널\u002F풀\u002F쿨타임 규약은 `17-sound-manager` 스킬에서 다룬다.\n\n---\n\n## See Also\n\n- `skills\u002Fdevian-unity\u002F22-sound-package\u002F19-sound-domain\u002FSKILL.md` — **Sound 도메인 설계 (SSOT)**\n- `skills\u002Fdevian-unity\u002F22-sound-package\u002F16-sound-tables\u002FSKILL.md` — TB_SOUND\u002FTB_VOICE 테이블 규약\n- `skills\u002Fdevian-unity\u002F22-sound-package\u002F17-sound-manager\u002FSKILL.md` — SoundManager 규약\n- `skills\u002Fdevian-unity\u002F22-sound-package\u002F20-base-audio-manager\u002FSKILL.md` — BaseAudioManager 공통 Play 규약\n- `skills\u002Fdevian-unity\u002F20-common-package\u002F31-table-manager\u002FSKILL.md` — TableManager (테이블 로딩)\n",{},"main","8cb5bd877a3a7004867d2f55697cb9e4ff2f1734","skills\u002Fdevian-unity\u002F22-sound-package\u002F18-voice-table-resolve","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":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add devwinsoft\u002Fdevian --skill 18-voice-table-resolve",{"tool":38,"command":39},"bunx","bunx skills add devwinsoft\u002Fdevian --skill 18-voice-table-resolve",{"tool":41,"command":42},"pnpm","pnpm dlx skills add devwinsoft\u002Fdevian --skill 18-voice-table-resolve","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian-unity\u002F22-sound-package\u002F18-voice-table-resolve\u002FSKILL.md",true,[],[47,53,61,69,78,85],{"skillNo":48,"name":49,"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":50,"categories":51,"keywords":52,"publishedAt":21},"01M6CBX3K2JJV38ANHVGCAT8A0","devian","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002FSKILL.md",[],[49],{"skillNo":54,"name":55,"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":56,"categories":57,"keywords":58,"publishedAt":21},"01M6CBX210BFMM8AMN770J9WY8","90-project-archive","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F90-project-archive\u002FSKILL.md",[],[59,60],"archive","90 project archive",{"skillNo":62,"name":63,"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":64,"categories":65,"keywords":66,"publishedAt":21},"01M6CBWZSGRR9R3YJZB3177667","30-env-management","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F30-env-management\u002FSKILL.md",[],[67,68],"management","30 env management",{"skillNo":70,"name":71,"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":72,"categories":73,"keywords":74,"publishedAt":21},"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",[],[75,76,77],"push","page","19 page push send",{"skillNo":79,"name":80,"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":81,"categories":82,"keywords":83,"publishedAt":21},"01M6CBWWRQ05A7604GHJKTPJTF","18-page-savedata","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F18-page-savedata\u002FSKILL.md",[],[76,84],"18 page savedata",{"skillNo":86,"name":87,"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":88,"categories":89,"keywords":90,"publishedAt":21},"01M6CBWVH4S2VF1V7B2GBTESCT","17-page-deobfuscate","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F17-page-deobfuscate\u002FSKILL.md",[],[76,91],"17 page deobfuscate"]