Codex / Antigravity 타워디펜스 만드는 중 사용 한 플랜 예시

디펜스 만드는 중 플랜 짜는 예시를 공유하면 좋을 것 같아서 끄적끄적 올려봅니다.

1. 초안 계획을 AI에 플랜을 세우라고 내용 명시
2. 해당 플랜을 gpt -> gemini -> claude -> gpt...로 더 이상 보완 할 게 없을 때까지 문서강화.
3. 해당플랜으로 task.md 제작. 이후 플랜과 task를 이용하여 작업 진행.

Codex에서 플랜 초안을 작성

다른 AI에게 문서 보완을 지시

플랜이 마음에 들때까지 반복. Google Flow로 이미지 제작.

이렇게 계속 진행하면 다음과 같은 플랜이 나오고 진행합니다.

Google Flow에서 생성한 이미지

타워슬롯_폴백제거_시각화_계획_2026_02_23.md

0.02MB

타워슬롯 폴백 제거 + 슬롯 시각화 적용 계획 (2026-02-23)

0. 목표

• 타워 슬롯이 없는 맵은 자동 폴백 생성 없이 에러로 중단해 데이터 누락을 즉시 드러낸다.
• 타워 건설 가능 위치를 유저가 인지할 수 있도록 슬롯 위치에 안내 이미지를 표시한다.
• 해당 슬롯에 타워가 건설되면 슬롯 안내 이미지는 즉시 숨긴다.

1. 범위

In Scope

• GameBattlefield / TowerManager / GameScene의 타워 슬롯 검증 흐름 정리
• 타워 슬롯 시각화 런타임 오브젝트(또는 프리팹) 표시/숨김 규칙 적용
• 슬롯 안내 이미지(스프라이트) 제작용 AI 프롬프트 작성
• QA 체크리스트 및 롤백 포인트 문서화

Out of Scope

• 타워 전투 로직(사거리/공격/스킬) 변경
• UI TowerRingMenu 배치/레이아웃 개편
• 슬롯 개수 자동 배치 알고리즘 도입

2. 현재 기준 동작(상세)

2-1) 폴백 슬롯 생성 지점 (제거 대상 2곳)

#	파일	메서드	동작
1	GameBattlefield.cs	EnsureRuntimeDefaults()	towerRoot.childCount == 0이면 CreateDefaultTowerSlots(towerRoot) 호출 → 3개 좌표 자동 생성
2	TowerManager.cs	Configure()	_towerSlots.Count == 0이면 하드코딩 좌표 3개 직접 추가

2-2) 슬롯 데이터 흐름

GameScene.ConfigureEconomyAndTower()
 └─ _battlefield.GetTowerSlotPositions()   ← towerRoot 하위 Transform → List<Vector3>
     └─ RebuildTowerSlotsIfNeeded()        ← towerRoot childCount로 리빌드
 └─ _towerManager.Configure(..., towerSlots, ...)
     └─ _towerSlots에 복사 → RebuildFreeSlots() → _freeSlotIndices 초기화

2-3) 빌드/판매 시 슬롯 상태 변경 흐름

• 빌드: TryBuildTowerAtSlot() → _freeSlotIndices.Remove(slotIndex)
• 판매: TrySellTower() → _freeSlotIndices.Add(tower.SlotIndex) + Sort
• 슬롯 검색: TryFindBuildableSlotAtWorldPosition(worldPos, maxDist) → 거리 기반 가장 가까운 free 슬롯 반환

2-4) 현재 시각 안내

• 별도 슬롯 마커 오브젝트 없음. 유저가 빈 슬롯 위치를 직관적으로 파악할 수 없음.

3. 변경 계획

[참조] NotebookLM 인사이트 (Kingdom Rush UI/UX 원칙)

• Snappy Feedback (Juice): 타워 슬롯 클릭 시 즉각적인 시각/청각 피드백이 필요하다. 타워 메뉴가 열리기 전이나 동시에 슬롯 자체의 반응(예: hover 시 밝아짐, 클릭 시 살짝 눌림 또는 먼지 파티클)을 주어 조작감을 높여야 한다.
• 맵과의 조화: 슬롯은 맵의 일부처럼 자연스럽게 무언가 지어질 기반(Dirt, Stone Base 등)으로 녹아들어야 하며, 상호작용 가능한 오브젝트임을 명확히 보여야 한다.

