Godot 4 + Claude Code로 인디게임 만들기 3부 – 전투 시스템 설계 문서화

Godot 4 + Claude Code로 인디게임 만들기 3부 – 전투 시스템 설계 문서화

📅 2026년 7월  |  ⏱️ 읽는 시간 약 13분  |  🏷️ Godot, ClaudeCode, 인디게임개발, 바이브코딩, 개발일지, 카드포지, 덱빌딩

💡 이 글에서 얻을 수 있는 것
2부에서 제작소 6개 시설을 완성하고 전투 시스템의 3가지 옵션(간단한 턴제·에너지 기반·핸드 드로우)을 놓고 고민하는 과정을 다뤘습니다. 3부에서는 "다 섞어줘"라는 한 마디로 결정된 통합 전투 시스템을 실제 설계 문서로 어떻게 구체화했는지 정리합니다. 턴 진행 순서, 리소스 표, 카드 사용 흐름까지 Claude Code에 넘기기 전 구현 가능한 수준의 스펙 문서를 만드는 과정을 그대로 보여드립니다.

📋 목차

1. 2부 요약 – 선택의 순간
2. "다 섞어줘" – 통합 전투 시스템 결정
3. 전투 진행 흐름 설계
4. 리소스 시스템 표로 정리하기
5. 플레이어 턴 3단계 상세 설계
6. 적 턴 – MVP는 단순하게
7. 게임 종료 조건
8. 카드 사용과 대미지 계산 흐름
9. 왜 코드보다 문서를 먼저 만들었나
10. 다음 단계 예고

1. 2부 요약 – 선택의 순간

2부에서 제작소 6개 시설(작업대·효과부여대·용광로·수리대·분해기·덱편성대)을 모두 완성한 뒤, 게임의 핵심 루프를 완성할 전투 시스템 설계를 시작했습니다. 세 가지 방식 중 하나를 선택해야 하는 질문을 받았습니다.

옵션	방식
1. 간단한 턴제	코스트/에너지 없이, 매턴 카드 1장 선택
2. 에너지 기반	매턴 에너지 회복, 카드마다 코스트 존재
3. 핸드 드로우 시스템	매턴 1장 드로우, 핸드 5장 유지

2. "다 섞어줘" – 통합 전투 시스템 결정

세 가지 옵션 중 하나를 고르는 대신, 세 시스템을 모두 결합하기로 결정했습니다. 에너지로 카드 사용을 제한하고, 핸드 드로우로 카드 순환을 관리하는 완전한 덱 빌딩 게임 방식입니다. 슬레이 더 스파이어 같은 로그라이크 덱빌딩 게임에서 흔히 쓰이는 구조와 유사합니다.

💡 왜 다 섞는 것이 합리적이었나: 카드 포지는 애초에 "카드를 직접 제작하는" 덱빌딩 게임을 표방합니다. 코스트 없는 단순 턴제로는 애써 만든 카드들의 강약 차이가 드러나지 않고, 핸드 드로우가 없으면 덱 구성 전략도 의미가 옅어집니다. 세 요소를 합쳐야 제작소에서 고민한 카드 조합이 실제 전투에서 전략으로 이어지는 구조가 완성됩니다.

결정이 나온 즉시 구현에 들어가지 않고, 먼저 CardForge_Combat_System_Design.md라는 설계 문서를 만들었습니다.

3. 전투 진행 흐름 설계

가장 먼저 전투 한 판이 어떻게 시작해서 끝나는지 전체 흐름을 다이어그램으로 정리했습니다.

전투 시작
  ↓
플레이어 턴
  ├─ 드로우: 핸드에 카드 1장 추가 (최대 5장)
  ├─ 플레이 페이즈: 카드 선택 → 에너지 소비 → 대미지 계산
  ├─ 반복: 에너지가 있으면 계속 플레이
  └─ 턴 종료: 에너지 초기화
    ↓
적 턴
  ├─ 몬스터가 고정 대미지 적용
  └─ 플레이어 HP 감소
    ↓
반복 (누군가 HP 0 이하가 될 때까지)
  ├─ 플레이어 HP ≤ 0: 패배
  └─ 몬스터 HP ≤ 0: 승리 → 재료 드롭

