Poke-Builder
Pokémon Champions 파티 빌더 — 6슬롯 파티를 구성하고 타입 상성을 확인하며, 결정력·내구력 매치업과 여러 턴짜리 배틀타워 시뮬레이션까지 판정하는 웹 앱.
주요 기능
- 6슬롯 파티 편성: 기술 4개·특성·도구 배치, 실제 스프라이트 이미지(메가·폼·성별 자동 반영), 이름 붙인 파티/빌드 프리셋 저장·불러오기, 드래그앤드랍 순서 변경
- 타입 상성 매트릭스: 파티 6마리 × 공격 타입 18종 방어 배율을 한눈에, 파티 전체 취약/강점 자동 판정
- 성격·능력포인트 편집: 챔피언스 전용 실수치 공식, 슬라이더 UI로 스탯 배분
- 결정력 & 내구력 매치업: 랭크·날씨·필드·스크린·특성·다단히트까지 반영해 확정 1타
3타 이상 판정, 난수(85100)별 데미지를 "실제 데미지 (HP%)"로 표기(범위 + 16개 펼치기). ver.1.9부터 카드별 가정 토글 — 상태이상·급소·HP 조건(맹화류·멀티스케일·HP 슬라이더)·조건부 위력(보복·눈사태·분함의발구르기·열불내기·분풀이·승부굳히기·작아지기)
- 배틀타워(다중 턴 시뮬레이션): 우선도·명중/회피·급소·상태이상·반동·2턴 차지기·난동(역린 등 2~3턴 고정 + 혼란)·날씨/필드 등 전투 로직 전반을 반영한 턴제 대전(난동·모으기 2턴째·반동 턴은 선택 없이 자동 진행 — 교체 불가), 6빌드→3선출 & 교체(중복 배치 방지, 드래그앤드롭 순서 변경, 압축 카드 뷰), 배틀비디오(배틀타워 최근 3전 다시보기)
- 배틀타워 AI(ver.1.9부터 난이도 선택 없이 한 가지): 상대 편을 컴퓨터가 조작 — 기술·교체·메가진화를 "HP 교환" 점수식 하나로 비교해 선택. 유턴류·회복·랭크업·배턴터치·상태이상·벽·설치기·날씨/필드/트릭룸·도발/앙코르·방어류(엔진 한 턴 시뮬레이션)까지 판단. ver.1.8부터 파티 단위 평가 — 남은 포켓몬끼리의 대면표로 교환 뒤 수 싸움까지 계산(미니맥스). ver.1.9에서 판단 정확도 보강 — 급소 확률, 기습 성공 확률, 반동·생명의구슬·흡수 등 자기 HP 변화, 모으기·반동 기술의 턴 비용, 탈피·수확·맹독 누적, 교체 봉쇄 기술 가치. ver.2.0에서 판단 구조 강화 — 후보 행동마다 실제 엔진으로 한 턴을 돌려 보는 탐색(Web Worker, "AI 생각 중" 표시, 평균 약 0.25초), 상대도 같은 평가식으로 판단한다고 보는 한 단계 추론 + 교체 읽기, 사용자 패턴 학습(대전 간 누적 — 배틀타워는 최근 약 100판, 랭크배틀은 별도 기록 최근 약 200판, 설정 화면
🧠 AI 학습 N판 → "AI가 본 내 습관"에서 성향 확인·학습 끄기·초기화). 판단 기준 한눈에 보기: ai-판단기준-요약.md
- 랭크배틀(ver.5.0, 사이드 메뉴): 배틀타워 화면(파티 편성·선출·대전)을 그대로 쓰되 상대는 AI와 샘플 파티로 자동 고정. 몬스터볼 → 슈퍼볼 → 하이퍼볼(각 4
1단계, 원형 게이지 경험치제) → 마스터볼(레이팅제 — 진입 레이팅 (1300 + 2×누적 승수) × 조건부 1.1, 한 판 기본 ±20 + 턴 보정, 연승·연패 배율) → 챔피언(마스터볼 레이팅 2500 이상). 승패 직후 계산 내역 카드·최근 50판 이력·30일 시즌 기록·이탈은 패배. 상대는 같은 등급의 샘플 파티 또는 같은 등급 샘플 슬롯으로 무작위 구축한 파티(볼별 비율: 몬스터 100% · 슈퍼 70% · 하이퍼 50% · 마스터 30% · 챔피언 40%)이고, 최근 상대는 다시 안 나오며 챔피언은 전용 최상 파티 풀을 쓴다. 경험치제 구간에서 연패하면 상대 파티 등급·AI 단계를 낮추는 난이도 보정. 랭크 AI는 몬스터볼하이퍼볼에서 실수 모델로 약화한 3단계, 마스터볼은 레이팅 구간(41) 따라 상대 모델만 → 앱 AI로 올라가고, 몬스터볼하이퍼볼에서 쌓은 사용자 습관을 마스터볼부터 단계적으로(0.25~1.0) 활용(학습은 배틀타워와 따로 — 랭크는 최근 약 200판). 편성·선출 화면의 상대는 메가폼·도구를 숨긴 기본형으로 표시. 배틀비디오는 랭크 최근 5전을 따로 보관
- 상대 진영 설치 기술 6종·강제 교체 기술 4종: 스텔스록·압정뿌리기 등 / 드래곤테일·울부짖기 등
- 계산 기능(사이드 메뉴, 탭 4개 — 탭끼리 내 포켓몬·상대 종·날씨·필드를 공유하고 날씨·필드 배경이 깔린다. 입력은 새로고침·탭 이동 뒤에도 자동 복원)
- 결정력 계산: 위 "결정력 & 내구력 매치업". 내/상대 포켓몬은 드래그앤드롭으로 자리를 바꾼다(ver.3.3)
- 노력치 역산(ver.2.1 "상대 실능치 역산"): 내가 입힌 데미지(상대 HP 정수 %)를 관측으로 입력하면 상대의 HP·방어(특방) 능력 포인트와 성격이 될 수 있는 범위를 좁힘 — 엔진과 같은 정수 데미지 공식으로 후보 전수를 난수 16단계까지 시험. ver.3.1에서 내가 받은 데미지로 상대 공격(특공), 선후공 관측으로 상대 스피드까지 역산하고 세 쪽을 결합(성격 공유·포인트 합계 66), 메가 전·후 비교 표. ver.3.3~3.6에서 다단히트·포인트 합계 하한·쓰러진 공격 지원, 결합 계산 약 4배 빠르게, 구체적인 후보 카드 목록(정렬 3종). ver.3.7에서 관측 사이 턴 종료 효과(먹다남은음식·독·화상·맹독 등) 반영
- 스피드 조정(ver.3.4 스피드 표 → 3.6 재설계): 내 스피드로 상대 최속·준속·무투자·최저속 단계별로 어떤 포켓몬을 추월하는지, 목표 포켓몬을 넘는 최소 스피드 포인트
- 내구 조정(ver.3.7): 상대 포켓몬·기술을 최대 난수(또는 난수 n%)로 맞아도 버티는 최소 HP·방어(특방) 포인트 조합 표, HP 최적 수치(16n+15 등) 표시. 포인트 편집 모달의 HP 눈금도 도구·타입·기술에 따라 자동 강조(ver.3.7)
- 샘플 파티 58개(ver.2.1, 2.2에서 심화샘플 6개, 3.1에서 4개, 3.2에서 3개, 3.5에서 1개, 5.0에서 2개, 5.1에서 2개, 5.2에서 심화샘플 10개·기초샘플 8개, 5.3에서 심화샘플 1개 추가, 배틀타워 설정 화면의 "샘플 파티"·"무작위 샘플"·"랜덤 구축"(ver.2.2 — 저장해 둔 슬롯 프리셋에서 마리 단위로 6마리 조합)·"배틀 프런티어"(ver.2.2 연속 대전 → 2.5 개편 — 선출을 고정하고 샘플 파티를 무작위로 상대하며 연승·최대 연승·샘플별 승패를 저장, 도중 이탈은 패배)): 심화샘플 40 + 기초샘플 18(날씨·트릭룸·스톨·하이퍼 오펜스·사이클·해악·막이·그래스·사이코·일렉트릭 등)을 양쪽 진영에 사본으로 불러온다. 읽기 전용 데이터라 불러와서 고쳐도 원본·저장 파티는 그대로. "내 샘플"(ver.3.1)은 ver.3.2부터 JSON 파일로 내보내고 가져올 수 있다(가져올 때 형식·id·포인트를 검사하고 중복은 제외)
- 사이드 메뉴: 계산 기능(위)·포켓몬 도감(전국도감 순 정렬, 루가루암 등 폼 변종은 폼 탭으로 종족값·특성·기술 전환)·카드형 기술표·도구 도감
- 레귤레이션 M-C 대응: 신규 포켓몬 26종 + 전용 기술·특성·지닌 도구를 엔진에 배선
- 글래스모피즘 UI + 모바일 대응(≤760px): 반투명·블러 기반 디자인 토큰, 하단 탭 네비(5.1 — 파티·계산·배틀타워·랭크배틀·도감 시트, 랭크 대전 중 이동 확인, 홈 화면 추가용 PWA 설정과 홈 인디케이터·노치 안전 영역), 모달 하단 시트화, 검색창 하단 고정, 입력 확대 방지
- 로컬 자동 저장: 편성 내용이
localStorage에 자동 저장, 새로고침해도 복원
- 백업·클라우드 동기화(파티 빌더 헤더 "백업" 버튼): 저장한 파티·저장한 포켓몬 빌드를 JSON 파일로 내보내기·가져오기(ver.5.5). 선택 기능으로 Google 로그인하면 저장한 파티·저장한 포켓몬·내 샘플(ver.6.2)이 Firebase(Firestore)에 자동 백업되고 같은 계정의 다른 기기와 맞춰진다(ver.6.0) — 한쪽만 바뀌면 자동 반영, 두 기기에서 따로 바꿨으면 항목 단위로 합친다(추가·삭제·이름 변경 모두, ver.6.2). 랭크배틀 기록(랭크·레이팅·승패·시즌 기록)과 프런티어 기록(연승·전적)도 같이 맞춘다(ver.6.2) — 두 기기에서 따로 플레이한 랭크 판은 기준 상태에서 시각 순으로 다시 계산해 합치고(시즌이 끼었거나 한쪽이 50판을 넘기는 등 합칠 수 없을 때만 화면에서 고른다), 프런티어 기록은 양쪽이 다르면 화면에서 고른다. 대전 영상·AI 학습 기억은 동기화하지 않는다. 로그인하지 않으면 지금처럼
localStorage만 쓴다
- 한국어 조사 자동 처리: 로그·모달 문구의 조사를 받침 기반으로 자동 판별
데이터 규모
- 포켓몬 252종 — 메가진화 가능 76종 / 메가폼 81개(일부 종은 메가폼 2개)
- 기술 511개 (우선도·랭크 변화·다단히트 정보 포함)
- 특성 216개
- 샘플 파티 58개 (
src/data/samplePartyPresets.json — npm run validate:data가 기술·특성·포인트·중복을 검사)
- 도구 166종 (메가스톤 포함)
- 성격 21종
- 스프라이트:
public/sprites/ — npm run sprites로 src/data/spriteManifest.json 재생성
기술 스택
React 19 + TypeScript + Vite 8. 서버 코드 없는 정적 SPA — 기본은 로컬 JSON 데이터 + localStorage로 동작하고, 선택 기능인 클라우드 백업만 Firebase(Authentication·Firestore, 로그인 화면을 열 때 지연 로딩)를 쓴다(ver.6.0). @/는 src/를 가리키는 경로 별칭(ver.1.5). 린트는 oxlint, 테스트 러너는 없음 — 엔진·AI 검증은 Vite ssrLoadModule로 src/를 직접 불러오는 스크립트(npm run test:ai·npm run sim:ai, ver.1.7)로 한다.
시작하기
npm install
npm run dev # http://localhost:5174
npm run build # 데이터 검증 + tsc -b + vite build → dist/
npm run lint # oxlint
npm run sprites # public/sprites/ 스캔 → src/data/spriteManifest.json 재생성
npm run test:ai # 배틀 AI·엔진 규칙 시나리오(실패 시 exit 1)
npm run test:inference # 상대 실능치 역산·내구 조정: 엔진 데미지 공식 대조 + 왕복·전수 검증(ver.2.1~)
npm run test:damage # 정수 데미지 공식 난수표 + 엔진 대조
npm run test:rank # 랭크배틀 규칙표(게이지·마스터볼 진입·레이팅·챔피언) 검증
npm run test:rank-ai # 랭크 AI 정책(단계·구간·연패 보정·상대 선택·랜덤 구축·학습 사용률) 검증
npm run test:sync # 클라우드 동기화 판정·정규화(6.0, 네트워크 없음)
npm run test:rules # Firestore 보안 규칙(에뮬레이터, Java 21 이상 필요)
npm run validate:data # 데이터 정합성 검사(build가 먼저 실행)
npm run sim:ai -- regress # 엔진 동작 불변 확인용 로그 해시(모드: regress|ai|greedy|style|h2h|selectvs|partyvs|diag|logidx)
npm run bench -- compare <이전 체크아웃> # AI 벤치(그리디·STATUS·h2h, 코어 수만큼 병렬 — toggle 모드는 켬/끔 비교)
클라우드 로그인(선택)을 쓰려면 프로젝트 루트에 .env.local을 만들어 VITE_FIREBASE_API_KEY·VITE_FIREBASE_AUTH_DOMAIN·VITE_FIREBASE_PROJECT_ID·VITE_FIREBASE_APP_ID 4개를 넣는다(값은 Firebase 콘솔 → 프로젝트 설정 → 내 앱. 웹 설정은 비밀이 아니고 *.local은 git에 올라가지 않는다). 없으면 "클라우드 백업" 구역만 보이지 않고 나머지는 그대로 동작한다. 규칙 검증(npm run test:rules)은 Java 21 이상이 필요하다.
배포 & 개발 워크플로
main 브랜치가 Vercel 프로덕션에 자동 배포된다(제로 설정, 프레임워크 프리셋 자동 감지). dev에서 항목별 브랜치를 파서 PR로 dev에 머지하고, 버전이 끝나면 dev를 main에 merge commit으로 병합한다(dev는 삭제하지 않는다). 기획·백로그 문서만 고치는 변경은 브랜치/PR 없이 직접 커밋한다. 상시 브랜치는 main·dev 둘뿐 — 머지된 작업 브랜치는 로컬·원격 모두 삭제한다.
폴더 구조
src/
├─ types/ Pokemon, Move, Ability, Item, Party, Nature, Matchup, BattleStats, Status, Weather, Field 등 도메인 타입
├─ data/ pokemon.json, moves.json, abilities.json, items.json, natures.json, typeChart.json, spriteManifest.json
├─ lib/ 데이터 조회·타입 상성·실수치/결정력/내구력 계산·특성/랭크/명중/턴순서 판정·도구 효과·
│ 상대 실능치 역산(defenseInference·attackInference·speedInference·combinedInference·candidateCards)·
│ 스피드/내구 조정(speedTable·bulkAdjust)·HP 눈금(hpMagic)·조사 자동 판별·로컬 저장(storage.ts, 팩토리 기반)
│ └─ battle/ 다중 턴 배틀 시뮬레이터(ver.1.5에 8개 파일로 분리) — state/switching/
│ hitResolution/preHitEffects/mirroredEffects/resolveAction/runTurn/finishTurn.ts
│ └─ ai/ 배틀 AI(ver.1.7) — evaluator(옵션 평가)·decision(HP 교환 점수식)·opponentMoveModel
│ (상대 기술 확률 모델)·partyEval(파티 대면표)·moveDamage·hitsToKill(처치 타수 DP)·
│ turnRates(턴 종료 효과)·statusMoveEffects·protectMoves 등
├─ hooks/ useParty · useMatchup · useBattleSetup · usePartyPresets · useSlotPresets · useMySamples · useBattleVideos · useBattleSeries · useAiMemory 등
└─ components/ PartyBoard, MatchupPage(+ DefenseInferencePanel·SpeedTablePanel·BulkAdjustPanel 탭), PokedexPage(+ TypeChartTable), MoveDexPage(카드형 UI), ItemDexPage, 각종 PickerModal 등
BattleLogPage(+ BattleSetupScreen/BattleSelectScreen/BattleBoard 화면 분리),
BattleTurnLog(+ 로그 계열별 렌더러 9종 분리)
public/sprites/ 포켓몬·메가진화·도구·타입 스프라이트 (spriteManifest.json 생성 소스)
scripts/ 데이터·에셋 유지보수 도구 — scripts/README.md 참고
문서
기획·백로그 문서는 docs/00_기획문서/에 있다 — 초기 개발 phase 문서는 01_phase/, 버전 백로그·세션 인계 문서는 02_backlog/(1.x는 01_ver.1.0/, 2.x는 02_ver.2.0/, 3.x는 03_ver.3.0/, 4.x는 04_ver.4.0/, 5.x는 05_ver.5.0/, 6.x는 06_ver.6.0/), 배틀 AI 설계 문서는 03_battleAI_DEV/, 샘플 파티 초안은 04_sample_DEV/. (docs/ 바로 아래의 03_샘플파티추가/에는 샘플 파티 추가용 원본 txt를 모아 둔다.) 버전별 배포 내역은 메이저 버전마다 요약 문서 하나로 묶었다:
- 1.x 요약 — ver.1.0.x ~ 1.9: 빌더·배틀타워·엔진 감사·글래스모피즘 UI·배틀타워 AI
- 2.x 요약 — ver.2.0 ~ 2.5: AI 판단 강화(탐색 오라클)·상대 실능치 역산·정수 데미지 공식
- 3.x 요약 — ver.3.0 ~ 3.7: 도감 상성표·프런티어·역산 2차·스피드 조정·내구 조정
- 4.x 요약 — ver.4.0: 모바일 관측 행·방어 역산 턴 종료 효과·내구 조정 한계 해소, 코드 전체 리팩토링, 디자인 검수(접근성·토글 통일·글자/반경/색 토큰·터치 영역), AI 상대 HP 비율 표기 · ver.4.1: 터치 영역 마커 클래스·reduce 모션 전역 규칙·편성 화면 설명 ⓘ
- 5.x 요약 — ver.5.0: 배틀타워 랭크배틀 시스템(몬스터볼~챔피언·레이팅제)·랭크별 AI 5단계와 마스터볼 구간 학습 활용·샘플 파티 강도 등급·최상 파티 풀, 코드 정리
- 6.x 요약 — ver.6.0: 계정 + 클라우드 백업(Firebase 로컬 우선 동기화)으로 저장한 파티·포켓몬 빌드 유실 방지, 새 코드 정리 · ver.6.1: 큰 컴포넌트·훅·테스트 스크립트 분할(동작 불변) · ver.6.2: 클라우드 동기화 개선(항목 단위 병합·내 샘플·랭크/프런티어 기록 동기화·창 복귀 자동 동기화 등) · ver.6.3(초안): 배틀 AI 작업 전용
- 데이터변경이력.md — 기존 항목 수치·학습셋 변경(밸런스 패치) 기록. ver.1.4부터 시작
ver.1.0 이전(Phase 1~8) 회고·기획 문서도 같은 폴더에 있다 — 초기 아키텍처 결정과 단계별 개발 이력이 궁금하면 참고.
