🏁 Wiki Racing

나무위키 링크만으로 목표 문서까지 도달하는 새로운 방식의 위키레이싱 게임

📺 데모 영상

video2625274034.mp4

📌 영상 타임라인

0:00 - 0:07: 도전 모드 게임플레이 (매우 쉬운 난이도)
0:07 - 0:19: 게임 완료 후 리더보드에 닉네임 등록
0:19 - 0:30: 리더보드 경로 상세 분석 기능
0:30 - 0:50: 도전 모드 게임플레이 (브랜치 생성 및 경로 변경)
0:50 - 1:10: 리더보드 10위권 밖 + 멀티 브랜치 경로 확인
1:10 - 1:36: 역링크 비허용 모드 게임플레이

🎯 프로젝트 소개

Wiki Racing은 나무위키의 링크만을 이용하여 시작 문서에서 목표 문서까지 최단 경로로 도달하는 웹 기반 게임입니다. 전통적인 위키레이싱의 재미는 유지하면서, 직관적인 비주얼 인터페이스와 개선된 사용자 경험을 제공합니다.

⚠️ 현재 개발 단계: 나무위키 실시간 연동은 개발 중이며, 현재는 목업 데이터로 게임 메커니즘과 UI/UX를 구현한 상태입니다.

✨ 무엇이 특별한가요?

기존 위키레이싱은 위키 사이트를 직접 방문하며 진행하기 때문에:

📚 방대한 문서 내용 속에서 링크를 찾는 피로감
🗺️ 지나온 경로를 추적하기 어려움
🎲 최적 경로를 알 수 없음

Wiki Racing은 이러한 문제를 해결합니다:

🎨 시각화된 네트워크 인터페이스: n8n 스타일의 노드 기반 UI로 링크 관계를 직관적으로 표현
📊 경로 추적: 방문한 모든 문서의 경로를 실시간으로 기록
🏆 리더보드: 다른 플레이어와 경쟁하고 최적 경로 비교
🎮 접근성 개선: 고립 문서를 배제하여 모든 게임이 완료 가능

🎮 주요 기능

1️⃣ 게임 모드

연습 모드: 시작/종료 문서를 직접 선택 (리더보드 미등록)
도전 모드: 랜덤 배정 문서로 실력 테스트 및 리더보드 기록

2️⃣ Git 스타일 브랜치 시각화 🌳

수평 분기 레이아웃: Git 그래프와 유사한 브랜치 시각화
브랜치 포지셔닝 알고리즘: 재귀적 계산으로 같은 높이에서 수평 분기
히스토리 탐색: 이전 노드 클릭으로 새 브랜치 생성 및 경로 변경
경로 추적: pathRefs를 통한 정확한 브랜치/인덱스 추적

3️⃣ 노드 기반 트리 인터페이스

계층적 구조: 각 문서에서 연결된 링크들을 자식 노드로 표현
인터랙티브 선택: 노드 클릭으로 다음 문서 탐색
목표 노드 강조: 펄스 애니메이션과 발광 효과로 목표 문서 시각적 강조
경로 강조: 선택한 경로는 색상과 크기로 시각적 구분

4️⃣ 리더보드 시스템 🏆

영구 저장소: localStorage 기반 세션 간 데이터 유지
도전 모드 전용: 연습 모드는 기록 제외, 도전 모드만 리더보드 등록
자동 난이도 계산:
- 쉬움: 점수 ≥ 800 && 이동 횟수 ≤ 5
- 어려움: 점수 < 600 || 이동 횟수 ≥ 13
- 보통: 그 외
동적 메달 시스템: 신규 점수 추가 시 금/은/동 메달 자동 조정
경로 상세 분석:
- 지나간 모든 문서를 순서대로 시각화
- 브랜치 구조 포함 전체 경로 표시
- 총 이동 횟수, 실제 경로 길이, 평균 시간 계산
- 브랜치 전략 분석

5️⃣ 게임 옵션

역링크 허용 여부: 난이도 조절 옵션 (기본값: 허용)
점수 시스템: 난이도와 성과 기반 자동 계산
타이머: 실시간 소요 시간 측정

🎨 디자인 철학

깔끔한 사용자 경험

TailwindCSS: 모던하고 반응형 디자인
Skeleton UI: 로딩 상태의 자연스러운 표현
직관적 내비게이션: 최소한의 클릭으로 모든 기능 접근

시각화 레퍼런스

