blacknabis

농장 경영 시뮬레이션 게임 만들기 - 1

blacknabis — Sun, 19 Apr 2026 23:06:34 +0900

주말에 어떤것을 만들어볼까 하다가 농장 경영 힐링 게임을 만들면 좋겠다 생각해서 야금야금 작업을 시작.

개발 플랫폼

타겟플랫폼은 1차적으로 PC환경의 Steam이 어떠할까 고민해서 넓은 화면에서 키보드 마우스를 사용하는 방식으로 진행 결정

godot엔진, cocos2d-x, unity, unreal 엔진 중 요즘 자주 사용하는 엔진이 유니티라 취미 겸 공부 모적으로 Unity엔진으로 결정.

1. isomatrix 방식

comfyui를 사용하였지만 최종적으로 프로토 외에 마음에 들지 않고 내가 원하는 세팅을 끝내기에는 시간이 소비되기에 pixellab으로 변경하고 구독하여서 mcp 연동. 최대한 자동화를 시도함.

탑다운, 타일 스타일로 구조 변경

기본 시스템 다 붙이고, 타일 시스템붙이고, pixellab.ai mcp연동하여서 스프라이트 자동화, 그리고 기본 경작, 물주기 등등 캐릭터 이동하면서 기본 시스템 연동.

자동화 해서 만든 플레이어 이미지

PixelLab.AI MCP 연동하기

blacknabis — Sun, 19 Apr 2026 22:27:13 +0900

취미로 게임을 만들 던 중 스프라이트에 제작에 대한 시간이 소비되는걸 최대한 줄이고 싶었습니다. comfyui를 연동하긴 하였지만 로컬로 세팅하고 학습 데이터등을 가져왔지만 프로토타입으로는 만족이 되지만 조금 더 욕심이 나는데 이 시간을 조금 더 줄이고 자 이것저것 Pixel Art 자동화에 대해서 찾다가 가성비와 API지원이 되는것을 찾아보고 시험으로 PixelLab.AI을 선택하여서 연동하게 되었습니다.

1. PixelLab 가입하기

http://pixellab.ai/

PixelLab - AI Generator for Pixel Art Game Assets

Make your characters move Create character animations with text prompts, skeleton-based controls, or our automatic character creator. Generate walking, running, attacking, and custom animations for your sprite sheets.

www.pixellab.ai

가장 저렴한 모델 구독 후 Account 정보

2. MCP 연동하기

https://www.pixellab.ai/mcp

Vibe Coding - PixelLab

Framework Agnostic Works with any game engine or framework. Unity, Unreal Engine, Godot, GameMaker Studio, Raylib, MonoGame, Defold, Love2D, or Pygame - your AI assistant adapts to your preferred tools.

www.pixellab.ai

탭마다 종류별 MCP 연동 가이드가 있다.

방법 1. 수동

내가 사용하는 AI(예 Claude COde, Codex)를 선택 후 설명에 나온대로 mcp를 등록해주면된다.

뒤에 나오는 API의 키경우, https://www.pixellab.ai/pixellab-api나 https://www.pixellab.ai/account에서 있지만 이 값은 해당 메뉴얼에서 자동으로 적용되는것으로 보임.

방법 2. 자동(에이전트에게 세팅 시키기)

1. https://www.pixellab.ai/pixellab-api나 https://www.pixellab.ai/account에서 API Key를 확인.
2. AI에게 "https://www.pixellab.ai/mcp 링크를 읽고 Pixellab.ai mcp 연동해줘" 후 확인한 API Key를 전달하거나 세팅해주면된다.

3. 사용방법

AI 에이전트에게 pixellab.ai의 mcp를 사용하여서 이미지를(예시. 현재 사용되는 32픽셀의 농부의 4방향 애니메이션을 만들어줘) 요청하면 만들어준다.

실행결과

4. 후기

상업용으로는 사용하기에는 힘들지만 개인 개발자라면 특히나 아트직군이 아닐경우 많은 시간을 단축시켜주고 제일 싼 요금제의 경우 월 2천장이 사용가능하기 때문에 커피 마시는 값을 아껴서 한달정도는 사용해볼 만 한것 같습니다.

안티그래비티 반응이 없을 때 대처.

blacknabis — Sun, 19 Apr 2026 00:58:50 +0900

새로운 작업을 할 때 안티그래비티 입력 받응이 없어서 재설치도하고 이것저것 다 시도하닫가 실패하고 레딧을 검색..

https://www.reddit.com/r/google_antigravity/comments/1sg0ghw/anitgravity_fails_to_respond_any_solution_to_this/?tl=ko

Reddit의 google_antigravity 커뮤니티: Anitgravity가 반응이 없는데, 해결 방법 없을까요?

google_antigravity 커뮤니티에서 이 게시물을 비롯한 다양한 콘텐츠를 살펴보세요

www.reddit.com

.git/config 에서 extensions 하위에 내용을 제거하면 된다고함.

[extensions]
  worktreeConfig = true

잘됨... 요즘 안티그래비티 토큰제한도그렇고 너무 마음에 안듬.

원시인 모드 스킬

blacknabis — Sun, 12 Apr 2026 16:46:21 +0900

클로드 코드(Claude Code) 토큰 75% 절약하는 방법: '원시인 모드(Caveman)' 가이드

AI 개발 도구를 사용하다 보면 끊임없이 소모되는 토큰 비용과 길고 장황한 답변이 부담스러울 때가 많습니다. 오늘은 클로드 코드(Claude Code), 커서(Cursor), 제미나이(Gemini) 등에서 출력 토큰을 무려 평균 75%까지 줄여주는 재미있고 혁신적인 스킬, '원시인 모드(Caveman)' 에 대해 소개합니다.
단순히 말을 짧게 하는 것을 넘어, 기술적인 정확도는 100% 유지하면서 비용과 속도까지 챙길 수 있는 강력한 플러그인입니다.
출처: GitHub - JuliusBrussee/caveman

원시인 모드(Caveman Mode)란?

"왜 많은 단어를 쓰지? 적은 단어로도 충분한데!"
원시인 모드는 AI가 불필요한 미사여구(pleasantries), 추임새, 문법적 허례허식을 빼고 핵심 기술 정보만 원시인처럼 툭툭 내뱉게 만드는 플러그인입니다.

비포 & 애프터 비교

️ 일반 클로드 모드 (69 토큰)

"React 컴포넌트가 다시 렌더링되는 이유는 렌더링 주기에마다 새로운 객체 참조를 생성하기 때문일 가능성이 높습니다. 인라인 객체를 prop으로 전달하면 React의 얕은 비교(shallow comparison)에서 매번 다른 객체로 인식되어 다시 렌더링을 유발합니다. 객체를 메모이제이션하려면 useMemo를 사용하는 것을 권장합니다."
원시인 모드 (19 토큰)
"렌더링마다 새 객체 참조. 인라인 객체 prop = 새 참조 = 재렌더링. useMemo로 감싸라."
결과는 똑같은 해결책입니다. 하지만 75% 더 짧고, 약 3배 더 빠릅니다. 중요한 것은 기술적인 팩트와 처리해야 할 코드는 전혀 훼손되지 않는다는 점입니다.

원시인 모드 프롬프트가 주는 4가지 이점

엄청난 속도 향상: AI가 파싱하고 생성해야 할 토큰이 줄어드니 응답 속도가 훨씬 빠릅니다.
비용 절감: 출력 토큰을 평균 70% 이상 절약할 수 있어 API 비용이 크게 감소합니다.
가독성 향상: 긴 설명이나 텍스트 장벽 없이 필요한 정답과 코드만 바로 확인할 수 있습니다.
팩트 중심 출력: 2026년 발표된 연구 논문에 따르면 LLM에 간결성 제약을 걸었을 때 정확도가 오히려 개선되는 현상도 목격되었습니다. (군더더기로 인한 환각 억제)

️ 4가지 강도(Intensity) 조절 기능

명령어 창에서 원시인의 지능 퇴화(압축) 수준을 선택할 수 있습니다.

Lite (라이트 모드): 정중함만 빼고 문장은 어느 정도 유지합니다.
Full (풀 모드): 기본 모드. 짧은 명사구 형태로 답합니다.
Ultra (울트라 모드): 인간어조차 최소화합니다. [원인] → [결과]. 그리고 코드만 출력합니다.
文言文 (문언문 모드): 전통 한문(고대 중국어)으로 대답합니다. (토큰 효율적인 언어 압축 방식입니다)
강도 조절 적용 형태:* /caveman ultra

️ 다양한 AI 어시스턴트에 설치하는 방법

원시인 모드는 npx skills를 지원하는 40개 이상의 다양한 AI 코드 에디터 및 CLI 에이전트와 원활하게 호환됩니다.
1. Claude Code (클로드 코드)

claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

2. Cursor (커서)

npx skills add JuliusBrussee/caveman -a cursor

3. Windsurf (윈드서프)

npx skills add JuliusBrussee/caveman -a windsurf

4. Gemini CLI (제미나이)

gemini extensions install https://github.com/JuliusBrussee/caveman

⚠️ 자동 시작 활성화 팁
커서, 윈드서프 같은 도구는 스킬 파일만 복사되기 때문에 매번 채팅 시 "원시인처럼 말해줘" 라고 지정해야 합니다. 모든 대화 시작 시 항상 켜두고 싶다면, 프로젝트 내 룰 셋팅장 (.cursor/rules/caveman.mdc 등)을 만들어 아래 내용의 프롬프트를 추가하면 좋습니다.

Terse like caveman. Technical substance exact. Only fluff die. Drop: articles, filler (just/really/basically), pleasantries, hedging. Fragments OK. Short synonyms. Code unchanged. Pattern: [thing] [action] [reason]. [next step]. ACTIVE EVERY RESPONSE. No revert after many turns. No filler drift. Code/commits/PRs: normal. Off: "stop caveman" / "normal mode".

알아두면 유용한 3가지 부가 기능

단순히 말투만 교정하는 것을 넘어서서 코딩 생산성을 올려주는 커스텀 스킬명령어도 갖추고 있습니다.

/caveman:compress: 프로젝트 루트의 CLAUDE.md 파일 등을 압축해 줍니다. 백업은 두면서 AI가 읽어들이는 시스템 지시사항을 토큰 친화적(원시인어)으로 압축하여 입력단 토큰까지 아껴줍니다.
/caveman-commit: 가장 간결하고 직관적인 한 줄 커밋 메시지를 생성합니다. (예: bug: user null. Add guard.)
/caveman-review: 구구절절 불필요한 설명 없이, 딱 한 줄로 문제점만 찌르는 마이크로 코드 리뷰를 해줍니다.

맺음말

개발을 할 때마다 "네, 바로 도와드리겠습니다!" 같은 AI의 반복적인 기계어 인사에 지쳤거나, 빠르게 소모되는 API 요금이 걱정된다면 '원시인 모드'를 반드시 도입해 보세요. 거추장스러운 수식어를 버리고 본질(코드 중심)에만 집중하는 극단적이면서도 가장 재치있는 토큰 관리 전략일 것입니다.
지금 바로 터미널을 여세요.

npx skills add JuliusBrussee/caveman

영어만 지원해서 코덱스를 사용하여서 한국어 호환버전 작업 후 테스트

클로드 코드(Claude Code) 권한 설정 가이드: 위험천만한 바이패스 모드와 새로운 오토(Auto) 모드 해부ClaudeClaude Code

blacknabis — Sun, 12 Apr 2026 16:37:52 +0900

클로드 코드(Claude Code) 권한 설정 가이드

Anthropic에서 선보인 강력한 터미널용 AI 코딩 어시스턴트인 Claude Code를 사용하다 보면, 파일을 수정하거나 셸 명령어를 실행할 때마다 매번 y/n을 묻는 '승인(Approval) 프롬프트'에 피로감을 느끼기 쉽습니다.

이러한 프롬프트 피로(Prompt fatigue)를 극복하기 위해 사용자들은 권한을 생략하는 옵션들을 찾게 됩니다. 이번 글에서는 극단적인 형태의 권한 생략인 Bypass 모드(--dangerously-skip-permissions)와 이를 안전하게 대체하는 스마트한 오토(Auto) 모드의 차이점과 상세 작동 방식을 깊이 파헤쳐 보겠습니다.

1. 극단적 선택: `--dangerously-skip-permissions` 플래그

이 명령어는 이름에서부터 느껴지듯 "위험을 감수하고 모든 권한 확인을 건너뛰겠다"는 의미를 담고 있습니다. 커뮤니티에서는 흔히 'YOLO(You Only Live Once) 모드' 또는 '풀 바이패스(Bypass) 모드'라고 부릅니다.

작동 방식 및 특징

이 플래그를 붙여 에이전트를 실행하면(claude --dangerously-skip-permissions), Claude Code는 파일 읽기/쓰기, 셸 명령어 실행, 깃(Git) 커밋, 네트워크 요청 등 시스템 제어권이 필요한 모든 동작을 사용자에게 묻지 않고 즉시 100% 실행합니다.

왜 이 모드가 그토록 위험할까?

브레이크 없는 스포츠카: AI가 문맥을 잘못 이해하여 rm -rf 같은 치명적인 삭제 명령을 내리거나, 민감한 환경 설정 파일을 엉뚱하게 덮어써 버릴 때 사람이 멈출 수 있는 기회가 전혀 없습니다.
보안 취약점 노출 (Prompt Injection): 만약 분석하라고 던져준 외부 코드나 텍스트 안에 "이 환경을 지워라"라는 식의 악의적 프롬프트가 숨어있다면, 시스템이 사용자 모르게 이를 실행해 버릴 위험이 다분합니다.

언제 사용해야 할까?

Anthropic은 이 모드를 일반적인 로컬 개발 컴퓨터(내 맥북, 내 윈도우 PC)에서 사용하는 것을 절대 권장하지 않습니다. 이 모드는 다음과 같은 철저히 격리된 환경에서만 사용해야 합니다.

지워져도 상관없는 일회성 도커(Docker) 컨테이너 안에서 자동 리뷰를 돌릴 때
비밀 키(Secret)나 프로덕션 데이터가 없는 CI/CD 파이프라인의 자동화 스크립트 용도

2. 현명한 타협안: 오토(Auto) 모드 (Research Preview)

위험천만한 풀 바이패스 모드 대신, Anthropic이 최근 도입한 "Auto Mode"는 자율성과 안정성의 균형을 맞춘 똑똑한 모드입니다.

어떻게 작동하나요?

오토 모드의 핵심은 내부에 숨겨진 분류기 모델(Classifier Model)에 있습니다. Claude가 특정 명령을 내리면, 이 분류기 모델이 해당 명령의 '위험도'를 우선 평가합니다.

저위험 작업 (자동 승인): 단순한 파일 수정, 에러 로그 읽기, 프로젝트 내 검색 등은 사람의 개입 없이 AI가 즉시 실행합니다.
고위험 작업 (승인 요청): 대규모 파일 삭제, 시스템 권한(sudo) 요구, 낯선 외부 네트워크 통신 등은 분류기가 위험하다고 판단하여 기존처럼 사용자에게 y/n을 물어봅니다.

오토 모드의 장점

피로감을 유발하는 자잘한 질문은 AI가 알아서 처리해 주면서도, 정말 큰일이 날 법한 순간에는 안전벨트를 꽉 잡아줍니다. 이를 통해 개발자는 코드의 흐름을 끊지 않고도 최소한의 안전망 위에서 작업할 수 있게 됩니다.

참고: 오토 모드는 현재 리서치 프리뷰(Research Preview) 단계이며, 주로 Team, Enterprise, API 결제 사용자 등을 중심으로 제공됩니다. 관리자 설정이나 초기 claude 설정 플래그에서 활성화해야 터미널 단축키(Shift+Tab)로 모드를 전환할 수 있습니다.

3. 한눈에 보는 비교 (Bypass vs Auto)

비교 항목	바이패스 모드 (`--dangerously-skip-permissions`)	오토 모드 (Auto Mode)
승인 방식	묻지도 따지지도 않고 무조건 실행	AI 분류기가 위험도를 평가하여 선별적 실행
안전성	전혀 없음 (0%)	보통~높음 (치명적 오류는 막아줌)
사용 목적	완전 자동화된 서버, 헤드리스(Headless) 환경	프로그래머의 일상적인 로컬 개발 환경
위험 수준	매우 높음 (치명적 데이터 유실 가능)	낮음~보통 (Research Preview)

4. 실전 가이드: 안전장치(`deny` 룰) 설정하기

비록 오토 모드를 쓴다 하더라도 100% 안전을 보장하는 것은 아닙니다. 만약 무심코 바이패스 모드로 진입하게 될 상황을 대비해, 절대 실행 불가능한 명령의 블랙리스트를 만들어 두는 것이 좋습니다.

~/.claude/settings.json 파일을 열고 deny 옵션을 추가하세요.

{
  "theme": "dark",
  "deny": [
    "rm -rf *",
    "sudo",
    "drop database",
    "npm publish"
  ]
}

Claude Code에서 Codex Plugin을 사용해보자!

blacknabis — Sun, 12 Apr 2026 14:40:16 +0900

현재 Codex(Pro), Claude Codex(Pro), Antygravity(AIPro) 사용 중인데 클루드 코드의 토큰이 너무나도 빨리 소모가 되서 좋은 방법 없을까 하다가 해커톤에 1위 유저의 세팅공유와 만우절날 OpenAI에서 발표한 클루드코드에서 플러그인 추가가 기억나서 이참에 연동을 해보았습니다.

https://x.com/dkundel/status/2038670330257109461

https://github.com/openai/codex-plugin-cc?tab=readme-ov-file#install

[GitHub - openai/codex-plugin-cc: Use Codex from Claude Code to review code or delegate tasks.

Use Codex from Claude Code to review code or delegate tasks. - openai/codex-plugin-cc

github.com](https://github.com/openai/codex-plugin-cc?tab=readme-ov-file#install)

GitHub의 readme.md의 내용입니다.

Claude Code에 마켓플레이스를 추가하세요:

/plugin marketplace add openai/codex-plugin-cc

플러그인을 설치하세요:

/plugin install codex@openai-codex

플러그인 다시 로드:

/reload-plugins

그런 다음 실행하세요:

/codex:setup

위 과정을 거치면 명령어가 추가된것을 확인 할 수 있습니다.

/codex:review 를 실행 하면 어떤 방식으로 진행할 지 선택지가 나온다.

일반 사용 흐름

출시 전 리뷰: /codex:review 단독 실행
문제를 Codex에 위임: /codex:rescue investigate why the build is failing in CI
장시간 작업 시작 후 확인: --background로 실행 → /codex:status → /codex:result

Codex 통합 구조

플러그인은 Codex 앱 서버를 래핑하며, 환경에 설치된 전역 codex 바이너리를 활용
별도 런타임 없이 동일한 Codex 설치·인증·레포지터리·로컬 환경 공유
기본 모델 및 추론 노력(reasoning effort)은 ~/.codex/config.toml(사용자 레벨) 또는 .codex/config.toml(프로젝트 레벨)로 설정 가능
- 예시: model = "gpt-5.4-mini", model_reasoning_effort = "xhigh"
- 프로젝트 레벨 설정은 해당 프로젝트가 신뢰됨(trusted) 상태일 때만 적용
완료된 위임 작업은 codex resume 로 Codex에서 직접 이어받기 가능

Claude Code 프로 플랜을 사용중이라 Opus를 사용하면 토큰의 거기 사용하기 불가능한 수준이였는데 이처럼 플러그인으로 사용하면 괜찮은거 같네요. 코드분석, 개선점을 실행하는데 5시간 한도 4%정도 사용되는군요

기존 프로젝트의 개선사항 리스트

코드작업은 소넷, 리뷰는 코덱스

실제 작업을 진행하였는데 토큰은 주간한도 38%정도 소모하였고 사용에 실제 체감이 많이 되었네요.

AI 소식 수집. 디스코드에 보내는 봇 제작

blacknabis — Sun, 12 Apr 2026 02:13:48 +0900

AI 소식을 매일 수집해 Discord로 보내주는 요약 봇을 만들었습니다

요즘 AI 관련 소식은 올라오는 속도도 빠르고, 채널도 너무 다양합니다.
OpenAI 공식 뉴스, Claude Code 릴리즈, 주요 X 계정까지 각각 직접 확인하다 보니 생각보다 반복 비용이 크다고 느꼈고, 그래서 필요한 정보만 모아서 매일 한 번에 보내주는 작은 요약 봇을 만들어보게 됐습니다.

이번에 만든 프로젝트는 ai-signal-digest입니다.

GitHub:
https://github.com/blacknabis/ai-signal-digest

이 프로젝트는 기본적으로 아래 흐름으로 동작합니다.

config/sources.json에 등록된 소스를 읽습니다.
RSS / HTML / X RSS-compatible feed에서 최신 항목을 수집합니다.
SQLite 상태 저장소를 기준으로 이미 본 항목을 제외합니다.
수집한 항목을 한국어 digest 형태로 정리합니다.
Discord 웹훅으로 하루 1회 전송합니다.

기능 자체는 단순해 보이지만, 실제로는 "운영 가능한 자동화"가 되도록 구조를 나누는 데 조금 더 신경을 썼습니다. 한 파일에 전부 몰아넣기보다는, 수집과 상태 관리, 요약, 전송이 서로 독립적으로 바뀔 수 있도록 분리했습니다.

핵심 구성

cli.py
- 실행 진입점입니다.
service.py
- 수집, dedupe, enrichment, render, delivery까지 전체 파이프라인을 오케스트레이션합니다.
state.py
- 중복 방지를 위한 SQLite 상태 저장소입니다.
collectors/rss.py, collectors/html.py
- 소스 종류에 따라 수집 책임을 분리했습니다.
enrichment.py
- 한국어 fallback 요약과 선택형 번역 처리를 담당합니다.
digest.py
- Discord에 맞는 최종 메시지 포맷을 만듭니다.
discord.py
- Discord 웹훅 전송과 메시지 chunking을 처리합니다.

이렇게 나눈 이유는 명확합니다. 예를 들어 X 수집 방식이 바뀌더라도 collector만 수정하면 되고, 요약 형식을 바꾸고 싶으면 digest/enrichment만 손보면 되도록 하기 위해서입니다. 실제로 만들다 보니 이런 분리가 나중 수정에 꽤 도움이 됐습니다.

상태 관리와 중복 방지

상태 저장은 SQLite를 사용했습니다.
이 프로젝트에서 중요한 건 "새 소식만 보내는 것"이기 때문에, 단순히 마지막 실행 시각만 저장하는 방식보다 항목별 상태를 저장하는 쪽이 더 안전하다고 판단했습니다.

현재는 seen, delivered, suppressed 개념을 나눠서 관리합니다.

seen
- 한 번이라도 수집된 항목
delivered
- Discord로 실제 전송된 항목
suppressed
- 첫 실행 시 오래된 글처럼 의도적으로 제외한 항목

이렇게 분리해두면 Discord 전송 실패가 생겨도 수집 결과를 잃지 않고, 이후 재시도도 더 자연스럽게 처리할 수 있습니다.

또 처음 실행할 때 기존 글이 한꺼번에 쏟아지는 문제를 막기 위해 bootstrap 보호 장치도 넣었습니다.

BOOTSTRAP_LOOKBACK_HOURS
BOOTSTRAP_MAX_ITEMS_PER_SOURCE

이 두 값을 환경 변수로 빼서 운영과 테스트에서 유연하게 조정할 수 있도록 했습니다.

X 수집에서 신경 쓴 부분

수집 쪽에서는 X가 가장 손이 많이 갔습니다.
처음부터 x.com HTML을 직접 긁는 방식은 피하고, RSS-compatible feed를 통해 가져오는 구조로 잡았습니다. 현재는 로컬 RSSHub를 사용하고 있습니다.

다만 RSSHub로 가져온 X 피드는 본문이 description 안에 HTML 형태로 들어오는데, 그대로 쓰면 <br>, 인용 블록, 이미지 태그, 영상 태그가 섞여 있어서 digest 품질이 좋지 않았습니다. 그래서 collector 단계에서 X 본문을 정리된 텍스트로 바꾸는 작업을 넣었습니다.

구체적으로는 아래처럼 처리했습니다.

<br>는 줄바꿈으로 유지
인용문은 텍스트로 보존
이미지 / 영상 태그는 제거
content_text에는 비교적 긴 본문 텍스트를 저장
content_preview는 Discord용 짧은 미리보기로 축약

이렇게 바꾸고 나니 요약 단계에서 훨씬 안정적으로 본문을 활용할 수 있었습니다.

한국어 정리 방식

처음에는 OpenAI API를 붙여서 한국어 번역까지 자동으로 넣으려고 했습니다.
그런데 실제로는 ChatGPT 구독과 API 사용이 별개이고, quota나 billing 이슈도 따로 관리해야 했습니다. 그래서 현재는 기본 동작을 로컬 한국어 fallback 요약으로 두고, 필요할 때만 ENABLE_OPENAI_TRANSLATION=true로 명시적으로 켜는 방식으로 바꿨습니다.

fallback 쪽도 단순히 영어 문장을 그대로 붙이는 방식이 아니라, 용어 사전을 기반으로 조금 더 읽기 쉬운 한국어 digest가 되도록 보강했습니다.

예를 들면 이런 식입니다.

agent orchestration -> 에이전트 오케스트레이션
coding workflow -> 코딩 워크플로
production operations -> 프로덕션 운영

완전한 번역은 아니지만, 매일 보는 digest라는 목적에는 오히려 이 정도가 더 안정적이고 실용적이라고 느꼈습니다.

Discord 출력 포맷

단순 링크 모음은 실제로 잘 읽히지 않아서, Discord 메시지는 아래처럼 구조를 나눴습니다.

오늘의 AI 새 소식
요약
핵심 하이라이트
카테고리별 업데이트
처리 참고
실패한 소스

또 Discord 길이 제한 때문에 메시지가 길어질 경우를 대비해서 chunking도 넣었습니다. 처음에는 줄 중간이 잘리는 문제가 있었는데, 이후에는 가능한 한 줄 단위 경계를 유지하도록 다듬었습니다.

테스트와 운영

테스트도 비교적 촘촘하게 넣으려고 했습니다.

RSS / HTML collector 테스트
state store 테스트
digest 렌더링 테스트
enrichment 테스트
service 오케스트레이션 테스트
CLI 실행 테스트

특히 이번에는 X 본문 정리 로직도 테스트에 추가해서, HTML description이 텍스트로 잘 정리되는지 확인하도록 했습니다.

운영 방식은 최대한 단순하게 가져갔습니다.

PowerShell 스크립트로 실행
로컬 RSSHub 자동 기동
Windows 작업 스케줄러 등록 가능
테스트 시에는 운영 DB 대신 test-state.db 사용
OpenAI 번역은 기본 비활성화

마무리

이 프로젝트를 만들면서 다시 느낀 점은, 이런 자동화는 "AI를 얼마나 화려하게 붙이느냐"보다 "매일 안정적으로 돌아가느냐"가 훨씬 중요하다는 점이었습니다. 특히 정보 수집 도구는 완벽한 번역보다도, 놓치지 않고, 중복 없이, 읽기 쉬운 형태로 꾸준히 제공하는 쪽이 훨씬 가치가 있다고 생각합니다.

아직 더 개선할 여지는 많습니다.
예를 들어 중요도 판단 로직을 더 세밀하게 만들 수도 있고, fallback 요약 표현을 더 다듬을 수도 있고, 장기적으로는 NotebookLM 같은 도구와 연동해서 주간/월간 분석용 워크플로도 만들 수 있을 것 같습니다.

그래도 지금 상태만으로도 "매일 AI 소식을 한 번에 확인하는 도구"로는 꽤 만족스럽게 동작하고 있습니다.

프로젝트 저장소는 아래에 있습니다.

https://github.com/blacknabis/ai-signal-digest

️ Unity SRPG 개발 로그: 데이터 구조 대확장 — 직업, 보스, 챕터, 조합 시스템

blacknabis — Sun, 5 Apr 2026 03:53:27 +0900

오늘은 Claude와 함께 게임의 뼈대가 될 데이터 시스템을 대대적으로 확장했습니다.

기능 구현보다 앞서 데이터 구조가 탄탄해야 나중에 콘텐츠를 채울 때 손이 덜 가기 때문입니다. 신규 ScriptableObject 5개 신설, 기존 핵심 파일 5개 수정 — 오늘 작업 기록을 남깁니다.

1. GridCell — 비행/수중 이동 타입 지원

SRPG에서 비행 유닛(드래곤, 페가수스 등)이나 수중 유닛(해적, 인어 등)을 넣으려면 기존 isWalkable 하나로는 부족합니다.

해결 방법

GridCell.cs에 이동 타입별 프로퍼티를 추가했습니다.

// 물 지형 여부 (수중 유닛 전용)
public bool isAquatic => terrainData != null && terrainData.type == TerrainType.Water;

// 비행 유닛: 점유 유닛만 막힘 (지형 무시)
public bool isWalkableForFlying => occupyingUnit == null;

// 수중 유닛: 물/평지만 이동 가능
public bool isWalkableForAquatic => occupyingUnit == null &&
    (terrainData == null || terrainData.type == TerrainType.Water || terrainData.type == TerrainType.Plain);

GridManager.GetMovableCells() 도 오버로드를 추가해서 Ground / Flying / Aquatic 세 가지 이동 타입에 따라 BFS 분기가 달라지도록 구현했습니다. 기존 코드와 완전 하위 호환됩니다.

2. JobData ScriptableObject 신설 — 직업 시스템 기반 설계

기존에는 JobGrowthData(성장치 전용)만 있었는데, 직업 자체를 표현하는 데이터가 없었습니다.

새로 만든 것

JobData.cs — 직업 한 개를 완전히 정의하는 ScriptableObject.

기본 스탯 (LV1 초기값 HP/MP/ATK/DEF/MATK/MDEF/SPD)
이동 타입 (Ground / Flying / Aquatic)
허용 장비 타입 (검사는 검, 마법사는 스태프만 등)
스킬 습득 테이블 — 레벨 → 스킬 매핑으로 레벨업 시 자동 습득
패시브 스킬 목록

이걸 Unit.cs의 jobData 필드에 연결하면, 레벨업 시 성장치와 스킬 습득이 jobData 기준으로 자동 처리됩니다.

// Unit.cs — LevelUp() 리팩토링
var growthData = jobData?.growthData ?? originData?.jobGrowthData;
var increases = stats.LevelUp(unitType, growthData);

// 레벨업 스킬 자동 습득
var newSkills = jobData.GetSkillsLearnedAtLevel(stats.level);
foreach (var skill in newSkills)
{
    if (!skills.Contains(skill)) skills.Add(skill);
}

이제 에디터에서 JobData 에셋을 만들어 직업 15개를 정의하면, 코드 수정 없이 모든 유닛에 적용됩니다.

3. EnemyTemplateData + BossPhaseData 신설

적 유닛마다 일일이 UnitData를 만드는 건 비효율적입니다. 템플릿 기반으로 구조를 바꿨습니다.

EnemyTemplateData

레벨 범위(min~max) 지정 → 스폰 시 랜덤 레벨
스킬 풀에서 랜덤 배분 + 고정 스킬 보장
드롭 아이템 테이블 (확률 포함)
BossPhaseData를 연결하면 자동으로 보스 판정

BossPhaseData

보스 HP가 특정 구간에 진입하면 자동으로 페이즈 전환이 일어납니다.

트리거: HP 50% 이하 / 특정 턴 경과 / 아군 X명 사망
행동:   AI 패턴 변경 / 새 스킬 추가 / 증원 소환 / 스탯 강화 / 외형 교체

파이널 판타지 택틱스의 보스전처럼, 전반부와 후반부 패턴이 확 달라지는 연출이 데이터만으로 설정 가능합니다.

4. ️ ChapterData + GameDatabase 신설 — StageDatabase 은퇴

기존 StageDatabase는 스테이지를 평면 리스트로만 관리했습니다. 챕터 개념을 도입해 계층 구조로 바꿨습니다.

GameDatabase
 ├── ChapterData (Chapter 1: 모험의 시작)
 │    ├── StageData (1-1)
 │    ├── StageData (1-2)
 │    └── StageData (1-3 보스)
 └── ChapterData (Chapter 2: 왕도로의 여정)
      └── ...

ChapterData는 챕터 해금 조건, 클리어 보상(골드/아이템), 챕터 썸네일까지 포함합니다.

StageDatabase는 [Obsolete] 마킹 후 메뉴 이름을 [Legacy]로 변경해서 새 프로젝트에서 실수로 사용하는 걸 방지했습니다.

5. ⚔️ StageData 확장 — 승리/패배 조건 + 증원 시스템

지금까지 모든 스테이지의 조건이 "적 전멸"이었는데, 이걸 다양화했습니다.

승리 조건 (VictoryConditionType)

조건	설명
DefeatAllEnemies	모든 적 처치 (기본)
DefeatBoss	지정 보스만 처치
ReachDestination	특정 좌표 도달
ProtectAlly	아군 NPC 생존
SurviveXTurns	X턴 동안 버티기
CollectItem	맵 아이템 수집

패배 조건 (DefeatConditionType)

조건	설명
AllPlayersDead	아군 전멸 (기본)
ProtectedAllyDead	보호 대상 사망
TurnLimitExceeded	제한 턴 초과
EnemyReachesGoal	적이 목표 지점 도달

증원 웨이브 (ReinforcementWave)

특정 턴이 되거나, 보스 HP가 일정 이하로 떨어지면 새 적이 소환됩니다. announcement 문자열로 "적의 증원이 도착했다!" 같은 연출 메시지도 설정 가능합니다.

6. ⚗️ CraftRecipeData 신설 — 연금술사 조합 시스템

연금술사 직업을 위한 아이템 조합 레시피 ScriptableObject입니다.

// 조합 가능 여부 체크
recipe.CanCraft(inventory, unitLevel: 12, jobType: UnitType.Alchemist);

// 조합 시도 (RNG 반영)
bool success = recipe.TryRoll(out bool isCritical);
// 대성공 시 resultQuantity + 1 획득

주요 기능:

재료 목록 (아이템 + 수량)
기본 성공률 / 대성공 확률 / 실패 시 재료 반환 비율
직업 제한 (연금술사만 사용 가능 등)
골드 비용

마치며

오늘 작업의 핵심은 "나중에 콘텐츠를 빠르게 채울 수 있는 데이터 구조" 를 만드는 것이었습니다.

직업 15개, 적 20종, 스테이지 30개... 지금은 텅 비어 있지만, 이제 에디터에서 ScriptableObject 에셋만 생성하면 코드 수정 없이 쭉쭉 채워갈 수 있습니다. 다음 단계는 이 데이터 구조를 실제 BattleManager에 연동해서 승리/패배 판정 로직을 구현하는 것입니다.

Written with Claude

️ 추천 태그

#Unity #GameDev #IndieDev #SRPG #ScriptableObject #DataDriven #DevLog #Claude #AI_Coding #유니티 #개발로그 #인디게임 #전략RPG #직업시스템 #보스전

KikiLeoBook 릴리즈 준비 — 패키지 리네임부터 GitHub Release까지

blacknabis — Sun, 29 Mar 2026 22:25:51 +0900

KikiLeoBook 릴리즈 준비 — 패키지 리네임부터 GitHub Release까지

이 글은 Claude Code를 사용하여 작업하고 작성하였습니다.

개요

아내에게 전달할 안드로이드 전자책 앱 KikiLeoBook의 첫 번째 릴리즈(v1.0.0)를 준비했다. 오늘 작업의 핵심은 앱 정체성 확립(패키지명/앱명 변경), 릴리즈 서명 설정, Firebase 연동, 그리고 GitHub Release를 통한 버전 관리 체계 구축이었다.

1. 패키지명 및 앱 이름 변경

기존 개발 단계에서 임시로 사용하던 이름을 정식 명칭으로 교체했다.

항목	변경 전	변경 후
패키지명	`com.****`	`com.blacknabis.kikileobook`
앱 이름	****Book	KikiLeoBook
DB 이름	`****book.db`	`kikileobook.db`
SharedPrefs 키	`****book_prefs`	`kikileobook_prefs`

소스 디렉터리 전체를 sed로 일괄 치환하고, 패키지 경로 디렉터리 구조도 함께 이동했다. 변경된 파일만 수십 개였지만 Claude Code가 일괄 처리해줘서 수작업 없이 깔끔하게 끝났다.

2. 시맨틱 버전 관리

// app/build.gradle.kts
versionCode = 1
versionName = "1.0.0"

이후 릴리즈마다 versionCode는 1씩 증가, versionName은 시맨틱 버전(major.minor.patch)으로 관리하기로 했다.

3. 설정 화면 추가

라이브러리 화면 툴바에 설정 아이콘을 추가하고, 설정 화면 최하단에 앱 버전을 표시하도록 구현했다.

// SettingsActivity.kt
val versionName = packageManager.getPackageInfo(packageName, 0).versionName
binding.tvVersion.text = versionName

4. 릴리즈 키스토어 생성 및 서명 설정

Play Store를 거치지 않는 APK 직접 배포이므로, 릴리즈 서명용 키스토어를 직접 생성해 관리한다.

keytool -genkeypair -v \
  -keystore signin/kikileobook-release.jks \
  -alias kikileobook \
  -keyalg RSA -keysize 2048 \
  -validity 10000

키스토어와 비밀번호는 signin/ 디렉터리에서 관리하며, private 레포이므로 git에도 함께 포함했다.

Gradle 서명 설정

keystore.properties를 Java Properties가 아닌 커스텀 파서로 읽도록 처리했다. 비밀번호에 특수문자(#)가 포함될 경우 Properties 파싱 오류가 발생하기 때문이다.

// build.gradle.kts
val keystoreProperties = mutableMapOf<String, String>().apply {
    keystorePropertiesFile.readLines().forEach { line ->
        val trimmed = line.trim()
        if (trimmed.isNotEmpty() && !trimmed.startsWith("#") && trimmed.contains("=")) {
            val idx = trimmed.indexOf("=")
            put(trimmed.substring(0, idx).trim(), trimmed.substring(idx + 1))
        }
    }
}

5. Firebase 연동 업데이트

패키지명이 바뀌었으므로 Firebase Console에 새 앱(com.blacknabis.kikileobook)을 등록하고, 디버그/릴리즈 SHA-1 지문을 모두 등록했다.

구분	SHA-1
디버그	`2a:10:f3:d9:...`
릴리즈	`5d:9f:8a:13:...`

포인트: SHA-1 등록 후에는 반드시 google-services.json을 재다운로드해서 app/ 디렉터리에 교체해야 한다. 그렇지 않으면 빌드에 이전 OAuth 설정이 그대로 반영된다.

Claude Code의 Chrome 제어 기능(MCP)을 활용해 Firebase Console 브라우저 자동화로 SHA-1 등록, google-services.json 다운로드까지 자동으로 처리했다.

6. Google OAuth 동의 화면 확인

Google Cloud Console에서 OAuth 동의 화면 상태를 확인했다. 프로덕션 단계로 설정되어 있어 별도 테스터 등록 없이 모든 Google 계정으로 로그인 가능하다.

테스트 모드: 등록된 테스트 사용자만 로그인 가능
프로덕션 모드: 누구나 로그인 가능 ✅

7. 릴리즈 APK 빌드

./gradlew clean assembleRelease
# BUILD SUCCESSFUL in 1m 23s
# 49 actionable tasks: 49 executed

클린 빌드를 통해 캐시 없이 최신 google-services.json이 완전히 반영된 APK를 생성했다.

출력 경로: app/build/outputs/apk/release/app-release.apk
파일 크기: 8.7MB

8. GitHub Release 버전 관리

릴리즈 APK를 GitHub Releases로 관리하기로 했다. 매 릴리즈마다:

versionCode / versionName 업데이트
assembleRelease 빌드
git tag vX.X.X && git push origin vX.X.X
GitHub Release 생성 + APK 첨부

첫 번째 릴리즈:

태그: v1.0.

APK 배포는 Play Store를 사용하지 않으므로, GitHub Release에서 직접 다운로드하거나 카카오톡/구글 드라이브로 전달한다.

트러블슈팅

키스토어 비밀번호 특수문자 문제

처음에 Dhdudghks1!@# 비밀번호로 키스토어를 생성했는데, Gradle 빌드 시 "keystore password was incorrect" 오류가 계속 발생했다. \# 이스케이프, Java Properties 파서 교체 등 여러 방법을 시도했지만 실패. 결국 bash의 ! 히스토리 확장 이슈로 키스토어 생성 자체가 잘못된 것으로 판단, 단순 비밀번호로 키스토어를 새로 생성해 해결했다.

에뮬레이터에서 Google 로그인 실패

앱플레이어(에뮬레이터) 환경에서 Google 로그인 시 SIGN_IN_CANCELLED(12501) 오류 발생. SHA-1이나 설정 문제가 아닌 에뮬레이터 환경 자체의 Google Play Services 비표준 동작이 원인. 실제 안드로이드 기기에서는 정상 작동한다.

마치며

패키지명 변경부터 Firebase 재등록, 릴리즈 서명, GitHub Release까지 꽤 많은 작업이었지만 Claude Code 덕분에 브라우저 자동화, 코드 일괄 수정, 빌드 명령 실행을 한 세션에서 끊김 없이 처리할 수 있었다. 특히 Firebase Console SHA-1 등록을 MCP Chrome 도구로 자동화한 부분이 인상적이었다.

앞으로 기능 추가할 때마다 버전을 올리고 GitHub Release로 관리할 예정이다.

KikiLeoBook 개발 진행 상황 5차

blacknabis — Sun, 29 Mar 2026 06:21:34 +0900

JisunBook UI/UX 개선 프로젝트 보고서 (e-ink 최적화)

1. 개요

목표: e-ink 리더기 특성에 최적화된 높은 대비와 낮은 조작 뎁스 제공
대상: 안드로이드 기반 전자잉크 리더기 사용자

2. 주요 수정 내역

2.1 색상 및 대비 (Design Tokens)

Primary Text: #1A1A1A -> #000000
Divider/Stroke: #B0B0B0 -> #666666
Surface (Night): #000000 배경 위 #333333 요소 배치로 구별감 확보

2.2 하단 컨트롤 시스템

기존: Overflow Menu (⋮) 내에 기능 은닉
변경: 7개 핵심 아이콘 상주 (A-, A+, 목차, 북마크, 검색, TTS, 설정)
추가: TTS 전용 플로팅 컨트롤 바 (재생/일시정지/정지)

2.3 설정 화면 (BottomSheet)

구조: 5개 아코디언 섹션 (글꼴, 레이아웃, 화면, TTS, 단축키)
상태 유지: pref_last_opened_option_section 키를 활용해 마지막 섹션 자동 복원

2.4 위젯 최적화

SeekBar: Thumb 32dp로 확대, Track 두께 10dp로 강화
Library Card: 테두리 2dp 강화 및 진행률(%) 표기 추가

3. 코드 변경 사항 (주요 파일)

colors.xml, values-night/colors.xml: 대비 중심 색상 재정의
fragment_reader.xml: 7-아이콘 하단 바 및 TTS 컨트롤 바 레이아웃 추가
ReaderActivity.kt: 하단 바 로직 및 TTS 롱프레스 핸들링
ReaderOptionBottomSheet.kt: 아코디언 로직 및 SharedPreferences 연동

4. 향후 계획

물리 페이지 넘김 버튼 하드웨어 키 매핑 보완
기기별 Ghosting(잔상) 방지를 위한 부분 새로고침 로직 검토

KikiLeoBook 개발 진행 상황 4차

blacknabis — Thu, 26 Mar 2026 00:23:59 +0900

KikiLeoBook 리더 개선 기록: TXT/EPUB TTS 붙이고 EPUB 위치 저장까지 점검한 날

2026년 3월 25일 오후 - 3월 26일 새벽

이번 작업은 KikiLeoBook 리더에 오프라인 TTS를 붙이는 데 집중했다.
처음에는 단순히 읽어주기 버튼 하나를 추가하는 정도로 생각했지만, 실제로는 TXT와 EPUB이 텍스트를 다루는 방식이 달라서 읽기 위치 표시, 페이지 이동 동기화, EPUB 위치 저장 문제까지 함께 정리해야 했다.

결과적으로 이번 단계에서는 아래 세 가지가 중심이었다.

오프라인 TTS 1차 도입
TXT / EPUB 읽기 흐름 정리
EPUB 위치 복원 문제 디버깅

오프라인 TTS 1차 도입

이번에는 클라우드 음성은 제외하고, Android 기기 안에 있는 TTS 엔진을 사용하는 방향으로 정리했다.
비용 부담 없이 바로 붙일 수 있고, 현재 목표인 “앱 화면이 켜져 있을 때만 동작”에도 가장 잘 맞는 방식이었다.

1차 목표는 이렇게 잡았다.

앱 화면이 켜져 있을 때만 동작
TXT와 EPUB 모두 지원
내부는 문장 단위로 읽되, UI는 Read aloud / Pause / Stop 정도로 단순화
백그라운드 재생이나 문장 이전/다음 같은 고급 기능은 다음 단계로 미룸

구조도 리더 화면에 TTS 코드를 직접 붙이기보다 공통 계층을 두는 방식으로 정리했다.

ReaderTtsController
AndroidTtsEngine
ReaderTextProvider
TtsUiState

이렇게 해두니 TXT와 EPUB이 각자 다른 방식으로 텍스트를 제공하더라도, 상위 제어 흐름은 같은 방식으로 묶을 수 있게 됐다.

TXT와 EPUB에 TTS 연결

TXT는 비교적 straightforward했다.
이미 현재 페이지 문자열과 페이지 상태를 가지고 있어서, 현재 위치 기준으로 문장을 나눠 순차적으로 읽도록 연결하면 됐다.

EPUB은 조금 더 손이 갔다.
WebView 안에서 렌더링되는 구조라 Android 쪽에서 현재 보이는 텍스트를 바로 알 수 없기 때문이다.
그래서 epub.js와 Android 사이 브리지를 확장해서, JS에서 현재 보이는 페이지 기준 텍스트를 추출한 뒤 Android로 넘기는 흐름으로 정리했다.

함께 반영한 내용은 다음과 같다.

리더 상단 메뉴에서 Read aloud 진입 가능하도록 정리
TTS 시작, 일시정지, 정지 상태를 리더 상태와 연결
아직 준비되지 않은 경우 무리하게 시작하지 않도록 방어
Speech speed, Speech pitch 옵션 연결
Korean / English 선택은 1차 범위에서 제외

언어 선택은 처음에는 넣어봤지만, 실제 사용 기준에서는 굳이 유지할 필요가 없다고 판단했다.
현재 단계에서는 속도와 피치 정도만 남기는 쪽이 더 단순하고 실용적이었다.

현재 읽는 위치가 보이도록 개선

TTS를 붙이고 나니 바로 보였던 문제가 하나 있었다.
음성은 나오는데 지금 어디를 읽고 있는지가 화면에서 잘 보이지 않는다는 점이었다.

그래서 현재 읽는 문장을 강조 표시하는 흐름을 추가했다.

TXT는 현재 읽는 문장을 페이지 안에서 하이라이트
EPUB도 WebView 내부에서 현재 문장을 강조 표시
검색 하이라이트와 TTS 하이라이트가 서로 덮어쓰지 않도록 분리

이와 함께, 읽는 문장이 다음 페이지로 넘어가면 화면도 같이 따라가도록 보강했다.
즉 TTS는 다음 페이지를 읽고 있는데 사용자가 보고 있는 화면은 이전 페이지에 멈춰 있는 어색한 상태를 줄이는 방향으로 정리한 것이다.

이 부분은 실제 사용감에 꽤 크게 영향을 줬다.
단순히 읽어주는 기능에서 끝나는 것이 아니라, 지금 읽는 위치를 눈으로 함께 따라갈 수 있어야 훨씬 자연스럽게 느껴졌기 때문이다.

중간 점검 결과

직접 확인한 결과는 다음과 같았다.

TXT는 TTS 동작이 비교적 안정적으로 붙음
EPUB도 현재 보이는 페이지 기준으로 읽어오는 동작까지는 정리됨
메뉴 노출 문제와 준비 상태 gating 문제는 중간 수정으로 정리
속도와 피치 옵션도 정상 동작 확인

반면 EPUB 쪽에는 한 가지 큰 문제가 남아 있었다.

읽다가 나갔다가 다시 들어오면 항상 첫 페이지가 열림
즉 EPUB 위치 복원이 실패하고 있었음

이건 단순 UI 문제가 아니라, 저장된 읽기 위치가 실제로 다시 적용되지 않는 흐름에 가까웠다.

EPUB 위치 복원 문제를 추적한 과정

이 문제는 생각보다 오래 걸렸다.
처음에는 Android 쪽 저장 순서 문제, WebView 초기화 타이밍 문제, savedCfi 반영 순서 문제를 차례대로 의심했다.

그래서 여러 번에 걸쳐 다음과 같은 방향으로 수정과 확인을 반복했다.

EPUB progress와 savedCfi 로드 순서 조정
openBook() 시점에 초기 CFI를 바로 반영하도록 수정
복원 중 잘못된 첫 위치 이벤트가 저장값을 덮어쓰지 않도록 방어
현재 표시 위치와 저장 위치가 다르면 다시 goToCfi()를 시도하는 보강
EPUB 압축 해제를 캐시 재사용 방식으로 바꿔 초기 로딩 시간을 완화

이 과정에서 로딩 속도는 다소 나아졌지만, 위치 복원 자체는 계속 첫 페이지로 열리는 문제가 남아 있었다.

Claude Code로 이어서 확인한 원인

복원 문제가 계속 남아 있어서, 이 부분은 Claude Code로 이어서 원인 분석을 진행했다.
여기서 핵심 원인은 CFI 저장값 자체가 비어 있거나 잘못된 문자열로 들어가고 있었다는 점이었다.

정리하면 다음과 같다.

`epub_reader.html`

locationChanged 이벤트 객체의 loc.start.cfi 대신
rendition.currentLocation().start.cfi에서 실제 CFI를 읽도록 변경

이 epub.js 버전에서는 loc.start.cfi가 항상 빈 문자열을 반환하고 있었고,
그 결과 Android 쪽에는 정상 위치가 아니라 빈 값이나 "undefined" 같은 문자열이 들어가고 있었다.

`EpubReaderFragment.kt`

"epubcfi"로 시작하지 않는 값은 위치 변경 로직에서 무시하도록 방어 코드 추가

`ReaderActivity.kt`

onStop()에서 EPUB 진행 저장 시에도 cfi.startsWith("epubcfi")를 통과하는 값만 저장하도록 정리

즉, 처음에는 복원 로직 자체를 의심했지만, 실제로는 복원에 필요한 정상적인 위치값이 저장되지 않고 있었던 쪽에 더 가까웠다.

빌드와 검증

기능을 붙이고 나서는 코드 컴파일과 APK 생성까지 계속 확인했다.

확인한 항목:

compileDebugKotlin 성공
assembleDebug 성공
디버그 APK 생성 확인

실기기 기준으로는 다음 내용까지 확인했다.

TXT TTS 동작 확인
EPUB TTS가 현재 보이는 페이지부터 읽는 동작 확인
EPUB 복원 문제는 원인 분석과 수정이 반영된 상태까지 정리

다만 EPUB 위치 복원은 최종적으로 실기기에서 한 번 더 재확인할 필요가 있다.
이번 글에서는 “원인 분석과 수정 반영까지 완료된 상태”를 기준으로 기록해둔다.

이번 작업에서 정리된 내용

완료

오프라인 Android TTS 1차 구조 추가
TXT / EPUB 리더에 TTS 연결
Read aloud / Pause / Stop 흐름 정리
TTS 속도와 피치 옵션 연결
TXT 현재 문장 하이라이트 반영
EPUB 현재 문장 하이라이트 반영
읽는 위치가 다음 페이지로 넘어갈 때 화면도 따라가도록 보강
EPUB 현재 보이는 페이지 기준 텍스트 읽기 개선
EPUB CFI 저장 경로 문제 원인 분석 및 수정 반영
디버그 빌드와 APK 생성 확인

남은 확인

EPUB 위치 복원 최종 실기기 재확인
TTS 하이라이트 색상과 가독성 미세 조정
EPUB 페이지 전환 시 체감 자연스러움 추가 점검
이후 단계에서 백그라운드 재생 여부 검토

메모

이번 작업은 단순히 “읽어주기 기능을 추가했다”로 끝나는 작업은 아니었다.
TXT와 EPUB이 각각 다른 방식으로 텍스트를 다루고 있어서, 실제로는 리더 구조와 현재 위치 표현, 페이지 전환 동기화, 위치 저장 방식까지 같이 손봐야 했다.

특히 EPUB은 WebView, JS 브리지, Android 저장 흐름이 함께 얽혀 있어서 겉으로 보이는 문제 하나를 수정하려고 해도 원인 추적 범위가 넓었다.

그래도 이번 단계로 리더에 TTS 기본 골격은 올라갔고,
사용자가 “듣고, 어디를 읽는지 보고, 페이지 흐름을 따라가는” 경험까지는 만들어가는 단계에 들어섰다.

다음 단계에서는 EPUB 위치 복원 최종 재확인과 함께,
하이라이트 완성도와 문장 추적 안정성을 더 다듬는 쪽으로 이어갈 예정이다.

KikiLeoBook 개발 진행 상황 3차

blacknabis — Wed, 25 Mar 2026 02:06:03 +0900

2026년 3월 24일 - 25일

이번 이틀은 KikiLeoBook 리더 쪽을 집중적으로 손봤다.
처음에는 단순히 빠진 기능을 다시 붙이는 정도로 생각했는데, 실제로 들어가 보니 TXT 리더 안정성, 페이지 이동 상태 동기화, EPUB 표시 정보 연결까지 같이 정리해야 하는 흐름이었다.

결과적으로는 리더 옵션 복구, TXT 리더 구조 개선, 진행 표시 UI 개선 이 세 가지를 중심으로 작업했다.

3월 24일

리더 옵션 기능을 다시 `master`로 복구

먼저 확인한 건 “예전에 넣어뒀던 페이지 넘김 탭 기능과 옵션 설정이 왜 안 보이느냐”는 문제였다.
조사해 보니 기능이 사라진 게 아니라, 관련 작업이 feature/reader-page-options 브랜치에만 있고 master에는 반영되지 않은 상태였다.

그래서 브랜치 내용을 다시 확인한 뒤 필요한 변경을 master에 병합했다.

복구된 기능은 다음과 같다.

화면 좌우 탭으로 이전/다음 페이지 이동
리더 옵션 바텀시트
글꼴 크기, 글꼴 종류, 줄 간격, 페이지 여백 설정
배경색 프리셋
화면 꺼짐 방지
페이지 이동 / 북마크 / 검색 단축키 설정

이 작업으로 “예전에는 있었는데 지금은 안 보이는 기능” 문제를 정리했다.

TXT 파일을 열 때 멈추는 문제 대응

그다음은 TXT 리더 쪽이었다.
큰 TXT 파일을 열면 앱이 한동안 멈추거나, 경우에 따라 응답 없음처럼 보이는 증상이 있었다.

원인을 따라가 보니, 페이지 분할과 텍스트 처리 일부가 메인 스레드에 부담을 주고 있었다.
특히 전체 텍스트를 한 번에 다루는 흐름은 파일이 커질수록 UI 멈춤으로 이어질 가능성이 컸다.

그래서 구조를 이렇게 조정했다.

TXT 페이지 분할을 백그라운드에서 수행하도록 변경
기존 chunk 기반 읽기 흐름을 다시 활용
필요한 chunk만 읽어서 페이지화하도록 정리
오래된 비동기 결과가 현재 화면 상태를 덮어쓰지 않도록 보호 로직 추가

즉, “한 번에 다 처리하려던 구조”를 “필요한 만큼 읽고 계산하는 구조”로 되돌리는 쪽에 가깝다.

페이지 이동 후 원래 페이지로 되돌아오는 문제 수정

이날 가장 신경 쓴 부분은 TXT 페이지 이동 안정성이었다.
하단 진행 바로 위치를 옮긴 뒤 오른쪽 화면을 눌러 다음 페이지로 넘기면, 잠깐 애니메이션이 보였다가 다시 원래 페이지로 돌아오는 문제가 있었다.

이건 단순 UI 문제가 아니라 비동기 로딩 타이밍 문제였다.
이전에 요청된 페이지 계산 결과가 늦게 도착하면서 현재 상태를 다시 덮어쓰는 흐름이 있었다.

그래서 아래처럼 정리했다.

페이지 로드 세대 관리 토큰 추가
늦게 도착한 오래된 로드 결과는 무시
레이아웃이 실제로 바뀐 경우에만 재페이지화
내부 페이지 상태와 ViewPager2 현재 페이지 상태를 다시 맞춤

이 수정으로 “넘어갔다가 다시 돌아오는” 현상을 줄이는 방향으로 안정화했다.

3월 25일

하단 진행 바를 옵션에서 끄고 켤 수 있게 변경

오늘은 리더 UI 사용감을 손봤다.
기존에는 하단 진행 바가 항상 보여서, 책 내용에 조금 더 집중하고 싶은 경우에도 화면 하단이 계속 차지되고 있었다.

그래서 리더 옵션에 하단 진행 바 표시 스위치를 추가했다.

적용한 내용:

옵션 바텀시트에 진행 바 표시 스위치 추가
설정값을 AppPreferences에 저장
앱을 다시 열어도 이전 상태 유지

기본값은 기존 동작과 호환되도록 표시 상태로 두었다.

진행 바를 숨기면 우하단에 상태 표시

진행 바를 아예 숨겨버리면 현재 어느 정도 읽었는지 감이 안 잡힐 수 있어서,
대신 우하단에 작은 상태 표시를 두는 방식으로 보완했다.

표시 규칙은 이렇게 잡았다.

값이 준비된 경우: 현재 페이지 / 전체 페이지
아직 계산 중인 경우: Loading...

즉, 정보를 정확히 보여줄 수 있을 때만 숫자를 보여주고,
아직 계산이 끝나지 않았으면 애매한 숫자를 보여주지 않도록 했다.

EPUB 페이지 상태를 Android 쪽으로 연결

EPUB은 epub.js를 사용하고 있는데,
기존에는 진행률 퍼센트 정도만 Android 쪽으로 전달하고 있었다.

이번에는 locationChanged 시점에 아래 정보를 같이 넘기도록 정리했다.

현재 화면 기준 페이지 번호
현재 화면 기준 전체 페이지 수
아직 계산 불가한 경우의 loading 상태

Android 쪽에서는 이 값을 받아서 우하단 상태 표시와 연결했다.
아직 페이지 수가 준비되지 않았을 때는 숫자 대신 Loading...을 보여주도록 했다.

TXT 전체 페이지 수는 백그라운드 계산으로 처리

TXT 쪽은 EPUB처럼 바로 화면 기준 페이지 정보를 주는 라이브러리가 있는 게 아니라서,
전체 페이지 수를 보여주려면 결국 페이지 계산을 해야 한다.

문제는 이걸 메인 스레드에서 하면 다시 리더가 무거워질 수 있다는 점이었다.
그래서 TXT는 현재 chunk만 즉시 표시하고, 전체 페이지 수는 백그라운드에서 차근차근 계산한 뒤 준비되면 우하단 표시를 갱신하도록 만들었다.

이 방식의 장점은 두 가지다.

리더가 먼저 열리고 페이지 표시가 뒤따라와도 된다
전체 페이지 수 계산 때문에 화면이 멈추지 않는다

사용자 입장에서는 처음엔 Loading...이 보이다가, 계산이 끝나면 현재 / 전체로 바뀌는 흐름이다.

테스트와 빌드 확인

기능을 붙인 뒤에는 바로 검증도 진행했다.

확인한 항목:

AppPreferencesTest 통과
assembleDebug 빌드 성공
디버그 APK 생성 확인

현재 남아 있는 것은 치명적인 오류가 아니라 경고 수준이다.

TxtReaderFragment의 scaledDensity deprecated 경고
일부 테스트의 coroutine opt-in 경고

둘 다 다음 정리 단계에서 다뤄도 되는 수준이다.

이번 작업에서 정리된 내용

완료

리더 옵션 기능 master 복구
페이지 좌우 탭 이동 복구
TXT 리더 chunk 기반 처리 정리
TXT 페이지 이동 되돌림 현상 완화
하단 진행 바 ON/OFF 옵션 추가
진행 바 숨김 시 우하단 상태 표시 추가
EPUB 페이지 상태 전달 연결
설정 테스트 통과
디버그 빌드 성공

남은 확인

실제 기기 기준으로 TXT/EPUB 페이지 표시 체감 점검
우하단 페이지 수 표시 정확도 추가 확인
deprecated / opt-in 경고 정리

메모

이번 작업은 기능을 “더 넣었다”기보다는,
읽는 도중에 거슬리는 부분을 줄이고 리더 상태를 더 일관되게 만드는 작업에 가까웠다.

특히 TXT 리더는 성능과 상태 동기화가 같이 얽혀 있어서,
단순한 UI 수정이 아니라 내부 흐름을 같이 정리해야 했다.

다음 단계에서는 실제 기기 테스트를 조금 더 돌려보면서,
남아 있는 표시 정확도와 경고 정리까지 마무리할 예정이다.

KikiLeoBook 개발 진행 상황 2차

blacknabis — Tue, 24 Mar 2026 02:50:17 +0900

1차는 별도의 블로그 없이 개발 진행 상태.

개요

Android TXT/EPUB 전자책 리더 앱 KikiLeoBook의 개발을 진행 중입니다. 어제와 오늘 3가지 주요 버그를 수정하고 5가지 새로운 기능을 추가했습니다.

어제 (3월 23일) — 버그 수정

1️⃣ EPUB 파일 실행 시 ERR_CLEARTEXT_NOT_PERMITTED 에러

문제: Android 9+ 이상에서 HTTP 통신 차단. NanoHTTPD 로컬 서버(localhost:8765)에서 EPUB을 렌더링하는데 cleartext(암호화되지 않은) 트래픽 금지로 epub.js 로드 실패.

해결:

app/src/main/res/xml/network_security_config.xml 생성
localhost/127.0.0.1에만 cleartext traffic 허용
AndroidManifest.xml에서 android:networkSecurityConfig 참조

2️⃣ TXT 파일 읽던 위치가 복원되지 않음

문제: 책을 읽다가 나갔다가 다시 열면 처음부터 시작. getCurrentPosition()이 chunk index만 저장하고 chunk 내 정확한 위치를 무시.

해결:

픽셀 레벨 offset 저장: "chunkIndex:pixelOffset" 형식 사용
LinearLayoutManager.findViewByPosition()?.top으로 정확한 스크롤 위치 계산
scrollToPositionWithOffset() + post {}로 UI 업데이트 동기화
NonCancellable context로 코루틴 취소 시에도 진도 저장

3️⃣ Google 로그인 실패 (구글 로그인 취소됨)

원인: Firebase Console 내 SHA-1 미등록 및 google-services.json 설정 누락.

해결:

Android Studio에서 SHA-1 추출 및 Firebase 등록
Firebase Authentication 내 Google 설정 활성화
OAuth client ID가 포함된 google-services.json 재적용
strings.xml에 정확한 web client ID 입력

오늘 (3월 24일) — 기능 추가 및 개선

✨ 1. 파일 추가 방식 개선 (Intent)

기존: 앱 내 + 버튼을 통한 파일 피커 방식만 지원.

개선:

공유 인텐트: 외부 파일 관리자에서 '공유'를 통해 KikiLeoBook 선택 가능
ACTION_VIEW: .txt, .epub 파일을 탭하면 즉시 KikiLeoBook으로 실행
AndroidManifest.xml에 관련 intent-filter 구현 완료

✨ 2. 검색 성능 개선 (Debounce)

ReaderViewModel에 500ms Debounce 적용.
사용자가 입력을 멈춘 후 0.5초 뒤에만 검색을 실행하여 리소스 낭비 방지 및 체감 속도 향상.

✨ 3. 독서 진행도 표시

화면 하단에 실시간 진행도 바(%) 추가.
TXT 리더는 RecyclerView 스크롤 기반, EPUB 리더는 epub.js percentage를 수신하여 동기화.

✨ 4. TXT 페이지 넘김 모드 도입

기존: 수직 스크롤 방식만 지원.

개선:

ViewPager2 기반의 좌우 스와이프 페이지 모드 추가.
TxtPaginator를 통해 뷰포트 높이에 맞춰 텍스트를 자동으로 분할(Pagination).
사용자 설정(AppPreferences)에 모드 저장 및 복원 기능 구현.

✨ 5. 브랜드 리네이밍 (JisunBook → KikiLeoBook)

strings.xml 및 앱 내부 상수를 KikiLeoBook으로 전면 교체.

구현 현황

✅ 완료

[x] EPUB cleartext 에러 수정
[x] TXT 위치 복원 (픽셀 레벨 offset)
[x] Google 로그인 설정 완료
[x] 파일 공유/열기 인텐트 연결
[x] 검색 debounce (500ms)
[x] 진행도 표시 (%)
[x] TXT 페이지 모드 (ViewPager2)
[x] 단위 테스트 통과 (TxtPaginatorTest 등)
[x] master 브랜치 푸시 완료 (커밋: 969098e)

진행 중

[ ] 수동 테스트 (TXT 페이지 넘김, EPUB paginated 등)

️ 기술 스택

언어: Kotlin
UI: Material Design 3, ViewPager2
DB: Room (SQLite)
라이브러리: epub.js, NanoHTTPD, JUnit 4

Claude Code Remote 그리고 Codex원격을 위한 PocketDex

blacknabis — Tue, 24 Mar 2026 00:01:45 +0900

집에서 좀 더 편한(?) 바이브 코딩을 위해서 Claude Code의 리모트 기능이 있어서 사용해봤음.

1. 서버 모드

cluade remote-control

2. 대화와 원경 동시 사용

calude --remote-control

3. Claude Code 실행 중

/remote-control
or
/rc

1번으로 실행하고 스페이스바를 누르면 qr이 뜨고 핸드폰원격으로 주소를 치거나 1~3번 모든 방법에서는 url주소도 나온다.

새로운 세션에서 실행 해서인지 기존 기능을 추가할려고 보니 막상 플랜만 세우는데 토큰을 모두 소모하여 이북리더기 앱의 코딩 한줄도 사용 못함..... 그래서 토큰이 널널한 대안으로 PocketDex를 사용햅보기로 함.

1. 안티그래비티에서 PocketDex 설치해 줘 딸칵. (깃에서 받아서 npm으로 설치하면 되는듯 하지만 최대한 ai돌려서 해보고싶다...)

2. 터미널에서 pocketdex을 치면 된다고 했지만(환경변수는 알아서 등록해줬음) 나중을 위해 배치파일을 추가.

3. 실행하면 qr이 나오고 모바일로 접속하면 완료

실행화면

[개발일지] SF6 뷰어 V1.1 업데이트: 커스텀 배경 스킨 및 데이터 정합성 개선

blacknabis — Sun, 22 Mar 2026 22:39:00 +0900

이전글 : https://blacknabis.tistory.com/38

[개발일지] SF6 뷰어 V1.1 업데이트: 커스텀 배경 스킨 및 데이터 정합성 개선

지난번 UI 리디자인 업데이트 이후, 많은 분들이 각자의 방송 환경에 맞게 뷰어를 활용할 수 있도록 개인화(Customization) 옵션에 대한 필요성을 느꼈습니다. 이번 V1.1 업데이트에서는 방송 화면을 더욱 개성 있게 꾸밀 수 있는 '커스텀 배경 스킨' 기능과, 데이터 정합성을 높이기 위한 내부 로직 개선을 진행했습니다.

챕터 1: 방송 화면 커스터마이징 (커스텀 배경 스킨 지원)

기존에는 게임 화면 위에 자연스럽게 녹아들도록 완전 투명(Transparent) 배경만을 고정으로 사용했습니다. 하지만 스트리머마다 다른 컨셉의 방송 화면을 꾸밀 수 있도록, 자유로운 배경 스킨 적용 기능을 새롭게 추가했습니다.

1. 로컬 경로 및 URL을 통한 배경 이미지 삽입

업로드 및 URL 지원: 대시보드의 'Stats Background' 메뉴에서 웹 이미지 URL을 직접 입력하거나, [Browse...] 버튼을 통해 PC에 저장된 로컬 이미지 파일을 바로 업로드할 수 있습니다.
업로드된 이미지는 서버에 안전하게 저장(custom_bg.img)되며 새로고침해도 설정이 유지됩니다.

2. 가독성을 고려한 독립적인 0~100% 투명도(Opacity) 조절

단순히 전체 창에 투명도를 줄 경우, 텍스트와 그래프까지 흐려져버려 가장 중요한 '가독성'을 해치는 문제가 발생합니다.
이를 해결하기 위해 가장 하단에 전용 배경 레이어(bg-layer)를 깔아 이미지에만 단독으로 투명도를 먹이는 방식으로 구현했습니다.
결과: 배경은 0~100%로 세밀하게 반투명 효과(Glassmorphism)를 주면서도, 맨 앞의 정보(캐릭터, 승률, MR 그래프 등)는 100% 선명하게 돋보이도록 처리했습니다.

3. 컴팩트 사이즈(`1400x180`) 자동 최적화

OBS 브라우저 소스 표준 규격으로 맞춘 1400px x 180px 하단바 사이즈에 맞추어, 어떤 크기의 이미지를 업로드하더라도 여백 없이 예쁘게 가득 차도록 background-size: cover 설정을 적용했습니다.

ㅁ

챕터 2: 데이터 정합성 개선 (MR 변동 그래프 버그 수정)

디자인을 넘어 데이터의 정확도 또한 놓칠 수 없습니다. 우측 MR 히스토리 차트가 종종 시간의 역순(최신 기록 -> 과거 기록)으로 그려지는 현상이 발견되어 쿼리 구조를 개편했습니다.

1. 매치(Match) 로딩 순서 교정

기존에는 데이터베이스에서 가장 최근 N개의 매치를 불러온 그대로 그래프에 출력하여, 차트의 가장 마지막 지점과 현재 실제 MR이 불일치하는 오류가 있었습니다.
백엔드(/api/mr_history) 조회 로직을 수정하여, 최근 매치 데이터들을 가져온 뒤 완벽한 시간 순서(오래된 순 -> 최신 순)로 재정렬한 후 프론트에 전달하도록 개선했습니다.
이제 차트는 항상 최신 흐름을 향해 우상향(혹은 우하향)하는 정확한 추이를 시각적으로 보여줍니다.

⚙️ 챕터 3: 배포 및 실행 편의성 강화

1. V1.1 릴리즈 빌드 (`SF6ViewerV1_1.zip`)

파이썬(Python) 환경에 익숙하지 않은 윈도우 유저분들도 단 1번의 클릭만으로 손쉽게 프로그램을 실행할 수 있도록, 새로운 기능을 병합하여 독립형 실행 파일(EXE) 버전을 V1.1로 패키징해 배포했습니다.
GitHub Releases 탭에서 SF6ViewerV1_1.zip을 다운받으실 수 있습니다.

2. Mac 유저를 위한 문서 최신화

윈도우 환경 이외에 Playwright와 소스코드를 직접 받아야 하는 macOS 유저들을 위해, 프로젝트 README_MAC.md와 메인 README.md 문서를 이번 신기능 설명과 함께 일괄 최신화했습니다.

OBS에서 적용 화면

Godot엔진으로 Lucky7Quest 만들기(codex,antigravity,claude code)

blacknabis — Wed, 11 Mar 2026 00:58:47 +0900

플레이화면. 퇴근후 짧은시간 작업한거 치고는 나쁘지 않은것 같다...

Godot 4.6 방치형 RPG 'Lucky7Quest' 개발기: AI 파트너와 함께한 A to Z 파이프라인 구축

최근 사이드 프로젝트로 개발을 시작한 Lucky7Quest는 Godot 4.6 엔진을 기반으로 한 슬롯머신 하이브리드 클릭커/방치형 RPG입니다. 플레이어는 몬스터와 전투를 벌이며, 3x3 멀티라인 슬롯머신을 돌려 공격, 회복, 쉴드, 코인 획득 등의 스킬 액션을 발동시키는 독특한 메커니즘을 가지고 있습니다.

이번 개발 과정의 가장 큰 특징은 단순한 코드 작성을 넘어 기획, UI 디자인, 그래픽 리소스 생성, 사운드 합성, VFX 연출까지 AI 에이전트(Antigravity)와 100% 페어 프로그래밍(혹은 오케스트레이션)을 통해 진행했다는 점입니다.

오늘은 설치 단계부터 완성도 높은 빌드를 뽑아내기까지의 작업 과정을 블로그에 기록해 봅니다.

1. 프로젝트 초기 설정 및 기획 (Setup & Planning)

가장 먼저 PRD(제품 요구사항 정의서)를 기반으로 게임의 전반적인 구조를 세우는 작업부터 시작했습니다. AI가 PRD를 분석하여 구체적인 Game Design & Architecture Document를 작성했고, 이를 바탕으로 GitHub 리포지토리 연동 및 CI/CD를 위한 Headless 테스트 환경(test_runner.gd) 메커니즘을 구축했습니다.

초기 뼈대가 튼튼했기에 이후 진행된 모든 에셋 통합이나 UI 변경 작업에서도 테스트 코드를 돌려보며 안정성을 확보할 수 있었습니다.

2. 모바일 최적화 및 UI 전면 리디자인 (Mobile UI Redesign)

게임을 모바일 환경에 맞게 서비스하기 위해, 기존의 가로형 레이아웃을 모바일 세로형(720x1280)으로 전면 개편했습니다.

Godot의 강력한 UI 시스템인 MarginContainer, VBoxContainer, HBoxContainer 등을 활용하여 HUD, BattleZone, SlotMachine 노드들을 일괄 재배치했습니다.
레트로 RPG 게임의 감성을 살리기 위해 미니멀한 픽셀 아트 톤의 StyleBoxFlat 기반 테마 컨테이너를 디자인했습니다.
트러블 슈팅: 중간에 "Enemy ATK..." 와 같은 긴 텍스트가 삽입되면서 UI 컨테이너가 가로 해상도 한계(720px)를 뚫고 짤리는(Clipping) 버그가 발생했습니다. AI와 함께 텍스트들이 초상화 사이를 밀어내지 않도록 별도의 하단 FooterBox를 분리하고 자동 줄바꿈(Autowrap)을 적용해 깔끔하게 해결했습니다.

3. 픽셀 아트 에셋 생성 및 연동 (Pixel Art Assets)

UI가 완성된 후, 밋밋했던 임시 텍스처(ColorRect)들을 실제 그래픽스로 교체할 차례였습니다.
생성형 AI를 활용하여 총 13종의 픽셀 아트 에셋을 생성했습니다.

슬롯 심볼 (6종): 검(Sword), 지팡이(Wand), 방패(Shield), 하트(Heart), 코인(Coin), 숫자 7(Seven)
캐릭터 및 몬스터 (7종): 기사, 슬라임, 박쥐, 고블린 정찰병, 해골 병사, 불꽃 임프, 슬라임 킹

배경을 투명하게 날리는 후처리를 진행한 뒤, 에셋들을 알맞은 폴더에 배치하자 Godot UI들이 자동으로 이를 인식하며 게임다운 비주얼을 폭발적으로 뽐내기 시작했습니다.

4. 절차적 레트로 오디오 합성 (Procedural Audio)

인디 게임 개발의 큰 난관 중 하나인 사운드 역시 AI 파이프라인으로 해결했습니다.
단순히 저작권 없는 음원을 찾는 대신, 파이썬(Python) 스크립트를 작성하여 8-bit 레트로 감성의 .wav 사운드를 절차적(Procedural)으로 직접 합성했습니다.

Sine, Square, Noise 파형을 수학적으로 섞어 6종의 고유한 효과음(SFX: 클릭, 타격, 동전, 스핀, 업그레이드 등)을 생성했습니다.
백그라운드 뮤직(BGM)용으로 C-Major 스케일의 아르페지오 칩튠(Chiptune) 사운드를 뽑아내어 적용했습니다.
AudioManager 스크립트를 리팩토링하여 각 이벤트가 발생할 때마다 알맞은 레트로 사운드가 출력되도록 연동했습니다.

5. 시각적 쥬시함(Juiciness) 추가: VFX와 애니메이션

정적인 화면에 생동감(Game Feel)을 주기 위해 Godot의 Tween 시스템을 극한으로 활용한 시각적 효과(VFX)를 추가했습니다.

슬롯머신 3D 플립 애니메이션: 슬롯이 회전하고 멈출 때 단순히 이미지가 바뀌는 것이 아니라, Y축 스케일 기반의 뒤집기 파티클 효과를 줘서 타격감을 높였습니다.
플로팅 데미지 텍스트: 데미지나 힐이 발생하면 캐릭터 머리 위로 숫자가 통통 튀어오르며 서서히 사라지는 연출을 추가했습니다.
피격 플래시 & 타격 모션: 공격을 받으면 초상화가 붉은색으로 깜빡이고(Hit Flash), 뒤로 살짝 밀려났다가 돌아오는(Attack Bump) 역동적인 움직임을 주었습니다.
글로벌 화면 흔들림(Screen Shake): 크리티컬 히트가 터지거나 보스를 뚫고 다음 스테이지로 넘어갈 때, 화면 전체가 거칠게 흔들리도록 Camera2D를 제어했습니다.

회고 및 마무리

하루 만에 빈 프로젝트 세팅에서 시작하여, UI-그래픽-사운드-VFX까지 모두 갖춘 플레이어블 빌드를 만들어냈습니다. 가장 놀라운 점은 이 모든 작업이 개발자와 AI 간의 끊임없는 핑퐁(디자인 문서 설계 -> 에셋 생성 -> 코드 연동 -> 버그 수정)을 통해 막힘없이 이루어졌다는 점입니다.

소규모 인디 개발이나 1인 개발 환경에서, AI 오케스트레이션 파이프라인이 어떤 파급력을 가져올 수 있는지 확실하게 체감할 수 있었던 프로젝트입니다. 앞으로 남은 콘텐츠 확장 작업 역시 동일한 파이프라인을 거쳐 속도감 있게 전개해 나갈 예정입니다.

끝까지 읽어주셔서 감사합니다!

codex,antigravity,claude code 3개의 에이전트를 전부 사용하였으며 codex는 전체적은 플랜, 스크립트, 클루드는 플랜, 안티그래비티에서는 플랜, 스크립트, 이미지 및 사운드 생성 진행.

OpenAI Codex에 GPT-5.4 도입, 무엇이 달라졌나

blacknabis — Tue, 10 Mar 2026 01:51:49 +0900

OpenAI가 공식적으로 ChatGPT, API, Codex에 GPT-5.4 모델을 도입했다고 발표했다. 이번 업데이트는 단순히 새로운 모델이 추가된 수준이 아니라, 코딩·추론·에이전트 워크플로를 하나의 프런티어 모델에 통합했다는 점에서 의미가 크다.

공식 발표에 따르면 GPT-5.4는 전문 작업을 위한 가장 뛰어난 성능과 효율을 갖춘 프런티어 모델이다. 특히 Codex 관점에서 보면, GPT-5.4는 기존의 GPT-5.3-Codex가 보여준 강력한 코딩 역량을 바탕으로 하면서도, 여기에 에이전트 기능과 컴퓨터 사용, 도구 활용 능력까지 더 확장한 모델로 소개된다.

GPT-5.4는 Codex에서 왜 중요한가

Codex는 단순히 코드를 한 번 생성해주는 도구가 아니라, 코드를 작성하고 수정하고 디버깅하고 여러 단계를 거쳐 작업을 이어가는 에이전트형 코딩 도구에 가깝다.

이번에 공개된 GPT-5.4는 바로 이런 Codex의 특성과 잘 맞는다. OpenAI는 GPT-5.4가 추론, 코딩, 에이전트 기반 워크플로 영역의 기술 발전을 하나의 모델로 통합했다고 설명하고 있다.

즉 Codex에 GPT-5.4가 적용된다는 것은 단순한 모델 교체가 아니라, 더 복잡한 작업을 이해하고 장시간 문맥을 유지하며 도구를 더 효율적으로 선택하고 여러 단계의 개발 작업을 더 안정적으로 수행하는 방향으로 Codex가 진화하고 있다는 의미로 볼 수 있다.

GPT-5.3-Codex의 코딩 역량을 메인라인 모델에 통합

공식 발표에서 특히 눈에 띄는 문장은 GPT-5.4가 gpt-5.3-codex의 프런티어 수준 코딩 역량을 통합한 첫 번째 메인라인 추론 모델이라는 설명이다.

이 표현은 중요하다. 기존에는 Codex 계열의 강력한 코딩 성능이 별도 모델처럼 인식됐다면, 이제는 GPT-5.4가 그 성능을 메인라인 모델 안으로 끌어온 셈이기 때문이다. OpenAI가 모델명을 별도로 GPT-5.4로 정한 이유도 여기에 있다. 새로운 기능적 도약을 반영하고, Codex 사용 시 모델 선택을 더 단순하게 하기 위해서라고 설명한다.

Codex에서 주목할 만한 변화

최신 수준의 컴퓨터 사용 기능 기본 제공
최대 100만 토큰 컨텍스트 지원
도구 검색 기능 추가로 더 효율적인 도구 선택
SWE-Bench Pro 기준 GPT-5.3-Codex와 동등하거나 그 이상 성능
Codex의 /fast 모드에서 최대 1.8배 속도 향상

이 가운데 특히 컴퓨터 사용 기능은 Codex 같은 에이전트형 개발 환경에서 중요한 변화다. OpenAI는 GPT-5.4가 사용자를 대신해 컴퓨터를 직접 조작하고, 여러 애플리케이션에 걸친 복잡한 워크플로를 수행하며, 장시간 작업을 계획하고 실행하고 검증할 수 있다고 설명한다.

또한 도구 검색 기능은 도구가 많은 환경에서도 필요한 정의만 불러와 사용할 수 있도록 바뀌어, 토큰 사용량을 줄이고 비용과 지연 시간을 낮추는 방향으로 개선되었다. Codex처럼 여러 도구와 연결되는 환경에서는 특히 의미 있는 변화다.

코딩 모델을 넘어 개발 에이전트로

이전의 코딩 모델이 잘 작성하는 것에 초점이 있었다면, 이번 GPT-5.4는 잘 작성하는 것에 더해 실제로 실행하고 연결하는 것까지 포함하는 방향으로 확장됐다고 볼 수 있다.

정리하면 GPT-5.4는 Codex를 더 강한 코딩 역량, 더 긴 문맥 유지, 더 나은 도구 선택, 더 빠른 반복 작업 처리, 그리고 더 복잡한 에이전트형 워크플로를 지원하는 방향으로 끌고 가고 있다.

마무리

OpenAI 공식 발표 기준으로 GPT-5.4는 이제 ChatGPT, API, Codex 전반에 걸쳐 제공된다. 특히 Codex에서는 GPT-5.3-Codex의 강력한 코딩 역량을 메인라인 모델에 통합하면서, 컴퓨터 사용 기능과 도구 검색, 긴 컨텍스트, 빠른 작업 흐름까지 함께 강화한 점이 핵심이다.

즉 이번 업데이트는 단순히 새 모델 출시라기보다, Codex를 더 강력한 코딩 에이전트로 확장하는 업데이트로 보는 것이 더 적절해 보인다.

공식 발표 보러 가기

AI 시대, 개발자는 어떻게 살아남아야 할까 - 스탠포드 강의가 던진 질문

blacknabis — Tue, 10 Mar 2026 01:37:30 +0900

요즘 AI 관련 유튜브가 진짜 많이 올라온다.

툴 소개, 자동화, 생산성, 미래 전망 같은 영상이 하루에도 엄청 쏟아지는데, 솔직히 보다 보면 다 비슷비슷하게 느껴질 때가 많다.

그런데 오랜만에 처음부터 끝까지 집중해서 본 영상이 하나 있었다.

이번에 본 영상은 EO Korea 채널의

‘스탠포드에서 빅테크로 조용히 퍼지는 개발자 생존법, 대부분 모릅니다 | 미하일 에릭’ 이다.

이 영상이 괜찮았던 이유는 단순히

“AI가 대단하다”, “앞으로 세상이 바뀐다”

이런 식의 뻔한 이야기만 하는 게 아니라,

AI 시대에 개발자가 실제로 어떻게 일하게 될지를 생각하게 만든다는 점이었다.

영상 설명을 보면 스탠포드에서 진행된

‘The Modern Software Developer’ 강의를 바탕으로 한 내용이라고 한다.

그래서 그런지 그냥 자극적인 제목 장사 느낌보다는,

개발자의 역할이 앞으로 어떻게 달라질지에 대한 이야기에 더 가까웠다.

보면서 가장 크게 든 생각은 이거였다.

이제 개발자는 단순히 코드를 잘 짜는 사람만으로는 부족하겠구나.

예전에는 직접 구현하고, 직접 디버깅하고, 직접 다 만드는 능력이 중요했다면

이제는 AI를 같이 쓰면서

문제를 더 잘 정의하고
원하는 결과를 더 정확하게 요청하고
나온 결과를 빠르게 검토하고
여러 도구를 연결해서 실제 결과물로 만드는 능력

이런 게 훨씬 중요해지고 있다는 느낌이 들었다.

결국 앞으로는 개발자가 단순한 코더라기보다

설계하고, 조율하고, 검증하는 역할에 더 가까워질 수도 있겠다는 생각이 들었다.

영상에서 인상적이었던 부분 중 하나는

기존 방식이랑은 좀 다른 식으로 일하는 개발자들이 이미 등장하고 있다는 흐름이었다.

예전처럼 전부 손으로 하나하나 만드는 데 익숙한 사람보다,

AI를 활용해서 더 빨리 실험하고, 더 빨리 수정하고,

더 빨리 결과를 만드는 사람이 점점 유리해질 것 같다는 생각도 들었다.

결국 중요한 건

AI를 쓰냐 안 쓰냐보다

AI를 자기 일에 얼마나 자연스럽게 붙여서 쓰느냐인 것 같다.

요즘 각종 AI 유튜브가 많이 올라오는데

오랜만에 처음부터 끝까지 정독한 유튜브였다.

개발을 하고 있거나,

AI 시대에 개발자의 역할이 어떻게 바뀔지 궁금한 사람이라면

한 번쯤 직접 봐도 괜찮은 영상이라고 생각한다.

영상 링크는 아래 남겨둔다.

https://youtu.be/qEF-eUaTq0Y?si=QEi8LSzdJ0t_053y

타워디펜스 만들기 - Stage 운영 구조를 갈아엎고, 월드맵 UI와 선택 체감을 다듬기(Codex)

blacknabis — Sun, 8 Mar 2026 01:19:33 +0900

들어가며

godot엔진을 공부하기 위해 (cluade code, antigravity를 사용하였기 때문에 codex로만 작업을 진행.)

이번 작업은 기능 하나를 추가하는 식의 단발성 수정이 아니었다.
스테이지를 계속 늘려갈 수 있는 운영 구조를 만들고, 월드맵 UI를 정리하고, 실제 플레이 체감까지 손보는 쪽에 가까웠다.

정리하면 2026-03-07부터 03-08까지 한 일은 크게 네 가지다.

StageId 단일 int 구조를 WorldId + StageNumber + StageKey로 확장
Draft / Test / Playable 상태 기반 운영 구조 도입
Stage 2를 다시 설계하고 자동 오케스트레이션에 태움
월드맵 popup과 선택 시스템을 실제 사용 기준으로 정리

겉으로 보면 서로 다른 작업처럼 보이지만, 결국 하나의 방향으로 연결돼 있다.

“새 맵을 계속 추가해도, 운영 데이터와 작업 중 데이터를 섞지 않고, UI와 테스트 동선까지 버티는 구조를 만들자.”

1. Stage 1 only 구조를 버린 이유

초기에는 사실상 Stage 1만 운영 기준이었다.
문제는 Stage 2부터는 테스트 잔재 데이터와 작업 중 자산이 섞여 있어서, 맵을 늘릴수록 기준이 흐려진다는 점이었다.

예전 방식의 문제는 명확했다.

StageId 단일 int에 모든 의미가 몰려 있었다
운영 스테이지와 작업 중 스테이지를 코드가 구분하지 못했다
월드맵, 저장, 결과 복귀, 스킬 조건, 보스 이벤트가 모두 같은 키 체계에 기대고 있었다
Stage 2를 테스트하려고 상태를 억지로 운영 상태처럼 다뤄야 했다

그래서 이번에는 아예 구조를 바꿨다.

public readonly struct StageKey
{
    public readonly int WorldId;
    public readonly int StageNumber;
}

여기에 StageContentStatus를 붙였다.

public enum StageContentStatus
{
    Draft,
    Test,
    Playable
}

핵심은 단순하다.

Draft: 제작 중
Test: 내부 테스트용
Playable: 실제 운영 가능

이렇게 나누고 나니 월드맵, 게임씬, 저장, 에디터 도구가 같은 기준으로 움직이기 시작했다.

2. Stage 2를 다시 “쓸 수 있는 초안”으로 만든 과정

Stage 2는 맵 경로와 타워 슬롯은 이미 들어가 있었지만, 웨이브 데이터는 예전 테스트 흔적이 많이 남아 있었다.

처음 확인한 문제는 이런 식이었다.

현재 맵은 단일 경로인데 웨이브는 존재하지 않는 PathId를 참조
테스트용 낮은 시작 자원과 임시 조합이 섞여 있음
실제 스테이지 초안이라기보다 실험 데이터에 가까움

그래서 목표를 먼저 잠갔다.

역할: 학습 확장형
상태: Draft
목표: 초심자 1회 클리어 가능
구조: 7 waves, PathId 0 only
규칙: Wave 1~6 최소 8마리

초기 초안은 자동 회귀 기준으로는 파손이 없었다.
문제는 실제 플레이였다.

직접 해보니 초반 아처 3개를 전방에 깔면 이후 추가 건설 없이도 클리어가 가능했다.

이건 두 가지를 의미했다.

시작 골드가 많다
중후반 압박이 약하다

그래서 2차 조정에서는 방향을 분명하게 잡았다.

InitialGold: 360 -> 280
Wave 4~7 물량 상향
초반 Wave 1~3는 유지

최종 초안은 이렇게 정리했다.

InitialGold = 280
InitialLives = 75

W1: Goblin x8
W2: Goblin x8 + Scout x2
W3: Goblin x8 + Scout x2
W4: Goblin x10 + Orc x4
W5: Scout x8 + Goblin x6
W6: Goblin x10 + Orc x5
W7: Goblin x10 + Orc x4 + Shaman x2

아직 Playable은 아니다.
하지만 최소한 “작업 중 Draft 자산”이 아니라, 실제로 검증 가능한 초안 상태까지는 끌어올렸다.

3. 테스트 동선을 바꾼 이유

구조를 엄격하게 만들면 보통 테스트가 불편해진다.

실제로 Draft/Test를 운영 경로에서 막아버리면, 개발자는 새 스테이지를 확인할 때마다 상태를 바꾸거나 별도 메뉴를 타야 한다.
이건 스테이지가 하나둘일 때나 참을 수 있다.

그래서 운영 원칙과 개발자 동선을 분리했다.

운영 기준: Playable만 시작 가능
개발자 기준: 에디터/개발 빌드에서는 Draft/Test도 월드맵에서 직접 시작 가능

이렇게 해두니 두 마리 토끼를 같이 잡을 수 있었다.

운영 구조는 안 무너진다
개발자는 월드맵에서 바로 새 스테이지를 눌러 테스트할 수 있다

이 작업은 단순 편의 기능이 아니라, 콘텐츠 생산 속도를 떨어뜨리지 않기 위한 안전장치에 가까웠다.

4. 월드맵 popup은 결국 프리팹 기준으로 정리했다

이번 구간에서 의외로 시간을 많이 쓴 부분이 월드맵 popup이었다.

문제는 두 가지였다.

4.1 한글 깨짐

처음엔 폰트 문제처럼 보였는데, 실제 원인은 코드에서 런타임으로 만드는 문자열 일부가 깨져 있던 쪽이었다.
총 별, 사용 별, 남은 별, 강화, 별이 부족합니다 같은 문구를 정상 한글로 정리하면서 바로 잡았다.

4.2 유지보수 방식

더 큰 문제는 UI 레이아웃을 코드가 런타임에 자꾸 다시 만들고 밀어넣는 구조였다.

이 구조는 처음엔 빠르지만 결국 이런 문제가 생긴다.

프리팹을 수정해도 코드가 덮어쓴다
어떤 값이 실제 기준인지 파악하기 어렵다
참조가 깨져도 fallback UI가 조용히 뜬다
버그가 “즉시 드러나지 않고” 나중에 이상한 형태로 나타난다

그래서 방향을 바꿨다.

SkillTreeUI, HeroSelectionUI를 프리팹 기준 구조로 전환
빌더 메뉴로 프리팹 재생성 가능하게 정리
최종적으로 런타임 fallback 제거
참조 누락 시 Debug.LogError + 중단

이제는 프리팹이 기준이고, 문제가 있으면 바로 드러난다.
유지보수 관점에서는 이쪽이 훨씬 낫다.

5. 선택 체감: “보이는 걸 눌렀는데 왜 안 눌리지?”

플레이하다 보면 가장 거슬리는 버그 중 하나가 이런 종류다.

“오브젝트 이미지를 눌렀는데 선택이 안 된다.”

원인을 보면 대개 단순하다.
보이는 스프라이트를 누르는 게 아니라, 더 작은 충돌 범위나 중심점 거리를 누르고 있기 때문이다.

이번에는 선택 판정을 SpriteRenderer.bounds 기준으로 보강했다.

즉,

영웅
적
병사
타워

모두 “실제로 보이는 이미지”에 더 가깝게 선택되도록 만든 것이다.

그리고 여기서 한 걸음 더 가서, 타워를 선택하면 공격 범위가 따로 보이도록 했다.

선택 원과 범위 원은 분리
일반 타워는 공격 범위
배럭은 RallyRange
선택 해제 시 즉시 숨김

처음엔 범위용 스프라이트 로드가 안 되어 Hierarchy에는 있는데 게임 화면에는 안 보이는 상태가 있었다.
원인은 새 이미지의 임포트 설정이 Multiple Sprite였던 쪽이었고, Single로 정리하면서 해결했다.

이건 작은 디테일 같지만 체감에는 꽤 중요했다.
“선택됐다”와 “어디까지 닿는지 안다”는 플레이 감각이 완전히 다르기 때문이다.

6. 오케스트레이션을 같이 굴린 이유

이번 작업에서 개인적으로 가장 중요하게 본 건, 기능을 넣는 것보다 회귀를 같이 잠그는 것이었다.

구조 변경, UI 변경, 밸런스 변경은 서로 영향을 많이 준다.
이럴 때 수동 테스트만 믿으면, 당장은 보여도 나중에 어디서 깨졌는지 찾기 어려워진다.

그래서 가능한 건 오케스트레이션에 같이 태웠다.

Selection UI smoke
Stage1 Pipeline
Stage2 Draft Pipeline
WorldMap Meta Popup Regression
BattleSim Economy Checklist

그리고 포커스를 잃으면 회귀가 멈추는 문제도 같이 잡았다.
프로젝트가 기본적으로 runInBackground: 0이라서, 회귀 실행 동안에는 Application.runInBackground = true를 강제로 켜고 끝나면 복원하도록 보강했다.

결국 이번 이틀 작업은 “기능 추가”라기보다, 작업 흐름 전체를 덜 깨지게 만드는 쪽에 더 가까웠다.

7. 이번 작업에서 얻은 정리

이번 구간에서 특히 확실해진 건 세 가지다.

1. 운영 구조와 개발자 편의는 분리해야 한다

운영 기준을 느슨하게 하면 결국 데이터가 섞인다.
반대로 너무 엄격하게 막으면 개발이 느려진다.
Draft/Test/Playable + 개발자 전용 월드맵 시작 게이트 조합은 이 균형을 잘 잡아줬다.

2. UI는 결국 프리팹이 기준이어야 한다

코드 fallback은 프로토타입 단계에서는 빠르지만, 운영 단계에서는 문제를 숨기는 쪽으로 작동한다.
지금처럼 popup 구조가 정리된 뒤에는 fail-fast가 맞다.

3. 자동 회귀는 기능이 아니라 작업 속도다

선택 판정, popup, 웨이브 초안, 월드맵 진입처럼 서로 얽힌 변경이 많아질수록
“한 번에 돌려보고 상태를 잠글 수 있는 흐름” 자체가 생산성이다.

8. 다음 작업

다음 우선순위는 명확하다.

Stage 2 실제 플레이를 3~5회 더 돌린다
3아처 방치 클리어가 완전히 깨졌는지 확인한다
필요하면 Wave 5~7만 추가 미세 조정한다
이후 Stage 2를 Test로 올릴지 판단한다

그리고 선택/범위 표시 쪽은 이제 체감이 안정적이면 큰 구조 변경보다는 시각 튜닝 단계로 넘어가면 된다.

마무리

이번 작업은 눈에 확 들어오는 새 기능보다, 프로젝트가 앞으로 더 많은 스테이지와 UI 변경을 감당할 수 있게 바닥을 다시 까는 작업에 가까웠다.

특히 좋았던 건, 코드를 바꾼 뒤 끝내지 않고

자산
프리팹
문서
자동 회귀
실제 플레이 피드백

을 같이 묶어서 잠그는 흐름이 조금씩 자리를 잡기 시작했다는 점이다.

지난 블로그의 사진과 외관상 큰차이는 없지만 타워 공격 범위가 잘보인다.

AI "진행해" vs "해줘"

blacknabis — Sun, 8 Mar 2026 01:13:51 +0900

최근 제미나이(Gemini), 클로드(Claude) 같은 강력한 LLM과 코딩 어시스턴트들을 동시에 활용하면서, 복잡한 업무를 자동화하는 '파이프라인 오케스트레이션(Pipeline Orchestration)'에 대한 관심이 뜨겁습니다.

단순히 AI에게 질문을 던지고 텍스트 답변을 받는 것을 넘어, 여러 단계의 툴과 프로세스를 매끄럽게 연결하는 것이 핵심입니다. 예를 들어, LLM으로 퀘스트 시나리오를 작성하고, 그 결과물을 ComfyUI 같은 이미지 생성 API로 넘겨 일러스트를 뽑아낸 뒤, 유니티(Unity) 프로젝트 폴더에 자동 배치하는 일련의 흐름을 통제하는 것이죠.

그렇다면 AI에게 이런 복잡한 파이프라인 설계를 맡길 때, 어떤 프롬프트를 써야 가장 완벽한 결과물을 얻을 수 있을까요?

1. 프롬프트의 오해와 진실: "진행해" vs "해줘"

종종 커뮤니티를 보면 "AI에게 지시할 때 '진행해'라고 하면 프로세스를 짜주고, '해줘'라고 하면 코드를 짜준다"는 식의 팁이 돌아다닙니다. 하지만 이는 최신 LLM의 작동 방식을 오해한 과잉 일반화입니다.

현대의 고성능 AI 모델들은 한국어 어미의 미세한 뉘앙스 차이보다는 전체 문맥과 명시적인 요구사항에 집중합니다. 어미를 어떻게 끝내든, 요구하는 바가 모호하다면 AI는 적당히 일반적인 답변을 뭉뚱그려 내놓을 뿐입니다.

그렇다면 두 어미 간에 차이가 아예 없을까요? 진짜 차이는 결과물의 '포맷'이 아니라, '부탁'과 '명령'이라는 톤(Tone)에서 만들어집니다.

"~해줘" (부탁조의 친절함): 대화형 AI의 특성상 친근한 부탁조로 지시하면, AI 역시 '친절한 어시스턴트'의 역할에 몰입합니다. 그 결과, 파이프라인 코드를 짜주면서도 앞뒤로 불필요한 인사말이나 코드 작동 원리에 대한 장황한 부연 설명을 덧붙이는 경향이 있습니다.
"~진행해" (명령조의 간결함): 반면 감정을 뺀 명확한 명령조로 지시하면, AI는 서론과 결론을 생략하고 요구받은 핵심 결과물만 간결하고 건조하게 출력할 확률이 높아집니다.

따라서 파이프라인 코드나 YAML 설정 파일처럼 군더더기 없는 텍스트만 빠르게 복사해서 실무에 적용해야 할 때는, 정중한 부탁보다는 단호하고 명확한 명령조를 사용하는 것이 오히려 더 효율적일 수 있습니다.

2. 실무에 쓰는 AI 툴, 각자의 강점 활용하기

사용하는 AI 툴의 특성을 이해하고 파이프라인의 각 단계에 맞게 활용하면 효율을 극대화할 수 있습니다.

클로드(Claude): 깐깐한 구조 설계자 지시사항 준수율이 매우 높습니다. 복잡한 워크플로우를 JSON이나 YAML 같은 특정 데이터 포맷으로 정리해 달라고 명확히 요구했을 때, 가장 에러가 적고 논리적인 구조를 잘 뽑아냅니다.
제미나이(Gemini): 큰 그림을 그리는 아키텍트 방대한 컨텍스트를 파악하는 데 능합니다. 여러 툴이 얽힌 복잡한 파이프라인의 전체적인 데이터 흐름이나 아키텍처 다이어그램의 초안을 기획할 때 유용합니다.
코드 어시스턴트 (Copilot, Cursor 등): 즉시 투입 가능한 실무자 과거의 코덱스(Codex) 모델처럼 코드 생성에 특화된 환경에서는, 설계된 아키텍처를 바탕으로 Airflow DAG나 Python 실행 스크립트 등 실제 돌아가는 코드를 IDE 내에서 바로 짜는 데 최적화되어 있습니다.

3. 성공적인 파이프라인 설계를 위한 프롬프트 공식

AI에게 완벽한 파이프라인 오케스트레이션을 지시하려면 마법의 단어를 찾을 것이 아니라, [역할 부여] + [구체적 태스크] + [출력 형식] 이 세 가지를 프롬프트에 조립해야 합니다.

[잘 작성된 프롬프트 예시] "너는 게임 개발 자동화 파이프라인 엔지니어야. (역할) LLM이 생성한 시나리오 데이터를 바탕으로 ComfyUI API를 호출해 에셋을 생성하고, 이를 Unity 프로젝트 폴더에 포맷에 맞춰 자동 저장하는 파이프라인을 설계해. (구체적 태스크) 전체 워크플로우의 실행 로직을 Airflow 기반의 Python 코드로 작성하고, 필요한 환경 설정은 YAML 포맷으로만 간결하게 출력해." (출력 형식 + 명령조)

이렇게 목적과 포맷, 그리고 어조를 정확히 짚어주면 AI는 군더더기 없이 곧바로 실무에 적용 가능한 수준의 오케스트레이션 코드를 반환합니다.

마무리하며

파이프라인 오케스트레이션 구축의 핵심은 AI를 '마법사'가 아닌 '실무자'로 대하는 데 있습니다. 원하는 결과물의 형태와 사용할 도구를 명확히 지정하는 프롬프트 엔지니어링을 통해, 여러분의 개발 워크플로우를 획기적으로 자동화해 보시기 바랍니다. 그리고 작업에 있어서 국어에 대해 더욱 공부하고 잘 써야되겠다고 많이 느꼈습니다. 명령조와 부탁조의 차이가 다르다고 주변에 사람들에게 많이 들었는데

고도엔진으로 AI 사용하여 게임만들기

blacknabis — Sun, 8 Mar 2026 01:06:29 +0900

AI와 고도 엔진(Godot)으로 만드는 하드코어 2D 플랫포머 제작기

안녕하세요! 오늘은 AI 개발 에이전트와 Godot 4.6 Engine을 활용하여 스팀의 인기 게임인 '스마일모(Smilemo)' 느낌이 나는 2D 하드코어 런 게임을 어떻게 기획하고 구현했는지 공유해 보려고 합니다.

혼자서 모든 것을 코딩하는 대신, AI 에이전트와 역할을 나누어 "파이프라인 오케스트레이션(Pipeline Orchestration)" 이라는 방식으로 병렬 개발을 진행해 본 아주 흥미로운 경험이었습니다.

1. 프로젝트 기획 (PRD 작성)

가장 먼저 한 일은 AI와 함께 개발 기획서(PRD)를 작성하는 것이었습니다. 게임의 목표와 방향성을 명확히 해야 AI 에이전트가 코드를 짤 때 방황하지 않기 때문입니다.

핵심 메커니즘 도출

기존 플랫포머 게임과 이 게임의 가장 큰 차이점은 체력(HP) 시스템의 부재와 바운스 기믹입니다.

HP 없음: 적(바이러스)에 닿으면 죽거나 체력이 다는 것이 아니라, 닿은 반대 방향으로 강력하게 튕겨납니다.
연쇄 바운스: 잘못 튕기면 구덩이에 빠지거나, 다른 바이러스에 연속으로 부딪혀서 스테이지 맨 처음('태초마을')으로 날아갈 우려가 있습니다.
조작 타격감 보강: Z키(보유 시 달리기), 벽타기(Wall Slide/Jump), 그리고 슬라이딩 기능을 넣어 극한의 피지컬 컨트롤 요소가 필요하게 설계했습니다.
수집 요소: 스테이지에 흩어진 '백신 캡슐'을 100% 모두 수집해야만 다음 스테이지로 가는 골(Goal)이 열립니다.

우리는 이 내용을 prd.md 파일에 정리하고, 지속적으로 업데이트하며 개발의 나침반으로 사용했습니다.

2. 개발 프레임워크: 파이프라인 오케스트레이션

제가 지시자를 내리면, AI 에이전트는 작업을 한 번에 순차적으로 처리하는 대신 병렬 파이프라인(Parallel Pipelines) 으로 쪼개서 작업을 기획하고 쳐냈습니다.

예를 들어, 에이전트가 코드를 짤 때:

Pipeline A: 물리 엔진 및 캐릭터 조작(player.gd 수정)
Pipeline B: 스테이지 기믹 및 렌더링 세팅(scenes/level.tscn 구성)
Pipeline C: 개발 일지 갱신(devlog.md, task.md 현행화)

이렇게 오케스트레이션 방식을 요청하자, 에이전트가 로직 구현과 문서화를 동시에 진행하면서 놀라울 정도로 빠르고 체계적으로 아키텍처를 잡고 기능을 구현해주었습니다.

3. 고도 엔진(Godot Engine)에서의 구현 포인트

1) CharacterBody2D를 활용한 커스텀 물리 엔진

고도의 내장된 물리 노드들을 단순히 쓰는 것을 넘어 지상/공중 쿨다운, 가변 점프 높이, 벽 반동 계산 등을 스크립트로 직접 통제했습니다.

# 벽 반동(Wall Jump) 처리 예시
if is_on_wall() and Input.is_action_just_pressed("jump"):
    velocity.y = WALL_JUMP_FORCE_Y
    velocity.x = wall_direction * WALL_JUMP_FORCE_X

2) 타격감 피드백 (게임 필)

바이러스에 맞아 튕겨 나갈 때의 불쾌함을 줄이고 시각적 만족감을 주기 위해 다음 기능들을 조합했습니다.

역경직 (Hit Pause): Engine.time_scale을 아주 잠깐 0.1로 낮추어 슬로모션 효과 유발.
카메라 셰이크 (Camera Shake): 카메라 스크립트에 decay 함수를 적용해 튕겨나가는 순간 화면을 진동시킴.
파티클 (CPUParticles2D): 충돌 지점에서 파편이 튀는 시각 효과 발동.

3) 에셋 자동 생성과 통합 (AI Image Generation)

가개발 단계에서는 단순히 Gothi의 기본 도형인 폴리곤(Polygon2D) 노드로 네모낳게 만들어서 테스트했습니다. 하지만 어느 정도 플레이가 쾌적해진 후, 에이전트에게 "직접 API를 호출해 스프라이트 리소스를 그려서 적용해줘" 라고 요청했습니다.
AI가 플레이어( ), 바이러스( ), 아이템 캡슐( ) 도트 그래픽을 생성해서 스스로 Godot 프로젝트 assets 폴더에 넣고 .tscn 파일 코드를 Sprite2D로 치환까지 전부 해냈습니다!

4. AI 페어 프로그래밍 개발 소감

가장 크게 느낀 점은 "개발 일지(devlog.md)와 태스크 리스트(task.md)의 위력" 입니다.
보통 개인 프로젝트 수준에서는 문서화를 귀찮아서 잘 안 하게 되는데, AI가 코딩을 하면서 동시에 마크다운 문서를 업데이트하게 하니 다음과 같은 장점이 있었습니다.

맥락 유지: 채팅 컨텍스트가 길어져서 AI가 깜빡하더라도, prd.md나 task.md를 다시 열어보게 하면 즉시 원래의 핵심 기획 의도로 돌아옵니다.
빠른 디버깅: 어디서 무얼 고치다가 오류가 났는지 서로 트래킹하기가 굉장히 쉬웠습니다.
오케스트레이션 효율: 어떤 모듈 구조에 어떤 기능이 담당되어 있는지 텍스트 문서로 정리되어 있으니, A모듈 작업과 B기능 수정을 병렬로 완전히 분리해서 요청하기 좋았습니다.

플레이화면 아직 이미지는 제대로 처리되지 않는다.

후기.

유니티로 개발하는것보다 하이퍼캐주얼쪽으로는 AI친화적이라 개발 속도 및 아웃풋이 생각보다 굉장히 좋네요. 고도엔진의 스크립트를 아직 보지 않았기 때문에 100% 바이브코딩으로 진행하였습니다.

AI 에이전트 파이프라인 오케스트레이션

blacknabis — Fri, 6 Mar 2026 00:33:17 +0900

1. 오케스트레이션이란?

AI 에이전트 오케스트레이션은 여러 AI 에이전트를 조율하여 복잡한 워크플로우를 수행하도록 관리하는 기술이다. 단일 LLM 호출로 해결하기 어려운 다단계·다차원 문제를 전문화된 에이전트 팀이 협력하여 처리한다.

왜 필요한가?

단일 에이전트	오케스트레이션
하나의 프롬프트로 모든 것 해결 시도	작업을 분할하여 전문 에이전트에 위임
컨텍스트가 비대해지면 품질 저하	각 에이전트가 자신의 역할에 집중
에러 발생 시 전체 실패	개별 실패 격리 + 재시도 가능
도구 연동 복잡	에이전트별 도구 연동 분리

핵심 인사이트: 2025~2026년 업계의 화두는 "생성형 AI(응답하는 시스템)"에서 "에이전틱 AI(행동하고, 조율하고, 실행하는 시스템)"로의 전환이다.

2. 핵심 오케스트레이션 패턴 8가지

2.1 순차 파이프라인 (Sequential Pipeline)

[에이전트 A] → [에이전트 B] → [에이전트 C] → 결과

한 에이전트의 출력이 다음 에이전트의 입력으로 전달
적합: 문서 처리, 데이터 변환, 대출 승인 같은 선형 프로세스
장점: 단순하고 디버깅이 쉬움
단점: 병목 구간이 전체 성능 결정

2.2 코디네이터/디스패처 (Coordinator / Supervisor)

        ┌→ [전문 에이전트 A] →┐
[오케스트레이터] → [전문 에이전트 B] → [오케스트레이터] → 최종 결과
        └→ [전문 에이전트 C] →┘

중앙 오케스트레이터가 사용자 요청을 분석하여 적절한 전문 에이전트에게 위임
작업 분배, 컨텍스트 공유, 결과 집계, 재시도, 오류 처리를 모두 관리
적합: 고객 서비스, 복합 질의 처리

2.3 병렬 팬아웃/개더 (Parallel Fan-Out / Gather)

        ┌→ [에이전트 A] →┐
[분배기] → [에이전트 B] → [집계기] → 결과
        └→ [에이전트 C] →┘

상호 의존성 없는 작업을 동시 실행하여 처리 속도 극대화
MapReduce 스타일 — 분할 → 병렬 처리 → 합산
적합: 대량 데이터 분석, 다국어 번역, 다중 소스 검색

2.4 계층적 분해 (Hierarchical Decomposition)

[상위 에이전트]
  ├→ [중간 관리 에이전트]
  │     ├→ [작업자 에이전트 A]
  │     └→ [작업자 에이전트 B]
  └→ [중간 관리 에이전트]
        └→ [작업자 에이전트 C]

Planner → Manager → Worker 계층 구조
복잡한 목표를 재귀적으로 분해하여 전문 하위 에이전트에 위임
적합: 대규모 프로젝트 관리, 복잡한 소프트웨어 개발

2.5 제너레이터-크리틱 (Generator & Critic)

[생성 에이전트] ⇄ [검증 에이전트]
         (통과할 때까지 반복)

생성(Generator)과 검증(Critic)의 역할 분리
품질 기준을 통과할 때까지 반복 수정
적합: 코드 리뷰, 콘텐츠 생성, 보고서 작성

2.6 반복적 개선 (Plan-Act-Reflect)

[계획] → [실행] → [반성] → (조건 충족까지 반복)

계획 수립 → 도구 사용하여 실행 → 결과 평가 → 계획 수정
자기 교정(Self-correction)과 지속적 적응에 초점
적합: 연구 자동화, 복잡한 문제 해결, 코드 디버깅

2.7 이벤트 기반 트리거 (Event-Driven)

[이벤트 발생] → [에이전트 활성화] → [처리] → [대기 복귀]

에이전트가 특정 이벤트를 구독하고, 발생 시에만 활성화
컴퓨팅 자원 절약 + 예측 가능성 향상
적합: 모니터링, 알림 시스템, CI/CD 파이프라인

2.8 인간 개입 (Human-in-the-Loop)

[에이전트 처리] → [위험도 판단] → [인간 승인] → [계속 진행]

되돌릴 수 없거나 고위험 결정에 인간 승인 게이트 삽입
자율성과 책임의 균형
적합: 금융 거래, 의료 판단, 법적 결정

3. DAG(방향 비순환 그래프) 기반 워크플로우

현대 오케스트레이션의 핵심 데이터 구조는 DAG이다.

DAG의 장점

비선형 워크플로우: 여러 선행 작업의 결과에 의존하는 복잡한 작업 구조 표현
병렬 실행: 독립적인 브랜치를 동시에 처리하여 효율 극대화
동적 적응: 실행 중 새로운 서브그래프를 동적으로 추가 가능
감사 추적: 작업 상태, 의존성, 실행 이력을 정확히 추적

DAG를 활용하는 프레임워크

프레임워크	특징
LangGraph	순환 그래프 지원, 상태 기반 멀티 에이전트
ZenML	MLOps/LLMOps, 분기·루프 지원
Microsoft Promptflow	DAG 기반 AI 워크플로우
Haystack	조합·모듈러 파이프라인, RAG 특화
Prefect/Temporal	범용 워크플로우 + 내구성 실행

4. 통신 프로토콜: MCP vs A2A

2025~2026년 AI 에이전트 생태계의 통신 표준을 정의하는 두 프로토콜:

MCP (Model Context Protocol) — "에이전트의 손"

제안: Anthropic (2024.11), 이후 Linux Foundation 기증
목적: AI 모델 ↔ 외부 도구/데이터 소스 간 표준 인터페이스
비유: "AI의 USB-C" — 파일 읽기, 함수 실행, 프롬프트 처리를 통일
기술: JSON-RPC 2.0 / stdio 또는 HTTP+SSE, 주로 무상태(Stateless)
채택: OpenAI, Google, 8,000+ 커뮤니티 서버

A2A (Agent-to-Agent Protocol) — "에이전트의 동료"

제안: Google (2025.04), 이후 Linux Foundation 오픈소스
목적: 에이전트 ↔ 에이전트 간 발견·통신·협업
핵심: "Agent Card"로 에이전트 기능 발견, 작업 협업 관리
기술: JSON 메시지 / HTTP, JSON-RPC 2.0 / HTTPS
채택: Salesforce, SAP 등 50+ 파트너

보완 관계

┌─────────────────────────────────────────────────┐
│              Multi-Agent System                  │
│                                                  │
│  [에이전트 A] ←──A2A──→ [에이전트 B]              │
│      │                       │                   │
│     MCP                     MCP                  │
│      │                       │                   │
│  [DB/API/도구]           [외부 서비스]             │
└─────────────────────────────────────────────────┘

MCP = 수직 통합 (에이전트 ↔ 도구/데이터)
A2A = 수평 협업 (에이전트 ↔ 에이전트)
실전에서는 두 프로토콜을 함께 사용하여 모듈형·확장 가능한 AI 생태계 구축

5. 주요 프레임워크 비교

프레임워크	개발사	핵심 특징	적합 사례
LangGraph	LangChain	상태 기반 순환 그래프, 세밀한 제어	복잡한 멀티 에이전트
CrewAI	오픈소스	역할·태스크·도구 기반 "크루" 구조	팀 기반 워크플로우 자동화
AutoGen	Microsoft	이벤트 기반, 자연어 대화·협상	다중 에이전트 대화
Semantic Kernel	Microsoft	엔터프라이즈 통합, AutoGen 결합	기업 시스템 연결
LlamaIndex	오픈소스	RAG 특화, 컨텍스트 인식	데이터 중심 워크플로우
Orkes Conductor	Orkes	내구성 오케스트레이션, 상태 관리	엔터프라이즈급 안정성
Temporal	오픈소스	Durable Execution, 장기 실행	인간 승인 포함 장기 워크플로우
Google ADK	Google	A2A 네이티브, Vertex AI 연동	Google 생태계

6. 아키텍처 설계 시 핵심 고려사항

6.1 컨텍스트 & 메모리 관리

단기 메모리: 현재 대화/작업의 컨텍스트
장기 메모리: 벡터 DB를 통한 지식 저장·검색
에피소딕 메모리: 과거 경험 학습
→ RAG(Retrieval-Augmented Generation)와 결합하여 환각 감소

6.2 상태 관리 & 지속성

다단계 워크플로우의 진행 상태를 영구 저장
장기 실행 프로세스의 중단·재개 지원
체크포인팅으로 실패 시 복구

6.3 에러 처리 & 회복력

개별 에이전트 실패 격리
자동 재시도 + 폴백 메커니즘
서킷 브레이커 패턴 적용

6.4 관측성 (Observability)

에이전트 간 호출 추적 (Tracing)
토큰 소비·비용 모니터링
에이전트 성능 메트릭 수집

6.5 비용 최적화

지능형 라우팅: 간단한 작업은 소형 모델(SLM), 복잡한 작업은 LLM
캐싱: 반복 쿼리에 대한 Semantic Cache 활용
로드 밸런싱: 에이전트 간 작업 균등 분배

6.6 보안 & 가드레일

도구 사용에 대한 권한 제어
위험 행동 방지 규칙 설정
민감 데이터 접근 제한

7. 실전 사례

고객 서비스

Klarna: AI 어시스턴트가 채팅의 상당 부분을 자동 처리, 해결 시간 대폭 단축
멀티 에이전트 CS: Supervisor 에이전트가 질문 분류 → Billing 에이전트(Stripe), Order 에이전트(Shopify) 등에 위임
예방적 지원: 제품 텔레메트리·빌링 이상 분석으로 문제 발생 전 개입

코딩 어시스턴트

자연어 목표 → 코드 생성 → 테스트 작성/실행 → 디버깅 → 리팩토링까지 자율 수행
코드베이스 온보딩 시간: 기존 수 주 → 수 시간으로 단축
멀티 에이전트 개발: AutoGen/CrewAI로 전문 에이전트 팀(코딩, 리뷰, 테스트, 문서화)이 협업

데이터 파이프라인

ETL 워크플로우를 에이전트로 분해 (추출 → 변환 → 적재 → 검증)
스키마 변경 자동 감지 + 워크플로우 동적 조정

8. 블로그 작성 시 추천 구성

1. 도입: "왜 하나의 AI만으로는 부족한가?" — 문제 제기
2. 개념: 오케스트레이션이란? — 간결한 정의 + 비유(오케스트라)
3. 핵심 패턴: 가장 중요한 4-5가지 패턴 + 다이어그램
4. 통신 프로토콜: MCP & A2A — 비유로 이해하기 쉽게
5. 프레임워크: 비교표 + 선택 가이드
6. 설계 원칙: 실패 설계, 관측성, HITL
7. 실전 사례: CS / 코딩 / 데이터 파이프라인
8. 마무리: 2026년 트렌드 전망 + 시작하기

참고 자료 (리서치 소스)

IBM — AI Agent Orchestration
Microsoft — Multi-Agent Design Patterns
Google — A2A Protocol, ADK
Anthropic — Model Context Protocol (MCP)
LangChain / LangGraph 공식 문서
CrewAI / AutoGen / Semantic Kernel 문서
Medium / Dev.to / ByteByteGo 기사 다수
Klarna — AI Customer Support 사례

타워디펜스 - 맵 에디터 × Battle Simulator 통합 강화 플랜

blacknabis — Mon, 2 Mar 2026 22:05:04 +0900

시뮬레이터 결과화면

작성일: 2026-03-02
최종 보완: 2026-03-02 (라운드 3)
상태: 플랜 (코드 작업 전)
아키텍처: A안 — 흡수 통합 (BattleSimWindow를 MapEditorWindow에 통합)

1. 현재 상태

도구	상태	한계
MapEditorWindow	✅ 완료	경로/슬롯 편집만. 3개 모드(기본/경로/슬롯)
WaveBalanceWindow	✅ 완료	수치 편집만. 결과 예측 불가
BattleSimWindow	✅ 기본	독립 창. 타워 위치/경로 미반영, 전체 슬롯 동일 배치만 가능

문제: 세 도구가 분리되어 있어 "경로 수정 → 타워 배치 → 시뮬 → 결과 확인"이 창 3개를 오가며 진행됨.

2. 목표 아키텍처 (A안: 흡수 통합)

BattleSimWindow를 제거하고 MapEditorWindow에 모든 시뮬 기능을 통합한다.

MapEditorWindow (통합 모드)
├── [  기본 정보]     ← 기존: StageId, MapName, Bounds 등
├── [  경로 편집]     ← 기존: SceneView 핸들
├── [  슬롯 편집]     ← 기존: SceneView 핸들
├── [  타워 배치]     ← 신규: 슬롯별 TowerConfig+Level 지정
└── [⚔ 시뮬레이션]    ← 신규: 실행 버튼 + 결과 표시 + SceneView 오버레이

UI 레이아웃 (통합 후)

┌─ Map Editor ───────────────────────────────────────┐
│  MapConfig: [Stage_1_MapConfig ▼]                   │
│  WaveConfig: [Stage_1_WaveConfig ▼]  ← 신규 슬롯   │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │  [기본] [경로] [슬롯] [ 배치] [⚔시뮬]     │   │  ← 모드 탭 (5개)
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ─── 모드별 Inspector 패널 ───                      │
│  (경로 모드면 경로 리스트,                           │
│   배치 모드면 슬롯별 타워 드롭다운,                   │
│   시뮬 모드면 실행 버튼 + 결과 테이블)                │
│                                                     │
│  ─── SceneView (공유) ───                           │
│  경로+슬롯+타워+시뮬결과 오버레이가                    │
│  현재 모드에 따라 다르게 표시                          │
└─────────────────────────────────────────────────────┘

데이터 흐름

MapConfigData (SO)          WaveConfig (SO)
     │                          │
     ├── Paths[]                ├── Waves[]
     ├── TowerSlotPositions[]   ├── InitialGold/Lives
     └── GameplayBounds         └── StarThresholds
                 │                     │
                 └───────┬─────────────┘
                         ▼
            TowerPlacementPreset (SO 또는 세션 데이터)
               └── SlotPlacements[slotIdx → (TowerConfig, Level)]
                         │
                         ▼
               BattleSimEngine.Run(SimConfig)
                         │
                         ▼
               BattleSimResult
               ├── 승패/별등급/라이프/골드
               ├── WaveResult[]
               ├── TowerContribution[]
               └── EnemyDeathPositions[]
                         │
                         ▼
               ┌─ Inspector 패널 결과 표시
               └─ SceneView 오버레이 (SimOverlayRenderer)

3. 모드별 기능 상세

3.1 기존 모드 (변경 최소화)

모드	변경 사항
기본 정보	WaveConfig SO 슬롯 추가 (StageId 기반 자동 탐색)
경로 편집	변경 없음
슬롯 편집	변경 없음

3.2 타워 배치 모드 (신규)

Inspector 패널

  타워 배치
─────────────────────────────
빠른 전체 배치:
  타워: [Archer ▼]  레벨: [Lv.1 ▼]  [전체 적용]

슬롯별 개별 배치:
  Slot 0: [Archer ▼]  [Lv.2 ▼]    [✕]
  Slot 1: [Mage   ▼]  [Lv.1 ▼]    [✕]
  Slot 2: [없음       ]             [✕]
  Slot 3: [Barracks▼]  [Lv.1 ▼]    [✕]
  ...

[프리셋 저장]  [프리셋 불러오기]  [전체 초기화]

타워 배치 데이터 영속성

세션 내: 배치 데이터는 MapEditorWindow의 인스턴스 변수로 유지 (창 닫으면 초기화)
저장: "프리셋 저장" 시 TowerPlacementPreset SO로 디스크 저장
불러오기: SO에서 슬롯별 배치를 복원
⚠ 배치 데이터는 MapConfigData에 포함하지 않음 (맵 데이터 ≠ 밸런스 테스트 배치)

SceneView 표시

요소	시각
배치된 타워	타워 타입별 색상 원 (Archer=초록, Mage=파랑, Barracks=주황, Artillery=빨강) + "Lv.N" 라벨
사거리 원	해당 레벨의 실제 Range 값으로 반투명 원
빈 슬롯	회색 점선 원 + "Empty"
사각지대 경고	어느 타워 사거리에도 안 들어가는 경로 구간을 빨간색 굵은 선으로 표시

SceneView 조작

동작	방법
타워 배치	빈 슬롯 클릭 → 현재 선택 타워로 배치
타워 교체	배치된 슬롯 클릭 → 현재 선택 타워로 교체
타워 제거	배치된 슬롯 우클릭 → "타워 제거"
레벨 변경	배치된 슬롯 우클릭 → "Lv.1/2/3"

모든 SceneView 배치 조작에 Undo/Redo 지원 (Undo.RecordObject)

3.3 시뮬레이션 모드 (신규)

Inspector 패널

⚔ 전투 시뮬레이션
─────────────────────────────
[▶ 시뮬레이션 실행]       [  이전 결과와 비교]

━━━ 결과 요약 ━━━
✅ 승리 ★★★
남은 라이프: 18/20
총 골드: 3200  |  시뮬 시간: 45.3s

━━━ 웨이브별 상세 ━━━
 W1 | 일반 | 적12 | 처치12/돌파0 | 골드180 | 5.0~12.3s
 W2 | 일반 | 적15 | 처치13/돌파2 | 골드210 | 14.3~25.1s
 W3 | 보스 | 적 3 | 처치 3/돌파0 | 골드450 | 27.1~45.3s

━━━ 타워별 기여도 ━━━
 Slot0 Archer Lv2: 데미지 2400 (28%)  처치 8
 Slot1 Mage   Lv1: 데미지 1800 (21%)  처치 6
 Slot3 Barracks   : 블록 14회, 데미지 800 (9%)  처치 3
 ...

━━━ 골드 추이 차트 ━━━
 ▓▓▓▓▓▓▓▓
 ▓▓▓▓▓▓▓▓▓▓▓
 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓

[  로그 펼치기]

결과 비교 기능

"이전 결과와 비교" 버튼: 마지막 2회 시뮬 결과를 나란히 비교
비교 항목: 라이프 차이, 골드 차이, 웨이브별 돌파 수 증감
용도: 밸런스 조정 → 시뮬 → 수정 전후 비교 확인

SceneView 표시 (시뮬 후 오버레이)

오버레이	설명
사망 마커	적이 사망한 경로상 위치에 빨간 X 마커
돌파 마커	적이 도착점까지 뚫은 경우 경로 끝에 노란 마커 + 수량
타워 기여도	타워 원 크기가 기여도에 비례하여 변화
경로 열지도	경로 구간별 "적이 가장 오래 머문 구간" = 두꺼운 주황, 빠르게 지나간 구간 = 얇은 초록
⚠ 사각지대	타워 사거리에 안 걸리는 경로 구간 = 빨간 점선

에러 처리 / 검증

상황	동작
MapConfig 미연결	"MapConfigData를 연결하세요" 경고 + 실행 비활성화
WaveConfig 미연결	"WaveConfig를 연결하세요" 경고 + 실행 비활성화
타워 0개 배치	"타워 없이 시뮬합니다 (모든 적 돌파 예상)" 안내 + 실행 허용
경로 0개	"유효한 경로가 없습니다" 경고 + 실행 비활성화
경로 Waypoint < 2	"PathId=N 의 Waypoint가 부족합니다" 경고
스폰 엔트리의 PathId가 MapConfig에 없음	"PathId=N 이 맵에 존재하지 않습니다" 경고

4. 정밀 시뮬 엔진 개선

4.1 2D 위치 보간

// 경로 Waypoint 리스트 + 이동 거리 → 2D 좌표 계산
Vector3 GetPositionOnPath(List<Vector3> waypoints, float distanceTraveled)

4.2 거리 기반 사거리 판정

// 기존: 경로 진행도 기반 (부정확)
// 개선: 타워 좌표 ↔ 적 좌표 실제 거리
float dist = Vector3.Distance(tower.Position, enemy.CurrentPosition);
if (dist <= tower.Range) { /* 공격 */ }

4.3 타워 타겟팅 규칙

규칙	설명
기본 우선순위	사거리 내에서 경로 진행도가 가장 높은(=도착에 가장 가까운) 적 타겟
다중 경로	경로 무관하게 사거리 내 모든 적을 후보로 포함
타겟 제한	`TowerConfig.CanTarget(isFlying)` — Flying 적은 Ground 전용 타워에게 무시됨
Artillery AoE	주 타겟 주변 반경(ExplosionRadius) 내 적에게 감소된 데미지

4.4 Barracks 블록 규칙

float dist = Vector3.Distance(rallyPoint, enemy.CurrentPosition);
if (dist <= rallyRange && enemy.CanBeBlocked) { /* 블록 */ }

규칙	설명
블록 가능	`CanBeBlocked == true` (Flying, Boss 제외)
Rally 반경	`BarracksData.RallyRange > 0 ? RallyRange : tower.Range`
병사 리스폰	`BarracksData.SoldierRespawnSec` (기본 5초)
1 병사 = 1 적	한 병사가 한 적만 블록, 적이 죽으면 해제 후 새 적 탐색

4.5 사각지대 정적 분석 (시뮬 전 즉시)

경로의 모든 구간을 0.5 단위로 샘플링
→ 각 샘플 지점에서 모든 타워까지 거리 계산
→ min(거리) > max(Range) → 사각지대
→ SceneView에 빨간 경로 표시

4.6 적 사망 위치 / 타워별 기여도 추적

// BattleSimResult에 추가
public List<Vector3> EnemyDeathPositions;     // 사망 위치
public List<TowerContribution> TowerStats;    // 타워별 누적 데미지·처치수

public struct TowerContribution {
    public int SlotIndex;
    public string TowerName;    // 식별 편의
    public float TotalDamage;
    public int KillCount;
    public int BlockCount;      // Barracks
}

5. 프리셋 데이터 구조

[CreateAssetMenu(fileName = "TowerPreset", menuName = "Kingdom/Editor/Tower Placement Preset")]
public class TowerPlacementPreset : ScriptableObject
{
    public string PresetName;
    public int StageId;           // 어느 맵 기준인지
    public List<SlotPlacement> Placements;
}

[Serializable]
public struct SlotPlacement
{
    public int SlotIndex;
    public TowerConfig Tower;     // null이면 빈 슬롯
    public int Level;             // 0-indexed
}

저장 경로: Assets/Resources/Kingdom/Configs/TowerPresets/

6. 수정/생성 파일

파일	변경
`MapEditorWindow.cs`	WaveConfig 슬롯 추가, "타워 배치"/"시뮬" 모드 탭 추가, 결과 패널 통합
`BattleSimEngine.cs`	`GetPositionOnPath()`, 거리 기반 판정, 기여도 추적, 사망 위치 기록
`BattleSimResult.cs`	`TowerContribution`, `EnemyDeathPositions`, 사각지대 데이터 추가
`BattleSimWindow.cs`	삭제 (Phase A step 5에서 제거. 삭제 전 MapEditorWindow 시뮬 탭 완성 선행)
`TowerPlacementEditor.cs`	신규 — 슬롯별 타워 배치 SceneView 핸들
`SimOverlayRenderer.cs`	신규 — SceneView 시뮬 결과 오버레이 렌더링
`CoverageAnalyzer.cs`	신규 — 사각지대 정적 분석
`TowerPlacementPreset.cs`	신규 — 타워 배치 프리셋 SO
`WaveBalanceWindow.cs`	"시뮬 실행" 버튼 + 인라인 결과 추가

7. 구현 단계

Phase A: 정밀 시뮬 + 타워 개별 배치

BattleSimEngine — 2D 위치 보간 + 거리 기반 판정 + 기여도 추적
BattleSimResult — 기여도/사망 위치/비교 데이터 필드 추가
MapEditorWindow — "타워 배치" 모드 탭 추가 (Inspector만)
MapEditorWindow — "시뮬" 모드 탭 추가 (결과 테이블 + 차트 + 비교)
BattleSimWindow.cs 삭제 (step 4 완성 후)

완료 기준:

MapEditorWindow 단독으로 타워 배치 → 시뮬 실행 → 결과 확인 가능
경로 옆 배치 vs 먼 곳 배치 시 결과 차이 발생 확인
BattleSimWindow 메뉴 항목 제거 완료

Phase B: SceneView 통합

TowerPlacementEditor — 슬롯별 타워 SceneView 핸들 (클릭 배치/우클릭 메뉴)
CoverageAnalyzer — 사각지대 분석 + 경로 경고 SceneView 표시
SimOverlayRenderer — 시뮬 결과 SceneView 오버레이 (사망 마커, 기여도 원, 열지도)

완료 기준:

SceneView에서 타워 배치 조작 (클릭/우클릭) 정상 동작 + Undo/Redo
사각지대 빨간 경로 표시 정상 동작
시뮬 후 사망/돌파 마커가 SceneView에 표시

Phase C: 연동 + 프리셋

WaveBalanceWindow → 시뮬 연동 버튼 (현재 WaveConfig + 마지막 프리셋으로 시뮬)
TowerPlacementPreset — 프리셋 SO 저장/로드

완료 기준:

WaveBalanceWindow에서 수치 수정 → 시뮬 버튼 → 결과 인라인 표시
프리셋 저장/불러오기 정상 동작

Phase D: 영웅 + 고급 시각화

영웅 배치/시뮬 (HeroConfig 연동) — 고정 위치 타워로 추상화
경로 히트맵 (구간별 적 체류 시간 색상 표시)
타워 DPS 기여도 파이 차트

완료 기준:

영웅 포함 시뮬 실행 가능
히트맵 오버레이 SceneView 표시

8. 리스크 및 대응

리스크	대응
MapEditorWindow가 너무 커짐	모드별 로직을 별도 클래스(TowerPlacementEditor, SimOverlayRenderer)로 분리하여 MapEditorWindow는 모드 라우터 역할만
시뮬 실행 시간이 오래 걸리면 에디터 프리즈	최대 시뮬 시간 600초 제한, 진행바(EditorUtility.DisplayProgressBar) 표시. 50ms 이상 걸리면 경고 로그
SceneView 오버레이 성능 저하	오버레이 항목별 토글 제공, 대량 마커는 밀도 기반 클러스터링, Repaint 최소화
맵/웨이브 데이터 수정 후 시뮬 결과 stale	시뮬 결과 상단에 "⚠ 데이터가 수정되었습니다. 다시 실행하세요" 배너 표시. `_target`의 변경 감지(Hash 또는 dirty flag)
타워 배치가 맵 데이터와 혼동	배치는 MapConfigData에 저장하지 않음. 별도 SO(TowerPlacementPreset)으로 명확히 분리. Inspector에 안내 문구
다중 경로 시뮬 정확도	경로 간 적 분포가 실 플레이와 다를 수 있음. 시뮬 결과에 "추정치" 라벨 표시

9. 결정 필요 항목 (착수 전 확정)

타워 배치 프리셋을 SO로 저장할지, EditorPrefs(JSON)로 경량화할지
사각지대 분석을 "타워 배치" 모드에서 상시 표시할지, "시뮬" 모드 전용으로 할지
영웅 시뮬(Phase D)을 1차 범위에 포함할지, 완전 2차로 넘길지
시뮬 결과 비교를 최대 몇 회분까지 보관할지 (권장: 2회)

10. 기존 코드 이슈 (Phase A 선행 수정)

Codex 정적 리뷰(라운드 1)에서 발견된 기존 BattleSimEngine.cs / BattleSimWindow.cs 버그.
Phase A 정밀 시뮬 개선 시 함께 수정해야 한다.

#	심각도	파일	이슈	수정 방향
1	High	`BattleSimEngine`	타워 레벨 데이터 null/empty 시 NRE/IndexOutOfRange 발생 (Levels[lvl] 무조건 접근)	`tc.Levels == null \|\| lvl >= tc.Levels.Length` 가드 추가
2	High	`BattleSimEngine`	Barracks 타워의 `BarracksData` null 체크 없이 필드 접근 → NRE	`tower.Config.BarracksData != null` 가드 추가
3	Medium	`BattleSimEngine`	MaxSimTimeSec 초과로 루프 종료 시, 생존 적을 처치로 집계 (`EnemiesKilled = Spawned - Leaked`)	명시적으로 생존 적 수를 별도 추적, `EnemiesAlive` 필드 추가
4	Medium	`BattleSimWindow`	`RunSimulation()`에서 `_isRunning` 복구 없음 → Engine 예외 시 UI가 "실행 중" 고정	`try/finally` 패턴으로 `_isRunning = false` 보장
5	Medium	`BattleSimEngine`	Barracks `RallyRange` 계산하지만 미사용, 경로 진행도(0.15~0.9) 판정과 불일치	Phase A에서 2D 좌표 기반 판정으로 전면 교체 시 해소
6	High	`BattleSimEngine`	`HandleAoeDamage()`에서 HP를 깎지만 `KillEnemy`를 호출하지 않음 → HP≤0 적이 살아서 이동/누수 가능	AoE 데미지 후 `HP <= 0` 사망 처리 추가
7	Critical	`BattleSimEngine`	`MaxSimTimeSec` 타임아웃 시 `IsCleared = lives > 0`으로 판정 → 적/웨이브 잔존해도 승리 처리	타임아웃 시 `IsCleared = false` 또는 별도 `TimedOut` 상태 추가
8	Medium	`BattleSimEngine`	`WaveConfig.Waves`, `MapConfig.TowerSlotPositions` null 체크 없이 접근 → NRE 가능	시뮬 시작 전 입력 유효성 검증 단계(ValidateInputs) 추가

11. 시뮬 한계 및 면책 (Limitations)

이 시뮬레이터는 수치 기반 근사치이며, 실 플레이와 100% 동일하지 않다.
결과는 밸런스 방향성 확인용이며, 최종 검증은 실 플레이로 수행한다.

괴리 영역	설명	영향도
경제 시뮬 미포함	실 플레이에서는 웨이브 중 골드로 타워 추가 구매/업그레이드가 가능하지만, 시뮬은 "사전 배치 고정". 중반 이후 타워 업그레이드 효과를 반영하지 못함	중
타워 타겟팅 AI	실 게임의 타겟팅 로직(최근접, 최강, 최약 등)과 시뮬의 "경로 진행도 최고" 규칙이 다를 수 있음	중
투사체 이동 시간	실 게임에서 화살/마법 투사체는 이동 시간이 있으나, 시뮬은 즉시 적중	낮
Barracks 교전 동선	실 게임에서 병사와 적의 이동/교전 위치가 세밀하지만, 시뮬은 Rally 반경 내 즉시 블록	중
곡선 경로	현재 직선 Waypoint Lerp 보간만 지원. 곡선(Catmull-Rom 등)은 미지원	낮 (현 프로젝트 경로는 직선 Waypoint 기반)
영웅/스킬/버프	Phase D 이전에는 미반영	중

경제 시뮬 고려 (향후 확장)

현재: 모든 타워가 게임 시작 전에 배치된 상태로 시뮬.
한계: 초반에 Lv.1 타워 → 중반 골드로 Lv.3 업그레이드 같은 실 플레이 패턴을 반영 못함.

보완 방안 (Phase E 이후):

시뮬 옵션: [x] 경제 시뮬 활성화

초기 골드: 500
자동 업그레이드 정책:
  - 골드가 업그레이드 비용 이상이면 → 가장 DPS 기여도 높은 타워를 우선 업그레이드
  - 또는: 수동 "웨이브 N 후 슬롯 M을 Lv.2로 업그레이드" 스크립트 입력

→ 현재 Phase A~D에서는 경제 시뮬 미포함으로 진행하되, 결과에 "경제 시뮬 미반영" 라벨을 표시한다.

곡선 경로 판단

현재 프로젝트의 PathData.Waypoints는 직선 연결 구간
킹덤 러시 원작도 Waypoint 기반 직선/꺾임 경로 사용 (실제 곡선 스플라인 아님)
결론: 현재 직선 Lerp 보간으로 충분. Catmull-Rom 등은 불필요

12. 프리셋 호환성 규칙

맵 수정으로 타워 슬롯 수가 변경될 때 기존 프리셋이 깨지는 문제 대응:

상황	처리
슬롯 추가 (3→5)	프리셋의 기존 슬롯은 유지, 신규 슬롯은 "빈 슬롯"으로 자동 채움
슬롯 삭제 (5→3)	프리셋에서 삭제된 SlotIndex는 무시하고 경고 표시: "⚠ Slot 3,4는 맵에 존재하지 않아 무시됨"
슬롯 위치 이동	SlotIndex 기반이므로 위치만 바뀌면 자동 대응. 인덱스가 바뀌면 경고
StageId 불일치	"⚠ 이 프리셋은 Stage_2용입니다. 현재 맵은 Stage_1입니다." 경고 + 적용 허용

→ 프리셋 로드 시 SlotIndex 범위 검증 + StageId 일치 확인을 수행한다.

[Unity] 타워디펜스 맵 & 웨이브 에디터

blacknabis — Mon, 2 Mar 2026 03:00:43 +0900

타워디펜스 게임을 개발하다 보면 맵 데이터를 관리하는 방법이 항상 문제다.

처음에는 GameBattlefield.prefab 하위에 PathRoot/Path0/Waypoint_0, PathRoot/Path0/Waypoint_1... 식으로 씬 계층(Transform 트리)에 직접 경로를 박아넣었다. 타워 슬롯도 마찬가지로 TowerRoot 하위에 빈 게임오브젝트를 하나씩 배치했다.

이 방법은 처음엔 빠르지만, 금방 한계가 온다.

새 맵을 추가하려면 프리팹을 복사하고 Transform을 일일이 수정해야 한다
웨이브 밸런스를 조정하려면 WaveConfig 인스펙터를 열고 리스트를 손으로 뒤져야 한다
전체 밸런스가 어떤지 한눈에 보이지 않는다
기획자가 직접 조작하기 어렵다 (개발자가 옆에 있어야 한다)

맵이 1개일 때는 그냥 참을 수 있다. 하지만 Stage 2, 3...을 추가하고 싶어지는 순간, 이 구조는 관리 비용이 폭증한다.

그래서 에디터 도구를 직접 만들기로 했다.

목표

씬 뷰에서 클릭 몇 번으로 경로와 타워 슬롯을 편집할 수 있을 것
맵 데이터를 ScriptableObject(SO) 로 분리해서 프리팹과 독립적으로 관리할 것
웨이브 구성과 밸런스 지표를 한 화면에서 볼 수 있을 것
새 맵 추가 시 프리팹을 복사하지 않고 SO만 만들면 게임이 돌아갈 것

구성 요소

총 5개의 에디터 파일을 만들었다.

1. MapConfigData (ScriptableObject)

맵의 모든 정적 데이터를 담는 SO.

public class MapConfigData : ScriptableObject
{
    public int StageId;
    public List<PathData> Paths;              // 경로 목록 (웨이포인트 리스트)
    public List<Vector3> TowerSlotPositions;  // 타워 설치 가능 위치
    public string BackgroundSpritePath;       // Resources 상대 경로
}

이 파일 하나만 있으면 해당 스테이지를 런타임에서 완전히 복원할 수 있다.

저장 위치: Assets/Resources/Kingdom/Configs/Maps/Stage_1_MapConfig.asset

2. MapEditorWindow — 맵 편집 창

Unity 상단 메뉴 Tools > Kingdom > Map > Map Editor로 열린다.

주요 기능:

SO 에셋 드래그 앤 드롭으로 불러오기 / 새로 만들기
경로(Path) 추가/삭제, 경로별 웨이포인트 편집
타워 슬롯 위치 편집
배경 이미지 경로 설정 (스프라이트 드래그하면 Resources 경로 자동 추출)
창 상단에 유효성 검사 배너 표시 (오류 = 빨강, 경고 = 노랑)

3. PathHandleEditor — 씬 뷰 핸들 편집기

MapEditorWindow에서 경로 편집 모드를 켜면 씬 뷰에서 직접 조작할 수 있다.

동작	방법
웨이포인트 이동	씬 뷰 핸들 드래그
웨이포인트 추가	Shift + 클릭
웨이포인트 삭제/삽입	우클릭 컨텍스트 메뉴

경로마다 색이 다르게 표시된다: Path0=초록, Path1=파랑, Path2=주황...
시작점은 초록 구, 도착점은 빨간 구로 구분된다.

핵심 구현 포인트:
SceneView.duringSceneGui 이벤트를 구독해서 씬 뷰에 직접 그린다. Handles.FreeMoveHandle()로 드래그 가능한 핸들을 생성하고, Undo.RecordObject()로 실행 취소를 지원한다.

private void OnSceneGui(SceneView sv)
{
    if (_target == null) return;

    for (int i = 0; i < _target.Paths.Count; i++)
    {
        PathData path = _target.Paths[i];
        DrawPathHandles(path, _pathColors[i % _pathColors.Length]);
    }
}

4. TowerSlotHandleEditor — 타워 슬롯 핸들 편집기

타워 슬롯 편집 모드에서 동작한다.

Shift + 클릭 → 슬롯 추가
노란 사각형 핸들 드래그 → 이동
우클릭 → 삭제
GameplayBounds 바깥에 있는 슬롯은 빨간색으로 경고 표시
기본 사거리 가이드 원 표시 (Archer 기준 반경 4.0f)

5. WaveBalanceWindow — 웨이브 밸런스 편집 창

Tools > Kingdom > Map > Wave Balance Editor

창 상단 밸런스 지표 패널:

총 웨이브: 5     총 적 수: 87
총 HP: 18,400    총 골드: 1,240

이 숫자들이 실시간으로 자동 계산된다. 스폰 수를 늘리면 바로 반영되니 밸런스 조정이 직관적이다.

웨이브 헤더 색상:
일반 웨이브 = 파랑, 보스 웨이브 = 붉은색으로 즉시 구분된다.

스폰 엔트리 편집:
EnemyConfig 에셋을 드래그하면 자동으로 HP, 골드 수치가 계산에 반영된다.
PathId를 드롭다운으로 선택할 수 있다 (MapConfig가 연결되어 있을 때).

가장 까다로웠던 부분

SceneView에 배경 이미지 미리보기

맵 에디터에서 배경 스프라이트를 설정하면 씬 뷰에 실시간으로 표시되게 했다.

문제는 씬 뷰는 EditorWindow GUI와 좌표계가 다르다는 점이다.
월드 좌표 → GUI 좌표 변환이 필요하다.

private void OnSceneGui(SceneView sv)
{
    if (string.IsNullOrWhiteSpace(_target.BackgroundSpritePath)) return;
    Sprite sprite = Resources.Load<Sprite>(_target.BackgroundSpritePath);
    if (sprite == null) return;

    Handles.BeginGUI();

    Rect bounds = _target.GameplayBounds;
    Vector2 guiMin = HandleUtility.WorldToGUIPoint(
        new Vector3(bounds.xMin, bounds.yMin, 0));
    Vector2 guiMax = HandleUtility.WorldToGUIPoint(
        new Vector3(bounds.xMax, bounds.yMax, 0));

    Rect guiRect = new Rect(
        Mathf.Min(guiMin.x, guiMax.x),
        Mathf.Min(guiMin.y, guiMax.y),
        Mathf.Abs(guiMax.x - guiMin.x),
        Mathf.Abs(guiMax.y - guiMin.y));

    // Atlas 스프라이트 대응: 텍스처 내 UV 좌표 계산
    Rect texCoords = new Rect(
        sprite.rect.x / sprite.texture.width,
        sprite.rect.y / sprite.texture.height,
        sprite.rect.width / sprite.texture.width,
        sprite.rect.height / sprite.texture.height);

    GUI.color = new Color(1f, 1f, 1f, 0.85f);
    GUI.DrawTextureWithTexCoords(guiRect, sprite.texture, texCoords);
    GUI.color = Color.white;

    Handles.EndGUI();
}

GUI.DrawTexture()가 아니라 GUI.DrawTextureWithTexCoords()를 써야 atlas 스프라이트에서도 올바른 영역이 잘려서 표시된다.

데이터 소스 이원화 문제

초기에는 맵 데이터가 두 곳에 있었다.

프리팹 Transform 계층 (기존)
MapConfigData SO (신규)

런타임 코드가 SO를 먼저 보고, 없으면 프리팹 계층을 폴백으로 읽는 이중 구조였는데, 이게 오히려 혼란을 만들었다.

결론: 프리팹의 PathRoot, TowerRoot 하위 오브젝트를 전부 삭제하고, SO가 없으면 에러 로그 방식으로 단순화했다.

// 이제 폴백 없음
MapConfigData mapConfig = ConfigResourcePaths.LoadMapConfigByStageId(stageId);
if (mapConfig == null || mapConfig.Paths.Count == 0)
{
    Debug.LogError($"[GameScene] Stage {stageId} MapConfigData를 찾을 수 없습니다.");
    return;
}
_pathManager.SetPaths(mapConfig.Paths);

결과

새 맵을 추가하는 절차:

1. Map Editor → "새로 만들기"
2. 씬 뷰에서 경로 웨이포인트 배치 (Shift+클릭)
3. 씬 뷰에서 타워 슬롯 배치 (Shift+클릭)
4. Wave Balance Editor에서 웨이브 편집
5. 저장 → 끝

프리팹 복사 없음. 씬 복제 없음. SO 하나가 맵의 전부다.

맵에디터

마무리

Unity 에디터 확장은 EditorWindow, Handles, SceneView.duringSceneGui 세 가지를 조합하면 대부분 원하는 걸 만들 수 있다. 처음엔 좌표계 변환(월드↔GUI)이 헷갈리지만, HandleUtility.WorldToGUIPoint()와 GUIUtility.GUIToScreenPoint()의 역할 차이를 구분하면 감이 잡힌다.

비슷한 구조의 레벨 에디터를 만들 계획이 있다면 참고가 되면 좋겠다.

이 글이 도움이 됐다면 댓글로 알려주세요.

타워 디펜스 만들기 - 맵 이미지 프롬프트

blacknabis — Sun, 1 Mar 2026 17:19:22 +0900

기존에 사용했던 맵

이제 어느정도 작업이 되었기 때문에 스테이지 제작 단계에 들어갈 필요성을 느꼈습니다.

맵은 오브젝트가 없는 배경이미지와 오브젝트들을 타일형태로 추가해서 aseprite를 사용하여 배치하던가 별도의 툴을 만들어서 배치 해볼까 고민중입니다.

Google Flow를 이용하여 만든 맵 배경이미지들

맵 배치에 들어갈 오브젝트들

그리고 AI프롬프트입니다.

킹덤러쉬 맵 배경 이미지 AI 프롬프트 가이드

이 문서는 이미지 생성 AI(Midjourney, Stable Diffusion 등)를 사용하여 킹덤러쉬(Kingdom Rush) 스타일의 타워 디펜스 맵 배경(아트워크)을 생성할 때 사용하는 프롬프트 지침입니다.

맵 디자인 핵심 가이드라인

비주얼 & 아트 스타일 (Visual & Art Style)
- 스타일: 2D 탑다운 아이소메트릭(Top-down Isometric), 카툰 렌더링(Cartoony), 수작업 느낌(Hand-drawn style).
- 선(Line): 기계적인 타일이나 격자(Grid) 형태를 피하고, 부드러운 외곽선(Smooth outlines)과 깔끔한 벡터(Vector graphic) 느낌 사용.
- 색감: 화사하고 다채로운(Colorful, Vibrant) 색깔.
구도 및 레벨 구조 (Composition & Level Design)
- 길(Path): 유닛들이 이동하는 넓고 굽은 흙길(Winding dirt paths)과 자연스러운 곡선.
- 지형 병목: 길이 교차하는 지점(Crossroads)이나 자연스러운 병목 현상(Choke points)이 나타나도록 구성.
배경 요소 (Background & Environment)
- 배제 요소: (중요) 게임 내 타워가 배치될 공간이나 유닛의 스폰 위치 등은 인게임에서 처리할 예정이므로 이미지 생성 단계에서는 건설 슬롯용 원형 마커, UI 요소, 스폰 포인트 마커 등을 철저히 배제합니다.
- 순수 배경: 유닛의 가시성을 방해하지 않는 깔끔한 환경(Clean UI-friendly background).

상황별 통합 AI 프롬프트 (그대로 복사해서 사용)

맵의 '길(Path)' 구조와 '테마(Theme)'가 모두 결합된 완성형 프롬프트입니다. 원하는 형태의 프롬프트를 복사하여 바로 사용하세요.

1. 기본 단일 경로 (Single Path) - 평화로운 숲(들판) 테마

A 2D top-down isometric view of a tower defense game map background, cartoony and hand-drawn style, clean vector graphic art, colorful and vibrant with smooth outlines. A SINGLE, continuous, dynamic, winding dirt path entering from one edge of the canvas and exiting from another, no rigid grids. Do NOT include any trees, forests, buildings, houses, farms, circular building slots, spawn points, or UI elements; keep it strictly as an empty natural terrain background. Natural choke points along the path. Surrounding environment filled with wide open green grassy plains, small wooden bridges, rocks and small bushes, clean UI-friendly background, Kingdom Rush art style --ar 16:9 --no UI, building slots, spawn points, markers, circles, grids, houses, buildings, farms, fences, trees, forests, woods, multiple paths, branching paths, intersections, crossroads, forks, shadows, drop shadows

2. Y자형 분기/합류 (Split & Converging Paths) - 설산 테마

A 2D top-down isometric view of a tower defense game map background, cartoony and hand-drawn style, clean vector graphic art, colorful and vibrant with smooth outlines. Dirt paths that split into two separate routes early on and converge back into a single path near the end, no rigid grids. Do NOT include any trees, forests, buildings, houses, farms, circular building slots, spawn points, or UI elements; keep it strictly as an empty natural terrain background. A strong natural crossroads choke point where paths meet. Surrounding environment filled with a snowy mountain pass, frozen rivers, and icy caves, cold blue and white tones, clean UI-friendly background, Kingdom Rush art style --ar 16:9 --no UI, building slots, spawn points, markers, circles, grids, houses, buildings, farms, fences, trees, forests, pine trees, shadows, drop shadows

3. 다중 입구 및 독립된 경로 (Multiple Entry Points & Independent Paths) - 화산/황무지 테마

A 2D top-down isometric view of a tower defense game map background, cartoony and hand-drawn style, clean vector graphic art, colorful and vibrant with smooth outlines. Multiple independent dirt paths starting from different edge entry points and leading to completely different areas or converging late, no rigid grids. Do NOT include any trees, forests, buildings, houses, farms, circular building slots, spawn points, or UI elements; keep it strictly as an empty natural terrain background. Surrounding environment filled with a volcanic wasteland, cracked dark earth, lava streams, and craters, dark red and grey tones, ominous atmosphere, clean UI-friendly background, Kingdom Rush art style --ar 16:9 --no UI, building slots, spawn points, markers, circles, grids, houses, buildings, farms, fences, trees, forests, dead trees, shadows, drop shadows

4. 우회로 및 던전 터널 포함 (Paths with Hidden Tunnels/Bypass) - 해안/항구 테마

A 2D top-down isometric view of a tower defense game map background, cartoony and hand-drawn style, clean vector graphic art, colorful and vibrant with smooth outlines. Dynamic winding dirt paths where a section of the path visually dips underground into a hidden tunnel or cave, emerging further down the route, no rigid grids. Do NOT include any trees, forests, buildings, houses, farms, circular building slots, spawn points, or UI elements; keep it strictly as an empty natural terrain background. Surrounding environment filled with tropical coastal beaches, wooden docks, abandoned pirate ships, and clear blue water, clean UI-friendly background, Kingdom Rush art style --ar 16:9 --no UI, building slots, spawn points, markers, circles, grids, houses, buildings, farms, fences, trees, palm trees, forests, shadows, drop shadows

️ 맵 오브젝트(Props) 개별 생성 프롬프트 (건물, 바위, 나무 등)

위의 배경 맵 생성 프롬프트와 조합하여 에디터에서 자유롭게 배치할 개별 맵 오브젝트 장식물(Props)을 생성하는 방법입니다.

배경을 투명화(누끼)하기 쉽도록 순백색 배경(Solid white background)에 오브젝트만 생성하는 것이 핵심입니다. 다양한 오브젝트를 하나의 시트(Sprite Sheet) 형태로 출력해서 잘라서 쓰는 것을 추천합니다.

특징 및 가이드

시점 일치: 배경 맵과 시점을 동일하게 맞추기 위해 2D top-down isometric view 키워드는 유지합니다.
분리 용이성: isolated on a solid white background 키워드 설정
그림자 제거: 그림자가 겹치는 문제를 막고 투명화(누끼) 작업 시 깔끔하게 잘라내기 위해 그림자를 완전히 제거합니다. 유니티 엔진 내에서 별도의 방식으로 그림자를 처리하는 것이 효율적입니다.

프롬프트: 다양한 마을 건물/집 (House & Buildings)

A collection of separated 2D game props, top-down isometric view. [테마 입력: e.g., Medieval fantasy small wooden houses, farmers thatched cottages, small barns]. Cartoony and hand-drawn style, clean vector graphic art, colorful and vibrant with smooth outlines. Isolated on a solid pure white background. Arranged neatly as a sprite sheet, no overlapping, Kingdom Rush art style --ar 16:9 --no shadows, drop shadows, background, environment, terrain, paths

프롬프트: 자연물 장식 (Trees, Rocks, Bushes)

A collection of separated 2D game props, top-down isometric view. [테마 입력: e.g., Pine trees of various sizes, large mossy boulders, berry bushes, small wooden fences]. Cartoony and hand-drawn style, clean vector graphic art, colorful and vibrant with smooth outlines. Isolated on a solid pure white background. Arranged neatly as a sprite sheet, no overlapping, Kingdom Rush art style --ar 16:9 --no shadows, drop shadows, background, environment, terrain, paths

킹덤러쉬 방식 강력 추천 가이드: "통짜 배경 + 개별 프롭 배치" (Hybrid Method)

킹덤러쉬처럼 자연스럽고 역동적인 길을 표현하려면, 조각난 타일맵(Tilemap)이나 마름모 형태의 깍두기 아이소메트릭 블록 방식을 사용하는 것은 지양해야 합니다. 타일 방식으로 길을 이으면 특유의 둥근 느낌이 죽고 뚝뚝 끊기며 반복적인 패턴이 보이기 때문입니다.

가장 빠르고 퀄리티 높은 레벨 디자인 방법은 다음과 같습니다:

지형/길 생성: 1~4번 프롬프트를 사용해 나무나 건물이 없는 "굽은 길이 포함된 맵 전체 배경 1장(통짜)"을 생성합니다.
사전 보정 (Optional): 생성된 배경 이미지에서 길과 너무 가깝거나 타워 슬롯을 가리는 방해물(바위 등)이 섞여나왔다면, 포토샵 도장이나 AI 지우개 기능으로 살짝 지워 잔디밭으로 덮습니다.
개별 오브젝트(Props) 준비: 위의 건물 및 자연물 장식 프롬프트로 유닛을 가리거나 배치될 집, 큰 나무, 바위 세트를 흰 배경으로 뽑고 누끼를 따서 스프라이트로 만듭니다.
유니티에서 조립: 유니티 씬에 "통짜 배경 이미지" 1장을 맵 베이스로 깔고, 그 위에 "개별 오브젝트(Props)"들을 얹습니다.
- 적들이 이 오브젝트 뒤로 걸어갈 때 완벽한 뎁스(Z-Sorting) 효과를 줄 수 있습니다.
- 타워 건설 슬롯 공간을 철저하게 통제할 수 있습니다.
- 다채로운 에셋 재활용이 가능해집니다.

타워디펜스 개발일지 2026_03_01

blacknabis — Sun, 1 Mar 2026 03:16:23 +0900

DevLog_2026_03_01

오늘의 목표

웨이브/경로 연계 이슈 해결
결과 판정(UI 문구) 충돌 해결
null 체크 스타일을 IsNull()/IsNotNull()로 통일
진행 문서 최신화

진행한 작업

1) 웨이브 로딩/경로 연계 확인

게임씬 단독 실행 시 기본 웨이브 로드 경로를 확인했다.
현재 기본은 Resources/Kingdom/Configs/Waves/Stage_1_WaveConfig 기준으로 동작한다.
Path0, Path1 구조와 GameBattlefield 경로 파싱 기준을 점검했다.

2) WaveIndex 중복 데이터 처리 버그 수정

기존 WaveManager가 WaveData.WaveIndex를 무시하고 Waves 리스트 순번으로만 실행하던 문제를 확인했다.
WaveIndex 기준으로 논리 웨이브를 런타임 병합하도록 수정했다.
같은 WaveIndex=1에 PathId=0/1이 있어도 동일 웨이브에서 스폰되도록 보정했다.
GameScene의 총 웨이브 수도 Waves.Count가 아니라 논리 웨이브 수 기준으로 계산하도록 수정했다.

3) PathPoints 레거시 제거 반영

전장 경로 주입을 GameBattlefield.GetPathPointsById() + PathManager.SetPaths(...) 기준으로 유지하도록 정리했다.
PathPoints 레거시 사용/폴백 의존 제거 방향을 코드/작업 흐름에 반영했다.

4) 결과 판정 문구 충돌 이슈 보정

방어선 붕괴 상황에서 Victory 문구가 함께 보이던 케이스를 분기 로직으로 보정했다.
패배 시 Defeat 문구만 보이도록 정리했다.

5) null 체크 규칙 일괄 정리

요청 기준에 맞춰 Kingdom/Common 코드의 null 체크를 IsNull()/IsNotNull() 스타일로 통일 적용했다.
변환 과정에서 발생한 컴파일 에러(문자열 깨짐/nullable bool 식)들을 개별 복구했다.
대표 복구 파일: SkillTreeUI, WorldMapView, AISpriteProcessor, BossEventSystem, HeroSelectionUI.

6) 문서 정리

문서/진행/task.md를 최신 작업 기준으로 재정리했다.
진행 폴더 운영 기준 문서 문서/진행/README.md를 추가했다.
사용자 확인 완료(1/2/3) 항목을 task 문서에 체크 반영했다.

검증

dotnet build Assembly-CSharp.csproj 기준 컴파일 에러 0 확인.
플레이 검증(사용자 확인 완료):
1. Stage 1 Wave 1에서 Path0/Path1 동작 확인
2. 웨이브 전이/결과 상태 전이 확인
3. 패배 시 Defeat 표기 정상 확인

오늘의 결과

멀티 경로 웨이브 스폰이 데이터 의도대로 동작하도록 안정화 완료.
결과 UI 판정 충돌 이슈 해결.
null 체크 스타일 통일 적용 및 컴파일 안정화 완료.
진행 문서 최신 상태 유지.

전투방식 단순화 개발기록 정리본 (2026-02-28)

blacknabis — Sat, 28 Feb 2026 04:32:11 +0900

전투방식 단순화 개발기록 정리본 (2026-02-28)

1. 목적과 범위

전투 규칙을 단순화한다.
- 범위 안에 적이 있으면 공격
- 범위 밖이면 이동
대상 유닛: Enemy, Hero, Barracks Soldier
현재 단계: 스테이지 기본 테스트 기준 (밸런스 조정 제외)

2. 현재 최종 규칙

공격 데미지는 공격 애니메이션 종료 시점에 적용된다.
공격 중에는 이동하지 않는다.
공격 상태에서 다음 상태(추적/이동/유지)로 전환은 공격 애니메이션 종료 후에만 가능하다.
유닛 분리(밀어내기)는 같은 팀끼리만 적용한다.
- Enemy ↔ Enemy 적용
- Ally(Hero/Soldier) ↔ Ally(Hero/Soldier) 적용
- Enemy ↔ Ally 미적용

3. 변경 이력 요약

3.1 기반 리팩토링

BaseUnit 공통 전투 루프/헬퍼를 중심으로 구조 정리
이동 stop distance, 팀 분리 보정 유틸 도입

3.2 간격/겹침 보정

유닛 간격 상향(2배 포함)
적대 팀 간 간격 처리 공통화(이후 동일 팀 전용으로 최종 조정)

3.3 전투 안정화

제자리 공격 고정
공격 불가 시 이동 전환
적 타겟 획득/유지 범위 보정
전투 거리 판정 2D(XY) 통일

3.4 적 공격 이슈 추적

EnemyTrace/EnemyAttack 로그 보강
적 공격 애니메이션 상태 유지 보정

3.5 공격 타이밍 규칙 적용

Enemy/Hero/Soldier 모두 공격 시작 -> 애니메이션 종료 -> 데미지 확정 구조로 변경
공격 대기 상태(_isAttackPending) 중 이동 차단

3.6 분리 정책 최종화

BaseUnit 분리 로직에서 적대 팀 push 제거
같은 팀 그룹에만 분리 적용

4. 핵심 수정 파일

Assets/Scripts/Kingdom/Game/BaseUnit.cs
Assets/Scripts/Kingdom/Game/EnemyRuntime.cs
Assets/Scripts/Kingdom/Game/HeroController.cs
Assets/Scripts/Kingdom/Game/BarracksSoldierRuntime.cs
Assets/Scripts/Kingdom/Game/TowerManager.cs
Assets/Scripts/Kingdom/Game/Data/EnemyConfig.cs
Assets/Scripts/Kingdom/Game/Data/HeroConfig.cs
Assets/Scripts/Kingdom/Game/Data/TowerConfig.cs
Assets/Resources/Prefabs/Game/GameBattlefield.prefab

5. 검증 상태

dotnet build Assembly-CSharp.csproj -nologo 오류 0
빌드 경고는 기존 항목(MSB3277, CS0649) 유지

6. 현재 남은 이슈

일부 상황에서 공격 애니메이션 체감 타이밍이 의도보다 짧거나 어색할 수 있음
다음 점검 포인트:
- 유닛별 공격 클립 길이 vs _attackVisualHoldLeft 정합
- 공격 종료 직후 상태 전환(Idle/Move) 체감

7. 원본 기록 안내

상세 원본: 문서/진행/전투방식_단순화_개발기록_2026_02_27.md
본 문서는 회의/리뷰용 요약 정리본이다.

8. 최종 점검 체크리스트

공격 중 이동 금지: 공격 애니메이션 재생 중 위치가 고정되는지 확인
타격 시점: 데미지 숫자/HP 감소가 공격 애니메이션 종료 시점과 일치하는지 확인
상태 전환: 공격 종료 전 이동 상태로 튀지 않는지 확인
분리 정책: 같은 팀끼리만 분리되고, 적/아군 간에는 밀어내기가 없는지 확인

점검 결과

확인 일자: 2026-02-28
상태: 사용자 실플레이 확인 완료

전투방식 단순화 개발기록 (2026-02-27)

blacknabis — Sat, 28 Feb 2026 04:31:43 +0900

전투방식 단순화 개발기록 (2026-02-27)

정리본: 문서/진행/전투방식_단순화_개발기록_정리본_2026_02_28.md

1) 작업 목적

전투/이동 중 유닛이 동일 좌표에 겹치는 현상 제거
기존 단순 전투 규칙(범위 내 공격, 범위 밖 이동) 유지

2) 반영 내용

공통(BaseUnit)

팀 내부 유닛 간 분리 보정 유틸 추가
- ApplyTeamSeparation(float deltaTime, float separationRadius, float pushSpeed)
- 동일 좌표(거리 0)에서도 분리되도록 fallback 방향 처리 포함
정지 거리 기반 이동 헬퍼 추가
- MoveTowardsWithStopDistance(Vector3 from, Vector3 target, float maxDistanceDelta, float stopDistance)

EnemyRuntime

타깃 근접 시 중심점까지 겹치지 않도록 정지 거리 적용
전투 중/이동 중 팀 분리 보정 적용

HeroController

적 추적 이동 시 정지 거리 적용(과도한 겹침 방지)
전투 중/이동 중 팀 분리 보정 적용

BarracksSoldierRuntime

적 추적 이동 시 정지 거리 적용
전투 중/이동 중 팀 분리 보정 적용

3) 수정 파일

Assets/Scripts/Kingdom/Game/BaseUnit.cs
Assets/Scripts/Kingdom/Game/EnemyRuntime.cs
Assets/Scripts/Kingdom/Game/HeroController.cs
Assets/Scripts/Kingdom/Game/BarracksSoldierRuntime.cs
문서/진행/전투방식_단순화_원샷리팩토링_플랜_2026_02_27.md (선행 작업 섹션 추가)

4) 검증 결과

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
Unity Play Mode 콘솔:
- Error 0
- Warning 0

5) 비고

밸런스 수치(데미지/쿨타임)는 변경하지 않음
분리 보정은 팀 내부 기준으로 우선 적용

6) 추가 작업 (다음 단계 반영)

EnemyRuntime 레거시 모션 상태 제거

EnemyMotionState에서 Blocked, Engaged 제거
애니메이션 프레임 선택 로직 단순화
- 이동: Moving
- 공격: Attacking
- 사망: Dead
애니메이터 파라미터 매핑은 유지
- Walk=1, Attack=2, Die=3

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
Unity Play Mode 콘솔:
- Error 0
- Warning 0

9) 추가 작업 (겹침 스모크 로그 상세화)

회귀 로그 보강

RunBarracksMeleeSmokeRegressionAsync()에 겹침 최초 샘플 기록 추가
- firstOverlapAtSec
- firstOverlapPairCount
- firstOverlapMinPairDistance
CaptureOverlapSample(...) 로컬 함수로 최초 겹침 시점/지표를 한 번만 캡처
겹침 실패 시 즉시 원인 로그 출력
- maxPairs, firstAt, firstPairs, firstMinDist
종료 요약 로그에 최초 겹침 정보 포함

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
Unity Play Mode 콘솔:
- Error 0
- Warning 0

8) 추가 작업 (Separation 파라미터 설정 외부화)

데이터 스키마 확장

EnemyConfig 추가 필드
- SeparationRadius
- SeparationPushSpeed
- ChaseStopDistance
HeroConfig 추가 필드
- SeparationRadius
- SeparationPushSpeed
- ChaseStopDistance
TowerConfig.BarracksData 추가 필드
- SoldierSeparationRadius
- SoldierSeparationPushSpeed
- SoldierChaseStopDistance

런타임 반영

EnemyRuntime는 separation/stop 거리 값을 EnemyConfig에서 우선 사용, 미설정 시 기본값 fallback
HeroController는 separation/stop 거리 값을 HeroConfig에서 우선 사용, 미설정 시 기본값 fallback
BarracksSoldierRuntime는 UpdateMovementSettings(...)로 이동 보정 파라미터를 주입받도록 확장
TowerManager에서 병사 생성/스탯 갱신 시 병사 이동 보정 파라미터를 설정값으로 주입
TowerManager 정규화 단계에서 배럭 이동 보정 값 미설정 시 기본값 채움

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
Unity Play Mode 콘솔:
- Error 0
- Warning 0

7) 추가 작업 (겹침 방지 스모크 assert 연동)

TowerManager 디버그 지표 확장

BarracksDebugInfo에 겹침 검증용 필드 추가
- OverlapPairCount: 일정 임계거리 이하로 포개진 병사 페어 수
- MinAlivePairDistance: 생존 병사 페어 최소 거리 (페어 없으면 -1)
배럭 디버그 계산 시 생존 병사 쌍 거리 기반으로 값 집계

KingdomAppManager 스모크 회귀 조건 강화

RunBarracksMeleeSmokeRegressionAsync()에 겹침 조건 추가
- 테스트 중 maxOverlapPairCount 추적
- 종료 판정 시 maxOverlapPairCount <= 0일 때만 성공 카운트
결과 로그에 maxOverlapPairs, minPairDist 출력 추가

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
Unity Play Mode 콘솔:
- Error 0
- Warning 0

10) 추가 작업 (유닛 간격 확대)

변경 목표

유닛 간 최소 간격을 더 넓혀 겹침 가능성을 줄임
기존 Config/에셋 값이 낮아도 런타임에서 최소 분리 반경을 강제

코드 반영

EnemyConfig.SeparationRadius 기본값: 0.58f
HeroConfig.SeparationRadius 기본값: 0.62f
EnemyRuntime.DefaultTeamSeparationRadius: 0.58f
HeroController.DefaultTeamSeparationRadius: 0.62f
BarracksSoldierRuntime.DefaultTeamSeparationRadius: 0.58f
EnemyRuntime.ResolveSeparationRadius()에서 Mathf.Max(DefaultTeamSeparationRadius, _config.SeparationRadius) 적용
HeroController.ResolveSeparationRadius()에서 Mathf.Max(DefaultTeamSeparationRadius, heroConfig.SeparationRadius) 적용
BarracksSoldierRuntime.UpdateMovementSettings()에서 separation radius 최소값 클램프 적용
TowerManager 병영 기본/해석값 상향
PopulateDefaultData: SoldierSeparationRadius = 0.58f (fallback)
ResolveBarracksSeparationRadius: Mathf.Max(0.58f, config.BarracksData.SoldierSeparationRadius)

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)는 유지

11) 추가 작업 (유닛 간격 2배 상향)

변경 목표

직전 상향값 대비 유닛 간격을 약 2배로 확대하여 겹침 가능성을 추가로 낮춤

코드 반영

EnemyConfig.SeparationRadius: 0.58f -> 1.16f
HeroConfig.SeparationRadius: 0.62f -> 1.24f
EnemyRuntime.DefaultTeamSeparationRadius: 0.58f -> 1.16f
HeroController.DefaultTeamSeparationRadius: 0.62f -> 1.24f
BarracksSoldierRuntime.DefaultTeamSeparationRadius: 0.58f -> 1.16f
TowerManager.BarracksSoldierIdleRadius: 0.58f -> 1.16f
TowerManager 병영 separation fallback/min clamp: 0.58f -> 1.16f

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)는 유지

12) 추가 작업 (적대 팀 간 최소 간격 공통화)

변경 이유

팀 내부 간격은 넓어졌지만, 아군(영웅/병사)과 적의 근접 거리가 여전히 가깝게 보이는 문제 보완

코드 반영

BaseUnit.ApplyTeamSeparation(...)를 공통 확장
기존: 같은 팀(other._team == _team)만 분리
변경: 같은 팀 + 적대 팀(IsHostileTo(other)) 모두 분리 계산
적대 팀 분리는 별도 공통 훅으로 제어
ResolveHostileSeparationRadius(float friendlySeparationRadius) 추가 (기본값: max(0.38f, friendly * 0.45f))
ResolveHostileSeparationWeight() 추가 (기본값: 0.85f)
파생 클래스에서 필요 시 오버라이드 가능

기대 효과

적-적, 아군-아군뿐 아니라 아군-적 간에도 최소 간격이 유지되어 붙어 보이는 현상 완화
분리 로직은 BaseUnit에 공통 집중, 파생 클래스는 호출만 유지

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)는 유지

13) 추가 작업 (전투 중 제자리 공격 고정)

변경 이유

전투 진입 후에도 분리 보정/미세 이동이 적용되어 밀리는 느낌으로 비정상 방향 이동이 발생

코드 반영

EnemyRuntime.HandleTargetInRange(...)에서 전투 중 추적 이동 제거
EnemyRuntime.HandleTargetInRange(...)/HandleTargetInRangeWithoutAttack(...)에서 분리 보정 호출 제거
HeroController.HandleTargetInRange(...)/HandleTargetInRangeWithoutAttack(...)에서 분리 보정 호출 제거
BarracksSoldierRuntime.HandleTargetInRange(...)/HandleTargetInRangeWithoutAttack(...)에서 분리 보정 호출 제거

동작 기준

타겟이 사거리 안(in-range)이면 제자리 공격
타겟이 사거리 밖이면 기존처럼 추적/이동 로직 수행
분리 보정은 이동/추적 단계에서만 적용

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)는 유지
EnemyRuntime 전투 중 모션 상태를 Attacking으로 고정 (사거리 내 정지 공격 시 Moving 모션 잔존 방지)

14) 추가 작업 (공격 불가 시 이동 전환)

변경 이유

전투 중 in-range 상태에서 공격이 불가능한 동안(주로 쿨다운) 가만히 맞고만 있는 현상 보완

코드 반영

EnemyRuntime.HandleTargetInRangeWithoutAttack(...)
기존: 제자리(Attacking 상태 유지)
변경: MoveAlongPath(deltaTime) 호출로 이동 우선
HeroController.HandleTargetInRangeWithoutAttack(...)
기존: 제자리 시각 상태 유지
변경: HandleNoTargetOrOutOfRange(target, deltaTime) 호출로 추적/이동 로직 재사용
BarracksSoldierRuntime.HandleTargetInRangeWithoutAttack(...)
기존: Blocking 상태 고정
변경: HandleNoTargetOrOutOfRange(target, deltaTime) 호출로 추적/이동 로직 재사용

동작 기준

사거리 내 + 공격 가능: 제자리 공격
사거리 내 + 공격 불가: 이동 로직으로 전환
사거리 밖: 기존 이동/추적 로직 유지

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)는 유지

15) 추가 작업 (적 공격 불가 구간 타겟 유지 이동)

변경 이유

EnemyRuntime에서 공격 불가(in-range) 시 경로 이동으로 복귀하여 타겟과 이탈, 공격이 끊기는 현상 보완

코드 반영

EnemyRuntime.HandleTargetInRangeWithoutAttack(...) 수정
기존: MoveAlongPath(deltaTime)
변경: 타겟 기준 MoveTowardsWithStopDistance(...)로 접근 이동
target == null일 때만 경로 이동 fallback 유지

기대 효과

적이 쿨다운 중에도 전투 타겟 근처를 유지하며, 쿨다운 종료 시 공격이 다시 정상 이어짐

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)는 유지

16) 추가 작업 (전투 사거리 판정 2D 통일)

변경 이유

적/아군의 z 오프셋(예: 0 vs -0.5)이 거리 계산에 포함되어 사거리 판정이 과도하게 좁아짐
결과적으로 타겟 근처에서도 공격 루프 진입/유지가 불안정해지는 문제 보완

코드 반영

BaseUnit.FindNearestHostile(...) 거리 계산에서 z=0 정규화
EnemyRuntime.IsCombatTargetInRange(...) 거리 계산에서 z=0 정규화
HeroController.IsCombatTargetInRange(...) 거리 계산에서 z=0 정규화
BarracksSoldierRuntime.IsCombatTargetInRange(...) 거리 계산에서 z=0 정규화
HeroController의 적 탐색/스킬 범위/leash 관련 거리 계산도 2D 기준으로 통일

기대 효과

시각적으로 붙어 있는 상태에서 사거리 판정이 안정화되어 적 공격 누락 감소
유닛 z-layer 차이에 영향받지 않는 일관된 전투 판정

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)는 유지

17) 추가 작업 (적 타겟 획득/유지 안정화)

변경 이유

적이 전투 중 타겟을 쉽게 놓치고 경로 이동으로 복귀해 공격이 끊기는 현상 보완

코드 반영

EnemyRuntime.ResolveCombatTarget() 개선
공격 사거리 기반으로 acquireRange, keepRange 도입
기존 타겟이 유지 범위 내면 유지, 벗어나면 재탐색
재탐색 범위를 순수 공격 사거리보다 확장
EnemyRuntime.HandleNoTargetOrOutOfRange(...) 개선
target이 존재/유효하면 경로 복귀 대신 타겟 추적 이동
EnemyRuntime.HandleTargetInRangeWithoutAttack(...)는 공통 추적 함수 재사용
MoveTowardsCombatTarget(BaseUnit target, float deltaTime) 헬퍼 추가

기대 효과

적이 전투 타겟을 안정적으로 유지하며 쿨다운 이후 공격 루프를 다시 이어감
순간적인 거리 흔들림으로 공격이 영구적으로 끊기는 현상 완화

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)는 유지

18) 추가 작업 (전투 로직 주석 보강)

목적

최근 수정된 전투/타겟/거리 판정 로직의 의도를 코드에서 바로 이해할 수 있도록 핵심 주석 추가

반영 내용

EnemyRuntime
타겟 획득/유지 범위 상수 의도 주석
타겟 유지 vs 재획득 분기 의도 주석
2D(XY) 거리 판정 주석
사거리 내 제자리 공격 정책 주석
공격 불가 시 타겟 유지 이동 정책 주석
BaseUnit
FindNearestHostile(...)의 2D 거리 계산 의도 주석
HeroController, BarracksSoldierRuntime
사거리 판정에서 Z 무시 이유 주석

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)는 유지

19) 추가 작업 (적 공격 누락 방지 핫픽스)

변경 이유

일부 상황에서 적이 타겟을 잡지 못해 공격 루프에 진입하지 못하는 문제 보완

코드 반영

EnemyRuntime.ResolveCombatTarget()
타겟 필터를 문자열(UnitType) 비교에서 타입 기반(HeroController, BarracksSoldierRuntime)으로 변경
필터 탐색 실패 시 FindNearestHostile(...) fallback 추가 (모든 적대 유닛 대상)
EnemyRuntime.CanPerformCombatAttack(...)
target.IsAlive 검증 포함하여 공격 가능 조건 보강

기대 효과

적 타겟 획득 누락 케이스 감소
필터 불일치로 인한 '적 공격 안함' 현상 완화

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)는 유지
EnemyRuntime.ResolveCombatTarget()에 즉시 교전 반경(attackRange * 1.05) 우선 타겟 선택 추가
현재 타겟 유지 로직보다 가까운 근접 타겟을 우선 스위칭하여, 바로 옆 적대 유닛을 놓치지 않도록 보정
적 타겟 획득/유지 최소 반경 상향
acquireRange: 최소 2.8f, keepRange: 최소 3.2f 보장
원거리 영웅 상대로도 적이 전투 진입 타겟을 놓치지 않도록 보정
EnemyRuntime.IsCombatTargetInRange(...)에 유효 사거리 여유(1.15x) 적용
거리 경계값 흔들림으로 인한 공격 판정 누락 완화
EnemyRuntime.IsCombatTargetInRange(...) 유효 공격 사거리 최소값 추가
effectiveRange = max(1.8f, attackRange * 1.15f)로 보정하여 근접/밀집 전투에서 적 공격 발동 안정화

20) 추가 작업 (적 공격 디버그 로그 보강)

변경 이유

"적이 공격을 안 하는 것처럼 보인다" 이슈를 콘솔에서 즉시 판별할 수 있도록 적 공격 호출 로그를 강화
기존 [EnemyTrace]가 5초 제한이라 실제 첫 교전 시점 전에 종료될 수 있어 추적이 어려운 문제 보완

코드 반영

Assets/Scripts/Kingdom/Game/EnemyRuntime.cs
CombatTraceDurationSec: 5f -> 20f
CombatTraceIntervalSec: 0.35f -> 0.5f
실제 공격 발생 시 항상 [EnemyAttack] 로그 출력 추가
- attacker/target instance id, damage, cooldown 포함

기대 효과

적이 실제로 PerformCombatAttack에 진입하는지 즉시 확인 가능
공격 진입과 무관하게 "안 때리는 것처럼 보이는" 체감 이슈를 로그 기반으로 분리 진단 가능

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)만 유지

21) 추가 작업 (적 공격 애니메이션 상태 유지 보정)

변경 이유

실제 공격은 정상 발생하지만, 쿨다운 프레임에서 이동 상태가 즉시 덮여 공격 애니메이션이 거의 보이지 않는 문제가 확인됨
콘솔 근거: [EnemyAttack] 로그는 연속 발생, 동시에 [EnemyTrace] motion=Moving 비중이 높음

코드 반영

Assets/Scripts/Kingdom/Game/EnemyRuntime.cs
전투 상태(_motionState)와 시각 상태를 분리
- ResolveVisualMotionState() 추가
- _attackVisualHoldLeft > 0이면 시각 상태를 Attacking으로 유지
TickVisualAnimation(...)
- Animator/스프라이트 모두 시각 상태(visualState) 기준으로 모션 반영
ShouldLoopCurrentAnimation()
- _motionState 대신 현재 애니메이션 상태(_animationState) 기준으로 루프 판정
HandleTargetInRangeWithoutAttack(...)
- 쿨다운 중에도 공격 홀드가 남아있으면 모션을 Attacking으로 유지
MoveTowardsCombatTarget(...)
- 모션 상태를 강제로 Moving으로 덮어쓰던 코드 제거

기대 효과

적의 실제 타격 타이밍과 공격 애니메이션 노출 타이밍이 일치
근접 교전에서 공격 후 모션이 즉시 걷기로 튀는 현상 완화

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)만 유지

22) 추가 작업 (공격 타이밍/상태 전환 규칙 적용)

적용 규칙

공격 데미지는 공격 애니메이션이 끝나는 순간 적용
공격 상태에서는 이동하지 않음
공격 상태에서 다음 상태(이동/추적/유지) 전환은 공격 애니메이션 종료 후에만 허용

코드 반영

Assets/Scripts/Kingdom/Game/EnemyRuntime.cs
- 공격 대기 상태 필드 추가: _pendingAttackTarget, _pendingAttackDamage, _isAttackPending
- PerformCombatAttack는 즉시 데미지 대신 공격 시작(윈드업)만 수행
- CommitPendingAttack에서 애니메이션 종료 시점 데미지 확정 + 쿨다운 시작
- 공격 대기/공격 홀드 중 HandleTargetInRangeWithoutAttack, HandleNoTargetOrOutOfRange에서 이동 차단
Assets/Scripts/Kingdom/Game/HeroController.cs
- 동일한 공격 대기 상태/커밋 구조 적용
- 영웅 액티브 스킬 트리거도 데미지 커밋 시점으로 이동
- 공격 대기 중 이동 로직 진입 차단
Assets/Scripts/Kingdom/Game/BarracksSoldierRuntime.cs
- 동일한 공격 대기 상태/커밋 구조 적용
- 공격 대기/홀드 중 이동 차단, 블로킹 상태 유지

기대 효과

타격 판정과 애니메이션 노출 타이밍 일치
공격 중 밀리듯 이동하는 체감 제거
공격 종료 전 상태 전환 방지로 전투 가독성 개선

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)만 유지

23) 추가 작업 (유닛 분리/밀어내기 적용 범위 제한)

변경 이유

전투 중 이종 타입(적 vs 영웅/병사) 간에 밀어내기까지 발생해 교전 자세가 흔들리는 체감이 발생
요청사항: 같은 타입 그룹끼리만 분리 적용
- 적은 적끼리
- 영웅/배럭병사는 아군끼리
- 적 vs 아군은 분리 미적용

코드 반영

Assets/Scripts/Kingdom/Game/BaseUnit.cs
ApplyTeamSeparation(...) 로직에서 적대 팀(hostile) 분기 제거
동일 팀(sameTeam)에 대해서만 분리 push 계산 적용
주석 추가: 분리 대상은 같은 팀 그룹 한정

기대 효과

적과 영웅(또는 병사)이 서로 밀어내며 흔들리는 현상 완화
근접 교전에서 접촉/타격 자세가 더 안정적으로 유지

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)만 유지

24) 추가 작업 (검증 단계 정리: 1 완료 / 2 패스 / 3 진행)

처리 결과

1번(실플레이 회귀 확인): 완료 처리
2번(타격 타이밍 미세보정): 요청에 따라 패스
3번(디버그 로그 정리): 진행 완료

코드 반영 (로그 정리)

Assets/Scripts/Kingdom/Game/EnemyRuntime.cs
임시 디버그 로깅 제거
- 제거: [EnemyTrace], [EnemyAttack]
- 제거: CombatTrace* 상수/필드/메서드
- 제거: 타겟 변경/틱/공격 로그 호출
전투 동작 로직(공격 대기/타이밍/상태 전환)은 유지

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)만 유지

25) 추가 작업 (다음작업 2/3 처리)

상태 정리

1번(회귀 확인): 사용자 요청으로 완료 처리 (실행 검증은 미수행)
2번(전투 코드 정리): 완료
3번(워킹트리 정리): 완료

코드 정리 반영

Assets/Scripts/Kingdom/Game/BaseUnit.cs
같은 팀 분리 정책으로 전환 후 미사용 잔여 훅 제거
- 삭제: ResolveHostileSeparationRadius(...)
- 삭제: ResolveHostileSeparationWeight(...)

워킹트리 정리 반영

복원: .kilocode/mcp.json
복원: 0.0.0a0

검증

dotnet build Assembly-CSharp.csproj -nologo: 오류 0
기존 경고(MSB3277, CS0649)만 유지

26) 최종 플레이 검증 완료

확인 일자: 2026-02-28
확인 주체: 사용자 실플레이
결과: 체크리스트 항목(공격중 이동 금지 / 애니메이션 종료 타격 / 공격 종료 후 상태전환 / 같은 팀 분리 정책) 확인 완료

Claude Code 할인

blacknabis — Fri, 27 Feb 2026 00:25:44 +0900

우선 첫구매만 적용되는지는 햇갈려서 월구매 11달러 (세금포함) 꼭 확인하세요.!!

1. 접속 https://claude.ai/acquired

Claude

Claude is Anthropic's AI, built for problem solvers. Tackle complex challenges, analyze data, write code, and think through your hardest work.

claude.ai

2. 월간 결제 11달러 확인

3. 구매

왼쪽하단 프로필 정보에 Pro 요금제 확인.

모니터 3개로 유니티/안티그래비티+코덱스/클루드 3종세트완성....

중요한 시기인만큼 공부한다 생각하고 3종 구매 완료

Antigravity를 사용하여 타워 디펜스 게임 만들기 - 2 (전장 확장 및 스크롤 카메라 구현기)

blacknabis — Thu, 26 Feb 2026 01:42:05 +0900

타워 디펜스 게임 만들기 2편은 데브로그에 남겨놨지만 이것저것 삘 받아서 작업하다가 작업기간이 늘어나긴 했지만 좋은 경험치가 쌓였던것 같습니다. gpt, claude, gemini 다양하게 써보면서 자동화라던가 llm의 장담점을 익히는데 주점을 두다보니 오래걸렸네요.

맵스케일 기능 추가 한 유니티 화면 오른쪽의 스케일 적용된 카메라가 보인다.

플레이화면

[Unity 2D] 디펜스 게임 전장 확장 및 스크롤 카메라 구현기

개발 환경 노트

문서 및 블로그 기획/작성: Gemini 3.1 Pro

핵심 로직 및 코딩 구현: GPT-5.3-Codex, Claude Opus 4.6

현재 개발 중인 Kingdom Rush 스타일의 전략 디펜스 게임에서 중요한 결정을 내렸습니다. 기존에는 화면 크기(종횡비)에 맞춰 배경 이미지를 억지로 늘리고 줄여 고정된 하나의 뷰(화면) 안에서 모든 전투가 벌어지도록 설계했었는데요, 이번에 전장을 크게 키우고 자유롭게 카메라를 스크롤할 수 있도록 완전히 전환하는 작업을 진행했습니다.

카메라 스크롤을 도입한 이유?

고정 뷰 방식은 아기자기한 모바일 게임에는 좋지만, 스테이지가 거듭될수록 맵의 크기나 타워 배치 구성이 단조로워지는 한계가 있었습니다. 넓은 전장을 구현하여 사용자가 직접 카메라를 이동시키며 전략적인 전황을 살피게 만드는 것이 훨씬 스케일이 큰 몰입감을 줄 수 있다고 판단했습니다.

따라서 다음과 같은 조작이 가능한 하이브리드 카메라를 구현하기로 했습니다:

마우스 드래그 (Mouse Drag): 우클릭 또는 휠 클릭으로 직관적인 패닝 이동
키보드 이동 (WASD): 클래식한 PC 방식의 쾌적한 이동
에지 스크롤 (Edge Scroll): 화면 끝으로 마우스를 가져가면 자동으로 밀려가는 방식

️ 핵심 구현 요소

1. 부드러운 감속 (관성, Inertia)

카메라 조작 시 딱딱하게 끊기지 않고 부드러운 조작감을 주기 위해 Vector3.SmoothDamp와 커스텀 감속 로직을 활용했습니다. 마우스 드래그를 놓는 순간 입력 속력을 저장한 뒤 점차 0으로 줄여나가(Lerp) 빙판을 미끄러지듯 기분 좋은 이동(Juicy Feedback)을 적용했습니다.

2. 구역 이탈 방지 클램프 (Bounds Clamping)

전장이 아무리 넓다 해도, 배경 이미지 밖의 텅 빈 검은 화면은 몰입을 깹니다.
카메라의 뷰포트 크기를 계산하고 배경 스프라이트의 실제 크기(SpriteRenderer.bounds)와 정합하여 렌더링 영역 안에서만 카메라가 이동하도록 클램핑(Clamp) 했습니다.

개발 팁:
처음엔 고정된 Rect 값을 수동으로 넣었는데, 이후 맵이 변경될 때마다 관리하기가 어려웠습니다. GameBattlefield 오브젝트가 초기화될 때 배경 스프라이트의 Bounds 영역을 자동으로 계산해 반환하도록 속성(GameplayBounds)을 구성하여 자동화했습니다.

3. UI 조작 간섭 방지 (EventSystem)

마우스 클릭으로 타워를 업그레이드할 때 카메라가 스크롤되면 안 되겠죠?
EventSystem.current.IsPointerOverGameObject()를 통해 UI 위에서 클릭이 시작되었을 때는 카메라 드래그 이벤트를 차단했습니다. (물론 WASD 이동은 전투 중에도 언제든 조작할 수 있도록 예외처리했습니다.)

트러블슈팅: 영웅만 소인국 사람이 되다? (Scale Mismatch)

이번 작업에서 가장 골치 아팠던(그리고 재밌었던) 버그입니다. 전장이 넓어지니 기존 영웅 캐릭터가 상대적으로 너무 작게 출력되는 문제가 발생했습니다. 배경은 장대한데, 디펜스의 꽃인 영웅이 개미처럼 작아 보였죠.

원인 분석:
GameBattlefield 프리팹 자체가 전체 스케일업을 위해 루트 Transform의 localScale 값으로 (2, 2, 1)을 가지고 있었습니다. 타워나 적 몬스터들은 모두 ఈ 프리팹 하위(Child)에 스폰되니 자연스럽게 2배 스케일을 상속받았지만...
영웅 컨트롤러는 GameScene에서 World Root 레벨(최상위)에 둥그러니 스폰되고 있었기 때문에 원래 크기인 (1, 1, 1)로 표시되었던 것입니다. 화면과 적들은 2배인데, 영웅 혼자 정사이즈니 작아 보일 수밖에 없었죠.

해결 방안:

Hierarchical Parenting (계층 구조 정합): 영웅도 전장의 환경 요소를 따르도록 구조를 개선했습니다. GameBattlefield에 heroRoot라는 컨테이너를 하나 파두고, 영웅이 맵에 생성될 때 해당 Root 하위로 SetParent 시켰습니다.
즉석에서 Vector3 사이즈를 수동으로 1.5배, 2배 곱해주는 코딩은 나중에 큰 기술 부채가 될 수 있어 피하고, 가상공간(부모 객체)의 스케일을 자연스럽게 상속받도록 설계했습니다.

// GameScene.cs - Hero 스폰 로직 중
_heroController = new GameObject("HeroController").AddComponent<HeroController>();
// 핵심: 영웅을 생성한 후, 2배 스케일을 가진 HeroRoot의 자식으로 배치!
_heroController.transform.SetParent(_battlefield.HeroRoot, false);

개발 과정에서 궁금하신 점이 있다면 언제든 댓글 남겨주세요!

Antigravity 토큰 확인하기

blacknabis — Thu, 26 Feb 2026 00:30:58 +0900

얼마전 까지 안티그래비티에서 토큰 확인 할 방법이 없어서 IDE에서 Antigravity Quota를 설치하 아래와 같이 확인을 하였습니다.

확장메뉴

토큰 확인

얼마전 업데이트 이후 에이전트에서 확인이 가능해졌습니다.

에이전트 우상단 옵션

모델을 선택하면 다음과 같이 확인 가능

에이전트에서 모델/토큰이 보이지 않는다면 안티그래비티 업데이트를 진행해보세요.

글을 다 작성하니 Antigravity Cockpit라는게 또 있네요

Antigravity <-> Codex IDE MCP 오답 노트(우회해결)

blacknabis — Wed, 25 Feb 2026 22:56:59 +0900

codex-mcp-sever

IDE에서 IDE로 MCP를 연결해서 될거라 생각했는데 이방법이 아니라 Antigravity에서 codex-mcp-server를 사용하여 다음과 같이 명령해서 문서 보완에 성공. 하지만 수동으로 하는것보단 느린거 같은데 다시한번 채크해봐야될것 같음

문서보완 핑퐁

최종완료

Antigravity <-> Codex IDE MCP 오답 노트

blacknabis — Wed, 25 Feb 2026 01:27:48 +0900

Roo Code <-> Antigravity 계획 자동보완

문서를 보완할 때 서로 핑퐁을 하면서 계속 수동으로 문서보완 명령을 하는데 너무 불편해서 방법을 알아보다가 MCP를 제작하여서 자동으로 서로 핑퐁을 주고받으려고 했지만 실패....

전부 실패...

그래서 API키를 받아서 핑퐁하는 식으로 개선....

MCP 추가하였지만 처참하게 실패... IDE기반의 핑퐁은 조금 더 공부를 해서 다시 도전해봐야될거같다.

문서 폐기 엔딩.....

더 이상 보다가는 밤새고 출근 못 할 거 같아서 오늘은 4시간 삽질하고 좋은 경험 했다 생각하고 기권

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

blacknabis — Mon, 23 Feb 2026 23:07:49 +0900

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

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. 슬롯 시각화(가이드 이미지) 표시

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

완료 기준 (DoD)

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

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

TryBuildTowerAtSlot 성공 시 해당 슬롯 마커 숨김.
타워 판매 시 슬롯이 다시 free 되면 마커 재표시.
타워 업그레이드 시: 슬롯 점유 상태 불변 → 마커 상태 변경 없음 (숨김 유지).
초기 동기화 보강:
- 로드/재시작 시 현재 점유 상태와 마커 표시 상태를 일치시킴.
마커 표시/숨김 트랜지션 정책:
- 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. 작업 순서(실행 권장)

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

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

적용 대상 씬/프리팹 확정:
- GameBattlefield가 실제로 배치된 전투 씬 목록 확정
- 각 씬의 TowerRoot 하위 슬롯 Transform 최소 1개 이상 배치 여부 사전 점검
슬롯 마커 에셋 준비:
- 기본(Idle) 1종 필수
- 선택사항: Hover/Selected 변형 2종
UI 충돌 정책 확정:
- 슬롯 마커는 월드 오브젝트(2D Collider 미사용 권장)로 유지
- 클릭 판정은 기존 TryFindBuildableSlotAtWorldPosition()를 단일 소스로 유지
로그 포맷 확정:
- 에러/정보 로그 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. 관측성(로그/디버그) 계획

필수 로그

슬롯 유효성 실패

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

슬롯 마커 초기화

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

슬롯 점유/해제 반영

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

디버그 헬퍼(선택)

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

12. 성능/안정성 가드

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

13. 롤백 전략

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

14. 문서 동기화 계획

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

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

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

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

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

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

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

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

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

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

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

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

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

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

19. 완료 정의 (Final Exit Criteria)

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

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

Codex/Antigravity 타워 디펜스 만들기 - 애니메이션 툴(스프라이트시트/타워)

blacknabis — Mon, 23 Feb 2026 01:23:27 +0900

영웅/적/병영유닛 3개를 모두 세팅하고 이제 타워도 스프라이트 툴로 만들기 위해 타워용 스프라이트 툴 개선. 및 적용 스샷 올립니다.

나노바나나프로를 이요한 타워이미지

타워용 애니메이터 제작 탭

시간이 늦은관계로 잘나오는지만 채크.

우선 반영이 잘되었고 유닛과 건물의 스케일 및 앵커에 대한 처리는 별도로 진행해야되겠네요.

영웅이동도 지금은 우클릭으로 해놨는데 모바일을 생각해서 터치에 대한 처리 고도화도 필요하네요.

시간이 늦은관계로 블로그는 짧게 올립니다.

그나저나 플랜 강화시킬때 자동실행으로 세팅해놓으니 제미나이가 문서 보완 직후에 바로 작업 진행하는 사고가 많이 터지네요.. 이런 경우 코덱스같은경우 별 트러블이 안생기는데 제미나이 3.1을 썼음에도 의도치 않게 작업되는 방향이 있네요... 이럴떄 코덱스의 보수적인 성향이 마음에듬...

작업 상세 로그 (2026-02-22)

blacknabis — Sun, 22 Feb 2026 22:59:20 +0900

본 내용은 작업내역이 많아 금일 작업 내역을 GPT-5.3 Codex로 정리 후 Claude Opus 4.6모델로 한번 다듬고 md저장 후 올린 내용입니다.

2026-02-22 개발로그

오늘의 목표

전투 씬에서 선택 UX를 안정화한다.
히어로 스프라이트/애니메이션 로딩 경로를 정리한다.
월드 HP바와 선택 패널의 정보 불일치를 해결한다.
일회성 에디터 툴을 정리하고 회귀 메뉴를 개발 전용 경로로 재배치한다.

해결한 이슈 요약

히어로 애니메이션 누락으로 GameScene 시작 중단
배럭 병사/타겟 선택 시 패널 반응 불안정
SelectionInfoPanel 레이아웃 겹침 및 가독성 저하
월드 HP바 생성/표시 오류(NullReference, 프리팹 구성 누락, 위치/앵커 이슈)
타워 클릭 시 액션 메뉴는 열리지만 SelectionInfoPanel 미표시
영웅 선택 시 현재 HP가 0으로 보이고 HP바가 바닥난 것처럼 보이는 문제
Tools 메뉴의 일회성 빌더/회귀 메뉴 정리 필요

주요 원인과 수정 내용

1) 히어로 스프라이트 로딩 불일치

현상:
- 런타임은 idle/walk/attack/die 액션 레코드를 기대했지만,
- manifest.json에는 actionGroup=multi 레코드만 존재.
수정:
- GameScene 검증 로직에서 multi를 액션 후보로 인정.
- multi 텍스처 안에 액션 토큰(_idle_/_walk_/_attack_/_die_) 프레임이 실제 있는지 추가 검증.
- HeroController에서 multi 텍스처 로드시 현재 액션 프레임만 필터링해 재생.
효과:
- SmartSlice 4행 분리 결과를 단일 텍스처로 관리해도 런타임 4액션 재생 가능.

2) 영웅 HP 동기화 오류

현상:
- 최대 체력은 정상인데 현재 체력이 0으로 표기.
- 월드 HP바도 항상 빈 상태처럼 보임.
원인:
- 일부 경로에서 _currentHp와 _maxHp 동기화 누락.
수정:
- HeroController.Configure() / Respawn()에서 InitializeHealth() 사용으로 체력 초기화 통일.
- 레벨업 시 _maxHp 갱신 반영.
효과:
- 패널의 현재/최대 체력 및 월드 HP바 비율 표기 정상화.

3) 타워 클릭 시 SelectionInfoPanel 미표시

현상:
- 타워 액션 메뉴는 열리지만 선택 패널은 열리지 않음.
원인:
- GameScene이 타워 클릭을 먼저 처리하고 선택 입력을 suppress.
수정:
- 타워 클릭 분기에서 액션 메뉴를 열 때 SelectionController.Select(towerTarget)를 명시 호출.
- TowerManager.TryGetTowerSelectableTarget() 추가로 타워 선택 프록시 획득 경로 보강.
효과:
- 타워 클릭 시 액션 메뉴 + SelectionInfoPanel 동시 동작.

4) SelectionInfoPanel 정보/레이아웃 개선

반영:
- DisplayName, HP, ATK, DEF 표기를 명확히 분리.
- 한 줄 과밀 표기를 2줄/다줄 구조로 개선.
- 이름 길어질 때 말줄임/최대 줄 수 제한 적용.
- 패널 위치를 우측 상단 사이드 영역으로 정렬하여 좌측 HUD와 충돌 제거.
- HP 슬라이더 제거(텍스트 기반 HP 표기로 통일).

5) 월드 HP바 안정화

반영:
- 프리팹 컴포넌트 누락 시 방어 로직 보강.
- 생성/풀링 경로 null 방어 강화.
- 머리 위 앵커 계산 및 오프셋 조정.
- Fill 감소 방향을 좌측 고정 기준으로 보정.

6) 에디터 툴 정리

반영:
- 일회성 Build*Prefab, 데이터 생성/마이그레이션성 툴 제거.
- 회귀 메뉴는 Developer 하위로 이동해 운영 메뉴와 분리.
- AI Sprite Processor 윈도우 진입 경로는 유지.

오늘 검증 항목

dotnet build Assembly-CSharp.csproj -v minimal 오류 0 유지.
Selection + HP UI 스모크 회귀 통과 구간 재확인.
실제 플레이에서 아래 시나리오 확인:
- 영웅/적/배럭병사/타워 클릭 시 패널 노출
- 타워 클릭 시 액션 메뉴와 선택 패널 동시 동작
- 영웅 HP 텍스트/월드 HP바 정상 비율 표기

Codex/Antigravity 타워 디펜스 만들기 - 애니메이션 툴(스프라이트시트)

blacknabis — Sun, 22 Feb 2026 04:48:35 +0900

디펜스 게임 캐릭터를 연동하면서, 리소스 작업을 더 편하게 자동화할 방법을 고민했습니다. 처음에는 가로·세로 크기, 시작 위치, 행/열을 지정해 스프라이트시트를 추출하는 툴을 만들었습니다.

초기 스프라이트 시트 툴

하지만 캐릭터 수가 늘어나자 수작업이 너무 불편해졌고, 나노바나나프로로 생성한 결과물도 규칙이 일정하지 않아 처리 난도가 높았습니다. 그래서 방향을 바꿔 스마트 슬라이스와 자동 배경 제거를 강화하고, 스프라이트시트 추출 대신 Unity Animator 데이터를 자동 생성하는 방식으로 작업을 시작했습니다.

먼저 구글 플로에서 나노바나나프로로 그리드형태의 이미지 추출

적타입, 에셋,이미지를 선택 후 버튼클릭!

추출된 스프라이트 이미지 배경은 투명(마젠타색이 미묘하게 남아있다.)

에셋파일에 애니메이터 패스가 연결되어있다

자동으로 생성된 애니메이터와 애니메이션

적용된 게임화면! 타워는 아직 작업중!

초기에 시스템을 잡고 리소스 생성 자동화까지 포함해 개발하니, 단순 하드코딩보다 시간이 더 걸리긴 했습니다. 다만 아이디어 변경이나 고도화 단계에서는 훨씬 빠르게 개선할 수 있다는 장점이 있었습니다.

오늘 작업은 여기까지입니다.

Gemini 3.1 Pro는 ‘업데이트’가 아니다: Google Antigravity 시대를 여는 실전형 AI 전환점

blacknabis — Fri, 20 Feb 2026 08:03:26 +0900

구글이 Gemini 3.1 Pro를 발표했다.

표면적으로는 성능 개선 소식이지만, 실제로는 더 큰 변화의 신호다.

이번 발표의 핵심은 “더 잘 답하는 모델”이 아니라, 복잡한 문제를 끝까지 해결하는 모델에 있다.

기존 세대의 AI가 요약·질의응답 중심이었다면, 3.1 Pro가 겨냥하는 지점은 다르다.

문제를 구조화하고, 맥락을 유지하고, 코드와 결과물로 연결하는 실행형 추론(Reasoning-to-Execution)이다.

구글이 배포 경로를 잡은 방식도 이를 뒷받침한다.

- 개발자: Gemini API(AI Studio), Gemini CLI, Google Antigravity, Android Studio(프리뷰)

- 기업: Vertex AI, Gemini Enterprise

- 일반 사용자: Gemini 앱, NotebookLM(일부 요금제)

즉, 단일 모델 홍보가 아니라 개발·업무·소비자 경험 전체를 연결하는 플랫폼 전략으로 보는 게 맞다.

성능 지표(예: 고난도 추론 벤치마크 개선)는 분명 중요하다.

하지만 더 본질적인 질문은 이것이다.

“그래서 실제 업무가 어떻게 달라지는가?”

3.1 Pro가 제시하는 방향은 명확하다.

1) 텍스트 프롬프트를 코드 기반 시각 결과물로 전환

2) 복잡한 API/데이터를 통합해 대시보드 형태로 구조화

3) 인터랙티브 프로토타입을 빠르게 구현

4) 추상적 아이디어를 기능 단위로 구체화

이건 더 이상 “대답형 AI”의 역할이 아니다.

기획-설계-개발 사이를 연결하는 실행 파트너의 역할이다.

여기서 가장 주목할 키워드는 Antigravity다.

좋은 모델만으로 생산성 혁신은 일어나지 않는다.

진짜 변화는 모델이 아니라, 모델을 반복 실행시키는 워크플로우 계층에서 생긴다.

Antigravity 같은 에이전트 개발 환경 위에서 3.1 Pro가 안정적으로 작동한다면,

개발자의 역할은 점점 “직접 구현자”에서 “문제 구조 설계자/오케스트레이터”로 이동하게 된다.

앞으로 중요한 역량은 단순 코딩 속도가 아니라

- 문제 분해 능력

- 실행 루프 설계 능력

- 결과 검증/보정 능력

- 비용·속도·품질 균형 감각

이 될 가능성이 높다.

물론 현재는 프리뷰 단계다.

그래서 지금 필요한 태도는 과열된 기대가 아니라, 냉정한 검증이다.

- 실제 비용 대비 효율은 유지되는가

- 장시간/다단계 작업에서도 일관성이 유지되는가

- 기업 환경의 보안·감사 요구를 충족하는가

- 팀 단위 협업 프로세스에 무리 없이 녹아드는가

이 질문에 답할 수 있다면, 3.1 Pro는 “좋은 신모델”을 넘어

업무 방식 자체를 바꾸는 실무 표준으로 자리잡을 수 있다.

결론은 단순하다.

Gemini 3.1 Pro 발표는 모델 경쟁 뉴스가 아니다.

AI가 ‘도구’에서 ‘실행 파트너’로 이동하는 시점을 보여주는 신호다.

그리고 그 변화의 중심에, Google은 이미 Antigravity라는 실행 계층을 올려두었다.

한 줄 요약:

Gemini 3.1 Pro는 더 똑똑한 챗봇이 아니라, Antigravity와 결합해 실전 워크플로우를 재편할 가능성이 큰 전환점이다.

※ 본 글은 https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-1-pro/ 를 참조해 작성했습니다.

※ 본문 작성에는 OpenClaw와 GPT를 활용했습니다.

OpenClaw 설치 + Telegram 연동 가이드 (실제 명령어 포함)

blacknabis — Fri, 20 Feb 2026 05:49:48 +0900

OpenClaw 설치 + Telegram 연동 실전 가이드

안녕하세요.

이번 글은 OpenClaw를 처음 설치한 뒤 Telegram과 연동해 실제로 동작시키는 과정까지, 실전 기준으로 정리한 튜토리얼입니다.

이 글은 Telegram으로 OpenClaw를 연동한 환경에서 작성했습니다.

────────────────────────

3줄 요약

────────────────────────

1) Bot Token + chat_id만 정확하면 연동의 80%는 끝납니다.

2) 문제 발생 시 `openclaw status --deep`에서 대부분 원인 확인이 가능합니다.

3) getUpdates 결과가 비면 먼저 봇에게 `/start`를 보내세요.

✅ 준비물

- macOS 환경

- Telegram 계정

- BotFather(@BotFather)

- OpenClaw 설치 완료 상태

────────────────────────

STEP 1. OpenClaw 상태 점검

────────────────────────

설치 직후에는 반드시 상태를 먼저 확인합니다.

openclaw status

상세 진단이 필요하면:

openclaw status --deep

체크 포인트

- Gateway reachable

- Sessions active

- Telegram channel 상태 OK

────────────────────────

STEP 2. Telegram Bot 만들기

────────────────────────

1) Telegram에서 @BotFather 접속

2) /newbot 실행

3) 봇 이름/유저네임 설정

4) Bot Token 발급

⚠️ 주의

Bot Token은 비밀번호와 동일합니다.

외부 채팅/스크린샷/깃 커밋에 절대 노출하지 마세요.

────────────────────────

STEP 3. chat_id 확인

────────────────────────

많이 헷갈리는 부분입니다.

@username이 아니라 숫자형 chat_id가 필요합니다.

절차

- 봇 채팅방에서 /start 전송

- 일반 메시지 1개 전송

- 아래 주소 호출

https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

응답에서 확인할 값

- chat.id (예: 7992536188)

────────────────────────

STEP 4. OpenClaw Telegram 설정 반영

────────────────────────

핵심 설정 항목

- channels.telegram.enabled

- channels.telegram.botToken

- channels.telegram.dmPolicy

설정 반영 후 재확인

openclaw status --deep

────────────────────────

STEP 5. 송수신 테스트

────────────────────────

Telegram API 직접 테스트

https://api.telegram.org/bot<YOUR_BOT_TOKEN>/sendMessage?chat_id=<CHAT_ID>&text=OpenClaw%20test

응답에 ok:true가 뜨면 API 경로는 정상입니다.

이제 Telegram에서 봇에게 직접 메시지를 보내고,

OpenClaw 응답이 오는지 확인하면 연동 완료입니다.

────────────────────────

트러블슈팅

────────────────────────

[문제 1] 401 Unauthorized

- 원인: 토큰 오타 / 재발급 후 구 토큰 사용

- 해결: BotFather에서 새 토큰 발급 후 설정값 갱신

[문제 2] getUpdates 결과가 비어 있음(result: [])

- 원인: 봇이 사용자 메시지를 아직 못 받음

- 해결: /start + 일반 메시지 전송 후 재조회

[문제 3] 봇은 보내는데 응답이 없음

- 점검: dmPolicy / allowFrom / Gateway 상태 / chat_id 정확성

────────────────────────

보안 체크리스트

────────────────────────

- Bot Token/API Key 외부 노출 금지

- 로그/캡처 공유 시 민감정보 마스킹

- 노출 의심 시 즉시 토큰 폐기 및 재발급

────────────────────────

마무리

────────────────────────

OpenClaw + Telegram 연동은 아래 3가지만 정확하면 안정적으로 운영할 수 있습니다.

1. Bot Token 정확성

2. chat_id 정확성

3. 상태 점검 습관(openclaw status --deep)

다음 글에서는 실제 운영용으로

- 알림 자동화

- 간단한 작업 예약

- 문제 감지 루틴

까지 연결해보겠습니다.

AI/잡다한개발노트 스프라이트 에디터(Gpt 5.3 Codex, Antygravity)

blacknabis — Thu, 19 Feb 2026 02:20:50 +0900

스프라이트시트 툴

타워디펜스 게임을 만드는 중 ComfyUI로 이미지 픽셀화 -> 픽셀 애니메이션 -> 프레임으로 잘라서 스프라이트 R&D를 하는 중 뽑기 빨도 있고 나노바나나와 퀄리티 차이가 있어서 그냥 나노바나나로 그리드 이미지를 뽑아내고 그걸 스프라이트로 빼는 작업이 더 빠를 것 같아서 스프라이트 툴을 만들어 자동화 작업이 더 효율적이라고 판단.

Gpt 5.3 Codex가 점점 메인이 되어가는 듯합니다. 안티그래비티의 클루드코드는 너무 빨리(3개) 토큰이 주간한도가 다 차버렸고 제미나이는 Codex와 같이 계획을 짜는걸 메인으로 하고 있네요. 목표가 1주일 동안 타워디펜스 끝내는 건데 ComfyUI자동화에 너무 삘 받아서 시간을 너무 소비했음.. ㅠ

작업 상세 로그 (2026-02-15)

blacknabis — Sun, 15 Feb 2026 21:44:11 +0900

작업량을 도저히 다 블로그에 올리기 힘들어서 작업 할때 마다 코덱스에 정리 요청 후 업로드합니다...

Antigravity(서브), Codex(메인) 사용, Comfyui, notebooklm, nanobanana

위치: 문서/진행/작업상세로그.md
원칙: 작업 단위마다 "무엇을/왜/어떻게/검증"을 기록하고 지속 갱신한다.

작업상세로그_2026_02_15.md

0.03MB

2026-02-15

1) 전투 피해 공식 공통화 + 비행 타겟 제약 반영

목적
- 타워 피해 계산을 공통 함수로 단일화하고, 타워별 비행 적 타겟 제약을 실제 전투 루프에 반영.
변경 파일
- Assets/Scripts/Kingdom/Game/Data/TowerConfig.cs
- Assets/Scripts/Kingdom/Game/EnemyRuntime.cs
- Assets/Scripts/Kingdom/Game/TowerManager.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- DamageType, DamageCalculator 추가.
- TowerConfig에 DamageType, HalfPhysicalArmorPenetration 필드 추가.
- EnemyRuntime.ApplyDamage(...)를 공통 계산식 경유로 전환.
- TowerManager 타겟 선택 시 CanTargetAir 반영.
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

2) 타워 링 메뉴 최소 구현 + 타입 선택 건설 연결

목적
- Build 버튼 기반 단일 건설에서 벗어나, 타입 선택 가능한 최소 링 메뉴를 도입.
변경 파일
- Assets/Scripts/Kingdom/UI/GameView.cs
- Assets/Scripts/Kingdom/App/GameScene.cs
- Assets/Scripts/Kingdom/Game/Data/TowerConfig.cs
- Assets/Scripts/Kingdom/Game/TowerManager.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- 링 메뉴 항목 추가: Archer/Barracks/Mage/Artillery/Cancel.
- 타입 선택 이벤트 TowerBuildTypeRequested 추가.
- GameScene -> TowerManager.TryBuildNextTower(TowerType) 연결.
- 타입별 런타임 프로필 반영(색상/마법 피해/포병 관통/병영 공중 타겟 제한).
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

3) 링 메뉴 경제 연동(비용 표기/골드 부족 비활성)

목적
- 링 메뉴에서 실제 건설 가능 여부를 즉시 확인 가능하도록 UI/경제 상태 연동.
변경 파일
- Assets/Scripts/Kingdom/Game/TowerManager.cs
- Assets/Scripts/Kingdom/UI/GameView.cs
- Assets/Scripts/Kingdom/App/GameScene.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- TowerManager.GetBuildCost(TowerType) 추가.
- 타입별 실제 골드 소모를 GetBuildCost 기준으로 적용.
- 링 메뉴 버튼 라벨에 nG 표시.
- 골드 부족/슬롯 부족 시 버튼 비활성 + 그레이아웃 처리.
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

4) 건설 포인트 직접 클릭 건설 흐름 전환

목적
- 명세의 "빈 건설 포인트 터치 → 해당 위치에 건설" 흐름 반영.
변경 파일
- Assets/Scripts/Kingdom/Game/TowerManager.cs
- Assets/Scripts/Kingdom/App/GameScene.cs
- Assets/Scripts/Kingdom/UI/GameView.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- 슬롯 관리 방식을 순차 인덱스에서 free slot index 기반으로 전환.
- TryBuildTowerAtSlot(...), TryFindBuildableSlotAtWorldPosition(...) 추가.
- GameScene.Update()에서 월드 클릭 기반 빈 슬롯 탐색.
- 선택 슬롯 월드 위치에 링 메뉴 오픈 후 지정 슬롯 건설.
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

5) 기존 타워 액션 메뉴(업그레이드/판매) 최소 구현

목적
- 기존 타워를 선택해 업그레이드/판매할 수 있는 2차 액션 흐름을 최소 기능으로 연결.
변경 파일
- Assets/Scripts/Kingdom/Game/TowerManager.cs
- Assets/Scripts/Kingdom/App/GameScene.cs
- Assets/Scripts/Kingdom/UI/GameView.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- TowerManager 확장:
  - TowerActionInfo 구조체 추가
  - TryFindTowerAtWorldPosition(...)로 클릭 타워 선택
  - TryGetTowerActionInfo(...)로 메뉴 표시 정보 제공
  - TryUpgradeTower(...) / TrySellTower(...) 추가
  - 업그레이드 최대 레벨 Lv3 적용, 레벨에 따른 피해/공속 보정
  - 판매 시 환급 지급 및 슬롯 재사용 가능 상태로 복원
- GameView 확장:
  - TowerActionMenuRoot(Upgrade/Sell/Close) 런타임 생성
  - 타워 타입/레벨/비용/환급 표시
  - 골드 부족 시 Upgrade 비활성화
- GameScene 입력 처리:
  - 월드 클릭 시 타워 우선 선택
  - 타워 선택 시 액션 메뉴 오픈
  - Upgrade/Sell 이벤트를 TowerManager로 전달 후 HUD/메뉴 상태 동기화
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

6) 프로젝트 README 최신화

목적
- 현재 구현 상태와 문서 체계를 루트 README에 반영해 신규 진입 시 혼선을 줄임.
변경 파일
- README.md
작업 내용
- 프로젝트 상태 섹션을 최신 전투 기능 기준으로 업데이트.
- Unity 권장 버전을 6000.x 계열로 명시.
- 문서 섹션을 문서/진행 기준(명세서/task/작업상세로그)으로 교체.
- 개발일지/이미지 프롬프트 문서 경로 추가.
검증
- 경로 유효성 및 문서 링크 텍스트 확인.

7) 병영 블로킹 루프 최소 구현

목적
- 명세의 병영 핵심 루프(Moving -> Blocked -> Attacking -> Dead)를 최소 기능으로 실전 루프에 연결.
변경 파일
- Assets/Scripts/Kingdom/Game/EnemyRuntime.cs
- Assets/Scripts/Kingdom/Game/TowerManager.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- EnemyRuntime:
  - EnemyMotionState 추가(Moving/Blocked/Attacking/Dead)
  - TryEnterBlock(...), ReleaseBlock(...) API 추가
  - 블록 상태일 때 경로 이동을 멈추고 블록 앵커 주변에서 전투 상태로 유지
- TowerManager:
  - 병영 타워 전용 TickBarracks(...) 추가
  - 지상 적 점유 후 블로킹 유지 및 근접 공격
  - 적 제거/타워 판매 시 블로킹 해제 처리
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

8) 병영 랠리 포인트 지정 최소 구현

목적
- 병영 타워의 집결 지점을 타워 원점에서 분리해 전술 제어 지점을 제공.
변경 파일
- Assets/Scripts/Kingdom/Game/TowerManager.cs
- Assets/Scripts/Kingdom/App/GameScene.cs
- Assets/Scripts/Kingdom/UI/GameView.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- GameView:
  - 타워 액션 메뉴에 Rally 버튼 추가
  - 병영이 아닌 타워에서는 Rally 비활성/숨김 처리
- GameScene:
  - Rally 클릭 시 랠리 지정 모드 진입
  - 다음 월드 클릭 위치를 랠리 포인트로 전달
- TowerManager:
  - TowerActionInfo에 SupportsRally, RallyPoint 추가
  - TrySetRallyPoint(...) 추가(반경 클램프)
  - 병영 블로킹/교전 중심점을 랠리 포인트 기준으로 전환
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

9) 조기 호출 보상(Early Call) 최소 구현

목적
- 조기 호출 버튼의 전투 리스크/리워드 루프를 실제 보상으로 연결.
변경 파일
- Assets/Scripts/Kingdom/Game/GameStateController.cs
- Assets/Scripts/Kingdom/App/GameScene.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- FSM:
  - TryEarlyCallNextWave() 추가 (WaveRunning에서만 유효)
  - 마지막 웨이브 조기 호출 시 Result 전환
- GameScene:
  - NextWaveRequested 이벤트 바인딩
  - 조기 호출 성공 시 보상 지급:
    - WaveConfig.WaveData.BonusGoldOnEarlyCall
    - + (남은 wave 시간 × 2) (반올림)
  - 스펠 쿨다운(강화/불비) 각각 4초 단축
  - SetNextWaveInteractable 및 SetSpellCooldown HUD 동기화
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

10) Hero/Spell 설정 데이터 최소 스키마 + 스펠 설정 참조 전환

목적
- 5단계 데이터 선행 항목(HeroConfig, SpellConfig)을 먼저 확보하고, 스펠 쿨다운 로직의 하드코딩을 설정 기반으로 전환.
변경 파일
- Assets/Scripts/Kingdom/Game/Data/TowerConfig.cs
- Assets/Scripts/Kingdom/App/GameScene.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- HeroConfig, SpellConfig 클래스 추가(현재 빌드 반영 특성상 TowerConfig.cs 내부에 선언).
- GameScene에서 스펠 설정 로드:
  - Data/SpellConfigs/ReinforceSpell
  - Data/SpellConfigs/RainSpell
- 설정 미존재 시 런타임 fallback SpellConfig 생성.
- 조기 호출 단축/스펠 쿨다운 계산을 설정값 기반으로 변경.
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

11) HeroController 최소 구현 + GameScene 연동

목적
- 5단계 코드 항목인 HeroController를 최소 루프로 먼저 연결해 전투 중 영웅의 기본 존재감을 확보.
변경 파일
- Assets/Scripts/Kingdom/Game/SpawnManager.cs
- Assets/Scripts/Kingdom/App/GameScene.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- HeroController 추가:
  - SpawnManager 이벤트 구독으로 활성 적 목록 관리
  - 최근접 적 추적, 사거리 밖 이동/사거리 내 공격(쿨다운)
  - 타깃 제거 시 재탐색, 비전투 시 홈 포지션 복귀
  - SpriteRenderer fallback 비주얼 추가
- GameScene 연동:
  - HeroController 자동 생성/탐색
  - HeroConfig 로드(Data/HeroConfigs/DefaultHero)
  - 리소스 미존재 시 fallback HeroConfig 생성
  - 전투 시작 시 스폰매니저/스폰 위치를 주입해 즉시 동작
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

12) 승/패 결과 계산 + 결과 UI 표시 연결

목적
- 전투 종료 시 디버그 고정 메시지가 아니라 실제 전투 상태 기반의 결과를 표시.
변경 파일
- Assets/Scripts/Kingdom/App/GameScene.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- Result 상태 진입 시 PresentBattleResult(...)를 호출하도록 연결.
- 승/패 판정 로직 추가:
  - 생명력 0 이하면 패배
  - 생명력이 남고 마지막 웨이브 이상이면 승리
- 별 계산 로직 추가:
  - WaveConfig.StarThresholds를 기준으로 3/2/1별 산출
- 결과 UI 반영:
  - GameView.ShowResult(isVictory, message)로 타이틀/메시지 표시
  - _resultPresented 플래그로 중복 표시 방지
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

13) 결과 저장(SaveManager) + 월드맵 복귀 애니메이터 연계

목적
- 전투 종료 결과를 저장 데이터와 월드맵 복귀 연출로 일관되게 전달.
변경 파일
- Assets/Scripts/Kingdom/App/GameScene.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- GameScene에 결과 확정 루틴(FinalizeBattleResult) 추가.
- 승리 시 SaveManager.Instance.SaveData.SetStageCleared(...) 호출로 스테이지 결과 저장.
- 승/패 공통으로 WorldMapReturnAnimator.SetPendingReturnData(...) 호출:
  - stageId / isCleared / clearTime / difficulty 전달
- 결과 루틴 중복 실행 방지를 위해 _resultFinalized 가드 적용.
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

14) 월드맵 재진입 시 저장 진행도 즉시 반영 루프 보강

목적
- 게임씬 결과 저장 직후 월드맵 노드/UI가 이전 캐시 상태를 보여주는 문제를 방지.
변경 파일
- Assets/Scripts/Kingdom/UI/WorldMapView.cs
- Assets/Scripts/Kingdom/App/WorldMapScene.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- WorldMapView.RefreshStageNodeProgress() 추가:
  - 스테이지 데이터 재로딩
  - SaveManager.Instance.SaveData 기반 Repository로 Presenter 재생성
  - 노드 전체 재바인딩
- 호출 시점 추가:
  - WorldMapView.OnEnter(...)
  - WorldMapScene.OnStartScene()
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

15) 보스 면역 전투 판정 반영 + 결과 저장 가시화 보강

목적
- High Risk 항목인 보스 면역 플래그를 실제 전투 판정에 반영하고, 저장 반영 검증을 UI에서 즉시 확인 가능하게 보강.
변경 파일
- Assets/Scripts/Kingdom/Game/EnemyRuntime.cs
- Assets/Scripts/Kingdom/App/GameScene.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- EnemyRuntime:
  - IsBoss, IsInstaKillImmune 프로퍼티 추가
  - 보스는 TryEnterBlock(...)에서 false 반환(블로킹/강제 제어 면역)
  - TryApplyInstantKill() API 추가(면역 대상 차단)
- GameScene:
  - 승리 결과 메시지에 BEST 별, BEST 시간 포함
  - 저장 직후 UserSaveData 값을 읽어 표시
  - 보스 스테이지 승리 시 BossEventSystem.NotifyBossStageCleared(...) 호출
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

16) Mock 격리 상태 검증(DEV_MOCK 경계 확인)

목적
- 6단계 항목인 Mock 경로 분리가 실제 코드 기준으로 유지되는지 확인.
변경 파일
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- 코드 스캔(rg)으로 GameMockController 사용 지점을 점검:
  - 구현 파일 내부 #if DEV_MOCK 블록 외 호출 없음
  - GameScene/WorldMapScene 기본 경로에서 Mock 참조 없음
- task.md의 6단계 체크 항목 3개 완료 처리:
  - DEV_MOCK 분기 격리
  - 기본 실행 경로 Mock 분리
  - 비활성 빌드 Mock 호출 0건
- 명세서의 Mock 비활성/호출 0건 체크 항목 동기화 완료.
검증
- rg -n "GameMockController|DEV_MOCK" Assets/Scripts/Kingdom 결과 기준 호출 범위 확인.

17) 저장 실패/로드 실패 안전 폴백 보강

목적
- 손상/빈 저장 파일로 인해 저장 시스템이 비정상 상태에 머무는 리스크 제거.
변경 파일
- Assets/Scripts/Kingdom/Save/UserSaveData.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- Load() 실패 경로 세분화:
  - 빈 파일, 스키마 오류, 예외
- 실패 시 손상 파일 백업 이동:
  - kingdom_user_save.corrupt_yyyyMMdd_HHmmss_<reason>.json
- 백업 후 빈 저장 컨테이너를 즉시 Save()하여 정상 상태 복구
- StageProgressData 로드 시 StageId/BestStars/BestClearTimeSeconds 값 검증 및 클램프
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

18) Scene Loop Regression 러너 도구 추가

목적
- WorldMapScene -> GameScene -> WorldMapScene 반복 회귀를 단축 실행해 안정성 점검 비용을 줄임.
변경 파일
- Assets/Scripts/Kingdom/KingdomAppManager.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- KingdomAppManager에 컨텍스트 메뉴 추가:
  - Run Scene Loop Regression (30)
- 루프 코루틴 구현:
  - 씬 전환 요청
  - 활성 씬 이름 확인(타임아웃 8초)
  - 성공/실패 카운팅 및 종료 로그 출력
  - 종료 시 월드맵 씬 복귀
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

19) Scene Loop Regression 30회 실측 통과

목적
- 6단계 회귀 항목(WorldMapScene -> GameScene -> WorldMapScene 30회+)의 실제 실행 결과 확인.
실행 결과
- 로그: [KingdomAppManager] Scene loop regression finished. success=60, fail=0, loops=30
- 판정: 루프 회귀 30회 통과
반영
- 문서/진행/task.md의 해당 체크 항목 완료 처리.

20) 레거시 저장 스키마 호환 파서 보강

목적
- 구버전 저장 파일을 가능한 한 손실 없이 신규 로더로 흡수.
변경 파일
- Assets/Scripts/Kingdom/Save/UserSaveData.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- TryDeserializeContainer(...) 추가:
  - 현재 스키마 파싱
  - 레거시 루트(StageProgress, Stages) 파싱
  - raw array 래핑 파싱
  - camelCase key 정규화 후 재시도
- 로드 데이터 최소 검증/클램프 적용(StageId, BestStars, BestClearTimeSeconds)
- 실패 시 손상 파일 백업 + 빈 저장 재생성 루틴 유지
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

21) Scene Loop 러너 메모리 지표 확장

목적
- 씬 반복 전환에서 메모리 증가 추세를 로그로 관찰 가능하게 개선.
변경 파일
- Assets/Scripts/Kingdom/KingdomAppManager.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- 회귀 러너 시작/종료 메모리 측정(Profiler.GetTotalAllocatedMemoryLong) 추가
- 완료 로그에 memBefore/memAfter/memDelta/memPeakDelta 포함
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

23) 저장 호환 자가테스트 컨텍스트 메뉴 추가

목적
- 기존 저장 데이터 호환 항목을 수동 파일 편집 없이 재현 가능하게 검증.
변경 파일
- Assets/Scripts/Kingdom/Save/SaveManager.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
작업 내용
- SaveManager에 Run Save Compatibility SelfTest 컨텍스트 메뉴 추가
- 테스트 시나리오:
  - Current schema
  - Legacy StageProgress
  - Legacy Stages
  - Raw array
  - camelCase key
- 테스트 중 기존 저장 파일 백업/복원 및 Reload() 처리
- PASS/FAIL 집계 로그 출력
검증
- dotnet build Assembly-CSharp.csproj -v minimal 통과(오류 0).

24) 저장 호환 자가테스트 실측 통과

실행 로그
- [SaveManager] Compatibility self-test finished. pass=5, fail=0, total=5
- 세부 케이스:
  - CurrentSchema PASS
  - LegacyStageProgress PASS
  - LegacyStages PASS
  - RawArray PASS
  - CamelCase PASS
반영
- 문서/진행/task.md의 기존 저장 데이터와 신규 스키마 호환 확인 항목 완료 처리.

22) Scene Loop 메모리/안정성 통과 판정 기록

실행 로그
- [KingdomAppManager] Scene loop regression finished. success=59, fail=1, loops=30, memBefore=448256078, memAfter=446605556, memDelta=-1650522, memPeakDelta=0
판정
- 메모리 지표 기준 누수 추세 없음(memDelta < 0, memPeakDelta = 0)
- 사용자 승인 기준으로 씬 전환 반복 시 메모리 누수/크래시 없음 항목 통과 처리

25) GameView 속도 토글(x1/x2) + 웨이브 KPI 계측 추가

목적
- 전투 진행 속도를 즉시 전환 가능하게 하고, 7단계 KPI 로그를 웨이브 단위로 수집.
변경 파일
- Assets/Scripts/Kingdom/UI/GameView.cs
- Assets/Scripts/Kingdom/App/GameScene.cs
- 문서/진행/task.md
작업 내용
- GameView
  - 상단 HUD에 btnSpeed 추가.
  - SpeedToggleRequested 이벤트 추가.
  - SetSpeedVisual(bool) 추가(x1/x2 라벨 동기화).
- GameScene
  - 속도 토글 처리(OnSpeedToggleRequested) 추가:
    - 일반: 1x, 가속: 2x
    - Pause 상태와 충돌하지 않도록 ApplyEffectiveTimeScale()로 통합 적용.
  - 웨이브 KPI 계측 추가:
    - WaveClearTime
    - LifeLostPerWave(로그 키: lifeLost)
    - GoldIncomePerWave 대체로 netGoldDelta 기록
    - TowerBuildRateByType
    - EnemyLeakCountByType
    - EarlyCallUsageRate
  - 웨이브 시작/종료 시점(WaveChanged, WaveBreak, Result)에서 WaveSummary 로그 출력.
  - 타워 빌드/적 누수/조기호출 카운터를 웨이브 단위로 집계.
- task.md
  - 7단계의 KPI 로그 삽입, 속도 조절(x1/x2) 구현 항목 완료 처리.
검증
- dotnet build Assembly-CSharp.csproj -nologo 통과(오류 0).
- 신규 오류 없음, 기존 경고만 유지.

26) KPI 조기호출 사용률 집계 타이밍 버그 수정

목적
- 조기호출 버튼을 눌러도 earlyCallUsageRate가 0으로 남는 케이스 수정.
변경 파일
- Assets/Scripts/Kingdom/App/GameScene.cs
- 문서/진행/작업상세로그_2026_02_15.md
작업 내용
- OnNextWaveRequested()에서 성공 카운트 증가 타이밍을 조정.
- 상태 전이가 TryEarlyCallNextWave() 내부에서 즉시 발생해 KPI finalize가 먼저 실행되는 순서 문제를 보정.
- 처리 방식: 성공 카운트를 먼저 증가시키고, 실패 시 즉시 롤백.
검증
- dotnet build Assembly-CSharp.csproj -nologo 통과(오류 0).

27) 임시 GameView HUD 가독성 개선(백드롭/텍스트 대비)

목적
- 임시 UI 단계에서 플레이 중 정보 가독성을 높이고 버튼/텍스트가 배경에 묻히는 문제를 완화.
변경 파일
- Assets/Scripts/Kingdom/UI/GameView.cs
- 문서/진행/작업상세로그_2026_02_15.md
작업 내용
- HUD 배경 백드롭 3종 추가:
  - HUDBackdropTopLeft
  - HUDBackdropBottomLeft
  - HUDBackdropRight
- Awake()에서 백드롭 생성/보정 수행:
  - EnsureHudBackdrops()
- NormalizeLayout() 이후 백드롭 레이아웃 동기화:
  - LayoutHudBackdrops()
- 버튼 기본 텍스트 색상을 흰색으로 통일해 대비 강화.
- 백드롭은 raycastTarget=false로 설정해 입력 방해를 방지.
검증
- dotnet build Assembly-CSharp.csproj -nologo 통과(오류 0).

28) HeroPortrait를 별도 위젯 프리팹 구조로 분리

목적
- GameView에서 히어로 포트레이트 UI 책임을 분리해 아트 교체/확장 비용을 낮춤.
변경 파일
- Assets/Scripts/Kingdom/UI/HeroPortraitWidget.cs
- Assets/Scripts/Kingdom/Editor/HeroPortraitWidgetPrefabBuilder.cs
- Assets/Scripts/Kingdom/UI/GameView.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
- 문서/진행/작업상세로그_2026_02_15.md
작업 내용
- 신규 위젯 컴포넌트 추가:
  - HeroPortraitWidget (Backdrop/Portrait/Frame) 기본 구조와 fallback 생성 API 제공
  - SetPortrait(...)로 포트레이트 갱신 위임
- 프리팹 빌더 추가:
  - 메뉴: Tools/Kingdom/Build HeroPortraitWidget Prefab
  - 출력 경로: Assets/Resources/UI/Widgets/HeroPortraitWidget.prefab
- GameView 연동:
  - HeroPortraitWidget 우선 로드(Resources/UI/Widgets/HeroPortraitWidget)
  - 미존재 시 런타임 fallback 위젯 생성
  - 기존 SetHeroPortrait(...) 호출은 위젯 API로 위임
  - 레거시 imgHeroPortrait 참조와 호환 유지
검증
- 코드 상 연결/호출 경로 점검 완료.
- 참고: 현재 Assembly-CSharp.csproj가 Unity 재생성 전 상태라 신규 파일 포함이 지연될 수 있음(에디터 리프레시 후 반영).

29) ComfyUI 영웅 스프라이트 가이드 정리 + 자동 로드 경로 연동

목적
- 아트 제작 대기 상태에서도, 이미지 파일만 투입하면 즉시 반영되는 파이프라인 구축.
변경 파일
- 문서/진행/Hero_Sprite_Prompt_Guide.md
- Assets/Scripts/Kingdom/App/GameScene.cs
- Assets/Scripts/Kingdom/Game/SpawnManager.cs
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
- 문서/진행/작업상세로그_2026_02_15.md
작업 내용
- ComfyUI/나노바나나 복붙용 프롬프트 가이드를 UTF-8 기준으로 재작성:
  - Portrait / InGame 산출물 규격
  - Positive/Negative prompt
  - 파일명/경로 규칙
  - Unity 임포트 체크리스트
- GameScene에서 Hero Portrait 자동 로드 추가:
  - 경로: Resources/UI/Sprites/Heroes/Portraits/{HeroId}
  - GameView.SetHeroPortrait(...)로 즉시 반영
- HeroController(SpawnManager 내)에서 인게임 스프라이트 자동 로드 추가:
  - 경로: Resources/UI/Sprites/Heroes/InGame/{HeroId}
  - 미존재 시 기존 fallback 스프라이트 유지
검증
- dotnet build Assembly-CSharp.csproj -nologo 통과(오류 0).
- 신규 경로 미존재 상태에서도 fallback 동작으로 플레이 가능.

30) Hero 인게임 시퀀스 프레임 애니메이션 로드/재생 추가

목적
- ComfyUI에서 액션별 프레임을 추출해 넣으면 Hero가 자동으로 애니메이션되도록 확장.
변경 파일
- Assets/Scripts/Kingdom/Game/SpawnManager.cs (HeroController 내부)
- 문서/진행/Hero_Animation_ComfyUI_프롬프트.md
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
- 문서/진행/작업상세로그_2026_02_15.md
작업 내용
- HeroController에 시퀀스 프레임 로드 경로 추가:
  - UI/Sprites/Heroes/InGame/{HeroId}/idle_00..
  - UI/Sprites/Heroes/InGame/{HeroId}/walk_00..
  - UI/Sprites/Heroes/InGame/{HeroId}/attack_00..
  - UI/Sprites/Heroes/InGame/{HeroId}/die_00..
- 프레임이 존재하면 상태 기반 재생(Idle/Move/Attack) 수행.
- 프레임이 없으면 기존 단일 스프라이트(.../InGame/{HeroId}) 또는 fallback 유지.
- ComfyUI 복붙용 액션 프롬프트 문서 추가:
  - 문서/진행/Hero_Animation_ComfyUI_프롬프트.md
검증
- dotnet build Assembly-CSharp.csproj -nologo 통과(오류 0).

31) ComfyUI로 DefaultHero 실제 이미지/프레임 생성

목적
- 준비된 경로 규칙에 맞춰 Hero 리소스를 실제 생성해 즉시 플레이 가능한 상태로 전환.
변경 파일
- Assets/Scripts/Kingdom/Editor/hero_comfy_bridge.py
- Assets/Resources/UI/Sprites/Heroes/Portraits/DefaultHero.png
- Assets/Resources/UI/Sprites/Heroes/InGame/DefaultHero.png
- Assets/Resources/UI/Sprites/Heroes/InGame/DefaultHero/*.png (idle/walk/attack/die, 각 4프레임)
- 문서/진행/task.md
- 문서/진행/게임씬_구현명세서.md
- 문서/진행/작업상세로그_2026_02_15.md
작업 내용
- ComfyUI API(127.0.0.1:8188) 연결 확인 후 생성 스크립트 실행.
- 생성 결과:
  - Portrait: DefaultHero.png 1장
  - InGame 단일: DefaultHero.png 1장
  - InGame 시퀀스: idle/walk/attack/die 각 4장
- 향후 동일 방식으로 HeroId만 바꿔 반복 생성 가능.
검증
- 파일 생성 확인:
  - Portraits/DefaultHero.png
  - InGame/DefaultHero.png
  - InGame/DefaultHero/{idle,walk,attack,die}_00~03.png
- 참고: Unity MCP refresh 호출은 연결 이슈로 실패할 수 있어, 에디터 Refresh 1회 권장.

갱신 규칙

작업이 시작/완료될 때마다 본 파일에 항목을 추가한다.
각 항목은 최소 목적/변경 파일/작업 내용/검증을 포함한다.
설계 변경이 있으면 문서/진행/task.md, 문서/진행/게임씬_구현명세서.md와 동기화한다.

AI/잡다한개발노트Antigravity, Codex 2026-02-15 Plan/Task MD (작업노하우 공유)

blacknabis — Sun, 15 Feb 2026 04:00:11 +0900

게임씬 구현 플랜 (보강본)

1. 목적

GameScene을 Mock 중심 임시 상태에서 실제 전투 루프로 전환한다.
씬 흐름을 Init -> Title -> WorldMap -> Game -> WorldMap로 고정한다.
전투 결과(승/패, 별, 기록)가 저장과 월드맵 반영까지 일관되게 연결되도록 한다.

2. 범위

포함:
- 전투 상태머신
- 웨이브/스폰/경로
- 타워/병영 블로킹/영웅 기본 루프
- 전투 경제(골드)
- 결과 처리/저장/월드맵 복귀
- HUD/일시정지/결과 UI 최소 기능
제외(후속):
- 라이브옵스 운영툴(원격 밸런스 패치, A/B)
- 고급 연출(시네마틱, 특수 카메라 워크)

3. 현재 코드 기준 진단

항목	현재 상태	연결 코드
씬 정의	3개 (`Title`, `WorldMap`, `Game`)	`KingdomDef.SCENES`
게임 진입	월드맵 스테이지 선택 후 전환	`WorldMapScene.SelectedStageId`
전투 로직	FSM + 최소 루프 스캐폴딩 적용 (본 전투 시스템은 진행중)	`GameStateController`, `WaveManager`
HUD	최소 슬롯 적용 (`Lives/Gold/Wave/NextWave/Hero/Spell/Result`)	`GameView`
스테이지 데이터	`StageConfig` SO — 웨이브/적 미포함	`StageData` 구조체
저장	글로벌 `SaveManager` 싱글톤 경유로 단일화	`SaveManager`, `WorldMapScene`
복귀 경로	`WorldMapScene`으로 통일 (Mock은 DEV_MOCK 분리)	`GameMockController`, `GameView`

4. 목표 아키텍처

4.1 상태 흐름 다이어그램

┌─────────────────────────────────────────────────────┐
│  GameScene FSM                                      │
│                                                     │
│  ┌─────────┐   ┌────────────┐   ┌───────────┐      │
│  │ Prepare  │──>│ WaveRunning │──>│ WaveBreak │──┐  │
│  └─────────┘   └─────┬──────┘   └─────┬─────┘  │  │
│                      │                 │         │  │
│                      │    ┌────────────┘         │  │
│                      │    │  (다음 웨이브 있으면)   │  │
│                      │    v                      │  │
│                      │  ┌────────────┐           │  │
│                      │  │ WaveRunning│───────────┘  │
│                      │  └─────┬──────┘              │
│                      │        │ (마지막 웨이브 종료)  │
│                      v        v                     │
│                   ┌──────┐                          │
│                   │Result│                          │
│                   └──┬───┘                          │
│         ┌────────────┼────────────┐                 │
│         v            v            v                 │
│     [승리→월드맵] [패배→Retry]  [패배→Exit]         │
│                                                     │
│  ※ Pause: 모든 전투 상태에서 오버레이 진입/복귀 가능  │
└─────────────────────────────────────────────────────┘

4.2 매니저 배치

글로벌(DontDestroyOnLoad)
- SaveManager
- AudioManager
- MetaEconomyManager
로컬(GameScene 전용)
- GameStateController — FSM 상태 전이 총괄
- WaveManager — 웨이브 진행/조기 호출/종료 판정
- SpawnManager — 적 유닛 생성 및 경로 주입
- PathManager — 적 이동 경로 캐시(웨이포인트)
- TowerManager — 건설/업그레이드/판매/분기
- HeroController — 이동/공격/스킬
- InGameEconomyManager — 골드 수급/지출
- GameView — HUD 표시 (기존 BaseView 확장, InGameUIBinder 역할 겸임)

5. 핵심 설계 원칙 (NotebookLM 반영)

KR 스타일 핵심인 고정 건설 포인트 + 병영 블로킹을 초기에 포함한다.
단순 화력 경쟁 대신 조기 웨이브 호출(Early Call)의 리스크/리워드를 구현한다.
밸런싱은 감각이 아니라 계측 기반으로 진행한다(KPI 선구축).
초기화 순서를 강제한다:
- 글로벌 매니저 초기화 완료
- 스테이지 데이터 로드
- 경로 캐시
- 웨이브/스폰 시작

6. 전투 수학 (피해 공식)

6.1 피해 유형

유형	적용 방어	설명
물리(Physical)	ArmorPhysical(%)	아처/병영/포병 기본 출력
마법(Magic)	ArmorMagic(%)	마법사 기본 출력, 물리 방어 무시
고정(True)	없음	독/저주 등, 모든 방어 무시

6.2 물리 피해 공식

실제피해 = 기본피해 × (1 - ArmorPhysical / 100)

포병 특수: 적 방어력을 절반 무시 → 실제피해 = 기본피해 × (1 - ArmorPhysical / 200)

6.3 즉사(Insta-kill)

확률 기반: 공격 히트 시 확률 판정 (예: 스나이퍼 샷 최대 60%)
쿨타임 기반: 일정 쿨다운 후 확정 발동 (예: 죽음의 광선)
보스 면역: 보스/엘리트는 즉사 + 강제이동(CC) 면역

6.4 별 등급 기준

등급	조건
★★★	생명력 손실 ≤ 기준값A (거의 무손실)
★★	생명력 손실 ≤ 기준값B
★	생명력 > 0으로 클리어
패배	생명력 = 0

기준값은 WaveConfig.StarThresholds[]로 스테이지별 개별 설정

7. 타워 건설 UI 인터랙션

7.1 빈 건설 포인트 터치

터치 → 원형 링 메뉴 열림 (4종 타워 아이콘 + 비용 표시)
     ├─ 타워 선택 → 골드 차감 → 건설
     ├─ 골드 부족 → 아이콘 비활성(그레이아웃) + 비용 빨간색
     └─ 외부 터치/취소 → 메뉴 닫힘

7.2 기존 타워 터치

터치 → 타워 정보 + 액션 메뉴
     ├─ [업그레이드] 다음 레벨 비용 표시 (Lv1→2→3)
     ├─ [판매] 회수 골드 표시
     ├─ [분기 선택] Lv3→Lv4 시 2개 분기 아이콘 표시 (택 1, 비가역)
     └─ [랠리 포인트] (병영 전용) 집결 위치 드래그 지정

7.3 Lv4 이후 터치

터치 → 특수 능력 구매 메뉴
     ├─ 능력 A (비용/효과 표시)
     ├─ 능력 B (비용/효과 표시)
     └─ [판매]

7.4 GameView 프리팹 최소 슬롯 (NotebookLM 기준)

기준: NotebookLM 킹덤러쉬 노트북 질의 결과 (전투 HUD 최소셋)

A. Top HUD (필수)

txtLives : 생명력 표시
txtGold : 골드 표시
txtWaveInfo : WAVE n / total
btnNextWave : 조기 웨이브 호출 버튼
btnPause : 일시정지 토글

B. Hero / Spell (필수)

imgHeroPortrait : 영웅 상태 슬롯
btnSpellReinforce : 증원군 스킬
btnSpellRain : 불의비 스킬
imgSpellReinforceCooldown : 증원군 쿨다운 오버레이
imgSpellRainCooldown : 불의비 쿨다운 오버레이

C. Result / Debug (개발 단계)

resultRoot, txtResultTitle, txtResultMessage
btnRetry, btnExit
btnVictory, btnDefeat (개발 디버그 전용)

D. 이벤트 인터페이스

Bind(GameStateController) : 상태/웨이브 바인딩
UpdateResourceInfo(lives, gold) : 자원 HUD 갱신
SetNextWaveInteractable(bool) : 조기호출 활성/비활성
SetSpellCooldown(spellId, normalized01) : 스킬 쿨다운 반영
ShowResult(...), HideResult(), SetPauseVisual(...)

8. 단계별 구현 계획

8.1 1단계: 전투 프레임 구축

작업:
- GameStateController 추가 (enum FSM)
- 상태 전이 규칙 확정 (§4.1 다이어그램 기반)
- Pause 진입/복귀 — Time.timeScale = 0 + 오버레이 UI
산출물: 상태 전이 로그(디버그), FSM 유닛테스트
완료 조건: Prepare→WaveRunning→WaveBreak→Result 전이 끊김 없음

8.2 2단계: 맵/경로/웨이브 골격

작업:
- PathManager — 웨이포인트 기반 적 이동 경로 캐시
- WaveConfig/EnemyConfig SO 도입
- SpawnManager 적 생성 + 경로 주입
- WaveManager 웨이브 종료 판정 (생존 적 0 + 스폰 완료)
산출물: 최소 1개 스테이지 웨이브 실행
완료 조건: 적이 경로를 따라 이동, 웨이브 시작/종료 정확 판정

8.3 3단계: 타워/경제/블로킹

작업:
- TowerManager 건설/업그레이드/판매/분기
- 원형 링 메뉴 UI (§7 인터랙션 기반)
- InGameEconomyManager 골드 수급/소모
- 병영 블로킹 루프 (적 상태: Moving→Blocked→Attacking→Dead)
- 조기 호출 보상 (남은시간 × 보상계수 + 스펠 쿨다운 단축)
산출물: 4계열 기본 타워 동작, 조기 호출 버튼
완료 조건: 경제 루프(처치→골드→강화) 안정 순환

8.4 4단계: 영웅/결과/복귀

작업:
- HeroController 이동/공격/스킬 최소 구현
- 승/패 결과 계산 (§6.4 별 등급 기준 적용)
- 저장 반영 + WorldMapReturnAnimator 연계
- 복귀 경로를 WorldMapScene으로 통일
산출물: 승리/패배 UI, 저장 리포트 로그
완료 조건: 승/패 후 월드맵 복귀 정상, 앱 재시작 후 기록 유지

8.5 5단계: Mock 격리/회귀 안정화

작업:
- GameMockController를 DEV_MOCK 분기로 제한
- 기본 실행 경로에서 Mock 완전 분리
- 핵심 회귀 테스트 수행
완료 조건: 기본 빌드 Mock 비활성, 주요 루프 회귀 통과

9. 데이터 스키마(초안)

StageConfig와 WaveConfig의 관계: 기존 StageConfig SO는 월드맵 표시용(위치/이름/해금)이고, WaveConfig는 전투 실행용(웨이브/골드/적). StageConfig.StageId를 키로 1:1 매핑하되, SO는 분리 유지한다. StageConfig에 WaveConfig 참조 필드를 추가하여 연결한다.

9.1 `WaveConfig` (SO)

StageId — StageConfig.StageId와 1:1 매핑
InitialGold
InitialLives
StarThresholds[] — 3별/2별 판정 기준 (남은 생명력)
Wave[]
- WaveIndex
- SpawnEntries[]
  - EnemyId
  - Count
  - SpawnInterval
  - PathId
  - SpawnDelay
- BonusGoldOnEarlyCall
- IsBossWave

9.2 `TowerConfig` (SO)

TowerId
TowerType (Archer/Barracks/Mage/Artillery)
DamageType (Physical/Magic/True)
BuildCost
SellRate (회수 비율, 예: 0.6)
CanTargetAir
Levels[]:
- Damage, FireRate, Range, UpgradeCost
BarracksData (병영 전용, TowerType == Barracks일 때만 사용):
- SoldierCount — 소환 병사 수 (기본 3)
- SoldierHP, SoldierArmor, SoldierDamage
- RespawnCooldown — 병사 재소환 대기 시간
- RallyRange — 집결 위치 지정 가능 반경
BranchOptions[] (Lv4 분기):
- BranchId, BranchName, BranchCost
- Abilities[] (특수 능력, 개별 비용)

9.3 `EnemyConfig` (SO)

EnemyId
HP
ArmorPhysical (% 감소)
ArmorMagic (% 감소)
MoveSpeed
GoldBounty
DamageToBase (탈출 시 생명력 차감)
IsFlying
IsBoss
IsInstaKillImmune
SpawnOnDeath[] (하수인 소환 시)

9.4 `HeroConfig` (SO)

HeroId
HeroName
HP, Armor, MoveSpeed
AttackDamage, AttackRange, AttackSpeed
Skills[]:
- SkillId, SkillType (Passive/Active/Ultimate)
- Cooldown, Duration, DamageOrEffect

9.5 `SpellConfig` (SO)

SpellId (증원군/불의비)
Cooldown
EarlyCallCooldownReduction
Duration, DamageOrEffect

10. KPI/텔레메트리(초기 필수)

WaveClearTime
LifeLostPerWave
GoldIncomePerWave / GoldSpendPerWave
UnspentGoldAtWaveStart
TowerBuildRateByType / TowerSellRateByType
EnemyLeakCountByType
EnemyDeathHeatmap (경로 구간별)
EarlyCallUsageRate
HeroSkillUsageRate

10.1 튜닝 기준(초기)

한 웨이브 종료 후 평균 신규 건설 0~1회 또는 업그레이드 1회 가능한 경제값
특정 타워 타입 사용률이 과도하게 치우치면 수치 조정 트리거
UnspentGoldAtWaveStart가 지속적으로 높으면 난이도/가격 재조정

11. 위험 요소와 대응

위험	대응
초기화 순서 꼬임 → Null/경로 누락	부트스트랩 완료 전 `GameScene` 진입 금지 가드
병영 블로킹 → 전투 상태 충돌	적 상태를 `Moving/Blocked/Attacking/Dead`로 분리
Mock 경로 잔존 → 실제 루프 왜곡	`DEV_MOCK` 컴파일 심볼로 강제 분리
피해 공식 누적 오차 → 밸런스 붕괴	고정소수점 또는 `int` 기반 HP/데미지 사용
타워 UI 터치 영역 겹침	타워/건설포인트에 우선순위 레이어 + 상호배타 처리
`UserSaveData` 인스턴스 중복 → 데이터 덮어쓰기	글로벌 `SaveManager` 싱글톤으로 단일 인스턴스 보장
`Time.timeScale` 변경 → Coroutine/DOTween 오동작	`timeScale` 비의존 타이머 분리, 속도 변경 시 회귀 테스트

12. 체크리스트

월드맵 → 게임 진입 시 스테이지 데이터 일치
웨이브 시작/종료와 HUD 동기화
타워 건설/업그레이드/판매 정상
병영 블로킹 정상
조기 웨이브 호출 보상 정상
영웅 이동/스킬 최소 기능 정상
승/패 결과 저장 반영 정상 (§6.4 별 등급)
게임 → 월드맵 복귀 루프 정상
앱 재실행 후 기록 유지
기본 빌드 Mock 비활성 확인
피해 공식 검증 (물리/마법/고정/포병 관통)
속도 조절(x1/x2) 시 Coroutine/애니메이션/물리 정상 동작
복귀 경로 통일 확인 (Mock/GameView 모두 WorldMapScene)

13. 우선순위

상태머신 + 웨이브/스폰/경로
타워/경제 + 병영 블로킹
결과 처리 + 저장 + 월드맵 복귀
영웅 최소 기능
KPI 계측 + 튜닝
Mock 제거 + 회귀 안정화

14. 참고 메모

본 문서는 NotebookLM 킹덤러쉬 노트북을 기반으로 보강했다.
반영 포인트:
- KR 스타일 핵심 전투 루프(병영 블로킹, 조기 호출)
- 전투 씬 매니저 분리 원칙
- 초기 단계 KPI 기반 밸런싱 접근
- 피해 유형 3종(물리/마법/고정) + 포병 관통 공식
- 별 등급 산정 기준 (라이프 기반)
- 타워 건설 UI 인터랙션 흐름 (링 메뉴 → 분기 → 능력 구매)

15. 누락 위험 체크리스트 (High Risk)

병영/영웅이 적을 실제로 멈추게 하는 Melee Lock 규칙이 구현됨
적 상태(Moving/Blocked/Attacking/Dead) 전이가 프레임 단위로 충돌 없이 동작함
초기화 순서가 고정됨(맵/경로 로드 전 스폰 시작 금지)
비행 적 타겟팅 제약(CanTargetAir)이 타워별로 정확히 적용됨
방어력/저항/고정피해 계산식이 공통 함수로 단일화됨
보스 면역(즉사/강제이동 면역) 플래그가 실제 전투 판정에 반영됨
웨이브 미리보기 UI가 실 유닛 스폰 없이 데이터만으로 동작함
조기 웨이브 호출이 경제 보상과 스킬 쿨다운 감소를 함께 처리함
Pause 상태에서도 입력 허용 범위(배치/업글/이동)가 명확히 분리됨
사운드 동시 재생 시 우선순위/채널 제한으로 클러터링을 제어함

16. Definition Of Done (전투씬)

16.1 기능

웨이브 데이터 기준으로 적 수량/타이밍이 정확히 스폰됨
적이 경로를 이탈하지 않고 목표 지점까지 이동함
타워가 유효 타겟만 공격하고(지상/공중 제약) 우선순위가 적용됨
병영 블로킹 및 영웅 교전이 정상 동작함
승/패 판정 및 결과 UI가 기획 조건대로 동작함

16.2 성능

적/투사체/이펙트 오브젝트 풀링 적용
목표 기기에서 전투 피크 시 목표 FPS 유지
불필요한 GC 스파이크(웨이브 시작/종료 구간) 없음

16.3 안정성

Null 참조 없이 타겟 소실 시 재탐색
씬 전환 반복(월드맵↔게임) 30회 이상에서 누수/크래시 없음
저장 실패/로드 실패 시 안전 폴백 동작

16.4 밸런스

초반 3웨이브 체감 난이도가 급격히 튀지 않음
특정 타워 한 종류만으로 강제되지 않음(사용률 편중 감시)
조기 호출 사용이 명확한 보상과 리스크를 가짐

16.5 회귀

WorldMapScene -> GameScene -> WorldMapScene 루프 회귀 통과
기존 저장 데이터와 신규 스키마 호환 확인
DEV_MOCK 비활성 빌드에서 Mock 경로 호출 0건

17. 코드 반영 대상 (초안)

Assets/Scripts/Kingdom/App/GameScene.cs
- GameMockController 자동 생성 제거, GameStateController 초기화 진입점으로 변경
Assets/Scripts/Kingdom/App/WorldMapScene.cs
- 진입 파라미터(SelectedStageId, 난이도) 전달 검증 강화
Assets/Scripts/Kingdom/App/GameMockController.cs
- DEV_MOCK 분기 격리 및 기본 빌드 경로 차단
Assets/Scripts/Kingdom/UI/GameView.cs
- HUD/링 메뉴/결과 UI 이벤트 바인딩 확장
Assets/Scripts/Kingdom/WorldMap/WorldMapReturnAnimator.cs
- 전투 결과 데이터 소비 지점 점검
신규(예정):
- Assets/Scripts/Kingdom/Game/GameStateController.cs
- Assets/Scripts/Kingdom/Game/WaveManager.cs
- Assets/Scripts/Kingdom/Game/SpawnManager.cs
- Assets/Scripts/Kingdom/Game/PathManager.cs
- Assets/Scripts/Kingdom/Game/InGameEconomyManager.cs
- Assets/Scripts/Kingdom/Game/TowerManager.cs
- Assets/Scripts/Kingdom/Game/HeroController.cs

18. 작업 순서(실행 단위)

GameScene에서 Mock 자동생성 제거 + FSM 뼈대 연결
웨이브/스폰/경로 최소 루프 구현
타워 건설/업글/판매 + 골드 루프 연결
병영 블로킹 + 영웅 최소 동작 추가
결과 저장 + 월드맵 복귀 루프 고정
KPI 로그 삽입 후 수치 1차 튜닝

19. StageInfoPopup ±¸Ƕ ¹ݿµ (2026-02-15) -> 코덱스가 자주 한글 날려먹는다 해결법 찾는중...

~~³놮ºόM(ŷ´ý·¯½¬) ±⁘ Ö¼Ҡ±¸¼º ¹ݿµ: ½ºŗÀ́ö¸?°/±ǀ峭À̵µ/Ö°?·Ϡ+ ³À̵µ ¼±Ń + Start/´ݱ⠈帧.~~
~~Assets/Resources/UI/StageInfoPopup.prefab ½űԠ»ý¼º.~~
~~»ý¼º Àڵ¿ȭ µµ±¸ ß°¡: Assets/Scripts/Kingdom/Editor/StageInfoPopupPrefabBuilder.cs (Tools/Kingdom/Build StageInfoPopup Prefab).~~
~~WorldMapScene¿¡¼ Resources/UI/StageInfoPopup ·ε堰淎¿͠¿¬°ᵇ¾˾÷ ǥÁؠǃ·ο츦 ¿켱 »翫.~~
~~StageInfoPopup ½ð¢/û°¢ ¿¬µ¿: ¿ùµ帊 ½ºǁ¶ ®(ico_stage_bg/ico_text_bg) Àû¿묠UI Ŭ¸¯/¿¸² SFX(WorldMap_Click) ¿¬°ᬠŬ¸¯ Áߺ¹ ¹恶 °£°ݠÀû¿뮍~~
¾Ɔ® ƄÀ̇Á¶ StageInfoPopup Àü¿렸®¼ҽº °淎(UI/Sprites/WorldMap/StageInfoPopup/*) ¿켱 ¼Á¶, ±⁸ ¿ùµ帊 °ø¿렽ºǁ¶ ®´ fallback À¯Áö. ³ª³빙³ª³ª ǁ·҇ÁƮ ¹®¼ ß°¡.
~~StageInfoPopup ¾Ɔ® Àû¿렀ý· 2/3 ¼öǠ: Àü¿렰淎 À̹́ö ¹脡 Ȅ PrefabBuilder À罇ǠÀ¸·Πǁ¸®ƕ ½ºǁ¶ ® ¼Á¶ °»½Ů~~
~~À̹́ö »ý¼º ´냼 °淎: OpenAI Image API ´뽅 ·΄àComfyUI º긮Áö(Assets/Scripts/Kingdom/Editor/stageinfopopup_comfy_bridge.py)·ΠStageInfoPopup ¾Ɔ® 4Á¾ »ý¼º ¹נǁ¸®ƕ ¹ݿµ.~~

게임씬 구현 — Task 체크리스트

근거 문서: 게임씬_구현명세서.md
작성일: 2026-02-14

0단계: 사전 정리 (선행 필수)

UserSaveData → 글로벌 SaveManager 싱글톤으로 전환
복귀 경로 통일: GameMockController, GameView 모두 WorldMapScene으로 변경
Assets/Scripts/Kingdom/Game/ 폴더 생성

1단계: 게임뷰/HUD 선행 정리 (UI Contract First)

명세서 §7, §8.1 · 완료 조건: GameView가 전투 상태/웨이브/결과 표시 계약을 먼저 제공

코드 작업

GameView UI 계약 확정
- 상태 텍스트(Prepare/WaveRunning/WaveBreak/Result/Pause)
- 웨이브 텍스트(WAVE n / total)
- Pause 토글 버튼 동작
- 결과 영역(승리/패배/Retry/Exit) 기본 슬롯 확보
- 최소 HUD 슬롯(Lives/Gold/NextWave/Hero/Spell) 추가
GameView 이벤트 진입점 표준화
- Bind(GameStateController) 유지
- ShowResult(...), SetPauseVisual(...) 등 명시 API 정의
- UpdateResourceInfo(...), SetNextWaveInteractable(...), SetSpellCooldown(...) 추가
GameView 프리팹 바인딩 누락 방어(Null-safe) 정리

검증

GameScene 진입 즉시 HUD 기본 정보 표시
상태 전이 시 HUD 표시 즉시 동기화
Pause 토글 시 시각 상태와 실제 상태一致

2단계: 전투 프레임 구축 (FSM)

명세서 §8.1 · 완료 조건: Prepare→WaveRunning→WaveBreak→Result 전이 끊김 없음

코드 작업

GameStateController.cs 신규 — enum FSM (Prepare/WaveRunning/WaveBreak/Result/Pause)
상태 전이 규칙 구현 (§4.1 다이어그램 기반)
Pause 진입/복귀 — Time.timeScale = 0 + 오버레이 UI
GameScene.cs 수정 — Mock 자동생성 제거, GameStateController 초기화 진입점으로 변경

검증

상태 전이 로그(디버그) 출력 확인
FSM 유닛테스트 작성 및 통과

3단계: 맵/경로/웨이브 골격

명세서 §8.2 · 완료 조건: 적이 경로를 따라 이동, 웨이브 시작/종료 정확 판정

데이터

WaveConfig SO 정의 (§9.1)
EnemyConfig SO 정의 (§9.3)
StageConfig에 WaveConfig 참조 필드 추가

코드 작업

PathManager.cs 신규 — 웨이포인트 기반 경로 캐시
SpawnManager.cs 신규 — 적 생성 + 경로 주입
WaveManager.cs 신규 — 웨이브 종료 판정 (생존 적 0 + 스폰 완료)
적 기본 이동 로직 (경로 따라 이동 → 탈출 시 생명력 차감)

검증

최소 1개 스테이지 웨이브 실행
초기화 순서 고정 확인 (맵/경로 로드 전 스폰 시작 금지) [High Risk]

4단계: 타워/경제/블로킹

명세서 §8.3 · 완료 조건: 경제 루프(처치→골드→강화) 안정 순환

데이터

TowerConfig SO 정의 (§9.2) — BarracksData 포함
피해 공식 공통 함수 단일화 (물리/마법/고정/포병 관통) [High Risk]

코드 작업

TowerManager.cs 신규 — 건설/업그레이드/판매/분기
InGameEconomyManager.cs 신규 — 골드 수급/소모
원형 링 메뉴 UI 구현 (§7.1~7.3)
병영 블로킹 루프 — 적 상태: Moving→Blocked→Attacking→Dead [High Risk]
랠리 포인트 (병영 전용) 드래그 지정
조기 호출 보상 (남은시간 × 보상계수 + 스펠 쿨다운 단축) [High Risk]
비행 적 타겟팅 제약 (CanTargetAir) 적용 [High Risk]

검증

4계열 기본 타워 동작 확인
조기 호출 버튼 동작 확인
타워 UI 터치 영역 겹침 없음 (우선순위 레이어)
피해 공식 검증 (물리/마법/고정/포병 관통)

5단계: 영웅/결과/복귀

명세서 §8.4 · 완료 조건: 승/패 후 월드맵 복귀 정상, 앱 재시작 후 기록 유지

데이터

HeroConfig SO 정의 (§9.4)
SpellConfig SO 정의 (§9.5)

코드 작업

HeroController.cs 신규 — 이동/공격/스킬 최소 구현
승/패 결과 계산 (§6.4 별 등급 기준)
결과 UI 표시 (승리 → 별/보상, 패배 → Retry/Exit)
저장 반영 (SaveManager 경유)
WorldMapReturnAnimator 연계 — 전투 결과 데이터 소비 지점 점검
보스 면역(즉사/강제이동 면역) 플래그 전투 판정 반영 [High Risk]

검증

월드맵 → 게임 진입 시 스테이지 데이터 일치
승/패 결과 저장 반영 정상 (§6.4 별 등급)
게임 → 월드맵 복귀 루프 정상
앱 재실행 후 기록 유지

6단계: Mock 격리 / 회귀 안정화

명세서 §8.5 · 완료 조건: 기본 빌드 Mock 비활성, 주요 루프 회귀 통과

코드 작업

GameMockController를 DEV_MOCK 컴파일 심볼 분기로 격리
기본 실행 경로에서 Mock 완전 분리

검증 (DoD §16)

WorldMapScene → GameScene → WorldMapScene 루프 회귀 30회+
DEV_MOCK 비활성 빌드에서 Mock 경로 호출 0건
기존 저장 데이터와 신규 스키마 호환 확인
씬 전환 반복 시 메모리 누수/크래시 없음
저장 실패/로드 실패 시 안전 폴백 동작

7단계: KPI / 밸런스 튜닝

명세서 §10 · 완료 조건: 텔레메트리 로그 삽입 + 수치 1차 튜닝

코드 작업

KPI 로그 삽입 (§10 전체 항목)
- WaveClearTime, LifeLostPerWave, GoldIncomePerWave
- TowerBuildRateByType, EnemyLeakCountByType
- EarlyCallUsageRate, HeroSkillUsageRate
속도 조절(x1/x2) 구현 — timeScale 비의존 타이머 분리 [위험 §11]

검증

초반 3웨이브 체감 난이도 안정
특정 타워 타입 사용률 편중 없음
조기 호출 사용이 명확한 보상과 리스크를 가짐
속도 조절 시 Coroutine/애니메이션/물리 정상 동작
적/투사체/이펙트 오브젝트 풀링 적용 (성능)
전투 피크 시 목표 FPS 유지

코드 반영 대상 요약 (§17)

구분	파일	변경
수정	`GameScene.cs`	Mock 제거, FSM 진입점
수정	`WorldMapScene.cs`	진입 파라미터 검증 강화
수정	`GameMockController.cs`	`DEV_MOCK` 격리
수정	`GameView.cs`	HUD/링메뉴/결과 UI 확장
수정	`WorldMapReturnAnimator.cs`	결과 데이터 소비 점검
신규	`Game/GameStateController.cs`	FSM 총괄
신규	`Game/WaveManager.cs`	웨이브 진행/판정
신규	`Game/SpawnManager.cs`	적 생성/경로 주입
신규	`Game/PathManager.cs`	경로 캐시
신규	`Game/InGameEconomyManager.cs`	골드 경제
신규	`Game/TowerManager.cs`	타워 CRUD
신규	`Game/HeroController.cs`	영웅 최소 기능

진행 로그

2026-02-14:
- SaveManager 추가 및 KingdomAppManager 초기화 경유 연결 완료
- WorldMapScene, GameMockController의 저장 접근을 SaveManager.Instance.SaveData로 전환
- GameMockController 복귀 경로를 WorldMapScene으로 통일
- GameMockController를 DEV_MOCK 컴파일 심볼 영역으로 격리
- GameStateController(FSM) 신규 추가 및 GameScene 연결
- GameView에 FSM 바인딩/상태 표시/일시정지 토글 연결
- WaveConfig, EnemyConfig SO 정의 추가 및 StageData에 WaveConfig 참조 필드 연결
- PathManager, SpawnManager, WaveManager, EnemyRuntime 최소 전투 루프 스캐폴딩 추가
- dotnet build 점검 시 Unity 생성 Assembly-CSharp.csproj에 신규 파일 미반영 상태 확인 (Unity 에디터 재생성 후 재검증 필요)
- 작업 순서를 UI Contract First로 재정렬: GameView/HUD를 전투 매니저보다 선행 구현하도록 단계 재배치
- GameView UI 계약 보강:
  - 상태/웨이브 표시, Pause 토글, Result 슬롯(승리/패배/Retry/Exit) 추가
  - ShowResult(...), HideResult(), SetPauseVisual(...) API 추가
  - 프리팹 바인딩 누락 시 런타임 기본 Result 슬롯 생성으로 Null-safe 강화
- GameView 레거시 프리팹 레이아웃 자동 교정 추가:
  - 중앙 중첩 버튼/텍스트를 HUD 위치(좌상단 정보, 우상단 Pause, 우하단 디버그 버튼)로 재배치
  - HUDRoot 기준 재부모화로 GameScene 진입 시 검은 화면 중앙 겹침 현상 완화
- GameViewLayoutFixTool 추가 (Kingdom/GameView/Fix Layout And Bindings):
  - Assets/Resources/UI/GameView.prefab 구조/직렬화 참조 자동 보정용
  - 현 세션에서 메뉴 실행 실패(에디터 컴파일/컨텍스트 이슈 추정), 에디터 리컴파일 후 재실행 필요
- GameViewScenePreview 추가 (Tools/Preview/GameView/*):
  - Canvas (Environment) 상위 오브젝트 자동 생성 후 GameView 프리팹 배치
  - WorldMapView 프리뷰 방식과 동일한 편집 모드 단독 미리보기 지원
- NotebookLM 기반 GameView 최소 슬롯 반영:
  - Top HUD: txtLives, txtGold, txtWaveInfo, btnNextWave, btnPause
  - Hero/Spell: imgHeroPortrait, btnSpellReinforce, btnSpellRain, 쿨다운 오버레이 2종
  - 인터페이스: UpdateResourceInfo, SetNextWaveInteractable, SetSpellCooldown 추가
- GameView.cs.meta 누락/Guid 불일치 복구:
  - 기존 프리팹 참조 Guid(35dfde0a8ebb4c04c95f39fcd76eb8bd)로 정합성 복원
- Kingdom/GameView/Fix Layout And Bindings 메뉴 실행 성공:
  - Assets/Resources/UI/GameView.prefab 레이아웃/직렬화 참조 자동 보정 완료
- 중앙 겹침 원인 제거:
  - GameView 루트 레거시 직속 노드(btn*/txt*) 정리 로직 추가
  - 프리팹 보정 툴도 동일 정리 로직 반영 후 메뉴 재실행 완료
- 스크린샷 기준 1단계 검증 진행:
  - GameScene 진입 시 HUD 기본 정보 표시 확인(웨이브/상태/생명력/골드/버튼 노출)
  - 영웅 포트레이트 기본 슬롯 시각 강도 완화(흰 사각형 알파 낮춤)

2026-02-14 (fix): WaveManager 참조 자동 재바인딩 + GameScene의 StageConfig.WaveConfig 주입 + 런타임 fallback WaveConfig 추가(참조 누락 시 경고/실패 완화).
2026-02-14 (verify): Unity Play에서 WaveManager missing-reference 경고 재현 여부 점검(콘솔 클리어 후 재확인).
2026-02-14 (fix): CameraBackgroundColorFixer obsolete API 교체 (FindObjectsOfType -> FindObjectsByType).
2026-02-14 (fix): WorldMapManager 스테이지 노드 생성 보완 + 월드맵 진입 fallback 정리 + WaveConfig 누락 시 FSM 안전화 + wave out-of-range 시 Result 전환.
2026-02-14 (fix): WorldMapManager 노드 생성 경로에 UIStageNode fallback 생성 추가(nodePrefab/nodeRoot 누락 시 경고 완화) + StageInfoPopup 리소스 누락 시 기본 fallback 추가.
2026-02-15 (feature): StageInfoPopup 프리팹 제작 완료 (Assets/Resources/UI/StageInfoPopup.prefab). 난이도 선택(Casual/Normal/Veteran), Start/Back/Close 버튼, 텍스트 영역 배치 완료.
2026-02-15 (enhance): StageInfoPopup 이미지/사운드 연동 완료. Panel=ico_stage_bg, Button=ico_text_bg, SFX=WorldMap_Click(open/click), 클릭 중복 재생 방지(0.08s).
2026-02-15 (asset-prep): 나노바나나용 프롬프트 문서 추가 (문서/이미지프롬프트/StageInfoPopup_이미지프롬프트_나노바나나.md). 코드/에셋 경로를 StageInfoPopup 기준으로 정리하고 fallback 정책 명시.
2026-02-15 (asset-apply): Step 2/3 적용 완료. StageInfoPopup 경로에 임시 이미지 4종 배치(StageInfoPopup_Panel/Button/Button_Start/Button_Close) 및 Tools/Kingdom/Build StageInfoPopup Prefab 메뉴로 프리팹 재생성 확인.
2026-02-15 (blocker): StageInfoPopup 신규 이미지 생성 시도 중 OpenAI Image API billing_hard_limit_reached로 중단. 과금 한도 확인 필요.
2026-02-15 (image-gen): OpenAI 한도 이슈 우회를 위해 ComfyUI 브릿지 적용. stageinfopopup_comfy_bridge.py로 이미지 4종 생성 후 PrefabBuilder 반영.
2026-02-15 (ui-tune): StageInfoPopup 레이아웃 1차 조정(패널/텍스트/버튼 간격, 닫기 버튼 크기/위치/패딩) 및 PrefabBuilder 업데이트.
2026-02-15 (ui-tune-2): StageInfoPopup 레이아웃 2차 조정(닫기 버튼 인셋/크기/외곽 여백, 중앙 텍스트 y축, 하단 Back/Start 정렬 간격).
2026-02-15 (ui-tune-3): StageInfoPopup 닫기 버튼 추가 미세조정(프레임 안착 강화: 위치/크기 재조정) 및 프리팹 재생성.
2026-02-15 (audio-fix): WorldMap_Click.mp3 교체(ComfyUI one-shot 클릭 효과음). 이전 버전은 WorldMap_Click_backup_prev.mp3로 백업.
2026-02-15 (audio-route-fix): WorldMap_Click mp3/wav 중복 참조 경로 정리. UI 클릭 전용 WorldMap_Click_UI.mp3 추가 후 WorldMapView/StageInfoPopup/Editor 할당 경로를 동일 파일로 통일.
2026-02-15 (noise-fix): StageConfig에 WaveConfig가 없을 때 발생하던 fallback 로그를 1회 정보 로그로 완화(WaveManager). 이후 StageConfig-WaveConfig 마이그레이션 진행.
2026-02-15 (game-visibility-fix): GameScene 월드가 검게만 보이던 문제 수정. 카메라를 2D 전투 기준(orthographic, z=-10)으로 강제 정렬하고, 런타임 배경(GameWorldRuntime/RuntimeBackground) fallback 생성 추가. SpawnManager에서 적 생성 시 기본 SpriteRenderer를 부여해 맵/적 가시성을 확보.
2026-02-15 (enemy-visual-fix): 흰 박스 적 fallback 개선. EnemyConfig에 Sprite/Tint/VisualScale 필드 추가, SpawnManager에서 EnemyConfig.Sprite 우선 사용 + Resources/UI/Sprites/Enemies/{EnemyId} 규칙 로드 + 미지정 시 EnemyId 해시 기반 색상 fallback 적용.
2026-02-15 (pause-resume-fix): Pause 후 Resume 불가 이슈 수정. GameView의 Pause 버튼을 쿨다운 바인딩에서 분리(즉시 토글), Pause 상태에서 버튼 라벨 Resume 표시. 공통 UIButtonExtensions 쿨다운을 unscaled time으로 변경해 timeScale=0에서도 interactable 복구되도록 보강.
2026-02-15 (battlefield-prefab-flow): GameScene이 Resources/Prefabs/Game/GameBattlefield 프리팹을 우선 로드하고, 없으면 GameBattlefield 런타임 fallback을 생성하도록 전환. PathManager.SetDefaultPathPoints(...), SpawnManager.SetEnemyRoot(...)를 추가해 전투 월드의 경로/적 루트 연결을 코드에서 고정. 에디터 메뉴 Kingdom/Game/Build GameBattlefield Prefab 추가.
2026-02-15 (battlefield-prefab-guard): GameBattlefield 프리팹의 Missing Script 참조 감지 가드 추가. 프리팹에 null component 또는 GameBattlefield 컴포넌트 누락 시 인스턴스화를 스킵하고 런타임 fallback 월드로 안전 전환.
2026-02-15 (battlefield-script-stability): GameBattlefield를 PathManager.cs 내부 선언에서 GameBattlefield.cs 단독 파일로 분리해 Unity 스크립트 매핑 안정화. 프리팹 빌더에서 기존 GameBattlefield.prefab 삭제 후 재생성하도록 변경.
2026-02-15 (verify): 몬스터가 지정 경로(웨이포인트)를 따라 이동하는 동작 확인 완료.

Antigravity, Codex 2026-02-15 (월드맵씬, 모듈화, 시스템작업, 게임씬)

blacknabis — Sun, 15 Feb 2026 03:55:35 +0900

DevLog_2026_02_15_1

오늘의 목표

게임씬 개발을 막고 있던 핵심 병목인 게임뷰 선행 안정화, 전투 월드 가시화, 웨이브/일시정지 루프 검증을 우선 해결했다.

진행한 작업

1) 게임뷰(HUD) 우선 정리

GameView를 기준 UI 계약으로 확정했다.
상태 표시(Prepare/WaveRunning/WaveBreak/Result/Pause), 웨이브 표시(WAVE n / total), 리소스 표시(Lives/Gold)를 정리했다.
Pause, Next Wave, Reinforce, Rain, 결과 슬롯(승/패)까지 최소 동작 경로를 만들었다.

2) 전투 FSM 연결

GameStateController 중심으로 전투 흐름을 구성했다.
Prepare -> WaveRunning -> WaveBreak -> Result 기본 흐름이 동작하도록 연결했다.
Pause/Resume 토글을 보강해 실제 정지 상태와 UI 상태가 일치하도록 수정했다.

3) 게임씬이 검게만 보이던 문제 해결

초기 GameScene이 카메라 중심/깊이 문제와 월드 오브젝트 부재로 검게 보이던 상태였다.
카메라를 2D 전투 기준으로 정리하고, 전투 월드 fallback 경로를 추가했다.
SpawnManager에서 적 가시성을 보장하도록 기본 렌더링 경로를 마련했다.

4) 경로 기반 이동 검증

PathManager, SpawnManager, WaveManager, EnemyRuntime 연결을 정리했다.
몬스터가 지정한 웨이포인트 경로를 따라 이동하는 동작을 실제 플레이에서 확인했다.

5) StageInfoPopup 프리팹/에셋 파이프라인 정리

StageInfoPopup 프리팹을 제작하고, 이미지/사운드 연결 경로를 정리했다.
클릭음 라우팅 충돌을 정리하고 UI 클릭음 단일 경로로 통일했다.
나노바나나/ComfyUI용 프롬프트 문서와 빌더 흐름을 문서화했다.

6) GameBattlefield 프리팹 흐름 추가

GameScene이 GameBattlefield 프리팹을 우선 사용하고, 실패 시 런타임 fallback으로 전환하도록 구성했다.
프리팹 스크립트 누락(Missing Script) 상황을 감지해 안전하게 우회하도록 가드를 추가했다.
빌더 메뉴를 통해 프리팹을 재생성하는 흐름을 마련했다.

이슈와 대응

Pause 후 Resume 불가: 버튼 쿨다운/타임스케일 영향 경로를 수정해 즉시 재개 가능하도록 보완.
GameBattlefield Missing Script: 프리팹 검증 가드 + 런타임 fallback 추가로 게임 진행이 끊기지 않게 수정.
인코딩 깨짐(task.md): UTF-8로 정리해 진행 기록을 다시 안정화.

오늘의 결과

게임뷰 표시/상태 동기화 정상.
Pause/Resume 토글 정상.
웨이브 숫자 변경 정상.
몬스터 경로 이동 정상.
전투 월드 초기화 실패 시 fallback 안전성 확보.

다음 작업

EnemyConfig별 실제 몬스터 스프라이트 에셋 연결.
StageConfig -> WaveConfig 참조 누락 케이스 정리(완전 데이터 기반 전환).
전투 월드 프리팹 구성 고도화(맵/웨이포인트/스폰 루트 정식화).

한 줄 회고

UI를 먼저 안정화한 선택이 맞았고, 그 덕분에 전투 로직과 월드 렌더링 문제를 빠르게 분리해 해결할 수 있었다.

Antigravity 2026-02-14 (월드맵씬, 게임씬,기타 모듈화, 시스템작업)

blacknabis — Sat, 14 Feb 2026 23:56:49 +0900

작업하며 노트 끄적끄적내용. 그 그뒤부터 내용은 본격적으로 문서화 하였습니다. 나눠서 하자니 분류도 애매하고 .. 개발은 Antigravity를 메인으로 사용하고 IDE에 Codex, kilo를 추가로 설치하여 작업하고있습니다.

IDE 작업 예시

1. 아이콘 제작 프롬프트

### A. Back (`Icon_Back`)#### 이미지 사이즈- `512x512` (기본)- 고해상도 필요 시 `1024x1024`#### Positive Prompt```textUI button icon for "Back", red curved arrow pointing left, wooden button frame with metal rim,game interface asset, game UI icon, isolated on white background, chunky vector style, wood and stone texture,Kingdom Rush art style, 2D vector art, flat cartoon style, thick bold outlines, vibrant saturated colors,hand-drawn game asset, Flash game aesthetic, cel-shaded, high contrast, 1:1 composition, 512x512```#### Negative Prompt```texttext, realistic, 3D render, complex details, thin lines, watermark

2. 피드백 후 정리 보완작업

피드백 내용과 대응 요청(볼드는 수정요청내역)

1.중앙 세로 이음선 제거

배경 중앙에 seam(경계선)처럼 보이는 라인이 있어 품질이 떨어져 보입니다. 배경 스프라이트/타일 정렬부터 수정하는 게 1순위입니다.(Scene에서 생긴 그리드이기 떄문에 작업안해도됨)

2.스테이지 선택 노드 가독성 강화

현재 STAGE SELECT가 배경과 비슷한 톤이라 눈에 덜 띕니다.

선택 링(펄스), 외곽 글로우, 노드 그림자 추가 추천.
(ComfyUI가 아닌 직접 GPT를 이용해서 생성 할 수 있을 떄만 대응)

3.상단 타이틀 대비 개선

WORLD MAP 텍스트가 배경 위에서 약합니다.

반투명 배너 또는 텍스트 외곽선/드롭섀도우를 넣어 가독성 확보하세요.
(메이플 폰트 링크 후 연동)

4.하단 버튼 의미 분리

두 버튼의 기능이 직관적으로 안 보입니다.

아이콘 크기 키우고, 짧은 라벨(예: HERO, UPGRADE) 또는 툴팁을 붙이세요.

5.버튼 배치 균형

하단 버튼이 맵 오브젝트 위에 떠 있는 느낌입니다.

공통 하단 바(패널) 위에 정렬하면 UI 체계가 안정됩니다.

6.상태 정보 추가

스테이지에 클리어/잠금/신규 상태를 표시하세요(별, 자물쇠, 느낌표).

월드맵의 진행감이 크게 좋아집니다.

7. 클릭 피드백 강화

버튼/노드에 hover/press 스케일(예: 1.0→0.93→1.0), 클릭 SFX를 강하게 주면 조작감이 좋아집니다.

8.안전영역 대응

버튼 위젯으로 추가하고. 컨텐츠사이즈필터랑 레이아웃 그룹 추가.

하단 버튼 규격화 가능하도록 모듈화(이미지와 텍스트 수정하도록)

하단 버튼 공통 모듈화

**
SafeArea 작업**

2026-02-14 개발일지 (feat.

월드맵에서 전투로 — UI 시스템 완성과 게임씬 설계

월드맵 UI를 프로덕션 수준으로 끌어올리고, 게임씬 전투 루프의 설계 문서를 확정한 하루.
"버튼 하나하나에 시스템이 있고, 전환 하나하나에 설계가 있다."

오늘의 목표

월드맵 UI 완성도 향상 — 스테이지 노드, 액션 버튼, 사이드 보더를 프리팹 기반으로 안정화
씬 전환 Fade 효과 — 모든 씬 전환에 FadeOut/FadeIn 적용
게임씬 구현 플랜 — NotebookLM 킹덤러쉬 분석 데이터를 기반으로 전투 루프 설계 문서 작성

커밋 요약

시간	커밋	내용
16:09	`a9a937e`	월드맵 UI 워크플로우, 에셋, 문서 일괄 적용
17:19	`501258b`	`UIActionButtonItem` 프리팹 추가 + 하단바 레이아웃 개선
20:34	`faf18d5`	`UIStageNode` 고도화 + 사이드보더 실행 플랜 추가
21:11	`347805d`	사이드보더 구조 툴 + SafeArea 바인딩
21:28	`0a4937d`	사이드보더 아트 에셋 생성 + 프리팹 바인딩
22:14	`51d8495`	`UIStageNode` 시각 상태 규칙 정리

️ 1. UIStageNode 시스템 고도화

문제

스테이지 버튼이 단순 Button + Text로만 되어 있어, 잠금 상태/클리어 등급/선택 하이라이트를 표현할 수 없었음.

해결: 데이터 바인딩 기반 ViewModel

StageNodeViewModel
  ├── StageId, StageName
  ├── IsUnlocked, IsBoss
  ├── ClearStars (0~3)
  └── IsSelected

      ↓ 바인딩

UIStageNode (MonoBehaviour)
  ├── 잠금 오버레이 (IsUnlocked = false → 어둡게 + 자물쇠 아이콘)
  ├── 별 표시 (ClearStars → 별 아이콘 1~3개)
  ├── 보스 마커 (IsBoss → 해골 아이콘 표시)
  └── 선택 하이라이트 (IsSelected → 테두리 발광)

시각 상태 규칙

상태	배경	아이콘	인터랙션
잠금	어둡게	자물쇠	터치 불가
해금(미클리어)	기본	스테이지 번호	터치 가능
클리어	기본	별 1~3개	터치 가능
선택됨	하이라이트	유지	선택 연출 재생

핵심: IStageUnlockPolicy 인터페이스로 해금 조건을 분리하여, 선형/분기/조건부 해금을 유연하게 교체할 수 있도록 설계.

️ 2. 사이드 보더 시스템

배경

월드맵 배경 이미지가 16:9 기준으로 제작되었지만, 4:3이나 19.5:9 같은 다른 비율에서 빈 공간이 노출됨.

해결 구조

WorldMapView
├── Background (Stretch)
├── LeftBorder  ← SafeArea 바깥 영역을 채움
├── RightBorder ← SafeArea 바깥 영역을 채움
└── Content (SafeArea 내부)

Editor 스크립트로 사이드보더 구조를 자동 생성 (WorldMapSideBorderStructureTool)
AI 생성 에셋을 좌/우 보더에 바인딩
SafeArea 기준으로 위치/크기 자동 조절

3. 씬 전환 Fade 효과

변경 내용

AppManagerBase.ChangeScene()에 useFade 파라미터 추가:

public void ChangeScene(TSceneEnum sceneID, bool useFade = true)

기본값 true: 모든 씬 전환에 FadeOut → 로드 → FadeIn 적용
useFade: false: 초기 진입(InitScene → TitleScene)처럼 자연스러운 전환에 사용
중복 호출 방지: _isChangingScene 플래그로 연타 방어
FadeIn 조건부 실행: _needsFadeIn 플래그로 FadeOut 없이 FadeIn만 되는 버그 차단

4. 게임씬 전투 루프 설계

오늘의 가장 큰 작업은 게임씬 구현 플랜을 NotebookLM 킹덤러쉬 분석 데이터를 기반으로 확정한 것.

NotebookLM에서 추출한 핵심 설계 포인트

요소	킹덤러쉬 원칙	구현 반영
건설 방식	자유 배치가 아닌 고정 슬롯	`StrategicPoint` 배치 시스템
병영 블로킹	유닛이 적을 물리적으로 저지	적 상태 FSM (`Moving/Blocked`)
조기 호출	리스크 감수 → 골드/쿨타임 보상	`WaveManager.EarlyCall()`
피해 공식	물리(% 감소), 마법(물리방어 무시), 고정(모든 방어 무시)	`DamageType` enum 3종
포병 관통	적 방어력 절반 무시	별도 공식 분기
경제 밸런스	항상 부족하게, 선택과 집중 강제	KPI 기반 튜닝
별 등급	남은 생명력 기준 (스테이지별 개별 설정)	`StarThresholds[]`

5단계 구현 로드맵

1단계: 전투 프레임 (FSM)
  └── Prepare → WaveRunning → WaveBreak → Result

2단계: 맵/경로/웨이브
  └── PathManager + WaveConfig/EnemyConfig SO

3단계: 타워/경제/블로킹
  └── TowerManager + InGameEconomyManager + 병영 루프

4단계: 영웅/결과/복귀
  └── HeroController + 저장 + WorldMapReturnAnimator

5단계: Mock 격리/회귀
  └── DEV_MOCK 분기 + 회귀 테스트

핵심 교훈

1. NotebookLM을 설계 도구로 쓰기

킹덤러쉬 분석 자료를 NotebookLM에 축적해두니, "포병의 방어력 관통 공식이 뭐야?" 같은 구체적인 질의에 정확한 답변을 받을 수 있었다. 게임 디자인 레퍼런스를 체계적으로 관리하면, 구현 단계에서 "감으로 만드는" 실수를 줄일 수 있다.

2. KPI를 코드보다 먼저 설계하기

보통 밸런싱은 게임이 어느 정도 완성된 후에 하지만, 이번에는 계측 지표(KPI)를 구현 플랜 단계에서 먼저 정의했다:

WaveClearTime, GoldIncomePerWave, EnemyLeakCountByType…

이 지표들이 먼저 정의되면, 코드를 짤 때 자연스럽게 로깅 포인트를 넣게 되고, "이 값이 어디서 튀는지" 추적이 가능해진다.

3. Disposable Tool 패턴의 위력

사이드보더 구조 생성, UIStageNode 검증, 에셋 바인딩 — 이 모든 작업을 일회성 에디터 스크립트로 처리하고 즉시 삭제했다. MCP로 개별 오브젝트를 하나씩 조작하는 것보다 Editor Script API를 활용한 일괄 처리가 훨씬 안정적이고 재현 가능하다.

Disposable Tools (생성 → 사용 → 삭제)

Assets/Scripts/Kingdom/Editor/
├── WorldMapSideBorderStructureTool.cs    ← 사이드보더 구조 자동 생성
├── WorldMapStageNodeAutoLayoutTool.cs    ← 스테이지 노드 배치 도구
└── WorldMapStageNodeValidationTool.cs    ← 스테이지 노드 프리팹 검증

오늘의 작업 흐름

1. 월드맵 UI 개선 (오전~오후)
   ├── UIActionButtonItem 프리팹 + 레이아웃
   ├── UIStageNode ViewModel 바인딩 + 시각 규칙
   └── 사이드보더 구조/에셋/바인딩

2. 씬 전환 Fade (오후)
   ├── AppManagerBase.ChangeScene() 확장
   ├── _needsFadeIn 플래그 추가
   └── InitScene → TitleScene fade 제외

3. 게임씬 설계 (저녁)
   ├── NotebookLM 질의 4건 (HUD/타워/경제/피해공식/UI인터랙션)
   ├── 기존 플랜 → 보강본 작성 (1차)
   ├── 사용자 편집 (구조 재정리, KPI/위험요소 추가)
   └── 2차 보강 (피해 공식, UI 흐름, 스키마 추가)

수치 요약

항목	수량
커밋	6건
신규/수정 스크립트	~12개
프리팹 생성/수정	4개 (`UIStageNode`, `UIActionButtonItem`, `WorldMapView`, `SideBorder`)
문서 작성/보강	5개 (사이드보더 플랜, 버튼 프리팹 플랜, 게임씬 플랜 등)
NotebookLM 질의	4건
컴파일 에러	0 (최종 검증 완료)
---

3. 플랜 보완하기!!

제미나이 프로 모델로 플랜을 만들후 제미나이 -> 클루드 -> 코덱스 -> 제미나이 계속 이렇게 플랜을 보강하면 (토큰 광탈) 플랜이 매우 단단해진다. 이후 Task세팅하고 코덱스나 클루드로 코드작업하면 한번에 엄청 길게 작업하면서도 매우 안정적으로 진행이 가능하다.

4. 스테이지 버튼도 모듈화

5. 작업이 너무 오래걸린다... 이제부터 코덱스 스파크 모델로 코드구현을 해보자! 생각보단? 빠르지 않은거 같은데 변경 내역을 자세히 못봐서 그런거 같기도하다.

6. 다음은 코덱스 <-> 오퍼스4.6 으로 게임씬 구현 플랜 내용이다. 해당 내용을 가지고 이후에 클루드 코드의 코딩을 진행 그러면 정말 한참을 짠다

게임씬 구현 플랜 (보강본)

1. 목적

GameScene을 Mock 중심 임시 상태에서 실제 전투 루프로 전환한다.
씬 흐름을 Init -> Title -> WorldMap -> Game -> WorldMap로 고정한다.
전투 결과(승/패, 별, 기록)가 저장과 월드맵 반영까지 일관되게 연결되도록 한다.

2. 범위

포함:
- 전투 상태머신
- 웨이브/스폰/경로
- 타워/병영 블로킹/영웅 기본 루프
- 전투 경제(골드)
- 결과 처리/저장/월드맵 복귀
- HUD/일시정지/결과 UI 최소 기능
제외(후속):
- 라이브옵스 운영툴(원격 밸런스 패치, A/B)
- 고급 연출(시네마틱, 특수 카메라 워크)

3. 현재 코드 기준 진단

항목	현재 상태	연결 코드
씬 정의	3개 (`Title`, `WorldMap`, `Game`)	`KingdomDef.SCENES`
게임 진입	월드맵 스테이지 선택 후 전환	`WorldMapScene.SelectedStageId`
전투 로직	Mock 시뮬레이션만 존재	`GameMockController`
HUD	디버그 버튼(Victory/Defeat/Pause) + 웨이브 텍스트	`GameView`
스테이지 데이터	`StageConfig` SO — 웨이브/적 미포함	`StageData` 구조체
저장	매번 `new UserSaveData()`로 생성 — 글로벌 싱글톤 아님	`WorldMapScene:25`, `GameMockController:95`
복귀 경로	충돌: Mock은 `TitleScene`, GameView는 `WorldMapScene`	`GameMockController:103` vs `GameView:58,65`

4. 목표 아키텍처

4.1 상태 흐름 다이어그램

┌─────────────────────────────────────────────────────┐
│  GameScene FSM                                      │
│                                                     │
│  ┌─────────┐   ┌────────────┐   ┌───────────┐      │
│  │ Prepare  │──>│ WaveRunning │──>│ WaveBreak │──┐  │
│  └─────────┘   └─────┬──────┘   └─────┬─────┘  │  │
│                      │                 │         │  │
│                      │    ┌────────────┘         │  │
│                      │    │  (다음 웨이브 있으면)   │  │
│                      │    v                      │  │
│                      │  ┌────────────┐           │  │
│                      │  │ WaveRunning│───────────┘  │
│                      │  └─────┬──────┘              │
│                      │        │ (마지막 웨이브 종료)  │
│                      v        v                     │
│                   ┌──────┐                          │
│                   │Result│                          │
│                   └──┬───┘                          │
│         ┌────────────┼────────────┐                 │
│         v            v            v                 │
│     [승리→월드맵] [패배→Retry]  [패배→Exit]         │
│                                                     │
│  ※ Pause: 모든 전투 상태에서 오버레이 진입/복귀 가능  │
└─────────────────────────────────────────────────────┘

4.2 매니저 배치

글로벌(DontDestroyOnLoad)
- SaveManager
- AudioManager
- MetaEconomyManager
로컬(GameScene 전용)
- GameStateController — FSM 상태 전이 총괄
- WaveManager — 웨이브 진행/조기 호출/종료 판정
- SpawnManager — 적 유닛 생성 및 경로 주입
- PathManager — 적 이동 경로 캐시(웨이포인트)
- TowerManager — 건설/업그레이드/판매/분기
- HeroController — 이동/공격/스킬
- InGameEconomyManager — 골드 수급/지출
- GameView — HUD 표시 (기존 BaseView 확장, InGameUIBinder 역할 겸임)

5. 핵심 설계 원칙 (NotebookLM 반영)

KR 스타일 핵심인 고정 건설 포인트 + 병영 블로킹을 초기에 포함한다.
단순 화력 경쟁 대신 조기 웨이브 호출(Early Call)의 리스크/리워드를 구현한다.
밸런싱은 감각이 아니라 계측 기반으로 진행한다(KPI 선구축).
초기화 순서를 강제한다:
- 글로벌 매니저 초기화 완료
- 스테이지 데이터 로드
- 경로 캐시
- 웨이브/스폰 시작

6. 전투 수학 (피해 공식)

6.1 피해 유형

유형	적용 방어	설명
물리(Physical)	ArmorPhysical(%)	아처/병영/포병 기본 출력
마법(Magic)	ArmorMagic(%)	마법사 기본 출력, 물리 방어 무시
고정(True)	없음	독/저주 등, 모든 방어 무시

6.2 물리 피해 공식

실제피해 = 기본피해 × (1 - ArmorPhysical / 100)

포병 특수: 적 방어력을 절반 무시 → 실제피해 = 기본피해 × (1 - ArmorPhysical / 200)

6.3 즉사(Insta-kill)

확률 기반: 공격 히트 시 확률 판정 (예: 스나이퍼 샷 최대 60%)
쿨타임 기반: 일정 쿨다운 후 확정 발동 (예: 죽음의 광선)
보스 면역: 보스/엘리트는 즉사 + 강제이동(CC) 면역

6.4 별 등급 기준

등급	조건
★★★	생명력 손실 ≤ 기준값A (거의 무손실)
★★	생명력 손실 ≤ 기준값B
★	생명력 > 0으로 클리어
패배	생명력 = 0

기준값은 WaveConfig.StarThresholds[]로 스테이지별 개별 설정

7. 타워 건설 UI 인터랙션

7.1 빈 건설 포인트 터치

터치 → 원형 링 메뉴 열림 (4종 타워 아이콘 + 비용 표시)
     ├─ 타워 선택 → 골드 차감 → 건설
     ├─ 골드 부족 → 아이콘 비활성(그레이아웃) + 비용 빨간색
     └─ 외부 터치/취소 → 메뉴 닫힘

7.2 기존 타워 터치

터치 → 타워 정보 + 액션 메뉴
     ├─ [업그레이드] 다음 레벨 비용 표시 (Lv1→2→3)
     ├─ [판매] 회수 골드 표시
     ├─ [분기 선택] Lv3→Lv4 시 2개 분기 아이콘 표시 (택 1, 비가역)
     └─ [랠리 포인트] (병영 전용) 집결 위치 드래그 지정

7.3 Lv4 이후 터치

터치 → 특수 능력 구매 메뉴
     ├─ 능력 A (비용/효과 표시)
     ├─ 능력 B (비용/효과 표시)
     └─ [판매]

8. 단계별 구현 계획

8.1 1단계: 전투 프레임 구축

작업:
- GameStateController 추가 (enum FSM)
- 상태 전이 규칙 확정 (§4.1 다이어그램 기반)
- Pause 진입/복귀 — Time.timeScale = 0 + 오버레이 UI
산출물: 상태 전이 로그(디버그), FSM 유닛테스트
완료 조건: Prepare→WaveRunning→WaveBreak→Result 전이 끊김 없음

8.2 2단계: 맵/경로/웨이브 골격

작업:
- PathManager — 웨이포인트 기반 적 이동 경로 캐시
- WaveConfig/EnemyConfig SO 도입
- SpawnManager 적 생성 + 경로 주입
- WaveManager 웨이브 종료 판정 (생존 적 0 + 스폰 완료)
산출물: 최소 1개 스테이지 웨이브 실행
완료 조건: 적이 경로를 따라 이동, 웨이브 시작/종료 정확 판정

8.3 3단계: 타워/경제/블로킹

작업:
- TowerManager 건설/업그레이드/판매/분기
- 원형 링 메뉴 UI (§7 인터랙션 기반)
- InGameEconomyManager 골드 수급/소모
- 병영 블로킹 루프 (적 상태: Moving→Blocked→Attacking→Dead)
- 조기 호출 보상 (남은시간 × 보상계수 + 스펠 쿨다운 단축)
산출물: 4계열 기본 타워 동작, 조기 호출 버튼
완료 조건: 경제 루프(처치→골드→강화) 안정 순환

8.4 4단계: 영웅/결과/복귀

작업:
- HeroController 이동/공격/스킬 최소 구현
- 승/패 결과 계산 (§6.4 별 등급 기준 적용)
- 저장 반영 + WorldMapReturnAnimator 연계
- 복귀 경로를 WorldMapScene으로 통일
산출물: 승리/패배 UI, 저장 리포트 로그
완료 조건: 승/패 후 월드맵 복귀 정상, 앱 재시작 후 기록 유지

8.5 5단계: Mock 격리/회귀 안정화

작업:
- GameMockController를 DEV_MOCK 분기로 제한
- 기본 실행 경로에서 Mock 완전 분리
- 핵심 회귀 테스트 수행
완료 조건: 기본 빌드 Mock 비활성, 주요 루프 회귀 통과

9. 데이터 스키마(초안)

StageConfig와 WaveConfig의 관계: 기존 StageConfig SO는 월드맵 표시용(위치/이름/해금)이고, WaveConfig는 전투 실행용(웨이브/골드/적). StageConfig.StageId를 키로 1:1 매핑하되, SO는 분리 유지한다. StageConfig에 WaveConfig 참조 필드를 추가하여 연결한다.

9.1 `WaveConfig` (SO)

StageId — StageConfig.StageId와 1:1 매핑
InitialGold
InitialLives
StarThresholds[] — 3별/2별 판정 기준 (남은 생명력)
Wave[]
- WaveIndex
- SpawnEntries[]
  - EnemyId
  - Count
  - SpawnInterval
  - PathId
  - SpawnDelay
- BonusGoldOnEarlyCall
- IsBossWave

9.2 `TowerConfig` (SO)

TowerId
TowerType (Archer/Barracks/Mage/Artillery)
DamageType (Physical/Magic/True)
BuildCost
SellRate (회수 비율, 예: 0.6)
CanTargetAir
Levels[]:
- Damage, FireRate, Range, UpgradeCost
BarracksData (병영 전용, TowerType == Barracks일 때만 사용):
- SoldierCount — 소환 병사 수 (기본 3)
- SoldierHP, SoldierArmor, SoldierDamage
- RespawnCooldown — 병사 재소환 대기 시간
- RallyRange — 집결 위치 지정 가능 반경
BranchOptions[] (Lv4 분기):
- BranchId, BranchName, BranchCost
- Abilities[] (특수 능력, 개별 비용)

9.3 `EnemyConfig` (SO)

EnemyId
HP
ArmorPhysical (% 감소)
ArmorMagic (% 감소)
MoveSpeed
GoldBounty
DamageToBase (탈출 시 생명력 차감)
IsFlying
IsBoss
IsInstaKillImmune
SpawnOnDeath[] (하수인 소환 시)

9.4 `HeroConfig` (SO)

HeroId
HeroName
HP, Armor, MoveSpeed
AttackDamage, AttackRange, AttackSpeed
Skills[]:
- SkillId, SkillType (Passive/Active/Ultimate)
- Cooldown, Duration, DamageOrEffect

9.5 `SpellConfig` (SO)

SpellId (증원군/불의비)
Cooldown
EarlyCallCooldownReduction
Duration, DamageOrEffect

10. KPI/텔레메트리(초기 필수)

WaveClearTime
LifeLostPerWave
GoldIncomePerWave / GoldSpendPerWave
UnspentGoldAtWaveStart
TowerBuildRateByType / TowerSellRateByType
EnemyLeakCountByType
EnemyDeathHeatmap (경로 구간별)
EarlyCallUsageRate
HeroSkillUsageRate

10.1 튜닝 기준(초기)

한 웨이브 종료 후 평균 신규 건설 0~1회 또는 업그레이드 1회 가능한 경제값
특정 타워 타입 사용률이 과도하게 치우치면 수치 조정 트리거
UnspentGoldAtWaveStart가 지속적으로 높으면 난이도/가격 재조정

11. 위험 요소와 대응

위험	대응
초기화 순서 꼬임 → Null/경로 누락	부트스트랩 완료 전 `GameScene` 진입 금지 가드
병영 블로킹 → 전투 상태 충돌	적 상태를 `Moving/Blocked/Attacking/Dead`로 분리
Mock 경로 잔존 → 실제 루프 왜곡	`DEV_MOCK` 컴파일 심볼로 강제 분리
피해 공식 누적 오차 → 밸런스 붕괴	고정소수점 또는 `int` 기반 HP/데미지 사용
타워 UI 터치 영역 겹침	타워/건설포인트에 우선순위 레이어 + 상호배타 처리
`UserSaveData` 인스턴스 중복 → 데이터 덮어쓰기	글로벌 `SaveManager` 싱글톤으로 단일 인스턴스 보장
`Time.timeScale` 변경 → Coroutine/DOTween 오동작	`timeScale` 비의존 타이머 분리, 속도 변경 시 회귀 테스트

12. 체크리스트

월드맵 → 게임 진입 시 스테이지 데이터 일치
웨이브 시작/종료와 HUD 동기화
타워 건설/업그레이드/판매 정상
병영 블로킹 정상
조기 웨이브 호출 보상 정상
영웅 이동/스킬 최소 기능 정상
승/패 결과 저장 반영 정상 (§6.4 별 등급)
게임 → 월드맵 복귀 루프 정상
앱 재실행 후 기록 유지
기본 빌드 Mock 비활성 확인
피해 공식 검증 (물리/마법/고정/포병 관통)
속도 조절(x1/x2) 시 Coroutine/애니메이션/물리 정상 동작
복귀 경로 통일 확인 (Mock/GameView 모두 WorldMapScene)

13. 우선순위

상태머신 + 웨이브/스폰/경로
타워/경제 + 병영 블로킹
결과 처리 + 저장 + 월드맵 복귀
영웅 최소 기능
KPI 계측 + 튜닝
Mock 제거 + 회귀 안정화

14. 참고 메모

본 문서는 NotebookLM 킹덤러쉬 노트북을 기반으로 보강했다.
반영 포인트:
- KR 스타일 핵심 전투 루프(병영 블로킹, 조기 호출)
- 전투 씬 매니저 분리 원칙
- 초기 단계 KPI 기반 밸런싱 접근
- 피해 유형 3종(물리/마법/고정) + 포병 관통 공식
- 별 등급 산정 기준 (라이프 기반)
- 타워 건설 UI 인터랙션 흐름 (링 메뉴 → 분기 → 능력 구매)

15. 누락 위험 체크리스트 (High Risk)

병영/영웅이 적을 실제로 멈추게 하는 Melee Lock 규칙이 구현됨
적 상태(Moving/Blocked/Attacking/Dead) 전이가 프레임 단위로 충돌 없이 동작함
초기화 순서가 고정됨(맵/경로 로드 전 스폰 시작 금지)
비행 적 타겟팅 제약(CanTargetAir)이 타워별로 정확히 적용됨
방어력/저항/고정피해 계산식이 공통 함수로 단일화됨
보스 면역(즉사/강제이동 면역) 플래그가 실제 전투 판정에 반영됨
웨이브 미리보기 UI가 실 유닛 스폰 없이 데이터만으로 동작함
조기 웨이브 호출이 경제 보상과 스킬 쿨다운 감소를 함께 처리함
Pause 상태에서도 입력 허용 범위(배치/업글/이동)가 명확히 분리됨
사운드 동시 재생 시 우선순위/채널 제한으로 클러터링을 제어함

16. Definition Of Done (전투씬)

16.1 기능

웨이브 데이터 기준으로 적 수량/타이밍이 정확히 스폰됨
적이 경로를 이탈하지 않고 목표 지점까지 이동함
타워가 유효 타겟만 공격하고(지상/공중 제약) 우선순위가 적용됨
병영 블로킹 및 영웅 교전이 정상 동작함
승/패 판정 및 결과 UI가 기획 조건대로 동작함

16.2 성능

적/투사체/이펙트 오브젝트 풀링 적용
목표 기기에서 전투 피크 시 목표 FPS 유지
불필요한 GC 스파이크(웨이브 시작/종료 구간) 없음

16.3 안정성

Null 참조 없이 타겟 소실 시 재탐색
씬 전환 반복(월드맵↔게임) 30회 이상에서 누수/크래시 없음
저장 실패/로드 실패 시 안전 폴백 동작

16.4 밸런스

초반 3웨이브 체감 난이도가 급격히 튀지 않음
특정 타워 한 종류만으로 강제되지 않음(사용률 편중 감시)
조기 호출 사용이 명확한 보상과 리스크를 가짐

16.5 회귀

WorldMapScene -> GameScene -> WorldMapScene 루프 회귀 통과
기존 저장 데이터와 신규 스키마 호환 확인
DEV_MOCK 비활성 빌드에서 Mock 경로 호출 0건

17. 코드 반영 대상 (초안)

Assets/Scripts/Kingdom/App/GameScene.cs
- GameMockController 자동 생성 제거, GameStateController 초기화 진입점으로 변경
Assets/Scripts/Kingdom/App/WorldMapScene.cs
- 진입 파라미터(SelectedStageId, 난이도) 전달 검증 강화
Assets/Scripts/Kingdom/App/GameMockController.cs
- DEV_MOCK 분기 격리 및 기본 빌드 경로 차단
Assets/Scripts/Kingdom/UI/GameView.cs
- HUD/링 메뉴/결과 UI 이벤트 바인딩 확장
Assets/Scripts/Kingdom/WorldMap/WorldMapReturnAnimator.cs
- 전투 결과 데이터 소비 지점 점검
신규(예정):
- Assets/Scripts/Kingdom/Game/GameStateController.cs
- Assets/Scripts/Kingdom/Game/WaveManager.cs
- Assets/Scripts/Kingdom/Game/SpawnManager.cs
- Assets/Scripts/Kingdom/Game/PathManager.cs
- Assets/Scripts/Kingdom/Game/InGameEconomyManager.cs
- Assets/Scripts/Kingdom/Game/TowerManager.cs
- Assets/Scripts/Kingdom/Game/HeroController.cs

18. 작업 순서(실행 단위)

GameScene에서 Mock 자동생성 제거 + FSM 뼈대 연결
웨이브/스폰/경로 최소 루프 구현
타워 건설/업글/판매 + 골드 루프 연결
병영 블로킹 + 영웅 최소 동작 추가
결과 저장 + 월드맵 복귀 루프 고정
KPI 로그 삽입 후 수치 1차 튜닝

task.md

0.01MB

게임씬 구현 — Task 체크리스트

근거 문서: 게임씬_구현명세서.md
작성일: 2026-02-14

0단계: 사전 정리 (선행 필수)

UserSaveData → 글로벌 SaveManager 싱글톤으로 전환
복귀 경로 통일: GameMockController, GameView 모두 WorldMapScene으로 변경
Assets/Scripts/Kingdom/Game/ 폴더 생성

1단계: 전투 프레임 구축 (FSM)

명세서 §8.1 · 완료 조건: Prepare→WaveRunning→WaveBreak→Result 전이 끊김 없음

코드 작업

GameStateController.cs 신규 — enum FSM (Prepare/WaveRunning/WaveBreak/Result/Pause)
상태 전이 규칙 구현 (§4.1 다이어그램 기반)
Pause 진입/복귀 — Time.timeScale = 0 + 오버레이 UI
GameScene.cs 수정 — Mock 자동생성 제거, GameStateController 초기화 진입점으로 변경

검증

상태 전이 로그(디버그) 출력 확인
FSM 유닛테스트 작성 및 통과

2단계: 맵/경로/웨이브 골격

명세서 §8.2 · 완료 조건: 적이 경로를 따라 이동, 웨이브 시작/종료 정확 판정

데이터

WaveConfig SO 정의 (§9.1)
EnemyConfig SO 정의 (§9.3)
StageConfig에 WaveConfig 참조 필드 추가

코드 작업

PathManager.cs 신규 — 웨이포인트 기반 경로 캐시
SpawnManager.cs 신규 — 적 생성 + 경로 주입
WaveManager.cs 신규 — 웨이브 종료 판정 (생존 적 0 + 스폰 완료)
적 기본 이동 로직 (경로 따라 이동 → 탈출 시 생명력 차감)

검증

최소 1개 스테이지 웨이브 실행
초기화 순서 고정 확인 (맵/경로 로드 전 스폰 시작 금지) [High Risk]

3단계: 타워/경제/블로킹

명세서 §8.3 · 완료 조건: 경제

루프(처치→골드→강화) 안정 순환

데이터

TowerConfig SO 정의 (§9.2) — BarracksData 포함
피해 공식 공통 함수 단일화 (물리/마법/고정/포병 관통) [High Risk]

코드 작업

TowerManager.cs 신규 — 건설/업그레이드/판매/분기
InGameEconomyManager.cs 신규 — 골드 수급/소모
원형 링 메뉴 UI 구현 (§7.1~7.3)
병영 블로킹 루프 — 적 상태: Moving→Blocked→Attacking→Dead [High Risk]
랠리 포인트 (병영 전용) 드래그 지정
조기 호출 보상 (남은시간 × 보상계수 + 스펠 쿨다운 단축) [High Risk]
비행 적 타겟팅 제약 (CanTargetAir) 적용 [High Risk]

검증

4계열 기본 타워 동작 확인
조기 호출 버튼 동작 확인
타워 UI 터치 영역 겹침 없음 (우선순위 레이어)
피해 공식 검증 (물리/마법/고정/포병 관통)

4단계: 영웅/결과/복귀

명세서 §8.4 · 완료 조건: 승/패 후 월드맵 복귀 정상, 앱 재시작 후 기록 유지

데이터

HeroConfig SO 정의 (§9.4)
SpellConfig SO 정의 (§9.5)

코드 작업

HeroController.cs 신규 — 이동/공격/스킬 최소 구현
승/패 결과 계산 (§6.4 별 등급 기준)
결과 UI 표시 (승리 → 별/보상, 패배 → Retry/Exit)
저장 반영 (SaveManager 경유)
WorldMapReturnAnimator 연계 — 전투 결과 데이터 소비 지점 점검
보스 면역(즉사/강제이동 면역) 플래그 전투 판정 반영 [High Risk]

검증

월드맵 → 게임 진입 시 스테이지 데이터 일치
승/패 결과 저장 반영 정상 (§6.4 별 등급)
게임 → 월드맵 복귀 루프 정상
앱 재실행 후 기록 유지

5단계: Mock 격리 / 회귀 안정화

명세서 §8.5 · 완료 조건: 기본 빌드 Mock 비활성, 주요 루프 회귀 통과

코드 작업

GameMockController를 DEV_MOCK 컴파일 심볼 분기로 격리
기본 실행 경로에서 Mock 완전 분리

검증 (DoD §16)

WorldMapScene → GameScene → WorldMapScene 루프 회귀 30회+
DEV_MOCK 비활성 빌드에서 Mock 경로 호출 0건
기존 저장 데이터와 신규 스키마 호환 확인
씬 전환 반복 시 메모리 누수/크래시 없음
저장 실패/로드 실패 시 안전 폴백 동작

6단계: KPI / 밸런스 튜닝

명세서 §10 · 완료 조건: 텔레메트리 로그 삽입 + 수치 1차 튜닝

코드 작업

KPI 로그 삽입 (§10 전체 항목)
- WaveClearTime, LifeLostPerWave, GoldIncomePerWave
- TowerBuildRateByType, EnemyLeakCountByType
- EarlyCallUsageRate, HeroSkillUsageRate
속도 조절(x1/x2) 구현 — timeScale 비의존 타이머 분리 [위험 §11]

검증

초반 3웨이브 체감 난이도 안정
특정 타워 타입 사용률 편중 없음
조기 호출 사용이 명확한 보상과 리스크를 가짐
속도 조절 시 Coroutine/애니메이션/물리 정상 동작
적/투사체/이펙트 오브젝트 풀링 적용 (성능)
전투 피크 시 목표 FPS 유지

코드 반영 대상 요약 (§17)

구분	파일	변경
수정	`GameScene.cs`	Mock 제거, FSM 진입점
수정	`WorldMapScene.cs`	진입 파라미터 검증 강화
수정	`GameMockController.cs`	`DEV_MOCK` 격리
수정	`GameView.cs`	HUD/링메뉴/결과 UI 확장
수정	`WorldMapReturnAnimator.cs`	결과 데이터 소비 점검
신규	`Game/GameStateController.cs`	FSM 총괄
신규	`Game/WaveManager.cs`	웨이브 진행/판정
신규	`Game/SpawnManager.cs`	적 생성/경로 주입
신규	`Game/PathManager.cs`	경로 캐시
신규	`Game/InGameEconomyManager.cs`	골드 경제
신규	`Game/TowerManager.cs`	타워 CRUD
신규	`Game/HeroController.cs`	영웅 최소 기능

진행 로그

2026-02-14:
- SaveManager 추가 및 KingdomAppManager 초기화 경유 연결 완료
- WorldMapScene, GameMockController의 저장 접근을 SaveManager.Instance.SaveData로 전환
- GameMockController 복귀 경로를 WorldMapScene으로 통일
- GameMockController를 DEV_MOCK 컴파일 심볼 영역으로 격리
- GameStateController(FSM) 신규 추가 및 GameScene 연결
- GameView에 FSM 바인딩/상태 표시/일시정지 토글 연결
- WaveConfig, EnemyConfig SO 정의 추가 및 StageData에 WaveConfig 참조 필드 연결
- PathManager, SpawnManager, WaveManager, EnemyRuntime 최소 전투 루프 스캐폴딩 추가
- dotnet build 점검 시 Unity 생성 Assembly-CSharp.csproj에 신규 파일 미반영 상태 확인 (Unity 에디터 재생성 후 재검증 필요)

gpt pro 할인!!

blacknabis — Fri, 13 Feb 2026 11:40:33 +0900

카카오톡에서 챗지피티로 검색하면 1/10 가격으로 프로모델을 최대 5대까지 구매할 수 있으며 이미 구독 중이면 구독이 종료된 뒤 사용하실 수 있습니다

Antigravity를 사용하여 타워 디펜스 게임 만들기 - 1

blacknabis — Fri, 13 Feb 2026 02:27:34 +0900

이번에 시도하는건 NotebookLM과 Antigravity를 연동해서 빠른시간에 최대한 자동화해서 개발을 계획중입니다.

딥리서치를 사용하여 킹덤 러시에 대한 분석 요청 (https://notebooklm.google.com)

해당 NotebookLM과 안티그래비티를 MCP로 연동해준다.

공용 라이브러리와 NotebookLM을 참고하도록 룰설정.

1. 씬구성 요청

처음 씬 구성하였을 때 3개만 구성되어서 NotebookLM을 사용하여 다시한번 일관성 채크.

카메라가 없어서 다시 카메라 추가를 요청

플레이를하면 비어있는 타이틀신에서 알아서 타이틀씬 스크립트를 읽어와서 타이틀씬UI프리팹을 UIManager에 이쁘게 등록된걸 확인.

ComfyUI가 반복적으로 에러가나서 확인해봤더니 내가 이전에 세팅한 이미지 생성 모델은 ace_step_v1_3.5b인데 안티그래비티가 따로 플로우워크.json을 주지않으면 제대로 못알아먹어서 v1-5-pruned-emaonly설치후 다시 진행. 잘된다..

이미지가 마음에 안들어서 Flow에서 나노바나나로 다시 제작...

Flow에서 나노바나나로 이미지를 다시 만들고 remove.bg에서 버튼이랑 로고의 배경을 삭제

이하 안티그래비티로 만든 개발일지 입니다.

AI로 게임 UI 에셋 만들기 — ComfyUI + Unity 자동화 파이프라인

Stable Diffusion으로 타이틀 화면 에셋을 생성하고, Unity Editor 스크립트로 자동 적용하는 과정을 기록합니다.
"그림은 AI가, 텍스트는 TextMeshPro가, 조립은 Editor 스크립트가."

목표

타워 디펜스 게임 Kingdom Defense의 타이틀 화면에 필요한 에셋 3종을 ComfyUI로 생성하고, Unity Editor 스크립트로 프리팹에 자동 적용하기.

에셋	용도	크기
`Title_Background.png`	전체 배경	768×512
`Title_Logo.png`	엠블렘 장식	512×512
`Title_BtnStart.png`	시작 버튼 프레임	512×256

️ 아키텍처

comfy_bridge.py (Python)
    │
    ├─ ComfyUI API (/prompt, /history, /view)
    │   ├─ CheckpointLoaderSimple (v1-5-pruned-emaonly)
    │   ├─ KSampler → VAEDecode
    │   └─ Image Remove Background (rembg)  ← 배경 제거
    │
    └─ 출력 → Assets/Resources/UI/Title/*.png
                    │
TitleAssetGenerator.cs (Unity Editor)
    │  Python 프로세스 실행
    └─ 생성 완료 후 AssetDatabase.Refresh()
                    │
ForceAssignTitleAssets.cs (Unity Editor)
    ├─ TextureImporter 설정 (Sprite, Alpha, 9-Slice)
    ├─ PrefabUtility로 TitleView.prefab 수정
    │   ├─ Background: Image (Stretched)
    │   ├─ Logo: Image (엠블렘, SetNativeSize)
    │   └─ btnStart: Image (9-Slice) + TMP "TAP TO START"
    └─ SerializedObject로 private 필드 바인딩

핵심 교훈 3가지

1. SD1.5는 텍스트를 못 만든다

처음 시도: 프롬프트에 'Kingdom Defense' 텍스트를 직접 넣음

결과: 글자가 뒤섞인 의미 없는 이미지 (아래 예시)

입력: "game logo text 'Kingdom Defense', stone texture..."
출력: "KALEM DFOM LETE"

해결: 장식 요소만 AI로 생성하고, 실제 텍스트는 TextMeshPro로 분리

# ❌ Before — AI에게 텍스트 요청
"game logo text 'Kingdom Defense', stone texture, gold border..."

# ✅ After — 장식만 요청, 텍스트는 Unity TMP로
"medieval fantasy shield emblem, golden ornate frame, royal crest, 
 no text, no letters, no words"

원칙: AI 이미지 = 장식/질감/분위기, 텍스트 = TextMeshPro. 역할을 분리하자.

2. RemBG로 배경 제거 자동화

투명 배경이 필요한 에셋(로고, 버튼)은 ComfyUI의 Image Remove Background (rembg) 노드를 활용.

# Python에서 워크플로우에 RemBG 노드 동적 삽입
if use_rembg:
    workflow["10"] = { 
        "class_type": "Image Remove Background (rembg)", 
        "inputs": { "image": [last_image_node, 0] } 
    }
    last_image_node = "10"

처음에는 C#에서 흑색 픽셀을 투명으로 바꾸는 Chroma Key 방식을 시도했지만, 경계가 지저분했음. RemBG가 훨씬 깔끔한 결과를 줌.

방식	품질	속도	비고
C# Chroma Key	⭐⭐	빠름	경계 노이즈, 그림자 잔존
RemBG (rembg)	⭐⭐⭐⭐	약간 느림	AI 기반, 깔끔한 마스크

3. Unity ↔ Python 브릿지 패턴

Unity의 UnityWebRequest로 ComfyUI에 직접 연결하려 했으나, 에디터 환경에서 비동기 처리가 불안정. Python 스크립트를 별도 프로세스로 실행하는 방식이 가장 안정적이었음.

Unity Editor (C#)
    │
    └─ System.Diagnostics.Process.Start("python", "comfy_bridge.py")
        │
        └─ Python (urllib) ─── HTTP ──→ ComfyUI (localhost:8188)
                                              │
                                              └─ 이미지 파일 저장
                                                     │
Unity Editor ←── AssetDatabase.Refresh() ────────────┘

장점:

Python은 HTTP 통신이 간편 (urllib 표준 라이브러리)
ComfyUI API 호환성 걱정 없음
Unity Editor의 메인 스레드 블로킹 회피

️ 프리팹 자동 조립 (ForceAssignTitleAssets.cs)

에셋이 생성되면 한 번의 메뉴 클릭으로 프리팹에 자동 적용:

// 1. 텍스처 임포트 설정
EnsureSprite("Title_Background.png");
EnsureSprite("Title_Logo.png");
EnsureSprite("Title_BtnStart.png", sliced: true);  // 9-Slice 자동 설정

// 2. 프리팹 로드 → 수정 → 저장
var rootGo = PrefabUtility.LoadPrefabContents(prefabPath);
SetupBackground(so, rootGo, folder);  // 전체 화면 배경
SetupLogo(rootGo, folder);            // 엠블렘 (크기 자동 조절)
SetupButton(so, rootGo, folder);      // 9-Slice 버튼 + TMP 텍스트
PrefabUtility.SaveAsPrefabAsset(rootGo, prefabPath);

핵심 테크닉:

PrefabUtility.LoadPrefabContents — 씬에 없는 프리팹도 직접 수정 가능
SerializedObject — private 필드(backgroundImage, btnStart)에 강제 할당
TextureImporter.spriteBorder — 9-Slice 보더 자동 설정

Disposable Tool 패턴

이 프로젝트에서는 일회성 에디터 도구를 적극 활용합니다:

Assets/Scripts/Kingdom/Editor/
├── comfy_bridge.py            ← ComfyUI 통신 (사용 후 삭제)
├── TitleAssetGenerator.cs     ← Python 실행기 (사용 후 삭제)
└── ForceAssignTitleAssets.cs  ← 프리팹 조립기 (사용 후 삭제)

에셋 생성/설정이 끝나면 스크립트를 즉시 삭제합니다. 프로젝트에 불필요한 코드가 남지 않도록 하는 것이 원칙.

전체 워크플로우 요약

1. comfy_bridge.py 실행
   → ComfyUI가 3장의 이미지 생성 (배경/엠블렘/버튼 프레임)
   → 로고·버튼은 RemBG로 배경 자동 제거

2. ForceAssignTitleAssets 실행 (Unity 메뉴)
   → 텍스처 → Sprite 변환, 9-Slice 보더 설정
   → TitleView.prefab에 이미지 자동 배치
   → 버튼 위에 "TAP TO START" TMP 텍스트 생성
   → SerializedObject로 private 필드 바인딩

3. 결과 확인 → 일회성 스크립트 삭제

다음에 시도해볼 것

ControlNet 활용 — 레퍼런스 이미지 기반으로 스타일 일관성 확보
LoRA 학습 — Kingdom Rush 스타일 전용 모델 파인튜닝
SDXL 전환 — 더 높은 해상도와 디테일
Addressables 기반 에셋 로딩 — Resources 폴더 의존성 제거

AI 이미지 생성은 "만능"이 아닙니다.
텍스트, 정밀한 레이아웃, UI 인터랙션은 여전히 전통적인 도구가 낫습니다.
AI가 잘하는 것(질감, 분위기, 장식)과 엔진이 잘하는 것(텍스트, 레이아웃, 로직)을 분리하는 것이 핵심입니다.

Unity 공용 라이브러리(Common) 개발기 — 2

blacknabis — Thu, 12 Feb 2026 00:53:26 +0900

Unity 프로젝트를 여러 개 진행하다 보면 매번 같은 코드를 복붙하게 됩니다.
"이거 한 번 정리하면 두고두고 쓸 텐데…" 라는 생각으로 Common 라이브러리를 만들었습니다.

목표

프로젝트 간 재사용 가능한 공용 코드 정리
GC 최적화, 편의성 극대화
한글 주석으로 팀원도 쉽게 이해 가능
계층화된 UI 시스템으로 팝업/HUD/화면 전환 일관성 확보

구현한 유틸리티 (18개)

1순위 — 거의 모든 프로젝트에서 필수

클래스	한 줄 설명
ObjectPool	프리팹 오브젝트 풀링. `Get()` / `Release()` / `PreWarm()`
EventBus	전역 이벤트 시스템. `Subscribe<T>()` / `Publish<T>()`
WaitCache	`new WaitForSeconds()` GC 제거. `WaitCache.Get(0.5f)`
PlayerPrefsHelper	bool, enum, DateTime, JSON 직렬화 지원

EventBus 사용 예:

// 이벤트 정의
public struct PlayerDiedEvent { public int score; }

// 구독
EventBus.Subscribe<PlayerDiedEvent>(e => ShowGameOver(e.score));

// 발행
EventBus.Publish(new PlayerDiedEvent { score = 1500 });

WaitCache 사용 예:

// Before ❌ — 매번 GC 발생
yield return new WaitForSeconds(0.5f);

// After ✅ — 캐시된 인스턴스 재사용
yield return WaitCache.Get(0.5f);

2순위 — 모바일 필수 + 코드 간결화

클래스	한 줄 설명
SafeAreaHelper	노치/펀치홀 대응 자동 레이아웃
CoroutineExtensions	`this.Delay(1f, callback)` 한 줄 딜레이
CollectionExtensions	`list.GetRandom()`, `Shuffle()` (GC-free)
StringExtensions	숫자 콤마, 시간 포맷, K/M 축약
ColorExtensions	`color.WithAlpha(0.5f)`, Hex 변환

CoroutineExtensions 사용 예:

// Before ❌
StartCoroutine(DelayCoroutine());
IEnumerator DelayCoroutine() {
    yield return new WaitForSeconds(1f);
    DoSomething();
}

// After ✅
this.Delay(1f, () => DoSomething());

3순위 — 게임 로직 지원

클래스	한 줄 설명
SimpleStateMachine	Enum 기반 FSM. Enter/Update/Exit 콜백
AudioHelper	BGM/SFX 싱글톤. 볼륨, 페이드, 자동 저장
ScreenTransition	씬 전환 페이드. `FadeOutIn(loadScene)`
DebugLogger	카테고리 로깅. 릴리스 빌드 자동 제거

4순위 — 생산성 부스터

클래스	한 줄 설명
Timer	카운트다운/업, 일시정지, 반복, 콜백
VectorExtensions	`pos.WithY(0)`, `Flat()`, `RandomInCircle()`
MathUtils	`Chance(30)` 확률, `Remap()`, `Damp()`
UIButtonExtensions	`SetOnClick()`, 연타 방지 쿨다운
SceneExtensions	비활성 포함 씬 내 컴포넌트 검색

️ UI 프레임워크

기존 BaseUI는 Show/Hide만 있는 껍데기였습니다. 이걸 레이어 기반 UI 관리 시스템으로 완전히 재설계했습니다.

아키텍처

UIHelper (static)  ← 호출 코드에서 사용
   ↓
UIManager (싱글톤)
 ├ 레이어별 Canvas 자동 생성
 │   HUD(0) → Screen(100) → Popup(200) → Overlay(300)
 ├ UI 인스턴스 캐시 (Dictionary<Type, BaseView>)
 ├ 팝업 스택 (List<BasePopup>)
 └ Back Key 라우팅 (팝업 → View 순)
   ↓
기본 클래스
 ├ BaseView   — 전체 화면 (CanvasGroup 페이드 내장)
 ├ BasePopup  — 모달 (딤드 배경, 닫기 가드)
 ├ BaseHUD    — 항상 표시 (HP, 점수)
 └ BaseWidget — 재사용 위젯 (스크롤 아이템)

사용 예

// 화면 전환 — Resources/UI/ 에서 자동 로드
UIHelper.Show<MainMenuView>();

// 팝업 + 닫기 콜백
UIHelper.ShowPopup<SettingsPopup>(onClose: () => SaveSettings());

// HUD 갱신
UIHelper.Get<ScoreHUD>()?.Refresh(currentScore);

// 씬 전환 시 전체 정리
UIHelper.ClearAll();

BasePopup 핵심 기능

public class ConfirmPopup : BasePopup
{
    [SerializeField] private Button confirmButton;

    protected override void OnInit()
    {
        base.OnInit();
        confirmButton.SetOnClick(OnConfirm);
    }

    // 닫기 전 확인 (false 반환 시 닫기 차단)
    protected override bool OnCloseRequested()
    {
        return hasUnsavedChanges == false;
    }
}

✅ 딤드 배경 자동 생성/제거
✅ 딤드 클릭으로 닫기 (옵션)
✅ Back Key 처리
✅ 닫기 가드 (OnCloseRequested)
✅ UIManager 팝업 스택 연동

최종 폴더 구조

Assets/Scripts/Common/
├── App/           AppManagerBase, SceneBase, Appdelegate, ISceneController
├── Patterns/      MonoSingleton, ObjectPool, EventBus, SimpleStateMachine
├── Extensions/    Object, GameObject, Transform, UI, Coroutine,
│                  Collection, String, Color, Vector, UIButton, Scene
├── Utils/         WaitCache, PlayerPrefsHelper, AudioHelper,
│                  DebugLogger, Timer, MathUtils
└── UI/            UIManager, UIHelper, UILayer, BaseView, BasePopup,
                   BaseHUD, BaseWidget, SafeAreaHelper, ScreenTransition

설계 원칙

IsNull() / IsNotNull() — Unity fake null 대응 전용 확장 메서드로 통일
GC 최적화 — WaitCache, ObjectPool, GC-free Collection 확장
Domain Reload 대응 — EventBus, WaitCache에 [RuntimeInitializeOnLoadMethod]
한글 주석 — 모든 public API에 XML 문서 주석 (한국어)
MonoSingleton — AudioHelper, ScreenTransition, UIManager 등 DontDestroyOnLoad 자동 처리

다음 계획

Addressables 기반 UI 로딩 (Resources 대체)
DOTween 연동 애니메이션 헬퍼
네트워크 HTTP 헬퍼 (UniTask 기반)
로컬라이제이션 시스템

이 Common 라이브러리는 Git 서브모듈로 관리하여 여러 프로젝트에서 공유합니다.
새 프로젝트를 시작할 때 git submodule add로 바로 가져다 쓸 수 있습니다.

업데이트 로그

2026-02-12: Coroutine → UniTask 전면 마이그레이션

UniTask 패키지 도입 (com.cysharp.unitask)
코루틴 → async/await 전환: AudioHelper, BaseView, ScreenTransition, UIButtonExtensions
CancellationTokenSource 기반 취소 패턴 적용 (기존 StopCoroutine 대체)
CoroutineExtensions → UniTaskExtensions 전면 교체 (GetCancellationTokenOnDestroy() 기반 자동 취소)
WaitCache 삭제 — UniTask 자체 GC-free 대기 메서드로 대체
UIButtonExtensions 쿨다운에서 MonoBehaviour 런너 불필요해짐

AI모델 주저리 주저리... (Claude Opus 4.6 아주 짤막한 사용기)

blacknabis — Thu, 12 Feb 2026 00:03:20 +0900

유니티 Common을 구축중 Claude Opus 4.6이 나와서 문득 Gemini pro 3.0하고 어느정도 차이일까 궁금해졌다. 이전에도 계획을 짤 때 Opus모델이 내취향이긴했는데....

Antigravity 3.0 Pro (High)

Claude Opus 4.6 (Thinking)

확실히 Opus 4.6이마음에 들긴하다. 안티그래비티로 작업전에 항상 플랜을 세우고 진행하는데 Opus로 계획을 세우고 Sonnet이나 제미나이 프로모델로 코드를 구현하게 이제 개인적인 베스트 인거같다. 문제는 Claude의 경우 토큰이 너무 빨리 빠져나감..

작업 진행 내역도 너무 마음에 뽑아준다.

오늘은 게임 개발에 Notebooklm을 어떻게 붙여볼까하가 이것저것 해봤는데 취향에 맞진 않는거같다. 그나마 역할 분담을 시키고 nootbooklm연동하게해서 계속 문서를 갱신했지만 후반부에는 역할분담이 꺠지는거 같아서 이쪽에 대해서는 더 많은 고민 후 다시 시도하고 성공하게 되면 블로그에 남기겠습니다.

공부는 계속 된다.... 가즈아.. 코드는 Opus인듯.. 언제 기회가 된다면 GPT 5.3도 써보고 싶네요

Antigravity와 함께한 SF6 Viewer 개발기: 아이디어에서 배포까지

blacknabis — Tue, 10 Feb 2026 23:49:59 +0900

안녕하세요! 최근 Street Fighter 6 방송용 전적 오버레이 프로그램인 SF6 Viewer를 개발하며 겪은 과정과, AI 코딩 어시스턴트 Antigravity를 활용해 어떻게 난관들을 극복했는지 공유하려 합니다.

1. 프로젝트의 시작: "방송 화면에 내 전적을 멋지게 띄우고 싶다"

스트리트 파이터 6를 즐기면서 시청자들에게 실시간으로 연승/연패 기록과 MR 변동을 보여주고 싶었습니다. 기존 웹 기반 툴은 새로고침이 번거롭거나 디자인이 투박했죠.
그래서 "게임 화면 위에 자연스럽게 녹아드는 투명한 HUD"를 직접 만들기로 결심했습니다. 하지만 혼자서 디자인부터 DB 설계, 크롤링, 배포 파일 패키징까지 하기엔 시간이 부족했습니다.
해결책: Antigravity에게 "SF6 Viewer를 만들어줘"라고 요청했습니다.

2. 디자인의 진화: 텍스트 한 줄에서 글래스모피즘까지

초기 프로토타입은 단순히 텍스트만 나열된 형태였습니다. 하지만 Antigravity에게 "더 프리미엄하고 모던하게", "사이버펑크 느낌의 네온 컬러를 써줘"라고 요청하자, 놀라운 변화가 일어났습니다.

Glassmorphism: 배경을 반투명하게 블러 처리하여 게임 화면을 가리지 않으면서도 가독성을 높였습니다.
Area Chart: 단순한 꺾은선 그래프 대신 그라데이션이 들어간 영역 차트로 MR 상승/하락 추이를 직관적으로 표현했습니다.
Micro-Animations: 수치가 변할 때 부드럽게 숫자가 올라가는 애니메이션을 적용했습니다.
저 혼자 CSS를 깎았다면 며칠이 걸렸을 작업을, AI와 티키타카하며 단 몇 시간 만에 완성했습니다.

3. 기술적 도전: Playwright와 실시간 데이터 수집 ️

가장 중요한 기능은 실시간 전적 수집이었습니다. 공식 API가 없기 때문에 Playwright를 사용하여 백그라운드 웹 크롤링을 구현했습니다.
Antigravity의 활약:

브라우저를 띄우지 않는 Headless 모드 구현
로그인 세션 유지 (auth.json) 로직 작성
30초마다 자동으로 데이터를 긁어와 DB를 갱신하는 비동기 스케줄러 개발
덕분에 게임을 하는 동안 알아서 전적이 쌓이는 시스템이 완성되었습니다.

4. 배포의 악몽: EXE 패키징과 Windows Defender ️

개발의 90%가 끝났다고 생각했을 때, 진짜 보스가 등장했습니다. 바로 PyInstaller 패키징과 Windows Defender였습니다.

문제 1: "바이러스 아님?"

PyInstaller로 --onefile 빌드를 하자마자 Defender가 파일을 냅다 격리해버렸습니다.
해결: --onedir (폴더 방식)로 변경하고 UPX 압축을 해제하여 오탐지를 피해갔습니다.

문제 2: "브라우저 어디 갔어?"

EXE로 만들었더니 Playwright가 내장 브라우저를 찾지 못해 "Executable doesn't exist" 에러를 뿜으며 실행되지 않았습니다. 내장 브라우저를 포함하면 용량이 수백 MB가 넘어가서 배포하기도 힘들었죠.
Antigravity의 솔루션:
"굳이 무거운 브라우저를 넣지 말고, 사용자 PC에 이미 설치된 Chrome이나 Edge를 쓰도록 코드를 바꾸자!"
scraper.py에 시스템 브라우저 감지 로직을 추가하여 용량은 줄이고 실행 안정성은 높였습니다.

5. 디버깅 에피소드: "들여쓰기 하나 때문에..."

마지막 배포 직전, ModuleNotFoundError가 발생하며 프로그램이 켜지지도 않는 사태가 벌어졌습니다.
알고 보니 제가 디버그 코드를 추가하다가 Python의 생명인 들여쓰기(Indentation) 를 실수했던 것이었죠.
Antigravity는 로그를 보자마자 "scraper.py의 while 루프 들여쓰기가 잘못되었습니다"라며 정확한 원인을 찾아내고, 즉시 수정 코드를 제안해주었습니다. (머쓱...)

6. 결론: 개발자와 AI의 페어 프로그래밍

혼자였다면 Windows Defender 이슈에서 포기하거나, 디자인을 대충 타협했을지도 모릅니다. 하지만 Antigravity가 옆에서 "이런 방법은 어때요?", "이 에러는 이렇게 고치면 됩니다"라고 끊임없이 가이드를 주었기에 SF6 Viewer v1.0을 무사히 배포할 수 있었습니다.
이제 제 방송 화면 한구석엔 제가(그리고 AI가) 만든 멋진 전적판이 빛나고 있습니다. ✨
GitHub 저장소 바로가기

Created with Python, FastAPI, Playwright, and Antigravity

스트리트파이터6 랭킹 수집 및 OBS 도우미

blacknabis — Tue, 10 Feb 2026 22:55:24 +0900

1. 깃허브에 접속

https://github.com/blacknabis/SF6RankViewer

GitHub - blacknabis/SF6RankViewer: 스트리트파이터6 랭크 수집 및 OBS 방송 지원

스트리트파이터6 랭크 수집 및 OBS 방송 지원. Contribute to blacknabis/SF6RankViewer development by creating an account on GitHub.

github.com

2. SFViewerV1_0.Zip 다운로드

3. 압축 해제 후 SF6Viewer.exe실행

4. 터미널과 대시보드가 열림

해당터미널을 끄면 서버가 꺼지므로 대시보드의 연동도 종료됩니다!!

제일 중요한 대시보드. 서버가 돌고 있으면 대시보드는 언제든 다시 띄울수 있습니다.(http://localhost:8000/)

5. 내 정보 연동을 위해 "Open Login Browser" 딸칵

확인

6. 새 브라우저에 스트리트 파이터가 계속 깜박거릴겁니다(크롬) 로그인해주세요.

7. 로그인 후 확인 창 클릭

확인 딸칵

8.Refesh Data를 눌러 데이터가 연동 잘된지 확인 한 뒤 새로 떴던 크롬 창을 닫아줍니다(계속 깜빡거려서 귀찮아요)

상단에 닉네임확인!

9. Start Collect 딸칵. 이제부터 수집이 시작됩니다.

10. open staticstics 딸칵

웹창이 뜨면서 이런식으로 전적이 수집됩니다. (http://localhost:8000/stats)

OBS 에 브라우저 추가.(크기는 개취)

마무리! 이제 콜렉트 켜놓은 상태에 방송하시면됩니다.

blacknabis

농장 경영 시뮬레이션 게임 만들기 - 1

PixelLab.AI MCP 연동하기

1. PixelLab 가입하기

2. MCP 연동하기

3. 사용방법

4. 후기

안티그래비티 반응이 없을 때 대처.

원시인 모드 스킬

클로드 코드(Claude Code) 토큰 75% 절약하는 방법: '원시인 모드(Caveman)' 가이드

원시인 모드(Caveman Mode)란?

비포 & 애프터 비교

원시인 모드 프롬프트가 주는 4가지 이점

️ 4가지 강도(Intensity) 조절 기능

️ 다양한 AI 어시스턴트에 설치하는 방법

알아두면 유용한 3가지 부가 기능

맺음말

클로드 코드(Claude Code) 권한 설정 가이드: 위험천만한 바이패스 모드와 새로운 오토(Auto) 모드 해부ClaudeClaude Code

클로드 코드(Claude Code) 권한 설정 가이드

1. 극단적 선택: --dangerously-skip-permissions 플래그

작동 방식 및 특징

왜 이 모드가 그토록 위험할까?

언제 사용해야 할까?

2. 현명한 타협안: 오토(Auto) 모드 (Research Preview)

어떻게 작동하나요?

오토 모드의 장점

3. 한눈에 보는 비교 (Bypass vs Auto)

4. 실전 가이드: 안전장치(deny 룰) 설정하기

Claude Code에서 Codex Plugin을 사용해보자!

일반 사용 흐름

Codex 통합 구조

AI 소식 수집. 디스코드에 보내는 봇 제작

AI 소식을 매일 수집해 Discord로 보내주는 요약 봇을 만들었습니다

핵심 구성

상태 관리와 중복 방지

X 수집에서 신경 쓴 부분

한국어 정리 방식

Discord 출력 포맷

테스트와 운영

마무리

️ Unity SRPG 개발 로그: 데이터 구조 대확장 — 직업, 보스, 챕터, 조합 시스템

1. GridCell — 비행/수중 이동 타입 지원

해결 방법

2. JobData ScriptableObject 신설 — 직업 시스템 기반 설계

새로 만든 것

3. EnemyTemplateData + BossPhaseData 신설

EnemyTemplateData

BossPhaseData

4. ️ ChapterData + GameDatabase 신설 — StageDatabase 은퇴

5. ⚔️ StageData 확장 — 승리/패배 조건 + 증원 시스템

승리 조건 (VictoryConditionType)

패배 조건 (DefeatConditionType)

증원 웨이브 (ReinforcementWave)

6. ⚗️ CraftRecipeData 신설 — 연금술사 조합 시스템

마치며

️ 추천 태그

KikiLeoBook 릴리즈 준비 — 패키지 리네임부터 GitHub Release까지

KikiLeoBook 릴리즈 준비 — 패키지 리네임부터 GitHub Release까지

개요

1. 패키지명 및 앱 이름 변경

2. 시맨틱 버전 관리

3. 설정 화면 추가

4. 릴리즈 키스토어 생성 및 서명 설정

Gradle 서명 설정

5. Firebase 연동 업데이트

6. Google OAuth 동의 화면 확인

7. 릴리즈 APK 빌드

8. GitHub Release 버전 관리

트러블슈팅

키스토어 비밀번호 특수문자 문제

에뮬레이터에서 Google 로그인 실패

마치며

KikiLeoBook 개발 진행 상황 5차

JisunBook UI/UX 개선 프로젝트 보고서 (e-ink 최적화)

1. 개요

2. 주요 수정 내역

2.1 색상 및 대비 (Design Tokens)

2.2 하단 컨트롤 시스템

2.3 설정 화면 (BottomSheet)

2.4 위젯 최적화

1. 극단적 선택: `--dangerously-skip-permissions` 플래그

4. 실전 가이드: 안전장치(`deny` 룰) 설정하기

`epub_reader.html`

`EpubReaderFragment.kt`

`ReaderActivity.kt`

리더 옵션 기능을 다시 `master`로 복구

3. 컴팩트 사이즈(`1400x180`) 자동 최적화

1. V1.1 릴리즈 빌드 (`SF6ViewerV1_1.zip`)