📌 이 흐름도 하나만으로도 "지금 뭘 만들어야 하는지"가 명확해집니다. 드로우 → 플레이 → 턴 종료 → 적 턴 → 승패 판정, 이 5단계가 이후 모든 세부 설계의 뼈대가 됩니다.

4. 리소스 시스템 표로 정리하기

전투에 필요한 리소스(HP, 에너지, 핸드, 덱)를 표로 정리해 각 리소스의 기본값과 특이사항을 한눈에 볼 수 있게 만들었습니다.

리소스	플레이어	적	비고
HP	최대 100	몬스터별 상이	감소 시 손상 카드 가능
에너지	매턴 3	고정	매턴 시작에 3으로 초기화
핸드	최대 5장	-	매턴 1장 드로우
덱	플레이어 덱	-	카드 소진 시 버린 카드 더미를 섞어 재생성(Reshuffle)

💡 "HP 감소 시 손상 카드 가능"이라는 짧은 메모가 제작소의 수리대 시스템과 전투를 연결하는 핵심 고리입니다. 전투에서 입은 피해가 카드 손상으로 이어지고, 손상된 카드는 다시 제작소의 수리대에서 고쳐야 하는 순환 구조를 의도한 설계입니다.

5. 플레이어 턴 3단계 상세 설계

플레이어 턴을 드로우 → 플레이 페이즈 → 턴 종료의 3단계로 나누고, 각 단계를 의사코드 수준으로 구체화했습니다.

Step 1 – 드로우

드로우 규칙

현재 핸드 카드 수 < 5이면: - 덱의 맨 위 카드 1장을 핸드에 추가 - 덱이 비어있으면 버린 카드(Discard Pile)를 섞어 덱으로 재생성

Step 2 – 플레이 페이즈

카드 사용 반복 로직

반복: 1. 플레이어가 핸드에서 카드 선택 2. 카드의 코스트 확인 (모든 카드: 코스트 1로 통일) 3. 현재 에너지 ≥ 코스트? - Yes: 카드 사용 → 에너지 차감 → 효과 발동 - No: 선택 불가 (disabled 표시) 4. 사용한 카드를 Discard Pile으로 이동 5. 에너지가 0이 되거나 플레이어가 턴 종료 버튼 클릭할 때까지 반복

📌 MVP 단계에서는 모든 카드 코스트를 1로 통일했습니다. 카드마다 다른 코스트를 부여하는 밸런싱은 게임의 기본 골격이 안정적으로 작동하는 것을 확인한 후에 진행하는 것이 안전하다고 판단했습니다.

Step 3 – 턴 종료

턴 종료 처리

- 에너지를 3으로 초기화 - 적의 턴으로 전환

6. 적 턴 – MVP는 단순하게

적 AI는 MVP 단계에서 의도적으로 가장 단순한 형태로 설계했습니다.

적 턴 로직 (MVP)

몬스터가 고정 공격 1회: - 플레이어 HP에서 [몬스터 기본 대미지] 차감 - 플레이어 턴으로 전환

💡 몬스터 패턴, 여러 번 공격, 특수 스킬은 전부 나중으로 미뤘습니다. 적 턴이 복잡해지면 플레이어 턴 로직이 잘 작동하는지 검증하기가 어려워지기 때문에, 먼저 "고정 대미지 1회"라는 가장 단순한 형태로 전체 루프를 완성하는 것을 우선순위로 뒀습니다.

7. 게임 종료 조건

승패 판정

매 턴 끝마다 확인: - 플레이어 HP ≤ 0: 패배 → 재료 50% 소실 + 거점 복귀 - 몬스터 HP ≤ 0: 승리 → 재료 드롭 + 거점 복귀

📌 여기서 "재료 50% 소실"은 이전에 설계했던 로그라이크 페널티 규칙과 정확히 일치합니다. 카드 자체는 잃지 않고 재료만 절반 소실되는 방식으로, 실패해도 "한 번 더 돌면 복구된다"는 동기를 유지하도록 설계 초반부터 일관되게 이어온 원칙입니다.

8. 카드 사용과 대미지 계산 흐름