Phase A. 슬롯 폴백 제거 + 에러 처리

변경 대상

파일	변경 내용
GameBattlefield.cs	EnsureRuntimeDefaults(): towerRoot.childCount == 0 분기에서 CreateDefaultTowerSlots() 호출을 에러 로그로 교체
GameBattlefield.cs	CreateDefaultTowerSlots(): 메서드 자체 삭제 또는 [Obsolete] 처리
TowerManager.cs	Configure(): _towerSlots.Count == 0 시 하드코딩 좌표 추가 블록 → Debug.LogError + enabled = false 로 교체

에러 메시지 예시

[TowerManager] 타워 슬롯 0개 감지. GameBattlefield.TowerRoot 하위에 슬롯(자식 Transform)을 1개 이상 배치하세요.

완료 기준 (DoD)

• 슬롯 없는 씬에서 폴백 슬롯이 생성되지 않는다.
• 콘솔에 명확한 에러가 출력되고, 타워 건설 UI가 열리지 않는다.

Phase B. 슬롯 시각화(가이드 이미지) 표시

1. 슬롯 월드 좌표마다 SlotMarker 표시 오브젝트 생성(스프라이트 렌더러 기반).
2. 기본 상태: free slot만 표시.
3. 카메라/배경 대비를 고려한 정렬 레이어/소팅오더 지정 (예: Background Layer의 최상단).
4. 시각 톤 및 작동 피드백 (Juice 반영):
   • 과도한 강조 대신 맵과 조화되는 은은한 기초 플랫폼/돌 판 형태
   • Idle(기본): 약간의 Sine 파동 스케일 또는 알파 깜빡임으로 "여기 뭔가 지을 수 있음" 시각 암시
   • Hover(마우스/터치 오버): 스프라이트 밝기 증가(Material Color/플래시) 혹은 외곽선 점등으로 상호작용 가능성 암시
   • Click(클릭): 스케일(Scale)이 살짝 줄었다 커지는 펀치 효과(Punch Scale)로 타격감 제공

완료 기준 (DoD)

• 전투 시작 시 빈 슬롯에만 마커가 보인다.
• 슬롯 위치와 메뉴 오픈 위치가 사용자 체감상 일치한다.

Phase C. 타워 건설 시 슬롯 이미지 숨김

1. TryBuildTowerAtSlot 성공 시 해당 슬롯 마커 숨김.
2. 타워 판매 시 슬롯이 다시 free 되면 마커 재표시.
3. 타워 업그레이드 시: 슬롯 점유 상태 불변 → 마커 상태 변경 없음 (숨김 유지).
4. 초기 동기화 보강:
   • 로드/재시작 시 현재 점유 상태와 마커 표시 상태를 일치시킴.
5. 마커 표시/숨김 트랜지션 정책:
   • P0(최소 구현): SetActive로 즉시 On/Off (트랜지션 없음).
   • P1(확장): 건설 성공 시 알파 페이드아웃 → SetActive(false) / 판매 시 알파 페이드인 → SetActive(true). 스프라이트 Color.a Lerp 기반.

완료 기준 (DoD)

• 건설 성공 즉시 해당 슬롯 마커가 사라진다.
• 판매 후 해당 슬롯 마커가 다시 보인다.
• 업그레이드 시 마커가 재표시되지 않는다.
• 중복 표시/잔상 없음.

4. 구현 포인트(상세 설계)

4-1) 신규 클래스: TowerSlotVisualizer

• 파일: Assets/Scripts/Kingdom/Game/TowerSlotVisualizer.cs
• 책임: 슬롯 마커 오브젝트의 생성/표시/숨김 관리 (단일 책임)

