반응형 안전교육 게임 - Frontend

리액트 기반의 반응형 안전 교육 게임으로, 플레이어가 옳은 안전 운전 습관을 함양할 수 있는 교육적 시뮬레이션 앱입니다.

프로젝트 개요

이 프로젝트는 농촌 지역의 일상을 시뮬레이션하여 사용자가 농촌 운전 환경 중 발생할 수 있는 교통 안전적 위험 요소를 간접 체험하고, 이를 에방할 수 있도록 설계된 웹 애플리케이션입니다. 과수원 작업, 시내 병원 진료, 시장에서 장보기 등의 시나리오를 통해 여러 상황별 안전 요소를 확인할 수 있습니다.

기술 스택

핵심 기술

• React 19.1: 최신 리액트 버전을 활용한 컴포넌트 기반 아키텍처
• TypeScript: 타입 안전성과 개발 생산성 향상
• React Router DOM: SPA 라우팅 관리
• Tailwind CSS: 효율적인 스타일링

주요 라이브러리

• Framer Motion: 부드러운 애니메이션과 페이지 전환 효과
• Howler.js: 고품질 오디오 관리 (효과음, 배경음악)
• js-cookie: 클라이언트 측 쿠키 관리
• Axios: HTTP 클라이언트 (API 통신)

개발 도구

• Vite: 빠른 개발 서버와 빌드 도구
• ESLint: 코드 품질 유지
• PostCSS: CSS 처리 및 최적화

프로젝트 구조

src/
├── components/          # 재사용 가능한 컴포넌트
│   ├── layout/         # 레이아웃 컴포넌트
│   └── ui/             # UI 공통 컴포넌트
├── pages/              # 페이지 컴포넌트
│   ├── home/           # 홈 관련 페이지
│   ├── scenarioSelect/ # 시나리오 선택
│   ├── quest/          # 게임 퀘스트들
│   └── ResultScreen/   # 결과 화면들
├── context/            # React 컨텍스트 (상태 관리)
├── hooks/              # 커스텀 훅
├── services/           # API 통신 로직
├── utils/              # 유틸리티 함수들
└── types/              # 타입 정의

핵심 컴포넌트 구조

레이아웃 시스템

프로젝트는 세 가지 주요 레이아웃을 사용하여 게임의 흐름을 관리합니다:

• StartPrologueLayout: 시작 화면과 프롤로그에 사용되는 레이아웃
• QuestLayout: 실제 게임 퀘스트 진행 시 사용되는 레이아웃
• ResultLayout: 게임 결과 및 점수 화면용 레이아웃

핵심 페이지들

게임은 단계적으로 진행되며, 각 단계마다 특화된 페이지가 있습니다:

1. 홈 화면 (HomePage): 게임 시작점으로 지역 설정 상태를 표시하고 캐릭터 애니메이션을 포함
2. 시나리오 선택 (ScenarioSelectPage): 드래그 인터랙션을 통한 시나리오 선택
3. 캐릭터 선택 (CharacterSelectPage): 플레이어 캐릭터 선택
4. 프롤로그 (ProloguePage): 미션 소개와 게임 설명
5. 퀘스트 페이지들: 각 시나리오별 특화된 미니게임들
6. 결과 화면들: 점수, 교육 내용, 인증서 등

주요 기능

반응형 스케일링 시스템

useScale 훅을 통해 다양한 화면 크기에 대응하는 반응형 디자인을 구현했습니다. 모든 컴포넌트는 이 스케일 값을 기반으로 크기를 조정하여 일관된 사용자 경험을 제공합니다.

이미지 최적화 및 프리로딩

EnhancedOptimizedImage 컴포넌트를 통해 이미지 로딩을 최적화했습니다. 이 컴포넌트는 이미지 프리로딩, 에러 처리, 로딩 상태 관리를 자동으로 처리하여 부드러운 사용자 경험을 보장합니다.

오디오 관리 시스템

audioManager 유틸리티를 통해 게임 전반의 오디오를 통합 관리합니다. 배경음악, 효과음, 버튼 클릭 사운드 등을 일관성 있게 처리하며, 볼륨 조절과 음소거 기능도 포함되어 있습니다.

드래그 인터랙션

시나리오 선택 화면에서는 터치/마우스 드래그를 통한 직관적인 인터랙션을 제공합니다. 모바일과 데스크톱 환경 모두에서 자연스러운 조작감을 구현했습니다.

애니메이션 시스템

Framer Motion을 활용하여 페이지 전환, 캐릭터 애니메이션, UI 요소 등에 부드러운 애니메이션을 적용했습니다. 각 애니메이션은 스케일 값에 따라 조정되어 반응형으로 동작합니다.

게임 플로우

게임은 다음과 같은 순서로 진행됩니다:

1. 초기 설정: 홈 화면에서 지역 설정 및 게임 시작
2. 시나리오 선택: 드래그 인터랙션을 통한 시나리오 선택
3. 캐릭터 선택: 플레이어 아바타 선택
4. 프롤로그: 선택한 시나리오의 배경 스토리와 미션 설명
5. 퀘스트 수행: 시나리오별 특화된 미니게임들
   • 기억력 게임 (MemoryCardQuest)
   • 운전 시뮬레이션 (PotholeQuest)
   • 농촌 체험 (MakgeolliQuest, HarvestQuest)
6. 결과 확인: 점수, 교육 내용, 마을 랭킹 등

상태 관리

Context API 활용

CharacterProvider를 통해 전역 캐릭터 상태를 관리하며, 선택된 캐릭터 정보가 게임 전반에 걸쳐 유지됩니다.

로컬 스토리지 활용

게임 진행 상황, 지역 설정, 점수 등의 중요한 데이터는 localStorage에 저장되어 페이지 새로고침 후에도 유지됩니다.

성능 최적화

이미지 최적화

• 자동 이미지 프리로딩으로 로딩 시간 단축
• WebP 형식 지원으로 파일 크기 최적화
• 레이지 로딩을 통한 초기 로딩 성능 향상

번들 최적화

Vite의 코드 분할과 트리 쉐이킹을 활용하여 번들 크기를 최적화했습니다. 성능 모니터링 스크립트(scripts/performance-check.js)를 통해 번들 분석 가능합니다.

개발 환경 설정

필수 요구사항

• Node.js 18 이상
• npm 또는 yarn 패키지 매니저

설치 및 실행

# 의존성 설치
npm install

# 개발 서버 실행
npm run dev

# 프로덕션 빌드
npm run build

# 프로덕션 미리보기
npm run preview

# 번들 분석
npm run analyze

주요 스크립트

• npm run dev: Vite 개발 서버 실행 (http://localhost:5173)
• npm run build: 프로덕션 빌드 생성
• npm run lint: ESLint를 통한 코드 검사
• npm run analyze: 번들 크기 및 성능 분석

배포

프로젝트는 Vercel에 최적화되어 있으며, vercel.json 설정을 통해 SPA 라우팅과 에셋 캐싱이 구성되어 있습니다.

환경 변수

배포 시 다음 환경 변수들이 필요니다 !

• API 엔드포인트 URL
• 외부 서비스 연동을 위한 키값들

추가 정보

브라우저 호환성

• Chrome/Edge (권장)
• Firefox
• Safari (제한적 지원)
• 모바일 브라우저 최적화