실제로 카드 한 장을 사용했을 때 내부적으로 어떤 계산이 일어나는지도 단계별로 정리했습니다.

카드 사용
  ↓
1. 사용 횟수 확인
  - 사용 횟수 > 0: 계속
  - 사용 횟수 = 0 (손상): 대미지 50% 감소
  ↓
2. 기본 대미지 계산
  Base Damage = 카드 기본 대미지 (예: 10)
  ↓
3. 효과 발동 (MVP 미구현, 추후 예정)
  - 시너지 조합이면 대미지 추가
  - 상태 이상 부여 (화상/독 등)
  ↓
4. 최종 대미지 적용
  몬스터 HP -= 최종 대미지
  ↓
5. 카드를 Discard Pile로 이동

💡 "사용 횟수 0인 손상 카드는 대미지 50% 감소"라는 규칙이 눈에 띕니다. 이 규칙 덕분에 제작소의 수리대가 단순한 부가 시설이 아니라, 전투 성능에 직접 영향을 주는 필수 관리 요소가 됩니다. 카드가 손상된 채로 전투에 나가도 아예 못 쓰는 게 아니라 절반 위력으로는 쓸 수 있게 해서, 급하게 던전에 들어가야 하는 상황에서도 선택지를 열어둔 설계입니다.

MVP 대미지 테이블 – 일부러 단순하게

능력	기본 대미지	비고
검술	10	-
궁술	10	-
마법	10	-
기타	10	-

📌 10종 핵심능력이 모두 대미지 10으로 통일되어 있습니다. 능력별 차등화는 전투 루프 자체가 정상 작동하는 것을 검증한 이후로 미뤄둔 의도적인 단순화입니다.

9. 왜 코드보다 문서를 먼저 만들었나

지금까지의 모든 내용은 사실 단 한 줄의 GDScript 코드도 작성하기 전에 정리한 것입니다. "다 섞어줘"라는 결정이 난 순간 바로 Claude Code에게 전투 씬을 만들어달라고 요청할 수도 있었지만, 그 전에 마크다운 설계 문서부터 만들었습니다.

바로 구현 요청 시	설계 문서 먼저 작성 시
턴 구조가 코드 안에 암묵적으로만 존재	턴 구조가 문서로 명시되어 언제든 재확인 가능
리소스 값(HP 100, 에너지 3 등)이 코드 곳곳에 흩어짐	리소스 표 하나로 모든 기본값을 한눈에 관리
MVP 범위가 애매해서 과설계 위험	"효과는 나중" 같은 범위 제한이 문서에 명시됨
다음 세션에서 설계 의도를 다시 설명해야 함	CLAUDE.md처럼 파일로 남아 다음 세션에 그대로 참조 가능

💡 1부에서 CLAUDE.md를 먼저 작성했던 것과 같은 원칙입니다. 게임의 핵심이 되는 시스템일수록, 코드를 짜기 전에 문서로 뼈대를 확정하는 것이 나중에 구조를 뒤엎는 시행착오를 줄여줍니다. 이 설계 문서(CardForge_Combat_System_Design.md)는 이후 Claude Code에게 전투 씬 구현을 요청할 때 그대로 참조 자료가 됩니다.

10. 다음 단계 예고

Phase	내용	상태
Phase 1	데이터 구조 (Custom Resource 정의)	✅ 완료
Phase 2	제작소 UI (6개 시설 전체)	✅ 완료
Phase 3	전투 시스템 – 설계 문서화	✅ 완료
Phase 3.5	전투 시스템 – Godot 구현	⏳ 예정
Phase 4	던전 루프 연결	⏳ 예정
Phase 5	밸런싱 & 폴리싱	⏳ 예정

전투 시스템의 뼈대가 문서로 완성되었습니다. 4부에서는 이 설계 문서를 바탕으로 Claude Code에게 실제 전투 씬(BattleScene)과 CombatManager 스크립트 구현을 요청하는 과정, 그리고 F5로 첫 전투를 직접 플레이해보며 발견한 이슈들을 다룰 예정입니다. 전투가 완성되면 던전 노드 시스템(전투 노드·보물상자·이벤트·휴식·보스)과 연결해 게임의 핵심 루프가 처음부터 끝까지 이어지게 됩니다.