🗺️ 현실 지도 기반 3D 게임 - 완전 가이드

📚 프로젝트 개요

Mapbox 실시간 지도를 기반으로 Three.js 3D 캐릭터가 도로를 따라 움직이는 네비게이션 스타일의 3D 게임입니다.

✨ 주요 특징

• ✅ Mapbox GL JS + Three.js 완전 통합
• ✅ GPS 기반 실시간 캐릭터 이동
• ✅ 네비게이션 카메라 (카카오맵/구글 네비 스타일)
• ✅ Mapbox Directions API 경로 계산
• ✅ 물리 엔진 기반 이동 (Rapier.js)
• ✅ glTF 애니메이션 시스템
• ✅ 모바일 최적화
• ✅ TypeScript + React 기반

---

🚀 빠른 시작

1️⃣ 설치

# 저장소 클론
git clone <repository-url>
cd mapbox-3d-game

# 의존성 설치
npm install

# 또는
yarn install

2️⃣ Mapbox Token 설정

# .env 파일 생성
cp .env.example .env

# .env 파일 편집
REACT_APP_MAPBOX_TOKEN=your_token_here

Mapbox Account에서 토큰을 발급받으세요.

3️⃣ 개발 서버 실행

npm run dev

브라우저에서 http://localhost:3000 접속

4️⃣ 빌드

npm run build
npm run preview

---

📁 프로젝트 구조

src/
├── core/                          # 핵심 엔진
│   ├── map/
│   │   └── MapboxManager.ts       # Mapbox 관리
│   ├── three/
│   │   └── ThreeManager.ts        # Three.js 렌더러
│   └── physics/
│       └── PhysicsManager.ts      # 물리 엔진
│
├── systems/                       # 게임 시스템
│   ├── camera/
│   │   └── CameraSystem.ts        # 네비게이션 카메라
│   ├── route/
│   │   └── RouteSystem.ts         # 경로 시스템
│   ├── player/
│   │   └── PlayerSystem.ts        # 캐릭터 시스템
│   └── animation/
│       └── AnimationSystem.ts     # 애니메이션
│
├── ui/                            # React 컴포넌트
│   ├── GameManager.tsx            # 메인 게임 루프
│   └── HUD.tsx                    # UI 요소
│
├── utils/                         # 유틸리티
│   ├── coordinates.ts             # 좌표 변환
│   ├── math.ts                    # 수학 함수
│   └── config.ts                  # 설정
│
├── types/
│   └── index.ts                   # TypeScript 인터페이스
│
└── main.tsx                       # Entry point

---

🎮 핵심 개념

1. 좌표 변환

• LngLat: [경도, 위도] - GPS 좌표
• Mercator: Mapbox 정규화 좌표 (0~1)
• World: Three.js 3D 좌표 (미터)

// 변환 예시
const lngLat: LngLat = [127.1086, 37.4050];
const coordinator = mapboxManager.getCoordinateConverter();
const worldPos: Vector3 = coordinator.lngLatToWorld(lngLat);

2. 게임 루프

requestAnimationFrame(gameLoop);

function gameLoop(time) {
  deltaTime = (time - lastTime) / 1000;
  
  // 1. GPS 입력
  playerSystem.update(gpsPosition, deltaTime);
  
  // 2. 물리 시뮬레이션
  physicsWorld.step(deltaTime);
  
  // 3. 카메라 업데이트
  cameraSystem.update(playerPos, playerHeading, deltaTime);
  
  // 4. 렌더링
  renderer.render(scene, camera);
}

3. 네비게이션 카메라

카메라는 항상 캐릭터 뒤에 위치하며 앞 도로를 바라봅니다:

카메라 위치 = 캐릭터 위치 + {
  x: -sin(heading) * distance (뒤쪽)
  y: height (위쪽)
  z: -cos(heading) * distance (뒤쪽)
}

LookAt 대상 = 캐릭터 위치 + {
  x: sin(heading) * lookahead (앞)
  y: 1.5 (눈 높이)
  z: cos(heading) * lookahead (앞)
}

---

🛠️ 사용 예시

경로 로드 및 시각화

const routeSystem = new RouteSystem(coordinator, mapboxToken);

// 경로 로드
const route = await routeSystem.loadRoute(
  [127.1086, 37.4050], // 시작
  [127.1100, 37.4040]  // 도착
);

// 3D 시각화
const routeMesh = routeSystem.visualizeRoute(route);
scene.add(routeMesh);

// 다음 웨이포인트 계산
const nextWaypoint = routeSystem.getNextWaypoint(
  playerWorldPos,
  route,
  10 // 10m 앞보기
);

캐릭터 로드 및 애니메이션

const playerSystem = new PlayerSystem(coordinator);

// 모델 로드
const characterModel = await playerSystem.initialize(
  'models/character.gltf'
);

// 게임 루프에서 업데이트
playerSystem.update(gpsPosition, deltaTime);

// 상태 확인
const state = playerSystem.getState();
console.log(state.animationState); // 'idle' | 'walk' | 'run'

카메라 제어

const camera = threeManager.getCamera();
const cameraSystem = new CameraSystem(camera);

// 게임 루프에서
cameraSystem.update(playerWorldPos, playerHeading, deltaTime);

// 카메라 설정 조정
cameraSystem.setCameraOffset({
  distance: 5.0,  // 더 멀리
  height: 2.5,    // 더 높이
  lookAheadDistance: 15.0 // 더 앞보기
});

---

📊 성능 최적화

모바일 최적화 활성화

import { getMobileOptimizedConfig } from './utils/config';

if (isMobileDevice()) {
  const config = getMobileOptimizedConfig();
  threeManager.initialize(container, config.render);
}