프로젝트는 n8n과 같은 워크플로우 시각화 도구에서 영감을 받았습니다:

노드 기반 인터페이스
계층적 정보 구조
인터랙티브한 요소 강조

🛠️ 기술 스택

Frontend

React + TypeScript: 타입 안전한 컴포넌트 기반 UI
TailwindCSS: 유틸리티 기반 반응형 스타일링
Zustand: 경량 상태 관리 라이브러리
Lucide React: 모던 아이콘 시스템

핵심 컴포넌트

WikiNodeTree: 노드 기반 트리 시각화 및 상호작용
PathHistory: Git 스타일 브랜치 히스토리
PathReplay: 경로 상세 분석 및 재현
Leaderboard: 영구 저장소 기반 랭킹 시스템

데이터 관리

localStorage: 세션 간 리더보드 데이터 영구 보존
JSON: 초기 리더보드 데이터 제공

알고리즘

재귀적 브랜치 포지셔닝: Git 그래프 스타일 레이아웃 계산
동적 난이도 계산: 점수 및 이동 횟수 기반 자동 분류
중복 방지 로직: useRef와 상태 비교를 통한 3중 검증

개발 예정

Node.js / Express: 나무위키 API 프록시 서버
Python: 나무위키 크롤링 및 데이터 파싱
Word2Vec: AI 기반 난이도 분석 (향후 확장)

🎯 핵심 가치

적절한 난이도의 재미
자동 난이도 계산으로 누구나 즐길 수 있는 게임 밸런스
경쟁의 재미
리더보드를 통한 실시간 랭킹과 다른 플레이어와의 경쟁
전략적 사고
브랜치 생성과 경로 변경을 통한 최적 경로 탐색
시각적 피드백
Git 스타일 브랜치 시각화로 복잡한 경로도 직관적으로 이해
접근성
위키레이싱 입문자도 쉽게 즐길 수 있는 친화적인 UI

💡 주요 구현 하이라이트

🌳 Git 스타일 브랜치 시각화

기존의 단순 시간순 나열이 아닌, Git 커밋 그래프와 같은 브랜치 구조로 경로를 시각화합니다.

핵심 알고리즘:

// 재귀적 브랜치 포지셔닝
function calculateBranchStartRow(
  branchIndex: number, 
  branches: PathBranch[]
): number {
  // 부모 브랜치의 분기 지점 찾기
  // 같은 높이에서 수평으로 분기
}

주요 특징:

이전 노드 클릭으로 새 브랜치 생성
pathRefs로 브랜치와 인덱스 정확히 추적
브랜치별 독립적인 경로 관리

🏆 지능형 리더보드 시스템

3중 중복 방지 메커니즘:

// 1. useRef로 저장된 엔트리 추적
const savedEntries = useRef<Set<string>>(new Set());

// 2. leaderboardData 중복 체크
const isDuplicate = leaderboardData.some(entry => 
  entry.playerName === name && entry.score === currentRun.score
);

// 3. entries 계산 시 중복 확인
const allEntries = [...leaderboardData, currentRun]
  .filter((entry, index, self) => 
    index === self.findIndex(e => e.id === entry.id)
  );

자동 난이도 분류:

쉬움: 800점 이상 & 5회 이하 이동
보통: 중간 범위
어려움: 600점 미만 또는 13회 이상 이동

📊 경로 상세 분석

각 플레이어의 전략을 시각적으로 분석합니다:

경로 재현: 실제 게임 플레이처럼 브랜치 구조 표시
문서 리스트: 방문한 모든 문서를 순서대로 나열
통계 분석: 총 이동 횟수, 실제 경로 길이, 평균 시간
전략 유형: 브랜치 사용 여부에 따른 전략 분류

🎨 UX 강화 요소

목표 노드 펄스 애니메이션:

@keyframes pulse-scale {
  0%, 100% { transform: scale(1.0); }
  50% { transform: scale(1.1); }
}

2초 주기 스케일 애니메이션
발광 그림자 효과로 시선 집중

오버플로우 관리:

PathReplay 모달 500px 고정 높이
수평/수직 스크롤로 긴 경로 처리

📁 프로젝트 구조

