93 lines
10 KiB
Markdown
93 lines
10 KiB
Markdown
# WL 프로젝트 (힘민지 기반 · What's your level?) — Unity 에디터 제어 가이드
|
||
|
||
Unity **6000.3.23f1** · URP 17.3 · 3D 액션 RPG · 레거시 Input(`activeInputHandler: 0`) · PlayFab(개발 `D1149` · 라이브 `CD90A`) · Addressables 2.x.
|
||
2026-09-05 PD 결정으로 힘민지(`kumatrio/nn_himminji` Dev · 2022.3.55f1)를 WL 의 본체로 채택하고 Unity 6 로 제자리 업그레이드했다.
|
||
조직 규칙·세션 절차의 SOT 는 NerdNavisAi 레포의 `profile-wl` 스킬이고, 이 파일은 **이 프로젝트에서 에이전트가 Unity 에디터를 다루는 방법**만 다룬다.
|
||
시스템 카탈로그(전투·테이블·UI·메타·서버)는 NerdNavisAi `himminji-reuse` 스킬(`references/01~07`)이 이 코드베이스 기준으로 작성돼 있다.
|
||
|
||
## 1. 에디터 제어 = Unity 공식 CLI + Pipeline 패키지 (커뮤니티 unity-mcp 사용 금지)
|
||
|
||
- `com.unity.pipeline` 0.6.0-exp.1 이 manifest 에 있고, 에디터가 켜져 있으면 Pipeline 서버가 자동 기동한다(포트 7800~7849 · 포트·토큰 파일 `Library/Pipeline/.unity-pipeline-port`).
|
||
- 호출 방식 = `unity command <이름> [--인자 값]` 을 Bash/PowerShell 도구로 직접 실행(기본). MCP 서버 `unity` 는 보조 경로.
|
||
- Windows 경로 인자가 들어가는 명령은 **PowerShell** 로. `unity` 를 못 찾으면 이 PC 는 `%LOCALAPPDATA%\Microsoft\WindowsApps\unity.exe`(winget MSIX 별칭).
|
||
- 명령 목록·인자 = `unity command` (이름 없이). CLI 는 베타 — `unity <명령> --help` 로 문법 재확인.
|
||
- 여러 줄 C# 은 `.cs` 파일로 두고 `unity command eval_file --file <경로>` (`using` 불가 · 네임스페이스 풀어 쓰기 · 첫 Roslyn 컴파일은 `--timeout 60`). 대량 작업은 `run_script --file AgentScripts/X.cs --entry X.Run`. 큰따옴표가 든 코드를 `eval --code` 로 밀어 넣지 않는다.
|
||
- 사용 규칙·함정(오브젝트는 `instanceId` 로 지정 · Play 중 `recompile` 금지 · `add/remove_component` 오류 시 `eval_file` 우회 · 프리팹은 `LoadPrefabContents→SaveAsPrefabAsset→UnloadPrefabContents` · `[SerializeField] List<T>` 는 정확한 제네릭 타입 · 캡처는 `Assets/` 밖으로 이동) = NerdNavisAi `profile-wl` 교훈 인덱스. 이 프로젝트는 **레거시 Input** 이라 런타임 입력 주입은 `simulate_pointer`·`simulate_key` 로.
|
||
|
||
## 2. 세션 시작 체크 (순서대로)
|
||
|
||
```powershell
|
||
unity status # 이 프로젝트가 ready 로 보이는지 (포트·PID)
|
||
unity command editor_status # playing / compiling / blocked_by_dialog 확인 (오픈 직후는 --timeout 60)
|
||
unity command set_autotick --enable true # 포커스 없어도 컴파일·테스트 진행 (필수)
|
||
```
|
||
|
||
- `editor_status` 가 `playing` 이면 PD 가 테스트 중일 수 있다 → 리컴파일·Play 전환·씬 저장 전 PD 확인. `blocked_by_dialog` 면 제목·메시지를 PD 에게 보고(CLI 로 못 닫는다).
|
||
- 에디터가 여러 개면 `--project-path E:\NerdNavis\nn_himminji` 로 대상을 고정한다. `unity close` 는 Hub/CLI 로 띄운 에디터만 잡는다.
|
||
- 🔴 **빌드 타겟은 Android 여야 컴파일된다** — `Assets/Script/Info/TitleInfo.cs` 의 `#if UNITY_ANDROID … #else` 분기가 걷어낸 Firebase Auth 를 참조한다. 새 Library 로 열면 Standalone 으로 초기화되니 `unity open <경로> --build-target Android` 또는 `unity command switch_build_target` 로 맞춘다.
|
||
|
||
## 3. 코드 수정 → 검증 루프
|
||
|
||
```powershell
|
||
unity command recompile
|
||
unity command recompile_status # completed | up_to_date 까지 반복 (failed 면 errors 배열 확인)
|
||
unity command get_console_logs --severity error --limit 20
|
||
```
|
||
|
||
- 컴파일 판정 = `recompile_status` completed/up_to_date **이고** 콘솔 error 0 (조직 C39). 도메인 리로드 중 연결 오류는 정상. 종료 코드 2 = 인자 오류, 6 = 에디터 쪽 실패.
|
||
- 콘솔 경고 614줄(테이블 문자열 ↔ enum 불일치 `[Not Defined ePurpose/eStat]` 588 · 걷어낸 SDK 컴포넌트 `referenced script missing` 26)은 레포 데이터 고유 — 에러 판정에서 제외한다.
|
||
|
||
## 4. 게임 시작 절차 (에디터)
|
||
|
||
1. `Assets/Scenes/Title.unity` 에서 Play (Lobby·InGame 씬 직접 Play 는 초기화가 없어 진행되지 않는다).
|
||
2. `MainToTitle` 이 Addressables 로 Title 프리팹 9종을 로드 → `TitleInfo` 가 테이블 로딩 후 `TestID` 입력칸 + `btn_login` 표시 → 버튼을 눌러야 로그인(라이브 `CD90A` → 버전 9.9.9 = dev → `D1149` 재로그인 → CloudScript `Get_UserInfo`).
|
||
3. "화면을 터치해 주세요"(localtext 124) → 클릭 → `SceneManager.LoadScene("Ingame")` → `SceneInfo.Load_AddScene` 이 로비 맵을 Additive 로드.
|
||
- 서버 의존 = PlayFab 타이틀·CloudScript(rev 612 · 소스 `Assets/PlayFabEditorExtensions/Editor/Resources/.CloudScript.js`) · 채팅·로그·쿠폰 서버 URL 은 TitleData `ServerStatus` — 이전 개발자 자산이라 론칭 전 교체 대상.
|
||
- 🔴 진단으로 `Save_LoginToken` 을 호출하지 말 것 — `CurToken` 이 바뀌면 PD 의 실행 중 세션이 「중복 로그인」(localtext 139)으로 종료된다. 읽기 전용 확인은 `LoginWithCustomID(CreateAccount:false)` + `GetTitleData` 까지만.
|
||
|
||
## 5. Play 제어·관찰
|
||
|
||
```powershell
|
||
unity command editor_play # / editor_pause / editor_stop
|
||
unity command capture_game_view --save_path Screenshots_WL/<이름>.png --source screen
|
||
unity command get_scene_hierarchy
|
||
unity command find_gameobjects --type <타입명>
|
||
```
|
||
|
||
## 6. 커스텀 명령
|
||
|
||
- 아직 없음. 구 WL 레포의 `wl_info`·`wl_timescale`·`wl_teleport_player`(`[CliCommand]` 정적 메서드) 패턴을 이 프로젝트의 `Actor`/`PCInfo` 에 맞춰 이식하는 것이 다음 단계. 데이터 값은 코드 상수로 두지 말고 테이블·설정 에셋을 읽는다(C45).
|
||
|
||
## 7. 커스텀 인터페이스 (HTTP + JSON)
|
||
|
||
- 서버 API = `http://127.0.0.1:<port>/api/{status, commands, exec, progress, dialog, job}` · 헤더 `Authorization: Bearer <evalToken>` (포트·토큰 = `Library/Pipeline/.unity-pipeline-port`).
|
||
- 클라이언트 = `Tools/Pipeline/pipeline_client.py` (표준 라이브러리만 · `python Tools/Pipeline/pipeline_client.py serve` → 브라우저 제어판 127.0.0.1:7700).
|
||
|
||
## 8. 커밋·기록
|
||
|
||
- 레포 = Gitea `NerdNavis_AiDev/Project_WL` **`main`**(2026-09-05 힘민지 기반으로 교체 · 원본 이력 `himminji/Dev` · 구 WL 프로토타입 `legacy/wl-prototype-6000`) · 원본 GitLab 은 remote `gitlab`. 구 WL 작업물 백업 = `Backup/WL_Prototype_2026-09-04/`(Assets 밖 · README 참고). 커밋은 PD 확인 후 파일 지정으로만. `Library/`·`Temp/`·`.unity-pipeline-runtime-port`·`Screenshots_WL/` 는 미추적.
|
||
- 에디터가 자동으로 고치는 파일(`PlayFabEditorPrefsSO.asset`·`GvhProjectSettings.xml`·URP 업그레이드로 재직렬화된 `.mat`)은 AI 변경이 아니다 — 커밋 여부는 PD 결정.
|
||
- 작업 결과·교훈은 NerdNavisAi 레포 `공유/대화로그/WL프로젝트/` 와 `profile-wl` 교훈 인덱스에 남긴다.
|
||
|
||
## 9. 병렬 작업 세션 (worktree) — 이 파일은 메인·모든 worktree 세션에 자동 로드된다 (2026-09-07 #802 · PD 승인 후 발효)
|
||
|
||
### Project
|
||
- Unity **6000.3.23f1** · URP 17.3 · 3D 액션 RPG(힘민지 기반) · **모바일 서비스 전제**(URP Balanced 기준 · geometry/tessellation 셰이더 금지 · 삼각형/SetPass 예산 명시 · 인스턴싱·LOD) · 빌드 타겟 **Android 필수** · 레거시 Input · Addressables 2.9.1 · PlayFab(dev `D1149`)
|
||
- UI 기준 해상도 **세로 1080×1920**(Expand) — `ProjectSettings` 방향 전환은 PD 결정 대기 · 한 손 조작 UX
|
||
- 데이터 SOT = `Assets/ResWork/Table/Export/*.json`(butler.xlsm) · 튜닝 값 = `Assets/WL/Settings/Resources/WL/*.asset` · 게임 코드는 asmdef 없이 Assembly-CSharp 단일(어떤 .cs 변경도 전체 리컴파일)
|
||
- PD 게임 비전 = ① 화려한 전투 액션(타격감·카메라·이펙트) ② 쉽고 빠른 성장 · 새로 만들기보다 보유 에셋 활용
|
||
|
||
### Rules (모든 세션 공통)
|
||
- 기존 아키텍처를 유지한다 · 새 Manager/Singleton 을 만들기 전에 기존 구조를 확인한다 · 힘민지 원본(`Assets/Script/**`)은 **1줄 훅 + 새 파일(`Assets/WL/<영역>/`)** 로 확장한다
|
||
- 데이터 값(거리·시간·배율·ID)을 코드 상수로 넣지 않는다 — 테이블·ScriptableObject(C45) · UI 와 Gameplay 로직을 분리한다 · public API 를 임의로 바꾸지 않는다
|
||
- 작업 전에 관련 파일을 먼저 분석한다 · 요청(발주서)에 없는 파일은 수정하지 않는다 · 완료 전 컴파일 게이트 통과 + 콘솔 error 0
|
||
- 실측한 것만 보고하고 미확인은 「미확인」(C23) · 이슈는 자체 결정 없이 Lead 에 보고(C3) · 200k 토큰 초과가 예상되면 멈추고 보고(C57)
|
||
- 상시 제약: 펫 스폰 금지 · 플레이어 무적 유지(임시) · 어그로 금지 · Play 는 Title 에서만 · 데모 씬 Play 금지 · Play 중 에셋 인스턴스 수정 금지
|
||
|
||
### 워커 세션 (cwd = `WL_wt/<gameplay|ui|systems>`) 규칙
|
||
- 역할·소유 경로·핫스팟 = 조직 레포 `공유/WL_병렬작업/ownership_map.json` · 발주서 = `공유/WL_병렬작업/tasks/WL-###.md`(첫 메시지로 경로가 온다) · 프로세스 SOT = `공유/WL_병렬작업/00_WL_병렬개발_프로세스_v1.md`(필요 절만 Read) · 조직 프로필 스킬·코어룰 전수 로드 금지
|
||
- 브랜치 `wl/<role>/WL-###-<slug>` · 커밋은 자기 브랜치에서 자유(`git add <경로 지정>` 만 · `-A` 금지 · 에디터 자동 변경 파일 제외) · **push 금지** · 완료 전 `git rebase main` + 게이트 재통과
|
||
- 컴파일 게이트 = `powershell -File <조직레포>/scripts/wl/wl_compile_gate.ps1 -Project <이 worktree> -Mode oneshot` (헤드리스 슬롯을 받았으면 `-Mode resident` + `unity command --project-path <이 worktree> …`)
|
||
- 메인 에디터(`WL_PROJECT_ROOT` · 포트 7800)는 락 없이 명령 금지 · 자기 worktree 에서 Play 로그인 금지(PlayFab 중복 로그인) · 다른 세션의 worktree 접근 금지
|
||
- 완료 = `공유/WL_병렬작업/reports/WL-###.md`(템플릿 `templates/완료보고.md` · 15줄 + 변경 파일 전수 + 실측 + 미확인) 작성 → Lead 세션에 메시지. 조직 레포 커밋은 Lead 만
|