[구조 스케치]
TowerSlotVisualizer : MonoBehaviour
├── [SerializeField] Sprite slotMarkerSprite   ← 기본 슬롯 마커 스프라이트
├── [SerializeField] int sortingOrder = -5     ← 타워 아래, 배경 위 정렬
├── List<GameObject> _markers                  ← 생성된 마커 오브젝트 목록
├── List<SpriteRenderer> _renderers            ← 렌더러 캐싱 (Color/알파 제어용)
├── Update() 혹은 Coroutine                    ← Mathf.Sin 기반의 저비용 Idle 애니메이션(알파/스케일 깜빡임) 구동
├── Initialize(IReadOnlyList<Vector3> slotPositions)
│   └─ 슬롯 좌표별 마커 생성, SpriteRenderer/Transform 캐싱
├── ShowMarker(int slotIndex)
│   └─ GameObject.SetActive(true)
├── HideMarker(int slotIndex)
│   └─ GameObject.SetActive(false)
├── RefreshAll(HashSet<int> freeSlotIndices)
│   └─ 모든 마커를 freeSlotIndices 기준으로 일괄 동기화
└── Cleanup()
    └─ 모든 마커 오브젝트 Destroy

4-2) TowerManager 이벤트 추가

기존 TryBuildTowerAtSlot/TrySellTower 메서드에 이벤트 발행 코드 추가:

public event System.Action<int> OnSlotOccupied;   // 빌드 성공 시 slotIndex 전달
public event System.Action<int> OnSlotFreed;       // 판매 성공 시 slotIndex 전달

4-3) GameScene Wiring 변경

ConfigureEconomyAndTower() 내부에 다음 흐름 추가:

1. TowerSlotVisualizer 생성 또는 GetComponent
2. visualizer.Initialize(towerSlots)
3. _towerManager.OnSlotOccupied += visualizer.HideMarker
4. _towerManager.OnSlotFreed += visualizer.ShowMarker

이벤트 해제 (메모리 누수 방지):

• TowerSlotVisualizer.OnDisable() 또는 Cleanup()에서 반드시 이벤트 구독 해제:

  _towerManager.OnSlotOccupied -= HideMarker;
  _towerManager.OnSlotFreed -= ShowMarker;

• 씬 전환/재시작 시 Cleanup() → 이벤트 해제 → 마커 Destroy 순서 보장.

4-4) 에셋 규칙 (프로젝트 리소스 폴더 구조 준수)

에셋	경로	추가 옵션 (가이드)
슬롯 마커 스프라이트	Assets/Resources/UI/Sprites/Game/tower_slot_marker.png	PPU: 맵 타일과 동일 비율(예: 100), Mesh Type: Full Rect
슬롯 마커 프리팹 (선택)	Assets/Resources/UI/SlotMarker.prefab	-

4-5) Sorting 규칙

레이어/오더	대상	값 (권장)
Sorting Layer	Default 또는 전용 SlotGuide	—
Order in Layer	슬롯 마커	-5 (배경 위, 타워/유닛 아래)
Order in Layer	타워 본체	0 ~ 10 (기존)

4-6) 에디터 전용 슬롯 검증 도구 (선택)

• 목적: 씬 저장/빌드 시 TowerRoot 하위 슬롯 0개를 사전에 감지하여 런타임 에러를 방지.
• 구현 방식: IProcessSceneWithReport 또는 커스텀 MenuItem 활용.
• 출력: 슬롯 누락 씬 이름 + 수정 힌트 콘솔 경고.
• 분류: Disposable Tool (일회성 Editor 스크립트) 또는 상시 유지 선택 가능.

5. 나노바나나(AI) 이미지 생성 프롬프트

5-1) 기본 프롬프트

Top-down 2D isometric tower-defense build slot foundation, hand-painted kingdom rush style,
clean stylized fantasy stone platform or wooden dirt base, subtle magical glowing runes, 
transparent background, centered composition, no text, no characters,
readable on grass and dirt map, highly detailed game asset, vibrant colors, 1:1.

5-2) 변형 프롬프트 (밝은 맵용)

Top-down 2D isometric build slot indicator for tower defense, hand-painted kingdom rush art style, 
carved stone circle with clear outline, minimal magical glow, 
transparent background, no text, no shadows outside object bounds,
strong silhouette, vibrant neutral fantasy style, production-ready 2D game sprite.

5-3) 네거티브 프롬프트

character, hero, enemy, weapon, castle, UI panel, letters, logo, watermark,
photorealistic, 3d render look, heavy bloom, noisy background, tilted perspective.

5-4) 생성 가이드