src/
├── components/
│   ├── GameHeader.tsx          # 게임 헤더 (타이머, 목표, 히스토리)
│   ├── WikiNodeTree.tsx        # 노드 트리 시각화
│   ├── PathHistory.tsx         # Git 스타일 브랜치 히스토리
│   ├── PathReplay.tsx          # 경로 상세 분석 및 재현
│   ├── Leaderboard.tsx         # 리더보드 시스템
│   ├── NameInputModal.tsx      # 닉네임 입력 모달
│   └── WikiRaceGame.tsx        # 메인 게임 로직
├── data/
│   └── leaderboard.json        # 초기 리더보드 데이터
├── types/
│   └── wikirace.ts            # TypeScript 타입 정의
└── gameStore.ts               # Zustand 상태 관리

주요 컴포넌트:
- 10개 파일, 1,100+ 줄 변경
- TypeScript 타입 안전성
- 모듈화된 컴포넌트 구조

🎮 게임 스크린샷

시작 화면

게임 모드 선택 (연습/도전)과 역링크 옵션 설정

게임 진행 화면

노드 기반 트리 인터페이스로 링크 탐색

Git 스타일 히스토리

수평 분기 레이아웃으로 모든 시도 추적

리더보드

TOP 10 랭킹과 동적 메달 시스템

경로 상세 분석

브랜치 구조 재현 및 전략 분석

🚀 시작하기

설치 방법

# 레포지토리 클론
git clone https://github.com/boostcampwm-snu-2025/Wiki_Racing-dev-pyun.git
cd Wiki_Racing-dev-pyun

# 의존성 설치
npm install

# 개발 서버 실행
npm run dev

환경 설정

.env 파일을 생성하고 필요한 환경 변수를 설정하세요:

# API 설정
API_URL=your_api_url
PORT=3000

# 데이터베이스
DB_HOST=localhost
DB_PORT=5432

📖 사용 방법

1. 게임 시작

메인 페이지에서 연습 모드 또는 도전 모드 선택
- 연습 모드: 자유롭게 연습 (리더보드 미등록)
- 도전 모드: 랭킹 등록 가능
역링크 허용 여부 설정

2. 게임 진행

시작 문서에서 연결된 링크들이 노드로 표시됨
목표 문서에 가까울 것 같은 링크를 선택
선택한 문서에서 다시 링크 탐색 반복

3. 경로 전략

브랜치 생성: "목록보기"에서 이전 노드 클릭
경로 변경: 새로운 브랜치에서 다른 경로 시도
최적화: 여러 경로를 시도하여 최단 경로 발견

4. 목표 달성

목표 문서(펄스 애니메이션)에 도달하면 게임 종료
소요 시간과 이동 횟수 확인
도전 모드: 10위 안에 들면 닉네임 입력

5. 리더보드

경로 보기: 상위 랭커들의 전략 분석
- Git 스타일 브랜치 구조
- 방문한 모든 문서 리스트
- 통계 및 전략 유형
자신의 기록: 10위권 밖이라도 하단에 본인 기록 표시

🎨 주요 화면

시작 화면

게임 모드 선택과 옵션 설정

게임 진행 화면

노드 기반 인터페이스로 링크 탐색

리더보드

TOP 10 랭킹과 경로 비교

🌟 해결한 Pain Points

문제점과 해결책

문제점	해결 방법
❌ 방문 경로 추적 어려움	✅ Git 스타일 브랜치 시각화로 모든 경로 추적
❌ 경로 변경 시 이전 기록 소실	✅ 브랜치 시스템으로 모든 시도 보존
❌ 다른 플레이어 경로 확인 불가	✅ 리더보드 경로 재현 기능
❌ 리더보드 중복 등재	✅ 3중 검증 시스템으로 완벽 방지
❌ 난이도 예측 불가	✅ 자동 난이도 계산 및 표시
❌ 모달 오버플로우	✅ 고정 높이 + 스크롤 처리

기술적 도전 과제

1. 리더보드 중복 등재 버그

// 문제: entries 계산 시 currentRun 포함
// → useEffect에서 leaderboardData에 추가
// → 재렌더링 시 currentRun + leaderboardData(이미 추가됨) 
// → 중복 발생

// 해결: 3중 검증
- useRef로 이미 저장된 항목 추적
- leaderboardData 중복 체크
- entries 필터링 시 ID 기반 중복 제거

2. 브랜치 경로 정보 손실

// 문제: leaderboardEntry에 branches와 pathRefs 미포함
// → 리더보드에서 브랜치 구조가 직선으로 표시

// 해결: 완전한 게임 상태 저장
const leaderboardEntry = {
  ...기본정보,
  branches: gameState.branches,      // 추가
  pathRefs: gameState.pathRefs,      // 추가
  currentBranch: gameState.currentBranch
};

