NIKKE 스쿼드 계산기

TypeScript 시뮬레이션 엔진을 웹 브라우저 안에서 실행하는 정적 스쿼드 대미지 계산기입니다.

서비스: https://nikke-calculator-xi.vercel.app/ (원본: https://moris-kr.github.io/nikke-calc/)

원본 계산 엔진: https://github.com/Jgaram/nikke-calc

AI 에이전트 연결 (MCP)

ChatGPT·Claude에 공개 MCP 주소 https://nikke-calc-mcp.onrender.com/mcp를 등록한 뒤, 계산기의 편의 기능 → MCP → AI 연결에서 받은 연결 코드를 전달하세요. AI가 요청하면 열어 둔 계산기 브라우저가 계산하고, Render는 입력과 결과를 중계합니다. 조회·계산 요청은 작업 ID를 먼저 반환하며 AI가 완료 결과를 따로 확인합니다. 탭과 기기를 깨워 두어야 하며 연결은 2시간, 완료 결과 보관은 5분입니다.

연결 코드를 아는 사람은 전체 육성·덱을 읽고 계산할 수 있으므로 공개하지 마세요. 사용 후 연결을 해제하면 권한이 취소됩니다. 닉네임·계정 ID·쿠키는 공유 데이터에 포함하지 않습니다. 육성·편성·계산 결과는 AI 서비스와 중계 서버를 거치며, 중계 서버는 메모리에 임시 보관합니다.

**설치·연결 튜토리얼**에서 ChatGPT/Claude와 브라우저 연결 방법을 확인하세요. 로컬 stdio MCP(nikke_mcp/, Node.js 22 이상)는 PC에서 사이트와 같은 TypeScript 엔진으로 계산합니다. 공개 중계 서버에 계산을 대신 실행하는 기능은 없습니다.

구조

• site/: Vite와 TypeScript로 만든 정적 웹 애플리케이션. site/src/engine/이 단일 TypeScript 계산 엔진
• scraper/: 블라블라링크 CDN에서 원시 게임 데이터를 수집하는 Python 스크래퍼 (nikke_scraped.json이 유일한 원시 데이터 정본)
• data/: 파싱된 정규화 데이터 — 캐릭터·스킬·무기 지연·버스트 게이지·기본 스펙
• context/: 게임 메커니즘 문서와 골든 스냅샷 회귀, doclint.py(문서↔코드 불일치 강제)
• worker/: 블라블라링크 조회 프록시 (Cloudflare Workers). nikke-api의 폴백으로만 씁니다
• worker-share/: 공유 코드·투표·피드백·레이드 중계 (Cloudflare Workers + KV + Durable Object)
• nikke_mcp/: AI 에이전트용 MCP 서버 — 로컬 stdio와 Render 공개 중계
• site/scripts/sync-runtime.mjs: 엔진, 데이터, 캐릭터 목록과 이미지를 웹 런타임으로 동기화
• .github/workflows/pages.yml: 테스트, 빌드, GitHub Pages 배포 자동화

주요 기능

• 캐릭터별 오버로드·하모니 큐브(17종)·소장품/애장품·스킬 레벨·한계돌파·컨트롤 개별 설정
• 계정 콘솔 설정 — 공통, 클래스 3종, 기업 5종을 소속별로 받아 스쿼드 전원에게 적용
• 5덱 모드와 덱 복사 — 한 덱의 편성과 설정을 다른 덱에 그대로 깔고 딜러만 바꿔 비교
• 캐릭터별 평타/스킬 딜 분해 — 기여도와 함께 일반 공격 대미지와 스킬 대미지 비율, 스킬별 딜·히트 수
• 프레임 단위 전투 타임라인 그래프
• 보고서 이미지 — 결과를 한 장짜리 PNG로 만들어 복사하거나 저장 (1덱은 세로 카드, 5덱은 합계와 25명 개별딜을 한 장에)
• 버스트 게이지 충전 시간 조절 — 게이지 누적 대신 쓰는 고정 시간을 직접 넣어 사이클을 조정
• 렛츠도로 CSV 불러오기와 블라블라링크 프로필 연동으로 실제 육성 상태 반영
• 스쿼드를 링크·코드로 공유, 편성 프리셋 저장, 덱끼리 순위 비교

모든 계산은 브라우저 안의 TypeScript 엔진(site/src/engine/)이 Web Worker에서 실행합니다. 선택 기능인 AI 연결을 켜면 육성·편성·계산 결과가 AI 서비스와 Render 중계 서버를 거칩니다. 결과 캐시는 해당 브라우저의 localStorage에 최대 30개까지 저장됩니다.

현재 선택 목록은 data/parsed_nikke.json과 data/parsed_skills.json 양쪽에 존재하는 실제 캐릭터만 포함합니다. test_ 데이터는 제외하며, 미리보기 캐릭터는 검증되지 않은 데이터라는 경고를 표시합니다. 현재 동기화 기준 지원 캐릭터는 202명입니다.

로컬 실행