• 배경: 반드시 투명(Transparent)
• 비율: 1:1 (권장 512 또는 1024)
• 산출물: 기본/hover/selected 3버전까지 확장 가능
• 생성 후 Assets/Resources/UI/Sprites/Game/ 하위에 배치

6. QA 체크리스트

#	항목	Phase	확인 방법
1	슬롯 0개 씬에서 에러 처리 동작 (폴백 없음)	A	TowerRoot 하위 자식 모두 제거 후 Play → 에러 로그 확인, 타워 메뉴 비활성
2	슬롯 있는 씬에서 모든 free 슬롯 마커 표시	B	Play 시 슬롯 수만큼 마커 표시 확인
3	슬롯 클릭 시 TowerRingMenu가 슬롯 위치 기준으로 오픈	B	마커 클릭 → 메뉴 위치 일치 확인
4	Hover 시 마커 밝기/스케일 변화	B	마우스 오버 → 시각 피드백 확인
5	건설 시 해당 슬롯 마커 즉시 숨김	C	타워 건설 → 마커 즉시 비활성
6	판매 시 해당 슬롯 마커 재표시	C	타워 판매 → 마커 재활성
7	웨이브 진행/일시정지/배속 변경 중 마커 상태 유지	C	다양한 게임 상태에서 마커 상태 불변 확인
8	씬 재시작 후 슬롯 점유-마커 상태 동기화	C	재시작 → 점유 슬롯은 숨김, free 슬롯은 표시
9	모든 슬롯 점유 후 추가 건설 요청 거부	C	모든 슬롯 채운 후 빈 땅 클릭 → 메뉴 미표시
10	타워 업그레이드 시 마커 숨김 유지	C	타워 업그레이드 → 마커 재표시 안 됨 확인
11	골드 부족 시 건설 실패 → 마커 표시 유지	C	골드 부족 상태에서 건설 시도 → 마커 숨김 안 됨 확인

7. 리스크 및 대응

리스크	심각도	대응
슬롯 누락 맵에서 플레이 불가	높음	에러 메시지에 수정 위치(GameBattlefield/TowerRoot) 명시 + 에디터에서 Play 자동 중단
마커 소팅 충돌로 타워/지형과 겹침	중간	전용 Sorting Layer 또는 고정 order 규칙(-5) 적용
건설/판매 이벤트 누락 시 마커 불일치	중간	RefreshAll() full-sync 메서드 확보, 웨이브 전환 시 호출
기존 씬 프리팹에 TowerRoot 자식 없음	낮음	Phase A 적용 시 기존 씬 점검 필수, 누락 시 에디터 로그로 즉시 감지
Hover/Click 피드백 과부하 (모바일 성능)	낮음	셰이더 대신 Color/Scale 변경으로 저비용 구현, Feature Flag로 피드백 ON/OFF 가능하게

8. 작업 순서(실행 권장)

1. Phase A 먼저 반영 (데이터 무결성 확보)
   • GameBattlefield.CreateDefaultTowerSlots 제거
   • TowerManager.Configure 폴백 블록 제거
2. Phase B 기본 마커 표시 구현
   • TowerSlotVisualizer 신규 작성
   • 슬롯 마커 스프라이트 생성 및 배치
3. Phase C 점유 상태 연동 마감
   • TowerManager 이벤트 추가
   • GameScene wiring 연결
4. QA 체크리스트 9항목 통과 후 문서/완료 이관

9. 구현 전 준비조건 (Definition of Ready)

1. 적용 대상 씬/프리팹 확정:
   • GameBattlefield가 실제로 배치된 전투 씬 목록 확정
   • 각 씬의 TowerRoot 하위 슬롯 Transform 최소 1개 이상 배치 여부 사전 점검
2. 슬롯 마커 에셋 준비:
   • 기본(Idle) 1종 필수
   • 선택사항: Hover/Selected 변형 2종
3. UI 충돌 정책 확정:
   • 슬롯 마커는 월드 오브젝트(2D Collider 미사용 권장)로 유지
   • 클릭 판정은 기존 TryFindBuildableSlotAtWorldPosition()를 단일 소스로 유지
4. 로그 포맷 확정:
   • 에러/정보 로그 prefix 통일 ([TowerSlot], [TowerManager], [GameScene])

10. 수용 기준 (Acceptance Scenarios)