3. 경로 분석 하드코딩

// 문제: PathReplay의 분석 내용이 고정된 텍스트

// 해결: 동적 계산
- 실제 방문한 문서 리스트 추출
- 브랜치 구조 분석
- 통계 자동 계산

⚡ 성능 및 최적화

알고리즘 복잡도

브랜치 포지셔닝: O(n) - 재귀적 계산
중복 제거: O(n) - Set 기반 검증
난이도 계산: O(1) - 단순 조건 분기

상태 관리

Zustand: Redux보다 가벼운 상태 관리
localStorage: 비동기 작업 최소화
useRef: 불필요한 리렌더링 방지

타입 안정성

interface LeaderboardEntry {
  id: string;
  playerName: string;
  score: number;
  moves: number;
  time: string;
  difficulty: 'easy' | 'medium' | 'hard';
  branches: PathBranch[];      // 브랜치 구조
  pathRefs: PathRef[];         // 경로 참조
  currentBranch: number;       // 현재 브랜치
}

코드 품질

✅ TypeScript strict mode
✅ 컴포넌트 모듈화
✅ 재사용 가능한 유틸리티 함수
✅ 일관된 코딩 스타일

🐛 알려진 이슈

현재 제한사항

⚠️ 나무위키 연동: 실시간 크롤링 미구현 (목업 데이터 사용)
⚠️ AI 난이도 분석: Word2Vec 모델 개발 중
⚠️ 브랜치 병합: Merge 기능 미구현

해결된 버그

✅ 리더보드 중복 등재 (v1.0)
✅ 브랜치 경로 정보 손실 (v1.0)
✅ 경로 분석 하드코딩 (v1.0)
✅ 모달 오버플로우 (v1.0)

🗺️ 로드맵

Phase 1: 핵심 기능 (완료) ✅

게임 메커니즘 구현
브랜치 시각화
리더보드 시스템
경로 분석

Phase 2: 데이터 연동 (진행 중) 🔄

나무위키 API 프록시
실시간 문서 크롤링
링크 파싱 및 필터링
고립 문서 감지

Phase 3: AI 기능 (계획) 📋

Word2Vec 난이도 분석
AI 최적 경로 탐색
역링크 가중치 조정
동적 난이도 계산

Phase 4: 소셜 기능 (계획) 📋

경로 비교 기능
소셜 공유
친구 대결 모드
주간 챌린지

📝 개발 히스토리

프로젝트의 상세한 개발 과정과 설계 결정은 Wiki에서 확인할 수 있습니다.

완료된 기능 ✅

✅ 프로젝트 기획 및 디자인
✅ Git 스타일 브랜치 시각화 시스템
✅ 노드 기반 트리 인터페이스
✅ 리더보드 시스템 (영구 저장소)
✅ 경로 상세 분석 및 재현
✅ 자동 난이도 계산
✅ 목표 노드 펄스 애니메이션
✅ 도전/연습 모드 구분
✅ 역링크 허용 옵션

개발 중 🔄

🔄 나무위키 실시간 연동
🔄 AI 기반 최적 경로 탐색
🔄 Word2Vec 난이도 분석 모델

향후 계획 📋

📋 브랜치 병합(merge) 기능
📋 리더보드 페이지네이션
📋 경로 비교 기능
📋 소셜 공유 기능
📋 역링크에 따른 동적 난이도 조정

주요 버그 수정

버그	해결 날짜	설명
리더보드 중복 등재	2024.12	3중 검증 시스템 구현
브랜치 경로 손실	2024.12	완전한 게임 상태 저장
경로 분석 하드코딩	2024.12	동적 계산 로직 구현
모달 오버플로우	2024.12	고정 높이 + 스크롤

👨‍💻 개발자

PYUN Chaebeom (@dev-pyun)

개인 프로젝트: Wiki Racing

🔧 기술적 도전

이 프로젝트를 통해 다음을 학습하고 구현했습니다:

Git 스타일 브랜치 시각화 알고리즘
React 상태 관리 최적화
중복 방지 메커니즘
localStorage 기반 영구 저장소
TypeScript 타입 안전성

📚 기술 블로그

개발 과정과 기술적 도전 과제는 프로젝트 Wiki와 Pull Requests에서 확인할 수 있습니다.

주요 PR:

