Survirun Map

위치 기반 러닝 서바이벌 게임 프로토타입입니다. Next.js Pages Router 위에서 Mapbox GL 지도를 띄우고, Threebox로 3D 유저, NPC, 좀비, 클릭커 오브젝트를 배치합니다. 사용자의 GPS 이동을 추적해 캐릭터와 카메라를 갱신하고, 전투, 스토리, 퀘스트, 장비, 가방 UI를 매니저 클래스로 연결합니다.

주요 기능

• 현재 위치 기반 Mapbox 3D 지도 렌더링
• GPS 이동 감지, 이동 거리 누적, 지도 카메라 추적
• Threebox 기반 GLB/GLTF 3D 오브젝트 배치
• 유저, 좀비, 메인 스토리 NPC, 클릭커 생성 및 상호작용
• 좀비 접근/선택 시 전투 진입과 Android WebView 브리지 호출
• 스토리 진행, 퀘스트 수락/완료, 보상, 장비, 가방 UI
• 조리 게임용 냉장고/레시피북 프로토타입

기술 스택

• Next.js 14
• React 18
• Emotion
• Redux Toolkit, React Redux
• Mapbox GL JS
• Threebox
• Turf.js

실행 환경

• Node.js 18.x
• npm
• Mapbox public access token
• 위치 권한을 허용할 수 있는 브라우저

브라우저 위치 API는 localhost 또는 HTTPS 환경에서 정상 동작합니다. 메인 지도 화면은 위치 권한을 거부하면 시작되지 않습니다.

시작하기

의존성을 설치합니다.

npm install

프로젝트 루트에 .env.local 파일을 만들고 Mapbox 토큰을 설정합니다.

NEXT_PUBLIC_MAP_KEY=your_mapbox_public_token

개발 서버를 실행합니다.

npm run dev

브라우저에서 http://localhost:3000을 열고 위치 권한을 허용합니다.

npm scripts

명령어	설명
npm run dev	Next.js 개발 서버 실행
npm run build	프로덕션 빌드 생성
npm run start	빌드된 앱 실행
npm run lint	Next.js ESLint 실행

주요 라우트

경로	역할
/	메인 러닝/지도 게임 화면
/map	지도 기능을 단순화한 프로토타입 화면
/admin	스토리 데이터 편집 실험 화면
/cook-game/cookbook	레시피북 프로토타입
/cook-game/refrigerator	재료 보관소 프로토타입
/api/hello	기본 API Route 샘플
/test*, /index-*	개발 중 테스트/실험용 페이지

프로젝트 구조

src/
  pages/          Next.js 라우트와 메인 진입 페이지
  mannger/        지도 게임의 매니저 클래스 모음
  modules/        전투, 지도, 가방, 다이얼로그 등 기능 모듈
  components/     버튼, 텍스트, 인벤토리, 지도 등 공용 컴포넌트
  store/          Redux Toolkit 스토어
  slice/          Redux slice
  stores/         useSyncExternalStore 기반 커스텀 스토어 실험 코드
  hooks/          랜덤, 룰렛, 애니메이션, 버튼 딜레이 유틸
  json/           좀비, 장비, 방어구, 퀘스트, 스토리 데이터
  styles/         전역 CSS
  threebox/       Threebox Stats 유틸

public/
  3D/             GLB, GLTF, 텍스처 등 3D 리소스
  img/            UI 이미지 리소스

src/mannger 디렉터리명은 오타처럼 보이지만 기존 import 경로가 이 이름을 기준으로 연결되어 있으므로 변경 시 전체 import를 함께 수정해야 합니다.

메인 화면 동작 흐름

1. src/pages/_app.js에서 전역 CSS, Mapbox CSS, Redux Provider, Dialog Provider를 연결합니다.
2. src/pages/index.js의 RunningManager가 현재 GPS 좌표를 가져옵니다.
3. Mapbox 지도를 생성하고 Threebox 인스턴스를 초기화합니다.
4. UserManager, MainStoryNPCManager, ZombieManager, ClickerManager가 사용자 주변에 3D 오브젝트를 생성합니다.
5. watchPosition으로 위치 변화를 감지해 사용자 모델, 좀비 추적, 지도 카메라, 이동 거리를 갱신합니다.
6. UI 매니저가 사망, 아이템, 보상, 퀘스트, 스토리, 가방, 장비 화면을 렌더링합니다.

Android WebView 연동

일부 로직은 브라우저 전역 객체를 통해 Android 앱과 통신하도록 작성되어 있습니다.

• window.Android.initUserData(...)
• window.Android.distance(...)
• window.Android.startBattle(...)
• window.Android.userHPChange(...)
• window.Web.getEventFun
• window.Web.openRecipe, window.Web.addIngredients 등 조리 게임용 함수

일반 브라우저에서 실행하면 window.Android가 없어서 관련 호출이 try/catch로 무시되거나 콘솔에 기록될 수 있습니다.

개발 메모

• Mapbox 토큰은 클라이언트에서 사용하는 public token만 NEXT_PUBLIC_MAP_KEY에 넣습니다.
• 일부 오래된 프로토타입 파일에는 MAP_KEY 참조가 남아 있지만 현재 메인 화면은 NEXT_PUBLIC_MAP_KEY를 사용합니다.
• .env.local은 로컬 환경 파일이므로 커밋하지 않습니다.
• 3D 리소스 경로는 public 기준 상대 경로로 전달됩니다. 예: 3D/user.glb
• 메인 화면은 실제 GPS와 위치 권한에 의존하므로 데스크톱 테스트 시 브라우저 개발자 도구의 위치 센서 기능을 사용하면 편합니다.
• src/store/store.js는 현재 앱에서 사용하는 Redux 스토어이고, src/stores는 별도의 커스텀 스토어 실험 코드입니다.