AS-01: 슬롯 누락 씬 방어

• Given: TowerRoot 하위 슬롯 0개
• When: 전투 씬 시작
• Then: 폴백 슬롯 미생성 + 에러 로그 출력 + 건설 메뉴 오픈 불가

AS-02: 빈 슬롯 시각 안내

• Given: 슬롯 3개, 초기 타워 0개
• When: 전투 시작
• Then: 슬롯 마커 3개 노출

AS-03: 건설 시 마커 숨김

• Given: 빈 슬롯 1개
• When: 슬롯에 타워 건설 성공
• Then: 해당 슬롯 마커만 즉시 숨김

AS-04: 판매 시 마커 복구

• Given: 건설된 타워 1개
• When: 타워 판매 성공
• Then: 해당 슬롯 마커 즉시 재표시

AS-05: 점유/표시 동기화

• Given: 슬롯 N개, 점유 M개
• When: 씬 재시작 또는 상태 재동기화 호출
• Then: free 슬롯만 표시되고 occupied 슬롯은 숨김

AS-06: 맵 여백 클릭 시 슬롯 상호작용 해제 (Cancel)

• Given: 빈 슬롯 1개 클릭 (메뉴 열림 상태)
• When: 슬롯 반경 외(빈 맵 영역) 빈 곳을 터치/클릭
• Then: 열렸던 메뉴가 닫힘과 동시에 슬롯 마커가 초기 Idle 상태로 정상 복귀

AS-07: 타워 업그레이드 시 마커 불변

• Given: 슬롯에 타워 건설 완료 (마커 숨김 상태)
• When: 해당 타워를 업그레이드
• Then: 슬롯 마커는 숨김 상태 유지 (재표시되지 않음)

AS-08: 골드 부족 시 건설 실패 → 마커 유지

• Given: 빈 슬롯 1개 (마커 표시 상태), 골드 부족
• When: 슬롯 클릭 후 건설 시도 실패
• Then: 슬롯 마커는 표시 상태 유지 (숨김 되지 않음)

11. 관측성(로그/디버그) 계획

필수 로그

1. 슬롯 유효성 실패

   [TowerManager] Tower slot validation failed. slotCount=0, hint=GameBattlefield/TowerRoot child required.

2. 슬롯 마커 초기화

   [TowerSlot] Visualizer initialized. totalSlots={N}, visibleSlots={F}

3. 슬롯 점유/해제 반영

   [TowerSlot] Slot occupied. slotIndex={i}
   [TowerSlot] Slot freed. slotIndex={i}

디버그 헬퍼(선택)

• TowerSlotVisualizer.RefreshAll() 호출 시 현재 visible 인덱스 출력 옵션
• 개발 빌드에서만 verbose 로그 허용

12. 성능/안정성 가드

1. 마커 오브젝트는 슬롯 수만큼 1회 생성 후 SetActive 토글만 수행 (런타임 Instantiate/Destroy 반복 금지)
2. 업데이트 루프 polling 금지:
   • 빌드/판매 이벤트 기반으로 상태 관리 수행. 시각적 Idle 애니메이션(알파/스케일 변조) 등 캐싱된 Transform/렌더러 대상 변환 연산만 최소 한정으로 Update/Coroutine 허용.
3. Hover/Click 피드백은 저비용 방식 + 모바일 최적화 우선:
   • 무거운 Animator 컴포넌트 추가 대신 Math 함수(Color/Scale 보간) 활용
   • 모바일(터치) 기기 고려: 터치스크린 특성 상 마우스 Hover 이벤트에 대한 피드백 전달이 제한적이므로, Click(Touch Down/Up) 단계에서 즉각적인 펀치 효과에 피드백 비중을 강화할 것.
4. null-safe 가드:
   • 슬롯 인덱스 범위 체크 실패 시 예외 대신 경고 로그 후 무시

13. 롤백 전략

1. 기능 플래그 도입(권장):
   • enableTowerSlotVisualizer
   • strictTowerSlotValidation
2. 긴급 롤백 순서:
   1. 시각화만 비활성화(enableTowerSlotVisualizer=false)
   2. 필요 시 검증 strict 모드 완화 (임시)
3. 롤백 후에도 폴백 좌표 자동 생성은 재도입하지 않음(데이터 무결성 원칙 유지)