주요 최적화 전략

1. Frustum Culling: 화면 밖 오브젝트 렌더링 스킵
2. Instancing: 같은 형태 오브젝트 배치 렌더링
3. 물리 Tick 조절: 30fps로 물리 계산 (렌더는 60fps)
4. 좌표 캐싱: 반복 변환 캐시
5. 해상도 동적 조절: FPS에 따라 화면 해상도 조정

자세한 최적화 가이드는 OPTIMIZATION.md를 참고하세요.

---

🎬 실시간 GPS 통합

GPS 입력 예시

// 실제 GPS 데이터 사용
navigator.geolocation.watchPosition(position => {
  const {latitude, longitude} = position.coords;
  
  playerSystem.update([longitude, latitude], deltaTime);
  
  // 지도 중심 추적
  mapboxManager.setCenter([longitude, latitude], true);
});

Kalman Filter로 노이즈 제거 (권장)

class GPSFilter {
  private kalmanX = new KalmanFilter();
  private kalmanY = new KalmanFilter();
  
  filter(lngLat: LngLat): LngLat {
    return [
      this.kalmanX.update(lngLat[0]),
      this.kalmanY.update(lngLat[1])
    ];
  }
}

---

🐛 디버그 모드

// config.ts에서
export const DEBUG_CONFIG = {
  enabled: true,
  showCoordinateAxis: true,
  showCameraCone: true,
  showPhysicsDebug: true,
  showPathDebug: true,
  logPerformanceMetrics: true
};

성능 메트릭 확인

const fps = threeManager.getFPS();
console.log(`FPS: ${fps}`);

const cacheSize = coordinator.getCacheSize();
console.log(`좌표 캐시: ${cacheSize}`);

---

📱 모바일 지원

iOS/Android 호환성

<!-- index.html -->
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
<meta name="viewport" content="
  width=device-width,
  initial-scale=1.0,
  user-scalable=no,
  viewport-fit=cover
" />

터치 최적화

// Passive event listeners
container.addEventListener('touchmove', onTouchMove, {passive: true});

// 백그라운드 일시 중지
document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    stopGameLoop();
  } else {
    startGameLoop();
  }
});

---

🔧 API 문서

MapboxManager

class MapboxManager {
  initialize(container: HTMLElement): Promise<void>
  getCoordinateConverter(): CoordinateConverter
  getCenter(): LngLat
  setCenter(lngLat: LngLat, animate?: boolean): void
  setZoom(zoom: number, animate?: boolean): void
  dispose(): void
}

ThreeManager

class ThreeManager {
  initialize(container: HTMLElement): void
  getScene(): THREE.Scene
  getRenderer(): THREE.WebGLRenderer
  getCamera(): THREE.PerspectiveCamera
  render(): void
  getFPS(): number
  dispose(): void
}

PlayerSystem

class PlayerSystem {
  initialize(gltfPath: string): Promise<CharacterModel>
  update(gpsPosition: LngLat, deltaTime: number): void
  getState(): PlayerState
  getMesh(): THREE.Group | null
  getWorldPosition(): Vector3
  getHeading(): number
}

CameraSystem

class CameraSystem {
  update(playerPos: Vector3, playerHeading: number, deltaTime: number): void
  setCameraOffset(config: Partial<CameraConfig>): void
  getCamera(): THREE.PerspectiveCamera
}

RouteSystem

class RouteSystem {
  loadRoute(start: LngLat, end: LngLat): Promise<Route>
  visualizeRoute(route: Route): THREE.Mesh
  findClosestPointOnRoute(pos: Vector3, route: Route): {point, index}
  getNextWaypoint(pos: Vector3, route: Route, lookahead: number): Vector3
  isRouteComplete(pos: Vector3, route: Route): boolean
}

---

🌍 Mapbox Directions API

API 키 설정

# .env
VITE_MAPBOX_TOKEN=pk.eyJ1IjoieW91ciIsImEiOiJjbXBmNHpld...

경로 프로필

// 지원하는 프로필
'driving'      // 자동차
'walking'      // 보행자
'cycling'      // 자전거
'driving-traffic' // 교통 정보 포함

---

🎨 커스터마이징

캐릭터 모델 변경

const characterModelPath = 'models/my-character.gltf';
const gameManager = <GameManager
  characterModelPath={characterModelPath}
  // ...
/>;

지도 스타일 변경

const mapboxConfig = {
  ...DEFAULT_MAPBOX_CONFIG,
  style: 'mapbox://styles/mapbox/satellite-v9' // 위성지도
};

카메라 거리 조정

const DEFAULT_CAMERA_CONFIG = {
  distance: 6.0,  // 더 멀리 (기본: 4.0)
  height: 3.0,    // 더 높이 (기본: 2.0)
  lookAheadDistance: 20.0
};

---

📚 참고 문서

• 전체 설계 가이드
• 좌표 변환 공식
• 렌더링 방식 분석
• 최적화 전략
• Three.js 문서
• Mapbox GL JS 문서

---

🤝 기여하기

버그 리포트나 기능 제안은 Issue를 통해 제출해주세요.

---

📄 라이선스

MIT License

---

🎯 다음 단계

Phase 2 개선 사항

• NPC 시스템
• 지형 콜라이더
• 3D 음향
• 날씨 시스템
• 하루/밤 사이클

Phase 3 고급 기능

• 멀티플레이어 (WebSocket)
• 상점 시스템
• 미션/퀘스트
• 아이템 수집

---

💬 질문?

더 이상의 도움이 필요하면 GitHub Discussions에서 질문해주세요!

Happy Coding! 🚀