🎮 게임 기능 개선 및 버그 수정 - 브랜치 시각화, 리더보드, 경로 분석

🙏 감사의 말

위키레이싱 게임 아이디어 제공: 나무위키, Wikipedia
시각화 영감: n8n, Git Graph
부스트캠프 멘토 및 피어 여러분의 피드백
React + TypeScript 커뮤니티

❓ FAQ

Q1. 나무위키 실시간 연동은 언제 완료되나요?

현재 게임 메커니즘과 UI/UX 구현이 완료되었으며, 나무위키 API 연동은 다음 단계로 계획되어 있습니다.

Q2. 왜 목업 데이터를 사용하나요?

게임의 핵심 기능(브랜치 시각화, 리더보드, 경로 분석)을 먼저 완성한 후, 실제 데이터 연동을 진행하는 것이 효율적이기 때문입니다.

Q3. 연습 모드와 도전 모드의 차이는?

연습 모드: 자유롭게 연습, 리더보드 미등록
도전 모드: 랜덤 문서, 리더보드 등록 가능

Q4. 브랜치는 어떻게 생성하나요?

"목록보기"에서 이전에 방문한 노드를 클릭하면 새로운 브랜치가 생성됩니다.

Q5. 점수는 어떻게 계산되나요?

점수 = (기본점수 - 이동횟수 * 페널티) + 시간보너스 형태로 계산되며, 적은 이동과 빠른 시간이 유리합니다.

Q6. 리더보드 데이터는 어디에 저장되나요?

브라우저의 localStorage에 저장되어 세션이 종료되어도 유지됩니다.

📞 문의

프로젝트에 대한 질문이나 제안사항이 있으시다면:

📧 Email: 이메일
💬 Issues: GitHub Issues

🎮 즐거운 위키레이싱 되세요! 🎮

⬆ Back to top

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
backup		backup
public		public
src		src
.gitignore		.gitignore
README.md		README.md
README2.md		README2.md
UI-IMPROVEMENT-GUIDELINES-old.md		UI-IMPROVEMENT-GUIDELINES-old.md
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.d.ts		vite.config.d.ts
vite.config.js		vite.config.js
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

🏁 Wiki Racing

📺 데모 영상

📌 영상 타임라인

🎯 프로젝트 소개

✨ 무엇이 특별한가요?

🎮 주요 기능

1️⃣ 게임 모드

2️⃣ Git 스타일 브랜치 시각화 🌳

3️⃣ 노드 기반 트리 인터페이스

4️⃣ 리더보드 시스템 🏆

5️⃣ 게임 옵션

🎨 디자인 철학

깔끔한 사용자 경험

시각화 레퍼런스

🛠️ 기술 스택

Frontend

핵심 컴포넌트

데이터 관리

알고리즘

개발 예정

🎯 핵심 가치

💡 주요 구현 하이라이트

🌳 Git 스타일 브랜치 시각화

🏆 지능형 리더보드 시스템

📊 경로 상세 분석

🎨 UX 강화 요소

📁 프로젝트 구조

🎮 게임 스크린샷

시작 화면

게임 진행 화면

Git 스타일 히스토리

리더보드

경로 상세 분석

🚀 시작하기

설치 방법

환경 설정

📖 사용 방법

1. 게임 시작

2. 게임 진행

3. 경로 전략

4. 목표 달성

5. 리더보드

🎨 주요 화면

시작 화면

게임 진행 화면

리더보드

🌟 해결한 Pain Points

문제점과 해결책

기술적 도전 과제

⚡ 성능 및 최적화

알고리즘 복잡도

상태 관리

타입 안정성

코드 품질

🐛 알려진 이슈

현재 제한사항

해결된 버그

🗺️ 로드맵

Phase 1: 핵심 기능 (완료) ✅

Phase 2: 데이터 연동 (진행 중) 🔄

Phase 3: AI 기능 (계획) 📋

Phase 4: 소셜 기능 (계획) 📋

📝 개발 히스토리

완료된 기능 ✅

개발 중 🔄

향후 계획 📋

주요 버그 수정

👨‍💻 개발자

🔧 기술적 도전

📚 기술 블로그

🙏 감사의 말

❓ FAQ

Q1. 나무위키 실시간 연동은 언제 완료되나요?

Q2. 왜 목업 데이터를 사용하나요?

Q3. 연습 모드와 도전 모드의 차이는?

Q4. 브랜치는 어떻게 생성하나요?

Packages