Node.js 22 이상이 필요합니다(문서 검증 doclint에는 Python 3도 필요).

cd site
npm install
npm run dev

Vite가 표시한 로컬 주소의 /nikke-calc/ 경로로 접속하면 됩니다.

검증

cd site
npm test -- --run src/engine   # 엔진 단위 테스트
npx tsx scripts/snapshot.ts    # 골든 대미지 회귀
npm run check-pages            # Pages 워크플로 점검
npm run build                  # 타입체크 + 프로덕션 빌드
python -m context.doclint      # 문서↔코드·데이터 정합 (repo 루트에서)

데이터 갱신

엔진이나 데이터, 캐릭터 이미지가 변경되면 생성물을 직접 수정하지 말고 다음 명령으로 다시 동기화합니다.

cd site
npm run sync-runtime
npm run check-runtime

npm run dev와 npm run build도 실행 전에 자동으로 런타임을 동기화합니다.

배포

현재 프로덕션은 Vercel(https://nikke-calculator-xi.vercel.app/)입니다. 루트 vercel.json이 repo 전체를 받아 site/를 빌드하고 site/dist를 서빙합니다 — 빌드에 ../data가 필요해서 site/만 루트로 두는 배포는 실패합니다. Git 연결 배포는 커밋 작성자 이메일이 GitHub 계정과 일치해야만 허용되므로, 안 맞으면 로컬 vercel build --prod → vercel deploy --prebuilt --prod (저장소 밖 디렉터리에서)로 올립니다.

main 브랜치의 .github/workflows/pages.yml은 GitHub Pages 배포용으로도 준비돼 있습니다 — repo를 public으로 열고 Pages를 켜면 테스트·빌드·배포가 자동으로 돕니다. 경로·도메인은 저장소 변수 VITE_BASE(Pages는 /nikke-calculator/, Vercel은 /)와 SITE_ORIGIN으로 맞춥니다.

블라블라링크 연동 (선택)

프로필 URL로 육성 데이터를 받아 오는 기능은 중계 서버가 있어야 동작합니다 — 블라블라링크 API는 CORS를 열어 두지 않고 조회에 로그인 세션을 요구하므로, 정적 사이트가 직접 부를 수 없습니다.

이 저장소는 두 경로를 둡니다(site/src/blabla-source.ts).

1. nikke-api (기본) — VITE_NIKKE_API로 가리키는 니케 API의 GET /api/user/:blablaid/roster를 부릅니다. 변수를 비우면 기본 배포본 (nikke-api-gunwoos-projects.vercel.app)을 쓰고, 서버 측 자격증명으로 매 호출 세션을 새로 받으므로 쿠키 갱신이 필요 없습니다.
2. Cloudflare 프록시 (폴백) — nikke-api가 죽어 있을 때만 VITE_BLABLA_PROXY의 워커 /sync로 갑니다. 배포 절차는 worker/README.md에 있습니다. «비공개»나 «주소 오류»는 어느 경로로 물어도 같으므로 폴백하지 않습니다.

변수는 GitHub 저장소의 Actions → Variables와 Vercel 프로젝트 환경 변수에 넣습니다(site/.env.production 주석 참고). 둘 다 비우면 블라블라링크 연동 버튼을 아예 그리지 않고 렛츠도로 CSV만 남습니다. 워커 주소에는 Cloudflare 계정 이름이 들어가므로 저장소 파일에는 적지 않습니다.

공유 서버 (선택)

공유 코드·투표·피드백·유니온 레이드 보드는 worker-share/가 중계합니다 — npx wrangler deploy로 배포한 뒤 주소를 VITE_SHARE_API에 넣습니다(배포본: nikke-calc-share.leegunwoo0325-5e6.workers.dev). wrangler.toml의 ALLOWED_ORIGINS에 사이트 도메인이 있어야 합니다. 비우면 서버 탭을 그리지 않습니다.

라이선스

계산 엔진의 원본은 https://github.com/Jgaram/nikke-calc이며 MIT 라이선스로 공개돼 있습니다. 이 저장소는 그 포크이므로 같은 MIT 라이선스를 따르고, 원 저작권 고지를 LICENSE에 그대로 싣습니다.

Copyright (c) 2026 Jgaram
MIT License

고지

이 저장소와 서비스는 비공식 팬 도구이며 SHIFT UP 또는 Level Infinite와 제휴하거나 이들의 승인을 받은 서비스가 아닙니다. 『승리의 여신: NIKKE』의 게임 데이터·캐릭터·이미지 및 관련 저작물에 대한 권리는 SHIFT UP CORP. 및 Level Infinite에 있습니다. 위 라이선스는 계산기 코드에만 적용되며 게임 저작물에는 적용되지 않습니다. 공개 운영 전에는 사용 중인 자산과 데이터의 배포 권한을 별도로 확인하세요.

계산 결과는 참고용입니다 — 버그나 아직 확인되지 않은 게임 메커니즘이 남아 있을 수 있습니다.