14. 문서 동기화 계획

1. 구현 착수 시:
   • 문서/진행/task.md에 본 트랙 Phase A/B/C 체크박스 추가
2. Phase 완료 시:
   • 계획서/작업로그/task 3종 동시 갱신
3. 최종 완료 시:
   • 본 문서를 문서/완료/YYYY_MM_DD로 이관
   • README의 진행/완료 문서 링크 갱신

15. 의사결정 레코드 (ADR 요약)

ADR-01: 슬롯 0개 시 폴백 생성 금지

• 결정: 자동 생성 대신 에러 처리
• 이유: 맵 데이터 누락을 조기 발견하고, 테스트/운영 환경 간 동작 불일치 제거
• 영향: 슬롯 누락 씬은 즉시 수정 필요

ADR-02: 슬롯 시각화는 월드 오브젝트 기반

• 결정: UI Overlay가 아닌 월드 기준 SpriteRenderer 사용
• 이유: 실제 건설 판정 좌표와 시각 표시의 일치성 확보
• 영향: 카메라 확대/축소 시에도 지형 기준으로 자연스럽게 표시

ADR-03: 상태 동기화는 이벤트 우선 + 전체 동기화 보조

• 결정: 빌드/판매 이벤트로 즉시 갱신하고, 예외 상황은 RefreshAll()로 회복
• 이유: 성능과 안정성 균형
• 영향: 이벤트 누락 시에도 복구 경로 확보

16. 오픈 이슈 (구현 전 확정 필요)

1. 슬롯 누락 시 동작 정책
   • 옵션 A: 타워 시스템만 비활성화
   • 옵션 B: 전투 씬 시작 중단(하드 실패)
   • 권장: 옵션 A — 타워만 비활성화하면 적 경로/웨이브/영웅 등 다른 시스템 학습용으로 씬 진행은 가능
2. Hover 피드백 입력 기준
   • 마우스 기준만 우선 적용할지, 터치/모바일 대응까지 동시에 갈지
   • 권장: P0에서는 Click 피드백(Punch Scale)만 구현, Hover는 P1에서 데스크톱 빌드 대상으로 추가
3. 슬롯 마커 아트 정책
   • 단일 공용 스프라이트 1종 vs 맵 테마별(초원/사막/설원) 다중 세트
   • 권장: P0은 공용 1종으로 시작, 테마별 변형은 맵 에셋 추가 시점에 확장
4. Sorting Layer 운영
   • Default 유지 vs 전용 SlotGuide 레이어 신설
   • 권장: Default 유지 + Order in Layer = -5로 P0 시작, 충돌 발생 시 전용 레이어로 승격

17. AI 협업용 출력 규격 (문서/프롬프트 공통)

1. 좌표계 명시
   • 모든 설명은 “월드 좌표 기준 슬롯 위치”를 기본으로 서술
2. 상태명 고정
   • Free, Occupied, Hidden, Visible 용어만 사용
3. 금지 표현
   • “자동으로 적당히”, “필요시” 같은 모호 표현 금지
4. 산출물 형식
   • 체크리스트는 PASS/FAIL 판정 가능한 문장으로 작성
5. 로그 예시
   • prefix + key=value 구조 유지 (slotIndex=, slotCount= 등)

18. QA 테스트 데이터셋(최소 세트)

1. Map_A_ValidSlots3: 정상 슬롯 3개
2. Map_B_NoSlots: 슬롯 0개(에러 처리 검증용)
3. Map_C_FullOccupied: 시작 시 슬롯 점유 상태 재현(동기화 검증용)
4. Map_D_MixedState: free/occupied 혼합 상태(판매/재표시 검증용)

19. 완료 정의 (Final Exit Criteria)

1. 기능
   • 폴백 슬롯 생성 코드 경로 0건
   • free 슬롯만 시각 표시, occupied 슬롯 비표시
2. 품질
   • QA 체크리스트 11항목 PASS
   • 오류 로그/경고 로그가 문서 스펙과 일치
3. 운영
   • task.md 상태 반영 완료
   • 완료 문서 이관 및 README 링크 갱신 완료

---

본 문서는 계획서이며, 코드 반영은 다음 작업 단계에서 진행한다.